cmxflow

cmxflow 🧪

Build cheminformatics and computational chemistry pipelines with composable blocks. Tune end-to-end with Bayesian Optimization. Or ask an LLM agent to do it.

Quick examples

Prepare ligands for docking

from cmxflow import Workflow

from cmxflow.sources import MoleculeSourceBlock from cmxflow.operators import ( MoleculeStandardizeBlock, IonizeMoleculeBlock, EnumerateStereoBlock, ConformerGenerationBlock, ) from cmxflow.sinks import MoleculeSinkBlock

Standardize → ionize (pH 6.4–8.4) → enumerate stereo → generate 3D conformers

workflow = Workflow() workflow.add( MoleculeSourceBlock(), MoleculeStandardizeBlock(), IonizeMoleculeBlock(), EnumerateStereoBlock(), ConformerGenerationBlock(), MoleculeSinkBlock(), ) workflow("library.smi", "prepared.sdf")

Dock a congeneric series

Pure-Python docking. Free docking is the default (index_poses=False); scaffold-indexed mode caches poses by Bemis–Murcko scaffold for ~3× faster throughput on congeneric series with consistent pose alignment.

from cmxflow import Workflow

from cmxflow.sources import MoleculeSourceBlock from cmxflow.operators import ConformerGenerationBlock, MoleculeDockBlock from cmxflow.sinks import MoleculeSinkBlock from cmxflow.utils.parallel import make_parallel

workflow = Workflow() workflow.add( MoleculeSourceBlock(), ConformerGenerationBlock(), make_parallel( MoleculeDockBlock( receptor="receptor.pdb", site_reference="crystal_ligand.sdf", index_poses=True, # omit for free docking ) ), MoleculeSinkBlock(), ) workflow("library.smi", "docked.sdf")

Tune a ligand-based virtual screen

from cmxflow import Workflow

from cmxflow.sources import MoleculeSourceBlock from cmxflow.operators import MoleculeSimilarityBlock from cmxflow.scores import EnrichmentScoreBlock from cmxflow.opt import Optimizer

Rank a library by 2D similarity to a known active, then tune the

fingerprint end-to-end to maximize enrichment AUC.

workflow = Workflow() workflow.add( MoleculeSourceBlock(), MoleculeSimilarityBlock(queries="crystal_ligand.sdf"), EnrichmentScoreBlock(target="active"), )

opt = Optimizer(workflow, "benchmark.csv") opt.optimize(n_trials=30, direction="maximize")

print(f"Best enrichment AUC: {opt.best_score:.3f}") print(opt.best_params)

Best enrichment AUC: 0.836

{'fingerprint_type': 'morgan', 'similarity_metric': 'sokal', 'radius': 2, 'nbits': 2545}

The four fingerprint parameters above are searched automatically — every block exposes its mutable parameters to the optimizer.

Or build it conversationally via an LLM agent

claude mcp add cmxflow -- cmxflow-mcp

*"How many of the molecules in library.csv pass Lipinski's rules?"*

*"I need to build a ligand-based virtual screening workflow. I'm not sure if 2D or 3D is better. Can you optimize two workflows?"*

*"Dock the molecules in hits.csv against receptor.pdb with crystal_ligand.sdf as a reference."*

The agent can build, run, *and* optimize workflows. See Using with Claude for full transcripts.

What's in the box

• 15+ blocks for sourcing, transforming, filtering, clustering, scoring, and docking molecules
• Bayesian optimization of pipeline parameters via Optuna
• Parallel execution for compute-heavy blocks (conformer generation, docking)
• Workflow serialization for save / load / reuse
• An MCP server with five tools: build_workflow, run_workflow, optimize_workflow, manage_workflows, view_structures

Install

pip install cmxflow

MCP server

claude mcp add cmxflow -- cmxflow-mcp

Optional: PyMOL

Required only for the view_structures MCP tool (3D visualization):

conda install -c conda-forge pymol-open-source

Documentation

• Docs site
• Block catalog
• Using with Claude — agent transcripts
• examples/basic_usage.ipynb — full tutorial
• examples/docking/docking.ipynb — docking walkthrough (ILS, scaffold-indexed, and template modes)

Project

MIT licensed. See CONTRIBUTING.md and RELEASING.md.