Experiment

class Experiment

An experiment supervises the execution of several runs of simulation.

It initializes simulations sharing the same Scenario and run them while collecting the desired data through ExperimentalRun.

• use run_once() to perform a single run.

• use run() to perform all runs, optionally saving the data to a HDF5 dataset.

• use start(), stop(), start_run(), stop_run(), update_run() to record data without launching a simulation, for instance if you are using a different run-loop.

__init__(time_step: float = 0.1, steps: int = 1000) → None

Constructs a new instance.

Parameters:

• time_step – The default simulation time step

• steps – The default number of simulation steps

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

Register a probe to record a group of data to during all runs.

Parameters:

• key (Callable[[], sim.GroupRecordProbe]) – the name associated to the group

• probe – the probe factory like a GroupRecordProbe class.

add_probe(probe: object) → None

Register a probe to be added to all runs

Parameters:

factory – A function that generate the probe.

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

Register a probe to record data to during all runs.

Parameters:

• key (Callable[[navground.sim.Dataset], sim.RecordProbe]) – the name associated to the record

• probe – the probe factory like a RecordProbe class.

add_run(seed: int, run: navground.sim.ExperimentalRun) → None

add_run_callback(callback: object, at_init: bool = False) → None

Adds a callback to be executed before/after each run.

Parameters:

• value – The callback

• at_init – Whether the callback should be called when initializing the run. If not set, it will be called at the completion of a run.

clear_run_callbacks() → None

Remove all run callbacks

dump() → str

Dumps the object to a YAML-string.

Returns:

The YAML representation

Return type:

str

get_run(index: int) → navground.sim.ExperimentalRun

init_run(seed: int, world: navground.sim.NativeWorld = None) → navground.sim.ExperimentalRun

Initializes a run

Parameters:

• seed – The random seed

• world – The world to simulate. If null, it will initialize a new world.

See start(). This is only need when using an external run-loop to simulate or when manually calling ExperimentalRun.run() later. Else use run_once() (or run() for all runs) to initialize and run at once.

static load(value: str) → object

Load a experiment from a YAML string.

Parameters:

value – the YAML string.

Returns:

The loaded experiment or None if loading fails.

Return type:

Experiment| None

remove_all_runs() → None

Clear the recording

remove_run(seed: int) → None

Removes a recorded run.

Parameters:

seed – The seed/index of the run

run(keep: bool = True, number_of_threads: int = 1, start_index: int | None = None, number_of_runs: int | None = None, data_path: os.PathLike | None = None) → None

Perform several runs and optionally record the data in a HFD5 file.

The number of runs is specified by the default number_of_runs if not specified.

Runs will be indexed sequentially and their index used as a random seed.

If save_directory not empty but points to an existing directory, it creates a HDF5 file <name>_<hash>_<timestamp>/data.h5 with attributes

• begin_time [string], ISO 8601 formatted string of the time when the experiment is run, see begin_time;

• duration_ns [unsigned], total duration in nanoseconds, see duration.

• experiment [string], YAML serialization of the experiment;

Moreover, at the end of each run, it saves a group run_<index> with attributes:

• duration_ns [unsigned], total duration in nanoseconds, see duration;

• seed [unsigned];

• steps [unsigned], actual number of steps performed;

• maximal_steps [unsigned], maximal number of steps that could have been performed;

• final_sim_time [float], the simulated time at the end of the run;

• world [string], YAML serialization of the world at the begin of the experiment.

datasets:

• times [float] (if RecordConfig.time is set);

• poses [float] (if RecordConfig.pose is set);

• twists [float] (if RecordConfig.twist is set);

• cmds [float] (if RecordConfig.cmd is set);

• actuated_cmds [float] (if RecordConfig.actuated_cmd is set);

• targets [float] (if RecordConfig.target is set);

• collisions [unsigned] (if RecordConfig.collisions is set);

• deadlocks [float] (if RecordConfig.deadlocks is set);

• efficacy [float] (if RecordConfig.efficacy is set);

• safety_violations [float] (if RecordConfig.safety_violation is set);

and groups:

• task_events (if RecordConfig.task_events is set), where each agents logs, in dataset task_events/<id> [float], the events emitted by their task.

Apart from saving data to the HDF5 file, each run is performed similarly to run_once().

Parameters:

• keep – Whether to keep runs in memory

• number_of_threads – How many threads to use. When more than one, runs will be distributed in parallel over the threads.

• start_index – The index/seed of the first run. If unspecified, it will use the experiment’s run_index

• number_of_runs – The number of runs. If unspecified, it will use the experiment’s number_of_runs

• data_path – A path to set optionally as path. If set, it will save an HDF5 file, but no YAML, to this path. If not set, path will be automatically set to <save_directory>/data.h5 if save_directory is set.

run_mp(number_of_processes: int, keep: bool = False, number_of_runs: int | None = None, start_index: int | None = None, callback: Callable[[int], None] | None = None, bar: tqdm.tqdm[Any] | None = None, scenario_init_callback: ScenarioInitCallback | None = None, use_multiprocess: bool = False, load_plugins: bool = True) → None

Run an experiment distributing its runs in parallel over multiple processes.

Use this to parallelize experiments that contains Python classes, see :py:fun:uses_python, Experiment.run parallelizes over multiple threads instead and cannot be used to run such experiments because of the GIL.

If keep=True, the experiment will query the runs from the different processes and hold them in memory. If it is configured to save the data, it will save a single HDF5 file.

If keep=False, the experiment won’t keep the runs in memory. If it is configured to save the data, it will save one HDF5 file per process ("data_<i>.h5") and one “data.h5” linking all the runs together. To access the data, you will need to load the HFD5 file.

Parameters:

• experiment – The experiment

• number_of_processes – The number of processes

• keep – Whether to keep runs in memory

• number_of_runs – The number of runs

• start_index – The index of the first run

• callback – An optional callback to run after each run is completed

• bar – An optional tqdm bar to display the progresses.

• scenario_init_callback – An optional callback to set as Experiment.scenario_init_callback.

• use_multiprocess – Whether to use the multiprocess package instead of multiprocessing

• load_plugins – Whether load the plugins in the processes

run_once(seed: int) → navground.sim.ExperimentalRun

Perform a single run

1. it initializes a world from its scenario by calling Scenario.init_world()

2. it runs the simulation, step by step, collecting data in a ExperimentalRun by calling ExperimentalRun.run()

Parameters:

seed – The index (and random seed) of the run

Returns:

The recorded run.

save(directory: os.PathLike | None = None, path: os.PathLike | None = None) → None

Save all recorded runs.

Parameters:

• directory – A path to set optionally as save_directory where to save YAML and HDF5 file.

• path – A path to set optionally as path. If set, it will save an HDF5 file, but no YAML, to this path. If not set, path will be automatically set to <save_directory>/data.h5 if save_directory is set.

static schema() → object

Returns the json-schema

Returns:

json-schema

Return type:

dict[str, typing.Any]

setup_tqdm(bar: tqdm.tqdm[Any], number_of_runs: int | None = None) → None

Configure a tqdm object that displays the progress of an experiment

Parameters:

• bar – a tqdm progress bar

• number_of_runs – the number of runs to track. If not provided, it will use sim.Experiment.number_of_runs.

start(path: os.PathLike | None = None) → None

Signal to start an experiment

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

This is only needed when using an external run-loop for the simulation. In this case:

1. call start()

2. For each run

i. Call init_run() and start_run() ii. from your run-loop, call update_run() to record the current state of the simulated world iii. Call stop_run()

3. Call stop()

Use run() instead to perform the simulations and record them all at once.

Calling start() is only effective once per experiment.

Parameters:

path – A path to set optionally as path. If set, it will save an HDF5 file, but no YAML, to this path. If not set, path will be automatically set to <save_directory>/data.h5 if save_directory is set.

start_run(run: navground.sim.ExperimentalRun) → None

Start recording a run

See start(). This is only need when using an external run-loop to simulate.

Call start_run() only once per run.

Parameters:

run – The run being recorded

stop(save_runs: bool = False) → None

Signal to stop an experiment

Parameters:

save_runs – Whether to save the runs before closing

See start(). This is only need when using an external run-loop to simulate.

stop_run(run: navground.sim.ExperimentalRun) → None

Stop the run recording

See start_run(). This is only need to use an external run-loop.

Parameters:

run – The run being recorded

update_run(run: navground.sim.ExperimentalRun) → None

{ function_description }

See start(). This is only need when using an external run-loop to simulate.

Call update_run() every time you need to record the current state of the world, typically after each simulation step.

Parameters:

run – The run being recorded

property begin_time

Type:

datetime.datetime

The system time when the experiment began.

property duration

Type:

datetime.timedelta

The duration required to perform the whole experiment.

property has_finished

Type:

bool

Determines if the experiment has finished.

property is_running

Type:

bool

Determines if the experiment is running.

property name

Type:

str

The name of the experiment

property number_of_runs

Type:

int

Default number of runs to perform

property path

Type:

Optional[os.PathLike]

The path where the experimental data has been saved.

property record_config

Type:

navground.sim.RecordConfig

A reference to the record config on which data to record

property record_scenario_properties

Type:

bool

Whether to record (sampled) scenario properties as world attributes

property reset_uids

Type:

bool

Whether to reset the Entities UID to zero before each run

property run_callbacks

Type:

dict[bool, list[Callable[[navground.sim.ExperimentalRun], None]]]

The run callbacks

property run_index

Type:

int

The seed/index of the next run

property runs

Type:

dict[int, navground.sim.ExperimentalRun]

The map of recorded runs.

runs are associated to the seed used to initialize them.

property save_directory

Type:

os.PathLike

Where to save the results

property scenario

Type:

navground.sim.Scenario

The scenario used to initialize a world

property scenario_init_callback

Type:

Optional[Callable[[navground.sim.Scenario, int], None]]

The callback called before the scenario initializes a world.

property steps

Type:

int

The default maximal number of steps to simulate during each run.

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 default time step used for simulation during each run