newton.solvers.SolverVBD#

class newton.solvers.SolverVBD(model, *, iterations=10, friction_epsilon=1e-2, integrate_with_external_rigid_solver=False, particle_enable_self_contact=False, particle_self_contact_radius=0.2, particle_self_contact_margin=0.2, particle_conservative_bound_relaxation=0.85, particle_vertex_contact_buffer_size=32, particle_edge_contact_buffer_size=64, particle_collision_detection_interval=0, particle_edge_parallel_epsilon=1e-5, particle_enable_tile_solve=True, particle_topological_contact_filter_threshold=2, particle_rest_shape_contact_exclusion_radius=0.0, particle_external_vertex_contact_filtering_map=None, particle_external_edge_contact_filtering_map=None, rigid_avbd_alpha=0.95, rigid_avbd_joint_alpha=None, rigid_avbd_contact_alpha=None, rigid_avbd_beta=0.0, rigid_avbd_linear_beta=None, rigid_avbd_angular_beta=None, rigid_avbd_gamma=0.999, rigid_contact_hard=True, rigid_contact_history=False, rigid_contact_stick_motion_eps=1.0e-4, rigid_contact_stick_freeze_translation_eps=1.0e-4, rigid_contact_stick_freeze_angular_eps=1.0e-4, rigid_contact_k_start=1.0e2, rigid_body_contact_buffer_size=64, rigid_body_particle_contact_buffer_size=256, rigid_joint_linear_ke=1.0e5, rigid_joint_angular_ke=1.0e5, rigid_joint_linear_k_start=1.0e2, rigid_joint_angular_k_start=1.0e1, rigid_joint_linear_kd=0.0, rigid_joint_angular_kd=0.0, deterministic=None)[source]#

Bases: SolverBase, CouplingInterface

An implicit solver using Vertex Block Descent (VBD) for particles and Augmented VBD (AVBD) for rigid bodies.

Experimental

SolverVBD’s public API and behavior may change without prior notice.

This unified solver supports:

  • Particle simulation (cloth, soft bodies) using the VBD algorithm

  • Rigid body simulation (joints, contacts) using the AVBD algorithm

  • Coupled particle-rigid body systems

For rigid bodies, the AVBD algorithm uses penalty stiffness that is fixed by default (rigid_avbd_beta=0) or ramped per iteration from k_start seeds by the AVBD beta parameters. Hard contacts and hard joint slots additionally use augmented-Lagrangian state.

Non-cable structural joint slots default to hard mode (augmented Lagrangian with persistent lambda and C0 stabilization). Cable stretch and bend default to soft mode. Joint hard/soft mode is initialized from the optional model.vbd.joint_is_hard custom attribute; author values at joint creation, before constructing the solver. The hard/soft mode can also be changed per slot at runtime via set_joint_constraint_mode().

Joint limitations:

See Joint Feature Support for the full comparison across solvers.

Buffer sizing:

SolverVBD pre-allocates contact state from capacities populated by CollisionPipeline when available; otherwise, the first step() lazily sizes buffers from Contacts. During CUDA graph recording, ordinary lazy resizing is supported only when Warp’s memory pool is enabled; otherwise, the solver raises with guidance to pre-size before capture. Rigid contact history must be allocated before capture regardless of memory-pool support. With rigid_contact_history=True, construct CollisionPipeline before SolverVBD, or run one uncaptured solver step before capture.

References

  • Anka He Chen, Ziheng Liu, Yin Yang, and Cem Yuksel. 2024. Vertex Block Descent. ACM Trans. Graph. 43, 4, Article 116 (July 2024), 16 pages. https://doi.org/10.1145/3658179

  • Chris Giles, Elie Diaz, and Cem Yuksel. 2025. Augmented Vertex Block Descent. ACM Trans. Graph. 44, 4, Article 90 (August 2025), 12 pages. https://doi.org/10.1145/3731195

Note

SolverVBD requires coloring for each system it solves:

Call newton.ModelBuilder.color() to automatically color both particles and rigid bodies.

VBD uses model.body_q as the structural rest pose and reads model.joint_q for drive/limit rest-angle offsets. The body transforms must match the joint angles at solver creation time (see example below).

Example

# Automatically color both particles and rigid bodies
builder.color()

model = builder.finalize()

solver = newton.solvers.SolverVBD(model)

# Initialize states and contacts
state_in = model.state()
state_out = model.state()
control = model.control()
contacts = model.contacts()

# Simulation loop
for i in range(100):
    model.collide(state_in, contacts)  # Update contacts
    solver.step(state_in, state_out, control, contacts, dt)
    state_in, state_out = state_out, state_in
class JointSlot#

Bases: object

Named constraint slot indices for set_joint_constraint_mode().

The first two solver constraint slots are structural where present:

  • CABLE: LINEAR/STRETCH -> stretch, ANGULAR/BEND -> bend

  • BALL: LINEAR only

  • FIXED/REVOLUTE/PRISMATIC/D6: LINEAR and ANGULAR

Drive/limit slots start at slot 2 and are not represented here. STRETCH and BEND are cable-only aliases for LINEAR and ANGULAR.

ANGULAR = 1#
BEND = 1#
LINEAR = 0#
STRETCH = 0#
classmethod register_custom_attributes(builder, *, dahl_defaults_enabled=True)#

Register SolverVBD custom Model attributes.

Currently registers:

  • vbd:joint_is_hard for per-joint hard/soft constraint mode

  • vbd:dahl_eps_max and vbd:dahl_tau for optional Dahl cable friction

Attributes are declared in the vbd namespace so they can be authored in scenes and in USD as newton:vbd:<attr>.

Parameters:

  • builder (ModelBuilder) – Model builder to register attributes on.

  • dahl_defaults_enabled (bool) – Deprecated compatibility mode. When True, Dahl parameters default to positive values. Prefer passing False and explicitly authoring positive Dahl values only when Dahl cable friction is desired.

__init__(model, *, iterations=10, friction_epsilon=1e-2, integrate_with_external_rigid_solver=False, particle_enable_self_contact=False, particle_self_contact_radius=0.2, particle_self_contact_margin=0.2, particle_conservative_bound_relaxation=0.85, particle_vertex_contact_buffer_size=32, particle_edge_contact_buffer_size=64, particle_collision_detection_interval=0, particle_edge_parallel_epsilon=1e-5, particle_enable_tile_solve=True, particle_topological_contact_filter_threshold=2, particle_rest_shape_contact_exclusion_radius=0.0, particle_external_vertex_contact_filtering_map=None, particle_external_edge_contact_filtering_map=None, rigid_avbd_alpha=0.95, rigid_avbd_joint_alpha=None, rigid_avbd_contact_alpha=None, rigid_avbd_beta=0.0, rigid_avbd_linear_beta=None, rigid_avbd_angular_beta=None, rigid_avbd_gamma=0.999, rigid_contact_hard=True, rigid_contact_history=False, rigid_contact_stick_motion_eps=1.0e-4, rigid_contact_stick_freeze_translation_eps=1.0e-4, rigid_contact_stick_freeze_angular_eps=1.0e-4, rigid_contact_k_start=1.0e2, rigid_body_contact_buffer_size=64, rigid_body_particle_contact_buffer_size=256, rigid_joint_linear_ke=1.0e5, rigid_joint_angular_ke=1.0e5, rigid_joint_linear_k_start=1.0e2, rigid_joint_angular_k_start=1.0e1, rigid_joint_linear_kd=0.0, rigid_joint_angular_kd=0.0, deterministic=None)#
Parameters:

  • model (Model) – The Model object used to initialize the integrator. Must be identical to the Model object passed to the step function.

  • parameters (Rigid body)

  • iterations (int) – Number of VBD iterations per step.

  • friction_epsilon (float) – Threshold to smooth small relative velocities in friction computation (used for both particle and rigid body contacts).

  • integrate_with_external_rigid_solver (bool) – Indicator for coupled rigid body-cloth simulation. When set to True, the solver assumes rigid bodies are integrated by an external solver (one-way coupling).

  • parameters

  • particle_enable_self_contact (bool) – Whether to enable self-contact detection for particles.

  • particle_self_contact_radius (float) – The radius used for self-contact detection. This is the distance at which vertex-triangle pairs and edge-edge pairs will start to interact with each other.

  • particle_self_contact_margin (float) – The margin used for self-contact detection. This is the distance at which vertex-triangle pairs and edge-edge will be considered in contact generation. It should be larger than particle_self_contact_radius to avoid missing contacts.

  • particle_conservative_bound_relaxation (float) – Relaxation factor for conservative penetration-free projection.

  • particle_vertex_contact_buffer_size (int) – Preallocation size for each vertex’s vertex-triangle collision buffer.

  • particle_edge_contact_buffer_size (int) – Preallocation size for edge’s edge-edge collision buffer.

  • particle_collision_detection_interval (int) – Controls how frequently particle self-contact detection is applied during the simulation. If set to a value < 0, collision detection is only performed once before the initialization step. If set to 0, collision detection is applied twice: once before and once immediately after initialization. If set to a value n >= 1, collision detection is applied before every n VBD iterations.

  • particle_edge_parallel_epsilon (float) – Threshold to detect near-parallel edges in edge-edge collision handling.

  • particle_enable_tile_solve (bool) – Whether to accelerate the particle solver using tile API.

  • particle_topological_contact_filter_threshold (int) – Maximum topological distance (measured in rings) under which candidate self-contacts are discarded. Set to a higher value to tolerate contacts between more closely connected mesh elements. Only used when particle_enable_self_contact is True. Note that setting this to a value larger than 3 will result in a significant increase in computation time.

  • particle_rest_shape_contact_exclusion_radius (float) – Additional world-space distance threshold for filtering topologically close primitives. Candidate contacts with a rest separation shorter than this value are ignored. The distance is evaluated in the rest configuration conveyed by model.particle_q. Only used when particle_enable_self_contact is True.

  • particle_external_vertex_contact_filtering_map (dict | None) – Optional dictionary used to exclude additional vertex-triangle pairs during contact generation. Keys must be vertex primitive ids (integers), and each value must be a list or set containing the triangle primitives to be filtered out. Only used when particle_enable_self_contact is True.

  • particle_external_edge_contact_filtering_map (dict | None) – Optional dictionary used to exclude additional edge-edge pairs during contact generation. Keys must be edge primitive ids (integers), and each value must be a list or set containing the edges to be filtered out. Only used when particle_enable_self_contact is True.

  • parameters

  • rigid_avbd_alpha (float) – C0 stabilization strength (C_stab = C - alpha * C0). Range: [0, 1]. Used as the default alpha for joints and body-body contacts.

  • rigid_avbd_joint_alpha (float | None) – Joint-specific alpha override. None (default) uses rigid_avbd_alpha.

  • rigid_avbd_contact_alpha (float | None) – Body-body contact alpha override. None (default) uses rigid_avbd_alpha. For hard contacts, lower values (e.g., 0.0) correct more current penetration each step and can give stronger repulsion when iteration count is low or contact history is disabled. Larger values can improve stability with enough iterations or contact history, but may feel weak with few iterations and no history.

  • rigid_avbd_beta (float) – Penalty ramp rate per AVBD iteration. 0 (default) disables ramping (fixed-k). Set to e.g. 1e5 for ramping. Used for both linear and angular constraints unless overridden. Note: linear (meters) and angular (radians) constraints have different units, so the overrides should be used for production tuning.

  • rigid_avbd_linear_beta (float | None) – Linear beta override for linear constraints (meters). None (default) uses rigid_avbd_beta.

  • rigid_avbd_angular_beta (float | None) – Angular beta override for angular constraints (radians). None (default) uses rigid_avbd_beta.

  • rigid_avbd_gamma (float) – Per-step decay factor for penalty k and persisted hard-mode lambda. Hard joint/contact lambda is additionally scaled by the corresponding alpha during warm-starting, following the AVBD reference scheme. Lower values decay faster, improving stability at the cost of slower convergence.

  • rigid_contact_hard (bool) – Whether body-body rigid contacts use hard mode (augmented Lagrangian with persistent lambda and C0 stabilization) or soft mode (penalty only).

  • rigid_contact_history (bool) – Whether to persist body-body contact state across steps using Contacts.rigid_contact_match_index from the collision pipeline. For hard contacts, restores lambda, penalty k, and sticky contact anchors; C0 is recomputed each step. For soft contacts, only restored penalty k affects the solve (useful with ramping). Requires contacts with rigid_contact_match_index populated; use CollisionPipeline(contact_matching="latest") for VBD warm-starting. Ignored when integrate_with_external_rigid_solver=True or model.body_count == 0. For CUDA graph capture, construct CollisionPipeline before SolverVBD so history is pre-allocated, or run one uncaptured solver step before capture.

  • rigid_contact_stick_motion_eps (float) – Tangential contact residual threshold for marking hard body-body contacts as sticking. Sticking contacts may replay contact points when rigid_contact_history=True; dynamic-dynamic sticking contacts may also use the body-level deadzone snap. Set to 0.0 to disable sticky flags while preserving lambda and penalty warm-starting.

  • rigid_contact_stick_freeze_translation_eps (float) – World-space translation threshold for the body-level deadzone snap on dynamic-dynamic sticking contacts. Set to 0.0 to disable translation snapping.

  • rigid_contact_stick_freeze_angular_eps (float) – Angular threshold [rad] for the body-level deadzone snap on dynamic-dynamic sticking contacts. Set to 0.0 to disable angular snapping.

  • rigid_contact_k_start (float) – Body-body and body-particle contact penalty seed for AVBD ramping. Used when rigid_avbd_linear_beta (or rigid_avbd_beta fallback) is greater than zero. When the linear beta is 0, k is fixed at the contact stiffness regardless of this value.

  • rigid_body_contact_buffer_size (int) – Max body-body contacts per rigid body for per-body contact lists.

  • rigid_body_particle_contact_buffer_size (int) – Max body-particle soft contacts tracked per rigid body, covering both particle-vs-surface and full-surface edge/face contacts.

  • rigid_joint_linear_ke (float) – Penalty stiffness ceiling for non-cable structural linear joint slots.

  • rigid_joint_angular_ke (float) – Penalty stiffness ceiling for non-cable structural angular joint slots.

  • rigid_joint_linear_k_start (float) – Linear penalty seed for AVBD ramping. Used when rigid_avbd_linear_beta (or rigid_avbd_beta fallback) is greater than zero. When the linear beta is 0, k is fixed at the joint stiffness regardless of this value.

  • rigid_joint_angular_k_start (float) – Angular penalty seed for AVBD ramping. Used when rigid_avbd_angular_beta (or rigid_avbd_beta fallback) is greater than zero. When the angular beta is 0, k is fixed at the joint stiffness regardless of this value.

  • rigid_joint_linear_kd (float) – Damping coefficient for non-cable linear joint constraints [N·s/m]. Negative values are clamped to 0.

  • rigid_joint_angular_kd (float) – Damping coefficient for non-cable angular joint constraints [N·m·s/rad]. Negative values are clamped to 0.

  • deterministic (DeterministicMode | None) – Opt-in determinism for this solver’s atomic-emitting kernel modules. Pass a warp.DeterministicMode, or None (default) to inherit the current wp.config.deterministic mode.

Note

  • The integrate_with_external_rigid_solver argument enables one-way coupling between rigid body and soft body solvers. If set to True, the rigid states should be integrated externally, with state_in passed to step representing the previous rigid state and state_out representing the current one. Frictional forces are computed accordingly.

  • particle_vertex_contact_buffer_size, particle_edge_contact_buffer_size, rigid_body_contact_buffer_size, and rigid_body_particle_contact_buffer_size are fixed and will not be dynamically resized during runtime. Setting them too small may result in undetected collisions (particles) or contact overflow (rigid body contacts). Setting them excessively large may increase memory usage and degrade performance.

  • Dahl hysteresis friction for cable bending is controlled by custom model attributes model.vbd.dahl_eps_max and model.vbd.dahl_tau. Register them with SolverVBD.register_custom_attributes before building the model. Dahl friction is enabled only when positive Dahl parameters are authored.

collect_rigid_contact_forces(body_q, body_q_prev, contacts, dt)#

Collect per-contact rigid contact forces and world-space application points.

Parameters:

  • body_q (wp.array(dtype=wp.transformf, ndim=1)) – Current body transforms (world frame), typically state_out.body_q after a step() call.

  • body_q_prev (wp.array(dtype=wp.transformf, ndim=1)) – Effective previous-pose history used by the step (world frame). Snapshot solver.body_q_prev before step() (it is advanced after the step). On a first or reset step, overwrite each rebaselined row with that step’s input body_q so its reported force matches the solve. For externally integrated bodies, pass the external solver’s previous transforms.

  • contacts (Contacts | None) – Contact data buffers containing rigid contact geometry/material references. If None, the function returns default zero/sentinel outputs.

  • dt (float) – Time step size [s].

Note

Call after collision generation and step() with the same Contacts buffer. If rigid contact state is absent or undersized, this returns sentinel/zero outputs without growing output buffers. Output buffers persist and grow on demand; they do not shrink, so iterate up to the returned rigid_contact_count rather than the array length.

Returns:

tuple[

wp.array[wp.int32], wp.array[wp.int32], wp.array[wp.vec3], wp.array[wp.vec3], wp.array[wp.vec3], wp.array[wp.int32],

]: Tuple of per-contact outputs:

  • body0: Body index for shape0, int32.

  • body1: Body index for shape1, int32.

  • point0_world: World-space contact point on body0, wp.vec3 [m].

  • point1_world: World-space contact point on body1, wp.vec3 [m].

  • force_on_body1: Contact force applied to body1 in world frame, wp.vec3 [N].

  • rigid_contact_count: Length-1 active rigid-contact count, int32.

Return type:

tuple[wp.array(dtype=wp.int32, ndim=1), wp.array(dtype=wp.int32, ndim=1), wp.array(dtype=wp.vec3f, ndim=1), wp.array(dtype=wp.vec3f, ndim=1), wp.array(dtype=wp.vec3f, ndim=1), wp.array(dtype=wp.int32, ndim=1)]

coupling_harvest_proxy_particle_forces(particle_local_to_proxy_global, out_particle_f, *, particle_qd_before, state, state_out, contacts, dt)#

Harvest contact-only proxy-particle forces.

As for proxy-body harvest, this stays contact-based because VBD allows some proxy interaction inside the destination solve for stronger coupling, but those proxy-only interactions should not appear as feedback forces on the source side.

coupling_harvest_proxy_wrenches(body_local_to_proxy_global, out_body_f, *, body_qd_before, state, state_out, contacts, dt)#

Harvest contact-only proxy-body wrenches.

VBD deliberately does not rely on the default momentum harvest here. The generic proxy path filters proxy-vs-proxy and proxy-vs-static rigid contacts so harvested momentum only reflects coupling-relevant interactions. VBD relaxes that restriction because allowing some proxy interaction inside the destination solve can strengthen the coupled solve. Those extra interactions still must not feed back through the coupling interface, so VBD harvests explicit contact forces instead of inferring feedback from total proxy momentum change.

coupling_notify_input_state_update(state, flags, *, iteration_restart=False, dt=0.0)#

Convert input body pose updates into VBD-compatible history updates.

coupling_prepare_proxy_contacts(state, contacts, *, contacts_freshly_detected=False)#

Update rigid history cadence for proxy contacts.

coupling_supports_inertial_property_refresh()#
notify_model_changed(flags)#
rebuild_bvh(state)#

This function will rebuild the BVHs used for detecting self-contacts using the input state.

When the simulated object deforms significantly, simply refitting the BVH can lead to deterioration of the BVH’s quality. In these cases, rebuilding the entire tree is necessary to achieve better querying efficiency.

Parameters:

state (newton.State) – The state whose particle positions (particle_q) will be used for rebuilding the BVHs.

reset(state, world_mask=None, flags=None)#

Reset rigid solver history and optional body state for selected worlds.

Body fields selected by flags are copied from the model defaults. Joint penalty is restored to its minimum; joint C0 and AVBD dual history is zeroed immediately. Pose and enabled-cable friction history (curvature, stress, and increment) are rebaselined together from the next step() input pose, after any intervening state edits or forward kinematics. Selected-world contact warm-start is cold-started when fresh rigid contacts are next processed. Internal rigid history is reset regardless of flags. When an external solver integrates the bodies, reset performs no rigid mutation; state and world_mask validation and particle warnings still apply, but body State arrays are not accessed or validated.

BODY_Q / BODY_QD copy model.body_q / model.body_qd into state; they do not restore a previously supplied state. A requested field is skipped if its state array is None. If your initial pose differs from the model defaults, pass flags=0 and author the pose any time before the next step; reset then preserves it and only clears VBD history. JOINT_Q / JOINT_QD are ignored (VBD uses maximal body_q / body_qd); to reset from joint coordinates, run eval_fk() after reset so the resulting body_q supersedes reset’s model copy. Particle flags are unsupported and warn only if the model contains particles (flags=None means ALL); particle and body-particle history is unchanged.

Reset does not run collision detection: after moving bodies, regenerate contacts and let the next step() refresh rigid contact state. The next rigid step() consumes the pose and cable rebaseline even when contacts=None, so author the final pose (or run eval_fk()) before stepping; contact invalidation instead waits for a fresh refresh. With rigid_contact_history=True, only contact_matching="latest" is supported; VBD cannot invalidate sticky matcher state owned by the collision pipeline. Reset does not change set_rigid_history_update(); leave rigid-history refresh enabled for the next contact-bearing step. Reusing contacts (set_rigid_history_update(False)) is unsupported only while contact invalidation is still pending.

Parameters:

  • state (newton.State) – The simulation state to reset (modified in place).

  • world_mask (wp.array(dtype=wp.bool, ndim=1) | None) – One-dimensional Warp boolean mask on the solver device. Shape (world_count,) selects local worlds only. Shape (world_count + 1,) additionally uses the final entry for entities not assigned to a world (world == -1). None selects all local and unassigned entities.

  • flags (StateFlags | int | None) – StateFlags (or int) selecting which body fields to copy from the model defaults. VBD honors BODY_Q and BODY_QD; None requests all flags.

set_joint_constraint_mode(joint_index, hard, slot=None)#

Set hard or soft constraint mode for a joint’s structural slots at runtime.

Hard mode (augmented Lagrangian): uses persistent lambda + C0 stabilization to drive constraint violation toward zero across iterations. Soft mode (penalty-only): uses penalty stiffness only (no lambda or C0 state).

Structural slots are LINEAR (slot 0) and ANGULAR (slot 1). Drive/limit slots (slot 2+) are always soft and cannot be set to hard.

By default, cable stretch and bend slots are soft, while non-cable structural slots are hard.

Hard/soft mode can also be authored per joint at build time via the vbd:joint_is_hard custom attribute, avoiding a runtime set_joint_constraint_mode() call:

SolverVBD.register_custom_attributes(builder, dahl_defaults_enabled=False)  # before adding joints
builder.add_joint_fixed(..., custom_attributes={"vbd:joint_is_hard": 0})
model = builder.finalize()
solver = SolverVBD(model, ...)
Parameters:

  • joint_index (int) – Index of the joint to modify.

  • hard (bool) – True for hard mode (AL), False for soft mode (penalty-only).

  • slot (int | None) – Specific slot index to set. If None, sets all structural slots. Use JointSlot.LINEAR / JointSlot.ANGULAR (equivalently JointSlot.STRETCH / JointSlot.BEND for cables).

Raises:

ValueError – If the joint index is out of range, or the slot is a drive/limit slot (>= 2), or the slot exceeds the joint’s constraint dimension.

set_rigid_history_update(update)#

Set whether the next step() should update rigid solver history.

When True (default), the step refreshes rigid contact state from the provided Contacts buffer: rebuilds per-body contact lists, initializes penalty_k/lambda/C0, and restores warm-start state from Contacts.rigid_contact_match_index when contact history is enabled. When False, the step reuses the current rigid contact lists and contact state. In that mode, the caller must pass the same contact result/buffers used by the previous refresh; do not run collision into the contacts buffer between refreshes. Passing newly collided contacts while update is disabled can mismatch stale per-body contact lists with current contact rows. For the same reason, do not change a body’s solvability (mass or kinematic flag) while update is disabled: the per-body lists depend on effective inverse mass and are not rebuilt until the next refresh.

Joint AVBD maintenance (C0 snapshot, lambda decay) runs every step regardless of this flag via step_joint_C0_lambda(). Rigid contact history snapshotting also runs every step when enabled.

This setting applies only to the next call to step() and is then reset to True. Useful for substepping where collision detection frequency differs from the simulation step frequency.

Parameters:

update (bool) – If True, update rigid solver state. If False, reuse previous.

step(state_in, state_out, control, contacts, dt)#

Execute one simulation timestep using VBD (particles) and AVBD (rigid bodies).

The solver follows a 3-phase structure: 1. Initialize: Forward integrate particles and rigid bodies, detect collisions, initialize contact state 2. Iterate: Interleave particle VBD iterations and rigid body AVBD iterations 3. Finalize: Update velocities and persistent state (Dahl friction)

To control rigid body substepping behavior, call set_rigid_history_update(). When True (default), the step rebuilds rigid contact lists, re-initializes rigid contact state (penalty_k, lambda, C0), and restores from history if enabled. When False, reuses previous rigid contact state. The flag is reset to True when consumed.

Parameters:

  • state_in (newton.State) – Input state.

  • state_out (newton.State) – Output state.

  • control (Control) – Control inputs.

  • contacts (Contacts | None) – Contact data produced by collide() (rigid-rigid and rigid-particle contacts). If None, rigid contact handling is skipped. Note that particle self-contact (if enabled) does not depend on this argument.

  • dt (float) – Time step size.

Raises:

RuntimeError – If required rigid contact-matching data is unavailable, or contact-history storage would need to be allocated or grown during CUDA graph capture.