Learning ensemble-derived relational priors for efficient molecular conformer generation

MANIMOL

MANIMOL predicts ensemble-derived pairwise mean/dispersion relational priors from molecular graphs, uses them in torsional proposal generation, and builds compact conformer libraries by reference-free selection.

The installable software is separated from large research artifacts:

• PyPI: lightweight numerical utilities and the complete checkpoint-backed inference source;
• external files: checkpoints and processed/raw datasets supplied by the user or a release;
• source repository: training and paper-specific experiment scripts.

No GEOM, Platinum, or PDBbind data and no model checkpoint are redistributed by this package.

Install

python -m pip install manimol
python -m pip install 'manimol[full]'

The base install only needs NumPy. The full extra adds PyTorch, PyTorch Geometric, RDKit, SciPy, tqdm, and PyYAML. GPU-enabled PyTorch should be installed for the user's CUDA environment when needed.

What is included

The wheel contains the existing MANIMOL implementation, including graph preprocessing; Stage-I graph and mean/dispersion heads; cross-fragment torsional context; dispersion-to-width control; probability-guided and noise-conditioned proposal branches; candidate-pool generation and oversampling; reference-free selection; ETKDG initialization; MMFF-based geometric preparation; filtering and RMSD deduplication; COV/AMR utilities; and checkpoint loading.

The package is assembled from the repository's real inference modules. It does not reimplement a simplified model under a new namespace.

Full inference

manimol-infer delegates to the same Stage-I/Stage-II entry point used by the project. It requires a compatible checkpoint and the processed/raw dataset records expected by that entry point:

manimol-infer \
  --base_checkpoint /path/to/stage2_best.pth \
  --denoiser_checkpoint /path/to/denoiser.pth \
  --checkpoint /path/to/stage2_best.pth \
  --dataset Drugs \
  --data_root /path/to/data \
  --raw_prefix geom_drugs \
  --split test \
  --device cuda \
  --use_dispersion_proposal \
  --select_candidates stable_fps_088 \
  --stable_displacement_quantile 0.88 \
  --output_dir results/manimol

The package default is a 15-fold candidate oversampling factor. The validated selection preset applies MMFF94s preparation, a 10 kcal/mol relative-energy window, reference-free 0.88 displacement filtering, and fixed-budget FPS. Override it with --oversample_factor or --select_candidates for another protocol. The underlying options remain available, including P-basin checkpoints, MMFF settings, energy-aware selectors, deduplication, RMSD backends, and metric thresholds:

manimol-infer --help

The checkpoint family, raw-prefix naming, and preprocessing must match. A wheel alone cannot reproduce a paper table without those external artifacts.

Python API

The lightweight numerical utilities remain directly importable:

import numpy as np
from manimol import density_centrality_select, ensemble_pairwise_prior

conformers = np.load("conformers.npy")  # (n_conformers, n_atoms, 3)
mean, dispersion = ensemble_pairwise_prior(conformers)
indices = density_centrality_select(conformers, k=20)
library = conformers[indices]

For the complete model-backed path, ManiMol is a thin wrapper around the real inference entry point. It uses the benchmark dataset contract rather than inventing a separate SMILES-to-PyG adapter:

from manimol import ManiMol

model = ManiMol.from_pretrained(
    "/path/to/stage2_best.pth",
    device="cuda",
    denoiser_checkpoint="/path/to/denoiser.pth",
)
model.generate(
    data_root="/path/to/data",
    output_dir="results/manimol",
    dataset="Drugs",
    raw_prefix="geom_drugs",
    split="test",
    select_candidates="stable_fps_088",
)

Generated SDF/metrics/log artifacts are written to output_dir. A direct generate(smiles=...) adapter is intentionally not claimed in this release: the production implementation expects graph, torsion-index, and conformer record fields. A future adapter should reuse the exact repository graph builder and be validated against this full path first.

Source layout

The runtime modules needed by the real entry point are kept under src/, including models/, dataset/, utils/, and the inference modules. Training and benchmark launchers remain in the source repository and are not needed to run a released checkpoint.

Development checks

python -m pip install -e '.[test,build]'
pytest
python -m build

The lightweight tests do not require PyTorch, PyTorch Geometric, or RDKit. The full path should be smoke-tested in an environment containing the full dependencies and a compatible checkpoint before release.