[wpimath] Document drift from desaturating discretized chassis speeds (NFC) (#7741)

wpimath/src/main/java/edu/wpi/first/math/kinematics/ChassisSpeeds.java

@@ -96,7 +96,10 @@ public class ChassisSpeeds implements ProtobufSerializable, StructSerializable {
    * along the y-axis, and omega * dt around the z-axis).
    *
    * <p>This is useful for compensating for translational skew when translating and rotating a
-   * swerve drivetrain.
+   * holonomic (swerve or mecanum) drivetrain. However, scaling down the ChassisSpeeds after
+   * discretizing (e.g., when desaturating swerve module speeds) rotates the direction of net motion
+   * in the opposite direction of rotational velocity, introducing a different translational skew
+   * which is not accounted for by discretization.
    *
    * @param vxMetersPerSecond Forward velocity.
    * @param vyMetersPerSecond Sideways velocity.
@@ -134,7 +137,10 @@ public class ChassisSpeeds implements ProtobufSerializable, StructSerializable {
    * along the y-axis, and omega * dt around the z-axis).
    *
    * <p>This is useful for compensating for translational skew when translating and rotating a
-   * swerve drivetrain.
+   * holonomic (swerve or mecanum) drivetrain. However, scaling down the ChassisSpeeds after
+   * discretizing (e.g., when desaturating swerve module speeds) rotates the direction of net motion
+   * in the opposite direction of rotational velocity, introducing a different translational skew
+   * which is not accounted for by discretization.
    *
    * @param vx Forward velocity.
    * @param vy Sideways velocity.
@@ -157,7 +163,10 @@ public class ChassisSpeeds implements ProtobufSerializable, StructSerializable {
    * along the y-axis, and omega * dt around the z-axis).
    *
    * <p>This is useful for compensating for translational skew when translating and rotating a
-   * swerve drivetrain.
+   * holonomic (swerve or mecanum) drivetrain. However, scaling down the ChassisSpeeds after
+   * discretizing (e.g., when desaturating swerve module speeds) rotates the direction of net motion
+   * in the opposite direction of rotational velocity, introducing a different translational skew
+   * which is not accounted for by discretization.
    *
    * @param continuousSpeeds The continuous speeds.
    * @param dtSeconds The duration of the timestep the speeds should be applied for.

wpimath/src/main/java/edu/wpi/first/math/kinematics/SwerveDriveKinematics.java

@@ -274,6 +274,10 @@ public class SwerveDriveKinematics
    * reduce all the wheel speeds to make sure that all requested module speeds are at-or-below the
    * absolute threshold, while maintaining the ratio of speeds between modules.
    *
+   * <p>Scaling down the module speeds rotates the direction of net motion in the opposite direction
+   * of rotational velocity, which makes discretizing the chassis speeds inaccurate because the
+   * discretization did not account for this translational skew.
+   *
    * @param moduleStates Reference to array of module states. The array will be mutated with the
    *     normalized speeds!
    * @param attainableMaxSpeedMetersPerSecond The absolute max speed that a module can reach.
@@ -300,6 +304,10 @@ public class SwerveDriveKinematics
    * reduce all the wheel speeds to make sure that all requested module speeds are at-or-below the
    * absolute threshold, while maintaining the ratio of speeds between modules.
    *
+   * <p>Scaling down the module speeds rotates the direction of net motion in the opposite direction
+   * of rotational velocity, which makes discretizing the chassis speeds inaccurate because the
+   * discretization did not account for this translational skew.
+   *
    * @param moduleStates Reference to array of module states. The array will be mutated with the
    *     normalized speeds!
    * @param attainableMaxSpeed The absolute max speed that a module can reach.
@@ -318,6 +326,10 @@ public class SwerveDriveKinematics
    * reduce all the wheel speeds to make sure that all requested module speeds are at-or-below the
    * absolute threshold, while maintaining the ratio of speeds between modules.
    *
+   * <p>Scaling down the module speeds rotates the direction of net motion in the opposite direction
+   * of rotational velocity, which makes discretizing the chassis speeds inaccurate because the
+   * discretization did not account for this translational skew.
+   *
    * @param moduleStates Reference to array of module states. The array will be mutated with the
    *     normalized speeds!
    * @param desiredChassisSpeed The desired speed of the robot
@@ -365,6 +377,10 @@ public class SwerveDriveKinematics
    * reduce all the wheel speeds to make sure that all requested module speeds are at-or-below the
    * absolute threshold, while maintaining the ratio of speeds between modules.
    *
+   * <p>Scaling down the module speeds rotates the direction of net motion in the opposite direction
+   * of rotational velocity, which makes discretizing the chassis speeds inaccurate because the
+   * discretization did not account for this translational skew.
+   *
    * @param moduleStates Reference to array of module states. The array will be mutated with the
    *     normalized speeds!
    * @param desiredChassisSpeed The desired speed of the robot

wpimath/src/main/native/include/frc/kinematics/ChassisSpeeds.h

@@ -59,7 +59,11 @@ struct WPILIB_DLLEXPORT ChassisSpeeds {
    * y-axis, and omega * dt around the z-axis).
    *
    * This is useful for compensating for translational skew when translating and
-   * rotating a swerve drivetrain.
+   * rotating a holonomic (swerve or mecanum) drivetrain. However, scaling down
+   * the ChassisSpeeds after discretizing (e.g., when desaturating swerve module
+   * speeds) rotates the direction of net motion in the opposite direction of
+   * rotational velocity, introducing a different translational skew which is
+   * not accounted for by discretization.
    *
    * @param vx Forward velocity.
    * @param vy Sideways velocity.
@@ -94,7 +98,11 @@ struct WPILIB_DLLEXPORT ChassisSpeeds {
    * y-axis, and omega * dt around the z-axis).
    *
    * This is useful for compensating for translational skew when translating and
-   * rotating a swerve drivetrain.
+   * rotating a holonomic (swerve or mecanum) drivetrain. However, scaling down
+   * the ChassisSpeeds after discretizing (e.g., when desaturating swerve module
+   * speeds) rotates the direction of net motion in the opposite direction of
+   * rotational velocity, introducing a different translational skew which is
+   * not accounted for by discretization.
    *
    * @param continuousSpeeds The continuous speeds.
    * @param dt The duration of the timestep the speeds should be applied for.

wpimath/src/main/native/include/frc/kinematics/SwerveDriveKinematics.h

@@ -335,6 +335,11 @@ class SwerveDriveKinematics
    * the absolute threshold, while maintaining the ratio of speeds between
    * modules.
    *
+   * Scaling down the module speeds rotates the direction of net motion in the
+   * opposite direction of rotational velocity, which makes discretizing the
+   * chassis speeds inaccurate because the discretization did not account for
+   * this translational skew.
+   *
    * @param moduleStates Reference to array of module states. The array will be
    * mutated with the normalized speeds!
    * @param attainableMaxSpeed The absolute max speed that a module can reach.
@@ -370,6 +375,11 @@ class SwerveDriveKinematics
    * the absolute threshold, while maintaining the ratio of speeds between
    * modules.
    *
+   * Scaling down the module speeds rotates the direction of net motion in the
+   * opposite direction of rotational velocity, which makes discretizing the
+   * chassis speeds inaccurate because the discretization did not account for
+   * this translational skew.
+   *
    * @param moduleStates Reference to array of module states. The array will be
    * mutated with the normalized speeds!
    * @param desiredChassisSpeed The desired speed of the robot