novaphy.solvers

Newton-aligned novaphy.solvers namespace. Solver classes, configuration objects, and solver-metadata enums live exclusively here; there is no novaphy.SolverXXX top-level shortcut.

import novaphy
solver = novaphy.solvers.SolverSemiImplicit(model)
pipeline = novaphy.CollisionPipeline(model)
contacts = pipeline.contacts()
pipeline.collide(state_in, contacts)
solver.step(state_in, state_out, control, contacts, dt)

All solvers share the contract:

solver.step(state_in: SimState, state_out: SimState,
            control: Control | None, contacts: Contacts | None,
            dt: float) -> None

state_in and state_out may alias for in-place stepping. Pass distinct SimState objects when the input buffer must be preserved. For most solvers, collision is explicit: populate contacts with CollisionPipeline.collide before solver.step whenever the step should enforce contacts. SolverIPC instead runs libuipc's internal collision pipeline and ignores the NovaPhy Contacts argument.

Solver Classes

Class	Description
SolverBase	Newton-aligned base contract.
SolverFeatherstone	Articulated-body Featherstone solver.
SolverIPC	IPC / libuipc solver (optional NVIDIA CUDA or CoreX build). May be None when IPC is not built.
SolverLBM	Sparse-block Lattice Boltzmann solver with an optional CUDA numerical backend.
SolverMPM	Material Point Method scaffold. Construction is legal, but step() raises RuntimeError.
SolverMuJoCo	Native MuJoCo-style solver: CPU in the normal build, optional CUDA selected by model device.
SolverPBF	Position Based Fluids solver.
SolverSPH	SPH fluid solver (CUDA-only; requires the optional SPH CUDA build).
SolverSemiImplicit	Free-body semi-implicit Euler + PGS.
SolverVBD	VBD / AVBD primal-dual solver (CPU; optional NVIDIA CUDA or Denglin DLAN).
SolverXPBD	XPBD maximal-coordinate constraint solver.

These entries are Newton-aligned SolverBase subclasses driven by the solver.step(state_in, state_out, control, contacts, dt) contract. SolverMPM is intentionally a non-runnable scaffold. Its backend_info.is_scaffold value is True, and calling step() fails loudly instead of producing placeholder physics:

model = novaphy.ModelBuilder().finalize()
mpm = novaphy.solvers.SolverMPM(model)

assert mpm.backend_info.is_scaffold
assert novaphy.is_scaffold(mpm)
# mpm.step(...) raises RuntimeError: kernels are not implemented.

Use novaphy.scaffold_reason(solver) for a human-readable diagnostic.

SolverLBM is not a scaffold. Its sparse-block fluid state is solver-owned, so backend_info.state_ownership is InternalWorld. The class and configuration are always importable, while numerical operations require a build with NOVAPHY_WITH_LBM_CUDA=ON:

lbm = novaphy.solvers.SolverLBM(model)
assert not lbm.backend_info.is_scaffold
if not lbm.has_cuda_backend:
    raise RuntimeError("Rebuild with NOVAPHY_WITH_LBM_CUDA=ON")

There is no top-level has_lbm_cuda() helper. Use the model-bound solver's read-only has_cuda_backend property.

SolverMuJoCo Backend Selection

SolverMuJoCo is a native implementation rather than an external MuJoCo runtime wrapper. Its backend is selected by model.device, not a constructor keyword:

if not novaphy.has_mujoco_cuda():
    raise RuntimeError("native SolverMuJoCo CUDA backend is unavailable")

model = builder.finalize(device=novaphy.Device.cuda(0))
solver = novaphy.solvers.SolverMuJoCo(model)

The CPU implementation is available in the normal build. Gate CUDA model construction with novaphy.has_mujoco_cuda(); a CUDA model does not silently fall back to CPU when the backend was not built. See the native MuJoCo guide for attribute registration, typed configuration, contacts, and the complete step loop.

Configuration Objects

Class	Description
IPCConfig	IPC solver configuration.
SolverLBM.Config	Sparse-block LBM options; alias of LBMConfig.
PBFConfig	Position Based Fluids configuration.
SolverFeatherstone.Config	Featherstone solver configuration (SolverFeatherstoneConfig).
SolverMPMConfig	Construction-time options for the scaffolded MPM solver.
SolverMuJoCo.Config	Typed native MuJoCo options (SolverMuJoCoConfig); all fields default to None.
SolverSettings	Shared rigid solver settings (semi-implicit / XPBD shared knobs).
SPHConfig	SPH solver configuration.
VBDConfig	SolverVBD configuration.
XPBDSolverSettings	XPBD-specific solver settings.

Enumerations and Metadata

Symbol	Description
JointSupportMatrix	Per-solver joint capability table.
LBMBackendKind	LBM backend selector; the current surface exposes CUDA only.
LBMCreateCriteriaType	Sparse-block activation criterion.
LBMSpreadKernel	Immersed-boundary spread kernel.
SolverBackendInfo	Backend descriptor (device, fixed-dt, etc.).
SolverBackendKind	Backend device classifier.
SolverNotifyFlags	Cache invalidation flags after Model mutation.
SolverStateOwnership	Whether a solver owns its own state.
SPHBackendKind	SPH backend selector; the current surface exposes CUDA only.
VbdBackend	VBD backend selector (CPU / CUDA / DLAN).

SolverMuJoCo also exposes its typed enums as nested attributes:

Symbol	Values / role
SolverMuJoCo.SolverType	CG, NEWTON.
SolverMuJoCo.IntegratorType	EULER, RK4, IMPLICIT, IMPLICIT_FAST.
SolverMuJoCo.ConeType	PYRAMIDAL, ELLIPTIC.
SolverMuJoCo.CtrlSource	Joint-target or direct actuator control source.
SolverMuJoCo.CtrlType	Position, velocity, or general actuator shortcut.
SolverMuJoCo.TrnType	Actuator transmission target type.

Legacy Backend Containers

Current NovaPhy releases do not expose public top-level World-style solver containers. Construct the solver under novaphy.solvers, allocate runtime buffers from the Model, and call solver.step(...) directly.

Old pattern	Replacement
novaphy.World(...)	SolverSemiImplicit, SolverXPBD, or SolverFeatherstone
novaphy.VBDWorld(...)	SolverVBD
novaphy.IPCWorld(...)	SolverIPC, guarded by novaphy.has_ipc()