pyvale 2025.4.0__py3-none-any.whl

pyvale/core/experimentsimulator.py

@@ -0,0 +1,99 @@
+"""
+================================================================================
+pyvale: the python validation engine
+License: MIT
+Copyright (C) 2025 The Computer Aided Validation Team
+================================================================================
+"""
+from dataclasses import dataclass
+import numpy as np
+from pyvale.core.sensorarray import ISensorArray
+import mooseherder as mh
+
+# NOTE: This module is a feature under developement.
+
+@dataclass(slots=True)
+class ExperimentStats:
+    """Dataclass holding summary statistics for a series of simulated
+    experiments.
+    """
+    mean: np.ndarray | None = None
+    std: np.ndarray | None = None
+    cov: np.ndarray | None = None
+    max: np.ndarray | None = None
+    min: np.ndarray | None = None
+    med: np.ndarray | None = None
+    q25: np.ndarray | None = None
+    q75: np.ndarray | None = None
+    mad: np.ndarray | None = None
+
+
+class ExperimentSimulator:
+    """An experiment simulator for running monte-carlo analysis by applying a
+    list of sensor arrays to a list of simulations over a given number of user
+    defined experiments. Calculates summary statistics for each sensor array
+    applied to each simulation.
+    """
+    __slots__ = ("sim_list","sensor_arrays","num_exp_per_sim","_exp_data",
+                 "_exp_stats")
+
+    def __init__(self,
+                 sim_list: list[mh.SimData],
+                 sensor_arrays: list[ISensorArray],
+                 num_exp_per_sim: int
+                 ) -> None:
+
+        self.sim_list = sim_list
+        self.sensor_arrays = sensor_arrays
+        self.num_exp_per_sim = num_exp_per_sim
+        self._exp_data = [None]*len(self.sensor_arrays)
+        self._exp_stats = [None]*len(self.sensor_arrays)
+
+    def get_data(self) -> list[np.ndarray | None]:
+        return self._exp_data
+
+    def get_stats(self) -> list[np.ndarray | None]:
+        return self._exp_stats
+
+    def run_experiments(self) -> list[np.ndarray]:
+        n_sims = len(self.sim_list)
+        # shape=list[n_arrays](n_sims,n_exps,n_sens,n_comps,n_time_steps)
+        self._exp_data = [None]*len(self.sensor_arrays)
+
+        for ii,aa in enumerate(self.sensor_arrays):
+            meas_array = np.zeros((n_sims,self.num_exp_per_sim)+
+                                aa.get_measurement_shape())
+
+            for jj,ss in enumerate(self.sim_list):
+                aa.get_field().set_sim_data(ss)
+
+                for ee in range(self.num_exp_per_sim):
+                    meas_array[jj,ee,:,:,:] = aa.calc_measurements()
+
+            self._exp_data[ii] = meas_array
+
+        return self._exp_data
+
+
+    def calc_stats(self) -> list[ExperimentStats]:
+        # shape=list[n_arrays](n_sims,n_exps,n_sens,n_comps,n_time_steps)
+        self._exp_stats = [None]*len(self.sensor_arrays)
+        for ii,_ in enumerate(self.sensor_arrays):
+            array_stats = ExperimentStats()
+            array_stats.max = np.max(self._exp_data[ii],axis=1)
+            array_stats.min = np.min(self._exp_data[ii],axis=1)
+            array_stats.mean = np.mean(self._exp_data[ii],axis=1)
+            array_stats.std = np.std(self._exp_data[ii],axis=1)
+            array_stats.med = np.median(self._exp_data[ii],axis=1)
+            array_stats.q25 = np.quantile(self._exp_data[ii],0.25,axis=1)
+            array_stats.q75 = np.quantile(self._exp_data[ii],0.75,axis=1)
+            array_stats.mad = np.median(np.abs(self._exp_data[ii] -
+                np.median(self._exp_data[ii],axis=1,keepdims=True)),axis=1)
+            self._exp_stats[ii] = array_stats
+
+        return self._exp_stats
+
+
+
+
+

pyvale/core/field.py

@@ -0,0 +1,136 @@
+"""
+================================================================================
+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 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:
+        """Abstract method. 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.
+        """
+        pass
+
+    @abstractmethod
+    def get_sim_data(self) -> mh.SimData:
+        """Abstract method. 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.
+        """
+        pass
+
+    @abstractmethod
+    def get_time_steps(self) -> np.ndarray:
+        """Abstract method. Gets a 1D array of time steps from the simulation
+        data.
+
+        Returns
+        -------
+        np.ndarray
+            1D array of simulation time steps. shape=(num_time_steps,)
+        """
+        pass
+
+    @abstractmethod
+    def get_visualiser(self) -> pv.UnstructuredGrid:
+        """Abstract method. 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.
+        """
+        pass
+
+    @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.
+        """
+        pass
+
+    @abstractmethod
+    def get_component_index(self,component: 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
+        """
+        pass
+
+    @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).
+        """
+        pass

pyvale/core/fieldconverter.py

@@ -0,0 +1,154 @@
+"""
+================================================================================
+pyvale: the python validation engine
+License: MIT
+Copyright (C) 2025 The Computer Aided Validation Team
+================================================================================
+"""
+import warnings
+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,
+                        spat_dim: 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.
+    spat_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,spat_dim)
+
+        # 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 _get_pyvista_cell_type(nodes_per_elem: int, spat_dim: int) -> CellType:
+    """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
+        Enumeration describing the element type in pyvista.
+    """
+    cell_type = 0
+
+    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:
+            warnings.warn(f"Cell type 2D with {nodes_per_elem} "
+                          + "nodes not recognised. Defaulting to 4 node QUAD")
+            cell_type = CellType.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
+        else:
+            warnings.warn(f"Cell type 3D with {nodes_per_elem} "
+                + "nodes not recognised. Defaulting to 8 node HEX")
+            cell_type = CellType.HEXAHEDRON
+
+    return cell_type
+
+
+def _exodus_to_pyvista_connect(cell_type: CellType, connect: np.ndarray) -> np.ndarray:
+    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 scale_length_units(sim_data: mh.SimData,
+                       disp_comps: tuple[str,...],
+                       scale: float) -> mh.SimData:
+
+    sim_data.coords = sim_data.coords*scale
+    for cc in disp_comps:
+        sim_data.node_vars[cc] = sim_data.node_vars[cc]*scale
+
+    return sim_data
+
+

pyvale/core/fieldsampler.py

@@ -0,0 +1,112 @@
+"""
+================================================================================
+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.core.field import IField
+from pyvale.core.sensordata import SensorData
+from pyvale.core.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/core/fieldscalar.py

@@ -0,0 +1,167 @@
+"""
+================================================================================
+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.core.field import IField
+from pyvale.core.fieldconverter import simdata_to_pyvista
+from pyvale.core.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","_spat_dims","_sim_data","_pyvista_grid",
+                 "_pyvista_vis")
+
+    def __init__(self,
+                 sim_data: mh.SimData,
+                 field_key: str,
+                 spat_dims: int) -> None:
+        """Initialiser for the `FieldScalar` class.
+
+        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.
+        spat_dims : int
+            Number of spatial dimensions (2 or 3) used for identifying element
+            types.
+        """
+
+        self._field_key = field_key
+        self._spat_dims = spat_dims
+
+        self._sim_data = sim_data
+        (self._pyvista_grid,self._pyvista_vis) = simdata_to_pyvista(
+            self._sim_data,
+            (self._field_key,),
+            self._spat_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._spat_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)
+