pyxx.units.ConstantUnitMathConventions

class pyxx.units.ConstantUnitMathConventions(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Options for defining what happens when a Unit object is multiplied by a constant

When defining units, there are often cases where one unit is simply a multiple of another; for instance, a meter is 100 times the size of a centimeter, and an inch is 2.54 times the size of a centimeter. Rather than defining entirely new units, it would be helpful if there was a quick way to generate them from existing units.

These options provide precisely this functionality. However, there is a significant complication: what convention should we take? Should multiplying a unit of meters by 1000 result in a unit 1000 times larger (a kilometer), or should it return a unit 1000 times smaller (a millimeter, since \(1\ m * \frac{1000\ mm}{1\ m} = 1000\ mm\))?

Due to this ambiguity, by default PyXX prohibits multiplication of Unit objects and constants. However, by setting the Unit.CONSTANT_MATH_CONVENTION attribute to one of the values described on this page, it is possible to override this default and specify the desired math convention for multiplying Unit objects by constants.

Warning

This is an advanced option. If you are uncertain about how it functions, leave it set to the default value (DISABLE) – you won’t lose any functionality of the PyXX package; you’ll only lose a minor shortcut intended purely for convenience.

Notes

In general, it is best to set this option at the beginning of your code, as it can get confusing if you set it later in your code and as a result different parts of your code follow different conventions.

To select a math convention for multiplying Unit objects by constants, include code similar to:

>>> from pyxx.units import Unit, ConstantUnitMathConventions
>>> Unit.CONSTANT_MATH_CONVENTION = ConstantUnitMathConventions.DISABLE

Attributes

DISABLE	Multiplying a unit by a constant is forbidden, and any attempt to do so results in an error being thrown.
UNIT_BASED	To create a new unit, multiply or divide by a constant as if you were directly manipulating the units themselves.
QUANTITY_BASED	To create a new unit, multiply or divide by a constant as you would do if converting quantities in the respective units.

DISABLE = 1

Multiplying a unit by a constant is forbidden, and any attempt to do so results in an error being thrown.

UNIT_BASED = 2

To create a new unit, multiply or divide by a constant as if you were directly manipulating the units themselves.

For example, suppose that we have already defined a unit of milliseconds ms and we want to create a new unit seconds s. Since one second is 1000 times larger than a millisecond, the unit of s could be created by:

s = 1000 * ms

QUANTITY_BASED = 3

To create a new unit, multiply or divide by a constant as you would do if converting quantities in the respective units.

For example, suppose that we have already defined a unit of milliseconds ms and we want to create a new unit seconds s. Since \(x\) milliseconds is equal to \(0.001x\) seconds, the unit of s could be created by:

s = 0.001 * ms