pyvale 2026.1.1__cp311-cp311-manylinux_2_17_i686.manylinux2014_i686.whl

pyvale/examples/extsensorsim/ex4e_chainfielderrs_vec2d.py

@@ -0,0 +1,233 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
+"""
+Errors: field-based chaining
+================================================================================
+
+In this example we show how field errors can be chained together and accumulated
+allowing for successive perturbations in position, sampling time and orientation.
+In order to do this we need to set our field error to be 'dependent'. Note that
+it is more computationally efficient to provide a single field error object as
+this will perform all perturbations in a single step allowing for a single new
+interpolation of the underlying physical field. However, in some cases it can
+be useful to separate the sensor parameter perturbations to determine which is
+contributing most to the total error.
+
+Under the hood the `pyvale` sensor simulation module uses and
+"""
+
+from pathlib import Path
+import numpy as np
+from scipy.spatial.transform import Rotation
+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.mechanical_2d_path()
+sim_data: mh.SimData = mh.ExodusLoader(data_path).load_all_sim_data()
+
+disp_keys = ("disp_x","disp_y")
+strain_norm_keys = ("strain_xx","strain_yy",)
+strain_dev_keys = ("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: tuple[Rotation] = (
+    Rotation.from_euler("zyx",[0,0,0], degrees=True),
+)
+
+sens_data = sens.SensorData(positions=sens_pos,
+                            sample_times=sample_times,
+                            angles=sens_angles)
+
+sens_array: sens.SensorsPoint = sens.SensorFactory.vector_point(
+    sim_data,
+    sens_data,
+    comp_keys=disp_keys,
+    spatial_dims=sens.EDim.TWOD,
+    descriptor=sens.DescriptorFactory.displacement(),
+)
+
+#%%
+# 2.1. Add simulated measurement errors
+# ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+#%%
+#
+# Now we will build a series of field errors that cause successive offsets in
+# sensor sampling time, sensor position and sensor orientation. That way
+# we should be able to analyse the sensor data object at each point in the
+# error chain to see how the sensor parameters have accumulated.
+# We will apply a position offset of -1.0mm in the x and y axes.
+pos_offset = -1.0*np.ones_like(sens_pos)
+pos_offset[:,2] = 0.0 # in 2d we only have offset in x and y so zero z
+pos_error_data = sens.ErrFieldData(pos_offset_xyz=pos_offset)
+
+#%%
+# We will then  apply a rotation offset about the z axis of 1 degree
+angle_offset = np.zeros_like(sens_pos)
+angle_offset[:,0] = 1.0 # only rotate about z in 2D
+angle_error_data = sens.ErrFieldData(ang_offset_zyx=angle_offset)
+
+time_offset = 2.0*np.ones_like(sens_array.get_sample_times())
+time_error_data = sens.ErrFieldData(time_offset=time_offset)
+
+#%%
+# Now we add all our field errors to our error chain. We add each error
+# twice to see how they accumulate with each other. We explicitly set the
+# error dependence to `DEPENDENT` so that the sensor state is accumulated
+# over the error chain. Note that `DEPENDENT` is the default for field errors 
+# so that the perturbations to the sensor data are accumulated.
+  
+err_chain: list[sens.IErrSimulator] = [
+    sens.ErrSysField(sens_array.get_field(),
+                     time_error_data,
+                     sens.EErrDep.DEPENDENT),
+    sens.ErrSysField(sens_array.get_field(),
+                     time_error_data,
+                     sens.EErrDep.DEPENDENT),
+    sens.ErrSysField(sens_array.get_field(),
+                     pos_error_data,
+                     sens.EErrDep.DEPENDENT),
+    sens.ErrSysField(sens_array.get_field(),
+                     pos_error_data,
+                     sens.EErrDep.DEPENDENT),
+    sens.ErrSysField(sens_array.get_field(),
+                     angle_error_data,
+                     sens.EErrDep.DEPENDENT),
+    sens.ErrSysField(sens_array.get_field(),
+                     angle_error_data,
+                     sens.EErrDep.DEPENDENT),
+]
+
+#%%
+# Instead of setting the dependence for each individual error above we could
+# also just use our error integration options to force all errors to be
+# `DEPENDENT`. We also set the error integration options to store the errors
+# for each step in the error chain so we can analyse the sensor data at each
+# step of chain. This option also allows us to separate the contribution of
+# each error in the chain to the total error rather than just being able to
+# analyse the total systematic and total random error which is the default.
+# Note that this option will use more memory.
+
+err_int_opts = sens.ErrIntOpts(force_dependence=sens.EErrDep.DEPENDENT,
+                               store_all_errs=True)
+
+sens_array.set_error_chain(err_chain,err_int_opts)
+
+
+#%%
+# 3. Create & run simulated experiment
+# ------------------------------------
+# Here we will print to the console the time, position and angle of from the
+# sensor data objects at each point in the error chain. We should see each
+# sensor parameter perturbed and accumulated throughout the chain.
+
+measurements = sens_array.sim_measurements()
+
+err_int = sens_array.get_error_integrator()
+
+sens_data_by_chain = err_int.get_sens_data_by_chain()
+if sens_data_by_chain is not None:
+    for ii,ss in enumerate(sens_data_by_chain):
+        print(80*"-")
+        if ss is not None:
+            print(f"SensorData @ [{ii}]")
+            print("TIME")
+            print(ss.sample_times)
+            print()
+            print("POSITIONS")
+            print(ss.positions)
+            print()
+            print("ANGLES")
+            for aa in ss.angles:
+                print(aa.as_euler("zyx",degrees=True))
+            print()
+        print(80*"-")
+
+#%%
+# Try setting all the field errors to be `INDEPENDENT` using the error
+# integration options above. You should see that the sensor parameters are
+# not accumulated throughout the error chain.
+#
+# Wen ow  print the results for one of the sensors so we can see what the errors
+# are for the last few sampling times.
+print(80*"-")
+
+sens_print = 0
+comp_print = 0
+time_last = 5
+time_print = slice(measurements.shape[2]-time_last,measurements.shape[2])
+
+print("SENSORS WITH ACCUMULATED FIELD ERRORS:")
+print(f"These are the last {time_last} virtual measurements of sensor "
+        + f"{sens_print} for {disp_keys[comp_print]}:")
+
+sens.print_measurements(sens_array,sens_print,comp_print,time_print)
+
+print(80*"-")
+
+#%%
+# 4. 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,"disp_y")
+pv_plot.camera_position = "xy"
+
+save_render = output_path/"ext_ex4e_locs.png"
+
+pv_plot.off_screen = True
+if pv_plot.off_screen:
+    pv_plot.screenshot(save_render)
+else:
+    pv_plot.show()
+
+# %%
+# .. image:: ../../../../_static/ext_ex4e_locs.png
+#    :alt: Virtual sensor locations.
+#    :width: 800px
+#    :align: center
+
+for kk in disp_keys:
+    (fig,ax) = sens.plot_time_traces(sens_array,kk)
+    save_traces = output_path/f"ext_ex4e_traces_{kk}.png"
+    fig.savefig(save_traces, dpi=300, bbox_inches="tight")
+
+# Uncomment this to display the sensor trace plot
+# plt.show()
+
+# %%
+# .. image:: ../../../../_static/ext_ex4e_traces_disp_y.png
+#    :alt: Simulated sensor traces.
+#    :width: 600px
+#    :align: center

pyvale/examples/extsensorsim/ex4f_caliberrs_scal2d.py

@@ -0,0 +1,167 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
+"""
+Errors: calibration
+================================================================================
+
+In this example we show how `pyvale` can simulate sensor calibration errors with
+user defined calibration functions.
+"""
+
+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
+
+
+#%%
+# Calibration Functions
+# ---------------------
+# First we need to define some calibration functions. These functions must take
+# a numpy array and return a numpy array of the same shape. We start by
+# defining what we think our calibration is called `calib_assumed()` and then
+# we also need to define the ground truth calibration `calib_truth()` so that
+# we can calculate the error between them. The calibration functions shown below
+# are simplified versions of the typical calibration curves for a K-type
+# thermocouple.
+
+def calib_assumed(signal: np.ndarray) -> np.ndarray:
+    return 24.3*signal + 0.616
+
+
+def calib_truth(signal: np.ndarray) -> np.ndarray:
+    return -0.01897 + 25.41881*signal - 0.42456*signal**2 + 0.04365*signal**3
+
+#%%
+# We are first going to do a quick analytical calculation for the minimum
+# and maximum systematic error we expect between our assumed and true
+# calibration. For our true calibration we know this holds between 0 and 6mV
+# so we perform the calculation over this range and print the min/max
+# expected error over this range.
+n_cal_divs = 10000
+signal_calib_range = np.array((0.0,6.0),dtype=np.float64)
+milli_volts = np.linspace(signal_calib_range[0],
+                            signal_calib_range[1],
+                            n_cal_divs)
+temp_truth = calib_truth(milli_volts)
+temp_assumed = calib_assumed(milli_volts)
+calib_error = temp_assumed - temp_truth
+
+print()
+print(80*"-")
+print(f"Max calibrated temperature: {np.min(temp_truth)} degC")
+print(f"Min calibrated temperature: {np.max(temp_truth)} degC")
+print()
+print(f"Calibration error over signal:"
+        + f" {signal_calib_range[0]} to {signal_calib_range[1]} mV")
+print(f"Max calib error: {np.max(calib_error)}")
+print(f"Min calib error: {np.min(calib_error)}")
+print(80*"-")
+print()
+
+# %%
+# .. image:: ../../../../_static/ext_ex4f_term_out_0.png
+#    :alt: Terminal output.
+#    :width: 700px
+#    :align: center
+
+#%%
+# 1. Load physics simulation data
+# -------------------------------
+data_path: Path = dataset.thermal_2d_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: dict[str,tuple[float,float]] = sens.simtools.get_sim_dims(sim_data)
+sens_pos: np.ndarray = sens.gen_pos_grid_inside(num_sensors=(3,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_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.TWOD,
+    descriptor=sens.DescriptorFactory.temperature(),
+)
+
+#%%
+# 2.1. Add simulated measurement errors
+# ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+# With our assumed and true calibration functions we can build our
+# calibration error object and add it to our error chain as normal. Note
+# that the truth calibration function must be inverted numerically so to
+# increase accuracy the number of divisions can be increased. However, 1e4
+# divisions should be suitable for most applications.
+
+cal_err = sens.ErrSysCalibration(calib_assumed,
+                                 calib_truth,
+                                 signal_calib_range,
+                                 n_cal_divs=10000)
+sens_array.set_error_chain([cal_err,])
+
+#%%
+# 3. Run a simulated experiment
+# ------------------------------------
+measurements = sens_array.sim_measurements()
+
+print(80*"-")
+
+sens_print = 0
+comp_print = 0
+time_last = 5
+time_print = slice(measurements.shape[2]-time_last,measurements.shape[2])
+
+print(f"These are the last {time_last} virtual measurements of sensor "
+        + f"{sens_print}:")
+
+sens.print_measurements(sens_array,sens_print,comp_print,time_print)
+
+print(80*"-")
+
+# %%
+# .. image:: ../../../../_static/ext_ex4f_term_out_1.png
+#    :alt: Terminal output.
+#    :width: 700px
+#    :align: center
+
+#%%
+# 4. Visualise the results
+# ------------------------
+
+output_path = Path.cwd() / "pyvale-output"
+if not output_path.is_dir():
+    output_path.mkdir(parents=True, exist_ok=True)
+
+(fig,ax) = sens.plot_time_traces(sens_array,comp_key="temperature")
+save_traces = output_path/"ext_ex4f_traces.png"
+fig.savefig(save_traces, dpi=300, bbox_inches="tight")
+
+# Uncomment this to display the sensor trace plot
+# plt.show()
+
+# %%
+# .. image:: ../../../../_static/ext_ex4f_traces.png
+#    :alt: Simulated sensor traces.
+#    :width: 600px
+#    :align: center

pyvale/examples/extsensorsim/ex4g_spatavgerrs_scal2d.py

@@ -0,0 +1,146 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
+"""
+Errors: spatial averaging
+================================================================================
+
+In this example we show how `pyvale` can simulate sensor spatial averaging for
+ground truth calculations as well as for calculating systematic errors.
+"""
+
+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_2d_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 arrays
+# --------------------------------
+# Now we are going to build a scalar field sensor array so we can control how
+# the ground truth is extracted for a sensor using area averaging. Note that
+# the default is an ideal point sensor with no spatial averaging. Later we
+# will add area averaging as a systematic error. Note that it is possible to
+# have an ideal point sensor with no area averaging for the truth and then
+# add an area averaging error. It is also possible to have a truth that is
+# area averaged without and area averaging error. Finally, you can specify
+# different averaging areas for the truth and systematic errors.
+
+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=(3,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)
+
+#%%
+# This is where we control the setup of the area averaging. We need to
+# specify the sensor dimensions and the type of numerical spatial
+# integration to use. Here we specify a square sensor in x and y with 4
+# point Gaussian quadrature integration. It is worth noting that increasing
+# the number of integration points will increase computational cost as each
+# additional integration point requires an additional interpolation of the
+# physical field.
+
+sensor_dims = np.array([5.0,5.0,0]) # units = mm
+
+sens_data = sens.SensorData(positions=sens_pos,
+                            sample_times=sample_times,
+                            spatial_averager=sens.EIntSpatialType.QUAD4PT,
+                            spatial_dims=sensor_dims)
+
+#%%
+# We have added spatial averaging to our sensor data so we can now create
+# our sensor array as we have done in previous examples.
+sens_array: sens.SensorsPoint = sens.SensorFactory.scalar_point(
+    sim_data,
+    sens_data,
+    comp_key="temperature",
+    spatial_dims=sens.EDim.TWOD,
+    descriptor=sens.DescriptorFactory.temperature(),
+)
+
+
+#%%
+# 2.1. Add simulated measurement errors
+# ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+# We are going to create a field error that includes area averaging as
+# an error. We do this by adding the option to our field error data class
+# specifying rectangular integration with 1 point.
+
+area_avg_err_data = sens.ErrFieldData(
+    spatial_averager=sens.EIntSpatialType.RECT1PT,
+    spatial_dims=np.array((20.0,20.0)),
+)
+
+#%%
+# We add the field error to our error chain as normal. We could combine it
+# with any of our other error models but we will isolate it for now so we
+# can see what it does.
+
+err_chain: list[sens.IErrSimulator] = [
+    sens.ErrSysField(sens_array.get_field(),area_avg_err_data),
+]
+
+sens_array.set_error_chain(err_chain)
+
+#%%
+# 3. Run a simulated experiment
+# -----------------------------
+# Now we run our sensor simulation to see how spatial averaging changes our
+# simulated measurement results.
+
+measurements = sens_array.sim_measurements()
+
+print(80*"-")
+sens_print = 0
+comp_print = 0
+time_last = 5
+time_print = slice(measurements.shape[2]-time_last,measurements.shape[2])
+
+print(f"These are the last {time_last} virtual measurements of sensor "
+        + f"{sens_print}:")
+
+sens.print_measurements(sens_array,sens_print,comp_print,time_print)
+print(80*"-")
+
+#%%
+# 4. Visualise the results
+# ------------------------
+
+output_path = Path.cwd() / "pyvale-output"
+if not output_path.is_dir():
+    output_path.mkdir(parents=True, exist_ok=True)
+
+(fig,ax) = sens.plot_time_traces(sens_array,comp_key="temperature")
+save_traces = output_path/"ext_ex4g_traces.png"
+fig.savefig(save_traces, dpi=300, bbox_inches="tight")
+
+# Uncomment this to display the sensor trace plot
+# plt.show()
+
+# %%
+# .. image:: ../../../../_static/ext_ex4g_traces.png
+#    :alt: Simulated sensor traces.
+#    :width: 600px
+#    :align: center
+
+