Imported from lzwei196/KISS-Knowledge-Infrastructure-for-Scientific-Simulation (models/SHAW/SKILL.md). Install upstream with npx skills add lzwei196/KISS-Knowledge-Infrastructure-for-Scientific-Simulation --skill SHAW. Copyright stays with the author.

MANDATORY EXECUTION POLICY — READ BEFORE PROCEEDING

You MUST run the actual model binary or package described in this document. If the model fails to import, compile, or execute, you MUST:

1. Check diagnostics/triplets.yaml for a matching error pattern
2. Try the fix suggested in the triplet's remedy section
3. If still failing, report the error to the user with full details

You MUST NOT substitute a simplified Python formula, regression equation, or hand-coded approximation in place of the real model. Doing so produces scientifically invalid results and defeats the purpose of the KI.

Before starting, run: python preflight_check.py (in this KI directory)

HWSD soil lookup: Use from ki_tools_common.soil_utils import lookup_hwsd to get sand/silt/clay/OC/pH for any lat/lon. Returns texture class and Saxton-Rawls hydraulic properties. to verify that the model binary/package and required data are available.

DEBUGGING PROTOCOL — When something goes wrong, follow this order:

1. Check triplets — diagnostics/triplets.yaml may already cover this error
2. Read official docs — The model's own documentation for expected formats/units
3. Find working examples — Check outputs/ or the model's shipped test data
4. Fix the tool — With knowledge of what "correct" looks like

Do NOT write custom debug scripts. The answers are in the docs and examples.

KI map — what to read, and when

Projected 2026-08-17 from the KI's actual contents — 8 components present. Refresh: python3 ki_tools_common/generate_skill_map.py --ki_dir <this KI>.

Executable tool index (projected — complete by construction)

Every public tool in this KI, by exact path. What each is FOR lives in the human-written Tool Inventory above; --help on any of these prints its arguments.

13 public tools; _-prefixed helpers and packaging files excluded.

1. Model Identity

2. What This Model Does

SHAW simulates coupled heat, water, and solute transfer through a vertical soil-plant-snow-residue-atmosphere system. It is used here for detailed freeze-thaw, soil temperature, soil moisture, snowpack, canopy energy balance, and solute profile behavior that simplified land-surface frost schemes cannot resolve.

3. Input Requirements

Exact shapes live in docs/format_spec.yaml (projected from dag + triplets; regenerate it after changing either source, never hand-edit it). This section explains the operational intent and common traps; the spec file is the contract.

3.1 Meteorological Forcing

3.2 Static Inputs

3.3 Configuration Files

4. Build Instructions

The binary is already compiled at KISSPATH_BINARIES/shaw/shaw303.

cd KISSPATH_BINARIES/shaw
bash compile.sh

The shipped compile script uses gfortran legacy compatibility flags and writes Shaw303/shaw303, with KISSPATH_BINARIES/shaw/shaw303 as the runnable symlink. There is no Code/ path to invent.

Known build issue: gfortran 10+ requires legacy argument-mismatch compatibility, already handled by compile.sh.

5. Execution

Always run python preflight_check.py in this KI directory before debugging a model run.

cd /path/to/input/files
printf "Trial.303.inp\n\n" | KISSPATH_BINARIES/shaw/shaw303

SHAW reads the .inp file path from stdin and then waits for a final Enter. It may exit with a benign Fortran EOF backtrace after writing complete .out files; judge success by non-empty output files, not by return code alone.

6. Output Description

Source: dag.yaml. The dag is the model identity for observable outputs. If this section and dag.yaml ever disagree, dag.yaml wins and this section is stale.

Headline output (the dag's validation_rank: 1 variable; this is the output SHAW is judged by):

soil_temperature_profile — Per-node soil temperature T(z,t); primary validation target. (degC)

Operational SHAW files that commonly carry these outputs are listed in the legacy "Output Files" section below. Use dag.yaml for validation-rank, observability, and canonical units.

7. Tool Inventory

Shared utilities should be used instead of ad hoc extraction code:

from ki_tools_common.load_forcing import load_daily_forcing
from ki_tools_common.soil_utils import lookup_hwsd

8. Unit Table / Unit Conversion Table

This unit table documents the conversions and traps stated by the KI body. For exact I/O shapes, read docs/format_spec.yaml; for canonical output units, read dag.yaml.

8c. Sign Conventions and Output Units

9. Diagnostic Triplets (Top 5)

Check diagnostics/triplets.yaml before debugging. The full corpus stays in YAML; this table only points to common SHAW-specific failures already named in this SKILL.

10. Coupling Interfaces

11. Validated Results

Headline Validation Target

The dag's rank-1 output is soil_temperature_profile, unit degC, described as: "Per-node soil temperature T(z,t); primary validation target."

Performance Bars — from docs/validation_convention.yaml

Every threshold below is the convention threshold and carries its citation key. Do not substitute remembered hydrology thresholds; the convention wins.

No convention-sourced achieved NSE value for soil_temperature_profile is stated in the extracted facts above. The validation narratives below report site-specific RMSE, Bias, R2, frost/snow behavior, and water-balance checks; do not recast those as NSE verdicts unless the metric is computed against the convention.

Existing Validation Cases in This SKILL

12. Parameter Selection by Region

These are physically informed starting rules already stated by the KI, not calibration replacements.

Data Preparation

Forcing data

Data Sources: Use from ki_tools_common.load_forcing import load_daily_forcing for CMFD/MSWX/NASA POWER. SHAW forcing tool is in s2_weather_prep/tools/ in this KI:

• s2_weather_prep/tools/convert_forcing_to_shaw.py — Converts CMFD/MSWX/NASA POWER to SHAW weather format (hourly or daily); handles specific humidity→RH, pressure Pa→kPa, solar radiation units

Data Validation Reference: See data_ki/CMFD/SKILL.md for CMFD unit documentation and known traps. See data_ki/HWSD/SKILL.md for soil property documentation.

SHAW Model (Simultaneous Heat and Water) v3.03 — Knowledge Infrastructure

What is SHAW?

The Simultaneous Heat and Water (SHAW) model is a 1D field-scale model that simulates coupled heat, water, and solute transfer through a soil-plant-snow-residue-atmosphere system. Developed by Gerald N. Flerchinger at USDA-ARS Northwest Watershed Research Center (Boise, Idaho).

SHAW is one of the most detailed models available for:

• Soil freezing and thawing — detailed ice content profiles, frost depth, freeze-thaw cycles
• Snowmelt — multi-layer snowpack with grain metamorphism, density evolution, albedo decay
• Crop residue layer — explicit heat/water transfer through standing dead material and surface litter
• Multi-species plant canopy — stomatal resistance, transpiration, canopy energy balance
• Solute transport — up to 10 solute types with advection-dispersion

SHAW vs RZ-SHAW (Why Standalone?)

The standalone version has more physics options and is required for detailed freeze-thaw studies, snow research, and CO2 flux simulation.

Installation

Requirements

• Compiler: gfortran (GNU Fortran) or any Fortran 77 compiler
• No external dependencies — pure Fortran 77, self-contained
• OS: Linux, macOS, Windows (with MinGW or Cygwin)

Compilation

The binary is ALREADY COMPILED at KISSPATH_BINARIES/shaw/shaw303 (a symlink to model/shaw/Shaw303/shaw303). To rebuild, use the shipped script (handles gfortran 10+ legacy flags) — do NOT invent a Code/ path, there is none:

cd KISSPATH_BINARIES/shaw
bash compile.sh    # gfortran -O2 -w -std=legacy -fallow-argument-mismatch
                   #   -o Shaw303/shaw303 Shaw303/Code+Debug/Shaw303.for
                   # + symlink model/shaw/shaw303

Running

cd /path/to/input/files
KISSPATH_BINARIES/shaw/shaw303
# When prompted, enter: Trial.303.inp

SHAW reads from stdin — it prompts for the .inp file path AND a final "Press Enter to end". For automation, pipe BOTH (triplet shaw_024):

printf "Trial.303.inp\n\n" | KISSPATH_BINARIES/shaw/shaw303

NOTE: SHAW normally exits with a benign Fortran EOF backtrace (non-zero return code) when it reaches the end of the weather file, yet writes COMPLETE output. Judge success by non-empty .out files, not by the return code (triplet shaw_018).

Input Files (5 required + 3 optional)

Required Files

Optional Files

Weather File Format

Hourly (MTSTEP=0):

JD  JH  JYR  TA  WIND  HUM  PRECIP  SNODEN  SUNHOR

• TA: Air temperature (C)
• WIND: Wind speed (m/s with IFLAGSI=1, else mph)
• HUM: Relative humidity (%)
• PRECIP: Precipitation (mm with IFLAGSI=1, else inches)
• SNODEN: New snow density (g/cm3, 0=auto-calculate)
• SUNHOR: Total solar radiation on horizontal surface (W/m2)

Daily (MTSTEP=1):

JD  JYR  TMAX  TMIN  TDEW  WIND  PRECIP  SOLAR

• TMAX/TMIN: Max/min daily air temperature (C)
• TDEW: Dew-point temperature (C)
• WIND: Average wind speed (m/s with IFLAGSI=1, else miles/day)
• PRECIP: Daily precipitation (mm with IFLAGSI=1, else inches)
• SOLAR: Average daily solar radiation (W/m2)

UNIT TRAPS (CRITICAL)

Site File Structure

The site file (.sit) has a complex multi-section structure:

• Lines A-E: General info (title, dates, location, materials, roughness)
• Lines F: Plant canopy parameters (if NPLANT > 0)
• Line G: Snow parameters
• Line H: Residue parameters (if NR > 0)
• Lines I: Solute parameters (if NSALT > 0)
• Lines J: Soil properties (boundary conditions, albedo, water retention curve, per-layer properties)

Soil Water Retention Options (IWRC)

⚠️ Soil Node Column Format — IWRC=1 (Campbell) — ACTUAL .sit format

The actual binary format used by SHAW v3.03 for each soil node line is 12 columns:

DEPTH  SAND  SILT  CLAY  OM  KSAT  BD  THETA_INIT  TINIT  BCAP  QUARTZ  BPAR

WARNING — template trap: The Compton Quebec template ships with QUARTZ=8.5 and BPAR=30.0 — both physically impossible or wrong. QUARTZ must be 0–1. BPAR=30 means soil stays liquid to −150°C, disabling freeze-thaw simulation. ALWAYS apply pedotransfer corrections (see below).

⚠️ BPAR and QUARTZ — Pedotransfer Functions (CRITICAL for freeze-thaw)

BPAR (Campbell's b) controls both:

• Water retention curve shape: ψ = BCAP × (θ/θ_sat)^(−BPAR)
• Freeze-thaw: unfrozen water at temperature T < 0°C: θ_L/θ_sat = (6230/|BCAP|)^(−1/BPAR)

With BPAR=30: 72% liquid water at −15°C → soil never freezes. With BPAR=6–9 (correct for loam/clay): 5–20% liquid at −15°C → realistic freeze-thaw.

Pedotransfer functions (apply via fix_bpar_quartz_from_texture() in setup_shaw_from_template.py):

# Rawls et al. (1982) — Campbell b from texture
bpar   = 3.10 + 0.157 * clay - 0.003 * sand     # typical NE China: 6–10
bpar   = max(2.0, min(12.0, bpar))               # clamped

# Johansen (1975) — quartz fraction from sand content  
quartz = min(0.85, max(0.10, sand/100.0 * 0.9 + 0.10))

# Cosby et al. (1984) — BCAP (air-entry, m, negative)
bcap   = -0.01 * (10.0 ** (1.54 - 0.0095*sand + 0.0063*(100-sand-clay)))
bcap   = max(bcap, -1.0)
bcap   = min(bcap, -0.05)

Always call after template setup:

from models.SHAW.knowledge_infrastructure.tools.s1_site_setup.setup_shaw_from_template import fix_bpar_quartz_from_texture
n = fix_bpar_quartz_from_texture(sit_path)

Or from run_shaw_parallel.py — fix_bpar_quartz_in_sit(sit_path) is defined inline and called after every template setup.

Output Files (up to 19)

Pipeline (7 stages)

s1_site_setup

Generate the .sit file from HWSD soil database + DEM slope/aspect + land cover.

s2_weather_prep

Convert CMFD/MSWX/NASA POWER forcing to SHAW weather format.

s3_plant_config

Configure plant canopy parameters from AVHRR land cover or DSSAT crop parameters.

s4_initial_conditions

Generate initial soil moisture and temperature profiles from VIC output or climatology.

s5_snow_residue_config

Configure snow parameters and crop residue layer properties.

s6_execution

Run SHAW model, monitor progress, parse output files.

s7_vic_coupling

Convert VIC grid cell parameters to SHAW format, run SHAW per cell for enhanced freeze-thaw.

VIC Coupling Strategy

SHAW provides detailed freeze-thaw physics that VIC's simplified frost scheme cannot match. The coupling approach:

1. Run VIC normally to get grid-cell water/energy balance
2. For cells where freeze-thaw is important (high latitude, high altitude):
   • Convert VIC soil parameters to SHAW format (via vic_to_shaw_soil.py)
   • Convert CMFD/MSWX forcing to SHAW weather format (via convert_forcing_to_shaw.py)
   • Initialize SHAW from VIC soil moisture/temperature
   • Run SHAW per cell for detailed frost depth, ice content, freeze-thaw timing
3. Use SHAW output to correct VIC's infiltration/runoff during frozen soil periods

Fortran 77 Traps (from PREFLIGHT)

Key References

• Flerchinger, G.N. (2017). The Simultaneous Heat and Water (SHAW) Model: User's Manual Version 3.0.x. Technical Report NWRC 2017-01.2.
• Flerchinger, G.N., Saxton, K.E. (1989). Simultaneous heat and water model of a freezing snow-residue-soil system. Trans. ASAE, 32(2):565-571.
• Flerchinger, G.N., Pierson, F.B. (1991). Modeling plant canopy effects on variability of soil temperature and water. Agric. For. Meteorol., 56:227-246.

Validated: JackPine Boreal Forest (OJP BERMS), Saskatchewan, Canada

Data source: BERMS (Boreal Ecosystem Research and Monitoring Sites)

• Operated by Environment and Climate Change Canada (ECCC)
• Site: Old Jack Pine (OJP), ~53.916°N, 104.692°W, 580m elevation
• Part of FLUXNET / AmeriFlux network
• Local path: KISSPATH_DATA/observedST-SM/soil_temperatureand_soil_moisture_canada/sas_forest/
• Reference: Barr et al. (2012) JGR-Biogeosciences; Zha et al. (2010) Global Change Biology

Data used:

• JackPine_Met.csv — 30-min: T, P, SWi, RH, WS, LWi (1998-2016)
• JackPine_Soil.csv — 30-min: VWC (5 depths) + ST (6 depths: 2,5,10,20,50,100 cm)
• JackPine_Snow.csv — 30-min: SnowT, SD_Clearing, SD_BlwCanopy

Simulation: 1999, hourly timestep, 365 days, ~30 seconds runtime

Soil Temperature Performance (uncalibrated)

Water Balance

• Annual P: 466 mm (literature ~430 mm)
• ET: 499 mm
• Snowmelt: 47 mm

Input Format Issues Found (3 triplets)

• dt_v003: MCANFLG=0 must NOT have root distribution line
• dt_v004: NSALT=0 must NOT have ASALT/DISPER columns
• dt_v005: Weather file needs +24h padding for EOF avoidance

Output files

All at outputs/shaw_jackpine/: 6 validation plots + SHAW input/output files

Validated: Manitoba Station 544 (Alexander Prairie), Canada

Data source: Manitoba Agriculture Weather Program (MAWP)

• Station 544, Alexander, Manitoba (49.81°N, 100.37°W, 460m elevation)
• Prairie grassland (no canopy, MCANFLG=0)
• Local path: KISSPATH_DATA/observedST-SM/soil_temperatureand_soil_moisture_canada/manitoba/
• Soil temperature at 4 depths: 5, 20, 50, 100 cm

Simulation: Nov 2019 – Oct 2020, daily weather input (MTSTEP=1), 364 days

Soil Temperature Performance (uncalibrated)

Frost & Snow

• Max frost depth: 25.1 cm (realistic for thin snowpack)
• Max snow depth: 11.8 cm, SWE: 11.8 mm (low — station precip gauge undercounts snow)
• Cold bias (-2 to -3°C) caused by insufficient snow insulation

Water Balance

• Annual ET: ~208 mm (expected ~350 mm — low due to precip undercatch)
• Freeze-thaw cycle captured: soil freezes Nov-Mar, thaws by April

Errors Found During Validation (6 triplets: shaw_026-031)

Key Lesson: Daily vs Hourly Weather

SHAW supports BOTH formats via the MTSTEP flag in .inp Line B:

CRITICAL: The daily format has NO hour column and uses TMAX/TMIN (not instantaneous TA). SOLAR is average daily W/m² (not instantaneous). Always verify column count matches MTSTEP.

Output files

All at outputs/shaw_manitoba_544/: validation_soil_temp.png, validation_frost_snow.png

Validated: NE China Black Soil Domain — 6 Stations (2021–2022)

Data source: Black Soil Observation Data NE China V2.0 (32 AWS/soil stations)

• Local path: data/china_data/BlackSoilObsData_NE_China_V2.0/ObservationData/
• Sensor: combined AWS with TDR soil moisture + soil temperature at a single depth
• Format: xlsx, header at row 10, ~30-min records
• Column format varies by station (8–15 columns): use column index, not name matching

6 validation cells and station mapping:

Observed monthly soil moisture (% VWC) — EcologicalQiqihar (best station, 2 full years):

Growing season (May–Oct) mean: 35.5% | Winter (Nov–Mar) mean: 18.2% (liquid only)

Literature reference (Chinese Geographical Science, Springer):
NE China Mollisol field capacity = 23.5–37% VWC, mean 31.65% across 113 soil profiles.
Winter liquid water (frozen Mollisol, 5–20cm): 0–10% VWC in frozen layers [from-memory, unverified beyond search result].

Key obs data notes:

• EcologicalQiqihar is the only station with complete freeze-thaw cycle data (Qiqihar city, MWRC experimental base)
• YianVegetables and LishuSiping measure at 20–40cm — not directly comparable to SHAW 5cm node
• HailunSuihua, ChanglingSongyuan, YouyiShuangyashan show anomalously high SM (50–70%) starting Jun 2022 only — likely sensor calibration issue or near-saturated wetland soil; treat with caution
• Compare SHAW liquid.out (not moist.out) against these sensors — sensors detect liquid water only

SHAW performance (6-cell HWSD-corrected run, ne_china_shaw_hwsd/):

• Before BPAR fix (BPAR=30): Qiqihar SM PBIAS = +29.4% (soil never froze, liquid stayed at 35% while obs dropped to 13%)
• After BPAR fix (BPAR=6.92 from Rawls 1982): Qiqihar winter liquid drops to 11–17% — physically correct
• Growing season dry bias (PBIAS ≈ −24%): caused by HWSD bulk density overestimate (BD=1380 vs. ~1100 kg/m³ for NE China Mollisols)

Run scripts:

• 6-cell validation: outputs/ne_china_shaw_vic_dssat/run_shaw_hwsd_validation.py
• Full 2223-cell domain: outputs/ne_china_shaw_vic_dssat/run_shaw_parallel.py (includes fix_bpar_quartz_in_sit() as of 2026-05-13)