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

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

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

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

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