Action: HBPAMM_MATRIX
| Module | pamm |
|---|---|
| Description | Usage |
| Adjacency matrix in which two electronegative atoms are adjacent if they are hydrogen bonded |   |
| output value | type |
| a matrix containing the weights for the bonds between each pair of atoms | matrix |
Details and examples
Adjacency matrix in which two electronegative atoms are adjacent if they are hydrogen bonded
This method allows you to calculate an adjacency matrix and use all the methods discussed in the documentation for the CONTACT_MATRIX upon it to define CVs. The element of the matrix that is calculated by this action is one if there is a hydrogen bond connecting atom to atom . Furthermore, we determine whether there is a hydrogen atom between these two atoms by using the PAMM technique that is discussed in the articles from the bibliography below and in the documentation for the PAMM action.
The example shown below illustrates how the method is used in practice
#SETTINGS INPUTFILES=regtest/pamm/rt-hbpamm/b3lyp.pamm m: HBPAMM_MATRIXAdjacency matrix in which two electronegative atoms are adjacent if they are hydrogen bonded This action has hidden defaults. More details ... GROUPthe atoms for which you would like to calculate the adjacency matrix=1-192:3 GROUPCa group of atoms that must be summed over when calculating each element of the adjacency matrix=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.... PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=m FILEthe name of the file on which to output these quantities=colvar
The input above is outputting the full hbpamm matrix. However, this action is perhaps more usefully used to investigate the connectivity between a collection of water molecules in liquid water. Importantly, however, the output matrix here is not symmetric. We thus calculate the number of hydrogen bonds that these atoms are donating using the following input:
#SETTINGS INPUTFILES=regtest/pamm/rt-hbpamm/b3lyp.pamm m: HBPAMM_MATRIXAdjacency matrix in which two electronegative atoms are adjacent if they are hydrogen bonded This action has hidden defaults. More details ... GROUPthe atoms for which you would like to calculate the adjacency matrix=1-192:3 GROUPCa group of atoms that must be summed over when calculating each element of the adjacency matrix=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.... ones: ONESCreate a constant vector with all elements equal to one This action is a shortcut. More details SIZEthe number of ones that you would like to create=64 rsums: MATRIX_VECTOR_PRODUCTCalculate the product of the matrix and the vector More details ARGthe label for the matrix and the vector/scalar that are being multiplied=m,ones DUMPATOMSDump selected atoms on a file. More details ATOMSthe atom indices whose positions you would like to print out=1-192:3 ARGthe labels of vectors that should be output in the xyz file=rsums FILEfile on which to output coordinates; extension is automatically detected=donors.xyz
To calculate the number of hydrogen bonds these atoms accept we would use the following input:
#SETTINGS INPUTFILES=regtest/pamm/rt-hbpamm/b3lyp.pamm m: HBPAMM_MATRIXAdjacency matrix in which two electronegative atoms are adjacent if they are hydrogen bonded This action has hidden defaults. More details ... GROUPthe atoms for which you would like to calculate the adjacency matrix=1-192:3 GROUPCa group of atoms that must be summed over when calculating each element of the adjacency matrix=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.... mT: TRANSPOSECalculate the transpose of a matrix More details ARGthe label of the vector or matrix that should be transposed=m ones: ONESCreate a constant vector with all elements equal to one This action is a shortcut. More details SIZEthe number of ones that you would like to create=64 rsums: MATRIX_VECTOR_PRODUCTCalculate the product of the matrix and the vector More details ARGthe label for the matrix and the vector/scalar that are being multiplied=mT,ones DUMPATOMSDump selected atoms on a file. More details ATOMSthe atom indices whose positions you would like to print out=1-192:3 ARGthe labels of vectors that should be output in the xyz file=rsums FILEfile on which to output coordinates; extension is automatically detected=acceptors.xyz
To calculate the total number of hydorgen bonds these atoms participate in you would use an input like this:
#SETTINGS INPUTFILES=regtest/pamm/rt-hbpamm/b3lyp.pamm m: HBPAMM_MATRIXAdjacency matrix in which two electronegative atoms are adjacent if they are hydrogen bonded This action has hidden defaults. More details ... GROUPthe atoms for which you would like to calculate the adjacency matrix=1-192:3 GROUPCa group of atoms that must be summed over when calculating each element of the adjacency matrix=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.... mT: TRANSPOSECalculate the transpose of a matrix More details ARGthe label of the vector or matrix that should be transposed=m hbmat: CUSTOMCalculate a combination of variables using a custom expression. More details ARGthe values input to this function=m,mT 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 ones: ONESCreate a constant vector with all elements equal to one This action is a shortcut. More details SIZEthe number of ones that you would like to create=64 rsums: MATRIX_VECTOR_PRODUCTCalculate the product of the matrix and the vector More details ARGthe label for the matrix and the vector/scalar that are being multiplied=hbmat,ones DUMPATOMSDump selected atoms on a file. More details ATOMSthe atom indices whose positions you would like to print out=1-192:3 ARGthe labels of vectors that should be output in the xyz file=rsums FILEfile on which to output coordinates; extension is automatically detected=hbonds.xyz
If you want to investigate whether there are hydrogen bonds between two groups of molecules you can use an input like this:
#SETTINGS INPUTFILES=regtest/pamm/rt-hbpamm/b3lyp.pamm m: HBPAMM_MATRIXAdjacency matrix in which two electronegative atoms are adjacent if they are hydrogen bonded This action has hidden defaults. More details ... GROUPAwhen you are calculating the adjacency matrix between two sets of atoms this keyword is used to specify the atoms along with the keyword GROUPB=1 GROUPBwhen you are calculating the adjacency matrix between two sets of atoms this keyword is used to specify the atoms along with the keyword GROUPA=2-192:3 GROUPCa group of atoms that must be summed over when calculating each element of the adjacency matrix=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.... PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=m FILEthe name of the file on which to output these quantities=colvar
This input outputs a matrix in which the th element tells you whether or not atom 1 donates a hydrogen bond to the th element in the group of 63 atoms that was specified using the ACCEPTORS keyword. The th element of the transpose of this matrix tells you if the th center donates a hydrogen bond to atom 1.
In general, it is better to use this action through the HBPAMM_SA, HBPAMM_SD and HBPAMM_SH keywords, which can be used to calculate the number of hydrogen bonds each donor, acceptor or hydrogen atom in your system participates in.
Periodic boundary conditions
Notice that in all the inputs above the distances values that enter the pamm expressions are calculated 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 m: HBPAMM_MATRIXAdjacency matrix in which two electronegative atoms are adjacent if they are hydrogen bonded This action has hidden defaults. More details ... GROUPthe atoms for which you would like to calculate the adjacency matrix=1-192:3 GROUPCa group of atoms that must be summed over when calculating each element of the adjacency matrix=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 ...
COMPONENTS flag
If you add the flag COMPONENTS to the input as shown below:
#SETTINGS INPUTFILES=regtest/pamm/rt-hbpamm/b3lyp.pamm c4: HBPAMM_MATRIXAdjacency matrix in which two electronegative atoms are adjacent if they are hydrogen bonded This action has hidden defaults. More details ... GROUPthe atoms for which you would like to calculate the adjacency matrix=1-192:3 GROUPCa group of atoms that must be summed over when calculating each element of the adjacency matrix=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.COMPONENTS also calculate the components of the vector connecting the atoms in the contact matrix ...
then four matrices with the labels c4.w, c4.x, c4.y and c4.z are output by the action. The matrix with the label c4.w is the adjacency matrix
that would be output if you had not added the COMPONENTS flag. The component of the matrices c4.x, c4.y and c4.z contain the , and
components of the vector connecting atoms and . Importantly, however, the components of these vectors are only stored in c4.x, c4.y and c4.z
if the elements of c4.w are non-zero. Using the COMPONENTS flag in this way ensures that you can use HBPAMM_MATRIX in tandem with many of the functionalities
that are part of the symfunc module. Remember, however, that the element of the HBPAMM_MATRIX is only non-zero if atom donates
a hydrogen bond to atom . You cannot use HBPAMM_MATRIX to identify the set of atoms that each atom is hydrogen bonded to.
The MASK keyword
You use the MASK keyword with HBPAMM_MATRIX in the same way that is used in CONTACT_MATRIX. This keyword thus expects a vector in input, which tells HBOND_MATRIX that it is safe to not calculate certain rows of the output matrix. An example where this keyword is used is shown below:
#SETTINGS INPUTFILES=regtest/pamm/rt-hbpamm/b3lyp.pamm # The atoms that are of interest ow: GROUPDefine a group of atoms so that a particular list of atoms can be referenced with a single label in definitions of CVs or virtual atoms. More details ATOMSthe numerical indexes for the set of atoms in the group=1-1650 # 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=ow 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} # Calculates cooordination numbers cmap: HBPAMM_MATRIXAdjacency matrix in which two electronegative atoms are adjacent if they are hydrogen bonded This action has hidden defaults. More details ... GROUPthe atoms for which you would like to calculate the adjacency matrix=ow GROUPCa group of atoms that must be summed over when calculating each element of the adjacency matrix=1650-3000 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 ... ones: ONESCreate a constant vector with all elements equal to one This action is a shortcut. More details SIZEthe number of ones that you would like to create=1650 cc: MATRIX_VECTOR_PRODUCTCalculate the product of the matrix and the vector More details ARGthe label for the matrix and the vector/scalar that are being multiplied=cmap,ones # Multiply coordination numbers by sphere vector prod: CUSTOMCalculate a combination of variables using a custom expression. More details ARGthe values input to this function=cc,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 # Sum of coordination numbers 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 coordination number for atoms in sphere of interest av: CUSTOMCalculate a combination of variables using a custom expression. More details ARGthe values input to this function=prod,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 calculates the average number of hydrogen bonds each of the atoms that are within a spherical region that is centered on the point donate.
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 |
| GROUP | atoms | the atoms for which you would like to calculate the adjacency matrix |
| GROUPA | atoms | when you are calculating the adjacency matrix between two sets of atoms this keyword is used to specify the atoms along with the keyword GROUPB |
| GROUPB | atoms | when you are calculating the adjacency matrix between two sets of atoms this keyword is used to specify the atoms along with the keyword GROUPA |
| GROUPC | atoms | a group of atoms that must be summed over when calculating each element of the adjacency matrix |
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 |
|---|---|---|---|
| w | matrix | COMPONENTS | a matrix containing the weights for the bonds between each pair of atoms |
| x | matrix | COMPONENTS | the projection of the bond on the x axis |
| y | matrix | COMPONENTS | the projection of the bond on the y axis |
| z | matrix | COMPONENTS | the projection of the bond on the z axis |
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 |
| GROUP | input | none | the atoms for which you would like to calculate the adjacency matrix |
| GROUPA | input | none | when you are calculating the adjacency matrix between two sets of atoms this keyword is used to specify the atoms along with the keyword GROUPB |
| GROUPB | input | none | when you are calculating the adjacency matrix between two sets of atoms this keyword is used to specify the atoms along with the keyword GROUPA |
| GROUPC | input | none | a group of atoms that must be summed over when calculating each element of the adjacency matrix |
| NL_CUTOFF | compulsory | 0.0 | The cutoff for the neighbor list |
| NL_STRIDE | compulsory | 1 | The frequency with which we are updating the atoms in the neighbor list |
| ORDER | compulsory | dah | the order in which the groups are specified in the input |
| 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)) |
| COMPONENTS | optional | false | also calculate the components of the vector connecting the atoms in the contact matrix |
| 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 |
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)