Java units API rewrite

[SamCarlberg]

Java generics are too limited to do what we need. This refactors generic code previously in Unit and Measure into unit-specific classes that can have unit-safe math operations (notably, times and divide) that can return values in known units instead of a wildcarded Measure<?>

Unit-specific measure implementations are automatically generated by ./wpiunits/generate_units.py, which generates generic interfaces and mutable and immutable implementations of those interfaces. These make up the bulk of the diff of this PR (approximately 9300 LOC)

This also adds units for angular and linear velocities, accelerations, and momenta; moment of inertia; and torque

Supersedes #6684, #6696, #6710, #6778

[github-actions]

This PR modifies commands. Please open a corresponding PR in Python Commands and include a link to this PR.

[spacey-sooty]

Can't speak for the internals but the new API looks much nicer 🙂
Can't wait to use it for my team!

[PeterJohnson]

Does per() no longer take a quantity but rather a unit type?

[narmstro2020]

Java generics are too limited to do what we need. This refactors generic code previously in Unit and Measure into unit-specific classes that can have unit-safe math operations (notably, times and divide) that can return values in known units instead of a wildcarded Measure<?>

Unit-specific measure implementations are automatically generated by ./wpiunits/generate_units.py, which generates generic interfaces and mutable and immutable implementations of those interfaces. These make up the bulk of the diff of this PR (approximately 9300 LOC)

This also adds units for angular and linear velocities, accelerations, and momenta; moment of inertia; and torque

Supersedes #6684, #6696, #6710, #6778

Never been happier to have been superseded. Good work

[PeterJohnson]

Needs conflicts resolved.

[SamCarlberg]

A raw cast is required here due to conflicts with the wildcarded return supertype:

wpiunits/src/main/java/edu/wpi/first/units/AccelerationUnit.java:59: error: incompatible types: Measure<CAP#1> cannot be converted to Acceleration<D>
    return (Acceleration<D>) super.zero();
                                       ^
  where D is a type-variable:
    D extends Unit declared in class AccelerationUnit
  where CAP#1 is a fresh type-variable:
    CAP#1 extends PerUnit<VelocityUnit<D>,TimeUnit> from capture of ? extends PerUnit<VelocityUnit<D>,TimeUnit>

[viggy96]

Measurands (which is what users often interact with, what variable types are, etc) is simply the raw name now (eg “Current”), so to disambiguate it makes sense that the actual unit types need to have suffixes (“CurrentUnit”). The other approach would be to add a suffix to the measurand, and be more verbose there (“CurrentMeasure”).

I see, so from a programmer perspective, we still get the raw name?

[SamCarlberg]

I see, so from a programmer perspective, we still get the raw name?

Yes, you would do something like this with the new API:

Voltage appliedVoltage = motor.getAppliedVoltage();
Current draw = motor.getCurrent();
Power totalPower = appliedVoltage.times(draw);

Instead of this (with the original units API):

Measure<Voltage> appliedVoltage = motor.getAppliedVoltage();
Measure<Current> draw = motor.getCurrent();
Measure<Power> totalPower = (Measure<Power>) appliedVoltage.times(draw);

Or this (if you want to use generic types for some reason). Note that this approach still loses out on type-safe math operations

Measure<VoltageUnit> appliedVoltage = motor.getAppliedVoltage();
Measure<CurrentUnit> draw = motor.getCurrent();
Measure<PowerUnit> totalPower = (Measure<PowerUnit>) appliedVoltage.times(draw);

[KangarooKoala]

Nothing blocking, just a few wonderings.

[KangarooKoala]

Did a search for Measure< through the diff and found the following parameters that still use X instead of Measure<XUnit> on 7365901:

• Command.withTimeout()
• Commands.waitTime()
• new WaitCommand()
• new SysIdRoutine.Config() (2 overloads)
• new SysIdRoutine.Mechanism() (2 overloads)
• LEDPattern.scrollAtRelativeSpeed() (Up to you how to handle asPeriod(), since that's the only usage of it in the current code, but it might be worth it to keep it even without immediate uses)
• LEDPattern.scrollAtAbsoluteSpeed()
• LEDPattern.blink() (2 overloads)
• LEDPattern.breathe()
• LEDPattern.atBrightness()
• TimedRobot.addPeriodic() (2 overloads)
• new ChassisSpeeds()
• ChassisSpeeds.discretize()
• ChassisSpeeds.fromFieldRelativeSpeeds()
• ChassisSpeeds.fromRobotRelativeSpeeds()
• new DifferentialDriveOdometry()
• DifferentialDriveOdometry.resetPosition()
• new DifferentialDriveWheelSpeeds()
• DifferentialDriveWheelSpeeds.desaturate()
• new MecanumDriveWheelPositions()
• new MecanumDriveWheelSpeeds()
• SwerveDriveKinematics.desaturateWheelSpeeds()
• new SwerveDriveKinematics()
• new TrajectoryConfig()
• TrajectoryConfig.setStartVelocity()
• TrajectoryConfig.setEndVelocity()
• new TrapezoidProfile.State()

[KangarooKoala]

Just out of curiosity, is there some reason this can't be Measure<LinearVelocityUnit> or maybe Measure<VelocityUnit<DistanceUnit>>?

[SamCarlberg]

Because of Java generic interoperability. This constructor accepts a measure of any unit that extends from PerUnit<DistanceUnit, TimeUnit - which means LinearVelocity, Per<DistanceUnit, TimeUnit>, or Velocity<DistanceUnit> would all be acceptable input types

[SamCarlberg]

The downside to wildcard bounds is that you can't use in, since the compiler doesn't know what specific subtype will be stored in the measure

[SamCarlberg]

Did a search for Measure< through the diff and found the following parameters that still use X instead of Measure<XUnit>

Thanks for checking it over.

I added the .ofNative method later to allow for a unit-specific object to be returned:

PerUnit<VoltageUnit, DistanceUnit> VoltsPerMeter = Volts.per(Meter);
var measure = VoltsPerMeter.ofNative(1.0); // => returns Per<VoltageUnit, DistanceUnit>
measure.in(VoltsPerMeter); // No cast is required

Which, if used instead of .of, means we have more information at compile time and won't be dealing with weird units. Which would mean wildcard bounds wouldn't be necessary. If it turns out we need generic parameters in the future, we can relax the types while still maintaining compatibility. But that won't be possible in the other direction (convert generic Measure to concrete types like Time or Voltage).

I believe it'd actually be better to use the unit-specific types at first, and relax later if necessary.