Metadata-Version: 2.1
Name: manimol
Version: 0.2.7
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
License-File: LICENSE_PENDING.md
Requires-Dist: numpy >=1.23
Provides-Extra: build
Requires-Dist: build >=1.0 ; extra == 'build'
Requires-Dist: twine >=4.0 ; extra == 'build'
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: 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: test
Requires-Dist: pytest >=7 ; extra == 'test'

<div align="center">
  <img src="docs/assets/manimol-logo.png" width="860" alt="ManiMol molecular conformer generation framework">
  <p><strong>Learning ensemble-derived relational priors for efficient molecular conformer generation</strong></p>
</div>

# 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

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

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

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

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

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

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