10.23. qmmm — QM/MM interface

To run HF with background charges, one could follow the following example:

import numpy
from pyscf import gto, scf, qmmm
mol = gto.M(atom='''
C       1.1879  -0.3829 0.0000
C       0.0000  0.5526  0.0000
O       -1.1867 -0.2472 0.0000
H       -1.9237 0.3850  0.0000
H       2.0985  0.2306  0.0000
H       1.1184  -1.0093 0.8869
H       1.1184  -1.0093 -0.8869
H       -0.0227 1.1812  0.8852
H       -0.0227 1.1812  -0.8852
            ''',
            basis='3-21g',
            verbose=4)
numpy.random.seed(1)
coords = numpy.random.random((5,3)) * 10
charges = (numpy.arange(5) + 1.) * -.1
mf = scf.UHF(mol)
mf = qmmm.mm_charge(mf, coords, charges)
mf.run()

10.23.1. Examples

Relevant examples examples/qmmm/00-hf.py examples/qmmm/01-dft.py examples/qmmm/02-mcscf.py examples/qmmm/03-ccsd.py examples/qmmm/04-cisd.py examples/qmmm/05-mp2.py examples/qmmm/06-tddft.py examples/qmmm/10-x2c.py examples/qmmm/11-newton.py examples/qmmm/11-soscf.py examples/qmmm/20-grad.py examples/qmmm/21-geom_opt.py examples/qmmm/30-force_on_mm_particles.py

QM/MM helper functions that modify the QM methods.

pyscf.qmmm.itrf.add_mm_charges(scf_method, atoms_or_coords, charges, unit=None)[source]

Embedding the one-electron (non-relativistic) potential generated by MM point charges into QM Hamiltonian.

The total energy includes the regular QM energy, the interaction between the nuclei in QM region and the MM charges, and the static Coulomb interaction between the electron density and the MM charges. It does not include the static Coulomb interactions of the MM point charges, the MM energy, the vdw interaction or other bonding/non-bonding effects between QM region and MM particles.

Args:

scf_method : a HF or DFT object

atoms_or_coords2D array, shape (N,3)

MM particle coordinates

charges1D array

MM particle charges

Kwargs:
unitstr

Bohr, AU, Ang (case insensitive). Default is the same to mol.unit

Returns:

Same method object as the input scf_method with modified 1e Hamiltonian

Note:

1. if MM charge and X2C correction are used together, function mm_charge needs to be applied after X2C decoration (.x2c method), eg mf = mm_charge(scf.RHF(mol).x2c()), [(0.5,0.6,0.8)], [-0.5]). 2. Once mm_charge function is applied on the SCF object, it affects all the post-HF calculations eg MP2, CCSD, MCSCF etc

Examples:

>>> mol = gto.M(atom='H 0 0 0; F 0 0 1', basis='ccpvdz', verbose=0)
>>> mf = mm_charge(dft.RKS(mol), [(0.5,0.6,0.8)], [-0.3])
>>> mf.kernel()
-101.940495711284
pyscf.qmmm.itrf.add_mm_charges_grad(scf_grad, atoms_or_coords, charges, unit=None)[source]

Apply the MM charges in the QM gradients’ method. It affects both the electronic and nuclear parts of the QM fragment.

Args:
scf_grada HF or DFT gradient object (grad.HF or grad.RKS etc)

Once the add_mm_charges_grad was applied, it affects all post-HF calculations eg MP2, CCSD, MCSCF etc

coords2D array, shape (N,3)

MM particle coordinates

charges1D array

MM particle charges

Kwargs:
unitstr

Bohr, AU, Ang (case insensitive). Default is the same to mol.unit

Returns:

Same gradeints method object as the input scf_grad method

Examples:

>>> from pyscf import gto, scf, grad
>>> mol = gto.M(atom='H 0 0 0; F 0 0 1', basis='ccpvdz', verbose=0)
>>> mf = mm_charge(scf.RHF(mol), [(0.5,0.6,0.8)], [-0.3])
>>> mf.kernel()
-101.940495711284
>>> hfg = mm_charge_grad(grad.hf.RHF(mf), coords, charges)
>>> hfg.kernel()
[[-0.25912357 -0.29235976 -0.38245077]
 [-1.70497052 -1.89423883  1.2794798 ]]
pyscf.qmmm.itrf.mm_charge(scf_method, atoms_or_coords, charges, unit=None)

Embedding the one-electron (non-relativistic) potential generated by MM point charges into QM Hamiltonian.

The total energy includes the regular QM energy, the interaction between the nuclei in QM region and the MM charges, and the static Coulomb interaction between the electron density and the MM charges. It does not include the static Coulomb interactions of the MM point charges, the MM energy, the vdw interaction or other bonding/non-bonding effects between QM region and MM particles.

Args:

scf_method : a HF or DFT object

atoms_or_coords2D array, shape (N,3)

MM particle coordinates

charges1D array

MM particle charges

Kwargs:
unitstr

Bohr, AU, Ang (case insensitive). Default is the same to mol.unit

Returns:

Same method object as the input scf_method with modified 1e Hamiltonian

Note:

1. if MM charge and X2C correction are used together, function mm_charge needs to be applied after X2C decoration (.x2c method), eg mf = mm_charge(scf.RHF(mol).x2c()), [(0.5,0.6,0.8)], [-0.5]). 2. Once mm_charge function is applied on the SCF object, it affects all the post-HF calculations eg MP2, CCSD, MCSCF etc

Examples:

>>> mol = gto.M(atom='H 0 0 0; F 0 0 1', basis='ccpvdz', verbose=0)
>>> mf = mm_charge(dft.RKS(mol), [(0.5,0.6,0.8)], [-0.3])
>>> mf.kernel()
-101.940495711284
pyscf.qmmm.itrf.mm_charge_grad(scf_grad, atoms_or_coords, charges, unit=None)

Apply the MM charges in the QM gradients’ method. It affects both the electronic and nuclear parts of the QM fragment.

Args:
scf_grada HF or DFT gradient object (grad.HF or grad.RKS etc)

Once the add_mm_charges_grad was applied, it affects all post-HF calculations eg MP2, CCSD, MCSCF etc

coords2D array, shape (N,3)

MM particle coordinates

charges1D array

MM particle charges

Kwargs:
unitstr

Bohr, AU, Ang (case insensitive). Default is the same to mol.unit

Returns:

Same gradeints method object as the input scf_grad method

Examples:

>>> from pyscf import gto, scf, grad
>>> mol = gto.M(atom='H 0 0 0; F 0 0 1', basis='ccpvdz', verbose=0)
>>> mf = mm_charge(scf.RHF(mol), [(0.5,0.6,0.8)], [-0.3])
>>> mf.kernel()
-101.940495711284
>>> hfg = mm_charge_grad(grad.hf.RHF(mf), coords, charges)
>>> hfg.kernel()
[[-0.25912357 -0.29235976 -0.38245077]
 [-1.70497052 -1.89423883  1.2794798 ]]
pyscf.qmmm.itrf.qmmm_for_scf(scf_method, mm_mol)[source]

Add the potential of MM particles to SCF (HF and DFT) method or CASCI method then generate the corresponding QM/MM method for the QM system.

Args:

mm_mol : MM Mole object

pyscf.qmmm.itrf.qmmm_grad_for_scf(scf_grad)[source]

Add the potential of MM particles to SCF (HF and DFT) object and then generate the corresponding QM/MM gradients method for the QM system.

The qmmm module implements a generic interface for use with MM programs.