Units (hwx.common)#

class Units(system='SI', **aliases)#

Bases: object

Utility class used to convert values from one set of units to another.

Attribute Table#

Name

Type

shortSystemName

property

system

property

Method Table#

Name

Description

changeUnitInUnitSystem (self, unitType, unitName, unitSystemName)

Changes the name of the unit in use, for the ‘unitType’ in the unit system

convert (self, value, units, formula, toBase)

Converts the specified value to/from base units.

createUnit (self, unitType, unitName, substitution_str, multiplier=1.0)

Creates a new unit ‘unitName’ of type ‘unitType’.

createUnitSystem (self, newUnitSystemName, templateUnitSystemName=’m Kg N Pa’, unitsToChange=None)

Creates a new Unit System by copying the units used in the templateUnitSystem

deleteUnitSystem (self, unitSystemName)

Deletes the unit system.

extractValueAndUnit (self, string)

Returns a double value and a unit expression from the specified string.

fromBase (self, value, units=’length’)

Converts the value from base units to the user specified unit.

getConversionScaleFactor (self, sourceUnit, targetUnit, units)

Returns the scale factor from source unit to target for the particular formula

getDefinedUnits (self, units=’length’)

Returns all the units defined for the particular formula

getFormattedString (self, value, units=’length’, format=’modeling’)

Converts the value from base units to user units and formats it into a

getInternalName (units)

Named used in c++

getPublicName (units)

Named used in python

getSystemNames (self)

Returns a list of names of the supported systems.

getUserUnit (self, units=’length’)

Returns the formula in the user unit system for the specified units.

getUnitsDisplayName (self, units, withUnits=True)

Converts units to a gui label.

getUnitsFromDisplayName (name)

Returns the units from the display name.

getUserUnit (self, units=’length’)

Returns the formula in the user unit system for the specified units.

setSystem (self, system=’SI’)

Sets user specified system to system.

toBase (self, value, units=’length’)

Converts the value from the user specified unit to base units

Example

Specify the model units.#
from hwx.common import Units

SI = Units(system='SI')
print(SI.shortSystemName)
print(SI.system)

MPA = Units("mpa")
print(MPA.shortSystemName)
print(MPA.system)
class UnitAliases(value)#

Bases: Enum

An enumeration.

Attribute Table#

Name

Type

angle

UnitAliases

byte

UnitAliases

current

UnitAliases

frequency

UnitAliases

length

UnitAliases

mass

UnitAliases

percent

UnitAliases

temperature

UnitAliases

thermalExpansion

UnitAliases

time

UnitAliases

torque

UnitAliases

property system#

Returns the name of the User unit template.

property shortSystemName#

Returns the first part of the system.

setSystem(system='SI')#

Sets user specified system to system.

getSystemNames()#

Returns a list of names of the supported systems.

getUserUnit(units='length')#

Returns the formula in the user unit system for the specified units.

Parameters:

units (str) – The units to consider.

Raises:

ValueError – If units is invalid.

Returns:

The formula in the user unit system.

Return type:

str

getUnit(units='length')#

Returns the formula in the user unit system for the specified units.

Parameters:

units (str) – The units to consider.

Raises:

ValueError – If units is invalid.

Returns:

The formula in the user unit system.

Return type:

str

getDefinedUnits(units='length')#

Returns all the units defined for the particular formula

Parameters:

units (str) – “length”, “mass”, “angle” …

Returns:

list[str]

getConversionScaleFactor(sourceUnit, targetUnit, units)#

Returns the scale factor from source unit to target for the particular formula

Parameters:
  • sourceUnit (str) – “m”, “kg”, “deg” …

  • targetUnit (str) – “cm”, “g”, “rad” …

  • units (str) – “length”, “mass”, “angle” …

Returns:

float

toBase(value, units='length')#

Converts the value from the user specified unit to base units

Parameters:
  • value (Union[float, list[float], str, list[str]]) – The value to convert.

  • units (str) – The units to convert.

Returns:

The converted value.

Return type:

float

fromBase(value, units='length')#

Converts the value from base units to the user specified unit.

Parameters:
  • value (Union[float, list[float], str, list[str]]) – The value to convert.

  • units (str) – The units to convert.

Returns:

The converted value.

Return type:

float

convert(value, units, formula, toBase)#

Converts the specified value to/from base units.

Parameters:
  • value (Union[float, list[float], str, list[str]]) – The value to convert.

  • units (str) – The units to convert.

  • formula (str) – The string conversion expression: m, mm, in, etc.

  • toBase (bool) – Determines whether to convert to base units or not.

Raises:

ValueError – If units is invalid.

Returns:

The converted value.

Return type:

float

getFormattedString(value, units='length', format='modeling')#

Converts the value from base units to user units and formats it into a string containing the value and unit: 5 -> ‘5 cm’.

Parameters:
  • value (float | list[float]) – The float to display. An iterable is returned comma separated: [1, 2] -> ‘1 cm, 2 cm’.

  • units (str) – length, mass, …

  • format (str | list[float, float]) – “modeling”: User preference for values shown during model setup. “results”: User preference for solver results. [width, precision] Python format string like “%g”.

Returns:

str

extractValueAndUnit(string)#

Returns a double value and a unit expression from the specified string.

Parameters:

string (str) – The string containing both the value and the unit.

Raises:

ValueError – If Units could not be split.

Returns:

The double value and the unit expression as a string.

Return type:

tuple[float, str]

getUnitsDisplayName(units, withUnits=True)#

Converts units to a gui label.

Parameters:
  • units (str) – The units.

  • withUnits (bool) – Determines whether to include units in the return value.

Returns:

The display name.

Return type:

str

createUnitSystem(newUnitSystemName, templateUnitSystemName='m Kg N Pa', unitsToChange=None)#
Creates a new Unit System by copying the units used in the templateUnitSystem

and then replacing the units for the unit types defined in unitsToChange.

Parameters:
  • newUnitSystemName (str) – The new unit system name.

  • templateUnitSystemName (str) – Template unit system to get units from and apply to new unit system.

  • unitsToChange (dict[str, str]) – A dictionary with unitTypes as keys and units as values.

Returns:

True on success, False otherwise.

Return type:

bool

deleteUnitSystem(unitSystemName)#

Deletes the unit system.

Parameters:

unitSystemName (str) – The unit system to delete.

Returns:

True on success, False otherwise.

Return type:

bool

createUnit(unitType, unitName, substitution_str, multiplier=1.0)#

Creates a new unit ‘unitName’ of type ‘unitType’.

For instance:

createUnit(‘pressure’, ‘bar’, ‘kg, m, s’, multiplier=1e5)

Parameters:
  • unitType (str) – The new unit type.

  • unitName (str) – The new unit name.

  • substitution_str (str) – A string that must contain, a comma separated list of units which suffice to build the unitType.

  • multiplier (float) – The conversion factor to the corresponding unit in the model unit.

Returns:

True on success, False otherwise.

Return type:

bool

changeUnitInUnitSystem(unitType, unitName, unitSystemName)#

Changes the name of the unit in use, for the ‘unitType’ in the unit system ‘unitSystemName’.

Parameters:
  • unitType (str) – The unit type.

  • unitName (str) – The new unit name.

  • unitSystemName (str) – The system name.

Returns:

True on success, False otherwise.

Return type:

bool