CoarseGrainMapper

class CoarseGrainMapper

Define a mapping object for converting an all-atom configuration to a coarse grain one. Rules need to be added to define the mapping, and then configuration can be converted.

addMappingRule(template, bead_size, bead_indices, context_indices=None, martini_label=None)

Add a definition of a coarse grain bead.

Parameters:

• template (MoleculeConfiguration | BulkConfiguration) – A configuration that contains an example of the bead.

• bead_size (str | PhysicalQuantity of type length) – The size of the resulting bead. This can be specified as a Martini bead size (R, S or T) or given explicitly as a bead radius.

• bead_indices (list of int) – Indices of the atoms in the configuration that are united in the bead.

• context_indices (list of int) – Additional atoms in the configuration that helps define an instance of the bead.

• martini_label (str) – A label describing polarity of the bead according to the Martini typing scheme. This requires that the bead size is also specified with a Martini label.

beadIndices(configuration, rule, use_precedence=True)

Return the indices of the atoms that are included in each bead.

Parameters:

• configuration (MoleculeConfiguration | BulkConfiguration) – Configuration for which the beads are being sought.

• rule (int) – The index of the rule for which the beads are sought.

• use_precedence (bool) – Whether or not precedence is used to exclude already mapped atoms.

Returns:

List of sets of the atoms that form each bead.

Return type:

list of sets

coarseGrainConfiguration(atomic_configuration, bead_center=None, maintain_mass=False)

Use the mapping rules to create a coarse-grain configuration from a all-atom configuration.

Parameters:

• atomic_configuration (MoleculeConfiguration | BulkConfiguration) – The configuration to be converted.

• bead_center (CenterOfGeometry | CenterOfMass | None) – Whether the center of geometry or the center of mass of the mapped atoms are used to place each bead. The default None corresponds to using the center of geometry.
  Default: CenterOfGeometry

• maintain_mass (bool) – Whether or not exact bead masses are maintained for beads of the same type. The default is to use the most frequent mass for all beads of a particular type.

Returns:

The configuration with mapped atoms converted to coarse grain beads.

Return type:

MoleculeConfiguration | BulkConfiguration

coarseGrainForces(atomic_configuration, forces)

Use the mapping rules to create a coarse-grain forces from a all-atom forces.

Parameters:

• atomic_configuration (MoleculeConfiguration | BulkConfiguration) – The configuration whose forces are being converted.

• forces (PhysicalQuantity array of type energy per distance) – The all atom forces being converted

Returns:

The configuration with mapped atoms converted to coarse grain beads.

Return type:

MoleculeConfiguration | BulkConfiguration

coarseGrainTrajectory(trajectory, bead_center=None, maintain_mass=False)

Use the mapping rules to create a coarse-grain trajectory from an all-atom trajectory. This method converts both Trajectory and MDTrajectory objects.

Parameters:

• atomic_configuration (Trajectory | MDTrajectory) – The trajectory to be converted.

• bead_center (CenterOfGeometry | CenterOfMass | None) – Whether the center of geometry or the center of mass of the mapped atoms are used to place each bead. The default None corresponds to using the center of geometry
  Default: CenterOfGeometry

• maintain_mass (bool) – Whether or not exact bead masses are maintained for beads of the same type. The default is to use the most frequent mass for all beads of a particular type.

Returns:

The configuration with mapped atoms converted to coarse grain beads.

Return type:

MoleculeConfiguration | BulkConfiguration

numberOfRules()

Returns:

The number of rules added to the mapping object.

Return type:

int

uniqueString()

Return a unique string representing the state of the object.

Usage Examples

Create a coarse-grain model of polystyrene from an existing all-atom configuration.

# Load the bulk all-atom configuration
aa_configuration = nlread('bulk_polystyrene.hdf5')[0]

# Load a template that helps to define the mapping
template = nlread('template.hdf5')[0]

# Create a mapping object and define mapping rules for the three different beads
# Each bead is set to the Martini Small (S) size.
mapper = CoarseGrainMapper()
mapper.addMappingRule(template, 'S', [0, 2, 3, 4, 15, 16, 17, 18])
mapper.addMappingRule(template, 'S', [1, 5, 7, 13, 14], context_indices=[0])
mapper.addMappingRule(template, 'S', [6, 8, 9, 10, 11, 12])

# Create the coarse-grain structure using the defined mapping rules
cg_configuration = mapper.coarseGrainConfiguration(aa_configuration)

# Save the configuration
nlsave('cg_polystyrene.hdf5', cg_configuration)

polystyrene_coarse_grain.py

The given script converts an all-atom configuration of bulk polystyrene into a coarse-grain one. The mapping follows the scheme in the figure below. Each bead corresponds to one full heavy atom and two halves, which are shared with neighboring beads. The backbone beads are centered on the carbons connected to the benzene ring. A second bead is then centered on the carbon in the benzene ring that connects to the backbone. Finally, two of the same bead types are used to map the remaining four carbon atoms in the benzene ring. All hydrogen atoms are included with their attached carbon.

Fig. 145 Coarse-grain mapping of polystyrene. The numbers correspond to the indices of the carbon atoms in the polystyrene template.

Once the mapping object is created, the mapping scheme is created by adding rules that define each bead. This is done by giving a configuration, the size of the bead and the indices of the atoms in the configuration that define the bead. When the all-atom configuration is mapped to a coarse-grain one, graph matching is used to convert all groups of atoms whose bond graph matches the atoms given in the rule. Additional atoms can also be given that help to identify the atoms being converted, without being included in the bead itself. This is done in the example above in defining the second bead using the argument context_indices. Here the connecting carbon chain atom is also given so that the bead is centered on the connection between the benzene ring and the carbon chain.

Once the mapping is defined the coarse-grain representation is simply created by giving a configuration and calling the coarseGrainConfiguration method.

Notes

The CoarseGrainMapper class can be used to define a mapping between all-atom and coarse-grain structures that can be then used to convert different configurations or trajectories. The mapping is constructed by adding rules that define each bead. A bead is defined by giving an example of one or more atoms in a configuration that map to the bead. The mapping algorithm can then use graph matching to find all the occurrences of this bond pattern and convert it into a bead. For each rule a template configuration, a bead size and the indices in the configuration that define the bead must be given. The size of the bead can be specified using the Martini formalism of R (regular) S (small) or T (tiny) or by simply giving a particle radius. In cases where the same or similar bonding patterns are used for different beads, additional atoms can be specified using the context_indices argument. These atoms are added to the graph pattern but are not included in the bead definition. An optional label for each bead can be also added with the martini_label argument.

Once the rules are defined a coarse-grain configuration or trajectory can be created from an all-atom one using the coarseGrainConfiguration and coarseGrainTrajectory methods. In addition to the configuration these also optionally take a definition of the bead center. New beads can either be placed at the center of mass of the mapped atom, or simply at the average Cartesian coordinates ignoring mass weighting. These options are specified with the flags CenterOfMass and CenterOfGeometry, respectively. Whether or not the the exact mass of the beads is maintained can also be specified. When converting polymers or other chain structures, beads on the end will often have different numbers of hydrogens or not have the same atom sharing as beads in the center. By default the most frequent mass of each bead type is used. In the case of a simple polyethylene polymer, this results in the whole polymer being represented by C₂H₄ beads. This ignores the additional hydrogens on each end. Setting the argument maintain_mass to True creates additional beads types for the terminal beads, that map the correct C₂H₅ end group.

When the configuration is converted the rules are applied in order to convert the structure. The graph matching algorithm is able to share atoms between different beads, to enable the creation of symmetric mappings. In the given example, a symmetric mapping of polystyrene is generated by sharing atoms between beads, allowing beads be be centered on the atoms that connect the carbon chain and the benzene ring.

Similar to configurations, all-atom forces can be mapped into coarse-grain forces. This is done assuming that the atoms of the bead form a rigid unit, and so the total force on the bead is the vector sum of the forces acting on the atoms.