isaaclab_tasks.utils

isaaclab_tasks.utils#

Sub-package with utilities, data collectors and environment wrappers.

Classes:

PresetCfg

Base class for declarative preset definitions.

Functions:

`get_checkpoint_path`(log_path[, run_dir, ...])	Get path to the model checkpoint in input directory.
`hydra_task_config`(task_name, ...)	Decorator for Hydra config with REPLACE-only preset semantics.
`import_packages`(package_name[, blacklist_pkgs])	Import all sub-packages in a package recursively.
`load_cfg_from_registry`(task_name, ...)	Load default configuration given its entry point from the gym registry.
`parse_env_cfg`(task_name[, device, num_envs, ...])	Parse configuration for an environment and override based on inputs.
`preset`(**options)	Create a `PresetCfg` instance from keyword arguments.
`resolve_presets`(cfg[, selected])	Replace every `PresetCfg` in the tree with the best alternative.
`resolve_task_config`(task_name, ...)	Resolve env and agent configs with Hydra overrides, presets, and scalars fully applied.
`setup_preset_cli`(parser[, argv])	Register the preset-selection help description and parse argv.

class isaaclab_tasks.utils.PresetCfg[source]#

Base class for declarative preset definitions.

Subclass this and define fields as preset options. The field named default holds the config instance used when no CLI override is given. All other fields are named alternative presets.

Example:

@configclass
class PhysicsCfg(PresetCfg):
    default: PhysxCfg = PhysxCfg()
    newton_mjwarp: NewtonCfg = NewtonCfg()

The preset name (newton_mjwarp) is decoupled from the config class (NewtonCfg): the class describes the Newton backend, while the field name labels which solver variant this entry selects.

Class-local helpers (underscore convention). Names prefixed with _ and callables (nested classes, methods) are skipped by the resolver and are NOT registered as variants. Use this to keep shared helpers adjacent to the variants that need them, without polluting the module namespace:

@configclass
class MultiBackendCameraCfg(PresetCfg):
    # Class-local helper -- not a variant.
    _ROTATED_OFFSET = CameraCfg.OffsetCfg(rot=(1, 0, 0, 0), ...)

    rgb = CameraCfg(data_types=["rgb"])
    albedo = CameraCfg(data_types=["albedo"], offset=_ROTATED_OFFSET)
    default = rgb

Methods:

__init__()

__init__() → None#

isaaclab_tasks.utils.get_checkpoint_path(log_path: str, run_dir: str = '.*', checkpoint: str = '.*', other_dirs: list[str] = None, sort_alpha: bool = True) → str[source]#

Get path to the model checkpoint in input directory.

The checkpoint file is resolved as: <log_path>/<run_dir>/<*other_dirs>/<checkpoint>, where the other_dirs are intermediate folder names to concatenate. These cannot be regex expressions.

If run_dir and checkpoint are regex expressions then the most recent (highest alphabetical order) run and checkpoint are selected. To disable this behavior, set the flag sort_alpha to False.

Parameters:

log_path – The log directory path to find models in.
run_dir – The regex expression for the name of the directory containing the run. Defaults to the most recent directory created inside log_path.
other_dirs – The intermediate directories between the run directory and the checkpoint file. Defaults to None, which implies that checkpoint file is directly under the run directory.
checkpoint – The regex expression for the model checkpoint file. Defaults to the most recent torch-model saved in the run_dir directory.
sort_alpha – Whether to sort the runs by alphabetical order. Defaults to True. If False, the folders in run_dir are sorted by the last modified time.

Returns:

The path to the model checkpoint.

Raises:

ValueError – When no runs are found in the input directory.
ValueError – When no checkpoints are found in the input directory.

isaaclab_tasks.utils.hydra_task_config(task_name: str, agent_cfg_entry_point: str) → Callable[source]#

Decorator for Hydra config with REPLACE-only preset semantics.

Parameters:

task_name – Task name (e.g., “Isaac-Reach-Franka”)
agent_cfg_entry_point – Agent config entry point key

Returns:

Decorated function receiving (env_cfg, agent_cfg, *args, **kwargs)

isaaclab_tasks.utils.import_packages(package_name: str, blacklist_pkgs: list[str] | None = None)[source]#

Import all sub-packages in a package recursively.

Only packages (directories with __init__.py) are imported — plain .py modules (e.g. env_cfg.py, env.py) are skipped. This is sufficient because gym.register() calls live exclusively in __init__.py files, and avoids eagerly importing every config module at startup.

Parameters:

package_name – The package name.
blacklist_pkgs – The list of blacklisted packages to skip. Defaults to None, which means no packages are blacklisted.

isaaclab_tasks.utils.load_cfg_from_registry(task_name: str, entry_point_key: str) → dict | object[source]#

Load default configuration given its entry point from the gym registry.

This function loads the configuration object from the gym registry for the given task name. It supports both YAML and Python configuration files.

It expects the configuration to be registered in the gym registry as:

gym.register(
    id="My-Awesome-Task-v0",
    ...
    kwargs={"env_entry_point_cfg": "path.to.config:ConfigClass"},
)

The parsed configuration object for above example can be obtained as:

from isaaclab_tasks.utils.parse_cfg import load_cfg_from_registry

cfg = load_cfg_from_registry("My-Awesome-Task-v0", "env_entry_point_cfg")

Parameters:

task_name – The name of the environment.
entry_point_key – The entry point key to resolve the configuration file.

Returns:

The parsed configuration object. If the entry point is a YAML file, it is parsed into a dictionary. If the entry point is a Python class, it is instantiated and returned.

Raises:

ValueError – If the entry point key is not available in the gym registry for the task.

isaaclab_tasks.utils.parse_env_cfg(task_name: str, device: str = 'cuda:0', num_envs: int | None = None, use_fabric: bool | None = None) → ManagerBasedRLEnvCfg | DirectRLEnvCfg[source]#

Parse configuration for an environment and override based on inputs.

Parameters:

task_name – The name of the environment.
device – The device to run the simulation on. Defaults to “cuda:0”.
num_envs – Number of environments to create. Defaults to None, in which case it is left unchanged.
use_fabric – Whether to enable/disable fabric interface. If false, all read/write operations go through USD. This slows down the simulation but allows seeing the changes in the USD through the USD stage. Defaults to None, in which case it is left unchanged.

Returns:

The parsed configuration object.

Raises:

RuntimeError – If the configuration for the task is not a class. We assume users always use a class for the environment configuration.

isaaclab_tasks.utils.preset(**options) → PresetCfg[source]#

Create a PresetCfg instance from keyword arguments.

A convenience factory that dynamically builds a PresetCfg subclass with one field per keyword argument, then returns an instance of it. The caller must supply a default key.

Example:

armature = preset(default=0.0, newton_mjwarp=0.01)
# Equivalent to:
# @configclass
# class _Preset(PresetCfg):
#     default: float = 0.0
#     newton_mjwarp: float = 0.01
# armature = _Preset()

Parameters:: **options – Preset alternatives keyed by name. Must include default.
Returns:: A PresetCfg instance whose fields are the supplied options.
Raises:: ValueError – If default is not provided.

isaaclab_tasks.utils.resolve_presets(cfg, selected=())[source]#

Replace every PresetCfg in the tree with the best alternative.

For each PresetCfg found during an active-tree breadth-first walk:

Pick the first name from selected that exists as a field on the preset, otherwise fall back to default.
Replace the preset in its parent (dict key or dataclass attr).
Continue walking the replacement (which may contain more presets).

Parameters:

cfg – A configclass, dict, or PresetCfg to resolve in-place.
selected – Set of preset names chosen by the user (e.g. from CLI presets=peg_insert_4mm,eval).

Returns:

The resolved cfg (possibly a different object if the root itself was a PresetCfg).

isaaclab_tasks.utils.resolve_task_config(task_name: str, agent_cfg_entry_point: str)[source]#

Resolve env and agent configs with Hydra overrides, presets, and scalars fully applied.

Safe to call before Kit is launched – callable config values are stored as ResolvableString and resolved lazily on first use, so no implementation modules are imported eagerly.

Parameters:

task_name – Task name (e.g., “Isaac-Velocity-Flat-Anymal-C-v0”).
agent_cfg_entry_point – Agent config entry point key (e.g., “rsl_rl_cfg_entry_point”).

Returns:

Tuple of (env_cfg, agent_cfg) fully resolved.

isaaclab_tasks.utils.setup_preset_cli(parser: ArgumentParser, argv: list[str] | None = None) → tuple[Namespace, list[str]][source]#

Register the preset-selection help description and parse argv.

Must be called after AppLauncher flags and script-specific arguments are registered on parser – otherwise those unknown tokens land in parse_known_args’s remainder.

The returned remainder contains the user-typed physics= / renderer= / presets= tokens verbatim, alongside any Hydra path overrides and any unknown argparse flags, ready to assign to sys.argv for hydra to parse.

Does not mutate sys.argv; the caller assigns sys.argv = [sys.argv[0]] + remaining when ready, so any argv-aware logic that re-reads sys.argv (e.g. an external callback) runs against the user’s original command line first.

Parameters:

parser – Caller’s argument parser. An argument_group is attached for help-time variant discovery; no add_argument calls are made, so the Namespace gains no preset attributes.
argv – Optional argument list to parse. When None (default), parse_known_args reads from sys.argv. Provided primarily for in-process test paths that drive the parser with a synthetic argv. Help-time variant enumeration always reads sys.argv – the user’s interactive command line is the only argv that triggers --help rendering.

Returns:

(args, remaining) where remaining is the verbatim output of parser.parse_known_args(argv), ready to hand to Hydra via sys.argv.

isaaclab_tasks.utils

Contents

isaaclab_tasks.utils#