diff --git a/doc/source/installation.rst b/doc/source/installation.rst index 923d1aa1..a4ad505f 100644 --- a/doc/source/installation.rst +++ b/doc/source/installation.rst @@ -1,140 +1,227 @@ .. -*- coding: utf-8 -*- ==================== -Installation +Installation Guide ==================== -The latest versions of **MDAnalysis** can be installed using `conda` or `pip`. -Currently, the conda releases only support serial calculations. -If you plan to use the parallel OpenMP algorithms, you need to -install MDAnalysis with pip and have a working OpenMP installation. +The latest version of **MDAnalysis** can be installed using :ref:`mamba-installation` (recommended), +or :ref:`pip-installation`. If you need to install MDAnalysis from source, follow :ref:`source-installation` +for stable releases. If you are a contributor or developer working on MDAnalysis, follow the +:ref:`development-installation` for editable installation and code modifications. -MDAnalysis has a separate :ref:`test suite ` **MDAnalysisTests** that is required to run the test cases and examples. -The test files change less frequently, take up around 90 MB of space, -and are not needed for daily use of MDAnalysis. However, they are often used in examples, -including many in this User Guide. If you are not interested in developing -MDAnalysis or using the example files, you most likely don't need the tests. If you want to -run examples in the User Guide, install the tests. -The tests are distributed separately from the main package. +Currently, the :ref:`mamba-installation` installs a version of MDAnalysis that does **not** include `OpenMP`_ +acceleration due to limitations in precompiled conda packages. If you need `OpenMP`_-enabled features, +consider installing via :ref:`pip-installation` and compiling from source with a compatible compiler and +OpenMP support. + +**MDAnalysisTests** is optional and is a separate :ref:`test suite ` used +for verifying MDAnalysis installations and running User Guide examples. It is not required for +daily use, but some tutorials rely on it. The package is approximately 90 MB and is not updated frequently. +If you plan to use tutorial examples or contribute to MDAnalysis, installing it is recommended. + +MDAnalysis supports specific Python versions. For the latest supported versions, please refer to the +`CHANGELOG`_ or the `PyPI`_. Ensure you have a compatible Python version installed before proceeding. .. note:: + MDAnalysis supports **Linux**, **macOS**, and **Windows**. - If you are installing on Windows, you must have - Microsoft Visual C++ 14.0 installed. If your installation - fails with the error message: + - If you encounter errors on **Windows** related to **Microsoft Visual C++ 14.0**, install the required **Build Tools for Visual Studio** from: `Microsoft Visual Studio Downloads`_. + - If you encounter any other issues following these instructions, seek help on `GitHub Discussions (Installation)`_. - error: Microsoft Visual C++ 14.0 is required. Get it with "Build Tools for Visual Studio": https://visualstudio.microsoft.com/downloads/ +.. _mamba-installation: - Try installing Build Tools for Visual Studio from - https://visualstudio.microsoft.com/downloads/ (scroll - down to the Tools for Visual Studio section). +mamba/conda +=========== +For most users, `mamba`_ is the **recommended** way to install MDAnalysis. It is a faster drop-in +replacement for `conda`_ and efficiently handles dependencies. We also recommend creating a new +environment for MDAnalysis to ensure a clean and isolated installation. -If you encounter any issues following these instructions, please -ask for help on `GitHub Discussions (Installation)`_. +MDAnalysis supports two common ways to install with `mamba`_: -.. _`GitHub Discussions (Installation)`: https://github.com/MDAnalysis/mdanalysis/discussions/categories/installation +**1. Recommended: Use Mambaforge** -conda -===== +`Mambaforge`_ is a minimal `conda`_ distribution that includes `mamba`_ by default, uses the `conda-forge`_ channel +(preferred for MDAnalysis) and avoids clutter from `Anaconda`_ base packages. -If you use ``conda`` to manage your Python environment, we highly recommend creating a new environment for MDAnalysis. -This will ensure that you have a clean installation of MDAnalysis and its dependencies, and will not interfere with other packages you may have installed. -We further recommend that you install and use ``mamba``, a faster drop-in replacement for ``conda``. +To install MDAnalysis with `Mambaforge`_, follow the `mambaforge installation instructions`_ and then +run the following commands to install MDAnalysis: .. code-block:: bash - conda create --name mdanalysis - conda activate mdanalysis - conda install -c conda-forge mamba + mamba create -n mdanalysis -c conda-forge mdanalysis + mamba activate mdanalysis -To install the latest stable version of MDAnalysis via ``conda``, use the following command. This installs all dependencies needed for full analysis functionality (excluding external programs such as `HOLE`_): +To install the :ref:`test suite ` (optional, ~90 MB): .. code-block:: bash - mamba install -c conda-forge mdanalysis + mamba install -c conda-forge MDAnalysisTests -To upgrade: +To upgrade, use: .. code-block:: bash mamba update mdanalysis -To install the tests: +If you're using MDAnalysis in **JupyterLab**, install `ipywidgets`_ for progress bar support: .. code-block:: bash - mamba install -c conda-forge MDAnalysisTests + mamba install -c conda-forge ipywidgets + +**2. Alternative: Use conda with conda-forge** -If you intend to use MDAnalysis in JupyterLab, you will have to install -an extra package for the progress bar in analysis classes: +If you prefer using `conda`_ directly (e.g., installed via `Anaconda installer`_), create a new environment with packages from the `conda-forge`_ channel: .. code-block:: bash - conda install -c conda-forge nodejs - jupyter labextension install @jupyter-widgets/jupyterlab-manager + conda create -n mdanalysis -c conda-forge mdanalysis + conda activate mdanalysis + +To install optional packages: + +.. code-block:: bash + + conda install -c conda-forge MDAnalysisTests ipywidgets + +.. _pip-installation: pip -===== -The following command will install or upgrade the latest stable version of MDAnalysis via ``pip``, with core dependencies. This means that some packages required by specific analysis modules will not be installed. +=== + +The following command will install or upgrade the latest stable version of MDAnalysis via `pip`_ with core dependencies. +This means that some packages required by specific analysis modules will not be installed. .. code-block:: bash pip install --upgrade MDAnalysis -If you need to install a fully-featured MDAnalysis, add the ``analysis`` tag. As with ``conda``, this will not install external programs such as `HOLE`_. +MDAnalysis offers several optional dependency groups (“extra tags”) that you can install with pip to enable additional features: + +- ``analysis``: optional dependencies for various analysis modules. +- ``extra_formats``: support for additional file formats. +- ``parallel``: install dask to enable parallel analysis across multiple cores or machines. +- ``doc``: install documentation build dependencies (e.g. Sphinx, themes). + +To see the full list of available extras, check the `pyproject.toml file`_. + +To install with optional features, use pip with one or more extras: .. code-block:: bash - pip install --upgrade MDAnalysis[analysis] + pip install --upgrade MDAnalysis[analysis,extra_formats,parallel] -To install/upgrade tests: +To install or upgrade the :ref:`test suite ` (optional, ~90 MB): .. code-block:: bash pip install --upgrade MDAnalysisTests -If you intend to use MDAnalysis in JupyterLab, you will have to install -an extra package for the progress bar in analysis classes: +If you're using MDAnalysis in **JupyterLab**, install `ipywidgets`_ for progress bar support: .. code-block:: bash - pip install nodejs - jupyter labextension install @jupyter-widgets/jupyterlab-manager + pip install ipywidgets +.. _source-installation: -Development versions -==================== -To install development versions of MDAnalysis, you can compile it from source. In order to install from source, you will need ``numpy`` and ``cython``. See :ref:`create-virtual-environment` for instructions on how to create a full development environment. +Install from source +=================== + +This section is for **users** who want to install a **specific stable version** of MDAnalysis +(e.g., for reproducibility or to debug a release). This is **not** intended for development or code contributions. +If you're a developer, see :ref:`development-installation`. + +To install from source, you must first ensure that your environment already contains all necessary dependencies. +We recommend you check the :ref:`create-virtual-environment` to set up a clean development environment +with all required dependencies. We recommend using `mamba`_ or `conda`_ to manage this setup. + +Follow the steps in: + +- `Set up with conda-forge`_ +- `Set up with mamba`_ + +MDAnalysis uses different Git branches for different purposes: + +- **package-X.Y.Z**: These are tags, not branches, and represent stable release versions (e.g., package-2.9.0). These tags are ideal if you need reproducibility, debugging, or version locking. You can browse all tags on the GitHub `Branches page`_. +- **develop**: The `develop`_ branch is the default and active development branch. If you're contributing to MDAnalysis or want the latest unreleased features, base your work on this branch (see :ref:`development-installation`). + +Clone the repository and check out the tag corresponding to the desired version: .. code-block:: bash git clone https://github.com/MDAnalysis/mdanalysis cd mdanalysis - # assuming you have already installed required dependencies + git checkout package- + +You will now be in a detached HEAD state, which is expected when checking out a tag. This allows you to explore or install that version without affecting branches. +If you plan to make changes, you can create a new branch based on the tag: + +.. code-block:: bash + + git switch -c my-fix-based-on-2.9.0 + +To install MDAnalysis from this version: + +.. code-block:: bash + + pip install package/. + +To run tests: + +.. code-block:: bash + + pip install MDAnalysisTests + +.. _development-installation: + +Install for development +========================== + +This section is for **contributors and developers** who want to modify MDAnalysis +or contribute to its development. You’ll install MDAnalysis in **editable mode**, which allows you to make code changes +without reinstalling the package each time. + +Before installing, follow the steps described in the :ref:`source-installation` to set up a clean environment +with all dependencies. + +Once your environment is ready, install MDAnalysis in editable mode: + +.. code-block:: bash + + git clone https://github.com/MDAnalysis/mdanalysis + cd mdanalysis + git switch develop # work on the develop branch + git checkout -b my-feature-branch # Create a new branch for your changes pip install -e package/ -And to install the test suite: +Installing in editable mode (`-e`) means that any changes you make to the MDAnalysis source code are immediately +available without needing to reinstall. + +If you plan to run tests you can install the test suite: .. code-block:: bash + # Install the test suite (optional but recommended for contributors) pip install -e testsuite/ +For more on how to set up and contribute, refer to the :ref:`contributing` guide. Testing ------- -The tests rely on the `pytest` and `numpy` packages, which must also be installed. Run tests with: +The tests rely on the `pytest`_ and `numpy`_ packages, which must also be installed. Run tests with: .. code-block:: bash pytest --disable-pytest-warnings --pyargs MDAnalysisTests All tests should pass (i.e. no FAIL, ERROR); SKIPPED or XFAIL are ok. If anything fails or gives an error, -`ask on GitHub Discussions `_ or `raise an issue `_. +ask on `GitHub Discussions`_ or `raise an issue`_. -Testing MDAnalysis can take a while, as there are quite a few tests. -The plugin `pytest-xdist `_ can be used to run tests in parallel. +Running MDAnalysis tests can take some time, as there are many test cases. +The plugin `pytest-xdist`_ can be used to run tests in parallel. .. code-block:: bash @@ -148,7 +235,7 @@ You can pass any additional compiler flags for the C/C++ compiler using the ``ex This allows you to add any additional compiler options required for your architecture. For example, ``extra_cflags`` can be used to tune your MDAnalysis installation for your current architecture using the `-march`, `-mtune`, `-mcpu` and related compiler flags. -*Which* particular compiler flags to use depends on your CPU architecture. An example for an x86_64 machine would be to change the line in `setup.cfg` as follows: +The optimal compiler flags depend on your CPU architecture. Commonly recommended settings are: .. code-block:: diff @@ -157,22 +244,24 @@ For example, ``extra_cflags`` can be used to tune your MDAnalysis installation f Use of these flags can give a significant performance boost where the compiler can effectively autovectorise. -Be sure to use the recommended flags for your target architecture. For example, ARM platforms recommend using ``-mcpu`` *instead* of ``-mcpu``, while -PowerPC platforms prefer *both* ``-mcpu`` and ``-mtune``. +Be sure to use the recommended flags for your target architecture. In many cases, +``-march`` and ``-mcpu`` can be used together or separately, and their behavior depends +on your platform and compiler version. For example, ARM platforms often prefer ``-mcpu``, +while PowerPC may use both ``-mcpu`` and ``-mtune``. Refer to the `GCC documentation on -march`_ +and `-mcpu`_ for platform-specific guidance. -Full dicussion of the these flags is available elsewhere (such as here in this wiki_ or in this ARM_ blog post) and a list of supported options should be provided by your compiler. The list for GCC_ is provided here. +Full discussion of these flags is available elsewhere (such as here in this `wiki`_ or in this `ARM`_ blog post) and a list of supported options should be provided by your compiler. The list for GCC_ is provided here. .. warning:: - Use of these compiler options is considered **advanced** and may reduce the binary compatibility of MDAnalysis significantly, especially if using `-march`, - making it usable only on a matching CPU architecture to the one it is compiled on. We **strongly** recommend that you run the test suite on your intended platform - before proceeding with analysis. + These compiler options are **advanced** and may reduce binary compatibility. In particular, using `-march` may restrict MDAnalysis to the exact CPU architecture it was compiled on. + We **strongly recommend** that you run the test suite on your intended platform before proceeding with analysis. In cases where you might encounter multiple CPU architectures (e.g. on a supercomputer where the login node and compute node have different architectures), you should avoid changing these options unless you are experienced with compiling software in these situations. Additional datasets =================== -MDAnalysisData_ is an additional package with datasets that can be used in example tutorials. You can install it with ``conda`` or ``pip``: +MDAnalysisData_ is an additional package with datasets that can be used in example tutorials. You can install it with `mamba`_ / `conda`_ or `pip`_: .. code-block:: bash @@ -183,9 +272,35 @@ MDAnalysisData_ is an additional package with datasets that can be used in examp This installation does not download all the datasets; instead, the datasets are cached when they are first downloaded using a Python command. - -.. _`HOLE`: http://www.holeprogram.org .. _GCC: https://gcc.gnu.org/onlinedocs/gcc/x86-Options.html .. _MDAnalysisData: https://www.mdanalysis.org/MDAnalysisData/ .. _wiki: https://wiki.gentoo.org/wiki/GCC_optimization#-march .. _ARM: https://community.arm.com/arm-community-blogs/b/tools-software-ides-blog/posts/compiler-flags-across-architectures-march-mtune-and-mcpu +.. _pip: https://pip.pypa.io/en/latest/index.html +.. _mamba: https://anaconda.org/conda-forge/mamba +.. _conda: https://docs.conda.io/projects/conda/en/latest/ +.. _source: https://github.com/MDAnalysis/mdanalysis/ +.. _GitHub Discussions (Installation): https://github.com/MDAnalysis/mdanalysis/discussions/categories/installation +.. _Microsoft Visual Studio Downloads: https://visualstudio.microsoft.com/downloads/ +.. _pytest: https://docs.pytest.org/en/stable/ +.. _numpy: https://numpy.org/ +.. _Github discussions: https://github.com/MDAnalysis/mdanalysis/discussions +.. _raise an issue: https://github.com/MDAnalysis/mdanalysis/issues +.. _pytest-xdist: https://github.com/pytest-dev/pytest-xdist +.. _OpenMP: https://www.openmp.org/ +.. _mambaforge installation instructions: https://mamba.readthedocs.io/en/latest/installation/mamba-installation.html +.. _Mambaforge: https://github.com/conda-forge/miniforge#mambaforge +.. _conda-forge: https://conda-forge.org/ +.. _Anaconda: https://www.anaconda.com/products/distribution +.. _ipywidgets: https://ipywidgets.readthedocs.io/en/stable/ +.. _Releases page: https://github.com/MDAnalysis/mdanalysis/releases +.. _Set up with conda-forge: https://userguide.mdanalysis.org/stable/contributing_code.html#with-conda-forge-packages +.. _Set up with mamba: https://userguide.mdanalysis.org/stable/contributing_code.html#with-mamba-conda +.. _develop: https://github.com/MDAnalysis/mdanalysis/tree/develop +.. _Branches page: https://github.com/MDAnalysis/mdanalysis/branches/all +.. _CHANGELOG: https://github.com/MDAnalysis/mdanalysis/blob/develop/package/CHANGELOG +.. _PyPI: https://pypi.org/project/MDAnalysis/ +.. _pyproject.toml file: https://github.com/MDAnalysis/mdanalysis/blob/develop/package/pyproject.toml#L69 +.. _GCC documentation on -march: https://gcc.gnu.org/onlinedocs/gcc/x86-Options.html +.. _-mcpu: https://gcc.gnu.org/onlinedocs/gcc/ARM-Options.html +.. _Anaconda installer: https://docs.anaconda.com/free/anaconda/install/