grits

coarsegrain module

GRiTS: Coarse-graining tools.

class grits.coarsegrain.Bead(smarts=None, orientation=None, **kwargs)

Bases: Compound

Coarse-grained Bead.

Wrapper for mbuild.Compound.

Parameters:

• smarts (str, default None) – SMARTS string used to specify this Bead.

• orientation (numpy array, default None) – Quaternion describing an anisotropic Gay-Berne bead’s orientation.

smarts

SMARTS string used to specify this Bead.

Type:

str

orientation

Quaternion describing an anisotropic Gay-Berne bead’s orientation.

Type:

numpy array

class grits.coarsegrain.CG_Compound(compound, beads=None, mapping=None, allow_overlap=False, add_hydrogens=False, aniso_beads=False, **kwargs)

Bases: Compound

Coarse-grained Compound.

Wrapper for mbuild.Compound. Coarse-grained mapping can be specified using SMARTS grammar.

Parameters:

• compound (mbuild.Compound) – Fine-grain structure to be coarse-grained

• beads (dict, default None) –

  Dictionary with keys containing desired bead name and values containing SMARTS string specification of that bead. For example:

  beads = {"_B": "c1sccc1", "_S": "CCC"}
  

  would map a "_B" bead to any thiophene moiety ("c1sccc1") found in the compound and an "_S" bead to a propyl moiety ("CCC"). User must provide only one of beads or mapping.

• mapping (dict or path, default None) –

  Either a dictionary or path to a json file of a dictionary. Dictionary keys contain desired bead name and SMARTS string specification of that bead and values containing list of tuples of atom indices:

  mapping = {"_B...c1sccc1": [(0, 4, 3, 2, 1), ...]}
  

  User must provide only one of beads or mapping.

• allow_overlap (bool, default False) – Whether to allow beads representing ring structures to share atoms.

• add_hydrogens (bool, default False) – Whether to add hydrogens. Useful for united-atom models.

• aniso_beads (bool, default False) – Whether to calculate orientations for anisotropic beads. Note: Bead sizes should be fitted during paramaterization. Only Gay-Berne major axis orientations are calculated here.

atomistic

The atomistic structure.

Type:

mbuild.Compound

mapping

A mapping from atomistic to coarse-grain structure. Dictionary keys are the bead name and SMARTS string (separated by “…”), and the values are a list of tuples of fine-grain particle indices for each bead instance:

{"_B...c1sccc1": [(0, 4, 3, 2, 1), ...], ...}

Type:

dict

anchors

A mapping of the anchor particle indices in each bead. Dictionary keys are the bead name and the values are a set of indices:

{"_B": {0, 2, 3}, ...}

Type:

dict

bond_map

A list of the bond types and the anchors to use for that bond:

[('_B-_S', (3, 0)), ...]

Type:

list[tuple(str, tuple(int, int))]

save_mapping(filename=None)

Save the mapping operator to a json file.

Parameters:

filename (str, default None) – Filename where the mapping operator will be saved in json format. If None is provided, the filename will be CG_Compound.name + “_mapping.json”.

Returns:

Path to saved mapping

Return type:

str

visualize(show_ports=False, color_scheme={}, show_atomistic=False, scale=1.0)

Visualize the Compound using py3dmol.

Allows for visualization of a Compound within a Jupyter Notebook. Modified to from mbuild.Compound.visualize() to show atomistic elements (translucent) with larger CG beads.

Parameters:

• show_ports (bool, default False) – Visualize Ports in addition to Particles

• color_scheme (dict, default {}) –

  Specify coloring for non-elemental particles keys are strings of the particle names values are strings of the colors:

  {'_CGBEAD': 'blue'}
  

• show_atomistic (bool, default False) – Show the atomistic structure stored in CG_Compound.atomistic

• scale (float, default 1.0) – Scaling factor to modify the size of objects in the view.

Returns:

view

Return type:

py3Dmol.view

class grits.coarsegrain.CG_System(gsdfile, beads=None, mapping=None, allow_overlap=False, conversion_dict=None, length_scale=1.0, mass_scale=1.0, add_hydrogens=False, aniso_beads=False)

Bases: object

Coarse-grained System.

Coarse-grained mapping can be specified using SMARTS grammar or the indices of particles.

Parameters:

• gsdfile (path) – Path to a gsd file.

• beads (dict, default None) –

  Dictionary with keys containing desired bead name and values containing SMARTS string specification of that bead. For example:

  beads = {"_B": "c1sccc1", "_S": "CCC"}
  

  would map a "_B" bead to any thiophene moiety ("c1sccc1") found in the compound and an "_S" bead to a propyl moiety ("CCC"). User must provide only one of beads or mapping.

• mapping (dict or path, default None) –

  Either a dictionary or path to a json file of a dictionary. Dictionary keys contain desired bead name and SMARTS string specification of that bead and values containing list of lists of atom indices:

  mapping = {"_B...c1sccc1": [[0, 4, 3, 2, 1], ...]}
  

  User must provide only one of beads or mapping. If a mapping is provided, the bonding between the beads will not be set.

• allow_overlap (bool, default False,) – Whether to allow beads representing ring structures to share atoms.

• conversion_dict (dictionary, default None) – Dictionary to map particle types to their element.

• length_scale (float, default 1.0) – Factor by which to scale length values.

• mass__scale (float, default 1.0) – Factor by which to scale mass values.

• add_hydrogens (bool, default False) – Whether to add hydrogens. Useful for united-atom models.

• aniso_beads (bool, default False) – Whether to calculate orientations for anisotropic beads. Note: Bead sizes should be fitted during paramaterization. These are not calculated here.

mapping

A mapping from atomistic to coarse-grain structure. Dictionary keys are the bead name and SMARTS string (separated by “…”), and the values are a list of numpy arrays of fine-grain particle indices for each bead instance:

{"_B...c1sccc1": [np.array([0, 4, 3, 2, 1]), ...], ...}

Type:

dict

save(cg_gsdfile, start=0, stop=None, stride=1)

Save the coarse-grain system to a gsd file.

Does not calculate the image of the coarse-grain bead.

Retains:

• configuration: box, step

• particles: N, position, typeid, types

• bonds: N, group, typeid, types

Parameters:

• cg_gsdfile (str) – Filename for new gsd file. If file already exists, it will be overwritten.

• start (int, default 0) – Where to start reading the gsd trajectory the system was created with.

• stop (int, default None) – Where to stop reading the gsd trajectory the system was created with. If None, will stop at the last frame.

• stride (int, default 1) – The step size to use when iterating through start:stop

save_mapping(filename)

Save the mapping operator to a json file.

Parameters:

filename (str) – Filename where the mapping operator will be saved in json format.

finegrain module

GRiTS: Fine-graining tools.

grits.finegrain.backmap(cg_compound)

Backmap a fine-grained representation onto a coarse one.

Creates a fine-grained compound from a coarse one using the attributes created during CG_Compound initialization.

Parameters:

cg_compound (CG_Compound) – Coarse-grained compound

Returns:

The atomistic structure mapped onto the coarse-grained one.

Return type:

mbuild.Compound

utils module

Utility functions for GRiTS.

class grits.utils.NumpyEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

Bases: JSONEncoder

Serializer for numpy objects.

default(obj)

Overwrite the default for numpy arrays and data types.

grits.utils.align(compound, particle, towards_compound, around=None)

Spin a compound such that particle points at towards_compound.

Parameters:

• compound (mbuild.Compound or CG_Compound,) – The compound to align

• particle (mbuild.Compound or CG_Compound,) – The particle to point at towards_compound. Child of compound.

• towards_compound (mbuild.Compound or CG_Compound,) – The compound to point towards.

• around (numpy.ndarray, default None) – The unit vector around which the compound is spun. If None is given, an orthogonal vector is chosen.

Returns:

The unit vector about which the compound is rotated

Return type:

numpy.ndarray

grits.utils.comp_from_snapshot(snapshot, indices, length_scale=1.0, mass_scale=1.0)

Convert particles by indices from a Snapshot to a Compound.

Parameters:

• snapshot (gsd.hoomd.Frame) – Snapshot from which to build the mbuild Compound.

• indices (np.ndarray) – Indices of the particles to be added to the compound.

• length_scale (float, default 1.0) – Value by which to scale the length values

• mass_scale (float, default 1.0) – Value by which to scale the mass values

Returns:

comp

Return type:

mbuild.Compound

Note

GSD snapshots center their boxes on the origin (0,0,0), so the compound is shifted by half the box lengths

grits.utils.get_bonded(compound, particle)

Get particles bonded to the given particle in a compound.

Parameters:

• compound (mbuild.Compound or CG_Compound) – Compound containing particle

• particle (mbuild.Particle or Bead) – Particle to which the directly bonded neighbors are requested

Returns:

The bonded particles.

Return type:

list[mbuild.Particle]

grits.utils.get_bonds(compound)

Convert Particle instances in bond_graph.edges to their indices.

See CG_Compound.bond_graph.edges().

Parameters:

compound (mbuild.Compound or CG_Compound) – Compound from which to get the indexed bond graph.

Returns:

Sorted list of bonded particle indices

Return type:

list[tuple(int, int)]

grits.utils.get_com(particle_positions, particle_masses)

Calculate center of mass coordinates.

Given a set of particle positions and masses, find their center of mass. Arrays must be of same dimension.

Parameters:

• particle_positions (numpy array) – N_particlesx3 numpy array of particle positions (x,y,z)

• particle_masses (numpy array) – N_particlesx0 numpy array of particle masses

Returns:

center_of_mass – 3x0 numpy array of center of mass coordinates

Return type:

numpy array

grits.utils.get_heavy_atoms(particles)

Filter out hydrogens for axis-angle calculation.

Returns arrays of only heavy atoms’ positions and masses, given a gsd.frame.particles object. Used in Aniso mapping.

Parameters:

particles (gsd.frame.particles) – Particles from all atom gsd frame.

Returns:

• heavy_partpos (numpy array) – Array of all positions of heavy atoms

• heavy_partmass (numpy array) – Array of all masses of heavy atoms

grits.utils.get_hydrogen(compound, particle)

Get the first hydrogen attached to particle.

Parameters:

• compound (mbuild.Compound or CG_Compound) – Compound which contains particle

• particle (mbuild.Particle or Bead) – Particle from which to remove a hydrogen

grits.utils.get_index(compound, particle)

Get the index of a Particle in the Compound.

The particle can be accessed like compound[index].

Parameters:

• compound (mbuild.Compound or CG_Compound) – Compound which contains particle

• particle (mbuild.Particle or Bead) – Particle for which to fetch the index

Returns:

The particle index

Return type:

int

grits.utils.get_major_axis(positions_arr)

Find the major axis for GB CG representation.

Used in axis-angle orientation representation.

Parameters:

• positions_arr (numpy array) – N_particlesx3 numpy array of particle positions to map to one aniso bead.

• elements_arr (list) – List of length N_particles containing particle elements

Returns:

• major_axis (numpy array) – array designating vector of major axis of Gay-Berne particle

• particle_indicies (tuple of ints) – tuple of two particle indices used to calculate major axis vector

grits.utils.get_quaternion(n1, n0=array([0, 0, 1]))

Calculate rotation quaternion from axis vectors.

Calculate axis and angle of rotation given two planes’ normal vectors, which is then used to calculate the quaternions for HOOMD.

Parameters:

• n1 (numpy array) – numpy array that is the major axis vector.

• n0 (numpy array) – numpy array that is used to define the default quaternion. Defaults to the Z-axis.

Returns:

quaternion – numpy array that tells the position of the monomer in units of a quaternion.

Return type:

numpy array

grits.utils.has_common_member(it_a, it_b)

Determine if two iterables share a common member.

Parameters:

• it_a (iterable object) – Iterable objects to compare

• it_b (iterable object) – Iterable objects to compare

Returns:

Whether the object share a common member.

Return type:

bool

grits.utils.has_number(string)

Determine whether a string contains a number.

Parameters:

string (str) – String which may contain a number

Returns:

Whether the string contains a number.

Return type:

bool

grits.utils.num2str(num)

Convert a number to a string.

Convert positive integers up to 701 into a capital letter (or letters).

Parameters:

num (int) – Number to convert

Examples

>>> num2str(0)
'A'
>>> num2str(25)
'Z'
>>> num2str(25)
'AA'

Returns:

The string conversion of the number

Return type:

str