Unit#

class ansys.units.unit.Unit(units: str | None = None, config: Mapping[str, Any] | None = None, dimensions: Dimensions | None = None, system: UnitSystem | str | None = None, table: Mapping[Literal['Mass', 'Length', 'Time', 'Temperature', 'Current', 'SubstanceAmount', 'Light', 'Angle', 'SolidAngle', 'Acceleration', 'AngularAcceleration', 'AngularVelocity', 'Area', 'Compressibility', 'Concentration', 'DecayConstant', 'Density', 'DynamicViscosity', 'ElectricCharge', 'ElectricChargeDensity', 'ElectricCurrentDensity', 'ElectricCurrentSource', 'ElectricFluxDensity', 'Enthalpy', 'Force', 'ForceDensity', 'Frequency', 'HeatFlux', 'HeatGeneration', 'HeatTransferCoefficient', 'Impulse', 'MagneticFieldIntensity', 'MassFlowRate', 'MassFlux', 'MolarConcentration', 'MolarEnergy', 'MolarEnthalpy', 'MolarEntropy', 'MolarMass', 'MolarVolume', 'Moment', 'MomentOfInertiaOfArea', 'MomentOfInertiaOfMass', 'Momentum', 'Pressure', 'ShearStrain', 'ShearStrainRate', 'SpecificConcentration', 'SpecificEnergy', 'SpecificEnthalpy', 'SpecificEntropy', 'SpecificFlameSurfaceDensity', 'SpecificHeatCapacity', 'SpecificVolume', 'Stiffness', 'Strain', 'SurfaceChargeDensity', 'SurfaceForceDensity', 'SurfacePowerDensity', 'SurfaceTension', 'TemperatureGradient', 'ThermalCapacitance', 'ThermalConductance', 'ThermalConductivity', 'ThermalContactResistance', 'ThermalExpansionCoefficient', 'Torque', 'Velocity', 'Volume', 'VolumetricFlowRate'], float] | None = None, copy_from: Unit | None = None, preferred_units: PreferredUnits | Sequence[Literal['kg', 'g', 'lb', 'lbm', 'slug', 'm', 'cm', 'ft', 'inch', 'in', 's', 'A', 'mol', 'slugmol', 'cd', 'sr', 'radian', 'degree', 'rev', 'K', 'C', 'F', 'R', 'delta_K', 'delta_C', 'delta_F', 'delta_R', 'min', 'h', 'N', 'Pa', 'bar', 'W', 'J', 'V', 'farad', 'H', 'S', 'Wb', 'T', 'dyne', 'erg', 'pdl', 'psi', 'lbf', 'psf', 'ohm', 'Hz', 'l', 'gal', 'BTU', 'cal', 'coulomb', 'tonne'] | str | UnitLike] | Literal['kg', 'g', 'lb', 'lbm', 'slug', 'm', 'cm', 'ft', 'inch', 'in', 's', 'A', 'mol', 'slugmol', 'cd', 'sr', 'radian', 'degree', 'rev', 'K', 'C', 'F', 'R', 'delta_K', 'delta_C', 'delta_F', 'delta_R', 'min', 'h', 'N', 'Pa', 'bar', 'W', 'J', 'V', 'farad', 'H', 'S', 'Wb', 'T', 'dyne', 'erg', 'pdl', 'psi', 'lbf', 'psf', 'ohm', 'Hz', 'l', 'gal', 'BTU', 'cal', 'coulomb', 'tonne'] | str | UnitLike | None = None)#

Bases: object

A class containing the string name and dimensions of a unit.

Parameters:

units: str, optional: Name of the unit or string chain of combined units
config: dict, optional: dictionary of unit properties
dimensions: Dimensions, optional: An instance of the Dimensions class.
system: str, optional: Define the unit system for base units of dimension, default is SI.
table: dict, optional: A dictionary of api table keys from the cfg.yaml and exponent values.
copy_from: Unit, optional: A previous instance of Unit.

Attributes:

name: The unit string.
si_units: The unit string in SI units.
si_scaling_factor: The scaling factor used to convert to SI units.
si_offset: The offset used to convert to SI units.
dimensions: The units base dimensions.

See also

ansys.units.common: A collection of predefined units for use.

Examples

>>> from ansys.units import Unit, Quantity
>>> fps = Unit("ft s^-1")
>>> fps.name
'ft s^-1'
>>> fps.dimensions
{'LENGTH': 1.0, 'TIME': -1.0}
>>> speed = Quantity(value=5, units=fps)
>>> speed
Quantity(5.0, "ft s^-1")

compatible_units() → set[str]#

Get all units with the same dimensions.

Returns:

set: A set of unit objects.

convert(system: UnitSystem, preferred_units: PreferredUnits | Sequence[Literal['kg', 'g', 'lb', 'lbm', 'slug', 'm', 'cm', 'ft', 'inch', 'in', 's', 'A', 'mol', 'slugmol', 'cd', 'sr', 'radian', 'degree', 'rev', 'K', 'C', 'F', 'R', 'delta_K', 'delta_C', 'delta_F', 'delta_R', 'min', 'h', 'N', 'Pa', 'bar', 'W', 'J', 'V', 'farad', 'H', 'S', 'Wb', 'T', 'dyne', 'erg', 'pdl', 'psi', 'lbf', 'psf', 'ohm', 'Hz', 'l', 'gal', 'BTU', 'cal', 'coulomb', 'tonne'] | str | UnitLike] | Literal['kg', 'g', 'lb', 'lbm', 'slug', 'm', 'cm', 'ft', 'inch', 'in', 's', 'A', 'mol', 'slugmol', 'cd', 'sr', 'radian', 'degree', 'rev', 'K', 'C', 'F', 'R', 'delta_K', 'delta_C', 'delta_F', 'delta_R', 'min', 'h', 'N', 'Pa', 'bar', 'W', 'J', 'V', 'farad', 'H', 'S', 'Wb', 'T', 'dyne', 'erg', 'pdl', 'psi', 'lbf', 'psf', 'ohm', 'Hz', 'l', 'gal', 'BTU', 'cal', 'coulomb', 'tonne'] | str | UnitLike | None = None) → Unit#

Convert a unit into the unit system.

Parameters:

systemUnitSystem: Unit system to convert to.
preferred_unitsPreferredUnits, optional: Preferred display/conversion units for derived dimensions. A plain unit or sequence of units is wrapped in a PreferredUnits automatically.

Returns:

Unit: Unit object converted into the unit system.

Examples

>>> ur = UnitRegistry()
>>> speed_si = Unit(units= ur.m / ur.s)
>>> bt = UnitSystem(system="BT")
>>> speed_bt = speed_si.convert(bt)

property dimensions: Dimensions#: The units base dimensions.

classmethod from_dict(data: Mapping[str, Any], registry: UnitRegistry | None = None) → Unit#

Create a unit from a dictionary written by to_dict().

Parameters:

datadict: Serialized unit.
registryUnitRegistry, optional: Registry used to resolve the unit name. Defaults to the application registry (see set_application_registry()).

property has_offset: bool#

True if the unit is a non-multiplicative (offset-based) unit, such as C.

Offset units inside compound units (for example W m^-1 C^-1) are interpreted as temperature differences and convert without an offset, so such compound units are multiplicative.

property is_absolute_temperature: bool#: True if the unit is an absolute temperature, not a difference.

property min_absolute_value: float | None#

Lowest physically valid value (absolute zero) in this unit.

None if the unit is not an absolute temperature. The limit is derived from the unit’s SI offset, so it applies to any configured temperature unit without referring to unit names.

property name: str#: The unit string.

property si_offset: float#: The offset used to convert to SI units.

property si_scaling_factor: float#: The scaling factor used to convert to SI units.

property si_units: str#: The unit string in SI units.

to_dict() → dict[str, Any]#

Serialize the unit to a dictionary.

The dictionary contains the unit name under "units". Custom units that are only defined in a UnitRegistry also include a "unit_definition" so that they can be restored without that registry.

Examples

>>> Unit("kg m^-3").to_dict()
{'units': 'kg m^-3'}

to_temperature_difference() → Unit#

Get the temperature difference unit matching this absolute temperature unit.

Returns:

Unit: Temperature difference unit with the same scaling factor.

Raises:

ValueError: If the unit is not an absolute temperature or has no configured temperature difference counterpart.

exception ansys.units.unit.ProhibitedTemperatureOperation(message: str | None = None)#

Bases: TypeError

Raised when two absolute temperatures are added.

exception ansys.units.unit.ProhibitedOffsetUnitOperation(unit: Unit, op: str)#

Bases: TypeError

Raised when an offset-based unit is used in an invalid operation.

exception ansys.units.unit.PrefixedOffsetUnit(term: str, base: str)#

Bases: ValueError

Raised when a multiplier prefix is applied to an offset-based unit.

exception ansys.units.unit.IncorrectUnits(unit1: Unit, unit2: Unit)#

Bases: ValueError

Raised when the specified units are incorrect.

exception ansys.units.unit.InconsistentDimensions#

Bases: ValueError

Raised when units have inconsistent base dimensions.

exception ansys.units.unit.UnconfiguredUnit(unit: str)#

Bases: ValueError

Raised when the specified unit is unconfigured.

exception ansys.units.unit.UnknownTableItem(item: str)#

Bases: ValueError

Raised when a quantity table item is undefined.