Skip to content

Soil Hydraulic Parameter from surface file for eCLM #87

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jjokella merged 6 commits into from
Nov 25, 2025
Merged

Soil Hydraulic Parameter from surface file for eCLM #87

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
46ea27e
Soil Hydraulic Parameter Perturbations for eCLM
jjokella Nov 20, 2025
a5bfe2a
namelist inputs: `parameters_in_file` and `parameters_in_file_adj`
jjokella Nov 21, 2025
120d880
Merge branch 'master' into dev-shp
jjokella Nov 21, 2025
de5e972
more descriptive namelist entry
jjokella Nov 25, 2025
e12540b
docs update
jjokella Nov 25, 2025
6677416
change namelist parameter name to
jjokella Nov 25, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion docs/_toc.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,9 @@ parts:
- file: users_guide/introduction/introduction
title: Scientific Background
- file: users_guide/introduction/perturbation
title: Perturbation routines
title: Atmospheric forcing noise
- file: users_guide/introduction/soil_hydraulic_parameters
title: Soil hydraulic properties from surface file

- caption: User's Guide
chapters:
Expand Down
177 changes: 14 additions & 163 deletions docs/users_guide/introduction/perturbation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,11 @@
# Perturbation routines #
# Atmospheric forcing noise #

This section describes **perturbation capabilities for eCLM-PDAF**.

The implementation of the Soil Hydraulic Parameter perturbation was
first introduced by Fernand Eloundou and adapted by Yorck
Ewerdwalbesloh.
This section describes **atmospheric forcing noise for eCLM-PDAF**.

The implementation of the atmospheric forcing perturbation routines
was first introduced by Yorck Ewerdwalbesloh.

## Description
## General Description

eCLM implements perturbations for atmospheric forcing variables
(temperature, precipitation, longwave radiation, and shortwave
Expand Down Expand Up @@ -46,144 +42,7 @@ is adjustable based on application requirements.
Perturbation fields are read from preprocessed noise files and applied
to atmospheric forcing variables within the eCLM model during runtime.

## Key Components ##

### 1. Soil Parameter Perturbation (`SoilStateInitTimeConstMod.F90`) ###

Allows reading perturbed hydraulic parameters from input files instead
of computing them via pedotransfer functions.

**Parameters:**
- `THETAS` - saturated water content
- `SHAPE_PARAM` - Brooks-Corey shape parameter (`bsw`)
- `PSIS_SAT` - saturated matric potential (`sucsat`)
- `KSAT` - saturated hydraulic conductivity (`xksat`)

**Implementation:**
- Hydraulic parameters read from surface file
- Reads EITHER original parameters (for `nlevsoifl=10` soil layers)
and applies organic matter mixing OR: Reads adjusted parameters with
`_adj` suffix (for all `nlevgrnd` layers) and **overwrites**
parameters from organic matter mixing.
- Falls back to pedotransfer functions if parameters aren't in the file
- Modifies organic matter mixing to preserve perturbed parameter
values

#### Surface File

Soil hydraulic parameters are read from the **surface dataset file**,
which is specified in the `lnd_in` namelist file under key `fsurdat`.

##### Sufrace File: Parameter Structure and Dimensions

All soil hydraulic parameters are stored as three-dimensional arrays
with the structure:

```
(nlevgrnd, lsmlat, lsmlon)
```

Where:
- `nlevgrnd`: Number of soil layers (vertical dimension, typically 25
layers in eCLM simulations, see namelist file key
`soil_layerstruct`)
- `lsmlat`: Number of latitude grid points
- `lsmlon`: Number of longitude grid points

This 3D structure enables depth-varying, spatially-distributed soil
properties across the model domain.

##### Surface File: Input Parameter Format

Two options
- original parameters that undergo organic mixing
- adjusted parameters that are used by input values

###### Original Parameters

The surface file must contain the following baseline parameters:

``` text
THETAS(nlevgrnd, lsmlat, lsmlon)
long_name: "Porosity"
units: "vol/vol"

SHAPE_PARAM(nlevgrnd, lsmlat, lsmlon)
long_name: "Shape (b) parameter"
units: "unitless"

PSIS_SAT(nlevgrnd, lsmlat, lsmlon)
long_name: "Saturated soil matric potential"
units: "mmH2O"

KSAT(nlevgrnd, lsmlat, lsmlon)
long_name: "Saturated hydraulic conductivity"
units: "mm/s"
```

These parameters apply to the first 10 soil layers (`nlevsoifl=10`) and
undergo organic matter mixing.

###### Adjusted Parameters for Data Assimilation

When running with perturbed soil parameters (e.g., from ensemble data
assimilation), the surface file should contain adjusted parameters
with the `_adj` suffix:

``` text
THETAS_adj(nlevgrnd, lsmlat, lsmlon)
long_name: "Porosity"
units: "vol/vol"
_FillValue: 1.e+30

SHAPE_PARAM_adj(nlevgrnd, lsmlat, lsmlon)
long_name: "Shape (b) parameter"
units: "unitless"
_FillValue: 1.e+30

PSIS_SAT_adj(nlevgrnd, lsmlat, lsmlon)
long_name: "Saturated soil matric potential"
units: "mmH2O"
_FillValue: 1000.0

KSAT_adj(nlevgrnd, lsmlat, lsmlon)
long_name: "Saturated hydraulic conductivity"
units: "mm/s"
_FillValue: 1.e+30
```

**Important Notes:**
- Adjusted parameters apply to **all** `nlevgrnd` layers
- When present, adjusted parameters **overwrite** the results of organic
matter mixing
- `PSIS_SAT_adj` uses a different fill value (1000.0) compared to other
parameters (1.e+30), reflecting special handling for undefined matric
potential values
- If adjusted parameters are not present in the surface file, eCLM falls
back to the original parameters or pedotransfer functions

#### Parameter Priority and Fallback Option

The code in `SoilStateInitTimeConstMod.F90` follows this priority order:

1. **First priority**: Read `_adj` parameters (if present) → applies
to all `nlevgrnd` layers → **overwrites** organic matter mixing
results
2. **Second priority**: Read original parameters → applies to first 10
layers (`nlevsoifl`) → undergoes organic matter mixing
3. **Fallback**: Use pedotransfer functions if parameters are absent
from the file

This hierarchical approach ensures maximum flexibility for both
standard simulations and data assimilation applications.

#### Note about the Brooks-Corey Shape Parameter ####

When perturbed soil parameters are read from input files, the organic
matter mixing for `bsw` uses the file-read value instead of the
hard-coded Cosby et al. (1984) Table 5 formula (`2.91 + 0.159*clay`).

### 2. Noise-Based Forcing Perturbation ###
## 1. Noise-Based Forcing Perturbation ##

When having an ensemble run, the memory consumption is too large if
the forcing data is perturbed one by one so that I get a file for each
Expand Down Expand Up @@ -216,13 +75,13 @@ data assimilation.
- Detects noise fields by checking if model field name contains `"noise"`
- Adjusts time coordinate reading to account for ensemble-extended noise files

#### Preparing Atmospheric Forcing Noise ####
### Preparing Atmospheric Forcing Noise ###

This section describes the workflow for generating and configuring
spatiotemporally correlated noise fields for atmospheric forcing
perturbations.

##### Noise Generation Tool #####
#### Noise Generation Tool ####

The `correlatedNoise.py`
(https://github.com/HPSCTerrSys/eCLM_atm-forcing-generator/pull/8)
Expand All @@ -241,7 +100,7 @@ correlated noise fields for all ensemble members.

**Output**: One NetCDF file per month containing noise fields for all ensemble members and all perturbed variables.

##### Stream File Configuration #####
#### Stream File Configuration ####

Stream files configure how eCLM reads and applies noise fields to
atmospheric forcing data. Three separate stream files are required
Expand All @@ -256,15 +115,15 @@ file must specify the following metadata fields:
- **Perturbation variables**: `tbot_noise` (temperature), `lwdn_noise` (longwave radiation), `precn_noise` (precipitation), `swdn_noise` (shortwave radiation)


##### Stream File Examples #####
#### Stream File Examples ####

The following examples demonstrate proper stream file configuration
for precipitation, solar radiation, and other atmospheric
variables. Each example must be adapted with correct file paths,
temporal parameters, and ensemble member IDs for your specific
application.

###### Precipitation Noise Stream File ######
##### Precipitation Noise Stream File #####

**File**: `user_datm.streams.precip_noise.stream_0000.txt`

Expand Down Expand Up @@ -323,7 +182,7 @@ application.
</fieldInfo>
```

###### Solar Radiation Noise Stream File ######
##### Solar Radiation Noise Stream File #####

**File**: `user_datm.streams.solar_noise.stream_0000.txt`

Expand Down Expand Up @@ -382,7 +241,7 @@ application.
</fieldInfo>
```

###### Temperature and Longwave Radiation Noise Stream File ######
##### Temperature and Longwave Radiation Noise Stream File #####

**File**: `user_datm.streams.other_noise.stream_0000.txt`

Expand Down Expand Up @@ -443,7 +302,7 @@ application.

```

### 3. DATM Integration (`datm_comp_mod.F90`) ###
## 2. DATM Integration (`datm_comp_mod.F90`) ##

Passes ensemble information (`inst_index`, `dt_option`, `ninst`) from
the data atmosphere (DATM) component to the stream infrastructure,
Expand All @@ -452,22 +311,14 @@ CESM's multi-instance framework.

## Design Rationale ##

1. **Dual perturbation approach**:
- Parameter perturbation for soil properties (offline preprocessing)
- Forcing perturbation via temporal noise patterns (runtime)

2. **Backward compatibility**: All changes are guarded by `USE_PDAF`
1. **Backward compatibility**: All changes are guarded by `USE_PDAF`
preprocessor directives

3. **Efficiency**: Uses a single noise file for all ensemble members
2. **Efficiency**: Uses a single noise file for all ensemble members
by time-shifting, avoiding storage duplication

4. **Flexibility**: Soil parameters can be perturbed or computed
traditionally based on file contents

## Modified Source Code ##

- `src/clm5/biogeophys/SoilStateInitTimeConstMod.F90`
- `src/csm_share/streams/shr_stream_mod.F90`
- `src/csm_share/streams/shr_strdata_mod.F90`
- `src/csm_share/streams/shr_dmodel_mod.F90`
Expand Down
Loading