This guide is aimed to give a general overview of the ONIOM implementation within the xtb program package.


This feature is only present in version 6.6 and newer or in the current bleeding-edge version.

General description

The ONIOM scheme is a multiscale calculation approach used to treat large molecular systems efficiently. A detailed review of the ONIOM scheme and its possible applications can be found at: Chung2015.

The total two-layer ONIOM energy is defined as

\[E_{oniom} = E_{whole, low} - E_{model, low} + E_{model ,high},\]

where \(E_{whole, low}\) and \(E_{model, low}\) terms are the single-point energies calculated at a low-level of theory of the whole system and a specific system cutoff (called henceforward ‘inner region’). \(E_{model, high}\) denotes the single-point energy of the inner region at a higher level of theory. The idea is to combine the different theory levels in a subtractive manner to compromise accuracy and speed.


To perform an ONIOM calculation with xtb the --oniom option is used. The inner region has to be defined by providing the atom numbers contained in it and two calculation methods (high:low) can be chosen. The ONIOM calculation is then invoked by callinig:

> xtb <geometry_file> --oniom [high]:[low] [inner_region]


If high:low are not provided, the gfn2:gfnff combination is used.


  • gfnff, gfn1, gfn2

These methods are available in the xtb and can be utilized both as high and low-level approaches in the ONIOM framework.


The ONIOM routine includes but is not limited to the xtb functionality. To expand the range of the available methods, the external ORCA and TURBOMOLE software packages can be employed. This is done by the addition of the corresponding binary path in the environment variable $PATH.

The best way to configure the external settings for the xtb run is to use xcontrol instructions.

  • orca

If ORCA should be employed, an orca input has to be provided to run calculations. An additional instruction file like xcontrol allows to specify the user-supplied orca input by adding the follwing lines:

   orca input file=<filename>

or to provide only calculation method:

   orca input string=<method>

If no input is specified, xtb writes an orca input with the default settings (B97-3c).

  • turbomole

Turbomole also uses its format to perform calculations, defined by the control file. Initially, the xtb searches for the control file in the user’s calculation directory, and if no file is present, writes it with some default settings (B97-3c).


Currently, it is possible to use ORCA/TURBOMOLE only as the high level embedding.

Inner region

To perform the ONIOM calculations with xtb one has to specify the inner_region_cutoff which is provided either directly as comma-separated indices (“1,3-5,9,10”), or via a file with the same content (or each index on a separate line).

If covalent bonds are cut between the inner region and the rest of the system, ONIOM handles the resulting boundary through Hydrogen Linked Atoms (LAs):

The positions for LAs are determined by the positions of the cleaved atoms:

\[[xyz]_{LA} = [xyz]_{con} +([xyz]_{host} - [xyz]_{con}) * k\]

where \([xyz]_{con}\) and \([xyz]_{host}\) are coordinates of connector atom (stays in the inner region) and host atom (replaced by LA), \(k\) is a fixed scaling factor.


To distinguish between different bonds the topology information from the low level method is used.


It is strongly recommended to cut only single bonds. When using the GFN-FF as a low-level method, one has to be very careful with the inner region specification. The topology data of the GFN-FF does not allow for an accurate distinction between single and higher-order bonds.



--chrg ‘int:int’:

extension of the classical --chrg flag, allows to specify charges for inner region and whole molecule as inner_region_charge:system_charge. If only one value is given, it is used as system_charge, and the xtb will determine the inner_region_charge automatically.


If inner_region_charge is specified in the external input format file(*.inp or control), one has to provide the same charge to the xtb as:

> xtb <geometry_file> --oniom <orca/turbomole>:<xtb> <inner_region> --chrg <inner_region_charge>:<system_charge>

write the geometry of the specified inner region without performing any calculations. Note that hydrogen-linked atoms are not present, due to the absence of the Wiberg bond orders. In addition, this procedure can be used to test the abovementioned automatic inner region charge determination.


extension of the original flag, with instructions for the xtb to delete all external files from ORCA/TURBOMOLE (except for *.inp and control files)


In addition to the above-mentioned xcontrol instructions deeper control over the ONIOM routine is available via the $oniom group block.

inner logs=[bool]

print high- and low-level optimization trajectory for the model system (high.inner_region.log and low.inner_region.log).

derived k=[bool]

k is a scaling factor for the LAs coordinates, which by default is constant. This instruction allows it to be dynamically assigned in dependence on the distance between the connector and host atoms.


perform outer region saturation

ignore topo=[bool]

bypass topology check when cutting bonds


redirecting the output of the external programs into files.

Example: S30L-23

As a showcase host-guest complex number 23 from S30L benchmark is chosen.


This system consists of 2 NCI-bound fragments: 1-62 and 63-98, the latter having +1 charge. To test the automatic charge identification routine:

To start single-point calculation with the user-defined orca input file:

  1. specify orca input and add its name in the xcontrol file:

Please use the engrad keyword to allow xtb to read the ORCA output. The inner region is automatically written in the some.xyz file.

  1. start xtb run:

> xtb input.xyz --oniom orca:gfn2 1-62 --chrg +1 --input xcontrol

The final xtb output for the given example is divided into 3 parts with the ONIOM results printed in the property printout section:


        Singlepoint calculation of whole system with low-level method


   ... skip ...


        Singlepoint calculation of inner region with low-level method


   ... skip ...


        Singlepoint calculation of inner region with high-level method


   ... skip ...

            |                Property Printout                |

             | TOTAL ENERGY            -1438.298999659396 Eh   |
             | GRADIENT NORM               0.045824034529 Eh/α |