AO to MO transformation#
Modules: ao2mo
Overview#
The ao2mo
module exposes important functionality for transforming 2-electron integrals, i.e. the 4-index transformation from atomic orbitals (AOs) to molecular orbitals (MOs).
The most important functions are kernel()
, load
, restore()
.
The function kernel()
takes in a Mole
object or the AO integrals stored in a numpy.ndarray
and a set of MO coefficients.
If erifile
is specified, the integrals will be stored in a HDF5 file with the given name, otherwise the integrals are returned as a numpy array.
from pyscf import gto, scf, ao2mo
import tempfile
mol = gto.Mole()
mol.build(
atom = 'H 0 0 0; F 0 0 1.1', # in Angstrom
basis = 'ccpvdz',
symmetry = True,
)
mf = scf.RHF(mol)
mf.kernel()
orb = mf.mo_coeff
# get the two-electron integrals as a numpy array
eri = ao2mo.kernel(mol, orb)
ftmp = tempfile.NamedTemporaryFile()
# saves the two-electron integrals in the file ftmp.name
ao2mo.kernel(mol, orb, ftmp.name)
The kernel()
function can also be invoked as the ao2mo()
method of the Mole
object
mol.ao2mo(orb)
The class load
allows users to load two-electron integrals from a hdf5 file.
ftmp = tempfile.NamedTmpFile()
ao2mo.kernel(mol, orb, ftmp)
with ao2mo.load(ftmp) as eri:
print(eri.shape)
The function restore()
restores a set of integrals to the desired permutation symmetry.
import numpy
with ao2mo.load(ftmp) as eri:
eri1 = ao2mo.restore(1, numpy.asarray(eri), orb.shape[1])
eri4 = ao2mo.restore('4', numpy.asarray(eri), orb.shape[1)
eri8 = ao2mo.restore('s8', numpy.asarray(eri), orb.shape[1])
print(eri1.shape)
print(eri4.shape)
print(eri8.shape)
The kernel function#
- kernel(eri_or_mol, mo_coeffs, erifile=None, dataname='eri_mo', intor='int2e', *args, **kwargs)#
- Parameters:
eri_or_mol – This is either a four-dimensional array that stores the AO integrals explicitly or a
Mole
object. If it is an array, everything will be kept in memory, and an incore algorithm will be used. If it is aMole
object, AO integrals will be computed on the fly, and the outcore algorithm will be used.mo_coeffs – This can be either a single set of MO coefficients in a numpy array, or a list of four sets of MO coefficients. Each of the four sets of MO coefficients correspond to an index in (ij|kl). If only one is provided, the four indices will correspond to the same MO coefficients.
erifile (str or
h5py.Group
object orh5py.File
object) – This is the name of the HDF5 file to store the integrals in. If theeri_or_mol
argument is a numpy array,kernel()
will call the incore algorithm to perform the transformation, and this argument will not be used. If specified, the integrals will be stored in the HDF5 file or the related group. If not specified, PySCF will use an anonymous temp file and return anumpy.ndarray
in the end.dataname (str) –
dataname
labels the integrals stored in the erifile. The integrals can be reused by assigning different datanames. If the erifile already contains the given dataname, the old integrals will be overwritten.intor (str) – the name of the integral you want to evaluate. More details can be found in
gto
.comp (int) – the component of the integral to be evaluated. It is closely related to
intor
, more details can also be found ingto
.aosym (int or str) – It specifies to what level will the
ao2mo()
utilize symmetry in ao integrals. Supported symmetry labels are the same as those inrestore()
. For more details see Transform integrals between symmetries section below. Default aosym is ‘s4’.compact (bool) – When this is
True
, the returned MO integrals have (up to 4-fold) permutation symmetry. When this isFalse
, the function will abandon any permutation symmetry, and return the “plain” MO integrals without any permutation symmetry.
Load the integrals#
Since integrals are stored in a HDF5 file when the outcore algorithm is used,
Pyscf provides the load
to help users access the integrals stored in the HDF5 file.
It takes a flexible ranges of objects including a str
which is the name of the HDF5 file, a h5py.File
object, a h5py.Group
object and a numpy array.
The dataname can also be taken as a second argument.
In this way, it helps users access integrals stored in memory and in a file on the same footing.
The load
class should only be used within a with
statement.
eri = ao2mo.kernel(mol, orb)
print(type(eri))
with ao2mo.load(erifile) as eri:
print(eri.shape)
ao2mo.kernel(mol, orb, erifile = 'hf.h5', dataname = 'test')
# load 2e integrals by filename and dataname
with ao2mo.load('hf.h5', 'test') as eri:
print(eri.shape)
import numpy
erirand = numpy.random.random((5,5,5,5))
# load 2e integrals from numpy array
with ao2mo.load(erirand) as eri:
print(eri.shape)
Transform integrals between symmetries#
The function restore()
can transform 2e integrals or any 4-index quantity (e.g. 2rdm) between different permutation symmetries.
It takes a symmetry label, a numpy.ndarray
as the 4-index quantity and the dimension norb
of this quantity (the four indices
must have the same dimension).
The symmetry label specifies the output symmetry the user desires, while
the symmetry of the input array is determined by its shape.
The relation between different symmetries and shape is described below.
“Plain” MO integrals or ‘s1’ symmetry have a shape of (norb, norb, norb, norb).
If a pair of indices have permutation symmetry, then only the triangular index is used and the shape is (npair, npair) with npair = norb*(norb+1)/2.
Thus integrals with ‘s2ij’ and ‘s2kl’ symmetries have a shape of (npair, norb, norb) or (norb, norb, npair) respectively.
If the integrals have ‘s4’ symmetry, then there is permutation symmetry between both ij indices and kl indices and the shape will be (npair, npair).
If the integrals have ‘s8’ symmetry, then permutation symmetry also exists between the ij pair and kl pair.
This will yield a one-dimensional array with length npair*(npair+1)/2.
restore()
determines the symmetry of the input array based on the above rules, and the shape of the output is also determined in this way.
If the input does not correspond to any of the above shapes, PySCF will throw an error.
Listed are the symmetry labels that can be used, whichcan be either be a str
or int
.
‘s8’, ‘8’, 8 |
8-fold symmetry |
‘s4, ‘4’, 4 |
4-fold symmetry |
‘s2kl’, ‘2kl’ |
2-fold symmetry between ij indices. |
‘s2ij’, ‘2ij’ |
2-fold symmetry between kl indices. |
‘s1’, ‘1’, 1 |
1-fold symmetry or no symmetry. |
Note#
The examples in this document can be found as a single python script in examples/ao2mo/02-ao2mo_doc.py, more examples can also be found at examples/ao2mo/02-ao2mo_doc.py directory.