Skip to main content

Reaction Mapping

A reaction mapping job aligns reactant and product atom indices and identifies which atoms and bonds are active in the transformation.

Use this when you need:

  • a reactant to product atom map
  • the active atom set
  • lists of forming and breaking bonds

Your First Mapping​

import atomiverse
from atomiverse import Atoms, JobFailedError, ReactionMapping

atomiverse.configure(api_key="your-api-key")

reactant, product = Atoms.from_reaction_smiles("CCO.O=O>>CC(=O)O")

job = ReactionMapping(
    reactant_atoms=reactant,
    product_atoms=product,
)
job.submit()

try:
    result = job.require_result()
except JobFailedError as exc:
    print(f"Job failed: {exc.failure.error}")
else:
    print("Mapped atoms:", result.mapping)
    print("Active atoms:", result.active_atoms)
    print("Forming bonds:", result.forming_bonds)
    print("Breaking bonds:", result.breaking_bonds)

Input Requirements​

ReactionMapping validates input before submission:

  • reactant and product must contain the same number of atoms
  • reactant and product must have the same elemental composition

Result​

job.require_result() returns a ReactionMappingResult.

FieldTypeDescription
mappingdict[int, int]Reactant atom index to product atom index mapping.
active_atomslist[int]Atom indices involved in bond changes.
forming_bondslist[tuple[int, int]]Bonds present in product but not reactant.
breaking_bondslist[tuple[int, int]]Bonds present in reactant but not product.
mapped_reactant_atomsAtomsReactant structure in mapped index order.
mapped_product_atomsAtomsProduct structure in mapped index order.

Non-blocking Submission​

from atomiverse import State

job.submit(wait=False)
job.refresh()

if job.state == State.DONE:
    print(job.require_result().mapping)
elif job.state == State.FAILED:
    print(job.require_failure().error)