pyvale 2025.5.3__cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

pyvale/__init__.py

@@ -0,0 +1,89 @@
+# ==============================================================================
+# 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
+uncertainties. Useful for experimental design, sensor placement optimisation,
+testing simulation validation metrics and testing digital shadows/twins.
+"""
+
+# 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.dataset 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.integratorspatial import *
+from pyvale.integratorquadrature import *
+from pyvale.integratorrectangle import *
+from pyvale.integratorfactory 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.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 *
+
+from pyvale.rendermesh import *
+from pyvale.rasternp import *
+
+from pyvale.imagedef2d import *
+
+from pyvale.errorintegrator import *
+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.visualsimsensors import *
+from pyvale.visualsimanimator import *
+from pyvale.visualexpplotter import *
+from pyvale.visualtraceplotter import *
+from pyvale.visualimages import *
+from pyvale.visualimagedef import *
+
+from pyvale.analyticmeshgen import *
+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

@@ -0,0 +1,102 @@
+#===============================================================================
+# 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/analyticsimdatafactory.py

@@ -0,0 +1,91 @@
+# ==============================================================================
+# 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 (AnalyticData2D,
+                                                  AnalyticSimDataGen)
+
+
+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.
+
+    Returns
+    -------
+    AnalyticCaseData2D
+        _description_
+    """
+    case_data = AnalyticData2D()
+    case_data.length_x = 10.0
+    case_data.length_y = 7.5
+    n_elem_mult = 10
+    case_data.num_elem_x = 4*n_elem_mult
+    case_data.num_elem_y = 3*n_elem_mult
+    case_data.time_steps = np.linspace(0.0,1.0,11)
+    return case_data
+
+
+class AnalyticCaseFactory:
+    """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,AnalyticSimDataGen]:
+        """_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,)
+        case_data.funcs_y = (10.0/case_data.length_y * sym_y,)
+        case_data.funcs_t = (sym_t,)
+        case_data.offsets_space = (20.0,)
+        case_data.offsets_time = (0.0,)
+
+        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,AnalyticSimDataGen]:
+        """_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),)
+        case_data.funcs_y = (sym_y*(sym_y - case_data.length_y),)
+        case_data.funcs_t = (sym_t,)
+
+        data_gen = AnalyticSimDataGen(case_data)
+
+        sim_data = data_gen.generate_sim_data()
+
+        return (sim_data,data_gen)
+
+
+
+

pyvale/analyticsimdatagenerator.py

@@ -0,0 +1,323 @@
+#===============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# 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
+import mooseherder as mh
+from pyvale.analyticmeshgen import rectangle_mesh_2d, fill_dims_2d
+
+
+@dataclass(slots=True)
+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.
+    """
+
+    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. Note that these
+    are the symbols used to describe the analytic field functions.
+    """
+
+    offsets_space: tuple[float,...] = (0.0,)
+    """Constants which are added to the physical field functions in each spatial
+    dimensions.
+    """
+
+    offsets_time: tuple[float,...] = (0.0,)
+    """Constant which is added to the physical field function in time.
+    """
+
+    nodes_per_elem: int = 4
+    """Number of nodes per element. Currently only rectangular meshes and with
+    4 nodes per element are supported. Defaults to 4.
+    """
+
+
+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/time to check
+    against pyvale interpolation functions. Currently only support 2D cases.
+    """
+
+    __slots__ = ("case_data","coords","connect","field_sym_funcs",
+                 "field_lam_funcs","field_eval")
+
+    def __init__(self, case_data: AnalyticData2D
+                 ) -> None:
+        """
+        Parameters
+        ----------
+        case_data : AnalyticCaseData2D
+            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,
+                                                         case_data.length_y,
+                                                         case_data.num_elem_x,
+                                                         case_data.num_elem_y)
+
+        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] *
+                                          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],
+                                                'numpy')
+        self.field_eval = dict()
+
+
+    def evaluate_field_truth(self,
+                       field_key: str,
+                       coords: np.ndarray,
+                       time_steps: np.ndarray | None = None) -> np.ndarray:
+        """Calculates the 'truth' from the analytical functions describing the
+        physical fields at the specified coordinates and time steps.
+
+        Parameters
+        ----------
+        field_key : str
+            Key for the underlying physical field.
+        coords : np.ndarray
+            Coordinates at which to evaluate the analytic physical field. shape
+            =(n_coords,coord[x,y,z])
+        time_steps : np.ndarray | None, optional
+            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
+            Array of analytic field evaluations with shape = (n_coords,
+            n_time_steps)
+        """
+        if time_steps is None:
+            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,
+                                                      x_eval,
+                                                      t_eval)
+        return field_vals
+
+
+    def evaluate_all_fields_truth(self,
+                       coords: np.ndarray,
+                       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
+            Coordinates at which to evaluate the analytic physical field. shape
+            =(n_coords,coord[x,y,z])
+        time_steps : np.ndarray | None, optional
+            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
+        -------
+        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
+
+        (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,
+                                                        x_eval,
+                                                        t_eval)
+        return eval_comps
+
+
+    def evaluate_field_at_nodes(self, field_key: str) -> np.ndarray:
+        """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
+        -------
+        np.ndarray
+            Array of field evaluations with shape=(n_nodes,n_timesteps)
+        """
+        (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]
+
+    def evaluate_all_fields_at_nodes(self) -> dict[str,np.ndarray]:
+        """Evaluates all physical fields at the node locations and nominal time
+        steps.
+
+        Returns
+        -------
+        dict[str,np.ndarray]
+            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)
+        eval_comps = dict()
+        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
+
+
+    def generate_sim_data(self) -> mh.SimData:
+        """Creates a SimData object using the analytic case geometry, mesh
+        parameters and the underlying physical fields.
+
+        Returns
+        -------
+        mh.SimData
+            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}
+
+        if not self.field_eval:
+            self.evaluate_all_fields_at_nodes()
+        sim_data.node_vars = self.field_eval
+
+        return sim_data
+
+
+    def get_visualisation_grid(self,
+                               field_key: str | None = None,
+                               time_step: int = -1
+                               ) -> tuple[np.ndarray,np.ndarray,np.ndarray]:
+        """Creates a visualisation grid for plotting heatmaps of the specified
+        analytic field using matplotlib.
+
+        Parameters
+        ----------
+        field_key : str | None, optional
+            String key for the field to be visualised, by default None. If None
+            then the first field key is used.
+        time_step : int, optional
+            Time step at which to extract the field to be plotted, by default -1
+
+        Returns
+        -------
+        tuple[np.ndarray,np.ndarray,np.ndarray]
+            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]
+
+        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)
+
+        if not self.field_eval:
+            self.evaluate_all_fields_at_nodes()
+
+        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