API reference

These entries are generated from the installed Python package. See the tutorials for complete workflows and required units.

Basin

class basinforge.Basin(basin_id, dates, precipitation, pet, qobs=None, temperature=None, area_km2=100.0, latitude=0.0, timestep='daily')

Contiguous forcing record; P/PET/Q are depths per model time step.

Parameters:

  • basin_id (str)

  • dates (DatetimeIndex)

  • precipitation (ndarray)

  • pet (ndarray)

  • qobs (ndarray | None)

  • temperature (ndarray | None)

  • area_km2 (float)

  • latitude (float)

  • timestep (str)

Model

class basinforge.Model(name: str, timestep: str, defaults: dict, bounds: dict, runner: Callable, variant: str, temperature_required: bool = False, backend: str = 'python')
Parameters:

  • name (str)

  • timestep (str)

  • defaults (dict)

  • bounds (dict)

  • runner (Callable)

  • variant (str)

  • temperature_required (bool)

  • backend (str)

CalibrationConfig

class basinforge.CalibrationConfig(method: 'str' = 'de', objective: 'str | dict' = 'nse', warmup: 'int' = 365, calibration_end: 'str | None' = None, calibration_fraction: 'float | None' = None, validation_start: 'str | None' = None, seed: 'int' = 42, maxiter: 'int' = 100, popsize: 'int' = 10, samples: 'int' = 1000, polish: 'bool' = False, bounds: 'dict | None' = None, fixed: 'dict' = <factory>)
Parameters:

  • method (str)

  • objective (str | dict)

  • warmup (int)

  • calibration_end (str | None)

  • calibration_fraction (float | None)

  • validation_start (str | None)

  • seed (int)

  • maxiter (int)

  • popsize (int)

  • samples (int)

  • polish (bool)

  • bounds (dict | None)

  • fixed (dict)

calibrate

basinforge.calibrate(basin, model='GR4J', config=None, *, progress=None)
Parameters:
Return type:

CalibrationResult

calibrate_many

basinforge.calibrate_many(basins, model='GR4J', config=None, *, workers=1, output=None, resume=False, fail_fast=False, progress=None)

Independent basin fits; errors isolated, successful completed jobs reusable.

calibrate_shared

basinforge.calibrate_shared(basins, model='GR4J', config=None, *, basin_weights=None)

One common parameter vector; equal basin weighting, not pooled hydrographs.

compare_models

basinforge.compare_models(basins, models, config=None, **kwargs)

calibrate_multistart

basinforge.calibrate_multistart(basin, model='GR4J', config=None, *, seeds=(42, 43, 44), progress=None)

Repeat independent searches; select by training loss, never validation.

run_experiment

basinforge.run_experiment(basin, model='GR4J', config=None, *, sensitivity='morris', sensitivity_options=None, output=None, starts=1, seeds=None)

Fit, analyze parameter sensitivity and optionally export a complete study.

sensitivity is "morris", "sobol" or None. Sensitivity uses the calibration bounds (and fixed parameters) and scores only the chronological training segment after warmup. The validation record is reserved for fit evaluation and never enters the sensitivity indices. If output is given, fit, HTML/PNG report and sensitivity JSON are staged and published as one new directory; existing output is refused.

morris_sensitivity

basinforge.morris_sensitivity(basin, model='GR4J', config=None, *, trajectories=12, levels=4, seed=42, bounds=None)

Morris screening using normalized elementary effects.

Evaluations = trajectories * (free parameters + 1). mu_star is the mean absolute effect on the minimized configured training objective per unit change across a parameter’s declared range. sigma describes effect variability and can indicate nonlinearity or interactions.

sobol_sensitivity

basinforge.sobol_sensitivity(basin, model='GR4J', config=None, *, samples=256, seed=42, bounds=None, bootstrap=200)

Saltelli/Jansen Sobol indices from a scrambled Sobol digital net.

samples must be a power of two (minimum four). Runtime is samples * (parameters + 2) model simulations. Bootstrap intervals quantify sampling variability of the index estimators, not hydrologic predictive uncertainty.

simulate_ensemble

basinforge.simulate_ensemble(basin, model, parameter_sets, *, quantiles=(0.05, 0.5, 0.95))

Descriptive parameter-scenario spread, not a calibrated posterior.

export_report

basinforge.export_report(basin, fit, directory)

Create a static HTML/PNG report; never overwrite an existing directory.

get_model

basinforge.get_model(name)
Parameters:

name (str | Model)

Return type:

Model

list_models

basinforge.list_models(*, include_optional=False)

configure_marrmot

basinforge.configure_marrmot(*, octave=None, package_list=None, timeout=300)

Configure picklable runners; settings survive spawned basin workers.

check_marrmot

basinforge.check_marrmot(*, octave=None, package_list=None, timeout=30)

Start the runtime and instantiate every class, checking optim too.

marrmot_details

basinforge.marrmot_details(basin, model, parameters=None)

Expose actual ET, stores and solver residuals for diagnostics.

close_marrmot

basinforge.close_marrmot()

Release only Octave workers owned by this Python process.