# modflowpy/flopy architecture

> Architecture diagram of the GitHub repository modflowpy/flopy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/modflowpy/flopy
- Repository: https://github.com/modflowpy/flopy

## Overview

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: [`flopy/utils`](https://github.com/modflowpy/flopy/tree/develop/flopy/utils) (Utils), [`flopy/mbase.py`](https://github.com/modflowpy/flopy/blob/develop/flopy/mbase.py) (Model base), [`flopy/mf6/mfsimbase.py`](https://github.com/modflowpy/flopy/blob/develop/flopy/mf6/mfsimbase.py) (MF6 sim), [`autotest`](https://github.com/modflowpy/flopy/tree/develop/autotest) (CI & tests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_user["User & docs"]
  node_node_readme["README<br/>project entry<br/>[README.md]"]
  node_node_examples["Examples"]
  node_node_docs["Docs notebooks<br/>tutorial surface<br/>[Notebooks]"]
end

subgraph group_grp_core["Core API"]
  node_node_flopy_init["Public API<br/>package facade<br/>[__init__.py]"]
  node_node_mbase["Model base<br/>core container<br/>[mbase.py]"]
  node_node_pakbase["Package base<br/>core package<br/>[pakbase.py]"]
  node_node_datbase["Data base<br/>core data<br/>[datbase.py]"]
end

subgraph group_grp_mf6["MODFLOW 6"]
  node_node_mf6_sim["MF6 sim<br/>simulation layer<br/>[mfsimbase.py]"]
  node_node_mf6_model["MF6 model<br/>model layer<br/>[mfmodel.py]"]
  node_node_mf6_package["MF6 package<br/>package layer<br/>[mfpackage.py]"]
  node_node_mf6_data["MF6 data<br/>typed data"]
  node_node_mf6_coords["MF6 coords<br/>coord metadata"]
  node_node_codegen["Codegen<br/>generated API"]
end

subgraph group_grp_legacy["Legacy models"]
  node_node_modflow["MODFLOW 2005<br/>legacy flow"]
  node_node_mfusg["MODFLOW-USG<br/>unstructured flow"]
  node_node_mt3d["MT3D<br/>transport"]
  node_node_seawat["SEAWAT<br/>coupled flow-transport"]
  node_node_modpath["MODPATH<br/>particle tracking"]
end

subgraph group_grp_shared["Shared utilities"]
  node_node_discretization["Grids<br/>geometry layer"]
  node_node_utils["Utils<br/>parsing & geospatial"]
end

subgraph group_grp_out["Output & analysis"]
  node_node_post["Postprocess<br/>analysis helpers<br/>[postprocessing.py]"]
  node_node_export["Export<br/>interop writers"]
  node_node_plot["Plot<br/>visualization"]
  node_node_pest["PEST<br/>calibration prep"]
end

subgraph group_grp_tooling["Tooling"]
  node_node_ci["CI & tests<br/>validation"]
  node_node_build["Build tools<br/>tooling<br/>[pyproject.toml]"]
end

node_node_ext(("External solvers<br/>binaries"))

node_node_readme -->|"introduces"| node_node_flopy_init
node_node_docs -->|"uses"| node_node_flopy_init
node_node_examples -->|"demonstrates"| node_node_modflow
node_node_examples -->|"demonstrates"| node_node_mf6_sim
node_node_flopy_init -->|"exports"| node_node_mbase
node_node_flopy_init -->|"exports"| node_node_discretization
node_node_mbase -->|"depends on"| node_node_pakbase
node_node_pakbase -->|"depends on"| node_node_datbase
node_node_mf6_sim -->|"contains"| node_node_mf6_model
node_node_mf6_model -->|"contains"| node_node_mf6_package
node_node_mf6_package -->|"uses"| node_node_mf6_data
node_node_mf6_sim -->|"uses"| node_node_mf6_coords
node_node_codegen -.->|"generates"| node_node_mf6_package
node_node_codegen -.->|"generates"| node_node_mf6_sim
node_node_modflow -->|"extends"| node_node_mbase
node_node_mfusg -->|"extends"| node_node_mbase
node_node_mt3d -->|"extends"| node_node_mbase
node_node_seawat -->|"extends"| node_node_mbase
node_node_modpath -->|"extends"| node_node_mbase
node_node_discretization -->|"feeds"| node_node_utils
node_node_utils -->|"feeds"| node_node_post
node_node_utils -->|"feeds"| node_node_export
node_node_utils -->|"feeds"| node_node_plot
node_node_mf6_data -->|"uses"| node_node_utils
node_node_post -->|"reads"| node_node_utils
node_node_export -->|"uses"| node_node_discretization
node_node_plot -->|"uses"| node_node_discretization
node_node_pest -->|"uses"| node_node_utils
node_node_mf6_sim -->|"runs"| node_node_ext
node_node_modflow -->|"runs"| node_node_ext
node_node_mfusg -->|"runs"| node_node_ext
node_node_mt3d -->|"runs"| node_node_ext
node_node_seawat -->|"runs"| node_node_ext
node_node_modpath -->|"runs"| node_node_ext
node_node_ci -->|"validates"| node_node_examples
node_node_ci -->|"validates"| node_node_utils
node_node_ci -->|"validates"| node_node_mf6_sim
node_node_build -->|"drives"| node_node_codegen
node_node_build -->|"drives"| node_node_ci

click node_node_readme "https://github.com/modflowpy/flopy/blob/develop/README.md"
click node_node_examples "https://github.com/modflowpy/flopy/tree/develop/examples"
click node_node_docs "https://github.com/modflowpy/flopy/blob/develop/.docs/Notebooks"
click node_node_flopy_init "https://github.com/modflowpy/flopy/blob/develop/flopy/__init__.py"
click node_node_mbase "https://github.com/modflowpy/flopy/blob/develop/flopy/mbase.py"
click node_node_pakbase "https://github.com/modflowpy/flopy/blob/develop/flopy/pakbase.py"
click node_node_datbase "https://github.com/modflowpy/flopy/blob/develop/flopy/datbase.py"
click node_node_mf6_sim "https://github.com/modflowpy/flopy/blob/develop/flopy/mf6/mfsimbase.py"
click node_node_mf6_model "https://github.com/modflowpy/flopy/blob/develop/flopy/mf6/mfmodel.py"
click node_node_mf6_package "https://github.com/modflowpy/flopy/blob/develop/flopy/mf6/mfpackage.py"
click node_node_mf6_data "https://github.com/modflowpy/flopy/tree/develop/flopy/mf6/data"
click node_node_mf6_coords "https://github.com/modflowpy/flopy/tree/develop/flopy/mf6/coordinates"
click node_node_codegen "https://github.com/modflowpy/flopy/tree/develop/flopy/mf6/utils/codegen"
click node_node_modflow "https://github.com/modflowpy/flopy/tree/develop/flopy/modflow"
click node_node_mfusg "https://github.com/modflowpy/flopy/tree/develop/flopy/mfusg"
click node_node_mt3d "https://github.com/modflowpy/flopy/tree/develop/flopy/mt3d"
click node_node_seawat "https://github.com/modflowpy/flopy/tree/develop/flopy/seawat"
click node_node_modpath "https://github.com/modflowpy/flopy/tree/develop/flopy/modpath"
click node_node_discretization "https://github.com/modflowpy/flopy/tree/develop/flopy/discretization"
click node_node_utils "https://github.com/modflowpy/flopy/tree/develop/flopy/utils"
click node_node_post "https://github.com/modflowpy/flopy/blob/develop/flopy/utils/postprocessing.py"
click node_node_export "https://github.com/modflowpy/flopy/tree/develop/flopy/export"
click node_node_plot "https://github.com/modflowpy/flopy/tree/develop/flopy/plot"
click node_node_pest "https://github.com/modflowpy/flopy/tree/develop/flopy/pest"
click node_node_ci "https://github.com/modflowpy/flopy/tree/develop/autotest"
click node_node_build "https://github.com/modflowpy/flopy/blob/develop/pyproject.toml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_readme,node_node_examples,node_node_docs,node_node_ci,node_node_build toneBlue
class node_node_flopy_init,node_node_mbase,node_node_pakbase,node_node_datbase toneAmber
class node_node_mf6_sim,node_node_mf6_model,node_node_mf6_package,node_node_mf6_data,node_node_mf6_coords,node_node_codegen toneMint
class node_node_modflow,node_node_mfusg,node_node_mt3d,node_node_seawat,node_node_modpath toneRose
class node_node_discretization,node_node_utils toneIndigo
class node_node_post,node_node_export,node_node_plot,node_node_pest toneTeal
class node_node_ext toneNeutral
```

## Components

### User & docs

Entry points, tutorials, and example workflows that show how FloPy is used.

- [README](https://github.com/modflowpy/flopy/blob/develop/README.md): project entry · High-level project overview and usage boundary. · `README.md`
- [Examples](https://github.com/modflowpy/flopy/tree/develop/examples): usage examples · Curated model setups and reference data across supported workflows. · `examples`
- [Docs notebooks](https://github.com/modflowpy/flopy/blob/develop/.docs/Notebooks): tutorial surface · Notebook-style tutorials and rendered docs for common FloPy compositions. · `.docs/Notebooks`

### Core API

Shared model/package abstractions used across model families.

- [Public API](https://github.com/modflowpy/flopy/blob/develop/flopy/__init__.py): package facade · Top-level imports and public surface exposed to users. · `flopy/__init__.py`
- [Model base](https://github.com/modflowpy/flopy/blob/develop/flopy/mbase.py): core container · Shared model lifecycle, writing, loading, and bookkeeping behavior. · `flopy/mbase.py`
- [Package base](https://github.com/modflowpy/flopy/blob/develop/flopy/pakbase.py): core package · Common package-level abstractions and file handling. · `flopy/pakbase.py`
- [Data base](https://github.com/modflowpy/flopy/blob/develop/flopy/datbase.py): core data · 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](https://github.com/modflowpy/flopy/blob/develop/flopy/mf6/mfsimbase.py): simulation layer · Simulation orchestration and top-level MF6 entry points. · `flopy/mf6/mfsimbase.py`
- [MF6 model](https://github.com/modflowpy/flopy/blob/develop/flopy/mf6/mfmodel.py): model layer · Model containers and coordination within a simulation. · `flopy/mf6/mfmodel.py`
- [MF6 package](https://github.com/modflowpy/flopy/blob/develop/flopy/mf6/mfpackage.py): package layer · MF6 package behavior shared by generated package classes. · `flopy/mf6/mfpackage.py`
- [MF6 data](https://github.com/modflowpy/flopy/tree/develop/flopy/mf6/data): typed data · MF6-specific array, list, scalar, and storage objects. · `flopy/mf6/data`
- [MF6 coords](https://github.com/modflowpy/flopy/tree/develop/flopy/mf6/coordinates): coord metadata · Simulation time and model/grid dimension metadata. · `flopy/mf6/coordinates`
- [Codegen](https://github.com/modflowpy/flopy/tree/develop/flopy/mf6/utils/codegen): generated API · 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](https://github.com/modflowpy/flopy/tree/develop/flopy/modflow): legacy flow · Structured-grid legacy MODFLOW packages and solver wiring. · `flopy/modflow`
- [MODFLOW-USG](https://github.com/modflowpy/flopy/tree/develop/flopy/mfusg): unstructured flow · Unstructured-grid MODFLOW-USG and conduit/lake variants. · `flopy/mfusg`
- [MT3D](https://github.com/modflowpy/flopy/tree/develop/flopy/mt3d): transport · Transport packages and coupling for MT3DMS/MT3D-USGS. · `flopy/mt3d`
- [SEAWAT](https://github.com/modflowpy/flopy/tree/develop/flopy/seawat): coupled flow-transport · Coupled variable-density flow and transport workflows. · `flopy/seawat`
- [MODPATH](https://github.com/modflowpy/flopy/tree/develop/flopy/modpath): particle tracking · Particle tracking simulations and particle data/group definitions. · `flopy/modpath`

### Shared utilities

Grids, parsing, geospatial helpers, post-processing, and interoperability support.

- [Grids](https://github.com/modflowpy/flopy/tree/develop/flopy/discretization): geometry layer · Structured, vertex, and unstructured grid representations plus model time. · `flopy/discretization`
- [Utils](https://github.com/modflowpy/flopy/tree/develop/flopy/utils): parsing & geospatial · File readers, binary/list parsers, grid intersection, geometry, and helper utilities. · `flopy/utils`

### Output & analysis

Readers and transformations that turn solver outputs into analysis-ready data.

- [Postprocess](https://github.com/modflowpy/flopy/blob/develop/flopy/utils/postprocessing.py): analysis helpers · Derived-field helpers for discharge, budgets, and other analysis-ready outputs. · `flopy/utils/postprocessing.py`
- [Export](https://github.com/modflowpy/flopy/tree/develop/flopy/export): interop writers · NetCDF, VTK, shapefile, units, and metadata writers. · `flopy/export`
- [Plot](https://github.com/modflowpy/flopy/tree/develop/flopy/plot): visualization · Map-view and cross-section plotting on matplotlib. · `flopy/plot`
- [PEST](https://github.com/modflowpy/flopy/tree/develop/flopy/pest): calibration prep · Template and parameter writers for PEST workflows. · `flopy/pest`

### Tooling

Build, CI, code generation, documentation, and release automation.

- [CI & tests](https://github.com/modflowpy/flopy/tree/develop/autotest): validation · Regression, snapshot, and example-based validation against solver outputs. · `autotest`
- [Build tools](https://github.com/modflowpy/flopy/blob/develop/pyproject.toml): tooling · Packaging, release, docs, benchmark, and maintenance automation. · `pyproject.toml`

### Other components

- **External solvers**: binaries · MODFLOW-family executables that FloPy writes inputs for and runs externally.

## Connections

- 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.
