How modflowpy/flopy works
FloPy is a Python modeling toolkit, not a standalone simulator. Its architecture is centered on building, writing, running, and post-processing groundwater models for the MODFLOW ecosystem and related tools.
1. Primary role and boundary
- The library sits between user Python scripts and external hydrologic executables such as MODFLOW 6, MODFLOW-2005, MODFLOW-NWT, MODFLOW-USG, MODPATH, MT3DMS/MT3D-USGS, and SEAWAT.
- FloPy itself does not solve the physics; it generates input decks, launches solvers, and reads their outputs.
2. Top-level package layout
- flopy/__init__.py exposes the main public API.
- The package is split by model family: mf6, modflow, mfusg, modpath, mt3d, seawat, plus cross-cutting support modules like utils, plot, export, discretization, and pest.
3. Core object model
- The foundational classes live in mbase.py, pakbase.py, and datbase.py.
- These define common behaviors for model containers, packages, file writing, loading, and bookkeeping of data and units.
- Most model-family classes extend these shared abstractions rather than reimplementing file I/O or lifecycle logic.
4. MODFLOW 6 subsystem
- flopy/mf6 is the most structured part of the repo.
- It has explicit layers for simulation, model, package, and data objects:
- mfsimbase.py, mfmodel.py, mfpackage.py
- data/ for typed MF6 data containers and storage
- coordinates/ for simulation time and grid/model-dimension metadata
- modflow/ inside mf6 contains the generated package classes for GWF, GWT, GWE, PRT, exchanges, observations, etc.
- utils/codegen is important here: much of the MF6 package surface is generated from templates, which is a key architectural boundary.
5. Legacy MODFLOW-family subsystems
- flopy/modflow supports older structured-grid MODFLOW variants and packages such as BAS, DIS, LPF, WEL, RCH, SFR, UZF, HFB, MNW, PCG, NWT, etc.
- flopy/mfusg handles unstructured-grid MODFLOW-USG and connected-lake/conduit variants.
- flopy/seawat combines flow and transport coupling for SEAWAT workflows.
- flopy/mt3d provides MT3DMS/MT3D-USGS transport packages and coupling files.
- flopy/modpath handles particle tracking simulations and particle-group definitions.
6. Grid and discretization layer
- discretization/ defines the grid representations used across model families:
- structuredgrid.py
- vertexgrid.py
- unstructuredgrid.py
- grid.py
- modeltime.py
- This layer is the geometric backbone for indexing cells, mapping coordinates, and relating model data to spatial layouts.
- It is a shared dependency for modeling, plotting, export, and intersection utilities.
7. Utilities for file parsing and geospatial operations
- flopy/utils is the main support library for reading solver outputs and handling model-related files.
- It includes binary readers, list-file parsers, observation readers, particle track readers, geospatial helpers, rasters, geometry, grid intersection, and zone budget utilities.
- This layer is where most “read results back into Python” workflows terminate.
8. Post-processing and analysis flow
- Typical data flow is: model object creation → write input files → run external solver → read binary/list outputs → analyze arrays and budgets.
- Post-processing helpers in utils/postprocessing.py and MF6-specific helpers in mf6/utils/postprocessing.py convert solver outputs into derived fields like specific discharge and other analysis-ready arrays.
9. Export and visualization
- flopy/export contains writers for NetCDF, VTK, shapefiles, and metadata/units normalization.
- flopy/plot provides map-view and cross-section plotting on top of matplotlib.
- These modules consume grid/model/output objects and form the presentation/interop boundary of the library.
10. Pest and templating support
- flopy/pest supports PEST workflows through parameter and template writers.
- This is a specialized preprocessing path for calibration/estimation rather than core model execution.
11. Examples, docs, and reference data
- examples/ and .docs/Notebooks/ contain curated model setups, sample inputs, and tutorial scripts across many supported packages.
- Large example datasets under examples/data/ act as regression references and documentation assets.
- The docs tree and notebook scripts are effectively a second “surface area” of the project, showing how the API is expected to be composed.
12. Testing and regression architecture
- autotest/ is broad and data-driven, with snapshot tests, regression tests, and binary file/output validation.
- The test suite is organized around file formats, package behavior, grids, plotting, geospatial utilities, and end-to-end model examples.
- This repo is validated heavily against expected solver outputs, which is essential because correctness depends on interoperability with external executables.
13. Tooling, build, and release pipeline
- pyproject.toml defines packaging and Python requirements.
- GitHub Actions workflows cover CI, examples, docs, codegen, benchmarking, and release publishing.
- scripts/ includes maintenance tasks like version updates and benchmark processing.
- Documentation is built separately under .docs/ and docs/, with Read the Docs integration.
14. How the pieces connect
- The cleanest architecture diagram is a layered flow:
- user scripts and notebooks at the top
- FloPy model/family APIs in the middle
- shared grid/utils/export/plot subsystems underneath
- external MODFLOW-family binaries on the right as execution targets
- output readers/post-processing feeding results back to Python
- The most important boundary is that FloPy is a Python orchestration and I/O layer around external numerical engines.
Main entry points: utils Utils · mbase.py Model base · mfsimbase.py MF6 sim · autotest CI & tests
Components 27
User & docs
Entry points, tutorials, and example workflows that show how FloPy is used.
- README · High-level project overview and usage boundary.
README.md - Examples · Curated model setups and reference data across supported workflows.
examples - Docs notebooks · Notebook-style tutorials and rendered docs for common FloPy compositions.
.docs/Notebooks
Core API
Shared model/package abstractions used across model families.
- Public API · Top-level imports and public surface exposed to users.
flopy/__init__.py - Model base · Shared model lifecycle, writing, loading, and bookkeeping behavior.
flopy/mbase.py - Package base · Common package-level abstractions and file handling.
flopy/pakbase.py - Data base · Shared data containers, units, and data-file mechanics.
flopy/datbase.py
MODFLOW 6
The most structured subsystem: simulation, model, package, and data layers for MF6.
- MF6 sim · Simulation orchestration and top-level MF6 entry points.
flopy/mf6/mfsimbase.py - MF6 model · Model containers and coordination within a simulation.
flopy/mf6/mfmodel.py - MF6 package · MF6 package behavior shared by generated package classes.
flopy/mf6/mfpackage.py - MF6 data · MF6-specific array, list, scalar, and storage objects.
flopy/mf6/data - MF6 coords · Simulation time and model/grid dimension metadata.
flopy/mf6/coordinates - Codegen · Template-based generation of MF6 package and simulation classes.
flopy/mf6/utils/codegen
Legacy models
Older MODFLOW-family and coupled transport/particle-tracking subsystems.
- MODFLOW 2005 · Structured-grid legacy MODFLOW packages and solver wiring.
flopy/modflow - MODFLOW-USG · Unstructured-grid MODFLOW-USG and conduit/lake variants.
flopy/mfusg - MT3D · Transport packages and coupling for MT3DMS/MT3D-USGS.
flopy/mt3d - SEAWAT · Coupled variable-density flow and transport workflows.
flopy/seawat - MODPATH · Particle tracking simulations and particle data/group definitions.
flopy/modpath
Shared utilities
Grids, parsing, geospatial helpers, post-processing, and interoperability support.
Output & analysis
Readers and transformations that turn solver outputs into analysis-ready data.
- Postprocess · Derived-field helpers for discharge, budgets, and other analysis-ready outputs.
flopy/utils/postprocessing.py - Export · NetCDF, VTK, shapefile, units, and metadata writers.
flopy/export - Plot · Map-view and cross-section plotting on matplotlib.
flopy/plot - PEST · Template and parameter writers for PEST workflows.
flopy/pest
Tooling
Build, CI, code generation, documentation, and release automation.
- CI & tests · Regression, snapshot, and example-based validation against solver outputs.
autotest - Build tools · Packaging, release, docs, benchmark, and maintenance automation.
pyproject.toml
Other components
- External solvers · MODFLOW-family executables that FloPy writes inputs for and runs externally.
Connections 39
- README → Public API: introduces · Explains the public API and repository purpose.
- Docs notebooks → Public API: uses · Tutorials demonstrate the library surface.
- Examples → MODFLOW 2005: demonstrates · Example inputs exercise legacy model families.
- Examples → MF6 sim: demonstrates · Examples cover MF6 simulations and packages.
- Public API → Model base: exports · Public API re-exports shared model abstractions.
- Public API → Grids: exports · Public API exposes grid and time utilities.
- Model base → Package base: depends on · Models are composed from packages.
- Package base → Data base: depends on · Packages rely on common data plumbing.
- MF6 sim → MF6 model: contains · A simulation manages one or more models.
- MF6 model → MF6 package: contains · Models are built from MF6 packages.
- MF6 package → MF6 data: uses · Package state is stored in typed data objects.
- MF6 sim → MF6 coords: uses · Simulation time and dimensions feed MF6 coordination.
- Codegen → MF6 package: generates · Templates create much of the MF6 package surface.
- Codegen → MF6 sim: generates · Templates also generate simulation/model scaffolding.
- MODFLOW 2005 → Model base: extends · Legacy MODFLOW packages build on shared model bases.
- MODFLOW-USG → Model base: extends · USG classes reuse the core abstractions.
- MT3D → Model base: extends · Transport packages use the same core lifecycle.
- SEAWAT → Model base: extends · SEAWAT workflows are built on common model abstractions.
- MODPATH → Model base: extends · Particle-tracking sims use the shared model base.
- Grids → Utils: feeds · Grid geometry is consumed by intersection and helper utilities.
- Utils → Postprocess: feeds · Readers and array helpers support post-processing.
- Utils → Export: feeds · Parsed grids and arrays are exported to external formats.
- Utils → Plot: feeds · Plotting consumes grids, arrays, and file readers.
- MF6 data → Utils: uses · MF6 data objects rely on shared parsing and file helpers.
- Postprocess → Utils: reads · Post-processing operates on solver outputs and grid utilities.
- Export → Grids: uses · Export formats need grid geometry and indexing.
- Plot → Grids: uses · Plots are rendered from grid geometry and cell layout.
- PEST → Utils: uses · Template writers reuse shared file and array utilities.
- MF6 sim → External solvers: runs · FloPy launches external executables rather than solving physics itself.
- MODFLOW 2005 → External solvers: runs · Legacy model families write inputs for external binaries.
- MODFLOW-USG → External solvers: runs · USG workflows target external MODFLOW-family solvers.
- MT3D → External solvers: runs · Transport workflows execute external transport engines.
- SEAWAT → External solvers: runs · SEAWAT wrappers target external coupled solvers.
- MODPATH → External solvers: runs · Particle tracking simulations are executed externally.
- CI & tests → Examples: validates · Regression tests reuse example data and expected outputs.
- CI & tests → Utils: validates · Tests cover readers, grids, geospatial utilities, and post-processing.
- CI & tests → MF6 sim: validates · The suite checks MF6 behavior and output compatibility.
- Build tools → Codegen: drives · Tooling includes generated-class workflows and maintenance scripts.
- Build tools → CI & tests: drives · CI workflows enforce correctness and release readiness.