Potential restraints

Potential restraints are a family of EnergyFunctionComponent instances that apply any given potential to a selection of Atom instances, optionally further masked or mapped. In other words, the application of a potential restraint to a Pose is characterized by a series of fully customizable steps to generate new and/or improved Potential restraints:

(Optional) Select a subset of Atom instances to apply the potential;
Define the potential function to be applied (See Available potentials);
Apply the potential mask to the selected Atom instances;
(Optional) Multiply a mask/map to the calculated energy and forces matrices;
Sum the calculated energy and forces matrices.

Note:

Most of these EnergyFunctionComponent instances are specific for a certain type of molecules (such as Peptides). The following types and methods constitute the backbone for all Potential restraints, but more specific applications can be found in other modules of ProtoSyn.

ProtoSyn Potential Restraint

Figure 1 | A diagram representation of the application of a potential restraint, in ProtoSyn. A given potential function (See Available potentials) is applied to a distance matrix (See Distance matrix calculation) calculated from the distances between all selected Atom instances. The resulting 2D energy matrix includes the energy values for each pair of interacting Atom instances. An optional secondary output from the application of the potential function is a 3D forces matrix, with the forces felt on each atom from the interaction with its pair. Both these matrices can optionally suffer another step: the application of a mask or map. On one hand, a Mask, similarly to its application in AbstractSelections, turns on and off certain pairs of interacting atoms. As an example, a mask allows the user to ignore same-atom energy artifacts using a get_diagonal_mask or ignore interaction between atoms of the same residue using an get_intra_residue_mask. On the other hand, a map in a 2D matrix (with the same size as the 2D energy matrix) with weights and biases. When the two matrices are multiplied together, certain interaction strengths are increased while others are reduced. An example would be the application of a contact map, where each weight corresponds to the certainty factor for the distance between each of the considered Atom pairs. As a final step both the 2D energy matrix and the 3D forces matrix (optionally after the application of the mask/map) are summed (in both axis, in the case of energy calculation, and in one axis, in the case of forces calculation).

Note:

The above paradigm for application of potential restraints requires, for the correct calculation of forces, the full_distance_matrix to be considered. This causes the energy value calculated to be double the expected (not considering the application on any non diagonally symmetrical mask), as both the top and bottom triagonal matrices are considered. In most cases this is not an issue, as the energy values are compared between simulation frames in relation to eachother and therefore the scale of the value is not important. However, in specific applications, further adjustment of the potential and/or mask applied may be necessary.

The following section is subdivided in the following topics, for organizational purposes:

Base methods
Available potentials
Creating custom potential functions
Available masks
Creating custom masks
Available Potential Restraint EnergyFunctionComponents

Base methods

The following methods are ubiquous to all Potential restraints:

ProtoSyn.Calculators.apply_potential! — Function

apply_potential!([A::Type{<: ProtoSyn.AbstractAccelerationType}], pose::Pose, potential::Function, update_forces::Bool, [verlet_list::Union{VerletList, Nothing}], [selection::Union{Nothing, ProtoSyn.AbstractSelection}], [mask::MaskMap])

Apply the given potential to the provided Pose pose. If the update_forces flag is set to true, also calculate the forces acting on the system. The call to this function can be further customized by providing an optional VerletList, an AbstractSelection selection or a MaskMap map (this can be a Mask, a Matrix or a Function).

Examples

julia> ProtoSyn.Calculators.apply_potential!(ProtoSyn.SISD_0, pose, (d; kwargs...) -> 0.0, false, nothing, nothing, nothing)
(0.0, [0.0 0.0 … 0.0 0.0; 0.0 0.0 … 0.0 0.0; 0.0 0.0 … 0.0 0.0])

Potential restraints

Base methods

Available potentials

Creating custom potential functions

Available masks

Creating custom masks

Available Potential Restraint EnergyFunctionComponents