pyvale 2026.1.1__cp311-cp311-manylinux_2_17_i686.manylinux2014_i686.whl

pyvale/sensorsim/sensorspoint.py

@@ -0,0 +1,308 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
+import numpy as np
+from pyvale.sensorsim.field import IField
+from pyvale.sensorsim.sensorarray import ISensorArray
+from pyvale.sensorsim.errorintegrator import (ErrIntegrator,
+                                              ErrIntOpts)
+from pyvale.sensorsim.errorsimulator import IErrSimulator
+from pyvale.sensorsim.sensordescriptor import SensorDescriptor
+from pyvale.sensorsim.sensordata import SensorData
+from pyvale.sensorsim.fieldsampler import sample_field_with_sensor_data
+
+
+class SensorsPoint(ISensorArray):
+    """A class for creating arrays of point sensors applied to a simulated
+    physical field. Examples include: thermocouples used to measure temperature
+    (a scalar field) or strain gauges used to measure strain (a tensor field).
+    Implements the ISensorArray interface.
+
+    This class uses the `pyvale` sensor measurement simulation model. Here a
+    measurement is taken as: measurement = truth + random errors + systematic
+    errors. The truth value for each sensor is interpolated from the physical
+    field (an implementation of the `IField` interface, nominally a
+    `FieldScalar`, `FieldVector` or `FieldTensor` object).
+
+    The random and systematic errors are calculated by a user specified error
+    integrator (`ErrIntegrator` class). This class contains a chain of different
+    types of user selected errors (implementations of the `IErrSimulator`
+    interface). Further information can be found in the `ErrIntegrator` class
+    and in implementations of the `IErrSimulator` interface.
+
+    In `pyvale`, function and methods with `sim` or `calc` in their name will 
+    cause probability distributions to be resampled and any additional 
+    calculations, such as interpolation, to be performed. Functions and methods 
+    with `get` in the name will directly return the previously calculated values 
+    without any computationally intensive calculations.
+
+    Calling the class method `sim_measurements()` will create and return an
+    array of simulated sensor measurements with the following shape=(num_sensors
+    ,num_field_component,num_time_steps). When calling `sim_measurements()` all
+    sensor errors that are based on probability distributions are resampled and
+    any required interpolations are performed (e.g. a random perturbation of the
+    sensor positions requiring interpolation at the perturbed sensor location).
+
+    Calling the class method `get_measurements()` just returns the previously
+    calculated set of sensor measurements without resampling of probability.
+    Distributions.
+
+    Without an error integrator this class can be used for interpolating
+    simulated physical fields quickly using finite element shape functions or 
+    mesh-free linear interpolation based on Delaunay triangulation.
+    """
+
+    __slots__ = ("_field","_descriptor","_sensor_data","_truth","_measurements",
+                 "_error_integrator")
+
+    def __init__(self,
+                 sensor_data: SensorData,
+                 field: IField,
+                 descriptor: SensorDescriptor | None = None,
+                 ) -> None:
+        """
+        Parameters
+        ----------
+        sensor_data : SensorData
+            Specifies sensor array parameters including: positions, sample times
+            , angles, and area averaging. See the `SensorData` dataclass for
+            details.
+        field : IField
+            The simulated physical field that the sensors will samples from.
+            This is normally a `FieldScalar`, `FieldVector` or `FieldTensor`.
+        descriptor : SensorDescriptor | None, optional
+            Contains descriptive information about the sensor array for display
+            and visualisations, by default None.
+        """
+        self._sensor_data = sensor_data
+        self._field = field
+        self._error_integrator = None
+
+        self._descriptor = SensorDescriptor()
+        if descriptor is not None:
+            self._descriptor = descriptor
+
+        self._truth = None
+        self._measurements = None
+
+    def get_descriptor(self) -> SensorDescriptor:
+        """Gets the sensor descriptor data class which contains a series of
+        strings used to describe the sensor array.
+
+        Returns
+        -------
+        SensorDescriptor
+            Data class containing strings used to describe the sensor array for
+            visualisations and plots.
+        """
+        return self._descriptor
+
+    def get_sample_times(self) -> np.ndarray:
+        """Gets the times at which the sensors sample the given physical field.
+        This is specified by the user in the SensorData object or defaults to
+        the time steps in the underlying simulation if unspecified.
+
+        Returns
+        -------
+        np.ndarray
+            Sample times with shape: (num_time_steps,)
+        """
+        if self._sensor_data.sample_times is None:
+            return self._field.get_time_steps()
+
+        return self._sensor_data.sample_times
+
+    def get_measurement_shape(self) -> tuple[int,int,int]:
+        """Gets the shape of the sensor measurement array. shape=(num_sensors,
+        num_field_components,num_time_steps)
+
+        Returns
+        -------
+        tuple[int,int,int]
+            Shape of the measurement array. shape=(num_sensors,
+            num_field_components,num_time_steps)
+        """
+
+        return (self._sensor_data.positions.shape[0],
+                len(self._field.get_all_components()),
+                self.get_sample_times().shape[0])
+
+    def get_field(self) -> IField:
+        """Gets a reference to the physical field that this sensor array
+        is applied to.
+
+        Returns
+        -------
+        IField
+            Reference to an `IField` interface.
+        """
+        return self._field
+
+
+    def calc_truth(self) -> np.ndarray:
+        """Calculates the ground truth sensor values by interpolating the
+        simulated physical field using the sensor array parameters in the
+        `SensorData` object.
+
+        Returns
+        -------
+        np.ndarray
+            Array of ground truth sensor values. shape=(num_sensors,
+            num_field_components,num_time_steps).
+        """
+        self._truth = sample_field_with_sensor_data(self._field,
+                                                    self._sensor_data)
+
+        return self._truth
+
+    def get_truth(self) -> np.ndarray:
+        """Gets the ground truth sensor values that were calculated previously.
+        If the ground truth values have not been calculated then
+        `calc_truth()` is called first.
+
+        Returns
+        -------
+        np.ndarray
+            Array of ground truth sensor values. shape=(num_sensors,
+            num_field_components,num_time_steps).
+        """
+        if self._truth is None:
+            self._truth = self.calc_truth()
+
+        return self._truth
+
+    def get_error_integrator(self) -> ErrIntegrator:
+        """Gets the error integrator allowing the user to interpret error
+        sources in the error chain and to separate random and systematic error
+        contributions.
+
+        Returns
+        -------
+        ErrIntegrator | None
+            The error integrator.
+        """
+        return self._error_integrator
+
+
+    def set_error_chain(self,
+                        err_chain: list[IErrSimulator] | None,
+                        err_int_opts: ErrIntOpts | None = None) -> None:
+        """Sets the error chain that will be used to calculate the sensor
+        array measurement errors when `sim_measurements()` is called. See the
+        `ErrIntegrator` class for further details as to how errors are 
+        calculated.
+
+        Parameters
+        ----------
+        err_chain : list[IErrSimulator] | None
+            Chain of user defined errors that will be evaluated in order as part
+            of the sensor simulation. Set to None to remove error calculation
+            and perform direct interpolation of the simulation to the virtual
+            sensor locations.
+        err_int_opts : ErrIntOpts | None, optional
+            Sets the options of virtual sensor error integration, by default
+            None. If None default options are used.
+        """
+        if err_chain is None:
+            self._error_integrator = None
+            return None
+
+        if err_int_opts is None:
+            err_int_opts = ErrIntOpts()
+
+        self._error_integrator = ErrIntegrator(err_chain,
+                                               self._sensor_data,
+                                               self.get_measurement_shape(),
+                                               err_int_opts)
+
+    def get_errors_systematic(self) -> np.ndarray | None:
+        """Gets the systematic error array from the previously calculated sensor
+        measurements. Returns None is no error integrator has been specified.
+
+        Returns
+        -------
+        np.ndarray | None
+            Array of systematic errors for this sensor array. shape=(num_sensors
+            ,num_field_components,num_time_steps). Returns None if no error
+            integrator has been set.
+        """
+        if self._error_integrator is None:
+            return None
+
+        return self._error_integrator.get_errs_systematic()
+
+    def get_errors_random(self) -> np.ndarray | None:
+        """Gets the random error array from the previously calculated sensor
+        measurements. Returns None is no error integrator has been specified.
+
+        Returns
+        -------
+        np.ndarray | None
+            Array of random errors for this sensor array. shape=(num_sensors
+            ,num_field_components,num_time_steps). Returns None if no error
+            integrator has been set.
+        """
+        if self._error_integrator is None:
+            return None
+
+        return self._error_integrator.get_errs_random()
+
+    def get_errors_total(self) -> np.ndarray | None:
+        """Gets the total error array from the previously calculated sensor
+        measurements. Returns None is no error integrator has been specified.
+
+        Returns
+        -------
+        np.ndarray | None
+            Array of total errors for this sensor array. shape=(num_sensors
+            ,num_field_components,num_time_steps). Returns None if no error
+            integrator has been set.
+        """
+        if self._error_integrator is None:
+            return None
+
+        return self._error_integrator.get_errs_total()
+
+    def sim_measurements(self) -> np.ndarray:
+        """Calculates a set of sensor measurements using the specified sensor
+        array parameters and the error intergator if specified. Calculates
+        measurements as: measurement = truth + systematic errors + random errors
+        . The truth is calculated once and is interpolated from the input
+        simulation field. The errors are calculated based on the user specified
+        error chain in the error integrator object. If no error integrator is
+        specified then only the truth is returned.
+
+        Returns
+        -------
+        np.ndarray
+            Array of sensor measurements including any simulated random and
+            systematic errors if an error integrator is specified. shape=(
+            num_sensors,num_field_components,num_time_steps).
+        """
+        if self._error_integrator is None:
+            self._measurements = self.get_truth()
+        else:
+            self._measurements = (self.get_truth() + 
+                self._error_integrator.calc_errors_from_chain(self.get_truth()))
+
+        return self._measurements
+
+    def get_measurements(self) -> np.ndarray:
+        """Returns the current set of simulated measurements if theses have been
+        calculated. If these have not been calculated then 'sim_measurements()'
+        is called and a set of measurements in then returned.
+
+        Returns
+        -------
+        np.ndarray
+            Array of sensor measurements including any simulated random and
+            systematic errors if an error integrator is specified. shape=(
+            num_sensors,num_field_components,num_time_steps).
+        """
+        if self._measurements is None:
+            self._measurements = self.sim_measurements()
+
+        return self._measurements

pyvale/sensorsim/sensortools.py

@@ -0,0 +1,113 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+import numpy as np
+import pyvale.mooseherder as mh
+from pyvale.sensorsim.sensorarray import ISensorArray
+
+
+def gen_pos_grid_inside(num_sensors: tuple[int,int,int],
+                        x_lims: tuple[float, float],
+                        y_lims: tuple[float, float],
+                        z_lims: tuple[float, float]) -> np.ndarray:
+    """Function for creating a uniform grid of sensors inside the specified
+    bounds and returning the positions in format that can be used to build a
+    `SensorData` object.
+
+    To create a line of sensors along the X axis set the number of sensors to 1
+    for all the Y and Z axes and then set the upper and lower limits of the Y
+    and Z axis to be the same value.
+
+    To create a plane of sensors in the X-Y plane set the number of sensors in
+    Z to 1 and set the upper and lower coordinates of the Z limit to the desired
+    Z location of the plane. Then set the number of sensors in X and Y as
+    desired along with the associated limits.
+
+    Parameters
+    ----------
+    n_sens : tuple[int,int,int]
+        Number of sensors to create in the X, Y and Z directions.
+    x_lims : tuple[float, float]
+        Limits of the X axis sensor locations.
+    y_lims : tuple[float, float]
+        Limits of the Y axis sensor locations.
+    z_lims : tuple[float, float]
+        Limits of the Z axis sensor locations.
+
+    Returns
+    -------
+    np.ndarray
+        Array of sensor positions with shape=(num_sensors,3) where num_sensors
+        is the product of integers in the num_sensors tuple. The columns are the
+        X, Y and Z locations of the sensors.
+    """
+    sens_pos_x = np.linspace(x_lims[0],x_lims[1],num_sensors[0]+2)[1:-1]
+    sens_pos_y = np.linspace(y_lims[0],y_lims[1],num_sensors[1]+2)[1:-1]
+    sens_pos_z = np.linspace(z_lims[0],z_lims[1],num_sensors[2]+2)[1:-1]
+
+    (sens_grid_x,sens_grid_y,sens_grid_z) = np.meshgrid(
+        sens_pos_x,sens_pos_y,sens_pos_z
+    )
+
+    sens_pos_x = sens_grid_x.flatten()
+    sens_pos_y = sens_grid_y.flatten()
+    sens_pos_z = sens_grid_z.flatten()
+
+    sens_pos = np.vstack((sens_pos_x,sens_pos_y,sens_pos_z)).T
+    return sens_pos
+
+#TODO: create these functions
+# - Function for rectangular grid where sensors are placed up to the edges 
+# - Function for cylinder of sensor placements
+# - Function for sphere of seb5nsor placements
+
+
+def print_measurements(sens_array: ISensorArray,
+                       sensors: int | slice,
+                       components: int | slice,
+                       time_steps: int | slice)  -> None:
+    """Diagnostic function to print sensor measurements to the console. Also
+    prints the ground truth, the random and the systematic errors for the
+    specified sensor array. The sensors, components and time steps are specified
+    as slices of the measurement array.
+
+    Parameters
+    ----------
+    sens_array : ISensorArray
+        Sensor array to print measurements for.
+    sensors : int | slice
+        Index for the sensor or slice of range of sensors to be printed to the
+        console.
+    components : int | slice
+        Index for the field component or slice of range of field components to
+        be printed to the console
+    time_steps : int | slice
+        Index for the time step or slice of time steps to be printed to the
+        console.
+    """
+
+    measurement =  sens_array.get_measurements()
+    truth = sens_array.get_truth()
+    rand_errs = sens_array.get_errors_random()
+    sys_errs = sens_array.get_errors_systematic()
+    tot_errs = sens_array.get_errors_total()
+
+    print(f"measurement.shape = \n    {measurement.shape}")
+    print(f"measurement = \n    {measurement[sensors,components,time_steps]}")
+    print(f"truth = \n    {truth[sensors,components,time_steps]}")
+
+    if rand_errs is not None:
+        print(f"random errors = \n    {rand_errs[sensors,components,time_steps]}")
+
+    if sys_errs is not None:
+        print(f"systematic errors = \n    {sys_errs[sensors,components,time_steps]}")
+
+    if tot_errs is not None:
+        print(f"total errors = \n    {tot_errs[sensors,components,time_steps]}")
+
+
+
+
+