Skip to content

Adding parameter estimation capabilities to CLM#1125

Draft
braczka wants to merge 18 commits into
mainfrom
calLMIP_assim
Draft

Adding parameter estimation capabilities to CLM#1125
braczka wants to merge 18 commits into
mainfrom
calLMIP_assim

Conversation

@braczka

@braczka braczka commented Jun 5, 2026

Copy link
Copy Markdown
Contributor

Description:

Adds parameter estimation functionality to CLM model. This is designed to be tested with the CalLMIP project for site level runs only, however, this code is generalized to handle regional/global simulations, where parameter global parameters are mapped onto 2D gridded space for localization. Code also performs spatial averaging of parameter posterior before reinserting back into clm parameter file for forecast integration.

Key additions:

  1. Adds parameter specific namelist file options to turn on parameter estimation (e.g. input.nml, shell scripting files). Allows user to choose multiple parameter types, multiple PFT types, and choice of parameter versus joint parameter-state estimation.
  2. Adds functionality to assimilate.csh which coordinates execution of DART specific executables and provides
    proper linkages to parameter related files, similar to functionality of previous domain files (e.g. restart, history, vector).
  3. Modifies model_mod.f90 to add a 4th parameter domain to CLM model (now restart,history,vector and param domains)
  4. Adds parameter augmentation capability (2D spatial mapping) within clm_to_dart.f90 file, such that parameter values are assigned explicit locations consistent with CLM lat/lon grid. No vertical location is assigned to parameter.
  5. Adds either geometric spatial weighting with PFT mask to average parameter posterior values to obtain a single global parameter for forecast step. User is provided a second spatial averaging methodology which geometrically averages based on the PFT specific land area coverage. In other words, grids with little % land area coverage of PFT undergoing parameter estimation will be de-weighted when calculating spatial average.
  6. Adds new land model based QTYs specific for calLMIP project including soil carbon, land-atmosphere flux and parameter QTYs.

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • Documentation update

Documentation changes needed?

  • My change requires a change to the documentation.
    • I have updated the documentation accordingly.

Tests

Will be tested with CalLMIP project for single site and multi-site parameter estimation immediately which will test the added param domain and namelist setting functionality. The site simulations do not require parameter augmentation and averaging functionality, so will perform a separate regional simulation for parameter localization/averaging testing.

Checklist for merging

  • Updated changelog entry
  • Documentation updated
  • Update conf.py

Checklist for release

  • Merge into main
  • Create release from the main branch with appropriate tag
  • Delete feature-branch

Testing Datasets

I will provide testing results related to CalLMIP project for single site and multi-site parameter and joint parameter-state DA simulations.

braczka added 16 commits June 5, 2026 15:26
Adding SOIL_CARBON_1m obs type. Although
soil carbon is vertically discretized in CLM
this observation is to the total carbon stock
in 1 meter.  For CLM TOTSOMC_1m, thus can treat
this obs as 2 dimensional (horizontal interp only)
Do not need vertical interpolation for
soil carbon 1 meter carbon stock.
Adding specific fast, medium, slow
turnover carbon pools
Assimilating averaged flux tower
data (hourly, monthly) requires simplified
common code obs type/quantity
Needed to reduce LH and SH quant and
obs names for text limits.

These are intended for direct interpolation
of daily averages.
Just updating namelist values
for calLMIP observations and time
Just simplified things when parsing
obs for calLMIP application
Adding land parameter quantities for CalLMIP
parameter DA. I have included a high level of
mechanism specificity anticipating I will need this
for variable localization later on.
The model_nml 6 column format now supports
new 'param' file origin and adds this new param domain
to join the original restart,history and vector clm domains.
 Adds 'estimate params' option and allows user to define which clm
PFTs to estimate parameters for. Performs parameter augmentation
to map explicit 2D lat/lon locations to global PFT parameters
(and for global scalar parameters).  Brings in new parameter
specific QTYs.
Leverages clm_to_dart to create parameter augmentation
(expansion) by mapping single global parameter value onto spatially
explicit 2D lat/lon clm grid.  This applies lat/lon history
information from history domain onto param domain.  Allows
for spatially explicit updates to parameter values and application
of spatial localization.
clm_to_dart expands parameter to spatial 2D grid,
therefore during the filter update global parameter values
will have spatially explicit updates. This commit
spatially averages the posterior parameter values
to generate a global parameter so that it can be
re-inserted into clm model for the subsequent forecast.
User options for spatial averaging based on geometric spatial average
and masks out cells where PFT is not present.  Also
has PFT-averaged option which spatially averages the
PFT specific spatial coverage to calculate global
posterior parameter value.
Adds namelist options  within model_nml, filter_nml
fill_inflation_restart_nml and clm_to_dart and dart_to_clm
specifically for parameter DA functionality
Assimilate.csh orchestrates key execution of
DART executables and links all important file defined
in namelist to DART code.  Block 4 adds the parameter
domain for functioning of fill_inflation_restart.
Block 5 provided proper linkages to parameter related
to template and expanded param files.  Block 7 performs
dart_to_clm execution and appropriate linkages.  Block 8
updates the archiving and cleanup consisten with other
domain files
Adds parameter file staging to run directory
Sets the initial parameter directory and base file
name.  Also informs the shell scripting when estimate_params
is turned on, which is required for non-Fortran related
operation of code (i.e. coordination of csh commands)
average_params_to_scalar previously used num_active_pfts > 0 to determine
whether a param variable was PFT-indexed or scalar, which incorrectly
classified scalar variables (e.g. cv) as PFT-indexed whenever any PFT
index was set. Fix by inspecting the actual variable dimensionality in
the compact param file via nf90_inquire_variable, mirroring the existing
logic in expand_params_to_grid (clm_to_dart.f90).
@braczka braczka self-assigned this Jun 5, 2026
@braczka braczka added Enhancement New feature or request CLM Community Land Model labels Jun 5, 2026

@hkershaw-brown hkershaw-brown left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Leaving this on request changes since this is not code to review (has not been run, & will not run).

@jlaucar

jlaucar commented Jun 10, 2026 via email

Copy link
Copy Markdown
Contributor

@braczka

braczka commented Jun 10, 2026

Copy link
Copy Markdown
Contributor Author

This is a draft PR, and as such, not ready to review. I am still currently testing/changing functionality. I put it on draft to start discussion on changes and development. If you want me to keep it as a branch and remove as draft PR I can do that as well...

braczka added 2 commits June 10, 2026 16:49
Force error if inconsistent param
estimation setting between input.nml and
shell scripting
All variables present in input.nml:model_nml
must be declared within clm_to_dart and dart_to_clm,
otherwise unrecognized namelist error
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

CLM Community Land Model Enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants