Add backends support for minimize_vectors

package/AUTHORS

@@ -271,6 +271,7 @@ Chronological list of authors
   - Mohammad Ayaan
   - Khushi Phougat
   - Kushagar Garg
+  - Pardhav Maradani
 
 External code
 -------------

package/CHANGELOG

@@ -15,7 +15,7 @@ The rules for this file:
 
 -------------------------------------------------------------------------------
 ??/??/?? IAlibay, orbeckst, marinegor, tylerjereddy, ljwoods2, marinegor,
-         spyke7, talagayev, tanii1125, BradyAJohnston
+         spyke7, talagayev, tanii1125, BradyAJohnston, PardhavMaradani
 
  * 2.11.0
 
@@ -37,6 +37,7 @@ Fixes
    DSSP by porting upstream PyDSSP 0.9.1 fix (Issue #4913)
 
 Enhancements
+ * Adds support for backend options in `minimize_vectors` (Issue #5234, PR #5235)
  * Adds support for parsing `.tpr` files produced by GROMACS 2026.0
  * Enables parallelization for analysis.diffusionmap.DistanceMatrix
    (Issue #4679, PR #4745)

package/MANIFEST.in

@@ -2,6 +2,7 @@ global-include *.pyx
 global-include *.pxd
 global-include *.c
 global-include *.h
+global-include *.hpp
 global-include *.cpp
 include MDAnalysis/lib/src/transformations/*
 recursive-include doc * 

package/MDAnalysis/lib/_distopia.py

@@ -190,3 +190,15 @@ def calc_self_distance_array_triclinic(
     coords: np.ndarray, box: np.ndarray, results: np.ndarray
 ) -> None:
     distopia.self_distance_array_triclinic(coords, box, results=results)
+
+
+def calc_minimize_vectors_ortho(
+    vectors: np.ndarray, box: np.ndarray, output: np.ndarray
+) -> None:
+    distopia.minimize_vectors_ortho(vectors, box[:3], output)
+
+
+def calc_minimize_vectors_triclinic(
+    vectors: np.ndarray, box: np.ndarray, output: np.ndarray
+) -> None:
+    distopia.minimize_vectors_triclinic(vectors, box, output)

package/MDAnalysis/lib/c_distances.pxd

@@ -1,3 +1,4 @@
+# distutils: language = c++
 from libc.stdint cimport uint64_t, UINT64_MAX
 
 
@@ -26,4 +27,8 @@ cdef extern from "calc_distances.h":
     void _ortho_pbc(coordinate* coords, uint64_t numcoords, float* box)
     void _triclinic_pbc(coordinate* coords, uint64_t numcoords, float* box)
     void minimum_image(double* x, float* box, float* inverse_box)
-    void minimum_image_triclinic(float* x, float* box, float* inverse_box)
+    void minimum_image_triclinic(float* x, float* box, float* inverse_box)
+
+cdef extern from "calc_distances.hpp":
+    void _calc_minimize_vectors_ortho[T](T* vectors, uint64_t numvectors, T* box, T* output)
+    void _calc_minimize_vectors_triclinic[T](T* vectors, uint64_t numvectors, T* box, T* output)

package/MDAnalysis/lib/c_distances.pyx

@@ -33,6 +33,7 @@ cimport cython
 from libc.stdint cimport uint64_t, UINT64_MAX
 import numpy
 cimport numpy
+from cython cimport floating
 numpy.import_array()
 
 from libc.math cimport round as cround
@@ -272,143 +273,19 @@ def contact_matrix_pbc(coord, sparse_contacts, box, cutoff):
 
 @cython.boundscheck(False)
 @cython.wraparound(False)
-cdef inline void _minimum_image_orthogonal(cython.floating[:] dx,
-                                           cython.floating[:] box,
-                                           cython.floating[:] inverse_box) nogil:
-    """Minimize dx to be the shortest vector
-
-    Parameters
-    ----------
-    dx : numpy.array, shape (3,)
-      vector to minimize
-    box : numpy.array, shape (3,)
-      box length in each dimension
-    inverse_box : numpy.array, shape (3,)
-      inverse of box
-
-    Operates in-place on dx!
-    """
-    cdef int i
-    cdef cython.floating s
-
-    for i in range(3):
-        if box[i] > 0:
-            s = inverse_box[i] * dx[i]
-            dx[i] = box[i] * (s - cround(s))
+def calc_minimize_vectors_ortho(
+    floating[:, ::1] vectors,
+    floating[::1] box,
+    floating[:, ::1] output) -> None:
+    cdef uint64_t numvectors = vectors.shape[0]
+    _calc_minimize_vectors_ortho(&vectors[0, 0], numvectors, &box[0], &output[0, 0])
 
 
 @cython.boundscheck(False)
 @cython.wraparound(False)
-cdef inline void _minimum_image_triclinic(cython.floating[:] dx,
-                                          cython.floating[:] box,
-                                          cython.floating[:] inverse_box) nogil:
-    """Minimise dx to be the shortest vector
-
-    Parameters
-    ----------
-    dx : numpy.array, shape (3,)
-      the vector to apply minimum image convention to
-    box : numpy.array, shape (9,)
-      flattened 3x3 representation of the unit cell
-    inverse_box : numpy.array, shape (3,)
-      inverse of the **diagonal** of the 3x3 representation
-
-    This version is near identical to the version in calc_distances.h, with the
-    difference being that this version does not assume that coordinates are at
-    most a single box length apart.
-
-    Operates in-place on dx!
-    """
-    cdef cython.floating dx_min[3]
-    cdef cython.floating s, dsq, dsq_min, rx
-    cdef cython.floating ry[2]
-    cdef cython.floating rz[3]
-    cdef int ix, iy, iz
-
-    # first make shift only 1 cell in any direction
-    s = cround(inverse_box[2] * dx[2])
-    dx[0] -= s * box[6]
-    dx[1] -= s * box[7]
-    dx[2] -= s * box[8]
-    s = cround(inverse_box[1] * dx[1])
-    dx[0] -= s * box[3]
-    dx[1] -= s * box[4]
-    s = cround(inverse_box[0] * dx[0])
-    dx[0] -= s * box[0]
-
-    if cython.floating is float:
-        dsq_min = FLT_MAX
-    else:
-        dsq_min = DBL_MAX
-    dx_min[0] = 0.0
-    dx_min[1] = 0.0
-    dx_min[2] = 0.0
-
-    # then check all images to see which combination of 1 cell shifts gives the best shift
-    for ix in range(-1, 2):
-        rx = dx[0] + box[0] * ix
-        for iy in range(-1, 2):
-            ry[0] = rx + box[3] * iy
-            ry[1] = dx[1] + box[4] * iy
-            for iz in range(-1, 2):
-                rz[0] = ry[0] + box[6] * iz
-                rz[1] = ry[1] + box[7] * iz
-                rz[2] = dx[2] + box[8] * iz
-                dsq = rz[0] * rz[0] + rz[1] * rz[1] + rz[2] * rz[2]
-                if (dsq < dsq_min):
-                    dsq_min = dsq
-                    dx_min[0] = rz[0]
-                    dx_min[1] = rz[1]
-                    dx_min[2] = rz[2]
-
-    dx[0] = dx_min[0]
-    dx[1] = dx_min[1]
-    dx[2] = dx_min[2]
-
-
-@cython.boundscheck(False)
-@cython.wraparound(False)
-@cython.cdivision(True)
-def _minimize_vectors_ortho(cython.floating[:, :] vectors not None, cython.floating[:] box not None,
-                            cython.floating[:, :] output not None):
-    cdef int i, n
-    cdef cython.floating box_inverse[3]
-    cdef cython.floating[:] box_inverse_view
-
-    box_inverse[0] = 1.0 / box[0]
-    box_inverse[1] = 1.0 / box[1]
-    box_inverse[2] = 1.0 / box[2]
-
-    box_inverse_view = box_inverse
-
-    n = len(vectors)
-    with nogil:
-        for i in range(n):
-            output[i, 0] = vectors[i, 0]
-            output[i, 1] = vectors[i, 1]
-            output[i, 2] = vectors[i, 2]
-            _minimum_image_orthogonal(output[i, :], box, box_inverse_view)
-
-
-@cython.boundscheck(False)
-@cython.wraparound(False)
-def _minimize_vectors_triclinic(cython.floating[:, :] vectors not None, cython.floating[:] box not None,
-                                cython.floating[:, :] output not None):
-    cdef int i, n
-    cdef cython.floating box_inverse[3]
-    cdef cython.floating[:] box_inverse_view
-
-    # this is only inverse of diagonal, used for initial shift to ensure vector is within a single shift away
-    box_inverse[0] = 1.0 / box[0]
-    box_inverse[1] = 1.0 / box[4]
-    box_inverse[2] = 1.0 / box[8]
-
-    box_inverse_view = box_inverse
-
-    n = len(vectors)
-    with nogil:
-        for i in range(n):
-            output[i, 0] = vectors[i, 0]
-            output[i, 1] = vectors[i, 1]
-            output[i, 2] = vectors[i, 2]
-            _minimum_image_triclinic(output[i, :], box, box_inverse_view)
+def calc_minimize_vectors_triclinic(
+    floating[:, ::1] vectors,
+    floating[:, ::1] box,
+    floating[:, ::1] output) -> None:
+    cdef uint64_t numvectors = vectors.shape[0]
+    _calc_minimize_vectors_triclinic(&vectors[0, 0], numvectors, &box[0][0], &output[0, 0])

package/MDAnalysis/lib/c_distances_openmp.pyx

@@ -21,6 +21,7 @@
 # J. Comput. Chem. 32 (2011), 2319--2327, doi:10.1002/jcc.21787
 #
 #
+# distutils: language = c++
 
 """
 Parallel distance calculation library --- :mod:`MDAnalysis.lib.c_distances_openmp`
@@ -30,9 +31,11 @@ Parallel distance calculation library --- :mod:`MDAnalysis.lib.c_distances_openm
 Contains OpenMP versions of the contents of "calc_distances.h"
 """
 
+cimport cython
 from libc.stdint cimport uint64_t
 import numpy
 cimport numpy
+from cython cimport floating
 numpy.import_array()
 
 cdef extern from "string.h":
@@ -60,6 +63,10 @@ cdef extern from "calc_distances.h":
     void _ortho_pbc(coordinate* coords, uint64_t numcoords, float* box)
     void _triclinic_pbc(coordinate* coords, uint64_t numcoords, float* box)
 
+cdef extern from "calc_distances.hpp":
+    void _calc_minimize_vectors_ortho[T](T* vectors, uint64_t numvectors, T* box, T* output)
+    void _calc_minimize_vectors_triclinic[T](T* vectors, uint64_t numvectors, T* box, T* output)
+
 
 OPENMP_ENABLED = True if USED_OPENMP else False
 
@@ -241,3 +248,23 @@ def triclinic_pbc(numpy.ndarray coords, numpy.ndarray box):
     numcoords = coords.shape[0]
 
     _triclinic_pbc(<coordinate*> coords.data, numcoords, <float*> box.data)
+
+
+@cython.boundscheck(False)
+@cython.wraparound(False)
+def calc_minimize_vectors_ortho(
+    floating[:, ::1] vectors,
+    floating[::1] box,
+    floating[:, ::1] output):
+    cdef uint64_t numvectors = vectors.shape[0]
+    _calc_minimize_vectors_ortho(&vectors[0, 0], numvectors, &box[0], &output[0, 0])
+
+
+@cython.boundscheck(False)
+@cython.wraparound(False)
+def calc_minimize_vectors_triclinic(
+    floating[:, ::1] vectors,
+    floating[:, ::1] box,
+    floating[:, ::1] output):
+    cdef uint64_t numvectors = vectors.shape[0]
+    _calc_minimize_vectors_triclinic(&vectors[0, 0], numvectors, &box[0][0], &output[0, 0])

package/MDAnalysis/lib/distances.py

@@ -151,7 +151,10 @@
 from .mdamath import triclinic_vectors
 from ._augment import augment_coordinates, undo_augment
 from .nsgrid import FastNS
-from .c_distances import _minimize_vectors_ortho, _minimize_vectors_triclinic
+from .c_distances import (
+    calc_minimize_vectors_ortho,
+    calc_minimize_vectors_triclinic,
+)
 from ._distopia import HAS_DISTOPIA
 
 
@@ -2103,7 +2106,11 @@ def apply_PBC(
 
 
 @check_coords("vectors", enforce_copy=False, enforce_dtype=False)
-def minimize_vectors(vectors: npt.NDArray, box: npt.NDArray) -> npt.NDArray:
+def minimize_vectors(
+    vectors: npt.NDArray,
+    box: npt.NDArray,
+    backend: str = "serial",
+) -> npt.NDArray:
     """Apply minimum image convention to an array of vectors
 
     This function is required for calculating the correct vectors between two
@@ -2121,6 +2128,8 @@ def minimize_vectors(vectors: npt.NDArray, box: npt.NDArray) -> npt.NDArray:
         triclinic and must be provided in the same format as returned by
         :attr:`MDAnalysis.coordinates.timestep.Timestep.dimensions`:
         ``[lx, ly, lz, alpha, beta, gamma]``.
+    backend : {'serial', 'OpenMP'}, optional
+        Keyword selecting the type of acceleration.
 
     Returns
     -------
@@ -2130,6 +2139,8 @@ def minimize_vectors(vectors: npt.NDArray, box: npt.NDArray) -> npt.NDArray:
 
 
     .. versionadded:: 2.1.0
+    .. versionchanged:: 2.11.0
+       Added *backend* keyword.
     """
     boxtype, box = check_box(box)
     output = np.empty_like(vectors)
@@ -2138,8 +2149,16 @@ def minimize_vectors(vectors: npt.NDArray, box: npt.NDArray) -> npt.NDArray:
     box = box.astype(vectors.dtype)
 
     if boxtype == "ortho":
-        _minimize_vectors_ortho(vectors, box, output)
+        _run(
+            "calc_minimize_vectors_ortho",
+            args=(vectors, box, output),
+            backend=backend,
+        )
     else:
-        _minimize_vectors_triclinic(vectors, box.ravel(), output)
+        _run(
+            "calc_minimize_vectors_triclinic",
+            args=(vectors, box, output),
+            backend=backend,
+        )
 
     return output