ReactionTemplate

class ReactionTemplate(image_list=None, bond_cutoff=None, angle_exclusion=None, exclude_rings_below_size=None, relative_reaction_probability=None)

Create a reaction template object that describes the bond changes and reacting functional groups for a specific reaction sequence.

Parameters:
  • image_list (list) – A list of MoleculeConfigurations that define the reaction template.

  • bond_cutoff (PhysicalQuantity of type length | list) – The bond cutoff used in the defined reactions.

  • angle_exclusion (PhysicalQuantity of type angle | list) – The angle exclusion used in the defined reactions.

  • exclude_rings_below_size (int | All | list) – The ring exclusion size used in the defined reactions.

  • relative_reaction_probability (list) – The relative reaction probabilities used in the defined reactions.

findReactiveGroupMap(configuration, add_tags_to_configuration=False)

Find the reactive groups in the starting configuration.

Parameters:
  • configuration (BulkConfiguration) – The configuration to find the reactive groups in.

  • add_tags_to_configuration (bool) – Whether or not reactive tags are added to the configuration.
    Default: False.

Returns:

The list of dictionaries defining the reactive groups.

Return type:

list

numberOfReactionSteps()
Returns:

The number of reaction steps in the template.

Return type:

int

reactions(bond_cutoff=None, angle_exclusion=None, exclude_rings_below_size=None, relative_reaction_probability=None)

Return the reactions defined by the template.

Parameters:
  • bond_cutoff (PhysicalQuantity of type length | list) – The bond cutoff used in the defined reactions.

  • angle_exclusion (PhysicalQuantity of type angle | list) – The angle exclusion used in the defined reactions.

  • exclude_rings_below_size (int | All | list) – The ring exclusion size used in the defined reactions.

  • relative_reaction_probability (list) – The relative reaction probabilities used in the defined reactions.

Returns:

The list of CrosslinkReaction objects that defines the reaction scheme.

Return type:

list

templateConfiguration(index)

Return the MoleculeConfiguration used to define the reaction.

Parameters:

index (int) – Index of the desired configuration.

Returns:

The template MoleculeConfiguration.

Return type:

MoleculeConfiguration

uniqueString()

Return a unique string representing the state of the object.

Usage Examples

Build a network polymer system based on an amine-epoxy reaction with a reaction template

# Load the templates.
template_a = nlread('Amine_Epoxy_Templates.hdf5')[0]
template_b = nlread('Amine_Epoxy_Templates.hdf5')[1]
template_c = nlread('Amine_Epoxy_Templates.hdf5')[2]

# Load the initial configuration for cross-linking.
configuration = nlread('Amine_Epoxy_Crosslink.hdf5')[-1]

# Create the ReactionTemplate object.
template = ReactionTemplate(
    image_list=[template_a, template_b, template_c],
    bond_cutoff=4*Angstrom,
    exclude_rings_below_size=0
)

# Define the CrosslinkConnector, using the ReactionTemplate.
crosslink_connector = CrosslinkConnector(
    configuration,
    reactions=template.reactions(),
    reactive_atom_groups=template.findReactiveGroupMap(configuration),
    max_number_of_reactions=None
)

# Define the CrosslinkBuilder object, using the OPLS potential to model the material.
opls_potential = OPLSPotentialBuilder()
polymer_builder = CrosslinkBuilder(
    crosslink_connector,
    cycles_to_terminate=None,
    reaction_percentage=100,
    nvt_steps_per_crosslink=1000,
    npt_steps_per_crosslink=1000,
    potential_builder=opls_potential,
    temperature=480*Kelvin,
    pressure=1*bar,
    bond_search_increment=0.5*Angstrom,
    max_bond_search_radii=6*Angstrom
)

# Run the polymer building simulation.
polymer_builder.runCrosslinking(trajectory_filename='Thermoset_Amine_Epoxy.hdf5')

Amine_Epoxy_Crosslink.py Amine_Epoxy_Crosslink.hdf5 Amine_Epoxy_Templates.hdf5

Note that the example here has been created to be illustrative of the process of building a thermoset material. For high-quality simulations it may be necessary to increase the number of molecular dynamics steps or the size of the system.

Notes

The ReactionTemplate class provides an alternative way to define reactions performed by the CrosslinkConnector. On initialization the object requires a list of MoleculeConfiguration objects that define the bonding of the atoms at each stage of the reaction. By analyzing the changes in bonding between successive configurations, the ReactionTemplate class determines the CrosslinkReaction objects required to perform those reactions. The individual molecules in each reactant stage also act as templates of the possible reactive groups. These molecules are matched against atoms in the configuration being reacted, to find all of the possible reactive groups. Both the reactions and the reactive groups can then be used to define a CrosslinkConnector object.

../../../_images/Epoxy_Reaction_Scheme.png

Fig. 169 The template configurations for an amine-epoxy reaction scheme.

The configurations that are used to define the amine-epoxy reaction used in the example is shown in the figure above. When creating configurations to model a reaction sequence, one constraint is that the atoms in each configuration must be in the same order. This is so that otherwise identical atoms can be identified across configurations. When creating multiple reaction steps, all of the molecules that participate in the reaction must be present at each stage, even if they do not react at that stage. In the case of the epoxy-amine example, it can be seen that the template requires two epoxy molecules, even though only one reacts at each stage. The ReactionTemplate class is also able to find reactive groups in a configuration. It does this by finding the segments of the configuration molecular graph that match molecules in a reactant step in the reaction sequence. To ensure that the template molecules remain general and chemically sensible, it is possible to set which atoms are used to match reactive groups in the reacting configuration. Atoms labeled with the tag COORDINATION are only used to indicate the coordination number of the atom that they are bonded to, rather than being searched for explicitly. So in the amine-epoxy example, the hydrogens on the methyl groups bonded to both the amine and the epoxy are labeled with the tag COORDINATION. This means that when the ReactionTemplate class looks for reactive groups in a configuration, it matches amine or epoxy groups that are bonded to 4-coordinate carbons. The nature of the atoms that the carbon is bonded to, aside from the epoxy or amine, is not taken into account. Note also that as it looks explicitly for 4-coordinate carbons, it will not match aromatic groups, such as the aromatic amine in aniline. To match aromatic carbons, a 3-coordinate carbon must be specified.

Note

As the atoms in configurations used to describe a reaction need to be in the same order, it can be easiest to create the initial configuration in the Molecule Builder. The configurations for additional stages can then be created by duplicating the initial configuration. As it can change atom ordering, it is also recommended to turn off Auto passivation in the Molecular Builder when changing the bonding in a configuration.

Atoms to be removed from the configuration after a reaction can be specified by removing all bonds to those atoms. Single atoms with no bonds in a configuration beyond the initial configuration are assumed to form small molecules that are removed after the reaction. As an example, in the condensation reaction of an alcohol with a carboxylic acid, a water molecule is produced along with the ester. To remove the water molecule after the reaction, the bonds between the hydrogens and oxygen atom in the water molecule need to be removed. The product configuration will therefore contain an ester molecule, a single oxygen atom and two single hydrogen atoms.

On initialization the MoleculeConfiguration that defines the chemistry of the reaction. Optionally, it is also possible to specify some parameters of the CrosslinkReaction objects that are created by the template. The arguments bond_cutoff, angle_exclusion, exclude_rings_below_size and relative_reaction_probability are all passed to the CrosslinkReaction objects and have the same meaning. The first three arguments can be specified with either a single value, which is passed to all CrosslinkReaction objects, or a list with a value for each object. As it only makes sense to have different values for different reactions, the relative_reaction_probability argument only accepts a list of values for each reaction.

Once the ReactionTemplate object is created, the reactive groups in a configuration can be found using the method findReactiveGroupMap. This takes as an argument the configuration which is to be reacted. It also takes an optional argument add_tags_to_configuration, which specifies whether or not the tags defining different reactions are added to the configuration. Placing tags on the configuration is not necessary when using a reaction template, and so by default the method does not place tags on the configuration. However, as tags are altered by the CrosslinkBuilder, adding tags can help to analyze the progress of a reaction. The findReactiveGroupMap method returns a list of dictionaries that define all of the reactive groups in the configuration. This is in the correct format to be directly passed to the CrosslinkConnector. A copy of the CrosslinkReaction objects contained by the template can also be returned with the method reactions. This takes the same 4 optional arguments as the initialization method, allowing for the parameters of the returned reaction objects to be changed without re-defining the template. The number of reaction steps in the template can also be returned with the method numberOfReactionSteps. Finally the MoleculeConfiguration objects used to define each stage of the reaction can be returned with the method templateConfiguration. This takes an integer argument indicating the index of the configuration that is returned.