/rdkit-chemdraw-cdxml

name: "rdkit-chemdraw-cdxml"
description: "Read, write, and edit ChemDraw CDX/CDXML files with RDKit's rdkit.Chem.rdChemDraw plus direct XML editing, always paired with a rendered PNG. Parse molecules and reactions from .cdxml/.cdx, write structures with good 2D depiction, and hand-build or modify the parts RDKit cannot write: reaction arrows, plus signs, schemes/steps, and text/labels. Use for reaction schemes, synthesis routes, mechanisms, retrosynthesis, or SI figures. Critical: RDKit writes structures only — round-tripping a reaction through a Mol silently drops arrows and text; this skill shows the XML layer that preserves them. For pure molecular analysis (descriptors, fingerprints, SMARTS) use rdkit-cheminformatics; for multi-format 3D conversion use openbabel."
license: "BSD-3-Clause"

RDKit ChemDraw / CDXML Toolkit

Overview

CDXML is an XML serialization of ChemDraw's object tree (CDX is its binary form). RDKit 2022.09+ exposes an optional Revvity ChemDraw parser at `rdkit.Chem.rdChemDraw` that reads molecules **and** reactions and writes molecule structures. RDKit cannot write **arrows, plus signs, schemes, or text** — those are built or edited at the XML level. This skill covers the full read → depict → annotate → write → modify → render loop.

Output contract

A `.cdxml` is not viewable without ChemDraw, and **you cannot run ChemDraw here** — so the rendered PNG is the only evidence the file is correct. Therefore:

• **Deliver `<name>.cdxml` and `<name>.png` together, matching basenames** — never the CDXML alone. `build_scheme()` and Module 9 write both; the helper raises if the PNG cannot be produced.
• **Validate before delivering** with `scripts/check_scheme.py` (rebuilds each molecule from the drawing, sanitizes, checks mass balance across arrows, and critiques layout). Drive it to zero problems.
• **Report honestly**: "opens correctly in ChemDraw" is never something you tested; stereochemistry is not drawn unless you added it. Offer a plain SMILES list of intermediates for schemes with more than three structures.

When to Use

• Convert SMILES/SDF/Mol into `.cdxml` files that open cleanly in ChemDraw
• Extract molecules or reactions (reactants/agents/products) from `.cdxml` or `.cdx`
• Build a reaction scheme: fragments + arrows + `+` separators + conditions text
• Modify an existing ChemDraw file (relabel, annotate, reposition) without losing its arrows/text
• Batch-generate ChemDraw figures for a reaction dataset or SAR table
• Use `rdkit-cheminformatics` instead for descriptors/fingerprints/SMARTS with no ChemDraw I/O
• For multi-format 3D conversion (MOL2, XYZ, PDB), use `openbabel`; this toolkit is 2D ChemDraw-specific

Prerequisites

• **Python packages**: `rdkit` (2023.03+, built with ChemDraw support), `epam.indigo` (renders CDXML→PNG); `xml.etree.ElementTree` (stdlib) handles all XML editing.
• **Inputs**: SMILES/Mol for writing; `.cdxml` (UTF-8 text) or `.cdx` (binary) for reading.
• **Check before installing.** RDKit is usually already present — run `python -c "import rdkit"` first; inside pixi use `pixi run python ...`.
• **Install `epam.indigo` into the interpreter that runs your code.** A bare `pip install` can land in a different Python than the kernel (e.g. system `/usr/local` vs the pixi env that has rdkit), so `import indigo` still fails even though the install "succeeded" — and no single interpreter then has both rdkit and indigo. In a Jupyter/IPython kernel use `%pip install epam.indigo`; otherwise `python -m pip install epam.indigo` (the running interpreter), or add it to the project env (`pixi add epam.indigo`). For the same reason, **do not run the build/render in a fresh `subprocess`** (`["python", …]` may resolve yet another interpreter) — import the helper and run it in the current process.

python -m pip install epam.indigo   # the running interpreter; or  %pip install epam.indigo  in Jupyter
python -c "from rdkit import Chem; print('ChemDraw write support:', Chem.HasChemDrawCDXSupport())"

Quick Start

from rdkit import Chem
from rdkit.Chem import rdChemDraw, rdDepictor

mol = Chem.MolFromSmiles("CC(=O)Oc1ccccc1C(=O)O")   # aspirin
rdDepictor.SetPreferCoordGen(True)
rdDepictor.Compute2DCoords(mol)                      # coordinates are REQUIRED before writing
cdxml = rdChemDraw.MolToChemDrawBlock(mol, rdChemDraw.CDXFormat.CDXML)   # -> str
open("aspirin.cdxml", "w", encoding="utf-8").write(cdxml)

Core API

Module 1: Reading molecules

`MolsFromChemDrawFile` / `MolsFromChemDrawBlock` handle both `.cdx` and `.cdxml`, returning a tuple of `Mol` (one per fragment).

from rdkit import Chem
from rdkit.Chem import rdChemDraw

mols = rdChemDraw.MolsFromChemDrawFile("drawing.cdxml", sanitize=True, removeHs=True)
for m in mols:
    print(Chem.MolToSmiles(m))

block = open("drawing.cdxml", encoding="utf-8").read()
mols = rdChemDraw.MolsFromChemDrawBlock(block, sanitize=True, removeHs=True)
mols_legacy = Chem.MolsFromCDXML(block)   # CDXML-only fallback, no ChemDraw SDK needed

Module 2: Reading reactions (arrows → reactant/product split)

`ReactionsFromChemDrawBlock` interprets `<step>`/`<arrow>` and returns `ChemicalReaction`s with reactants, agents, and products split out. Note the reaction reader defaults `sanitize=False`.

from rdkit import Chem
from rdkit.Chem import rdChemDraw, rdChemReactions

block = open("reaction.cdxml", encoding="utf-8").read()
for rxn in rdChemDraw.ReactionsFromChemDrawBlock(block, sanitize=True):
    print("reactants:", [Chem.MolToSmiles(m) for m in rxn.GetReactants()])
    print("products :", [Chem.MolToSmiles(m) for m in rxn.GetProducts()])

rxns = rdChemReactions.ReactionsFromCDXMLBlock(block, sanitize=True)   # legacy equivalent

Module 3: Writing molecule structures

`MolToChemDrawBlock` writes one molecule to CDXML (`str`). CDX (binary) write is broken in `rdChemDraw` (`UnicodeDecodeError`); use the legacy writer for CDX byt