The CESM Ocean Ecosystem Model User's Guide
The CESM Ocean Ecosystem Model User's Guide
Nancy J. Norton
Keith Lindsay
National Center for Atmospheric Research
25 June 2010
Contents
- Introduction
- The ecosys_nml namelist
- The ecosys_parms_nml namelist
- Ecosystem model output
- Ecosystem model additions to the POP tavg_nml namelist settings
- Ecosystem model additions to the POP tavg_contents file
- 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
- Introduction
- 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.
Table: Ecosystem base-model namelist: ecosys_nml &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_factorauto-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
%filenameauto-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_factor1.0e-1 1.0e-1 scale factor for variable in the dust_flux input file (kg/m2/sec -> g/cm2/sec) iron_flux_input
%filenameauto-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_factor6.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
%filenameauto-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_factor1.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
%filenameauto-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_factor7.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
%filenameauto-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_factor7.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_varnameliron_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
- 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.
Table: Ecosystem namelist: ecosys_parms_nml &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)
- 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.
Table: Additional ecosystem time-averaged history fields 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 /
- 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.)
Table: Auto-generated extra-tracer time-averaged history fields (passive_tracers.F90) 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 /
Table: Auto-generated extra-tracer time-averaged history fields (advection.F90) 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 /
Table: Auto-generated extra-tracer time-averaged history fields (horizontal_mix.F90) 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 /
Table: Auto-generated extra-tracer time-averaged history fields (vertical_mix.F90) Name Units Description DIA_IMPVF_X tracer flux units Tracer Flux Across Bottom Face from Diabatic Implicit Vertical Mixing /
Table: Auto-generated extra-tracer time-averaged history fields (vmix_kpp.F90) Name Units Description KPP_SRC_X tracer tendency units Tracer tendency from KPP non local mixing term /
- The ocn.ecosystem.setup.csh script
- 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
- 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:
- Put a copy of the ocn.ecosys.setup.csh script into your $CASE/SourceMods/src.pop2 directory:
- Edit your copy of the ocn.ecosys.setup.csh script, eg:
ecosys_nml namelist:
tavg_nml settings:
tavg_contents fields and/or streams:
- Run your CASE
cp $CCSMROOT/models/ocn/pop2/input_templates/ocn.ecosys.setup.csh $CASE/SourceMods/src.pop2
vi $CASE/SourceMods/src.pop2/ocn.ecosys.setup.csh
as follows:
Go to the "else if ($command == namelist) then" block in your $CASE/SourceMods/src.pop2/ocn.ecosys.setup.csh script and make your changes.
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).
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.
Changing the ecosys_parms_nml default settings
- Put a copy of the ecosys_parms.F90 file into your $CASE/SourceMods/src.pop2 directory, eg:
- Edit the ecosys_parms_nml values in your copy, eg:
- Build the CASE interactively by issuing ./$CASE.build script on the command line in your $CASE directory
- Run your CASE
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.
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:
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:
cp $CCSMROOT/models/ocn/pop2/source/ecosys_parms.F90 $CASE/SourceMods/src.pop2
vi $CASE/SourceMods/src.pop2/ecosys_parms.F90
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.
2010-06-25