Metadata-Version: 2.1
Name: chiralfinder
Version: 0.0.3
Summary: The chiralfinder package.
Home-page: https://github.com/Meteor-han/chiralfinder/
License: MIT
Keywords: Chirality,Chiral axis
Author: Runhan Shi
Author-email: han.run.jiangming@sjtu.edu.cn
Maintainer: Runhan Shi
Maintainer-email: han.run.jiangming@sjtu.edu.cn
Requires-Python: >=3.8,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.13
Requires-Dist: numpy (>=1.26.4,<2.0.0)
Requires-Dist: rdkit (>=2024.3.3,<2025.0.0)
Requires-Dist: tqdm (>=4.65.0,<5.0.0)
Project-URL: Documentation, https://github.com/Meteor-han/chiralfinder/
Project-URL: Repository, https://github.com/Meteor-han/chiralfinder/
Project-URL: issues, https://github.com/Meteor-han/chiralfinder/issues
Description-Content-Type: text/markdown

# chiralfinder

Data and codes for the paper "[A Unifying Geometric Framework for Computational Representation of Stereoisomers Based on Mixed Product](https://www.cell.com/cell-reports-physical-science/fulltext/S2666-3864(25)00664-2)", published in *Cell Reports Physical Science* 2026.

## Overview

Molecular chirality plays a fundamental role in chemistry, biology, and drug discovery, yet existing computational methods struggle with complex stereochemistry and cannot quantify chirality. This project introduces **a unifying geometric framework based on mixed product representations** that directly map molecular symmetry breaking into a 3D algebraic space. The framework provides quantitative descriptors for each stereogenic element, going beyond the qualitative Cahn–Ingold–Prelog rules. We implement this theory in **ChiralFinder**, a computational tool that accurately identifies and distinguishes central and axial stereogenic elements, differentiates conformations, and integrates effectively with machine learning models to improve spectra prediction. By offering a rigorous geometric foundation, ChiralFinder enables automated chirality analysis and forms the basis for a comprehensive stereoisomer representation framework with potential extensions to planar and helical chirality.

<img src="https://github.com/Meteor-han/chiralfinder/blob/main/img_axial/chirality product.png" alt="1"  width="95%" height="auto" />

## Web server

See online web server at [Here](https://compbio.sjtu.edu.cn/services/chiralfinder).

## Quick use

To use ChiralFinder as a python package, install Anaconda, create and enter your own environment like

    conda create -n env_test python=3.10
Enter the conda environment and install the ChiralFinder package through pip like

```
conda activate env_test
pip install chiralfinder
```

Run `run_example.py` to get example results.

```
python run_example.py
```

```python
from chiralfinder import ChiralFinder

if __name__ == '__main__':
    smi_list = ["C[C@H]1CC(=O)[C@]2(CCCC2=O)C1", "CC1=CC=C(SC2=C(C)N(C3=CC=CC=C3C(C)(C)C)C(C)=C2)C=C1"]

    chiral_finder = ChiralFinder(smi_list, "SMILES")
    res_ = chiral_finder.get_axial(n_cpus=8)
    print(res_[0]["chiral axes"], res_[1]["chiral axes"])
    chiral_finder.draw_res_axial("./img")

    smi_list_center = ["BrC/C(=C\[C@@H]1CCCO1)C1CCCCC1"]
    chiral_finder = ChiralFinder(smi_list_center, "SMILES")
    res_ = chiral_finder.get_central()
    print(res_)
```

You will get the images of two molecules with predicted chiral axes in the folder `./img` by default. Predicted chiral axes:

```
[(5,)] [(9, 10)]
```

<img src="https://github.com/Meteor-han/chiralfinder/blob/main/img_axial/0.png" alt="0" width="30%" height="auto" /><img src="https://github.com/Meteor-han/chiralfinder/blob/main/img_axial/1.png" alt="1"  width="30%" height="auto" />

You will get the prediction of one molecule for central chirality.

```
[{'center id': [4], 
'quadrupole matrix': 
       [[array([[-0.29989338, -1.08474684,  0.09943545],
       [-0.58823299,  0.65781245, -1.20683256],
       [ 2.07548201, -0.47857599, -1.02051216]])]], 
'determinant': [[3.6349643722752485]], 
'norm CP': [[0.9890715818535913]], 
'sign': [[1.0]], 
'neighbor ids': [[18, 5, 3, 8]]}]
```


## Dataset

The RotA dataset is stored in the folder `./data`. It contains 3,140 conformers of 650 axially chiral molecules, each with at least one chiral axis. The excel file contains labeled chiral axes and some calculated molecular properties. The pickle file includes calculated molecular conformers. The dataset includes a wide range of axially chiral structures, and the corresponding molecular fingerprints are visualized below.

<img src="https://github.com/Meteor-han/chiralfinder/blob/main/img_axial/axial_650.png" alt="1"  width="80%" height="auto" />

We also provide sampled achiral molecules and centrally chiral molecules with multiple centers from the PubChem3D database in the folder `./data`.

## Citation

```
@article{Shi2025ChiralFinder,
  author    = {Shi, Runhan and Zhang, Chi and Yu, Gufeng and Huo, Xiaohong and Yang, Yang},
  title     = {A unifying geometric framework for computational representation of stereoisomers based on mixed product},
  journal   = {Cell Reports Physical Science},
  year      = {2026},
  volume    = {7},
  number    = {1},
  pages     = {103065},
  doi       = {10.1016/j.xcrp.2025.103065},
}
```


