[wpilib] Rename NormalizeWheelSpeeds to DesaturateWheelSpeeds (#3791)

wpimath/src/main/native/include/frc/StateSpaceUtil.h

@@ -336,8 +336,8 @@ Eigen::Vector<double, Inputs> ClampInputMaxMagnitude(
 }
 
 /**
- * Normalize all inputs if any excedes the maximum magnitude. Useful for systems
- * such as differential drivetrains.
+ * Renormalize all inputs if any exceeds the maximum magnitude. Useful for
+ * systems such as differential drivetrains.
  *
  * @tparam Inputs      The number of inputs.
  * @param u            The input vector.
@@ -345,7 +345,7 @@ Eigen::Vector<double, Inputs> ClampInputMaxMagnitude(
  * @return The normalizedInput
  */
 template <int Inputs>
-Eigen::Vector<double, Inputs> NormalizeInputVector(
+Eigen::Vector<double, Inputs> DesaturateInputVector(
     const Eigen::Vector<double, Inputs>& u, double maxMagnitude) {
   double maxValue = u.template lpNorm<Eigen::Infinity>();
 

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

@@ -24,15 +24,17 @@ struct WPILIB_DLLEXPORT DifferentialDriveWheelSpeeds {
   units::meters_per_second_t right = 0_mps;
 
   /**
-   * Normalizes the wheel speeds using some max attainable speed. Sometimes,
-   * after inverse kinematics, the requested speed from a/several modules may be
-   * above the max attainable speed for the driving motor on that module. To fix
-   * this issue, one can "normalize" all the wheel speeds to make sure that all
-   * requested module speeds are below the absolute threshold, while maintaining
-   * the ratio of speeds between modules.
+   * Renormalizes the wheel speeds if either side is above the specified
+   * maximum.
+   *
+   * Sometimes, after inverse kinematics, the requested speed from one or more
+   * wheels may be above the max attainable speed for the driving motor on that
+   * wheel. To fix this issue, one can 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 wheels.
    *
    * @param attainableMaxSpeed The absolute max speed that a wheel can reach.
    */
-  void Normalize(units::meters_per_second_t attainableMaxSpeed);
+  void Desaturate(units::meters_per_second_t attainableMaxSpeed);
 };
 }  // namespace frc

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

@@ -34,15 +34,17 @@ struct WPILIB_DLLEXPORT MecanumDriveWheelSpeeds {
   units::meters_per_second_t rearRight = 0_mps;
 
   /**
-   * Normalizes the wheel speeds using some max attainable speed. Sometimes,
-   * after inverse kinematics, the requested speed from a/several modules may be
-   * above the max attainable speed for the driving motor on that module. To fix
-   * this issue, one can "normalize" all the wheel speeds to make sure that all
-   * requested module speeds are below the absolute threshold, while maintaining
-   * the ratio of speeds between modules.
+   * Renormalizes the wheel speeds if any individual speed is above the
+   * specified maximum.
+   *
+   * Sometimes, after inverse kinematics, the requested speed from one or
+   * more wheels may be above the max attainable speed for the driving motor on
+   * that wheel. To fix this issue, one can 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 wheels.
    *
    * @param attainableMaxSpeed The absolute max speed that a wheel can reach.
    */
-  void Normalize(units::meters_per_second_t attainableMaxSpeed);
+  void Desaturate(units::meters_per_second_t attainableMaxSpeed);
 };
 }  // namespace frc

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

@@ -114,7 +114,7 @@ class SwerveDriveKinematics {
    * @return An array containing the module states. Use caution because these
    * module states are not normalized. Sometimes, a user input may cause one of
    * the module speeds to go above the attainable max velocity. Use the
-   * NormalizeWheelSpeeds(wpi::array<SwerveModuleState, NumModules>*,
+   * DesaturateWheelSpeeds(wpi::array<SwerveModuleState, NumModules>*,
    * units::meters_per_second_t) function to rectify this issue. In addition,
    * you can leverage the power of C++17 to directly assign the module states to
    * variables:
@@ -159,18 +159,21 @@ class SwerveDriveKinematics {
       wpi::array<SwerveModuleState, NumModules> moduleStates) const;
 
   /**
-   * Normalizes the wheel speeds using some max attainable speed. Sometimes,
-   * after inverse kinematics, the requested speed from a/several modules may be
-   * above the max attainable speed for the driving motor on that module. To fix
-   * this issue, one can "normalize" all the wheel speeds to make sure that all
-   * requested module speeds are below the absolute threshold, while maintaining
-   * the ratio of speeds between modules.
+   * Renormalizes the wheel speeds if any individual speed is above the
+   * specified maximum.
+   *
+   * Sometimes, after inverse kinematics, the requested speed
+   * from one or more modules may be above the max attainable speed for the
+   * driving motor on that module. To fix this issue, one can 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.
    *
    * @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.
    */
-  static void NormalizeWheelSpeeds(
+  static void DesaturateWheelSpeeds(
       wpi::array<SwerveModuleState, NumModules>* moduleStates,
       units::meters_per_second_t attainableMaxSpeed);
 

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

@@ -88,7 +88,7 @@ ChassisSpeeds SwerveDriveKinematics<NumModules>::ToChassisSpeeds(
 }
 
 template <size_t NumModules>
-void SwerveDriveKinematics<NumModules>::NormalizeWheelSpeeds(
+void SwerveDriveKinematics<NumModules>::DesaturateWheelSpeeds(
     wpi::array<SwerveModuleState, NumModules>* moduleStates,
     units::meters_per_second_t attainableMaxSpeed) {
   auto& states = *moduleStates;

wpimath/src/main/native/include/frc/system/LinearSystemLoop.h

@@ -54,7 +54,7 @@ class LinearSystemLoop {
       : LinearSystemLoop(
             plant, controller, observer,
             [=](const Eigen::Vector<double, Inputs>& u) {
-              return frc::NormalizeInputVector<Inputs>(u, maxVoltage.value());
+              return frc::DesaturateInputVector<Inputs>(u, maxVoltage.value());
             },
             dt) {}
 
@@ -99,7 +99,7 @@ class LinearSystemLoop {
       KalmanFilter<States, Inputs, Outputs>& observer, units::volt_t maxVoltage)
       : LinearSystemLoop(controller, feedforward, observer,
                          [=](const Eigen::Vector<double, Inputs>& u) {
-                           return frc::NormalizeInputVector<Inputs>(
+                           return frc::DesaturateInputVector<Inputs>(
                                u, maxVoltage.value());
                          }) {}
 

wpimath/src/main/native/include/frc/trajectory/constraint/SwerveDriveKinematicsConstraint.inc

@@ -24,7 +24,7 @@ SwerveDriveKinematicsConstraint<NumModules>::MaxVelocity(
   auto yVelocity = velocity * pose.Rotation().Sin();
   auto wheelSpeeds = m_kinematics.ToSwerveModuleStates(
       {xVelocity, yVelocity, velocity * curvature});
-  m_kinematics.NormalizeWheelSpeeds(&wheelSpeeds, m_maxSpeed);
+  m_kinematics.DesaturateWheelSpeeds(&wheelSpeeds, m_maxSpeed);
 
   auto normSpeeds = m_kinematics.ToChassisSpeeds(wheelSpeeds);