This page describes the build and installation of PyBaMM from the source code, available on GitHub. Note that this is not the recommended approach for most users and should be reserved to people wanting to participate in the development of PyBaMM, or people who really need to use bleeding-edge feature(s) not yet available in the latest released version. If you do not fall in the two previous categories, you would be better off installing PyBaMM using pip or conda.
Lastly, familiarity with the Python ecosystem is recommended (pip, virtualenvs). Here is a gentle introduction/refresher: Python Virtual Environments: A Primer.
The following instructions are valid for both GNU/Linux distributions and MacOS. If you are running Windows, consider using the Windows Subsystem for Linux (WSL).
To obtain the PyBaMM source code, clone the GitHub repository
git clone https://github.com/pybamm-team/PyBaMM.git
or download the source archive on the repository’s homepage.
To install PyBaMM, you will need:
Python 3 (PyBaMM supports versions 3.8, 3.9, 3.10, and 3.11)
The Python headers file for your current Python version.
A BLAS library (for instance openblas).
A C compiler (ex:
A Fortran compiler (ex:
graphviz(optional), if you wish to build the documentation locally.
You can install the above with
sudo apt install python3.X python3.X-dev libopenblas-dev gcc gfortran graphviz
X is the version sub-number.
brew install python openblas gcc gfortran graphviz libomp
Finally, we recommend using Nox. You can install it with
python3.X -m pip install --user nox
Depending on your operating system, you may or may not have
pip installed along Python.
pip is not found, you probably want to install the
PyBaMM comes with a DAE solver based on the IDA solver provided by the SUNDIALS library. To use this solver, you must make sure that you have the necessary SUNDIALS components installed on your system.
The IDA-based solver is currently unavailable on windows. If you are running windows, you can simply skip this section and jump to Installing PyBaMM.
# in the PyBaMM/ directory nox -s pybamm-requires
This will download, compile and install the SuiteSparse and SUNDIALS libraries.
Both libraries are installed in
If you’d rather do things yourself,
Make sure you have CMake installed
Compile and install SuiteSparse (PyBaMM only requires the
Compile and install SUNDIALS.
Clone the pybind11 repository in the
PyBaMM/directory (make sure the directory is named
PyBaMM ships with a Python script that automates points 2. and 3. You can run it with
You should now have everything ready to build and install PyBaMM successfully.
# in the PyBaMM/ directory nox -s dev
It is recommended to use
-v to see outputs of all commands run.
You can now activate the environment with
and run the tests to check your installation.
PyBaMM/ directory, you can install PyBaMM using
pip install .
If you intend to contribute to the development of PyBaMM, it is convenient to install in “editable mode”, along with all the optional dependencies and useful tools for development and documentation:
pip install -e .[all,dev,docs]
If you are using
zsh, you would need to use different pattern matching:
pip install -e '.[all,dev,docs]'
Before you start contributing to PyBaMM, please read the contributing guidelines.
You can use Nox to run the unit tests and example notebooks in isolated virtual environments.
The default command
will run pre-commit, install
Linux dependencies, and run the unit tests.
This can take several minutes.
To just run the unit tests, use
nox -s unit
Similarly, to run the integration tests, use
nox -s integration
Finally, to run the unit and the integration suites sequentially, use
nox -s tests
You can run unit tests for PyBaMM using
# in the PyBaMM/ directory python run-tests.py --unit
The above starts a sub-process using the current python interpreter (i.e. using your current Python environment) and run the unit tests. This can take a few minutes.
You can also use the test runner to run the doctests:
python run-tests.py --doctest
There is more to the PyBaMM test runner. To see a list of all options, type
python run-tests.py --help
The documentation is built using
nox -s docs
This will build the documentation and serve it locally (thanks to sphinx-autobuild) for preview. The preview will be updated automatically following changes.
Nox can also be used to run doctests, run examples, and generate a coverage report using:
nox -s examples: Run the Jupyter notebooks in
nox -s scripts: Run the example scripts in
nox -s doctests: Run doctests.
nox -s coverage: Measure current test coverage and generate a coverage report.
nox -s quick: Run integration tests, unit tests, and doctests sequentially.
Here are some additional useful commands you can run with
--verbose or -v: Enables verbose mode, providing more detailed output during the execution of Nox sessions.
--list or -l: Lists all available Nox sessions and their descriptions.
--stop-on-first-error: Stops the execution of Nox sessions immediately after the first error or failure occurs.
--envdir <path>: Specifies the directory where Nox creates and manages the virtual environments used by the sessions. In this case, the directory is set to
--install-only: Skips the test execution and only performs the installation step defined in the Nox sessions.
--nocolor: Disables the color output in the console during the execution of Nox sessions.
--report output.json: Generates a JSON report of the Nox session execution and saves it to the specified file, in this case, “output.json”.
Problem: I’ve made edits to source files in PyBaMM, but these are not being used when I run my Python script.
Solution: Make sure you have installed PyBaMM using the
pip install -e .. This sets the installed location of the
source files to your current directory.
Problem: Errors when solving model
ValueError: Integrator name ida does not exsist, or
ValueError: Integrator name cvode does not exsist.
Solution: This could mean that you have not installed
scikits.odes correctly, check the instructions given above and make
sure each command was successful.
One possibility is that you have not set your
point to the sundials library, type
echo $LD_LIBRARY_PATH and make
sure one of the directories printed out corresponds to where the
sundials libraries are located.
Another common reason is that you forget to install a BLAS library such as OpenBLAS before installing sundials. Check the cmake output when you configured Sundials, it might say:
-- A library with BLAS API not found. Please specify library location. -- LAPACK requires BLAS
If this is the case, on a Debian or Ubuntu system you can install
sudo apt-get install libopenblas-dev (or
brew install openblas for Mac OS) and then re-install sundials using
the instructions above.