rename "equivalent" method as it is misleading

[Alan Iwi]

I see that the equivalent method on Units objects is essentially an extended wrapper to ut_are_convertible() . This is a test for whether pairs of units are convertible as currently implemented by UDUNITS, rather than a statement of whether the units are fundamentally equivalent. In particular, UDUNITS will, as a convenience, convert not only between pairs of equivalent units, but also between reciprocal units, although this does not extend to arbitrary power-law conversions that would be technically possible:

>>> from cf.units import Units as U
>>> U("m").equivalent(U("m-1"))
True
>>> U("m").equivalent(U("m3"))
False

Surely in both the above cases, the following is true:

• the two units have different dimensions

• but a mathematical operation (not involving any other units) could map one to the other.

So there is not a clear logical basis for a distinction between the two cases in terms of "equivalence".

I would argue that "m" and "m-1" are not in any sense equivalent units, and as such, the name of the method is misleading.

I therefore suggest introducing an is_convertible method, and deprecating equivalent.

[David Hassell]

Hmm. I hadn't appreciated this subtlety. You;re right - equivalent is not appropriate. I shall rename it as you suggest. For backwards compatibility, I'll leave the equivalent method there as a wrapper to the new is_convertible method and a deprecation warning will be printed.

There are ~40 uses of this method in the cf-python library, which will need to be changed, which will happen in due course.

Thanks,

David