From faa76234615dc209412ce9e678773dd3cac1f04e Mon Sep 17 00:00:00 2001
From: Oliver Beckstein <orbeckst@gmail.com>
Date: Wed, 14 Aug 2024 20:27:26 -0700
Subject: [PATCH] fix installation instructions and recommend mamba instead of
conda (#370)
* fix #361
* recommend mamba over conda
* include standard mamba installation instructions
* See @mikemhenry comment https://github.com/MDAnalysis/UserGuide/issues/361#issuecomment-2176431603
* fix #368
* fix install instructions
* recommend Python 3.12 and recommend to remove unsupported opt packages
---------
Co-authored-by: IAlibay <IAlibay@users.noreply.github.com>
---
doc/source/contributing_code.rst | 183 ++++++++++++++++++++-----------
1 file changed, 118 insertions(+), 65 deletions(-)
diff --git a/doc/source/contributing_code.rst b/doc/source/contributing_code.rst
index 65bc8c98..eca7b9bc 100644
--- a/doc/source/contributing_code.rst
+++ b/doc/source/contributing_code.rst
@@ -69,24 +69,29 @@ You can do this either with :ref:`conda <dev-with-conda>` or :ref:`pip <dev-with
.. _dev-with-conda:
-With conda
-----------
+With conda-forge packages
+-------------------------
+
+We will use pre-compiled packages from the `conda-forge <https://conda-forge.org/>`_ repository.
+
+The program to manage these packages is called :program:`conda` although for the following we recommend using the faster one called :program:`mamba`. We will use ``mamba`` for the examples but you can equally use ``conda`` instead.
-Install either `Anaconda <https://www.anaconda.com/download/>`_
-or `miniconda <https://conda.io/miniconda.html>`_.
-Make sure your conda is up to date:
+* For ``mamba``, follow the `mamba installation instructions <https://mamba.readthedocs.io/en/latest/installation/mamba-installation.html>`_ or the `miniforge installation instructions <https://github.com/conda-forge/miniforge?tab=readme-ov-file#install>`_.
+* For ``conda`` install either the `Anaconda <https://www.anaconda.com/download/>`_ distribution or `miniconda <https://conda.io/miniconda.html>`_.
+
+Make sure your :program:`mamba` (or :program:`conda`) is up to date:
.. code-block:: bash
- conda update conda
+ mamba update mamba
-Create a new environment with ``conda create``. This will allow you to change code in
+Create a new environment with ``mamba create``. This will allow you to change code in
an isolated environment without touching your base Python installation, and without
touching existing environments that may have stable versions of MDAnalysis. :
.. code-block:: bash
- conda create --name mdanalysis-dev "python>=3.9"
+ mamba create --name mdanalysis-dev "python>=3.12"
Use a recent version of Python that is supported by MDAnalysis for this environment.
@@ -94,7 +99,7 @@ Activate the environment to build MDAnalysis into it:
.. code-block:: bash
- conda activate mdanalysis-dev
+ mamba activate mdanalysis-dev
.. warning::
Make sure the :code:`mdanalysis-dev` environment is active when developing MDAnalysis.
@@ -103,19 +108,19 @@ To view your environments:
.. code-block:: bash
- conda info -e
+ mamba info -e
To list the packages installed in your current environment:
.. code-block:: bash
- conda list
+ mamba list
.. note::
When you finish developing MDAnalysis you can deactivate the environment with
- :code:`conda deactivate`, in order to return to your root environment.
+ :code:`mamba deactivate`, in order to return to your root environment.
-See the full `conda documentation <http://conda.pydata.org/docs>`__ for more details.
+See the full `mamba documentation <https://mamba.readthedocs.io/en/latest/index.html>`_ or the full `conda documentation <https://docs.conda.io/projects/conda/>`_ for more details.
.. _dev-with-pip:
@@ -204,49 +209,77 @@ This sets the number of files to 4096. However, this command only applies to you
Building MDAnalysis
-------------------
-With conda
-----------
+With mamba/conda
+----------------
.. note::
Make sure that you have :ref:`cloned the repository <forking-code-repo>`
- and activated your virtual environment with :code:`conda activate mdanalysis-dev`.
+ and activated your virtual environment with :code:`mamba activate mdanalysis-dev`.
-First we need to install dependencies. You'll need a mix of conda and pip installations:
+First we need to install the dependencies. To install the base MDAnalysis
+dependencies, do the following:
.. code-block:: bash
- conda install -c conda-forge \
- 'Cython>=0.28' \
- 'numpy>=1.21.0' \
- 'biopython>=1.80' \
- 'networkx>=2.0' \
- 'GridDataFormats>=0.4.0' \
+ mamba install -c conda-forge \
+ 'cython>=0.28' \
+ 'fasteners' \
+ 'griddataformats>=0.4.0' \
+ 'hypothesis' \
+ 'matplotlib-base>=1.5.1' \
+ 'mdahole2-base' \
+ 'mda-xdrlib' \
'mmtf-python>=1.0.0' \
- 'joblib>=0.12' \
+ 'numpy>=1.23.2' \
+ 'packaging' \
+ 'pathsimanalysis' \
+ 'pytest' \
'scipy>=1.5.0' \
- 'matplotlib>=1.5.1' \
+ 'threadpoolctl' \
'tqdm>=4.43.0' \
- 'threadpoolctl'\
- 'packaging' \
- 'fasteners' \
- 'netCDF4>=1.0' \
- 'h5py>=2.10' \
+ 'waterdynamics'
+
+
+You can also install the following optional dependencies, although please note
+that they many not all be available for your machine type. Specifically,
+*hole2*, and *distopia* are only available on Linux + x86_64 machines, and *openmm*
+is not available for Windows. Simply remove any optional package that
+is not available for your operating system/architecture from your list.
+
+ .. code-block:: bash
+
+ mamba install -c conda-forge \
+ 'biopython>=1.80' \
'chemfiles>=0.10' \
- 'pyedr>=0.7.0' \
- 'pytng>=0.2.3' \
+ 'clustalw=2.1' \
+ 'distopia>=0.2.0' \
+ 'duecredit' \
'gsd>3.0.0' \
- 'rdkit>=2020.03.1' \
+ 'h5py>=2.1.0' \
+ 'hole2' \
+ 'joblib>=0.12' \
+ 'netcdf4' \
+ 'networkx' \
+ 'openmm' \
'parmed' \
- 'seaborn' \
+ 'pyedr>0.7.0' \
+ 'pytest-xdist' \
+ 'pytest-cov' \
+ 'pytest-timeout' \
+ 'pytng>=0.2.3' \
+ 'rdkit>=2020.03.1' \
'scikit-learn' \
- 'tidynamics>=1.0.0' \
- 'mda-xdrlib'
+ 'seaborn>=0.7.0' \
+ 'tidynamics>1.0.0'
# documentation dependencies
- conda install -c conda-forge 'mdanalysis-sphinx-theme>=1.3.0' docutils sphinx-sitemap sphinxcontrib-bibtex pybtex pybtex-docutils
- python -m pip install docutils sphinx-sitemap sphinxcontrib-bibtex pybtex pybtex-docutils
+ mamba install -c conda-forge \
+ 'mdanalysis-sphinx-theme>=1.3.0' \
+ docutils \
+ sphinxcontrib-bibtex \
+ sphinx-sitemap
-Ensure that you have a working C/C++ compiler (e.g. gcc or clang). You will also need Python ≥ 3.9. We will now install MDAnalysis.
+Ensure that you have a working C/C++ compiler (e.g. :program:`gcc` or :program:`clang`). You will also need Python ≥ 3.10 (which you already installed in your virtual environment). We will now install MDAnalysis.
.. code-block:: bash
@@ -268,7 +301,7 @@ At this point you should be able to import MDAnalysis from your locally built ve
$ python # start an interpreter
>>> import MDAnalysis as mda
>>> mda.__version__
- '2.6.0-dev0'
+ '2.8.0-dev0'
With pip and virtualenv
@@ -279,45 +312,65 @@ With pip and virtualenv
and activated your virtual environment with :code:`source myproject-env/bin/activate`
(or :code:`workon my-project` if you used the `virtualenvwrapper package <https://virtualenvwrapper.readthedocs.io/en/latest/>`_)
-Install the dependencies:
+First we need to install the dependencies. To install the base MDAnalysis
+dependencies, do the following:
.. code-block:: bash
python -m pip install \
- 'Cython>=0.28' \
- 'numpy>=1.21.0' \
- 'biopython>=1.80' \
- 'networkx>=2.0' \
- 'GridDataFormats>=0.4.0' \
+ 'cython>=0.28' \
+ 'fasteners' \
+ 'griddataformats>=0.4.0' \
+ 'hypothesis' \
+ 'matplotlib>=1.5.1' \
+ 'mdahole2' \
+ 'mda-xdrlib' \
'mmtf-python>=1.0.0' \
- 'joblib>=0.12' \
+ 'numpy>=1.23.2' \
+ 'packaging' \
+ 'pathsimanalysis' \
+ 'pytest' \
'scipy>=1.5.0' \
- 'matplotlib>=1.5.1' \
+ 'threadpoolctl' \
'tqdm>=4.43.0' \
- 'threadpoolctl'\
- 'packaging' \
- 'fasteners' \
- 'netCDF4>=1.0' \
- 'h5py>=2.10' \
+ 'waterdynamics'
+
+You can also install the following optional dependencies (note that
+you will not be able to install all the optional dependencies as
+many not available via `pip`, e.g. `clustalw`):
+
+ .. code-block:: bash
+
+ python -m pip install \
+ 'biopython>=1.80' \
'chemfiles>=0.10' \
- 'pyedr>=0.7.0' \
- 'pytng>=0.2.3' \
+ 'distopia>=0.2.0' \
+ 'duecredit' \
'gsd>3.0.0' \
- 'rdkit>=2020.03.1' \
+ 'h5py>=2.1.0' \
+ 'joblib>=0.12' \
+ 'netcdf4' \
+ 'networkx' \
'parmed' \
- 'seaborn' \
+ 'pyedr>0.7.0' \
+ 'pytest-xdist' \
+ 'pytest-cov' \
+ 'pytest-timeout' \
+ 'pytng>=0.2.3' \
+ 'rdkit>=2020.03.1' \
'scikit-learn' \
- 'tidynamics>=1.0.0' \
- 'mda-xdrlib'
+ 'seaborn>=0.7.0' \
+ 'tidynamics>1.0.0'
- # for building documentation
+ # documentation dependencies
python -m pip install \
- sphinx 'mdanalysis-sphinx-theme>=1.3.0' sphinx-sitemap \
- pybtex docutils pybtex-docutils sphinxcontrib-bibtex
+ 'mdanalysis-sphinx-theme>=1.3.0' \
+ docutils \
+ sphinxcontrib-bibtex \
+ sphinx-sitemap
-Some packages, such as ``clustalw``, are not available via pip.
-Ensure that you have a working C/C++ compiler (e.g. gcc or clang). You will also need Python ≥ 3.9. We will now install MDAnalysis.
+Ensure that you have a working C/C++ compiler (e.g. gcc or clang). You will also need Python ≥ 3.10. We will now install MDAnalysis.
.. code-block:: bash
@@ -339,7 +392,7 @@ At this point you should be able to import MDAnalysis from your locally built ve
$ python # start an interpreter
>>> import MDAnalysis as mda
>>> mda.__version__
- '2.7.0-dev0'
+ '2.8.0-dev0'
.. _branches-in-mdanalysis: