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 quasi-random 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:

1. During compilation, all instances of ExternalParameter are gathered together and given to the ExternalSampler.forParameters function; this function creates an appropriate ExternalSampler, whose configuration can be controlled using global parameters (see the function documentation for details).

2. When sampling a scene, before sampling any other distributions the sample method of the ExternalSampler is called to sample all the external parameters. For active samplers, this method passes along the feedback value given to Scenario.generate, if any.

3. 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 their sampleGiven 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 two-step 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 built-in 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 = new Object at (VerifaiRange(5, 15), 0)

This is equivalent to the ordinary Scenic line ego = new 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 = new Object at (VerifaiRange(5, 15), 0)

Now the X coordinate will be sampled using VerifAI’s cross-entropy 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 cross-entropy can be used for falsification in this way, driving a system toward parts of the parameter space where a specification is violated.

The cross-entropy sampler in VerifAI can be started from a non-uniform prior. Scenic provides a convenient way to define this prior using the ordinary syntax for distributions:

param verifaiSamplerType = 'ce'
ego = new Object at (VerifaiParameter.withPrior(Normal(10, 3)), 0)

Now cross-entropy 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

ExternalParameter	A value determined by external code rather than Scenic's internal sampler.
ExternalSampler	Abstract class for objects called to sample values for each external parameter.
VerifaiDiscreteRange	A DiscreteRange (integer interval) sampled by VerifAI.
VerifaiOptions	An Options (discrete set) sampled by VerifAI.
VerifaiParameter	An external parameter sampled using one of VerifAI's samplers.
VerifaiRange	A Range (real interval) sampled by VerifAI.
VerifaiSampler	An external sampler exposing the samplers in the VerifAI toolkit.

Member Details

class ExternalSampler(params, globalParams)

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 parameter externalSamplerRejectionFeedback.

static forParameters(params, globalParams)

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 of ExternalSampler. Otherwise, a VerifaiSampler 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 of Distribution!

Returns:

An ExternalSampler configured for the given parameters.

sample(feedback)

Sample values for all the external parameters.

Parameters:

feedback – Feedback from the last sample (for active samplers).

nextSample(feedback)

Actually do the sampling. Implemented by subclasses.

valueFor(param)

Return the sampled value for a parameter. Implemented by subclasses.

class VerifaiSampler(params, globalParams)

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 the verifai.server.choose_sampler function); the default is 'halton'

• verifaiSamplerParams – DotMap of options passed to the sampler

The VerifaiSampler supports external parameters which are instances of VerifaiParameter.

static nameForParam(i)

Parameter name for a given index in the Feature Space.

class ExternalParameter

Bases: Distribution

A value determined by external code rather than Scenic’s internal sampler.

sampleGiven(value)

Specialization of Samplable.sampleGiven for external parameters.

By default, this method simply looks up the value previously sampled by ExternalSampler.sample.

class VerifaiParameter(domain)

Bases: ExternalParameter

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

static withPrior(dist, buckets=None)

Creates a VerifaiParameter using the given distribution as a prior.

Since the VerifAI cross-entropy sampler currently only supports piecewise-constant distributions, if the prior is not of that form it may be approximated. For most built-in distributions, the approximation is exact: for a particular distribution, check its bucket method.

class VerifaiRange(low, high, buckets=None, weights=None)

Bases: VerifaiParameter

A Range (real interval) sampled by VerifAI.

_defaultValueType

alias of float

class VerifaiDiscreteRange(low, high, weights=None)

Bases: VerifaiParameter

A DiscreteRange (integer interval) sampled by VerifAI.

_defaultValueType

alias of float

class VerifaiOptions(opts)

Bases: Options

An Options (discrete set) sampled by VerifAI.