HNBody  Version 1.0.10
Options Reference Manual

Introduction

This page describes the complete set of options that can appear in an HNBody options file, their syntax, and a summary of their meaning. Options can be divided into two broad categories, input and output; a single options file can contain either or both of the two types. The file is treated as an input file only if one or more particle initial conditions is supplied, and as an output file only if the Tfinal option is present; initializing an integration requires (and makes use of) only input options. Output options are used to specify the length of time a system is to be evolved, and what type of output files are to be generated, when execution is handled by the standard driver. For specialized applications, lower-level library functions are provided to allow users to develop their own drivers.

The HNBody package accepts input from files (called options files and normally named with the extension .hnb) structured according to the following format:

The notation [...] means the enclosed item is optional, while (: | =) means that either a colon (':') or an equals sign ('=') is required at that location. Individual options must occupy a single logical line, possibly spanning multiple physical lines. Both Names and Values are case-insensitive and may be abbreviated to the shortest unique symbol. Exact matches take precedence over abbreviations, and whitespace around Name and before the first Value is optional and ignored. If an option accepts multiple values, they must be separated by whitespace; their relative order is not significant. If an option has a default, it is listed in its description; this defines the value of the option if it is omitted from the file. Otherwise, the option is required if the file is of the same type as the option (e.g., 'required' input options can and should be omitted from output-only files). It is normally an error to define an option (or a value within an option) more than once. In describing the value syntax for an item,  [optional values]  are surrounded by square brackets and values that must appear together  (as a group)  are enclosed in parentheses; mutually-exclusive values  are separated by  vertical bars. Options must always contain at least one value, even if no single one is uniformly required. Consider for instance the following entry for a hypothetical option named Greek:


Greek

Syntax:     [alpha | (beta gamma) | (delta   [epsilon])]   [mu nu]

Default value:   alpha

This option's Name is Greek and it takes on a default Value of alpha if omitted from a file. A value of alpha can appear alone, or be accompanied by either the value mu or nu (but not both). If beta is specified, then gamma must also appear, but neither alpha nor delta can; epsilon may be given only if delta is, but is not mandatory. If none of alpha through epsilon appears, then either mu or nu must be given, even though they are optional otherwise.


Many options accept simple Boolean, file name, or floating-point values only; the syntax description for these lists the permitted value as <Boolean>, <File>, or <Float>, respectively. Their accepted values are as follows:

The list that follows covers the complete set of input options first, then all output options. Within each group, options are ordered alphabetically. The special Include option, which does not fit into either category, appears in both lists for convenience.

Units

The unit value corresponding to options such as MassUnit consists of a base unit, optionally preceded by a metric prefix, and optionally multiplied by a number (separated by whitespace or a '*' character). Unlike other values, base units cannot be abbreviated, and the metric prefix (but only it) is case-sensitive. All standard SI prefixes are recognized, with the modifications that 'u' is used to denote micro and 'D' to denote deka. Names for base units follow SI standards where defined, except that AU (in addition to the official SI name, ua) is accepted for astronomical units. The value of the gravitational constant G is calculated automatically in terms of the given units; this is done such that the currently recommended SI value is obtained when SI units are used, and the Gaussian gravitational constant (which is known much more accurately than G alone) is used when Solar System units—Msun, AU, and d —are specified. The base unit yr refers to a Julian year of exactly 365.25 days.


INPUT OPTIONS


AngleUnit

Syntax:   [SI-prefix]deg | [SI-prefix]rad   [<Float> ... ]

Sets the unit of measure for plane angles. The base units, deg (degree) and rad (radian), can be prefixed by any of the standard SI prefixes and multiplied by one or more numbers, which determines the overall unit.


Corrector

Syntax:   <Boolean> | Order2 Order4 Order6

Default value:   False

Determines the level of symplectic correction applied to a Symplectic integration. Boolean values either disable correction or enable it using the highest available order (recommended); the OrderN values set the use of a specific order (lower order correction is faster, but less effective).


DeltaM

Syntax:   <Float>

Default value:   0

For ZWPs evolved with a Symplectic integrator in Barycentric coordinates, sets the effective mass at barycenter (the mass factor in the Kepler drifts) according to Mbary = M * (1 + DeltaM); ignored otherwise.

Note
As a convenience, a negative value of DeltaM will be replaced by the sum of the HWP masses (excluding M) divided by M.

FixedHWPs

Syntax:   <Boolean>

Default value:   False

Indicates whether HWPs are to be held fixed at their initial positions. This specialized option is useful mainly for test calculations.


HWP

Syntax:   <Float> <Float> <Float> <Float> <Float> <Float> <Float>   [<Float> ... ]

Default value:   no default; at least one  HWP, LWP or  ZWP required

Specifies initial conditions for a heavyweight particle. At least 7 values are required (its mass and initial phase space coordinates), and possibly more. The number and ordering of values must match that declared by the InputOrder option, which must have been previously defined. Unlike most options, the option name (HWP) and separator (':' or '=') can be omitted for convenience—in this case, however, the actual particle type will be set to the value of ParticleType (= HWPs by default). The units of all values must be consistent with the {AngleUnit, LengthUnit, MassUnit, TimeUnit } set.


Include

Syntax:   <File>   [<File> ... ]

Default value:   optional — no default

Allows the user to specify one or more files to be included (read in) at the current location, in the order in which they are listed; the effect is the same as if each file had been physically edited into the current file, and the Include directive removed. A single file can contain an arbitrary number of Include directives, and included files can themselves contain Include options.


InputCoord

Syntax:   Barycentric Bodycentric Jacobi

Default value:   Bodycentric

Sets the coordinate system in which input particle phase space values (whether Cartesian vectors or osculating orbital elements; cf. InputOrder) are referenced.

Warning
This option is only partially implemented at this time. Cartesian vectors are considered intertial regardless of the value of InputCoord (hence Jacobi vectors are treated incorrectly). Barycentric and Jacobi orbital elements differ from Bodycentric elements only in the mass factor used in the conversion to inertial coordinates: M + m[i] for the former, and M for the latter, where m[i] is the mass of the particle in question.

InputOrder

Syntax:   Mass (x1 x2 x3 v1 v2 v3)  |  ( (SemiMajorAxis Eccentricity) | (SemiMajorAxis PeriDistance) | (PeriDistance Eccentricity) Inclination (LongAscendNode ArgPeriapse) | (LongAscendNode LongPeriapse) | (LongPeriapse ArgPeriapse) MeanAnomaly TrueAnomaly MeanLongitude TrueLongitude MeanLatitude TrueLatitude ((Epoch Time) TimePeriapse) )   [EncRadius]   [CaptRadius]   [IdTag]   [JacIndex]

Fixes the column order for particle initial conditions. Valid initial conditions require specification of six independent phase space values, plus mass. The phase space coordinates can be given either as Cartesian position and velocity in an arbitrary inertial frame, or as a complete set of osculating bodycentric orbital elements. The EncRadius and CaptRadius fields are reserved for future use and are currently ignored. The IdTag argument can be used to number bodies as the user finds convenient; if omitted, bodies are numbered from 1 in the order they are input, except that the dominant mass is always number 0 (this cannot be overridden). User-supplied IdTag values need not be continuous, but must be positive (IdTag = 0 is required for the dominant mass). The JacIndex field can be used to specify the Jacobi index of each body in a Symplectic integration (see Integrator) employing Jacobi coordinates (see IntegCoord), or to initialize indices when output in Jacobi coordinates is desired; if omitted, the default is to number the bodies in the order they were specified, just as for IdTag. Note that 0 <= JacIndex < N is required (JacIndex = 0 is required for the dominant mass).


IntegCoord

Syntax:   (Bodycentric   [Modified]) | Jacobi   [Order2 Order4]   [Drift-Kick Kick-Drift Shift-Drift]

Default value:   Jacobi Order2 Kick-Drift

Sets the integration (i.e., mapping) coordinates used by the Symplectic integrator for the HWPs and LWPs (the ODE methods always use bodycentric coordinates), the convergence rate of the symplectic mapping, and the order in which the Hamiltonian pieces are assembled to create the mapping.


IntegCoordZWPs

Syntax:   (Barycentric   [Regularized]) | (Bodycentric   [Order2]   [Kick-Drift]

Default value:   Barycentric Order2 Kick-Drift

Sets the integration (i.e., mapping) coordinates used by the Symplectic integrator for the ZWPs (the ODE methods always use bodycentric coordinates), the convergence rate of the symplectic mapping, and the order in which the Hamiltonian pieces are assembled to create the mapping.


Integrator

Syntax:   Symplectic | (Bulirsch-Stoer Runge-Kutta   [<Float>])

Default value:   Symplectic

Sets the integration method to use. The optional <Float> value accepted by the latter two specifies the desired relative accuracy (default = 1e-12); an accuracy of 0 disables adaptive step size control, forcing constant steps of size StepSize to be taken.


LengthUnit

Syntax:   [SI-prefix]AU | [SI-prefix]| [SI-prefix]pc | [SI-prefix]ua   [<Float> ...]

Sets the unit of measure for length. The base units, AU or ua (astronomical unit), m (meter), or pc (parsec), can be prefixed by any of the standard SI prefixes and multiplied by one or more numbers, which determines the overall unit.


LWP

Syntax:   <Float> <Float> <Float> <Float> <Float> <Float> <Float>   [<Float> ...]

Default value:   no default; at least one  HWP, LWP or  ZWP required

Specifies initial conditions for a lightweight particle. At least 7 values are required (its mass and initial phase space coordinates), and possibly more. The number and ordering of values must match that declared by the InputOrder option, which must have been previously defined. Unlike most options, the option name (LWP) and separator (':' or '=') can be omitted for convenience—in this case, however, the actual particle type will be set to the value of ParticleType (= HWPs by default). The units of all values must be consistent with the {AngleUnit, LengthUnit, MassUnit, TimeUnit} set.


LWPsPerturbZWPs

Syntax:   <Boolean>

Default value:   False

Determines whether LWPs perturb ZWPs (i.e., whether the gravitational force of the LWPs on the ZWPs is included in the calculation).


M

Syntax:   <Float>

Sets the mass of the dominant body, in units of MassUnit.

Note
If initial conditions for the dominant mass are given, the numerical value of its mass must exactly equal M.

MassUnit

Syntax:   [SI-prefix]| [SI-prefix]Msun   [<Float> ...]

Sets the unit of measure for mass. The base units, g (gram) and Msun (Solar mass), can be prefixed by any of the standard SI prefixes and multiplied by one or more numbers, which determines the overall unit.


N

Syntax:   Automatic <Float>

Default value:   = NHWPs + NLWPs + NZWPs; required if  NHWPs not defined

Sets the total number of particles in the system, including the dominant mass. A value of Automatic instructs the package to set N automatically based on the number of particle initial conditions supplied. Floating values are rounded to the nearest integer. This option can be omitted only if NHWPs is defined. However determined, all integrations require N >= 2.


NHWPs

Syntax:   Automatic <Float>

Default value:   = N - NLWPs - NZWPs; required if  N not defined

Sets the total number of HWPs in the system, including the dominant mass. A value of Automatic instructs the package to set NHWPs automatically based on the number of HWP initial conditions supplied. Floating values are rounded to the nearest integer. This option can be omitted only if N is defined; otherwise it must appear prior to any particle initial conditions (HWPs, LWPs, or ZWPs).


NLWPs

Syntax:   Automatic <Float>

Default value:   required only for systems with LWPs

Sets the total number of LWPs in the system. A value of Automatic instructs the package to set NLWPs automatically based on the number of LWP initial conditions supplied. Floating values are rounded to the nearest integer. If required this option must appear prior to any particle initial conditions (HWPs, LWPs, or ZWPs).


NZWPs

Syntax:   Automatic <Float>

Default value:   required only for systems with ZWPs

Sets the total number of ZWPs in the system. A value of Automatic instructs the package to set NZWPs automatically based on the number of ZWP initial conditions supplied. Floating values are rounded to the nearest integer. If required this option must appear prior to any particle initial conditions (HWPs, LWPs, or ZWPs).


OblateJ2

Syntax:   <Float>

Default value:   optional — no default

Sets the oblateness parameter J2 (gravitational quadrupole moment) of the dominant mass, which can be used to better model the gravitational field of an extended central object. Its use requires that OblateRadius also be defined.


OblateJ4

Syntax:   <Float>

Default value:   optional — no default

Sets the oblateness parameter J4 (gravitational octapole moment) of the dominant mass, which can be used to better model the gravitational field of an extended central object. Its use requires that OblateRadius also be defined.


OblateJ6

Syntax:   <Float>

Default value:   optional — no default

Sets the oblateness parameter J6 (sixth-order gravitational multipole moment) of the dominant mass, which can be used to better model the gravitational field of an extended central object. Its use requires that OblateRadius also be defined.


OblateRadius

Syntax:   <Float>

Default value:   required only if  OblateJ2, OblateJ4 or  OblateJ6 is defined

Sets the effective radius of the dominant mass for the purposes of calculating the field perturbations due to oblateness. This option is required if OblateJ2, OblateJ4 or OblateJ6 is specified, and ignored otherwise.


ParticleType

Syntax:   HWPs LWPs ZWPs

Default value:   HWPs

Sets the default particle type for subsequent initial conditions for which a type is not explicitly given. Unlike other options, ParticleType may be freely redefined within an options file.


PostNewtonian

Syntax:   <Boolean>

Default value:   False

Indicates whether to include post-Newtonian (i.e., leading-order general relativistic) effects due to the dominant mass.


PruneCollisions

Syntax:   <Boolean>

Default value:   False

For Symplectic integrations only (see Integrator), determines whether bodies ejected from the system should be automatically removed (ignored) for the duration of the simulation. A particle is considered "ejected" if its osculating eccentricity during any Kepler drift exceeds 1 (i.e., the orbit is hyperbolic). ODE integrations are not based on Keplerian motion and ignore this option. Note that no further output will be generated for pruned particles.


StepSize

Syntax:   <Float>

Sets the step size to use for the HWP/LWP integration, in units of TimeUnit.


StepSizeZWPs

Syntax:   <Float>

Default value:   the value of  StepSize

Sets the step size to use for ZWPs in a Symplectic integration (for ODE integrations, StepSize applies to all particles), in units of TimeUnit.


TimeUnit

Syntax:   [SI-prefix]| [SI-prefix]| [SI-prefix]| [SI-prefix]yr   [<Float> ...]

Sets the unit of measure for time. The base units, d (day), h (hour), s (second), or yr (Julian year), can be prefixed by any of the standard SI prefixes and multiplied by one or more numbers, which determines the overall unit.


Tinitial

Syntax:   <Float>

Default value:   0

Sets the absolute time (epoch) of the particle initial conditions, in units of TimeUnit.


TipToe

Syntax:   <Boolean>

Default value:   False

Indicates whether a Symplectic integration should take extra care in calculating the Kepler drifts; enabling it nearly doubles the cost of the drifts, but (for long integrations) can decrease particles' mean motion errors by several orders of magnitude.


UserInitFile

Syntax:   <File>

Default value:   optional — no default

Defines the name of an auxiliary, user-defined initialization file to pass to hnb_user_init_func(). If the user has not created a specialized driver program incorporating a user-defined initialization function, the UserInitFile option is simply ignored. If the option is omitted, a NULL argument will be passed to hnb_user_init_func(). The contents and interpretation of <File> are completely unspecified by the HNBody package.


ZWP

Syntax:   <Float> <Float> <Float> <Float> <Float> <Float> <Float>   [<Float> ... ]

Default value:   no default; at least one HWP, LWP or  ZWP required

Specifies initial conditions for a zero-weight (i.e., massless) particle. At least 7 values are required (its mass and initial phase space coordinates), and possibly more. The number and ordering of values must match that declared by the InputOrder option, which must have been previously defined. Unlike most options, the option name (ZWP) and separator (':' or '=') can be omitted for convenience—in this case, however, the actual particle type will be set to the value of ParticleType (= HWPs by default). The units of all values must be consistent with the {AngleUnit, LengthUnit, MassUnit, TimeUnit} set.


OUTPUT OPTIONS


EnergyData

Syntax:   Double Float Text

Default value:   Text

Sets the physical data format for the file: Text for ordinary text, Double for double precision binary data, and Float for single precision binary data. Note that the header is always written as plain text. It is strongly recommended that headers always be used with binary files.


EnergyFile

Syntax:   <File>

Default value:   optional — no default

Sets the name of the file to which the relative errors in energy and angular momentum exhibited by the integration are written. Each line in the file displays the errors at a particular time; details of the format are described elsewhere.


EnergyHeader

Syntax:   <Boolean>

Default value:   True

Indicates whether to prepend the EnergyFile with header information describing the contents of the file. Details of the header format are described elsewhere.


EnergyInterval

Syntax:   <Float>   [Steps]

Default value:   required only if  EnergyFile is defined

Sets the (integration) time interval at which to write data to the EnergyFile, implicitly in units of TimeUnit as specified in the input file (you cannot convert EnergyInterval to other units by specifying TimeUnit in an output file), or in units of the HWP/LWP step size if Steps is specified. In either case, the interval is rounded to the nearest integer number of Steps.


Include

Syntax:   <File>   [<File> ...]

Default value:   optional — no default

Allows the user to specify one or more files to be included (read in) at the current location, in the order in which they are listed; the effect is the same as if each file had been physically edited into the current file, and the Include directive removed. A single file can contain an arbitrary number of Include directives, and included files can themselves contain Include options.


OutputCoord

Syntax:   Barycentric Bodycentric Jacobi

Default value:   required only if  OutputFiles is defined

Sets the coordinate system to which particle phase space values (whether Cartesian vectors or osculating orbital elements) are referenced in OutputFiles.


OutputData

Syntax:   Double Float SmartFloat Text

Default value:   Text

Sets the physical data format for the file: Text for ordinary text, Double for double precision binary data, Float for single precision binary data, and SmartFloat for single precision binary data in which slowly-varying quantities (such as SemiMajorAxis) are output as differences relative to their initial values. Note that the header is always written as plain text. It is strongly recommended that headers always be used with binary files.


OutputDigits

Syntax:   <Float>

Default value:   6

Sets the number of digits precision for data written to OutputFiles; the number is rounded to the nearest integer in the range [1, 20]. This option is ignored for binary OutputData types.


OutputFiles

Syntax:   <Filespec>

Default value:   optional — no default

Sets the name of the body-specific output files to generate; these files list the phase space positions and/or other data about a particle at different times, one file for each particle. The data to outout and format thereof is determined by other Output... options. A %d in the file name is replaced by the particle's IdTag to create a unique file name for each body; if no %d is found, one is implicitly appended to <Filespec>. Likewise, a %P is replaced by the current process ID.


OutputHeader

Syntax:   <Boolean>

Default value:   True

Indicates whether to prepend OutputFiles with header information describing the contents of the file. Details of the header format are described elsewhere.


OutputInterval

Syntax:   <Float>   [Steps]

Default value:   required only if  OutputFiles is defined

Sets the (integration) time interval at which to write data to the OutputFiles, implicitly in units of TimeUnit as specified in the input file (you cannot convert OutputInterval to other units by specifying TimeUnit in an output file), or in units of the HWP/LWP StepSize if Steps is specified. In either case, the interval is rounded to the nearest integer number of Steps.


OutputOrder

Syntax:     [Time]   [Epoch]   [x1]   [x2]   [x3]   [v1]   [v2]   [v3]   [SemiMajorAxis]   [Eccentricity]   [Inclination]   [LongAscendNode]   [ArgPeriapse]   [LongPeriapse]   [TimePeriapse]   [PeriDistance]   [MeanAnomaly]   [TrueAnomaly]   [MeanLongitude]   [TrueLongitude]   [MeanLatitude]   [TrueLatitude]   [Mass]   [EncRadius]   [CaptRadius]   [IdTag]   [JacIndex]

Default value:   required only if  OutputFiles is defined

Determines the order and type of particle data to write to OutputFiles. It is permissible to specify a value more than once, though this is not recommended. The maximum number of tags allowed is 32.


OutputTypes

Syntax:     [HWPs]   [LWPs]   [ZWPs]

Default value:   HWPs LWPs ZWPs

Sets the type or types of particles for which OutputFiles are to be generated.


SaveFiles

Syntax:   <Filespec>

Default value:   optional — no default

Sets the name of the system save files to generate; these files record information about the state of the integration to allow restarting it in the event of, e.g., a computer crash or power failure. The files should not be edited in any way and there precise contents is unspecified and subject to change. A %d in the file name is replaced by a sequence number to create a unique file name each time; if no %d is present, the file will be overwritten every time the integration is saved. Likewise, a %P is replaced by the current process ID.


SaveInterval

Syntax:   <Float>   [Steps]

Default value:   required only if  SaveFiles is defined

Sets the (integration) time interval at which to save the integration state for possible restarting at a later date. The value is implicitly in units of TimeUnit as specified in the input file (you cannot convert SaveInterval to other units by specifying TimeUnit in an output file), or in units of the HWP/LWP StepSize if Steps is specified. In either case, the interval is rounded to the nearest integer number of Steps.


SaveLimit

Syntax:   <Float>

Default value:   1000000

Sets the maximum number of SaveFiles to use; once this limit has been reached, the next save file written will overwrite the oldest one present. Hence this option results in a "circular buffer" composed of the SaveLimit most recent SaveFiles.


StateCoord

Syntax:   Barycentric Bodycentric Jacobi

Default value:   required only if  StateFiles is defined

Sets the coordinate system to which particle phase space values (whether Cartesian vectors or osculating orbital elements) are referenced in StateFiles.


StateData

Syntax:   Double Float Text

Default value:   Text

Sets the physical data format for the file: Text for ordinary text, Double for double precision binary data, and Float for single precision binary data. Note that the header is always written as plain text. It is strongly recommended that headers always be used with binary files.


StateDigits

Syntax:   <Float>

Default value:   6

Sets the number of digits precision for data written to StateFiles; the number is rounded to the nearest integer in the range [1, 20]. This option is ignored for binary StateData types.


StateFiles

Syntax:   <Filespec>

Default value:   optional — no default

Sets the name of the system state files to generate; these files list the phase space positions and/or other data about all particles at different times, each body occupying one line in the StateFiles, one file for each time. The data to outout and format thereof is determined by other State... options. A %d in the file name is replaced by a sequence number to create a unique file name for each time; if no %d is found, one is implicitly appended to <Filespec>. Likewise, a %P is replaced by the current process ID.


StateHeader

Syntax:   <Boolean>

Default value:   True

Indicates whether to prepend StateFiles with header information describing the contents of the file. Details of the header format are described elsewhere.


StateInterval

Syntax:   <Float>   [Steps]

Default value:   required only if  StateFiles is defined

Sets the (integration) time interval at which to write data to the StateFiles, implicitly in units of TimeUnit as specified in the input file (you cannot convert StateInterval to other units by specifying TimeUnit in an output file), or in units of the HWP/LWP StepSize if Steps is specified. In either case, the interval is rounded to the nearest integer number of Steps.


StateOrder

Syntax:     [Time]   [Epoch]   [x1]   [x2]   [x3]   [v1]   [v2]   [v3]   [SemiMajorAxis]   [Eccentricity]   [Inclination]   [LongAscendNode]   [ArgPeriapse]   [LongPeriapse]   [TimePeriapse]   [PeriDistance]   [MeanAnomaly]   [TrueAnomaly]   [MeanLongitude]   [TrueLongitude]   [MeanLatitude]   [TrueLatitude]   [Mass]   [EncRadius]   [CaptRadius]   [IdTag]   [JacIndex]

Default value:   required only if  StateFiles is defined

Determines the order and type of particle data to write to StateFiles. It is permissible to specify a value more than once, though this is not recommended. The maximum number of tags allowed is 32.


StateTypes

Syntax:     [HWPs]   [LWPs]   [ZWPs]

Default value:   HWPs LWPs ZWPs

Sets the type or types of particles to include in StateFiles. If some types are omitted, it is recommended that IdTag be included in StateOrder to aid particle identification.


Tfinal

Syntax:   <Float>

Sets the absolute time (epoch) at which to abandon integration of the system, implicitly in units of TimeUnit as specified in the input file (you cannot convert Tfinal to other units by specifying TimeUnit in an output file), or in units of the HWP/LWP step size if Steps is specified. In either case, the time (relative to the initial time) is rounded to the nearest integer number of Steps.