Unit registry#

class ansys.units.unit_registry.UnitRegistry(config: str = 'cfg.yaml', other: Mapping[str, Mapping[str, Any]] = {}, custom_units: Sequence[Mapping[str, Any]] | None = None)#

Bases: object

A representation of valid Unit instances.

All base and derived units loaded from the configuration file, cfg.yaml, on package initialization are provided by default.

Parameters:

config: str, optional: Path of a YAML configuration file, which can be a custom file, and defaults to the provided file, cfg.yaml. Custom configuration files must match the format of the default configuration file.
other: dict, optional: Dictionary for additional units (uses config file format).
custom_unitslist of dict, optional: List of custom units to register during construction. Each dict must have keys "unit", "composition", and "factor" matching the register_unit() signature.

Examples

>>> from ansys.units import UnitRegistry, Unit
>>> ureg = UnitRegistry()
>>> assert ureg.kg == Unit(units="kg")
>>> fps = Unit("ft s^-1")
>>> ureg.foot_per_sec = fps

>>> ur = UnitRegistry(custom_units=[
...     {"unit": "micron", "composition": "m", "factor": 1e-6},
...     {"unit": "inch", "composition": "m", "factor": 0.0254},
... ])
>>> q = ur.Quantity(10, "micron")

Quantity(value: int | float | Sequence[float], units: str | Unit) → Quantity#

Create a Quantity using this registry’s units.

This method allows creating quantities with instance-registered units using string names.

Parameters:

valueint, float, or sequence: The numeric value.
unitsstr or Unit: The unit name (looked up in this registry) or a Unit object.

Returns:

Quantity: The created quantity.

Examples

>>> ur = UnitRegistry()
>>> ur.register_unit(unit="micron", composition="m", factor=1e-6)
>>> q = ur.Quantity(1, "micron")
>>> print(q)
1.0 micron

get_unit(name: str) → Unit#

Look up a unit by name from this registry.

Checks instance-registered units first, then falls back to built-in units and compound unit strings. This allows string-based lookup of custom registered units as well as standard unit expressions.

Parameters:

namestr: The unit name or compound unit string to look up (e.g., “micron”, “m”, “kg mol^-1”).

Returns:

Unit: The unit object.

Raises:

AttributeError: If the unit is not found in this registry or cannot be parsed.

register_alias(alias: str, canonical: str) → None#

The alias is added to the global alias table so that it can be used anywhere a unit string is accepted (Unit(), Quantity(), etc.).

Parameters:

aliasstr: The alias name (e.g., "deg").
canonicalstr: The canonical unit name the alias resolves to (e.g., "degree"). Must be a configured base or derived unit, or an existing alias.

Raises:

AliasAlreadyRegistered: If alias is already registered as a unit or alias.
ValueError: If canonical is not a known unit or alias.

register_unit(*, unit: str, composition: str, factor: float) → Unit#

This is instance-scoped: it affects only this registry and does not mutate global state or other registries. The registered unit can be accessed as an attribute (e.g., ur.micron) or via get_unit() for string-based lookup.

Parameters:

unit: str: The symbol/name of the new unit (e.g., “micron”).
composition: str: A valid unit composition using existing configured units (e.g., “m”).
factor: float: Scale factor that relates the composition to this unit.

Returns:

Unit: The registered unit attached on this instance.

Raises:

UnitNameAlreadyRegistered: If a unit with the same name already exists on this instance or as a built-in. This is a name-only check and does not detect equivalent definitions with different names.
ValueError: If unit is empty or factor is not finite.

Notes

The name collision check is superficial (name-only). Two units with different names but equivalent definitions (same composition and factor) can both be registered without error.

Examples

>>> ur = UnitRegistry()
>>> ur.register_unit(unit="micron", composition="m", factor=1e-6)
>>> q = ur.Quantity(1, "micron")  # Use registry's Quantity method

exception ansys.units.unit_registry.UnitNameAlreadyRegistered(name: str)#

Bases: ValueError

Raised when a unit name conflicts with an existing name.

This is a name-only check. Units with different names but equivalent definitions (same composition and factor) are not detected.

exception ansys.units.unit_registry.AliasAlreadyRegistered(name: str)#

Bases: ValueError

Raised when an alias conflicts with an existing unit or alias.