PyBaMM Battery Modelling and Simulation in Python

PyBaMM's Battery Research Problem

PyBaMM solves a specific research problem: turning battery modelling assumptions into executable simulations that can be changed and compared. Its intended users are Python developers, battery researchers and interdisciplinary teams that need to explore cell designs, parameter values and operating conditions. The package is not simply a viewer for precomputed battery data. Its documented scope includes changing physics, geometry, submeshes, discretisation methods and solvers, so the model definition remains accessible to the user.

The package is organised around a modelling framework, a library of battery models and parameters, and specialised tools for battery experiments and visualisation. This division gives a project a clear progression. A user can select a model, supply an experiment or operating condition, solve the resulting system and inspect the results. That structure is useful when a research question requires several variants rather than one fixed result.

The README presents PyBaMM as an open-source project for multi-institutional, interdisciplinary collaboration. It is also hosted under NumFOCUS's fiscal sponsorship and follows an open governance model. Those repository facts do not by themselves establish model accuracy, but they do clarify the project's institutional setting. The practical focus remains Python-based battery simulation rather than battery hardware control, cell manufacturing or raw data acquisition.

The intended research questions include the effect of different battery designs and modelling assumptions under varying operating scenarios. PyBaMM can represent a familiar DFN model as a starting point, but its value comes from making the assumptions and numerical setup configurable. That makes it more appropriate for exploratory studies than for a pipeline that expects one immutable result from a preapproved cell specification.

PyBaMM's Model and Experiment Architecture

The documented basic workflow connects three layers. First, the model is created. Second, it is passed to `pybamm.Simulation`. Third, the simulation is solved over a time interval and can be plotted. The README uses `pybamm.lithium_ion.DFN()` as the example model and identifies it as the Doyle-Fuller-Newman model. With default settings, the shortest example solves a constant-current discharge from 0 to 3600 seconds.

PyBaMM also separates the operating protocol from the battery model through `pybamm.Experiment`. The documented experiment contains a discharge, a rest, a charge, a constant-voltage hold and another rest, with the entire sequence repeated three times. Current, duration, voltage and rest conditions are written as experiment instructions. The model and experiment are then supplied to a simulation, which makes the operating protocol inspectable and reusable.

The root repository configuration identifies a UV workspace with `packages/*` as its members. It specifically identifies `packages/pybamm` as the Python package and `packages/pybammsolvers` as a solver package. The latter uses `scikit-build-core`, while the root configuration includes `pybind11`, `cmake` and `ninja` among its development dependencies. This layout indicates a split between the main modelling package and solver packaging, although the README does not document every internal solver interface.

The important design constraint is that flexibility increases the number of choices available to the user. A changed submesh or solver is not merely a display option. It becomes part of how the mathematical model is discretised and integrated. Teams therefore need to preserve their configuration alongside results if they expect to reproduce a simulation later.

The architecture also supports comparing model assumptions without rewriting the operating sequence. The same experiment can be attached to a different model, while the same model can be evaluated under different protocols. The repository examples point to this style of reusable scientific scripting, but they do not define a universal result schema for storing experiments, meshes and solver diagnostics.

Installing PyBaMM with pip and conda-forge

The README says PyBaMM is available on GNU/Linux, macOS and Windows. It strongly recommends installing the package inside a Python virtual environment so that its dependencies do not alter a system-wide Python installation. The project links its installation documentation for the full virtual environment procedure, but the README excerpt does not provide the platform-specific virtual environment commands. The documented package installation command is:

pip install pybamm

Run that command inside the virtual environment in which you want the package installed. The command installs the PyBaMM package rather than a model-specific project. The README also states that PyBaMM is available as a conda package through the conda-forge channel, but it does not give a conda installation command, so this article does not invent one.

There is a version caveat for conda-forge. The README notes that versions between 24.11.2 and 25.6, excluding the boundary versions, are not available there. For a pip installation, the installed version will depend on the package index and the environment's existing dependencies. For work tied to a particular release, the repository advises checking the matching release tag rather than assuming that examples on `main` apply unchanged.

After installation, confirm that the intended Python environment is active before running an example. The README does not document a separate verification command, version output or required operating-system package list. It does identify the supported operating systems and the two distribution channels, which gives a new user a clear starting point without implying that installation alone validates the model.

Running a First DFN Discharge with PyBaMM

The README's first example is short enough to serve as an installation check, but it also establishes the expected sequence of API calls. It creates the DFN model, creates a simulation around that model, solves it for one hour and requests a plot. The example uses `sim.plot()` as the final call. The repository does not specify the plot format or numerical output, so the useful result to look for is a completed solve followed by the plotting call without an import or setup error.

import pybamm

model = pybamm.lithium_ion.DFN()
sim = pybamm.Simulation(model)
sim.solve([0, 3600])
sim.plot()

This code is meaningful as a first use because it does not require the experiment syntax. It establishes the basic model, simulation and solve path with default settings. Once it runs, a user can compare the default model with a modified parameter set or inspect the DFN example script and notebook linked by the README for more extensive configuration.

A first run should not be treated as validation of a particular cell design. The example is a model demonstration. The README does not state the calibration procedure, parameter uncertainty, experimental tolerances or convergence criteria for a production study. Those checks belong in the research process around PyBaMM, not in the assumption that the one-hour example proves the model represents a physical pack.

The repository also states that examples on `main` are tested against the latest commit. If an installed pip version is older, users should switch to the corresponding GitHub release tag to see compatible examples. That distinction matters when a tutorial behaves differently from a local installation.

The default solve is also not a complete experimental report. It gives a time interval and a model, while the plot call exposes the result visually. The README does not prescribe how to export every variable, create a convergence table or generate a controlled report, so a team adopting PyBaMM may need to build those practices around it.

Experiment-Based Charge, Discharge and Rest Sequences

For a more representative first use, the README provides an experiment that exercises several battery operations. A discharge is followed by a rest, then a charge, a constant-voltage hold and another rest. The sequence is repeated three times. Unlike the basic solve call, the experiment expresses both the operating procedure and its stopping conditions. This is a concrete way to learn the difference between choosing a model and describing what happens to it.

import pybamm

experiment = pybamm.Experiment(
    [
        (
            "Discharge at C/10 for 10 hours or until 3.3 V",
            "Rest for 1 hour",
            "Charge at 1 A until 4.1 V",
            "Hold at 4.1 V until 50 mA",
            "Rest for 1 hour",
        )
    ]
    * 3,
)
model = pybamm.lithium_ion.DFN()
sim = pybamm.Simulation(model, experiment=experiment)
sim.solve()
sim.plot()

This example gives a user more control over a simulation protocol, but it also introduces terminology that must be interpreted correctly. `C/10`, current limits, voltage limits and rest periods belong to the experiment description. The README does not provide a full specification of every supported experiment instruction or how termination is prioritised when several limits apply. It also does not promise that one DFN parameter set is appropriate for every chemistry or cell format.

The alternative approach is to define a simpler time interval and solve it directly. That is easier for a first API check, while the experiment object is better suited to repeatable operating protocols. PyBaMM supports both styles, but choosing between them is part of the modelling task rather than a mandatory setup convention.

For a production study, the experiment text should be retained alongside the model name, parameter set and solver configuration. The README gives the syntax, not a complete experiment registry or validation protocol. That limitation makes PyBaMM a useful research component while leaving study governance to the adopting laboratory or engineering team.

PyBaMM Limitations and the Alternative of Fixed-Parameter Workflows

PyBaMM's flexibility is also its main adoption constraint. The README lists several choices that can be changed, including physics, parameters, geometry, submeshes, spatial discretisation and solvers. That is appropriate for research, but it can make results harder to compare when two runs differ in more than one setting. The README does not prescribe a complete configuration record or a universal convergence check.

PyBaMM is also not the right tool when the requirement is a battery data pipeline with no mathematical model. It does not describe measurement acquisition, laboratory automation, battery management firmware or production-cell control. It should not be selected merely because a project needs to store and display battery records. Its contribution begins with a physical model and a numerical solve.

A real alternative is a fixed-parameter workflow in which an organisation selects one validated cell model, hard-codes its parameters and standard operating cases, and produces a narrow set of reports. That approach reduces configuration freedom and can simplify review, but it cannot answer the same range of design and assumption questions without adding another model or parameter workflow. PyBaMM instead keeps those choices inside the Python simulation layer. The decision depends on whether the team needs exploratory modelling or only a fixed, previously established calculation.

The repository's CalVer policy uses versions of the form `YY.MM.N.P`. Releases are not on a fixed schedule, and any release may contain breaking changes. Removed or renamed public APIs are supposed to receive a `DeprecationWarning` for at least two prior feature releases where technically possible, with details in `CHANGELOG.md` and `RELEASE.md`. This creates an upgrade cost for code that depends on public APIs.

PyBaMM is licensed under BSD-3-Clause. The repository identifies the licence through its `LICENSE.txt` file. Users should review that file for the applicable terms. This is a repository-level licensing fact, not legal advice.

Editorial conclusion

PyBaMM fits researchers who need reusable physics-based battery models, parameter exploration and experiment-driven Python workflows. It is less suitable for a team seeking one fixed-cell calculation with no model configuration or solver selection. Before adoption, verify the DFN assumptions, parameter provenance, solver configuration and compatibility between the installed PyBaMM version and the examples you plan to use. The repository's last push was on 2026-10-16, and recent releases include PyBaMM 26.10.1.0, pybammsolvers 0.11.1 and pybamm-model-zoo 0.1.1.

Frequently asked questions

Official sources

1. License: BSD-3-Clause
2. Project website
3. pybamm-team/PyBaMM on GitHub
4. README
5. Releases