newton.solvers.SolverFeatherstone#

class newton.solvers.SolverFeatherstone(model, *, angular_damping=0.05, update_mass_matrix_interval=1, friction_smoothing=None, use_tile_gemm=False, fuse_cholesky=True, deterministic=None)[source]#

Bases: SolverBase, CouplingInterface

A semi-implicit integrator using symplectic Euler that operates on reduced (also called generalized) coordinates to simulate articulated rigid body dynamics based on Featherstone’s composite rigid body algorithm (CRBA).

See: Featherstone, Roy. Rigid Body Dynamics Algorithms. Springer US, 2014.

Instead of maximal coordinates body_q (rigid body positions) and body_qd (rigid body velocities) as is the case in SolverSemiImplicit and SolverXPBD, SolverFeatherstone uses joint_q and joint_qd to represent the positions and velocities of joints without allowing any redundant degrees of freedom.

After constructing Model and State objects this time-integrator may be used to advance the simulation state forward in time.

Note

Unlike SolverSemiImplicit and SolverXPBD, SolverFeatherstone does not simulate rigid bodies with nonzero mass as floating bodies if they are not connected through any joints. Floating-base systems require an explicit free joint with which the body is connected to the world, see newton.ModelBuilder.add_joint_free().

Semi-implicit time integration is a variational integrator that preserves energy, however it not unconditionally stable, and requires a time-step small enough to support the required stiffness and damping forces.

See: https://en.wikipedia.org/wiki/Semi-implicit_Euler_method

This solver uses the routines from SolverSemiImplicit to simulate particles, cloth, and soft bodies.

Joint limitations:

Supported joint types: PRISMATIC, REVOLUTE, BALL, FIXED, FREE, DISTANCE (treated as FREE), D6. ROD joints are not supported.
joint_armature, joint_limit_ke/joint_limit_kd, joint_target_ke/joint_target_kd, and joint_f are supported.
Position/velocity target tracking (joint_target_q/ joint_target_qd) is applied only to PRISMATIC, REVOLUTE, and D6 joints. For BALL, FREE, and DISTANCE joints the target arrays are read but no drive force is applied.
joint_friction, joint_effort_limit, joint_velocity_limit, joint_enabled, and joint_target_mode are not supported.
Joint-owned mimic relationships are supported for PRISMATIC, REVOLUTE, and D6 joints. Equality constraints and the deprecated sparse mimic constraints are not supported.

See Joint Feature Support for the full comparison across solvers.

Solver observables:

body_parent_f is populated when BODY_PARENT_F is requested from observables(). The reported wrench is the per-body net spatial force from the RNEA backward pass translated to the body’s COM (linear [N] first, torque [N·m] in world frame at the COM), matching the wrench-transmitted-through- the-inbound-joint convention used by SolverMuJoCo’s cfrc_int. In equilibrium this reaction counters all forces acting on the body’s subtree (gravity, contacts, State.body_f, and the net effect of joint_f) by Newton’s third law.

Free-floating roots (bodies whose only inbound joint is FREE) are not special-cased: the same RNEA sum is written, which for such bodies is the residual force balance from the recursion (e.g. contacts vs. gravity in equilibrium, or the gyroscopic v x* (I*v) term during tumbling) rather than a true joint reaction. Treat it as a diagnostic in that case.

Mimic reduction requires every mimic follower and reference to belong to the same assigned articulation. Models with standalone or mixed-membership mimic pairs may be used with maximal-coordinate solvers instead.

Example

solver = newton.solvers.SolverFeatherstone(model)

# simulation loop
for i in range(100):
    solver.step(state_in, state_out, control, contacts, dt)
    state_in, state_out = state_out, state_in

__init__(model, *, angular_damping=0.05, update_mass_matrix_interval=1, friction_smoothing=None, use_tile_gemm=False, fuse_cholesky=True, deterministic=None)#

Parameters:

model (Model) – The model to be simulated.
angular_damping (float) – Angular damping factor. Defaults to 0.05.
update_mass_matrix_interval (int) – How often to update the mass matrix (every n-th time the step() function gets called). The update is also forced on the next step after notify_model_changed() reports body, joint DOF or inertial changes. Both decisions are made on the host when step() runs, so a captured CUDA graph replays the choice made at capture time; use an interval of 1 or recapture after such a notification. Defaults to 1.
friction_smoothing (float | None) –
Deprecated, ignored compatibility argument.

Deprecated since version 1.8: Remove this argument. Shape material kf controls the low-speed friction slope and mu controls the Coulomb limit.
use_tile_gemm (bool) – Whether to use operators from Warp’s Tile API to solve for joint accelerations. A kernel is compiled per distinct articulation size. Defaults to False.
fuse_cholesky (bool) – Whether to fuse the Cholesky decomposition into the inertia matrix evaluation kernel when using the Tile API. Only used if use_tile_gemm is true. Defaults to True.
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.

Raises:

ValueError – If model contains a ROD joint, or active mimic reduction contains a pair outside the same assigned articulation.

notify_model_changed(flags)#

step(state_in, state_out, control, contacts, dt, *, observables=None)#

SUPPORTED_OBSERVABLES: ClassVar[frozenset[str]] = frozenset({'body_parent_f'})#

Names of observables supported by this solver class.

Entries are string identifiers, such as ObservableKind.BODY_QDD. Query supported_observables for the capabilities of an instance.

property friction_smoothing: float#: Legacy value retained for attribute access; it has no effect on friction.

Deprecated since version 1.8: Reading or assigning this attribute warns. Use shape material kf for the low-speed friction slope and mu for the Coulomb limit.