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

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

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.

ANUGA Skill

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.

Version: ANUGA 3.3.2 (anuga-py) Domain: hydrology / 2D shallow-water inundation Last updated: 2026-08-18 Validation status: tested; real-world body campaign pending

1. Model Identity

2. What This Model Does

ANUGA solves the 2D depth-averaged shallow-water equations over an unstructured triangular mesh. It predicts water-surface stage, depth, horizontal momentum, discharge through cross-sections, and flood inundation extent for event-scale hydrodynamic simulations.

Scope includes rainfall and riverine inflow forcing, wetting/drying, Manning friction, open or reflective boundaries, and hydraulic-structure operators. Scope excludes fully 3D turbulence, vertical convection, breaking waves, and forecasting as the model role.

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 states intent and common traps; the spec file is the contract.

3.1 Forcing

3.2 Static Inputs and Parameters

3.3 Initial and Boundary Conditions

4. Build Instructions

ANUGA is already installed at KISSPATH_HOME/.local/lib/python3.12/site-packages/anuga. Before any run, execute the KI preflight from this directory:

python preflight_check.py

Known build/runtime issue: if import anuga fails with a missing .so or undefined symbol, use diagnostic dt_anuga_016 and reinstall ANUGA for the current Python interpreter before running the KI.

5. Execution

Always run the real ANUGA package through the KI tools. Start with preflight, then use the stage docs and commands in the legacy workflow sections below for rainfall, riverine inflow, simulation, and SWW parsing.

python preflight_check.py
python tools/run_anuga.py --help
python tools/parse_anuga_output.py --help

Expected runtime is mesh-size and event-length dependent; maximum_triangle_area, finaltime, and the adaptive CFL timestep dominate cost.

6. Output Description

Source: dag.yaml. The dag is the model identity for observable outputs; if this section ever disagrees with dag.yaml, the dag wins.

Headline output (dag validation_rank: 1; the variable this model is judged by):

inundation_extent — Surface-water flooded area, derived by thresholding water depth over the mesh at peak inundation. (km^2 (or boolean wet/dry field))

Other dag outputs are stage, depth, xmomentum, ymomentum, discharge, and stage (analytical-benchmark centerline).

7. Tool Inventory

Use the detailed stage docs in docs/s1_convert_rainfall_forcing.md through docs/s5_parse_anuga_outputs.md before composing commands.

8. Unit Conversion Table

8c. Sign Conventions and Output Units

9. Diagnostic Triplets (Top 5)

Read diagnostics/triplets.yaml on any error. These five real IDs cover the most common KI-level failures; do not duplicate the full corpus here.

10. Coupling Interfaces

11. Validated Results

Test Basin: analytical dam-break benchmark

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

Source for bars: docs/validation_convention.yaml. Every stated threshold below is cited exactly as the convention cites it. Null convention bands are written as no cited threshold.

Bar for inundation_extent (csi, direction maximize): satisfactory >= 0.46 (hoch2019, neal2016); good = no cited threshold; very good >= 0.74 (hoch2019, neal2016). Achieved: body campaign pending.

Manifest validation tier: tested. Manifest tier justification: measured: NSE=1.000, KGE=0.998, R=1.000. This is an analytical centerline-stage benchmark result, not a completed body-campaign validation of rank-1 inundation_extent.

Data Replacement Tracking

12. Parameter Selection by Region

These are physically informed starting points, not proof of calibration.

Type: 2D depth-averaged shallow-water hydrodynamics (finite-volume, unstructured triangular mesh) Primary use: tsunami inundation, dam-break, flood modeling Authoritative source: https://github.com/anuga-community/anuga_core Installed at: KISSPATH_HOME/.local/lib/python3.12/site-packages/anuga

KI Tools

All tools are in tools/ and use ki_tools_common.load_forcing for CMFD/MSWX/NASA POWER data.

Stage Docs

• docs/s1_convert_rainfall_forcing.md — CMFD/MSWX/NASA POWER rainfall to ANUGA Rate_operator CSV
• docs/s2_load_hydat_series.md — HYDAT flow/level extraction with datum metadata
• docs/s3_build_inflow_hydrograph.md — gauge discharge to Inlet_operator hydrograph CSV
• docs/s4_run_anuga_simulation.md — DEM setup, boundaries, rainfall/inflow, and SWW generation
• docs/s5_parse_anuga_outputs.md — discharge, stage/depth, and inundation-extent extraction

Two forcing modes — pick the one the event actually has

• Rain-on-grid (run_anuga.py --forcing_csv, Rate_operator): rainfall falls on the whole mesh. Correct for a small headwater box; it CANNOT reproduce a flood routed in from upstream.
• Riverine inflow (run_anuga.py --inflow_csv --inlet_latlon, Inlet_operator): a prescribed discharge hydrograph enters at a point on the channel. This is the dag's first-class inflow discharge forcing and the right mode for any reach whose water comes from upstream. The two can be combined.

Coordinate frames — the #1 source of silent wrong answers

ANUGA uses two frames and they differ by extent_m/2:

Never hand-convert. Use --inlet_latlon LAT LON (run_anuga.py) and --gauge_latlon LAT,LON with --center_lat/--center_lon (parse_anuga_output.py); both route through run_anuga.latlon_to_domain_xy. run_anuga.py also carries a post-fit elevation range guard that raises if the fitted terrain escapes the source DEM range — that guard is what catches a frame/extrapolation bug instead of silently fabricating ±1000 m terrain.

DEM selection

run_anuga.py resolves terrain in this order: --dem_path → the China 90 m DEM (only when the whole domain bbox fits inside it) → the overlapping MERIT DEM 90 m global tiles (KISSPATH_DATA/MERIT_DEM/nNNwWWW_dem.tif, mosaicked automatically across a seam). MERIT is EGM96 orthometric; the China DEM is SRTM. There is no synthetic-terrain fallback unless you pass --allow_synthetic_dem (smoke tests only).

Real-world simulation workflow

# 1. Convert forcing to ANUGA rainfall format
python tools/convert_forcing_to_anuga.py \
    --source cmfd --lat 32.9 --lon 117.4 \
    --start_year 2005 --end_year 2005 \
    --output_dir ./forcing/

# 2. Run ANUGA simulation with DEM and rainfall
python tools/run_anuga.py \
    --lat 32.9 --lon 117.4 --extent_m 5000 \
    --forcing_csv ./forcing/rainfall_timeseries.csv \
    --output_dir ./output/ --finaltime 86400

# 3. Extract discharge at outlet cross-section
python tools/parse_anuga_output.py \
    --sww_file ./output/anuga_sim.sww \
    --cross_section "-2500,0,2500,0" \
    --output_csv ./output/discharge.csv

Riverine workflow — stage at a gauge (worked example, HYDAT)

Validated 2026-08-09 on the Fraser River: inlet driven by observed discharge at HYDAT 08MF005 (Fraser R. at Hope), stage scored at HYDAT 08MF035 (Fraser R. near Agassiz) 31 km downstream. Drive from an upstream station and score at a different, downstream station — driving and scoring the same gauge only reproduces its rating curve.

# 1. Observations: upstream discharge (driver) + downstream level (target)
python tools/load_hydat_series.py --station 08MF005 --variable flow \
    --start 2020-04-01 --end 2020-06-30 --output_csv ./obs/hope_flow.csv
python tools/load_hydat_series.py --station 08MF035 --variable level \
    --start 2020-04-01 --end 2020-06-30 --output_csv ./obs/agassiz_level.csv

# 2. Inlet hydrograph (t=0 at --start, shared origin with the rainfall CSV)
python tools/build_inflow_hydrograph.py --gauge_csv ./obs/hope_flow.csv \
    --start 2020-04-01 --end 2020-06-30 --output_csv ./forcing/inflow.csv

# 3. Run: Inlet_operator on the channel, Transmissive outlet facing downstream
python tools/run_anuga.py --lat 49.230 --lon -121.740 --extent_m 20000 \
    --max_area 30000 --manning_n 0.035 --outlet_side left \
    --inflow_csv ./forcing/inflow.csv \
    --inlet_latlon 49.2745 -121.651 --inlet_radius_m 1200 \
    --finaltime 7862400 --yieldstep 21600 --output_dir ./output/

# 4. Stage at the gauge, snapped to the channel low point
python tools/parse_anuga_output.py --sww_file ./output/anuga_sim.sww \
    --gauge_latlon "49.20369,-121.77583" \
    --center_lat 49.230 --center_lon -121.740 \
    --snap_to_channel_m 400 --output_csv ./output/stage.csv

Vertical datum — check BEFORE scoring stage. ANUGA carries no datum awareness, so an absolute stage comparison is only meaningful when the gauge datum is geodetic. load_hydat_series.py writes <csv>.meta.json with datum_name, datum_id and every published STN_DATUM_CONVERSION offset. Many HYDAT stations use ASSUMED DATUM (id 10) whose zero is arbitrary — e.g. 08MF005 levels need +27.926 m to reach the GSC geodetic datum. Score against a station whose own datum is geodetic (08MF035 = id 35), or apply the published conversion; never compare a raw arbitrary-datum level to DEM elevations.

--snap_to_channel_m is not cosmetic. A published gauge lat/lon is a bank or bridge position. On a 30–90 m DEM the nearest mesh vertex is routinely a bank cell that never wets, so the extracted "stage" is a CONSTANT equal to the bank elevation. parse_anuga_output.py warns when the extraction vertex is wet in <50 % of stored timesteps — treat that warning as a hard stop, not noise.

Known limitation of a 90 m DEM for absolute stage. MERIT/SRTM record the water surface at acquisition, not the bed, and resolve neither the channel bathymetry nor engineered dikes. On a large diked river the model therefore conveys the flood across the whole floodplain and the absolute stage is biased low. Prefer r / timing for a KI-validity verdict on such a reach and read nse/pbias as a terrain-data statement, not a solver statement.

Key variables

Unit conversions (forcing)

• CMFD precip: kg/m²/s → mm/timestep (×timestep_s) → m/s (÷1000 ÷ timestep_s)
• ANUGA Rate_operator expects rainfall in m/s

Parameters

Calibration is typically limited to Manning's n and mesh resolution. ANUGA is a physics-based solver; most parameters are physical constants, not tuneable coefficients.

Output Description

ANUGA writes simulation results to SWW files (NetCDF-like format):

Use parse_anuga_output.py to extract stage/discharge time series to CSV. SWW files can also be visualized with anuga_viewer or converted to raster grids for GIS analysis.

Validation strategy

ANUGA is a physics solver, not a forecasting model. The correct validation is against analytical / closed-form solutions, not gauge NSE/KGE. Treat comparison_type='analytical' as the default mode for ANUGA tests.

Standard benchmarks shipped under validation_tests/analytical_exact/ in the source repo:

Default test

dam_break_wet: 1D Stoker dam-break on a 1000 m x 5 m flat channel, h1=10 m (left), h0=1 m (right), no friction, finaltime=50 s. Compare modeled stage along the centerline at t=50 s against anuga.validation_tests.analytical_exact.dam_break_wet.analytical_dam_break_wet.vec_dam_break.

Execution

python -c "import anuga" # sanity
# runner: diagnostics/run_dam_break_wet.py — loads numerical + analytical, writes NSE/R/KGE

Metric reporting: NSE, Pearson R, KGE computed on 1D centerline stage profile (numerical_stage at t_final vs analytical h at the same x).

Notes on previous failure

The earlier run used examples/simple_examples/runup.py (synthetic 10x10 rectangular beach) with comparison_type='none', yielding null metrics. The fix is to switch to an analytical-solution benchmark and compare pointwise.