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:
|double||enabled||computations performed in double precision|
|dx||disabled||writes header files for OpenDX scripts|
|fortran||disabled||makes binary dumps readable by fortran77 programs|
|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|
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:
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:
When configure runs, it creates a custom Makefile for the problem in the directory athena1.0/src using the file athena1.0/src/Makefile.in as a template. After successful execution, configure will echo the options that have been set (including all the default values).