Table of Contents

name

gyrfalcON - a superberb N-body code (public version)

synopsis

gyrfalcON [parameter=value]

requirement

requires NEMO version 3.2.1 or higher, see http://www.astro.umd.edu/nemo. It is recommended to configure NEMO with configure --enable-single --enable-lfs.

description

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.

parameters controlling I/O

in=file
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.
out=file
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 resume=t.
give=IOstring
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.
step=val
Primary data output is made every val simulation time units. If val=0 output is made every blockstep. Default: 1.
startout=t|f
Write primary output at the initial simulation time. Default t.
lastout=t|f
Write primary output at the last simulation time, even if not at an ordinary output step. Default: t.
out2=file
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.
give2=IOstring
Specifies which data are given with primary data output; same format as for give. Default: mxv.
step2=val
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.
logfile=file
Log output (time, total energy, angular momentum, CPU time consumption etc) is written to file. If file=-, log output is made to stdout. Default: -.
logstep=num
Log output is made every num blocksteps. Default 1.
resume=t|f
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.

parameters controlling the time integration

tstop=val
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.
stopfile=file
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.
kmax=val
The longest time step is taken to be tau=2^(-val) simulation time units long. Default: required.
Nlev=num
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

of

fac/|a|,

fph/|Phi|,

fpa*sqrt(|Phi|)/|a|, and

fea*sqrt(e/|a|),

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 defaults.

parameters controlling Gravity

theta=val
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.
Ncrit=num
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.
eps=val
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.
kernel=num
The softening kernel is taken to be the Pnum kernel (see the documentation in the user guide). Default: 1.
Grav=val
The numerical value of Newton’s constant of gravity is set to val. Default: 1.
hgrow=num
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 first.
root_center=x,y,z
If given, the root cell of the oct-tree used in the falcON algorithm is centred on the position x,y,z. No default.
accname=name
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.

accpars=parameter list
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 default.

other parameters

manipname=name
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. No default.
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.
manipfile=file
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.
manippath=path
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".

example

In order to integrate a Plummer sphere with N=10^5 particles, you may issue the command

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),
getgravity(1falcON) 
Dehnen, W., 2000, ApJ, 536, L39
Dehnen, W., 2001, MNRAS, 324, 273
Dehnen, W., 2002, JCP, 179, 27

files
falcON/doc/user_guide.pdf                         User Guide for falcON

author


Walter Dehnen                              walter.dehnen@astro.le.ac.uk
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