pyvale 2026.1.1__cp311-cp311-manylinux_2_17_i686.manylinux2014_i686.whl

pyvale/sensorsim/errordriftcalc.py

@@ -0,0 +1,104 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
+from abc import ABC, abstractmethod
+import numpy as np
+
+
+class IDriftCalculator(ABC):
+    """Interface (abstract base class) for applying a function to cause a sensor
+    array measurement to drift (normally over time). The initialiser for the
+    concrete implementation of this class specifies the function parameters and
+    a unified method is provided to calculate the drift based on the input.
+    """
+
+    @abstractmethod
+    def calc_drift(self, drift_var: np.ndarray) -> np.ndarray:
+        """Abstract method. Used to calculate the drift function based on the
+        input drift variable (useually the time steps).
+
+        Parameters
+        ----------
+        drift_var : np.ndarray
+            Array of values (normally time steps) that are used to calculate the
+            drift errors.
+
+        Returns
+        -------
+        np.ndarray
+            Array of drift errors having the same shape as the input drift_var
+            array.
+        """
+
+
+class DriftConstant(IDriftCalculator):
+    """Class for applying a constant drift error over time.
+
+    Implements the IDriftCalculator interface.
+    """
+    __slots__ = ("_offset",)
+
+    def __init__(self, offset: float) -> None:
+        """
+        Parameters
+        ----------
+        offset : float
+            Constant drift offset.
+        """
+        self._offset = offset
+
+    def calc_drift(self, drift_var: np.ndarray) -> np.ndarray:
+        return self._offset*np.ones_like(drift_var)
+
+
+class DriftLinear(IDriftCalculator):
+    """Class for applying a linear drift error over time.
+
+    Implements the IDriftCalculator interface.
+    """
+    __slots__ = ("_slope","_offset")
+
+    def __init__(self, slope: float, offset: float = 0.0) -> None:
+        """
+        Parameters
+        ----------
+        slope : float
+            Slope of the drift error function.
+        offset : float, optional
+            Offset (intercept) of the drift error function, by default 0.0.
+        """
+        self._slope = slope
+        self._offset = offset
+
+    def calc_drift(self, drift_var: np.ndarray) -> np.ndarray:
+        return self._slope*drift_var + self._offset
+
+
+class DriftPolynomial(IDriftCalculator):
+    """Class for applying a polynomial drift error over time. The coefficients
+    of the polynomial are specified with a numpy array from constant term to
+    highest power.
+
+    Implements the IDriftCalculator interface.
+    """
+
+    __slots__ = ("_coeffs",)
+
+    def __init__(self, coeffs: np.ndarray) -> None:
+        """
+        Parameters
+        ----------
+        coeffs : np.ndarray
+            Array of polynomial coefficients from constant to highest power.
+        """
+        self._coeffs = coeffs
+
+    def calc_drift(self, drift_var: np.ndarray) -> np.ndarray:
+        poly = np.zeros_like(drift_var)
+        for ii,cc in enumerate(self._coeffs):
+            poly += cc*drift_var**ii
+
+        return poly

pyvale/sensorsim/errorintegrator.py

@@ -0,0 +1,359 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
+import copy
+from dataclasses import dataclass
+import numpy as np
+from pyvale.sensorsim.errorsimulator import (IErrSimulator,
+                                              EErrType,
+                                              EErrDep)
+from pyvale.sensorsim.sensordata import SensorData
+
+
+@dataclass(slots=True)
+class ErrIntOpts:
+    """Error integration options dataclass. Allows the user to control how
+    errors are calculated and stored in memory for later use.
+    """
+
+    force_dependence: EErrDep | None = None
+    """Forces all errors to be calculated with the specified dependence. If set
+    to None then all errors will use their default/preset dependence.
+
+    Note that some errors are inherently independent so will not change. For
+    example: `ErrRandNormal` is purely independent whereas `ErrRandNormPercent`
+    can have the percentage error calculated based on the ground truth
+    (independent) or based on the accumulated sensor measurement (dependent).
+    """
+
+    store_all_errs: bool = False
+    """Stores all errors for individual error in the chain if True. Also stores
+    a list of SensorData objects showing perturbations to the sensor array
+    parameters caused by individual errors. Consumes significantly more memory
+    but is useful for finding which errors contribute most to the total
+    measurement error. For large sensor arrays (>100 sensors)
+    """
+
+
+class ErrIntegrator:
+    """Class for managing sensor error integration. Takes a list of objects that
+    implement the `IErrSimulator` interface (i.e. the error chain) and loops
+    through them calculating each errors contribution to the total measurement
+    error and sums this over all errors in the chain. In addition to the total
+    error a sum of the random and systematic errors (see `EErrType`) is
+    calculated and stored.
+
+    This class also accumulates perturbations to the sensor array parameters due
+    to errors (i.e. sensor positioning error or temporal drift). The accumulated
+    sensor array parameters are stored as a `SensorData` object.
+
+    The errors are calculated in the order specified in the list. For dependent
+    errors (`EErrDependence.DEPENDENT`) the position of the error within the
+    error chain determines the accumulated sensor measurement that will be used
+    to calculate the error.
+
+    The user can control how the errors are calculated using the `ErrIntOpts`
+    dataclass.
+    """
+    __slots__ = ("_err_chain","_meas_shape","_errs_by_chain",
+                 "_errs_systematic","_errs_random","_errs_total",
+                 "_sens_data_by_chain","_err_int_opts","_sens_data_accumulated",
+                 "_sens_data_initial")
+
+    def __init__(self,
+                 err_chain: list[IErrSimulator],
+                 sensor_data_initial: SensorData,
+                 meas_shape: tuple[int,int,int],
+                 err_int_opts: ErrIntOpts | None = None) -> None:
+        """
+        Parameters
+        ----------
+        err_chain : list[IErrSimulator]
+            List of error objects implementing the IErrSimulator interface.
+        sensor_data_initial : SensorData
+            Object holding the initial sensor array parameters before they are
+            modified by the error chain.
+        meas_shape : tuple[int,int,int]
+            Shape of the sensor measurement array. shape=(num_sensors,
+            num_field_components,num_time_steps)
+        err_int_opts : ErrIntOpts | None, optional
+            Options for controlling how errors are calculated/summed and how
+            they are store in memory, by default None. If None then the default
+            options dataclass is used.
+        """
+
+        if err_int_opts is None:
+            self._err_int_opts = ErrIntOpts()
+        else:
+            self._err_int_opts = err_int_opts
+
+        self.set_error_chain(err_chain)
+        self._meas_shape = meas_shape
+
+        self._sens_data_initial = copy.deepcopy(sensor_data_initial)
+        self._sens_data_accumulated = copy.deepcopy(sensor_data_initial)
+
+        if self._err_int_opts.store_all_errs:
+            self._sens_data_by_chain = []
+            self._errs_by_chain = np.zeros((len(self._err_chain),)+ \
+                                               self._meas_shape)
+        else:
+            self._sens_data_by_chain = None
+            self._errs_by_chain = None
+
+        self._errs_systematic = np.zeros(meas_shape)
+        self._errs_random = np.zeros(meas_shape)
+        self._errs_total = np.zeros(meas_shape)
+
+
+    def reseed_error_chain(self, seed: int | None = None) -> None:
+        """Iterates through the error chain and calls the reseed method for all
+        errors in the chain. Used for reseeding multi-processed simulations 
+        where all workers inherit the same seed from the main process.
+
+        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).
+        """    
+        for ee in self._err_chain:
+            ee.reseed(seed)
+
+    def set_error_chain(self, err_chain: list[IErrSimulator]) -> None:
+        """Sets the error chain that will be looped over to calculate the sensor
+        measurement errors. If the error integration options are forcing error
+        dependence then all errors in the chain will have their dependence set
+        to the specified value.
+
+        Parameters
+        ----------
+        err_chain : list[IErrSimulator]
+            List of error calculators implementing the IErrSimulator interface.
+        """
+        self._err_chain = err_chain
+
+        if self._err_int_opts.force_dependence is not None:
+            for ee in self._err_chain:
+                ee.set_error_dep(self._err_int_opts.force_dependence)
+
+
+    def calc_errors_from_chain(self, truth: np.ndarray) -> np.ndarray:
+        """Calculates all errors by looping over the error chain. The total
+         measurement error is summed as each error is calculated in order. Note
+         that this causes all errors based on probability distributions to be
+         resampled and any required interpolations to be performed (e.g. from
+         randomly perturbing the sensor positions). Accumulated errors are also
+         stored for random and systematic errors separately (see `EErrType`).
+
+         If the `store_all_errs = True` in the `ErrIntOpts` dataclass then each
+         individual error is stored in a numpy array (see `get_errs_by_chain()`)
+         along with the accumulated errors in another numpy array.
+
+        Parameters
+        ----------
+        truth : np.ndarray
+            Array of ground truth sensor measurements interpolated from the
+            simulated physical field. shape=(num_sensors,num_field_components,
+            num_time_steps).
+
+        Returns
+        -------
+        np.ndarray
+            Array of total errors summed over all errors in the chain. shape=(
+            num_sensors,num_field_components,num_time_steps).
+        """
+        # NOTE: needed to make sure dependent field errors always start from
+        # nominal before the error chain is evaluated. Otherwise dependent field
+        # errors create a random walk in sensor position.
+        self._sens_data_accumulated = copy.deepcopy(self._sens_data_initial)
+
+        if self._err_int_opts.store_all_errs:
+            return self._calc_errors_store_by_chain(truth)
+
+        return self._calc_errors_mem_eff(truth)
+
+
+    def _calc_errors_store_by_chain(self, truth: np.ndarray) -> np.ndarray:
+        """Helper function for calculating all errors in the chain and summing
+        them. Returns the total error and stores sums of the random and
+        systematic errors in member variables. This function also stores each
+        individual error calculation in a separate numpy array for analysis.
+
+        Parameters
+        ----------
+        truth : np.ndarray
+            Array of ground truth sensor measurements interpolated from the
+            simulated physical field. shape=(num_sensors,num_field_components,
+            num_time_steps).
+
+        Returns
+        -------
+        np.ndarray
+            Array of total errors summed over all errors in the chain. shape=(
+            num_sensors,num_field_components,num_time_steps).
+        """
+        self._errs_total = np.zeros_like(truth)
+        self._errs_systematic = np.zeros_like(truth)
+        self._errs_random = np.zeros_like(truth)
+        self._errs_by_chain = (np.zeros((len(self._err_chain),)
+                               + self._meas_shape))
+
+        for ii,ee in enumerate(self._err_chain):
+
+            if ee.get_error_dep() == EErrDep.DEPENDENT:
+                (error_array,sens_data) = ee.sim_errs(truth+self._errs_total,
+                                                       self._sens_data_accumulated)
+                # Only accumulate sensor data perturbations for dependent errs
+                self._sens_data_accumulated = copy.deepcopy(sens_data)
+            else:
+                (error_array,sens_data) = ee.sim_errs(truth,
+                                                       self._sens_data_initial)
+
+            self._sens_data_by_chain.append(sens_data)
+
+            if ee.get_error_type() == EErrType.SYSTEMATIC:
+                self._errs_systematic = self._errs_systematic + error_array
+            else:
+                self._errs_random = self._errs_random + error_array
+
+            self._errs_total = self._errs_total + error_array
+            self._errs_by_chain[ii,:,:,:] = error_array
+
+        return self._errs_total
+
+
+    def _calc_errors_mem_eff(self, truth: np.ndarray) -> np.ndarray:
+        """Helper function for calculating all errors in the chain and summing
+        them. Returns the total error and stores sums of the random and
+        systematic errors in member variables. The individual error
+        contributions are not stored in this case for memory efficiency, only
+        the summed total, random and systematic error arrays are stored.
+
+        Parameters
+        ----------
+        truth : np.ndarray
+            Array of ground truth sensor measurements interpolated from the
+            simulated physical field. shape=(num_sensors,num_field_components,
+            num_time_steps).
+
+        Returns
+        -------
+        np.ndarray
+            Array of total errors summed over all errors in the chain. shape=(
+            num_sensors,num_field_components,num_time_steps).
+        """
+        self._errs_total = np.zeros_like(truth)
+        self._errs_systematic = np.zeros_like(truth)
+        self._errs_random = np.zeros_like(truth)
+
+        for ee in self._err_chain:
+
+            if ee.get_error_dep() == EErrDep.DEPENDENT:
+                (error_array,sens_data) = ee.sim_errs(
+                    truth+self._errs_total,
+                    self._sens_data_accumulated
+                )
+
+                # Only accumulate sensor data perturbations for dependent errors
+                self._sens_data_accumulated = copy.deepcopy(sens_data)
+            else:
+                (error_array,sens_data) = ee.sim_errs(truth,
+                                                       self._sens_data_initial)
+            
+
+            if ee.get_error_type() == EErrType.SYSTEMATIC:
+                self._errs_systematic = self._errs_systematic + error_array
+            else:
+                self._errs_random = self._errs_random + error_array
+
+            self._errs_total = self._errs_total + error_array
+
+        return self._errs_total
+
+
+    def get_errs_by_chain(self) -> np.ndarray | None:
+        """Gets the array of errors for each error in chain. If `store_all_errs`
+        is False in `ErrIntOpts` then this will return None.
+
+        Returns
+        -------
+        np.ndarray | None
+            Array of all errors in the chain. shape=(num_errs_in_chain,
+            num_sensors,num_field_components,num_time_steps). Returns None if
+            `ErrIntOpts.store_all_errs=False`.
+        """
+        return self._errs_by_chain
+
+    def get_sens_data_by_chain(self) -> list[SensorData] | None:
+        """Gets the list of sensor data objects storing how each error in the
+        chain has perturbed the underlying sensor parameters. If
+        `store_all_errs` is False in `ErrIntOpts` then this will return None.
+        If no sensor array parameters are modified by the error chain then all
+        SensorData objects in the list will be identical to the SensorData
+        object used to create the sensor array.
+
+        Returns
+        -------
+        list[SensorData] | None
+            List of perturbed sensors array parameters for each error in the
+            chain. Returns None if `ErrIntOpts.store_all_errs=False`.
+        """
+        return self._sens_data_by_chain
+
+    def get_sens_data_accumulated(self) -> SensorData:
+        """Gets the final accumulated sensor array parameters based on all
+        errors in the chain as a SensorData object. If no errors modify the
+        sensor array parameters then the SensorData object returns will be
+        identical to the SensorData object used to create the sensor array.
+
+        Returns
+        -------
+        SensorData
+            The final sensor array parameters based on accumulating all
+            perturbations from all errors in the error chain.
+        """
+        return self._sens_data_accumulated
+
+    def get_errs_systematic(self) -> np.ndarray:
+        """Gets the array of summed systematic errors over the error chain. If
+        the errors have not been calculated then an array of zeros is returned.
+
+        Returns
+        -------
+        np.ndarray
+            Array of total systematic errors. shape=(num_sensors,
+            num_field_components,num_time_steps)
+        """
+        return self._errs_systematic
+
+    def get_errs_random(self) -> np.ndarray:
+        """Gets the array of summed random errors over the error chain. If the
+        errors have not been calculated then an array of zeros is returned.
+
+        Returns
+        -------
+        np.ndarray
+            Array of total random errors. shape=(num_sensors,
+            num_field_components,num_time_steps)
+        """
+        return self._errs_random
+
+    def get_errs_total(self) -> np.ndarray:
+        """Gets the array of total errors. If the errors have not been
+        calculated then an array of zeros is returned. Note that this function
+        just returns the most recently calculated errors and will not resample
+        from probability distributions.
+
+        Returns
+        -------
+        np.ndarray
+            Array of total errors. shape=(num_sensors,num_field_components,
+            num_time_steps)
+        """
+        return self._errs_total
+
+

pyvale/sensorsim/errorrand.py

@@ -0,0 +1,105 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
+import numpy as np
+from pyvale.sensorsim.sensordata import SensorData
+from pyvale.sensorsim.errorsimulator import (IErrSimulator,
+                                         EErrType,
+                                         EErrDep)
+from pyvale.sensorsim.generatorsrandom import IGenRandom
+
+
+class ErrRandGen(IErrSimulator):
+    """Sensor random error calculator based on sampling a user specified random
+    number generator implementing the `IGeneratorRandom` interface.
+
+    Implements the `IErrSimulator` interface.
+    """
+    __slots__ = ("_generator","_err_dep")
+
+    def __init__(self,
+                 generator: IGenRandom,
+                 err_dep: EErrDep = EErrDep.INDEPENDENT) -> None:
+        """
+        Parameters
+        ----------
+        generator : IGeneratorRandom
+            Interface for a user specified random number generator.
+        err_dep : EErrDependence, optional
+            Error calculation dependence, by default EErrDependence.INDEPENDENT.
+        """
+        self._generator = generator
+        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.RANDOM
+
+    def reseed(self, seed: int | None = None) -> None:        
+        self._generator.reseed(seed)
+
+    def sim_errs(self,
+                  err_basis: np.ndarray,
+                  sens_data: SensorData,
+                  ) -> tuple[np.ndarray, SensorData]:
+        rand_errs = self._generator.generate(shape=err_basis.shape)
+
+        return (rand_errs,sens_data)
+
+
+class ErrRandGenPercent(IErrSimulator):
+    """Random error calculator based on sampling a user specified random
+    number generator implementing the `IGeneratorRandom` interface. This class
+    assumes the random generator is for a percentage error based on the input
+    error basis and therefore it supports error dependence.
+
+    The percentage error is calculated based on the ground truth if the error
+    dependence is `INDEPENDENT` or based on the accumulated sensor measurement
+    if the dependence is `DEPENDENT`.
+
+    Implements the `IErrSimulator` interface.
+    """
+    __slots__ = ("_generator","_err_dep")
+
+    def __init__(self,
+                 generator: IGenRandom,
+                 err_dep: EErrDep = EErrDep.INDEPENDENT) -> None:
+        """
+        Parameters
+        ----------
+        generator : IGeneratorRandom
+            Interface for a user specified random number generator.
+        err_dep : EErrDependence, optional
+            Error calculation dependence, by default EErrDependence.INDEPENDENT.
+        """
+        self._generator = generator
+        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.RANDOM
+
+    def reseed(self, seed: int | None = None) -> None:
+        self._generator.reseed(seed)
+
+    def sim_errs(self,
+                  err_basis: np.ndarray,
+                  sens_data: SensorData,
+                  ) -> tuple[np.ndarray, SensorData]:
+        rand_errs = err_basis \
+            * self._generator.generate(shape=err_basis.shape)/100.0
+
+        return (rand_errs,sens_data)