KNF Predictor

Physics-informed surrogate models for rapid prediction of the Kulkarni-NCI Fingerprint (KNF) of non-covalent complexes.

Overview

KNF Predictor is research software for estimating the nine-component Kulkarni-NCI Fingerprint from molecular structures. The surrogate reduces the cost of generating KNF features with quantum-chemical and real-space analysis workflows.

The package is intended for rapid screening and prioritization. High-value candidates should still be checked with the reference computational workflow.

What KNF Represents

KNF combines geometric, electronic, and non-covalent-interaction statistics in one compact vector.

Block	Features	Physical meaning
Geometry	f1, f2	Center-of-mass distance and donor-hydrogen-acceptor angle
Electronic structure	f3, f4, f5	Wiberg bond order, dipole moment, and polarizability
NCI-field statistics	f6-f9	Attractive-point count, mean, standard deviation, and skewness

Published Results

Two different prediction tasks are reported in the associated paper. They should not be interpreted as the same benchmark.

KNF as a Stability Descriptor

These results measure how well KNF predicts supramolecular stability.

Evaluation	Reported R2
DES dataset, 2,649 complexes	0.793
S66 cross-domain evaluation	0.955 +/- 0.027
DES cross-domain evaluation	0.688 +/- 0.069
S30L evaluation	0.803

Surrogate Prediction of KNF Features

These results measure how well the graph model reproduces the KNF vector itself.

• Seven critical KNF features achieved reported R2 values above 0.78.
• The reported per-complex runtime decreased from 6.9 s to 16.6 ms under the benchmark setup.
• This corresponds to a reported 416-fold acceleration.

Runtime and throughput depend on hardware, batch size, molecular size, and software configuration.

Installation

Install from PyPI:

pip install knf-predictor

Install the development version from source:

git clone https://github.com/Prasanna163/KNF-Predictor.git
cd KNF-Predictor
pip install -e .

Core dependencies include PyTorch, PyTorch Geometric, NumPy, pandas, scikit-learn, and tqdm.

Quick Start

Command Line

Predict from a SMILES string:

knf-predict -s "CCO" -o output.csv

Predict structures in an XYZ directory:

knf-predict -i molecules/ -o results.csv --device cuda

Predict from a CSV file containing a SMILES column:

knf-predict -i dataset.csv --smiles-col SMILES -o predictions.csv

Python API

from knf_predictor import KNFPredictor

predictor = KNFPredictor(device="cpu")
results = predictor.predict_smiles(["CCO", "CC(=O)O"])
print(results)

Recommended Screening Workflow

1. Generate KNF predictions for the candidate library.
2. Rank or cluster candidates using the features relevant to the scientific question.
3. Inspect structures for domain and geometry problems.
4. Recalculate selected candidates with the reference KNF workflow.
5. Report surrogate and reference results separately.

Limitations

• Predictions are model-dependent and may degrade outside the training domain.
• Input geometry quality affects structure-based predictions.
• Aggregate R2 values do not guarantee equal accuracy for every KNF feature.
• GPU throughput values are hardware-specific.
• The model does not replace electronic-structure validation for final scientific claims.

Citation

@article{kulkarni2026knf,
  author  = {Kulkarni, Prasanna P.},
  title   = {A Physics-Informed Fingerprint for Generalizable Prediction of Supramolecular Stability},
  journal = {The Journal of Physical Chemistry B},
  year    = {2026},
  volume  = {130},
  number  = {1},
  pages   = {493--508},
  doi     = {10.1021/acs.jpcb.5c07262}
}

License

This repository is distributed under the MIT License. See LICENSE.

Contact

Prasanna P. Kulkarni
Institute of Chemical Technology, Mumbai, Marathwada Campus
Email: prasannakulkarni163@gmail.com