pyvale 2026.1.1__cp311-cp311-manylinux_2_17_i686.manylinux2014_i686.whl

pyvale/examples/extsensorsim/ex4b_fielderrs_scal3d.py

@@ -0,0 +1,197 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
+"""
+Errors: field-based
+================================================================================
+
+In this example we give an overview of field-based systematic errors. Field
+errors require additional interpolation of the underlying physical field such as
+uncertainty in a sensor position or sampling time. For this example we will
+focus on field error sources that perturb sensor locations and sampling times.
+
+Note that field errors are more computationally intensive than basic errors as
+they require additional interpolations of the underlying physical field.
+"""
+
+from pathlib import Path
+import numpy as np
+import matplotlib.pyplot as plt
+
+# pyvale imports
+import pyvale.mooseherder as mh
+import pyvale.sensorsim as sens
+import pyvale.dataset as dataset
+
+#%%
+# 1. Load physics simulation data
+# -------------------------------
+data_path: Path = dataset.thermal_3d_path()
+sim_data: mh.SimData = mh.ExodusLoader(data_path).load_all_sim_data()
+sim_data: mh.SimData = sens.scale_length_units(scale=1000.0,
+                                               sim_data=sim_data,
+                                               disp_keys=None)
+
+#%%
+# 2. Build virtual sensor array
+# -----------------------------
+sim_dims = sens.simtools.get_sim_dims(sim_data)
+sens_pos: np.ndarray = sens.gen_pos_grid_inside(num_sensors=(1,4,1),
+                                                x_lims=(12.5,12.5),
+                                                y_lims=sim_dims["y"],
+                                                z_lims=sim_dims["z"])
+
+sample_times = np.linspace(0.0,np.max(sim_data.time),50)
+
+sens_data = sens.SensorData(positions=sens_pos,
+                            sample_times=sample_times)
+
+sens_array: sens.SensorsPoint = sens.SensorFactory.scalar_point(
+    sim_data,
+    sens_data,
+    comp_key="temperature",
+    spatial_dims=sens.EDim.THREED,
+    descriptor=sens.DescriptorFactory.temperature(),
+)
+
+#%%
+# 2.1. Add simulated measurement errors
+# ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+# Now we will create a field error data class which we will use to build our
+# field error. This controls which sensor parameters will be perturbed such
+# as: position, time and orientation. Here we will perturb the sensor
+# positions on the face of the block using a normal distribution and we will
+# also perturb the measurement times using constant offsets and random
+# generators.
+#
+# We can apply a constant offset to each sensor position in x,y,z by
+# providing a shape=(num_sensors,coord[x,y,z]) array. Here we apply a
+# constant offset in the y and z direction for all sensors. We also apply a
+# constant offset to the sampling times for all sensors.
+
+pos_offset_xyz = np.array((0.0,1.0,1.0),dtype=np.float64)
+pos_offset_xyz = np.tile(pos_offset_xyz,(sens_pos.shape[0],1))
+
+time_offset = np.full((sample_times.shape[0],),0.1)
+
+#%%
+# Using the `Gen*` random generators in pyvale we can randomly perturb the
+# position or sampling times of our virtual sensors.
+pos_rand = sens.GenUniform(low=-0.5,high=0.5)  # units = mm
+time_rand = sens.GenNormal(std=0.1) # units = s
+
+#%%
+# Now we put everything into our field error data class ready to build our
+# field error object. Have a look at the other parameters in this data class
+# to get a feel for the other types of supported field errors. We will look
+# at the orientation and area averaging errors when we look at vector and
+# tensor fields in later examples.
+field_err_data = sens.ErrFieldData(
+    pos_offset_xyz=pos_offset_xyz,
+    time_offset=time_offset,
+    pos_rand_xyz=(None,pos_rand,pos_rand),
+    time_rand=time_rand
+)
+
+#%%
+# Adding our field error to our error chain is exactly the same as the basic
+# errors we have seen previously. We can also combine field errors with
+# basic errors and place them anywhere in our error chain. We can even chain
+# field errors together and set them to be 'dependent' in which case the
+# perturbations to the sensor data will be accumulated. We will look at chaining
+# field errors in a later example. For now we will just have a single field
+# error so we can easily visualise what this type of error does.
+
+err_chain: list[sens.IErrSimulator] = [
+    sens.ErrSysField(sens_array.get_field(),field_err_data),
+]
+
+sens_array.set_error_chain(err_chain)
+
+#%%
+# It is important that we put errors in our error chain in the order we want
+# them evaluated. For example, if we want to combine a field error that perturbs
+# the sensor position with a dependent random noise as a percentage of the
+# measurement at that position then we must place the random error after our
+# field error in the error chain (and set the random error to be 'dependent').
+
+#%%
+# 3. Run simulated experiment
+# ---------------------------
+
+measurements: np.ndarray = sens_array.sim_measurements()
+
+truth: np.ndarray = sens_array.get_truth()
+sys_errs: np.ndarray = sens_array.get_errors_systematic()
+rand_errs: np.ndarray = sens_array.get_errors_random()
+
+print(80*"-")
+print("measurement = truth + sysematic error + random error")
+
+print(f"measurements.shape = {measurements.shape} = "
+        + "(n_sensors,n_field_components,n_timesteps)")
+print(f"truth.shape     = {truth.shape}")
+print(f"sys_errs.shape  = {sys_errs.shape}")
+print(f"rand_errs.shape = {rand_errs.shape}")
+
+sens_print: int = 3
+comp_print: int = 0
+time_last: int = 5
+time_print = slice(measurements.shape[2]-time_last,measurements.shape[2])
+
+print(f"\nThese are the last {time_last} virtual measurements of sensor "
+        + f"{sens_print}:\n")
+
+sens.print_measurements(sens_array,sens_print,comp_print,time_print)
+print("\n"+80*"-")
+
+#%%
+# 4. Analyse & visualise the results
+# ----------------------------------
+
+output_path = Path.cwd() / "pyvale-output"
+if not output_path.is_dir():
+    output_path.mkdir(parents=True, exist_ok=True)
+
+pv_plot = sens.plot_point_sensors_on_sim(sens_array,
+                                         comp_key="temperature")
+
+pv_plot.camera_position = [(59.354, 43.428, 69.946),
+                           (-2.858, 13.189, 4.523),
+                           (-0.215, 0.948, -0.233)]
+
+# Set to False to show an interactive plot instead of saving the figure
+pv_plot.off_screen = True
+if pv_plot.off_screen:
+    pv_plot.screenshot(output_path/"ext_ex4b_locs.png")
+else:
+    pv_plot.show()
+
+# %%
+# Visualisation of nominal and perturbed sensor locations including the field
+# errors.
+#
+# .. image:: ../../../../_static/ext_ex4b_locs.png
+#    :alt: Visualisation of virtual sensor locations.
+#    :width: 800px
+#    :align: center
+
+
+(fig,ax) = sens.plot_time_traces(sens_array,comp_key="temperature")
+fig.savefig(output_path/"ext_ex4b_traces.png",dpi=300,bbox_inches="tight")
+
+# Uncomment this to display the sensor trace plot
+# plt.show()
+
+# %%
+# Sensor traces showing the effects of the field error perturbing sensor
+# location and sensor sample times.
+#
+# .. image:: ../../../../_static/ext_ex4b_traces.png
+#    :alt: Simulated sensor traces.
+#    :width: 600px
+#    :align: center
+

pyvale/examples/extsensorsim/ex4c_angleerrs_vec2d.py

@@ -0,0 +1,215 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
+"""
+Errors: field-based with angles
+================================================================================
+
+In this example we demonstrate how to setup vector field sensors at custom
+orientations with respect to the simulation coordinate system. We first build a
+sensor array aligned with the simulation coords in the same way as the previous
+example. We then build a sensor array with the sensors rotated and compare this
+to the case with no rotation.
+"""
+
+from pathlib import Path
+import numpy as np
+import matplotlib.pyplot as plt
+from scipy.spatial.transform import Rotation
+
+# pyvale imports
+import pyvale.mooseherder as mh
+import pyvale.sensorsim as sens
+import pyvale.dataset as dataset
+
+
+#%%
+# 1. Load physics simulation data
+# -------------------------------
+
+data_path: Path = dataset.mechanical_2d_path()
+sim_data: mh.SimData = mh.ExodusLoader(data_path).load_all_sim_data()
+
+disp_keys = ("disp_x","disp_y")
+strain_keys = ("strain_xx","strain_yy","strain_xy")
+
+sim_data: mh.SimData  = sens.scale_length_units(scale=1000.0,
+                                                sim_data=sim_data,
+                                                disp_keys=disp_keys)
+
+#%%
+# 2. Build virtual sensor arrays
+# --------------------------------
+
+sim_dims: dict[str,tuple[float,float]] = sens.simtools.get_sim_dims(sim_data)
+sens_pos: np.ndarray = sens.gen_pos_grid_inside(num_sensors=(2,2,1),
+                                                x_lims=sim_dims["x"],
+                                                y_lims=sim_dims["y"],
+                                                z_lims=(0.0,0.0))
+
+sample_times: np.ndarray = np.linspace(0.0,np.max(sim_data.time),50)
+
+sens_angles_norot: tuple[Rotation] = (
+    Rotation.from_euler("zyx",[0,0,0], degrees=True),
+)
+
+sens_data_norot = sens.SensorData(positions=sens_pos,
+                                  sample_times=sample_times,
+                                  angles=sens_angles_norot)
+
+
+sens_array_norot: sens.SensorsPoint = sens.SensorFactory.vector_point(
+    sim_data,
+    sens_data_norot,
+    comp_keys=disp_keys,
+    spatial_dims=sens.EDim.TWOD,
+    descriptor=sens.DescriptorFactory.displacement(),
+)
+
+#%%
+# To create our sensor array with rotated sensors we need to add a tuple of
+# scipy rotation objects to our sensor data class. This tuple must be the
+# same length as the number of sensors in the sensor array. Note that it is
+# also possible to specify a single rotation in the tuple in this case all
+# sensors are assumed to have the same rotation and they are batch processed
+# to increase speed. Here we will define our rotations to all be the same
+# rotation in degrees about the z axis which is the out of plane axis for
+# our current test case.
+
+sens_rot_deg: float = 90.0
+sens_angles_rot = sens_pos.shape[0] * \
+    (Rotation.from_euler("zyx",[sens_rot_deg,0,0],degrees=True),)
+
+# We could have also use a single element tuple to have all sensors have the
+# angle and batch process them:
+sens_angles_rot = (Rotation.from_euler("zyx",[sens_rot_deg,0,0],degrees=True),)
+
+sens_data_rot = sens.SensorData(positions=sens_pos,
+                                sample_times=sample_times,
+                                angles=sens_angles_rot)
+
+sens_array_rot: sens.SensorsPoint = sens.SensorFactory.vector_point(
+    sim_data,
+    sens_data_rot,
+    comp_keys=disp_keys,
+    spatial_dims=sens.EDim.TWOD,
+    descriptor=sens.DescriptorFactory.displacement(),
+)
+
+#%%
+# 2.1. Add simulated measurement errors
+# ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+# We can also use a field error to add uncertainty to the sensors angle.
+# We can apply a specific offset to each sensor or provide a random
+# generator to perturb the sensors orientation. Note that the offset and
+# the random generator should provide the perturbation in degrees.
+
+angle_offset_zyx = np.zeros_like(sens_pos)
+angle_offset_zyx[:,0] = 2.0 # only rotate about z in 2D
+angle_rand_zyx = (sens.GenUniform(low=-2.0,high=2.0),None,None)
+angle_error_data = sens.ErrFieldData(ang_offset_zyx=angle_offset_zyx,
+                                     ang_rand_zyx=angle_rand_zyx)
+
+err_chain_norot: list[sens.IErrSimulator] = [
+    sens.ErrSysField(sens_array_norot.get_field(),angle_error_data),
+]
+sens_array_norot.set_error_chain(err_chain_norot)
+
+
+err_chain_rot: list[sens.IErrSimulator] = [
+    sens.ErrSysField(sens_array_rot.get_field(),angle_error_data),
+]
+sens_array_rot.set_error_chain(err_chain_rot)
+
+#%%
+# 3. Create & run simulated experiment
+# ------------------------------------
+# When we print the measurements here we should see that the truth for the
+# rotated and non-rotated cases is the same. This is because we have rotated the
+# sensors 90 degrees, which means the x (component=0) of the non-rotated case
+# should be the same as the y (component=1) for the rotated case.
+
+meas_rot = sens_array_rot.sim_measurements()
+meas_norot = sens_array_norot.sim_measurements()
+
+print(80*"-")
+
+sens_print: int = 0
+comp_print: int = 0
+time_last: int = 5
+time_print = slice(meas_norot.shape[2]-time_last,meas_norot.shape[2])
+
+print("DISP. SENSORS: NO ROTATION")
+sens.print_measurements(sens_array_norot,sens_print,comp_print,time_print)
+
+comp_print = 1
+print("\nDISP. SENSORS: ROTATED")
+sens.print_measurements(sens_array_rot,sens_print,comp_print,time_print)
+
+print(80*"-")
+
+#%%
+# 4. Analyse & visualise the results
+# ----------------------------------
+
+output_path = Path.cwd() / "pyvale-output"
+if not output_path.is_dir():
+    output_path.mkdir(parents=True, exist_ok=True)
+
+
+pv_plot = sens.plot_point_sensors_on_sim(sens_array_norot,
+                                         comp_key="disp_y")
+pv_plot.camera_position = "xy"
+
+# Set to False to show an interactive plot instead of saving the figure
+pv_plot.off_screen = True
+if pv_plot.off_screen:
+    pv_plot.screenshot(output_path/"ext_ex4c_locs.png")
+else:
+    pv_plot.show()
+
+# %%
+# Virtual sensor locations:
+#
+# .. image:: ../../../../_static/ext_ex4c_locs.png
+#    :alt: Visualisation of virtual sensor locations.
+#    :width: 800px
+#    :align: center
+
+# We can now plot the traces for the non-rotated and rotated sensors to
+# compare them:
+
+for ff in disp_keys:
+    (fig,ax) = sens.plot_time_traces(sens_array_norot,ff)
+    ax[0].set_title("No Rotation")
+
+    save_traces = output_path/f"ext_ex4c_traces_norot_{ff}.png"
+    fig.savefig(save_traces, dpi=300, bbox_inches="tight")
+
+    (fig,ax) = sens.plot_time_traces(sens_array_rot,ff)
+    ax[0].set_title(f"Rotated {sens_rot_deg} deg.")
+
+    save_traces = output_path/f"ext_ex4c_traces_rot_{ff}.png"
+    fig.savefig(save_traces, dpi=300, bbox_inches="tight")
+
+# Uncomment to show trace plots interactively
+# plt.show()
+
+# %%
+# Non-rotated sensors, y displacement:
+#
+# .. image:: ../../../../_static/ext_ex4c_traces_norot_disp_y.png
+#    :alt: Non-rotated sensor traces for the y displacement.
+#    :width: 600px
+#    :align: center
+
+# %%
+# Rotated sensors, x displacement:
+#
+# .. image:: ../../../../_static/ext_ex4c_traces_rot_disp_x.png
+#    :alt: Rotated sensor traces for the x displacement.
+#    :width: 600px
+#    :align: center

pyvale/examples/extsensorsim/ex4d_fieldlockerrs_vec3d.py

@@ -0,0 +1,184 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
+"""
+Errors: field-based position/angle locking
+================================================================================
+
+This example demonstrates how to create field errors on 3D geometries where we
+want to perturb sensor locations and orientation but we want our sensors to stay
+attached to the surfaces they are on. To demonstrate this we will use a
+thermo-mechanical simulation of a 10mm cube where we will place sensors on each
+of the 6 faces of the cube.
+"""
+
+from pathlib import Path
+import numpy as np
+import matplotlib.pyplot as plt
+
+# pyvale imports
+import pyvale.mooseherder as mh
+import pyvale.sensorsim as sens
+import pyvale.dataset as dataset
+
+#%%
+# 1. Load physics simulation data
+# -------------------------------
+
+data_path: Path = dataset.element_case_output_path(dataset.EElemTest.HEX20)
+sim_data: mh.SimData = mh.ExodusLoader(data_path).load_all_sim_data()
+
+disp_keys = ("disp_x","disp_y","disp_z")
+sim_data: mh.SimData = sens.scale_length_units(scale=1000.0,
+                                               sim_data=sim_data,
+                                               disp_keys=disp_keys)
+
+#%%
+# 2. Build virtual sensor arrays
+# --------------------------------
+
+# Simulation is a 10mm cube
+sensor_positions = np.array(((5.0,0.0,5.0),     # cube x-z face
+                             (5.0,10.0,5.0),    # cube x-z face
+                             (5.0,5.0,0.0),     # cube x-y face
+                             (5.0,5.0,10.0),    # cube x-y face
+                             (0.0,5.0,5.0),     # cube y-z face
+                             (10.0,5.0,5.0),))  # cube y-z face
+
+sample_times = np.linspace(0.0,np.max(sim_data.time),50)
+
+sens_data = sens.SensorData(positions=sensor_positions,
+                            sample_times=sample_times)
+
+
+sens_array: sens.SensorsPoint = sens.SensorFactory.vector_point(
+    sim_data,
+    sens_data,
+    comp_keys=disp_keys,
+    spatial_dims=sens.EDim.THREED,
+    descriptor=sens.DescriptorFactory.displacement(),
+)
+
+#%%
+# 2.1. Add simulated measurement errors
+# ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+# Our simulation is a cube and we have sensors on the midpoint of each face of
+# the cube. We want to allow our sensors positions and orientation to be
+# perturbed as part of our uncertainty simulation but we want the sensors to
+# stay attached to the faces of the cube they are located on
+
+
+pos_uncert = 1.0 # units = mm
+pos_rand = (sens.GenUniform(low=-pos_uncert,high=pos_uncert),
+            sens.GenUniform(low=-pos_uncert,high=pos_uncert),
+            sens.GenUniform(low=-pos_uncert,high=pos_uncert))
+
+pos_lock = np.full(sensor_positions.shape,False,dtype=bool)
+pos_lock[0,1] = True # cube x-z face, lock y
+pos_lock[1,1] = True # cube x-z face, lock y
+pos_lock[2,2] = True # cube x-y face, lock z
+pos_lock[3,2] = True # cube x-y face, lock z
+pos_lock[4,0] = True # cube y-z face, lock x
+pos_lock[5,0] = True # cube y-z face, lock x
+
+ang_uncert = 2.0 # units = degrees
+ang_rand = (sens.GenUniform(low=-ang_uncert,high=ang_uncert),
+            sens.GenUniform(low=-ang_uncert,high=ang_uncert),
+            sens.GenUniform(low=-ang_uncert,high=ang_uncert))
+
+ang_lock = np.full(sensor_positions.shape,True,dtype=bool)
+ang_lock[0,1] = False # cube x-z face, unlock/rotate about y
+ang_lock[1,1] = False # cube x-z face, unlock/rotate about y
+ang_lock[2,2] = False # cube x-y face, unlock/rotate about z
+ang_lock[3,2] = False # cube x-y face, unlock/rotate about z
+ang_lock[4,0] = False # cube y-z face, unlock/rotate about x
+ang_lock[5,0] = False # cube y-z face, unlock/rotate about x
+
+field_err_data = sens.ErrFieldData(pos_rand_xyz=pos_rand,
+                                   pos_lock_xyz=pos_lock)
+
+error_chain: list[sens.IErrSimulator] = [
+    sens.ErrSysField(sens_array.get_field(),field_err_data),
+    sens.ErrSysGenPercent(sens.GenUniform(low=-1.0,high=1.0),
+                          sens.EErrDep.DEPENDENT),
+    sens.ErrRandGenPercent(sens.GenNormal(std=1.0),sens.EErrDep.DEPENDENT),
+]
+
+sens_array.set_error_chain(error_chain)
+
+
+#%%
+# 3. Run a simulated experiment
+# -----------------------------
+
+measurements: np.ndarray = sens_array.sim_measurements()
+
+truth: np.ndarray = sens_array.get_truth()
+sys_errs: np.ndarray = sens_array.get_errors_systematic()
+rand_errs: np.ndarray = sens_array.get_errors_random()
+
+print(80*"-")
+print("measurement = truth + sysematic error + random error")
+
+print(f"measurements.shape = {measurements.shape} = "
+        + "(n_sensors,n_field_components,n_timesteps)")
+print(f"truth.shape     = {truth.shape}")
+print(f"sys_errs.shape  = {sys_errs.shape}")
+print(f"rand_errs.shape = {rand_errs.shape}")
+
+sens_print: int = 2 # x-y face sensor
+comp_print: int = 1 # component=disp_y
+time_last: int = 5
+time_print = slice(measurements.shape[2]-time_last,measurements.shape[2])
+
+print(f"\nThese are the last {time_last} virtual measurements of sensor "
+        + f"{sens_print}:\n")
+
+sens.print_measurements(sens_array,sens_print,comp_print,time_print)
+print("\n"+80*"-")
+
+#%%
+# 4. Analyse & visualise the results
+# ----------------------------------
+
+output_path = Path.cwd() / "pyvale-output"
+if not output_path.is_dir():
+    output_path.mkdir(parents=True, exist_ok=True)
+
+for kk in disp_keys:
+    pv_plot = sens.plot_point_sensors_on_sim(sens_array,kk)
+    pv_plot.camera_position = "yz"
+    pv_plot.camera.azimuth = 45
+    pv_plot.camera.elevation = 45
+
+    # Set to False to show an interactive plot instead of saving the figure
+    pv_plot.off_screen = True
+    if pv_plot.off_screen:
+        pv_plot.screenshot(output_path/f"ext_ex4d_locs_{kk}.png")
+    else:
+        pv_plot.show()
+
+# %%
+# .. image:: ../../../../_static/ext_ex4d_locs_disp_y.png
+#    :alt: Virtual sensor location visualisation.
+#    :width: 800px
+#    :align: center
+
+
+for kk in disp_keys:
+    (fig,ax) = sens.plot_time_traces(sens_array,comp_key=kk)
+    fig.savefig(output_path/f"ext_ex4d_traces_{kk}.png",
+                dpi=300,
+                bbox_inches="tight")
+
+# Uncomment this to display the sensor trace plot
+# plt.show()
+
+# %%
+# .. image:: ../../../../_static/ext_ex4d_traces_disp_y.png
+#    :alt: Simulated sensor traces.
+#    :width: 600px
+#    :align: center