isaaclab_newton.physics

Implementation backends for simulation interfaces.

Classes

NewtonManager	Newton physics manager for Isaac Lab.
NewtonBackend	Everything bound to one finalized Newton model, and the operations that initialize, step and query it.
NewtonCloneRecord	Native replication outputs, kept across hard resets.
MjWarpActuatorBridge	Per-step MuJoCo Warp DOF channel for one Newton actuator.
NewtonCfg	Configuration for Newton physics manager.
NewtonBackendCfg	Allocate model and state from the matching builder; closing them leaves the builder intact.
NewtonBuilderCfg	Share mutable construction data, populated before model allocation and retained across hard resets.
NewtonSoftContactCfg	Global soft-contact parameters applied to the finalized Newton model.
NewtonCollisionPipelineCfg	Configuration for Newton collision pipeline.
NewtonShapeCfg	Default per-shape collision properties applied to all shapes in a Newton scene.
NewtonSolver	How Isaac Lab builds and drives a Newton solver.
MJWarpSolver	Newton's MuJoCo Warp solver, which steps in place on one state.
VBDSolver	Newton's Vertex Block Descent solver.
XPBDSolver	Newton's XPBD solver, which double-buffers state.
FeatherstoneSolver	Newton's Featherstone solver, which double-buffers state.
KaminoSolver	Newton's Kamino solver, which resets its internals through forward kinematics.
MPMSolver	Newton's implicit MPM solver, which steps particle materials in place on one state.
NewtonSolverCfg	Configuration of a Newton solver.
MJWarpSolverCfg	Configuration for MuJoCo Warp solver-related parameters.
VBDSolverCfg	Configuration for the Vertex Block Descent solver.
XPBDSolverCfg	An implicit integrator using eXtended Position-Based Dynamics (XPBD) for rigid and soft body simulation.
FeatherstoneSolverCfg	A semi-implicit integrator using symplectic Euler.
KaminoCollisionDetectorCfg	Internal Kamino collision-detector parameters.
KaminoConstraintsCfg	Global constraint stabilization parameters for Kamino.
KaminoDVICfg	DVI forward-dynamics solver parameters for Kamino.
KaminoDVISolverCfg	Configuration for Kamino with the DVI forward-dynamics solver.
KaminoDynamicsCfg	Constrained forward-dynamics problem parameters for Kamino.
KaminoFKCfg	Forward-kinematics reset solver parameters for Kamino.
KaminoMaterialsCfg	Material mixing parameters for Kamino contacts.
KaminoPADMMCfg	P-ADMM forward-dynamics solver parameters for Kamino.
KaminoPADMMSolverCfg	Configuration for Kamino with the P-ADMM forward-dynamics solver.
MPMSolverCfg	Configuration for Newton's implicit Material Point Method (MPM) solver.
HydroelasticSDFCfg	Configuration for SDF-based hydroelastic collision handling.

Physics Manager

class isaaclab_newton.physics.NewtonManager

Bases: PhysicsManager

Newton physics manager for Isaac Lab.

Runs one NewtonBackend through the physics lifecycle and keeps what survives hard resets: the builder, site requests, replication outputs and decimation.

Lifecycle: initialize() -> reset() -> step() (repeated) -> close().

Attributes:

backend_name	Backend implementation key used by asset and sensor factories.
builder	Shared construction builder, acquired at initialize() and kept across hard resets.
backend	Data bound to the finalized model; replaced on every hard reset.
shares_materials	Whether contacts read one material table shared by all environments instead of per-shape values.
supports_anim_recording	Whether this backend can service --anim_recording_enabled (OVD Recorder).
views	Backend views by prim path expression, shared by the consumers of this manager.

Methods:

__init__(cfg)	Store the physics configuration this manager runs.
setup_deformable_body(prim, deformable_type, ...)	Apply Newton's token deformable anchor schemas and sync the visual mesh geometry.
initialize(sim_context)	Initialize the manager with simulation context.
reset([soft])	Reset physics simulation.
forward()	Update articulation kinematics without stepping physics; see NewtonBackend.forward().
video_capture_backend()	Newton GL headless perspective video capture.
step()	Advance physics by one environment step, or one physics step when the environment runs decimation.
close()	Clean up Newton physics resources.
get_scene_data_backend()	Return the SceneDataBackend for the SceneDataProvider.
register_callback(callback, event[, order, ...])	Register a callback.
get_physics_sim_view()	Return the registered articulation views.
is_fabric_enabled()	Check if fabric interface is enabled (not applicable for Newton).
clear()	Clear all Newton-specific state (callbacks cleared by super().close()).
register_site(body_pattern, xform, *[, ...])	Request a site for injection into prototypes before replication.
inject_sites(main_builder, source_builders)	Add unresolved sites to source builders, or to the main builder for global and shared-asset sites.
record_clone(record, site_index_map)	Record native replication outputs for model finalization and consumers.
get_site_index_map()	Return resolved sites by label.
get_world_xforms()	Return the root transform of each cloned world, or None without replication.
get_clone_source_builders()	Return per-source builders retained from replication, keyed by clone-plan source path.
request_extended_state_attribute(attr)	Request an extended state attribute (e.g. "body_qdd") from the builder before finalization.
request_extended_contact_attribute(attr)	Request an extended contact attribute (e.g. "force") from the builder before finalization.
add_model_change(change)	Register a model change to notify the solver at the next step.
invalidate_fk([env_mask, articulation_ids, ...])	Publish an authored-state change and schedule FK; see NewtonBackend.invalidate_fk().
invalidate_body_state([env_mask, consume_mask])	Publish directly authored body state; see NewtonBackend.invalidate_body_state().
start_simulation()	Start simulation by finalizing model and initializing state.
instantiate_builder_from_stage()	Import the explicitly declared clone plan into the Newton builder.
initialize_solver()	Build the solver, its contacts and the initial body state; see NewtonBackend.init_solver().
create_visual_material_writer(batches)	Compile material-to-shape addresses for the active Newton model.
create_visual_shape_color_writer(asset, ...)	Compile selected articulation-body shape addresses for the active Newton model.
get_scene_data_provider()	Return the active scene data provider.
activate_newton_actuator_path()	Run the model's Newton actuators inside the step; see NewtonBackend.activate_actuators().
register_solver_init_callback(callback)	Append a one-shot hook invoked once the solver exists, before the initial FK and any CUDA graph capture.
register_pre_actuator_callback(callback)	Append a hook invoked before the Newton actuators of every physics step.
register_post_actuator_callback(callback)	Append a hook invoked after the Newton actuators of every physics step.
register_state_force_callback(callback)	Register a graph-safe callback that applies forces before every solver substep.
register_post_step_callback(callback)	Append a hook invoked once per step(), after the last solver substep and before sensors update.
unregister_post_step_callback(callback)	Remove a post-step callback; removing an absent callback is a no-op.
set_decimation(decimation)	Set the decimation count; see NewtonBackend.set_decimation().
handles_decimation()	Whether step() executes the full decimation loop; see NewtonBackend.handles_decimation().
add_contact_sensor([body_names_expr, ...])	Add a contact sensor between bodies or shapes; see NewtonBackend.add_contact_sensor().
after_visualizers_render()	Hook after visualizers have stepped during render().
clear_callbacks()	Remove all registered callbacks.
deregister_callback(callback_id)	Remove a registered callback.
dispatch_event(event[, payload])	Dispatch an event to all registered callbacks.
fix_articulation_root(articulation_prim[, stage])	Ensure that an articulation root has one enabled world fixed joint.
get_backend()	Get the tensor backend being used ("numpy" or "torch").
get_device()	Get the physics simulation device.
get_physics_dt()	Get the physics timestep in seconds.
get_simulation_time()	Get the current simulation time in seconds.
pause()	Pause physics simulation.
play()	Start or resume physics simulation.
pre_render()	Sync deferred physics state to the rendering backend.
safe_callback_invoke(fn, *args[, ...])	Invoke a callback, catching exceptions that would be swallowed by external event buses.
stop()	Stop physics simulation.
wait_for_playing()	Block until the timeline is playing.
add_imu_sensor(sites)	Add an IMU sensor at sites; see NewtonBackend.add_imu_sensor().

backend_name: ClassVar[str] = 'newton'

Backend implementation key used by asset and sensor factories.

__init__(cfg: NewtonCfg)

Store the physics configuration this manager runs.

Parameters:

cfg – Physics configuration whose class_type selected this manager.

builder: ModelBuilder | None

Shared construction builder, acquired at initialize() and kept across hard resets.

backend: NewtonBackend | None

Data bound to the finalized model; replaced on every hard reset.

property shares_materials: bool

Whether contacts read one material table shared by all environments instead of per-shape values.

classmethod setup_deformable_body(prim: Any, deformable_type: str, sim_mesh_prim: Any, vis_mesh_prim: Any) → None

Apply Newton’s token deformable anchor schemas and sync the visual mesh geometry.

initialize(sim_context: SimulationContext) → None

Initialize the manager with simulation context.

Parameters:

sim_context – Parent simulation context.

reset(soft: bool = False) → None

Reset physics simulation.

A hard reset (soft=False) closes the backend, with its solver, contacts, step callbacks and captured graph, and finalizes a new one. Consumers bind to it again on PHYSICS_READY; reacquire asset.data and its arrays afterwards. A soft reset keeps the backend.

Parameters:

soft – If True, skip full reinitialization.

forward() → None

Update articulation kinematics without stepping physics; see NewtonBackend.forward().

video_capture_backend() → str

Newton GL headless perspective video capture.

step() → None

Advance physics by one environment step, or one physics step when the environment runs decimation.

close() → None

Clean up Newton physics resources.

get_scene_data_backend() → SceneDataBackend | None

Return the SceneDataBackend for the SceneDataProvider.

register_callback(callback: Callable, event: PhysicsEvent, order: int = 0, name: str | None = None, wrap_weak_ref: bool = True) → CallbackHandle

Register a callback. Passes event to parent class.

get_physics_sim_view() → list

Return the registered articulation views.

is_fabric_enabled() → bool

Check if fabric interface is enabled (not applicable for Newton).

clear()

Clear all Newton-specific state (callbacks cleared by super().close()).

register_site(body_pattern: str | None, xform: transformf, *, per_world: bool = False) → str

Request a site for injection into prototypes before replication.

Sensors call this during __init__. Identical (body_pattern, per_world, transform) requests share a site, and requests persist until close(), so sites survive hard resets without being requested again. The pattern matches prototype-local body labels (e.g. "Robot/finger.*") during replication, and wildcard patterns create one site per matched body.

Parameters:

• body_pattern – Regex matched against body labels, or None for a global site.

• xform – Site transform relative to the body.

• per_world – Create one bodyless site in each cloned world’s frame. Requires body_pattern=None.

Returns:

The assigned site label.

inject_sites(main_builder: newton.ModelBuilder, source_builders: dict[str, newton.ModelBuilder]) → tuple[dict[str, int], dict[int, dict[str, list[int]]], dict[str, transformf]]

Add unresolved sites to source builders, or to the main builder for global and shared-asset sites.

Parameters:

• main_builder – Top-level builder that receives global sites.

• source_builders – Source builders by source path.

Returns:

global site shape indices by label, builder-local site indices by id(builder) and label, and world-root site transforms by label.

Return type:

(global_site_indices, source_site_indices, env_root_sites)

record_clone(record: NewtonCloneRecord, site_index_map: dict[str, tuple[int, None] | tuple[None, list[list[int]]]]) → None

Record native replication outputs for model finalization and consumers.

Parameters:

• record – Replication outputs.

• site_index_map – Sites resolved during replication, by label.

get_site_index_map() → dict[str, tuple[int, None] | tuple[None, list[list[int]]]]

Return resolved sites by label.

get_world_xforms() → list[transformf] | None

Return the root transform of each cloned world, or None without replication.

get_clone_source_builders() → dict[str, newton.ModelBuilder]

Return per-source builders retained from replication, keyed by clone-plan source path.

request_extended_state_attribute(attr: str) → None

Request an extended state attribute (e.g. "body_qdd") from the builder before finalization.

Parameters:

attr – State attribute name (must be in State.EXTENDED_ATTRIBUTES).

request_extended_contact_attribute(attr: str) → None

Request an extended contact attribute (e.g. "force") from the builder before finalization.

Parameters:

attr – Contact attribute name.

add_model_change(change: newton.ModelFlags) → None

Register a model change to notify the solver at the next step.

invalidate_fk(env_mask: array | None = None, articulation_ids: array | None = None, *, articulation_mask: array | None = None, consume_mask: bool = False) → None

Publish an authored-state change and schedule FK; see NewtonBackend.invalidate_fk().

Asset writers invalidate their own caches separately. Pending work is consumed at the next forward, raw-state, rendering, or physics-step boundary.

invalidate_body_state(env_mask: array | None = None, *, consume_mask: bool = False) → None

Publish directly authored body state; see NewtonBackend.invalidate_body_state().

start_simulation() → None

Start simulation by finalizing model and initializing state.

This function finalizes the model and initializes the simulation state. Note: Collision pipeline is initialized later in initialize_solver() after we determine whether the solver needs external collision detection.

instantiate_builder_from_stage()

Import the explicitly declared clone plan into the Newton builder.

initialize_solver() → None

Build the solver, its contacts and the initial body state; see NewtonBackend.init_solver().

create_visual_material_writer(batches: tuple[VisualMaterialBatch, ...]) → VisualMaterialWriter

Compile material-to-shape addresses for the active Newton model.

create_visual_shape_color_writer(asset: BaseArticulation, body_names: tuple[str, ...]) → VisualShapeColorWriter

Compile selected articulation-body shape addresses for the active Newton model.

get_scene_data_provider() → SceneDataProvider

Return the active scene data provider.

activate_newton_actuator_path() → None

Run the model’s Newton actuators inside the step; see NewtonBackend.activate_actuators().

register_solver_init_callback(callback: Callable[[], None]) → None

Append a one-shot hook invoked once the solver exists, before the initial FK and any CUDA graph capture.

register_pre_actuator_callback(callback: Callable[[], None]) → None

Append a hook invoked before the Newton actuators of every physics step.

Each callback is recorded into the captured step, so it must be graph-safe. Hard resets discard these hooks; register them again when the new model is ready.

register_post_actuator_callback(callback: Callable[[], None]) → None

Append a hook invoked after the Newton actuators of every physics step.

Each callback is recorded into the captured step right after the Newton actuators and before the solver substeps, so its writes to state/control are visible to the integrator on the same iteration. Callbacks fire in registration order. Hard resets discard these hooks; register them again when the new model is ready.

register_state_force_callback(callback: Callable[[newton.State], None]) → None

Register a graph-safe callback that applies forces before every solver substep.

Hard resets discard these hooks; register them again when the new model is ready.

Parameters:

callback – Function that adds forces [N, N·m] to the provided state.

register_post_step_callback(callback: Callable[[], None]) → None

Append a hook invoked once per step(), after the last solver substep and before sensors update.

The hook reflects the state after all decimation iterations of the step. Callbacks must be graph-safe (fixed shapes, no host branching on device data) because they are recorded into the captured step. Hard resets discard these hooks; register them again when the new model is ready.

unregister_post_step_callback(callback: Callable[[], None]) → None

Remove a post-step callback; removing an absent callback is a no-op.

set_decimation(decimation: int) → None

Set the decimation count; see NewtonBackend.set_decimation().

Once Newton actuators run in the step, one step() advances the whole decimation loop.

handles_decimation() → bool

Whether step() executes the full decimation loop; see NewtonBackend.handles_decimation().

add_contact_sensor(body_names_expr: str | list[str] | None = None, shape_names_expr: str | list[str] | None = None, contact_partners_body_expr: str | list[str] | None = None, contact_partners_shape_expr: str | list[str] | None = None, verbose: bool = False) → newton.sensors.SensorContact

Add a contact sensor between bodies or shapes; see NewtonBackend.add_contact_sensor().

after_visualizers_render() → None

Hook after visualizers have stepped during render().

Use for physics-backend sync (e.g. fabric) if needed. Default is a no-op.

clear_callbacks() → None

Remove all registered callbacks.

IDs remain unique for this manager’s lifetime. Otherwise a retained handle could deregister a new callback after a close and reinitialization of the same manager.

deregister_callback(callback_id: int | CallbackHandle) → None

Remove a registered callback.

Parameters:

callback_id – The ID or CallbackHandle returned by register_callback().

dispatch_event(event: PhysicsEvent, payload: Any = None) → None

Dispatch an event to all registered callbacks.

This is the default implementation using simple callback lists. Subclasses may override or extend with platform-specific dispatch.

Parameters:

• event – The event to dispatch.

• payload – Optional data to pass to callbacks.

classmethod fix_articulation_root(articulation_prim: Any, stage: Any = None) → Any

Ensure that an articulation root has one enabled world fixed joint.

An articulation rooted at a fixed joint that attaches it to the world, a layout that UsdPhysics allows, is fixed by that joint. The base implementation leaves the root in place. Backends whose parser requires a different root topology may relocate it and return the resulting root prim.

Parameters:

• articulation_prim – The articulation-root prim to fix.

• stage – The stage containing the prim. Defaults to the current stage.

Returns:

The articulation-root prim after backend normalization.

Raises:

NotImplementedError – If a new joint is needed and the root is not a rigid body.

get_backend() → str

Get the tensor backend being used (“numpy” or “torch”).

get_device() → str

Get the physics simulation device.

get_physics_dt() → float

Get the physics timestep in seconds.

get_simulation_time() → float

Get the current simulation time in seconds.

pause() → None

Pause physics simulation. Default is no-op.

play() → None

Start or resume physics simulation. Default is no-op.

pre_render() → None

Sync deferred physics state to the rendering backend.

Called by render() before cameras and visualizers read scene data. The default implementation is a no-op. Backends that defer transform writes (e.g. Newton’s dirty-flag pattern) should override this to flush pending updates.

static safe_callback_invoke(fn: Callable, *args, backend_manager: PhysicsManager | None = None, physics_manager: PhysicsManager | None = None) → None

Invoke a callback, catching exceptions that would be swallowed by external event buses.

Ignores ReferenceError (from garbage-collected weakref proxies). All other exceptions are forwarded to backend_manager.``store_callback_exception`` when available (see note below), or re-raised immediately otherwise.

Parameters:

• fn – Callback to invoke.

• *args – Positional arguments for fn.

• backend_manager – Manager that stores swallowed exceptions, if any.

• physics_manager – Deprecated alias of backend_manager.

Note (Octi):

The carb event bus used by PhysX/Omniverse silently swallows exceptions raised inside callbacks. PhysxManager works around this by storing the exception and re-raising it after event dispatch completes (in reset() / step()). Backends that dispatch events directly (e.g. Newton) don’t need this — exceptions propagate normally — so store_callback_exception is not called for them. This is a known wart; a cleaner solution is actively being explored.

stop() → None

Stop physics simulation. Default is no-op.

supports_anim_recording: ClassVar[bool] = False

Whether this backend can service --anim_recording_enabled (OVD Recorder).

Overridden by backends that implement the recorder (currently PhysX-only).

wait_for_playing() → None

Block until the timeline is playing. Default is no-op.

views: dict[str, Any]

Backend views by prim path expression, shared by the consumers of this manager.

add_imu_sensor(sites: list[int]) → newton.sensors.SensorIMU

Add an IMU sensor at sites; see NewtonBackend.add_imu_sensor().

isaaclab_newton.physics.create_builder(physics_cfg: NewtonCfg | None = None, up_axis: str | None = None, **kwargs) → newton.ModelBuilder

Create a ModelBuilder configured with Isaac Lab’s defaults.

Forwards NewtonShapeCfg defaults onto Newton’s upstream ModelBuilder.default_shape_cfg via checked_apply(), and registers the custom attributes the configured solver reads. Without a Newton configuration the default shape settings still apply, so rough-terrain margin and gap hold during early construction.

Parameters:

• physics_cfg – Newton physics configuration; None uses the default shape settings and no solver attributes.

• up_axis – Override for the up-axis. Defaults to "Z".

• **kwargs – Forwarded to ModelBuilder.

Returns:

New builder with up-axis and per-shape defaults (gap, margin) applied.

class isaaclab_newton.physics.NewtonBackend

Everything bound to one finalized Newton model, and the operations that initialize, step and query it.

A render-only backend (non-Newton physics) holds only the model and state_0.

Attributes:

model	Finalized Newton model; model.num_envs is its world count.
state_version	Advanced whenever the step or FK changes the state; asset data recomputes derived values cached before it.
particle_ranges	(start, count) particle range per replicated deformable prim path.
deformable_ranges	(start, count, kind) particle range per deformable label; kind is "surface" or "volume".
state_0	Current state; the solver reads it and, for double-buffered solvers, writes state_1.
geometry_offsets	First particle index per deformable label on a render-only backend; empty on a simulation backend.
bvh_refit	Timestamp of the last BVH refit, shared by ray casters and cameras.
cfg	Newton physics settings, or None for a render-only backend.
dt	Duration of one physics step [s].
num_substeps	Solver substeps per physics step.
solver_dt	Duration of one solver substep [s].
deterministic_mode	Warp determinism mode of the solver and collision pipeline.
state_1	Next state written by the solver.
control	Joint targets and applied forces read by the solver.
solver	Newton solver, built by init_solver().
solver_ops	Isaac Lab driver of solver, built from NewtonCfg.solver_cfg by init_solver().
collision_pipeline	Collision pipeline, or None when the solver collides internally.
contacts	Contacts produced by the collision pipeline or the solver.
contact_observables	Solver-owned contact forces when registered sensors require them.
staged_body_f	Body forces [N, N·m] written before the step, re-applied before every substep.
world_mask	Worlds to reset; the final slot is Newton's global world, which Isaac Lab never resets.
fk_mask	Articulations whose forward kinematics must be evaluated.
kinematics_dirty	Whether joint coordinates changed since the last forward kinematics.
transforms_may_change_on_graph_replay	Whether state was written inside an outer CUDA graph capture; forward() then always runs.
model_changes	Model-property categories to notify the solver of at the next step.
warned_model_changes	Ignored model-property categories already warned about.
contact_sensors	Newton contact sensors keyed by their request.
imu_sensors	Newton IMU sensors, updated after each physics step.
actuators	Newton actuators run inside the step, or None.
actuators_active	Whether an articulation runs its Newton actuators in the step (activate_actuators()).
pre_actuator_callbacks	Run before the Newton actuators of every physics step.
post_actuator_callbacks	Run after the Newton actuators of every physics step, before its solver substeps.
state_force_callbacks	Add forces [N, N·m] to the input state of every solver substep.
post_step_callbacks	Run once after the last solver substep of a step().
solver_init_callbacks	Run once by init_solver(), after the solver exists and before the initial FK.
decimation	Physics steps per environment step.
capture	Records the step as a CUDA graph, or None when the step runs eagerly; set by init_solver().
graphs	Captured parts of the step, keyed by part; empty until the first step is captured.

Methods:

create_visual_material_writer(batches)	Bind material writes to this resource's native shape-color buffer.
close()	Drop native handles after consumers release their bindings.
init_solver([env_template, relaxed_capture])	Build the solver and its contacts, run the solver-init callbacks, and evaluate the initial FK.
invalidate_fk([env_mask, articulation_ids, ...])	Schedule solver reset and FK for the masked worlds and articulations.
invalidate_body_state([env_mask, consume_mask])	Schedule solver reset for directly authored body state, without requesting FK.
forward()	Reset solver internals and evaluate FK for the flagged worlds and articulations, then clear the flags.
notify_model_changes()	Notify the solver of the queued model-property changes once, combining their categories.
activate_actuators()	Run the model's Newton actuators inside the step.
add_contact_sensor([body_names_expr, ...])	Add a contact sensor between bodies or shapes; identical requests share one sensor.
add_imu_sensor(sites)	Add an IMU sensor at sites; the body_qdd state attribute must be requested before finalization.
handles_decimation()	Whether one step() runs the whole decimation loop: once an articulation runs Newton actuators in it.
set_decimation(decimation)	Set the physics steps per environment step.
invalidate_graph()	Drop the captured step; with capture enabled, the next step runs eagerly and is captured again.
step()	Advance one physics step, or the whole decimation loop when handles_decimation().
state_pointers()	Addresses of state_0's body and particle arrays, 0 for an absent array.
refit_bvh(timestamp, *[, use_cuda_graph])	Refit the model's shape and particle BVHs to state_0 once per state timestamp.

model

Finalized Newton model; model.num_envs is its world count.

state_version

Advanced whenever the step or FK changes the state; asset data recomputes derived values cached before it.

particle_ranges: dict[str, tuple[int, int]]

(start, count) particle range per replicated deformable prim path.

deformable_ranges

(start, count, kind) particle range per deformable label; kind is "surface" or "volume".

state_0: State

Current state; the solver reads it and, for double-buffered solvers, writes state_1.

geometry_offsets

First particle index per deformable label on a render-only backend; empty on a simulation backend.

bvh_refit

Timestamp of the last BVH refit, shared by ray casters and cameras.

cfg: NewtonCfg | None

Newton physics settings, or None for a render-only backend.

dt

Duration of one physics step [s].

num_substeps

Solver substeps per physics step.

solver_dt

Duration of one solver substep [s].

deterministic_mode

Warp determinism mode of the solver and collision pipeline.

state_1: State

Next state written by the solver.

control

Joint targets and applied forces read by the solver.

solver: SolverBase | None

Newton solver, built by init_solver().

solver_ops: NewtonSolver | None

Isaac Lab driver of solver, built from NewtonCfg.solver_cfg by init_solver().

collision_pipeline: CollisionPipeline | None

Collision pipeline, or None when the solver collides internally.

contacts: Contacts | None

Contacts produced by the collision pipeline or the solver.

contact_observables: SolverBase.Observables | None

Solver-owned contact forces when registered sensors require them.

staged_body_f: wp.array | None

Body forces [N, N·m] written before the step, re-applied before every substep.

world_mask

Worlds to reset; the final slot is Newton’s global world, which Isaac Lab never resets.

fk_mask

Articulations whose forward kinematics must be evaluated.

kinematics_dirty

Whether joint coordinates changed since the last forward kinematics.

transforms_may_change_on_graph_replay

Whether state was written inside an outer CUDA graph capture; forward() then always runs.

model_changes: set[int]

Model-property categories to notify the solver of at the next step.

warned_model_changes: set[int]

Ignored model-property categories already warned about.

contact_sensors: dict[tuple, SensorContact]

Newton contact sensors keyed by their request.

imu_sensors: list[SensorIMU]

Newton IMU sensors, updated after each physics step.

actuators: NewtonActuatorAdapter | None

Newton actuators run inside the step, or None.

actuators_active

Whether an articulation runs its Newton actuators in the step (activate_actuators()).

pre_actuator_callbacks: list[Callable[[], None]]

Run before the Newton actuators of every physics step.

post_actuator_callbacks: list[Callable[[], None]]

Run after the Newton actuators of every physics step, before its solver substeps.

state_force_callbacks: list[Callable[[State], None]]

Add forces [N, N·m] to the input state of every solver substep.

post_step_callbacks: list[Callable[[], None]]

Run once after the last solver substep of a step().

solver_init_callbacks: list[Callable[[], None]]

Run once by init_solver(), after the solver exists and before the initial FK.

decimation

Physics steps per environment step.

capture: Callable[[Callable[[], None]], wp.Graph] | None

Records the step as a CUDA graph, or None when the step runs eagerly; set by init_solver().

graphs: dict[str | tuple[str, int], wp.Graph]

Captured parts of the step, keyed by part; empty until the first step is captured.

create_visual_material_writer(batches: tuple[VisualMaterialBatch, ...]) → VisualMaterialWriter

Bind material writes to this resource’s native shape-color buffer.

close() → None

Drop native handles after consumers release their bindings.

init_solver(env_template: str | None = None, *, relaxed_capture: Callable[[], bool] | None = None) → None

Build the solver and its contacts, run the solver-init callbacks, and evaluate the initial FK.

Parameters:

• env_template – Environment prim path template that expands {ENV_REGEX_NS} in solver selectors.

• relaxed_capture – Returns, when the step is captured, whether to capture in relaxed mode; see capture_graph(). Defaults to strict capture.

invalidate_fk(env_mask: array | None = None, articulation_ids: array | None = None, *, articulation_mask: array | None = None, consume_mask: bool = False) → None

Schedule solver reset and FK for the masked worlds and articulations.

Parameters:

• env_mask – Mask over envs, which map to worlds through the model’s articulation-to-world table.

• articulation_ids – Model articulation index of each (env, view-local articulation), from ArticulationView.articulation_ids. With either argument None, every world and articulation is flagged, as for native state writes.

• articulation_mask – View-local articulations to flag. None selects every articulation of the view.

• consume_mask – Clear the flagged env_mask entries after reading them. Caller masks are otherwise unchanged.

invalidate_body_state(env_mask: array | None = None, *, consume_mask: bool = False) → None

Schedule solver reset for directly authored body state, without requesting FK.

Parameters:

• env_mask – Environments to flag, shaped (world_count,). None selects every world.

• consume_mask – Clear the flagged env_mask entries after reading them.

forward() → None

Reset solver internals and evaluate FK for the flagged worlds and articulations, then clear the flags.

notify_model_changes() → None

Notify the solver of the queued model-property changes once, combining their categories.

Inside an enclosing CUDA graph capture, the refresh is recorded and runs on every replay.

activate_actuators() → None

Run the model’s Newton actuators inside the step. Idempotent.

add_contact_sensor(body_names_expr: str | list[str] | None = None, shape_names_expr: str | list[str] | None = None, contact_partners_body_expr: str | list[str] | None = None, contact_partners_shape_expr: str | list[str] | None = None, verbose: bool = False) → newton.sensors.SensorContact

Add a contact sensor between bodies or shapes; identical requests share one sensor.

Parameters:

• body_names_expr – Expression for body names to sense.

• shape_names_expr – Expression for shape names to sense.

• contact_partners_body_expr – Expression for contact partner body names.

• contact_partners_shape_expr – Expression for contact partner shape names.

• verbose – Print verbose information.

Returns:

The Newton contact sensor, updated at the end of every step.

add_imu_sensor(sites: list[int]) → newton.sensors.SensorIMU

Add an IMU sensor at sites; the body_qdd state attribute must be requested before finalization.

Parameters:

sites – Site index of each environment.

Returns:

The Newton sensor, updated at the end of every step.

handles_decimation() → bool

Whether one step() runs the whole decimation loop: once an articulation runs Newton actuators in it.

set_decimation(decimation: int) → None

Set the physics steps per environment step.

invalidate_graph() → None

Drop the captured step; with capture enabled, the next step runs eagerly and is captured again.

step() → bool

Advance one physics step, or the whole decimation loop when handles_decimation().

Each physics step runs _before_actuators(), the Newton actuators, then _after_actuators(), and the step ends with _finish_step(). With capture-safe actuators the whole loop replays from one CUDA graph; otherwise the actuators run eagerly between the captured _before_actuators() and _after_actuators() graphs. Each part runs eagerly the first time and is then captured. Inside an enclosing capture the step records into it instead. The solver then checks the step for asynchronous failures (NewtonSolver.check_step()).

Returns:

Whether the step replays captured graphs.

state_pointers() → tuple[int, int]

Addresses of state_0’s body and particle arrays, 0 for an absent array.

Captured queries read these arrays, so they are recaptured when an address changes.

refit_bvh(timestamp: int, *, use_cuda_graph: bool = True) → None

Refit the model’s shape and particle BVHs to state_0 once per state timestamp.

Parameters:

• timestamp – Monotonic version of the state, e.g. the sum of the scene-data transform and geometry timestamps.

• use_cuda_graph – Whether to replay the refit from a CUDA graph on CUDA devices.

class isaaclab_newton.physics.NewtonCloneRecord

Native replication outputs, kept across hard resets.

Attributes:

world_xforms	Root transform of each cloned world, or None without replication.
source_builders	Per-source builders, keyed by clone-plan source path.
particle_ranges	(start, count) particle range per replicated deformable prim path.
cable_bindings	Body indices per replicated cable prim path.
geometry_batches	Shape batches the scene data backend publishes as geometry.

Methods:

__init__(world_xforms, source_builders, ...)

world_xforms: list[transformf] | None

Root transform of each cloned world, or None without replication.

source_builders: dict[str, newton.ModelBuilder]

Per-source builders, keyed by clone-plan source path.

particle_ranges: dict[str, tuple[int, int]]

(start, count) particle range per replicated deformable prim path.

cable_bindings: dict[str, list[int]]

Body indices per replicated cable prim path.

geometry_batches: list

Shape batches the scene data backend publishes as geometry.

__init__(world_xforms: list[transformf] | None, source_builders: dict[str, newton.ModelBuilder], particle_ranges: dict[str, tuple[int, int]], cable_bindings: dict[str, list[int]], geometry_batches: list) → None

Newton simulation data bound to one finalized model, and how it is stepped.

Functions:

capture_graph(device, fn, *[, relaxed])

Record fn into a CUDA graph without running it.

isaaclab_newton.physics.newton_backend.capture_graph(device: Device | str | None, fn: Callable[[], None], *, relaxed: bool = False) → Graph

Record fn into a CUDA graph without running it.

Parameters:

• device – CUDA device.

• fn – Work to record. Perform lazy initialization before capture.

• relaxed – Allow unrelated work on other threads, as required by Kit rendering.

Returns:

The captured graph, replayed with warp.capture_launch().

Solvers

class isaaclab_newton.physics.NewtonSolver

How Isaac Lab builds and drives a Newton solver.

A solver configuration selects the subclass through class_type, which builds Newton’s solver on construction and drives it afterwards. Classmethods run before the model exists and take only the configuration. The generic methods below follow Newton’s SolverBase API; a subclass overrides only where its solver differs.

Attributes:

solver_class	Newton solver class that build() constructs; None describes geometry only.
single_state	Whether the solver steps in place on one newton.State.
deterministic	Whether the solver can honor a Warp determinism guarantee.
contact_sensors	Whether the Newton solver can provide CONTACT_F observables to contact sensors.
ignored_model_changes	Model changes the solver does not apply after construction, mapped to the warning logged once.
cfg	Solver configuration.
native	Newton's solver.

Methods:

solver_classes(cfg)	Newton solvers whose custom builder attributes, and USD schemas, the builder needs before import.
prepare_builder(cfg, builder)	Normalize the complete builder before it is finalized.
applied_deterministic_mode(cfg, mode)	The Warp determinism mode the solver and collision pipeline run with for a requested mode.
shares_materials(cfg)	Whether contacts read one material table shared by all environments instead of per-shape values.
coupling_error(cfg, in_place)	Why the solver cannot run as a coupled-solver entry (stepping in place or not), or None.
__init__(cfg, model, mode[, env_template])	Build Newton's solver.
build(model, mode, env_template)	Construct Newton's solver from the configuration fields matching its constructor.
init_state(state)	Initialize solver-owned buffers of a double-buffered solver's output state.
applies_body_forces()	Whether the solver consumes applied rigid-body forces from newton.State.body_f.
supports_capture()	Whether the solver can be recorded into a CUDA graph.
uses_collision_pipeline()	Whether contacts come from Newton's CollisionPipeline instead of the solver.
create_collision_pipeline(**kwargs)	Construct the collision pipeline over the solver's model; kwargs are the pipeline arguments.
create_contacts()	Allocate the contacts a solver reports itself when it does not use the collision pipeline.
prepare_contacts(contacts, pipeline)	Bind newly allocated contacts to solver-owned buffers before CUDA graph capture.
pre_step(state)	Refresh solver structures once per physics step, before collision.
step(state_in, state_out, control, contacts, ...)	Advance one substep of dt [s].
post_step(state)	Publish derived state once per physics step, after the substeps.
reset(state, world_mask)	Clear solver-owned history for the worlds of a (world_count + 1,) mask, keeping authored joint state.
eval_fk(state, world_mask, fk_mask)	Update body state from the joint coordinates of the masked articulations; None selects everything.
check_step(captured, debug)	Raise asynchronous solver failures after a step launch (captured: a CUDA graph replay), and log diagnostics when debug is set.
fixed_tendon_control(cfg, articulation, model)	Build the fixed-tendon command adapter of an articulation, or None when no tendon is driven.

solver_class: ClassVar[type[newton.solvers.SolverBase] | None] = None

Newton solver class that build() constructs; None describes geometry only.

single_state: ClassVar[bool] = False

Whether the solver steps in place on one newton.State.

deterministic: ClassVar[bool] = False

Whether the solver can honor a Warp determinism guarantee.

contact_sensors: ClassVar[bool] = True

Whether the Newton solver can provide CONTACT_F observables to contact sensors.

ignored_model_changes: ClassVar[Mapping[newton.ModelFlags, str]] = {}

Model changes the solver does not apply after construction, mapped to the warning logged once.

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

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

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

Normalize the complete builder before it is finalized.

classmethod applied_deterministic_mode(cfg: NewtonSolverCfg, mode: wp.DeterministicMode) → wp.DeterministicMode

The Warp determinism mode the solver and collision pipeline run with for a requested mode.

classmethod shares_materials(cfg: NewtonSolverCfg) → bool

Whether contacts read one material table shared by all environments instead of per-shape values.

classmethod coupling_error(cfg: NewtonSolverCfg, in_place: bool) → str | None

Why the solver cannot run as a coupled-solver entry (stepping in place or not), or None.

__init__(cfg: NewtonSolverCfg, model: Model, mode: wp.DeterministicMode, env_template: str | None = None)

Build Newton’s solver.

Parameters:

• cfg – Solver configuration.

• model – Model, or coupled-entry model view, the solver advances.

• mode – Warp determinism mode.

• env_template – Environment path template of the clone plan, e.g. "/World/envs/env_{}".

cfg

Solver configuration.

native: newton.solvers.SolverBase

Newton’s solver.

build(model: newton.Model, mode: DeterministicMode, env_template: str | None) → newton.solvers.SolverBase

Construct Newton’s solver from the configuration fields matching its constructor.

init_state(state: newton.State) → None

Initialize solver-owned buffers of a double-buffered solver’s output state.

applies_body_forces() → bool

Whether the solver consumes applied rigid-body forces from newton.State.body_f.

supports_capture() → bool

Whether the solver can be recorded into a CUDA graph.

uses_collision_pipeline() → bool

Whether contacts come from Newton’s CollisionPipeline instead of the solver.

create_collision_pipeline(**kwargs) → newton.CollisionPipeline

Construct the collision pipeline over the solver’s model; kwargs are the pipeline arguments.

create_contacts() → Contacts | None

Allocate the contacts a solver reports itself when it does not use the collision pipeline.

prepare_contacts(contacts: Contacts, pipeline: CollisionPipeline | None) → None

Bind newly allocated contacts to solver-owned buffers before CUDA graph capture.

pre_step(state: newton.State) → None

Refresh solver structures once per physics step, before collision.

step(state_in: State, state_out: State, control: Control, contacts: Contacts | None, dt: float, *, observables: SolverBase.Observables | None = None) → None

Advance one substep of dt [s].

post_step(state: newton.State) → None

Publish derived state once per physics step, after the substeps.

reset(state: newton.State, world_mask: array) → None

Clear solver-owned history for the worlds of a (world_count + 1,) mask, keeping authored joint state.

eval_fk(state: newton.State, world_mask: array | None, fk_mask: array | None) → None

Update body state from the joint coordinates of the masked articulations; None selects everything.

check_step(captured: bool, debug: bool) → None

Raise asynchronous solver failures after a step launch (captured: a CUDA graph replay), and log diagnostics when debug is set.

classmethod fixed_tendon_control(cfg: NewtonSolverCfg, articulation: Any, model: Model) → Any

Build the fixed-tendon command adapter of an articulation, or None when no tendon is driven.

class isaaclab_newton.physics.MJWarpSolver

Bases: NewtonSolver

Newton’s MuJoCo Warp solver, which steps in place on one state.

Methods:

__new__(*args, **kwargs)
__init__(cfg, model, mode[, env_template])	Build Newton's solver.

classmethod __new__(*args, **kwargs)

__init__(cfg: NewtonSolverCfg, model: Model, mode: wp.DeterministicMode, env_template: str | None = None)

Build Newton’s solver.

Parameters:

• cfg – Solver configuration.

• model – Model, or coupled-entry model view, the solver advances.

• mode – Warp determinism mode.

• env_template – Environment path template of the clone plan, e.g. "/World/envs/env_{}".

class isaaclab_newton.physics.VBDSolver

Bases: NewtonSolver

Newton’s Vertex Block Descent solver.

Methods:

__new__(*args, **kwargs)
__init__(cfg, model, mode[, env_template])	Build Newton's solver.

classmethod __new__(*args, **kwargs)

__init__(cfg: NewtonSolverCfg, model: Model, mode: wp.DeterministicMode, env_template: str | None = None)

Build Newton’s solver.

Parameters:

• cfg – Solver configuration.

• model – Model, or coupled-entry model view, the solver advances.

• mode – Warp determinism mode.

• env_template – Environment path template of the clone plan, e.g. "/World/envs/env_{}".

class isaaclab_newton.physics.XPBDSolver

Bases: NewtonSolver

Newton’s XPBD solver, which double-buffers state.

Methods:

__new__(*args, **kwargs)
__init__(cfg, model, mode[, env_template])	Build Newton's solver.

classmethod __new__(*args, **kwargs)

__init__(cfg: NewtonSolverCfg, model: Model, mode: wp.DeterministicMode, env_template: str | None = None)

Build Newton’s solver.

Parameters:

• cfg – Solver configuration.

• model – Model, or coupled-entry model view, the solver advances.

• mode – Warp determinism mode.

• env_template – Environment path template of the clone plan, e.g. "/World/envs/env_{}".

class isaaclab_newton.physics.FeatherstoneSolver

Bases: NewtonSolver

Newton’s Featherstone solver, which double-buffers state.

Methods:

__new__(*args, **kwargs)
__init__(cfg, model, mode[, env_template])	Build Newton's solver.

classmethod __new__(*args, **kwargs)

__init__(cfg: NewtonSolverCfg, model: Model, mode: wp.DeterministicMode, env_template: str | None = None)

Build Newton’s solver.

Parameters:

• cfg – Solver configuration.

• model – Model, or coupled-entry model view, the solver advances.

• mode – Warp determinism mode.

• env_template – Environment path template of the clone plan, e.g. "/World/envs/env_{}".

class isaaclab_newton.physics.KaminoSolver

Bases: NewtonSolver

Newton’s Kamino solver, which resets its internals through forward kinematics.

Methods:

__new__(*args, **kwargs)
__init__(cfg, model, mode[, env_template])	Build Newton's solver.

classmethod __new__(*args, **kwargs)

__init__(cfg: NewtonSolverCfg, model: Model, mode: wp.DeterministicMode, env_template: str | None = None)

Build Newton’s solver.

Parameters:

• cfg – Solver configuration.

• model – Model, or coupled-entry model view, the solver advances.

• mode – Warp determinism mode.

• env_template – Environment path template of the clone plan, e.g. "/World/envs/env_{}".

class isaaclab_newton.physics.MPMSolver

Bases: NewtonSolver

Newton’s implicit MPM solver, which steps particle materials in place on one state.

Methods:

__new__(*args, **kwargs)
__init__(cfg, model, mode[, env_template])	Build Newton's solver.

classmethod __new__(*args, **kwargs)

__init__(cfg: NewtonSolverCfg, model: Model, mode: wp.DeterministicMode, env_template: str | None = None)

Build Newton’s solver.

Parameters:

• cfg – Solver configuration.

• model – Model, or coupled-entry model view, the solver advances.

• mode – Warp determinism mode.

• env_template – Environment path template of the clone plan, e.g. "/World/envs/env_{}".

Actuator Solver Access

class isaaclab_newton.physics.MjWarpActuatorBridge

Bases: object

Per-step MuJoCo Warp DOF channel for one Newton actuator.

Attributes:

STIFF_SOLREF_FRICTION	Stiff (-stiffness, -damping) friction solref from the reference BAM implementation [N.m/rad, N.m.s/rad].
STIFF_SOLIMP_FRICTION	Friction-constraint impedance profile paired with STIFF_SOLREF_FRICTION [-].

Methods:

is_available(solver)	Return whether solver steps MuJoCo Warp.
__init__(solver, model, dof_indices, device)	Bind the bridge to a MuJoCo Warp solver.
publish_dof_friction(friction_budget)	Write the actuator's dry-friction budget into dof_frictionloss for the next solve.
gather_external_torque(external_torque)	Fill external_torque with the previous solve's external load per slot.
stiffen_friction_constraint()	Stiffen the managed DOFs' friction constraint in MuJoCo Warp and in the Newton model.

STIFF_SOLREF_FRICTION: ClassVar[tuple[float, float]] = (-50000.0, -200.0)

Stiff (-stiffness, -damping) friction solref from the reference BAM implementation [N.m/rad, N.m.s/rad].

STIFF_SOLIMP_FRICTION: ClassVar[tuple[float, float, float, float, float]] = (0.99, 0.9999, 0.001, 0.5, 2.0)

Friction-constraint impedance profile paired with STIFF_SOLREF_FRICTION [-].

static is_available(solver: SolverBase | None) → bool

Return whether solver steps MuJoCo Warp.

CPU MuJoCo is unsupported: it still builds the MuJoCo Warp model, but steps the host MuJoCo model, which the bridge neither writes nor reads.

__init__(solver: newton.solvers.SolverMuJoCo, model: newton.Model, dof_indices: array, device: str)

Bind the bridge to a MuJoCo Warp solver.

Parameters:

• solver – The active MuJoCo Warp solver.

• model – The Newton model the solver was built from.

• dof_indices – Global Newton DOF index of each actuator slot, shape (N,).

• device – Warp device the actuator arrays live on.

Raises:

RuntimeError – If the solver’s DOF fields are not stored per world, so per-environment writes would alias one buffer.

publish_dof_friction(friction_budget: array) → None

Write the actuator’s dry-friction budget into dof_frictionloss for the next solve.

Parameters:

friction_budget – Velocity-independent friction budget per slot [N.m], shape (N,).

gather_external_torque(external_torque: array) → None

Fill external_torque with the previous solve’s external load per slot.

Applied body wrenches are not included.

Parameters:

external_torque – Destination, shape (N,). Written with -qfrc_bias + qfrc_constraint - qfrc_own_friction [N.m].

stiffen_friction_constraint() → None

Stiffen the managed DOFs’ friction constraint in MuJoCo Warp and in the Newton model.

Writing the Newton model too keeps the stiff values across joint-property resyncs.

Physics Configuration

class isaaclab_newton.physics.NewtonCfg

Bases: PhysicsCfg

Configuration for Newton physics manager.

This configuration includes Newton-specific simulation settings and solver configuration.

class_type selects the integration manager independently of the solver, which solver_cfg describes. Downstream code can subclass NewtonManager and set this field.

Attributes:

class_type	Manager class, constructed by SimulationContext as instantiate(cfg).
num_substeps	Number of substeps to use for the solver.
deterministic	Whether to request reproducible physics from the backend.
collision_decimation	Re-collide every N solver substeps within a physics tick (0 = once per tick).
debug_mode	Whether to enable debug mode for the solver.
use_cuda_graph	Whether to use CUDA graphing when simulating.
deterministic_mode	Determinism guarantee applied to the Newton solver and collision pipeline.
solver_cfg	Solver configuration.
soft_contact_cfg	Global soft-contact parameters applied after model finalization.
collision_cfg	Newton collision pipeline configuration.
default_shape_cfg	Default per-shape collision properties applied to every shape in the scene.
load_visual_shapes	Whether Newton replication imports visual-only geometry from USD.
bvh_constructor_geometry	BVH construction algorithm for mesh geometry colliders.
bvh_constructor_scene	BVH construction algorithm for the top-level scene (broad-phase) hierarchy.
bvh_constructor_gaussian	BVH construction algorithm for Gaussian-splat primitives.

class_type: type[NewtonManager] | str

Manager class, constructed by SimulationContext as instantiate(cfg).

num_substeps: int

Number of substeps to use for the solver.

deterministic: bool

Whether to request reproducible physics from the backend. Defaults to False.

This is the backend-agnostic form of the request, set by the --deterministic command-line flag. Each physics manager translates it into its own settings when the simulation starts, and raises when its configuration cannot provide the guarantee. A backend-specific determinism attribute set explicitly, such as deterministic_mode, is the more specific instruction and takes precedence.

Deterministic execution can increase memory use and reduce simulation performance.

collision_decimation: int

Re-collide every N solver substeps within a physics tick (0 = once per tick).

debug_mode: bool

Whether to enable debug mode for the solver.

use_cuda_graph: bool

Whether to use CUDA graphing when simulating.

Graphs are captured immediately after the first eager physics step, after reset and decimation setup. Capture does not advance physics. Kit/RTX uses a nonblocking stream with relaxed capture mode; kitless simulation uses Warp’s standard capture mode.

If set to False, the simulation performance will be severely degraded.

deterministic_mode: Literal['not_guaranteed', 'run_to_run', 'gpu_to_gpu']

Determinism guarantee applied to the Newton solver and collision pipeline.

The values "not_guaranteed", "run_to_run", and "gpu_to_gpu" map to the corresponding warp.DeterministicMode values. Deterministic execution increases memory use and can reduce simulation performance.

Warning

Deterministic contact ordering adds sorting work and allocates buffers sized for the configured maximum contact count. Runtime and memory overhead therefore grow with contact capacity. Enable this mode only when its reproducibility guarantee is required.

MJWarp on the GPU (built with its sensor stage disabled), XPBD, and Featherstone support this setting. Newton raises an error during solver initialization for unsupported solvers rather than silently running them without the requested guarantee.

solver_cfg: NewtonSolverCfg | None

Solver configuration. If None (default), MJWarpSolverCfg is used by default.

soft_contact_cfg: NewtonSoftContactCfg | None

Global soft-contact parameters applied after model finalization.

If None, Newton model defaults are preserved.

collision_cfg: NewtonCollisionPipelineCfg | None

Newton collision pipeline configuration.

Controls how Newton’s CollisionPipeline is configured when it is active. The pipeline is active when the solver delegates collision detection to Newton:

• MJWarpSolverCfg with use_mujoco_contacts=False,

• KaminoPADMMSolverCfg or KaminoDVISolverCfg with use_collision_detector=False,

• XPBDSolverCfg (always),

• VBDSolverCfg (always),

• FeatherstoneSolverCfg (always).

MPMSolverCfg does not use this pipeline; implicit MPM treats rigid geometry as colliders internally.

If None (default), a pipeline with broad_phase="explicit" is created automatically. Set this to a NewtonCollisionPipelineCfg to customize parameters such as broad phase algorithm, contact limits, or hydroelastic mode.

Note

Setting this while MJWarpSolverCfg.use_mujoco_contacts=True raises ValueError. When a Kamino solver config has use_collision_detector=True, the field is ignored because Kamino’s internal detector handles contacts.

default_shape_cfg: NewtonShapeCfg

Default per-shape collision properties applied to every shape in the scene.

Forwarded to Newton’s ModelBuilder.default_shape_cfg at builder construction via checked_apply(). See NewtonShapeCfg for the declared fields.

load_visual_shapes: bool | None

Whether Newton replication imports visual-only geometry from USD.

None imports it only when a viewer, an offscreen rgb_array capture, or a camera sensor is active, so headless training does not pay the USD parse time and memory for shapes nothing draws. Set to True to always import it, which is needed when a ray-cast sensor must hit geometry that carries no collider.

bvh_constructor_geometry: Literal['lbvh', 'sah', 'cubql']

BVH construction algorithm for mesh geometry colliders.

Selects the bounding-volume-hierarchy builder Newton uses for the triangle meshes of collision geometry, forwarded to ModelBuilder.BvhConfig. Trades build time against query (traversal) quality:

• "lbvh": linear BVH; fastest to build, lowest-quality tree.

• "sah": surface-area-heuristic BVH; slower build, tighter tree with faster ray/overlap queries.

• "cubql": cuBQL GPU builder; balances fast construction with good tree quality on the GPU (default).

bvh_constructor_scene: Literal['lbvh', 'sah']

BVH construction algorithm for the top-level scene (broad-phase) hierarchy.

Selects the builder for the BVH over all colliders used during broad-phase culling, forwarded to ModelBuilder.BvhConfig. See bvh_constructor_geometry for the "lbvh" / "sah" trade-off; "cubql" is not available for the scene hierarchy.

bvh_constructor_gaussian: Literal['lbvh', 'sah', 'cubql']

BVH construction algorithm for Gaussian-splat primitives.

Selects the builder for the BVH over 3D Gaussian primitives (used by the Gaussian renderer/collision path), forwarded to ModelBuilder.BvhConfig. See bvh_constructor_geometry for the "lbvh" / "sah" / "cubql" trade-off.

class isaaclab_newton.physics.NewtonBackendCfg

Bases: BackendCfg

Allocate model and state from the matching builder; closing them leaves the builder intact.

Attributes:

class_type	Constructor called through instantiate(cfg); the returned resource must implement close().
physics_cfg	Selected physics settings, also identifying the shared construction builder.
device	Device on which to allocate the model and native buffers.

class_type: type[NewtonBackend] | str

Constructor called through instantiate(cfg); the returned resource must implement close().

physics_cfg: PhysicsCfg

Selected physics settings, also identifying the shared construction builder.

device: str

Device on which to allocate the model and native buffers.

class isaaclab_newton.physics.NewtonBuilderCfg

Bases: object

Share mutable construction data, populated before model allocation and retained across hard resets.

Attributes:

class_type	Factory function returning a new newton.ModelBuilder; instantiate() calls it.
physics_cfg	Selected physics settings; non-Newton physics requires a render-only Newton representation.

class_type: Callable[[NewtonBuilderCfg], ModelBuilder] | str

Factory function returning a new newton.ModelBuilder; instantiate() calls it.

physics_cfg: PhysicsCfg

Selected physics settings; non-Newton physics requires a render-only Newton representation.

isaaclab_newton.physics.create_newton_builder(cfg: NewtonBuilderCfg) → newton.ModelBuilder

Construct the shared builder: solver-aware under Newton physics, plain otherwise.

Parameters:

cfg – The selected physics configuration.

Returns:

An empty builder.

class isaaclab_newton.physics.NewtonSoftContactCfg

Bases: object

Global soft-contact parameters applied to the finalized Newton model.

Attributes:

soft_contact_ke	Body-particle and particle self-contact stiffness [N/m].
soft_contact_kd	Body-particle contact damping [N*s/m].
soft_contact_mu	Body-particle contact friction coefficient [dimensionless].

soft_contact_ke: float

Body-particle and particle self-contact stiffness [N/m].

Effective body-particle stiffness is 0.5 * (soft_contact_ke + shape_ke), where shape_ke is the rigid shape’s material stiffness.

soft_contact_kd: float

Body-particle contact damping [N*s/m].

soft_contact_mu: float

Body-particle contact friction coefficient [dimensionless].

Effective body-particle friction is sqrt(soft_contact_mu * shape_mu), where shape_mu is the rigid shape’s material friction coefficient.

class isaaclab_newton.physics.NewtonSolverCfg

Bases: object

Configuration of a Newton solver.

class_type selects the NewtonSolver that builds and drives the solver; customizing a solver means subclassing it. For the solver parameters, see the Newton documentation.

Attributes:

class_type	Solver class that builds and drives Newton's solver, e.g. instantiate(cfg, model, mode).step(...).
solver_type	Solver type metadata (deprecated).

class_type: type[NewtonSolver] | str

Solver class that builds and drives Newton’s solver, e.g. instantiate(cfg, model, mode).step(...).

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.

class isaaclab_newton.physics.MJWarpSolverCfg

Bases: NewtonSolverCfg

Configuration for MuJoCo Warp solver-related parameters.

These parameters are used to configure the MuJoCo Warp solver. For more information, see the MuJoCo Warp documentation.

Attributes:

class_type	Solver class that builds and drives Newton's solver, e.g. instantiate(cfg, model, mode).step(...).
solver_type	Solver type.
njmax	Number of constraints per environment (world).
nconmax	Number of contact points per environment (world).
iterations	Number of solver iterations.
ls_iterations	Number of line search iterations for the solver.
solver	Solver type.
integrator	Integrator type.
use_mujoco_cpu	Whether to use the pure MuJoCo backend instead of mujoco_warp.
disable_contacts	Whether to disable contact computation in MuJoCo.
disable_sensors	Whether to disable MuJoCo Warp's internal sensor computation.
default_actuator_gear	Default gear ratio for all actuators.
actuator_gears	Dictionary mapping joint names to specific gear ratios, overriding the default_actuator_gear.
update_data_interval	Frequency (in solver substeps) at which to update the MuJoCo Data object from the Newton state.
save_to_mjcf	Optional path to save the generated MJCF model file.
impratio	Frictional-to-normal constraint impedance ratio.
cone	The type of contact friction cone.
ccd_iterations	Maximum iterations for convex collision detection (GJK/EPA).
enable_multiccd	Whether to enable multiple-contact convex collision detection.
ls_parallel	Deprecated parallel line search option.
use_mujoco_contacts	Whether to use MuJoCo's internal contact solver.
tolerance	Solver convergence tolerance for the constraint residual.

class_type: type | str

Solver class that builds and drives Newton’s solver, e.g. instantiate(cfg, model, mode).step(...).

solver_type: str

Solver type. Can be “mujoco_warp”.

njmax: int

Number of constraints per environment (world).

nconmax: int | None

Number of contact points per environment (world).

iterations: int

Number of solver iterations.

ls_iterations: int

Number of line search iterations for the solver.

solver: str

Solver type. Can be “cg” or “newton”, or their corresponding MuJoCo integer constants.

integrator: str

Integrator type. Can be “euler”, “rk4”, or “implicitfast”, or their corresponding MuJoCo integer constants.

use_mujoco_cpu: bool

Whether to use the pure MuJoCo backend instead of mujoco_warp.

disable_contacts: bool

Whether to disable contact computation in MuJoCo.

disable_sensors: bool

Whether to disable MuJoCo Warp’s internal sensor computation.

A determinism guarantee (NewtonCfg.deterministic_mode) disables it automatically. Isaac Lab sensors use Newton state directly and do not depend on MuJoCo Warp’s internal sensor data.

default_actuator_gear: float | None

Default gear ratio for all actuators.

actuator_gears: dict[str, float] | None

Dictionary mapping joint names to specific gear ratios, overriding the default_actuator_gear.

update_data_interval: int

Frequency (in solver substeps) at which to update the MuJoCo Data object from the Newton state.

If 0, periodic state imports are disabled after initialization. With MuJoCo Warp, authored state writes that flag the manager’s reset mask are still synchronized for the affected worlds at the next forward or physics-step boundary, independently of this interval. The native MuJoCo CPU backend only synchronizes template world 0 when it is flagged.

save_to_mjcf: str | None

Optional path to save the generated MJCF model file.

If None, the MJCF model is not saved.

impratio: float

Frictional-to-normal constraint impedance ratio.

cone: str

The type of contact friction cone. Can be “pyramidal” or “elliptic”.

ccd_iterations: int

Maximum iterations for convex collision detection (GJK/EPA).

Increase this if you see warnings about opt.ccd_iterations needing to be increased, which typically occurs with complex collision geometries (e.g. multi-finger hands).

enable_multiccd: bool

Whether to enable multiple-contact convex collision detection. Defaults to False.

With use_mujoco_contacts enabled, supported convex geometry pairs can generate a contact manifold (several points across a touching surface) instead of a single point. This can improve stability for flat mesh contacts in stacking and grasping. It does not enable continuous collision detection or prevent tunneling between simulation steps.

MuJoCo Warp’s supported pairs and contact-margin restrictions differ from MuJoCo CPU. Primitive colliders can already produce multiple contacts with this option disabled. Additional contacts can increase solver work and the required nconmax and njmax capacities. See MuJoCo’s multiple-contact documentation.

ls_parallel: bool

Deprecated parallel line search option.

Setting this to True emits a DeprecationWarning and is ignored. MuJoCo Warp is dropping support for parallel line search; Isaac Lab uses iterative line search for performance.

use_mujoco_contacts: bool

Whether to use MuJoCo’s internal contact solver.

If True (default), MuJoCo handles collision detection and contact resolution internally. If False, Newton’s CollisionPipeline is used instead. A default pipeline (broad_phase="explicit") is created automatically when NewtonCfg.collision_cfg is None. Set NewtonCfg.collision_cfg to a NewtonCollisionPipelineCfg to customize pipeline parameters (broad phase, contact limits, hydroelastic, etc.).

Note

Setting collision_cfg while use_mujoco_contacts=True raises ValueError because the two collision modes are mutually exclusive.

tolerance: float

Solver convergence tolerance for the constraint residual.

The solver iterates until the residual drops below this threshold or iterations is reached. Lower values give more precise constraint satisfaction at the cost of more iterations. MuJoCo default is 1e-8; Newton default is 1e-6.

class isaaclab_newton.physics.VBDSolverCfg

Bases: NewtonSolverCfg

Configuration for the Vertex Block Descent solver.

Attributes:

class_type	Solver class that builds and drives Newton's solver, e.g. instantiate(cfg, model, mode).step(...).
iterations	Number of VBD iterations per substep.
friction_epsilon	Relative tangential speed used to smooth friction near rest [m/s].
integrate_with_external_rigid_solver	Whether an external solver integrates rigid bodies.
update_joint_state	Derive standalone VBD joint positions and velocities after each physics tick.
particle_enable_self_contact	Whether to enable particle self-contact.
particle_self_contact_radius	Particle radius used for self-contact detection [m].
particle_self_contact_margin	Self-contact detection margin [m].
particle_collision_detection_interval	<0 before init, 0 before and after init, k>=1 before every k VBD iterations.
particle_vertex_contact_buffer_size	Preallocation size for each vertex contact buffer.
solver_type	Solver type metadata (deprecated).
particle_edge_contact_buffer_size	Preallocation size for each edge contact buffer.
particle_topological_contact_filter_threshold	Topological distance below which self-contacts are discarded.
particle_rest_shape_contact_exclusion_radius	Rest-shape separation threshold for filtering contacts [m].
rigid_compliant_alm	Whether to use compliant ALM for rigid joints and contacts; None preserves Newton's default.
rigid_joint_linear_ke	Structural linear stiffness of non-rod rigid joints [N/m], separate from joint-drive gains.
rigid_joint_angular_ke	Structural angular stiffness of non-rod rigid joints [N m/rad], separate from joint-drive gains.
rigid_contact_k_start	Initial stiffness seed for rigid-body contacts [N/m].
rigid_body_contact_buffer_size	Per-body body-body contact capacity when VBD integrates rigid bodies.
rigid_body_particle_contact_buffer_size	Per-body particle, edge, and face soft-contact capacity when VBD integrates rigid bodies.

class_type: type | str

Solver class that builds and drives Newton’s solver, e.g. instantiate(cfg, model, mode).step(...).

iterations: int

Number of VBD iterations per substep.

friction_epsilon: float

Relative tangential speed used to smooth friction near rest [m/s].

integrate_with_external_rigid_solver: bool

Whether an external solver integrates rigid bodies.

update_joint_state: bool

Derive standalone VBD joint positions and velocities after each physics tick.

Disable only when consumers use body state exclusively. External rigid integration and coupled solvers retain ownership of their generalized joint state and skip this synchronization.

particle_enable_self_contact: bool

Whether to enable particle self-contact.

particle_self_contact_radius: float

Particle radius used for self-contact detection [m].

particle_self_contact_margin: float

Self-contact detection margin [m].

particle_collision_detection_interval: int

<0 before init, 0 before and after init, k>=1 before every k VBD iterations.

Type:

Self-contact detection

particle_vertex_contact_buffer_size: int

Preallocation size for each vertex contact buffer.

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.

particle_edge_contact_buffer_size: int

Preallocation size for each edge contact buffer.

particle_topological_contact_filter_threshold: int

Topological distance below which self-contacts are discarded.

particle_rest_shape_contact_exclusion_radius: float

Rest-shape separation threshold for filtering contacts [m].

rigid_compliant_alm: bool | None

Whether to use compliant ALM for rigid joints and contacts; None preserves Newton’s default.

rigid_joint_linear_ke: float

Structural linear stiffness of non-rod rigid joints [N/m], separate from joint-drive gains.

rigid_joint_angular_ke: float

Structural angular stiffness of non-rod rigid joints [N m/rad], separate from joint-drive gains.

rigid_contact_k_start: float

Initial stiffness seed for rigid-body contacts [N/m].

rigid_body_contact_buffer_size: int

Per-body body-body contact capacity when VBD integrates rigid bodies.

rigid_body_particle_contact_buffer_size: int

Per-body particle, edge, and face soft-contact capacity when VBD integrates rigid bodies.

class isaaclab_newton.physics.XPBDSolverCfg

Bases: NewtonSolverCfg

An implicit integrator using eXtended Position-Based Dynamics (XPBD) for rigid and soft body simulation.

References

• Miles Macklin, Matthias Müller, and Nuttapong Chentanez. 2016. XPBD: position-based simulation of compliant constrained dynamics. In Proceedings of the 9th International Conference on Motion in Games (MIG ‘16). Association for Computing Machinery, New York, NY, USA, 49-54. https://doi.org/10.1145/2994258.2994272

• Matthias Müller, Miles Macklin, Nuttapong Chentanez, Stefan Jeschke, and Tae-Yong Kim. 2020. Detailed rigid body simulation with extended position based dynamics. In Proceedings of the ACM SIGGRAPH/Eurographics Symposium on Computer Animation (SCA ‘20). Eurographics Association, Goslar, DEU, Article 10, 1-12. https://doi.org/10.1111/cgf.14105

Attributes:

class_type	Solver class that builds and drives Newton's solver, e.g. instantiate(cfg, model, mode).step(...).
solver_type	Solver type.
iterations	Number of solver iterations.
soft_body_relaxation	Relaxation parameter for soft body simulation.
soft_contact_relaxation	Relaxation parameter for soft contact simulation.
joint_linear_relaxation	Relaxation parameter for joint linear simulation.
joint_angular_relaxation	Relaxation parameter for joint angular simulation.
joint_linear_compliance	Compliance parameter for joint linear simulation.
joint_angular_compliance	Compliance parameter for joint angular simulation.
rigid_contact_relaxation	Relaxation parameter for rigid contact simulation.
rigid_contact_con_weighting	Whether to use contact constraint weighting for rigid contact simulation.
angular_damping	Angular damping parameter for rigid contact simulation.
enable_restitution	Whether to enable restitution for rigid contact simulation.

class_type: type | str

Solver class that builds and drives Newton’s solver, e.g. instantiate(cfg, model, mode).step(...).

solver_type: str

Solver type. Can be “xpbd”.

iterations: int

Number of solver iterations.

soft_body_relaxation: float

Relaxation parameter for soft body simulation.

soft_contact_relaxation: float

Relaxation parameter for soft contact simulation.

joint_linear_relaxation: float

Relaxation parameter for joint linear simulation.

joint_angular_relaxation: float

Relaxation parameter for joint angular simulation.

joint_linear_compliance: float

Compliance parameter for joint linear simulation.

joint_angular_compliance: float

Compliance parameter for joint angular simulation.

rigid_contact_relaxation: float

Relaxation parameter for rigid contact simulation.

rigid_contact_con_weighting: bool

Whether to use contact constraint weighting for rigid contact simulation.

angular_damping: float

Angular damping parameter for rigid contact simulation.

enable_restitution: bool

Whether to enable restitution for rigid contact simulation.

class isaaclab_newton.physics.FeatherstoneSolverCfg

Bases: NewtonSolverCfg

A semi-implicit integrator using symplectic Euler.

It operates on reduced (also called generalized) coordinates to simulate articulated rigid body dynamics based on Featherstone’s composite rigid body algorithm (CRBA).

See: Featherstone, Roy. Rigid Body Dynamics Algorithms. Springer US, 2014.

Semi-implicit time integration is a variational integrator that preserves energy, however it is not unconditionally stable, and requires a time-step small enough to support the required stiffness and damping forces.

See: https://en.wikipedia.org/wiki/Semi-implicit_Euler_method

Attributes:

class_type	Solver class that builds and drives Newton's solver, e.g. instantiate(cfg, model, mode).step(...).
solver_type	Solver type.
angular_damping	Angular damping parameter for rigid contact simulation.
update_mass_matrix_interval	Frequency (in simulation steps) at which to update the mass matrix.
friction_smoothing	Friction smoothing parameter.
use_tile_gemm	Whether to use tile-based GEMM for the mass matrix.
fuse_cholesky	Whether to fuse the Cholesky decomposition.

class_type: type | str

Solver class that builds and drives Newton’s solver, e.g. instantiate(cfg, model, mode).step(...).

solver_type: str

Solver type. Can be “featherstone”.

angular_damping: float

Angular damping parameter for rigid contact simulation.

update_mass_matrix_interval: int

Frequency (in simulation steps) at which to update the mass matrix.

friction_smoothing: float

Friction smoothing parameter.

use_tile_gemm: bool

Whether to use tile-based GEMM for the mass matrix.

fuse_cholesky: bool

Whether to fuse the Cholesky decomposition.

class isaaclab_newton.physics.KaminoPADMMCfg

Bases: object

P-ADMM forward-dynamics solver parameters for Kamino.

Attributes:

max_iterations	Maximum number of P-ADMM solver iterations.
primal_tolerance	Primal residual convergence tolerance.
dual_tolerance	Dual residual convergence tolerance.
compl_tolerance	Complementarity residual convergence tolerance.
restart_tolerance	Combined primal-dual residual tolerance for acceleration restarts.
rho_0	Initial penalty parameter.
rho_min	Lower bound on the penalty parameter.
a_0	Initial acceleration parameter.
alpha	Primal-dual residual threshold for penalty updates.
tau	Penalty increase/decrease factor.
eta	Proximal regularization parameter.
penalty_update_freq	Frequency of penalty updates.
penalty_update_method	Penalty update method.
linear_solver_tolerance	Absolute tolerance for the iterative linear solver.
linear_solver_tolerance_ratio	Ratio adapting the linear solver tolerance from the ADMM primal residual.
use_acceleration	Whether to use Nesterov-type acceleration (APADMM).
use_graph_conditionals	Whether to use CUDA graph conditional nodes in the iterative solver.
warmstart_mode	Warmstart mode.
contact_warmstart_method	Contact warm-start method.

max_iterations: int

Maximum number of P-ADMM solver iterations.

primal_tolerance: float

Primal residual convergence tolerance.

dual_tolerance: float

Dual residual convergence tolerance.

compl_tolerance: float

Complementarity residual convergence tolerance.

restart_tolerance: float

Combined primal-dual residual tolerance for acceleration restarts.

rho_0: float

Initial penalty parameter.

rho_min: float

Lower bound on the penalty parameter.

a_0: float

Initial acceleration parameter.

alpha: float

Primal-dual residual threshold for penalty updates.

tau: float

Penalty increase/decrease factor.

eta: float

Proximal regularization parameter. Must be greater than zero.

penalty_update_freq: int

Frequency of penalty updates. Zero disables updates.

penalty_update_method: Literal['fixed', 'balanced']

Penalty update method.

linear_solver_tolerance: float

Absolute tolerance for the iterative linear solver. Zero leaves it unchanged.

linear_solver_tolerance_ratio: float

Ratio adapting the linear solver tolerance from the ADMM primal residual.

use_acceleration: bool

Whether to use Nesterov-type acceleration (APADMM).

use_graph_conditionals: bool

Whether to use CUDA graph conditional nodes in the iterative solver.

warmstart_mode: Literal['none', 'internal', 'containers']

Warmstart mode.

contact_warmstart_method: Literal['key_and_position', 'geom_pair_net_force', 'geom_pair_net_wrench', 'key_and_position_with_net_force_backup', 'key_and_position_with_net_wrench_backup']

Contact warm-start method.

class isaaclab_newton.physics.KaminoDVICfg

Bases: object

DVI forward-dynamics solver parameters for Kamino.

Attributes:

tolerance	Convergence tolerance on the projected update size.
regularization	Diagonal regularization added to each projected update denominator.
omega	Relaxation factor applied to projected Gauss-Seidel updates.
max_alternating_iterations	Maximum outer DVI iterations.
inequality_sweeps_per_iteration	Projected Gauss-Seidel sweeps per DVI iteration.
bilateral_solve_interval	DVI iterations between repeated direct bilateral solves.
bilateral_solver_type	Direct linear solver for the bilateral constraint block.
bilateral_solver_kwargs	Additional keyword arguments for the bilateral linear solver.
warmstart_mode	Warmstart mode.
contact_warmstart_method	Contact warm-start method when warmstart_mode is containers.

tolerance: float

Convergence tolerance on the projected update size.

regularization: float

Diagonal regularization added to each projected update denominator.

omega: float

Relaxation factor applied to projected Gauss-Seidel updates.

max_alternating_iterations: int

Maximum outer DVI iterations.

inequality_sweeps_per_iteration: int

Projected Gauss-Seidel sweeps per DVI iteration.

bilateral_solve_interval: int

DVI iterations between repeated direct bilateral solves.

bilateral_solver_type: Literal['LLTB', 'LLTBRCM']

Direct linear solver for the bilateral constraint block.

bilateral_solver_kwargs: dict[str, Any]

Additional keyword arguments for the bilateral linear solver.

warmstart_mode: Literal['none', 'internal', 'containers']

Warmstart mode.

contact_warmstart_method: Literal['key_and_position', 'geom_pair_net_force', 'key_and_position_with_net_force_backup']

Contact warm-start method when warmstart_mode is containers.

class isaaclab_newton.physics.KaminoDynamicsCfg

Bases: object

Constrained forward-dynamics problem parameters for Kamino.

Attributes:

preconditioning	Whether to precondition the dual problem.
linear_solver_type	Linear solver for the dynamics problem.
linear_solver_kwargs	Additional keyword arguments for the linear solver.

preconditioning: bool

Whether to precondition the dual problem. Must be False when using DVI.

linear_solver_type: Literal['LLTB', 'LLTBRCM', 'CR', 'CRF']

Linear solver for the dynamics problem.

linear_solver_kwargs: dict[str, Any]

Additional keyword arguments for the linear solver.

class isaaclab_newton.physics.KaminoConstraintsCfg

Bases: object

Global constraint stabilization parameters for Kamino.

Attributes:

alpha	Baumgarte stabilization for bilateral joint constraints.
beta	Baumgarte stabilization for unilateral joint-limit constraints.
gamma	Baumgarte stabilization for unilateral contact constraints.
delta	Contact penetration margin [m].

alpha: float

Baumgarte stabilization for bilateral joint constraints. Valid range is [0, 1].

beta: float

Baumgarte stabilization for unilateral joint-limit constraints. Valid range is [0, 1].

gamma: float

Baumgarte stabilization for unilateral contact constraints. Valid range is [0, 1].

delta: float

Contact penetration margin [m].

class isaaclab_newton.physics.KaminoFKCfg

Bases: object

Forward-kinematics reset solver parameters for Kamino.

Attributes:

use_regularization	Whether to regularize the FK reset solve (Tikhonov term on body poses).
regularization_weight	Weight of the FK reset regularizer when use_regularization is True.
tolerance	Convergence tolerance of the FK reset solve.

use_regularization: bool

Whether to regularize the FK reset solve (Tikhonov term on body poses).

regularization_weight: float

Weight of the FK reset regularizer when use_regularization is True.

tolerance: float

Convergence tolerance of the FK reset solve.

class isaaclab_newton.physics.KaminoCollisionDetectorCfg

Bases: object

Internal Kamino collision-detector parameters.

Attributes:

pipeline	Collision-detection pipeline.
broadphase	Broad-phase algorithm.
bvtype	Bounding-volume type.
max_contacts	Model-wide contact buffer capacity cap.
max_contacts_per_world	Per-world contact buffer capacity override.
max_contacts_per_pair	Maximum contacts generated per candidate geometry pair.
max_triangle_pairs	Maximum triangle-primitive shape pairs in narrow phase.
default_gap	Default detection gap [m] applied as a floor to per-geometry gaps.

pipeline: Literal['primitive', 'unified'] | None

Collision-detection pipeline. None uses Newton’s default (unified).

broadphase: Literal['nxn', 'sap', 'explicit'] | None

Broad-phase algorithm. None uses Newton’s default.

bvtype: Literal['aabb', 'bs'] | None

Bounding-volume type. None uses Newton’s default.

max_contacts: int | None

Model-wide contact buffer capacity cap.

max_contacts_per_world: int | None

Per-world contact buffer capacity override.

max_contacts_per_pair: int | None

Maximum contacts generated per candidate geometry pair.

max_triangle_pairs: int | None

Maximum triangle-primitive shape pairs in narrow phase.

default_gap: float | None

Default detection gap [m] applied as a floor to per-geometry gaps.

class isaaclab_newton.physics.KaminoMaterialsCfg

Bases: object

Material mixing parameters for Kamino contacts.

Attributes:

friction_mix_mode	How friction coefficients are mixed for a contact pair.
restitution_mix_mode	How restitution coefficients are mixed for a contact pair.

friction_mix_mode: Literal['average', 'multiply', 'max', 'min']

How friction coefficients are mixed for a contact pair.

restitution_mix_mode: Literal['average', 'multiply', 'max', 'min']

How restitution coefficients are mixed for a contact pair.

class isaaclab_newton.physics.KaminoPADMMSolverCfg

Bases: _KaminoSolverCfgBase

Configuration for Kamino with the P-ADMM forward-dynamics solver.

Attributes:

class_type	Solver class that builds and drives Newton's solver, e.g. instantiate(cfg, model, mode).step(...).
solver_type	Solver type.
integrator	Integrator type.
use_collision_detector	Whether to use Kamino's internal collision detector instead of Newton's pipeline.
use_fk_solver	Whether to enable the forward kinematics solver for state resets.
sparse_jacobian	Whether to use sparse Jacobian computation.
sparse_dynamics	Whether to use sparse dynamics computation.
rotation_correction	Rotation correction mode.
angular_velocity_damping	Angular velocity damping factor.
collect_solver_info	Whether to collect solver convergence and performance info at each step.
compute_solution_metrics	Whether to compute solution metrics at each step.
dynamics	Constrained dynamics problem parameters.
constraints	Constraint stabilization parameters.
fk	Forward-kinematics reset solver parameters.
collision_detector	Internal collision-detector parameters.
materials	Material mixing parameters.
max_contacts_per_world	Cap the per-world contact pre-allocation handed to Kamino.
dynamics_solver_cfg	P-ADMM forward-dynamics solver parameters.

class_type: type | str

Solver class that builds and drives Newton’s solver, e.g. instantiate(cfg, model, mode).step(...).

solver_type: str

Solver type. Can be “kamino”.

integrator: Literal['euler', 'moreau']

Integrator type.

use_collision_detector: bool

Whether to use Kamino’s internal collision detector instead of Newton’s pipeline.

use_fk_solver: bool | None

Whether to enable the forward kinematics solver for state resets.

When None, Kamino will automatically determine whether to use the FK solver based on the model’s articulation structure. If the model has loop-closing joints, the FK solver will be used.

When True, eval_fk() reconciles body state via SolverKamino.reset() with SolverKamino.ResetConfig.from_joints. Kamino’s FK solver computes consistent body poses/velocities from the joint coordinates (including the base joint for floating bases), resolves passive / loop-closure joints, and writes back a consistent full joint state. Environment resets only need to write actuated DOFs in joint_q; passive values are filled in by FK. This is required for closed-loop systems.

When False, Newton’s articulated eval_fk is used instead over the full joint_q / joint_qd. It is then up to the user to specify constraint-consistent values. This is the faster option for purely articulated (tree-structured) systems.

sparse_jacobian: bool | None

Whether to use sparse Jacobian computation. None lets Newton pick per backend.

sparse_dynamics: bool

Whether to use sparse dynamics computation.

rotation_correction: Literal['twopi', 'continuous', 'none']

Rotation correction mode.

angular_velocity_damping: float

Angular velocity damping factor. Valid range is [0.0, 1.0].

collect_solver_info: bool

Whether to collect solver convergence and performance info at each step.

Warning

Enabling this significantly increases solver runtime and should only be used for debugging.

compute_solution_metrics: bool

Whether to compute solution metrics at each step.

Warning

Enabling this significantly increases solver runtime and should only be used for debugging.

dynamics: KaminoDynamicsCfg | None

Constrained dynamics problem parameters.

When None, Newton selects defaults appropriate to the selected dynamics solver and sparsity settings.

constraints: KaminoConstraintsCfg

Constraint stabilization parameters.

fk: KaminoFKCfg

Forward-kinematics reset solver parameters.

collision_detector: KaminoCollisionDetectorCfg

Internal collision-detector parameters.

materials: KaminoMaterialsCfg

Material mixing parameters.

max_contacts_per_world: int | None

Cap the per-world contact pre-allocation handed to Kamino.

When None, Kamino falls back to geoms.world_minimum_contacts derived from the collision pipeline, which over-allocates dramatically for contact-rich assets. Set this to bound GPU memory for multi-env training of contact-heavy tasks (e.g. legged locomotion or manipulation). The total model.rigid_contact_max is computed as max_contacts_per_world * model.world_count before solver construction.

This field is applied by build() and is not forwarded to Newton.

dynamics_solver_cfg: KaminoPADMMCfg

P-ADMM forward-dynamics solver parameters.

class isaaclab_newton.physics.KaminoDVISolverCfg

Bases: _KaminoSolverCfgBase

Configuration for Kamino with the DVI forward-dynamics solver.

Attributes:

class_type	Solver class that builds and drives Newton's solver, e.g. instantiate(cfg, model, mode).step(...).
solver_type	Solver type.
integrator	Integrator type.
use_collision_detector	Whether to use Kamino's internal collision detector instead of Newton's pipeline.
use_fk_solver	Whether to enable the forward kinematics solver for state resets.
sparse_jacobian	Whether to use sparse Jacobian computation.
sparse_dynamics	Whether to use sparse dynamics computation.
rotation_correction	Rotation correction mode.
angular_velocity_damping	Angular velocity damping factor.
collect_solver_info	Whether to collect solver convergence and performance info at each step.
compute_solution_metrics	Whether to compute solution metrics at each step.
dynamics	Constrained dynamics problem parameters.
constraints	Constraint stabilization parameters.
fk	Forward-kinematics reset solver parameters.
collision_detector	Internal collision-detector parameters.
materials	Material mixing parameters.
max_contacts_per_world	Cap the per-world contact pre-allocation handed to Kamino.
dynamics_solver_cfg	DVI forward-dynamics solver parameters.

class_type: type | str

Solver class that builds and drives Newton’s solver, e.g. instantiate(cfg, model, mode).step(...).

solver_type: str

Solver type. Can be “kamino”.

integrator: Literal['euler', 'moreau']

Integrator type.

use_collision_detector: bool

Whether to use Kamino’s internal collision detector instead of Newton’s pipeline.

use_fk_solver: bool | None

Whether to enable the forward kinematics solver for state resets.

When None, Kamino will automatically determine whether to use the FK solver based on the model’s articulation structure. If the model has loop-closing joints, the FK solver will be used.

When True, eval_fk() reconciles body state via SolverKamino.reset() with SolverKamino.ResetConfig.from_joints. Kamino’s FK solver computes consistent body poses/velocities from the joint coordinates (including the base joint for floating bases), resolves passive / loop-closure joints, and writes back a consistent full joint state. Environment resets only need to write actuated DOFs in joint_q; passive values are filled in by FK. This is required for closed-loop systems.

When False, Newton’s articulated eval_fk is used instead over the full joint_q / joint_qd. It is then up to the user to specify constraint-consistent values. This is the faster option for purely articulated (tree-structured) systems.

sparse_jacobian: bool | None

Whether to use sparse Jacobian computation. None lets Newton pick per backend.

sparse_dynamics: bool

Whether to use sparse dynamics computation.

rotation_correction: Literal['twopi', 'continuous', 'none']

Rotation correction mode.

angular_velocity_damping: float

Angular velocity damping factor. Valid range is [0.0, 1.0].

collect_solver_info: bool

Whether to collect solver convergence and performance info at each step.

Warning

Enabling this significantly increases solver runtime and should only be used for debugging.

compute_solution_metrics: bool

Whether to compute solution metrics at each step.

Warning

Enabling this significantly increases solver runtime and should only be used for debugging.

dynamics: KaminoDynamicsCfg | None

Constrained dynamics problem parameters.

When None, Newton selects defaults appropriate to the selected dynamics solver and sparsity settings.

constraints: KaminoConstraintsCfg

Constraint stabilization parameters.

fk: KaminoFKCfg

Forward-kinematics reset solver parameters.

collision_detector: KaminoCollisionDetectorCfg

Internal collision-detector parameters.

materials: KaminoMaterialsCfg

Material mixing parameters.

max_contacts_per_world: int | None

Cap the per-world contact pre-allocation handed to Kamino.

When None, Kamino falls back to geoms.world_minimum_contacts derived from the collision pipeline, which over-allocates dramatically for contact-rich assets. Set this to bound GPU memory for multi-env training of contact-heavy tasks (e.g. legged locomotion or manipulation). The total model.rigid_contact_max is computed as max_contacts_per_world * model.world_count before solver construction.

This field is applied by build() and is not forwarded to Newton.

dynamics_solver_cfg: KaminoDVICfg

DVI forward-dynamics solver parameters.

class isaaclab_newton.physics.MPMSolverCfg

Bases: NewtonSolverCfg

Configuration for Newton’s implicit Material Point Method (MPM) solver.

The implicit MPM solver advances particle materials and treats rigid geometry as colliders. It is not a rigid-body or articulation dynamics solver.

Attributes:

class_type	Solver class that builds and drives Newton's solver, e.g. instantiate(cfg, model, mode).step(...).
solver_type	Solver type.
max_iterations	Maximum number of iterations for the rheology solver.
tolerance	Tolerance for the rheology solver.
solver	Rheology solver, or an ordered warm-start sequence of solvers.
warmstart_mode	Warm-start mode for the rheology solver.
collider_velocity_mode	Collider velocity computation mode.
voxel_size	Size of the MPM grid voxels [m].
grid_type	Type of grid to use.
grid_padding	Number of empty cells to add around particles when allocating the grid.
max_active_cell_count	Maximum active grid-cell count shared by all worlds.
max_leaf_node_count	Maximum sparse-grid leaf-node count shared by all worlds.
max_lower_node_count	Maximum sparse-grid lower internal-node count shared by all worlds.
max_upper_node_count	Maximum sparse-grid upper internal-node count shared by all worlds.
separate_worlds	Whether each Newton world uses an independent local MPM grid environment.
transfer_scheme	Particle-grid transfer scheme.
integration_scheme	Integration scheme controlling shape-function support.
critical_fraction	Dimensionless fraction under which the yield surface collapses.
air_drag	Numerical drag for background air.
collider_normal_from_sdf_gradient	Whether collider normals are computed from SDF gradients rather than closest points.
collider_basis	Collider basis function, such as "S2" or "Q1".
strain_basis	Strain basis function, such as "P0", "P1d", "Q1", or "Q1d".
velocity_basis	Velocity basis function, such as "Q1", "B2", or "B3".
project_outside_colliders	Whether to hard-project particles out of collider interiors after each substep.

class_type: type | str

Solver class that builds and drives Newton’s solver, e.g. instantiate(cfg, model, mode).step(...).

solver_type: str

Solver type. Can be “implicit_mpm”.

max_iterations: int

Maximum number of iterations for the rheology solver.

tolerance: float

Tolerance for the rheology solver.

solver: str | tuple[str, ...]

Rheology solver, or an ordered warm-start sequence of solvers.

Values use the canonical tokens defined by NewtonMPMSceneAPI. "auto" lets Newton pick the solver from the velocity basis. Pass a tuple such as ("conjugate-residual", "gauss-seidel") to warm-start solvers left-to-right.

warmstart_mode: Literal['none', 'auto', 'particles', 'grid', 'smoothed']

Warm-start mode for the rheology solver.

collider_velocity_mode: Literal['forward', 'backward', 'instantaneous', 'finite_difference']

Collider velocity computation mode.

"instantaneous" is deprecated in favor of "forward", and "finite_difference" is deprecated in favor of "backward".

voxel_size: float

Size of the MPM grid voxels [m].

grid_type: Literal['sparse', 'dense', 'fixed']

Type of grid to use.

grid_padding: int

Number of empty cells to add around particles when allocating the grid.

max_active_cell_count: int

Maximum active grid-cell count shared by all worlds.

A positive value reserves persistent capacity for rebuildable sparse grids and bounds active subsets of dense and fixed grids. -1 keeps sparse allocation dynamic and uses exact active counts for the other grid types.

max_leaf_node_count: int

Maximum sparse-grid leaf-node count shared by all worlds.

-1 lets Newton derive the capacity from max_active_cell_count.

max_lower_node_count: int

Maximum sparse-grid lower internal-node count shared by all worlds.

-1 lets Newton derive the capacity from the initial topology.

max_upper_node_count: int

Maximum sparse-grid upper internal-node count shared by all worlds.

-1 lets Newton derive the capacity from the initial topology.

separate_worlds: bool

Whether each Newton world uses an independent local MPM grid environment.

transfer_scheme: Literal['apic', 'pic']

Particle-grid transfer scheme.

integration_scheme: Literal['pic', 'gimp']

Integration scheme controlling shape-function support.

critical_fraction: float

Dimensionless fraction under which the yield surface collapses.

air_drag: float

Numerical drag for background air.

collider_normal_from_sdf_gradient: bool

Whether collider normals are computed from SDF gradients rather than closest points.

collider_basis: str

Collider basis function, such as "S2" or "Q1".

strain_basis: str

Strain basis function, such as "P0", "P1d", "Q1", or "Q1d".

velocity_basis: str

Velocity basis function, such as "Q1", "B2", or "B3".

project_outside_colliders: bool

Whether to hard-project particles out of collider interiors after each substep.

When True, step() calls SolverImplicitMPM.project_outside() immediately after every solver substep: it applies a Coulomb response and pushes particles that drifted into a collider back onto its surface. The implicit solve already resolves colliders at the grid level; this is the particle-level correction that stops material from slowly settling inside colliders, mirroring Newton’s MPM examples. Leave it False for collider-free scenes to skip a per-substep projection pass over every particle.

This is a manager-level stepping option and is intentionally not part of SolverImplicitMPM.Config.

class isaaclab_newton.physics.NewtonCollisionPipelineCfg

Bases: object

Configuration for Newton collision pipeline.

Full-featured collision pipeline with GJK/MPR narrow phase and pluggable broad phase. When this config is set on NewtonCfg.collision_cfg:

• MJWarpSolverCfg: Newton’s collision pipeline replaces MuJoCo’s internal contact solver.

• Other solvers (XPBD, Featherstone, etc.): Configures the collision pipeline parameters (these solvers always use Newton’s collision pipeline).

Key features:

• GJK/MPR algorithms for convex-convex collision detection

• Multiple broad phase options: NXN (all-pairs), SAP (sweep-and-prune), EXPLICIT (precomputed pairs)

• Mesh-mesh collision via SDF with contact reduction

• Optional hydroelastic contact model for compliant surfaces

For more details, see the Newton collision pipeline guide and CollisionPipeline API.

Attributes:

broad_phase	Broad phase algorithm for collision detection.
reduce_contacts	Whether to reduce contacts for mesh-mesh collisions.
rigid_contact_max	Maximum number of rigid contacts to allocate.
max_triangle_pairs	Maximum number of triangle pairs allocated by narrow phase for mesh and heightfield collisions.
soft_contact_max	Maximum number of soft contacts to allocate.
soft_contact_margin	Margin [m] for soft contact generation.
enable_rigid_soft_full_surface_contact	Whether to generate soft contacts against full-surface-capable rigid colliders.
requires_grad	Whether to enable gradient computation for collision.
sdf_hydroelastic_config	Configuration for SDF-based hydroelastic collision handling.

Methods:

to_pipeline_args()

Build keyword arguments for newton.CollisionPipeline.

broad_phase: Literal['explicit', 'nxn', 'sap']

Broad phase algorithm for collision detection.

Options:

• "explicit": Use precomputed shape pairs from model.shape_contact_pairs.

• "nxn": All-pairs brute force. Simple but O(n^2) complexity.

• "sap": Sweep-and-prune. Good for scenes with many dynamic objects.

Defaults to "explicit" (same as Newton’s default when broad_phase=None).

reduce_contacts: bool

Whether to reduce contacts for mesh-mesh collisions.

When True, uses shared memory contact reduction to select representative contacts. Improves performance and stability for meshes with many vertices.

Defaults to True (same as Newton’s default).

rigid_contact_max: int | None

Maximum number of rigid contacts to allocate.

Resolution order:

1. If provided, use this value.

2. Else if model.rigid_contact_max > 0, use the model value.

3. Else estimate automatically from model shape and pair metadata.

Defaults to None (auto-estimate, same as Newton’s default).

max_triangle_pairs: int | None

Maximum number of triangle pairs allocated by narrow phase for mesh and heightfield collisions.

Also sizes the global contact-reduction buffer and hashtable, which all worlds share. If None, Newton estimates it from the model, so it grows with the number of worlds. Set it explicitly to choose the memory budget, or when overflow warnings appear.

Defaults to None (auto-estimate, same as Newton’s default).

soft_contact_max: int | None

Maximum number of soft contacts to allocate.

If None, computed as shape_count * particle_count.

Defaults to None (auto-compute, same as Newton’s default).

soft_contact_margin: float

Margin [m] for soft contact generation.

Defaults to 0.01 (same as Newton’s default).

enable_rigid_soft_full_surface_contact: bool

Whether to generate soft contacts against full-surface-capable rigid colliders.

When True, Newton adds edge and triangle-interior soft contacts (in addition to the per-vertex particle contacts) so rigid features that pass between soft vertices are caught. Analytic shapes (boxes, capsules, spheres) are full-surface-capable without an SDF; any participating mesh/convex collider must carry a volume SDF.

Defaults to False (same as Newton’s default).

requires_grad: bool | None

Whether to enable gradient computation for collision.

If None, uses model.requires_grad.

Defaults to None (same as Newton’s default).

sdf_hydroelastic_config: HydroelasticSDFCfg | None

Configuration for SDF-based hydroelastic collision handling.

If None, hydroelastic contacts are disabled. If set, enables hydroelastic contacts with the specified parameters.

Defaults to None (hydroelastic disabled, same as Newton’s default).

to_pipeline_args() → dict[str, Any]

Build keyword arguments for newton.CollisionPipeline.

Converts this configuration into the dict expected by CollisionPipeline.__init__, handling nested config conversion (e.g. HydroelasticSDFCfg → HydroelasticSDF.Config).

Returns:

Keyword arguments suitable for CollisionPipeline(model, **args).

class isaaclab_newton.physics.HydroelasticSDFCfg

Bases: object

Configuration for SDF-based hydroelastic collision handling.

Hydroelastic contacts generate distributed contact areas instead of point contacts, providing more realistic force distribution for manipulation and compliant surfaces.

For more details, see the Newton hydroelastic contacts guide.

Attributes:

reduce_contacts	Whether to reduce contacts to a smaller representative set per shape pair.
buffer_fraction	(0, 1].
normal_matching	Whether to rotate reduced contact normals to align with aggregate force direction.
anchor_contact	Whether to add an anchor contact at the center of pressure for each normal bin.
margin_contact_area	Contact area [m^2] used for non-penetrating contacts at the margin.
output_contact_surface	Whether to output hydroelastic contact surface vertices for visualization.

reduce_contacts: bool

Whether to reduce contacts to a smaller representative set per shape pair.

When False, all generated contacts are passed through without reduction.

Defaults to True (same as Newton’s default).

buffer_fraction: float

(0, 1].

Lower values reduce memory usage but may cause overflows in dense scenes. Overflows are bounds-safe and emit warnings; increase this value when warnings appear.

Defaults to 1.0 (same as Newton’s default).

Type:

Fraction of worst-case hydroelastic buffer allocations. Range

normal_matching: bool

Whether to rotate reduced contact normals to align with aggregate force direction.

Only active when reduce_contacts is True.

Defaults to True (same as Newton’s default).

anchor_contact: bool

Whether to add an anchor contact at the center of pressure for each normal bin.

The anchor contact helps preserve moment balance. Only active when reduce_contacts is True.

Defaults to False (same as Newton’s default).

margin_contact_area: float

Contact area [m^2] used for non-penetrating contacts at the margin.

Defaults to 0.01 (same as Newton’s default).

output_contact_surface: bool

Whether to output hydroelastic contact surface vertices for visualization.

Defaults to False (same as Newton’s default).

class isaaclab_newton.physics.NewtonShapeCfg

Bases: object

Default per-shape collision properties applied to all shapes in a Newton scene.

Mirrors Newton’s ModelBuilder.default_shape_cfg. Fields that Isaac Lab overrides or exposes for user overrides are declared here; fields not represented keep Newton’s upstream defaults. The struct is forwarded onto Newton’s upstream ShapeConfig via checked_apply() at builder construction.

Attributes:

margin	Default per-shape collision margin [m].
gap	Default per-shape contact gap [m].
ke	Default per-shape normal contact stiffness [N/m].
kd	Default per-shape normal contact damping [N*s/m].
mu	Default per-shape friction coefficient [dimensionless].

margin: float

Default per-shape collision margin [m].

A nonzero margin (e.g. 0.01) is required for stable contact on triangle-mesh terrain — without it, lightweight robots fail to learn rough-terrain locomotion on Newton. Newton’s upstream default is 0.0.

gap: float

Default per-shape contact gap [m]. Newton’s upstream default is None.

ke: float

Default per-shape normal contact stiffness [N/m].

Applied to shapes that lack an explicit material; per-asset materials override it. Mirrors Newton’s ShapeConfig.ke default.

kd: float

Default per-shape normal contact damping [N*s/m].

Applied to shapes that lack an explicit material; per-asset materials override it. Mirrors Newton’s ShapeConfig.kd default.

mu: float

Default per-shape friction coefficient [dimensionless].

Applied to shapes that lack an explicit material; per-asset materials override it. Mirrors Newton’s ShapeConfig.mu default.

MPM Solver State

isaaclab_newton.physics.reset_mpm_solver_state(backend: NewtonBackend, state: State | None = None, world_mask: wp.array(dtype=wp.bool) | None = None, flags: StateFlags | int | None = None) → None

Reset MPM and coupled-solver history after task state is rewritten.

When state is omitted, both distinct backend state buffers are reset so a later buffer swap cannot restore stale history. A mask follows Newton’s canonical world_count + 1 contract, where the last entry selects global entities in world -1. A selected single local world is promoted to a full reset because a one-world MPM grid has no environment offsets.

Parameters:

• backend – Backend whose solver to reset, e.g. NewtonManager.backend.

• state – State whose solver-owned history should be reset. If omitted, reset both backend states.

• world_mask – Canonical per-world mask, including the final global-world entry.

• flags – State components whose solver-owned history should reset.

Raises:

• RuntimeError – If the MPM solver or a usable state is not initialized.

• ValueError – If world_mask does not use Newton’s canonical shape.