Package: dftd3
Python interface for the D3 dispersion model.
This Python project is targeted at developers who want to interface their project via Python withs-dftd3.This interface provides access to the C-API ofs-dftd3via the CFFI module.
The low-level CFFI interface is available in thedftd3.libdftd3module and only required for implementing other interfaces.
A more pythonic interface is provided in thedftd3.interfacemodule which can be used to build more specific interfaces.fromdftd3.interfaceimportRationalDampingParam,DispersionModelimportnumpyasnpnumbers=np.array([1,1,6,5,1,15,8,17,13,15,5,1,9,15,1,15])positions=np.array([# Coordinates in Bohr[+2.79274810283778,+3.82998228828316,-2.79287054959216],[-1.43447454186833,+0.43418729987882,+5.53854345129809],[-3.26268343665218,-2.50644032426151,-1.56631149351046],[+2.14548759959147,-0.88798018953965,-2.24592534506187],[-4.30233097423181,-3.93631518670031,-0.48930754109119],[+0.06107643564880,-3.82467931731366,-2.22333344469482],[+0.41168550401858,+0.58105573172764,+5.56854609916143],[+4.41363836635653,+3.92515871809283,+2.57961724984000],[+1.33707758998700,+1.40194471661647,+1.97530004949523],[+3.08342709834868,+1.72520024666801,-4.42666116106828],[-3.02346932078505,+0.04438199934191,-0.27636197425010],[+1.11508390868455,-0.97617412809198,+6.25462847718180],[+0.61938955433011,+2.17903547389232,-6.21279842416963],[-2.67491681346835,+3.00175899761859,+1.05038813614845],[-4.13181080289514,-2.34226739863660,-3.44356159392859],[+2.85007173009739,-2.64884892757600,+0.71010806424206],])model=DispersionModel(numbers,positions)res=model.get_dispersion(RationalDampingParam(method="pbe0"),grad=False)print(res.get("energy"))# Results in atomic units# => -0.029489232932494884QCSchema IntegrationThis Python API natively understands QCSchema and theQCArchive infrastructure.
If the QCElemental package is installed thedftd3.qcschemamodule becomes importable and provides therun_qcschemafunction.fromdftd3.qcschemaimportrun_qcschemaimportqcelementalasqcelatomic_input=qcel.models.AtomicInput(molecule=qcel.models.Molecule(symbols=["O","H","H"],geometry=[0.00000000000000,0.00000000000000,-0.73578586109551,1.44183152868459,0.00000000000000,0.36789293054775,-1.44183152868459,0.00000000000000,0.36789293054775],),driver="energy",model={"method":"tpss",},keywords={"level_hint":"d3bj",},)atomic_result=run_qcschema(atomic_input)print(atomic_result.return_result)# => -0.0004204244108151285ASE IntegrationTo integrate withASEthis interface implements an ASE Calculator.
TheDFTD3calculator becomes importable if an ASE installation is available.>>>fromase.buildimportmolecule>>>fromdftd3.aseimportDFTD3>>>atoms=molecule('H2O')>>>atoms.calc=DFTD3(method="TPSS",damping="d3bj")>>>atoms.get_potential_energy()-0.0114416338147162>>>atoms.calc.set(method="PBE"){'method':'PBE'}>>>atoms.get_potential_energy()-0.009781913226281063>>>atoms.get_forces()array([[-0.00000000e+00-0.00000000e+009.56568982e-05][-0.00000000e+00-4.06046858e-05-4.78284491e-05][-0.00000000e+004.06046858e-05-4.78284491e-05]])To use theDFTD3calculator as dispersion correction the calculator can be combined using theSumCalculatorfrom thease.calculators.mixingmodule.>>>fromase.buildimportmolecule>>>fromase.calculators.mixingimportSumCalculator>>>fromase.calculators.nwchemimportNWChem>>>fromdftd3.aseimportDFTD3>>>atoms=molecule('H2O')>>>atoms.calc=SumCalculator([DFTD3(method="PBE",damping="d3bj"),NWChem(xc="PBE")])For convenienceDFTD3allows to combine itself with another calculator by using theadd_calculatormethod which returns a SumCalculator:>>>fromase.buildimportmolecule>>>fromase.calculators.emtimportEMT>>>fromdftd4.aseimportDFTD3>>>atoms=molecule("C60")>>>atoms.calc=DFTD3(method="pbe",damping="d3bj").add_calculator(EMT())>>>atoms.get_potential_energy()7.513593999944228>>>[calc.get_potential_energy()forcalcinatoms.calc.calcs][-4.850025823367818,12.363619823312046]The individual contributions are available by iterating over the list of calculators incalc.calcs.
Note thatDFTD3will always place itself as first calculator in the list.PySCF supportIntegration withPySCFis possible by using thedftd3.pyscfmodule.
The module provides aDFTD3Dispersionclass to construct a PySCF compatible calculator for evaluating the dispersion energy and gradients.>>>frompyscfimportgto>>>importdftd3.pyscfasdisp>>>mol=gto.M(...atom="""
...          C   -0.189833176  -0.645396435   0.069807761
...          C    1.121636324  -0.354065576   0.439096514
...          C    1.486520953   0.962572632   0.712107225
...          C    0.549329390   1.989209324   0.617868956
...          C   -0.757627135   1.681862630   0.246856908
...          C   -1.138190460   0.370551816  -0.028582325
...          Br  -2.038462778   3.070459841   0.115165429
...          H    1.852935245  -1.146434699   0.514119204
...          H    0.825048723   3.012176989   0.829385472
...          H    2.502259769   1.196433556   1.000317333
...          H   -2.157140187   0.151608161  -0.313181471
...          H   -0.480820487  -1.664983631  -0.142918416
...          S   -4.157443472   5.729584377  -0.878761129
...          H   -4.823791426   4.796089466  -1.563433338
...          C   -2.828338520   5.970593053  -2.091189515
...          H   -2.167577293   6.722356639  -1.668621815
...          H   -2.264954814   5.054835899  -2.240198499
...          H   -3.218524904   6.337447714  -3.035087058
...          """...)>>>d3=disp.DFTD3Dispersion(mol,xc="PW6B95",version="d3bj")>>>d3.kernel()[0]array(-0.01009386)>>>d3.version="d3zero"# Change to zero damping>>>d3.kernel()[0]array(-0.00574098)>>>d3.atm=True# Activate three-body dispersion>>>d3.kernel()[0]array(-0.00574289)To make use of the dispersion correction together with other calculators, theenergymethod allows to apply a dispersion correction to an existing calculator.>>>frompyscfimportgto,scf>>>importdftd3.pyscfasdisp>>>mol=gto.M(...atom="""
...          O  -1.65542061  -0.12330038   0.00000000
...          O   1.24621244   0.10268870   0.00000000
...          H  -0.70409026   0.03193167   0.00000000
...          H  -2.03867273   0.75372294   0.00000000
...          H   1.57598558  -0.38252146  -0.75856129
...          H   1.57598558  -0.38252146   0.75856129
...          """...)>>>grad=disp.energy(scf.RHF(mol)).run().nuc_grad_method()convergedSCFenergy=-149.947191000075>>>g=grad.kernel()---------------DFTD3gradients---------------xyz0O0.01718869760.05066062460.00000000001O0.0383596853-0.04590575490.00000000002H-0.0313133974-0.0125865676-0.00000000003H0.0066705789-0.03805018720.00000000004H-0.01545278220.02294094250.02151419915H-0.01545278220.0229409425-0.0215141991----------------------------------------------InstallingThis project is packaged for thecondapackage manager and available on theconda-forgechannel.
To install thecondapackage manager we recommend theminiforgeinstaller.
If theconda-forgechannel is not yet enabled, add it to your channels withcondaconfig--addchannelsconda-forgeOnce theconda-forgechannel has been enabled, this project can be installed with:condainstalldftd3-pythonNow you are ready to usedftd3, check if you can import it with>>>importdftd3>>>fromdftd3.libdftd3importget_api_version>>>get_api_version()'0.7.0'Building the extension moduleTo perform an out-of-tree build some version ofs-dftd3has to be available on your system and preferably findable bypkg-config.
Try to find as-dftd3installation you build against first withpkg-config--modversions-dftd3Adjust thePKG_CONFIG_PATHenvironment variable to include the correct directories to find the installation if necessary.Using pipThis project support installation with pip as an easy way to build the Python API.
Precompiled Python wheels for Linux are available onpypiand can be installed withpipinstalldftd3Other platforms need to build from source, the following dependencies are required to do soC compiler to build the C-API and compile the extension module (the compiler name should be exported in theCCenvironment variable)Python 3.6 or newerThe following Python packages are required additionallycffinumpypkgconfig(setup only)Make sure to have your C compiler set to theCCenvironment variableexportCC=gccInstall the project with pippipinstall.If you already have as-dftd3installation,e.g.from conda-forge, you can build the Python extension module directly without cloning this repositorypipinstall"https://github.com/dftd3/simple-dftd3/archive/refs/heads/main.zip#egg=dftd3-python&subdirectory=python"Using mesonThis directory contains a separate meson build file to allow the out-of-tree build of the CFFI extension module.
The out-of-tree build requiresC compiler to build the C-API and compile the extension modulemesonversion 0.53 or newera build-system backend,i.e.ninjaversion 1.7 or newerPython 3.6 or newer with theCFFIpackage installedSetup a build withmesonsetup_build-Dpython_version=$(whichpython3)The Python version can be used to select a different Python version, it defaults to'python3'.
Python 2 is not supported with this project, the Python version key is meant to select between several local Python 3 versions.Compile the project withmesoncompile-C_buildThe extension module is now available in_build/dftd3/_libdftd3.*.so.
You can install as usual withmesonconfigure_build--prefix=/path/to/installmesoninstall-C_build