pyvale 2025.4.0__py3-none-any.whl

pyvale/core/sensorarraypoint.py

@@ -0,0 +1,280 @@
+"""
+================================================================================
+pyvale: the python validation engine
+License: MIT
+Copyright (C) 2025 The Computer Aided Validation Team
+================================================================================
+"""
+import numpy as np
+from pyvale.core.field import IField
+from pyvale.core.sensorarray import ISensorArray
+from pyvale.core.errorintegrator import ErrIntegrator
+from pyvale.core.sensordescriptor import SensorDescriptor
+from pyvale.core.sensordata import SensorData
+from pyvale.core.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:
+        """Initialiser for the `SensorArrayPoint` class.
+
+        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/core/sensordata.py

@@ -0,0 +1,72 @@
+"""
+================================================================================
+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.core.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/core/sensordescriptor.py

@@ -0,0 +1,101 @@
+
+"""
+================================================================================
+pyvale: the python validation engine
+License: MIT
+Copyright (C) 2025 The Computer Aided Validation Team
+================================================================================
+"""
+from dataclasses import dataclass
+import numpy as np
+
+#TODO: Docstrings
+
+@dataclass(slots=True)
+class SensorDescriptor:
+    name: str = 'Measured Value'
+    units: str = r"-"
+    time_units: str = r"s"
+    symbol: str = r"m"
+    tag: str = 'S'
+    components: tuple[str,...] | None = None
+
+    def create_label(self, comp_ind: int | None = None) -> str:
+        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:
+        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]:
+        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:
+    @staticmethod
+    def temperature_descriptor() -> SensorDescriptor:
+        descriptor = SensorDescriptor()
+        descriptor.name = 'Temp.'
+        descriptor.symbol = 'T'
+        descriptor.units = r'^{\circ}C'
+        descriptor.tag = 'TC'
+        return descriptor
+
+    @staticmethod
+    def displacement_descriptor() -> SensorDescriptor:
+        descriptor = SensorDescriptor()
+        descriptor.name = 'Disp.'
+        descriptor.symbol = 'u'
+        descriptor.units = r'm'
+        descriptor.tag = 'DS'
+        descriptor.components = ('x','y','z')
+        return descriptor
+
+    @staticmethod
+    def strain_descriptor(spat_dims: int = 3) -> SensorDescriptor:
+        descriptor = SensorDescriptor()
+        descriptor.name = 'Strain'
+        descriptor.symbol = r'\varepsilon'
+        descriptor.units = r'-'
+        descriptor.tag = 'SG'
+
+        if spat_dims == 2:
+            descriptor.components = ('xx','yy','xy')
+        else:
+            descriptor.components = ('xx','yy','zz','xy','yz','xz')
+
+        return descriptor

pyvale/core/sensortools.py

@@ -0,0 +1,143 @@
+"""
+================================================================================
+pyvale: the python validation engine
+License: MIT
+Copyright (C) 2025 The Computer Aided Validation Team
+================================================================================
+"""
+import numpy as np
+import mooseherder as mh
+from pyvale.core.sensorarray import ISensorArray
+
+
+def create_sensor_pos_array(num_sensors: tuple[int,int,int],
+                           x_lims: tuple[float, float],
+                           y_lims: tuple[float, float],
+                           z_lims: tuple[float, float]) -> np.ndarray:
+    """Function or 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
+
+
+def print_measurements(sens_array: ISensorArray,
+                       sensors: tuple[int,int],
+                       components: tuple[int,int],
+                       time_steps: tuple[int,int])  -> 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 measurement for.
+    sensors : tuple[int,int]
+        Range of sensors to print from the measurement array using the slice
+        specified by this tuple.
+    components : tuple[int,int]
+        Range of field components to print based on slicing the measurement
+        array with this tuple.
+    time_steps : tuple[int,int]
+        Range of time steps to print based on slicing the measurement array with
+        this tuple.
+    """
+    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"\nmeasurement.shape = \n    {measurement.shape}")
+    print_meas = measurement[sensors[0]:sensors[1],
+                             components[0]:components[1],
+                             time_steps[0]:time_steps[1]]
+    print(f"measurement = \n    {print_meas}")
+
+    print_truth = truth[sensors[0]:sensors[1],
+                        components[0]:components[1],
+                        time_steps[0]:time_steps[1]]
+    print(f"truth = \n    {print_truth}")
+
+    if rand_errs is not None:
+        print_randerrs = rand_errs[sensors[0]:sensors[1],
+                                    components[0]:components[1],
+                                    time_steps[0]:time_steps[1]]
+        print(f"random errors = \n    {print_randerrs}")
+
+    if sys_errs is not None:
+        print_syserrs = sys_errs[sensors[0]:sensors[1],
+                                        components[0]:components[1],
+                                        time_steps[0]:time_steps[1]]
+        print(f"systematic errors = \n    {print_syserrs}")
+
+    if tot_errs is not None:
+        print_toterrs = tot_errs[sensors[0]:sensors[1],
+                                        components[0]:components[1],
+                                        time_steps[0]:time_steps[1]]
+        print(f"total errors = \n    {print_syserrs}")
+
+    print()
+
+
+def print_dimensions(sim_data: mh.SimData) -> None:
+    """Diagnostic function for quickly finding the coordinate limits for from a
+    given simulation.
+
+    Parameters
+    ----------
+    sim_data : mh.SimData
+        Simulation data objects containing the nodal coordinates.
+    """
+    print(80*"-")
+    print("SimData Dimensions:")
+    print(f"x [min,max] = [{np.min(sim_data.coords[:,0])}," + \
+          f"{np.max(sim_data.coords[:,0])}]")
+    print(f"y [min,max] = [{np.min(sim_data.coords[:,1])}," + \
+          f"{np.max(sim_data.coords[:,1])}]")
+    print(f"z [min,max] = [{np.min(sim_data.coords[:,2])}," + \
+          f"{np.max(sim_data.coords[:,2])}]")
+    print(f"t [min,max] = [{np.min(sim_data.time)},{np.max(sim_data.time)}]")
+    print(80*"-")
+