Configuration

Contents

Configuration#

navground.learning.config

Actions#

Base class#

Bases: ABC, Registrable

The abstract base time of actions configuration.

Describes how the agent should convert control commands from navground navground.core.Behavior to actions to be applied a gymnasium.Env and, in the opposite direction), actions computed by a ML-policy to control commands to be applied in navground.

Complete the configuration for a target behavior is known.

Parameters:

behavior (Behavior) – The behavior

Return type:

None

Gets the action from the command computed by a behavior.

Parameters:
  • behavior (Behavior) – The behavior

  • time_step (float) – The time step

Returns:

The action.

Return type:

Action

Convert action to navground command.

Parameters:
  • action (Action) – The action

  • behavior (Behavior | None) – The behavior that is requesting the command

  • time_step (float) – The time step

Returns:

A control command.

Return type:

Twist2

Whether is the configuration is complete.

Returns:

True if complete, False otherwise.

Parameters:

warn (bool)

Return type:

bool

The action space

Returns:

A valid Gymnasium space

End-to-end#

Continuous#

Bases: ConfigWithKinematic, ActionConfig

Configuration of the conversion between control actions and control commands. Actions are either command accelerations or command velocities, depending on use_acceleration_action().

Parameters:
  • dtype (str) – The data type

  • dof (int | None) – The number of degrees of freedom of the agent

  • max_speed (float) – The upper bound of the speed.

  • max_angular_speed (float) – The upper bound of the angular speed.

  • max_acceleration (float) – The upper bound of the acceleration.

  • max_angular_acceleration (float) – The upper bound of the angular acceleration.

  • use_acceleration_action (bool) – Whether actions are accelerations. If not set, actions are velocities.

  • use_wheels (bool) – Whether action uses wheel speeds/acceleration instead of body speeds/acceleration. Only effective if the b behavior has a wheeled kinematics.

  • fix_orientation (bool) – Whether to force the agent not to control orientation, i.e., to not include the angular command in actions.

  • has_wheels (bool | None) – Whether the agent as wheels. If None, it will defer to the agent kinematics.

Configure the fields that are not yet set from the behavior’s kinematics.

Parameters:

behavior (Behavior) – The behavior

Return type:

None

Load an instance from a dictionary.

Selects a class from field type and calls its method _make_from_dict().

Parameters:

value (Mapping[str, Any]) – The value

Raises:

ValueError – If type is not defined or not registered.

Returns:

An instance initialized from the content of value.

Return type:

Self

The number of control dimensions

The YAML-able dictionary representation.

Adds the class type name to the dictionary returned by _get_dict().

Returns:

A YAML-able dictionary

Whether to keep the agent orientation fixed

Whether the agent as wheels. If None, it will defer to the agent kinematics.

The maximal agent acceleration module; only relevant if use_acceleration_action is set.

The maximal agent angular acceleration; only relevant if use_acceleration_action is set.

The action space.

Whether to output acceleration commands instead of velocity commands.

Whether to output control commands that refer to wheel speeds or accelerations.

Discrete#

Bases: ControlActionConfig

Configuration of the conversion between discrete control actions and control commands. Actions are either command accelerations or command velocities, depending on ControlActionConfig.use_acceleration_action.

Discrete actions are first converted to continuous action and then, by the super class ControlActionConfig, to control commands.

The action space gymnasium.spaces.Discrete is discrete. Values are encoded using a ternary numeral system, where for every dimension:

Title#

Discrete

Continuous

0

space.low

1

0

2

space.high

Parameters:
  • dtype (str) – The data type

  • dof (int | None) – The number of degrees of freedom of the agent

  • max_speed (float) – The upper bound of the speed.

  • max_angular_speed (float) – The upper bound of the angular speed.

  • max_acceleration (float) – The upper bound of the acceleration.

  • max_angular_acceleration (float) – The upper bound of the angular acceleration.

  • use_acceleration_action (bool) – Whether actions are accelerations. If not set, actions are velocities.

  • use_wheels (bool) – Whether action uses wheel speeds/acceleration instead of body speeds/acceleration. Only effective if the b behavior has a wheeled kinematics.

  • fix_orientation (bool) – Whether to force the agent not to control orientation, i.e., to not include the angular command in actions.

  • has_wheels (bool | None) – Whether the agent as wheels. If None, it will defer to the agent kinematics.

The action space.

  • 0: backwards

  • 1: do-nothing

  • 2: forwards

[Multi-]Binary#

Bases: ControlActionConfig

Configuration of the conversion between discrete control actions and control commands. Actions are either command accelerations or command velocities, depending on ControlActionConfig.use_acceleration_action.

Discrete actions are first converted to continuous action and then, by the super class ControlActionConfig, to control commands.

The action space gymnasium.spaces.MultiBinary is discrete, with two values for each continuous dimension: the first bit refers to moving/accelerating backwards (yes/no), and the second bit to moving/accelerating forwards (yes/no).

Discrete values are encoded using a 2-bits per dimension, where

Title#

Discrete

Continuous

[1, 0]

space.low

[0, 0]

0

[1, 1]

0

[0, 1]

space.high

Parameters:
  • dtype (str) – The data type

  • dof (int | None) – The number of degrees of freedom of the agent

  • max_speed (float) – The upper bound of the speed.

  • max_angular_speed (float) – The upper bound of the angular speed.

  • max_acceleration (float) – The upper bound of the acceleration.

  • max_angular_acceleration (float) – The upper bound of the angular acceleration.

  • use_acceleration_action (bool) – Whether actions are accelerations. If not set, actions are velocities.

  • use_wheels (bool) – Whether action uses wheel speeds/acceleration instead of body speeds/acceleration. Only effective if the b behavior has a wheeled kinematics.

  • fix_orientation (bool) – Whether to force the agent not to control orientation, i.e., to not include the angular command in actions.

  • has_wheels (bool | None) – Whether the agent as wheels. If None, it will defer to the agent kinematics.

The action space.

brake Y/N x accelerate Y/N

Communication#

Continuous#

Bases: ControlActionConfig

Configuration of the conversion between actions and control commands.

Actions are composed of control values (accelerations or command velocities, depending on ControlActionConfig.use_acceleration_action()) and the message to be transmitted.

Action are decomposed as:

  • the control is converted to a navground.core.Twist2 (and later actuated)

  • the message is set as attribute Behavior._comm (and later broadcasted)

Parameters:
  • dtype (str) – The data type

  • dof (int | None) – The number of degrees of freedom of the agent

  • max_speed (float) – The upper bound of the speed.

  • max_angular_speed (float) – The upper bound of the angular speed.

  • max_acceleration (float) – The upper bound of the acceleration.

  • max_angular_acceleration (float) – The upper bound of the angular acceleration.

  • use_acceleration_action (bool) – Whether actions are accelerations. If not set, actions are velocities.

  • use_wheels (bool) – Whether action uses wheel speeds/acceleration instead of body speeds/acceleration. Only effective if the b behavior has a wheeled kinematics.

  • fix_orientation (bool) – Whether to force the agent not to control orientation, i.e., to not include the angular command in actions.

  • has_wheels (bool | None) – Whether the agent as wheels. If None, it will defer to the agent kinematics.

  • comm_size (int) – The size of the message to broadcast

The size of the message to broadcast

The box space of the broadcasted messages with dimension ControlActionConfig.action_size() and values between -1 and 1.

Returns:

the box space

Discrete#

Bases: ControlActionConfig

Actions are composed of control values and the message to be transmitted

Message {0, 1} and controls {0, 1, 2} are discrete and encoded using a mixed numerical scheme: - the lower part with a ternary encoding for controls - the upper part with binary encoding for messages.

Action to be actuated are decomposed: - the control is converted to a navground.core.Twist2, - the message is set as attribute Behavior._comm.

Parameters:
  • dtype (str) – The data type

  • dof (int | None) – The number of degrees of freedom of the agent

  • max_speed (float) – The upper bound of the speed.

  • max_angular_speed (float) – The upper bound of the angular speed.

  • max_acceleration (float) – The upper bound of the acceleration.

  • max_angular_acceleration (float) – The upper bound of the angular acceleration.

  • use_acceleration_action (bool) – Whether actions are accelerations. If not set, actions are velocities.

  • use_wheels (bool) – Whether action uses wheel speeds/acceleration instead of body speeds/acceleration. Only effective if the b behavior has a wheeled kinematics.

  • fix_orientation (bool) – Whether to force the agent not to control orientation, i.e., to not include the angular command in actions.

  • has_wheels (bool | None) – Whether the agent as wheels. If None, it will defer to the agent kinematics.

  • comm_size (int) – The size of the message to broadcast

The size of the message to broadcast

The box space of the broadcasted messages with dimension ControlActionConfig.action_size() and values in {0, 1}.

Returns:

the box space

The control space {0 (backwards), 1 (do-nothing), 2 (forwards)} multiplied by the communication space {0, 1}

Behavior Modulation#

Bases: DataclassConfig, ActionConfig

Configuration of the conversion between modulation actions and control commands.

Parameters:

Actions are values of parameters of a behavior.

Load an instance from a dictionary.

Selects a class from field type and calls its method _make_from_dict().

Parameters:

value (Mapping[str, Any]) – The value

Raises:

ValueError – If type is not defined or not registered.

Returns:

An instance initialized from the content of value.

Return type:

Self

The parameters to modulate as a dictionary name -> space configuration

The action space is a flattened gymnasium.spaces.Dict with one entry per controlled parameter.

Observations#

Base class#

Bases: ABC, Registrable

Configure how to convert the state of a a navground.sim.Agent to observation consumed in a gymnasium.Env.

Observation may contain data from the agent’s behavior ego state (e.g., velocity) and navground.core.Behavior.target (e.g. relative target direction), and data generated by navground.sim.Sensor.

Complete the configuration for a target behavior is known.

Parameters:
Return type:

None

Whether is the configuration is complete.

Returns:

True if complete, False otherwise.

Parameters:

warn (bool)

Return type:

bool

The size of observations queue. If larger than 1, recent observations will be first stacked and then flattened.

Default#

Bases: ConfigWithKinematic, ObservationConfig

This class configures which information from the behavior state to include in the observations.

Parameters:
  • flat (bool) – Whether to flatten the observation space

  • history (int) – The size of observations queue. If larger than 1, recent observations will be first stacked and then flattened.

  • include_target_distance (bool) – Whether to include the target distance in the observations.

  • include_target_distance_validity (bool) – Whether to include whether the target distance is valid in the observations.

  • max_target_distance (float) – The upper bound of target distance. Only relevant if include_target_distance=True

  • include_target_direction (bool) – Whether to include the target direction in the observations.

  • include_target_direction_validity (bool) – Whether to include whether the target direction is valid in the observations.

  • include_velocity (bool) – Whether to include the current velocity in the observations.

  • include_angular_speed (bool) – Whether to include the current angular_speed in the observations.

  • include_target_speed (bool) – Whether to include the target speed in the observations.

  • include_target_angular_speed (bool) – Whether to include the target angular speed in the observations.

  • max_speed (float) – The upper bound of the speed.

  • max_angular_speed (float) – The upper bound of the angular speed.

  • include_radius (bool) – Whether to include the own radius in the observations.

  • max_radius (float) – The upper bound of own radius. Only relevant if include_radius=True.

  • normalize (bool) – Whether to normalize observations in [-1, 1]

  • ignore_keys (list[str]) – Which keys to ignore

  • sort_keys (bool) – Whether to sort the keys

  • keys (Sequence[str] | None) – Which keys to select

  • include_position (bool) – Whether to include the behavior position Coordinates are only included if the related interval has length > 0, e.g., min_x < max for the x-coordinate.

  • max_x (float) – The upper bound of x-coordinate

  • max_y (float) – The upper bound of y-coordinate

  • min_x (float) – The lower bound of x-coordinate

  • min_y (float) – The lower bound of y-coordinate

  • include_orientation (bool) – Whether to include the behavior orientation

  • dtype (str)

  • dof (int | None)

  • flat_values (bool)

  • include_target_orientation (bool)

  • include_target_orientation_validity (bool)

Configure the fields that are not yet set from the behavior’s kinematics.

Parameters:

behavior (Behavior) – The behavior

Return type:

None

Load an instance from a dictionary.

Selects a class from field type and calls its method _make_from_dict().

Parameters:

value (Mapping[str, Any]) – The value

Raises:

ValueError – If type is not defined or not registered.

Returns:

An instance initialized from the content of value.

Return type:

Self

The YAML-able dictionary representation.

Adds the class type name to the dictionary returned by _get_dict().

Returns:

A YAML-able dictionary

Whether the observation space is flat

Whether the flatten the spaces of a dict observation space

The size of observations queue. If larger than 1, recent observations will be first stacked and then flattened.

Which keys to ignore

Whether observations include the current angular_speed.

Whether to include the behavior orientation

Whether to include the behavior position

Whether observations include the own radius.

Whether observations include the target angular speed.

Whether observations include the target direction.

Whether observations include whether the validity of the target direction.

Whether observations include the target direction.

Whether observations include the validity of the target direction.

TODO

TODO

Whether observations include the target speed.

Whether observations include the current velocity.

Which keys to select

The upper bound of own radius. Only relevant if include_radius is set.

The upper bound of target distance. Only relevant if include_target_distance is set.

The maximal x-coordinate

The maximal y-coordinate

The minimal x-coordinate

The minimal y-coordinate

Whether to normalize observations in [-1, 1]

Whether to sort the keys

State#

Base class#

Bases: ABC, Registrable

Configure how to get the environment state from the current state of a navground.sim.World

Returns the space of the global state

Parameters:

world (sim.World) – The world

Returns:

The space.

Return type:

gym.spaces.Box

Computes the global state from the current world state

Parameters:

world (World) – The world

Returns:

an array with the global state

Return type:

Array

Default#

Bases: DataclassConfig, StateConfig

This class configures which information from the behavior state to include in the global environement state.

Parameters:
  • include_position (bool) – Whether observations include the position

  • include_orientation (bool) – Whether observations include the orientation

  • include_radius (bool) – Whether to include the radius in the observations.

  • max_radius (float) – Maximal radius.

  • include_velocity (bool) – Whether to include the velocity

  • include_angular_speed (bool) – Whether to include the angular_speed

  • include_x (bool) – Whether observations include the x-coordinates

  • include_y (bool) – Whether observations include the y-coordinates

  • include_target_distance (bool) – Whether to include the target distance in the observations.

  • max_target_distance (float) – Maximal target distance

  • include_target_distance_validity (bool) – Whether to include whether the target distance is valid in the observations.

  • include_target_direction (bool) – Whether to include the target direction in the observations.

  • include_target_direction_validity (bool) – Whether to include whether the target direction is valid in the observations.

  • include_target_speed (bool) – Whether to include the target speed in the observations.

  • include_target_angular_speed (bool) – Whether to include the target angular speed in the observations.

  • dtype (str)

  • use_absolute_frame (bool)

  • include_target_orientation (bool)

  • include_target_orientation_validity (bool)

  • include_all (dataclasses.InitVar[bool])

Load an instance from a dictionary.

Selects a class from field type and calls its method _make_from_dict().

Parameters:

value (Mapping[str, Any]) – The value

Raises:

ValueError – If type is not defined or not registered.

Returns:

An instance initialized from the content of value.

Return type:

Self

The YAML-able dictionary representation.

Adds the class type name to the dictionary returned by _get_dict().

Returns:

A YAML-able dictionary

Whether to include all fields

Whether to include the angular_speed.

Whether observations include the orientation.

Whether observations include the position.

Whether observations include the radius.

Whether observations include the target angular speed.

Whether observations include the target direction.

Whether observations include whether the validity of the target direction.

Whether observations include the target direction.

Whether observations include the validity of the target direction.

TODO

TODO

Whether observations include the target speed.

Whether to include the velocity.

Whether observations include the x-coordinates

Whether observations include the y-coordinates

Maximal radius.

Maximal target distance

Whether to use the absolute frame for velocity and target direction

Group#

Bases: object

Configure a group of navground agents so that they are exposed in a gymnasium.Env (only single agents) or pettingzoo.utils.env.ParallelEnv (one or more agents).

Group configurations can be stuck. For instance, the configuration provided to define the environment for training needs needs to define at least indices, action and observation, and possibly also one sensors. Instead, for evaluation, we may provide just the policy, as the agents are already configured.

Parameters:

:param color : An optional color for the agents (only used for displaying)

:param tagAn optional tag added to the agents navground.sim.Agent.tags,

(does not impact simulation, only used to identify the agents)

Parameters:

The actions configuration

A JSON-able representation of the configuration

Returns:

A JSON-able dict

The agents’ color

Whether the agents apply such policy deterministically

Failure condition

The indices of the agents in the navground.sim.World.agents list

The observations configuration

The policy assigned to the agents (during evaluation)

The reward function

List of sensors to generate observations for the agents

Success condition

An optional additional tag for the agents

Whether to terminate when the agent fails

Whether to terminate when the agent succeeds

Overlaps two sets of group configurations, letting the first inherit attributes from the second if they are not specified.

Parameters:
  • groups (Collection[GroupConfig]) – A collection of groups configuration

  • other_groups (Collection[GroupConfig]) – Another collection of groups configuration to be inherited from.

  • max_number (int) – The maximum number of agents, needed to intersect the groups GroupConfig.indices to identify which agents belong to groups in both sets.

Returns:

A new list of groups, where the attributes from both groups collections.

Return type:

list[GroupConfig]