openAMUNDSEN · diff

git:20260826.6c18863 to git:20261018.004fedf

1 added, 1 removed. Audit C to C.

> **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.

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

> 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

| when you need | read | why |

|---|---|---|

| FIRST, always | `preflight_check.py` | run it (`python preflight_check.py`): proves env/binary/data are usable and emits a machine-readable `PREFLIGHT_REPORT=` line. Do not debug a run that never had a healthy environment. |

| to run the pipeline stages | `tools/` (4 tools) | the executable pipeline. Read each tool's argparse (`--help`) before composing a command; SKILL.md's stage table says which tool serves which stage. |

| before running a stage | `docs/s*_*.md` (5 stage docs) | per-stage procedure, verification and traps — the how-to that SKILL.md's overview compresses. |

| on ANY error, before debugging | `diagnostics/triplets.yaml` (18 entries) | symptom → diagnosis → remedy for this model's known failure modes. Check here FIRST; the answer usually exists. Never renumber or rewrite entries. |

| to know what an output IS | `dag.yaml` | the model's identity: every output's medium, units, `validation_rank` (1 = the headline variable) and observability. Scoring and obs-binding read THIS — when asked 'what does this model predict', the dag is the answer, not a guess. |

| when building inputs / parsing outputs | `docs/format_spec.yaml` | exact I/O shapes + `known_issues`, projected from dag + triplets. Regenerate with `ki_tools_common/generate_format_spec.py` after changing either — never hand-edit. |

| to judge a run's skill | `docs/validation_convention.yaml` | how this model's field judges it validated: per-`dag_variable` metrics, directions and CITED pass-bands. A run is graded against these, not against intuition. |

| for claims and thresholds | `docs/gathered_papers.json` (20 papers) + `docs/papers_index.md` | the literature this KI is judged by; each entry's `text_path` is fetched full text in the central paper cache. `role: benchmark` marks the model's own skill paper. |

| for a machine-readable summary | `knowledge_infrastructure.yaml` | the manifest (package, pipeline, validation tier, counts) — projected by `ki_tools_common/generate_ki_manifest.py`; regenerate after structural changes, never hand-edit. |

*Projected 2026-08-17 from the KI's actual contents — 9 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.

| tool (exact path) | invocation |

|---|---|

| `tools/convert_meteo_forcing.py` | `KISSPATH_PYTHON_ENV/bin/python {KI}/tools/convert_meteo_forcing.py --help` |

| `tools/convert_soil_params.py` | `KISSPATH_PYTHON_ENV/bin/python {KI}/tools/convert_soil_params.py --help` |

| `tools/parse_output.py` | `KISSPATH_PYTHON_ENV/bin/python {KI}/tools/parse_output.py --help` |

| `tools/run_openamundsen.py` | `KISSPATH_PYTHON_ENV/bin/python {KI}/tools/run_openamundsen.py --help` |

*4 public tools; `_`-prefixed helpers and packaging files excluded.*

# openAMUNDSEN Knowledge Infrastructure

**Package**: hydrocraft-openamundsen-snow

**Version**: 1.0.0

**Created**: 2026-03-26

**Model**: openAMUNDSEN (fully distributed snow/hydroclimatological model)

**Domain**: Cryosphere — snow accumulation, ablation, energy balance in mountain regions

**Language**: Python (with Numba JIT acceleration)

**License**: MIT

---

## Data Preparation

### Forcing data

**Data Sources**: Use `from ki_tools_common.load_forcing import load_daily_forcing` for CMFD/MSWX/NASA POWER.

**Data Validation Reference**: See `data_ki/CMFD/SKILL.md` for atmospheric forcing documentation.

See `data_ki/SNOTEL/SKILL.md` for snow observations.

See `data_ki/BedMachine/SKILL.md` for ice topography.

See `data_ki/MEaSUREs/SKILL.md` for ice velocity.

## Overview

openAMUNDSEN is a fully distributed snow and hydroclimatological modeling framework designed

for mountain regions. It operates at spatial resolutions of 10–100 m and temporal resolutions

of 1–3 hours. The model simulates the complete snow mass and energy balance including:

- Spatial interpolation of meteorological station data (IDW, lapse rates)

- Solar radiation with terrain slope/orientation, hill shading, atmospheric transmission

- Precipitation phase partitioning (air temperature or wet-bulb temperature methods)

- Precipitation correction for wind-induced undercatch (WMO, Kochendorfer)

- Snow redistribution based on terrain factors (SRF method)

- Multilayer or cryolayer snow models with full energy balance

- Forest canopy snow interception, sublimation, and melt unloading

- Evapotranspiration via FAO Penman-Monteith

- Soil heat conduction through multiple layers

- Glacier mass balance (experimental, delta-h method)

**Key output variables**: SWE, snow depth, snow melt, runoff, sublimation, surface temperature,

albedo, radiation fluxes, evapotranspiration.

---

## Output Description

**Source of truth**: `dag.yaml`. This section restates the KI's dag facts for readers; if

this section and `dag.yaml` ever disagree, `dag.yaml` wins.

**Headline output** (`validation_rank: 1`):

`dag.yaml` rank-1 fact: `var='swe' unit='kg m-2' description='Snow water equivalent — mass of snow per unit area (CF surface_snow_amount).'`

> `swe` — Snow water equivalent — mass of snow per unit area (CF surface_snow_amount). (`kg m-2`)

| Output variable (dag `var`) | Unit | Description / role |

|-----------------------------|------|--------------------|

| `swe` | `kg m-2` | Snow water equivalent — mass of snow per unit area (CF surface_snow_amount). |

| `snow_depth` | see `dag.yaml` | Other dag output |

| `snow_cover` | area fraction / extent | Other dag output |

| `snow_melt` | see `dag.yaml` | Other dag output |

| `snow_runoff` | see `dag.yaml` | Other dag output |

| `snow_density` | see `dag.yaml` | Other dag output |

| `evapotranspiration` | see `dag.yaml` | Other dag output |

The dag's rank-1 output is `swe`. Other dag outputs are `snow_depth`,

`snow_cover` (area fraction / extent), `snow_melt`, `snow_runoff`,

`snow_density`, and `evapotranspiration`.

---

## Installation

```bash

# Recommended: conda

conda install --channel=conda-forge openamundsen

# Alternative: pip

python -m venv venv && source venv/bin/activate

pip install openamundsen

# From source

git clone https://github.com/openamundsen/openamundsen

cd openamundsen

pip install -e .

```

**Core dependencies**: numpy, pandas>=1.1, xarray>=0.14, netCDF4, rasterio>=1.1,

scipy, numba>=0.50.1, pyproj, ruamel.yaml>=0.15, cerberus, munch, pwlf

**Python version**: >= 3.10

**Binary location**: `openamundsen` CLI command (entry point from pip install)

**Test**: `openamundsen config.yml` — should run with example config

---

## Pipeline Stages

The openAMUNDSEN workflow proceeds through the following stages:

```

s1_grid_setup ──────────┐

├──→ s3_configuration ──→ s4_model_init ──→ s5_execution

s2_meteo_preparation ───┘ │ │ │

│ │ ▼

s6_output_config canopy/ET s7_output_parse

(optional) │

▼

s8_validation

```

### Stage Descriptions

|-------|------|-------------|------|

---

## Unit Trap Table

**CRITICAL**: openAMUNDSEN expects specific units. Getting these wrong produces silent errors.

|----------|--------------|----------------|--------|------------|

| `wind_speed` | **m s⁻¹** | km h⁻¹ | Precipitation correction 3.6x too strong | dt_005 |

| Snow density | **kg m⁻³** | g cm⁻³ | Density 1000x too low | dt_012 |

---

## Unit Table / Unit Conversion Table

**Source of truth**: `docs/format_spec.yaml`, `dag.yaml`, and the unit traps above. This table

summarizes the units this KI already documents; verify source-data attributes before converting

new forcing files.

|----------|------------------|--------------------------|----------------------------------------|------------|

| `swe` | `kg m-2` | none stated in extracted dag facts | rank-1 output unit from `dag.yaml` | n/a |

| `wind_speed` | `m s-1` | `km h-1` | divide `km h-1` by `3.6` | dt_005 |

| `resolution` | `m` | km | convert kilometers to meters before configuration | dt_010 |

| Soil thickness | `m` | cm | divide centimeters by `100` | dt_011 |

| Snow density | `kg m-3` | `g cm-3` | multiply `g cm-3` by `1000` | dt_012 |

Output units to verify after every run:

- `swe`: `kg m-2`, from `dag.yaml`.

- `snow_depth`, `snow_cover`, `snow_melt`, `snow_runoff`, `snow_density`,

and `evapotranspiration`: listed as dag outputs; read their exact units from

`dag.yaml` and output NetCDF attributes before post-processing.

---

## Tools Reference

|------|-------|------|-------|---------|

---

## Skill Knowledge Cross-Reference

| Knowledge Area | Skill Document | Key Traps |

|----------------|---------------|-----------|

| Grid setup | `docs/s1_grid_setup.md` | DEM must be Arc/Info ASCII, projected CRS |

| Meteorological forcing | `docs/s2_meteo_forcing.md` | dt_001–dt_007 (unit conversions) |

| Configuration | `docs/s3_configuration.md` | dt_010, dt_013, dt_015 |

| Model execution | `docs/s4_model_execution.md` | Runtime errors, memory issues |

| Output analysis | `docs/s5_output_analysis.md` | Variable naming, aggregation traps |

---

## Critical Domain Knowledge

These are non-obvious facts that cause silent failures if ignored:

1. **Temperature MUST be in Kelvin** (dt_001): The model uses T0=273.15 K internally.

Input filters reject temp < 200 K, so Celsius values (e.g., -10°C) are silently clipped

to NaN, causing interpolation failure.

2. **Precipitation is per-timestep accumulation, not rate** (dt_002): For CSV input,

precip is kg m⁻² per timestep (e.g., mm per hour). For NetCDF with units="kg m-2 s-1",

the model auto-converts by multiplying by timestep seconds. Mixing these up causes

massive over/under-accumulation.

3. **Station coordinates in CSV mode must be WGS84 lon/lat** (dt_014): The `meteo.crs`

config must match the station coordinate system. If stations.csv has projected coords

but crs is set to epsg:4326, stations map to wrong locations.

4. **DEM filename convention is strict** (dt_009): Must be `dem_{domain}_{resolution}.asc`

where domain and resolution match the config exactly.

5. **Lapse rates are in K/m, not K/100m or K/km** (dt_013): Monthly lapse rate arrays

in config are per meter. A typical value is 0.0065 K/m (6.5 K/km). Using 6.5 directly

means 6500 K/km — temperatures crash.

6. **Input filter silently replaces out-of-range values with NaN** (dt_003): If humidity

is 0–1 fraction instead of 0–100%, values are clipped to NaN by the default filter

(min=1, max=100). No error is raised.

7. **Cloud fraction auto-conversion is fragile** (dt_006): The model converts fraction

(0–1) to percent only if max(cloud_fraction) ≤ 1 AND len(data) > 10. Short time

series or already-percent data bypass conversion.

8. **Wind speed minimum is 0.1 m/s** (dt_005): Values below 0.1 are clipped. This

prevents division-by-zero in turbulent exchange but affects calm-wind statistics.

9. **Snow model choice affects layer structure** (dt_016): "multilayer" uses explicit

thickness layers; "cryolayers" uses categorical transitions (new→old→firn→ice).

Switching models mid-calibration invalidates all tuned parameters.

---

## Configuration Reference

Minimal YAML configuration:

```yaml

domain: my_catchment

start_date: 2020-10-01

end_date: 2021-09-30

resolution: 50

timestep: 3h

crs: "epsg:32632"

timezone: 1

input_data:

grids:

dir: ./input/grid

meteo:

dir: ./input/meteo

format: csv

crs: "epsg:4326"

output_data:

timeseries:

format: netcdf

add_default_variables: true

points:

- x: 642579

y: 5193069

name: station_A

snow:

model: multilayer

melt:

method: energy_balance

results_dir: ./output

```

---

## Calibration Parameters (Priority Order)

|-----------|------------|-------|---------|--------|

---

## Data Requirements

|-----------|--------|--------|----------|

| DEM | SRTM, ASTER, LiDAR | Arc/Info ASCII (.asc) | Yes |

---

## Quick Start

```bash

# 1. Prepare grid data

cp dem_mydomain_50.asc input/grid/

cp roi_mydomain_50.asc input/grid/ # optional

# 2. Prepare meteorological data (CSV format)

# Place station CSV files in input/meteo/ with stations.csv

# 3. Create configuration

# Edit config.yml (see Configuration Reference above)

# 4. Run model

openamundsen config.yml

# 5. Analyze output

python parse_output.py --results-dir ./output --format csv

```

---

## Diagnostic Triplets Summary

|----|-------|----------|-------|

| dt_001 | s2 | silent | Temperature in °C instead of K |

| dt_002 | s2 | silent | Precipitation unit mismatch (rate vs accumulation) |

| dt_003 | s2 | silent | Relative humidity as fraction (0–1) not percent |

| dt_004 | s2 | silent | Shortwave radiation unit mismatch |

| dt_005 | s2 | degraded | Wind speed in km/h instead of m/s |

| dt_006 | s2 | silent | Cloud fraction auto-conversion failure |

| dt_007 | s2 | silent | NetCDF precip units attribute missing |

| dt_008 | s1 | silent | Station altitude in wrong unit |

| dt_009 | s1 | fatal | DEM filename does not match config domain/resolution |

| dt_010 | s3 | fatal | Resolution in km instead of m |

| dt_011 | s3 | silent | Soil thickness in cm instead of m |

| dt_012 | s3 | silent | Snow density initialization in g/cm³ |

| dt_013 | s3 | silent | Lapse rate in K/km instead of K/m |

| dt_014 | s2 | fatal | Station coordinates in projected CRS but config says WGS84 |

| dt_015 | s3 | fatal | Invalid timestep string |

| dt_016 | s5 | degraded | Snow model switch invalidates calibration |

| dt_017 | s4 | fatal | No stations within grid extent |

| dt_018 | s5 | degraded | Canopy enabled but no land cover grid |

---

## Validated Results

**Source of truth**: `docs/validation_convention.yaml`. This section restates the

convention bars supplied by the KI. Do not judge a model run by intuition; compare run

metrics against these cited bands. If a convention band is null, write `no cited threshold`.

### Headline Output: `swe`

`swe` is the dag rank-1 output: Snow water equivalent — mass of snow per unit area

(CF surface_snow_amount). Unit: `kg m-2`.

|--------------|--------|-----------|-------------------|-----------|----------------|---------------|

### Additional Convention Bars

|--------------|--------|-----------|-------------------|-----------|----------------|---------------|

Achieved calibration, validation, and full-period metric values are run outputs, not

convention bars. Record them only when produced by this KI's execution and validation tools,

then compare them against the cited bands above.

---

## File Structure

```

ki/

├── SKILL.md # This file

├── tools/

│ ├── convert_meteo_forcing.py # Reanalysis → openAMUNDSEN meteo format

│ ├── convert_soil_params.py # HWSD → model soil parameters

│ ├── run_openamundsen.py # Execution wrapper with preflight checks

│ └── parse_output.py # NetCDF/CSV result extraction

├── docs/

│ ├── s1_grid_setup.md # DEM and ROI preparation

│ ├── s2_meteo_forcing.md # Meteorological data conversion

│ ├── s3_configuration.md # YAML configuration guide

│ ├── s4_model_execution.md # Running the model

│ └── s5_output_analysis.md # Output parsing and validation

└── diagnostics/

- └── triplets.yaml # 18 symptom→diagnosis→remedy entries

+ └── triplets.yaml # diagnostic triplets (count: KI map)

```