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=None, rigid_contact_stick_freeze_translation_eps=None, rigid_contact_stick_freeze_angular_eps=None, 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) and are initialized from the optional model.vbd.joint_is_hard custom attribute; author values at joint creation, before constructing the solver. Cable stretch, shear, bend, and twist always initialize to soft mode regardless of joint_is_hard and are switched only at runtime. The hard/soft mode can be changed per slot at runtime via set_joint_constraint_mode() (for both cable and non-cable joints).

Joint limitations:

See Joint Feature Support for the full comparison across solvers.

Buffer sizing:

Body-body contact state is pre-allocated from model.rigid_contact_max when a CollisionPipeline has already published it and this solver owns the rigid system. Body-particle contact state is pre-sized from a world-aware particle-shape pair count, which excludes the enable_rigid_soft_full_surface_contact edge/face headroom. Both grow from Contacts on the first step(), and the rigid contact force outputs grow in collect_rigid_contact_forces(). During graph capture, ordinary lazy resizing is supported on CPU and on CUDA with Warp’s stream-ordered memory pool enabled; otherwise the solver raises with guidance to pre-size before capture. Rigid contact history is cross-replay-persistent state, so it must always be allocated before capture regardless of the device’s allocation-during-capture support – allocating it inside a graph records a wp.zeros fill that wipes the warm-start buffers on every replay. 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).

For CUDA graph capture, the recommended construction order is CollisionPipeline -> Contacts -> SolverVBD, all before capture.

Example

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

model = builder.finalize()

collision_pipeline = newton.CollisionPipeline(model)
contacts = collision_pipeline.contacts()

solver = newton.solvers.SolverVBD(model)

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

# Simulation loop
for i in range(100):
    collision_pipeline.collide(state_in, 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().

Structural constraint slots by joint type:

  • CABLE: STRETCH=0, SHEAR=1, BEND=2, TWIST=3

  • BALL: LINEAR=0 only

  • FIXED/REVOLUTE/PRISMATIC/D6: LINEAR=0, ANGULAR=1

STRETCH/SHEAR/BEND/TWIST are cable-only names for the SolverVBD cable layout emitted by the builder cable APIs. Only structural slots are named here; per-DOF drive/limit slots (slot 2+ on non-cable joints) are not.

ANGULAR = 1#
BEND = 2#
LINEAR = 0#
SHEAR = 1#
STRETCH = 0#
TWIST = 3#
classmethod register_custom_attributes(builder, *, dahl_defaults_enabled=False)#

Register SolverVBD custom Model attributes.

Currently registers:

  • vbd:joint_is_hard for per-joint hard/soft constraint mode (non-cable joints)

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

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

Dahl cable friction is enabled per joint only where both model.vbd.dahl_eps_max and model.vbd.dahl_tau are authored positive; the attributes default to zero.

Parameters:

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

  • dahl_defaults_enabled (bool) –

    Deprecated compatibility mode. When True, Dahl parameters default to positive values instead of zero.

    Deprecated since version 1.5: The compatibility mode will be removed; author positive Dahl values explicitly 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=None, rigid_contact_stick_freeze_translation_eps=None, rigid_contact_stick_freeze_angular_eps=None, 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 numeric contact state across steps using Contacts.rigid_contact_match_index. Hard contacts restore lambda and penalty k; soft contacts restore penalty k only. Contact geometry remains owned by the collision pipeline. Requires CollisionPipeline(contact_matching="latest") or "sticky". Ignored when integrate_with_external_rigid_solver=True or model.body_count == 0. During graph capture, construct the collision pipeline before SolverVBD so history is pre-allocated, or run one uncaptured solver step before capture.

  • rigid_contact_stick_motion_eps (float | None) –

    Deprecated and ignored. SolverVBD no longer classifies contacts as sticking. Use CollisionPipeline(contact_matching="sticky", contact_matching_pos_threshold=...) for persistent contact geometry.

    Deprecated since version 1.5.

  • rigid_contact_stick_freeze_translation_eps (float | None) –

    Deprecated and ignored. The SolverVBD body-level contact deadzone was removed.

    Deprecated since version 1.5.

  • rigid_contact_stick_freeze_angular_eps (float | None) –

    Deprecated and ignored. The SolverVBD body-level contact deadzone was removed.

    Deprecated since version 1.5.

  • 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 angular response 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[wp.transformf]) – Current body transforms (world frame), typically state_out.body_q after a step() call.

  • body_q_prev (wp.array[wp.transformf]) – 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[wp.int32], wp.array[wp.int32], wp.array[wp.vec3f], wp.array[wp.vec3f], wp.array[wp.vec3f], wp.array[wp.int32]]

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_full_surface_soft_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 and particle 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 reset 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_Q / PARTICLE_QD likewise copy model.particle_q / model.particle_qd into state for particles in the selected worlds, using the same masking as the body fields (world_mask=None also restores global world == -1 particles; an explicit mask restores globals only through its final entry). One path covers both cloth and volumetric (tet) soft bodies, and it runs even when an external solver integrates the bodies or the model has none. A requested particle field is skipped if its state array is None. Particle and body-particle solver history is intentionally left untouched: particle_q_prev is rebaselined from the incoming state at the start of the next step(), self-contact and body-particle contacts rebuild per step, and tet/cloth elasticity is stateless, so no particle history cold-start is required. Reset does not refresh the particle self-contact BVH; the next step() refits it from the incoming positions. After a large reset displacement, call rebuild_bvh() to restore acceleration-structure quality. Both reset and rebuild_bvh() are graph-capturable, so either may run inside a captured episode-reset graph.

Reset does not run collision detection, and step() consumes the supplied contacts rather than rerunning collide(). After moving bodies or particles, regenerate contacts so stale soft contacts are not reused, 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. VBD cold-starts its numeric contact state for reset-selected worlds. Frame-to-frame correspondence and sticky contact geometry remain owned by CollisionPipeline; construct a new pipeline to discard that history after a discontinuous episode reset. 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[wp.bool] | None) –

    One-dimensional Warp boolean mask on the solver device. Shape (world_count + 1,), with the final entry selecting entities in global world -1. None selects all local and global entities.

    Deprecated since version 1.5: Passing a mask with shape (world_count,) is deprecated. Use shape (world_count + 1,) with a final False entry to select local worlds only.

  • flags (StateFlags | int | None) – StateFlags (or int) selecting which body and particle fields to copy from the model defaults. VBD honors BODY_Q, BODY_QD, PARTICLE_Q, and PARTICLE_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.

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

Non-cable structural slots are LINEAR (slot 0) and ANGULAR (slot 1). Builder-created cable joints expose STRETCH (slot 0), SHEAR (slot 1), BEND (slot 2), and TWIST (slot 3). Other drive/limit slots are always soft and cannot be set to hard.

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

For non-cable joints, 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)  # 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 for non-cable joints, or JointSlot.STRETCH / JointSlot.SHEAR / JointSlot.BEND / JointSlot.TWIST for cables.

Raises:

ValueError – If the joint index is out of range or the slot is not a structural slot for this joint.

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, adaptive penalty upkeep) 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), allocated with 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 graph capture.