Options¶
HydPy offers infinite configuration possibilities for those familiar with Python. But even without programming skills, one has a lot of options, and this section lists the most relevant ones, explains how to set them, and points to the places of the reference manual containing further information.
All options discussed here work for the framework in general or apply to all (or at
least many) models and are accessible from both Python scripts and XML files. Refer to
the reference manuals’ model documentation for more
model-specific questions like: What options do I have to set the capillary rise when
using lland_dd
?).
Class Options
provides many of the most general options. Note that the default
values of some of its options are suitable for real projects but less for testing
purposes. Hence, the various code examples of this documentation rely on settings that
deviate from these defaults, and you need to adjust these options to be able to
reproduce all examples exactly.
The documentation of the individual Options
members explains their purposes and
mentions possible deviations of default and testing values. All these options are
configurable when working with XML files, and any changes apply to the entire XML-based
workflow. In contrast, when defining workflows with Python scripts, you can change all
options multiple times.
Take the reprdigits
option as an example, which determines the maximum number
of digits of floating point numbers shown in HydPy’s string representations. Its
default is -1, which means printing in the highest available precision. However, HydPy
sets it to 6 during testing, compromising preciseness and readability.
You can access and modify this and the other mentioned options via the singleton
instance of class Options
available in the pub
module, which stores this and other
public project data:
You can access and modify this and the other mentioned options via the singleton
instance of class Options
available in the pub
module (pub
stores this and other
public configuration data):
>>> from hydpy import pub, round_
>>> pub.options.reprdigits
6
>>> round_(1.0 / 3.0)
0.333333
Use a simple assignment statement to change the printed precision permanently:
>>> pub.options.reprdigits = 4
>>> round_(1.0 / 3.0)
0.3333
For temporary changes, we encourage using the with syntax. Then, the modification only applies inside the with block (even when an error occurs):
>>> with pub.options.reprdigits(2):
... round_(1.0 / 3.0)
0.33
>>> round_(1.0 / 3.0)
0.3333
Many options are “bool-like” but not actually of type bool
. Hence, you cannot rely
on identity checks via is when writing Python scripts:
>>> pub.options.timestampleft
TRUE
>>> assert pub.options.timestampleft # fine
>>> pub.options.timestampleft == True # fine
True
>>> pub.options.timestampleft is True # buggy
False
The second group of options worth mentioning here is provided by multiple “file
managers”, which also are singleton objects and members of the pub
module.
NetworkManager
, ControlManager
, ConditionManager
, and SequenceManager
manage,
as their names suggest, reading and writing network,
control, condition, and time
series files. The instances are named after their classes but, as
usual, in lower-case letters. They become available after starting a HydPy project via
initialising class HydPy
:
>>> from hydpy import HydPy
>>> hp = HydPy("my_project")
>>> assert hasattr(pub, "networkmanager")
All these file managers offer the currentdir
property (which so far does
not support the with syntax) to change the directory selected for reading or writing
data. By default, the currentdir
is within the base directory defined by
the respective file manager:
>>> assert pub.networkmanager.BASEDIR == "network"
>>> assert pub.controlmanager.BASEDIR == "control"
>>> assert pub.conditionmanager.BASEDIR == "conditions"
>>> assert pub.sequencemanager.BASEDIR == "series"
The only file managers providing other user-relevant options (which do support the
with syntax) are ConditionManager
and SequenceManager
. One example is option
filetype
for choosing between the ASCII, NetCDF, and Numpy file
formats.
When working with XML files, HydPy offers more flexibility for the file managers’
options than for those of class Options
. When setting each option once and for all,
one could not, for example, read meteorological input data from NetCDF files of one
directory and write discharge data to ASCII files in another directory. Therefore,
HydPy’s XML support offers two exceptions, which are both illustrated, for example, by
the single_run.xml file supplied with the HydPy-H-Lahn example project.
First, the XML element conditions_io allows for specifying separate directories for
reading and writing condition files. Second, the XML element serios_io can contain
multiple readers and writers, and one can specify individual option values for
each.
The option mode is specific to XML files. It allows reading and writing time series
data “just in time” during simulation runs (in contrast to handling the complete time
series data in RAM). When working with Python scripts, the counterpart to mode is
the function argument jit (provided, for example, by method
prepare_allseries()
). The documentation on class HydPy
explains its usage in
detail.