xmltools¶

This module provides features for executing HydPy workflows based on XML configuration files.

At the heart of module xmltools lies function run_simulation(), which is thought to be applied via a command line (see the documentation on script hyd for further information). run_simulation() expects that the HydPy project you want to work with is available in your current working directory and contains an XML configuration file (as single_run.xml in the example project folder LahnH). This configuration file must agree with the XML schema file HydPyConfigSingleRun.xsd, which is available in the Configuration Tools subpackage and also downloadable for each HydPy release. In case you did implement new or changed existing models, you have to update this schema file. HydPy does this automatically through its setup mechanism (see the documentation on class XSDWriter).

To show how to apply run_simulation() via a command line, we first copy the LahnH project into the iotesting folder via calling function prepare_full_example_1():

>>> from hydpy.examples import prepare_full_example_1
>>> prepare_full_example_1()

Running the simulation requires defining the main script (hyd.py), the function specifying the actual workflow (run_simulation), the name of the project of interest (LahnH), and the name of the relevant XMK configuration file (single_run.xml). To simulate using the command line, we pass the required text to function run_subprocess():

>>> from hydpy import run_subprocess, TestIO
>>> import subprocess
>>> with TestIO():    
...     result = run_subprocess("hyd.py run_simulation LahnH single_run.xml")
Start HydPy project `LahnH` (...).
Read configuration file `single_run.xml` (...).
Interpret the defined options (...).
Interpret the defined period (...).
Read all network files (...).
Activate the selected network (...).
Read the required control files (...).
Read the required condition files (...).
Read the required time series files (...).
Perform the simulation run (...).
Write the desired condition files (...).
Write the desired time series files (...).

As defined by the XML configuration file, the simulation started on the first and ended at the sixths January 1996. The following example shows the read initial conditions and the written final conditions of sequence SM for the 12 hydrological response units of the subcatchment land_dill:

>>> with TestIO():
...     filepath = "LahnH/conditions/init_1996_01_01_00_00_00/land_dill.py"
...     with open(filepath) as file_:
...         print("".join(file_.readlines()[10:12]))
...     filepath = "LahnH/conditions/init_1996_01_06/land_dill.py"
...     with open(filepath) as file_:
...         print("".join(file_.readlines()[9:12]))
sm(185.13164, 181.18755, 199.80432, 196.55888, 212.04018, 209.48859,
   222.12115, 220.12671, 230.30756, 228.70779, 236.91943, 235.64427)

sm(183.873078, 179.955801, 198.446011, 195.222634, 210.598689,
   208.064445, 220.611126, 218.630245, 228.741883, 227.152989,
   235.308805, 234.042313)

The intermediate soil moisture values are stored in a NetCDF file called hland_v1_state_sm.nc:

>>> import numpy
>>> from hydpy import print_values
>>> from hydpy.core.netcdftools import netcdf4, chars2str, query_variable
>>> with TestIO():
...     ncfile = netcdf4.Dataset("LahnH/series/output/hland_v1_state_sm.nc")
...     chars2str(query_variable(ncfile, "station_id"))[:3]
...     print_values(query_variable(ncfile, "state_sm")[:, 0])
['land_dill_0', 'land_dill_1', 'land_dill_2']
184.926173, 184.603966, 184.386666, 184.098541, 183.873078
>>> ncfile.close()

Spatially averaged time series values are stored in files ending with the suffix _mean:

>>> with TestIO(clear_all=True):
...     print_values((numpy.load(
...         "LahnH/series/output/lahn_1_sim_q_mean.npy")[13:]))
9.647824, 8.517795, 7.781311, 7.344944, 7.153142

Module xmltools implements the following members:

find() Return the first XML element with the given name found in the given XML root.

strip() Remove the XML namespace from the given string and return it.

run_simulation() Perform a HydPy workflow in agreement with the given XML configuration file available in the directory of the given project. ToDo

XMLBase Base class for the concrete classes XMLInterface, XMLConditions, XMLSeries, and XMLSubseries.

XMLInterface An interface to XML configuration files that are valid concerning schema file HydPyConfigSingleRun.xsd or HydPyConfigMultipleRuns.xsd.

XMLConditions Helper class for XMLInterface responsible for loading and saving initial conditions.

XMLSeries Helper class for XMLInterface responsible for loading and saving time series data, which is further delegated to suitable instances of class XMLSubseries.

XMLSelector ToDo

XMLSubseries Helper class for XMLSeries responsible for loading and saving time series data.

XMLExchange Helper class for XMLInterface responsible for interpreting exchange items, accessible via different instances of class XMLItemgroup.

XMLItemgroup Helper class for XMLExchange responsible for handling the exchange items related to model parameter and sequences separately from the exchange items of node sequences.

XMLModel Helper class for XMLItemgroup responsible for handling the exchange items related to different parameter or sequence groups of Model objects.

XMLSubvars Helper class for XMLModel responsible for handling the exchange items related to individual parameters or sequences of Model objects.

XMLNode Helper class for XMLItemgroup responsible for handling the exchange items related to individual parameters or sequences of Node objects.

XMLVar Helper class for XMLSubvars and XMLNode responsible for creating a defined exchange item.

XSDWriter A pure classmethod class for writing the actual XML schema file HydPyConfigBase.xsd, which makes sure that an XML configuration file is readable by class XMLInterface.

hydpy.auxs.xmltools.find(root: xml.etree.ElementTree.Element, name: str, optional: typing_extensions.Literal[True, False] = True) → Optional[xml.etree.ElementTree.Element][source]¶

Return the first XML element with the given name found in the given XML root.

>>> from hydpy.auxs.xmltools import find, XMLInterface
>>> from hydpy.data import make_filepath
>>> interface = XMLInterface("single_run.xml", make_filepath("LahnH"))
>>> find(interface.root, "timegrid").tag.endswith("timegrid")
True

By default, function find() returns None in case the required element is missing:

>>> find(interface.root, "wrong")

Set the argument optional to False to let function find() raise errors instead:

>>> find(interface.root, "wrong", optional=False)
Traceback (most recent call last):
...
AttributeError: The actual XML element `config` does not define a XML subelement named `wrong`.  Please make sure your XML file follows the relevant XML schema.

hydpy.auxs.xmltools.strip(name: str) → str [source]¶

Remove the XML namespace from the given string and return it.

>>> from hydpy.auxs.xmltools import strip
>>> strip("{https://github.com/something.xsd}something")
'something'

hydpy.auxs.xmltools.run_simulation(projectname: str, xmlfile: str) → None [source]¶

Perform a HydPy workflow in agreement with the given XML configuration file available in the directory of the given project. ToDo

Function run_simulation() is a “script function” and is normally used as explained in the main documentation on module xmltools.

class hydpy.auxs.xmltools.XMLBase[source]¶

Bases: object

Base class for the concrete classes XMLInterface, XMLConditions, XMLSeries, and XMLSubseries.

Subclasses of XMLBase support iterating XML subelements, while skipping those named selections or devices:

>>> from hydpy.auxs.xmltools import XMLInterface
>>> from hydpy.data import make_filepath
>>> interface = XMLInterface("multiple_runs.xml", make_filepath("LahnH"))
>>> itemgroup = interface.exchange.itemgroups[1]
>>> for element in itemgroup:
...     print(strip(element.tag))
hland_v1
>>> for element in itemgroup.models[0].subvars[0].vars[0]:
...     print(strip(element.tag))
alias
dim
init

root: xml.etree.ElementTree.Element¶

property name¶

Apply function strip() to the root of the object of the XMLBase subclass.

>>> from hydpy.auxs.xmltools import XMLInterface
>>> from hydpy.data import make_filepath
>>> interface = XMLInterface("single_run.xml", make_filepath("LahnH"))
>>> interface.name
'config'
>>> interface.series_io.readers[0].name
'reader'

find(name: str, optional: typing_extensions.Literal[True, False] = True) → Optional[xml.etree.ElementTree.Element][source]¶

Apply function find() to the root of the object of the XMLBase subclass.

>>> from hydpy.auxs.xmltools import XMLInterface
>>> from hydpy.data import make_filepath
>>> interface = XMLInterface("single_run.xml", make_filepath("LahnH"))
>>> interface.find("timegrid").tag.endswith("timegrid")
True

>>> interface.find("wrong")

>>> interface.find("wrong", optional=False)
Traceback (most recent call last):
...
AttributeError: The actual XML element `config` does not define a XML subelement named `wrong`.  Please make sure your XML file follows the relevant XML schema.

class hydpy.auxs.xmltools.XMLInterface(filename: str, directory: Optional[str] = None)[source]¶

Bases: hydpy.auxs.xmltools.XMLBase

An interface to XML configuration files that are valid concerning: schema file HydPyConfigSingleRun.xsd or HydPyConfigMultipleRuns.xsd.

>>> from hydpy.auxs.xmltools import XMLInterface
>>> from hydpy.data import make_filepath
>>> interface = XMLInterface("single_run.xml", make_filepath("LahnH"))
>>> interface.root.tag
'{https://github.com/hydpy-dev/hydpy/releases/download/your-hydpy-version/HydPyConfigSingleRun.xsd}config'
>>> interface = XMLInterface('multiple_runs.xml', make_filepath('LahnH'))
>>> interface.root.tag
'{https://github.com/hydpy-dev/hydpy/releases/download/your-hydpy-version/HydPyConfigMultipleRuns.xsd}config'
>>> XMLInterface('wrongfilepath.xml', 'wrongdir')    
Traceback (most recent call last):
...
FileNotFoundError: While trying to parse the XML configuration file ...wrongfilepath.xml, the following error occurred: [Errno 2] No such file or directory: '...wrongfilepath.xml'

root: xml.etree.ElementTree.Element¶

validate_xml() → None [source]¶

Raise an error if the actual XML does not agree with one of the available schema files.

# ToDo: should it be accompanied by a script function?

The first example relies on a distorted version of the configuration file single_run.xml:

>>> from hydpy.examples import prepare_full_example_1
>>> prepare_full_example_1()
>>> from hydpy import TestIO, xml_replace
>>> from hydpy.auxs.xmltools import XMLInterface
>>> import os
>>> with TestIO():    
...     xml_replace("LahnH/single_run",
...                 firstdate="1996-01-32T00:00:00")
template file: LahnH/single_run.xmlt
target file: LahnH/single_run.xml
replacements:
  config_start --> <...HydPyConfigBase.xsd"
              ...HydPyConfigSingleRun.xsd"> (default argument)
  firstdate --> 1996-01-32T00:00:00 (given argument)
  zip_ --> false (default argument)
  zip_ --> false (default argument)
  config_end --> </hpcsr:config> (default argument)
>>> with TestIO():
...     interface = XMLInterface("single_run.xml", "LahnH")
>>> interface.validate_xml()    
Traceback (most recent call last):
...
xmlschema.validators.exceptions.XMLSchemaDecodeError: While trying to validate XML file `...single_run.xml`, the following error occurred: failed validating '1996-01-32T00:00:00' with XsdAtomicBuiltin(name='xs:dateTime')...
...
Reason: day is out of range for month
...
Schema:
...
Instance:
...
  <firstdate xmlns="https://github.com/hydpy-dev/hydpy/releases/download/your-hydpy-version/HydPyConfigBase.xsd">1996-01-32T00:00:00</firstdate>
...
Path: /hpcsr:config/timegrid/firstdate
...

In the second example, we examine a correct configuration file:

>>> with TestIO():    
...     xml_replace("LahnH/single_run")
...     interface = XMLInterface("single_run.xml", "LahnH")
template file: LahnH/single_run.xmlt
target file: LahnH/single_run.xml
replacements:
  config_start --> <...HydPyConfigBase.xsd"
              ...HydPyConfigSingleRun.xsd"> (default argument)
  firstdate --> 1996-01-01T00:00:00 (default argument)
  zip_ --> false (default argument)
  zip_ --> false (default argument)
  config_end --> </hpcsr:config> (default argument)
>>> interface.validate_xml()

The XML configuration file must correctly refer to the corresponding schema file:

>>> with TestIO():    
...     xml_replace("LahnH/single_run",
...                 config_start="<config>",
...                 config_end="</config>")
...     interface = XMLInterface("single_run.xml", "LahnH")
template file: LahnH/single_run.xmlt
target file: LahnH/single_run.xml
replacements:
  config_start --> <config> (given argument)
  firstdate --> 1996-01-01T00:00:00 (default argument)
  zip_ --> false (default argument)
  zip_ --> false (default argument)
  config_end --> </config> (given argument)
>>> interface.validate_xml()    
Traceback (most recent call last):
...
RuntimeError: While trying to validate XML file `...single_run.xml`, the following error occurred: Configuration file `single_run.xml` does not correctly refer to one of the available XML schema files (HydPyConfigSingleRun.xsd and HydPyConfigMultipleRuns.xsd).

XML files based on HydPyConfigMultipleRuns.xsd can be validated as well:

>>> with TestIO():
...     interface = XMLInterface("multiple_runs.xml", "LahnH")
>>> interface.validate_xml()    

update_options() → None [source]¶

Update the Options object available in module pub with the values defined in the options XML element.

>>> from hydpy.auxs.xmltools import XMLInterface
>>> from hydpy import pub
>>> from hydpy.data import make_filepath
>>> interface = XMLInterface("single_run.xml", make_filepath("LahnH"))
>>> pub.options.ellipsis = 0
>>> pub.options.parameterstep = "1h"
>>> pub.options.printprogress = True
>>> pub.options.printincolor = True
>>> pub.options.reprdigits = -1
>>> pub.options.utcoffset = -60
>>> pub.options.warnsimulationstep = 0
>>> interface.update_options()
>>> pub.options
Options(
    autocompile -> 1
    checkseries -> 1
    dirverbose -> 0
    ellipsis -> 0
    flattennetcdf -> 1
    forcecompiling -> 0
    isolatenetcdf -> 1
    parameterstep -> Period("1d")
    printprogress -> 0
    printincolor -> 0
    reprcomments -> 0
    reprdigits -> 6
    simulationstep -> Period()
    skipdoctests -> 0
    timeaxisnetcdf -> 0
    trimvariables -> 1
    usecython -> 1
    usedefaultvalues -> 0
    utclongitude -> 15
    utcoffset -> 60
    warnmissingcontrolfile -> 0
    warnmissingobsfile -> 1
    warnmissingsimfile -> 1
    warnsimulationstep -> 0
    warntrim -> 1
)
>>> pub.options.printprogress = False
>>> pub.options.reprdigits = 6

update_timegrids() → None [source]¶

Update the Timegrids object available in module pub with the values defined in the timegrid XML element.

Usually, one would prefer to define firstdate, lastdate, and stepsize elements as in the XML configuration file of the LahnH example project:

>>> from hydpy.examples import prepare_full_example_1
>>> prepare_full_example_1()
>>> from hydpy import HydPy, pub, TestIO
>>> from hydpy.auxs.xmltools import XMLInterface

>>> hp = HydPy("LahnH")
>>> with TestIO():
...     hp.prepare_network()
...     XMLInterface("single_run.xml").update_timegrids()
>>> pub.timegrids
Timegrids("1996-01-01T00:00:00",
          "1996-01-06T00:00:00",
          "1d")

Alternatively, one can provide the file path to a seriesfile, which must be a valid NetCDF file. The XMLInterface object then interprets the file’s time information:

>>> name = "LahnH/series/input/hland_v1_input_p.nc"
>>> with TestIO():
...     with open("LahnH/single_run.xml") as file_:
...         lines = file_.readlines()
...     for idx, line in enumerate(lines):
...         if "<timegrid>" in line:
...             break
...     with open("LahnH/single_run.xml", "w") as file_:
...         _ = file_.write("".join(lines[:idx+1]))
...         _ = file_.write(
...             f"        <seriesfile>{name}</seriesfile>\n")
...         _ = file_.write("".join(lines[idx+4:]))
...     XMLInterface("single_run.xml").update_timegrids()
>>> pub.timegrids
Timegrids("1996-01-01 00:00:00",
          "2007-01-01 00:00:00",
          "1d")

property selections¶

The Selections object defined on the main level of the actual XML file.

>>> from hydpy.examples import prepare_full_example_1
>>> prepare_full_example_1()

>>> from hydpy import HydPy, TestIO, XMLInterface
>>> hp = HydPy("LahnH")
>>> with TestIO():
...     hp.prepare_network()
...     interface = XMLInterface("single_run.xml")
>>> interface.find("selections").text = "headwaters streams"
>>> selections = interface.selections
>>> for selection in selections:
...     print(selection.name)
headwaters
streams
>>> selections.headwaters
Selection("headwaters",
          nodes=("dill", "lahn_1"),
          elements=("land_dill", "land_lahn_1"))
>>> interface.find("selections").text = "head_waters"
>>> interface.selections
Traceback (most recent call last):
...
NameError: The XML configuration file tries to define a selection using the text `head_waters`, but the actual project does not  handle such a `Selection` object.

property devices¶

The additional devices defined on the main level of the actual XML file collected by a Selection object.

>>> from hydpy.examples import prepare_full_example_1
>>> prepare_full_example_1()

>>> from hydpy import HydPy, TestIO, XMLInterface
>>> hp = HydPy("LahnH")
>>> with TestIO():
...     hp.prepare_network()
...     interface = XMLInterface("single_run.xml")
>>> interface.devices
Selection("temporary_result_of_xml_parsing",
          nodes="dill",
          elements=("land_dill", "land_lahn_1"))
>>> interface.find("devices").text = "land_lahn1"
>>> interface.devices
Traceback (most recent call last):
...
NameError: The XML configuration file tries to define additional devices using the text `land_lahn1`, but the complete selection of the actual project does neither handle a `Node` or `Element` object with such a name or keyword.

property elements¶

Yield all Element objects returned by selections and devices without duplicates.

>>> from hydpy.examples import prepare_full_example_1
>>> prepare_full_example_1()

>>> from hydpy import HydPy, TestIO, XMLInterface
>>> hp = HydPy("LahnH")
>>> with TestIO():
...     hp.prepare_network()
...     interface = XMLInterface("single_run.xml")
>>> interface.find("selections").text = "headwaters streams"
>>> for element in interface.elements:
...      print(element.name)
land_dill
land_lahn_1
stream_dill_lahn_2
stream_lahn_1_lahn_2
stream_lahn_2_lahn_3

property fullselection¶

A Selection object containing all Element and Node objects defined by selections and devices.

>>> from hydpy.examples import prepare_full_example_1
>>> prepare_full_example_1()

>>> from hydpy import HydPy, TestIO, XMLInterface
>>> hp = HydPy("LahnH")
>>> with TestIO():
...     hp.prepare_network()
...     interface = XMLInterface("single_run.xml")
>>> interface.find("selections").text = "nonheadwaters"
>>> interface.fullselection
Selection("fullselection",
          nodes=("dill", "lahn_2", "lahn_3"),
          elements=("land_dill", "land_lahn_1", "land_lahn_2",
                    "land_lahn_3"))

property conditions_io¶

The condition_io element defined in the actual XML file.

>>> from hydpy.auxs.xmltools import XMLInterface, strip
>>> from hydpy.data import make_filepath
>>> interface = XMLInterface("single_run.xml", make_filepath("LahnH"))
>>> strip(interface.series_io.root.tag)
'series_io'

property series_io¶

The series_io element defined in the actual XML file.

>>> from hydpy.auxs.xmltools import XMLInterface, strip
>>> from hydpy.data import make_filepath
>>> interface = XMLInterface("single_run.xml", make_filepath("LahnH"))
>>> strip(interface.series_io.root.tag)
'series_io'

property exchange¶

The exchange element defined in the actual XML file.

>>> from hydpy.auxs.xmltools import XMLInterface, strip
>>> from hydpy.data import make_filepath
>>> interface = XMLInterface(
...     "multiple_runs.xml", make_filepath("LahnH"))
>>> strip(interface.exchange.root.tag)
'exchange'

class hydpy.auxs.xmltools.XMLConditions(master: hydpy.auxs.xmltools.XMLInterface, root: xml.etree.ElementTree.Element)[source]¶

Bases: hydpy.auxs.xmltools.XMLBase

Helper class for XMLInterface responsible for loading and saving initial conditions.

root: xml.etree.ElementTree.Element¶

load_conditions() → None [source]¶

Load the condition files of the Model objects of all Element objects returned by elements:

>>> from hydpy.examples import prepare_full_example_1
>>> prepare_full_example_1()

>>> from hydpy import HydPy, pub, TestIO, XMLInterface
>>> hp = HydPy("LahnH")
>>> pub.timegrids = "1996-01-01", "1996-01-06", "1d"
>>> with TestIO():
...     hp.prepare_network()
...     hp.prepare_models()
...     interface = XMLInterface("single_run.xml")
...     interface.find("selections").text = "headwaters"
...     interface.conditions_io.load_conditions()
>>> hp.elements.land_lahn_1.model.sequences.states.lz
lz(8.18711)
>>> hp.elements.land_lahn_2.model.sequences.states.lz
lz(nan)

save_conditions() → None [source]¶

Save the condition files of the Model objects of all Element objects returned by elements:

>>> from hydpy.examples import prepare_full_example_1
>>> prepare_full_example_1()

>>> import os
>>> from hydpy import HydPy, pub, TestIO, XMLInterface
>>> hp = HydPy("LahnH")
>>> pub.timegrids = "1996-01-01", "1996-01-06", "1d"
>>> with TestIO():
...     hp.prepare_network()
...     hp.prepare_models()
...     hp.elements.land_dill.model.sequences.states.lz = 999.0
...     interface = XMLInterface("single_run.xml")
...     interface.find("selections").text = "headwaters"
...     interface.conditions_io.save_conditions()
...     dirpath = "LahnH/conditions/init_1996_01_06"
...     with open(os.path.join(dirpath, "land_dill.py")) as file_:
...         print(file_.readlines()[11].strip())
...     os.path.exists(os.path.join(dirpath, "land_lahn_2.py"))
lz(999.0)
False
>>> from hydpy import xml_replace
>>> with TestIO():
...     xml_replace("LahnH/single_run", printflag=False, zip_="true")
...     interface = XMLInterface("single_run.xml")
...     interface.find("selections").text = "headwaters"
...     os.path.exists("LahnH/conditions/init_1996_01_06.zip")
...     interface.conditions_io.save_conditions()
...     os.path.exists("LahnH/conditions/init_1996_01_06.zip")
False
True

class hydpy.auxs.xmltools.XMLSeries(master: hydpy.auxs.xmltools.XMLInterface, root: xml.etree.ElementTree.Element)[source]¶

Bases: hydpy.auxs.xmltools.XMLBase

Helper class for XMLInterface responsible for loading and saving time series data, which is further delegated to suitable instances of class XMLSubseries.

root: xml.etree.ElementTree.Element¶

property readers¶

The reader XML elements defined in the actual XML file.

>>> from hydpy.auxs.xmltools import XMLInterface
>>> from hydpy.data import make_filepath
>>> interface = XMLInterface("single_run.xml", make_filepath("LahnH"))
>>> for reader in interface.series_io.readers:
...     print(reader.info)
all input data

property writers¶

The writer XML elements defined in the actual XML file.

>>> from hydpy.auxs.xmltools import XMLInterface
>>> from hydpy.data import make_filepath
>>> interface = XMLInterface("single_run.xml", make_filepath("LahnH"))
>>> for writer in interface.series_io.writers:
...     print(writer.info)
precipitation
soilmoisture
averaged

prepare_series() → None [source]¶

Call prepare_series() of all XMLSubseries objects with the same memory set object.

>>> from hydpy.auxs.xmltools import XMLInterface, XMLSubseries
>>> from hydpy.data import make_filepath
>>> interface = XMLInterface("single_run.xml", make_filepath("LahnH"))
>>> series_io = interface.series_io
>>> from unittest import mock
>>> prepare_series = XMLSubseries.prepare_series
>>> XMLSubseries.prepare_series = mock.MagicMock()
>>> series_io.prepare_series()
>>> args = XMLSubseries.prepare_series.call_args_list
>>> len(args) == len(series_io.readers) + len(series_io.writers)
True
>>> args[0][0][0]
set()
>>> args[0][0][0] is args[-1][0][0]
True
>>> XMLSubseries.prepare_series = prepare_series

load_series() → None [source]¶: Call load_series() of all XMLSubseries objects handles as “readers”.

save_series() → None [source]¶: Call load_series() of all XMLSubseries objects handles as “writers”.

class hydpy.auxs.xmltools.XMLSelector[source]¶

Bases: hydpy.auxs.xmltools.XMLBase

ToDo

master: hydpy.auxs.xmltools.XMLBase¶

root: xml.etree.ElementTree.Element¶

property selections¶

The Selections object defined for the respective reader or writer element of the actual XML file. ToDo

If the reader or writer element does not define a special selections element, the general selections element of XMLInterface is used.

>>> from hydpy.examples import prepare_full_example_1
>>> prepare_full_example_1()

>>> from hydpy import HydPy, pub, TestIO, XMLInterface
>>> hp = HydPy("LahnH")
>>> pub.timegrids = "1996-01-01", "1996-01-06", "1d"
>>> with TestIO():
...     hp.prepare_network()
...     hp.prepare_models()
...     interface = XMLInterface("single_run.xml")
>>> series_io = interface.series_io
>>> for seq in (series_io.readers + series_io.writers):
...     print(seq.info, seq.selections.names)
all input data ()
precipitation ('headwaters',)
soilmoisture ('complete',)
averaged ('complete',)

If property selections does not find the definition of a Selections object, it raises the following error:

>>> interface.root.remove(interface.find("selections"))
>>> series_io = interface.series_io
>>> for seq in (series_io.readers + series_io.writers):
...     print(seq.info, seq.selections.names)
Traceback (most recent call last):
...
AttributeError: Unable to find a XML element named "selections".  Please make sure your XML file follows the relevant XML schema.

property devices¶

The additional devices defined for the respective reader or writer element contained within a Selection object. ToDo

If the reader or writer element does not define its own additional devices, devices of XMLInterface is used.

>>> from hydpy.examples import prepare_full_example_1
>>> prepare_full_example_1()

>>> from hydpy import HydPy, TestIO, XMLInterface
>>> hp = HydPy("LahnH")
>>> with TestIO():
...     hp.prepare_network()
...     interface = XMLInterface("single_run.xml")
>>> series_io = interface.series_io
>>> for seq in (series_io.readers + series_io.writers):
...     print(seq.info, seq.devices.nodes, seq.devices.elements)
all input data Nodes() Elements("land_dill", "land_lahn_1", "land_lahn_2", "land_lahn_3")
precipitation Nodes() Elements("land_lahn_1", "land_lahn_2")
soilmoisture Nodes("dill") Elements("land_dill", "land_lahn_1")
averaged Nodes() Elements()

If property selections does not find the definition of a Selections object, it raises the following error:

>>> interface.root.remove(interface.find("devices"))
>>> series_io = interface.series_io
>>> for seq in (series_io.readers + series_io.writers):
...     print(seq.info, seq.devices.nodes, seq.devices.elements)
Traceback (most recent call last):
...
AttributeError: Unable to find a XML element named "devices".  Please make sure your XML file follows the relevant XML schema.

property elements¶

Return the Element objects selected by the actual reader or writer element. ToDo

>>> from hydpy.examples import prepare_full_example_1
>>> prepare_full_example_1()

>>> from hydpy import HydPy, TestIO, XMLInterface
>>> hp = HydPy("LahnH")
>>> with TestIO():
...     hp.prepare_network()
...     interface = XMLInterface("single_run.xml")
>>> for element in interface.series_io.writers[0].elements:
...     print(element.name)
land_dill
land_lahn_1
land_lahn_2

property nodes¶

Return the Node objects selected by the actual reader or writer element. ToDo

>>> from hydpy.examples import prepare_full_example_1
>>> prepare_full_example_1()

>>> from hydpy import HydPy, TestIO, XMLInterface
>>> hp = HydPy("LahnH")
>>> with TestIO():
...     hp.prepare_network()
...     interface = XMLInterface("single_run.xml")
>>> for node in interface.series_io.writers[0].nodes:
...     print(node.name)
dill
lahn_1

class hydpy.auxs.xmltools.XMLSubseries(master: hydpy.auxs.xmltools.XMLSeries, root: xml.etree.ElementTree.Element)[source]¶

Bases: hydpy.auxs.xmltools.XMLSelector

Helper class for XMLSeries responsible for loading and saving time series data.

master: hydpy.auxs.xmltools.XMLBase¶

root: xml.etree.ElementTree.Element¶

property info¶: Info attribute of the actual XML reader or writer element.

prepare_sequencemanager() → None [source]¶

Configure the SequenceManager object available in module pub following the definitions of the actual XML reader or writer element when available; if not use those of the XML series_io element.

Compare the following results with single_run.xml to see that the first writer element defines the input file type specifically, that the second writer element defines a general file type, and that the third writer element does not define any file type (the principle mechanism is the same for other options, e.g. the aggregation mode):

>>> from hydpy.examples import prepare_full_example_1
>>> prepare_full_example_1()

>>> from hydpy import HydPy, TestIO, XMLInterface, pub
>>> hp = HydPy("LahnH")
>>> with TestIO():
...     hp.prepare_network()
...     interface = XMLInterface("single_run.xml")
>>> series_io = interface.series_io
>>> with TestIO():
...     series_io.writers[0].prepare_sequencemanager()
>>> pub.sequencemanager.inputfiletype
'asc'
>>> pub.sequencemanager.fluxfiletype
'npy'
>>> pub.sequencemanager.fluxaggregation
'none'
>>> with TestIO():
...     series_io.writers[1].prepare_sequencemanager()
>>> pub.sequencemanager.statefiletype
'nc'
>>> pub.sequencemanager.stateoverwrite
False
>>> with TestIO():
...     series_io.writers[2].prepare_sequencemanager()
>>> pub.sequencemanager.statefiletype
'npy'
>>> pub.sequencemanager.fluxaggregation
'mean'
>>> pub.sequencemanager.inputoverwrite
True
>>> pub.sequencemanager.inputdirpath
'LahnH/series/input'

property model2subs2seqs¶

A nested defaultdict containing the model specific information provided by the XML sequences element.

>>> from hydpy.auxs.xmltools import XMLInterface
>>> from hydpy.data import make_filepath
>>> interface = XMLInterface("single_run.xml", make_filepath("LahnH"))
>>> series_io = interface.series_io
>>> model2subs2seqs = series_io.writers[2].model2subs2seqs
>>> for model, subs2seqs in sorted(model2subs2seqs.items()):
...     for subs, seq in sorted(subs2seqs.items()):
...         print(model, subs, seq)
hland_v1 fluxes ['pc', 'tf']
hland_v1 states ['sm']
hstream_v1 states ['qjoints']

property subs2seqs¶

A defaultdict containing the node-specific information provided by XML sequences element.

>>> from hydpy.auxs.xmltools import XMLInterface
>>> from hydpy.data import make_filepath
>>> interface = XMLInterface("single_run.xml", make_filepath("LahnH"))
>>> series_io = interface.series_io
>>> subs2seqs = series_io.writers[2].subs2seqs
>>> for subs, seq in sorted(subs2seqs.items()):
...     print(subs, seq)
node ['sim', 'obs']

prepare_series(memory: Set[hydpy.core.sequencetools.IOSequence]) → None [source]¶

Call activate_ram() of all sequences selected by the given output element of the actual XML file.

Use the memory argument to pass in already prepared sequences; newly prepared sequences will be added.

>>> from hydpy.examples import prepare_full_example_1
>>> prepare_full_example_1()

>>> from hydpy import HydPy, pub, TestIO, XMLInterface
>>> hp = HydPy("LahnH")
>>> pub.timegrids = "1996-01-01", "1996-01-06", "1d"
>>> with TestIO():
...     hp.prepare_network()
...     hp.prepare_models()
...     interface = XMLInterface("single_run.xml")
>>> interface.update_timegrids()
>>> series_io = interface.series_io

>>> memory = set()
>>> pc = hp.elements.land_dill.model.sequences.fluxes.pc
>>> pc.ramflag
False
>>> series_io.writers[0].prepare_series(memory)
>>> pc in memory
True
>>> pc.ramflag
True

>>> pc.deactivate_ram()
>>> pc.ramflag
False
>>> series_io.writers[0].prepare_series(memory)
>>> pc.ramflag
False

load_series() → None [source]¶

Load time series data as defined by the actual XML reader element.

>>> from hydpy.examples import prepare_full_example_1
>>> prepare_full_example_1()

>>> from hydpy import HydPy, pub, TestIO, XMLInterface
>>> hp = HydPy("LahnH")
>>> pub.timegrids = "1996-01-01", "1996-01-06", "1d"
>>> with TestIO():
...     hp.prepare_network()
...     hp.prepare_models()
...     interface = XMLInterface("single_run.xml")
...     interface.update_options()
...     interface.update_timegrids()
...     series_io = interface.series_io
...     series_io.prepare_series()
...     series_io.load_series()
>>> from hydpy import print_values
>>> print_values(
...     hp.elements.land_dill.model.sequences.inputs.t.series[:3])
-0.298846, -0.811539, -2.493848

save_series() → None [source]¶

Save time series data as defined by the actual XML writer element.

>>> from hydpy.examples import prepare_full_example_1
>>> prepare_full_example_1()

>>> from hydpy import HydPy, pub, TestIO, XMLInterface
>>> hp = HydPy("LahnH")
>>> pub.timegrids = "1996-01-01", "1996-01-06", "1d"
>>> with TestIO():
...     hp.prepare_network()
...     hp.prepare_models()
...     interface = XMLInterface("single_run.xml")
...     interface.update_options()
>>> interface.update_timegrids()
>>> series_io = interface.series_io
>>> series_io.prepare_series()
>>> hp.elements.land_dill.model.sequences.fluxes.pc.series[2, 3] = 9.0
>>> hp.nodes.lahn_2.sequences.sim.series[4] = 7.0
>>> with TestIO():
...     series_io.save_series()
>>> import numpy
>>> with TestIO():
...     os.path.exists(
...         "LahnH/series/output/land_lahn_2_flux_pc.npy")
...     os.path.exists(
...         "LahnH/series/output/land_lahn_3_flux_pc.npy")
...     numpy.load(
...         "LahnH/series/output/land_dill_flux_pc.npy")[13+2, 3]
...     numpy.load(
...         "LahnH/series/output/lahn_2_sim_q_mean.npy")[13+4]
True
False
9.0
7.0

class hydpy.auxs.xmltools.XMLExchange(master: hydpy.auxs.xmltools.XMLInterface, root: xml.etree.ElementTree.Element)[source]¶

Bases: hydpy.auxs.xmltools.XMLBase

Helper class for XMLInterface responsible for interpreting exchange items, accessible via different instances of class XMLItemgroup.

root: xml.etree.ElementTree.Element¶

property parameteritems¶

Create and return all items for changing control parameter values.

>>> from hydpy.examples import prepare_full_example_1
>>> prepare_full_example_1()

>>> from hydpy import HydPy, pub, TestIO, XMLInterface
>>> hp = HydPy("LahnH")
>>> pub.timegrids = "1996-01-01", "1996-01-06", "1d"
>>> with TestIO():
...     hp.prepare_everything()
...     interface = XMLInterface("multiple_runs.xml")
>>> for item in interface.exchange.parameteritems:
...     print(item.name)
alpha
beta
lag
damp
sfcf_1
sfcf_2
sfcf_3

property conditionitems¶

Return all items for changing condition sequence values.

>>> from hydpy.examples import prepare_full_example_1
>>> prepare_full_example_1()

>>> from hydpy import HydPy, pub, TestIO, XMLInterface
>>> hp = HydPy("LahnH")
>>> pub.timegrids = "1996-01-01", "1996-01-06", "1d"
>>> with TestIO():
...     hp.prepare_everything()
...     interface = XMLInterface("multiple_runs.xml")
>>> for item in interface.exchange.conditionitems:
...     print(item.name)
sm_lahn_2
sm_lahn_1
quh

property getitems¶

Return all items for querying the current values or the complete time series of sequences.

>>> from hydpy.examples import prepare_full_example_1
>>> prepare_full_example_1()

>>> from hydpy import HydPy, pub, TestIO, XMLInterface
>>> hp = HydPy("LahnH")
>>> pub.timegrids = "1996-01-01", "1996-01-06", "1d"
>>> with TestIO():
...     hp.prepare_everything()
...     interface = XMLInterface("multiple_runs.xml")
>>> for item in interface.exchange.getitems:
...     print(item.target)
fluxes_qt
fluxes_qt_series
states_sm
states_sm_series
nodes_sim_series

prepare_series() → None [source]¶: Prepare all required series arrays via calling method activate_ram().

property itemgroups¶: The relevant XMLItemgroup objects.

class hydpy.auxs.xmltools.XMLItemgroup(master: hydpy.auxs.xmltools.XMLExchange, root: xml.etree.ElementTree.Element)[source]¶

Bases: hydpy.auxs.xmltools.XMLBase

Helper class for XMLExchange responsible for handling the exchange items related to model parameter and sequences separately from the exchange items of node sequences.

root: xml.etree.ElementTree.Element¶

property models¶: The required XMLModel objects.

property nodes¶: The required XMLNode objects.

class hydpy.auxs.xmltools.XMLModel(master: hydpy.auxs.xmltools.XMLItemgroup, root: xml.etree.ElementTree.Element)[source]¶

Bases: hydpy.auxs.xmltools.XMLBase

Helper class for XMLItemgroup responsible for handling the exchange items related to different parameter or sequence groups of Model objects.

root: xml.etree.ElementTree.Element¶

property subvars¶: The required XMLSubvars objects.

class hydpy.auxs.xmltools.XMLSubvars(master: hydpy.auxs.xmltools.XMLModel, root: xml.etree.ElementTree.Element)[source]¶

Bases: hydpy.auxs.xmltools.XMLBase

Helper class for XMLModel responsible for handling the exchange items related to individual parameters or sequences of Model objects.

root: xml.etree.ElementTree.Element¶

property vars¶: The required XMLVar objects.

class hydpy.auxs.xmltools.XMLNode(master: hydpy.auxs.xmltools.XMLItemgroup, root: xml.etree.ElementTree.Element)[source]¶

Bases: hydpy.auxs.xmltools.XMLBase

Helper class for XMLItemgroup responsible for handling the exchange items related to individual parameters or sequences of Node objects.

root: xml.etree.ElementTree.Element¶

property vars¶: The required XMLVar objects.

class hydpy.auxs.xmltools.XMLVar(master: Union[hydpy.auxs.xmltools.XMLSubvars, hydpy.auxs.xmltools.XMLNode], root: xml.etree.ElementTree.Element)[source]¶

Bases: hydpy.auxs.xmltools.XMLSelector

Helper class for XMLSubvars and XMLNode responsible for creating a defined exchange item.

master: hydpy.auxs.xmltools.XMLBase¶

root: xml.etree.ElementTree.Element¶

property item¶

The actually defined ExchangeItem object.

We first prepare the LahnH example project and then create the related XMLInterface object defined by the XML configuration file multiple_runs:

>>> from hydpy.examples import prepare_full_example_1
>>> prepare_full_example_1()

>>> from hydpy import HydPy, pub, TestIO, XMLInterface
>>> hp = HydPy("LahnH")
>>> pub.timegrids = "1996-01-01", "1996-01-06", "1d"
>>> with TestIO():
...     hp.prepare_everything()
...     interface = XMLInterface("multiple_runs.xml")

One of the defined SetItem objects modifies the values of all Alpha objects of application model hland_v1. We demonstrate this for the control parameter object handled by element land_dill:

>>> var = interface.exchange.itemgroups[0].models[0].subvars[0].vars[0]
>>> item = var.item
>>> item.value
array(2.0)
>>> hp.elements.land_dill.model.parameters.control.alpha
alpha(1.0)
>>> item.update_variables()
>>> hp.elements.land_dill.model.parameters.control.alpha
alpha(2.0)

The second example is comparable but focusses on a SetItem modifying control parameter Lag of application model hstream_v1:

>>> var = interface.exchange.itemgroups[0].models[2].subvars[0].vars[0]
>>> item = var.item
>>> item.value
array(5.0)
>>> hp.elements.stream_dill_lahn_2.model.parameters.control.lag
lag(0.0)
>>> item.update_variables()
>>> hp.elements.stream_dill_lahn_2.model.parameters.control.lag
lag(5.0)

The third discussed SetItem assigns the same value to all entries of state sequence SM, resulting in the some soil moisture for all individual hydrological response units of element land_lahn_2:

>>> var = interface.exchange.itemgroups[1].models[0].subvars[0].vars[0]
>>> item = var.item
>>> item.name
'sm_lahn_2'
>>> item.value
array(123.0)
>>> hp.elements.land_lahn_2.model.sequences.states.sm
sm(138.31396, 135.71124, 147.54968, 145.47142, 154.96405, 153.32805,
   160.91917, 159.62434, 165.65575, 164.63255)
>>> item.update_variables()
>>> hp.elements.land_lahn_2.model.sequences.states.sm
sm(123.0, 123.0, 123.0, 123.0, 123.0, 123.0, 123.0, 123.0, 123.0, 123.0)

The fourth SetItem is, in contrast to the last example, 1-dimensional and thus allows to assign different values to the individual hydrological response units of element land_lahn_1:

>>> var = interface.exchange.itemgroups[1].models[0].subvars[0].vars[1]
>>> item = var.item
>>> item.name
'sm_lahn_1'
>>> item.value
array([ 110.,  120.,  130.,  140.,  150.,  160.,  170.,  180.,  190.,
        200.,  210.,  220.,  230.])
>>> hp.elements.land_lahn_1.model.sequences.states.sm
sm(99.27505, 96.17726, 109.16576, 106.39745, 117.97304, 115.56252,
   125.81523, 123.73198, 132.80035, 130.91684, 138.95523, 137.25983,
   142.84148)
>>> from hydpy import pub
>>> with pub.options.warntrim(False):
...     item.update_variables()
>>> hp.elements.land_lahn_1.model.sequences.states.sm
sm(110.0, 120.0, 130.0, 140.0, 150.0, 160.0, 170.0, 180.0, 190.0, 200.0,
   206.0, 206.0, 206.0)

AddItem sfcf_1, sfcf_2, and sfcf_3 serve to demonstrate how a scalar value (sfcf_1 and sfcf_2) or a vector of values can be used to change the value of a “target” parameter (SfCF) in relation to a “base” parameter (RfCF):

>>> for element in pub.selections.headwaters.elements:
...     element.model.parameters.control.rfcf(1.1)
>>> for element in pub.selections.nonheadwaters.elements:
...     element.model.parameters.control.rfcf(1.0)

>>> for subvars in interface.exchange.itemgroups[2].models[0].subvars:
...     for var in subvars.vars:
...         var.item.update_variables()
>>> for element in hp.elements.catchment:
...     print(element, repr(element.model.parameters.control.sfcf))
land_dill sfcf(1.4)
land_lahn_1 sfcf(1.4)
land_lahn_2 sfcf(1.2)
land_lahn_3 sfcf(field=1.1, forest=1.2)

The final three examples focus on GetItem objects. One GetItem object queries the actual values of the SM states of all relevant elements:

>>> var = interface.exchange.itemgroups[3].models[0].subvars[1].vars[0]
>>> hp.elements.land_dill.model.sequences.states.sm = 1.0
>>> for name, target in var.item.yield_name2value():
...     print(name, target)    
land_dill_states_sm [1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0]
land_lahn_1_states_sm [110.0, 120.0, 130.0, 140.0, 150.0, 160.0, 170.0, 180.0, 190.0, 200.0, 206.0, 206.0, 206.0]
land_lahn_2_states_sm [123.0, 123.0, 123.0, 123.0, 123.0, 123.0, 123.0, 123.0, 123.0, 123.0]
land_lahn_3_states_sm [101.3124...]

Another GetItem object queries both the actual and the time series values of the QT flux sequence of element land_dill:

>>> vars_ = interface.exchange.itemgroups[3].models[0].subvars[0].vars
>>> qt = hp.elements.land_dill.model.sequences.fluxes.qt
>>> qt(1.0)
>>> qt.series = 2.0
>>> for var in vars_:
...     for name, target in var.item.yield_name2value():
...         print(name, target)    
land_dill_fluxes_qt 1.0
land_dill_fluxes_qt_series [2.0, 2.0, 2.0, 2.0, 2.0]

Last but not least, one GetItem queries the simulated time series values avaiable through node dill:

>>> var = interface.exchange.itemgroups[3].nodes[0].vars[0]
>>> hp.nodes.dill.sequences.sim.series = range(5)
>>> for name, target in var.item.yield_name2value():
...     print(name, target)    
dill_nodes_sim_series [0.0, 1.0, 2.0, 3.0, 4.0]
>>> for name, target in var.item.yield_name2value(2, 4):
...     print(name, target)    
dill_nodes_sim_series [2.0, 3.0]

class hydpy.auxs.xmltools.XSDWriter[source]¶

Bases: object

A pure classmethod class for writing the actual XML schema file HydPyConfigBase.xsd, which makes sure that an XML configuration file is readable by class XMLInterface.

Unless you are interested in enhancing HydPy’s XML functionalities, you should, if any, be interested in method write_xsd() only.

confpath: str = '/home/travis/virtualenv/python3.7.1/lib/python3.7/site-packages/hydpy/conf'¶

filepath_source: str = '/home/travis/virtualenv/python3.7.1/lib/python3.7/site-packages/hydpy/conf/HydPyConfigBase.xsdt'¶

filepath_target: str = '/home/travis/virtualenv/python3.7.1/lib/python3.7/site-packages/hydpy/conf/HydPyConfigBase.xsd'¶

classmethod write_xsd() → None [source]¶

Write the complete base schema file HydPyConfigBase.xsd based on the template file HydPyConfigBase.xsdt.

Method write_xsd() adds model-specific information to the general information of template file HydPyConfigBase.xsdt regarding reading and writing of time series data and exchanging parameter and sequence values e.g. during calibration.

The following example shows that after writing a new schema file, method validate_xml() does not raise an error when either applied on the XML configuration files single_run.xml or multiple_runs.xml of the LahnH example project:

>>> import os
>>> from hydpy.auxs.xmltools import XSDWriter, XMLInterface
>>> if os.path.exists(XSDWriter.filepath_target):
...     os.remove(XSDWriter.filepath_target)
>>> os.path.exists(XSDWriter.filepath_target)
False
>>> XSDWriter.write_xsd()
>>> os.path.exists(XSDWriter.filepath_target)
True

>>> from hydpy.data import make_filepath
>>> for configfile in ("single_run.xml", "multiple_runs.xml"):
...     XMLInterface(configfile, make_filepath("LahnH")).validate_xml()

static get_modelnames() → List[str][source]¶

Return a sorted list containing all application model names.

>>> from hydpy.auxs.xmltools import XSDWriter
>>> print(XSDWriter.get_modelnames())    
[...'dam_v001', 'dam_v002', 'dam_v003', 'dam_v004', 'dam_v005',...]

classmethod get_insertion() → str [source]¶

Return the complete string to be inserted into the string of the template file.

>>> from hydpy.auxs.xmltools import XSDWriter
>>> print(XSDWriter.get_insertion())    
     <element name="arma_v1"
              substitutionGroup="hpcb:sequenceGroup"
              type="hpcb:arma_v1Type"/>

     <complexType name="arma_v1Type">
         <complexContent>
             <extension base="hpcb:sequenceGroupType">
                 <sequence>
                    <element name="fluxes"
                             minOccurs="0">
                        <complexType>
                            <sequence>
                                <element
                                    name="qin"
                                    minOccurs="0"/>
...
                        </complexType>
                    </element>
                 </sequence>
             </extension>
         </complexContent>
     </complexType>

classmethod get_modelinsertion(model: modeltools.Model, indent: int) → str [source]¶

Return the insertion string required for the given application model.

>>> from hydpy.auxs.xmltools import XSDWriter
>>> from hydpy import prepare_model
>>> model = prepare_model("hland_v1")
>>> print(XSDWriter.get_modelinsertion(model, 1))   
    <element name="inputs"
             minOccurs="0">
        <complexType>
            <sequence>
                <element
                    name="p"
                    minOccurs="0"/>
...
    </element>
    <element name="fluxes"
             minOccurs="0">
...
    </element>
    <element name="states"
             minOccurs="0">
...
    </element>

classmethod get_subsequencesinsertion(subsequences: hydpy.core.sequencetools.SubSequences, indent: int) → str [source]¶

Return the insertion string required for the given group of sequences.

>>> from hydpy.auxs.xmltools import XSDWriter
>>> from hydpy import prepare_model
>>> model = prepare_model("hland_v1")
>>> print(XSDWriter.get_subsequencesinsertion(
...     model.sequences.fluxes, 1))    
    <element name="fluxes"
             minOccurs="0">
        <complexType>
            <sequence>
                <element
                    name="tmean"
                    minOccurs="0"/>
                <element
                    name="tc"
                    minOccurs="0"/>
...
                <element
                    name="qt"
                    minOccurs="0"/>
            </sequence>
        </complexType>
    </element>

static get_sequenceinsertion(sequence: hydpy.core.sequencetools.Sequence_, indent: int) → str [source]¶

Return the insertion string required for the given sequence.

>>> from hydpy.auxs.xmltools import XSDWriter
>>> from hydpy import prepare_model
>>> model = prepare_model("hland_v1")
>>> print(XSDWriter.get_sequenceinsertion(model.sequences.fluxes.pc, 1))
    <element
        name="pc"
        minOccurs="0"/>

classmethod get_exchangeinsertion() → str [source]¶

Return the complete string related to the definition of exchange items to be inserted into the string of the template file.

>>> from hydpy.auxs.xmltools import XSDWriter
>>> print(XSDWriter.get_exchangeinsertion())    
    <complexType name="arma_v1_mathitemType">
...
    <element name="setitems">
...
    <complexType name="arma_v1_setitemsType">
...
    <element name="additems">
...
    <element name="getitems">
...

classmethod get_mathitemsinsertion(indent: int) → str [source]¶

Return a string defining a model-specific XML type extending ItemType.

>>> from hydpy.auxs.xmltools import XSDWriter
>>> print(XSDWriter.get_mathitemsinsertion(1))    
    <complexType name="arma_v1_mathitemType">
        <complexContent>
            <extension base="hpcb:setitemType">
                <choice>
                    <element name="control.responses"/>
...
                    <element name="logs.logout"/>
                </choice>
            </extension>
        </complexContent>
    </complexType>

    <complexType name="conv_v001_mathitemType">
...

classmethod get_itemsinsertion(itemgroup: str, indent: int) → str [source]¶

Return a string defining the XML element for the given exchange item group.

>>> from hydpy.auxs.xmltools import XSDWriter
>>> print(XSDWriter.get_itemsinsertion(
...     "setitems", 1))    
    <element name="setitems">
        <complexType>
            <sequence>
                <element ref="hpcb:selections"
                         minOccurs="0"/>
                <element ref="hpcb:devices"
                         minOccurs="0"/>
...
                <element name="hland_v1"
                         type="hpcb:hland_v1_setitemsType"
                         minOccurs="0"
                         maxOccurs="unbounded"/>
...
                <element name="nodes"
                         type="hpcb:nodes_setitemsType"
                         minOccurs="0"
                         maxOccurs="unbounded"/>
            </sequence>
            <attribute name="info" type="string"/>
        </complexType>
    </element>

classmethod get_itemtypesinsertion(itemgroup: str, indent: int) → str [source]¶

Return a string defining the required types for the given exchange item group.

>>> from hydpy.auxs.xmltools import XSDWriter
>>> print(XSDWriter.get_itemtypesinsertion(
...     "setitems", 1))    
    <complexType name="arma_v1_setitemsType">
...
    </complexType>

    <complexType name="dam_v001_setitemsType">
...
    <complexType name="nodes_setitemsType">
...

classmethod get_itemtypeinsertion(itemgroup: str, modelname: str, indent: int) → str [source]¶

Return a string defining the required types for the given combination of an exchange item group and an application model.

>>> from hydpy.auxs.xmltools import XSDWriter
>>> print(XSDWriter.get_itemtypeinsertion(
...     "setitems", "hland_v1", 1))    
    <complexType name="hland_v1_setitemsType">
        <sequence>
            <element ref="hpcb:selections"
                     minOccurs="0"/>
            <element ref="hpcb:devices"
                     minOccurs="0"/>
            <element name="control"
                     minOccurs="0"
                     maxOccurs="unbounded">
...
        </sequence>
    </complexType>

classmethod get_nodesitemtypeinsertion(itemgroup: str, indent: int) → str [source]¶

Return a string defining the required types for the given combination of an exchange item group and Node objects.

>>> from hydpy.auxs.xmltools import XSDWriter
>>> print(XSDWriter.get_nodesitemtypeinsertion(
...     "setitems", 1))    
    <complexType name="nodes_setitemsType">
        <sequence>
            <element ref="hpcb:selections"
                     minOccurs="0"/>
            <element ref="hpcb:devices"
                     minOccurs="0"/>
            <element name="sim"
                     type="hpcb:setitemType"
                     minOccurs="0"
                     maxOccurs="unbounded"/>
            <element name="obs"
                     type="hpcb:setitemType"
                     minOccurs="0"
                     maxOccurs="unbounded"/>
            <element name="sim.series"
                     type="hpcb:setitemType"
                     minOccurs="0"
                     maxOccurs="unbounded"/>
            <element name="obs.series"
                     type="hpcb:setitemType"
                     minOccurs="0"
                     maxOccurs="unbounded"/>
        </sequence>
    </complexType>

classmethod get_subgroupsiteminsertion(itemgroup: str, modelname: str, indent: int) → str [source]¶

Return a string defining the required types for the given combination of an exchange item group and an application model.

>>> from hydpy.auxs.xmltools import XSDWriter
>>> print(XSDWriter.get_subgroupsiteminsertion(
...     "setitems", "hland_v1", 1))    
    <element name="control"
             minOccurs="0"
             maxOccurs="unbounded">
...
    </element>
    <element name="inputs"
...
    <element name="fluxes"
...
    <element name="states"
...
    <element name="logs"
...

classmethod get_subgroupiteminsertion(itemgroup: str, model: modeltools.Model, subgroup: variabletools.SubVariables, indent: int) → str [source]¶

Return a string defining the required types for the given combination of an exchange item group and a specific variable subgroup of an application model or class Node.

Note that for setitems and getitems setitemType and getitemType are referenced, respectively, and for all others the model-specific mathitemType:

>>> from hydpy import prepare_model
>>> model = prepare_model("hland_v1")
>>> from hydpy.auxs.xmltools import XSDWriter
>>> print(XSDWriter.get_subgroupiteminsertion(    
...     "setitems", model, model.parameters.control, 1))
    <element name="control"
             minOccurs="0"
             maxOccurs="unbounded">
        <complexType>
            <sequence>
                <element ref="hpcb:selections"
                         minOccurs="0"/>
                <element ref="hpcb:devices"
                         minOccurs="0"/>
                <element name="area"
                         type="hpcb:setitemType"
                         minOccurs="0"
                         maxOccurs="unbounded"/>
                <element name="nmbzones"
...
            </sequence>
        </complexType>
    </element>

>>> print(XSDWriter.get_subgroupiteminsertion(    
...     "getitems", model, model.parameters.control, 1))
    <element name="control"
...
                <element name="area"
                         type="hpcb:getitemType"
                         minOccurs="0"
                         maxOccurs="unbounded"/>
...

>>> print(XSDWriter.get_subgroupiteminsertion(    
...     "additems", model, model.parameters.control, 1))
    <element name="control"
...
                <element name="area"
                         type="hpcb:hland_v1_mathitemType"
                         minOccurs="0"
                         maxOccurs="unbounded"/>
...

For sequence classes, additional “series” elements are added:

>>> print(XSDWriter.get_subgroupiteminsertion(    
...     "setitems", model, model.sequences.fluxes, 1))
    <element name="fluxes"
...
                <element name="tmean"
                         type="hpcb:setitemType"
                         minOccurs="0"
                         maxOccurs="unbounded"/>
                <element name="tmean.series"
                         type="hpcb:setitemType"
                         minOccurs="0"
                         maxOccurs="unbounded"/>
                <element name="tc"
...
            </sequence>
        </complexType>
    </element>

xmltools¶

Table of Contents

Previous topic

Next topic

This Page

Versions