navground_sim

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:

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)

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] [-v] [--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
-v, --version: show program’s version number and exit
--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, sampler).

usage: echo [-h] [--no-plugins] [-v] [--chdir] [--type {bool,int,float,str,vector,[bool],[int],[float],[str],[vector]}] kind YAML

Positional Arguments#

kind: The kind of object to load: behavior, modulation, kinematics, state_estimation, task, scenario, world, agent, experiment, sampler
YAML: YAML string, or path to a YAML file, describing an experiment

Named Arguments#

--no-plugins

Do not load plugins

-v, --version

show program’s version number and exit

--chdir

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

--type

Possible choices: bool, int, float, str, vector, [bool], [int], [float], [str], [vector]

The sampled type

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] [-v] [--register] [--type TYPE]
              [{kinematics,scenario,agent,core,experiment,sim,world,behavior_modulation,behavior,task,state_estimation}]

Positional Arguments#

kind

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

The target type of the scheme

Named Arguments#

--no-plugins: Do not load plugins
-v, --version: show program’s version number and exit
--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] [-v] [--dependencies]

Named Arguments#

-v, --version: show program’s version number and exit
--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++, or from a sampler.

usage: sample [-h] [--no-plugins] [-v] [--seed SEED] [--type TYPE] [--number NUMBER] [--chdir] YAML

Positional Arguments#

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

Named Arguments#

--no-plugins

Do not load plugins

Default: False

-v, --version

show program’s version number and exit

--seed

The random seed

Default: 0

--type

The sampled value

Default: ''

--number

The number of samples

Default: 1

--chdir

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

Default: False

Example (scenario)#

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

Sampled world
=============

obstacles:
  []
walls:
  []
agents:
  - behavior:
      optimal_speed: 0
      optimal_angular_speed: 0
      rotation_tau: 0.5
      safety_margin: 0
      horizon: 5
      path_look_ahead: 1
      path_tau: 0.5
      radius: 0
      heading: velocity
      social_margin:
        modulation:
...

Example (sampler)#

$ sample "{sampler: uniform, from: 0, to: 10}" --type int --number 5

Sampled int
===========

0: 5
1: 0
2: 3
3: 3
4: 7

run#

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

usage: run [-h] [--no-plugins] [-v] [--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

-v, --version

show program’s version number and exit

--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.0362629 s
Saved to: "/tmp/experiment_1622124573627242003_2025-06-07_16-32-21/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
...

navground_sim

Contents

navground_sim#

Dependencies#

Libraries#

navground_sim#

Executables#

info#

Named Arguments#

Example#

echo#

Positional Arguments#

Named Arguments#

Example#

schema#

Positional Arguments#

Named Arguments#

Example#

plugins#

Named Arguments#

Example#

sample#

Positional Arguments#

Named Arguments#

Example (scenario)#

Example (sampler)#

run#

Positional Arguments#

Named Arguments#

Example#

navground#

Example#