Clarify behavior of Quantity arithmetic on shifted units

[desruisseaux]

Clarify the behavior of Q₁ + Q₂ or Q * n (with n a unitless number) when the unit of measurement of Q, Q₁ or Q₂ is "shifted". Example of shifted units are:

• Temperature in Celsius, with °C defined as K - 273.15 K.
• Density sigma-t, with σT defined as ρ - 1000 kg/m³ (used in oceanography).
• Other shifted units in other scientific domains?

Taking temperature in °C as an example, addition can happen in at least two different contexts:

• T₁ + T₂ : there is some legitimate uses for such additions, but they are rare.
• T + ΔT : a more common case.

In the T₁ + T₂ case, both quantities must be converted to K before addition. So 20°C + 10°C = 303.15°C because T₂ = 283.15 K. In the T + ΔT case, 10°C is an increment (ΔT). So in this later case 20°C + 10°C = 30°C.

In current API, there is no way to know if a number is an absolute quantity or an increment. So there is no way to know if we are in the T₁ + T₂ case or in the T + ΔT case. If we want to differentiate those quantities, we may need to:

• Add a new method in UnitConverter: deltaConvert(double), which convert the given value without applying the offset. This is similar to deltaTransform in java.awt.geom.AffineTransform.
• Introduce a new interface: Increment<Q extends Quantity<Q>>.
• Defines arithmetic rules as below: in any arithmetic operation like M₁ + M₂ or M * n, implementation SHALL do the following steps at least conceptually (implementations are allowed to avoid conversions in some cases provided that the numerical result is the same):
  • All M values SHALL be converted to system units before addition or multiplication.
    • Conversions of Quantity instances shall be done with UnitConverter.convert(…).
    • Conversions of Increment instances shall be done with UnitConverter.deltaConvert(…).
  • Result type is defined by the following table:
    • Quantity + Quantity = Quantity
    • Quantity + Increment = Quantity
    • Increment + Quantity = Quantity
    • Increment + Increment = Increment
    • Quantity * n = Quantity
    • Increment * n = Increment
  • Result value is converted back to the unit of measurement of the first operand (M₁).
    • Using UnitConverter.convert(…) if the result type is Quantity.
    • Using UnitConverter.deltaConvert(…) if the result type is Increment.

Requires #98
Requires #99

[desruisseaux]

Note: see https://rechneronline.de/temperatur/temperature.php for example of operations on temperatures. Even if the above proposal is not apply, at least we should add tests making sure that 20°C + 10°C = 303.15°C, not 30°C, unless we clearly state in the javadoc a policy about when quantities are considered increments.

[keilw]

This sounds rather intrusive for adding it to the API and introduce something like javax.measure.Increment or add a new method to the UnitConverter interface in that same package. Especially if it does not apply to at least 90% of all quantities (in javax.measure.quantity plus e.g. si-quantity or systems-quantity)
The mentioned other example Density is part of si-quantity but it does not seem used by any of the unit systems yet.
We decided to keep Range or Measurement in implementation modules like Indriya. Or ComparableQuantity which in theory (Java SE8 and above now) could even be merged into Quantity, but I'm not sure about that either (will ask this in a separate ticket)
So while using Comparable, Serializable or Prefix apply to pretty much every quantity (maybe the only ones where Prefix may not make much sense are Temperature and a few others)
So a gut feeling tells me, the small amount of quantities (out of at least 60 in the 3 quantity modules/packages as of now, how many are confirmed to need Increment?) does not justify an extra API element, but it seems perfectly fine to define it similar to Range or ComparableQuantity.

Beside UnitConverter.convert() does not return a Quantity, so adding a method that does would break with its current purpose. If AddConverter (used between CELSIUS and KELVIN right now) does not work for this case, why not introduce another UnitConverter implementation that does? If a Quantity or similar element like Increment has to be applied and returned, the QuantityFunctions class looks like a good place for methods like delta() etc.

[desruisseaux]

I never proposed to have a method returning Quantity in UnitConverter. I proposed a deltaConvert(double) method, returning a double like the existing convert(double).

The other example is not Density, but sigma-t. Density has nothing special compared to other units; it sigma-t which is a shifted unit.

Yes, addition of an Increment interface is intrusive. But conceptually it applies to all units; not only temperature and sigma-t. It is not apparent for other units because in their case, Quantity and Increment have the same behavior.

The situation is not comparable to Range. Range can be defined in a totally independent way; supporting ranges in an external API do not require any change in JSR-363 API. But the situation is not the same for Increment. If arithmetic operations are defined in Quantity, then they need to define precisely their behavior with shifted units - current API is not satisfying. We can either talk about increment in the javadoc, or introduce an explicit Increment type.

[keilw]

The wording sounded a bit like the interface would be expected as a return value. Nevertheless if there were two methods there it had a rather significant impact on the Spec and other places to clarify how to use them and when. It is a bit like the new fireAsync() methods introduced with CDI 2 that are also applied and used in parallel to those already existing. The overhead in the API would not be that big, but Spec, RI and TCK would have to be changed significantly. Not entirely sure, if it had to be on the top level, but if you envision a Quantity.add(Increment) method then it must be, see Prefix and its relation to Unit.

Similar to CDI 2 I would probably call such new method UnitConverter.convertDelta() or UnitConverter.convertIncrement() rather than deltaConvert().

While Range could also be done using e.g. Google Guava, the Measurement interface is something e.g. OSGi Measurement has defined in its core API.

[keilw]

Wonder, if someone from the SmartHome team like @htreu or @kaikreuzer might help with that at least as Contributors?

[desruisseaux]

I'm find with convertDelta or convertIncrement method names.

Introducing an explicit Increment interface is one possibility. Another possibility is to not introduce new interface an introduce the following methods in Quantity instead:

• addIncrement(Quantity)
• subtractIncrement(Quantity)
• multiplyIncrement(Quantity)
• divideIncrement(Quantity)

[keilw]

While it adds extra methods that may actually be less intrusive and complex. #96 asked about possibly adding a few methods now in ComparableQuantity into the API. If the result of these 4 candidates is always a Quantity, would method overloading with add(Quantity, OperationType) also work? OperationType would simply be an enum either standalone or a static inner type in Quantity.

Let's do a quick vote.
Please state your preference for the result and argument of "increment" operations:

[keilw]

A) Add a new Increment type to the API.

[keilw]

B) Reuse Quantity and add new methods like addIncrement(Quantity) or add(Quantity, OperationType.INCREMENT) to it.

[keilw]

I hope others will also cast their vote. I voted B also because the whole formatting topic for quantities would get even more complicated if we had to differentiate between Quantity and Increment.