QC/MM with xTB

Introduction

This guide provides a complete walkthrough for integrating the xTB (extended Tight-Binding) quantum chemistry package with pDynamo3, allowing you to perform semiempirical QM and hybrid QM/MM calculations using xTB as the backend. You can use xTB in pDynamo via its interface with the ORCA program, and if that is the case, this tutorial is not necessary. However, there are some technical advantages to using xTB directly within pDynamo without relying on the ORCA interface. These include access to additional information from the xTB output logs, support for optional keywords, and easier parallelization.

Step 1 – Download and Install xTB

The first step is to obtain the xTB software. Developed by the Grimme group, xTB is freely available for academic use. It supports a variety of semiempirical methods, such as GFN1-xTB and GFN2-xTB, making it highly suitable for large-scale or hybrid QM/MM simulations.

•     Visit the official repository or the precompiled releases page:

https://github.com/grimme-lab/xtb

•     Download the latest stable release for your operating system.

•     Unpack the archive and move the extracted folder to your preferred programs directory. For example:
  
  

mkdir -p $HOME/programs

cd $HOME/programs

tar -xvzf xtb-6.6.1.tar.xz

Step 2 – Add the xTB Module to pDynamo

pDynamo does not include xTB support natively, but you can enable it via a custom module. The required file is QCModelXTB.py, which implements the interface between pDynamo and xTB. Copy this file into the following pDynamo source directory:

.../pDynamo3/pMolecule/QCModel

In the same directory, open the __init__.py file and add the following line at the end of the import section:

from .QCModelXTB import _XTBCommand, QCModelXTB

This line ensures that your new xTB model will be available from within pDynamo’s module tree.

Step 3 – Define the xTB Environment Variable

To allow pDynamo to locate and execute the xTB binary, you need to set an environment variable that points to the xTB executable.

• File to edit:

.../pDynamo3/installation/shellScripts/environment_bash.com

• Add the following line at the end of the file (adjust the path to match your setup):

# Path to xTB binary

PDYNAMO3_XTBCOMMAND=$HOME/programs/xtb-6.6.1/bin/xtb          ; export PDYNAMO3_XTBCOMMAND

This example is the xTB version of Example 9 from the classic book examples in pDynamo.

import os

#---------------------------------------

from pBabel                    import*                                     

from pCore                     import*  

#---------------------------------------

from pMolecule                 import*                              

from pMolecule.MMModel         import*

from pMolecule.NBModel         import*                                     

from pMolecule.QCModel         import*

#---------------------------------------

from pScientific               import*                                     

from pScientific.Arrays        import*                                     

from pScientific.Geometry3     import*                                     

from pScientific.RandomNumbers import*                                     

from pScientific.Statistics    import*

from pScientific.Symmetry      import*

#---------------------------------------                              

from pSimulation               import*

#---------------------------------------

#-----------------------------------------------------------------------

# . Local name.

_name  = "book"

# . The input data paths.

dataPath = TestScript_InputDataPath ( _name )

molPath  = os.path.join ( dataPath, "mol" )

#-----------------------------------------------------------------------

# . Header.

logFile.Header ( )

# . Define the MM.

mmModel = MMModelOPLS.WithParameterSet ( "bookSmallExamples" )

# . Define the molecule.

system = ImportSystem ( os.path.join ( molPath, "bala_c7eq.mol" ) )

# . Define the selection for the methyl group - QC atoms

methylGroup = Selection.FromIterable ( [ 10, 11, 12, 13 ] )

# . Eletronic State

electronicState = ElectronicState.WithOptions ( charge = 0   , 

                                          multiplicity = 1   , 

                                      isSpinRestricted = True)

system.electronicState = electronicState

# . Defining QC model 

qcModel = QCModelXTB.WithOptions ( 

                                 gfn        = 2   ,  # default = 2 ----> 1 = GFN1-xTB / 2 = GFN2-xTB  

                                 parallel   = 1   ,  # default = 1 ----> Number of CPUs           

                                 acc        = 1.0 ,  # default = 1                 

                                 fermi_temp = 300 ,  # default = 300          

                                 iterations = 300 ,  # default = 300

                                 #keywords   = None ,  # Any aditional xTB keyword

                                 #scratch    = path ,  # default is the pDynamo scrath folder                                 )

# . Defining NB model -  xTB uses the same as ORCA 

nbModel = NBModelORCA.WithDefaults ( )

# . Define the energy model.

system.DefineMMModel ( mmModel )

system.DefineQCModel ( qcModel, qcSelection = methylGroup )

system.DefineNBModel ( nbModel )

# .  Energy and Summary

system.Energy()

system.Summary ( )