# hnbody/opts.h File Reference

Enumerations and functions related to HNBody input and output files. More...

`#include "hnbody/kernel.h"`
Include dependency graph for opts.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

## Data Structures
struct | hnb_option_struct
| Option values data structure. More...
struct | hnb_cli_struct
| HNBody Command Line Interface options. More...
## Defines
#define | HNB_ORDER_MAX 32
| Maximum number of columns allowed in InputOrder, OutputOrder, etc.
## Typedefs
typedef enum hnb_class_enum | hnb_class_t
| Output file classes.
typedef enum hnb_format_enum | hnb_format_t
| Output file formats.
typedef enum hnb_coord_enum | hnb_coord_t
| Output file coordinate systems.
typedef enum hnb_option_enum | hnb_option_tag
| Input (a.k.a. option) file tags.
typedef struct hnb_option_struct | hnb_options_t
| Option values data structure.
typedef struct hnb_cli_struct | hnb_cli_t
| HNBody Command Line Interface options.
## Enumerations
enum | hnb_class_enum { HNB_SAVE, HNB_ENERGY, HNB_OUTPUT, HNB_STATE, HNB_BAD_CLASS }
| Output file classes. More...
enum | hnb_format_enum { HNB_TEXT = 0, HNB_FLOAT = 1, HNB_DOUBLE = 2, HNB_SMARTFLOAT = 3, HNB_BAD_FORMAT }
| Output file formats. More...
enum | hnb_coord_enum { HNB_BARY, HNB_BODY, HNB_JACOBI, HNB_BAD_COORD }
| Output file coordinate systems. More...
enum | hnb_option_enum { val_true, val_yes, val_false, val_no, name_integ, val_symp, val_BS, val_RK, name_integcoord, name_coordzwp, val_jac, val_regular, val_baryc, val_bodyc, val_modified, val_kd, val_dk, val_sd, name_corr, val_O2, val_O4, val_O6, val_rev, name_tiptoe, name_enc, name_prune, name_thread, name_thrtiming, name_dzH, name_dzZ, name_M, name_dM, name_N, name_nH, name_nL, name_nZ, val_auto, name_aunit, val_deg, val_rad, name_munit, val_g, val_Msun, name_lunit, val_m, val_AU, val_ua, val_pc, name_tunit, val_s, val_h, val_d, val_yr, name_incoord, name_iorder, val_mass, val_rcapt, val_renc, val_semi, val_peridist, val_ecc, val_incl, val_longasc, val_longperi, val_argperi, val_meanlong, val_truelong, val_meanlati, val_truelati, val_meananom, val_trueanom, val_time, val_epoch, val_timeperi, val_x1, val_x2, val_x3, val_v1, val_v2, val_v3, val_idtag, val_jindex, name_J2, name_J4, name_J6, name_obRadius, name_postn, name_ptype, name_ltype, val_hwps, val_lwps, val_zwps, name_hwp, name_lwp, name_zwp, name_fixhwp, name_tinit, name_tfinal, name_outfile, name_outhead, name_outint, name_outcoord, name_outdig, name_outdata, name_outtype, name_outorder, name_stfile, name_sthead, name_stint, name_stcoord, name_stdig, name_stdata, name_sttype, name_storder, name_savfile, name_savint, name_savlimit, name_ergfile, name_erghead, name_ergint, name_ergdata, val_steps, val_double, val_float, val_smart, val_text, name_infile, name_include, NOPTAGS, MULTITAGS, FLOATVAL }
| Input (a.k.a. option) file tags.
## Functions
DLLSPEC void | hnb_blank_cli (hnb_cli_t *cli)
| Clears command line interface options.
DLLSPEC void | hnb_blank_options (hnb_options_t *opts)
DLLSPEC void | hnb_fill_options (hnb_options_t *opts)
DLLSPEC void | hnb_free_options (hnb_options_t *opts)
| Frees allocated options memory.
DLLSPEC void | hnb_read_option_array (hnb_options_t *opts, const char *array[], FILE *logfile)
| Parses an HNBody option string array.
DLLSPEC void | hnb_read_option_file (hnb_options_t *opts, const char *file, FILE *logfile)
| Parses an HNBody input file.
DLLSPEC void | hnb_exec (hnb_data_t *sys, const hnb_options_t *opts, FILE *logfile, const char *save)
| Executes a pre-initialized integration.
DLLSPEC int | hnb_interface (hnb_options_t *opts, hnb_cli_t *cli, int argc, char *argv[], void(*custom)(FILE *f, const char *prefix))
| Parses the standard HNBody driver command line interface.
DLLSPEC int | hnb_opts_driver (hnb_options_t *opts, const hnb_cli_t *cli, hnb_extra_t kick, hnb_extra_t shift, hnb_drift_t drift, hnb_derivs_t derivs, hnb_energy_t energy)
| Performs an integration given a complete set of defining options.
DLLSPEC double | hnb_benchmark (const hnb_options_t *opts, hnb_extra_t kick, hnb_extra_t shift, hnb_drift_t drift, hnb_derivs_t derivs, double maxcpu)
| Estimates CPU time per step of an integration.
DLLSPEC hnb_data_t * | hnb_opts_init (hnb_options_t *opts, hnb_extra_t ekick, hnb_extra_t eshift, hnb_drift_t edrift, hnb_derivs_t ederivs, hnb_energy_t energy)
| Initializes an HNBody integration.

## Detailed Description

Id
  opts.h,v 1.18 2011/06/14 15:56:47 rauch Exp

Author:
  Kevin P. Rauch

## Typedef Documentation

typedef enum hnb_format_enum hnb_format_t

Warning:
  Numerical values are fixed by the file type spec---do not change!

## Enumeration Type Documentation

enum hnb_class_enum

Enumerator:

  HNB_SAVE | Save file.
  HNB_ENERGY | Energy file.
  HNB_OUTPUT | Output file.
  HNB_STATE | State file.
  HNB_BAD_CLASS | Explicit invalid value.

enum hnb_coord_enum

Enumerator:

  HNB_BARY | Barycentric reference frame.
  HNB_BODY | Bodycentric reference frame.
  HNB_JACOBI | Jacobi (hierarchical barycentric) reference frame.
  HNB_BAD_COORD | Explicit invalid value.

enum hnb_format_enum

Warning:
  Numerical values are fixed by the file type spec---do not change!

Enumerator:

  HNB_TEXT | Text (ASCII) format.
  HNB_FLOAT | Single precision format.
  HNB_DOUBLE | Double precision format.
  HNB_SMARTFLOAT | Optimized single precision format.
  HNB_BAD_FORMAT | Explicit invalid value.

## Function Documentation

DLLSPEC double hnb_benchmark | ( | const hnb_options_t * | opts,
|  | hnb_extra_t | kick,
|  | hnb_extra_t | shift,
|  | hnb_drift_t | drift,
|  | hnb_derivs_t | derivs,
|  | double | maxcpu |
| ) |  |  |

This routine determines the average CPU time per step of an integration. The number of steps integrated is systematically increased until of order tcpu seconds of CPU time have been used. If no options are supplied a standard test problem is integrated. All output is disabled during benchmarking; if output is frequent, the returned value may significantly underestimate the actual time per step. Results may also be inaccurate if the CPU time for a complete integration (Tinitial to Tfinal) is of order the resolution of the system clock.

Parameters:

  | opts | is the (filled) options structure specifying the integration; if NULL, a standardized (HNBmark) integration is benchmarked.
  | kick | is an optional `extra_kick()` term to include in the integration; use NULL if none (Symplectic only).
  | shift | is an optional `extra_shift()` term to include in the integratio; use NULL if none (Symplectic only).
  | drift | is an optional `extra_drift()` term to include in the integratio; use NULL if none (Symplectic only).
  | derivs | is an optional `extra_derivs()` term to include in the integration; use NULL if none (ODE only).
  | maxcpu | is the desired CPU time (in seconds) to expend during the benchmark.

Returns:
  the CPU time per step (in seconds), or -1 if benchmarking failed for any reason.

References hnb_exec(), hnb_free_options(), hnb_opts_init(), and hnb_read_option_array().

Referenced by hnb_interface(), and hnb_opts_driver().

DLLSPEC void hnb_blank_cli | ( | hnb_cli_t * | cli | ) |

This routine initializes a command line interface structure with its default values. It is assumed that all members are prepared to be overwritten---in particular, no attempt is made to close file pointers or free dynamic memory (it has no way of determining whether such actions are appropriate).

References hnb_cli_struct::bench, hnb_cli_struct::help, hnb_cli_struct::log, hnb_cli_struct::logfile, hnb_cli_struct::quiet, hnb_cli_struct::recfile, hnb_cli_struct::savefile, hnb_cli_struct::tcpu, and hnb_cli_struct::version.

Referenced by hnb_interface().

DLLSPEC void hnb_exec | ( | hnb_data_t * | sys,
|  | const hnb_options_t * | opts,
|  | FILE * | log,
|  | const char * | save |
| ) |  |  |

This routine takes a pre-initialized system and a set of (output) options, and performs the integration. If log is non-NULL, it is an open file descriptor to use for ancillary output. If save is non-NULL, it is the name of an HNBody Save file to be used in restarting the integration; Energy and Output files are trimmed to their length when the save file was written.

References hnb_exec(), and HNB_SMARTFLOAT.

Referenced by hnb_benchmark(), hnb_exec(), and hnb_opts_driver().

DLLSPEC void hnb_free_options | ( | hnb_options_t * | opts | ) |

This routine frees any dynamically allocated memory inside the options structure (it does not assume that opts itself was dynamically allocated---if so it must be freed separately).

Warning:
  All pointer types are assumed to be independent blocks of heap. This is true for structures filled by standard HNBody API calls; beware if you have filled it manually!

Parameters:

  | opts | is the options structure whose contents is to be freed.

References hnb_free_options().

Referenced by hnb_argv_driver(), hnb_benchmark(), and hnb_free_options().

DLLSPEC int hnb_interface | ( | hnb_options_t * | opts,
|  | hnb_cli_t * | cli,
|  | int | argc,
|  | char * | argv[],
|  | void(*)(FILE *f, const char *prefix) | custom |
| ) |  |  |

This routine parses the standard HNBody command line options, reads and digests the specified HNBody input files, and saves the results in opts and cli. The output can be fed directly to hnb_driver(). Actionable (the -h, -m and -v flags) or invalid command line options result in return of a blank opts structure.

Parameters:

  | opts | is the options structure to initialize (blank) and fill in.
  | cli | is the command line structure to initialize and fill in.
  | argc | is the number of command line arguments supplied.
  | argv | is the array of option strings; argv[0] should contain the name of the driver.
  | custom | is an optional custom driver version/information writer whose output is prepended to help messages and log files; use NULL if none.

Returns:
  0 (opts filled) or 1 (opts blank) on success, else -1 (opts blank) on any error.

Warning:
  The contents of cli and opts will be completely overwritten; avoiding memory leaks etc. is the responsibility of the caller.

See also:
  hnb_argv_driver(), hnb_opts_driver()

References hnb_cli_struct::bench, hnb_cli_struct::help, hnb_benchmark(), hnb_blank_cli(), hnb_read_option_file(), hnb_cli_struct::log, hnb_cli_struct::logfile, hnb_cli_struct::quiet, hnb_cli_struct::recfile, hnb_cli_struct::savefile, hnb_cli_struct::tcpu, and hnb_cli_struct::version.

Referenced by hnb_argv_driver().

DLLSPEC int hnb_opts_driver | ( | hnb_options_t * | opts,
|  | const hnb_cli_t * | cli,
|  | hnb_extra_t | kick,
|  | hnb_extra_t | shift,
|  | hnb_drift_t | drift,
|  | hnb_derivs_t | derivs,
|  | hnb_energy_t | energy |
| ) |  |  |

This routine sets up and then executes an integration defined by the supplied options and command line arguments.

Parameters:

  | opts | is the (filled) options structure defining the integration.
  | cli | contains the command line interface values for the integration.
  | kick | is an optional `extra_kick()` term to include in the integration; use NULL if none (Symplectic only).
  | shift | is an optional `extra_shift()` term to include in the integration; use NULL if none (Symplectic only).
  | drift | is an optional `extra_drift()` term to include in the integration; use NULL if none (Symplectic only).
  | derivs | is an optional `extra_derivs()` term to include in the integration; use NULL if none (ODE only).
  | energy | is an optional `extra_energy()` term to include in the integration; use NULL if none.

Returns:
  EXIT_SUCCESS on success, else EXIT_FAILURE.

Note:
  opts can be modified during initialization, and should be reused only to repeat the same integration, possibly with trivial changes. At present only changing `Tfinal` is considered "trivial".

See also:
  hnb_argv_driver(), hnb_interface()

References hnb_benchmark(), hnb_exec(), hnb_opts_init(), hnb_cli_struct::log, hnb_cli_struct::quiet, hnb_cli_struct::recfile, hnb_cli_struct::savefile, and hnb_cli_struct::tcpu.

Referenced by hnb_argv_driver().

DLLSPEC hnb_data_t* hnb_opts_init | ( | hnb_options_t * | opts,
|  | hnb_extra_t | kick,
|  | hnb_extra_t | shift,
|  | hnb_drift_t | drift,
|  | hnb_derivs_t | derivs,
|  | hnb_energy_t | energy |
| ) |  |  |

This routine initializes an HNBody integration given a set of options and optional additions to the Hamiltonian; aside from initial conditions, it is assumed that all other option information has been assigned valid values.

Parameters:

  | opts | is the (filled) options structure specifying the integration.
  | kick | is an optional `extra_kick()` term to include in the integration; use NULL if none (Symplectic only).
  | shift | is an optional `extra_shift()` term to include in the integratio; use NULL if none (Symplectic only).
  | drift | is an optional `extra_drift()` term to include in the integratio; use NULL if none (Symplectic only).
  | derivs | is an optional `extra_derivs()` term to include in the integration; use NULL if none (ODE only).
  | energy | is an optional `extra_energy()` term to include in the integration; use NULL if none.

Returns:
  a valid, initialized integration structure, else NULL.

References HNB_JACOBI, hnb_opts_init(), HNB_ORDER_MAX, and hnb_raw_init().

Referenced by hnb_benchmark(), hnb_opts_driver(), and hnb_opts_init().

DLLSPEC void hnb_read_option_array | ( | hnb_options_t * | opts,
|  | const char * | array[],
|  | FILE * | log |
| ) |  |  |

This routine parses the contents of an array of option strings and adds the digested content to an options structure. It can be called successively given the same structure to accumulate options spread over multiple files.

Parameters:

  | opts | is the structure in which to accumulate options.
  | array | is the string array to parse.
  | log | is the (optional) stream for diagnostic output.

See also:
  hnb_read_option_file

References HNB_ORDER_MAX, and hnb_read_option_array().

Referenced by hnb_benchmark(), and hnb_read_option_array().

DLLSPEC void hnb_read_option_file | ( | hnb_options_t * | opts,
|  | const char * | file,
|  | FILE * | log |
| ) |  |  |

This routine parses the contents of an options file and adds the digested content to an options structure. It can be called successively given the same structure to accumulate options spread over multiple files.

Parameters:

  | opts | is the structure in which to accumulate options.
  | file | is the file to parse.
  | log | is the (optional) stream for diagnostic output.

See also:
  hnb_read_option_array

References HNB_ORDER_MAX, and hnb_read_option_file().

Referenced by hnb_interface(), and hnb_read_option_file().