novaphy.solvers.SolverVBD¶

Vertex Block Descent (VBD) and Augmented VBD (AVBD) primal-dual rigid-body solver, aligned with the Augmented Vertex Block Descent SIGGRAPH 2025 paper. Suitable for stiff stacks, joints under tight constraints, and compliant springs where Sequential Impulse drift becomes visible. For real-time free-body piles use SolverSemiImplicit; for articulated robots in reduced coordinates use SolverFeatherstone.

Supports:

Rigid contacts with Coulomb friction from the caller-provided CollisionPipeline.
Augmented-Lagrangian joints between bodies.
Particle cloth / soft-body constraints on the CPU SolverBase path.

SolverBase API

SolverVBD is exposed as novaphy.solvers.SolverVBD and is driven through solver.step(state_in, state_out, control, contacts, dt). There is no top-level novaphy.VBDWorld container.

Pipeline¶

graph LR
    A[Configured<br/>broadphase] --> B[Shape-aware<br/>narrowphase]
    B --> C[AVBD primal-dual<br/>iterations]
    C --> D[Block-coordinate<br/>descent]
    D --> E[Integrate]

SolverVBD shares the rigid collision pipeline with SolverSemiImplicit. The caller may select explicit, NXN, or SAP broadphase; the shape-aware narrowphase then produces contacts consumed by the AVBD primal-dual iterations.

Backends¶

Backend	Build flag	Notes
CPU	always built	Default.
CUDA	`NOVAPHY_WITH_VBD_CUDA=ON`	GPU-accelerated; experimental. Selected via VbdBackend.
Denglin DLAN	`NOVAPHY_WITH_VBD_DLAN=ON`	CUDA-source compatibility path for Denglin hardware; mutually exclusive with the NVIDIA CUDA option.

Use novaphy.has_vbd_cuda() or novaphy.has_vbd_dlan() before selecting an optional backend. The CPU implementation also contains particle / soft-body constraints, but the packaged python/demos/vbd/demo_vbd_soft.py scene browser currently selects the CUDA backend only.

Constructor¶

Construct SolverVBD from an immutable model and a VBD configuration:

novaphy.solvers.SolverVBD(model: Model, config: VBDConfig | None = None)

Parameter	Description
`model`	Immutable simulation model from `ModelBuilder.finalize()`.
`config`	Optional VBDConfig with iterations, backend, and AVBD penalty / relaxation parameters. The time step is supplied to `step()`.

Example¶

import novaphy

builder = novaphy.ModelBuilder()
builder.add_ground_plane(y=0.0)
# ... add bodies and shapes ...
builder.color()

cfg = novaphy.solvers.VBDConfig()
cfg.iterations = 4
# cfg.backend = novaphy.solvers.VbdBackend.CUDA   # optional GPU backend
dt = 1.0 / 60.0

model = builder.finalize()
solver = novaphy.solvers.SolverVBD(model, cfg)
state = model.state()
control = model.control()
pipeline = novaphy.CollisionPipeline(model)
contacts = pipeline.contacts()

for _ in range(120):
    state.clear_forces()
    pipeline.collide(state, contacts)
    solver.step(state, state, control, contacts, dt)

Demos¶

Demo	Description
`python/demos/vbd/demo_vbd_rigid.py`	CPU rigid contact and supported-joint scenes.
`python/demos/vbd/demo_vbd_soft.py`	CUDA cloth and soft-rigid contact scene browser.