0
# FloPy
1

2
FloPy is a comprehensive Python library for groundwater modeling that provides support for MODFLOW 6, MODFLOW-2005, MODFLOW-NWT, MODFLOW-USG, and MODFLOW-2000, along with related models like MODPATH, MT3DMS, MT3D-USGS, and SEAWAT. The package enables scientists and engineers to create, run, and post-process MODFLOW-based groundwater models through a Python interface, offering tools for model construction, parameter management, input/output handling, and visualization.
3

4
## Package Information
5

6
- **Package Name**: flopy
7
- **Language**: Python
8
- **Installation**: `pip install flopy` or `conda install -c conda-forge flopy`
9
- **Requirements**: Python 3.10+, numpy >=1.20.3, matplotlib >=1.4.0, pandas >=2.0.0
10

11
## Core Imports
12

13
```python
14
import flopy
15
```
16

17
For specific model types:
18

19
```python
20
# MODFLOW 6
21
from flopy.mf6 import MFSimulation, ModflowGwf
22

23
# MODFLOW 2005
24
from flopy.modflow import Modflow
25

26
# Utilities and plotting
27
from flopy.utils import HeadFile, CellBudgetFile, ZoneBudget
28
from flopy.plot import PlotMapView
29
```
30

31
## Basic Usage
32

33
```python
34
import flopy
35
import numpy as np
36

37
# Create a simple MODFLOW 6 groundwater flow model
38
sim = flopy.mf6.MFSimulation(sim_name='example', version='mf6', exe_name='mf6')
39

40
# Add time discretization
41
tdis = flopy.mf6.ModflowTdis(sim, time_units='DAYS', nper=1, perioddata=[(1.0, 1, 1)])
42

43
# Create groundwater flow model
44
gwf = flopy.mf6.ModflowGwf(sim, modelname='gwf', save_flows=True)
45

46
# Add discretization
47
dis = flopy.mf6.ModflowGwfdis(gwf, nlay=1, nrow=10, ncol=10, delr=100.0, delc=100.0)
48

49
# Add initial conditions
50
ic = flopy.mf6.ModflowGwfic(gwf, strt=100.0)
51

52
# Add node property flow
53
npf = flopy.mf6.ModflowGwfnpf(gwf, k=1.0)
54

55
# Add constant head boundary
56
chd_period_data = {0: [[(0, 0, 0), 100.0], [(0, 9, 9), 90.0]]}
57
chd = flopy.mf6.ModflowGwfchd(gwf, stress_period_data=chd_period_data)
58

59
# Add output control
60
oc = flopy.mf6.ModflowGwfoc(gwf, head_filerecord='gwf.hds', budget_filerecord='gwf.cbc', saverecord=[('HEAD', 'ALL'), ('BUDGET', 'ALL')])
61

62
# Add solver
63
ims = flopy.mf6.ModflowIms(sim, complexity='SIMPLE')
64

65
# Write input files
66
sim.write_simulation()
67

68
# Run the model
69
success, buff = sim.run_simulation()
70
```
71

72
## Architecture
73

74
FloPy follows a modular architecture that mirrors the structure of MODFLOW models:
75

76
- **Models**: Top-level containers (MFSimulation, Modflow, Mt3dms, etc.) that manage packages and execution
77
- **Packages**: Individual model components (boundary conditions, solvers, discretization)
78
- **Grids**: Spatial discretization classes (StructuredGrid, UnstructuredGrid, VertexGrid) 
79
- **Data Arrays**: Utilities for handling model input data (Util2d, Util3d, MfList)
80
- **File I/O**: Readers and writers for model input/output files
81
- **Visualization**: Plotting tools for model grids, results, and cross-sections
82

83
This design enables flexible model construction while maintaining compatibility with MODFLOW file formats and conventions.
84

85
## Capabilities
86

87
### MODFLOW 6 Models
88

89
Complete support for MODFLOW 6 including groundwater flow (GWF), transport (GWT), energy transport (GWE), and particle tracking (PRT) models with all standard packages and advanced features.
90

91
```python { .api }
92
class MFSimulation:
93
    """MODFLOW 6 simulation container"""
94
    def __init__(self, sim_name: str = 'sim', version: str = 'mf6', exe_name: Union[str, PathLike] = 'mf6', sim_ws: Union[str, PathLike] = '.', verbosity_level: int = 1, write_headers: bool = True, use_pandas: bool = True, lazy_io: bool = False, continue_=None, nocheck=None, memory_print_option=None, profile_option=None, maxerrors=None, print_input=None, hpc_data=None): ...
95
    def write_simulation(self, silent: bool = False): ...
96
    def run_simulation(self, silent: bool = False, pause: bool = False, report: bool = False): ...
97

98
class ModflowGwf:
99
    """MODFLOW 6 groundwater flow model"""
100
    def __init__(self, simulation, modelname: str = 'model', model_nam_file=None, version: str = 'mf6', exe_name: str = 'mf6', model_rel_path: str = '.', list=None, print_input=None, print_flows=None, save_flows=None, newtonoptions=None, nc_mesh2d_filerecord=None, nc_structured_filerecord=None, nc_filerecord=None, **kwargs): ...
101

102
class ModflowGwt:
103
    """MODFLOW 6 groundwater transport model"""
104
    def __init__(self, simulation, modelname: str = 'model', model_nam_file=None, version: str = 'mf6', exe_name: str = 'mf6', model_rel_path: str = '.', list=None, print_input=None, print_flows=None, save_flows=None, nc_mesh2d_filerecord=None, nc_structured_filerecord=None, nc_filerecord=None, **kwargs): ...
105
```
106

107
[MODFLOW 6](./modflow6.md)
108

109
### MODFLOW 2005 Models
110

111
Support for MODFLOW-2005, MODFLOW-NWT, MODFLOW-USG, and MODFLOW-2000 with comprehensive package coverage including flow, boundary conditions, and solvers.
112

113
```python { .api }
114
class Modflow:
115
    """MODFLOW 2005 model"""
116
    def __init__(self, modelname: str = 'modflowtest', namefile_ext: str = 'nam', version: str = 'mf2005', exe_name: str = 'mf2005', **kwargs): ...
117
    def write_input(self, SelPackList: list = None, check: bool = True): ...
118
    def run_model(self, silent: bool = False, pause: bool = False, report: bool = False): ...
119
```
120

121
[MODFLOW 2005](./modflow2005.md)
122

123
### Grid and Discretization
124

125
Grid classes for structured, unstructured, and vertex-based discretizations with coordinate transformations, intersection utilities, and export capabilities.
126

127
```python { .api }
128
class StructuredGrid:
129
    """Regular rectangular grid discretization"""
130
    def __init__(self, delc, delr, top=None, botm=None, idomain=None, **kwargs): ...
131
    @property
132
    def xcellcenters(self): ...
133
    @property
134
    def ycellcenters(self): ...
135
    def intersect(self, x, y, z=None): ...
136

137
class UnstructuredGrid:
138
    """Flexible unstructured mesh discretization"""
139
    def __init__(self, vertices, iverts, **kwargs): ...
140

141
class ModelTime:
142
    """Temporal discretization management"""
143
    def __init__(self, perioddata, time_units='days', **kwargs): ...
144
```
145

146
[Grid and Discretization](./discretization.md)
147

148
### Transport Modeling
149

150
MT3DMS and MT3D-USGS transport models with advection, dispersion, reactions, and specialized packages for complex transport scenarios.
151

152
```python { .api }
153
class Mt3dms:
154
    """MT3DMS transport model"""
155
    def __init__(self, modelname: str = 'mt3dtest', namefile_ext: str = 'nam', ftlfilename: str = 'mt3d_link.ftl', **kwargs): ...
156

157
class Mt3dBtn:
158
    """Basic transport package"""
159
    def __init__(self, model, nlay=1, nrow=2, ncol=2, **kwargs): ...
160
```
161

162
[Transport Modeling](./transport.md)
163

164
### Particle Tracking
165

166
MODPATH 6 and 7 models for particle tracking analysis with flexible particle placement, endpoint analysis, and pathline tracking.
167

168
```python { .api }
169
class Modpath7:
170
    """MODPATH 7 particle tracking model"""
171
    def __init__(self, modelname: str = 'modpathtest', flowmodel=None, **kwargs): ...
172

173
class ParticleData:
174
    """Base particle data class"""
175
    def __init__(self, partlocs, **kwargs): ...
176

177
class ParticleGroup:
178
    """Particle group container"""
179
    def __init__(self, particlegroupname: str, particledata, **kwargs): ...
180
```
181

182
[Particle Tracking](./particle-tracking.md)
183

184
### File I/O and Post-processing
185

186
Comprehensive file readers for MODFLOW output files, budget analysis, observation processing, and result visualization.
187

188
```python { .api }
189
class HeadFile:
190
    """Head file reader"""
191
    def __init__(self, filename, text='head', **kwargs): ...
192
    def get_data(self, kstpkper=None, idx=None, totim=None): ...
193

194
class CellBudgetFile:
195
    """Cell budget file reader"""
196
    def __init__(self, filename, **kwargs): ...
197
    def get_data(self, kstpkper=None, idx=None, totim=None, text=None): ...
198

199
class ZoneBudget:
200
    """Zone budget analysis"""
201
    def __init__(self, cbc_file, z, kstpkper=None, **kwargs): ...
202
```
203

204
[File I/O and Post-processing](./file-io.md)
205

206
### Visualization and Plotting
207

208
Plotting utilities for map views, cross-sections, and 3D visualization with matplotlib integration and export capabilities.
209

210
```python { .api }
211
class PlotMapView:
212
    """Map view plotting"""
213
    def __init__(self, model=None, ax=None, layer=0, **kwargs): ...
214
    def plot_grid(self, **kwargs): ...
215
    def plot_array(self, a, **kwargs): ...
216
    def contour_array(self, a, **kwargs): ...
217

218
class PlotCrossSection:
219
    """Cross-section plotting"""
220
    def __init__(self, model=None, line=None, ax=None, **kwargs): ...
221
```
222

223
[Visualization and Plotting](./plotting.md)
224

225
### Data Export
226

227
Export model grids, arrays, and results to various formats including NetCDF, VTK, shapefiles, and other GIS-compatible formats.
228

229
```python { .api }
230
class NetCdf:
231
    """NetCDF export functionality"""
232
    def __init__(self, output_filename, model, **kwargs): ...
233
    def write(self): ...
234

235
class Vtk:
236
    """VTK format export"""
237
    def __init__(self, model, **kwargs): ...
238
    def add_array(self, array, name, **kwargs): ...
239
```
240

241
[Data Export](./export.md)
242

243
### Utilities and Helpers
244

245
General utilities for model checking, parameter estimation, coordinate transformations, and integration with external tools.
246

247
```python { .api }
248
def run_model(namefile, exe_name, **kwargs):
249
    """Execute model runs with subprocess management"""
250
    ...
251

252
def which(program):
253
    """Find executable paths"""
254
    ...
255

256
def check(model, **kwargs):
257
    """Model checking function"""
258
    ...
259
```
260

261
[Utilities and Helpers](./utilities.md)
262

263
## Common Types
264

265
```python { .api }
266
# Stress period data format
267
StressPeriodData = dict[int, list[list]]
268

269
# Array data types
270
ArrayData = Union[int, float, np.ndarray, list]
271

272
# File path types
273
FilePath = Union[str, os.PathLike]
274

275
# Model coordinate types
276
Coordinates = tuple[float, float] | list[float]
277
```