isaaclab_tasks.utils

isaaclab_tasks.utils#

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

Classes:

PresetCfg

Base class for declarative preset definitions.

Functions:

`add_launcher_args`(parser)	Add simulation-launcher CLI arguments (`--headless`, `--device`, etc.) to parser.
`compute_kit_requirements`(env_cfg[, ...])	Compute whether Kit is needed and related flags.
`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.
`launch_simulation`(env_cfg[, launcher_args])	Context manager that launches the appropriate simulation runtime for env_cfg.
`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.

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: NewtonCfg = NewtonCfg()

Methods:

__init__()

__init__() → None#

isaaclab_tasks.utils.add_launcher_args(parser: ArgumentParser) → None[source]#

Add simulation-launcher CLI arguments (--headless, --device, etc.) to parser.

Delegates to AppLauncher.add_app_launcher_args() so that user scripts do not need to import AppLauncher directly.

isaaclab_tasks.utils.compute_kit_requirements(env_cfg, launcher_args: Namespace | dict | None = None) → tuple[bool, bool, set[str]][source]#

Compute whether Kit is needed and related flags.

Uses the same logic as launch_simulation() to decide whether Isaac Sim Kit must be launched.

Parameters:

env_cfg – Resolved environment config (e.g. from resolve_task_config()).
launcher_args – Optional CLI args; if --visualizer includes kit, needs_kit is True.

Returns:

(needs_kit, has_kit_cameras, visualizer_types)

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-v0”)
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.launch_simulation(env_cfg, launcher_args: Namespace | dict | None = None) → Generator[None, None, None][source]#

Context manager that launches the appropriate simulation runtime for env_cfg.

Recursively scans the config tree to decide whether Isaac Sim Kit is needed.
Auto-enables enable_cameras when the scene contains camera sensors that use a Kit renderer (not Newton).
For Kit-based backends, launches AppLauncher and calls app.close() on exit.
For kitless backends (e.g. Newton with Newton Warp renderer only), this is a no-op.
For Newton Physics + RTX Renderer (with Kit cameras): Kit is launched so that RTX can run; Newton syncs its state to the USD stage each step for rendering.

Example:

with launch_simulation(env_cfg, args_cli):
    main()

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=0.01)
# Equivalent to:
# @configclass
# class _Preset(PresetCfg):
#     default: float = 0.0
#     newton: 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: set[str] = frozenset({}))[source]#

Replace every PresetCfg in the tree with the best alternative.

For each PresetCfg found during a depth-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

Contents

isaaclab_tasks.utils#