Installation

Python package

Python 3.11 or later is required. Install from PyPI:

python -m pip install basinforge-hydro==0.1.0
basinforge doctor

For an editable installation and the example scripts, install from the repository:

git clone https://github.com/Barbhuiya12/basinforge-hydro.git
cd basinforge-hydro
python -m venv .venv
source .venv/bin/activate
python -m pip install -e .
basinforge doctor
basinforge models

On Windows, replace activation with .venv\Scripts\activate. Wheels and source archives are also available from GitHub Releases.

The Python install supplies the 14 Python model implementations without installing LuMod or SMARTpy as runtime packages. First calls to Numba-backed kernels may be slower while compiling. Optional independent upstream parity tests use python -m pip install -e '.[dev,reference]'.

Optional MARRMoT engine

The 47 MARRMoT adapters additionally require Octave and its optim package. The wheel contains model source, not an Octave executable.

On Ubuntu/Debian:

sudo apt install octave octave-optim
basinforge doctor --check-marrmot
basinforge models --all

For other systems, use your Octave distribution and install optim using its package manager. Building packages may require a compiler and additional dependencies. With a nonstandard installation:

basinforge doctor --check-marrmot \
  --octave /path/to/octave-cli \
  --octave-package-list /path/to/local-package-list

The package-list argument is optional. Equivalent environment variables are BASINFORGE_OCTAVE and BASINFORGE_OCTAVE_PACKAGE_LIST.

from basinforge import configure_marrmot
configure_marrmot(octave="/path/to/octave-cli", timeout=300)

Preflight checks constructors/dependencies. It does not establish hydrological validity for your data.

Development and tests

python -m pip install -e '.[dev,docs]'
python -m pytest -q
python -m build

The default test run skips external-engine integration tests. With Octave installed:

BASINFORGE_TEST_MARRMOT=1 python -m pytest -q

Build this documentation

python -m pip install -e '.[docs]'
python scripts/build_site.py --output _site
python -m http.server 8000 --directory _site

Open http://localhost:8000. Existing build directories are refused; choose another --output for a later build. GitHub Pages builds the same documentation automatically from main.