chemdraw-figures
Draw chemistry figures (reaction schemes, rows of literature reactions, catalytic cycles, metal–π complexes, reaction energy profiles from DFT energies, transition-state structures) as editable ChemDraw CDXML plus a PNG, using the cdxkit Python library in this folder. Use when the user asks to draw, redraw or tidy a ChemDraw figure, scheme, catalytic cycle or energy profile (also in Chinese, e.g. "画 ChemDraw 图", "画个催化循环", "画能量图", "照第 1 章那种风格画", "按刘组规范画"). Styles are optional: use a style from styles/ only when the user names it; if no style is named, ask once which style to use before drawing.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/ruiqi-ding-chem--chemdraw-figure-kit)HTML
<a href="/listings/ruiqi-ding-chem--chemdraw-figure-kit"><img src="/api/listings/ruiqi-ding-chem--chemdraw-figure-kit/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
git clone https://github.com/Ruiqi-Ding-chem/chemdraw-figure-kit.git cd chemdraw-figure-kit pip install -r requirements.txt # numpy, matplotlib, rdkit python examples/02_literature_rows.py # writes examples/out/02_literature_rows.cdxml + .png
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 241 lines
- ---
- name: chemdraw-figures
- description: Draw chemistry figures (reaction schemes, rows of literature reactions, catalytic cycles, metal–π complexes, reaction energy profiles from DFT energies, transition-state structures) as editable ChemDraw CDXML plus a PNG, using the cdxkit Python library in this folder. Use when the user asks to draw, redraw or tidy a ChemDraw figure, scheme, catalytic cycle or energy profile (also in Chinese, e.g. "画 ChemDraw 图", "画个催化循环", "画能量图", "照第 1 章那种风格画", "按刘组规范画"). Styles are optional: use a style from styles/ only when the user names it; if no style is named, ask once which style to use before drawing.
- ---
- # ChemDraw figures with cdxkit
- cdxkit turns a short Python description of a figure into two files: a CDXML that opens in
- ChemDraw and stays fully editable, and a PNG rendered to look like ChemDraw (600 dpi). The
- library is in `cdxkit/` next to this file; the examples in `examples/` are the fastest way to
- see how a figure is built.
- ## 1. Settle content and style first
- - **Content.** Which reactions, structures, conditions and numbers go in, and where each one
- comes from (a paper, the user's own ChemDraw file, their notes). If something is missing,
- ask; never fill in a yield, condition or structure from memory.
- - **Style.** Styles live in `styles/`. Use one only when the user asks for it by name (or
- says e.g. "like Chapter 1", "第 1 章那种风格" → `styles/literature-rows.md`). If the user
- did not name a style, ask once, offering:
- - `acs-plain`: ChemDraw's ACS Document 1996 defaults, black only (`styles/acs-plain.md`);
- - `literature-rows`: one literature reaction per row, a few colours with fixed meanings,
- curved in/out arrows on cycles (`styles/literature-rows.md`);
- - `liu-group`: computational figures, i.e. energy profiles, transition states and
- intermediates, following the Liu group SOPs (`styles/liu-group.md`; also "刘组风格");
- - match a figure or spec the user provides.
- Do not apply colours or layout conventions from a style the user did not choose. For an
- energy profile with no style named, offer liu-group first: it is the only style with rules
- for profiles.
- ## 2. Rules that hold in every style
- 1. **Faithful to the source.** Draw each structure as the source draws it: same orientation,
- same stereochemistry (do not mirror or flip a product "to fit"; a flipped drawing suggests
- a different stereoisomer). Copy conditions and numbers exactly, and say what a number is
- (isolated vs NMR yield, d.r., ee). If the source is not available, say so instead of
- guessing.
- 2. **Consistent within a figure.** The same kind of thing is drawn the same way everywhere
- in one figure (do not show one compound as a structure and another as a condensed formula;
- same abbreviation, same bond length, same label style).
- 3. **Labels read correctly.** A label is written so that the bonded atom touches the bond:
- - bond from the right → `OTIPS` becomes `TIPSO`;
- - bond from the left → start with the bonded atom, e.g. `Fe(CO)<sub>2</sub>Cp*`;
- - bond from above or below → start with the bonded atom and left-align it, e.g.
- `('OBBu<sub>2</sub>', 'left')`.
- Write labels as they should appear. In the CDXML, cdxkit stores a label that sits left of
- its bond in ChemDraw's typed order (`TIPSO` is stored as `OTIPS`), because ChemDraw reads
- labels that way when it opens or saves a file. Do not reverse labels yourself.
- 4. **Look at it.** Always render the PNG and view it before showing it to the user. Check
- for: reversed or misplaced labels, overlapping text, arrows that do not reach, crowded
- conditions, rows that are not centred, empty space on one side.
- 5. **Check the file.** `layout.save()` prints `name: self-check PASS` plus any `WARNING:` lines.
- - PASS means the CDXML reads back with RDKit with the same nodes, bonds and organic skeleton
- (fragments made only of labels such as `[Fe]`, `L`, `Ar` are checked for counts only). It
- says nothing about how the PNG looks.
- - Two warnings concern bonds squeezed between labels; in both cases lengthen the bond
- (`L.ML` for metal bonds) or move the labels:
- - "bond X-Y … is hidden by its labels": the bond is missing from the PNG (it is still in
- the CDXML);
- - "bond X-Y … shows only n pt between its labels": the bond is too short to read. A
- dashed TS bond shorter than about 4 pt looks solid.
- - On Windows with ChemDraw installed, `cdxkit.chemdraw.export()` opens the CDXML in ChemDraw
- and saves a ChemDraw-rendered PNG/CDX. It refuses to run while ChemDraw is already open
- (the user may have unsaved work) and never quits a ChemDraw it did not start.
- 6. **Hand over** the `.cdxml` (for editing in ChemDraw) and the `.png`, and list anything the
- user should still adjust by hand (see Limitations).
- ## 3. Using the library
- ```python
- import sys; sys.path.insert(0, r'<this skill folder>')
- from cdxkit import Scene, mid, register_color
- from cdxkit import layout as L
- from cdxkit.cycle import Cycle
- s = Scene() # ACS 1996: Arial 10 pt, bond 14.4 pt
- m, box = L.place(s, 'C=CCC', 10, 60) # SMILES -> atoms; box = ink bbox
- fe = s.add_atom_label(*L.metal_above(m[0], m[1]), '[Fe]<sup>+</sup>')
- L.eta2(s, fe, m[0], m[1]) # dashed eta-2 line to the C=C midpoint
- L.add_h(s, m[2], deg=-90, color='red') # explicit H (optional colour)
- x = L.arrow_with_conditions(s, box[2] + 12, 60, above=['Et<sub>3</sub>N'], below=['CH<sub>2</sub>Cl<sub>2</sub>'])
- L.place(s, '*CC=CC', x + 12, 60, labels={0: '[Fe]'})
- L.save(s, 'out/figure') # out/figure.cdxml + .png, prints self-check
- ```
- Coordinates are points (1/72 in), y grows downwards; angles are degrees counter-clockwise on
- paper (0 = right, 90 = up).
- **Atoms are found by position.** `add_bond(p1, p2)` connects whatever atom sits at p1/p2
- (within 0.6 pt), so never draw a second fragment on top of an existing one ("draw at the
- origin, move later" goes wrong). Draw each part at its final position, or draw it in its own
- `Scene` and copy it in with `L.merge(s, part, dx, dy)`; `RowFigure` already does this for
- every row. The library warns when an atom lands on another one, and `save()` lists labels
- left without bonds. Text accepts `<sub> <sup> <i> <b>`, `\n`, and HTML entities
- (`′` ′, `π` π, `°` °).
- | Need | Call |
- |---|---|
- | sizes | `L.BL` = 14.4 pt (C–C bond), `L.ML` = 21 pt (metal–ligand bond) |
- | molecule from SMILES | `L.place(s, smi, left, cy, rotate=, flip=, labels={i: 'Ar'}, align_atom=None)` → (AtomMap, ink box); `cy` centres the ink box, or puts atom `align_atom` at height cy (to sit a chain on the arrow axis). `L.place_center(...)`; `L.ink_size(smi)`; `L.orient(smi, i, j, deg, flip=)` gives the `rotate` that points bond i→j at deg (pass the same flip as to place). AtomMaps are snapshots: after moving atoms, look them up again. A metal on a `*` gets a C–C length bond; lengthen it with `L.stretch(s, m[c], m[star], L.ML)`. Put abbreviations on `*` atoms; give stereo in the SMILES, e.g. SMILES `C/C=C(\*)c1ccccc1` (in a Python string `'C/C=C(\\*)c1ccccc1'`). |
- | hand-drawn fragment | `s.add_atom_label(x, y, text, align=None|'left'|'right'|'center')` (None = automatic, the default), `s.add_bond(p1, p2, order=1|2|3, style='solid'|'dashed'|'wedge'|'hash'|'bold', pos=, color=)`, `s.set_bond(p1, p2, ...)`, `L.phenyl(s, p, deg)`, `L.stretch(s, p_fixed, p_move, length)` |
- | colour a label / bond | `s.paint(p, 'navy')` (atom label at p), `s.color_bond(p1, p2, 'red', style='bold')` |
- | point at an angle | `L.pol(p, deg, d=L.BL)` |
- | metal on a π bond | `L.metal_above(a1, a2)`, `L.eta2(s, metal, a1, a2)` |
- | explicit H | `L.add_h(s, p, deg=None, color=None)` (deg=None: open direction) |
- | allene centre dot | `L.allene_dot(s, p)` |
- | arrows | `L.arrow_with_conditions(s, x1, y, above=[...], below=[...], eq=False)`, `s.add_arrow(x1, y1, x2, y2, head='full'|'half'|'none', dashed=, bold=, lw=)` (head='none' = Line tool; bold=True = ChemDraw Bold line), `s.add_arc_arrow(cx, cy, r, a0, a1, head=, head_size=(800, 700, 200))`, `s.add_eq_arrows(...)`, `L.line(s, p, q, dashed=True)` (plain line, not a bond) |
- | chair / boat (six-membered cyclic TS) | `L.chair(center, side=L.ML, mirror=False, flip=False)` → 6 positions in ring order (plain-line textbook chair); `L.boat(center, side=, mirror=, flip=)` → positions of ChemDraw's boat template (draw front edge bold, tip-to-front edges as wedges; see docstring). `L.polygon(center, n, side=)` is for planar rings only |
- | energy profile | see "Energy profiles" below |
- | text | `s.add_text(x, y, text, align=, valign='baseline'|'center', color=, size=)` → ink box; `L.caption_under(s, box, text, dy=)`, `L.plus(s, x, y)`, `L.text_lines(...)`, `L.text_width(text)`, `L.wrap(text, width)` |
- | boxes | `L.fill_box(s, box_or_Mark, pad=4, fill='fill')` (tile behind a structure), `s.add_rect(x, y, w, h, fill=, dashed=, rounded=)`, `L.label_box(s, x_right, y_base, text, fill)`, `s.add_bracket(...)`, `L.via_bracket(s, box)` |
- | colours | palette names `red navy grey fill rule redfill navyfill greyfill darkblue darkred` (`grey` = #797979, `darkblue` #011993 and `darkred` #941100 are the liu-group pathway colours); more with `register_color('teal', '#13786F')` |
- | one row per reaction | `L.RowFigure(width=468, title_position='top'|'left', row_gap=10, rule_color='rule'|None, tag_color=).row(title, draw_fn, tag=, align='center'|'left')` then `.build()`. Each `draw_fn(part)` draws in its own scene at any coordinates; the row is measured, centred and merged in. Titles are bold 10 pt, tags italic. For acs-plain use `rule_color=None`. |
- | combine pieces | `L.merge(s, part, dx, dy)` copies scene `part` into `s` |
- | catalytic cycle | see "Catalytic cycles" below |
- | move / measure a part | `mk = L.Mark(s)` … draw … `mk.bbox()`, `mk.shift(dx, dy)` |
- | output | `L.save(s, base)` → `base.cdxml`, `base.png` + self-check (`s.check_cdxml` needs `s.to_cdxml` first; `save` does both); `cdxkit.chemdraw.export(cdxml, [png, cdx])` |
- ### Metal centres and labels
- - Atom labels are anchored automatically:
- - a label or metal symbol bonded on both sides, or with three or more bonds, is centred on
- the atom (`Ar–Pd–X` with two `PPh3`, `L–Pd<sup>II</sup>–L`);
- - a label whose bond comes from the right is right-aligned (`Fp–CH2`, `TIPSO–`);
- - otherwise it is left-aligned, so the first character sits on the atom (`PPh3` above or
- below a metal).
- Override with `align='left'|'right'|'center'`. A label cannot be anchored on a character in
- its middle (e.g. the Fe of `Cp*Fe(CO)2`); write it so that the bonded atom comes first or
- last.
- - Use `L.ML` for metal–ligand bonds. If two labels end up so close that the bond between them
- would vanish, `save()` warns.
- ### Catalytic cycles
- ```python
- cyc = Cycle(s, cx, cy, r, clockwise=True, hook_radius=17, hook_sweep=72)
- cyc.arc(62, 16) # arc arrow, head at 16 deg (clockwise)
- cyc.hook(54, 'in', 'base') # reagent joins at 54 deg
- cyc.hook(34, 'out', 'BH<sup>+</sup>') # by-product leaves at 34 deg
- cyc.hook(148, 'in', draw_fn) # draw_fn(scene, (x, y)): a structure
- cyc.label(26, 'deprotonation', dist=8, color='navy') # step name inside, next to its arc
- ```
- - A hook touches the cycle at `theta` and curls outwards. For a clockwise cycle the free end
- of an `'in'` hook lies upstream (counter-clockwise of theta) and that of an `'out'` hook lies
- downstream. Pick theta so the free end lands in empty space.
- - The label or structure goes beyond the free end: to its right on the right half of the
- cycle, to its left on the left half, centred near the top and bottom. Force a side with
- `side='left'|'right'|'center'`; `gap=` sets the distance; `head_in='full'` puts a head on an
- 'in' hook.
- - `cyc.label` accepts multi-line text (`'reductive\nelimination'`) and keeps wide text near
- the top and bottom clear of the arc. Increase `dist` if it still touches.
- - Typical sizes with 10 pt text: r = 55–65 pt.
- ### Energy profiles
- ```python
- from cdxkit.energy import EnergyProfile, load_energies, common_sides
- E = load_energies('energies.csv', column='M06/def2-TZVP') # {label: kcal/mol}, see below
- ep = EnergyProfile(energies=E) # liu-group defaults; bars='bonds' optional
- ep.path(['1', 'TS1', ('2', None, dict(add='R<sub>2</sub>C=O')), '3', 'TS3a',
- ('4a', None, dict(add='R<sub>3</sub>SiH', remove='LCuH')), ('5a', None, dict(shift=25))])
- ep.path(['3', 'TS3b', '4b']) # starts at a known label = branches there
- ep.structure('TS1', draw_ts1) # draw_ts1(scene) draws the TS anywhere
- # ep.note('M06/def2-TZVP/SMD(DCE)//B3LYP-D3(BJ)/6-31G(d)') # only if the user asks for it
- ep.save('out/profile') # .cdxml + .png + checks + table of values
- ```
- - **Numbers.** Take them from the user's table, never from memory or from an old figure.
- - The CSV has the label in the first column and one column per method, in kcal/mol relative
- to one reference. Columns whose header starts with `#` are notes; an empty cell or n.a.
- means no value.
- - A step given only by its label is looked up in that table. `('TS1', 12.4)` gives the
- value directly; use it only when there is no table.
- - The same label in two pathways is one point. It must have the same energy in both; give
- different species different labels.
- - **Step options** (on the step, as a dict):
- - `add=`, `remove=`: a reagent entering or a product leaving on the connector to the next
- step;
- - `at=`, `curve='above'|'below'`: where on that connector the curve touches (0 to 1), and
- on which side of it the curve goes. If either is left out, the library tries positions
- and both sides until the curve and its texts touch nothing;
- - `shift=`: a scale break on the connector into this step; this and later steps are drawn
- that many kcal/mol higher;
- - `x=`: the column slot;
- - `side='above'|'below'`: put both texts on that side of the bar;
- - `text=`: how the number is printed, e.g. `'TS2-<i>cis</i>'`;
- - `dh=`: ΔH, printed in parentheses under ΔG.
- - **`EnergyProfile` options:**
- - `columns=1|2`, `span=`, `bar=`, `scale=`: override the automatic layout;
- - `axis=`: the axis text, e.g. `'Δ<i>G</i><sub>sol</sub>\n(kcal/mol)'`;
- - `enthalpies=`: a ΔH table;
- - `bars='lines'|'bonds'`: draw bars and connectors as Line-tool objects (as the SOP text
- says) or as bonds (as in the group's reference figure; connectors then follow a dragged
- bar in ChemDraw).
- - **Structures.** `ep.structure(label, draw_fn_or_smiles, side=None, dx=, dy=, number=True,
- auto=True)` puts TSs above and intermediates below, each with its bold number. It then
- moves the structure further away or sideways until it touches nothing.
- - **`save()` prints:**
- - the RDKit self-check of the structures;
- - an **energy check**: the CDXML is read back, and every bar must be at the right height
- for its value, every value text must sit at its bar, and the heights must follow the scale
- pair by pair. Numbers that belong to no bar are listed.
- - `OVERLAP:` warnings for any text, curve or structure that touches something else. Fix
- them before showing the figure:
- - a curve or its text: `at=` and `curve=` on that step;
- - a bar's value or number: `side=`;
- - a structure: `dx=`/`dy=` or `side=` in `ep.structure`;
- - otherwise: `x=` to move the step to another slot, or a wider `span=`.
- - `NOTE:` lines saying which points had their texts mirrored because their bars are close.
- - the table of values as drawn. Show it to the user next to the figure.
- - **Your own additions.** `ep.add(lambda s, pts: ...)` draws extra items on the profile
- (`pts[label]` gives `x0`, `x1`, `xc`, `y`, `top`, `bottom`). These are kept on every
- `save()` and checked for overlaps. Editing the Scene returned by `build()` does not work,
- because `save()` builds again.
- - **A set of figures** (one per method in a benchmark, or main text plus SI): build the
- profiles, then call `common_sides(ep1, ep2, ...)` before saving them, so that every figure
- mirrors the same points. Their heights still differ with the energies.
- - cdxkit draws new profiles. To put new numbers into a hand-finished ChemDraw profile, edit
- that file instead of redrawing it (see styles/liu-group.md).
- Workflow that works well: write one small script per figure, one function per row or panel;
- render; look at the PNG; adjust coordinates; repeat. Keep the script with the figure so it can
- be regenerated after the user's comments.
- ## 4. Limitations (tell the user when relevant)
- - The PNG is cdxkit's own rendering, made to match ChemDraw; ChemDraw's own rendering can
- differ slightly (label clipping, double-bond offsets, kerning). Use `cdxkit.chemdraw` to get
- a ChemDraw-rendered PNG when exact appearance matters.
- - Labels ChemDraw knows (`TIPSO`, `MeO2C`, `BocHN`) are read by ChemDraw as chemistry. Labels
- that cdxkit cannot split into units the way ChemDraw does (primes such as `Ar′`, `[Fe]`,
- `Bpin`, formulas such as `C5H11`, unknown abbreviations) are stored as shown and marked
- `LabelDisplay="Right"`, so ChemDraw draws them as written but may mark them as uninterpreted.
- - Reactions are drawn as graphics, not as ChemDraw reaction objects.
- - Molecules do not avoid each other automatically; positions come from your coordinates
- (use the returned boxes). Only `EnergyProfile.structure` searches for a free place.
- - Not drawn by cdxkit: radical dots, orbitals, perspective rings with gaps at crossing bonds,
- insets drawn at another scale, several panels in one energy profile. Add them in ChemDraw.
README.md · README · 227 lines
- # chemdraw-figure-kit (cdxkit)
- Draw chemistry figures in Python and get **editable ChemDraw files** (CDXML) plus a matching
- **600 dpi PNG**: reaction schemes, rows of literature reactions, catalytic cycles,
- organometallic π complexes, and reaction energy profiles drawn to scale from DFT energies, in
- ChemDraw's ACS Document 1996 style.
- The repository is also a **Claude Code skill**. With it installed, an AI assistant can draw
- publication figures on request, follow a named house style, and hand back files that open
- and stay editable in ChemDraw.
- | cdxkit's own PNG | the same CDXML opened and rendered by ChemDraw 23 |
- |---|---|
- |  |  |
- |  |  |
- |  |  |
- ## Why
- ChemDraw is the standard for chemistry figures, but drawing by hand is slow to repeat. When a
- reviewer asks you to change the colour of every removed hydrogen, re-centre twenty rows, or
- redraw a catalytic cycle, every figure has to be edited one at a time. cdxkit keeps each figure
- as a short script:
- - **Reproducible:** change one line and regenerate every figure in the same style.
- - **Still ChemDraw:** the output is a real CDXML document, with ACS 1996 settings, molecules
- as fragments, and arrows as ChemDraw arrow objects, so the final touches can be made in
- ChemDraw.
- - **Checked:** each CDXML is read back with RDKit and compared with what was drawn. Problems that
- only show in the picture, such as a bond hidden behind two labels, are reported as warnings.
- For energy profiles, every bar height and every printed value is read back from the file and
- checked against the input energies. On Windows, the file can also be opened by ChemDraw
- itself through COM automation.
- ## Features
- - Molecules from SMILES, laid out by RDKit and scaled to 14.4 pt bonds. You can rotate, mirror
- and add abbreviation labels (`Ar`, `TIPSO`, `[Fe]`). Wedge and hash bonds come from the
- stereochemistry.
- - Hand-drawn fragments for organometallics. Metal–π coordination is a dashed line to a bond
- midpoint, written as a ChemDraw multi-centre attachment. Explicit H atoms are placed in the
- open direction, and an allene centre can be shown as a dot.
- - Text with sub/superscripts, italics and bold, using ChemDraw's label and caption
- conventions.
- - Arrow types: straight, half-headed, equilibrium, dashed, arc, and curved *hook* arrows
- tangent to a catalytic cycle.
- - Boxes, filled tiles, brackets, row separators, and named colours, with your own colours
- added to the CDXML colour table.
- - Layout helpers:
- - place a molecule by the edge of its ink box;
- - draw an arrow long enough for its conditions;
- - stack rows (`RowFigure`) and centre each one;
- - move or measure any part of a scene.
- - Reaction energy profiles (`cdxkit.energy`):
- - layout: one to three pathways drawn to scale (10 kcal/mol = 1 in), branches from shared
- intermediates, mirrored labels for close bars, scale breaks;
- - annotations: curved lines and arrows for reagents entering and products leaving;
- - structures: TS structures above the profile and intermediates below, each moved to a
- free place automatically;
- - checks: the energies are read from a CSV table, written back out of the CDXML and compared,
- and overlaps are reported.
- - Three style guides (`styles/`): plain ACS; *literature-rows* for thesis or review
- background figures; and *liu-group* for computational figures, i.e. energy profiles and TS
- structures, following the Liu group's figure SOPs.
- ## Install
- ```bash
- git clone https://github.com/Ruiqi-Ding-chem/chemdraw-figure-kit.git
- cd chemdraw-figure-kit
- pip install -r requirements.txt # numpy, matplotlib, rdkit
- python examples/02_literature_rows.py # writes examples/out/02_literature_rows.cdxml + .png
- ```
- ## Quick start
- ```python
- from cdxkit import Scene
- from cdxkit import layout as L
- s = Scene() # ACS 1996: Arial 10 pt, bonds 14.4 pt
- m, box = L.place(s, 'C=CCC', 10, 60) # 1-butene; m = {atom index: (x, y)}
- fp = s.add_atom_label(*L.metal_above(m[0], m[1]), 'Fp<sup>+</sup>')
- L.eta2(s, fp, m[0], m[1]) # dashed eta-2 bond to the C=C midpoint
- L.add_h(s, m[2], deg=-90, color='red') # the allylic H that is removed
- x = L.arrow_with_conditions(s, box[2] + 14, 60, above=['Et<sub>3</sub>N'])
- L.place(s, '*CC=CC', x + 12, 60, labels={0: 'Fp'})
- L.save(s, 'out/fp_allyl') # out/fp_allyl.cdxml + .png, self-check PASS
- ```
- Units are points (1/72 in) with y pointing down, as in CDXML. Angles are degrees
- counter-clockwise on paper. Draw at print size, and the figure comes out at ACS sizes when
- inserted at 100 %.
- More in `examples/`:
- - `01_quickstart.py`: a single scheme;
- - `02_literature_rows.py`: one literature reaction per row;
- - `03_catalytic_cycle.py`: a catalytic cycle with hook arrows;
- - `04_energy_profile.py`: an energy profile with two competing pathways (made-up energies);
- - `SKILL.md`: a compact API table.
- ## Reaction energy profiles
- ```python
- from cdxkit.energy import EnergyProfile, load_energies
- E = load_energies('energies.csv', column='M06/def2-TZVP') # label, one column per method
- ep = EnergyProfile(energies=E)
- ep.path(['1', 'TS1', ('2', None, dict(add='R<sub>2</sub>C=O')), '3', 'TS3a', '4a'])
- ep.path(['3', 'TS3b', '4b']) # a branch: starts at the shared point 3
- ep.structure('TS1', draw_ts1) # your drawing function, placed above TS1
- ep.save('out/profile')
- ```
- The layout follows the group SOP described in [`styles/liu-group.md`](styles/liu-group.md):
- - Format: one column (4.5 in) up to 5 structures, two columns (10 in) for 6–10. Bars are
- 0.6 in.
- - Labels: one-decimal values with a true minus sign above each bar, and bold compound numbers
- below.
- - Pathways in black, dark blue and dark red, joined by thin solid connectors.
- `save()` reads the CDXML back and reports `energy check PASS` only if every bar sits at the
- height of its value and every value text sits next to its bar. It also lists numbers that
- belong to no bar and texts or curves that overlap, and prints the table of values as drawn.
- Bars can be ChemDraw Bold lines (default) or bold bonds (`bars='bonds'`), so that connectors
- follow when a bar is dragged in ChemDraw.
- ## Catalytic cycles
- ```python
- from cdxkit.cycle import Cycle
- cyc = Cycle(s, cx=200, cy=140, r=58) # clockwise
- cyc.arc(62, 16) # arc arrow between two intermediates
- cyc.hook(54, 'in', 'base') # reagent joins the cycle tangentially
- cyc.hook(34, 'out', 'BH<sup>+</sup>') # by-product leaves
- cyc.hook(148, 'in', draw_substrate) # a structure instead of a caption
- ```
- Each hook runs on a small circle that touches the cycle from outside, so it merges with the
- cycle's direction instead of meeting it at an angle.
- ## Open in ChemDraw (optional, Windows)
- ```bash
- python -m cdxkit.chemdraw examples/out/03_catalytic_cycle.cdxml cycle_chemdraw.png cycle.cdx
- ```
- This uses ChemDraw's COM automation to open the CDXML and save it again (`.png`, `.cdx`,
- `.emf`). It refuses to run while ChemDraw is already open, so unsaved work cannot be touched,
- and it only quits a ChemDraw instance it started itself.
- ## Use as a Claude Code skill
- ```powershell
- ./install_skill.ps1 # Windows: copies the kit to ~/.claude/skills/chemdraw-figures
- ```
- ```bash
- ./install_skill.sh # macOS / Linux
- ```
- Then ask Claude Code for a figure, e.g. *"redraw this scheme in ChemDraw"*, *"draw the
- catalytic cycle in the literature-rows style"* or *"make the energy profile from energies.csv
- in the liu-group style"*. The skill (`SKILL.md`) tells the assistant three things:
- - **Choose a style first.** Use a style only when you name it; otherwise ask which one you
- want.
- - **Follow rules that hold in every style.** Draw structures as the source does (no flipped
- products), copy numbers exactly and say what kind they are, and keep one drawing convention
- within a figure.
- - **Check the result.** Render, look at the PNG, run the CDXML self-check, and hand back both
- files.
- ## Styles
- - [`styles/acs-plain.md`](styles/acs-plain.md): ChemDraw ACS Document 1996, black only.
- - [`styles/literature-rows.md`](styles/literature-rows.md): background figures for a thesis or
- review chapter.
- - One literature reaction per row, with a bold "Author, year" title.
- - A small palette where each colour has one meaning: removed H and new bond, labels,
- catalyst box, side paths.
- - Curved in/out arrows on catalytic cycles.
- - [`styles/liu-group.md`](styles/liu-group.md): computational figures, following the figure,
- ChemDraw and reaction-energy-profile SOPs of the Liu group (Peng Liu, University of
- Pittsburgh).
- - Dashed bonds only for bonds forming or breaking in a TS; dative bonds in grey.
- - Energy profiles drawn to scale, with pathway colours by rank.
- - Sizing for a single reduction of the whole figure in Word.
- Add your own by writing a new `styles/<name>.md`.
- ## Tests
- ```bash
- python tests/test_examples.py # or: python -m pytest tests
- ```
- The tests do the following:
- - build every example, write it, and read it back with RDKit;
- - read the energy-profile example back for bar heights and values;
- - check energy rounding (half away from zero, never "−0.0") and CSV reading;
- - check that one label given two energies is rejected;
- - check that a value changed in the file is caught by the read-back;
- - check that labels left of their bond are stored in ChemDraw's typed order.
- With ChemDraw installed (Windows), `CDXKIT_CHEMDRAW=1 python tests/test_examples.py` also lets
- ChemDraw open, save and reopen a sheet of labels, and requires the same picture each time.
- ## Limitations
- - The PNG is cdxkit's own rendering, made to match ChemDraw. Label clipping, double-bond
- offsets and kerning differ slightly from ChemDraw's output (compare the gallery above).
- - Labels are written as they should appear (`TIPSO` left of its bond). In the CDXML they are
- stored in ChemDraw's typed order (`OTIPS`), so ChemDraw shows the same label when it opens
- the file and after it saves it. Labels cdxkit cannot split into units the way ChemDraw does
- (`Ar′`, `[Fe]`, `Bpin`, `C5H11`, unknown abbreviations) are stored as shown and marked to be
- drawn as stored; ChemDraw may mark these as uninterpreted.
- - Reactions are drawn as graphics, not ChemDraw reaction objects. Molecules do not avoid each
- other automatically; only structures on an energy profile look for a free place.
- - Not drawn: radical dots, orbitals, perspective rings with gaps at crossing bonds, insets at a
- different scale. Add them in ChemDraw.
- - cdxkit draws new energy profiles. To put new numbers into a hand-finished ChemDraw profile,
- edit that file instead.
- ## License
- MIT, © 2026 Ruiqi Ding. Developed with Claude Code.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.