reedmaxwell · reedmaxwell · Apr 16, 2026
diff --git a/README.md b/README.md
diff --git a/clm_inputs/README.md b/clm_inputs/README.md
@@ -0,0 +1,97 @@
+# CLM Input Files
+
+Shipped CLM driver files for both the ET and snow examples. These track the
+"best-practice" files published in
+[parflow/parflow PR #714](https://github.com/parflow/parflow/pull/714)
+(`feature/clm_driver_cleanup` → master).
+
+## Current Layout
+
+```
+clm_inputs/
+├── drv_clmin_template.dat   # shared (ET + snow) — exact copy of
+│                            #   test/tcl/clm/drv_clmin_bestpractice.dat
+├── et/
+│   └── drv_vegp.dat         # copy of test/tcl/clm/drv_vegp_bestpractice.dat
+└── snow/
+    └── drv_vegp.dat         # currently identical to et/drv_vegp.dat
+```
+
+Each notebook copies the topic-specific `drv_vegp.dat` into its run directory
+and patches `drv_clmin_template.dat`'s date fields for the selected water year.
+
+## Why the two `drv_vegp.dat` files are identical
+
+The PR #714 best-practice `drv_vegp.dat` is topic-agnostic — it carries the
+full IGBP PFT table with all improvements needed by either example:
+
+- CLM4.5 optical/structural corrections (grass, savanna, crop)
+- PFT-specific photosynthesis (`vcmx25` + C3/C4 fixes)
+- Medlyn stomatal conductance (`g1_medlyn`)
+- Canopy clumping index (`clump`, He et al. 2012)
+- Foliage nitrogen (`folnmx`)
+
+None of those hurt a snow run — the snow-specific tuning lives outside this
+file, in the ParFlow run script (`run.Solver.CLM.*` keys) and in the
+site-specific `drv_vegm.dat` (IGBP=7 for the shrubland snow default).
+
+So today, `et/drv_vegp.dat` and `snow/drv_vegp.dat` are byte-identical copies
+of the same upstream file. The duplication is intentional — it keeps the
+door open for topic-specific tuning without a restructure.
+
+## Planned Consolidation
+
+When we're confident neither topic needs per-topic vegp overrides, collapse to:
+
+```
+clm_inputs/
+├── drv_clmin_template.dat   # unchanged
+└── drv_vegp.dat             # single shared best-practice file
+```
+
+And update the two topic notebooks:
+
+| File | Change |
+|------|--------|
+| `et/locate_plot_station_get_forcing.ipynb` | `Path("../clm_inputs/et")` → `Path("../clm_inputs")` |
+| `snow/locate_plot_station_get_forcing.ipynb` | `Path("../clm_inputs/snow")` → `Path("../clm_inputs")` |
+
+That's a three-line change (two notebook edits + delete the two subdirs).
+
+### Triggers that would *prevent* consolidation
+
+Reasons we might end up keeping the split:
+
+1. **Snow-specific PFT tuning**. If future work finds that snow-site canopy
+   radiation/transpiration benefits from different `z0m`, `displa`, `rhol_*`,
+   `taul_*` values at high-elevation shrubland sites, those would live in
+   `snow/drv_vegp.dat` and diverge from the ET file.
+2. **Different `vcmx25` regimes for snow vs. ET sites**. Unlikely but
+   possible if PFT photosynthesis is retuned for cold/dormant-season behavior.
+3. **Experimental physics branches**. If a future branch ships a new
+   `drv_vegp.dat` format with extra columns for one topic only.
+
+None of these apply today.
+
+## Upstream Tracking
+
+When `parflow/master` updates either best-practice file, refresh both copies
+here. The fastest check is a `diff` against the upstream raw files:
+
+```bash
+for f in drv_clmin_bestpractice drv_vegp_bestpractice; do
+  curl -sL "https://raw.githubusercontent.com/parflow/parflow/master/test/tcl/clm/${f}.dat" | \
+    diff - clm_inputs/${f%_bestpractice}_template.dat  # or et/drv_vegp.dat, snow/drv_vegp.dat
+done
+```
+
+(Adjust target paths — `drv_clmin_bestpractice` lands in
+`clm_inputs/drv_clmin_template.dat`, `drv_vegp_bestpractice` lands in both
+`clm_inputs/et/drv_vegp.dat` and `clm_inputs/snow/drv_vegp.dat`.)
+
+## Background
+
+- PR #714: "Document CLM driver files and remove dead parameters"
+  (feature/clm_driver_cleanup, merged March 2026).
+- Related PRs: #712 (CLM ET improvements), #695/#698/#701/#709 (snow).
+- See the top-level `README.md` for the complete merged-PR table.
diff --git a/clm_inputs/drv_vegp.dat → clm_inputs/et/drv_vegp.dat b/clm_inputs/drv_vegp.dat → clm_inputs/et/drv_vegp.dat
diff --git a/clm_inputs/snow/drv_vegp.dat b/clm_inputs/snow/drv_vegp.dat
@@ -0,0 +1,176 @@
+!=========================================================================
+! ParFlow-CLM vegetation parameter file (IGBP classification)
+!
+! Part of ParFlow v3.14 (March 2026)
+! https://parflow.org | https://github.com/parflow/parflow
+! Originally based on CLM 1.0 (Dai et al. 2003)
+!
+! References:
+!  Maxwell & Miller (2005) J. Hydrometeorol. — ParFlow-CLM coupling
+!  Kollet & Maxwell (2008) Water Resour. Res. — Integrated watershed model
+!  Maxwell & Condon (2016) Science, SI — Coupling approach, parameter tables
+!  Kuffour et al. (2020) Geosci. Model Dev. — ParFlow v3.5 description
+!=========================================================================
+! drv_vegp_bestpractice.dat:
+!
+! DESCRIPTION:
+!  Best-practice vegetation parameters with CLM4.5 optical/structural
+!  corrections, PFT-dependent photosynthesis, and canopy clumping.
+!
+!  Changes from default drv_vegp.dat:
+!    - CLM4.5 optical corrections for grass/savanna/crop (IGBP 8-10, 12):
+!        taus_vis, taus_nir → 0.001 (CLM4.5 Table 3.1)
+!        rhos_vis → 0.16, rhos_nir → 0.39
+!        rhol_nir: IGBP 9,10,12: 0.58 → 0.35
+!    - CLM4.5 structural: IGBP 10 sai 4.0→0.5, roota 1.0→11.0 (Zeng 2001)
+!    - C3/C4 photosynthesis parameter fixes
+!    - Medlyn stomatal conductance (g1_medlyn)
+!    - Foliage nitrogen (folnmx)
+!    - Canopy clumping index (clump) for radiation calculations
+!
+!  Presence of vcmx25 keyword activates PFT-specific photosynthesis.
+!
+!  Parameter sources:
+!    Oleson et al. (2013) CLM4.5 Tech Note — Optical/structural corrections
+!    Jefferson et al. (2017) J. Hydrometeorol. — Photosynthesis sensitivity
+!    Medlyn et al. (2011), Lin et al. (2015) — Stomatal conductance
+!    He et al. (2012) / Lawrence et al. (2019) — Canopy clumping index
+!
+! REVISION HISTORY:
+!  1998-1999: Yongjiu Dai, Xubin Zeng; Original CLM code (NCAR)
+!  2004-2009: Reed Maxwell, Stefan Kollet; ParFlow-CLM coupling
+!  2009: Ian Ferguson; Irrigation schemes
+!  2014: Nick Engdahl; Stomatal resistance multiplier, output controls
+!  2016: Reed Maxwell, Bryant Reyes; Under-canopy drag (csoilc) correction
+!  2017: Jennifer Jefferson; ET and transpiration improvements
+!  2018-2019: Lindsay Bearup, Anna Ryken; Snow parameterizations
+!  2022: Reed Maxwell; CLM update
+!  Jan-Mar 2026: Reed Maxwell; Snow parameterizations, ET improvements,
+!                PFT photosynthesis, Medlyn stomata, canopy clumping,
+!                CLM4.5 optical/structural corrections, driver cleanup
+!=========================================================================
+!IGBP Land Cover Types
+!  1 evergreen needleleaf forests
+!  2 evergreen broadleaf forests
+!  3 deciduous needleleaf forests
+!  4 deciduous broadleaf forests
+!  5 mixed forests
+!  6 closed shrublands
+!  7 open shrublands
+!  8 woody savannas
+!  9 savannas
+! 10 grasslands
+! 11 permanent wetlands
+! 12 croplands
+! 13 urban and built-up lands
+! 14 cropland / natural vegetation mosaics
+! 15 snow and ice
+! 16 barren or sparsely vegetated
+! 17 water bodies
+! 18 bare soil
+!=========================================================================
+!
+itypwat        (1-soil, 2-land ice, 3-deep lake, 4-shallow lake, 5-wetland: swamp, marsh)
+1 1 1 1 1 1 1 1 1 1 5 1 1 1 2 1 3 1
+!
+lai            Maximum leaf area index [-]
+6.00 6.00 6.00 6.00 6.00 6.00 6.00 6.00 6.00 2.00 6.00 6.00 5.00 6.00 0.00 6.00 0.00 0.00
+!
+lai0           Minimum leaf area index [-]
+5.00 5.00 1.00 1.00 3.00 2.00 1.00 2.00 1.00 0.50 0.50 0.50 1.00 2.00 0.00 0.50 0.00 0.00
+!
+sai            Stem area index [-]
+2.00 2.00 2.00 2.00 2.00 2.00 2.00 2.00 2.00 0.50 2.00 0.50 2.00 2.00 2.00 2.00 2.00 0.00
+!              CLM4.5: IGBP 10 sai 4.0→0.5
+!
+z0m            Aerodynamic roughness length [m]
+1.00 2.20  1.00 0.80 0.80 0.10 0.10 0.70 0.10 0.03 0.03 0.06 0.50 0.06 0.01 0.05 0.002 0.01
+!
+displa         Displacement height [m]
+11.0 23.00 11.0 13.0 13.0 0.30 0.30 6.50 0.70 0.30 0.30 0.30 3.00 0.30 0.00 0.10 0.00  0.00
+!
+dleaf          Leaf dimension [m]
+0.04 0.04 0.04 0.04 0.04 0.04 0.04 0.04 0.04 0.04 0.04 0.04 0.04 0.04 0.04 0.04 0.04 0.00
+!
+roota          Fitted numerical index of rooting distribution
+7.00 7.00 7.00 6.00 5.00 6.00 5.00 6.00 5.00 11.00 6.00 6.00 5.00 5.00 0.00 5.00 0.00 0.00
+!              CLM4.5: IGBP 10 roota 1.0→11.0 (Zeng 2001)
+!
+rootb          Fitted numerical index of rooting distribution
+2.00 1.00 2.00 2.00 1.50 1.50 2.50 2.50 1.00 2.50 2.00 2.50 2.00 2.00 0.00 2.00 0.00 0.00
+!
+rhol_vis       !leaf reflectance vis
+0.07 0.10 0.07 0.10 0.08 0.08 0.08 0.09 0.11 0.11 0.11 0.11 0.09 0.09 -99. 0.09 -99. -99.
+!
+rhol_nir       !leaf reflectance nir
+0.35 0.45 0.35 0.45 0.40 0.40 0.40 0.49 0.35 0.35 0.35 0.35 0.47 0.47 -99. 0.47 -99. -99.
+!              CLM4.5: IGBP 9,10,12 rhol_nir 0.58→0.35
+!
+rhos_vis       !stem reflectance vis
+0.16 0.16 0.16 0.16 0.16 0.16 0.16 0.16 0.16 0.16 0.36 0.16 0.24 0.24 -99. 0.24 -99. -99.
+!              CLM4.5: IGBP 8,9,10,12 rhos_vis →0.16
+!
+rhos_nir       !stem reflectance nir
+0.39 0.39 0.39 0.39 0.39 0.39 0.39 0.39 0.39 0.39 0.39 0.39 0.47 0.47 -99. 0.47 -99. -99.
+!              CLM4.5: IGBP 8,9,10,12 rhos_nir →0.39
+!
+taul_vis       !leaf transmittance vis
+0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.06 0.07 0.07 0.07 0.07 0.06 0.06 -99. 0.06 -99. -99.
+!
+taul_nir       !leaf transmittance nir
+0.10 0.25 0.10 0.25 0.17 0.17 0.17 0.21 0.25 0.25 0.10 0.25 0.20 0.20 -99. 0.20 -99. -99.
+!
+taus_vis       !stem transmittance vis
+0.001 0.001 0.001 0.001 0.001 0.001 0.001 0.001 0.001 0.001 0.22 0.001 0.09 0.09 -99. 0.09 -99. -99.
+!              CLM4.5: IGBP 8,9,10,12 taus_vis →0.001 (Table 3.1)
+!
+taus_nir       !stem transmittance nir
+0.001 0.001 0.001 0.001 0.001 0.001 0.001 0.001 0.001 0.001 0.001 0.001 0.15 0.15 -99. 0.15 -99. -99.
+!              CLM4.5: IGBP 8,9,10,12 taus_nir →0.001 (Table 3.1)
+!
+xl             !leaf/stem orientation index
+0.01  0.10  0.01  0.25  0.13  0.13  0.13 -0.08 -0.3 -0.3  -0.3  -0.3 -0.07 -0.07 -99. -0.07  -99. -99.
+!
+vw             !btran exponent:[(h2osoi_vol-watdry)/(watopt-watdry)]**vw
+1. 1. 1. 1. 1. 1. 1. 1. 1. 1. 1. 1. 1. 1. -99. 1. -99. -99.
+!
+irrig          !(irrig=0 -> no irrigation, irrig=1 -> irrigate)
+0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
+!
+! --- PFT-Specific Photosynthesis Parameters ---
+!   Presence of vcmx25 activates PFT-specific photosynthesis in CLM.
+!   Without these, CLM uses hardcoded defaults from clm_varcon.F90.
+!
+vcmx25         Maximum rate of carboxylation at 25C (umol CO2/m2/s)
+51. 62. 39. 57. 54. 17. 17. 40. 40. 24. 52. 50. 50. 24. 0. 17. 0. 0.
+!              C3/C4 fix: IGBP 10 (GRA) 52→24 (C4), IGBP 14 50→24 (C4)
+!
+c3psn          Photosynthetic pathway (1=C3, 0=C4)
+1. 1. 1. 1. 1. 1. 1. 1. 1. 0. 1. 0. 1. 0. 0. 0. 0. 0.
+!              IGBP 10 (GRA)=C4, IGBP 12 (CRO)=C4 (temperate default)
+!
+mp             Ball-Berry slope parameter
+9. 9. 9. 9. 9. 9. 9. 9. 9. 4. 9. 4. 9. 4. 0. 9. 0. 0.
+!              C4 types use mp=4 (Collatz et al. 1992)
+!
+bp             Minimum leaf conductance (umol/m2/s)
+2000. 2000. 2000. 2000. 2000. 2000. 2000. 2000. 2000. 40000. 2000. 40000. 2000. 40000. 2000. 2000. 2000. 2000.
+!              C4 types use bp=40000 (Collatz et al. 1992)
+!
+qe25           Quantum efficiency at 25C (umol CO2/umol photon)
+0.06 0.06 0.06 0.06 0.06 0.06 0.06 0.06 0.06 0.05 0.06 0.04 0.06 0.05 0. 0.06 0. 0.
+!              C4 fix: IGBP 10 0.04→0.05, IGBP 14 0.04→0.05
+!
+folnmx         Foliage nitrogen concentration when f(N)=1 (%)
+1.5 1.5 1.5 1.5 1.5 1.5 1.5 1.5 1.5 1.5 1.5 1.5 1.5 1.5 1.5 1.5 1.5 1.5
+!
+g1_medlyn      Medlyn stomatal slope parameter (kPa^0.5)
+2.35 4.12 2.35 4.45 3.50 4.70 4.70 4.45 4.45 1.62 5.25 1.79 4.00 1.62 0. 4.70 0. 0.
+!              Medlyn et al. (2011); values from Lin et al. (2015)
+!              C3/C4 fix: IGBP 9 1.62→4.45 (C3 savanna), IGBP 10 5.25→1.62 (C4),
+!                         IGBP 12 5.79→1.79 (C4), IGBP 14 5.25→1.62 (C4)
+!
+clump          Vegetation clumping index (0-1, 1=no clumping)
+0.62 0.72 0.58 0.76 0.69 0.84 0.84 0.78 0.78 0.95 0.80 0.95 0.95 0.95 1.0 0.95 1.0 1.0
+!              He et al. (2012); values by IGBP class from global dataset
+!