scenic.core.distributions
Objects representing distributions that can be sampled from.
Summary of Module Members
Functions
Uniform distribution over a finite list of options. |
|
|
|
Whether the function supports iterable unpacking of distributions. |
|
Decorator for wrapping a function so that it can take distributions as arguments. |
|
Decorator for wrapping a method so that it can take distributions as arguments. |
|
|
|
Like distributionFunction, but additionally specifies that the function is monotonic. |
|
|
|
|
|
Lower and upper bounds on this value, if known. |
|
Wrap Python data types with Distributions, if necessary. |
|
Original function underlying a distribution wrapper. |
|
|
|
Decorator indicating the function supports iterable unpacking of distributions. |
Classes
Distribution resulting from accessing an attribute of a distribution |
|
A samplable which always evaluates to a constant value. |
|
Distribution over a range of integers. |
|
Abstract class for distributions. |
|
Distribution resulting from passing distributions to a function |
|
Distribution resulting from passing distributions to a method of a fixed object |
|
Distribution selecting among values based on another distribution. |
|
Normal distribution |
|
Distribution resulting from applying an operator to one or more distributions |
|
Distribution over a finite list of options. |
|
Uniform distribution over a range |
|
Abstract class for values which can be sampled, possibly depending on other values. |
|
Distributions over |
|
A placeholder for the iterable unpacking operator * applied to a distribution. |
|
Truncated normal distribution. |
|
Distributions over tuples (or namedtuples, or lists). |
|
Uniform distribution over a variable number of options. |
Exceptions
Exception indicating illegal conditional control flow depending on a random value. |
|
Exception used to signal that the sample currently being generated must be rejected. |
Member Details
- canUnpackDistributions(func)[source]
Whether the function supports iterable unpacking of distributions.
- unpacksDistributions(func)[source]
Decorator indicating the function supports iterable unpacking of distributions.
- exception RejectionException[source]
Bases:
Exception
Exception used to signal that the sample currently being generated must be rejected.
- exception RandomControlFlowError[source]
Bases:
ScenicError
Exception indicating illegal conditional control flow depending on a random value.
This includes trying to iterate over a random value, making a range of random length, etc.
- class Samplable(dependencies)[source]
Bases:
LazilyEvaluable
Abstract class for values which can be sampled, possibly depending on other values.
Samplables may specify a proxy object which must have the same distribution as the original after conditioning on the scenario’s requirements. This allows transparent conditioning without modifying Samplable fields of immutable objects.
- Parameters:
dependencies – sequence of values that this value may depend on (formally, objects for which sampled values must be provided to
sampleGiven
). It is legal to include values which are not instances ofSamplable
, e.g. integers.- Attributes:
_conditioned – proxy object as described above; set using
conditionTo
._dependencies – tuple of other samplables which must be sampled before this one; set by the initializer and subsequently immutable.
- static sampleAll(quantities)[source]
Sample all the given Samplables, which may have dependencies in common.
Reproducibility note: the order in which the quantities are given can affect the order in which calls to random are made, affecting the final result.
- sampleGiven(value)[source]
Sample this value, given values for all its dependencies.
Implemented by subclasses.
- Parameters:
value (DefaultIdentityDict) – dictionary mapping objects to their sampled values. Guaranteed to provide values for all objects given in the set of dependencies when this
Samplable
was created.
- conditionTo(value)[source]
Condition this value to another value with the same conditional distribution.
- class ConstantSamplable(value)[source]
Bases:
Samplable
A samplable which always evaluates to a constant value.
Only for internal use.
- class Distribution(*dependencies, valueType=None)[source]
Bases:
Samplable
Abstract class for distributions.
Note
When called during dynamic simulations (vs. scenario compilation), constructors for distributions return actual sampled values, not
Distribution
objects.- Parameters:
- Attributes:
_valueType – type of the values sampled from this distribution, or Object if the type is not known.
- _defaultValueType
Default valueType for distributions of this class, when not otherwise specified.
alias of
object
- _deterministic = False
Whether this type of distribution is a deterministic function of its dependencies.
For example,
Options
is implemented as deterministic by using an internalDiscreteRange
to select which of its finitely-many options to choose from: the value of theOptions
is then completely determined by the value of the range and the values of each of the options. This simplifies serialization because these dependencies likely have simpler valueTypes than theOptions
itself (e.g. if we had a random choice between a list and a string, encoding the actual sampled value would require saving type information).
- clone()[source]
Construct an independent copy of this Distribution.
Optionally implemented by subclasses.
- property isPrimitive
Whether this is a primitive Distribution.
- serializeValue(values, serializer)[source]
Serialize the sampled value of this distribution.
This method is used internally by
Scenario.sceneToBytes
and related APIs. If you define a new subclass ofDistribution
, you probably don’t need to override this method. If your distribution has an unusual valueType (i.e. notfloat
,int
, orVector
), see the documentation forSerializer
for instructions on how to support serialization.
- bucket(buckets=None)[source]
Construct a bucketed approximation of this Distribution.
Optionally implemented by subclasses.
This function factors a given Distribution into a discrete distribution over buckets together with a distribution for each bucket. The argument buckets controls how many buckets the domain of the original Distribution is split into. Since the result is an independent distribution, the original must support
clone
.
- class TupleDistribution(*coordinates, builder=<class 'tuple'>)[source]
Bases:
Distribution
,Sequence
Distributions over tuples (or namedtuples, or lists).
- class SliceDistribution(start, stop, step)[source]
Bases:
Distribution
Distributions over
slice
objects.
- toDistribution(val)[source]
Wrap Python data types with Distributions, if necessary.
For example, tuples containing Samplables need to be converted into TupleDistributions in order to keep track of dependencies properly.
- class FunctionDistribution(func, args, kwargs, support=None, valueType=None)[source]
Bases:
Distribution
Distribution resulting from passing distributions to a function
- distributionFunction(wrapped=None, *, support=None, valueType=None)[source]
Decorator for wrapping a function so that it can take distributions as arguments.
This decorator is mainly for internal use, and is not necessary when defining a function in a Scenic file. It is, however, needed when calling external functions which contain control flow or other operations that Scenic distribution objects (representing random values) do not support.
- monotonicDistributionFunction(method, valueType=None)[source]
Like distributionFunction, but additionally specifies that the function is monotonic.
- class StarredDistribution(value, lineno)[source]
Bases:
Distribution
A placeholder for the iterable unpacking operator * applied to a distribution.
- class MethodDistribution(method, obj, args, kwargs, valueType=None)[source]
Bases:
Distribution
Distribution resulting from passing distributions to a method of a fixed object
- distributionMethod(method=None, *, identity=None)[source]
Decorator for wrapping a method so that it can take distributions as arguments.
- class AttributeDistribution(attribute, obj, valueType=None)[source]
Bases:
Distribution
Distribution resulting from accessing an attribute of a distribution
- class OperatorDistribution(operator, obj, operands, kwoperands, valueType=None)[source]
Bases:
Distribution
Distribution resulting from applying an operator to one or more distributions
- class MultiplexerDistribution(index, options)[source]
Bases:
Distribution
Distribution selecting among values based on another distribution.
- class Range(low, high)[source]
Bases:
Distribution
Uniform distribution over a range
- class Normal(mean, stddev)[source]
Bases:
Distribution
Normal distribution
- class TruncatedNormal(mean, stddev, low, high)[source]
Bases:
Normal
Truncated normal distribution.
- class DiscreteRange(low, high, weights=None, emptyMessage='empty DiscreteRange')[source]
Bases:
Distribution
Distribution over a range of integers.
- class Options(opts)[source]
Bases:
MultiplexerDistribution
Distribution over a finite list of options.
Specified by a dict giving probabilities; otherwise uniform over a given iterable.
- Uniform(*opts)[source]
Uniform distribution over a finite list of options.
Implemented as an instance of
Options
when the set of options is known statically, and an instance ofUniformDistribution
otherwise.
- class UniformDistribution(opts)[source]
Bases:
Distribution
Uniform distribution over a variable number of options.
See
Options
for the more common uniform distribution over a fixed number of options. This class is for the special case where iterable unpacking is applied to a distribution, so that the number of options is unknown at compile time.