Trajectory replay
*****************

For some applications it is necessary to run calculations on all (or a
subset of) frames from a trajectory obtained in another job. Often
this is done with a different engine in order to learn something about
the differences in the potential energy surface between the engines.
This could easily be scripted with PLAMS, but since the 2022.1 release
the AMS driver itself also implements a convenient "Replay" task to do
this.

The input for the replay task is quite minimal. The following input
file would replay every tenth frame of the first 1000 frames on the
trajectory of "oldjob" with the DFTB engine to calculate nuclear
gradients:

   Task Replay

   Replay
      File oldjob.results
      Frames 1:1000:10
   End

   Properties
      Gradients True
   End

   Engine DFTB
   EndEngine

See also:

  Example input files for replaying PES scans, NEB and MD
  calculations.

Note that it is not necessary to specify a System block in the input
of a replay job, as the system will just be loaded from the job to be
replayed. What properties are evaluated for each frame in the
trajectory can be configured in the "Properties" block of the input
file. For a list of available properties, see for example the manual
pages on Gradients, Hessian, Stress tensor, Elasticity and Dipole
moment, Polarizability, Bond orders.

Depending on the kind of job that is being replayed, you will get a
slightly different default behavior for the selection of frames to be
replayed:

* For PES scans only the frames corresponding to the converged PES
  points will be replayed. The resulting "ams.rkf" output file will
  contain the "PESScan" section, as if it had been produced by running
  a PES scan job.

* For Nudged Elastic Band (NEB) jobs only the frames corresponding to
  the converged images are replayed. The resulting "ams.rkf" file will
  have an "NEB" section that looks like it is from a NEB job that
  converged immediately.

* All other job types (such as Molecular Dynamics) will just replay
  whatever is on the "History" section on the "ams.rkf" file. By
  default all frames are replayed, but a subset can be chosen with the
  "Replay%Frames" keyword.

Note that the replay task does not use driver level parallelism. The
engine is called on each frame in turn, always restarting from the
previously calculated frame. (The restarting should not cause
problems, but it can be disabled with the
"EngineDebugging%IgnorePreviousResults" option, see developer
options).

Details of the Replay task can be configured in the "Replay" block in
the input.

   Replay
      File string
      Frames integer_list
      StoreAllResultFiles Yes/No
   End

"Replay"
   Type:
      Block

   Description:
      Configures the details of the Replay task.

   "File"
      Type:
         String

      GUI name:
         Restart from

      Description:
         Provide an ams.rkf file (or a .results folder) from a
         previously run job to replay. The file needs to contain a
         History section.

   "Frames"
      Type:
         Integer List

      Description:
         List of frames from the History section to recompute.
         If you use AMSmovie, you can use it to find the frame number,
         but add one since frame numbers in AMSmovie start at 0.
         If not specified the recomputed frames are determined
         automatically based on the task of the job that is being
         replayed: PES scans and NEB calculations will only have the
         converged points replayed, while all other tasks will have
         all frames recomputed.                      Specifying the
         frames to recompute in the input is probably only useful when
         replaying trajectories from MolecularDynamics calculations.

   "StoreAllResultFiles"
      Type:
         Bool

      Default value:
         No

      Description:
         If this option is enabled AMS will produce a separate engine
         output file for every replayed frame.
         While basic properties like energy, gradients, stress tensor,
         etc. are stored anyway on the History section in the AMS
         driver output file (if they were requested in the Properties
         block), engine specific properties (e.g. excitations energies
         from ADF) will only be available if the full result files are
         stored.
