You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The latest versions of **MDAnalysis** can be installed using `conda` or `pip`.
8
-
Currently, the conda releases only support serial calculations.
9
-
If you plan to use the parallel OpenMP algorithms, you need to
10
-
install MDAnalysis with pip and have a working OpenMP installation.
7
+
The latest version of **MDAnalysis** can be installed using :ref:`mamba-installation` (recommended),
8
+
or :ref:`pip-installation`. If you need to install MDAnalysis from source, follow :ref:`source-installation`
9
+
for stable releases. If you are a contributor or developer working on MDAnalysis, follow the
10
+
:ref:`development-installation` for editable installation and code modifications.
11
11
12
-
MDAnalysis has a separate :ref:`test suite <mdanalysistests>` **MDAnalysisTests** that is required to run the test cases and examples.
13
-
The test files change less frequently, take up around 90 MB of space,
14
-
and are not needed for daily use of MDAnalysis. However, they are often used in examples,
15
-
including many in this User Guide. If you are not interested in developing
16
-
MDAnalysis or using the example files, you most likely don't need the tests. If you want to
17
-
run examples in the User Guide, install the tests.
18
-
The tests are distributed separately from the main package.
12
+
Currently, the :ref:`mamba-installation` installs a version of MDAnalysis that does **not** include `OpenMP`_
13
+
acceleration due to limitations in precompiled conda packages. If you need `OpenMP`_-enabled features,
14
+
consider installing via :ref:`pip-installation` and compiling from source with a compatible compiler and
15
+
OpenMP support.
16
+
17
+
**MDAnalysisTests** is optional and is a separate :ref:`test suite <mdanalysistests>` used
18
+
for verifying MDAnalysis installations and running User Guide examples. It is not required for
19
+
daily use, but some tutorials rely on it. The package is approximately 90 MB and is not updated frequently.
20
+
If you plan to use tutorial examples or contribute to MDAnalysis, installing it is recommended.
21
+
22
+
MDAnalysis supports specific Python versions. For the latest supported versions, please refer to the
23
+
`CHANGELOG`_ or the `PyPI`_. Ensure you have a compatible Python version installed before proceeding.
19
24
20
25
.. note::
26
+
MDAnalysis supports **Linux**, **macOS**, and **Windows**.
21
27
22
-
If you are installing on Windows, you must have
23
-
Microsoft Visual C++ 14.0 installed. If your installation
24
-
fails with the error message:
28
+
- 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`_.
29
+
- If you encounter any other issues following these instructions, seek help on `GitHub Discussions (Installation)`_.
25
30
26
-
error: Microsoft Visual C++ 14.0 is required. Get it with "Build Tools for Visual Studio": https://visualstudio.microsoft.com/downloads/
`Mambaforge`_ is a minimal `conda`_ distribution that includes `mamba`_ by default, uses the `conda-forge`_ channel
45
+
(preferred for MDAnalysis) and avoids clutter from `Anaconda`_ base packages.
40
46
41
-
If you use ``conda`` to manage your Python environment, we highly recommend creating a new environment for MDAnalysis.
42
-
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.
43
-
We further recommend that you install and use ``mamba``, a faster drop-in replacement for ``conda``.
47
+
To install MDAnalysis with `Mambaforge`_, follow the `mambaforge installation instructions`_ and then
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`_):
55
+
To install the :ref:`test suite <mdanalysistests>` (optional, ~90 MB):
52
56
53
57
.. code-block:: bash
54
58
55
-
mamba install -c conda-forge mdanalysis
59
+
mamba install -c conda-forge MDAnalysisTests
56
60
57
-
To upgrade:
61
+
To upgrade, use:
58
62
59
63
.. code-block:: bash
60
64
61
65
mamba update mdanalysis
62
66
63
-
To install the tests:
67
+
If you're using MDAnalysis in **JupyterLab**, install `ipywidgets`_ for progress bar support:
64
68
65
69
.. code-block:: bash
66
70
67
-
mamba install -c conda-forge MDAnalysisTests
71
+
mamba install -c conda-forge ipywidgets
72
+
73
+
**2. Alternative: Use conda with conda-forge**
68
74
69
-
If you intend to use MDAnalysis in JupyterLab, you will have to install
70
-
an extra package for the progress bar in analysis classes:
75
+
If you prefer using `conda`_ directly (e.g., installed via `Anaconda installer`_), create a new environment with packages from the `conda-forge`_ channel:
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.
91
+
===
92
+
93
+
The following command will install or upgrade the latest stable version of MDAnalysis via `pip`_ with core dependencies.
94
+
This means that some packages required by specific analysis modules will not be installed.
80
95
81
96
.. code-block:: bash
82
97
83
98
pip install --upgrade MDAnalysis
84
99
85
-
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`_.
100
+
MDAnalysis offers several optional dependency groups (“extra tags”) that you can install with pip to enable additional features:
101
+
102
+
- ``analysis``: optional dependencies for various analysis modules.
103
+
- ``extra_formats``: support for additional file formats.
104
+
- ``parallel``: install dask to enable parallel analysis across multiple cores or machines.
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.
129
+
Install from source
130
+
===================
131
+
132
+
This section is for **users** who want to install a **specific stable version** of MDAnalysis
133
+
(e.g., for reproducibility or to debug a release). This is **not** intended for development or code contributions.
134
+
If you're a developer, see :ref:`development-installation`.
135
+
136
+
To install from source, you must first ensure that your environment already contains all necessary dependencies.
137
+
We recommend you check the :ref:`create-virtual-environment` to set up a clean development environment
138
+
with all required dependencies. We recommend using `mamba`_ or `conda`_ to manage this setup.
139
+
140
+
Follow the steps in:
141
+
142
+
- `Set up with conda-forge`_
143
+
- `Set up with mamba`_
144
+
145
+
MDAnalysis uses different Git branches for different purposes:
146
+
147
+
- **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`_.
148
+
- **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`).
149
+
150
+
Clone the repository and check out the tag corresponding to the desired version:
# assuming you have already installed required dependencies
156
+
git checkout package-<version>
157
+
158
+
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.
159
+
If you plan to make changes, you can create a new branch based on the tag:
160
+
161
+
.. code-block:: bash
162
+
163
+
git switch -c my-fix-based-on-2.9.0
164
+
165
+
To install MDAnalysis from this version:
166
+
167
+
.. code-block:: bash
168
+
169
+
pip install package/.
170
+
171
+
To run tests:
172
+
173
+
.. code-block:: bash
174
+
175
+
pip install MDAnalysisTests
176
+
177
+
.. _development-installation:
178
+
179
+
Install for development
180
+
==========================
181
+
182
+
This section is for **contributors and developers** who want to modify MDAnalysis
183
+
or contribute to its development. You’ll install MDAnalysis in **editable mode**, which allows you to make code changes
184
+
without reinstalling the package each time.
185
+
186
+
Before installing, follow the steps described in the :ref:`source-installation` to set up a clean environment
187
+
with all dependencies.
188
+
189
+
Once your environment is ready, install MDAnalysis in editable mode:
All tests should pass (i.e. no FAIL, ERROR); SKIPPED or XFAIL are ok. If anything fails or gives an error,
134
-
`ask on GitHub Discussions<https://github.com/MDAnalysis/mdanalysis/discussions>`_ or `raise an issue<https://github.com/MDAnalysis/mdanalysis/issues>`_.
221
+
ask on `GitHub Discussions`_ or `raise an issue`_.
135
222
136
-
Testing MDAnalysis can take a while, as there are quite a few tests.
137
-
The plugin `pytest-xdist<https://github.com/pytest-dev/pytest-xdist>`_ can be used to run tests in parallel.
223
+
Running MDAnalysis tests can take some time, as there are many test cases.
224
+
The plugin `pytest-xdist`_ can be used to run tests in parallel.
138
225
139
226
.. code-block:: bash
140
227
@@ -148,7 +235,7 @@ You can pass any additional compiler flags for the C/C++ compiler using the ``ex
148
235
This allows you to add any additional compiler options required for your architecture.
149
236
150
237
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.
151
-
*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:
238
+
The optimal compiler flags depend on your CPU architecture. Commonly recommended settings are:
152
239
153
240
.. code-block:: diff
154
241
@@ -157,22 +244,24 @@ For example, ``extra_cflags`` can be used to tune your MDAnalysis installation f
157
244
158
245
Use of these flags can give a significant performance boost where the compiler can effectively autovectorise.
159
246
160
-
Be sure to use the recommended flags for your target architecture. For example, ARM platforms recommend using ``-mcpu`` *instead* of ``-mcpu``, while
161
-
PowerPC platforms prefer *both* ``-mcpu`` and ``-mtune``.
247
+
Be sure to use the recommended flags for your target architecture. In many cases,
248
+
``-march`` and ``-mcpu`` can be used together or separately, and their behavior depends
249
+
on your platform and compiler version. For example, ARM platforms often prefer ``-mcpu``,
250
+
while PowerPC may use both ``-mcpu`` and ``-mtune``. Refer to the `GCC documentation on -march`_
251
+
and `-mcpu`_ for platform-specific guidance.
162
252
163
-
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.
253
+
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.
164
254
165
255
.. warning::
166
-
Use of these compiler options is considered **advanced** and may reduce the binary compatibility of MDAnalysis significantly, especially if using `-march`,
167
-
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
168
-
before proceeding with analysis.
256
+
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.
257
+
We **strongly recommend** that you run the test suite on your intended platform before proceeding with analysis.
169
258
170
259
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.
171
260
172
261
Additional datasets
173
262
===================
174
263
175
-
MDAnalysisData_ is an additional package with datasets that can be used in example tutorials. You can install it with ``conda`` or ``pip``:
264
+
MDAnalysisData_ is an additional package with datasets that can be used in example tutorials. You can install it with `mamba`_ / `conda`_ or `pip`_:
176
265
177
266
.. code-block:: bash
178
267
@@ -183,9 +272,35 @@ MDAnalysisData_ is an additional package with datasets that can be used in examp
183
272
184
273
This installation does not download all the datasets; instead, the datasets are cached when they are first downloaded using a Python command.
0 commit comments