.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "api/gallery/hydrology/plot_17_beven_kirkby_topmodel.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_17_beven_kirkby_topmodel.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_17_beven_kirkby_topmodel.py:


Beven and Kirkby's TOPMODEL (1979)
==================================

Keith Beven and Mike Kirkby argued that runoff comes mostly from saturated
ground that expands and contracts with the wetness of a catchment, and that
where it forms is predictable from the topography. Their topographic index
``ln(a / tan(beta))`` is high where a large area drains through a gentle
slope, at the foot of hillslopes and in hollows. One catchment-mean deficit
then sets the local deficit everywhere, the saturated area and an
exponentially receding baseflow.

.. GENERATED FROM PYTHON SOURCE LINES 13-44



.. image-sg:: /api/gallery/hydrology/images/sphx_glr_plot_17_beven_kirkby_topmodel_001.png
   :alt: Saturated at a 50 mm mean deficit (inside line), Saturated area and baseflow
   :srcset: /api/gallery/hydrology/images/sphx_glr_plot_17_beven_kirkby_topmodel_001.png
   :class: sphx-glr-single-img





.. code-block:: Python


    import matplotlib.pyplot as plt
    import numpy as np

    from earthsciencekit.hydrology import topmodel_baseflow, topmodel_deficit, topographic_index

    x = np.linspace(1, 400, 400)  # m from the divide along a hillslope
    y = np.linspace(-1, 1, 81)[:, None]  # across the hillslope; convergent toward y = 0
    area = x * (1 + 2 * np.exp(-((y / 0.3) ** 2)) * x / 400)  # upslope area per unit contour width [m]
    slope = np.arctan(0.02 + 0.25 * np.sin(np.pi * x / 400) ** 2 + 0.01 * np.abs(y))
    index = topographic_index(area, slope)
    mean_index, scaling = index.mean(), 0.03
    mean_deficit = np.linspace(0, 0.15, 61)
    saturated = [np.mean(topmodel_deficit(d, index, mean_index, scaling) <= 0) for d in mean_deficit]
    assert np.all(np.diff(saturated) <= 0) and saturated[0] > 0.3 and saturated[-1] == 0
    baseflow = topmodel_baseflow(5e-3, mean_index, mean_deficit, scaling)
    assert np.isclose(baseflow[20] / baseflow[0], np.exp(-mean_deficit[20] / scaling))

    fig, (left, right) = plt.subplots(1, 2, figsize=(10, 4))
    image = left.pcolormesh(x, y.ravel(), index, shading="auto", cmap="Blues")
    left.contour(x, y.ravel(), topmodel_deficit(0.05, index, mean_index, scaling), levels=[0], colors="k")
    fig.colorbar(image, ax=left, label="ln(a / tan(beta))")
    left.set(xlabel="distance from the divide [m]", ylabel="across slope", title="Saturated at a 50 mm mean deficit (inside line)")
    right.plot(mean_deficit * 1e3, saturated, label="saturated fraction")
    right.set(xlabel="catchment-mean deficit [mm]", ylabel="saturated fraction", title="Saturated area and baseflow")
    twin = right.twinx()
    twin.semilogy(mean_deficit * 1e3, baseflow * 3.6e6, "C1--", label="baseflow")
    twin.set_ylabel("baseflow [mm/h]")
    fig.tight_layout()

    plt.show()


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

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


.. _sphx_glr_download_api_gallery_hydrology_plot_17_beven_kirkby_topmodel.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_17_beven_kirkby_topmodel.ipynb
        :alt: Launch JupyterLite
        :width: 150 px

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

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

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

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

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

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


.. only:: html

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

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