Go to the bottom of this page. See the search engine and sub-section links.
Go to next page Go to previous page Go to top of this section Go to top page Go to table of contents

Previous Section Headers

User's Guide to NCAR CAM2.0

2. Using CAM2.0

3. Simple Code Modifications

The most common changes to the model are the addition of new output variables, the addition of transported constituents, the modification of history file contents, the modification of the model resolution, and the addition of a new parameterization. This section provides some guidelines for making these kinds of changes. For more details on the scientific and algorithmic structure of the model see the CAM2.0 Scientific Description.

3.1 Using the Scripts with Modified Code

If the user wishes to include modified code, a disk directory or directories should first be created where all the modified code will reside. See the option in Table 2.2Commandline arguments to configure for documentation on using configure to use directories with modified source code.

3.2 Adding New Output Variables

This section describes how to add a variable to a history file.  If the field is in the Master Field List (see Table 2.7), the user must modify the code by uncommenting the outfld call for that field and must also add it to the history output via namelist variable(s) FINCL(1-6).

If the field is not on the Master Field List, the user must add it to the list by modifying routine bldfld.  Within bldfld, fields are added to the Master Field List by calling addfld.  Six pieces of information are passed to addfld in an argument list:

  1. Field name:

  2. 8-character field name, left-justified, alphanumeric or spaces only.
  3. Field units:

  4. 8-character units description. See Table 3.1
  5. Number of vertical levels in the field.
  6. Default averaging flag. See Section for more information.
  7. Field descriptor:

  8. up to 128-characters
  9. Parallel decomposition type (i.e. is this a physics or dynamics variable)
Table 3.1: Units of History File Fields
m meter
kg kilogram
s second
K degree Kelvin
percent percent
fraction fraction
gram gram
um micro meter
N Newton
Pa Pascal
W Watt

Two examples extracted from bldfld are shown below:  . Notice that the arguments passed to addfld are the 8-character field name, the 8-character field units, the number of vertical levels, the default averaging flag, a long name, and the decomposition type.

call addfld('TS      ', 'K       ', 1,'A', 'Surface temperature', phys_decomp )
call addfld('U       ', 'K       ', plev,'A', 'Zonal wind'      , dyn_decomp  )

The user must then add an outfld call for the field at an appropriate location in the code.   For example, the outfld call for the field T, taken from diagnostics.F90, is shown below: 

call outfld('T       ',  state%t, pcols, lchnk )

The arguments in the call to outfld are the 8-character field name, the variable array in which it is stored, the first dimension of the data array, and the chunk index.

Once these steps are taken, the field may be added to the desired history file by using namelist variable FINCL(1-6) or by modifying routine, h_default, which defines default history tape contents.

3.3 Trouble-Shooting Model Changes

If the cause of abnormal termination is unclear, the user should first ensure that the model is run single-threaded with SPMD off.  Abnormal termination in a multi-tasked job can result in confusing ancillary error messages.

We address several possible causes of model failure. Resource allocation errors will be addressed first, followed by remedies for suspected coding errors. Finally, analysis tools are described for physics formulation errors (i.e., where there is an error in modifications to a prognostic variable calculation).

3.3.1 Resource Allocation Errors

A system resource problem which may occur on SUN architectures is that the default stack size on the SUN is sometimes too small for larger resolution runs or when running on multiple processors.  The model usually fails with a segmentation fault.  The user should try increasing the stack size if this problem occurs. The stack size can be set to its maximum by using the limit command. Typing limit alone will print the system resource limits.  To set the stack size to its maximum type limit stacksize unlimited

When running the message passing code on multiple processors it is necessary to place the limit command in the user's shell startup script.  Since the message passing software usually starts new processes, the user must make sure that these processes have the larger stack size when started by MPI.  An easy way to determine that new shells have the larger stack size is to execute the command rsh machine limit (where machine is the name of a computer on which to start the remote shell.)  Once the stack size has been increased try running the model again.  If the stack size was too small before it should run to completion. 

3.3.2 Coding Errors

We suggest that for debugging purposes only statically allocated memory locations and/or stack space be initialized to "indefinite". Furthermore,array bounds checking should be turned on if possible. The standard Makefile achieves this if configure is invoked with the -debug option.

If the model is running but producing incorrect or suspicious history files, a quick and easy-to-use diagnostic program, cprnc, is available. This program provides a statistical analysis of differences in history file data. No command line arguments are  required. cprnc compares fields of the same name on each file, printing out statistics about the number of differences found, location and magnitude of worst absolute difference, location and magnitude of worst relative difference, RMS difference, maximum and minimum field values, and average field values.

Sub Sections

    3.1 Using the Scripts with Modified Code

    3.2 Adding New Output Variables

    3.3 Trouble-Shooting Model Changes

 Go to the top of this page. See links to previous section headers.
Go to next page Go to previous page Go to top of this section Go to top page Go to table of contents

 Search for keywords in the CAM2.0 Users GuideSearch page

Questions on these pages can be sent to... erik@ucar.edu .

$Name: $ $Revision: 1.1 $ $Date: 2004/06/08 02:57:20 $ $Author: jmccaa $