molcraftdiffusion 1.7.0

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.

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.

Features

Installation

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

GPU / CUDA:

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

CPU-only:

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 for optional capabilities, platform-specific dependencies, and development setup.

Usage

Pre-trained diffusion models are available on Hugging Face. 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.

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

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 for commands and optional dependencies.

Documentation

• Installation
• Supported architectures and application domains
• Tutorials
• Configuration templates

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

Modular Framework for 3D Molecular Generation in Computational Chemistry Applications

@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

A Diffusion Framework for Geometrically Valid and Practically Viable 3D Molecular Generation

@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},
}