polymerist.rdutils.reactions

Utilities for representing and modelling chemical reactions between RDKit molecules

Submodules

• polymerist.rdutils.reactions.assembly
• polymerist.rdutils.reactions.fragment
• polymerist.rdutils.reactions.reactexc
• polymerist.rdutils.reactions.reactinfo
• polymerist.rdutils.reactions.reactions
• polymerist.rdutils.reactions.reactors

Attributes

IBIS

Classes

AnnotatedReaction	RDKit ChemicalReaction subclass with additional useful information about product atom and bond mappings and reaction naming
AtomTraceInfo	For encapsulating information about the origin and destination of a mapped atom, traced through a reaction
BondTraceInfo	For encapsulating information about bonds which are between mapped atoms and which change during a reaction
BondChange	For indicating how a bond which changed in a reaction was altered
IntermonomerBondIdentificationStrategy	Abstract base for Intermonomer Bond Identification Strategies for fragmentation during in-silico polymerization
ReseparateRGroups	IBIS which cleaves any new bonds formed between atoms that were formerly the start of an R-group in the reaction template
CutMinimumCostBondsStrategy	Subtype of IBIS which chooses bonds as solutions to minimum graph cut problem
PolymerizationReactor	Reactor which exhaustively generates monomers fragments according to a given a polymerization mechanism
ReactionAssembler	Class for producing reaction templates from reactants, bond derangements

Package Contents

class polymerist.rdutils.reactions.AnnotatedReaction(*args, **kwargs)

Bases: rdkit.Chem.rdChemReactions.ChemicalReaction

RDKit ChemicalReaction subclass with additional useful information about product atom and bond mappings and reaction naming Initialization must be done either via AnnotatedReaction.from_smarts, AnnotatedReaction.from_rdmols, or AnnotatedReaction.from_rxnfile

RXNNAME_LINE_NO: ClassVar[int] = 1

RXNNAME_RE: ClassVar[re.Pattern]

classmethod from_smarts(rxn_smarts: str) → AnnotatedReaction

Instantiate reaction from mapped SMARTS string

to_smarts() → str

Export reaction as mapped SMARTS string

property smarts: str

Mapped SMARTS string representation of reaction

to_smiles() → str

Export reaction as mapped SMILES string

property smiles: str

Mapped SMILES string representation of reaction

classmethod from_rdmols(reactant_templates: Iterable[rdkit.Chem.rdchem.Mol], product_templates: Iterable[rdkit.Chem.rdchem.Mol], agent_templates: Iterable[rdkit.Chem.rdchem.Mol] | None = None) → AnnotatedReaction

For instantiating reactions directly from molecules instead of SMARTS strings

classmethod rxnname_from_rxnfile(rxnfile_path: str | pathlib.Path) → str

Extract the reaction name from a (properly-formatted) .RXN file

property rxnname: str

A string handle associated with this reaction

classmethod from_rxnfile(rxnfile_path: str | pathlib.Path) → AnnotatedReaction

For instantiating reactions directly from MDL .rxn files

to_rxnfile(rxnfile_path: str | pathlib.Path, wilds_to_R_groups: bool = True) → None

Save reaction to an MDL .RXN file. Replaces ports with R-groups to enable proper loading

property mapped_atom_info_by_map_number: dict[int, polymerist.rdutils.reactions.reactinfo.AtomTraceInfo]

Provenance info about the reactant origin and product destination of all mapped atoms, keyed by atom map numbers

property mapped_atom_info: set[polymerist.rdutils.reactions.reactinfo.AtomTraceInfo]

Compile provenance info about the reactant origin and product destination of all mapped atoms

property mapped_atom_info_by_product_idx: dict[str, set[polymerist.rdutils.reactions.reactinfo.AtomTraceInfo]]

Sets of provenance info about the reactant origin and product destination of all mapped atoms grouped by the indices of the products in which they appear

property reactive_atom_info: dict[int, polymerist.rdutils.reactions.reactinfo.AtomTraceInfo]

Compile reactant origin and product destination of all mapped atoms which are changed by the reaction

property mapped_bond_info: set[polymerist.rdutils.reactions.reactinfo.BondTraceInfo]

All provenance info on how bonds between mapped atoms (at least one of which is reactive) change over the reaction

property mapped_bond_info_by_change_type: dict[str | polymerist.rdutils.reactions.reactinfo.BondChange, set[polymerist.rdutils.reactions.reactinfo.BondTraceInfo]]

Mapped bond provenance information, grouped by the types of bond changes each bond experienced

property mapped_bond_info_by_product_idx: dict[str | polymerist.rdutils.reactions.reactinfo.BondChange, set[polymerist.rdutils.reactions.reactinfo.BondTraceInfo]]

Mapped bond provenance information, grouped by the index of the product the bond ends up in

compile_functional_group_inventory(labeled_reactants: dict[L, rdkit.Chem.rdchem.Mol]) → polymerist.genutils.sequences.discernment.SymbolInventory[int, L]

Construct an inventory of numbers of functional groups (reactant templates) found in an ordered pool of reactant Mols, which can be evaluated as a DISCERNMENT-type problem to determine valid reactant ordering(s), if some exist

Isomorphisms to the DISCERNMENT problem in this instance are as follows:

“symbols” <-> indices of functional groups, as-defined by reactant templates “target word” <-> the sequence of indices [n-1] = [0, 1, …, n-1] where “n” is the number of reactant templates “magazine” <-> an ordered collection of reactant molecules, which may contain any number of functional groups apiece each “word labels” <-> the output of the provided labeling method on the reactant Mol or, if no labeling method is provided, the index of the reactant in the sequence

enumerate_valid_reactant_orderings(reactant_pool: Iterable[rdkit.Chem.rdchem.Mol] | Mapping[L, rdkit.Chem.rdchem.Mol], labeling_method: Callable[[rdkit.Chem.rdchem.Mol], L] | None = None, as_mols: bool = True, allow_resampling: bool = False, deterministic: bool = True) → Generator[None | tuple[L] | tuple[rdkit.Chem.rdchem.Mol], None, None]

Enumerates all orderings of reactants compatible with the reactant templates defined in this reaction

Yields: * a single NoneType if no such ordering exists * tuples of Chem.Mol objects if as_mols=True * tuples of molecule labels if as_mols=False. Labels can be:

** Indices of molecules in-sequence if labeling_method is not provided ** Any molecule label is labeling_method is provided;

Note that the labels provided must be valid keys for indexing reactant_pool to support as_mols

If allow_resampling=False, each reactant will only be allowed to contribute exactly 1 of its functional groups 1 to any solution

valid_reactant_ordering(reactant_pool: Sequence[rdkit.Chem.rdchem.Mol], as_mols: bool = True, allow_resampling: bool = False, deterministic: bool = True) → None | tuple[int] | tuple[rdkit.Chem.rdchem.Mol]

Get first ordering of reactants compatible with the reactant templates defined in this reaction

Yields: * a single NoneType if no such ordering exists * a tuple of Chem.Mol objects if as_mols=True * a tuple of indices of reactants in the passed sequence if as_mols=False

If allow_resampling=False, each reactant will only be allowed to contribute exactly 1 of its functional groups 1 to any solution

has_reactable_subset(reactant_pool: Sequence[rdkit.Chem.rdchem.Mol], allow_resampling: bool = False) → bool

Determine if a sequence of reactants Mols contains any subset of Mols which are compatible with the reactant templates defined by this reaction If allow_resampling=False, each reactant will only be allowed to contribute exactly 1 of its functional groups 1 to any solution

validate_reactants(reactants: Sequence[rdkit.Chem.rdchem.Mol], allow_resampling: bool = False) → None

Check whether a collection of reactant Mols can be reacted with this reaction definition

reactants_are_compatible(reactants: Sequence[rdkit.Chem.rdchem.Mol], allow_resampling: bool = False) → bool

Determine whether a collection of reactants can be reacted with this reaction or not

static apply_atom_info_to_product(product: rdkit.Chem.rdchem.Mol, product_atom_infos: Iterable[polymerist.rdutils.reactions.reactinfo.AtomTraceInfo], reactants: Sequence[rdkit.Chem.rdchem.Mol], apply_map_labels: bool = True) → None

Transfer props and (if requested) map number information from atoms in reactant Mols to their corresponding atoms in a product Mol Acts in-place on the “product” Mol instance

static apply_bond_info_to_product(product: rdkit.Chem.rdchem.Mol, product_bond_infos: Iterable[polymerist.rdutils.reactions.reactinfo.BondTraceInfo]) → None

Mark any changed bonds with bond props and clean up bond type info in places where bonds get modified Acts in-place on the “product” Mol instance

react(reactants: Sequence[rdkit.Chem.rdchem.Mol], repetitions: int = 1, keep_map_labels: bool = True, _suppress_reactant_validation: bool = False) → Generator[rdkit.Chem.rdchem.Mol, None, None]

Execute reaction over a collection of reactants and generate product molecule(s) Does not require reactants to match the ORDER of the expected reactant templates by default (only to have the correct number of reactants)

class polymerist.rdutils.reactions.AtomTraceInfo

For encapsulating information about the origin and destination of a mapped atom, traced through a reaction

map_number: int

reactant_idx: int

reactant_atom_idx: int

product_idx: int

product_atom_idx: int

class polymerist.rdutils.reactions.BondTraceInfo

For encapsulating information about bonds which are between mapped atoms and which change during a reaction

map_nums: tuple[int, int] | frozenset[int]

product_idx: int | None

product_bond_idx: int | None

bond_change_type: str | BondChange

initial_bond_type: float | rdkit.Chem.BondType

final_bond_type: float | rdkit.Chem.BondType

class polymerist.rdutils.reactions.BondChange

Bases: enum.StrEnum

For indicating how a bond which changed in a reaction was altered

ADDED

DELETED

MODIFIED

UNCHANGED

polymerist.rdutils.reactions.IBIS

class polymerist.rdutils.reactions.IntermonomerBondIdentificationStrategy

Bases: abc.ABC

Abstract base for Intermonomer Bond Identification Strategies for fragmentation during in-silico polymerization

locate_intermonomer_bonds(product: rdkit.Chem.Mol) → Generator[int, None, None]

Generates the indices of all identified inter-monomer bonds by molecule, no more than once each

produce_fragments(product: rdkit.Chem.Mol, separate: bool = True) → rdkit.Chem.Mol | tuple[rdkit.Chem.Mol]

Apply break all bonds identified by this IBIS algorithm and return the resulting fragments

class polymerist.rdutils.reactions.ReseparateRGroups

Bases: IntermonomerBondIdentificationStrategy

IBIS which cleaves any new bonds formed between atoms that were formerly the start of an R-group in the reaction template

class polymerist.rdutils.reactions.CutMinimumCostBondsStrategy(base_bond_cost: float | None = None, bond_discounts: dict[str, tuple[int, Callable[[rdkit.Chem.Mol], tuple[int, int]]]] | None = None, bond_cost_keyword: str | None = 'cost_to_cut', max_bonds_per_cut: int = 1, *args: P, **kwargs: P)

Bases: IntermonomerBondIdentificationStrategy

Subtype of IBIS which chooses bonds as solutions to minimum graph cut problem All bonds in a molecule are given some base cost to cut, then a discount is applied to some bonds by specified conditions

Cuts are then made (no more than once) on the lowest cost bond(s) separating each pair of R-groups

base_bond_cost = None

bond_discounts = None

bond_cost_keyword = 'cost_to_cut'

max_bonds_per_cut = 1

class polymerist.rdutils.reactions.PolymerizationReactor

Reactor which exhaustively generates monomers fragments according to a given a polymerization mechanism

rxn_schema: polymerist.rdutils.reactions.reactions.AnnotatedReaction

fragment_strategy: polymerist.rdutils.reactions.fragment.IBIS

propagate_pooled(monomers: Iterable[rdkit.Chem.rdchem.Mol], rxn_depth_max: int = 5, allow_resampling: bool = False, clear_map_labels: bool = True, clear_dummy_labels: bool = False, sanitize_ops: rdkit.Chem.rdmolops.SanitizeFlags = SANITIZE_ALL, aromaticity_model: rdkit.Chem.rdmolops.AromaticityModel = AROMATICITY_MDL) → dict[polymerist.smileslib.cleanup.Smiles, rdkit.Chem.rdchem.Mol]

Discovers and enumerates all possible repeat unit fragments formable from a given polymerization step reaction mechanism

Propagation acts on a pool of fragments reactants (initially just the “monomers” passed in) and proceeds in rounds where all reactible subsets are adducted and fragmented, and any previously-unseen fragments are added to the pool Enumeration halts either when no new fragments have been found or the set maximum number of reaction step(s) is reached

“Uniqueness” of a fragment is assessed by its RDKit-canonicalized SMILES representation

propagate(monomers: Sequence[rdkit.Chem.rdchem.Mol], clear_map_labels: bool = True, sanitize_ops: rdkit.Chem.rdmolops.SanitizeFlags = SANITIZE_ALL, aromaticity_model: rdkit.Chem.rdmolops.AromaticityModel = AROMATICITY_MDL) → Generator[tuple[tuple[rdkit.Chem.rdchem.Mol, Ellipsis], tuple[rdkit.Chem.rdchem.Mol, Ellipsis]], None, None]

Keep reacting and fragmenting a pair of monomers until all reactive sites have been reacted Returns fragment pairs at each step of the chain propagation process

class polymerist.rdutils.reactions.ReactionAssembler

Class for producing reaction templates from reactants, bond derangements

reactive_groups: Iterable[rdkit.Chem.rdchem.Mol]

byproducts: Iterable[rdkit.Chem.rdchem.Mol] = []

bond_derangement: dict[int, tuple[int, int]]

rxn_name: str = ''

property reactants: rdkit.Chem.rdchem.RWMol

Combine cached reactive groups into single, contiguously-numbered Mol for manipulation

products(show_steps: bool = False, sanitize_ops: rdkit.Chem.rdmolops.SanitizeFlags = SANITIZE_ALL, bond_breakage_marker: str = '--x->', bond_formation_marker: str = '---->') → rdkit.Chem.rdchem.Mol

Generate the product template defined by the provided reactants and bond derangement

products_by_importance(combined: bool = True, show_steps: bool = False, sanitize_ops: rdkit.Chem.rdmolops.SanitizeFlags = SANITIZE_ALL) → tuple[rdkit.Chem.rdchem.Mol | None | list[rdkit.Chem.rdchem.Mol], rdkit.Chem.rdchem.Mol | None | list[rdkit.Chem.rdchem.Mol]]

Partition reaction products into major and minor/byproducts, each returned as a single Combined Mol

property byproduct_map_nums: tuple[set, set]

Partitions map numbers present in the product(s) by whether or not they belong to a collection of side products Returns a set of map numbers NOT in a side product and set set which are

property byproduct_relabeling: dict[int, int]

Determine a relabeling of the N map numbers in the reaction template which are not any of the given side products Relabeling is in standard form, i.e. new labels are taken from the first N natural numbers with the order of labels preserved

assemble_rxn(show_steps: bool = False, sanitize_ops: rdkit.Chem.rdmolops.SanitizeFlags = SANITIZE_ALL) → polymerist.rdutils.reactions.reactions.AnnotatedReaction

Assemble MDL rxn template from information stored in self