pyiwfm: Python Interface for IWFM#

pyiwfm is a Python package for working with IWFM (Integrated Water Flow Model) models developed by the California Department of Water Resources.

Getting Started

New to pyiwfm? Start here to learn how to install and use the package.

Installation

User Guide

Learn how to use pyiwfm’s core features for reading, writing, and manipulating IWFM models.

User Guide

Tutorials

Step-by-step tutorials for common workflows like mesh generation, visualization, and model comparison.

Tutorials

API Reference

Complete API documentation for all modules, classes, and functions.

API Reference

Visualization Gallery

Browse examples showcasing pyiwfm’s visualization capabilities for meshes, scalar fields, streams, and water budgets.

Visualization Gallery

Drawdown Analysis

Compute and visualize groundwater drawdown relative to a reference timestep with diverging colormaps.

Drawdown Analysis

Simulation Diagnostics

Parse simulation logs to track convergence, mass balance errors, and identify problem areas.

Simulation Diagnostics

Stream Depletion

Compare baseline and pumping scenarios to quantify impact on stream flows.

Stream Depletion Analysis

Features#

Read/Write IWFM Files: Support for ASCII, binary, HDF5, and HEC-DSS formats
Mesh Generation: Create finite element meshes using Triangle or Gmsh
GIS Export: Export to GeoPackage, Shapefile, and GeoJSON formats
Interactive Web Viewer: Browser-based visualization with FastAPI, React, vtk.js, and deck.gl — includes data export (CSV, GeoPackage, matplotlib plots), model comparison, drawdown animation, and head statistics
Calibration Tools: SMP observation file I/O, IWFM2OBS time interpolation with automatic model file discovery, multi-layer T-weighted observation well processing, fuzzy c-means well clustering, typical hydrograph computation (CalcTypHyd), SimulationMessages.out parser, and publication-quality calibration figures
PEST++ Integration: Complete interface for parameter estimation with PEST++
Ensemble Methods: Prior/posterior ensemble generation for pestpp-ies
Subprocess Runner: Run IWFM executables and manage scenarios
Plotting: Matplotlib-based visualization of meshes and scalar fields, including server-side plot generation via the web API
Model Comparison: Compare models with metrics and generate reports, accessible via web viewer endpoint
Consistent Component Interface: BaseComponent ABC provides validate() and n_items across all 6 model components
Drawdown Analysis: Compute drawdown relative to reference timesteps with per-node, per-element, max-map, and robust range calculations
Stream Depletion: Compare baseline and pumping model runs to quantify stream flow depletion at individual reaches
Budget Checks: Mass balance sanity checks to detect timesteps with inflow/outflow/storage imbalance
Mesh Quality: Element-level quality metrics (aspect ratio, skewness, min/max angle) with aggregate statistics
Simulation Diagnostics: Parse SimulationMessages.out for structured messages, convergence tracking, mass balance errors, and spatial hotspots
PEST++ CLI: pyiwfm pest setup/run/analyze commands for end-to-end calibration from the command line

Quick Example#

from pyiwfm.core.mesh import AppGrid, Node, Element
from pyiwfm.visualization import GISExporter

# Create a simple mesh
nodes = {
    1: Node(id=1, x=0.0, y=0.0),
    2: Node(id=2, x=100.0, y=0.0),
    3: Node(id=3, x=50.0, y=100.0),
}
elements = {
    1: Element(id=1, vertices=(1, 2, 3), subregion=1),
}
grid = AppGrid(nodes=nodes, elements=elements)

# Export to GeoPackage
exporter = GISExporter(grid=grid, crs="EPSG:26910")
exporter.export_geopackage("model.gpkg")

Installation#

Install pyiwfm using pip:

pip install pyiwfm

For optional dependencies:

# Mesh generation (triangle, gmsh)
pip install pyiwfm[mesh]

# VTK 3D export
pip install pyiwfm[viz]

# Web viewer (FastAPI + vtk.js + deck.gl)
pip install pyiwfm[webapi]

# PEST++ integration (scipy)
pip install pyiwfm[pest]

# Development (pytest, mypy, ruff)
pip install -e ".[dev]"

# All optional dependencies
pip install pyiwfm[all]