Feature: CLM snow parameterization options (parflow#695)

## Summary
Add configurable snow parameterization options for CLM.
## New Features
- **Rain-snow partitioning:** CLM, WetbulbThreshold, WetbulbLinear
methods
- **Thin snow damping:** Prevents spurious early-season melt from warm
ground
- **Albedo schemes:** CLM, VIC, Tarboton temperature-dependent aging
## New Keys (12 total)
- `Solver.CLM.SnowPartition`, `WetbulbThreshold`
- `Solver.CLM.ThinSnowDamping`, `ThinSnowThreshold`
- `Solver.CLM.AlbedoScheme`, `AlbedoVisNew`, `AlbedoNirNew`, `AlbedoMin`
- `Solver.CLM.AlbedoDecayVis`, `AlbedoDecayNir`, `AlbedoAccumA`,
`AlbedoThawA`
## Changes
- YAML schema with types, defaults, and bounds
- RST documentation with physics background
- 3 bibliography references
- 3 Python tests with reference outputs
## References
- Wang et al. (2019) GRL, doi:10.1029/2019GL085722
- Tarboton & Luce (1996) WRR, doi:10.1029/96WR01049
- Andreadis et al. (2009) JHM
## Test Plan
- [x] `clm_snow_defaults` - backward compatibility
- [x] `clm_snow_partition` - WetbulbThreshold method
- [x] `clm_snow_albedo` - Tarboton scheme
  All pass via `ctest -R clm_snow`

---------

Co-authored-by: Reed <rmaxwell@mines.edu>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Steven Smith <smith84@llnl.gov>

Author: 4 people

docs/user_manual/keys.rst

@@ -6337,6 +6337,182 @@ to be active.
    <runname>.Solver.CLM.UseSlopeAspect = True   ## Python syntax
 
 
+.. _CLM Snow Parameterization:
+
+CLM Snow Parameterization
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+These keys control snow physics options for improved snow modeling.
+All keys default to backward-compatible behavior when not set.
+Note that ``CLM`` must be compiled and linked at runtime for these
+options to be active.
+
+**Rain-Snow Partitioning**
+
+Standard ``CLM`` uses air temperature to partition precipitation into rain
+and snow. However, falling hydrometeors cool via evaporation, making
+wet-bulb temperature a better predictor, especially in dry mountain
+climates where snow can persist at air temperatures above 0°C.
+Reference: :cite:p:`Wang2019`.
+
+*string* **Solver.CLM.SnowPartition** CLM Selects the method for
+partitioning precipitation into rain and snow. The valid types for
+this key are **CLM**, **WetbulbThreshold**, **WetbulbLinear**.
+
+**CLM**:
+   Standard air temperature threshold with linear transition (default).
+
+**WetbulbThreshold**:
+   Sharp threshold at wet-bulb temperature. Better for dry mountain climates.
+
+**WetbulbLinear**:
+   Linear transition around wet-bulb temperature threshold.
+
+.. container:: list
+
+   ::
+
+      pfset Solver.CLM.SnowPartition "WetbulbThreshold"         ## TCL syntax
+      <runname>.Solver.CLM.SnowPartition = "WetbulbThreshold"   ## Python syntax
+
+*double* **Solver.CLM.WetbulbThreshold** 274.15 Threshold temperature in
+Kelvin for wetbulb partitioning methods. Default 274.15 K (1°C). Only
+used when ``Solver.CLM.SnowPartition`` is ``WetbulbThreshold`` or
+``WetbulbLinear``.
+
+.. container:: list
+
+   ::
+
+      pfset Solver.CLM.WetbulbThreshold 274.15         ## TCL syntax
+      <runname>.Solver.CLM.WetbulbThreshold = 274.15   ## Python syntax
+
+**Thin Snow Damping**
+
+Thin early-season snowpacks can experience spurious melt due to warm
+ground heat flux. This option reduces melt energy for shallow snowpacks
+to prevent premature ablation.
+
+*double* **Solver.CLM.ThinSnowDamping** 1.0 Fraction of melt energy
+retained for thin snowpacks. A value of 1.0 means no damping (default,
+backward compatible). A value of 0.1 means only 10% of melt energy is
+applied (90% reduction).
+
+.. container:: list
+
+   ::
+
+      pfset Solver.CLM.ThinSnowDamping 0.3         ## TCL syntax
+      <runname>.Solver.CLM.ThinSnowDamping = 0.3   ## Python syntax
+
+*double* **Solver.CLM.ThinSnowThreshold** 50.0 Snow water equivalent
+threshold in mm below which thin snow damping applies.
+
+.. container:: list
+
+   ::
+
+      pfset Solver.CLM.ThinSnowThreshold 50.0         ## TCL syntax
+      <runname>.Solver.CLM.ThinSnowThreshold = 50.0   ## Python syntax
+
+**Albedo Schemes**
+
+Snow albedo controls the radiation balance and strongly influences melt
+timing. Three schemes are available:
+
+*string* **Solver.CLM.AlbedoScheme** CLM Snow albedo calculation method.
+The valid types for this key are **CLM**, **VIC**, **Tarboton**.
+
+**CLM**:
+   Age-based exponential decay using the snowage variable (default).
+
+**VIC**:
+   Separate decay rates for cold (accumulating) and warm (melting)
+   conditions based on ground temperature. Reference: :cite:p:`Andreadis2009`.
+
+**Tarboton**:
+   Arrhenius temperature-dependent aging where decay accelerates near
+   the melting point. Reference: :cite:p:`Tarboton1996`.
+
+.. container:: list
+
+   ::
+
+      pfset Solver.CLM.AlbedoScheme "Tarboton"         ## TCL syntax
+      <runname>.Solver.CLM.AlbedoScheme = "Tarboton"   ## Python syntax
+
+*double* **Solver.CLM.AlbedoVisNew** 0.95 Fresh snow visible-band albedo.
+Physically ranges 0.85-0.98.
+
+.. container:: list
+
+   ::
+
+      pfset Solver.CLM.AlbedoVisNew 0.95         ## TCL syntax
+      <runname>.Solver.CLM.AlbedoVisNew = 0.95   ## Python syntax
+
+*double* **Solver.CLM.AlbedoNirNew** 0.65 Fresh snow near-infrared albedo.
+Physically ranges 0.5-0.7.
+
+.. container:: list
+
+   ::
+
+      pfset Solver.CLM.AlbedoNirNew 0.65         ## TCL syntax
+      <runname>.Solver.CLM.AlbedoNirNew = 0.65   ## Python syntax
+
+*double* **Solver.CLM.AlbedoMin** 0.4 Minimum snow albedo floor for aged
+or dirty snow.
+
+.. container:: list
+
+   ::
+
+      pfset Solver.CLM.AlbedoMin 0.4         ## TCL syntax
+      <runname>.Solver.CLM.AlbedoMin = 0.4   ## Python syntax
+
+*double* **Solver.CLM.AlbedoDecayVis** 0.5 Visible albedo decay coefficient
+for ``CLM`` and ``Tarboton`` schemes.
+
+.. container:: list
+
+   ::
+
+      pfset Solver.CLM.AlbedoDecayVis 0.5         ## TCL syntax
+      <runname>.Solver.CLM.AlbedoDecayVis = 0.5   ## Python syntax
+
+*double* **Solver.CLM.AlbedoDecayNir** 0.2 NIR albedo decay coefficient
+for ``CLM`` and ``Tarboton`` schemes. NIR typically decays faster than visible.
+
+.. container:: list
+
+   ::
+
+      pfset Solver.CLM.AlbedoDecayNir 0.2         ## TCL syntax
+      <runname>.Solver.CLM.AlbedoDecayNir = 0.2   ## Python syntax
+
+*double* **Solver.CLM.AlbedoAccumA** 0.94 VIC scheme cold-phase
+(accumulation) decay base per hour. Should be greater than ``AlbedoThawA``.
+
+.. container:: list
+
+   ::
+
+      pfset Solver.CLM.AlbedoAccumA 0.94         ## TCL syntax
+      <runname>.Solver.CLM.AlbedoAccumA = 0.94   ## Python syntax
+
+*double* **Solver.CLM.AlbedoThawA** 0.82 VIC scheme melt-phase decay base
+per hour. Should be less than ``AlbedoAccumA`` since melt conditions age
+snow faster.
+
+.. container:: list
+
+   ::
+
+      pfset Solver.CLM.AlbedoThawA 0.82         ## TCL syntax
+      <runname>.Solver.CLM.AlbedoThawA = 0.82   ## Python syntax
+
+
 .. _ParFlow NetCDF4 Parallel I/O:
 
 ParFlow NetCDF4 Parallel I/O

docs/user_manual/refs.bib

@@ -1378,3 +1378,36 @@ @misc{endian
 title = {Endianness --- Wikipedia, The Free Encyclopedia},
 url = {http://en.wikipedia.org/wiki/Endianness},
 }
+
+@article{Wang2019,
+author = {Wang, Y. and Broxton, P. and Fang, Y. and Behrangi, A. and Barlage, M. and Zeng, X. and Niu, G.},
+journal = {Geophysical Research Letters},
+number = {22},
+pages = {13104--13113},
+title = {A Wet-Bulb Temperature-Based Rain-Snow Partitioning Scheme Improves Snowpack Prediction Over the Drier Western United States},
+volume = {46},
+year = {2019},
+doi = {10.1029/2019GL085722},
+}
+
+@article{Andreadis2009,
+author = {Andreadis, K. M. and Storck, P. and Lettenmaier, D. P.},
+journal = {Journal of Hydrometeorology},
+number = {6},
+pages = {1379--1395},
+title = {Modeling Snow Accumulation and Ablation Processes in Forested Environments},
+volume = {10},
+year = {2009},
+doi = {10.1175/2009JHM1083.1},
+}
+
+@article{Tarboton1996,
+author = {Tarboton, D. G. and Luce, C. H.},
+journal = {Water Resources Research},
+number = {4},
+pages = {1195--1207},
+title = {Utah Energy Balance Snow Accumulation and Melt Model (UEB)},
+volume = {32},
+year = {1996},
+doi = {10.1029/96WR01049},
+}

pf-keys/definitions/solver.yaml

@@ -494,6 +494,146 @@ Solver:
         BoolDomain:
         RequiresModule: CLM
 
+    # -----------------------------------------------------------------------------
+    # CLM Snow Parameterization Keys
+    # -----------------------------------------------------------------------------
+
+    SnowPartition:
+      help: >
+        [Type: string] Selects the rain-snow partitioning method. CLM uses air
+        temperature threshold, while wetbulb methods account for evaporative
+        cooling of falling hydrometeors. Reference: Wang et al. (2019) GRL.
+      default: CLM
+      domains:
+        EnumDomain:
+          enum_list:
+            - CLM
+            - WetbulbThreshold
+            - WetbulbLinear
+        RequiresModule: CLM
+
+    WetbulbThreshold:
+      help: >
+        [Type: double] Threshold temperature (K) for wetbulb rain-snow partitioning.
+        Default 274.15 K (1 degree C). Only used when SnowPartition is WetbulbThreshold
+        or WetbulbLinear.
+      default: 274.15
+      domains:
+        DoubleValue:
+          min_value: 268.15
+          max_value: 278.15
+        RequiresModule: CLM
+
+    ThinSnowDamping:
+      help: >
+        [Type: double] Fraction of melt energy retained for thin snowpacks.
+        1.0 = no damping (default, backward compatible), 0.1 = 90% energy reduction.
+        Prevents spurious early-season melt from warm ground heat flux.
+      default: 1.0
+      domains:
+        DoubleValue:
+          min_value: 0.0
+          max_value: 1.0
+        RequiresModule: CLM
+
+    ThinSnowThreshold:
+      help: >
+        [Type: double] SWE threshold (mm) below which thin snow damping applies.
+      default: 50.0
+      domains:
+        DoubleValue:
+          min_value: 1.0
+          max_value: 500.0
+        RequiresModule: CLM
+
+    AlbedoScheme:
+      help: >
+        [Type: string] Snow albedo calculation method. CLM uses age-based decay,
+        VIC uses separate cold/melt decay rates based on ground temperature,
+        Tarboton uses Arrhenius temperature-dependent aging.
+        References: Andreadis et al. (2009), Tarboton and Luce (1996).
+      default: CLM
+      domains:
+        EnumDomain:
+          enum_list:
+            - CLM
+            - VIC
+            - Tarboton
+        RequiresModule: CLM
+
+    AlbedoVisNew:
+      help: >
+        [Type: double] Fresh snow visible-band albedo. Physically ranges 0.85-0.98.
+      default: 0.95
+      domains:
+        DoubleValue:
+          min_value: 0.80
+          max_value: 0.99
+        RequiresModule: CLM
+
+    AlbedoNirNew:
+      help: >
+        [Type: double] Fresh snow near-infrared albedo. Physically ranges 0.5-0.7.
+      default: 0.65
+      domains:
+        DoubleValue:
+          min_value: 0.40
+          max_value: 0.85
+        RequiresModule: CLM
+
+    AlbedoMin:
+      help: >
+        [Type: double] Minimum snow albedo floor for aged or dirty snow.
+      default: 0.4
+      domains:
+        DoubleValue:
+          min_value: 0.2
+          max_value: 0.7
+        RequiresModule: CLM
+
+    AlbedoDecayVis:
+      help: >
+        [Type: double] Visible albedo decay coefficient for CLM and Tarboton schemes.
+      default: 0.5
+      domains:
+        DoubleValue:
+          min_value: 0.1
+          max_value: 2.0
+        RequiresModule: CLM
+
+    AlbedoDecayNir:
+      help: >
+        [Type: double] NIR albedo decay coefficient for CLM and Tarboton schemes.
+        NIR typically decays faster than visible.
+      default: 0.2
+      domains:
+        DoubleValue:
+          min_value: 0.05
+          max_value: 1.0
+        RequiresModule: CLM
+
+    AlbedoAccumA:
+      help: >
+        [Type: double] VIC scheme cold-phase (accumulation) decay base per hour.
+        Should be greater than AlbedoThawA.
+      default: 0.94
+      domains:
+        DoubleValue:
+          min_value: 0.80
+          max_value: 0.99
+        RequiresModule: CLM
+
+    AlbedoThawA:
+      help: >
+        [Type: double] VIC scheme melt-phase decay base per hour.
+        Should be less than AlbedoAccumA since melt conditions age snow faster.
+      default: 0.82
+      domains:
+        DoubleValue:
+          min_value: 0.70
+          max_value: 0.95
+        RequiresModule: CLM
+
     # -----------------------------------------------------------------------------
     # CLM input variables to write drv_clmin.dat (Input) and drv_vegp.dat (VegParams) files
     # -----------------------------------------------------------------------------