Merge pull request #3044 from arjxn-py/make-deps-optional

Create Optional Dependencies
pybamm-team · Jul 6, 2023 · fffe650 · fffe650
2 parents 36ef0ec + 63524b4
commit fffe650
Show file tree

Hide file tree

Showing 6 changed files with 194 additions and 24 deletions.
diff --git 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
@@ -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
@@ -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
@@ -50,8 +50,152 @@ Following GNU/Linux and macOS solvers are optionally available:
 *  `scikits.odes <https://scikits-odes.readthedocs.io/en/latest/>`_ -based solver, see `Optional - scikits.odes solver <https://pybamm.readthedocs.io/en/latest/source/user_guide/installation/GNU-linux.html#optional-scikits-odes-solver>`_.
 *  `jax <https://jax.readthedocs.io/en/latest/notebooks/quickstart.html>`_ -based solver, see `Optional - JaxSolver <https://pybamm.readthedocs.io/en/latest/source/user_guide/installation/GNU-linux.html#optional-jaxsolver>`_.
 
+Dependencies
+------------
+.. _install.required_dependencies:
+
+Required dependencies
+~~~~~~~~~~~~~~~~~~~~~
+
+PyBaMM requires the following dependencies.
+
+================================================================ ==========================
+Package                                                          Minimum supported version
+================================================================ ==========================
+`NumPy <https://numpy.org>`__                                    1.16.0
+`SciPy <https://docs.scipy.org/doc/scipy/>`__                    2.8.2
+`pandas <https://pandas.pydata.org/docs/>`__                     0.24.0
+`CasADi <https://web.casadi.org/docs/>`__                        3.6.0
+`Xarray <https://docs.xarray.dev/en/stable/>`__                  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 <https://imageio.readthedocs.io/en/stable/>`__     2.9.0              plot               For generating simulation GIFs.
+`matplotlib <https://matplotlib.org/stable/>`__             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 <https://www.sphinx-doc.org/en/master/>`__                                                1.5.0              docs               Sphinx makes it easy to create intelligent and beautiful documentation.
+`pydata-sphinx-theme <https://pydata-sphinx-theme.readthedocs.io/en/stable/>`__                   \-                 docs               A clean, Bootstrap-based Sphinx theme.
+`sphinx_design <https://sphinx-design.readthedocs.io/en/latest/>`__                               \-                 docs               A sphinx extension for designing.
+`sphinx-copybutton <https://sphinx-copybutton.readthedocs.io/en/latest/>`__                       \-                 docs               To copy codeblocks.
+`myst-parser <https://myst-parser.readthedocs.io/en/latest/>`__                                   \-                 docs               For technical & scientific documentation.
+`sphinx-inline-tabs <https://sphinx-inline-tabs.readthedocs.io/en/latest/>`__                     \-                 docs               Add inline tabbed content to your Sphinx documentation.
+`sphinxcontrib-bibtex <https://sphinxcontrib-bibtex.readthedocs.io/en/latest/>`__                 \-                 docs               For BibTeX citations.
+`sphinx-autobuild <https://sphinx-extensions.readthedocs.io/en/latest/sphinx-autobuild.html>`__   \-                 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 <https://docs.jupyter.org/en/latest/>`__                                \-                 examples           For example notebooks rendering.
+================================================================================ ================== ================== ================================
+
+.. _install.dev_dependencies:
+
+Dev dependencies
+^^^^^^^^^^^^^^^^^
+
+Installable with ``pip install "pybamm[dev]"``
+
+================================================================================ ================== ================== =============================================================
+Dependency                                                                       Minimum Version    pip extra          Notes
+================================================================================ ================== ================== =============================================================
+`pre-commit <https://pre-commit.com/index.html>`__                               \-                 dev                For managing and maintaining multi-language pre-commit hooks.
+`black <https://black.readthedocs.io/en/stable/>`__                              \-                 dev                For code formatting.
+================================================================================ ================== ================== =============================================================
+
+.. _install.cite_dependencies:
+
+Cite dependencies
+^^^^^^^^^^^^^^^^^
+
+Installable with ``pip install "pybamm[cite]"``
+
+=========================================================== ================== ================== =========================================
+Dependency                                                  Minimum Version    pip extra          Notes
+=========================================================== ================== ================== =========================================
+`pybtex <https://docs.pybtex.org/>`__                       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 <https://docs.sympy.org/latest/index.html>`__        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 <https://pypi.org/project/bpx/>`__                     \-                 bpx                Battery Parameter eXchange
+=========================================================== ================== ================== ==========================
+
+.. _install.tqdm_dependencies:
+
+tqdm dependencies
+^^^^^^^^^^^^^^^^^
+
+Installable with ``pip install "pybamm[tqdm]"``
+
+=========================================================== ================== ================== ==================
+Dependency                                                  Minimum Version    pip extra          Notes
+=========================================================== ================== ================== ==================
+`tqdm <https://tqdm.github.io/>`__                          \-                 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
@@ -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,15 +54,15 @@ 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")
 
 
 @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
@@ -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={