Experimental run

class RecordSensingConfig

Holds the configuration to record sensing during an experimental run

static schema() → object

property agent_indices

Type:

list[int]

The indices of the agents to record

property name

Type:

str

The name of the dataset group

property sensor

Type:

navground.sim.Sensor

The sensor to record, if none, it will the record the behavior sensing state

class RecordNeighborsConfig

Holds the configuration to record neighbors during an experimental run

static schema() → object

property enabled

Type:

bool

Whether to record neighbors or not

property number

Type:

int

The number of neighbors to record. If more, it will record the nearest number record. If fewer, it will pads with zeros.

property relative

Type:

bool

Whether to use a frame relative to the agent or the absolute frame.

class RecordConfig

Holds which data to record during an experimental run

static all(value: bool) → navground.sim.RecordConfig

Sets all to record or not record.

Returns:

The configuration.

record_sensor(name: str, sensor: navground.sim.Sensor, agent_indices: list[int]) → None

Add a sensor to be recorded

Parameters:

• name – The name of the group

• sensor – The sensor to record

• agent_indices – The agent indices whose sensing to record

set_all(value: bool) → None

Sets all to record or not record.

Parameters:

value – The desired value

property actuated_cmd

Type:

bool

Whether to record the agents actuated control commands

property cmd

Type:

bool

Whether to record the agents control commands

property collisions

Type:

bool

Whether to record collisions

property deadlocks

Type:

bool

Whether to record the time since when agents are stuck

property efficacy

Type:

bool

Whether to record efficacy (i.e., fraction of actual velocity vs optimal velocity)

property neighbors

Type:

navground.sim.RecordNeighborsConfig

Whether and how to record neighbors

property pose

Type:

bool

Whether to record the agents poses

property safety_violation

Type:

bool

Whether to record safety violations

property sensing

Type:

list[navground.sim.RecordSensingConfig]

The sensors to record

property target

Type:

bool

Whether to record the agents targets

property task_events

Type:

bool

Whether to record data from task events

property time

Type:

bool

Whether to record the simulation time

property twist

Type:

bool

Whether to record the agents twists

property use_agent_uid_as_key

Type:

bool

Whether to use uid as keys for sensing and task events. Else it will use the agent index.

property world

Type:

bool

Whether to record the initial world state (as YAML)

class ExperimentalRun

Simulates a world and collects data.

add_group_record_probe(key: str, probe: object) → object

Adds a group record probe.

Parameters:

• key (Callable[[], sim.GroupRecordProbe]) – the key of the group to be created

• probe – the probe factory like a GroupRecordProbe class.

add_probe(probe: navground.sim.Probe) → None

Adds a probe

Parameters:

probe – The probe

add_record(key: str, data: object = None, dtype: object = None, item_shape: list[int] = []) → navground.sim.Dataset

Adds a record.

Parameters:

• key (str) – the record key

• data (numpy.typing.ArrayLike | None) – Copies shape, data and dtype from this numpy array (if specified)

• dtype (numpy.typing.DTypeLike | None.) – The type of data to store (if specified and if data is None)

• item_shape (List[int]) – Set the shape of all axis except the first (only if data is None ). Set to an empty list to instantiate a flat dataset.

add_record_probe(key: str, probe: object) → object

Adds a record probe.

Parameters:

• key (Callable[[navground.sim.Dataset], sim.RecordProbe]) – the key of the record to be created

• probe – the probe factory like a RecordProbe class.

static data_from_target(target: navground.core.Target) → list[float]

Encode a target to be stored by a run.

Parameters:

target – The target

Returns:

The data

get_collision_events(min_interval: int = 1) → navground.sim.Dataset

The recorded collision events between pairs of entities as as a Dataset of shape (number of collisions, 3) and dtype np.uint32:

[[time_step, uid_0, uid_1], 
 ...]

Only collision among the same pair separated by at least minimal_interval are returned. The array is empty if collisions have not been recorded in the run.

get_collisions_at_step(step: int) → set[tuple[navground.sim.Entity, navground.sim.Entity]]

Gets recorded collisions at a given step.

Parameters:

step – The step. Negative steps are interpreted as relative to the last registered step, i.e., -1 is the last step.

Returns:

The set of colliding entity pairs.

get_record(key: str = '') → navground.sim.Dataset

Gets the record associated to a given key.

Parameters:

key – The key

Returns:

The record or null if none is found.

get_record_names(group: str = '') → set[str]

Gets the names of records.

Parameters:

group – An optional group. If specified, the looks for record associated to keys <group>/....

Returns:

The record names (relative to the group if specified).

get_records(group: str = '') → dict[str, navground.sim.Dataset]

Gets the records.

Parameters:

group – If specified, limits to records in a given group.

Returns:

The records

get_sensing_for(id: int) → dict[str, navground.sim.Dataset]

Gets the recorded sensing.

Parameters:

id – The agent uid or index (if RecordConfig.use_agent_uid_as_key is not set)

Returns:

The dictionary {key: sensing data}

get_steps_to_collision(min_interval: int = 1) → navground.sim.Dataset

The number of steps to the next recorded collision for each agent as as a Dataset of shape (number of steps, number of agents) and dtype np.uint32:

[[agent_0_steps, agent_1_steps, ...], 
 ...]

get_task_events(*args, **kwargs)

Overloaded function.

1. get_task_events(agent: navground.sim.NativeAgent) -> numpy.ndarray

The recorded events logged by the task of an agent as a numpy array of shape (number events, size of event log) and dtype float:

[[data_0, ...], 
 ...]

The array is empty if the agent’s task has not been recorded in the run.

Parameters:

agent – The agent

Returns:

The events logged by the agent task

2. get_task_events(uid: int) -> object

The recorded events logged by the task of an agent as a numpy array of shape (number events, size of event log) and dtype float:

[[data_0, ...], 
 ...]

The array is empty if the agent’s task has not been recorded in the run.

Parameters:

uid – The uid of the agent

Returns:

The events logged by the agent task

go_to_step(step: int, ignore_collisions: bool = False, ignore_twists: bool = False, ignore_cmds: bool = False, ignore_targets: bool = False, ignore_sensing: bool = False) → bool

Try to advance the world to a given recorded step.

Depending if the data has been recorded, it will update:

• poses

• twists

• cmds

• targets

• sensing

• time

• collisions

Parameters:

• step – The step. Negative steps are interpreted as relative to the last registered step, i.e., -1 is the last step.

• ignore_collisions – Whether to skip setting collisions

• ignore_twists – Whether to skip setting twists

• ignore_cmds – Whether to skip setting [last] commands

• ignore_targets – Whether to skip setting targets

• ignore_sensing – Whether to skip setting sensing

Returns:

True if the operation was possible and false otherwise.

index_of_agent(agent: navground.sim.NativeAgent) → int | None

Associate an index to a given agent.

Data related to agents is stored in this order. For example, poses at a given time step are stored as [[x_0, y_0, z_0], [x_1, y_1, z_1], ...]

where the pose of agent a is at the index returned by this function.

Parameters:

agent – The agent

Returns:

The index of data related to this agent.

reset() → None

Resets the run.

run() → None

Runs a simulation and automatically record data step by step

You don’t need to call start(), update(), stop() beside run() as run() manages all the simulation and recording.

You don’t need to call run() when running an Experiment (see Experiment.run() instead) but only if you are want to perform a run outside of an Experiment.

start() → None

Signals that has simulation has started.

Note that this won’t neither execute the simulation nor record data. It will just record the a time stamp and change the state to running.

You don’t need to call start(), update(), stop(), or run() when running an Experiment (see Experiment.run() instead) but only if you are want to perform a run outside of an Experiment.

Either call start() -> update() periodically after manually advancing the simulation -> stop(), or run() once, which does perform all the steps automatically.

stop() → None

Signals that has simulation has stopped.

Call this after start() to stop the recording of a simulation.

You don’t need to call start(), update(), stop(), or run() when running an Experiment (see Experiment.run() instead) but only if you are want to perform a run outside of an Experiment.

static target_from_data(data: list[float]) → navground.core.Target

Decode a target from data stored by a run.

Parameters:

data – The data

Returns:

The target

update() → None

Signals that data needs to be updated

Note that this won’t execute the simulation. Use it only between start() and stop() calls to collect data about the current world state.

Note that after the maximal number of steps has been recorded, it won’t record any more data.

property actuated_commands

Type:

numpy.ndarray

The recorded actuated commands of the agents as a numpy array of shape (simulation steps, number of agents, 3) and dtype float:

[[[vx_0, vy_0, omega_0], 
  [vx_1, vy_1, omega_1], 
  ...], 
 ...]

The array is empty if actuated commands have not been recorded in the run.

property bounding_box

Type:

navground.sim.BoundingBox

The rectangle that contains the world during the whole run.

property collisions

Type:

numpy.ndarray

The recorded collisions between pairs of entities as as a numpy array of shape (number of collisions, 3) and dtype np.uint32:

[[time_step, uid_0, uid_1], 
 ...]

The array is empty if collisions have not been recorded in the run.

property commands

Type:

numpy.ndarray

The recorded commands of the agents as a numpy array of shape (simulation steps, number of agents, 3) and dtype float:

[[[vx_0, vy_0, omega_0], 
  [vx_1, vy_1, omega_1], 
  ...], 
 ...]

The array is empty if commands have not been recorded in the run.

property deadlocks

Type:

numpy.ndarray

The time since agents are deadlocked as a numpy array of shape (number of agents, ) and dtype float:

[time_0, time_1, ...]

If time_i is negative, the i-th agent is not stuck at the end of the recording. Else, it has been stuck since time_i.

The array is empty if deadlocks have not been recorded in the run.

property duration

Type:

datetime.timedelta

The real-time duration of the run.

property efficacy

Type:

numpy.ndarray

The recorded agents’ efficacy as a numpy array of shape (simulation steps, number of agents) and dtype float:

[[efficacy_0, efficacy_1, ...],
 ...]

The array is empty if efficacy has not been recorded in the run.

property final_sim_time

Type:

float

The last recorded simulation time

property has_finished

Type:

bool

Whether the run is finished.

property maximal_steps

Type:

int

The number of steps execute

property neighbors

Type:

numpy.ndarray

The recorded agents’ neighbors as a numpy array of shape (simulation steps, number of agents, number of neighbors, 5) and dtype float:

[[[radius, x, y, vx, vy]],
 ...]

The array is empty if efficacy has not been recorded in the run.

property poses

Type:

numpy.ndarray

The recorded poses of the agents as a numpy array of shape (simulation steps, number of agents, 3) and dtype float:

[[[x_0, y_0, theta_0], 
  [x_1, y_1, theta_1], 
  ...], 
 ...]

The array is empty if poses have not been recorded in the run.

property record_config

Type:

navground.sim.RecordConfig

The record config on which data to record

property record_names

Type:

set[str]

The names of records.

Parameters:

group – an optional group. if specified, the looks for record associated to keys <group>/....

property recorded_steps

Type:

int

The number of recorded steps.

property records

Type:

dict[str, navground.sim.Dataset]

The records.

Parameters:

group – if specified, limits to records in a given group.

property safety_violations

Type:

numpy.ndarray

The recorded amounts of safety violation as a numpy array of shape (simulation steps, number of agents) and dtype float:

[[violation_0, violation_1, ...],
 ...]

where a value of 0 represents no violations.

The array is empty if safety violations have not been recorded in the run.

property seed

Type:

int

The seed used to initialize the simulation.

property sensing

Type:

dict[int, dict[str, navground.sim.Dataset]]

The recorded sensing.

property targets

Type:

numpy.ndarray

The recorded targets of the agents as a numpy array of shape (simulation steps, number of agents, 14) and dtype float:

[[[position?, position[0], position[1], orientation?, orientation, 
   speed?, speed, direction?, direction[0], direction[1],
   angular_speed?, angular_speed, position_tol, orientation_tol], 
   ...] 
 ...]

where <x>? is 1.0 if the field is defined with value <x>, else <x>? is 0.0 and value <x> is set to zero.

The array is empty if targets have not been recorded in the run.

property task_events

Type:

dict[int, object]

The recorded events logged by the tasks all agents as a dictionart of numpy array of shape (number events, size of event log) and dtype float:

{<agent_uid>: [[data_0, ...], ...]}

The array are empty if the agent’s task has not been recorded in the run.

Returns:

The events logged by the tasks all agents

property terminate_when_all_idle_or_stuck

Type:

bool

Whether to terminate when all agents are idle or stuck.

property time_step

Type:

float

The time step used for simulation.

property times

Type:

numpy.ndarray

The recorded simulation times as a numpy array of shape (simulation steps) and dtype float:

[t_0, t_1, ...]

The array is empty if times have not been recorded in the run.

property twists

Type:

numpy.ndarray

The recorded twists of the agents as a numpy array of shape (simulation steps, number of agents, 3) and dtype float:

[[[vx_0, vy_0, omega_0], 
  [vx_1, vy_1, omega_1], 
  ...], 
 ...]

The array is empty if twist have not been recorded in the run.

property world

Type:

navground.sim.NativeWorld

Returns the simulated world.