Unit systems#

class ansys.units.systems.UnitSystem(base_units: Mapping[BaseDimensions, Literal['kg', 'g', 'lb', 'lbm', 'slug', 'm', 'cm', 'ft', 'inch', 'in', 's', 'A', 'mol', 'slugmol', 'cd', 'sr', 'radian', 'degree', 'K', 'C', 'F', 'R', 'delta_K', 'delta_C', 'delta_F', 'delta_R', 'N', 'Pa', 'W', 'J', 'V', 'farad', 'H', 'S', 'Wb', 'T', 'dyne', 'erg', 'h', 'pdl', 'psi', 'lbf', 'psf', 'ohm', 'Hz', 'l', 'gal', 'BTU', 'cal', 'coulomb', 'tonne'] | str] | None = None, preferred_units: Sequence[Literal['kg', 'g', 'lb', 'lbm', 'slug', 'm', 'cm', 'ft', 'inch', 'in', 's', 'A', 'mol', 'slugmol', 'cd', 'sr', 'radian', 'degree', 'K', 'C', 'F', 'R', 'delta_K', 'delta_C', 'delta_F', 'delta_R', 'N', 'Pa', 'W', 'J', 'V', 'farad', 'H', 'S', 'Wb', 'T', 'dyne', 'erg', 'h', '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', 'K', 'C', 'F', 'R', 'delta_K', 'delta_C', 'delta_F', 'delta_R', 'N', 'Pa', 'W', 'J', 'V', 'farad', 'H', 'S', 'Wb', 'T', 'dyne', 'erg', 'h', 'pdl', 'psi', 'lbf', 'psf', 'ohm', 'Hz', 'l', 'gal', 'BTU', 'cal', 'coulomb', 'tonne'] | str | UnitLike | None = None, system: Literal['SI', 'CGS', 'BT'] | str = 'SI', copy_from: UnitSystem | None = None)#

Bases: object

A class representing base units for a unit system.

Predefined unit systems work automatically and are configured when the package is initialized, whereas you can add user-defined systems at any time.

Parameters:

base_units: dict, optional: Units mapped to base dimensions types.
preferred_units: str, list, optional: Preferred units used when converted dimensions match. These units are display/conversion targets for derived quantities, not base-unit slots.
system: str, Unit, optional: Predefined unit system.
copy_from: UnitSystem, optional: Make a copy of a unit system.

Attributes:

MASS: Mass unit of the unit system.
LENGTH: Length unit of the unit system.
TIME: Time unit of the unit system.
TEMPERATURE: Temperature unit of the unit system.
TEMPERATURE_DIFFERENCE: Temperature unit of the unit system.
ANGLE: Angle unit of the unit system.
CHEMICAL_AMOUNT: Chemical Amount unit of the unit system.
LIGHT: Light unit of the unit system.
CURRENT: Current unit of the unit system.
SOLID_ANGLE: Solid Angle unit of the unit system.

property ANGLE: Literal['radian', 'degree'] | str#: Angle unit of the unit system.

property CHEMICAL_AMOUNT: Literal['mol', 'slugmol'] | str#: Chemical Amount unit of the unit system.

property CURRENT: Literal['A'] | str#: Current unit of the unit system.

property LENGTH: Literal['m', 'cm', 'ft', 'inch', 'in'] | str#: Length unit of the unit system.

property LIGHT: Literal['cd'] | str#: Light unit of the unit system.

property MASS: Literal['kg', 'g', 'lb', 'lbm', 'slug'] | str#: Mass unit of the unit system.

property SOLID_ANGLE: Literal['sr'] | str#: Solid Angle unit of the unit system.

property TEMPERATURE: Literal['K', 'C', 'F', 'R'] | str#: Temperature unit of the unit system.

property TEMPERATURE_DIFFERENCE: Literal['delta_K', 'delta_C', 'delta_F', 'delta_R'] | str#: Temperature unit of the unit system.

property TIME: Literal['s'] | str#: Time unit of the unit system.

add_preferred_units(units: Sequence[Literal['kg', 'g', 'lb', 'lbm', 'slug', 'm', 'cm', 'ft', 'inch', 'in', 's', 'A', 'mol', 'slugmol', 'cd', 'sr', 'radian', 'degree', 'K', 'C', 'F', 'R', 'delta_K', 'delta_C', 'delta_F', 'delta_R', 'N', 'Pa', 'W', 'J', 'V', 'farad', 'H', 'S', 'Wb', 'T', 'dyne', 'erg', 'h', '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', 'K', 'C', 'F', 'R', 'delta_K', 'delta_C', 'delta_F', 'delta_R', 'N', 'Pa', 'W', 'J', 'V', 'farad', 'H', 'S', 'Wb', 'T', 'dyne', 'erg', 'h', 'pdl', 'psi', 'lbf', 'psf', 'ohm', 'Hz', 'l', 'gal', 'BTU', 'cal', 'coulomb', 'tonne'] | str | UnitLike) → None#

Add preferred display units for derived dimensions.

When a unit is converted using this unit system, a matching preferred unit is returned instead of the expanded base-unit expression. For example, a millimeter-tonne-second system can prefer "MPa" for pressure/stress dimensions instead of "tonne mm^-1 s^-2".

Parameters:

units: list: Preferred units to use for matching dimensions.

preferred_unit_for(dimensions: Dimensions) → str | None#: Return the preferred unit name for dimensions, if one is configured.

classmethod register_system(name: str, base_units: Mapping[BaseDimensions, Literal['kg', 'g', 'lb', 'lbm', 'slug', 'm', 'cm', 'ft', 'inch', 'in', 's', 'A', 'mol', 'slugmol', 'cd', 'sr', 'radian', 'degree', 'K', 'C', 'F', 'R', 'delta_K', 'delta_C', 'delta_F', 'delta_R', 'N', 'Pa', 'W', 'J', 'V', 'farad', 'H', 'S', 'Wb', 'T', 'dyne', 'erg', 'h', 'pdl', 'psi', 'lbf', 'psf', 'ohm', 'Hz', 'l', 'gal', 'BTU', 'cal', 'coulomb', 'tonne'] | str], preferred_units: Sequence[Literal['kg', 'g', 'lb', 'lbm', 'slug', 'm', 'cm', 'ft', 'inch', 'in', 's', 'A', 'mol', 'slugmol', 'cd', 'sr', 'radian', 'degree', 'K', 'C', 'F', 'R', 'delta_K', 'delta_C', 'delta_F', 'delta_R', 'N', 'Pa', 'W', 'J', 'V', 'farad', 'H', 'S', 'Wb', 'T', 'dyne', 'erg', 'h', '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', 'K', 'C', 'F', 'R', 'delta_K', 'delta_C', 'delta_F', 'delta_R', 'N', 'Pa', 'W', 'J', 'V', 'farad', 'H', 'S', 'Wb', 'T', 'dyne', 'erg', 'h', 'pdl', 'psi', 'lbf', 'psf', 'ohm', 'Hz', 'l', 'gal', 'BTU', 'cal', 'coulomb', 'tonne'] | str | UnitLike | None = None) → None#

Once registered, the system can be created anywhere via UnitSystem(system=name), the same way built-in systems such as "SI", "CGS", and "BT" are used. Registration is global for the running process (module-scoped), matching the behavior of the predefined unit systems loaded from cfg.yaml.

Note

Only the resolved unit name is persisted, not the Unit object itself. Instance-scoped custom units created with register_unit() are not known globally by name, so while passing one here succeeds (it is valid at registration time), reconstructing the system later with UnitSystem(system=name) fails unless the unit is also resolvable without that specific registry (for example a built-in unit, or a prefixed/derived atomic unit).

Parameters:

name: str: Name of the new unit system, for example "MMGS".
base_units: dict: Units mapped to base dimensions types. Every member of BaseDimensions must be provided so the resulting system is fully defined.
preferred_units: str, list, optional: Preferred units used when converted dimensions match. These units are display/conversion targets for derived quantities, not base-unit slots.

Raises:

UnitSystemAlreadyRegistered: If name is already used by a built-in or previously registered unit system.
IncompleteUnitSystem: If base_units is missing one or more base dimensions.
NotBaseUnit: If a unit is not dimensionally atomic (for example a derived unit that spans more than one base dimension, such as "Pa").
IncorrectUnitType: If a unit does not match its intended base dimension.
UnconfiguredPreferredUnit: If a preferred unit cannot be resolved globally by name.
PreferredUnitAlreadyRegistered: If two preferred units have the same dimensions.

Examples

>>> from ansys.units import BaseDimensions, UnitSystem
>>> dims = BaseDimensions
>>> UnitSystem.register_system(
...     name="MMGS",
...     base_units={
...         dims.MASS: "g",
...         dims.LENGTH: "mm",
...         dims.TIME: "s",
...         dims.TEMPERATURE: "K",
...         dims.TEMPERATURE_DIFFERENCE: "delta_K",
...         dims.ANGLE: "radian",
...         dims.CHEMICAL_AMOUNT: "mol",
...         dims.LIGHT: "cd",
...         dims.CURRENT: "A",
...         dims.SOLID_ANGLE: "sr",
...     },
... )
>>> mmgs = UnitSystem(system="MMGS")
>>> mmgs.LENGTH
'mm'

update(base_units: Mapping[BaseDimensions, Literal['kg', 'g', 'lb', 'lbm', 'slug', 'm', 'cm', 'ft', 'inch', 'in', 's', 'A', 'mol', 'slugmol', 'cd', 'sr', 'radian', 'degree', 'K', 'C', 'F', 'R', 'delta_K', 'delta_C', 'delta_F', 'delta_R', 'N', 'Pa', 'W', 'J', 'V', 'farad', 'H', 'S', 'Wb', 'T', 'dyne', 'erg', 'h', 'pdl', 'psi', 'lbf', 'psf', 'ohm', 'Hz', 'l', 'gal', 'BTU', 'cal', 'coulomb', 'tonne'] | str])#

Change the units of the unit system.

Parameters:

base_units: dict: Units mapped to base dimensions types.

exception ansys.units.systems.IncorrectUnitType(unit, unit_type)#

Bases: ValueError

Raised when a unit is provided that does not have a valid type of base unit.

exception ansys.units.systems.InvalidUnitSystem(sys)#

Bases: ValueError

Raised when a unit system is initialized with an unsupported unit system.

exception ansys.units.systems.NotBaseUnit(unit)#

Bases: ValueError

Raised when a unit system unit is not a configured base unit.