Hybrid Engine Options
*********************


Sub-engines and EngineIDs
=========================

Inside the Hybrid engine input block one or more sub-engine blocks can
be defined. These have exactly the same format as regular engine
blocks. There is, however, one extra feature: the "EngineId".
Optionally, a unique name can be added to the engine definition as an
extra string, serving as an identifier. By default the identifier is
simply the engine name. The extra string allows the user to select the
same engine multiple times, each time  with different settings.

This is an example, where we use the same engine (ADF) with two
different spin polarizations, using results corresponding to the
lowest energy.

   Engine Hybrid
       Energy # we want results from the engine that yields the lowest energy to be this engine's result
          DynamicFactors UseLowestEnergy
          # The user-supplied factors are irrelevant here so we omit them
          Term EngineId=adf-singlet Region=*
          Term EngineId=adf-triplet Region=*
       End

       Engine ADF adf-singlet   # here adf-singlet is the EngineID
         SpinPolarization 0
         Unrestricted False
       EndEngine

       Engine ADF adf-triplet
         SpinPolarization 2
         Unrestricted True
       EndEngine

   EndEngine

EngineIDs are for instance used in the technical example QUILD, which
tests that EngineIDs are case-insensitive.

   Engine header

"Engine"
   Type:
      Block

   Recurring:
      True

   Description:
      The input for the computational (sub) engine. The header of the
      block determines the type of the engine. An optional second word
      in the header serves as the EngineID, if not present it defaults
      to the engine name. Currently it is not allowed to have a Hybrid
      engine as a sub engine.


Linear Combination of Energy Terms
==================================

The block "Energy" triggers a QUILD-like setup, allowing the energy to
be defined as a linear combination of energy terms. Each energy term
can be computed for a different subset of the molecular system, and
with a different engine.

See the basic QUILD example. As you can see capping can be enabled per
energy term, and the user can set a charge per term (for the
corresponding region). One can also switch off the  periodic boundary
conditions for individual terms, using the "PBC" keyword. The latter
can be used in a QM/MM setup (three energy terms), to have the
interactions across the periodic boundary computed fully with the MM
engine.

   Energy
      DynamicFactors [Default | UseLowestEnergy | UseHighestEnergy]
      Term
         Charge float
         EngineID string
         Factor float
         PBC Yes/No
         Region string
         UseCappingAtoms Yes/No
      End
   End

"Energy"
   Type:
      Block

   Description:
      This block is there to construct the energy.

   "DynamicFactors"
      Type:
         Multiple Choice

      Default value:
         Default

      Options:
         [Default, UseLowestEnergy, UseHighestEnergy]

      GUI name:
         Adjust factors

      Description:
         Default - use factors as set in the corresponding Term
         blocks;                       UseLowestEnergy - set all
         factors to 0 except for that of the engine with the lowest
         energy, which is set to 1;
         UseHighestEnergy - set all factors to 0 except for that of
         the engine with the highest energy, which is set to 1.
         The last two options make sense only for non-QMMM hybrid
         calculation (that is, if the QMMM block is not present) and
         only when using engines whose energies can be compared
         directly.

   "Term"
      Type:
         Block

      Recurring:
         True

      Description:
         This block is there to construct the energy term. Can have
         multiple occurrences

      "Charge"
         Type:
            Float

         Default value:
            0.0

         Description:
            Net charge to be used for this energy term.

      "EngineID"
         Type:
            String

         Description:
            Identifier for the engine

      "Factor"
         Type:
            Float

         Default value:
            1.0

         Description:
      "PBC"
         Type:
            Bool

         Default value:
            Yes

         Description:
            If the full system has a periodic lattice, apply it to the
            region

      "Region"
         Type:
            String

         Description:
            Identifier for the region

      "UseCappingAtoms"
         Type:
            Bool

         Default value:
            Yes

         Description:
            Whether to use capping for broken bonds


QM/MM
=====

The alternative to the "Energy" block is the "QMMM" block, which
triggers a two-layer computation. The embedding type can be selected
with the "Embedding" key, for which mechanical or electrostatic can be
selected. The former option triggers a specific linear combination of
three energy terms, and can therefore also be set up using the
"Energy" block (see basic QUILD example).

See the basic electrostatic embedding example. Capping can be
disabled, and charges can be set for the QM and MM regions.

   QMMM
      Embedding [Mechanical | Electrostatic]
      MMCharge float
      MMEngineID string
      QMCharge float
      QMEngineID string
      QMRegion string
      UseCappingAtoms Yes/No
   End

"QMMM"
   Type:
      Block

   Description:
      This block is there to identify the QMMM engines.

   "Embedding"
      Type:
         Multiple Choice

      Default value:
         Electrostatic

      Options:
         [Mechanical, Electrostatic]

      Description:
         Determines how the QM region is embedded into the MM region.
         Mechanical embedding embedding can also be achieved using the
         Energy%Terms keywords, but the common case of a two region
         mechanical QM/MM embedding is easier to set up using this
         keyword.

   "MMCharge"
      Type:
         Float

      Default value:
         0.0

      Description:
         Net charge to be used for the MM region.

   "MMEngineID"
      Type:
         String

      Description:
         Identifier for the MM engine

   "QMCharge"
      Type:
         Float

      Default value:
         0.0

      Description:
         Net charge to be used for the QM region.

   "QMEngineID"
      Type:
         String

      Description:
         Identifier for the QM engine

   "QMRegion"
      Type:
         String

      Description:
         Identifier for the QM region. The rest of the system is
         considered the MM region.

   "UseCappingAtoms"
      Type:
         Bool

      Default value:
         Yes

      Description:
         Whether to use capping for broken bonds.


Committee
=========

It is also possible to run the hybrid engine in "Committee" mode. When
using the hybrid engine as a committee, the average is taken of each
engine, meaning that all the regions and factors must be the same.
Additionally, the spread of results of the different engines is
understood as an uncertainty. The standard deviation of the different
engine energies and forces are computed and reported as the
uncertainty.

   Committee
      Enabled Yes/No
   End

"Committee"
   Type:
      Block

   Description:
      Settings for using the hybrid engine as a committee. The factors
      and region for each engine must be the same. When committee is
      enabled the standard deviation is also reported as the
      uncertainty.

   "Enabled"
      Type:
         Bool

      Default value:
         No

      Description:
         Enable committee


Capping
=======

Whether of not capping is enabled is set inside the "Energy" and
"QMMM" blocks. If enabled then the user can influence the position and
type of the capping atom with the "Capping" sub-block.

   Capping
      AllowHighBondOrders Yes/No
      AtomicInfoForCappingAtom string
      CappingElement string
      CheckCapping Yes/No
      Distance float
      Option [Fractional | Fixed]
   End

"Capping"
   Type:
      Block

   Description:
      This block is about capping details. Capping occurs with
      hydrogen atoms when a bond is broken between an atom inside the
      region and one outside.

   "AllowHighBondOrders"
      Type:
         Bool

      Default value:
         No

      Description:
         Allows capping of interregional aromatic, double and triple
         bonds. This is normally not a good idea, since the capping is
         done with hydrogen atoms.

   "AtomicInfoForCappingAtom"
      Type:
         String

      Default value:
         ForceField.Type=H_ ForceField.Charge=0.0

      Description:
         The AtomicInfo for the capping atoms. Typically a string like
         ForceField.Type=X much like forcefield info is entered in the
         System block for normal atoms.

   "CappingElement"
      Type:
         String

      Default value:
         H

      Description:
         The element to be used for capping. The hydrogen atom has the
         advantage that it is very small.

   "CheckCapping"
      Type:
         Bool

      Default value:
         Yes

      Description:
         The same outside atom can be involved in multiple capping
         coordinate definitions. This is not a good idea, and this
         will not be accepted by using this check.

   "Distance"
      Type:
         Float

      Default value:
         -1.0

      Description:
         A negative value means automatic. In that case the sum of
         covalent radii is used

   "Option"
      Type:
         Multiple Choice

      Default value:
         Fixed

      Options:
         [Fractional, Fixed]

      GUI name:
         Capping option

      Description:
         The capping atom is always along the broken bond vector.
         The bond distance between the capping atom and the two atoms
         are obtained from covalent radii, let us call them D1H and
         D2H.                      With option=Fractional the capping
         is on the bond vector with the fraction D1H/(D1H+D2H).
         With the Fixed option it at the distance D1H from atom 1. A
         distance of zero always means the coordinate of the inside
         atom.

For a specific application of QM/MM with capping atoms see this
example.


Restarts
========

In a molecular dynamics run or geometry optimization, the geometries
at subsequent steps are often very similar. Generally, efficiency can
be gained by providing the engines with information from the previous
step ("restart"), as this might speed up the SCF or charge
equilibration procedure, if applicable. To the forcefield engine, this
might avoid re-loading of the database, guessing bonds, etc. at every
step. By default all sub-engines are provided with restart
information. It can be switched off with the "RestartSubEngines" key.

   RestartSubEngines Yes/No

"RestartSubEngines"
   Type:
      Bool

   Default value:
      Yes

   Description:
      Save all the results of the subengines and pass those in a next
      geometry step or MD step.


Charges per region
==================

The user can specify charges per region associated with each energy
term.

Depending on the setup the charges can be set with the
"Energy%Term%Charge" or the "QMMM%mmCharge" and "QMMM%mmCharge" keys.

For a QM engine the charge for a region determines the number of
electrons in the region defined in the energy term. For the ForceField
engine, charges are specified per atom, and they should add up to the
charge specified for the region.


Linear Combination of Energy Terms
----------------------------------

When the Linear Combination of Energy Terms feature is selected, but
using the "Energy" block, the energy is a linear combination of
independent calculations. It is in this spirit that the total charge
is considered to be

   Q = \sum_i^N w_i \; Q^\text{engine(i)}\big(region(i)\big)

In the QMMM setup the total charge is the sum of the charge of the mm
region and the qm region.

When "Energy%DynamicFactors" is set to anything other than "Default"
the factors specified in the Term blocks are not used.


Electrostatic Embedding
-----------------------

In general, the charges for sub-regions should be consistent with the
charge specified for the total system. However, in the case of an
electrostatic embedding computation with capping atoms, the sum of
charges of the subsystems used in the computation of the five energy
terms is allowed to deviate from the total system charge.

   E = E^{MM}(E) + E^{QM}\big(\text{A}_C(V^\text{E})\big) +
   E^\text{MM}_\text{nonelstat}(\text{A+E}) -
   E^\text{MM}_\text{nonelstat}(\text{A}_C) -
   E^\text{MM}_\text{nonelstat}(\text{E})

The MM region that will be passed to the MM engine (term 1) will often
have a fractional charge, due to un-capped dangling bonds. The
fractional charge of the QM-region however (term 2), should be
corrected by the capping atom charges, to yield a chemical system that
optimally resembles the full system. As a result, the sub-region
charges do not need to add up to the total charge of the system.
