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.
`fold_preset_tokens`(tokens)	Fold preset selector tokens into a single `presets=<csv>` token.
`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.
`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.

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.fold_preset_tokens(tokens: list[str]) → list[str][source]#

Fold preset selector tokens into a single presets=<csv> token.

Recognises physics=NAME / renderer=NAME / presets=NAME[,NAME,...] in tokens (exact key match; dotted keys like env.sim.physics=NAME are path-targeted overrides and pass through unchanged). All recognised names are deduped in first-occurrence order and emitted as a leading presets=<csv> token; every other token in tokens is appended in its original position.

Call this on the remainder returned by setup_preset_cli() before assigning sys.argv. Scripts that intersect the remainder with callback-returned tokens (e.g. rsl_rl/{train,play}.py’s --external_callback flow) must do the intersection first (both sides pre-fold) and then call this function.

Parameters:: tokens – Pre-fold token list (typically the second element of the tuple returned by setup_preset_cli()).
Returns:: A new list with selector tokens folded into one leading presets=<csv> token if any were present; otherwise the input list is returned unchanged.

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

Does NOT fold typed selectors. The returned remainder still contains the user-typed physics= / renderer= / presets= tokens verbatim, alongside any Hydra path overrides and any unknown argparse flags. Call fold_preset_tokens() on the remainder before assigning sys.argv; keeping parse and fold separate lets callers run other filters (notably rsl_rl’s --external_callback intersection) on the pre-fold list, where vocabularies match.

Does not mutate sys.argv; the caller assigns sys.argv = [sys.argv[0]] + fold_preset_tokens(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.

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). Apply fold_preset_tokens() to remaining before handing it to Hydra.

isaaclab_tasks.utils

Contents

isaaclab_tasks.utils#