diff --git a/wpimath/src/main/java/edu/wpi/first/math/trajectory/ExponentialProfile.java b/wpimath/src/main/java/edu/wpi/first/math/trajectory/ExponentialProfile.java index 46b0c14416..e2dae9322a 100644 --- a/wpimath/src/main/java/edu/wpi/first/math/trajectory/ExponentialProfile.java +++ b/wpimath/src/main/java/edu/wpi/first/math/trajectory/ExponentialProfile.java @@ -81,7 +81,7 @@ public class ExponentialProfile { public final double B; /** - * Construct constraints for an ExponentialProfile. + * Constructs constraints for an ExponentialProfile. * * @param maxInput maximum unsigned input voltage * @param A The State-Space 1x1 system matrix. @@ -103,7 +103,7 @@ public class ExponentialProfile { } /** - * Construct constraints for an ExponentialProfile from characteristics. + * Constructs constraints for an ExponentialProfile from characteristics. * * @param maxInput maximum unsigned input voltage * @param kV The velocity gain. @@ -115,7 +115,7 @@ public class ExponentialProfile { } /** - * Construct constraints for an ExponentialProfile from State-Space parameters. + * Constructs constraints for an ExponentialProfile from State-Space parameters. * * @param maxInput maximum unsigned input voltage * @param A The State-Space 1x1 system matrix. @@ -139,7 +139,7 @@ public class ExponentialProfile { public State() {} /** - * Construct a state within an exponential profile. + * Constructs a state within an exponential profile. * * @param position The position at this state. * @param velocity The velocity at this state. @@ -166,7 +166,7 @@ public class ExponentialProfile { } /** - * Construct an ExponentialProfile. + * Constructs an ExponentialProfile. * * @param constraints The constraints on the profile, like maximum input. */ @@ -175,10 +175,10 @@ public class ExponentialProfile { } /** - * Calculate the correct position and velocity for the profile at a time t where the current state - * is at time t = 0. + * Calculates the position and velocity for the profile at a time t where the current state is at + * time t = 0. * - * @param t The time since the beginning of the profile. + * @param t How long to advance from the current state toward the desired state. * @param current The current state. * @param goal The desired state when the profile is complete. * @return The position and velocity of the profile at time t. @@ -205,7 +205,7 @@ public class ExponentialProfile { } /** - * Calculate the point after which the fastest way to reach the goal state is to apply input in + * Calculates the point after which the fastest way to reach the goal state is to apply input in * the opposite direction. * * @param current The current state. @@ -220,7 +220,7 @@ public class ExponentialProfile { } /** - * Calculate the point after which the fastest way to reach the goal state is to apply input in + * Calculates the point after which the fastest way to reach the goal state is to apply input in * the opposite direction. * * @param current The current state. @@ -242,7 +242,7 @@ public class ExponentialProfile { } /** - * Calculate the time it will take for this profile to reach the goal state. + * Calculates the time it will take for this profile to reach the goal state. * * @param current The current state. * @param goal The desired state when the profile is complete. @@ -255,8 +255,8 @@ public class ExponentialProfile { } /** - * Calculate the time it will take for this profile to reach the inflection point, and the time it - * will take for this profile to reach the goal state. + * Calculates the time it will take for this profile to reach the inflection point, and the time + * it will take for this profile to reach the goal state. * * @param current The current state. * @param goal The desired state when the profile is complete. @@ -271,8 +271,8 @@ public class ExponentialProfile { } /** - * Calculate the time it will take for this profile to reach the inflection point, and the time it - * will take for this profile to reach the goal state. + * Calculates the time it will take for this profile to reach the inflection point, and the time + * it will take for this profile to reach the goal state. * * @param current The current state. * @param inflectionPoint The inflection point of this profile. @@ -332,7 +332,7 @@ public class ExponentialProfile { } /** - * Calculate the position reached after t seconds when applying an input from the initial state. + * Calculates the position reached after t seconds when applying an input from the initial state. * * @param t The time since the initial state. * @param input The signed input applied to this profile from the initial state. @@ -349,7 +349,7 @@ public class ExponentialProfile { } /** - * Calculate the velocity reached after t seconds when applying an input from the initial state. + * Calculates the velocity reached after t seconds when applying an input from the initial state. * * @param t The time since the initial state. * @param input The signed input applied to this profile from the initial state. @@ -365,7 +365,7 @@ public class ExponentialProfile { } /** - * Calculate the time required to reach a specified velocity given the initial velocity. + * Calculates the time required to reach a specified velocity given the initial velocity. * * @param velocity The goal velocity. * @param input The signed input applied to this profile from the initial state. @@ -381,7 +381,7 @@ public class ExponentialProfile { } /** - * Calculate the distance reached at the same time as the given velocity when applying the given + * Calculates the distance reached at the same time as the given velocity when applying the given * input from the initial state. * * @param velocity The velocity reached by this profile @@ -400,7 +400,7 @@ public class ExponentialProfile { } /** - * Calculate the velocity at which input should be reversed in order to reach the goal state from + * Calculates the velocity at which input should be reversed in order to reach the goal state from * the current state. * * @param input The signed input applied to this profile from the current state. diff --git a/wpimath/src/main/java/edu/wpi/first/math/trajectory/TrapezoidProfile.java b/wpimath/src/main/java/edu/wpi/first/math/trajectory/TrapezoidProfile.java index 5215d3a4f9..657ea24fe3 100644 --- a/wpimath/src/main/java/edu/wpi/first/math/trajectory/TrapezoidProfile.java +++ b/wpimath/src/main/java/edu/wpi/first/math/trajectory/TrapezoidProfile.java @@ -63,7 +63,7 @@ public class TrapezoidProfile { public final double maxAcceleration; /** - * Construct constraints for a TrapezoidProfile. + * Constructs constraints for a TrapezoidProfile. * * @param maxVelocity maximum velocity * @param maxAcceleration maximum acceleration @@ -75,7 +75,7 @@ public class TrapezoidProfile { } /** - * Construct constraints for a TrapezoidProfile. + * Constructs constraints for a TrapezoidProfile. * * @param Unit type. * @param maxVelocity maximum velocity @@ -137,7 +137,7 @@ public class TrapezoidProfile { } /** - * Construct a TrapezoidProfile. + * Constructs a TrapezoidProfile. * * @param constraints The constraints on the profile, like maximum velocity. */ @@ -147,7 +147,7 @@ public class TrapezoidProfile { } /** - * Construct a TrapezoidProfile. + * Constructs a TrapezoidProfile. * * @param constraints The constraints on the profile, like maximum velocity. * @param goal The desired state when the profile is complete. @@ -197,7 +197,7 @@ public class TrapezoidProfile { } /** - * Construct a TrapezoidProfile. + * Constructs a TrapezoidProfile. * * @param constraints The constraints on the profile, like maximum velocity. * @param goal The desired state when the profile is complete. @@ -210,10 +210,10 @@ public class TrapezoidProfile { } /** - * Calculate the correct position and velocity for the profile at a time t where the beginning of - * the profile was at time t = 0. + * Calculates the position and velocity for the profile at a time t where the current state is at + * time t = 0. * - * @param t The time since the beginning of the profile. + * @param t How long to advance from the current state toward the desired state. * @return The position and velocity of the profile at time t. * @deprecated Pass the desired and current state into calculate instead of constructing a new * TrapezoidProfile with the desired and current state @@ -247,10 +247,10 @@ public class TrapezoidProfile { } /** - * Calculate the correct position and velocity for the profile at a time t where the beginning of - * the profile was at time t = 0. + * Calculates the position and velocity for the profile at a time t where the current state is at + * time t = 0. * - * @param t The time since the beginning of the profile. + * @param t How long to advance from the current state toward the desired state. * @param current The current state. * @param goal The desired state when the profile is complete. * @return The position and velocity of the profile at time t. diff --git a/wpimath/src/main/native/include/frc/trajectory/ExponentialProfile.h b/wpimath/src/main/native/include/frc/trajectory/ExponentialProfile.h index 3622aa7865..9f836c1036 100644 --- a/wpimath/src/main/native/include/frc/trajectory/ExponentialProfile.h +++ b/wpimath/src/main/native/include/frc/trajectory/ExponentialProfile.h @@ -81,7 +81,7 @@ class ExponentialProfile { class Constraints { public: /** - * Construct constraints for an ExponentialProfile. + * Constructs constraints for an ExponentialProfile. * * @param maxInput maximum unsigned input voltage * @param A The State-Space 1x1 system matrix. @@ -91,7 +91,7 @@ class ExponentialProfile { : maxInput{maxInput}, A{A}, B{B} {} /** - * Construct constraints for an ExponentialProfile from characteristics. + * Constructs constraints for an ExponentialProfile from characteristics. * * @param maxInput maximum unsigned input voltage * @param kV The velocity gain. @@ -130,7 +130,7 @@ class ExponentialProfile { }; /** - * Construct a ExponentialProfile. + * Constructs a ExponentialProfile. * * @param constraints The constraints on the profile, like maximum input. */ @@ -142,41 +142,72 @@ class ExponentialProfile { ExponentialProfile& operator=(ExponentialProfile&&) = default; /** - * Calculate the correct position and velocity for the profile at a time t - * where the current state is at time t = 0. + * Calculates the position and velocity for the profile at a time t where the + * current state is at time t = 0. + * + * @param t How long to advance from the current state toward the desired + * state. + * @param current The current state. + * @param goal The desired state when the profile is complete. + * @return The position and velocity of the profile at time t. */ State Calculate(const units::second_t& t, const State& current, const State& goal) const; /** - * Calculate the point after which the fastest way to reach the goal state is + * Calculates the point after which the fastest way to reach the goal state is * to apply input in the opposite direction. + * + * @param current The current state. + * @param goal The desired state when the profile is complete. + * @return The position and velocity of the profile at the inflection point. */ State CalculateInflectionPoint(const State& current, const State& goal) const; /** - * Calculate the time it will take for this profile to reach the goal state. + * Calculates the time it will take for this profile to reach the goal state. + * + * @param current The current state. + * @param goal The desired state when the profile is complete. + * @return The total duration of this profile. */ units::second_t TimeLeftUntil(const State& current, const State& goal) const; /** - * Calculate the time it will take for this profile to reach the inflection + * Calculates the time it will take for this profile to reach the inflection * point, and the time it will take for this profile to reach the goal state. + * + * @param current The current state. + * @param goal The desired state when the profile is complete. + * @return The timing information for this profile. */ ProfileTiming CalculateProfileTiming(const State& current, const State& goal) const; private: /** - * Calculate the point after which the fastest way to reach the goal state is + * Calculates the point after which the fastest way to reach the goal state is * to apply input in the opposite direction. + * + * @param current The current state. + * @param goal The desired state when the profile is complete. + * @param input The signed input applied to this profile from the current + * state. + * @return The position and velocity of the profile at the inflection point. */ State CalculateInflectionPoint(const State& current, const State& goal, const Input_t& input) const; /** - * Calculate the time it will take for this profile to reach the inflection + * Calculates the time it will take for this profile to reach the inflection * point, and the time it will take for this profile to reach the goal state. + * + * @param current The current state. + * @param inflectionPoint The inflection point of this profile. + * @param goal The desired state when the profile is complete. + * @param input The signed input applied to this profile from the current + * state. + * @return The timing information for this profile. */ ProfileTiming CalculateProfileTiming(const State& current, const State& inflectionPoint, @@ -184,40 +215,70 @@ class ExponentialProfile { const Input_t& input) const; /** - * Calculate the velocity reached after t seconds when applying an input from - * the initial state. - */ - Velocity_t ComputeVelocityFromTime(const units::second_t& time, - const Input_t& input, - const State& initial) const; - - /** - * Calculate the position reached after t seconds when applying an input from + * Calculates the position reached after t seconds when applying an input from * the initial state. + * + * @param t The time since the initial state. + * @param input The signed input applied to this profile from the initial + * state. + * @param initial The initial state. + * @return The distance travelled by this profile. */ Distance_t ComputeDistanceFromTime(const units::second_t& time, const Input_t& input, const State& initial) const; /** - * Calculate the distance reached at the same time as the given velocity when - * applying the given input from the initial state. + * Calculates the velocity reached after t seconds when applying an input from + * the initial state. + * + * @param t The time since the initial state. + * @param input The signed input applied to this profile from the initial + * state. + * @param initial The initial state. + * @return The distance travelled by this profile. */ - Distance_t ComputeDistanceFromVelocity(const Velocity_t& velocity, - const Input_t& input, - const State& initial) const; + Velocity_t ComputeVelocityFromTime(const units::second_t& time, + const Input_t& input, + const State& initial) const; /** - * Calculate the time required to reach a specified velocity given the initial - * velocity. + * Calculates the time required to reach a specified velocity given the + * initial velocity. + * + * @param velocity The goal velocity. + * @param input The signed input applied to this profile from the initial + * state. + * @param initial The initial velocity. + * @return The time required to reach the goal velocity. */ units::second_t ComputeTimeFromVelocity(const Velocity_t& velocity, const Input_t& input, const Velocity_t& initial) const; /** - * Calculate the velocity at which input should be reversed in order to reach + * Calculates the distance reached at the same time as the given velocity when + * applying the given input from the initial state. + * + * @param velocity The velocity reached by this profile + * @param input The signed input applied to this profile from the initial + * state. + * @param initial The initial state. + * @return The distance reached when the given velocity is reached. + */ + Distance_t ComputeDistanceFromVelocity(const Velocity_t& velocity, + const Input_t& input, + const State& initial) const; + + /** + * Calculates the velocity at which input should be reversed in order to reach * the goal state from the current state. + * + * @param input The signed input applied to this profile from the current + * state. + * @param current The current state. + * @param goal The goal state. + * @return The inflection velocity. */ Velocity_t SolveForInflectionVelocity(const Input_t& input, const State& current, @@ -226,8 +287,11 @@ class ExponentialProfile { /** * Returns true if the profile should be inverted. * - *
The profile is inverted if we should first apply negative input in order
- * to reach the goal state.
+ * The profile is inverted if we should first apply negative input in order to
+ * reach the goal state.
+ *
+ * @param current The initial state (usually the current state).
+ * @param goal The desired state when the profile is complete.
*/
bool ShouldFlipInput(const State& current, const State& goal) const;
diff --git a/wpimath/src/main/native/include/frc/trajectory/ExponentialProfile.inc b/wpimath/src/main/native/include/frc/trajectory/ExponentialProfile.inc
index ded52452e5..f8fd5f0ac5 100644
--- a/wpimath/src/main/native/include/frc/trajectory/ExponentialProfile.inc
+++ b/wpimath/src/main/native/include/frc/trajectory/ExponentialProfile.inc
@@ -50,23 +50,6 @@ ExponentialProfile