LST-DA for eCLM-PDAF

docs/_toc.yml

@@ -28,6 +28,7 @@ parts:
       - file: users_guide/running_tsmp_pdaf/input_cmd
       - file: users_guide/running_tsmp_pdaf/input_obs
       - file: users_guide/running_tsmp_pdaf/input_enkfpf
+      - file: users_guide/running_tsmp_pdaf/lst_da
 
     - file: users_guide/debugging_tsmp_pdaf/README
       title: Debugging TSMP-PDAF

docs/users_guide/running_tsmp_pdaf/README.md

@@ -15,6 +15,9 @@ COSMO](cos)). Additionally, a control file for the data assimilation
 Furthermore, some command line options ([Command line options](cmd))
 need to be specified when TSMP-PDAF is executed.
 
+For assimilation of land surface temperature observations into CLM, see
+[Land Surface Temperature Data Assimilation](lstda).
+
 See the Virtual Machine download on webpage
 <https://datapub.fz-juelich.de/slts/tsmp-vm/index.html>.
 

docs/users_guide/running_tsmp_pdaf/input_enkfpf.md

@@ -63,6 +63,10 @@ statevec_max_layer =
 t_printensemble =
 watmin_switch =
 swc_mask_snow =
+T_mask_snow =
+increment_type =
+T_mask_T =
+T_max_increment =
 
 [COSMO]
 nprocs      =
@@ -479,16 +483,37 @@ CLM (standalone only).
    manual
    <https://escomp.github.io/ctsm-docs/versions/release-clm5.0/html/tech_note/index.html>)
 
+(enkfpf:clm:update_T)=
 ### CLM:update_T ###
 
-`CLM:update_T`: (integer) Flag for updating of ground and vegetation
-temperature.
+`CLM:update_T`: (integer) Flag for updating temperature variables in
+eCLM via LST data assimilation.
 
-Currently only CLM3.5
+State vector variables updated for each option:
 
--  0: No update of ground and vegetation temperature
+-  0: No update of temperature variables.
 
--  1: Update of ground and vegetation temperature
+-  1: Update of ground temperature (`t_grnd`) and vegetation
+   temperature (`t_veg`) directly. The simulated LST is computed from
+   `t_grnd` and `t_veg` using a radiometric mixing formula
+   ([Kustas & Anderson, 2009](https://doi.org/10.1016/j.agrformet.2009.05.016),
+   Eq. 7) with LAI.
+
+-  2: Gridcell-mean update of skin temperature (`t_skin`, not
+   prognostic), soil/snow temperatures (`t_soisno`, all `nlevgrnd`
+   layers), and vegetation temperature (`t_veg`). Each patch/column is
+   updated based on gridcell-mean increments and according to selected
+   [increment type](enkfpf:clm:increment_type). The observation
+   operator uses the skin temperature (TSKIN) as the simulated LST
+   equivalent.
+
+-  3: Like `2`, but additionally updates ground temperature
+   (`t_grnd`).  State vector: `t_skin`, `t_soisno` (`nlevgrnd`
+   layers), `t_veg`, `t_grnd`.
+
+
+See [Land Surface Temperature Data Assimilation](lstda) for a detailed
+description.
 
 ### CLM:print_swc ###
 
@@ -595,12 +620,62 @@ are allowed.
 `CLM:swc_mask_snow`: (integer) Switch for masking columns with snow
 cover from SWC updates.
 
-Snow covers larger than 1mm are switched off for the update.
+Columns with snow depth ≥ 1 mm are excluded from the update.
 
 Only takes effect if `CLM:update_swc``is switched on.
 
 Default setting is `0`: No masking of columns with snow cover.
 
+(enkfpf:clm:T_mask_snow)=
+### CLM:T_mask_snow ###
+
+`CLM:T_mask_snow`: (integer) Switch for masking columns with snow
+cover from T updates.
+
+Snow covers larger than 1mm are switched off for the update.
+
+Only takes effect if `CLM:update_T` is switched on.
+
+Default setting is `0`: No masking of columns with snow cover.
+
+(enkfpf:clm:increment_type)=
+### CLM:increment_type ###
+
+`CLM:increment_type`: (integer) Switch for changing increment type in
+T-update.
+
+- `0`: Multiplicative increment
+- `1`: Additive increment
+
+Only takes effect if `CLM:update_T` is switched on.
+
+Default setting is `0`: Multiplicative increment.
+
+(enkfpf:clm:T_max_increment)=
+### CLM:T_max_increment ###
+
+`CLM:T_max_increment`: (double) Maximum allowed magnitude of the
+additive temperature increment (K).
+
+Only takes effect if `CLM:update_T` is switched on and
+`CLM:increment_type` is set to `1`.
+
+Default setting is `5.0`: Updates larger than 5K are not applied.
+
+(enkfpf:clm:T_mask_T)=
+### CLM:T_mask_T ###
+
+`CLM:T_mask_T`: (double) Offset above freezing (K) used as the
+lower-temperature masking threshold. The update is suppressed whenever
+
+```
+t_soisno(:,1) < 273.15 K + CLM:T_mask_T.
+```
+
+Only takes effect if `CLM:update_T` is switched on.
+
+Default setting is `0.`: Masking updates below freezing temperatures.
+
 (enkfpf:cosmo)=
 ## [COSMO] ##
 
@@ -862,7 +937,7 @@ Default: 0, output turned off.
 ## Parameter Summary ##
 
  | section   | parameter               | default value |
- |:---------:|:-----------------------:|:-------------:|
+ |:----------|:------------------------|:--------------|
  | `[PF]`    |                         |               |
  |           | `problemname`           | \-            |
  |           | `nprocs`                | 0             |
@@ -892,6 +967,8 @@ Default: 0, output turned off.
  |           | `problemname`           | \-            |
  |           | `nprocs`                | 0             |
  |           | `update_swc`            | 1             |
+ |           | `update_texture`        | 0             |
+ |           | `update_T`              | 0             |
  |           | `print_swc`             | 0             |
  |           | `print_et`              | 0             |
  |           | `statevec_allcol`       | 0             |
@@ -900,6 +977,10 @@ Default: 0, output turned off.
  |           | `statevec_max_layer`    | 25            |
  |           | `t_printensemble`       | -2            |
  |           | `watmin_switch`         | 0             |
+ |           | `T_mask_snow`           | 0             |
+ |           | `increment_type`        | 0             |
+ |           | `T_max_increment`       | 5.0           |
+ |           | `T_mask_T`              | 0.0           |
  | `[COSMO]` |                         |               |
  |           | `nprocs`                | 0             |
  |           | `dtmult`                | 0             |

docs/users_guide/running_tsmp_pdaf/lst_da.md

@@ -0,0 +1,166 @@
+(lstda)=
+# Land Surface Temperature Data Assimilation #
+
+Land Surface Temperature data assimilation (LST-DA) in TSMP-PDAF enables
+the assimilation of remotely-sensed land surface temperature (LST)
+observations into the eCLM land-surface model. The analysis step updates
+one or more temperature variables in the CLM state, and auxiliary masking
+and increment-clipping parameters allow the update to be restricted to
+physically meaningful regimes.
+
+## Configuration ##
+
+LST-DA is controlled by five parameters in the [`[CLM]` section of
+`enkfpf.par`](enkfpf:clm):
+
+- [`CLM:update_T`](enkfpf:clm:update_T): selects which CLM temperature
+  variables are placed in the state vector and updated after the analysis
+  step.
+- [`CLM:T_mask_snow`](enkfpf:clm:T_mask_snow): optionally masks out
+  columns with snow cover from the temperature update.
+- [`CLM:increment_type`](enkfpf:clm:increment_type): switches between
+  multiplicative (default) and additive increments.
+- [`CLM:T_max_increment`](enkfpf:clm:T_max_increment): clips additive
+  increments to a maximum magnitude (only relevant when
+  `CLM:increment_type=1`).
+- [`CLM:T_mask_T`](enkfpf:clm:T_mask_T): masks out columns whose
+  surface-layer soil temperature falls below a threshold close to
+  freezing.
+
+When LST-DA is active (`CLM:update_T != 0`), the temperature state
+variables replace the soil water content (SWC) in the state vector.
+Simultaneous assimilation of SWC and LST in the same PDAF update step is
+not supported.
+
+## State Vector ##
+
+The state vector content depends on `CLM:update_T`. For options 2 and 3
+the state vector is defined at the gridcell level (one value per grid
+cell); for option 1 it is defined at the patch level.
+
+| `update_T` | State vector variables                                       |
+|:-----------|:-------------------------------------------------------------|
+| `1`        | `t_grnd` (per patch) + `t_veg` (per patch)                   |
+| `2`        | `t_skin` (per gridcell) + `t_soisno` (all `nlevgrnd` layers) |
+|            | + `t_veg` (per gridcell)                                     |
+| `3`        | Same as `2`, plus `t_grnd` (per gridcell)                    |
+
+## Observation Operator ##
+
+The observation operator maps the CLM state to a simulated LST:
+
+- **Option 1**: The simulated LST is computed from `t_grnd` and
+  `t_veg` using the radiometric mixing formula of [Kustas & Anderson
+  (2009)](https://doi.org/10.1016/j.agrformet.2009.05.016) (Eq. 7),
+  weighted by leaf area index (LAI).
+- **Options 2 and 3**: The skin temperature `t_skin` is used directly as
+  the simulated LST. Observations are indexed at the gridcell level
+  (one observation per grid cell).
+
+## Increment Application ##
+
+After the PDAF analysis step, the updated state vector values are written
+back to the CLM temperature arrays. Two increment modes are available,
+selected via [`CLM:increment_type`](enkfpf:clm:increment_type):
+
+**Multiplicative increment** (`CLM:increment_type=0`, default):
+Each temperature variable is scaled by the ratio of the posterior to the
+prior gridcell-mean skin temperature:
+
+```
+t_update = t_prior × (TSKIN_out / TSKIN_in)
+```
+
+**Additive increment** (`CLM:increment_type=1`):
+The difference between posterior and prior gridcell-mean TSKIN is added
+directly to each temperature variable:
+
+```
+t_update = t_prior + (TSKIN_out - TSKIN_in)
+```
+
+When `CLM:increment_type=1`, the increment is clipped to
+`±CLM:T_max_increment` (default 5 K). Increments that exceed this
+threshold are replaced by the clipped value and a warning counter is
+incremented; the total number of clipped increments is printed after each
+analysis step.
+
+## Masking ##
+
+Two independent masking conditions can suppress the update for individual
+columns or grid cells:
+
+**Snow masking** (`CLM:T_mask_snow`): When set to `1`, columns with a
+snow depth ≥ 1 mm are excluded from the temperature update. This avoids
+applying a bare-soil LST increment to snow-covered grid cells.
+
+**Freeze masking** (`CLM:T_mask_T`): The update is suppressed whenever
+the soil/snow temperature of the surface layer (`t_soisno(:,1)`) falls
+below `T_freeze + CLM:T_mask_T`. With the default value of `0`, this
+masks all grid cells at or below the freezing point (273.15 K).
+
+Both masks are evaluated independently for each patch or column.
+
+## Safety Checks ##
+
+- NaN checks are applied to all updated temperature variables; a warning
+  is printed to stdout if a NaN value is detected.
+- Clipped additive increments are counted per analysis step and the total
+  is printed for `t_skin`, `t_soisno`, `t_veg`, and `t_grnd` separately.
+- The update is skipped entirely for a given patch/column if the
+  gridcell-mean TSKIN change falls below `1e-7 K` (numerical tolerance).
+
+## Configuration Examples ##
+
+### Assimilate LST into ground and vegetation temperature (option 1) ###
+
+```text
+[CLM]
+update_T       = 1
+increment_type = 0
+```
+
+The simulated LST is computed from `t_grnd` and `t_veg` via the
+[Kustas & Anderson (2009)](https://doi.org/10.1016/j.agrformet.2009.05.016)
+radiometric mixing formula. Both variables are updated with a
+multiplicative increment.
+
+### Assimilate LST into skin and soil temperature (option 2) ###
+
+```text
+[CLM]
+update_T       = 2
+increment_type = 0
+T_mask_snow    = 1
+T_mask_T       = 0.0
+```
+
+TSKIN is used as the simulated LST. After analysis, `t_skin`, all
+`t_soisno` layers, and `t_veg` are scaled by the TSKIN increment factor.
+Snow-covered columns are excluded from the update.
+
+### Assimilate LST with additive increment and clipping (option 2) ###
+
+```text
+[CLM]
+update_T         = 2
+increment_type   = 1
+T_max_increment  = 3.0
+T_mask_T         = 2.0
+```
+
+The TSKIN increment is applied additively and clipped to ±3 K. Grid cells
+whose surface-layer temperature falls below 275.15 K (freezing + 2 K) are
+excluded.
+
+### Assimilate LST including ground temperature (option 3) ###
+
+```text
+[CLM]
+update_T       = 3
+increment_type = 0
+T_mask_snow    = 1
+```
+
+Like option 2, but `t_grnd` is additionally included in the state vector
+and updated. Snow-covered columns are masked out.