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 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).

Energy
   DynamicFactors [Default | UseLowestEnergy | UseHighestEnergy]
   Term
      Charge float
      EngineID string
      Factor float
      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

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.

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.