|
HNBody
Version 1.0.10
|
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:
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:
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:
<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 and %P substrings are replaced by numeric values as described by the corresponding options.<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.
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.
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.
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).
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.
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.
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.
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.
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.
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).
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.
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.
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.
Syntax: [SI-prefix]AU | [SI-prefix]m | [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.
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.
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).
Syntax: <Float>
Sets the mass of the dominant body, in units of MassUnit.
Syntax: [SI-prefix]g | [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.
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.
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).
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).
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).
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.
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.
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.
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.
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.
Syntax: <Boolean>
Default value: False
Indicates whether to include post-Newtonian (i.e., leading-order general relativistic) effects due to the dominant mass.
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.
Syntax: <Float>
Sets the step size to use for the HWP/LWP integration, in units of TimeUnit.
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.
Syntax: [SI-prefix]d | [SI-prefix]h | [SI-prefix]s | [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.
Syntax: <Float>
Default value: 0
Sets the absolute time (epoch) of the particle initial conditions, in units of TimeUnit.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Syntax: [HWPs] [LWPs] [ZWPs]
Default value: HWPs LWPs ZWPs
Sets the type or types of particles for which OutputFiles are to be generated.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
1.8.7