REFACTOR: Update register unit functionality

[hpohekar]

This pull request introduces significant improvements to the UnitRegistry class, focusing on more flexible and robust custom unit registration, improved string-based lookup, and clearer error handling for unit name collisions. The documentation and tests are updated to reflect these changes, making it easier for users to register and access custom units both at construction and after instantiation.

Key changes:

Custom Unit Registration & Lookup

• Added a custom_units parameter to the UnitRegistry constructor, allowing users to register custom units at the time of registry creation using a list of dictionaries. This enables more convenient and declarative unit setup. [1] [2] [3] [4]
• Introduced the get_unit method and a Quantity method on UnitRegistry for string-based lookup and creation of quantities using custom units, improving usability and consistency.

Name Collision & Error Handling

• Replaced the UnitAlreadyRegistered exception with a more specific UnitNameAlreadyRegistered exception, used consistently throughout the codebase for name-only collision detection (i.e., duplicate unit names, including built-ins). The check is now explicitly name-based, allowing equivalent units with different names. [1] [2] [3] [4] [5] [6] [7] [8]

Documentation Updates

• Expanded and reorganized documentation to clearly explain how to register custom units at construction and after instantiation, how string-based lookup works, and how instance isolation and name collision detection operate. Examples and notes have been added for clarity. [1] [2]

---

These changes make it easier and safer to extend the unit system with custom definitions, while providing clear feedback and documentation for users.

[seanpearsonuk]

Approving subject to checks by @mkundu1. Thanks!

[mkundu1]

@hpohekar The following code gives some error:

from ansys.units import UnitRegistry, Quantity, get_si_value
ur = UnitRegistry()
ur.register_unit(unit="micron", composition="m", factor=1e-6)
q1 = Quantity(1, ur.get_unit("micron"))  # this works
print(get_si_value(q1))
q2 = Quantity(1, ur.get_unit("kg mol^-1"))  # this fails
print(get_si_value(q2))
q3 = Quantity(1, "kg mol^-1") # this works
print(get_si_value(q3))

I need a consistent way of accessing units when I'm using the custom registry.

[seanpearsonuk]

@hpohekar The following code gives some error:

from ansys.units import UnitRegistry, Quantity, get_si_value
ur = UnitRegistry()
ur.register_unit(unit="micron", composition="m", factor=1e-6)
q1 = Quantity(1, ur.get_unit("micron"))  # this works
print(get_si_value(q1))
q2 = Quantity(1, ur.get_unit("kg mol^-1"))  # this fails
print(get_si_value(q2))
q3 = Quantity(1, "kg mol^-1") # this works
print(get_si_value(q3))

I need a consistent way of accessing units from the custom registry.

There's no need to rush to a solution here. We could alternatively just add micron for now, and revisit improvements later.

[hpohekar]

@hpohekar The following code gives some error:

from ansys.units import UnitRegistry, Quantity, get_si_value
ur = UnitRegistry()
ur.register_unit(unit="micron", composition="m", factor=1e-6)
q1 = Quantity(1, ur.get_unit("micron"))  # this works
print(get_si_value(q1))
q2 = Quantity(1, ur.get_unit("kg mol^-1"))  # this fails
print(get_si_value(q2))
q3 = Quantity(1, "kg mol^-1") # this works
print(get_si_value(q3))

I need a consistent way of accessing units when I'm using the custom registry.

@mkundu1 I have refactored to fix this. Please confirm. Thank you.

[mkundu1]

@hpohekar The following code gives some error:

from ansys.units import UnitRegistry, Quantity, get_si_value
ur = UnitRegistry()
ur.register_unit(unit="micron", composition="m", factor=1e-6)
q1 = Quantity(1, ur.get_unit("micron"))  # this works
print(get_si_value(q1))
q2 = Quantity(1, ur.get_unit("kg mol^-1"))  # this fails
print(get_si_value(q2))
q3 = Quantity(1, "kg mol^-1") # this works
print(get_si_value(q3))

I need a consistent way of accessing units when I'm using the custom registry.

@mkundu1 I have refactored to fix this. Please confirm. Thank you.

@hpohekar This is working fine now, thanks