:orphan:

User Guide
==========

.. toctree::
   :maxdepth: 1
   :hidden:

The imod Python package builds on top of popular Python packages like
`xarray`_, `pandas`_, and `geopandas`_ to prepare and analyze MODFLOW models.
This user guide will introduce these packages and their data structures, and
explains how they relate to the many forms of data we come across while
modeling groundwater flow.

This user guide is not an exhaustive explanation of these packages and their
data structures. Rather this guide intends to introduce the packages, explain
their roles, and how they fit together to help with groundwater modeling.

The imod package provides a link between these packages and groundwater
modeling.Pandas, geopandas, and xarray already provide a great deal of
capabilities and features; imod expands these capabilities when they are
(i)MODFLOW specific or when existing capabilities are too limited or too slow.

Specifically:

* input and output to (i)MODFLOW specific file formats.
* data preparation, mostly "GIS-like" routines: raster to vector and vice versa,
  changing cell sizes, data selection, gapfilling, etc.
* overview statistics, water balance, etc,
* visualization of groundwater heads, cross sections, 3D animations, etc.

Nearly every function in imod consumes and produces xarray, pandas, or
geopandas data structures. Therefore, this guide first introduces these data
structures. Secondly, it will demonstrate how a modeling workflow is set up. 

.. toctree::
   :titlesonly:
   :hidden:
   
.. _xarray: http://xarray.pydata.org
.. _pandas: http://pandas.pydata.org
.. _geopandas: http://geopandas.org



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Geospatial data primarily comes in two forms: raster data and vector data. This guide focuses on the first.">

.. only:: html

  .. image:: /user-guide/images/thumb/sphx_glr_01-raster-data_thumb.png
    :alt:

  :ref:`sphx_glr_user-guide_01-raster-data.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Raster data and xarray</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Geospatial data primarily comes in two forms: raster data and vector data. This guide focuses on the latter.">

.. only:: html

  .. image:: /user-guide/images/thumb/sphx_glr_02-vector-data_thumb.png
    :alt:

  :ref:`sphx_glr_user-guide_02-vector-data.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Vector data and Geopandas</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Handling time series is major part of geohydrology and groundwater modeling. Time series data come in more than one form:">

.. only:: html

  .. image:: /user-guide/images/thumb/sphx_glr_03-timeseries-data_thumb.png
    :alt:

  :ref:`sphx_glr_user-guide_03-timeseries-data.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Time series data and Pandas</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="MODFLOW6 supports unstructured grids. Unlike raster data, the connectivity of unstructured grids is irregular. This means that the number of neighboring cells is not constant; for structured grids, every cell has 4 neighbors (in 2D), or 6 neighbors (in 3D).">

.. only:: html

  .. image:: /user-guide/images/thumb/sphx_glr_05-unstructured-grids_thumb.png
    :alt:

  :ref:`sphx_glr_user-guide_05-unstructured-grids.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Unstructured Grids</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="A powerful feature of xarray is `lazy evaluation`_. Lazy evaluation means that expressions are delayed until the results are needed. In a nutshell, lazy evaluation has the following advantages for us:">

.. only:: html

  .. image:: /user-guide/images/thumb/sphx_glr_06-lazy-evaluation_thumb.png
    :alt:

  :ref:`sphx_glr_user-guide_06-lazy-evaluation.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Lazy evaluation</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="iMOD Python provides nice functionality to discretize your models into stress periods, depending on the timesteps you assigned your boundary conditions. This functionality is activated with the create_time_discretization() method.">

.. only:: html

  .. image:: /user-guide/images/thumb/sphx_glr_07-time-discretization_thumb.png
    :alt:

  :ref:`sphx_glr_user-guide_07-time-discretization.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Model time discretization</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Most MF6 packages have spatial data arrays as input. These arrays are discrete: they are defined over the simulation grid and contain values associated to each cell.">

.. only:: html

  .. image:: /user-guide/images/thumb/sphx_glr_08-regridding_thumb.png
    :alt:

  :ref:`sphx_glr_user-guide_08-regridding.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Regridding</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="iMOD Python has multiple features to help you define the topsystem of the groundwater system. With &quot;topsystem&quot; we mean all forcings which act on the top of the groundwater system. These are usually either meteorological (precipitation &amp; evapotranspiration) or hydrological (rivers, ditches, lakes, sea) in nature. In MODFLOW6 these are usually simulated with the DRN, RIV, GHB, and RCH package. This data is usually provided as planar grids (x, y) without any vertical dimension. This user guide will show you how to allocate these forcings across model layers to grid cells and how to distribute conductances for Robin-like boundary conditions (RIV, DRN, GHB) over model layers. We will demonstrate this with the RIV package, as this package supports all options for allocating cells and distributing conductances. A subset of options are available for the DRN, GHB, and RCH packages.">

.. only:: html

  .. image:: /user-guide/images/thumb/sphx_glr_09-topsystem_thumb.png
    :alt:

  :ref:`sphx_glr_user-guide_09-topsystem.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Topsystem: from 2D map to 3D model</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="More often than not, data contained in databases is not entirely consistent, causing errors. It therefore is useful to have some utilities at hand to clean up data. We included some convenience methods to help clean up inconsistent datasets.">

.. only:: html

  .. image:: /user-guide/images/thumb/sphx_glr_10-cleanup_thumb.png
    :alt:

  :ref:`sphx_glr_user-guide_10-cleanup.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Data cleanup</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>


.. toctree::
   :hidden:

   /user-guide/01-raster-data
   /user-guide/02-vector-data
   /user-guide/03-timeseries-data
   /user-guide/05-unstructured-grids
   /user-guide/06-lazy-evaluation
   /user-guide/07-time-discretization
   /user-guide/08-regridding
   /user-guide/09-topsystem
   /user-guide/10-cleanup


.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-gallery

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download all examples in Python source code: user-guide_python.zip </user-guide/user-guide_python.zip>`

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download all examples in Jupyter notebooks: user-guide_jupyter.zip </user-guide/user-guide_jupyter.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_