knf-predictor 2.0.1
Ultra-fast prediction of supramolecular stability using Graph Neural Networks
License: MIT
Requires Python: >=3.8
Keywords: chemistry, machine-learning, supramolecular, deep-learning, graph-neural-networks, cheminformatics

# KNF Predictor

> **Ultra-fast prediction of supramolecular stability using the Kulkarni-NCI Fingerprint (KNF)**

A Python package for predicting the **Non-Covalent Interaction Score (SNCI)** of supramolecular complexes using a physics-informed, 9-dimensional molecular descriptor. Powered by a Graph Attention Network (GAT) surrogate model for **416× acceleration** over quantum mechanical calculations.

[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![PyTorch](https://img.shields.io/badge/PyTorch-2.0+-ee4c2c.svg)](https://pytorch.org/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

---

## 📌 What is KNF?

The **Kulkarni-NCI Fingerprint (KNF)** is a state-of-the-art descriptor for supramolecular stability prediction:

- **R² = 0.793** on 2,649 Deep Eutectic Solvent (DES) complexes
- **47% improvement** over traditional SOAP descriptors (14,560 features)
- **99.9% dimensionality reduction** (9 features vs. 14,560)
- **Universal generalization** across hydrogen-bond and dispersion-dominated systems

### The 9 KNF Features

| Block | Features | Physical Meaning |
|-------|----------|------------------|
| **Geometric** | f₁, f₂ | Center-of-mass distance, H-bond angle |
| **Electronic** | f₃, f₄, f₅ | Wiberg bond order, dipole moment, polarizability |
| **NCI Statistics** | f₆, f₇, f₈, f₉ | Attractive point count, mean/std/skew of NCI field |

---

## 🚀 Features

✅ **Command-line interface** for batch predictions  
✅ **GPU acceleration** (CUDA support)  
✅ **416× faster** than quantum mechanical calculations  
✅ **Validated performance**: R² = 0.997 on test set  
✅ **Handles large datasets**: 200,000+ molecules/hour  
✅ **Production-ready**: Robust error handling, progress tracking  

---

## 📦 Installation

### Prerequisites
- Python 3.8+
- PyTorch 2.0+
- CUDA 11.7+ (optional, for GPU)

### Quick Install

Clone repository
git clone https://github.com/Prasanna163/knf-predictor.git
cd knf-predictor

Install in development mode
pip install -e .

text

### Dependencies
pip install torch>=2.0.0 torch-geometric>=2.3.0 rdkit>=2023.3.1 numpy pandas tqdm

text

---

## ⚡ Quick Start

### Command-Line Usage

Single molecule (SMILES)
knf-predict -s "CCO" -o output.csv

Batch prediction from folder
knf-predict -i molecules/ -o results.csv --device cuda

From CSV with SMILES column
knf-predict -i dataset.csv --smiles-col "SMILES" -o predictions.csv

text

### Python API

from knf_predictor import KNFPredictor

Initialize predictor
predictor = KNFPredictor(device='cuda') # or 'cpu'

Predict from SMILES
results = predictor.predict_smiles([
"CCO", # Ethanol
"CC(=O)O", # Acetic acid
])

print(results)

Output: DataFrame with 9 KNF features per molecule
text

---

## 📊 Performance Benchmarks

### Throughput (Molecules/Hour)

| System | CPU | GPU |
|--------|-----|-----|
| **KNF Surrogate** | 1,872 | 216,886 |
| **QM Pipeline** | 520 | - |
| **Speedup** | 3.6× | **416×** |

### Prediction Accuracy (Test Set, N=398)

| Feature | R² | MAE |
|---------|-----|-----|
| f₁ (Distance) | 0.866 | 0.243 Å |
| f₃ (WBO) | 0.860 | 0.0087 |
| f₅ (Polarizability) | **0.938** | 8.23 Bohr³ |
| f₇ (NCI Mean) | 0.741 | 0.0034 a.u. |
| **Overall** | **0.997** | - |

---

## 🛠️ Advanced Usage

### GPU Batch Processing

Optimize batch size for your GPU
knf-predict -i molecules/ -o output.csv
--device cuda
--batch-size 64 # Adjust based on GPU memory

text

### Hybrid Screening Workflow

from knf_predictor import KNFPredictor

predictor = KNFPredictor(device='cuda')

Step 1: Fast screening (GAT surrogate)
results = predictor.predict_folder('library/', batch_size=64)

Step 2: Refine top candidates (QM if needed)
top_100 = results.nlargest(100, 'f7_nci_mean')

... perform QM calculations on top_100 ...
text

---

## 📁 Input Formats

### 1. XYZ Files (Recommended)
12
Ethanol molecule
C 0.000 0.000 0.000
H 1.000 0.000 0.000
...

text

### 2. SMILES Strings
knf-predict -s "CCO" -o output.csv

text

### 3. CSV with SMILES
ID,SMILES,Property
1,CCO,78.5
2,CC(=O)O,60.05

text
undefined
knf-predict -i data.csv --smiles-col SMILES -o predictions.csv

text

---

## 📖 Citation

If you use this package in your research, please cite:

@article{kulkarni2025knf,
title={A Physics-Informed Fingerprint for Generalizable Prediction of Supramolecular Stability},
author={Kulkarni, Prasanna P.},
journal={Journal Name},
year={2025},
doi={10.xxxx/xxxxx}
}

text

---

## 🧪 Validated Datasets

| Dataset | Size | Domain | R² |
|---------|------|--------|-----|
| **DES** | 2,649 | Hydrogen-bonded | 0.793 |
| **S66×8** | 528 | Mixed interactions | 0.955 |
| **S30L** | 30 | Dispersion-bound | 0.803 |
| **Experimental DES** | 40 | Lab-validated | 0.893 |

---

## ⚙️ Configuration

### Model Files

Place the following files in `knf_predictor/models/`:

models/
├── gat_surrogate_best.pt # Pre-trained GAT model
├── scaler_X.pkl # Feature scaler
└── scaler_y.pkl # Target scaler

text

Download from: [Releases](https://github.com/Prasanna163/knf-predictor/releases)

### GPU Requirements

- **Minimum**: 4 GB VRAM (batch_size=16)
- **Recommended**: 6 GB VRAM (batch_size=64)
- **Optimal**: 8+ GB VRAM (batch_size=128)

---

## 🐛 Troubleshooting

### Common Issues

**Problem**: `CUDA out of memory`  
**Solution**: Reduce `--batch-size` or use CPU

**Problem**: `python: command not found`  
**Solution**: Add Python to PATH (see [Installation Guide](docs/PATH_FIX.md))

---

## 📜 License

MIT License - see [LICENSE](LICENSE) for details.

---

## 🤝 Contributing

Contributions are welcome! Please:
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/new-descriptor`)
3. Commit changes (`git commit -m 'Add new descriptor'`)
4. Push to branch (`git push origin feature/new-descriptor`)
5. Open a Pull Request

---

## 📞 Contact

**Prasanna P. Kulkarni**  
Institute of Chemical Technology, Mumbai  
📧 prasannakulkarni163@gmail.com  
🔗 [GitHub](https://github.com/Prasanna163) | [LinkedIn](https://www.linkedin.com/in/prasanna-kulkarni-25b70b262/)

---

## 🙏 Acknowledgments

- Google Gemini Pro for manuscript assistance
- PyTorch Geometric team for graph neural network framework
- RDKit community for cheminformatics tools

---

**⚡ Built for computational chemists, by computational chemists.**