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

pyvale/__init__.py

@@ -1,8 +1,8 @@
-# ================================================================================
+# ==============================================================================
 # 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
@@ -15,6 +15,7 @@ testing simulation validation metrics and testing digital shadows/twins.
 # underlying project structure: the user should be able to use 'pyvale.'
 # and access everything in one layer without multiple import dots
 
+
 from pyvale.dataset import *
 
 from pyvale.field import *
@@ -40,6 +41,7 @@ from pyvale.camera import *
 from pyvale.cameradata import *
 from pyvale.cameradata2d import *
 from pyvale.cameratools import *
+from pyvale.camerastereo import *
 
 import pyvale.cython.rastercyth as rastercyth
 from pyvale.rastercy import *
@@ -54,13 +56,14 @@ from pyvale.errorrand import *
 from pyvale.errorsysindep import *
 from pyvale.errorsysdep import *
 from pyvale.errorsysfield import *
+from pyvale.errorsyscalib import *
 from pyvale.errordriftcalc import *
 
 from pyvale.generatorsrandom import *
 
 from pyvale.visualopts import *
 from pyvale.visualtools import *
-from pyvale.visualsimplotter import *
+from pyvale.visualsimsensors import *
 from pyvale.visualsimanimator import *
 from pyvale.visualexpplotter import *
 from pyvale.visualtraceplotter import *
@@ -72,3 +75,15 @@ from pyvale.analyticsimdatagenerator import *
 from pyvale.analyticsimdatafactory import *
 
 from pyvale.experimentsimulator import *
+
+from pyvale.blendercalibrationdata import *
+from pyvale.blenderlightdata import *
+from pyvale.blendermaterialdata import *
+from pyvale.blenderrenderdata import *
+from pyvale.blenderscene import *
+from pyvale.blendertools import *
+from pyvale.simtools import *
+
+from pyvale.output import *
+from pyvale.pyvaleexceptions import *
+

pyvale/analyticmeshgen.py

@@ -3,6 +3,7 @@
 # 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

pyvale/analyticsimdatafactory.py

@@ -1,18 +1,22 @@
-# ================================================================================
+# ==============================================================================
 # pyvale: the python validation engine
 # License: MIT
 # Copyright (C) 2025 The Computer Aided Validation Team
-# ================================================================================
+# ==============================================================================
+
+"""
+Helper functions and mini factory for building standard test meshes with
+analytic functions for the physical fields.
+"""
 
 import numpy as np
 import sympy
 import mooseherder as mh
-from pyvale.analyticsimdatagenerator import (AnalyticCaseData2D,
-                                                  AnalyticSimDataGenerator)
-
+from pyvale.analyticsimdatagenerator import (AnalyticData2D,
+                                                  AnalyticSimDataGen)
 
 
-def standard_case_2d() -> AnalyticCaseData2D:
+def standard_case_2d() -> AnalyticData2D:
     """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.
@@ -22,7 +26,7 @@ def standard_case_2d() -> AnalyticCaseData2D:
     AnalyticCaseData2D
         _description_
     """
-    case_data = AnalyticCaseData2D()
+    case_data = AnalyticData2D()
     case_data.length_x = 10.0
     case_data.length_y = 7.5
     n_elem_mult = 10
@@ -33,12 +37,13 @@ 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.
+    """Namespace for function used to build 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]:
+    def scalar_linear_2d() -> tuple[mh.SimData,AnalyticSimDataGen]:
         """_summary_
 
         Returns
@@ -54,14 +59,14 @@ class AnalyticCaseFactory:
         case_data.offsets_space = (20.0,)
         case_data.offsets_time = (0.0,)
 
-        data_gen = AnalyticSimDataGenerator(case_data)
+        data_gen = AnalyticSimDataGen(case_data)
 
         sim_data = data_gen.generate_sim_data()
 
         return (sim_data,data_gen)
 
     @staticmethod
-    def scalar_quadratic_2d() -> tuple[mh.SimData,AnalyticSimDataGenerator]:
+    def scalar_quadratic_2d() -> tuple[mh.SimData,AnalyticSimDataGen]:
         """_summary_
 
         Returns
@@ -75,7 +80,7 @@ class AnalyticCaseFactory:
         case_data.funcs_y = (sym_y*(sym_y - case_data.length_y),)
         case_data.funcs_t = (sym_t,)
 
-        data_gen = AnalyticSimDataGenerator(case_data)
+        data_gen = AnalyticSimDataGen(case_data)
 
         sim_data = data_gen.generate_sim_data()
 

pyvale/analyticsimdatagenerator.py

@@ -4,6 +4,11 @@
 # Copyright (C) 2025 The Computer Aided Validation Team
 #===============================================================================
 
+"""
+Generic tools for creating SimData objects based on analytic functions for the
+underlying physical fields. Useful for testing pyvale.
+"""
+
 from dataclasses import dataclass
 import numpy as np
 import sympy
@@ -12,7 +17,7 @@ from pyvale.analyticmeshgen import rectangle_mesh_2d, fill_dims_2d
 
 
 @dataclass(slots=True)
-class AnalyticCaseData2D:
+class AnalyticData2D:
     """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.
@@ -72,89 +77,98 @@ class AnalyticCaseData2D:
                                         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.
+    spatial dimensions default to x and y and time is denoted t. Note that these
+    are the symbols used to describe the analytic field functions.
     """
 
     offsets_space: tuple[float,...] = (0.0,)
-    """_summary_
+    """Constants which are added to the physical field functions in each spatial
+    dimensions.
     """
 
     offsets_time: tuple[float,...] = (0.0,)
-    """_summary_
+    """Constant which is added to the physical field function in time.
     """
 
     nodes_per_elem: int = 4
-    """_summary_
+    """Number of nodes per element. Currently only rectangular meshes and with
+    4 nodes per element are supported. Defaults to 4.
     """
 
 
-class AnalyticSimDataGenerator:
+class AnalyticSimDataGen:
     """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.
+    the analytic field functions at a given spatial coordinate/time to check
+    against pyvale interpolation functions. Currently only support 2D cases.
     """
 
-    __slots__ = ("_case_data","_coords","_connect")
+    __slots__ = ("case_data","coords","connect","field_sym_funcs",
+                 "field_lam_funcs","field_eval")
 
-    def __init__(self, case_data: AnalyticCaseData2D
+    def __init__(self, case_data: AnalyticData2D
                  ) -> None:
-        """_summary_
-
+        """
         Parameters
         ----------
         case_data : AnalyticCaseData2D
-            _description_
+            Data class containing the parameters required to create the analytic
+            mesh and the underlying physical field functions.
         """
-        self._case_data = case_data
-        (self._coords,self._connect) = rectangle_mesh_2d(case_data.length_x,
+        self.case_data = case_data
+        (self.coords,self.connect) = rectangle_mesh_2d(case_data.length_x,
                                                          case_data.length_y,
                                                          case_data.num_elem_x,
                                                          case_data.num_elem_y)
 
-        self._field_sym_funcs = dict()
-        self._field_lam_funcs = dict()
+        self.field_sym_funcs = dict()
+        self.field_lam_funcs = dict()
         for ii,kk in enumerate(case_data.field_keys):
-            self._field_sym_funcs[kk] = ((case_data.funcs_x[ii] *
+            self.field_sym_funcs[kk] = ((case_data.funcs_x[ii] *
                                           case_data.funcs_y[ii] +
                                           case_data.offsets_space[ii]) *
                                         (case_data.funcs_t[ii] +
                                          case_data.offsets_time[ii]))
 
-            self._field_lam_funcs[kk] = sympy.lambdify(case_data.symbols,
-                                                self._field_sym_funcs[kk],
+            self.field_lam_funcs[kk] = sympy.lambdify(case_data.symbols,
+                                                self.field_sym_funcs[kk],
                                                 'numpy')
-        self._field_eval = dict()
+        self.field_eval = dict()
 
 
     def evaluate_field_truth(self,
                        field_key: str,
                        coords: np.ndarray,
                        time_steps: np.ndarray | None = None) -> np.ndarray:
-        """_summary_
+        """Calculates the 'truth' from the analytical functions describing the
+        physical fields at the specified coordinates and time steps.
 
         Parameters
         ----------
         field_key : str
-            _description_
+            Key for the underlying physical field.
         coords : np.ndarray
-            _description_
+            Coordinates at which to evaluate the analytic physical field. shape
+            =(n_coords,coord[x,y,z])
         time_steps : np.ndarray | None, optional
-            _description_, by default None
+            Time steps at which to evaluate the physical field, by default None.
+            If this is none the evaluation time steps are assumed to match the
+            nominal time steps.
 
         Returns
         -------
         np.ndarray
-            _description_
+            Array of analytic field evaluations with shape = (n_coords,
+            n_time_steps)
         """
         if time_steps is None:
-            time_steps = self._case_data.time_steps
+            time_steps = self.case_data.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,
+        field_vals = self.field_lam_funcs[field_key](y_eval,
                                                       x_eval,
                                                       t_eval)
         return field_vals
@@ -162,89 +176,105 @@ class AnalyticSimDataGenerator:
 
     def evaluate_all_fields_truth(self,
                        coords: np.ndarray,
-                       time_steps: np.ndarray | None = None) -> np.ndarray:
-        """_summary_
+                       time_steps: np.ndarray | None = None
+                       ) -> dict[str,np.ndarray]:
+        """Evaluates all analytic physical fields at the specified coordinates
+        and time steps.
 
         Parameters
         ----------
         coords : np.ndarray
-            _description_
+            Coordinates at which to evaluate the analytic physical field. shape
+            =(n_coords,coord[x,y,z])
         time_steps : np.ndarray | None, optional
-            _description_, by default None
+            Time steps at which to evaluate the physical field, by default None.
+            If this is none the evaluation time steps are assumed to match the
+            nominal time steps.
 
         Returns
         -------
-        np.ndarray
-            _description_
+        dict[str,np.ndarray]
+            Dictionary keyed by the field name giving a numpy array with shape =
+            (n_coords,n_timesteps)
         """
         if time_steps is None:
-            time_steps = self._case_data.time_steps
+            time_steps = self.case_data.time_steps
 
         (x_eval,y_eval,t_eval) = fill_dims_2d(coords[:,0],
                                             coords[:,1],
                                             time_steps)
 
         eval_comps = dict()
-        for kk in  self._case_data.field_keys:
-            eval_comps[kk] = self._field_lam_funcs[kk](y_eval,
+        for kk in  self.case_data.field_keys:
+            eval_comps[kk] = self.field_lam_funcs[kk](y_eval,
                                                         x_eval,
                                                         t_eval)
         return eval_comps
 
 
     def evaluate_field_at_nodes(self, field_key: str) -> np.ndarray:
-        (x_eval,y_eval,t_eval) = fill_dims_2d(self._coords[:,0],
-                                           self._coords[:,1],
-                                           self._case_data.time_steps)
-        """_summary_
+        """Evaluates the underlying physical field at the node locations and
+        nominal time steps.
+
+        Parameters
+        ----------
+        field_key : str
+            String key for the field to be evaluated.
 
         Returns
         -------
-        _type_
-            _description_
+        np.ndarray
+            Array of field evaluations with shape=(n_nodes,n_timesteps)
         """
-        self._field_eval[field_key] = self._field_lam_funcs[field_key](y_eval,
+        (x_eval,y_eval,t_eval) = fill_dims_2d(self.coords[:,0],
+                                           self.coords[:,1],
+                                           self.case_data.time_steps)
+
+        self.field_eval[field_key] = self.field_lam_funcs[field_key](y_eval,
                                                                         x_eval,
                                                                         t_eval)
-        return self._field_eval[field_key]
+        return self.field_eval[field_key]
 
     def evaluate_all_fields_at_nodes(self) -> dict[str,np.ndarray]:
-        """_summary_
+        """Evaluates all physical fields at the node locations and nominal time
+        steps.
 
         Returns
         -------
         dict[str,np.ndarray]
-            _description_
+            Dictionary keyed by the field name giving a numpy array with shape =
+            (n_coords,n_timesteps)
         """
-        (x_eval,y_eval,t_eval) = fill_dims_2d(self._coords[:,0],
-                                           self._coords[:,1],
-                                           self._case_data.time_steps)
+        (x_eval,y_eval,t_eval) = fill_dims_2d(self.coords[:,0],
+                                           self.coords[:,1],
+                                           self.case_data.time_steps)
         eval_comps = dict()
-        for kk in  self._case_data.field_keys:
-            eval_comps[kk] = self._field_lam_funcs[kk](y_eval,
+        for kk in  self.case_data.field_keys:
+            eval_comps[kk] = self.field_lam_funcs[kk](y_eval,
                                                         x_eval,
                                                         t_eval)
-        self._field_eval = eval_comps
-        return self._field_eval
+        self.field_eval = eval_comps
+        return self.field_eval
 
 
     def generate_sim_data(self) -> mh.SimData:
-        """_summary_
+        """Creates a SimData object using the analytic case geometry, mesh
+        parameters and the underlying physical fields.
 
         Returns
         -------
         mh.SimData
-            _description_
+            SimData object built from the analytic case data.
         """
         sim_data = mh.SimData()
         sim_data.num_spat_dims = 2
-        sim_data.time = self._case_data.time_steps
-        sim_data.coords = self._coords
-        sim_data.connect = {'connect1': self._connect}
+        sim_data.time = self.case_data.time_steps
+        sim_data.coords = self.coords
+        sim_data.connect = {'connect1': self.connect}
 
-        if not self._field_eval:
+        if not self.field_eval:
             self.evaluate_all_fields_at_nodes()
-        sim_data.node_vars = self._field_eval
+        sim_data.node_vars = self.field_eval
 
         return sim_data
 
@@ -253,33 +283,36 @@ class AnalyticSimDataGenerator:
                                field_key: str | None = None,
                                time_step: int = -1
                                ) -> tuple[np.ndarray,np.ndarray,np.ndarray]:
-        """_summary_
+        """Creates a visualisation grid for plotting heatmaps of the specified
+        analytic field using matplotlib.
 
         Parameters
         ----------
         field_key : str | None, optional
-            _description_, by default None
+            String key for the field to be visualised, by default None. If None
+            then the first field key is used.
         time_step : int, optional
-            _description_, by default -1
+            Time step at which to extract the field to be plotted, by default -1
 
         Returns
         -------
         tuple[np.ndarray,np.ndarray,np.ndarray]
-            _description_
+            Tuple containing the 2D grid of x coordinates, grid of y coordinates
+            and a grid of field evaluations.
         """
         if field_key is None:
-            field_key = self._case_data.field_keys[0]
+            field_key = self.case_data.field_keys[0]
 
-        grid_shape = (self._case_data.num_elem_y+1,
-                      self._case_data.num_elem_x+1)
+        grid_shape = (self.case_data.num_elem_y+1,
+                      self.case_data.num_elem_x+1)
 
-        grid_x = np.atleast_2d(self._coords[:,0]).T.reshape(grid_shape)
-        grid_y = np.atleast_2d(self._coords[:,1]).T.reshape(grid_shape)
+        grid_x = np.atleast_2d(self.coords[:,0]).T.reshape(grid_shape)
+        grid_y = np.atleast_2d(self.coords[:,1]).T.reshape(grid_shape)
 
-        if not self._field_eval:
+        if not self.field_eval:
             self.evaluate_all_fields_at_nodes()
 
-        scalar_grid = np.reshape(self._field_eval[field_key][:,time_step],grid_shape)
+        scalar_grid = np.reshape(self.field_eval[field_key][:,time_step],grid_shape)
 
         return (grid_x,grid_y,scalar_grid)
 

pyvale/blendercalibrationdata.py

@@ -0,0 +1,15 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+from dataclasses import dataclass
+
+#TODO: doctsrings
+
+@dataclass(slots=True)
+class CalibrationData:
+    angle_lims: tuple = (-10, 10)
+    angle_step: int = 5
+    plunge_lims: tuple = (-5, 5)
+    plunge_step: int = 5

pyvale/blenderlightdata.py

@@ -0,0 +1,26 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+from dataclasses import dataclass
+from enum import Enum
+import numpy as np
+from scipy.spatial.transform import Rotation
+
+#TODO: docstrings
+
+class BlenderLightType(Enum):
+    POINT = 'POINT'
+    SUN = 'SUN'
+    SPOT = 'SPOT'
+    AREA = 'AREA'
+
+@dataclass(slots=True)
+class BlenderLightData():
+    pos_world: np.ndarray
+    rot_world: Rotation
+    energy: int # NOTE: In Watts
+    type: BlenderLightType = BlenderLightType.POINT
+    shadow_soft_size: float = 1.5
+

pyvale/blendermaterialdata.py

@@ -0,0 +1,15 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+from dataclasses import dataclass
+
+#TODO: docstrings
+
+@dataclass(slots=True)
+class BlenderMaterialData():
+    # TODO: Add other material properties here
+    roughness: float = 1.0
+    metallic: float = 0.0
+    interpolant: int = 'Cubic'

pyvale/blenderrenderdata.py

@@ -0,0 +1,30 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
+from enum import Enum
+from dataclasses import dataclass
+from pathlib import Path
+from pyvale.cameradata import CameraData
+from pyvale.output import Outputs
+
+#TODO: docstrings
+
+class RenderEngine(Enum):
+    """Different render engines on Blender
+    """
+    CYCLES = "CYCLES"
+    EEVEE = "BLENDER_EEVEE_NEXT"
+    WORKBENCH = "BLENDER_WORKBENCH"
+
+@dataclass(slots=True)
+class RenderData:
+    cam_data: CameraData | tuple[CameraData, CameraData]
+    base_dir: Path = Outputs.base_dir
+    samples: int = 2
+    engine: RenderEngine = RenderEngine.CYCLES
+    max_bounces: int = 12
+    bit_size: int = 8
+    threads:int = 4