From ea63721b223a8036ad6d41e3165620fdca26dd9a Mon Sep 17 00:00:00 2001
From: Giovanni Bussi <giovanni.bussi@gmail.com>
Date: Fri, 28 Apr 2017 16:43:59 +0200
Subject: [PATCH] Improved INCLUDE documentation
I added several examples with plumedfile, so I only
push this on master branch.
---
src/generic/Include.cpp | 87 ++++++++++++++++++++++++++++++++++++++---
1 file changed, 82 insertions(+), 5 deletions(-)
diff --git a/src/generic/Include.cpp b/src/generic/Include.cpp
index 30539f0bb..70f41716c 100644
--- a/src/generic/Include.cpp
+++ b/src/generic/Include.cpp
@@ -37,28 +37,105 @@ Useful to split very large plumed.dat files.
\par Examples
-This input
+This input:
\plumedfile
c1: COM ATOMS=1-100
c2: COM ATOMS=101-202
d: DISTANCE ARG=c1,c2
PRINT ARG=d
\endplumedfile
-
-can be replaced with
+can be replaced with this input:
\plumedfile
INCLUDE FILE=pippo.dat
d: DISTANCE ARG=c1,c2
PRINT ARG=d
\endplumedfile
-
where the content of file pippo.dat is
\plumedfile
c1: COM ATOMS=1-100
c2: COM ATOMS=101-202
\endplumedfile
-(see also \ref COM, \ref DISTANCE, and \ref PRINT).
+The files in this example are rather short, but imagine a case like this one:
+\plumedfile
+INCLUDE FILE=groups.dat
+c: COORDINATION GROUPA=groupa GROUPB=groupb R_0=0.5
+METAD ARG=c HEIGHT=0.2 PACE=100 SIGMA=0.2 BIASFACTOR=5
+\endplumedfile
+Here `groups.dat` could be huge file containing group definitions such as
+\plumedfile
+groupa: GROUP ...
+ ATOMS={
+ 10
+ 50
+ 60
+## imagine a long list here
+ 70
+ 80
+ 120
+ }
+...
+groupb: GROUP ...
+ ATOMS={
+ 11
+ 51
+ 61
+## imagine a long list here
+ 71
+ 81
+ 121
+ }
+...
+\endplumedfile
+So, included files are the best place where one can store long definitions.
+
+Another case where INCLUDE is very useful is when running multi-replica simulations.
+Here different replicas might have different input files, but perhaps a large part of the
+input is shared. This part can be put in a common included file. For instance you could have
+`common.dat`:
+\plumedfile
+# this is common.dat
+t: TORSION ATOMS=1,2,3,4
+\endplumedfile
+Then `plumed.0.dat`:
+\plumedfile
+# this is plumed.0.dat
+INCLUDE FILE=common.dat
+RESTRAINT ARG=t AT=1.0 KAPPA=10
+\endplumedfile
+And `plumed.1.dat`:
+\plumedfile
+# this is plumed.1.dat
+INCLUDE FILE=common.dat
+RESTRAINT ARG=t AT=1.2 KAPPA=10
+\endplumedfile
+
+\warning
+Remember that when using multi replica simulations whenever plumed tried to open
+a file for reading it looks for a file with the replica suffix first.
+This is true also for files opened by INCLUDE!
+
+As an example, the same result of the inputs above could have been obtained using
+`plumed.dat`:
+\plumedfile
+# this is plumed.dat
+t: TORSION ATOMS=1,2,3,4
+INCLUDE FILE=other.dat
+\endplumedfile
+Then `other.0.dat`:
+\plumedfile
+# this is other.0.dat
+RESTRAINT ARG=t AT=1.0 KAPPA=10
+\endplumedfile
+And `other.1.dat`:
+\plumedfile
+# this is other.1.dat
+RESTRAINT ARG=t AT=1.2 KAPPA=10
+\endplumedfile
+
+
+
+
*/
//+ENDPLUMEDOC
--
GitLab