Reaction Network

Generate possible reaction products from a single reactant SMILES by enumerating bond-breaking / bond-forming patterns, filtering candidates with Chemprop machine-learning models, and refining geometries with the Sella optimiser.

The result is a sorted list of product SMILES with relative energies, ready to feed into transition-state search jobs.

from atomiverse import ReactionNetwork, LevelOfTheory

job = ReactionNetwork(
    smiles="C=CC=C",
    level_of_theory=LevelOfTheory(method="gfn2-xtb"),
    num_broken_bonds=3,
)
job.submit()

result = job.require_result()
for product in result.products:
    print(f"{product.smiles}: {product.relative_energy_ev:.3f} eV")

Pipeline Stages

1. Enumeration — Break up to num_broken_bonds bonds and form new ones to generate candidate product SMILES.

2. ML Filtering — Score candidates with two Chemprop models:

   • Local-minimum classifier — discards products unlikely to be stable minima.
   • Enthalpy regression — discards products with high predicted reaction enthalpy.

3. Geometry Refinement — Generate conformers with RDKit/UFF, optimise each with Sella (or LBFGS fallback) using the chosen calculator, and keep the lowest-energy conformer whose connectivity matches the canonical SMILES.

Inputs

• smiles — Canonical SMILES of the reactant molecule.
• level_of_theory — Calculator used for geometry refinement (must support energies and forces).
• num_broken_bonds — Maximum bonds to break during enumeration (2–6, default 4). Higher values explore more of the reaction network but increase combinatorial cost quadratically.

Thresholds

These control which candidates survive each filtering stage. All have sensible defaults derived from the original REVAMP publication.

Parameter	Default	Description
classification_probability_cutoff	0.1	Minimum classifier score to pass the local-minimum filter.
enthalpy_model_cutoff	0.1	Maximum predicted enthalpy (Hartree) to pass the enthalpy filter.
enthalpy_nnp_cutoff	0.82	Maximum relative energy (eV) after geometry refinement.
n_confs	5	Number of RDKit/UFF conformers generated per molecule.
use_sella	True	Use Sella optimiser; falls back to LBFGS if unavailable.
fmax	0.01	Force convergence criterion (eV/Å).
max_steps	300	Maximum optimiser steps per conformer.

Results

• result.reactant_smiles — Canonical SMILES of the input reactant.
• result.products — List of ProductCandidate objects, each with:
  • smiles — Canonical SMILES of the product.
  • relative_energy_ev — Relative energy (product − reactant) in eV.

Products are sorted by relative energy (ascending). Products whose refined energy exceeds enthalpy_nnp_cutoff are discarded.

Compute Resources

Reaction network generation is assigned to a resource tier based on atom count and the num_broken_bonds parameter:

Atoms	Bonds ≤ 4	Bonds ≥ 5
≤ 30	Tier S (1 h)	Tier M (4 h)
≤ 80	Tier M (4 h)	Tier L (12 h)
≤ 150	Tier L (12 h)	Tier XL (24 h)
> 150	Tier XL (24 h)	Tier XL (24 h)

Completed reaction network enumerations are cached by reactant SMILES, level of theory, and all threshold parameters.