navground_sim

This package extend navigation playground with all you need to perform simulations and record data.

Dependencies

• navground_core the core library

• GEOS for computational geometry

• HighFive to write HDF5 files

Libraries

navground_sim

A C++ library to perform navigation simulations; see the API reference.

To use the library in a C++ CMake project:

1. add the dependency in CMakeLists.txt

   find_package(navground_sim REQUIRED)
   # if using ament
   # ament_target_dependencies(<MYTARGET> navground_sim)
   # else
   target_link_libraries(<MYTARGET> PRIVATE navground_sim::navground_sim)
   

2. include the appropriate headers in your code

   #include "navground/sim/world.h"
   

Executables

info

Lists registered components (behaviors, kinematics, behavior modulations, state estimations, tasks, and scenarios) implemented in C++.

usage: info [-h] [--no-plugins] [--build] [--properties] [--description] [--behaviors [BEHAVIORS]] [--kinematics [KINEMATICS]]
            [--modulations [MODULATIONS]] [--state_estimations [STATE ESTIMATIONS]] [--tasks [TASKS]] [--scenarios [SCENARIOS]]

Named Arguments

--no-plugins

Do not load plugins

--build

Include build infos

--properties

Include properties

--description

Include property descriptions

--behaviors

selects behaviors

--kinematics

selects kinematics

--modulations

selects modulations

--state_estimations

selects state estimations

--tasks

selects tasks

--scenarios

selects scenarios

Example

$ info --properties

Installed components
====================
Behaviors
---------
CppPolicy
    flat: false (bool)
    include_angular_speed: false (bool)
    include_target_direction: false (bool)
    include_target_distance: false (bool)
    include_target_speed: false (bool)
    include_velocity: false (bool)
    max_acceleration: 10 (float)
    max_angular_acceleration: 0 (float)
    policy_path:  (str)
    shared: false (bool)
    use_acceleration_action: false (bool)
Dummy
    environment:  (str)
HL
    aperture: 3.14159 (float)
...

echo

Load and then print a YAML representation of an object (behavior, kinematic, behavior modulation, state estimation, task, scenarios, agent, world, experiment).

usage: echo [-h] [--no-plugins] [--chdir] kind YAML

Positional Arguments

kind

The kind of object to load: behavior, modulation, kinematics, state_estimation, task, scenario, world, agent, experiment

YAML

YAML string, or path to a YAML file, describing an experiment

Named Arguments

--no-plugins

Do not load plugins

--chdir

Whether to change working directory to the directory containing the file. Useful when the config contains relative paths.

Example

$ echo scenario "{type: Corridor, agent_margin: 0.25, width: 2}"

type: Corridor
add_safety_to_agent_margin: true
agent_margin: 0.25
length: 10
width: 2
obstacles:
  []

schema

Print JSON-Schema of YAML-convertible navground sim classes.

usage: schema [-h] [--no-plugins] [--register] [--type TYPE]
              [{agent,behavior_modulation,behavior,core,task,world,experiment,state_estimation,kinematics,sim,scenario}]

Positional Arguments

kind

Possible choices: agent, behavior_modulation, behavior, core, task, world, experiment, state_estimation, kinematics, sim, scenario

The target type of the scheme

Named Arguments

--no-plugins

Do not load plugins

--register

Whether to generate the register schema instead of the base class schema

--type

If provided, generates the schema for the sub-class registered under this name

Example

$ schema sim

$id: http://navground/sim
$schema: https://json-schema.org/draft/2020-12/schema
$defs:
  vector2:
    type: array
    items:
      type: number
    minItems: 2
    maxItems: 2
    $id: http://navground/vector2
    $schema: https://json-schema.org/draft/2020-12/schema
  line_segment:
    type: array
    items:
      $ref: vector2
    minItems: 2
    maxItems: 2
    $id: http://navground/line_segment
    $schema: https://json-schema.org/draft/2020-12/schema
  disc:
...

plugins

Load and list plugins.

usage: plugins [-h] [--dependencies]

Named Arguments

--dependencies

Display dependencies of C++ plugins

Example

$ plugins

navground_demos
---------------
Scenarios: ThymioDemo

navground_examples
------------------
Behaviors: Idle
Scenarios: Empty

sample

Samples a world from a scenario containing components implemented in C++.

usage: sample [-h] [--no-plugins] [--chdir] YAML

Positional Arguments

YAML

YAML string, or path to a YAML file, describing an experiment

Named Arguments

--no-plugins

Do not load plugins

Default: False

--chdir

Whether to change working directory to the directory containing the file. Useful when the config contains relative paths.

Default: False

Example

$ sample "{type: Antipodal, groups: [{number: 2}]}"

type: Antipodal
orientation_noise: 0
position_noise: 0
radius: 1
shuffle: 0
tolerance: 0.100000001
obstacles:
  []
groups:
  - behavior:
      type: ""
    number: 2
------------------------------
obstacles:
  []
walls:
  []
agents:
  - behavior:
      optimal_speed: 0
...

run

Run an experiment limited to components implemented in C++.

usage: run [-h] [--no-plugins] [--tqdm] [--run_index RUN_INDEX] [--runs RUNS] [--threads THREADS] [--processes PROCESSES]
           [--save_directory SAVE_DIRECTORY] [--save_single_hdf5] [--use_multiprocess] [--chdir]
           YAML

Positional Arguments

YAML

YAML string, or path to a YAML file, describing an experiment

Named Arguments

--no-plugins

Do not load plugins

Default: False

--tqdm

Display tqdm bar

Default: False

--run_index

Will overwrite the experiment own run_index if positive.

Default: -1

--runs

Will overwrite the experiment own runs if positive.

Default: -1

--threads

Number of threads

Default: 1

--processes

Number of processes

Default: 1

--save_directory

Where to save the experiment. If not specified, it reads the value from the configuration

--save_single_hdf5

Whether to store a single HDF5 file when using multiple processes

Default: False

--use_multiprocess

Whether to use the multiprocess package instead of multiprocessings

Default: False

--chdir

Whether to change working directory to the directory containing the file. Useful when the config contains relative paths.

Default: False

If the experiment is recording data, it will create a directory named <experiment_name>_<experiment_hash>_<datestamp> with

• an HDF5 file data.h5` with data recorded during the experiment,

• a YAML file experiment.yaml with the configuration of the experiment.

Example

$ run "{save_directory: "/tmp", scenario: {type: Antipodal, groups: [{number: 20}]}}"

Performing experiment ...
Experiment done
Duration: 0.0367623 s
Saved to: "/tmp/experiment_3812492788053772637_2025-01-09_14-51-13/data.h5"

Note

Although individual runs execute in a single thread, we can speed up experiments consisting of multiple runs by parallelizing them. Check out the related guide to know more.

navground

A command that contains all other commands of this package as sub-commands, installed in the binary directory. Using it, you can run

$ naground <command> [arguments]

instead of

$ install/lib/navground_sim/<command> [arguments]

Example

$ navground run --help
Usage: run [--help] [--version] [--tqdm] [--run_index VAR] [--runs VAR] [--threads VAR] [--processes VAR] [--save_directory VAR] [--chdir] YAML

Runs an experiment.

Positional arguments:
  YAML              YAML string, or path to a YAML file, describing an experiment 

Optional arguments:
  -h, --help        shows help message and exits 
  -v, --version     prints version information and exits 
  --tqdm            Display tqdm bar 
  --run_index       Will overwrite the experiment own run_index if positive. [nargs=0..1] [default: -1]
  --runs            Will overwrite the experiment own runs if positive. [nargs=0..1] [default: -1]
  --threads         Number of threads [nargs=0..1] [default: 1]
  --processes       Number of processes [only supported by Python] [nargs=0..1] [default: 1]
  --save_directory  Where to save the experiment. If not specified, it reads the value from the configuration 
  --chdir           Whether to change working directory to the directory containing the file. Useful when the config contains relative paths
...