From 29e29fda7d17d3c9ad40a9b86ab17a606718de9f Mon Sep 17 00:00:00 2001 From: Namir Oues Date: Fri, 21 Feb 2025 20:19:54 +0000 Subject: [PATCH 01/11] Redesign installation guide in User Guide --- doc/source/installation.rst | 68 +++++++++++++------------------------ 1 file changed, 23 insertions(+), 45 deletions(-) diff --git a/doc/source/installation.rst b/doc/source/installation.rst index 923d1aa18..07d1f0c2d 100644 --- a/doc/source/installation.rst +++ b/doc/source/installation.rst @@ -1,70 +1,43 @@ .. -*- 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. - -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. +**MDAnalysis** can be installed using `conda `_ (recommended), `pip `_, or from `source `_ for development. .. note:: + MDAnalysis supports **Linux**, **macOS**, and **Windows** (Python 3.8+). + If you encounter installation issues, seek help on `GitHub Discussions (Installation) `_. - If you are installing on Windows, you must have - Microsoft Visual C++ 14.0 installed. If your installation - fails with the error message: - - error: Microsoft Visual C++ 14.0 is required. Get it with "Build Tools for Visual Studio": https://visualstudio.microsoft.com/downloads/ - - Try installing Build Tools for Visual Studio from - https://visualstudio.microsoft.com/downloads/ (scroll - down to the Tools for Visual Studio section). - - -If you encounter any issues following these instructions, please -ask for help on `GitHub Discussions (Installation)`_. - -.. _`GitHub Discussions (Installation)`: https://github.com/MDAnalysis/mdanalysis/discussions/categories/installation - -conda +Conda installation ===== -If you use ``conda`` to manage your Python environment, we highly recommend creating a new environment for MDAnalysis. +For most users, `conda `_ is the easiest way to install MDAnalysis. 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``. .. code-block:: bash conda create --name mdanalysis conda activate mdanalysis - conda install -c conda-forge mamba + conda install -c conda-forge 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 upgrade to the latest version: .. code-block:: bash - mamba install -c conda-forge mdanalysis + conda update mdanalysis -To upgrade: +To install the **test suite** (useful for examples and validation): .. code-block:: bash - mamba update mdanalysis + conda install MDAnalysisTests -To install the tests: - -.. code-block:: bash +.. warning:: + Conda installations **do not support OpenMP**. + If you need **parallel OpenMP calculations**, install MDAnalysis using `pip `_. - mamba install -c conda-forge MDAnalysisTests If you intend to use MDAnalysis in JupyterLab, you will have to install an extra package for the progress bar in analysis classes: @@ -74,21 +47,22 @@ an extra package for the progress bar in analysis classes: conda install -c conda-forge nodejs jupyter labextension install @jupyter-widgets/jupyterlab-manager -pip +Pip installation ===== -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. + +If you do not use Conda or require **OpenMP support**, install MDAnalysis via `pip `_: .. 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`_. +For full functionality with **analysis modules**: .. code-block:: bash pip install --upgrade MDAnalysis[analysis] -To install/upgrade tests: +To install the **test suite**: .. code-block:: bash @@ -102,6 +76,10 @@ an extra package for the progress bar in analysis classes: pip install nodejs jupyter labextension install @jupyter-widgets/jupyterlab-manager +.. note:: + If you are installing on **Windows**, and encounter errors related to **Microsoft Visual C++ 14.0**, install **Build Tools for Visual Studio** from `here `_. + +---------------------- Development versions ==================== From 556788f2cc5c8d0af7775c06b0125ebb221a5bbb Mon Sep 17 00:00:00 2001 From: Namir Oues Date: Sat, 22 Feb 2025 16:24:30 +0000 Subject: [PATCH 02/11] final clear version of Installation Guide --- doc/source/installation.rst | 83 ++++++++++++++++++++++--------------- 1 file changed, 50 insertions(+), 33 deletions(-) diff --git a/doc/source/installation.rst b/doc/source/installation.rst index 07d1f0c2d..cc3c82e03 100644 --- a/doc/source/installation.rst +++ b/doc/source/installation.rst @@ -4,42 +4,57 @@ Installation Guide ==================== -**MDAnalysis** can be installed using `conda `_ (recommended), `pip `_, or from `source `_ for development. +The latest version of **MDAnalysis** can be installed using: +`pip `_ (most common, for general users), +`conda `_ (recommended for better dependency management), +or from `source `_ (for development and contributing). 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. + +**MDAnalysisTests** is a optional and it 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 depend on it. The package is 90 MB and does not change frequently. If you plan to use tutorial examples +or contribute to MDAnalysis development, installing it is recommended. .. note:: - MDAnalysis supports **Linux**, **macOS**, and **Windows** (Python 3.8+). - If you encounter installation issues, seek help on `GitHub Discussions (Installation) `_. + MDAnalysis supports **Linux**, **macOS**, and **Windows** (Python 3.8+). + + - 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) `_. + +.. warning:: + `Conda `_ and `pip `_ installations **do not include** external programs such as `HOLE `_. Conda installation ===== - -For most users, `conda `_ is the easiest way to install MDAnalysis. 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. + +For most users, `conda `_ is the easiest way to install MDAnalysis because it manages dependencies effectively. +We highly recommend creating a new environment for MDAnalysis. We further recommend that you install and use ``mamba``, a faster drop-in replacement for ``conda``. .. code-block:: bash conda create --name mdanalysis conda activate mdanalysis - conda install -c conda-forge mdanalysis + conda install -c conda-forge mamba -To upgrade to the latest version: +To install the latest stable version of MDAnalysis via ``conda``, use the following command. This installs all dependencies needed for full analysis functionality. .. code-block:: bash - conda update mdanalysis + mamba install -c conda-forge mdanalysis -To install the **test suite** (useful for examples and validation): +To upgrade use: .. code-block:: bash - conda install MDAnalysisTests + mamba update mdanalysis -.. warning:: - Conda installations **do not support OpenMP**. - If you need **parallel OpenMP calculations**, install MDAnalysis using `pip `_. +To install the `test suite `_ use: + +.. code-block:: bash + mamba install -c conda-forge MDAnalysisTests -If you intend to use MDAnalysis in JupyterLab, you will have to install +If you intend to use MDAnalysis in **JupyterLab**, you will have to install an extra package for the progress bar in analysis classes: .. code-block:: bash @@ -47,28 +62,33 @@ an extra package for the progress bar in analysis classes: conda install -c conda-forge nodejs jupyter labextension install @jupyter-widgets/jupyterlab-manager +.. warning:: + MDAnalysis installed via conda does not support OpenMP. If you need **parallel OpenMP calculations**, + **install MDAnalysis** using `pip `_. + Pip installation ===== -If you do not use Conda or require **OpenMP support**, install MDAnalysis via `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. .. code-block:: bash pip install --upgrade MDAnalysis -For full functionality with **analysis modules**: + +If you need to install a fully-featured MDAnalysis, add the ``analysis`` tag. .. code-block:: bash pip install --upgrade MDAnalysis[analysis] -To install the **test suite**: +To install or upgrade the `test suite `_: .. code-block:: bash pip install --upgrade MDAnalysisTests -If you intend to use MDAnalysis in JupyterLab, you will have to install +If you intend to use MDAnalysis in **JupyterLab**, you will have to install an extra package for the progress bar in analysis classes: .. code-block:: bash @@ -76,15 +96,11 @@ an extra package for the progress bar in analysis classes: pip install nodejs jupyter labextension install @jupyter-widgets/jupyterlab-manager -.. note:: - If you are installing on **Windows**, and encounter errors related to **Microsoft Visual C++ 14.0**, install **Build Tools for Visual Studio** from `here `_. - ----------------------- - -Development versions +Install from `source `_ ==================== -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. +To install the latest development versions of MDAnalysis (including unreleased features and bug fixes) you can compile it from `source `_. Use the following commands: + .. code-block:: bash git clone https://github.com/MDAnalysis/mdanalysis @@ -92,17 +108,19 @@ To install development versions of MDAnalysis, you can compile it from source. I # assuming you have already installed required dependencies pip install -e package/ -And to install the test suite: +.. note:: + 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. + +To install the test suite: .. code-block:: bash pip install -e testsuite/ - 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 @@ -135,15 +153,14 @@ 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 +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``. 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. .. 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. From da287f28f672a5e26ca5bbb75bf82dce4033eb57 Mon Sep 17 00:00:00 2001 From: Namir Oues Date: Tue, 4 Mar 2025 16:20:48 +0000 Subject: [PATCH 03/11] update installation instructions in User Guide and address review comments --- doc/source/installation.rst | 107 ++++++++++++++++++++++-------------- 1 file changed, 67 insertions(+), 40 deletions(-) diff --git a/doc/source/installation.rst b/doc/source/installation.rst index cc3c82e03..1c5e3640c 100644 --- a/doc/source/installation.rst +++ b/doc/source/installation.rst @@ -4,31 +4,40 @@ Installation Guide ==================== -The latest version of **MDAnalysis** can be installed using: -`pip `_ (most common, for general users), -`conda `_ (recommended for better dependency management), -or from `source `_ (for development and contributing). 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:`conda-installation` (recommended), +or :ref:`pip-installation`. For development and contribution users can :ref:`source-installation`. + +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. + +**MDAnalysisTests** is optional and it 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 depend on it. The package is 90 MB and does not change frequently. +If you plan to use tutorial examples or contribute to MDAnalysis development, installing it is recommended. -**MDAnalysisTests** is a optional and it 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 depend on it. The package is 90 MB and does not change frequently. If you plan to use tutorial examples -or contribute to MDAnalysis development, installing it is recommended. +MDAnalysis requires Python 3.8 or later. Ensure you have an appropriate Python version installed before proceeding. .. note:: MDAnalysis supports **Linux**, **macOS**, and **Windows** (Python 3.8+). - - 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) `_. + - 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)`_. .. warning:: - `Conda `_ and `pip `_ installations **do not include** external programs such as `HOLE `_. + `conda`_ and `pip`_ installations **do not include** external programs such as `HOLE`_. + +.. _conda-installation: -Conda installation -===== +conda +====== -For most users, `conda `_ is the easiest way to install MDAnalysis because it manages dependencies effectively. -We highly recommend creating a new environment for MDAnalysis. We further recommend that you install and use ``mamba``, a faster drop-in replacement for ``conda``. +For most users, `conda`_ is the easiest way to install MDAnalysis because it manages dependencies effectively. +We highly recommend creating a new environment for MDAnalysis to ensure a clean installation of MDAnalysis and +its dependencies. We further recommend that you install and use `mamba`_, a faster drop-in replacement for `conda`_. + +If you don't have `conda`_ you can follow the `conda installation instructions`_. You can then create the environment +and install `mamba`_ with: .. code-block:: bash @@ -36,7 +45,7 @@ We highly recommend creating a new environment for MDAnalysis. We further recomm conda activate mdanalysis conda install -c conda-forge mamba -To install the latest stable version of MDAnalysis via ``conda``, use the following command. This installs all dependencies needed for full analysis functionality. +To install the latest stable version of MDAnalysis via `mamba`_ with all dependencies for full functionality, use the following command. .. code-block:: bash @@ -48,7 +57,7 @@ To upgrade use: mamba update mdanalysis -To install the `test suite `_ use: +To install the :ref:`test suite ` use: .. code-block:: bash @@ -62,14 +71,13 @@ an extra package for the progress bar in analysis classes: conda install -c conda-forge nodejs jupyter labextension install @jupyter-widgets/jupyterlab-manager -.. warning:: - MDAnalysis installed via conda does not support OpenMP. If you need **parallel OpenMP calculations**, - **install MDAnalysis** using `pip `_. +.. _pip-installation: -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 @@ -82,7 +90,7 @@ If you need to install a fully-featured MDAnalysis, add the ``analysis`` tag. pip install --upgrade MDAnalysis[analysis] -To install or upgrade the `test suite `_: +To install or upgrade the :ref:`test suite `: .. code-block:: bash @@ -96,41 +104,47 @@ an extra package for the progress bar in analysis classes: pip install nodejs jupyter labextension install @jupyter-widgets/jupyterlab-manager -Install from `source `_ -==================== +.. _source-installation: + +Install from source +=================== -To install the latest development versions of MDAnalysis (including unreleased features and bug fixes) you can compile it from `source `_. Use the following commands: +If you plan to develop or contribute to MDAnalysis, follow these instructions first. Then, refer to :ref:`contributing` for additional guidelines. + +To install the latest development versions of MDAnalysis (including unreleased features and bug fixes) you can compile it from `source`_. Use the following commands: .. code-block:: bash + # Clone the MDAnalysis repository git clone https://github.com/MDAnalysis/mdanalysis cd mdanalysis # assuming you have already installed required dependencies pip install -e package/ .. note:: - 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. + 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. To install the test suite: .. code-block:: bash - + + # Install the test suite (optional but recommended for contributors) pip install -e testsuite/ 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 @@ -144,7 +158,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. An example for an x86_64 machine would be to change the line in `setup.cfg` as follows: .. code-block:: diff @@ -153,10 +167,10 @@ 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. For example, ARM platforms recommend using ``-mcpu`` instead of ``-march``, while +PowerPC platforms prefer both ``-mcpu`` and ``-mtune``. -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:: 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. @@ -167,7 +181,7 @@ In cases where you might encounter multiple CPU architectures (e.g. on a superco 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 `conda`_ or `pip`_: .. code-block:: bash @@ -179,8 +193,21 @@ 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 +.. _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/ +.. _conda installation instructions: https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html \ No newline at end of file From ed4772dfe4d29677300b9415e3e0bec1a7021807 Mon Sep 17 00:00:00 2001 From: Namir Oues Date: Sat, 22 Mar 2025 20:25:38 +0000 Subject: [PATCH 04/11] Address PR review comments and update outdated content --- doc/source/installation.rst | 165 +++++++++++++++++++++++++----------- 1 file changed, 117 insertions(+), 48 deletions(-) diff --git a/doc/source/installation.rst b/doc/source/installation.rst index 1c5e3640c..828f1c7b2 100644 --- a/doc/source/installation.rst +++ b/doc/source/installation.rst @@ -4,17 +4,20 @@ Installation Guide ==================== -The latest version of **MDAnalysis** can be installed using :ref:`conda-installation` (recommended), -or :ref:`pip-installation`. For development and contribution users can :ref:`source-installation`. - -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. + +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 it 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 depend on it. The package is 90 MB and does not change frequently. -If you plan to use tutorial examples or contribute to MDAnalysis development, installing it is recommended. +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 requires Python 3.8 or later. Ensure you have an appropriate Python version installed before proceeding. @@ -25,51 +28,65 @@ MDAnalysis requires Python 3.8 or later. Ensure you have an appropriate Python v - If you encounter any other issues following these instructions, seek help on `GitHub Discussions (Installation)`_. .. warning:: - `conda`_ and `pip`_ installations **do not include** external programs such as `HOLE`_. + :ref:`mamba-installation` and :ref:`pip-installation` installations **do not include** external programs such as `HOLE`_. + +.. _mamba-installation: + +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. + +MDAnalysis supports two common ways to install with `mamba`_: -.. _conda-installation: +**1. Recommended: Use Mambaforge** -conda -====== - -For most users, `conda`_ is the easiest way to install MDAnalysis because it manages dependencies effectively. -We highly recommend creating a new environment for MDAnalysis to ensure a clean installation of MDAnalysis and -its dependencies. We further recommend that you install and use `mamba`_, a faster drop-in replacement for `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 don't have `conda`_ you can follow the `conda installation instructions`_. You can then create the environment -and install `mamba`_ with: +To install MDAnalysis with `Mambaforge`_, first download the `mambaforge installer`_ and then run: .. code-block:: bash - conda create --name mdanalysis - conda activate mdanalysis - conda install -c conda-forge mamba + mamba create -n mdanalysis mdanalysis + mamba activate mdanalysis -To install the latest stable version of MDAnalysis via `mamba`_ with all dependencies for full functionality, use the following command. +To install the :ref:`test suite ` (optional, ~90 MB): .. code-block:: bash - mamba install -c conda-forge mdanalysis + mamba install -c conda-forge MDAnalysisTests + +For more installation options (including Windows installers), see the `official mamba installation guide`_. -To upgrade use: +To upgrade, use: .. code-block:: bash mamba update mdanalysis -To install the :ref:`test suite ` use: +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: Install mamba to an existing conda installation** -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 already use `conda`_, you can add `mamba`_ to your base environment: .. code-block:: bash - conda install -c conda-forge nodejs - jupyter labextension install @jupyter-widgets/jupyterlab-manager + conda install -c conda-forge mamba + +Then create and activate an environment with MDAnalysis: + +.. code-block:: bash + + mamba create -n mdanalysis mdanalysis + mamba activate mdanalysis .. _pip-installation: @@ -83,54 +100,96 @@ This means that some packages required by specific analysis modules will not be pip install --upgrade MDAnalysis - -If you need to install a fully-featured MDAnalysis, add the ``analysis`` tag. +To install a fully-featured version of MDAnalysis (including optional analysis modules), use the ``analysis`` extra tag: .. code-block:: bash pip install --upgrade MDAnalysis[analysis] -To install or upgrade the :ref:`test suite `: +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: Install from source =================== -If you plan to develop or contribute to MDAnalysis, follow these instructions first. Then, refer to :ref:`contributing` for additional guidelines. +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 branches contain specific stable releases (e.g., ``package-2.9.0``) and are intended for users who need reproducibility, debugging, or version locking. You can browse them on the GitHub `Branches page`_ or view official releases on the `Releases page`_. +- **develop**: The `develop branch`_ is the default and active development branch. If you're contributing to MDAnalysis or want the latest features before they're released, base your work on this branch (see :ref:`development-installation`). + +To install the **latest stable release** from source: -To install the latest development versions of MDAnalysis (including unreleased features and bug fixes) you can compile it from `source`_. Use the following commands: - .. code-block:: bash - # Clone the MDAnalysis repository git clone https://github.com/MDAnalysis/mdanalysis cd mdanalysis - # assuming you have already installed required dependencies + git checkout release- + pip install . + +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 checkout develop # Switch to the development branch + git checkout -b my-feature-branch # Create a new branch for your changes pip install -e package/ -.. note:: - 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. +Installing in editable mode (`-e`) means that any changes you make to the MDAnalysis source code are immediately +available without needing to reinstall. -To install the test suite: +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 ------- @@ -181,7 +240,7 @@ In cases where you might encounter multiple CPU architectures (e.g. on a superco 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 @@ -210,4 +269,14 @@ This installation does not download all the datasets; instead, the datasets are .. _raise an issue: https://github.com/MDAnalysis/mdanalysis/issues .. _pytest-xdist: https://github.com/pytest-dev/pytest-xdist .. _OpenMP: https://www.openmp.org/ -.. _conda installation instructions: https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html \ No newline at end of file +.. _official mamba installation guide: https://mamba.readthedocs.io/en/latest/installation/mamba-installation.html +.. _mambaforge installer: https://github.com/conda-forge/miniforge#mambaforge +.. _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 branch: https://github.com/MDAnalysis/mdanalysis/tree/develop +.. _Branches page: https://github.com/MDAnalysis/mdanalysis/branches/all \ No newline at end of file From d0f1936c9a5bf97806d3560eb4174c1758f37d4d Mon Sep 17 00:00:00 2001 From: Namir Oues Date: Sun, 23 Mar 2025 08:37:07 +0000 Subject: [PATCH 05/11] address PR review comments --- doc/source/installation.rst | 42 ++++++++++++++++++++++--------------- 1 file changed, 25 insertions(+), 17 deletions(-) diff --git a/doc/source/installation.rst b/doc/source/installation.rst index 828f1c7b2..351b29a9c 100644 --- a/doc/source/installation.rst +++ b/doc/source/installation.rst @@ -14,22 +14,20 @@ acceleration due to limitations in precompiled conda packages. If you need `Open consider installing via :ref:`pip-installation` and compiling from source with a compatible compiler and OpenMP support. -**MDAnalysisTests** is optional and it is a separate :ref:`test suite ` used +**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 requires Python 3.8 or later. Ensure you have an appropriate Python version installed before proceeding. +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** (Python 3.8+). + MDAnalysis supports **Linux**, **macOS**, and **Windows**. - 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)`_. -.. warning:: - :ref:`mamba-installation` and :ref:`pip-installation` installations **do not include** external programs such as `HOLE`_. - .. _mamba-installation: mamba/conda @@ -46,7 +44,8 @@ MDAnalysis supports two common ways to install with `mamba`_: `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. -To install MDAnalysis with `Mambaforge`_, first download the `mambaforge installer`_ and then run: +To install MDAnalysis with `Mambaforge`_, follow the `mambaforge installation instructions`_ and then +run the following commands to install MDAnalysis: .. code-block:: bash @@ -59,8 +58,6 @@ To install the :ref:`test suite ` (optional, ~90 MB): mamba install -c conda-forge MDAnalysisTests -For more installation options (including Windows installers), see the `official mamba installation guide`_. - To upgrade, use: .. code-block:: bash @@ -100,11 +97,20 @@ This means that some packages required by specific analysis modules will not be pip install --upgrade MDAnalysis -To install a fully-featured version of MDAnalysis (including optional analysis modules), use the ``analysis`` extra tag: +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 or upgrade the :ref:`test suite ` (optional, ~90 MB): @@ -139,7 +145,7 @@ Follow the steps in: MDAnalysis uses different Git branches for different purposes: - **package-X.Y.Z**: These branches contain specific stable releases (e.g., ``package-2.9.0``) and are intended for users who need reproducibility, debugging, or version locking. You can browse them on the GitHub `Branches page`_ or view official releases on the `Releases page`_. -- **develop**: The `develop branch`_ is the default and active development branch. If you're contributing to MDAnalysis or want the latest features before they're released, base your work on this branch (see :ref:`development-installation`). +- **develop**: The `develop`_ branch is the default and active development branch. If you're contributing to MDAnalysis or want the latest features before they're released, base your work on this branch (see :ref:`development-installation`). To install the **latest stable release** from source: @@ -174,7 +180,7 @@ Once your environment is ready, install MDAnalysis in editable mode: git clone https://github.com/MDAnalysis/mdanalysis cd mdanalysis - git checkout develop # Switch to the development branch + 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/ @@ -269,8 +275,7 @@ This installation does not download all the datasets; instead, the datasets are .. _raise an issue: https://github.com/MDAnalysis/mdanalysis/issues .. _pytest-xdist: https://github.com/pytest-dev/pytest-xdist .. _OpenMP: https://www.openmp.org/ -.. _official mamba installation guide: https://mamba.readthedocs.io/en/latest/installation/mamba-installation.html -.. _mambaforge installer: https://github.com/conda-forge/miniforge#mambaforge +.. _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 @@ -278,5 +283,8 @@ This installation does not download all the datasets; instead, the datasets are .. _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 branch: https://github.com/MDAnalysis/mdanalysis/tree/develop -.. _Branches page: https://github.com/MDAnalysis/mdanalysis/branches/all \ No newline at end of file +.. _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/35d9d2e3ab08e7e6741b57fe02a7215fe3b91a6c/package/pyproject.toml#L69 \ No newline at end of file From 5ef1085bb74bd9976ff8cbb82b191ee1b796301b Mon Sep 17 00:00:00 2001 From: Namir Oues Date: Sun, 23 Mar 2025 08:39:03 +0000 Subject: [PATCH 06/11] Fix pre-commit: trim trailing whitespace and ensure EOF newline" --- doc/source/installation.rst | 72 ++++++++++++++++++------------------- 1 file changed, 35 insertions(+), 37 deletions(-) diff --git a/doc/source/installation.rst b/doc/source/installation.rst index 351b29a9c..ac7e4212d 100644 --- a/doc/source/installation.rst +++ b/doc/source/installation.rst @@ -4,44 +4,44 @@ Installation Guide ==================== -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 +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. -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 +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. +**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 +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**. + MDAnalysis supports **Linux**, **macOS**, and **Windows**. - - 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)`_. + - 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)`_. .. _mamba-installation: -mamba/conda +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 +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. MDAnalysis supports two common ways to install with `mamba`_: **1. Recommended: Use Mambaforge** -`Mambaforge`_ is a minimal `conda`_ distribution that includes `mamba`_ by default, uses the `conda-forge`_ channel +`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. To install MDAnalysis with `Mambaforge`_, follow the `mambaforge installation instructions`_ and then @@ -87,10 +87,10 @@ Then create and activate an environment with MDAnalysis: .. _pip-installation: -pip +pip === -The following command will install or upgrade the latest stable version of MDAnalysis via `pip`_ with core dependencies. +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 @@ -129,18 +129,18 @@ If you're using MDAnalysis in **JupyterLab**, install `ipywidgets`_ for progress 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. +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. +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`_ +- `Set up with mamba`_ MDAnalysis uses different Git branches for different purposes: @@ -153,7 +153,7 @@ To install the **latest stable release** from source: git clone https://github.com/MDAnalysis/mdanalysis cd mdanalysis - git checkout release- + git checkout release- pip install . To run tests: @@ -164,15 +164,15 @@ To run tests: .. _development-installation: -Install for development +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 +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. +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: @@ -184,7 +184,7 @@ Once your environment is ready, install MDAnalysis in editable mode: git checkout -b my-feature-branch # Create a new branch for your changes pip install -e package/ -Installing in editable mode (`-e`) means that any changes you make to the MDAnalysis source code are immediately +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: @@ -232,7 +232,7 @@ The optimal compiler flags depend on your CPU architecture. An example for an x8 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 ``-march``, while +Be sure to use the recommended flags for your target architecture. For example, ARM platforms recommend using ``-mcpu`` instead of ``-march``, while PowerPC platforms prefer both ``-mcpu`` and ``-mtune``. 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. @@ -257,13 +257,11 @@ 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 +.. _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/ @@ -271,9 +269,9 @@ This installation does not download all the datasets; instead, the datasets are .. _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 +.. _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 +.. _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 @@ -287,4 +285,4 @@ This installation does not download all the datasets; instead, the datasets are .. _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/35d9d2e3ab08e7e6741b57fe02a7215fe3b91a6c/package/pyproject.toml#L69 \ No newline at end of file +.. _pyproject.toml file: https://github.com/MDAnalysis/mdanalysis/blob/35d9d2e3ab08e7e6741b57fe02a7215fe3b91a6c/package/pyproject.toml#L69 From 61efd5e6bddd97148e060a835e0b5fc136cf3ba9 Mon Sep 17 00:00:00 2001 From: Namir Oues Date: Fri, 28 Mar 2025 19:29:49 +0000 Subject: [PATCH 07/11] address PR review comments --- doc/source/installation.rst | 26 ++++++++++++++++---------- 1 file changed, 16 insertions(+), 10 deletions(-) diff --git a/doc/source/installation.rst b/doc/source/installation.rst index ac7e4212d..1bd26df5f 100644 --- a/doc/source/installation.rst +++ b/doc/source/installation.rst @@ -49,7 +49,7 @@ run the following commands to install MDAnalysis: .. code-block:: bash - mamba create -n mdanalysis mdanalysis + mamba create -n mdanalysis -c conda-forge mdanalysis mamba activate mdanalysis To install the :ref:`test suite ` (optional, ~90 MB): @@ -70,20 +70,20 @@ If you're using MDAnalysis in **JupyterLab**, install `ipywidgets`_ for progress mamba install -c conda-forge ipywidgets -**2. Alternative: Install mamba to an existing conda installation** +**2. Alternative: Use conda with conda-forge** -If you already use `conda`_, you can add `mamba`_ to your base environment: +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 mamba + conda create -n mdanalysis -c conda-forge mdanalysis + conda activate mdanalysis -Then create and activate an environment with MDAnalysis: +To install optional packages: .. code-block:: bash - mamba create -n mdanalysis mdanalysis - mamba activate mdanalysis + conda install -c conda-forge MDAnalysisTests ipywidgets .. _pip-installation: @@ -223,7 +223,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. -The optimal compiler flags depend 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 @@ -232,8 +232,11 @@ The optimal compiler flags depend on your CPU architecture. An example for an x8 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 ``-march``, 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 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. @@ -286,3 +289,6 @@ This installation does not download all the datasets; instead, the datasets are .. _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/35d9d2e3ab08e7e6741b57fe02a7215fe3b91a6c/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/ \ No newline at end of file From cb102d980ecf397d6da56a15d50771a03f13534a Mon Sep 17 00:00:00 2001 From: Namir Oues Date: Fri, 28 Mar 2025 19:36:46 +0000 Subject: [PATCH 08/11] fix missing newline at end of installation.rst --- doc/source/installation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/installation.rst b/doc/source/installation.rst index 1bd26df5f..9122872d6 100644 --- a/doc/source/installation.rst +++ b/doc/source/installation.rst @@ -291,4 +291,4 @@ This installation does not download all the datasets; instead, the datasets are .. _pyproject.toml file: https://github.com/MDAnalysis/mdanalysis/blob/35d9d2e3ab08e7e6741b57fe02a7215fe3b91a6c/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/ \ No newline at end of file +.. _Anaconda installer: https://docs.anaconda.com/free/anaconda/install/ From e016913f5c65c0ac92be6c13b0c3ad533669d876 Mon Sep 17 00:00:00 2001 From: Oliver Beckstein Date: Sat, 29 Mar 2025 02:02:37 -0700 Subject: [PATCH 09/11] Update doc/source/installation.rst --- doc/source/installation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/installation.rst b/doc/source/installation.rst index 9122872d6..d876a53ed 100644 --- a/doc/source/installation.rst +++ b/doc/source/installation.rst @@ -288,7 +288,7 @@ This installation does not download all the datasets; instead, the datasets are .. _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/35d9d2e3ab08e7e6741b57fe02a7215fe3b91a6c/package/pyproject.toml#L69 +.. _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/ From 1184152f7ec1394bd776a2cce3fad10b2f0fbf32 Mon Sep 17 00:00:00 2001 From: Oliver Beckstein Date: Sat, 29 Mar 2025 02:02:53 -0700 Subject: [PATCH 10/11] Update doc/source/installation.rst --- doc/source/installation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/installation.rst b/doc/source/installation.rst index d876a53ed..1c1398934 100644 --- a/doc/source/installation.rst +++ b/doc/source/installation.rst @@ -153,7 +153,7 @@ To install the **latest stable release** from source: git clone https://github.com/MDAnalysis/mdanalysis cd mdanalysis - git checkout release- + git switch release- pip install . To run tests: From 21de04ad359af6bc86591bfdd8af3f2e81b1b99b Mon Sep 17 00:00:00 2001 From: Namir Oues Date: Mon, 31 Mar 2025 08:34:48 +0100 Subject: [PATCH 11/11] address PR review comments --- doc/source/installation.rst | 22 +++++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) diff --git a/doc/source/installation.rst b/doc/source/installation.rst index 1c1398934..a4ad505fe 100644 --- a/doc/source/installation.rst +++ b/doc/source/installation.rst @@ -144,17 +144,29 @@ Follow the steps in: MDAnalysis uses different Git branches for different purposes: -- **package-X.Y.Z**: These branches contain specific stable releases (e.g., ``package-2.9.0``) and are intended for users who need reproducibility, debugging, or version locking. You can browse them on the GitHub `Branches page`_ or view official releases on the `Releases page`_. -- **develop**: The `develop`_ branch is the default and active development branch. If you're contributing to MDAnalysis or want the latest features before they're released, base your work on this branch (see :ref:`development-installation`). +- **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`). -To install the **latest stable release** from source: +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 - git switch release- - pip install . + 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: