MNiShed v3.1.0

MNiShed v3.1.0 — a backward-compatible minor release (single-cascade behaviour is unchanged from v3.0.0).

Added

• Parallel sub-catchments: a basin can be partitioned into spatially distinct
  zones that drain to the same channel in parallel, each with its own
  reservoir cascade and snowpack/frozen-ground state. Basin discharge and
  storage are the area-weighted means over sub-catchments. Configure with a
  sub_catchments: YAML block (each entry has a name, area_fraction, its
  own reservoirs block, and optional initial_conditions); calibrate by
  passing a sub_catchments=[...] argument to run_and_score. Supported on
  both the pure-Python and Numba JIT time loops. A single sub-catchment of
  area 1.0 reproduces the previous single-cascade behaviour exactly, so
  existing configurations and calls are unchanged. New SubCatchment class
  and Buckets.sub_catchments / Buckets.n_sub_catchments.
  run_and_score chains per-sub-catchment storage state (reservoir depths,
  snowpack, frozen-ground index, carried deficit) across decade windows:
  final_states / initial_states are nested per sub-catchment when there
  are several, and stay flat/scalar for a single sub-catchment.
• The Numba JIT now covers PDM saturation-excess (pdm_H0) and
  et_water_stress; those configurations previously fell back to the
  pure-Python loop. The JIT and pure-Python loops remain verified-identical, so
  the JIT is now used for every supported configuration whenever Numba is
  importable.

Changed

• The pure-Python time-loop fallback is no longer silent. Buckets.run() emits
  a one-time UserWarning when Numba is installed but fails to import (usually
  a NumPy/Numba version mismatch), so an unexpected ~100× slowdown is visible.
  A plain "Numba not installed" stays quiet, since pure Python is the expected
  default without the jit extra.

Deprecated

• The flat single-sub-catchment state shape ({'reservoirs': [...], 'snowpack': ..., 'fgi': ...}) for run_and_score's initial_states /
  post_spinup_states. Passing it now emits a DeprecationWarning; it will be
  removed in v4.0 in favour of the uniform per-sub-catchment form
  ({'sub_catchments': [...]}). See
  #18. The nested form is
  accepted at any number of sub-catchments (including one) and does not warn.

Fixed

• run_and_score now validates chained initial_states / post_spinup_states
  and raises a clear ValueError if they contain non-finite (NaN/inf) values,
  naming the offending key/index. Previously a NaN state from a partial-data or
  failed decade propagated silently — every modelled flow became NaN and the
  score looked merely poor rather than broken. (None reservoir entries in
  post_spinup_states, meaning "keep the spin-up value", are still allowed.)
• The BMI snowpack__liquid_equivalent_depth and
  land_surface__frozen_ground_index outputs are now the area-weighted basin
  mean over sub-catchments, instead of reporting only the first sub-catchment.
  Exact for a single sub-catchment, so K=1 couplers are unchanged
  (#16).