User's Guide to NCAR CAM2.0.2

2. Using CAM2.0.2

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.2 Scientific Description.

3.1 Using the Scripts with Modified 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:

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

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

up to 128-characters
6. Parallel decomposition type (i.e. is this a physics or dynamics variable)

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

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 some architectures is that the default stack size on 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.

    3.1 Using the Scripts with Modified Code

    3.2 Adding New Output Variables

    3.3 Trouble-Shooting Model Changes

 Search page

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