anuga_drainage: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this project is

anuga_drainage couples the 2D hydrodynamic shallow-water model ANUGA (overland/surface flow) with a 1D stormwater/sewer network solver (SWMM via pyswmm, or pipedream via pipedream_solver). The 2D model handles the surface; the 1D model handles the underground pipe network; the two exchange water at inlets/manholes each timestep.

The installable package is intentionally tiny — almost all the real logic lives in the per-example run_*.py scripts. The package only provides the shared physics of the 2D↔1D exchange.

Install & environment

Assume work happens inside an existing conda environment that already has a current ANUGA built and importable. On top of that env:

pip install -e .                  # installs the anuga_drainage package
pip install pyswmm                 # SWMM backend (standard PyPI release, 2.1.0)
pip install git+https://github.com/mdbartos/pipedream.git   # pipedream backend — NOT the PyPI release

Keep the package installed editable (pip install -e .). On the maintainer's hand-built dev box (not created from environment.yml), the install has silently reverted to a plain copied install in site-packages that predates newer source — symptom: an example raises TypeError: ... got an unexpected keyword argument for a kwarg that is present in src/ (e.g. couple_from_inp(..., inlet_polygons=...)). An example that happens to use only older kwargs (e.g. real_example/run_from_inp.py) keeps working, masking the cause. When an example "stops working", first check pip show anuga_drainage is editable and python -c "import pandas; print(pandas.__version__)" is <3 (see next paragraph) before debugging the script; the fix is pip install -e . --no-deps and pip install 'pandas<3'.

pipedream must come from git master, not PyPI. The released pipedream-solver 0.2.2 uses np.bool8, removed in numpy 2.x (which the ANUGA env requires), so it crashes on SuperLink(...) construction. Git master replaced those with np.bool_. Caveat: even git master still has np.bool8 in two optional code paths — nsuperlink.py reposition_junctions() and the nquality.py water-quality solver. None of the examples use these (all have #superlink.reposition_junctions() commented out), but uncommenting reposition_junctions() will hit the bug. Fix submitted upstream: https://github.com/mdbartos/pipedream/pull/73 — once merged (and ideally released to PyPI), this caveat and the git-master requirement can be revisited.