Quickstart Guide: Idealized finite-volume model
Abstract
This document describes how to acquire, compile, and run a “vertically Lagrangian” finite-volume model running the Held-Suarez GCM benchmark
References
A description of the finite-volume model can be found here: Lin, Shian-Jiann, 2004: A “vertically Lagrangian” finite-volume dynamical core for global models. Monthly Weather Review, 132(10), 2293-2307.
A description of the Held-Suarez GCM benchmark can be found here: Held, Isaac M., and M J Suarez, 1994: A proposal for the intercomparison of the dynamical cores of atmospheric general circulation models Bulletin of the American Meteorological Society, 75(10), 1825-1830.
Table of Contents
A zipped tar ball containing the code and scripts can be downloaded here. The tar ball contains code, scripts and a few tools.
This release includes a script which compiles and runs the model along with input data, such as namelists. These exist in the exp directory.
After extraction, the runscript exists here: exp/fms_runscript.
The runscript provided performs the minimum required steps to run the models and are intended only as a starting point for the development of more practical runscripts.
The runscript:
- compiles the mppnccombine executable for multiprocessing platforms,
- compiles and links the model source code,
- creates a working directory where the model will be run,
- creates or copies the required input data into the working directory, and
- runs the model.
Note that the directory paths and file paths are variables. They are initially set to correspond to the directory structure as it exists upon download, but are made variables to accommodate changes to this directory structure.
The diagnostic fields output from the models is mulithreaded. That is, each processor writes a separate file which includes data only from its own portion of the globe (its “domain”). A utility named mppnccombine is supplied which is executed after the model execution is complete and which combines these into a single file which covers the entire globe. For a complete description of mppnccombine see the mppnccombine documentation in the user’s guide.
The output is not moved from the working directory, archiving of output is left to the user. The files needed to restart the model are left in the working directory’s subdirectory called RESTART. If it is desired to restart the model from this state, do the following:
- Move the files in $workdir/RESTART to $workdir/INPUT.
- The mppnccombine utility will not overwrite preexisting diagnostic field files in $workdir, so they must be moved or renamed before restarting.
- Comment the if ( -e $workdir ) block in the runscript, which prevents accidental reuse of the working directory.
- You can then execute the runscript again.
If you encounter a compile error when executing the sample runscript, please first check whether you have correctly customized your mkmf template. The scripts use the mkmf utility, which creates make files to facilitate compilation. The mkmf utility uses a platform-specific template for setting up system and platform dependent parameters. Sample templates for various platforms are provided in the bin directory. You may need to consult your system administrator to set up a compilation template for your platform and ensure the locations for system libraries are defined correctly. For a complete description of mkmf see the mkmf documentation. The $platform variable in the runscript is used to separate and identify platform-specific items in the runscript, including the mkmf template.
The execution is accomplished with a utility called mpirun, which is unique to machines by Silicon Graphics. This may need to be changed to run on other platforms.
By default the scripts are set up to run only one or two days. The run length is controlled by the namelist main_nml which is set directly in the runscripts for convenience. To increase the run length to 200 days, change the namelist parameter days in the runscript as follows. The other parameter in the namelist, dt_atmos, controls the atmospheric time step.
&main_nml
days = 200,
dt_atmos = 1800 /
By default the scripts are set up to run with the MPI library, but only on one processor. To increase the number of processors, change the $npes variable at the top of the sample runscript. You may need to consult the documentation for each particular model concerning appropriate processor counts for that model.
To run without the MPI library, do the following:
- Make sure you are only using one processor, ie, the variable $npes is set to 1 at the top of the sample runscript.
- Change the run command in the runscript from “mpirun -np $npes fms.x” to simply “fms.x“.
- Remove the -Duse_libMPI from the mkmf line in the runscript.
- Remove the -lmpi from the $LIBS variable in your mkmf template.
- Move or remove your previous compilation directory (specified as $execdir in the runscript) so that all code must be recompiled.
All inquiries regarding this release should be mailed to: GFDL.Climate.Model.Info@noaa.gov