Unit aliases#

PyAnsys Units supports unit aliases, allowing you to use shorthand or alternative names for units. For example, you can write deg instead of degree, meter instead of m, or newton instead of N.

Aliases resolve transparently to their canonical unit names during parsing, so they work everywhere a unit string is accepted: Unit(), Quantity(), compound unit strings, and conversions.

Built-in aliases#

A set of common aliases is shipped out of the box in the cfg.yaml configuration file. Some examples:

Alias	Canonical unit
`deg`	`degree`
`rad`	`radian`
`sec`	`s`
`meter` / `metre`	`m`
`kilogram`	`kg`
`foot` / `feet`	`ft`
`newton`	`N`
`pascal`	`Pa`
`watt`	`W`
`joule`	`J`
`volt`	`V`
`hertz`	`Hz`
`liter` / `litre`	`l`

Using aliases#

Aliases can be used anywhere you would normally write a unit name:

from ansys.units import Unit, Quantity

# Create a unit from an alias
angle = Unit("deg")  # resolves to "degree"
length = Unit("meter")  # resolves to "m"

# Create quantities with aliases
q = Quantity(90, "deg")  # 90.0 degree

# Aliases work inside compound unit strings
angular_vel = Unit("deg sec^-1")  # "degree s^-1"
accel = Unit("meter sec^-2")  # "m s^-2"

# Conversions work normally
q_rad = Quantity(180, "deg").to("radian")

Alias equality#

A unit created from an alias is identical to the canonical unit. They share the same dimensions, SI scaling factor, and SI offset:

from ansys.units import Unit

assert Unit("deg") == Unit("degree")
assert Unit("rad") == Unit("radian")
assert Unit("meter") == Unit("m")

Registering custom aliases#

You can register your own aliases at runtime using the UnitRegistry.register_alias() method:

from ansys.units import Unit, UnitRegistry

ureg = UnitRegistry()
ureg.register_alias("angular_deg", "degree")

u = Unit("angular_deg")  # resolves to "degree"

The method validates that:

The alias does not shadow an existing base unit, derived unit, or alias (raises AliasAlreadyRegistered).
The canonical target is a configured unit or an existing alias (raises ValueError).
Neither argument is empty (raises ValueError).

Aliases can also point to other aliases. The resolution follows the chain transitively until a canonical unit is reached:

ureg.register_alias("my_angle", "deg")  # "deg" -> "degree"
Unit("my_angle")  # resolves to "degree"

Note

Aliases registered programmatically via register_alias() are added to the global alias table. They take effect immediately for all subsequent Unit() and Quantity() calls in the same process. They are not persisted across sessions.