pyvale 2026.1.1__cp311-cp311-manylinux_2_17_i686.manylinux2014_i686.whl

pyvale/sensorsim/simtools.py

@@ -0,0 +1,300 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
+"""This module contains helper functions that are useful for inspecting and
+manipulating simulation data.
+"""
+
+from typing import Any
+import dataclasses
+import numpy as np
+import pyvale.mooseherder as mh
+from pyvale.sensorsim.rendermesh import RenderMesh
+from pyvale.sensorsim.exceptions import Collapse2Dto3DError
+
+
+def print_dataclass_fields(in_data: Any) -> None:
+    """Diagnostic function to print all fields of a dataclass.
+
+    Parameters
+    ----------
+    in_data : Any
+        A data class to print the type and fields for as well as the type of
+        each of the fields.
+    """
+
+    print(f"Data class fields for: {type(in_data)}")
+    for field in dataclasses.fields(in_data):
+        if not field.name.startswith('__'):
+            print(f"    {field.name}: {field.type}")
+    print()
+
+
+def print_sim_data(sim_data: mh.SimData) -> None:
+    """Diagnostic function for inspecting a sim data object to work out shapes
+    of time, coordinates, connectivity tables, node vars, elem vars as well as
+    the associated keys in the dicttionaries for the connectivity,
+    node/elem/glob vars.
+
+    Parameters
+    ----------
+    sim_data : mh.SimData
+        SimData to print shapes of numpy arrays.
+    """
+    print()
+    if sim_data.time is not None:
+        print(f"{sim_data.time.shape=}")
+    print()
+
+    if sim_data.coords is not None:
+        print(f"{sim_data.coords.shape=}")
+    print()
+
+    def print_dict(in_dict: dict | None) -> None:
+        if in_dict is None:
+            print("    None\n")
+            return
+
+        print(f"keys={in_dict.keys()}")
+        for kk in in_dict:
+            print(f"    {kk}.shape={in_dict[kk].shape}")
+
+        print()
+
+    print("sim_data.connect")
+    print_dict(sim_data.connect)
+    print("sim_data.node_vars")
+    print_dict(sim_data.node_vars)
+    print("sim_data.elem_vars")
+    print_dict(sim_data.elem_vars)
+    print("sim_data.glob_vars")
+    print_dict(sim_data.glob_vars)
+
+
+def print_dimensions(sim_data: mh.SimData) -> None:
+    """Diagnostic function for quickly finding the coordinate limits for from a
+    given simulation.
+
+    Parameters
+    ----------
+    sim_data : mh.SimData
+        Simulation data object containing the nodal coordinates.
+    """
+    print(80*"-")
+    print("SimData Dimensions:")
+    print(f"x [min,max] = [{np.min(sim_data.coords[:,0])}," + \
+        f"{np.max(sim_data.coords[:,0])}]")
+    print(f"y [min,max] = [{np.min(sim_data.coords[:,1])}," + \
+        f"{np.max(sim_data.coords[:,1])}]")
+    print(f"z [min,max] = [{np.min(sim_data.coords[:,2])}," + \
+        f"{np.max(sim_data.coords[:,2])}]")
+    print(f"t [min,max] = [{np.min(sim_data.time)},{np.max(sim_data.time)}]")
+    print(80*"-")
+
+
+def get_sim_dims(sim_data: mh.SimData) -> dict[str,tuple[float,float]]:
+    """Diagnostic function for extracting the dimensional limits in space and
+    time from a SimData object. Useful for finding the spatial dimensions over
+    which simulated sensors can be placed as well as the times over which they
+    can sampled the underlying field.
+
+    Parameters
+    ----------
+    sim_data : mh.SimData
+        Simulation data object containing the coordinates and time steps.
+
+    Returns
+    -------
+    dict[str,tuple[float,float]]
+        Dictionary of space and time coordinate limits keyed as 'x','y','z' for
+        the spatial dimensions and 't' for time. The dictionary will return a
+        tuple with the (min,max) of the given dimension.
+    """
+    sim_dims = {}
+    sim_dims["x"] = (np.min(sim_data.coords[:,0]),np.max(sim_data.coords[:,0]))
+    sim_dims["y"] = (np.min(sim_data.coords[:,1]),np.max(sim_data.coords[:,1]))
+    sim_dims["z"] = (np.min(sim_data.coords[:,2]),np.max(sim_data.coords[:,2]))
+    sim_dims["t"] = (np.min(sim_data.time),np.max(sim_data.time))
+    return sim_dims
+
+
+def centre_mesh_nodes(nodes: np.ndarray, spat_dim: int) -> np.ndarray:
+    """A method to centre the nodes of a mesh around the origin.
+
+    Parameters
+    ----------
+    nodes : np.ndarray
+        An array containing the node locations of the mesh.
+    spat_dim : int
+        The spatial dimension of the mesh.
+
+    Returns
+    -------
+    np.ndarray
+        An array containing the mesh node locations, but centred around
+        the origin.
+    """
+    max = np.max(nodes, axis=0)
+    min = np.min(nodes, axis=0)
+    middle = max - ((max - min) / 2)
+    if spat_dim == 3:
+        middle[2] = 0
+    centred = np.subtract(nodes, middle)
+    return centred
+
+
+def get_deformed_nodes(timestep: int,
+                        render_mesh: RenderMesh) -> np.ndarray | None:
+    """A method to obtain the deformed locations of all the nodes at a given
+        timestep.
+
+    Parameters
+    ----------
+    timestep : int
+        The timestep at which to find the deformed nodes.
+    render_mesh: RenderMeshData
+        A dataclass containing the skinned mesh and simulation results.
+
+    Returns
+    -------
+    np.ndarray | None
+        An array containing the deformed values of all the components at
+        each node location. Returns None if there are no deformation values.
+    """
+    if render_mesh.fields_disp is None:
+        return None
+
+    added_disp = render_mesh.fields_disp[:, timestep]
+    if added_disp.shape[1] == 2:
+        added_disp = np.hstack((added_disp,np.zeros([added_disp.shape[0],1])))
+    coords = np.delete(render_mesh.coords, 3, axis=1)
+    deformed_nodes = coords + added_disp
+    return deformed_nodes
+
+
+def scale_length_units(scale: float,
+                       sim_data: mh.SimData,
+                       disp_keys: 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_keys : 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_keys is not None:
+        for cc in disp_keys:
+            sim_data.node_vars[cc] = sim_data.node_vars[cc]*scale
+
+    return sim_data
+
+
+
+def coords_to_2D(coords_3d: np.ndarray) -> np.ndarray:
+    """Collapses and input coordinate array with 3 spatial dimensions to have
+    only 2 spatial dimensions. Useful for removing the axis that is zero for
+    Delaunay triangulation.
+
+    Parameters
+    ----------
+    coords_3d : np.ndarray
+        Array of coordinates with shape=(num_points,coord[X,Y,Z]). Note that
+        this is the same format as in a `SimData` object
+
+    Returns
+    -------
+    np.ndarray
+        A coordinate array for the 2D simulation with the zero axis removed.
+        The array has shape (num_points,2) where the second axis represents the
+        2D coords.
+
+    Raises
+    ------
+    Collapse2Dto3DError
+        Problem is either 3D or 1D, coordinates must have exactly one axis which
+        is all zeros.
+    """
+    zero_axs = get_sim_zero_axs(coords_3d)
+    num_zero_ax = np.sum(zero_axs)
+
+    if num_zero_ax == 0:
+        raise Collapse2Dto3DError("No coordinate axis is close to zero, unable" \
+            "to collapse problem to 2D. Check coords in SimData object.")
+
+    if num_zero_ax > 1:
+        raise Collapse2Dto3DError("Two coordinate axes are close to zero," \
+            " problem is 1D cannot collapse problem to 2D. Check coords in " \
+            "SimData object.")
+
+    ax_to_zero = np.argmax(zero_axs != 0)
+    coords_2d = np.delete(coords_3d,ax_to_zero,axis=1)
+    return coords_2d
+
+
+def get_sim_zero_axs(coords_3d: np.ndarray) -> np.ndarray:
+    """Helper function to extract which (if any) axis is all zeros in a
+    coordinate array.
+
+    Parameters
+    ----------
+    coords_3d : np.ndarray
+        Array of coordinates with shape=(num_points,coord[X,Y,Z]). Note that
+        this is the same format as in a `SimData` object
+
+    Returns
+    -------
+    np.ndarray
+        A 3 element array with '1' where the axis is zero and '0' everywhere
+        else. The elements of the array nominally represent (X,Y,Z).
+    """
+    zero_axs = np.zeros((3,),dtype=np.uintp)
+    for ii in range(coords_3d.shape[1]):
+        if np.allclose(coords_3d[:,ii],0):
+            zero_axs[ii] = 1
+
+    return zero_axs
+
+
+def is_sim_2D(coords_3d: np.ndarray) -> bool:
+    """Helper function that inspects a numpy array of coordinates and determines
+    if one of the spatial axes is all zero to infer that the simulation is 2D.
+
+    Parameters
+    ----------
+    coords_3d : np.ndarray
+        Array of coordinates with shape=(num_points,coord[X,Y,Z]). Note that
+        this is the same format as in a `SimData` object
+
+    Returns
+    -------
+    bool
+        True if the simulation has exactly one coordinate axis as all zero and
+        False otherwise.
+    """
+    zero_axs = get_sim_zero_axs(coords_3d)
+
+    if np.sum(zero_axs) == 1:
+        return True
+
+    return False
+
+
+

pyvale/sensorsim/visualexpplotter.py

@@ -0,0 +1,201 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
+"""
+This module contains functions for plotting virtuals sensor trace summary
+statistics and uncertainty bounds over simulated experiments.
+"""
+
+from typing import Any
+import numpy as np
+import matplotlib.figure as mpf
+import matplotlib.axes._axes as mpa
+import matplotlib.pyplot as plt
+from pyvale.sensorsim.exceptions import VisError
+from pyvale.sensorsim.visualopts import (PlotOptsGeneral,
+                                         TraceOptsExperiment,
+                                         EExpVisBounds,
+                                         EExpVisCentre)
+from pyvale.sensorsim.sensordescriptor import SensorDescriptor
+from pyvale.sensorsim.experimentsimulator import (ExperimentSimulator,
+                                                  ExpSimSaveKeys)
+from pyvale.sensorsim.experimentstats import calc_sensor_array_stats
+
+
+def plot_exp_traces(exp_data: dict[tuple[str,...],np.ndarray],
+                    comp_ind: int,
+                    sens_key: str,
+                    sim_key: str,
+                    descriptor: SensorDescriptor,
+                    trace_opts: TraceOptsExperiment | None = None,
+                    plot_opts: PlotOptsGeneral | None = None,
+                    exp_save_keys: ExpSimSaveKeys | None = None,
+                    ) -> tuple[mpf.Figure,mpa.Axes]:
+    """Plots the traces from a set of simulated experiments for a given input
+    physics simulation and sensor array.
+
+    Parameters
+    ----------
+    exp_data : dict[tuple[str,...],np.ndarray]
+        Simulated experiment data dictionary produced by the experiment
+        simulator.
+    comp_ind : int
+        Index for the component of the measurement array to plot. For scalar
+        field sensors there is only one component so this should be 0. For
+        vector field sensors the components are in the order the keys where
+        specified which is normally x,y,z. For tensor field sensors the keys are
+        in the order they are specified with normal followed by deviatoric
+        components.
+    sens_key : str
+        String key identifying the sensor array in the simulated experiment data
+        dictionary.
+    sim_key : str
+        String key identifying the input physics simulation in the simulation
+        data dictionary.
+    descriptor : SensorDescriptor
+        Descriptor containing strings for labelling the plot axes with sensor
+        units and names.
+    trace_opts : TraceOptsExperiment | None, optional
+        Options for plotting the experiment traces including how to display the
+        scatter in the traces, by default None. If None a default options
+        dataclass is created.
+    plot_opts : PlotOptsGeneral | None, optional
+        Options for controlling characteristics of the plot including the size
+        of the figure, line widths etc., by default None. If None a default
+        plot options dataclass is created.
+    exp_save_keys : ExpSimSaveKeys | None, optional
+        Keys for extracting the simulation data from the simulated experiment
+        data dictionary, by default None. If None the default keys are used.
+
+    Returns
+    -------
+    tuple[mpf.Figure,mpa.Axes]
+        Figure and axes object for the matplotlib plot that is created.
+    """
+    if trace_opts is None:
+        trace_opts = TraceOptsExperiment()
+
+    if plot_opts is None:
+        plot_opts = PlotOptsGeneral()
+
+    if exp_save_keys is None:
+        exp_save_keys = ExpSimSaveKeys()
+
+    meas_key = (sim_key,sens_key,exp_save_keys.meas)
+    sys_key = (sim_key,sens_key,exp_save_keys.sys)
+    rand_key = (sim_key,sens_key,exp_save_keys.rand)
+    time_key = (sim_key,sens_key,exp_save_keys.sens_times)
+
+    exp_arr = exp_data[meas_key]
+    samp_time = exp_data[time_key]
+
+    num_exp_per_sim = exp_arr.shape[0]
+    num_sens = exp_arr.shape[1]
+
+    if trace_opts.sensors_to_plot is None:
+        sensors_to_plot = range(num_sens)
+    else:
+        sensors_to_plot = trace_opts.sensors_to_plot
+
+    #---------------------------------------------------------------------------
+    # Figure canvas setup
+    (fig, ax) = plt.subplots(figsize=plot_opts.single_fig_size_landscape,
+                           layout='constrained')
+    fig.set_dpi(plot_opts.resolution)
+
+    #---------------------------------------------------------------------------
+    # Plot all simulated experimental points
+    if trace_opts.plot_all_exp_points:
+        for ss in sensors_to_plot:
+            for ee in range(num_exp_per_sim):
+                ax.plot(samp_time,
+                        exp_arr[ee,ss,comp_ind,:],
+                        "+",
+                        lw=plot_opts.lw,
+                        ms=plot_opts.ms,
+                        color=plot_opts.colors[ss % plot_opts.colors_num])
+
+    sensor_tags = descriptor.create_sensor_tags(num_sens)
+    lines = []
+
+    # TODO: limit this to only calculate what we need for the fill and centre
+    exp_stats = calc_sensor_array_stats(exp_arr)
+
+    for ss in sensors_to_plot:
+        if trace_opts.centre == EExpVisCentre.MEDIAN:
+            trace_centre = exp_stats.med[ss,comp_ind,:]
+        else:
+            trace_centre = exp_stats.mean[ss,comp_ind,:]
+
+        line, = ax.plot(samp_time,
+                trace_centre,
+                trace_opts.exp_centre_line,
+                label=sensor_tags[ss],
+                lw=plot_opts.lw,
+                ms=plot_opts.ms,
+                color=plot_opts.colors[ss % plot_opts.colors_num])
+        lines.append(line)
+
+        if trace_opts.fill_between is not None:
+            if trace_opts.fill_between == EExpVisBounds.MINMAX:
+                upper = trace_opts.fill_scale*exp_stats.min
+                lower = trace_opts.fill_scale*exp_stats.max
+            elif trace_opts.fill_between == EExpVisBounds.QUARTILE:
+                upper = trace_opts.fill_scale*exp_stats.q25
+                lower = trace_opts.fill_scale*exp_stats.q75
+            elif trace_opts.fill_between == EExpVisBounds.STD:
+                upper = trace_centre + \
+                        trace_opts.fill_scale*exp_stats.std
+                lower = trace_centre - \
+                        trace_opts.fill_scale*exp_stats.std
+            elif trace_opts.fill_between == EExpVisBounds.MAD:
+                upper = trace_centre + \
+                        trace_opts.fill_scale*exp_stats.mad
+                lower = trace_centre - \
+                        trace_opts.fill_scale*exp_stats.mad
+
+            ax.fill_between(samp_time,
+                upper[ss,comp_ind,:],
+                lower[ss,comp_ind,:],
+                color=plot_opts.colors[ss % plot_opts.colors_num],
+                alpha=0.2)
+
+    #---------------------------------------------------------------------------
+    # Plot simulation and truth line
+    if (trace_opts.truth_line is not None 
+        and sys_key in exp_data 
+        and rand_key in exp_data):
+        truth = exp_data[meas_key] - exp_data[sys_key] - exp_data[rand_key]
+        truth = truth[0,:,:,:]
+        for ss in sensors_to_plot:
+            ax.plot(samp_time,
+                    truth[ss,comp_ind,:],
+                    trace_opts.truth_line,
+                    lw=plot_opts.lw,
+                    ms=plot_opts.ms,
+                    color=plot_opts.colors[ss % plot_opts.colors_num])
+
+    #---------------------------------------------------------------------------
+    # Axis / legend labels and options
+    ax.set_xlabel(trace_opts.time_label,
+                fontsize=plot_opts.font_ax_size, fontname=plot_opts.font_name)
+    ax.set_ylabel(descriptor.create_label(comp_ind),
+                fontsize=plot_opts.font_ax_size, fontname=plot_opts.font_name)
+
+    if trace_opts.time_min_max is None:
+        ax.set_xlim((np.min(samp_time),np.max(samp_time))) # type: ignore
+    else:
+        ax.set_xlim(trace_opts.time_min_max)
+
+    if trace_opts.legend_loc is not None:
+        ax.legend(handles=lines,
+                  prop={"size":plot_opts.font_leg_size},
+                  loc=trace_opts.legend_loc)
+
+    plt.grid(True)
+    plt.draw()
+
+    return (fig,ax)

pyvale/sensorsim/visualimagedef.py

@@ -0,0 +1,74 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
+"""
+NOTE: this module is a feature under developement.
+"""
+
+import numpy as np
+import matplotlib.pyplot as plt
+
+class ImageDefDiags:
+    @staticmethod
+    def plot_speckle_image(image: np.ndarray,
+                   title: str = "",
+                   cmap: str = "gray") -> None:
+        fig, ax = plt.subplots()
+        cset = plt.imshow(image,cmap=plt.get_cmap(cmap),origin='lower')
+        ax.set_aspect('equal','box')
+        ax.set_title(title,fontsize=12)
+        fig.colorbar(cset)
+
+    @staticmethod
+    def plot_vector_image(image: np.ndarray,
+                   title: str = "",
+                   cmap: str = "plasma") -> None:
+        fig, ax = plt.subplots()
+        cset = plt.imshow(image,cmap=plt.get_cmap(cmap),origin='lower')
+        ax.set_aspect('equal','box')
+        ax.set_title(title,fontsize=12)
+        fig.colorbar(cset)
+
+
+    @staticmethod
+    def plot_image_xy(image: np.ndarray,
+                      extent: tuple[float,float,float,float],
+                      title: str = "",
+                      cmap: str = "plasma",
+                      ax_units: str = "mm") -> None:
+
+        fig, ax = plt.subplots()
+        cset = plt.imshow(image,
+                        aspect='auto',interpolation='none',
+                        origin='lower',cmap=plt.get_cmap(cmap),
+                        extent=extent)
+        ax.set_aspect('equal','box')
+        ax.set_title(title,fontsize=12)
+        ax.set_xlabel(f'x [{ax_units}]',fontsize=12)
+        ax.set_ylabel(f'y [{ax_units}]',fontsize=12)
+        fig.colorbar(cset)
+
+    @staticmethod
+    def plot_all_diags(def_image: np.ndarray,
+                    def_mask: np.ndarray | None,
+                    def_image_subpx: np.ndarray,
+                    subpx_disp_x: np.ndarray,
+                    subpx_disp_y: np.ndarray,
+                    subpx_grid_xm: np.ndarray,
+                    subpx_grid_ym: np.ndarray) -> None:
+        image_map = "gray"
+        vector_map = "plasma"
+
+        if def_mask is not None:
+            ImageDefDiags.plot_speckle_image('Def. Mask',def_mask,image_map)
+
+        ImageDefDiags.plot_speckle_image('Subpx Def. Image',def_image_subpx,image_map)
+        ImageDefDiags.plot_speckle_image('Def. Image',def_image,image_map)
+
+        ext = tuple(np.array([subpx_grid_xm.min(),subpx_grid_xm.max(),
+                        subpx_grid_ym.min(),subpx_grid_ym.max()])*10**3)
+        ImageDefDiags.plot_image_xy('Sub Pixel Disp X',subpx_disp_x,ext,vector_map)
+        ImageDefDiags.plot_image_xy('Sub Pixel Disp Y',subpx_disp_y,ext,vector_map)

pyvale/sensorsim/visualimages.py

@@ -0,0 +1,76 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
+"""
+NOTE: this module is a feature under developement.
+"""
+
+from typing import Any
+import numpy as np
+import matplotlib.pyplot as plt
+from pyvale.sensorsim.camera import CameraBasic2D
+from pyvale.sensorsim.visualopts import PlotOptsGeneral
+
+# TODO: this only works for a 2D camera, maybe this should be deprecated
+def plot_measurement_image(camera: CameraBasic2D,
+                           component: str,
+                           time_step: int = -1,
+                           plot_opts: PlotOptsGeneral | None = None
+                           ) -> tuple[Any,Any]:
+
+    if plot_opts is None:
+        plot_opts = PlotOptsGeneral()
+
+    comp_ind = camera.get_field().get_component_index(component)
+    meas_image = camera.get_measurement_images()[:,:,comp_ind,time_step]
+    descriptor = camera.get_descriptor()
+
+    (fig, ax) = plt.subplots(figsize=plot_opts.single_fig_size_square,
+                             layout='constrained')
+    fig.set_dpi(plot_opts.resolution)
+
+    cset = plt.imshow(meas_image,
+                      cmap=plt.get_cmap(plot_opts.cmap_seq),
+                      origin='lower')
+    ax.set_aspect('equal','box')
+
+    fig.colorbar(cset,
+                 label=descriptor.create_label_flat(comp_ind))
+
+    title = f"Time: {camera.get_sample_times()[time_step]}s"
+    ax.set_title(title,fontsize=plot_opts.font_head_size)
+    ax.set_xlabel(r"x ($px$)",
+                fontsize=plot_opts.font_ax_size, fontname=plot_opts.font_name)
+    ax.set_ylabel(r"y ($px$)",
+                fontsize=plot_opts.font_ax_size, fontname=plot_opts.font_name)
+
+    return (fig,ax)
+
+
+def plot_field_image(image: np.ndarray,
+                     title_str: str | None = None,
+                     plot_opts: PlotOptsGeneral | None = None
+                     ) -> tuple[Any,Any]:
+
+    if plot_opts is None:
+        plot_opts = PlotOptsGeneral()
+
+        (fig, ax) = plt.subplots(figsize=plot_opts.single_fig_size_square,
+                                layout='constrained')
+        fig.set_dpi(plot_opts.resolution)
+        cset = plt.imshow(image,
+                          cmap=plt.get_cmap(plot_opts.cmap_seq))
+                          #origin='lower')
+        ax.set_aspect('equal','box')
+        fig.colorbar(cset)
+        if title_str is not None:
+            ax.set_title(title_str,fontsize=plot_opts.font_head_size)
+        ax.set_xlabel(r"x ($px$)",
+                    fontsize=plot_opts.font_ax_size, fontname=plot_opts.font_name)
+        ax.set_ylabel(r"y ($px$)",
+                    fontsize=plot_opts.font_ax_size, fontname=plot_opts.font_name)
+
+        return (fig,ax)