pyvale 2025.4.1__py3-none-any.whl → 2025.5.2__py3-none-any.whl

pyvale/fieldconverter.py

@@ -1,16 +1,19 @@
-# ================================================================================
+# ==============================================================================
 # 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 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,
                         elem_dims: int
@@ -44,6 +47,8 @@ def simdata_to_pyvista(sim_data: mh.SimData,
         (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)
@@ -69,19 +74,61 @@ def simdata_to_pyvista(sim_data: mh.SimData,
     return (pv_grid,pv_grid_vis)
 
 
-def scale_length_units(sim_data: mh.SimData,
-                       disp_comps: tuple[str,...],
-                       scale: float) -> mh.SimData:
+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
-    for cc in disp_comps:
-        sim_data.node_vars[cc] = sim_data.node_vars[cc]*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)
@@ -162,7 +209,7 @@ def extract_surf_mesh(sim_data: mh.SimData) -> mh.SimData:
     return face_data
 
 
-def _get_pyvista_cell_type(nodes_per_elem: int, spat_dim: int) -> CellType:
+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
@@ -174,10 +221,10 @@ def _get_pyvista_cell_type(nodes_per_elem: int, spat_dim: int) -> CellType:
 
     Returns
     -------
-    CellType
+    CellType | None
         Enumeration describing the element type in pyvista.
     """
-    cell_type = 0
+    cell_type = None
 
     if spat_dim == 2:
         if nodes_per_elem == 4:
@@ -192,10 +239,6 @@ def _get_pyvista_cell_type(nodes_per_elem: int, spat_dim: int) -> CellType:
             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
@@ -207,15 +250,29 @@ def _get_pyvista_cell_type(nodes_per_elem: int, spat_dim: int) -> CellType:
             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:
+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
@@ -235,7 +292,25 @@ def _exodus_to_pyvista_connect(cell_type: CellType, connect: np.ndarray) -> np.n
 
 
 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),
@@ -272,4 +347,5 @@ def _get_surf_map(nodes_per_elem: int) -> np.ndarray:
                          (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.")
+    raise ValueError("Number of nodes does not match a 3D element type for " \
+        "surface extraction.")

pyvale/fieldsampler.py

@@ -1,8 +1,8 @@
-# ================================================================================
+# ==============================================================================
 # pyvale: the python validation engine
 # License: MIT
 # Copyright (C) 2025 The Computer Aided Validation Team
-# ================================================================================
+# ==============================================================================
 
 import numpy as np
 import pyvista as pv

pyvale/fieldscalar.py

@@ -1,8 +1,8 @@
-# ================================================================================
+# ==============================================================================
 # pyvale: the python validation engine
 # License: MIT
 # Copyright (C) 2025 The Computer Aided Validation Team
-# ================================================================================
+# ==============================================================================
 
 import numpy as np
 import pyvista as pv
@@ -13,40 +13,40 @@ 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","_spat_dims","_sim_data","_pyvista_grid",
+    __slots__ = ("_field_key","_elem_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.
-
+                 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.
-        spat_dims : int
+        elem_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._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._spat_dims
+            self._elem_dims
         )
 
     def set_sim_data(self, sim_data: mh.SimData) -> None:
@@ -64,7 +64,7 @@ class FieldScalar(IField):
         (self._pyvista_grid,self._pyvista_vis) = simdata_to_pyvista(
             sim_data,
             (self._field_key,),
-            self._spat_dims
+            self._elem_dims
         )
 
     def get_sim_data(self) -> mh.SimData:

pyvale/fieldtensor.py

@@ -1,8 +1,8 @@
-# ================================================================================
+# ==============================================================================
 # pyvale: the python validation engine
 # License: MIT
 # Copyright (C) 2025 The Computer Aided Validation Team
-# ================================================================================
+# ==============================================================================
 
 import numpy as np
 import pyvista as pv
@@ -17,6 +17,8 @@ from pyvale.fieldtransform import (transform_tensor_2d,
                                    transform_tensor_3d,
                                    transform_tensor_3d_batch)
 
+# TODO:
+# - Checking to ensure normal and dev components are consistent
 
 class FieldTensor(IField):
     """Class for sampling (interpolating) tensor fields from simulations to
@@ -29,32 +31,28 @@ class FieldTensor(IField):
 
     def __init__(self,
                  sim_data: mh.SimData,
-                 field_key: str,
-                 norm_components: tuple[str,...],
-                 dev_components: tuple[str,...],
-                 spat_dims: int) -> None:
-        """Initialiser for the `FieldVector` class.
-
+                 field_name: str,
+                 norm_comps: tuple[str,...],
+                 dev_comps: tuple[str,...],
+                 elem_dims: int) -> None:
+        """
         Parameters
         ----------
         sim_data : mh.SimData
             Simulation data object containing the mesh and field to interpolate.
-        field_key : str
+        field_name : str
             String describing the tensor field. For example: 'strain'.
         components : tuple[str,...]
             String keys to the field components in the `SimData` object. For
             example ('stain_xx','strain_yy','strain_xy').
-        spat_dims : int
+        elem_dims : int
             Number of spatial dimensions (2 or 3) used for identifying element
             types.
         """
-        self._field_key = field_key
-        self._norm_components = norm_components
-        self._dev_components = dev_components
-        self._spat_dims = spat_dims
-
-        #TODO: do some checking to make sure norm/dev components are consistent
-        # based on the spatial dimensions
+        self._field_key = field_name
+        self._norm_components = norm_comps
+        self._dev_components = dev_comps
+        self._spat_dims = elem_dims
 
         self._sim_data = sim_data
         (self._pyvista_grid,self._pyvista_vis) = simdata_to_pyvista(

pyvale/fieldtransform.py

@@ -1,8 +1,13 @@
-# ================================================================================
+# ==============================================================================
 # pyvale: the python validation engine
 # License: MIT
 # Copyright (C) 2025 The Computer Aided Validation Team
-# ================================================================================
+# ==============================================================================
+
+"""
+This module contains a set of functions for transforming vector and tensor
+fields based on an input transformation matrix.
+"""
 
 import numpy as np
 

pyvale/fieldvector.py

@@ -1,8 +1,8 @@
-# ================================================================================
+# ==============================================================================
 # pyvale: the python validation engine
 # License: MIT
 # Copyright (C) 2025 The Computer Aided Validation Team
-# ================================================================================
+# ==============================================================================
 
 import numpy as np
 import pyvista as pv
@@ -30,9 +30,8 @@ class FieldVector(IField):
                  sim_data: mh.SimData,
                  field_key: str,
                  components: tuple[str,...],
-                 spat_dims: int) -> None:
-        """Initialiser for the `FieldVector` class.
-
+                 elem_dims: int) -> None:
+        """
         Parameters
         ----------
         sim_data : mh.SimData
@@ -42,13 +41,13 @@ class FieldVector(IField):
         components : tuple[str,...]
             String keys to the field components in the `SimData` object. For
             example ('disp_x','disp_y').
-        spat_dims : int
+        elem_dims : int
             Number of spatial dimensions (2 or 3) used for identifying element
             types.
         """
         self._field_key = field_key
         self._components = components
-        self._spat_dims = spat_dims
+        self._spat_dims = elem_dims
 
         self._sim_data = sim_data
         (self._pyvista_grid,self._pyvista_vis) = simdata_to_pyvista(

pyvale/generatorsrandom.py

@@ -1,14 +1,14 @@
-# ================================================================================
+# ==============================================================================
 # pyvale: the python validation engine
 # License: MIT
 # Copyright (C) 2025 The Computer Aided Validation Team
-# ================================================================================
+# ==============================================================================
 
 from abc import ABC, abstractmethod
 import numpy as np
 
 
-class IGeneratorRandom(ABC):
+class IGenRandom(ABC):
     """Interface (abstract base class) for wrapping numpy random number
     generation to allow probability distribution parameters to be specified in
     the initialiser whereas the generation of random numbers has a common
@@ -34,7 +34,7 @@ class IGeneratorRandom(ABC):
         pass
 
 
-class GeneratorNormal(IGeneratorRandom):
+class GenNormal(IGenRandom):
     """Class wrapping the numpy normal random number generator. Implements the
     IGeneratorRandom interface to allow for interchangeability with other random
     number generators.
@@ -45,9 +45,7 @@ class GeneratorNormal(IGeneratorRandom):
                  std: float = 1.0,
                  mean: float = 0.0,
                  seed: int | None = None) -> None:
-        """Initialiser taking the parameters of the probability distribution and
-        an optional seed for the random generator to allow for reproducibility.
-
+        """
         Parameters
         ----------
         std : float, optional
@@ -82,7 +80,7 @@ class GeneratorNormal(IGeneratorRandom):
                                 size = shape)
 
 
-class GeneratorLogNormal(IGeneratorRandom):
+class GenLogNormal(IGenRandom):
     """Class wrapping the numpy lognormal random generator. Implements the
     IGeneratorRandom interface to allow for interchangeability with other random
     number generators.
@@ -93,9 +91,7 @@ class GeneratorLogNormal(IGeneratorRandom):
                  std: float = 1.0,
                  mean: float = 0.0,
                  seed: int | None = None) -> None:
-        """Initialiser taking the parameters of the probability distribution and
-        an optional seed for the random generator to allow for reproducibility.
-
+        """
         Parameters
         ----------
         std : float, optional
@@ -129,7 +125,7 @@ class GeneratorLogNormal(IGeneratorRandom):
                                    size = shape)
 
 
-class GeneratorUniform(IGeneratorRandom):
+class GenUniform(IGenRandom):
     """Class wrapping the numpy uniform random number generator. Implements the
     IGeneratorRandom interface to allow for interchangeability with other random
     number generators.
@@ -140,9 +136,7 @@ class GeneratorUniform(IGeneratorRandom):
                  low: float = -1.0,
                  high: float = 1.0,
                  seed: int | None = None) -> None:
-        """Initialiser taking the parameters of the probability distribution and
-        an optional seed for the random generator to allow for reproducibility.
-
+        """
         Parameters
         ----------
         low : float, optional
@@ -176,7 +170,7 @@ class GeneratorUniform(IGeneratorRandom):
                                  size = shape)
 
 
-class GeneratorExponential(IGeneratorRandom):
+class GenExponential(IGenRandom):
     """Class wrapping the numpy exponential random generator. Implements the
     IGeneratorRandom interface to allow for interchangeability with other random
     number generators.
@@ -186,9 +180,7 @@ class GeneratorExponential(IGeneratorRandom):
     def __init__(self,
                  scale: float = 1.0,
                  seed: int | None = None) -> None:
-        """Initialiser taking the parameters of the probability distribution and
-        an optional seed for the random generator to allow for reproducibility.
-
+        """
         Parameters
         ----------
         scale : float, optional
@@ -218,7 +210,7 @@ class GeneratorExponential(IGeneratorRandom):
                                      size = shape)
 
 
-class GeneratorChiSquare(IGeneratorRandom):
+class GenChiSquare(IGenRandom):
     """Class wrapping the numpy chi square random generator. Implements the
     IGeneratorRandom interface to allow for interchangeability with other random
     number generators.
@@ -228,9 +220,7 @@ class GeneratorChiSquare(IGeneratorRandom):
     def __init__(self,
                  dofs: float,
                  seed: int | None = None) -> None:
-        """Initialiser taking the parameters of the probability distribution and
-        an optional seed for the random generator to allow for reproducibility.
-
+        """
         Parameters
         ----------
         dofs : float
@@ -260,7 +250,7 @@ class GeneratorChiSquare(IGeneratorRandom):
                                    size = shape)
 
 
-class GeneratorDirichlet(IGeneratorRandom):
+class GenDirichlet(IGenRandom):
     """Class wrapping the numpy dirichlet random generator. Implements the
     IGeneratorRandom interface to allow for interchangeability with other random
     number generators.
@@ -270,9 +260,7 @@ class GeneratorDirichlet(IGeneratorRandom):
     def __init__(self,
                  alpha: float,
                  seed: int | None = None) -> None:
-        """Initialiser taking the parameters of the probability distribution and
-        an optional seed for the random generator to allow for reproducibility.
-
+        """
         Parameters
         ----------
         alpha : float
@@ -300,7 +288,7 @@ class GeneratorDirichlet(IGeneratorRandom):
         return self._rng.dirichlet(alpha = self._alpha, size = shape)
 
 
-class GeneratorF(IGeneratorRandom):
+class GenF(IGenRandom):
     """Class wrapping the numpy F distribution random generator. Implements the
     IGeneratorRandom interface to allow for interchangeability with other random
     number generators.
@@ -310,9 +298,7 @@ class GeneratorF(IGeneratorRandom):
     def __init__(self,
                  dofs: float,
                  seed: int | None = None) -> None:
-        """Initialiser taking the parameters of the probability distribution and
-        an optional seed for the random generator to allow for reproducibility.
-
+        """
         Parameters
         ----------
         dofs : float
@@ -341,7 +327,7 @@ class GeneratorF(IGeneratorRandom):
         return self._rng.f(dfnum = self._dofs, size = shape)
 
 
-class GeneratorGamma(IGeneratorRandom):
+class GenGamma(IGenRandom):
     """Class wrapping the numpy gamma random generator. Implements the
     IGeneratorRandom interface to allow for interchangeability with other random
     number generators.
@@ -352,9 +338,7 @@ class GeneratorGamma(IGeneratorRandom):
                  shape: float,
                  scale: float = 1.0,
                  seed: int | None = None) -> None:
-        """Initialiser taking the parameters of the probability distribution and
-        an optional seed for the random generator to allow for reproducibility.
-
+        """
         Parameters
         ----------
         shape : float
@@ -387,7 +371,7 @@ class GeneratorGamma(IGeneratorRandom):
                                      size = shape)
 
 
-class GeneratorStandardT(IGeneratorRandom):
+class GenStandardT(IGenRandom):
     """Class wrapping the numpy t distribution random generator. Implements the
     IGeneratorRandom interface to allow for interchangeability with other random
     number generators.
@@ -397,9 +381,7 @@ class GeneratorStandardT(IGeneratorRandom):
     def __init__(self,
                  dofs: float,
                  seed: int | None = None) -> None:
-        """Initialiser taking the parameters of the probability distribution and
-        an optional seed for the random generator to allow for reproducibility.
-
+        """
         Parameters
         ----------
         dofs : float
@@ -429,7 +411,7 @@ class GeneratorStandardT(IGeneratorRandom):
                                    size = shape)
 
 
-class GeneratorBeta(IGeneratorRandom):
+class GenBeta(IGenRandom):
     """Class wrapping the numpy beta distribution random generator. Implements
     the IGeneratorRandom interface to allow for interchangeability with other
     random number generators.
@@ -440,9 +422,7 @@ class GeneratorBeta(IGeneratorRandom):
                  a: float,
                  b: float,
                  seed: int | None = None) -> None:
-        """Initialiser taking the parameters of the probability distribution and
-        an optional seed for the random generator to allow for reproducibility.
-
+        """
         Parameters
         ----------
         a : float
@@ -475,7 +455,7 @@ class GeneratorBeta(IGeneratorRandom):
                               size = shape)
 
 
-class GeneratorTriangular(IGeneratorRandom):
+class GenTriangular(IGenRandom):
     """Class wrapping the numpy triangular random generator. Implements the
     IGeneratorRandom interface to allow for interchangeability with other random
     number generators.
@@ -487,9 +467,7 @@ class GeneratorTriangular(IGeneratorRandom):
                  mode: float = 0.0,
                  right: float = 1.0,
                  seed: int | None = None) -> None:
-        """Initialiser taking the parameters of the probability distribution and
-        an optional seed for the random generator to allow for reproducibility.
-
+        """
         Parameters
         ----------
         left : float, optional

pyvale/imagedef2d.py

@@ -1,8 +1,12 @@
-# ================================================================================
+# ==============================================================================
 # pyvale: the python validation engine
 # License: MIT
 # Copyright (C) 2025 The Computer Aided Validation Team
-# ================================================================================
+# ==============================================================================
+
+"""
+NOTE: This module is a feature under developement.
+"""
 
 import time
 import warnings

pyvale/integratorfactory.py

@@ -1,8 +1,8 @@
-# ================================================================================
+# ==============================================================================
 # pyvale: the python validation engine
 # License: MIT
 # Copyright (C) 2025 The Computer Aided Validation Team
-# ================================================================================
+# ==============================================================================
 
 import numpy as np
 from pyvale.field import IField