scenic.core.simulators

Interface between Scenic and simulators.

This module defines the core classes Simulator and Simulation which orchestrate dynamic simulations. Each simulator interface defines subclasses of these classes for their particular simulator.

Ordinary Scenic users only need to know about the top-level simulation API Simulator.simulate and the attributes of the Simulation class (in particular the result attribute, which captures information about the result of the simulation as a SimulationResult object).

Summary of Module Members

Classes

DummySimulation	Minimal Simulation subclass for DummySimulator.
DummySimulator	Simulator which does (almost) nothing, for testing and debugging purposes.
ReplayMode	An enumeration.
Simulation	A single simulation run.
SimulationResult	Result of running a simulation.
Simulator	A simulator which can execute dynamic simulations from Scenic scenes.
TerminationType	Enum describing the possible ways a simulation can end.

Exceptions

DivergenceError	Exception indicating simulation replay failed due to simulator nondeterminism.
SimulationCreationError	Exception indicating a simulation could not be run from the given scene.
SimulatorInterfaceWarning	Warning indicating an issue with the interface to an external simulator.

Member Details

exception SimulatorInterfaceWarning

Bases: UserWarning

Warning indicating an issue with the interface to an external simulator.

exception SimulationCreationError

Bases: Exception

Exception indicating a simulation could not be run from the given scene.

Can also be issued during a simulation if dynamic object creation fails.

exception DivergenceError

Bases: Exception

Exception indicating simulation replay failed due to simulator nondeterminism.

class Simulator

Bases: ABC

A simulator which can execute dynamic simulations from Scenic scenes.

Simulator interfaces which support dynamic simulations should implement a subclass of Simulator. An instance of the class represents a connection to the simulator suitable for running multiple simulations (not necessarily of the same Scenic program). For an example of how to implement this class, and its counterpart Simulation for individual simulations, see scenic.simulators.webots.simulator.

Users who create an instance of Simulator should call its destroy method when they are finished running simulations to allow the interface to do any necessary cleanup.

simulate(scene, maxSteps=None, maxIterations=1, *, timestep=None, verbosity=None, raiseGuardViolations=False, replay=None, enableReplay=True, enableDivergenceCheck=False, divergenceTolerance=0, continueAfterDivergence=False, allowPickle=False)

Run a simulation for a given scene.

For details on how simulations are run, see Execution of Dynamic Scenarios.

Parameters:

• scene (Scene) – Scene from which to start the simulation (sampled using Scenario.generate).

• maxSteps (int) – Maximum number of time steps for the simulation, or None to not impose a time bound.

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

• timestep (float) – Length of a time step in seconds, or None to use a default provided by the simulator interface. Some interfaces may not allow arbitrary time step lengths or may require the timestep to be set when creating the Simulator and not customized per-simulation.

• verbosity (int) – If not None, override Scenic’s global verbosity level (from the --verbosity option or scenic.setDebuggingOptions).

• raiseGuardViolations (bool) – Whether violations of preconditions/invariants of scenarios/behaviors should cause this method to raise an exception, instead of only rejecting the simulation (the default behavior).

• replay (bytes) – If not None, must be replay data output by Simulation.getReplay: we will then replay the saved simulation rather than randomly generating one as usual. If maxSteps is larger than that of the original simulation, then once the replay is exhausted the simulation will continue to run in the usual randomized manner.

• enableReplay (bool) – Whether to save data from the simulation so that it can be serialized for later replay using Scenario.simulationToBytes or Simulation.getReplay. Enabled by default as the overhead is generally low.

• enableDivergenceCheck (bool) – Whether to save the values of every dynamic property at each time step, so that when the simulation is replayed, nondeterminism in the simulator (or replaying the simulation in the wrong simulator) can be detected. Disabled by default as this option greatly increases the size of replay objects (~100 bytes per object per step).

• divergenceTolerance (float) – Amount by which a dynamic property can deviate in a replay from its original value before we consider the replay to have diverged. The default value is zero: no deviation is allowed. If finer control over divergences is required, see Simulation.valuesHaveDiverged.

• continueAfterDivergence (bool) – Whether to continue simulating after a divergence is detected instead of raising a DivergenceError. If this is true, then a divergence ends the replaying of the saved scenario but the simulation will continue in the usual randomized manner (i.e., it is as if the replay data ran out at the moment of the divergence).

• allowPickle (bool) – Whether to use pickle to (de)serialize custom object types. See sceneFromBytes for a discussion of when this may be needed (rarely) and its security implications.

Returns:

A Simulation object representing the completed simulation, or None if no simulation satisfying the requirements could be found within maxIterations iterations.

Raises:

• SimulationCreationError – if an error occurred while trying to run a simulation (e.g. some assumption made by the simulator was violated, like trying to create an object inside another).

• GuardViolation – if raiseGuardViolations is true and a precondition or invariant was violated during the simulation.

• DivergenceError – if replaying a simulation (via the replay option) and the replay has diverged from the original; requires the original simulation to have been run with enableDivergenceCheck.

• SerializationError – if writing or reading replay data fails. This could happen if your scenario uses an unusual custom distribution (see sceneToBytes) or if the replayed scenario has diverged without divergence-checking enabled.

Changed in version 3.0: maxIterations is now 1 by default.

New in version 3.0: The timestep argument.

replay(scene, replay, **kwargs)

Replay a simulation.

This convenience method simply calls simulate (and so takes all the same arguments), but makes the replay argument positional so you can write simulator.replay(scene, replay) instead of simulator.simulate(scene, replay=replay).

abstract createSimulation(scene, **kwargs)

Create a Simulation from a Scenic scene.

This should be overridden by subclasses to return instances of their own specialized subclass of Simulation. The given scene and kwargs (together making up all the arguments passed to simulate except for maxIterations) should be passed through to the initializer of that instance.

Changed in version 3.0: This method is now called with all the arguments to simulate except for maxIterations; these should be passed through as described above.

destroy()

Clean up as needed when shutting down the simulator interface.

Subclasses should call the parent implementation, which will catch this method being called twice on the same Simulator.

class Simulation(scene, *, maxSteps, name, timestep, replay=None, enableReplay=True, allowPickle=False, enableDivergenceCheck=False, divergenceTolerance=0, continueAfterDivergence=False, verbosity=0)

Bases: ABC

A single simulation run.

These objects are not manipulated manually, but are created by a Simulator. Simulator interfaces should subclass this class, implementing various abstract methods to call the appropriate simulator APIs. In particular, the following methods must be implemented:

• createObjectInSimulator, to create an object;

• step, to run the simulation for one time step;

• getProperties, to read back the new state of an object.

Other methods can be overridden if necessary, e.g. setup for initialization at the start of the simulation and destroy for cleanup afterward.

Changed in version 3.0: The __init__ method of subclasses should no longer create objects; the createObjectInSimulator method will be called instead. Other initialization which needs to take place after object creation should be done in setup after calling the superclass implementation.

The arguments to __init__ are the same as those to simulate, except that maxIterations is omitted.

Attributes:

• currentTime (int) – Number of time steps elapsed so far.

• timestep (float) – Length of each time step in seconds.

• objects – List of Scenic objects (instances of Object) existing in the simulation. This list will change if objects are created dynamically.

• agents – List of agents in the simulation.

• result (SimulationResult) – Result of the simulation, or None if it has not yet completed. This is the primary object which should be inspected to get data out of the simulation: the other undocumented attributes of this class are for internal use only.

Raises:

RejectSimulationException – if a requirement is violated.

setup()

Set up the simulation to run in the simulator.

Subclasses may override this method to perform custom initialization, but should call the parent implementation to create the objects in the initial scene (through createObjectInSimulator).

abstract createObjectInSimulator(obj)

Create the given object in the simulator.

Implemented by subclasses. Should raise SimulationCreationError if creating the object fails.

Parameters:

obj (Object) – the Scenic object to create.

Raises:

SimulationCreationError – if unable to create the object in the simulator.

scheduleForAgents()

Compute the order for the agents to run in the next time step.

The default order is the order in which the agents were created.

Returns:

An iterable which is a permutation of self.agents.

actionsAreCompatible(agent, actions)

Check whether the given actions can be taken simultaneously by an agent.

The default is to consider all actions compatible with each other, and to call Action.canBeTakenBy to determine if an agent can take an action. Subclasses should override this method as appropriate.

Parameters:

• agent (Object) – the agent which wants to take the given actions.

• actions (tuple) – tuple of actions to be taken.

executeActions(allActions)

Execute the actions selected by the agents.

The default implementation calls the applyTo method of each Action to apply it to the appropriate agent. Subclasses may override this method to make additional simulator API calls as needed, but should call this implementation too or otherwise emulate its functionality.

Parameters:

allActions – an OrderedDict mapping each agent to a tuple of actions. The order of agents in the dict should be respected in case the order of actions matters.

abstract step()

Run the simulation for one step and return the next trajectory element.

Implemented by subclasses. This should cause the simulator to simulate physics for self.timestep seconds.

updateObjects()

Update the positions and other properties of objects from the simulation.

Subclasses likely do not need to override this method: they should implement its subroutine getProperties below.

valuesHaveDiverged(obj, prop, expected, actual)

Decide whether the value of a dynamic property has diverged from the replay.

The default implementation considers scalar and vector properties to have diverged if the distance between the actual and expected values is greater than self.divergenceTolerance (which is 0 by default); other types of properties use the != operator.

Subclasses may override this function to provide more specialized criteria (e.g. allowing some properties to diverge more than others).

Parameters:

• obj (Object) – The object being considered.

• prop (str) – The name of the dynamic property being considered.

• expected – The value of the property saved in the replay currently being run.

• actual – The value of the property in the current simulation.

Returns:

True if the actual value should be considered as having diverged from the expected one; otherwise False.

abstract getProperties(obj, properties)

Read the values of the given properties of the object from the simulator.

Implemented by subclasses.

Parameters:

• obj (Object) – Scenic object in question.

• properties (set) – Set of names of properties to read from the simulator. It is safe to destructively iterate through the set if you want.

Returns:

A dict mapping each of the given properties to its current value.

currentState()

Return the current state of the simulation.

The definition of ‘state’ is up to the simulator; the ‘state’ is simply saved at each time step to define the ‘trajectory’ of the simulation.

The default implementation returns a tuple of the positions of all objects.

property currentRealTime

Current simulation time, in seconds.

destroy()

Perform any cleanup necessary to reset the simulator after a simulation.

The default implementation does nothing by default; it may be overridden by subclasses.

getReplay()

Encode this simulation to a bytes object for future replay.

Requires that the simulation was run with enableReplay=True (the default).

class ReplayMode(value)

Bases: IntFlag

An enumeration.

class DummySimulator(drift=0)

Bases: Simulator

Simulator which does (almost) nothing, for testing and debugging purposes.

To allow testing the change of dynamic properties over time, all objects drift upward by drift every time step.

class DummySimulation(scene, drift=0, **kwargs)

Bases: Simulation

Minimal Simulation subclass for DummySimulator.

class TerminationType(value)

Bases: Enum

Enum describing the possible ways a simulation can end.

timeLimit = 'reached simulation time limit'

Simulation reached the specified time limit.

scenarioComplete = 'the top-level scenario finished'

The top-level scenario finished executing.

(Either its compose block completed, one of its termination conditions was met, or it was terminated with terminate.)

simulationTerminationCondition = 'a simulation termination condition was met'

A user-specified simulation termination condition was met.

terminatedByMonitor = 'a monitor terminated the simulation'

A monitor used terminate simulation to end the simulation.

terminatedByBehavior = 'a behavior terminated the simulation'

A dynamic behavior used terminate simulation to end the simulation.

class SimulationResult(trajectory, actions, terminationType, terminationReason, records)

Result of running a simulation.

Attributes:

• trajectory – A tuple giving for each time step the simulation’s ‘state’: by default the positions of every object. See Simulation.currentState.

• finalState – The last ‘state’ of the simulation, as above.

• actions – A tuple giving for each time step a dict specifying for each agent the (possibly-empty) tuple of actions it took at that time step.

• terminationType (TerminationType) – The way the simulation ended.

• terminationReason (str) – A human-readable string giving the reason why the simulation ended, possibly including debugging info.

• records (dict) – For each record statement, the value or time series of values its expression took during the simulation.