Imported from lzwei196/KISS-Knowledge-Infrastructure-for-Scientific-Simulation (models/WSIMOD/SKILL.md). Install upstream with npx skills add lzwei196/KISS-Knowledge-Infrastructure-for-Scientific-Simulation --skill WSIMOD. 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.

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

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.

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

WSIMOD Knowledge Infrastructure v1.0.0

• Package: hydrocraft-wsimod
• Model: WSIMOD (Water Systems Integrated Modelling framework)
• Version: 0.6+ (PyPI)
• Domain: Integrated water cycle modelling — water quantity and quality
• Authors: Barnaby Dobson, Imperial College London
• References: Dobson et al. 2023 (JOSS, doi:10.21105/joss.04996); Dobson et al. 2024 (GMD, doi:10.5194/gmd-17-4495-2024)
• Stats: 4 tools, 5 skill docs, 18 diagnostic triplets, ~11,500 lines Python source

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: Input from upstream hydrological models. See data_ki/GRanD/SKILL.md for dam/reservoir database. See data_ki/HydroLAKES/SKILL.md for lake morphometry.

1. Overview

WSIMOD is a Python framework for simulating water quantity and quality across the terrestrial water cycle. It uses a node-arc message-passing architecture where physical components (land surfaces, sewers, rivers, reservoirs, treatment works, demand points) are represented as nodes connected by arcs that transport water.

Key capabilities:

• Integrated urban-rural catchment simulation
• 12 water quality pollutants tracked (N, P, BOD, COD, solids, DO, pH, temperature)
• Flexible node-arc graph: users wire any configuration of water system components
• Daily timestep with configurable orchestration sequence
• CLI and Python API execution modes
• YAML configuration with CSV timeseries inputs
• Mass-balance checking at every node and arc

WSIMOD combines processes from CityWat (urban water) and CatchWat (rural hydrology) into a single message-passing framework. Each node responds to four message types: pull_check, pull_set, push_check, push_set — enabling flexible routing of water volumes with associated quality (VQIP dictionaries).

2. Installation

From PyPI (recommended)

python -m venv venv && source venv/bin/activate
pip install wsimod

From GitHub (development)

pip install git+https://github.com/ImperialCollegeLondon/wsi@main

With demos (includes geopandas, matplotlib, shapely)

pip install wsimod[demos]

Development mode

git clone https://github.com/ImperialCollegeLondon/wsi.git
cd wsi
pip install -e .[dev]

Dependencies

Test command

wsimod settings.yaml --inputs ./input_dir --outputs ./output_dir

3. Pipeline Stages

Stage Details

s0 — Configuration: Define simulation period, pollutants to track, node types, spatial extent. Choose between CLI (YAML settings) or Python API.

s1 — Domain Setup: Identify catchment boundaries, node graph topology. Define which node types (Land, Sewer, River, Reservoir, Groundwater, Demand, WTW, etc.) are needed and how they connect via arcs.

s2 — Data Preparation: Gather raw meteorological and hydrological timeseries. Convert to WSIMOD's expected CSV format with columns: site, date, variable, value.

s3 — Forcing/Input: Convert precipitation (mm → m via MM_TO_M), temperature (°C), evapotranspiration (mm/d), flow data. Build data_input_dict for each node.

s4 — Parameters: Set node-specific parameters: surface areas (m²), tank capacities (ML or m³), residence times (days), pollutant loads (kg/timestep), decay rates.

s5 — Execution: Run the model via CLI or Python API. The orchestration loop iterates over dates, calling node functions in sequence.

s6 — Output Parsing: Extract flows.csv, tanks.csv, surfaces.csv. Parse VQIP records into analyzable DataFrames.

4. Unit Trap Table

These unit conversions are the most common source of silent errors in WSIMOD.

Critical Constants (from wsimod.core.constants)

MM_TO_M = 1e-3              # precipitation, ET₀, soil depth
ML_TO_M3 = 1000             # volume conversion
M3_S_TO_ML_D = 86.4         # flow rate
KM2_TO_M2 = 1e6             # area
MG_L_TO_KG_M3 = 1e-3        # concentration → mass/volume
KG_M3_TO_MG_L = 1e3         # mass/volume → concentration
FLOAT_ACCURACY = 1e-11      # mass balance tolerance
DT_DAYS = 1                 # default timestep
DECAY_REFERENCE_TEMPERATURE = 20  # °C for decay rate adjustment

5. Node Types Reference

6. VQIP (Volume-Quality Input Product) Structure

Every water transfer in WSIMOD is a VQIP dictionary:

vqip = {
    'volume': 100.0,       # m³/timestep (or ML depending on config)
    'do': 8.5,             # mg/L — non-additive
    'temperature': 15.0,   # °C — non-additive
    'ph': 7.5,             # pH — non-additive
    'phosphate': 0.05,     # kg — additive (mass)
    'org-phosphorus': 0.01,# kg — additive
    'ammonia': 0.02,       # kg — additive
    'nitrate': 0.03,       # kg — additive
    'nitrite': 0.001,      # kg — additive
    'org-nitrogen': 0.01,  # kg — additive
    'bod': 5.0,            # kg — additive
    'cod': 10.0,           # kg — additive
    'solids': 1.0,         # kg — additive
}

Additive pollutants (9): Mass-based; scale linearly with volume. When mixing, masses sum directly.

Non-additive pollutants (3): Concentration/intensive; when mixing, volume-weighted average is taken (not summed).

7. Default Orchestration Sequence

The model calls node functions in this order each timestep:

8. Tools Reference

Total: ~1,000 lines validated Python

9. Skill Documents

10. Critical Domain Knowledge

These non-obvious facts cause silent failures if violated:

dt_001: Precipitation must be in meters, not millimeters. WSIMOD expects precipitation in m/timestep. Most weather datasets provide mm/day. Omitting × MM_TO_M causes 1000× too much rainfall, flooding all nodes. Detection: check max(precipitation) < 0.5 m/d for temperate climates.

dt_002: Volume units are ML by default, but nodes may use m³. MM_M2_TO_SIM_VOLUME converts precipitation depth × area to simulation volume. Default simulation volume is ML (megalitres). Some node parameters use m³. Mixing units silently corrupts mass balance.

dt_003: Additive vs non-additive pollutant mixing. Additive pollutants (phosphate, ammonia, etc.) are in kg — masses sum when mixing. Non-additive pollutants (DO, temperature, pH) are concentrations — volume-weighted average when mixing. Treating a non-additive as additive doubles concentrations.

dt_004: data_input_dict keys are (variable, timestamp) tuples. The timestamp must be a pandas Timestamp or WSIMOD to_datetime object. Using string dates as keys causes silent KeyError → zero forcing for all timesteps.

dt_005: Node names in arcs must match exactly. Arc in_port and out_port reference node names. Typos cause KeyError at model construction. Names are case-sensitive.

dt_006: Sewer capacity is m³/d, not ML/d. Despite other nodes using ML, sewer capacity is in m³/d. Using ML values gives 1000× too much capacity, preventing any CSO (combined sewer overflow).

dt_007: Pollutant decay uses reference temperature of 20°C. k(T) = k_ref × (coeff ^ (T - 20)). If temperature is in wrong units or missing, decay rates are silently wrong. Always verify temperature is in °C.

dt_008: Land surface area is in m². Some datasets provide area in km² or hectares. Using km² without converting to m² gives 1e6× wrong runoff volume. Use KM2_TO_M2 = 1e6.

dt_009: Mass balance tolerance is 1e-11. FLOAT_ACCURACY = 1e-11. Mass balance violations below this threshold are ignored. If custom nodes accumulate floating-point errors, violations may be masked.

11. Validation: Built-in Test Cases

WSIMOD includes comprehensive tests in the tests/ directory:

• Quickstart demo: Simple urban-rural catchment (Land → Sewer → Groundwater → River)
• Oxford case study: Multi-node Thames catchment with demand, WTW, reservoirs
• Land demo: Detailed land surface hydrology with multiple surface types

Test command:

cd source/repo && python -m pytest tests/ -v

12. Configuration Format

YAML Settings File (custom mode)

dates:
  - "2009-01-01"
  - "2009-01-02"
  # ... daily dates

data:
  land_timeseries:
    filename: "timeseries_data.csv"
    filters:
      - where: site
        is: oxford_land
    scaling:
      - where: variable
        is: precipitation
        variable: value
        factor: MM_TO_M
    index: [variable, date]
    output: value
    format: dict

nodes:
  - type_: Land
    name: my_land
    data_input_dict: "data:land_timeseries"
    surfaces:
      - type_: ImperviousSurface
        surface: urban
        area: 10
      - type_: PerviousSurface
        surface: rural
        area: 100
        depth: 0.5

  - type_: Sewer
    name: my_sewer
    capacity: 0.04

  - type_: Groundwater
    name: my_gw
    area: 100
    capacity: 100

arcs:
  - type_: Arc
    name: urban_drain
    in_port: my_land
    out_port: my_sewer

  - type_: Arc
    name: percolation
    in_port: my_land
    out_port: my_gw

Saved Model Format

Models can be saved/loaded with model.save() / model.load():

• config.yml — full model definition
• *.csv.gz — compressed timeseries data
• *.parquet — optional parquet data files

13. Diagnostic Triplets Summary

Output Description

WSIMOD's model.run() returns four DataFrames: flows, tanks, _, surfaces. The flows DataFrame records water volumes (m^3 or ML) and VQIP pollutant masses/concentrations transferred along each arc per timestep. The tanks DataFrame logs storage levels at each node. The surfaces DataFrame tracks land surface states (soil moisture, runoff, percolation). These are returned as lists of dictionaries convertible to pandas DataFrames via pd.DataFrame(flows). Use parse_wsimod_output.py to export results to CSV files (flows.csv, tanks.csv, surfaces.csv) with columns including date, arc/node_name, volume, and pollutant values, and to compute mass-balance checks across the network.

6. Output Description (dag.yaml-sourced)

This section restates the observable outputs from dag.yaml. If this section and dag.yaml disagree, dag.yaml wins.

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

river flow / discharge — Routed river discharge at a node, a subset of the flows record commonly compared to gauge data. (m3/d or ML/d)

The flows record is the main parsing source for routed discharge and water quality transfers. The rank-1 output river flow / discharge is a subset of that record and should be compared to gauge observations in m3/d or ML/d.

8. Unit Conversion Table

The exact I/O contract lives in docs/format_spec.yaml; this unit table summarizes the unit traps used by the pipeline and diagnostic triplets. Verify the source data attributes before converting a new dataset.

Output unit convention: river flow / discharge is scored in m3/d or ML/d. Do not compare raw m3/s gauge data to parsed daily discharge until it has been converted to the same unit basis.

11. Validated Results

This section states the model's validation target and field pass-bands from docs/validation_convention.yaml. It does not claim a site-specific achieved score unless a run report supplies one.

Headline Validation Target

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

For any metric or dag variable not listed in docs/validation_convention.yaml, write the band as no cited threshold; do not substitute remembered hydrology thresholds.

Achieved Result Values

No calibration, validation, or full-period achieved metric values were supplied in the sourced facts for this edit. Record achieved values only after running the real WSIMOD package or CLI, then judge river flow / discharge against the bands above.

14. Quick Start

import pandas as pd
from wsimod.core import constants
from wsimod.orchestration.model import Model

# 1. Load timeseries data
data = pd.read_csv("timeseries_data.csv")
data.loc[data.variable == "precipitation", "value"] *= constants.MM_TO_M
data.date = pd.to_datetime(data.date)
dates = data.date.drop_duplicates()

# 2. Build data_input_dict
land_inputs = data.set_index(["variable", "date"]).value.to_dict()

# 3. Define nodes
nodes = [
    {"type_": "Land", "name": "my_land",
     "data_input_dict": land_inputs,
     "surfaces": [
         {"type_": "PerviousSurface", "surface": "rural",
          "area": 100, "depth": 0.5}
     ]},
    {"type_": "Groundwater", "name": "my_gw",
     "area": 100, "capacity": 100},
    {"type_": "Node", "name": "my_river"},
    {"type_": "Waste", "name": "outlet"},
]

# 4. Define arcs
arcs = [
    {"type_": "Arc", "in_port": "my_land", "out_port": "my_gw",
     "name": "percolation"},
    {"type_": "Arc", "in_port": "my_land", "out_port": "my_river",
     "name": "runoff"},
    {"type_": "Arc", "in_port": "my_gw", "out_port": "my_river",
     "name": "baseflow"},
    {"type_": "Arc", "in_port": "my_river", "out_port": "outlet",
     "name": "outflow"},
]

# 5. Create and run model
model = Model()
model.dates = dates
model.add_nodes(nodes)
model.add_arcs(arcs)
flows, tanks, _, surfaces = model.run()

# 6. Parse output
flows_df = pd.DataFrame(flows)
print(flows_df.head())

15. Coupling Points

16. File Structure

ki/
├── SKILL.md                              # This file
├── knowledge_infrastructure.yaml          # Schema-compliant YAML
├── tools/
│   ├── convert_forcing_data.py           # Forcing/input converter
│   ├── convert_parameters.py             # Soil/parameter converter
│   ├── run_wsimod.py                     # Execution wrapper
│   └── parse_wsimod_output.py            # Output parser
├── docs/
│   ├── s0_configuration_skill.md         # Configuration guide
│   ├── s2_data_preparation_skill.md      # Data preparation guide
│   ├── s4_parameters_skill.md            # Parameter setup guide
│   ├── s5_execution_skill.md             # Execution guide
│   └── s6_output_analysis_skill.md       # Output analysis guide
└── diagnostics/
    └── triplets.yaml                     # 18 diagnostic triplets