scenic.core.external_params¶
Support for values which are sampled outside of Scenic.
External Samplers in General¶
External samplers provide a mechanism to use different types of sampling
techniques, like optimization or quasirandom sampling, from within a Scenic
program. Ordinary random values in Scenic are instances of Distribution
;
this module defines a special subclass, ExternalParameter
, representing a
value which is sampled externally. Scenic programs with external parameters
are handled as follows:
During compilation, all instances of
ExternalParameter
are gathered together and given to theExternalSampler.forParameters
function; this function creates an appropriateExternalSampler
, whose configuration can be controlled using global parameters (see the function documentation for details).When sampling a scene, before sampling any other distributions the
sample
method of theExternalSampler
is called to sample all the external parameters. For active samplers, this method passes along thefeedback
value given toScenario.generate
, if any.Once the external parameters have values, the program is equivalent to one without external parameters, and sampling proceeds as usual. As for every instance of
Distribution
, the external parameters will have theirsampleGiven
method called once all their dependencies have been sampled; by default this method just returns the value sampled for this parameter in step (2).
Note
Note that while external parameters, like all instances of Distribution
,
are allowed to have dependencies, they are an exception to the usual rule
that dependencies are always sampled before dependents, because the
ExternalSampler.sample
method is called before any other sampling.
However, as explained above, the sampleGiven
method is
called in the proper order and external samplers which need to do sampling
based on the values of other distributions can be invoked from it. The
twostep mechanism with ExternalSampler.sample
is provided for samplers
which sample the whole space of external parameters at once (e.g. the
VerifAI samplers).
Samplers from VerifAI¶
The external sampling mechanism is designed to be extensible. The only builtin
ExternalSampler
is the VerifaiSampler
, which provides access to the
samplers in the VerifAI toolkit (which in turn can use Scenic as a modeling
language).
The VerifaiSampler
supports several types of external parameters corresponding
to the primitive distributions: VerifaiRange
and VerifaiDiscreteRange
for
continuous and discrete intervals, and VerifaiOptions
for discrete sets.
For example, suppose we write:
ego = Object at (VerifaiRange(5, 15), 0)
This is equivalent to the ordinary Scenic line ego = Object at (Range(5, 15), 0)
,
except that the X coordinate of the ego is sampled by VerifAI within the range
(5, 15) instead of being uniformly distributed over it. By default the
VerifaiSampler
uses VerifAI’s Halton sampler, so the range will still be
covered uniformly but more systematically. If we want to use a different sampler,
we can set the verifaiSamplerType
global parameter:
param verifaiSamplerType = 'ce'
ego = Object at (VerifaiRange(5, 15), 0)
Now the X coordinate will be sampled using VerifAI’s crossentropy sampler.
If we pass a feedback value to Scenario.generate
which scores the previous
scene, then the coordinate will not be sampled uniformly but rather converge to
a distribution concentrated on values minimizing the score. Active samplers like
crossentropy can be used for falsification in this way, driving a system toward
parts of the parameter space where a specification is violated.
The crossentropy sampler in VerifAI can be started from a nonuniform prior. Scenic provides a convenient way to define this prior using the ordinary syntax for distributions:
param verifaiSamplerType = 'ce'
ego = Object at (VerifaiParameter.withPrior(Normal(10, 3)), 0)
Now crossentropy sampling will start from a normal distribution with mean 10
and standard deviation 3. Priors are restricted to primitive distributions and
in general may be approximated so that VerifAI can handle them – see
VerifaiParameter.withPrior
for details.
For more information on how to customize the sampler, see VerifaiSampler
.
Summary of Module Members¶
Classes
A value determined by external code rather than Scenic's internal sampler. 

Abstract class for objects called to sample values for each external parameter. 

A 

An 

An external parameter sampled using one of VerifAI's samplers. 

A 

An external sampler exposing the samplers in the VerifAI toolkit. 
Member Details¶
 class ExternalSampler(params, globalParams)[source]¶
Abstract class for objects called to sample values for each external parameter.
The initializer for this class takes the same arguments as the factory function
forParameters
below. Attributes
rejectionFeedback – Value passed to the
sample
method when the last sample was rejected. This value can be chosen by a Scenic scenario using the global parameterexternalSamplerRejectionFeedback
.
 static forParameters(params, globalParams)[source]¶
Create an
ExternalSampler
given the sets of external and global parameters.The scenario may explicitly select an external sampler by assigning the global parameter
externalSampler
to a subclass ofExternalSampler
. Otherwise, aVerifaiSampler
is used by default. Parameters
params (tuple) – Tuple listing each
ExternalParameter
.globalParams (dict) – Dictionary of global parameters for the
Scenario
, made available here to support sampler customization through setting parameters. Note that the values of these parameters may be instances ofDistribution
!
 Returns
An
ExternalSampler
configured for the given parameters.
 class VerifaiSampler(params, globalParams)[source]¶
Bases:
ExternalSampler
An external sampler exposing the samplers in the VerifAI toolkit.
The sampler can be configured using the following Scenic global parameters:
verifaiSamplerType
– sampler type (see theverifai.server.choose_sampler
function); the default is'halton'
verifaiSamplerParams
–DotMap
of options passed to the sampler
The
VerifaiSampler
supports external parameters which are instances ofVerifaiParameter
.
 class ExternalParameter(*args, **kwargs)[source]¶
Bases:
Distribution
A value determined by external code rather than Scenic’s internal sampler.
 sampleGiven(value)[source]¶
Specialization of
Samplable.sampleGiven
for external parameters.By default, this method simply looks up the value previously sampled by
ExternalSampler.sample
.
 class VerifaiParameter(*args, **kwargs)[source]¶
Bases:
ExternalParameter
An external parameter sampled using one of VerifAI’s samplers.
 static withPrior(dist, buckets=None)[source]¶
Creates a
VerifaiParameter
using the given distribution as a prior.Since the VerifAI crossentropy sampler currently only supports piecewiseconstant distributions, if the prior is not of that form it may be approximated. For most builtin distributions, the approximation is exact: for a particular distribution, check its
bucket
method.
 class VerifaiRange(*args, **kwargs)[source]¶
Bases:
VerifaiParameter
A
Range
(real interval) sampled by VerifAI.
 class VerifaiDiscreteRange(*args, **kwargs)[source]¶
Bases:
VerifaiParameter
A
DiscreteRange
(integer interval) sampled by VerifAI.