pyvale 2025.4.0__py3-none-any.whl

pyvale/core/integratorfactory.py

@@ -0,0 +1,241 @@
+"""
+================================================================================
+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.sensordata import SensorData
+from pyvale.core.integratorspatial import IIntegratorSpatial
+from pyvale.core.integratortype import EIntSpatialType
+from pyvale.core.integratorrectangle import Rectangle2D
+from pyvale.core.integratorquadrature import (Quadrature2D,
+                                              create_gauss_weights_2d_4pts,
+                                              create_gauss_weights_2d_9pts)
+
+class IntegratorSpatialFactory:
+    """Namespace for static methods used to build 2D spatial integrators. These
+    integrators are used to simulate spatial averaging for sensors.
+    """
+
+    @staticmethod
+    def rect_2d_1pt(field: IField,
+                    sensor_data: SensorData,
+                    )-> Rectangle2D:
+        """Builds and returns a 2D rectangular spatial integrator with a single
+        integration point.
+
+        Parameters
+        ----------
+        field : IField
+            Interface specifying the physical field that the integrator will
+            sample from.
+        sensor_data : SensorData
+            Sensor data specifying the location of the sensors that will be
+            used for the spatial integration
+
+        Returns
+        -------
+        Rectangle2D
+            Rectangular spatial integrator that can sample the specified
+            physical field at specified locations
+        """
+
+        int_pt_offsets = np.array([[0,0,0],])
+
+        return Rectangle2D(field,
+                           sensor_data,
+                           int_pt_offsets)
+
+
+    @staticmethod
+    def rect_2d_4pt(field: IField,
+                    sensor_data: SensorData,
+                    )-> Rectangle2D:
+        """Builds and returns a 2D rectangular spatial integrator with four
+        equally spaced integration points in a grid pattern.
+
+        Parameters
+        ----------
+        field : IField
+            Interface specifying the physical field that the integrator will
+            sample from.
+        sensor_data : SensorData
+            Sensor data specifying the location of the sensors that will be
+            used for the spatial integration
+
+        Returns
+        -------
+        Rectangle2D
+            Rectangular spatial integrator that can sample the specified
+            physical field at specified locations
+        """
+        int_pt_offsets = sensor_data.spatial_dims * np.array([[-0.5,-0.5,0],
+                                                              [-0.5,0.5,0],
+                                                              [0.5,-0.5,0],
+                                                              [0.5,0.5,0],])
+
+        return Rectangle2D(field,
+                           sensor_data,
+                           int_pt_offsets)
+
+
+
+    @staticmethod
+    def rect_2d_9pt(field: IField,
+                    sensor_data: SensorData,
+                    )-> Rectangle2D:
+        """Builds and returns a 2D rectangular spatial integrator with nine
+        equally spaced integration points in a grid pattern.
+
+        Parameters
+        ----------
+        field : IField
+            Interface specifying the physical field that the integrator will
+            sample from.
+        sensor_data : SensorData
+            Sensor data specifying the location of the sensors that will be
+            used for the spatial integration
+
+        Returns
+        -------
+        Rectangle2D
+            Rectangular spatial integrator that can sample the specified
+            physical field at specified locations
+        """
+        int_pt_offsets = sensor_data.spatial_dims * np.array([[-1/3,-1/3,0],
+                                                              [-1/3,0,0],
+                                                              [-1/3,1/3,0],
+                                                              [0,-1/3,0],
+                                                              [0,0,0],
+                                                              [0,1/3,0],
+                                                              [1/3,-1/3,0],
+                                                              [1/3,0,0],
+                                                              [1/3,1/3,0]])
+
+        return Rectangle2D(field,
+                           sensor_data,
+                           int_pt_offsets)
+
+
+    @staticmethod
+    def quad_2d_4pt(field: IField,
+                    sensor_data: SensorData,
+                    )-> Quadrature2D:
+        """Builds and returns a Gaussian quadrature spatal integrator based on
+        a rectangular area with four integration points.
+
+        Parameters
+        ----------
+        field : IField
+            Interface specifying the physical field that the integrator will
+            sample from.
+        sensor_data : SensorData
+            Sensor data specifying the location of the sensors that will be
+            used for the spatial integration
+
+        Returns
+        -------
+        Quadrature2D
+            Quadrature integrator that can be used to sample the physical field
+            at specified locations.
+        """
+        gauss_pt_offsets = (sensor_data.spatial_dims * 1/np.sqrt(3)
+                                            * np.array([[-1,-1,0],
+                                                        [-1,1,0],
+                                                        [1,-1,0],
+                                                        [1,1,0]]))
+
+        gauss_weight_func = create_gauss_weights_2d_4pts
+
+        return Quadrature2D(field,
+                            sensor_data,
+                            gauss_pt_offsets,
+                            gauss_weight_func)
+
+
+    @staticmethod
+    def quad_2d_9pt(field: IField,
+                    sensor_data: SensorData,
+                    )-> Quadrature2D:
+        """Builds and returns a Gaussian quadrature spatal integrator based on
+        a rectangular area with nine integration points.
+
+        Parameters
+        ----------
+        field : IField
+            Interface specifying the physical field that the integrator will
+            sample from.
+        sensor_data : SensorData
+            Sensor data specifying the location of the sensors that will be
+            used for the spatial integration
+
+        Returns
+        -------
+        Quadrature2D
+            Quadrature integrator that can be used to sample the physical field
+            at specified locations.
+        """
+        gauss_pt_offsets = (sensor_data.spatial_dims
+                            * np.array([[-np.sqrt(0.6),-np.sqrt(0.6),0],
+                                        [-np.sqrt(0.6),np.sqrt(0.6),0],
+                                        [np.sqrt(0.6),-np.sqrt(0.6),0],
+                                        [np.sqrt(0.6),np.sqrt(0.6),0],
+                                        [-np.sqrt(0.6),0,0],
+                                        [0,-np.sqrt(0.6),0],
+                                        [0,np.sqrt(0.6),0],
+                                        [np.sqrt(0.6),0,0],
+                                        [0,0,0]]))
+
+        gauss_weight_func = create_gauss_weights_2d_9pts
+
+        return Quadrature2D(field,
+                            sensor_data,
+                            gauss_pt_offsets,
+                            gauss_weight_func)
+
+
+def build_spatial_averager(field: IField, sensor_data: SensorData,
+                          ) -> IIntegratorSpatial | None:
+    """Helper function to build a spatial integrator based on the
+    "EIntSpatialType" enumeration in the SensorData object. Separates the
+    spatial integration object from the SensorData object.
+
+    Parameters
+    ----------
+    field : IField
+        Physical field that will be sampled by the spatial averager.
+    sensor_data : SensorData
+        Sensor data containing the type of spatial integrator to build in the
+        `sensor_data.spatial_averager` as an `EIntSpatialType` enumeration.
+
+    Returns
+    -------
+    IIntegratorSpatial | None
+        The spatial averager that will sample the physical field at the
+        specified sensor locations. If `sensor_data.spatial_averager` or
+        `sensor_data.spatial_dims` are None then it is not possible to build a
+        spatial integrator and None is returned.
+    """
+    if sensor_data.spatial_averager is None or sensor_data.spatial_dims is None:
+        return None
+
+    if sensor_data.spatial_averager == EIntSpatialType.RECT1PT:
+        return IntegratorSpatialFactory.rect_2d_1pt(field,
+                                                    sensor_data)
+    elif sensor_data.spatial_averager == EIntSpatialType.RECT4PT:
+        return IntegratorSpatialFactory.rect_2d_4pt(field,
+                                                    sensor_data)
+    elif sensor_data.spatial_averager == EIntSpatialType.RECT9PT:
+        return IntegratorSpatialFactory.rect_2d_9pt(field,
+                                                    sensor_data)
+    elif sensor_data.spatial_averager == EIntSpatialType.QUAD4PT:
+        return IntegratorSpatialFactory.quad_2d_4pt(field,
+                                                    sensor_data)
+    elif sensor_data.spatial_averager == EIntSpatialType.QUAD9PT:
+        return IntegratorSpatialFactory.quad_2d_9pt(field,
+                                                    sensor_data)
+    else:
+        return None

pyvale/core/integratorquadrature.py

@@ -0,0 +1,192 @@
+"""
+================================================================================
+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.core.field import IField
+from pyvale.core.integratorspatial import (IIntegratorSpatial,
+                                           create_int_pt_array)
+from pyvale.core.sensordata import SensorData
+
+#TODO: Docstrings
+
+class Quadrature2D(IIntegratorSpatial):
+    """Gaussian quadrature numerical integrator for spatial averaging in 2D.
+    Used to model spatial averaging of sensors over a rectangular area which is
+    specified in the SensorData object. Handles sampling of the physical field
+    at the integration points and averages them back to a single value per
+    sensor location as specified in the SensorData object.
+
+    Implements the `IIntegratorSpatial` interface allowing for interoperability
+    of different spatial integration algorithms for modelling sensor averaging.
+    """
+    __slots__ = ("_field","_area","_n_gauss_pts","_gauss_pt_offsets"
+                 ,"_gauss_weight_func","_gauss_pts","_averages","_sens_data")
+
+    def __init__(self,
+                 field: IField,
+                 sens_data: SensorData,
+                 gauss_pt_offsets: np.ndarray,
+                 gauss_weight_func: Callable) -> None:
+        """Initiliaser for the 2D Gaussian quadrature numerical integrator.
+
+        Parameters
+        ----------
+        field : IField
+            A physical field interface that will be sampled at the integration
+            points and averaged back to single value per sensor.
+        sens_data : SensorData
+            Parameters of the sensor array including the sensor locations,
+            sampling times, type of spatial integrator and its dimensions. See
+            the `SensorData` dataclass for more details.
+        gauss_pt_offsets : np.ndarray
+            Offsets from the central location of the integration area with
+            shape=(n_gauss_pts,coord[X,Y,Z])
+        gauss_weight_func : Callable
+            A function that takes the shape of the measurement array as a tuple
+            and returns a numpy array of weights for the gaussian integration
+            points. The function must return an array with shape=(n_gauss_pts,)
+            +meas_shape where meas_shape=(num_sensors,num_field_components,
+            num_time_steps)
+        """
+        self._field = field
+        self._sens_data = sens_data
+        self._area = self._sens_data.spatial_dims[0] * \
+            self._sens_data.spatial_dims[1]
+
+        self._n_gauss_pts = gauss_pt_offsets.shape[0]
+        self._gauss_pt_offsets = gauss_pt_offsets
+        self._gauss_weight_func = gauss_weight_func
+
+        self._gauss_pts = create_int_pt_array(self._sens_data,
+                                              self._gauss_pt_offsets)
+        self._averages = None
+
+    def calc_integrals(self, sens_data: SensorData | None = None) -> np.ndarray:
+        """_summary_
+
+        Parameters
+        ----------
+        sens_data : SensorData | None, optional
+            _description_, by default None
+
+        Returns
+        -------
+        np.ndarray
+            _description_
+        """
+        self._averages = self.calc_averages(sens_data)
+        return self._area*self.get_averages()
+
+    def get_integrals(self) -> np.ndarray:
+        """_summary_
+
+        Returns
+        -------
+        np.ndarray
+            _description_
+        """
+        return self._area*self.get_averages()
+
+    def calc_averages(self, sens_data: SensorData | None = None) -> np.ndarray:
+        """_summary_
+
+        Parameters
+        ----------
+        sens_data : SensorData | None, optional
+            _description_, by default None
+
+        Returns
+        -------
+        np.ndarray
+            _description_
+        """
+        if sens_data is not None:
+            self._sens_data = sens_data
+
+        # shape=(n_sens*n_gauss_pts,n_dims)
+        self._gauss_pts = create_int_pt_array(self._sens_data,
+                                              self._gauss_pt_offsets)
+
+        # shape=(n_gauss_pts*n_sens,n_comps,n_timesteps)
+        gauss_vals = self._field.sample_field(self._gauss_pts,
+                                              self._sens_data.sample_times,
+                                              self._sens_data.angles)
+
+        meas_shape = (self._sens_data.positions.shape[0],
+                      gauss_vals.shape[1],
+                      gauss_vals.shape[2])
+
+        # shape=(n_gauss_pts,n_sens,n_comps,n_timesteps)
+        gauss_vals = gauss_vals.reshape((self._n_gauss_pts,)+meas_shape,
+                                         order='F')
+
+        # shape=(n_gauss_pts,n_sens,n_comps,n_timesteps)
+        gauss_weights = self._gauss_weight_func(meas_shape)
+
+        # NOTE: coeff comes from changing gauss interval from [-1,1] to [a,b] -
+        # so (a-b)/2 * (a-b)/2 = sensor_area / 4, then need to divide by the
+        # integration area to convert to an average:
+        # integrals = self._area/4 * np.sum(gauss_weights*gauss_vals,axis=0)
+        # self._averages = (1/self._area)*integrals
+
+        # shape=(n_sensors,n_comps,n_timsteps)=meas_shape
+        self._averages = 1/4 * np.sum(gauss_weights*gauss_vals,axis=0)
+        return self._averages
+
+    def get_averages(self) -> np.ndarray:
+        """_summary_
+
+        Returns
+        -------
+        np.ndarray
+            _description_
+        """
+        if self._averages is None:
+            self._averages = self.calc_averages()
+
+        return self._averages
+
+
+def create_gauss_weights_2d_4pts(meas_shape: tuple[int,int,int]) -> np.ndarray:
+    """Helper function that creates an array of weights for gaussian quadrature
+    integration. This function provides the weights for 2D integrator with 4
+    integration points.
+
+    Parameters
+    ----------
+    meas_shape : tuple[int,int,int]
+        _description_
+
+    Returns
+    -------
+    np.ndarray
+        _description_
+    """
+    #shape=(4,)+meas_shape
+    return np.ones((4,)+meas_shape)
+
+
+def create_gauss_weights_2d_9pts(meas_shape: tuple[int,int,int]) -> np.ndarray:
+    """_summary_
+
+    Parameters
+    ----------
+    meas_shape : tuple[int,int,int]
+        _description_
+
+    Returns
+    -------
+    np.ndarray
+        _description_
+    """
+    # shape=(9,)+meas_shape
+    gauss_weights = np.vstack((25/81 * np.ones((4,)+meas_shape),
+                               40/81 * np.ones((4,)+meas_shape),
+                               64/81 * np.ones((1,)+meas_shape)))
+    return gauss_weights
+

pyvale/core/integratorrectangle.py

@@ -0,0 +1,88 @@
+"""
+================================================================================
+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.integratorspatial import (IIntegratorSpatial,
+                                           create_int_pt_array)
+from pyvale.core.sensordata import SensorData
+
+
+#TODO: Docstrings
+
+#NOTE: code below is very similar to quadrature integrator should be able to
+# refactor into injected classes/functions
+
+class Rectangle2D(IIntegratorSpatial):
+    __slots__ = ("_field","sens_data","_area","_area_int","_n_int_pts",
+                 "_int_pt_offsets","_int_pts","_averages")
+
+    def __init__(self,
+                 field: IField,
+                 sens_data: SensorData,
+                 int_pt_offsets: np.ndarray) -> None:
+
+        self._field = field
+        self._sens_data = sens_data
+
+        self._area = (self._sens_data.spatial_dims[0]
+                      * self._sens_data.spatial_dims[1])
+        self._area_int = self._area/int_pt_offsets.shape[0]
+
+        self._n_int_pts = int_pt_offsets.shape[0]
+        self._int_pt_offsets = int_pt_offsets
+        self._int_pts = create_int_pt_array(self._sens_data,
+                                            self._int_pt_offsets)
+
+        self._averages = None
+
+
+    def calc_integrals(self, sens_data: SensorData | None = None) -> np.ndarray:
+        self._averages = self.calc_averages(sens_data)
+        return self._area*self.get_averages()
+
+
+    def get_integrals(self) -> np.ndarray:
+        return self._area*self.get_averages()
+
+    def calc_averages(self, sens_data: SensorData | None = None) -> np.ndarray:
+
+        if sens_data is not None:
+            self._sens_data = sens_data
+
+        # shape=(n_sens*n_int_pts,n_dims)
+        self._int_pts = create_int_pt_array(self._sens_data,
+                                            self._int_pt_offsets)
+
+
+        # shape=(n_int_pts*n_sens,n_comps,n_timesteps)
+        int_vals = self._field.sample_field(self._int_pts,
+                                            self._sens_data.sample_times,
+                                            self._sens_data.angles)
+
+        meas_shape = (self._sens_data.positions.shape[0],
+                      int_vals.shape[1],
+                      int_vals.shape[2])
+
+        # shape=(n_gauss_pts,n_sens,n_comps,n_timesteps)
+        int_vals = int_vals.reshape((self._n_int_pts,)+meas_shape,
+                                     order='F')
+
+        # shape=(n_sensors,n_comps,n_timsteps)
+        self._averages = 1/self._area * np.sum(self._area_int*int_vals,axis=0)
+
+        return self._averages
+
+
+    def get_averages(self) -> np.ndarray:
+        if self._averages is None:
+            self._averages = self.calc_averages()
+
+        return self._averages
+
+
+

pyvale/core/integratorspatial.py

@@ -0,0 +1,90 @@
+"""
+================================================================================
+pyvale: the python validation engine
+License: MIT
+Copyright (C) 2025 The Computer Aided Validation Team
+================================================================================
+"""
+from abc import ABC, abstractmethod
+import numpy as np
+from pyvale.core.sensordata import SensorData
+
+
+def create_int_pt_array(sens_data: SensorData,
+                        int_pt_offsets: np.ndarray,
+                        ) -> np.ndarray:
+    """Creates the integration point locations in local coordinates based on the
+    specified offsets from the local origin.
+
+    Parameters
+    ----------
+    sens_data : SensorData
+        Contains the parameters of the sensor array including: positions, sample
+        times and orientations. If specified the sensor orientations are used
+        to rotate the positions of the integration points.
+    int_pt_offsets : np.ndarray
+        Offsets of the intergation points in non-rotated local coordinates.
+
+    Returns
+    -------
+    np.ndarray
+        The integration point locations in world (simulation) coordinates. The
+        rows of the array are all the integration points for all sensors and the
+        columns are the X,Y,Z coordinates. shape=(num_sensors*num_int_points,3).
+    """
+    n_sens = sens_data.positions.shape[0]
+    n_int_pts = int_pt_offsets.shape[0]
+
+    # shape=(n_sens*n_int_pts,n_dims)
+    offset_array = np.tile(int_pt_offsets,(n_sens,1))
+
+    if sens_data.angles is not None:
+        for ii,rr in enumerate(sens_data.angles):
+            offset_array[ii*n_int_pts:(ii+1)*n_int_pts,:] = \
+                np.matmul(rr.as_matrix(),int_pt_offsets.T).T
+
+    # shape=(n_sens*n_int_pts,n_dims)
+    int_pt_array = np.repeat(sens_data.positions,int_pt_offsets.shape[0],axis=0)
+
+    return int_pt_array + offset_array
+
+
+class IIntegratorSpatial(ABC):
+    """Interface (abstract base class) for spatial integrators. Used for
+    averaging sensor values over a given space.
+    """
+
+    @abstractmethod
+    def calc_averages(self, sens_data: SensorData) -> np.ndarray:
+        """Abstract method. Calculates the spatial average for each sensor using
+        the specified sensor dimensions and integration method. This is done by
+        interpolating the sensor values at each sensors integration points.
+
+        Parameters
+        ----------
+        sens_data : SensorData
+            Contains the parameters of the sensor array including: positions,
+            sample times, spatial averaging and orientations.
+
+        Returns
+        -------
+        np.ndarray
+            Array of simulated sensor measurements. shape=(num_sensors,
+            num_field_components,num_time_steps).
+        """
+        pass
+
+    @abstractmethod
+    def get_averages(self) -> np.ndarray:
+        """Abstract method. Returns the previously calculated spatial averages
+        for each sensor. If these have not been calculated then `calc_averages`
+        is called and the result is returned.
+
+        Returns
+        -------
+        np.ndarray
+            Array of simulated sensor measurements. shape=(num_sensors,
+            num_field_components,num_time_steps).
+        """
+        pass
+

pyvale/core/integratortype.py

@@ -0,0 +1,44 @@
+"""
+================================================================================
+pyvale: the python validation engine
+License: MIT
+Copyright (C) 2025 The Computer Aided Validation Team
+================================================================================
+"""
+import enum
+
+
+class EIntSpatialType(enum.Enum):
+    """Enumeration specifying the type of spatial integrator to build. Used for
+    spatial averaging for sensors.
+
+    RECT1PT
+        Rectangular 2D integrator splitting the area into 1 part.
+
+    RECT4PT
+        Rectangular 2D integrator splitting the area into 4 equal parts.
+
+    RECT9PT
+        Rectangular 2D integrator splitting the area into 9 equal parts.
+
+    QUAD4PT
+        Gaussian quadrature 2D integrator over 4 points.
+
+    QUAD9PT
+        Gaussia quadrature 2D integrator over 9 points.
+    """
+
+    RECT1PT = enum.auto()
+    """Rectangular 2D integrator splitting the area into 1 part."""
+
+    RECT4PT = enum.auto()
+    """Rectangular 2D integrator splitting the area into 4 equal parts."""
+
+    RECT9PT = enum.auto()
+    """Rectangular 2D integrator splitting the area into 9 equal parts."""
+
+    QUAD4PT = enum.auto()
+    """Gaussian quadrature 2D integrator over 4 points."""
+
+    QUAD9PT = enum.auto()
+    """Gaussia quadrature 2D integrator over 9 points."""