From 906e06c408e3a5a87ea7b83f55d953c73072cae2 Mon Sep 17 00:00:00 2001 From: Nikolai Fast Date: Tue, 12 Nov 2024 16:27:04 +0100 Subject: [PATCH] Cleaned up mathematical notation for physical units (#1995) Co-authored-by: NikolaiFa --- docs/2_4_common_schema.adoc | 122 +++++++++++++++++++++--------------- 1 file changed, 71 insertions(+), 51 deletions(-) diff --git a/docs/2_4_common_schema.adoc b/docs/2_4_common_schema.adoc index b9bb65f8..8d5753c7 100644 --- a/docs/2_4_common_schema.adoc +++ b/docs/2_4_common_schema.adoc @@ -340,7 +340,12 @@ A value latexmath:[v_{\mathit{unit}}] in `Unit` is converted to the base unit la [latexmath] ++++ -v_{\mathit{base}} = \texttt{factor} * v_{\mathit{unit}} + \texttt{if relativeQuantity then 0 else offset} +v_{\mathit{base}} = \texttt{factor} \cdot v_{\mathit{unit}} + \left\{ +\begin{array}{ll} +0 & \texttt{if relativeQuantity = true} \\ +\texttt{offset} & \texttt{if relativeQuantity = false} +\end{array} +\right. ++++ where `factor` and `offset` are attributes of the ``, and `relativeQuantity` an attribute of the `TypeDefinition` of a variable. @@ -348,13 +353,13 @@ _[For example, if_ latexmath:[{p_{\mathit{bar}}}] _is a pressure value in unit ` [latexmath] ++++ -{p_{\mathit{Pa}} = 10^5 p_{\mathit{bar}}} +{p_{\mathit{Pa}} = 10^5 \cdot p_{\mathit{bar}}} ++++ _and therefore, `factor = 1.0e5` and `offset = 0.0`._ _In the following table several unit examples are given._ -_Note that if in column `exponents` the definition_ latexmath:[\frac{kg \cdot m^2}{s^2}] _is present, then the attributes of `` are `kg=1, m=2, s=-2`._ +_Note that if in column `exponents` the definition_ latexmath:[\mathrm{kg} \cdot \mathrm{m}^2 \cdot \mathrm{s}^{-2}] _is present, then the attributes of `` are `kg=1, m=2, s=-2`._ .Unit examples. [[table-unit-examples]] @@ -370,75 +375,75 @@ h|offset |_Torque_ |`N.m` -|latexmath:[{kg \cdot m^2 / s^2}] -|`1.0` -|`0.0` +|latexmath:[\mathrm{kg} \cdot \mathrm{m}^2 \cdot \mathrm{s}^{-2}] +|latexmath:[1.0] +|latexmath:[0.0] |_Energy_ |`J` -|latexmath:[{kg \cdot m^2 / s^2}] -|`1.0` -|`0.0` +|latexmath:[\mathrm{kg} \cdot \mathrm{m}^2 \cdot \mathrm{s}^{-2}] +|latexmath:[1.0] +|latexmath:[0.0] |_Pressure_ |`bar` -|latexmath:[{\frac{kg}{m \cdot s^2}}] -|`1.0e5` -|`0.0` +|latexmath:[\mathrm{kg} \cdot \mathrm{m}^{-1} \cdot \mathrm{s}^{-2}] +|latexmath:[1.0 \cdot 10^5] +|latexmath:[0.0] |_Angle_ |`deg` -|`rad` -|`0.01745329251994330 (= pi/180)` -|`0.0` +|latexmath:[\mathrm{rad}] +|latexmath:[0.01745329251994330 \ \left(= \frac{\pi}{180}\right)] +|latexmath:[0.0] |_Angular velocity_ |`rad/s` -|`rad/s` -|`1.0` -|`0.0` +|latexmath:[\mathrm{rad} \cdot \mathrm{s}^{-1}] +|latexmath:[1.0] +|latexmath:[0.0] |_Angular velocity_ |`rpm` -|`rad/s` -|`0.1047197551196598 (= 2*pi/60)` -|`0.0` +|latexmath:[\mathrm{rad} \cdot \mathrm{s}^{-1}] +|latexmath:[0.1047197551196598 \ \left(= 2 \cdot \frac{\pi}{60}\right)] +|latexmath:[0.0] |_Frequency_ |`Hz` -|`rad/s` -|`6.283185307179586 (= 2*pi)` -|`0.0` +|latexmath:[\mathrm{rad} \cdot \mathrm{s}^{-1}] +|latexmath:[6.283185307179586 \ \left(= 2 \cdot \pi\right)] +|latexmath:[0.0] |_Temperature_ |`°F` -|`K` -|`0.5555555555555556 (= 5/9)` -|`255.3722222222222 (= 273.15-32*5/9)` +|latexmath:[\mathrm{K}] +|latexmath:[0.5555555555555556 \ \left(= \frac{5}{9}\right)] +|latexmath:[255.3722222222222 \ \left(= 273.15 - 32 \cdot \frac{5}{9}\right)] |_Percent by length_ |`%/m` -|`1/m` -|`0.01` -|`0.0` +|latexmath:[\mathrm{m}^{-1}] +|latexmath:[0.01] +|latexmath:[0.0] |_Parts per million_ |`ppm` -|`1` -|`1.0e-6` -|`0.0` +|latexmath:[1] +|latexmath:[1.0 \cdot 10^{-6}] +|latexmath:[0.0] |_Length_ |`km` -|`m` -|`1000` -|`0.0` +|latexmath:[\mathrm{m}] +|latexmath:[1000] +|latexmath:[0.0] |_Length_ |`yd` -|`m` -|`0.9144` -|`0.0` +|latexmath:[\mathrm{m}] +|latexmath:[0.9144] +|latexmath:[0.0] |==== _Note that `Hz` is typically used as `Unit.name` for a frequency quantity, but it can also be used as `` for an angular velocity quantity (since `revolution/s`)._ @@ -452,10 +457,25 @@ _When only one of <> `v2` and <> `v1`, connected with equation `v _When two variables v1 and v2 are connected and for both of them `` elements are defined, then they must have identical exponents of their ``._ _If `factor` and `offset` are also identical, again the connection equation `v2 = v1` holds._ _If `factor` and `offset` are not identical, the tool may either trigger an error or, if supported, perform a conversion; in other words, use the connection equation (in this case the `relativeQuantity` of the ``, see below, has to be taken into account in order to determine whether `offset` shall or shall not be utilized):_ -+ -`factor(v1) * v1 + (if relativeQuantity(v1) then 0 else offset(v1)) = factor(v2) * v2 + (if relativeQuantity(v2) then 0 else offset(v2))` + + +[latexmath] +++++ +\texttt{factor(v1)} \cdot \texttt{v1} + \left\{ +\begin{array}{ll} +0 & \texttt{if relativeQuantity(v1) = true} \\ +\texttt{offset(v1)} & \texttt{if relativeQuantity(v1) = false} +\end{array} +\right. += +\texttt{factor(v2)} \cdot \texttt{v2} + \left\{ +\begin{array}{ll} +0 & \texttt{if relativeQuantity(v2) = true} \\ +\texttt{offset(v2)} & \texttt{if relativeQuantity(v2) = false} +\end{array} +\right. +++++ _where_ `relativeQuantity(v1) = relativeQuantity(v2)` _is required_. -+ + _As a result, wrong connections can be detected (for example, connecting a force with an angle-based variable would trigger an error) and conversions between, say, US and SI units can be either automatically performed or, if not supported, an error is triggered as well._ + _This approach is not satisfactory for variables belonging to different quantities that have, however, the same ``, such as quantities `Energy` and `Torque`, or `AngularVelocity` and `Frequency`._ @@ -473,8 +493,8 @@ _Example:_ [latexmath] ++++ \begin{align*} -J \cdot \alpha = \tau \rightarrow [kg.m^2]*[rad/s^2] = [kg.m^2/s^2] & \quad \text{// o.k. ("rad" is treated as "1")} \\ -J \cdot \alpha = f \rightarrow [kg.m^2]*[rad/s^2] = [kg.m/s^2] & \quad \text{// error, since dimensions do not agree} +J \cdot \alpha = \tau \rightarrow [\mathrm{kg} \cdot \mathrm{m}^2] \cdot [\mathrm{rad} \cdot \mathrm{s}^{-2}] = [\mathrm{kg} \cdot \mathrm{m}^2 \cdot \mathrm{s}^{-2}] & \quad \text{// o.k. ("rad" is treated as "1")} \\ +J \cdot \alpha = f \rightarrow [\mathrm{kg} \cdot \mathrm{m}^2] \cdot [\mathrm{rad} \cdot \mathrm{s}^{-2}] = [\mathrm{kg} \cdot \mathrm{m} \cdot \mathrm{s}^{-2}] & \quad \text{// error, since dimensions do not agree} \end{align*} ++++ @@ -485,11 +505,11 @@ _If no unit computation is needed, `rad` is propagated._ _If a unit computation is needed and one of the involved units has `rad` as a ``, then unit propagation is not possible._ _Examples:_ + -- _a = b + c, and `Unit` of c is provided, but not `Unit` of a and b:_ + +- _latexmath:[a = b + c], and `Unit` of c is provided, but not `Unit` of a and b:_ + _The Unit definition of `c` (in other words, `Unit.name`, ``, ``) is also used for `a` and `b`._ _For example, if BaseUnit(c) = `rad/s`, then BaseUnit(a) = BaseUnit(b) = `rad/s`._ + -- _a = b*c, and `Unit` of a and of c is provided, but not `Unit` of b:_ + +- _latexmath:[a = b \cdot c], and `Unit` of a and of c is provided, but not `Unit` of b:_ + _If `rad` is either part of the `` of `a` and/or of `c`, then the `` of `b` cannot be deduced (otherwise it can be deduced)._ _Example: If `BaseUnit(a) = kg.m/s2` and `BaseUnit(c) = m/s2`, then the `BaseUnit(b)` can be deduced to be `kg`._ _In such a case `Unit.name` of b cannot be deduced from the `Unit.name` of `a` and `c`, and a tool would typically construct the `Unit.name` of `b` from the deduced ``.]_ @@ -512,8 +532,8 @@ A value latexmath:[v_{\mathit{unit}}] in `Unit` is converted to a value latexmat ++++ v_{\mathit{display}} = \left\{\begin{array}{ll} -\texttt{factor} * v_{\mathit{unit}} + \texttt{offset} &\text{if} \; \texttt{inverse = false} \\ -\texttt{factor} * \frac{1}{v_{\mathit{unit}}} &\text{if} \; \texttt{inverse = true} +\texttt{factor} \cdot v_{\mathit{unit}} + \texttt{offset} &\text{if} \; \texttt{inverse = false} \\ +\texttt{factor} \cdot \frac{1}{v_{\mathit{unit}}} &\text{if} \; \texttt{inverse = true} \end{array}\right. ++++ @@ -523,10 +543,10 @@ _For example, if latexmath:[{T_K}] is the temperature value of `Unit.name` (in ` [latexmath] ++++ -T_F = (9/5) * (T_K - 273.15) + 32 +T_F = \frac{9}{5} \cdot (T_K - 273.15) + 32 ++++ -_and therefore, `factor = 1.8 (=9/5)` and `offset = -459.67 (= 32 - 273.15*9/5)`._ +_and therefore, latexmath:[\texttt{factor} = 1.8 \ \left(= \frac{9}{5}\right)] and latexmath:[\texttt{offset} = -459.67 \ \left(= 32 - 273.15 \cdot \frac{9}{5}\right)]._ _Both the `DisplayUnit.name` definitions as well as the `Unit.name` definitions are used in the variable elements._ @@ -638,7 +658,7 @@ _[If, for example, an `` is defined with `name1 = -4`, `name2 = 1`, If not defined and no other information about the nominal value is available, then `nominal = 1` is assumed. For array variables, this nominal value applies to all elements of the array. + _[The nominal value of a variable can be, for example, used to determine the absolute tolerance for this variable as needed by numerical algorithms:_ + -`absoluteTolerance = nominal * tolerance * 0.01` + +`absoluteTolerance = nominal \cdot tolerance \cdot 0.01` + _where `tolerance` is, for example, the relative tolerance defined in <>.]_ |`unbounded`