schrodinger.application.desmond.packages.staf module

Simulation Trajectory Analysis Framework (STAF)

Copyright Schrodinger, LLC. All rights reserved.

class schrodinger.application.desmond.packages.staf.GeomAnalyzerBase(*args, **kwargs)

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.

A dynamic analyzer (or dynalyzer) redefines its calculations from frame to frame, typically due to atom selection change, i.e., dynamic ASL.

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 we regard dynamic analyzer as the more general concept. This means that a static analyzer is a dynamic analyzer with trivial (nil) dependency on the coordinates.

All subclasses should define two private methods:

  • _precalc

    • This method will be called by a GeomCalc object to register geometry calculations.

  • _postcalc

    • This 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) to calculate all requested geometry calculation frame by frame. Also see the docstring of the analysis.analyze function.

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

  • _dyncalc

    • This method will be called by a GeomCalc object to register geometry calculations for each trajectory frame.

__init__(is_dynamic=False)
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 center the selected particles in the copy.

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.

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

This function will copy the input trajectory frame (fr), and center the selected particles along the Z-axis in the copy.

Returns

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

class schrodinger.application.desmond.packages.staf.CenteredSoluteAnalysis(*args, **kwargs)

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, asl_center='solute', asl_exclude='ions or water or metals', **kwarg)
Parameters

  • asl_center – ASL for the atoms to be centered

  • asl_exclude – ASL for the atoms to be excluded from centering. For example, ASL ‘protein’ could select ion and water molecules which may be too mobile for the centering.

class schrodinger.application.desmond.packages.staf.MaestroAnalysis(*args, **kwargs)

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

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

class schrodinger.application.desmond.packages.staf.CustomMaestroAnalysis(*args, **kwargs)

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)
class schrodinger.application.desmond.packages.staf.CompositeAnalyzer(*args, **kwargs)

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.

class schrodinger.application.desmond.packages.staf.UpdatedCmsFsysCtAnalysis(*args, **kwargs)

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

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

N.B.: Typically all analyzers share the same Cms object, thus 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)
class schrodinger.application.desmond.packages.staf.DynamicPositerAnalyzer(*args, **kwargs)

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

This analyzer uses (dynamic) atom selection to create Positer for each frame.

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

class schrodinger.application.desmond.packages.staf.DynamicAslAnalyzer(*args, **kwargs)

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

A base class for all analyzers that support dynamic ASL expressions. It guarantees to update the atom IDs from the given ASL expression for each frame and store the atom IDs into a private attribute _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)
class schrodinger.application.desmond.packages.staf.CompositeDynamicAslAnalyzer(*args, **kwargs)

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 (see docstring of DynamicAslAnalyzer), which will be automatically called by the DynamicAslAnalyzer._dyncalc method (see docstring of DynamicAslAnalyzer for more detail).

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

Bases: object

This class appends analyzers’ results to trajectory frames. The prominent application is to treat Com, Coc, or Centroid analyzers as composite “atoms” with GIDs, which enables geometric calculations among both regular atoms and composite “atoms”.

__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 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 minimum 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 periodic boundary condition.

Basic usage:

calc = GeomCalc()

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

# Does calculations. calc(pbc, frame)

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

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

addFittedPlanarAngle(i_gids: List[int], j_gids: List[int])

Add a fitted planar angle calculation request. The first list of gids defines the first group of atoms and the second list of gids defines the second group, for each of which a best-fitting plane is calculated.

Parameters

._gids – The gids defining each group of atoms

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

getFittedPlanarAngle(i_gids: List[int], j_gids: List[int])

Get the fitted planar angle (in radians) as defined by the two lists: i_gids and j_gids. See the docstring of addFittedPlanarAngle for more detail.

getCustom(cid)

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