.. _sec-sideChainPrediction: SideChainPrediction Block in Pele++ control file ================================================ This block configures the Side Chain Prediction phase in a ``peleSimulation`` command, or the Side Chain Prediction execution of a ``sideChainSimulation`` command. In a ``peleSimulation``, this phase will be active depending on the ``sideChainPredictionFrequency`` PELE parameter (:ref:`sec-peleParameters-sideChainPredictionFrequency`). The side chain prediction will be applied to the set of links formed by: - if ``sideChainPredictionRegionRadius`` (:ref:`sec-peleParameters-sideChainPredictionRegionRadius`) is not zero, then the links to perturb (if the perturbation phase is active) and all those other links that are at most ``sideChainPredictionRegionRadius`` :math:`\AA{}` away from the links to perturb. - the *top side links*, which are those links that worsen their energy the most between the beginning of a PELE step and the end of the perturbation and ANM phase. The number of these links is selected by the PELE parameter ``numberOfTopSideSelectedLinks`` (:ref:`sec-peleParameters-numberOfTopSideSelectedLinks`). Also the links that are at most ``topSideRadius`` :math:`\AA{}` away from the *top side links* (:ref:`sec-peleParameters-topSideRadius`) will be included. - the links selected with ``selectionToInclude`` (:ref:`sec-sideChainPrediction-selectionToInclude`). - removing, from all the links previously selected, those links in ``selectionToOmit`` (:ref:`sec-sideChainPrediction-selectionToOmit`). Notice that links without side chains and cross linked cysteines are not considered in the side chain prediction. Algorithm selection ------------------- algorithm ^^^^^^^^^ Use: It sets the side chain prediction algorithm that will be used. Possible options: - "zhexin": Iterative algorithm that predicts the side chain conformation for each link until it reaches convergence - "boltzmannSampling": Algorithm that samples the rotamers according to the Boltzmann distribution at a given temperature T Default value: ``"zhexin"``. Brief description of the algorithms ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - Zhexin algorithm: It is an iterative algorithm that tries to find the most likely rotamer. To do so, it clusters the rotamers and estimates the partition function. It chooses the rotamer that has the greatest contribution. It is performed several times, until convergence is reached. - Boltzmann Sampling: It chooses a random rotamer according to the Boltzmann distribution. For all the non-clashing rotamers, their energies are evaluated and assigned their Boltzmann weight :math:`\frac{e^{-\beta E}}{\sum e^{-\beta E}}`. One is chosen according to this weight. Links selection --------------- .. _sec-sideChainPrediction-selectionToInclude: selectionToInclude ^^^^^^^^^^^^^^^^^^ Parameter: Selector\* selector Use: String used to select the links to which the side chain prediction is going to be performed. Note: It uses the standard jSon format. This example selects from link "2" to "4" in the chain "A": .. code-block:: json "selectionToInclude": { "links": {"ranges": ["A:2 A:4"] } } For a more detailed description, see :ref:`sec-selectionExamples`. .. _sec-sideChainPrediction-selectionToOmit: selectionToOmit ^^^^^^^^^^^^^^^ Parameter: Selector\* omit Use: String used to select the links to which the side chain prediction is never going to be performed. Note: It uses the standard jSon format. Omit prevails over include, i.e. if a link is chosen in both lists, it is omitted. See :ref:`sec-selectionExamples`. .. _sec-sideChainPrediction-parameters: Parameters ---------- resolution ^^^^^^^^^^ Parameter: double gridres Use: Resolution of the rotamer library to be used for the 'non-polar' part of non-ligand links (the polar part always uses the resolution given in the link-type rotamer library file for the polar atom). Ligand links always use the resolution stated in the rotamer library file for that link; therefore this parameter does not affect them. The angles a rotamer can take are divided in bins of length 'gridres' degrees. Note for developers: Used all along the side chain prediction. Units: Degrees Range: It can take any value, generally 10, 20, 30, 40 (these are the only values allowed for standard protein residues). If an unsupported resolution is chosen, it is set to the base resolution for each type of link, which is 10 in the standard protein residues. Default value: 10 Plop info: - Plop control file name: 'gridres' - Plop parameter name: 'side\_params%gridres' - Plop default value: 10 .. _sec-sideChainPrediction-parameters-overlapfactor: Overlap factor ^^^^^^^^^^^^^^ We consider that two atoms are clashing when: d12 < overlap\_factor \* (rvdw,1 + rvdw,2) where d12 is the distance between them and rvdw,i is the Van der Waals radius of the i-th atom. The program starts looking for non-clashing rotamers with an overlap factor = initial overlap factor. If it does not find any suitable rotamer (i.e. the algorithm failed), it decreases its value deltaOverlapFactor (=0.05). The process is repeated until overlap factor = minimal overlap factor. initialOverlapFactor ^^^^^^^^^^^^^^^^^^^^ Parameter: double initialOverlapFactor Use: Initial overlap factor. Note for developers: Used in ZhexinSideChainAlgorithm::run Units: Dimensionless Default value: 0.75 Plop info: - Plop control file name: 'ofac\_init' - Plop parameter name: 'tree\_params%ofac\_init' - Plop default value: 0.75 minimalOverlapFactor ^^^^^^^^^^^^^^^^^^^^ Parameter: double minimalOverlapFactor Use: Minimal overlap factor. It is also used when we want a loose selection of non-clashing rotamers. Note for developers: Used everywhere we need to know if the algorithm failed. Units: Dimensionless Default value: 0.7 Plop info: - Plop control file name: 'ofac\_min' - Plop parameter name: 'tree\_params%ofac\_min' - Plop default value: 0.7 randomize ^^^^^^^^^ Parameter: bool randomize Use: It only makes sense when the 'zhexin' algorithm is used. It randomizes the initial conformation of the selected links' side chains. When it is false, ``numberOfIterations`` is not considered, since it becomes effectively 1. Notes for developers: Used in ZhexinSideChainAlgorithm::findMinimumInEnergyUsingRotamerLibrary and ZhexinSideChainAlgorithm::findMinimumInEnergyUsingRotamerLibrary Default value: false Plop info: - Plop control file name: 'rand' - Plop parameter name: 'side\_params%randomize' - Plop default value: False discardHighEnergySolutions ^^^^^^^^^^^^^^^^^^^^^^^^^^ Parameter bool discardHighEnergySolutions Use: If the side chain prediction does not have backbone clashes (though it may have side chain clashes), but the solution structure has an energy higher than the initial energy (at least, 10 kcal/mol), then that solution is discarded if this parameter is true. When discarded, the initial structure is retained. Default value: false Plop info: - Plop control file name: 'failsafe' - Plop parameter name: 'side_params%failsafe' - Plop default value: True numberOfIterations ^^^^^^^^^^^^^^^^^^ Parameter: unsigned int numberOfIterations Use: Number of iterations that the 'zhexin' algorithm is going to perform. This is only considered when ``randomize`` is true; otherwise, the effective number of iterations is 1. Notes for developers: Used in ZhexinSideChainAlgorithm::findMinimumInEnergyUsingRotamerLibrary Units: Dimensionless Range: [0, inf) Default value: 1 Plop info: - Plop control file name: 'iter' - Plop parameter name: 'side\_params%niter' - Plop default value: 1 temperature ^^^^^^^^^^^ Parameter: double temperature Use: Temperature to sample the rotamers in the 'boltzmannSampling' algorithm Notes for developers: Used in SideChain::computeNonClashingRotamersProbabilities Default value: 2000 Plop info: - Plop control file name: - - Plop parameter name: - - Plop default value: - skipGlobalMinimization ^^^^^^^^^^^^^^^^^^^^^^ Parameter: bool skipGlobalMinimization Use: Flag to activate or deactivate the final relaxation minimization performed at the end of a side chain prediction. Note for developers: Used in PeleStep::relax Default value: false .. _sec-sideChainPrediction-sideChainPredictionMinimizer: sideChainMinimizer ------------------ Minimizer block. If this block is not present, then no side chain prediction minimization is run. Check the minimization block documentation (:ref:`sec-minimization`) for more information. If this section is present, then this minimization is run at the end of each side chain prediction iteration; the minimization affects only the atoms considered during the side chain prediction. In this case (the "sideChainMinimizer" block is present, so the internal minimization will be performed), the default minimization type is "TruncatedNewton", with the following default parameters (other parameters have the same default as shown in the minimization block documentation): - "EnergyDifference": 1.0 - "MinimumRMS": 0.1 - "MaximumMinimizationIterations": 3 - "MaximumNewtonIterations": 65, - "nonBondingListUpdatedEachMinStep": true - "alphaUpdated": false - "sgbUpdated": true - "iterationsBetweenNBlistLongUpdate": 2 If the perturbation is active, also the perturbation constraints will be on (see :ref:`sec-peleParameters-perturbationCOMConstraintConstant`). The permanent constraints (:ref:`sec-permanentConstraints`) are also on. By default, a final relaxation minimization is executed at the end of the side chain prediction phase in a PELE simulation, but this is configured in the ``"Minimizer"`` section of such command (see :ref:`sec-minimization`). This behaviour can be changed with the flag skipGlobalMinimization.