Cross grid seed dispersal

[YanlanLiu]

This PR implements cross grid seed dispersal, allowing seed exchange among neighboring grids.

Description:

• This tracks the seed production of each PFT and assigns a fraction for seed dispersal outside the local grid.
• The seed mass received by each neighboring cell is calculated based on a seed dispersal kernel, which can be among exponential, exponential power, and Log-sech kernel functions as described in Bullock et al. (2016).
• The parameter file is updated to include the shape parameters of the kernel function, the maximum dispersal distance, and the fraction of seeds departing from the local grid.
• Seed mass per PFT dispersed from neighboring grids is added to the local seed bank.
• Both incoming and departing seed masses per PFT are tracked in boundary conditions, included in the mass balance check and communicated with the host land model.
• The branch is coordinated with Add FATES cross-grid seed dispersal mechanism E3SM-Project/E3SM#5555 and Add FATES cross-grid seed dispersal mechanism ESCOMP/CTSM#2077, where the neighboring grids are identified and cross-grid seed exchange is applied at a specified time interval (day, month, or year).

Resolves #471

Collaborators:

I wrote the initial version with help of @jenniferholm, in discussion with @ckoven, @rgknox, and @slevisconsulting. @glemieux significantly improved the version by implementing wrap functions, dispersal kernels, updated parameter files, and improved ELM-FATES interface.

Expectation of Answer Changes:

When turned on, cross grid seed dispersal is expected to change seed bank storage thus PFT composition. The cross grid seed dispersal can be turned off by setting the fates_seed_dispersal_fraction parameter to zero.

Checklist:

• My change requires a change to the documentation.
• I have updated the in-code documentation .AND. (the technical note .OR. the wiki) accordingly.
• I have read the CONTRIBUTING document.
• FATES PASS/FAIL regression tests were run
• If answers were expected to change, evaluation was performed and provided

Test Results:

Not yet tested

CTSM (or) E3SM (specify which) test hash-tag:

CTSM (or) E3SM (specify which) baseline hash-tag:

FATES baseline hash-tag:

Test Output:

[glemieux]

I'm finding that exact restarts when seed dispersal is on is not B4B. Investigating. Note that this is not part of the official regression testing list at this time.

[glemieux]

ERS testing is passing b4b now with commits e5cd151 and ESCOMP/CTSM@e978870. An e3sm version of the latter commit is forthcoming along with rerunning of the standard regression tests.

UPDATE: e3sm commit is E3SM-Project/E3SM@b11b83c

[glemieux]

It looks like the ERS fix did not address the thread/task switching restart ERP tests, all of which are failing COMPARE_base_rest. Based on the variety of grid sizes and debug modes, this appears to be strictly an issue with the ERP setup. I also can confirm that only the seed relevant history output is the issue here via the AllVars test. I'm currently investigating.

Failing tests:

• ERP_D_Ld3.f19_g17.I2000Clm50FatesCruRsGs.cheyenne_intel.clm-FatesCold
• ERP_D_P36x2_Ld3.f19_g17.I2000Clm50FatesCru.cheyenne_intel.clm-FatesCold
• ERP_Ld3.f09_g17.I2000Clm50FatesRs.cheyenne_intel.clm-FatesCold
• ERP_Ld9.f45_f45_mg37.I2000Clm50FatesCruRsGs.cheyenne_intel.clm-FatesColdAllVars

[glemieux]

Per recommendation from @adrifoster, I've refactored the code on both the hlm and fates side to utilize a namelist switch to handle the seed dispersal cadence, which will also allow the user to turn off seed dispersal without modifying the parameter file.

The code is still not b4b across different pe layouts, but I've generated #1089 to note this track this to be fixed on a future PR.

[glemieux]

Retesting the with the fates suite on cheyenne and izumi results in all expected tests passing B4B. Note that ESCOMP/CTSM#2077 adds a cross-grid seed dispersal testmod and a pelayout changing PEM test that has been flagged as an expected failure.

Cheyenne: /glade/scratch/glemieux/ctsm-tests/tests_pr1005-fates-dev142
Izumi: /scratch/cluster/glemieux/ctsm-tests/tests_pr1005-fates-dev142

[glemieux]

Re-running fates suite testing after implementing clm-side updates, all expected tests pass b4b:

cheyenne: /glade/u/home/glemieux/scratch/ctsm-tests/tests_pr1005-fates-dev143
izumi: /home/glemieux/scratch/ctsm-tests/tests_pr1005-basegen-dev143