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