SYNOPSIS
     xgear -o source -r rates -s species -a nn -c nn -i nn -n nn -t nn -u nn 
                           [ -b nn -d nn -e nn -g nn -l nn -m nn -p nn -q nn -v nn -z nn ]
     xgear -f paramfile
     xgear -h

DESCRIPTION
     Xgear is for running astrochemical models using derivatives of the HMC (hot molecular core) 
     NEWGEAR Fortran code initially developed by Tom Millar and collaborators in the early 1980s, 
     and as further developed by Helen Roberts from 1998. The HMC code utilises DLSODE: the Double 
     precision Livermore Solver for Ordinary Differential Equations (Hindmarsh 1983; Radhakrishnan 
     and Hindmarsh 1993). See http://www.xgear.eu/ for the current status of Xgear.

     Command line parameters are defined using the following options:

     -a    Av extinction (mag)
     -b    grain radius (cm)
     -c    CRI rate factor
     -d    underlying D/H ratio
     -e    density of sites on grain surface (cm-2)
     -f    read parameters from file
     -g    gas to dust ratio
     -h    show this help information
     -i    initial abundance factor
     -l    time in years since t=0
     -m    maximum number of models per run
     -n    n(H2) number density
     -o    source or target name
     -p    dust grain albedo in far UV
     -q    dust density ratio
     -r    reaction rate filename
     -s    species and initial abundances filename
     -t    kinetic temperature (K)
     -u    UV field factor
     -v    UV field at 1400 A (erg cm-3 A-1)
     -z    cosmic ray ionisation (CRI) rate (s-1)

     Options -a -c -i -n -t -u can each take up to 10 parameter values and each parameter defaults 
     to a single arbitary value (defined in xgear.h). Most astrochemical modelling involves varying
     the values of these six parameters (as well as initial abundances in the species file).

     Options -b -d -e -g -l -p -q -v -z each take a single parameter value and each parameter 
     defaults to a 'standard' local ISM value (defined in xgear.h). Apart from the time in years 
     since t=0 and the gas to dust ratio these parameters do not normally need to be modified.

     Option -m is provided to control the maximum number of models run in a single session.

EXAMPLES
     xgear -o cloud9 -r rates.dat -s specs.dat -a 1 3 5 -c 20 -i 0.5 -n 1000 10000 -t 10 20 -u 5 

     This will run 12 models with these parameters:

     Source name:             cloud9
     Rate file:               rates.dat
     Species file:            specs.dat
     Temperature:             10  20  K  (2 values)
     Density n(H2):           1000  10000  cm-3  (2 values)
     IA factor:               0.50  (1 values)
     CRI factor:              20.00  (1 values)
     UV factor:               5.00  (1 values)
     Extinction (Av):         1.00  3.00  5.00  mag  (3 values)
     Timescale:               1.00e+07  yr
     Gas to dust ratio:       100
     Dust density ratio:      3.00
     Grain sites density:     7.90e+14  cm-2
     Grain radius:            1.00e-05  cm
     Dust grain albedo:       0.60
     CRI rate:                1.30e-17  s-1
     UV field at 1400 A:      5.00e-17  erg cm-3 A-1
     Underlying D/H ratio:    1.75e-05
     Deuterium rates:         1.70e-09  9.81e-03  1.23e+00  9.96e+01
     N+ + H2 rates:           2.31e+01  9.16e+00
     Models to run:           12 (max 25)

     An output data sub-directory will be created and named using the range of parameter values 
     (in the above example it would be named "cloud9_t10-20_n1000-10000_ia0_cri20_uv5_av1-5_001"). 
     Note that the numerical suffix is incremented if the sub-directory already exists. This 
     sub-directory will be placed in the current working directory or that pointed to by the shell
     variable XGEAR_WORK. Individual output data files will be named using the parameters of each 
     specific model run (e.g. "cloud9_t10_n1000_ia0.5_cri20.0_uv5.0_av1.0.dat" combined with the
     following prefixes: "abund_" abundances over time; "fract_" D/H abundances over time; "impor_" 
     the most important formation and destruction routes for each molecule at various times).

     xgear -f TMC-1.cfg
     
     This will load a set of parameters as specified in the file TMC-1.cfg (see xgear.cfg for
     an example configuration file). Note that command line parameters specified before -f will 
     be overridden by values specified in the configuration file, but command line parameters 
     specified after -f will override values specified in the configuration file. 

     A number of additional special parameters can only be specified in an xgear configuration 
     file. These include reaction rate parameters that can not be defined in standard rate files,
     such as deuterium fractionation reactions, and error control parameters.

ENVIRONMENT VARIABLES
     The following shell environment variables can be set to define directory locations:

     XGEAR_DIR     xgear and its resources including this help file
     XGEAR_WORK    output data directories 
     XGEAR_PARAM   parameter configuration files
     XGEAR_SPEC    species and initial abundances files
     XGEAR_RATE    reaction rates files

NOTE
     Xgear checks all parameter values and quits with an error message if any are invalid.
     See xgear.h which defines default values and minimum/maximum ranges for each parameter.