MuonExperimentOpt

MuonExperimentOpt is a Python project made by Alex Sampson, Lucas Wilkins and John Wilkinson. This project's purpose is to help the user plan optimised Muon Spectroscopy experiments by using Fisher information. It is a continuation of HOGBEN by J. Durant et al (https://github.com/jfkcooper/HOGBEN) which was made to optimise experimental design in Neutron Reflectometry. This project makes use of the mantid Python package and Mantid Workbench, see https://github.com/mantidproject/mantid.

This project contains a collection of Python scripts designed to be run by the user in Mantid Workbench.

Installation

1. Clone this git repository.

2. Pull the latest changes.

3. Install Mantid if it is not already installed (this project has been built and tested for version 6.10.0, later versions should work).

4. Install all libraries in requirements using pip if not already installed

Testing

Tests are to be run manually due to it not being possible to have continuous integration through Mantid Workbench (needed for Python and Qt version)

1. Open Mantid Workbench.

2. Open and run tests/run_tests.py in Mantid Workbench, be patient it takes a while to run some of the tests.

Note: This project does not currently have full test coverage.

Docs

Full sphinx documentation for this project can be found at docs/build/html/index.html

To rebuild docs please ensure sphinx is installed, navigate to docs and run sphinx-apidoc -o source ../src/muon_experiment_opt then sphinx-build -b html source build/html (twice if errors occur).

Usage

1. Open Mantid Workbench.

2. Open the chosen python file in Mantid Workbench and run it through its built in editor, (Mantid Workbench is necessary to ensure the correct Qt version and Python version with access to the Mantid library is in use).

Scripts to be used (found in src)

Optimise muon experiments using Fisher information

required_num_events.py Determines the minimum number of muon decay events required to satisfy acceptable error thresholds for a specific experiment. The user can select polarisation functions defined in Mantid or create a compound polarisation function (additive) and enter the predicted parameter values for their experiment.

The following four optimisation files using Fisher information assume a Dynamic Kubo toyabe polarisation function which models the dynamic behaviour of battery materials well.

LF_sweep_investigation.py Uses fisher information to find the optimal combination of three different fixed fields for LF sweep experiments. Performs this optimisation for a range of Nu and Delta values. Displays the results as ternary plots of ellipses to visualise the size of errors.

LF_sweep_dual_field_single_experiment_planner.py Optimises a dual-field longitudinal field (LF) μSR experiment with specific parameter values by identifying the field strength and count proportion that minimise parameter error (e.g., in Δ, ν, Δ₂).

LF_sweep_dual_field_full_param_space_optimisation.py Runs an optimisation across a range of Delta and Nu values to find the best second field strength for a dual-field LF sweep experiment. Outputs heatmaps and visualisations of the optimal values, and saves the results (Nu, Delta, optimal field) as a pickle file for further analysis.

surface_fitter.py Fits a surface to points in the Nu, Delta, Optimal field space (heatmap) that are generated by the full parameter space optimisation code and stored in a pickle file. Operates on the 'BEST_LF_sweep_dual_field_optimisation_data.pkl' file. To analyse data from a recently run full param space optimisation please rename 'LF_sweep_dual_field_optimisation_data.pkl' to 'BEST_LF_sweep_dual_field_optimisation_data.pkl'. Fitting equation form is fixed to work nicely with the trends that have been seen in previous analysis but could be changed by the user by modifying this script if necessary. Generating this surface is not necessary but can provide an equation to find optimal field strength values instead of a heatmap if prefered.

Optimise muon experiments using simulation and fitting (slower)

run_error_curves_from_simulation.py A wrapper to run parallelised code to optimise the LF strength in a dual-field LF sweep experiment for a specific set of parameters using a simulation and fitting method as an alternative to fisher information. This is done by simulating experimental data and performing a fitting on it hundreds of times, then finding the standard deviation of fitting parameters which represents parameter error.

Analyse the results of a completed LF experiment

experimental_data_pickler.py Creates a pickle file of experimental data from Mantid workspaces for further analysis in Python.

run_experimental_data_analysis.py A wrapper to run parallelised code analyse experimental data pickled by experimental_data_pickler.py. This is done using a bootstrapping method taking samples from the groups of data, performing a simultaneous fitting on them and finding the standard deviation of the fitting values.

Other Folders in src

helpers Contains the helper files used by the scripts that are to be run by the user.

imgs Contains plots automatically saved by some of the files in this project, a space to manually save other generated plots.

pickles Contains pickle files generated by the scripts in this file (pickled experiment data, saved heatmap data for full param space optimisation, and picked simulation and fitting data that can be cumulatively built and saved)

in_development Code still in development, currently gaussian_process_regression.py: Code to perform Gaussian Process Regression intended for Nu, Temperature data. To be used in combination with other factors (predicted experimental errors etc.) to predict the best temperatures to be investigated next in an experiment.

Final Note:

pickles and imgs could be added to .gitignore to avoid merge issues if the project is to be modified by multiple users simultaneously.