Line data Source code
1 : /* +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
2 : Copyright (c) 2013-2019 The plumed team
3 : (see the PEOPLE file at the root of the distribution for a list of names)
4 :
5 : See http://www.plumed.org for more information.
6 :
7 : This file is part of plumed, version 2.
8 :
9 : plumed is free software: you can redistribute it and/or modify
10 : it under the terms of the GNU Lesser General Public License as published by
11 : the Free Software Foundation, either version 3 of the License, or
12 : (at your option) any later version.
13 :
14 : plumed is distributed in the hope that it will be useful,
15 : but WITHOUT ANY WARRANTY; without even the implied warranty of
16 : MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 : GNU Lesser General Public License for more details.
18 :
19 : You should have received a copy of the GNU Lesser General Public License
20 : along with plumed. If not, see <http://www.gnu.org/licenses/>.
21 : +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ */
22 : #include "PathBase.h"
23 : #include "core/ActionRegister.h"
24 :
25 : //+PLUMEDOC COLVAR PATH
26 : /*
27 : Path collective variables with a more flexible framework for the distance metric being used.
28 :
29 : The Path Collective Variables developed by Branduardi and co-workers \cite brand07 allow one
30 : to compute the progress along a high-dimensional path and the distance from the high-dimensional
31 : path. The progress along the path (s) is computed using:
32 :
33 : \f[
34 : s = \frac{ \sum_{i=1}^N i \exp( -\lambda R[X - X_i] ) }{ \sum_{i=1}^N \exp( -\lambda R[X - X_i] ) }
35 : \f]
36 :
37 : while the distance from the path (z) is measured using:
38 :
39 : \f[
40 : z = -\frac{1}{\lambda} \ln\left[ \sum_{i=1}^N \exp( -\lambda R[X - X_i] ) \right]
41 : \f]
42 :
43 : In these expressions \f$N\f$ high-dimensional frames (\f$X_i\f$) are used to describe the path in the high-dimensional
44 : space. The two expressions above are then functions of the distances from each of the high-dimensional frames \f$R[X - X_i]\f$.
45 : Within PLUMED there are multiple ways to define the distance from a high-dimensional configuration. You could calculate
46 : the RMSD distance or you could calculate the ammount by which a set of collective variables change. As such this implementation
47 : of the path cv allows one to use all the difference distance metrics that are discussed in \ref dists. This is as opposed to
48 : the alternative implementation of path (\ref PATHMSD) which is a bit faster but which only allows one to use the RMSD distance.
49 :
50 : The \f$s\f$ and \f$z\f$ variables are calculated using the above formulas by default. However, there is an alternative method
51 : of calculating these collective variables, which is detailed in \cite bernd-path. This alternative method uses the tools of
52 : geometry (as opposed to algebra, which is used in the equations above). In this alternative formula the progress along the path
53 : \f$s\f$ is calculated using:
54 :
55 : \f[
56 : s = i_2 + \textrm{sign}(i_2-i_1) \frac{ \sqrt{( \mathbf{v}_1\cdot\mathbf{v}_2 )^2 - |\mathbf{v}_3|^2(|\mathbf{v}_1|^2 - |\mathbf{v}_2|^2) } }{2|\mathbf{v}_3|^2} - \frac{\mathbf{v}_1\cdot\mathbf{v}_3 - |\mathbf{v}_3|^2}{2|\mathbf{v}_3|^2}
57 : \f]
58 :
59 : where \f$\mathbf{v}_1\f$ and \f$\mathbf{v}_3\f$ are the vectors connecting the current position to the closest and second closest node of the path,
60 : respectfully and \f$i_1\f$ and \f$i_2\f$ are the projections of the closest and second closest frames of the path. \f$\mathbf{v}_2\f$, meanwhile, is the
61 : vector connecting the closest frame to the second closest frame. The distance from the path, \f$z\f$ is calculated using:
62 :
63 : \f[
64 : z = \sqrt{ \left[ |\mathbf{v}_1|^2 - |\mathbf{v}_2| \left( \frac{ \sqrt{( \mathbf{v}_1\cdot\mathbf{v}_2 )^2 - |\mathbf{v}_3|^2(|\mathbf{v}_1|^2 - |\mathbf{v}_2|^2) } }{2|\mathbf{v}_3|^2} - \frac{\mathbf{v}_1\cdot\mathbf{v}_3 - |\mathbf{v}_3|^2}{2|\mathbf{v}_3|^2} \right) \right]^2 }
65 : \f]
66 :
67 : The symbols here are as they were for \f$s\f$. If you would like to use these equations to calculate \f$s\f$ and \f$z\f$ then you should use the GPATH flag.
68 : The values of \f$s\f$ and \f$z\f$ can then be referenced using the gspath and gzpath labels.
69 :
70 : \par Examples
71 :
72 : In the example below the path is defined using RMSD distance from frames.
73 : The reference frames in the path are defined in the pdb file. In this frame
74 : each configuration in the path is separated by a line containing just the word END.
75 :
76 : \plumedfile
77 : p1: PATH REFERENCE=file.pdb TYPE=OPTIMAL LAMBDA=500.0
78 : PRINT ARG=p1.sss,p1.zzz STRIDE=1 FILE=colvar FMT=%8.4f
79 : \endplumedfile
80 :
81 : In the example below the path is defined using the values of two torsional angles (t1 and t2).
82 : In addition, the \f$s\f$ and \f$z\f$ are calculated using the geometric expressions described
83 : above rather than the alegebraic expressions that are used by default.
84 :
85 : \plumedfile
86 : t1: TORSION ATOMS=5,7,9,15
87 : t2: TORSION ATOMS=7,9,15,17
88 : pp: PATH TYPE=EUCLIDEAN REFERENCE=epath.pdb GPATH NOSPATH NOZPATH
89 : PRINT ARG=pp.* FILE=colvar
90 : \endplumedfile
91 :
92 : Notice that the LAMBDA parameter is not required here as we are not calculating \f$s\f$ and \f$s\f$
93 : using the algebraic formulae defined earlier. The positions of the frames in the path are defined
94 : in the file epath.pdb. An extract from this file looks as shown below.
95 :
96 : \verbatim
97 : REMARK ARG=t1,t2 t1=-4.25053 t2=3.88053
98 : END
99 : REMARK ARG=t1,t2 t1=-4.11 t2=3.75
100 : END
101 : REMARK ARG=t1,t2 t1=-3.96947 t2=3.61947
102 : END
103 : \endverbatim
104 :
105 : The remarks in this pdb file tell PLUMED the labels that are being used to define the position in the
106 : high dimensional space and the values that these arguments have at each point on the path.
107 :
108 : The following input instructs PLUMED to calculate the values of the path collective variables. The frames that make up this
109 : path are defined in the file all.pdb and all distances are measured using the OPTIMAL metric that is discussed in the manual
110 : page on \ref RMSD.
111 :
112 : \plumedfile
113 : p2: PATH REFERENCE=all.pdb LAMBDA=69087
114 : PRINT ARG=p2.spath,p2.zpath STRIDE=1 FILE=colvar
115 : \endplumedfile
116 :
117 : If you wish to use collective variable values in the definition of your path you would use an input file with something like this:
118 :
119 : \plumedfile
120 : d1: DISTANCE ATOMS=1,2
121 : d2: DISTANCE ATOMS=3,4a
122 : p2: PATH REFERENCE=mypath.pdb LAMBDA=2 TYPE=EUCLIDEAN
123 : PRINT ARG=p2.spath,p2.zpath STRIDE=1 FILE=colvar
124 : \endplumedfile
125 :
126 : The corresponding pdb file containing the definitions of the frames in the path would then look like this:
127 :
128 : \verbatim
129 : DESCRIPTION: a defintiion of a PATH
130 : REMARK TYPE=EUCLIDEAN
131 : REMARK ARG=d1,d2
132 : REMARK d1=1.0 d2=1.0
133 : END
134 : REMARK TYPE=EUCLIDEAN
135 : REMARK ARG=d1,d2
136 : REMARK d1=2.0 d2=2.0
137 : END
138 : \endverbatim
139 :
140 : For each frame in the path you must specify the arguments that should be used to calculate the distance between the instantaneous configuration
141 : of the system and the reference configurations together with the values that these arguments take in each of the reference configurations.
142 :
143 : */
144 : //+ENDPLUMEDOC
145 :
146 : namespace PLMD {
147 : namespace mapping {
148 :
149 12 : class Path : public PathBase {
150 : public:
151 : static void registerKeywords( Keywords& keys );
152 : explicit Path(const ActionOptions&);
153 : };
154 :
155 6458 : PLUMED_REGISTER_ACTION(Path,"PATH")
156 :
157 7 : void Path::registerKeywords( Keywords& keys ) {
158 14 : PathBase::registerKeywords( keys ); keys.remove("PROPERTY");
159 21 : keys.addFlag("NOSPATH",false,"do not calculate the spath position");
160 21 : keys.remove("LOWMEM"); keys.use("GPATH");
161 7 : }
162 :
163 6 : Path::Path(const ActionOptions& ao):
164 : Action(ao),
165 6 : PathBase(ao)
166 : {
167 : setLowMemOption( true );
168 12 : bool nos; parseFlag("NOSPATH",nos);
169 :
170 : std::string empty;
171 6 : if(!nos) {
172 12 : if( getPropertyIndex("spath")!=0 || getNumberOfProperties()>1 ) {
173 0 : error("paths only work when there is a single property called sss being calculated");
174 : }
175 4 : if( getLambda()==0 ) error("you must set LAMBDA parameter in order to calculate spath position. Use LAMBDA/NOSPATH keyword");
176 : empty="LABEL=spath";
177 8 : addVessel("SPATH",empty,0);
178 : }
179 6 : readVesselKeywords();
180 6 : checkRead();
181 6 : }
182 :
183 : }
184 4839 : }
|
