pyvale 2026.1.1__cp311-cp311-manylinux_2_17_i686.manylinux2014_i686.whl

pyvale/sensorsim/errorsimulator.py

@@ -0,0 +1,137 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
+import enum
+from abc import ABC, abstractmethod
+import numpy as np
+from pyvale.sensorsim.sensordata import SensorData
+
+
+class EErrType(enum.Enum):
+    """Enumeration defining the error type for separation of error types for
+    later analysis.
+
+    EErrType.SYSTEMATIC:
+        Also known as an epistemic error and is due to a lack of
+        knowledge. Common examples include spatial or temporal averaging,
+        digitisation / round off error and calibration errors.
+
+    EErrType.RANDOM:
+        Also known as aleatory error and is generally a result of sensor
+        noise.
+    """
+    SYSTEMATIC = enum.auto()
+    RANDOM = enum.auto()
+
+
+class EErrDep(enum.Enum):
+    """Enumeration defining error dependence.
+
+    EErrDep.INDEPENDENT:
+        Errors are calculated based on the ground truth sensor values
+        interpolated from the input simulation.
+
+    EErrDep.DEPENDENT:
+        Errors are calculated based on the accumulated sensor reading due
+        to all preceeding errors in the chain.
+    """
+    INDEPENDENT = enum.auto()
+    DEPENDENT = enum.auto()
+
+
+class IErrSimulator(ABC):
+    """Interface (abstract base class) for sensor error simulation allowing a
+    list of simulated errors (i.e. an error chain) to be constructed and
+    executed in order.
+    """
+
+    @abstractmethod
+    def get_error_type(self) -> EErrType:
+        """Gets the error type enumeration as either random or systematic. 
+        Random errors sample at every time step and systematic errors typically
+        apply a bias that is constant over time. 
+
+        Returns
+        -------
+        EErrType
+            Enumeration definining RANDOM or SYSTEMATIC error types.
+        """
+
+    @abstractmethod
+    def get_error_dep(self) -> EErrDep:
+        """Gets the error dependence enumeration value. Independent errors are
+        calculated based on the ground truth and ignore other errors in the 
+        error chain. Dependent errors are calculated based on the accumulated
+        measurement value at their place in the error chain.
+
+        Returns
+        -------
+        EErrDep
+            Enumeration definining INDEPENDENT or DEPENDENT error dependence.
+        """
+
+    @abstractmethod
+    def set_error_dep(self, dependence: EErrDep) -> None:
+        """Sets the error dependence for errors that support changing the 
+        dependence. Independent errors are calculated based on the ground truth 
+        and ignore other errors in the error chain. Dependent errors are 
+        calculated based on the accumulated measurement value at their place in 
+        the error chain.
+
+        Parameters
+        ----------
+        dependence : EErrDep
+            Enumeration definining INDEPENDENT or DEPENDENT error dependence.
+        """
+
+    @abstractmethod
+    def reseed(self,seed: int | None = None) -> None:
+        """Reseeds the random generators of the error simulator. Mainly used for
+        multi-processed simulations which inherit the same seed as the main 
+        process so need to be reseeded. If the error simulator does not have any
+        random generators then this function implementation will be empty.
+
+        Parameters
+        ----------
+        seed : int | None, optional
+            Integer seed for the random number generator, by default None. If 
+            None then the seed is generated using OS entropy (see numpy docs).
+        """
+
+
+    @abstractmethod
+    def sim_errs(self,
+                  err_basis: np.ndarray,
+                  sens_data: SensorData,
+                  ) -> tuple[np.ndarray, SensorData]:
+        """Creates the simulated error array based on the input error basis 
+        array. The output error array will be the same shape as the input 
+        error basis array.
+
+        Parameters
+        ----------
+        err_basis : np.ndarray
+            Used as the base array for calculating the returned error. If the 
+            error is independent this will be the 'truth' array and if the error
+            is dependent this will be the accumulated sensor measurement array 
+            at this point in the error chain.
+        sens_data : SensorData
+            Sensor data object holding the current sensor state before applying
+            this error calculation.
+
+        Returns
+        -------
+        tuple[np.ndarray, SensorData]
+            Tuple containing the error array from this calculator and a
+            SensorData object with the current accumulated sensor state starting
+            from the nominal state up to and including this error calculator in
+            the error chain. Note that many errors do not modify the sensor data
+            so the sensor data class is passed through this function unchanged.
+        """
+
+
+
+

pyvale/sensorsim/errorsyscalib.py

@@ -0,0 +1,93 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
+from typing import Callable
+import numpy as np
+from pyvale.sensorsim.errorsimulator import (IErrSimulator,
+                                         EErrType,
+                                         EErrDep)
+from pyvale.sensorsim.sensordata import SensorData
+
+# TODO: add option to use Newton's method for function inversion instead of a
+# cal table.
+
+class ErrSysCalibration(IErrSimulator):
+    """Systematic error calculator for calibration errors. The user specifies an
+    assumed calibration and a ground truth calibration function. The ground
+    truth calibration function is inverted and linearly interpolated numerically
+    based on the number of divisions specified by the user.
+
+    Implements the `IErrSimulator` interface.
+    """
+    __slots__ = ("_assumed_cali","_truth_calib","_cal_range","_n_cal_divs",
+                 "_err_dep","_truth_calc_table")
+
+    def __init__(self,
+                 assumed_calib: Callable[[np.ndarray],np.ndarray],
+                 truth_calib: Callable[[np.ndarray],np.ndarray],
+                 cal_range: tuple[float,float],
+                 n_cal_divs: int = 10000,
+                 err_dep: EErrDep = EErrDep.INDEPENDENT) -> None:
+        """
+        Parameters
+        ----------
+        assumed_calib : Callable[[np.ndarray],np.ndarray]
+            Assumed calibration function taking the input unitless 'signal' and
+            converting it to the same units as the physical field being sampled
+            by the sensor array.
+        truth_calib : Callable[[np.ndarray],np.ndarray]
+            Assumed calibration function taking the input unitless 'signal' and
+            converting it to the same units as the physical field being sampled
+            by the sensor array.
+        cal_range : tuple[float,float]
+            Range over which the calibration functions are valid. This is
+            normally based on a voltage range such as (0,10) volts.
+        n_cal_divs : int, optional
+            Number of divisions to discretise the the truth calibration function
+            for numerical inversion, by default 10000.
+        err_dep : EErrDependence, optional
+            Error calculation dependence, by default EErrDependence.INDEPENDENT.
+        """
+        self._assumed_calib = assumed_calib
+        self._truth_calib = truth_calib
+        self._cal_range = cal_range
+        self._n_cal_divs = n_cal_divs
+        self._err_dep = err_dep
+
+        self._truth_cal_table = np.zeros((n_cal_divs,2))
+        self._truth_cal_table[:,0] = np.linspace(cal_range[0],
+                                                cal_range[1],
+                                                n_cal_divs)
+        self._truth_cal_table[:,1] = self._truth_calib(
+                                        self._truth_cal_table[:,0])
+
+    def get_error_dep(self) -> EErrDep:
+        return self._err_dep
+
+    def set_error_dep(self, dependence: EErrDep) -> None:
+        self._err_dep = dependence
+
+    def get_error_type(self) -> EErrType:
+        return EErrType.SYSTEMATIC
+
+    def reseed(self, seed: int | None = None) -> None:
+        pass
+
+    def sim_errs(self,
+                  err_basis: np.ndarray,
+                  sens_data: SensorData,
+                  ) -> tuple[np.ndarray, SensorData]:
+        # shape=(n_sens,n_comps,n_time_steps)
+        signal_from_field = np.interp(err_basis,
+                                    self._truth_cal_table[:,1],
+                                    self._truth_cal_table[:,0])
+        # shape=(n_sens,n_comps,n_time_steps)
+        field_from_assumed_calib = self._assumed_calib(signal_from_field)
+
+        sys_errs = field_from_assumed_calib - err_basis
+
+        return (sys_errs,sens_data)
+

pyvale/sensorsim/errorsysdep.py

@@ -0,0 +1,197 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
+import enum
+from typing import Callable
+import numpy as np
+from pyvale.sensorsim.sensordata import SensorData
+from pyvale.sensorsim.errorsimulator import (IErrSimulator,
+                                         EErrType,
+                                         EErrDep)
+
+
+class ERoundMethod(enum.Enum):
+    """Enumeration used to specify the method for rounding floats to integers.
+    """
+    ROUND = enum.auto()
+    FLOOR = enum.auto()
+    CEIL = enum.auto()
+
+
+def _select_round_method(method: ERoundMethod) -> Callable:
+    """Helper function for selecting the rounding method based on the user
+    specified enumeration. Returns a numpy function for rounding.
+
+    Parameters
+    ----------
+    method : ERoundMethod
+        Enumeration specifying the rounding method.
+
+    Returns
+    -------
+    Callable
+        numpy rounding method as np.floor, np.ceil or np.round.
+    """
+    if method == ERoundMethod.FLOOR:
+        return np.floor
+    if method == ERoundMethod.CEIL:
+        return np.ceil
+    return np.round
+
+
+class ErrSysRoundOff(IErrSimulator):
+    """Systematic error calculator for round off error. The user can specify the
+    floor, ceiling or nearest integer method for rounding. The user can also
+    specify a base to round to that defaults 1. Implements the `IErrSimulator`
+    interface.
+    """
+    __slots__ = ("_base","_method","_err_dep")
+
+    def __init__(self,
+                 method: ERoundMethod = ERoundMethod.ROUND,
+                 base: float = 1.0,
+                 err_dep: EErrDep = EErrDep.DEPENDENT) -> None:
+        """
+        Parameters
+        ----------
+        method : ERoundMethod, optional
+            Enumeration specifying the rounding method, by default
+            ERoundMethod.ROUND.
+        base : float, optional
+            Base to round to, by default 1.0.
+        err_dep : EErrDependence, optional
+            Error calculation dependence, by default EErrDependence.DEPENDENT.
+        """
+        self._base = base
+        self._method = _select_round_method(method)
+        self._err_dep = err_dep
+
+    def get_error_dep(self) -> EErrDep:
+        return self._err_dep
+
+    def set_error_dep(self, dependence: EErrDep) -> None:
+        self._err_dep = dependence
+
+    def get_error_type(self) -> EErrType:
+        return EErrType.SYSTEMATIC
+
+    def reseed(self, seed: int | None = None) -> None:
+        pass
+
+    def sim_errs(self,
+                  err_basis: np.ndarray,
+                  sens_data: SensorData,
+                  ) -> tuple[np.ndarray, SensorData]:
+        rounded_measurements = self._base*self._method(err_basis/self._base)
+
+        return (rounded_measurements - err_basis,sens_data)
+
+
+class ErrSysDigitisation(IErrSimulator):
+    """Systematic error calculator for digitisation error base on a user
+    specified number of bits per physical unit and rounding method. Implements
+    the `IErrSimulator` interface.
+    """
+    __slots__ = ("_units_per_bit","_method","_err_dep")
+
+    def __init__(self,
+                 bits_per_unit: float,
+                 method: ERoundMethod = ERoundMethod.ROUND,
+                 err_dep: EErrDep = EErrDep.DEPENDENT) -> None:
+        """
+        Parameters
+        ----------
+        bits_per_unit : float
+            The number of bits per physical unit used to determine the
+            digitisation error.
+        method : ERoundMethod, optional
+            User specified rounding method, by default ERoundMethod.ROUND.
+        err_dep : EErrDependence, optional
+            Error calculation dependence, by default EErrDependence.DEPENDENT.
+        """
+        self._units_per_bit = 1/float(bits_per_unit)
+        self._method = _select_round_method(method)
+        self._err_dep = err_dep
+
+    def get_error_dep(self) -> EErrDep:
+        return self._err_dep
+
+    def set_error_dep(self, dependence: EErrDep) -> None:
+        self._err_dep = dependence
+
+    def get_error_type(self) -> EErrType:
+        return EErrType.SYSTEMATIC
+
+    def reseed(self, seed: int | None = None) -> None:
+        pass
+
+    def sim_errs(self,
+                  err_basis: np.ndarray,
+                  sens_data: SensorData,
+                  ) -> tuple[np.ndarray, SensorData]:
+        rounded_measurements = self._units_per_bit*self._method(
+            err_basis/self._units_per_bit)
+
+        return (rounded_measurements - err_basis,sens_data)
+
+
+class ErrSysSaturation(IErrSimulator):
+    """Systematic error calculator for saturation error base on user specified
+    minimum and maximum measurement values. Implements the `IErrSimulator`
+    interface.
+
+    NOTE: For this error to function as expected and clamp the measurement
+    within the specified range it must be placed last in the error chain and
+    the behaviour must be set to: EErrDependence.DEPENDENT.
+    """
+    __slots__ = ("_min","_max","_err_dep")
+
+    def __init__(self,
+                 meas_min: float,
+                 meas_max: float) -> None:
+        """
+        Parameters
+        ----------
+        meas_min : float
+            Minimum value to saturate the measurement to.
+        meas_max : float
+            Maximum value to saturate the measurement to.
+
+        Raises
+        ------
+        ValueError
+            Raised if the user specified minimum measurement is greater than the
+            maximum measurement.
+        """
+        if meas_min > meas_max:
+            raise ValueError("Minimum must be smaller than maximum for "+
+                             "systematic error saturation")
+
+        self._min = meas_min
+        self._max = meas_max
+        self._err_dep = EErrDep.DEPENDENT
+
+    def get_error_dep(self) -> EErrDep:
+        return self._err_dep
+
+    def set_error_dep(self, dependence: EErrDep) -> None:
+        self._err_dep = dependence
+
+    def get_error_type(self) -> EErrType:
+        return EErrType.SYSTEMATIC
+
+    def reseed(self, seed: int | None = None) -> None:
+        pass
+
+    def sim_errs(self,
+                  err_basis: np.ndarray,
+                  sens_data: SensorData,
+                  ) -> tuple[np.ndarray, SensorData]:
+        saturated = np.copy(err_basis)
+        saturated[saturated > self._max] = self._max
+        saturated[saturated < self._min] = self._min
+
+        return (saturated - err_basis,sens_data)