geodesic-interpolate 1.0.0__tar.gz

geodesic_interpolate-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Xiaolei Zhu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

geodesic_interpolate-1.0.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include README.md
+include LICENSE

geodesic_interpolate-1.0.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: geodesic_interpolate
+Version: 1.0.0
+Summary: Interpolation and smoothing of reaction paths with geodesics in redundant internal coordinates.
+Home-page: https://github.com/virtualzx-nad/geodesic-interpolate
+Author: Xiaolei Zhu
+Author-email: virtualzx@gmail.com
+License: MIT
+Project-URL: Bug Reports, https://github.com/virtualzx-nad/geodesic-interpolate/issues
+Project-URL: Source, https://github.com/virtualzx-nad/geodesic-interpolate
+Keywords: chemistry,molecular dynamics,reaction paths,geodesics
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.13
+Requires-Dist: scipy>=0.19
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+Geodesic interpolations of reaction pathways
+====
+Constructing interpolation paths between molecular geometries to obtain reaction path.
+
+Traditional interpolation methods encounter difficulty when it comes to redundant internal coordinate spaces, because the feasible physical space compose only a very small and highly curved subspace.  In this method, we avoid the problem of feasibility by operating strictly in feasible space, and bring in the benefit of internal coordinates through proper application of the corresponding metric tensor.  With this new formulation, we view the configuration space as a Riemannian manifold with a metric generated from a set of internal coordinates. The interpolation paths are defined as geodesic curves on such manifolds.  In other words the integrated total coordinate change is minimized. Such a definition ensures that the constructed paths are smooth and well behaved. The package is also used for smoothing discontinuous or noisy trajectories obtained from MD simulations.
+
+It has been shown that the method generate smooth paths with reasonable barrier height even for highly complex reactions, such as protein unfolding or concerted cycloaddition reactions with many simutaneous ring formations.   The default coordinate system uses Morse scaled pair-wise distances.  The lengths in such coordinate systems have the physical meaning of the total number of bond changes along the path.
+
+This is a pure python implementation, so it is not optimized for speed, but rather is intended to serve as a reference implementation of the algorithms described in the paper.  Still, interpolating systems with ~1000 atoms should not be a problem.
+
+
+Directory Structure
+----
+- geodesic_interpolate      Python package for interpolation and smoothing by finding geodesic curves with redundant internal metrics
+  - `__init__.py`      Python package file
+  - `__main__.py`      Standalone script for performing interpolation and smoothings.
+  - `geodesic.py`      Computation and minimization of path length in redundant internal metrics.  This is used to optimize
+   a path way to find a geodesic.  Cannot change the number of images during optimization
+  - `interpolation.py` Generating approximate interpolation points to be used as starting guess for the geodesic optimizations.
+   Recursively attempt to perform bisections on largest segment in internal space.  Generally will create path
+   with discontinuities, so a smoothing process need to follow this.
+  - `coord_utils.py`   Coordinate utilities.  A simplified version of Nanoreactor coordinates module which provide a scaled
+   interatomic distance coordinate, pair screening based on threshold and connectivity, as well as trans-rotational
+   alignment based on Kabsch algorithm.
+  - `fileio.py`        XYZ file reading and writing
+- setup.py             Installation script.  This will install both the Python package, which can be imported by name `geodesic_interpolate`
+   and the standalone script, which is also named `geodesic_interpolate`
+- test_cases           A few test cases used to check the performance of the code.  Note that the large ones may take a few minutes
+   thanks to Python.  Especially need to run them when testing out alternative coordinate scaling methods.
+  - `H+CH4_CH3+H2.xyz` A simple test case.  Should always work
+  - `DielsAlder.xyz`   Dehydro-Diels-Alder reaction.  This is an important test case because the initial structure is planar symmetric and
+   could access both the final structure and its mirror image, which as exactly the same internal coordinates.  Proper
+   monitoring of geodesic length during the interpolation process is therefore crucial for this to work, without which
+   the raw interpolated path will jump between mirror images and the optimized path would contain some flopping.
+   Also tests the non-sweeping global path optimization algo in a relatively large system.
+  - `TrpCage_unfold.xyz` Unfolding a Trp-cage mini-protein.  Need at least 10 images to work.  Folded geometry taken from Stefan''s test
+   directory which is instead taken from Nathan.  Unfolded structure is generated by force navigated MD for 1ns under
+   1nN on C and N terminal with ReaxFF, then optimizing without force at 6-31g/b3lyp level.  For testing many
+   simultaneous large amplitude motions.
+  - `collagen.xyz`     Interpolate between the solution and crystal structure of collagen Kunitz domain 1kun - 1kth.  Solvents removed
+   from the PDB structures.  Tests collision avoidance for large movements in the core of folded protein.  Other
+   groups should slightly breath to create room for the part that changes.
+  - `calcium_binding.xyz`  Binding two Ca2+ ions to the yeast Calmodulin N terminal domain 1f54 -1f55.  The apo structure did not have
+   ions so two of which were added by hand at random locations away from the protein.  It seem to be hard to avoid
+   large movements of the Ca2+ cations when they are very far away from the protein but once in contact they should
+   move smoothly.  This is to test if the interpolater can correctly route and find the entry point and connect the
+   path.
+
+
+Prerequisites
+----
+
+Python :  >=3.8
+
+Numpy  :  Tested with 1.13
+
+Scipy  :  Tested with 0.19
+
+
+Installation
+----
+
+### From PyPI
+
+Once a release has been published to PyPI, install the package with:
+
+    pip install geodesic_interpolate
+
+### From Source
+
+The package can be used without installation from the package directory with
+
+    python -m geodesic_interpolate filename ...
+
+To use the script from an arbitrary location or import the Python module, install the package with pip:
+
+    python -m pip install .
+
+This will install a Python package `geodesic_interpolate` and a standalone script `geodesic_interpolate`.
+The package can be invoked from an arbitrary location using the aforementioned command line after installation,
+and a standalone script with the same signature can also be used
+
+    geodesic_interpolate filename.xyz --output output.xyz --nimages 20 ...
+
+
+Usage
+----
+usage: geodesic_interpolate [-h] [--nimages NIMAGES] [--sweep] [--no-sweep]
+                            [--output OUTPUT] [--tol TOL] [--maxiter MAXITER]
+                            [--microiter MICROITER] [--scaling SCALING]
+                            [--friction FRICTION] [--dist-cutoff DIST_CUTOFF]
+                            [--logging {DEBUG,INFO,WARNING,ERROR}]
+                            [--save-raw SAVE_RAW]
+                            filename
+
+Interpolates between two geometries
+
+positional arguments:
+  * filename            XYZ file containing geometries. If the number of images is smaller than the desired number,
+   interpolation points will be added. If the number is greater, subsampling will be performed.
+
+optional arguments:
+  * `-h`, `--help`      show this help message and exit
+  * `--nimages NIMAGES` Number of images. (default: 17)
+  * `--sweep`           Sweep across the path optimizing one image at a time, instead of moving all images at the same time.
+   Default is to perform sweeping updates if there are more than 30 atoms. (default: None)
+  * `--no-sweep`        Do not perform sweeping. (default: None)
+  * `--output OUTPUT`   Output filename. Default is interp.xyz (default: interpolated.xyz)
+  * `--tol TOL`         Convergence tolerance (default: 0.002)
+  * `--maxiter MAXITER` Maximum number of minimization iterations (default: 15)
+  * `--microiter MICROITER`  Maximum number of micro iterations for sweeping algorithm. (default: 20)
+  * `--scaling SCALING` Exponential parameter for morse potential (default: 1.7)
+  * `--friction FRICTION`   Size of friction term used to prevent very large change of geometry. (default: 0.01)
+  * `--dist-cutoff DIST_CUTOFF` Cut-off value for the distance between a pair of atoms to be included in the coordinate system. (default: 3)
+  * `--logging {DEBUG,INFO,WARNING,ERROR}`   Logging level to adopt [ DEBUG | INFO | WARNING | ERROR ] (default: INFO)
+  * `--save-raw SAVE_RAW`   When specified, save the raw path after bisections be before smoothing. (default: None)

geodesic_interpolate-1.0.0/README.md

@@ -0,0 +1,116 @@
+Geodesic interpolations of reaction pathways
+====
+Constructing interpolation paths between molecular geometries to obtain reaction path.
+
+Traditional interpolation methods encounter difficulty when it comes to redundant internal coordinate spaces, because the feasible physical space compose only a very small and highly curved subspace.  In this method, we avoid the problem of feasibility by operating strictly in feasible space, and bring in the benefit of internal coordinates through proper application of the corresponding metric tensor.  With this new formulation, we view the configuration space as a Riemannian manifold with a metric generated from a set of internal coordinates. The interpolation paths are defined as geodesic curves on such manifolds.  In other words the integrated total coordinate change is minimized. Such a definition ensures that the constructed paths are smooth and well behaved. The package is also used for smoothing discontinuous or noisy trajectories obtained from MD simulations.
+
+It has been shown that the method generate smooth paths with reasonable barrier height even for highly complex reactions, such as protein unfolding or concerted cycloaddition reactions with many simutaneous ring formations.   The default coordinate system uses Morse scaled pair-wise distances.  The lengths in such coordinate systems have the physical meaning of the total number of bond changes along the path.
+
+This is a pure python implementation, so it is not optimized for speed, but rather is intended to serve as a reference implementation of the algorithms described in the paper.  Still, interpolating systems with ~1000 atoms should not be a problem.
+
+
+Directory Structure
+----
+- geodesic_interpolate      Python package for interpolation and smoothing by finding geodesic curves with redundant internal metrics
+  - `__init__.py`      Python package file
+  - `__main__.py`      Standalone script for performing interpolation and smoothings.
+  - `geodesic.py`      Computation and minimization of path length in redundant internal metrics.  This is used to optimize
+   a path way to find a geodesic.  Cannot change the number of images during optimization
+  - `interpolation.py` Generating approximate interpolation points to be used as starting guess for the geodesic optimizations.
+   Recursively attempt to perform bisections on largest segment in internal space.  Generally will create path
+   with discontinuities, so a smoothing process need to follow this.
+  - `coord_utils.py`   Coordinate utilities.  A simplified version of Nanoreactor coordinates module which provide a scaled
+   interatomic distance coordinate, pair screening based on threshold and connectivity, as well as trans-rotational
+   alignment based on Kabsch algorithm.
+  - `fileio.py`        XYZ file reading and writing
+- setup.py             Installation script.  This will install both the Python package, which can be imported by name `geodesic_interpolate`
+   and the standalone script, which is also named `geodesic_interpolate`
+- test_cases           A few test cases used to check the performance of the code.  Note that the large ones may take a few minutes
+   thanks to Python.  Especially need to run them when testing out alternative coordinate scaling methods.
+  - `H+CH4_CH3+H2.xyz` A simple test case.  Should always work
+  - `DielsAlder.xyz`   Dehydro-Diels-Alder reaction.  This is an important test case because the initial structure is planar symmetric and
+   could access both the final structure and its mirror image, which as exactly the same internal coordinates.  Proper
+   monitoring of geodesic length during the interpolation process is therefore crucial for this to work, without which
+   the raw interpolated path will jump between mirror images and the optimized path would contain some flopping.
+   Also tests the non-sweeping global path optimization algo in a relatively large system.
+  - `TrpCage_unfold.xyz` Unfolding a Trp-cage mini-protein.  Need at least 10 images to work.  Folded geometry taken from Stefan''s test
+   directory which is instead taken from Nathan.  Unfolded structure is generated by force navigated MD for 1ns under
+   1nN on C and N terminal with ReaxFF, then optimizing without force at 6-31g/b3lyp level.  For testing many
+   simultaneous large amplitude motions.
+  - `collagen.xyz`     Interpolate between the solution and crystal structure of collagen Kunitz domain 1kun - 1kth.  Solvents removed
+   from the PDB structures.  Tests collision avoidance for large movements in the core of folded protein.  Other
+   groups should slightly breath to create room for the part that changes.
+  - `calcium_binding.xyz`  Binding two Ca2+ ions to the yeast Calmodulin N terminal domain 1f54 -1f55.  The apo structure did not have
+   ions so two of which were added by hand at random locations away from the protein.  It seem to be hard to avoid
+   large movements of the Ca2+ cations when they are very far away from the protein but once in contact they should
+   move smoothly.  This is to test if the interpolater can correctly route and find the entry point and connect the
+   path.
+
+
+Prerequisites
+----
+
+Python :  >=3.8
+
+Numpy  :  Tested with 1.13
+
+Scipy  :  Tested with 0.19
+
+
+Installation
+----
+
+### From PyPI
+
+Once a release has been published to PyPI, install the package with:
+
+    pip install geodesic_interpolate
+
+### From Source
+
+The package can be used without installation from the package directory with
+
+    python -m geodesic_interpolate filename ...
+
+To use the script from an arbitrary location or import the Python module, install the package with pip:
+
+    python -m pip install .
+
+This will install a Python package `geodesic_interpolate` and a standalone script `geodesic_interpolate`.
+The package can be invoked from an arbitrary location using the aforementioned command line after installation,
+and a standalone script with the same signature can also be used
+
+    geodesic_interpolate filename.xyz --output output.xyz --nimages 20 ...
+
+
+Usage
+----
+usage: geodesic_interpolate [-h] [--nimages NIMAGES] [--sweep] [--no-sweep]
+                            [--output OUTPUT] [--tol TOL] [--maxiter MAXITER]
+                            [--microiter MICROITER] [--scaling SCALING]
+                            [--friction FRICTION] [--dist-cutoff DIST_CUTOFF]
+                            [--logging {DEBUG,INFO,WARNING,ERROR}]
+                            [--save-raw SAVE_RAW]
+                            filename
+
+Interpolates between two geometries
+
+positional arguments:
+  * filename            XYZ file containing geometries. If the number of images is smaller than the desired number,
+   interpolation points will be added. If the number is greater, subsampling will be performed.
+
+optional arguments:
+  * `-h`, `--help`      show this help message and exit
+  * `--nimages NIMAGES` Number of images. (default: 17)
+  * `--sweep`           Sweep across the path optimizing one image at a time, instead of moving all images at the same time.
+   Default is to perform sweeping updates if there are more than 30 atoms. (default: None)
+  * `--no-sweep`        Do not perform sweeping. (default: None)
+  * `--output OUTPUT`   Output filename. Default is interp.xyz (default: interpolated.xyz)
+  * `--tol TOL`         Convergence tolerance (default: 0.002)
+  * `--maxiter MAXITER` Maximum number of minimization iterations (default: 15)
+  * `--microiter MICROITER`  Maximum number of micro iterations for sweeping algorithm. (default: 20)
+  * `--scaling SCALING` Exponential parameter for morse potential (default: 1.7)
+  * `--friction FRICTION`   Size of friction term used to prevent very large change of geometry. (default: 0.01)
+  * `--dist-cutoff DIST_CUTOFF` Cut-off value for the distance between a pair of atoms to be included in the coordinate system. (default: 3)
+  * `--logging {DEBUG,INFO,WARNING,ERROR}`   Logging level to adopt [ DEBUG | INFO | WARNING | ERROR ] (default: INFO)
+  * `--save-raw SAVE_RAW`   When specified, save the raw path after bisections be before smoothing. (default: None)

geodesic_interpolate-1.0.0/geodesic_interpolate/__init__.py

@@ -0,0 +1,2 @@
+from .geodesic import Geodesic
+from .interpolation import redistribute

geodesic_interpolate-1.0.0/geodesic_interpolate/__main__.py

@@ -0,0 +1,86 @@
+"""Performing geodesic interpolation or smoothing.
+Optimize reaction path using geometric information by minimizing path length with metrics defined by
+redundant internal coordinates.   Avoids the discontinuity and convergence problems of conventional
+interpolation methods by incorporating internal coordinate structure while operating in Cartesian,
+avoiding unfeasibility.
+
+Xiaolei Zhu et al, Martinez Group, Stanford University
+"""
+import logging
+import argparse
+
+import numpy as np
+
+from .fileio import read_xyz, write_xyz
+from .interpolation import redistribute
+from .geodesic import Geodesic
+
+
+logger = logging.getLogger(__name__)
+
+
+def main():
+    """Main entry point of the geodesic interpolation package.
+    Parse command line arguments then activate the interpolators and smoothers."""
+    ps = argparse.ArgumentParser(description="Interpolates between two geometries",
+                                 formatter_class=argparse.ArgumentDefaultsHelpFormatter)
+    ps.add_argument("filename", type=str, help="XYZ file containing geometries. If the number of images "
+                    "is smaller than the desired number, interpolation points will be added.  If the "
+                    "number is greater, subsampling will be performed.")
+    ps.add_argument("--nimages", type=int, default=17, help="Number of images.")
+    ps.add_argument("--sweep", action="store_true", help="Sweep across the path optimizing one image at "
+                    "a time, instead of moving all images at the same time.  Default is to perform sweeping "
+                    "updates if there are more than 30 atoms.")
+    ps.add_argument("--no-sweep", dest='sweep', action="store_false", help="Do not perform sweeping.")
+    ps.set_defaults(sweep=None)
+    ps.add_argument("--output", default="interpolated.xyz", type=str, help="Output filename. "
+                    "Default is interp.xyz")
+    ps.add_argument("--tol", default=2e-3, type=float, help="Convergence tolerance")
+    ps.add_argument("--maxiter", default=15, type=int, help="Maximum number of minimization iterations")
+    ps.add_argument("--microiter", default=20, type=int, help="Maximum number of micro iterations for "
+                    "sweeping algorithm.")
+    ps.add_argument("--scaling", default=1.7, type=float, help="Exponential parameter for morse potential")
+    ps.add_argument("--friction", default=1e-2, type=float, help="Size of friction term used to prevent "
+                    "very large change of geometry.")
+    ps.add_argument("--dist-cutoff", dest='dist_cutoff', default=3, type=float, help="Cut-off value for the "
+                    "distance between a pair of atoms to be included in the coordinate system.")
+    ps.add_argument("--logging", default="INFO", choices=['DEBUG', 'INFO', 'WARNING', 'ERROR'],
+                    help="Logging level to adopt [ DEBUG | INFO | WARNING | ERROR ]")
+    ps.add_argument("--save-raw", dest='save_raw', default=None, type=str, help="When specified, save the "
+                    "raw path after bisections be before smoothing.")
+    args = ps.parse_args()
+
+    # Setup logging based on designated logging level
+    logging.basicConfig(format="[%(module)-12s]%(message)s", level=args.logging)
+
+    # Read the initial geometries.
+    symbols, X = read_xyz(args.filename)
+    logger.info('Loaded %d geometries from %s', len(X), args.filename)
+    if len(X) < 2:
+        raise ValueError("Need at least two initial geometries.")
+
+    # First redistribute number of images.  Perform interpolation if too few and subsampling if too many
+    # images are given
+    raw = redistribute(symbols, X, args.nimages, tol=args.tol * 5)
+    if args.save_raw is not None:
+        write_xyz(args.save_raw, symbols, raw)
+
+    # Perform smoothing by minimizing distance in Cartesian coordinates with redundant internal metric
+    # to find the appropriate geodesic curve on the hyperspace.
+    smoother = Geodesic(symbols, raw, args.scaling, threshold=args.dist_cutoff, friction=args.friction)
+    if args.sweep is None:
+        args.sweep = len(symbols) > 35
+    try:
+        if args.sweep:
+            smoother.sweep(tol=args.tol, max_iter=args.maxiter, micro_iter=args.microiter)
+        else:
+            smoother.smooth(tol=args.tol, max_iter=args.maxiter)
+    finally:
+        # Save the smoothed path to output file.  try block is to ensure output is saved if one ^C the
+        # process, or there is an error
+        logging.info('Saving final path to file %s', args.output)
+        write_xyz(args.output, symbols, smoother.path)
+
+
+if __name__ == "__main__":
+    main()

geodesic_interpolate-1.0.0/geodesic_interpolate/coord_utils.py

@@ -0,0 +1,221 @@
+"""Coordinate utilities used by the interpolation program"""
+import logging
+
+import numpy as np
+from scipy.spatial import KDTree
+
+
+logger = logging.getLogger(__name__)
+
+
+def align_path(path):
+    """Rotate and translate images to minimize RMSD movements along the path.
+    Also moves the geometric center of all images to the origin.
+    """
+    path = np.array(path)
+    path[0] -= np.mean(path[0], axis=0)
+    max_rmsd = 0
+    for g, nextg in zip(path, path[1:]):
+        rmsd, nextg[:] = align_geom(g, nextg)
+        max_rmsd = max(max_rmsd, rmsd)
+    return max_rmsd, path
+
+
+def align_geom(refgeom, geom):
+    """Find translation/rotation that moves a given geometry to maximally overlap
+    with a reference geometry. Implemented with Kabsch algorithm.
+
+    Args:
+        refgeom:    The reference geometry to be rotated to
+        geom:       The geometry to be rotated and shifted
+
+    Returns:
+        RMSD:       Root-mean-squared difference between the rotated geometry
+                    and the reference
+        new_geom:   The rotated geometry that maximumally overal with the reference
+    """
+    center = np.mean(refgeom, axis=0)   # Find the geometric center
+    ref2 = refgeom - center
+    geom2 = geom - np.mean(geom, axis=0)
+    cov = np.dot(geom2.T, ref2)
+    v, sv, w = np.linalg.svd(cov)
+    if np.linalg.det(v) * np.linalg.det(w) < 0:
+        sv[-1] = -sv[-1]
+        v[:, -1] = -v[:, -1]
+    u = np.dot(v, w)
+    new_geom = np.dot(geom2, u) + center
+    rmsd = np.sqrt(np.mean((new_geom - refgeom) ** 2))
+    return rmsd, new_geom
+
+
+ATOMIC_RADIUS = dict(H=0.31, He=0.28,
+                     Li=1.28, Be=0.96, B=0.84, C=0.76, N=0.71, O=0.66, F=0.57, Ne=0.58,
+                     Na=1.66, Mg=1.41, Al=1.21, Si=1.11, P=1.07, S=1.05, Cl=1.02, Ar=1.06)
+
+
+def get_bond_list(geom, atoms=None, threshold=4, min_neighbors=4, snapshots=30, bond_threshold=1.8,
+                  enforce=()):
+    """Get the list of all the important atom pairs.
+    Samples a number of snapshots from a list of geometries to generate all
+    distances that are below a given threshold in any of them.
+
+    Args:
+        atoms:      Symbols for each atoms.
+        geom:       One or a list of geometries to check for pairs
+        threshold:  Threshold for including a bond in the bond list
+        min_neighbors: Minimum number of neighbors to include for each atom.
+                    If an atom has smaller than this number of bonds, additional
+                    distances will be added to reach this number.
+        snapshots:  Number of snapshots to be used in the generation, useful
+                    for speeding up the process if the path is long and
+                    atoms numerous.
+
+    Returns:
+        List of all the included interatomic distance pairs.
+    """
+    # Type casting and value checks on input parameters
+    geom = np.asarray(geom)
+    if len(geom.shape) < 3:
+        # If there is only one geometry or it is flattened, promote to 3d
+        geom = geom.reshape(1, -1, 3)
+    min_neighbors = min(min_neighbors, geom.shape[1] - 1)
+
+    # Determine which images to be used to determine distances
+    snapshots = min(len(geom), snapshots)
+    images = [0, len(geom) - 1]
+    if snapshots > 2:
+        images.extend(np.random.choice(range(1, snapshots - 1), snapshots - 2, replace=False))
+    # Get neighbor list for included geometry and merge them
+    rijset = set(enforce)
+    for image in images:
+        tree = KDTree(geom[image])
+        pairs = tree.query_pairs(threshold)
+        rijset.update(pairs)
+        bonded = tree.query_pairs(bond_threshold)
+        neighbors = {i: {i} for i in range(geom.shape[1])}
+        for i, j in bonded:
+            neighbors[i].add(j)
+            neighbors[j].add(i)
+        for i, j in bonded:
+            for ni in neighbors[i]:
+                for nj in neighbors[j]:
+                    if ni != nj:
+                        pair = tuple(sorted([ni, nj]))
+                        if pair not in rijset:
+                            rijset.add(pair)
+    rijlist = sorted(rijset)
+    # Check neighbor count to make sure `min_neighbors` is satisfied
+    count = np.zeros(geom.shape[1], dtype=int)
+    for i, j in rijlist:
+        count[i] += 1
+        count[j] += 1
+    for idx, ct in enumerate(count):
+        if ct < min_neighbors:
+            _, neighbors = tree.query(geom[-1, idx], k=min_neighbors + 1)
+            for i in neighbors:
+                if i == idx:
+                    continue
+                pair = tuple(sorted([i, idx]))
+                if pair in rijset:
+                    continue
+                else:
+                    rijset.add(pair)
+                    rijlist.append(pair)
+                    count[i] += 1
+                    count[idx] += 1
+    if atoms is None:
+        re = np.full(len(rijlist), 2.0)
+    else:
+        radius = np.array([ATOMIC_RADIUS.get(atom.capitalize(), 1.5) for atom in atoms])
+        re = np.array([radius[i] + radius[j] for i, j in rijlist])
+    logger.debug("Pair list contain %d pairs", len(rijlist))
+    return rijlist, re
+
+
+def compute_rij(geom, rij_list):
+    """Calculate a list of distances and their derivatives
+
+    Takes a set of cartesian geometries then calculate selected distances and their
+    cartesian gradients given a list of atom pairs.
+
+    Args:
+        geom: Cartesian geometry of all the points.  Must be 2d numpy array or list
+            with shape (natoms, 3)
+        rij_list: list of indexes of all the atom pairs
+
+    Returns:
+        rij (array): Array of all the distances.
+        bmat (3d array): Cartesian gradients of all the distances."""
+    nrij = len(rij_list)
+    rij = np.zeros(nrij)
+    bmat = np.zeros((nrij, len(geom), 3))
+    for idx, (i, j) in enumerate(rij_list):
+        dvec = geom[i] - geom[j]
+        rij[idx] = r = np.sqrt(dvec[0] * dvec[0] +
+                               dvec[1] * dvec[1] + dvec[2] * dvec[2])
+        grad = dvec / r
+        bmat[idx, i] = grad
+        bmat[idx, j] = -grad
+    return rij, bmat
+
+
+def compute_wij(geom, rij_list, func):
+    """Calculate a list of scaled distances and their derivatives
+
+    Takes a set of cartesian geometries then calculate selected distances and their
+    cartesian gradients given a list of atom pairs.  The distances are scaled with
+    a given scaling function.
+
+    Args:
+        geom: Cartesian geometry of all the points.  Must be 2d numpy array or list
+            with shape (natoms, 3)
+        rij_list: 2d numpy array of indexes of all the atom pairs
+        func: A scaling function, which returns both the value and derivative.  Must
+            qualify as a numpy Ufunc in order to be broadcasted to array elements.
+
+    Returns:
+        wij (array): Array of all the scaled distances.
+        bmat (2d array): Cartesian gradients of all the scaled distances, with the
+            second dimension flattened (need this to be used in scipy.optimize)."""
+    geom = np.asarray(geom).reshape(-1, 3)
+    nrij = len(rij_list)
+    rij, bmat = compute_rij(geom, rij_list)
+    wij, dwdr = func(rij)
+    for idx, grad in enumerate(dwdr):
+        bmat[idx] *= grad
+    return wij, bmat.reshape(nrij, -1)
+
+
+def morse_scaler(re=1.5, alpha=1.7, beta=0.01):
+    """Returns a scaling function that determines the metric of the internal
+    coordinates using morse potential
+
+    Takes an internuclear distance, returns the scaled distance, and the
+    derivative of the scaled distance with respect to the unscaled one.
+    """
+    def scaler(x):
+        ratio = x / re
+        val1 = np.exp(alpha * (1 - ratio))
+        val2 = beta / ratio
+        dval = -alpha / re * val1 - val2 / x
+        return val1 + val2, dval
+    return scaler
+
+
+def elu_scaler(re=2, alpha=2, beta=0.01):
+    """Returns a scaling function that determines the metric of the internal
+    coordinates using morse potential
+
+    Takes an internuclear distance, returns the scaled distance, and the
+    derivative of the scaled distance with respect to the unscaled one.
+    """
+    def scaler(x):
+        val1 = (1 - x / re) * alpha + 1
+        dval = np.full(x.shape, -alpha / re)
+        large = x > re
+        v1l = np.exp(alpha * (1 - x[large] / re))
+        val1[large] = v1l
+        dval[large] = -alpha / re * v1l
+        val2 = beta * re / x
+        return val1 + val2, dval - val2 / x
+    return scaler

geodesic_interpolate-1.0.0/geodesic_interpolate/fileio.py

@@ -0,0 +1,49 @@
+"""File IO utilities"""
+import numpy as np
+
+
+def read_xyz(filename):
+    """Read XYZ file and return atom names and coordinates
+
+    Args:
+        filename:  Name of xyz data file
+
+    Returns:
+        atom_names: Element symbols of all the atoms
+        coords: Cartesian coordinates for every frame.
+    """
+    coords = []
+    with open(filename, 'r') as f:
+        for line in f:
+            try:
+                natm = int(line)	# Read number of atoms
+                next(f)		# Skip over comments
+                atom_names = []
+                geom = np.zeros((natm, 3), float)
+                for i in range(natm):
+                    line = next(f).split()
+                    atom_names.append(line[0])
+                    geom[i] = line[1:4]     # Numpy auto-converts str to float
+            except (TypeError, IOError, IndexError, StopIteration):
+                raise ValueError('Incorrect XYZ file format')
+            coords.append(geom)
+    if not coords:
+        raise ValueError("File is empty")
+    return atom_names, coords
+
+
+def write_xyz(filename, atoms, coords):
+    """Write atom names and coordinate data to XYZ file
+
+    Args:
+        filename:   Name of xyz data file
+        atoms:      Iterable of atom names
+        coords:     Coordinates, must be of shape nimages*natoms*3
+    """
+    natoms = len(atoms)
+    with open(filename, 'w') as f:
+        for i, X in enumerate(np.atleast_3d(coords)):
+            f.write("%d\n" % natoms)
+            f.write("Frame %d\n" % i)
+            for a, Xa in zip(atoms, X):
+                f.write(" {:3} {:21.12f} {:21.12f} {:21.12f}\n".format(a, *Xa))

geodesic_interpolate-1.0.0/geodesic_interpolate/geodesic.py

@@ -0,0 +1,233 @@
+"""Geodesic smoothing.   Minimize the path length using redundant internal coordinate
+metric to find geodesics directly in Cartesian, to avoid feasibility problems associated
+with redundant internals.
+"""
+import logging
+
+import numpy as np
+from scipy.optimize import least_squares
+
+from .coord_utils import align_path, get_bond_list, morse_scaler, compute_wij
+
+
+logger = logging.getLogger(__name__)
+
+
+class Geodesic(object):
+    """Optimizer to obtain geodesic in redundant internal coordinates.  Core part is the calculation
+    of the path length in the internal metric."""
+    def __init__(self, atoms, path, scaler=1.7, threshold=3.0, min_neighbors=4, log_level=logging.INFO,
+                 friction=1e-3):
+        """Initialize the interpolater
+        Args:
+            atoms:      Atom symbols, used to lookup radii
+            path:       Initial geometries of the path, must be of dimension `nimage * natoms * 3`
+            scaler:     Either the alpha parameter for morse potential, or an explicit scaling function.
+                        It is easier to get smoother paths with small number of data points using small
+                        scaling factors, as they have large range, but larger values usually give
+                        better energetics because they better represent the (sharp) energy landscape.
+            threshold:  Distance cut-off for constructing inter-nuclear distance coordinates.  Note that
+                        any atoms linked by three or less bonds will also be added.
+            min_neighbors:  Minimum number of neighbors an atom must have in the atom pair list.
+            log_level:  Logging level to use.
+            friction:   Friction term in the target function which regularizes the optimization step
+                        size to prevent explosion.
+        """
+        rmsd0, self.path = align_path(path)
+        logger.log(log_level, "Maximum RMSD change in initial path: %10.2f", rmsd0)
+        if self.path.ndim != 3:
+            raise ValueError('The path to be interpolated must have 3 dimensions')
+        self.nimages, self.natoms, _ = self.path.shape
+        # Construct coordinates
+        self.rij_list, self.re = get_bond_list(path, atoms, threshold=threshold, min_neighbors=min_neighbors)
+        if isinstance(scaler, float):
+            self.scaler = morse_scaler(re=self.re, alpha=1.7)
+        else:
+            self.scaler = scaler
+        self.nrij = len(self.rij_list)
+        self.friction = friction
+        # Initalize interal storages for mid points, internal coordinates and B matrices
+        logger.log(log_level, "Performing geodesic smoothing")
+        logger.log(log_level, "  Images: %4d  Atoms %4d Rijs %6d", self.nimages, self.natoms, len(self.rij_list))
+        self.neval = 0
+        self.w = [None] * len(path)
+        self.dwdR = [None] * len(path)
+        self.X_mid = [None] * (len(path) - 1)
+        self.w_mid = [None] * (len(path) - 1)
+        self.dwdR_mid = [None] * (len(path) - 1)
+        self.disps = self.grad = self.segment = None
+        self.conv_path = []
+
+    def update_intc(self):
+        """Adjust unknown locations of mid points and compute missing values of internal coordinates
+        and their derivatives.  Any missing values will be marked with None values in internal storage,
+        and this routine finds and calculates them.  This is to avoid redundant evaluation of value and
+        gradients of internal coordinates."""
+        for i, (X, w, dwdR) in enumerate(zip(self.path, self.w, self.dwdR)):
+            if w is None:
+                self.w[i], self.dwdR[i] = compute_wij(X, self.rij_list, self.scaler)
+        for i, (X0, X1, w) in enumerate(zip(self.path, self.path[1:], self.w_mid)):
+            if w is None:
+                self.X_mid[i] = Xm = (X0 + X1) / 2
+                self.w_mid[i], self.dwdR_mid[i] = compute_wij(Xm, self.rij_list, self.scaler)
+
+    def update_geometry(self, X, start, end):
+        """Update the geometry of a segment of the path, then set the corresponding internal
+        coordinate, derivatives and midpoint locations to unknown"""
+        X = X.reshape(self.path[start:end].shape)
+        if np.array_equal(X, self.path[start:end]):
+            return False
+        self.path[start:end] = X
+        for i in range(start, end):
+            self.w_mid[i] = self.w[i] = None
+        self.w_mid[start - 1] = None
+        return True
+
+    def compute_disps(self, start=1, end=-1, dx=None, friction=1e-3):
+        """Compute displacement vectors and total length between two images.
+        Only recalculate internal coordinates if they are unknown."""
+        if end < 0:
+            end += self.nimages
+        self.update_intc()
+        # Calculate displacement vectors in each segment, and the total length
+        vecs_l = [wm - wl for wl, wm in zip(self.w[start - 1:end], self.w_mid[start - 1:end])]
+        vecs_r = [wr - wm for wr, wm in zip(self.w[start:end + 1], self.w_mid[start - 1:end])]
+        self.length = np.sum(np.linalg.norm(vecs_l, axis=1)) + np.sum(np.linalg.norm(vecs_r, axis=1))
+        if dx is None:
+            trans = np.zeros(self.path[start:end].size)
+        else:
+            trans = friction * dx  # Translation from initial geometry.  friction term 
+        self.disps = np.concatenate(vecs_l + vecs_r + [trans])
+        self.disps0 = self.disps[:len(vecs_l) * 2]
+
+    def compute_disp_grad(self, start, end, friction=1e-3):
+        """Compute derivatives of the displacement vectors with respect to the Cartesian coordinates"""
+        # Calculate derivatives of displacement vectors with respect to image Cartesians
+        l = end - start + 1
+        self.grad = np.zeros((l * 2 * self.nrij + 3 * (end - start) * self.natoms, (end - start) * 3 * self.natoms))
+        self.grad0 = self.grad[:l * 2 * self.nrij]
+        grad_shape = (l, self.nrij, end - start, 3 * self.natoms)
+        grad_l = self.grad[:l * self.nrij].reshape(grad_shape)
+        grad_r = self.grad[l * self.nrij:l * self.nrij * 2].reshape(grad_shape)
+        for i, image in enumerate(range(start, end)):
+            dmid1 = self.dwdR_mid[image - 1] / 2
+            dmid2 = self.dwdR_mid[image] / 2
+            grad_l[i + 1, :, i, :] = dmid2 - self.dwdR[image]
+            grad_l[i, :, i, :] = dmid1
+            grad_r[i + 1, :, i, :] = -dmid2
+            grad_r[i, :, i, :] = self.dwdR[image] - dmid1
+        for idx in range((end - start) * 3 * self.natoms):
+            self.grad[l * self.nrij * 2 + idx, idx] = friction
+
+    def compute_target_func(self, X=None, start=1, end=-1, log_level=logging.INFO, x0=None, friction=1e-3):
+        """Compute the vectorized target function, which is then used for least
+        squares minimization."""
+        if end < 0:
+            end += self.nimages
+        if X is not None and not self.update_geometry(X, start, end) and self.segment == (start, end):
+            return
+        self.segment = start, end
+        dx = np.zeros(self.path[start:end].size) if x0 is None else self.path[start:end].ravel() - x0.ravel()
+        self.compute_disps(start, end, dx=dx, friction=friction)
+        self.compute_disp_grad(start, end, friction=friction)
+        self.optimality = np.linalg.norm(np.einsum('i,i...', self.disps, self.grad), ord=np.inf)
+        logger.log(log_level, "  Iteration %3d: Length %10.3f |dL|=%7.3e", self.neval, self.length, self.optimality)
+        self.conv_path.append(self.path[1].copy())
+        self.neval += 1
+
+    def target_func(self, X, **kwargs):
+        """Wrapper around `compute_target_func` to prevent repeated evaluation at
+        the same geometry"""
+        self.compute_target_func(X, **kwargs)
+        return self.disps
+
+    def target_deriv(self, X, **kwargs):
+        """Wrapper around `compute_target_func` to prevent repeated evaluation at
+        the same geometry"""
+        self.compute_target_func(X, **kwargs)
+        return self.grad
+
+    def smooth(self, tol=1e-3, max_iter=50, start=1, end=-1, log_level=logging.INFO, friction=None,
+               xref=None):
+        """Minimize the path length as an overall function of the coordinates of all the images.
+        This should in principle be very efficient, but may be quite costly for large systems with
+        many images.
+
+        Args:
+            tol:        Convergence tolerance of the optimality. (.i.e uniform gradient of target func)
+            max_iter:   Maximum number of iterations to run.
+            start, end: Specify which section of the path to optimize.
+            log_level:  Logging level during the optimization
+
+        Returns:
+            The optimized path.  This is also stored in self.path
+        """
+        X0 = np.array(self.path[start:end]).ravel()
+        if xref is None:
+            xref= X0
+        self.disps = self.grad = self.segment = None
+        logger.log(log_level, "  Degree of freedoms %6d: ", len(X0))
+        if friction is None:
+            friction = self.friction
+        # Configure the keyword arguments that will be sent to the target function.
+        kwargs = dict(start=start, end=end, log_level=log_level, x0=xref, friction=friction)
+        self.compute_target_func(**kwargs)  # Compute length and optimality
+        if self.optimality > tol:
+            result = least_squares(self.target_func, X0, self.target_deriv, ftol=tol, gtol=tol,
+                                   max_nfev=max_iter, kwargs=kwargs, loss='soft_l1')
+            self.update_geometry(result['x'], start, end)
+            logger.log(log_level, "Smoothing converged after %d iterations", result['nfev'])
+        else:
+            logger.log(log_level, "Skipping smoothing: path already optimal.")
+        rmsd, self.path = align_path(self.path)
+        logger.log(log_level, "Final path length: %12.5f  Max RMSD in path: %10.2f", self.length, rmsd)
+        return self.path
+
+    def sweep(self, tol=1e-3, max_iter=50, micro_iter=20, start=1, end=-1):
+        """Minimize the path length by adjusting one image at a time and sweeping the optimization
+        side across the chain.  This is not as efficient, but scales much more friendly with the
+        size of the system given the slowness of scipy's optimizers.  Also allows more detailed
+        control and easy way of skipping nearly optimal points than the overall case.
+
+        Args:
+            tol:        Convergence tolerance of the optimality. (.i.e uniform gradient of target func)
+            max_iter:   Maximum number of sweeps through the path.
+            micro_iter: Number of micro-iterations to be performed when optimizing each image.
+            start, end: Specify which section of the path to optimize.
+            log_level:  Logging level during the optimization
+
+        Returns:
+            The optimized path.  This is also stored in self.path
+        """
+        if end < 0:
+            end = self.nimages + end
+        self.neval = 0
+        images = range(start, end)
+        logger.info("  Degree of freedoms %6d: ", (end - start) * 3 * self.natoms)
+        # Microiteration convergence tolerances are adjusted on the fly based on level of convergence.
+        curr_tol = tol * 10
+        self.compute_disps()    # Compute and print the initial path length
+        logger.info("  Initial length: %8.3f", self.length)
+        for iteration in range(max_iter):
+            max_dL = 0
+            X0 = self.path.copy()
+            for i in images[:-1]:   # Use self.smooth() to optimize individual images
+                xmid = (self.path[i - 1] + self.path[i + 1]) * 0.5
+                self.smooth(curr_tol, max_iter=min(micro_iter, iteration + 6),
+                            start=i, end=i + 1, log_level=logging.DEBUG,
+                            friction=self.friction if iteration else 0.1,
+                            xref=xmid)
+                max_dL = max(max_dL, self.optimality)
+            self.compute_disps()    # Compute final length after sweep
+            logger.info("Sweep %3d: L=%7.2f dX=%7.2e tol=%7.3e dL=%7.3e",
+                     iteration, self.length, np.linalg.norm(self.path - X0), curr_tol, max_dL)
+            if max_dL < tol:    # Check for convergence.
+                logger.info("Optimization converged after %d iteartions", iteration)
+                break
+            curr_tol = max(tol * 0.5, max_dL * 0.2) # Adjust micro-iteration threshold
+            images = list(reversed(images))         # Alternate sweeping direction.
+        else:
+            logger.info("Optimization not converged after %d iteartions", iteration)
+        rmsd, self.path = align_path(self.path)
+        logger.info("Final path length: %12.5f  Max RMSD in path: %10.2f", self.length, rmsd)
+        return self.path

geodesic_interpolate-1.0.0/geodesic_interpolate/interpolation.py

@@ -0,0 +1,134 @@
+"""Simplified geodesic interpolations module, which uses geodesic lengths as criteria
+to add bisection points until point count meet desired number.
+Will need another following geodesic smoothing to get final path.
+"""
+import logging
+
+import numpy as np
+from scipy.optimize import least_squares, minimize
+
+from .geodesic import Geodesic
+from .coord_utils import get_bond_list, compute_wij, morse_scaler, align_geom, align_path
+
+
+logger = logging.getLogger(__name__)
+
+
+def mid_point(atoms, geom1, geom2, tol=1e-2, nudge=0.01, threshold=4):
+    """Find the Cartesian geometry that has internal coordinate values closest to the average of
+    two geometries.
+
+    Simply perform a least-squares minimization on the difference between the current internal
+    and the average of the two end points.  This is done twice, using either end point as the
+    starting guess.  DON'T USE THE CARTESIAN AVERAGE AS GUESS, THINGS WILL BLOW UP.
+
+    This is used to generate an initial guess path for the later smoothing routine.
+    Genenrally, the added point may not be continuous with the both end points, but
+    provides a good enough starting guess.
+
+    Random nudges are added to the initial geometry, so running multiple times may not yield
+    the same converged geometry. For larger systems, one will never get the same geometry
+    twice.  So one may want to perform multiple runs and check which yields the best result.
+
+    Args:
+        geom1, geom2:   Cartesian geometry of the end points
+        tol:    Convergence tolarnce for the least-squares minimization process
+        nudge:  Random nudges added to the initial geometry, which helps to discover different
+                solutions.  Also helps in cases where optimal paths break the symmetry.
+        threshold:  Threshold for including an atom-pair in the coordinate system
+
+    Returns:
+        Optimized mid-point which bisects the two endpoints in internal coordinates
+    """
+    # Process the initial geometries, construct coordinate system and obtain average internals
+    geom1, geom2 = np.array(geom1), np.array(geom2)
+    add_pair = set()
+    geom_list = [geom1, geom2]
+    # This loop is for ensuring a sufficient large coordinate system.  The interpolated point may
+    # have atom pairs in contact that are far away at both end-points, which may cause collision.
+    # One can include all atom pairs, but this may blow up for large molecules.  Here the compromise
+    # is to use a screened list of atom pairs first, then add more if additional atoms come into
+    # contant, then rerun the minimization until the coordinate system is consistant with the
+    # interpolated geometry
+    while True:
+        rijlist, re = get_bond_list(geom_list, threshold=threshold + 1, enforce=add_pair)
+        scaler = morse_scaler(alpha=0.7, re=re)
+        w1, _ = compute_wij(geom1, rijlist, scaler)
+        w2, _ = compute_wij(geom2, rijlist, scaler)
+        w = (w1 + w2) / 2
+        d_min, x_min = np.inf, None
+        friction = 0.1 / np.sqrt(geom1.shape[0])
+        def target_func(X):
+            """Squared difference with reference w0"""
+            wx, dwdR = compute_wij(X, rijlist, scaler)
+            delta_w = wx - w
+            val, grad = 0.5 * np.dot(delta_w, delta_w), np.einsum('i,ij->j', delta_w, dwdR)
+            logger.info("val=%10.3f  ", val)
+            return val, grad
+
+        # The inner loop performs minimization using either end-point as the starting guess.
+        for coef in [0.02, 0.98]:
+            x0 = (geom1 * coef + (1 - coef) * geom2).ravel()
+            x0 += nudge * np.random.random_sample(x0.shape)
+            logger.debug('Starting least-squares minimization of bisection point at %7.2f.', coef)
+            result = least_squares(lambda x: np.concatenate([compute_wij(x, rijlist, scaler)[0] - w, (x-x0)*friction]), x0,
+                                   lambda x: np.vstack([compute_wij(x, rijlist, scaler)[1], np.identity(x.size) * friction]), ftol=tol, gtol=tol)
+            x_mid = result['x'].reshape(-1, 3)
+            # Take the interpolated geometry, construct new pair list and check for new contacts
+            new_list = geom_list + [x_mid]
+            new_rij, _ = get_bond_list(new_list, threshold=threshold, min_neighbors=0)
+            extras = set(new_rij) - set(rijlist)
+            if extras: 
+                logger.info('  Screened pairs came into contact. Adding reference point.')
+                # Update pair list then go back to the minimization loop if new contacts are found
+                geom_list = new_list
+                add_pair |= extras
+                break
+            # Perform local geodesic optimization for the new image.
+            smoother = Geodesic(atoms, [geom1, x_mid, geom2], 0.7, threshold=threshold, log_level=logging.DEBUG, friction=1)
+            smoother.compute_disps()
+            width = max([np.sqrt(np.mean((g - smoother.path[1]) ** 2)) for g in [geom1, geom2]])
+            dist, x_mid = width + smoother.length, smoother.path[1]
+            logger.debug('  Trial path length: %8.3f after %d iterations', dist, result['nfev'])
+            if dist < d_min:
+                d_min, x_min = dist, x_mid
+        else:   # Both starting guesses finished without new atom pairs.  Minimization successful
+            break
+    return x_min
+
+
+def redistribute(atoms, geoms, nimages, tol=1e-2):
+    """Add or remove images so that the path length matches the desired number.
+
+    If the number is too few, new points are added by bisecting the largest RMSD. If too numerous,
+    one image is removed at a time so that the new merged segment has the shortest RMSD.
+
+    Args:
+        geoms:      Geometry of the original path.
+        nimages:    The desired number of images
+        tol:        Convergence tolerance for bisection.
+
+    Returns:
+        An aligned and redistributed path with has the correct number of images.
+    """
+    _, geoms = align_path(geoms)
+    geoms = list(geoms)
+    # If there are too few images, add bisection points
+    while len(geoms) < nimages:
+        dists = [np.sqrt(np.mean((g1 - g2) ** 2)) for g1, g2 in zip(geoms[1:], geoms)]
+        max_i = np.argmax(dists)
+        logger.info("Inserting image between %d and %d with Cartesian RMSD %10.3f.  New length:%d",
+                    max_i, max_i + 1, dists[max_i], len(geoms) + 1)
+        insertion = mid_point(atoms, geoms[max_i], geoms[max_i + 1], tol)
+        _, insertion = align_geom(geoms[max_i], insertion)
+        geoms.insert(max_i + 1, insertion)
+        geoms = list(align_path(geoms)[1])
+    # If there are too many images, remove points
+    while len(geoms) > nimages:
+        dists = [np.sqrt(np.mean((g1 - g2) ** 2)) for g1, g2 in zip(geoms[2:], geoms)]
+        min_i = np.argmin(dists)
+        logger.info("Removing image %d.  Cartesian RMSD of merged section %10.3f",
+                    min_i + 1, dists[min_i])
+        del geoms[min_i + 1]
+        geoms = list(align_path(geoms)[1])
+    return geoms

geodesic_interpolate-1.0.0/geodesic_interpolate.egg-info/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: geodesic_interpolate
+Version: 1.0.0
+Summary: Interpolation and smoothing of reaction paths with geodesics in redundant internal coordinates.
+Home-page: https://github.com/virtualzx-nad/geodesic-interpolate
+Author: Xiaolei Zhu
+Author-email: virtualzx@gmail.com
+License: MIT
+Project-URL: Bug Reports, https://github.com/virtualzx-nad/geodesic-interpolate/issues
+Project-URL: Source, https://github.com/virtualzx-nad/geodesic-interpolate
+Keywords: chemistry,molecular dynamics,reaction paths,geodesics
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.13
+Requires-Dist: scipy>=0.19
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+Geodesic interpolations of reaction pathways
+====
+Constructing interpolation paths between molecular geometries to obtain reaction path.
+
+Traditional interpolation methods encounter difficulty when it comes to redundant internal coordinate spaces, because the feasible physical space compose only a very small and highly curved subspace.  In this method, we avoid the problem of feasibility by operating strictly in feasible space, and bring in the benefit of internal coordinates through proper application of the corresponding metric tensor.  With this new formulation, we view the configuration space as a Riemannian manifold with a metric generated from a set of internal coordinates. The interpolation paths are defined as geodesic curves on such manifolds.  In other words the integrated total coordinate change is minimized. Such a definition ensures that the constructed paths are smooth and well behaved. The package is also used for smoothing discontinuous or noisy trajectories obtained from MD simulations.
+
+It has been shown that the method generate smooth paths with reasonable barrier height even for highly complex reactions, such as protein unfolding or concerted cycloaddition reactions with many simutaneous ring formations.   The default coordinate system uses Morse scaled pair-wise distances.  The lengths in such coordinate systems have the physical meaning of the total number of bond changes along the path.
+
+This is a pure python implementation, so it is not optimized for speed, but rather is intended to serve as a reference implementation of the algorithms described in the paper.  Still, interpolating systems with ~1000 atoms should not be a problem.
+
+
+Directory Structure
+----
+- geodesic_interpolate      Python package for interpolation and smoothing by finding geodesic curves with redundant internal metrics
+  - `__init__.py`      Python package file
+  - `__main__.py`      Standalone script for performing interpolation and smoothings.
+  - `geodesic.py`      Computation and minimization of path length in redundant internal metrics.  This is used to optimize
+   a path way to find a geodesic.  Cannot change the number of images during optimization
+  - `interpolation.py` Generating approximate interpolation points to be used as starting guess for the geodesic optimizations.
+   Recursively attempt to perform bisections on largest segment in internal space.  Generally will create path
+   with discontinuities, so a smoothing process need to follow this.
+  - `coord_utils.py`   Coordinate utilities.  A simplified version of Nanoreactor coordinates module which provide a scaled
+   interatomic distance coordinate, pair screening based on threshold and connectivity, as well as trans-rotational
+   alignment based on Kabsch algorithm.
+  - `fileio.py`        XYZ file reading and writing
+- setup.py             Installation script.  This will install both the Python package, which can be imported by name `geodesic_interpolate`
+   and the standalone script, which is also named `geodesic_interpolate`
+- test_cases           A few test cases used to check the performance of the code.  Note that the large ones may take a few minutes
+   thanks to Python.  Especially need to run them when testing out alternative coordinate scaling methods.
+  - `H+CH4_CH3+H2.xyz` A simple test case.  Should always work
+  - `DielsAlder.xyz`   Dehydro-Diels-Alder reaction.  This is an important test case because the initial structure is planar symmetric and
+   could access both the final structure and its mirror image, which as exactly the same internal coordinates.  Proper
+   monitoring of geodesic length during the interpolation process is therefore crucial for this to work, without which
+   the raw interpolated path will jump between mirror images and the optimized path would contain some flopping.
+   Also tests the non-sweeping global path optimization algo in a relatively large system.
+  - `TrpCage_unfold.xyz` Unfolding a Trp-cage mini-protein.  Need at least 10 images to work.  Folded geometry taken from Stefan''s test
+   directory which is instead taken from Nathan.  Unfolded structure is generated by force navigated MD for 1ns under
+   1nN on C and N terminal with ReaxFF, then optimizing without force at 6-31g/b3lyp level.  For testing many
+   simultaneous large amplitude motions.
+  - `collagen.xyz`     Interpolate between the solution and crystal structure of collagen Kunitz domain 1kun - 1kth.  Solvents removed
+   from the PDB structures.  Tests collision avoidance for large movements in the core of folded protein.  Other
+   groups should slightly breath to create room for the part that changes.
+  - `calcium_binding.xyz`  Binding two Ca2+ ions to the yeast Calmodulin N terminal domain 1f54 -1f55.  The apo structure did not have
+   ions so two of which were added by hand at random locations away from the protein.  It seem to be hard to avoid
+   large movements of the Ca2+ cations when they are very far away from the protein but once in contact they should
+   move smoothly.  This is to test if the interpolater can correctly route and find the entry point and connect the
+   path.
+
+
+Prerequisites
+----
+
+Python :  >=3.8
+
+Numpy  :  Tested with 1.13
+
+Scipy  :  Tested with 0.19
+
+
+Installation
+----
+
+### From PyPI
+
+Once a release has been published to PyPI, install the package with:
+
+    pip install geodesic_interpolate
+
+### From Source
+
+The package can be used without installation from the package directory with
+
+    python -m geodesic_interpolate filename ...
+
+To use the script from an arbitrary location or import the Python module, install the package with pip:
+
+    python -m pip install .
+
+This will install a Python package `geodesic_interpolate` and a standalone script `geodesic_interpolate`.
+The package can be invoked from an arbitrary location using the aforementioned command line after installation,
+and a standalone script with the same signature can also be used
+
+    geodesic_interpolate filename.xyz --output output.xyz --nimages 20 ...
+
+
+Usage
+----
+usage: geodesic_interpolate [-h] [--nimages NIMAGES] [--sweep] [--no-sweep]
+                            [--output OUTPUT] [--tol TOL] [--maxiter MAXITER]
+                            [--microiter MICROITER] [--scaling SCALING]
+                            [--friction FRICTION] [--dist-cutoff DIST_CUTOFF]
+                            [--logging {DEBUG,INFO,WARNING,ERROR}]
+                            [--save-raw SAVE_RAW]
+                            filename
+
+Interpolates between two geometries
+
+positional arguments:
+  * filename            XYZ file containing geometries. If the number of images is smaller than the desired number,
+   interpolation points will be added. If the number is greater, subsampling will be performed.
+
+optional arguments:
+  * `-h`, `--help`      show this help message and exit
+  * `--nimages NIMAGES` Number of images. (default: 17)
+  * `--sweep`           Sweep across the path optimizing one image at a time, instead of moving all images at the same time.
+   Default is to perform sweeping updates if there are more than 30 atoms. (default: None)
+  * `--no-sweep`        Do not perform sweeping. (default: None)
+  * `--output OUTPUT`   Output filename. Default is interp.xyz (default: interpolated.xyz)
+  * `--tol TOL`         Convergence tolerance (default: 0.002)
+  * `--maxiter MAXITER` Maximum number of minimization iterations (default: 15)
+  * `--microiter MICROITER`  Maximum number of micro iterations for sweeping algorithm. (default: 20)
+  * `--scaling SCALING` Exponential parameter for morse potential (default: 1.7)
+  * `--friction FRICTION`   Size of friction term used to prevent very large change of geometry. (default: 0.01)
+  * `--dist-cutoff DIST_CUTOFF` Cut-off value for the distance between a pair of atoms to be included in the coordinate system. (default: 3)
+  * `--logging {DEBUG,INFO,WARNING,ERROR}`   Logging level to adopt [ DEBUG | INFO | WARNING | ERROR ] (default: INFO)
+  * `--save-raw SAVE_RAW`   When specified, save the raw path after bisections be before smoothing. (default: None)

geodesic_interpolate-1.0.0/geodesic_interpolate.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+setup.py
+geodesic_interpolate/__init__.py
+geodesic_interpolate/__main__.py
+geodesic_interpolate/coord_utils.py
+geodesic_interpolate/fileio.py
+geodesic_interpolate/geodesic.py
+geodesic_interpolate/interpolation.py
+geodesic_interpolate.egg-info/PKG-INFO
+geodesic_interpolate.egg-info/SOURCES.txt
+geodesic_interpolate.egg-info/dependency_links.txt
+geodesic_interpolate.egg-info/entry_points.txt
+geodesic_interpolate.egg-info/requires.txt
+geodesic_interpolate.egg-info/top_level.txt

geodesic_interpolate-1.0.0/geodesic_interpolate.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

geodesic_interpolate-1.0.0/geodesic_interpolate.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+geodesic_interpolate = geodesic_interpolate.__main__:main

geodesic_interpolate-1.0.0/geodesic_interpolate.egg-info/requires.txt

@@ -0,0 +1,2 @@
+numpy>=1.13
+scipy>=0.19

geodesic_interpolate-1.0.0/geodesic_interpolate.egg-info/top_level.txt

@@ -0,0 +1 @@
+geodesic_interpolate

geodesic_interpolate-1.0.0/pyproject.toml

@@ -0,0 +1,3 @@
+[build-system]
+requires = ["setuptools>=42", "wheel"]
+build-backend = "setuptools.build_meta"

geodesic_interpolate-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

geodesic_interpolate-1.0.0/setup.py

@@ -0,0 +1,49 @@
+"""Installer for geodesic interpolation package.
+Install the package into python environment, and provide an entry point for the
+main interpolation script.
+"""
+from setuptools import setup
+import pathlib
+
+# Read the contents of README.md
+here = pathlib.Path(__file__).parent.resolve()
+long_description = (here / "README.md").read_text(encoding="utf-8")
+
+setup(
+    name='geodesic_interpolate',
+    version='1.0.0',
+    description='Interpolation and smoothing of reaction paths with geodesics in redundant internal coordinates.',
+    long_description=long_description,
+    long_description_content_type='text/markdown',
+    author='Xiaolei Zhu',
+    author_email='virtualzx@gmail.com',
+    url='https://github.com/virtualzx-nad/geodesic-interpolate',
+    license='MIT',
+    packages=['geodesic_interpolate'],
+    python_requires='>=3.8',
+    install_requires=[
+        'numpy>=1.13',
+        'scipy>=0.19',
+    ],
+    entry_points = {
+        'console_scripts': [
+            'geodesic_interpolate=geodesic_interpolate.__main__:main',
+        ],
+    },
+    classifiers=[
+        'Development Status :: 4 - Beta',
+        'Intended Audience :: Science/Research',
+        'Programming Language :: Python :: 3.8',
+        'Programming Language :: Python :: 3.9',
+        'Programming Language :: Python :: 3.10',
+        'Programming Language :: Python :: 3.11',
+        'Programming Language :: Python :: 3.12',
+        'Topic :: Scientific/Engineering :: Chemistry',
+        'Topic :: Scientific/Engineering :: Physics',
+    ],
+    keywords='chemistry, molecular dynamics, reaction paths, geodesics',
+    project_urls={
+        'Bug Reports': 'https://github.com/virtualzx-nad/geodesic-interpolate/issues',
+        'Source': 'https://github.com/virtualzx-nad/geodesic-interpolate',
+    },
+)