HydPy 6.2.dev1__cp313-cp313-win_amd64.whl

hydpy/models/hland/hland_outlets.py

@@ -0,0 +1,11 @@
+# pylint: disable=missing-module-docstring
+
+# import...
+# ...from HydPy
+from hydpy.core import sequencetools
+
+
+class Q(sequencetools.OutletSequence):
+    """Runoff [m³/s]."""
+
+    NDIM, NUMERIC = 0, False

hydpy/models/hland/hland_parameters.py

@@ -0,0 +1,227 @@
+# pylint: disable=missing-module-docstring
+
+# import...
+# ...from HydPy
+from hydpy.core import parametertools
+
+# ...from hland
+from hydpy.models.hland.hland_constants import CONSTANTS
+from hydpy.models.hland import hland_masks
+
+
+class ParameterBase(parametertools.ZipParameter):
+    """Base class for 1-dimensional parameters."""
+
+    constants = CONSTANTS
+
+    @property
+    def refweights(self):
+        """Reference to the associated instance of |RelZoneAreas| for calculating areal
+        mean values."""
+        return self.subpars.pars.control.zonearea
+
+
+class ParameterComplete(ParameterBase):
+    """Base class for 1-dimensional parameters relevant for all types of zones.
+
+    |ParameterComplete| applies the features of class |ZipParameter| on the land use
+    types |FIELD|, |FOREST|, |GLACIER|, |ILAKE|, and |SEALED| and considers them all as
+    relevant (e.g., for calculating weighted averages).
+
+    We use parameter |PCorr| as an example, which is a subclass of |ParameterComplete|.
+    After preparing the parameter |ZoneType|, |PCorr| allows setting its values using
+    the relevant land-use types as keywords:
+
+    >>> from hydpy import print_vector, round_
+    >>> from hydpy.models.hland import *
+    >>> parameterstep("1d")
+    >>> nmbzones(6)
+    >>> zonetype(FIELD, FOREST, GLACIER, ILAKE, FIELD, SEALED)
+    >>> pcorr(field=2.0, forest=1.0, glacier=4.0, ilake=3.0, sealed=5.0)
+    >>> pcorr
+    pcorr(field=2.0, forest=1.0, glacier=4.0, ilake=3.0, sealed=5.0)
+    >>> print_vector(pcorr.values)
+    2.0, 1.0, 4.0, 3.0, 2.0, 5.0
+
+    Parameter |ZoneArea| serves for calculating areal means (see the documentation on
+    |property| |ParameterBase.refweights|):
+
+    >>> zonearea.values = 0.0, 1.0, 2.0, 3.0, 4.0, 5.0
+    >>> round_(pcorr.average_values())
+    3.4
+
+    Alternatively, pass other masks defined in module |hland_masks| to take only
+    certain types of zones into account:
+
+    >>> round_(pcorr.average_values(model.masks.field))
+    2.0
+    >>> round_(pcorr.average_values("soil"))
+    1.8
+    >>> round_(pcorr.average_values(model.masks.field, "forest"))
+    1.8
+
+    All other masks (for example, |hland_masks.Soil|, being used by |ParameterSoil|
+    subclasses as |hland_control.IcMax|) are subsets of mask |hland_masks.Complete|:
+
+    >>> icmax.mask in pcorr.mask
+    True
+    >>> pcorr.mask in icmax.mask
+    False
+    """
+
+    mask = hland_masks.Complete()
+
+
+class ParameterLand(ParameterBase):
+    """Base class for 1-dimensional parameters relevant for |FIELD|, |FOREST|,
+    |GLACIER|, and |SEALED| zones.
+
+    |ParameterLand| works similarly to |ParameterComplete|.  Some examples based on the
+    parameter |WHC|:
+
+    >>> from hydpy.models.hland import *
+    >>> parameterstep("1d")
+    >>> nmbzones(5)
+    >>> zonetype(FIELD, FOREST, GLACIER, ILAKE, FIELD)
+    >>> whc(field=2.0, forest=1.0, glacier=4.0, ilake=3.0)
+    >>> whc
+    whc(field=2.0, forest=1.0, glacier=4.0)
+    >>> whc(field=2.0, default=9.0)
+    >>> whc
+    whc(field=2.0, forest=9.0, glacier=9.0)
+    >>> zonearea.values = 1.0, 1.0, 1.0, nan, 1.0
+    >>> from hydpy import round_
+    >>> round_(whc.average_values())
+    5.5
+    """
+
+    mask = hland_masks.Land()
+
+
+class ParameterInterception(ParameterBase):
+    """Base class for 1-dimensional parameters relevant for |FIELD|, |FOREST|, and
+    |SEALED| zones.
+
+    |ParameterInterception| works similarly to |ParameterComplete|. Some examples based
+    on the parameter |IcMax|:
+
+    >>> from hydpy.models.hland import *
+    >>> parameterstep("1d")
+    >>> nmbzones(5)
+    >>> zonetype(FIELD, FOREST, GLACIER, ILAKE, SEALED)
+    >>> icmax(field=2.0, forest=1.0, glacier=4.0, ilake=5.0, sealed=3.0)
+    >>> icmax
+    icmax(field=2.0, forest=1.0, sealed=3.0)
+    >>> icmax(field=2.0, default=8.0, sealed=3.0)
+    >>> icmax
+    icmax(field=2.0, forest=8.0, sealed=3.0)
+    >>> zonearea.values = 1.0, 2.0, nan, nan, 3.0
+    >>> from hydpy import round_
+    >>> round_(icmax.average_values())
+    4.5
+    """
+
+    mask = hland_masks.Interception()
+
+
+class ParameterSoil(ParameterBase):
+    """Base class for 1-dimensional parameters relevant for |FIELD| and |FOREST| zones.
+
+    |ParameterSoil| works similarly to |ParameterComplete|. Some examples based on the
+    parameter |IcMax|:
+
+    >>> from hydpy.models.hland import *
+    >>> parameterstep("1d")
+    >>> nmbzones(5)
+    >>> zonetype(FIELD, FOREST, GLACIER, ILAKE, FIELD)
+    >>> icmax(field=2.0, forest=1.0, glacier=4.0, ilake=3.0)
+    >>> icmax
+    icmax(field=2.0, forest=1.0)
+    >>> icmax(field=2.0, default=9.0)
+    >>> icmax
+    icmax(field=2.0, forest=9.0)
+    >>> zonearea.values = 0.0, 1.0, nan, nan, 3.0
+    >>> from hydpy import round_
+    >>> round_(icmax.average_values())
+    3.75
+    """
+
+    mask = hland_masks.Soil()
+
+
+class ParameterUpperZone(ParameterBase):
+    """Base class for 1-dimensional parameters relevant for |FIELD|, |FOREST|, and
+    |GLACIER| zones.
+
+    |ParameterLand| works similarly to |ParameterComplete|.  Some examples based on
+    parameter |H1|:
+
+    >>> from hydpy.models.hland import *
+    >>> parameterstep()
+    >>> nmbzones(6)
+    >>> zonetype(FIELD, FOREST, GLACIER, ILAKE, FIELD, SEALED)
+    >>> h1(field=2.0, forest=1.0, glacier=4.0, ilake=3.0, sealed=5.0)
+    >>> h1
+    h1(field=2.0, forest=1.0, glacier=4.0)
+    >>> h1(field=2.0, default=9.0)
+    >>> h1
+    h1(field=2.0, forest=9.0, glacier=9.0)
+    >>> zonearea.values = 1.0, 1.0, 1.0, nan, 1.0, nan
+    >>> from hydpy import round_
+    >>> round_(h1.average_values())
+    5.5
+    """
+
+    mask = hland_masks.UpperZone()
+
+
+class ParameterGlacier(ParameterBase):
+    """Base class for 1-dimensional parameters relevant for |GLACIER| zones.
+
+    |ParameterGlacier| works similarly to |ParameterComplete|.  Some examples based on
+    the parameter |GMelt|:
+
+    >>> from hydpy.models.hland import *
+    >>> parameterstep("1d")
+    >>> simulationstep("1d")
+    >>> nmbzones(5)
+    >>> zonetype(GLACIER, FOREST, ILAKE, GLACIER, FIELD)
+    >>> gmelt(field=2.0, forest=1.0, glacier=4.0, ilake=3.0)
+    >>> gmelt
+    gmelt(4.0)
+    >>> gmelt(field=2.0, forest=9.0, default=8.0)
+    >>> gmelt
+    gmelt(8.0)
+    >>> zonearea.values = 1.0, nan, nan, 1.0, nan
+    >>> from hydpy import round_
+    >>> round_(gmelt.average_values())
+    8.0
+    """
+
+    mask = hland_masks.Glacier()
+
+
+class ParameterNoGlacier(ParameterBase):
+    """Base class for 1-dimensional parameters relevant for |FIELD|, |FOREST|, and
+    |ILAKE| zones.
+
+    |ParameterNoGlacier| works similarly to |ParameterComplete|.  Some examples based
+    on the parameter |TCorr|:
+
+    >>> from hydpy.models.hland import *
+    >>> parameterstep("1d")
+    >>> nmbzones(5)
+    >>> zonetype(FIELD, FOREST, GLACIER, ILAKE, FIELD)
+    >>> tcorr(field=2.0, forest=1.0, glacier=4.0, ilake=3.0)
+    >>> tcorr
+    tcorr(field=2.0, forest=1.0, ilake=3.0)
+    >>> tcorr(field=2.0, default=9.0)
+    >>> tcorr
+    tcorr(field=2.0, forest=9.0, ilake=9.0)
+    >>> zonearea.values = 1.0, 1.0, nan, 1.0, 1.0
+    >>> from hydpy import round_
+    >>> round_(tcorr.average_values())
+    5.5
+    """
+
+    mask = hland_masks.NoGlacier()

hydpy/models/hland/hland_sequences.py

@@ -0,0 +1,382 @@
+# pylint: disable=missing-module-docstring
+
+# import...
+# ...from site-packages
+import numpy
+
+# ...from HydPy
+from hydpy.core.typingtools import *
+from hydpy.core import sequencetools
+
+
+class Factor1DSequence(sequencetools.FactorSequence):
+    """Base class for 1-dimensional factor subclasses that support aggregation with
+    respect to |ZoneArea|.
+
+    All |Factor1DSequence| subclasses must implement fitting mask objects individually.
+
+    The following example shows how the subclass |TC| works:
+
+    >>> from hydpy.models.hland import *
+    >>> parameterstep("1d")
+    >>> nmbzones(5)
+    >>> zonetype(FIELD, FOREST, GLACIER, ILAKE, SEALED)
+    >>> zonearea.values = 10.0, 20.0, 30.0, 35.0, 5.0
+    >>> factors.tc(5.0, 2.0, 4.0, 1.0, 6.0)
+    >>> from hydpy import round_
+    >>> round_(factors.tc.average_values())
+    2.75
+    """
+
+    NDIM = 1
+    NUMERIC = False
+
+    @property
+    def refweights(self):
+        """Alias for the associated instance of |ZoneArea| for calculating areal
+        values."""
+        return self.subseqs.seqs.model.parameters.control.zonearea
+
+
+class Factor2DSequence(sequencetools.FactorSequence):
+    """Base class for 2-dimensional factor subclasses that support aggregation with
+    respect to |ZoneArea|.
+
+    All |Factor2DSequence| subclasses must implement fitting mask objects individually.
+
+    The following example shows how subclass |SWE| works, which implements mask |Land|:
+
+    >>> from hydpy.models.hland import *
+    >>> parameterstep()
+    >>> nmbzones(5)
+    >>> sclass(2)
+    >>> zonetype(FIELD, FOREST, GLACIER, ILAKE, SEALED)
+    >>> zonearea.values = 10.0, 20.0, 30.0, 40.0, 60.0
+    >>> factors.swe = [[40.0, 10.0, 30.0, nan, 0.0],
+    ...                [60.0, 30.0, 50.0, nan, 20.0]]
+    >>> from hydpy import round_
+    >>> round_(factors.swe.average_values())
+    22.5
+    """
+
+    NDIM = 2
+    NUMERIC = False
+
+    @property
+    def refweights(self):
+        """Alias for the associated instance of |ZoneArea| for calculating areal
+        values."""
+        return self.subseqs.seqs.model.parameters.control.zonearea
+
+    @property
+    def valuevector(self) -> VectorFloat:
+        """Values of the individual zones; each entry is the average of the values of
+        all snow classes of a specific zone.
+
+        We take subclass |SWE| as an example:
+
+        >>> from hydpy.models.hland import *
+        >>> parameterstep("1d")
+        >>> nmbzones(3)
+        >>> sclass(2)
+        >>> zonetype(FIELD)
+        >>> zonearea.values = 1.0, 1.0, 1.0
+        >>> factors.swe = [[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]]
+        >>> from hydpy import print_vector
+        >>> print_vector(factors.swe.valuevector)
+        2.5, 3.5, 4.5
+
+        The definition of |Factor2DSequence.valuevector| of |Factor2DSequence| allows
+        applying method |Variable.average_values| like for the 1-dimensional
+        zone-related sequences of |hland|:
+
+        >>> print_vector([factors.swe.average_values()])
+        3.5
+        """
+        return numpy.mean(self.value, axis=0)
+
+    @property
+    def seriesmatrix(self) -> MatrixFloat:
+        """Time series of the values of the individual zones; each entry is the average
+        of the values of all snow classes of a specific zone.
+
+        We take subclass |Melt| as an example:
+
+        >>> from hydpy import pub
+        >>> pub.timegrids = "2000-01-01", "2000-01-05", "1d"
+        >>> from hydpy.models.hland import *
+        >>> parameterstep("1d")
+        >>> nmbzones(3)
+        >>> sclass(2)
+        >>> zonetype(FIELD)
+        >>> zonearea.values = 1.0, 1.0, 1.0
+        >>> factors.swe.prepare_series()
+        >>> factors.swe.series = [[[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]],
+        ...                     [[2.0, 3.0, 4.0], [5.0, 6.0, 7.0]],
+        ...                     [[3.0, 4.0, 5.0], [6.0, 7.0, 8.0]],
+        ...                     [[4.0, 5.0, 6.0], [7.0, 8.0, 9.0]]]
+        >>> from hydpy import print_vector
+        >>> for values in factors.swe.seriesmatrix:
+        ...     print_vector(values)
+        2.5, 3.5, 4.5
+        3.5, 4.5, 5.5
+        4.5, 5.5, 6.5
+        5.5, 6.5, 7.5
+
+        The definition of |Factor2DSequence.seriesmatrix| of |Factor2DSequence| allows
+        applying method |IOSequence.average_series| like for the 1-dimensional
+        zone-related sequences of |hland|:
+
+        >>> print_vector(factors.swe.average_series())
+        3.5, 4.5, 5.5, 6.5
+        """
+        return numpy.mean(self.series, axis=1)
+
+
+class Flux1DSequence(sequencetools.FluxSequence):
+    """Base class for 1-dimensional flux subclasses that support aggregation with
+    respect to |ZoneArea|.
+
+    All |Flux1DSequence| subclasses must implement fitting mask objects individually.
+
+    The following example shows how the subclass |PC| works:
+
+    >>> from hydpy.models.hland import *
+    >>> parameterstep("1d")
+    >>> nmbzones(5)
+    >>> zonetype(FIELD, FOREST, GLACIER, ILAKE, SEALED)
+    >>> zonearea.values = 10.0, 20.0, 30.0, 35.0, 5.0
+    >>> fluxes.pc(5.0, 2.0, 4.0, 1.0, 6.0)
+    >>> from hydpy import round_
+    >>> round_(fluxes.pc.average_values())
+    2.75
+    """
+
+    NDIM = 1
+    NUMERIC = False
+
+    @property
+    def refweights(self):
+        """Alias for the associated instance of |ZoneArea| for calculating areal
+        values."""
+        return self.subseqs.seqs.model.parameters.control.zonearea
+
+
+class Flux2DSequence(sequencetools.FluxSequence):
+    """Base class for 2-dimensional flux subclasses that support aggregation with
+    respect to |ZoneArea|.
+
+    All |Flux2DSequence| subclasses must implement fitting mask objects individually.
+
+    The following example shows how subclass |Melt| works, which implements mask |Snow|:
+
+    >>> from hydpy.models.hland import *
+    >>> parameterstep("1d")
+    >>> nmbzones(5)
+    >>> sclass(2)
+    >>> zonetype(FIELD, FOREST, GLACIER, ILAKE, SEALED)
+    >>> zonearea.values = 10.0, 20.0, 30.0, 40.0, 60.0
+    >>> fluxes.melt = [[40.0, 10.0, 30.0, nan, 0.0],
+    ...                [60.0, 30.0, 50.0, nan, 20.0]]
+    >>> from hydpy import round_
+    >>> round_(fluxes.melt.average_values())
+    22.5
+    """
+
+    NDIM = 2
+    NUMERIC = False
+
+    @property
+    def refweights(self):
+        """Alias for the associated instance of |ZoneArea| for calculating areal
+        values."""
+        return self.subseqs.seqs.model.parameters.control.zonearea
+
+    @property
+    def valuevector(self) -> VectorFloat:
+        """Values of the individual zones; each entry is the average of the values of
+        all snow classes of a specific zone.
+
+        We take subclass |Melt| as an example:
+
+        >>> from hydpy.models.hland import *
+        >>> parameterstep("1d")
+        >>> nmbzones(3)
+        >>> sclass(2)
+        >>> zonetype(FIELD)
+        >>> zonearea.values = 1.0, 1.0, 1.0
+        >>> fluxes.melt = [[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]]
+        >>> from hydpy import print_vector
+        >>> print_vector(fluxes.melt.valuevector)
+        2.5, 3.5, 4.5
+
+        The definition of |Flux2DSequence.valuevector| of |Flux2DSequence| allows
+        applying method |Variable.average_values| like for the 1-dimensional
+        zone-related sequences of |hland|:
+
+        >>> print_vector([fluxes.melt.average_values()])
+        3.5
+        """
+        return numpy.mean(self.value, axis=0)
+
+    @property
+    def seriesmatrix(self) -> MatrixFloat:
+        """Time series of the values of the individual zones; each entry is the average
+        of the values of all snow classes of a specific zone.
+
+        We take subclass |Melt| as an example:
+
+        >>> from hydpy import pub
+        >>> pub.timegrids = "2000-01-01", "2000-01-05", "1d"
+        >>> from hydpy.models.hland import *
+        >>> parameterstep("1d")
+        >>> nmbzones(3)
+        >>> sclass(2)
+        >>> zonetype(FIELD)
+        >>> zonearea.values = 1.0, 1.0, 1.0
+        >>> fluxes.melt.prepare_series()
+        >>> fluxes.melt.series = [[[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]],
+        ...                     [[2.0, 3.0, 4.0], [5.0, 6.0, 7.0]],
+        ...                     [[3.0, 4.0, 5.0], [6.0, 7.0, 8.0]],
+        ...                     [[4.0, 5.0, 6.0], [7.0, 8.0, 9.0]]]
+        >>> from hydpy import print_vector
+        >>> for values in fluxes.melt.seriesmatrix:
+        ...     print_vector(values)
+        2.5, 3.5, 4.5
+        3.5, 4.5, 5.5
+        4.5, 5.5, 6.5
+        5.5, 6.5, 7.5
+
+        The definition of |Flux2DSequence.seriesmatrix| of |Flux2DSequence| allows
+        applying method |IOSequence.average_series| like for the 1-dimensional
+        zone-related sequences of |hland|:
+
+        >>> print_vector(fluxes.melt.average_series())
+        3.5, 4.5, 5.5, 6.5
+        """
+        return numpy.mean(self.series, axis=1)
+
+
+class State1DSequence(sequencetools.StateSequence):
+    """Base class for 1-dimensional state subclasses that support aggregation with
+    respect to |ZoneArea|.
+
+    All |State1DSequence| subclasses must implement fitting mask objects individually.
+
+    The following example shows how subclass |SM| works, which implements mask |Soil|:
+
+    >>> from hydpy.models.hland import *
+    >>> parameterstep("1d")
+    >>> nmbzones(5)
+    >>> zonetype(FIELD, FOREST, GLACIER, ILAKE, SEALED)
+    >>> zonearea.values = 10.0, 20.0, 30.0, 40.0, 50.0
+    >>> fc(100.0)
+    >>> states.sm = 50.0, 20.0, 40.0, 10.0, nan
+    >>> from hydpy import round_
+    >>> round_(states.sm.average_values())
+    30.0
+    """
+
+    NDIM = 1
+    NUMERIC = False
+
+    @property
+    def refweights(self):
+        """Alias for the associated instance of |ZoneArea| for calculating
+        areal values."""
+        return self.subseqs.seqs.model.parameters.control.zonearea
+
+
+class State2DSequence(sequencetools.StateSequence):
+    """Base class for 2-dimensional state subclasses that support aggregation with
+    respect to |ZoneArea|.
+
+    All |State2DSequence| subclasses must implement fitting mask objects individually.
+
+    The following example shows how subclass |SP| works, which implements mask |Snow|:
+
+    >>> from hydpy.models.hland import *
+    >>> parameterstep("1d")
+    >>> nmbzones(5)
+    >>> sclass(2)
+    >>> zonetype(FIELD, FOREST, GLACIER, ILAKE, SEALED)
+    >>> zonearea.values = 10.0, 20.0, 30.0, 40.0, 60.0
+    >>> states.sp = [[40.0, 10.0, 30.0, nan, 0.0],
+    ...              [60.0, 30.0, 50.0, nan, 20.0]]
+    >>> from hydpy import round_
+    >>> round_(states.sp.average_values())
+    22.5
+    """
+
+    NDIM = 2
+    NUMERIC = False
+
+    @property
+    def refweights(self):
+        """Alias for the associated instance of |ZoneArea| for calculating areal
+        values."""
+        return self.subseqs.seqs.model.parameters.control.zonearea
+
+    @property
+    def valuevector(self) -> VectorFloat:
+        """Values of the individual zones; each entry is the average of the values of
+        all snow classes of a specific zone.
+
+        We take subclass |SP| as an example:
+
+        >>> from hydpy.models.hland import *
+        >>> parameterstep("1d")
+        >>> nmbzones(3)
+        >>> sclass(2)
+        >>> zonetype(FIELD)
+        >>> zonearea.values = 1.0, 1.0, 1.0
+        >>> states.sp = [[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]]
+        >>> from hydpy import print_vector
+        >>> print_vector(states.sp.valuevector)
+        2.5, 3.5, 4.5
+
+        The definition of |State2DSequence.valuevector| of |State2DSequence| allows
+        applying method |Variable.average_values| like for the 1-dimensional
+        zone-related sequences of |hland|:
+
+        >>> print_vector([states.sp.average_values()])
+        3.5
+        """
+        return numpy.mean(self.value, axis=0)
+
+    @property
+    def seriesmatrix(self) -> MatrixFloat:
+        """Time series of the values of the individual zones; each entry is the average
+        of the values of all snow classes of a specific zone.
+
+        We take subclass |SP| as an example:
+
+        >>> from hydpy import pub
+        >>> pub.timegrids = "2000-01-01", "2000-01-05", "1d"
+        >>> from hydpy.models.hland import *
+        >>> parameterstep("1d")
+        >>> nmbzones(3)
+        >>> sclass(2)
+        >>> zonetype(FIELD)
+        >>> zonearea.values = 1.0, 1.0, 1.0
+        >>> states.sp.prepare_series()
+        >>> states.sp.series = [[[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]],
+        ...                     [[2.0, 3.0, 4.0], [5.0, 6.0, 7.0]],
+        ...                     [[3.0, 4.0, 5.0], [6.0, 7.0, 8.0]],
+        ...                     [[4.0, 5.0, 6.0], [7.0, 8.0, 9.0]]]
+        >>> from hydpy import print_vector
+        >>> for values in states.sp.seriesmatrix:
+        ...     print_vector(values)
+        2.5, 3.5, 4.5
+        3.5, 4.5, 5.5
+        4.5, 5.5, 6.5
+        5.5, 6.5, 7.5
+
+        The definition of |State2DSequence.seriesmatrix| of |State2DSequence| allows
+        applying method |IOSequence.average_series| like for the 1-dimensional
+        zone-related sequences of |hland|:
+
+        >>> print_vector(states.sp.average_series())
+        3.5, 4.5, 5.5, 6.5
+        """
+        return numpy.mean(self.series, axis=1)