Units (hwx.common)¶
Utility class used to convert values from one set of units to another.
Properties¶
Public Methods¶
classmethod getUnitsFromDisplayName (cls, name)
changeUnitInUnitSystem (self, unitType, unitName, unitSystemName)
convert (self, value, units, formula, toBase)
createUnit (self, unitType, unitName, substitution_str, multiplier=1.0)
createUnitSystem (self, newUnitSystemName, templateUnitSystemName=’m Kg N Pa’, unitsToChange=None)
deleteUnitSystem (self, unitSystemName)
extractValueAndUnit (self, string)
fromBase (self, value, units=’length’)
getFormattedString (self, value, units=’length’, format=’modeling’)
getSystemNames (self)
getUnit (self, units=’length’)
getUnitsDisplayName (self, units, withUnits=True)
getUserUnit (self, units=’length’)
setSystem (self, system=’SI’)
toBase (self, value, units=’length’)
Property Details¶
- property shortSystemName¶
Returns the first part of the system.
- property system¶
Returns the name of the User unit template.
Method Details¶
- classmethod getUnitsFromDisplayName(cls, name)¶
Returns the units from the display name.
This is the inverse of getUnitsDisplayName.
- changeUnitInUnitSystem(self, unitType, unitName, unitSystemName)¶
Changes the name of the unit in use, for the “unitType” in the unit system “unitSystemName”.
- param unitType
The unit type.
- type unitType
str
- param unitName
The new unit name.
- type unitName
str
- param unitSystemName
The system name.
- type unitSystemName
str
- returns
True on success, False otherwise.
- rtype
bool
- convert(self, value, units, formula, toBase)¶
Converts the specified value to/from base units.
- param value
The value to convert.
- type value
Union[float, list[float], str, list[str]]
- param units
The units to convert.
- type units
str
- param formula
The string conversion expression: m, mm, in, etc.
- type formula
str
- param toBase
Determines whether to convert to base units or not.
- type toBase
bool
- raises ValueError
If units is invalid.
- returns
The converted value.
- rtype
float
- createUnit(self, 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)
- param unitType
The new unit type.
- type unitType
str
- param unitName
The new unit name.
- type unitName
str
- param substitution_str
A string that must contain, a comma separated list of units which suffice to build the unitType.
- type substitution_str
str
- param multiplier
The conversion factor to the corresponding unit in the model unit.
- type multiplier
float
- returns
True on success, False otherwise.
- rtype
bool
- createUnitSystem(self, 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.
- param newUnitSystemName
The new unit system name.
- type newUnitSystemName
str
- param templateUnitSystemName
Template unit system to get units from and apply to new unit system.
- type templateUnitSystemName
str
- param unitsToChange
A dictionary with unitTypes as keys and units as values.
- type unitsToChange
dict[str, str]
- returns
True on success, False otherwise.
- rtype
bool
- deleteUnitSystem(self, unitSystemName)¶
Deletes the unit system.
- param unitSystemName
The unit system to delete.
- type unitSystemName
str
- returns
True on success, False otherwise.
- rtype
bool
- extractValueAndUnit(self, string)¶
Returns a double value and a unit expression from the specified string.
- param string
The string containing both the value and the unit.
- type string
str
- raises ValueError
If Units could not be split.
- returns
The double value and the unit expression as a string.
- rtype
tuple[float, str]
- fromBase(self, value, units='length')¶
Converts the value from base units to the user specified unit.
- param value
The value to convert.
- type value
Union[float, list[float], str, list[str]]
- param units
The units to convert.
- type units
str
- returns
The converted value.
- rtype
float
- getFormattedString(self, 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”.
- param value
The float to display. An iterable is returned comma separated: [1, 2] -> “1 cm, 2 cm”.
- type value
float | list[float]
- param units
length, mass, …
- type units
str
- param format
“modeling”: User preference for values shown during model setup. “results”: User preference for solver results. [width, precision] Python format string like “%g”.
- type format
str | list[float, float]
- returns
str
- getSystemNames(self)¶
Returns a list of names of the supported systems.
- getUnit(self, units='length')¶
Returns the formula in the user unit system for the specified units.
- param units
The units to consider.
- type units
str
- raises ValueError
If units is invalid.
- returns
The formula in the user unit system.
- rtype
str
- getUnitsDisplayName(self, units, withUnits=True)¶
Converts units to a gui label.
- param units
The units.
- type units
str
- param withUnits
Determines whether to include units in the return value.
- type withUnits
bool
- returns
The display name.
- rtype
str
- getUserUnit(self, units='length')¶
Returns the formula in the user unit system for the specified units.
- param units
The units to consider.
- type units
str
- raises ValueError
If units is invalid.
- returns
The formula in the user unit system.
- rtype
str
- 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
- param value
The value to convert.
- type value
Union[float, list[float], str, list[str]]
- param units
The units to convert.
- type units
str
- returns
The converted value.
- rtype
float