Validating model parameters#

When running your model, you always want to be sure only valid parameters have been passed, since for invalid parameters the model will either break or show unexpected behaviour. For instance, certain parameters may need to be integers or probabilities, or you may want string parameters to be one of only a few permissible options.

Utopia allows to specify validity constraints on your model’s parameters and have them automatically checked before a simulation run and without the need to include those checks into your model implementation.

You can define a parameter’s default value, its data type, range limits, or pass a set of accepted values. In case of any errors, a concise message is logged and the run terminated. Additionally, you can directly add a clear name and descriptive text to your parameter, making that information parseable and reducing the need for comment strings.

For certain frequently used parameter types (such as probabilities), a convenient shorthand notation is available.

Note

This feature currently only supports validating scalar nodes. You cannot validate sequences or the structure of mappings.

Basic syntax#

Validation parameters can be optionally specified on all scalar parameters in your default model configuration file, i.e. inside the <your_model_name>_cfg.yml file. The rationale behind specifying it in that file is to have all information on model parameters in one place.

If you wish to have a model parameter validated, simply add a !param tag after the parameter name, and specify the default value and any validity constraints in an indented block underneath. A default value is required, though the validity restrictions are optional.

Refer to the utopya.parameter.Parameter API and to the examples to learn more about possible keys.

Warning

!param can only be specified inside your default model configuration, e.g. MyFancyModel_cfg.yml. Specifying it elsewhere will lead to errors!

Examples#

# # The default configuation file for MyModel
# ---
  some_int: !param
    name: my integer
    description: some integer parameter
    default: 3
    dtype: int

  another_int: !param
    name: my negative integer
    description: an integer less than zero
    default: -2
    limits: [~, 0]
    limits_mode: ()

  some_unsigned_int: !param
    default: 0
    dtype: uint8  # only allows integer values in [0, 255]

  a_float: !param
    default: 4.20
    dtype: float

  a_string: !param
    default: foo
    is_any_of: [foo, bar, baz]

  some:
    nested:
      parameter: !param
        default: spam
        is_any_of: [spam, fish]
        dtype: str

Hint

Use YAML’s ~ (i.e., None) for specifying ±inf in limits.

Shorthands#

For frequently used parameter types, shorthand tags are available to spare you the trouble of having to specify limits or data types. Simply add the corresponding YAML tag and the default value directly:

# # The default configuation file for MyModel
# ---
  # ...

  # a probability value, i.e. a float in [0, 1]
  some_probability: !is-probability 0.3

  # an integer
  some_int: !is-int 3

  # a positive value (strictly greater than 0)
  some_positive_value: !is-positive 5

  # a boolean
  some_bool: !is-bool true

Available shorthands are:

  • is-probability (a float in range [0, 1])

  • is-int

  • is-bool

  • is-string

  • is-positive/is-negative: strictly greater/less than zero

  • is-unsigned: greater or equal to zero and data type uint

  • is-positive-int/is-negative-int: strictly greater/less than zero and data type int

See also the Forest Fire model for an integrated demo of this feature.

Validation procedure#

Parameter validation happens as part of the Multiverse initialization and before any simulations are started.

The validation is restricted to the parameter_space entry of the meta configuration, i.e. all values that will be made available to the model executable. If parameter_space actually is a parameter space, validation will always occur for the full parameter space and including the default point, independent of whether a sweep will actually be performed.

For all specified validation parameters, the given value is checked against the constraints using the Parameter‘s validate() method:

Hint

For very large sweeps (parameter space volume > 10k), parameter validation may take a long time and can thus be optionally disabled.

To skip parameter validation, set the following entry on the top-level of the run configuration:

perform_validation: false

Alternatively, you can specify --skip-validation via the command line interface, see utopia run --help.