schrodinger.application.desmond.packages.staf module

Simulation Trajectory Analysis Framework (STAF)

Copyright Schrodinger, LLC. All rights reserved.

class schrodinger.application.desmond.packages.staf.GeomAnalyzerBase(is_dynamic=False)

Bases: object

Base class of all geometry analyzer classes

At this level, we make a distinction of two types of analyzers: static and dynamic analyzers, which we call staalyzers and dynalyzers, respectively, in short.

A dynamic analyzer (or dynalyzer) is one that the exact calculations that it needs have to be re-defined from frame to frame. One typical case is when the user uses dynamic ASL expressions to select atoms for geometry calculations, because the selected atoms may differ from frame to frame, the exact geometry calculations will have to be redetermined with the coordinates of the particles in each frame.

Generally speaking, any analyses where the exact types and/or quantities of calculations depend on the dynamics of the simulation system will fall into the conceptual regime of dynamic analyzer.

A static analyzer (or staalyzer) is the opposite. The exact types and/or quantities of calculations are predefined and doesn’t depend on the coordinates of the particles.

Also note that we regard dynamic analyzer as the more general concept. This means that a static analyzer is a dynamic analyzer that has trivial (nil) dependency on the coordinates.

All subclasses are expected to define two private methods:

• _precalc - This private method will be called by a GeomCalc object to register

  wanted geometry calculations.

• _postcalc - This private method will be called by a GeomCalc object to finish

  the particular analysis calculation. And the results should are saved in the self._result

In between the _precalc and _postcalc calls, the GeomCalc object will be called (outside the analyzer class) for the current frame to calculate all requested geometry calculation. Also see the docstring of the analysis.analyze function.

For dynalyzers, the subclass is expected to define one more private method:

• _dyncalc - This private method will be called by a GeomCalc object to register

  wanted geometry calculations for each trajectory frame.

__init__(is_dynamic=False)

Initialize self. See help(type(self)) for accurate signature.

disableDyncalc()

Disable the execution of _dyncalc(). This is used to avoid redundant _precalc() calculations delegated in _dyncalc().

isDynamic()

schrodinger.application.desmond.packages.staf.center_fr(data, pbc, fr, custom)

This function will copy the input trajectory frame (fr), and in the copy frame the selected particles will be centered.

Returns:Updated data, where values are updated for the given fr.

schrodinger.application.desmond.packages.staf.center_ct(data, pbc, fr, custom)

Center selected particles in the simulation box, and it will automatically make all molecules whole. This function will create a centered frame and a copy of the full system CT from the centered frame.

Caveat: center_fr should have been called on the same key and frame. This is an implicit coupling (bad) between the two functions.

Returns:Updated data, where values are updated for the given fr.

class schrodinger.application.desmond.packages.staf.CenteredSoluteAnalysis(msys_model, cms_model, *arg, **kwarg)

Bases: schrodinger.application.desmond.packages.staf.GeomAnalyzerBase

This class provides a temporary trajectory frame where the solute atoms are centered. It helps resolve PBC wrapping issues for analyzers such as analysis.RMSD, analysis.PosAlign.

__init__(msys_model, cms_model, *arg, **kwarg)

Initialize self. See help(type(self)) for accurate signature.

disableDyncalc()

Disable the execution of _dyncalc(). This is used to avoid redundant _precalc() calculations delegated in _dyncalc().

isDynamic()

class schrodinger.application.desmond.packages.staf.MaestroAnalysis(msys_model, cms_model, *arg, **kwarg)

Bases: schrodinger.application.desmond.packages.staf.CenteredSoluteAnalysis

Analyzer classes that perform calculations based on the solute-centered full-system CT could inherit this base class.

__init__(msys_model, cms_model, *arg, **kwarg)

Initialize self. See help(type(self)) for accurate signature.

disableDyncalc()

Disable the execution of _dyncalc(). This is used to avoid redundant _precalc() calculations delegated in _dyncalc().

isDynamic()

class schrodinger.application.desmond.packages.staf.CustomMaestroAnalysis(msys_model, cms_model, func)

Bases: schrodinger.application.desmond.packages.staf.MaestroAnalysis

Compute the result of a custom function on centered models. Under the hood, this custom function serves as a CID for _CustomCalc. The same key of MaestroAnalysis is used, and the value is a tuple of the custom function’s return and the centered fullsystem CT.

__init__(msys_model, cms_model, func)

disableDyncalc()

Disable the execution of _dyncalc(). This is used to avoid redundant _precalc() calculations delegated in _dyncalc().

isDynamic()

class schrodinger.application.desmond.packages.staf.CompositeAnalyzer(is_dynamic=False)

Bases: schrodinger.application.desmond.packages.staf.GeomAnalyzerBase

A composite analyzer calls one or more other analyzers (subanalyzers) to obtain (intermediate) results. The subclass should define the subanalyzers as a private attribute: _analyzers, whose value should be a list of analyzers.

__init__(is_dynamic=False)

Initialize self. See help(type(self)) for accurate signature.

disableDyncalc()

Disable the execution of _dyncalc(). This is used to avoid redundant _precalc() calculations delegated in _dyncalc().

isDynamic()

class schrodinger.application.desmond.packages.staf.UpdatedCmsFsysCtAnalysis(msys_model, cms_model, *arg, **kwarg)

Bases: schrodinger.application.desmond.packages.staf.GeomAnalyzerBase

This class updates the full system CT inside the cms object to each trajectory frame.

Since typically all analyzers share the same cms object, the existence of an instance of this class has side effect on other analyzers (This side effect is probably wanted).

__init__(msys_model, cms_model, *arg, **kwarg)

Initialize self. See help(type(self)) for accurate signature.

disableDyncalc()

Disable the execution of _dyncalc(). This is used to avoid redundant _precalc() calculations delegated in _dyncalc().

isDynamic()

class schrodinger.application.desmond.packages.staf.DynamicPositerAnalyzer(msys_model, cms_model, asl, initializer)

Bases: schrodinger.application.desmond.packages.staf.UpdatedCmsFsysCtAnalysis

__init__(msys_model, cms_model, asl, initializer)

Parameters:initializer (callable) – It takes three input arguments (msys_model, cms_model, and a list of AIDs) and returns a Positer instance.

disableDyncalc()

Disable the execution of _dyncalc(). This is used to avoid redundant _precalc() calculations delegated in _dyncalc().

isDynamic()

class schrodinger.application.desmond.packages.staf.DynamicAslAnalyzer(msys_model, cms_model, asl)

Bases: schrodinger.application.desmond.packages.staf.UpdatedCmsFsysCtAnalysis

A base class for all analyzers that support dynamic ASL expressions. This base class will guarantee to update the atom IDs from the given ASL expression for each frame and store the atom IDs into a private attribuate _aids.

This class defines the private method _dyncalc to be called by the GeomCalc object. This class expects its subclass to define a _dyninit(self)' method to be automatically called by the `_dyncalc method after the _aids has been updated. The subclass’ _dyninit method should redefine the geometry calculations based on the updated atom IDs and will be called by both the __init__ and the _dyncalc methods of this class.

__init__(msys_model, cms_model, asl)

disableDyncalc()

Disable the execution of _dyncalc(). This is used to avoid redundant _precalc() calculations delegated in _dyncalc().

isDynamic()

class schrodinger.application.desmond.packages.staf.CompositeDynamicAslAnalyzer(msys_model, cms_model, asl)

Bases: schrodinger.application.desmond.packages.staf.DynamicAslAnalyzer, schrodinger.application.desmond.packages.staf.CompositeAnalyzer

A base class for analyzers whose ALL subanalyzers are redefined for each frame based on the results of the dynamic ASL expression. The redefinition of subanalyzers are done by the analyzer’s _dyninit method docstring of DynamicAslAnalyzer), which will be automatically called by the DynamicAslAnalyzer._dyncalc method (see the docstring of DynamicAslAnalyzer for more detail).

__init__(msys_model, cms_model, asl)

disableDyncalc()

Disable the execution of _dyncalc(). This is used to avoid redundant _precalc() calculations delegated in _dyncalc().

isDynamic()

class schrodinger.application.desmond.packages.staf.Positer(analyzers, num_pos)

Bases: object

A class to create a positer object for use with the GeomCalc class.

__init__(analyzers, num_pos)

Parameters:analyzers (list. Each element can be an analyzer, for example, a Com, or Coc, or Centroid object.) – A list of analyzers. Each analyzer will return a new position.

setGidOffset(gid_offset)

Parameters:gid_offset (int) – The GID of the first position added by this positer will be natoms + gid_offset, where natoms is the number of interaction sites in the original model system.

numPos()

Return type:int Returns:The number of new positions to be added into the position array of the given frame.

gids()

Return type:list of int objects Returns:The GIDs of the new positions to be added.

class schrodinger.application.desmond.packages.staf.GeomCalc

Bases: object

We use this class to batch the geometry calculations and avoid duplications. For example, you want to calculate the bond distance between atoms 1 and 2, and also an dihedral angle involving these two atoms. Both calculations require to calculate the vector between the mininum images of the two atoms, but we don’t want to do the calculation twice. With this class, we avoid such duplications.

All geometry calculations take into account the peridoic boundary condition.

Basic usage:

calc = GeomCalc()

# Loads geometry-calculation requests. calc.addVector(…) calc.addDistance(…) calc.addAngle(…) calc.addTorsion(…) calc.addPlanarAngle(…)

# Does calculations. calc(pbc, frame)

# Gets results. vec = calc.getVector(…) dis = calc.getDistance(…) ang = calc.getAngle(…) dih = calc.getTorsion(…) pla = calc.getPlanarAngle(…)

__init__()

Initialize self. See help(type(self)) for accurate signature.

addPosition(positer, num_pos, is_dynamic=False)

Add extra position into the position array.

Parameters:

• positer (Callable, will be called as: positer(pbc, fr), where pbc is a Pbc object, and fr is a traj.Frame object.) – Function (or callable object) to append new positions into the position array of the given frame.
• num_pos (int, must be a nonnegative number.) – The number of new positions to be added by positer

Return type:

int

Returns:

The gid offset of the first new position that will be generated by this positer.

addVector(from_gid, to_gid)

Add a vector calculation request.

addDistance(i_gid, j_gid)

Add a distance calculation request.

addAngle(i_gid, j_gid, k_gid)

Add an angle calculation request.

The angle is defined by the two vectors: j==>i and j==>k.

addTorsion(i_gid, j_gid, k_gid, l_gid)

Add a torsion calculation request.

The torsion is defined by the four position vectors:

i o o l

/

/

j o—–o k

In other words, it’s the dihedral angle between the two planes: i-j-k and j-k-l.

addPlanarAngle(i_gid, j_gid, k_gid, l_gid, m_gid, n_gid)

Add a planar angle calculation request. The first three gids define the first plane and the second gids define the second plane. The acute angle between these two planes is returned.

addCustom(cid, key=None, default=None)

Add a custom calculation item.

Parameters:

• cid (Any hashable object) – Specify the type of the calculation. The results of this type of calculation can be obtained by calling getCustom(c).
• key (Any hashable object) – A particular calculation item of the type c. The result of this item can be obtained by this: getCustom(c)[key].
• default – The default result of the calculation item key.

addAnalyzer(analyzer)

Add a custom analyzer. :type analyzer: Duck type that must define the following interface:

1. _precalc(self, calc) where calc is a GeomCalc object. This method should call calc.addCustom to add an calculation item of a custom calculation type.
2. _postcalc(self, calc, pbc, fr) where calc is a GeomCalc object, pbc is a Pbc object, and fr is a traj.Frame object. This method can get the calculation result by calling calc.getCustom and do further calculations as necessary to get the final analytic results.

getVector(from_gid, to_gid)

Get the vector between the atoms: from_gid and to_gid.

getDistance(i_gid, j_gid)

Get the distance (in Angstroms) between the atoms: i_gid and j_gid.

getAngle(i_gid, j_gid, k_gid)

Get the angle (in radians) between the two vectors: j==>i and j==>k.

getTorsion(i_gid, j_gid, k_gid, l_gid)

Get the torsion (in radians) as defined by the four atoms: i_gid, j_gid, k_gid, and l_gid. See the docstring of addTorsion for more detail.

getPlanarAngle(i_gid, j_gid, k_gid, l_gid, m_gid, n_gid)

Get the planar angle (in radians) as defined by the six atoms: i_gid, j_gid, k_gid, l_gid, m_gid, and n_gid. See the docstring of addPlanarAngle for more detail.

getCustom(cid)

Return all results of the custom calculation type c :type cid: Any hashable object