Parameter Validation

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.