Metadata-Version: 2.4
Name: manimol
Version: 0.2.0
Summary: MANIMOL ensemble-relational conformer generation and compact-library construction
Author: MANIMOL developers
License: MIT License
        
        Copyright (c) 2026 MANIMOL developers
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Keywords: molecular conformers,conformer generation,chemical informatics
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Chemistry
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.23
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"
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"
Dynamic: license-file

# 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 precision2r \
  --output_dir results/manimol
```

The package default is a 15-fold candidate oversampling factor. Override it
with `--oversample_factor` 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="precision2r",
)
```

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.
