pyvale 2025.5.3__cp311-cp311-win_amd64.whl

pyvale/fieldconverter.py

@@ -0,0 +1,351 @@
+# ==============================================================================
+# 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 mooseherder as mh
+
+def simdata_to_pyvista(sim_data: mh.SimData,
+                        components: tuple[str,...] | None,
+                        elem_dims: int
+                        ) -> tuple[pv.UnstructuredGrid,pv.UnstructuredGrid]:
+    """Converts the mesh and field data in a `SimData` object into a pyvista
+    UnstructuredGrid for sampling (interpolating) the data and visualisation.
+
+    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 : int
+        Number of spatial dimensions (2 or 3) used to determine the element
+        types in the mesh from the number of nodes per element.
+
+    Returns
+    -------
+    tuple[pv.UnstructuredGrid,pv.UnstructuredGrid]
+        The first UnstructuredGrid has the field components attached as dataset
+        arrays. The second has no field data attached for visualisation.
+    """
+    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,elem_dims)
+        assert this_cell_type is not None, ("Cell type with dimension " +
+            f"{elem_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)
+    pv_grid_vis = pv.UnstructuredGrid(cells, cell_types, points)
+
+    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,pv_grid_vis)
+
+
+def scale_length_units(scale: float,
+                       sim_data: mh.SimData,
+                       disp_comps: tuple[str,...] | None = None,
+                       ) -> mh.SimData:
+    """Used to scale the length units of a simulation. Commonly used to convert
+    SI units to mm for use with visualisation tools and rendering algorithms.
+
+    Parameters
+    ----------
+    scale : float
+        Scale multiplier used to scale the coordinates and displacement fields
+        if specified.
+    sim_data : mh.SimData
+        Simulation dataclass that will be scaled.
+    disp_comps : tuple[str,...] | None, optional
+        Tuple of string keys for the displacement keys to be scaled, by default
+        None. If None then the displacements are not scaled.
+
+    Returns
+    -------
+    mh.SimData
+        Simulation dataclass with scaled length units.
+    """
+    sim_data.coords = sim_data.coords*scale
+
+    if disp_comps is not None:
+        for cc in disp_comps:
+            sim_data.node_vars[cc] = sim_data.node_vars[cc]*scale
+
+    return sim_data
+
+
+# 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
+
+
+def _get_pyvista_cell_type(nodes_per_elem: int, spat_dim: int) -> 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 : int
+        Number of spatial dimensions in the mesh (2 or 3).
+
+    Returns
+    -------
+    CellType | None
+        Enumeration describing the element type in pyvista.
+    """
+    cell_type = None
+
+    if 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
+    else:
+        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
+
+
+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
+
+
+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.")

pyvale/fieldsampler.py

@@ -0,0 +1,111 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
+import numpy as np
+import pyvista as pv
+from pyvale.field import IField
+from pyvale.sensordata import SensorData
+from pyvale.integratorfactory import build_spatial_averager
+
+
+def sample_field_with_sensor_data(field: IField, sensor_data: SensorData
+                                  ) -> np.ndarray:
+    """Samples (interpolates) an `IField` object using the parameters specified
+    in the `SensorData` object.
+
+    Parameters
+    ----------
+    field : IField
+        The simulated physical field that the sensors will samples from. This is
+        normally a `FieldScalar`, `FieldVector` or `FieldTensor`.
+    sensor_data : SensorData
+        Contains sensor array parameters including: number of sensors, positions
+        and sample times. See the `SensorData` class for more information.
+
+    Returns
+    -------
+    np.ndarray
+        Array of sampled sensor measurements with shape=(num_sensors,
+        num_field_components,num_time_steps).
+    """
+    if sensor_data.spatial_averager is None:
+        return field.sample_field(sensor_data.positions,
+                                  sensor_data.sample_times,
+                                  sensor_data.angles)
+
+    spatial_integrator = build_spatial_averager(field,sensor_data)
+    return spatial_integrator.calc_averages()
+
+
+# NOTE: sampling outside the bounds of the sample returns a value of 0
+def sample_pyvista_grid(components: tuple[str,...],
+                        pyvista_grid: pv.UnstructuredGrid,
+                        sim_time_steps: np.ndarray,
+                        points: np.ndarray,
+                        sample_times: np.ndarray | None = None
+                        ) -> np.ndarray:
+    """Function for sampling (interpolating) a pyvista grid object containing
+    simulated field data. The pyvista sample method uses VTK to perform the
+    spatial interpolation using the element shape functions. If the sampling
+    time steps are not the same as the simulation time then a linear
+    interpolation over time is performed using numpy.
+
+    NOTE: sampling outside the mesh bounds of the sample returns a value of 0.
+
+    Parameters
+    ----------
+    components : tuple[str,...]
+        String keys for the components to be sampled in the pyvista grid object.
+        Useful for only interpolating the field components of interest for speed
+        and memory reduction.
+    pyvista_grid : pv.UnstructuredGrid
+        Pyvista grid object containing the simulation mesh and the components of
+        the physical field that will be sampled.
+    sim_time_steps : np.ndarray
+        Simulation time steps corresponding to the fields in the pyvista grid
+        object.
+    points : np.ndarray
+        Coordinates of the points at which to sample the pyvista grid object.
+        shape=(num_points,3) where the columns are the X, Y and Z coordinates of
+        the sample points in simulation world coordintes.
+    sample_times : np.ndarray | None, optional
+        Array of time steps at which to sample the pyvista grid. If None then no
+        temporal interpolation is performed and the sample times are assumed to
+        be the simulation time steps.
+
+    Returns
+    -------
+    np.ndarray
+        Array of sampled sensor measurements with shape=(num_sensors,
+        num_field_components,num_time_steps).
+    """
+    pv_points = pv.PolyData(points)
+    sample_data = pv_points.sample(pyvista_grid)
+
+    n_comps = len(components)
+    (n_sensors,n_time_steps) = np.array(sample_data[components[0]]).shape
+    sample_at_sim_time = np.empty((n_sensors,n_comps,n_time_steps))
+
+    for ii,cc in enumerate(components):
+        sample_at_sim_time[:,ii,:] = np.array(sample_data[cc])
+
+    if sample_times is None:
+        return sample_at_sim_time
+
+    def sample_time_interp(x):
+        return np.interp(sample_times, sim_time_steps, x)
+
+    n_time_steps = sample_times.shape[0]
+    sample_at_spec_time = np.empty((n_sensors,n_comps,n_time_steps))
+
+    for ii,cc in enumerate(components):
+        sample_at_spec_time[:,ii,:] = np.apply_along_axis(sample_time_interp,-1,
+                                                    sample_at_sim_time[:,ii,:])
+
+    return sample_at_spec_time
+
+
+

pyvale/fieldscalar.py

@@ -0,0 +1,166 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
+import numpy as np
+import pyvista as pv
+from scipy.spatial.transform import Rotation
+import mooseherder as mh
+
+from pyvale.field import IField
+from pyvale.fieldconverter import simdata_to_pyvista
+from pyvale.fieldsampler import sample_pyvista_grid
+
+
+class FieldScalar(IField):
+    """Class for sampling (interpolating) scalar fields from simulations to
+    provide sensor values at specified locations and times.
+
+    Implements the `IField` interface.
+    """
+    __slots__ = ("_field_key","_elem_dims","_sim_data","_pyvista_grid",
+                 "_pyvista_vis")
+
+    def __init__(self,
+                 sim_data: mh.SimData,
+                 field_key: str,
+                 elem_dims: int) -> None:
+        """
+        Parameters
+        ----------
+        sim_data : mh.SimData
+            Simulation data object containing the mesh and field to interpolate.
+        field_key : str
+            String key for the scalar field component in the `SimData` object.
+        elem_dims : int
+            Number of spatial dimensions (2 or 3) used for identifying element
+            types.
+        """
+
+        self._field_key = field_key
+        self._elem_dims = elem_dims
+
+        self._sim_data = sim_data
+        (self._pyvista_grid,self._pyvista_vis) = simdata_to_pyvista(
+            self._sim_data,
+            (self._field_key,),
+            self._elem_dims
+        )
+
+    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 by setting a different `SimData`.
+
+        Parameters
+        ----------
+        sim_data : mh.SimData
+            Mooseherder SimData object. Contains a mesh and a simulated
+            physical field.
+        """
+        self._sim_data = sim_data
+        (self._pyvista_grid,self._pyvista_vis) = simdata_to_pyvista(
+            sim_data,
+            (self._field_key,),
+            self._elem_dims
+        )
+
+    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.
+        """
+        return self._sim_data
+
+    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,)
+        """
+        return self._sim_data.time
+
+    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.
+        """
+        return self._pyvista_vis
+
+    def get_all_components(self) -> tuple[str, ...]:
+        """Gets the string key for the component of the physical field. A scalar
+        field only has a single component so a tuple of length 1 is returned.
+
+        Returns
+        -------
+        tuple[str,...]
+            Tuple containing the string key for the physical field.
+        """
+        return (self._field_key,)
+
+    def get_component_index(self, comp: 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.
+
+        Parameters
+        ----------
+        component : str
+            String key for the field component (e.g. 'temperature' or 'disp_x').
+
+        Returns
+        -------
+        int
+            Index for the selected field component
+        """
+        return 0 # scalar fields only have one component!
+
+    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).
+        """
+        return sample_pyvista_grid((self._field_key,),
+                                self._pyvista_grid,
+                                self._sim_data.time,
+                                points,
+                                times)
+