This HTML automatically generated with rman for NEMO
Table of Contents
newton0, newton0tree, newton0reg - nbody codes with equal time steps
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]
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).
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).
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.
mkplummer(1NEMO)
, nbody0(1NEMO)
STARLAB: http://www.sns.ias.edu/~starlab/
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.
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...
Piet Hut
NEMO/src/nbody/evolve/newton0 source code
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