Configuration

navground.learning.config

Actions

Base class

class ActionConfig

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.

abstract configure(behavior: Behavior) → None

Complete the configuration for a target behavior is known.

Parameters:

behavior (Behavior) – The behavior

Return type:

None

abstract get_action(behavior: Behavior, time_step: float) → Action

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

abstract get_cmd_from_action(action: Action, behavior: Behavior | None, time_step: float) → Twist2

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

abstract is_configured(warn: bool = False) → bool

Whether is the configuration is complete.

Returns:

True if complete, False otherwise.

Parameters:

warn (bool)

Return type:

bool

abstract property space: gym.Space[Any]

The action space

Returns:

A valid Gymnasium space

End-to-end

class ControlActionConfig(dtype: str = '', max_speed: float = inf, max_angular_speed: float = inf, dof: int | None = None, max_acceleration: float = inf, max_angular_acceleration: float = inf, use_acceleration_action: bool = False, fix_orientation: bool = False, use_wheels: bool = False, has_wheels: bool | None = None)

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

Parameters:

• 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.

• dtype (str)

• dof (int | None)

• has_wheels (bool | None)

fix_orientation: bool = False

Whether to keep the agent orientation fixed

has_wheels: bool | None = None

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

max_acceleration: float = inf

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

max_angular_acceleration: float = inf

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

property space: Box

The action space.

use_acceleration_action: bool = False

Whether to output acceleration commands instead of velocity commands.

use_wheels: bool = False

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

Behavior Modulation

class ModulationActionConfig(params: dict[str, dict[str, ~typing.Any]] = <factory>)

Configuration of the conversion between modulation actions and control commands.

Parameters:

params (dict[str, dict[str, Any]]) – The parameters to modulate.

Actions are values of parameters of a behavior.

params: dict[str, dict[str, Any]]

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

property space: Space[Any]

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

Observations

Base class

class ObservationConfig

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 a navground.sim.Sensor.

abstract configure(behavior: core.Behavior | None, sensing_space: gym.spaces.Dict) → None

Complete the configuration for a target behavior is known.

Parameters:

• behavior (core.Behavior | None) – The behavior

• sensing_space (gym.spaces.Dict) – The sensing space

Return type:

None

abstract is_configured(warn: bool = False) → bool

Whether is the configuration is complete.

Returns:

True if complete, False otherwise.

Parameters:

warn (bool)

Return type:

bool

abstract property history: int

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

Default

class DefaultObservationConfig(dtype: str = '', max_speed: float = inf, max_angular_speed: float = inf, dof: int | None = None, flat: bool = False, history: int = 1, include_target_distance: bool = False, include_target_distance_validity: bool = False, max_target_distance: float = inf, include_target_direction: bool = True, include_target_direction_validity: bool = False, include_velocity: bool = False, include_angular_speed: bool = False, include_radius: bool = False, include_target_speed: bool = False, include_target_angular_speed: bool = False, max_radius: float = inf)

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.

• dtype (str)

• dof (int | None)

flat: bool = False

Whether the observation space is flat

history: int = 1

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

include_angular_speed: bool = False

Whether observations include the current angular_speed.

include_radius: bool = False

Whether observations include the own radius.

include_target_angular_speed: bool = False

Whether observations include the target angular speed.

include_target_direction: bool = True

Whether observations include the target direction.

include_target_direction_validity: bool = False

Whether observations include whether the validity of the target direction.

include_target_distance: bool = False

Whether observations include the target direction.

include_target_distance_validity: bool = False

Whether observations include the validity of the target direction.

include_target_speed: bool = False

Whether observations include the target speed.

include_velocity: bool = False

Whether observations include the current velocity.

max_radius: float = inf

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

max_target_distance: float = inf

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

Group

class GroupConfig(indices: Indices = Indices.all(), action: ActionConfig | None = None, observation: ObservationConfig | None = None, sensor: sim.Sensor | str | dict[str, Any] | None = None, reward: Reward | None = None, color: str = '', tag: str = '', policy: AnyPolicyPredictor | PathLike = '', deterministic: bool = False)

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 the sensor. Instead, for evaluation, we may provide just the policy, as the agents are already configured.

Parameters:

• indices (Indices) – The indices of the agents in the navground.sim.World.agents list.

• action (ActionConfig | None) – The actions configuration.

• observation (ObservationConfig | None) – The observations configuration.

• sensor (sim.Sensor | str | dict[str, Any] | None) – A sensor to produce observations for the agents. If a str, it will be interpreted as the YAML representation of a sensor. If a dict, it will be dumped to YAML and then treated as a str. If None, it will use the agents’ own state estimation, if a sensor.

• reward (Reward | None) – An optional reward function to use.

• color (str)

• tag (str)

• policy (AnyPolicyPredictor | PathLike)

• deterministic (bool)

: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:

• policy (AnyPolicyPredictor | PathLike) – The policy assigned to the agents during evaluation.

• deterministic (bool) – Whether the agents apply such policy deterministically.

• indices (Indices)

• action (ActionConfig | None)

• observation (ObservationConfig | None)

• sensor (sim.Sensor | str | dict[str, Any] | None)

• reward (Reward | None)

• color (str)

• tag (str)

action: ActionConfig | None = None

The actions configuration

property asdict: dict[str, Any]

A JSON-able representation of the configuration

Returns:

A JSON-able dict

color: str = ''

The agents’ color

deterministic: bool = False

Whether the agents apply such policy deterministically

indices: Indices = Indices.all()

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

observation: ObservationConfig | None = None

The observations configuration

policy: AnyPolicyPredictor | PathLike = ''

The policy assigned to the agents (during evaluation)

reward: Reward | None = None

The reward function

sensor: sim.Sensor | str | dict[str, Any] | None = None

A sensor to produce observations for the agents

tag: str = ''

An optional additional tag for the agents

merge_groups_configs(groups: Collection[GroupConfig], other_groups: Collection[GroupConfig], max_number: int) → list[GroupConfig]

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]