C5MPI

About

The C5MPI utility is a front-end for Century5 and DayCent5 which runs multiple simulations concurrently on systems that support MPI. C5MPI accepts a text file containing Century5 or DayCent5 command-lines, and runs one simulation per command-line, on as many CPUs or cores as is specified. A log file is created for each C5MPI job, containing progress and status information for each individual simulation.

The MPI installation on your system determines the number of cores or CPUs available. C5MPI has been tested on OpenMPI versions 1.6 and greater. The version of MPI should be at least 2.0, requiring MPI-IO capability. Parallel netCDF and HDF5 are required.

Usage

mpi-launcher-program -n [number-of-processes] C5MPI.exe [-c|-d] -f command-line-file

To view help information on using C5MPI:

mpirun -n 4 C5MPI.exe --help

or on Cray systems:

aprun -n 4 C5MPI.exe --help

The number of processes is the total number of command-lines plus 3. (C5MPI uses three processes for itself.)

To run on a typical MPI installation, use the mpiexec or mpirun program to launch C5MPI. In the following example, C5MPI will run a simulation using 8 processes, with 5 processes running the Century5 model, and will look for a command-line file named cmd-line-file.txt:

mpiexec -n 8 C5MPI.exe -c -f cmd-line-file.txt

To run on a typical Cray, use "aprun" instead of "mpiexec" to launch C5MPI. This example uses 32 cores:

aprun -n 32 -T C5MPI.exe -c -f cmd-line-file

C5MPI will produce a log file, whose name is displayed on the console. The log file contains messages, warnings, and errors, if any, produced by the simulations, and a summary of the C5MPI job.

Options

-f | --file file            Name with path of command-line file
[ -c | --century5 ]         Run the Century5 model (-c or -d is required)
[ -d | --daycent5 ]         Run the DayCent5 model
[ -rf | --restartfile file ]
                            Create a restart file at end of simulation.
[ -ids | --siteIDs ] file   File containing site ID numbers (deprecated)
[ -p | --progress-bar ]     Display a progress bar
[ -u | --username ] name    User name for simulation logs and results
[ -V | --version ]          Version information
[ -A | --about ]            Description of this product.
[ -t | --test ]             Do not run simulations, only prepare to run and report issues.
[ -? | --help ]             Display help

Examples

The following example shows lines in a command-line file using CSV output format.

# Command-line file for CPER simulations 1 through 3
# All simulations use the same management and fixed parameter set.
# Output is written to CSV files
-s CPER-1.100 -m CPER.sch -o output/CPER-1 -fm gfix.100 -ts -ar -d1 -d3
-s CPER-2.100 -m CPER.sch -o output/CPER-2 -fm gfix.100 -ts -ar -d1 -d3
-s CPER-3.100 -m CPER.sch -o output/CPER-3 -fm gfix.100 -ts -ar -d1 -d3

A typical command-line file using the spatial netCDF output format will be like this:

# Command-line file for CPER simulations 1 through 3
# All simulations use the same management and fixed parameter set.
# Output is written to a spatial netCDF file set.
# For DayCent5 simulations, do not produce daily output files.
-s CPER-1.100 -m CPER.sch -o output/CPER -fm gfix.100 -tsn -ar -td0 -d1 -d3
-s CPER-2.100 -m CPER.sch -o output/CPER -fm gfix.100 -tsn -ar -td0 -d1 -d3
-s CPER-3.100 -m CPER.sch -o output/CPER -fm gfix.100 -tsn -ar -td0 -d1 -d3

The following example shows lines in a command-line file using a spatial netCDF site parameter file, simulating site numbers 1-3.

# Command-line file for CPER simulations 1 through 3
# All simulations use the same management and fixed parameter set.
# Output is written to CSV files
-s CPER.nc,1 -m CPER.sch -o output/CPER-1 -fm gfix.100 -ts -ar -d1 -d3
-s CPER.nc,2 -m CPER.sch -o output/CPER-2 -fm gfix.100 -ts -ar -d1 -d3
-s CPER.nc,3 -m CPER.sch -o output/CPER-3 -fm gfix.100 -ts -ar -d1 -d3

Notes

Requirements and limitations:

Comment lines (lines beginning with any of the characters # ; ! or //) are ignored.
If you are using the spatial netCDF output file format, then
- all output files should have the same name. (In the above example it is "output/CPER".)
- All management files (SCH files) must have the same simulation times, output times and number of output records. The remaining management can vary with the simulation. (For CSV output format, the simulation and output times can vary.)
For parallel (concurrent) netCDF performance, the HDF5 and netCDF libraries must be built with the parallel capability enabled. (For details on building the libraries, see the document in the source code directory doc/BuildEcosystemModels.html)

Typical output from a C5MPI run looks like this:

C5MPI: starting at 1969/07/20 20:18:00
C5MPI: Log file name: C5MPI_grasslands_1969-07-20_20-18-00.log
C5MPI: starting 2 tasks for simulations.
C5MPI: stopping at 1969/07/20 20:18:01

View the log file for details of the simulations' progress and any warning and error messages.