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,11 @@ statevec_max_layer =
 t_printensemble =
 watmin_switch =
 swc_mask_snow =
+T_mask_snow =
+T_mask_snow_depth =
+increment_type =
+T_mask_T =
+T_max_increment =
 
 [COSMO]
 nprocs      =
@@ -479,16 +484,48 @@ 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`,
+   `min(nlevgrnd, CLM:statevec_max_layer)` 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`
+   (`min(nlevgrnd, CLM:statevec_max_layer)` layers), `t_veg`,
+   `t_grnd`.
+
+-  4: Like `2`, but additionally updates surface water temperature
+   (`t_h2osfc`). State vector: `t_skin`, `t_soisno`
+   (`min(nlevgrnd, CLM:statevec_max_layer)` layers), `t_veg`,
+   `t_h2osfc`.
+
+-  5: Like `3`, but additionally updates surface water temperature
+   (`t_h2osfc`). State vector: `t_skin`, `t_soisno`
+   (`min(nlevgrnd, CLM:statevec_max_layer)` layers), `t_veg`,
+   `t_grnd`, `t_h2osfc`.
+
+See [Land Surface Temperature Data Assimilation](lstda) for a detailed
+description.
 
 ### CLM:print_swc ###
 
@@ -546,25 +583,36 @@ If `0` (default): Use all columns and all layers.
 If `1`: Use only hydrologically active columns and only layers until
 bedrock.
 
+(enkfpf:clm:statevec_max_layer)=
 ### CLM:statevec_max_layer ###
 
 **Not yet in main branch**
 
-`CLM:statevec_max_layer`: (integer) Number of layers to add in the
-state vector.
+`CLM:statevec_max_layer`: (integer) Maximum number of soil layers
+included in the state vector.
+
+Used in two contexts:
 
-Only used, when `CLM:statevec_allcol` and `CLM:statevec_only_active`
-are switched on.
+- **SWC state vector**: when `CLM:statevec_allcol` and
+  `CLM:statevec_only_active` are both switched on, limits the number
+  of soil layers included per column.
+- **T state vector**: when `CLM:update_T` is `2`, `3`, `4`, or `5`,
+  limits the number of `t_soisno` layers included. The effective number
+  of layers is `min(nlevgrnd, CLM:statevec_max_layer)`.
 
-If `25` (default): All layers are in state vector.
+If `25` (default): All layers are in the state vector (CLM5 has 25
+soil layers by default, so this effectively means no restriction).
 
-If `9`: Only the first nine layers in state vector (corresponds to 1.2
-meter).
+If `9`: Only the first nine layers are included (corresponds to
+approximately 1.2 m depth).
 
 For a depth profile of CLM layers, see [CLM Technical Note: 2.2.2.1
 Soil
 Layers](https://escomp.github.io/ctsm-docs/versions/master/html/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.html#soil-layers).
 
+See [Land Surface Temperature Data Assimilation](lstda) for context on
+the T state vector use.
+
 ### CLM:t_printensemble ###
 
 `CLM:t_printensemble`: (integer) The timestep for the state ensemble
@@ -595,12 +643,76 @@ 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.
+
+When set to `1`, columns with a snow depth exceeding
+`CLM:T_mask_snow_depth` are excluded from the temperature update.
+
+Only takes effect if `CLM:update_T` is switched on.
+
+Default setting is `0`: No masking of columns with snow cover.
+
+(enkfpf:clm:T_mask_snow_depth)=
+### CLM:T_mask_snow_depth ###
+
+`CLM:T_mask_snow_depth`: (double) Snow depth threshold (m) used by
+the snow masking condition. Columns with `snow_depth >=
+CLM:T_mask_snow_depth` are excluded from the temperature update when
+`CLM:T_mask_snow = 1`.
+
+Only takes effect if `CLM:update_T` and `CLM:T_mask_snow` are both
+switched on.
+
+Default setting is `0.001` (1 mm).
+
+(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 +974,7 @@ Default: 0, output turned off.
 ## Parameter Summary ##
 
  | section   | parameter               | default value |
- |:---------:|:-----------------------:|:-------------:|
+ |:----------|:------------------------|:--------------|
  | `[PF]`    |                         |               |
  |           | `problemname`           | \-            |
  |           | `nprocs`                | 0             |
@@ -892,6 +1004,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 +1014,11 @@ Default: 0, output turned off.
  |           | `statevec_max_layer`    | 25            |
  |           | `t_printensemble`       | -2            |
  |           | `watmin_switch`         | 0             |
+ |           | `T_mask_snow`           | 0             |
+ |           | `T_mask_snow_depth`     | 0.001         |
+ |           | `increment_type`        | 0             |
+ |           | `T_max_increment`       | 5.0           |
+ |           | `T_mask_T`              | 0.0           |
  | `[COSMO]` |                         |               |
  |           | `nprocs`                | 0             |
  |           | `dtmult`                | 0             |