Make documentation and fix issues with self-distance array python l…

…ayer (#168) * progress * improve versioningit setup * add proper execution * start of examples * almost done * remove shape checking where not needed * remove _ver * changes to self distance array * fix matrix * add issue tracker link * improve rtd config * path * path again * improve further * lets try
MDAnalysis · Oct 13, 2024 · 6bfaaef · 6bfaaef
1 parent 8cf5dac
commit 6bfaaef
Show file tree

Hide file tree

Showing 14 changed files with 373 additions and 70 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,47 @@
+name: docs
+
+on:
+  push:
+    branches:
+    - main
+
+
+defaults:
+  run:
+    shell: bash -l {0}
+
+jobs:
+  pip-install-docs:
+    # A pure Python install, which relies purely on pyproject.toml contents
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        # for now windows pip install builds seem to fail for some reason
+        os: [ubuntu-latest]
+        python-version: ['3.10']
+
+    steps:
+    - uses: actions/checkout@v3
+      with:
+        submodules: recursive
+
+    - uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: check_env
+      run: |
+        which python
+        python -m pip list
+
+    - name: build
+      run: python -m pip install . -vvv
+
+    - name: make docs with mkdocs
+      run: |
+        python -m pip install docs/requirements.txt
+        cd docs
+        mkdocs build
+        mkdocs gh-deploy
+
diff --git a/.github/workflows/make_and_test.yml b/.github/workflows/make_and_test.yml
@@ -97,3 +97,4 @@ jobs:
     - name: python_test
       # run python API tests
       run: pytest distopia/tests
+
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -8,12 +8,17 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.12"
+    python: "mambaforge-22.9"
+
+conda:
+  environment: devtools/conda_envs/distopia_ubuntu-latest.yaml
 
 mkdocs:
   configuration: docs/mkdocs.yml
 
 # Optionally declare the Python requirements required to build your docs
 python:
   install:
+  - method: pip
+    path: .
   - requirements: docs/requirements.txt
diff --git a/distopia/__init__.py b/distopia/__init__.py
@@ -1,4 +1,3 @@
-from ._version import __version__
 
 from ._distopia import (
     calc_bonds_ortho,
@@ -34,5 +33,4 @@
     'calc_self_distance_array_no_box',
     'calc_self_distance_array_ortho',
     'calc_self_distance_array_triclinic',
-    '__version__',
 ]
diff --git a/distopia/_distopia.pyx b/distopia/_distopia.pyx
@@ -184,7 +184,7 @@ def calc_bonds_no_box(floating[:, ::1] coords0,
 
     Returns
     -------
-    distances : float32 or float64 array
+    distances : np.array
       same length and dtype as coords0/coords1
     """
     cdef floating[::1] results_view
@@ -229,7 +229,7 @@ def  calc_bonds_ortho(floating[:, ::1] coords0,
 
     Returns
     -------
-    distances : np array
+    distances : np.array
       same length and dtype as coords0/coords1
     """
     cdef floating[::1] results_view
@@ -276,7 +276,7 @@ def  calc_bonds_triclinic(floating[:, ::1] coords0,
 
     Returns
     -------
-    distances : np array
+    distances : np.array
       same length and dtype as coords0/coords1
     """
     cdef floating[::1] results_view
@@ -417,7 +417,7 @@ def calc_angles_triclinic(
     
     Returns
     -------
-    angles : np array
+    angles : np.array
         same length and dtype as coords0/coords1/coords2
     """
     cdef floating[::1] results_view
@@ -464,7 +464,7 @@ def calc_dihedrals_no_box(
     
     Returns
     -------
-    dihedrals : np array
+    dihedrals : np.array
       same length and dtype as coords0/coords1/coords2/coords3
     """
     cdef floating[::1] results_view
@@ -514,7 +514,7 @@ def calc_dihedrals_ortho(
     
     Returns
     -------
-    dihedrals : np array
+    dihedrals : np.array
       same length and dtype as coords0/coords1/coords2/coords3
     """
     cdef floating[::1] results_view
@@ -564,7 +564,7 @@ def calc_dihedrals_triclinic(
     
     Returns
     -------
-    dihedrals : np array
+    dihedrals : np.array
       same length and dtype as coords0/coords1/coords2/coords3
     """
     cdef floating[::1] results_view
@@ -610,7 +610,7 @@ def calc_distance_array_no_box(
     
     Returns
     -------
-    distances : np array
+    distances : np.array
       MxN array of distances
     """
 
@@ -621,7 +621,6 @@ def calc_distance_array_no_box(
 
     dims[0] = <ssize_t > nvals0 * nvals1
 
-    _check_shapes(coords0, coords1)
 
     if results is None:
         if floating is float:
@@ -661,7 +660,7 @@ def calc_distance_array_ortho(
     
     Returns
     -------
-    distances : np array
+    distances : np.array
       MxN array of distances
     """
     cdef floating[::1] results_view
@@ -671,7 +670,6 @@ def calc_distance_array_ortho(
 
     dims[0] = <ssize_t > nvals0 * nvals1
 
-    _check_shapes(coords0, coords1)
 
     if results is None:
         if floating is float:
@@ -712,7 +710,7 @@ def calc_distance_array_triclinic(
     
     Returns
     -------
-    distances : np array
+    distances : np.array
       MxN array of distances
     """
     cdef floating[::1] results_view
@@ -723,7 +721,7 @@ def calc_distance_array_triclinic(
 
     dims[0] = <ssize_t > nvals0 * nvals1
 
-    _check_shapes(coords0, coords1)
+
 
     if results is None:
         if floating is float:
@@ -751,28 +749,28 @@ def calc_distance_array_triclinic(
 def calc_self_distance_array_no_box(
      floating[:, ::1] coords0,
      floating[::1] results=None):
-    """Calculate pairwise distance matrix between coordinates under triclinic boundary conditions
+    """Calculate self-pairwise distance matrix between coordinates with no periodic boundary conditions
 
     Parameters
     ----------
-    coords0, coords1 : float32 or float64 array
+    coords0, float32 or float64 array
       must be same length and dtype
-    box : float32 or float64 array
-        periodic boundary dimensions, in 3x3 format
     results: float32 or float64 array (optional)
-        array to store results in, must be a single dimension of length MxN where M is the length of coords0 and N is the length of coords1
+        array to store results in, must be a single dimension of length N*(N-1)/2 where N is the length of coords0
     
     Returns
     -------
-    distances : np array
-      MxN array of distances
+    distances : np.array
+      N*(N-1)/2 array of distances, a flattened upper triangle of the full NxN matrix with the diagonal removed
     """
     cdef floating[::1] results_view
     cdef size_t nvals0 = coords0.shape[0]
 
     cdef cnp.npy_intp[1] dims
 
-    dims[0] = <ssize_t > nvals0 * nvals0
+    cdef ssize_t final_size = nvals0 * (nvals0 -1) // 2 
+
+    dims[0] = <ssize_t > final_size
 
 
     if results is None:
@@ -782,15 +780,15 @@ def calc_self_distance_array_no_box(
             results = cnp.PyArray_EMPTY(1, dims, cnp.NPY_FLOAT64, 0)
 
     else:
-        _check_results(results, nvals0)
+        _check_results(results, final_size)
 
     results_view = results
 
     CalcSelfDistanceArrayNoBox(&coords0[0][0],
                                nvals0,
                                &results_view[0])
 
-    return np.array(results).reshape(coords0.shape[0], coords0.shape[0])
+    return np.array(results)
 
 
 
@@ -801,29 +799,30 @@ def calc_self_distance_array_ortho(
      floating[:, ::1] coords0,
      floating[::1] box,
      floating[::1] results=None):
-    """Calculate pairwise distance matrix between coordinates under triclinic boundary conditions
+    """Calculate self-pairwise distance matrix between coordinates under orthorhombic periodic boundary conditions
 
     Parameters
     ----------
-    coords0, coords1 : float32 or float64 array
+    coords0: float32 or float64 array
       must be same length and dtype
     box : float32 or float64 array
         periodic boundary dimensions, in 3x3 format
     results: float32 or float64 array (optional)
-        array to store results in, must be a single dimension of length MxN where M is the length of coords0 and N is the length of coords1
+        array to store results in, must be a single dimension of length N*(N-1)/2 where N is the length of coords0
     
     Returns
     -------
-    distances : np array
-      MxN array of distances
+    distances : np.array
+      N*(N-1)/2 array of distances, a flattened upper triangle of the full NxN matrix with the diagonal removed
     """
     cdef floating[::1] results_view
     cdef size_t nvals0 = coords0.shape[0]
 
     cdef cnp.npy_intp[1] dims
 
-    dims[0] = <ssize_t > nvals0 * nvals0
+    cdef ssize_t final_size = nvals0 * (nvals0 -1) // 2 
 
+    dims[0] = <ssize_t > final_size
 
     if results is None:
         if floating is float:
@@ -832,7 +831,7 @@ def calc_self_distance_array_ortho(
             results = cnp.PyArray_EMPTY(1, dims, cnp.NPY_FLOAT64, 0)
 
     else:
-        _check_results(results, nvals0)
+        _check_results(results, final_size)
 
     results_view = results
 
@@ -841,7 +840,7 @@ def calc_self_distance_array_ortho(
                                &box[0],
                                &results_view[0])
 
-    return np.array(results).reshape(coords0.shape[0], coords0.shape[0])
+    return np.array(results)
 
 
 @cython.boundscheck(False)
@@ -850,7 +849,7 @@ def calc_self_distance_array_triclinic(
      floating[:, ::1] coords0,
      floating[:, ::1] box,
      floating[::1] results=None):
-    """Calculate pairwise distance matrix between coordinates under triclinic boundary conditions
+    """Calculate self-pairwise distance matrix between coordinates under triclinic boundary conditions
 
     Parameters
     ----------
@@ -859,19 +858,21 @@ def calc_self_distance_array_triclinic(
     box : float32 or float64 array
         periodic boundary dimensions, in 3x3 format
     results: float32 or float64 array (optional)
-        array to store results in, must be a single dimension of length MxN where M is the length of coords0 and N is the length of coords1
+        array to store results in, must be a single dimension of length NxN where M is the length of coords0
     
     Returns
     -------
-    distances : np array
-      MxN array of distances
+    distances : np.array
+      N*(N-1)/2 array of distances, a flattened upper triangle of the full NxN matrix with the diagonal removed
     """
     cdef floating[::1] results_view
     cdef size_t nvals0 = coords0.shape[0]
 
     cdef cnp.npy_intp[1] dims
 
-    dims[0] = <ssize_t > nvals0 * nvals0
+    cdef ssize_t final_size = nvals0 * (nvals0 -1) // 2 
+
+    dims[0] = <ssize_t > final_size
 
 
     if results is None:
@@ -881,7 +882,7 @@ def calc_self_distance_array_triclinic(
             results = cnp.PyArray_EMPTY(1, dims, cnp.NPY_FLOAT64, 0)
 
     else:
-        _check_results(results, nvals0)
+        _check_results(results, final_size)
 
     results_view = results
 
@@ -890,4 +891,4 @@ def calc_self_distance_array_triclinic(
                                &box[0][0],
                                &results_view[0])
 
-    return np.array(results).reshape(coords0.shape[0], coords0.shape[0])
+    return np.array(results)
diff --git a/distopia/_version.py b/distopia/_version.py
Original file line number	Diff line number	Diff line change
Expand Up		@@ -97,3 +97,4 @@ jobs:
		- name: python_test
		# run python API tests
		run: pytest distopia/tests