MODFLOW, ParFlow, ATS and PFLOTRAN

The hydrological end of the connection. Every other method in this section measures the subsurface; MODFLOW, ParFlow, ATS and PFLOTRAN outputs can be compared with those measurements. Parameter write-back supports MODFLOW and ParFlow.

What you can do

• Read water content, saturation and porosity out of a supported hydrological run, for one timestep or a whole series.

• Carry those states through petrophysics into a geophysical property, then forward model the survey that property would produce.

• Map an interpreted geophysical quantity back onto the hydrological grid.

• Write MODFLOW 6 or ParFlow inputs carrying that update, as a copy. Neither writer modifies the source model and neither runs the solver.

• Compare hydrological responses with and without geophysically informed structure.

Required inputs

ATS and PFLOTRAN snapshot readers are available through the Python API. See ATS and PFLOTRAN outputs to geophysics for output formats, time units, volumetric water content and mapping cells to a geophysical mesh.

Model	What is read	Notes
MODFLOW 6	UZF water content, porosity	MODFLOWWaterContent takes the simulation workspace and a 2D idomain; nonzero cells receive consecutive UZF indices in row-major order. FloPy reads and writes the simulation.
ParFlow	Saturation, porosity, domain mask	ParflowSaturation takes the run directory and the run name, and discovers the available timesteps itself.
ATS	Visualization HDF5 scalar cell fields, and the *_mesh.h5 beside them	Liquid saturation, porosity, derived volumetric liquid water content; the cell centres for spatial interpolation come from ATS’s mesh file.
PFLOTRAN	Snapshot HDF5 time groups, single or multiple files	Preserves native array axes and time units; the cell centres come from the run’s Coordinates (structured) or Domain (unstructured) group. Select a run name or explicit filename.

For writing, you supply the update as an array matching the model grid exactly, in the model’s own length and time units.

Typical outputs

Going out of the model: arrays of water content, saturation or porosity on the model grid, ready for the petrophysical conversion.

Going back in: a copy of the simulation with the mapped fields replaced. write_modflow6_inputs accepts hydraulic_conductivity, vertical_conductivity, specific_storage, specific_yield, initial_head and bottom_elevation; packages, stress periods and boundary conditions are left as configured.

Choose a workflow

Your goal	Start here
Understand how the two directions connect	Connecting geophysical data and hydrological models
Load model outputs and inspect them	Ex. Loading and Processing Hydrological Model Outputs
Predict an ERT survey from a model state	Hydrology to ERT
Predict an EM sounding from a model state	Hydrology to EM (TDEM and FDEM)
Compare several methods over one profile	Ex. Hydrology to Multi-Geophysics Responses
Write an interpreted result back into the model	Write updates back to hydrological models
Run MODFLOW with geophysically informed structure	Run MODFLOW with geophysical structure

Desktop support

Desktop Studio carries the hydrological side in its project tree: Hydro → Geophysics for the forward direction - a survey line drawn on the model’s map, the section under it, and the simulated surveys - and ERT → Water Content for the interpretation that feeds back.

Python examples

• Ex. Loading and Processing Hydrological Model Outputs: read both model families and plot what came out.

• Ex. ERT Workflow: From Hydrological Models to ERT responses and Inversion: the full hydrology-to-ERT chain.

• Ex. Geophysical structure → MODFLOW → hydrological response: run and compare hydrological responses with a uniform and an interpreted interface. This one actually runs the solver.

Reading a timestep out of each model family:

import numpy as np
from PyHydroGeophysX.model_output import MODFLOWWaterContent, ParflowSaturation

idomain = np.loadtxt("examples/data/modflow/id.txt")
mf = MODFLOWWaterContent(model_directory="examples/data/modflow", idomain=idomain)
water_content = mf.load_timestep(1)

pf = ParflowSaturation(model_directory="examples/data/parflow/test2", run_name="test2")
saturation = pf.load_timestep(0)

Hydro_modular then carries a state straight through to a survey response: hydro_to_ert, hydro_to_srt, hydro_to_tdem, hydro_to_fdem and hydro_to_gravity. Each needs the mesh, the profile interpolation and the petrophysical parameters alongside the model arrays, so Hydrology to ERT walks one of them end to end rather than compressing it here.

Relevant API

• model_output package for MODFLOWWaterContent, MODFLOWPorosity, ParflowSaturation and ParflowPorosity.

• Hydro_modular package for the conversions from a hydrological state to each geophysical method.

• model_input package for write_modflow6_inputs, write_parflow_inputs and the grid mapping that prepares an update.

Limitations and optional dependencies

MODFLOW support goes through FloPy and ParFlow support through pftools, both installed by the geophysics extra:

pip install "pyhydrogeophysx[geophysics]"

The ParFlow readers have a standalone PFB fallback and work without pftools. ATS and PFLOTRAN HDF5 readers require the hydrology extra (h5py), loaded only when constructing a reader:

pip install "pyhydrogeophysx[hydrology]"

These adapters provide the Python output and interpolation API. The Desktop Studio’s hydrology page, the hydro bundle and the agent workflows read MODFLOW and ParFlow only; ATS and PFLOTRAN are not available there yet. Writing inputs is not running a model: the writers produce a copy for you to run yourself, and the MODFLOW writer requires a MODFLOW 6 groundwater-flow model.