optiontools¶
This module implements features for defining local or global HydPy options.
Module optiontools
implements the following members:
TypeOption
Type variable.
TypeOptionContextBase
Type variable.
TypeOptionPropertyBase
Type variable.
OptionPropertyBase
Base class for defining descriptors that work like regularproperty
instances and support the with statement to change the property’s value temporarily.
OptionPropertyBool
Descriptor for defining options of typebool
.
OptionPropertyInt
Descriptor for defining options of typeint
.
OptionPropertyStr
Descriptor for defining options of typestr
.
OptionPropertyPeriod
Descriptor for defining options of typePeriod
.
OptionPropertySeriesFileType
Descriptor for defining options of typeSeriesFileType
.
OptionPropertySeriesAggregation
Descriptor for defining options of typeSeriesAggregationType
.
OptionContextBase
Base class for defining context managers required for the differentOptionPropertyBase
subclasses.
OptionContextBool
Context manager required byOptionPropertyBool
.
OptionContextInt
Context manager required byOptionPropertyInt
.
OptionContextStr
Context manager required byOptionPropertyStr
.
OptionContextPeriod
Context manager required byOptionPropertyPeriod
.
OptionContextSeriesFileType
Context manager required byOptionPropertySeriesFileType
.
OptionContextSeriesAggregation
Context manager required byOptionPropertySeriesAggregation
.
Options
Singleton class for the general options available in the globalpub
module.
- class hydpy.core.optiontools.OptionPropertyBase(default: TypeOption, doc: str)[source]¶
Bases:
BaseDescriptor
,Generic
[TypeOption
]Base class for defining descriptors that work like regular
property
instances and support the with statement to change the property’s value temporarily.
- class hydpy.core.optiontools.OptionPropertyBool(default: TypeOption, doc: str)[source]¶
Bases:
OptionPropertyBase
[bool
]Descriptor for defining options of type
bool
.Framework or model developers should implement options of type
bool
as follows:>>> from hydpy.core.optiontools import OptionPropertyBool >>> class T: ... v = OptionPropertyBool(True, "x")
The given string serves for documentation:
>>> T.v.__doc__ 'x'
Users can change the current value “normally” by assignments:
>>> t = T() >>> assert t.v >>> t.v = False >>> assert not t.v
Deleting restores the default value:
>>> del t.v >>> assert t.v
In most cases, the prefered way is to change options “temporarily” for a specific code block introduced by the with statement:
>>> with t.v(False): ... assert not t.v ... with t.v(True): ... assert t.v ... with t.v(): ... assert t.v ... with t.v(None): ... assert t.v ... with t.v(False): ... assert not t.v ... with t.v(): ... t.v = False ... assert not t.v ... assert t.v ... assert t.v ... assert t.v ... assert not t.v >>> assert t.v
>>> with t.v(False): ... assert not t.v ... raise RuntimeError Traceback (most recent call last): ... RuntimeError >>> assert t.v
- class hydpy.core.optiontools.OptionPropertyInt(default: TypeOption, doc: str)[source]¶
Bases:
OptionPropertyBase
[int
]Descriptor for defining options of type
int
.Framework or model developers should implement options of type
int
as follows:>>> from hydpy.core.optiontools import OptionPropertyInt >>> class T: ... v = OptionPropertyInt(1, "x")
The given string serves for documentation:
>>> T.v.__doc__ 'x'
Users can change the current value “normally” by assignments:
>>> t = T() >>> assert t.v == 1 >>> t.v = 2 >>> assert t.v == 2
Deleting restores the default value:
>>> del t.v >>> assert t.v == 1
In most cases, the prefered way is to change options “temporarily” for a specific code block introduced by the with statement:
>>> with t.v(2): ... assert t.v == 2 ... with t.v(3): ... assert t.v == 3 ... with t.v(): ... assert t.v == 3 ... with t.v(None): ... assert t.v == 3 ... with t.v(1): ... assert t.v == 1 ... with t.v(): ... t.v = 4 ... assert t.v == 4 ... assert t.v == 3 ... assert t.v == 3 ... assert t.v == 3 ... assert t.v == 2 >>> assert t.v == 1
>>> with t.v(2): ... assert t.v == 2 ... raise RuntimeError Traceback (most recent call last): ... RuntimeError >>> assert t.v == 1
- class hydpy.core.optiontools.OptionPropertyStr(default: TypeOption, doc: str)[source]¶
Bases:
OptionPropertyBase
[str
]Descriptor for defining options of type
str
.Framework or model developers should implement options of type
str
as follows:>>> from hydpy.core.optiontools import OptionPropertyStr >>> class T: ... v = OptionPropertyStr("1", "x")
The given string serves for documentation:
>>> T.v.__doc__ 'x'
Users can change the current value “normally” by assignments:
>>> t = T() >>> assert t.v == "1" >>> t.v = "2" >>> assert t.v == "2"
Deleting restores the default value:
>>> del t.v >>> assert t.v == "1"
In most cases, the prefered way is to change options “temporarily” for a specific code block introduced by the with statement:
>>> with t.v("2"): ... assert t.v == "2" ... with t.v("3"): ... assert t.v == "3" ... with t.v(): ... assert t.v == "3" ... with t.v(None): ... assert t.v == "3" ... with t.v("1"): ... assert t.v == "1" ... with t.v(): ... t.v = "4" ... assert t.v == "4" ... assert t.v == "3" ... assert t.v == "3" ... assert t.v == "3" ... assert t.v == "2" >>> assert t.v == "1"
>>> with t.v("2"): ... assert t.v == "2" ... raise RuntimeError Traceback (most recent call last): ... RuntimeError >>> assert t.v == "1"
- class hydpy.core.optiontools.OptionPropertyPeriod(default: TypeOption, doc: str)[source]¶
Bases:
OptionPropertyBase
[Period
]Descriptor for defining options of type
Period
.Framework or model developers should implement options of type
Period
as follows:>>> from hydpy.core.optiontools import OptionPropertyPeriod >>> class T: ... v = OptionPropertyPeriod("1d", "x")
The given string serves for documentation:
>>> T.v.__doc__ 'x'
Users can change the current value “normally” by assignments (note the automatic type conversion):
>>> t = T() >>> assert t.v == "1d" >>> t.v = "2d" >>> from hydpy import Period >>> assert t.v == Period("2d")
Deleting restores the default value:
>>> del t.v >>> assert t.v == "1d"
In most cases, the prefered way is to change options “temporarily” for a specific code block introduced by the with statement:
>>> with t.v("2d"): ... assert t.v == "2d" ... with t.v("3d"): ... assert t.v == "3d" ... with t.v(): ... assert t.v == "3d" ... with t.v(None): ... assert t.v == "3d" ... with t.v("1d"): ... assert t.v == "1d" ... with t.v(): ... t.v = "4d" ... assert t.v == "4d" ... assert t.v == "3d" ... assert t.v == "3d" ... assert t.v == "3d" ... assert t.v == "2d" >>> assert t.v == "1d"
>>> with t.v("2d"): ... assert t.v == "2d" ... raise RuntimeError Traceback (most recent call last): ... RuntimeError >>> assert t.v == "1d"
- class hydpy.core.optiontools.OptionPropertySeriesFileType(default: TypeOption, doc: str)[source]¶
Bases:
OptionPropertyBase
[Literal
[‘npy’, ‘asc’, ‘nc’]]Descriptor for defining options of type
SeriesFileType
.HydPy currently supports a simple text format (asc), the numpy binary format (npy) and NetCDF files (nc). Options based on
OptionPropertySeriesFileType
automatically check if the given string is a supported file-ending and raise errors if not:>>> from hydpy.core.optiontools import OptionPropertySeriesFileType >>> class T: ... v = OptionPropertySeriesFileType("asc", "x") >>> T.v.__doc__ 'x'
>>> t = T() >>> assert t.v == "asc" >>> t.v = "abc" Traceback (most recent call last): ... ValueError: The given sequence file type `abc` is not implemented. Please choose one of the following file types: npy, asc, and nc. >>> assert t.v == "asc" >>> t.v = "npy" >>> assert t.v == "npy" >>> t.v = "nc" >>> assert t.v == "nc" >>> t.v = "asc" >>> assert t.v == "asc"
>>> with t.v("abc"): ... pass Traceback (most recent call last): ... ValueError: The given sequence file type `abc` is not implemented. Please choose one of the following file types: npy, asc, and nc. >>> assert t.v == "asc" >>> with t.v("npy"): ... assert t.v == "npy" ... with t.v("nc"): ... assert t.v == "nc" ... with t.v(): ... assert t.v == "nc" ... with t.v(None): ... assert t.v == "nc" ... assert t.v == "npy" >>> assert t.v == "asc"
- class hydpy.core.optiontools.OptionPropertySeriesAggregation(default: TypeOption, doc: str)[source]¶
Bases:
OptionPropertyBase
[Literal
[‘none’, ‘mean’]]Descriptor for defining options of type
SeriesAggregationType
.The only currently supported aggregation is averaging (mean). Use none to avoid any aggregation. Options based on
OptionPropertySeriesAggregation
automatically check if the given string meets one of these modes and raises errors if not:>>> from hydpy.core.optiontools import OptionPropertySeriesAggregation >>> class T: ... v = OptionPropertySeriesAggregation("none", "x") >>> T.v.__doc__ 'x'
>>> t = T() >>> assert t.v == "none" >>> t.v = "sum" Traceback (most recent call last): ... ValueError: The given aggregation mode `sum` is not implemented. Please choose one of the following modes: none and mean. >>> assert t.v == "none" >>> t.v = "mean" >>> assert t.v == "mean" >>> t.v = "none" >>> assert t.v == "none"
>>> with t.v("sum"): ... pass Traceback (most recent call last): ... ValueError: The given aggregation mode `sum` is not implemented. Please choose one of the following modes: none and mean. >>> assert t.v == "none" >>> with t.v("mean"): ... assert t.v == "mean" ... with t.v(): ... assert t.v == "mean" ... with t.v(None): ... assert t.v == "mean" ... assert t.v == "mean" >>> assert t.v == "none"
- class hydpy.core.optiontools.OptionContextBase(value: TypeOption, set_value: Callable[[TypeOption | None], None] | None = None)[source]¶
Bases:
Generic
[TypeOption
]Base class for defining context managers required for the different
OptionPropertyBase
subclasses.
- class hydpy.core.optiontools.OptionContextBool(value: bool, set_value: Callable[[bool], None] | None = None)[source]¶
Bases:
int
,OptionContextBase
[bool
]Context manager required by
OptionPropertyBool
.
- class hydpy.core.optiontools.OptionContextInt(value: int, set_value: Callable[[int], None] | None = None)[source]¶
Bases:
int
,OptionContextBase
[int
]Context manager required by
OptionPropertyInt
.
- class hydpy.core.optiontools.OptionContextStr(value: str, set_value: Callable[[str], None] | None = None)[source]¶
Bases:
str
,OptionContextBase
[str
]Context manager required by
OptionPropertyStr
.
- class hydpy.core.optiontools.OptionContextPeriod(value: timetools.PeriodConstrArg, set_value: Callable[[timetools.PeriodConstrArg | None], None] | None = None)[source]¶
Bases:
Period
,OptionContextBase
[Period
]Context manager required by
OptionPropertyPeriod
.
- class hydpy.core.optiontools.OptionContextSeriesFileType(value: Literal['npy', 'asc', 'nc'], set_value: Callable[[Literal['npy', 'asc', 'nc']], None] | None = None)[source]¶
Bases:
str
,OptionContextBase
[Literal
[‘npy’, ‘asc’, ‘nc’]]Context manager required by
OptionPropertySeriesFileType
.
- class hydpy.core.optiontools.OptionContextSeriesAggregation(value: Literal['none', 'mean'], set_value: Callable[[Literal['none', 'mean']], None] | None = None)[source]¶
Bases:
str
,OptionContextBase
[Literal
[‘none’, ‘mean’]]Context manager required by
OptionPropertySeriesAggregation
.
- class hydpy.core.optiontools.Options[source]¶
Bases:
object
Singleton class for the general options available in the global
pub
module.Most options are simple True/False or 0/1 flags.
You can change all options in two ways. First, using the with statement makes sure the change is reverted after leaving the corresponding code block (even if an error occurs):
>>> from hydpy import pub >>> pub.options.printprogress = 0 >>> pub.options.printprogress 0 >>> with pub.options.printprogress(True): ... print(pub.options.printprogress) 1 >>> pub.options.printprogress 0
Alternatively, you can change all options via simple assignments:
>>> pub.options.printprogress = True >>> pub.options.printprogress 1
But then you might have to keep in mind to undo the change later:
>>> pub.options.printprogress 1 >>> pub.options.printprogress = False >>> pub.options.printprogress 0
When using the with statement, you can pass nothing or
None
, which does not change the original setting and resets it after leaving the with block:>>> with pub.options.printprogress(None): ... print(pub.options.printprogress) ... pub.options.printprogress = True ... print(pub.options.printprogress) 0 1 >>> pub.options.printprogress 0
The delete statement restores the respective default setting:
>>> del pub.options.printprogress >>> pub.options.printprogress 1
- checkseries¶
True/False flag for raising an error when loading an input time series that does not cover the whole initialisation period or contains
nan
values.
- ellipsis¶
Ellipsis points serve to shorten the string representations of iterable HydPy objects containing many entries. Set a value to define the maximum number of entries before and behind ellipsis points. Set it to zero to avoid any ellipsis points. Set it to -999 to rely on the default values of the respective iterable objects.
- parameterstep¶
The actual parameter time step size. Change it by passing a
Period
object or any validPeriod
constructor argument. The default parameter step is one day.>>> from hydpy import pub >>> pub.options.parameterstep Period("1d")
- printprogress¶
A True/False flag for printing information about the progress of some processes to the standard output.
- reprcomments¶
A True/False flag for including comments into string representations. So far, this option affects the behaviour of a few implemented classes, only.
- reprdigits¶
Required precision of string representations of floating point numbers, defined as the minimum number of digits to be reproduced by the string representation (see function
repr_
).
- simulationstep¶
The actual simulation time step size. Change it by passing a
Period
object or any validPeriod
constructor argument. HydPy does not define a default simulation step (indicated by an emptyPeriod
object).Note that you cannot manually define the
simulationstep
whenever it is already available via attributestepsize
of the globalTimegrids
object in modulepub
(pub.timegrids):>>> from hydpy import pub >>> pub.options.simulationstep Period()
>>> pub.options.simulationstep = "1h" >>> pub.options.simulationstep Period("1h")
>>> pub.timegrids = "2000-01-01", "2001-01-01", "1d" >>> pub.options.simulationstep Period("1d")
>>> pub.options.simulationstep = "1s" >>> pub.options.simulationstep Period("1d")
>>> del pub.timegrids >>> pub.options.simulationstep Period("1s")
>>> del pub.options.simulationstep >>> pub.options.simulationstep Period()
- trimvariables¶
A True/False flag for enabling/disabling function
trim()
. Set it toFalse
only for good reasons.
- usecython¶
A True/False flag for applying cythonized models if possible, which are much faster than pure Python models.
- usedefaultvalues¶
A True/False flag for initialising parameters with standard values.
- utclongitude¶
Longitude of the centre of the local time zone (see option
utcoffset
). Defaults to 15, which corresponds to the central meridian of UTC+01:00.
- utcoffset¶
Local time offset from UTC in minutes (see option
utclongitude
. Defaults to 60, which corresponds to UTC+01:00.
- timestampleft¶
A True/False flag telling if assigning interval data (like hourly precipitation) to single time points relies on the start (True, default) or the end (False) of the respective interval.
HydPy-internally, we usually prevent such potentially problematic assignments by using
Timegrid
objects that define grids of intervals instead of time points. However, some exceptions cannot be avoided, for example, when reading or writing NetCDF files.
- warnmissingcontrolfile¶
A True/False flag for only raising a warning instead of an exception when a necessary control file is missing.
- warnmissingobsfile¶
A True/False flag for raising a warning when a requested observation sequence demanded by a node instance is missing.
- warnmissingsimfile¶
A True/False flag for raising a warning when a requested simulation sequence demanded by a node instance is missing.
- warnsimulationstep¶
A True/False flag for raising a warning when function
simulationstep()
is called for the first time directly by the user.