Metadata-Version: 2.4
Name: manimol
Version: 0.2.2
Summary: MANIMOL ensemble-relational conformer generation and compact-library construction
Author: MANIMOL developers
Keywords: molecular conformers,conformer generation,chemical informatics
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Chemistry
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE_PENDING.md
Requires-Dist: numpy>=1.23
Provides-Extra: full
Requires-Dist: torch>=2.3; extra == "full"
Requires-Dist: torch-geometric>=2.5; extra == "full"
Requires-Dist: rdkit; extra == "full"
Requires-Dist: scipy>=1.10; extra == "full"
Requires-Dist: tqdm>=4.66; extra == "full"
Requires-Dist: pyyaml>=6; extra == "full"
Provides-Extra: evaluation
Requires-Dist: pandas>=2.0; extra == "evaluation"
Requires-Dist: matplotlib>=3.7; extra == "evaluation"
Requires-Dist: scikit-learn>=1.3; extra == "evaluation"
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Provides-Extra: build
Requires-Dist: build>=1.0; extra == "build"
Requires-Dist: twine>=4.0; extra == "build"
Dynamic: license-file

# 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

```bash
pip install manimol
```

For the checkpoint-backed model pipeline:

```bash
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

```text
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.

### 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:

```bash
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,
dispersion-controlled proposals, deterministic modes, `support_medoid_050`
finite-budget selection, and 200-step 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:

```bash
manimol-infer --help
```

Training is also exposed through the original staged entry point:

```bash
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:

```python
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:

```python
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

```bash
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.
