Metadata-Version: 2.4
Name: molcraftdiffusion
Version: 1.7.0
Summary: A unified generative AI framework for 3D molecular generation using diffusion models
Author-email: Thanapat Worakul <thanapat.worakul@epfl.ch>
Maintainer-email: Thanapat Worakul <thanapat.worakul@epfl.ch>
License: MIT
Project-URL: Homepage, https://github.com/pregHosh/MolCraftDiffusion
Project-URL: Repository, https://github.com/pregHosh/MolCraftDiffusion
Project-URL: Documentation, https://preghosh.github.io/MolCraftDiffusion/
Project-URL: Bug Tracker, https://github.com/pregHosh/MolCraftDiffusion/issues
Requires-Python: <3.14,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0.0
Requires-Dist: fire
Requires-Dist: decorator
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: networkx
Requires-Dist: matplotlib
Requires-Dist: seaborn
Requires-Dist: pandas
Requires-Dist: scikit-learn
Requires-Dist: tqdm
Requires-Dist: pyyaml
Requires-Dist: omegaconf
Requires-Dist: tensordict
Requires-Dist: rich
Requires-Dist: lightning
Requires-Dist: wandb
Requires-Dist: hydra-colorlog
Requires-Dist: hydra-core>=1.0.0
Requires-Dist: rootutils
Requires-Dist: psutil
Requires-Dist: e3nn
Requires-Dist: torchmetrics
Requires-Dist: biotite
Requires-Dist: datamol
Requires-Dist: ase
Requires-Dist: rdkit
Requires-Dist: pytorch-lightning
Requires-Dist: lightning-utilities
Provides-Extra: data
Requires-Dist: mendeleev; extra == "data"
Requires-Dist: safetensors; extra == "data"
Requires-Dist: dscribe; extra == "data"
Requires-Dist: openbabel>=3.2.0; extra == "data"
Provides-Extra: bio
Requires-Dist: oddt; extra == "bio"
Requires-Dist: biopython; extra == "bio"
Provides-Extra: analyze
Requires-Dist: posebusters>=0.5.1; extra == "analyze"
Requires-Dist: morfeus-ml; extra == "analyze"
Requires-Dist: rmsd; extra == "analyze"
Requires-Dist: open3d; extra == "analyze"
Requires-Dist: openbabel>=3.2.0; extra == "analyze"
Requires-Dist: posecheck; extra == "analyze"
Provides-Extra: flowmol
Requires-Dist: dgl; extra == "flowmol"
Provides-Extra: shape
Requires-Dist: scikit-image; extra == "shape"
Requires-Dist: trimesh; extra == "shape"
Provides-Extra: gpu
Requires-Dist: torch==2.6.0; extra == "gpu"
Requires-Dist: torchvision==0.21.0; extra == "gpu"
Requires-Dist: torchaudio==2.6.0; extra == "gpu"
Requires-Dist: torch_geometric; extra == "gpu"
Requires-Dist: torch_scatter; extra == "gpu"
Requires-Dist: torch_sparse; extra == "gpu"
Requires-Dist: torch_cluster; extra == "gpu"
Requires-Dist: torch_spline_conv; extra == "gpu"
Provides-Extra: cpu
Requires-Dist: torch==2.6.0; extra == "cpu"
Requires-Dist: torchvision==0.21.0; extra == "cpu"
Requires-Dist: torchaudio==2.6.0; extra == "cpu"
Requires-Dist: torch_geometric; extra == "cpu"
Requires-Dist: torch_scatter; extra == "cpu"
Requires-Dist: torch_sparse; extra == "cpu"
Requires-Dist: torch_cluster; extra == "cpu"
Requires-Dist: torch_spline_conv; extra == "cpu"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: isort>=5.10.0; extra == "dev"
Requires-Dist: flake8>=5.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: pre-commit>=2.20.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=7.4; extra == "docs"
Requires-Dist: furo>=2024.1.29; extra == "docs"
Requires-Dist: myst-parser>=3.0; extra == "docs"
Requires-Dist: sphinx-copybutton>=0.5; extra == "docs"
Requires-Dist: sphinx-autoapi>=3.1; extra == "docs"
Requires-Dist: sphinx-sitemap>=2.6; extra == "docs"
Requires-Dist: sphinx-design>=0.6; extra == "docs"
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: pytest-cov>=4.0.0; extra == "test"
Requires-Dist: pytest-mock>=3.8.0; extra == "test"
Dynamic: license-file

<p align="center">
  <img src="./images/logo.png" alt="MolCraftDiffusion" width="480"/>
</p>

<p align="center">
  <a href="https://pypi.org/project/molcraftdiffusion/"><img src="https://img.shields.io/pypi/v/molcraftdiffusion" alt="PyPI"/></a>
  <a href="https://pubs.acs.org/doi/10.1021/jacs.5c19960"><img src="https://img.shields.io/badge/DOI-10.1021/jacs.5c19960-red" alt="DOI"/></a>
  <a href="https://doi.org/10.5281/zenodo.19511401"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.19511401.svg" alt="DOI"/></a>
  <a href="https://huggingface.co/pregH/MolecularDiffusion"><img src="https://img.shields.io/badge/Weights-HuggingFace-yellow" alt="Weights"/></a>
  <a href="https://huggingface.co/pregH/MolecularDiffusion"><img src="https://img.shields.io/badge/Dataset-HuggingFace-yellow" alt="Dataset"/></a>
  <a href="https://preghosh.github.io/MolCraftDiffusion/"><img src="https://img.shields.io/badge/Docs-blue" alt="Docs"/></a>
</p>

---

Three-dimensional molecular generative models place atoms directly in Cartesian space, enabling geometric and physicochemical conditioning. Yet their implementations and evaluation workflows remain fragmented across incompatible repositories.

**One platform brings together a broad range of 3D molecular generators for de novo, property-directed, structure-guided, shape-conditioned, pocket-conditioned, fragment-based, and pharmacophore-driven design.**

MolCraftDiffusion unifies data preparation, training and fine-tuning, guided generation, checkpoint handling, and evaluation behind a modular architecture and consistent CLI. This shared workflow makes diverse generators easier to build, compare, and apply across virtual library construction, chemical-space exploration, inverse design, and structure-based discovery.

<p align="center">
  <img src="./images/overview.png" alt="workflow" width="700"/>
</p>

## One Platform, Many 3D Generation Paradigms

- **De novo generation** of complete 3D molecules
- **Property-directed generation** for inverse molecular design
- **Structure-guided generation** through inpainting, outpainting, and soft reference steering
- **Shape-conditioned generation** around desired molecular geometries
- **Protein-pocket-conditioned generation** for structure-based molecular design
- **Fragment linking and scaffold elaboration**
- **Pharmacophore-conditioned generation**
- **Latent-space diffusion and flow-matching approaches**

These capabilities share the same configuration system, CLI, data pipeline, checkpoint handling, and analysis tools, making it possible to apply and compare different generation paradigms without maintaining separate codebases. See the [supported architectures and their application domains](https://preghosh.github.io/MolCraftDiffusion/architectures.html).

## Features

| | |
|---|---|
| **Broad generator coverage** | Multiple 3D generation paradigms and application domains in one platform |
| **3D-native generation** | Models trained directly in Cartesian space; geometric validity by construction, not augmentation |
| **Extensible architecture** | Multiple backbone families included; adding a new model is a single sub-package drop-in |
| **Steerable generation** | Guide outputs towards target properties or structural constraints without retraining |
| **End-to-end pipeline** | Raw data through training to post-generation analysis, with no glue scripts needed |
| **Unified CLI** | `train · generate · predict · analyze · data`, all from one `MolCraftDiff` entry point |
| **Built-in analysis suite** | Geometry optimisation, validity metrics, quantum-chemical descriptors, and featurisation |

## Installation

```bash
# Create environment
conda create -n molcraft python=3.11 -y
conda activate molcraft
```

**GPU / CUDA:**
```bash
pip install molcraftdiffusion[gpu] \
    --find-links https://data.pyg.org/whl/torch-2.6.0+cu124.html
```

**CPU-only:**
```bash
pip install molcraftdiffusion[cpu] \
    --extra-index-url https://download.pytorch.org/whl/cpu \
    --find-links https://data.pyg.org/whl/torch-2.6.0+cpu.html
```

See the [installation guide](https://preghosh.github.io/MolCraftDiffusion/installation.html) for optional capabilities, platform-specific dependencies, and development setup.

## Usage

Pre-trained diffusion models are available on [Hugging Face](https://huggingface.co/pregHosh/MolecularDiffusion). Starting from a pretrained checkpoint is recommended for downstream tasks.

### CLI

Training and inference commands accept a YAML config followed by optional Hydra-style overrides:

```
MolCraftDiff {train|generate|predict|eval-predict} CONFIG [key=value ...]
```

Analysis and data preparation are direct utility command groups, while generation sweeps accept a sweep config and command-line options.

| Command | Description |
|---|---|
| `train` | Train a diffusion, regression, or guidance model |
| `generate` | Sample molecules from a trained model |
| `generate-sweep` | Run and resume generation parameter sweeps |
| `predict` | Run property prediction |
| `eval-predict` | Evaluate prediction results |
| `analyze` | Post-process and evaluate generated molecules |
| `data` | Data preparation and augmentation utilities |

```bash
MolCraftDiff train configs/example_diffusion_config.yaml
MolCraftDiff generate configs/generate.yaml interference.num_generate=100
MolCraftDiff predict configs/predict.yaml
MolCraftDiff generate-sweep path/to/sweep.yaml --dry-run
MolCraftDiff data prepare compile -s data_dir/ -d dataset.db

MolCraftDiff --help         # all commands
MolCraftDiff train --help   # per-command help
```

### Analysis & Post-processing

```bash
MolCraftDiff analyze metrics generated_molecules/
MolCraftDiff analyze --help
```

The analysis suite covers structural validation, geometry optimisation and comparison, electronic properties, molecular representations, and feature extraction. See the [analysis tutorial](https://preghosh.github.io/MolCraftDiffusion/tutorials/09_analyze.html) for commands and optional dependencies.

## Documentation

- [Installation](https://preghosh.github.io/MolCraftDiffusion/installation.html)
- [Supported architectures and application domains](https://preghosh.github.io/MolCraftDiffusion/architectures.html)
- [Tutorials](https://preghosh.github.io/MolCraftDiffusion/tutorials/index.html)
- [Configuration templates](https://preghosh.github.io/MolCraftDiffusion/config_templates.html)

## Project Structure

```
src/MolecularDiffusion/
├── cli/                         # Shared command-line entry points
├── configs/
│   ├── tasks/<generator>.yaml   # Hydra registration for a generator
│   └── ...                      # Shared data, trainer, engine, and generation configs
├── core/                        # Architecture-agnostic training engines and callbacks
├── data/                        # Shared datasets, loaders, and molecular representations
├── modules/
│   ├── layers/<family>/         # Optional reusable architectural building blocks
│   ├── models/<generator>/      # Isolated model implementation
│   └── tasks/<generator>.py     # Thin adapter to the common task interface
├── runmodes/                    # Generic training, generation, and analysis workflows
└── utils/                       # Geometry, diffusion, graph, and I/O utilities
```

Adding a generator normally requires only its isolated model implementation, a task adapter, and a Hydra task config. The shared CLI, data pipeline, training engines, checkpoint handling, and analysis workflows remain unchanged because they operate through a common task interface.

## Citation

If you use MolCraftDiffusion in your research, please cite:

### MolCraftDiffusion

[![DOI](https://img.shields.io/badge/DOI-10.1021/jacs.5c19960-red)](https://pubs.acs.org/doi/10.1021/jacs.5c19960)

[Modular Framework for 3D Molecular Generation in Computational Chemistry Applications](https://pubs.acs.org/doi/10.1021/jacs.5c19960)

```bibtex
@article{worakul_modular_2026,
	title = {Modular {Framework} for {3D} {Molecular} {Generation} in {Computational} {Chemistry} {Applications}},
	copyright = {https://creativecommons.org/licenses/by/4.0/},
	issn = {0002-7863, 1520-5126},
	url = {https://pubs.acs.org/doi/10.1021/jacs.5c19960},
	doi = {10.1021/jacs.5c19960},
	language = {en},
	urldate = {2026-06-24},
	journal = {Journal of the American Chemical Society},
	author = {Worakul, Thanapat and Azzouzi, Mohammed and Wodrich, Matthew D. and Corminboeuf, Clémence},
	month = jun,
	year = {2026},
	pages = {jacs.5c19960},
}
```

### Related Paper

[![DOI](https://img.shields.io/badge/DOI-10.26434/chemrxiv.15005231/v1-red)](https://chemrxiv.org/doi/full/10.26434/chemrxiv.15005231/v1)

[A Diffusion Framework for Geometrically Valid and Practically Viable 3D Molecular Generation](https://chemrxiv.org/doi/full/10.26434/chemrxiv.15005231/v1)

```bibtex
@article{worakul_diffusion_2026,
	title = {A {Diffusion} {Framework} for {Geometrically} {Valid} and {Practically} {Viable} {3D} {Molecular} {Generation}},
	url = {https://chemrxiv.org/doi/full/10.26434/chemrxiv.15005231/v1},
	doi = {10.26434/chemrxiv.15005231/v1},
	publisher = {American Chemical Society (ACS)},
	author = {Worakul, Thanapat and Corminboeuf, Clémence},
	month = jun,
	year = {2026},
}
```
