Improve the Java Units Library with additional methods and unit types

[bhall-ctre]

Coming from the C++ units library, the Java units library has a few rough edges that can occasionally make working with the library difficult. Below are some suggestions for unit and feature additions to improve the usability of the library, based on both my experience with the library so far and our requirements for the library at CTRE.

Unit Additions

• Frequency
  • Hertz (should this be a Velocity<Dimensionless>?)
• Magnetic Field Strength
  • Tesla, Millitesla, Microtesla
• Force and Torque
  • Add force and torque units to wpiunits #6676

Functionality Improvements

Unfortunately, there may be some limitations of Java that prevent all these suggestions from being implemented, but I believe we should add whatever we can.

• Add support for dividing a Measure<U1> by a Measure<U2>
  • Edit: already fixed in [wpiunit] Add Measure.divide(Measure<U2>) #6611
• Add inverse() to Measure and Unit
  • For example, I should be able to take a time in Seconds and invert it to become a frequency in Hertz.
  • There may be technical challenges with this and dividing two measures, as doing Value.of(1).divide(meas) would also be a method of creating an inverse. Likewise, Meters.mult(Seconds.inverse()) may not give the desired type of Velocity<Distance>, although that can probably be handled in documentation.
• Add squared() and cubed() to Unit
  • This would just be an easy way to get square and cubic units. For example, Meters.squared() is equivalent to Meters.mult(Meters).
  • However, this could also be a footgun, as Rotations.per(Second.squared()) may not result in a type of Velocity<Velocity<Angle>>.

[narmstro2020]

I love the Java units library.

One of the barriers to entry I feel is writing a method that returns a type. That type is something like acceleration. The type signature for the method is Measure<Velocity<Velocity<Distance>>>>.

This is a little inelegant and people will just look away and handle units in their own way. However this seems more to be due to the limitations of Java than anything else. Adding a unit for force and torque is fine, but a method returning this type would have a signature is ridiculous.

The library itself seems to have some issues separating Dimension, Unit, and Physical quantity.

Torque and Energy are two physical quantities, they are measured with the same dimension. That dimension can be captured in a variety of named units that are also characterized by a dimension. I feel like instead of Measure<Unit> it should be more Measure<Dimension>. Each dimension should have its own list of units. Internally a dimension can either be a base dimension (like mass or current, or time, I'm going by the SI unit definition here) or a composite dimension like Nm or J/S. Under the hood every dimension is a product of these base dimensions, quotients being negative integer powers. Nm is just Mass * Distance * Distance * Second^-1 * Second^-1.

[WispySparks]

I agree with the separation being confusing, for example the library has Power as its own sort of unit when it could be work/energy over time. Same thing with the torque units, I feel like it would be cleaner to have Torque be its own unit instead of deriving it from the other base units because it would become extremely cumbersome to define a method to take in or return some unit of torque.

[narmstro2020]

So every dimension in SI is built up of integer power of base units. One can remove the unit concept entirely from the picture and think in terms of dimension

Torque and Energy are measurable things.

A measurable thing has a dimension.

Units are when we go from dimension to measurements of those measurable things.

The main dimensions are time, mass, electric current, temperature, substance and luminous intensity.
I'd argue not using the last two. I can't imagine needing moles in FRC. Luminous intensity is possible, but could be expanded up later.

[PeterJohnson]

The type signature for the method is Measure<Velocity>>.

You mean Measure<Velocity<Velocity<Distance>>>?

However this seems more to be due to the limitations of Java than anything else.

Yes, Java's type system is very limiting in what we can do for units. Unlike C++, there is no ability in Java to define type aliases like using Acceleration = Velocity<Velocity<Distance>> to simplify function signatures or the generic types in general, thus the proliferation of specific "units" that aren't really base units. The fact that generics are not reified in Java also is a limiter, so we can't just overload functions based on the generic type, or do things at runtime based on the generic type. This is compounded by the fact we do not want to use immutable values (thus the separation of Measure and MutableMeasure) due to memory allocation / GC concerns.

I feel like instead of Measure it should be more Measure.

I think something was lost here? You need to backtick quote it (``) to preserve the angle brackets.

[narmstro2020]

Ah. I lost the angle brackets.

Measure<Unit> should be Measure<Dimension> that might help.

[narmstro2020]

We also like the pattern Meters.of(magnitude) to make a measurement of that particular unit and Measure.in(Unit) to extract the magnitude. These require static methods which means that Units need to be classes. I'll tool around with this some and post a link here in the coming week.

[PeterJohnson]

These require static methods which means that Units need to be classes.

I'm confused... those already exist in the library? Units.Meters.of(magnitude).

[narmstro2020]

Sorry for the confusion. I know they exist. I'm just making a comment about the utility of those methods. Any alterations in the existing codebase would have a hard time justifying not keeping those methods. They almost make it like using the C++ library.