# kernel/driver.c File Reference

Implements driver-related HNBody functionality. More...

`#include <math.h>`
`#include <signal.h>`
`#include "hnbody/errors.h"`
`#include "hnbody/expert.h"`
`#include "hnbody/output.h"`
Include dependency graph for driver.c:

## Functions
void | hnb_checkpoint (hnb_data_t *sys, const char *file, int halt)
| Sets on-demand checkpointing of an integration.
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.
void | hnb_blank_cli (hnb_cli_t *cli)
| Clears command line interface options.
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.
int | hnb_argv_driver (int argc, char *argv[], hnb_extra_t kick, hnb_extra_t shift, hnb_drift_t drift, hnb_derivs_t derivs, hnb_energy_t energy, void(*custom)(FILE *f, const char *prefix))
| Performs an integration given a set of command line arguments.
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.

## Detailed Description

Id
  driver.c,v 1.11 2011/06/14 15:57:03 rauch Exp

SRC-Level: ISO C
MT-Level: TBD

Author:
  Kevin P. Rauch

## Function Documentation

int hnb_argv_driver | ( | int | argc,
|  | char * | argv[],
|  | hnb_extra_t | kick,
|  | hnb_extra_t | shift,
|  | hnb_drift_t | drift,
|  | hnb_derivs_t | derivs,
|  | hnb_energy_t | energy,
|  | void(*)(FILE *f, const char *prefix) | custom |
| ) |  |  |

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

Parameters:

  | argc | is the number of command line arguments supplied.
  | argv | is the array of argument strings; argv[0] should contain the name of the driver.
  | 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.
  | custom | is an optional custom driver version/information writer whose output is prepended to help messages and log files; use NULL if none.

Returns:
  EXIT_SUCCESS on success, else EXIT_FAILURE.

See also:
  hnb_interface(), hnb_opts_driver()

References hnb_free_options(), hnb_interface(), hnb_opts_driver(), hnb_cli_struct::log, and hnb_cli_struct::logfile.

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().

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().

void hnb_checkpoint | ( | hnb_data_t * | sys,
|  | const char * | file,
|  | int | halt |
| ) |  |  |

Parameters:

  | sys | is the integration to checkpoint.
  | file | is the name of the save file to write; use NULL if none.
  | halt | is non-zero iff the hnb_exec() should return once the current step is completed.

Note:
  This routine is async-signal safe.

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().

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().