Configuring distributions

This page describes how to use classes such as schema::Distribution to denote stochastic quantities, as a bridge between loading a scenario specification and populating the corresponding symbolic::Expression quantities into a systems::System.

We'll explain uses of schema::Distribution and related types using the matching YAML syntax as parsed by yaml::LoadYamlFile.

Given this C++ data structure:

You might load a YAML file such as this:

stuff:

value: 1.0

The `stuff.value`

is set to a constant (not stochastic) value 1.0.

Alternatively, you might load a YAML file such as this:

stuff:

value: !Gaussian

mean: 1.0

stddev: 0.5

Now, `stuff.value`

is set to gaussian variable with the given mean and standard deviation.

The exclamation point syntax is a YAML type tag, which we use to specify the type choice within an `std::variant`

. The schema::DistributionVariant is a typedef for a specific `std::variant`

.

There are a few other choices for the type.

Here, you might specify a real-valued uniform range:

Or, you might choose from a set of equally-likely options:

stuff:

value: !UniformDiscrete

values: [1.0, 1.5, 2.0]

You may also use YAML's flow style to fit everything onto a single line. These one-line spellings are the equivalent to those above.

stuff:

value: !Gaussian { mean: 1.0, stddev: 0.5 }

stuff:

value: !UniformDiscrete { values: [1.0, 1.5, 2.0] }

For convenience, we also provide the option to specify a vector of independent stochastic variables with the same type.

We'll explain uses of schema::DistributionVector and related types using the matching YAML syntax as parsed by yaml::LoadYamlFile.

Given this C++ data structure:

You might load a YAML file such as this:

thing:

value: [1.0, 2.0, 3.0]

The `thing.value`

is set to a constant (not stochastic) vector with three elements.

You might also choose to constrain the vector to be a fixed size:

struct MyThing3 {

schema::DistributionVectorVariant3 value;

};

MyThing3 thing3;

Whether fixed or dynamic size, you might specify stochastic variables:

thing:

value: !GaussianVector

mean: [2.1, 2.2, 2.3]

stddev: [1.0] # Same stddev each.

Or:

thing:

value: !GaussianVector

mean: [2.1, 2.2, 2.3]

stddev: [1.0, 0.5, 0.2] # Different stddev each.

Or:

- Note
- You cannot mix, e.g., Gaussian and Uniform within the same vector; all elements must be a homogeneous type.

All distributions still support constants for some elements and stochastic for others by specifying a zero-sized range for the constant elements:

thing:

value: !UniformVector # The first element is a constant 2.0, not stochastic.

min: [2.0, -1.0]

max: [2.0, 1.0]

Or:

thing:

value: !GaussianVector # The first element is a constant 2.0, not stochastic.

mean: [2.0, 3.0]

stddev: [0.0, 1.0]

See Configuring transforms for one practical application, of specifying rotations, translations, and transforms using stochastic schemas.