devicetools¶
This modules implements the fundamental features for structuring HydPy projects.
Module devicetools
provides two Device
subclasses, Node
and Element
. In this
documentation, “node” stands for an object of class Node
, “element” for an object of
class Element
, and “device” for either of them (you cannot initialise objects of
class Device
directly). On the other hand, “nodes”, for example, does not
necessarily mean an object of class Nodes
, but any other group of Node
objects as
well.
Each element handles a single Model
object and represents, for example, a subbasin or
a channel segment. The purpose of a node is to connect different elements and, for
example, to pass the discharge calculated for a subbasin outlet (from a first element)
to the top of a channel segment (to second element). Class Node
and Element
come
with specialised container classes (Nodes
and Elements
). The names of individual
nodes and elements serve as identity values, so duplicate names are not permitted.
Note that module devicetools
implements a registry mechanism both for nodes and
elements, preventing instantiating an object with an already assigned name. This
mechanism allows to address the same node or element in different network files (see
module selectiontools
).
Let us take class Node
as an example. One can call its constructor with the same
name multiple times, but it returns already existing nodes when available:
>>> from hydpy import Node
>>> node1 = Node("test1")
>>> node2a = Node("test2")
>>> node2b = Node("test2")
>>> node1 is node2a
False
>>> node2a is node2b
True
To get information on all currently registered nodes, call method
extract_new()
:
>>> Node.extract_new()
Nodes("test1", "test2")
Method extract_new()
returns only those nodes prepared or
recovered after its last invocation:
>>> node1 = Node("test1")
>>> node3a = Node("test3")
>>> Node.extract_new()
Nodes("test1", "test3")
For a complete list of all available nodes, use the method query_all()
:
>>> Node.query_all()
Nodes("test1", "test2", "test3")
When working interactively in the Python interpreter, it might be useful to clear the registry completely, sometimes. Do this with care because defining nodes with already assigned names might result in surprises due to using their names for identification:
>>> nodes = Node.query_all()
>>> Node.clear_all()
>>> Node.query_all()
Nodes()
>>> node3b = Node("test3")
>>> node3b in nodes
True
>>> nodes.test3.name == node3b.name
True
>>> nodes.test3 is node3b
False
Module devicetools
implements the following members:
TypeDevice
Type variable.
TypeDevices
Type variable.
Keywords
Set of keyword arguments used to describe and search forElement
andNode
objects.
FusedVariable
CombinesInputSequence
andOutputSequence
subclasses of different models dealing with the same property into a single variable.
clear_registries_temporarily()
Context manager for clearing the currentNode
,Element
, andFusedVariable
registries.
Element
Handles aModel
object and connects it to other models viaNode
objects.
- class hydpy.core.devicetools.Keywords(*names: str)[source]¶
-
Set of keyword arguments used to describe and search for
Element
andNode
objects.- startswith(name: str) List[str] [source]¶
Return a list of all keywords, starting with the given string.
>>> from hydpy.core.devicetools import Keywords >>> keywords = Keywords("first_keyword", "second_keyword", ... "keyword_3", "keyword_4", ... "keyboard") >>> keywords.startswith("keyword") ['keyword_3', 'keyword_4']
- endswith(name: str) List[str] [source]¶
Return a list of all keywords ending with the given string.
>>> from hydpy.core.devicetools import Keywords >>> keywords = Keywords("first_keyword", "second_keyword", ... "keyword_3", "keyword_4", ... "keyboard") >>> keywords.endswith("keyword") ['first_keyword', 'second_keyword']
- contains(name: str) List[str] [source]¶
Return a list of all keywords containing the given string.
>>> from hydpy.core.devicetools import Keywords >>> keywords = Keywords("first_keyword", "second_keyword", ... "keyword_3", "keyword_4", ... "keyboard") >>> keywords.contains("keyword") ['first_keyword', 'keyword_3', 'keyword_4', 'second_keyword']
- update(*names: str) None [source]¶
Before updating, the given names are checked to be valid variable identifiers.
>>> from hydpy.core.devicetools import Keywords >>> keywords = Keywords("first_keyword", "second_keyword", ... "keyword_3", "keyword_4", ... "keyboard") >>> keywords.update("test_1", "test 2") Traceback (most recent call last): ... ValueError: While trying to add the keyword `test 2` to device ?, the following error occurred: The given name string `test 2` does not define a valid variable identifier. ...
Note that even the first string (test1) is not added due to the second one (test 2) being invalid.
>>> keywords Keywords("first_keyword", "keyboard", "keyword_3", "keyword_4", "second_keyword")
After correcting the second string, everything works fine:
>>> keywords.update("test_1", "test_2") >>> keywords Keywords("first_keyword", "keyboard", "keyword_3", "keyword_4", "second_keyword", "test_1", "test_2")
- add(name: Any) None [source]¶
Before adding a new name, it is checked to be valid variable identifiers.
>>> from hydpy.core.devicetools import Keywords >>> keywords = Keywords("first_keyword", "second_keyword", ... "keyword_3", "keyword_4", ... "keyboard") >>> keywords.add("1_test") Traceback (most recent call last): ... ValueError: While trying to add the keyword `1_test` to device ?, the following error occurred: The given name string `1_test` does not define a valid variable identifier. ...
>>> keywords Keywords("first_keyword", "keyboard", "keyword_3", "keyword_4", "second_keyword")
After correcting the string, everything works fine:
>>> keywords.add("one_test") >>> keywords Keywords("first_keyword", "keyboard", "keyword_3", "keyword_4", "one_test", "second_keyword")
- class hydpy.core.devicetools.FusedVariable(name: str, *sequences: sequencetools.InOutSequenceTypes)[source]¶
Bases:
object
Combines
InputSequence
andOutputSequence
subclasses of different models dealing with the same property into a single variable.Class
FusedVariable
is one possible type of the propertyvariable
of classNode
. We need it in some HydPy projects where the involved models do not only pass runoff to each other but share other types of data as well. Each project-specificFusedVariable
object serves as a “meta-type”, indicating which input and output sequences of the different models correlate and are thus connectable with each other.Using class
FusedVariable
is easiest to explain by a concrete example. Assume we useconv_v001
to interpolate the air temperature for a specific location. We use this temperature as input to theevap_v001
model, which requires this and other meteorological data to calculate potential evapotranspiration. Further, we pass the calculated potential evapotranspiration as input tolland_v2
for calculating the actual evapotranspiration. Hence, we need to connect the output sequenceReferenceEvapotranspiration
ofevap_v001
with the input sequencePET
oflland_v2
.Additionally,
lland_v2
requires temperature data itself for modelling snow processes, introducing the problem that we need to use the same data (the output ofconv_v001
) as the input of two differently named input sequences (AirTemperature
andTemL
forevap_v001
andlland_v2
, respectively).For our concrete example, we need to create two
FusedVariable
objects. E combinesReferenceEvapotranspiration
andPET
and T combinesAirTemperature
andTemL
(for convenience, we import their globally available aliases):>>> from hydpy import FusedVariable >>> from hydpy.inputs import lland_PET, evap_AirTemperature, lland_TemL >>> from hydpy.outputs import evap_ReferenceEvapotranspiration >>> E = FusedVariable("E", evap_ReferenceEvapotranspiration, lland_PET) >>> T = FusedVariable("T", evap_AirTemperature, lland_TemL)
Now we can construct the network:
Node t1 handles the original temperature and serves as the input node to element conv. We define the (arbitrarily selected) string Temp to be its variable.
Node e receives the potential evapotranspiration calculated by element evap and passes it to element lland. Node e thus receives the fused variable E.
Node t2 handles the interpolated temperature and serves as the outlet node of element conv and the input node to elements evap and lland. Node t2 thus receives the fused variable T.
>>> from hydpy import Node, Element >>> t1 = Node("t1", variable="Temp") >>> t2 = Node("t2", variable=T) >>> e = Node("e", variable=E) >>> conv = Element("element_conv", ... inlets=t1, ... outlets=t2) >>> evap = Element("element_evap", ... inputs=t2, ... outputs=e) >>> lland = Element("element_lland", ... inputs=(t2, e), ... outlets="node_q")
Now we can prepare the different model objects and assign them to their corresponding elements (note that parameters
InputCoordinates
andOutputCoordinates
ofconv_v001
first require information on the location of the relevant nodes):>>> from hydpy import prepare_model >>> model_conv = prepare_model("conv_v001") >>> model_conv.parameters.control.inputcoordinates(t1=(0, 0)) >>> model_conv.parameters.control.outputcoordinates(t2=(1, 1)) >>> model_conv.parameters.control.maxnmbinputs(1) >>> model_conv.parameters.update() >>> conv.model = model_conv >>> evap.model = prepare_model("evap_v001") >>> lland.model = prepare_model("lland_v2")
We assign a temperature value to node t1:
>>> t1.sequences.sim = -273.15
Model
conv_v001
now can perform a simulation step and pass its output to node t2:>>> conv.model.simulate(0) >>> t2.sequences.sim sim(-273.15)
Without further configuration,
evap_v001
cannot perform any simulation steps. Hence, we just call itsload_data()
method to show that its input sequenceAirTemperature
is well connected to theSim
sequence of node t2 and receives the correct data:>>> evap.model.load_data() >>> evap.model.sequences.inputs.airtemperature airtemperature(-273.15)
The output sequence
ReferenceEvapotranspiration
is also well connected. A call to methodupdate_outputs()
passes its (manually set) value to node e, respectively:>>> evap.model.sequences.fluxes.referenceevapotranspiration = 999.9 >>> evap.model.update_outputs() >>> e.sequences.sim sim(999.9)
Finally, both input sequences
TemL
andPET
receive the current values of nodes t2 and e:>>> lland.model.load_data() >>> lland.model.sequences.inputs.teml teml(-273.15) >>> lland.model.sequences.inputs.pet pet(999.9)
When defining fused variables, class
FusedVariable
performs some registration behind the scenes, similar to classesNode
andElement
do. Again, the name works as the identifier, and we force the same fused variable to exist only once, even when defined in different selection files repeatedly. Hence, when we repeat the definition from above, we get the same object:>>> Test = FusedVariable("T", evap_AirTemperature, lland_TemL) >>> T is Test True
Changing the member sequences of an existing fused variable is not allowed:
>>> from hydpy.inputs import hland_T >>> FusedVariable("T", hland_T, lland_TemL) Traceback (most recent call last): ... ValueError: The sequences combined by a FusedVariable object cannot be changed. The already defined sequences of the fused variable `T` are `evap_AirTemperature and lland_TemL` instead of `hland_T and lland_TemL`. Keep in mind, that `name` is the unique identifier for fused variable instances.
Defining additional fused variables with the same member sequences does not seem advisable but is allowed:
>>> Temp = FusedVariable("Temp", evap_AirTemperature, lland_TemL) >>> T is Temp False
To get an overview of the already existing fused variables, call method
get_registry()
:>>> len(FusedVariable.get_registry()) 3
Principally, you can clear the registry via method
clear_registry()
, but remember it does not removeFusedVariable
objects from the running process being otherwise referenced:>>> FusedVariable.clear_registry() >>> FusedVariable.get_registry() () >>> t2.variable FusedVariable("T", evap_AirTemperature, lland_TemL)
- classmethod get_registry() Tuple[FusedVariable, ...] [source]¶
Get all
FusedVariable
objects initialised so far.
- classmethod clear_registry() None [source]¶
Clear the registry from all
FusedVariable
objects initialised so far.Use this method only for good reasons!
- class hydpy.core.devicetools.Devices(*values: TypeDevice | str | Iterable[TypeDevice | str] | None, mutable: bool = True)[source]¶
Bases:
Generic
[TypeDevice
]Base class for class
Elements
and classNodes
.The following features are common to class
Nodes
and classElements
. We arbitrarily select classNodes
for all examples.To initialise a
Nodes
collection class, pass a variable number ofstr
orNode
objects. Strings are used to create new or query already existing nodes automatically:>>> from hydpy import Node, Nodes >>> nodes = Nodes("na", ... Node("nb", variable="W"), ... Node("nc", keywords=("group_a", "group_1")), ... Node("nd", keywords=("group_a", "group_2")), ... Node("ne", keywords=("group_b", "group_1")))
Nodes
andElements
objects are containers supporting attribute access. You can access each node or element directly by its name:>>> nodes.na Node("na", variable="Q")
Wrong node names result in the following error message:
>>> nodes.wrong Traceback (most recent call last): ... AttributeError: The selected Nodes object has neither a `wrong` attribute nor does it handle a Node object with name or keyword `wrong`, which could be returned.
As explained in more detail in the documentation on property
keywords
, you can also use the keywords of the individual nodes to query the relevant ones:>>> nodes.group_a Nodes("nc", "nd")
Especially in this context, you might find it useful to also get an iterable object in case no node or only a single node is available:
>>> Nodes.forceiterable = True >>> nodes.wrong Nodes() >>> nodes.na Nodes("na") >>> Nodes.forceiterable = False
Attribute deleting is supported:
>>> "na" in nodes True >>> del nodes.na >>> "na" in nodes False >>> del nodes.na Traceback (most recent call last): ... AttributeError: The actual Nodes object does not handle a Node object named `na` which could be removed, and deleting other attributes is not supported.
However, shown by the next example, setting devices via attribute access could result in inconsistencies and is not allowed (see method
add_device()
instead):>>> nodes.NF = Node("nf") Traceback (most recent call last): ... AttributeError: Setting attributes of Nodes objects could result in confusion whether a new attribute should be handled as a Node object or as a "normal" attribute and is thus not support, hence `NF` is rejected.
Nodes
andElements
instances support iteration:>>> len(nodes) 4 >>> for node in nodes: ... print(node.name, end=",") nb,nc,nd,ne,
The binary operators +, +=, - and -= support adding and removing single devices or groups of devices:
>>> nodes Nodes("nb", "nc", "nd", "ne") >>> nodes - Node("nc") Nodes("nb", "nd", "ne")
Nodes(“nb”, “nc”, “nd”, “ne”) >>> nodes -= Nodes(“nc”, “ne”) >>> nodes Nodes(“nb”, “nd”)
>>> nodes + "nc" Nodes("nb", "nc", "nd") >>> nodes Nodes("nb", "nd") >>> nodes += ("nc", Node("ne")) >>> nodes Nodes("nb", "nc", "nd", "ne")
Attempts to add already existing or to remove non-existing devices do no harm:
>>> nodes Nodes("nb", "nc", "nd", "ne") >>> nodes + ("nc", "ne") Nodes("nb", "nc", "nd", "ne") >>> nodes - Node("na") Nodes("nb", "nc", "nd", "ne")
Comparisons are supported, with “x < y” being
True
if “x” is a subset of “y”:>>> subgroup = Nodes("nc", "ne") >>> subgroup < nodes, nodes < subgroup, nodes < nodes (True, False, False) >>> subgroup <= nodes, nodes <= subgroup, nodes <= nodes (True, False, True) >>> subgroup == nodes, nodes == subgroup, nodes == nodes, nodes == "nodes" (False, False, True, False) >>> subgroup != nodes, nodes != subgroup, nodes != nodes, nodes != "nodes" (True, True, False, True) >>> subgroup >= nodes, nodes >= subgroup, nodes >= nodes (False, True, True) >>> subgroup > nodes, nodes > subgroup, nodes > nodes (False, True, False)
Class
Nodes
supports the in operator both forstr
andNode
objects and generally returnsFalse
for other types:>>> "na" in nodes False >>> "nb" in nodes True >>> Node("na") in nodes False >>> Node("nb") in nodes True >>> 1 in nodes False
Passing wrong arguments to the constructor of class
Node
results in errors like the following:>>> from hydpy import Element >>> Nodes("na", Element("ea")) Traceback (most recent call last): ... TypeError: While trying to initialise a `Nodes` object, the following error occurred: The given (sub)value `Element("ea")` is not an instance of the following classes: Node and str.
- add_device(device: TypeDevice | str) None [source]¶
Add the given
Node
orElement
object to the actualNodes
orElements
object.You can pass either a string or a device:
>>> from hydpy import Nodes >>> nodes = Nodes() >>> nodes.add_device("old_node") >>> nodes Nodes("old_node") >>> nodes.add_device("new_node") >>> nodes Nodes("new_node", "old_node")
Method
add_device()
is disabled for immutableNodes
andElements
objects:>>> nodes.mutable = False >>> nodes.add_device("newest_node") Traceback (most recent call last): ... RuntimeError: While trying to add the device `newest_node` to a Nodes object, the following error occurred: Adding devices to immutable Nodes objects is not allowed.
- remove_device(device: TypeDevice | str) None [source]¶
Remove the given
Node
orElement
object from the actualNodes
orElements
object.You can pass either a string or a device:
>>> from hydpy import Node, Nodes >>> nodes = Nodes("node_x", "node_y") >>> node_x, node_y = nodes >>> nodes.remove_device(Node("node_y")) >>> nodes Nodes("node_x") >>> nodes.remove_device(Node("node_x")) >>> nodes Nodes() >>> nodes.remove_device(Node("node_z")) Traceback (most recent call last): ... ValueError: While trying to remove the device `node_z` from a Nodes object, the following error occurred: The actual Nodes object does not handle such a device.
Method
remove_device()
is disabled for immutableNodes
andElements
objects:>>> nodes.mutable = False >>> nodes.remove_device("node_z") Traceback (most recent call last): ... RuntimeError: While trying to remove the device `node_z` from a Nodes object, the following error occurred: Removing devices from immutable Nodes objects is not allowed.
- property names: Tuple[str, ...]¶
A sorted tuple of the names of the handled devices.
>>> from hydpy import Nodes >>> Nodes("a", "c", "b").names ('a', 'b', 'c')
- property devices: Tuple[TypeDevice, ...]¶
A tuple of the handled devices sorted by the device names.
>>> from hydpy import Nodes >>> for node in Nodes("a", "c", "b").devices: ... print(repr(node)) Node("a", variable="Q") Node("b", variable="Q") Node("c", variable="Q")
- property keywords: Set[str]¶
A set of all keywords of all handled devices.
In addition to attribute access via device names,
Nodes
andElements
objects allow for attribute access via keywords, allowing for an efficient search of certain groups of devices. Let us use the example from above, where the nodes na and nb have no keywords, but each of the other three nodes both belongs to either group_a or group_b and group_1 or group_2:>>> from hydpy import Node, Nodes >>> nodes = Nodes("na", ... Node("nb", variable="W"), ... Node("nc", keywords=("group_a", "group_1")), ... Node("nd", keywords=("group_a", "group_2")), ... Node("ne", keywords=("group_b", "group_1"))) >>> nodes Nodes("na", "nb", "nc", "nd", "ne") >>> sorted(nodes.keywords) ['group_1', 'group_2', 'group_a', 'group_b']
If you are interested in inspecting all devices belonging to group_a, select them via this keyword:
>>> subgroup = nodes.group_1 >>> subgroup Nodes("nc", "ne")
You can further restrict the search by also selecting the devices belonging to group_b, which holds only for node “e”, in the discussed example:
>>> subsubgroup = subgroup.group_b >>> subsubgroup Node("ne", variable="Q", keywords=["group_1", "group_b"])
Note that the keywords already used for building a device subgroup are not informative anymore (as they hold for each device) and are thus not shown anymore:
>>> sorted(subgroup.keywords) ['group_a', 'group_b']
The latter might be confusing if you intend to work with a device subgroup for a longer time. After copying the subgroup, all keywords of the contained devices are available again:
>>> from copy import copy >>> newgroup = copy(subgroup) >>> sorted(newgroup.keywords) ['group_1', 'group_a', 'group_b']
- search_keywords(*keywords: str) TypeDevices [source]¶
Search for all devices handling at least one of the given keywords and return them.
>>> from hydpy import Node, Nodes >>> nodes = Nodes("na", ... Node("nb", variable="W"), ... Node("nc", keywords=("group_a", "group_1")), ... Node("nd", keywords=("group_a", "group_2")), ... Node("ne", keywords=("group_b", "group_1"))) >>> nodes.search_keywords("group_c") Nodes() >>> nodes.search_keywords("group_a") Nodes("nc", "nd") >>> nodes.search_keywords("group_a", "group_1") Nodes("nc", "nd", "ne")
- copy() TypeDevices [source]¶
Return a shallow copy of the actual
Nodes
orElements
object.Method
copy()
returns a semi-flat copy ofNodes
orElements
objects due to their devices being not copyable:>>> from hydpy import Nodes >>> old = Nodes("x", "y") >>> import copy >>> new = copy.copy(old) >>> new == old True >>> new is old False >>> new.devices is old.devices False >>> new.x is new.x True
Changing the
name
of a device is recognised both by the original and the copied collection objects:>>> new.x.name = "z" >>> old.z Node("z", variable="Q") >>> new.z Node("z", variable="Q")
Deep copying is permitted due to the above reason:
>>> copy.deepcopy(old) Traceback (most recent call last): ... NotImplementedError: Deep copying of Nodes objects is not supported, as it would require to make deep copies of the Node objects themselves, which is in conflict with using their names as identifiers.
- class hydpy.core.devicetools.Nodes(*values: MayNonerable2[Node, str], mutable: bool = True, defaultvariable: NodeVariableType = 'Q')[source]¶
-
A container class for handling
Node
objects.For the general usage of
Nodes
objects, please see the documentation on its base classDevices
.Class
Nodes
provides the additional keyword argument defaultvariable. Use it to temporarily change the default variable “Q” to another value during the initialisation of newNode
objects:>>> from hydpy import Nodes >>> a1, t2 = Nodes("a1", "a2", defaultvariable="A") >>> a1 Node("a1", variable="A")
Be aware that changing the default variable does not affect already existing nodes:
>>> a1, b1 = Nodes("a1", "b1", defaultvariable="B") >>> a1 Node("a1", variable="A") >>> b1 Node("b1", variable="B")
- prepare_allseries(allocate_ram: bool = True, jit: bool = False) None [source]¶
Call method
prepare_allseries()
of all handledNode
objects.
- prepare_simseries(allocate_ram: bool = True, read_jit: bool = False, write_jit: bool = False) None [source]¶
Call method
prepare_simseries()
of all handledNode
objects.
- prepare_obsseries(allocate_ram: bool = True, read_jit: bool = False, write_jit: bool = False) None [source]¶
Call method
prepare_obsseries()
of all handledNode
objects.
- load_allseries() None [source]¶
Call methods
load_simseries()
andload_obsseries()
.
- load_simseries() None [source]¶
Call method
load_series()
of allSim
objects with an activatedmemoryflag
.
- load_obsseries() None [source]¶
Call method
load_series()
of allObs
objects with an activatedmemoryflag
.
- save_allseries() None [source]¶
Call methods
save_simseries()
andsave_obsseries()
.
- save_simseries() None [source]¶
Call method
save_series()
of allSim
objects with an activatedmemoryflag
.
- save_obsseries() None [source]¶
Call method
save_series()
of allObs
objects with an activatedmemoryflag
.
- class hydpy.core.devicetools.Elements(*values: TypeDevice | str | Iterable[TypeDevice | str] | None, mutable: bool = True)[source]¶
-
A container for handling
Element
objects.For the general usage of
Elements
objects, please see the documentation on its base classDevices
.- prepare_models() None [source]¶
Call method
prepare_model()
of all handleElement
objects.We show, based on the LahnH example project, that method
init_model()
prepares theModel
objects of all elements, including building the required connections and updating the derived parameters:>>> from hydpy.examples import prepare_full_example_1 >>> prepare_full_example_1() >>> from hydpy import attrready, HydPy, pub, TestIO >>> with TestIO(): ... hp = HydPy("LahnH") ... pub.timegrids = "1996-01-01", "1996-02-01", "1d" ... hp.prepare_network() ... hp.prepare_models() >>> hp.elements.land_dill.model.parameters.derived.dt dt(0.000833)
Wrong control files result in error messages like the following:
>>> with TestIO(): ... with open("LahnH/control/default/land_dill.py", "a") as file_: ... _ = file_.write("zonetype(-1)") ... hp.prepare_models() Traceback (most recent call last): ... ValueError: While trying to initialise the model object of element `land_dill`, the following error occurred: While trying to load the control file `...land_dill.py`, the following error occurred: At least one value of parameter `zonetype` of element `?` is not valid.
By default, missing control files result in exceptions:
>>> del hp.elements.land_dill.model >>> import os >>> with TestIO(): ... os.remove("LahnH/control/default/land_dill.py") ... hp.prepare_models() Traceback (most recent call last): ... FileNotFoundError: While trying to initialise the model object of element `land_dill`, the following error occurred: While trying to load the control file `...land_dill.py`, the following error occurred: ... >>> attrready(hp.elements.land_dill, "model") False
When building new, still incomplete HydPy projects, this behaviour can be annoying. After setting the option
warnmissingcontrolfile
toFalse
, missing control files result in a warning only:>>> with TestIO(): ... with pub.options.warnmissingcontrolfile(True): ... hp.prepare_models() Traceback (most recent call last): ... UserWarning: Due to a missing or no accessible control file, no model could be initialised for element `land_dill` >>> attrready(hp.elements.land_dill, "model") False
- init_models() None [source]¶
Deprecated: use method
prepare_models()
instead.>>> from hydpy import Elements >>> from unittest import mock >>> with mock.patch.object(Elements, "prepare_models") as mocked: ... elements = Elements() ... elements.init_models() Traceback (most recent call last): ... hydpy.core.exceptiontools.HydPyDeprecationWarning: Method `init_models` of class `Elements` is deprecated. Use method `prepare_models` instead. >>> mocked.call_args_list [call()]
- save_controls(parameterstep: timetools.PeriodConstrArg | None = None, simulationstep: timetools.PeriodConstrArg | None = None, auxfiler: auxfiletools.Auxfiler | None = None) None [source]¶
Save the control parameters of the
Model
object handled by eachElement
object and eventually the ones handled by the givenAuxfiler
object.
- load_conditions() None [source]¶
Save the initial conditions of the
Model
object handled by eachElement
object.
- save_conditions() None [source]¶
Save the calculated conditions of the
Model
object handled by eachElement
object.
- trim_conditions() None [source]¶
Call method
trim_conditions()
of theSequences
object handled (indirectly) by eachElement
object.
- reset_conditions() None [source]¶
Call method
reset()
of theSequences
object handled (indirectly) by eachElement
object.
- property conditions: hydpytools.ConditionsType¶
A nested dictionary that contains the values of all
ConditionSequence
objects of all currently handled models.See the documentation on property
conditions
for further information.
- prepare_allseries(allocate_ram: bool = True, jit: bool = False) None [source]¶
Call method
prepare_allseries()
of all handledElement
objects.
- prepare_inputseries(allocate_ram: bool = True, read_jit: bool = False, write_jit: bool = False) None [source]¶
Call method
prepare_inputseries()
of all handledElement
objects.
- prepare_factorseries(allocate_ram: bool = True, write_jit: bool = False) None [source]¶
Call method
prepare_factorseries()
of all handledElement
objects.
- prepare_fluxseries(allocate_ram: bool = True, write_jit: bool = False) None [source]¶
Call method
prepare_fluxseries()
of all handledElement
objects.
- prepare_stateseries(allocate_ram: bool = True, write_jit: bool = False) None [source]¶
Call method
prepare_stateseries()
of all handledElement
objects.
- load_allseries() None [source]¶
Call methods
load_inputseries()
,load_factorseries()
,load_fluxseries()
, andload_stateseries()
.
- load_inputseries() None [source]¶
Call method
load_series()
of allInputSequence
objects with an activatedmemoryflag
.
- load_factorseries() None [source]¶
Call method
load_series()
of allFactorSequence
objects with an activatedmemoryflag
.
- load_fluxseries() None [source]¶
Call method
load_series()
of allFluxSequence
objects with an activatedmemoryflag
.
- load_stateseries() None [source]¶
Call method
load_series()
of allStateSequence
objects with an activatedmemoryflag
.
- save_allseries() None [source]¶
Call methods
save_inputseries()
,save_factorseries()
,save_fluxseries()
, andsave_stateseries()
.
- save_inputseries() None [source]¶
Call method
save_series()
of allInputSequence
objects with an activatedmemoryflag
.
- save_factorseries() None [source]¶
Call method
save_series()
of allFactorSequence
objects with an activatedmemoryflag
.
- save_fluxseries() None [source]¶
Call method
save_series()
of allFluxSequence
objects with an activatedmemoryflag
.
- save_stateseries() None [source]¶
Call method
save_series()
of allStateSequence
objects with an activatedmemoryflag
.
- class hydpy.core.devicetools.Device(value: Device | str, *args: object, **kwargs: object)[source]¶
Bases:
object
Base class for class
Element
and classNode
.- classmethod query_all() Devices[Device] [source]¶
Get all
Node
orElement
objects initialised so far.See the main documentation on module
devicetools
for further information.
- classmethod extract_new() Devices[Device] [source]¶
Gather all “new”
Node
orElement
objects.See the main documentation on module
devicetools
for further information.
- classmethod clear_all() None [source]¶
Clear the registry from all initialised
Node
orElement
objects.See the main documentation on module
devicetools
for further information.
- property name: str¶
Name of the actual
Node
orElement
object.Device names serve as identifiers, as explained in the main documentation on module
devicetools
. Hence, define them carefully:>>> from hydpy import Node >>> Node.clear_all() >>> node1, node2 = Node("n1"), Node("n2") >>> node1 is Node("n1") True >>> node1 is Node("n2") False
Each device name must be a valid variable identifier (see function
valid_variable_identifier()
) to allow for attribute access:>>> from hydpy import Nodes >>> nodes = Nodes(node1, "n2") >>> nodes.n1 Node("n1", variable="Q")
Invalid variable identifiers result in errors like the following:
>>> node3 = Node("n 3") Traceback (most recent call last): ... ValueError: While trying to initialize a `Node` object with value `n 3` of type `str`, the following error occurred: The given name string `n 3` does not define a valid variable identifier. ...
When you change the name of a device (only do this for a good reason), the corresponding keys of all related
Nodes
andElements
objects (as well as of the internal registry) change automatically:>>> Node.query_all() Nodes("n1", "n2") >>> node1.name = "n1a" >>> nodes Nodes("n1a", "n2") >>> Node.query_all() Nodes("n1a", "n2")
- property keywords: Keywords¶
Keywords describing the actual
Node
orElement
object.The keywords are contained within a
Keywords
object:>>> from hydpy import Node >>> node = Node("n", keywords="word0") >>> node.keywords Keywords("word0")
Assigning new words does not overwrite already existing ones. You are allowed to add them individually or within iterable objects:
>>> node.keywords = "word1" >>> node.keywords = "word2", "word3" >>> node.keywords Keywords("word0", "word1", "word2", "word3")
Additionally, passing additional keywords to the constructor of class
Node
orElement
works also fine:>>> Node("n", keywords=("word3", "word4", "word5")) Node("n", variable="Q", keywords=["word0", "word1", "word2", "word3", "word4", "word5"])
You can delete all keywords at once:
>>> del node.keywords >>> node.keywords Keywords()
- class hydpy.core.devicetools.Node(value: Device | str, *args: object, **kwargs: object)[source]¶
Bases:
Device
Handles the data flow between
Element
objects.Node
objects always handle two sequences, aSim
object for simulated values and anObs
object for measured values:>>> from hydpy import Node >>> node = Node("test") >>> for sequence in node.sequences: ... print(sequence) sim(0.0) obs(0.0)
Each node can handle an arbitrary number of “input” and “output” elements, available as instance attributes entries and exits, respectively:
>>> node.entries Elements() >>> node.exits Elements()
You cannot (or at least should not) add new elements manually:
>>> node.entries = "element" Traceback (most recent call last): ... AttributeError: ... >>> node.exits.add_device("element") Traceback (most recent call last): ... RuntimeError: While trying to add the device `element` to a Elements object, the following error occurred: Adding devices to immutable Elements objects is not allowed.
Instead, see the documentation on class
Element
on how to connectNode
andElement
objects properly.- masks = defaultmask of module hydpy.core.masktools¶
- sequences: sequencetools.NodeSequences¶
- property entries: Elements¶
Group of
Element
objects which set the the simulated value of theNode
object.
- property exits: Elements¶
Group of
Element
objects which query the simulated or observed value of the actualNode
object.
- property variable: NodeVariableType¶
The variable handled by the actual
Node
object.By default, we suppose that nodes route discharge:
>>> from hydpy import Node >>> node = Node("test1") >>> node.variable 'Q'
Each other string, as well as each
InputSequence
subclass, is acceptable (for further information, see the documentation on methodconnect()
):>>> Node("test2", variable="H") Node("test2", variable="H") >>> from hydpy.models.hland.hland_inputs import T >>> Node("test3", variable=T) Node("test3", variable=hland_T)
The last above example shows that the string representations of nodes handling “class variables” use the aliases importable from the top-level of the HydPy package:
>>> from hydpy.inputs import hland_P >>> Node("test4", variable=hland_P) Node("test4", variable=hland_P)
For some complex HydPy projects, one may need to fall back on
FusedVariable
objects. The string representation then relies on the name of the fused variable:>>> from hydpy import FusedVariable >>> from hydpy.inputs import lland_Nied >>> Precipitation = FusedVariable("Precip", hland_P, lland_Nied) >>> Node("test5", variable=Precipitation) Node("test5", variable=Precip)
To avoid confusion, one cannot change
variable
:>>> node.variable = "H" Traceback (most recent call last): ... AttributeError: ... >>> Node("test1", variable="H") Traceback (most recent call last): ... ValueError: The variable to be represented by a Node instance cannot be changed. The variable of node `test1` is `Q` instead of `H`. Keep in mind, that `name` is the unique identifier of node objects.
- property deploymode: Literal['newsim', 'oldsim', 'obs', 'obs_newsim', 'obs_oldsim']¶
Defines the kind of information a node offers its exit elements.
HydPy supports the following modes:
newsim: Deploy the simulated values calculated just recently. newsim is the default mode, used, for example, when a node receives a discharge value from an upstream element and passes it to the downstream element directly.
obs: Deploy observed values instead of simulated values. The node still receives the simulated values from its upstream element(s). However, it deploys values to its downstream element(s), which are defined externally. Usually, these values are observations made available within a time-series file. See the documentation on module
sequencetools
for further information on file specifications.oldsim: Similar to mode obs. However, it is usually applied when a node is supposed to deploy simulated values that have been calculated in a previous simulation run and stored in a sequence file.
obs_newsim: Combination of mode obs and newsim. Mode obs_newsim gives priority to the provision of observation values. New simulation values serve as a replacement for missing observed values.
obs_oldsim: Combination of mode obs and oldsim. Mode obs_oldsim gives priority to the provision of observation values. Old simulation values serve as a replacement for missing observed values.
One relevant difference between modes obs and oldsim is that the external values are either handled by the obs or the sim sequence object. Hence, if you select the oldsim mode, the values of the upstream elements calculated within the current simulation are not available (e.g. for parameter calibration) after the simulation finishes.
Please refer to the documentation on method
simulate()
of classHydPy
, which provides some application examples.>>> from hydpy import Node >>> node = Node("test") >>> node.deploymode 'newsim' >>> node.deploymode = "obs" >>> node.deploymode 'obs' >>> node.deploymode = "oldsim" >>> node.deploymode 'oldsim' >>> node.deploymode = "obs_newsim" >>> node.deploymode 'obs_newsim' >>> node.deploymode = "obs_oldsim" >>> node.deploymode 'obs_oldsim' >>> node.deploymode = "newsim" >>> node.deploymode 'newsim' >>> node.deploymode = "oldobs" Traceback (most recent call last): ... ValueError: When trying to set the routing mode of node `test`, the value `oldobs` was given, but only the following values are allowed: `newsim`, `oldsim`, `obs`, `obs_newsim`, and `obs_oldsim`.
- get_double(group: str) Double [source]¶
Return the
Double
object appropriate for the givenElement
input or output group and the actualdeploymode
.Method
get_double()
should be of interest for framework developers only (and eventually for model developers).Let
Node
object node1 handle different simulation and observation values:>>> from hydpy import Node >>> node = Node("node1") >>> node.sequences.sim = 1.0 >>> node.sequences.obs = 2.0
The following test function shows for a given
deploymode
if methodget_double()
either returns theDouble
object handling the simulated value (1.0) or theDouble
object handling the observed value (2.0):>>> def test(deploymode): ... node.deploymode = deploymode ... for group in ("inlets", "receivers", "outlets", "senders"): ... print(group, node.get_double(group))
In the default mode, nodes (passively) route simulated values by offering the
Double
object of sequenceSim
to allElement
input and output groups:>>> test("newsim") inlets 1.0 receivers 1.0 outlets 1.0 senders 1.0
Setting
deploymode
to obs means that a node receives simulated values (from group outlets or senders) but provides observed values (to group inlets or receivers):>>> test("obs") inlets 2.0 receivers 2.0 outlets 1.0 senders 1.0
With
deploymode
set to oldsim, the node provides (previously) simulated values (to group inlets or receivers) but does not receive any values. Methodget_double()
just returns a dummyDouble
object initialised to 0.0 in this case (for group outlets or senders):>>> test("oldsim") inlets 1.0 receivers 1.0 outlets 0.0 senders 0.0
Other
Element
input or output groups are not supported:>>> node.get_double("test") Traceback (most recent call last): ... ValueError: Function `get_double` of class `Node` does not support the given group name `test`.
- reset(idx: int = 0) None [source]¶
Reset the actual value of the simulation sequence to zero.
>>> from hydpy import Node >>> node = Node("node1") >>> node.sequences.sim = 1.0 >>> node.reset() >>> node.sequences.sim sim(0.0)
- prepare_allseries(allocate_ram: bool = True, jit: bool = False) None [source]¶
Call method
prepare_simseries()
with write_jit=jit and methodprepare_obsseries()
with read_jit=jit.
- prepare_simseries(allocate_ram: bool = True, read_jit: bool = False, write_jit: bool = False) None [source]¶
Call method
prepare_series()
of theSim
sequence object.
- prepare_obsseries(allocate_ram: bool = True, read_jit: bool = False, write_jit: bool = False) None [source]¶
Call method
prepare_series()
of theObs
sequence object.
- plot_allseries(*, labels: Tuple[str, str] | None = None, colors: str | Tuple[str, str] | None = None, linestyles: Literal['-', '--', '-.', ':', 'solid', 'dashed', 'dashdot', 'dotted'] | Tuple[Literal['-', '--', '-.', ':', 'solid', 'dashed', 'dashdot', 'dotted'], Literal['-', '--', '-.', ':', 'solid', 'dashed', 'dashdot', 'dotted']] | None = None, linewidths: int | Tuple[int, int] | None = None, focus: bool = False, stepsize: Literal['daily', 'd', 'monthly', 'm'] | None = None) Figure [source]¶
Plot the
series
data of both theSim
and theObs
sequence object.We demonstrate the functionalities of method
plot_allseries()
based on the Lahn example project:>>> from hydpy.examples import prepare_full_example_2 >>> hp, pub, _ = prepare_full_example_2(lastdate="1997-01-01")
We perform a simulation run and calculate “observed” values for node dill:
>>> hp.simulate() >>> dill = hp.nodes.dill >>> dill.sequences.obs.series = dill.sequences.sim.series + 10.0
A call to method
plot_allseries()
prints the time-series of both sequences to the screen immediately (if not, you need to activate the interactive mode of matplotlib first):>>> figure = dill.plot_allseries()
Subsequent calls to
plot_allseries()
or the related methodsplot_simseries()
andplot_obsseries()
of nodes add further time-series data to the existing plot:>>> lahn_1 = hp.nodes.lahn_1 >>> figure = lahn_1.plot_simseries()
You can modify the appearance of the lines by passing different arguments:
>>> lahn_1.sequences.obs.series = lahn_1.sequences.sim.series + 10.0 >>> figure = lahn_1.plot_obsseries(color="black", linestyle="dashed")
All mentioned plotting functions return a
matplotlib
Figure
object. Use it for further plot handling, e.g. adding a title and saving the current figure to disk:>>> from hydpy.core.testtools import save_autofig >>> text = figure.axes[0].set_title('daily') >>> save_autofig("Node_plot_allseries_1.png", figure)
You can plot the data in an aggregated manner (see the documentation on the function
aggregate_series()
for the supported step sizes and further details):>>> figure = dill.plot_allseries(stepsize="monthly") >>> text = figure.axes[0].set_title('monthly') >>> save_autofig("Node_plot_allseries_2.png", figure)
You can restrict the plotted period via the
eval_
Timegrid
and overwrite the time-series label and other defaults via keyword arguments. For tuples passed to methodplot_allseries()
, the first entry corresponds to the observation and the second one to the simulation results:>>> pub.timegrids.eval_.dates = "1996-10-01", "1996-11-01" >>> figure = lahn_1.plot_allseries(labels=("measured", "calculated"), ... colors=("blue", "red"), ... linewidths=2, ... linestyles=("--", ":"), ... focus=True,) >>> save_autofig("Node_plot_allseries_3.png", figure)
When necessary, all plotting methods raise errors like the following:
>>> figure = lahn_1.plot_allseries(stepsize="quaterly") Traceback (most recent call last): ... ValueError: While trying to plot the time series of sequence(s) obs and sim of node `lahn_1` for the period `1996-10-01 00:00:00` to `1996-11-01 00:00:00`, the following error occurred: While trying to aggregate the given series, the following error occurred: Argument `stepsize` received value `quaterly`, but only the following ones are supported: `monthly` (default) and `daily`.
>>> from hydpy import pub >>> del pub.timegrids >>> figure = lahn_1.plot_allseries() Traceback (most recent call last): ... hydpy.core.exceptiontools.AttributeNotReady: While trying to plot the time series of sequence(s) obs and sim of node `lahn_1` , the following error occurred: Attribute timegrids of module `pub` is not defined at the moment.
- plot_simseries(*, label: str | None = None, color: str | None = None, linestyle: Literal['-', '--', '-.', ':', 'solid', 'dashed', 'dashdot', 'dotted'] | None = None, linewidth: int | None = None, focus: bool = False, stepsize: Literal['daily', 'd', 'monthly', 'm'] | None = None) Figure [source]¶
Plot the
series
of theSim
sequence object.See method
plot_allseries()
for further information.
- plot_obsseries(*, label: str | None = None, color: str | None = None, linestyle: Literal['-', '--', '-.', ':', 'solid', 'dashed', 'dashdot', 'dotted'] | None = None, linewidth: int | None = None, focus: bool = False, stepsize: Literal['daily', 'd', 'monthly', 'm'] | None = None) Figure [source]¶
Plot the
series
of theObs
sequence object.See method
plot_allseries()
for further information.
- class hydpy.core.devicetools.Element(value: Device | str, *args: object, **kwargs: object)[source]¶
Bases:
Device
- Handles a
Model
object and connects it to other models via Node
objects.When preparing
Element
objects, one links them to nodes of different “groups”, each group of nodes implemented as an immutableNodes
object:inlets
andoutlets
nodes handle, for example, the inflow to and the outflow from the respective element.receivers
andsenders
nodes are thought for information flow between arbitrary elements, for example, to inform adam
model about the discharge at a gauge downstream.inputs
nodes provide optional input information, for example, interpolated precipitation that could alternatively be read from files as well.outputs
nodes query optional output information, for example, the water level of a dam.
You can select the relevant nodes either by passing them explicitly or passing their name both as single objects or as objects contained within an iterable object:
>>> from hydpy import Element, Node >>> Element("test", ... inlets="inl1", ... outlets=Node("outl1"), ... receivers=("rec1", Node("rec2"))) Element("test", inlets="inl1", outlets="outl1", receivers=["rec1", "rec2"])
Repeating such a statement with different nodes adds them to the existing ones without any conflict in case of repeated specifications:
>>> Element("test", ... inlets="inl1", ... receivers=("rec2", "rec3"), ... senders="sen1", ... inputs="inp1", ... outputs="outp1") Element("test", inlets="inl1", outlets="outl1", receivers=["rec1", "rec2", "rec3"], senders="sen1", inputs="inp1", outputs="outp1")
Subsequent adding of nodes also works via property access:
>>> test = Element("test") >>> test.inlets = "inl2" >>> test.outlets = None >>> test.receivers = () >>> test.senders = "sen2", Node("sen3") >>> test.inputs = [] >>> test.outputs = Node("outp2") >>> test Element("test", inlets=["inl1", "inl2"], outlets="outl1", receivers=["rec1", "rec2", "rec3"], senders=["sen1", "sen2", "sen3"], inputs="inp1", outputs=["outp1", "outp2"])
The properties try to verify that all connections make sense. For example, an element should never handle an inlet node that it also handles as an outlet, input, or output node:
>>> test.inlets = "outl1" Traceback (most recent call last): ... ValueError: For element `test`, the given inlet node `outl1` is already defined as a(n) outlet node, which is not allowed.
>>> test.inlets = "inp1" Traceback (most recent call last): ... ValueError: For element `test`, the given inlet node `inp1` is already defined as a(n) input node, which is not allowed.
>>> test.inlets = "outp1" Traceback (most recent call last): ... ValueError: For element `test`, the given inlet node `outp1` is already defined as a(n) output node, which is not allowed.
Similar holds for the outlet nodes:
>>> test.outlets = "inl1" Traceback (most recent call last): ... ValueError: For element `test`, the given outlet node `inl1` is already defined as a(n) inlet node, which is not allowed.
>>> test.outlets = "inp1" Traceback (most recent call last): ... ValueError: For element `test`, the given outlet node `inp1` is already defined as a(n) input node, which is not allowed.
>>> test.outlets = "outp1" Traceback (most recent call last): ... ValueError: For element `test`, the given outlet node `outp1` is already defined as a(n) output node, which is not allowed.
The following restrictions hold for the sender nodes:
>>> test.senders = "rec1" Traceback (most recent call last): ... ValueError: For element `test`, the given sender node `rec1` is already defined as a(n) receiver node, which is not allowed.
>>> test.senders = "inp1" Traceback (most recent call last): ... ValueError: For element `test`, the given sender node `inp1` is already defined as a(n) input node, which is not allowed.
>>> test.senders = "outp1" Traceback (most recent call last): ... ValueError: For element `test`, the given sender node `outp1` is already defined as a(n) output node, which is not allowed.
The following restrictions hold for the receiver nodes:
>>> test.receivers = "sen1" Traceback (most recent call last): ... ValueError: For element `test`, the given receiver node `sen1` is already defined as a(n) sender node, which is not allowed.
>>> test.receivers = "inp1" Traceback (most recent call last): ... ValueError: For element `test`, the given receiver node `inp1` is already defined as a(n) input node, which is not allowed.
>>> test.receivers = "outp1" Traceback (most recent call last): ... ValueError: For element `test`, the given receiver node `outp1` is already defined as a(n) output node, which is not allowed.
The following restrictions hold for the input nodes:
>>> test.inputs = "outp1" Traceback (most recent call last): ... ValueError: For element `test`, the given input node `outp1` is already defined as a(n) output node, which is not allowed.
>>> test.inputs = "inl1" Traceback (most recent call last): ... ValueError: For element `test`, the given input node `inl1` is already defined as a(n) inlet node, which is not allowed.
>>> test.inputs = "outl1" Traceback (most recent call last): ... ValueError: For element `test`, the given input node `outl1` is already defined as a(n) outlet node, which is not allowed.
>>> test.inputs = "sen1" Traceback (most recent call last): ... ValueError: For element `test`, the given input node `sen1` is already defined as a(n) sender node, which is not allowed.
>>> test.inputs = "rec1" Traceback (most recent call last): ... ValueError: For element `test`, the given input node `rec1` is already defined as a(n) receiver node, which is not allowed.
The following restrictions hold for the output nodes:
>>> test.outputs = "inp1" Traceback (most recent call last): ... ValueError: For element `test`, the given output node `inp1` is already defined as a(n) input node, which is not allowed.
>>> test.outputs = "inl1" Traceback (most recent call last): ... ValueError: For element `test`, the given output node `inl1` is already defined as a(n) inlet node, which is not allowed.
>>> test.outputs = "outl1" Traceback (most recent call last): ... ValueError: For element `test`, the given output node `outl1` is already defined as a(n) outlet node, which is not allowed.
>>> test.outputs = "sen1" Traceback (most recent call last): ... ValueError: For element `test`, the given output node `sen1` is already defined as a(n) sender node, which is not allowed.
>>> test.outputs = "rec1" Traceback (most recent call last): ... ValueError: For element `test`, the given output node `rec1` is already defined as a(n) receiver node, which is not allowed.
Note that the discussed
Nodes
objects are immutable by default, disallowing to change them in other ways as described above:>>> test.inlets += "inl3" Traceback (most recent call last): ... RuntimeError: While trying to add the device `inl3` to a Nodes object, the following error occurred: Adding devices to immutable Nodes objects is not allowed.
Setting their mutable flag to
True
changes this behaviour:>>> test.inlets.mutable = True >>> test.inlets.add_device("inl3")
However, it is up to you to make sure that the added node also handles the relevant element in the suitable group. In the discussed example, only node inl2 has been added properly but not node inl3:
>>> test.inlets.inl2.exits Elements("test") >>> test.inlets.inl3.exits Elements()
- property inlets: Nodes¶
Group of
Node
objects from which the handledModel
object queries its “upstream” input values (e.g. inflow).
- property outlets: Nodes¶
Group of
Node
objects to which the handledModel
object passes its “downstream” output values (e.g. outflow).
- property receivers: Nodes¶
Group of
Node
objects from which the handledModel
object queries its “remote” information values (e.g. discharge at a remote downstream).
- property senders: Nodes¶
Group of
Node
objects to which the handledModel
object passes its “remote” information values (e.g. water level of adam
model).
- property inputs: Nodes¶
Group of
Node
objects from which the handledModel
object queries its “external” input values, instead of reading them from files (e.g. interpolated precipitation).
- property outputs: Nodes¶
Group of
Node
objects to which the handledModel
object passes its “internal” output values, available via sequences of typeFluxSequence
orStateSequence
(e.g. potential evaporation).
- property model: modeltools.Model¶
The
Model
object handled by the actualElement
object.Directly after their initialisation, elements do not know which model they require:
>>> from hydpy import attrready, Element >>> hland = Element("hland", outlets="outlet") >>> hland.model Traceback (most recent call last): ... hydpy.core.exceptiontools.AttributeNotReady: The model object of element `hland` has been requested but not been prepared so far.
During scripting and when working interactively in the Python shell, it is often convenient to assign a
Model
directly.>>> from hydpy.models.hland_v1 import * >>> parameterstep("1d") >>> hland.model = model >>> hland.model.name 'hland_v1'
>>> del hland.model >>> attrready(hland, "model") False
For the “usual” approach to prepare models, please see the method
prepare_model()
.The following examples show that assigning
Model
objects to propertymodel
creates some connection required by the respective model type automatically. These examples should be relevant for developers only.The following
hbranch
model branches a single input value (from to node inp) to multiple outputs (nodes out1 and out2):>>> from hydpy import Element, Node, reverse_model_wildcard_import, pub >>> reverse_model_wildcard_import() >>> pub.timegrids = "2000-01-01", "2000-01-02", "1d" >>> element = Element("a_branch", ... inlets="branch_input", ... outlets=("branch_output_1", "branch_output_2")) >>> inp = element.inlets.branch_input >>> out1, out2 = element.outlets >>> from hydpy.models.hbranch import * >>> parameterstep() >>> delta(0.0) >>> minimum(0.0) >>> xpoints(0.0, 3.0) >>> ypoints(branch_output_1=[0.0, 1.0], branch_output_2=[0.0, 2.0]) >>> parameters.update() >>> element.model = model
To show that the inlet and outlet connections are built properly, we assign a new value to the inlet node inp and verify that the suitable fractions of this value are passed to the outlet nodes out1` and out2 by calling the method
simulate()
:>>> inp.sequences.sim = 999.0 >>> model.simulate(0) >>> fluxes.originalinput originalinput(999.0) >>> out1.sequences.sim sim(333.0) >>> out2.sequences.sim sim(666.0)
- prepare_model(clear_registry: bool = True) None [source]¶
Load the control file of the actual
Element
object, initialise itsModel
object, build the required connections via (an eventually overridden version of) methodconnect()
of classModel
, and update its derived parameter values via calling (an eventually overridden version) of methodupdate()
of classParameters
.See method
prepare_models()
of classHydPy
and propertyModel
of classElement
fur further information.
- init_model(clear_registry: bool = True) None [source]¶
Deprecated: use method
prepare_model()
instead.>>> from hydpy import Element >>> from unittest import mock >>> with mock.patch.object(Element, "prepare_model") as mocked: ... element = Element("test") ... element.init_model(False) Traceback (most recent call last): ... hydpy.core.exceptiontools.HydPyDeprecationWarning: Method `init_model` of class `Element` is deprecated. Use method `prepare_model` instead. >>> mocked.call_args_list [call(False)]
- property variables: Set[NodeVariableType]¶
A set of all different
variable
values of theNode
objects directly connected to the actualElement
object.Suppose there is an element connected to five nodes, which (partly) represent different variables:
>>> from hydpy import Element, Node >>> element = Element("Test", ... inlets=(Node("N1", "X"), Node("N2", "Y1")), ... outlets=(Node("N3", "X"), Node("N4", "Y2")), ... receivers=(Node("N5", "X"), Node("N6", "Y3")), ... senders=(Node("N7", "X"), Node("N8", "Y4")))
Property
variables
puts all the different variables of these nodes together:>>> sorted(element.variables) ['X', 'Y1', 'Y2', 'Y3', 'Y4']
- prepare_allseries(allocate_ram: bool = True, jit: bool = False) None [source]¶
Call method
prepare_inputseries()
with read_jit=jit and methodsprepare_factorseries()
,prepare_fluxseries()
, andprepare_stateseries()
with write_jit=jit.
- prepare_inputseries(allocate_ram: bool = True, read_jit: bool = False, write_jit: bool = False) None [source]¶
Call method
prepare_series()
of allInputSequence
objects of the currently handledModel
instance.
- prepare_factorseries(allocate_ram: bool = True, write_jit: bool = False) None [source]¶
Call method
prepare_series()
of allFactorSequence
objects of the currently handledModel
instance.
- prepare_fluxseries(allocate_ram: bool = True, write_jit: bool = False) None [source]¶
Call method
prepare_series()
of allFluxSequence
objects of the currently handledModel
instance.
- prepare_stateseries(allocate_ram: bool = True, write_jit: bool = False) None [source]¶
Call method
prepare_series()
of allStateSequence
objects of the currently handledModel
instance.
- plot_inputseries(names: Sequence[str] | None = None, *, average: bool = False, labels: Tuple[str, ...] | None = None, colors: str | Tuple[str, ...] | None = None, linestyles: Literal['-', '--', '-.', ':', 'solid', 'dashed', 'dashdot', 'dotted'] | Tuple[Literal['-', '--', '-.', ':', 'solid', 'dashed', 'dashdot', 'dotted'], ...] | None = None, linewidths: int | Tuple[int, ...] | None = None, focus: bool = True) Figure [source]¶
Plot (the selected)
InputSequence
series
values.We demonstrate the functionalities of method
plot_inputseries()
based on the Lahn example project:>>> from hydpy.examples import prepare_full_example_2 >>> hp, pub, _ = prepare_full_example_2(lastdate="1997-01-01")
Without any arguments,
plot_inputseries()
prints the time-series of all input sequences handled by itsModel
object directly to the screen (in our exampleP
,T
,TN
, andEPN
of application modelhland_v1
):>>> land = hp.elements.land_dill >>> figure = land.plot_inputseries()
You can use the pyplot API of matplotlib to modify the returned figure or to save it to disk (or print it to the screen, in case the interactive mode of matplotlib is disabled):
>>> from hydpy.core.testtools import save_autofig >>> save_autofig("Element_plot_inputseries.png", figure)
Methods
plot_factorseries()
,plot_fluxseries()
, andplot_stateseries()
work in the same manner. Before applying them, one has to calculate the time-series of theFactorSequence
,FluxSequence
, andStateSequence
objects:>>> hp.simulate()
All three methods allow selecting specific sequences by passing their names (here, flux sequences
Q0
andQ1
ofhland_v1
). Additionally, you can pass general or individual values to the arguments labels, colors, linestyles, and linewidths:>>> figure = land.plot_fluxseries( ... ["q0", "q1"], labels=("direct runoff", "base flow"), ... colors=("red", "green"), linestyles="--", linewidths=2) >>> save_autofig("Element_plot_fluxseries.png", figure)
For 1- and 2-dimensional
IOSequence
objects, all three methods plot the individual time-series in the same colour. We demonstrate this for the frozen (SP
) and the liquid (WC
) water equivalent of the snow cover of different hydrological response units. Therefore, we restrict the shown period to February and March via theeval_
time-grid:>>> with pub.timegrids.eval_(firstdate="1996-02-01", lastdate="1996-04-01"): ... figure = land.plot_stateseries(["sp", "wc"]) >>> save_autofig("Element_plot_stateseries.png", figure)
Alternatively, you can print the averaged time-series by assigning
True
to the argument average. We demonstrate this functionality for the factor sequenceTC
(this time, without focusing on the time-series y-extent):>>> figure = land.plot_factorseries(["tc"], colors=("grey",)) >>> figure = land.plot_factorseries( ... ["tc"], average=True, focus=False, colors="black", linewidths=3) >>> save_autofig("Element_plot_factorseries.png", figure)
- plot_factorseries(names: Sequence[str] | None = None, *, average: bool = False, labels: Tuple[str, ...] | None = None, colors: str | Tuple[str, ...] | None = None, linestyles: Literal['-', '--', '-.', ':', 'solid', 'dashed', 'dashdot', 'dotted'] | Tuple[Literal['-', '--', '-.', ':', 'solid', 'dashed', 'dashdot', 'dotted'], ...] | None = None, linewidths: int | Tuple[int, ...] | None = None, focus: bool = True) Figure [source]¶
Plot the factor series of the handled model.
See the documentation on method
plot_inputseries()
for additional information.
- plot_fluxseries(names: Sequence[str] | None = None, *, average: bool = False, labels: Tuple[str, ...] | None = None, colors: str | Tuple[str, ...] | None = None, linestyles: Literal['-', '--', '-.', ':', 'solid', 'dashed', 'dashdot', 'dotted'] | Tuple[Literal['-', '--', '-.', ':', 'solid', 'dashed', 'dashdot', 'dotted'], ...] | None = None, linewidths: int | Tuple[int, ...] | None = None, focus: bool = True) Figure [source]¶
Plot the flux series of the handled model.
See the documentation on method
plot_inputseries()
for additional information.
- plot_stateseries(names: Sequence[str] | None = None, *, average: bool = False, labels: Tuple[str, ...] | None = None, colors: str | Tuple[str, ...] | None = None, linestyles: Literal['-', '--', '-.', ':', 'solid', 'dashed', 'dashdot', 'dotted'] | Tuple[Literal['-', '--', '-.', ':', 'solid', 'dashed', 'dashdot', 'dotted'], ...] | None = None, linewidths: int | Tuple[int, ...] | None = None, focus: bool = True) Figure [source]¶
Plot the state series of the handled model.
See the documentation on method
plot_inputseries()
for additional information.
- Handles a
- hydpy.core.devicetools.clear_registries_temporarily() Generator[None, None, None] [source]¶
Context manager for clearing the current
Node
,Element
, andFusedVariable
registries.Function
clear_registries_temporarily()
is only available for testing purposes.These are the relevant registries for the currently initialised
Node
,Element
, andFusedVariable
objects:>>> from hydpy.core import devicetools >>> registries = (devicetools._id2devices, ... devicetools._registry[devicetools.Node], ... devicetools._registry[devicetools.Element], ... devicetools._selection[devicetools.Node], ... devicetools._selection[devicetools.Element], ... devicetools._registry_fusedvariable)
We first clear them and, just for testing, insert some numbers:
>>> for idx, registry in enumerate(registries): ... registry.clear() ... registry[idx] = idx+1
Within the with block, all registries are empty:
>>> with devicetools.clear_registries_temporarily(): ... for registry in registries: ... print(registry) {} {} {} {} {} {}
Before leaving the with block, the
clear_registries_temporarily()
method restores the contents of each dictionary:>>> for registry in registries: ... print(registry) ... registry.clear() {0: 1} {1: 2} {2: 3} {3: 4} {4: 5} {5: 6}