CESM Models: CSM1.4 Climatological Data Ocean Model User's Guide
Authored by: Brian Kauffman kauff @ ucar.edu
Introduction
The Climatological Data Ocean Model (docn) functions as the ocean component in a CSM configuration. Recall that a configuration consists of various independent component models (atmosphere, land, ocean, and sea-ice), each connected to a flux coupler. The docn ocean component interacts with the flux coupler just like any ocean model would, but it is not an active model, rather, it takes SST data from an input data file and sends it to the coupler, ignoring any forcing data received from the coupler. Typically the input data file contains climatological SST data (e.g. from Shea, Trenberth, & Reynolds). Such a "dummy model" is useful for coupling an active atmosphere model with climatological SST data.
Important Note: When assembling a CSM configuration, carefully consider the limitations and requirements of all components and be sure that the complete set of component models will interact in a meaningful way. In particular, consider whether the data provided by this model is adequate for your application.
Contents
- 1. Input Data
- 2. Output Data
- 3. Input Parameters
- 4. Preparing the model for execution
- 5. Source code maintenance
1. Input Data
SST Data
On startup, this model reads in SST data from a netCDF file. This file, is called data.sst.nc, contains 12 months of SST data (presumably monthly mean fields), and is on a 2x2 degree grid. A file is provided with the source code that can be used in this context. This file contains Shea, Trenberth, & Reynolds (STR) SST climatology data. The file provided can be replaced by any other SST data file that is in the same format. Because netCDF files are self describing, one can query the file itself for specifics about the file format.
Model domain
On startup, this model reads in domain data from a netCDF file. Data exchanged with the coupler will be on this model domain. This file, called data.domain.nc, contains x & y coordinate arrays as well as a domain mask. This model uses a latitude/longitude grid only, with 1d coordinate arrays x(i) & y(j), and a 2d domain mask mask(i,j). A mask value of 0 indicates land points (i.e. not in the model's domain) and negative values indicate land-locked regions (e.g. the Caspian Sea).
Input parameter namelist
On startup, this model reads an input namelist parameter file from stdin. This model has very few input namelist parameters. Often times there will be only one input parameter, ncpl, which is a positive integer specifying how many times per simulated day this model will communicate with the flux coupler. See the section on input namelist variables for a complete list and description of namelist parameters.
Data received from the flux coupler
The model receives the following fields from the flux coupler (via message passing):
- zonal surface stress (N/m²)
- meridional surface stress (N/²)
- net shortwave radiation (W/²)
- latent+sensible+longwave+melting heat (W/²)
- precipitation+evaporation+melting water (kg/s/m²)
- land runoff water (kg/s/basin)
None of these fields are used by this model. These fields are received because the coupler/ocean interface specification requires that this set of fields be received. The coupler has no way of knowing whether the components it is connected to are active models or data models.
2. Output data
History files
This model does not create history files. The only data associated with this model is the data that is already contained in the input SST data file.
Restart files
This model does not need or create restart files.
Runtime diagnostics
This model generates some diagnostic messages which are written to stdout. This output consists mostly of brief messages that indicate how the simulation is progressing and whether any error conditions have been detected. Stdout also contains a record of the values of all model input parameters.
Data sent to the flux coupler
The model sends the following fields to the flux coupler (via message passing):
- surface temperature (°Kelvin)
- u: zonal velocity (m/s)
- v: meridional velocity (m/s)
- dh/dx: zonal surface slope (m/m)
- dh/dy: meridional surface slope (m/m)
- Q: heat of fusion (Q>0) or melting potential (Q<0) (W/m²)
While the SST is taken from the input data file (based on the 12 monthly average fields, linearly interpolated in time), the remaining fields are set to zero. This model must send these fields to the coupler because this is part of the coupler/ocean interface requirement. The fields are set to zero because we must assume they be used by the coupler (or perhaps another component model) and it would seem that zero values are reasonable in this context. The coupler has no way of knowing whether the components it is connected to are active models or data models.
3. Input Parameters
The model reads an input namelist from stdin at runtime. Following is a list and description of available namelist input parameters.
ncpl
Type:integer
Default: 1
Required: no (assuming the default value is appropriate)
Description: This specifies how many times per day the model communicates (exchanges data) with the coupler
info_dbug
Type: integer
Default: 1
Required: no
Description: Debugging information level: 0, 1, 2, or 3.
- 0 => write the least amount of debugging information to stdout
- 1 => write a small amount of debugging information to stdout
- 2 => write a medium amount of debugging information to stdout
- 3 => write a large amount of debugging information to stdout
4. Preparing the model for execution
The model's setup script, call ocn.setup.csh, is invoked prior to the execution of the model. The setup script builds the executable code, documents the source code, and gathers the required input data files.
Each CSM component gets it's own, separate subdirectory in which it's setup script is run, in which the it's executable resides, and in which all of it's input and output files are kept. A set of environment variables set in a parent NQS script and is available for use (a model may not actually use all of these variables).
Below is an example setup script, followed by some explanation.
#! /bin/csh -f
#======================================================================
# Purpose:
# (a) build an executable model (docn4 climatological data ocn model)
# (b) document the source code used
# (c) gather or create necessary input files
#======================================================================
echo '================================================================='
echo ' Preparing model for execution '
echo '================================================================='
echo ' '
echo Date: `date`
echo ' '
echo 'Env variables by a parent shell:'
echo ' $CASE = ' $CASE
echo ' $CASESTR = ' $CASESTR
echo ' $RUNTYPE = ' $RUNTYPE
echo ' $ARCH = ' $ARCH
echo ' $CSMSHARE = ' $CSMSHARE
echo ' $MAXCPUS = ' $MAXCPUS
echo ' $SSD = ' $SSD
echo ' $MSS = ' $MSS
echo ' $MSSDIR = ' $MSSDIR
echo ' $MSSRPD = ' $MSSRPD
echo ' $MSSPWD = ' $MSSPWD
echo ' $RPTDIR = ' $RPTDIR
echo ' $MSGLIB = ' $MSGLIB
echo '-----------------------------------------------------------------'
echo ' (a) Build an executable '
echo '-----------------------------------------------------------------'
if ( -e ocn ) then
echo 'Note: using an existing binary'
ls -lFt ocn src/Build.log.* | head
else
#--- create a src code sub-directory ---
mkdir src
cd src
#--- document the build ---
set BLDLOG = Build.log."`date +%y%m%d-%H%M%S`"
echo 'Note: (re)building a binary'
echo "See: $BLDLOG "
echo "Build log " >! $BLDLOG
echo "Date: `date` " >>& $BLDLOG
echo "Dir : `pwd` " >>& $BLDLOG
echo "User: $LOGNAME " >>& $BLDLOG
#--- gather source code ---
echo "/fs/cgd/csm/models/ocn/docn4.0 " >! Filepath
#cho "/insert/filepath/for/patches " >> Filepath
foreach SRCDIR (`cat Filepath`)
echo "o gathering src code from $SRCDIR" >>& $BLDLOG
cat $SRCDIR/README >>& $BLDLOG
ls -lF $SRCDIR >>& $BLDLOG
cp -fp $SRCDIR/* . >>& $BLDLOG
end
#--- select resolution ---
rm -f dims.h ; ln -s dims.h.ncom_x2 dims.h
#--- create make's include files & invoke make ---
Makeprep >>& $BLDLOG
make EXEC=docn4 ARCH=$ARCH >>& $BLDLOG || exit 2
#--- link binary into /. directory ---
cd ..
rm -f ocn ; ln -s src/docn4 ocn
endif
echo '-----------------------------------------------------------------'
echo ' (b) document the source code used '
echo '-----------------------------------------------------------------'
echo "o contents of /src:" ; ls -alFt src ; echo ' '
echo "o revision control info:" ; grep 'CVS' src/*.[hF] ; echo ' '
echo '-----------------------------------------------------------------'
echo ' (c) gather or create necessary input files '
echo '-----------------------------------------------------------------'
set DATADIR = /fs/cgd/csm/models/ocn/docn4.0
cp -fp $DATADIR/*.nc .
rm data.sst.nc ; ln -s sst.str.nc data.sst.nc
rm data.domain.nc ; ln -s domain.ncom_x2_1.nc data.domain.nc
cat >! ocn.parm << EOF
&inparm
ncpl = 1
/
EOF
echo "o contents of ocn.parm:" ; cat ocn.parm ; echo ' '
echo "o contents of `pwd`:" ; ls -alF ; echo ' '
echo '================================================================='
echo ' End of setup shell script '
echo '================================================================='
Items (a) through (c) in the above setup script are now reviewed.
(a) Build an executable
The goal here is to build an executable binary in the current working directory. This is done by
- identifying a source code directory (directories),
- acquiring the source code from that directory (directories),
- selecting a resolution-dependent "dims.h" file,
- executing the Makeprep script which creates the include files required by the makefile (e.g. a list of dependencies), and
- executing the Makefile.
The model resolution (i.e. the number of x and y grid points) must be known at compile time and is specified in one resolution-dependent file: dims.h. Notice how an appropriate dims.h file is selected. Several dims.h files are provided corresponding to frequently used resolutions, but it is easy to create a dims.h file for any desired resolution. The details of how to build the executable (e.g. preprocessor and compiler options) are contained in the Makefile.
(b) Document the source code used
Here we make a detailed listing of the source code used, a list of revision control system (CVS) information, and list of the contents of the current working directory. This information can be used to identify the source code used in a particular simulation.
(c) Gather or create necessary input files
An input namelist file is constructed. The namelist variables specify how often the model will communicate with the coupler (12 times per day) and what the input land data sequence will be (three years of data, starting at year five, with the first year in the data sequence corresponding with simulation year one). See the section describing the input namelist variables for more details.
5. Source Code Maintenance
The distribution Fortran source code for this model comes with a Makefile which suitable for use Cray C90, Cray J90, SGI, or NEC SX4 architectures. By examining how compilation between these various machines is handled, it should be easy to port this code to other machines as well. The code is written almost entirely using standard Fortran 77.
The code must be compiled with a particular model resolution in mind. The only files that must change with respect to resolution (i.e. have "hard-coded" resolution dependence) are dims.h (a source code file) and data.domain (an input data file). See the section describing the setup script for an example on how these dependencies are handled at compile time and run time.
This code was developed using the CVS revision control system, but only one "tagged" version of the code is available within any one distribution. Each source code file contains detailed revision control information.