Metadata-Version: 2.4
Name: pybop
Version: 25.11
Summary: Python Battery Optimisation and Parameterisation
Author: The PyBOP Team
Maintainer: The PyBOP Team
License: BSD 3-Clause License
        
        Copyright (c) 2023, pybop-team
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this
           list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        
        3. Neither the name of the copyright holder nor the names of its
           contributors may be used to endorse or promote products derived from
           this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
        
Project-URL: Homepage, https://github.com/pybop-team/PyBOP
Project-URL: Documentation, https://pybop-docs.readthedocs.io
Project-URL: Repository, https://github.com/pybop-team/PyBOP
Project-URL: Releases, https://github.com/pybop-team/PyBOP/releases
Project-URL: Changelog, https://github.com/pybop-team/PyBOP/blob/develop/CHANGELOG.md
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Requires-Python: <3.13,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pybamm>=25.10.1
Requires-Dist: numpy
Requires-Dist: scipy>=1.3
Requires-Dist: pints>=0.5.1
Requires-Dist: SALib>=1.5
Provides-Extra: plot
Requires-Dist: plotly>=5.0; extra == "plot"
Provides-Extra: docs
Requires-Dist: pydata-sphinx-theme; extra == "docs"
Requires-Dist: sphinx>=6; extra == "docs"
Requires-Dist: sphinx-autobuild; extra == "docs"
Requires-Dist: sphinx-autoapi; extra == "docs"
Requires-Dist: sphinx-automodapi; extra == "docs"
Requires-Dist: sphinx_copybutton; extra == "docs"
Requires-Dist: sphinx_favicon; extra == "docs"
Requires-Dist: sphinx_design; extra == "docs"
Requires-Dist: myst-parser; extra == "docs"
Provides-Extra: dev
Requires-Dist: nox[uv]; extra == "dev"
Requires-Dist: nbmake; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: pytest>=6; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: pytest-mock; extra == "dev"
Requires-Dist: pytest-xdist; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Provides-Extra: scifem
Requires-Dist: scikit-fem>=8.1.0; extra == "scifem"
Provides-Extra: bpx
Requires-Dist: bpx<0.6,>=0.5; extra == "bpx"
Provides-Extra: pyprobe
Requires-Dist: PyProBE-Data; python_version >= "3.11" and extra == "pyprobe"
Provides-Extra: all
Requires-Dist: pybop[bpx,plot,pyprobe,scifem]; extra == "all"
Dynamic: license-file

<div align="center">

  <img src="https://raw.githubusercontent.com/pybop-team/PyBOP/develop/assets/logo/PyBOP_logo.svg" alt="The PyBOP logo." width="600" />

  # Python Battery Optimisation and Parameterisation


  [![Scheduled](https://github.com/pybop-team/PyBOP/actions/workflows/scheduled_tests.yaml/badge.svg)](https://github.com/pybop-team/PyBOP/actions/workflows/scheduled_tests.yaml)
  [![Contributors](https://img.shields.io/github/contributors/pybop-team/PyBOP)](https://github.com/pybop-team/PyBOP/graphs/contributors)
  [![Python Versions from PEP 621 TOML](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Fpybop-team%2FPyBOP%2Fdevelop%2Fpyproject.toml&label=Python)](https://pypi.org/project/pybop/)
  [![Codecov](https://codecov.io/gh/pybop-team/PyBOP/branch/develop/graph/badge.svg)](https://app.codecov.io/gh/pybop-team/PyBOP)
  [![License](https://img.shields.io/github/license/pybop-team/PyBOP?color=blue)](https://github.com/pybop-team/PyBOP/blob/develop/LICENSE)
  [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/pybop-team/PyBOP/blob/develop/)
  [![nbviewer](https://raw.githubusercontent.com/jupyter/design/master/logos/Badges/nbviewer_badge.svg)](https://nbviewer.org/github/pybop-team/PyBOP/tree/develop/examples/notebooks/)
  [![Static Badge](https://img.shields.io/badge/https%3A%2F%2Fpybop-team.github.io%2Fpybop-bench%2F?label=Benchmarks)](https://pybop-team.github.io/pybop-bench/)
  [![Releases](https://img.shields.io/github/v/release/pybop-team/PyBOP?color=gold)](https://github.com/pybop-team/PyBOP/releases)

[<ins>Main Branch Examples</ins>](https://github.com/pybop-team/PyBOP/tree/main/examples) [<ins>Develop Branch Examples</ins>](https://github.com/pybop-team/PyBOP/tree/develop/examples)

</div>

PyBOP provides tools for the parameterisation and optimisation of battery models, using both Bayesian and frequentist approaches, with [example workflows](https://github.com/pybop-team/PyBOP/tree/main/examples/) to assist the user. PyBOP can be used to parameterise various battery models, including the electrochemical and equivalent circuit models available in [PyBaMM](https://pybamm.org/).

📌 PyBOP v25.10 presents a [major restructure](https://github.com/pybop-team/PyBOP/blob/main/CHANGELOG.md) of PyBOP's base classes. We move from setting up
a model, problem, cost, then optimiser to defining a simulator, cost, problem, and then optimiser. A `pybop.pybamm.Simulator` is designed to simulate a
`pybamm.BaseModel`. Optimisation parameters can be passed through a `pybamm.ParameterValues` class.
To understand how to update your use of PyBOP, please take a look at the example notebooks and scripts.

<p align="center">
    <img src="https://raw.githubusercontent.com/pybop-team/PyBOP/develop/assets/PyBOP-high-level.svg" alt="A diagram showing the PyBOP logo surrounded by connections to experimental data as an input, forward simulations provided by PyBaMM, results for parameteriation and design optimisation, as well as funding bodies (the Faraday Institution, EU IntelLiGent and DigiBatt projects)." width="700" />
</p>

<p align="center">
    <img src="https://raw.githubusercontent.com/pybop-team/PyBOP/develop/assets/PyBOP_components.drawio.pdf" alt="A diagram showing the main PyBOP classes: the Simulator and Cost, which together define the optimisation Problem, and the Optimiser or Sampler which generates the Result." width="700" />
</p>

## 💻 Installation

Within your virtual environment, install PyBOP:

```bash
pip install pybop
```

To install the most recent state of PyBOP, install from the `develop` branch,

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

To install a previous version of PyBOP, use the following template and replace the version number:

```bash
pip install pybop==v24.3
```

To check that PyBOP is installed correctly, run one of the examples in the following section. For a development installation, see the [Contribution Guide](https://github.com/pybop-team/PyBOP/blob/develop/CONTRIBUTING.md#Installation). More installation information is available in our [documentation](https://pybop-docs.readthedocs.io/en/latest/installation.html) and the [extended installation instructions](https://docs.pybamm.org/en/latest/source/user_guide/installation/gnu-linux-mac.html) for PyBaMM.


## 💡 Use Cases

PyBOP has two intended uses:

1. Parameter inference from battery test data.

2. Design optimisation under battery manufacturing/use constraints.

These include a wide variety of optimisation problems that require careful consideration due to the choice of battery model, data availability and/or the choice of design parameters.

### Publications

Please take inspiration from the following journal articles which show how PyBOP is being used for research:

- "Physics-based battery model parametrisation from impedance data" by [Hallemans et al. (2025)](https://doi.org/10.1149/1945-7111/add41b) with [open-source code and data](https://github.com/Battery-Intelligence-Lab/Hallemans-2025-JES)
- "Transport limitations in single-crystal NCM cathode electrodes" by [Jackowska et al. (2025)](https://doi.org/10.1016/j.jpowsour.2025.238881) with [open-source code](https://github.com/Battery-Intelligence-Lab/Jackowska-2025-JPS) and [original data](https://edata.bham.ac.uk/)

### Jupyter Notebooks

Explore our [example notebooks](https://github.com/pybop-team/PyBOP/tree/develop/examples) for hands-on demonstrations:

- [Getting started with gradient-based optimisation](https://nbviewer.org/github/pybop-team/PyBOP/blob/develop/examples/notebooks/getting_started/optimising_with_adamw.ipynb)
- [Estimating ECM parameters from a HPPC pulse](https://nbviewer.org/github/pybop-team/PyBOP/blob/develop/examples/notebooks/battery_parameterisation/ecm_multipulse_identification.ipynb)
- [Identifying ECM parameters with nonlinear constraints](https://nbviewer.org/github/pybop-team/PyBOP/blob/develop/examples/notebooks/battery_parameterisation/ecm_scipy_constraints.ipynb)
- [Parameter identification for a spatial pouch cell model](https://nbviewer.org/github/pybop-team/PyBOP/blob/develop/examples/notebooks/battery_parameterisation/pouch_cell_identification.ipynb)
- [Energy-based electrode design optimisation](https://nbviewer.org/github/pybop-team/PyBOP/blob/develop/examples/notebooks/design_optimisation/energy_based_electrode_design.ipynb)

### Python Scripts

Find additional script-based examples in the [examples directory](https://github.com/pybop-team/PyBOP/tree/develop/examples/scripts):

- [Getting started with SciPy minimize](https://github.com/pybop-team/PyBOP/blob/develop/examples/scripts/getting_started/optimising_with_scipy_minimize.py)
- [Estimating diffusivity from GITT data](https://github.com/pybop-team/PyBOP/blob/develop/examples/scripts/battery_parameterisation/gitt_fitting.py)
- [Maximum a Posteriori parameter identification](https://github.com/pybop-team/PyBOP/blob/develop/examples/scripts/getting_started/maximum_a_posteriori.py)
- [Using electrochemical impedance spectroscopy (EIS) data](https://github.com/pybop-team/PyBOP/blob/develop/examples/scripts/battery_parameterisation/simple_eis.py)
- [Getting started with MCMC samplers](https://github.com/pybop-team/PyBOP/blob/develop/examples/scripts/getting_started/monte_carlo_sampling.py)


### Grouped Models
In addition to the models available in PyBaMM, PyBOP currently hosts some grouped-parameter versions of common battery models which are
purpose-built for parameter esimation and can be found under [models](https://github.com/pybop-team/PyBOP/tree/develop/pybop/models).


## 👉 Code of Conduct

PyBOP aims to foster a broad consortium of developers and users, building on and learning from the success of the [PyBaMM](https://pybamm.org/) community. Our values are:

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

-   Interoperability (modularity for maximum impact and inclusivity)

-   User-friendliness (putting user requirements first via user-assistance & workflows)

## 📃 License

PyBOP is released under the [BSD 3-Clause License](https://github.com/pybop-team/PyBOP/blob/develop/LICENSE).

## 🌟 Contributing

We would like to thank all contributors to PyBOP. Contributions are welcome! See [CONTRIBUTING.md](https://github.com/pybop-team/PyBOP/blob/develop/CONTRIBUTING.md) for ways to get started.

The original PyBOP developers were supported by research funding from the [Faraday Institution](https://www.faraday.ac.uk/),
[UK Research and Innovation](https://www.ukri.org/),
and [Horizon Europe IntelLiGent Consortium](https://heuintelligent.eu).
