Amy Langenhorst
Amy.Langenhorst
noaa.gov
Abstract
This document describes how to acquire, compile, and run specific test cases of four solo FMS atmospheric dynamical core models. The available codes are a finite-difference B-grid model, a spectral transform model, and a "vertically Lagrangian" finite-volume model running the Held-Suarez GCM benchmark. Also included are a B-grid shallow water model and two simple spectral variations, a spectral barotropic model and spectral shallow water model.
For more information, see the User's Guide which is included in this package and also accessible from the FMS Homepage.
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 Atmospheric Dynamical Cores 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 instructions for obtaining the release package, which are described below.
The download will create a directory called atm_dycores in your current working directory containing the release package. The readme file in the atm_dycores directory gives a brief overview of the package's directory structure and contents.
Sample output is also available for download. See Section 3, “Examine the Output” for more information on the sample output.
This release includes six sample experiments in the directory atm_dycores/exp. Each runs one of the atmospheric dynamical core models, which are:
-
B-grid
A hydrostatic, finite difference primative equation GCM. A complete description can be found at ../src/atmos_bgrid/documentation/bgrid.pdf.
-
B-grid Shallow Water
A B-grid model of shallow incompressible fluid dynamics. A description of the B-grid dynamical core can be found at ../src/atmos_bgrid/documentation/bgrid.pdf.
-
Spectral
A hydrostatic, spectral primative equation GCM. A complete description can be found at ../src/atmos_spectral/documentation/spectral_core.pdf.
-
Spectral Shallow Water
A spectral model of shallow incompressible fluid dynamics. A complete description can be found at ../src/atmos_spectral_shallow/shallow.pdf.
-
Spectral Barotropic
A spectral model of non-divergent incompressible fluid dynamics. A complete description can be found at ../src/atmos_spectral_barotropic/barotropic.pdf.
-
Finite Volume
A "vertically Lagrangian" finite-volume model. A complete description can be found in
Lin, S-J., 2004: A "vertically Lagrangian" finite-volume dynamical core for global models. Monthly Weather Review, 132(10), 2293-2307.
The runscripts provided in each exp/$dycore directory perform the minimum required steps to run the models and are intended only as a starting point for the development of more practical runscripts. The sample script:
-
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 atm_dycores/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.
You may download sample output data for comparison at https://fms.gfdl.noaa.gov/projects/fms/ under the "Files" tab. Each tar file expands to a directory containing a readme file along with netcdf and ascii output. The files bgrid_output.tar.gz, fv_output.tar.gz and spectral_output.tar.gz contain daily snapshots of surface pressure and time means of all fields over the 200 to 1200 day period. The file bgrid_shallow_output.tar.gz contains daily snapshots of surface pressure and time means of all fields over a 30 day period. The file spectral_barotropic_output.tar.gz contains 1000 days of diagnostic output with a 200 day spin-up period for the spectral barotropic model. spectral_shallow_output.tar.gz contains 30 days of diagnostic output for the spectral shallow water model.