imod

An open source project to make working with MODFLOW groundwater models in Python easier.
https://github.com/deltares/imod-python

Category: Hydrosphere
Sub Category: Freshwater and Hydrology

Keywords from Contributors

groundwater imod MODFLOW hydrology water-resources water-management modflow 3d-viewer qgis-plugin earth-science

Last synced: about 23 hours ago
JSON representation

Repository metadata

🐍🧰 Make massive MODFLOW models

• Host: GitHub
• URL: https://github.com/deltares/imod-python
• Owner: Deltares
• License: mit
• Created: 2023-12-08T13:57:59.000Z (over 1 year ago)
• Default Branch: master
• Last Pushed: 2025-05-04T13:07:54.000Z (13 days ago)
• Last Synced: 2025-05-09T20:05:26.471Z (8 days ago)
• Language: Python
• Homepage: https://deltares.github.io/imod-python/
• Size: 39.5 MB
• Stars: 24
• Watchers: 8
• Forks: 3
• Open Issues: 178
• Releases: 27
• Metadata Files:
  • Readme: README.rst
  • License: LICENSE

README.rst

          .. image:: https://dpcbuild.deltares.nl/app/rest/builds/buildType:id:iMOD6_IMODPython_Windows_Tests/statusIcon.svg
   :target: https://github.com/Deltares/imod-python/commits/master/
.. image:: https://img.shields.io/pypi/l/imod
   :target: https://choosealicense.com/licenses/mit/
.. image:: https://img.shields.io/conda/vn/conda-forge/imod.svg
   :target: https://github.com/conda-forge/imod-feedstock
.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/prefix-dev/pixi/main/assets/badge/v0.json
   :target: https://pixi.sh

The ``imod`` Python package is an open source project to make working with
MODFLOW groundwater models in Python easier. It builds on top of popular
packages such as `xarray`_, `pandas`_, `geopandas`_, `dask`_,  and `rasterio`_
to provide a versatile toolset for working with large groundwater modeling
datasets. Some of its core functionalities are:

* Preparing and modifying data from a variety of GIS, scientific, and MODFLOW
  file formats;
* Regridding, clipping, masking, and splitting MODFLOW 6 models;
* Fast writing of data to MODFLOW-based models;
* Selecting and evaluating, e.g. for time series comparison or water budgets;
* Visualizing cross sections, time series, or 3D animations.

We currently support the following MODFLOW-based kernels:

* `USGS MODFLOW 6`_, structured (DIS) and discretization by vertices (DISV)
  grids only. Not all advanced stress packages are supported (only LAK and UZF)
* `iMOD-WQ`_, which integrates SEAWAT (density-dependent
  groundwater flow) and MT3DMS (multi-species reactive transport calculations)

Development currently focuses on supporting more MODFLOW 6 functionalities.
iMOD-WQ has been sunset and will no longer be developed.

Why ``imod``?
=============

1\. Easily create grid-based model packages
-------------------------------------------

Seamlessly integrate your GIS rasters or meshes with MODFLOW 6, by using `xarray`_
and `xugrid`_ arrays, for structured and unstructured grids, respectively, to
create grid-based model packages. 

.. code-block:: python

  import imod

  # Open Geotiff with elevation data as xarray DataArray
  elevation = imod.rasterio.open("elevation.tif")

  # Create idomain grid
  layer_template = xr.DataArray([1, 1, 1], dims=('layer',), coords={'layer': [1, 2, 3]})
  idomain = layer_template * xr.ones_like(elevation).astype(int)

  # Compute bottom elevations of model layers
  layer_thickness = xr.DataArray([10.0, 20.0, 10.0], dims=('layer',), coords={'layer': [1, 2, 3]})
  bottom = elevation - layer_thickness.cumsum(dim='layer')

  # Create MODFLOW 6 DIS package
  dis_pkg = imod.mf6.StructuredDiscretization(
      idomain=idomain, top=elevation, bottom=bottom.transpose("layer", "y", "x")
  )


2\. Assign wells based on data at hand, instead of the model grid
-----------------------------------------------------------------

Assign wells based on x, y coordinates and filter screen depths, instead of
layer, row and column:

.. code-block:: python

  # Specify well locations
  x = [150_200.0, 160_800.0]
  y = [450_300.0, 460_200.0]

  # Specify well screen depths
  screen_top = [0.0, 0.0]
  screen_bottom = [-4.0, -10.0]

  # Specify flow rate, which changes over time.
  weltimes = pd.date_range("2000-01-01", "2000-01-03", freq="2D")
  well_rates_period1 = [0.5, 1.0]
  well_rates_period2 =  [2.5, 3.0]
  rate = xr.DataArray([well_rates_period1, well_rates_period2], coords={"time": weltimes}, dims=("time","index"))

  # Now construct the Well package
  wel_pkg = imod.mf6.Well(x=x, y=y, rate=rate, screen_top=screen_top, screen_bottom=screen_bottom)

iMOD Python will take care of the rest and assign the wells to the correct model
layers upon writing the model. It will furthermore distribute well rates based
on transmissivities. To verify how wells will be assigned to MODFLOW 6 cells before
writing the entire simulation, you can use the following command:

.. code-block:: python

  # Wells have been distributed across two model layers based on screen depths.
  wel_mf6_pkg = wel_pkg.to_mf6(idomain, top, bottom, k=1.0)
  print(wel_mf6_pkg["cellid"])

  # Well rates have been distributed based on screen overlap
  print(wel_mf6_pkg["rate"])


3\. Utilities to assign 2D river grids to 3D model layers
---------------------------------------------------------

A common problem in groundwater modeling is to assign 2D river or drain grids to
3D model layers. iMOD Python has utilities to do this, supporting all kinds of
different methods. Furthermore, it can help you distribute the conductance
across layers.

`See examples here `_

4\. Create stress periods based on times assigned to boundary conditions
--------------------------------------------------------------------------

MODFLOW 6 requires that all stress periods are defined in the time discretization
package. However, usually boundary conditions are defined at inconsistent
times. iMOD Python can help you to create a time discretization package that is
consistent, based on all the unique times assigned to the boundary conditions.

`See futher explanation here `_

.. code-block:: python

  # First add the packages to the simulation. NOTE: To get a functional model,
  # more packages are needed than these two.
  simulation = imod.mf6.Modflow6Simulation("example")
  simulation["gwf"] = imod.mf6.GroundwaterFlowModel()
  simulation["gwf"]["dis"] = dis_pkg
  simulation["gwf"]["wel"] = wel_pkg

  # Create a time discretization based on the times assigned to the packages.
  # Specify the end time of the simulation as one of the additional_times
  simulation.create_time_discretization(additional_times=["2000-01-07"])

  # Note that timesteps in well package are also inserted in the time
  # discretization
  print(simulation["time_discretization"].dataset)


5\. Regridding MODFLOW 6 models to different grids
--------------------------------------------------

Regrid MODFLOW 6 models to different grids, even from structured to unstructured
grids. iMOD Python takes care of properly scaling the input parameters. You can
also configure scaling methods yourself for each input parameter, for example
when you want to upscale drainage elevations with the minimum instead of the
average.

.. code-block:: python

  sim_regridded = simulation.regrid_like(new_unstructured_grid)
  # Notice that discretization has converted to VerticesDiscretization (DISV)
  print(sim_regridded["gwf"]["dis"])


`See further explanation here `_

6\. Clip MODFLOW 6 models to a bounding box
-------------------------------------------

To reduce the size of your model, you can clip it to a bounding box. This is
useful for example when you want to create a smaller model for testing purposes.

.. code-block:: python

  sim_clipped = simulation.clip_box(x_min=125_000, x_max=175_000, y_min=425_000, y_max=475_000)

You can even provide states for the model, which will be set on the model boundaries of the clipped model.

.. code-block:: python

  # Create a grid of zeros, which will be used to
  # set as heads at the boundaries of clipped parts.
  head_for_boundary = xr.zeros_like(idomain, dtype=float)
  states_for_boundary = {"gwf": head_for_boundary}

  sim_clipped = simulation.clip_box(
      x_min=125_000, x_max=175_000, y_min=425_000, y_max=475_000, states_for_boundary=states_for_boundary
  )

  # Notice that a Constant Head (CHD) package has been created for the clipped
  # model.
  print(sim_clipped["gwf"])

7\. Performant writing of MODFLOW 6 models
------------------------------------------

iMOD Python efficiently writes MODFLOW 6 models to disk, especially large models.
Tests we have conducted for the Dutch National Groundwater Model (LHM) show that
iMOD Python can write a model with 21.84 million cells 5 to 60 times faster (for
respectively 1 and 365 stress periods) than the alternative `Flopy`_ package. 
Furthermore ``imod`` can even write models that are larger than the available
memory, using `dask`_ arrays.

*NOTE:* We don't hate Flopy, nor seek its demise. iMOD developers also
contribute and aid in the development of Flopy.

8\. Import your iMOD5 models
----------------------------

Models made with `iMOD5`_ can be imported into iMOD Python, provided that they are
defined in a projectfile.

.. code-block:: python

  # Open projectfile data
  imod5_data, period_data = imod.formats.prj.open_projectfile_data("path/to/projectfile.prj")

  # Specify times for the simulation, this will be used to resample iMOD5 wells
  # to and to set the time discretization
  times = [np.datetime64("2000-01-01"), np.datetime64("2000-01-02"), np.datetime64("2000-01-03")]
  
  # Create a simulation object
  simulation = imod.mf6.Modflow6Simulation.from_imod5_data(imod5_data, period_data, times)

`See this page for a full list of supported iMO5 functionalities. `_

Why not ``imod``?
=================

1\. You want to make a small, synthetic model
---------------------------------------------

If you are not interested in deriving models from spatial data, but just want to
allocate boundary conditions based on layer, row, column numbers, or create a
model of a 2D cross-section: You are better off using `Flopy`_.

2\. Not all MODFLOW 6 features are supported
--------------------------------------------

Currently, we don't support the following MODFLOW 6 features:

- timeseries files
- DISU package
- Groundwater Energy Model (GWE)
- Streamflow routing (SFR) package (`in development `_)
- Ghost Node Correction (GNC) package
- Multi-aquifer well (MAW) package
- Water mover (MVR) package
- Particle tracking (PRT)

Most of these features can be implemented with some effort, but we have not
prioritized them yet. The exceptions are the DISU package and the timeseries
files, which would require significant work to our backend. As a result, we will
likely not support these two features in the foreseeable future. If you need any of the
other features, feel free to open an issue on our GitHub page.

Additional links
================

Documentation: https://deltares.github.io/imod-python

Source code: https://github.com/Deltares/imod-python

Issues: https://github.com/Deltares/imod-python/issues

.. _Deltares: https://www.deltares.nl
.. _dask: https://dask.org/
.. _xarray: http://xarray.pydata.org/
.. _xugrid: https://deltares.github.io/xugrid/
.. _pandas: http://pandas.pydata.org/
.. _rasterio: https://rasterio.readthedocs.io/en/latest/
.. _geopandas: http://geopandas.org/
.. _netCDF: https://www.unidata.ucar.edu/software/netcdf/
.. _USGS MODFLOW 6: https://www.usgs.gov/software/modflow-6-usgs-modular-hydrologic-model
.. _iMOD-WQ: https://oss.deltares.nl/web/imod
.. _iMOD5: https://oss.deltares.nl/web/imod
.. _Flopy: https://flopy.readthedocs.io/en/latest/

        

---

Owner metadata

• Name: Deltares
• Login: Deltares
• Email: [email protected]
• Kind: organization
• Description: Deltares is an independent institute for applied research in the field of water and subsurface.
• Website: https://www.deltares.nl/en/
• Location: Delft, The Netherlands
• Twitter: deltares
• Company:
• Icon url: https://avatars.githubusercontent.com/u/6613768?v=4
• Repositories: 74
• Last ynced at: 2023-03-03T19:30:55.614Z
• Profile URL: https://github.com/Deltares

---

GitHub Events

Total

• Create event: 235
• Release event: 7
• Issues event: 301
• Watch event: 5
• Delete event: 216
• Issue comment event: 503
• Push event: 404
• Pull request review event: 263
• Pull request review comment event: 216
• Pull request event: 292

Last Year

• Create event: 235
• Release event: 7
• Issues event: 301
• Watch event: 5
• Delete event: 216
• Issue comment event: 503
• Push event: 404
• Pull request review event: 263
• Pull request review comment event: 216
• Pull request event: 292

---

Committers metadata

Last synced: 9 days ago

Name	Email	Commits
Huite Bootsma	h****a@g****m	908
JoerivanEngelen	j****n@h****m	621
Martijn Visser	m****r@g****m	236
luit slooten	l****n@d****l	111
Sunny Titus	7****a	79
Joost Delsman	j****n@d****l	58
Deltares service account	1****t	51
jdelsman	j****n@g****m	30
Tess op den Kelder	T****r@d****l	29
Tess op den Kelder	t****r@h****m	22
Hofer-Julian	j****r@g****g	14
Joost Delsman	J****n@d****l	13
HendrikKok	5****k	11
Niels Mulder	N****r@d****l	7
Huite Bootsma	h****a@g****m	6
TobiasMulder	t****r@d****l	6
Janneke Pouwels	j****s@d****l	4
Simon Buijs	b****n@g****m	3
Marnix	1****x	2
Betsy Romero Verastegui	B****i@d****l	1
titus	t****s@T****y	1
nielsmulderdeltares	n****s@g****m	1
Vince Kaandorp	v****p@g****m	1
Thijs Hendrikx	T****x@d****l	1
Steijn van	s****1@b****l	1
Joachim Hunink	j****k@d****l	1
Jarno Verkaik	v****k	1
wpbonelli	w****i@g****m	1

Committer domains:

• deltares.nl: 10
• gnome.org: 1

---

Issue and Pull Request metadata

Last synced: 2 days ago

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/deltares/imod-python

---

---

---

Package metadata

• Total packages: 2
• Total downloads:
  • pypi: 1,432 last-month
• Total dependent packages: 4 (may contain duplicates)
• Total dependent repositories: 11 (may contain duplicates)
• Total versions: 54
• Total maintainers: 5

---

Dependencies

Score: 15.92116940296115