================== Units (hwx.common) ================== Utility class used to convert values from one set of units to another. ---------- Properties ---------- +------------------+------------------+ | shortSystemName_ | systemName_ | +------------------+------------------+ -------------- Public Methods -------------- +-----------------------------------------------------------------------------------------------------+ | classmethod castToInternalExpression_ (cls, units) | +-----------------------------------------------------------------------------------------------------+ | 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') | +-----------------------------------------------------------------------------------------------------+ | getCurrentSystemName_ (self) | +-----------------------------------------------------------------------------------------------------+ | getFormattedString_ (self, value, units='length', format=None) | +-----------------------------------------------------------------------------------------------------+ | 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 ---------------- .. _shortSystemName: .. method:: shortSystemName Returns the first part of the systemName. .. _systemName: .. method:: systemName Returns the name of the User unit template. -------------- Method Details -------------- .. _castToInternalExpression: .. classmethod:: castToInternalExpression(cls, units) Returns aliased units to internal names. .. _getUnitsFromDisplayName: .. classmethod:: getUnitsFromDisplayName(cls, name) Returns the units from the display name. This is the inverse of getUnitsDisplayName. .. _changeUnitInUnitSystem: .. method:: 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: .. method:: 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: :exc:`ValueError` -- If units is invalid. :returns: The converted value. :rtype: float .. _createUnit: .. method:: 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: .. method:: 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: .. method:: 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: .. method:: 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: :exc:`ValueError` -- If Units could not be split. :returns: The double value and the unit expression as a string. :rtype: tuple[float, str] .. _fromBase: .. method:: 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 .. _getCurrentSystemName: .. method:: getCurrentSystemName(self) Returns the current user specified system name. .. _getFormattedString: .. method:: getFormattedString(self, value, units='length', format=None) Converts the value from base units to user units and format the value into a string containing the converted value and the user formula. :param value: The value to convert. :type value: Union[float, list[float], str, list[str]] :param units: The units. :type units: str :param format: The format used to convert the value to a string. :type format: Union[str, callable, tuple[float, float]] :returns: The formatted string. :rtype: str .. _getSystemNames: .. method:: getSystemNames(self) Returns a list of names of the supported systems. .. _getUnit: .. method:: 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: :exc:`ValueError` -- If units is invalid. :returns: The formula in the user unit system. :rtype: str .. _getUnitsDisplayName: .. method:: 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: .. method:: 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: :exc:`ValueError` -- If units is invalid. :returns: The formula in the user unit system. :rtype: str .. _setSystem: .. method:: setSystem(self, system='SI') Sets user specified system to system. .. _toBase: .. method:: 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