Tutorials

Step-by-step tutorials for common pyiwfm workflows.

• Tutorial: Reading an Existing IWFM Model
  • Learning Objectives
  • Overview
  • Quick Load
  • Inspecting the Model
  • Stream Network
  • Lakes
  • Stratigraphy and Ground Surface
  • Loading with Error Handling
  • Loading Individual Components
  • Reading Simulation Results
  • Comment-Preserving Load
  • Exporting the Loaded Model
  • Complete Script
  • Next Steps
• Tutorial: Building the IWFM Sample Model from Scratch
  • Learning Objectives
  • Overview
  • Section 1: Create the Mesh
  • Section 2: Define Stratigraphy
  • Section 3: Groundwater Component
  • Section 4: Stream Component
  • Section 5: Lake Component
  • Section 6: Root Zone Component
  • Section 7: Assemble and Write the Model
  • Section 8: Run the Preprocessor
  • Section 9: Run the Simulation
  • Section 10: Visualize Results
  • Interactive Viewing
  • Complete Script
  • Next Steps
• Tutorial: Mesh Generation
  • Learning Objectives
  • Step 1: Import Libraries
  • Step 2: Define the Model Boundary
  • Step 3: Add Stream Constraints
  • Step 4: Add Well Locations
  • Step 5: Define Refinement Zones
  • Step 6: Generate the Mesh
  • Step 7: Convert to AppGrid
  • Step 8: Visualize the Mesh
  • Step 9: Export to GIS
  • Step 10: Analyze Mesh Quality
  • Complete Script
  • Next Steps
• Tutorial: Mixed Triangular-Quadrilateral Mesh
  • Learning Objectives
  • Prerequisites
  • Step 1: Define Model Geometry
  • Step 2: Generate Three Mesh Variants
  • Step 3: Visualize All Three Modes Side by Side
  • Step 4: Color Elements by Type in a Mixed Mesh
  • Step 5: Compare Element Area Distributions
  • Step 6: Convert and Export
  • Complete Script
  • Next Steps
• Tutorial: Visualization
  • Learning Objectives
  • Setup
  • Part 1: GIS Export
  • Part 2: VTK Export for ParaView
  • Part 3: Matplotlib Plotting
  • Summary
• Tutorial: Model Comparison
  • Learning Objectives
  • Setup: Create Two Model Versions
  • Part 1: Comparing Meshes
  • Part 2: Comparing Stratigraphy
  • Part 3: Combined Model Diff
  • Part 4: Computing Performance Metrics
  • Part 5: Time Series Comparison
  • Part 6: Spatial Comparison
  • Part 7: Generating Reports
  • Part 8: Visualizing Differences
  • Summary
• Tutorial: Calibration Workflow
  • Learning Objectives
  • Step 1: Reading SMP Files
  • Step 2: IWFM2OBS – Interpolate to Observation Times
  • Step 2b: Model-Discovery Mode (IWFM2OBS from Simulation Main File)
  • Step 3: Cluster Observation Wells
  • Step 4: Compute Typical Hydrographs (CalcTypHyd)
  • Step 5: Calibration Metrics
  • Step 6: Calibration Plots
  • Step 7: Parse SimulationMessages.out
  • CLI Commands
  • Summary
• Tutorial: Packaging and Running IWFM Models
  • Learning Objectives
  • Prerequisites
  • Collecting Model Files
  • Creating a ZIP Archive
  • Generating Run Scripts
  • CLI Commands
  • Complete Workflow
  • Next Steps
• Drawdown Analysis
  • Learning Objectives
  • Prerequisites
  • Step 1: Load Head Data
  • Step 2: Compute Drawdown
  • Step 3: Element-Averaged Drawdown
  • Step 4: Maximum Drawdown Map
  • Step 5: Visualize with Matplotlib
  • Step 6: Drawdown Range for Color Scaling
  • Web Viewer: Drawdown Mode
• Stream Depletion Analysis
  • Learning Objectives
  • Prerequisites
  • Step 1: Compute Stream Depletion
  • Step 2: Inspect Individual Reaches
  • Step 3: Plot Depletion Timeseries
  • Step 4: Compare Baseline vs Scenario Flows
  • Step 5: Multi-Reach Summary
  • Serialization
• Simulation Diagnostics
  • Learning Objectives
  • Prerequisites
  • Step 1: Parse Simulation Messages
  • Step 2: Filter by Severity
  • Step 3: Plot Convergence
  • Step 4: Mass Balance Error Analysis
  • Step 5: Spatial Hotspot Analysis
  • Step 6: Convergence Summary
  • Web Viewer Diagnostics
• Mesh Quality Analysis
  • Learning Objectives
  • Prerequisites
  • Step 1: Load a Mesh
  • Step 2: Compute Mesh Quality
  • Step 3: Inspect Individual Elements
  • Step 4: Histogram of Aspect Ratios
  • Step 5: Spatial Visualization of Skewness
  • Step 6: Quality Summary for API
  • Quality Thresholds

Overview

These tutorials walk you through complete workflows using pyiwfm:

Reading an Existing Model (C2VSimCG)

Load C2VSimCG (California Central Valley Simulation – Coarse Grid), inspect its mesh, streams, lakes, stratigraphy, and create visualizations. Start here if you already have an IWFM model and want to work with it in Python.

Building the Sample Model from Scratch

Build the official IWFM sample model programmatically – mesh, stratigraphy, groundwater, streams, lakes, root zone – then run the preprocessor and simulation and visualize results.

Mesh Generation

Create a finite element mesh from scratch, including defining boundaries, adding stream constraints, and refining areas of interest.

Mixed Triangular-Quadrilateral Mesh

Generate meshes with Gmsh that combine triangles and quadrilaterals. Compare pure triangle, pure quad, and mixed element modes side by side, and visualize element type distributions and area statistics.

Visualization

Export model data for visualization in GIS software, ParaView, and matplotlib. Create publication-quality figures.

Model Comparison

Compare two model versions, compute performance metrics, and generate comparison reports.

Calibration Workflow

Cluster observation wells, interpolate simulated heads to observation times (IWFM2OBS), compute typical hydrographs (CalcTypHyd), and create publication-quality calibration figures.

Packaging and Running Models

Package an IWFM model directory into a distributable ZIP archive, generate platform-appropriate run scripts (.bat, .ps1, .sh), and use the pyiwfm package and pyiwfm run CLI commands.

Drawdown Analysis

Compute drawdown relative to a reference timestep, visualize spatially with diverging colormaps, and use the web viewer’s drawdown mode.

Stream Depletion Analysis

Compare baseline and pumping scenario model runs to quantify stream flow depletion, plot timeseries, and interpret cumulative depletion.

Simulation Diagnostics

Parse IWFM SimulationMessages.out files, track convergence iterations, identify mass balance errors, and locate problem areas.

Mesh Quality Analysis

Compute element quality metrics (aspect ratio, skewness, angles), identify problematic elements, and visualize quality spatially.

Prerequisites

Make sure you have pyiwfm installed with the required optional dependencies:

pip install pyiwfm[all]

The tutorials assume basic familiarity with:

• Python and NumPy arrays

• IWFM model concepts (mesh, stratigraphy, layers)

• Basic GIS concepts (coordinate systems, shapefiles)