August 4, 2016

FloPy: A Python interface for MODFLOW that kicks tail!

Posted by tomglee

Authored by: Kevin Befus – Assistant professor, Department of Civil and Architectural Engineering at the University of Wyoming

Groundwater modeling is getting better. Models are becoming more sophisticated with simpler interfaces to add, extract, and process the data. So, at first appearances, the U.S. Geological Survey’s (USGS) recent release of a Python module named FloPy for preparing, running, and managing MODFLOW groundwater models seems to be a step backwards.

Oh, but it isn’t.


First, a couple disclaimers. Yes, at the time of writing this I work for the USGS and use this new Python module for my research. Did I have to use FloPy? No. Am I glad I did? YES! Before using FloPy, I dabbled in the various non-commercial MODFLOW interfaces but got bogged down on how many drop down menus, pop-up menus, wizards, and separate plotting programs with their own menus were needed to make a meaningful groundwater model on top of a new lexicon of variable names (IUPWCB must mean “internally unknown parameter with concentrated bacon”, right?).

FloPy made its official debut in February 2016 with a Groundwater methods report 1. Bakker et al. do an excellent job telling us why we should use FloPy. I’ll leave that to you and tell you what I think.

Here’s what is great about FloPy:

  1. FloPy is 100% MODFLOW. No tweaks to anything. You choose the executable file you want it to use or compile it yourself, and you’re off!
  2. You have the near-infinite data management, manipulation, and plotting capabilities of Python at your fingertips. Python has a lot of packages. It can be overwhelming. You can rely commercial packages like ESRI’s arcpy if you want, but there’s a list of free libraries that give you even more freedom to get the input data just right. Since I mentioned freedom, here’s the list of free libraries I find useful but it is in no way an endorsement nor exhaustive: scipy, numpy, gdal, osgeo, fiona, shapely, cartopy, pyshp, pandas, matplotlib, and let’s not forget…flopy!
  3. It’s easy to duplicate and alter an existing model. Once you have your script perfect for running a particular groundwater model, you can take pieces of it to make a slightly altered version, or you can pop it in a loop that runs through your uncertain inputs for sensitivity testing. Change your grid with the flip of a variable, and make sure that mesh converges!
  4. Loading other MODFLOW models works great. Say you want to run someone else’s model with slightly different recharge, but their recharge is variable in space. Since FloPy incorporates numpy’s grid/matrix handling capabilities, you can change individual entries with row-column selections or change the whole recharge grid by multiplying it by either a single number or say a random matrix with a normal distribution and some added noise. If you just want to use their recharge data to run your own model, you can save the position coordinates (they have hopefully provided you with their coordinate system and model transformations) and recharge arrays to your very favorite format (csv, nc, mat, tif) and load it later as a matrix to add to your model, all in a single Python script.
  5. Building off of the ability to load or create MODFLOW models, FloPy has functions for plotting 2D map or cross-section views of the model discretization, boundary conditions, and results. Shapefiles can be included in these plots if they are in the same coordinate system as the model or extracted from the model (ever want a polygon feature of every model cell with attributes for every property of that cell?). I do my own shapefile manipulations in Python, but FloPy has some great plotting tools built in.
  6. You already have the data in Python. See what adding a low permeability layer does to spring discharge. Then, with the model made, you have to make sense of it. Maybe develop some interesting spatial or time series analyses. Enter Python. Plotting with matplotlib also makes beautiful, journal article-worthy figures…with enough sweat and tears from your end (not as many as you may think). Yes, this is a repeat of 2), but, seriously, it’s in PYTHON!
  7. FloPy is totally free. Python is free. Tons of science-oriented libraries in Python are free.


Here’s a flashy example.  It is straightforward and only takes one script to create a SEAWAT model from scratch and plot the 2D steady state salinity distribution and flow vectors for a simple Henry 2 problem based on a slightly edited FloPy example script.  There are more than a dozen example scripts available on the FloPy site as well as a very cool capture ratio script provided in the methods report 1.

For the groundwater educators out there, a FloPy groundwater model script can be paired with homework questions that get students testing how changing hydraulic conductivity in certain parts of the model changes the water table configuration. Or maybe a new well needs to be drilled on a plot of land near a spring… The scenarios are endless. Students can develop a fundamental understanding of groundwater flow while getting experience with both groundwater modeling and computer programming. Win, win, and win.

Essentially all of the standard MODFLOW packages are operational in FloPy, and there are varying levels of support for some of the specialized MODFLOW compilations and processing tools (e.g., MODFLOW-USG, MODFLOW-NWT, MT3DMS, SEAWAT, PEST, and MODPATH). PEST and MODPATH are currently not executable with FloPy, but these features will probably be added in a future release (I have made my own klugy modules for running ZoneBudget and MODPATH that interface reasonably well with the rest of FloPy).

Get on your way and give FloPy a try today!


The Python package is available online at

The documentation is available online at

The USGS FloPy page is


Bakker, M., V. Post, C. D. Langevin, J. D. Hughes, J. T. White, J. J. Starn, and M. N. Fienen (2016), Scripting MODFLOW Model Development Using Python and FloPy, Groundwater, doi:10.1111/gwat.12413.

Henry, H.R., 1964. Effects of dispersion on salt encroachment in coastal aquifers. In: Cooper, H.H. (Ed.), Sea Water in Coastal Aquifers: U.S. Geological Survey Water- Supply Paper 1613-C p. C71–C84.

About the author:

Kevin Befus is a groundwater hydrologist with geology and geophysics experience — examining geological, biological, and chemical processes, especially considering their connections to water across scales.