CESM Ocean Ecosystem Model User Guide
Nancy J. Norton
Keith Lindsay
NSF National Center for Atmospheric Research
25 June 2010
Table of contents
- Introduction
- The ecosys_nml namelist
- The ecosys_parms_nml namelist
- Ecosystem model output
- Auto-generated generic extra-tracer time-averaged history (tavg_contents) fields
- The ocn.ecosystem.setup.csh script
- Customizing your ecosystem model ecosys_nml, tavg_nml, and tavg_contents settings
- Customizing your ecosystem model ecosys_parms_nml settings
1. 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.
2. 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.
| &ecosys_nml | Default value | Valid values | Parameters used to initialize the ecosystem model |
|---|---|---|---|
| init_ecosys_option | auto-filled 1, based on CESM runtype | 'file', 'ccsm_startup', 'ccsm_continue', 'ccsm_branch', 'ccsm_hybrid' | option for initializing the ecosystem model |
| init_ecosys_init_file | auto-filled 1, based on grid resolution | 'same_as_TS' or any valid filename string ≤ 256 chars | ecosystem input initialization filename for the option init_ecosys_option = 'file' |
| init_ecosys_init_file_fmt | auto-filled 1 | 'bin', 'nc' | ecosystem initialization input file format suffix (binary or netCDF) |
| tracer_init_ext(:) %mod_varname |
'ALK', 'DIC', 'O2' | any supported tracer name | tracer variable name; tracer_init_ext is a derived type used to read tracers from a file |
| tracer_init_ext(:) %scale_factor |
auto-filled 1, based on the variable | any valid floating-point number | scale factor for the tracer (tracer_init_ext(:)%mod_varname) |
| lflux_gas_o2 | .true. | .true., .false. | controls the reading of gas flux forcing file |
| lflux_gas_co2 | .true. | .true., .false. | controls the reading of gas flux forcing file |
| locmip_k1_k2_bug_fix | auto-filled 1 | .true., .false. | if .true., apply the ocmip bug fix. if .false., maintain backwards compatability with previous cases. |
| atm_co2_opt | auto-filled 1, based upon $OCN_CO2_TYPE setting | 'const', 'drv_prog', 'drv_diag' | option for atmospheric CO2 concentration |
| atm_co2_const | auto-filled 1; set to CCSM_CO2_PPMV value | any valid floating point number | value of atmospheric CO2 (ppm, dry-air, 1 atm) |
| ecosys_tadvect_ctype | 'base_model' | 'base_model', or any valid advection type ('centered', 'upwind', 'lw_lim') | advection method for ecosystem tracers. Selecting 'base_model' results in using the same method as the base model. |
| gas_flux_forcing_opt | 'drv' | 'drv','file' | option for forcing gas fluxes. if 'drv', get forcing from CESM driver; if 'file', read from a file |
| lmarginal_seas | .true. | .true., .false. | if .true., ecosystem is active in marginal seas; if .false., it is not |
| lsource_sink | .true. | .true., .false. | if .true., compute time derivatives for ecosystem state variables; if .false., do not |
| comp_surf_avg_freq_opt | 'never' | 'never', 'nyear', 'nmonth' | choice for frequency of comp_surf_avg |
| comp_surf_avg_freq | 1 | integer | frequency value for comp_surf_avg_opt |
| use_nml_surf_vals | auto-filled 1, based upon runtype setting | .true., .false. | if .true., namelist surf values override values from restart file |
| surf_avg_dic_const | 1944.0 | valid floating-point number | value to be used when use_nml_surf_vals = .true. |
| surf_avg_alk_const | 2225.0 | valid floating-point number | value to be used when use_nml_surf_vals = .true. |
| ecosys_qsw_distrb_const | .false. | .true., .false. | if .true., the ecosystem model sees constant qsw (has no qsw diurnal cycle) |
| dust_flux_input %filename |
auto-filled 1, based upon grid resolution | string ≤ 256 chars | dust_flux input filename |
| dust_flux_input %file_fmt |
'nc' | 'bin', 'nc' | dust_flux input file format suffix (binary or netCDF) |
| dust_flux_input %file_varname |
'DSTSF' | 'DSTSF' | variable name in the dust_flux input file |
| dust_flux_input %scale_factor |
1.0e-1 | 1.0e-1 | scale factor for variable in the dust_flux input file (kg/m2/sec -> g/cm2/sec) |
| iron_flux_input %filename |
auto-filled 1, based upon grid resolution | string ≤ 256 chars | iron_flux input filename |
| iron_flux_input %file_fmt |
'nc' | 'bin', 'nc' | iron_flux input file format suffix (binary or netCDF) |
| iron_flux_input %file_varname |
'DSTSF' | 'DSTSF' | variable name in the iron_flux input file |
| iron_flux_input %scale_factor |
6.2668e4 | 6.2668e4 | scale factor for variable in the iron_flux input file (kg/m2/sec -> nmol/cm2/sec, 3.5% iron by weight) |
| fesed_flux_input %filename |
auto-filled 1, based upon grid resolution | string ≤ 256 chars | fesed_flux input filename |
| fesed_flux_input %file_fmt |
'nc' | 'bin', 'nc' | fesed_flux input file format suffix (binary or netCDF) |
| fesed_flux_input %file_varname |
'FESEDFLUXIN' | 'FESEDFLUXIN' | variable name in the fesed_flux input file |
| fesed_flux_input %scale_factor |
1.1574e-6 | 1.1574e-6 | scale factor for variable in the fesed_flux input file (umolFe/m2/day -> nmolFe/cm2/s) |
| lecovars_full_depth_tavg | .false. | .true., .false. | if .true., write ecosystem tavg variables at all depths; if .false., write ecosystem variables to a depth of 150m |
| lrest_po4 | .false. | .true., .false. | controls restoring on PO4 |
| lrest_no3 | .false. | .true., .false. | controls restoring on NO3 |
| lrest_sio3 | .false. | .true., .false. | controls restoring on SiO3 |
| rest_time_inv_surf | 0.0 | inverse restoring timescale at surface | |
| rest_time_inv_deep | 0.0 | inverse restoring timescale at depth | |
| rest_z0 | 1000.0 | shallow end of transition regime | |
| rest_z1 | 2000.0 | deep end of transition regime | |
| lnutr_variable_restore | .false. | .true., .false. | geographically varying nutrient restoring |
| ndep_data_type | auto-filled 1, based on $OCN_TRANSIENT setting | 'monthly-calendar', 'shr_stream', 'none' | type of ndep forcing |
| nox_flux_monthly_input %filename |
auto-filled 1, based on $OCN_TRANSIENT setting | 'unknown', or any valid filename ≤ 256 chars | namelist input for nox_flux_monthly: file name |
| nox_flux_monthly_input %file_fmt |
'nc' | 'bin', 'nc' | namelist input for nox_flux_monthly: file format (binary or netCDF) |
| nox_flux_monthly_input %file_varname |
'NOy_deposition' or 'nox_flux', depending on $OCN_TRANSIENT setting | 'NOy_deposition', 'nox_flux', or any valid filename ≤ 256 chars | namelist input for nox_flux_monthly: variable name on the file |
| nox_flux_monthly_input %scale_factor |
7.1429e+06 (kgN/m2/sec -> nmolN/cm2/sec or 1.0, depending on $OCN_TRANSIENT setting | any scientifically valid floating-point number | nox_flux_monthly scale factor for the specified file_varname |
| nhy_flux_monthly_input %filename |
auto-filled 1, based on $OCN_TRANSIENT setting, or 'unknown' | 'unknown', or any valid filename ≤ 256 chars | nhy_flux_monthly_input file name |
| nhy_flux_monthly_input %file_fmt |
'nc' | 'bin', 'nc' | namelist input for nhy_flux_monthly_input: file format (binary or netCDF) |
| nhy_flux_monthly_input %file_varname |
'NHx_deposition' or 'nhy_flux', depending on $OCN_TRANSIENT setting | 'NHx_deposition', 'nhy_flux', or any valid filename ≤ 256 chars | namelist input for nhy_flux_monthly_input: variable name on the file |
| nhy_flux_monthly_input %scale_factor |
7.1429e+06 (kgN/m2/sec -> nmolN/cm2/sec) or 1.0, depending on $OCN_TRANSIENT setting | any scientifically valid floating-point number | namelist input for nhy_flux_monthly_input: scale factor for nhy_flux_monthly_input %file_varname |
| liron_patch | .false. | .true., .false. | flag for iron patch fertilization |
| gas_flux_forcing_opt | 'drv' | 'drv', 'file' | option for forcing gas fluxes. if 'drv', fluxes are from coupler; if 'file', fluxes are read from a file |
| / |
1 automatically set by the ocn.ecosys.setup.csh script
3. 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.
| &ecosys_parms_nml | Default value | Parameters used to initialize the ecosystem model |
|---|---|---|
| parm_Fe_bioavail | 0.02 | fraction of Fe flux that is bioavailable |
| parm_o2_min | 4.0 | minimum O2 needed for production and consumption (nmol/cm3) |
| parm_o2_min_delta | 2.0 | width of minimum O2 range (nmol/cm3) |
| parm_no3_min | 110.0 | minimum NO3 needed for denitrification (mmol/m3 ) |
| parm_kappa_nitrif | 0.06*dps2 | nitrification inverse time constant (1/sec) |
| parm_nitrif_par_lim | 5.0 | PAR limit for nitrification (W/m2) |
| parm_z_umax_0 | 2.5 * dps2 | maximum zoo growth rate on sphyto at Tref 3 (1/sec) |
| parm_diat_umax_0 | 1.95 * dps2 | maximum zoo growth rate on diat at Tref 3 (1/sec) |
| parm_z_mort_0 | 0.08 * dps2 | zoo linear mort rate (1/sec) |
| parm_z_mort2_0 | 0.42 * dps2 | zoo quad mort rate (1/sec/((mmol C/m3)) |
| parm_sd_remin_0 | 0.006667 * dps2 | small detrital remineralization rate (1/sec) |
| parm_sp_kNO3 | 0.5 | sphyto nitrate half saturation coefficient (mmol N/m3) |
| parm_diat_kNO3 | 2.5 | diatom nitrate half saturation coefficient (mmol N/m3) |
| parm_sp_kNH4 | 0.01 | sphyto ammonium half saturation coefficient (mmol N/m3) |
| parm_diat_kNH4 | 0.1 | diatom ammonium half saturation coefficient (mmol N/m3) |
| parm_sp_kFe | 0.03e-3 | sphyto iron half saturation coefficient (nmol Fe/m3) |
| parm_diat_kFe | 0.08e-3 | diatom iron half saturation coefficient (nmol Fe/m3) |
| parm_diat_kSiO3 | 1.0 | diatom si half saturation coefficient (mmol SiO3/m3) |
| parm_sp_kPO4 | 0.01 | sphyto PO4 uptake (mmol P/m3) |
| parm_diat_kPO4 | 0.1 | diatom PO4 uptate (mmol P/m3) |
| parm_z_grz | 1.0 | grazing coefficient for small phyto (mmol C/m3) |
| parm_alphaChl | 0.3 * dps2 | initial slope of P_I curve (GD98) (mmol C m2/(mg Chl W sec)) |
| parm_alphaChlsp | 0.34 * dps2 | initial slope of P_I curve (GD98) (mmol C m2/(mg Chl W sec)) |
| parm_labile_ratio | 0.65 | fraction of loss to DOC that routed directly to DIC (non-dimensional) |
| parm_alphaDiaz | 0.17 * dps2 | chl. spec. init. slope of diaz. P_I curve |
| parm_diaz_umax_0 | 0.9 * dps2 | maximum zoo growth rate on diazotrophs at Tref (1/sec) |
| / |
2 dps = number of days in a second
3 Tref = 30.0 reference temperature (deg. C)
4. 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'.
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.
| Output stream number | Name | Units | Description |
|---|---|---|---|
| $s1 | ECOSYS_ATM_PRESS | atmospheres | Atmospheric Pressure for ecosys fluxes |
| $s1 | ECOSYS_IFRAC | fraction | Ice Fraction for ecosys fluxes |
| $s2 | ECOSYS_IFRAC_2 | fraction | Ice Fraction for ecosys fluxes (same as ECOSYS_IFRAC; support for second output stream) |
| $s1 | ECOSYS_XKW | cm/s | XKW for ecosys fluxes |
| $s2 | ECOSYS_XKW_2 | cm/s | XKW for ecosys fluxes (same as ECOSYS_XKW; support for second output stream) |
| $s1 | SCHMIDT_O2 | none | O2 Schmidt Number |
| $s1 | SCHMIDT_CO2 | none | CO2 Schmidt Number |
| $s1 | IRON_FLUX | nmol/cm2/s | Iron Flux |
| $s1 | NOx_FLUX | nmol/cm2/s | Flux of NOx from Atmosphere |
| $s1 | NHy_FLUX | nmol/cm2/s | Flux of NHy from Atmosphere |
| $s1 | PH | none | Surface pH |
| $s1 | O2SAT | mmol/m3 | O2 Saturation |
| $s1 | STF_O2 | mmol/m3 cm/s | Dissolved Oxygen Surface Flux |
| $s2 | STF_O2_2 | mmol/m3 cm/s | Dissolved Oxygen Surface Flux; (same as STF_O2; support for second output stream) |
| $s1 | CO2STAR | mmol/m3 | CO2 Star |
| $s1 | DCO2STAR | mmol/m3 | D CO2 Star |
| $s1 | pCO2SURF | ppmv | surface pCO2 |
| $s1 | DpCO2 | ppmv | D pCO2 |
| $s2 | DpCO2_2 | ppmv | D pCO2 (same as DpCO2; support for second output stream) |
| $s1 | FG_CO2 | mmol/m3 cm/s | DIC Surface Gas Flux |
| $s2 | FG_CO2_2 | mmol/m3 cm/s | DIC Surface Gas Flux (same as FG_CO2; support for second output stream) |
| $s1 | ATM_CO2 | ppmv | Atmospheric CO2 |
| $s1 | FvPER_DIC | mmol/m3 cm/s | Dissolved Inorganic Carbon Virtual Surface Flux, PER |
| $s1 | FvICE_DIC | mmol/m3 cm/s | Dissolved Inorganic Carbon Virtual Surface Flux, ICE |
| $s1 | FvPER_ALK | meq/m3 cm/s | Alkalinity Virtual Surface Flux, PER |
| $s1 | FvICE_ALK | meq/m3 cm/s | Alkalinity Virtual Surface Flux, ICE |
| $s1 | PO4 | mmol/m3 | Dissolved Inorganic Phosphate |
| $s1 | NO3 | mmol/m3 | Dissolved Inorganic Nitrate |
| $s1 | SiO3 | mmol/m3 | Dissolved Inorganic Silicate |
| $s1 | NH4 | mmol/m3 | Dissolved Ammonia |
| $s1 | Fe | mmol/m3 | Dissolved Inorganic Iron |
| $s1 | O2 | mmol/m3 | Dissolved Oxygen |
| $s1 | O2_ZMIN | mmol/m3 | Vertical Minimum of O2 |
| $s1 | O2_ZMIN_DEPTH | cm | Depth of Vertical Minimum of O2 |
| $s1 | O2_PRODUCTION | mmol/m3/s | O2 Production |
| $s1 | O2_CONSUMPTION | mmol/m3/s | O2 Consumption |
| $s1 | AOU | mmol/m3 | Apparent O2 Utilization |
| $s1 | DIC | mmol/m3 | Dissolved Inorganic Carbon |
| $s1 | J_DIC | mmol/m3/s | Dissolved Inorganic Carbon Source Sink Term |
| $s1 | ALK | meq/m3 | Alkalinity |
| $s1 | H2CO3 | mmol/m3 | Carbonic Acid Concentration |
| $s1 | HCO3 | mmol/m3 | Bicarbonate Ion Concentration |
| $s1 | CO3 | mmol/m3 | Carbonate Ion Concentration |
| $s1 | pH_3D | none | pH |
| $s1 | co3_sat_calc | mmol/m3 | CO3 concentration at calcite saturation |
| $s1 | zsatcalc | cm | Calcite Saturation Depth |
| $s1 | co3_sat_arag | mmol/m3 | CO3 concentration at aragonite saturation |
| $s1 | zsatarag | cm | Aragonite Saturation Depth |
| $s1 | DOC | mmol/m3 | Dissolved Organic Carbon |
| $s1 | DOC_prod | mmol/m3/s | DOC Production |
| $s1 | DOC_remin | mmol/m3/s | DOC Remineralization |
| $s1 | spC | mmol/m3 | Small Phytoplankton Carbon |
| $s1 | spChl | mg/m3 | Small phytoplankton Chlorophyll |
| $s1 | spCaCO3 | mmol/m3 | Small Phytoplankton CaCO3 |
| $s1 | diatC | mmol/m3 | Diatom Carbon |
| $s1 | diatChl | mg/m3 | Diatom Chlorophyll |
| $s1 | zooC | mmol/m3 | Zooplankton Carbon |
| $s1 | spFe | mmol/m3 | Small Phytoplankton Iron |
| $s1 | diatSi | mmol/m3 | Diatom Silicon |
| $s1 | diatFe | mmol/m3 | Diatom Iron |
| $s1 | diazC | mmol/m3 | Diazotroph Carbon |
| $s1 | diazChl | mg/m3 | Diazotroph Chlorophyll |
| $s1 | diazFe | mmol/m3 | Diazotroph Iron |
| $s1 | DON | mmol/m3 | Dissolved Organic Nitrogen |
| $s1 | DOFe | mmol/m3 | Dissolved Organic Iron |
| $s1 | DOP | mmol/m3 | Dissolved Organic Phosphorus |
| $s1 | graze_sp | mmol/m3/s | Small Phyto Grazing |
| $s1 | graze_diat | mmol/m3/s | Diatom Grazing |
| $s1 | graze_diaz | mmol/m3/s | Diazotroph Grazing |
| $s1 | sp_agg | mmol/m3/s | Small Phyto Aggregate |
| $s1 | diat_agg | mmol/m3/s | Diatom Aggregate |
| $s1 | photoC_sp | mmol/m3/s | Small Phyto C Fixation |
| $s1 | CaCO3_form | mmol/m3/s | CaCO3 Formation |
| $s1 | photoC_diat | mmol/m3/s | Diatom C Fixation |
| $s1 | photoC_diaz | mmol/m3/s | Diaz C Fixation |
| $s1 | photoC_NO3_sp | mmol/m3/s | Small Phyto C Fixation from NO3 |
| $s1 | photoC_NO3_diat | mmol/m3/s | Diatom C Fixation from NO3 |
| $s1 | photoC_NO3_diaz | mmol/m3/s | Diaz C Fixation from NO3 |
| $s1 | Fe_scavenge | mmol/m3/s | Iron Scavenging |
| $s1 | Fe_scavenge_rate | 1/year | Iron Scavenging Rate |
| $s1 | diaz_Nfix | mmol/m3/s | Diaz N Fixation |
| $s1 | bSi_form | mmol/m3/s | Diatom Si Uptake |
| $s1 | NITRIF | mmol/m3/s | Nitrification |
| $s1 | DENITRIF | mmol/m3/s | Denitrification |
| $s1 | POC_PROD | mmol/m3/s | POC Production |
| $s1 | CaCO3_PROD | mmol/m3/s | CaCO3 Production |
| $s1 | SiO2_PROD | mmol/m3/s | SiO2 Production |
| $s1 | P_iron_PROD | mmol/m3/s | P_iron Production |
| $s1 | POC_FLUX_IN | mmol/m3 cm/s | POC Flux into Cell |
| $s1 | CaCO3_FLUX_IN | mmol/m3 cm/s | CaCO3 flux into cell |
| $s1 | SiO2_FLUX_IN | mmol/m3 cm/s | SiO2 Flux into Cell |
| $s1 | P_iron_FLUX_IN | mmol/m3 cm/s | P_iron Flux into Cell |
| $s1 | PAR_avg | W/m2 | PAR Average over Model Cell |
| $s1 | sp_Fe_lim | none | Small Phyto Fe Limitation |
| $s1 | diat_Fe_lim | none | Diatom Fe Limitation |
| $s1 | diaz_Fe_lim | none | Diaz Fe Limitation |
| $s1 | sp_N_lim | none | Small Phyto N Limitation |
| $s1 | diat_N_lim | none | Diatom N Limitation |
| $s1 | sp_PO4_lim | none | Small Phyto PO4 Limitation |
| $s1 | diat_PO4_lim | none | Diatom PO4 Limitation |
| $s1 | diaz_P_lim | none | Diaz PO4 Limitation |
| $s1 | diat_SiO3_lim | none | Diatom SiO3 Limitation |
| $s1 | sp_light_lim | none | Small Phyto Light Limitation |
| $s1 | diat_light_lim | none | Diatom Light Limitation |
| $s1 | diaz_light_lim | none | Diaz Light Limitation |
| $s1 | DON_prod | mmol/m3/s | DON Production |
| $s1 | DOFe_prod | mmol/m3/s | DOFe Production |
| $s1 | DOP_prod | mmol/m3/s | DOP Production |
| $s1 | sp_loss | mmol/m3/s | Small Phyto Loss |
| $s1 | diat_loss | mmol/m3/s | Diatom Loss |
| $s1 | zoo_loss | mmol/m3/s | Zooplankton Loss |
| $s1 | diaz_loss | mmol/m3/s | Diaz Loss |
| $s1 | Jint_100m_DIC | mmol/m3 cm/s | Dissolved Inorganic Carbon Source Sink Term Vertical Integral, 0-100m |
| $s1 | Jint_100m_NO3 | mmol/m3 cm/s | Dissolved Inorganic Nitrate Source Sink Term Vertical Integral, 0-100m |
| $s1 | Jint_100m_NH4 | mmol/m3 cm/s | Dissolved Ammonia Source Sink Term Vertical Integral, 0-100m |
| $s1 | Jint_100m_PO4 | mmol/m3 cm/s | Dissolved Inorganic Phosphate Source Sink Term Vertical Integral, 0-100m |
| $s1 | Jint_100m_Fe | mmol/m3 cm/s | Dissolved Inorganic Iron Source Sink Term Vertical Integral, 0-100m |
| $s1 | Jint_100m_SiO3 | mmol/m3 cm/s | Dissolved Inorganic Silicate Source Sink Term Vertical Integral, 0-100m |
| $s1 | Jint_100m_ALK | meq/m3 cm/s | Alkalinity Source Sink Term Vertical Integral, 0-100m |
| $s1 | Jint_100m_O2 | mmol/m3 cm/s | Dissolved Oxygen Source Sink Term Vertical Integral, 0-100m |
| $s1 | Jint_100m_DOC | mmol/m3 cm/s | Dissolved Organic Carbon Source Sink Term Vertical Integral, 0-100m |
| $s1 | tend_zint_100m_DIC | mmol/m3 cm/s | Dissolved Inorganic Carbon Tendency Vertical Integral, 0-100m |
| $s1 | tend_zint_100m_NO3 | mmol/m3 cm/s | Dissolved Inorganic Nitrate Tendency Vertical Integral, 0-100m |
| $s1 | tend_zint_100m_NH4 | mmol/m3 cm/s | Dissolved Ammonia Tendency Vertical Integral, 0-100m |
| $s1 | tend_zint_100m_PO4 | mmol/m3 cm/s | Dissolved Inorganic Phosphate Tendency Tendency Vertical Integral, 0-100m |
| $s1 | tend_zint_100m_Fe | mmol/m3 cm/s | Dissolved Inorganic Iron Tendency Vertical Integral, 0-100m |
| $s1 | tend_zint_100m_SiO3 | mmol/m3 cm/s | Dissolved Inorganic Silicate Tendency Vertical Integral, 0-100m |
| $s1 | tend_zint_100m_ALK | meq/m3 cm/s | Alkalinity Tendency Vertical Integral, 0-100m |
| $s1 | tend_zint_100m_O2 | mmol/m3 cm/s | Dissolved Oxygen Tendency Vertical Integral, 0-100m |
| $s1 | tend_zint_100m_DOC | mmol/m3 cm/s | Dissolved Organic Carbon Tendency Vertical Integral, 0-100m |
| $s2 | photoC_sp_zint | mmol/m3 cm/s | Small Phyto C Fixation Vertical Integral |
| $s2 | CaCO3_form_zint | mmol/m3 cm/s | CaCO3 Formation Vertical Integral |
| $s2 | photoC_diaz_zint | mmol/m3 cm/s | Diaz C Fixation Vertical Integral |
| $s2 | photoC_diat_zint | mmol/m3 cm/s | Diatom C Fixation Vertical Integral |
| $s1 | photoC_NO3_sp_zint | mmol/m3 cm/s | Small Phyto C Fixation from NO3 Vertical Integral |
| $s1 | photoC_NO3_diat_zint | mmol/m3 cm/s | Diatom C Fixation from NO3 Vertical Integral |
| $s1 | photoC_NO3_diaz_zint | mmol/m3 cm/s | Diaz C Fixation from NO3 Vertical Integral |
| $s2 | spC_zint_100m | mmol/m3 cm | Small Phytoplankton Carbon 0-100m Vertical Integral |
| $s2 | spCaCO3_zint_100m | mmol/m3 cm | Small Phytoplankton CaCO3 0-100m Vertical Integral |
| $s2 | diazC_zint_100m | mmol/m3 cm | Diazotroph Carbon 0-100m Vertical Integral |
| $s2 | diatC_zint_100m | mmol/m3 cm | Diatom Carbon 0-100m Vertical Integral |
| $s2 | zooC_zint_100m | mmol/m3 cm | Zooplankton Carbon 0-100m Vertical Integral |
| $s2 | spChl_SURF | mg/m3 | Small phytoplankton Chlorophyll Surface Value |
| $s2 | diazChl_SURF | mg/m3 | Diazotroph Chlorophyll Surface Value |
| $s2 | diatChl_SURF | mg/m3 | Diatom Chlorophyll Surface Value |
| $s3 | J_NO3 | mmol/m3/s | Dissolved Inorganic Nitrate Source Sink Term |
| $s3 | J_NH4 | mmol/m3/s | Dissolved Ammonia Source Sink Term |
| $s3 | J_PO4 | mmol/m3/s | Dissolved Inorganic Phosphate Source Sink Term |
| $s3 | J_Fe | mmol/m3/s | Dissolved Inorganic Iron Source Sink Term |
| $s3 | J_SiO3 | mmol/m3/s | Dissolved Inorganic Silicate Source Sink Term |
| $s3 | J_ALK | meq/m3/s | Alkalinity Source Sink Term |
| $s3 | UE_O2 | mmol/m3/s | O2 Flux in grid-x direction |
| $s3 | VN_O2 | mmol/m3/s | O2 Flux in grid-y direction |
| $s3 | WT_O2 | mmol/m3/s | O2 Flux Across Top Face |
| $s3 | KPP_SRC_O2 | mmol/m3/s | O2 tendency from KPP non local mixing term |
| $s3 | DIA_IMPVF_O2 | mmol/m3 cm/s | O2 Flux Across Bottom Face from Diabatic Implicit Vertical Mixing |
| $s3 | HDIFE_O2 | mmol/m3/s | O2 Horizontal Diffusive Flux in grid-x direction |
| $s3 | HDIFN_O2 | mmol/m3/s | O2 Horizontal Diffusive Flux in grid-y direction |
| $s3 | HDIFB_O2 | mmol/m3/s | O2 Horizontal Diffusive Flux across Bottom Face |
| $s3 | UE_DOC | mmol/m3/s | DOC Flux in grid-x direction |
| $s3 | VN_DOC | mmol/m3/s | DOC Flux in grid-y direction |
| $s3 | WT_DOC | mmol/m3/s | DOC Flux Across Top Face |
| $s3 | DIA_IMPVF_DOC | mmol/m3 cm/s | DOC Flux Across Bottom Face from Diabatic Implicit Vertical Mixing |
| $s3 | HDIFE_DOC | mmol/m3/s | DOC Horizontal Diffusive Flux in grid-x direction |
| $s3 | HDIFN_DOC | mmol/m3/s | DOC Horizontal Diffusive Flux in grid-y direction |
| $s3 | HDIFB_DOC | mmol/m3/s | DOC Horizontal Diffusive Flux across Bottom Face |
| $s3 | UE_DIC | mmol/m3/s | DIC Flux in grid-x direction |
| $s3 | VN_DIC | mmol/m3/s | DIC Flux in grid-y direction |
| $s3 | WT_DIC | mmol/m3/s | DIC Flux Across Top Face |
| $s3 | KPP_SRC_DIC | mmol/m3/s | DIC tendency from KPP non local mixing term |
| $s3 | DIA_IMPVF_DIC | mmol/m3 cm/s | DIC Flux Across Bottom Face from Diabatic Implicit Vertical Mixing |
| $s3 | HDIFE_DIC | mmol/m3/s | DIC Horizontal Diffusive Flux in grid-x direction |
| $s3 | HDIFN_DIC | mmol/m3/s | DIC Horizontal Diffusive Flux in grid-y direction |
| $s3 | HDIFB_DIC | mmol/m3/s | DIC Horizontal Diffusive Flux across Bottom Face |
| $s3 | UE_Fe | mmol/m3/s | Fe Flux in grid-x direction |
| $s3 | VN_Fe | mmol/m3/s | Fe Flux in grid-y direction |
| $s3 | WT_Fe | mmol/m3/s | Fe Flux Across Top Face |
| $s3 | KPP_SRC_Fe | mmol/m3/s | Fe tendency from KPP non local mixing term |
| $s3 | DIA_IMPVF_Fe | mmol/m3 cm/s | Fe Flux Across Bottom Face from Diabatic Implicit Vertical Mixing |
| $s3 | HDIFE_Fe | mmol/m3/s | Fe Horizontal Diffusive Flux in grid-x direction |
| $s3 | HDIFN_Fe | mmol/m3/s | Fe Horizontal Diffusive Flux in grid-y direction |
| $s3 | HDIFB_Fe | mmol/m3/s | Fe Horizontal Diffusive Flux across Bottom Face |
| inactive | PV_O2 | cm/s | PV_O2 |
| inactive | PV_CO2 | cm/s | CO2 Piston Velocity |
| inactive | DUST_FLUX | g/cm2/s | Dust Flux |
| inactive | PO4_RESTORE | mmol/m3 | PO4 Restoring |
| inactive | NO3_RESTORE | mmol/m3 | NO3 Restoring |
| inactive | SiO3_RESTORE | mmol/m3 | SiO3 Restoring |
| inactive | POC_REMIN | mmol/m3/s | POC Remineralization |
| inactive | CaCO3_REMIN | mmol/m3/s | CaCO3 Remineralization |
| inactive | SiO2_REMIN | mmol/m3/s | SiO2 Remineralization |
| inactive | dust_FLUX_IN | ng/s/m2 | Dust Flux into Cell |
| inactive | dust_REMIN | mmol/m3/s | Dust Remineralization |
| inactive | P_iron_REMIN | mmol/m3/s | P_iron Remineralization |
| inactive | graze_TOT | mmol/m3/s | Total Grazing |
| inactive | photoC_TOT | mmol/m3/s | Total C Fixation |
| inactive | photoC_TOT_zint | mmol/m3 cm/s | Total C Fixation Vertical Integral |
| inactive | photoC_TOT_zint | mmol/m3 cm/s | Total C Fixation Vertical Integral |
| inactive | photoC_NO3_TOT | mmol/m3/s | Total C Fixation from NO3 |
| inactive | photoC_NO3_TOT_zint | mmol/m3 cm/s | Total C Fixation from NO3 Vertical Integral |
| inactive | photoC_NO3_TOT_zint | mmol/m3 cm/s | Total C Fixation from NO3 Vertical Integral |
| inactive | DON_remin | mmol/m3/s | DON Remineralization |
| inactive | DOFe_remin | mmol/m3/s | DOFe Remineralization |
| inactive | DOP_remin | mmol/m3/s | DOP Remineralization |
| inactive | photoFe_sp | mmol/m3/s | Small Phyto Fe Uptake |
| inactive | photoFe_diat | mmol/m3/s | Diatom Fe Uptake |
| inactive | photoFe_diaz | mmol/m3/s | Diaz Fe Uptake |
| / |
5. 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.)
| Name | Units | Description |
|---|---|---|
| X | tracer units | Tracer |
| X_SQR | (tracer units)2 | Tracer squared |
| X_SURF | tracer units | Tracer Surface Value |
| X_zint_100m | tracer units cm | Tracer 0-100m Vertical Integral |
| J_X | tracer tendency units | Tracer Source Sink Term |
| Jint_X | tracer flux units | Tracer Source Sink Term Vertical Integral |
| Jint_100m_X | tracer flux units | Tracer Source Sink Term Vertical Integral, 0-100m |
| tend_zint_100m_X | tracer flux units | Tracer Tendency Vertical Integral, 0-100m |
| STF_X | tracer flux units | Tracer Surface Flux |
| RESID_X | tracer flux units | Tracer Residual Surface Flux |
| FvPER_X | tracer flux units | Tracer Virtual Surface Flux, PER |
| FvICE_X | tracer flux units | Tracer Virtual Surface Flux, ICE |
| / |
| Name | Units | Description |
|---|---|---|
| UE_X | tracer tendency units | Tracer Flux in grid-x direction |
| VN_X | tracer tendency units | Tracer Flux in grid-y direction |
| WT_X | tracer tendency units | Tracer Flux Across Top Face |
| ADV_X | tracer flux units | Vertically-Integrated Tracer Advection Tendency |
| / |
| Name | Units | Description |
|---|---|---|
| HDIFE_X | tracer tendency units | Tracer Horizontal Diffusive Flux in grid-x direction |
| HDIFN_X | tracer tendency units | Tracer Horizontal Diffusive Flux in grid-y direction |
| HDIFB_X | tracer tendency units | Tracer Horizontal Diffusive Flux across Bottom Face |
| / |
| Name | Units | Description |
|---|---|---|
| DIA_IMPVF_X | tracer flux units | Tracer Flux Across Bottom Face from Diabatic Implicit Vertical Mixing |
| / |
| Name | Units | Description |
|---|---|---|
| KPP_SRC_X | tracer tendency units | Tracer tendency from KPP non local mixing term |
| / |
6. 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
7. 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
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.