scenic.core.distributions

Objects representing distributions that can be sampled from.

Summary of Module Members

Functions

Uniform	Uniform distribution over a finite list of options.
canUnpackDistributions	Whether the function supports iterable unpacking of distributions.
dependencies	Dependencies which must be sampled before this value.
distributionFunction	Decorator for wrapping a function so that it can take distributions as arguments.
distributionMethod	Decorator for wrapping a method so that it can take distributions as arguments.
makeOperatorHandler
monotonicDistributionFunction	Like distributionFunction, but additionally specifies that the function is monotonic.
needsSampling	Whether this value requires sampling.
supmax
supmin
supportInterval	Lower and upper bounds on this value, if known.
toDistribution	Wrap Python data types with Distributions, if necessary.
underlyingFunction	Original function underlying a distribution wrapper.
unionOfSupports
unpacksDistributions	Decorator indicating the function supports iterable unpacking of distributions.

Classes

AttributeDistribution	Distribution resulting from accessing an attribute of a distribution
ConstantSamplable	A samplable which always evaluates to a constant value.
DiscreteRange	Distribution over a range of integers.
Distribution	Abstract class for distributions.
FunctionDistribution	Distribution resulting from passing distributions to a function
MethodDistribution	Distribution resulting from passing distributions to a method of a fixed object
MultiplexerDistribution	Distribution selecting among values based on another distribution.
Normal	Normal distribution
OperatorDistribution	Distribution resulting from applying an operator to one or more distributions
Options	Distribution over a finite list of options.
Range	Uniform distribution over a range
Samplable	Abstract class for values which can be sampled, possibly depending on other values.
StarredDistribution	A placeholder for the iterable unpacking operator * applied to a distribution.
TruncatedNormal	Truncated normal distribution.
TupleDistribution	Distributions over tuples (or namedtuples, or lists).
UniformDistribution	Uniform distribution over a variable number of options.

Exceptions

RandomControlFlowError	Exception indicating illegal conditional control flow depending on a random value.
RejectionException	Exception used to signal that the sample currently being generated must be rejected.

Member Details

dependencies(thing)

Dependencies which must be sampled before this value.

needsSampling(thing)

Whether this value requires sampling.

supportInterval(thing)

Lower and upper bounds on this value, if known.

underlyingFunction(thing)

Original function underlying a distribution wrapper.

canUnpackDistributions(func)

Whether the function supports iterable unpacking of distributions.

unpacksDistributions(func)

Decorator indicating the function supports iterable unpacking of distributions.

exception RejectionException

Bases: Exception

Exception used to signal that the sample currently being generated must be rejected.

exception RandomControlFlowError(msg, loc=None)

Bases: RuntimeParseError

Exception indicating illegal conditional control flow depending on a random value.

This includes trying to iterate over a random value, take the length of a random sequence whose length can’t be determined statically, etc.

class Samplable(dependencies)

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 of Samplable, 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)

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.

sample(subsamples=None)

Sample this value, optionally given some values already sampled.

sampleGiven(value)

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)

Condition this value to another value with the same conditional distribution.

evaluateIn(context)

See LazilyEvaluable.evaluateIn.

class ConstantSamplable(value)

Bases: Samplable

A samplable which always evaluates to a constant value.

Only for internal use.

class Distribution(*args, **kwargs)

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

• dependencies – values which this distribution may depend on (see Samplable).

• valueType – _valueType to use (see below), or None for the default.

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

clone()

Construct an independent copy of this Distribution.

Optionally implemented by subclasses.

property isPrimitive

Whether this is a primitive Distribution.

bucket(buckets=None)

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.

supportInterval()

Compute lower and upper bounds on the value of this Distribution.

By default returns (None, None) indicating that no lower or upper bounds are known. Subclasses may override this method to provide more accurate results.

class TupleDistribution(*args, **kwargs)

Bases: Distribution, Sequence

Distributions over tuples (or namedtuples, or lists).

toDistribution(val)

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(*args, **kwargs)

Bases: Distribution

Distribution resulting from passing distributions to a function

distributionFunction(wrapped=None, *, support=None, valueType=None)

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)

Like distributionFunction, but additionally specifies that the function is monotonic.

class StarredDistribution(*args, **kwargs)

Bases: Distribution

A placeholder for the iterable unpacking operator * applied to a distribution.

class MethodDistribution(*args, **kwargs)

Bases: Distribution

Distribution resulting from passing distributions to a method of a fixed object

distributionMethod(method)

Decorator for wrapping a method so that it can take distributions as arguments.

class AttributeDistribution(*args, **kwargs)

Bases: Distribution

Distribution resulting from accessing an attribute of a distribution

static inferType(obj, attribute)

Attempt to infer the type of the given attribute.

class OperatorDistribution(*args, **kwargs)

Bases: Distribution

Distribution resulting from applying an operator to one or more distributions

static inferType(obj, operator, operands)

Attempt to infer the result type of the given operator application.

class MultiplexerDistribution(*args, **kwargs)

Bases: Distribution

Distribution selecting among values based on another distribution.

class Range(*args, **kwargs)

Bases: Distribution

Uniform distribution over a range

class Normal(*args, **kwargs)

Bases: Distribution

Normal distribution

class TruncatedNormal(*args, **kwargs)

Bases: Normal

Truncated normal distribution.

class DiscreteRange(*args, **kwargs)

Bases: Distribution

Distribution over a range of integers.

class Options(*args, **kwargs)

Bases: MultiplexerDistribution

Distribution over a finite list of options.

Specified by a dict giving probabilities; otherwise uniform over a given iterable.

Uniform(*opts)

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 of UniformDistribution otherwise.

class UniformDistribution(*args, **kwargs)

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.