Molecular dynamics
******************

To enable the molecular dynamics, set "MolecularDynamics%Enabled" to
Yes. If it is set to No, you can still load previously run MD
simulations and continue with the Network Extraction and Product
Ranking parts.

The reactions discovery tool implements special non-equilibrium MD
methods to promote chemical reactions, namely the Nanoreactor and
Lattice deformation. The type is controlled by
"MolecularDynamics%Type".

The number of simulations to run is controlled by
"MolecularDynamics%NumSimulations". To get enough statistics, it is
recommended to run several MD simulations. The results will be
gathered into a single summary in the Network Extraction and Product
Ranking parts.

To replace all hydrogens with deuterium set
"MolecularDynamics%UseDeuterium Yes". If you prefer, you can use a
bond guessing algorithm instead of the engine-calculated bonds by
setting "MolecularDynamics%BondOrders%Method" to "Guess".

See also: Bond orders & Molecule detection

   MolecularDynamics
      Enabled Yes/No
      Type [NanoReactor | LatticeDeformation | Restart]
      NumSimulations integer
      UseDeuterium Yes/No
      TimeStep float
      BondOrders
         Method [Guess | EngineWithGuessFallback]
      End
   End

"MolecularDynamics"
   Type:
      Block

   Description:
      Settings for reactive molecular dynamics.

   "Enabled"
      Type:
         Bool

      Default value:
         Yes

      GUI name:
         Reactive Molecular Dynamics

      Description:
         Whether to run molecular dynamics.

   "Type"
      Type:
         Multiple Choice

      Default value:
         NanoReactor

      Options:
         [NanoReactor, LatticeDeformation, Restart]

      Description:
         The type of molecular dynamics.

   "NumSimulations"
      Type:
         Integer

      Default value:
         4

      GUI name:
         Number of simulations

      Description:
         Total number of MD simulations to run.

   "UseDeuterium"
      Type:
         Bool

      Default value:
         No

      Description:
         If true, all hydrogen atoms will be replaced by deuterium
         during the MD. This helps to slow down the motion of the
         hydrogen atoms. This options does *not* affect the density
         you should insert in BuildSystem%Density. However, it *does*
         affect the density on the resulting MD trajectory file.

   "TimeStep"
      Type:
         Float

      Default value:
         0.5

      Unit:
         fs

      Description:
         Molecular dynamics time step.

   "BondOrders"
      Type:
         Block

      Description:
         Details regarding the calculation/guessing of bond orders
         during Molecular Dynamics. The bond changes during the MD are
         later analyzed in the Network Extraction step.

      "Method"
         Type:
            Multiple Choice

         Default value:
            EngineWithGuessFallback

         Options:
            [Guess, EngineWithGuessFallback]

         Description:
            How to compute the bond orders.
            'Guess': Use a bond guessing algorithm based on the
            system's geometry. This is the same algorithm that is used
            by the Graphical User Interface to guess bonds.
            'EngineWithGuessFallback': let the engine compute the bond
            orders but if the engine did not produce any bond orders,
            use the bond guessing algorithm as a fallback option.


Nanoreactor
===========

To enable the nanoreactor mode, set "MolecularDynamics%Type" to
"NanoReactor".

The nanoreactor is run **without** periodic boundary conditions.
Details can be found in the Nanoreactor AMS Driver documentation.

The following 4 phases are looped throughout the simulation:

+----------------------+----------------------+----------------------+----------------------+----------------------+
| phase                | volume fraction      | time (fs)            | thermostat T (K)     | force constant       |
|                      |                      |                      |                      | (Ha/bohr^2)          |
|======================|======================|======================|======================|======================|
| pre_compression      | 1.05                 | 25                   | 250                  | 0.0005               |
+----------------------+----------------------+----------------------+----------------------+----------------------+
| compression          | "MinVolumeFraction"  | 25                   | 250                  | 0.01                 |
+----------------------+----------------------+----------------------+----------------------+----------------------+
| post_compression     | 1.05                 | 100                  | 250                  | 0.0005               |
+----------------------+----------------------+----------------------+----------------------+----------------------+
| diffusion            | 1.05                 | "DiffusionTime"      | "Temperature"        | 0.0004               |
+----------------------+----------------------+----------------------+----------------------+----------------------+

The radius of the nanoreactor for each individual phase is calculated
as:

* r_nanoreactor (per phase) = *volume fraction*^1/3 * "InitialRadius"

"InitialRadius" is automatically determined, but can also be
explicitly specified in the input.

If you want to customize any numbers other than "MinVolumeFraction",
"DiffusionTime", and "Temperature", or if you want to change the
number of phases, you can

* set up your own NanoReactor simulations outside the Reactions
  Discovery tool, and then

* specify the path to the results using NetworkExtraction.

All nanoreactor-specific input options:

   MolecularDynamics
      NanoReactor
         DiffusionTime float
         InitialRadius float
         MinVolumeFraction float
         NumCycles integer
         Temperature float
      End
   End

"MolecularDynamics"
   Type:
      Block

   Description:
      Settings for reactive molecular dynamics.

   "NanoReactor"
      Type:
         Block

      Description:
         Option for the reactive molecular dynamics.

      "DiffusionTime"
         Type:
            Float

         Default value:
            250.0

         Unit:
            fs

         Description:
            The length of the diffusion phase in femtoseconds.

      "InitialRadius"
         Type:
            Float

         Unit:
            angstrom

         Description:
            The radius of the initial (spherical) system. If
            "BuildSystem" is used, the value is ignored (then the
            value is automatically determined). If "BuildSystem" is
            not used, then a guess for the "InitialRadius" will be
            made if it is not specified.

      "MinVolumeFraction"
         Type:
            Float

         Default value:
            0.6

         GUI name:
            Minimum volume fraction

         Description:
            The minimum (compressed) volume of the system, as a
            fraction of the initial (maximum) system volume.

      "NumCycles"
         Type:
            Integer

         Default value:
            10

         GUI name:
            Number of cycles

         Description:
            How many compression-expansion cycles to perform.

      "Temperature"
         Type:
            Float

         Default value:
            500.0

         Unit:
            K

         Description:
            Temperature during the diffusion phase. The temperature
            during the compression phase will be much higher as a
            result of the inward acceleration.


Lattice deformation
===================

To enable the lattice deformation mode, set "MolecularDynamics%Type"
to "LatticeDeformation".

Lattice deformation requires that the system is 3D-periodic. For more
details, see the MDDeformation AMS Driver documentation.

The volume oscillates for "NumCycles" cycles with a period of "Period"
fs between

* V_initial, and

* V_compressed = V_initial* "MinVolumeFraction".

All lattice deformation input options:

   MolecularDynamics
      LatticeDeformation
         MinVolumeFraction float
         NumCycles integer
         Period float
         Temperature float
      End
   End

"MolecularDynamics"
   Type:
      Block

   Description:
      Settings for reactive molecular dynamics.

   "LatticeDeformation"
      Type:
         Block

      Description:
         Option for the reactive molecular dynamics.

      "MinVolumeFraction"
         Type:
            Float

         Default value:
            0.3

         GUI name:
            Minimum volume fraction

         Description:
            The minimum (compressed) volume of the system, as a
            fraction of the initial (maximum) system volume.

      "NumCycles"
         Type:
            Integer

         Default value:
            10

         GUI name:
            Number of cycles

         Description:
            How many compression-expansion cycles to perform.

      "Period"
         Type:
            Float

         Default value:
            100.0

         Unit:
            fs

         Description:
            The period with which the lattice will oscillate in
            femtoseconds.

      "Temperature"
         Type:
            Float

         Default value:
            500.0

         Unit:
            K

         Description:
            Thermostat temperature during the MD simulation.


Build the initial system
========================

Note:

  This section describes a convenient way to build the system directly
  from the input.You can also build the initial system in any way you
  like. Then set "MolecularDynamics%BuildSystem%Enabled" to "False"
  and give the coordinates/lattice or coordinate file in the "System"
  block.

BuildSystem will build a

* **sphere centered at the origin** if "MolecularDynamics%Type" is
  "NanoReactor" - the radius of the sphere will automatically be
  passed on to the "NanoReactor" settings.

* **cubic box** if "MolecularDynamics%Type" is "LatticeDeformation".

The **initial system** is specified through a series of "Molecule"
blocks. Each "Molecule" block contains either a SMILES string or a
reference to a "System" block, as well as the mole fraction of that
particular molecule.

The **initial density** and the **system size** are specified with the
"Density" and "NumAtoms" keywords:

You can choose to run a short **equilibration simulation** by setting
"Equilibration". This can be useful if the packmol-generated structure
is unrealistic.

   MolecularDynamics
      BuildSystem
         Density float
         Enabled Yes/No
         Equilibration Yes/No
         Molecule
            MoleFraction float
            SMILES string
            SystemID string
         End
         NumAtoms integer
      End
   End

"MolecularDynamics"
   Type:
      Block

   Description:
      Settings for reactive molecular dynamics.

   "BuildSystem"
      Type:
         Block

      Description:
         Build the initial system for molecular dynamics with packmol.
         If "MolecularDynamics%Type" is set to "Restart", then
         BuildSystem is ignored.

      "Density"
         Type:
            Float

         Default value:
            1.0

         Unit:
            g/cm^3

         Description:
            The initial density of the system. This should be the
            lowest density (corresponding to the largest volume) that
            you want the system to have. The standard atomic masses
            are used when building the system.

      "Enabled"
         Type:
            Bool

         Default value:
            Yes

         GUI name:
            Build System

         Description:
            If True, build the initial system using packmol. If False,
            a System block must be provided with the initial system.

      "Equilibration"
         Type:
            Bool

         Default value:
            No

         Description:
            Whether to run a short 250 fs equilibration simulation on
            the packmol-built structure.

      "Molecule"
         Type:
            Block

         Recurring:
            True

         Description:
            A molecule to put in the MD simulation.

         "MoleFraction"
            Type:
               Float

            Default value:
               1.0

            GUI name:
               Relative mole fraction

            Description:
               Mole fraction of the molecule (the mole fractions of
               the various molecules will be normalized, so only the
               relative MoleFraction values matter)

         "SMILES"
            Type:
               String

            Description:
               The SMILES string of the molecules.

         "SystemID"
            Type:
               String

            Description:
               The ID of the corresponding System (i.e. the header of
               the corresponding System block).

      "NumAtoms"
         Type:
            Integer

         Default value:
            200

         GUI name:
            Number of atoms

         Description:
            Approximate total number of atoms in each MD simulation.


Fixed MD settings
=================

The reactions discovery tool automatically sets the following for all
MD simulations:

* wca_potential_addon,

* Frames are saved every 10 fs. To save disk space, velocities are not
  saved.

* MD checkpoints are saved every 1000 MD steps (allowing to "Restart")

* A Berendsen thermostat with a very short time constant and
  "BerendsenApply = Local".

For a complete view of all the MD input, open the "mdsim_0/mdsim_0.in"
file created by the Reactions Discovery tool.

See also: MolecularDynamics in the AMS Driver documentation


Molecular dynamics restart
==========================

Set "MolecularDynamics Type=Restart" in order to

* continue interrupted MD simulations (for example if they exceeded
  the walltime limit), or

* add extra steps to already finished MD simulations

   MolecularDynamics
      Restart
         Directory string
         NSteps integer
      End
   End

"MolecularDynamics"
   Type:
      Block

   Description:
      Settings for reactive molecular dynamics.

   "Restart"
      Type:
         Block

      Description:
         Settings for restarting MD simulations.

      "Directory"
         Type:
            String

         GUI name:
            Restart directory

         Description:
            Directory containing a previous Reactions Discovery
            calculation with MD simulations that were not finished.
            Note: This directory will be scanned recursively for
            ams.rkf files!

      "NSteps"
         Type:
            Integer

         GUI name:
            Number of steps

         Description:
            Number of MD steps. If left empty, the number of MD steps
            from the original MD trajectory will be used. Note that
            you need to manually increase this number if you want to
            continue finished simulations.


Example: restart MD simulations after they exceeded walltime limit
------------------------------------------------------------------

Input:

   MolecularDynamics
       Enabled Yes
       Type Restart
       Restart
           Directory /some/path
       End
   End
   Engine ...
       ...
   EndEngine

If "/some/path" contains the following files:

   /some/path/dir1/ams.rkf
   /some/path/dir2/subdir/ams.rkf

where those "ams.rkf" files come from MD simulations, then if

* ams.rkf contains **an unfinished simulation** (e.g. because the job
  exceeded the walltime limit), it will be restarted from where it
  finished, but if

* ams.rkf contains **a finished simulation**, then the trajectory will
  simply be copied

Note:

  * The rest of the "MolecularDynamics" reactions discovery input
    block is **ignored**, meaning that it doesn't matter if you
    specify "LatticeDeformation" or "NanoReactor" or their respective
    settings. The MD settings from the "ams.rkf" file will be used.

  * The "Engine" block from the reactions discovery input block is
    **used**.

  * If you restart from a previous reactions discovery results
    directory (which you likely do), then it may contain several
    directories "mdsim_0", "mdsim_1", etc., or you may have called
    them something else if you set up the MD simulations manually. The
    **numbering may change** in the restart run, so that the new
    "mdsim_1" actually continues the trajectory from the original
    "mdsim_0".


Example: Continue MD simulations for more steps
-----------------------------------------------

   MolecularDynamics
       Enabled Yes
       Type Restart
       Restart
           Directory /some/path
           NSteps 20000
       End
   End
   Engine ...
       ...
   EndEngine

The above will continue all MD simulations until 20000 steps. If the
original simulation ran for 5000 steps, then the new simulation will
continue for another 15000 steps.
