Drake
Drake C++ Documentation

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 {
};
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 {
};
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]

See also

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