Versions Compared

Old Version 11

changes.mady.by.user Katherine Calvin

Saved on

compared with

New Version Current

changes.mady.by.user Katherine Calvin

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

The Design Document page provides a description of the algorithms, implementation and planned testing including unit, verification, validation and performance testing. Please read  Step 1.3 Performance Expectations that explains feature documentation requirements from the performance group point of view. 

...

Submodules: GCAM, and the other parts of the IAC code, are added via submodule. To minimize the amount of code reorganization, we technically have two submodules. The e3sm-integration branch of the main GCAM code (https://github.com/JGCRI/gcam-core) is included as a submodule to the https://github.com/E3SM-Project/giac repository, which is then submoduled into E3SM. giac includes some coupling code, in particular, the code to downscale, harmonize, and create land surface files. Ideally, we would include all of the relevant GCAM post-processing and coupling code in a single repository, but that isn't practical right now so we are using nested submodules.


IAC component implementation

  1. Coupler modifications
    1. cesm_comp_mod.F90
      1. Set up iac vars,  comp type, etc.
      2. modify general component function calls to include iac component
        1. … list function calls
        2. prep_lnd_init
        3. prep_atm_init
      1. RECV/run/SEND sections for iac component
      2. modify general component function calls to include iac component
        1. … list function calls
      1. Header: include iac modules and vars
      2. Mod cesm_init() function
      3. Mod cesm_run() function
  2. New iac coupler interface
    1. iac_comp_mct.F90
      1. iac_init_mct()
      2. iac_run_mct()
      3. iac_final_mct()
      1. New functions
    2. New files

<INSERT FIGURE SHOWING HOW THE IAC COUPLING WORKS>

...

  • iac or component "z" added wherever components are listed, used, defined, etc.
  • Adds coupling code for lnd->iac, iac->lnd, iac→atm
    • lnd → iac
      • Defines the state variables that are passed from land to iac (NPP, heterotrophic respiration, PFT weight)
      • Each variable is passed for each PFTs 
      • KATE: it says four variables but I only see 3 in code - I think we need to pass % vegetated land too?
    • iac → lnd
      • Defines the single state variable passed from iac to land (percent of vegetated land unit for each PFT)
    • iac → atm
      • Defines the single flux variable passed from iac to atm (surface flux of CO2)
      • KATE will need to modify after aircraft and monthly is added, depending on how this is done

IAC component implementation

...

  1. cesm_comp_mod.F90
    1. Set up iac vars,  comp type, etc.
    2. modify general component function calls to include iac component
      1. … list function calls
      2. prep_lnd_init
      3. prep_atm_init
    1. RECV/run/SEND sections for iac component
    2. modify general component function calls to include iac component
      1. … list function calls
    1. Header: include iac modules and vars
    2. Mod cesm_init() function
    3. Mod cesm_run() function
  2. prep_lnd_mod.F90
    1. prep_lnd_calc_z2x_lx() - iac export to lnd grid, run in lnd prep
    2. prep_lnd_get_z2x_lx() - accessor function
    3. Mapping functions?
    1. prep_lnd_init() - include iac
    1. New functions
    2. Modify existing functions
  3. prep_atm_mod.F90
    1. prep_atm_calc_z2x_ax() - iac export to atm grid, run in atm prep
    2. prep_atm_get_z2x_ax() - accessor
    3. Mapping functions?
    1. prep_atm_init() - include iac
    1. New functions
    2. Modify existing functions
  1. ...Files currently unknown
  2. ...list modifications
  1. prep_iac_mod.F90
    1. prep_iac_init()
    2. prep_iac_accum() - accum land inputs, run in lnd post
    3. prep_iac_accum_avg() - average lnd accumulators
    4. prep_iac_calc_l2x_zx()  - lnd export to iac grid
    5. prep_iac_mrg() - merge iac inputs
    1. New functions:
    2. Associated New functions
  1. Modified files
  2. Modify mod files to include iac in function files
  3. New files

...

  1. iac_init_mct()
  2. iac_run_mct()
  3. iac_final_mct()
  1. New functions

...


  1. Initialization and communications: modify modules and functions to include iac interface variables and perform iac initializations
    1. IACID, ALLIACID, CPLALLIACID, CPLIACID, numinst_iac
    2. Modify functions to work with iac
    1. seq_infodata_getData, seq_infodata_putData, seq_infodata_init, other functions
      1. iac_present, iac_prognostic, iac_phase, others
      2. explicit and/or bytype interface?
    2. seq_comm_mct.F90
    3. seq_infodata_mod.F90 - add iac

...

components/clm/src/main/clm_driver.F90:

  • TO BE COMPLETEDAdd call to lnd2iac if iac_active is true

components/clm/src/main/clm_iniatilizeMod.F90:

  • TO BE COMPLETEDAdd call to init_lnd2iac if iac_active is true

components/clm/src/main/clm_instMod.F90:

...

  • Initialize lnd2iac
  • NOTE: there are calls to initialize iac2lnd, but they are currently commented out.

components/clm/src/main/clm_varctl.F90:

  • iac_active added as a control variable, defaulted to false

components/clm/src/main/iac2lndMod.F90:

...

  • New File!
  • Defines Init, Restart, and update_iac2lnd subroutines
    • Init allocates memory for variables
    • Restart reads and writes iac2lnd information to/from the restart file
    • update_iac2lnd sets the ELM variables from the information passed from iac
      • Loops over the 1D array from iac and extracts the information for each patch and PFT on this grid

components/clm/src/main/lnd2iacMod.F90:

  • New File!
  • Defines Init and update_lnd2iac subroutines
    • KATE:

...

  • TO BE COMPLETED
    • Why no Restart?
    • Init allocates memory for hr, npp, and pftwt for all grid x PFT combinations
    • update_lnd2iac loops over patch and extracts variables by pft for this grid


Changes to EAM


components/cam/src/control/camsrfexch.F90: 

  • Input from IAC to EAM defined (fco2_iac)

components/cam/src/cpl/atm_import_export.F90: 

  • Code modified to check if iac component passed data first. If not, read from file

components/cam/src/cpl/cam_cpl_indices.F90: 

  • co2 flux from iac added to list of co2 flux indices


Design Solution: Implement compsets to activate different combinations of components

Date last modified: 
Contributors: 

.....description.....

.....reference.....

Katherine Calvin (Unlicensed)

At this point, we have added the following compsets:

<INSERT NAME>: Couples GCAM and ELM only (effectively an I compset + GCAM)

<INSERT NAME>: Couples GCAM, EAM, and ELM (effectively an F compset + GCAM)

Note that we will subsequently add different compsets for different future forcing scenarios (e.g., different RCPs). The compsets listed above are used to demonstrate capabilities and for testing.


Design Solution: Enable couplings through namelist options

Date last modified: 
Contributors: 

.....description.....

.....reference.....

Katherine Calvin (Unlicensed)

The following namelist variables have been added:

KATE TO ADD LIST


Design Solution: Embed algorithms for temporal & spatial resolution changes within the IAC component that are as flexible as possible

Date last modified: 
Contributors: 

.....description.....

.....reference.....

 

Planned Verification and Unit Testing 

Verification and Unit Testing: Expert Review

Date last modified: 
Contributors: 

The named experts provided extensive review of each other's work, to verify that the design and implementations met the stated requirements. Model testing at each stage of implementation was used to verify that intended changes were correctly implemented, and that unintended changes were avoided.


Planned Validation Testing 

Validation Testing:  Evaluation

with iESM developed diagnostic scripts

of data exchanged between components

Date last modified: 
Contributors: Katherine Calvin (Unlicensed), Alan Di Vittorio

The results of the ported code will eventually be analyzed in a similar manner to that of the iESM (e.g., Thornton et al., 2017). We will not expect exact matches, since we are using a different ESM, but we can ensure the behavior matches expectations/previous experience. For this code review, we will use a set of short test simulations and examine the inputs, outputs, and logs of all components to ensure that the information is being passed correctly in each configuration. We will document the exact checks and archive the code when possible so this can be replicated later.

Planned Performance Testing 

Performance Testing: Short simulations on multiple platforms

Date last modified: 
Contributors: Katherine Calvin (Unlicensed)

We do not expect GCAM to alter the performance of the coupled system, but we will perform short coupled simulations on multiple platforms to quantify the change.