The HNBody package accepts input from files (called options files and normally named with the extension .hnb) structured according to the following format:
Name (: | =) Value [Value ...] [# Comment...]
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:
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:
<Boolean> values can be any one of: False, No, True, or Yes, the first pair and last pair being synonyms for each other.<File> values must be a legal file name.<Filespec> values are the same as <File>, except that %d substrings are replaced by numeric values as described by the option.<Float> values must be valid decimal floating-point constants.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.
<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.
<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).
<Float> 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.
<Boolean> Indicates whether HWPs are to be held fixed at their initial positions. This specialized option is useful mainly for test calculations.
<Float> <Float> <Float> <Float> <Float> <Float> <Float> [<Float> ... ] 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.
<File> [<File> ... ] 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.
Sets the coordinate system in which input particle phase space values (whether Cartesian vectors or osculating orbital elements; cf. InputOrder) are referenced.
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).
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.
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.
<Float>])
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.
<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.
<Float> <Float> <Float> <Float> <Float> <Float> <Float> [<Float> ...] 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.
<Boolean> Determines whether LWPs perturb ZWPs (i.e., whether the gravitational force of the LWPs on the ZWPs is included in the calculation).
<Float>Sets the mass of the dominant body, in units of MassUnit.
<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.
<Float> 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.
<Float> 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 HWP initial conditions.
<Float> 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. This option must appear prior to any LWP initial conditions.
<Float> 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. This option must appear prior to any ZWP initial conditions.
<Float> 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.
<Float> 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.
<Float> 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 or OblateJ4 is specified, and ignored otherwise.
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.
<Boolean> Indicates whether to include post-Newtonian (i.e., leading-order general relativistic) effects due to the dominant mass.
<Boolean> 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.
<Float>Sets the step size to use for the HWP/LWP integration, in units of TimeUnit.
<Float> Sets the step size to use for ZWPs in a Symplectic integration (for ODE integrations, StepSize applies to all particles), in units of TimeUnit.
<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.
<Float> Sets the absolute time (epoch) of the particle initial conditions, in units of TimeUnit.
<Boolean> 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.
<File>
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.
<Float> <Float> <Float> <Float> <Float> <Float> <Float> [<Float> ... ] 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.
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.
<File> 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.
<Boolean> Indicates whether to prepend the EnergyFile with header information describing the contents of the file. Details of the header format are described elsewhere.
<Float> [Steps] 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.
<File> [<File> ...] 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.
Sets the coordinate system to which particle phase space values (whether Cartesian vectors or osculating orbital elements) are referenced in OutputFiles.
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.
<Float> 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.
<Filespec>
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>.
<Boolean> Indicates whether to prepend OutputFiles with header information describing the contents of the file. Details of the header format are described elsewhere.
<Float> [Steps] 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.
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.
Sets the type or types of particles for which OutputFiles are to be generated.
<Filespec>
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.
<Float> [Steps] 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.
<Float> 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.
Sets the coordinate system to which particle phase space values (whether Cartesian vectors or osculating orbital elements) are referenced in StateFiles.
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.
<Float> 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.
<Filespec>
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>.
<Boolean> Indicates whether to prepend StateFiles with header information describing the contents of the file. Details of the header format are described elsewhere.
<Float> [Steps] 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.
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.
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.
<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.
1.3.6