Metadata-Version: 2.5
Name: ryan-culverts
Version: 26.10.18.4
Summary: Independent SI culvert hydraulics: numerical foundations and traceable methods.
Project-URL: Changelog, https://github.com/Chain-Frost/ryan-culverts/blob/main/docs/changelog.md
Project-URL: Documentation, https://chain-frost.github.io/ryan-culverts/
Project-URL: Issues, https://github.com/Chain-Frost/ryan-culverts/issues
Project-URL: Repository, https://github.com/Chain-Frost/ryan-culverts
Author: Ryan Brook
License-Expression: SUL-1.0
License-File: LICENSE
Keywords: civil-engineering,culvert,hydraulics,hydrology
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Typing :: Typed
Requires-Python: >=3.13
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mkdocs-material>=9.6; extra == 'dev'
Requires-Dist: mkdocs>=1.6; extra == 'dev'
Requires-Dist: mkdocstrings[python]>=0.30; extra == 'dev'
Requires-Dist: pymarkdownlnt>=0.9.39; extra == 'dev'
Requires-Dist: pyright>=1.1.410; extra == 'dev'
Requires-Dist: pytest>=9; extra == 'dev'
Requires-Dist: ruff==0.16.6; extra == 'dev'
Provides-Extra: external-validation
Requires-Dist: run-hy8>=2026.10.5.1; extra == 'external-validation'
Description-Content-Type: text/markdown

# 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](docs/work/long-term-development-plan.md) defines the scope and
development sequence. The `culvert_solver` package contains provisional circular 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](docs/releases/README.md) before using the package.

Agents should start with the [work register](docs/work/README.md), 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](AGENTS.md).

The [documentation site](https://chain-frost.github.io/ryan-culverts/) 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](docs/legacy/README.md) for retained evidence, potential reuse from
the preserved scenarios, and decisions made before implementation.

Additional implementation references are recorded in the
[reference register](docs/references.md).

Development records: [progress](docs/progress.md),
[computational basis](docs/computational_basis.md),
[architecture](docs/architecture.md), [validation](docs/validation.md) and
[HY-8 capability matrix](docs/hy8_feature_parity.md).

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](docs/packaging.md#python-support-policy).

```powershell
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.

```powershell
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](docs/packaging.md) 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](docs/pypi_publishing.md).

## License

This project is licensed under the [Sustainable Use License v1.0](LICENSE)
(`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.
