pyvale 2025.4.0__py3-none-any.whl → 2025.5.1__py3-none-any.whl

pyvale/{core/generatorsrandom.py → generatorsrandom.py}

@@ -1,15 +1,14 @@
-"""
-================================================================================
-pyvale: the python validation engine
-License: MIT
-Copyright (C) 2025 The Computer Aided Validation Team
-================================================================================
-"""
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
 from abc import ABC, abstractmethod
 import numpy as np
 
 
-class IGeneratorRandom(ABC):
+class IGenRandom(ABC):
     """Interface (abstract base class) for wrapping numpy random number
     generation to allow probability distribution parameters to be specified in
     the initialiser whereas the generation of random numbers has a common
@@ -35,7 +34,7 @@ class IGeneratorRandom(ABC):
         pass
 
 
-class GeneratorNormal(IGeneratorRandom):
+class GenNormal(IGenRandom):
     """Class wrapping the numpy normal random number generator. Implements the
     IGeneratorRandom interface to allow for interchangeability with other random
     number generators.
@@ -46,9 +45,7 @@ class GeneratorNormal(IGeneratorRandom):
                  std: float = 1.0,
                  mean: float = 0.0,
                  seed: int | None = None) -> None:
-        """Initialiser taking the parameters of the probability distribution and
-        an optional seed for the random generator to allow for reproducibility.
-
+        """
         Parameters
         ----------
         std : float, optional
@@ -83,7 +80,7 @@ class GeneratorNormal(IGeneratorRandom):
                                 size = shape)
 
 
-class GeneratorLogNormal(IGeneratorRandom):
+class GenLogNormal(IGenRandom):
     """Class wrapping the numpy lognormal random generator. Implements the
     IGeneratorRandom interface to allow for interchangeability with other random
     number generators.
@@ -94,9 +91,7 @@ class GeneratorLogNormal(IGeneratorRandom):
                  std: float = 1.0,
                  mean: float = 0.0,
                  seed: int | None = None) -> None:
-        """Initialiser taking the parameters of the probability distribution and
-        an optional seed for the random generator to allow for reproducibility.
-
+        """
         Parameters
         ----------
         std : float, optional
@@ -130,7 +125,7 @@ class GeneratorLogNormal(IGeneratorRandom):
                                    size = shape)
 
 
-class GeneratorUniform(IGeneratorRandom):
+class GenUniform(IGenRandom):
     """Class wrapping the numpy uniform random number generator. Implements the
     IGeneratorRandom interface to allow for interchangeability with other random
     number generators.
@@ -141,9 +136,7 @@ class GeneratorUniform(IGeneratorRandom):
                  low: float = -1.0,
                  high: float = 1.0,
                  seed: int | None = None) -> None:
-        """Initialiser taking the parameters of the probability distribution and
-        an optional seed for the random generator to allow for reproducibility.
-
+        """
         Parameters
         ----------
         low : float, optional
@@ -177,7 +170,7 @@ class GeneratorUniform(IGeneratorRandom):
                                  size = shape)
 
 
-class GeneratorExponential(IGeneratorRandom):
+class GenExponential(IGenRandom):
     """Class wrapping the numpy exponential random generator. Implements the
     IGeneratorRandom interface to allow for interchangeability with other random
     number generators.
@@ -187,9 +180,7 @@ class GeneratorExponential(IGeneratorRandom):
     def __init__(self,
                  scale: float = 1.0,
                  seed: int | None = None) -> None:
-        """Initialiser taking the parameters of the probability distribution and
-        an optional seed for the random generator to allow for reproducibility.
-
+        """
         Parameters
         ----------
         scale : float, optional
@@ -219,7 +210,7 @@ class GeneratorExponential(IGeneratorRandom):
                                      size = shape)
 
 
-class GeneratorChiSquare(IGeneratorRandom):
+class GenChiSquare(IGenRandom):
     """Class wrapping the numpy chi square random generator. Implements the
     IGeneratorRandom interface to allow for interchangeability with other random
     number generators.
@@ -229,9 +220,7 @@ class GeneratorChiSquare(IGeneratorRandom):
     def __init__(self,
                  dofs: float,
                  seed: int | None = None) -> None:
-        """Initialiser taking the parameters of the probability distribution and
-        an optional seed for the random generator to allow for reproducibility.
-
+        """
         Parameters
         ----------
         dofs : float
@@ -261,7 +250,7 @@ class GeneratorChiSquare(IGeneratorRandom):
                                    size = shape)
 
 
-class GeneratorDirichlet(IGeneratorRandom):
+class GenDirichlet(IGenRandom):
     """Class wrapping the numpy dirichlet random generator. Implements the
     IGeneratorRandom interface to allow for interchangeability with other random
     number generators.
@@ -271,9 +260,7 @@ class GeneratorDirichlet(IGeneratorRandom):
     def __init__(self,
                  alpha: float,
                  seed: int | None = None) -> None:
-        """Initialiser taking the parameters of the probability distribution and
-        an optional seed for the random generator to allow for reproducibility.
-
+        """
         Parameters
         ----------
         alpha : float
@@ -301,7 +288,7 @@ class GeneratorDirichlet(IGeneratorRandom):
         return self._rng.dirichlet(alpha = self._alpha, size = shape)
 
 
-class GeneratorF(IGeneratorRandom):
+class GenF(IGenRandom):
     """Class wrapping the numpy F distribution random generator. Implements the
     IGeneratorRandom interface to allow for interchangeability with other random
     number generators.
@@ -311,9 +298,7 @@ class GeneratorF(IGeneratorRandom):
     def __init__(self,
                  dofs: float,
                  seed: int | None = None) -> None:
-        """Initialiser taking the parameters of the probability distribution and
-        an optional seed for the random generator to allow for reproducibility.
-
+        """
         Parameters
         ----------
         dofs : float
@@ -342,7 +327,7 @@ class GeneratorF(IGeneratorRandom):
         return self._rng.f(dfnum = self._dofs, size = shape)
 
 
-class GeneratorGamma(IGeneratorRandom):
+class GenGamma(IGenRandom):
     """Class wrapping the numpy gamma random generator. Implements the
     IGeneratorRandom interface to allow for interchangeability with other random
     number generators.
@@ -353,9 +338,7 @@ class GeneratorGamma(IGeneratorRandom):
                  shape: float,
                  scale: float = 1.0,
                  seed: int | None = None) -> None:
-        """Initialiser taking the parameters of the probability distribution and
-        an optional seed for the random generator to allow for reproducibility.
-
+        """
         Parameters
         ----------
         shape : float
@@ -388,7 +371,7 @@ class GeneratorGamma(IGeneratorRandom):
                                      size = shape)
 
 
-class GeneratorStandardT(IGeneratorRandom):
+class GenStandardT(IGenRandom):
     """Class wrapping the numpy t distribution random generator. Implements the
     IGeneratorRandom interface to allow for interchangeability with other random
     number generators.
@@ -398,9 +381,7 @@ class GeneratorStandardT(IGeneratorRandom):
     def __init__(self,
                  dofs: float,
                  seed: int | None = None) -> None:
-        """Initialiser taking the parameters of the probability distribution and
-        an optional seed for the random generator to allow for reproducibility.
-
+        """
         Parameters
         ----------
         dofs : float
@@ -430,7 +411,7 @@ class GeneratorStandardT(IGeneratorRandom):
                                    size = shape)
 
 
-class GeneratorBeta(IGeneratorRandom):
+class GenBeta(IGenRandom):
     """Class wrapping the numpy beta distribution random generator. Implements
     the IGeneratorRandom interface to allow for interchangeability with other
     random number generators.
@@ -441,9 +422,7 @@ class GeneratorBeta(IGeneratorRandom):
                  a: float,
                  b: float,
                  seed: int | None = None) -> None:
-        """Initialiser taking the parameters of the probability distribution and
-        an optional seed for the random generator to allow for reproducibility.
-
+        """
         Parameters
         ----------
         a : float
@@ -476,7 +455,7 @@ class GeneratorBeta(IGeneratorRandom):
                               size = shape)
 
 
-class GeneratorTriangular(IGeneratorRandom):
+class GenTriangular(IGenRandom):
     """Class wrapping the numpy triangular random generator. Implements the
     IGeneratorRandom interface to allow for interchangeability with other random
     number generators.
@@ -488,9 +467,7 @@ class GeneratorTriangular(IGeneratorRandom):
                  mode: float = 0.0,
                  right: float = 1.0,
                  seed: int | None = None) -> None:
-        """Initialiser taking the parameters of the probability distribution and
-        an optional seed for the random generator to allow for reproducibility.
-
+        """
         Parameters
         ----------
         left : float, optional

pyvale/{core/imagedef2d.py → imagedef2d.py}

@@ -1,10 +1,13 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
 """
-================================================================================
-pyvale: the python validation engine
-License: MIT
-Copyright (C) 2025 The Computer Aided Validation Team
-================================================================================
+NOTE: This module is a feature under developement.
 """
+
 import time
 import warnings
 from dataclasses import dataclass
@@ -14,9 +17,9 @@ from scipy.interpolate import griddata
 from scipy.interpolate import RectBivariateSpline
 from scipy import ndimage
 
-from pyvale.core.rasternp import edge_function, RasterNP
-from pyvale.core.cameradata2d import CameraData2D
-from pyvale.core.cameratools import CameraTools
+from pyvale.rasternp import edge_function, RasterNP
+from pyvale.cameradata2d import CameraData2D
+from pyvale.cameratools import CameraTools
 
 
 @dataclass(slots=True)

pyvale/{core/integratorfactory.py → integratorfactory.py}

@@ -1,17 +1,16 @@
-"""
-================================================================================
-pyvale: the python validation engine
-License: MIT
-Copyright (C) 2025 The Computer Aided Validation Team
-================================================================================
-"""
+# ==============================================================================
+# 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,
+from pyvale.field import IField
+from pyvale.sensordata import SensorData
+from pyvale.integratorspatial import IIntegratorSpatial
+from pyvale.integratortype import EIntSpatialType
+from pyvale.integratorrectangle import Rectangle2D
+from pyvale.integratorquadrature import (Quadrature2D,
                                               create_gauss_weights_2d_4pts,
                                               create_gauss_weights_2d_9pts)
 

pyvale/{core/integratorquadrature.py → integratorquadrature.py}

@@ -1,18 +1,16 @@
-"""
-================================================================================
-pyvale: the python validation engine
-License: MIT
-Copyright (C) 2025 The Computer Aided Validation Team
-================================================================================
-"""
+# ==============================================================================
+# 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
+from pyvale.field import IField
+from pyvale.integratorspatial import (IIntegratorSpatial,
+                                      create_int_pt_array)
+from pyvale.sensordata import SensorData
 
-#TODO: Docstrings
 
 class Quadrature2D(IIntegratorSpatial):
     """Gaussian quadrature numerical integrator for spatial averaging in 2D.
@@ -24,7 +22,7 @@ class Quadrature2D(IIntegratorSpatial):
     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"
+    __slots__ = ("_field","_area","_gauss_pts_num","_gauss_pt_offsets"
                  ,"_gauss_weight_func","_gauss_pts","_averages","_sens_data")
 
     def __init__(self,
@@ -32,8 +30,7 @@ class Quadrature2D(IIntegratorSpatial):
                  sens_data: SensorData,
                  gauss_pt_offsets: np.ndarray,
                  gauss_weight_func: Callable) -> None:
-        """Initiliaser for the 2D Gaussian quadrature numerical integrator.
-
+        """
         Parameters
         ----------
         field : IField
@@ -58,7 +55,7 @@ class Quadrature2D(IIntegratorSpatial):
         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_pts_num = gauss_pt_offsets.shape[0]
         self._gauss_pt_offsets = gauss_pt_offsets
         self._gauss_weight_func = gauss_weight_func
 
@@ -67,43 +64,61 @@ class Quadrature2D(IIntegratorSpatial):
         self._averages = None
 
     def calc_integrals(self, sens_data: SensorData | None = None) -> np.ndarray:
-        """_summary_
+        """Calculates the numerical integrals for each sensor based on the
+        specified sensor data and numerical integration options (i.e. geometry
+        and integration points).
 
         Parameters
         ----------
         sens_data : SensorData | None, optional
-            _description_, by default None
+            Specifies the sensor parameters used to calculate the averages, by
+            default None. Is a sensor data object is passed a reference to that
+            object is stored by this class and used in later calculations. If
+            None then it uses the SensorData object stored by this class.
+            Defaults to None.
 
         Returns
         -------
         np.ndarray
-            _description_
+            Array of virtual sensor integrals with shape=(n_sensors,n_comps,
+            n_timsteps). Note this is consistent with pyvales measurement array.
         """
         self._averages = self.calc_averages(sens_data)
         return self._area*self.get_averages()
 
     def get_integrals(self) -> np.ndarray:
-        """_summary_
+        """Gets the most recent calculation of the spatial averages for all
+        sensors in the sensor array without performing any new interpolation. If
+        the averages have not been calculated they are first calculated and then
+        returned.
 
         Returns
         -------
         np.ndarray
-            _description_
+            Array of virtual sensor averages with shape=(n_sensors,n_comps,
+            n_timsteps). Note this is consistent with pyvales measurement array.
         """
         return self._area*self.get_averages()
 
     def calc_averages(self, sens_data: SensorData | None = None) -> np.ndarray:
-        """_summary_
+        """Calculates the spatial averages for each sensor based on the
+        specified sensor data and numerical integration options (i.e. geometry
+        and integration points).
 
         Parameters
         ----------
         sens_data : SensorData | None, optional
-            _description_, by default None
+            Specifies the sensor parameters used to calculate the averages, by
+            default None. Is a sensor data object is passed a reference to that
+            object is stored by this class and used in later calculations. If
+            None then it uses the SensorData object stored by this class.
+            Defaults to None.
 
         Returns
         -------
         np.ndarray
-            _description_
+            Array of virtual sensor averages with shape=(n_sensors,n_comps,
+            n_timsteps). Note this is consistent with pyvales measurement array.
         """
         if sens_data is not None:
             self._sens_data = sens_data
@@ -122,7 +137,7 @@ class Quadrature2D(IIntegratorSpatial):
                       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,
+        gauss_vals = gauss_vals.reshape((self._gauss_pts_num,)+meas_shape,
                                          order='F')
 
         # shape=(n_gauss_pts,n_sens,n_comps,n_timesteps)
@@ -139,12 +154,16 @@ class Quadrature2D(IIntegratorSpatial):
         return self._averages
 
     def get_averages(self) -> np.ndarray:
-        """_summary_
+        """Gets the most recent calculation of the spatial averages for all
+        sensors in the sensor array without performing any new interpolation. If
+        the averages have not been calculated they are first calculated and then
+        returned.
 
         Returns
         -------
         np.ndarray
-            _description_
+            Array of virtual sensor averages with shape=(n_sensors,n_comps,
+            n_timsteps). Note this is consistent with pyvales measurement array.
         """
         if self._averages is None:
             self._averages = self.calc_averages()
@@ -160,29 +179,35 @@ def create_gauss_weights_2d_4pts(meas_shape: tuple[int,int,int]) -> np.ndarray:
     Parameters
     ----------
     meas_shape : tuple[int,int,int]
-        _description_
+        Shape of the measurement array, shape=(n_sensors,n_field_comps,
+        n_time_steps).
 
     Returns
     -------
     np.ndarray
-        _description_
+        Array of gaussian quadrature weights with shape = (n_gauss_pts,n_sensors
+        ,n_field_comps,n_time_steps).
     """
     #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_
+    """Helper function that creates an array of weights for gaussian quadrature
+    integration. This function provides the weights for 2D integrator with 9
+    integration points.
 
     Parameters
     ----------
     meas_shape : tuple[int,int,int]
-        _description_
+        Shape of the measurement array, shape=(n_sensors,n_field_comps,
+        n_time_steps).
 
     Returns
     -------
     np.ndarray
-        _description_
+        Array of gaussian quadrature weights with shape = (n_gauss_pts,n_sensors
+        ,n_field_comps,n_time_steps).
     """
     # shape=(9,)+meas_shape
     gauss_weights = np.vstack((25/81 * np.ones((4,)+meas_shape),

pyvale/integratorrectangle.py

@@ -0,0 +1,165 @@
+# ==============================================================================
+# 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.integratorspatial import (IIntegratorSpatial,
+                                           create_int_pt_array)
+from pyvale.sensordata import SensorData
+
+#NOTE: code below is very similar to quadrature integrator should be able to
+# refactor into injected classes/functions
+
+class Rectangle2D(IIntegratorSpatial):
+    """Rectangular 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","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:
+        """
+        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.
+        int_pt_offsets : np.ndarray
+            Offsets from the central location of the integration area with
+            shape=(n_gauss_pts,coord[X,Y,Z])
+        """
+        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:
+        """Calculates the numerical integrals for each sensor based on the
+        specified sensor data and numerical integration options (i.e. geometry
+        and integration points).
+
+        Parameters
+        ----------
+        sens_data : SensorData | None, optional
+            Specifies the sensor parameters used to calculate the averages, by
+            default None. Is a sensor data object is passed a reference to that
+            object is stored by this class and used in later calculations. If
+            None then it uses the SensorData object stored by this class.
+            Defaults to None.
+
+        Returns
+        -------
+        np.ndarray
+            Array of virtual sensor integrals with shape=(n_sensors,n_comps,
+            n_timsteps). Note this is consistent with pyvales measurement array.
+        """
+        self._averages = self.calc_averages(sens_data)
+        return self._area*self.get_averages()
+
+
+    def get_integrals(self) -> np.ndarray:
+        """Gets the most recent calculation of the spatial averages for all
+        sensors in the sensor array without performing any new interpolation. If
+        the averages have not been calculated they are first calculated and then
+        returned.
+
+        Returns
+        -------
+        np.ndarray
+            Array of virtual sensor averages with shape=(n_sensors,n_comps,
+            n_timsteps). Note this is consistent with pyvales measurement array.
+        """
+        return self._area*self.get_averages()
+
+    def calc_averages(self, sens_data: SensorData | None = None) -> np.ndarray:
+        """Calculates the spatial averages for each sensor based on the
+        specified sensor data and numerical integration options (i.e. geometry
+        and integration points).
+
+        Parameters
+        ----------
+        sens_data : SensorData | None, optional
+            Specifies the sensor parameters used to calculate the averages, by
+            default None. Is a sensor data object is passed a reference to that
+            object is stored by this class and used in later calculations. If
+            None then it uses the SensorData object stored by this class.
+            Defaults to None.
+
+        Returns
+        -------
+        np.ndarray
+            Array of virtual sensor averages with shape=(n_sensors,n_comps,
+            n_timsteps). Note this is consistent with pyvales measurement array.
+        """
+        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:
+        """Gets the most recent calculation of the spatial averages for all
+        sensors in the sensor array without performing any new interpolation. If
+        the averages have not been calculated they are first calculated and then
+        returned.
+
+        Returns
+        -------
+        np.ndarray
+            Array of virtual sensor averages with shape=(n_sensors,n_comps,
+            n_timsteps). Note this is consistent with pyvales measurement array.
+        """
+        if self._averages is None:
+            self._averages = self.calc_averages()
+
+        return self._averages
+
+
+