pyvale 2025.4.0__py3-none-any.whl → 2025.5.1__py3-none-any.whl

pyvale/errorsyscalib.py

@@ -0,0 +1,134 @@
+# ==============================================================================
+# 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.errorcalculator import (IErrCalculator,
+                                         EErrType,
+                                         EErrDep)
+from pyvale.sensordata import SensorData
+
+# TODO: add option to use Newton's method for function inversion instead of a
+# cal table.
+
+class ErrSysCalibration(IErrCalculator):
+    """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 `IErrCalculator` 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:
+        """Gets the error dependence state for this error calculator. An
+        independent error is calculated based on the input truth values as the
+        error basis. A dependent error is calculated based on the accumulated
+        sensor reading from all preceeding errors in the chain.
+
+        Returns
+        -------
+        EErrDependence
+            Enumeration defining INDEPENDENT or DEPENDENT behaviour.
+        """
+        return self._err_dep
+
+    def set_error_dep(self, dependence: EErrDep) -> None:
+        """Sets the error dependence state for this error calculator. An
+        independent error is calculated based on the input truth values as the
+        error basis. A dependent error is calculated based on the accumulated
+        sensor reading from all preceeding errors in the chain.
+
+        Parameters
+        ----------
+        dependence : EErrDependence
+            Enumeration defining INDEPENDENT or DEPENDENT behaviour.
+        """
+        self._err_dep = dependence
+
+    def get_error_type(self) -> EErrType:
+        """Gets the error type.
+
+        Returns
+        -------
+        EErrType
+            Enumeration definining RANDOM or SYSTEMATIC error types.
+        """
+        return EErrType.SYSTEMATIC
+
+    def calc_errs(self,
+                  err_basis: np.ndarray,
+                  sens_data: SensorData,
+                  ) -> tuple[np.ndarray, SensorData]:
+        """Calculates the error array based on the size of the input.
+
+        Parameters
+        ----------
+        err_basis : np.ndarray
+            Array of values with the same dimensions as the sensor measurement
+            matrix.
+        sens_data : SensorData
+            The accumulated sensor state data for all errors prior to this one.
+
+        Returns
+        -------
+        tuple[np.ndarray, SensorData]
+            Tuple containing the calculated error array and pass through of the
+            sensor data object as it is not modified by this class. The returned
+            error array has the same shape as the input error basis.
+        """
+        # 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/{core/errorsysdep.py → errorsysdep.py}

@@ -1,17 +1,16 @@
-"""
-================================================================================
-pyvale: the python validation engine
-License: MIT
-Copyright (C) 2025 The Computer Aided Validation Team
-================================================================================
-"""
+# ==============================================================================
+# 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.core.sensordata import SensorData
-from pyvale.core.errorcalculator import (IErrCalculator,
+from pyvale.sensordata import SensorData
+from pyvale.errorcalculator import (IErrCalculator,
                                          EErrType,
-                                         EErrDependence)
+                                         EErrDep)
 
 
 class ERoundMethod(enum.Enum):
@@ -54,9 +53,8 @@ class ErrSysRoundOff(IErrCalculator):
     def __init__(self,
                  method: ERoundMethod = ERoundMethod.ROUND,
                  base: float = 1.0,
-                 err_dep: EErrDependence = EErrDependence.DEPENDENT) -> None:
-        """Initialiser for the `ErrSysRoundOff` class.
-
+                 err_dep: EErrDep = EErrDep.DEPENDENT) -> None:
+        """
         Parameters
         ----------
         method : ERoundMethod, optional
@@ -71,7 +69,7 @@ class ErrSysRoundOff(IErrCalculator):
         self._method = _select_round_method(method)
         self._err_dep = err_dep
 
-    def get_error_dep(self) -> EErrDependence:
+    def get_error_dep(self) -> EErrDep:
         """Gets the error dependence state for this error calculator. An
         independent error is calculated based on the input truth values as the
         error basis. A dependent error is calculated based on the accumulated
@@ -84,7 +82,7 @@ class ErrSysRoundOff(IErrCalculator):
         """
         return self._err_dep
 
-    def set_error_dep(self, dependence: EErrDependence) -> None:
+    def set_error_dep(self, dependence: EErrDep) -> None:
         """Sets the error dependence state for this error calculator. An
         independent error is calculated based on the input truth values as the
         error basis. A dependent error is calculated based on the accumulated
@@ -143,9 +141,8 @@ class ErrSysDigitisation(IErrCalculator):
     def __init__(self,
                  bits_per_unit: float,
                  method: ERoundMethod = ERoundMethod.ROUND,
-                 err_dep: EErrDependence = EErrDependence.DEPENDENT) -> None:
-        """Initialiser for the `ErrSysDigitisation` class.
-
+                 err_dep: EErrDep = EErrDep.DEPENDENT) -> None:
+        """
         Parameters
         ----------
         bits_per_unit : float
@@ -160,7 +157,7 @@ class ErrSysDigitisation(IErrCalculator):
         self._method = _select_round_method(method)
         self._err_dep = err_dep
 
-    def get_error_dep(self) -> EErrDependence:
+    def get_error_dep(self) -> EErrDep:
         """Gets the error dependence state for this error calculator. An
         independent error is calculated based on the input truth values as the
         error basis. A dependent error is calculated based on the accumulated
@@ -173,7 +170,7 @@ class ErrSysDigitisation(IErrCalculator):
         """
         return self._err_dep
 
-    def set_error_dep(self, dependence: EErrDependence) -> None:
+    def set_error_dep(self, dependence: EErrDep) -> None:
         """Sets the error dependence state for this error calculator. An
         independent error is calculated based on the input truth values as the
         error basis. A dependent error is calculated based on the accumulated
@@ -227,18 +224,17 @@ class ErrSysSaturation(IErrCalculator):
     """Systematic error calculator for saturation error base on user specified
     minimum and maximum measurement values. Implements the `IErrCalculator`
     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:
-        """Initialiser for the `ErrSysSaturation` class.
-
-        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.
-
+        """
         Parameters
         ----------
         meas_min : float
@@ -258,9 +254,9 @@ class ErrSysSaturation(IErrCalculator):
 
         self._min = meas_min
         self._max = meas_max
-        self._err_dep = EErrDependence.DEPENDENT
+        self._err_dep = EErrDep.DEPENDENT
 
-    def get_error_dep(self) -> EErrDependence:
+    def get_error_dep(self) -> EErrDep:
         """Gets the error dependence state for this error calculator. An
         independent error is calculated based on the input truth values as the
         error basis. A dependent error is calculated based on the accumulated
@@ -273,7 +269,7 @@ class ErrSysSaturation(IErrCalculator):
         """
         return self._err_dep
 
-    def set_error_dep(self, dependence: EErrDependence) -> None:
+    def set_error_dep(self, dependence: EErrDep) -> None:
         """Sets the error dependence state for this error calculator. An
         independent error is calculated based on the input truth values as the
         error basis. A dependent error is calculated based on the accumulated

pyvale/{core/errorsysfield.py → errorsysfield.py}

@@ -1,24 +1,30 @@
-"""
-================================================================================
-pyvale: the python validation engine
-License: MIT
-Copyright (C) 2025 The Computer Aided Validation Team
-================================================================================
-"""
+# ==============================================================================
+# 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 scipy.spatial.transform import Rotation
 
-from pyvale.core.field import IField
-from pyvale.core.fieldsampler import sample_field_with_sensor_data
-from pyvale.core.sensordata import SensorData
-from pyvale.core.integratortype import EIntSpatialType
-from pyvale.core.errorcalculator import (IErrCalculator,
+from pyvale.field import IField
+from pyvale.fieldsampler import sample_field_with_sensor_data
+from pyvale.sensordata import SensorData
+from pyvale.integratortype import EIntSpatialType
+from pyvale.errorcalculator import (IErrCalculator,
                                     EErrType,
-                                    EErrDependence)
-from pyvale.core.errordriftcalc import IDriftCalculator
-from pyvale.core.generatorsrandom import IGeneratorRandom
+                                    EErrDep)
+from pyvale.errordriftcalc import IDriftCalculator
+from pyvale.generatorsrandom import IGenRandom
+
+# TODO:
+# - Implement different perturbed sampling times for each sensor or allow all
+#   to lock to the same time step as it works now.
+# - Need to check that we perform field rotations correctly for sensor angles.
+#   - This needs to be updated to take rotation objects for offsets and to build
+#     and compose rotations
 
 
 @dataclass(slots=True)
@@ -46,25 +52,26 @@ class ErrFieldData:
     num_time_steps,). If None then no time offset is applied.
     """
 
-    pos_rand_xyz: tuple[IGeneratorRandom | None,
-                        IGeneratorRandom | None,
-                        IGeneratorRandom | None] = (None,None,None)
-    """Tuple of random generators (implementations of `IGeneratorRandom`
+    pos_rand_xyz: tuple[IGenRandom | None,
+                        IGenRandom | None,
+                        IGenRandom | None] = (None,None,None)
+    """Tuple of random generators (implementations of `IGenRandom`
     interface) for perturbing the sensor positions. The generators perturb the
     X, Y and Z coordinates in order. If None then that axis is not randomly
-    perturbed from the nominal sensor position.
+    perturbed from the nominal sensor position. Note that the random generators
+    should return position perturbations consistent with the simulation units.
     """
 
-    ang_rand_zyx: tuple[IGeneratorRandom | None,
-                        IGeneratorRandom | None,
-                        IGeneratorRandom | None] = (None,None,None)
-    """Tuple of random generators (implementations of `IGeneratorRandom`
+    ang_rand_zyx: tuple[IGenRandom | None,
+                        IGenRandom | None,
+                        IGenRandom | None] = (None,None,None)
+    """Tuple of random generators (implementations of `IGenRandom`
     interface) for perturbing the sensor angles. The generators perturb
     rotations about the the Z, Y and X axis  in order. If None then that axis is
     not randomly perturbed from the nominal sensor position.
     """
 
-    time_rand: IGeneratorRandom | None = None
+    time_rand: IGenRandom | None = None
     """Random generator for perturbing sensor array sampling times for the
     purpose of calculating field based errors. If None then sensor sampling
     times will not be perturbed from the nominal times.
@@ -82,11 +89,13 @@ class ErrFieldData:
     specified above. shape=(3,)
     """
 
-    # DEV FEATURE: locks the coordinate even if offsets and random generators are specified
+    # DEV FEATURE: locks the coordinate even if offsets and random generators
+    # are specified. These allow individual sensors to be locked when we only
+    # specify a random generator for each axis not each sensor.
     pos_lock_xyz: np.ndarray | None = None
     ang_lock_zyx: np.ndarray | None = None
 
-    #TODO: implement drift for other dimensions, pos/angle
+    # TODO: implement drift for other dimensions, pos/angle
     time_drift: IDriftCalculator | None = None
     """Temporal drift calculation
     """
@@ -108,9 +117,8 @@ class ErrSysField(IErrCalculator):
     def __init__(self,
                 field: IField,
                 field_err_data: ErrFieldData,
-                err_dep: EErrDependence = EErrDependence.INDEPENDENT) -> None:
-        """Initialiser for the `ErrSysField` class.
-
+                err_dep: EErrDep = EErrDep.INDEPENDENT) -> None:
+        """
         Parameters
         ----------
         field : IField
@@ -121,15 +129,15 @@ class ErrSysField(IErrCalculator):
             Dataclass specifying which sensor array parameters will be perturbed
             and how they will be perturbed. See the `ErrFieldData` class for
             more detail
-        err_dep : EErrDependence, optional
-            Error calculation dependence, by default EErrDependence.INDEPENDENT.
+        err_dep : EErrDep, optional
+            Error calculation dependence, by default EErrDep.DEPENDENT.
         """
         self._field = field
         self._field_err_data = field_err_data
         self._err_dep = err_dep
         self._sensor_data_perturbed = SensorData()
 
-    def get_error_dep(self) -> EErrDependence:
+    def get_error_dep(self) -> EErrDep:
         """Gets the error dependence state for this error calculator. An
         independent error is calculated based on the input truth values as the
         error basis. A dependent error is calculated based on the accumulated
@@ -137,12 +145,12 @@ class ErrSysField(IErrCalculator):
 
         Returns
         -------
-        EErrDependence
+        EErrDep
             Enumeration defining INDEPENDENT or DEPENDENT behaviour.
         """
         return self._err_dep
 
-    def set_error_dep(self, dependence: EErrDependence) -> None:
+    def set_error_dep(self, dependence: EErrDep) -> None:
         """Sets the error dependence state for this error calculator. An
         independent error is calculated based on the input truth values as the
         error basis. A dependent error is calculated based on the accumulated
@@ -150,7 +158,7 @@ class ErrSysField(IErrCalculator):
 
         Parameters
         ----------
-        dependence : EErrDependence
+        dependence : EErrDep
             Enumeration defining INDEPENDENT or DEPENDENT behaviour.
         """
         self._err_dep = dependence
@@ -232,9 +240,9 @@ class ErrSysField(IErrCalculator):
 
 def _perturb_sensor_positions(sens_pos_nominal: np.ndarray,
                              pos_offset_xyz: np.ndarray | None,
-                             pos_rand_xyz: tuple[IGeneratorRandom | None,
-                                                 IGeneratorRandom | None,
-                                                 IGeneratorRandom | None] | None,
+                             pos_rand_xyz: tuple[IGenRandom | None,
+                                                 IGenRandom | None,
+                                                 IGenRandom | None] | None,
                              pos_loc_xyz: np.ndarray | None,
                             ) -> np.ndarray:
     """Helper function for perturbing the sensor positions from their nominal
@@ -250,9 +258,9 @@ def _perturb_sensor_positions(sens_pos_nominal: np.ndarray,
         Offsets to apply to the sensor positions as an array with shape=
         (num_sensors,3) wherethe columns represent the position in the X, Y and
         Z axes. If None then no offset is applied.
-    pos_rand_xyz : tuple[IGeneratorRandom  |  None,
-                         IGeneratorRandom  |  None,
-                         IGeneratorRandom  |  None] | None
+    pos_rand_xyz : tuple[IGenRandom  |  None,
+                         IGenRandom  |  None,
+                         IGenRandom  |  None] | None
         Random generators for sensor position perturbations along the the X, Y
         and Z axes. If None then no perturbation is applied.
     pos_loc_xyz : np.ndarray | None
@@ -285,7 +293,7 @@ def _perturb_sensor_positions(sens_pos_nominal: np.ndarray,
 def _perturb_sample_times(sim_time: np.ndarray,
                          time_nominal: np.ndarray | None,
                          time_offset: np.ndarray | None,
-                         time_rand: IGeneratorRandom | None,
+                         time_rand: IGenRandom | None,
                          time_drift: IDriftCalculator | None
                          ) -> np.ndarray | None:
     """Helper function for calculating perturbed sensor sampling times for the
@@ -301,7 +309,7 @@ def _perturb_sample_times(sim_time: np.ndarray,
     time_offset : np.ndarray | None
         Array of time offsets to apply to all sensors. If None then no offsets
         are applied.
-    time_rand : IGeneratorRandom | None
+    time_rand : IGenRandom | None
         Random generator for perturbing the sampling times of all sensors. If
         None then no random perturbation of sampling times occurs.
     time_drift : IDriftCalculator | None
@@ -337,9 +345,9 @@ def _perturb_sample_times(sim_time: np.ndarray,
 def _perturb_sensor_angles(n_sensors: int,
                           angles_nominal: tuple[Rotation,...] | None,
                           angle_offsets_zyx: np.ndarray | None,
-                          rand_ang_zyx: tuple[IGeneratorRandom | None,
-                                              IGeneratorRandom | None,
-                                              IGeneratorRandom | None] | None,
+                          rand_ang_zyx: tuple[IGenRandom | None,
+                                              IGenRandom | None,
+                                              IGenRandom | None] | None,
                           angle_loc_zyx: np.ndarray | None,
                           ) -> tuple[Rotation,...] | None:
     """Helper function for perturbing sensor angles for the purpose of
@@ -357,9 +365,9 @@ def _perturb_sensor_angles(n_sensors: int,
         Angle offsets to apply to the sensor array as an array with shape=(
         num_sensors,3) where the columns are the rotations about Z, Y and X in
         degrees. If None then no offsets are applied.
-    rand_ang_zyx : tuple[IGeneratorRandom  |  None,
-                         IGeneratorRandom  |  None,
-                         IGeneratorRandom  |  None] | None
+    rand_ang_zyx : tuple[IGenRandom  |  None,
+                         IGenRandom  |  None,
+                         IGenRandom  |  None] | None
         Random generators for perturbing sensor angles about the Z, Y and X axis
         respectively. If None then no random perturbation to the sensor angle
         occurs.
@@ -403,5 +411,4 @@ def _perturb_sensor_angles(n_sensors: int,
         sensor_rot = Rotation.from_euler("zyx",sensor_rot_angs, degrees=True)
         angles_perturbed[ii] = sensor_rot*rot_nom
 
-    return tuple(angles_perturbed)
-
+    return tuple(angles_perturbed)