Team2890/allwpilib
4
0
Fork 0
mirror of https://github.com/wpilibsuite/allwpilib synced 2026-06-20 00:51:42 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
6c9dcc157e7b1ac7dfbd7fc96194ab810229c8a5
allwpilib/wpiunits/src/main/java/edu/wpi/first/units/Energy.java

30 lines
970 B
Java
Raw Normal View History

[wpiunits] Add subproject for a Java typesafe unit system (#5371) # Background Unit safety has always been a problem in WPILib. Any value corresponding to a physical measurement, such as current draw or distance traveled, is represented by a bare number with no unit tied to it; it's up to the programmer to know what units they're working and take care to remember that while working on their robot program. This leads to bugs when programmers accidentally mix units without knowing, or measure something (such as a wheel diameter) in one unit and program using another. `wpiunits` is intended to eliminate that class of bugs. Another source of friction is the controllers and models in `wpimath` that expect all inputs to be in terms of SI units (meter, kilogram, and so on), while most FRC teams are US-based and most commonly use imperial units. wpimath does a good job of noting unit types in method names and argument names; however, it still relies on users properly converting values (and knowing they even have to do so). # API There are really only two core classes in this library: `Unit` and `Measure`. A `Unit` represents some dimension like distance or time. `Unit` is subclassed to define specific dimensions (eg `Distance` and `Time`) and those subclasses are instantiated to defined particular units in those dimensions, such as `Meters` and `Feet` being instances of the `Distance` class. A `Measure` is a value tied to a particular dimension like distance and knows what unit that value is tied to. `Measure` has two implementations - one immutable and one mutable. The `Measure` interface only defines *read-only* operations; any API working with measurements should use the interface. The default implementation is `ImmutableMeasure`, which only implements those read-only operations and is useful for tracking constants. `MutableMeasure` also adds some methods that will allow for mutation of its internal state; this class is intended for use for things like sensors and controllers that track internal state and don't want to allocate new `Measure` objects every time something like `myEncoder.getDistance()` is called. However, the APIs for those methods should still only expose the read-only `Measure` interface so users can't (without casting or reflection) change the internal values. A `Units` class provides convenient definitions for most of the commonly used unit types, such as `Meters`, `Feet`, and `Milliseconds`. I recommend static importing these units eg `import static edu.wpi.first.units.Units.Meters`) so they can be used like `Meters.of(1.234)` instead of `Units.Meters.of(1.234)` # Examples These examples are admittedly contrived. Users shouldn't be interacting much with measure objects themselves, since wpimath and wpilibj classes will be updated to support working with them; users will often just have to take a `Measure` output from one place (such as an encoder) and feed it as input to something else (such as a PID controller or kinematics model) ```java // Using raw units Encoder encoder = ... int kPulsesPerRev = 2048; double kWheelDiameterMeters = Units.inchesToMeters(6); double kGearRatio = 10.86; // always have to remember this encoder will output in meters! encoder.setDistancePerPulse(kWheelDiameterMeters * Math.PI / (kGearRatio * kPulsesPerRev)); Command driveDistance(double distance) { // have to know the distance argument needs to be in meters! return run(this::driveStraight).until(() -> encoder.getDistance() >= distance); } // Oops! This will go 16 feet, not 5! Command driveFiveFeet = driveDistance(5); Command driveOneMeter = driveDistance(1); ``` ```java // Using wpiunits Encoder encoder = ... int kPulsesPerRev = 2048; Measure<Distance> kWheelDiameter = Inches.of(6); double kGearRatio = 10.86; encoder.setDistancePerPulse(kWheelDiameter.times(Math.PI).divide(kGearRatio * kPulsesPerRev)); Command driveDistance(Measure<Distance> distance) { // Measure#gte automatically handles unit conversions return run(this::driveStraight).until(() -> encoder.getDistance().gte(distance)); } // Users HAVE to be explicit about their units Command driveFiveFeet = driveDistance(Feet.of(5)); Command driveOneMeter = driveDistance(Meters.of(1)); ``` ```java SmartDashboard.putNumber("Temperature (C)", pdp.getTemperature().in(Celsius)); SmartDashboard.putNumber("Temperature (F)", pdp.getTemperature().in(Fahrenheit)); ``` ```java var InchSecond = Inch.mult(Second); // new combined unit types can be user-defined var InchPerSecond = Inch.per(Second); PIDController<Distance, ElectricPotential> heightController = new PIDController<>( /* kP */ Volts.of(0.2).per(Inch), /* kI */ Volts.of(0.002).per(InchSecond), /* kD */ Volts.of(0.008).per(InchPerSecond) ); var elevatorTop = Feet.of(4).plus(Inches.of(6.125)); elevatorMotor.setVoltage(heightController.calculate(encoder.getDistance(), elevatorTop)); ```
2023-07-23 17:18:17 -04:00
// Copyright (c) FIRST and other WPILib contributors.
// Open Source Software; you can modify and/or share it under the terms of
// the WPILib BSD license file in the root directory of this project.
package edu.wpi.first.units;
[wpiunits] Documentation improvements (#5932)
2023-11-23 12:57:58 -06:00
/**
* Unit of energy dimension.
*
* <p>This is the base type for units of energy dimension. It is also used to specify the dimension
* for {@link Measure}: <code>Measure&lt;Energy&gt;</code>.
*
* <p>Actual units (such as {@link Units#Joules} and {@link Units#Kilojoules}) can be found in the
* {@link Units} class.
*/
[wpiunits] Add subproject for a Java typesafe unit system (#5371) # Background Unit safety has always been a problem in WPILib. Any value corresponding to a physical measurement, such as current draw or distance traveled, is represented by a bare number with no unit tied to it; it's up to the programmer to know what units they're working and take care to remember that while working on their robot program. This leads to bugs when programmers accidentally mix units without knowing, or measure something (such as a wheel diameter) in one unit and program using another. `wpiunits` is intended to eliminate that class of bugs. Another source of friction is the controllers and models in `wpimath` that expect all inputs to be in terms of SI units (meter, kilogram, and so on), while most FRC teams are US-based and most commonly use imperial units. wpimath does a good job of noting unit types in method names and argument names; however, it still relies on users properly converting values (and knowing they even have to do so). # API There are really only two core classes in this library: `Unit` and `Measure`. A `Unit` represents some dimension like distance or time. `Unit` is subclassed to define specific dimensions (eg `Distance` and `Time`) and those subclasses are instantiated to defined particular units in those dimensions, such as `Meters` and `Feet` being instances of the `Distance` class. A `Measure` is a value tied to a particular dimension like distance and knows what unit that value is tied to. `Measure` has two implementations - one immutable and one mutable. The `Measure` interface only defines *read-only* operations; any API working with measurements should use the interface. The default implementation is `ImmutableMeasure`, which only implements those read-only operations and is useful for tracking constants. `MutableMeasure` also adds some methods that will allow for mutation of its internal state; this class is intended for use for things like sensors and controllers that track internal state and don't want to allocate new `Measure` objects every time something like `myEncoder.getDistance()` is called. However, the APIs for those methods should still only expose the read-only `Measure` interface so users can't (without casting or reflection) change the internal values. A `Units` class provides convenient definitions for most of the commonly used unit types, such as `Meters`, `Feet`, and `Milliseconds`. I recommend static importing these units eg `import static edu.wpi.first.units.Units.Meters`) so they can be used like `Meters.of(1.234)` instead of `Units.Meters.of(1.234)` # Examples These examples are admittedly contrived. Users shouldn't be interacting much with measure objects themselves, since wpimath and wpilibj classes will be updated to support working with them; users will often just have to take a `Measure` output from one place (such as an encoder) and feed it as input to something else (such as a PID controller or kinematics model) ```java // Using raw units Encoder encoder = ... int kPulsesPerRev = 2048; double kWheelDiameterMeters = Units.inchesToMeters(6); double kGearRatio = 10.86; // always have to remember this encoder will output in meters! encoder.setDistancePerPulse(kWheelDiameterMeters * Math.PI / (kGearRatio * kPulsesPerRev)); Command driveDistance(double distance) { // have to know the distance argument needs to be in meters! return run(this::driveStraight).until(() -> encoder.getDistance() >= distance); } // Oops! This will go 16 feet, not 5! Command driveFiveFeet = driveDistance(5); Command driveOneMeter = driveDistance(1); ``` ```java // Using wpiunits Encoder encoder = ... int kPulsesPerRev = 2048; Measure<Distance> kWheelDiameter = Inches.of(6); double kGearRatio = 10.86; encoder.setDistancePerPulse(kWheelDiameter.times(Math.PI).divide(kGearRatio * kPulsesPerRev)); Command driveDistance(Measure<Distance> distance) { // Measure#gte automatically handles unit conversions return run(this::driveStraight).until(() -> encoder.getDistance().gte(distance)); } // Users HAVE to be explicit about their units Command driveFiveFeet = driveDistance(Feet.of(5)); Command driveOneMeter = driveDistance(Meters.of(1)); ``` ```java SmartDashboard.putNumber("Temperature (C)", pdp.getTemperature().in(Celsius)); SmartDashboard.putNumber("Temperature (F)", pdp.getTemperature().in(Fahrenheit)); ``` ```java var InchSecond = Inch.mult(Second); // new combined unit types can be user-defined var InchPerSecond = Inch.per(Second); PIDController<Distance, ElectricPotential> heightController = new PIDController<>( /* kP */ Volts.of(0.2).per(Inch), /* kI */ Volts.of(0.002).per(InchSecond), /* kD */ Volts.of(0.008).per(InchPerSecond) ); var elevatorTop = Feet.of(4).plus(Inches.of(6.125)); elevatorMotor.setVoltage(heightController.calculate(encoder.getDistance(), elevatorTop)); ```
2023-07-23 17:18:17 -04:00
public class Energy extends Unit<Energy> {
[docs] Build with JavaDoc 17 and add missing docs (#6220) Co-authored-by: Sam Carlberg <sam.carlberg@gmail.com>
2024-01-19 23:42:09 -08:00
Energy(
[wpiunits] Change units to track their base unit, instead of their base class (#6342) Unit objects now have a reference to the base unit from which they're derived. Constructing a unit object without specifying a base unit implicitly signifies that it's its own base unit, eg new Angle(null, 1, "Radian", "rad") would be the base angle unit of radians, while new Angle(Radians, 2 * PI, "Rotation", "R") would be a new angle unit based on radians. This fixes much of the hacky code surrounding the derived unit types Velocity, Per, and Mult, but is a breaking change for any user code that defines custom unit classes or uses the anonymous unit type.
2024-05-12 09:15:56 -04:00
Energy baseUnit,
UnaryFunction toBaseConverter,
UnaryFunction fromBaseConverter,
String name,
String symbol) {
super(baseUnit, toBaseConverter, fromBaseConverter, name, symbol);
[wpiunits] Add subproject for a Java typesafe unit system (#5371) # Background Unit safety has always been a problem in WPILib. Any value corresponding to a physical measurement, such as current draw or distance traveled, is represented by a bare number with no unit tied to it; it's up to the programmer to know what units they're working and take care to remember that while working on their robot program. This leads to bugs when programmers accidentally mix units without knowing, or measure something (such as a wheel diameter) in one unit and program using another. `wpiunits` is intended to eliminate that class of bugs. Another source of friction is the controllers and models in `wpimath` that expect all inputs to be in terms of SI units (meter, kilogram, and so on), while most FRC teams are US-based and most commonly use imperial units. wpimath does a good job of noting unit types in method names and argument names; however, it still relies on users properly converting values (and knowing they even have to do so). # API There are really only two core classes in this library: `Unit` and `Measure`. A `Unit` represents some dimension like distance or time. `Unit` is subclassed to define specific dimensions (eg `Distance` and `Time`) and those subclasses are instantiated to defined particular units in those dimensions, such as `Meters` and `Feet` being instances of the `Distance` class. A `Measure` is a value tied to a particular dimension like distance and knows what unit that value is tied to. `Measure` has two implementations - one immutable and one mutable. The `Measure` interface only defines *read-only* operations; any API working with measurements should use the interface. The default implementation is `ImmutableMeasure`, which only implements those read-only operations and is useful for tracking constants. `MutableMeasure` also adds some methods that will allow for mutation of its internal state; this class is intended for use for things like sensors and controllers that track internal state and don't want to allocate new `Measure` objects every time something like `myEncoder.getDistance()` is called. However, the APIs for those methods should still only expose the read-only `Measure` interface so users can't (without casting or reflection) change the internal values. A `Units` class provides convenient definitions for most of the commonly used unit types, such as `Meters`, `Feet`, and `Milliseconds`. I recommend static importing these units eg `import static edu.wpi.first.units.Units.Meters`) so they can be used like `Meters.of(1.234)` instead of `Units.Meters.of(1.234)` # Examples These examples are admittedly contrived. Users shouldn't be interacting much with measure objects themselves, since wpimath and wpilibj classes will be updated to support working with them; users will often just have to take a `Measure` output from one place (such as an encoder) and feed it as input to something else (such as a PID controller or kinematics model) ```java // Using raw units Encoder encoder = ... int kPulsesPerRev = 2048; double kWheelDiameterMeters = Units.inchesToMeters(6); double kGearRatio = 10.86; // always have to remember this encoder will output in meters! encoder.setDistancePerPulse(kWheelDiameterMeters * Math.PI / (kGearRatio * kPulsesPerRev)); Command driveDistance(double distance) { // have to know the distance argument needs to be in meters! return run(this::driveStraight).until(() -> encoder.getDistance() >= distance); } // Oops! This will go 16 feet, not 5! Command driveFiveFeet = driveDistance(5); Command driveOneMeter = driveDistance(1); ``` ```java // Using wpiunits Encoder encoder = ... int kPulsesPerRev = 2048; Measure<Distance> kWheelDiameter = Inches.of(6); double kGearRatio = 10.86; encoder.setDistancePerPulse(kWheelDiameter.times(Math.PI).divide(kGearRatio * kPulsesPerRev)); Command driveDistance(Measure<Distance> distance) { // Measure#gte automatically handles unit conversions return run(this::driveStraight).until(() -> encoder.getDistance().gte(distance)); } // Users HAVE to be explicit about their units Command driveFiveFeet = driveDistance(Feet.of(5)); Command driveOneMeter = driveDistance(Meters.of(1)); ``` ```java SmartDashboard.putNumber("Temperature (C)", pdp.getTemperature().in(Celsius)); SmartDashboard.putNumber("Temperature (F)", pdp.getTemperature().in(Fahrenheit)); ``` ```java var InchSecond = Inch.mult(Second); // new combined unit types can be user-defined var InchPerSecond = Inch.per(Second); PIDController<Distance, ElectricPotential> heightController = new PIDController<>( /* kP */ Volts.of(0.2).per(Inch), /* kI */ Volts.of(0.002).per(InchSecond), /* kD */ Volts.of(0.008).per(InchPerSecond) ); var elevatorTop = Feet.of(4).plus(Inches.of(6.125)); elevatorMotor.setVoltage(heightController.calculate(encoder.getDistance(), elevatorTop)); ```
2023-07-23 17:18:17 -04:00
}
[wpiunits] Change units to track their base unit, instead of their base class (#6342) Unit objects now have a reference to the base unit from which they're derived. Constructing a unit object without specifying a base unit implicitly signifies that it's its own base unit, eg new Angle(null, 1, "Radian", "rad") would be the base angle unit of radians, while new Angle(Radians, 2 * PI, "Rotation", "R") would be a new angle unit based on radians. This fixes much of the hacky code surrounding the derived unit types Velocity, Per, and Mult, but is a breaking change for any user code that defines custom unit classes or uses the anonymous unit type.
2024-05-12 09:15:56 -04:00
Energy(Energy baseUnit, double baseUnitEquivalent, String name, String symbol) {
super(baseUnit, baseUnitEquivalent, name, symbol);
[wpiunits] Add subproject for a Java typesafe unit system (#5371) # Background Unit safety has always been a problem in WPILib. Any value corresponding to a physical measurement, such as current draw or distance traveled, is represented by a bare number with no unit tied to it; it's up to the programmer to know what units they're working and take care to remember that while working on their robot program. This leads to bugs when programmers accidentally mix units without knowing, or measure something (such as a wheel diameter) in one unit and program using another. `wpiunits` is intended to eliminate that class of bugs. Another source of friction is the controllers and models in `wpimath` that expect all inputs to be in terms of SI units (meter, kilogram, and so on), while most FRC teams are US-based and most commonly use imperial units. wpimath does a good job of noting unit types in method names and argument names; however, it still relies on users properly converting values (and knowing they even have to do so). # API There are really only two core classes in this library: `Unit` and `Measure`. A `Unit` represents some dimension like distance or time. `Unit` is subclassed to define specific dimensions (eg `Distance` and `Time`) and those subclasses are instantiated to defined particular units in those dimensions, such as `Meters` and `Feet` being instances of the `Distance` class. A `Measure` is a value tied to a particular dimension like distance and knows what unit that value is tied to. `Measure` has two implementations - one immutable and one mutable. The `Measure` interface only defines *read-only* operations; any API working with measurements should use the interface. The default implementation is `ImmutableMeasure`, which only implements those read-only operations and is useful for tracking constants. `MutableMeasure` also adds some methods that will allow for mutation of its internal state; this class is intended for use for things like sensors and controllers that track internal state and don't want to allocate new `Measure` objects every time something like `myEncoder.getDistance()` is called. However, the APIs for those methods should still only expose the read-only `Measure` interface so users can't (without casting or reflection) change the internal values. A `Units` class provides convenient definitions for most of the commonly used unit types, such as `Meters`, `Feet`, and `Milliseconds`. I recommend static importing these units eg `import static edu.wpi.first.units.Units.Meters`) so they can be used like `Meters.of(1.234)` instead of `Units.Meters.of(1.234)` # Examples These examples are admittedly contrived. Users shouldn't be interacting much with measure objects themselves, since wpimath and wpilibj classes will be updated to support working with them; users will often just have to take a `Measure` output from one place (such as an encoder) and feed it as input to something else (such as a PID controller or kinematics model) ```java // Using raw units Encoder encoder = ... int kPulsesPerRev = 2048; double kWheelDiameterMeters = Units.inchesToMeters(6); double kGearRatio = 10.86; // always have to remember this encoder will output in meters! encoder.setDistancePerPulse(kWheelDiameterMeters * Math.PI / (kGearRatio * kPulsesPerRev)); Command driveDistance(double distance) { // have to know the distance argument needs to be in meters! return run(this::driveStraight).until(() -> encoder.getDistance() >= distance); } // Oops! This will go 16 feet, not 5! Command driveFiveFeet = driveDistance(5); Command driveOneMeter = driveDistance(1); ``` ```java // Using wpiunits Encoder encoder = ... int kPulsesPerRev = 2048; Measure<Distance> kWheelDiameter = Inches.of(6); double kGearRatio = 10.86; encoder.setDistancePerPulse(kWheelDiameter.times(Math.PI).divide(kGearRatio * kPulsesPerRev)); Command driveDistance(Measure<Distance> distance) { // Measure#gte automatically handles unit conversions return run(this::driveStraight).until(() -> encoder.getDistance().gte(distance)); } // Users HAVE to be explicit about their units Command driveFiveFeet = driveDistance(Feet.of(5)); Command driveOneMeter = driveDistance(Meters.of(1)); ``` ```java SmartDashboard.putNumber("Temperature (C)", pdp.getTemperature().in(Celsius)); SmartDashboard.putNumber("Temperature (F)", pdp.getTemperature().in(Fahrenheit)); ``` ```java var InchSecond = Inch.mult(Second); // new combined unit types can be user-defined var InchPerSecond = Inch.per(Second); PIDController<Distance, ElectricPotential> heightController = new PIDController<>( /* kP */ Volts.of(0.2).per(Inch), /* kI */ Volts.of(0.002).per(InchSecond), /* kD */ Volts.of(0.008).per(InchPerSecond) ); var elevatorTop = Feet.of(4).plus(Inches.of(6.125)); elevatorMotor.setVoltage(heightController.calculate(encoder.getDistance(), elevatorTop)); ```
2023-07-23 17:18:17 -04:00
}
}
Reference in New Issue Copy Permalink