lzwei196/kiss-knowledge-infrastructure-for-scientific-simulation/pysteps

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.