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

pyvale/__init__.py

@@ -1,3 +1,9 @@
+# ================================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ================================================================================
+
 """
 `pyvale`: the python validation engine. Used to simulate experimental data from
 an input multi-physics simulation by explicitly modelling sensors with realistic
@@ -5,71 +11,64 @@ uncertainties. Useful for experimental design, sensor placement optimisation,
 testing simulation validation metrics and testing digital shadows/twins.
 """
 
-"""
-================================================================================
-pyvale: the python validation engine
-License: MIT
-Copyright (C) 2025 The Computer Aided Validation Team
-================================================================================
-"""
 # NOTE: this simplifies and decouples how the user calls pyvale from the
 # underlying project structure: the user should be able to use 'pyvale.'
 # and access everything in one layer without multiple import dots
 
-from pyvale.core.dataset import *
+from pyvale.dataset import *
 
-from pyvale.core.field import *
-from pyvale.core.fieldscalar import *
-from pyvale.core.fieldvector import *
-from pyvale.core.fieldtensor import *
-from pyvale.core.fieldconverter import *
-from pyvale.core.fieldtransform import *
+from pyvale.field import *
+from pyvale.fieldscalar import *
+from pyvale.fieldvector import *
+from pyvale.fieldtensor import *
+from pyvale.fieldconverter import *
+from pyvale.fieldtransform import *
 
-from pyvale.core.integratorspatial import *
-from pyvale.core.integratorquadrature import *
-from pyvale.core.integratorrectangle import *
-from pyvale.core.integratorfactory import *
+from pyvale.integratorspatial import *
+from pyvale.integratorquadrature import *
+from pyvale.integratorrectangle import *
+from pyvale.integratorfactory import *
 
-from pyvale.core.sensordescriptor import *
-from pyvale.core.sensortools import *
-from pyvale.core.sensorarray import *
-from pyvale.core.sensorarrayfactory import *
-from pyvale.core.sensorarraypoint import *
-from pyvale.core.sensordata import *
+from pyvale.sensordescriptor import *
+from pyvale.sensortools import *
+from pyvale.sensorarray import *
+from pyvale.sensorarrayfactory import *
+from pyvale.sensorarraypoint import *
+from pyvale.sensordata import *
 
-from pyvale.core.camera import *
-from pyvale.core.cameradata import *
-from pyvale.core.cameradata2d import *
-from pyvale.core.cameratools import *
+from pyvale.camera import *
+from pyvale.cameradata import *
+from pyvale.cameradata2d import *
+from pyvale.cameratools import *
 
-import pyvale.core.cython.rastercyth as rastercyth
-from pyvale.core.rastercy import *
+import pyvale.cython.rastercyth as rastercyth
+from pyvale.rastercy import *
 
-from pyvale.core.rendermesh import *
-from pyvale.core.rasternp import *
+from pyvale.rendermesh import *
+from pyvale.rasternp import *
 
-from pyvale.core.imagedef2d import *
+from pyvale.imagedef2d import *
 
-from pyvale.core.errorintegrator import *
-from pyvale.core.errorrand import *
-from pyvale.core.errorsysindep import *
-from pyvale.core.errorsysdep import *
-from pyvale.core.errorsysfield import *
-from pyvale.core.errordriftcalc import *
+from pyvale.errorintegrator import *
+from pyvale.errorrand import *
+from pyvale.errorsysindep import *
+from pyvale.errorsysdep import *
+from pyvale.errorsysfield import *
+from pyvale.errordriftcalc import *
 
-from pyvale.core.generatorsrandom import *
+from pyvale.generatorsrandom import *
 
-from pyvale.core.visualopts import *
-from pyvale.core.visualtools import *
-from pyvale.core.visualsimplotter import *
-from pyvale.core.visualsimanimator import *
-from pyvale.core.visualexpplotter import *
-from pyvale.core.visualtraceplotter import *
-from pyvale.core.visualimages import *
-from pyvale.core.visualimagedef import *
+from pyvale.visualopts import *
+from pyvale.visualtools import *
+from pyvale.visualsimplotter import *
+from pyvale.visualsimanimator import *
+from pyvale.visualexpplotter import *
+from pyvale.visualtraceplotter import *
+from pyvale.visualimages import *
+from pyvale.visualimagedef import *
 
-from pyvale.core.analyticmeshgen import *
-from pyvale.core.analyticsimdatagenerator import *
-from pyvale.core.analyticsimdatafactory import *
+from pyvale.analyticmeshgen import *
+from pyvale.analyticsimdatagenerator import *
+from pyvale.analyticsimdatafactory import *
 
-from pyvale.core.experimentsimulator import *
+from pyvale.experimentsimulator import *

pyvale/analyticmeshgen.py

@@ -0,0 +1,101 @@
+#===============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+#===============================================================================
+"""
+Analytic mesh creation tools for testing pyvale sensor simulation and
+uncertainty quantification functionality with a known analytic function for the
+scalar/vector/tensor field of interest.
+"""
+import numpy as np
+
+
+def rectangle_mesh_2d(leng_x: float,
+                      leng_y: float,
+                      n_elem_x: int,
+                      n_elem_y: int) -> tuple[np.ndarray,np.ndarray]:
+    """Creates the nodal coordinates and element connectivity table for a simple
+    2D quad mesh for a rectangular plate.
+
+    Parameters
+    ----------
+    leng_x : float
+        Length of the plate in the x direction.
+    leng_y : float
+        Length of the plate in the y direction.
+    n_elem_x : int
+        Number of elements along the x axis
+    n_elem_y : int
+        Number of elements along the y axis
+
+    Returns
+    -------
+    tuple[np.ndarray,np.ndarray]
+        The coordinates and connectivity table as numpy arrays. The coordinates
+        have shape=(n_nodes,coord[x,y,z]). The connectivity tables has shape=
+        (nodes_per_elem,num_elems).
+    """
+    n_elems = n_elem_x*n_elem_y
+    n_node_x = n_elem_x+1
+    n_node_y = n_elem_y+1
+    nodes_per_elem = 4
+
+    coord_x = np.linspace(0,leng_x,n_node_x)
+    coord_y = np.linspace(0,leng_y,n_node_y)
+    (coord_grid_x,coord_grid_y) = np.meshgrid(coord_x,coord_y)
+
+    coord_x = np.atleast_2d(coord_grid_x.flatten()).T
+    coord_y = np.atleast_2d(coord_grid_y.flatten()).T
+    coord_z = np.zeros_like(coord_x)
+    coords = np.hstack((coord_x,coord_y,coord_z))
+
+    connect = np.zeros((n_elems,nodes_per_elem)).astype(np.int64)
+    row = 1
+    nn = 0
+    for ee in range(n_elems):
+        nn += 1
+        if nn >= row*n_node_x:
+            row += 1
+            nn += 1
+
+        connect[ee,:] = np.array([nn,nn+1,nn+n_node_x+1,nn+n_node_x])
+    connect = connect.T
+
+    return (coords,connect)
+
+
+def fill_dims_2d(coord_x: np.ndarray,
+              coord_y: np.ndarray,
+              time: np.ndarray) -> tuple[np.ndarray,np.ndarray,np.ndarray]:
+    """Helper function to generate 2D filled arrays tih consistent dimensions
+    for array based maths operations. Takes 1D input vectors for the x, y and
+    time dimensions and returns 2D arrays with shape=(num_coords,num_timesteps).
+    Useful for evaluating analytical functions in space and time.
+
+    Parameters
+    ----------
+    coord_x : np.ndarray
+        1D flattened coordinate list for the x axis.
+    coord_y : np.ndarray
+        1D flattened coordinate list for the y axis.
+    time : np.ndarray
+        1D array of time steps.
+
+
+    Returns
+    -------
+    tuple[np.ndarray,np.ndarray,np.ndarray]
+        Filled 2D arrays with shape=(num_coords,num_timesteps) for the x, y and
+        time parameters respectively.
+    """
+    full_x = np.repeat(np.atleast_2d(coord_x).T,
+                       time.shape[0],
+                       axis=1)
+    full_y = np.repeat(np.atleast_2d(coord_y).T,
+                       time.shape[0],
+                       axis=1)
+    full_time = np.repeat(np.atleast_2d(time),
+                          coord_x.shape[0],
+                          axis=0)
+    return (full_x,full_y,full_time)

pyvale/{core/analyticsimdatafactory.py → analyticsimdatafactory.py}

@@ -1,19 +1,27 @@
-"""
-================================================================================
-pyvale: the python validation engine
-License: MIT
-Copyright (C) 2025 The Computer Aided Validation Team
-================================================================================
-"""
+# ================================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ================================================================================
+
 import numpy as np
 import sympy
 import mooseherder as mh
-from pyvale.core.analyticsimdatagenerator import (AnalyticCaseData2D,
+from pyvale.analyticsimdatagenerator import (AnalyticCaseData2D,
                                                   AnalyticSimDataGenerator)
 
-# NOTE: This module is a feature under developement.
+
 
 def standard_case_2d() -> AnalyticCaseData2D:
+    """Created the standard 2D analytic test case which is a plate with
+    dimensions 10x7.5 (x,y), number of elements 40x30 (x,y), and time steps of
+    0 to 10 in increments of 1.
+
+    Returns
+    -------
+    AnalyticCaseData2D
+        _description_
+    """
     case_data = AnalyticCaseData2D()
     case_data.length_x = 10.0
     case_data.length_y = 7.5
@@ -25,10 +33,19 @@ def standard_case_2d() -> AnalyticCaseData2D:
 
 
 class AnalyticCaseFactory:
+    """Builds pre-defined 2D meshes and fields based on analytic functions for
+    testing the sensor simulation functionality of pyvale.
+    """
 
     @staticmethod
     def scalar_linear_2d() -> tuple[mh.SimData,AnalyticSimDataGenerator]:
+        """_summary_
 
+        Returns
+        -------
+        tuple[mh.SimData,AnalyticSimDataGenerator]
+            _description_
+        """
         case_data = standard_case_2d()
         (sym_y,sym_x,sym_t) = sympy.symbols("y,x,t")
         case_data.funcs_x = (20.0/case_data.length_x * sym_x,)
@@ -45,7 +62,13 @@ class AnalyticCaseFactory:
 
     @staticmethod
     def scalar_quadratic_2d() -> tuple[mh.SimData,AnalyticSimDataGenerator]:
+        """_summary_
 
+        Returns
+        -------
+        tuple[mh.SimData,AnalyticSimDataGenerator]
+            _description_
+        """
         case_data = standard_case_2d()
         (sym_y,sym_x,sym_t) = sympy.symbols("y,x,t")
         case_data.funcs_x = (sym_x*(sym_x - case_data.length_x),)

pyvale/{core/analyticsimdatagenerator.py → analyticsimdatagenerator.py}

@@ -1,41 +1,111 @@
-"""
-================================================================================
-pyvale: the python validation engine
-License: MIT
-Copyright (C) 2025 The Computer Aided Validation Team
-================================================================================
-"""
+#===============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+#===============================================================================
+
 from dataclasses import dataclass
 import numpy as np
 import sympy
 import mooseherder as mh
-from pyvale.core.analyticmeshgen import rectangle_mesh_2d, fill_dims
+from pyvale.analyticmeshgen import rectangle_mesh_2d, fill_dims_2d
 
-# NOTE: This module is a feature under developement.
 
-@dataclass
+@dataclass(slots=True)
 class AnalyticCaseData2D:
+    """Dataclass for describing a 2D analytic test case for pyvale sensor
+    simulation. Includes information about the geometry, the mesh and the
+    analytic functions used to generate the field data.
+    """
+
     length_x: float = 10.0
+    """Length of the test case geometry in the X direction in length units.
+    Defaults to 10.0.
+    """
+
     length_y: float = 7.5
+    """Length of the test case geometry in the Y direction in length units.
+    Defaults to 7.5.
+    """
+
     num_elem_x: int = 4
+    """Number of elements in the mesh in the X direction. Defaults to 4.
+    """
+
     num_elem_y: int = 3
+    """Number of elements in the mesh in the Y direction. Defaults to 3.
+    """
+
     time_steps: np.ndarray | None = None
+    """1D array of time steps for the analytic test case. Defaults to None which
+    is for a test case that only has spatially varying functions.
+    """
+
     field_keys: tuple[str,...] = ('scalar',)
+    """Keys used to describe the field of interest. For a scalar field there is
+    only a single key. For a vector field 2 keys are required in 2D (xx,yy). For
+    a tensor field 3 keys are required for 2D (xx,yy,xy). Defaults to a single
+    key for a scalar field: ("scalar",).
+    """
+
     funcs_x: tuple[sympy.Expr,...] | None = None
+    """Analytic functions describing the field variation as a function of the x
+    coordinate. This tuple should have the same number of functions as the
+    number of field keys. Analytic functions in x, y and t are multiplied
+    together so setting a function to a constant of 1 will have no effect.
+    """
     funcs_y: tuple[sympy.Expr,...] | None = None
+    """Analytic functions describing the field variation as a function of the y
+    coordinate. This tuple should have the same number of functions as the
+    number of field keys. Analytic functions in x, y and t are multiplied
+    together so setting a function to a constant of 1 will have no effect.
+    """
+
     funcs_t: tuple[sympy.Expr,...] | None = None
+    """Analytic functions describing the field variation as a function of time
+    This tuple should have the same number of functions as the number of field
+    keys. Analytic functions in x, y and t are multiplied together so setting a
+    function to a constant of 1 will have no effect.
+    """
+
     symbols: tuple[sympy.Symbol,...] = (sympy.Symbol("y"),
                                         sympy.Symbol("x"),
                                         sympy.Symbol("t"))
+    """Sympy symbols describing the relevant dimensions of the problem. For 2D
+    spatial dimensions default to x and y and time is denoted t.
+    """
+
     offsets_space: tuple[float,...] = (0.0,)
+    """_summary_
+    """
+
     offsets_time: tuple[float,...] = (0.0,)
+    """_summary_
+    """
+
     nodes_per_elem: int = 4
+    """_summary_
+    """
 
 
 class AnalyticSimDataGenerator:
+    """Class for generating analytic field data as a `SimData` object to test
+    the sensor simulation functionality of pyvale. Provides tools to evaluate
+    the analytic field functions at a given spatial coordinate and time to check
+    against pyvale interpolation functions.
+    """
+
+    __slots__ = ("_case_data","_coords","_connect")
+
     def __init__(self, case_data: AnalyticCaseData2D
                  ) -> None:
+        """_summary_
 
+        Parameters
+        ----------
+        case_data : AnalyticCaseData2D
+            _description_
+        """
         self._case_data = case_data
         (self._coords,self._connect) = rectangle_mesh_2d(case_data.length_x,
                                                          case_data.length_y,
@@ -61,28 +131,56 @@ class AnalyticSimDataGenerator:
                        field_key: str,
                        coords: np.ndarray,
                        time_steps: np.ndarray | None = None) -> np.ndarray:
-
+        """_summary_
+
+        Parameters
+        ----------
+        field_key : str
+            _description_
+        coords : np.ndarray
+            _description_
+        time_steps : np.ndarray | None, optional
+            _description_, by default None
+
+        Returns
+        -------
+        np.ndarray
+            _description_
+        """
         if time_steps is None:
             time_steps = self._case_data.time_steps
 
-        (x_eval,y_eval,t_eval) = fill_dims(coords[:,0],
-                                            coords[:,1],
-                                            time_steps)
+        (x_eval,y_eval,t_eval) = fill_dims_2d(coords[:,0],
+                                           coords[:,1],
+                                           time_steps)
 
         field_vals = self._field_lam_funcs[field_key](y_eval,
-                                                x_eval,
-                                                t_eval)
+                                                      x_eval,
+                                                      t_eval)
         return field_vals
 
 
     def evaluate_all_fields_truth(self,
                        coords: np.ndarray,
                        time_steps: np.ndarray | None = None) -> np.ndarray:
-
+        """_summary_
+
+        Parameters
+        ----------
+        coords : np.ndarray
+            _description_
+        time_steps : np.ndarray | None, optional
+            _description_, by default None
+
+        Returns
+        -------
+        np.ndarray
+            _description_
+        """
         if time_steps is None:
             time_steps = self._case_data.time_steps
 
-        (x_eval,y_eval,t_eval) = fill_dims(coords[:,0],
+        (x_eval,y_eval,t_eval) = fill_dims_2d(coords[:,0],
                                             coords[:,1],
                                             time_steps)
 
@@ -95,17 +193,30 @@ class AnalyticSimDataGenerator:
 
 
     def evaluate_field_at_nodes(self, field_key: str) -> np.ndarray:
-        (x_eval,y_eval,t_eval) = fill_dims(self._coords[:,0],
+        (x_eval,y_eval,t_eval) = fill_dims_2d(self._coords[:,0],
                                            self._coords[:,1],
                                            self._case_data.time_steps)
+        """_summary_
 
+        Returns
+        -------
+        _type_
+            _description_
+        """
         self._field_eval[field_key] = self._field_lam_funcs[field_key](y_eval,
                                                                         x_eval,
                                                                         t_eval)
         return self._field_eval[field_key]
 
     def evaluate_all_fields_at_nodes(self) -> dict[str,np.ndarray]:
-        (x_eval,y_eval,t_eval) = fill_dims(self._coords[:,0],
+        """_summary_
+
+        Returns
+        -------
+        dict[str,np.ndarray]
+            _description_
+        """
+        (x_eval,y_eval,t_eval) = fill_dims_2d(self._coords[:,0],
                                            self._coords[:,1],
                                            self._case_data.time_steps)
         eval_comps = dict()
@@ -118,7 +229,13 @@ class AnalyticSimDataGenerator:
 
 
     def generate_sim_data(self) -> mh.SimData:
+        """_summary_
 
+        Returns
+        -------
+        mh.SimData
+            _description_
+        """
         sim_data = mh.SimData()
         sim_data.num_spat_dims = 2
         sim_data.time = self._case_data.time_steps
@@ -136,7 +253,20 @@ class AnalyticSimDataGenerator:
                                field_key: str | None = None,
                                time_step: int = -1
                                ) -> tuple[np.ndarray,np.ndarray,np.ndarray]:
-
+        """_summary_
+
+        Parameters
+        ----------
+        field_key : str | None, optional
+            _description_, by default None
+        time_step : int, optional
+            _description_, by default -1
+
+        Returns
+        -------
+        tuple[np.ndarray,np.ndarray,np.ndarray]
+            _description_
+        """
         if field_key is None:
             field_key = self._case_data.field_keys[0]
 

pyvale/{core/camera.py → camera.py}

@@ -1,18 +1,17 @@
-"""
-================================================================================
-pyvale: the python validation engine
-License: MIT
-Copyright (C) 2025 The Computer Aided Validation Team
-================================================================================
-"""
+# ================================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ================================================================================
+
 import numpy as np
-from pyvale.core.field import IField
-from pyvale.core.sensorarray import ISensorArray
-from pyvale.core.errorintegrator import ErrIntegrator
-from pyvale.core.sensordescriptor import SensorDescriptor
-from pyvale.core.fieldsampler import sample_field_with_sensor_data
-from pyvale.core.cameradata2d import CameraData2D
-from pyvale.core.cameratools import CameraTools
+from pyvale.field import IField
+from pyvale.sensorarray import ISensorArray
+from pyvale.errorintegrator import ErrIntegrator
+from pyvale.sensordescriptor import SensorDescriptor
+from pyvale.fieldsampler import sample_field_with_sensor_data
+from pyvale.cameradata2d import CameraData2D
+from pyvale.cameratools import CameraTools
 
 
 # NOTE: This module is a feature under developement.

pyvale/{core/cameradata.py → cameradata.py}

@@ -1,28 +1,15 @@
-"""
-================================================================================
-pyvale: the python validation engine
-License: MIT
-Copyright (C) 2025 The Computer Aided Validation Team
-================================================================================
-"""
+# ================================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ================================================================================
+
 from dataclasses import dataclass, field
 import numpy as np
 from scipy.spatial.transform import Rotation
 
 
 # NOTE: This module is a feature under developement.
-#
-# - Camera Local Coords: Pixel positions in pixels/meters
-# - Global Sim Coords: Transform from local pixel positions to sim coords in meters
-# - For this transformation we need user to specify center of ROI in sim coords
-# - There are going to be different ways to specify the camera properties
-
-# For thin lens theory will need to know some combination of:
-#   - The focal length of the lense
-#   - The working distance
-
-# Will need to create different ways for the user to automatically position the
-# camera
 
 
 @dataclass(slots=True)

pyvale/{core/cameradata2d.py → cameradata2d.py}

@@ -1,14 +1,14 @@
-"""
-================================================================================
-pyvale: the python validation engine
-License: MIT
-Copyright (C) 2025 The Computer Aided Validation Team
-================================================================================
-"""
+# ================================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ================================================================================
+
 from dataclasses import dataclass, field
 import numpy as np
 from scipy.spatial.transform import Rotation
 
+# NOTE: This module is a feature under developement.
 
 @dataclass(slots=True)
 class CameraData2D: