scenic.core.scenarios

Scenario and scene objects.

Summary of Module Members

Classes

Scenario	A compiled Scenic scenario, from which scenes can be sampled.
Scene	A scene generated from a Scenic scenario.

Member Details

class Scene

A scene generated from a Scenic scenario.

To run a dynamic simulation from a scene, create an instance of Simulator for the simulator you want to use, and pass the scene to its simulate method.

Attributes:

• objects (tuple of Object) – All objects in the scene. The ego object is first, if there is one.

• egoObject (Object or None) – The ego object, if any.

• params (dict) – Dictionary mapping the name of each global parameter to its value.

• workspace (Workspace) – The workspace for the scenario.

Changed in version 3.0: The egoObject attribute can now be None.

dumpAsScenicCode(stream=sys.stdout)

Dump Scenic code reproducing this scene to the given stream.

For non-human-readable but complete serialization of scenes see Scenario.sceneToBytes and Scenario.sceneFromBytes.

Note

This function does not currently reproduce parts of the original Scenic program defining behaviors, functions, etc. used in the scene. Also, if the scene involves any user-defined types, they must provide a suitable __repr__ for this function to print them properly.

Parameters:

stream (text file) – Where to print the code (default sys.stdout).

show3D(axes)

Render a 3D schematic of the scene for debugging.

show2D(zoom=None, block=True)

Render a 2D schematic of the scene for debugging.

class Scenario

A compiled Scenic scenario, from which scenes can be sampled.

generate(maxIterations=2000, verbosity=0, feedback=None)

Sample a Scene from this scenario.

For a description of how scene generation is done, see Scene Generation.

Parameters:

• maxIterations (int) – Maximum number of rejection sampling iterations.

• verbosity (int) – Verbosity level.

• feedback (float) – Feedback to pass to external samplers doing active sampling. See scenic.core.external_params.

Returns:

A pair with the sampled Scene and the number of iterations used.

Raises:

RejectionException – if no valid sample is found in maxIterations iterations.

generateBatch(numScenes, maxIterations=inf, verbosity=0, feedback=None)

Sample several Scene objects from this scenario.

For a description of how scene generation is done, see Scene Generation.

Parameters:

• numScenes (int) – Number of scenes to generate.

• maxIterations (int) – Maximum number of rejection sampling iterations (over all scenes).

• verbosity (int) – Verbosity level.

• feedback (float) – Feedback to pass to external samplers doing active sampling. See scenic.core.external_params.

Returns:

A pair with a list of the sampled Scene objects and the total number of iterations used.

Raises:

RejectionException – if not enough valid samples are found in maxIterations iterations.

resetExternalSampler()

Reset the scenario’s external sampler, if any.

If the Python random seed is reset before calling this function, this should cause the sequence of generated scenes to be deterministic.

conditionOn(scene=None, objects=(), params={})

Condition the scenario on particular values for some objects or parameters.

This method changes the distribution of the scenario and should be used with care: it does not attempt to check that the new distribution is equivalent to the old one or that it has nonzero probability of satisfying the scenario’s requirements.

For example, to sample object #5 in the scenario once and then leave it fixed in all subsequent samples:

sceneA, _ = scenario.generate()
scenario.conditionOn(scene=sceneA, objects=(5,))
sceneB, _ = scenario.generate()     # will have the same object 5 as sceneA

Parameters:

• scene (Scene) – Scene from which to take values for the given objects, if any.

• objects – Sequence of indices specifying which objects in this scenario should be conditioned on the corresponding objects in scene (i.e. those with the same index in the list of objects).

• params (dict) – Dictionary of global parameters to condition and their new values (which may be constants or distributions).

sceneToBytes(scene, allowPickle=False)

Encode a Scene sampled from this scenario to a bytes object.

The serialized scene may be reconstituted with sceneFromBytes. The format used is suitable for long-term storage of scenes, although it is not guaranteed to be compatible across major versions of Scenic. For further discussion and usage examples, see Storing Scenes/Simulations for Later Use.

Raises:

SerializationError – if the scene could not be properly encoded. This should not happen unless your scenario includes a user-defined Distribution subclass with an unusual value type. If you get this exception, see the documentation for the internal class Serializer for solutions.

sceneFromBytes(data, verify=True, allowPickle=False)

Decode a Scene serialized with sceneToBytes.

Parameters:

• data (bytes) – Encoding of a Scene sampled from this scenario.

• verify (bool) – If true (the default), raise an exception if the scene appears to have been generated from a different scenario (meaning it will almost certainly not decode correctly).

• allowPickle (bool) – Enable using pickle to deserialize custom object types. False by default because it allows malicious data to trigger arbitrary code execution (see the pickle documentation). Use this option only if you trust the source of the data and it is not practical to implement serialization for the datatypes you need.

Raises:

SerializationError – if the scene could not be properly decoded.

simulationToBytes(simulation, allowPickle=False)

Encode a Simulation sampled from this scenario to a bytes object.

The serialized simulation may be replayed with simulationFromBytes. As with sceneToBytes, the format used is suitable for long-term storage but is not guaranteed to be compatible across major versions of Scenic.

Raises:

SerializationError – if the simulation could not be properly encoded. This should not happen unless your scenario includes a user-defined Distribution subclass with an unusual value type. If you get this exception, see the documentation for the internal class Serializer for solutions.

Note

The returned data encodes both the scene comprising the initial condition for the simulation and the simulation itself. If you will be running many simulations starting from the same scene, you can save space by separately encoding the scene and the various simulations: use sceneToBytes and Simulation.getReplay for encoding, and the replay argument of Simulator.simulate for decoding.

simulationFromBytes(data, simulator, *, verify=True, allowPickle=False, **kwargs)

Replay a Simulation serialized with simulationToBytes.

Parameters:

• data (bytes) – Encoding of a Simulation sampled from this scenario.

• simulator (Simulator) – Simulator in which to run the simulation. Using a different simulator configuration than that used for the original simulation may cause errors or unexpected behavior. If you need to do this, see the enableDivergenceCheck option of Simulator.simulate.

• verify (bool) – As in sceneFromBytes.

• allowPickle (bool) – As in sceneFromBytes.

• kwargs – All additional keyword arguments are passed through to the simulator; see Simulator.simulate for the available configuration options.

Returns:

A Simulation object representing the completed simulation.

Raises:

• SerializationError – if the simulation could not be properly decoded.

• DivergenceError – if the replayed simulation has diverged from the original (requires the original to have been run with divergence-checking support; see Simulator.simulate).