Python Battery Optimisation and Parameterisation

PyBOP

PyBOP provides a comprehensive suite of tools for parameterisation and optimisation of battery models. It aims to implement Bayesian and frequentist techniques with example workflows to guide the user. PyBOP can be applied to parameterise a wide range of battery models, including the electrochemical and equivalent circuit models available in PyBaMM. A major emphasis in PyBOP is understandable and actionable diagnostics for the user, while still providing extensibility for advanced probabilistic methods. By building on the state-of-the-art battery models and leveraging Python's accessibility, PyBOP enables agile and robust parameterisation and optimisation.

The figure below gives PyBOP's current conceptual structure. The living software specification of PyBOP can be found here. This package is under active development, expect API evolution with releases.

Getting Started

Prerequisites

To use and/or contribute to PyBOP, you must first install Python 3 (specifically, 3.8-3.11). For example, on a Debian-based distribution (Debian, Ubuntu - including via WSL, Linux Mint), open a terminal and enter:

sudo apt update
sudo apt install python3 python3-virtualenv

For further information, please refer to the similar installation instructions for PyBaMM.

Installation

Create a virtual environment called pybop-env within your current directory using:

virtualenv pybop-env

Activate the environment with:

source pybop-env/bin/activate

You can check which version of python is installed within the virtual environment by typing:

python --version

Later, you can deactivate the environment and go back to your original system using:

deactivate

Note that there are alternative packages which can be used to create and manage virtual environments, for example pyenv and pyenv-virtualenv. In this case, follow the instructions to install these packages and then to create, activate and deactivate a virtual environment, use:

pyenv virtualenv pybop-env
pyenv activate pybop-env
pyenv deactivate

Within your virtual environment, install the develop branch of PyBOP:

pip install git+https://github.com/pybop-team/PyBOP.git@develop

To alternatively install PyBOP from a local directory, use the following template, substituting in the relevant path:

pip install -e "PATH_TO_PYBOP"

Now, with PyBOP installed in your virtual environment, you can run Python scripts which import and use the functionality of this package.

Usage

PyBOP has two classes of intended use case:

1. parameter estimation from battery test data
2. design optimisation subject to battery manufacturing/usage constraints

These classes encompass a wide variety of optimisation problems, which depend on the choice of battery model, the available data and/or the choice of design parameters.

Parameter estimation

The example below shows a simple fitting routine that starts by generating synthetic data from a single particle model with modified parameter values. An RMSE cost function using the terminal voltage as the optimised signal is completed to determine the unknown parameter values. First, the synthetic data is generated:

import pybop
import pybamm
import pandas as pd
import numpy as np

def getdata(x0):
        model = pybamm.lithium_ion.SPM()
        params = model.default_parameter_values

        params.update(
            {
                "Negative electrode active material volume fraction": x0[0],
                "Positive electrode active material volume fraction": x0[1],
            }
        )
        experiment = pybamm.Experiment(
            [
                (
                    "Discharge at 2C for 5 minutes (1 second period)",
                    "Rest for 2 minutes (1 second period)",
                    "Charge at 1C for 5 minutes (1 second period)",
                    "Rest for 2 minutes (1 second period)",
                ),
            ]
            * 2
        )
        sim = pybamm.Simulation(model, experiment=experiment, parameter_values=params)
        return sim.solve()


# Form observations
x0 = np.array([0.55, 0.63])
solution = getdata(x0)

Next, the observed variables are defined, with the model construction and parameter definitions following. Finally, the parameterisation class is constructed and parameter fitting is completed.

observations = [
    pybop.Observed("Time [s]", solution["Time [s]"].data),
    pybop.Observed("Current function [A]", solution["Current [A]"].data),
    pybop.Observed("Voltage [V]", solution["Terminal voltage [V]"].data),
]

# Define model
model = pybop.models.lithium_ion.SPM()
model.parameter_set = model.pybamm_model.default_parameter_values

# Fitting parameters
params = [
    pybop.Parameter(
        "Negative electrode active material volume fraction",
        prior=pybop.Gaussian(0.5, 0.05),
        bounds=[0.35, 0.75],
    ),
    pybop.Parameter(
        "Positive electrode active material volume fraction",
        prior=pybop.Gaussian(0.65, 0.05),
        bounds=[0.45, 0.85],
    ),
]

parameterisation = pybop.Parameterisation(
    model, observations=observations, fit_parameters=params
)

# get RMSE estimate using NLOpt
results, last_optim, num_evals = parameterisation.rmse(
    signal="Voltage [V]", method="nlopt" # results = [0.54452026, 0.63064801]
)

Code of Conduct

PyBOP aims to foster a broad consortium of developers and users, building on and learning from the success of the PyBaMM community. Our values are:

• Open-source (code and ideas should be shared)

• Inclusivity and fairness (those who want to contribute may do so, and their input is appropriately recognised)

• Inter-operability (aiming for modularity to enable maximum impact and inclusivity)

• User-friendliness (putting user requirements first, thinking about user-assistance & workflows)

Contributing

Thanks to all of our contributing members! [emoji key]

Brady Planden 🚇 ⚠️ 💻 💡

NicolaCourtier 💻

David Howey 🤔 🧑‍🏫

Martin Robinson 🤔 🧑‍🏫

Contributions are always welcome! See contributing.md for ways to get started.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

This project follows the all-contributors specifications. Contributions of any kind are welcome!