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             : The INCLUDE command is Useful when you want to split very large plumed.dat files.
      36             : 
      37             : In PLUMED 2.4 this action was now allowed to appear before the initial setup part of the file
      38             : (e.g. in the part that conained any [UNITS](UNITS.md) and [MOLINFO](MOLINFO.md) commands).
      39             : However, from PLUMED 2.5 onwards, INCLUDE commands can be used in any position of the file.
      40             : 
      41             : ## Basic example
      42             : 
      43             : This input:
      44             : 
      45             : ```plumed
      46             : c1: COM ATOMS=1-100
      47             : c2: COM ATOMS=101-202
      48             : d: DISTANCE ATOMS=c1,c2
      49             : PRINT ARG=d
      50             : ```
      51             : 
      52             : can be replaced with this input:
      53             : 
      54             : ```plumed
      55             : INCLUDE FILE=extras/pippo.dat
      56             : d: DISTANCE ATOMS=c1,c2
      57             : PRINT ARG=d
      58             : ```
      59             : 
      60             : Notice that you can see the contents of pippo.dat by clicking on the name of the file
      61             : 
      62             : ## Using INCLUDE to define groups
      63             : 
      64             : Using INCLUDE for the input in the previous section is rather pointless as the included file is rather short.
      65             : In a case like the one shown below the INCLUDE command is much more useful:
      66             : 
      67             : ```plumed
      68             : INCLUDE FILE=extras/groups.dat
      69             : c: COORDINATION GROUPA=groupa GROUPB=groupb R_0=0.5
      70             : METAD ARG=c HEIGHT=0.2 PACE=100 SIGMA=0.2 BIASFACTOR=5
      71             : ```
      72             : 
      73             : Although the `groups.dat` file here is short again it could be much larger if the groups
      74             : contained very lage numbers of atoms.
      75             : 
      76             : ## INCLUDE and multiple replicas
      77             : 
      78             : Another case where INCLUDE can be useful is when running multi-replica simulations.
      79             : Here different replicas might have different input files, but perhaps a large part of the
      80             : input is shared. This part can be put in a common included file. For instance you could use
      81             : a `common.dat` to share part of the input across the input for the two replica simulation
      82             : which has the following `plumed.0.dat` input file:
      83             : 
      84             : ```plumed
      85             : # this is plumed.0.dat
      86             : INCLUDE FILE=extras/common.dat
      87             : RESTRAINT ARG=t AT=1.0 KAPPA=10
      88             : ```
      89             : 
      90             : and the following `plumed.1.dat` input file
      91             : 
      92             : ```plumed
      93             : # this is plumed.1.dat
      94             : INCLUDE FILE=extras/common.dat
      95             : RESTRAINT ARG=t AT=1.2 KAPPA=10
      96             : ```
      97             : 
      98             : When you run calculations in this way it is important to reember that PLUMED will always try to open
      99             : files for reading with a replica suffix first.  This is also even for files opened by INCLUDE!
     100             : We can thus implement the calculation above using the following common input for the two replicas:
     101             : 
     102             : ```plumed
     103             : #SETTINGS NREPLICAS=2
     104             : t: TORSION ATOMS=1,2,3,4
     105             : INCLUDE FILE=extras/other.inc
     106             : ```
     107             : 
     108             : We would then have an other.0.inc file that contains the defintion of the RESTRAINT command with AT=1.0
     109             : and an other.1.inc file that contains the defintion of the RESTRAINT command with AT=1.2.
     110             : 
     111             : In practice, however, we recommend using the special replica syntax that is discussed on [this page](parsing.md)
     112             : in place of the INCLUDE file approach that has been described above.  If you are using this syntax the input
     113             : for the calculation above is as follows:
     114             : 
     115             : ```plumed
     116             : #SETTINGS NREPLICAS=2
     117             : t: TORSION ATOMS=1,2,3,4
     118             : RESTRAINT ARG=t AT=@replicas:1.0,1.2 KAPPA=10
     119             : ```
     120             : 
     121             : The version of this input that uses INCLUDE files is an older syntax that was used in older versions of PLUMED
     122             : before the special replica syntax was made available.
     123             : 
     124             : */
     125             : //+ENDPLUMEDOC
     126             : 
     127             : class Include :
     128             :   public ActionAnyorder {
     129             : public:
     130             :   static void registerKeywords( Keywords& keys );
     131             :   explicit Include(const ActionOptions&ao);
     132           0 :   void calculate() override {}
     133           0 :   void apply() override {}
     134             : };
     135             : 
     136             : PLUMED_REGISTER_ACTION(Include,"INCLUDE")
     137             : 
     138          25 : void Include::registerKeywords( Keywords& keys ) {
     139          25 :   Action::registerKeywords(keys);
     140          25 :   keys.add("compulsory","FILE","file to be included");
     141          25 : }
     142             : 
     143          23 : Include::Include(const ActionOptions&ao):
     144             :   Action(ao),
     145          23 :   ActionAnyorder(ao) {
     146             :   std::string f;
     147          23 :   parse("FILE",f);
     148          23 :   checkRead();
     149          23 :   plumed.readInputFile(f);
     150          23 : }
     151             : 
     152             : }
     153             : }
     154             :