Skip to content

Commit

Permalink
fix installation instructions and recommend mamba instead of conda (#370
Browse files Browse the repository at this point in the history 
)

* fix #361
  * recommend mamba over conda
  * include standard mamba installation instructions
  * See @mikemhenry comment #361 (comment)
* 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>
  • Loading branch information
@orbeckst @IAlibay
orbeckst and IAlibay authored Aug 15, 2024
1 parent a08963a commit faa7623
Showing 1 changed file with 118 additions and 65 deletions.
183 changes: 118 additions & 65 deletions doc/source/contributing_code.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -69,32 +69,37 @@ 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.

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.
Expand All @@ -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:

Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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:
Expand Down

0 comments on commit faa7623

Please sign in to comment.