.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "api/gallery/hydrology/plot_08_richards_equation.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_api_gallery_hydrology_plot_08_richards_equation.py>`
        to download the full example code or to run this example in your browser via JupyterLite.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_api_gallery_hydrology_plot_08_richards_equation.py:


Richards's equation (1931)
==========================

Lorenzo Richards extended Darcy's law to unsaturated soil, where the
conductivity depends on the capillary suction, and combined it with
conservation of water into the equation that bears his name. In steady flow
the flux is the same at every height, and for Gardner's exponential
conductivity the suction profile above a water table has a closed form:
hydrostatic without flow, a unit-gradient tail under infiltration, and a limit
height above which evaporation cannot be supplied from below.

.. GENERATED FROM PYTHON SOURCE LINES 13-34



.. image-sg:: /api/gallery/hydrology/images/sphx_glr_plot_08_richards_equation_001.png
   :alt: Richards: steady profiles in a Gardner soil
   :srcset: /api/gallery/hydrology/images/sphx_glr_plot_08_richards_equation_001.png
   :class: sphx-glr-single-img





.. code-block:: Python


    import matplotlib.pyplot as plt
    import numpy as np

    from earthsciencekit.hydrology import gardner_conductivity, richards_steady_head, unsaturated_darcy_flux

    conductivity, alpha = 1e-5, 4.0  # m/s and 1/m
    height = np.linspace(0, 1.5, 3001)
    fig, ax = plt.subplots()
    for flux, label in [(-5e-6, "infiltration, q = -5e-6 m/s"), (0.0, "no flow"), (2e-7, "evaporation, q = 2e-7 m/s")]:
        top = height if flux <= 0 else height[height < np.log(1 + conductivity / flux) / alpha * 0.98]
        head = richards_steady_head(top, flux, conductivity, alpha)
        result = unsaturated_darcy_flux(gardner_conductivity(head, conductivity, alpha), np.gradient(head, top))
        assert np.allclose(result[1:-1], flux, atol=1e-3 * conductivity)
        ax.plot(-head, top, label=label)
    limit = np.log(1 + conductivity / 2e-7) / alpha
    ax.axhline(limit, color="0.6", ls=":", label=f"limit of capillary supply, {limit:.2f} m")
    ax.set(xlabel="suction head [m]", ylabel="height above the water table [m]", title="Richards: steady profiles in a Gardner soil")
    ax.legend(fontsize="small")

    plt.show()


.. rst-class:: sphx-glr-timing

   **Total running time of the script:** (0 minutes 0.109 seconds)


.. _sphx_glr_download_api_gallery_hydrology_plot_08_richards_equation.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: lite-badge

      .. image:: images/jupyterlite_badge_logo.svg
        :target: ../../../lite/lab/index.html?path=api/gallery/hydrology/plot_08_richards_equation.ipynb
        :alt: Launch JupyterLite
        :width: 150 px

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

      :download:`Download Jupyter notebook: plot_08_richards_equation.ipynb <plot_08_richards_equation.ipynb>`

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

      :download:`Download Python source code: plot_08_richards_equation.py <plot_08_richards_equation.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: plot_08_richards_equation.zip <plot_08_richards_equation.zip>`


.. only:: html

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

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