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/ActionSetup.h"
      23             : #include "core/ActionRegister.h"
      24             : #include "core/PlumedMain.h"
      25             : #include "tools/Exception.h"
      26             : 
      27             : namespace PLMD {
      28             : namespace setup {
      29             : 
      30             : //+PLUMEDOC GENERIC RESTART
      31             : /*
      32             : Activate restart.
      33             : 
      34             : Many MD calculations are run on supercomputer facilities that limit the amount of
      35             : time an individual calculation can run for.  As MD simulations take a long time to
      36             : complete, you often have to restart your calculations and build up your trajectories by
      37             : running a chain of sub-runs. Some MD codes tell PLUMED if the MD has restarted
      38             : the calculation from a checkpoint file while others do not. To avoid problems we recommend
      39             : using the RESTART commands and keywords in your input files whenever you are generating
      40             : trajetories by restarting calculations from a checkpoint file.
      41             : 
      42             : RESTART is a Setup directive and, as such, should appear
      43             : at the beginning of the input file. When you include the RESTART command
      44             : in your plumed.dat file you are telling PLUMED that you want to restart all
      45             : the actions. Restarting these actions ensures that, as discussed [here](Files.md), PLUMED appends
      46             : all the files that are open for writing. Appending to these files makes it
      47             : easier to analyze results from simulations that have been performed as a
      48             : chain of several sub-runs.
      49             : 
      50             : To consider what this means in practise consider the following input:
      51             : 
      52             : ```plumed
      53             : d: DISTANCE ATOMS=1,2
      54             : PRINT ARG=d FILE=out
      55             : ```
      56             : 
      57             : If you run a plumed calculation in a directory which already contains a file called
      58             : `out` that file called `out` will be renamed `bck.0.out` so that the data from the new
      59             : calculation can be output to a new version of the file `out` and so that the data in the
      60             : old version of the file is not lost.
      61             : 
      62             : If by contrast you run the calculation in that same directory with the following input:
      63             : 
      64             : ```plumed
      65             : RESTART
      66             : d: DISTANCE ATOMS=1,2
      67             : PRINT ARG=d FILE=out
      68             : ```
      69             : 
      70             : The data from the new simulation simulation will be appended to the file called `out` that
      71             : was already present in the data.
      72             : 
      73             : Notice that it is also possible to enable or disable restart on a per-action
      74             : basis using the RESTART keyword as illustrated below:
      75             : 
      76             : ```plumed
      77             : d1: DISTANCE ATOMS=1,2
      78             : d2: DISTANCE ATOMS=1,2
      79             : PRINT ARG=d1 FILE=out1
      80             : PRINT ARG=d2 FILE=out2 RESTART=YES
      81             : ```
      82             : 
      83             : If this input is used any files called `out1` are backed up to `bck.0.out1`.  Data from the
      84             : new calculation is then appended to any file called `out2`  that is present in the working directory.
      85             : 
      86             : Notice that the RESTART keyword is assigned one of three values:
      87             : 
      88             : - `RESTART=AUTO` is the default and means that global settings are used
      89             : - `RESTART=YES` means that the action is restarted
      90             : - `RESTART=NO` means that the action is not restarted even if there is a global restart command
      91             : 
      92             : The following input is thus equivalent to the first input that introduced the RESTART keyword.
      93             : 
      94             : ```plumed
      95             : RESTART
      96             : d1: DISTANCE ATOMS=1,2
      97             : d2: DISTANCE ATOMS=1,2
      98             : PRINT ARG=d1 FILE=out1 RESTART=NO
      99             : PRINT ARG=d2 FILE=out2
     100             : ```
     101             : 
     102             : [!CAUTION]
     103             : The RESTART directive can have also other important side effects. For methods such as [METAD](METAD.md)
     104             : or [PBMETAD](PBMETAD.md) when the action is told to restart all the hills from the previous run are read
     105             : in at the start of the calculation so that the bias potential at the start of the restarted simulation is
     106             : identical to the bias potential at the end of the previous run.
     107             : 
     108             : If you are absolutely certain that you do not want to restart any of the actions in your input you
     109             : can use an input like the example below:
     110             : 
     111             : ```plumed
     112             : RESTART NO
     113             : d1: DISTANCE ATOMS=1,2
     114             : PRINT ARG=d1 FILE=out1
     115             : ```
     116             : 
     117             : The `RESTART NO` command in this input tells PLUMED that no actions are to be restarted even if the MD
     118             : code has told PLUMED that the initial configuration came from a checkpoint file and that the trajectory
     119             : is being restarted.
     120             : 
     121             : */
     122             : //+ENDPLUMEDOC
     123             : 
     124             : class Restart :
     125             :   public virtual ActionSetup {
     126             : public:
     127             :   static void registerKeywords( Keywords& keys );
     128             :   explicit Restart(const ActionOptions&ao);
     129             : };
     130             : 
     131             : PLUMED_REGISTER_ACTION(Restart,"RESTART")
     132             : 
     133          58 : void Restart::registerKeywords( Keywords& keys ) {
     134          58 :   ActionSetup::registerKeywords(keys);
     135          58 :   keys.addFlag("NO",false,"switch off restart - can be used to override the behavior of the MD engine");
     136          58 : }
     137             : 
     138          56 : Restart::Restart(const ActionOptions&ao):
     139             :   Action(ao),
     140          56 :   ActionSetup(ao) {
     141          56 :   bool no=false;
     142          56 :   parseFlag("NO",no);
     143          56 :   bool md=plumed.getRestart();
     144         111 :   log<<"  MD code "<<(md?"did":"didn't")<<" require restart\n";
     145          56 :   if(no) {
     146           1 :     if(md) {
     147           1 :       log<<"  Switching off restart\n";
     148             :     }
     149           1 :     plumed.setRestart(false);
     150           1 :     log<<"  Not restarting simulation: files will be backed up\n";
     151             :   } else {
     152          55 :     if(!md) {
     153          55 :       log<<"  Switching on restart\n";
     154             :     }
     155          55 :     plumed.setRestart(true);
     156          55 :     log<<"  Restarting simulation: files will be appended\n";
     157             :   }
     158          56 : }
     159             : 
     160             : }
     161             : }