CrosslinkConnector¶

class CrosslinkConnector(configuration, reactions, functional_groups=None, reactive_atom_groups=None, max_number_of_reactions=None, random_seed=None)¶

Create a class for performing cross-linking in a polymer system.

Parameters:

configuration (MoleculeConfiguration | BulkConfiguration) – The configuration that is to be reacted.
reactions (CrosslinkReaction | list of CrosslinkReaction) – The CrosslinkReaction objects that define the possible reactions.
functional_groups (list) – List of lists of atom tags that defines the functional groups in the configuration that can react according to the defined reactions. Cannot be specified together with reactive_atom_groups.
reactive_atom_groups (list) – List of dictionaries that identify the atoms in the configuration that react and their reaction tags. These are the same tags used to define atoms in the reaction definitions. Cannot be specified together with functional_groups.
max_number_of_reactions (int) – The maximum number of reactions done in a cycle. None allows all available reactions.
Default: None
random_seed (int) – A seed for the random number generator used to select reactions when unequal reaction probabilities are specified.

crosslink(configuration=None)¶

Perform cross-linking on the stored configuration.

Parameters:: configuration (MoleculeConfiguration | BulkConfiguration) – An optional configuration used if the atomic positions of the atoms changes between cross-linking steps. If not specified the current stored configuration is used.
Returns:: Dictionary containing the number of reactions, lists of bonds formed and broken and atoms transferred.
Return type:: dict

initialConfiguration()¶

Return a copy of the initial configuration on which the reactive groups are initially set.

Returns:: The initial supplied configuration.
Return type:: MoleculeConfiguration | BulkConfiguration

maximumBondSearchRadius()¶

Find the maximum bond search radius in the defined reactions.

Returns:: The maximum bond search radius from each reaction.
Return type:: PhysicalQuantity of type length

numberOfPossibleReactions()¶

Return the number of possible reactions found during the previous cross-linking step. This can include several reactions involving the same atoms, and so not all reactions may be able to be performed simultaneously.

Returns:: Number of possible reactions.
Return type:: int

ratioReacted()¶

Return the ratio of the current number of reactive groups to the initial number. This gives an indication of overall progress of the reaction. Numbers returned are in the range 0 to 1.

Returns:: Ratio of reacted groups.
Return type:: int

reactedConfiguration()¶

Return the current reacted configuration that has resulted from the performed cross-linking steps. If no cross-linking has been done the initial configuration is returned.

Returns:: The reacted configuration.
Return type:: MoleculeConfiguration | BulkConfiguration

Usage Examples¶

Define a cross-linker 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
)

# Define the CrosslinkConnector, using the defined reactions and functional groups to find the
# reactive atom groups in the configuration.
crosslink_connector = CrosslinkConnector(
    configuration,
    reactions=[reaction_a, reaction_b, reaction_c],
    functional_groups=[['REACT_A_C', 'REACT_A_O'], ['REACT_B_N', 'REACT_B_H1', 'REACT_B_H2']],
    max_number_of_reactions=100
)

Amine_Epoxy_Crosslink.py Amine_Epoxy_Crosslink.hdf5

Define a cross-linker 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
)

# Explicitly define the reactive atom groups in the configuration.
reactive_atom_groups = [{'REACT_C_A': 0, 'REACT_O_A': 2, 'REACT_H_A': 8},
                        {'REACT_C_A': 1, 'REACT_O_A': 5, 'REACT_H_A': 9},
                        {'REACT_C_A': 10, 'REACT_O_A': 12, 'REACT_H_A': 18},
                        {'REACT_C_A': 11, 'REACT_O_A': 15, 'REACT_H_A': 19},
                        {'REACT_C_A': 20, 'REACT_O_A': 22, 'REACT_H_A': 28},
                        {'REACT_C_A': 21, 'REACT_O_A': 25, 'REACT_H_A': 29},
                        {'REACT_C_A': 30, 'REACT_O_A': 32, 'REACT_H_A': 38},
                        {'REACT_C_A': 31, 'REACT_O_A': 35, 'REACT_H_A': 39},
                        {'REACT_C_A': 40, 'REACT_O_A': 42, 'REACT_H_A': 48},
                        {'REACT_C_A': 41, 'REACT_O_A': 45, 'REACT_H_A': 49},
                        {'REACT_C_A': 50, 'REACT_O_A': 52, 'REACT_H_A': 58},
                        {'REACT_C_A': 51, 'REACT_O_A': 55, 'REACT_H_A': 59},
                        {'REACT_C_A': 60, 'REACT_O_A': 62, 'REACT_H_A': 68},
                        {'REACT_C_A': 61, 'REACT_O_A': 65, 'REACT_H_A': 69},
                        {'REACT_C_A': 70, 'REACT_O_A': 72, 'REACT_H_A': 78},
                        {'REACT_C_A': 71, 'REACT_O_A': 75, 'REACT_H_A': 79},
                        {'REACT_C_A': 80, 'REACT_O_A': 82, 'REACT_H_A': 88},
                        {'REACT_C_A': 81, 'REACT_O_A': 85, 'REACT_H_A': 89},
                        {'REACT_C_A': 90, 'REACT_O_A': 92, 'REACT_H_A': 98},
                        {'REACT_C_A': 91, 'REACT_O_A': 95, 'REACT_H_A': 99},
                        {'REACT_C_B': 0, 'REACT_O_B': 2, 'REACT_H_B': 8},
                        {'REACT_C_B': 1, 'REACT_O_B': 5, 'REACT_H_B': 9},
                        {'REACT_C_B': 10, 'REACT_O_B': 12, 'REACT_H_B': 18},
                        {'REACT_C_B': 11, 'REACT_O_B': 15, 'REACT_H_B': 19},
                        {'REACT_C_B': 20, 'REACT_O_B': 22, 'REACT_H_B': 28},
                        {'REACT_C_B': 21, 'REACT_O_B': 25, 'REACT_H_B': 29},
                        {'REACT_C_B': 30, 'REACT_O_B': 32, 'REACT_H_B': 38},
                        {'REACT_C_B': 31, 'REACT_O_B': 35, 'REACT_H_B': 39},
                        {'REACT_C_B': 40, 'REACT_O_B': 42, 'REACT_H_B': 48},
                        {'REACT_C_B': 41, 'REACT_O_B': 45, 'REACT_H_B': 49},
                        {'REACT_C_B': 50, 'REACT_O_B': 52, 'REACT_H_B': 58},
                        {'REACT_C_B': 51, 'REACT_O_B': 55, 'REACT_H_B': 59},
                        {'REACT_C_B': 60, 'REACT_O_B': 62, 'REACT_H_B': 68},
                        {'REACT_C_B': 61, 'REACT_O_B': 65, 'REACT_H_B': 69},
                        {'REACT_C_B': 70, 'REACT_O_B': 72, 'REACT_H_B': 78},
                        {'REACT_C_B': 71, 'REACT_O_B': 75, 'REACT_H_B': 79},
                        {'REACT_C_B': 80, 'REACT_O_B': 82, 'REACT_H_B': 88},
                        {'REACT_C_B': 81, 'REACT_O_B': 85, 'REACT_H_B': 89},
                        {'REACT_C_B': 90, 'REACT_O_B': 92, 'REACT_H_B': 98}]

# Define the CrosslinkConnector, using the defined reactions and reactive atom groups.
crosslink_connector = CrosslinkConnector(
    configuration,
    reactions=[reaction_a, reaction_b],
    reactive_atom_groups=reactive_atom_groups,
    max_number_of_reactions=5
)

PEO_Crosslink.py PEO_Crosslink.hdf5

Notes¶

The CrosslinkConnector class contains the necessary information to describe the possible reactions in a configuration. The class also contains methods to detect which groups are able to react together and to carry out these reactions by altering the bonding. This enables the creation of realistic amorphous structures that are formed through a chemical process. For instance it allows building polymer systems from monomers in a range of geometries, or post-synthetic cross-linking of linear polymer chains. This class can be used in a stand-alone manner to perform a discrete set of reactions on a single configuration. It can also be used together with the CrosslinkBuilder class to model the progressive changes in the configuration as reactions occur and the positions of the atoms evolve.

To create a CrosslinkConnector object 3 arguments are required. First the parameter configuration takes the configuration in which reactions are being modeled. The reactions themselves are given as the argument reactions. The takes a list of CrosslinkReaction objects that define all of the possible reactions in the given configuration. Lastly a list of the atoms that are able to react and the reactions they are able to participate in is required. This can be specified in one of two ways. One method is to use the parameter functional_groups. This argument takes a list of lists, with each list containing atom tags of the atoms that together form a reactive functional group. As an example, in the epoxy-amine system the epoxy and amine atoms create two different reactive functional groups. These groups are then specified as a list of lists of the tags on the atoms that make up each group. On initialization the CrosslinkConnector finds all the reactive groups of each type by finding the groups of atoms that are located closest to each other. There can be any number of identical reactive groups in a configuration. The second way to specify the reactive atoms is to explicitly define them. This is done using the argument reactive_atom_groups. This argument takes a list of dictionaries, each dictionary representing one reactive group of atoms. The keys and values in the dictionary are the atom tags used in the reaction definitions and the indices of the atoms respectively. As the reacting atom groups are given explicitly, when reactive_atom_groups is set, tags for the reacting atoms do not need to be set on the configuration.

Note

The reactions and reactive atoms required by the arguments reactions and reactive_atom_groups respectively can be generated from the input configuration using a ReactionTemplate object. See the documentation of this object for more details.

The CrosslinkConnector also accepts two optional arguments on initialization. The first of these, max_number_of_reactions, controls the maximum number of reactions that are performed at each cross-linking step. This allows some control over the rate at which reactions are performed. This can be important at the start of a reaction simulation, where often a large number of reactions are possible. Without limiting the number of reactions, the initial structure may be locked into the configuration, as the performed reactions make the structure far more rigid. By default all possible reactions are carried out at each step. A seed to the random number generator used to determine whether or not low probability reactions are carried out can be given through the argument random_seed.

Performing a cross-linking step with the CrosslinkConnector is done through using the method crosslink. This takes an optional configuration to be reacted as input, and returns the number of reactions that were performed, as well as details of the bond changes as a result of the reactions. Supplying a configuration is useful in cases where the atomic positions of the atoms change in between cross-linking steps. If no configuration is supplied, either the initial configuration or the configuration produced by the last cross-linking step is used. Accessing the stored configurations is done through the methods initialConfiguration and reactedConfiguration. Information about the progress of the reactions can also be obtained through two methods. The method ratioReacted gives the ratio of reactive groups that have undergone a reaction compared to the total number of groups. In cases where the multi-step reactions are being modeled, the newly formed reactive groups are taken into account. The total number of possible reactions found after each reaction step can also be returned using the method numberOfPossibleReactions. The maximum bond cutoff radius in the defined reactions can also be returned with the function maximumBondSearchRadius.