isaaclab_contrib.custom_coupling

Opt-in example of a custom Newton coupled solver.

Import isaaclab_contrib.custom_coupling.tasks to register the example task.

The custom MJWarp and VBD coupled solver is an opt-in example. Import isaaclab_contrib.custom_coupling.tasks explicitly to register IsaacContrib-Lift-Soft-Franka-Custom-Coupling. The environment requires a full Isaac Lab installation containing isaaclab_tasks.

Classes

coupled_mjwarp_vbd_solver_cfg.CoupledMJWarpVBDSolverCfg	Configuration for the custom MJWarp and VBD coupled solver.
coupled_mjwarp_vbd_solver.CoupledMJWarpVBDSolver	Couple MJWarp rigid bodies with VBD deformables, each built from its own configuration.
franka_soft_env_cfg.FrankaSoftCustomCouplingEnvCfg	Franka soft lifting with manual MJWarp and VBD coupling.

Custom Coupling

class isaaclab_contrib.custom_coupling.coupled_mjwarp_vbd_solver_cfg.CoupledMJWarpVBDSolverCfg

Bases: NewtonSolverCfg

Configuration for the custom MJWarp and VBD coupled solver.

Attributes:

class_type	Solver class whose class methods build and drive Newton's solver, e.g. class_type.build(cfg, model, mode).
rigid_solver_cfg	MJWarp rigid-body solver configuration.
solver_type	Solver type metadata (deprecated).
soft_solver_cfg	VBD deformable solver configuration.
coupling_mode	Coupling direction between the rigid and deformable solvers.

class_type: type | str

Solver class whose class methods build and drive Newton’s solver, e.g. class_type.build(cfg, model, mode).

rigid_solver_cfg: MJWarpSolverCfg

MJWarp rigid-body solver configuration.

solver_type: str

Solver type metadata (deprecated).

Deprecated since version Solver: dispatch is driven by the configuration class; this field is retained as metadata for logging and debugging only. Do not branch on solver_type in new code.

soft_solver_cfg: VBDSolverCfg

VBD deformable solver configuration.

coupling_mode: Literal['one_way', 'two_way']

Coupling direction between the rigid and deformable solvers.

class isaaclab_contrib.custom_coupling.coupled_mjwarp_vbd_solver.CoupledMJWarpVBDSolver

Bases: NewtonSolver

Couple MJWarp rigid bodies with VBD deformables, each built from its own configuration.

Attributes:

contact_sensors

Whether Newton contact sensors can read the solver's contacts.

Methods:

solver_classes(cfg)	Newton solvers whose custom builder attributes, and USD schemas, the builder needs before import.
prepare_builder(cfg, builder)	Prepare the completed builder for both sub-solvers, e.g. color it for VBD.
build(cfg, model, mode[, env_template])	Construct both sub-solvers through their own configurations.
prepare_contacts(cfg, solver, contacts, pipeline)	Bind the collision pipeline used inside each coupled substep.
pre_step(cfg, solver, state)	Refresh solver structures once per physics step, before collision.

contact_sensors: ClassVar[bool] = False

Whether Newton contact sensors can read the solver’s contacts.

classmethod solver_classes(cfg: CoupledMJWarpVBDSolverCfg) → tuple[type[SolverBase], ...]

Newton solvers whose custom builder attributes, and USD schemas, the builder needs before import.

classmethod prepare_builder(cfg: CoupledMJWarpVBDSolverCfg, builder: ModelBuilder) → None

Prepare the completed builder for both sub-solvers, e.g. color it for VBD.

classmethod build(cfg: CoupledMJWarpVBDSolverCfg, model: Model, mode: wp.DeterministicMode, env_template: str | None = None) → SolverCoupledMJWarpVBD

Construct both sub-solvers through their own configurations.

classmethod prepare_contacts(cfg: CoupledMJWarpVBDSolverCfg, solver: SolverCoupledMJWarpVBD, contacts: Contacts, pipeline: CollisionPipeline | None) → None

Bind the collision pipeline used inside each coupled substep.

classmethod pre_step(cfg: CoupledMJWarpVBDSolverCfg, solver: SolverCoupledMJWarpVBD, state: State) → None

Refresh solver structures once per physics step, before collision.

class isaaclab_contrib.custom_coupling.franka_soft_env_cfg.FrankaSoftCustomCouplingEnvCfg

Bases: FrankaSoftEnvCfg

Franka soft lifting with manual MJWarp and VBD coupling.

Methods:

__init__([class_type, sim, ...])

Attributes:

class_type	The environment class constructed from this configuration.
sim	Physics simulation configuration.
ui_window_class_type	The class type of the UI window.
seed	The seed for the random number generator.
decimation	Number of control action updates @ sim dt per policy dt.
scene	Scene settings.
recorders	Recorder settings.
observations	Observation space settings.
actions	Action space settings.
events	Event settings.
rerender_on_reset	Whether a render step is performed again after at least one environment has been reset.
num_rerenders_on_reset	Number of render steps to perform after reset.
wait_for_textures	True to wait for assets to be loaded completely, False otherwise.
xr	Configuration for viewing and interacting with the environment through an XR device.
teleop_devices	Configuration for teleoperation devices.
isaac_teleop	Configuration for Isaac Capture-based teleoperation.
export_io_descriptors	Whether to export the IO descriptors for the environment.
log_dir	Directory for logging experiment artifacts.
video_recorders	Video recording streams.
viewer	Deprecated viewer configuration.
is_finite_horizon	Whether the learning task is treated as a finite or infinite horizon problem for the agent.
compute_final_obs	Whether to capture the terminal observation before a Same-Step autoreset and expose it.
episode_length_s	Duration of an episode (in seconds).
rewards	Reward settings.
terminations	Termination settings.
curriculum	Curriculum settings.
commands	Command settings.

__init__(class_type: type | str = <factory>, sim: SimulationCfg = <factory>, ui_window_class_type: type | str | None = <factory>, seed: int | None = <factory>, decimation: int = <factory>, scene: FrankaSoftSceneCfg = <factory>, recorders: object = <factory>, observations: ObservationsCfg = <factory>, actions: ActionsCfg = <factory>, events: EventCfg = <factory>, rerender_on_reset: bool = <factory>, num_rerenders_on_reset: int = <factory>, wait_for_textures: bool = <factory>, xr: XrCfg | None = <factory>, teleop_devices: DevicesCfg = <factory>, isaac_teleop: object | None = <factory>, export_io_descriptors: bool = <factory>, log_dir: str | None = <factory>, video_recorders: list[VideoRecorderCfg] = <factory>, viewer: ViewerCfg = <factory>, is_finite_horizon: bool = <factory>, compute_final_obs: bool = <factory>, episode_length_s: float = <factory>, rewards: RewardsCfg = <factory>, terminations: TerminationsCfg = <factory>, curriculum: CurriculumCfg = <factory>, commands: CommandsCfg = <factory>) → None

class_type: type | str

The environment class constructed from this configuration.

sim: SimulationCfg

Physics simulation configuration. Default is SimulationCfg().

ui_window_class_type: type | str | None

The class type of the UI window. Default is None.

If None, then no UI window is created.

Note

If you want to make your own UI window, you can create a class that inherits from from isaaclab.envs.ui.base_env_window.BaseEnvWindow. Then, you can set this attribute to your class type.

seed: int | None

The seed for the random number generator. Defaults to None, in which case the seed is not set.

Note

The seed is set at the beginning of the environment initialization. This ensures that the environment creation is deterministic and behaves similarly across different runs.

decimation: int

Number of control action updates @ sim dt per policy dt.

For instance, if the simulation dt is 0.01s and the policy dt is 0.1s, then the decimation is 10. This means that the control action is updated every 10 simulation steps.

scene: FrankaSoftSceneCfg

Scene settings.

Please refer to the isaaclab.scene.InteractiveSceneCfg class for more details.

recorders: object

Recorder settings. Defaults to recording nothing.

Please refer to the isaaclab.managers.RecorderManager class for more details.

observations: ObservationsCfg

Observation space settings.

Please refer to the isaaclab.managers.ObservationManager class for more details.

actions: ActionsCfg

Action space settings.

Please refer to the isaaclab.managers.ActionManager class for more details.

events: EventCfg

Event settings. Defaults to the basic configuration that resets the scene to its default state.

Please refer to the isaaclab.managers.EventManager class for more details.

rerender_on_reset: bool

Whether a render step is performed again after at least one environment has been reset. Defaults to False, which means no render step will be performed after reset.

• When this is False, data collected from sensors after performing reset will be stale and will not reflect the latest states in simulation caused by the reset.

• When this is True, an extra render step will be performed to update the sensor data to reflect the latest states from the reset. This comes at a cost of performance as an additional render step will be performed after each time an environment is reset.

Deprecated since version 2.3.1: This attribute is deprecated and will be removed in the future. Please use num_rerenders_on_reset instead.

To get the same behaviour as setting this parameter to True or False, set num_rerenders_on_reset to 1 or 0, respectively.

num_rerenders_on_reset: int

Number of render steps to perform after reset. Defaults to 0, which means no render step will be performed after reset.

• When this is 0, no render step will be performed after reset. Data collected from sensors after performing reset will be stale and will not reflect the latest states in simulation caused by the reset.

• When this is greater than 0, the specified number of extra render steps will be performed to update the sensor data to reflect the latest states from the reset. This comes at a cost of performance as additional render steps will be performed after each time an environment is reset.

wait_for_textures: bool

True to wait for assets to be loaded completely, False otherwise. Defaults to True.

xr: XrCfg | None

Configuration for viewing and interacting with the environment through an XR device.

teleop_devices: DevicesCfg

Configuration for teleoperation devices.

isaac_teleop: object | None

Configuration for Isaac Capture-based teleoperation.

When set, the environment uses the Isaac Capture stack for XR teleoperation instead of the native Isaac Lab teleop devices. This should be a IsaacTeleopCfg instance from the isaaclab_teleop package.

The teleop scripts will automatically detect this configuration and use the Isaac Capture stack when present.

export_io_descriptors: bool

Whether to export the IO descriptors for the environment. Defaults to False.

Deprecated since version 3.0: IO descriptors will be removed in Isaac Lab 3.2. Use the LEAPP export workflow for supported RSL-RL/PyTorch deployments.

log_dir: str | None

Directory for logging experiment artifacts. Defaults to None, in which case no specific log directory is set.

video_recorders: list[VideoRecorderCfg]

Video recording streams. Each entry records from its configured source independently.

Leave empty to disable recording. Set --video on the CLI to auto-populate this list with a default stream from the active visualizer.

viewer: ViewerCfg

Deprecated viewer configuration. Use visualizer_cfgs instead.

Deprecated since version This: field is deprecated and will be removed in a future release. Configure the viewport camera via VisualizerCfg on the simulation config::

from isaaclab.visualizers import VisualizerCfg env_cfg.sim.visualizer_cfgs = VisualizerCfg(eye=(4.5, 0.0, 6.0))

is_finite_horizon: bool

Whether the learning task is treated as a finite or infinite horizon problem for the agent. Defaults to False, which means the task is treated as an infinite horizon problem.

This flag handles the subtleties of finite and infinite horizon tasks:

• Finite horizon: no penalty or bootstrapping value is required by the the agent for running out of time. However, the environment still needs to terminate the episode after the time limit is reached.

• Infinite horizon: the agent needs to bootstrap the value of the state at the end of the episode. This is done by sending a time-limit (or truncated) done signal to the agent, which triggers this bootstrapping calculation.

If True, then the environment is treated as a finite horizon problem and no time-out (or truncated) done signal is sent to the agent. If False, then the environment is treated as an infinite horizon problem and a time-out (or truncated) done signal is sent to the agent.

Note

The base ManagerBasedRLEnv class does not use this flag directly. It is used by the environment wrappers to determine what type of done signal to send to the corresponding learning agent.

compute_final_obs: bool

Whether to capture the terminal observation before a Same-Step autoreset and expose it.

Under Same-Step autoreset (see metadata), an environment that terminates is reset within the same step() call, so the returned observation belongs to the new episode. When this flag is True, the observation is computed once more before the reset and stored under extras["final_obs"], so wrappers can report it as the true terminal observation for value bootstrapping.

Defaults to False, which preserves the previous behavior: no terminal observation is captured, extras["final_obs"] is not populated, and the extra observation computation is skipped.

Note

Currently consumed by the Sb3VecEnvWrapper wrapper.

episode_length_s: float

Duration of an episode (in seconds).

Based on the decimation rate and physics time step, the episode length is calculated as:

episode_length_steps = ceil(episode_length_s / (decimation_rate * physics_time_step))

For example, if the decimation rate is 10, the physics time step is 0.01, and the episode length is 10 seconds, then the episode length in steps is 100.

rewards: RewardsCfg

Reward settings.

Please refer to the isaaclab.managers.RewardManager class for more details.

terminations: TerminationsCfg

Termination settings.

Please refer to the isaaclab.managers.TerminationManager class for more details.

curriculum: CurriculumCfg

Curriculum settings. Defaults to None, in which case no curriculum is applied.

Please refer to the isaaclab.managers.CurriculumManager class for more details.

commands: CommandsCfg

Command settings. Defaults to None, in which case no commands are generated.

Please refer to the isaaclab.managers.CommandManager class for more details.