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 theself._result
In between the
_precalc
and_postcalc
calls, theGeomCalc
object will be called (outside the analyzer class) to calculate all requested geometry calculation frame by frame. Also see the docstring of theanalysis.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 givenfr
.
- 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 givenfr
.
- 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 givenfr
.
- 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 ofMaestroAnalysis
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.
- 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 theGeomCalc
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 ofDynamicAslAnalyzer
), which will be automatically called by theDynamicAslAnalyzer._dyncalc
method (see docstring ofDynamicAslAnalyzer
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
, orCentroid
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, aCom
, orCoc
, orCentroid
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
ofint
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)
, wherepbc
is aPbc
object, andfr
is atraj.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 bypositer
- 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:
_precalc(self, calc) where
calc
is aGeomCalc
object. This method should callcalc.addCustom
to add an calculation item of a custom calculation type._postcalc(self, calc, pbc, fr) where
calc
is aGeomCalc
object,pbc
is aPbc
object, andfr
is atraj.Frame
object. This method can get the calculation result by callingcalc.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
andto_gid
.
- getDistance(i_gid, j_gid)¶
Get the distance (in Angstroms) between the atoms:
i_gid
andj_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
, andl_gid
. See the docstring ofaddTorsion
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
, andn_gid
. See the docstring ofaddPlanarAngle
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
andj_gids
. See the docstring ofaddFittedPlanarAngle
for more detail.
- getCustom(cid)¶
Return all results of the custom calculation type
c
:type cid: Any hashable object