Quantity API

[lucascolley]

Ideas for a minimal standard Quantity API, to work with the Unit API.

[nstarman]

1. Quantity(Protocol[ValueT, UnitT]) object.
2. with standardized 2 fields: e.g. .value, .unit
3. parametrized by the type of the value and the unit. This will statically say whether a Quantity has a Jax array value and Pint units, versus a PyTorch value and Astropy units.
4. QuantityArray(Quantity[ValueT, UnitT], Array, Protocol) object that is the intersection type of the Quantity and Array API so that the Quantity object satisfies the Array API, regardless of whether the .value does.
5. Unit conversion, in accordance with Unit API.

[lucascolley]

In light of https://github.com/orgs/quantity-dev/discussions/4, on (1):

• Quantity(Protocol[ValueT, UnitT[KindT]]) object. If the unit and the kind have the same dimensionality, or the kind is unspecified, a Quantity object should be constructed. Otherwise, some sort of dimensionality exception should be raised.

In light of https://github.com/orgs/quantity-dev/discussions/2#discussioncomment-11780525, on (3):

• float, complex, and array API standard arrays must be accepted for the value. So far undecided on int and bool, but consider Quantity API astropy/quantity-2.0#23 (comment).

[andrewgsavage]

on 4, pint uses a single Quantity class for both scalars and arrays. There's been a few discussions on splitting into two classes but they haven't had a good reason to make the split.

What do you mean by parameterized by in 3?

[nstarman]

on 4, pint uses a single Quantity class for both scalars and arrays. There's been a few discussions on splitting into two classes but they haven't had a good reason to make the split.

That's fine :) (4) is a statement about how the Quantity acts under operations, e.g. addition, not what the value type is. That's why it's parametrized by a generic ValueT, not one constrained to arrays. So the value could even be a string! As long as the Quantity (not necessarily the value) is Array-like, then it obeys the Quantity and Array APIs. Now I wouldn't recommend the value being a string, but that is up to implementing libraries. We purposefully don't mandate the value type.

QuantityValueArray: TypeAlias = Quantity[Array, UnitT]
QuantityArrayValueArray: TypeAlias = QuantityArray[Array, UnitT]

Would be array-valued quantity types.

[dalito]

One thing that also pint does not yet do right is considering quantity kinds (see hgrecco/pint#1967). Two quantities may have the same units but can be of different quantity kind (so they should not be added although they have the same unit). For a new API it may be worth to consider quantity kind support from the beginning.

[nstarman]

So Quantity(Protocol[ValueT, UnitT, KindT])?

Would the kind be associated with the Quantity or the Unit? Quantity(Protocol[ValueT, UnitT[KindT]])?

[lucascolley]

Would the kind be associated with the Quantity or the Unit? Quantity(Protocol[ValueT, UnitT[KindT]])?

I think tying it to the unit makes sense, yes, since (kind, unit) pairs can be reasoned about without an associated value. But it should be accessible at the Quantity level, since two quantities can have the same kind but different units, so one may want to compare the kinds regardless of the units.

And each kind is associated with one unique dimensionality (apart from the special case of kind being unspecified).

[lucascolley]

In other words, (u, k) is a valid unit-kind pair iff (u.dimensionality == k.dimensionality or k is the "unspecified" kind). And a quantity can have any valid unit-kind pair.

[andrewgsavage]

there is also the concept of the affine space

I had avoided raising kinds and affine space as it will be difficult to standardise on a common API when we don't have an implementation in python! The referenced paper/library is also very new

[nstarman]

Thanks for sharing! I would be very interested to hear how we can keep the developing API compatible with this rigorous reference.
Could you write out the dunder methods for Quantity and QuantityPoint?

[ngoldbaum]

I think .to(new_unit) should be standardized. There should also be a way to do unit conversions in-place, but the default should copy.

It might also be nice to standard e.g. to_SI, to_mks, or to_cgs which are often very useful.

[ngoldbaum]

Another thing that I think might need to be considered if you want to bring in unit systems and non-SI units is that converting between unit systems like that is not necessarily guaranteed to always work. In unyt we tried to accommodate common conversions from SI to CGS electromagnetic units (e.g. converting between Tesla and Gauss, which is well-defined) but in general it's not well-defined to do that sort of thing.

[nstarman]

Converting between composed units, agreed, but converting between base units?
E.g. a (not-efficient) recipe is
Q.unit -> {dimension: base_unit} -> {dimension: convert_unit(unit, UnitSystem.base_units[dimension])} -> CompositeUnit -> NewQ

[ngoldbaum]

It's only possible to write "equivalencies" between guassian and SI electromagnetic units. The correct conversion depends on the context and it's impossible for a unit system to automatically guess what the correct context is, because Maxwell's equations have a different formulation.

Admittedly gaussian E&M units are niche, but at least in astronomy tend to be used in some situations.

[phlptp]

One other thing I do deal with rather regularly is per-unit value. There are technically dimensionless quantities but the operations with them are very much tied to the original units. This is particularly useful in power systems, but also in a few other contexts. The unit library I am working on also has a notion of commodities, which brings in the possibility of some otherwise intractable conversions, as with material densities volume to mass conversion become possible, or for some energy sources, mass or volume to energy conversions are common.

[andrewgsavage]

equivalencies look the similar in pint and unyt, both can be added as arguements in .to
https://unyt.readthedocs.io/en/stable/usage.html
https://pint.readthedocs.io/en/stable/user/contexts.html

@phlptp could you give worked examples of those?

[andrewgsavage]

Need to decide on the attribute names where they differ between libraries at present,

• .units or .unit
• .magnitude or .value(s)
• .m_as or to_values

any others? are there any reasons to choose one over another?

[nstarman]

It's almost always obvious in context that to has to do with units

.to(dtype) is also a good pattern. Avoided for a reason. With a slightly longer name we avoid name collision. Our Quantities are not the only context!

[ngoldbaum]

IMO we should be putting the unit metadata in the dtype but that's a whole other discussion...

[andrewgsavage]

new_value = x.to_unit(new_unit).value

Code like this is why I prefer the spelling to instead of to_unit. It's almost always obvious in context that to has to do with units and often spelling it to_units leads to unnecessary duplication of the signal that the function deals with units.

Yes, at present is almost always obvious from context. However I hope adopting a common API would allow downstream libraries to support units that haven't considered it worthwhile due to the multiple options. At which point new_value = x.to("m") could be read as to meters, or to timedelta.

[nstarman]

IMO we should be putting the unit metadata in the dtype but that's a whole other discussion...

Agreed. I wish that were possible in a non-package-specific way!

[lucascolley]

I wish that were possible in a non-package-specific way!

I mean, eventually it could be standardised as an array API extension! But I think the timeline for that is years, as adoption would have to spread to the common array libraries.

[andrewgsavage]

I think we should move on to a design document synthesizing the results of the discussion and sending out polls voting on non-resolved aspects, e.g. should the attribute be called .dimension or .dimensions. Also, I would suggest actually starting with the Quantity API. IMO it's easier to design "down" than "up". And since isinstance(x, QuantityProtocol) only checks the existence of attributes/methods, not their types, it's easy to have placeholder protocols for Unit, etc that get filled in when we move on to the Units API. WDYT?

Originally posted by @nstarman in #1 (reply in thread)
Sounds good,
What are the non resolved quantity aspects for polling?

• Singular/Pluralised attributes
• whether to include kinds
• to or to_unit
• to_SI, to_mks or to_unit(list_of_units) or or to_unit(Group*)

*would need a Group protocol added to the API

[nstarman]

Can you provide a MWE of the Group ? What might it's Protocol look like?