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 agymnasium.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.
Convert action to navground command.
Whether is the configuration is complete.
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:
- Raises:
ValueError – If
type
is not defined or not registered.- Returns:
An instance initialized from the content of
value
.- Return type:
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 attributeBehavior._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.
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:
- Raises:
ValueError – If
type
is not defined or not registered.- Returns:
An instance initialized from the content of
value
.- Return type:
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 agymnasium.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 bynavground.sim.Sensor
.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
Whether is the configuration is complete.
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]
sort_keys (bool) – Whether to sort the keys
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:
- Raises:
ValueError – If
type
is not defined or not registered.- Returns:
An instance initialized from the content of
value
.- Return type:
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:
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:
- Raises:
ValueError – If
type
is not defined or not registered.- Returns:
An instance initialized from the content of
value
.- Return type:
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) orpettingzoo.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
andobservation
, and possibly also onesensors
. 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 (dc.InitVar[SensorLike | None]) – An optional sensor that will be added to
sensors
.sensors (SensorSequenceLike) – A sequence of sensor to generate observations for the agents or its YAML representation. If Items of class
str
will be interpreted as the YAML representation of a sensor. Items of classdict
will be dumped to YAML and then treated as astr
. If empty, it will use the agents’ own sensors.reward (Reward | None) – An optional reward function to use.
color (str)
tag (str)
policy (AnyPolicyPredictor | PathLike)
deterministic (bool)
terminate_on_success (bool | None)
terminate_on_failure (bool | None)
success_condition (TerminationCondition | None)
failure_condition (TerminationCondition | None)
: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.
terminate_on_success (bool | None) – Whether to terminate when the agent succeeds
terminate_on_failure (bool | None) – Whether to terminate when the agent fails
success_condition (TerminationCondition | None) – Optional success condition
failure_condition (TerminationCondition | None) – Optional failure condition
indices (Indices)
action (ActionConfig | None)
observation (ObservationConfig | None)
sensor (dc.InitVar[SensorLike | None])
sensors (SensorSequenceLike)
reward (Reward | None)
color (str)
tag (str)
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: