pyvale 2026.1.1__cp311-cp311-manylinux_2_17_i686.manylinux2014_i686.whl

pyvale/sensorsim/experimentstats.py

@@ -0,0 +1,115 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
+from dataclasses import dataclass
+import numpy as np
+
+@dataclass(slots=True)
+class ExpSimStats:
+    """Dataclass holding summary statistics for a series of simulated
+    experiments produced using the experiment simulator. All summary statistics
+    are calculated over the 'experiments' dimension of the measurements array so
+    the arrays of statistics have the shape=(n_sensors,n_field_comps,
+    n_time_steps).
+    """
+
+    mean: np.ndarray | None = None
+    """Mean of each sensors measurement for the given field component and time
+    step as an array with shape=(n_sensors,n_field_comps,n_time_steps).
+    """
+
+    std: np.ndarray | None = None
+    """Standard deviation of the sensor measurements for the given field
+    component and time step as an array with shape=(n_sensors,n_field_comps,
+    n_time_steps)
+    """
+
+    max: np.ndarray | None = None
+    """Maximum of the sensor measurements for the given field component and time
+    step as an array with shape=(n_sensors,n_field_comps,n_time_steps)
+    """
+
+    min: np.ndarray | None = None
+    """Minmum of the sensor measurements for the given field component and time
+    step as an array with shape=(n_sensors,n_field_comps,n_time_steps)
+    """
+
+    med: np.ndarray | None = None
+    """Median  of the sensor measurements for the given field component and time
+    step as an array with shape=(n_sensors,n_field_comps,n_time_steps)
+    """
+
+    q25: np.ndarray | None = None
+    """Lower 25% quantile of the sensor measurements for the given field
+    component and time step as an array with shape=(n_sensors,n_field_comps,
+    n_time_steps)
+    """
+
+    q75: np.ndarray | None = None
+    """Upper 75% quantile of the sensor measurements for the given field
+    component and time step as an array with shape=(n_sensors,n_field_comps,
+    n_time_steps)
+    """
+
+    mad: np.ndarray | None = None
+    """Median absolute deviation of the sensor measurements for the given field
+    component and time step as an array with shape=(n_sensors,n_field_comps,
+    n_time_steps)
+    """
+
+
+def calc_exp_sim_stats(exp_data: dict[tuple[str,...],np.ndarray]
+                          ) -> dict[tuple[str,...],ExpSimStats]:
+    """Calculates summary statistics over all virtual experiments for all
+    virtual sensor arrays.
+
+    Returns
+    -------
+    dict[tuple[str,...],ExperimentStats]
+        Dictionary of summary statistics data classes for the virtual
+        experiments. 
+    """
+
+    # dict[tuple[str,..],shape=(n_exps,n_sens,n_comps,n_time_steps)]
+    exp_stats: dict[tuple[str,...],ExpSimStats] = {}
+
+    for kk,dd in exp_data.items():
+        # f = float
+        if dd.dtype.kind == 'f':
+            exp_stats[kk] = calc_sensor_array_stats(dd)
+        # U = unicode string, S = byte string
+        elif dd.dtype.kind == 'U' or dd.dtype.kind == 'S':
+            exp_stats[kk] = dd
+
+        # Implicitly remove anything that we don't expect: integers, objects etc
+
+    # dict[tuple[str,..],shape=(n_exps,n_sens,n_comps,n_time_steps)]
+    return exp_stats
+
+
+def calc_sensor_array_stats(exp_data: np.ndarray) -> ExpSimStats:
+    """Calculates summary statistics for a specific sensor array over all
+    virual experiments.
+
+    Returns
+    -------
+    ExperimentStats
+        Summary statistics data class for the sensor array.
+    """
+
+    axis: int = 0
+    exp_stats = ExpSimStats(
+        max = np.max(exp_data,axis=axis),
+        min = np.min(exp_data,axis=axis),
+        mean = np.mean(exp_data,axis=axis),
+        std = np.std(exp_data,axis=axis),
+        med = np.median(exp_data,axis=axis),
+        q25 = np.quantile(exp_data,0.25,axis=axis),
+        q75 = np.quantile(exp_data,0.75,axis=axis),
+        mad = np.median(np.abs(exp_data -
+            np.median(exp_data,axis=axis,keepdims=True)),axis=axis),
+    )
+    return exp_stats

pyvale/sensorsim/field.py

@@ -0,0 +1,127 @@
+# ==============================================================================
+# 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 scipy.spatial.transform import Rotation
+import pyvista as pv
+import pyvale.mooseherder as mh
+
+
+class IField(ABC):
+    """Interface (abstract base class) for sampling (interpolating) physical
+    fields from simulations to provide sensor values at specified locations and
+    times.
+    """
+
+    @abstractmethod
+    def set_sim_data(self,sim_data: mh.SimData) -> None:
+        """Sets the SimData object that will be interpolated to obtain sensor 
+        values. The purpose of this is to be able to apply the same sensor array 
+        to an array of different simulations.
+
+        Parameters
+        ----------
+        sim_data : mh.SimData
+            Mooseherder SimData object. Contains a mesh and a simulated
+            physical field.
+        """
+
+    @abstractmethod
+    def get_sim_data(self) -> mh.SimData:
+        """Gets the simulation data object associated with this field. Used by 
+        pyvale visualisation tools to display simulation data with simulated 
+        sensor values.
+
+        Returns
+        -------
+        mh.SimData
+            Mooseherder SimData object. Contains a mesh and a simulated
+            physical field.
+        """
+
+    @abstractmethod
+    def get_time_steps(self) -> np.ndarray:
+        """Gets a 1D array of time steps from the simulation data.
+
+        Returns
+        -------
+        np.ndarray
+            1D array of simulation time steps. shape=(num_time_steps,)
+        """
+
+    @abstractmethod
+    def get_visualiser(self) -> pv.UnstructuredGrid:
+        """Gets a pyvista unstructured grid object for visualisation purposes.
+
+        Returns
+        -------
+        pv.UnstructuredGrid
+            Pyvista unstructured grid object containing only a mesh without any
+            physical field data attached.
+        """
+
+    @abstractmethod
+    def get_all_components(self) -> tuple[str,...]:
+        """Gets the string keys for the component of the physical field. For
+        example: a scalar field might just have ('temperature',) whereas a
+        vector field might have ('disp_x','disp_y','disp_z').
+
+        Returns
+        -------
+        tuple[str,...]
+            Tuple containing the string keys for all components of the physical
+            field.
+        """
+
+    @abstractmethod
+    def get_component_index(self,comp_key: str) -> int:
+        """Gets the index for a component of the physical field. Used for
+        getting the index of a component in the sensor measurement array based 
+        on its string key.
+
+        Parameters
+        ----------
+        comp_key : str
+            String key for the field component (e.g. 'temperature' or 'disp_x').
+
+        Returns
+        -------
+        int
+            Index for the selected field component.
+        """
+
+    @abstractmethod
+    def sample_field(self,
+                    points: np.ndarray,
+                    times: np.ndarray | None = None,
+                    angles: tuple[Rotation,...] | None = None,
+                    ) -> np.ndarray:
+        """Samples (interpolates) the simulation field at the specified
+        positions, times, and angles.
+
+        Parameters
+        ----------
+        points : np.ndarray
+            Spatial points to be sampled with the rows indicating the point
+            number of the columns indicating the X,Y and Z coordinates.
+        times : np.ndarray | None, optional
+            Times to sample the underlying simulation. If None then the
+            simulation time steps are used and no temporal interpolation is
+            performed, by default None.
+        angles : tuple[Rotation,...] | None, optional
+            Angles to rotate the sampled values into with rotations specified
+            with respect to the simulation world coordinates. If a single
+            rotation is specified then all points are assumed to have the same
+            angle and are batch processed for speed. If None then no rotation is
+            performed, by default None.
+
+        Returns
+        -------
+        np.ndarray
+            An array of sampled (interpolated) values with the following
+            dimensions: shape=(num_points,num_components,num_time_steps).
+        """

pyvale/sensorsim/fieldconverter.py

@@ -0,0 +1,378 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
+"""
+This module provides functions for manipulating simulation data objects to be
+compatible with the underlying machinery of pyvale.
+"""
+
+import numpy as np
+import pyvista as pv
+from pyvista import CellType
+import pyvale.mooseherder as mh
+from pyvale.sensorsim.enums import EDim
+
+
+def simdata_to_pyvista_interp(sim_data: mh.SimData,
+                              components: tuple[str,...] | None,
+                              spatial_dims: EDim,
+                              ) -> pv.UnstructuredGrid:
+    """Converts the mesh and field data in a `SimData` object into a pyvista
+    UnstructuredGrid for interpolating the data.
+
+    Parameters
+    ----------
+    sim_data : mh.SimData
+        Object containing a mesh and associated field data from a simulation.
+    components : tuple[str,...] | None
+        String keys for the components of the field to extract from the
+        simulation data.
+    elem_dim : EDim
+        Number of spatial dimensions in the simulation (TWOD or THREED).  For 
+        mesh-based data this is used to determine the element type and 
+        distinguish between 4 node quads in 2D and 4 node tets in 3D. For point
+        cloud data this determines if 2D or 3D Delaunay triangulation is used.
+
+    Returns
+    -------
+    pv.UnstructuredGrid
+        As pyvista grid with attached field data to allow for interpolation on
+        the mesh using the element shape functions.
+    """
+
+    pv_grid = _gen_pyvista_grid(sim_data,spatial_dims)
+
+    if components is not None and sim_data.node_vars is not None:
+        for cc in components:
+            pv_grid[cc] = sim_data.node_vars[cc]
+
+    return pv_grid
+
+
+def simdata_to_pyvista_vis(sim_data: mh.SimData,
+                           spatial_dims: EDim,
+                           ) -> pv.UnstructuredGrid | pv.PolyData:
+    """Converts the mesh and field data in a `SimData` object into a pyvista
+    UnstructuredGrid or PolyData object for visualisation.
+
+    Parameters
+    ----------
+    sim_data : mh.SimData
+        Object containing a mesh and associated field data from a simulation.
+    elem_dim : EDim
+        Number of spatial dimensions in the simulation (TWOD or THREED).  For 
+        mesh-based data this is used to determine the element type and 
+        distinguish between 4 node quads in 2D and 4 node tets in 3D. For point
+        cloud data this determines if 2D or 3D Delaunay triangulation is used.
+
+    Returns
+    -------
+    pv.UnstructuredGrid | pv.PolyData
+        A pyvista unstructured grid or poly data object that has no field data
+        attached for visualisation purposes.
+    """
+    if sim_data.connect is None:
+        return pv.PolyData(sim_data.coords)
+
+    return _gen_pyvista_grid(sim_data,spatial_dims)
+
+
+
+def _gen_pyvista_grid(sim_data: mh.SimData,
+                      spatial_dims: int) -> pv.UnstructuredGrid:
+    """Helper function for generating a blank pyvista unstructure grid mesh from
+    a SimData object.
+
+    Parameters
+    ----------
+    sim_data : mh.SimData
+        Object containing a mesh and associated field data from a simulation.
+    elem_dim : EDim
+        Number of spatial dimensions in the simulation (TWOD or THREED).  For 
+        mesh-based data this is used to determine the element type and 
+        distinguish between 4 node quads in 2D and 4 node tets in 3D. For point
+        cloud data this determines if 2D or 3D Delaunay triangulation is used.
+
+    Returns
+    -------
+    pv.UnstructuredGrid
+        A pyvista unstructured grid that has no field data attached.
+    """
+    flat_connect = np.array([],dtype=np.int64)
+    cell_types = np.array([],dtype=np.int64)
+
+    for cc in sim_data.connect:
+        # NOTE: need the -1 here to make element numbers 0 indexed!
+        this_connect = np.copy(sim_data.connect[cc])-1
+        (nodes_per_elem,n_elems) = this_connect.shape
+
+        this_cell_type = _get_pyvista_cell_type(nodes_per_elem,spatial_dims)
+        assert this_cell_type is not None, ("Cell type with dimension " +
+            f"{spatial_dims} and {nodes_per_elem} nodes per element not " +
+            "recognised.")
+
+        # VTK and exodus have different winding for 3D higher order quads
+        this_connect = _exodus_to_pyvista_connect(this_cell_type,this_connect)
+
+        this_connect = this_connect.T.flatten()
+        idxs = np.arange(0,n_elems*nodes_per_elem,nodes_per_elem,dtype=np.int64)
+
+        this_connect = np.insert(this_connect,idxs,nodes_per_elem)
+
+        cell_types = np.hstack((cell_types,np.full(n_elems,this_cell_type)))
+        flat_connect = np.hstack((flat_connect,this_connect),dtype=np.int64)
+
+    cells = flat_connect
+
+    points = sim_data.coords
+    pv_grid = pv.UnstructuredGrid(cells, cell_types, points)
+    return pv_grid
+
+
+# TODO: make this work for sim_data with multiple connectivity
+def extract_surf_mesh(sim_data: mh.SimData) -> mh.SimData:
+    """Extracts a surface mesh from a 3D simulation dataclass. Useful for
+    limiting the memory required for analysing sensors that only measure surface
+    fields. This function currently supports:
+        - A single connectivity table
+        - Higher order retrahedral and hexahedral elements (but not wedges or
+          pyramids)
+
+    NOTE: this function returns the surface mesh with element nodal winding
+    consistent with th exodus output format.
+
+    Parameters
+    ----------
+    sim_data : mh.SimData
+        Simulation dataclass containing the 3D mesh from which the surface mesh
+        is to be extracted.
+
+    Returns
+    -------
+    mh.SimData
+        Simulation data class containing the data for the surface mesh.
+    """
+
+    # NOTE: need to fix exodus 1 indexing for now and put it back at the end
+    # shape=(nodes_per_elem,num_elems)
+    connect = np.copy(sim_data.connect["connect1"])-1
+    num_elems = connect.shape[1]
+
+    assert "connect2" not in sim_data.connect, \
+        "Multiple connectivity tables not supported yet."
+
+    # Mapping of node numbers to faces for each element face
+    face_map = _get_surf_map(nodes_per_elem=connect.shape[0])
+    faces_per_elem = face_map.shape[0]
+    nodes_per_face = face_map.shape[1]
+
+    # shape=(faces_per_elem,nodes_per_face,num_elems)
+    faces_wound = connect[face_map,:]
+    # shape=(num_elems,faces_per_elem,nodes_per_face)
+    faces_wound = faces_wound.transpose((2,0,1))
+
+    # Create an array of all faces with shape=(total_faces,nodes_per_face)
+    faces_total = faces_per_elem*num_elems
+    faces_flat_wound = faces_wound.reshape((faces_total,nodes_per_face))
+    # Sort the rows so nodes are in the same order when comparing them
+    faces_flat_sorted = np.copy(np.sort(faces_flat_wound,axis=1))
+
+    # Count each unique face in the list of faces, faces that appear only once
+    # must be external faces
+    (_,
+     faces_unique_inds,
+     faces_unique_counts) = np.unique(faces_flat_sorted,
+                                      axis=0,
+                                      return_counts=True,
+                                      return_index=True)
+
+    # Indices of the external faces in faces_flat
+    faces_ext_inds_in_unique = np.where(faces_unique_counts==1)[0]
+
+    # shape=(num_ext_faces,nodes_per_face)
+    faces_ext_inds = faces_unique_inds[faces_ext_inds_in_unique]
+
+    faces_ext_wound = faces_flat_wound[faces_ext_inds]
+
+    faces_coord_inds = np.unique(faces_ext_wound.flatten())
+    faces_coords = np.copy(sim_data.coords[faces_coord_inds])
+
+    faces_shape = faces_ext_wound.shape
+    faces_ext_wound_flat = faces_ext_wound.flatten()
+    faces_ext_remap_flat = np.copy(faces_ext_wound_flat)
+
+    # Remap coordinates in the connectivity to match the trimmed list of coords
+    # that belong to the external faces
+    for mm,cc in enumerate(faces_coord_inds):
+        if mm == cc:
+            continue
+
+        ind_to_map = np.where(faces_ext_wound_flat == cc)[0]
+        faces_ext_remap_flat[ind_to_map] = mm
+
+    faces_ext_remap = faces_ext_remap_flat.reshape(faces_shape)
+    faces_ext_remap = faces_ext_remap + 1 # back to exodus 1 index
+
+    # Now we build the SimData object and slice out the node and element
+    # variables using the coordinate indexing.
+    face_data = mh.SimData(coords=faces_coords,
+                           connect={"connect1":faces_ext_remap.T},
+                           time=sim_data.time)
+
+    if sim_data.node_vars is not None:
+        face_data.node_vars = {}
+        for nn in sim_data.node_vars:
+            face_data.node_vars[nn] = sim_data.node_vars[nn][faces_coord_inds,:]
+
+    if sim_data.elem_vars is not None:
+        face_data.elem_vars = {}
+        for ee in sim_data.node_vars:
+            face_data.elem_vars[ee] = sim_data.elem_vars[ee][faces_coord_inds,:]
+
+    return face_data
+
+#TODO: make this support triangular prisms in 3D.
+def _get_pyvista_cell_type(nodes_per_elem: int, 
+                           spat_dim: EDim) -> CellType | None:
+    """Helper function to identify the pyvista element type in the mesh.
+
+    Parameters
+    ----------
+    nodes_per_elem : int
+        Number of nodes per element.
+    spat_dim : EDim
+        Number of spatial dimensions in the simulation (TWOD or THREED).
+
+    Returns
+    -------
+    CellType | None
+        Enumeration describing the element type in pyvista.
+    """
+    cell_type = None
+
+    if spat_dim == EDim.TWOD or spat_dim == 2:
+        if nodes_per_elem == 4:
+            cell_type = CellType.QUAD
+        elif nodes_per_elem == 3:
+            cell_type = CellType.TRIANGLE
+        elif nodes_per_elem == 6:
+            cell_type = CellType.QUADRATIC_TRIANGLE
+        elif nodes_per_elem == 7:
+            cell_type = CellType.BIQUADRATIC_TRIANGLE
+        elif nodes_per_elem == 8:
+            cell_type = CellType.QUADRATIC_QUAD
+        elif nodes_per_elem == 9:
+            cell_type = CellType.BIQUADRATIC_QUAD
+    elif spat_dim == EDim.THREED or spat_dim == 3:
+        if nodes_per_elem == 8:
+            cell_type =  CellType.HEXAHEDRON
+        elif nodes_per_elem == 4:
+            cell_type = CellType.TETRA
+        elif nodes_per_elem == 10:
+            cell_type = CellType.QUADRATIC_TETRA
+        elif nodes_per_elem == 20:
+            cell_type = CellType.QUADRATIC_HEXAHEDRON
+        elif nodes_per_elem == 27:
+            cell_type = CellType.TRIQUADRATIC_HEXAHEDRON
+
+    return cell_type
+
+#TODO: make this support triangular prisms in 3D.
+def _exodus_to_pyvista_connect(cell_type: CellType,
+                               connect: np.ndarray) -> np.ndarray:
+    """Helper function that specifies the nodal winding map for higher order
+    tet and hex elements between the exodus output format and pyvista (VTK).
+
+    Parameters
+    ----------
+    cell_type : CellType
+        pyvista (VTK) cell type enumeration.
+    connect : np.ndarray
+        Input connectivity table in exodus winding format.
+        shape=(nodes_per_elem,num_elems)
+
+    Returns
+    -------
+    np.ndarray
+        Output connectivity table in pyvista (VTK) format.
+        shape=(nodes_per_elem,num_elems)
+    """
+    copy_connect = np.copy(connect)
+
+    # NOTE: it looks like VTK does not support TET14
+    # VTK and exodus have different winding for 3D higher order quads
+    if cell_type == CellType.QUADRATIC_HEXAHEDRON:
+        connect[12:16,:] = copy_connect[16:20,:]
+        connect[16:20,:] = copy_connect[12:16,:]
+    elif cell_type == CellType.TRIQUADRATIC_HEXAHEDRON:
+        connect[12:16,:] = copy_connect[16:20,:]
+        connect[16:20,:] = copy_connect[12:16,:]
+        connect[20:24,:] = copy_connect[23:27,:]
+        connect[24,:] = copy_connect[21,:]
+        connect[25,:] = copy_connect[22,:]
+        connect[26,:] = copy_connect[20,:]
+
+    return connect
+
+#TODO: make this support triangular prisms in 3D.
+def _get_surf_map(nodes_per_elem: int) -> np.ndarray:
+    """Helper function specifying the mapping from 3D tet and hex elements to
+    the individual faces consistent with the exodus output format.
+
+    Parameters
+    ----------
+    nodes_per_elem : int
+        Number of nodes per element.
+
+    Returns
+    -------
+    np.ndarray
+        Array of indices mapping the nodes to faces with shape=(num_faces,n
+        odes_per_face)
+
+    Raises
+    ------
+    ValueError
+        Element type is not supported.
+    """
+    if nodes_per_elem == 4: # TET4
+       return np.array(((0,1,2),
+                        (0,3,1),
+                        (0,2,3),
+                        (1,3,2)))
+
+    if nodes_per_elem == 8: # HEX8
+        return np.array(((0,1,2,3),
+                         (0,3,7,4),
+                         (4,7,6,5),
+                         (1,5,6,2),
+                         (0,4,5,1),
+                         (2,6,7,3)))
+
+    if nodes_per_elem == 10: # TET10
+       return np.array(((0,1,2,4,5,6),
+                        (0,3,1,4,8,7),
+                        (0,2,3,6,9,7),
+                        (1,3,2,8,9,5)))
+
+    if nodes_per_elem == 20: # HEX20
+        return np.array(((0,1,2,3,8,9,10,11),
+                         (0,3,7,4,11,15,19,12),
+                         (4,7,6,5,19,18,17,16),
+                         (1,5,6,2,13,17,14,9),
+                         (0,4,5,1,12,16,13,8),
+                         (2,6,7,3,14,18,15,10)))
+
+    if nodes_per_elem == 27: # HEX27
+        return np.array(((0,1,2,3,8,9,10,11,21),
+                         (0,3,7,4,11,15,19,12,23),
+                         (4,7,6,5,19,18,17,16,22),
+                         (1,5,6,2,13,17,14,9,24),
+                         (0,4,5,1,12,16,13,8,25),
+                         (2,6,7,3,14,18,15,10,26)))
+
+    raise ValueError("Number of nodes does not match a 3D element type for " \
+        "surface extraction.")