HydPy-Evap-RET-TW2002 (Turc-Wendling reference evapotranspiration, 2002)

The primary purpose of evap_ret_tw2002 is to serve as a submodel that provides estimates of potential grass reference evapotranspiration following ATV-DVWK (2002), as demonstrated for lland_dd. However, you can also use it as a stand-alone model, as it does not require interaction with a main model. The following examples make use of this stand-alone functionality.

evap_ret_tw2002 requires two submodels. One must follow the RadiationModel_V1 or the RadiationModel_V2 interface and provide global radiation data; the other must follow the TempModel_V1 or the TempModel_V2 interface and provide temperature data.

Integration tests

Note

When new to HydPy, consider reading section Integration Tests first.

Application model evap_ret_tw2002 requires no input from an external model and does not supply any data to an outlet sequence. Hence, assigning a model instance to a blank Element instance is sufficient:

>>> from hydpy import Element
>>> from hydpy.models.evap_ret_tw2002 import *
>>> parameterstep()
>>> element = Element("element")
>>> element.model = model

The Turc-Wendling equation requires input data aggregated over at least one day. We start with a daily simulation step:

>>> from hydpy import IntegrationTest, pub
>>> pub.timegrids = "2000-07-06", "2000-07-07", "1d"

We set the parameter and input values in agreement with the hourly simulation example of evap_ret_fao56, which allows for comparison with the results of the FAO reference evapotranspiration model applied to data of station Uccle (Brussels, Belgium), as reported in example 18 of Allen et al. (1998):

>>> nmbhru(1)
>>> hruarea(1.0)
>>> evapotranspirationfactor(1.0)
>>> hrualtitude(100.0)

evap_ret_fao56 has no counterpart for the CoastFactor parameter. We set its value from our gut feeling to 0.9, as Brussels is not directly adjacent to the coastline (0.6) but also not that far away from it (1.0):

>>> coastfactor(0.9)

A meteo_glob_io and a meteo_temp_io submodel provide the required global radiation and temperature data:

>>> with model.add_radiationmodel_v2("meteo_glob_io"):
...     pass
>>> with model.add_tempmodel_v2("meteo_temp_io"):
...     temperatureaddend(1.0)

Now, we can initialise an IntegrationTest object and set the required meteorological input:

>>> test = IntegrationTest(element)
>>> test.dateformat = "%Y-%d-%m"
>>> model.tempmodel.sequences.inputs.temperature.series = 15.9
>>> model.radiationmodel.sequences.inputs.globalradiation.series = 255.367464

For the example at hand, there is an excellent agreement with the result calculated by evap_ret_fao56 and given by Allen et al. (1998), which is 3.75 mm/d:

>>> test()
Click to see the table

Instead of IO submodels, one could use the main model of evap_ret_tw2002 for providing the temperature data or a “real” submodel that calculates the global radiation data. The first option is not feasible here due to not using evap_ret_tw2002 as a submodel but as a stand-alone model. But we can demonstrate the latter option by using, for example, meteo_glob_fao56, which we also configure in agreement with the hourly simulation example. Hence, meteo_glob_fao56 reproduces the global radiation above so that evap_ret_tw2002 calculates the same potential evapotranspiration value:

>>> with model.add_radiationmodel_v1("meteo_glob_fao56"):
...     latitude(50.8)
...     angstromconstant(0.25)
...     angstromfactor(0.5)

>>> test = IntegrationTest(element)
>>> test.dateformat = "%Y-%d-%m"
>>> model.tempmodel.sequences.inputs.temperature.series = 15.9
>>> model.radiationmodel.sequences.inputs.sunshineduration.series = 9.25

>>> test()
Click to see the table

evap_ret_tw2002 is also applicable to sub-daily simulation step sizes. Then, it still evaluates the Turc-Wendling equation for daily data, namely the averages of the air temperature and the global radiation of the last 24 hours, and converts the resulting daily evapotranspiration to the actual simulation step size. To demonstrate this, we prepare a simulation period of 24 hours:

>>> pub.timegrids = "2000-08-03", "2000-08-04", "1h"

We switch back to IO submodels and take the hourly air temperature and global radiation data from the hourly simulation, land example of evap_aet_morsim:

>>> with model.add_radiationmodel_v2("meteo_glob_io"):
...     pass
>>> with model.add_tempmodel_v2("meteo_temp_io"):
...     temperatureaddend(0.0)

>>> test = IntegrationTest(element)
>>> test.dateformat = "%Y-%d-%m %H:00"

>>> model.tempmodel.sequences.inputs.temperature.series = (
...     16.9, 16.6, 16.4, 16.3, 16.0, 15.9, 16.0, 16.6, 17.4, 19.0, 20.3, 21.4, 21.3,
...     21.8, 22.9, 22.7, 22.5, 21.9, 21.4, 20.7, 19.4, 17.8, 17.0, 16.4)
>>> model.radiationmodel.sequences.inputs.globalradiation.series = (
...     0.0, 0.0, 0.0, 0.0, 1.943686, 21.932441, 57.256187, 109.332844, 170.949152,
...     311.762624, 501.583299, 615.018727, 626.544326, 496.133417, 419.520994,
...     387.887354, 278.496873, 137.138608, 51.080715, 13.632816, 0.185943, 0.0, 0.0,
...     0.0)

Due to averaging over the last 24 hours, we must provide the corresponding logged data for the 24 hours preceding the simulation period. We take them from the hourly simulation, land example, too:

>>> test.inits = (
...     (logs.loggedglobalradiation,
...      [0.0, 0.0, 0.0, 0.0, 0.0, 27.8, 55.6, 138.9, 222.2, 305.6, 333.3, 388.9,
...       527.8, 444.4, 250.0, 222.2, 166.7, 111.1, 55.6, 27.8, 0.0, 0.0, 0.0, 0.0]),
...     (logs.loggedairtemperature,
...      [[13.2], [13.2], [13.1], [12.6], [12.7], [13.0], [13.5], [14.8], [16.2],
...       [17.7], [18.8], [19.4], [20.4], [21.0], [21.5], [21.2], [20.4], [20.7],
...       [20.2], [19.7], [19.0], [18.0], [17.5], [17.1]]))

The calculated reference evapotranspiration does not follow the diurnal pattern of the meteorological input. Instead, it changes only gradually with the moving averages of air temperature and global radiation, so that, for example, the values of the last night hours even exceed those around noon:

>>> test()
Click to see the table

After 24 hours, the moving averages cover exactly the simulated day. Hence, multiplying the last hourly value by 24 gives the reference evapotranspiration one would calculate for this day in a simulation with a daily step size:

>>> from hydpy import round_
>>> round_(24.0 * fluxes.referenceevapotranspiration.series[-1, 0])
2.737713

Method features

class hydpy.models.evap_ret_tw2002.Model[source]

Bases: Main_TempModel_V1, Main_TempModel_V2A, Main_RadiationModel_V1, Main_RadiationModel_V2, Sub_ETModel, PETModel_V1

HydPy-Evap-RET-TW2002 (Turc-Wendling reference evapotranspiration, 2002).

The following “run methods” are called in the given sequence during each simulation step:
The following interface methods are available to main models using the defined model as a submodel:
The following “additional methods” might be called by one or more of the other methods or are meant to be directly called by the user:
Users can hook submodels into the defined main model if they satisfy one of the following interfaces:

  • TempModel_V1 Pure getter interface for using main models as sub-submodels.

  • TempModel_V2 Simple interface for determining the temperature in one step.

  • RadiationModel_V1 Simple interface for determining all data in one step.

DOCNAME = ('Evap-RET-TW2002', 'Turc-Wendling reference evapotranspiration, 2002')
tempmodel

Required submodel that complies with one of the following interfaces: TempModel_V1 or TempModel_V2.

radiationmodel

Required submodel that complies with one of the following interfaces: RadiationModel_V1 or RadiationModel_V2.

REUSABLE_METHODS = ()

Parameter features

class hydpy.models.evap_ret_tw2002.ControlParameters(master: Parameters[TM_co], cls_fastaccess: type[FastAccessParameter] | None = None, cymodel: CyModelProtocol | None = None)

Bases: ControlParameters

Control parameters of model evap_ret_tw2002.

The following classes are selected:

  • NmbHRU The number of separately modelled hydrological response units [-].

  • Water A flag that indicates whether the individual zones are water areas or not.

  • Soil A flag that indicates whether soil evapotranspiration is relevant for the individual zones.

  • Plant A flag that indicates whether the individual zones contain any vegetation.

  • HRUArea The area of each hydrological response unit [km²].

  • HRUAltitude The altitude of each hydrological response unit [m].

  • CoastFactor The “coast factor” of Turc-Wendling’s reference evapotranspiration equation [-].

  • EvapotranspirationFactor The adjustment factor for potential evapotranspiration [-].

class hydpy.models.evap_ret_tw2002.DerivedParameters(master: Parameters[TM_co], cls_fastaccess: type[FastAccessParameter] | None = None, cymodel: CyModelProtocol | None = None)

Bases: DerivedParameters

Derived parameters of model evap_ret_tw2002.

The following classes are selected:

  • HRUAreaFraction The area fraction of each hydrological response unit [-].

  • Days The length of the actual simulation step size in days [d].

  • NmbLogEntries The number of log entries required for a memory duration of 24 hours [-].

Sequence features

class hydpy.models.evap_ret_tw2002.FactorSequences(master: Sequences[TM_co], cls_fastaccess: type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)

Bases: FactorSequences

Factor sequences of model evap_ret_tw2002.

The following classes are selected:
class hydpy.models.evap_ret_tw2002.FluxSequences(master: Sequences[TM_co], cls_fastaccess: type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)

Bases: FluxSequences

Flux sequences of model evap_ret_tw2002.

The following classes are selected:
class hydpy.models.evap_ret_tw2002.LogSequences(master: Sequences[TM_co], cls_fastaccess: type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)

Bases: LogSequences

Log sequences of model evap_ret_tw2002.

The following classes are selected:

Auxiliary features

class hydpy.models.evap_ret_tw2002.Masks[source]

Bases: Masks

Masks applicable to evap_ret_tw2002.

The following classes are selected:

  • Complete Mask without any restrictions.

  • Soil Mask including hydrological response units where evapotranspiration from soils occurs.

  • Plant Mask including hydrological response units containing any vegetation.

  • Water Mask including hydrological response units where evaporation from open water areas.