isaaclab_contrib.coupling

Named Newton couplers and their configurations.

This package contains contributed coupled-solver support (proxy and ADMM based rigid-deformable coupling) that wraps Newton’s experimental coupled solvers. Each sub-solver declares its model ownership as a named entry, and coupling interfaces refer to those entries by name.

Classes

CouplerEntryCfg	Configuration for one named sub-solver and its model ownership.
CouplerCfg	Base configuration for a Newton experimental coupled solver.
CouplerProxyMappingCfg	Configuration for one directed virtual-proxy mapping.
CouplerProxyCfg	Configuration for Newton's lagged-impulse virtual-proxy coupling.
CouplerAdmmCfg	Configuration for Newton's linearized ADMM coupling.
CouplerSolver	Couple named entries, each built from its own solver configuration on its model view.

Coupler Configurations

class isaaclab_contrib.coupling.CouplerEntryCfg

Bases: object

Configuration for one named sub-solver and its model ownership.

Bodies are selected by full Newton body-label regex. Joints and shapes attached to selected bodies are included by default; additional shapes can be selected directly by their full labels.

Attributes:

name	Unique name used by coupling mappings to reference this entry.
solver_cfg	Configuration used to construct this entry's Newton solver.
bodies	Bodies owned by this entry.
particles	Parent-model particle indices owned by this entry.
all_particles	Whether this entry owns every particle in the parent model.
include_child_joints	Whether fully selected child joints are owned by this entry.
include_body_shapes	Whether shapes attached to selected bodies are owned by this entry.
include_static_shapes	Whether this entry owns all shapes whose body index is -1.
shape_label_patterns	Regexes matched against full Newton shape labels, with {ENV_REGEX_NS} expansion.
substeps	Number of equal substeps this entry runs inside one coupled step.
in_place	Whether this entry steps in-place instead of using a second state buffer.

name: str

Unique name used by coupling mappings to reference this entry.

solver_cfg: NewtonSolverCfg

Configuration used to construct this entry’s Newton solver.

bodies: list[str]

Bodies owned by this entry.

Each string is treated as a regex matched against full Newton body labels, including all descendant body labels below the matched path. {ENV_REGEX_NS} expands to the simulation’s declared clone template.

particles: list[int]

Parent-model particle indices owned by this entry.

all_particles: bool

Whether this entry owns every particle in the parent model.

include_child_joints: bool

Whether fully selected child joints are owned by this entry.

A joint is owned when its child body is selected and its parent is either the world or selected by the same entry.

include_body_shapes: bool

Whether shapes attached to selected bodies are owned by this entry.

include_static_shapes: bool

Whether this entry owns all shapes whose body index is -1.

shape_label_patterns: list[str]

Regexes matched against full Newton shape labels, with {ENV_REGEX_NS} expansion.

substeps: int

Number of equal substeps this entry runs inside one coupled step.

in_place: bool

Whether this entry steps in-place instead of using a second state buffer.

Use this only for solvers, such as implicit MPM, whose public stepping contract explicitly supports identical input and output states. Coupled MPM entries require this field to be True.

class isaaclab_contrib.coupling.CouplerCfg

Bases: NewtonSolverCfg

Base configuration for a Newton experimental coupled solver.

Bodies, particles, joints, and shapes may be assigned to at most one entry. Unassigned model elements remain outside the nested solvers. Use a concrete subclass to configure the coupling interfaces.

Attributes:

class_type	Solver class whose class methods build and drive Newton's solver, e.g. class_type.build(cfg, model, mode).
solver_type	Solver type metadata (deprecated).
entries	Ordered named sub-solver entries and their ownership selectors.
outer_contact_entry	Entry whose shape pairs the outer collision pipeline collides, or None for the whole model.

class_type: type | str

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

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.

entries: list[CouplerEntryCfg]

Ordered named sub-solver entries and their ownership selectors.

outer_contact_entry: str | None

Entry whose shape pairs the outer collision pipeline collides, or None for the whole model.

Restricting outer contacts to one entry lets another entry, e.g. a cable, run its own post-transfer pipeline.

class isaaclab_contrib.coupling.CouplerProxyMappingCfg

Bases: object

Configuration for one directed virtual-proxy mapping.

Attributes:

source	Name of the entry that owns the source bodies.
destination	Name of the entry that receives the proxy bodies.
bodies	Source bodies exposed as proxies in the destination entry.
particles	Source particle indices exposed as proxies in the destination entry.
mode	Proxy transfer mode passed to Newton's coupled-proxy solver.
mass_scale	Scale applied to proxy body mass/inertia and particle mass in the destination view.
proxy_relaxation	Relaxation factor applied to proxy-feedback forces in lagged and staggered modes.
proxy_relaxation_mode	Proxy-feedback relaxation mode.
proxy_relaxation_min	Minimum relaxation factor used by adaptive Aitken relaxation.
proxy_relaxation_max	Maximum relaxation factor used by adaptive Aitken relaxation.
collide_interval	Proxy-local collision refresh interval.
collision_pipeline	Configuration or factory for the proxy destination collision pipeline.

source: str

Name of the entry that owns the source bodies.

destination: str

Name of the entry that receives the proxy bodies.

bodies: list[str | int]

Source bodies exposed as proxies in the destination entry.

String selectors use the full-label-regex semantics of CouplerEntryCfg.bodies. Raw Newton body ids may be given directly as integers. The coupler resolves a copy at build time, preserving these declarations.

particles: list[int]

Source particle indices exposed as proxies in the destination entry.

mode: Literal['lagged', 'staggered']

Proxy transfer mode passed to Newton’s coupled-proxy solver.

mass_scale: float

Scale applied to proxy body mass/inertia and particle mass in the destination view.

proxy_relaxation: float

Relaxation factor applied to proxy-feedback forces in lagged and staggered modes.

Fixed relaxation blends the new force estimate with the previous feedback. Setting this to 0 from a fresh state preserves zero feedback while retaining source-to-destination proxy motion, which yields one-way coupling. Switching an ongoing run to zero instead preserves its existing feedback.

proxy_relaxation_mode: Literal['fixed', 'aitken']

Proxy-feedback relaxation mode.

proxy_relaxation_min: float

Minimum relaxation factor used by adaptive Aitken relaxation.

proxy_relaxation_max: float

Maximum relaxation factor used by adaptive Aitken relaxation.

collide_interval: int | None

Proxy-local collision refresh interval.

None refreshes contacts on every proxy pass. Explicit values must be positive integers and require collision_pipeline to be a factory.

collision_pipeline: NewtonCollisionPipelineCfg | Callable[[ModelView], CollisionPipeline | None] | None

Configuration or factory for the proxy destination collision pipeline.

Setting the field or returning None from the factory passes shared outer contacts to the destination.

class isaaclab_contrib.coupling.CouplerProxyCfg

Bases: CouplerCfg

Configuration for Newton’s lagged-impulse virtual-proxy coupling.

Newton’s proxy coupler currently supports at most two solver entries.

Attributes:

class_type	Solver class whose class methods build and drive Newton's solver, e.g. class_type.build(cfg, model, mode).
solver_type	Solver type metadata (deprecated).
entries	Ordered named sub-solver entries and their ownership selectors.
outer_contact_entry	Entry whose shape pairs the outer collision pipeline collides, or None for the whole model.
proxies	Directed proxy mappings between named solver entries.
iterations	Number of proxy relaxation passes per coupled step.

class_type: type | str

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

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.

entries: list[CouplerEntryCfg]

Ordered named sub-solver entries and their ownership selectors.

outer_contact_entry: str | None

Entry whose shape pairs the outer collision pipeline collides, or None for the whole model.

Restricting outer contacts to one entry lets another entry, e.g. a cable, run its own post-transfer pipeline.

proxies: list[CouplerProxyMappingCfg]

Directed proxy mappings between named solver entries.

iterations: int

Number of proxy relaxation passes per coupled step.

class isaaclab_contrib.coupling.CouplerAdmmCfg

Bases: CouplerCfg

Configuration for Newton’s linearized ADMM coupling.

Attributes:

class_type	Solver class whose class methods build and drive Newton's solver, e.g. class_type.build(cfg, model, mode).
solver_type	Solver type metadata (deprecated).
entries	Ordered named sub-solver entries and their ownership selectors.
outer_contact_entry	Entry whose shape pairs the outer collision pipeline collides, or None for the whole model.
contact_max_triangle_pairs	Internal ADMM triangle-pair capacity across all environments in one process.
contact_reduction_hashtable_size_factor	Contact-reduction hash table size relative to the internal triangle-pair capacity.
contact_pairs	Symmetric contact interfaces as (entry_name, entry_name) pairs.
iterations	Number of ADMM dual iterations per coupled step.
rho	ADMM penalty parameter [dimensionless].
gamma	Proximal mass scaling parameter [dimensionless].
baumgarte	Position-error correction fraction [dimensionless].
joint_stiffness	Translational cross-solver joint stiffness [N/m].
joint_damping	Translational cross-solver joint damping [N*s/m].
joint_angular_stiffness	Angular cross-solver joint stiffness [N*m/rad].
joint_angular_damping	Angular cross-solver joint damping [N*m*s/rad].
joint_proximal_bodies	Whether cross-solver joint neighbors remain visible as inertial proxies.
joint_proximal_destination_entries	Optional entries that receive cross-solver joint proximal bodies.
joint_proximal_mass_scale	Mass scale applied to cross-solver joint proximal bodies.
rigid_contact_matching	Frame-to-frame matching mode for collision-detected rigid contacts.
contact_matching_pos_threshold	Maximum midpoint distance for matching rigid contacts [m].
contact_matching_normal_dot_threshold	Minimum normal dot product for matching rigid contacts.
contact_matching_force_scale	Scale applied to the previous ADMM dual when a rigid contact matches.

class_type: type | str

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

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.

entries: list[CouplerEntryCfg]

Ordered named sub-solver entries and their ownership selectors.

outer_contact_entry: str | None

Entry whose shape pairs the outer collision pipeline collides, or None for the whole model.

Restricting outer contacts to one entry lets another entry, e.g. a cable, run its own post-transfer pipeline.

contact_max_triangle_pairs: int | None

Internal ADMM triangle-pair capacity across all environments in one process.

None uses Newton’s default. Must be less than 2**20 with rigid_contact_matching set to "latest" or "sticky"; larger capacities require "disabled".

contact_reduction_hashtable_size_factor: float | None

Contact-reduction hash table size relative to the internal triangle-pair capacity.

None uses Newton’s default. Increase it for hash table fill or insertion warnings.

contact_pairs: list[tuple[str, str]] | None

Symmetric contact interfaces as (entry_name, entry_name) pairs.

None asks Newton to detect every distinct entry pair automatically. An empty list disables ADMM contact coupling.

iterations: int

Number of ADMM dual iterations per coupled step.

rho: float

ADMM penalty parameter [dimensionless].

gamma: float

Proximal mass scaling parameter [dimensionless].

baumgarte: float

Position-error correction fraction [dimensionless].

joint_stiffness: float

Translational cross-solver joint stiffness [N/m].

joint_damping: float

Translational cross-solver joint damping [N*s/m].

joint_angular_stiffness: float

Angular cross-solver joint stiffness [N*m/rad].

joint_angular_damping: float

Angular cross-solver joint damping [N*m*s/rad].

joint_proximal_bodies: bool

Whether cross-solver joint neighbors remain visible as inertial proxies.

joint_proximal_destination_entries: list[str] | None

Optional entries that receive cross-solver joint proximal bodies.

joint_proximal_mass_scale: float

Mass scale applied to cross-solver joint proximal bodies.

rigid_contact_matching: Literal['disabled', 'latest', 'sticky']

Frame-to-frame matching mode for collision-detected rigid contacts.

contact_matching_pos_threshold: float | None

Maximum midpoint distance for matching rigid contacts [m].

contact_matching_normal_dot_threshold: float | None

Minimum normal dot product for matching rigid contacts.

contact_matching_force_scale: float

Scale applied to the previous ADMM dual when a rigid contact matches.

Coupler Solver

class isaaclab_contrib.coupling.CouplerSolver

Bases: NewtonSolver

Couple named entries, each built from its own solver configuration on its model view.

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 shared builder once per distinct entry solver class.
build(cfg, model, mode[, env_template])	Resolve entry ownership, build each entry's solver on its model view, and couple the entries.
build_coupled(cfg, model, entries, proxies, mode)	Construct Newton's coupled solver from the built entries; tasks with a custom coupled solver override it.
supports_capture(cfg, solver)	Whether the solver can be recorded into a CUDA graph.
uses_collision_pipeline(cfg, solver)	Whether an entry that collides outside its proxies expects contacts from Newton's collision pipeline.
create_collision_pipeline(cfg, solver, **kwargs)	Collide the whole model, or only outer_contact_entry's shape pairs.
reset(cfg, solver, state, world_mask)	Reset every entry for masked worlds, promoting a selected single MPM world to the full-reset path.
check_step(cfg, solver, captured, debug)	Raise asynchronous failures, and log diagnostics, of every entry's solver.

contact_sensors: ClassVar[bool] = False

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

classmethod solver_classes(cfg: CouplerCfg) → tuple[type[newton.solvers.SolverBase], ...]

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

classmethod prepare_builder(cfg: CouplerCfg, builder: newton.ModelBuilder) → None

Prepare the shared builder once per distinct entry solver class.

classmethod build(cfg: CouplerCfg, model: newton.Model, mode: DeterministicMode, env_template: str | None = None) → newton.solvers.experimental.coupled.SolverCoupled

Resolve entry ownership, build each entry’s solver on its model view, and couple the entries.

{ENV_REGEX_NS} in entry and proxy body selectors and shape patterns expands against env_template; the configuration stays unchanged.

classmethod build_coupled(cfg: CouplerCfg, model: newton.Model, entries: list[newton.solvers.experimental.coupled.SolverCoupled.Entry], proxies: list[CouplerProxyMappingCfg], mode: DeterministicMode) → newton.solvers.experimental.coupled.SolverCoupled

Construct Newton’s coupled solver from the built entries; tasks with a custom coupled solver override it.

A proxy configuration without proxies steps its entries independently: Newton’s proxy solver advances only connected proxy groups.

classmethod supports_capture(cfg: CouplerCfg, solver: newton.solvers.experimental.coupled.SolverCoupled) → bool

Whether the solver can be recorded into a CUDA graph.

classmethod uses_collision_pipeline(cfg: CouplerCfg, solver: newton.solvers.experimental.coupled.SolverCoupled) → bool

Whether an entry that collides outside its proxies expects contacts from Newton’s collision pipeline.

classmethod create_collision_pipeline(cfg: CouplerCfg, solver: newton.solvers.experimental.coupled.SolverCoupled, **kwargs) → newton.CollisionPipeline

Collide the whole model, or only outer_contact_entry’s shape pairs.

classmethod reset(cfg: CouplerCfg, solver: newton.solvers.experimental.coupled.SolverCoupled, state: newton.State, world_mask: array) → None

Reset every entry for masked worlds, promoting a selected single MPM world to the full-reset path.

classmethod check_step(cfg: CouplerCfg, solver: newton.solvers.experimental.coupled.SolverCoupled, captured: bool, debug: bool) → None

Raise asynchronous failures, and log diagnostics, of every entry’s solver.