Merge pull request #100 from Computer-Aided-Validation-Laboratory/dev

Added user guide and formatting improvements to docs

Author: ScepticalRabbit

.gitignore

@@ -30,6 +30,7 @@ pyvale-output/
 !reports/images/*.svg
 !images/*.png
 !images/*.svg
+!docs/source/_static/*.png
 
 # Image deformation test cases
 *.pkl

README.md

@@ -1,9 +1,9 @@
-# Pyvale
+# pyvale
 ![fig_pyvale_logo](https://raw.githubusercontent.com/Computer-Aided-Validation-Laboratory/pyvale/main/images/pyvale_logo.png)
 
-The python validation engine (`pyvale`): An all-in-one package for sensor simulation, sensor uncertainty quantification, sensor placement optimisation and simulation calibration/validation. Used to simulate experimental data from an input multi-physics simulation by explicitly modelling sensors with realistic uncertainties. Useful for experimental design, sensor placement optimisation, testing simulation validation metrics and virtually testing digital shadows/twins.
+The python validation engine (`pyvale`) is you virtual engineering laboratory: An all-in-one package for sensor simulation, sensor uncertainty quantification, sensor placement optimisation and simulation calibration/validation. Used to simulate experimental data from an input multi-physics simulation by explicitly modelling sensors with realistic uncertainties. Useful for experimental design, sensor placement optimisation, testing simulation validation metrics and virtually testing digital shadows/twins.
 
-We provide dedicated tools for simulation and uncertainty quantification of imaging sensors including digital image correlation (DIC) and infra-red thermography (IRT). Check out the [documentation](https://computer-aided-validation-laboratory.github.io/pyvale/examples.html) to get started with some of our examples.
+We provide dedicated tools for simulation and uncertainty quantification of imaging sensors including digital image correlation (DIC) and infra-red thermography (IRT). Check out the [documentation](https://computer-aided-validation-laboratory.github.io/pyvale/index.html) to get started with some of our examples.
 
 ## Quick Demo: Simulating Point Sensors
 Here we demonstrate how `pyvale` can be used to simulate thermocouples and strain gauges applied to a [MOOSE](https://mooseframework.inl.gov/index.html) thermo-mechanical simulation of a fusion divertor armour heatsink. The figures below show visualisations of the virtual thermocouple and strain gauge locations on the simualtion mesh as well as time traces for each sensor over a series of simulated experiments.
@@ -25,72 +25,19 @@ The code to run the simulated experiments and produce the output shown here come
 pip install pyvale
 ```
 
-## Detailed Install: Ubuntu
-### Managing Python Versions
-To be compatible with `bpy` (the Blender python interface), `pyvale` uses python 3.11. To install python 3.11 without corrupting your operating systems python installation first add the deadsnakes repository to apt:
-```shell
-sudo add-apt-repository ppa:deadsnakes/ppa
-sudo apt update && sudo apt upgrade -y
-```
-
-Install python 3.11 and the dev version:
-```shell
-sudo apt install python3.11
-sudo apt install python3.11-dev
-```
-
-Add `venv` to your python 3.11 install:
-```shell
-sudo apt install python3.11-venv
-```
-
-Check your python 3.11 install is working using the following command which should open an interactive python interpreter:
-```shell
-python3.11
-```
-
-### Virtual Environment
-
-We recommend installing `pyvale` in a virtual environment using `venv` or `pyvale` can be installed into an existing environment of your choice. To create a specific virtual environment for `pyvale` navigate to the directory you want to install the environment and use:
-
-```shell
-python3.11 -m venv .pyvale-env
-source .pyvale-env/bin/activate
-```
-
-### Standard Local Installation
-`pyvale` can be installed from pypi. Ensure you virtual environment is activated and run the following from the `pyvale` directory:
-```shell
-pip install pyvale
-```
-
-### Developer Local Installation
-
-Clone `pyvale` to your local system along with submodules using:
-```shell
-git clone --recurse-submodules git@github.com:Computer-Aided-Validation-Laboratory/pyvale.git
-```
-
-`cd` to the root directory of `pyvale`. Ensure you virtual environment is activated and run the following commmand from the `pyvale` directory:
-```shell
-pip install -e .
-pip install -e ./dependencies/mooseherder
-```
-
-### Running Physics Simulations with MOOSE
-`pyvale` come pre-packaged with example `moose` physics simulation inputs (.i) and outputs (as '.e' exodus files) to demonstrate its functionality. If you need to run additional simulation cases we recommend `proteus` (https://github.com/aurora-multiphysics/proteus) which has build scripts for common linux distributions.
+We recommend installing `pyvale` into a virtual environment of your choice as `pyvale` requires python 3.11. If you need help setting up your virtual environment and installing `pyvale` head over to the [installation guide](https://computer-aided-validation-laboratory.github.io/pyvale/install.html) in our docs.
 
 ## Contributors
 The Computer Aided Validation Team at UKAEA:
 - Lloyd Fletcher ([ScepticalRabbit](https://github.com/ScepticalRabbit)), UK Atomic Energy Authority
 - Joel Hirst ([JoelPhys](https://github.com/JoelPhys)), UK Atomic Energy Authority
-- John Charlton ([coolmule0](https://github.com/coolmule0)), UK Atomic Energy Authority
 - Lorna Sibson ([lornasibson](https://github.com/lornasibson)), UK Atomic Energy Authority
 - Megan Sampson ([meganasampson](https://github.com/meganasampson)), UK Atomic Energy Authority
 - Michael Atkinson ([mikesmic](https://github.com/mikesmic)), UK Atomic Energy Authority
 - Adel Tayeb ([3adelTayeb](https://github.com/3adelTayeb)), UK Atomic Energy Authority
 - Alex Marsh ([alexmarsh2](https://github.com/alexmarsh2)), UK Atomic Energy Authority
 - Rory Spencer ([fusmatrs](https://github.com/orgs/Computer-Aided-Validation-Laboratory/people/fusmatrs)), UK Atomic Energy Authority
+- John Charlton ([coolmule0](https://github.com/coolmule0)), UK Atomic Energy Authority
 
 
 

dev/ex4_2_simple_expsim3d_thermmech3d.py

@@ -0,0 +1,71 @@
+# ==============================================================================
+# pyvale: the python validation engine
+# License: MIT
+# Copyright (C) 2025 The Computer Aided Validation Team
+# ==============================================================================
+
+import numpy as np
+import matplotlib.pyplot as plt
+import mooseherder as mh
+import pyvale as pyv
+
+
+#-------------------------------------------------------------------------------
+sim_path = pyv.DataSet.thermomechanical_3d_path()
+sim_data = mh.ExodusReader(sim_path).read_all_sim_data()
+sim_data = pyv.scale_length_units(scale=1000.0,
+                                  sim_data=sim_data)
+
+
+#-------------------------------------------------------------------------------
+x_lims = (12.5,12.5)
+y_lims = (0.0,33.0)
+z_lims = (0.0,12.0)
+n_sens = (1,4,1)
+tc_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)
+
+tc_sens_data = pyv.SensorData(positions=tc_sens_pos,
+                              sample_times=sample_times)
+
+
+tc_array = pyv.SensorArrayFactory \
+    .thermocouples_no_errs(sim_data,
+                            tc_sens_data,
+                            elem_dims=3,
+                            field_name="temperature")
+
+tc_err_chain = []
+tc_err_chain.append(pyv.ErrSysUnifPercent(low_percent=1.0,high_percent=1.0))
+tc_err_chain.append(pyv.ErrRandNormPercent(std=1.0))
+tc_error_int = pyv.ErrIntegrator(tc_err_chain,
+                                 tc_sens_data,
+                                 tc_array.get_measurement_shape())
+tc_array.set_error_integrator(tc_error_int)
+
+
+#-------------------------------------------------------------------------------
+exp_sim = pyv.ExperimentSimulator([sim_data,],
+                                  [tc_array,],
+                                  num_exp_per_sim=100)
+exp_data = exp_sim.run_experiments()
+exp_stats = exp_sim.calc_stats()
+
+
+
+#-------------------------------------------------------------------------------
+pv_plot = pyv.plot_point_sensors_on_sim(tc_array,"temperature")
+pv_plot.camera_position = [(59.354, 43.428, 69.946),
+                            (-2.858, 13.189, 4.523),
+                            (-0.215, 0.948, -0.233)]
+
+pv_plot.show()
+
+
+(fig,ax) = pyv.plot_exp_traces(exp_sim,
+                                component="temperature",
+                                sens_array_num=0,
+                                sim_num=0)
+
+plt.show()

docs/source/_static/pyvale_rabbit_only.png

@@ -0,0 +1 @@
+../../../images/pyvale_rabbit_only.png

docs/source/_static/thermomech3d_sg_traces.png

@@ -0,0 +1 @@
+../../../images/thermomech3d_sg_traces.png

docs/source/_static/thermomech3d_sg_vis.png

@@ -0,0 +1 @@
+../../../images/thermomech3d_sg_vis.png

docs/source/_static/thermomech3d_tc_traces.png

@@ -0,0 +1 @@
+../../../images/thermomech3d_tc_traces.png

docs/source/_static/thermomech3d_tc_vis.png

@@ -0,0 +1 @@
+../../../images/thermomech3d_tc_vis.png

docs/source/examples.rst

@@ -1,38 +1,18 @@
-Examples
-========
+.. _examples_all:
 
-Basics
-------
+Examples
+================
 
+Basics for Point Sensors
+------------------------
 .. toctree::
-   :maxdepth: 1
-
-   examples/basics/ex1_1_basicscalars_therm2d.rst
-   examples/basics/ex1_2_sensormodel_therm2d.rst
-   examples/basics/ex1_3_customsens_therm3d.rst
-   examples/basics/ex1_4_basicerrors_therm3d.rst
-   examples/basics/ex1_5_fielderrs_therm3d.rst
-   examples/basics/ex1_6_caliberrs_therm2d.rst
-   examples/basics/ex1_7_spatavg_therm2d.rst
-   examples/basics/ex2_1_basicvectors_disp2d.rst
-   examples/basics/ex2_2_vectorsens_disp2d.rst
-   examples/basics/ex2_3_sensangle_disp2d.rst
-   examples/basics/ex2_4_chainfielderrs_disp2d.rst
-   examples/basics/ex2_5_vectorfields3d_disp3d.rst
-   examples/basics/ex3_1_basictensors_strain2d.rst
-   examples/basics/ex3_2_tensorsens2d_strain2d.rst
-   examples/basics/ex3_3_tensorsens3d_strain3d.rst
-   examples/basics/ex4_1_expsim2d_thermmech2d.rst
-   examples/basics/ex4_2_expsim3d_thermmech3d.rst
+   :maxdepth: 2
 
-Blender
--------
+   examples_basics.rst
 
+Blender for Digital Image Correlation
+-------------------------------------
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
-   examples/renderblender/ex1_1_blenderscene.rst
-   examples/renderblender/ex1_2_blenderdeformed.rst
-   examples/renderblender/ex2_1_stereoscene.rst
-   examples/renderblender/ex2_2_stereodeformed.rst
-   examples/renderblender/ex3_1_blendercalibration.rst
+   examples_blender.rst

docs/source/examples_basics.rst

@@ -0,0 +1,25 @@
+.. _examples_basics:
+
+Basics
+======
+
+.. toctree::
+   :maxdepth: 1
+
+   examples/basics/ex1_1_basicscalars_therm2d.rst
+   examples/basics/ex1_2_sensormodel_therm2d.rst
+   examples/basics/ex1_3_customsens_therm3d.rst
+   examples/basics/ex1_4_basicerrors_therm3d.rst
+   examples/basics/ex1_5_fielderrs_therm3d.rst
+   examples/basics/ex1_6_caliberrs_therm2d.rst
+   examples/basics/ex1_7_spatavg_therm2d.rst
+   examples/basics/ex2_1_basicvectors_disp2d.rst
+   examples/basics/ex2_2_vectorsens_disp2d.rst
+   examples/basics/ex2_3_sensangle_disp2d.rst
+   examples/basics/ex2_4_chainfielderrs_disp2d.rst
+   examples/basics/ex2_5_vectorfields3d_disp3d.rst
+   examples/basics/ex3_1_basictensors_strain2d.rst
+   examples/basics/ex3_2_tensorsens2d_strain2d.rst
+   examples/basics/ex3_3_tensorsens3d_strain3d.rst
+   examples/basics/ex4_1_expsim2d_thermmech2d.rst
+   examples/basics/ex4_2_expsim3d_thermmech3d.rst