pyvale 2025.5.3__cp311-cp311-win_amd64.whl

pyvale/sensorarraypoint.py

@@ -0,0 +1,278 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
+import numpy as np
+from pyvale.field import IField
+from pyvale.sensorarray import ISensorArray
+from pyvale.errorintegrator import ErrIntegrator
+from pyvale.sensordescriptor import SensorDescriptor
+from pyvale.sensordata import SensorData
+from pyvale.fieldsampler import sample_field_with_sensor_data
+
+
+class SensorArrayPoint(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 `IErrCalculator`
+    interface). Further information can be found in the `ErrIntegrator` class
+    and in implementations of the `IErrCalculator` interface.
+
+    In `pyvale`, function and methods with `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
+    resampling probability distributions.
+
+    Calling the class method `calc_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 `calc_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.
+    """
+
+    __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_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_values(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_values()` 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_values()
+
+        return self._truth
+
+    def set_error_integrator(self, err_int: ErrIntegrator) -> None:
+        """Sets the error intergrator that will be used to calculate the sensor
+        array measurement errors when `calc_measurements()` is called. See the
+        `ErrIntegrator` class for further detail.
+
+        Parameters
+        ----------
+        err_int : ErrIntegrator
+            Error integration object with a chain of user defined sensor errors.
+        """
+        self._error_integrator = err_int
+
+    def get_sensor_data_perturbed(self) -> SensorData | None:
+        """Gets the final sensor array parameters after all errors in the error
+        integrator have been applied. If no error integrator is specified then
+        None is returned.
+
+        Returns
+        -------
+        SensorData | None
+            The accumulated sensor array parameters as a SensorData object.
+            Returns None if no error integrator has been specified.
+        """
+        if self._error_integrator is None:
+            return None
+
+        return self._error_integrator.get_sens_data_accumulated()
+
+    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 calc_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.            _description_ew simulated experiment
+        for this sensor array.
+
+        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 'calc_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.calc_measurements()
+
+        return self._measurements

pyvale/sensordata.py

@@ -0,0 +1,71 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
+from dataclasses import dataclass
+import numpy as np
+from scipy.spatial.transform import Rotation
+from pyvale.integratortype import EIntSpatialType
+
+
+@dataclass(slots=True)
+class SensorData:
+    """Data class used for specifying sensor array parameters including:
+    position, sample times, angles (for vector/tensor fields), spatial averaging
+    and spatial dimensions of the sensor for spatial averaging. The number of
+    sensor positions specified determines the number of sensors in the array.
+    """
+
+    positions: np.ndarray | None = None
+    """Numpy array of sensor positions where each row is for an individual
+    sensor and the columns specify the X, Y and Z coordinates respectively. To
+    create a sensor array the positions must be specified and the number of rows
+    of the position array determines the number of sensors in the array.
+
+    shape=(num_sensors,3)
+    """
+
+    sample_times: np.ndarray | None = None
+    """Numpy array of times at which the sensors will take measurements (sample
+    the field). This does not need to be specified to create a sensor array and
+    if it is set to None then the sample times will be assumed to be the same as
+    the simulation time steps.
+
+    shape=(num_time_steps,)
+    """
+
+    angles: tuple[Rotation,...] | None = None
+    """The angles for each sensor in the array specified using scipy Rotation
+    objects. For scalar fields the rotation only has an effect if a spatial
+    averager is specified and the locations of the integration points are
+    rotated. For vector and tensor fields the field is transformed using this
+    rotation as well as rotating the positions of the integration points if a
+    spatial averager is specified.
+
+    Specifying a single rotation in the tuple will cause all sensors to have the
+    same rotation and they will be batch processed increasing speed. Otherwise
+    this tuple must have a length equal to the number of sensors (i.e. the
+    number of rows in the position array above).
+
+    shape=(num_sensor,) | (1,)
+    """
+
+    spatial_averager: EIntSpatialType | None = None
+    """Type of spatial averaging to use for this sensor array. If None then no
+    spatial averaging is performed and sensor values are taken directly from the
+    specified positions.
+    """
+
+    spatial_dims: np.ndarray | None = None
+    """The spatial dimension of the sensor array in its local X,Y,Z coordinates.
+    Only used if spatial averager is specified above.
+
+    shape=(3,)
+    """
+
+
+
+
+

pyvale/sensordescriptor.py

@@ -0,0 +1,213 @@
+
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
+"""
+This module is used to create sensor descriptors which are strings used to label
+plots and visualisations for virtual sensor simulations.
+"""
+
+from dataclasses import dataclass
+import numpy as np
+
+
+@dataclass(slots=True)
+class SensorDescriptor:
+    """Dataclass for storing string descriptors for sensor array vis2ualisation.
+    Used for labelling matplotlib and pyvista plots with the sensor name,
+    physical units and other descriptors.
+    """
+
+    name: str = "Measured Value"
+    """String describing the field that the sensor measures e.g. temperature
+    , strain etc. Defaults to 'Measured Value'.
+    """
+
+    units: str = r"-"
+    """String describing the sensor measurement units. Defaults to '-'. Latex
+    symbols can be used with a raw string.
+    """
+
+    time_units: str = r"s"
+    """String describing time units. Defaults to 's'.
+    """
+
+    symbol: str = r"m"
+    """Symbol for describing the field the sensor measures. For example 'T' for
+    temperature of r'\epsilon' for strain. Latex symbols can be used with a raw
+    string.
+    """
+
+    tag: str = "S"
+    """String shorthand tag used to label sensors on pyvista plots. Defaults to
+    'S'.
+    """
+
+    components: tuple[str,...] | None = None
+    """Tuple of strings describing the field components. Defaults to None which
+    is used for scalar fields. For vector fields use ('x','y','z') for 3D and
+    for tensor fields use ('xx','yy','zz','xy','yz','xz').
+    """
+
+
+    def create_label(self, comp_ind: int | None = None) -> str:
+        """Creates an axis label for a matplotlib plot based on the sensor
+        descriptor string. The axis label takes the form: 'name, symbol [units]'
+        This version creates a label with line breaks which is useful for
+        vertical colourbars.
+
+        Parameters
+        ----------
+        comp_ind : int | None, optional
+            Index of the field component to create a label for, by default None.
+            If None the first field component is used.
+
+        Returns
+        -------
+        str
+            Axis label for field component in the form: 'name, symbol [units]'.
+        """
+        label = ""
+        if self.name != "":
+            label = label + rf"{self.name} "
+
+
+        symbol = rf"${self.symbol}$ "
+        if comp_ind is not None and self.components is not None:
+            symbol = rf"${self.symbol}_{{{self.components[comp_ind]}}}$ "
+        if symbol != "":
+            label = label + symbol
+
+        if self.units != "":
+            label = label + "\n" + rf"[${self.units}$]"
+
+        return label
+
+    def create_label_flat(self, comp_ind: int | None = None) -> str:
+        """Creates an axis label for a matplotlib plot based on the sensor
+        descriptor string. The axis label takes the form: 'name, symbol [units]'
+        This version creates a label with no line breaks which is useful for
+        axis labels on plots.
+
+        Parameters
+        ----------
+        comp_ind : int | None, optional
+            Index of the field component to create a label for, by default None.
+            If None the first field component is used.
+
+        Returns
+        -------
+        str
+            Axis label for field component in the form: 'name, symbol [units]'.
+        """
+        label = ""
+        if self.name != "":
+            label = label + rf"{self.name} "
+
+
+        symbol = rf"${self.symbol}$ "
+        if comp_ind is not None and self.components is not None:
+            symbol = rf"${self.symbol}_{{{self.components[comp_ind]}}}$ "
+        if symbol != "":
+            label = label + symbol
+
+        if self.units != "":
+            label = label + " " + rf"[${self.units}$]"
+
+        return label
+
+    def create_sensor_tags(self,n_sensors: int) -> list[str]:
+        """Creates a list of numbered sensor tags for labelling sensor locations
+        or for graph legends. Tags are shorthand names for sensors such as TC
+        for thermocouples or SG for strain gauges.
+
+        Parameters
+        ----------
+        n_sensors : int
+            The number of sensors to create tags for.
+
+        Returns
+        -------
+        list[str]
+            A list of sensor tags
+        """
+        z_width = int(np.log10(n_sensors))+1
+
+        sensor_names = list()
+        for ss in range(n_sensors):
+            num_str = f"{ss+1}".zfill(z_width)
+            sensor_names.append(f"{self.tag}{num_str}")
+
+        return sensor_names
+
+
+class SensorDescriptorFactory:
+    """A factory for building common sensor descriptors for scalar, vector and
+    tensor fields. Builds descriptors for thermcouples, displacement sensors
+    and strain sensors.
+    """
+
+    @staticmethod
+    def temperature_descriptor() -> SensorDescriptor:
+        """Creates a generic temperature sensor descriptor. Assumes the sensor
+        is measuring a temperature in degrees C.
+
+        Returns
+        -------
+        SensorDescriptor
+            The default temperature sensor descriptor.
+        """
+        descriptor = SensorDescriptor(name="Temp.",
+                                      symbol="T",
+                                      units=r"^{\circ}C",
+                                      tag="TC")
+        return descriptor
+
+    @staticmethod
+    def displacement_descriptor() -> SensorDescriptor:
+        """Creates a generic displacement sensor descriptor. Assumes units of mm
+        and vector components of x,y,z.
+
+        Returns
+        -------
+        SensorDescriptor
+            The default displacement sensor descriptor.
+        """
+        descriptor = SensorDescriptor(name="Disp.",
+                                      symbol="u",
+                                      units=r"mm",
+                                      tag="DS",
+                                      components=("x","y","z"))
+        return descriptor
+
+    @staticmethod
+    def strain_descriptor(spat_dims: int = 3) -> SensorDescriptor:
+        """Creates a generic strain sensor descriptor. Assumes strain is
+        unitless and that the components are xx,yy,xy for 2D and xx,yy,zz,xy,yz,
+        xz for 3D.
+
+        Parameters
+        ----------
+        spat_dims : int, optional
+            Number of spatial dimensions used for setting the components of the
+            tensor strain field, by default 3.
+
+        Returns
+        -------
+        SensorDescriptor
+            The default strain sensor descriptor.
+        """
+        descriptor = SensorDescriptor(name="Strain",
+                                      symbol=r"\varepsilon",
+                                      units=r"-",
+                                      tag="SG")
+
+        if spat_dims == 2:
+            descriptor.components = ("xx","yy","xy")
+        else:
+            descriptor.components = ("xx","yy","zz","xy","yz","xz")
+
+        return descriptor