SIMULATION MANAGER

class invertedai.SimulationManager(scene_plotter_cfg: Optional[ScenePlotterConfig] = None, waypoint_cfg: Optional[WaypointManagerConfig] = None, log_writer_cfg: Optional[LogWriterConfig] = None)

Stateful class for managing keyed agents with an internal dictionary SimulationAgentDict to manage AgentData by AgentID

and provides wrappers around the IAI large_initialize and large_drive APIs

Parameters: scene_plotter_cfg : Optional[ScenePlotterConfig]

Configuration object used to initialize a ScenePlotter instance Enables birdview visualization and animation of the simulation

waypoint_cfgOptional[WaypointManagerConfig]

Configuration for initializing a WaypointManager If provided waypoints will be dynamically updated during simulation

log_writer_cfgOptional[LogWriterConfig]

Configuration for enabling structured logging of the simulation If provided all initialize and drive steps will be recorded to a JSON log

drive(external_agent_data: Optional[DefaultDict[str, AgentData]] = None, **kwargs) → DriveResponse

Advance the simulation by one timestep with large_drive() using the data from agents

in self.agents_dict and optionally provided external_agent_data

This method: - updates self.agents_dict with results from large_drive - uses iai.WaypointManager to update waypoints if configured - Records visualization and logging outputs if configured

Parameters: external_agent_data : Optional[SimulationAgentDict]

Optional stateless dictionary of externally created agents to

drive alongside internal self.agents_dict at this timestep

Requires both valid state and properties to be provided for each agent in the dictionary You can use the Scenario Builder tool available on the Inverted AI website to validate an agent’s state and properties

Returns:

DriveResponse

Please see large_drive() for information on kwargs

Note: - agent_states, agent_properties, and recurrent_states should not be

provided in kwargs. These values are automatically derived from the internal agent dictionary and managed by this wrapper

• For all other supported parameters, please refer to the documentation for large_drive()

export_log(path: Optional[str] = None)

Export the log of the simulation to a JSON file if logging was enabled with a

LogWriterConfig during initialization of the SimulationManager

Parameters: path : Optional[str]

Optional path to specify where the log should be saved. If None, will default to the path provided in LogWriterConfig during initialization.

If no path is provided in either place, will raise an error.

initialize(regions: List[Region], external_agent_data: Optional[DefaultDict[str, AgentData]] = None, **kwargs) → InitializeResponse

Initialize simulation using large_initialize() with agents in self.agents_dict along with any optionally provided external_agent_data

Parameters: regions : List[Region]

Regions with presampled agents. use iai.get_regions_default() to obtain list of Regions

external_agent_dataOptional[SimulationAgentDict]

Optional stateless dictionary of externally created agents to initialize alongside internal self.agents_dict Requires valid properties and optional state to be provided for each agent in the dictionary You can use the Scenario Builder tool available on the Inverted AI website to validate an agent’s state and properties

Please see large_initialize() for documentation on **kwargs

Note: - agent_states, agent_properties, and recurrent_states should not be

provided in **kwargs. These values are automatically derived from the internal agent dictionary and managed by this wrapper

• For all other supported parameters, please refer to the documentation for large_initialize()

insert_agents(agent_data_list: List[AgentData], ids: Optional[List[str]], overwrite: bool = False)

Insert multiple agents into the existing agents_dict using their AgentData

Parameters: agent_data_list : List[AgentData]

List of AgentData for each agent to be inserted

idsOptional[List[str]]

Optional list of AgentIDs to use for the new agents. If None, random UUIDs will be generated for each new agent.

overwrite: bool

If True, allows new agents to overwrite existing agents with the same ID.

remove_agents(agent_ids: List[str])

Removes multiple agents from the SimulationManager given their AgentIDs

Parameters: agent_ids : List[str]

List of AgentIDs to remove

Raises: KeyError

If any AgentID does not exist in self.agents_dict

visualize_data(**kwargs) → FuncAnimation

Produce an animation of sequentially recorded steps. If a ScenePlotter was configured during initialization,

recorded steps from each drive will be visualized using the birdview map and static actors.

A matplotlib animation object can be returned and/or a gif saved of the scene.

For kwargs, please see documentation from animate_scene() in the ScenePlotter class