scenic.core.simulators

Interface between Scenic and simulators.

Summary of Module Members

Classes

Action	An action which can be taken by an agent for one step of a simulation.
DummySimulation	Minimal Simulation subclass for DummySimulator.
DummySimulator	Simulator which does nothing, for debugging purposes.
EndScenarioAction	Special action indicating it is time to end the current scenario.
EndSimulationAction	Special action indicating it is time to end the simulation.
Simulation	A single simulation run, possibly in progress.
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

RejectSimulationException	Exception indicating a requirement was violated at runtime.
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 RejectSimulationException

Bases: Exception

Exception indicating a requirement was violated at runtime.

class Simulator

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 a simple example of how to implement this class, and its counterpart Simulation for individual simulations, see scenic.simulators.lgsvl.simulator.

simulate(scene, maxSteps=None, maxIterations=100, verbosity=None, raiseGuardViolations=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.

• 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).

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.

createSimulation(scene, verbosity=0)

Create a Simulation from a Scenic scene.

This should be overridden by subclasses to return instances of their own specialized subclass of Simulation.

destroy()

Clean up as needed when shutting down the simulator interface.

class Simulation(scene, timestep=1, verbosity=0)

A single simulation run, possibly in progress.

These objects are not manipulated manually, but are created and executed by a Simulator. Simulator interfaces should subclass this class, overriding abstract methods like createObjectInSimulator, step, and getProperties to call the appropriate simulator APIs.

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 attributes of this class are primarily for internal use.

run(maxSteps)

Run the simulation.

Throws a RejectSimulationException if a requirement is violated.

createObject(obj)

Dynamically create an object.

createObjectInSimulator(obj)

Create the given object in the simulator.

Implemented by subclasses, and called through createObject. Should raise SimulationCreationError if creating the object fails.

scheduleForAgents()

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

actionsAreCompatible(agent, actions)

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

The default is to have all actions compatible with each other and all agents. Subclasses should override this method as appropriate.

executeActions(allActions)

Execute the actions selected by the agents.

Note that allActions is an OrderedDict, as the order of actions may matter.

step()

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

updateObjects()

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

getProperties(obj, properties)

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

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.

destroy()

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

class DummySimulator(timestep=1)

Bases: Simulator

Simulator which does nothing, for debugging purposes.

class DummySimulation(scene, timestep=1, verbosity=0)

Bases: Simulation

Minimal Simulation subclass for DummySimulator.

class Action

An action which can be taken by an agent for one step of a simulation.

class EndSimulationAction(line)

Bases: Action

Special action indicating it is time to end the simulation.

Only for internal use.

class EndScenarioAction(line)

Bases: Action

Special action indicating it is time to end the current scenario.

Only for internal use.

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’s compose block finished executing.

simulationTerminationCondition = 'a simulation termination condition was met'

A user-specified termination condition was met.

terminatedByMonitor = 'a monitor terminated the simulation'

A monitor used terminate to end the simulation.

terminatedByBehavior = 'a behavior terminated the simulation'

A dynamic behavior used terminate 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.