Metadata-Version: 2.4
Name: kearsley_numba
Version: 0.1.0
Summary: Fast Kearsley 3D superposition (RMSD minimization) using Numba JIT
Author: bigbigdumdum
License: MIT License
        
        Copyright (c) 2024 Mukundan S
        
        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.
        
Project-URL: Homepage, https://github.com/bigbigdumdum/kearsley_numbajit
Project-URL: Repository, https://github.com/bigbigdumdum/kearsley_numbajit
Project-URL: Bug Tracker, https://github.com/bigbigdumdum/kearsley_numbajit/issues
Keywords: kearsley,rmsd,superposition,numba,structural-biology,protein
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Chemistry
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: numba>=0.57
Requires-Dist: scipy>=1.6
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-benchmark; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# Kearsley's algorithm

Kearsley's algorithm calculates the rotaiton and translation required to superimposed two sets of cordinates by minimizing their RMSD. 

This is a faster implementation of the python implementation by Marcelo Moreno (martxelo) (https://github.com/martxelo/kearsley-algorithm) using numba njit.

Benchmarks by %timeit for fitting 10 atoms

Original version: 215 µs ± 27.9 µs per loop (mean ± std. dev. of 7 runs, 1,000 loops each)

This version: 9.62 µs ± 124 ns per loop (mean ± std. dev. of 7 runs, 100,000 loops each) 

A cpython implementation might be faster. 

# Usage

My application needed fit_tansform to also computer structure overlap, which is the percentage of atoms withing a distance cutoff.

```python3
u,v = read_from_data()
# these have to be of the numpy arrays of shape (N,3) where the N must be the same for both u and v

# so_dc is the distance cutoff used to compute structure overlap. Has to be a float. 
so_dc = 1.0

from kearsley import fit_transform

# get cordinates of v transformedt to u, RMSD, SO, and the rotation and translation matrices as numpy arrays
transformed_v, rmsd , so, rotation, translation = fit_transform(u, v, so_dc)
```
If only rmsd needs to be computed

```python3
from kearsley import fit

rmsd, q, centroid_u, centroid_v = fit(u, v)

# rotation and translation matrices can be computed by

from kearsley import fill_rot_and_trans

centroid_u_ = np.empty(3,dtype=float)
rotation = np.empty((3,3),dtype=float)

rotation,translation = fill_rot_and_trans(q,centroid_u,centroid_v,rotation,centroid_u_)
```
If rotationand translation matrices are already computed transform function can transform an array of shape (M,3). Note that the M can be different to N. This function, for example, allows fitting a subset of coordinates and then applying that transformation to all coordinates.
```python3
from kearsley import fit_transform,transform

u,v = read_from_data() # shape (N,3)
w = read_all_cordinantes() # w is the superset of v. and is of the shape (M,3) M>N

transformed_v, rmsd , so, rotation, translation = fit_transform(u, v, so_dc)

# get transformed w
tra_v = transform(w,rotation,translation)
```

# Packages and version used

The following are the packages and version which this script was last tested with.
```
python = 3.12.2
numpy = 1.26.4
numba = 0.59.1
```


