PyAnsys Units basics

PyAnsys Units provides a Pythonic interface for units, unit systems, and unit conversions. Its features enable seamless setup and usage of physical quantities.

This example shows you how to perform these tasks:

• Create quantities (unit strings, dimensions, and quantity tables).

• Access different quantity properties.

• Perform arithmetic operations.

• Perform unit conversions.

• Create unit systems (custom and predefined).

• Apply unit systems to quantities.

# sphinx_gallery_thumbnail_path = '_static/basic_usage.png'

Perform required imports

Import the ansys.units package.

from ansys.units import (
    BaseDimensions,
    Dimensions,
    PreferredUnits,
    Quantity,
    UnitSystem,
)
from ansys.units.common import *  # noqa: F403
from ansys.units.quantity import get_si_value

Create quantities

You can instantiate quantities using one of four methods: - Unit operations from common : float, Unit - Unit strings : str, Unit - Dimensions : Dimensions - Quantity table : dict

# Unit operations

volume = 1 * m**3

acceleration = 3 * m * s**-2

torque = 5 * N * m

pressure = 250 * Pa  # there are even some derived units

combined = (2 * N) / (m**2) + (3 * Pa)

# Unit strings

volume = Quantity(value=1, units="m^3")

acceleration = Quantity(value=3, units="m s^-2")

torque = Quantity(value=5, units="N m")

# Dimensions

dims = BaseDimensions

vol_dims = Dimensions({dims.LENGTH: 3})
volume = Quantity(value=1, dimensions=vol_dims)

acc_dims = Dimensions({dims.LENGTH: 1, dims.TIME: -2})
acceleration = Quantity(value=3, dimensions=acc_dims)

tor_dims = Dimensions({dims.MASS: 1, dims.LENGTH: 2, dims.TIME: -2})
torque = Quantity(value=5, dimensions=tor_dims)

# Quantity table

volume = Quantity(value=1, quantity_table={"Volume": 1})

acceleration = Quantity(value=3, quantity_table={"Acceleration": 1})

torque = Quantity(value=5, quantity_table={"Torque": 1})

Specify quantity properties

For a quantity, you specify six properties:

# 1. value : float | int
# 2. units : str
# 3. si_value : float | int
# 4. si_units : str
# 5. dimensions : dict
# 6. is_dimensionless : bool


dynamic_viscosity = Quantity(value=50, quantity_table={"DynamicViscosity": 1})

dynamic_viscosity.value  # >>> 50.0
dynamic_viscosity.units.name  # >>> "Pa s"
dynamic_viscosity.units.si_units  # >>> "kg m^-1 s^-1"
dynamic_viscosity.dimensions  # >>> {'MASS': 1.0, 'LENGTH': -1.0, 'TIME': -1.0}
dynamic_viscosity.is_dimensionless  # >>> False
get_si_value(dynamic_viscosity)  # >>> 50.0

50.0

Perform arithmetic operations

You can perform all mathematical operations on a quantity.

import math

q1 = 10 * m * s**-1
q2 = 5.0 * m * s**-1

# Subtraction

q3 = q2 - q1
q3.value  # >>> 5.0
q3.units.name  # >>> "m s^-1"

# Addition

q4 = q2 + q1
q4.value  # >>> 15.0
q4.units.name  # >>> "m s^-1"

# Division

q5 = q2 / q1
q5.value  # >>> 2.0
q5.units.name  # >>> ''

# Multiplication

q6 = q2 * q1
q6.value  # >>> 50.0
q6.units.name  # >>> "m^2 s^-2"

# Negation

q7 = -q2
q7.value  # >>> -5.0
q7.units.name  # >>> "m s^-1"

# Exponents

q8 = q1**2
q8.value  # >>> 100.0
q8.units.name  # >>> "m^2 s^-2"

# Roots

q9 = Quantity(5.0)

math.sqrt(q9)  # >>> 2.2360679775

# Trigonometry

math.sin(90 * degree)  # >>> 1.0
math.cos(math.pi * radian)  # >>> -1.0

-1.0

Perform conversions

To check the compatible units use the ‘compatible_units’ method.

five_slug = 5 * slug
five_slug.compatible_units()  # >>> {'lbm', 'g', 'lb', 'kg'}

# You can perform conversions on quantities with compatible units.

five_slug_in_kg = five_slug.to(kg)

five_slug_in_kg.value  # >>> 72.96951468603184
five_slug_in_kg.units.name  # >>> "kg"

twenty_five_ms = 25 * m
cm = twenty_five_ms.to(cm)

cm.value  # >>> 2500
cm.units.name  # >>> "cm"

dvis = 1.0 * lb * ft**-1 * s**-1
pas = dvis.to(Pa * s)

pas.value  # >>> 1.4881639435695542
pas.units.name  # >>> "Pa s"

'Pa s'

Instantiate unit systems

You can instantiate unit systems using a few methods:

• Custom units

• Predefined unit systems

• Copy from a preexisting unit system

• Combinations of these

# Custom units

dims = BaseDimensions
sys = UnitSystem(base_units={dims.MASS: "slug", dims.LENGTH: "ft"}, system="SI")
sys
"""
MASS: slug LENGTH: ft TIME: s TEMPERATURE: K TEMPERATURE_DIFFERENCE: delta_K ANGLE:

radian CHEMICAL_AMOUNT: mol LIGHT: cd CURRENT: A SOLID_ANGLE: sr.
"""

# Predefined unit systems

cgs = UnitSystem(system="CGS")
cgs
"""
MASS: g LENGTH: cm TIME: s TEMPERATURE: K TEMPERATURE_DIFFERENCE: delta_K ANGLE:

radian CHEMICAL_AMOUNT: mol LIGHT: cd CURRENT: A SOLID_ANGLE: sr.
"""

# Copy from a preexisting unit system

cgs_copy = UnitSystem(copy_from=cgs)
cgs_copy
"""
MASS: g LENGTH: cm TIME: s TEMPERATURE: K TEMPERATURE_DIFFERENCE: delta_K ANGLE:

radian CHEMICAL_AMOUNT: mol LIGHT: cd CURRENT: A SOLID_ANGLE: sr.
"""

# Combinations of these

cgs_modified = UnitSystem(
    base_units={dims.MASS: "slug", dims.LENGTH: "ft", dims.ANGLE: "degree"},
    copy_from=cgs,
)
cgs_modified
"""
MASS: slug LENGTH: ft TIME: s TEMPERATURE: K TEMPERATURE_DIFFERENCE: delta_K ANGLE:

degree CHEMICAL_AMOUNT: mol LIGHT: cd CURRENT: A SOLID_ANGLE: sr.
"""

'\nMASS: slug LENGTH: ft TIME: s TEMPERATURE: K TEMPERATURE_DIFFERENCE: delta_K ANGLE:\n\ndegree CHEMICAL_AMOUNT: mol LIGHT: cd CURRENT: A SOLID_ANGLE: sr.\n'

Create a unit system independently

You can create a unit system independently and apply it to quantities.

si = UnitSystem()
feet_per_second = 11.2 * ft * s**-1

meters_per_second = feet_per_second.convert(si)

meters_per_second.value  # >>> 3.4137599999999995
meters_per_second.units  # >>> "m s^-1"

Unit('m s^-1')

Using preferred units

Specify a list of units that quantities will automatically convert to.

Quantity.preferred_units(units=[J])

torque = Quantity(1, quantity_table={"Torque": 1})
torque  # >>> Quantity (1.0, "J")

ten_N = 10 * N
ten_m = 10 * m

joules = ten_N * ten_m
joules  # >>> Quantity (100.0, "J")

Quantity(100.0, "J")

Preferred units as a conversion policy

PreferredUnits is a separate conversion policy object, independent of UnitSystem, that you pass explicitly to convert(). A UnitSystem only defines base units, so converting through it produces an expanded base-unit expression unless a PreferredUnits policy is supplied.

mm_tonne_second = UnitSystem(
    base_units={dims.MASS: "tonne", dims.LENGTH: "mm", dims.TIME: "s"}
)

expanded = Quantity(210e9, "Pa").convert(mm_tonne_second)
expanded.units.name  # >>> "tonne mm^-1 s^-2"

material_prefs = PreferredUnits(["MPa"])
simplified = Quantity(210e9, "Pa").convert(
    mm_tonne_second, preferred_units=material_prefs
)
simplified.units.name  # >>> "MPa"

# Preferred units match by dimensions only. Quantities with the same
# dimensions, such as stress and energy density, use the same preferred unit.
energy_density = Quantity(210e9, "J m^-3").convert(
    mm_tonne_second, preferred_units=material_prefs
)
energy_density.units.name  # >>> "MPa"

'MPa'