ryan-culverts

An early-stage culvert hydraulics library built around primary hydraulic references, analytical validation, and mixed-group crossings. The retained wheel is an alpha package for integration testing; it is not engineering design software.

The long-term development plan defines the scope and development sequence. The culvert_solver package contains provisional circular, horizontal/vertical elliptical, and box hydraulics through rating-curve generation, including mixed groups, constant-crest unsubmerged roadway overtopping, and road-level inventories. Geometry, numerical foundations, and several equation-level calculations have analytical or published-example tests; combined-system validation remains bounded. See the maintained release notes before using the package.

Agents should start with the work register, which separates active remediation from deferred scope and links the current acceptance criteria. Coding agents, including web-only agents without HY-8, must also follow the repository agent instructions.

The documentation site is built from the maintained user and engineering documentation, generated API reference, and changelog; GitHub Pages must be enabled for the repository before its first deployment.

The previous culvertflow prototype has been retired. See the cleanup review for retained evidence, potential reuse from the preserved scenarios, and decisions made before implementation.

Additional implementation references are recorded in the reference register.

Development records: progress, computational basis, architecture, validation and HY-8 capability matrix.

Use your selected Python installation. Python 3.13 and 3.14 are supported; Python 3.13 is the minimum installation version. See the Python support policy.

python -m pip install --user -e ".[dev]"
python -m pytest -q
python -m ruff check .
python -m pyright
python -m pymarkdown -d MD013 scan -r README.md docs

The Markdown check allows long lines for tables and source URLs. Heading rules, including MD025, remain enabled.

The dev extra supports offline tests and CI without run-hy8 or HY-8. Local executable comparisons use the separate external-validation extra and require the separately installed Windows HY-8 executable. The hydraulic library has no runtime dependency on either.

python -m pip install --user -e ".[dev,external-validation]"
python -m pyright --project pyright-external.json

The ordinary Pyright check excludes those optional harnesses; GitHub CI installs only dev and runs all offline tests against retained comparison evidence.

Dependencies and build metadata live in pyproject.toml; there is no separate requirements.txt. Pip installs the package and its dev extra, while Hatchling builds the universal wheel through python -m build --wheel. See the packaging workflow for install and build commands.

On Windows, .\package.bat increments the calendar version, builds and verifies the universal wheel, then replaces the previous project wheel only after success. .\install-latest-wheel.bat installs the newest local wheel, and .\package_and_install.bat performs both steps with fail-fast exit handling. Use .\force-reinstall.bat for the existing wheel or .\package_and_force_install.bat to rebuild before forcing replacement of the installed package.

For PyPI release setup and automation, see publishing.

License

This project is licensed under the Sustainable Use License v1.0 (SUL-1.0).

The software may be used and modified for personal, non-commercial, and internal business purposes, including commercial professional and consulting work where the software itself is not provided as a commercial product or service.

Commercial distribution, incorporation into software supplied commercially to third parties, or provision of the software or its functionality as a paid hosted service, SaaS, or API is not permitted under the free licence.

Separate commercial licensing may be available on request.