Rewrite exc_ff_pid as an excitation-driven velocity controller

[Copilot]

exc_ff_pid was implementing a position loop (PID(theta_ref - theta)) and discarding measured velocity, which is the wrong control structure for wave-energy absorption. This updates the controller to track an excitation-driven velocity reference while preserving the existing exc_ff_pid config/CLI selector.

• Controller rewrite

  • Renamed the C++ class from ExcitationFeedforwardPID to ExcitationVelocityController
  • Replaced the old position law with:
    • vel_ref = alpha * F_exc
    • tau_cmd = ff_gain * F_exc + PID(vel_ref - theta_dot)
    • returned PTO torque uses the repo’s restoring sign convention
  • Removed the vestigial position path entirely (theta_ref no longer exists)

  double ExcitationVelocityController::ComputeForce(double /*disp*/, double vel, double t) {
      const double f_exc = f_exc_source_->GetLatestExcitationTorque();
      pid_->SetSetpoint(alpha_ * f_exc);
      const double tau_ff = ff_gain_ * f_exc;
      const double tau_pid = pid_->Compute(vel, t);
      return -(tau_ff + tau_pid);
  }

• Config/schema update

  • Replaced controller.exc_ff_pid.theta_ref and nested pid with:
    • alpha
    • ff_gain
    • vel_pid
  • Set velocity-loop defaults to conservative, tunable values:
    • alpha = 0.05
    • ff_gain = 0.5
    • vel_pid = { kp: 1.0, ki: 0.0, kd: 0.0, tau_d: 0.02, u_min: -5.0, u_max: 5.0 }
  • Kept the external controller token exc_ff_pid unchanged so existing CLI overrides and sweep scripts continue to select the controller the same way

• Runtime wiring

  • Updated controller construction in demo_vgoswec.cpp to build ExcitationVelocityController
  • Switched PID parameter sourcing to cfg.controller.exc_ff_pid.vel_pid

• Docs and examples

  • Updated active_pto.h sign/convention docs to describe the velocity law
  • Updated docs/CONTROLLERS.md and the exc_ff_pid YAML examples to match the new schema and control structure
  • Removed stale references to position tracking terminology in adjacent docs/comments

• Focused test updates

  • Reworked the smoke test coverage for exc_ff_pid to validate:
    • feedforward behavior under the active sign convention
    • PID action on velocity error rather than displacement
    • parsing of the new vel_pid config schema