odxtools 7.1.0__py3-none-any.whl → 7.2.0__py3-none-any.whl

odxtools/compumethods/linearcompumethod.py

@@ -1,212 +1,92 @@
 # SPDX-License-Identifier: MIT
 from dataclasses import dataclass
-from typing import Optional
+from typing import List, cast
+from xml.etree import ElementTree
 
 from ..exceptions import DecodeError, EncodeError, odxassert, odxraise
+from ..odxlink import OdxDocFragment
 from ..odxtypes import AtomicOdxType, DataType
-from .compumethod import CompuMethod, CompuMethodCategory
-from .limit import Limit
+from ..utils import dataclass_fields_asdict
+from .compumethod import CompuCategory, CompuMethod
+from .linearsegment import LinearSegment
 
 
 @dataclass
 class LinearCompuMethod(CompuMethod):
-    """Represents the decoding function d(y) = (offset + factor * y) / denominator
-    where d(y) is the physical value and y is the internal value.
-
-    Examples
-    --------
-
-    Define the decoding function `d(y) = 4+2*y` (or equivalent encoding `e(x) = floor((x-4)/2)`)
-    on all integers `y` in the range -10..10 (and `x` in -16..25).
-
-    ```python
-    method = LinearCompuMethod(
-        offset=4,
-        factor=2,
-        internal_type=DataType.A_INT32,
-        physical_type=DataType.A_INT32,
-        internal_lower_limit = Limit(-10, IntervalType.CLOSED),
-        internal_upper_limit = Limit(11, IntervalType.OPEN)
-    )
-    ```
-
-    Decode an internal value:
-
-    ```python
-    >>> method.convert_internal_to_physical(6)  # == 4+2*6
-    16
-    ```
-
-    Encode a physical value:
-
-    ```python
-    >>> method.convert_physical_to_internal(6)  # == 6/2-2
-    1
-    ```
-
-    Get physical limits:
-
-    ```python
-    >>> method.physical_lower_limit
-    Limit(value=-16, interval_type=IntervalType.CLOSED)
-    >>> method.physical_upper_limit
-    Limit(value=26, interval_type=IntervalType.OPEN)
-    ```
-
-    (Note that there may be additional restrictions to valid physical values by the surrounding data object prop.
-    For example, limits given by the bit length are not considered in the compu method.)
-    """
-
-    offset: float
-    factor: float
-    denominator: float
-    internal_lower_limit: Optional[Limit]
-    internal_upper_limit: Optional[Limit]
+    """A compu method which does linear interpoation
 
-    def __post_init__(self) -> None:
-        odxassert(self.denominator > 0)
+    i.e. internal values are converted to physical ones using the
+    function `f(x) = (offset + factor * x)/denominator` where `f(x)`
+    is the physical value and `x` is the internal value. In contrast
+    to `ScaleLinearCompuMethod`, this compu method only exhibits a
+    single segment)
 
-        self.__compute_physical_limits()
+    For details, refer to ASAM specification MCD-2 D (ODX), section 7.3.6.6.3.
+    """
 
     @property
-    def category(self) -> CompuMethodCategory:
-        return "LINEAR"
+    def segment(self) -> LinearSegment:
+        return self._segment
 
-    @property
-    def physical_lower_limit(self) -> Optional[Limit]:
-        return self._physical_lower_limit
+    @staticmethod
+    def compu_method_from_et(et_element: ElementTree.Element, doc_frags: List[OdxDocFragment], *,
+                             internal_type: DataType,
+                             physical_type: DataType) -> "LinearCompuMethod":
+        cm = CompuMethod.compu_method_from_et(
+            et_element, doc_frags, internal_type=internal_type, physical_type=physical_type)
+        kwargs = dataclass_fields_asdict(cm)
 
-    @property
-    def physical_upper_limit(self) -> Optional[Limit]:
-        return self._physical_upper_limit
-
-    def __compute_physical_limits(self) -> None:
-        """Computes the physical limits and stores them in the properties
-        self._physical_lower_limit and self._physical_upper_limit.
-        This method is only called during the initialization of a LinearCompuMethod.
-        """
-
-        def convert_internal_to_physical_limit(internal_limit: Optional[Limit],
-                                               is_upper_limit: bool) -> Optional[Limit]:
-            """Helper method
-
-            Parameters:
-
-            internal_limit
-                the internal limit to be converted to a physical limit
-            is_upper_limit
-                True iff limit is the internal upper limit
-            """
-            if internal_limit is None or internal_limit.value_raw is None:
-                return None
-
-            internal_value = self.internal_type.from_string(internal_limit.value_raw)
-            physical_value = self._convert_internal_to_physical(internal_value)
-
-            result = Limit(
-                value_raw=str(physical_value),
-                value_type=self.physical_type,
-                interval_type=internal_limit.interval_type)
-
-            return result
-
-        self._physical_lower_limit = None
-        self._physical_upper_limit = None
-
-        if self.factor >= 0:
-            self._physical_lower_limit = convert_internal_to_physical_limit(
-                self.internal_lower_limit, False)
-            self._physical_upper_limit = convert_internal_to_physical_limit(
-                self.internal_upper_limit, True)
-        else:
-            # If the factor is negative, the lower and upper limit are swapped
-            self._physical_lower_limit = convert_internal_to_physical_limit(
-                self.internal_upper_limit, True)
-            self._physical_upper_limit = convert_internal_to_physical_limit(
-                self.internal_lower_limit, False)
-
-    def _convert_internal_to_physical(self, internal_value: AtomicOdxType) -> AtomicOdxType:
-        if not isinstance(internal_value, (int, float)):
-            raise DecodeError(f"The type of internal values of linear compumethods must "
-                              f"either int or float (is: {type(internal_value).__name__})")
-
-        if self.denominator is None:
-            result = self.offset + self.factor * internal_value
-        else:
-            result = (self.offset + self.factor * internal_value) / self.denominator
-
-        if self.physical_type in [
-                DataType.A_INT32,
-                DataType.A_UINT32,
-        ]:
-            result = round(result)
-
-        return self.physical_type.make_from(result)
+        return LinearCompuMethod(**kwargs)
+
+    def __post_init__(self) -> None:
+        odxassert(self.category == CompuCategory.LINEAR,
+                  "LinearCompuMethod must exhibit LINEAR category")
+
+        odxassert(self.physical_type in [
+            DataType.A_FLOAT32,
+            DataType.A_FLOAT64,
+            DataType.A_INT32,
+            DataType.A_UINT32,
+        ])
+        odxassert(self.internal_type in [
+            DataType.A_FLOAT32,
+            DataType.A_FLOAT64,
+            DataType.A_INT32,
+            DataType.A_UINT32,
+        ])
+
+        if self.compu_internal_to_phys is None:
+            odxraise("LINEAR compu methods require COMPU-INTERNAL-TO-PHYS")
+            return
+
+        compu_scales = self.compu_internal_to_phys.compu_scales
+
+        if len(compu_scales) == 0:
+            odxraise("LINEAR compu methods expect at least one compu scale within "
+                     "COMPU-INTERNAL-TO-PHYS")
+            return cast(None, LinearCompuMethod)
+        elif len(compu_scales) > 1:
+            odxraise("LINEAR compu methods expect at most one compu scale within "
+                     "COMPU-INTERNAL-TO-PHYS")
+
+        scale = compu_scales[0]
+        self._segment = LinearSegment.from_compu_scale(
+            scale, internal_type=self.internal_type, physical_type=self.physical_type)
 
     def convert_internal_to_physical(self, internal_value: AtomicOdxType) -> AtomicOdxType:
-        odxassert(self.is_valid_internal_value(internal_value))
-        return self._convert_internal_to_physical(internal_value)
+        if not self._segment.internal_applies(internal_value):
+            odxraise(r"Cannot decode internal value {internal_value}", DecodeError)
+
+        return self._segment.convert_internal_to_physical(internal_value)
 
     def convert_physical_to_internal(self, physical_value: AtomicOdxType) -> AtomicOdxType:
-        if not isinstance(physical_value, (int, float)):
-            odxraise(
-                "The type of physical values of linear compumethods must "
-                "either int or float", EncodeError)
-            return 0
-
-        odxassert(
-            self.is_valid_physical_value(physical_value),
-            f"physical value {physical_value} of type {type(physical_value)} "
-            f"is not valid. Expected type {self.physical_type} with internal "
-            f"range {self.internal_lower_limit} to {self.internal_upper_limit}")
-        if self.denominator is None:
-            result = (physical_value - self.offset) / self.factor
-        else:
-            result = ((physical_value * self.denominator) - self.offset) / self.factor
-
-        if self.internal_type in [
-                DataType.A_INT32,
-                DataType.A_UINT32,
-        ]:
-            result = round(result)
-        return self.internal_type.make_from(result)
+        if not self._segment.physical_applies(physical_value):
+            odxraise(r"Cannot decode physical value {physical_value}", EncodeError)
+
+        return self._segment.convert_physical_to_internal(physical_value)
 
     def is_valid_physical_value(self, physical_value: AtomicOdxType) -> bool:
-        # Do type checks
-        expected_type = self.physical_type.python_type
-        if issubclass(expected_type, float):
-            if not isinstance(physical_value, (int, float)):
-                return False
-        else:
-            if not isinstance(physical_value, expected_type):
-                return False
-
-        # Check the limits
-        if self.physical_lower_limit is not None and not self.physical_lower_limit.complies_to_lower(
-                physical_value):
-            return False
-        if self.physical_upper_limit is not None and not self.physical_upper_limit.complies_to_upper(
-                physical_value):
-            return False
-
-        return True
+        return self._segment.physical_applies(physical_value)
 
     def is_valid_internal_value(self, internal_value: AtomicOdxType) -> bool:
-        # Do type checks
-        expected_type = self.internal_type.python_type
-        if issubclass(expected_type, float):
-            if not isinstance(internal_value, (int, float)):
-                return False
-        else:
-            if not isinstance(internal_value, expected_type):
-                return False
-
-        # Check the limits
-        if self.internal_lower_limit is not None and not self.internal_lower_limit.complies_to_lower(
-                internal_value):
-            return False
-        if self.internal_upper_limit is not None and not self.internal_upper_limit.complies_to_upper(
-                internal_value):
-            return False
-
-        return True
+        return self._segment.internal_applies(internal_value)

odxtools/compumethods/linearsegment.py

@@ -0,0 +1,193 @@
+# SPDX-License-Identifier: MIT
+from dataclasses import dataclass
+from typing import Optional, Union
+
+from ..exceptions import odxraise, odxrequire
+from ..odxtypes import AtomicOdxType, DataType
+from .compuscale import CompuScale
+from .limit import Limit
+
+
+@dataclass
+class LinearSegment:
+    """Helper class to represent a segment of a piecewise-linear interpolation.
+
+    Multiple compu methods (LINEAR, SCALE-LINEAR, TAB-INTP) require
+    linear interpolation. This class centralizes the required
+    parameters for a single such segment. (The required parameters are
+    extracted from the respective compu method's
+    COMPU-INTERNAL-TO-PHYS objects. We do it this way because the
+    internal-to-phys objects are rather clunky to work with and
+    feature a lot of irrelevant information.)
+
+    """
+    offset: float
+    factor: float
+    denominator: float
+    internal_lower_limit: Optional[Limit]
+    internal_upper_limit: Optional[Limit]
+
+    inverse_value: Union[int, float]  # value used as inverse if factor is 0
+
+    internal_type: DataType
+    physical_type: DataType
+
+    @staticmethod
+    def from_compu_scale(scale: CompuScale, *, internal_type: DataType,
+                         physical_type: DataType) -> "LinearSegment":
+        coeffs = odxrequire(scale.compu_rational_coeffs)
+
+        offset = coeffs.numerators[0]
+        factor = coeffs.numerators[1]
+
+        denominator = 1.0
+        if len(coeffs.denominators) > 0:
+            denominator = coeffs.denominators[0]
+
+        inverse_value: Union[int, float] = 0
+        if scale.compu_inverse_value is not None:
+            if abs(factor) < 1e-10:
+                odxraise(f"COMPU-INVERSE-VALUE for non-zero slope ({factor}) defined")
+            x = odxrequire(scale.compu_inverse_value).value
+            if not isinstance(x, (int, float)):
+                odxraise(f"Non-numeric COMPU-INVERSE-VALUE specified ({x!r})")
+            inverse_value = x
+
+        internal_lower_limit = scale.lower_limit
+        internal_upper_limit = scale.upper_limit
+
+        return LinearSegment(
+            offset=offset,
+            factor=factor,
+            denominator=denominator,
+            internal_lower_limit=internal_lower_limit,
+            internal_upper_limit=internal_upper_limit,
+            inverse_value=inverse_value,
+            internal_type=internal_type,
+            physical_type=physical_type)
+
+    @property
+    def physical_lower_limit(self) -> Optional[Limit]:
+        return self._physical_lower_limit
+
+    @property
+    def physical_upper_limit(self) -> Optional[Limit]:
+        return self._physical_upper_limit
+
+    def __post_init__(self) -> None:
+        self.__compute_physical_limits()
+
+    def convert_internal_to_physical(self, internal_value: AtomicOdxType) -> Union[float, int]:
+        if not isinstance(internal_value, (int, float)):
+            odxraise(f"Internal values of linear compumethods must "
+                     f"either be int or float (is: {type(internal_value).__name__})")
+
+        result = (self.offset + self.factor * internal_value) / self.denominator
+
+        if self.physical_type in [
+                DataType.A_INT32,
+                DataType.A_UINT32,
+        ]:
+            result = round(result)
+
+        return result
+
+    def convert_physical_to_internal(self, physical_value: AtomicOdxType) -> Union[float, int]:
+        if not isinstance(physical_value, (int, float)):
+            odxraise(f"Physical values of linear compumethods must "
+                     f"either be int or float (is: {type(physical_value).__name__})")
+
+        if abs(self.factor) < 1e-10:
+            # "If factor = 0 then COMPU-INVERSE-VALUE shall be specified.
+            return self.inverse_value
+
+        result = (physical_value * self.denominator - self.offset) / self.factor
+
+        if self.internal_type in [
+                DataType.A_INT32,
+                DataType.A_UINT32,
+        ]:
+            result = round(result)
+
+        return result
+
+    def __compute_physical_limits(self) -> None:
+        """Computes the physical limits and stores them in the properties
+        self._physical_lower_limit and self._physical_upper_limit.
+        This method is called by `__post_init__()`.
+        """
+
+        def convert_internal_to_physical_limit(internal_limit: Optional[Limit],
+                                               is_upper_limit: bool) -> Optional[Limit]:
+            """Helper method to convert a single internal limit
+            """
+            if internal_limit is None or internal_limit.value_raw is None:
+                return None
+
+            internal_value = self.internal_type.from_string(internal_limit.value_raw)
+            physical_value = self.convert_internal_to_physical(internal_value)
+
+            result = Limit(
+                value_raw=str(physical_value),
+                value_type=self.physical_type,
+                interval_type=internal_limit.interval_type)
+
+            return result
+
+        self._physical_lower_limit = None
+        self._physical_upper_limit = None
+
+        if self.factor >= 0:
+            self._physical_lower_limit = convert_internal_to_physical_limit(
+                self.internal_lower_limit, False)
+            self._physical_upper_limit = convert_internal_to_physical_limit(
+                self.internal_upper_limit, True)
+        else:
+            # If the scaling factor is negative, the lower and upper
+            # limit are swapped
+            self._physical_lower_limit = convert_internal_to_physical_limit(
+                self.internal_upper_limit, True)
+            self._physical_upper_limit = convert_internal_to_physical_limit(
+                self.internal_lower_limit, False)
+
+    def physical_applies(self, physical_value: AtomicOdxType) -> bool:
+        """Returns True iff the segment is applicable to a given physical value"""
+        # Do type checks
+        expected_type = self.physical_type.python_type
+        if issubclass(expected_type, float):
+            if not isinstance(physical_value, (int, float)):
+                return False
+        else:
+            if not isinstance(physical_value, expected_type):
+                return False
+
+        if self._physical_lower_limit is not None and \
+           not self._physical_lower_limit.complies_to_lower(physical_value):
+            return False
+
+        if self._physical_upper_limit is not None and \
+           not self._physical_upper_limit.complies_to_upper(physical_value):
+            return False
+
+        return True
+
+    def internal_applies(self, internal_value: AtomicOdxType) -> bool:
+        """Returns True iff the segment is applicable to a given internal value"""
+        # Do type checks
+        expected_type = self.internal_type.python_type
+        if issubclass(expected_type, float):
+            if not isinstance(internal_value, (int, float)):
+                return False
+        else:
+            if not isinstance(internal_value, expected_type):
+                return False
+
+        if self.internal_lower_limit is not None and \
+           not self.internal_lower_limit.complies_to_lower(internal_value):
+            return False
+
+        if self.internal_upper_limit is not None and \
+           not self.internal_upper_limit.complies_to_upper(internal_value):
+            return False
+
+        return True

odxtools/compumethods/scalelinearcompumethod.py

@@ -1,39 +1,145 @@
 # SPDX-License-Identifier: MIT
 from dataclasses import dataclass
-from typing import List
+from typing import List, Union, cast
+from xml.etree import ElementTree
 
-from ..exceptions import odxassert
-from ..odxtypes import AtomicOdxType
-from .compumethod import CompuMethod, CompuMethodCategory
-from .linearcompumethod import LinearCompuMethod
+from ..exceptions import DecodeError, EncodeError, odxassert, odxraise
+from ..odxlink import OdxDocFragment
+from ..odxtypes import AtomicOdxType, DataType
+from ..utils import dataclass_fields_asdict
+from .compumethod import CompuCategory, CompuMethod
+from .limit import IntervalType
+from .linearsegment import LinearSegment
 
 
 @dataclass
 class ScaleLinearCompuMethod(CompuMethod):
-    linear_methods: List[LinearCompuMethod]
+    """A piecewise linear compu method which may feature discontinuities.
+
+    For details, refer to ASAM specification MCD-2 D (ODX), section 7.3.6.6.4.
+    """
 
     @property
-    def category(self) -> CompuMethodCategory:
-        return "SCALE-LINEAR"
-
-    def convert_physical_to_internal(self, physical_value: AtomicOdxType) -> AtomicOdxType:
-        odxassert(
-            self.is_valid_physical_value(physical_value),
-            f"cannot convert the invalid physical value {physical_value!r} "
-            f"of type {type(physical_value)}")
-        lin_method = next(
-            scale for scale in self.linear_methods if scale.is_valid_physical_value(physical_value))
-        return lin_method.convert_physical_to_internal(physical_value)
-
-    def convert_internal_to_physical(self, internal_value: AtomicOdxType) -> AtomicOdxType:
-        lin_method = next(
-            scale for scale in self.linear_methods if scale.is_valid_internal_value(internal_value))
-        return lin_method.convert_internal_to_physical(internal_value)
+    def segments(self) -> List[LinearSegment]:
+        return self._segments
+
+    @staticmethod
+    def compu_method_from_et(et_element: ElementTree.Element, doc_frags: List[OdxDocFragment], *,
+                             internal_type: DataType,
+                             physical_type: DataType) -> "ScaleLinearCompuMethod":
+        cm = CompuMethod.compu_method_from_et(
+            et_element, doc_frags, internal_type=internal_type, physical_type=physical_type)
+        kwargs = dataclass_fields_asdict(cm)
+
+        return ScaleLinearCompuMethod(**kwargs)
+
+    def __post_init__(self) -> None:
+        self._segments: List[LinearSegment] = []
+
+        odxassert(self.category == CompuCategory.SCALE_LINEAR,
+                  "ScaleLinearCompuMethod must exibit SCALE-LINEAR category")
+
+        odxassert(self.physical_type in [
+            DataType.A_FLOAT32,
+            DataType.A_FLOAT64,
+            DataType.A_INT32,
+            DataType.A_UINT32,
+        ])
+        odxassert(self.internal_type in [
+            DataType.A_FLOAT32,
+            DataType.A_FLOAT64,
+            DataType.A_INT32,
+            DataType.A_UINT32,
+        ])
+
+        if self.compu_internal_to_phys is None:
+            odxraise("SCALE-LINEAR compu methods require COMPU-INTERNAL-TO-PHYS")
+            return
+
+        compu_scales = self.compu_internal_to_phys.compu_scales
+
+        for scale in compu_scales:
+            self._segments.append(
+                LinearSegment.from_compu_scale(
+                    scale, internal_type=self.internal_type, physical_type=self.physical_type))
+
+        # find out if the transfer function is invertible (i.e. if it
+        # can be encoded by normal means). section 7.3.6.6.4 of the
+        # ODX specification states that the condition for
+        # invertibility is that adjacent COMPU-SCALES exhibit the same
+        # values on their common boundaries and that the slope in all
+        # intervals exhibit the same sign (or are 0). For segments
+        # with a slope of zero, COMPU-INVERSE-VALUE shall be used.
+        self._is_invertible = True
+        ref_factor = self._segments[0].factor
+        for i in range(0, len(self._segments) - 1):
+            s0 = self.segments[i]
+            s1 = self.segments[i + 1]
+
+            if ref_factor * s1.factor < 0:
+                self._is_invertible = False
+                break
+            if s1.factor != 0:
+                ref_factor = s1.factor
+
+            # both interval boundaries must not be infinite
+            if s0.internal_upper_limit is None or \
+               s1.internal_lower_limit is None:
+                self._is_invertible = False
+                break
+            elif s0.internal_upper_limit.value is None or \
+               s1.internal_lower_limit.value is None or \
+               s0.internal_upper_limit.interval_type == IntervalType.INFINITE or \
+               s1.internal_lower_limit.interval_type == IntervalType.INFINITE:
+                self._is_invertible = False
+                break
+
+            # the intervals must use the same reference point
+            if (x := s0.internal_upper_limit.value) != s1.internal_lower_limit.value:
+                self._is_invertible = False
+                break
+
+            if not isinstance(x, (int, float)):
+                odxraise("Linear segments must use int or float for all quantities")
+
+            # the respective function value at the interval's
+            # reference point must be identical
+            y0 = s0.convert_internal_to_physical(x)
+            y1 = s1.convert_internal_to_physical(x)
+            if abs(y0 - y1) < 1e-10:
+                self._is_invertible = False
+                break
+
+    def convert_physical_to_internal(self, physical_value: AtomicOdxType) -> Union[float, int]:
+        if not self._is_invertible:
+            odxraise(
+                f"Trying to encode value {physical_value!r} using a non-invertible "
+                f"SCALE-LINEAR transfer function", EncodeError)
+
+        applicable_segments = [
+            seg for seg in self._segments if seg.physical_applies(physical_value)
+        ]
+        if not applicable_segments:
+            odxraise(r"No applicable segment for value {physical_value} found", EncodeError)
+            return cast(int, None)
+
+        seg = applicable_segments[0]
+
+        return seg.convert_physical_to_internal(physical_value)
+
+    def convert_internal_to_physical(self, internal_value: AtomicOdxType) -> Union[float, int]:
+        applicable_segments = [
+            seg for seg in self._segments if seg.internal_applies(internal_value)
+        ]
+        if not applicable_segments:
+            odxraise(r"No applicable segment for value {internal_value} found", DecodeError)
+            return cast(int, None)
+
+        seg = applicable_segments[0]
+        return seg.convert_internal_to_physical(internal_value)
 
     def is_valid_physical_value(self, physical_value: AtomicOdxType) -> bool:
-        return any(
-            True for scale in self.linear_methods if scale.is_valid_physical_value(physical_value))
+        return any(True for seg in self._segments if seg.physical_applies(physical_value))
 
     def is_valid_internal_value(self, internal_value: AtomicOdxType) -> bool:
-        return any(
-            True for scale in self.linear_methods if scale.is_valid_internal_value(internal_value))
+        return any(True for seg in self._segments if seg.internal_applies(internal_value))