MANIMOL

MANIMOL learns ensemble-derived pairwise mean and dispersion relational priors from molecular graphs and uses them to guide torsional conformer generation and reference-free compact-library construction.

The public project contains the active source implementation used by the paper's MANIMOL pipeline. It does not redistribute benchmark datasets, checkpoints, generated conformers, server outputs, or credentials.

Quick Start

Installation

pip install manimol

For the checkpoint-backed model pipeline:

pip install "manimol[full]"

The full extra provides PyTorch, PyTorch Geometric, RDKit, SciPy, tqdm, and PyYAML. The optional evaluation extra adds pandas, Matplotlib, and scikit-learn used by selected benchmark/reporting scripts. Install a CUDA-compatible PyTorch build separately when GPU inference is required.

What the public code runs

2D molecular graph
    -> graph encoder
    -> mean + dispersion relational priors
    -> cross-fragment torsional context
    -> circular torsion-state proposals
    -> probability-guided and noise-conditioned branches
    -> oversampled candidate pool
    -> reference-free selection
    -> ETKDG initialization and MMFF94s pool preparation
    -> optional final GFN2-xTB relaxation and RMSD deduplication
    -> final conformer library and metrics

The mean and dispersion predictions jointly form the torsional relational context. Dispersion also enters the separate bond-specific width pathway. The active mean--dispersion inference path uses the repository's MMFF94s pool preparation and can optionally run the existing GFN2-xTB final relaxation; the package does not claim that every research selector uses an identical energy-window rule. The README follows the implementation; it does not replace or simplify the model.

For the fixed-budget post-processing protocol used in the current manuscript, the public API provides the complete sequence

MMFF94s optimization -> relative 10 kcal/mol energy window
-> centered-RMSD farthest-point selection -> final MMFF94s optimization

It can be applied to a generated candidate tensor and an RDKit molecule after the checkpoint-backed inference step:

from manimol import mmff94s_window_fps

library = mmff94s_window_fps(
    candidate_coordinates, molecule, target_count=10,
    window_kcal=10.0, final_mmff94s=True,
)

The model-side generation still performs oversampling and reference-free selection through manimol-infer; the post-processing function is explicit so that the energy window and FPS budget are reproducible rather than hidden in a paper-specific script. Checkpoints and benchmark data remain external.

Inference command

The full inference entry point uses the same dataset-record contract as the paper experiments. It requires a compatible checkpoint and local data files:

manimol-infer \
  --protocol route2_paper \
  --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 precision2r \
  --output_dir results/manimol

The route2_paper preset uses the validated defaults: 15-fold oversampling (30R candidates for a 2R retained budget), dispersion-controlled proposals, deterministic modes, the 20-neighbor density--centrality selector (precision2r, $α=1.0$, $β=0.45$, 0.45 prefilter quantile, and 0.04 duplicate radius), and MMFF94s preparation. Override any value explicitly for another protocol. If no denoiser checkpoint is available, pass --pbasin_only explicitly for the Stage-II-only path. All options from the real inference parser remain available:

manimol-infer --help

Training is also exposed through the original staged entry point:

manimol-train --stage stage1 ...
manimol-train --stage torsion ...
manimol-train --stage pbasin ...
manimol-train --stage denoiser ...

Python API

The lightweight numerical utilities are usable without the full dependencies:

import numpy as np
from manimol import density_centrality_select, ensemble_pairwise_prior

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

The checkpoint-backed wrapper delegates to the real inference modules:

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/example",
    dataset="Drugs",
    raw_prefix="geom_drugs",
    split="test",
    protocol="route2_paper",
)

Every run writes manifest.json beside the generated artifacts. It records the protocol, exact argument vector, checkpoint SHA256, data-root path, runtime version, and run status. Denoiser polishing, torsion refinement, xTB relaxation, and energy-window filters remain opt-in.

The current production code requires graph/torsion/conformer dataset records; this release does not claim an unvalidated generate(smiles=...) adapter. That limitation is documented rather than hidden behind a second, simplified implementation.

Repository layout

• src/manimol/: public utilities and thin runtime/CLI wrappers;
• src/models/, src/dataset/, src/utils/: copied active implementation;
• src/*.py: original training and inference entry modules;
• configs/: public configuration templates;
• scripts/: research and reproduction scripts copied from the active project. Some scripts require external datasets, PyMOL/Vina, or private experiment-only modules and are not part of the minimal public API;
• tests/: copied tests from the active implementation;
• checkpoints/: documentation only; weights are not committed;
• MANIMOL_MODULE_AUDIT.md: source-to-method audit.

Development

python -m pip install -e ".[test,build]"
pytest
python -m build
python -m twine check dist/*

Before a public release, run a full inference smoke test with the exact checkpoint and dataset files intended for release. The project license and the repository URL in CITATION.cff are intentionally left for the authors to confirm. LICENSE_PENDING.md must be replaced by the authors' chosen license before publishing a public repository or a final PyPI release.