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

pyvale/examples/renderblender/ex3_1_blendercalibration.py

@@ -0,0 +1,120 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
+import numpy as np
+from scipy.spatial.transform import Rotation
+from pathlib import Path
+import pyvale
+
+def main() -> None:
+    #NOTE: All lengths are to be specified in mm
+
+    # Set the save path
+    # --------------------------------------------------------------------------
+    # All the files saved will be saved to a subfolder within this specified
+    # base directory.
+    # This base directory can be specified by:
+    base_dir = Path("./")
+    # If no base directory is specified, it will be set as your home directory
+
+    # Creating the scene
+    # --------------------------------------------------------------------------
+    scene = pyvale.BlenderScene()
+
+    # Add the calibration target
+    # A rectangular calibration target of the specified size is added to the scene
+    target = scene.add_cal_target(target_size=np.array([150, 100, 10]))
+
+    # Add the camera
+    cam_data_0 = pyvale.CameraData(pixels_num=np.array([1540, 1040]),
+                                 pixels_size=np.array([0.00345, 0.00345]),
+                                 pos_world=np.array([0, 0, 400]),
+                                 rot_world=Rotation.from_euler("xyz", [0, 0, 0]),
+                                 roi_cent_world=(0, 0, 0),
+                                 focal_length=15.0)
+    # Set this to "symmetric" to get a symmetric stereo system or set this to
+    # "faceon" to get a face-on stereo system
+    stereo_setup = "faceon"
+    if stereo_setup == "symmetric":
+        stereo_system = pyvale.CameraTools.symmetric_stereo_cameras(
+            cam_data_0=cam_data_0,
+            stereo_angle=15.0)
+    if stereo_setup == "faceon":
+        stereo_system = pyvale.CameraTools.faceon_stereo_cameras(
+            cam_data_0=cam_data_0,
+            stereo_angle=15.0)
+
+    scene.add_stereo_system(stereo_system)
+
+    # Generate calibration file
+    stereo_system.save_calibration(base_dir)
+
+    # Add the light
+    light_data = pyvale.BlenderLightData(type=pyvale.BlenderLightType.POINT,
+                                         pos_world=(0, 0, 200),
+                                         rot_world=Rotation.from_euler("xyz",
+                                                                       [0, 0, 0]),
+                                         energy=1)
+    light = scene.add_light(light_data)
+    # The light can be moved and rotated:
+    light.location = (0, 0, 210)
+    light.rotation_euler = (0, 0, 0) # NOTE: The default is an XYZ Euler angle
+
+    # Apply the calibration target pattern
+    material_data = pyvale.BlenderMaterialData()
+    speckle_path = Path.cwd() / "src/pyvale/data/cal_target.tiff"
+    mm_px_resolution = pyvale.CameraTools.calculate_mm_px_resolution(cam_data_0)
+    scene.add_speckle(part=target,
+                                    speckle_path=speckle_path,
+                                    mat_data=material_data,
+                                    mm_px_resolution=mm_px_resolution,
+                                    cal=True)
+    # NOTE: The `cal` flag has to be set to True in order to scale the
+    # calibration target pattern correctly
+
+    # Rendering calibration images
+    # --------------------------------------------------------------------------
+    save_dir = Path.cwd() / "blenderimages"
+    save_name = "cal"
+    render_data = pyvale.RenderData(cam_data=(stereo_system.cam_data_0,
+                                              stereo_system.cam_data_1),
+                                    base_dir=base_dir)
+    # NOTE: The number of threads used to render the images is set within
+    # RenderData, it is defaulted to 4 threads
+
+    # The desired limits for the calibration target movement are to be set within
+    # the CalibrationData dataclass
+    calibration_data = pyvale.CalibrationData(angle_lims=(-10, 10),
+                                              angle_step=5,
+                                              plunge_lims=(-5, 5),
+                                              plunge_step=5)
+
+    # The number of calibration images that will be rendered can be calculated
+    number_calibration_images = pyvale.BlenderTools.number_calibration_images(calibration_data)
+    print()
+    print(80*"-")
+    print("Number of calibration images to be rendered:", number_calibration_images)
+    print(80*"-")
+
+    # The calibration images can then be rendered
+    pyvale.BlenderTools.render_calibration_images(render_data,
+                                                  calibration_data,
+                                                  target)
+
+    print()
+    print(80*"-")
+    print("Save directory of the images:", (render_data.base_dir / "calimages"))
+    print(80*"-")
+    print()
+
+    # Save Blender file
+    # --------------------------------------------------------------------------
+    # The file that will be saved is a Blender project file. This can be opened
+    # with the Blender GUI to view the scene.
+    pyvale.BlenderTools.save_blender_file(base_dir)
+
+if __name__ == "__main__":
+    main()

pyvale/examples/{rasterisation → renderrasterisation}/ex_rastenp.py

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

pyvale/examples/{rasterisation → renderrasterisation}/ex_rastercyth_oneframe.py

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

pyvale/examples/{rasterisation → renderrasterisation}/ex_rastercyth_static_cypara.py

@@ -1,8 +1,9 @@
-#===============================================================================
+# ==============================================================================
 # pyvale: the python validation engine
 # License: MIT
 # Copyright (C) 2025 The Computer Aided Validation Team
-#===============================================================================
+# ==============================================================================
+
 from pathlib import Path
 import time
 import numpy as np
@@ -12,10 +13,6 @@ import mooseherder as mh
 import pyvale as pyv
 
 def main() -> None:
-    """pyvale example: rasterisation field renderer
-    ----------------------------------------------------------------------------
-    - TODO
-    """
     print()
     print(80*"=")
     print("RASTER CYTHON FILE (should be *.so on Linux):")
@@ -23,8 +20,6 @@ def main() -> None:
     print(80*"=")
     print()
 
-    # This a path to an exodus *.e output file from MOOSE, this can be
-    # replaced with a path to your own simulation file
     sim_path = pyv.DataSet.render_mechanical_3d_path()
     #sim_path = pyv.DataSet.render_simple_block_path()
     #sim_path = Path.home()/"pyvale"/"src"/"pyvale"/"simcases"/"case26_out.e"

pyvale/examples/{rasterisation → renderrasterisation}/ex_rastercyth_static_pypara.py

@@ -1,9 +1,11 @@
-#===============================================================================
+# ==============================================================================
 # pyvale: the python validation engine
 # License: MIT
 # Copyright (C) 2025 The Computer Aided Validation Team
-#===============================================================================
-from pathlib import Path
+# ==============================================================================
+
+
+
 import time
 import numpy as np
 from scipy.spatial.transform import Rotation
@@ -11,11 +13,8 @@ import matplotlib.pyplot as plt
 import mooseherder as mh
 import pyvale as pyv
 
+
 def main() -> None:
-    """pyvale example: rasterisation field renderer
-    ----------------------------------------------------------------------------
-    - TODO
-    """
     print()
     print(80*"=")
     print("RASTER CYTHON FILE (should be *.so on Linux):")

pyvale/examples/{ex1_4_thermal2d.py → visualisation/ex1_1_plot_traces.py}

@@ -1,26 +1,31 @@
-# ================================================================================
+# ==============================================================================
 # pyvale: the python validation engine
 # License: MIT
 # Copyright (C) 2025 The Computer Aided Validation Team
-# ================================================================================
+# ==============================================================================
+
+"""
+Pyvale example: TODO
+--------------------------------------------------------------------------------
+TODO
+
+Test case: TODO
+"""
 
 import numpy as np
 import matplotlib.pyplot as plt
 import mooseherder as mh
 import pyvale as pyv
 
+# TODO: comments and full description for this example like the basics examples
 
 def main() -> None:
-    """pyvale example: point sensors on a 2D thermal simulation
-    ----------------------------------------------------------------------------
-    - Demonstrates options for controlling plots of points sensor traces using
-      matplotlib
-    """
+
     data_path = pyv.DataSet.thermal_2d_path()
     sim_data = mh.ExodusReader(data_path).read_all_sim_data()
-    field_key = list(sim_data.node_vars.keys())[0] # type: ignore
-    # Scale to mm to make 3D visualisation scaling easier
-    sim_data.coords = sim_data.coords*1000.0 # type: ignore
+    sim_data = pyv.scale_length_units(scale=1000.0,
+                                      sim_data=sim_data,
+                                      disp_comps=None)
 
     n_sens = (4,1,1)
     x_lims = (0.0,100.0)
@@ -33,11 +38,12 @@ def main() -> None:
     sens_data = pyv.SensorData(positions=sens_pos,
                                   sample_times=sample_times)
 
+    field_key = "temperature"
     tc_array = pyv.SensorArrayFactory \
         .thermocouples_basic_errs(sim_data,
                                   sens_data,
                                   field_key,
-                                  spat_dims=2)
+                                  elem_dims=2)
 
     err_int = pyv.ErrIntegrator([pyv.ErrSysOffset(offset=-5.0)],
                                      sens_data,
@@ -46,14 +52,24 @@ def main() -> None:
 
     measurements = tc_array.get_measurements()
 
+
     print(80*"-")
-    print("Looking at the last 5 time steps (measurements) of sensor 0:")
-    pyv.print_measurements(tc_array,
-                              (0,1),
-                              (0,1),
-                              (measurements.shape[2]-5,measurements.shape[2]))
+
+    sens_print: int = 0
+    time_print: int = 5
+    comp_print: int = 0
+
+    print(f"These are the last {time_print} virtual measurements of sensor "
+          + f"{sens_print}:")
+
+    pyv.print_measurements(sens_array=tc_array,
+                           sensors=(sens_print,sens_print+1),
+                           components=(comp_print,comp_print+1),
+                           time_steps=(measurements.shape[2]-time_print,
+                                       measurements.shape[2]))
     print(80*"-")
 
+
     trace_props = pyv.TraceOptsSensor()
 
     trace_props.truth_line = None

pyvale/examples/{features/ex_animation_tools_3dmonoblock.py → visualisation/ex2_1_animate_sim.py}

@@ -1,48 +1,54 @@
-'''
-================================================================================
-Example: 3d thermocouples on a monoblock
-
-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
+# ==============================================================================
+
+"""
+Pyvale example: TODO
+--------------------------------------------------------------------------------
+TODO
+
+Test case: TODO
+"""
+
 from pathlib import Path
 import numpy as np
 import mooseherder as mh
-import pyvale
+import pyvale as pyv
 
 
 def main() -> None:
-    """pyvale example: visualisation tools 3D
-    """
-    # Use mooseherder to read the exodus and get a SimData object
-    data_path = pyvale.DataSet.thermal_3d_path()
+
+    data_path = pyv.DataSet.thermal_3d_path()
     sim_data = mh.ExodusReader(data_path).read_all_sim_data()
-    field_name = 'temperature'
-    # Scale to mm to make 3D visualisation scaling easier
+
+    sim_data = pyv.scale_length_units(scale=1000.0,
+                                      sim_data=sim_data,
+                                      disp_comps=None)
     sim_data.coords = sim_data.coords*1000.0 # type: ignore
 
-    pyvale.print_dimensions(sim_data)
+    pyv.print_dimensions(sim_data)
 
     n_sens = (1,4,1)
     x_lims = (12.5,12.5)
     y_lims = (0,33.0)
     z_lims = (0.0,12.0)
-    sens_pos = pyvale.create_sensor_pos_array(n_sens,x_lims,y_lims,z_lims)
+    sens_pos = pyv.create_sensor_pos_array(n_sens,x_lims,y_lims,z_lims)
 
-    sens_data = pyvale.SensorData(positions=sens_pos)
+    sens_data = pyv.SensorData(positions=sens_pos)
 
-    tc_array = pyvale.SensorArrayFactory() \
+    field_key = 'temperature'
+    tc_array = pyv.SensorArrayFactory() \
         .thermocouples_basic_errs(sim_data,
                                   sens_data,
-                                  field_name,
-                                  spat_dims=3)
+                                  field_key,
+                                  elem_dims=3)
 
     measurements = tc_array.get_measurements()
     print(f'\nMeasurements for sensor at top of block:\n{measurements[-1,0,:]}\n')
 
-    vis_opts = pyvale.VisOptsSimSensors()
+    vis_opts = pyv.VisOptsSimSensors()
     vis_opts.window_size_px = (1200,800)
     vis_opts.camera_position = np.array([(59.354, 43.428, 69.946),
                                          (-2.858, 13.189, 4.523),
@@ -54,25 +60,25 @@ def main() -> None:
         save_dir.mkdir()
 
     if vis_mode == "animate":
-        anim_opts = pyvale.VisOptsAnimation()
+        anim_opts = pyv.VisOptsAnimation()
 
         anim_opts.save_path = save_dir / "test_animation"
-        anim_opts.save_animation = pyvale.EAnimationType.MP4
+        anim_opts.save_animation = pyv.EAnimationType.MP4
 
-        pv_anim = pyvale.animate_sim_with_sensors(tc_array,
-                                                  field_name,
+        pv_anim = pyv.animate_sim_with_sensors(tc_array,
+                                                  field_key,
                                                   time_steps=None,
                                                   vis_opts=vis_opts,
                                                   anim_opts=anim_opts)
 
     else:
-        image_save_opts = pyvale.VisOptsImageSave()
+        image_save_opts = pyv.VisOptsImageSave()
 
         image_save_opts.path = save_dir / "test_vector_graphics"
-        image_save_opts.image_type = pyvale.EImageType.SVG
+        image_save_opts.image_type = pyv.EImageType.SVG
 
-        pv_plot = pyvale.plot_point_sensors_on_sim(tc_array,
-                                                field_name,
+        pv_plot = pyv.plot_point_sensors_on_sim(tc_array,
+                                                field_key,
                                                 time_step=-1,
                                                 vis_opts=vis_opts,
                                                 image_save_opts=image_save_opts)

pyvale/experimentsimulator.py

@@ -1,30 +1,74 @@
-# ================================================================================
+# ==============================================================================
 # pyvale: the python validation engine
 # License: MIT
 # Copyright (C) 2025 The Computer Aided Validation Team
-# ================================================================================
+# ==============================================================================
+
+"""
+This module is used for performing Monte-Carlo virtual experiments over a series
+of input simulation cases and sensor arrays.
+"""
 
 from dataclasses import dataclass
 import numpy as np
-from pyvale.sensorarray import ISensorArray
 import mooseherder as mh
+from pyvale.sensorarray import ISensorArray
 
-# NOTE: This module is a feature under developement.
 
 @dataclass(slots=True)
 class ExperimentStats:
     """Dataclass holding summary statistics for a series of simulated
-    experiments.
+    experiments produced using the experiment simulator. All summary statistics
+    are calculated over the 'experiments' dimension of the measurements array so
+    the arrays of statistics have the shape=(n_sims,n_sensors,n_field_comps,
+    n_time_steps). Note that the n_sims dimension refers to the number of input
+    multi-physics simulations (i.e. SimData objects) that the virtual
+    experiments were performed over.
     """
+
     mean: np.ndarray | None = None
+    """Mean of each sensors measurement for the given field component and time
+    step as an array with shape=(n_sims,n_sensors,n_field_comps,n_time_steps).
+    """
+
     std: np.ndarray | None = None
-    cov: np.ndarray | None = None
+    """Standard deviation of the sensor measurements for the given field
+    component and time step as an array with shape=(n_sims,n_sensors,
+    n_field_comps, n_time_steps)
+    """
+
     max: np.ndarray | None = None
+    """Maximum of the sensor measurements for the given field component and time
+    step as an array with shape=(n_sims,n_sensors,n_field_comps,n_time_steps)
+    """
+
     min: np.ndarray | None = None
+    """Minmum of the sensor measurements for the given field component and time
+    step as an array with shape=(n_sims,n_sensors,n_field_comps,n_time_steps)
+    """
+
     med: np.ndarray | None = None
+    """Median  of the sensor measurements for the given field component and time
+    step as an array with shape=(n_sims,n_sensors,n_field_comps,n_time_steps)
+    """
+
     q25: np.ndarray | None = None
+    """Lower 25% quantile of the sensor measurements for the given field
+    component and time step as an array with shape=(n_sims,n_sensors,
+    n_field_comps, n_time_steps)
+    """
+
     q75: np.ndarray | None = None
+    """Upper 75% quantile of the sensor measurements for the given field
+    component and time step as an array with shape=(n_sims,n_sensors,
+    _field_comps, n_time_steps)
+    """
+
     mad: np.ndarray | None = None
+    """Median absolute deviation of the sensor measurements for the given field
+    component and time step as an array with shape=(n_sims,n_sensors,
+    n_field_comps, n_time_steps)
+    """
 
 
 class ExperimentSimulator:
@@ -33,7 +77,7 @@ class ExperimentSimulator:
     defined experiments. Calculates summary statistics for each sensor array
     applied to each simulation.
     """
-    __slots__ = ("sim_list","sensor_arrays","num_exp_per_sim","_exp_data",
+    __slots__ = ("_sim_list","_sensor_arrays","_num_exp_per_sim","_exp_data",
                  "_exp_stats")
 
     def __init__(self,
@@ -41,43 +85,75 @@ class ExperimentSimulator:
                  sensor_arrays: list[ISensorArray],
                  num_exp_per_sim: int
                  ) -> None:
-
-        self.sim_list = sim_list
-        self.sensor_arrays = sensor_arrays
-        self.num_exp_per_sim = num_exp_per_sim
-        self._exp_data = [None]*len(self.sensor_arrays)
-        self._exp_stats = [None]*len(self.sensor_arrays)
-
-    def get_data(self) -> list[np.ndarray | None]:
-        return self._exp_data
-
-    def get_stats(self) -> list[np.ndarray | None]:
-        return self._exp_stats
+        """
+        Parameters
+        ----------
+        sim_list : list[mh.SimData]
+            List of simulation data objects over which the virtual experiments
+            will be performed.
+        sensor_arrays : list[ISensorArray]
+            The sensor arrays that will be applied to each simulation to
+            generate the virtual experiment data.
+        num_exp_per_sim : int
+            Number of virtual experiments to perform for each simulation and
+            sensor array.
+        """
+        self._sim_list = sim_list
+        self._sensor_arrays = sensor_arrays
+        self._num_exp_per_sim = num_exp_per_sim
+        self._exp_data = None
+        self._exp_stats = None
 
     def run_experiments(self) -> list[np.ndarray]:
-        n_sims = len(self.sim_list)
-        # shape=list[n_arrays](n_sims,n_exps,n_sens,n_comps,n_time_steps)
-        self._exp_data = [None]*len(self.sensor_arrays)
-
-        for ii,aa in enumerate(self.sensor_arrays):
-            meas_array = np.zeros((n_sims,self.num_exp_per_sim)+
+        """Runs the specified number of virtual experiments over the number of
+        input simulation cases and virtual sensor arrays.
+
+        Returns
+        -------
+        list[np.ndarray]
+            List of virtual experimental data arrays where the list index
+            corresponds to the virtual sensor array and the data is an array
+            with shape=(n_sims,n_exps,n_sens,n_comps,n_time_steps).
+        """
+
+        n_sims = len(self._sim_list)
+        # shape=list[n_sens_arrays](n_sims,n_exps,n_sens,n_comps,n_time_steps)
+        self._exp_data = [None]*len(self._sensor_arrays)
+
+        for ii,aa in enumerate(self._sensor_arrays):
+            meas_array = np.zeros((n_sims,self._num_exp_per_sim)+
                                 aa.get_measurement_shape())
 
-            for jj,ss in enumerate(self.sim_list):
+            for jj,ss in enumerate(self._sim_list):
                 aa.get_field().set_sim_data(ss)
 
-                for ee in range(self.num_exp_per_sim):
+                for ee in range(self._num_exp_per_sim):
                     meas_array[jj,ee,:,:,:] = aa.calc_measurements()
 
             self._exp_data[ii] = meas_array
 
+        # shape=list[n_sens_arrays](n_sims,n_exps,n_sens,n_comps,n_time_steps)
         return self._exp_data
 
 
     def calc_stats(self) -> list[ExperimentStats]:
-        # shape=list[n_arrays](n_sims,n_exps,n_sens,n_comps,n_time_steps)
-        self._exp_stats = [None]*len(self.sensor_arrays)
-        for ii,_ in enumerate(self.sensor_arrays):
+        """Calculates summary statistics over the number of virtual experiments
+        specified. If `run_experiments()` has not been called then it is called
+        to generate the virtual experimental data to perform the statistical
+        calculations.
+
+        Returns
+        -------
+        list[ExperimentStats]
+            List of summary statistics data classes for the virtual experiments.
+            The list index correponds to the virtual sensor array.
+        """
+        if self._exp_data is None:
+            self._exp_data = self.run_experiments()
+
+        # shape=list[n_sens_arrays](n_sims,n_sens,n_comps,n_time_steps)
+        self._exp_stats = [None]*len(self._sensor_arrays)
+        for ii,_ in enumerate(self._sensor_arrays):
             array_stats = ExperimentStats()
             array_stats.max = np.max(self._exp_data[ii],axis=1)
             array_stats.min = np.min(self._exp_data[ii],axis=1)
@@ -90,6 +166,7 @@ class ExperimentSimulator:
                 np.median(self._exp_data[ii],axis=1,keepdims=True)),axis=1)
             self._exp_stats[ii] = array_stats
 
+        # shape=list[n_sens_arrays](n_sims,n_sens,n_comps,n_time_steps)
         return self._exp_stats
 
 

pyvale/field.py

@@ -1,8 +1,8 @@
-# ================================================================================
+# ==============================================================================
 # pyvale: the python validation engine
 # License: MIT
 # Copyright (C) 2025 The Computer Aided Validation Team
-# ================================================================================
+# ==============================================================================
 
 from abc import ABC, abstractmethod
 import numpy as np
@@ -29,7 +29,6 @@ class IField(ABC):
             Mooseherder SimData object. Contains a mesh and a simulated
             physical field.
         """
-        pass
 
     @abstractmethod
     def get_sim_data(self) -> mh.SimData:
@@ -43,7 +42,6 @@ class IField(ABC):
             Mooseherder SimData object. Contains a mesh and a simulated
             physical field.
         """
-        pass
 
     @abstractmethod
     def get_time_steps(self) -> np.ndarray:
@@ -55,7 +53,6 @@ class IField(ABC):
         np.ndarray
             1D array of simulation time steps. shape=(num_time_steps,)
         """
-        pass
 
     @abstractmethod
     def get_visualiser(self) -> pv.UnstructuredGrid:
@@ -68,7 +65,6 @@ class IField(ABC):
             Pyvista unstructured grid object containing only a mesh without any
             physical field data attached.
         """
-        pass
 
     @abstractmethod
     def get_all_components(self) -> tuple[str,...]:
@@ -82,7 +78,6 @@ class IField(ABC):
             Tuple containing the string keys for all components of the physical
             field.
         """
-        pass
 
     @abstractmethod
     def get_component_index(self,component: str) -> int:
@@ -99,7 +94,6 @@ class IField(ABC):
         int
             Index for the selected field component
         """
-        pass
 
     @abstractmethod
     def sample_field(self,
@@ -132,4 +126,3 @@ class IField(ABC):
             An array of sampled (interpolated) values with the following
             dimensions: shape=(num_points,num_components,num_time_steps).
         """
-        pass