Versions Compared

Old Version 11

changes.mady.by.user Katherine Calvin

Saved on

compared with

New Version 12

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. 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. … list function calls
    1. Header: include iac modules and vars
    2. Mod cesm_init() function
    3. Mod cesm_run() function
  1. 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
  2. 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
  3. 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
  4. 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:

  • TO BE COMPLETEDInitialize 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 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 grid, patch, and PFT

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

  • TO BE COMPLETEDNew File!


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.....


Design Solution: Enable couplings through namelist options

Date last modified: 
Contributors: 

.....description.....

.....reference.....


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

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

The results of the ported code will 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.

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.