CrosslinkReaction

class CrosslinkReaction(add_bonds=None, remove_bonds=None, transfer_groups=None, remove_atoms=None, secondary_reaction_map=None, bond_cutoff=None, angle_exclusion=None, exclude_rings_below_size=None, relative_reaction_probability=None)

Defines a cross-linking reaction between a group of atoms.

Parameters:
  • add_bonds (list | None) – List of tuples containing pairs of tags of atoms between which bonds are added.

  • remove_bonds (list | None) – List of tuples containing pairs of tags of atoms between which bonds are removed.

  • transfer_groups (list | None) – List of tuples containing triplets of atom tags of atoms to transfer. Order of tuple is atom transferred, atom transferred from then atom transferred to.

  • remove_atoms (list) – A list of atom tags of atoms to be removed after the reaction.

  • secondary_reaction_map (dict) – Map for how to change current types into new types for a following reaction.

  • bond_cutoff (PhysicalQuantity of type length) – The maximum distance between reactive atoms.
    Default: 5*Angstrom

  • angle_exclusion (PhysicalQuantity of type angle) – The minimum bond angle allowed when forming a new bond.
    Default: 30*Degrees

  • exclude_rings_below_size (int | All) – Prevent reactions that form rings below a set size. The flag All excludes all reactions that form rings. The value 0 allows all ring forming reactions.
    Default: All.

  • relative_reaction_probability (float) – Relative probability that reaction is performed.
    Default: 1

addBonds()
Returns:

List of tuples containing atom tags of reactive atoms.

Return type:

list

angleExclusion()
Returns:

The minimum bond angle allowed when forming a new bond.

Return type:

PhysicalQuantity of type angle

bondCutoff()
Returns:

The maximum distance between reactive atoms.

Return type:

PhysicalQuantity of type length

excludeRingsBelowSize()
Returns:

The ring exclusion size. The flag All prohibits all ring formation.

Return type:

int | All

relativeReactionProbability()
Returns:

Return the relative probability that the reaction is performed.

Return type:

float

removeAtoms()
Returns:

A list of atoms tags of atoms to be removed after the reaction.

Return type:

list

removeBonds()
Returns:

List of tuples containing atom tags of bonds to be removed.

Return type:

list

secondaryReactionMap()

Return a dictionary mapping changes from current types into new types for a following reaction.

Returns:

A dictionary showing the pairing of reactant and product types.

Return type:

dict

totalReactionTags()

Return a set of all the tags used to define the reaction.

Returns:

The set of the reaction tags.

Return type:

set

transferGroups()
Returns:

Return a list of tuples containing atom tags of atoms to transfer. Order of tuple is atom transferred, atom transferred from then atom transferred to.

Return type:

list

uniqueString()

Return a unique string representing the state of the object.

Usage Examples

Define reactions for use in cross-linking an epoxy-amine system

# Load the configuration to be reacted.
configuration = nlread('Amine_Epoxy_Crosslink.hdf5')[-1]

# Specify the reactions for primary amines with an epoxy using the two different hydrogens.
reaction_a = CrosslinkReaction(
    add_bonds=[('REACT_A_C', 'REACT_B_N')],
    remove_bonds=[('REACT_A_C', 'REACT_A_O')],
    transfer_groups=[('REACT_B_H1', 'REACT_B_N', 'REACT_A_O')],
    secondary_reaction_map={'REACT_B_N': 'REACT_C_N', 'REACT_B_H2': 'REACT_C_H', },
    exclude_rings_below_size=0,
    bond_cutoff=4*Angstrom
)
reaction_b = CrosslinkReaction(
    add_bonds=[('REACT_A_C', 'REACT_B_N')],
    remove_bonds=[('REACT_A_C', 'REACT_A_O')],
    transfer_groups=[('REACT_B_H2', 'REACT_B_N', 'REACT_A_O')],
    secondary_reaction_map={'REACT_B_N': 'REACT_C_N', 'REACT_B_H1': 'REACT_C_H', },
    exclude_rings_below_size=0,
    bond_cutoff=4*Angstrom
)

# Specify the reaction of a secondary amine with an epoxy.
reaction_c = CrosslinkReaction(
    add_bonds=[('REACT_A_C', 'REACT_C_N')],
    remove_bonds=[('REACT_A_C', 'REACT_A_O')],
    transfer_groups=[('REACT_C_H', 'REACT_C_N', 'REACT_A_O')],
    exclude_rings_below_size=0,
    bond_cutoff=4*Angstrom
)

Amine_Epoxy_Crosslink.py Amine_Epoxy_Crosslink.hdf5

Define reactions for creating linear polymers of poly(ethylene oxide)

# Load the configuration to be reacted.
configuration = nlread('PEO_Crosslink.hdf5')[-1]

# Specify the reactions of ethylene glycol using both possible atom arrangements.
reaction_a = CrosslinkReaction(
    add_bonds=[('REACT_C_A', 'REACT_O_B')],
    remove_atoms=['REACT_O_A', 'REACT_H_A', 'REACT_H_B'],
    bond_cutoff=5*Angstrom
)
reaction_b = CrosslinkReaction(
    add_bonds=[('REACT_O_A', 'REACT_C_B')],
    remove_atoms=['REACT_O_B', 'REACT_H_A', 'REACT_H_B'],
    bond_cutoff=5*Angstrom
)

PEO_Crosslink.py PEO_Crosslink.hdf5

The given examples above demonstrate how reactions between groups of atoms in a configuration can be defined. The reaction definitions rely on atom tags that can be assigned to specific atoms. In the first case of the epoxy-amine reaction, the reaction is a 2-step process. Here an epoxy can react with a primary amine to first form a secondary amine and then another epoxy can react with the secondary amine to form a tertiary amine. To model these two stages requires using a secondary reaction map to correctly label atoms for the second reaction. As the resulting structure is also a network structure, all rings are allowed to be formed by reactions creating the three-dimensional network.

In the second example the reactions necessary for linking ethylene glycol into linear polymers of poly(ethylene oxide) is shown. This proceeds through a condensation reaction where the two hydroxy groups react to form an ether and a water molecule. This water molecule can be removed by setting remove_atoms argument.

Notes

The CrosslinkReaction class contains details of specific reactions that are performed by the CrosslinkConnector and CrosslinkBuilder classes. In this class reactions are specified using atomic tags. Tags are associated atoms according to the role that those atoms can play in specific reactions. Using these tags, reactions can be described through defining how the bonding of these atoms changes during the reaction. It is possible to describe changes to any number of atoms during a reaction, allowing for the description of complex reactions.

Reactions are defined when the object is initialized. The initialization function takes several arguments that define the reaction. The necessary argument add_bonds describes the bonds that are created during the reaction, while the optional argument remove_bonds describes bonds that are destroyed. Both these arguments require lists of tuples that contain the two atom tags between which bonds are added or removed. In reactions where single atoms are removed from one atom and added onto another, the motion of this atom can be described with the argument transfer_groups. This argument takes a list of tuples, containing tags of the atom being transferred, the atom it is bonded to in the reactant and then the atom it is bonded to in the product. This option is most commonly used for specifying proton transfer, as in the epoxy-amine example above. In some cases the reactions that are being modeled generate additional unwanted molecules, such as condensation reactions. In these cases the argument remove_atoms allows the specification of atoms that are removed from the configuration once they have reacted. In cases where multi-step reactions are to be modeled, atoms may change through a series of reactive types. One example of this is in epoxy-amine reactions, where primary amines first form secondary amines and then tertiary amines. Multi-step reaction pathways can be created with the secondary_reaction_map argument. This takes a dictionary which maps how the reactive type of the atoms change after the specific reaction.

The CrosslinkReaction class initialization function also contains some arguments that control when the reaction can happen[1]. The argument bond_cutoff sets a maximum bond length for newly formed bonds. Reactions that require creation of bonds longer than this cutoff are excluded. Similarly the argument angle_exclusion defines the minimum allowed bond angle that can be created when a new bond is formed. The exclusion of rings and cyclic structures is controlled through the parameter exclude_rings_below_size. In the case where two reacting groups are on the same molecule, reacting these two groups will form a ring or a cyclic structure. The argument exclude_rings_below_size defines the minimum size of any ring formed for the reaction to be accepted. The default value is All, which excludes any reaction that forms a cyclic structure. This value is appropriate in cases where molecules react to form linear polymer chains. A value of 0 allows all reactions that form cyclic structures. A small or zero value of exclude_rings_below_size is needed in cases where molecules react to form three dimensional network systems. Finally the relative probability of the reaction can be specified using the relative_reaction_probability argument. This is useful in cases where multiple reactions with different kinetics are being modeled. Setting different relative reactive probabilities allows slowing the rate of one reaction relative to another by passing over opportunities to perform that reaction. By default all reactions have a relative probability of 1, meaning they are performed whenever allowed.