Reaction roles and chemical exchange

Implementation notes and historical checks. Open the visual guide →.

Reaction roles connect editable molecules to a drawing arrow. They stay attached when objects move, and are saved in the native drawing. Position alone never changes a molecule from a reactant into a product.

Define a reaction

1. Draw or import the molecules and a reaction arrow.
2. Open Properties → Labels & chemistry → Reaction roles…, or Export → Reaction roles & export….
3. Choose the arrow for this step. For several steps, each arrow has its own roles.
4. Select a molecule on the canvas and choose Assign selected molecules under Reactants, Products, or Reagents / catalysts. Selecting one atom assigns its complete connected molecule. You can assign several selected molecules together.
5. Click a structure thumbnail in the inspector to select that participant on the canvas. Reassigning it moves it to the chosen role. Clear selected roles removes its membership without deleting the molecule.

Select reaction selects its arrow, all participants, and associated captions. Native copy/paste and Duplicate retain a complete selected reaction and remap its object IDs. A partial molecule selection is copied as an ordinary drawing fragment.

Role edits are undoable. Remove reaction roles keeps all drawing objects. Deleting an arrow removes its reaction definition; deleting atoms prunes the corresponding membership. Extending an assigned molecule also extends its membership. A bond edit that joins separate participants is rejected: clear their roles first if you intend to combine them. Reversing a defined arrow swaps reactants and products in the same Undo step.

Assistant-generated schemes already contain reactant and product roles, including their coefficients. Reaction conditions remain editable captions. Text written above or below a straight arrow attaches to it, and the arrow keeps itself long enough for the text; see conditions on an arrow. Text conditions do not automatically become chemical reagent structures; draw and assign a reagent when it should be included in reaction data.

Copy a drawn reaction

Cmd/Ctrl+C copies the drawing for ReShiki, ChemDraw, Office and image apps. It supplies no chemical plain text. To paste a structure into a text field such as SciFinder’s, select it and use Cmd/Ctrl+Alt+C. With no selected arrow, this copies molecular SMILES and retains all selected disconnected molecular components. Inspect the receiving editor’s interpretation of a mixture or salt; copying all components does not establish receiver acceptance.

For an unassigned scheme, select all complete participant molecules and exactly one straight forward arrow. Copy-only inference assigns starting materials toward the arrow’s start and products toward its end, including vertical, diagonal and right-to-left layouts. It groups complete connected components and assigns each one once. Molecules touching or crossing the arrow midpoint, unexplained central components, multiple or degenerate arrows, unsupported arrow semantics and missing reaction sides prevent inference. Captions do not automatically become chemical agents.

Existing explicit roles override geometry, including their coefficients and agent membership. An incomplete explicit reaction selection cannot be reinterpreted from its layout. Without the arrow, one complete explicit participant can supply molecular text; partial participants and selections spanning explicit participants are rejected for chemical text even if the selection snapshot has pruned their reaction metadata. Unassigned no-arrow molecules continue to use the molecular copy path.

The inferred roles exist only in the chemical copy. The drawing retains its existing reaction roles. Copy does not move atoms, change the source document or create an Undo entry. Ambiguous or invalid inference leaves the previous clipboard intact and reports the reason. Chemical Copy as choices use the same selection rules and report an error when the requested conversion cannot be prepared.

Cmd/Ctrl+Alt+C for one clear reaction uses bounded ChemDoodle JSON. Aromatic molecules use validated canonical Kekulé bonds with preserved attached hydrogen counts. Agents, non-unit coefficients, atom maps, stereochemistry, radicals, unsupported bonds, collapsed abbreviations and disconnected components grouped into one participant remain outside that JSON format. Save .rsk for the full drawing and use RXN/reaction SMILES when the receiver supports those features.

See the SciFinder handoff guide for CAS Draw’s molecular SMILES field/Add to Editor and ChemDoodle’s reaction Open/Load field. The October 5 check used an optimized arm64 QA build at f648465 with Edge on macOS: ordinary reaction Copy reached ChemDoodle’s Open text field, and Load showed the complete benzene-to-cyclohexane reaction with correct roles. Direct Cmd+V in its drawing canvas inserted an older internal six-atom Cyclohexane instead. CAS Draw’s canvas did not import the no-arrow two-ring SMILES or MOL clipboard data. Real Cmd+V of the two-ring SMILES into its text field followed by Add accepted both molecules. Center Structure revealed the complete Benzene with three double bonds and Cyclohexane with six single bonds; the screenshot showed C6H12 (84.16) . C6H6 (78.11). MOL was checked only for text-field delivery, without Add/conversion. No searches were submitted, and vertical/reversed layouts remain covered locally rather than by these live checks. That build supplied chemical text through ordinary Copy; current builds use Cmd/Ctrl+Alt+C for that text.

Use ReShiki Cmd/Ctrl+Alt+C → Cmd/Ctrl+V into ChemDoodle’s Open text field → Load. Both complete participants and their reactant/product roles were preserved in the tested benzene-to-cyclohexane fixture. PR #144 added this workflow; direct canvas paste and CAS reaction integration are outside this change. The guide records the exact actions, baseline comparison and limits. Local fixtures can be prepared without publishing clipboard data or contacting CAS:

cargo run --locked --example scifinder_clipboard_qa -- /tmp/reshiki-scifinder-clipboard

Import and export

Open .rxn or .rsmi files, or paste RXN text or reaction SMILES into Import. Reaction SMILES uses reactants>agents>products, for example:

CC(=O)O.CCO>OS(=O)(=O)O>CCOC(C)=O.O

The importer lays out editable molecules, separators and an arrow, with chemical agents above the arrow. Participant spacing and plus signs use visible label widths, including hydrogens, subscripts, charges and atom maps; the arrow widens to fit its agent row. Existing molecular coordinates within each RXN participant are retained; page and arrow layout are recreated.

Choose one arrow in the reaction inspector to export it. Export controls remain visible while the participant list scrolls. Both sides must contain a participant.

Format	Retained data	Limits
.rsk	Complete drawing, reaction roles, coefficients, captions, arrow conditions, styles and groups	Use this for continued editing.
RXN V3000	Reactants, products, separate agents, atom maps, supported molecular stereochemistry and atom coordinates	Arrow appearance, captions and page layout are not stored.
Reaction SMILES (.rsmi)	Reactants, products, agents, atom maps and supported molecular stereochemistry	Coordinates and drawing appearance are not stored. Disconnected components can become separate participants when reopened.

Coefficients greater than one export as repeated chemical participants. Repeated mapped participants need distinct atom maps; the exporter rejects duplicate map numbers on one side. Query atoms, enhanced stereo groups, hydrogen interactions, partial and quadruple bonds are not supported by this reaction-exchange workflow and produce an error rather than a flattened structure. The expanded export is limited to 10,000 atoms.

Molecular MOL/SMILES/InChI and current CDXML/CDX drawing exchange do not retain these reaction roles. The native clipboard representation preserves them when pasting a complete reaction into ReShiki. Save .rsk alongside an exchange file to retain the full scheme.

Atom mapping and label placement

Atom maps number the atoms that correspond between reactants and products. You can set them by hand, let Auto-map suggest them, show them on the drawing and align the products to the reactants.

Use atom maps

1. Assign reactants and products first (see Define a reaction). The Atom maps section of the reaction inspector then shows how many atoms are mapped.
2. To set one map, select one atom, type a number in Atom map and choose Set. Clear removes it. You can also right-click an atom and choose Edit atom map… or Clear atom map.
3. To pair two atoms, select one reactant atom and one product atom and choose Pair selected atoms.
4. To map the rest, choose Auto-map. Review atom maps lists each suggested pair, for example Map 1 · C #1 → C #5. Click a row to select the pair in the drawing.
5. Choose Apply maps to keep the suggestion, or Discard.
6. Choose Align mapped structures to turn and move each product so that its mapped atoms line up with the reactants.

Show maps shows or hides the map numbers. Move labels lets you drag each map number; press Escape when you are done. Reset label positions returns them to automatic placement. Atom-label size and font settings also apply to map numbers. Each edit is one Undo step.

Mapped reaction SMILES such as [CH3:1][CH2:2][OH:3]>>[CH3:1][CH:2]=[O:3] import with their maps visible.

Atom map limits

• Auto-map suggests a mapping for you to review. It compares structures only; it does not determine a reaction mechanism.
• Auto-map keeps maps you set. Reagents are not mapped.
• Auto-map needs coefficients of 1 and at most 128 atoms per side. Draw a repeated molecule explicitly before mapping it.
• A map number must be unique on each side of the reaction and must match the element and isotope of its partner.
• Changing the drawing discards an unapplied suggestion.
• RXN and reaction SMILES keep the map numbers. Save a .rsk file to keep custom label positions and styles too.

Atom map implementation notes

A map label derives its text from the atom’s map number and has its own position and style. Show maps controls only the ink; the chemical map numbers stay in the document and in RXN/reaction SMILES export. Custom atom numbers such as Cα remain independent and can appear alongside a map label. Maps are positive integers up to 2147483647; 0 clears a map. Edits check uniqueness on that reaction side and element/isotope agreement with an existing counterpart. Existing different labels must be cleared before pairing.

Auto-map runs in Rust and stays detached from the document until applied. It keeps existing maps as anchors, matches exact elements/isotopes, and excludes agents. It maximizes the number of corresponding atoms, then favors conserved heavy-atom adjacency, all adjacency, unchanged bond classes, fewer changed atom environments, and smaller charge/H/radical differences. Bond order, charge, attached hydrogens, degree and ring membership can change in a reaction and never exclude candidate pairs. Coordinates and stereochemistry are preserved; they are not used to infer a reaction mechanism.

The review states whether it found one best map under this graph score (One best mapping under the graph score), several equal-best maps (Several mappings tie under the graph score), or a search-budget result whose optimality and uniqueness are unknown. A budget result still contains a complete feasible atom correspondence. Unmatched atoms keep their existing maps or stay unmapped; omitted coproducts are not invented.

The default search limits are 128 explicit atoms per side, 768 bonds, 16384 candidate pairs, 250000 search states, and 20000000 charged matching work units. Work is charged before candidate comparisons, maximum-matching scans, scoring, bounds and search choices. If that budget ends before a full feasible incumbent exists, Auto-map reports an error and creates no proposal. Chemical validation/preparation is bounded by the input caps; this budget is not a wall-clock deadline. A mapping edit also checks other reaction steps containing a shared intermediate, including their coefficients, so it cannot make an earlier exportable repeated participant unmappable. Same-side duplicate map classes can be valid imported SMILES data; the editor preserves them, displays them, and asks for unique anchors before Auto-map. The reaction exporter rejects duplicate maps on one side.

Map label offsets and styles survive .rsk save, Undo, copy within ReShiki and figure export. Align mapped structures rotates and translates each whole product participant toward its mapped reactant coordinates, using a common offset for the reaction’s drawing lanes. It preserves bond lengths, depth, wedge appearance, chemical stereo and connectivity, without reflections or scaling. Molecules without a mapped counterpart stay in place. Alignment does not create maps.

Concrete reaction SMILES and reaction SMARTS serve different purposes: query expressions such as [N!0H:3] are not concrete molecular atoms. The Daylight SMILES specification explains atom classes, and the RDKit Book explains reaction SMARTS. The mapped reaction example motivates correspondence and coordinated drawing. Gaussian/TS export remains future work; this editor supplies persistent chemical atom maps and visible labels.

Current limits and verification

Persistent reactions use explicit role assignment and chemical exchange. The bounded single-arrow inference above applies only to copying; broader reaction interpretation, whole-scheme cleanup, balancing, yields, quantities, and coefficient editing in the inspector remain future work. The existing cleanup command still operates only on your selected atoms or molecules and leaves the reaction arrow and unselected molecules fixed.

Regression checks cover role reassignment, native save/copy/delete, ID remapping, growth, rejected cross-role joins, undo/redo, arrow reversal, assistant roles, coefficients, selected-step export, atom maps, tetrahedral and E/Z stereochemistry, cleanup, and abbreviation replacement. Offscreen native UI checks cover 1280 × 820 and 1040 × 680 layouts and export-button mouse events without opening a desktop window. The 0.6 desktop walkthrough also inspected the native role cards for an esterification with two reactants and two products. Windows/Office images remain from the earlier verification.

Reaction parsing, layout and export run in Rust. Independent tests compare the results with the original RDKit reaction APIs.