pyvale 2026.1.1__cp311-cp311-manylinux_2_17_i686.manylinux2014_i686.whl

pyvale/sensorsim/sensordescriptor.py

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

pyvale/sensorsim/sensorfactory.py

@@ -0,0 +1,179 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
+"""
+This module contains helper functions that assemble common sensor array
+configurations without the user needing to configure all the sub-components
+themselves.
+"""
+
+
+import pyvale.mooseherder as mh
+from pyvale.sensorsim.fieldscalar import FieldScalar
+from pyvale.sensorsim.fieldvector import FieldVector
+from pyvale.sensorsim.fieldtensor import FieldTensor
+from pyvale.sensorsim.sensordescriptor import (DescriptorFactory,
+                                               SensorDescriptor)
+from pyvale.sensorsim.sensorspoint import SensorsPoint, SensorData
+from pyvale.sensorsim.enums import EDim
+
+
+class SensorFactory:
+    @staticmethod
+    def scalar_point(sim_data: mh.SimData,
+                     sensor_data: SensorData,
+                     comp_key: str,
+                     spatial_dims: EDim,
+                     descriptor: SensorDescriptor | None = None
+                     ) -> SensorsPoint:
+        """Helper function to assemble a scalar field point sensor array object
+        based on the input simulation data, sensor data and specified physical
+        field.
+
+        Parameters
+        ----------
+        sim_data : mh.SimData
+            Simulation data object containing the physical field that the v
+            virtual sensor array will sample.
+        sensor_data : SensorData
+            Sensor data object specifying the sensor array parameters such as
+            the sensor positions and sampling times.
+        comp_key : str
+            String key to acces the physical field that the sensors will be
+            applied to in the node_vars dictionary of the SimData object.
+        spatial_dims : EDim
+            Enumeration specifying the number of spatial dimensions the
+            simulation uses as .TWOD or .THREED. Used to determine the element
+            type for mesh-based data or the triangulation type for mesh free.
+        descriptor : SensorDescriptor | None, optional
+            Optional dataclass specifying the strings used to describe the
+            sensor array such as the name of the field to be sensed and the
+            units, by default None. If None then a default descriptor is
+            created.
+
+        Returns
+        -------
+        SensorArrayPoint
+            The assembled point sensor array object.
+        """
+        if descriptor is None:
+            descriptor = DescriptorFactory.scalar()
+
+        s_field = FieldScalar(sim_data,comp_key,spatial_dims)
+
+        sens_array = SensorsPoint(sensor_data,
+                                      s_field,
+                                      descriptor)
+        return sens_array
+
+    @staticmethod
+    def vector_point(sim_data: mh.SimData,
+                     sensor_data: SensorData,
+                     comp_keys: tuple[str,...],
+                     spatial_dims: EDim,
+                     descriptor: SensorDescriptor | None = None,
+                     ) -> SensorsPoint:
+        """"Helper function to assemble a vector field point sensor array object
+        based on the input simulation data, sensor data and specified physical
+        field.
+
+        Parameters
+        ----------
+        sim_data : mh.SimData
+            Simulation data object containing the physical field that the v
+            virtual sensor array will sample.
+        sensor_data : SensorData
+            Sensor data object specifying the sensor array parameters such as
+            the sensor positions and sampling times.
+        comp_keys : tuple[str,...]
+            Tuple of keys for the components of the vector field that will be
+            sampled by the virtual sensors. For example: displacement fields in
+            2D will have ("disp_x","disp_y").
+        spatial_dims : EDim
+            Enumeration specifying the number of spatial dimensions the
+            simulation uses as .TWOD or .THREED. Used to determine the element
+            type for mesh-based data or the triangulation type for mesh free.
+        descriptor : SensorDescriptor | None, optional
+            Optional dataclass specifying the strings used to describe the
+            sensor array such as the name of the field to be sensed and the
+            units, by default None. If None then a default descriptor is
+            created.
+
+        Returns
+        -------
+        SensorArrayPoint
+            The assembled point sensor array object.
+        """
+
+        if descriptor is None:
+            descriptor = DescriptorFactory.vector()
+
+        disp_field = FieldVector(sim_data,
+                                 comp_keys,
+                                 spatial_dims)
+        sens_array = SensorsPoint(sensor_data,
+                                      disp_field,
+                                      descriptor)
+        return sens_array
+
+    @staticmethod
+    def tensor_point(sim_data: mh.SimData,
+                     sensor_data: SensorData,
+                     norm_comp_keys: tuple[str,...],
+                     dev_comp_keys: tuple[str,...],
+                     spatial_dims: EDim,
+                     descriptor: SensorDescriptor | None = None,
+                     ) -> SensorsPoint:
+        """Helper function to assemble a tensor field point sensor array object
+        based on the input simulation data, sensor data and specified physical
+        field.
+
+        Parameters
+        ----------
+        sim_data : mh.SimData
+            Simulation data object containing the physical field that the v
+            virtual sensor array will sample.
+        sensor_data : SensorData
+            Sensor data object specifying the sensor array parameters such as
+            the sensor positions and sampling times.
+        norm_comp_keys : tuple[str,...]
+            Tuple of string keys for the normal components of the tensor field
+            in the node_vars dictionary of the SimData object. For example:
+            strain fields in 2D will typically have ("strain_xx","strain_yy").
+        dev_comp_keys : tuple[str,...]
+            Tuple of string keys for the deviatoric components of the tensor
+            field in the node_vars dictionary of the SimData object. For
+            example: strain fields in 2D will typicall have ("strain_xy",).
+        spatial_dims : EDim
+            Enumeration specifying the number of spatial dimensions the
+            simulation uses as .TWOD or .THREED. Used to determine the element
+            type for mesh-based data or the triangulation type for mesh free.
+        descriptor : SensorDescriptor | None, optional
+            Optional dataclass specifying the strings used to describe the
+            sensor array such as the name of the field to be sensed and the
+            units, by default None. If None then a default descriptor is
+            created.
+        Returns
+        -------
+        SensorArrayPoint
+            The assembled point sensor array object.
+        """
+
+        if descriptor is None:
+            descriptor = DescriptorFactory.tensor(spatial_dims)
+
+        strain_field = FieldTensor(sim_data,
+                                   norm_comp_keys,
+                                   dev_comp_keys,
+                                   spatial_dims)
+        sens_array = SensorsPoint(sensor_data,
+                                      strain_field,
+                                      descriptor)
+
+        return sens_array
+
+
+