Line data    Source code

       1             : /* +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
       2             :    Copyright (c) 2012-2023 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 "core/Action.h"
      23             : #include "core/ActionAnyorder.h"
      24             : #include "core/ActionRegister.h"
      25             : #include "core/PlumedMain.h"
      26             : #include "tools/Exception.h"
      27             : 
      28             : namespace PLMD {
      29             : namespace generic {
      30             : 
      31             : //+PLUMEDOC GENERIC INCLUDE
      32             : /*
      33             : Includes an external input file, similar to #include in C preprocessor.
      34             : 
      35             : Useful to split very large plumed.dat files. Notice that in PLUMED 2.4 this action
      36             : cannot be used before the initial setup part of the file (e.g. in the part with \ref UNITS, \ref MOLINFO, etc).
      37             : As of PLUMED 2.5, \ref INCLUDE can be used in any position of the file.
      38             : 
      39             : \par Examples
      40             : 
      41             : This input:
      42             : \plumedfile
      43             : c1: COM ATOMS=1-100
      44             : c2: COM ATOMS=101-202
      45             : d: DISTANCE ATOMS=c1,c2
      46             : PRINT ARG=d
      47             : \endplumedfile
      48             : can be replaced with this input:
      49             : \plumedfile
      50             : INCLUDE FILE=pippo.dat
      51             : d: DISTANCE ATOMS=c1,c2
      52             : PRINT ARG=d
      53             : \endplumedfile
      54             : where the content of file pippo.dat is
      55             : \plumedfile
      56             : #SETTINGS FILENAME=pippo.dat
      57             : # this is pippo.dat
      58             : c1: COM ATOMS=1-100
      59             : c2: COM ATOMS=101-202
      60             : \endplumedfile
      61             : 
      62             : The files in this example are rather short, but imagine a case like this one:
      63             : \plumedfile
      64             : INCLUDE FILE=groups.dat
      65             : c: COORDINATION GROUPA=groupa GROUPB=groupb R_0=0.5
      66             : METAD ARG=c HEIGHT=0.2 PACE=100 SIGMA=0.2 BIASFACTOR=5
      67             : \endplumedfile
      68             : Here `groups.dat` could be a huge file containing group definitions.  This groups.dat file might look something
      69             : like the following example but with more atom indices in the groups.
      70             : \plumedfile
      71             : #SETTINGS FILENAME=groups.dat
      72             : # this is groups.dat
      73             : groupa: GROUP ...
      74             :   ATOMS={
      75             :     10
      76             :     50
      77             :     60
      78             :     70
      79             :     80
      80             :     120
      81             :   }
      82             : ...
      83             : groupb: GROUP ...
      84             :   ATOMS={
      85             :     11
      86             :     51
      87             :     61
      88             :     71
      89             :     81
      90             :     121
      91             :   }
      92             : ...
      93             : \endplumedfile
      94             : So, included files are the best place where one can store long definitions.
      95             : 
      96             : Another case where INCLUDE is very useful is when running multi-replica simulations.
      97             : Here different replicas might have different input files, but perhaps a large part of the
      98             : input is shared. This part can be put in a common included file. For instance you could have
      99             : `common.dat`:
     100             : \plumedfile
     101             : #SETTINGS FILENAME=common.dat
     102             : # this is common.dat
     103             : t: TORSION ATOMS=1,2,3,4
     104             : \endplumedfile
     105             : Then `plumed.0.dat`:
     106             : \plumedfile
     107             : # this is plumed.0.dat
     108             : INCLUDE FILE=common.dat
     109             : RESTRAINT ARG=t AT=1.0 KAPPA=10
     110             : \endplumedfile
     111             : And `plumed.1.dat`:
     112             : \plumedfile
     113             : # this is plumed.1.dat
     114             : INCLUDE FILE=common.dat
     115             : RESTRAINT ARG=t AT=1.2 KAPPA=10
     116             : \endplumedfile
     117             : 
     118             : \warning
     119             : Remember that when using multi replica simulations whenever plumed tried to open
     120             : a file for reading it looks for a file with the replica suffix first.
     121             : This is true also for files opened by INCLUDE!
     122             : 
     123             : As an example, the same result of the inputs above could have been obtained using
     124             : the following `plumed.dat` file:
     125             : \plumedfile
     126             : #SETTINGS NREPLICAS=2
     127             : t: TORSION ATOMS=1,2,3,4
     128             : INCLUDE FILE=other.inc
     129             : \endplumedfile
     130             : Then `other.0.inc`:
     131             : \plumedfile
     132             : #SETTINGS FILENAME=other.0.inc
     133             : # this is other.0.inc
     134             : RESTRAINT ARG=t AT=1.0 KAPPA=10
     135             : \endplumedfile
     136             : And `other.1.inc`:
     137             : \plumedfile
     138             : #SETTINGS FILENAME=other.1.inc
     139             : # this is other.1.inc
     140             : RESTRAINT ARG=t AT=1.2 KAPPA=10
     141             : \endplumedfile
     142             : 
     143             : 
     144             : 
     145             : 
     146             : 
     147             : */
     148             : //+ENDPLUMEDOC
     149             : 
     150             : class Include :
     151             :   public ActionAnyorder
     152             : {
     153             : public:
     154             :   static void registerKeywords( Keywords& keys );
     155             :   explicit Include(const ActionOptions&ao);
     156           0 :   void calculate() override {}
     157           0 :   void apply() override {}
     158             : };
     159             : 
     160             : PLUMED_REGISTER_ACTION(Include,"INCLUDE")
     161             : 
     162          25 : void Include::registerKeywords( Keywords& keys ) {
     163          25 :   Action::registerKeywords(keys);
     164          50 :   keys.add("compulsory","FILE","file to be included");
     165          25 : }
     166             : 
     167          23 : Include::Include(const ActionOptions&ao):
     168             :   Action(ao),
     169          23 :   ActionAnyorder(ao)
     170             : {
     171             :   std::string f;
     172          23 :   parse("FILE",f);
     173          23 :   checkRead();
     174          23 :   plumed.readInputFile(f);
     175          23 : }
     176             : 
     177             : }
     178             : }
     179             :