pyvale 2025.4.1__py3-none-any.whl → 2025.5.2__py3-none-any.whl

pyvale/errorsysindep.py

@@ -1,15 +1,14 @@
-# ================================================================================
+# ==============================================================================
 # 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,
-                                         EErrDependence)
-from pyvale.generatorsrandom import IGeneratorRandom
+                                         EErrDep)
+from pyvale.generatorsrandom import IGenRandom
 from pyvale.sensordata import SensorData
 
 
@@ -21,21 +20,20 @@ class ErrSysOffset(IErrCalculator):
 
     def __init__(self,
                  offset: float,
-                 err_dep: EErrDependence = EErrDependence.INDEPENDENT) -> None:
-        """Initialiser for the `ErrSysOffset` class.
-
+                 err_dep: EErrDep = EErrDep.INDEPENDENT) -> None:
+        """
         Parameters
         ----------
         offset : float
             Constant offset to apply to all simulated measurements from the
             sensor array.
         err_dep : EErrDependence, optional
-            Error , by default EErrDependence.INDEPENDENT
+            Error calculation dependence, by default EErrDependence.INDEPENDENT.
         """
         self._offset = offset
         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
@@ -51,7 +49,7 @@ class ErrSysOffset(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
@@ -110,9 +108,8 @@ class ErrSysOffsetPercent(IErrCalculator):
 
     def __init__(self,
                  offset_percent: float,
-                 err_dep: EErrDependence = EErrDependence.INDEPENDENT) -> None:
-        """Initialiser for the `ErrSysOffsetPercent` class.
-
+                 err_dep: EErrDep = EErrDep.INDEPENDENT) -> None:
+        """
         Parameters
         ----------
         offset_percent : float
@@ -124,7 +121,7 @@ class ErrSysOffsetPercent(IErrCalculator):
         self._offset_percent = offset_percent
         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
@@ -137,7 +134,7 @@ class ErrSysOffsetPercent(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
@@ -187,7 +184,7 @@ class ErrSysOffsetPercent(IErrCalculator):
                 sens_data)
 
 
-class ErrSysUniform(IErrCalculator):
+class ErrSysUnif(IErrCalculator):
     """Systematic error calculator for applying an offset to each sensor that is
     sampled from a uniform probability distribution specified by its upper and
     lower bounds. Implements the `IErrCalculator` interface.
@@ -197,10 +194,9 @@ class ErrSysUniform(IErrCalculator):
     def __init__(self,
                  low: float,
                  high: float,
-                 err_dep: EErrDependence = EErrDependence.INDEPENDENT,
+                 err_dep: EErrDep = EErrDep.INDEPENDENT,
                  seed: int | None = None) -> None:
-        """Initialiser for the `ErrSysUniform` class.
-
+        """
         Parameters
         ----------
         low : float
@@ -220,7 +216,7 @@ class ErrSysUniform(IErrCalculator):
         self._rng = np.random.default_rng(seed)
         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
@@ -236,7 +232,7 @@ class ErrSysUniform(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
@@ -296,7 +292,7 @@ class ErrSysUniform(IErrCalculator):
         return (sys_errs,sens_data)
 
 
-class ErrSysUniformPercent(IErrCalculator):
+class ErrSysUnifPercent(IErrCalculator):
     """Systematic error calculator for applying a percentage offset to each
     sensor that is sampled from a uniform probability distribution specified by
     its upper and lower bounds.
@@ -312,10 +308,9 @@ class ErrSysUniformPercent(IErrCalculator):
     def __init__(self,
                  low_percent: float,
                  high_percent: float,
-                 err_dep: EErrDependence = EErrDependence.INDEPENDENT,
+                 err_dep: EErrDep = EErrDep.INDEPENDENT,
                  seed: int | None = None) -> None:
-        """_summary_
-
+        """
         Parameters
         ----------
         low_percent : float
@@ -333,7 +328,7 @@ class ErrSysUniformPercent(IErrCalculator):
         self._rng = np.random.default_rng(seed)
         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
@@ -346,7 +341,7 @@ class ErrSysUniformPercent(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
@@ -403,7 +398,7 @@ class ErrSysUniformPercent(IErrCalculator):
         return (err_basis*sys_errs,sens_data)
 
 
-class ErrSysNormal(IErrCalculator):
+class ErrSysNorm(IErrCalculator):
     """Systematic error calculator for applying an offset to each individual
     sensor in the array based on sampling from a normal distribution specified
     by its standard deviation and mean. Note that the offset is constant for
@@ -414,10 +409,9 @@ class ErrSysNormal(IErrCalculator):
     def __init__(self,
                  std: float,
                  mean: float = 0.0,
-                 err_dep: EErrDependence = EErrDependence.INDEPENDENT,
+                 err_dep: EErrDep = EErrDep.INDEPENDENT,
                  seed: int | None = None) -> None:
-        """Initialiser for the `ErrSysNormal` class.
-
+        """
         Parameters
         ----------
         std : float
@@ -435,7 +429,7 @@ class ErrSysNormal(IErrCalculator):
         self._rng = np.random.default_rng(seed)
         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
@@ -451,7 +445,7 @@ class ErrSysNormal(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
@@ -527,13 +521,24 @@ class ErrSysNormPercent(IErrCalculator):
 
     def __init__(self,
                  std_percent: float,
-                 err_dep: EErrDependence = EErrDependence.INDEPENDENT,
+                 err_dep: EErrDep = EErrDep.INDEPENDENT,
                  seed: int | None = None) -> None:
+        """
+        Parameters
+        ----------
+        std_percent : float
+            Standard deviation as a percentage in the range (0,100).
+        err_dep : EErrDependence, optional
+            Error calculation dependence, by default EErrDependence.INDEPENDENT.
+        seed : int | None, optional
+            Optional seed for the random generator to allow for replicable
+            behaviour, by default None.
+        """
         self._std = std_percent/100
         self._rng = np.random.default_rng(seed)
         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
@@ -546,7 +551,7 @@ class ErrSysNormPercent(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
@@ -573,12 +578,6 @@ class ErrSysNormPercent(IErrCalculator):
                   err_basis: np.ndarray,
                   sens_data: SensorData,
                   ) -> tuple[np.ndarray, SensorData]:
-
-        err_shape = np.array(err_basis.shape)
-        err_shape[-1] = 1
-        sys_errs = self._rng.normal(loc=0.0,
-                                    scale=self._std,
-                                    size=err_shape)
         """Calculates the error array based on the size of the input.
 
         Parameters
@@ -596,6 +595,13 @@ class ErrSysNormPercent(IErrCalculator):
             sensor data object as it is not modified by this class. The returned
             error array has the same shape as the input error basis.
         """
+
+        err_shape = np.array(err_basis.shape)
+        err_shape[-1] = 1
+        sys_errs = self._rng.normal(loc=0.0,
+                                    scale=self._std,
+                                    size=err_shape)
+
         tile_shape = np.array(err_basis.shape)
         tile_shape[0:-1] = 1
         sys_errs = np.tile(sys_errs,tuple(tile_shape))
@@ -603,7 +609,7 @@ class ErrSysNormPercent(IErrCalculator):
         return (err_basis*sys_errs,sens_data)
 
 
-class ErrSysGenerator(IErrCalculator):
+class ErrSysGen(IErrCalculator):
     """Systematic error calculator for applying a unique offset to each sensor
     by sample from a user specified probability distribution (an implementation
     of the `IGeneratorRandom` interface).
@@ -613,13 +619,21 @@ class ErrSysGenerator(IErrCalculator):
     __slots__ = ("_generator","_err_dep")
 
     def __init__(self,
-                 generator: IGeneratorRandom,
-                 err_dep: EErrDependence = EErrDependence.INDEPENDENT) -> None:
-
+                 generator: IGenRandom,
+                 err_dep: EErrDep = EErrDep.INDEPENDENT) -> None:
+        """
+        Parameters
+        ----------
+        generator : IGenRandom
+            Random generator object used to calculate the systematic error in
+            simulation units.
+        err_dep : EErrDependence, optional
+            Error calculation dependence, by default EErrDependence.INDEPENDENT.
+        """
         self._generator = generator
         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
@@ -632,7 +646,7 @@ class ErrSysGenerator(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
@@ -704,13 +718,21 @@ class ErrSysGenPercent(IErrCalculator):
     __slots__ = ("_generator","_err_dep")
 
     def __init__(self,
-                 generator: IGeneratorRandom,
-                 err_dep: EErrDependence = EErrDependence.INDEPENDENT) -> None:
-
+                 generator: IGenRandom,
+                 err_dep: EErrDep = EErrDep.INDEPENDENT) -> None:
+        """
+        Parameters
+        ----------
+        generator : IGenRandom
+            Random generator which returns a percentage error in the range
+            (0,100)
+        err_dep : EErrDep, optional
+            Error calculation dependence, by default EErrDep.INDEPENDENT
+        """
         self._generator = generator
         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
@@ -723,7 +745,7 @@ class ErrSysGenPercent(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
@@ -770,7 +792,9 @@ class ErrSysGenPercent(IErrCalculator):
         err_shape = np.array(err_basis.shape)
         err_shape[-1] = 1
 
-        sys_errs = self._generator.generate(size=err_shape)
+        sys_errs = self._generator.generate(shape=err_shape)
+        # Convert percent to decimal
+        sys_errs = sys_errs/100.0
 
         tile_shape = np.array(err_basis.shape)
         tile_shape[0:-1] = 1
@@ -780,125 +804,5 @@ class ErrSysGenPercent(IErrCalculator):
         return (sys_errs,sens_data)
 
 
-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: EErrDependence = EErrDependence.INDEPENDENT) -> None:
-        """_summary_
-
-        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) -> EErrDependence:
-        """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: EErrDependence) -> 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/examples/basics/ex1_1_basicscalars_therm2d.py

@@ -0,0 +1,131 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
+"""
+Pyvale example: Basics of pyvale point sensor simualtion
+--------------------------------------------------------------------------------
+In this example we introduce the basic features of pyvale for point sensor
+simulation. We demonstrate quick sensor array construction with defaults using
+the pyvale sensor array factory. Finally we run a sensor simulation and display
+the output.
+
+Test case: Scalar field point sensors (thermocouples) on a 2D thermal simulation
+"""
+
+from pathlib import Path
+import matplotlib.pyplot as plt
+import mooseherder as mh
+import pyvale as pyv
+
+
+def main() -> None:
+
+    # Here we load a pre-generated MOOSE finite element simulation dataset that
+    # comes packaged with pyvale. The simulation is a 2D rectangular plate with
+    # a bi-directional temperature gradient. You can replace this with the path
+    # to your own MOOSE simulation with exodus output (*.e). Note that the
+    # field_key must match the name of your variable in your MOOSE simulation.
+    data_path = pyv.DataSet.thermal_2d_path()
+    # We use `mooseherder` to load the exodus file into a `SimData` object.
+    sim_data = mh.ExodusReader(data_path).read_all_sim_data()
+
+    # Scale to mm to make 3D visualisation scaling easier as pyvista scales
+    # everything to unity
+    sim_data = pyv.scale_length_units(scale=1000.0,
+                                      sim_data=sim_data,
+                                      disp_comps=None)
+
+    # We now use a helper function to create a grid of sensor locations but we
+    # could have also manually built the numpy array of sensor locations which
+    # has the shape=(num_sensors,coord[x,y,z]).
+    n_sens = (3,2,1)
+    x_lims = (0.0,100.0)
+    y_lims = (0.0,50.0)
+    z_lims = (0.0,0.0)
+    sens_pos = pyv.create_sensor_pos_array(n_sens,x_lims,y_lims,z_lims)
+
+    # This dataclass contains the parameters to build our sensor array. We can
+    # also customise the output frequency, the sensor area and the sensor
+    # orientation. For now we will use the defaults which assumes an ideal point
+    # sensor sampling at the simulation time steps.
+    sens_data = pyv.SensorData(positions=sens_pos)
+
+    # Now that we have our sensor locations we can use the sensor factory to
+    # build a basic thermocouple array with some useful defaults. In later
+    # examples we will see how to customise sensor parameters and errors.
+    # This basic thermocouple array includes a 1% systematic and random error.
+    # If you want to remove the simulated errors and just interpolate at the
+    # sensor locations then user `.thermocouples_no_errs()`.
+    field_key: str = "temperature"
+    tc_array = pyv.SensorArrayFactory \
+        .thermocouples_basic_errs(sim_data,
+                                  sens_data,
+                                  elem_dims=2,
+                                  field_name=field_key)
+
+    # We have built our sensor array so now we can call `calc_measurements()` to
+    # generate simulated sensor traces.
+    measurements = tc_array.calc_measurements()
+    print(f"\nMeasurements for last sensor:\n{measurements[-1,0,:]}\n")
+
+    # We can now visualise the sensor locations on the simulation mesh and the
+    # simulated sensor traces using pyvale's visualisation tools which use
+    # pyvista for meshes and matplotlib for sensor traces. pyvale will return
+    # plot and axes objects to the user allowing additional customisation using
+    # pyvista and matplotlib. This also means that we need to call `.show()`
+    # ourselves to display the figure as pyvale does not do this for us.
+
+    # If we are going to save figures we need to make sure the path exists. Here
+    # we create a default output path based on your current working directory.
+    output_path = Path.cwd() / "pyvale-output"
+    if not output_path.is_dir():
+        output_path.mkdir(parents=True, exist_ok=True)
+
+    # This creates a pyvista visualisation of the sensor locations on the
+    # simulation mesh. The plot will can be shown in interactive mode by calling
+    # `pv_plot.show()` alternatively
+    pv_plot = pyv.plot_point_sensors_on_sim(tc_array,field_key)
+
+    # We determined manually by moving camera in interative mode and then
+    # printing camera position to console after window close, as below.
+    pv_plot.camera_position = [(-7.547, 59.753, 134.52),
+                                (41.916, 25.303, 9.297),
+                                (0.0810, 0.969, -0.234)]
+
+
+    # This allows us to save a vector graphic and raster graphic showing the
+    # sensor locations on the simulation mesh
+    save_render = output_path / "basics_ex1_1_sensorlocs.svg"
+    pv_plot.save_graphic(save_render) # only for .svg .eps .ps .pdf .tex
+    pv_plot.screenshot(save_render.with_suffix(".png"))
+
+    # We can also show the simulation and sensor locations in interative mode
+    # by calling `.show()`
+    pv_plot.show()
+
+    print(80*"-")
+    print("Camera position after interative view:")
+    print(pv_plot.camera_position)
+    print(80*"-"+"\n")
+
+    # This plots the time traces for all of our sensors. The solid line shows
+    # the 'truth' interpolated from the simulation and the dashed line with
+    # markers shows the simulated sensor traces. In later examples we will see
+    # how to configure this plot but for now we note we that we are returned a
+    # matplotlib figure and axes object which allows for further customisation.
+    (fig,ax) = pyv.plot_time_traces(tc_array,field_key)
+
+    # We can also save the sensor trace plot as a vector and raster graphic
+    save_traces = output_path/"basics_ex1_1_sensortraces.png"
+    fig.savefig(save_traces, dpi=300, bbox_inches="tight")
+    fig.savefig(save_traces.with_suffix(".svg"), dpi=300, bbox_inches="tight")
+
+    # The trace plot can also be shown in interactive mode using `plt.show()`
+    plt.show()
+
+
+if __name__ == "__main__":
+    main()