pyvale 2025.4.0__py3-none-any.whl → 2025.5.1__py3-none-any.whl

pyvale/examples/basics/ex1_2_sensormodel_therm2d.py

@@ -0,0 +1,158 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
+"""
+Pyvale example: Sensor model & `get_measurements()` vs `calc_measurements()`
+--------------------------------------------------------------------------------
+In this example we explain the pyvale virtual sensor measurement model. For a
+virtual sensor in pyvale a measurement is defined as measurement = truth +
+systematic error + random error. Sources of systematic errors include: spatial/
+temporal averaging, uncertainty in position / sampling time / orientation,
+digitisation, saturation, and calibration. Sources of random error are generally
+due to measurement noise characterised by a given probability distribution.
+
+Random errors can be mitigated by performing multiple experiments and averaging.
+However, systematic errors cannot easily be accounted for without a forward
+model of the source of the error. Characterising the contribution of systematic
+errors to the total measurement error is a key application of `pyvale`.
+
+between the `get_measurements()` and `calc_measurements()` methods for a sensor
+array. Calling `get_measurements()` retrieves the results for the current
+simulated experiment whereas calling `calc_measurements()` will generate a new
+simulated experiment by sampling / calculating the systematic and random errors.
+
+Test case: Scalar field point sensors (thermocouples) on a 2D thermal simulation
+"""
+
+import matplotlib.pyplot as plt
+import mooseherder as mh
+import pyvale as pyv
+
+
+def main() -> None:
+    # The first part of this example is the similar to basics example 1.1, so
+    # feel free to skip to after the first call to `calc_measurements()`.
+
+    # Here we load a pre-generated MOOSE finite element simulation dataset that
+    # comes packaged with pyvale. The simulation is a 2D rectangular plate with
+    # a bi-directional temperature gradient.
+    data_path = pyv.DataSet.thermal_2d_path()
+    sim_data = mh.ExodusReader(data_path).read_all_sim_data()
+    field_key: str = "temperature"
+    # Scale to mm to make 3D visualisation scaling easier as pyvista scales
+    # everything to unity
+    sim_data = pyv.scale_length_units(scale=1000.0,
+                                      sim_data=sim_data,
+                                      disp_comps=None)
+
+    # We now use a helper function to create a grid of sensor locations but we
+    # could have also manually built the numpy array of sensor locations which
+    # has the shape=(num_sensors,coord[x,y,z]).
+    n_sens = (4,1,1)
+    x_lims = (0.0,100.0)
+    y_lims = (0.0,50.0)
+    z_lims = (0.0,0.0)
+    sens_pos = pyv.create_sensor_pos_array(n_sens,x_lims,y_lims,z_lims)
+
+    # This dataclass contains the parameters to build our sensor array. We can
+    # also customise the output frequency, the sensor area and the sensor
+    # orientation. For now we will use the defaults which assumes an ideal point
+    # sensor sampling at the simulation time steps.
+    sens_data = pyv.SensorData(positions=sens_pos)
+
+    # Now that we have our sensor locations we can use the sensor factory to
+    # build a basic thermocouple array with some useful defaults. In later
+    # examples we will see how to customise sensor parameters and errors.
+    # This basic thermocouple array includes a 5% systematic and random error -
+    # We are specifically using exaggerated errors here for visualisation.
+    tc_array = pyv.SensorArrayFactory \
+        .thermocouples_basic_errs(sim_data,
+                                  sens_data,
+                                  elem_dims=2,
+                                  field_name=field_key,
+                                  errs_pc=5.0)
+
+
+    # We have built our sensor array so now we can call `calc_measurements()` to
+    # generate simulated sensor traces.
+    measurements = tc_array.calc_measurements()
+
+    # From here we are going to experiment with repeated calls to
+    # `calc_measurements()` and `get_measurements()` for our sensor array. We
+    # will print the results to the console as well as plotting time traces of
+    # the simulated sensor output. All further explanations are in the print
+    # statements below.
+
+    print("\n"+80*"-")
+    print("For a sensor array: "
+          + "measurement = truth + sysematic error + random error")
+    print(f"\nmeasurements.shape = {measurements.shape} = "
+          + "(n_sensors,n_field_components,n_timesteps)\n")
+    print("Here we have a scalar temperature field so only 1 field component.")
+    print("The truth, systematic error and random error arrays all have the "+
+          "same shape.")
+
+    sens_print: int = 0
+    time_print: int = 5
+    comp_print: int = 0
+
+    print(80*"-")
+    print(f"Looking at the last {time_print} virtual measurements" +
+          f" of sensor {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*"-")
+    print("If we call the `calc_measurements()` method then the errors are "
+          + "re-calculated.")
+    measurements = tc_array.calc_measurements()
+
+    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]))
+
+    (fig,ax) = pyv.plot_time_traces(tc_array,field_key)
+    ax.set_title("Exp 1: called calc_measurements()")
+
+    print(80*"-")
+    print("If we call the `get_measurements()` method then the errors are the "
+          + "same:")
+    measurements = tc_array.get_measurements()
+
+    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]))
+
+    (fig,ax) = pyv.plot_time_traces(tc_array,field_key)
+    ax.set_title("Exp 2: called get_measurements()")
+
+    print(80*"-")
+    print("If we call the `calc_measurements()` method again we generate / "
+          "sample new errors:")
+    measurements = tc_array.calc_measurements()
+
+    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]))
+
+    (fig,ax) = pyv.plot_time_traces(tc_array,field_key)
+    ax.set_title("Exp 3: called calc_measurements()")
+
+    print(80*"-")
+
+    plt.show()
+
+if __name__ == "__main__":
+    main()

pyvale/examples/basics/ex1_3_customsens_therm3d.py

@@ -0,0 +1,216 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
+"""
+Pyvale example: Building a point sensor array from scratch with custom errors
+--------------------------------------------------------------------------------
+Here we build a custom point sensor array from scratch that is similar to the
+pre-built thermocouple array from example 1.1. For this example we switch to a
+3D thermal simulation of a fusion heatsink component.
+
+Test case: Scalar field point sensors (thermocouples) on a 3D thermal simulation
+"""
+
+from pathlib import Path
+import numpy as np
+import matplotlib.pyplot as plt
+import mooseherder as mh
+import pyvale as pyv
+
+
+def main() -> None:
+    # To build our custom point sensor array we need to at minimum provide a
+    # `IField` (i.e. `FieldScaler`, `FieldVector`, `FieldTensor`) and a
+    # `SensorData` object. For labelling visualisations (e.g. axis labels and
+    # unit labels) we can also provide a `SensorDescriptor` object.
+    # Once we have built our `SensorArrayPoint` object from these we can then
+    # attach custom chains of different types of random and systematic errors
+    # to be evaluated when we run our measurement simulation. This example is
+    # based on the same thermal example we have used in the last two examples so
+    # we start by loading our simulation data:
+
+    data_path = pyv.DataSet.thermal_3d_path()
+    sim_data = mh.ExodusReader(data_path).read_all_sim_data()
+    # Scale to mm to make 3D visualisation scaling easier as pyvista scales
+    # everything to unity
+    sim_data = pyv.scale_length_units(scale=1000.0,
+                                      sim_data=sim_data,
+                                      disp_comps=None)
+
+    # We are going to build a custom temperature sensor so we need a scalar
+    # field object to perform interpolation to the sensor locations at the
+    # desired sampling times.
+    field_key: str = "temperature"
+    t_field = pyv.FieldScalar(sim_data,
+                              field_key=field_key,
+                              elem_dims=3)
+
+
+    # Next we need to create our `SensorData` object which will set the position
+    # and sampling times of our sensors. We use the same helper function we used
+    # previously to create a uniformly spaced grid of sensors in space
+    n_sens = (1,4,1)
+    x_lims = (12.5,12.5)
+    y_lims = (0.0,33.0)
+    z_lims = (0.0,12.0)
+    sens_pos = pyv.create_sensor_pos_array(n_sens,x_lims,y_lims,z_lims)
+
+    # We are also going to specify the times at which we would like to simulate
+    # measurements. Setting this to `None` will default the measurements times
+    # to match the simulation time steps.
+    sample_times = np.linspace(0.0,np.max(sim_data.time),50)
+
+    sensor_data = pyv.SensorData(positions=sens_pos,
+                                 sample_times=sample_times)
+
+    # Finally, we can create a `SensorDescriptor` which will be used to label
+    # the visualisation and sensor trace plots we have seen in previous
+    # examples.
+    use_auto_descriptor: str = "blank"
+    if use_auto_descriptor == "manual":
+        descriptor = pyv.SensorDescriptor(name="Temperature",
+                                          symbol="T",
+                                          units = r"^{\circ}C",
+                                          tag = "TC")
+    elif use_auto_descriptor == "factory":
+        descriptor = pyv.SensorDescriptorFactory.temperature_descriptor()
+    else:
+        descriptor = pyv.SensorDescriptor()
+
+
+    # We can now build our custom point sensor array. This sensor array has no
+    # errors so if we call `get_measurements()` or `calc_measurements()` we will
+    # be able to extract the simulation truth values at the sensor locations.
+    tc_array = pyv.SensorArrayPoint(sensor_data,
+                                    t_field,
+                                    descriptor)
+
+    # This is a new 3D simulation we are analysing so we should visualise the
+    # sensor locations before we run our measurement simulation. We use the same
+    # code as we did in example 1.1 to display the sensor locations.
+
+    # We are also going to save some figures to disk as well as displaying them
+    # interactively so we create a directory for this:
+    output_path = Path.cwd() / "pyvale-output"
+    if not output_path.is_dir():
+        output_path.mkdir(parents=True, exist_ok=True)
+
+    pv_plot = pyv.plot_point_sensors_on_sim(tc_array,field_key)
+
+    pv_plot.camera_position = [(59.354, 43.428, 69.946),
+                               (-2.858, 13.189, 4.523),
+                               (-0.215, 0.948, -0.233)]
+
+    save_render = output_path / "customsensors_ex1_3_sensorlocs.svg"
+    pv_plot.save_graphic(save_render) # only for .svg .eps .ps .pdf .tex
+    pv_plot.screenshot(save_render.with_suffix(".png"))
+
+    pv_plot.show()
+
+    # If we want to simulate sources of uncertainty for our sensor array we need
+    # to add an `ErrIntegrator` to our sensor array using the method
+    # `set_error_integrator()`. We provide our `ErrIntegrator` a list of error
+    # objects which will be evaluated in the order specified in the list.
+    #
+    # In pyvale errors have a type specified as: random / systematic
+    # (`EErrorType`) and a dependence `EErrDependence` as: independent /
+    # dependent. When analysing errors all random all systematic errors are
+    # grouped and summed together.
+    #
+    # The error dependence determines if an error is
+    # calculated based on the truth (independent) or the accumulated measurement
+    # based on all previous errors in the chain (dependent). Some errors are
+    # purely independent such as random noise with a normal distribution with a
+    # set standard devitation. An example of an error that is dependent would be
+    # saturation which must be place last in the error chain and will clamp the
+    # final sensor value to be within the specified bounds.
+    #
+    # pyvale provides a library of different random `ErrRand*` and systematic
+    # `ErrSys*` errors which can be found listed in the docs. In the next
+    # example we will explore the error library but for now we will specify some
+    # common error types. Try experimenting with the code below to turn the
+    # different error types off and on to see how it changes the virtual sensor
+    # measurements.
+    errors_on = {"sys": True,
+                 "rand": True}
+
+    error_chain = []
+    if errors_on["sys"]:
+        # This systematic error is just a constant offset of -5 to all simulated
+        # measurements. Note that error values should be specified in the same
+        # units as the simulation.
+        error_chain.append(pyv.ErrSysOffset(offset=-10.0))
+
+        # This systematic error samples from a uniform probability distribution.
+        error_chain.append(pyv.ErrSysUnif(low=-10.0,
+                                             high=10.0))
+
+    if errors_on["rand"]:
+        # This random error is generated by sampling from a normal distribution
+        # with the given standard deviation in simulation units.
+        error_chain.append(pyv.ErrRandNorm(std=5.0))
+
+        # This random error is generated as a percentage sampled from uniform
+        # probability distribution
+        error_chain.append(pyv.ErrRandUnifPercent(low_percent=-5.0,
+                                                  high_percent=5.0))
+
+
+    # By default pyvale does not store all individual error source
+    # calculations (i.e. only the total random and total systematic error are
+    # stored) to save memory but this can be changed using `ErrIntOpts`. This
+    # can also be used to force all errors to behave if they
+
+    if len(error_chain) > 0:
+        err_int_opts = pyv.ErrIntOpts()
+        error_integrator = pyv.ErrIntegrator(error_chain,
+                                             sensor_data,
+                                             tc_array.get_measurement_shape(),
+                                             err_int_opts=err_int_opts)
+        tc_array.set_error_integrator(error_integrator)
+
+
+    # Now that we have added our error chain we can run a simulation to sample
+    # from all our error sources.
+    measurements = tc_array.calc_measurements()
+
+    # We display the simulation results by printing to the console and by
+    # plotting the sensor times traces. Try experimenting with the errors above
+    # to see how the results change.
+    print("\n"+80*"-")
+    print("For a virtual sensor: measurement = truth + sysematic error + random error")
+    print(f"measurements.shape = {measurements.shape} = "+
+          "(n_sensors,n_field_components,n_timesteps)\n")
+    print("The truth, systematic error and random error arrays have the same "+
+          "shape.")
+
+    print(80*"-")
+
+    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*"-")
+
+    (fig,ax) = pyv.plot_time_traces(tc_array,field_key)
+
+    save_traces = output_path/"customsensors_ex1_3_sensortraces.png"
+    fig.savefig(save_traces, dpi=300, bbox_inches="tight")
+    fig.savefig(save_traces.with_suffix(".svg"), dpi=300, bbox_inches="tight")
+
+    plt.show()
+
+
+if __name__ == "__main__":
+    main()

pyvale/examples/basics/ex1_4_basicerrors_therm3d.py

@@ -0,0 +1,153 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
+"""
+Pyvale example: Overview of the basic error library
+--------------------------------------------------------------------------------
+Building on what we learned in examples 1.1-1.3 we now have a look at the basic
+error library for pyvale. The sensor error models in pyvale are grouped into the
+types of random (`ErrRand*`) and systematic (`ErrSys*`). In this example we will
+consider probability distribution based sampled errors, constant offsets and
+basic systematic errors such as digitisation / saturation.
+
+In the next examples we will consider more advanced error sources including:
+field errors that perturb the sensor parameters (e.g. location, sampling time
+and orientation) requiring re-interpolation of the underlying field data; and
+calibration errors.
+
+Test case: Scalar field point sensors (thermocouples) on a 3D thermal simulation
+
+Advanced users: It is also possible to write custom errors by writing your own
+class that implements the `IErrCalculator` abstract base class and then add them
+to your error chain.
+"""
+
+import numpy as np
+import matplotlib.pyplot as plt
+import mooseherder as mh
+import pyvale as pyv
+
+
+def main() -> None:
+    # First we use everything we learned from the first three examples to build
+    # a thermocouple sensor array for the same 3D thermal simulation we have
+    # analysed in the previous example.
+    data_path = pyv.DataSet.thermal_3d_path()
+    sim_data = mh.ExodusReader(data_path).read_all_sim_data()
+    sim_data = pyv.scale_length_units(scale=1000.0,
+                                      sim_data=sim_data,
+                                      disp_comps=None)
+    n_sens = (1,4,1)
+    x_lims = (12.5,12.5)
+    y_lims = (0.0,33.0)
+    z_lims = (0.0,12.0)
+    sens_pos = pyv.create_sensor_pos_array(n_sens,x_lims,y_lims,z_lims)
+
+    sample_times = np.linspace(0.0,np.max(sim_data.time),50) # | None
+
+    sensor_data = pyv.SensorData(positions=sens_pos,
+                                sample_times=sample_times)
+
+    field_key: str = "temperature"
+    tc_array = pyv.SensorArrayFactory \
+        .thermocouples_no_errs(sim_data,
+                               sensor_data,
+                               elem_dims=3,
+                               field_name=field_key)
+
+    # Now we have our thermocouple array applied to our simulation without any
+    # errors we can build a custom chain of basic errors. Here we will start by
+    # adding a series of systematic errors that are independent:
+    err_chain = []
+
+    # For probability sampling systematic errors the distribution is sampled to
+    # provide an offset which is assumed to be constant over all sensor sampling
+    # times. This is different to random errors which are sampled to provide a
+    # different error for each sensor and time step.
+
+    # These systematic errors provide a constant offset to all measurements in
+    # simulation units or as a percentage.
+    err_chain.append(pyv.ErrSysOffset(offset=-10.0))
+    err_chain.append(pyv.ErrSysOffsetPercent(offset_percent=-1.0))
+
+    # These systematic errors are sampled from a uniform or normal probability
+    # distribution either in simulation units or as a percentage.
+    err_chain.append(pyv.ErrSysUnif(low=-1.0,
+                                    high=1.0))
+    err_chain.append(pyv.ErrSysUnifPercent(low_percent=-1.0,
+                                           high_percent=1.0))
+    err_chain.append(pyv.ErrSysNorm(std=1.0))
+    err_chain.append(pyv.ErrSysNormPercent(std_percent=1.0))
+
+    # pyvale includes a series of random number generator objects that wrap the
+    # random number generators from numpy. These are named `Gen*` and can be
+    # used with an `ErrSysGen` or an `ErrSysGenPercent` object to create custom
+    # probability distribution sampling errors:
+    sys_gen = pyv.GenTriangular(left=-1.0,
+                                mode=0.0,
+                                right=1.0)
+    err_chain.append(pyv.ErrSysGen(sys_gen))
+
+    # We can also build the equivalent of `ErrSysUnifPercent` above using a
+    # `Gen` object inserted into an `ErrSysGenPercent` object:
+    unif_gen = pyv.GenUniform(low=-1.0,
+                              high=1.0)
+    err_chain.append(pyv.ErrSysGenPercent(unif_gen))
+
+
+    # We can also add a series of random errors in a similar manner to the
+    # systematic errors above noting that these will generate a new error for
+    # each sensor and each time step whereas the systematic error sampling
+    # provides a constant shift over all sampling times for each sensor.
+    err_chain.append(pyv.ErrRandNorm(std = 2.0))
+    err_chain.append(pyv.ErrRandNormPercent(std_percent=2.0))
+    err_chain.append(pyv.ErrRandUnif(low=-2.0,high=2.0))
+    err_chain.append(pyv.ErrRandUnifPercent(low_percent=-2.0,
+                                            high_percent=2.0))
+    rand_gen = pyv.GenTriangular(left=-5.0,
+                                 mode=0.0,
+                                 right=5.0)
+    err_chain.append(pyv.ErrRandGenerator(rand_gen))
+
+    # Finally we add some dependent systematic errors including rounding errors,
+    # digitisation and saturation. Note that the saturation error must be placed
+    # last in the error chain. Try changing some of these values to see how the
+    # sensor traces change - particularly the saturation error.
+    err_chain.append(pyv.ErrSysRoundOff(pyv.ERoundMethod.ROUND,0.1))
+    err_chain.append(pyv.ErrSysDigitisation(bits_per_unit=2**16/100))
+    err_chain.append(pyv.ErrSysSaturation(meas_min=0.0,meas_max=400.0))
+
+    err_int = pyv.ErrIntegrator(err_chain,
+                                sensor_data,
+                                tc_array.get_measurement_shape())
+    tc_array.set_error_integrator(err_int)
+
+    # Now we can run the sensor simulation and display the results to see the
+    # different error sources as we have done in previous examples.
+    measurements = tc_array.calc_measurements()
+
+    print(80*"-")
+
+    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*"-")
+
+    pyv.plot_time_traces(tc_array,field_key)
+    plt.show()
+
+
+if __name__ == '__main__':
+    main()