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

pyvale/sensorarrayfactory.py

@@ -1,8 +1,8 @@
-# ================================================================================
+# ==============================================================================
 # pyvale: the python validation engine
 # License: MIT
 # Copyright (C) 2025 The Computer Aided Validation Team
-# ================================================================================
+# ==============================================================================
 
 import numpy as np
 
@@ -14,12 +14,14 @@ from pyvale.fieldtensor import FieldTensor
 from pyvale.sensordescriptor import SensorDescriptorFactory
 from pyvale.sensorarraypoint import SensorArrayPoint, SensorData
 from pyvale.errorintegrator import ErrIntegrator
-from pyvale.errorsysindep import ErrSysUniformPercent
+from pyvale.errorsysindep import ErrSysUnifPercent
 from pyvale.errorrand import ErrRandNormPercent
 from pyvale.errorsysdep import (ErrSysDigitisation,
                                      ErrSysSaturation)
 
-#TODO: Docstrings
+# TODO:
+# - docstrings
+# - more sensor models
 
 class SensorArrayFactory:
     """Namespace for static methods used to build common types of sensor arrays
@@ -29,35 +31,13 @@ class SensorArrayFactory:
     @staticmethod
     def thermocouples_no_errs(sim_data: mh.SimData,
                               sensor_data: SensorData,
+                              elem_dims: int,
                               field_name: str = "temperature",
-                              spat_dims: int = 3,
                               ) -> SensorArrayPoint:
-        """Builds and returns a point sensor array with common parameters used
-        for thermocouples applied to a temperature field without any simulated
-        measurement errors. Allows the user to build and attach their own error
-        chain or use this for fast interpolation to sensor locations without
-        errors.
-
-        Parameters
-        ----------
-        sim_data : mh.SimData
-            Simulation data containing a mesh and a temperature field for the
-            thermocouple array to sample.
-        sensor_data : SensorData
-            _description_
-        field_name : str, optional
-            _description_, by default "temperature"
-        spat_dims : int, optional
-            , by default 3
-
-        Returns
-        -------
-        SensorArrayPoint
-            _description_
-        """
+
         descriptor = SensorDescriptorFactory.temperature_descriptor()
 
-        t_field = FieldScalar(sim_data,field_name,spat_dims)
+        t_field = FieldScalar(sim_data,field_name,elem_dims)
 
         sens_array = SensorArrayPoint(sensor_data,
                                       t_field,
@@ -68,19 +48,20 @@ class SensorArrayFactory:
     @staticmethod
     def thermocouples_basic_errs(sim_data: mh.SimData,
                                  sensor_data: SensorData,
+                                 elem_dims: int,
                                  field_name: str = "temperature",
-                                 spat_dims: int = 3,
                                  errs_pc: float = 1.0
                                  ) -> SensorArrayPoint:
 
         sens_array = SensorArrayFactory.thermocouples_no_errs(sim_data,
                                                               sensor_data,
-                                                              field_name,
-                                                              spat_dims)
+                                                              elem_dims,
+                                                              field_name)
 
         err_int = basic_err_integrator(sens_array.get_measurement_shape(),
                                        sensor_data,
-                                       errs_pc)
+                                       sys_err_pc=errs_pc,
+                                       rand_err_pc=errs_pc)
 
         # Normal thermcouple amp = 5mV / K
         err_int._err_chain.append(ErrSysDigitisation(bits_per_unit=2**16/1000))
@@ -89,19 +70,22 @@ class SensorArrayFactory:
         sens_array.set_error_integrator(err_int)
         return sens_array
 
+
+
     @staticmethod
     def disp_sensors_no_errs(sim_data: mh.SimData,
-                            sensor_data: SensorData,
-                            field_name: str = "displacement",
-                            spat_dims: int = 3,
-                            ) -> SensorArrayPoint:
+                             sensor_data: SensorData,
+                             elem_dims: int,
+                             field_name: str,
+                             field_comps: tuple[str,...],
+                             ) -> SensorArrayPoint:
 
         descriptor = SensorDescriptorFactory.displacement_descriptor()
 
         disp_field = FieldVector(sim_data,
                                  field_name,
-                                 ('disp_x','disp_y'),
-                                 spat_dims)
+                                 field_comps,
+                                 elem_dims)
 
         sens_array = SensorArrayPoint(sensor_data,
                                       disp_field,
@@ -112,18 +96,21 @@ class SensorArrayFactory:
     @staticmethod
     def disp_sensors_basic_errs(sim_data: mh.SimData,
                                 sensor_data: SensorData,
-                                field_name: str = "displacement",
-                                spat_dims: int = 3,
-                                errs_pc: float = 1
+                                elem_dims: int,
+                                field_name: str,
+                                field_comps: tuple[str,...],
+                                errs_pc: float = 1.0,
                                 ) -> SensorArrayPoint:
 
         sens_array = SensorArrayFactory.disp_sensors_no_errs(sim_data,
-                                                            sensor_data,
-                                                            field_name,
-                                                            spat_dims)
+                                                             sensor_data,
+                                                             elem_dims,
+                                                             field_name,
+                                                             field_comps)
         err_int = basic_err_integrator(sens_array.get_measurement_shape(),
                                        sensor_data,
-                                       errs_pc)
+                                       sys_err_pc=errs_pc,
+                                       rand_err_pc=errs_pc)
         sens_array.set_error_integrator(err_int)
 
         return sens_array
@@ -131,23 +118,18 @@ class SensorArrayFactory:
     @staticmethod
     def strain_gauges_no_errs(sim_data: mh.SimData,
                               sensor_data: SensorData,
-                              field_name: str = "strain",
-                              spat_dims: int = 3
+                              elem_dims: int,
+                              field_name: str,
+                              norm_comps: tuple[str,...],
+                              dev_comps: tuple[str,...]
                               ) -> SensorArrayPoint:
-        descriptor = SensorDescriptorFactory.strain_descriptor(spat_dims)
-
-        if spat_dims == 2:
-            norm_components = ('strain_xx','strain_yy')
-            dev_components = ('strain_xy',)
-        else:
-            norm_components = ('strain_xx','strain_yy','strain_zz')
-            dev_components = ('strain_xy','strain_yz','strain_xz')
+        descriptor = SensorDescriptorFactory.strain_descriptor(elem_dims)
 
         strain_field = FieldTensor(sim_data,
-                                 field_name,
-                                 norm_components,
-                                 dev_components,
-                                 spat_dims)
+                                   field_name,
+                                   norm_comps,
+                                   dev_comps,
+                                   elem_dims)
 
         sens_array = SensorArrayPoint(sensor_data,
                                       strain_field,
@@ -159,19 +141,24 @@ class SensorArrayFactory:
     @staticmethod
     def strain_gauges_basic_errs(sim_data: mh.SimData,
                                 sensor_data: SensorData,
-                                field_name: str = "strain",
-                                spat_dims: int = 3,
+                                elem_dims: int,
+                                field_name: str,
+                                norm_comps: tuple[str,...],
+                                dev_comps: tuple[str,...],
                                 errs_pc: float = 1.0
                                 ) -> SensorArrayPoint:
 
         sens_array = SensorArrayFactory.strain_gauges_no_errs(sim_data,
                                                               sensor_data,
+                                                              elem_dims,
                                                               field_name,
-                                                              spat_dims)
+                                                              norm_comps,
+                                                              dev_comps)
 
         err_int = basic_err_integrator(sens_array.get_measurement_shape(),
                                        sensor_data,
-                                       errs_pc)
+                                       sys_err_pc=errs_pc,
+                                       rand_err_pc=errs_pc)
         sens_array.set_error_integrator(err_int)
 
         return sens_array
@@ -203,7 +190,7 @@ def basic_err_integrator(meas_shape: np.ndarray,
         a normal percentage random error.
     """
     err_chain = []
-    err_chain.append(ErrSysUniformPercent(-sys_err_pc,sys_err_pc))
+    err_chain.append(ErrSysUnifPercent(-sys_err_pc,sys_err_pc))
     err_chain.append(ErrRandNormPercent(rand_err_pc))
     err_int = ErrIntegrator(err_chain,sensor_data,meas_shape)
     return err_int

pyvale/sensorarraypoint.py

@@ -1,8 +1,8 @@
-# ================================================================================
+# ==============================================================================
 # pyvale: the python validation engine
 # License: MIT
 # Copyright (C) 2025 The Computer Aided Validation Team
-# ================================================================================
+# ==============================================================================
 
 import numpy as np
 from pyvale.field import IField
@@ -52,16 +52,15 @@ class SensorArrayPoint(ISensorArray):
     simulated physical fields quickly using finite element shape functions.
     """
 
-    __slots__ = ("field","descriptor","sensor_data","_truth","_measurements",
-                 "error_integrator")
+    __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
@@ -75,13 +74,13 @@ class SensorArrayPoint(ISensorArray):
             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._sensor_data = sensor_data
+        self._field = field
+        self._error_integrator = None
 
-        self.descriptor = SensorDescriptor()
+        self._descriptor = SensorDescriptor()
         if descriptor is not None:
-            self.descriptor = descriptor
+            self._descriptor = descriptor
 
         self._truth = None
         self._measurements = None
@@ -96,10 +95,10 @@ class SensorArrayPoint(ISensorArray):
         np.ndarray
             Sample times with shape: (num_time_steps,)
         """
-        if self.sensor_data.sample_times is None:
-            return self.field.get_time_steps()
+        if self._sensor_data.sample_times is None:
+            return self._field.get_time_steps()
 
-        return self.sensor_data.sample_times
+        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,
@@ -112,8 +111,8 @@ class SensorArrayPoint(ISensorArray):
             num_field_components,num_time_steps)
         """
 
-        return (self.sensor_data.positions.shape[0],
-                len(self.field.get_all_components()),
+        return (self._sensor_data.positions.shape[0],
+                len(self._field.get_all_components()),
                 self.get_sample_times().shape[0])
 
     def get_field(self) -> IField:
@@ -125,7 +124,7 @@ class SensorArrayPoint(ISensorArray):
         IField
             Reference to an `IField` interface.
         """
-        return self.field
+        return self._field
 
 
     def calc_truth_values(self) -> np.ndarray:
@@ -139,8 +138,8 @@ class SensorArrayPoint(ISensorArray):
             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)
+        self._truth = sample_field_with_sensor_data(self._field,
+                                                    self._sensor_data)
 
         return self._truth
 
@@ -170,7 +169,7 @@ class SensorArrayPoint(ISensorArray):
         err_int : ErrIntegrator
             Error integration object with a chain of user defined sensor errors.
         """
-        self.error_integrator = err_int
+        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
@@ -183,10 +182,10 @@ class SensorArrayPoint(ISensorArray):
             The accumulated sensor array parameters as a SensorData object.
             Returns None if no error integrator has been specified.
         """
-        if self.error_integrator is None:
+        if self._error_integrator is None:
             return None
 
-        return self.error_integrator.get_sens_data_accumulated()
+        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
@@ -199,10 +198,10 @@ class SensorArrayPoint(ISensorArray):
             ,num_field_components,num_time_steps). Returns None if no error
             integrator has been set.
         """
-        if self.error_integrator is None:
+        if self._error_integrator is None:
             return None
 
-        return self.error_integrator.get_errs_systematic()
+        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
@@ -215,10 +214,10 @@ class SensorArrayPoint(ISensorArray):
             ,num_field_components,num_time_steps). Returns None if no error
             integrator has been set.
         """
-        if self.error_integrator is None:
+        if self._error_integrator is None:
             return None
 
-        return self.error_integrator.get_errs_random()
+        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
@@ -231,10 +230,10 @@ class SensorArrayPoint(ISensorArray):
             ,num_field_components,num_time_steps). Returns None if no error
             integrator has been set.
         """
-        if self.error_integrator is None:
+        if self._error_integrator is None:
             return None
 
-        return self.error_integrator.get_errs_total()
+        return self._error_integrator.get_errs_total()
 
     def calc_measurements(self) -> np.ndarray:
         """Calculates a set of sensor measurements using the specified sensor
@@ -253,11 +252,11 @@ class SensorArrayPoint(ISensorArray):
             systematic errors if an error integrator is specified. shape=(
             num_sensors,num_field_components,num_time_steps).
         """
-        if self.error_integrator is None:
+        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())
+                self._error_integrator.calc_errors_from_chain(self.get_truth())
 
         return self._measurements
 

pyvale/sensordata.py

@@ -1,8 +1,8 @@
-# ================================================================================
+# ==============================================================================
 # pyvale: the python validation engine
 # License: MIT
 # Copyright (C) 2025 The Computer Aided Validation Team
-# ================================================================================
+# ==============================================================================
 
 from dataclasses import dataclass
 import numpy as np

pyvale/sensordescriptor.py

@@ -1,25 +1,75 @@
 
-# ================================================================================
+# ==============================================================================
 # 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
 
-#TODO: Docstrings
 
 @dataclass(slots=True)
 class SensorDescriptor:
-    name: str = 'Measured Value'
+    """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"
-    tag: str = 'S'
+    """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} "
@@ -37,6 +87,22 @@ class SensorDescriptor:
         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} "
@@ -54,47 +120,94 @@ class SensorDescriptor:
         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}')
+            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:
-        descriptor = SensorDescriptor()
-        descriptor.name = 'Temp.'
-        descriptor.symbol = 'T'
-        descriptor.units = r'^{\circ}C'
-        descriptor.tag = 'TC'
+        """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:
-        descriptor = SensorDescriptor()
-        descriptor.name = 'Disp.'
-        descriptor.symbol = 'u'
-        descriptor.units = r'm'
-        descriptor.tag = 'DS'
-        descriptor.components = ('x','y','z')
+        """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:
-        descriptor = SensorDescriptor()
-        descriptor.name = 'Strain'
-        descriptor.symbol = r'\varepsilon'
-        descriptor.units = r'-'
-        descriptor.tag = 'SG'
+        """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')
+            descriptor.components = ("xx","yy","xy")
         else:
-            descriptor.components = ('xx','yy','zz','xy','yz','xz')
+            descriptor.components = ("xx","yy","zz","xy","yz","xz")
 
         return descriptor

pyvale/sensortools.py

@@ -1,8 +1,8 @@
-# ================================================================================
+# ==============================================================================
 # pyvale: the python validation engine
 # License: MIT
 # Copyright (C) 2025 The Computer Aided Validation Team
-# ================================================================================
+# ==============================================================================
 
 import numpy as np
 import mooseherder as mh
@@ -115,7 +115,7 @@ def print_measurements(sens_array: ISensorArray,
         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(f"total errors = \n    {print_toterrs}")
 
     print()