next up previous
Next: Compiling athena1.0 Up: UsersGuide1 Previous: Obtaining and Installing athena1.0

Configuring athena1.0

After you have installed athena1.0, the next step is to configure the code for a specific problem, a specific machine, and for a specific level of accuracy and optimization. A shell script called configure generated by the GNU autoconf toolkit2 is used for this step.

There are several basic functions served by the configure script. The first is to enable or disable features in the code, and to choose between different packages implemented in athena1.0. Configure features are used when a particular option has only two choices: enabled (or ``on") or disabled (``off"): examples include choosing whether the executable uses single or double precision, or enabling or disabling various data output formats. Configure packages are used when an option may have more than one choice. Examples of packages include the basic physics options (such as hydrodynamics or MHD, adiabatic or isothermal equation of state, etc.), as well as the algorithm options (order of accuracy for the reconstruction step, choice of Riemann solver, etc.). These package options are controlled at the source code level using C precompiler macros. The configure script provides a powerful way of setting these macros through a command line interface that does not require the user to edit any special files.

A second basic function served by configure is to set compiler and linker options and flags using environment variables. Since optimization is not an important issue for a one-dimensional code, this feature is not used in athena1.0.

Finally, a third function of configure is to query the system automatically to see that a C-compiler, linker, and any external libraries necessary for compilation are installed and accessible. If they are not, configure can automatically disable features so as to allow installation to complete. For example, if the HDF library is not installed on the target system, configure can automatically disable HDF data output (even if the user requests this feature be enabled in the command line), allowing the code to be compiled and linked without errors due to unresolved references (although the resulting executable will not generate HDF files, of course)3.

The basic syntax of the configure command is:

configure [-enable-feature] [-disable-feature] [-with-package=choice],
where feature and package are valid options in athena1.0, and choice is the value to which package is to be set. The valid optional features in athena1.0 are given in Table 1, and the valid optional packages (including all possible choices and their default values) are given in Table 2.

Table: Optional features controlled by configure in athena1.0
double enabled computations performed in double precision
dx disabled writes header files for OpenDX scripts
fortran disabled makes binary dumps readable by fortran77 programs$^{a}$

$^{a}$Current implementation almost certainly not portable, but works with Solaris and Linux.

Table: Optional packages controlled by configure in athena1.0
PACKAGE CHOICE$^{a}$ Comments
gas hydro create code for hydrodynamics
  mhd create code for MHD
eos adiabatic use adiabatic equation of state
  isothermal use isothermal equation of state
problem function-name use function-name in directory /src/prob for initial conditions
flux roe use Roe's Riemann solver
  hlle use the HLLE Riemann solver
  hllc use the HLLC Riemann solver (hydrodynamics only)
order 2 use second-order (piecewise-linear) spatial reconstruction
  3 use third-order (piecewise-parabolic) spatial reconstruction
$^{a}$ Default choices shown in bold.

Only one choice can be made for each optional package given in Table 2 (the choices are mutually exclusive). The ``problem" package should be set to the function name in the directory athena1.0/src/prob that is to be used by the code to initialize the problem of interest. Several choices are included for the test problems that can be run by athena1.0, the default is athena1.0/src/prob/shkset.c. Note that configure creates a symbolic link between problem.c in athena1.0/src and the appropriate function name in athena1.0/src/prob.

The configure script should be run in the root directory /athena1.0. Running configure with the help option (configure -help) gives more information, including a list of all optional features and packages.

For example, to configure athena1.0 to run an isothermal hydrodynamical shocktube problem initialized with the function shkset.c problem using Roe fluxes and third-order interpolation in single precision, use the following:

configure -enable-single -with-eos=isothermal -with-gas=hydro -with-order=3

To configure athena1.0 to run the linear wave test problem in adiabatic MHD using HLLE fluxes and second-order interpolation in double precision, use the following:

configure -with-flux=hlle -with-problem=linear_wave

When configure runs, it creates a custom Makefile for the problem in the directory athena1.0/src using the file athena1.0/src/ as a template. After successful execution, configure will echo the options that have been set (including all the default values).

next up previous
Next: Compiling athena1.0 Up: UsersGuide1 Previous: Obtaining and Installing athena1.0