CanCPL namelist description
===========================

All of CanCPL's namelist options must ultimately be placed in the file ``nl_coupler_par`` at runtime. The description here is valid for CanESM v5.3+. The namelist for v5.1 is broadly similar but does not contain all of the same options.

main_coupler_par
----------------
- **env_runid**: The model's runid
- **windstress_remap**: The regridding option to use for windstress (default = ``bilinear``)
- **cpl_rs_abort_if_missing_field**: If true, error out if the restart file is missing a field (``.true.`` \| ``.false.``)
- **bulk_in_cpl**: If true, calculate fluxes within the coupler using the bulk formulae (``.true.`` \| ``.false.``)
- **zero_runoff_sent_to_ocean**: If true, runoff will be set to zero within the coupler (``.true.`` \| ``.false.``)
- **use_runoff_spreading**: If true, activate runoff_spreading (``.true.`` \| ``.false.``)
- **balance_hc_watermass**: If true, the heat fluxes associated with the water mass transfert get canceled by adjusting O_QnsMix (``.true.`` \| ``.false.``)
- **write_history**: If true, write coupler fields every step (``.true.`` \| ``.false.``)
- **yyg_correction_type**: When using gem (see use_gem), ``goddard_weighting`` or ``full_seam_ones`` are supported
- **use_routehandle_files**: If true, the coupler will produce the routing files at the first jobs and used them to initialize the regrid information for th next job. (``.true.`` \| ``.false.``)
- **cpl_river_route**: If true, use internal coupler river routing scheme (``.true.`` \| ``.false.``)
- **write_history_river**: If true, write coupler fields for rivers every step (``.true.`` \| ``.false.``)
-  **env_model**: An identifying string for the model name
-  **env_start**: An identifying string for the model start date
-  **sim_start_year**: \*
-  **sim_start_month**: \*
-  **sim_start_day**: \*
-  **sim_start_hour**: \*
-  **sim_start_min**: \*
-  **sim_stop_year**: \*
-  **sim_stop_month**: \*
-  **sim_stop_day**: \*
-  **sim_stop_hour**: \*
-  **sim_stop_min**: \*
-  **cpl_use_initial_conditions**: If true, the coupler is initialized from initial conditions\*
\*Set in cpl_prelude (changes with every resubmission)

comm_coupler_par
----------------

Options here are configuration parameters that are required across multiple programs (CanCPL, CanAM, and CanNEMO):

-  **couple_serial**: If true, the AGCM and ocean are stepped sequentially (``.true.`` \| ``.false.``)
-  **use_gem**: If true, expect the use of GEM dyn core (``.true.`` \| ``.false.``)
-  **atm_forcing_from_file**: False for ESM runs (forcing comes from ocean, True for AMIP (``.true.`` \| ``.false.``)
-  **use_nemo**: True for ESM runs, False for AMIP (``.true.`` \| ``.false.``)
-  **specified_bc_file**: Filename of specified boundary conditions file, if used
-  **specified_bc_year_offset**: (AMIP-only) Value added to the year in the specified boundary conditions (AMIP-only)
-  **specified_bc_type**: (AMIP-only) Define the TYPE of data that is fed to the AGCM for its bcs (1 = monthly climatology, 2 = daily climatology, 3 = multi-year monthly data, 4 = multi-year daily data
-  **cpl_verbosity**: Verbosity of CanCPL rank file output. 0 is mainly initialization information, 1 adds component model data transfer inforation, 2 adds all regrid information


comm_coupler_horz_dims
----------------------

The following variables define the common horizontal grid sizes within the coupler that are used. These are required across multiple programs (CanCPL, CanAM, and CanNEMO).

-  **nlon_a**: Number of longitudes on atmosphere grid, not including overlap (integer)
-  **nlat_a**: Number of latitudes on atmosphere grid (integer)
-  **olap_a**: Number of overlap longitudes on atmosphere grid (integer)
-  **nlon_o**: Number of longitudes on ocean grid, not including overlap (integer)
-  **nlat_o**: Number of latitudes on ocean grid (integer)
-  **olap_o**: Number of overlap longitudes on ocean grid (integer)
-  **nlon_i**: Number of longitudes on sea ice grid, not including overlap (integer)
-  **nlat_i**: Number of latitudes on sea ice grid (integer)
-  **olap_i**: Number of overlap longitudes on sea ice grid (integer)
-  **nlon_r**: Number of longitudes on river grid, not including overlap (integer)
-  **nlat_r**: Number of latitudes on river grid (integer)
- **olap_r**:  Number of overlap longitudes on river grid (integer)

variable_lists
--------------

List of variables to be passed to and from CanCPL each coupling cycling. 

FIELD SPECS: Coupler Var Name, CCC Name, Description, Units, Initialized Value, Grid Identifier, Var Use, Interpolation Method, Normalization Method, Use Src Mask, Use Dest Mask

Example: 

``atm_var_list(1) = "UFSO_atm_yin",  "UFSO", "Zonal Atm-Ocn Wind Stress", "N m-2", 0, "atm_yin", "send_to_cpl", "", "", .false., .false.``

NOTES: 
  - Var Use describes how this variable is used within CanCPL:
    - 'send_to_cpl'  : component sends during main communication step
    - 'rcv_from_cpl' : component receives during main communication step
    - 'misc'         : general catch all for other variable types
  - The last four columns only apply for variables that are received by components (i.e. use the rcv_from_cpl value)
  - order matters for ocn transfers - i.e. the ocean vars must be defined in the same order that NEMO expects to send/receive them (will be checked at runtime)