Parameter Validation#
With utopya’s parameter validation framework, model parameters can be validated before a simulation is started, which helps to avoid misconfigurations early on: before a simulation is even started. In addition, it offers an alternative to parameter checks in the model implementation.
Unlike many validation frameworks out there, utopya.parameter
allows to define parameter properties alongside their defaults and is optimized for use with YAML configuration files.
How to use#
Let’s start with an example, assuming that your model’s default configuration looks something like this, containing parameters of different
enable_fleeing: true
p_flee: 0.1
flee_distance: 3
flee_mode: random
To use parameter validation, the parameters’ allowed values need to be specified.
This can be done directly in the default model configuration using YAML tags (!<tag>
):
enable_fleeing: !is-bool true
p_flee: !is-probability 0.1
flee_distance: !is-unsigned 3
flee_mode: !param
default: random
is_any_of: [random, intelligent]
As you can see, the parameter specification uses YAML tags (!<tag>
) and aims to be as descriptive as possible:
p_flee
is meant to control a probability, flee_mode
can either be random
or intelligent
and so on.
In the example, we have made use of both the shorthand syntax (starting with !is-
) and the full form (!param
), each constructing a Parameter
object from the given arguments which can then be validated.
To use parameter validation, simply set these tags in your model’s default configuration.
They work with any kind of scalar parameters.
When the Multiverse
assembles the configuration for the model run, it will automatically validate the given values against these parameters.
Hint
To disable parameter validation, set the perform_validation
parameter in the Multiverse
meta-configuration to False
, e.g. from your run configuration.
In the command line interface, --no-validate
will deactivate parameter validation.
Note
It is not yet possible to validate sequences or mappings. Parameter values need to be scalar (numerical, string, boolean etc).
Shorthand Syntax#
As seen above, the shorthand modes are meant to directly describe which parameter values are valid. The following shorthand modes are available:
In [1]: from utopya.parameter import Parameter
In [2]: print("\n".join(Parameter.SHORTHAND_MODES))
is-positive
is-positive-or-zero
is-negative
is-negative-or-zero
is-probability
is-in-unit-interval
is-int
is-positive-int
is-negative-int
is-unsigned
is-string
is-bool
Hint
Typically, you will use these from within a YAML configuration file, without needing an import.
Don’t forget that the corresponding YAML tag has a leading exclamation mark: !<mode>
.
Alternatively, these modes can also be used for the from_shorthand()
class method; this is what happens under the hood.
Exact definition of shorthand parameters
In [3]: print_shorthand_defaults()
is-positive
limits : (0, None)
limits_mode : '(]'
is-positive-or-zero
limits : (0, None)
limits_mode : '[]'
is-negative
limits : (None, 0)
limits_mode : '[)'
is-negative-or-zero
limits : (None, 0)
limits_mode : '[]'
is-probability
limits : (0, 1)
dtype : <class 'float'>
is-in-unit-interval
limits : (0, 1)
dtype : <class 'float'>
is-int
dtype : <class 'int'>
is-positive-int
limits : (0, None)
limits_mode : '()'
dtype : <class 'int'>
is-negative-int
limits : (None, 0)
limits_mode : '()'
dtype : <class 'int'>
is-unsigned
limits : (0, None)
limits_mode : '[)'
dtype : 'uint'
is-string
dtype : <class 'str'>
is-bool
dtype : <class 'bool'>