Arithmetic operations for Parameters and DescriptorNumbers

[damskii9992]

General

Adding capability to do arithmetic operations on Parameters and DescriptorNumbers allow users to use fitted parameters to do quick and easy calculations with uncertainties and units to calculate items of interest, as well as quickly and easily create new parameters/descriptors from previous ones with correctly propagated limits.

Implementation

Currently, the following arithmetic operations are implemented for Parameter and DescriptorNumber:

• Addition
• Subtraction
• Multiplication
• Division
• Exponentiation
• Negation
• Absolute value

The output is a Parameter with automatically calculated min/max if any of the elements of the arithmetic operation is a Parameter, except for in specific cases explained below, otherwise the output is a DescriptorNumber. In either case, the unit and variance are also automatically propagated.

The operations work between any of Parameter, DescriptorNumber, floats or integers, except for exponentiation which does not take parameters as exponents.

Details for specific operations

Addition

The min/max limits of the resulting Parameter is the sum of min/max of the two Parameters.

When adding DescriptorNumber or a float/integer to a Parameter, the min/max are increased by the value of the DescriptorNumber or the float/integer instead.

Floats/integers can only be added to a dimensionless Parameter/DescriptorNumber, and these can only be added together if their units have the same physical dimension.

In case the units of the operands are different yet have the same physical dimension, the 2nd operand is converted to the unit of the 1st operand, in line with other libraries such as Pint.

Subtraction

Subtraction works similarly to addition, with the exception that the limits of the resulting Parameter from subtraction between two Parameters are handled differently.
The resulting min is now the min of the first operand, subtracted by the max of the second operand, and vice versa for the resulting max.

Subtraction of -np.inf with np.inf here yields -np.inf rather than NaN because these are numerical limits.

Multiplication

For multiplication of Parameters the resulting min/max are the lowest/highest of the 4 combinations that the min/max of the operands can be multiplied together.

Here, multiplication of ±np.inf with 0 yields 0, because these are numerical limits.

Multiplication of Parameters with other Parameters or DescriptorNumbers also multiplies their units together and simplify the resulting unit.

Special case
In the instance a Parameter is multiplied by a 0 or a DescriptorNumber with a value of 0, the returned result is a DescriptorNumber with a value of 0, rather than a Parameter, because the result is 0 no matter which value the Parameter takes within its min/max interval.

This is not the case when multiplied by another Parameter with a value of 0, because that Parameter can itself take values other than 0.

Division

For the division of two Parameters, the resulting min/max depends mostly on the denominator. If the denominator Parameters min/max crosses 0, the denominator can be arbitrarily close to 0 from either side, and the resulting Parameter thus has limits of ±np.inf.

If the denominator has 0 as either its min or max, it can be arbitrarily close to 0 from only one side, and thus the limits of the resulting Parameter can either both be ±np.inf, (if the numerator Parameter can be both positive and negative), or one side can be ±np.inf and the other side finite.

If the denominator has finite limits not including 0, the resulting limits are determined like in the multiplication operation, by the min and max of the 4 possible combinations of divisions between min/maxes of the Parameters

Division by a float/integer or a DescriptorNumber/Parameter with a value of 0 raises a ZeroDivisionError, instead of yielding np.inf, in order to avoid NaNs in a fitting procedure.

Special case
If a float/integer or a DescriptorNumber with a value of 0 is divided by a Parameter, the result is a DescriptorNumber with a value of 0, like in the multiplication operation, since the result does not depend on which value the Parameter takes within its limits.

Exponentiation

Parameters can only be raised to powers of floats/integers or DescriptorNumbers without a unit or a variance, since exponents have to be unit-less and it is not well-defined how to propagate a variance in the exponent.

If the Parameter/DescriptorNumber has a unit, it can only be raised to integer powers, as non-integer power units are not well-defined.
Fractional powers of negative-valued Parameters/DescriptorNumbers raise a ValueError, since complex numbers are not supported and the result is otherwise a NaN value, which is to be avoided.

For the same reason, if the min of a Parameter raised to a factional power is negative, the resulting min is 0, as 0 is the smallest value for which the operation was allowed.

If a Parameter is raised to the power of 0, the returned result is a DescriptorNumber, since the result does not depend on which value the Parameter takes within its limits.

If the exponent is a multiple of 2 and the Parameters limits crosses 0, the resulting min value is set to 0 and the max value is the largest of the absolute value of min and max, since exponents of multiples of 2 are always positive.

Negation

When a Parameter is negated, the resulting min becomes minus the max and vice versa for the max

Absolute Value

If the limits of the Parameter crosses 0, the resulting min becomes 0 and the max is the larger of the absolute values of the min and max.

link to the ADR suggestion
#27