Reaction#

The Reaction class defines a linkage-generator engine that can be used to automatically determine how two molecules should be connected based on a functional rule set. The Reaction class works hand in hand with the Reactivity classes that define how to find suitable attachment points in a molecule. However, the Reaction class can also be used without a Reactivity class by directly providing functions that define how to find attachment points in the source and target molecules. Be sure to check out the Reaction tutorial and Reactivities tutorial for more information.

For example to let BuildAMol figure out how to connect a carboxylic acid to an amine to form an amide bond you can use the following code:

import buildamol as bam
from buildamol.structural.reactivity import Carboxyl, Amine

# start with two molecules
acid = bam.read_smiles("CC(=O)O")
amine = bam.read_smiles("CCN")

# create a reaction that uses the Carboxyl reactivity to find attachment points in the acid
# and the Amine reactivity to find attachment points in the amine
reaction = bam.Reaction.from_reactivities(
   electrophile=Carboxyl(),
   nucleophile=Amine()
)

# now we can use the reaction to connect the two molecules
product = reaction(acid, amine)

Make sure to check out the Tutorials for more examples on how to use the Reaction class and the various Reactivity classes.

class buildamol.core.Reaction(atom1: Atom | callable, atom2: Atom | callable, delete_in_target: List | callable = None, delete_in_source: List | callable = None, bond_order: int = 1)[source]#

Bases: object

A class representing a (pseudo-) chemical reaction between two molecules. It serves as a factory to create Linkages from callables rather than direct atom identifiers.

Parameters:

  • atom1 (Union[Atom, callable]) – The atom in the target molecule to which the source molecule will be connected. This can be an Atom object or a callable that takes a Molecule and returns an Atom

  • atom2 (Union[Atom, callable]) – The atom in the source molecule which will be connected to the target molecule. This can be an Atom object or a callable that takes a Molecule and returns an Atom

  • delete_in_target (Union[List, callable], optional) – A list of atoms in the target molecule to be deleted upon connection, or a callable that takes the atom1 and the target molecule and returns such a list. Default Hydrogen-deletion is applied if None.

  • delete_in_source (Union[List, callable], optional) – A list of atoms in the source molecule to be deleted upon connection, or a callable that takes the atom2 and the source molecule and returns such a list. Default Hydrogen-deletion is applied if None.

  • bond_order (int, optional) – The bond order of the new bond formed between atom1 and atom2. Default is 1 (single bond).

apply(target: Molecule, source: Molecule, inplace: bool = False) → Molecule[source]#

Apply the reaction to two molecules, creating a new molecule with the linkage applied. This is the same as calling the Reaction object directly.

Parameters:

  • target (Molecule) – The target molecule to which the source molecule will be connected.

  • source (Molecule) – The source molecule which will be connected to the target molecule.

  • inplace (bool, optional) – If True, modify the target molecule in place. If False, create a copy of the target molecule. Default is False.

Returns:

A new Molecule object with the linkage applied.

Return type:

Molecule

can_apply(target: Molecule, source: Molecule) → bool[source]#

Check if the reaction can be applied to the given target and source molecules. This checks if the specified atoms and deletions are valid in the context of the provided molecules and stores the resolved atoms and deletions in memory for later use.

This method is automatically called by the apply method.

Parameters:

  • target (Molecule) – The target molecule to which the source molecule will be connected.

  • source (Molecule) – The source molecule which will be connected to the target molecule.

Returns:

True if the reaction can be applied, False otherwise.

Return type:

bool

create_linkage(target: Molecule, source: Molecule) → Linkage[source]#

Create one or more Linkage object(s) based on the current reaction parameters and the provided molecules. This does not modify the molecules, it only creates the Linkage object(s).

This method is automatically called by the apply method. It requires that can_apply has been called beforehand to ensure that the reaction can be applied.

Parameters:

  • target (Molecule) – The target molecule to which the source molecule will be connected.

  • source (Molecule) – The source molecule which will be connected to the target molecule.

Returns:

A Linkage object or a list of Linkage objects representing the connection(s) to be made between the target and source molecules.

Return type:

Linkage or List[Linkage]

classmethod from_reactivities(nucleophile: Reactivity, electrophile: Reactivity, bond_order: int = 1, target_is_electrophile: bool = True)[source]#

Set up a Reaction from two Reactivity objects, one for the nucleophile (source) and one for the electrophile (target). This is a convenience method to quickly create a Reaction from predefined Reactivity patterns.

Parameters:

  • nucleophile (Reactivity) – The Reactivity object defining the nucleophilic behavior of the source molecule.

  • electrophile (Reactivity) – The Reactivity object defining the electrophilic behavior of the target molecule.

  • bond_order (int, optional) – The bond order of the new bond formed between the nucleophile and electrophile. Default is 1 (single bond).

  • target_is_electrophile (bool, optional) – Set to False to modify the roles of nucleophile and electrophile, i.e. the target molecule is the nucleophile and the source molecule is the electrophile.

set_reactivity(atom1: Atom | callable = None, atom2: Atom | callable = None, delete_in_target: List | callable = None, delete_in_source: List | callable = None, bond_order: int = None)[source]#

Set new parameters for the reaction.

Parameters:

  • atom1 (Union[Atom, callable], optional) – The atom in the target molecule to which the source molecule will be connected. This can be an Atom object or a callable that takes a Molecule and returns an Atom

  • atom2 (Union[Atom, callable], optional) – The atom in the source molecule which will be connected to the target molecule. This can be an Atom object or a callable that takes a Molecule and returns an Atom

  • delete_in_target (Union[List, callable], optional) – A list of atoms in the target molecule to be deleted upon connection, or a callable that takes the atom1 and the target molecule and returns such a list. Default Hydrogen-deletion is applied if None.

  • delete_in_source (Union[List, callable], optional) – A list of atoms in the source molecule to be deleted upon connection, or a callable that takes the atom2 and the source molecule and returns such a list. Default Hydrogen-deletion is applied if None.

  • bond_order (int, optional) – The bond order of the new bond formed between atom1 and atom2. Default is 1 (single bond).

with_reactivity(atom1: Atom | callable = None, atom2: Atom | callable = None, delete_in_target: List | callable = None, delete_in_source: List | callable = None, bond_order: int = None)[source]#

Create a new Reaction with modified parameters.

Parameters:

  • atom1 (Union[Atom, callable], optional) – The atom in the target molecule to which the source molecule will be connected. This can be an Atom object or a callable that takes a Molecule and returns an Atom

  • atom2 (Union[Atom, callable], optional) – The atom in the source molecule which will be connected to the target molecule. This can be an Atom object or a callable that takes a Molecule and returns an Atom

  • delete_in_target (Union[List, callable], optional) – A list of atoms in the target molecule to be deleted upon connection, or a callable that takes the atom1 and the target molecule and returns such a list. Default Hydrogen-deletion is applied if None.

  • delete_in_source (Union[List, callable], optional) – A list of atoms in the source molecule to be deleted upon connection, or a callable that takes the atom2 and the source molecule and returns such a list. Default Hydrogen-deletion is applied if None.

  • bond_order (int, optional) – The bond order of the new bond formed between atom1 and atom2. Default is 1 (single bond).

Returns:

A new Reaction object with the modified parameters.

Return type:

Reaction