reaction-atom-mapping

name	reaction-atom-mapping
description	Map atoms and changed bonds for a complete reaction with RXNMapper. Use for reactant/product correspondence and reaction-centre audits, not target-only retrosynthesis or feasibility.
license	MIT
origin	openai4s
capabilities	{"network":{"mode":"raw_required","domains":[]}}
metadata	{"third_party":[{"kind":"model","name":"RXNMapper","license":"MIT","terms_url":"https://github.com/rxn4chemistry/rxnmapper/blob/main/LICENSE"}]}

Reaction atom mapping

Answer one scientific question: for a reaction whose reactant and product sides are already specified, which atoms correspond across the transformation? Changed bonds derived from that mapping define a machine-readable reaction centre. This task does not propose precursors and does not establish feasibility.

Use RXNMapper, an attention-guided ALBERT mapper distributed with a local Python API and a mapping confidence value.

Install and run

Install it in the optional chemistry environment:

conda create -n rxnmapper python=3.11 -y
conda run -n rxnmapper python -m pip install "rxnmapper[rdkit]==0.4.3"

Select that interpreter in its own OpenAI4S Python Cell. The switch is applied before the following Cell, so do not combine this call with the import:

host.env.use("rxnmapper")

After the switch succeeds, run the mapping code in a new Cell:

from rxnmapper import BatchedMapper

mapper = BatchedMapper(batch_size=32)
reaction = "CCBr.OCC>>CCOCC"
record = next(mapper.map_reactions_with_info([reaction]))
print(record["mapped_rxn"], record["confidence"])

Outside a Web session, where host.env.use(...) is unavailable, save the same code as a workspace script and execute it with conda run -n rxnmapper python. Do not run the bare import in the original kernel after installing into another environment.

Use BatchedMapper for campaigns because it handles invalid records without aborting the whole batch. Keep the original reaction string alongside the mapped result.

For OpenAI4S, create a manifest from the reviewed RXNMapper 0.4.3 wheel SHA in reaction_model_deployment.UPSTREAM_DISTRIBUTIONS, then call ReactionModelBackend("rxnmapper", ...) with a python_command that uses the external prefix. The foreign worker emits mapped reactions, confidence, stable atom correspondences, failures, runtime package versions, and the exact manifest fingerprint. It never downloads a model during inference.

Scenario 3 benchmark contract

Use ../retrosynthesis_planning/atom_mapping_benchmark.py for curated blind evaluation. Public inputs must be map-free. The adapter must emit the mapped reaction plus explicit stable reactant/product atom correspondences; the normalizer checks conservation, duplicate/unmapped atoms and changed bonds. Private scoring accepts pre-frozen symmetry-equivalent correspondences and excludes explicitly ambiguous reactions from whole-reaction exact accuracy, while still reporting changed-bond F1 for them.

Derive the reaction centre

Parse the mapped reactant and product sides with RDKit. Build bond dictionaries keyed by sorted atom-map-number pairs, with bond type as the value. Report:

• bonds present only on the reactant side as broken;
• bonds present only on the product side as formed;
• pairs present on both sides with a changed bond order;
• mapped atoms missing from either side;
• unmapped atoms and duplicate map numbers.

Do not silently repair unbalanced reactions, strip reagents, or move molecules between reaction fields. Those choices change the scientific object being mapped and must be recorded as preprocessing.

Acceptance checks

• Both >> sides are present and parseable.
• Atom-map numbers are unique within each side after mapping.
• Every changed bond references mapped atoms.
• Mapping confidence is preserved as the model's own score, not converted to a probability that the proposed reaction is correct.
• For evaluation, use atom-mapping and bond-change ground truth only after the predicted mapping is fixed.

Output contract

Return original reaction SMILES, mapped reaction SMILES, mapper confidence, formed/broken/order-changed bonds, parse warnings, unmapped atoms, model version, and environment provenance.

Failure modes

Symptom	Action
input contains only a product	Stop and use single-step-retrosynthesis; atom mapping requires both sides.
mapper returns >> or an empty record	Mark the reaction invalid and preserve the original input.
confidence is low	Keep the mapping for review but do not use its reaction centre as an unquestioned label.
atom conservation fails	Report imbalance separately; do not force a cosmetically balanced mapping.

Primary source: https://github.com/rxn4chemistry/rxnmapper.