schrodinger.application.desmond.packages.topo module

Functionalities to handle molecular topologies

Copyright Schrodinger, LLC. All rights reserved.

class schrodinger.application.desmond.packages.topo.DuckFrame(model)

Bases: object

A duck-type frame with limited interface.

FIXME: I only implemented the interface for what is needed now. We may need enhancements down the road, but that should be easy. -YW (Jun 2, 2016)

We can duck-type a msys model (i.e., a msys.System object) into a `DuckFrame’ object, example:

dfr = DuckFrame(msys_model)

Changes on the DuckFrame' object should NOT affect the original `model object.

box

pos(i=None)

Return the position vector(s).

vel()

schrodinger.application.desmond.packages.topo.aid_match(cms_model)

Return type:list of int Returns:Returns an array of atom indices. Index = 1-based atom index as in the full-system CT, value = index of the matched atom (0 means not matched).

schrodinger.application.desmond.packages.topo.aids2gids(cms_model, aids, include_pseudoatoms=True)

Convert a list of atom IDs (aids) into a list of gids. If any selected atoms have pseudoatoms associated to them, the pseudoatoms will be included into the list of gids.

Parameters:cms_model (cms.Cms) – A cms model generated by read_cms (see above). Return type:list of int Returns:A list of gids of the selected particles

schrodinger.application.desmond.packages.topo.asl2gids(cms_model, asl, include_pseudoatoms=True)

Evaluate an ASL expression, and return a list of gids of particles selected by asl. If any selected atoms have pseudoatoms associated to them, the pseudoatoms will be included into the list of gids.

Parameters:

• cms_model (cms.Cms) – A cms model generated by read_cms (see above).
• asl (str) – An ASL expression

Return type:

list of int

Returns:

An unsorted list of gids of the selected particles

schrodinger.application.desmond.packages.topo.center(msys_model, gids, tr, dims=None)

This function will do what glue does, but it will do one more thing: It will translate the coordinates of all atoms so that the specified molecules will be placed at the center (origin) of the simulation box.

Parameters:

• msys_model (msys.System) – The msys model, which must be consistent with the trajectory in terms of the molecular topology. This object will not be mutated.
• gids (list) – A list of gids to specify the molecules to be glued and centered
• tr (list) – The simulation trajectory to be modified
• dim (None or list of int, e.g., [2] for z axis, [0, 1] for x-y plane. If set to None, center on all three spatial dimensions) – dimensions to be centered on

Return type:

list

Returns:

Modified simulation trajectory

schrodinger.application.desmond.packages.topo.center_cms(msys_model, gids, cms_model, dims=None)

Similar to center (see above), but on a cms model instead of a simulation trajectory.

Both msys_model and cms_model must be previously obtained through the read_cms function. They both should have the same atom coordinates and the same simulation box matrix.

Parameters:dim (None or list of int, e.g., [2] for z axis, [0, 1] for x-y plane. If set to None, center on all three spatial dimensions) – dimensions to be centered on Return type:structure.Structure Returns:Modified cms model

schrodinger.application.desmond.packages.topo.cms_atom(cms_model)

Returns an iterator through all atoms in a cms model. At each iteration, we can get a tuple of (fsys_atom, comp_atom, comp_ct, ct_index), where

• fsys_atom: atom in full-system CT
• comp_atom: atom in component CT
• comp_ct: component CT to which `comp_atom’ belong
• ct_index: index of the component CT

schrodinger.application.desmond.packages.topo.comp_atoms(cms_model)

A coroutine to iterate through all atoms in all component CTs of the cms_model.

schrodinger.application.desmond.packages.topo.dehydrate(msys_model, cms_model, tr, water_gids, num_kept_water=200)

This function removes the majority of bulk waters, retaining a specified numbers of water molecules around a selected region.

This function assumes that the system has already been centered, such that the only N-number of waters are retained around the origin. This function returns a list of water GIDs, for each frame, that are the closest to the origin.

This approach has been tested on 3-pt and 4-pt waters with the systems that where set up with Desmond/Schrodinger tools. The assumptions being made are:

1. The water CT is the last idem of cms_model.comp_ct
2. The individual water molecules are organized in OHH order, where oxygen atom is folled by two hydrogen atoms.
3. If virtual site-containing water models are being used (like 4-pt), the virtual sites are ordered in the pseudo-block of ffio in same order as their corresponded water molecules.

Parameters:

• water_gids (list of int) – the GIDs of water molecules. The default order atoms in a water molecule is OHH. May also include pseudo atoms for 4- and 5-pt water models. (See assumptions above)
• num_kept_water (int) – total number of water molecules to retain

schrodinger.application.desmond.packages.topo.extract_subsystem(cms_model, asl)

We need to clarify on what we call ``subsystem’’ here. First, let’s review the hierarchical structure of a chemical system in the cms model:

• At the most top level is the whole system.
• Under that are a number of CTs (connectivity tables). Each CT contains one molecule (usually in the case of macromolecules), or more (the most obvious example is the water CT, which include thousands of water molecules).
• Under that are chains, which belong to the same molecule but not necessarily covalently bonded.
• Under that are residues, groups, atoms, pseudoatoms, …, which we don’t have to go into the detail.

Despite of the fact that there are already a lot of concepts to grasp, it’s still sometimes inadequate to describe a portion of the system. The problem arises mainly due to the fact that the cms model contains force field data: When we do atom selections, we have to keep that in mind, we won’t be able to create a valid .cms file if we select a number of atoms that don’t match the force field data.

To address that problem, we introduce an extra concept that sits between the CT and the molecule levels in the hierarchy. We can call it ``instance’‘, and it refers to a single complete substructure that matches the ffio. For example, in a protein CT, the ffio describe the whole protein structure, and so the instance there is the whole protein, and the CT contains only 1 instance; whereas in a water CT, the ffio describes only a single water molecule, and thus the instance is a single water molecule, and the CT contains a number of instances.

With that, we now define a subsystem as follows: A subsystem is a portion of the original system, containing 1 or more instances of any types as defined in the original system. By this definition, a subsystem should always be a valid cms model.

We allow users to specify a subsystem using ASL, but how do we deal with cases where the ASL expression doesn’t include a complete set of atoms in their respective instances? For now, we will simply automatically expand the selection to the whole instance. This is good enough for most cases, I think. Of course, in future we should have no problem to be more sophisticated in deciding to expand or shrink the selection.

Parameters:

• cms_model (cms.Cms) – A cms model generated by read_cms (see above). Won’t be mutated.
• asl (str) – ASL expression to specify the subsystem.

Return type:

(new-cms-model, seletion-in-gid)

Returns:

Returns a new cms.Cms object (the input cms_model will not be mutated), and an unsorted list of gids of the selected atoms ( which does NOT include any pseudoatoms).

schrodinger.application.desmond.packages.topo.get_aids_with_virtuals(cms_model)

Returns:a list of full-system AIDs that have virtual sites attached to them. Return type:set of int

schrodinger.application.desmond.packages.topo.glue(msys_model, gids, tr)

First, make-whole all molecules in the simulation system, and then glue the selected molecules together.

Parameters:

• msys_model (msys.System) – The msys model, which must be consistent with the trajectory in terms of the molecular topology. This object will not be mutated.
• gids (list) – A list of gids to specify the molecules to be glued
• tr (list) – The simulation trajectory to be modified

Return type:

list

Returns:

Modified simulation trajectory

schrodinger.application.desmond.packages.topo.glue_cms(msys_model, gids, cms_model)

Similar to glue (see above), but on a cms model instead of a simulation trajectory.

Both msys_model and cms_model must be previously obtained through the read_cms function. They both should have the same atom coordinates and the same simulation box matrix.

Return type:structure.Structure Returns:Modified cms model

schrodinger.application.desmond.packages.topo.make_glued_topology(msys_model, cms_model)

Add glued topology to msys_model, which contains with extra bonds based on proximity of the solute molecules. It works with _pfx_apply to properly center disjoint solute molecules (e.g., proteins with missing segments, dimers) The assumption is that the input msys_model has the correct spatial configurations.

schrodinger.application.desmond.packages.topo.make_whole(msys_model, tr)

In MD simulation, molecules can be broken due to the periodic bound condition, which makes some atoms be at one side of the simulation box and the other atoms at the opposite side. This function will edit the atom coordinates so to make broken molecules whole again for each frame of the MD trajectory tr.

Parameters:

• msys_model (msys.System) – The msys model, which must be consistent with the trajectory in terms of the molecular topology. This object will not be mutated.
• tr (list) – The simulation trajectory to be modified

Return type:

list

Returns:

Modified simulation trajectory

schrodinger.application.desmond.packages.topo.make_whole_cms(msys_model, cms_model)

Similar to make_whole (see above), but on a cms model instead of a simulation trajectory.

Both msys_model and cms_model must be previously obtained through the read_cms function. They both should have the same atom coordinates and the same simulation box matrix.

Return type:structure.Structure Returns:Modified cms model

schrodinger.application.desmond.packages.topo.pseudoatom_match(msys_model, cms_model)

This function will find the match between pseudoatoms and return it as a list of pseudoatom indices.

match = pseudoatom_match(msys_model) j = match[i]

where `j’ is the matched pseudoatom’s index in the ffio_pseudo block of the mutant CT, `i’ is the pseudoatom’s index in that of the reference CT. If `i’-th pseudoatom is not matched, `j’s value is zero. `match[0]’ is always junk and should be ignored.

For non-alchemical-FEP systems, this function returns an empty list.

schrodinger.application.desmond.packages.topo.read_cms(fname=None, from_string=None)

Read a .cms file from the given file name fname, or from a string buffer. How does this differ from cms.Cms(fname)? - Here, two models will be created for the given .cms file. So you will

get 2-tuple return value: The first member is the msys model, and the second is the cms model.

• The cms model returned by this function will give you correct gids, whereas the model returned by cms.Cms(fname) might not do so when there are virtual sites.

• The cms model returned by this function will have two extra attributes: - pseudoatoms This is a map from the gid of a physical atom to that

  of its pseudoatom(s).

  • pseudomatch This is pseudoatom match between the two alchemical molecules. (See the docstring of pseudoatom_match for detail)

Will we unite this with cms.Cms(fname)? Maybe. But I don’t see a strong motivation right now, and I don’t want to overengineer. -YW (May 26, 2016)

FIXME: msys.LoadMAE(...) is unbelievably slow and may take up to 10 sec for typically-sized alchemical FEP systems.

schrodinger.application.desmond.packages.topo.set_original_index_property(cms_model)

For each atom in the full-system CT, add an atom-level property: ‘i_m_original_index’, and set its value to the atom’s ID.

schrodinger.application.desmond.packages.topo.superimpose(msys_model, gids, tr, ref_pos, weights=None)

This function will do what center does, but in addition it will align and superimpose all the coordinates in the frame with respect to a reference coordinates (ref_pos). This operation will be applied to all frames in the trajectory.

Parameters:

• msys_model (msys.System) – The msys model, which must be consistent with the trajectory in terms of the molecular topology. This object will not be mutated.
• gids (list) – A list of gids to specify the molecules to be glued and centered
• tr (list) – The simulation trajectory to be modified
• ref_pos (numpy.array. 3xN matrix, where N is length of gids.) – Reference coordinates used for alignments
• weights (list or None) – Atom weights used for alignments. If it’s None, all atoms will be weighted equally.

Return type:

list

Returns:

Modified simulation trajectory

schrodinger.application.desmond.packages.topo.superimpose_cms(msys_model, gids, cms_model, ref_pos, weights=None)

Similar to superimpose (see above), but on a cms model instead of a simulation trajectory.

Both msys_model and cms_model must be previously obtained through the read_cms function. They both should have the same atom coordinates and the same simulation box matrix.

Return type:structure.Structure Returns:Modified cms model

schrodinger.application.desmond.packages.topo.update_cms(cms_model, frame, update_pseudoatoms=True)

Updates the given cms model cms_model with the atom coordinates and the simulation box matrix from a simulation frame frame.

N.B.: If you call this function for every frame of a long trajectory, you might find this function is quite slow. Also keep in mind that its performance has a strong dependency on the number of atoms in the system. If all that you want is a full-system CT with atom coordinates updated by the trajectory frame, consider using the update_fsys_ct function above, which is much faster than this function.

Return type:structure.Structure Returns:The same input cms_model object, which has been updated on the atom coordinates and the simulation box matrix.

schrodinger.application.desmond.packages.topo.update_cms_box(ct, box)

Given a ct, set the following CT-level properties using the values from box:

“r_chorus_box_ax”, “r_chorus_box_ay”, “r_chorus_box_az”, “r_chorus_box_bx”, “r_chorus_box_by”, “r_chorus_box_bz”, “r_chorus_box_cx”, “r_chorus_box_cy”, “r_chorus_box_cz”,

Return type:structure.Structure Returns:The same input ct object, whose “r_chorus_box_*” CT-level properties has been updated by this function.

schrodinger.application.desmond.packages.topo.update_cms_physical(cms_model, pos, vel, box)

Update the physical data of a cms model. The physical data include all atom positions and velocities and also the box matrix.

Parameters:cms_model (structure.Structure) – The cms model to be updated. This model does NOT have to be created by the read_cms function.

schrodinger.application.desmond.packages.topo.update_fsys_ct(cms_model, frame, gids=None)

Updates coordinates and simulation-box-matrix of only the full-system CT with the given trajectory frame.

N.B.: This function doesn’t update the velocities.

Parameters:gids – It should correspond to all atoms in cms_model Return type:structure.Structure Returns:The same input cms_model object, which has been updated on the atom coordinates and simulation box matrix of only the full-system CT.

schrodinger.application.desmond.packages.topo.update_msys(msys_model, frame)

Updates the given msys model msys_model with the atom coordinates and velocities and the simulation box matrix from a simulation frame frame.

Return type:msys.System Returns:The same input msys_model object, which has been updated on the atom coordinates and velocities and the simulation box matrix.