Registering Custom Units#

You can register new derived units at runtime using instance-scoped registration directly on a UnitRegistry instance.

Instance-Scoped#

  • The UnitRegistry.register_unit(name, composition, factor) method adds a new unit symbol to that registry instance.

  • Duplicate registrations on the same instance (including collisions with built-in units) raise UnitAlreadyRegistered.

Example#

from ansys.units import UnitRegistry

ur = UnitRegistry()

# Register a symbol 'Q' equivalent to Joule (N m)
ur.register_unit(name="Q", composition="N m", factor=1)
assert ur.Q == ur.J

# A new registry does not see instance registrations
ur2 = UnitRegistry()
try:
    _ = ur2.Q
    raise AssertionError("Expected AttributeError for ur2.Q")
except AttributeError:
    pass

Note

Dynamic registration is instance-scoped. Register units on the specific UnitRegistry you want to use; new registries do not automatically inherit instance-registered units.

Notes#

  • composition must be a valid unit string composed of configured base/derived units (for example, "N m").

  • factor is the scale factor relating the composition to the new unit symbol.