Public API

PyBaMM is a Python package for mathematical modelling and simulation of battery systems. The main classes and functions that are intended to be used by the user are described in this document. For a more detailed description of the classes and methods, see the API reference.

Available PyBaMM models

PyBaMM includes a number of pre-implemented models, which can be used as they are or modified to suit your needs. The main models are:

• lithium_ion.SPM: Single Particle Model

• lithium_ion.SPMe: Single Particle Model with Electrolyte

• lithium_ion.DFN: Doyle-Fuller-Newman

The behaviour of the models can be modified by passing in an BatteryModelOptions object when creating the model.

Simulations

Simulation is a class that automates the process of setting up a model and solving it, and acts as the highest-level API to PyBaMM. Pass at least a BaseModel object, and optionally the experiment, solver, parameter values, and geometry objects described below to the Simulation object. Any of these optional arguments not provided will be supplied by the defaults specified in the model.

Parameters

PyBaMM models are parameterised by a set of parameters, which are stored in a ParameterValues object. This object acts like a Python dictionary with a few extra PyBaMM specific features and methods. Parameters in a model are represented as either Parameter objects or FunctionParameter objects, and the values in the ParameterValues object replace these objects in the model before it is solved. The values in the ParameterValues object can be scalars, Python functions or expressions of type Symbol.

Experiments

An Experiment object represents an experimental protocol that can be used to simulate the behaviour of a battery. The particular protocol can be provided as a Python string, or as a sequences of step.BaseStep objects.

Solvers

The two main solvers in PyBaMM are the CasadiSolver and the IDAKLUSolver. Both are wrappers around the Sundials suite of solvers, but the CasadiSolver uses the CasADi library whereas the IDAKLUSolver is PyBaMM specific. Both solvers have many options that can be set to control the solver behaviour, see the documentation for each solver for more details.

When a model is solved, the solution is returned as a Solution object.

Plotting

A solution object can be plotted using the Solution.plot() or Simulation.plot() methods, which returns a QuickPlot object. Note that the arguments to the plotting methods of both classes are the same as QuickPlot.

Other plotting functions are the plot_voltage_components() and plot_summary_variables() functions, which correspond to the similarly named methods of the Solution and Simulation classes.

Writing PyBaMM models

Each PyBaMM model, and the custom models written by users, are written as a set of expressions that describe the model. Each of the expressions is a subclass of the Symbol class, which represents a mathematical expression.

If you wish to create a custom model, you can use the BaseModel class as a starting point.

Discretisation

Each PyBaMM model contains continuous operators that must be discretised before they can be solved. This is done using a Discretisation object, which takes a Mesh object and a dictionary of SpatialMethod objects.

Logging

PyBaMM uses the Python logging module to log messages at different levels of severity. Use the pybamm.set_logging_level() function to set the logging level for PyBaMM.