.. _cesm-attributes:

=======================
 CMEPS CESM attributes
=======================

The following *additional* attributes are required for CESM model applications.

General
--------------

**diro**, **logfile**
  Specifies the full pathname of the directory and filename of the directory and file name for mediator log output.
  For CESM this is determine in the attribute group ``MED_modelio`` that is generated by the CIME case control system.

**flds_i2o_per_cat**
  if true, select per ice thickness category fields are passed to the ocean.

Toggle for active compoenents
-----------------------------

**ATM_model**, **GLC_model**, **ICE_model**, **LND_model**, **ROF_model**, **OCN_model**, **WAV_model**
  In CESM, stub components are still used. These attributes determine if the component is a stub component and sets the
  mediator present flag for that component to ``false``.

Mediator Mapping file attributes
--------------------------------

  If a mapping file value is set to ``unset``, then CMEPS will create an online route handle instead.

**ice2atm_fmapname**, **ice2atm_smapname**
  ice -> atm fluxes and state mapping files
**lnd2atm_fmapname**, **lnd2atm_smapname**
  land -> atm fluxes and state mapping files
**ocn2atm_smapname**, **ocn2atm_fmapname**
  ocean -> atm fluxes and state mapping files
**atm2lnd_fmapname**, **atm2lnd_smapname**
  atm -> land fluxes and state mapping files
**atm2ice_fmapname**, **atm2ice_smapname**, **atm2ice_vmapname**
  atmosphere -> sea-ice fluxes, state, and velocities
**atm2ocn_fmapname**, **atm2ocn_smapname**, **atm2ocn_vmapname**
  atmosphere -> ocean fluxes, state, and velocities
**rof2lnd_fmapname**
  river -> land flux mapping file
**glc2lnd_fmapname**, **glc2lnd_smapname**
  land-ice -> land fluxes and state mapping files
**glc2ice_rmapname**
  "smoothed" land-ice -> sea-ice liquid mapping file
**glc2ocn_liq_rmapname**, **glc2ocn_ice_rmapname**
  "smoothed" land-ice -> ocean liquid and ice mapping files
**rof2ocn_liq_rmapname**, **rof2ocn_ice_rmapname**
  "smoothed" river -> ocean liquid and ice mapping file
**wav2ocn_smapname**
  wave -> ocean state mapping file
**lnd2rof_fmapname**
  land -> river flux mapping file
**lnd2glc_fmapname**, **lnd2glc_smapname**
  land -> land-ice flux and state mapping file
**atm2wav_smapname**, **ice2wav_smapname**, **ocn2wav_smapname**
  atmosphere -> wave, ice -> wave and ocean -> wave state mapping files

**mapuv_with_cart3d**
  used for atm->ocn and atm-ice mapping of u and v
  if true, rotate u,v to 3d cartesian space, map from src->dest, then rotate back

Mediator ocean albedo attributes
--------------------------------

  The following are used by CMEPS to calculate ocean albedoes in used in ``med_phases_ocnalb_mod.F90``

**start_type**
  Determines if start type of the run. The currently supported values are ``startup``, ``continue`` and ``branch``.
**orb_mode**
  orbital model setting configured. The supported values are::

    fixed_year:  uses the orb_iyear and other orb inputs are ignored.  In
    this mode, the orbital parameters are constant and based on the year.

    variable_year: uses the orb_iyear and orb_iyear_align.  In this mode,
    the orbital parameters vary as the model year advances and the model
    year orb_iyear_align has the equivalent orbital year of orb_iyear.

    fixed_parameters: uses the orb_eccen, orb_mvelp, and orb_obliq to set
    the orbital parameters which then remain constant through the model integration

**orb_iyear**
  year of orbit, used when orb_mode is fixed_year or variable_year
**orb_iyear_align**
  model year associated with orb_iyear when orb_mode is variable_year
**orb_obliq**
  obliquity of orbit in degrees, used when orb_mode is fixed_parameters
**orb_eccen**
  eccentricity of orbit, used when orb_mode is fixed_parameters.
**orb_mvelp**
 location of vernal equinox in longitude degrees, used when orb_mode is fixed_parameters

Mediator land-ice component attribtes
-------------------------------------

**glc_renormalize_smb**
  Whether to renormalize the surface mass balance (smb) sent from lnd to glc so that the
  global integral on the glc grid agrees with the global integral on the lnd grid.

  Unlike most fluxes, smb is remapped with bilinear rather than conservative mapping weights,
  so this option is needed for conservation. However, conservation is not required in many
  cases, since we often run glc as a diagnostic (one-way-coupled) component.

  Allowable values are:
  ``on``: always do this renormalization

  ``off``: never do this renormalization (see WARNING below)

  ``on_if_glc_coupled_fluxes``: Determine at runtime whether to do this renormalization.
  Does the renormalization if we're running a two-way-coupled glc that sends fluxes
  to other components (which is the case where we need conservation).
  Does NOT do the renormalization if we're running a one-way-coupled glc, or if
  we're running a glc-only compset (T compsets).
  (In these cases, conservation is not important.)
  Only used if running with a prognostic GLC component.
  WARNING: Setting this to 'off' will break conservation when running with an
  evolving, two-way-coupled glc.

**glc_avg_period**
  Period at which coupler averages fields sent to GLC (the land-ice component).
  This supports doing the averaging to GLC less frequently than GLC is called
  (i.e., separating the averaging frequency from the calling frequency).
  This is useful because there are benefits to only averaging the GLC inputs
  as frequently as they are really needed (yearly for CISM), but GLC needs to
  still be called more frequently than that in order to support mid-year restarts.
  Setting glc_avg_period to 'glc_coupling_period' means that the averaging is
  done exactly when the GLC is called (governed by GLC_NCPL).

**glc_cpl_dt**
  glc coupling interval in seconds