Amy Langenhorst
Amy.Langenhorst
noaa.gov
Abstract
This document describes how to acquire, compile, and run the FMS AM2 model.
Table of Contents
The Flexible Modeling System development team at GFDL uses a local implementation of GForge to serve FMS software, located at http://fms.gfdl.noaa.gov. In order to obtain the source code, you must register as an FMS user on our software server. After submitting the registration form on the software server, you should receive an automatically generated confirmation email within a few minutes. Clicking on the link in the email confirms the creation of your account.
After your account has been created, you should log in and request access to the FMS AM2 Model project. Once the FMS project administrator grants you access, you will receive a second e-mail notification. This email requires action on the part of the project administrator and thus may take longer to arrive. The email will contain a software access password along with instructions for obtaining the release package, which are described below.
To check out the release package containing source code, scripts, and documentation via CVS, type the following commands into a shell window. You might wish to first create a directory called fms in which to run these commands. You should enter the software access password when prompted by the cvs login command. At cvs login, the file ~/.cvspass is read. If this file does not already exist, an error message may display and the cvs login may fail. In this event, you should first create this file via touch ~/.cvspass.
cvs -z3 -d:pserver:cvs@fms.gfdl.noaa.gov:/cvsroot/am2 login cvs -z3 -d:pserver:cvs@fms.gfdl.noaa.gov:/cvsroot/am2 co -r khartoum am2
This will create a directory called am2 in your current working directory containing the release package. The readme file in the am2 directory gives a brief overview of the package's directory structure and contents.
If you prefer not to use CVS, you may download the tar file called am2.tar.gz from https://fms.gfdl.noaa.gov/projects/am2/. Input datasets and sample output is also available there for download. See Section 4, “Examine the Output” for more information on the sample output.
You will need to download the following files to use as input data for the AM2 model.
Table 1. Input Datasets
|
File |
Size |
Content |
|---|---|---|
|
am2_input_data.tar.gz |
1.8 GB |
Input datasets for physical parameterizations |
|
grid_spec.nc.gz |
3.2 MB |
Grid spec file (exchange grid) for use with AM2 |
|
N45L18_am2p12_om3v5.nc.tar.gz |
44 MB |
Initial conditions |
You can download these datasets from GFDL's Gforge server at https://fms.gfdl.noaa.gov/projects/am2/.
Once you have downloaded the files and placed them into the directory in which you want to store them, edit the variables inputData, gridSpec and initCond in the runscript am2/scripts/fms_runscript accordingly.
This release includes a compile script and a run script in the directory am2/scripts. The scripts should be executed from the am2/scripts directory. The compile script
-
compiles the mppnccombine executable for multiprocessing platforms,
-
compiles and links the model source code,
The run script
-
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 CVS checkout, but are made variables to accommodate changes to this directory structure.
Minimally, one should set the root directory to the location of the downloaded code. The work directory should be a temporary directory where the code will run. Note that a large amount of data will be copied into the work directory. Output from the run will be moved to the outputDir directory, which is customizable in the runscript.
For the single processor one day test case, the script took about 43 minutes to run on the SGI Origin 3000 at GFDL.
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 atmospheric dynamical core user's guide.
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 a Makefile 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 am2/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.
By default the scripts are set up to run only one day. The run length is controlled by the namelist coupler_nml which is set directly in the runscript for convenience.
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. The processor count must be consistent with the processor layouts defined in bgrid_core_driver_nml, ice_model_nml, and ocean_model_nml.
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.
You may download sample output data for comparison at https://fms.gfdl.noaa.gov/projects/am2/ under the Files tab. The file output.tar.gz contains three directories: ascii, history and restart. The ascii directory contains text output of the model including stdout and log messages. The history directory contains netCDF diagnostic output, governed by your entries in the diag_table. History files are labeled with the timestamp at the beginning of the period of data they contain. The restart directory contains files which describe the state of the model at the time given in the timestamp; to start the model running from this state, you should provide a restart file as the initial conditions for your next run. The sample runscript manages restart files itself based on the $numSubmissions and $runsPerScript variables.