Documentation and CLI for backend selection

CHANGELOG.md

@@ -10,30 +10,25 @@ Contributors:    @RMeli, @takluyver, @Jnelen
 
 ### Added
 
+* Functionality to manually select the backend from CLI [PR #108 | @RMeli]
 * Functionality to manually select the backend [PR  #107 | @Jnelen]
+* Python `3.12` to CI [PR  #102 | @RMeli]
+* macOS M1 (`macoOS-14`) to CI [PR  #102 | @RMeli]
 
 ### Changed
 
-* Molecular graphs are now cached per backend using a dictionary [PR  #107 | @Jnelen]
+* Molecular graphs cache to cache by backend [PR  #107 | @Jnelen]
+* Python build system to use flit_core directly [PR #103 | @takluyver]
+* Minimum version of Python to `3.9` (to reduce CI matrix) [PR  #102 | @RMeli]
 
 ### Fixed
 
 * Failing tests with `pytest=8.0.0` [PR #101 | @RMeli]
 
-### Changed
-
-* Updated Python build system to use flit_core directly [PR #103 | @takluyver]
-* Minimum version of Python to `3.9` (to reduce CI matrix) [PR  #102 | @RMeli]
-
 ### Improved
 
 * Messages for `NotImplementedError` exceptions [PR #90 | @RMeli]
 
-### Added
-
-* Python `3.12` to CI [PR  #102 | @RMeli]
-* macOS M1 (`macoOS-14`) to CI [PR  #102 | @RMeli]
-
 ### Removed
 
 * `.gitattributes` and `.lgtm.yaml` stale files

README.md

@@ -159,6 +159,25 @@ def symmrmsd(
 > [!NOTE]
 > Atomic properties (`aprops`) can be any Python object when using [NetworkX](https://networkx.github.io/), or integers, floats, or strings when using [graph-tool](https://graph-tool.skewed.de/).
 
+#### Select Backend
+
+`spyrmsd` supports both [NetworkX](https://networkx.github.io/) and [graph-tool](https://graph-tool.skewed.de/) for the calculation of graph isomorphisms. You can check which backend is being used with
+
+```python
+spyrmsd.get_backend()
+```
+
+You can also manually select your preferred backend with
+
+```python
+spyrmsd.set_backend("networkx")
+# spyrmsd uses NetworkX
+spyrmsd.set_backend("graph_tool")
+# spyrmsd uses graph_tool
+```
+
+The available backends (which depend on the installed dependencies) are stored in `spyrmsd.available_backends`.
+
 ## Development
 
 To ensure code quality and consistency the following tools are used during development:

docs/source/tutorials/tutorial.ipynb

@@ -14,6 +14,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "import spyrmsd\n",
     "from spyrmsd import io, rmsd"
    ]
   },
@@ -107,8 +108,8 @@
      "output_type": "stream",
      "text": [
       "<frozen importlib._bootstrap>:241: RuntimeWarning: to-Python converter for std::__1::pair<double, double> already registered; second conversion method ignored.\n",
-      "[18:44:03] Molecule does not have explicit Hs. Consider calling AddHs()\n",
-      "[18:44:03] Molecule does not have explicit Hs. Consider calling AddHs()\n"
+      "[21:58:01] Molecule does not have explicit Hs. Consider calling AddHs()\n",
+      "[21:58:01] Molecule does not have explicit Hs. Consider calling AddHs()\n"
      ]
     },
     {
@@ -289,6 +290,102 @@
     "\n",
     "print(RMSD)"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Change Backend"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "`spyrmsd` supports multiple backends. You see which backends are available by looking at the `available_backends` attribute:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 11,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "['graph_tool', 'networkx']"
+      ]
+     },
+     "execution_count": 11,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "spyrmsd.available_backends"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The available backends are a subset of the supported backends. Only the backends that are installed will be available."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "You can check the current backend with"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 12,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "'graph_tool'"
+      ]
+     },
+     "execution_count": 12,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "spyrmsd.get_backend()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "You can switch the backend using"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 13,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "'networkx'"
+      ]
+     },
+     "execution_count": 13,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "spyrmsd.set_backend(\"networkx\")\n",
+    "spyrmsd.get_backend()"
+   ]
   }
  ],
  "metadata": {
@@ -307,7 +404,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.4"
+   "version": "3.11.8"
   }
  },
  "nbformat": 4,

docs/source/tutorials/tutorial.rst

@@ -3,6 +3,7 @@ Tutorial
 
 .. code:: ipython3
 
+    import spyrmsd
     from spyrmsd import io, rmsd
 
 OpenBabel or RDKit
@@ -68,8 +69,8 @@ constructors.
 .. parsed-literal::
 
     <frozen importlib._bootstrap>:241: RuntimeWarning: to-Python converter for std::__1::pair<double, double> already registered; second conversion method ignored.
-    [18:44:03] Molecule does not have explicit Hs. Consider calling AddHs()
-    [18:44:03] Molecule does not have explicit Hs. Consider calling AddHs()
+    [21:58:01] Molecule does not have explicit Hs. Consider calling AddHs()
+    [21:58:01] Molecule does not have explicit Hs. Consider calling AddHs()
 
 
 
@@ -95,7 +96,7 @@ Hydrogen atoms can be removed with the ``strip()`` function:
         mol.strip()
 
 Symmetry-Corrected RMSD
------------------------
+~~~~~~~~~~~~~~~~~~~~~~~
 
 ``spyrmsd`` only needs atomic coordinates, atomic number and the
 molecular adjacency matrix to compute the standard RMSD with
@@ -137,7 +138,7 @@ reference molecule and all other molecules:
 
 
 Minimum RMSD
-~~~~~~~~~~~~
+------------
 
 We can also compute the minimum RMSD obtained by superimposing the
 molecular structures:
@@ -160,3 +161,56 @@ molecular structures:
 .. parsed-literal::
 
     [1.2012368667355435, 1.0533413220699535, 1.153253104575529, 1.036542688936588, 0.8407673221224187, 1.1758143217869736, 0.7817315189656655, 1.0933314311267845, 1.0260767175206462, 0.9586369647000478]
+
+
+
+Change Backend
+~~~~~~~~~~~~~~
+
+``spyrmsd`` supports multiple backends. You see which backends are
+available by looking at the ``available_backends`` attribute:
+
+.. code:: ipython3
+
+    spyrmsd.available_backends
+
+
+
+
+.. parsed-literal::
+
+    ['graph_tool', 'networkx']
+
+
+
+The available backends are a subset of the supported backends. Only the
+backends that are installed will be available.
+
+You can check the current backend with
+
+.. code:: ipython3
+
+    spyrmsd.get_backend()
+
+
+
+
+.. parsed-literal::
+
+    'graph_tool'
+
+
+
+You can switch the backend using
+
+.. code:: ipython3
+
+    spyrmsd.set_backend("networkx")
+    spyrmsd.get_backend()
+
+
+
+
+.. parsed-literal::
+
+    'networkx'

spyrmsd/__main__.py

@@ -6,7 +6,9 @@
     import argparse as ap
     import importlib.util
     import sys
+    import warnings
 
+    import spyrmsd
     from spyrmsd import io
     from spyrmsd.rmsd import rmsdwrapper
 
@@ -25,6 +27,13 @@
     parser.add_argument(
         "-n", "--nosymm", action="store_false", help="No graph isomorphism"
     )
+    parser.add_argument(
+        "-g",
+        "--graph-backend",
+        type=str,
+        default=None,
+        help="Graph library (backend)",
+    )
 
     args = parser.parse_args()
 
@@ -49,6 +58,11 @@
         print("ERROR: Molecule file(s) not found.", file=sys.stderr)
         exit(-1)
 
+    if args.graph_backend is not None:
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            spyrmsd.set_backend(args.graph_backend)
+
     # Loop over molecules within fil
     RMSDlist = rmsdwrapper(
         ref,