Module topo

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

Returns: list of int

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).

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.

Parameters:

• msys_model (msys.System)
• cms_model (cms.Cms. This object should be created by the read_cms(...) function (see below).)

Read a .cms file from the given file name C{fname}.
How does this differ from C{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 C{cms.Cms(fname)} might not do so when
  there are virtual sites.
- The cms model returned by this function will have two extra attributes:
  - C{pseudoatoms} This is a map from the gid of a physical atom to that
    of its pseudoatom(s).
  - C{pseudomatch} This is pseudoatom match between the two alchemical
    molecules. (See the docstring of L{pseudoatom_match} for detail)

Will we unite this with C{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: C{msys.LoadMAE(...)} is unbelievably slow and may take up to 10 sec
for typically-sized alchemical FEP systems.

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 convalently 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.

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

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).

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

Parameters:

• cms_model (cms.Cms)

Given a C{ct}, set the following CT-level properties using the values from
C{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",

@type box: Any type that supports double subscriptions like C{box[0][1]},
           where both indices are zero-based.

@rtype: L{structure.Structure}
@return: The same input C{ct} object, whose "r_chorus_box_*" CT-level
         properties has been updated by this function.

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

FIXME: Currently, this function doesn't update the velocities.

Parameters:

• cms_model (structure.Structure)
• frame (Duck type (see DuckFrame for the interface requirements).)

Returns: structure.Structure

The same input cms_model object, which has been updated on the atom coordinates and the simulation box matrix.

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

Parameters:

• msys_model (msys.System)
• frame (Duck type (see DuckFrame for the interface requirements).)

Returns: msys.System

The same input msys_model object, which has been updated on the atom coordinates and velocities and the simulation box matrix.

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).

Returns: list of int

A list of gids of the selected particles

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

Returns: list of int

An unsorted list of gids of the selected particles

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

Returns: list

Modified simulation trajectory

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

Returns: list

Modified simulation trajectory

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

Returns: list

Modified simulation trajectory

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.

Returns: structure.Structure

Modified 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.

Returns: structure.Structure

Modified cms model

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.

Returns: structure.Structure

Modified cms model