ep-bolfi 3.0.1

EP-BOLFI (Expectation Propagation with Bayesian Optimization for Likelihood-Free Inference) extends the simulator optimizer BOLFI with the data featurization of Expectation Propagation.

EP-BOLFI

EP-BOLFI (Expectation Propagation with Bayesian Optimization for Likelihood-Free Inference) extends the simulator optimizer BOLFI with the data featurization of Expectation Propagation. EP-BOLFI inherits the advantages of both: high stability to measurement noise and considerable reduction of computational effort. The performance is one to two orders of magnitude better than Markov-Chain Monte Carlo, counted in the number of simulator evaluations required.

Documentation

ep_bolfi contains the EP-BOLFI algorithm, a few example models, and utility functions that cover fitting functions, datafile imports, dataset processing, and visualization. For further details, please refer to the HTML documentation on GitLab Pages.

Examples

The examples currently comprise of the code used in the EP-BOLFI publication. Apart from the SPMe benchmark, they analyze a GITT dataset provided by BASF. You can find the dataset at the DOI 10.5281/zenodo.7478267. If you wish to re-run the parameterization yourself, copy the contents of GITT_data_and_parameterization_info.zip into examples first.

• To perform the SPMe benchmarks from Aitio et al., please use spme_benchmark_multimodal.py and spme_benchmark_unimodal.py. To calculate the tabulated results presented in the article, use evaluate_spme_benchmark_confidence.py.
• To preprocess the OCV curves, please use ocv_from_cccv_and_gitt.py.
• To view the GITT data, please use measurement_plot.py.
• To estimate parameters from the GITT data from BASF, use run_estimation.py, and after that collect_gitt_estimation_results.py. This may take more than a week to run.
• To get the tabulated results for the GITT parameterization, please use evaluate_gitt_estimation_confidence.py.
• To perform the verification of the GITT data parameterization, please use verify_estimation.py. This may take more than a week to run.
• To analyze the correlation matrix for the 7-parameter estimation, please use correlation_visualization.py.
• To plot the results from the GITT estimation procedure, please use gitt_visualization.py.
• To analyze the precision and reliability of the GITT estimation procedure, please use calculate_experimental_and_simulated_features.py. To plot this analysis, please use analytic_vs_epbolfi_results.py and sensitivity_visualization.py.
• To plot the joint resistance of the two exchange-current densities, please use joint_resistance.py.

Using EP-BOLFI to process your measurements with your model

Please have a look at the setup example. gitt_basf.py contains the preprocessing of the GITT dataset and a GITT simulator. gitt.py contains one possible definition of features in a GITT measurement. For performing the optimization, please have a look at run_estimation.py. If you wish to re-use an optimization result as starting value, use .Q, .r, .Q_features and .r_features and pass them to the initialization of the EP-BOLFI object.

Installation

EP-BOLFI requires Python 3.8 or greater. Just download the newest Release .whl file and requirements.txt. Install the dependencies with requirements.txt via pip, then install the .whl file. In case you want to build the package from source, please refer to CONTRIBUTING.md.

Using pip

Create a virtual environment and activate it. On Linux and Mac:

python3.9 -m venv ep_bolfi
source ep_bolfi/bin/activate

On Windows:

py -3.9 -m venv ep_bolfi
. .\ep_bolfi\Scripts\activate

Then install the dependencies and package:

pip install -r requirements.txt
pip install ep_bolfi-${VERSION}-py3-none-any.whl

Using miniforge

On Windows, first initialize conda to work with PowerShell, assuming you work with PowerShell:

conda init powershell

Create a new virtual environment:

conda create -n ep_bolfi python=3.9
conda activate ep_bolfi

and install the dependencies there. The fastest way is to use pip to install the packages:

pip install -r requirements.txt

If you want to use the conda package manager as much as possible, use these lines instead:

conda env update --file ep_bolfi.yml
pip install -r pip_only_requirements.txt

Then install the dependencies and package:

conda install ep_bolfi-${VERSION}-py39_0.tar.bz2

Using the Kadi4Mat tools

The files in (ep_bolfi/kadi_tools) are command-line tools. These command-line tools are designed to interface with the database software Kadi4Mat, of which we have an internal instance running at (https://kadi-dlr.hiu-batteries.de/).

In order to use these command-line tools in the workflow toolchain of Kadi4Mat, they are implemented with the library xmlhelpy which extends the Click library for command-line tools with the option to generate machine-readable representations of command-line tools. You can find these representations in ep_bolfi/kadi_tools/xml_representations, but only when installing a Release. If they are missing in your installation, please refer to the manual instructions in CONTRIBUTING.md.

KadiStudio can import the .py files, or on a Kadi4Mat instance with the online workflow editor enabled, the .xml files can be imported by uploading them to any Record on the respective Kadi4Mat instance. The command-line tools are then available as building blocks for workflows.

For executing workflows that contain one of these tools, the command python has to launch a Python environment with this library installed. Either bake the activation of said environment into the convenience scripts in the following section, or make your command line automatically activate it by following these steps.

On Linux:

nano ~/.profile

Then add the following line to the bottom of the file:

source ~/ep_bolfi/bin/activate

On Windows:

notepad $((Split-Path $profile -Parent) + "\profile.ps1")

Then add the following line to the bottom of the text file:

. .\ep_bolfi\Scripts\activate

In the case where spurious lines like "warning in ...: failed to import cython module: falling back to numpy" show up and break workflow scripts, these are due to an unfortunate design decision in GPy. You need to install GPy from source like so to improve performance as well:

git clone https://github.com/SheffieldML/GPy.git
cd GPy
pip install .

For the smoothest installation experience, we recommend using the HPC JUSTUS 2.

Convenience scripts to execute Kadi4Mat workflows

Since KadiStudio is semi-usable at this point in time to work with Kadi4Mat workflows, there are two helper scripts in this repository for executing workflows automatically, including input interactions. First, install the libraries process engine and process manager. We recommend Linux or using Linux indirectly via WSL on Windows. On Linux, (ep_bolfi/utility/execute_workflow_locally.py) can be made into an executable with PyInstaller that can be registered with your OS or browser to execute workflow files:

pip install pyinstaller
pyinstaller ep_bolfi/utility/execute_workflow_locally.py

You then find the executable inside (dist/execute_workflow_locally/). Do not use (build), and move the whole folder (dist/execute_workflow_locally/) to where you want to store executable, as the executable depends on the folder contents.

On Windows, use (ep_bolfi/utility/send_workflow_to_wsl.py). It is a wrapper for the case where the process engine and process manager are installed within a WSL on Windows. First, make sure that you installed EP-BOLFI as described above first within WSL. The script assumes you did so within a virtual environment ~/venv in WSL, like so:

pip install virtualenv
cd ~
mkdir venv
virtualenv venv
source venv/bin/activate
pip/conda install ...

Then, instead of (ep_bolfi/utility/execute_workflow_locally.py), you make an executable out of (ep_bolfi/utility/send_workflow_to_wsl.py) in Windows:

pip install pyinstaller
pyinstaller ep_bolfi/utility/send_workflow_to_wsl.py

Then move the folder (dist/send_workflow_to_wsl/) to where you want to store the executable and then register the contained (send_workflow_to_wsl.exe) with your OS or browser to open workflow files. Remember to install and activate Xming if you wish to have graphical outputs.

Contributing to EP-BOLFI

Please refer to the contributing guidelines and adhere to the Code of Conduct.

Licence

This is a purely internal repository, hence there is no licence. Please note that the lack of a licence bars you from using this code in any way, shape or form outside CEC. Please use the code published on https://github.com/YannickNoelStephanKuhn/EP-BOLFI for those purposes instead.