Unit conversion functions/methods and their names

[andrewgsavage]

There's discussion starting #9 (comment) about unit conversion and the methods.

in short:
What should the name of a unit conversion function that returns a quantity be?
Potential names:

• asquantity(quantity, new_unit) could be used but would combine initialising and conversion in the same function.
• asunit could be expected to return a unit.
• convert has debateable concerns over name collision.
• uconvert isn't a nice name
• convert_quantity is my suggestion, including the return type in the name.

Should a unit conversion function that returns the value exist, and what should it be named?

• The aforementioned function could be used, and then use Quantity.value, so this doesn't need to exist in the initial release.
  Potential names:
• uconvert_value
• convert_value is my suggestion

Should a general function exist for converting between units? ie convert(unit1, unit2, value)

[nstarman]

My current thoughts:

• asquantity: IMO its fine for the function to be flexible and call the official unit conversion function, like numpy.asarray can internally call numpy.astype for dtype conversion.
• asunit 👎
• convert 👎 Explicit is better than implicit. We're doing unit conversion, this name is for any conversion.
• uconvert 👍. Explicit is better than implicit. Readability counts.
• convert_quantity 🤷 it's ambiguous IMO. What on quantities are we converting — the class type, the unit, the dtype? This name works equally well for inter-library quantity type conversion, unit conversion, and dtype conversion. Yes the context of other functions is important, but also each function name should stand on its own.
• convert_unit_on_quantity: 👎 0 ambiguity, but not concise. Straw man counterexample to all the concise names above 😆

Should a unit conversion function that returns the value exist, and what should it be named?

Yes.
The same thoughts about name ambiguity apply.

[andrewgsavage]

• uconvert 👍. Explicit is better than implicit. Readability counts.

so make it units_convert!

[nstarman]

Then does it convert unit (e.g. km to kpc) or units on quantity?
Funnily enough this is similar to uconvert, however the fact that it's "more" explicit also makes it more ambiguous.

[andrewgsavage]

Should a unit conversion function that returns the value exist, and what should it be named?

It could be named asvalue and follow the existing asmyclass pattern which returns myclass

[nstarman]

Sorry. At the Astropy conference this week. Limited time to contribute to discussion. I'd like to put in some thoughts next week, if this can Issue can remain open till then :)

[nstarman]

Do we have consensus on asquantity? We can chip away at this monolith.

[lucascolley]

Is the consensus about the specified way to perform conversion being https://github.com/quantity-dev/metrology-apis/blob/main/src/metrology_apis/__init__.py#L33-L34 ?

[andrewgsavage]

Do we have consensus on asquantity? We can chip away at this monolith.

@lucascolley and @mhvk preferred separating the initialising and conversion functionality in #9 (comment)

[lucascolley]

I'm not entirely sure if I still prefer that

[lucascolley]

thought about this a bit more - I think I am happy with conversion going via asquantity. Of course libraries can implement other functions/methods, but I think asquantity(q, u) is the one that makes the most sense to require. q == asquantity(q) should be true, likewise for q == asquantity(q, q.unit). I think it would be strange to throw an error for asquantity(q, v) instead of attempting to perform conversion.

What do you think @mhvk ?

[mhvk]

I'm OK with doing it. My only hesitation remains that asquantity(v, unit) is different from asquantity(dimensionless_q, unit), while I like attempting to treat values as the same as dimensionless quantities. But, really, here we are asking to turn something to a quantity, where the behaviour is pretty obvious -- and astropy's Quantity initializer has had the same behaviour since its inception! So, fine to go OK with it. Just need to be sure for the unit API has something of the form convert(value, from_unit, to_unit).