Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/pybamm-team/PyBaMM/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through running your first battery simulation with PyBaMM. By the end, you’ll have a working simulation and know how to access and visualize results.
1

Install PyBaMM

Install PyBaMM using pip or conda:
pip install pybamm
Use a virtual environment to avoid dependency conflicts. See the Installation guide for full instructions.
2

Run a basic 1C discharge

The simplest simulation is a 1C constant-current discharge using the Doyle-Fuller-Newman model:
Basic discharge
import pybamm

model = pybamm.lithium_ion.DFN()   # Doyle-Fuller-Newman model
sim = pybamm.Simulation(model)
sim.solve([0, 3600])               # solve for 1 hour
sim.plot()
This runs the DFN model with default parameters (Chen2020) and plots all key variables interactively.
3

Simulate a charge/discharge experiment

Define a multi-step experiment with plain English strings:
Charge/discharge cycle
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,  # repeat 3 times
)
model = pybamm.lithium_ion.DFN()
sim = pybamm.Simulation(model, experiment=experiment)
sim.solve()
sim.plot()
4

Access solution variables

After solving, you can extract any model variable from the solution:
Access solution data
import pybamm

model = pybamm.lithium_ion.SPM()
sim = pybamm.Simulation(model)
sol = sim.solve([0, 3600])

# Access terminal voltage
voltage = sol["Terminal voltage [V]"]
print(voltage.entries)      # numpy array of values
print(voltage.t)            # time points (seconds)

# Access other variables
current = sol["Current [A]"]
temperature = sol["Cell temperature [K]"]

# Access by time
v_at_t = voltage(t=1800)    # voltage at 30 minutes
5

Try a different model and parameters

Swap the model and parameter set with minimal changes:
Different model and parameters
import pybamm

# Use SPM (faster) instead of DFN
model = pybamm.lithium_ion.SPM()

# Load a different parameter set
param = pybamm.ParameterValues("Marquis2019")

# Override a single parameter
param["Current function [A]"] = 1.5

sim = pybamm.Simulation(model, parameter_values=param)
sol = sim.solve([0, 3600])
print(f"Minimum voltage: {sol['Terminal voltage [V]'].entries.min():.4f} V")
Available parameter sets include: Chen2020, Marquis2019, OKane2022, ORegan2022, Ecker2015, and more. See Parameter Sets for the full list.

​
Next steps

Battery Models

Explore SPM, SPMe, DFN, MPM, MSMR and other physics-based models.

Simulations Guide

Learn all Simulation options: solvers, parameters, saving, and loading.

Experiments Guide

Define complex charge/discharge protocols with experiment strings.

API Reference

Full reference for every class, method, and parameter.
You can run PyBaMM notebooks interactively in Google Colab without any local installation by opening notebooks from the PyBaMM GitHub repository in Colab.

Build docs developers (and LLMs) love

Get started for freeTalk to us