/swmm-params

name: swmm-params
description: Deterministic mapping from land use and soil texture to SWMM runoff/subarea and Green-Ampt infiltration parameters. Use when generating first-pass subcatchment parameter tables for swmm-builder.

SWMM Params (MVP mapping layer)

Part of [Agentic SWMM](https://github.com/Zhonghao1995/agentic-swmm-workflow) — install the project first for the executable toolchain (aiswmm CLI, SWMM solver, MCP servers).

What this skill provides

• Transparent CSV-to-JSON mapping for:
• land use class -> SWMM `[SUBCATCHMENTS]` + `[SUBAREAS]` defaults
• soil texture/type -> SWMM `[INFILTRATION]` (Green-Ampt) defaults
• Deterministic, auditable outputs with explicit fallback usage and unmatched-key reporting.
• Optional merge step that emits one builder-ready JSON artifact.

Scripts

• `scripts/landuse_to_swmm_params.py`
• maps `subcatchment_id + landuse_class` to runoff/subarea parameters
• `scripts/soil_to_greenampt.py`
• maps `subcatchment_id + soil_texture` to Green-Ampt infiltration parameters
• `scripts/merge_swmm_params.py`
• merges outputs from the two mapping scripts into one JSON package for future `swmm-builder`

Default lookup tables

By default, scripts read bundled lookup CSVs:

• `skills/swmm-params/references/landuse_class_to_subcatch_params.csv`
• `skills/swmm-params/references/soil_texture_to_greenampt.csv`

You can override lookup paths with CLI flags.

Minimal input format

Land use input CSV:

• required columns: `subcatchment_id`, `landuse_class`

Soil input CSV:

• required columns: `subcatchment_id`, `soil_texture`

Example files are provided under `examples/`.

Outputs

Each mapper writes explicit JSON containing:

• `records` (row-level audit trail)
• `sections` (SWMM-oriented lists keyed by subcatchment)
• `unmatched_*` lists (rows that used fallback)
• `counts` summary

The merge script writes:

• `sections` (`subcatchments`, `subareas`, `infiltration`)
• `by_subcatchment` (combined record per subcatchment ID)
• `incomplete_ids` (IDs missing one or more sections)

CLI flags

All three scripts share these optional flags:

• `--strict` — fail instead of using the `DEFAULT` fallback row when an input key is missing from the lookup table. Useful for auditable production runs where silent fallback would mask a data gap.

`landuse_to_swmm_params.py` also accepts:

• `--subcatchment-column <col>` — override the CSV column used as the subcatchment ID (default: `subcatchment_id`).
• `--landuse-column <col>` — override the CSV column used as the land use class (default: `landuse_class`).

`soil_to_greenampt.py` also accepts:

• `--subcatchment-column <col>` — override the CSV column used as the subcatchment ID (default: `subcatchment_id`).
• `--soil-column <col>` — override the CSV column used as the soil texture/type (default: `soil_texture`).

MCP

MCP wrapper location:

• `mcp/swmm-params/server.js`

Exposed tools:

• `map_landuse` (`inputCsvPath`, optional `lookupCsvPath`, `outputPath`)
• `map_soil` (`inputCsvPath`, optional `lookupCsvPath`, `outputPath`)
• `merge_params` (`landuseJsonPath`, `soilJsonPath`, `outputPath`)

Quick start:

npm --prefix mcp/swmm-params install
npm --prefix mcp/swmm-params run start

Known limitations

• Lookup mapping is key-based only (no spatial interpolation or fuzzy matching).
• A fallback row is expected in lookup tables (`DEFAULT` for land use, `-` or `DEFAULT` for soil).
• No unit conversion or calibration logic is included here.
• This skill only maps parameters; it does not write a full SWMM `.inp`.

Example commands

python3 skills/swmm-params/scripts/landuse_to_swmm_params.py \
  --input skills/swmm-params/examples/landuse_input.csv \
  --output runs/swmm-params/example_landuse.json

python3 skills/swmm-params/scripts/soil_to_greenampt.py \
  --input skills/swmm-params/examples/soil_input.csv \
  --output runs/swmm-params/example_soil.json

python3 skills/swmm-params/scripts/merge_swmm_params.py \
  --landuse-json runs/swmm-params/example_landuse.json \
  --soil-json runs/swmm-params/example_soil.json \
  --output runs/swmm-params/example_builder_params.json