Merge branch 'master' into dev-grace-da

jjokella · jjokella · commit ade72af18d5a · 2025-11-28T18:09:50.000+01:00
diff --git a/CONTRIBUTORS.txt b/CONTRIBUTORS.txt
@@ -6,4 +6,5 @@ Marco VAN HULTEN
 Ana GONZALEZ-NICOLAS
 Daniel CAVIEDES-VOULLIÈME
 Olga DOMBROWSKI
-
+Yorck EWERDWALBESLOH
+Fernand ELOUNDOU
diff --git a/docs/_toc.yml b/docs/_toc.yml
@@ -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:
diff --git a/docs/users_guide/introduction/perturbation.md b/docs/users_guide/introduction/perturbation.md
@@ -1,12 +1,11 @@
-# Perturbation routines #
+# Atmospheric forcing noise #
 
-This section describes **perturbation capabilities for eCLM-PDAF**.
+This section describes **atmospheric forcing noise for eCLM-PDAF**.
 
-The implementation of the perturbation routines was first introduced
-by Yorck Ewerdwalbesloh in
-https://gitlab.jsc.fz-juelich.de/detect/cluster-c/c01/perturbationroutineclm5.
+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
@@ -43,33 +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:**
-- Reads both 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
-
-#### 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
@@ -102,44 +75,18 @@ data assimilation.
 - Detects noise fields by checking if model field name contains `"noise"`
 - Adjusts time coordinate reading to account for ensemble-extended noise files
 
-### 3. DATM Integration (`datm_comp_mod.F90`) ###
-
-Passes ensemble information (`inst_index`, `dt_option`, `ninst`) from
-the data atmosphere (DATM) component to the stream infrastructure,
-enabling the noise perturbation mechanism to operate correctly within
-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` preprocessor directives
-
-3. **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`
-- `src/datm/datm_comp_mod.F90`
-
-## 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 `tools/correlatedNoise.py` script generates monthly NetCDF files
-containing spatiotemporally correlated noise fields for all ensemble
-members.
+The `correlatedNoise.py`
+(https://github.com/HPSCTerrSys/eCLM_atm-forcing-generator/pull/8)
+script generates monthly NetCDF files containing spatiotemporally
+correlated noise fields for all ensemble members.
 
 **Key Configuration Parameters:**
 
@@ -153,7 +100,7 @@ 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
@@ -168,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`
 
@@ -235,7 +182,7 @@ application.
 </fieldInfo>
 ```
 
-#### Solar Radiation Noise Stream File
+##### Solar Radiation Noise Stream File #####
 
 **File**: `user_datm.streams.solar_noise.stream_0000.txt`
 
@@ -294,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`
 
@@ -354,3 +301,26 @@ application.
 </fieldInfo>
 
 ```
+
+## 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,
+enabling the noise perturbation mechanism to operate correctly within
+CESM's multi-instance framework.
+
+## Design Rationale ##
+
+1. **Backward compatibility**: All changes are guarded by `USE_PDAF`
+   preprocessor directives
+
+2. **Efficiency**: Uses a single noise file for all ensemble members
+   by time-shifting, avoiding storage duplication
+
+## Modified Source Code ##
+
+- `src/csm_share/streams/shr_stream_mod.F90`
+- `src/csm_share/streams/shr_strdata_mod.F90`
+- `src/csm_share/streams/shr_dmodel_mod.F90`
+- `src/datm/datm_comp_mod.F90`
+
diff --git a/docs/users_guide/introduction/soil_hydraulic_parameters.md b/docs/users_guide/introduction/soil_hydraulic_parameters.md
@@ -0,0 +1,205 @@
+# Soil Hydraulic Parameters #
+
+This section describes **setting Soil Hydraulic Parameters from the
+surface file**.
+
+The implementation was first introduced by Fernand Eloundou and
+adapted by Yorck Ewerdwalbesloh.
+
+## 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
+- parameters that undergo organic mixing
+- adjusted parameters that are used by input values
+
+##### Parameters before organic mixing
+
+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 after organic mixing
+
+For using adjusted soil parameters from file that represent the whole
+soil including organic matter, 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
+
+### Namelist Configuration
+
+The soil hydraulic parameter reading behavior is controlled by two
+namelist settings in the `clm_soilstate_inparm` section of the `lnd_in`
+namelist file:
+
+#### `soil_hyd_inparm_from_file`
+
+**Type:** logical
+**Default:** `.false.`
+**Description:** Controls whether to read baseline hydraulic parameters
+from the surface dataset file.
+
+When set to `.true.`:
+- eCLM reads `THETAS`, `SHAPE_PARAM`, `PSIS_SAT`, and `KSAT` from the
+  surface file
+- Parameters apply to the first 10 soil layers (`nlevsoifl=10`)
+- Parameters undergo organic matter mixing
+- If any required variable is missing, the model aborts with an error
+  message
+
+When set to `.false.` (default):
+- Hydraulic parameters are computed via pedotransfer functions from
+  sand and clay fractions
+- No parameters are read from the surface file
+
+#### `soil_hyd_inparm_from_file_adj`
+
+**Type:** logical
+**Default:** `.false.`
+**Description:** Controls whether to read organic-matter-adjusted
+hydraulic parameters from the surface dataset file.
+
+When set to `.true.`:
+- eCLM reads `THETAS_adj`, `SHAPE_PARAM_adj`, `PSIS_SAT_adj`, and
+  `KSAT_adj` from the surface file
+- Parameters apply to **all** `nlevgrnd` soil layers (typically 25
+  layers)
+- Adjusted parameters **overwrite** the results from organic matter
+  mixing
+- If any required variable is missing, the model aborts with an error
+  message
+
+When set to `.false.` (default):
+- No organic-matter-adjusted parameters are read from the surface file
+- Organic matter mixing results are used as final parameter values
+
+#### Example Configuration
+
+```fortran
+&clm_soilstate_inparm
+  organic_frac_squared = .false.
+  soil_hyd_inparm_from_file = .false.
+  soil_hyd_inparm_from_file_adj = .true.
+/
+```
+
+This configuration:
+- Reads adjusted parameters from the surface file which override the
+  organic matter mixing results
+- Can e.g. be used for ensemble data assimilation applications with
+  perturbed soil parameters specified in a group of surface files, one
+  surface file per ensemble member.
+
+#### Error Handling
+
+Both namelist parameters enforce strict error checking:
+- If set to `.true.`, **all** required parameters must be present in
+  the surface file
+- Missing variables trigger an immediate model abort with a descriptive
+  error message
+- This ensures users are explicitly aware when parameter files are
+  incomplete
+
+### 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`).
+
+## Modified Source Code ##
+
+- `src/clm5/biogeophys/SoilStateInitTimeConstMod.F90`
diff --git a/src/clm5/biogeophys/SoilStateInitTimeConstMod.F90 b/src/clm5/biogeophys/SoilStateInitTimeConstMod.F90
