Quantity#

Bases: object

A class representing a physical quantity’s value and associated units.

A Quantity object can be instantiated from a NumPy array or list only if the NumPy package is installed.

The value argument is not required when using copy_from. A value can be given to override the value from the copy.

Implicit conversion from Quantity to float is only allowed if the operand is of quantity type angle or dimensionless.

Parameters:

valueint, float, list, np.array: Real value of the quantity.
unitsstr, Unit, optional: Initializes the quantity’s units using a string or Unit instance.
quantity_tabledict[str, int], optional: Initializes the quantity’s units using the quantity table.
dimensionsDimensions, optional: Initializes the quantity’s units in SI using a Dimensions instance.
copy_fromQuantity, optional: An existing Quantity instance.

Attributes:

value: Value in contained units.
units: The quantity’s units.
dimensions: The quantity’s dimensions.
is_dimensionless: True if the quantity is dimensionless.

compatible_units() → set[str]#

Get all units with the same dimensions.

Returns:

set: A set of unit objects.

convert(system: UnitSystem) → Quantity#

Convert a quantity into the unit system.

Parameters:

systemUnitSystem: Unit system to convert to.

Returns:

Quantity: Quantity object converted into the unit system.

Examples

>>> ur = UnitRegistry()
>>> speed_si = Quantity(value=5, units= ur.m / ur.s)
>>> bt = UnitSystem(system="BT")
>>> speed_bt = speed_si.convert(bt)

property dimensions#: The quantity’s dimensions.

property is_dimensionless#: True if the quantity is dimensionless.

classmethod preferred_units(units: list[Unit | str], remove: bool = False) → None#

Add or remove preferred units.

Quantities are automatically converted to preferred units when the quantity is initialized. Conversion is always carried out if the base units are consistent with the preferred units.

Each preferred unit must have unique dimensions. To override units with the same dimensions, the original must first be removed.

Parameters:

unitslist: A list of units to be added or removed.
removebool: Specify if the units should be removed.

to(to_units: Unit | str) → Quantity#

Perform quantity conversions.

Parameters:

to_unitsUnit or str: Desired unit to convert to.

Returns:

Quantity: Quantity instance in the desired units.

Examples

>>> speed_si = Quantity(value=5, units="m s^-1")
>>> speed_bt = speed_si.to("ft s^-1")

property units: Unit#: The quantity’s units.

validate_matching_dimensions(other)#: Validates dimensions of quantities.

property value#: Value in contained units.

ansys.units.quantity.get_si_value(quantity: Quantity) → float#: Returns a quantity’s value in SI units.

exception ansys.units.quantity.ExcessiveParameters#

Bases: ValueError

Raised when excessive parameters are provided.

exception ansys.units.quantity.IncompatibleDimensions(from_unit, to_unit)#

Bases: ValueError

Raised when dimensions are incompatible.

exception ansys.units.quantity.IncompatibleQuantities(q1, q2)#

Bases: ValueError

Raised when quantities are incompatible.

exception ansys.units.quantity.IncompatibleValue(value)#

Bases: ValueError

Raised when an incompatible value is provided.

exception ansys.units.quantity.InsufficientArguments#

Bases: ValueError

Raised when insufficient arguments are provided.

exception ansys.units.quantity.InvalidFloatUsage#

Bases: FloatingPointError

Raised when float is unsupported for given type of quantity.

exception ansys.units.quantity.NumPyRequired#

Bases: ModuleNotFoundError

Raised when NumPy is unavailable.

exception ansys.units.quantity.RequiresUniqueDimensions(unit, other_unit)#

Bases: ValueError

Raised when two units with the same dimensions are added to the chosen units.