Repository: MDAnalysis/mdanalysis
Pull request #4970: update distopia docs
Author: login: orbeckst
Created: 2025-03-14T18:33:50Z | Merged: 2025-03-15T13:06:36Z


<!-- 
Insert issue number that this PR fixes (if any) just after 'Fixes #'.
If this PR does not fix an existing issue, consider opening one or remove 'Fixes #' from the PR description.
-->
Fixes n/a

Changes made in this Pull Request:
<!-- Describe the changes that this PR makes. If applicable, use the following bullet list. --> 
- document HAS_DISTOPIA
- small distopia docs updates
- add name to CHANGELOG


## PR Checklist
<!-- Please use the following checklist to ensure the PR is ready to be reviewed/merged. -->
 - [ ] Issue raised/referenced?
 - [ ] Tests updated/added?
 - [x] Documentation updated/added?
 - [x] `package/CHANGELOG` file updated?
 - [x] Is your name in `package/AUTHORS`? (If it is not, add it!)

## Developers Certificate of Origin
<!-- 
In order for this PR to be merged you **must certify that you are able to submit your code to be included in MDAnalysis**.
-->

I certify that I can submit this code contribution as described in the [**Developer Certificate of Origin**](https://developercertificate.org/), under the MDAnalysis [LICENSE](https://github.com/MDAnalysis/mdanalysis/blob/develop/LICENSE).


<!-- readthedocs-preview mdanalysis start -->
----
📚 Documentation preview 📚: https://mdanalysis--4970.org.readthedocs.build/en/4970/

<!-- readthedocs-preview mdanalysis end -->


Diff:
diff --git a/package/CHANGELOG b/package/CHANGELOG
index 776507d9ceb..5d15333ae67 100644
--- a/package/CHANGELOG
+++ b/package/CHANGELOG
@@ -14,7 +14,7 @@ The rules for this file:
 
 
 -------------------------------------------------------------------------------
-??/??/?? IAlibay
+??/??/?? IAlibay, orbeckst
 
 
  * 2.10.0
diff --git a/package/MDAnalysis/lib/distances.py b/package/MDAnalysis/lib/distances.py
index 5fa35ecc907..efa6f55c238 100644
--- a/package/MDAnalysis/lib/distances.py
+++ b/package/MDAnalysis/lib/distances.py
@@ -48,9 +48,12 @@
 
    "OpenMP"   :mod:`c_distances_openmp` parallel implementation in C/Cython
                                         with OpenMP
-   "distopia"  `_distopia`               SIMD-accelerated implementation
+
+   "distopia"  `_distopia`              SIMD-accelerated implementation
+                                        with the `distopia`_ library
    ========== ========================= ======================================
 
+
 Use of the distopia library
 ---------------------------
 
@@ -65,25 +68,27 @@
 .. table:: Functions available using the `distopia`_ backend.
    :align: center
 
-   +-----------------------------------------------+
-   | Functions                                     |
-   +===============================================+
-   | MDAnalysis.lib.distances.calc_bonds           |
-   +-----------------------------------------------+
-   | MDAnalysis.lib.distances.calc_angles          |
-   +-----------------------------------------------+
-   | MDAnalysis.lib.distances.calc_dihedrals       |
-   +-----------------------------------------------+
-   | MDAnalysis.lib.distances.distance_array       | 
-   +-----------------------------------------------+
-   | MDAnalysis.lib.distances.self_distance_array  |
-   +-----------------------------------------------+
+   +-------------------------------------------------------+
+   | Functions                                             |
+   +=======================================================+
+   | :func:`MDAnalysis.lib.distances.calc_bonds`           |
+   +-------------------------------------------------------+
+   | :func:`MDAnalysis.lib.distances.calc_angles`          |
+   +-------------------------------------------------------+
+   | :func:`MDAnalysis.lib.distances.calc_dihedrals`       |
+   +-------------------------------------------------------+
+   | :func:`MDAnalysis.lib.distances.distance_array`       |
+   +-------------------------------------------------------+
+   | :func:`MDAnalysis.lib.distances.self_distance_array`  |
+   +-------------------------------------------------------+
 
 If `distopia`_ is installed, the functions in this table will accept the key
-'distopia' for the `backend` keyword argument. If the distopia backend is
-selected the `distopia` library will be used to calculate the distances. Note
-that for functions listed in this table **distopia is not the default backend
-and must be selected.**
+'distopia' for the `backend` keyword argument. The variable
+:data:`HAS_DISTOPIA` is set to ``True`` if distopia is available.
+
+If the distopia backend is selected the `distopia` library will be used to
+calculate the distances. Note that for functions listed in this table
+**distopia is not the default backend and must be explicitly selected.**
 
 
 .. Note::
@@ -109,6 +114,14 @@
 .. versionchanged:: 2.9.0
    Distopia support greatly expanded (with distopia ≥ 0.4.0).
 
+Constants
+---------
+.. data:: HAS_DISTOPIA
+
+   This variable is ``True`` if the :mod:`distopia` package has been
+   installed and is available as a `backend`. Otherwise it is
+   ``False``.
+
 Functions
 ---------
 .. autofunction:: distance_array
@@ -124,6 +137,7 @@
 .. autofunction:: augment_coordinates(coordinates, box, r)
 .. autofunction:: undo_augment(results, translation, nreal)
 .. autofunction:: minimize_vectors(vectors, box)
+
 """
 import numpy as np
 import numpy.typing as npt


Reviews:
user: login: RMeli
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-03-14T21:42:12Z
user: login: orbeckst
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-03-14T21:53:07Z
user: login: RMeli
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-03-14T22:43:32Z
user: login: hmacdope
state: APPROVED
author_association: MEMBER
submitted_at: 2025-03-15T09:15:52Z
user: login: RMeli
state: APPROVED
author_association: MEMBER
submitted_at: 2025-03-15T13:06:16Z

Review comments:
diff_hunk: @@ -48,9 +48,12 @@
 
    "OpenMP"   :mod:`c_distances_openmp` parallel implementation in C/Cython
                                         with OpenMP
-   "distopia"  `_distopia`               SIMD-accelerated implementation
+
+   "distopia"  `_distopia`              SIMD-accelerated implementation
+                                        with the distopia_ library
path: package/MDAnalysis/lib/distances.py
user: login: RMeli
body: ```suggestion
                                        with the `distopia`_ library
```
?
created_at: 2025-03-14T21:40:55Z
author_association: MEMBER
diff_hunk: @@ -48,9 +48,12 @@
 
    "OpenMP"   :mod:`c_distances_openmp` parallel implementation in C/Cython
                                         with OpenMP
-   "distopia"  `_distopia`               SIMD-accelerated implementation
+
+   "distopia"  `_distopia`              SIMD-accelerated implementation
+                                        with the distopia_ library
path: package/MDAnalysis/lib/distances.py
user: login: orbeckst
body: Both work but yours is more explicit 👍 – thx
created_at: 2025-03-14T21:53:07Z
author_association: MEMBER
diff_hunk: @@ -48,9 +48,12 @@
 
    "OpenMP"   :mod:`c_distances_openmp` parallel implementation in C/Cython
                                         with OpenMP
-   "distopia"  `_distopia`               SIMD-accelerated implementation
+
+   "distopia"  `_distopia`              SIMD-accelerated implementation
+                                        with the distopia_ library
path: package/MDAnalysis/lib/distances.py
user: login: RMeli
body: TIL
created_at: 2025-03-14T22:43:32Z
author_association: MEMBER

PR comments:
user: login: orbeckst
created_at: 2025-03-14T18:34:21Z
body: Haven't checked the doc build locally, sorry, ran out of time.
author_association: MEMBER
user: login: codecov[bot]
created_at: 2025-03-14T18:44:14Z
body: ## [Codecov](https://app.codecov.io/gh/MDAnalysis/mdanalysis/pull/4970?dropdown=coverage&src=pr&el=h1&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=MDAnalysis) Report
All modified and coverable lines are covered by tests :white_check_mark:
> Project coverage is 93.40%. Comparing base [(`9d072d9`)](https://app.codecov.io/gh/MDAnalysis/mdanalysis/commit/9d072d9485fa4b438de5539c8f60d4b07eca6ba9?dropdown=coverage&el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=MDAnalysis) to head [(`0a93ca0`)](https://app.codecov.io/gh/MDAnalysis/mdanalysis/commit/0a93ca02bf43b864f189d49348538f73e47e75f2?dropdown=coverage&el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=MDAnalysis).
> Report is 21 commits behind head on develop.

<details><summary>Additional details and impacted files</summary>


```diff
@@             Coverage Diff             @@
##           develop    #4970      +/-   ##
===========================================
- Coverage    93.42%   93.40%   -0.02%     
===========================================
  Files          177      189      +12     
  Lines        21859    22925    +1066     
  Branches      3078     3078              
===========================================
+ Hits         20422    21414     +992     
- Misses         986     1059      +73     
- Partials       451      452       +1     
```

</details>

[:umbrella: View full report in Codecov by Sentry](https://app.codecov.io/gh/MDAnalysis/mdanalysis/pull/4970?dropdown=coverage&src=pr&el=continue&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=MDAnalysis).   
:loudspeaker: Have feedback on the report? [Share it here](https://about.codecov.io/codecov-pr-comment-feedback/?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=MDAnalysis).

<details><summary> :rocket: New features to boost your workflow: </summary>

- :snowflake: [Test Analytics](https://docs.codecov.com/docs/test-analytics): Detect flaky tests, report on failures, and find test suite problems.
</details>
author_association: NONE
user: login: orbeckst
created_at: 2025-03-14T21:11:17Z
body: Renders ok on RTD.
author_association: MEMBER
user: login: orbeckst
created_at: 2025-03-14T23:40:12Z
body: @RMeli may I please assign you as PR shepherd? (If you don't have the bandwidth please un-assign yourself.) Thanks!
author_association: MEMBER