Preferred units

class ansys.units.preferred_units.PreferredUnits(units: 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

An immutable mapping from dimensions to a preferred unit name.

PreferredUnits is a conversion policy: it decides which named derived unit, such as "MPa", is emitted instead of an expanded base-unit expression, such as "tonne mm^-1 s^-2", when a quantity is converted through a UnitSystem. It is independent of any particular UnitSystem and is passed directly to convert().

Entries are matched only by dimensions. Quantities with the same dimensions, such as torque and energy (both M L^2 T^-2), or stress and energy density (both M L^-1 T^-2), share the same preferred-unit entry.

Parameters:

units: optional

Preferred unit entries: a single unit name, a Unit instance, any object with a name, or a sequence of these values.

Raises:

UnconfiguredPreferredUnit

If a unit cannot be resolved to a known, dimensioned unit.

PreferredUnitAlreadyRegistered

If two entries would register different units for the same dimensions.

Examples

>>> from ansys.units import PreferredUnits
>>> prefs = PreferredUnits(["MPa", "N"])

unit_for(dimensions: Dimensions) → str | None

Return the preferred unit name for dimensions, if one is configured.

Parameters:

dimensions: Dimensions

Dimensions of the quantity being converted.

Returns:

str, optional

The preferred unit name, or None if no entry matches.

with_units(units: 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) → PreferredUnits

Return a new PreferredUnits combining these entries with additional ones.

Parameters:

units:

Additional preferred unit entries, validated atomically together with the existing entries.

Returns:

PreferredUnits

A new, independent PreferredUnits instance.

exception ansys.units.preferred_units.UnconfiguredPreferredUnit(unit: 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)

Bases: ValueError

Raised when a preferred unit cannot be resolved.

exception ansys.units.preferred_units.PreferredUnitAlreadyRegistered(existing_unit: str, conflicting_unit: str)

Bases: ValueError

Raised when two preferred units conflict for the same dimensions.