Table of Contents
gyrfalcON - a superberb N-body code (public version)
requires NEMO version 3.2.1 or higher, see
It is recommended to configure NEMO with configure
gyrfalcON stands for "GalaxY simulatoR
using falcON". It is a full-fledged N-body code using Walter Dehnen’s force
algorithm of complexity O(N) (falcON), which is about 10 times faster than
an optimally coded tree code. gyrfalcON features individual adaptive time
steps and individual (but fixed) softening lengths.
- Input data is read from file, which must be in NEMO snapshot
format. If file=-, input is expected from stdin, useful for piping data
from another program. Default: required.
- Unless resume=t (see below),
primary output is written to file in NEMO snapshot format. If file=-, output
is written to stdout; If file=., no output is made. Default: required unless
- Specifies which data are given with primary data
output. IOstring must be an unbroken string of characters, each of which
indicates a datum (per body) to be written. The meanings are as follows.
m=mass, x=position, v=velocity, p=N-body potential, q=external potential
(to be added to the N-body potential), a=acceleration, e=individual softening
lengths, and l=time-step levels. Default: mxv.
- Primary data output
is made every val simulation time units. If val=0 output is made every blockstep.
- Write primary output at the initial simulation time.
- Write primary output at the last simulation time,
even if not at an ordinary output step. Default: t.
- If given, secondary
output is written to file in NEMO snapshot format. If file=-, output is written
to stdout; If file=., no secondary output is made. No default.
- Specifies which data are given with primary data output; same format as
for give. Default: mxv.
- Scondary data output is made every val
simulation time units. If val=0, output is made every blockstep. Useful for
piping results to an analysing programm. Default: mxv.
- Log output
(time, total energy, angular momentum, CPU time consumption etc) is written
to file. If file=-, log output is made to stdout. Default: -.
output is made every num blocksteps. Default 1.
- Resume an old simulation:
input is read from the last snapshot in the input file; primary data output
is appended to the same file (out is ignored). Default: f.
- The simulation shall be halted at simulation
time=val. By default, the simulation will not be stopped at a pre-defined
time, see also stopfile. If val equals the initial simulation time, the
initial forces are computed and, if so desired, output is made for this
time only. No Default.
- If given, the code stops as soon as
file is found to exist. If lastout=t, a final output is made. This mechanism
allows a controlled end of a simulation: an analyzing tool, which obtains
the simulation data via the pipe from gyrfalcON may find that a pre-set condition
for ending the simulation is satisfied and create a stopfile. No Default.
- The longest time step is taken to be tau=2^(-val) simulation time
units long. Default: required.
- num time-step levels will be used.
If num=1, a leap-frog integrator with constant global time step tau is used.
Otherwise, if num>1, a block-step scheme with num time-step levels is used,
i.e. the longest step contains 2^(num-1) shortest steps. The bodies’ individual
time-step levels are adapted in an (almost) time symmetric fashion as controlled
by the parameters fac, fph, fpa, and fea.
- fac=fac fph=fph fpa=fpa fea=fea
These factors control the average time step of a body to be the minimum
where a, Phi,
and e denote the acceleration, potential and softening length, respectively.
If either of these factors is zero, it is ignored.
In order to make a sensible
choice for hmin, Nlev, fac, fph, fpa, and fea, use the following method.
(1) Decide on the smallest time step: think what time step you would use
in a single-time-step leap-frog scheme and then set tau (via hmin) to about
half of that. (2) Decide on the largest time step, whereby ensuring that
orbits in regions of very low density are accurately integrated when using
the above criterion. (3) Do some tests with varying fac, fph, fpa, and
fea (set tstop=0), in order to check that the distribution of bodies over
the time steps is reasonable, in particular there should be a few percent
in the smallest time step.
Note that using this scheme is sensible only
if you really have a very inhomogeneous stellar system, because otherwise,
the simple single-time-step leap-frog is only slightly less efficient but
somewhat more accurate. In particular, with the block-step scheme, the total
momentum is not conserved, but with the single-time-step leap-frog it is. No
- The tolerance parameter
for falcON is set to val. It is recommended to stick to the default or smaller
value, but see the discussion in the falcON user guide Default: 0.6.
- In building the tree, a cell containg num bodies or less is not splitted.
This parameter controls the speed with which the tree is build. The default
is chosen to yield best performance for a single time step leap-frog scheme.
If you are using individual adaptive time steps (see above), you may consider
to increase num somewhat. This has little effect on the forces (actually
makes them slightly more accurate) but may reduce the CPU time consumption
(only with individual adaptive time steps). Default: 6.
- If val>=0,
val is taken to be the (globally constant) softening length. If val<0, bodies
are assumed to have inidividual softening lengths, which must be provided
with the input data. The individual softening lengths will be kept fixed
at their initial values throughout the simulation. With this method, you
can have larger softening length for more massive bodies, in order to have
the same maximum force (requiring individual softening lengths proporptional
to the square root of the body mass). Default: 0.05.
- The softening
kernel is taken to be the Pnum kernel (see the documentation in the user
guide). Default: 1.
- The numerical value of Newton’s constant of gravity
is set to val. Default: 1.
- With this option you can suppress the
re-growing of the tree every (shortest) time step. Instead, the tree is grown
only every 2^(num) shortest steps and re-used otherwise. Note, however that
re-using the tree violates time symmetry. I have not much experience with
this option and recommend not to use it, unless you want to validate it
- If given, the root cell of the oct-tree used in
the falcON algorithm is centred on the position x,y,z. No default.
- If given, an external acceleration field with that name is used. The code
searches for a shared object file and loads it dynamically. If the shared
object file does not contain functionality for an external acceleration
field, but for an external old-style NEMO potential, that is used to construct
an acceleration field (fall-back mechanism). Several acceleration fields
may be added by the syntax accname=name1+name2+name3. No default.
- If accname is given, the external acceleration field is using the
parameter list, a comma-separated list of floating point numbers, for initialisation.
If more than one accname is given, a parameter list (possibly empty) must
be given for each, separated by either ; or #. No default.
- accfile=file If
accname is given, the external
- acceleration field is using the the file,
if any, for initialisation. If more than one accname is given, a file name
(possibly empty) must be given for each, separated by either ; or #. No
- If given, a run-time manipulator
with that name is used. The code searches for a shared object file and loads
it dynamically. Several manipulators may be concatinated by the syntax manipname=name1+name2+name3.
- manippars=parameter list
- If manipname is given, the run-time
manipulator is using the parameter list, a comma-separated list of floating
point numbers, for initialisation. If more than one manipname is given,
a parameter list (possibly empty) must be given for each, separated by
either ; or #. No default.
- If manipname is given, the run-time
manipulator is using the the file, if any, for initialisation. If more than
one manipname is given, a file name (possibly empty) must be given for
each, separated by either ; or #. No default.
- If manipname
is given, the path path is searched for a file manipname.so to lead the
manipulator. By default, the path searched is ".:$FALCON/manip".
In order to integrate a Plummer sphere with N=10^5 particles, you may issue
mkplum - 100000 seed=1 | gyrfalcON - plum.snp tstop=10 kmax=6 eps=0.1
which first creates initial conditions from a Plummer model, which are
then piped into gyrfalcON. gyrfalcON creates an output file plum.snp containing
output every full time unit until time t=10. The log output looks like this:
# "gyrfalcON - plum.snp tstop=10 kmax=6 eps=0.1"
# run at Wed Feb 28 09:36:44
# by "wd11"
# on "virgo"
# pid 5620
# time E=T+V T V_in W -2T/W
|L| |v_cm| l2R D tree grav step accumulated
0.0000 -0.1461342 0.14677 -0.29290 -0.29161 1.0066 0.0021715 0.0017
9 16 0.07 0.94 1.02 0:00:01.02
0.015625 -0.1461343 0.14677 -0.29290 -0.29161 1.0066 0.0021715 0.0017
9 16 0.05 0.95 1.02 0:00:02.04
0.031250 -0.1461347 0.14677 -0.29290 -0.29161 1.0066 0.0021714 0.0017
9 16 0.04 0.95 1.02 0:00:03.06
0.046875 -0.1461345 0.14677 -0.29290 -0.29161 1.0066 0.0021714 0.0017
9 16 0.04 0.96 1.02 0:00:04.08
9.9531 -0.1461328 0.14451 -0.29065 -0.28940 0.99873 0.0021646 0.0017
9 16 0.05 0.96 1.03 0:10:47.70
9.9688 -0.1461329 0.14451 -0.29065 -0.28939 0.99873 0.0021646 0.0017
9 16 0.05 0.95 1.01 0:10:48.71
9.9844 -0.1461329 0.14451 -0.29064 -0.28939 0.99872 0.0021646 0.0017
9 16 0.06 0.95 1.02 0:10:49.73
10.000 -0.1461333 0.14451 -0.29064 -0.28940 0.99870 0.0021647 0.0017
9 16 0.04 0.95 1.01 0:10:50.74
output data warning (NEMO)gyrfalcON, much like ZENO programs, writes a
new type of SnapShot files, in which the PhaseSpace array has been split
into a Position and Velocity array. The get_snap macros understand this
flavor, but will - for now - convert the data back into the less flexible
type with combined PhaseSpace coordinates. see alsoaddgravity(1falcON),
Dehnen, W., 2000, ApJ, 536, L39
Dehnen, W., 2001, MNRAS, 324, 273
Dehnen, W., 2002, JCP, 179, 27
falcON/doc/user_guide.pdf User Guide for falcON
Walter Dehnen firstname.lastname@example.org
update history of this man page
18-may-2004 first version of manual WD
01-jul-2004 version 2.2 of gyrfalcON WD
27-sep-2005 version 3.0.4 of gyrfalcON WD
28-feb-2007 version 3.0.9 of gyrfalcON WD
Table of Contents