syneltra 0.1.0b1

Endpoint-conditioned electron-flow mechanism search

SynEltra

A framework for electron-flow mechanism generation from atom-mapped reaction SMILES.

SynEltra builds imaginary transition-state (ITS) graphs from mapped reactions, enumerates electron-pushing trajectories via beam search, ranks them by electronic scoring, and renders them as Nature-style arrow-pushing figures.

---

Installation

conda env create -f env.yaml
conda activate syneltra-env
pip install -e .

Requirements: Python ≥ 3.11, SynKit ≥ 1.3.2, RDKit, NetworkX, NumPy, Matplotlib.

---

Quick Start

One-line trajectory search

from syneltra import rsmi_to_trajs

rsmi = "[CH3:1][Br:2].[OH-:3]>>[CH3:1][OH:3].[Br-:2]"

trajs = rsmi_to_trajs(rsmi)          # sorted best-first
best  = trajs[0]                     # top-ranked mechanism

graphs      = best.graphs()          # RC-context graphs per step (list[nx.Graph])
graphs_full = best.graphs(full=True) # full molecular graphs
transitions = best.transitions       # list[Transition] — arrow sequence

print(f"Found {len(trajs)} trajectories, {len(transitions)} steps in best")
for i, t in enumerate(transitions):
    print(f"  [{i+1}] {t.kind}  {t.src} → {t.dst}")

rsmi_to_trajs parameters

Parameter	Default	Description
rsmi	—	Atom-mapped reaction SMILES (reactants>>products)
family	None	"polar", "pericyclic", or "radical". Auto-inferred when None.
k	0	Context-expansion radius for the workspace builder
max_depth	20	Maximum arrow-step depth for beam search
beam_width	64	Beam width; wider = more diverse trajectories, higher cost
max_results	20	Max trajectories returned before ranking
electronic_mode	"fmo-hsab-resonance"	Electronic scoring mode ("consensus", etc.)

---

Visualization

import matplotlib.pyplot as plt
from syneltra import rsmi_to_trajs, rsmi_to_reaction_bundle
from syneltra.visualization import MechanismVisualizer

rsmi   = "[CH3:1][Br:2].[OH-:3]>>[CH3:1][OH:3].[Br-:2]"
bundle = rsmi_to_reaction_bundle(rsmi)
trajs  = rsmi_to_trajs(rsmi)
best   = trajs[0]
viz    = MechanismVisualizer()

Reactant + ITS panel (default)

fig = viz.visualize_trajectory(
    reactant_graph=bundle.reactant_graph,
    transitions=best.transitions,
    its_graph=bundle.its,
    product_graph=bundle.product_graph,
    title="SN2: MeBr + OH⁻",
)
plt.show()

Step-by-step elementary panels

fig = viz.visualize_trajectory(
    reactant_graph=bundle.reactant_graph,
    transitions=best.transitions,
    its_graph=bundle.its,
    all_graphs=best.graphs(full=True),  # required for this mode
    product_graph=bundle.product_graph,
    title="SN2: step-by-step",
    show_elementary_steps=True,
    arrows_per_step=1,
)
plt.show()

Iterate over all ranked trajectories

for i, traj in enumerate(trajs):
    fig = viz.visualize_trajectory(
        reactant_graph=bundle.reactant_graph,
        transitions=traj.transitions,
        its_graph=bundle.its,
        product_graph=bundle.product_graph,
        title=f"Trajectory {i+1}/{len(trajs)}",
        fade_non_rc=True,
        use_rc_glow=True,
    )
    plt.show()

Key visualize_trajectory options

Parameter	Default	Description
fade_non_rc	False	Fade non-reaction-centre bonds
use_rc_glow	True	Soft halo around changed bonds
show_elementary_steps	False	One panel per arrow group
arrows_per_step	2	Arrows per panel (elementary mode)
show_atom_map	True	Show atom-map badges
step_labels	True	Label individual arrows
gap	3.0	Horizontal spacing between panels

---

Low-level API

from syneltra import (
    rsmi_to_reaction_graphs,   # → (reactant_graph, product_graph)
    rsmi_to_its,               # → ITS nx.Graph
    rsmi_to_reaction_bundle,   # → ReactionGraphBundle
    build_endpoint_states_from_its,
    MechanismEnumerator,
    ITSPlanner,
)

# Build graphs manually
r_graph, p_graph = rsmi_to_reaction_graphs(rsmi)

# Enumerate without ranking
from syneltra import MechanismEnumerator, rsmi_to_its
its = rsmi_to_its(rsmi)
trajs = MechanismEnumerator().enumerate_from_its(its, max_depth=10, beam_width=32)

---

Supported reaction families

Family	Vocabulary	Notes
polar	LP-/B+, B-/LP+, B-/B+	Ionic / heterolytic; default fallback
pericyclic	B-/B+ only	Concerted bond-flow (Diels-Alder, sigmatropic, …)
radical	above + B-/2R•, 2R•-/B+, R•/B-/B+, R•-/H-/R•+	Homolytic / chain processes

---

Project structure

syneltra/
├── chemistry/      # IO, ITS construction, endpoint states
├── constraints/    # Arrow-plan validity constraints
├── core/           # Config, models (Trajectory, StateSnapshot, …)
├── mechanism/      # Operators, planner, vocabulary, pruner
├── ranker/         # Trajectory ranking by electronic score
├── scoring/        # FMO, HSAB, resonance scoring functions
├── search/         # Beam-search enumerator
└── visualization/  # MechanismVisualizer, arrow rendering

Contributing

• Tieu-Long Phan

Publication

SYnEltra:

License

This project is licensed under MIT License - see the License file for details.

Acknowledgments

This project has received funding from the European Unions Horizon Europe Doctoral Network programme under the Marie-Skłodowska-Curie grant agreement No 101072930 (TACsy -- Training Alliance for Computational)