 |
OTX Reference
|
|
|
OTX Reference
|
|
Data type for handling float values with physical units More...
Namespaces | |
| namespace | DataTypes |
| Data types, see also Core data types. | |
| namespace | Exceptions |
| Error handling. | |
| namespace | Terms |
| Lists all Terms. | |
| namespace | Variables |
| Variable Access. | |
Classes | |
| class | CheckerRule |
| Comprehensive checker rule listing, see also Core checker rules. More... | |
Data type for handling float values with physical units
The Quantities extension provides a new data type Quantity which is derived from Float can be used in all places where FloatTerm or NumericTerm arguments are allowed. The @ç Quantity type contains additional information about a value’s physical unit, allowing it to describe actual measurement values. This allows e.g. the OTX DiagCom extension to use quantities for getting data in and out of diagnostic services.
A Quantity, as mentioned, contains information about a physical unit besides the actual value. To do this, OTX quantities reuses the unit definition data model specified by the ODX standard (see UNIT-SPEC data type in ISO 22901-1). The intention is to use ODX for defining a set of units that can then be referenced by elements of the OTX Quantities extension. As an example, a minimal UNIT-SPEC definition is provided below.
The way an ODX UNIT-SPEC is defined allows an OTX runtime system to automatically convert Quantity values into different units, as long as these are defined as equivalent units in ODX. Thus, an OTX runtime is able to automatically perform basic arithmetic operations on @ç Quantity operands, so for example an addition operation on a Quantity containing a "km/h" value with another Quantity containing a value in "m/s". In subsequent sections, the user-assigned unit of a Quantity is referred to as a display unit, while the corresponding SI-dimensioned unit is called base unit. Accordingly, the quantities' value in display units is called physical or display value, while the value in base SI dimensions is referred to as internal or normalized value.
Since QuantityTerm is based on OTX core FloatTerm, Quantity values can be used in all places where FloatTerm or NumericTerm arguments are allowed. This is e.g. the OTX core arithmetic terms, comparison terms and conversion terms, for which special rules will apply when the operands are Quantity values. There are also places where general rules apply, e.g. where a display value can be used, discarding unit information.
Warning: Special care has to be taken by OTX authors when arithmetic operations are applied on
Quantityvalues with display units involving an offset to the corresponding SI base unit. For instance, consider the operation 50°C - 10°C which yields 40°K (which is -233.15°C). Physically this is correct because the OTX runtime treats the operand 10°C as an absolute temperature quantity, not as a temperature difference. However, OTX authors unaware of the influence of unit offsets might expect a different result (40°C). To facilitate the handling of unit offsets, it is strongly recommended to use separate units for absolute values and difference values, where difference values do not have an offset to the SI base unit. This must be supported by the selectedUNIT-SPECdata base. In the example above, the first operand should use an absolute temperature unit T[°C], while the second operand should use a difference temperature unit ΔT[°C]. With this, the operation 50°C - 10°C yields 313.15°K (40°C), which is the expected result.
When applied to a Quantity, the ToFloat term will return the value of the @ç Quantity normalized to the SI base units correlated to its display unit. For example a Quantity representing a speed value of 12.4 kilometres per hour will return a Float value of 3.44 (as 12.4 km/h equal 3.44 m/s).
When applied to a Quantity, the ToString term will return a String containing the quanitity's display value followed by a space (Unicode character U+0020) followed by the DISPLAY-NAME of the unit definition of its display unit. For computing the string representation of the display value, the same rules as specified for otx:ToString(Float) will apply. However, if the display precision property of the Quantity is set, the fixed-point-part will be rounded to the decimal place given by the display precision property.
Negative precision values are also allowed (expressing decimal positions to the left of the point). For instance, a Quantity representing a speed value of 12.35 kilometres per hour with a display precision of 1 will be rendered as "12.4 km/h", whereas a Quantity of 1234.5 kilometres and a precision of -2 will be rendered as "1200 km", etc. For very large or very small values where ToString yields a representation in scientific notation, the same rules will apply, so for instance a Quantity of 1.123*105 milliseconds with a display precision of 2 will be rendered as "1.12E5 ms". Furthermore, if the display precision is greater than the number of decimal digits representing the fractional part, the string will be stuffed by zero, e.g. a Quantity of 100.1 meters with a display precision of 3 yields "100.100 m".
When applied to a Unit, the ToString term will return a String containing the DISPLAY-NAME of the corresponding unit definition. For example a Quantity representing a speed value of 12.4 kilometres per hour will be rendered as "12.4 km/h".
Important: For all other OTX core conversion terms, the behaviour when applied to
QuantityorUnitvalues is unspecified.
When Quantity values are added or subtracted, the physical dimensions of the display unit of all Quantity operands shall be identical. That means that e.g. a distance Quantity can only be added to another distance Quantity (or a scalar). Otherwise an InvalidConversionException will be thrown, e.g. when a distance is added to a time.
If scalar operands exist, they will be interpreted as normalized values according to the physical dimension of the Quantity operands. This allows e.g. the addition of 2 km + 1 m + 11 which will result in a Quantity of 2012 m.
The display unit of the resulting Quantity will be set to the SI base unit corresponding to the quantity's physical dimension. Furthermore, the display precision of the resulting Quantity will be the maximum of the display precisions of the operands. If the base unit is not defined in the UNIT-SPEC, an InvalidConversionException will be thrown.
When Quantity values are multiplied or divided, a definition of the physical dimension of the resulting Quantity has to exist in the UNIT-SPEC. That means that e.g. a distance Quantity can only be divided by a time Quantity if a distance/time base unit is available (e.g. 72 km divided by 2 h equals 10 m/s). Otherwise an InvalidConversionException will be thrown.
Scalar operands will be interpreted "as is"; this allows e.g. the multiplication of 2 * 2 km which will result in a Quantity of 4000 m.
The display unit of the resulting Quantity will be set to the SI base unit corresponding to the physical dimension resulting from the operation. Furthermore, the display precision of the resulting Quantity will be the maximum of the display precisions of the operands.
When the absolute value or the negation is computed from a Quantity, the display unit of the resulting Quantity should be set to the SI base unit corresponding to the physical dimension of the original Quantity. Furthermore, the display precision of the resulting Quantity will be equal to the display precision of the original Quantity. First the computation to SI Unit is done, and secondly the math function is calculated.
Example: |-10°C| transform to SI |263 K| Result: 263 K (this is equal to -10 °C)
When Quantity values are compared using relational operators, an OTX runtime will use the quantities' normalized values for comparison. So if e.g. a Quantity of 8 kilometres is to be compared with a Quantity of 10 miles, the runtime system will convert both values into meters before doing the comparison. Furthermore, the physical dimensions of the display unit of the Quantity values being compared shall be identical – e.g. it is allowed to compare distances with each other, but it is illegal to compare a distance to a time – in that case an InvalidConversionException will be thrown.
If scalar operands exist, they will be interpreted as normalized values according to the physical dimension of the Quantity operands. This allows e.g. the comparison of 2 km < 11 which will result in false (because the comparison is equivalent to comparing 2 km < 11m).
Generally whenever Quantity values are used in OTX actions or terms for which no specific definition is provided regarding the behaviour in the case of Quantity arguments, the OTX runtime will use the quantity's ToFloat value for computation. For instance, if a Quantity is used as an operand to the Math.Sin term, the Float value (that is, the quantity’s normalized value) will be used as input for the operation.