metadata: version: "1.0.0"

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)

to verify that the model binary/package and required data are available.

DEBUGGING PROTOCOL — When something goes wrong (model crashes, wrong output,

unexpected values), follow this order. Do NOT skip steps or write debug scripts:

1. Check triplets — diagnostics/triplets.yaml may already cover this error

2. Read official docs — Check the model's own documentation (PDF manual, README,

official examples) for expected input formats, variable names, and units

3. Find working examples — Look in outputs/ for previous successful runs of

this model, or check if the model ships with test/example data

4. Fix the tool — Now that you know what "correct" looks like, make targeted fixes

Resist the urge to write diagnostic/debug Python scripts. The answers are almost

always in the official docs and working examples, not in reverse-engineering the binary.

<!-- KI-MAP:BEGIN (projected by generate_skill_map.py — edit the KI, not this table) -->

KI map — what to read, and when

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>`. <!-- KI-MAP:END -->

<!-- KI-TOOL-INDEX:BEGIN (projected by generate_skill_map.py — the discoverability contract: every public tool, exact path; PURPOSE stays human-authored elsewhere) -->

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.

5 public tools; `_`-prefixed helpers and packaging files excluded. <!-- KI-TOOL-INDEX:END -->

model: pySTEPS version: 1.20.0 domain: precipitation_nowcasting not_a_hydrological_model: true

pySTEPS -- Knowledge Infrastructure

Version: 1.20.0

Domain: precipitation_nowcasting

Last updated: 2026-08-18

Validation status: binary_only

1. Model Identity

pySTEPS is a Python library, not a standalone binary. The package version is 1.20.0 via importlib.metadata; the module itself has no __version__ attribute.

It is NOT a hydrological model and cannot be validated directly against hydrocraft.db station discharge or water-quality observations.

2. What This Model Does

pySTEPS performs deterministic and probabilistic precipitation nowcasting from radar QPE sequences. It estimates atmospheric precipitation advection with optical-flow methods and advects observed precipitation intensity fields forward on the same radar grid.

This KI treats pySTEPS as a physics/signal-processing library. The validated path exercises the real pySTEPS code paths for Proesmans motion estimation, extrapolation nowcast, and det_cat_fct/fss verification.

3. Input Requirements

Exact shapes live in docs/format_spec.yaml, projected from dag.yaml and diagnostics/triplets.yaml. Regenerate that file after changing either source; do not hand-edit it.

3.1 Radar Precipitation Sequence

Input is a sequence of 2-D precipitation intensity fields on a uniform radar grid, typically 3-4 past frames at 5-15 min cadence. Supported importers include BoM RF3, DWD HDF5, FMI PGM, KNMI HDF5, MCH GIF, OPERA HDF5, and SAF NetCDF.

3.2 Static Inputs

3.3 Configuration Files

4. Build Instructions

pySTEPS is used as the installed Python package in this environment. Before any run, verify the package, data expectations, and KI structure:

cd KISSPATH_KI_ROOT/pySTEPS/knowledge_infrastructure
python3 preflight_check.py

Known build issues must be handled through diagnostics/triplets.yaml first, then the official pySTEPS docs and working examples.

5. Execution

cd KISSPATH_KI_ROOT/pySTEPS/knowledge_infrastructure
python3 preflight_check.py
python3 diagnostics/run_synthetic_advection.py

The synthetic runner writes diagnostics/last_run.json with per-lead CSI/POD/FAR/FSS scores plus timing. A tester_result.json is also written to the KI root for the orchestrator.

Expected runtime is the local runtime of the synthetic analytical test on a 200x200 grid with 4 past frames and 5 lead times.

6. Output Description

This section restates dag.yaml. If this section and dag.yaml disagree, dag.yaml wins.

Headline output (the dag's validation_rank: 1 variable -- the one this model is judged by):

motion_field -- Estimated 2-D atmospheric radar precipitation advection velocity field (2, ny, nx) from the optical-flow stage on the radar precipitation frame sequence; an intermediate product also returnable on its own. (pixels/timestep)

7. Tool Inventory

Stage Docs

• docs/s1_data_import.md - import radar frames, metadata, units, and NaN handling.
• docs/s2_motion_estimation.md - estimate pySTEPS optical-flow motion fields.
• docs/s3_nowcast.md - run extrapolation, STEPS, or ANVIL nowcasts.
• docs/s4_verification.md - score forecasts against held-out radar frames.
• docs/s5_postprocess.md - export nowcasts to NetCDF, GeoTIFF, or CSV.

Before composing a command, read each tool's argparse help and the corresponding stage doc.

8. Unit Conversion Table

pySTEPS operates on 2-D precipitation fields. This table documents the units and conversions encountered in this KI pipeline.

8c. Sign Conventions and Output Units

Primary units encountered:

Critical unit conversion rules:

• dBZ to mm/h: R = (10**(dBZ/10) / 200)**(1/1.6) using the default Z=200*R^1.6.
• mm/h to dBR: dBR = 10 * log10(R); set a threshold first because R > 0 is required.
• mm/h to mm: depth_mm = rate_mm_h * timestep_minutes / 60.0.
• Radar frame timestep (metadata['accutime']) is in minutes. Common values are 5 for OPERA and BoM, 10 for FMI, and 15 for DWD.

Accumulation period pitfalls:

• A "5-minute rainfall rate" in mm/h means the average rate during a 5-min window, not 5 mm/h.
• To get 1-hour accumulation from 5-min frames, sum 12 consecutive frames in mm/h and multiply each by 5/60.
• STEPS ensemble output is instantaneous rate at each lead time, not accumulated between lead times.

9. Diagnostic Triplets (Top 5)

Check diagnostics/triplets.yaml before debugging any model crash, wrong output, or unexpected values. The full corpus is there (current count: the KI map at the top of this file); cite the real triplet ids from that file in run notes instead of duplicating or renumbering them here.

10. Coupling Interfaces

For real-data extension, see examples/README.md.

11. Validated Results

Test Case: synthetic_advection

Because no real radar archive is mounted, this KI validates pySTEPS against a synthetic advected precipitation sequence where the true future frames are known exactly.

Performance Metrics -- judged against the field's bar, not intuition

The convention bars below restate docs/validation_convention.yaml. A null convention band is written as "no cited threshold"; no substitute threshold is implied.

The synthetic runner reports CSI, POD, FAR at threshold 0.5 mm/h and FSS at scale 20 px. Its synthetic-test expectations are mean CSI > 0.95 and mean FSS > 0.99; these are runner checks, not convention pass-bands for motion_field.

Data Replacement Tracking

12. Parameter Selection by Region

These are physically informed starting points for pySTEPS runs, not calibration against hydrocraft.db discharge or water-quality observations.

Motion Estimation Parameters

Nowcast Parameters

Verification Parameters

Domain Size Guidelines