Support standard behaviour, operations, and functions as for numerical types

[matterhorn103]

It is important that quantities support standard operations and functions for manipulation as far as possible.

Whether the behaviour should conform to standards/precedent in Python is another question.

The Python docs for numeric types list various operations that are supported by all numeric types (except complex, crucially), but not yet by Quantity:

• [ ] // operator (__floordiv__())
• [ ] % operator (__mod__(), remainder of Q1 / Q2)
• [ ] -x, i.e. __neg__(), is supported by Quantity but review for subclasses: Temperature gives e.g. -50 °C for Temperature(50, °C).__neg__(), LogarithmicQuantity doesn't support it
• [ ] abs(Q) (__abs__()) – note that abs(complex("3+4j")) returns 5.0 i.e. the magnitude
• [ ] int(Q) is supported but needs review: it defers to Decimal.__int__(), meaning the rounding is done with a different rounding mode to our default
• [ ] float(Q) and int(Q) need review: they only work on dimensionless quantities. Users may be surprised to not be able to just get Q.number via float(). In contrast, complex doesn't support them even if the imaginary part is 0, despite the fact that complex(1+0j) == 1
• [ ] Q.__complex__() probably doesn't make sense to implement, unless it just does complex(float(Q)).
• [ ] Q.conjugate() is necessary if complex numbers are implemented
• [ ] Q.__divmod__() to give (Q1 // Q2, Q1 % Q2)

Real types (int and float) support a few more:

• [ ] Q.round(self[, ndigits]) – supported but review compliance with standards
• [ ] Q.trunc(self)
• [ ] Q.floor(self)
• [ ] Q.ceil(self)

This page in the docs says the following methods "can be" defined (but don't have to be) in order to emulate numeric objects (already implemented or reviewed ones are left out):

• [ ] Q.lshift(self, other)
• [ ] Q.rshift(self, other)
• [ ] Q.and(self, other)
• [ ] Q.xor(self, other)
• [ ] Q.or(self, other)
• [ ] in-place operations – would have to return a new object, naturally, since we are making things immutable
• [ ] Q.neg(self)
• [ ] Q.pos(self)
• [ ] Q.abs(self)
• [ ] Q.invert(self)
• [ ] Q.index(self)

The math module also has various functions that might be sensible to support. We should check though, and if Decimal doesn't, maybe Quantity shouldn't. I also don't know how one goes about supporting them since they act on a quantity and are not methods of Quantity itself:

• [ ] math.fabs(Q) – not sure what this is for
• [ ] math.fmod
• [ ] math.frexp
• [ ] math.fsum
• [ ] math.isclose
• [ ] math.isfinite
• [ ] math.isinf
• [ ] math.isnan
• [ ] math.isqrt
• [ ] math.modf
• [ ] math.prod
• [ ] math.remainder
• [ ] math.sumprod
• [ ] math.ulp
• [ ] math.cbrt
• [ ] math.exp
• [ ] math.exp2
• [ ] math.expm1
• [ ] math.log
• [ ] math.log1p
• [ ] math.log2
• [ ] math.log10
• [ ] math.pow
• [ ] math.sqrt
• [ ] math.acos
• [ ] math.asin
• [ ] math.atan
• [ ] math.atan2
• [ ] math.cos
• [ ] math.dist
• [ ] math.hypot
• [ ] math.sin
• [ ] math.tan
• [ ] math.acosh
• [ ] math.asinh
• [ ] math.atanh
• [ ] math.cosh
• [ ] math.sinh
• [ ] math.tanh
• [ ] math.erf
• [ ] math.erfc
• [ ] math.gamma
• [ ] math.lgamma

Consider implementing the following for special values:

• [ ] Quantity.inf()
• [ ] Quantity.nan()

The methods of Decimal are naturally all candidates. Many are not meaningful for a quantity, but should be assessed for inclusion:

• [ ] adjusted()
• [ ] as_integer_ratio() – or an analogous one that returns either a ratio of quantities with integer numbers or one quantity with a fractional number?
• [ ] compare(), though not sure what this adds
• [ ] compare_signal()
• [ ] compare_total()
• [ ] compare_total_mag()
• [ ] conjugate() – returns self for Decimal
• [ ] copy_abs()
• [ ] copy_negate()
• [ ] copy_sign()
• [x] exp()
• [ ] fma()
• [ ] is_infinite
• [ ] is_nan
• [ ] is_normal
• [ ] is_qnan
• [ ] is_signed
• [ ] is_snan
• [ ] is_subnormal
• [ ] is_zero
• [x] ln
• [x] log10
• [ ] logb
• [ ] logical_xxx
• [ ] max
• [ ] max_mag
• [ ] min
• [ ] min_mag
• [ ] next_minus
• [ ] next_plus
• [ ] next_toward
• [ ] normalize - definitely implement this, just call self.number.normalize() and self.uncertainty.normalize()
• [ ] number_class
• [ ] quantize – definitely implement this. The question is whether to just do self.number.quantize(other.number) or to essentially do what Q.round_to_resolution_of() does
• [ ] radix
• [ ] remainder_near
• [ ] rotate
• [ ] same_quantum
• [ ] scaleb
• [ ] shift
• [x] sqrt
• [ ] to_eng_string
• [ ] to_integral
• [ ] to_integral_exact
• [ ] to_integral_value

float also has these additional methods:

• [ ] Q.is_integer()

IEEE 754 (floating point standard, also for decimal floating point) has both required operations:

• [ ] Conversions to and from integer
• [ ] Previous and next consecutive values
• [ ] Arithmetic operations (add, subtract, multiply, divide, square root, [fused multiply–add], remainder, minimum, maximum)
• [ ] Conversions (between formats, to and from strings, etc.)
• [ ] Scaling and (for decimal) quantizing
• [ ] Copying and manipulating the sign (abs, negate, etc.)
• [ ] Comparisons and total ordering
• [ ] Classification of numbers (subnormal, finite, etc.) and testing for NaNs
• [ ] Testing and setting status flags [what does this mean?]

and recommended operations, which often are just compound methods?:

• [ ] e^x, 2^x, 10^x
• [ ] (e^x)-1, 2^x - 1, 10^x - 1
• [ ] ln, log2, log10
• [ ] ln(1+x), log2(1+x), log10(1+x)
• [ ] sqrt(x^2 + y^2)
• [ ] 1/ sqrt(x)
• [ ] (1+x)^n for x >= -1 (compound)
• [ ] x^(1/n)
• [ ] x^n, x^y
• [ ] sinx, cosx, tanx
• [ ] arcsin/cos/tan, atan2(y,x)
• [ ] sinhx, coshx, tanhx
• [ ] arcsinhx etc.

[matterhorn103]

Sometimes it is not just a question of support but also of making an opinionated decision as to what the result of an operation/function should be.

For example, Quantity currently supports int(Q), but throws an error if the quantity is not dimensionless. Moreover, the decision was already made to just use the underlying Decimal.__int__(), such that a non-integer number gets rounded. This might be sensible, as the user expects this behaviour by analogy to float, Decimal, etc.. However, the rounding is then different to the usual rounding behaviour of Quantity.

Rounding is another good example. IEEE 754 requires "ties to even" as the default for binary and the recommended default for decimal, on the basis that it results in no bias. Implementation of "ties to away" is also required for decimal implementations. This is what quanstants uses by default, though, to align with non-technical users' expectations. Again, this opinionated decision should be reviewed.

quanstants deliberately makes key decisions to break from how Python normally does things (rounding, use of decimal, decimalization of floats as strings). So the question is often whether it should match behaviour of built-in types or to go its own way.