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 "pipedream-solver @ git+https://github.com/anuga-community/pipedream.git@anuga"   # pipedream backend — the community fork, 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 that pipedream is the community fork's anuga branch (see next paragraph) before debugging the script; the fix is pip install -e . --no-deps and pip install -e .[pipedream].

pipedream comes from the anuga-community fork, branch anuga (pyproject.toml's pipedream extra and environment.yml both point there). Upstream mdbartos/pipedream has had no commit since May 2024 and neither its PyPI release (0.2.2) nor its master works with a current numpy/pandas: 0.2.2 uses np.bool8 (removed in numpy 2.x) and master's SuperLink(...) construction crashes under pandas 3's Copy-on-Write, because it hands read-only .values arrays to numba kernels compiled with eager, writable-only signatures. The fork's anuga branch is upstream master plus the two fixes (np.bool_; writable copies of the DataFrame-derived arrays). Both are also open upstream (mdbartos/pipedream#73, #74); if they are ever merged and released, point the extra back at upstream. There is no longer a pandas<3 pin.