navground_sim_py

navground_sim_py#

This package provides Python bindings to the simulation library and utilities to display the simulation.

Dependencies#

navground_core_py the core python package
navground_sim the simulation library

Python packages#

navground.sim#

A Python package to perform navigation simulations; see the API reference.

To use the package

add the install path to PYTHONPATH
import the packge
```
from navground import sim
```

Executables#

info#

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

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.0 (float)
    max_angular_acceleration: 0.0 (float)
    policy_path:  (str)
    shared: False (bool)
    use_acceleration_action: False (bool)
Dummy
    environment:  (str)
GroupPolicy
    deterministic: False (bool)
...

echo#

Load and then print a YAML representation of an object (behavior, kinematic, behavior modulation, state estimation, task, scenarios, agent, world, experiment, sampler). It is equivalent to the C++ version but with additional components implemented in Python.

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 task "{type: Path, points: [[1, 2], [3, 4]]}"

type: Path
points:
  -
    - 1
    - 2
  -
    - 3
    - 4
tolerance: 1

schema#

Print JSON-Schema of YAML-convertible navground sim classes. It is equivalent to the C++ version but with additional components implemented in Python.

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 task

$id: http://navground/task
$ref: task_register
$schema: https://json-schema.org/draft/2020-12/schema
properties:
  type:
    type: string
type: object
unevaluatedProperties: false

validate#

Validates a YAML representation of an object (behavior, kinematic, behavior modulation, state estimation, task, scenarios, agent, world, experiment, sampler) against the schema generated by schema using python-jsonschema.

usage: validate [-h] [--no-plugins] [-v] [--type {bool,int,float,str,vector,[bool],[int],[float],[str],[vector]}]
                {behavior,behavior_modulation,kinematics,state_estimation,task,agent,world,scenario,experiment,sampler} YAML

Positional Arguments#

kind

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

The kind of object to validate

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

--type

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

The sampled type

Example#

$ validate task "{type: UnknownTask}"

{'type': 'UnknownTask'} is not valid under any of the given schemas

Failed validating 'anyOf' in schema:
    {'$schema': 'https://json-schema.org/draft/2020-12/schema',
     '$id': 'http://navground/task_register',
     'anyOf': [{'properties': {'type': {'const': 'Direction'},
                               'direction': {'$ref': 'vector2',
                                             'default': [1, 0],
                                             'description': 'direction'}}},
               {'properties': {'type': {'const': 'GoToPose'},
                               'angular_tolerance': {'type': 'number',
                                                     'default': inf,
                                                     'description': 'Angular '
                                                                    'tolerance '
                                                                    '[rad]'},
                               'orientation': {'type': 'number',
                                               'default': 0,
                                               'description': 'Goal '
                                                              'orientation '
                                                              '[rad]'},
...

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_examples_py
---------------------
Behaviors: PyIdle [Python]

navground_demos
---------------
Scenarios: PyThymioDemo [Python], ThymioDemo [C++]

navground_examples
------------------
Behaviors: Idle [C++]
Scenarios: Empty [C++]

sample#

Samples a world from a scenario with components implemented in C++ or Python, 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 using a Python interpreter. It may be slightly slower than the C++ implementation, but has access to components implemented in Python.

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 using Python ...
Experiment done
Duration:  0.028 s
Saved to: /tmp/experiment_15485119806850053049_2025-06-07_16-32-36/data.h5

Note

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

run_rt#

Run an experiment using Python in real time. You can visualize the world in a browser view.

usage: run_rt [-h] [--no-plugins] [-v] [--factor FACTOR] [--no-ui] [--seed SEED] [--port PORT] [--width WIDTH] [--no-browser] [--ui-fps UI_FPS]
              [--background-color BACKGROUND_COLOR] [--area MIN_X MIN_Y MAX_X MAX_Y] [--display-shape] [--display-deadlocks] [--display-collisions]
              [--html HTML]
              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

--factor

Real-time factor (set to 1.0 to run in real-time, set to higher to run faster or to lower to run slower then real-time)

Default: 1.0

--no-ui

Do not use a view

Default: False

--seed

The random seed of the simulation. If negative, it will be picked randomly

Default: -1

--port

The websocket port

Default: 8000

--width

Size of the view in pixels

Default: 500

--no-browser

Do not open a browser view

Default: False

--ui-fps

Maximal update rate of the view

Default: 25.0

--background-color

View background color

Default: 'lightgray'

--area

Minimal area rendered in the view

--display-shape

Display effective agent shape

Default: False

--display-deadlocks

Color deadlocked agent in blue

Default: False

--display-collisions

Color deadlocked agent in red

Default: False

--html

Where to save the HTML file. Leave empty to use a temporary directory

Default: ''

Example#

$ run_rt experiment.yaml --factor 5.0

record video#

Record a video from an experiment.

usage: record_video [-h] [--no-plugins] [-v] [--seed SEED] [--factor FACTOR] [--width WIDTH] [--fps FPS] [--background-color BACKGROUND_COLOR]
                    [--area MIN_X MIN_Y MAX_X MAX_Y] [--relative_margin RELATIVE_MARGIN] [--display-shape] [--follow FOLLOW] [--grid GRID] [--chdir]
                    input output

Positional Arguments#

input: YAML string, or path to a YAML file describing an experiment, or a path to HDF5 file of a recorded experiment
output: Path where to save the video

Named Arguments#

--no-plugins

Do not load plugins

Default: False

-v, --version

show program’s version number and exit

--seed

The random seed of the simulation. If negative, it will be picked randomly

Default: -1

--factor

Real-time factor (set to 1.0 to run in real-time, set to higher to run faster or to lower to run slower then real-time)

Default: 1.0

--width

Size of the video in pixels

Default: 640

--fps

Video fps

Default: 24

--background-color

View background color

Default: 'lightgray'

--area

Minimal area rendered in the view

--relative_margin

A relative margin to add around the area

Default: 0.05

--display-shape

Display effective agent shape

Default: False

--follow

The index of the agent to follow

Default: -1

--grid

The size of the grid

Default: 0

--chdir

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

Default: False

Example#

$ record_video experiment.yaml video.mp4 --factor 5.0

replay#

Replays an experiment in real-time. You can visualize the world in a browser view, similarly to run_rt but for recorded experiment, or create a video from it.

usage: replay [-h] [-v] [--factor FACTOR] [--no-ui] [--record_video RECORD_VIDEO] [--no-browser] [--ui-fps UI_FPS] [--seed SEED]
              [--background-color BACKGROUND_COLOR] [--html HTML]
              path

Positional Arguments#

path: The path an HDF5 file that store an experiment

Named Arguments#

-v, --version

show program’s version number and exit

--factor

Real-time factor (set to 1.0 to run in real-time, set to higher to run faster or to lower to run slower then real-time)

Default: 1.0

--no-ui

Do not use a view

Default: False

--record_video

The path to a folder where to save videos instead of replaying in an UI. If left empty, it will not create videos.

Default: ''

--no-browser

Do not open a browser view

Default: False

--ui-fps

Maximal update rate of the view

Default: 25.0

--seed

The seed of the run to replay. If negative or not specified, will replay all runs

Default: -1

--background-color

View background color

Default: 'lightgray'

--html

Where to save the HTML file. Leave empty to use a temporary directory

Default: ''

Example#

$ replay ./experiment_3784746994027959661_2023-07-07_16-13-36/data.h5 --factor 10

navground_py#

Like 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_py <command> [arguments]

instead of

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

You can also execute this command directly from Python

$ python -m navground.sim [sub-command] [arguments]

Example#

$ navground_py run --help
usage: navground_py 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

Runs an experiment using the Python interpreter

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

options:
  -h, --help            show this help message and exit
  --no-plugins          Do not load plugins
  -v, --version         show program's version number and exit
  --tqdm                Display tqdm bar
  --run_index RUN_INDEX
                        Will overwrite the experiment own run_index if
...

navground_sim_py

Contents

navground_sim_py#

Dependencies#

Python packages#

navground.sim#

Executables#

info#

Named Arguments#

Example#

echo#

Positional Arguments#

Named Arguments#

Example#

schema#

Positional Arguments#

Named Arguments#

Example#

validate#

Positional Arguments#

Named Arguments#

Example#

plugins#

Named Arguments#

Example#

sample#

Positional Arguments#

Named Arguments#

Example (scenario)#

Example (sampler)#

run#

Positional Arguments#

Named Arguments#

Example#

run_rt#

Positional Arguments#

Named Arguments#

Example#

record video#

Positional Arguments#

Named Arguments#

Example#

replay#

Positional Arguments#

Named Arguments#

Example#

navground_py#

Example#