Add masked particle resets to SolverVBD

[mmichelis]

Description

Add masked deformable (cloth and volumetric soft body) reset support to SolverVBD.reset(), addressing the particle half of #3256 (the rigid half is #3316).

Note

Stacked on #3316 — this branch contains the rigid-reset commits; only the final commit (Fix: Reset particles in VBD solver) belongs to this PR. Review that commit's diff, and merge after #3316 lands.

reset() now honors StateFlags.PARTICLE_Q / StateFlags.PARTICLE_QD: a new reset_particle_state kernel copies model.particle_q / model.particle_qd into the state for particles in worlds selected by world_mask, with the same semantics as the rigid path (world_mask=None also resets global world == -1 particles; an explicit mask excludes them). The particle reset also runs when an external solver integrates the bodies, and for particle-only models.

No solver history plumbing is needed on the particle side: particle_q_prev is rebaselined from the incoming state at the start of every step(), self-contact and body-particle contact buffers are rebuilt per step (init_body_particle_contacts cold-starts body_particle_contact_penalty_k on every contact refresh, with no match-index warm-start path), and tet/cloth elasticity is stateless. Cloth and volumetric deformables therefore share this single reset path. The previous "particle resets are not supported" warning is removed and the docstring documents the particle behavior, including regenerating contacts after moving particles and rebuild_bvh for large displacements with self-contact.

Checklist

• New or existing tests cover these changes
• The documentation is up to date with these changes
• CHANGELOG.md has been updated (if user-facing change)

Test plan

uv run --extra dev -m newton.tests -k particle_reset

• test_particle_reset_state_flags_and_masks: two-world cloth plus a global particle; verifies masked restore of the selected world only, PARTICLE_Q-only / PARTICLE_QD-only / flags=0 selectivity, that an explicit all-true mask excludes global particles while world_mask=None includes them, and that a post-reset step stays finite.
• test_particle_reset_soft_body: two-world tet soft grid; masked restore and post-reset step with tet elasticity.

Tests were verified to fail without the implementation (TDD), pass on CPU and CUDA, and the full VBD suite (60 tests) passes. Pre-commit is clean.

New feature / API change

import warp as wp

import newton

solver = newton.solvers.SolverVBD(model)

# Reset cloth/soft-body particles of selected worlds to the model defaults.
world_mask = wp.array([True, False], dtype=wp.bool)
solver.reset(state, world_mask=world_mask)

# Positions only, keep velocities.
solver.reset(state, world_mask=world_mask, flags=newton.StateFlags.PARTICLE_Q)

Summary by CodeRabbit

• New Features

  • Added reset support for selected worlds, including rigid bodies, cloth, and soft-body particles.
  • Improved warm-start and history handling so resets now rebaseline poses and restore contact/cable state more reliably.

• Bug Fixes

  • Fixed reset behavior to honor per-world masking and state flags.
  • Contact history and cable history now clear or restart correctly after a reset, reducing stale simulation carryover.

• Tests

  • Added regression coverage for rigid, particle, soft-body, and cable reset scenarios.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

Run ID: 37c73b4f-3e49-4210-96e4-5e948795eb33

📥 Commits

Reviewing files that changed from the base of the PR and between 1420fc4 and e4e9152.

📒 Files selected for processing (5)

• CHANGELOG.md
• newton/_src/solvers/vbd/particle_vbd_kernels.py
• newton/_src/solvers/vbd/rigid_vbd_kernels.py
• newton/_src/solvers/vbd/solver_vbd.py
• newton/tests/test_solver_vbd.py

---

📝 Walkthrough

Walkthrough

This PR adds masked reset support to SolverVBD: a new reset_particle_state kernel and a reset_rigid_state/_reset_joint_history kernel path, world-mask helper functions, rebaseline/reset masks threaded through contact init, forward step, and cable Dahl parameter kernels, a public reset() API, tests, and changelog updates.

Changes

Masked reset support for SolverVBD

Layer / File(s)	Summary
Particle reset kernel newton/_src/solvers/vbd/particle_vbd_kernels.py	Adds reset_particle_state kernel copying model default particle q/qd into world state for particles selected via reset_all or particle_world/world_mask.
Rigid reset kernels and helpers newton/_src/solvers/vbd/rigid_vbd_kernels.py	Adds _world_selected/_shape_world_selected/_contact_world_selected helpers and reset_rigid_state/_reset_joint_history kernels resetting body pose/velocity and clearing joint AVBD history for selected worlds.
Forward-step and cable rebaseline newton/_src/solvers/vbd/rigid_vbd_kernels.py	forward_step_rigid_bodies and compute_cable_dahl_parameters gain pose_rebaseline_mask/joint_world inputs to rebaseline body_q_prev and Dahl curvature state for selected worlds; docstrings updated accordingly.
Contact-history reset invalidation newton/_src/solvers/vbd/rigid_vbd_kernels.py	init_body_body_contacts_avbd gains reset-pending/reset-mask and mapping inputs to force cold-start of matched contacts in worlds pending reset.
SolverVBD.reset() API and wiring newton/_src/solvers/vbd/solver_vbd.py	Adds new kernel imports, allocates rebaseline/reset masks, implements reset(state, world_mask, flags) validating inputs and invoking particle/rigid reset kernels, and threads masks through contact init/forward step/cable update calls with consumption logic.
Regression tests and changelog newton/tests/test_solver_vbd.py, CHANGELOG.md	Updates existing tests for new kernel arity, adds new tests for rigid/particle/soft-body/cable reset and contact reset lifecycle/ownership, registers them, and documents reset support in the changelog.

Estimated code review effort: 4 (Complex) | ~75 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant SolverVBD
  participant reset_particle_state
  participant reset_rigid_state
  participant ForwardStep as forward_step_rigid_bodies

  Caller->>SolverVBD: reset(state, world_mask, flags)
  SolverVBD->>SolverVBD: validate state/world_mask/flags
  alt particle flags set
    SolverVBD->>reset_particle_state: copy model_particle_q/qd
  end
  alt owns rigid bodies
    SolverVBD->>reset_rigid_state: reset body pose/vel, mark rebaseline mask, mark contact reset pending
  end
  Caller->>SolverVBD: step()
  SolverVBD->>ForwardStep: forward_step_rigid_bodies(pose_rebaseline_mask)
  ForwardStep-->>SolverVBD: rebaselined body_q_prev
  SolverVBD->>SolverVBD: clear pose_rebaseline_mask

Loading

Possibly related PRs

• newton-physics/newton#2327: Both PRs modify the VBD body–body contact warm-start/history machinery via init_body_body_contacts_avbd, related to this PR's reset-pending handling.
• newton-physics/newton#2754: Both PRs modify VBD rigid contact history initialization/restore in the same init_body_body_contacts_avbd/snapshot pipeline.

Suggested reviewers: jumyungc, eric-heiden, nvtw

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[mmichelis]

Superseded by the stacked PR against the parent branch: jumyungc#1