knf-predictor 2.0.1

Ultra-fast prediction of supramolecular stability using Graph Neural Networks

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.

---

📌 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

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)

---

📜 License

MIT License - see 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
📧 [e-mail]
🔗 GitHub | LinkedIn

---

🙏 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.