Action: HBPAMM_SA
| Module | pamm |
|---|---|
| Description | Usage |
| Calculate the number of hydrogen bonds each acceptor participates in using the HBPamm method |   |
| output value | type |
| a vector specifiying the number of hydrogen bonds each of the specified atoms participates within | vector |
Details and examples
Calculate the number of hydrogen bonds each acceptor participates in using the HBPamm method
This shortcut action allows you to calculate the number of hydrogen bonds each of the atoms specified using the SITES keyword accepts from its neighbours. The number of hydrogen bonds that a particular site accepts is determined by using the PAMM tehcnique that is discussed in the articles from the bibliography below and in the documentation for the PAMM action
The following example shows how you can use this action to calculate how many hydrogen bonds each of the water moecules in a box of water accepts from its neighbours.
#SETTINGS INPUTFILES=regtest/pamm/rt-hbpamm/b3lyp.pamm acceptors: HBPAMM_SACalculate the number of hydrogen bonds each acceptor participates in using the HBPamm method This action is a shortcut. More details ... SITESThe list of atoms which can be part of a hydrogen bond=1-192:3 HYDROGENSThe list of hydrogen atoms that can form part of a hydrogen bond=2-192:3,3-192:3 CLUSTERSthe name of the file that contains the definitions of all the kernels for PAMM=regtest/pamm/rt-hbpamm/b3lyp.pammClick here to see an extract from this file.REGULARISE don't allow the denominator to be smaller then this value=0.001 GAUSS_CUTOFF the cutoff at which to stop evaluating the kernel function is set equal to sqrt(2*x)*(max(adc)+cov(adc))=6.25 ... DUMPATOMSDump selected atoms on a file. More details ARGthe labels of vectors that should be output in the xyz file=acceptors ATOMSthe atom indices whose positions you would like to print out=1-192:3 FILEfile on which to output coordinates; extension is automatically detected=acceptors.xyz
The output here is an xyz with five columns. As explained in the documentation for DUMPATOMS, the first four columns are the usual columns that you would expect in an xyz file. The fifth column then contains the number of hydrogen bonds that have been accepted by each of the atoms.
In the example input above all the atoms specified using the SITE keyword can both accept and donate hydrogen bonds. If the group of atoms that can accept hydrogen bonds is different from the group of atoms that can donate hydrogen bonds then you use the ACCEPTORS and DONORS keyword as shown below:
#SETTINGS INPUTFILES=regtest/pamm/rt-hbpamm/b3lyp.pamm acceptors: HBPAMM_SACalculate the number of hydrogen bonds each acceptor participates in using the HBPamm method This action is a shortcut. More details ... ACCEPTORSThe list of atoms which can accept a hydrogen bond=1-9:3 DONORSThe list of atoms which can donate a hydrogen bond=1-192:3 CLUSTERSthe name of the file that contains the definitions of all the kernels for PAMM=regtest/pamm/rt-hbpamm/b3lyp.pammClick here to see an extract from this file.HYDROGENSThe list of hydrogen atoms that can form part of a hydrogen bond=2-192:3,3-192:3 ... DUMPATOMSDump selected atoms on a file. More details ARGthe labels of vectors that should be output in the xyz file=acceptors ATOMSthe atom indices whose positions you would like to print out=1-9:3 FILEfile on which to output coordinates; extension is automatically detected=acceptors.xyz
This input will still output an xyz file with five columns. The fifth column in this file will give the number of hydrogen bonds that each of the three atoms that were specified using the ACCEPTORS keyword accept from the atoms that were specified by the DONORS keyword. Notice also that the as the REGULARISE and GAUSS_CUTOFF keywords were not used in this input these quantities are set to the default values that are given in the table below.
The NOPBC flag
When you use the HBPAMM_MATRIX you need to calculate the distances between various pairs of atoms. In all the inputs that have been provided above we calculate these distances between pairs of atoms in a way that takes the periodic boundary conditions into account. If you want to ignore the periodic boundary conditions you can use the NOPBC flag as shown below.
#SETTINGS INPUTFILES=regtest/pamm/rt-hbpamm/b3lyp.pamm acceptors: HBPAMM_SACalculate the number of hydrogen bonds each acceptor participates in using the HBPamm method This action is a shortcut. More details ... SITESThe list of atoms which can be part of a hydrogen bond=1-192:3 HYDROGENSThe list of hydrogen atoms that can form part of a hydrogen bond=2-192:3,3-192:3 CLUSTERSthe name of the file that contains the definitions of all the kernels for PAMM=regtest/pamm/rt-hbpamm/b3lyp.pammClick here to see an extract from this file.NOPBC don't use pbc ... DUMPATOMSDump selected atoms on a file. More details ARGthe labels of vectors that should be output in the xyz file=acceptors ATOMSthe atom indices whose positions you would like to print out=1-192:3 FILEfile on which to output coordinates; extension is automatically detected=acceptors.xyz
The MASK keyword
You can use the MASK keyword with this action in the same way that it is used with COORDINATIONNUMBER. This keyword thus expects a vector in input, which tells PLUMED the atoms for which you do not need to calculate the number of hydrogen bonds. As illustrated below, this is useful if you are using functionality from the volumes module to calculate the average number of hydrogen bonds those atoms that lie in a certain part of the simulation box accept from their neighbors.
#SETTINGS INPUTFILES=regtest/pamm/rt-hbpamm/b3lyp.pamm # Fixed virtual atom which serves as the probe volume's center (pos. in nm) center: FIXEDATOMAdd a virtual atom in a fixed position. This action has hidden defaults. More details ATcoordinates of the virtual atom=2.5,2.5,2.5 # Vector in which element i is one if atom i is in sphere of interest and zero otherwise sphere: INSPHEREThis quantity can be used to calculate functions of the distribution of collective variables for the atoms that lie in a particular, user-specified part of of the cell. More details ATOMSthe group of atoms that you would like to investigate=1-192:3 CENTERthe atom whose vicinity we are interested in examining=center RADIUSthe switching function that tells us the extent of the sphereical region of interest. Options for this keyword are explained in the documentation for LESS_THAN.={GAUSSIAN D_0=0.5 R_0=0.01 D_MAX=0.52} # Calculate the number of hydrogen bonds that have been accepted acceptors: HBPAMM_SACalculate the number of hydrogen bonds each acceptor participates in using the HBPamm method This action is a shortcut. More details ... SITESThe list of atoms which can be part of a hydrogen bond=1-192:3 HYDROGENSThe list of hydrogen atoms that can form part of a hydrogen bond=2-192:3,3-192:3 CLUSTERSthe name of the file that contains the definitions of all the kernels for PAMM=regtest/pamm/rt-hbpamm/b3lyp.pammClick here to see an extract from this file.MASKa vector that is used to used to determine which rows of the adjancency matrix to compute=sphere ... # Multiply number of hydrogen bonds by sphere vector prod: CUSTOMCalculate a combination of variables using a custom expression. More details ARGthe values input to this function=acceptors,sphere FUNCthe function you wish to evaluate=x*y PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO # Total number of hydrogen bonds accepted for atoms that are in the sphere of interest numer: SUMCalculate the sum of the arguments More details ARGthe vector/matrix/grid whose elements shuld be added together=prod PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO # Number of atoms that are in sphere of interest denom: SUMCalculate the sum of the arguments More details ARGthe vector/matrix/grid whose elements shuld be added together=sphere PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO # Average number of accepted hydrogen bonds for atoms in sphere of interest av: CUSTOMCalculate a combination of variables using a custom expression. More details ARGthe values input to this function=numer,denom FUNCthe function you wish to evaluate=x/y PERIODICif the output of your function is periodic then you should specify the periodicity of the function=NO # And print out final CV to a file PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=av FILEthe name of the file on which to output these quantities=colvar STRIDE the frequency with which the quantities of interest should be output=1
This input calculate the number of hydrogen bonds that are accepted by those atoms that are within a spherical region that is centered on the point .
Optimisation details
If you expand the inputs above you will see that they all the HBPAMM_MATRIX action. The matrix that this action computes is sparse as each atom only forms hydroen bonds with a relatively small number of neighbors. The vast majority of the elements in the HBPAMM_MATRIX are thsu zero. To reduce the amount of memory that PLUMED requires PLUMED uses sparse matrix storage. Consequently, whenever you calculate and store a contact matrix only the elements of the matrix that are non-zero are stored.
We also use the sparsity of the HBPAMM_MATRIX to make the time required to compute the matrix scale linearly rather than quadratically with the number of atoms. We know that element is only non-zero if the donor and acceptor atoms are within:
where runs over all the PAMM kernels. is the gaussian cutoff that is specified using the REGULARIZE
keyword, is the mean acceptor-donor distance for the th kernel, is the largest
eigenvalue of the covariance for the th kernel and is the acceptor-donor distance component
of its corresponding eigenvector. We can determine that many pairs of atoms are further appart than without computing the
distance between these atoms by using divide and conquer strategies such as linked lists and neighbour lists. Furthermore, we do not even
need to set a D_MAX parameter as we would have to if we were using CONTACT_MATRIX as the above cutoff can be determined
from the parameters of the Gaussian kernels directly.
Input
The arguments and atoms that serve as the input for this action are specified using one or more of the keywords in the following table.
| Keyword | Type | Description |
|---|---|---|
| MASK | vector | a vector that is used to used to determine which rows of the adjancency matrix to compute |
| SITES | atoms | The list of atoms which can be part of a hydrogen bond |
| DONORS | atoms | The list of atoms which can donate a hydrogen bond |
| ACCEPTORS | atoms | The list of atoms which can accept a hydrogen bond |
| HYDROGENS | atoms | The list of hydrogen atoms that can form part of a hydrogen bond |
Output components
This action can calculate the values in the following table when the associated keyword is included in the input for the action. These values can be referenced elsewhere in the input by using this Action's label followed by a dot and the name of the value required from the list below.
| Name | Type | Keyword | Description |
|---|---|---|---|
| lessthan | scalar | LESS_THAN | the number of colvars that have a value less than a threshold |
| morethan | scalar | MORE_THAN | the number of colvars that have a value more than a threshold |
| altmin | scalar | ALT_MIN | the minimum value of the cv |
| min | scalar | MIN | the minimum colvar |
| max | scalar | MAX | the maximum colvar |
| between | scalar | BETWEEN | the number of colvars that have a value that lies in a particular interval |
| highest | scalar | HIGHEST | the largest of the colvars |
| lowest | scalar | LOWEST | the smallest of the colvars |
| sum | scalar | SUM | the sum of the colvars |
| mean | scalar | MEAN | the mean of the colvars |
Full list of keywords
The following table describes the keywords and options that can be used with this action
| Keyword | Type | Default | Description |
|---|---|---|---|
| MASK | input | none | a vector that is used to used to determine which rows of the adjancency matrix to compute |
| SITES | input | none | The list of atoms which can be part of a hydrogen bond |
| DONORS | input | none | The list of atoms which can donate a hydrogen bond |
| ACCEPTORS | input | none | The list of atoms which can accept a hydrogen bond |
| HYDROGENS | input | none | The list of hydrogen atoms that can form part of a hydrogen bond |
| CLUSTERS | compulsory | none | the name of the file that contains the definitions of all the kernels for PAMM |
| REGULARISE | compulsory | 0.001 | don't allow the denominator to be smaller then this value |
| GAUSS_CUTOFF | compulsory | 6.25 | the cutoff at which to stop evaluating the kernel function is set equal to sqrt(2x)(max(adc)+cov(adc)) |
| NOPBC | optional | false | don't use pbc |
| SERIAL | optional | false | do the calculation in serial. Further information about this flag can be found here. |
| USEGPU | optional | false | run this calculation on the GPU. Further information about this flag can be found here. |
deprecated keywords
The keywords in the following table can still be used with this action but have been deprecated
| Keyword | Description |
|---|---|
| ATOMS | You should use GROUP instead of this keyword which was used in older versions of PLUMED and is provided for back compatibility only |
| LESS_THAN | calculate the number of variables that are less than a certain target value |
| MORE_THAN | calculate the number of variables that are more than a certain target value |
| ALT_MIN | calculate the minimum value |
| MIN | calculate the minimum value |
| MAX | calculate the maximum value |
| BETWEEN | calculate the number of values that are within a certain range |
| HIGHEST | this flag allows you to recover the highest of these variables |
| HISTOGRAM | calculate a discretized histogram of the distribution of values |
| LOWEST | this flag allows you to recover the lowest of these variables |
| SUM | calculate the sum of all the quantities |
| MEAN | calculate the mean of all the quantities |
References
More information about how this action can be used is available in the following articles:
- P. Gasparotto, M. Ceriotti, Recognizing molecular patterns by machine learning: An agnostic structural definition of the hydrogen bond. The Journal of Chemical Physics. 141 (2014)
- P. Gasparotto, R. H. Meißner, M. Ceriotti, Recognizing Local and Global Structural Motifs at the Atomic Scale. Journal of Chemical Theory and Computation. 14, 486–498 (2018)
- G. A. Tribello, F. Giberti, G. C. Sosso, M. Salvalaglio, M. Parrinello, Analyzing and Driving Cluster Formation in Atomistic Simulations. Journal of Chemical Theory and Computation. 13, 1317–1327 (2017)