Update documentation for conflicting extras

README.md

@@ -26,10 +26,9 @@ Tools for machine learnt interatomic potentials
 - sevenn = 0.10.3 (optional)
 - alignn = 2024.5.27 (optional)
 
-All required and optional dependencies can be found in [pyproject.toml](pyproject.toml).
+Where possible, we aim to update pinned MLIP dependencies to match their latest releases, subject to any required API fixes.
 
-> [!NOTE]
-> Where possible, we expect to update pinned MLIP dependencies to match their latest releases, subject to any required API fixes.
+All required and optional dependencies can be found in [pyproject.toml](pyproject.toml).
 
 
 ### Installation
@@ -48,13 +47,22 @@ python3 -m pip install git+https://github.com/stfc/janus-core.git
 
 By default, MACE is the only MLIP installed.
 
-Other MLIPs can be installed as `extras`. For example, to install CHGNet and M3GNet, run:
+Other MLIPs can be installed as `extras`. For example, to install CHGNet and SevenNet, run:
 
 ```python
-python3 -m pip install janus-core[chgnet,m3gnet]
+python3 -m pip install janus-core[chgnet,sevennet]
 ```
 
-or to install all supported MLIPs:
+> [!WARNING]
+> `matgl` and `alignn` depend on [dgl](https://github.com/dmlc/dgl?tab=readme-ov-file), which no
+> longer publishes to PyPI. If `janus-core` is installed with either of these extras, PyTorch will
+> automatically be set to 2.2.0 to ensure compatibility. However, this is incompatible with `chgnet`,
+> and may limit the available features in others, including `mace`. To use `matgl` and/or `alignn` with
+> more recent PyTorch release, please refer to the
+> [installation documentation](https://stfc.github.io/janus-core/user_guide/installation.html).
+
+
+To install all MLIPs that do not depend on `dgl`:
 
 ```python
 python3 -m pip install janus-core[all]
@@ -290,7 +298,7 @@ We recommend installing uv for dependency management when developing for `janus-
 ```shell
 git clone https://github.com/stfc/janus-core
 cd janus-core
-uv sync --all-extras # Create a virtual environment and install all dependencies
+uv sync --extras all # Create a virtual environment and install dependencies
 source .venv/bin/activate
 pre-commit install  # Install pre-commit hooks
 pytest -v  # Discover and run all tests

docs/source/developer_guide/get_started.rst

@@ -27,11 +27,11 @@ Dependencies useful for development can then be installed by running::
 
 Extras, such as optional MLIPs, can also be installed by running::
 
-    uv sync -p 3.12 --extra alignn --extra sevennet
+    uv sync -p 3.12 --extra chgnet --extra sevennet
 
-or to install all supported MLIPs::
+or to install all MLIPs that do not depend on ``dgl``::
 
-    uv sync -p 3.12 --all-extras
+    uv sync -p 3.12 --extras all
 
 
 Using uv

docs/source/getting_started/getting_started.rst

@@ -15,10 +15,9 @@ Dependencies
 - sevenn = 0.10.3 (optional)
 - alignn = 2024.5.27 (optional)
 
-All required and optional dependencies can be found in `pyproject.toml <https://github.com/stfc/janus-core/blob/main/pyproject.toml>`_.
+Where possible, we aim to update pinned MLIP dependencies to match their latest releases, subject to any required API fixes.
 
-.. note::
-    Where possible, we expect to update pinned MLIP dependencies to match their latest releases, subject to any required API fixes.
+All required and optional dependencies can be found in `pyproject.toml <https://github.com/stfc/janus-core/blob/main/pyproject.toml>`_.
 
 
 Installation
@@ -38,13 +37,23 @@ To get all the latest changes, ``janus-core`` can also be installed from GitHub:
 
 By default, MACE is the only MLIP installed.
 
-Other MLIPs can be installed as ``extras``. For example, to install CHGNet and M3GNet, run:
+Other MLIPs can be installed as ``extras``. For example, to install CHGNet and SevenNet, run:
 
 .. code-block:: python
 
-    python3 -m pip install janus-core[chgnet,m3gnet]
+    python3 -m pip install janus-core[chgnet,sevennet]
+
+
+.. warning::
+
+    ``matgl`` and ``alignn`` depend on `dgl <https://github.com/dmlc/dgl?tab=readme-ov-file>`_,
+    which no longer publishes to PyPI. If ``janus-core`` is installed with either of these extras,
+    PyTorch will automatically be set to 2.2.0 to ensure compatibility. However, this is incompatible
+    with ``chgnet``, and may limit the available features in others, including ``mace``. To use
+    ``matgl`` and/or ``alignn`` with more recent PyTorch release, please refer to the
+    :doc:`installation documentation </user_guide/installation>`.
 
-or to install all supported MLIPs:
+To install all MLIPs that do not depend on `dgl`:
 
 .. code-block:: python
 

docs/source/user_guide/index.rst

@@ -5,6 +5,7 @@ User guide
 .. toctree::
     :maxdepth: 3
 
-    command_line
+    installation
     python
+    command_line
     troubleshooting

docs/source/user_guide/installation.rst

@@ -0,0 +1,77 @@
+============
+Installation
+============
+
+Updating Dependencies
+=====================
+
+Installing from PyPI
+--------------------
+
+When installing ``janus-core``, dependencies are automatically selected to be consistent with all
+``extras``.
+
+For an individual MLIP, you may be able to upgrade dependencies beyond these defaults,
+to include newer features or bug fixes. For example, to upgrade PyTorch to the latest version:
+
+.. code-block:: bash
+
+    python3 -m pip install -U torch
+
+
+or a specific version:
+
+.. code-block:: bash
+
+    python3 -m pip install torch==2.5.1
+
+
+.. tip::
+
+    If you are using ``uv``, ``python3 -m pip`` should be replaced with ``uv pip``
+
+
+Installing from git repositories
+--------------------------------
+
+It may be useful to upgrade dependencies to include their latest changes, or code in development,
+often available on GitHub or GitLab.
+
+For example, to use the latest version of ASE:
+
+.. code-block:: bash
+
+    python3 -m pip install git+https://gitlab.com/ase/ase.git
+
+Specific branches may also be targeted:
+
+.. code-block:: bash
+
+    python3 -m pip install git+https://gitlab.com/drFaustroll/ase.git@npt_triangular
+
+This will install the ``npt_triangular`` branch of https://gitlab.com/drFaustroll/ase, which includes a
+fix to allow NPT when the computational box is not an upper triangular matrix.
+
+
+Additional libraries
+--------------------
+
+Some libraries are not installed by default, but may improve performance, such as:
+
+- ``cuEquivariance`` can be used for `CUDA accerlation of MACE <https://mace-docs.readthedocs.io/en/latest/guide/cuda_acceleration.html>`_ (with PyTorch 2.4 onwards)
+- `PyTorch implementation of DFTD3 <https://github.com/CheukHinHoJerry/torch-dftd.git>`_, which can be used by MACE calculations on GPU
+
+
+Updating DGL
+------------
+
+`DGL <https://github.com/dmlc/dgl>`_, which is a dependency of ``alignn`` and ``matgl``, no longer
+publishes to PyPI, and no longer publishes any packages for Windows or MacOS.
+
+When installing these MLIPs, ``janus-core`` will therefore automatically install the ``dgl==2.1.0``,
+as well as ``torch==2.2.0``, to ensure full compatibility.
+
+To use ``alignn`` and/or ``matgl`` with more recent versions of PyTorch, ``torch`` and ``dgl`` must
+both be upgraded manually. Please refer to their
+`installation instructions <https://www.dgl.ai/pages/start.html>`_ to upgrade ``dgl``, ensuring
+that the PyTorch version, CUDA version, and OS are selected appropriately.