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.

Stochastic variables

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:

struct MyStuff {
  schema::DistributionVariant value;
};
MyStuff stuff;

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:

stuff:
  value: !Uniform
    min: 1.0
    max: 5.0

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: !Uniform { min: 1.0, max: 5.0 }

stuff:

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

Vectors of stochastic variables

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:

struct MyThing {
  schema::DistributionVectorVariantX value;
};
MyThing thing;

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:

thing:
  value: !UniformVector
    min: [10.0, 20.0]
    max: [11.0, 22.0]

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]

Stochastic variables

Vectors of stochastic variables

See also