ewatercycle_HBV.model
=====================

.. py:module:: ewatercycle_HBV.model

.. autoapi-nested-parse::

   eWaterCycle wrapper for the HBV model.









Module Contents
---------------

.. py:function:: import_bmi()

   "Import BMI, raise useful exception if not found


.. py:data:: SUPPORTED_FORCINGS
   :value: ('HBVForcing', 'CaravanForcing', 'LumpedMakkinkForcing')


.. py:data:: HBV_PARAMS
   :value: ('Imax', 'Ce', 'Sumax', 'Beta', 'Pmax', 'Tlag', 'Kf', 'Ks', 'FM')


.. py:data:: HBV_STATES
   :value: ('Si', 'Su', 'Sf', 'Ss', 'Sp')


.. py:class:: HBVMethods

   Bases: :py:obj:`ewatercycle.base.model.eWaterCycleModel`


   The eWatercycle HBV model.


   .. py:attribute:: forcing
      :type:  ewatercycle.forcing.LumpedMakkinkForcing | ewatercycle_HBV.forcing.HBVForcing | ewatercycle.forcing.GenericLumpedForcing


   .. py:attribute:: parameter_set
      :type:  None


   .. py:property:: parameters
      :type: collections.abc.ItemsView[str, Any]


      List the (initial!) parameters for this model.

      Exposed HBV parameters:
          Imax (mm): is the maximum amount of interception, under the assumption that all interception evaporates

          Ce(−): is a parameter used to describe what factor actually evaporates from the ground
                (Unsaturated root zone: 𝑆𝑢) and is 𝐸𝐴=𝑆𝑢𝑆𝑢,𝑚𝑎𝑥×𝐶𝑒𝐸𝑝

          Sumax(mm): Is the size of the reservoir of the unsaturated root zone (𝑆𝑢)
                  i.e. the amount of water the top layer of soil can hold. This parameter is used in a few other calculations.

          Beta (−): is a factor controlling the split between fast and slow flow (overland vs groundwater).
                  Some water will be held by the soil whilst some flows over it and straight to the river.
                  𝐶𝑟=(𝑆𝑢/𝑆𝑢_𝑚𝑎𝑥)^𝛽 which is used to determine the water infiltrating: 𝑄𝑖𝑢=(1−𝐶𝑟)𝑃𝑒
                  where 𝑃𝑒 is the actual precipitation reaching the ground.
                  The rest flow into the fast reservoir 𝑄𝑢𝑓 – which is the groundwater.

          Pmax (mm): is the maximum amount of percolation which can occur from the ground
                     to the deeper groundwater flow: 𝑄𝑢𝑠=𝑃𝑚𝑎𝑥(𝑆𝑢𝑆𝑢,𝑚𝑎𝑥)

          T_lag (d): is the lag time between water falling and reaching the river.

          Kf (-): the fast flow is modelled as a linear reservoir thus a fraction
                  of the volume stored leaves to the river 𝑄𝑓=𝐾𝑓∗𝑆𝑓

          Ks (−): Similarly the slow flow is also modelled as 𝑄𝑆=𝐾𝑠∗𝑆𝑆.

          FM (mm/deg/d): Melt Factor: mm of melt per deg per day


   .. py:property:: states
      :type: collections.abc.ItemsView[str, Any]


      List the (initial!) states for this model.

      Exposed HBV states:
          Si (mm): Interception storage, water stored in leaves
          Su (mm): Unsaturated rootzone storage, water stored accessible to plants
          Sf (mm): Fastflow storage, moving Fast through the soil - preferential flow paths, upper level
          Ss (mm): Groundwater storage, moving Slowly through the soil - deeper grounds water.
          Sp (mm): SnowPack Storage, amount of snow stored


   .. py:method:: finalize() -> None

      Perform tear-down tasks for the model.

      After finalization, the model should not be used anymore.



.. py:class:: HBV

   Bases: :py:obj:`ewatercycle.base.model.ContainerizedModel`, :py:obj:`HBVMethods`


   The HBV eWaterCycle model, with the Container Registry docker image.


   .. py:attribute:: bmi_image
      :type:  ewatercycle.container.ContainerImage


.. py:class:: HBVLocal

   Bases: :py:obj:`ewatercycle.base.model.LocalModel`, :py:obj:`HBVMethods`


   The HBV eWaterCycle model, with the local BMI.


   .. py:attribute:: bmi_class
      :type:  Type[bmipy.Bmi]


.. py:function:: validate_forcing(model: HBVMethods)

   Validate the forcing input of the model, and update model._config with the paths.

   Checks if:
       - the forcing object is officially supported by this model. Warns if not.
       - the user is trying to use GenericLumpedForcing. Raises error if they are.
       - the forcing is HBVForcing, and if so, deals with the txt/nc files correctly
       - the units are correct (if the data has attributes), and converts them it
           they are not correct.

   :param model: HBV Model class