novaphy.solvers.SolverFeatherstone¶

Articulated-body solver using forward kinematics, RNEA bias forces, a CRBA mass matrix, and a Cholesky solve in reduced coordinates. The recommended backend for robots, kinematic chains, pendulums, and tree-structured multibody systems.

Pipeline¶

graph LR
    A[Forward<br/>kinematics] --> B[RNEA<br/>bias forces]
    B --> C[CRBA<br/>mass matrix]
    C --> D[Cholesky<br/>solve]
    D --> E[Integrate]

Algorithms:

Forward Kinematics (FK) computes link transforms from joint_q.
Recursive Newton-Euler (RNEA) computes bias forces (Coriolis + gravity
applied wrenches).
CRBA assembles the joint-space mass matrix H(q).
Cholesky solve produces qdd from H qdd = tau - bias.
Semi-implicit integration on q / qd with quaternion renormalization for Free / Ball joints.

Supplied rigid contacts are enforced by the multibody Sequential Impulse PGS tail. Joint limits are handled separately in the reduced-coordinate generalized-force path before integration.

Constructor¶

config = novaphy.solvers.SolverFeatherstone.Config()
solver = novaphy.solvers.SolverFeatherstone(model, config)

Parameter	Description
`model`	Required. `Model` containing at least one articulation.
`config`	Optional SolverFeatherstoneConfig. If omitted, `SolverFeatherstone.Config()` is used.

SolverFeatherstone.Config is the Python-facing alias for the C++ SolverFeatherstoneConfig pybind type.

Post-Construction Tuning¶

Tune configuration before construction or through solver.settings after construction:

`solver.settings.<field>`	Type	Description
`angular_damping`	`float`	Angular damping coefficient.
`update_mass_matrix_interval`	`int`	Mass-matrix rebuild cadence.
`substeps`	`int`	Integration substeps per call.
`integrate_particles`	`bool`	On CPU, advance particles too; disable when an external soft-body solver owns particle integration.
`pgs_iterations`	`int`	Velocity-level PGS contact iterations when contacts are supplied.
`pgs_baumgarte`	`float`	Baumgarte stabilization for contact correction.
`pgs_slop`	`float`	Penetration slop tolerance.
`pgs_cfm`	`float`	Constraint force mixing.
`pgs_restitution_threshold`	`float`	Velocity below this skips restitution.
`pgs_warm_start`	`bool`	Enable warm-starting.
`pgs_split_impulse`	`bool`	Enable split impulse correction.

solver = novaphy.solvers.SolverFeatherstone(model)
solver.settings.pgs_iterations = 50
solver.settings.pgs_slop = 0.001

Joint Support¶

SolverFeatherstone supports reduced-coordinate joints:

Joint	DOF	Notes
`Revolute`	1	Rotation around an axis.
`Prismatic`	1	Translation along an axis.
`Ball`	3	Spherical joint (3 rotational DOFs, quaternion state).
`Fixed`	0	Rigid attachment.
`Free`	6	Floating base (3 translation + quaternion).

Distance, D6, and Cable are maximal-coordinate constraint types; use solver.joint_support() to check whether a backend enforces them.

Query solver.joint_support() for the runtime JointSupportMatrix.

Example¶

import numpy as np
import novaphy

builder = novaphy.ModelBuilder()
builder.add_ground_plane(y=0.0)

# Add a single-link revolute pendulum.
body_idx = builder.add_link(
    xform=novaphy.Transform.from_translation(
        np.array([0.0, 1.0, 0.0], dtype=np.float32)
    ),
    mass=1.0,
    inertia=np.diag(np.array([0.1, 0.02, 0.1], dtype=np.float32)),
    lock_inertia=True,
)
builder.add_shape_box(
    body_idx,
    hx=0.1,
    hy=0.5,
    hz=0.1,
    cfg=novaphy.ShapeConfig(density=0.0),
)
joint_idx = builder.add_joint_revolute(
    parent=-1,
    child=body_idx,
    axis=np.array([0.0, 0.0, 1.0], dtype=np.float32),
)
builder.add_articulation([joint_idx])

model = builder.finalize()
config = novaphy.solvers.SolverFeatherstone.Config()
config.angular_damping = 0.05
config.update_mass_matrix_interval = 1
solver = novaphy.solvers.SolverFeatherstone(model, config)

state    = model.state()
control  = model.control()
pipeline = novaphy.CollisionPipeline(model)
contacts = pipeline.contacts()

for _ in range(1000):
    state.clear_forces()
    pipeline.collide(state, contacts)
    solver.step(state, state, control, contacts, 1.0 / 120.0)

When To Use¶

Scenario	Recommendation
Robots, manipulators, legged systems	Default articulated backend.
Long kinematic chains (ropes, wrecking balls)	Reduced coordinates handle long chains stably.
Free bodies only, no joints	Use SolverSemiImplicit.
Position-level joint constraints with compliance	Use SolverXPBD.

Demos¶

Demo	What it shows
`python/demos/featherstone/demo_fs_pgs_cradle.py`	Newton's cradle with contact.
`python/demos/featherstone/demo_fs_pgs_rope.py`	Articulated rope with PGS contact.
`python/demos/featherstone/demo_fs_pgs_wrecking_ball.py`	Chain pendulum and rigid impact.
`python/demos/featherstone/demo_fs_pgs_seesaw.py`	Revolute seesaw and impact.
`python/demos/featherstone/demo_fs_pgs_motor_arm.py`	Driven articulated arm.