This HTML automatically generated with rman for NEMO
Table of Contents

Name

newton0, newton0tree, newton0reg - nbody codes with equal time steps

Synopsis

newton0 [in=infile] [lastout=lastoutfile] [out=outfile] [save=savefile] [restore=restorefile] [resume=resumefile] [restart=restartfile] [nbody=integer] [seed=integer] [t_begin=real] [t_end=real] [dt_minor=real] [dt_major=real] [dt_save=real] [dt_max=real] [nstep=integer] [min_pairdist=real] [de_max=real] [nstep_de=integer] [cpu_max=real] [cpu_last_call=real] [eta_acc=real] [r0_soft=real] [soft_focus=softeningtype] [timestep=timestepcriterion] [diagnostics=diagnosticstype] [scheme=integrationscheme] [headline=string]

newton0tree [...same as in newton0...] [tol=real] [celldivision=celldivisionmethod]

newton0reg [...same as in newton0...] [niter=integer]

Description

newton0 is a simple type of gravitational many-body code: simple in the sense of giving all particles equal time steps at any given time (although the length of this shared time step does change in time in an adaptive fashion; see below). Apart from this limitation the code is rather flexible: it gives a choice of a number of integration schemes which can be invoked on the command line; a choice of various softening procedures; a choice of time step criterion; a choice of diagnostics provided during the run; and it has a wide choice of start-up options, from a snapshot, or a previously saved system state, or from scratch in which case newton0 produces a Plummer model.

newton0tree is an extension to newton0 in which a hierarchical force calculation is performed using an adaptive Eulerian tree scheme (J. Barnes and P. Hut 1986, Nature 324, 446), which reduces the number of pairwise force calculations per timestep from order #N sup 2# to order #N log N# .

newton0reg is an extension to newton0 in which a full pairwise regularization scheme is implemented, based on the Kustaanheimo_Stiefel four-dimensional regularization, as generalized by D.C. Heggie, Celestial Mechanics 10, 217 (1974); and implemented following the recipes given by S. Mikkola, Mon. Not. R. astr. Soc. 215, 171 (1985). The order of the system of equations is raised from the usual #6 N# to #4N(N-1)+1#.

The code has been written in a highly structured, modular and flexible way (see the Newton0 Primer). It can thus serve as a blueprint for more advanced gravitational many-body integration modules. Its generality makes it suitable for experimentation with different integration, softening, timestep and diagnostics schemes. When using newton0 in production runs it may be advisable to throw out some of the unneeded embellishments, and to optimize the inner loops -- but remember: premature optimization is the root of all evil (or at least of most).

Parameters

The following parameters are recognized in order; they may be given in any order if the keyword is also given. Use --help to confirm this man page is up to date.
in=infile
If infile is specified, a nbody snapshot is read in from this file (a quick way of preparing a simple system for testing purposes is to use snapenter(1NEMO) ). The command line parameters are used to determine the type and duration of the integration, and the modes of output. Only one of the files inputfile, restorefile, resumefile may be specified: if none are specified, a new Plummer model is generated (Default: no file specification).
lastout=lastoutfile
If lastoutfile is specified, then output data are written into this file in standard snapshot format at the end of the integration. Since only one output is performed, the integration can be viewed as a black box which maps an in-state to an out-state without any clutter of intermediate information. This option is useful for testing purposes, since the lastoutfiles of two different runs can be compared directly, for example using snapdiff(1NEMO) ; using snapdiff on two outfiles would only compare the echos of the initial states, and later states would have to be extracted using snaptrim(1NEMO) before passing them to snapdiff(1NEMO) (Default: no file specification).
out=outfile
If outfile is specified, then output data are written into this file in standard snapshot format, at time intervals regulated by dt_min_out and dt_maj_out (see below; Default: no file specification).
save=savefile
If savefile is specified, the whole system state is saved periodically at time intervals dt_save. (Default: no file specification).
restore=restorefile
If restorefile is specified, a previously saved system state is read in from this file. The command line parameters are ignored (in contrast to the following option below), and the system is run to completion solely according to the information contained in restorefile. Thus, unless restorefile contains an interrupted run, no integration will take place since t_end will already have been reached. Only one of the files inputfile, restorefile, resumefile may be specified: if none are specified, a new Plummer model is generated (Default: no file specification).
resume=resumefile
If resumefile is specified, a previously saved system state is read in from this file. The command line parameters are used (in contrast to the previous option above) to determine the type and duration of the integration, and the modes of output. Only one of the files inputfile, restorefile, resumefile may be specified: if none are specified, a new Plummer model is generated (Default: no file specification).
restart=restartfile
If restartfile is specified, newton0 will deposit into this file a command which will continue the present run after a systemcrash as if nothing had happened. Specifying a restartfile will be ignored if no savefile is specified as well. If both files are given, then the system is supposed to execute the restartfile automatically at reboot time (through some sort of specification in some sort of system file), and all will be well again, one hopes (Default: no file specification).
nbody=integer
number of particles in a newly generated Plummer model (Default: nbody=3).
seed=integer
seed for the random number generator used in generating a new Plummer model (default: a value 0, which will be converted into a unique new value using UNIX’s clock time, in seconds since once-upon-a-time-in-the-seventies-of-the-previous-century). See also xrandom(1NEMO) for more info on seed=
t_begin=real
time at which the integration starts (Default: t_begin=0.0).
t_end=real
time at which the integration will halt (Default: t_end=1.0).
dt_minor=real
time intervals between minor outputs, when diagnostics are printed on the standard output channel and diagnostics are added to outfile in snapshot format (Default: dt_minor=0.5).
dt_major=real
time intervals between major outputs, when diagnostics are printed on the standard output channel and diagnostics as well as a complete set of particle data are added to outfile in snapshot format (Default: dt_major=1.0).
dt_save=real
time intervals between saving a complete system state (Default: dt_save=0.5).
dt_max=real
maximum length of the allowed integration time step which is shared between all particles (Default: dt_max=1000).
nstep=integer
maximum number of integration steps, after which execution of the program is halted immediately (Default: nstep=10000000).
min_pairdist=real
minimum allowed (softened) pair distance. If any pair of particles anywhere in the system attains a (softened) separation smaller than min_pairdist integration is halted. Note: when using softening, the pair distance measured is the softened distance between two particles. Specifying a minimum allowed pair distance smaller than the effective softening length therefore cannot halt integration (Default: min_pairdist=0.0).
de_max=real
maximum amount of drift allowed in the total energy of the system. If the total energy changes by more than this amount, integration is halted. The frequency with which this test is applied is governed by the parameter nstep_de as described below (Default: de_max=10000000).
nstep_de=integer
indicates the number of time steps after which the total energy value is checked against de_macs. (Default: nstep_de=10000000).
cpu_max=real
maximum amount of CPU time allowed (expressed in minutes), after which execution of the program is halted immediately (Default: cpu_max=10000000).
cpu_last_call=real
soft limit on the amount of CPU time used (expressed in minutes): after this amount has been exceeded, execution of the program will be halted at the time of the next major output. This allows a more graceful exit than the above hard option of cpu_max. Notice, however, that it may be prudent to give suitable limits for both these parameters, since an extreme condition such as a very close encounter may slow down simulated time to such an extent that the time of the next scheduled major output may "never" be reached (Default: cpu_last_call=10000000).
eta_acc=real
dimensionless integration accuracy parameter, used in determining the size of the integration time step: the step length is taken as the small fraction eta_acc of the projected collision time. The latter is defined as follows: the relative distance and speed in each particle pair is determined, and from these the time scale of change defined as the ratio of the relative speed and the relative distance; the minimum of all these time scales is the projected collision time (Default: eta_acc=0.01).
r0_soft=real
softening length used to soften the potential of a point mass according to the type of softening specified by soft_focus (see below; Default: r0_soft=0.0).
soft_focus=softeningtype
type of softening used to soften the potential of a point mass. The following options are implemented: plummer specifies the traditional softening in which each point particle assumes the potential of a density distribution according to a small Plummer model; power4 is a generalization of the previous one in which the square of the softening length is replaced by the fourth power, giving a shorter range for the softening; power8 is a similar generalization to the eight power; exponential is again similar, but has an exponentially short range; sphere replaces each point particle by a homogeneous sphere; shell replaces each point particle by a homogeneous shell; spline replaces each point particle by a cubic spline with compact support (Default: soft_focus=plummer).
timestep=timestepcriterion
criterion for determinening the next timestep. Currently only two criteria are provided: constant implies a constant time step equal to the value of eta_acc; and collision_time which adaptively determines the timestep as the fraction eta_acc of the timescale on which the first pair configuration changes significantly. Expressed more accurately: the relative distance and speed in each particle pair is determined, and from these the time scale of change which would be the time scale for a collision if position and velocity would be parallel and opposite; hence the name (Default: timestep=constant).
diagnostics=diagnosticstype
choice of diagnostics output, in binary as well as in ascii. This will be a place where a large variety of types of diagnostics can be offered in future versions. Presently only one type is implemented (Default: diagnostics=standard).
scheme=integrationscheme
integration scheme used to integration Newton’s equations of motion for the whole system state (modeled as a set of 2*nbody*NDIM simultaneous nonlinear ordinary differential equations). The following options are implemented: forward_euler, backward_euler, runge_kutta_2, runge_kutta_4, runge_kutta_6, rk_fehlberg_45. The first two are forward Euler and backwards Euler schemes, respectively; the next three are Runge-Kutta schemes of 2nd, 4th and 6th order, respectively; and the last one is a Runge-kutta-Fehlberg scheme of combined 4th and 5th order (the present implementation uses only the final, 5th order Runge-Kutta information of this last scheme) (Default: scheme=runge_kutta_4 for NEWTON0 and NEWTON0REG; scheme=leapfrog for NEWTON0TREE).
headline=string
Optional headline, which is written as the first item in the snapshot file, the next item being the snapshot itself (Default for NEWTON0: "Newton0code: equal time steps"; for NEWTON0REG: "Newton0 code: equal time steps & regularization"; for NEWTON0TREE: "Newton0 code: equal time steps & hierarchical tree forces").
tol=real
ONLY for NEWTON0TREE: the tolerance parameter, which determines which cells are subdivided: for example, in the simplest celldivisonmethod (see below), whenever the ratio of cell size over cell distance to a body is smaller than tol, the interaction between the cell and the body is computed directly without further subdivision (Default: tol=1.0).
celldivision=celldivisonmethod
ONLY for NEWTON0TREE: the method used to decide when to subdivide a cell from which one wants to compute the gravitational attraction on an individual particle. The simplest method, constant_theta, applies a constant opening-angle criterion (Default: celldivision=constant_theta).
niter=integer
ONLY for NEWTON0REG: number of iterations performed in trying to arrive at the correct time to end the integration (since integration is with respect to pseudo-time, the end of an integration time step can only be predicted roughly with respect to real time; iterating with increasing smaller timestep helps to zoom in on the correct end-time; Default: niter=3).

Examples

Here is an example of integrating a 10 body Plummer sphere, with and without regularization: $ mkplummer p10 10 seed=123

$ newton0 p10 out=p10.out t_end=100 dt_major=0.1
t_now T+U T/U (E-E0)/E0 dE/E0 nsteps pair_min cputime
0.000 -0.1670 -0.4984 -0 -0 0 0.35 0
0.100 -0.1670 -0.5041 -1.8e-10 -1.8e-10 10 0.33 0
...
1.000 -0.1670 -0.5909 2e-10 -1.1e-09 100 0.23 0
10.000 15.3983-122.1181 -93 1.3e-10 1000 0.0059 0.00033
100.000 16.7514-716.4978 -1e+02 0 10000 0.0059 0.0035

$ newton0reg p10 out=p10reg.out t_end=100 dt_major=0.1
t_now T+U T/U (E-E0)/E0 dE/E0 nsteps pair_min cputime
0.000 -0.1670 -0.4984 -0 -0 0 0.35 0
0.100 -0.1670 -0.5041 -5.3e-10 -5.3e-10 10 0.33 0
1.000 -0.1670 -0.5909 -1.9e-09 -1.9e-09 101 0.23 0.0005
10.000 -0.1668 -0.5254 -0.0011 0.00014 958 0.0031 0.0055
100.000 -0.0869 -0.7171 -0.48 0.3 9619 0.0027 0.056

Although energy conservation is not great at all in the regularized version, it behaves much better than the vanilla version of newton0.

See Also

mkplummer(1NEMO) , nbody0(1NEMO)

STARLAB: http://www.sns.ias.edu/~starlab/

Caveats

newton0 has not been maintained for a long time, the code was revived in 2001 as version 2.0, but for any serious research codes such as the nbodyX series written by S.Aarseth (see e.g. nbody0(1NEMO) ) or the starlab package should probably be used.

Bugs

Running the code with a file named savefile lying around tricks poor newton0 into assuming that it has just been restored to the land of the living and that it should resume the task of its previous reincarnation left undone according to the contents of savefile. Another bug: if intended to be restored automatically this way, simply reissuing the original command will revive the last saved system as advertised, but only after removing (or better: renaming) the old outfile, since newton0 is civilized enough to refuse to overwrite the contents of the old outfile. One can then manually concatenate the new and old outfile after completion of the run.

The Newton0 Primer is lost...

Author

Piet Hut

Files


NEMO/src/nbody/evolve/newton0    source code

History


25-May-87    Version 1.0: created             PIET
5-feb-01    V2.0: converted for NEMO V3    PJT
20-feb-04    2.0a: integrated in NEMO V3, fixed an I/O problem    PJT
26-dec-2023    add EXAMPLE    PJT