Unit#
This module contains utilities for working with dimensioned real and complex
numbers, as in numbers with units. By default, PSCAD Automation Library obtains
the unit system from a running PSCAD application, hence PSCAD must be running
when using the classes provided here for unit conversions. Alternatively, the
user can provide their own unit system in an XML file using UnitSystem.parse()
.
Unit System#
- class mhi.pscad.unit.UnitSystem#
The system of units to use for conversions.
The individual units which are supported must be provided externally, such as via XML to the
UnitSystem.parse()
method.SI prefixes from Yotta (\(10^{24}\)) to Yocto (\(10^{-24}\)) are supported. Additionally, both “da” and “D” may be used to indicate “Deka” (\(10^{1}\)), and both “µ” and “u” may be used to indicated “micro” (\(10^{-6}\)).
- classmethod parse(xml)#
Extract units from an XML string of the form:
<unit_system> <Domain> <Unit symbol="V" base="V" alias="" inverse="" multiplier="1.0" /> <Unit symbol="A" base="A" alias="" inverse="" multiplier="1.0" /> ... </Domain> <Domain> ... </Domain> ... </unit_system>
- classmethod convert(from_value, from_units, to_units)#
Convert a value from one unit into a different unit.
With appropriate unit definitions:
>>> UnitSystem.convert(100, "km/hr", "mi/hr") 62.1371192237334
If a unit is not recognized, Not-a-Number is returned.
The result will be nonsensical if the unit dimensions do not agree. Converting “km” to “min” will result in multiplication by 16.67, since “km” is 1000 “m” base units, and “min” is 60 “s” base units, this the conversion multiplies by 1000 then divides by 60.
Value#
- class mhi.pscad.unit.Value(value, units=None)#
A floating point value, with units.
A parameter typically has a unit associated with it, such as “km”. The user may enter the parameter value with their own units, such as “100.0 [mi]”. A Value holds the text which has been entered for the parameter, but when used in calculations, it will reflect the numerical value converted to the parameter’s expected units, ie
160.9344
.The value’s unit does not propogate through calculations; to attach units to the calculated value, create a new
Value
.Example
>>> user_input = "100.0 [mi]" >>> parameter_units = "km" >>> length = Value(user_input, parameter_units) >>> length.real 160.9344 >>> length * 2 321.8688 >>> str(length) '100.0 [mi]' >>> double_length = Value(length * 2, "km") >>> str(double_length) '321.8688 [km]'
- normalized(fmt: str = 'f') str #
Return the converted value as a string, along with the expected units.
- Parameters:
fmt (str) – a format specifier, such as
'.2f'
(optional)- Returns:
The converted value.
- Return type:
str
- property units: str#
The units this value is expressed in.
Complex Value#
- class mhi.pscad.unit.ComplexValue(value, units=None)#
A complex value, with units.
A parameter typically has a unit associated with it, such as “km”. The user may enter the parameter value with their own units, such as “(100.0, -12.0) [kV]”. A Value holds the text which has been entered for the parameter, but when used in calculations, it will reflect the numerical value converted to the parameter’s expected units.
The value’s unit does not propogate through calculations; to attach units to the calculated value, create a new
ComplexValue
.Example
>>> user_input = "(1.0, -0.012) [kV]" >>> parameter_units = "V" >>> voltage = ComplexValue(user_input, parameter_units) >>> voltage.real 1000.0 >>> voltage.imag -12.0 >>> voltage * 2 (2000-24j) >>> str(voltage) '(1.0, -0.012) [kV]' >>> double_voltage = ComplexValue(voltage * 2, "V") >>> str(double_voltage) '(2000.0, -24.0) [V]'
- normalized(fmt: str = 'f') str #
Return the converted value as a string, along with the expected units.
- Parameters:
fmt (str) – a format specifier, such as
'.2f'
(optional)- Returns:
The converted value.
- Return type:
str
- property units: str#
The units this value is expressed in.