Design doc

[andrewgsavage]

Following from https://github.com/orgs/quantity-dev/discussions/1#discussioncomment-11930701
Here's a start at a design doc
https://github.com/quantity-dev/quantity-api/blob/docs/docs/quantity_design.md

and a draft of the protocol:
quantity-dev/quantity-api#1

edit: moved to PRs from https://docs.google.com/document/d/1jBiUrqn8V2Fgpxcbp8sUbS8k10jrU-RavLI4L9J25sk/edit?usp=sharing

[nstarman]

Thank you for taking this on! I started on the Proposed Quantity Design which has all the stuff we need to vote on.

[neutrinoceros]

I have a quick question for you:
Is this

class Quantity[V, U](Protocol):
    @property
    def value(self) -> V: ...
    @property
    def unit(self) -> U: ...

equivalent to this

class Quantity(Protocol[V, U]):
    @property
    def value(self) -> V: ...
    @property
    def unit(self) -> U: ...

?
(I have not had the opportunity to use PEP 695 syntax yet)

[nstarman]

Yes, except for the former it's not necessary to define the typevars, as it should be for the latter.

[neutrinoceros]

Excellent, thanks !

[neutrinoceros]

Thanks ! I added links to relevant PEPs were due

[nstarman]

How do you think we should vote? Should we schedule a Zoom call then send out the decision to relevant stakeholders for comment (astropy, pint, unyt, etc), then meet again to finalize?

[hgrecco]

Hi there!

[andrewgsavage]

@jules-ch @dalito had also shown interest

[neutrinoceros]

Let me also ping @jzuhone for unyt and @MridulS for scipp

[dalito]

Thanks for the ping.

[jzuhone]

Let me know when the zoom call is

[SimonHeybrock]

Thanks! I have left a couple of comments.

Maybe a personal preference, but could we (instead of a Google doc) have this as a PR with a markdown document and/or an actual Python module with a draft of the protocol?

[keewis]

I thought you mentioned to me that pint was considering changing this behaviour

indeed, I still think that by default *_like should copy everything, including the units (fwiw, I'm not as involved with pint at the moment).

However, how about adding a units kwarg to those functions (except maybe full_like, where that may not make as much sense)? I didn't do that in the PR you're quoting because NEP18 didn't support it (I think?), but it seems the Array API does allow adding additional kwargs?

[lucascolley]

If zeros_like copies the units, we can always start with zeros_like(x).to_unit(Unit.dimensionless), and introduce zeros_like(x, unit=Unit.dimensionless) at a later point if we want to. The main thing is to decide whether it should copy the units, or be dimensionless by default.

Do you agree with me though, @SimonHeybrock, that this question is beyond the scope of the current discussion? I don't think a decision either way will affect the Quantity API, right?

[keewis]

we can always start with zeros_like(x).to_unit(Unit.dimensionless), and introduce zeros_like(x, unit=Unit.dimensionless) at a later point if we want to

that will only work if to_unit is something to the effect of with_unit (i.e. override the units), and not convert_to

[lucascolley]

that will only work if to_unit is something to the effect of with_unit (i.e. override the units), and not convert_to

very good point—in light of that, I think Quantity(x.value, Unit.pint) would eliminate the need for x.with_unit(Unit.pint) (it seems to me like overriding the unit (avoiding conversion) at the Quantity API level should be a relatively rare thing, right? let me know). For the zeros_like example, I think zeros_like(x, unit=Unit.dimensionless) is the way to go.

[mhvk]

Super that you posted a python one instead of the google doc - maybe an idea to explicitly note in the google docs that discusssion should be at quantity-dev/quantity-api#1 instead.

[lucascolley]

.to_unit() vs to vs <<

I was under the impression that << was about defining __rlshift__ in the Unit API (to add units to a value, returning a Quantity), rather than anything directly in the Quantity API - is that right @mhvk ? Or were you also thinking about some_quantity << some_unit converting between units?

[mhvk]

In astropy.units, << currently serves both purposes, to add a unit to an array and to convert a quantity to a new unit. This may actually have been a mistake, as it breaks the general rule than a number/array is equivalent to a dimensionless quantity.

Part of the reason for suggesting things like dunder methods is that the different units/value packages clearly have made different choices for the attributes/methods for getting the value/magnitude, unit, and doing conversions. So, it seemed to make sense to define new ones that we could all support. And I still like using operators as they seem simpler... I'd like a << unit for attach unit, q >> unit for convert a quantity to new one, and perhaps q // unit for a value in the given unit (which implies q % unit has to be 0). But it may be better to define special methods for those.

p.s. Super aside, I've been super busy with regular job stuff (graduate admission, sigh...) but hope to contribute a bit more in the coming weeks. Though it looks like I'll have some catching up to do!

[lucascolley]

__init__ signature

Could anyone help spell out the options here?

[mhvk]

Has it been considered whether Quantity (or asquantity) should attempt to construct a Unit from the unit argument? Passing unit strings (to construct an actual Unit from) is a common use case and gives a nicer UX.

I agree that should be possible. It is perhaps an argument for having a separate creation function. For such a function, I think it is reasonable to allow passing in strings, while for the class it will keep things much faster if value and unit are of known type (array-api compatible and unit, resp.). Like asarray, the asquantity function could, e.g., also wrap python numbers in something array-api compatible.

A perhaps bigger question is whether we want to use asarray directly (with standard array API, that would mean unit would have to be a keyword argument, though), so having a simple asquantity(value, unit) may make sense to define.

[lucascolley]

I think asquantity would be a great idea for a namespace such as those provided by quantity-array, and trivial to implement. I don't think we need to specify any requirements for the underlying Quantity libraries though - see also https://github.com/orgs/quantity-dev/discussions/6#discussioncomment-12043625.

[mhvk]

I think we're starting to converge on the requirements on the Quantity library being of the type of how they behave and what (few) attributes they have rather than how they are initialized.

[lucascolley]

Right, but as I said at https://github.com/orgs/quantity-dev/discussions/6#discussioncomment-12043625 it seems like we need at least some standard way of initialising a Quantity.

[mhvk]

Agreed, there needs to be a standard way to initialize, but I think it has become clear that it should be callable with a given name where the implementation is left up to the library. I like quantity (a la np.array) personally, but asquantity would be fine. I don't think we should give a class name to avoid requiring that the class has to be able to deal with parsing value or unit.

[lucascolley]

Python module with a draft of the protocol?

quantity-dev/quantity-api#1 (the same can follow for the unit / dimension APIs in due course)

[mhvk]

In practice, astropy has local imports for the parts in units that produce a Quantity, and just import Unit in the quantity module.

[lucascolley]

astropy has local imports for the parts in units that produce a Quantity

Sure, but I think we need module level imports when we are using Quantity in the type signature? Unless hiding things behind if typing.TYPE_CHECKING helps?

[andrewgsavage]

it might be too late now, but this sounds to me like we should be developing these APIs in a monorepo using a workspace.

I don't think it's too late! This seems good to me—how about quantity-dev/metrology-apis?

pixi supports this workflow

yep, happy to look at setting this up. I'm pretty swamped with uni work this week but should be able to get to it soon.

I'm a little lost. We seem to be headed towards a single API containing Quantity, Unit, Dimension. What's the purpose of a package for each of them? Could we not just put them into the quantity repo?

[lucascolley]

I also wonder whether a single module would be sufficient

[neutrinoceros]

Admittedly I haven't done a super good job of keeping up to date, but I thought we were actually going the other way with a handful of minimal but inter-locked APIs, and as many package. If there's a consensus that a single package makes more sense, then a workspace is indeed not necessary.

[andrewgsavage]

Something that I don't think is clear is whether we are going for an api that's aiming to be minimal or catch common usage. I had worded the design doc aiming for common use, since we've been discussing things like Quantity.to_unit and .dimensionality returning Dimension objects, which are more than the minimum needed.

[lucascolley]

QAPI should be designed such that np.ndarray already conforms to it, which doesn't make sense to me

For sure. This is another case where implementations should be allowed to treat NumPy arrays as dimensionless quantities if they want to (and infer the missing pieces), but we shouldn't specify this as required.

[mhvk]

Here, I was specifically commenting on the draft implementation of __add__, where other.to_units(...) is used. I still think it is a mistake to think like this, what I think is much better is to call out to the unit name space and have a function that returns converters for each argument, converting their values to the right unit (in this case, other to self.unit, but for xp.sin it would be self to radians. But I'll admit I'm strongly influenced by how we do it in astropy, and this works really well. (And for __add__, if other is an ndarray, it would be treated as dimensionless.)

Anyway, I found that in our Quantity implementation .to_units (our .to()) is not something that we use much - it is much more a convenience for users. Indeed, even elsewhere in astropy, to_value(unit) is used much more often. Bottom line: I don't think a method like to_units belons in the required API, but we should have a function that does conversion in the units API. Which reminds me that, really, we should be discussing the units API -- it is the true core!

[nstarman]

@mhvk, how about something like ustrip - https://unxt.readthedocs.io/en/latest/api/quantity.html#unxt.quantity.ustrip.
Then for implementing libraries their Quantity's add might be

def __add__(self, other):
    u = self.__metrology_namespace__()
    other_v = u.ustrip(self.units, other)  # will raise if conversion is not possible
    value = self.value + other_v
    return u.asquantity(value, self.units)  # or other implementations like dataclasses.replace(self, value=value)

This is a direct call out to the units API.
ustrip's argument order is entirely up for discussion. The unxt implementation is purposefully Julia-like.

[mhvk]

Yes, something like that, though I think one more generally wants a ustrip that is aware of what function (here "add"), we're trying to emulate (so that it can, e.g., convert to radian for "sin").

Anyway, my more general point is, like yours, that only the unit knows what conversion is needed, so it seems more logical to have the conversion happen via something on the unit namespace.

[nstarman]

Anyway, my more general point is, like yours, that only the unit knows what conversion is needed, so it seems more logical to have the conversion happen via something on the unit namespace.

Strong agree.
See https://github.com/quantity-dev/quantity-api/issues/4#issuecomment-2646010113 for why I think there should still be a user-convenience method for unit conversion on Q objects. I like Julia and all, but Python is OO and we should have methods on objects 🤣.