Model motor torque across wheel speed

[Zw96042]

Summary

• Model the signed ideal-DC-motor voltage envelope for both differential and swerve trajectories.
• Keep the existing planner speed, current-limited torque, and traction limits independent from the physical motor curve.
• Add physical motor free-speed and stall-torque settings, with Kraken X60 defaults for new projects.
• Preserve existing project behavior by migrating older files with the new constraint disabled.

Why

Choreo currently treats maximum wheel speed and maximum wheel torque as independent constraints. A real DC motor cannot produce its zero-speed torque at every speed: back-EMF reduces the available propulsive torque as wheel speed rises.

This is a focused replacement for #1475, which has been inactive since May 31 and now conflicts with main. The underlying issue in #1245 remains unresolved, so this PR keeps the change centered on the torque-speed constraint and implements it for both drivetrain types.

The blue REV torque curve demonstrates the behavior this PR adds: available torque decreases toward zero as the motor approaches free speed. Choreo reconstructs that ideal line from stall torque and free speed, then intersects it with the independently configured current-limited maximum torque. The power and efficiency curves are shown for context but are not modeled as separate constraints here. Source: REV Robotics NEO Vortex documentation.

Model

For each differential wheel, the normalized terminal voltage is

V / V_nominal = torque / stall_torque + angular_velocity / free_speed

and is bounded to [-1, 1]. This gives the usual linear torque-speed curve in forward and reverse while retaining the correct braking quadrants. The existing current and traction constraints remain in force, so this does not attempt to model battery sag, supply-current limits, or regenerative-energy acceptance.

Swerve uses the corresponding smooth two-dimensional voltage-vector constraint. Choreo does not optimize an explicit module azimuth or traction axis, so this is an isotropic surrogate: it is exact when module force and velocity are collinear and conservative for lateral force. The formulation is rotationally invariant and matches the optimizer's existing isotropic module force model.

Compatibility

• Project schema: 2 -> 3
• Trajectory schema: 3 -> 4
• Existing .chor and .traj files migrate with the curve disabled, avoiding a silent change to regenerated trajectories.
• Existing C++ aggregate initializers remain source-compatible because the fields are appended with defaults. The exported struct layout changes, so binary consumers must rebuild; Rust callers must populate the new fields.

Verification

• cargo test --workspace
• cargo clippy --workspace -- -D warnings
• TrajoptLib CMake build and ctest (31/31)
• Differential and swerve examples
• TypeScript typecheck, ESLint, and Vite production build
• Rust, C++, Java, and frontend formatting checks
• Focused migration and generated-trajectory regression tests

Closes #1245
Supersedes #1475

[shueja]

We're going to keep working on the other PR, which has actual physical testing behind it.

[Zw96042]

Thanks. That makes sense. I couldn’t find the physical testing procedure or logged results in #1475 or #1245.

The constraint in #1509 is derived directly from the DC motor equations $V = IR + k_e\omega$ and $\tau = k_t I$, but I understand prioritizing hardware-validated behavior. Would you be able to share the test setup or data? I’d be interested in comparing both formulations against the same measurements and contributing any useful pieces from #1509 to #1475.