omni.isaac.lab.managers#
Sub-module for environment managers.
The managers are used to handle various aspects of the environment such as randomization events, curriculum, and observations. Each manager implements a specific functionality for the environment. The managers are designed to be modular and can be easily extended to support new functionality.
Classes
Configuration for a scene entity that is used by the manager's term. |
|
Base class for all managers. |
|
Base class for manager terms. |
|
Configuration for a manager term. |
|
Manager for computing observation signals for a given world. |
|
Configuration for an observation group. |
|
Configuration for an observation term. |
|
Manager for processing and applying actions for a given world. |
|
Base class for action terms. |
|
Configuration for an action term. |
|
Manager for orchestrating operations based on different simulation events. |
|
Configuration for a event term. |
|
Manager for generating commands. |
|
The base class for implementing a command term. |
|
Configuration for a command generator term. |
|
Manager for computing reward signals for a given world. |
|
Configuration for a reward term. |
|
Manager for computing done signals for a given world. |
|
Configuration for a termination term. |
|
Manager to implement and execute specific curricula. |
|
Configuration for a curriculum term. |
Scene Entity#
- class omni.isaac.lab.managers.SceneEntityCfg[source]#
Configuration for a scene entity that is used by the manager’s term.
This class is used to specify the name of the scene entity that is queried from the
InteractiveScene
and passed to the manager’s term function.Attributes:
The name of the scene entity.
The names of the joints from the scene entity.
The indices of the joints from the asset required by the term.
The names of the fixed tendons from the scene entity.
The indices of the fixed tendons from the asset required by the term.
The names of the bodies from the asset required by the term.
The indices of the bodies from the asset required by the term.
Whether to preserve indices ordering to match with that in the specified joint or body names.
Methods:
resolve
(scene)Resolves the scene entity and converts the joint and body names to indices.
- name: str#
The name of the scene entity.
This is the name defined in the scene configuration file. See the
InteractiveSceneCfg
class for more details.
- joint_names: str | list[str] | None#
The names of the joints from the scene entity. Defaults to None.
The names can be either joint names or a regular expression matching the joint names.
These are converted to joint indices on initialization of the manager and passed to the term function as a list of joint indices under
joint_ids
.
- joint_ids: list[int] | slice#
The indices of the joints from the asset required by the term. Defaults to slice(None), which means all the joints in the asset (if present).
If
joint_names
is specified, this is filled in automatically on initialization of the manager.
- fixed_tendon_names: str | list[str] | None#
The names of the fixed tendons from the scene entity. Defaults to None.
The names can be either joint names or a regular expression matching the joint names.
These are converted to fixed tendon indices on initialization of the manager and passed to the term function as a list of fixed tendon indices under
fixed_tendon_ids
.
- fixed_tendon_ids: list[int] | slice#
The indices of the fixed tendons from the asset required by the term. Defaults to slice(None), which means all the fixed tendons in the asset (if present).
If
fixed_tendon_names
is specified, this is filled in automatically on initialization of the manager.
- body_names: str | list[str] | None#
The names of the bodies from the asset required by the term. Defaults to None.
The names can be either body names or a regular expression matching the body names.
These are converted to body indices on initialization of the manager and passed to the term function as a list of body indices under
body_ids
.
- body_ids: list[int] | slice#
The indices of the bodies from the asset required by the term. Defaults to slice(None), which means all the bodies in the asset.
If
body_names
is specified, this is filled in automatically on initialization of the manager.
- preserve_order: bool#
Whether to preserve indices ordering to match with that in the specified joint or body names. Defaults to False.
If False, the ordering of the indices are sorted in ascending order (i.e. the ordering in the entity’s joints or bodies). Otherwise, the indices are preserved in the order of the specified joint and body names.
For more details, see the
omni.isaac.lab.utils.string.resolve_matching_names()
function.Note
This attribute is only used when
joint_names
orbody_names
are specified.
- resolve(scene: InteractiveScene)[source]#
Resolves the scene entity and converts the joint and body names to indices.
This function examines the scene entity from the
InteractiveScene
and resolves the indices and names of the joints and bodies. It is an expensive operation as it resolves regular expressions and should be called only once.- Parameters:
scene – The interactive scene instance.
- Raises:
ValueError – If the scene entity is not found.
ValueError – If both
joint_names
andjoint_ids
are specified and are not consistent.ValueError – If both
fixed_tendon_names
andfixed_tendon_ids
are specified and are not consistent.ValueError – If both
body_names
andbody_ids
are specified and are not consistent.
Manager Base#
- class omni.isaac.lab.managers.ManagerBase[source]#
Base class for all managers.
Methods:
__init__
(cfg, env)Initialize the manager.
reset
([env_ids])Resets the manager and returns logging information for the current time-step.
find_terms
(name_keys)Find terms in the manager based on the names.
Attributes:
Number of environments.
Device on which to perform computations.
Name of active terms.
- __init__(cfg: object, env: ManagerBasedEnv)[source]#
Initialize the manager.
- Parameters:
cfg – The configuration object. If None, the manager is initialized without any terms.
env – The environment instance.
- reset(env_ids: Sequence[int] | None = None) dict[str, float] [source]#
Resets the manager and returns logging information for the current time-step.
- Parameters:
env_ids – The environment ids for which to log data. Defaults None, which logs data for all environments.
- Returns:
Dictionary containing the logging information.
- find_terms(name_keys: str | Sequence[str]) list[str] [source]#
Find terms in the manager based on the names.
This function searches the manager for terms based on the names. The names can be specified as regular expressions or a list of regular expressions. The search is performed on the active terms in the manager.
Please check the
omni.isaac.lab.utils.string_utils.resolve_matching_names()
function for more information on the name matching.- Parameters:
name_keys – A regular expression or a list of regular expressions to match the term names.
- Returns:
A list of term names that match the input keys.
- class omni.isaac.lab.managers.ManagerTermBase[source]#
Base class for manager terms.
Manager term implementations can be functions or classes. If the term is a class, it should inherit from this base class and implement the required methods.
Each manager is implemented as a class that inherits from the
ManagerBase
class. Each manager class should also have a corresponding configuration class that defines the configuration terms for the manager. Each term should theManagerTermBaseCfg
class or its subclass.Example pseudo-code for creating a manager:
from omni.isaac.lab.utils import configclass from omni.isaac.lab.utils.mdp import ManagerBase, ManagerTermBaseCfg @configclass class MyManagerCfg: my_term_1: ManagerTermBaseCfg = ManagerTermBaseCfg(...) my_term_2: ManagerTermBaseCfg = ManagerTermBaseCfg(...) my_term_3: ManagerTermBaseCfg = ManagerTermBaseCfg(...) # define manager instance my_manager = ManagerBase(cfg=ManagerCfg(), env=env)
Methods:
Attributes:
- __init__(cfg: ManagerTermBaseCfg, env: ManagerBasedEnv)[source]#
Initialize the manager term.
- Parameters:
cfg – The configuration object.
env – The environment instance.
- class omni.isaac.lab.managers.ManagerTermBaseCfg[source]#
Configuration for a manager term.
Attributes:
The function or class to be called for the term.
The parameters to be passed to the function as keyword arguments.
- func: Callable | ManagerTermBase#
The function or class to be called for the term.
The function must take the environment object as the first argument. The remaining arguments are specified in the
params
attribute.It also supports callable classes, i.e. classes that implement the
__call__()
method. In this case, the class should inherit from theManagerTermBase
class and implement the required methods.
- params: dict[str, Any | SceneEntityCfg]#
The parameters to be passed to the function as keyword arguments. Defaults to an empty dict.
Note
If the value is a
SceneEntityCfg
object, the manager will query the scene entity from theInteractiveScene
and process the entity’s joints and bodies as specified in theSceneEntityCfg
object.
Observation Manager#
- class omni.isaac.lab.managers.ObservationManager[source]#
Bases:
ManagerBase
Manager for computing observation signals for a given world.
Observations are organized into groups based on their intended usage. This allows having different observation groups for different types of learning such as asymmetric actor-critic and student-teacher training. Each group contains observation terms which contain information about the observation function to call, the noise corruption model to use, and the sensor to retrieve data from.
Each observation group should inherit from the
ObservationGroupCfg
class. Within each group, each observation term should instantiate theObservationTermCfg
class. Based on the configuration, the observations in a group can be concatenated into a single tensor or returned as a dictionary with keys corresponding to the term’s name.If the observations in a group are concatenated, the shape of the concatenated tensor is computed based on the shapes of the individual observation terms. This information is stored in the
group_obs_dim
dictionary with keys as the group names and values as the shape of the observation tensor. When the terms in a group are not concatenated, the attribute stores a list of shapes for each term in the group.Note
When the observation terms in a group do not have the same shape, the observation terms cannot be concatenated. In this case, please set the
ObservationGroupCfg.concatenate_terms
attribute in the group configuration to False.The observation manager can be used to compute observations for all the groups or for a specific group. The observations are computed by calling the registered functions for each term in the group. The functions are called in the order of the terms in the group. The functions are expected to return a tensor with shape (num_envs, …).
If a noise model or custom modifier is registered for a term, the function is called to corrupt the observation. The corruption function is expected to return a tensor with the same shape as the observation. The observations are clipped and scaled as per the configuration settings.
Methods:
__init__
(cfg, env)Initialize observation manager.
reset
([env_ids])Resets the manager and returns logging information for the current time-step.
compute
()Compute the observations per group for all groups.
compute_group
(group_name)Computes the observations for a given group.
find_terms
(name_keys)Find terms in the manager based on the names.
Attributes:
Name of active observation terms in each group.
Shape of computed observations in each group.
Shape of individual observation terms in each group.
Whether the observation terms are concatenated in each group or not.
Device on which to perform computations.
Number of environments.
- __init__(cfg: object, env: ManagerBasedEnv)[source]#
Initialize observation manager.
- Parameters:
cfg – The configuration object or dictionary (
dict[str, ObservationGroupCfg]
).env – The environment instance.
- Raises:
ValueError – If the configuration is None.
RuntimeError – If the shapes of the observation terms in a group are not compatible for concatenation and the
concatenate_terms
attribute is set to True.
- property active_terms: dict[str, list[str]]#
Name of active observation terms in each group.
The keys are the group names and the values are the list of observation term names in the group.
- property group_obs_dim: dict[str, tuple[int, ...] | list[tuple[int, ...]]]#
Shape of computed observations in each group.
The key is the group name and the value is the shape of the observation tensor. If the terms in the group are concatenated, the value is a single tuple representing the shape of the concatenated observation tensor. Otherwise, the value is a list of tuples, where each tuple represents the shape of the observation tensor for a term in the group.
- property group_obs_term_dim: dict[str, list[tuple[int, ...]]]#
Shape of individual observation terms in each group.
The key is the group name and the value is a list of tuples representing the shape of the observation terms in the group. The order of the tuples corresponds to the order of the terms in the group. This matches the order of the terms in the
active_terms
.
- property group_obs_concatenate: dict[str, bool]#
Whether the observation terms are concatenated in each group or not.
The key is the group name and the value is a boolean specifying whether the observation terms in the group are concatenated into a single tensor. If True, the observations are concatenated along the last dimension.
The values are set based on the
concatenate_terms
attribute in the group configuration.
- reset(env_ids: Sequence[int] | None = None) dict[str, float] [source]#
Resets the manager and returns logging information for the current time-step.
- Parameters:
env_ids – The environment ids for which to log data. Defaults None, which logs data for all environments.
- Returns:
Dictionary containing the logging information.
- compute() dict[str, torch.Tensor | dict[str, torch.Tensor]] [source]#
Compute the observations per group for all groups.
The method computes the observations for all the groups handled by the observation manager. Please check the
compute_group()
on the processing of observations per group.- Returns:
A dictionary with keys as the group names and values as the computed observations. The observations are either concatenated into a single tensor or returned as a dictionary with keys corresponding to the term’s name.
- compute_group(group_name: str) torch.Tensor | dict[str, torch.Tensor] [source]#
Computes the observations for a given group.
The observations for a given group are computed by calling the registered functions for each term in the group. The functions are called in the order of the terms in the group. The functions are expected to return a tensor with shape (num_envs, …).
The following steps are performed for each observation term:
Compute observation term by calling the function
Apply custom modifiers in the order specified in
ObservationTermCfg.modifiers
Apply corruption/noise model based on
ObservationTermCfg.noise
Apply clipping based on
ObservationTermCfg.clip
Apply scaling based on
ObservationTermCfg.scale
We apply noise to the computed term first to maintain the integrity of how noise affects the data as it truly exists in the real world. If the noise is applied after clipping or scaling, the noise could be artificially constrained or amplified, which might misrepresent how noise naturally occurs in the data.
- Parameters:
group_name – The name of the group for which to compute the observations. Defaults to None, in which case observations for all the groups are computed and returned.
- Returns:
Depending on the group’s configuration, the tensors for individual observation terms are concatenated along the last dimension into a single tensor. Otherwise, they are returned as a dictionary with keys corresponding to the term’s name.
- Raises:
ValueError – If input
group_name
is not a valid group handled by the manager.
- find_terms(name_keys: str | Sequence[str]) list[str] #
Find terms in the manager based on the names.
This function searches the manager for terms based on the names. The names can be specified as regular expressions or a list of regular expressions. The search is performed on the active terms in the manager.
Please check the
omni.isaac.lab.utils.string_utils.resolve_matching_names()
function for more information on the name matching.- Parameters:
name_keys – A regular expression or a list of regular expressions to match the term names.
- Returns:
A list of term names that match the input keys.
- class omni.isaac.lab.managers.ObservationGroupCfg[source]#
Configuration for an observation group.
Attributes:
Whether to concatenate the observation terms in the group.
Whether to enable corruption for the observation group.
- concatenate_terms: bool#
Whether to concatenate the observation terms in the group. Defaults to True.
If true, the observation terms in the group are concatenated along the last dimension. Otherwise, they are kept separate and returned as a dictionary.
If the observation group contains terms of different dimensions, it must be set to False.
- class omni.isaac.lab.managers.ObservationTermCfg[source]#
Configuration for an observation term.
Attributes:
The name of the function to be called.
The list of data modifiers to apply to the observation in order.
The noise to add to the observation.
The clipping range for the observation after adding noise.
The scale to apply to the observation after clipping.
The parameters to be passed to the function as keyword arguments.
- func: Callable[..., torch.Tensor]#
The name of the function to be called.
This function should take the environment object and any other parameters as input and return the observation signal as torch float tensors of shape (num_envs, obs_term_dim).
- modifiers: list[ModifierCfg] | None#
The list of data modifiers to apply to the observation in order. Defaults to None, in which case no modifications will be applied.
Modifiers are applied in the order they are specified in the list. They can be stateless or stateful, and can be used to apply transformations to the observation data. For example, a modifier can be used to normalize the observation data or to apply a rolling average.
For more information on modifiers, see the
ModifierCfg
class.
- noise: NoiseCfg | None#
The noise to add to the observation. Defaults to None, in which case no noise is added.
- clip: tuple[float, float] | None#
The clipping range for the observation after adding noise. Defaults to None, in which case no clipping is applied.
- scale: tuple[float, ...] | float | None#
The scale to apply to the observation after clipping. Defaults to None, in which case no scaling is applied (same as setting scale to
1
).We leverage PyTorch broadcasting to scale the observation tensor with the provided value. If a tuple is provided, please make sure the length of the tuple matches the dimensions of the tensor outputted from the term.
- params: dict[str, Any | SceneEntityCfg]#
The parameters to be passed to the function as keyword arguments. Defaults to an empty dict.
Note
If the value is a
SceneEntityCfg
object, the manager will query the scene entity from theInteractiveScene
and process the entity’s joints and bodies as specified in theSceneEntityCfg
object.
Action Manager#
- class omni.isaac.lab.managers.ActionManager[source]#
Bases:
ManagerBase
Manager for processing and applying actions for a given world.
The action manager handles the interpretation and application of user-defined actions on a given world. It is comprised of different action terms that decide the dimension of the expected actions.
The action manager performs operations at two stages:
processing of actions: It splits the input actions to each term and performs any pre-processing needed. This should be called once at every environment step.
apply actions: This operation typically sets the processed actions into the assets in the scene (such as robots). It should be called before every simulation step.
Methods:
__init__
(cfg, env)Initialize the action manager.
set_debug_vis
(debug_vis)Sets whether to visualize the action data.
reset
([env_ids])Resets the action history.
process_action
(action)Processes the actions sent to the environment.
Applies the actions to the environment/simulation.
get_term
(name)Returns the action term with the specified name.
find_terms
(name_keys)Find terms in the manager based on the names.
Attributes:
Total dimension of actions.
Name of active action terms.
Shape of each action term.
The actions sent to the environment.
The previous actions sent to the environment.
Whether the command terms have debug visualization implemented.
Device on which to perform computations.
Number of environments.
- __init__(cfg: object, env: ManagerBasedEnv)[source]#
Initialize the action manager.
- Parameters:
cfg – The configuration object or dictionary (
dict[str, ActionTermCfg]
).env – The environment instance.
- Raises:
ValueError – If the configuration is None.
- property action: torch.Tensor#
The actions sent to the environment. Shape is (num_envs, total_action_dim).
- property prev_action: torch.Tensor#
The previous actions sent to the environment. Shape is (num_envs, total_action_dim).
- property has_debug_vis_implementation: bool#
Whether the command terms have debug visualization implemented.
- set_debug_vis(debug_vis: bool) bool [source]#
Sets whether to visualize the action data. :param debug_vis: Whether to visualize the action data.
- Returns:
Whether the debug visualization was successfully set. False if the action does not support debug visualization.
- reset(env_ids: Sequence[int] | None = None) dict[str, torch.Tensor] [source]#
Resets the action history.
- Parameters:
env_ids – The environment ids. Defaults to None, in which case all environments are considered.
- Returns:
An empty dictionary.
- process_action(action: torch.Tensor)[source]#
Processes the actions sent to the environment.
Note
This function should be called once per environment step.
- Parameters:
action – The actions to process.
- apply_action() None [source]#
Applies the actions to the environment/simulation.
Note
This should be called at every simulation step.
- get_term(name: str) ActionTerm [source]#
Returns the action term with the specified name.
- Parameters:
name – The name of the action term.
- Returns:
The action term with the specified name.
- find_terms(name_keys: str | Sequence[str]) list[str] #
Find terms in the manager based on the names.
This function searches the manager for terms based on the names. The names can be specified as regular expressions or a list of regular expressions. The search is performed on the active terms in the manager.
Please check the
omni.isaac.lab.utils.string_utils.resolve_matching_names()
function for more information on the name matching.- Parameters:
name_keys – A regular expression or a list of regular expressions to match the term names.
- Returns:
A list of term names that match the input keys.
- class omni.isaac.lab.managers.ActionTerm[source]#
Bases:
ManagerTermBase
Base class for action terms.
The action term is responsible for processing the raw actions sent to the environment and applying them to the asset managed by the term. The action term is comprised of two operations:
Processing of actions: This operation is performed once per environment step and is responsible for pre-processing the raw actions sent to the environment.
Applying actions: This operation is performed once per simulation step and is responsible for applying the processed actions to the asset managed by the term.
Methods:
__init__
(cfg, env)Initialize the action term.
set_debug_vis
(debug_vis)Sets whether to visualize the action term data.
process_actions
(actions)Processes the actions sent to the environment.
Applies the actions to the asset managed by the term.
reset
([env_ids])Resets the manager term.
Attributes:
Dimension of the action term.
The input/raw actions sent to the term.
The actions computed by the term after applying any processing.
Whether the action term has a debug visualization implemented.
Device on which to perform computations.
Number of environments.
- __init__(cfg: ActionTermCfg, env: ManagerBasedEnv)[source]#
Initialize the action term.
- Parameters:
cfg – The configuration object.
env – The environment instance.
- abstract property raw_actions: torch.Tensor#
The input/raw actions sent to the term.
- abstract property processed_actions: torch.Tensor#
The actions computed by the term after applying any processing.
- property has_debug_vis_implementation: bool#
Whether the action term has a debug visualization implemented.
- set_debug_vis(debug_vis: bool) bool [source]#
Sets whether to visualize the action term data. :param debug_vis: Whether to visualize the action term data.
- Returns:
Whether the debug visualization was successfully set. False if the action term does not support debug visualization.
- abstract process_actions(actions: torch.Tensor)[source]#
Processes the actions sent to the environment.
Note
This function is called once per environment step by the manager.
- Parameters:
actions – The actions to process.
- class omni.isaac.lab.managers.ActionTermCfg[source]#
Configuration for an action term.
Attributes:
The associated action term class.
The name of the scene entity.
Whether to visualize debug information.
- class_type: type[ActionTerm]#
The associated action term class.
The class should inherit from
omni.isaac.lab.managers.action_manager.ActionTerm
.
Event Manager#
- class omni.isaac.lab.managers.EventManager[source]#
Bases:
ManagerBase
Manager for orchestrating operations based on different simulation events.
The event manager applies operations to the environment based on different simulation events. For example, changing the masses of objects or their friction coefficients during initialization/ reset, or applying random pushes to the robot at a fixed interval of steps. The user can specify several modes of events to fine-tune the behavior based on when to apply the event.
The event terms are parsed from a config class containing the manager’s settings and each term’s parameters. Each event term should instantiate the
EventTermCfg
class.Event terms can be grouped by their mode. The mode is a user-defined string that specifies when the event term should be applied. This provides the user complete control over when event terms should be applied.
For a typical training process, you may want to apply events in the following modes:
“startup”: Event is applied once at the beginning of the training.
“reset”: Event is applied at every reset.
“interval”: Event is applied at pre-specified intervals of time.
However, you can also define your own modes and use them in the training process as you see fit. For this you will need to add the triggering of that mode in the environment implementation as well.
Note
The triggering of operations corresponding to the mode
"interval"
are the only mode that are directly handled by the manager itself. The other modes are handled by the environment implementation.Methods:
__init__
(cfg, env)Initialize the event manager.
reset
([env_ids])Resets the manager and returns logging information for the current time-step.
apply
(mode[, env_ids, dt, global_env_step_count])Calls each event term in the specified mode.
set_term_cfg
(term_name, cfg)Sets the configuration of the specified term into the manager.
get_term_cfg
(term_name)Gets the configuration for the specified term.
find_terms
(name_keys)Find terms in the manager based on the names.
Attributes:
Name of active event terms.
Modes of events.
Device on which to perform computations.
Number of environments.
- __init__(cfg: object, env: ManagerBasedEnv)[source]#
Initialize the event manager.
- Parameters:
cfg – A configuration object or dictionary (
dict[str, EventTermCfg]
).env – An environment object.
- property active_terms: dict[str, list[str]]#
Name of active event terms.
The keys are the modes of event and the values are the names of the event terms.
- reset(env_ids: Sequence[int] | None = None) dict[str, float] [source]#
Resets the manager and returns logging information for the current time-step.
- Parameters:
env_ids – The environment ids for which to log data. Defaults None, which logs data for all environments.
- Returns:
Dictionary containing the logging information.
- apply(mode: str, env_ids: Sequence[int] | None = None, dt: float | None = None, global_env_step_count: int | None = None)[source]#
Calls each event term in the specified mode.
This function iterates over all the event terms in the specified mode and calls the function corresponding to the term. The function is called with the environment instance and the environment indices to apply the event to.
For the “interval” mode, the function is called when the time interval has passed. This requires specifying the time step of the environment.
For the “reset” mode, the function is called when the mode is “reset” and the total number of environment steps that have happened since the last trigger of the function is equal to its configured parameter for the number of environment steps between resets.
- Parameters:
mode – The mode of event.
env_ids – The indices of the environments to apply the event to. Defaults to None, in which case the event is applied to all environments when applicable.
dt – The time step of the environment. This is only used for the “interval” mode. Defaults to None to simplify the call for other modes.
global_env_step_count – The total number of environment steps that have happened. This is only used for the “reset” mode. Defaults to None to simplify the call for other modes.
- Raises:
ValueError – If the mode is
"interval"
and the time step is not provided.ValueError – If the mode is
"interval"
and the environment indices are provided. This is an undefined behavior as the environment indices are computed based on the time left for each environment.ValueError – If the mode is
"reset"
and the total number of environment steps that have happened is not provided.
- set_term_cfg(term_name: str, cfg: EventTermCfg)[source]#
Sets the configuration of the specified term into the manager.
The method finds the term by name by searching through all the modes. It then updates the configuration of the term with the first matching name.
- Parameters:
term_name – The name of the event term.
cfg – The configuration for the event term.
- Raises:
ValueError – If the term name is not found.
- get_term_cfg(term_name: str) EventTermCfg [source]#
Gets the configuration for the specified term.
The method finds the term by name by searching through all the modes. It then returns the configuration of the term with the first matching name.
- Parameters:
term_name – The name of the event term.
- Returns:
The configuration of the event term.
- Raises:
ValueError – If the term name is not found.
- find_terms(name_keys: str | Sequence[str]) list[str] #
Find terms in the manager based on the names.
This function searches the manager for terms based on the names. The names can be specified as regular expressions or a list of regular expressions. The search is performed on the active terms in the manager.
Please check the
omni.isaac.lab.utils.string_utils.resolve_matching_names()
function for more information on the name matching.- Parameters:
name_keys – A regular expression or a list of regular expressions to match the term names.
- Returns:
A list of term names that match the input keys.
- class omni.isaac.lab.managers.EventTermCfg[source]#
Configuration for a event term.
Attributes:
The parameters to be passed to the function as keyword arguments.
The name of the function to be called.
The mode in which the event term is applied.
The range of time in seconds at which the term is applied.
Whether randomization should be tracked on a per-environment basis.
The number of environment steps after which the term is applied since its last application.
- params: dict[str, Any | SceneEntityCfg]#
The parameters to be passed to the function as keyword arguments. Defaults to an empty dict.
Note
If the value is a
SceneEntityCfg
object, the manager will query the scene entity from theInteractiveScene
and process the entity’s joints and bodies as specified in theSceneEntityCfg
object.
- func: Callable[..., None]#
The name of the function to be called.
This function should take the environment object, environment indices and any other parameters as input.
- mode: str#
The mode in which the event term is applied.
Note
The mode name
"interval"
is a special mode that is handled by the manager Hence, its name is reserved and cannot be used for other modes.
- interval_range_s: tuple[float, float] | None#
The range of time in seconds at which the term is applied. Defaults to None.
Based on this, the interval is sampled uniformly between the specified range for each environment instance. The term is applied on the environment instances where the current time hits the interval time.
Note
This is only used if the mode is
"interval"
.
- is_global_time: bool#
Whether randomization should be tracked on a per-environment basis. Defaults to False.
If True, the same interval time is used for all the environment instances. If False, the interval time is sampled independently for each environment instance and the term is applied when the current time hits the interval time for that instance.
Note
This is only used if the mode is
"interval"
.
- min_step_count_between_reset: int#
The number of environment steps after which the term is applied since its last application. Defaults to 0.
When the mode is “reset”, the term is only applied if the number of environment steps since its last application exceeds this quantity. This helps to avoid calling the term too often, thereby improving performance.
If the value is zero, the term is applied on every call to the manager with the mode “reset”.
Note
This is only used if the mode is
"reset"
.
Command Manager#
- class omni.isaac.lab.managers.CommandManager[source]#
Manager for generating commands.
The command manager is used to generate commands for an agent to execute. It makes it convenient to switch between different command generation strategies within the same environment. For instance, in an environment consisting of a quadrupedal robot, the command to it could be a velocity command or position command. By keeping the command generation logic separate from the environment, it is easy to switch between different command generation strategies.
The command terms are implemented as classes that inherit from the
CommandTerm
class. Each command generator term should also have a corresponding configuration class that inherits from theCommandTermCfg
class.Methods:
__init__
(cfg, env)Initialize the command manager.
set_debug_vis
(debug_vis)Sets whether to visualize the command data.
reset
([env_ids])Reset the command terms and log their metrics.
compute
(dt)Updates the commands.
get_command
(name)Returns the command for the specified command term.
get_term
(name)Returns the command term with the specified name.
Attributes:
Name of active command terms.
Whether the command terms have debug visualization implemented.
- __init__(cfg: object, env: ManagerBasedRLEnv)[source]#
Initialize the command manager.
- Parameters:
cfg – The configuration object or dictionary (
dict[str, CommandTermCfg]
).env – The environment instance.
- property has_debug_vis_implementation: bool#
Whether the command terms have debug visualization implemented.
- set_debug_vis(debug_vis: bool) bool [source]#
Sets whether to visualize the command data.
- Parameters:
debug_vis – Whether to visualize the command data.
- Returns:
Whether the debug visualization was successfully set. False if the command generator does not support debug visualization.
- reset(env_ids: Sequence[int] | None = None) dict[str, torch.Tensor] [source]#
Reset the command terms and log their metrics.
This function resets the command counter and resamples the command for each term. It should be called at the beginning of each episode.
- Parameters:
env_ids – The list of environment IDs to reset. Defaults to None.
- Returns:
A dictionary containing the information to log under the “Metrics/{term_name}/{metric_name}” key.
- compute(dt: float)[source]#
Updates the commands.
This function calls each command term managed by the class.
- Parameters:
dt – The time-step interval of the environment.
- get_command(name: str) torch.Tensor [source]#
Returns the command for the specified command term.
- Parameters:
name – The name of the command term.
- Returns:
The command tensor of the specified command term.
- get_term(name: str) CommandTerm [source]#
Returns the command term with the specified name.
- Parameters:
name – The name of the command term.
- Returns:
The command term with the specified name.
- class omni.isaac.lab.managers.CommandTerm[source]#
The base class for implementing a command term.
A command term is used to generate commands for goal-conditioned tasks. For example, in the case of a goal-conditioned navigation task, the command term can be used to generate a target position for the robot to navigate to.
It implements a resampling mechanism that allows the command to be resampled at a fixed frequency. The resampling frequency can be specified in the configuration object. Additionally, it is possible to assign a visualization function to the command term that can be used to visualize the command in the simulator.
Attributes:
The command tensor.
Whether the command generator has a debug visualization implemented.
Methods:
set_debug_vis
(debug_vis)Sets whether to visualize the command data.
reset
([env_ids])Reset the command generator and log metrics.
compute
(dt)Compute the command.
- abstract property command: torch.Tensor#
The command tensor. Shape is (num_envs, command_dim).
- property has_debug_vis_implementation: bool#
Whether the command generator has a debug visualization implemented.
- set_debug_vis(debug_vis: bool) bool [source]#
Sets whether to visualize the command data.
- Parameters:
debug_vis – Whether to visualize the command data.
- Returns:
Whether the debug visualization was successfully set. False if the command generator does not support debug visualization.
- reset(env_ids: Sequence[int] | None = None) dict[str, float] [source]#
Reset the command generator and log metrics.
This function resets the command counter and resamples the command. It should be called at the beginning of each episode.
- Parameters:
env_ids – The list of environment IDs to reset. Defaults to None.
- Returns:
A dictionary containing the information to log under the “{name}” key.
Reward Manager#
- class omni.isaac.lab.managers.RewardManager[source]#
Bases:
ManagerBase
Manager for computing reward signals for a given world.
The reward manager computes the total reward as a sum of the weighted reward terms. The reward terms are parsed from a nested config class containing the reward manger’s settings and reward terms configuration.
The reward terms are parsed from a config class containing the manager’s settings and each term’s parameters. Each reward term should instantiate the
RewardTermCfg
class.Note
The reward manager multiplies the reward term’s
weight
with the time-step intervaldt
of the environment. This is done to ensure that the computed reward terms are balanced with respect to the chosen time-step interval in the environment.Methods:
__init__
(cfg, env)Initialize the reward manager.
reset
([env_ids])Returns the episodic sum of individual reward terms.
compute
(dt)Computes the reward signal as a weighted sum of individual terms.
set_term_cfg
(term_name, cfg)Sets the configuration of the specified term into the manager.
get_term_cfg
(term_name)Gets the configuration for the specified term.
find_terms
(name_keys)Find terms in the manager based on the names.
Attributes:
Name of active reward terms.
Device on which to perform computations.
Number of environments.
- __init__(cfg: object, env: ManagerBasedRLEnv)[source]#
Initialize the reward manager.
- Parameters:
cfg – The configuration object or dictionary (
dict[str, RewardTermCfg]
).env – The environment instance.
- reset(env_ids: Sequence[int] | None = None) dict[str, torch.Tensor] [source]#
Returns the episodic sum of individual reward terms.
- Parameters:
env_ids – The environment ids for which the episodic sum of individual reward terms is to be returned. Defaults to all the environment ids.
- Returns:
Dictionary of episodic sum of individual reward terms.
- compute(dt: float) torch.Tensor [source]#
Computes the reward signal as a weighted sum of individual terms.
This function calls each reward term managed by the class and adds them to compute the net reward signal. It also updates the episodic sums corresponding to individual reward terms.
- Parameters:
dt – The time-step interval of the environment.
- Returns:
The net reward signal of shape (num_envs,).
- set_term_cfg(term_name: str, cfg: RewardTermCfg)[source]#
Sets the configuration of the specified term into the manager.
- Parameters:
term_name – The name of the reward term.
cfg – The configuration for the reward term.
- Raises:
ValueError – If the term name is not found.
- get_term_cfg(term_name: str) RewardTermCfg [source]#
Gets the configuration for the specified term.
- Parameters:
term_name – The name of the reward term.
- Returns:
The configuration of the reward term.
- Raises:
ValueError – If the term name is not found.
- find_terms(name_keys: str | Sequence[str]) list[str] #
Find terms in the manager based on the names.
This function searches the manager for terms based on the names. The names can be specified as regular expressions or a list of regular expressions. The search is performed on the active terms in the manager.
Please check the
omni.isaac.lab.utils.string_utils.resolve_matching_names()
function for more information on the name matching.- Parameters:
name_keys – A regular expression or a list of regular expressions to match the term names.
- Returns:
A list of term names that match the input keys.
Termination Manager#
- class omni.isaac.lab.managers.TerminationManager[source]#
Bases:
ManagerBase
Manager for computing done signals for a given world.
The termination manager computes the termination signal (also called dones) as a combination of termination terms. Each termination term is a function which takes the environment as an argument and returns a boolean tensor of shape (num_envs,). The termination manager computes the termination signal as the union (logical or) of all the termination terms.
Following the Gymnasium API, the termination signal is computed as the logical OR of the following signals:
Time-out: This signal is set to true if the environment has ended after an externally defined condition (that is outside the scope of a MDP). For example, the environment may be terminated if the episode has timed out (i.e. reached max episode length).
Terminated: This signal is set to true if the environment has reached a terminal state defined by the environment. This state may correspond to task success, task failure, robot falling, etc.
These signals can be individually accessed using the
time_outs
andterminated
properties.The termination terms are parsed from a config class containing the manager’s settings and each term’s parameters. Each termination term should instantiate the
TerminationTermCfg
class. The term’s configurationTerminationTermCfg.time_out
decides whether the term is a timeout or a termination term.Methods:
__init__
(cfg, env)Initializes the termination manager.
reset
([env_ids])Returns the episodic counts of individual termination terms.
compute
()Computes the termination signal as union of individual terms.
get_term
(name)Returns the termination term with the specified name.
set_term_cfg
(term_name, cfg)Sets the configuration of the specified term into the manager.
get_term_cfg
(term_name)Gets the configuration for the specified term.
find_terms
(name_keys)Find terms in the manager based on the names.
Attributes:
Name of active termination terms.
The net termination signal.
The timeout signal (reaching max episode length).
The terminated signal (reaching a terminal state).
Device on which to perform computations.
Number of environments.
- __init__(cfg: object, env: ManagerBasedRLEnv)[source]#
Initializes the termination manager.
- Parameters:
cfg – The configuration object or dictionary (
dict[str, TerminationTermCfg]
).env – An environment object.
- property dones: torch.Tensor#
The net termination signal. Shape is (num_envs,).
- property time_outs: torch.Tensor#
The timeout signal (reaching max episode length). Shape is (num_envs,).
This signal is set to true if the environment has ended after an externally defined condition (that is outside the scope of a MDP). For example, the environment may be terminated if the episode has timed out (i.e. reached max episode length).
- property terminated: torch.Tensor#
The terminated signal (reaching a terminal state). Shape is (num_envs,).
This signal is set to true if the environment has reached a terminal state defined by the environment. This state may correspond to task success, task failure, robot falling, etc.
- reset(env_ids: Sequence[int] | None = None) dict[str, torch.Tensor] [source]#
Returns the episodic counts of individual termination terms.
- Parameters:
env_ids – The environment ids. Defaults to None, in which case all environments are considered.
- Returns:
Dictionary of episodic sum of individual reward terms.
- compute() torch.Tensor [source]#
Computes the termination signal as union of individual terms.
This function calls each termination term managed by the class and performs a logical OR operation to compute the net termination signal.
- Returns:
The combined termination signal of shape (num_envs,).
- get_term(name: str) torch.Tensor [source]#
Returns the termination term with the specified name.
- Parameters:
name – The name of the termination term.
- Returns:
The corresponding termination term value. Shape is (num_envs,).
- set_term_cfg(term_name: str, cfg: TerminationTermCfg)[source]#
Sets the configuration of the specified term into the manager.
- Parameters:
term_name – The name of the termination term.
cfg – The configuration for the termination term.
- Raises:
ValueError – If the term name is not found.
- get_term_cfg(term_name: str) TerminationTermCfg [source]#
Gets the configuration for the specified term.
- Parameters:
term_name – The name of the termination term.
- Returns:
The configuration of the termination term.
- Raises:
ValueError – If the term name is not found.
- find_terms(name_keys: str | Sequence[str]) list[str] #
Find terms in the manager based on the names.
This function searches the manager for terms based on the names. The names can be specified as regular expressions or a list of regular expressions. The search is performed on the active terms in the manager.
Please check the
omni.isaac.lab.utils.string_utils.resolve_matching_names()
function for more information on the name matching.- Parameters:
name_keys – A regular expression or a list of regular expressions to match the term names.
- Returns:
A list of term names that match the input keys.
- class omni.isaac.lab.managers.TerminationTermCfg[source]#
Configuration for a termination term.
Attributes:
The parameters to be passed to the function as keyword arguments.
The name of the function to be called.
Whether the termination term contributes towards episodic timeouts.
- params: dict[str, Any | SceneEntityCfg]#
The parameters to be passed to the function as keyword arguments. Defaults to an empty dict.
Note
If the value is a
SceneEntityCfg
object, the manager will query the scene entity from theInteractiveScene
and process the entity’s joints and bodies as specified in theSceneEntityCfg
object.
- func: Callable[..., torch.Tensor]#
The name of the function to be called.
This function should take the environment object and any other parameters as input and return the termination signals as torch boolean tensors of shape (num_envs,).
Curriculum Manager#
- class omni.isaac.lab.managers.CurriculumManager[source]#
Bases:
ManagerBase
Manager to implement and execute specific curricula.
The curriculum manager updates various quantities of the environment subject to a training curriculum by calling a list of terms. These help stabilize learning by progressively making the learning tasks harder as the agent improves.
The curriculum terms are parsed from a config class containing the manager’s settings and each term’s parameters. Each curriculum term should instantiate the
CurriculumTermCfg
class.Methods:
__init__
(cfg, env)Initialize the manager.
reset
([env_ids])Returns the current state of individual curriculum terms.
compute
([env_ids])Update the curriculum terms.
find_terms
(name_keys)Find terms in the manager based on the names.
Attributes:
Name of active curriculum terms.
Device on which to perform computations.
Number of environments.
- __init__(cfg: object, env: ManagerBasedRLEnv)[source]#
Initialize the manager.
- Parameters:
cfg – The configuration object or dictionary (
dict[str, CurriculumTermCfg]
)env – An environment object.
- Raises:
TypeError – If curriculum term is not of type
CurriculumTermCfg
.ValueError – If curriculum term configuration does not satisfy its function signature.
- reset(env_ids: Sequence[int] | None = None) dict[str, float] [source]#
Returns the current state of individual curriculum terms.
Note
This function does not use the environment indices
env_ids
and logs the state of all the terms. The argument is only present to maintain consistency with other classes.- Returns:
Dictionary of curriculum terms and their states.
- compute(env_ids: Sequence[int] | None = None)[source]#
Update the curriculum terms.
This function calls each curriculum term managed by the class.
- Parameters:
env_ids – The list of environment IDs to update. If None, all the environments are updated. Defaults to None.
- find_terms(name_keys: str | Sequence[str]) list[str] #
Find terms in the manager based on the names.
This function searches the manager for terms based on the names. The names can be specified as regular expressions or a list of regular expressions. The search is performed on the active terms in the manager.
Please check the
omni.isaac.lab.utils.string_utils.resolve_matching_names()
function for more information on the name matching.- Parameters:
name_keys – A regular expression or a list of regular expressions to match the term names.
- Returns:
A list of term names that match the input keys.
- class omni.isaac.lab.managers.CurriculumTermCfg[source]#
Configuration for a curriculum term.
Attributes:
The name of the function to be called.
The parameters to be passed to the function as keyword arguments.
- func: Callable[..., float | dict[str, float] | None]#
The name of the function to be called.
This function should take the environment object, environment indices and any other parameters as input and return the curriculum state for logging purposes. If the function returns None, the curriculum state is not logged.
- params: dict[str, Any | SceneEntityCfg]#
The parameters to be passed to the function as keyword arguments. Defaults to an empty dict.
Note
If the value is a
SceneEntityCfg
object, the manager will query the scene entity from theInteractiveScene
and process the entity’s joints and bodies as specified in theSceneEntityCfg
object.