Rule#

The synkit.Rule package treats reaction transformations as first-class objects. It provides a focused toolkit to compose, apply, and modify reaction rules for forward prediction, retrosynthesis, and rule-database workflows. In practice, rules serve as portable graph-rewriting operators that can be analyzed, normalized, and reused across datasets.

Compose

Build new rules by composing smaller transformations. Useful for mechanism-inspired template construction, rule closure, and assembling multi-step edits into a single reusable template.

Apply

Apply rules to molecule/reaction graphs for forward or backward inference. Often used together with synkit.Graph.Matcher strategies to enumerate all valid matches and transformations.

Modify

Edit and normalize rule templates: handle hydrogens, tune context, and adjust matching behavior to improve robustness across heterogeneous data.

Package layout#

Rule utilities are typically organized into three subpackages:

  • synkit.Rule.Compose — rule composition and combination

  • synkit.Rule.Apply — applying rules (often via reactor workflows)

  • synkit.Rule.Modify — editing / normalization (e.g., hydrogen handling, context tuning)

Common patterns#

Compose then apply#

Compose a new rule from existing templates and apply it via a reactor workflow. This is a common pattern for building “macro-templates” that capture a richer transformation while remaining directly applicable to substrates.

Compose rules, then apply the composed rule via a reactor#
 1# Pseudocode (exact function names may vary by version)
 2from synkit.Rule.Compose.rule_compose import compose_rules
 3from synkit.Synthesis.Reactor.syn_reactor import SynReactor
 4
 5r_new = compose_rules(rule_a, rule_b)
 6
 7reactor = SynReactor(
 8    substrate="CC=O.CC=O",
 9    template=r_new,
10    invert=False,
11    strategy="comp",
12)
13products = reactor.smarts_list
14print(products)

Notes

  • Composition is useful when you want a single template that “summarizes” multiple edits.

  • Applying a composed rule typically benefits from strategy='comp' when substrates contain multiple disconnected components.

Context and hydrogen handling#

Real-world datasets often mix implicit/explicit hydrogens, inconsistent aromaticity flags, and different atom-mapping conventions. Utilities in synkit.Rule.Modify (together with related helpers in synkit.Chem and synkit.Graph) help normalize templates and improve matching robustness.

Typical operations include:

  • switching between implicit-H and explicit-H conventions in the reaction center

  • tightening or relaxing context around the reaction center to control rule specificity

  • aligning template conventions with standardization/canonicalization steps

Where to go next#

  • Graph Module — matching engines and isomorphism strategies

  • Chem Module — reaction standardization and mapping validation

  • API Reference — auto-generated API docs for synkit.Rule