MNiShed Documentation

A simple, flexible reservoir-based hydrological model for water balance simulation and streamflow prediction.

MNiShed (MN = Minnesota, Mni = water in Dakota, Mini = small/lumped, Shed = watershed) is a lumped conceptual model that routes precipitation through an optional snowpack and a cascade of reservoirs to produce streamflow. Ideal for long water-balance studies, climate impact assessments, and ungauged basins.

Key Features

• Cascading reservoirs – linear or nonlinear (power-law) recession, soil to groundwater, with optional leakance/threshold junctions and tile drainage

• Calibration – KGE, NSE, and log-KGE scoring; AIC model comparison; baseflow index; flow duration curve; Nash-cascade routing; decadal chaining

• Fast – Numba JIT-compiled daily time loop, roughly 100–400× faster than pure Python (see Benchmarks)

• Data-driven setup – estimate recession exponents (Brutsaert–Nieber) and parameter priors directly from observed streamflow

• Exact annual water balance – ET scaled so P - Q - ET = 0 over each water year

• Flexible ET – from data or the Thornthwaite–Chang equation; optional storage-dependent and reservoir-draw ET

• Optional snowpack module – positive-degree-day melt with rain-on-snow sensible heat

• Optional frozen ground module – Molnau & Bissell FGI blocks deep infiltration

• CSDMS Basic Model Interface – couple MNiShed with other models

• Python API and command-line interface

• Lightweight – minimal dependencies (NumPy, Pandas, SciPy, Matplotlib, PyYAML)

Getting Started

• Installation
  • Requirements
  • Optional acceleration (Numba)
  • From PyPI
  • From Source (Development)
  • Installing Documentation Dependencies
  • Verification
  • Troubleshooting
  • Next Steps
• Quick Start
  • Prepare Your Data
  • Create a Configuration File
  • Run the Model
  • Adjust Parameters
  • Next Steps
• Tutorial: From Data to Calibrated Model
  • Overview
  • Input Data Format
  • Stage 1 — Estimate Priors
  • Stage 2 — Write a Configuration File
  • Stage 3 — Quick Check Before Calibrating
  • Stage 4 — Calibrate
  • Stage 5 — Evaluate
  • See Also

User Guide

• Configuration Reference
  • Configuration File Structure
  • The timeseries section
  • The initial_conditions section
  • The catchment section
  • The general section
  • The reservoirs section
  • The snowmelt section
  • The modules section
  • ET Module Parameters
  • Complete Example
  • Illustrative Starting Points
• Model Description
  • Theory & Mathematical Formulation
  • Daily Water Balance
  • Optional Process Modules
  • Snowpack Module (Optional)
  • Frozen Ground Module (Optional)
  • Regional Groundwater Import (Optional)
  • Direct Runoff Bypass (Optional)
  • Linear Reservoir Cascade
  • Junctions Between Reservoirs (Optional)
  • Nonlinear (Power-Law) Recession (Optional)
  • Saturation-Excess Runoff (PDM, Optional)
  • Suggested Model Structures
  • Evapotranspiration
  • Model Skill Evaluation
  • Model Assumptions & Limitations

Reference

• API Reference
  • Buckets
  • Reservoir
  • Snowpack
  • run_and_score
  • CalibResult
  • HydrographSeparation
• Calibration
  • run_and_score()
  • CalibResult
  • Goodness-of-Fit Metrics
  • Practical Calibration Workflow
  • Suggested Parameter Sets
• Recession Analysis
  • Theory
  • Brutsaert–Nieber Analysis
  • Using Results in MNiShed
  • Workflow
  • Goodness of fit and the power-law assumption
  • Interpretation guide
  • References
• Data-Driven Priors
• References
  • Model Development
  • Snowpack and Rain-on-Snow
  • Frozen Ground
  • Evapotranspiration
  • Reservoir Cascade Structure
  • Channel Routing
  • Model Calibration and Evaluation
  • Software
  • External Resources

Integration

• CSDMS Basic Model Interface
  • Overview
  • Installation
  • Usage
  • Exposed Variables
  • Grid and Time
  • Caveats
  • API Reference

Performance

• Benchmarks
  • JIT scaling

Quick Example

Python API:

import mnished

model = mnished.Buckets()
model.initialize('config.yml')
model.run()
nse = model.compute_NSE(verbose=True)
model.plot()

Command-line:

mnished -y config.yml

Getting Help

• Report bugs: GitHub Issues

• Discuss: GitHub Discussions

• Learn more: CSDMS Model Page

About

MNiShed is developed and maintained by the MNiMORPH group. It is published under the GNU General Public License v3.0.

Citation:

If you use MNiShed in your research, please cite it using the information in CITATION.cff at the repository root, or via the Zenodo DOI badge above.