Skip to content

novaphy.actuators

Minimal actuator framework. The current public surface is the smallest data-path compatible subset needed by the Newton container contract: a PD controller that accumulates effort into Control.joint_f.

Data Flow

Actuators sit between the application's control loop and the solver. Per step:

  application target ──▶ Actuator.step(state, control)
                                       │
                                       ▼ writes effort into
                              Control.joint_f[indices]
                                       │
                                       ▼ consumed by
                         solver.step(state, state, control, contacts, dt)

The actuator reads SimState.joint_q / joint_qd for feedback but does not modify the state. It writes only to the Control buffer's joint_f channel for the configured DOF indices, and the solver consumes that channel during its step call.

Minimal Example

import novaphy
from novaphy import actuators

ctrl     = actuators.ControllerPD(kp=[10.0], kd=[0.5])
actuator = actuators.Actuator(indices=[0], controller=ctrl)

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

for step_idx in range(steps):
    control.joint_f.fill_zero()
    control.joint_target_pos[0] = q_des(step_idx)
    actuator.step(state, control)              # writes Control.joint_f[0]
    pipeline.collide(state, contacts)
    solver.step(state, state, control, contacts, dt)

The actuator adds effort with +=; clear or restore control.joint_f before each control evaluation when forces should not accumulate across steps. Its single indices array addresses both joint_q and joint_qd, so it is appropriate when the selected coordinates have matching q/qd indices (typically 1-DOF joints). It is not a general mapping for Free, Ball, or other layouts where nq != nv. The current NumPy implementation also requires CPU-resident buffers.

Classes

Class Description
Actuator Composed actuator that writes effort into control.joint_f.
ControllerPD Per-DOF proportional-derivative controller.

Compatibility Notes

Newton's newton.actuators library is significantly larger; NovaPhy does not yet provide:

  • Controller base class abstraction
  • PIDController, MLPController, LSTMController
  • Clamper / SymmetricClamper / DCMotorClamper / LookupTableClamper
  • ActuatorDelay (per-DOF command input delay)
  • ActuatorSpec, ComponentSchema, parse_usd_actuator, register_usd_schema (USD actuator parsing)