The CESM Ocean Ecosystem Model User's Guide

Nancy J. Norton
Keith Lindsay
National Center for Atmospheric Research
25 June 2010

Contents

1. Introduction
2. The ecosys_nml namelist
3. The ecosys_parms_nml namelist
4. Ecosystem model output
   • Ecosystem model additions to the POP tavg_nml namelist settings
   • Ecosystem model additions to the POP tavg_contents file
5. Auto-generated generic extra-tracer time-averaged history (tavg_contents) fields
6. The ocn.ecosystem.setup.csh script
7. Customizing your ecosystem model ecosys_nml, tavg_nml, and tavg_contents settings
   • ecosys_nml namelist
   • tavg_nml namelist
   • tavg_contents fields and/or streams
8. Customizing your ecosystem model ecosys_parms_nml settings

Introduction

This User's Guide contains information on the CESM1 ocean ecosystem model namelist settings, time-averaged history-file variables, and scripts. The user of this guide is expected to be familiar with the terminology and concepts contained in the CESM1 User's Guide and the CESM1 POP User's Guide.

The CESM ocean ecosystem model executes as a submodel of the CESM POP active-ocean model. It is activated by adding the string 'ecosys' to the CESM environment variable $OCN_TRACER_MODULES in the user's $CASE/env_build.xml file. Only active-ocean cases using POP (eg, B-, C-, or G-type compsets) can run the CESM ocean ecosystem model. Typically, a user will select an ecosystem case at the CESM create_newcase stage by selecting an ecosystem compset in which the $OCN_TRACER_MODULES variable already includes the 'ecosys' string, such as C- or G- compsets with "ECO" in the name (eg, compset CECO) and B compsets with "BGC" in the name.

The CESM ecosystem model code is distributed with the CESM POP model and resides in the same source-code directory as the main POP model. Of particular interest to the ecosystem-model user is the file ecosys_parms.F90, which defines the parameter values in one of the two ecosystem model namelists, ecosys_parms_nml.

An extensive collection of shell scripts supports the creation of a new CESM $CASE via the create_newcase command. For the CESM ocean ecosystem model, there exists an additional, specialized script, ocn.ecosys.setup.csh, that is used to automatically generate appropriate ecosystem model settings. This script is located in the POP input_templates directory.

In order to make changes to most of the out-of-the box ocean ecosystem settings, you must modify the ocn.ecosys.setup.csh script; in order to modify the ecosys_parms_nml namelist paramters, you must modify the FORTRAN file ecosys_parms.F90. A section on customizing your ocean ecosystem settings appears at the end of this document.

Return to top

The ecosys_nml namelist

The ecosys_nml namelist is one of two CESM ocean ecosystem model namelists. The variables in the ecosys_nml namelist are set by the ocn.ecosys.setup.csh script and are summarized in the following table.

¹ automatically set by the ocn.ecosys.setup.csh script

Return to top

The ecosys_parms_nml namelist

The ecosys_parms_nml namelist is one of two CESM ocean ecosystem model namelists. The variables in the ecosys_parms_nml namelist are set in the ecosys_parms.F90 file and are summarized in the following table.

² dps = number of days in a second

³ T_ref = 30.0 reference temperature (deg. C)

Return to top

Ecosystem model output

The creation of POP time-averaged output files and their contents is controlled by the tavg_contents file and the tavg_nml namelist. The entries in the tavg_contents file are used to request individual history-file output fields, and the tavg_nml namelist is used to specify the averaging interval, the output filenames, the frequency of the file writes, the names of the output files, the number of the output files (output "streams"), etc. For details, see the "Time-averaged history files" section in the CESM1 POP User's Guide.

The ecosystem model defines and controls its own output fields and files. The mechanism by which this is accomplished is defined in the following two sections.

Ecosystem model additions to the POP tavg_nml namelist settings

When a CESM ecosystem $CASE.run script is executed, the ecosystem setup script dynamically modifies the tavg_nml settings that appear in the POP base-model namelist input file, pop2_in. The ecosystem setup script adds two ecosystem time-averaged output streams to the tavg_nml namelist. The following code block is used to define the settings for these additional streams. If you want to change these settings, follow the instructions in the customization section below.

        tavg_freq_opt             = 'nday'          'nyear'
        tavg_freq                 =  1              1
        tavg_stream_filestrings   = 'ecosys.nday1'  'ecosys.nyear1'
        tavg_file_freq_opt        = 'nmonth'        'nyear'
        tavg_file_freq            =  1              1
        tavg_start_opt            = 'nstep'         'nstep'
        tavg_start                =  0              0
        tavg_fmt_in               = 'nc'            'nc'
        tavg_fmt_out              = 'nc'            'nc'
        ltavg_has_offset_date     = .false.         .false.
        tavg_offset_years         =  1              1
        tavg_offset_months        =  1              1
        tavg_offset_days          =  2              2
        ltavg_one_time_header     = .false.         .false.

These tavg_nml settings create two ecosystem-specific output files ("streams") that will contain only ecosystem-model variables. The first is a file of daily averaged fields which will be bundled together in a monthly timeseries file in netCDF format. That file's name will have the string 'ecosys.nday1' embedded in it. The second is a file of annually averaged fields written once per year in a netCDF file; its name will include the string 'ecosys.nyear1'.

Return to top

Ecosystem model additions to the POP tavg_contents file

When a CESM ecosystem $CASE.run script is executed, the ecosystem setup script dynamically appends time-averaged history-file variables to the POP base-model tavg_contents file. By appearing the in the tavg_contents file, the fields are "requested" and will therefore appear in the time-averaged history output files when the CASE is run.

By default, the CESM ecosystem tavg_contents variables are assigned to three different output streams, which are identified in the following table as $s1, $s2, and $s3. The first stream, $s1, is set to 1 by the ocn.ecosys.setup.csh script. This means that anything in the tavg_contents file in stream $s1 will be written to the first base-model stream. (By default, the base-model stream is a stream of monthly averaged fields).

The $s2 stream is the first of the two ecosystem-specific output files, and $s3 is the second. The actual values of $s2 and $s3 are determined at run time by the ecosystem setup script, depending on the number of output streams in the rest of the POP model.

The following table summarizes all of the ecosystem fields that are automatically appended to the tavg_contents file. Note that some entries in this table are defined, but inactive, in the ocn.ecosys.setup.csh script (denoted "inactive" in the Output stream number column). The user can activate them if desired; if you want to change these default settings, follow the instructions in the customization section below.

Return to top

Auto-generated generic extra-tracer time-averaged history (tavg_contents) fields

Every variable that appears in the POP tavg_contents input file must also be defined in the POP model code, which is accomplished via a call to the define_tavg_field routine for each variable. POP automatically generates a pre-defined set of time-averaged history output fields for each extra tracer (tracers other than T and S).

This convenient mechanism allows a user to select these pre-defined fields in the tavg_contents file for any extra model tracer without needing to modify the code. (See the customization section for how to select or add an ecosystem field, such as an auto-generated field, to the tavg_contents file.)

Return to top

The ocn.ecosystem.setup.csh script

The ocn.ecosys.setup.csh script is invoked by the $CASE/Buildconf/pop2.buildnml.csh script each time an active-ocean CESM ecosystem $CASE.run script is executed. The ocn.ecosys.setup.csh script has multiple entry points, each of which controls a different aspect of the ecosystem model setup. The entry points of interest to the user who wants to modify the out-of-the-box settings include:

• namelist defines the ecosys_nml namelist settings
• set_tavg_nml adds ecosystem stream information to the POP base-model tavg_nml namelist
• tavg_contents adds ecosystem time-averaged output fields to the POP base-model tavg_contents file

Return to top

Customizing your ecosystem model ecosys_nml, tavg_nml, and tavg_contents settings

To modifiy any of the ecosys_nml namelist parameters, the ecosystem-related tavg_nml namelist parameters, or the ecosystem-related tavg_contents fields, you must modify the ecosystem model setup script. To do so, follow these three steps:

1. Put a copy of the ocn.ecosys.setup.csh script into your $CASE/SourceMods/src.pop2 directory:

   cp $CCSMROOT/models/ocn/pop2/input_templates/ocn.ecosys.setup.csh $CASE/SourceMods/src.pop2

2. Edit your copy of the ocn.ecosys.setup.csh script, eg:

   vi $CASE/SourceMods/src.pop2/ocn.ecosys.setup.csh

   as follows:

ecosys_nml namelist:

Go to the "else if ($command == namelist) then" block in your $CASE/SourceMods/src.pop2/ocn.ecosys.setup.csh script and make your changes.

tavg_nml settings:

Go to the "else if ($command == set_tavg_nml) then" block in your $CASE/SourceMods/src.pop2/ocn.ecosys.setup.csh script and make your changes.

In this block you can change the default tavg streams information (add streams, put all variables into one stream, change the default filenames of the ecosystem tavg output streams, etc). Note that the limitations of the base model apply here; in particular, you cannot have more than nine tavg output streams, total.

Also note that if you change the number of ecosystem tavg output streams in this namelist, you will also need to coordinate your changes in the tavg_contents block (see next section).

tavg_contents fields and/or streams:

Go to the "else if ($command == tavg_contents) then" block in your $CASE/SourceMods/src.pop2/ocn.ecosys.setup.csh script and make your changes.

Here you can remove ecosystem fields from your output files (just comment them out by changing the first three characters in the line to "# "). You can also add supported ecosystem fields (fields that have been defined in the ecosystem code via a call to subroutine define_tavg_field, such as the auto-generated fields) that are not included in the default. If the field is present in the ocn.ecosys.setup.csh script, you just need to uncomment it in the ocn.ecosys.setup.csh script and assign it to a valid tavg output stream. If the field is supported but does not appear in the ocn.ecosys.setup.csh script, you can add its name and assign it to a valid stream.

If the field is not supported, you will need to modify the POP base code in your $CASE/SourceMods/src.pop2 directory by adding appropriate calls to define_tavg_field and add the field to the tavg_contents file.

3. Run your CASE

Return to top

Changing the ecosys_parms_nml default settings

In order to change the ecosys_parms_nml default settings, you must edit the ecosys_parms.F90 file and build (or rebuild) your CASE. This can be accomplished in the following four steps:

1. Put a copy of the ecosys_parms.F90 file into your $CASE/SourceMods/src.pop2 directory, eg:

   cp $CCSMROOT/models/ocn/pop2/source/ecosys_parms.F90 $CASE/SourceMods/src.pop2

2. Edit the ecosys_parms_nml values in your copy, eg:

   vi $CASE/SourceMods/src.pop2/ecosys_parms.F90

3. Build the CASE interactively by issuing ./$CASE.build script on the command line in your $CASE directory
4. Run your CASE

NOTE: If you do not build the case after a change to the ecosys_parms.F90 file and before submitting your run script, the changes that you made to the ecosys_parms_nml values will not be in effect in your run.

Return to top