diff --git a/CHANGELOG.md b/CHANGELOG.md index 5b8d09e06d..af7f75d281 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,9 @@ # [Unreleased](https://github.com/pybamm-team/PyBaMM/) +## Breaking changes + +- PyBaMM now has optional dependencies that can be installed with the pattern `pip install pybamm[option]` e.g. `pybamm[plot]` ([#3044](https://github.com/pybamm-team/PyBaMM/pull/3044)) + ## Bug fixes - Parameters in `Prada2013` have been updated to better match those given in the paper, which is a 2.3 Ah cell, instead of the mix-and-match with the 1.1 Ah cell from Lain2019. diff --git a/README.md b/README.md index 8cc7564a21..f41eaa56d9 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ [![Scheduled](https://github.com/pybamm-team/PyBaMM/actions/workflows/run_periodic_tests.yml/badge.svg?branch=develop)](https://github.com/pybamm-team/PyBaMM/actions/workflows/run_periodic_tests.yml) [![readthedocs](https://readthedocs.org/projects/pybamm/badge/?version=latest)](https://pybamm.readthedocs.io/en/latest/?badge=latest) [![codecov](https://codecov.io/gh/pybamm-team/PyBaMM/branch/main/graph/badge.svg)](https://codecov.io/gh/pybamm-team/PyBaMM) -[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/pybamm-team/PyBaMM/blob/develop/) +[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/pybamm-team/PyBaMM/blob/main/) [![DOI](https://zenodo.org/badge/DOI/10.5334/jors.309.svg)](https://doi.org/10.5334/jors.309) [![release](https://img.shields.io/github/v/release/pybamm-team/PyBaMM?color=yellow)](https://github.com/pybamm-team/PyBaMM/releases) [![black code style](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black) diff --git a/docs/requirements.txt b/docs/requirements.txt index 0d641f4e37..e91a003d82 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -11,6 +11,7 @@ jupyter # For example notebooks pybtex sympy >= 1.8 xarray +tqdm # Note: Matplotlib is loaded for debug plots but to ensure pybamm runs # on systems without an attached display it should never be imported # outside of plot() methods. diff --git a/docs/source/user_guide/installation/index.rst b/docs/source/user_guide/installation/index.rst index 636be8743f..8d7f282e6b 100644 --- a/docs/source/user_guide/installation/index.rst +++ b/docs/source/user_guide/installation/index.rst @@ -50,8 +50,152 @@ Following GNU/Linux and macOS solvers are optionally available: * `scikits.odes `_ -based solver, see `Optional - scikits.odes solver `_. * `jax `_ -based solver, see `Optional - JaxSolver `_. +Dependencies +------------ +.. _install.required_dependencies: + +Required dependencies +~~~~~~~~~~~~~~~~~~~~~ + +PyBaMM requires the following dependencies. + +================================================================ ========================== +Package Minimum supported version +================================================================ ========================== +`NumPy `__ 1.16.0 +`SciPy `__ 2.8.2 +`pandas `__ 0.24.0 +`CasADi `__ 3.6.0 +`Xarray `__ 2023.04.0 +================================================================ ========================== + +.. _install.optional_dependencies: + +Optional Dependencies +~~~~~~~~~~~~~~~~~~~~~ + +PyBaMM has a number of optional dependencies for different functionalities. +If the optional dependency is not installed, PyBaMM will raise an ImportError when the method requiring that dependency is called. + +If using pip, optional PyBaMM dependencies can be installed or managed in a file (e.g. requirements.txt or setup.py) +as optional extras (e.g.,``pybamm[dev,plot]``). All optional dependencies can be installed with ``pybamm[all]``, +and specific sets of dependencies are listed in the sections below. + +.. _install.plot_dependencies: + +Plot dependencies +^^^^^^^^^^^^^^^^^ + +Installable with ``pip install "pybamm[plot]"`` + +=========================================================== ================== ================== ================================================================== +Dependency Minimum Version pip extra Notes +=========================================================== ================== ================== ================================================================== +`imageio `__ 2.9.0 plot For generating simulation GIFs. +`matplotlib `__ 2.0.0 plot To plot various battery models, and analyzing battery performance. +=========================================================== ================== ================== ================================================================== + +.. _install.docs_dependencies: + +Docs dependencies +^^^^^^^^^^^^^^^^^ + +Installable with ``pip install "pybamm[docs]"`` + +================================================================================================= ================== ================== ======================================================================= +Dependency Minimum Version pip extra Notes +================================================================================================= ================== ================== ======================================================================= +`sphinx `__ 1.5.0 docs Sphinx makes it easy to create intelligent and beautiful documentation. +`pydata-sphinx-theme `__ \- docs A clean, Bootstrap-based Sphinx theme. +`sphinx_design `__ \- docs A sphinx extension for designing. +`sphinx-copybutton `__ \- docs To copy codeblocks. +`myst-parser `__ \- docs For technical & scientific documentation. +`sphinx-inline-tabs `__ \- docs Add inline tabbed content to your Sphinx documentation. +`sphinxcontrib-bibtex `__ \- docs For BibTeX citations. +`sphinx-autobuild `__ \- docs For re-building docs once triggered. +================================================================================================= ================== ================== ======================================================================= + +.. _install.examples_dependencies: + +Examples dependencies +^^^^^^^^^^^^^^^^^^^^^ + +Installable with ``pip install "pybamm[examples]"`` + +================================================================================ ================== ================== ================================ +Dependency Minimum Version pip extra Notes +================================================================================ ================== ================== ================================ +`jupyter `__ \- examples For example notebooks rendering. +================================================================================ ================== ================== ================================ + +.. _install.dev_dependencies: + +Dev dependencies +^^^^^^^^^^^^^^^^^ + +Installable with ``pip install "pybamm[dev]"`` + +================================================================================ ================== ================== ============================================================= +Dependency Minimum Version pip extra Notes +================================================================================ ================== ================== ============================================================= +`pre-commit `__ \- dev For managing and maintaining multi-language pre-commit hooks. +`black `__ \- dev For code formatting. +================================================================================ ================== ================== ============================================================= + +.. _install.cite_dependencies: + +Cite dependencies +^^^^^^^^^^^^^^^^^ + +Installable with ``pip install "pybamm[cite]"`` + +=========================================================== ================== ================== ========================================= +Dependency Minimum Version pip extra Notes +=========================================================== ================== ================== ========================================= +`pybtex `__ 0.24.0 cite BibTeX-compatible bibliography processor. +=========================================================== ================== ================== ========================================= + +.. _install.latexify_dependencies: + +Latexify dependencies +^^^^^^^^^^^^^^^^^^^^^ + +Installable with ``pip install "pybamm[latexify]"`` + +=========================================================== ================== ================== ========================= +Dependency Minimum Version pip extra Notes +=========================================================== ================== ================== ========================= +`sympy `__ 1.8.0 latexify For symbolic mathematics. +=========================================================== ================== ================== ========================= + +.. _install.bpx_dependencies: + +bpx dependencies +^^^^^^^^^^^^^^^^^ + +Installable with ``pip install "pybamm[bpx]"`` + +=========================================================== ================== ================== ========================== +Dependency Minimum Version pip extra Notes +=========================================================== ================== ================== ========================== +`bpx `__ \- bpx Battery Parameter eXchange +=========================================================== ================== ================== ========================== + +.. _install.tqdm_dependencies: + +tqdm dependencies +^^^^^^^^^^^^^^^^^ + +Installable with ``pip install "pybamm[tqdm]"`` + +=========================================================== ================== ================== ================== +Dependency Minimum Version pip extra Notes +=========================================================== ================== ================== ================== +`tqdm `__ \- tqdm For logging loops. +=========================================================== ================== ================== ================== + Full installation guide ------------------------ +----------------------- Installing a specific version? Installing from source? Check the advanced installation pages below diff --git a/noxfile.py b/noxfile.py index 34aa64652e..08b2845cec 100644 --- a/noxfile.py +++ b/noxfile.py @@ -38,7 +38,7 @@ def run_coverage(session): "LD_LIBRARY_PATH" ] = f"{homedir}/.local/lib:{session.env.get('LD_LIBRARY_PATH')}" session.install("coverage") - session.install("-e", ".") + session.install("-e", ".[all]") if sys.platform != "win32": session.install("scikits.odes") session.run("pybamm_install_jax") @@ -54,7 +54,7 @@ def run_integration(session): session.env[ "LD_LIBRARY_PATH" ] = f"{homedir}/.local/lib:{session.env.get('LD_LIBRARY_PATH')}" - session.install("-e", ".[dev]") + session.install("-e", ".[all]") if sys.platform == "linux": session.install("scikits.odes") session.run("python", "run-tests.py", "--integration") @@ -62,7 +62,7 @@ def run_integration(session): @nox.session(name="doctests", reuse_venv=True) def run_doctests(session): - session.install("-e", ".[docs]") + session.install("-e", ".[all,docs]") session.run("python", "run-tests.py", "--doctest") @@ -73,7 +73,7 @@ def run_unit(session): session.env[ "LD_LIBRARY_PATH" ] = f"{homedir}/.local/lib:{session.env.get('LD_LIBRARY_PATH')}" - session.install("-e", ".") + session.install("-e", ".[all]") if sys.platform == "linux": session.run("pybamm_install_jax") session.install("scikits.odes") @@ -82,7 +82,7 @@ def run_unit(session): @nox.session(name="examples", reuse_venv=True) def run_examples(session): - session.install("-e", ".[dev]") + session.install("-e", ".[all]") session.run("python", "run-tests.py", "--examples") @@ -91,7 +91,7 @@ def set_dev(session): homedir = os.getenv("HOME") LD_LIBRARY_PATH = f"{homedir}/.local/lib:{session.env.get('LD_LIBRARY_PATH')}" envbindir = session.bin - session.install("-e", ".[dev]") + session.install("-e", ".[all]") session.install("cmake") session.run( "echo", @@ -109,7 +109,7 @@ def run_tests(session): session.env[ "LD_LIBRARY_PATH" ] = f"{homedir}/.local/lib:{session.env.get('LD_LIBRARY_PATH')}" - session.install("-e", ".[dev]") + session.install("-e", ".[all]") if sys.platform == "linux" or sys.platform == "darwin": session.run("pybamm_install_jax") session.install("scikits.odes") @@ -119,7 +119,7 @@ def run_tests(session): @nox.session(name="docs", reuse_venv=True) def build_docs(session): envbindir = session.bin - session.install("-e", ".[docs]") + session.install("-e", ".[all,docs]") with session.chdir("docs/"): session.run( "sphinx-autobuild", diff --git a/setup.py b/setup.py index 5b7ee6e7d2..aabd460f4a 100644 --- a/setup.py +++ b/setup.py @@ -206,21 +206,8 @@ def compile_KLU(): "numpy>=1.16", "scipy>=1.3", "pandas>=0.24", - "anytree>=2.4.3", - "autograd>=1.2", - "scikit-fem>=0.2.0", "casadi>=3.6.0", - "imageio>=2.9.0", - "pybtex>=0.24.0", - "sympy>=1.8", "xarray", - "bpx", - "tqdm", - # Note: Matplotlib is loaded for debug plots, but to ensure pybamm runs - # on systems without an attached display, it should never be imported - # outside of plot() methods. - # Should not be imported - "matplotlib>=2.0", ], extras_require={ "docs": [ @@ -240,10 +227,44 @@ def compile_KLU(): "sphinx-gallery", "sphinx-hoverxref", ], # For doc generation + "examples": [ + "jupyter", # For example notebooks + ], + "plot": [ + "imageio>=2.9.0", + # Note: Matplotlib is loaded for debug plots, but to ensure pybamm runs + # on systems without an attached display, it should never be imported + # outside of plot() methods. + # Should not be imported + "matplotlib>=2.0", + ], + "cite": [ + "pybtex>=0.24.0", + ], + "latexify": [ + "sympy>=1.8", + ], + "bpx": [ + "bpx", + ], + "tqdm": [ + "tqdm", + ], "dev": [ "pre-commit", # For code style checking "black", # For code style auto-formatting - "jupyter", # For example notebooks + ], + "all": [ + "anytree>=2.4.3", + "autograd>=1.2", + "scikit-fem>=0.2.0", + "imageio>=2.9.0", + "pybtex>=0.24.0", + "sympy>=1.8", + "bpx", + "tqdm", + "matplotlib>=2.0", + "jupyter", ], }, entry_points={