Py SCF 1.4 Manual

User Manual:

Open the PDF directly: View PDF .
Page Count: 275 [warning: Documents this large are best viewed by clicking the View PDF Link!]

Contents
Python Module Index
Index
det_ovlp

PySCF Documentation

Release 1.4.0

Qiming Sun <osirpt.sun@gmail.com>

Oct 12, 2017

CONTENTS

1 Contents 3

1.1 An overview of PySCF .......................................... 3

1.2 Tutorial .................................................. 5

1.3 Advanced topics ............................................. 18

1.4 Installation ................................................ 27

1.5 gto — Molecular structure and GTO basis ................................ 29

1.6 lib ..................................................... 74

1.7 scf .................................................... 80

1.8 ao2mo .................................................. 128

1.9 mcscf ................................................... 137

1.10 fci ..................................................... 150

1.11 symm ................................................... 156

1.12 df — density ﬁtting ............................................ 158

1.13 dft ..................................................... 159

1.14 tools ................................................... 173

1.15 Benchmark ................................................ 176

1.16 General .................................................. 176

1.17 Version history .............................................. 178

Python Module Index 179

Index 181

PySCF Documentation, Release 1.4.0

PySCF is a collection of electronic structure programs powered by Python. The package aims to provide a simple,

light-weight, and efﬁcient platform for quantum chemistry calculations and code development. The program is devel-

oped with the following principles:

• Easy to install, to use, to extend and to be embedded;

• Minimal requirements on libraries (no Boost or MPI) and computing resources (perhaps sacriﬁcing efﬁciency

to reduce I/O);

• 90/10 Python/C (only computational hot spots are written in C);

• 90/10 functional/OOP (unless performance critical, functions are pure).

CONTENTS 1

PySCF Documentation, Release 1.4.0

2 CONTENTS

CHAPTER

ONE

CONTENTS

1.1 An overview of PySCF

Python-based simulations of chemistry framework (PYSCF) is a general-purpose electronic structure platform de-

signed from the ground up to emphasize code simplicity, so as to facilitate new method development and enable

ﬂexible computational workﬂows. The package provides a wide range of tools to support simulations of ﬁnite-size

systems, extended systems with periodic boundary conditions, low-dimensional periodic systems, and custom Hamil-

tonians, using mean-ﬁeld and post-mean-ﬁeld methods with standard Gaussian basis functions. To ensure ease of

extensibility, PYSCF uses the Python language to implement almost all of its features, while computationally critical

paths are implemented with heavily optimized C routines. Using this combined Python/C implementation, the package

is as efﬁcient as the best existing C or Fortran- based quantum chemistry programs.

1.1.1 Features

• Hartree-Fock (up to ~5000 basis)

–Non-relativistic restricted open-shell, unrestricted HF

–Scalar relativistic HF

–2-component relativistic HF

–4-component relativistic Dirac-Hartree-Fock

–Density ﬁtting HF

–Second order SCF

–General JK contraction function

–DIIS, EDIIS, ADIIS and second order solver

–SCF wavefunction stability analysis

–Generalized Hartree-Fock (GHF)

• DFT (up to ~5000 basis)

–Non-relativistic restricted, restricted open-shell, unrestricted Kohn-Sham

–Scalar relativistic DFT

–Density ﬁtting DFT

–General XC functional evaluator (for Libxc or XcFun)

–General AO evaluator

• TDDFT

PySCF Documentation, Release 1.4.0

–TDHF (and density-ﬁtting TDHF)

–TDDFT (and density-ﬁtting TDDFT)

–TDHF gradients

–TDDFT gradients

• General CASCI/CASSCF solver (up to ~3000 basis)

–State-average CASCI/CASSCF

–State-speciﬁc CASCI/CASSCF for excited states

–Multiple roots CASCI

–Support DMRG as plugin CI solver to do DMRG-CASSCF

–Support FCIQMC as plugin CI solver to do FCIQMC-CASSCF

–UHF-based UCASSCF

–Density-ﬁtting CASSCF

–DMET-CAS and AVAS active space constructor

• MP2 (up to ~200 occupied, ~2000 virtual orbitals)

–Canonical MP2

–Density-ﬁtting MP2

–MP2-F12

• CCSD (up to ~100 occupied, ~1500 virtual orbitals)

–canonical RCCSD, UCCSD

–canonical RCCSD, UCCSD lambda solver

–RCCSD and UCCSD 1-particle and 2-particle density matrices

–CCSD gradients

–EOM-IP/EA/EE-CCSD

–RCC2

–Density-ﬁtting CCSD

• CCSD(T)

–Canonical RCCSD(T) and UCCSD(T)

–Canonical RCCSD(T) 1- and 2-particle density matrices

–Canonical RCCSD(T) gradients

• CI

–RCISD and UCISD

–RCISD and UCISD 1, 2-particle density matrices

–Selected-CI

–Selected-CI 1, 2-particle density matrices

• Full CI

–Direct-CI solver for spin degenerated Hamiltonian

4 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

–Direct-CI solver for spin non-degenerated Hamiltonian

–1, and 2-particle transition density matrices

–1, 2, 3, and 4-particle density matrices

–CI wavefunction overlap

• Gradients

–Non-relativistic RHF gradients

–4-component DHF gradients

–Non-relativistic DFT gradients

–Non-relativistic CCSD gradients

–Non-relativistic TDHF and TDDFT gradients

• Hessian

–Non-relativistic RHF hessian

–Non-relativistic RKS hessian

• Properties

–Non-relativistic RHF, UHF, RKS, UKS NMR shielding

–4-component DHF NMR shielding

–Non-relativistic RHF, UHF spin-spin coupling

–4-component DHF spin-spin coupling

–Non-relativistic UHF, UKS hyperﬁne coupling

–4-component DHF hyperﬁne coupling

–Non-relativistic UHF, UKS g-tensor

–4-component DHF g-tensor

–Non-relativistic UHF zero-ﬁeld splitting

–Molecular electrostatic potential (MEP)

• MRPT

–Strongly contracted NEVPT2

–DMRG-NEVPT2

–IC-MPS-PT2

• Extended systems with periodic boundary condition

–gamma point RHF, UHF, RKS, UKS

–gamma point TDDFT, MP2, CCSD

–PBC RHF, UHF, RKS, UKS with k-point sampling

–PBC RCCSD and UCCSD with k-point sampling

–PBC k-point EOM-IP/EA-CCSD

–PBC AO integrals

–PBC MO integral transformation

1.1. An overview of PySCF 5

PySCF Documentation, Release 1.4.0

–PBC density ﬁtting

–Smearing for mean-ﬁeld calculation

–Low-dimensional (0D, 1D, 2D) PBC systems

–TDHF and TDDFT with k-point sampling

• AO integrals

–Interface to call Libcint library

–1-electron real-GTO and spinor-GTO integrals

–2-electron real-GTO and spinor-GTO integrals

–3-center 1-electron real-GTO and spinor-GTO integrals

–3-center 2-electron real-GTO and spinor-GTO integrals

–General basis value evaluator (for numeric integration)

–PBC 1-electron integrals

–PBC 2-electron integrals

–F12 integrals

• MO integrals

–2-electron integral transformation for any integrals provided by Libcint library

–Support for 4-index integral transformation with 4 different orbitals

–PBC 2-electron MO integrals

• Localizer

–Boys

–Edmiston

–Meta-Lowdin

–Natural atomic orbital (NAO)

–Intrinsic atomic orbital (IAO)

–Pipek-Mezey

• Geometry optimization

–RHF, RKS, RCCSD with pyberny geometry optimizer

• D2h symmetry and linear molecule symmetry

–Molecule symmetry detection

–Symmetry adapted basis

–Label orbital symmetry on the ﬂy

–Hot update symmetry information

–Function to symmetrize given orbital space

• Tools

–fcidump

–molden

6 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

–cubegen

–Molpro XML reader

• Interface to integral package Libcint

• Interface to DMRG CheMPS2

• Interface to DMRG Block

• Interface to FCIQMC NECI

• Interface to XC functional library XCFun

• Interface to XC functional library Libxc

PySCF Python-based simulations of chemistry framework

How to use

There are two ways to access the documentation: the docstrings come with the code, and an online program reference,

available from http://www.sunqm.net/pyscf/index.html

We recommend the enhanced Python interpreter IPython and the web-based Python IDE Ipython notebook to try out

the package:

>>> from pyscf import gto, scf

>>> mol =gto.M(atom='H000;H001.2', basis='cc-pvdz')

>>> mol.apply(scf.RHF).run()

converged SCF energy = -1.06111199785749

-1.06111199786

Pure function and Class

Class are designed to hold only the ﬁnal results and the control parameters such as maximum number of iterations,

convergence threshold, etc. The intermediate status are not saved in the class. If the .kernel() function is ﬁnished

without any errors, the solution will be saved in the class (see documentation).

Most useful functions are implemented at module level, and can be accessed in both class and module, e.g.

scf.hf.get_jk(mol,dm) and SCF(mol).get_jk(mol,dm) have the same functionality. As a result, most

functions and class are pure, i.e. no status are saved, and the argument are not changed inplace. Exceptions (destruc-

tive functions and methods) are sufﬁxed with underscore in the function name, eg mcscf.state_average_(mc)

changes the attribute of its argument mc

Stream functions

For most methods, there are three stream functions to pipe computing stream:

1.set function to update object attributes, eg mf = scf.RHF(mol).set(conv_tol=1e-5) is identical to

proceed in two steps mf = scf.RHF(mol); mf.conv_tol=1e-5

2.run function to execute the kernel function (the function arguments are passed to kernel function). If keyword

arguments is given, it will ﬁrst call .set function to update object attributes then execute the kernel function. Eg mf

= scf.RHF(mol).run(dm_init,conv_tol=1e-5) is identical to three steps mf = scf.RHF(mol);

mf.conv_tol=1e-5; mf.kernel(dm_init)

1.1. An overview of PySCF 7

PySCF Documentation, Release 1.4.0

3.apply function to apply the given function/class to the current object (func-

tion arguments and keyword arguments are passed to the given function). Eg

mol.apply(scf.RHF).run().apply(mcscf.CASSCF,6,4,frozen=4) is identical to mf =

scf.RHF(mol); mf.kernel(); mcscf.CASSCF(mf,6,4,frozen=4)

1.2 Tutorial

1.2.1 Quick setup

The prerequisites of PySCF include cmake,numpy,scipy, and h5py. On the Ubuntu host, you can quickly install

them:

$ sudo apt-get install python-h5py python-scipy cmake

Then download the latest version of pyscf and build C extensions in pyscf/lib:

$ git clone https://github.com/sunqm/pyscf

$ cd pyscf/lib

$ mkdir build

$ cd build

$ cmake ..

$ make

Finally, update the Python runtime path PYTHONPATH (assuming pyscf is put in /home/abc, replace it with your own

path):

$ echo 'export PYTHONPATH=/home/abc:$PYTHONPATH' >> ~/.bashrc

$ source ~/.bashrc

To ensure the installation is successed, start a Python shell, and type:

>>> import pyscf

If you got errors like:

ImportError: No module named pyscf

It’s very possible that you put /home/abc/pyscf in PYTHONPATH. You need to remove the /pyscf in that string

and try import pyscf in the python shell again.

Note: The quick setup does not provide the best performance. Please see Installation for the installation with

optimized libraries.

1.2.2 A simple example

Here is an example to run HF calculation for hydrogen molecule:

>>> from pyscf import gto, scf

>>> mol =gto.M(atom='H000;H001.2', basis='ccpvdz')

>>> mf =scf.RHF(mol)

>>> mf.kernel()

8 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

converged SCF energy = -1.06111199785749

-1.06111199786

1.2.3 Initializing a molecule

There are three ways to deﬁne and initialize a molecule. The ﬁrst is to use the keyword arguments of Mole.build()

to initialize a molecule:

>>> from pyscf import gto

>>> mol =gto.Mole()

>>> mol.build(

... atom ='''O 0 0 0; H 0 1 0; H 0 0 1''',

... basis ='sto-3g')

The second way is to assign the geometry, basis etc. to Mole object, then call build() function to initialize the

molecule:

>>> mol =gto.Mole()

>>> mol.atom ='''O 0 0 0; H 0 1 0; H 0 0 1'''

>>> mol.basis ='sto-3g'

>>> mol.build()

The third way is to use the shortcut function Mole.M(). This function pass all arguments to Mole.build():

>>> from pyscf import gto

>>> mol =gto.M(

... atom ='''O 0 0 0; H 0 1 0; H 0 0 1''',

... basis ='sto-3g')

Either way, you may have noticed two keywords atom and basis. They are used to hold the molecular geometry

and basis sets.

Geometry

Molecular geometry can be input in Cartesian format:

>>> mol =gto.Mole()

>>> mol.atom ='''O 0, 0, 0

... H 0 1 0; H 0, 0, 1'''

The atoms in the molecule are represented by an element symbol plus three numbers for coordinates. Different atoms

should be separated by ;or line break. In the same atom, ,can be used to separate different items. Z-matrix input

format is also supported by the input parser:

>>> mol =gto.Mole()

>>> mol.atom ='''O

... H, 1, 1.2; H 1 1.2 2 105'''

Similarly, different atoms need to be separated by ;or line break. If you need to label an atom to distinguish it from the

rest, you can preﬁx or sufﬁx number or special characters 1234567890~!@#$%^&*()_+.?:<>[]{}| (except ,

and ;) to an atomic symbol. With this decoration, you can specify different basis sets, or masses, or nuclear models

for different atoms:

1.2. Tutorial 9

PySCF Documentation, Release 1.4.0

>>> mol =gto.Mole()

>>> mol.atom ='''8 0 0 0; h:1 0 1 0; H@2 0 0'''

>>> mol.basis ={'O':'sto-3g','H':'cc-pvdz','H@2':'6-31G'}

>>> mol.build()

>>> print(mol._atom)

[['O', [0.0, 0.0, 0.0]], ['H:1', [0.0, 1.0, 0.0]], ['H@2', [0.0, 0.0]]]

Basis set

The simplest way is to assign a string of basis name to mol.basis:

mol.basis ='sto3g'

This input will apply the speciﬁed basis set to all atoms. The basis name in the string is case insensitive. White space,

dash and underscore in the basis name are all ignored. If different basis sets are required for different elements, a

python dict can be assigned to the basis attribute:

mol.basis ={'O':'sto3g','H':'6-31g'}

You can ﬁnd more examples in section input_basis and in the ﬁle examples/gto/04-input_basis.py.

Other parameters

You can assign more informations to the molecular object:

mol.symmetry =1

mol.charge =1

mol.spin =1

mol.nucmod ={'O1':1}

mol.mass ={'O1':18,'H':2}

Note: Mole.spin is 2S, the alpha and beta electron number difference.

Mole also deﬁnes some global parameters. You can control the print level globally with verbose:

mol.verbose =4

The print level can be 0 (quite, no output) to 9 (very noise). Mostly, the useful messages are printed at level 4 (info),

and 5 (debug). You can also specify the place where to write the output messages:

mol.output ='path/to/my_log.txt'

Without assigning this variable, messages will be dumped to sys.stdout. You can control the maximum memory

usage globally:

mol.max_memory =1000 # MB

The default size can be deﬁned with shell environment variable PYSCF_MAX_MEMORY

output and max_memory can be assigned from command line:

$ python example.py -o /path/to/my_log.txt -m 1000

10 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

1.2.4 Initializing a crystal

Initialization a crystal unit cell is very similar to the initialization molecular object. Here, pyscf.pbc.gto.Cell

class should be used instead of the pyscf.gto.Mole class:

>>> from pyscf.pbc import gto

>>> cell =gto.Cell()

>>> cell.atom ='''H 0 0 0; H 1 1 1'''

>>> cell.basis ='gth-dzvp'

>>> cell.pseudo ='gth-pade'

>>> cell.a=numpy.eye(3)*2

>>> cell.build()

The crystal initialization requires an extra parameter cell.a which represents the lattice vectors. In the above

example, we speciﬁed cell.pseudo for the pseudo-potential of the system which is an optional parameter. The

input format of basis set is the same to that of Mole object. The other attributes of Mole object such as verbose,

max_memory,spin can also be used in the crystal systems. More details of the crystal Cell object and the relevant

input parameters are documented in pbc.gto — Crystal cell structure.

1D and 2D systems

PySCF PBC module supports the low-dimensional PBC systems. You can initialize the attribute cell.dimension

to specify the dimension of the system:

>>> from pyscf.pbc import gto

>>> cell =gto.Cell()

>>> cell.atom ='''H 0 0 0; H 1 1 0'''

>>> cell.basis ='sto3g'

>>> cell.dimension =2

>>> cell.a=numpy.eye(3)*2

>>> cell.build()

When cell.dimension is speciﬁed, a vacuum of inﬁnite size will be applied on certain dimension(s). More

speciﬁcally, when cell.dimension is 2, the z-direction will be treated as inﬁnite large and the xy-plane constitutes

the periodic surface. When cell.dimension is 1, y and z axes are treated as vacuum thus wire is placed on the

x axis. When cell.dimension is 0, all three directions are vacuum. The PBC system is actually the same to the

molecular system.

1.2.5 HF, MP2, MCSCF

Hartree-Fock

Now we are ready to study electronic structure theory with pyscf. Let’s take oxygen molecule as the ﬁrst example:

>>> from pyscf import gto

>>> mol =gto.Mole()

>>> mol.verbose =5

>>> mol.output ='o2.log'

>>> mol.atom ='O000;O001.2'

>>> mol.basis ='ccpvdz'

>>> mol.build()

Apply non-relativistic Hartree-Fock:

1.2. Tutorial 11

PySCF Documentation, Release 1.4.0

>>> from pyscf import scf

>>> m=scf.RHF(mol)

>>> print('E(HF) = %g'%m.kernel())

E(HF) = -149.544214749

The ground state of oxygen molecule should be triplet. So we change the spin to 2(2 more alpha electrons than beta

electrons):

>>> o2_tri =mol.copy()

>>> o2_tri.spin =2

>>> o2_tri.build(0,0)# two "0"s to prevent dumping input and parsing command line

>>> rhf3 =scf.RHF(o2_tri)

>>> print(rhf3.kernel())

-149.609461122

Run UHF:

>>> uhf3 =scf.UHF(o2_tri)

>>> print(uhf3.scf())

-149.628992314

>>> print('S^2 = %f, 2S+1 = %f'%uhf3.spin_square())

S^2 = 2.032647, 2S+1 = 3.021686

where we called mf.scf(), which is an alias name of mf.kernel. You can impose symmetry:

>>> o2_sym =mol.copy()

>>> o2_sym.spin =2

>>> o2_sym.symmetry =1

>>> o2_sym.build(0,0)

>>> rhf3_sym =scf.RHF(o2_sym)

>>> print(rhf3_sym.kernel())

-149.609461122

Here we rebuild the molecule because we need to initialize the point group symmetry information, symmetry adapted

orbitals. We can check the occupancy for each irreducible representations:

>>> import numpy

>>> from pyscf import symm

>>> def myocc(mf):

... mol =mf.mol

... irrep_id =mol.irrep_id

... so =mol.symm_orb

... orbsym =symm.label_orb_symm(mol, irrep_id, so, mf.mo_coeff)

... doccsym =numpy.array(orbsym)[mf.mo_occ==2]

... soccsym =numpy.array(orbsym)[mf.mo_occ==1]

... for ir,irname in enumerate(mol.irrep_name):

... print('%s, double-occ = %d, single-occ = %d'%

... (irname, sum(doccsym==ir), sum(soccsym==ir)))

>>> myocc(rhf3_sym)

Ag, double-occ = 3, single-occ = 0

B1g, double-occ = 0, single-occ = 0

B2g, double-occ = 0, single-occ = 1

B3g, double-occ = 0, single-occ = 1

Au, double-occ = 0, single-occ = 0

B1u, double-occ = 2, single-occ = 0

B2u, double-occ = 1, single-occ = 0

B3u, double-occ = 1, single-occ = 0

12 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

To label the irreducible representation of given orbitals, symm.label_orb_symm() needs the information of

the point group symmetry which are initialized in mol object, including the id of irreducible representations

Mole.irrep_id and the symmetry adapted basis Mole.symm_orb. For each irrep_id,Mole.irrep_name

gives the associated irrep symbol (A1, B1 ...). In the SCF calculation, you can control the symmetry of the wave func-

tion by assigning the number of alpha electrons and beta electrons (alpha,beta) for some irreps:

>>> rhf3_sym.irrep_nelec ={'B2g': (1,1), 'B3g': (1,1), 'B2u': (1,0), 'B3u': (1,0)}

>>> rhf3_sym.kernel()

>>> print(rhf3_sym.kernel())

-148.983117701

>>> rhf3_sym.get_irrep_nelec()

{'Ag' : (3, 3), 'B1g': (0, 0), 'B2g': (1, 1), 'B3g': (1, 1), 'Au' : (0, 0), 'B1u':

˓→(1, 0), 'B2u': (0, 1), 'B3u': (1, 0)}

More informations of the calculation can be found in the output ﬁle o2.log.

MP2 and MO integral transformation

Next, we compute the correlation energy with mp.mp2:

>>> from pyscf import mp

>>> mp2 =mp.MP2(m)

>>> print('E(MP2) = %.9g'%mp2.kernel()[0])

E(MP2) = -0.379359288

This is the correlation energy of singlet ground state. For the triplet state, we can write a function to compute the

correlation energy

𝐸𝑐𝑜𝑟𝑟 =1

4

𝑖𝑗𝑎𝑏

⟨𝑖𝑗||𝑎𝑏⟩⟨𝑎𝑏||𝑖𝑗⟩

𝜖𝑖+𝜖𝑗−𝜖𝑎−𝜖𝑏

def myump2(mf):

import numpy

from pyscf import ao2mo

# As UHF objects, mo_energy, mo_occ, mo_coeff are two-item lists

# (the first item for alpha spin, the second for beta spin).

mo_energy =mf.mo_energy

mo_occ =mf.mo_occ

mo_coeff =mf.mo_coeff

o=numpy.hstack((mo_coeff[0][:,mo_occ[0]>0] ,mo_coeff[1][:,mo_occ[1]>0]))

v=numpy.hstack((mo_coeff[0][:,mo_occ[0]==0],mo_coeff[1][:,mo_occ[1]==0]))

eo =numpy.hstack((mo_energy[0][mo_occ[0]>0] ,mo_energy[1][mo_occ[1]>0]))

ev =numpy.hstack((mo_energy[0][mo_occ[0]==0],mo_energy[1][mo_occ[1]==0]))

no =o.shape[1]

nv =v.shape[1]

noa =sum(mo_occ[0]>0)

nva =sum(mo_occ[0]==0)

eri =ao2mo.general(mf.mol, (o,v,o,v)).reshape(no,nv,no,nv)

eri[:noa,nva:] =eri[noa:,:nva] =eri[:,:,:noa,nva:] =eri[:,:,noa:,:nva] =0

g=eri -eri.transpose(0,3,2,1)

eov =eo.reshape(-1,1)-ev.reshape(-1)

de =1/(eov.reshape(-1,1)+eov.reshape(-1)).reshape(g.shape)

emp2 = .25 *numpy.einsum('iajb,iajb,iajb->', g, g, de)

return emp2

1.2. Tutorial 13

PySCF Documentation, Release 1.4.0

>>> print('E(UMP2) = %.9g'%myump2(uhf3))

-0.346926068

In this example, we concatenate 𝛼and 𝛽orbitals to mimic the spin-orbitals. After integral transformation, we zeroed

out the integrals of different spin. Here, the ao2mo module provides the general 2-electron MO integral transforma-

tion. Using this module, you are able to do arbitrary integral transformation for arbitrary integrals. For example, the

following code gives the (ov|vv) type integrals:

>>> from pyscf import ao2mo

>>> import h5py

>>> mocc =m.mo_coeff[:,m.mo_occ>0]

>>> mvir =m.mo_coeff[:,m.mo_occ==0]

>>> ao2mo.general(mol, (mocc,mvir,mvir,mvir), 'tmp.h5', compact=False)

>>> feri =h5py.File('tmp.h5')

>>> ovvv =numpy.array(feri['eri_mo'])

>>> print(ovvv.shape)

(160, 400)

We pass compact=False to ao2mo.general() to prevent the function using the permutation symmetry between

the virtual-virtual pair of |vv). So the shape of ovvv corresponds to 8 occupied orbitals by 20 virtual orbitals for

electron 1 (ov| and 20 by 20 for electron 2 |vv). In the following example, we transformed the analytical gradients

of 2-electron integrals

⟨(𝜕

𝜕𝑅 𝜙𝑖)𝜙𝑘|𝜙𝑗𝜙𝑙⟩=𝜕𝜙𝑖(𝑟1)

𝜕𝑅 𝜙𝑗(𝑟1)𝜙𝑘(𝑟2)𝜙𝑙(𝑟2)

|𝑟1−𝑟2|𝑑𝑟1𝑑𝑟2

>>> nocc =mol.nelectron // 2

>>> co =mf.mo_coeff[:,:nocc]

>>> cv =mf.mo_coeff[:,nocc:]

>>> nvir =cv.shape[1]

>>> eri =ao2mo.general(mol, (co,cv,co,cv), intor='int2e_ip1_sph', comp=3)

>>> eri =eri.reshape(3, nocc, nvir, nocc, nvir)

>>> print(eri.shape)

(3, 8, 20, 8, 20)

CASCI and CASSCF

The two classes mcscf.CASCI and mcscf.CASSCF provided by mcscf have the same initialization interface:

>>> from pyscf import mcscf

>>> mc =mcscf.CASCI(m, 4,6)

>>> print('E(CASCI) = %.9g'%mc.casci()[0])

E(CASCI) = -149.601051

>>> mc =mcscf.CASSCF(m, 4,6)

>>> print('E(CASSCF) = %.9g'%mc.kernel()[0])

E(CASSCF) = -149.613191

In this example, the CAS space is (6e, 4o): the third argument for CASCI/CASSCF is the size of CAS space; the

fourth argument is the number of electrons. By default, the CAS solver determines the alpha-electron number and

beta-electron number based on the attribute Mole.spin. In the above example, the number of alpha electrons is

equal to the number of beta electrons, since the mol object is initialized with spin=0. The spin multiplicity of the

CASSCF/CASCI solver can be changed by the fourth argument:

14 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

>>> mc =mcscf.CASSCF(m, 4, (4,2))

>>> print('E(CASSCF) = %.9g'%mc.kernel()[0])

E(CASSCF) = -149.609461

>>> print('S^2 = %.7f, 2S+1 = %.7f'%mcscf.spin_square(mc))

S^2 = 2.0000000, 2S+1 = 3.0000000

The two integers in the tuple represent the number of alpha and beta electrons. Although it is a triplet state, the solution

might not be correct since the CASSCF is based on the incorrect singlet HF ground state. Starting from the ROHF

ground state, we have:

>>> mc =mcscf.CASSCF(rhf3, 4,6)

>>> print('E(CASSCF) = %.9g'%mc.kernel()[0])

E(CASSCF) = -149.646746

The energy is lower than the RHF initial guess. .. We can also use the UHF ground .. state to start a CASSCF

calculation:: .. .. >>> mc = mcscf.CASSCF(uhf3, 4, 6) .. >>> print(‘E(CASSCF) = %.9g’ % mc.kernel()[0]) ..

E(CASSCF) = -149.661324 .. >>> print(‘S^2 = %.7f, 2S+1 = %.7f’ % mcscf.spin_square(mc)) .. S^2 = 3.9713105,

2S+1 = 4.1091656 .. .. Woo, the total energy is even lower. But the spin is contaminated.

1.2.6 Restore an old calculation

There is no restart mechanism available in PySCF package. Calculations can be “restarted” by the proper initial guess.

For SCF, the initial guess can be prepared in many ways. One is to read the chkpoint ﬁle which is generated in the

previous or other calculations:

>>> from pyscf import scf

>>> mf =scf.RHF(mol)

>>> mf.chkfile ='/path/to/chkfile'

>>> mf.init_guess ='chkfile'

>>> mf.kernel()

/path/to/chkfile can be found in the output in the calculation (if mol.verbose >= 4, the ﬁlename of the

chkﬁle will be dumped in the output). By setting chkfile and init_guess, the SCF module can read the

molecular orbitals from the given chkfile and rotate them to representation of the required basis. The example

examples/scf/15-initial_guess.py records other methods to generate SCF initial guess.

Initial guess can be fed to the calculation directly. For example, we can read the initial guess form a chkﬁle and achieve

the same effects as the on in the previous example:

>>> from pyscf import scf

>>> mf =scf.RHF(mol)

>>> dm =scf.hf.from_chk(mol, '/path/to/chkfile')

>>> mf.kernel(dm)

scf.hf.from_chk() reads the chkpoint ﬁle and generates the corresponding density matrix represented in the

required basis.

Initial guess chkfile is not limited to the calculation based on the same molecular and same basis set. One can

ﬁrst do a cheap SCF (with small basis sets) or a model SCF (dropping a few atoms, or charged system), then use

scf.hf.from_chk() to project the results to the target basis sets.

To restart a CASSCF calculation, you need prepare either CASSCF orbitals or CI coefﬁcients (not that useful unless

doing a DMRG-CASSCF calculation) or both. For example:

#!/usr/bin/env python

1.2. Tutorial 15

PySCF Documentation, Release 1.4.0

# Author: Qiming Sun <osirpt.sun@gmail.com>

import tempfile

from pyscf import gto, scf, mcscf

from pyscf import lib

'''

Restart CASSCF from previous calculation.

There is no "restart" keyword for CASSCF solver. The CASSCF solver is

completely controlled by initial guess. So we can mimic the restart feature

by providing proper initial guess from previous calculation.

We need assign the .chkfile a string to indicate the file where to save the

CASSCF intermediate results. Then we can "restart" the calculation from the

intermediate results.

'''

tmpchk =tempfile.NamedTemporaryFile()

mol =gto.Mole()

mol.atom ='C000;C001.2'

mol.basis ='ccpvdz'

mol.build()

mf =scf.RHF(mol)

mf.kernel()

mc =mcscf.CASSCF(mf, 6,6)

mc.chkfile =tmpchk.name

mc.max_cycle_macro =1

mc.kernel()

#######################################################################

# Assuming the CASSCF was interrupted. Intermediate data were saved in

# tmpchk file. Here we read the chkfile to restart the previous calculation.

#######################################################################

mol =gto.Mole()

mol.atom ='C000;C001.2'

mol.basis ='ccpvdz'

mol.build()

mc =mcscf.CASSCF(scf.RHF(mol), 6,6)

mo =lib.chkfile.load(tmpchk.name, 'mcscf/mo_coeff')

mc.kernel(mo)

1.2.7 Access AO integrals

molecular integrals

PySCF uses Libcint library as the AO integral engine. It provides simple interface function getints_by_shell()

to evaluate integrals. The following example evaluates 3-center 2-electron integrals with this function:

16 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

import numpy

from pyscf import gto, scf, df

mol =gto.M(atom='O 0 0 0; h 0 -0.757 0.587; h 0 0.757 0.587', basis='cc-pvdz')

auxmol =gto.M(atom='O 0 0 0; h 0 -0.757 0.587; h 0 0.757 0.587', basis='weigend')

pmol =mol +auxmol

nao =mol.nao_nr()

naux =auxmol.nao_nr()

eri3c =numpy.empty((nao,nao,naux))

pi =0

for iin range(mol.nbas):

pj =0

for jin range(mol.nbas):

pk =0

for kin range(mol.nbas, mol.nbas+auxmol.nbas):

shls =(i, j, k)

buf =pmol.intor_by_shell('int3c2e_sph', shls)

di, dj, dk =buf.shape

eri3c[pi:pi+di,pj:pj+dj,pk:pk+dk] =buf

pk += dk

pj += dj

pi += di

Here we load the Weigend density ﬁtting basis to auxmol and append the basis to normal orbital basis which was ini-

tialized in mol. In the result pmol object, the ﬁrst mol.nbas shells are the orbital basis and the next auxmol.nbas

are auxiliary basis. The three nested loops run over all integrals for the three index integral (ij|K). Similarly, we can

compute the two center Coulomb integrals:

eri2c =numpy.empty((naux,naux))

pk =0

for kin range(mol.nbas, mol.nbas+auxmol.nbas):

pl =0

for lin range(mol.nbas, mol.nbas+auxmol.nbas):

shls =(k, l)

buf =pmol.intor_by_shell('int2c2e_sph', shls)

dk, dl =buf.shape

eri2c[pk:pk+dk,pl:pl+dl] =buf

pl += dl

pk += dk

Now we can use the two-center integrals and three-center integrals to implement the density ﬁtting Hartree-Fock code.

def get_vhf(mol, dm, *args, **kwargs):

naux =eri2c.shape[0]

nao =mol.nao_nr()

rho =numpy.einsum('ijp,ij->p', eri3c, dm)

rho =numpy.linalg.solve(eri2c, rho)

jmat =numpy.einsum('p,ijp->ij', rho, eri3c)

kpj =numpy.einsum('ijp,jk->ikp', eri3c, dm)

pik =numpy.linalg.solve(eri2c, kpj.reshape(-1,naux).T)

kmat =numpy.einsum('pik,kjp->ij', pik.reshape(naux,nao,nao), eri3c)

return jmat -kmat *.5

mf =scf.RHF(mol)

mf.verbose =0

mf.get_veff =get_vhf

print('E(DF-HF) = %.12f, ref = %.12f'%(mf.kernel(), scf.density_fit(mf).kernel()))

Your screen should output

1.2. Tutorial 17

PySCF Documentation, Release 1.4.0

E(DF-HF) = -76.025936299702, ref = -76.025936299702

Evaluating the integrals with nested loops and mol.intor_by_shell() method is inefﬁcient. It is preferred to

load integrals in bulk and this can be done with mol.intor() method:

eri2c =auxmol.intor('int2c2e_sph')

eri3c =pmol.intor('int3c2e_sph', shls_slice=(0,mol.nbas,0,mol.nbas,mol.nbas,mol.

˓→nbas+auxmol.nbas))

eri3c =eri3c.reshape(mol.nao_nr(), mol.nao_nr(), -1)

mol.intor() method can be used to evaluate one-electron integrals, two-electron integrals:

hcore =mol.intor('int1e_nuc_sph')+mol.intor('int1e_kin_sph')

overlap =mol.intor('int1e_ovlp_sph')

eri =mol.intor('int2e_sph')

There is a long list of supported AO integrals. See moleintor.

PBC AO integrals

mol.intor() can only be used to evaluate the integrals with open boundary conditions. When the periodic bound-

ary conditions of crystal systems are studied, you need to use pbc.Cell.pbc_intor() function to evaluate the

integrals of short-range operators, such as the overlap, kinetic matrix:

from pyscf.pbc import gto

cell =gto.Cell()

cell.atom ='H000;H111'

cell.a=numpy.eye(3)*2.

cell.build()

overlap =cell.pbc_intor('int1e_ovlp_sph')

By default, pbc.Cell.pbc_intor() function returns the Γ-point integrals. If k-points are speciﬁed, function

pbc.Cell.pbc_intor() can also evaluate the k-point integrals:

kpts =cell.make_kpts([2,2,2]) # 8 k-points

overlap =cell.pbc_intor('int1e_ovlp_sph', kpts=kpts)

Note: pbc.Cell.pbc_intor() can only be used to evaluate the short-range integrals. PBC density ﬁtting

method has to be used to compute the long-range operator such as nuclear attraction integrals, Coulomb integrals.

The two-electron Coulomb integrals can be evaluated with PBC density ﬁtting methods:

from pyscf.pbc import df

eri =df.DF(cell).get_eri()

See also pbc.df — PBC denisty ﬁtting for more details of the PBC density ﬁtting module.

1.2.8 Other features

Density ﬁtting

18 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

#!/usr/bin/env python

# Author: Qiming Sun <osirpt.sun@gmail.com>

from pyscf import gto

from pyscf import scf

'''

Density fitting method by decorating the scf object with scf.density_fit function.

There is no flag to control the program to do density fitting for 2-electron

integration. The way to call density fitting is to decorate the existed scf

object with scf.density_fit function.

NOTE scf.density_fit function generates a new object, which works exactly the

same way as the regular scf method. The density fitting scf object is an

independent object to the regular scf object which is to be decorated. By

doing so, density fitting can be applied anytime, anywhere in your script

without affecting the exsited scf object.

See also:

examples/df/00-with_df.py

examples/df/01-auxbasis.py

'''

mol =gto.Mole()

mol.build(

verbose =0,

atom ='''8 0 0. 0

1 0 -0.757 0.587

1 0 0.757 0.587''',

basis ='ccpvdz',

)

mf =scf.density_fit(scf.RHF(mol))

energy =mf.kernel()

print('E = %.12f, ref = -76.026744737355' %energy)

# Stream style: calling .density_fit method to return a DF-SCF object.

mf =scf.RHF(mol).density_fit()

energy =mf.kernel()

print('E = %.12f, ref = -76.026744737355' %energy)

# By default optimal auxiliary basis (if possible) or even-tempered gaussian

# functions are used fitting basis. You can assign with_df.auxbasis to change

# the change the fitting basis.

mol.spin =1

mol.charge =1

mol.build(0,0)

mf =scf.UKS(mol).density_fit()

mf.with_df.auxbasis ='cc-pvdz-jkfit'

energy =mf.kernel()

print('E = %.12f, ref = -75.390366559552' %energy)

1.2. Tutorial 19

PySCF Documentation, Release 1.4.0

Customizing Hamiltonian

#!/usr/bin/env python

# Author: Qiming Sun <osirpt.sun@gmail.com>

import numpy

from pyscf import gto, scf, ao2mo

'''

Customizing Hamiltonian for SCF module.

Three steps to define Hamiltonian for SCF:

1. Specify the number of electrons. (Note mole object must be "built" before doing

˓→this step)

2. Overwrite three attributes of scf object

.get_hcore

.get_ovlp

._eri

3. Specify initial guess (to overwrite the default atomic density initial guess)

Note you will see warning message on the screen:

overwrite keys get_ovlp get_hcore of <class 'pyscf.scf.hf.RHF'>

'''

mol =gto.M()

n=10

mol.nelectron =n

mf =scf.RHF(mol)

h1 =numpy.zeros((n,n))

for iin range(n-1):

h1[i,i+1]=h1[i+1,i] = -1.0

h1[n-1,0]=h1[0,n-1]= -1.0 # PBC

eri =numpy.zeros((n,n,n,n))

for iin range(n):

eri[i,i,i,i] =4.0

mf.get_hcore =lambda *args: h1

mf.get_ovlp =lambda *args: numpy.eye(n)

# ao2mo.restore(8, eri, n) to get 8-fold permutation symmetry of the integrals

# ._eri only supports the two-electron integrals in 4-fold or 8-fold symmetry.

mf._eri =ao2mo.restore(8, eri, n)

mf.kernel()

Symmetry in CASSCF

#!/usr/bin/env python

20 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

# Author: Qiming Sun <osirpt.sun@gmail.com>

from pyscf import gto, scf, mcscf

'''

Symmetry is not immutable

In PySCF, symmetry is not built-in data structure. Orbitals are stored in C1

symmetry. The irreps and symmetry information are generated on the fly.

We can switch on symmetry for CASSCF solver even the Hartree-Fock is not

optimized with symmetry.

'''

mol =gto.Mole()

mol.build(

atom =[['O' , (0. ,0. ,0.)],

[1, (0. ,-0.757 ,0.587)],

[1, (0. ,0.757 ,0.587)]],

basis ='cc-pvdz',

)

mf =scf.RHF(mol)

mf.kernel()

mol.build(0,0, symmetry ='C2v')

mc =mcscf.CASSCF(mf, 6,8)

mc.kernel()

1.3 Installation

We provide three ways to install PySCF package.

1.3.1 Installation with conda

If you have Anaconda environment, PySCF package can be installed with:

$ conda install -c pyscf pyscf

1.3.2 Installation with pip

You have to ﬁrst install the dependent libraries (due to the missing of build-time dependency in pip PEP 518):

$ pip install numpy scipy h5py

Then install PySCF:

$ pip install pyscf

Note: libxc library is not available in the PyPI repository. pyscf.dft module is not working unless the libxc library

was installed in the system. You can download libxc library from http://octopus-code.org/wiki/Libxc:download. You

1.3. Installation 21

PySCF Documentation, Release 1.4.0

need to add –enable-shared when compiling the libxc library. Before calling pip, the path where the libxc library is

installed needs to be added to the environment variable PYSCF_INC_DIR

1.3.3 Manual installation from github repo

You can manually install PySCF from the PySCF github repo. Manual installation requires cmake,numpy,scipy and

h5py libraries. You can download the latest PySCF version (or the development branch) from github:

$ git clone https://github.com/sunqm/pyscf

$ cd pyscf

$ git checkout dev # optional if you'd like to try out the development branch

Build the C extensions in pyscf/lib:

$ cd pyscf/lib

$ mkdir build

$ cd build

$ cmake ..

$ make

This will automatically download the analytical GTO integral library libcint and the DFT exchange correlation func-

tional libraries libxc and xcfun. Finally, to make Python able to ﬁnd the pyscf package, add the top-level pyscf

directory (not the pyscf/pyscf subdirectory) to PYTHONPATH. For example, if pyscf is installed in /opt,

PYTHONPATH should be like:

export PYTHONPATH=/opt/pyscf:$PYTHONPATH

To ensure the installation is successful, start a Python shell, and type:

>>> import pyscf

For Mac OS X/macOS, you may get an import error if your OS X/macOS version is 10.11 or later:

OSError: dlopen(xxx/pyscf/pyscf/lib/libcgto.dylib, 6): Library not loaded: libcint.3.

˓→0.dylib

Referenced from: xxx/pyscf/pyscf/lib/libcgto.dylib

Reason: unsafe use of relative rpath libcint.3.0.dylib in xxx/pyscf/pyscf/lib/libcgto.

˓→dylib with restricted binary

This is caused by the RPATH. It can be ﬁxed by running the script

pyscf/lib/_runme_to_fix_dylib_osx10.11.sh in pyscf/lib directory:

cd pyscf/lib

sh _runme_to_fix_dylib_osx10.11.sh

Note: RPATH has been built in the dynamic library. This may cause library loading error on some systems.

You can run pyscf/lib/_runme_to_remove_rpath.sh to remove the rpath code from the library head.

Another workaround is to set -DCMAKE_SKIP_RPATH=1 and -DCMAKE_MACOSX_RPATH=0 in cmake com-

mand line. When the RPATH was removed, you need to add pyscf/lib and pyscf/lib/deps/lib in

LD_LIBRARY_PATH.

A useful last step is to set the scratch directory. The default scratch directory of PySCF is controlled by environment

variable PYSCF_TMPDIR. If it’s not speciﬁed, the system wide temporary directory TMPDIR will be used as the

scratch directory.

22 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

1.3.4 Installation without network

If you have problems downloading the external libraries on your computer, you can manually build the libraries, as

shown in the following instructions. First, you need to install libcint, libxc or xcfun libraries. libcint cint3 branch and

xcfun stable-1.x branch are required by PySCF. They can be downloaded from github:

$ git clone https://github.com/sunqm/libcint.git

$ cd libcint

$ git checkout origin/cint3

$ cd .. && tar czf libcint.tar.gz libcint

$ git clone https://github.com/sunqm/xcfun.git

$ cd xcfun

$ git checkout origin/stable-1.x

$ cd .. && tar czf xcfun.tar.gz xcfun

libxc-3.* can be found in http://octopus-code.org/wiki/Main_Page or here. Assuming /opt is the place where these

libraries will be installed, these packages should be compiled with the ﬂags:

$ tar xvzf libcint.tar.gz

$ cd libcint

$ mkdir build && cd build

$ cmake -DWITH_F12=1 -DWITH_RANGE_COULOMB=1 -DWITH_COULOMB_ERF=1 \

-DCMAKE_INSTALL_PREFIX:PATH=/opt -DCMAKE_INSTALL_LIBDIR:PATH=lib ..

$ make && make install

$ tar xvzf libxc-3.0.0.tar.gz

$ cd libxc-0.0.0

$ mkdir build && cd build

$ ../configure --prefix=/opt --libdir=/opt/lib --enable-shared --disable-fortran

˓→LIBS=-lm

$ make && make install

$ tar xvzf xcfun.tar.gz

$ cd xcfun

$ mkdir build && cd build

$ cmake -DCMAKE_BUILD_TYPE=RELEASE -DBUILD_SHARED_LIBS=1 -DXC_MAX_ORDER=3 -DXCFUN_

˓→ENABLE_TESTS=0 \

-DCMAKE_INSTALL_PREFIX:PATH=/opt -DCMAKE_INSTALL_LIBDIR:PATH=lib ..

$ make && make install

Next compile PySCF:

$ cd pyscf/pyscf/lib

$ mkdir build && cd build

$ cmake -DBUILD_LIBCINT=0 -DBUILD_LIBXC=0 -DBUILD_XCFUN=0 -DCMAKE_INSTALL_PREFIX:

˓→PATH=/opt ..

$ make

Finally update the PYTHONPATH environment for Python interpreter.

1.3.5 Using optimized BLAS

The default installation does not require the user to identify external linear algebra libraries, but instead tries to ﬁnd

them automatically. This automated setup script may only ﬁnd and link to slow BLAS/LAPACK libraries. To improve

performance, users can install the package with other BLAS vendors, such as the Intel Math Kernel Library (MKL),

which can provide 10x speedup in many modules:

1.3. Installation 23

PySCF Documentation, Release 1.4.0

$ cd pyscf/lib/build

$ cmake -DBLA_VENDOR=Intel10_64lp_seq ..

$ make

If you are using Anaconda as your Python-side platform, you can link PySCF to the MKL library coming with Ana-

conda package:

$ export MKLROOT=/path/to/anaconda2

$ export LD_LIBRARY_PATH=$MKLROOT/lib:$LD_LIBRARY_PATH

$ cd pyscf/lib/build

$ cmake -DBLA_VENDOR=Intel10_64lp_seq ..

$ make

You can link to other BLAS libraries by setting BLA_VENDOR, eg BLA_VENDOR=ATLAS,

BLA_VENDOR=IBMESSL. Please refer to cmake mannual for more details of the use of FindBLAS macro.

If the cmake BLA_VENDOR cannot ﬁnd the right BLAS library as you expected, you can assign the libraries to the

variable BLAS_LIBRARIES in lib/CMakeLists.txt:

set(BLAS_LIBRARIES "${BLAS_LIBRARIES};/path/to/mkl/lib/intel64/libmkl_intel_lp64.so")

set(BLAS_LIBRARIES "${BLAS_LIBRARIES};/path/to/mkl/lib/intel64/libmkl_sequential.so")

set(BLAS_LIBRARIES "${BLAS_LIBRARIES};/path/to/mkl/lib/intel64/libmkl_core.so")

set(BLAS_LIBRARIES "${BLAS_LIBRARIES};/path/to/mkl/lib/intel64/libmkl_avx.so")

1.3.6 Using optimized integral library

The default integral library used by PySCF is libcint (https://github.com/sunqm/libcint). To ensure the compatibility

on various high performance computer systems, PySCF does not use the fast integral library by default. For X86-64

platforms, libcint library has an efﬁcient implementation Qcint https://github.com/sunqm/qcint.git which is heavily

optimized against SSE3 instructions. To replace the default libcint library with qcint library, edit the URL of the

integral library in lib/CMakeLists.txt ﬁle:

ExternalProject_Add(libcint

GIT_REPOSITORY

https://github.com/sunqm/qcint.git

...

1.3.7 Plugins

nao

pyscf/nao module includes the basic functions of numerical atomic orbitals (NAO) and the (nao based) TDDFT

methods. This module was contributed by Marc Barbry and Peter Koval. You can enable this module with a cmake

ﬂag:

$ cmake -DENABLE_NAO=1 ..

More information of the compilcation can be found in pyscf/lib/nao/README.md.

DMRG solver

Density matrix renormalization group (DMRG) implementations Block (http://chemists.princeton.edu/chan/software/

block-code-for-dmrg) and CheMPS2 (http://sebwouters.github.io/CheMPS2/index.html) are efﬁcient DMRG solvers

24 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

for ab initio quantum chemistry problem. Installing Block requires C++11 compiler. If C++11 is not supported

by your compiler, you can register and download the precompiled Block binary from http://chemists.princeton.

edu/chan/software/block-code-for-dmrg. Before using the Block or CheMPS2, you need create a conﬁg ﬁle fu-

ture/dmrgscf/settings.py (as shown by settings.py.example) to store the path where the DMRG solver was installed.

FCIQMC

NECI (https://github.com/ghb24/NECI_STABLE) is FCIQMC code developed by George Booth and Ali Alavi.

PySCF has an interface to call FCIQMC solver NECI. To use NECI, you need create a conﬁg ﬁle fu-

ture/fciqmc/settings.py to store the path where NECI was installed.

Libxc

By default, building PySCF will automatically download and install Libxc 2.2.2.pyscf.dft.libxc module pro-

vided a general interface to access Libxc functionals.

Xcfun

By default, building PySCF will automatically download and install latest xcfun code from https://github.com/dftlibs/

xcfun.pyscf.dft.xcfun module provided a general interface to access Libxc functionals.

XianCI

XianCI is a spin-adapted MRCI program. “Bingbing Suo” <bsuo@nwu.edu.cn> is the main developer of XianCI

program.

1.4 gto — Molecular structure and GTO basis

This module provides the functions to parse the command line options, the molecular geometry and format the basic

functions for libcint integral library. In mole, a basic class Mole is deﬁned to hold the global parameters, which will

be used throughout the package.

1.4.1 Input

Geometry

There are multiple ways to input molecular geometry. The internal format of Mole.atom is a python list:

atom =[[atom1, (x, y, z)],

[atom2, (x, y, z)],

...

[atomN, (x, y, z)]]

You can input the geometry in this format. You can use Python script to construct the geometry:

>>> mol =gto.Mole()

>>> mol.atom =[['O',(0,0,0)], ['H',(0,1,0)], ['H',(0,0,1)]]

>>> mol.atom.extend([['H', (i, i, i)] for iin range(1,5)])

1.4. gto — Molecular structure and GTO basis 25

PySCF Documentation, Release 1.4.0

Besides Python list, tuple and numpy.ndarray are all supported by the internal format:

>>> mol.atom =(('O',numpy.zeros(3)), ['H',0,1,0], ['H',[0,0,1]])

Also, atom can be a string of Cartesian format or Z-matrix format:

>>> mol =gto.Mole()

>>> mol.atom ='''

>>> O000

>>> H010

>>> H001;

>>> '''

There are a few requirements for the string format. The string input takes ;or \n to partition atoms. White space and

,are used to divide items for each atom. Blank lines or lines started with #will be ignored:

>>> mol =gto.M(

... mol.atom ='''

... #O000

... H010

...

... H001;

... ''')

>>> mol.natm

The geometry string is case-insensitive. It also supports to input the nuclear charges of elements:

>>> mol =gto.Mole()

>>> mol.atom =[[8,(0,0,0)], ['h',(0,1,0)], ['H',(0,0,1)]]

If you need to label an atom to distinguish it from the rest, you can preﬁx or sufﬁx number or special characters

1234567890~!@#$%^&*()_+.?:<>[]{}| (except ,and ;) to an atomic symbol. With this decoration, you

can specify different basis sets, or masses, or nuclear models for different atoms:

>>> mol =gto.Mole()

>>> mol.atom ='''8 0 0 0; h:1 0 1 0; H@2 0 0'''

>>> mol.basis ={'O':'sto-3g','H':'cc-pvdz','H@2':'6-31G'}

>>> mol.build()

>>> print(mol.atom)

[['O', [0.0, 0.0, 0.0]], ['H:1', [0.0, 1.0, 0.0]], ['H@2', [0.0, 0.0]]]

No matter which format or symbols were used in the input, Mole.build() will convert Mole.atom to the internal

format:

>>> mol.atom ='''

O 0, 0, 0 ; 1 0.0 1 0

H@2,0 0 1

'''

>>> mol.build()

>>> print(mol.atom)

[['O', [0.0, 0.0, 0.0]], ['H', [0.0, 1.0, 0.0]], ['H@2', [0.0, 0.0, 1.0]]]

Input Basis

There are various ways to input basis sets. Besides the input of universal basis string and basis dict:

26 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

mol.basis ='sto3g'

mol.basis ={'O':'sto3g','H':'6-31g'}

basis can be input with helper functions. Function basis.parse() can parse a basis string of NWChem format

(https://bse.pnl.gov/bse/portal):

mol.basis ={'O': gto.basis.parse('''

C S

71.6168370 0.15432897

13.0450960 0.53532814

3.5305122 0.44463454

C SP

2.9412494 -0.09996723 0.15591627

0.6834831 0.39951283 0.60768372

0.2222899 0.70011547 0.39195739

''')}

Functions basis.load() can be load arbitrary basis from the database, even the basis which does not match the

element.

mol.basis = {‘H’: gto.basis.load(‘sto3g’, ‘C’)}

Both basis.parse() and basis.load() return the basis set in the internal format (See the ba-

sis_internal_format).

Basis parser supports “Ghost” atom:

mol.basis ={'GHOST': gto.basis.load('cc-pvdz','O'), 'H':'sto3g'}

More examples of inputing ghost atoms can be found in examples/gto/03-ghost_atom.py

Like the requirements of geometry input, you can use atomic symbol (case-insensitive) or the atomic nuclear charge,

as the keyword of the basis dict. Preﬁx and sufﬁx of numbers and special characters are allowed. If the decorated

atomic symbol is appeared in atom but not basis, the basis parser will remove all decorations then seek the pure

atomic symbol in basis dict. In the following example, 6-31G basis will be assigned to the second H atom, but

STO-3G will be used for the third atom:

mol.atom ='8000;h1010;H2001'

mol.basis ={'O':'sto-3g','H':'sto3g','H1':'6-31G'}

Command line

Some of the input variables can be passed from command line:

$ python example.py -o /path/to/my_log.txt -m 1000

This command line speciﬁes the output ﬁle and the maximum of memory for the calculation. By default, command

line has the highest priority, which means our settings in the script will be overwritten by the command line arguments.

To make the input parser ignore the command line arguments, you can call the Mole.build() with:

mol.build(0,0)

The ﬁrst 0 prevent build() dumping the input ﬁle. The second 0 prevent build() parsing command line.

1.4. gto — Molecular structure and GTO basis 27

PySCF Documentation, Release 1.4.0

1.4.2 Program reference

mole

Mole class handles three layers: input, internal format, libcint arguments. The relationship of the three layers are:

.atom (input)<=> ._atom (for python) <=> ._atm (for libcint)

.basis (input)<=> ._basis (for python) <=> ._bas (for libcint)

input layer does not talk to libcint directly. Data are held in python internal fomrat layer. Most of methods de-

ﬁned in this class only operates on the internal format. Exceptions are make_env, make_atm_env, make_bas_env,

set_common_orig_(),set_rinv_orig_() which are used to manipulate the libcint arguments.

pyscf.gto.mole.M(**kwargs)

This is a shortcut to build up Mole object.

Args: Same to Mole.build()

Examples:

>>> from pyscf import gto

>>> mol =gto.M(atom='H000;F001', basis='6-31g')

class pyscf.gto.mole.Mole(**kwargs)

Basic class to hold molecular structure and global options

Attributes:

verbose [int] Print level

output [str or None] Output ﬁle, default is None which dumps msg to sys.stdout

max_memory [int, ﬂoat] Allowed memory in MB

charge [int] Charge of molecule. It affects the electron numbers

spin [int] 2S, num. alpha electrons - num. beta electrons

symmetry [bool or str] Whether to use symmetry. When this variable is set to True, the molecule will be

rotated and the highest rotation axis will be placed z-axis. If a string is given as the name of point

group, the given point group symmetry will be used. Note that the input molecular coordinates will

not be changed in this case.

symmetry_subgroup [str] subgroup

atom [list or str] To deﬁne molecluar structure. The internal format is

atom = [[atom1, (x, y, z)],

[atom2, (x, y, z)],

...

[atomN, (x, y, z)]]

unit [str] Angstrom or Bohr

basis [dict or str] To deﬁne basis set.

nucmod [dict or str] Nuclear model. Set it to 0, None or False for point nuclear model. Any other values

will enable Gaussian nuclear model. Default is point nuclear model.

28 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

cart [boolean] Using Cartesian GTO basis and integrals (6d,10f,15g)

** Following attributes are generated by Mole.build() **

stdout [ﬁle object] Default is sys.stdout if Mole.output is not set

groupname [str] One of D2h, C2h, C2v, D2, Cs, Ci, C2, C1

nelectron [int] sum of nuclear charges - Mole.charge

symm_orb [a list of numpy.ndarray] Symmetry adapted basis. Each element is a set of symm-adapted

orbitals for one irreducible representation. The list index does not correspond to the id of irreducible

representation.

irrep_id [a list of int] Each element is one irreducible representation id associated with the basis stored in

symm_orb. One irrep id stands for one irreducible representation symbol. The irrep symbol and the

relevant id are deﬁned in symm.param.IRREP_ID_TABLE

irrep_name [a list of str] Each element is one irreducible representation symbol associated with the basis

stored in symm_orb. The irrep symbols are deﬁned in symm.param.IRREP_ID_TABLE

_built [bool] To label whether Mole.build() has been called. It ensures some functions being initial-

ized once.

_basis [dict] like Mole.basis, the internal format which is returned from the parser

format_basis()

_keys [a set of str] Store the keys appeared in the module. It is used to check misinput attributes

** Following attributes are arguments used by libcint library **

_atm : [[charge,ptr-of-coord,nuc-model,ptr-zeta,0,0],[...]] each element

reperesents one atom

natm : number of atoms

_bas : [[atom-id,angular-momentum,num-primitive-GTO,num-contracted-GTO,0,ptr-of-exps,ptr-of-contract-coeff,0],[...]]

each element reperesents one shell

nbas : number of shells

_env : list of ﬂoats to store the coordinates, GTO exponents, contract-coefﬁcients

Examples:

>>> mol =Mole(atom='H^2 0 0 0; H 0 0 1.1', basis='sto3g').build()

>>> print(mol.atom_symbol(0))

H^2

>>> print(mol.atom_pure_symbol(0))

>>> print(mol.nao_nr())

>>> print(mol.intor('int1e_ovlp_sph'))

[[ 0.99999999 0.43958641]

[ 0.43958641 0.99999999]]

>>> mol.charge =1

>>> mol.build()

<class 'pyscf.gto.mole.Mole'> has no attributes Charge

ao_labels(mol,fmt=True)

Labels for AO basis functions

Kwargs: fmt : str or bool if fmt is boolean, it controls whether to format the labels and the default format

is “%d%3s %s%-4s”. if fmt is string, the string will be used as the print format.

1.4. gto — Molecular structure and GTO basis 29

PySCF Documentation, Release 1.4.0

Returns: List of [(atom-id, symbol-str, nl-str, str-of-AO-notation)] or formatted strings based on the ar-

gument “fmt”

ao_loc_2c(mol)

Offset of every shell in the spinor basis function spectrum

Returns: list, each entry is the corresponding start id of spinor function

Examples:

>>> mol =gto.M(atom='O000;C001', basis='6-31g')

>>> gto.ao_loc_2c(mol)

[0, 2, 4, 6, 12, 18, 20, 22, 24, 30, 36]

ao_loc_nr(mol,cart=False)

Offset of every shell in the spherical basis function spectrum

Returns: list, each entry is the corresponding start basis function id

Examples:

>>> mol =gto.M(atom='O000;C001', basis='6-31g')

>>> gto.ao_loc_nr(mol)

[0, 1, 2, 3, 6, 9, 10, 11, 12, 15, 18]

aoslice_2c_by_atom(mol)

2-component AO offset for each atom. Return a list, each item of the list gives (start-shell-id, stop-shell-id,

start-AO-id, stop-AO-id)

aoslice_by_atom(mol,ao_loc=None)

AO offsets for each atom. Return a list, each item of the list gives (start-shell-id, stop-shell-id, start-AO-id,

stop-AO-id)

aoslice_nr_by_atom(mol,ao_loc=None)

AO offsets for each atom. Return a list, each item of the list gives (start-shell-id, stop-shell-id, start-AO-id,

stop-AO-id)

atom_charge(atm_id)

Nuclear effective charge of the given atom id Note “atom_charge /= _charge(atom_symbol)” when ECP is

enabled. Number of electrons screened by ECP can be obtained by _charge(atom_symbol)-atom_charge

Args:

atm_id [int] 0-based

Examples:

>>> mol.build(atom='H 0 0 0; Cl 0 0 1.1')

>>> mol.atom_charge(1)

atom_charges()

np.asarray([mol.atom_charge(i) for i in range(mol.natm)])

atom_coord(atm_id)

Coordinates (ndarray) of the given atom id

Args:

atm_id [int] 0-based

Examples:

30 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

>>> mol.build(atom='H 0 0 0; Cl 0 0 1.1')

>>> mol.atom_coord(1)

[ 0. 0. 2.07869874]

atom_coords()

np.asarray([mol.atom_coords(i) for i in range(mol.natm)])

atom_nelec_core(atm_id)

Number of core electrons for pseudo potential.

atom_nshells(atm_id)

Number of basis/shells of the given atom

Args:

atm_id [int] 0-based

Examples:

>>> mol.build(atom='H 0 0 0; Cl 0 0 1.1')

>>> mol.atom_nshells(1)

atom_pure_symbol(atm_id)

For the given atom id, return the standard symbol (striping special characters)

Args:

atm_id [int] 0-based

Examples:

>>> mol.build(atom='H^2 0 0 0; H 0 0 1.1')

>>> mol.atom_symbol(0)

atom_shell_ids(atm_id)

A list of the shell-ids of the given atom

Args:

atm_id [int] 0-based

Examples:

>>> mol.build(atom='H 0 0 0; Cl 0 0 1.1', basis='cc-pvdz')

>>> mol.atom_shell_ids(1)

[3, 4, 5, 6, 7]

atom_symbol(atm_id)

For the given atom id, return the input symbol (without striping special characters)

Args:

atm_id [int] 0-based

Examples:

>>> mol.build(atom='H^2 0 0 0; H 0 0 1.1')

>>> mol.atom_symbol(0)

H^2

1.4. gto — Molecular structure and GTO basis 31

PySCF Documentation, Release 1.4.0

bas_angular(bas_id)

The angular momentum associated with the given basis

Args:

bas_id [int] 0-based

Examples:

>>> mol.build(atom='H 0 0 0; Cl 0 0 1.1', basis='cc-pvdz')

>>> mol.bas_atom(7)

bas_atom(bas_id)

The atom (0-based id) that the given basis sits on

Args:

bas_id [int] 0-based

Examples:

>>> mol.build(atom='H 0 0 0; Cl 0 0 1.1', basis='cc-pvdz')

>>> mol.bas_atom(7)

bas_coord(bas_id)

Coordinates (ndarray) associated with the given basis id

Args:

bas_id [int] 0-based

Examples:

>>> mol.build(atom='H 0 0 0; Cl 0 0 1.1')

>>> mol.bas_coord(1)

[ 0. 0. 2.07869874]

bas_ctr_coeff(bas_id)

Contract coefﬁcients (ndarray) of the given shell

Args:

bas_id [int] 0-based

Examples:

>>> mol.M(atom='H 0 0 0; Cl 0 0 1.1', basis='cc-pvdz')

>>> mol.bas_ctr_coeff(0)

[[ 10.03400444]

[ 4.1188704 ]

[ 1.53971186]]

bas_exp(bas_id)

exponents (ndarray) of the given shell

Args:

bas_id [int] 0-based

Examples:

32 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

>>> mol.build(atom='H 0 0 0; Cl 0 0 1.1', basis='cc-pvdz')

>>> mol.bas_kappa(0)

[ 13.01 1.962 0.4446]

bas_kappa(bas_id)

Kappa (if l < j, -l-1, else l) of the given shell

Args:

bas_id [int] 0-based

Examples:

>>> mol.build(atom='H 0 0 0; Cl 0 0 1.1', basis='cc-pvdz')

>>> mol.bas_kappa(3)

bas_len_cart(bas_id)

The number of Cartesian function associated with given basis

bas_len_spinor(bas_id)

The number of spinor associated with given basis If kappa is 0, return 4l+2

bas_nctr(bas_id)

The number of contracted GTOs for the given shell

Args:

bas_id [int] 0-based

Examples:

>>> mol.build(atom='H 0 0 0; Cl 0 0 1.1', basis='cc-pvdz')

>>> mol.bas_atom(3)

bas_nprim(bas_id)

The number of primitive GTOs for the given shell

Args:

bas_id [int] 0-based

Examples:

>>> mol.build(atom='H 0 0 0; Cl 0 0 1.1', basis='cc-pvdz')

>>> mol.bas_atom(3)

build(dump_input=True,parse_arg=True,verbose=None,output=None,max_memory=None,

atom=None,basis=None,unit=None,nucmod=None,ecp=None,charge=None,spin=None,

symmetry=None,symmetry_subgroup=None,cart=None)

Setup moleclue and initialize some control parameters. Whenever you change the value of the attributes

of Mole, you need call this function to refresh the internal data of Mole.

Kwargs:

dump_input [bool] whether to dump the contents of input ﬁle in the output ﬁle

parse_arg [bool] whether to read the sys.argv and overwrite the relevant parameters

verbose [int] Print level. If given, overwrite Mole.verbose

1.4. gto — Molecular structure and GTO basis 33

PySCF Documentation, Release 1.4.0

output [str or None] Output ﬁle. If given, overwrite Mole.output

max_memory [int, ﬂoat] Allowd memory in MB. If given, overwrite Mole.max_memory

atom [list or str] To deﬁne molecluar structure.

basis [dict or str] To deﬁne basis set.

nucmod [dict or str] Nuclear model. If given, overwrite Mole.nucmod

charge [int] Charge of molecule. It affects the electron numbers If given, overwrite Mole.charge

spin [int] 2S, num. alpha electrons - num. beta electrons If given, overwrite Mole.spin

symmetry [bool or str] Whether to use symmetry. If given a string of point group name, the given

point group symmetry will be used.

cart2sph_coeff(normalized=’sp’)

Transformation matrix to transform the Cartesian GTOs to spherical GTOs

Kwargs:

normalized [string or boolean] How the Cartesian GTOs are normalized. Except s and p functions,

Cartesian GTOs do not have the universal normalization coefﬁcients for the different components

of the same shell. The value of this argument can be one of ‘sp’, ‘all’, None. ‘sp’ means the

Cartesian s and p basis are normalized. ‘all’ means all Cartesian functions are normalized. None

means none of the Cartesian functions are normalized.

Examples:

>>> mol =gto.M(atom='H000;F001', basis='ccpvtz')

>>> c=mol.cart2sph_coeff()

>>> s0 =mol.intor('int1e_ovlp_sph')

>>> s1 =c.T.dot(mol.intor('int1e_ovlp_cart')).dot(c)

>>> print(abs(s1-s0).sum())

>>> 4.58676826646e-15

cart_labels(fmt=False)

Labels for Cartesian GTO functions

Kwargs: fmt : str or bool if fmt is boolean, it controls whether to format the labels and the default format

is “%d%3s %s%-4s”. if fmt is string, the string will be used as the print format.

Returns: List of [(atom-id, symbol-str, nl-str, str-of-xyz-notation)] or formatted strings based on the ar-

gument “fmt”

condense_to_shell(mol,mat,compressor=<function amax>)

The given matrix is ﬁrst partitioned to blocks, based on AO shell as delimiter. Then call compressor

function to abstract each block.

dumps(mol)

Serialize Mole object to a JSON formatted str.

energy_nuc(mol,charges=None,coords=None)

Compute nuclear repulsion energy (AU) or static Coulomb energy

Returns ﬂoat

etbs(etbs)

Generate even tempered basis. See also expand_etb()

Args: etbs = [(l, n, alpha, beta), (l, n, alpha, beta),...]

Returns: Formated basis

34 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

Examples:

>>> gto.expand_etbs([(0,2,1.5,2.), (1,2,1,2.)])

[[0, [6.0, 1]], [0, [3.0, 1]], [1, [1., 1]], [1, [2., 1]]]

eval_gto(mol,eval_name,coords,comp=1,shls_slice=None,non0tab=None,ao_loc=None,

out=None)

Evaluate AO function value on the given grids,

Args: eval_name : str

Function Expression

“GTOval_sph” |AO>

“GTOval_ip_sph” nabla |AO>

“GTOval_ig_sph” (#C(0 1) g) |AO>

“GTOval_ipig_sph” (#C(0 1) nabla g) |AO>

“GTOval_cart” |AO>

“GTOval_ip_cart” nabla |AO>

“GTOval_ig_cart” (#C(0 1) g)|AO>

atm [int32 ndarray] libcint integral function argument

bas [int32 ndarray] libcint integral function argument

env [ﬂoat64 ndarray] libcint integral function argument

coords [2D array, shape (N,3)] The coordinates of the grids.

Kwargs:

shls_slice [2-element list] (shl_start, shl_end). If given, only part of AOs (shl_start <= shell_id <

shl_end) are evaluated. By default, all shells deﬁned in mol will be evaluated.

non0tab [2D bool array] mask array to indicate whether the AO values are zero. The mask array can

be obtained by calling make_mask()

out [ndarray] If provided, results are written into this array.

Returns: 2D array of shape (N,nao) Or 3D array of shape (*,N,nao) for AO values

Examples:

>>> mol =gto.M(atom='O000;H001;H010', basis='ccpvdz')

>>> coords =numpy.random.random((100,3)) # 100 random points

>>> ao_value =mol.eval_gto("GTOval_sph", coords)

>>> print(ao_value.shape)

(100, 24)

>>> ao_value =mol.eval_gto("GTOval_ig_sph", coords, comp=3)

>>> print(ao_value.shape)

(3, 100, 24)

expand_etb(l,n,alpha,beta)

Generate the exponents of even tempered basis for Mole.basis. .. math:

e=e^{-\alpha *\beta^{i-1}} for i=1.. n

Args:

l[int] Angular momentum

1.4. gto — Molecular structure and GTO basis 35

PySCF Documentation, Release 1.4.0

n[int] Number of GTOs

Returns: Formated basis

Examples:

>>> gto.expand_etb(1,3,1.5,2)

[[1, [6.0, 1]], [1, [3.0, 1]], [1, [1.5, 1]]]

expand_etbs(etbs)

Generate even tempered basis. See also expand_etb()

Args: etbs = [(l, n, alpha, beta), (l, n, alpha, beta),...]

Returns: Formated basis

Examples:

>>> gto.expand_etbs([(0,2,1.5,2.), (1,2,1,2.)])

[[0, [6.0, 1]], [0, [3.0, 1]], [1, [1., 1]], [1, [2., 1]]]

format_atom(atom,origin=0,axes=None,unit=’Ang’)

Convert the input Mole.atom to the internal data format. Including, changing the nuclear charge to atom

symbol, converting the coordinates to AU, rotate and shift the molecule. If the atom is a string, it takes ”;”

and “n” for the mark to separate atoms; ”,” and arbitrary length of blank space to spearate the individual

terms for an atom. Blank line will be ignored.

Args:

atoms [list or str] the same to Mole.atom

Kwargs:

origin [ndarray] new axis origin.

axes [ndarray] (new_x, new_y, new_z), each entry is a length-3 array

unit [str or number] If unit is one of strings (B, b, Bohr, bohr, AU, au), the coordinates of the input

atoms are the atomic unit; If unit is one of strings (A, a, Angstrom, angstrom, Ang, ang), the

coordinates are in the unit of angstrom; If a number is given, the number are considered as the

Bohr value (in angstrom), which should be around 0.53

Returns: “atoms” in the internal format as _atom

Examples:

>>> gto.format_atom('9,0,0,0; h@1 0 0 1', origin=(1,1,1))

[['F', [-1.0, -1.0, -1.0]], ['H@1', [-1.0, -1.0, 0.0]]]

>>> gto.format_atom(['9,0,0,0', (1, (0,0,1))], origin=(1,1,1))

[['F', [-1.0, -1.0, -1.0]], ['H', [-1, -1, 0]]]

format_basis(basis_tab)

Convert the input Mole.basis to the internal data format.

‘‘{ atom: [(l, ((-exp, c_1, c_2, ..),

(-exp, c_1, c_2, ..))),

(l, ((-exp, c_1, c_2, ..), (-exp, c_1, c_2, ..)))], ... }‘‘

Args:

basis_tab [dict] Similar to Mole.basis, it cannot be a str

36 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

Returns: Formated basis

Examples:

>>> gto.format_basis({'H':'sto-3g','H^2':'3-21g'})

{'H': [[0,

[3.4252509099999999, 0.15432897000000001],

[0.62391373000000006, 0.53532813999999995],

[0.16885539999999999, 0.44463454000000002]]],

'H^2': [[0,

[5.4471780000000001, 0.15628500000000001],

[0.82454700000000003, 0.90469100000000002]],

[0, [0.18319199999999999, 1.0]]]}

format_ecp(ecp_tab)

Convert the input ecp (dict) to the internal data format:

{ atom: (nelec, # core electrons

((l, # l=-1 for UL, l>=0 for Ul to indicate |l><l|

(((exp_1, c_1), # for r^0

(exp_2, c_2), ...),

((exp_1, c_1), # for r^1 (exp_2, c_2), ...),

((exp_1, c_1), # for r^2 ...))))),

...}

gto_norm(l,expnt)

Normalized factor for GTO radial part 𝑔=𝑟𝑙𝑒−𝛼𝑟2

𝑔2𝑟2𝑑𝑟

=22𝑙+3(𝑙+ 1)!(2𝑎)𝑙+1.5

(2𝑙+ 2)!√𝜋

Ref: H. B. Schlegel and M. J. Frisch, Int. J. Quant. Chem., 54(1995), 83-87.

Args:

l (int): angular momentum

expnt : exponent 𝛼

Returns: normalization factor

Examples:

>>> print gto_norm(0,1)

2.5264751109842591

has_ecp()

Whether pesudo potential is used in the system.

intor(intor,comp=1,hermi=0,aosym=’s1’,out=None,shls_slice=None)

Integral generator.

Args:

1.4. gto — Molecular structure and GTO basis 37

PySCF Documentation, Release 1.4.0

intor [str] Name of the 1e or 2e AO integrals. Ref to getints() for the complete list of available

1-electron integral names

Kwargs:

comp [int] Components of the integrals, e.g. int1e_ipovlp_sph has 3 components.

hermi [int] Symmetry of the integrals

0 : no symmetry assumed (default)

1 : hermitian

2 : anti-hermitian

Returns: ndarray of 1-electron integrals, can be either 2-dim or 3-dim, depending on comp

Examples:

>>> mol.build(atom='H000;H001.1', basis='sto-3g')

>>> mol.intor('int1e_ipnuc_sph', comp=3)# <nabla i | V_nuc | j>

[[[ 0. 0. ]

[ 0. 0. ]]

[[ 0. 0. ]

[ 0. 0. ]]

[[ 0.10289944 0.48176097]

[-0.48176097 -0.10289944]]]

>>> mol.intor('int1e_nuc_spinor')

[[-1.69771092+0.j 0.00000000+0.j -0.67146312+0.j 0.00000000+0.j]

[ 0.00000000+0.j -1.69771092+0.j 0.00000000+0.j -0.67146312+0.j]

[-0.67146312+0.j 0.00000000+0.j -1.69771092+0.j 0.00000000+0.j]

[ 0.00000000+0.j -0.67146312+0.j 0.00000000+0.j -1.69771092+0.j]]

intor_asymmetric(intor,comp=1)

One-electron integral generator. The integrals are assumed to be anti-hermitian

Args:

intor [str] Name of the 1-electron integral. Ref to getints() for the complete list of available

1-electron integral names

Kwargs:

comp [int] Components of the integrals, e.g. int1e_ipovlp has 3 components.

Returns: ndarray of 1-electron integrals, can be either 2-dim or 3-dim, depending on comp

Examples:

>>> mol.build(atom='H000;H001.1', basis='sto-3g')

>>> mol.intor_asymmetric('int1e_nuc_spinor')

[[-1.69771092+0.j 0.00000000+0.j 0.67146312+0.j 0.00000000+0.j]

[ 0.00000000+0.j -1.69771092+0.j 0.00000000+0.j 0.67146312+0.j]

[-0.67146312+0.j 0.00000000+0.j -1.69771092+0.j 0.00000000+0.j]

[ 0.00000000+0.j -0.67146312+0.j 0.00000000+0.j -1.69771092+0.j]]

intor_by_shell(intor,shells,comp=1)

For given 2, 3 or 4 shells, interface for libcint to get 1e, 2e, 2-center-2e or 3-center-2e integrals

Args:

intor_name [str] See also getints() for the supported intor_name

38 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

shls [list of int] The AO shell-ids of the integrals

atm [int32 ndarray] libcint integral function argument

bas [int32 ndarray] libcint integral function argument

env [ﬂoat64 ndarray] libcint integral function argument

Kwargs:

comp [int] Components of the integrals, e.g. int1e_ipovlp has 3 components.

Returns: ndarray of 2-dim to 5-dim, depending on the integral type (1e, 2e, 3c-2e, 2c2e) and the value

of comp

Examples: The gradients of the spherical 2e integrals

>>> mol.build(atom='H000;H001.1', basis='sto-3g')

>>> gto.getints_by_shell('int2e_ip1_sph', (0,1,0,1), mol._atm, mol._bas, mol.

˓→_env, comp=3)

[[[[[-0. ]]]]

[[[[-0. ]]]]

[[[[-0.08760462]]]]]

intor_symmetric(intor,comp=1)

One-electron integral generator. The integrals are assumed to be hermitian

Args:

intor [str] Name of the 1-electron integral. Ref to getints() for the complete list of available

1-electron integral names

Kwargs:

comp [int] Components of the integrals, e.g. int1e_ipovlp_sph has 3 components.

Returns: ndarray of 1-electron integrals, can be either 2-dim or 3-dim, depending on comp

Examples:

>>> mol.build(atom='H000;H001.1', basis='sto-3g')

>>> mol.intor_symmetric('int1e_nuc_spinor')

[[-1.69771092+0.j 0.00000000+0.j -0.67146312+0.j 0.00000000+0.j]

[ 0.00000000+0.j -1.69771092+0.j 0.00000000+0.j -0.67146312+0.j]

[-0.67146312+0.j 0.00000000+0.j -1.69771092+0.j 0.00000000+0.j]

[ 0.00000000+0.j -0.67146312+0.j 0.00000000+0.j -1.69771092+0.j]]

kernel(dump_input=True,parse_arg=True,verbose=None,output=None,max_memory=None,

atom=None,basis=None,unit=None,nucmod=None,ecp=None,charge=None,spin=None,

symmetry=None,symmetry_subgroup=None,cart=None)

Setup moleclue and initialize some control parameters. Whenever you change the value of the attributes

of Mole, you need call this function to refresh the internal data of Mole.

Kwargs:

dump_input [bool] whether to dump the contents of input ﬁle in the output ﬁle

parse_arg [bool] whether to read the sys.argv and overwrite the relevant parameters

verbose [int] Print level. If given, overwrite Mole.verbose

output [str or None] Output ﬁle. If given, overwrite Mole.output

max_memory [int, ﬂoat] Allowd memory in MB. If given, overwrite Mole.max_memory

1.4. gto — Molecular structure and GTO basis 39

PySCF Documentation, Release 1.4.0

atom [list or str] To deﬁne molecluar structure.

basis [dict or str] To deﬁne basis set.

nucmod [dict or str] Nuclear model. If given, overwrite Mole.nucmod

charge [int] Charge of molecule. It affects the electron numbers If given, overwrite Mole.charge

spin [int] 2S, num. alpha electrons - num. beta electrons If given, overwrite Mole.spin

symmetry [bool or str] Whether to use symmetry. If given a string of point group name, the given

point group symmetry will be used.

loads(molstr)

Deserialize a str containing a JSON document to a Mole object.

nao_2c(mol)

Total number of contracted spinor GTOs for the given Mole object

nao_2c_range(mol,bas_id0,bas_id1)

Lower and upper boundary of contracted spinor basis functions associated with the given shell range

Args:

mol : Mole object

bas_id0 [int] start shell id, 0-based

bas_id1 [int] stop shell id, 0-based

Returns: tupel of start basis function id and the stop function id

Examples:

>>> mol =gto.M(atom='O000;C001', basis='6-31g')

>>> gto.nao_2c_range(mol, 2,4)

(4, 12)

nao_cart(mol)

Total number of contracted cartesian GTOs for the given Mole object

nao_nr(mol,cart=False)

Total number of contracted spherical GTOs for the given Mole object

nao_nr_range(mol,bas_id0,bas_id1)

Lower and upper boundary of contracted spherical basis functions associated with the given shell range

Args:

mol : Mole object

bas_id0 [int] start shell id

bas_id1 [int] stop shell id

Returns: tupel of start basis function id and the stop function id

Examples:

>>> mol =gto.M(atom='O000;C001', basis='6-31g')

>>> gto.nao_nr_range(mol, 2,4)

(2, 6)

npgto_nr(mol,cart=False)

Total number of primitive spherical GTOs for the given Mole object

40 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

offset_2c_by_atom(mol)

2-component AO offset for each atom. Return a list, each item of the list gives (start-shell-id, stop-shell-id,

start-AO-id, stop-AO-id)

offset_ao_by_atom(mol,ao_loc=None)

AO offsets for each atom. Return a list, each item of the list gives (start-shell-id, stop-shell-id, start-AO-id,

stop-AO-id)

offset_nr_by_atom(mol,ao_loc=None)

AO offsets for each atom. Return a list, each item of the list gives (start-shell-id, stop-shell-id, start-AO-id,

stop-AO-id)

pack(mol)

Pack the input args of Mole to a dict.

Note this function only pack the input arguments (not the entire Mole class). Modiﬁcations to mol._atm,

mol._bas, mol._env are not tracked. Use dumps() to serialize the entire Mole object.

search_ao_label(mol,label)

Find the index of the AO basis function based on the given ao_label

Args:

ao_label [string or a list of strings] The regular expression pattern to match the orbital labels re-

turned by mol.ao_labels()

Returns: A list of index for the AOs that matches the given ao_label RE pattern

Examples:

>>> mol =gto.M(atom='H000;Cl001', basis='ccpvtz')

>>> mol.parse_aolabel('Cl.*p')

[19 20 21 22 23 24 25 26 27 28 29 30]

>>> mol.parse_aolabel('Cl 2p')

[19 20 21]

>>> mol.parse_aolabel(['Cl.*d','Cl 4p'])

[25 26 27 31 32 33 34 35 36 37 38 39 40]

search_ao_nr(mol,atm_id,l,m,atmshell)

Search the ﬁrst basis function id (not the shell id) which matches the given atom-id, angular momentum

magnetic angular momentum, principal shell.

Args:

atm_id [int] atom id, 0-based

l[int] angular momentum

m[int] magnetic angular momentum

atmshell [int] principal quantum number

Returns: basis function id, 0-based. If not found, return None

Examples:

>>> mol =gto.M(atom='H000;Cl001', basis='sto-3g')

>>> mol.search_ao_nr(1,1,-1,3)# Cl 3px

set_common_orig(coord)

Update common origin which held in :class‘Mole‘._env. Note the unit is Bohr

Examples:

1.4. gto — Molecular structure and GTO basis 41

PySCF Documentation, Release 1.4.0

>>> mol.set_common_orig(0)

>>> mol.set_common_orig((1,0,0))

set_common_orig_(coord)

Update common origin which held in :class‘Mole‘._env. Note the unit is Bohr

Examples:

>>> mol.set_common_orig(0)

>>> mol.set_common_orig((1,0,0))

set_common_origin(coord)

Update common origin which held in :class‘Mole‘._env. Note the unit is Bohr

Examples:

>>> mol.set_common_orig(0)

>>> mol.set_common_orig((1,0,0))

set_common_origin_(coord)

Update common origin which held in :class‘Mole‘._env. Note the unit is Bohr

Examples:

>>> mol.set_common_orig(0)

>>> mol.set_common_orig((1,0,0))

set_f12_zeta(zeta)

Set zeta for YP exp(-zeta r12)/r12 or STG exp(-zeta r12) type integrals

set_geom_(atoms,unit=’Angstrom’,symmetry=None)

Replace geometry

set_nuc_mod(atm_id,zeta)

Change the nuclear charge distribution of the given atom ID. The charge distribution is deﬁned as: rho(r) =

nuc_charge * Norm * exp(-zeta * r^2). This function can only be called after .build() method is executed.

Examples:

>>> for ia in range(mol.natm):

... zeta =gto.filatov_nuc_mod(mol.atom_charge(ia))

... mol.set_nuc_mod(ia, zeta)

set_nuc_mod_(atm_id,zeta)

Change the nuclear charge distribution of the given atom ID. The charge distribution is deﬁned as: rho(r) =

nuc_charge * Norm * exp(-zeta * r^2). This function can only be called after .build() method is executed.

Examples:

>>> for ia in range(mol.natm):

... zeta =gto.filatov_nuc_mod(mol.atom_charge(ia))

... mol.set_nuc_mod(ia, zeta)

set_range_coulomb(omega)

Apply the long range part of range-separated Coulomb operator for all 2e integrals erf(omega r12) / r12

set omega to 0 to siwtch off the range-separated Coulomb

set_range_coulomb_(omega)

Apply the long range part of range-separated Coulomb operator for all 2e integrals erf(omega r12) / r12

set omega to 0 to siwtch off the range-separated Coulomb

42 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

set_rinv_orig(coord)

Update origin for operator 1

|𝑟−𝑅𝑂|.Note the unit is Bohr

Examples:

>>> mol.set_rinv_orig(0)

>>> mol.set_rinv_orig((0,1,0))

set_rinv_orig_(coord)

Update origin for operator 1

|𝑟−𝑅𝑂|.Note the unit is Bohr

Examples:

>>> mol.set_rinv_orig(0)

>>> mol.set_rinv_orig((0,1,0))

set_rinv_origin(coord)

Update origin for operator 1

|𝑟−𝑅𝑂|.Note the unit is Bohr

Examples:

>>> mol.set_rinv_orig(0)

>>> mol.set_rinv_orig((0,1,0))

set_rinv_origin_(coord)

Update origin for operator 1

|𝑟−𝑅𝑂|.Note the unit is Bohr

Examples:

>>> mol.set_rinv_orig(0)

>>> mol.set_rinv_orig((0,1,0))

set_rinv_zeta(zeta)

Assume the charge distribution on the “rinv_orig”. zeta is the parameter to control the charge distribu-

tion: rho(r) = Norm * exp(-zeta * r^2). Be careful when call this function. It affects the behavior of

int1e_rinv_* functions. Make sure to set it back to 0 after using it!

set_rinv_zeta_(zeta)

Assume the charge distribution on the “rinv_orig”. zeta is the parameter to control the charge distribu-

tion: rho(r) = Norm * exp(-zeta * r^2). Be careful when call this function. It affects the behavior of

int1e_rinv_* functions. Make sure to set it back to 0 after using it!

spheric_labels(fmt=False)

Labels for spherical GTO functions

Kwargs: fmt : str or bool if fmt is boolean, it controls whether to format the labels and the default format

is “%d%3s %s%-4s”. if fmt is string, the string will be used as the print format.

Returns: List of [(atom-id, symbol-str, nl-str, str-of-real-spherical-notation] or formatted strings based

on the argument “fmt”

Examples:

>>> mol =gto.M(atom='H000;Cl001', basis='sto-3g')

>>> gto.spherical_labels(mol)

[(0, 'H', '1s', ''), (1, 'Cl', '1s', ''), (1, 'Cl', '2s', ''), (1, 'Cl', '3s

˓→', ''), (1, 'Cl', '2p', 'x'), (1, 'Cl', '2p', 'y'), (1, 'Cl', '2p', 'z'),

˓→(1, 'Cl', '3p', 'x'), (1, 'Cl', '3p', 'y'), (1, 'Cl', '3p', 'z')]

spherical_labels(fmt=False)

Labels for spherical GTO functions

1.4. gto — Molecular structure and GTO basis 43

PySCF Documentation, Release 1.4.0

Kwargs: fmt : str or bool if fmt is boolean, it controls whether to format the labels and the default format

is “%d%3s %s%-4s”. if fmt is string, the string will be used as the print format.

Returns: List of [(atom-id, symbol-str, nl-str, str-of-real-spherical-notation] or formatted strings based

on the argument “fmt”

Examples:

>>> mol =gto.M(atom='H000;Cl001', basis='sto-3g')

>>> gto.spherical_labels(mol)

[(0, 'H', '1s', ''), (1, 'Cl', '1s', ''), (1, 'Cl', '2s', ''), (1, 'Cl', '3s

˓→', ''), (1, 'Cl', '2p', 'x'), (1, 'Cl', '2p', 'y'), (1, 'Cl', '2p', 'z'),

˓→(1, 'Cl', '3p', 'x'), (1, 'Cl', '3p', 'y'), (1, 'Cl', '3p', 'z')]

time_reversal_map(mol)

The index to map the spinor functions and its time reversal counterpart. The returned indices have postive

or negative values. For the i-th basis function, if the returned j = idx[i] < 0, it means 𝑇|𝑖⟩=−|𝑗⟩,

otherwise 𝑇|𝑖⟩=|𝑗⟩

tot_electrons(mol)

Total number of electrons for the given molecule

Returns: electron number in integer

Examples:

>>> mol =gto.M(atom='H010;C001', charge=1)

>>> mol.tot_electrons()

unpack(moldic)

Unpack a dict which is packed by pack(), to generate the input arguments for Mole object.

pyscf.gto.mole.ao_labels(mol,fmt=True)

Labels for AO basis functions

Kwargs: fmt : str or bool if fmt is boolean, it controls whether to format the labels and the default format is

“%d%3s %s%-4s”. if fmt is string, the string will be used as the print format.

Returns: List of [(atom-id, symbol-str, nl-str, str-of-AO-notation)] or formatted strings based on the argument

“fmt”

pyscf.gto.mole.ao_loc_2c(mol)

Offset of every shell in the spinor basis function spectrum

Returns: list, each entry is the corresponding start id of spinor function

Examples:

>>> mol =gto.M(atom='O000;C001', basis='6-31g')

>>> gto.ao_loc_2c(mol)

[0, 2, 4, 6, 12, 18, 20, 22, 24, 30, 36]

pyscf.gto.mole.ao_loc_nr(mol,cart=False)

Offset of every shell in the spherical basis function spectrum

Returns: list, each entry is the corresponding start basis function id

Examples:

44 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

>>> mol =gto.M(atom='O000;C001', basis='6-31g')

>>> gto.ao_loc_nr(mol)

[0, 1, 2, 3, 6, 9, 10, 11, 12, 15, 18]

pyscf.gto.mole.aoslice_by_atom(mol,ao_loc=None)

AO offsets for each atom. Return a list, each item of the list gives (start-shell-id, stop-shell-id, start-AO-id,

stop-AO-id)

pyscf.gto.mole.atom_types(atoms,basis=None)

symmetry inequivalent atoms

pyscf.gto.mole.cart2j_kappa(kappa,l=None,normalized=None)

Cartesian to spinor, indexed by kappa

Kwargs:

normalized : How the Cartesian GTOs are normalized. ‘sp’ means the s and p functions are normalized.

pyscf.gto.mole.cart2j_l(l,normalized=None)

Cartesian to spinor, indexed by l

pyscf.gto.mole.cart2sph(l)

Cartesian to real spherical transformation matrix

pyscf.gto.mole.cart2zmat(coord)

>>> c=numpy.array((

(0.000000000000, 1.889726124565, 0.000000000000),

(0.000000000000, 0.000000000000, -1.889726124565),

(1.889726124565, -1.889726124565, 0.000000000000),

(1.889726124565, 0.000000000000, 1.133835674739)))

>>> print cart2zmat(c)

1 2.67247631453057

1 4.22555607338457 2 50.7684795164077

1 2.90305235726773 2 79.3904651036893 3 6.20854462618583

pyscf.gto.mole.cart_labels(mol,fmt=True)

Labels for Cartesian GTO functions

Kwargs: fmt : str or bool if fmt is boolean, it controls whether to format the labels and the default format is

“%d%3s %s%-4s”. if fmt is string, the string will be used as the print format.

Returns: List of [(atom-id, symbol-str, nl-str, str-of-xyz-notation)] or formatted strings based on the argument

“fmt”

pyscf.gto.mole.chiral_mol(mol1,mol2=None)

Detect whether the given molelcule is chiral molecule or two molecules are chiral isomers.

pyscf.gto.mole.conc_env(atm1,bas1,env1,atm2,bas2,env2)

Concatenate two Mole’s integral parameters. This function can be used to construct the environment for cross

integrals like

⟨𝜇|𝜈⟩, 𝜇 ∈𝑚𝑜𝑙1, 𝜈 ∈𝑚𝑜𝑙2

Returns: Concatenated atm, bas, env

Examples: Compute the overlap between H2 molecule and O atom

1.4. gto — Molecular structure and GTO basis 45

PySCF Documentation, Release 1.4.0

>>> mol1 =gto.M(atom='H010;H001', basis='sto3g')

>>> mol2 =gto.M(atom='O 0 0 0', basis='sto3g')

>>> atm3, bas3, env3 =gto.conc_env(mol1._atm, mol1._bas, mol1._env,

... mol2._atm, mol2._bas, mol2._env)

>>> gto.moleintor.getints('int1e_ovlp_sph', atm3, bas3, env3, range(2),

˓→range(2,5))

[[ 0.04875181 0.44714688 0. 0.37820346 0. ]

[ 0.04875181 0.44714688 0. 0. 0.37820346]]

pyscf.gto.mole.conc_mol(mol1,mol2)

Concatenate two Mole objects.

pyscf.gto.mole.condense_to_shell(mol,mat,compressor=<function amax>)

The given matrix is ﬁrst partitioned to blocks, based on AO shell as delimiter. Then call compressor function to

abstract each block.

pyscf.gto.mole.copy(mol)

Deepcopy of the given Mole object

pyscf.gto.mole.dumps(mol)

Serialize Mole object to a JSON formatted str.

pyscf.gto.mole.dyall_nuc_mod(mass,c=137.03599967994)

Generate the nuclear charge distribution parameter zeta rho(r) = nuc_charge * Norm * exp(-zeta * r^2)

Ref. L. Visscher and K. Dyall, At. Data Nucl. Data Tables, 67, 207 (1997)

pyscf.gto.mole.energy_nuc(mol,charges=None,coords=None)

Compute nuclear repulsion energy (AU) or static Coulomb energy

Returns ﬂoat

pyscf.gto.mole.etbs(etbs)

Generate even tempered basis. See also expand_etb()

Args: etbs = [(l, n, alpha, beta), (l, n, alpha, beta),...]

Returns: Formated basis

Examples:

>>> gto.expand_etbs([(0,2,1.5,2.), (1,2,1,2.)])

[[0, [6.0, 1]], [0, [3.0, 1]], [1, [1., 1]], [1, [2., 1]]]

pyscf.gto.mole.expand_etb(l,n,alpha,beta)

Generate the exponents of even tempered basis for Mole.basis. .. math:

e=e^{-\alpha *\beta^{i-1}} for i=1.. n

Args:

l[int] Angular momentum

n[int] Number of GTOs

Returns: Formated basis

Examples:

>>> gto.expand_etb(1,3,1.5,2)

[[1, [6.0, 1]], [1, [3.0, 1]], [1, [1.5, 1]]]

46 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

pyscf.gto.mole.expand_etbs(etbs)

Generate even tempered basis. See also expand_etb()

Args: etbs = [(l, n, alpha, beta), (l, n, alpha, beta),...]

Returns: Formated basis

Examples:

>>> gto.expand_etbs([(0,2,1.5,2.), (1,2,1,2.)])

[[0, [6.0, 1]], [0, [3.0, 1]], [1, [1., 1]], [1, [2., 1]]]

pyscf.gto.mole.filatov_nuc_mod(nuc_charge,c=137.03599967994)

Generate the nuclear charge distribution parameter zeta rho(r) = nuc_charge * Norm * exp(-zeta * r^2)

Ref. M. Filatov and D. Cremer, Theor. Chem. Acc. 108, 168 (2002)

13. Filatov and D. Cremer, Chem. Phys. Lett. 351, 259 (2002)

pyscf.gto.mole.format_atom(atoms,origin=0,axes=None,unit=’Ang’)

Convert the input Mole.atom to the internal data format. Including, changing the nuclear charge to atom

symbol, converting the coordinates to AU, rotate and shift the molecule. If the atom is a string, it takes ”;” and

“n” for the mark to separate atoms; ”,” and arbitrary length of blank space to spearate the individual terms for

an atom. Blank line will be ignored.

Args:

atoms [list or str] the same to Mole.atom

Kwargs:

origin [ndarray] new axis origin.

axes [ndarray] (new_x, new_y, new_z), each entry is a length-3 array

unit [str or number] If unit is one of strings (B, b, Bohr, bohr, AU, au), the coordinates of the input atoms

are the atomic unit; If unit is one of strings (A, a, Angstrom, angstrom, Ang, ang), the coordinates

are in the unit of angstrom; If a number is given, the number are considered as the Bohr value (in

angstrom), which should be around 0.53

Returns: “atoms” in the internal format as _atom

Examples:

>>> gto.format_atom('9,0,0,0; h@1 0 0 1', origin=(1,1,1))

[['F', [-1.0, -1.0, -1.0]], ['H@1', [-1.0, -1.0, 0.0]]]

>>> gto.format_atom(['9,0,0,0', (1, (0,0,1))], origin=(1,1,1))

[['F', [-1.0, -1.0, -1.0]], ['H', [-1, -1, 0]]]

pyscf.gto.mole.format_basis(basis_tab)

Convert the input Mole.basis to the internal data format.

‘‘{ atom: [(l, ((-exp, c_1, c_2, ..),

(-exp, c_1, c_2, ..))),

(l, ((-exp, c_1, c_2, ..), (-exp, c_1, c_2, ..)))], ... }‘‘

Args:

basis_tab [dict] Similar to Mole.basis, it cannot be a str

Returns: Formated basis

1.4. gto — Molecular structure and GTO basis 47

PySCF Documentation, Release 1.4.0

Examples:

>>> gto.format_basis({'H':'sto-3g','H^2':'3-21g'})

{'H': [[0,

[3.4252509099999999, 0.15432897000000001],

[0.62391373000000006, 0.53532813999999995],

[0.16885539999999999, 0.44463454000000002]]],

'H^2': [[0,

[5.4471780000000001, 0.15628500000000001],

[0.82454700000000003, 0.90469100000000002]],

[0, [0.18319199999999999, 1.0]]]}

pyscf.gto.mole.format_ecp(ecp_tab)

Convert the input ecp (dict) to the internal data format:

{ atom: (nelec, # core electrons

((l, # l=-1 for UL, l>=0 for Ul to indicate |l><l|

(((exp_1, c_1), # for r^0

(exp_2, c_2), ...),

((exp_1, c_1), # for r^1 (exp_2, c_2), ...),

((exp_1, c_1), # for r^2 ...))))),

...}

pyscf.gto.mole.from_zmatrix(atomstr)

>>> a="""H

H 1 2.67247631453057

H 1 4.22555607338457 2 50.7684795164077

H 1 2.90305235726773 2 79.3904651036893 3 6.20854462618583"""

>>> for xin zmat2cart(a): print x

['H', array([ 0., 0., 0.])]

['H', array([ 2.67247631, 0. , 0. ])]

['H', array([ 2.67247631, 0. , 3.27310166])]

['H', array([ 0.53449526, 0.30859098, 2.83668811])]

pyscf.gto.mole.gto_norm(l,expnt)

Normalized factor for GTO radial part 𝑔=𝑟𝑙𝑒−𝛼𝑟2

𝑔2𝑟2𝑑𝑟

=22𝑙+3(𝑙+ 1)!(2𝑎)𝑙+1.5

(2𝑙+ 2)!√𝜋

Ref: H. B. Schlegel and M. J. Frisch, Int. J. Quant. Chem., 54(1995), 83-87.

Args:

l (int): angular momentum

expnt : exponent 𝛼

Returns: normalization factor

Examples:

48 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

>>> print gto_norm(0,1)

2.5264751109842591

pyscf.gto.mole.intor_cross(intor,mol1,mol2,comp=1)

1-electron integrals from two molecules like

⟨𝜇|𝑖𝑛𝑡𝑜𝑟|𝜈⟩, 𝜇 ∈𝑚𝑜𝑙1, 𝜈 ∈𝑚𝑜𝑙2

Args:

intor [str] Name of the 1-electron integral, such as int1e_ovlp_sph (spherical overlap), int1e_nuc_cart

(cartesian nuclear attraction), int1e_ipovlp_spinor (spinor overlap gradients), etc. Ref to

getints() for the full list of available 1-electron integral names

mol1, mol2: Mole objects

Kwargs:

comp [int] Components of the integrals, e.g. int1e_ipovlp_sph has 3 components

Returns: ndarray of 1-electron integrals, can be either 2-dim or 3-dim, depending on comp

Examples: Compute the overlap between H2 molecule and O atom

>>> mol1 =gto.M(atom='H010;H001', basis='sto3g')

>>> mol2 =gto.M(atom='O 0 0 0', basis='sto3g')

>>> gto.intor_cross('int1e_ovlp_sph', mol1, mol2)

[[ 0.04875181 0.44714688 0. 0.37820346 0. ]

[ 0.04875181 0.44714688 0. 0. 0.37820346]]

pyscf.gto.mole.is_same_mol(mol1,mol2,tol=1e-05,cmp_basis=True,ignore_chiral=False)

Compare the two molecules whether they have the same structure.

Kwargs:

tol [ﬂoat] In Bohr

cmp_basis [bool] Whether to compare basis functions for the two molecules

pyscf.gto.mole.len_cart(l)

The number of Cartesian function associated with given angular momentum.

pyscf.gto.mole.len_spinor(l,kappa)

The number of spinor associated with given angular momentum and kappa. If kappa is 0, return 4l+2

pyscf.gto.mole.loads(molstr)

Deserialize a str containing a JSON document to a Mole object.

pyscf.gto.mole.make_atm_env(atom,ptr=0)

Convert the internal format Mole._atom to the format required by libcint integrals

pyscf.gto.mole.make_bas_env(basis_add,atom_id=0,ptr=0)

Convert Mole.basis to the argument bas for libcint integrals

pyscf.gto.mole.make_env(atoms,basis,pre_env=[],nucmod={})

Generate the input arguments for libcint library based on internal format Mole._atom and

Mole._basis

pyscf.gto.mole.nao_2c(mol)

Total number of contracted spinor GTOs for the given Mole object

pyscf.gto.mole.nao_2c_range(mol,bas_id0,bas_id1)

Lower and upper boundary of contracted spinor basis functions associated with the given shell range

1.4. gto — Molecular structure and GTO basis 49

PySCF Documentation, Release 1.4.0

Args:

mol : Mole object

bas_id0 [int] start shell id, 0-based

bas_id1 [int] stop shell id, 0-based

Returns: tupel of start basis function id and the stop function id

Examples:

>>> mol =gto.M(atom='O000;C001', basis='6-31g')

>>> gto.nao_2c_range(mol, 2,4)

(4, 12)

pyscf.gto.mole.nao_cart(mol)

Total number of contracted cartesian GTOs for the given Mole object

pyscf.gto.mole.nao_nr(mol,cart=False)

Total number of contracted spherical GTOs for the given Mole object

pyscf.gto.mole.nao_nr_range(mol,bas_id0,bas_id1)

Lower and upper boundary of contracted spherical basis functions associated with the given shell range

Args:

mol : Mole object

bas_id0 [int] start shell id

bas_id1 [int] stop shell id

Returns: tupel of start basis function id and the stop function id

Examples:

>>> mol =gto.M(atom='O000;C001', basis='6-31g')

>>> gto.nao_nr_range(mol, 2,4)

(2, 6)

pyscf.gto.mole.npgto_nr(mol,cart=False)

Total number of primitive spherical GTOs for the given Mole object

pyscf.gto.mole.offset_2c_by_atom(mol)

2-component AO offset for each atom. Return a list, each item of the list gives (start-shell-id, stop-shell-id,

start-AO-id, stop-AO-id)

pyscf.gto.mole.offset_nr_by_atom(mol,ao_loc=None)

AO offsets for each atom. Return a list, each item of the list gives (start-shell-id, stop-shell-id, start-AO-id,

stop-AO-id)

pyscf.gto.mole.pack(mol)

Pack the input args of Mole to a dict.

Note this function only pack the input arguments (not the entire Mole class). Modiﬁcations to mol._atm,

mol._bas, mol._env are not tracked. Use dumps() to serialize the entire Mole object.

pyscf.gto.mole.same_mol(mol1,mol2,tol=1e-05,cmp_basis=True,ignore_chiral=False)

Compare the two molecules whether they have the same structure.

Kwargs:

tol [ﬂoat] In Bohr

50 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

cmp_basis [bool] Whether to compare basis functions for the two molecules

pyscf.gto.mole.search_ao_label(mol,label)

Find the index of the AO basis function based on the given ao_label

Args:

ao_label [string or a list of strings] The regular expression pattern to match the orbital labels returned by

mol.ao_labels()

Returns: A list of index for the AOs that matches the given ao_label RE pattern

Examples:

>>> mol =gto.M(atom='H000;Cl001', basis='ccpvtz')

>>> mol.parse_aolabel('Cl.*p')

[19 20 21 22 23 24 25 26 27 28 29 30]

>>> mol.parse_aolabel('Cl 2p')

[19 20 21]

>>> mol.parse_aolabel(['Cl.*d','Cl 4p'])

[25 26 27 31 32 33 34 35 36 37 38 39 40]

pyscf.gto.mole.search_ao_nr(mol,atm_id,l,m,atmshell)

Search the ﬁrst basis function id (not the shell id) which matches the given atom-id, angular momentum mag-

netic angular momentum, principal shell.

Args:

atm_id [int] atom id, 0-based

l[int] angular momentum

m[int] magnetic angular momentum

atmshell [int] principal quantum number

Returns: basis function id, 0-based. If not found, return None

Examples:

>>> mol =gto.M(atom='H000;Cl001', basis='sto-3g')

>>> mol.search_ao_nr(1,1,-1,3)# Cl 3px

pyscf.gto.mole.search_shell_id(mol,atm_id,l)

Search the ﬁrst basis/shell id (not the basis function id) which matches the given atom-id and angular momentum

Args:

atm_id [int] atom id, 0-based

l[int] angular momentum

Returns: basis id, 0-based. If not found, return None

Examples:

>>> mol =gto.M(atom='H000;Cl001', basis='sto-3g')

>>> mol.search_shell_id(1,1)# Cl p shell

>>> mol.search_shell_id(1,2)# Cl d shell

None

1.4. gto — Molecular structure and GTO basis 51

PySCF Documentation, Release 1.4.0

pyscf.gto.mole.spheric_labels(mol,fmt=True)

Labels for spherical GTO functions

Kwargs: fmt : str or bool if fmt is boolean, it controls whether to format the labels and the default format is

“%d%3s %s%-4s”. if fmt is string, the string will be used as the print format.

Returns: List of [(atom-id, symbol-str, nl-str, str-of-real-spherical-notation] or formatted strings based on the

argument “fmt”

Examples:

>>> mol =gto.M(atom='H000;Cl001', basis='sto-3g')

>>> gto.spherical_labels(mol)

[(0, 'H', '1s', ''), (1, 'Cl', '1s', ''), (1, 'Cl', '2s', ''), (1, 'Cl', '3s', '

˓→'), (1, 'Cl', '2p', 'x'), (1, 'Cl', '2p', 'y'), (1, 'Cl', '2p', 'z'), (1, 'Cl',

˓→'3p', 'x'), (1, 'Cl', '3p', 'y'), (1, 'Cl', '3p', 'z')]

pyscf.gto.mole.spherical_labels(mol,fmt=True)

Labels for spherical GTO functions

Kwargs: fmt : str or bool if fmt is boolean, it controls whether to format the labels and the default format is

“%d%3s %s%-4s”. if fmt is string, the string will be used as the print format.

Returns: List of [(atom-id, symbol-str, nl-str, str-of-real-spherical-notation] or formatted strings based on the

argument “fmt”

Examples:

>>> mol =gto.M(atom='H000;Cl001', basis='sto-3g')

>>> gto.spherical_labels(mol)

[(0, 'H', '1s', ''), (1, 'Cl', '1s', ''), (1, 'Cl', '2s', ''), (1, 'Cl', '3s', '

˓→'), (1, 'Cl', '2p', 'x'), (1, 'Cl', '2p', 'y'), (1, 'Cl', '2p', 'z'), (1, 'Cl',

˓→'3p', 'x'), (1, 'Cl', '3p', 'y'), (1, 'Cl', '3p', 'z')]

pyscf.gto.mole.time_reversal_map(mol)

The index to map the spinor functions and its time reversal counterpart. The returned indices have postive or

negative values. For the i-th basis function, if the returned j = idx[i] < 0, it means 𝑇|𝑖⟩=−|𝑗⟩, otherwise

𝑇|𝑖⟩=|𝑗⟩

pyscf.gto.mole.tot_electrons(mol)

Total number of electrons for the given molecule

Returns: electron number in integer

Examples:

>>> mol =gto.M(atom='H010;C001', charge=1)

>>> mol.tot_electrons()

pyscf.gto.mole.uncontract(_basis)

Uncontract internal format _basis

Examples:

>>> gto.uncontract_basis(gto.load('sto3g','He'))

[[0, [6.3624213899999997, 1]], [0, [1.1589229999999999, 1]], [0, [0.

˓→31364978999999998, 1]]]

pyscf.gto.mole.uncontract_basis(_basis)

Uncontract internal format _basis

52 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

Examples:

>>> gto.uncontract_basis(gto.load('sto3g','He'))

[[0, [6.3624213899999997, 1]], [0, [1.1589229999999999, 1]], [0, [0.

˓→31364978999999998, 1]]]

pyscf.gto.mole.unpack(moldic)

Unpack a dict which is packed by pack(), to generate the input arguments for Mole object.

pyscf.gto.mole.zmat(atomstr)

>>> a="""H

H 1 2.67247631453057

H 1 4.22555607338457 2 50.7684795164077

H 1 2.90305235726773 2 79.3904651036893 3 6.20854462618583"""

>>> for xin zmat2cart(a): print x

['H', array([ 0., 0., 0.])]

['H', array([ 2.67247631, 0. , 0. ])]

['H', array([ 2.67247631, 0. , 3.27310166])]

['H', array([ 0.53449526, 0.30859098, 2.83668811])]

pyscf.gto.mole.zmat2cart(atomstr)

>>> a="""H

H 1 2.67247631453057

H 1 4.22555607338457 2 50.7684795164077

H 1 2.90305235726773 2 79.3904651036893 3 6.20854462618583"""

>>> for xin zmat2cart(a): print x

['H', array([ 0., 0., 0.])]

['H', array([ 2.67247631, 0. , 0. ])]

['H', array([ 2.67247631, 0. , 3.27310166])]

['H', array([ 0.53449526, 0.30859098, 2.83668811])]

class pyscf.gto.mole.Mole(**kwargs)

Basic class to hold molecular structure and global options

Attributes:

verbose [int] Print level

output [str or None] Output ﬁle, default is None which dumps msg to sys.stdout

max_memory [int, ﬂoat] Allowed memory in MB

charge [int] Charge of molecule. It affects the electron numbers

spin [int] 2S, num. alpha electrons - num. beta electrons

symmetry [bool or str] Whether to use symmetry. When this variable is set to True, the molecule will be

rotated and the highest rotation axis will be placed z-axis. If a string is given as the name of point

group, the given point group symmetry will be used. Note that the input molecular coordinates will

not be changed in this case.

symmetry_subgroup [str] subgroup

atom [list or str] To deﬁne molecluar structure. The internal format is

atom = [[atom1, (x, y, z)],

1.4. gto — Molecular structure and GTO basis 53

PySCF Documentation, Release 1.4.0

[atom2, (x, y, z)],

...

[atomN, (x, y, z)]]

unit [str] Angstrom or Bohr

basis [dict or str] To deﬁne basis set.

nucmod [dict or str] Nuclear model. Set it to 0, None or False for point nuclear model. Any other values

will enable Gaussian nuclear model. Default is point nuclear model.

cart [boolean] Using Cartesian GTO basis and integrals (6d,10f,15g)

** Following attributes are generated by Mole.build() **

stdout [ﬁle object] Default is sys.stdout if Mole.output is not set

groupname [str] One of D2h, C2h, C2v, D2, Cs, Ci, C2, C1

nelectron [int] sum of nuclear charges - Mole.charge

symm_orb [a list of numpy.ndarray] Symmetry adapted basis. Each element is a set of symm-adapted

orbitals for one irreducible representation. The list index does not correspond to the id of irreducible

representation.

irrep_id [a list of int] Each element is one irreducible representation id associated with the basis stored

in symm_orb. One irrep id stands for one irreducible representation symbol. The irrep symbol and

the relevant id are deﬁned in symm.param.IRREP_ID_TABLE

irrep_name [a list of str] Each element is one irreducible representation symbol associated with the basis

stored in symm_orb. The irrep symbols are deﬁned in symm.param.IRREP_ID_TABLE

_built [bool] To label whether Mole.build() has been called. It ensures some functions being ini-

tialized once.

_basis [dict] like Mole.basis, the internal format which is returned from the parser

format_basis()

_keys [a set of str] Store the keys appeared in the module. It is used to check misinput attributes

** Following attributes are arguments used by libcint library **

_atm : [[charge,ptr-of-coord,nuc-model,ptr-zeta,0,0],[...]] each element

reperesents one atom

natm : number of atoms

_bas : [[atom-id,angular-momentum,num-primitive-GTO,num-contracted-GTO,0,ptr-of-exps,ptr-of-contract-coeff,0],[...]]

each element reperesents one shell

nbas : number of shells

_env : list of ﬂoats to store the coordinates, GTO exponents, contract-coefﬁcients

Examples:

>>> mol =Mole(atom='H^2 0 0 0; H 0 0 1.1', basis='sto3g').build()

>>> print(mol.atom_symbol(0))

H^2

>>> print(mol.atom_pure_symbol(0))

>>> print(mol.nao_nr())

54 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

>>> print(mol.intor('int1e_ovlp_sph'))

[[ 0.99999999 0.43958641]

[ 0.43958641 0.99999999]]

>>> mol.charge =1

>>> mol.build()

<class 'pyscf.gto.mole.Mole'> has no attributes Charge

ao_labels(mol,fmt=True)

Labels for AO basis functions

Kwargs: fmt : str or bool if fmt is boolean, it controls whether to format the labels and the default format

is “%d%3s %s%-4s”. if fmt is string, the string will be used as the print format.

Returns: List of [(atom-id, symbol-str, nl-str, str-of-AO-notation)] or formatted strings based on the

argument “fmt”

ao_loc_2c(mol)

Offset of every shell in the spinor basis function spectrum

Returns: list, each entry is the corresponding start id of spinor function

Examples:

>>> mol =gto.M(atom='O000;C001', basis='6-31g')

>>> gto.ao_loc_2c(mol)

[0, 2, 4, 6, 12, 18, 20, 22, 24, 30, 36]

ao_loc_nr(mol,cart=False)

Offset of every shell in the spherical basis function spectrum

Returns: list, each entry is the corresponding start basis function id

Examples:

>>> mol =gto.M(atom='O000;C001', basis='6-31g')

>>> gto.ao_loc_nr(mol)

[0, 1, 2, 3, 6, 9, 10, 11, 12, 15, 18]

aoslice_2c_by_atom(mol)

2-component AO offset for each atom. Return a list, each item of the list gives (start-shell-id, stop-shell-id,

start-AO-id, stop-AO-id)

aoslice_by_atom(mol,ao_loc=None)

AO offsets for each atom. Return a list, each item of the list gives (start-shell-id, stop-shell-id, start-AO-id,

stop-AO-id)

aoslice_nr_by_atom(mol,ao_loc=None)

AO offsets for each atom. Return a list, each item of the list gives (start-shell-id, stop-shell-id, start-AO-id,

stop-AO-id)

atom_charge(atm_id)

Nuclear effective charge of the given atom id Note “atom_charge /= _charge(atom_symbol)” when ECP is

enabled. Number of electrons screened by ECP can be obtained by _charge(atom_symbol)-atom_charge

Args:

atm_id [int] 0-based

Examples:

1.4. gto — Molecular structure and GTO basis 55

PySCF Documentation, Release 1.4.0

>>> mol.build(atom='H 0 0 0; Cl 0 0 1.1')

>>> mol.atom_charge(1)

atom_charges()

np.asarray([mol.atom_charge(i) for i in range(mol.natm)])

atom_coord(atm_id)

Coordinates (ndarray) of the given atom id

Args:

atm_id [int] 0-based

Examples:

>>> mol.build(atom='H 0 0 0; Cl 0 0 1.1')

>>> mol.atom_coord(1)

[ 0. 0. 2.07869874]

atom_coords()

np.asarray([mol.atom_coords(i) for i in range(mol.natm)])

atom_nelec_core(atm_id)

Number of core electrons for pseudo potential.

atom_nshells(atm_id)

Number of basis/shells of the given atom

Args:

atm_id [int] 0-based

Examples:

>>> mol.build(atom='H 0 0 0; Cl 0 0 1.1')

>>> mol.atom_nshells(1)

atom_pure_symbol(atm_id)

For the given atom id, return the standard symbol (striping special characters)

Args:

atm_id [int] 0-based

Examples:

>>> mol.build(atom='H^2 0 0 0; H 0 0 1.1')

>>> mol.atom_symbol(0)

atom_shell_ids(atm_id)

A list of the shell-ids of the given atom

Args:

atm_id [int] 0-based

Examples:

56 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

>>> mol.build(atom='H 0 0 0; Cl 0 0 1.1', basis='cc-pvdz')

>>> mol.atom_shell_ids(1)

[3, 4, 5, 6, 7]

atom_symbol(atm_id)

For the given atom id, return the input symbol (without striping special characters)

Args:

atm_id [int] 0-based

Examples:

>>> mol.build(atom='H^2 0 0 0; H 0 0 1.1')

>>> mol.atom_symbol(0)

H^2

bas_angular(bas_id)

The angular momentum associated with the given basis

Args:

bas_id [int] 0-based

Examples:

>>> mol.build(atom='H 0 0 0; Cl 0 0 1.1', basis='cc-pvdz')

>>> mol.bas_atom(7)

bas_atom(bas_id)

The atom (0-based id) that the given basis sits on

Args:

bas_id [int] 0-based

Examples:

>>> mol.build(atom='H 0 0 0; Cl 0 0 1.1', basis='cc-pvdz')

>>> mol.bas_atom(7)

bas_coord(bas_id)

Coordinates (ndarray) associated with the given basis id

Args:

bas_id [int] 0-based

Examples:

>>> mol.build(atom='H 0 0 0; Cl 0 0 1.1')

>>> mol.bas_coord(1)

[ 0. 0. 2.07869874]

bas_ctr_coeff(bas_id)

Contract coefﬁcients (ndarray) of the given shell

Args:

bas_id [int] 0-based

1.4. gto — Molecular structure and GTO basis 57

PySCF Documentation, Release 1.4.0

Examples:

>>> mol.M(atom='H 0 0 0; Cl 0 0 1.1', basis='cc-pvdz')

>>> mol.bas_ctr_coeff(0)

[[ 10.03400444]

[ 4.1188704 ]

[ 1.53971186]]

bas_exp(bas_id)

exponents (ndarray) of the given shell

Args:

bas_id [int] 0-based

Examples:

>>> mol.build(atom='H 0 0 0; Cl 0 0 1.1', basis='cc-pvdz')

>>> mol.bas_kappa(0)

[ 13.01 1.962 0.4446]

bas_kappa(bas_id)

Kappa (if l < j, -l-1, else l) of the given shell

Args:

bas_id [int] 0-based

Examples:

>>> mol.build(atom='H 0 0 0; Cl 0 0 1.1', basis='cc-pvdz')

>>> mol.bas_kappa(3)

bas_len_cart(bas_id)

The number of Cartesian function associated with given basis

bas_len_spinor(bas_id)

The number of spinor associated with given basis If kappa is 0, return 4l+2

bas_nctr(bas_id)

The number of contracted GTOs for the given shell

Args:

bas_id [int] 0-based

Examples:

>>> mol.build(atom='H 0 0 0; Cl 0 0 1.1', basis='cc-pvdz')

>>> mol.bas_atom(3)

bas_nprim(bas_id)

The number of primitive GTOs for the given shell

Args:

bas_id [int] 0-based

Examples:

58 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

>>> mol.build(atom='H 0 0 0; Cl 0 0 1.1', basis='cc-pvdz')

>>> mol.bas_atom(3)

build(dump_input=True,parse_arg=True,verbose=None,output=None,max_memory=None,

atom=None,basis=None,unit=None,nucmod=None,ecp=None,charge=None,spin=None,

symmetry=None,symmetry_subgroup=None,cart=None)

Setup moleclue and initialize some control parameters. Whenever you change the value of the attributes

of Mole, you need call this function to refresh the internal data of Mole.

Kwargs:

dump_input [bool] whether to dump the contents of input ﬁle in the output ﬁle

parse_arg [bool] whether to read the sys.argv and overwrite the relevant parameters

verbose [int] Print level. If given, overwrite Mole.verbose

output [str or None] Output ﬁle. If given, overwrite Mole.output

max_memory [int, ﬂoat] Allowd memory in MB. If given, overwrite Mole.max_memory

atom [list or str] To deﬁne molecluar structure.

basis [dict or str] To deﬁne basis set.

nucmod [dict or str] Nuclear model. If given, overwrite Mole.nucmod

charge [int] Charge of molecule. It affects the electron numbers If given, overwrite Mole.charge

spin [int] 2S, num. alpha electrons - num. beta electrons If given, overwrite Mole.spin

symmetry [bool or str] Whether to use symmetry. If given a string of point group name, the given

point group symmetry will be used.

cart2sph_coeff(normalized=’sp’)

Transformation matrix to transform the Cartesian GTOs to spherical GTOs

Kwargs:

normalized [string or boolean] How the Cartesian GTOs are normalized. Except s and p functions,

Cartesian GTOs do not have the universal normalization coefﬁcients for the different compo-

nents of the same shell. The value of this argument can be one of ‘sp’, ‘all’, None. ‘sp’ means

the Cartesian s and p basis are normalized. ‘all’ means all Cartesian functions are normalized.

None means none of the Cartesian functions are normalized.

Examples:

>>> mol =gto.M(atom='H000;F001', basis='ccpvtz')

>>> c=mol.cart2sph_coeff()

>>> s0 =mol.intor('int1e_ovlp_sph')

>>> s1 =c.T.dot(mol.intor('int1e_ovlp_cart')).dot(c)

>>> print(abs(s1-s0).sum())

>>> 4.58676826646e-15

cart_labels(fmt=False)

Labels for Cartesian GTO functions

Kwargs: fmt : str or bool if fmt is boolean, it controls whether to format the labels and the default format

is “%d%3s %s%-4s”. if fmt is string, the string will be used as the print format.

Returns: List of [(atom-id, symbol-str, nl-str, str-of-xyz-notation)] or formatted strings based on the

argument “fmt”

1.4. gto — Molecular structure and GTO basis 59

PySCF Documentation, Release 1.4.0

condense_to_shell(mol,mat,compressor=<function amax>)

The given matrix is ﬁrst partitioned to blocks, based on AO shell as delimiter. Then call compressor

function to abstract each block.

dumps(mol)

Serialize Mole object to a JSON formatted str.

energy_nuc(mol,charges=None,coords=None)

Compute nuclear repulsion energy (AU) or static Coulomb energy

Returns ﬂoat

etbs(etbs)

Generate even tempered basis. See also expand_etb()

Args: etbs = [(l, n, alpha, beta), (l, n, alpha, beta),...]

Returns: Formated basis

Examples:

>>> gto.expand_etbs([(0,2,1.5,2.), (1,2,1,2.)])

[[0, [6.0, 1]], [0, [3.0, 1]], [1, [1., 1]], [1, [2., 1]]]

eval_gto(mol,eval_name,coords,comp=1,shls_slice=None,non0tab=None,ao_loc=None,

out=None)

Evaluate AO function value on the given grids,

Args: eval_name : str

Function Expression

“GTOval_sph” |AO>

“GTOval_ip_sph” nabla |AO>

“GTOval_ig_sph” (#C(0 1) g) |AO>

“GTOval_ipig_sph” (#C(0 1) nabla g) |AO>

“GTOval_cart” |AO>

“GTOval_ip_cart” nabla |AO>

“GTOval_ig_cart” (#C(0 1) g)|AO>

atm [int32 ndarray] libcint integral function argument

bas [int32 ndarray] libcint integral function argument

env [ﬂoat64 ndarray] libcint integral function argument

coords [2D array, shape (N,3)] The coordinates of the grids.

Kwargs:

shls_slice [2-element list] (shl_start, shl_end). If given, only part of AOs (shl_start <= shell_id <

shl_end) are evaluated. By default, all shells deﬁned in mol will be evaluated.

non0tab [2D bool array] mask array to indicate whether the AO values are zero. The mask array

can be obtained by calling make_mask()

out [ndarray] If provided, results are written into this array.

Returns: 2D array of shape (N,nao) Or 3D array of shape (*,N,nao) for AO values

Examples:

60 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

>>> mol =gto.M(atom='O000;H001;H010', basis='ccpvdz')

>>> coords =numpy.random.random((100,3)) # 100 random points

>>> ao_value =mol.eval_gto("GTOval_sph", coords)

>>> print(ao_value.shape)

(100, 24)

>>> ao_value =mol.eval_gto("GTOval_ig_sph", coords, comp=3)

>>> print(ao_value.shape)

(3, 100, 24)

expand_etb(l,n,alpha,beta)

Generate the exponents of even tempered basis for Mole.basis. .. math:

e=e^{-\alpha *\beta^{i-1}} for i=1.. n

Args:

l[int] Angular momentum

n[int] Number of GTOs

Returns: Formated basis

Examples:

>>> gto.expand_etb(1,3,1.5,2)

[[1, [6.0, 1]], [1, [3.0, 1]], [1, [1.5, 1]]]

expand_etbs(etbs)

Generate even tempered basis. See also expand_etb()

Args: etbs = [(l, n, alpha, beta), (l, n, alpha, beta),...]

Returns: Formated basis

Examples:

>>> gto.expand_etbs([(0,2,1.5,2.), (1,2,1,2.)])

[[0, [6.0, 1]], [0, [3.0, 1]], [1, [1., 1]], [1, [2., 1]]]

format_atom(atom,origin=0,axes=None,unit=’Ang’)

Convert the input Mole.atom to the internal data format. Including, changing the nuclear charge to

atom symbol, converting the coordinates to AU, rotate and shift the molecule. If the atom is a string, it

takes ”;” and “n” for the mark to separate atoms; ”,” and arbitrary length of blank space to spearate the

individual terms for an atom. Blank line will be ignored.

Args:

atoms [list or str] the same to Mole.atom

Kwargs:

origin [ndarray] new axis origin.

axes [ndarray] (new_x, new_y, new_z), each entry is a length-3 array

unit [str or number] If unit is one of strings (B, b, Bohr, bohr, AU, au), the coordinates of the input

atoms are the atomic unit; If unit is one of strings (A, a, Angstrom, angstrom, Ang, ang), the

coordinates are in the unit of angstrom; If a number is given, the number are considered as the

Bohr value (in angstrom), which should be around 0.53

Returns: “atoms” in the internal format as _atom

1.4. gto — Molecular structure and GTO basis 61

PySCF Documentation, Release 1.4.0

Examples:

>>> gto.format_atom('9,0,0,0; h@1 0 0 1', origin=(1,1,1))

[['F', [-1.0, -1.0, -1.0]], ['H@1', [-1.0, -1.0, 0.0]]]

>>> gto.format_atom(['9,0,0,0', (1, (0,0,1))], origin=(1,1,1))

[['F', [-1.0, -1.0, -1.0]], ['H', [-1, -1, 0]]]

format_basis(basis_tab)

Convert the input Mole.basis to the internal data format.

‘‘{ atom: [(l, ((-exp, c_1, c_2, ..),

(-exp, c_1, c_2, ..))),

(l, ((-exp, c_1, c_2, ..), (-exp, c_1, c_2, ..)))], ... }‘‘

Args:

basis_tab [dict] Similar to Mole.basis, it cannot be a str

Returns: Formated basis

Examples:

>>> gto.format_basis({'H':'sto-3g','H^2':'3-21g'})

{'H': [[0,

[3.4252509099999999, 0.15432897000000001],

[0.62391373000000006, 0.53532813999999995],

[0.16885539999999999, 0.44463454000000002]]],

'H^2': [[0,

[5.4471780000000001, 0.15628500000000001],

[0.82454700000000003, 0.90469100000000002]],

[0, [0.18319199999999999, 1.0]]]}

format_ecp(ecp_tab)

Convert the input ecp (dict) to the internal data format:

{ atom: (nelec, # core electrons

((l, # l=-1 for UL, l>=0 for Ul to indicate |l><l|

(((exp_1, c_1), # for r^0

(exp_2, c_2), ...),

((exp_1, c_1), # for r^1 (exp_2, c_2), ...),

((exp_1, c_1), # for r^2 ...))))),

...}

gto_norm(l,expnt)

Normalized factor for GTO radial part 𝑔=𝑟𝑙𝑒−𝛼𝑟2

𝑔2𝑟2𝑑𝑟

=22𝑙+3(𝑙+ 1)!(2𝑎)𝑙+1.5

(2𝑙+ 2)!√𝜋

Ref: H. B. Schlegel and M. J. Frisch, Int. J. Quant. Chem., 54(1995), 83-87.

62 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

Args:

l (int): angular momentum

expnt : exponent 𝛼

Returns: normalization factor

Examples:

>>> print gto_norm(0,1)

2.5264751109842591

has_ecp()

Whether pesudo potential is used in the system.

intor(intor,comp=1,hermi=0,aosym=’s1’,out=None,shls_slice=None)

Integral generator.

Args:

intor [str] Name of the 1e or 2e AO integrals. Ref to getints() for the complete list of available

1-electron integral names

Kwargs:

comp [int] Components of the integrals, e.g. int1e_ipovlp_sph has 3 components.

hermi [int] Symmetry of the integrals

0 : no symmetry assumed (default)

1 : hermitian

2 : anti-hermitian

Returns: ndarray of 1-electron integrals, can be either 2-dim or 3-dim, depending on comp

Examples:

>>> mol.build(atom='H000;H001.1', basis='sto-3g')

>>> mol.intor('int1e_ipnuc_sph', comp=3)# <nabla i | V_nuc | j>

[[[ 0. 0. ]

[ 0. 0. ]]

[[ 0. 0. ]

[ 0. 0. ]]

[[ 0.10289944 0.48176097]

[-0.48176097 -0.10289944]]]

>>> mol.intor('int1e_nuc_spinor')

[[-1.69771092+0.j 0.00000000+0.j -0.67146312+0.j 0.00000000+0.j]

[ 0.00000000+0.j -1.69771092+0.j 0.00000000+0.j -0.67146312+0.j]

[-0.67146312+0.j 0.00000000+0.j -1.69771092+0.j 0.00000000+0.j]

[ 0.00000000+0.j -0.67146312+0.j 0.00000000+0.j -1.69771092+0.j]]

intor_asymmetric(intor,comp=1)

One-electron integral generator. The integrals are assumed to be anti-hermitian

Args:

intor [str] Name of the 1-electron integral. Ref to getints() for the complete list of available

1-electron integral names

1.4. gto — Molecular structure and GTO basis 63

PySCF Documentation, Release 1.4.0

Kwargs:

comp [int] Components of the integrals, e.g. int1e_ipovlp has 3 components.

Returns: ndarray of 1-electron integrals, can be either 2-dim or 3-dim, depending on comp

Examples:

>>> mol.build(atom='H000;H001.1', basis='sto-3g')

>>> mol.intor_asymmetric('int1e_nuc_spinor')

[[-1.69771092+0.j 0.00000000+0.j 0.67146312+0.j 0.00000000+0.j]

[ 0.00000000+0.j -1.69771092+0.j 0.00000000+0.j 0.67146312+0.j]

[-0.67146312+0.j 0.00000000+0.j -1.69771092+0.j 0.00000000+0.j]

[ 0.00000000+0.j -0.67146312+0.j 0.00000000+0.j -1.69771092+0.j]]

intor_by_shell(intor,shells,comp=1)

For given 2, 3 or 4 shells, interface for libcint to get 1e, 2e, 2-center-2e or 3-center-2e integrals

Args:

intor_name [str] See also getints() for the supported intor_name

shls [list of int] The AO shell-ids of the integrals

atm [int32 ndarray] libcint integral function argument

bas [int32 ndarray] libcint integral function argument

env [ﬂoat64 ndarray] libcint integral function argument

Kwargs:

comp [int] Components of the integrals, e.g. int1e_ipovlp has 3 components.

Returns: ndarray of 2-dim to 5-dim, depending on the integral type (1e, 2e, 3c-2e, 2c2e) and the value

of comp

Examples: The gradients of the spherical 2e integrals

>>> mol.build(atom='H000;H001.1', basis='sto-3g')

>>> gto.getints_by_shell('int2e_ip1_sph', (0,1,0,1), mol._atm, mol._bas, mol.

˓→_env, comp=3)

[[[[[-0. ]]]]

[[[[-0. ]]]]

[[[[-0.08760462]]]]]

intor_symmetric(intor,comp=1)

One-electron integral generator. The integrals are assumed to be hermitian

Args:

intor [str] Name of the 1-electron integral. Ref to getints() for the complete list of available

1-electron integral names

Kwargs:

comp [int] Components of the integrals, e.g. int1e_ipovlp_sph has 3 components.

Returns: ndarray of 1-electron integrals, can be either 2-dim or 3-dim, depending on comp

Examples:

>>> mol.build(atom='H000;H001.1', basis='sto-3g')

>>> mol.intor_symmetric('int1e_nuc_spinor')

[[-1.69771092+0.j 0.00000000+0.j -0.67146312+0.j 0.00000000+0.j]

64 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

[ 0.00000000+0.j -1.69771092+0.j 0.00000000+0.j -0.67146312+0.j]

[-0.67146312+0.j 0.00000000+0.j -1.69771092+0.j 0.00000000+0.j]

[ 0.00000000+0.j -0.67146312+0.j 0.00000000+0.j -1.69771092+0.j]]

kernel(dump_input=True,parse_arg=True,verbose=None,output=None,max_memory=None,

atom=None,basis=None,unit=None,nucmod=None,ecp=None,charge=None,spin=None,

symmetry=None,symmetry_subgroup=None,cart=None)

Setup moleclue and initialize some control parameters. Whenever you change the value of the attributes

of Mole, you need call this function to refresh the internal data of Mole.

Kwargs:

dump_input [bool] whether to dump the contents of input ﬁle in the output ﬁle

parse_arg [bool] whether to read the sys.argv and overwrite the relevant parameters

verbose [int] Print level. If given, overwrite Mole.verbose

output [str or None] Output ﬁle. If given, overwrite Mole.output

max_memory [int, ﬂoat] Allowd memory in MB. If given, overwrite Mole.max_memory

atom [list or str] To deﬁne molecluar structure.

basis [dict or str] To deﬁne basis set.

nucmod [dict or str] Nuclear model. If given, overwrite Mole.nucmod

charge [int] Charge of molecule. It affects the electron numbers If given, overwrite Mole.charge

spin [int] 2S, num. alpha electrons - num. beta electrons If given, overwrite Mole.spin

symmetry [bool or str] Whether to use symmetry. If given a string of point group name, the given

point group symmetry will be used.

loads(molstr)

Deserialize a str containing a JSON document to a Mole object.

nao_2c(mol)

Total number of contracted spinor GTOs for the given Mole object

nao_2c_range(mol,bas_id0,bas_id1)

Lower and upper boundary of contracted spinor basis functions associated with the given shell range

Args:

mol : Mole object

bas_id0 [int] start shell id, 0-based

bas_id1 [int] stop shell id, 0-based

Returns: tupel of start basis function id and the stop function id

Examples:

>>> mol =gto.M(atom='O000;C001', basis='6-31g')

>>> gto.nao_2c_range(mol, 2,4)

(4, 12)

nao_cart(mol)

Total number of contracted cartesian GTOs for the given Mole object

nao_nr(mol,cart=False)

Total number of contracted spherical GTOs for the given Mole object

1.4. gto — Molecular structure and GTO basis 65

PySCF Documentation, Release 1.4.0

nao_nr_range(mol,bas_id0,bas_id1)

Lower and upper boundary of contracted spherical basis functions associated with the given shell range

Args:

mol : Mole object

bas_id0 [int] start shell id

bas_id1 [int] stop shell id

Returns: tupel of start basis function id and the stop function id

Examples:

>>> mol =gto.M(atom='O000;C001', basis='6-31g')

>>> gto.nao_nr_range(mol, 2,4)

(2, 6)

npgto_nr(mol,cart=False)

Total number of primitive spherical GTOs for the given Mole object

offset_2c_by_atom(mol)

2-component AO offset for each atom. Return a list, each item of the list gives (start-shell-id, stop-shell-id,

start-AO-id, stop-AO-id)

offset_ao_by_atom(mol,ao_loc=None)

AO offsets for each atom. Return a list, each item of the list gives (start-shell-id, stop-shell-id, start-AO-id,

stop-AO-id)

offset_nr_by_atom(mol,ao_loc=None)

AO offsets for each atom. Return a list, each item of the list gives (start-shell-id, stop-shell-id, start-AO-id,

stop-AO-id)

pack(mol)

Pack the input args of Mole to a dict.

Note this function only pack the input arguments (not the entire Mole class). Modiﬁcations to mol._atm,

mol._bas, mol._env are not tracked. Use dumps() to serialize the entire Mole object.

search_ao_label(mol,label)

Find the index of the AO basis function based on the given ao_label

Args:

ao_label [string or a list of strings] The regular expression pattern to match the orbital labels re-

turned by mol.ao_labels()

Returns: A list of index for the AOs that matches the given ao_label RE pattern

Examples:

>>> mol =gto.M(atom='H000;Cl001', basis='ccpvtz')

>>> mol.parse_aolabel('Cl.*p')

[19 20 21 22 23 24 25 26 27 28 29 30]

>>> mol.parse_aolabel('Cl 2p')

[19 20 21]

>>> mol.parse_aolabel(['Cl.*d','Cl 4p'])

[25 26 27 31 32 33 34 35 36 37 38 39 40]

search_ao_nr(mol,atm_id,l,m,atmshell)

Search the ﬁrst basis function id (not the shell id) which matches the given atom-id, angular momentum

magnetic angular momentum, principal shell.

66 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

Args:

atm_id [int] atom id, 0-based

l[int] angular momentum

m[int] magnetic angular momentum

atmshell [int] principal quantum number

Returns: basis function id, 0-based. If not found, return None

Examples:

>>> mol =gto.M(atom='H000;Cl001', basis='sto-3g')

>>> mol.search_ao_nr(1,1,-1,3)# Cl 3px

set_common_orig(coord)

Update common origin which held in :class‘Mole‘._env. Note the unit is Bohr

Examples:

>>> mol.set_common_orig(0)

>>> mol.set_common_orig((1,0,0))

set_common_orig_(coord)

Update common origin which held in :class‘Mole‘._env. Note the unit is Bohr

Examples:

>>> mol.set_common_orig(0)

>>> mol.set_common_orig((1,0,0))

set_common_origin(coord)

Update common origin which held in :class‘Mole‘._env. Note the unit is Bohr

Examples:

>>> mol.set_common_orig(0)

>>> mol.set_common_orig((1,0,0))

set_common_origin_(coord)

Update common origin which held in :class‘Mole‘._env. Note the unit is Bohr

Examples:

>>> mol.set_common_orig(0)

>>> mol.set_common_orig((1,0,0))

set_f12_zeta(zeta)

Set zeta for YP exp(-zeta r12)/r12 or STG exp(-zeta r12) type integrals

set_geom_(atoms,unit=’Angstrom’,symmetry=None)

Replace geometry

set_nuc_mod(atm_id,zeta)

Change the nuclear charge distribution of the given atom ID. The charge distribution is deﬁned as: rho(r) =

nuc_charge * Norm * exp(-zeta * r^2). This function can only be called after .build() method is executed.

Examples:

1.4. gto — Molecular structure and GTO basis 67

PySCF Documentation, Release 1.4.0

>>> for ia in range(mol.natm):

... zeta =gto.filatov_nuc_mod(mol.atom_charge(ia))

... mol.set_nuc_mod(ia, zeta)

set_nuc_mod_(atm_id,zeta)

Change the nuclear charge distribution of the given atom ID. The charge distribution is deﬁned as: rho(r) =

nuc_charge * Norm * exp(-zeta * r^2). This function can only be called after .build() method is executed.

Examples:

>>> for ia in range(mol.natm):

... zeta =gto.filatov_nuc_mod(mol.atom_charge(ia))

... mol.set_nuc_mod(ia, zeta)

set_range_coulomb(omega)

Apply the long range part of range-separated Coulomb operator for all 2e integrals erf(omega r12) / r12

set omega to 0 to siwtch off the range-separated Coulomb

set_range_coulomb_(omega)

Apply the long range part of range-separated Coulomb operator for all 2e integrals erf(omega r12) / r12

set omega to 0 to siwtch off the range-separated Coulomb

set_rinv_orig(coord)

Update origin for operator 1

|𝑟−𝑅𝑂|.Note the unit is Bohr

Examples:

>>> mol.set_rinv_orig(0)

>>> mol.set_rinv_orig((0,1,0))

set_rinv_orig_(coord)

Update origin for operator 1

|𝑟−𝑅𝑂|.Note the unit is Bohr

Examples:

>>> mol.set_rinv_orig(0)

>>> mol.set_rinv_orig((0,1,0))

set_rinv_origin(coord)

Update origin for operator 1

|𝑟−𝑅𝑂|.Note the unit is Bohr

Examples:

>>> mol.set_rinv_orig(0)

>>> mol.set_rinv_orig((0,1,0))

set_rinv_origin_(coord)

Update origin for operator 1

|𝑟−𝑅𝑂|.Note the unit is Bohr

Examples:

>>> mol.set_rinv_orig(0)

>>> mol.set_rinv_orig((0,1,0))

set_rinv_zeta(zeta)

Assume the charge distribution on the “rinv_orig”. zeta is the parameter to control the charge distribu-

tion: rho(r) = Norm * exp(-zeta * r^2). Be careful when call this function. It affects the behavior of

int1e_rinv_* functions. Make sure to set it back to 0 after using it!

68 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

set_rinv_zeta_(zeta)

Assume the charge distribution on the “rinv_orig”. zeta is the parameter to control the charge distribu-

tion: rho(r) = Norm * exp(-zeta * r^2). Be careful when call this function. It affects the behavior of

int1e_rinv_* functions. Make sure to set it back to 0 after using it!

spheric_labels(fmt=False)

Labels for spherical GTO functions

Kwargs: fmt : str or bool if fmt is boolean, it controls whether to format the labels and the default format

is “%d%3s %s%-4s”. if fmt is string, the string will be used as the print format.

Returns: List of [(atom-id, symbol-str, nl-str, str-of-real-spherical-notation] or formatted strings based

on the argument “fmt”

Examples:

>>> mol =gto.M(atom='H000;Cl001', basis='sto-3g')

>>> gto.spherical_labels(mol)

[(0, 'H', '1s', ''), (1, 'Cl', '1s', ''), (1, 'Cl', '2s', ''), (1, 'Cl', '3s

˓→', ''), (1, 'Cl', '2p', 'x'), (1, 'Cl', '2p', 'y'), (1, 'Cl', '2p', 'z'),

˓→(1, 'Cl', '3p', 'x'), (1, 'Cl', '3p', 'y'), (1, 'Cl', '3p', 'z')]

spherical_labels(fmt=False)

Labels for spherical GTO functions

Kwargs: fmt : str or bool if fmt is boolean, it controls whether to format the labels and the default format

is “%d%3s %s%-4s”. if fmt is string, the string will be used as the print format.

Returns: List of [(atom-id, symbol-str, nl-str, str-of-real-spherical-notation] or formatted strings based

on the argument “fmt”

Examples:

>>> mol =gto.M(atom='H000;Cl001', basis='sto-3g')

>>> gto.spherical_labels(mol)

[(0, 'H', '1s', ''), (1, 'Cl', '1s', ''), (1, 'Cl', '2s', ''), (1, 'Cl', '3s

˓→', ''), (1, 'Cl', '2p', 'x'), (1, 'Cl', '2p', 'y'), (1, 'Cl', '2p', 'z'),

˓→(1, 'Cl', '3p', 'x'), (1, 'Cl', '3p', 'y'), (1, 'Cl', '3p', 'z')]

time_reversal_map(mol)

The index to map the spinor functions and its time reversal counterpart. The returned indices have postive

or negative values. For the i-th basis function, if the returned j = idx[i] < 0, it means 𝑇|𝑖⟩=−|𝑗⟩,

otherwise 𝑇|𝑖⟩=|𝑗⟩

tot_electrons(mol)

Total number of electrons for the given molecule

Returns: electron number in integer

Examples:

>>> mol =gto.M(atom='H010;C001', charge=1)

>>> mol.tot_electrons()

unpack(moldic)

Unpack a dict which is packed by pack(), to generate the input arguments for Mole object.

1.4. gto — Molecular structure and GTO basis 69

PySCF Documentation, Release 1.4.0

moleintor

pyscf.gto.moleintor.ascint3(intor_name)

convert cint2 function name to cint3 function name

pyscf.gto.moleintor.getints(intor_name,atm,bas,env,shls_slice=None,comp=1,hermi=0,

aosym=’s1’,ao_loc=None,cintopt=None,out=None)

1e and 2e integral generator.

Args: intor_name : str

Function Expression

“int1e_ovlp_sph” ( | )

“int1e_nuc_sph” ( | nuc | )

“int1e_kin_sph” (.5 | p dot p)

“int1e_ia01p_sph” (#C(0 1) | nabla-rinv | cross p)

“int1e_giao_irjxp_sph” (#C(0 1) | r cross p)

“int1e_cg_irxp_sph” (#C(0 1) | rc cross p)

“int1e_giao_a11part_sph” (-.5 | nabla-rinv | r)

“int1e_cg_a11part_sph” (-.5 | nabla-rinv | rc)

“int1e_a01gp_sph” (g | nabla-rinv cross p |)

“int1e_igkin_sph” (#C(0 .5) g | p dot p)

“int1e_igovlp_sph” (#C(0 1) g |)

“int1e_ignuc_sph” (#C(0 1) g | nuc |)

“int1e_z_sph” ( | zc | )

“int1e_zz_sph” ( | zc zc | )

“int1e_r_sph” ( | rc | )

“int1e_r2_sph” ( | rc dot rc | )

“int1e_rr_sph” ( | rc rc | )

“int1e_pnucp_sph” (p* | nuc dot p | )

“int1e_prinvxp_sph” (p* | rinv cross p | )

“int1e_ovlp_spinor” ( | )

“int1e_nuc_spinor” ( | nuc |)

“int1e_srsr_spinor” (sigma dot r | sigma dot r)

“int1e_sr_spinor” (sigma dot r |)

“int1e_srsp_spinor” (sigma dot r | sigma dot p)

“int1e_spsp_spinor” (sigma dot p | sigma dot p)

“int1e_sp_spinor” (sigma dot p |)

“int1e_spnucsp_spinor” (sigma dot p | nuc | sigma dot p)

“int1e_srnucsr_spinor” (sigma dot r | nuc | sigma dot r)

“int1e_govlp_spinor” (g |)

“int1e_gnuc_spinor” (g | nuc |)

“int1e_cg_sa10sa01_spinor” (.5 sigma cross rc | sigma cross nabla-rinv |)

“int1e_cg_sa10sp_spinor” (.5 rc cross sigma | sigma dot p)

“int1e_cg_sa10nucsp_spinor” (.5 rc cross sigma | nuc | sigma dot p)

“int1e_giao_sa10sa01_spinor” (.5 sigma cross r | sigma cross nabla-rinv |)

“int1e_giao_sa10sp_spinor” (.5 r cross sigma | sigma dot p)

“int1e_giao_sa10nucsp_spinor” (.5 r cross sigma | nuc | sigma dot p)

“int1e_sa01sp_spinor” (| nabla-rinv cross sigma | sigma dot p)

“int1e_spgsp_spinor” (g sigma dot p | sigma dot p)

“int1e_spgnucsp_spinor” (g sigma dot p | nuc | sigma dot p)

“int1e_spgsa01_spinor” (g sigma dot p | nabla-rinv cross sigma |)

“int1e_spspsp_spinor” (sigma dot p | sigma dot p sigma dot p)

Continued on next page

70 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

Table 1.1 – continued from previous page

Function Expression

“int1e_spnuc_spinor” (sigma dot p | nuc |)

“int1e_ovlp_cart” ( | )

“int1e_nuc_cart” ( | nuc | )

“int1e_kin_cart” (.5 | p dot p)

“int1e_ia01p_cart” (#C(0 1) | nabla-rinv | cross p)

“int1e_giao_irjxp_cart” (#C(0 1) | r cross p)

“int1e_cg_irxp_cart” (#C(0 1) | rc cross p)

“int1e_giao_a11part_cart” (-.5 | nabla-rinv | r)

“int1e_cg_a11part_cart” (-.5 | nabla-rinv | rc)

“int1e_a01gp_cart” (g | nabla-rinv cross p |)

“int1e_igkin_cart” (#C(0 .5) g | p dot p)

“int1e_igovlp_cart” (#C(0 1) g |)

“int1e_ignuc_cart” (#C(0 1) g | nuc |)

“int1e_ipovlp_sph” (nabla |)

“int1e_ipkin_sph” (.5 nabla | p dot p)

“int1e_ipnuc_sph” (nabla | nuc |)

“int1e_iprinv_sph” (nabla | rinv |)

“int1e_rinv_sph” (| rinv |)

“int1e_ipovlp_spinor” (nabla |)

“int1e_ipkin_spinor” (.5 nabla | p dot p)

“int1e_ipnuc_spinor” (nabla | nuc |)

“int1e_iprinv_spinor” (nabla | rinv |)

“int1e_ipspnucsp_spinor” (nabla sigma dot p | nuc | sigma dot p)

“int1e_ipsprinvsp_spinor” (nabla sigma dot p | rinv | sigma dot p)

“int1e_ipovlp_cart” (nabla |)

“int1e_ipkin_cart” (.5 nabla | p dot p)

“int1e_ipnuc_cart” (nabla | nuc |)

“int1e_iprinv_cart” (nabla | rinv |)

“int1e_rinv_cart” (| rinv |)

“int2e_p1vxp1_sph” ( p* , cross p | , ) ; SSO

“int2e_sph” ( , | , )

“int2e_ig1_sph” (#C(0 1) g , | , )

“int2e_spinor” (, | , )

“int2e_spsp1_spinor” (sigma dot p , sigma dot p | , )

“int2e_spsp1spsp2_spinor” (sigma dot p , sigma dot p | sigma dot p , sigma dot p )

“int2e_srsr1_spinor” (sigma dot r , sigma dot r | ,)

“int2e_srsr1srsr2_spinor” (sigma dot r , sigma dot r | sigma dot r , sigma dot r)

“int2e_cg_sa10sp1_spinor” (.5 rc cross sigma , sigma dot p | ,)

“int2e_cg_sa10sp1spsp2_spinor” (.5 rc cross sigma , sigma dot p | sigma dot p , sigma dot p )

“int2e_giao_sa10sp1_spinor” (.5 r cross sigma , sigma dot p | ,)

“int2e_giao_sa10sp1spsp2_spinor” (.5 r cross sigma , sigma dot p | sigma dot p , sigma dot p )

“int2e_g1_spinor” (g , | ,)

“int2e_spgsp1_spinor” (g sigma dot p , sigma dot p | ,)

“int2e_g1spsp2_spinor” (g , | sigma dot p , sigma dot p)

“int2e_spgsp1spsp2_spinor” (g sigma dot p , sigma dot p | sigma dot p , sigma dot p)

“int2e_spv1_spinor” (sigma dot p , | ,)

“int2e_vsp1_spinor” (, sigma dot p | ,)

“int2e_spsp2_spinor” (, | sigma dot p , sigma dot p)

“int2e_spv1spv2_spinor” (sigma dot p , | sigma dot p ,)

Continued on next page

1.4. gto — Molecular structure and GTO basis 71

PySCF Documentation, Release 1.4.0

Table 1.1 – continued from previous page

Function Expression

“int2e_vsp1spv2_spinor” (, sigma dot p | sigma dot p ,)

“int2e_spv1vsp2_spinor” (sigma dot p , | , sigma dot p)

“int2e_vsp1vsp2_spinor” (, sigma dot p | , sigma dot p)

“int2e_spv1spsp2_spinor” (sigma dot p , | sigma dot p , sigma dot p)

“int2e_vsp1spsp2_spinor” (, sigma dot p | sigma dot p , sigma dot p)

“int2e_ig1_cart” (#C(0 1) g , | , )

“int2e_ip1_sph” (nabla , | ,)

“int2e_ip1_spinor” (nabla , | ,)

“int2e_ipspsp1_spinor” (nabla sigma dot p , sigma dot p | ,)

“int2e_ip1spsp2_spinor” (nabla , | sigma dot p , sigma dot p)

“int2e_ipspsp1spsp2_spinor” (nabla sigma dot p , sigma dot p | sigma dot p , sigma dot p)

“int2e_ipsrsr1_spinor” (nabla sigma dot r , sigma dot r | ,)

“int2e_ip1srsr2_spinor” (nabla , | sigma dot r , sigma dot r)

“int2e_ipsrsr1srsr2_spinor” (nabla sigma dot r , sigma dot r | sigma dot r , sigma dot r)

“int2e_ip1_cart” (nabla , | ,)

“int2e_ssp1ssp2_spinor” ( , sigma dot p | gaunt | , sigma dot p)

“int2e_cg_ssa10ssp2_spinor” (rc cross sigma , | gaunt | , sigma dot p)

“int2e_giao_ssa10ssp2_spinor” (r cross sigma , | gaunt | , sigma dot p)

“int2e_gssp1ssp2_spinor” (g , sigma dot p | gaunt | , sigma dot p)

“int2e_ipip1_sph” ( nabla nabla , | , )

“int2e_ipvip1_sph” ( nabla , nabla | , )

“int2e_ip1ip2_sph” ( nabla , | nabla , )

“int3c2e_ip1_sph” (nabla , | )

“int3c2e_ip2_sph” ( , | nabla)

“int2c2e_ip1_sph” (nabla | r12 | )

“int3c2e_spinor” (nabla , | )

“int3c2e_spsp1_spinor” (nabla , | )

“int3c2e_ip1_spinor” (nabla , | )

“int3c2e_ip2_spinor” ( , | nabla)

“int3c2e_ipspsp1_spinor” (nabla sigma dot p , sigma dot p | )

“int3c2e_spsp1ip2_spinor” (sigma dot p , sigma dot p | nabla )

atm [int32 ndarray] libcint integral function argument

bas [int32 ndarray] libcint integral function argument

env [ﬂoat64 ndarray] libcint integral function argument

Kwargs:

shls_slice [8-element list] (ish_start, ish_end, jsh_start, jsh_end, ksh_start, ksh_end, lsh_start, lsh_end)

comp [int] Components of the integrals, e.g. int1e_ipovlp has 3 components.

hermi [int (1e integral only)] Symmetry of the 1e integrals

0 : no symmetry assumed (default)

1 : hermitian

2 : anti-hermitian

72 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

aosym [str (2e integral only)] Symmetry of the 2e integrals

4 or ‘4’ or ‘s4’: 4-fold symmetry (default)

‘2ij’ or ‘s2ij’ : symmetry between i, j in (ij|kl)

‘2kl’ or ‘s2kl’ : symmetry between k, l in (ij|kl)

1 or ‘1’ or ‘s1’: no symmetry

out [ndarray (2e integral only)] array to store the 2e AO integrals

Returns: ndarray of 1-electron integrals, can be either 2-dim or 3-dim, depending on comp

Examples:

>>> mol.build(atom='H000;H001.1', basis='sto-3g')

>>> gto.getints('int1e_ipnuc_sph', mol._atm, mol._bas, mol._env, comp=3)# <nabla

˓→i | V_nuc | j>

[[[ 0. 0. ]

[ 0. 0. ]]

[[ 0. 0. ]

[ 0. 0. ]]

[[ 0.10289944 0.48176097]

[-0.48176097 -0.10289944]]]

pyscf.gto.moleintor.getints_by_shell(intor_name,shls,atm,bas,env,comp=1)

For given 2, 3 or 4 shells, interface for libcint to get 1e, 2e, 2-center-2e or 3-center-2e integrals

Args:

intor_name [str] See also getints() for the supported intor_name

shls [list of int] The AO shell-ids of the integrals

atm [int32 ndarray] libcint integral function argument

bas [int32 ndarray] libcint integral function argument

env [ﬂoat64 ndarray] libcint integral function argument

Kwargs:

comp [int] Components of the integrals, e.g. int1e_ipovlp has 3 components.

Returns: ndarray of 2-dim to 5-dim, depending on the integral type (1e, 2e, 3c-2e, 2c2e) and the value of comp

Examples: The gradients of the spherical 2e integrals

>>> mol.build(atom='H000;H001.1', basis='sto-3g')

>>> gto.getints_by_shell('int2e_ip1_sph', (0,1,0,1), mol._atm, mol._bas, mol._

˓→env, comp=3)

[[[[[-0. ]]]]

[[[[-0. ]]]]

[[[[-0.08760462]]]]]

1.4. gto — Molecular structure and GTO basis 73

PySCF Documentation, Release 1.4.0

basis

Internal format

This module loads basis set and ECP data from basis database and parse the basis (mostly in NWChem format) and

ﬁnally convert to internal format. The internal format of basis set is:

basis ={atom_type1:[[angular_momentum

(GTO-exp1, contract-coeff11, contract-coeff12),

(GTO-exp2, contract-coeff21, contract-coeff22),

(GTO-exp3, contract-coeff31, contract-coeff32),

...],

[angular_momentum

(GTO-exp1, contract-coeff11, contract-coeff12),

...],

atom_type2:[[angular_momentum, (...),],

...],

For example:

mol.basis ={'H': [[0,

(19.2406000,0.0328280),

(2.8992000,0.2312080),

(0.6534000,0.8172380),],

[0,

(0.1776000,1.0000000),],

[1,

(1.0000000,1.0000000),]],

}

Some basis sets, e.g. pyscf/gto/basis/dzp_dunning.py, are saved in the internal format.

pyscf.gto.basis.load(ﬁlename_or_basisname,symb)

Convert the basis of the given symbol to internal format

Args:

ﬁlename_or_basisname [str] Case insensitive basis set name. Special characters will be removed. or a

string of “path/to/ﬁle” which stores the basis functions

symb [str] Atomic symbol, Special characters will be removed.

Examples: Load STO 3G basis of carbon to oxygen atom

>>> mol =gto.Mole()

>>> mol.basis ={'O': load('sto-3g','C')}

pyscf.gto.basis.load_ecp(ﬁlename_or_basisname,symb)

Convert the basis of the given symbol to internal format

pyscf.gto.basis.parse(string,symb=None)

Parse the NWChem format basis or ECP text, return an internal basis (ECP) format which can be assigned to

Mole.basis or Mole.ecp

Args: string : Blank linke and the lines of “BASIS SET” and “END” will be ignored

Examples:

74 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

>>> mol =gto.Mole()

>>> mol.basis ={'O': gto.basis.parse("""

... #BASIS SET: (6s,3p) -> [2s,1p]

... C S

... 71.6168370 0.15432897

... 13.0450960 0.53532814

... 3.5305122 0.44463454

... C SP

... 2.9412494 -0.09996723 0.15591627

... 0.6834831 0.39951283 0.60768372

... 0.2222899 0.70011547 0.39195739

... """)}

1.5 lib — Helper functions, parameters, and C extensions

C code and some fundamental functions

1.5.1 parameters

Some PySCF environment parameters are deﬁned in this module.

Scratch directory

The PySCF scratch directory is speciﬁed by TMPDIR. Its default value is the same to the system environment variable

TMPDIR. It can be overwritten by the system environment variable PYSCF_TMPDIR.

Maximum memory

The variable MAX_MEMORY deﬁnes the maximum memory that PySCF can be used in the calculation. Its unit is MB.

The default value is 4000 MB. It can be overwritten by the system environment variable PYSCF_MAX_MEMORY.

Note: Some calculations may exceed the max_memory limit, especially when the incore_anyway of Mole object

was set.

1.5. lib — Helper functions, parameters, and C extensions 75

PySCF Documentation, Release 1.4.0

1.5.2 logger

Logging system

Log level

Level number

DEBUG4 9

DEBUG3 8

DEBUG2 7

DEBUG1 6

DEBUG 5

INFO 4

NOTE 3

WARN 2

ERROR 1

QUIET 0

Big verbose value means more noise in the output ﬁle.

Note: At log level 1 (ERROR) and 2 (WARN), the messages are also output to stderr.

Each Logger object has its own output destination and verbose level. So multiple Logger objects can be created

to manage the message system without affecting each other. The methods provided by Logger class has the direct

connection to the log level. E.g. info() print messages if the verbose level >= 4 (INFO):

>>> import sys

>>> from pyscf import lib

>>> log =lib.logger.Logger(sys.stdout, 4)

>>> log.info('info level')

info level

>>> log.verbose =3

>>> log.info('info level')

>>> log.note('note level')

note level

timer

Logger object provides timer method for timing. Set TIMER_LEVEL to control which level to output the timing. It is

5 (DEBUG) by default.

>>> import sys,time

>>> from pyscf import lib

>>> log =lib.logger.Logger(sys.stdout, 4)

>>> t0 =time.clock()

>>> log.timer('test', t0)

>>> lib.logger.TIMER_LEVEL =4

>>> log.timer('test', t0)

CPU time for test 0.00 sec

76 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

1.5.3 numpy helper

pyscf.lib.numpy_helper.asarray(a,dtype=None,order=None)

Convert a list of N-dim arrays to a (N+1) dim array. It is equivalent to numpy.asarray function but more efﬁcient.

pyscf.lib.numpy_helper.cartesian_prod(arrays,out=None)

Generate a cartesian product of input arrays. http://stackoverﬂow.com/questions/1208118/

using-numpy-to-build-an-array-of-all-combinations-of-two-arrays

Args:

arrays [list of array-like] 1-D arrays to form the cartesian product of.

out [ndarray] Array to place the cartesian product in.

Returns:

out [ndarray] 2-D array of shape (M, len(arrays)) containing cartesian products formed of input arrays.

Examples:

>>> cartesian_prod(([1,2,3], [4,5], [6,7]))

array([[1, 4, 6],

[1, 4, 7],

[1, 5, 6],

[1, 5, 7],

[2, 4, 6],

[2, 4, 7],

[2, 5, 6],

[2, 5, 7],

[3, 4, 6],

[3, 4, 7],

[3, 5, 6],

[3, 5, 7]])

pyscf.lib.numpy_helper.cond(x,p=None)

Compute the condition number

pyscf.lib.numpy_helper.condense(opname,a,locs)

nd =loc[-1]

out =numpy.empty((nd,nd))

for i,i0 in enumerate(loc):

i1 =loc[i+1]

for j,j0 in enumerate(loc):

j1 =loc[j+1]

out[i,j] =op(a[i0:i1,j0:j1])

return out

pyscf.lib.numpy_helper.ddot(a,b,alpha=1,c=None,beta=0)

Matrix-matrix multiplication for double precision arrays

pyscf.lib.numpy_helper.direct_sum(subscripts,*operands)

Apply the summation over many operands with the einsum fashion.

Examples:

>>> a=numpy.random((6,5))

>>> b=numpy.random((4,3,2))

>>> direct_sum('ij,klm->ijklm', a, b).shape

1.5. lib — Helper functions, parameters, and C extensions 77

PySCF Documentation, Release 1.4.0

(6, 5, 4, 3, 2)

>>> direct_sum('ij,klm', a, b).shape

(6, 5, 4, 3, 2)

>>> direct_sum('i,j,klm->mjlik', a[0], a[:,0], b).shape

(2, 6, 3, 5, 4)

>>> direct_sum('ij-klm->ijklm', a, b).shape

(6, 5, 4, 3, 2)

>>> direct_sum('ij+klm', a, b).shape

(6, 5, 4, 3, 2)

>>> direct_sum('-i-j+klm->mjlik', a[0], a[:,0], b).shape

(2, 6, 3, 5, 4)

>>> c=numpy.random((3,5))

>>> z=direct_sum('ik+jk->kij', a, c).shape # This is slow

>>> abs(a.T.reshape(5,6,1)+c.reshape(5,1,3)-z).sum()

0.0

pyscf.lib.numpy_helper.einsum(idx_str,*tensors)

Perform a more efﬁcient einsum via reshaping to a matrix multiply.

Current differences compared to numpy.einsum: This assumes that each repeated index is actually summed (i.e.

no ‘i,i->i’) and appears only twice (i.e. no ‘ij,ik,il->jkl’). The output indices must be explicitly speciﬁed (i.e.

‘ij,j->i’ and not ‘ij,j’).

pyscf.lib.numpy_helper.hermi_sum(a,axes=None,hermi=1,inplace=False,out=None)

a + a.T for better memory efﬁciency

Examples:

>>> transpose_sum(numpy.arange(4.).reshape(2,2))

[[ 0. 3.]

[ 3. 6.]]

pyscf.lib.numpy_helper.hermi_triu(mat,hermi=1,inplace=True)

Use the elements of the lower triangular part to ﬁll the upper triangular part.

Kwargs: ﬁlltriu : int

1 (default) return a hermitian matrix

2 return an anti-hermitian matrix

Examples:

>>> unpack_row(numpy.arange(9.).reshape(3,3), 1)

[[ 0. 3. 6.]

[ 3. 4. 7.]

[ 6. 7. 8.]]

>>> unpack_row(numpy.arange(9.).reshape(3,3), 2)

[[ 0. -3. -6.]

[ 3. 4. -7.]

[ 6. 7. 8.]]

pyscf.lib.numpy_helper.norm(x,ord=None,axis=None)

numpy.linalg.norm for numpy 1.6.*

pyscf.lib.numpy_helper.pack_tril(mat,axis=-1,out=None)

ﬂatten the lower triangular part of a matrix. Given mat, it returns mat[...,numpy.tril_indices(mat.shape[0])]

Examples:

78 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

>>> pack_tril(numpy.arange(9).reshape(3,3))

[034678]

pyscf.lib.numpy_helper.solve_lineq_by_SVD(a,b)

a*x=b

pyscf.lib.numpy_helper.take_2d(a,idx,idy,out=None)

a(idx,idy)

Examples:

>>> out =numpy.arange(9.).reshape(3,3)

>>> take_2d(a, [0,2], [0,2])

[[ 0. 2.]

[ 6. 8.]]

pyscf.lib.numpy_helper.takebak_2d(out,a,idx,idy)

Reverse operation of take_2d. out(idx,idy) += a

Examples:

>>> out =numpy.zeros((3,3))

>>> takebak_2d(out, numpy.ones((2,2)), [0,2], [0,2])

[[ 1. 0. 1.]

[ 0. 0. 0.]

[ 1. 0. 1.]]

pyscf.lib.numpy_helper.transpose(a,axes=None,inplace=False,out=None)

Transpose array for better memory efﬁciency

Examples:

>>> transpose(numpy.ones((3,2)))

[[ 1. 1. 1.]

[ 1. 1. 1.]]

pyscf.lib.numpy_helper.transpose_sum(a,inplace=False,out=None)

a + a.T for better memory efﬁciency

Examples:

>>> transpose_sum(numpy.arange(4.).reshape(2,2))

[[ 0. 3.]

[ 3. 6.]]

pyscf.lib.numpy_helper.unpack_row(tril,row_id)

Extract one row of the lower triangular part of a matrix. It is equivalent to unpack_tril(a)[row_id]

Examples:

>>> unpack_row(numpy.arange(6.), 0)

[ 0. 1. 3.]

>>> unpack_tril(numpy.arange(6.))[0]

[ 0. 1. 3.]

pyscf.lib.numpy_helper.unpack_tril(tril,ﬁlltriu=1,axis=-1,out=None)

Reverse operation of pack_tril.

Kwargs: ﬁlltriu : int

1.5. lib — Helper functions, parameters, and C extensions 79

PySCF Documentation, Release 1.4.0

0 Do not ﬁll the upper triangular part, random number may appear in the upper triangular part

1 (default) Transpose the lower triangular part to ﬁll the upper triangular part

2 Similar to ﬁlltriu=1, negative of the lower triangular part is assign to the upper triangular

part to make the matrix anti-hermitian

Examples:

>>> unpack_tril(numpy.arange(6.))

[[ 0. 1. 3.]

[ 1. 2. 4.]

[ 3. 4. 5.]]

>>> unpack_tril(numpy.arange(6.), 0)

[[ 0. 0. 0.]

[ 1. 2. 0.]

[ 3. 4. 5.]]

>>> unpack_tril(numpy.arange(6.), 2)

[[ 0. -1. -3.]

[ 1. 2. -4.]

[ 3. 4. 5.]]

pyscf.lib.numpy_helper.zdot(a,b,alpha=1,c=None,beta=0)

Matrix-matrix multiplication for double complex arrays using Gauss’s complex multiplication algorithm

Extension to scipy.linalg module

pyscf.lib.linalg_helper.cho_solve(a,b)

Solve ax = b, where a is hermitian matrix

pyscf.lib.linalg_helper.davidson(aop,x0,precond,tol=1e-12,max_cycle=50,max_space=12,

lindep=1e-14,max_memory=2000,dot=<built-in function

dot>,callback=None,nroots=1,lessio=False,verbose=2,

follow_state=False)

Davidson diagonalization method to solve a c = e c. Ref [1] E.R. Davidson, J. Comput. Phys. 17 (1), 87-94

(1975). [2] http://people.inf.ethz.ch/arbenz/ewp/Lnotes/chapter11.pdf

Args:

aop [function(x) => array_like_x] aop(x) to mimic the matrix vector multiplication 𝑗𝑎𝑖𝑗 *𝑥𝑗. The

argument is a 1D array. The returned value is a 1D array.

x0 [1D array or a list of 1D array] Initial guess. The initial guess vector(s) are just used as the initial

subspace bases. If the subspace is smaller than “nroots”, eg 10 roots and one initial guess, all eigen-

vectors are chosen as the eigenvectors during the iterations. The ﬁrst iteration has one eigenvector,

the next iteration has two, the third iterastion has 4, ..., until the subspace size > nroots.

precond [function(dx, e, x0) => array_like_dx] Preconditioner to generate new trial vector. The argument

dx is a residual vector a*x0-e*x0; e is the current eigenvalue; x0 is the current eigenvector.

Kwargs:

tol [ﬂoat] Convergence tolerance.

max_cycle [int] max number of iterations.

max_space [int] space size to hold trial vectors.

lindep [ﬂoat] Linear dependency threshold. The function is terminated when the smallest eigenvalue of

the metric of the trial vectors is lower than this threshold.

max_memory [int or ﬂoat] Allowed memory in MB.

dot [function(x, y) => scalar] Inner product

80 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

callback [function(envs_dict) => None] callback function takes one dict as the argument which is gener-

ated by the builtin function locals(), so that the callback function can access all local variables

in the current envrionment.

nroots [int] Number of eigenvalues to be computed. When nroots > 1, it affects the shape of the return

value

lessio [bool] How to compute a*x0 for current eigenvector x0. There are two ways to compute a*x0. One

is to assemble the existed a*x. The other is to call aop(x0). The default is the ﬁrst method which

needs more IO and less computational cost. When IO is slow, the second method can be considered.

follow_state [bool] If the solution dramatically changes in two iterations, clean the subspace and restart

the iteration with the old solution. It can help to improve numerical stability. Default is False.

Returns:

e[ﬂoat or list of ﬂoats] Eigenvalue. By default it’s one ﬂoat number. If nroots > 1, it is a list of ﬂoats

for the lowest nroots eigenvalues.

c[1D array or list of 1D arrays] Eigenvector. By default it’s a 1D array. If nroots > 1, it is a list of

arrays for the lowest nroots eigenvectors.

Examples:

>>> from pyscf import lib

>>> a=numpy.random.random((10,10))

>>> a=a+a.T

>>> aop =lambda x: numpy.dot(a,x)

>>> precond =lambda dx, e, x0: dx/(a.diagonal()-e)

>>> x0 =a[0]

>>> e,c=lib.davidson(aop, x0, precond)

pyscf.lib.linalg_helper.davidson1(aop,x0,precond,tol=1e-12,max_cycle=50,

max_space=12,lindep=1e-14,max_memory=2000,

dot=<built-in function dot>,callback=None,nroots=1,

lessio=False,verbose=2,follow_state=False)

Davidson diagonalization method to solve a c = e c. Ref [1] E.R. Davidson, J. Comput. Phys. 17 (1), 87-94

(1975). [2] http://people.inf.ethz.ch/arbenz/ewp/Lnotes/chapter11.pdf

Args:

aop [function([x]) => [array_like_x]] Matrix vector multiplication 𝑦𝑘𝑖 =𝑗𝑎𝑖𝑗 *𝑥𝑗𝑘.

x0 [1D array or a list of 1D array] Initial guess. The initial guess vector(s) are just used as the initial

subspace bases. If the subspace is smaller than “nroots”, eg 10 roots and one initial guess, all eigen-

vectors are chosen as the eigenvectors during the iterations. The ﬁrst iteration has one eigenvector,

the next iteration has two, the third iterastion has 4, ..., until the subspace size > nroots.

precond [function(dx, e, x0) => array_like_dx] Preconditioner to generate new trial vector. The argument

dx is a residual vector a*x0-e*x0; e is the current eigenvalue; x0 is the current eigenvector.

Kwargs:

tol [ﬂoat] Convergence tolerance.

max_cycle [int] max number of iterations.

max_space [int] space size to hold trial vectors.

lindep [ﬂoat] Linear dependency threshold. The function is terminated when the smallest eigenvalue of

the metric of the trial vectors is lower than this threshold.

max_memory [int or ﬂoat] Allowed memory in MB.

1.5. lib — Helper functions, parameters, and C extensions 81

PySCF Documentation, Release 1.4.0

dot [function(x, y) => scalar] Inner product

callback [function(envs_dict) => None] callback function takes one dict as the argument which is gener-

ated by the builtin function locals(), so that the callback function can access all local variables

in the current envrionment.

nroots [int] Number of eigenvalues to be computed. When nroots > 1, it affects the shape of the return

value

lessio [bool] How to compute a*x0 for current eigenvector x0. There are two ways to compute a*x0. One

is to assemble the existed a*x. The other is to call aop(x0). The default is the ﬁrst method which

needs more IO and less computational cost. When IO is slow, the second method can be considered.

follow_state [bool] If the solution dramatically changes in two iterations, clean the subspace and restart

the iteration with the old solution. It can help to improve numerical stability. Default is False.

Returns:

conv [bool] Converged or not

e[list of ﬂoats] The lowest nroots eigenvalues.

c[list of 1D arrays] The lowest nroots eigenvectors.

Examples:

>>> from pyscf import lib

>>> a=numpy.random.random((10,10))

>>> a=a+a.T

>>> aop =lambda xs: [numpy.dot(a,x) for xin xs]

>>> precond =lambda dx, e, x0: dx/(a.diagonal()-e)

>>> x0 =a[0]

>>> e,c=lib.davidson(aop, x0, precond, nroots=2)

>>> len(e)

pyscf.lib.linalg_helper.davidson_nosym(aop,x0,precond,tol=1e-12,max_cycle=50,

max_space=12,lindep=1e-14,max_memory=2000,

dot=<built-in function dot>,callback=None,

nroots=1,lessio=False,left=False,pick=<function

pick_real_eigs>,verbose=2,follow_state=False)

Davidson diagonalization to solve the non-symmetric eigenvalue problem

Args:

aop [function([x]) => [array_like_x]] Matrix vector multiplication 𝑦𝑘𝑖 =𝑗𝑎𝑖𝑗 *𝑥𝑗𝑘.

x0 [1D array or a list of 1D array] Initial guess. The initial guess vector(s) are just used as the initial

subspace bases. If the subspace is smaller than “nroots”, eg 10 roots and one initial guess, all eigen-

vectors are chosen as the eigenvectors during the iterations. The ﬁrst iteration has one eigenvector,

the next iteration has two, the third iterastion has 4, ..., until the subspace size > nroots.

precond [function(dx, e, x0) => array_like_dx] Preconditioner to generate new trial vector. The argument

dx is a residual vector a*x0-e*x0; e is the current eigenvalue; x0 is the current eigenvector.

Kwargs:

tol [ﬂoat] Convergence tolerance.

max_cycle [int] max number of iterations.

max_space [int] space size to hold trial vectors.

82 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

lindep [ﬂoat] Linear dependency threshold. The function is terminated when the smallest eigenvalue of

the metric of the trial vectors is lower than this threshold.

max_memory [int or ﬂoat] Allowed memory in MB.

dot [function(x, y) => scalar] Inner product

callback [function(envs_dict) => None] callback function takes one dict as the argument which is gener-

ated by the builtin function locals(), so that the callback function can access all local variables

in the current envrionment.

nroots [int] Number of eigenvalues to be computed. When nroots > 1, it affects the shape of the return

value

lessio [bool] How to compute a*x0 for current eigenvector x0. There are two ways to compute a*x0. One

is to assemble the existed a*x. The other is to call aop(x0). The default is the ﬁrst method which

needs more IO and less computational cost. When IO is slow, the second method can be considered.

left [bool] Whether to calculate and return left eigenvectors. Default is False.

pick [function(w,v,nroots) => (e[idx], w[:,idx], idx)] Function to ﬁlter eigenvalues and eigenvectors.

follow_state [bool] If the solution dramatically changes in two iterations, clean the subspace and restart

the iteration with the old solution. It can help to improve numerical stability. Default is False.

Returns:

conv [bool] Converged or not

e[list of eigenvalues] The eigenvalues can be sorted real or complex, depending on the return value of

pick function.

vl [list of 1D arrays] Left eigenvectors. Only returned if left=True.

c[list of 1D arrays] Right eigenvectors.

Examples:

>>> from pyscf import lib

>>> a=numpy.random.random((10,10))

>>> a=a

>>> aop =lambda xs: [numpy.dot(a,x) for xin xs]

>>> precond =lambda dx, e, x0: dx/(a.diagonal()-e)

>>> x0 =a[0]

>>> e, vl, vr =lib.davidson(aop, x0, precond, nroots=2, left=True)

>>> len(e)

pyscf.lib.linalg_helper.dgeev(abop,x0,precond,type=1,tol=1e-12,max_cycle=50,

max_space=12,lindep=1e-14,max_memory=2000,dot=<built-

in function dot>,callback=None,nroots=1,lessio=False,

verbose=2)

Davidson diagonalization method to solve A c = e B c.

Args:

abop [function(x) => (array_like_x, array_like_x)] abop applies two matrix vector multiplications and

returns tuple (Ax, Bx)

x0 [1D array] Initial guess

precond [function(dx, e, x0) => array_like_dx] Preconditioner to generate new trial vector. The argument

dx is a residual vector a*x0-e*x0; e is the current eigenvalue; x0 is the current eigenvector.

Kwargs:

1.5. lib — Helper functions, parameters, and C extensions 83

PySCF Documentation, Release 1.4.0

tol [ﬂoat] Convergence tolerance.

max_cycle [int] max number of iterations.

max_space [int] space size to hold trial vectors.

lindep [ﬂoat] Linear dependency threshold. The function is terminated when the smallest eigenvalue of

the metric of the trial vectors is lower than this threshold.

max_memory [int or ﬂoat] Allowed memory in MB.

dot [function(x, y) => scalar] Inner product

callback [function(envs_dict) => None] callback function takes one dict as the argument which is gener-

ated by the builtin function locals(), so that the callback function can access all local variables

in the current envrionment.

nroots [int] Number of eigenvalues to be computed. When nroots > 1, it affects the shape of the return

value

lessio [bool] How to compute a*x0 for current eigenvector x0. There are two ways to compute a*x0. One

is to assemble the existed a*x. The other is to call aop(x0). The default is the ﬁrst method which

needs more IO and less computational cost. When IO is slow, the second method can be considered.

Returns:

e[list of ﬂoats] The lowest nroots eigenvalues.

c[list of 1D arrays] The lowest nroots eigenvectors.

pyscf.lib.linalg_helper.dgeev1(abop,x0,precond,type=1,tol=1e-12,max_cycle=50,

max_space=12,lindep=1e-14,max_memory=2000,dot=<built-

in function dot>,callback=None,nroots=1,lessio=False,

verbose=2)

Davidson diagonalization method to solve A c = e B c.

Args:

abop [function([x]) => ([array_like_x], [array_like_x])] abop applies two matrix vector multiplications

and returns tuple (Ax, Bx)

x0 [1D array] Initial guess

precond [function(dx, e, x0) => array_like_dx] Preconditioner to generate new trial vector. The argument

dx is a residual vector a*x0-e*x0; e is the current eigenvalue; x0 is the current eigenvector.

Kwargs:

tol [ﬂoat] Convergence tolerance.

max_cycle [int] max number of iterations.

max_space [int] space size to hold trial vectors.

lindep [ﬂoat] Linear dependency threshold. The function is terminated when the smallest eigenvalue of

the metric of the trial vectors is lower than this threshold.

max_memory [int or ﬂoat] Allowed memory in MB.

dot [function(x, y) => scalar] Inner product

callback [function(envs_dict) => None] callback function takes one dict as the argument which is gener-

ated by the builtin function locals(), so that the callback function can access all local variables

in the current envrionment.

nroots [int] Number of eigenvalues to be computed. When nroots > 1, it affects the shape of the return

value

84 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

lessio [bool] How to compute a*x0 for current eigenvector x0. There are two ways to compute a*x0. One

is to assemble the existed a*x. The other is to call aop(x0). The default is the ﬁrst method which

needs more IO and less computational cost. When IO is slow, the second method can be considered.

Returns:

conv [bool] Converged or not

e[list of ﬂoats] The lowest nroots eigenvalues.

c[list of 1D arrays] The lowest nroots eigenvectors.

pyscf.lib.linalg_helper.dsolve(aop,b,precond,tol=1e-12,max_cycle=30,dot=<built-in func-

tion dot>,lindep=1e-16,verbose=0)

Davidson iteration to solve linear equation. It works bad.

pyscf.lib.linalg_helper.eig(aop,x0,precond,tol=1e-12,max_cycle=50,max_space=12,

lindep=1e-14,max_memory=2000,dot=<built-in function dot>,

callback=None,nroots=1,lessio=False,left=False,pick=<function

pick_real_eigs>,verbose=2,follow_state=False)

Davidson diagonalization to solve the non-symmetric eigenvalue problem

Args:

aop [function([x]) => [array_like_x]] Matrix vector multiplication 𝑦𝑘𝑖 =𝑗𝑎𝑖𝑗 *𝑥𝑗𝑘.

x0 [1D array or a list of 1D array] Initial guess. The initial guess vector(s) are just used as the initial

subspace bases. If the subspace is smaller than “nroots”, eg 10 roots and one initial guess, all eigen-

vectors are chosen as the eigenvectors during the iterations. The ﬁrst iteration has one eigenvector,

the next iteration has two, the third iterastion has 4, ..., until the subspace size > nroots.

precond [function(dx, e, x0) => array_like_dx] Preconditioner to generate new trial vector. The argument

dx is a residual vector a*x0-e*x0; e is the current eigenvalue; x0 is the current eigenvector.

Kwargs:

tol [ﬂoat] Convergence tolerance.

max_cycle [int] max number of iterations.

max_space [int] space size to hold trial vectors.

lindep [ﬂoat] Linear dependency threshold. The function is terminated when the smallest eigenvalue of

the metric of the trial vectors is lower than this threshold.

max_memory [int or ﬂoat] Allowed memory in MB.

dot [function(x, y) => scalar] Inner product

callback [function(envs_dict) => None] callback function takes one dict as the argument which is gener-

ated by the builtin function locals(), so that the callback function can access all local variables

in the current envrionment.

nroots [int] Number of eigenvalues to be computed. When nroots > 1, it affects the shape of the return

value

lessio [bool] How to compute a*x0 for current eigenvector x0. There are two ways to compute a*x0. One

is to assemble the existed a*x. The other is to call aop(x0). The default is the ﬁrst method which

needs more IO and less computational cost. When IO is slow, the second method can be considered.

left [bool] Whether to calculate and return left eigenvectors. Default is False.

pick [function(w,v,nroots) => (e[idx], w[:,idx], idx)] Function to ﬁlter eigenvalues and eigenvectors.

follow_state [bool] If the solution dramatically changes in two iterations, clean the subspace and restart

the iteration with the old solution. It can help to improve numerical stability. Default is False.

1.5. lib — Helper functions, parameters, and C extensions 85

PySCF Documentation, Release 1.4.0

Returns:

conv [bool] Converged or not

e[list of eigenvalues] The eigenvalues can be sorted real or complex, depending on the return value of

pick function.

vl [list of 1D arrays] Left eigenvectors. Only returned if left=True.

c[list of 1D arrays] Right eigenvectors.

Examples:

>>> from pyscf import lib

>>> a=numpy.random.random((10,10))

>>> a=a

>>> aop =lambda xs: [numpy.dot(a,x) for xin xs]

>>> precond =lambda dx, e, x0: dx/(a.diagonal()-e)

>>> x0 =a[0]

>>> e, vl, vr =lib.davidson(aop, x0, precond, nroots=2, left=True)

>>> len(e)

pyscf.lib.linalg_helper.eigh_by_blocks(h,s=None,labels=None)

Solve an ordinary or generalized eigenvalue problem for diagonal blocks. The diagonal blocks are extracted

based on the given basis “labels”. The rows and columns which have the same labels are put in the same

block. One common scenario one needs the block-wise diagonalization is to diagonalize the matrix in symmetry

adapted basis, in which “labels” is the irreps of each basis.

Args:

h, s [2D array] Complex Hermitian or real symmetric matrix.

Kwargs: labels : list

Returns: w, v. w is the eigenvalue vector; v is the eigenfunction array; seig is the eigenvalue vector of the

metric s.

Examples:

>>> from pyscf import lib

>>> a=numpy.ones((4,4))

>>> a[0::3,0::3]=0

>>> a[1::3,1::3]=2

>>> a[2::3,2::3]=4

>>> labels =['a','b','c','a']

>>> lib.eigh_by_blocks(a, labels)

(array([ 0., 0., 2., 4.]),

array([[ 1., 0., 0., 0.],

[ 0., 0., 1., 0.],

[ 0., 0., 0., 1.],

[ 0., 1., 0., 0.]]))

>>> numpy.linalg.eigh(a)

(array([ -8.82020545e-01, -1.81556477e-16, 1.77653793e+00, 5.10548262e+00]),

array([[ 6.40734630e-01, -7.07106781e-01, 1.68598330e-01, -2.47050070e-01],

[ -3.80616542e-01, 9.40505244e-17, 8.19944479e-01, -4.27577008e-01],

[ -1.84524565e-01, 9.40505244e-17, -5.20423152e-01, -8.33732828e-01],

[ 6.40734630e-01, 7.07106781e-01, 1.68598330e-01, -2.47050070e-

˓→01]]))

86 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

>>> from pyscf import gto, lib, symm

>>> mol =gto.M(atom='H000;H001', basis='ccpvdz', symmetry=True)

>>> c=numpy.hstack(mol.symm_orb)

>>> vnuc_so =reduce(numpy.dot, (c.T, mol.intor('int1e_nuc_sph'), c))

>>> orbsym =symm.label_orb_symm(mol, mol.irrep_name, mol.symm_orb, c)

>>> lib.eigh_by_blocks(vnuc_so, labels=orbsym)

(array([-4.50766885, -1.80666351, -1.7808565 , -1.7808565 , -1.74189134,

-0.98998583, -0.98998583, -0.40322226, -0.30242374, -0.07608981]),

...)

pyscf.lib.linalg_helper.krylov(aop,b,x0=None,tol=1e-10,max_cycle=30,dot=<built-in func-

tion dot>,lindep=1e-15,callback=None,hermi=False,ver-

bose=2)

Krylov subspace method to solve (1+a) x = b. Ref: J. A. Pople et al, Int. J. Quantum. Chem. Symp. 13, 225

(1979).

Args:

aop [function(x) => array_like_x] aop(x) to mimic the matrix vector multiplication 𝑗𝑎𝑖𝑗 𝑥𝑗. The argu-

ment is a 1D array. The returned value is a 1D array.

Kwargs:

x0 [1D array] Initial guess

tol [ﬂoat] Tolerance to terminate the operation aop(x).

max_cycle [int] max number of iterations.

lindep [ﬂoat] Linear dependency threshold. The function is terminated when the smallest eigenvalue of

the metric of the trial vectors is lower than this threshold.

dot [function(x, y) => scalar] Inner product

callback [function(envs_dict) => None] callback function takes one dict as the argument which is gener-

ated by the builtin function locals(), so that the callback function can access all local variables

in the current envrionment.

Returns: x : 1D array like b

Examples:

>>> from pyscf import lib

>>> a=numpy.random.random((10,10)) *1e-2

>>> b=numpy.random.random(10)

>>> aop =lambda x: numpy.dot(a,x)

>>> x=lib.krylov(aop, b)

>>> numpy.allclose(numpy.dot(a,x)+x, b)

True

pyscf.lib.linalg_helper.safe_eigh(h,s,lindep=1e-15)

Solve generalized eigenvalue problem h v = w s v.

Note: The number of eigenvalues and eigenvectors might be less than the matrix dimension if linear dependency

is found in metric s.

Args:

h, s [2D array] Complex Hermitian or real symmetric matrix.

1.5. lib — Helper functions, parameters, and C extensions 87

PySCF Documentation, Release 1.4.0

Kwargs:

lindep [ﬂoat] Linear dependency threshold. By diagonalizing the metric s, we consider the eigenvectors

are linearly dependent subsets if their eigenvalues are smaller than this threshold.

Returns: w, v, seig. w is the eigenvalue vector; v is the eigenfunction array; seig is the eigenvalue vector of the

metric s.

1.5.4 chkﬁle

pyscf.lib.chkfile.dump(chkﬁle,key,value)

Save array(s) in chkﬁle

Args:

chkﬁle [str] Name of chkﬁle.

key : str

value [array, vector ... or dict] If value is a python dict, the key/value of the dict will be saved recursively

as the HDF5 group/dataset

Returns: No return value

Examples:

>>> import h5py

>>> from pyscf import lib

>>> ci ={'Ci' : {'op': ('E','i'), 'irrep': ('Ag','Au')}}

>>> lib.chkfile.save('symm.chk','symm', ci)

>>> f=h5py.File('symm.chk')

>>> f.keys()

['symm']

>>> f['symm'].keys()

['Ci']

>>> f['symm/Ci'].keys()

['op', 'irrep']

>>> f['symm/Ci/op']

pyscf.lib.chkfile.dump_mol(mol,chkﬁle)

Save Mole object in chkﬁle

Args: mol : an instance of Mole.

chkﬁle [str] Name of chkﬁle.

Returns: No return value

pyscf.lib.chkfile.load(chkﬁle,key)

Load array(s) from chkﬁle

Args:

chkﬁle [str] Name of chkﬁle. The chkﬁle needs to be saved in HDF5 format.

key [str] HDF5.dataset name or group name. If key is the HDF5 group name, the group will be loaded

into an Python dict, recursively

Returns: whatever read from chkﬁle

Examples:

88 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

>>> from pyscf import gto, scf, lib

>>> mol =gto.M(atom='He 0 0 0')

>>> mf =scf.RHF(mol)

>>> mf.chkfile ='He.chk'

>>> mf.kernel()

>>> mo_coeff =lib.chkfile.load('He.chk','scf/mo_coeff')

>>> mo_coeff.shape

(1, 1)

>>> scfdat =lib.chkfile.load('He.chk','scf')

>>> scfdat.keys()

['e_tot', 'mo_occ', 'mo_energy', 'mo_coeff']

pyscf.lib.chkfile.load_mol(chkﬁle)

Load Mole object from chkﬁle. The save_mol/load_mol operation can be used a serialization method for Mole

object.

Args:

chkﬁle [str] Name of chkﬁle.

Returns: A (initialized/built) Mole object

Examples:

>>> from pyscf import gto, lib

>>> mol =gto.M(atom='He 0 0 0')

>>> lib.chkfile.save_mol(mol, 'He.chk')

>>> lib.chkfile.load_mol('He.chk')

<pyscf.gto.mole.Mole object at 0x7fdcd94d7f50>

pyscf.lib.chkfile.save_mol(mol,chkﬁle)

Save Mole object in chkﬁle

Args: mol : an instance of Mole.

chkﬁle [str] Name of chkﬁle.

Returns: No return value

Fast load

The results of SCF and MCSCF methods are saved as a Python dictionary in the chkﬁle. One can fast load the results

and update the SCF and MCSCF objects using the python built in methods .__dict__.update, eg:

from pyscf import gto, scf, mcscf, lib

mol =gto.M(atom='N000;N111', basis='ccpvdz')

mf =mol.apply(scf.RHF).set(chkfile='n2.chk).run()

mc =mcscf.CASSCF(mf, 6,6).set(chkfile='n2.chk').run()

# load SCF results

mf =scf.RHF(mol)

mf.__dict__.update(lib.chkfile.load('n2.chk','scf'))

# load MCSCF results

mc =mcscf.CASCI(mf, 6,6)

mc.__dict__.update(lib.chkfile.load('n2.chk','mcscf'))

mc.kernel()

1.5. lib — Helper functions, parameters, and C extensions 89

PySCF Documentation, Release 1.4.0

1.6 scf — Mean-ﬁeld methods

1.6.1 Stability analysis

1.6.2 Addons

Special treatments may be required to the SCF methods in some situations. These special treatments cannot be uni-

versally applied for all SCF models. They were deﬁned in the scf.addons module. For example, in an UHF

calculation, we may want the 𝑆𝑧value to be changed (the numbers of alpha and beta electrons not conserved) during

SCF iteration while conserving the total number of electrons. scf.addons.dynamic_sz_() can provide this

functionality:

from pyscf import gto, scf

mol =gto.M(atom='O000;O001')

mf =scf.UHF(mol)

mf.verbose=4

mf =scf.addons.dynamic_sz_(mf)

mf.kernel()

print('S^2 = %s, 2S+1 = %s'%mf.spin_square())

This function automatically converges the ground sate of oxygen molecule to triplet state although we didn’t specify

spin state in the mol object.

Note: Function scf.addons.dynamic_sz_() has side effects. It changes the underlying mean-ﬁeld object.

The addons mechanism increases the ﬂexibility of PySCf program. You can deﬁne various addons to customize the

default behaviour of pyscf program. For example, if you’d like to track the changes of the density (the diagonal term

of density matrix) of certain basis during the SCF iteration, you can write the following addon to output the required

density:

def output_density(mf, basis_label):

ao_labels =mf.mol.ao_labels()

old_make_rdm1 =mf.make_rdm1

def make_rdm1(mo_coeff, mo_occ):

dm =old_make_rdm1(mo_coeff, mo_occ)

print('AO alpha beta')

for i,s in enumerate(ao_labels):

if basis_label in s:

print(s, dm[0][i,i], dm[1][i,i])

return dm

mf.make_rdm1 =make_rdm1

return mf

from pyscf import gto, scf

mol =gto.M(atom='O000;O001')

mf =scf.UHF(mol)

mf.verbose=4

mf =scf.addons.dynamic_sz_(mf)

mf =output_density(mf, 'O 2p')

mf.kernel()

90 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

1.6.3 Caching two-electron integrals

When memory is enough (speciﬁed by the max_memory of SCF object), the SCF object generates all

two-electron integrals in memory and cache them in _eri array. The default max_memory (deﬁned in

lib.parameters.MAX_MEMORY, see Maximum memory) is 4 GB. It roughly corresponds to two-electron real

integrals for 250 orbitals. For small systems, the cached integrals usually provide the best performance. If you have

enough main memory in your computer, you can increase the max_memory of SCF object to cache the integrals in

memory.

The cached integrals _eri are treated as a dense tensor. When system becomes larger and the two-electron integral

tensor becomes sparse, caching integrals may lose performance advantage. This is mainly due to the fact that the

implementation of J/K build for the cached integrals did not utilize the sparsity of the integral tensor. Also, the data

locality was not considered in the implementation which sometimes leads to bad OpenMP multi-threading speed up.

For large system, the AO-driven direct SCF method is more favorable.

1.6.4 Customizing Hamiltonian

This integral object _eri is not merely used by the mean-ﬁeld calculation. Along with the get_hcore() method,

this two-electron integral object will be treated as the Hamiltonian in the post-SCF code whenever possible. This

mechanism provides a way to model arbitrary fermion system in PySCF. You can customize a system by changing the

1-electron Hamiltonian and the mean-ﬁeld _eri attribute. For example, the following code solves a model system:

import numpy

from pyscf import gto, scf, ao2mo, ccsd

mol =gto.M()

n=10

mol.nelectron =10

mf =scf.RHF(mol)

t=numpy.zeros((n,n))

for iin range(n-1):

t[i,i+1]=t[i+1,i] = -1.0

t[n-1,0]=t[0,n-1]=1.0 # anti-PBC

eri =numpy.zeros((n,n,n,n))

for iin range(n):

eri[i,i,i,i] =4.0

mf.get_hcore =lambda *args: t

mf.get_ovlp =lambda *args: numpy.eye(n)

# ao2mo.restore(8, eri, n) to get 8-fold symmetry of the integrals

# ._eri only supports the 2-electron integrals in 4-fold or 8-fold symmetry.

mf._eri =ao2mo.restore(8, eri, n)

mf.kernel()

mycc =ccsd.RCCSD(mf).run()

e,v =mycc.ipccsd(nroots=3)

print('IP = ', e)

e,v =mycc.eaccsd(nroots=3)

print('EA = ', e)

Some post-SCF methods require the 4-index MO integrals. Depending the available memory (affected by the value

of max_memory in each class), these methods may not use the “AO integrals” cached in _eri. To ensure the post

mean-ﬁeld methods to use the _eri integrals no matter whether the actual memory usage is over the max_memory

limite, you can set the ﬂag incore_anyway in Mole class to True before calling the kernel() function of the

1.6. scf — Mean-ﬁeld methods 91

PySCF Documentation, Release 1.4.0

post-SCF methods. In the following example, without setting incore_anyway=True, the CCSD calculations will

crash:

import numpy

from pyscf import gto, scf, ao2mo, ccsd

mol =gto.M()

n=10

mol.nelectron =n

mol.max_memory =0

mf =scf.RHF(mol)

t=numpy.zeros((n,n))

for iin range(n-1):

t[i,i+1]=t[i+1,i] =1.0

t[n-1,0]=t[0,n-1]= -1.0

eri =numpy.zeros((n,n,n,n))

for iin range(n):

eri[i,i,i,i] =4.0

mf.get_hcore =lambda *args: t

mf.get_ovlp =lambda *args: numpy.eye(n)

mf._eri =ao2mo.restore(8, eri, n)

mf.kernel()

mol.incore_anyway =True

mycc =ccsd.RCCSD(mf).run()

e,v =mycc.ipccsd(nroots=3)

print('IP = ', e)

e,v =mycc.eaccsd(nroots=3)

print('EA = ', e)

Holding the entire two-particle interactions matrix elements in memory often leads to high memory usage. In the

SCF calculation, the memory usage can be optimized if _eri is sparse. The SCF iterations requires only the Fock

matrix which in turn calls the J/K build function SCF.get_jk() to compute the Coulomb and HF-exchange matrix.

Overwriting the SCF.get_jk() function can reduce the memory footprint of the SCF part in the above example:

import numpy

from pyscf import gto, scf, ao2mo, ccsd

mol =gto.M()

n=10

mol.nelectron =n

mol.max_memory =0

mf =scf.RHF(mol)

t=numpy.zeros((n,n))

for iin range(n-1):

t[i,i+1]=t[i+1,i] =1.0

t[n-1,0]=t[0,n-1]= -1.0

mf.get_hcore =lambda *args: t

mf.get_ovlp =lambda *args: numpy.eye(n)

def get_jk(mol, dm, *args):

j=numpy.diag(dm.diagonal()) *4.

k=numpy.diag(dm.diagonal()) *4.

return j, k

mf.get_jk =get_jk

mf.kernel()

92 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

Another way to handle the two-particle interactions of large model system is to use the density ﬁtting/Cholesky de-

composed integrals. See also Saving/Loading DF integral tensor.

1.6.5 Program reference

Non-relativistic and relativistic Hartree-Fock

Simple usage:

>>> from pyscf import gto, scf

>>> mol =gto.M(atom='H000;H001')

>>> mf =scf.RHF(mol).run()

scf.RHF() returns an instance of SCF class. There are some parameters to control the SCF method.

verbose [int] Print level. Default value equals to Mole.verbose

max_memory [ﬂoat or int] Allowed memory in MB. Default value equals to Mole.max_memory

chkﬁle [str] checkpoint ﬁle to save MOs, orbital energies etc.

conv_tol [ﬂoat] converge threshold. Default is 1e-10

max_cycle [int] max number of iterations. Default is 50

init_guess [str] initial guess method. It can be one of ‘minao’, ‘atom’, ‘1e’, ‘chkﬁle’. Default is ‘minao’

DIIS [class listed in scf.diis] Default is diis.SCF_DIIS. Set it to None/False to turn off DIIS.

diis [bool] whether to do DIIS. Default is True.

diis_space [int] DIIS space size. By default, 8 Fock matrices and errors vector are stored.

diis_start_cycle [int] The step to start DIIS. Default is 0.

level_shift_factor [ﬂoat or int] Level shift (in AU) for virtual space. Default is 0.

direct_scf [bool] Direct SCF is used by default.

direct_scf_tol [ﬂoat] Direct SCF cutoff threshold. Default is 1e-13.

callback [function] callback function takes one dict as the argument which is generated by the builtin

function locals(), so that the callback function can access all local variables in the current

envrionment.

conv_check [bool] An extra cycle to check convergence after SCF iterations.

nelec [(int,int), for UHF/ROHF class] freeze the number of (alpha,beta) electrons.

irrep_nelec [dict, for symmetry- RHF/ROHF/UHF class only] to indicate the number of electrons for

each irreps. In RHF, give {‘ir_name’:int, ...} ; In ROHF/UHF, give {‘ir_name’:(int,int), ...} . It is

effective when Mole.symmetry is set True.

auxbasis [str, for density ﬁtting SCF only] Auxiliary basis for density ﬁtting.

>>> mf =scf.density_fit(scf.UHF(mol))

>>> mf.scf()

Density ﬁtting can be applied to all non-relativistic HF class.

with_ssss [bool, for Dirac-Hartree-Fock only] If False, ignore small component integrals (SS|SS). De-

fault is True.

with_gaunt [bool, for Dirac-Hartree-Fock only] If False, ignore Gaunt interaction. Default is False.

1.6. scf — Mean-ﬁeld methods 93

PySCF Documentation, Release 1.4.0

Saved results

converged [bool] SCF converged or not

e_tot [ﬂoat] Total HF energy (electronic energy plus nuclear repulsion)

mo_energy [] Orbital energies

mo_occ Orbital occupancy

mo_coeff Orbital coefﬁcients

Non-relativistic Hartree-Fock

class pyscf.scf.hf.SCF(mol)

SCF base class. non-relativistic RHF.

Attributes:

verbose [int] Print level. Default value equals to Mole.verbose

max_memory [ﬂoat or int] Allowed memory in MB. Default equals to Mole.max_memory

chkﬁle [str] checkpoint ﬁle to save MOs, orbital energies etc.

conv_tol [ﬂoat] converge threshold. Default is 1e-10

conv_tol_grad [ﬂoat] gradients converge threshold. Default is sqrt(conv_tol)

max_cycle [int] max number of iterations. Default is 50

init_guess [str] initial guess method. It can be one of ‘minao’, ‘atom’, ‘1e’, ‘chkﬁle’. Default is ‘minao’

diis [boolean or object of DIIS class listed in scf.diis] Default is diis.SCF_DIIS. Set it to None

to turn off DIIS.

diis_space [int] DIIS space size. By default, 8 Fock matrices and errors vector are stored.

diis_start_cycle [int] The step to start DIIS. Default is 1.

diis_ﬁle: ‘str’ File to store DIIS vectors and error vectors.

level_shift [ﬂoat or int] Level shift (in AU) for virtual space. Default is 0.

direct_scf [bool] Direct SCF is used by default.

direct_scf_tol [ﬂoat] Direct SCF cutoff threshold. Default is 1e-13.

callback [function(envs_dict) => None] callback function takes one dict as the argument which is gener-

ated by the builtin function locals(), so that the callback function can access all local variables

in the current envrionment.

conv_check [bool] An extra cycle to check convergence after SCF iterations.

Saved results

converged [bool] SCF converged or not

e_tot [ﬂoat] Total HF energy (electronic energy plus nuclear repulsion)

mo_energy : Orbital energies

mo_occ Orbital occupancy

mo_coeff Orbital coefﬁcients

Examples:

94 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

>>> mol =gto.M(atom='H000;H001.1', basis='cc-pvdz')

>>> mf =scf.hf.SCF(mol)

>>> mf.verbose =0

>>> mf.level_shift = .4

>>> mf.scf()

-1.0811707843775884

analyze(verbose=None,**kwargs)

Analyze the given SCF object: print orbital energies, occupancies; print orbital coefﬁcients; Mulliken

population analysis; Diople moment.

as_scanner(mf )

Generating a scanner/solver for HF PES.

The returned solver is a function. This function requires one argument “mol” as input and returns total

HF energy.

The solver will automatically use the results of last calculation as the initial guess of the new calculation.

All parameters assigned in the SCF object (DIIS, conv_tol, max_memory etc) are automatically applied

in the solver.

Note scanner has side effects. It may change many underlying objects (_scf, with_df, with_x2c, ...) during

calculation.

Examples:

>>> from pyscf import gto, scf

>>> hf_scanner =scf.RHF(gto.Mole().set(verbose=0)).as_scanner()

>>> hf_scanner(gto.M(atom='H000;F001.1'))

-98.552190448277955

>>> hf_scanner(gto.M(atom='H000;F001.5'))

-98.414750424294368

canonicalize(mf,mo_coeff,mo_occ,fock=None)

Canonicalization diagonalizes the Fock matrix within occupied, open, virtual subspaces separatedly (with-

out change occupancy).

dip_moment(mol=None,dm=None,unit_symbol=None,verbose=3)

Dipole moment calculation

𝜇𝑥=−

𝜇

𝜈

𝑃𝜇𝜈 (𝜈|𝑥|𝜇) + 

𝐴

𝑄𝐴𝑋𝐴

𝜇𝑦=−

𝜇

𝜈

𝑃𝜇𝜈 (𝜈|𝑦|𝜇) + 

𝐴

𝑄𝐴𝑌𝐴

𝜇𝑧=−

𝜇

𝜈

𝑃𝜇𝜈 (𝜈|𝑧|𝜇) + 

𝐴

𝑄𝐴𝑍𝐴

where 𝜇𝑥, 𝜇𝑦, 𝜇𝑧are the x, y and z components of dipole moment

Args: mol: an instance of Mole dm : a 2D ndarrays density matrices

Return: A list: the dipole moment on x, y and z component

eig(h,s)

Solver for generalized eigenvalue problem

𝐻𝐶 =𝑆𝐶𝐸

1.6. scf — Mean-ﬁeld methods 95

PySCF Documentation, Release 1.4.0

energy_elec(mf,dm=None,h1e=None,vhf=None)

Electronic part of Hartree-Fock energy, for given core hamiltonian and HF potential

... math:

E=\sum_{ij}h_{ij} \gamma_{ji}

+\frac{1}{2}\sum_{ijkl} \gamma_{ji}\gamma_{lk} \langle ik||jl\rangle

Args: mf : an instance of SCF class

Kwargs:

dm [2D ndarray] one-partical density matrix

h1e [2D ndarray] Core hamiltonian

vhf [2D ndarray] HF potential

Returns: Hartree-Fock electronic energy and the Coulomb energy

Examples:

>>> from pyscf import gto, scf

>>> mol =gto.M(atom='H000;H001.1')

>>> mf =scf.RHF(mol)

>>> mf.scf()

>>> dm =mf.make_rdm1()

>>> scf.hf.energy_elec(mf, dm)

(-1.5176090667746334, 0.60917167853723675)

energy_tot(mf,dm=None,h1e=None,vhf=None)

Total Hartree-Fock energy, electronic part plus nuclear repulstion See scf.hf.energy_elec() for

the electron part

from_chk(chkﬁle=None,project=True)

Read the HF results from checkpoint ﬁle, then project it to the basis deﬁned by mol

Returns: Density matrix, 2D ndarray

get_fock(mf,h1e=None,s1e=None,vhf=None,dm=None,cycle=-1,diis=None,

diis_start_cycle=None,level_shift_factor=None,damp_factor=None)

F = h^{core} + V^{HF}

Special treatment (damping, DIIS, or level shift) will be applied to the Fock matrix if diis and cycle is

speciﬁed (The two parameters are passed to get_fock function during the SCF iteration)

Args:

h1e [2D ndarray] Core hamiltonian

s1e [2D ndarray] Overlap matrix, for DIIS

vhf [2D ndarray] HF potential matrix

dm [2D ndarray] Density matrix, for DIIS

Kwargs:

cycle [int] Then present SCF iteration step, for DIIS

diis [an object of SCF.DIIS class] DIIS object to hold intermediate Fock and error vectors

diis_start_cycle [int] The step to start DIIS. Default is 0.

level_shift_factor [ﬂoat or int] Level shift (in AU) for virtual space. Default is 0.

96 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

get_grad(mo_coeff,mo_occ,fock=None)

RHF Gradients

Args:

mo_coeff [2D ndarray] Obital coefﬁcients

mo_occ [1D ndarray] Orbital occupancy

fock_ao [2D ndarray] Fock matrix in AO representation

Returns: Gradients in MO representation. It’s a num_occ*num_vir vector.

get_j(mol=None,dm=None,hermi=1)

Compute J matrix for the given density matrix.

get_jk(mol=None,dm=None,hermi=1)

Compute J, K matrices for the given density matrix

Args: mol : an instance of Mole

dm [ndarray or list of ndarrays] A density matrix or a list of density matrices

Kwargs:

hermi [int] Whether J, K matrix is hermitian

0 : no hermitian or symmetric

1 : hermitian

2 : anti-hermitian

vhfopt : A class which holds precomputed quantities to optimize the computation of J, K matrices

Returns: Depending on the given dm, the function returns one J and one K matrix, or a list of J matrices

and a list of K matrices, corresponding to the input density matrices.

Examples:

>>> from pyscf import gto, scf

>>> from pyscf.scf import _vhf

>>> mol =gto.M(atom='H000;H001.1')

>>> dms =numpy.random.random((3,mol.nao_nr(),mol.nao_nr()))

>>> j,k=scf.hf.get_jk(mol, dms, hermi=0)

>>> print(j.shape)

(3, 2, 2)

get_k(mol=None,dm=None,hermi=1)

Compute K matrix for the given density matrix.

get_occ(mf,mo_energy=None,mo_coeff=None)

Label the occupancies for each orbital

Kwargs:

mo_energy [1D ndarray] Obital energies

mo_coeff [2D ndarray] Obital coefﬁcients

Examples:

1.6. scf — Mean-ﬁeld methods 97

PySCF Documentation, Release 1.4.0

>>> from pyscf import gto, scf

>>> mol =gto.M(atom='H000;F001.1')

>>> mf =scf.hf.SCF(mol)

>>> energy =numpy.array([-10.,-1.,1,-2.,0,-3])

>>> mf.get_occ(energy)

array([2, 2, 0, 2, 2, 2])

get_veff(mol=None,dm=None,dm_last=0,vhf_last=0,hermi=1)

Hartree-Fock potential matrix for the given density matrix

Args: mol : an instance of Mole

dm [ndarray or list of ndarrays] A density matrix or a list of density matrices

Kwargs:

dm_last [ndarray or a list of ndarrays or 0] The density matrix baseline. If not 0, this function

computes the increment of HF potential w.r.t. the reference HF potential matrix.

vhf_last [ndarray or a list of ndarrays or 0] The reference HF potential matrix.

hermi [int] Whether J, K matrix is hermitian

0 : no hermitian or symmetric

1 : hermitian

2 : anti-hermitian

vhfopt : A class which holds precomputed quantities to optimize the computation of J, K matrices

Returns: matrix Vhf = 2*J - K. Vhf can be a list matrices, corresponding to the input density matrices.

Examples:

>>> import numpy

>>> from pyscf import gto, scf

>>> from pyscf.scf import _vhf

>>> mol =gto.M(atom='H000;H001.1')

>>> dm0 =numpy.random.random((mol.nao_nr(),mol.nao_nr()))

>>> vhf0 =scf.hf.get_veff(mol, dm0, hermi=0)

>>> dm1 =numpy.random.random((mol.nao_nr(),mol.nao_nr()))

>>> vhf1 =scf.hf.get_veff(mol, dm1, hermi=0)

>>> vhf2 =scf.hf.get_veff(mol, dm1, dm_last=dm0, vhf_last=vhf0, hermi=0)

>>> numpy.allclose(vhf1, vhf2)

True

init_guess_by_1e(mol=None)

Generate initial guess density matrix from core hamiltonian

Returns: Density matrix, 2D ndarray

init_guess_by_atom(mol=None)

Generate initial guess density matrix from superposition of atomic HF density matrix. The atomic HF is

occupancy averaged RHF

Returns: Density matrix, 2D ndarray

init_guess_by_chkfile(chkﬁle=None,project=True)

Read the HF results from checkpoint ﬁle, then project it to the basis deﬁned by mol

98 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

Returns: Density matrix, 2D ndarray

init_guess_by_minao(mol=None)

Generate initial guess density matrix based on ANO basis, then project the density matrix to the basis set

deﬁned by mol

Returns: Density matrix, 2D ndarray

Examples:

>>> from pyscf import gto, scf

>>> mol =gto.M(atom='H000;H001.1')

>>> scf.hf.init_guess_by_minao(mol)

array([[ 0.94758917, 0.09227308],

[ 0.09227308, 0.94758917]])

kernel(dm0=None)

main routine for SCF

Kwargs:

dm0 [ndarray] If given, it will be used as the initial guess density matrix

Examples:

>>> import numpy

>>> from pyscf import gto, scf

>>> mol =gto.M(atom='H000;F001.1')

>>> mf =scf.hf.SCF(mol)

>>> dm_guess =numpy.eye(mol.nao_nr())

>>> mf.kernel(dm_guess)

converged SCF energy = -98.5521904482821

-98.552190448282104

make_rdm1(mo_coeff=None,mo_occ=None)

One-particle density matrix in AO representation

Args:

mo_coeff [2D ndarray] Orbital coefﬁcients. Each column is one orbital.

mo_occ [1D ndarray] Occupancy

mulliken_meta(mol=None,dm=None,verbose=5,pre_orth_method=’ANO’,s=None)

Mulliken population analysis, based on meta-Lowdin AOs. In the meta-lowdin, the AOs are grouped in

three sets: core, valence and Rydberg, the orthogonalization are carreid out within each subsets.

Args: mol : an instance of Mole

dm [ndarray or 2-item list of ndarray] Density matrix. ROHF dm is a 2-item list of 2D array

Kwargs: verbose : int or instance of lib.logger.Logger

pre_orth_method [str] Pre-orthogonalization, which localized GTOs for each atom. To obtain the

occupied and unoccupied atomic shells, there are three methods

‘ano’ : Project GTOs to ANO basis

‘minao’ : Project GTOs to MINAO basis

‘scf’ : Fraction-averaged RHF

1.6. scf — Mean-ﬁeld methods 99

PySCF Documentation, Release 1.4.0

mulliken_pop(mol=None,dm=None,s=None,verbose=5)

Mulliken population analysis

𝑀𝑖𝑗 =𝐷𝑖𝑗 𝑆𝑗𝑖

Mulliken charges

𝛿𝑖=

𝑗

𝑀𝑖𝑗

pop(*args,**kwargs)

Mulliken population analysis, based on meta-Lowdin AOs. In the meta-lowdin, the AOs are grouped in

three sets: core, valence and Rydberg, the orthogonalization are carreid out within each subsets.

Args: mol : an instance of Mole

dm [ndarray or 2-item list of ndarray] Density matrix. ROHF dm is a 2-item list of 2D array

Kwargs: verbose : int or instance of lib.logger.Logger

pre_orth_method [str] Pre-orthogonalization, which localized GTOs for each atom. To obtain the

occupied and unoccupied atomic shells, there are three methods

‘ano’ : Project GTOs to ANO basis

‘minao’ : Project GTOs to MINAO basis

‘scf’ : Fraction-averaged RHF

scf(dm0=None)

main routine for SCF

Kwargs:

dm0 [ndarray] If given, it will be used as the initial guess density matrix

Examples:

>>> import numpy

>>> from pyscf import gto, scf

>>> mol =gto.M(atom='H000;F001.1')

>>> mf =scf.hf.SCF(mol)

>>> dm_guess =numpy.eye(mol.nao_nr())

>>> mf.kernel(dm_guess)

converged SCF energy = -98.5521904482821

-98.552190448282104

update(chkﬁle=None)

Read attributes from the chkﬁle then replace the attributes of current object. See also mf.update_from_chk

class pyscf.scf.hf.RHF(mol)

SCF base class. non-relativistic RHF.

Attributes:

verbose [int] Print level. Default value equals to Mole.verbose

max_memory [ﬂoat or int] Allowed memory in MB. Default equals to Mole.max_memory

100 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

chkﬁle [str] checkpoint ﬁle to save MOs, orbital energies etc.

conv_tol [ﬂoat] converge threshold. Default is 1e-10

conv_tol_grad [ﬂoat] gradients converge threshold. Default is sqrt(conv_tol)

max_cycle [int] max number of iterations. Default is 50

init_guess [str] initial guess method. It can be one of ‘minao’, ‘atom’, ‘1e’, ‘chkﬁle’. Default is ‘minao’

diis [boolean or object of DIIS class listed in scf.diis] Default is diis.SCF_DIIS. Set it to None

to turn off DIIS.

diis_space [int] DIIS space size. By default, 8 Fock matrices and errors vector are stored.

diis_start_cycle [int] The step to start DIIS. Default is 1.

diis_ﬁle: ‘str’ File to store DIIS vectors and error vectors.

level_shift [ﬂoat or int] Level shift (in AU) for virtual space. Default is 0.

direct_scf [bool] Direct SCF is used by default.

direct_scf_tol [ﬂoat] Direct SCF cutoff threshold. Default is 1e-13.

callback [function(envs_dict) => None] callback function takes one dict as the argument which is gener-

ated by the builtin function locals(), so that the callback function can access all local variables

in the current envrionment.

conv_check [bool] An extra cycle to check convergence after SCF iterations.

Saved results

converged [bool] SCF converged or not

e_tot [ﬂoat] Total HF energy (electronic energy plus nuclear repulsion)

mo_energy : Orbital energies

mo_occ Orbital occupancy

mo_coeff Orbital coefﬁcients

Examples:

>>> mol =gto.M(atom='H000;H001.1', basis='cc-pvdz')

>>> mf =scf.hf.SCF(mol)

>>> mf.verbose =0

>>> mf.level_shift = .4

>>> mf.scf()

-1.0811707843775884

convert_from_(mf )

Convert given mean-ﬁeld object to RHF/ROHF

get_jk(mol=None,dm=None,hermi=1)

Compute J, K matrices for the given density matrix

Args: mol : an instance of Mole

dm [ndarray or list of ndarrays] A density matrix or a list of density matrices

Kwargs:

hermi [int] Whether J, K matrix is hermitian

1.6. scf — Mean-ﬁeld methods 101

PySCF Documentation, Release 1.4.0

0 : no hermitian or symmetric

1 : hermitian

2 : anti-hermitian

vhfopt : A class which holds precomputed quantities to optimize the computation of J, K matrices

Returns: Depending on the given dm, the function returns one J and one K matrix, or a list of J matrices

and a list of K matrices, corresponding to the input density matrices.

Examples:

>>> from pyscf import gto, scf

>>> from pyscf.scf import _vhf

>>> mol =gto.M(atom='H000;H001.1')

>>> dms =numpy.random.random((3,mol.nao_nr(),mol.nao_nr()))

>>> j,k=scf.hf.get_jk(mol, dms, hermi=0)

>>> print(j.shape)

(3, 2, 2)

class pyscf.scf.rohf.ROHF(mol)

SCF base class. non-relativistic RHF.

Attributes:

verbose [int] Print level. Default value equals to Mole.verbose

max_memory [ﬂoat or int] Allowed memory in MB. Default equals to Mole.max_memory

chkﬁle [str] checkpoint ﬁle to save MOs, orbital energies etc.

conv_tol [ﬂoat] converge threshold. Default is 1e-10

conv_tol_grad [ﬂoat] gradients converge threshold. Default is sqrt(conv_tol)

max_cycle [int] max number of iterations. Default is 50

init_guess [str] initial guess method. It can be one of ‘minao’, ‘atom’, ‘1e’, ‘chkﬁle’. Default is ‘minao’

diis [boolean or object of DIIS class listed in scf.diis] Default is diis.SCF_DIIS. Set it to None

to turn off DIIS.

diis_space [int] DIIS space size. By default, 8 Fock matrices and errors vector are stored.

diis_start_cycle [int] The step to start DIIS. Default is 1.

diis_ﬁle: ‘str’ File to store DIIS vectors and error vectors.

level_shift [ﬂoat or int] Level shift (in AU) for virtual space. Default is 0.

direct_scf [bool] Direct SCF is used by default.

direct_scf_tol [ﬂoat] Direct SCF cutoff threshold. Default is 1e-13.

callback [function(envs_dict) => None] callback function takes one dict as the argument which is gener-

ated by the builtin function locals(), so that the callback function can access all local variables

in the current envrionment.

conv_check [bool] An extra cycle to check convergence after SCF iterations.

Saved results

converged [bool] SCF converged or not

102 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

e_tot [ﬂoat] Total HF energy (electronic energy plus nuclear repulsion)

mo_energy : Orbital energies

mo_occ Orbital occupancy

mo_coeff Orbital coefﬁcients

Examples:

>>> mol =gto.M(atom='H000;H001.1', basis='cc-pvdz')

>>> mf =scf.hf.SCF(mol)

>>> mf.verbose =0

>>> mf.level_shift = .4

>>> mf.scf()

-1.0811707843775884

analyze(verbose=None,**kwargs)

Analyze the given SCF object: print orbital energies, occupancies; print orbital coefﬁcients; Mulliken

population analysis

canonicalize(mf,mo_coeff,mo_occ,fock=None)

Canonicalization diagonalizes the Fock matrix within occupied, open, virtual subspaces separatedly (with-

out change occupancy).

eig(fock,s)

Solver for generalized eigenvalue problem

𝐻𝐶 =𝑆𝐶𝐸

get_fock(mf,h1e=None,s1e=None,vhf=None,dm=None,cycle=-1,diis=None,

diis_start_cycle=None,level_shift_factor=None,damp_factor=None)

Build fock matrix based on Roothaan’s effective fock. See also get_roothaan_fock()

get_grad(mo_coeff,mo_occ,fock=None)

ROHF gradients is the off-diagonal block [co + cv + ov], where [ cc co cv ] [ oc oo ov ] [ vc vo vv ]

get_occ(mf,mo_energy=None,mo_coeff=None)

Label the occupancies for each orbital. NOTE the occupancies are not assigned based on the orbital

energy ordering. The ﬁrst N orbitals are assigned to be occupied orbitals.

Examples:

>>> mol =gto.M(atom='H000;O001.1', spin=1)

>>> mf =scf.hf.SCF(mol)

>>> energy =numpy.array([-10.,-1.,1,-2.,0,-3])

>>> mf.get_occ(energy)

array([2, 2, 2, 2, 1, 0])

get_veff(mol=None,dm=None,dm_last=0,vhf_last=0,hermi=1)

Unrestricted Hartree-Fock potential matrix of alpha and beta spins, for the given density matrix

𝑉𝛼

𝑖𝑗 =

𝑘𝑙

(𝑖𝑗|𝑘𝑙)(𝛾𝛼

𝑙𝑘 +𝛾𝛽

𝑙𝑘)−

𝑘𝑙

(𝑖𝑙|𝑘𝑗)𝛾𝛼

𝑙𝑘

𝑉𝛽

𝑖𝑗 =

𝑘𝑙

(𝑖𝑗|𝑘𝑙)(𝛾𝛼

𝑙𝑘 +𝛾𝛽

𝑙𝑘)−

𝑘𝑙

(𝑖𝑙|𝑘𝑗)𝛾𝛽

𝑙𝑘

Args: mol : an instance of Mole

dm [a list of ndarrays] A list of density matrices, stored as (alpha,alpha,...,beta,beta,...)

1.6. scf — Mean-ﬁeld methods 103

PySCF Documentation, Release 1.4.0

Kwargs:

dm_last [ndarray or a list of ndarrays or 0] The density matrix baseline. When it is not 0, this

function computes the increment of HF potential w.r.t. the reference HF potential matrix.

vhf_last [ndarray or a list of ndarrays or 0] The reference HF potential matrix.

hermi [int] Whether J, K matrix is hermitian

0 : no hermitian or symmetric

1 : hermitian

2 : anti-hermitian

vhfopt : A class which holds precomputed quantities to optimize the computation of J, K matrices

Returns: 𝑉ℎ𝑓 = (𝑉𝛼, 𝑉 𝛽).𝑉𝛼(and 𝑉𝛽) can be a list matrices, corresponding to the input density

matrices.

Examples:

>>> import numpy

>>> from pyscf import gto, scf

>>> mol =gto.M(atom='H000;H001.1')

>>> dmsa =numpy.random.random((3,mol.nao_nr(),mol.nao_nr()))

>>> dmsb =numpy.random.random((3,mol.nao_nr(),mol.nao_nr()))

>>> dms =numpy.vstack((dmsa,dmsb))

>>> dms.shape

(6, 2, 2)

>>> vhfa, vhfb =scf.uhf.get_veff(mol, dms, hermi=0)

>>> vhfa.shape

(3, 2, 2)

>>> vhfb.shape

(3, 2, 2)

make_rdm1(mo_coeff=None,mo_occ=None)

One-particle densit matrix. mo_occ is a 1D array, with occupancy 1 or 2.

class pyscf.scf.uhf.UHF(mol)

SCF base class. non-relativistic RHF.

Attributes:

verbose [int] Print level. Default value equals to Mole.verbose

max_memory [ﬂoat or int] Allowed memory in MB. Default equals to Mole.max_memory

chkﬁle [str] checkpoint ﬁle to save MOs, orbital energies etc.

conv_tol [ﬂoat] converge threshold. Default is 1e-10

conv_tol_grad [ﬂoat] gradients converge threshold. Default is sqrt(conv_tol)

max_cycle [int] max number of iterations. Default is 50

init_guess [str] initial guess method. It can be one of ‘minao’, ‘atom’, ‘1e’, ‘chkﬁle’. Default is ‘minao’

diis [boolean or object of DIIS class listed in scf.diis] Default is diis.SCF_DIIS. Set it to None

to turn off DIIS.

104 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

diis_space [int] DIIS space size. By default, 8 Fock matrices and errors vector are stored.

diis_start_cycle [int] The step to start DIIS. Default is 1.

diis_ﬁle: ‘str’ File to store DIIS vectors and error vectors.

level_shift [ﬂoat or int] Level shift (in AU) for virtual space. Default is 0.

direct_scf [bool] Direct SCF is used by default.

direct_scf_tol [ﬂoat] Direct SCF cutoff threshold. Default is 1e-13.

callback [function(envs_dict) => None] callback function takes one dict as the argument which is gener-

ated by the builtin function locals(), so that the callback function can access all local variables

in the current envrionment.

conv_check [bool] An extra cycle to check convergence after SCF iterations.

Saved results

converged [bool] SCF converged or not

e_tot [ﬂoat] Total HF energy (electronic energy plus nuclear repulsion)

mo_energy : Orbital energies

mo_occ Orbital occupancy

mo_coeff Orbital coefﬁcients

Examples:

>>> mol =gto.M(atom='H000;H001.1', basis='cc-pvdz')

>>> mf =scf.hf.SCF(mol)

>>> mf.verbose =0

>>> mf.level_shift = .4

>>> mf.scf()

-1.0811707843775884

Attributes for UHF:

nelec [(int, int)] If given, freeze the number of (alpha,beta) electrons to the given value.

level_shift [number or two-element list] level shift (in Eh) for alpha and beta Fock if two-element list is

given.

Examples:

>>> mol =gto.M(atom='O000;H001;H010', basis='ccpvdz', charge=1,

˓→spin=1, verbose=0)

>>> mf =scf.UHF(mol)

>>> mf.kernel()

-75.623975516256706

>>> print('S^2 = %.7f, 2S+1 = %.7f'%mf.spin_square())

S^2 = 0.7570150, 2S+1 = 2.0070027

canonicalize(mf,mo_coeff,mo_occ,fock=None)

Canonicalization diagonalizes the UHF Fock matrix within occupied, virtual subspaces separatedly (with-

out change occupancy).

det_ovlp(mo1,mo2,occ1,occ2,ovlp=None)

Calculate the overlap between two different determinants. It is the product of single values of molecular

1.6. scf — Mean-ﬁeld methods 105

PySCF Documentation, Release 1.4.0

orbital overlap matrix.

𝑆12 =⟨Ψ𝐴|Ψ𝐵⟩= (detU)(detV†)

2𝑁



𝑖=1

𝜆𝑖𝑖

where U,V, 𝜆 are unitary matrices and single values generated by single value decomposition(SVD) of

the overlap matrix Owhich is the overlap matrix of two sets of molecular orbitals:

U†OV =Λ

Args:

mo1, mo2 [2D ndarrays] Molecualr orbital coefﬁcients

occ1, occ2: 2D ndarrays occupation numbers

Return:

A list: the product of single values: ﬂoat x_a, x_b: 1D ndarrays UΛ−1V†They are used to cal-

culate asymmetric density matrix

dip_moment(mol=None,dm=None,unit_symbol=None,verbose=3)

Dipole moment calculation

𝜇𝑥=−

𝜇

𝜈

𝑃𝜇𝜈 (𝜈|𝑥|𝜇) + 

𝐴

𝑄𝐴𝑋𝐴

𝜇𝑦=−

𝜇

𝜈

𝑃𝜇𝜈 (𝜈|𝑦|𝜇) + 

𝐴

𝑄𝐴𝑌𝐴

𝜇𝑧=−

𝜇

𝜈

𝑃𝜇𝜈 (𝜈|𝑧|𝜇) + 

𝐴

𝑄𝐴𝑍𝐴

where 𝜇𝑥, 𝜇𝑦, 𝜇𝑧are the x, y and z components of dipole moment

Args: mol: an instance of Mole

dm [a list of 2D ndarrays] a list of density matrices

Return: A list: the dipole moment on x, y and z component

energy_elec(mf,dm=None,h1e=None,vhf=None)

Electronic energy of Unrestricted Hartree-Fock

Returns: Hartree-Fock electronic energy and the 2-electron part contribution

get_jk(mol=None,dm=None,hermi=1)

Coulomb (J) and exchange (K)

Args:

dm [a list of 2D arrays or a list of 3D arrays] (alpha_dm, beta_dm) or (alpha_dms, beta_dms)

get_veff(mol=None,dm=None,dm_last=0,vhf_last=0,hermi=1)

Unrestricted Hartree-Fock potential matrix of alpha and beta spins, for the given density matrix

𝑉𝛼

𝑖𝑗 =

𝑘𝑙

(𝑖𝑗|𝑘𝑙)(𝛾𝛼

𝑙𝑘 +𝛾𝛽

𝑙𝑘)−

𝑘𝑙

(𝑖𝑙|𝑘𝑗)𝛾𝛼

𝑙𝑘

𝑉𝛽

𝑖𝑗 =

𝑘𝑙

(𝑖𝑗|𝑘𝑙)(𝛾𝛼

𝑙𝑘 +𝛾𝛽

𝑙𝑘)−

𝑘𝑙

(𝑖𝑙|𝑘𝑗)𝛾𝛽

𝑙𝑘

Args: mol : an instance of Mole

dm [a list of ndarrays] A list of density matrices, stored as (alpha,alpha,...,beta,beta,...)

106 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

Kwargs:

dm_last [ndarray or a list of ndarrays or 0] The density matrix baseline. When it is not 0, this

function computes the increment of HF potential w.r.t. the reference HF potential matrix.

vhf_last [ndarray or a list of ndarrays or 0] The reference HF potential matrix.

hermi [int] Whether J, K matrix is hermitian

0 : no hermitian or symmetric

1 : hermitian

2 : anti-hermitian

vhfopt : A class which holds precomputed quantities to optimize the computation of J, K matrices

Returns: 𝑉ℎ𝑓 = (𝑉𝛼, 𝑉 𝛽).𝑉𝛼(and 𝑉𝛽) can be a list matrices, corresponding to the input density

matrices.

Examples:

>>> import numpy

>>> from pyscf import gto, scf

>>> mol =gto.M(atom='H000;H001.1')

>>> dmsa =numpy.random.random((3,mol.nao_nr(),mol.nao_nr()))

>>> dmsb =numpy.random.random((3,mol.nao_nr(),mol.nao_nr()))

>>> dms =numpy.vstack((dmsa,dmsb))

>>> dms.shape

(6, 2, 2)

>>> vhfa, vhfb =scf.uhf.get_veff(mol, dms, hermi=0)

>>> vhfa.shape

(3, 2, 2)

>>> vhfb.shape

(3, 2, 2)

init_guess_by_minao(mol=None,breaksym=True)

Initial guess in terms of the overlap to minimal basis.

make_asym_dm(mo1,mo2,occ1,occ2,x)

One-particle asymmetric density matrix

Args:

mo1, mo2 [2D ndarrays] Molecualr orbital coefﬁcients

occ1, occ2: 2D ndarrays Occupation numbers

x: 2D ndarrays UΛ−1V†. See also det_ovlp()

Return: A list of 2D ndarrays for alpha and beta spin

Examples:

>>> mf1 =scf.UHF(gto.M(atom='H000;F001.3', basis='ccpvdz')).run()

>>> mf2 =scf.UHF(gto.M(atom='H000;F001.4', basis='ccpvdz')).run()

>>> s=gto.intor_cross('int1e_ovlp_sph', mf1.mol, mf2.mol)

>>> det, x =det_ovlp(mf1.mo_coeff, mf1.mo_occ, mf2.mo_coeff, mf2.mo_occ, s)

>>> adm =make_asym_dm(mf1.mo_coeff, mf1.mo_occ, mf2.mo_coeff, mf2.mo_occ, x)

>>> adm.shape

(2, 19, 19)

1.6. scf — Mean-ﬁeld methods 107

PySCF Documentation, Release 1.4.0

make_rdm1(mo_coeff=None,mo_occ=None)

One-particle density matrix

Returns: A list of 2D ndarrays for alpha and beta spins

spin_square(mo_coeff=None,s=None)

Spin of the given UHF orbitals

𝑆2=1

2(𝑆+𝑆−+𝑆−𝑆+) + 𝑆2

𝑧

where 𝑆+=𝑖𝑆𝑖+is effective for all beta occupied orbitals; 𝑆−=𝑖𝑆𝑖−is effective for all alpha

occupied orbitals.

1.There are two possibilities for 𝑆+𝑆−

(a) same electron 𝑆+𝑆−=𝑖𝑠𝑖+𝑠𝑖−,



𝑖⟨𝑈𝐻𝐹 |𝑠𝑖+𝑠𝑖−|𝑈𝐻𝐹 ⟩=

𝑝𝑞 ⟨𝑝|𝑠+𝑠−|𝑞⟩𝛾𝑞𝑝 =𝑛𝛼

2) different electrons 𝑆+𝑆−=𝑠𝑖+𝑠𝑗−,(𝑖̸=𝑗). There are in total 𝑛(𝑛−1) terms. As a

two-particle operator,

⟨𝑆+𝑆−⟩=⟨𝑖𝑗|𝑠+𝑠−|𝑖𝑗⟩−⟨𝑖𝑗|𝑠+𝑠−|𝑗𝑖⟩=−⟨𝑖𝛼|𝑗𝛽⟩⟨𝑗𝛽|𝑖𝛼⟩

2.Similarly, for 𝑆−𝑆+

(a) same electron



𝑖⟨𝑠𝑖−𝑠𝑖+⟩=𝑛𝛽

(a) different electrons

⟨𝑆−𝑆+⟩=−⟨𝑖𝛽|𝑗𝛼⟩⟨𝑗𝛼|𝑖𝛽⟩

2.For 𝑆2

𝑧

(a) same electron

⟨𝑠2

𝑧⟩=1

4(𝑛𝛼+𝑛𝛽)

(a) different electrons

2

𝑖𝑗

(⟨𝑖𝑗|2𝑠𝑧1𝑠𝑧2|𝑖𝑗⟩−⟨𝑖𝑗|2𝑠𝑧1𝑠𝑧2|𝑗𝑖⟩)

4(⟨𝑖𝛼|𝑖𝛼⟩⟨𝑗𝛼|𝑗𝛼⟩−⟨𝑖𝛼|𝑖𝛼⟩⟨𝑗𝛽|𝑗𝛽⟩−⟨𝑖𝛽|𝑖𝛽⟩⟨𝑗𝛼|𝑗𝛼⟩+⟨𝑖𝛽|𝑖𝛽⟩⟨𝑗𝛽|𝑗𝛽⟩)

−1

4(⟨𝑖𝛼|𝑗𝛼⟩⟨𝑗𝛼|𝑖𝛼⟩+⟨𝑖𝛽|𝑗𝛽⟩⟨𝑗𝛽|𝑖𝛽⟩)

4(𝑛2

𝛼−𝑛𝛼𝑛𝛽−𝑛𝛽𝑛𝛼+𝑛2

𝛽)−1

4(𝑛𝛼+𝑛𝛽)

4((𝑛𝛼−𝑛𝛽)2−(𝑛𝛼+𝑛𝛽))

In total

⟨𝑆2⟩=1

2(𝑛𝛼−

𝑖𝑗 ⟨𝑖𝛼|𝑗𝛽⟩⟨𝑗𝛽|𝑖𝛼⟩+𝑛𝛽−

𝑖𝑗 ⟨𝑖𝛽|𝑗𝛼⟩⟨𝑗𝛼|𝑖𝛽⟩) + 1

4(𝑛𝛼−𝑛𝛽)2

108 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

Args:

mo [a list of 2 ndarrays] Occupied alpha and occupied beta orbitals

Kwargs:

s[ndarray] AO overlap

Returns: A list of two ﬂoats. The ﬁrst is the expectation value of S^2. The second is the corresponding

2S+1

Examples:

>>> mol =gto.M(atom='O000;H001;H010', basis='ccpvdz', charge=1,

˓→spin=1, verbose=0)

>>> mf =scf.UHF(mol)

>>> mf.kernel()

-75.623975516256706

>>> mo =(mf.mo_coeff[0][:,mf.mo_occ[0]>0], mf.mo_coeff[1][:,mf.mo_occ[1]>0])

>>> print('S^2 = %.7f, 2S+1 = %.7f'%spin_square(mo, mol.intor('int1e_ovlp_

˓→sph')))

S^2 = 0.7570150, 2S+1 = 2.0070027

Hartree-Fock

class pyscf.scf.hf.RHF(mol)

SCF base class. non-relativistic RHF.

Attributes:

verbose [int] Print level. Default value equals to Mole.verbose

max_memory [ﬂoat or int] Allowed memory in MB. Default equals to Mole.max_memory

chkﬁle [str] checkpoint ﬁle to save MOs, orbital energies etc.

conv_tol [ﬂoat] converge threshold. Default is 1e-10

conv_tol_grad [ﬂoat] gradients converge threshold. Default is sqrt(conv_tol)

max_cycle [int] max number of iterations. Default is 50

init_guess [str] initial guess method. It can be one of ‘minao’, ‘atom’, ‘1e’, ‘chkﬁle’. Default is ‘minao’

diis [boolean or object of DIIS class listed in scf.diis] Default is diis.SCF_DIIS. Set it to None

to turn off DIIS.

diis_space [int] DIIS space size. By default, 8 Fock matrices and errors vector are stored.

diis_start_cycle [int] The step to start DIIS. Default is 1.

diis_ﬁle: ‘str’ File to store DIIS vectors and error vectors.

level_shift [ﬂoat or int] Level shift (in AU) for virtual space. Default is 0.

direct_scf [bool] Direct SCF is used by default.

direct_scf_tol [ﬂoat] Direct SCF cutoff threshold. Default is 1e-13.

callback [function(envs_dict) => None] callback function takes one dict as the argument which is gener-

ated by the builtin function locals(), so that the callback function can access all local variables

in the current envrionment.

conv_check [bool] An extra cycle to check convergence after SCF iterations.

1.6. scf — Mean-ﬁeld methods 109

PySCF Documentation, Release 1.4.0

Saved results

converged [bool] SCF converged or not

e_tot [ﬂoat] Total HF energy (electronic energy plus nuclear repulsion)

mo_energy : Orbital energies

mo_occ Orbital occupancy

mo_coeff Orbital coefﬁcients

Examples:

>>> mol =gto.M(atom='H000;H001.1', basis='cc-pvdz')

>>> mf =scf.hf.SCF(mol)

>>> mf.verbose =0

>>> mf.level_shift = .4

>>> mf.scf()

-1.0811707843775884

convert_from_(mf )

Convert given mean-ﬁeld object to RHF/ROHF

get_jk(mol=None,dm=None,hermi=1)

Compute J, K matrices for the given density matrix

Args: mol : an instance of Mole

dm [ndarray or list of ndarrays] A density matrix or a list of density matrices

Kwargs:

hermi [int] Whether J, K matrix is hermitian

0 : no hermitian or symmetric

1 : hermitian

2 : anti-hermitian

vhfopt : A class which holds precomputed quantities to optimize the computation of J, K matrices

Returns: Depending on the given dm, the function returns one J and one K matrix, or a list of J matrices

and a list of K matrices, corresponding to the input density matrices.

Examples:

>>> from pyscf import gto, scf

>>> from pyscf.scf import _vhf

>>> mol =gto.M(atom='H000;H001.1')

>>> dms =numpy.random.random((3,mol.nao_nr(),mol.nao_nr()))

>>> j,k=scf.hf.get_jk(mol, dms, hermi=0)

>>> print(j.shape)

(3, 2, 2)

class pyscf.scf.hf.SCF(mol)

SCF base class. non-relativistic RHF.

Attributes:

verbose [int] Print level. Default value equals to Mole.verbose

110 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

max_memory [ﬂoat or int] Allowed memory in MB. Default equals to Mole.max_memory

chkﬁle [str] checkpoint ﬁle to save MOs, orbital energies etc.

conv_tol [ﬂoat] converge threshold. Default is 1e-10

conv_tol_grad [ﬂoat] gradients converge threshold. Default is sqrt(conv_tol)

max_cycle [int] max number of iterations. Default is 50

init_guess [str] initial guess method. It can be one of ‘minao’, ‘atom’, ‘1e’, ‘chkﬁle’. Default is ‘minao’

diis [boolean or object of DIIS class listed in scf.diis] Default is diis.SCF_DIIS. Set it to None

to turn off DIIS.

diis_space [int] DIIS space size. By default, 8 Fock matrices and errors vector are stored.

diis_start_cycle [int] The step to start DIIS. Default is 1.

diis_ﬁle: ‘str’ File to store DIIS vectors and error vectors.

level_shift [ﬂoat or int] Level shift (in AU) for virtual space. Default is 0.

direct_scf [bool] Direct SCF is used by default.

direct_scf_tol [ﬂoat] Direct SCF cutoff threshold. Default is 1e-13.

callback [function(envs_dict) => None] callback function takes one dict as the argument which is gener-

ated by the builtin function locals(), so that the callback function can access all local variables

in the current envrionment.

conv_check [bool] An extra cycle to check convergence after SCF iterations.

Saved results

converged [bool] SCF converged or not

e_tot [ﬂoat] Total HF energy (electronic energy plus nuclear repulsion)

mo_energy : Orbital energies

mo_occ Orbital occupancy

mo_coeff Orbital coefﬁcients

Examples:

>>> mol =gto.M(atom='H000;H001.1', basis='cc-pvdz')

>>> mf =scf.hf.SCF(mol)

>>> mf.verbose =0

>>> mf.level_shift = .4

>>> mf.scf()

-1.0811707843775884

analyze(verbose=None,**kwargs)

Analyze the given SCF object: print orbital energies, occupancies; print orbital coefﬁcients; Mulliken

population analysis; Diople moment.

as_scanner(mf )

Generating a scanner/solver for HF PES.

The returned solver is a function. This function requires one argument “mol” as input and returns total

HF energy.

The solver will automatically use the results of last calculation as the initial guess of the new calculation.

All parameters assigned in the SCF object (DIIS, conv_tol, max_memory etc) are automatically applied

in the solver.

1.6. scf — Mean-ﬁeld methods 111

PySCF Documentation, Release 1.4.0

Note scanner has side effects. It may change many underlying objects (_scf, with_df, with_x2c, ...) during

calculation.

Examples:

>>> from pyscf import gto, scf

>>> hf_scanner =scf.RHF(gto.Mole().set(verbose=0)).as_scanner()

>>> hf_scanner(gto.M(atom='H000;F001.1'))

-98.552190448277955

>>> hf_scanner(gto.M(atom='H000;F001.5'))

-98.414750424294368

canonicalize(mf,mo_coeff,mo_occ,fock=None)

Canonicalization diagonalizes the Fock matrix within occupied, open, virtual subspaces separatedly (with-

out change occupancy).

dip_moment(mol=None,dm=None,unit_symbol=None,verbose=3)

Dipole moment calculation

𝜇𝑥=−

𝜇

𝜈

𝑃𝜇𝜈 (𝜈|𝑥|𝜇) + 

𝐴

𝑄𝐴𝑋𝐴

𝜇𝑦=−

𝜇

𝜈

𝑃𝜇𝜈 (𝜈|𝑦|𝜇) + 

𝐴

𝑄𝐴𝑌𝐴

𝜇𝑧=−

𝜇

𝜈

𝑃𝜇𝜈 (𝜈|𝑧|𝜇) + 

𝐴

𝑄𝐴𝑍𝐴

where 𝜇𝑥, 𝜇𝑦, 𝜇𝑧are the x, y and z components of dipole moment

Args: mol: an instance of Mole dm : a 2D ndarrays density matrices

Return: A list: the dipole moment on x, y and z component

eig(h,s)

Solver for generalized eigenvalue problem

𝐻𝐶 =𝑆𝐶𝐸

energy_elec(mf,dm=None,h1e=None,vhf=None)

Electronic part of Hartree-Fock energy, for given core hamiltonian and HF potential

... math:

E=\sum_{ij}h_{ij} \gamma_{ji}

+\frac{1}{2}\sum_{ijkl} \gamma_{ji}\gamma_{lk} \langle ik||jl\rangle

Args: mf : an instance of SCF class

Kwargs:

dm [2D ndarray] one-partical density matrix

h1e [2D ndarray] Core hamiltonian

vhf [2D ndarray] HF potential

Returns: Hartree-Fock electronic energy and the Coulomb energy

Examples:

112 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

>>> from pyscf import gto, scf

>>> mol =gto.M(atom='H000;H001.1')

>>> mf =scf.RHF(mol)

>>> mf.scf()

>>> dm =mf.make_rdm1()

>>> scf.hf.energy_elec(mf, dm)

(-1.5176090667746334, 0.60917167853723675)

energy_tot(mf,dm=None,h1e=None,vhf=None)

Total Hartree-Fock energy, electronic part plus nuclear repulstion See scf.hf.energy_elec() for

the electron part

from_chk(chkﬁle=None,project=True)

Read the HF results from checkpoint ﬁle, then project it to the basis deﬁned by mol

Returns: Density matrix, 2D ndarray

get_fock(mf,h1e=None,s1e=None,vhf=None,dm=None,cycle=-1,diis=None,

diis_start_cycle=None,level_shift_factor=None,damp_factor=None)

F = h^{core} + V^{HF}

Special treatment (damping, DIIS, or level shift) will be applied to the Fock matrix if diis and cycle is

speciﬁed (The two parameters are passed to get_fock function during the SCF iteration)

Args:

h1e [2D ndarray] Core hamiltonian

s1e [2D ndarray] Overlap matrix, for DIIS

vhf [2D ndarray] HF potential matrix

dm [2D ndarray] Density matrix, for DIIS

Kwargs:

cycle [int] Then present SCF iteration step, for DIIS

diis [an object of SCF.DIIS class] DIIS object to hold intermediate Fock and error vectors

diis_start_cycle [int] The step to start DIIS. Default is 0.

level_shift_factor [ﬂoat or int] Level shift (in AU) for virtual space. Default is 0.

get_grad(mo_coeff,mo_occ,fock=None)

RHF Gradients

Args:

mo_coeff [2D ndarray] Obital coefﬁcients

mo_occ [1D ndarray] Orbital occupancy

fock_ao [2D ndarray] Fock matrix in AO representation

Returns: Gradients in MO representation. It’s a num_occ*num_vir vector.

get_j(mol=None,dm=None,hermi=1)

Compute J matrix for the given density matrix.

get_jk(mol=None,dm=None,hermi=1)

Compute J, K matrices for the given density matrix

Args: mol : an instance of Mole

dm [ndarray or list of ndarrays] A density matrix or a list of density matrices

1.6. scf — Mean-ﬁeld methods 113

PySCF Documentation, Release 1.4.0

Kwargs:

hermi [int] Whether J, K matrix is hermitian

0 : no hermitian or symmetric

1 : hermitian

2 : anti-hermitian

vhfopt : A class which holds precomputed quantities to optimize the computation of J, K matrices

Returns: Depending on the given dm, the function returns one J and one K matrix, or a list of J matrices

and a list of K matrices, corresponding to the input density matrices.

Examples:

>>> from pyscf import gto, scf

>>> from pyscf.scf import _vhf

>>> mol =gto.M(atom='H000;H001.1')

>>> dms =numpy.random.random((3,mol.nao_nr(),mol.nao_nr()))

>>> j,k=scf.hf.get_jk(mol, dms, hermi=0)

>>> print(j.shape)

(3, 2, 2)

get_k(mol=None,dm=None,hermi=1)

Compute K matrix for the given density matrix.

get_occ(mf,mo_energy=None,mo_coeff=None)

Label the occupancies for each orbital

Kwargs:

mo_energy [1D ndarray] Obital energies

mo_coeff [2D ndarray] Obital coefﬁcients

Examples:

>>> from pyscf import gto, scf

>>> mol =gto.M(atom='H000;F001.1')

>>> mf =scf.hf.SCF(mol)

>>> energy =numpy.array([-10.,-1.,1,-2.,0,-3])

>>> mf.get_occ(energy)

array([2, 2, 0, 2, 2, 2])

get_veff(mol=None,dm=None,dm_last=0,vhf_last=0,hermi=1)

Hartree-Fock potential matrix for the given density matrix

Args: mol : an instance of Mole

dm [ndarray or list of ndarrays] A density matrix or a list of density matrices

Kwargs:

dm_last [ndarray or a list of ndarrays or 0] The density matrix baseline. If not 0, this function

computes the increment of HF potential w.r.t. the reference HF potential matrix.

vhf_last [ndarray or a list of ndarrays or 0] The reference HF potential matrix.

hermi [int] Whether J, K matrix is hermitian

114 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

0 : no hermitian or symmetric

1 : hermitian

2 : anti-hermitian

vhfopt : A class which holds precomputed quantities to optimize the computation of J, K matrices

Returns: matrix Vhf = 2*J - K. Vhf can be a list matrices, corresponding to the input density matrices.

Examples:

>>> import numpy

>>> from pyscf import gto, scf

>>> from pyscf.scf import _vhf

>>> mol =gto.M(atom='H000;H001.1')

>>> dm0 =numpy.random.random((mol.nao_nr(),mol.nao_nr()))

>>> vhf0 =scf.hf.get_veff(mol, dm0, hermi=0)

>>> dm1 =numpy.random.random((mol.nao_nr(),mol.nao_nr()))

>>> vhf1 =scf.hf.get_veff(mol, dm1, hermi=0)

>>> vhf2 =scf.hf.get_veff(mol, dm1, dm_last=dm0, vhf_last=vhf0, hermi=0)

>>> numpy.allclose(vhf1, vhf2)

True

init_guess_by_1e(mol=None)

Generate initial guess density matrix from core hamiltonian

Returns: Density matrix, 2D ndarray

init_guess_by_atom(mol=None)

Generate initial guess density matrix from superposition of atomic HF density matrix. The atomic HF is

occupancy averaged RHF

Returns: Density matrix, 2D ndarray

init_guess_by_chkfile(chkﬁle=None,project=True)

Read the HF results from checkpoint ﬁle, then project it to the basis deﬁned by mol

Returns: Density matrix, 2D ndarray

init_guess_by_minao(mol=None)

Generate initial guess density matrix based on ANO basis, then project the density matrix to the basis set

deﬁned by mol

Returns: Density matrix, 2D ndarray

Examples:

>>> from pyscf import gto, scf

>>> mol =gto.M(atom='H000;H001.1')

>>> scf.hf.init_guess_by_minao(mol)

array([[ 0.94758917, 0.09227308],

[ 0.09227308, 0.94758917]])

kernel(dm0=None)

main routine for SCF

Kwargs:

dm0 [ndarray] If given, it will be used as the initial guess density matrix

Examples:

1.6. scf — Mean-ﬁeld methods 115

PySCF Documentation, Release 1.4.0

>>> import numpy

>>> from pyscf import gto, scf

>>> mol =gto.M(atom='H000;F001.1')

>>> mf =scf.hf.SCF(mol)

>>> dm_guess =numpy.eye(mol.nao_nr())

>>> mf.kernel(dm_guess)

converged SCF energy = -98.5521904482821

-98.552190448282104

make_rdm1(mo_coeff=None,mo_occ=None)

One-particle density matrix in AO representation

Args:

mo_coeff [2D ndarray] Orbital coefﬁcients. Each column is one orbital.

mo_occ [1D ndarray] Occupancy

mulliken_meta(mol=None,dm=None,verbose=5,pre_orth_method=’ANO’,s=None)

Mulliken population analysis, based on meta-Lowdin AOs. In the meta-lowdin, the AOs are grouped in

three sets: core, valence and Rydberg, the orthogonalization are carreid out within each subsets.

Args: mol : an instance of Mole

dm [ndarray or 2-item list of ndarray] Density matrix. ROHF dm is a 2-item list of 2D array

Kwargs: verbose : int or instance of lib.logger.Logger

pre_orth_method [str] Pre-orthogonalization, which localized GTOs for each atom. To obtain the

occupied and unoccupied atomic shells, there are three methods

‘ano’ : Project GTOs to ANO basis

‘minao’ : Project GTOs to MINAO basis

‘scf’ : Fraction-averaged RHF

mulliken_pop(mol=None,dm=None,s=None,verbose=5)

Mulliken population analysis

𝑀𝑖𝑗 =𝐷𝑖𝑗 𝑆𝑗𝑖

Mulliken charges

𝛿𝑖=

𝑗

𝑀𝑖𝑗

pop(*args,**kwargs)

Mulliken population analysis, based on meta-Lowdin AOs. In the meta-lowdin, the AOs are grouped in

three sets: core, valence and Rydberg, the orthogonalization are carreid out within each subsets.

Args: mol : an instance of Mole

dm [ndarray or 2-item list of ndarray] Density matrix. ROHF dm is a 2-item list of 2D array

Kwargs: verbose : int or instance of lib.logger.Logger

pre_orth_method [str] Pre-orthogonalization, which localized GTOs for each atom. To obtain the

occupied and unoccupied atomic shells, there are three methods

116 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

‘ano’ : Project GTOs to ANO basis

‘minao’ : Project GTOs to MINAO basis

‘scf’ : Fraction-averaged RHF

scf(dm0=None)

main routine for SCF

Kwargs:

dm0 [ndarray] If given, it will be used as the initial guess density matrix

Examples:

>>> import numpy

>>> from pyscf import gto, scf

>>> mol =gto.M(atom='H000;F001.1')

>>> mf =scf.hf.SCF(mol)

>>> dm_guess =numpy.eye(mol.nao_nr())

>>> mf.kernel(dm_guess)

converged SCF energy = -98.5521904482821

-98.552190448282104

update(chkﬁle=None)

Read attributes from the chkﬁle then replace the attributes of current object. See also mf.update_from_chk

pyscf.scf.hf.analyze(mf,verbose=5,**kwargs)

Analyze the given SCF object: print orbital energies, occupancies; print orbital coefﬁcients; Mulliken population

analysis; Diople moment.

pyscf.scf.hf.as_scanner(mf )

Generating a scanner/solver for HF PES.

The returned solver is a function. This function requires one argument “mol” as input and returns total HF

energy.

The solver will automatically use the results of last calculation as the initial guess of the new calculation. All

parameters assigned in the SCF object (DIIS, conv_tol, max_memory etc) are automatically applied in the

solver.

Note scanner has side effects. It may change many underlying objects (_scf, with_df, with_x2c, ...) during

calculation.

Examples:

>>> from pyscf import gto, scf

>>> hf_scanner =scf.RHF(gto.Mole().set(verbose=0)).as_scanner()

>>> hf_scanner(gto.M(atom='H000;F001.1'))

-98.552190448277955

>>> hf_scanner(gto.M(atom='H000;F001.5'))

-98.414750424294368

pyscf.scf.hf.canonicalize(mf,mo_coeff,mo_occ,fock=None)

Canonicalization diagonalizes the Fock matrix within occupied, open, virtual subspaces separatedly (without

change occupancy).

pyscf.scf.hf.dip_moment(mol,dm,unit_symbol=’Debye’,verbose=3)

1.6. scf — Mean-ﬁeld methods 117

PySCF Documentation, Release 1.4.0

Dipole moment calculation

𝜇𝑥=−

𝜇

𝜈

𝑃𝜇𝜈 (𝜈|𝑥|𝜇) + 

𝐴

𝑄𝐴𝑋𝐴

𝜇𝑦=−

𝜇

𝜈

𝑃𝜇𝜈 (𝜈|𝑦|𝜇) + 

𝐴

𝑄𝐴𝑌𝐴

𝜇𝑧=−

𝜇

𝜈

𝑃𝜇𝜈 (𝜈|𝑧|𝜇) + 

𝐴

𝑄𝐴𝑍𝐴

where 𝜇𝑥, 𝜇𝑦, 𝜇𝑧are the x, y and z components of dipole moment

Args: mol: an instance of Mole dm : a 2D ndarrays density matrices

Return: A list: the dipole moment on x, y and z component

pyscf.scf.hf.dot_eri_dm(eri,dm,hermi=0)

Compute J, K matrices in terms of the given 2-electron integrals and density matrix:

J ~ numpy.einsum(‘pqrs,qp->rs’, eri, dm) K ~ numpy.einsum(‘pqrs,qr->ps’, eri, dm)

Args:

eri [ndarray] 8-fold or 4-fold ERIs

dm [ndarray or list of ndarrays] A density matrix or a list of density matrices

Kwargs:

hermi [int] Whether J, K matrix is hermitian

0 : no hermitian or symmetric

1 : hermitian

2 : anti-hermitian

Returns: Depending on the given dm, the function returns one J and one K matrix, or a list of J matrices and a

list of K matrices, corresponding to the input density matrices.

Examples:

>>> from pyscf import gto, scf

>>> from pyscf.scf import _vhf

>>> mol =gto.M(atom='H000;H001.1')

>>> eri =_vhf.int2e_sph(mol._atm, mol._bas, mol._env)

>>> dms =numpy.random.random((3,mol.nao_nr(),mol.nao_nr()))

>>> j,k=scf.hf.dot_eri_dm(eri, dms, hermi=0)

>>> print(j.shape)

(3, 2, 2)

pyscf.scf.hf.eig(h,s)

Solver for generalized eigenvalue problem

𝐻𝐶 =𝑆𝐶𝐸

pyscf.scf.hf.energy_elec(mf,dm=None,h1e=None,vhf=None)

Electronic part of Hartree-Fock energy, for given core hamiltonian and HF potential

... math:

118 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

E=\sum_{ij}h_{ij} \gamma_{ji}

+\frac{1}{2}\sum_{ijkl} \gamma_{ji}\gamma_{lk} \langle ik||jl\rangle

Args: mf : an instance of SCF class

Kwargs:

dm [2D ndarray] one-partical density matrix

h1e [2D ndarray] Core hamiltonian

vhf [2D ndarray] HF potential

Returns: Hartree-Fock electronic energy and the Coulomb energy

Examples:

>>> from pyscf import gto, scf

>>> mol =gto.M(atom='H000;H001.1')

>>> mf =scf.RHF(mol)

>>> mf.scf()

>>> dm =mf.make_rdm1()

>>> scf.hf.energy_elec(mf, dm)

(-1.5176090667746334, 0.60917167853723675)

pyscf.scf.hf.energy_tot(mf,dm=None,h1e=None,vhf=None)

Total Hartree-Fock energy, electronic part plus nuclear repulstion See scf.hf.energy_elec() for the

electron part

pyscf.scf.hf.get_fock(mf,h1e=None,s1e=None,vhf=None,dm=None,cycle=-1,diis=None,

diis_start_cycle=None,level_shift_factor=None,damp_factor=None)

F = h^{core} + V^{HF}

Special treatment (damping, DIIS, or level shift) will be applied to the Fock matrix if diis and cycle is speciﬁed

(The two parameters are passed to get_fock function during the SCF iteration)

Args:

h1e [2D ndarray] Core hamiltonian

s1e [2D ndarray] Overlap matrix, for DIIS

vhf [2D ndarray] HF potential matrix

dm [2D ndarray] Density matrix, for DIIS

Kwargs:

cycle [int] Then present SCF iteration step, for DIIS

diis [an object of SCF.DIIS class] DIIS object to hold intermediate Fock and error vectors

diis_start_cycle [int] The step to start DIIS. Default is 0.

level_shift_factor [ﬂoat or int] Level shift (in AU) for virtual space. Default is 0.

pyscf.scf.hf.get_grad(mo_coeff,mo_occ,fock_ao)

RHF Gradients

Args:

mo_coeff [2D ndarray] Obital coefﬁcients

mo_occ [1D ndarray] Orbital occupancy

1.6. scf — Mean-ﬁeld methods 119

PySCF Documentation, Release 1.4.0

fock_ao [2D ndarray] Fock matrix in AO representation

Returns: Gradients in MO representation. It’s a num_occ*num_vir vector.

pyscf.scf.hf.get_hcore(mol)

Core Hamiltonian

Examples:

>>> from pyscf import gto, scf

>>> mol =gto.M(atom='H000;H001.1')

>>> scf.hf.get_hcore(mol)

array([[-0.93767904, -0.59316327],

[-0.59316327, -0.93767904]])

pyscf.scf.hf.get_init_guess(mol,key=’minao’)

Pick a init_guess method

Kwargs:

key [str] One of ‘minao’, ‘atom’, ‘1e’, ‘chkﬁle’.

pyscf.scf.hf.get_jk(mol,dm,hermi=1,vhfopt=None)

Compute J, K matrices for the given density matrix

Args: mol : an instance of Mole

dm [ndarray or list of ndarrays] A density matrix or a list of density matrices

Kwargs:

hermi [int] Whether J, K matrix is hermitian

0 : no hermitian or symmetric

1 : hermitian

2 : anti-hermitian

vhfopt : A class which holds precomputed quantities to optimize the computation of J, K matrices

Returns: Depending on the given dm, the function returns one J and one K matrix, or a list of J matrices and a

list of K matrices, corresponding to the input density matrices.

Examples:

>>> from pyscf import gto, scf

>>> from pyscf.scf import _vhf

>>> mol =gto.M(atom='H000;H001.1')

>>> dms =numpy.random.random((3,mol.nao_nr(),mol.nao_nr()))

>>> j,k=scf.hf.get_jk(mol, dms, hermi=0)

>>> print(j.shape)

(3, 2, 2)

pyscf.scf.hf.get_occ(mf,mo_energy=None,mo_coeff=None)

Label the occupancies for each orbital

Kwargs:

mo_energy [1D ndarray] Obital energies

mo_coeff [2D ndarray] Obital coefﬁcients

120 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

Examples:

>>> from pyscf import gto, scf

>>> mol =gto.M(atom='H000;F001.1')

>>> mf =scf.hf.SCF(mol)

>>> energy =numpy.array([-10.,-1.,1,-2.,0,-3])

>>> mf.get_occ(energy)

array([2, 2, 0, 2, 2, 2])

pyscf.scf.hf.get_ovlp(mol)

Overlap matrix

pyscf.scf.hf.get_veff(mol,dm,dm_last=None,vhf_last=None,hermi=1,vhfopt=None)

Hartree-Fock potential matrix for the given density matrix

Args: mol : an instance of Mole

dm [ndarray or list of ndarrays] A density matrix or a list of density matrices

Kwargs:

dm_last [ndarray or a list of ndarrays or 0] The density matrix baseline. If not 0, this function computes

the increment of HF potential w.r.t. the reference HF potential matrix.

vhf_last [ndarray or a list of ndarrays or 0] The reference HF potential matrix.

hermi [int] Whether J, K matrix is hermitian

0 : no hermitian or symmetric

1 : hermitian

2 : anti-hermitian

vhfopt : A class which holds precomputed quantities to optimize the computation of J, K matrices

Returns: matrix Vhf = 2*J - K. Vhf can be a list matrices, corresponding to the input density matrices.

Examples:

>>> import numpy

>>> from pyscf import gto, scf

>>> from pyscf.scf import _vhf

>>> mol =gto.M(atom='H000;H001.1')

>>> dm0 =numpy.random.random((mol.nao_nr(),mol.nao_nr()))

>>> vhf0 =scf.hf.get_veff(mol, dm0, hermi=0)

>>> dm1 =numpy.random.random((mol.nao_nr(),mol.nao_nr()))

>>> vhf1 =scf.hf.get_veff(mol, dm1, hermi=0)

>>> vhf2 =scf.hf.get_veff(mol, dm1, dm_last=dm0, vhf_last=vhf0, hermi=0)

>>> numpy.allclose(vhf1, vhf2)

True

pyscf.scf.hf.init_guess_by_1e(mol)

Generate initial guess density matrix from core hamiltonian

Returns: Density matrix, 2D ndarray

pyscf.scf.hf.init_guess_by_atom(mol)

Generate initial guess density matrix from superposition of atomic HF density matrix. The atomic HF is occu-

pancy averaged RHF

1.6. scf — Mean-ﬁeld methods 121

PySCF Documentation, Release 1.4.0

Returns: Density matrix, 2D ndarray

pyscf.scf.hf.init_guess_by_chkfile(mol,chkﬁle_name,project=True)

Read the HF results from checkpoint ﬁle, then project it to the basis deﬁned by mol

Returns: Density matrix, 2D ndarray

pyscf.scf.hf.init_guess_by_minao(mol)

Generate initial guess density matrix based on ANO basis, then project the density matrix to the basis set deﬁned

by mol

Returns: Density matrix, 2D ndarray

Examples:

>>> from pyscf import gto, scf

>>> mol =gto.M(atom='H000;H001.1')

>>> scf.hf.init_guess_by_minao(mol)

array([[ 0.94758917, 0.09227308],

[ 0.09227308, 0.94758917]])

pyscf.scf.hf.kernel(mf,conv_tol=1e-10,conv_tol_grad=None,dump_chk=True,dm0=None,call-

back=None,conv_check=True,**kwargs)

kernel: the SCF driver.

Args:

mf [an instance of SCF class] To hold the ﬂags to control SCF. Besides the control parameters, one can

modify its function members to change the behavior of SCF. The member functions which are called

in kernel are

mf.get_init_guess

mf.get_hcore

mf.get_ovlp

mf.get_fock

mf.get_grad

mf.eig

mf.get_occ

mf.make_rdm1

mf.energy_tot

mf.dump_chk

Kwargs:

conv_tol [ﬂoat] converge threshold.

conv_tol_grad [ﬂoat] gradients converge threshold.

dump_chk [bool] Whether to save SCF intermediate results in the checkpoint ﬁle

dm0 [ndarray] Initial guess density matrix. If not given (the default), the kernel takes the density matrix

generated by mf.get_init_guess.

callback [function(envs_dict) => None] callback function takes one dict as the argument which is gener-

ated by the builtin function locals(), so that the callback function can access all local variables

in the current envrionment.

Returns: A list : scf_conv, e_tot, mo_energy, mo_coeff, mo_occ

122 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

scf_conv [bool] True means SCF converged

e_tot [ﬂoat] Hartree-Fock energy of last iteration

mo_energy [1D ﬂoat array] Orbital energies. Depending the eig function provided by mf object, the

orbital energies may NOT be sorted.

mo_coeff [2D array] Orbital coefﬁcients.

mo_occ [1D array] Orbital occupancies. The occupancies may NOT be sorted from large to small.

Examples:

>>> from pyscf import gto, scf

>>> mol =gto.M(atom='H000;H001.1', basis='cc-pvdz')

>>> conv, e, mo_e, mo, mo_occ =scf.hf.kernel(scf.hf.SCF(mol), dm0=numpy.eye(mol.

˓→nao_nr()))

>>> print('conv = %s, E(HF) = %.12f'%(conv, e))

conv = True, E(HF) = -1.081170784378

pyscf.scf.hf.level_shift(s,d,f,factor)

Apply level shift ∆to virtual orbitals

𝐹 𝐶 =𝑆𝐶𝐸 (1.1)

𝐹=𝐹+𝑆𝐶Λ𝐶†𝑆(1.2)

Λ𝑖𝑗 =𝛿𝑖𝑗 ∆𝑖∈virtual

0otherwise (1.3)

Returns: New Fock matrix, 2D ndarray

pyscf.scf.hf.make_rdm1(mo_coeff,mo_occ)

One-particle density matrix in AO representation

Args:

mo_coeff [2D ndarray] Orbital coefﬁcients. Each column is one orbital.

mo_occ [1D ndarray] Occupancy

pyscf.scf.hf.mulliken_meta(mol,dm,verbose=5,pre_orth_method=’ANO’,s=None)

Mulliken population analysis, based on meta-Lowdin AOs. In the meta-lowdin, the AOs are grouped in three

sets: core, valence and Rydberg, the orthogonalization are carreid out within each subsets.

Args: mol : an instance of Mole

dm [ndarray or 2-item list of ndarray] Density matrix. ROHF dm is a 2-item list of 2D array

Kwargs: verbose : int or instance of lib.logger.Logger

pre_orth_method [str] Pre-orthogonalization, which localized GTOs for each atom. To obtain the occu-

pied and unoccupied atomic shells, there are three methods

‘ano’ : Project GTOs to ANO basis

‘minao’ : Project GTOs to MINAO basis

‘scf’ : Fraction-averaged RHF

1.6. scf — Mean-ﬁeld methods 123

PySCF Documentation, Release 1.4.0

pyscf.scf.hf.mulliken_pop(mol,dm,s=None,verbose=5)

Mulliken population analysis

𝑀𝑖𝑗 =𝐷𝑖𝑗 𝑆𝑗𝑖

Mulliken charges

𝛿𝑖=

𝑗

𝑀𝑖𝑗

pyscf.scf.hf.mulliken_pop_meta_lowdin_ao(mol,dm,verbose=5,pre_orth_method=’ANO’,

s=None)

Mulliken population analysis, based on meta-Lowdin AOs. In the meta-lowdin, the AOs are grouped in three

sets: core, valence and Rydberg, the orthogonalization are carreid out within each subsets.

Args: mol : an instance of Mole

dm [ndarray or 2-item list of ndarray] Density matrix. ROHF dm is a 2-item list of 2D array

Kwargs: verbose : int or instance of lib.logger.Logger

pre_orth_method [str] Pre-orthogonalization, which localized GTOs for each atom. To obtain the occu-

pied and unoccupied atomic shells, there are three methods

‘ano’ : Project GTOs to ANO basis

‘minao’ : Project GTOs to MINAO basis

‘scf’ : Fraction-averaged RHF

class pyscf.scf.uhf.UHF(mol)

SCF base class. non-relativistic RHF.

Attributes:

verbose [int] Print level. Default value equals to Mole.verbose

max_memory [ﬂoat or int] Allowed memory in MB. Default equals to Mole.max_memory

chkﬁle [str] checkpoint ﬁle to save MOs, orbital energies etc.

conv_tol [ﬂoat] converge threshold. Default is 1e-10

conv_tol_grad [ﬂoat] gradients converge threshold. Default is sqrt(conv_tol)

max_cycle [int] max number of iterations. Default is 50

init_guess [str] initial guess method. It can be one of ‘minao’, ‘atom’, ‘1e’, ‘chkﬁle’. Default is ‘minao’

diis [boolean or object of DIIS class listed in scf.diis] Default is diis.SCF_DIIS. Set it to None

to turn off DIIS.

diis_space [int] DIIS space size. By default, 8 Fock matrices and errors vector are stored.

diis_start_cycle [int] The step to start DIIS. Default is 1.

diis_ﬁle: ‘str’ File to store DIIS vectors and error vectors.

level_shift [ﬂoat or int] Level shift (in AU) for virtual space. Default is 0.

direct_scf [bool] Direct SCF is used by default.

124 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

direct_scf_tol [ﬂoat] Direct SCF cutoff threshold. Default is 1e-13.

callback [function(envs_dict) => None] callback function takes one dict as the argument which is gener-

ated by the builtin function locals(), so that the callback function can access all local variables

in the current envrionment.

conv_check [bool] An extra cycle to check convergence after SCF iterations.

Saved results

converged [bool] SCF converged or not

e_tot [ﬂoat] Total HF energy (electronic energy plus nuclear repulsion)

mo_energy : Orbital energies

mo_occ Orbital occupancy

mo_coeff Orbital coefﬁcients

Examples:

>>> mol =gto.M(atom='H000;H001.1', basis='cc-pvdz')

>>> mf =scf.hf.SCF(mol)

>>> mf.verbose =0

>>> mf.level_shift = .4

>>> mf.scf()

-1.0811707843775884

Attributes for UHF:

nelec [(int, int)] If given, freeze the number of (alpha,beta) electrons to the given value.

level_shift [number or two-element list] level shift (in Eh) for alpha and beta Fock if two-element list is

given.

Examples:

>>> mol =gto.M(atom='O000;H001;H010', basis='ccpvdz', charge=1,

˓→spin=1, verbose=0)

>>> mf =scf.UHF(mol)

>>> mf.kernel()

-75.623975516256706

>>> print('S^2 = %.7f, 2S+1 = %.7f'%mf.spin_square())

S^2 = 0.7570150, 2S+1 = 2.0070027

canonicalize(mf,mo_coeff,mo_occ,fock=None)

Canonicalization diagonalizes the UHF Fock matrix within occupied, virtual subspaces separatedly (with-

out change occupancy).

det_ovlp(mo1,mo2,occ1,occ2,ovlp=None)

Calculate the overlap between two different determinants. It is the product of single values of molecular

orbital overlap matrix.

𝑆12 =⟨Ψ𝐴|Ψ𝐵⟩= (detU)(detV†)

2𝑁



𝑖=1

𝜆𝑖𝑖

where U,V, 𝜆 are unitary matrices and single values generated by single value decomposition(SVD) of

the overlap matrix Owhich is the overlap matrix of two sets of molecular orbitals:

U†OV =Λ

1.6. scf — Mean-ﬁeld methods 125

PySCF Documentation, Release 1.4.0

Args:

mo1, mo2 [2D ndarrays] Molecualr orbital coefﬁcients

occ1, occ2: 2D ndarrays occupation numbers

Return:

A list: the product of single values: ﬂoat x_a, x_b: 1D ndarrays UΛ−1V†They are used to cal-

culate asymmetric density matrix

dip_moment(mol=None,dm=None,unit_symbol=None,verbose=3)

Dipole moment calculation

𝜇𝑥=−

𝜇

𝜈

𝑃𝜇𝜈 (𝜈|𝑥|𝜇) + 

𝐴

𝑄𝐴𝑋𝐴

𝜇𝑦=−

𝜇

𝜈

𝑃𝜇𝜈 (𝜈|𝑦|𝜇) + 

𝐴

𝑄𝐴𝑌𝐴

𝜇𝑧=−

𝜇

𝜈

𝑃𝜇𝜈 (𝜈|𝑧|𝜇) + 

𝐴

𝑄𝐴𝑍𝐴

where 𝜇𝑥, 𝜇𝑦, 𝜇𝑧are the x, y and z components of dipole moment

Args: mol: an instance of Mole

dm [a list of 2D ndarrays] a list of density matrices

Return: A list: the dipole moment on x, y and z component

energy_elec(mf,dm=None,h1e=None,vhf=None)

Electronic energy of Unrestricted Hartree-Fock

Returns: Hartree-Fock electronic energy and the 2-electron part contribution

get_jk(mol=None,dm=None,hermi=1)

Coulomb (J) and exchange (K)

Args:

dm [a list of 2D arrays or a list of 3D arrays] (alpha_dm, beta_dm) or (alpha_dms, beta_dms)

get_veff(mol=None,dm=None,dm_last=0,vhf_last=0,hermi=1)

Unrestricted Hartree-Fock potential matrix of alpha and beta spins, for the given density matrix

𝑉𝛼

𝑖𝑗 =

𝑘𝑙

(𝑖𝑗|𝑘𝑙)(𝛾𝛼

𝑙𝑘 +𝛾𝛽

𝑙𝑘)−

𝑘𝑙

(𝑖𝑙|𝑘𝑗)𝛾𝛼

𝑙𝑘

𝑉𝛽

𝑖𝑗 =

𝑘𝑙

(𝑖𝑗|𝑘𝑙)(𝛾𝛼

𝑙𝑘 +𝛾𝛽

𝑙𝑘)−

𝑘𝑙

(𝑖𝑙|𝑘𝑗)𝛾𝛽

𝑙𝑘

Args: mol : an instance of Mole

dm [a list of ndarrays] A list of density matrices, stored as (alpha,alpha,...,beta,beta,...)

Kwargs:

dm_last [ndarray or a list of ndarrays or 0] The density matrix baseline. When it is not 0, this

function computes the increment of HF potential w.r.t. the reference HF potential matrix.

vhf_last [ndarray or a list of ndarrays or 0] The reference HF potential matrix.

hermi [int] Whether J, K matrix is hermitian

0 : no hermitian or symmetric

126 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

1 : hermitian

2 : anti-hermitian

vhfopt : A class which holds precomputed quantities to optimize the computation of J, K matrices

Returns: 𝑉ℎ𝑓 = (𝑉𝛼, 𝑉 𝛽).𝑉𝛼(and 𝑉𝛽) can be a list matrices, corresponding to the input density

matrices.

Examples:

>>> import numpy

>>> from pyscf import gto, scf

>>> mol =gto.M(atom='H000;H001.1')

>>> dmsa =numpy.random.random((3,mol.nao_nr(),mol.nao_nr()))

>>> dmsb =numpy.random.random((3,mol.nao_nr(),mol.nao_nr()))

>>> dms =numpy.vstack((dmsa,dmsb))

>>> dms.shape

(6, 2, 2)

>>> vhfa, vhfb =scf.uhf.get_veff(mol, dms, hermi=0)

>>> vhfa.shape

(3, 2, 2)

>>> vhfb.shape

(3, 2, 2)

init_guess_by_minao(mol=None,breaksym=True)

Initial guess in terms of the overlap to minimal basis.

make_asym_dm(mo1,mo2,occ1,occ2,x)

One-particle asymmetric density matrix

Args:

mo1, mo2 [2D ndarrays] Molecualr orbital coefﬁcients

occ1, occ2: 2D ndarrays Occupation numbers

x: 2D ndarrays UΛ−1V†. See also det_ovlp()

Return: A list of 2D ndarrays for alpha and beta spin

Examples:

>>> mf1 =scf.UHF(gto.M(atom='H000;F001.3', basis='ccpvdz')).run()

>>> mf2 =scf.UHF(gto.M(atom='H000;F001.4', basis='ccpvdz')).run()

>>> s=gto.intor_cross('int1e_ovlp_sph', mf1.mol, mf2.mol)

>>> det, x =det_ovlp(mf1.mo_coeff, mf1.mo_occ, mf2.mo_coeff, mf2.mo_occ, s)

>>> adm =make_asym_dm(mf1.mo_coeff, mf1.mo_occ, mf2.mo_coeff, mf2.mo_occ, x)

>>> adm.shape

(2, 19, 19)

make_rdm1(mo_coeff=None,mo_occ=None)

One-particle density matrix

Returns: A list of 2D ndarrays for alpha and beta spins

spin_square(mo_coeff=None,s=None)

Spin of the given UHF orbitals

𝑆2=1

2(𝑆+𝑆−+𝑆−𝑆+) + 𝑆2

𝑧

1.6. scf — Mean-ﬁeld methods 127

PySCF Documentation, Release 1.4.0

where 𝑆+=𝑖𝑆𝑖+is effective for all beta occupied orbitals; 𝑆−=𝑖𝑆𝑖−is effective for all alpha

occupied orbitals.

1.There are two possibilities for 𝑆+𝑆−

(a) same electron 𝑆+𝑆−=𝑖𝑠𝑖+𝑠𝑖−,



𝑖⟨𝑈𝐻𝐹 |𝑠𝑖+𝑠𝑖−|𝑈𝐻𝐹 ⟩=

𝑝𝑞 ⟨𝑝|𝑠+𝑠−|𝑞⟩𝛾𝑞𝑝 =𝑛𝛼

2) different electrons 𝑆+𝑆−=𝑠𝑖+𝑠𝑗−,(𝑖̸=𝑗). There are in total 𝑛(𝑛−1) terms. As a

two-particle operator,

⟨𝑆+𝑆−⟩=⟨𝑖𝑗|𝑠+𝑠−|𝑖𝑗⟩−⟨𝑖𝑗|𝑠+𝑠−|𝑗𝑖⟩=−⟨𝑖𝛼|𝑗𝛽⟩⟨𝑗𝛽|𝑖𝛼⟩

2.Similarly, for 𝑆−𝑆+

(a) same electron



𝑖⟨𝑠𝑖−𝑠𝑖+⟩=𝑛𝛽

(a) different electrons

⟨𝑆−𝑆+⟩=−⟨𝑖𝛽|𝑗𝛼⟩⟨𝑗𝛼|𝑖𝛽⟩

2.For 𝑆2

𝑧

(a) same electron

⟨𝑠2

𝑧⟩=1

4(𝑛𝛼+𝑛𝛽)

(a) different electrons

2

𝑖𝑗

(⟨𝑖𝑗|2𝑠𝑧1𝑠𝑧2|𝑖𝑗⟩−⟨𝑖𝑗|2𝑠𝑧1𝑠𝑧2|𝑗𝑖⟩)

4(⟨𝑖𝛼|𝑖𝛼⟩⟨𝑗𝛼|𝑗𝛼⟩−⟨𝑖𝛼|𝑖𝛼⟩⟨𝑗𝛽|𝑗𝛽⟩−⟨𝑖𝛽|𝑖𝛽⟩⟨𝑗𝛼|𝑗𝛼⟩+⟨𝑖𝛽|𝑖𝛽⟩⟨𝑗𝛽|𝑗𝛽⟩)

−1

4(⟨𝑖𝛼|𝑗𝛼⟩⟨𝑗𝛼|𝑖𝛼⟩+⟨𝑖𝛽|𝑗𝛽⟩⟨𝑗𝛽|𝑖𝛽⟩)

4(𝑛2

𝛼−𝑛𝛼𝑛𝛽−𝑛𝛽𝑛𝛼+𝑛2

𝛽)−1

4(𝑛𝛼+𝑛𝛽)

4((𝑛𝛼−𝑛𝛽)2−(𝑛𝛼+𝑛𝛽))

In total

⟨𝑆2⟩=1

2(𝑛𝛼−

𝑖𝑗 ⟨𝑖𝛼|𝑗𝛽⟩⟨𝑗𝛽|𝑖𝛼⟩+𝑛𝛽−

𝑖𝑗 ⟨𝑖𝛽|𝑗𝛼⟩⟨𝑗𝛼|𝑖𝛽⟩) + 1

4(𝑛𝛼−𝑛𝛽)2

Args:

mo [a list of 2 ndarrays] Occupied alpha and occupied beta orbitals

Kwargs:

s[ndarray] AO overlap

Returns: A list of two ﬂoats. The ﬁrst is the expectation value of S^2. The second is the corresponding

2S+1

Examples:

128 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

>>> mol =gto.M(atom='O000;H001;H010', basis='ccpvdz', charge=1,

˓→spin=1, verbose=0)

>>> mf =scf.UHF(mol)

>>> mf.kernel()

-75.623975516256706

>>> mo =(mf.mo_coeff[0][:,mf.mo_occ[0]>0], mf.mo_coeff[1][:,mf.mo_occ[1]>0])

>>> print('S^2 = %.7f, 2S+1 = %.7f'%spin_square(mo, mol.intor('int1e_ovlp_

˓→sph')))

S^2 = 0.7570150, 2S+1 = 2.0070027

pyscf.scf.uhf.analyze(mf,verbose=5,**kwargs)

Analyze the given SCF object: print orbital energies, occupancies; print orbital coefﬁcients; Mulliken population

analysis; Dipole moment

pyscf.scf.uhf.canonicalize(mf,mo_coeff,mo_occ,fock=None)

Canonicalization diagonalizes the UHF Fock matrix within occupied, virtual subspaces separatedly (without

change occupancy).

pyscf.scf.uhf.det_ovlp(mo1,mo2,occ1,occ2,ovlp)

Calculate the overlap between two different determinants. It is the product of single values of molecular orbital

overlap matrix.

𝑆12 =⟨Ψ𝐴|Ψ𝐵⟩= (detU)(detV†)

2𝑁



𝑖=1

𝜆𝑖𝑖

where U,V, 𝜆 are unitary matrices and single values generated by single value decomposition(SVD) of the

overlap matrix Owhich is the overlap matrix of two sets of molecular orbitals:

U†OV =Λ

Args:

mo1, mo2 [2D ndarrays] Molecualr orbital coefﬁcients

occ1, occ2: 2D ndarrays occupation numbers

Return:

A list: the product of single values: ﬂoat x_a, x_b: 1D ndarrays UΛ−1V†They are used to calculate

asymmetric density matrix

pyscf.scf.uhf.dip_moment(mol,dm,unit_symbol=’Debye’,verbose=3)

Dipole moment calculation

𝜇𝑥=−

𝜇

𝜈

𝑃𝜇𝜈 (𝜈|𝑥|𝜇) + 

𝐴

𝑄𝐴𝑋𝐴

𝜇𝑦=−

𝜇

𝜈

𝑃𝜇𝜈 (𝜈|𝑦|𝜇) + 

𝐴

𝑄𝐴𝑌𝐴

𝜇𝑧=−

𝜇

𝜈

𝑃𝜇𝜈 (𝜈|𝑧|𝜇) + 

𝐴

𝑄𝐴𝑍𝐴

where 𝜇𝑥, 𝜇𝑦, 𝜇𝑧are the x, y and z components of dipole moment

Args: mol: an instance of Mole

dm [a list of 2D ndarrays] a list of density matrices

Return: A list: the dipole moment on x, y and z component

1.6. scf — Mean-ﬁeld methods 129

PySCF Documentation, Release 1.4.0

pyscf.scf.uhf.energy_elec(mf,dm=None,h1e=None,vhf=None)

Electronic energy of Unrestricted Hartree-Fock

Returns: Hartree-Fock electronic energy and the 2-electron part contribution

pyscf.scf.uhf.get_grad(mo_coeff,mo_occ,fock_ao)

UHF Gradients

pyscf.scf.uhf.get_veff(mol,dm,dm_last=0,vhf_last=0,hermi=1,vhfopt=None)

Unrestricted Hartree-Fock potential matrix of alpha and beta spins, for the given density matrix

𝑉𝛼

𝑖𝑗 =

𝑘𝑙

(𝑖𝑗|𝑘𝑙)(𝛾𝛼

𝑙𝑘 +𝛾𝛽

𝑙𝑘)−

𝑘𝑙

(𝑖𝑙|𝑘𝑗)𝛾𝛼

𝑙𝑘

𝑉𝛽

𝑖𝑗 =

𝑘𝑙

(𝑖𝑗|𝑘𝑙)(𝛾𝛼

𝑙𝑘 +𝛾𝛽

𝑙𝑘)−

𝑘𝑙

(𝑖𝑙|𝑘𝑗)𝛾𝛽

𝑙𝑘

Args: mol : an instance of Mole

dm [a list of ndarrays] A list of density matrices, stored as (alpha,alpha,...,beta,beta,...)

Kwargs:

dm_last [ndarray or a list of ndarrays or 0] The density matrix baseline. When it is not 0, this function

computes the increment of HF potential w.r.t. the reference HF potential matrix.

vhf_last [ndarray or a list of ndarrays or 0] The reference HF potential matrix.

hermi [int] Whether J, K matrix is hermitian

0 : no hermitian or symmetric

1 : hermitian

2 : anti-hermitian

vhfopt : A class which holds precomputed quantities to optimize the computation of J, K matrices

Returns: 𝑉ℎ𝑓 = (𝑉𝛼, 𝑉 𝛽).𝑉𝛼(and 𝑉𝛽) can be a list matrices, corresponding to the input density matrices.

Examples:

>>> import numpy

>>> from pyscf import gto, scf

>>> mol =gto.M(atom='H000;H001.1')

>>> dmsa =numpy.random.random((3,mol.nao_nr(),mol.nao_nr()))

>>> dmsb =numpy.random.random((3,mol.nao_nr(),mol.nao_nr()))

>>> dms =numpy.vstack((dmsa,dmsb))

>>> dms.shape

(6, 2, 2)

>>> vhfa, vhfb =scf.uhf.get_veff(mol, dms, hermi=0)

>>> vhfa.shape

(3, 2, 2)

>>> vhfb.shape

(3, 2, 2)

pyscf.scf.uhf.init_guess_by_minao(mol,breaksym=True)

Generate initial guess density matrix based on ANO basis, then project the density matrix to the basis set deﬁned

by mol

Returns: Density matrices, a list of 2D ndarrays for alpha and beta spins

130 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

pyscf.scf.uhf.make_asym_dm(mo1,mo2,occ1,occ2,x)

One-particle asymmetric density matrix

Args:

mo1, mo2 [2D ndarrays] Molecualr orbital coefﬁcients

occ1, occ2: 2D ndarrays Occupation numbers

x: 2D ndarrays UΛ−1V†. See also det_ovlp()

Return: A list of 2D ndarrays for alpha and beta spin

Examples:

>>> mf1 =scf.UHF(gto.M(atom='H000;F001.3', basis='ccpvdz')).run()

>>> mf2 =scf.UHF(gto.M(atom='H000;F001.4', basis='ccpvdz')).run()

>>> s=gto.intor_cross('int1e_ovlp_sph', mf1.mol, mf2.mol)

>>> det, x =det_ovlp(mf1.mo_coeff, mf1.mo_occ, mf2.mo_coeff, mf2.mo_occ, s)

>>> adm =make_asym_dm(mf1.mo_coeff, mf1.mo_occ, mf2.mo_coeff, mf2.mo_occ, x)

>>> adm.shape

(2, 19, 19)

pyscf.scf.uhf.make_rdm1(mo_coeff,mo_occ)

One-particle density matrix

Returns: A list of 2D ndarrays for alpha and beta spins

pyscf.scf.uhf.mulliken_meta(mol,dm_ao,verbose=5,pre_orth_method=’ANO’,s=None)

Mulliken population analysis, based on meta-Lowdin AOs.

pyscf.scf.uhf.mulliken_pop(mol,dm,s=None,verbose=5)

Mulliken population analysis

pyscf.scf.uhf.mulliken_pop_meta_lowdin_ao(mol,dm_ao,verbose=5,

pre_orth_method=’ANO’,s=None)

Mulliken population analysis, based on meta-Lowdin AOs.

pyscf.scf.uhf.rhf_to_uhf(mf )

Create UHF object based on the RHF object

pyscf.scf.uhf.spin_square(mo,s=1)

Spin of the given UHF orbitals

𝑆2=1

2(𝑆+𝑆−+𝑆−𝑆+) + 𝑆2

𝑧

where 𝑆+=𝑖𝑆𝑖+is effective for all beta occupied orbitals; 𝑆−=𝑖𝑆𝑖−is effective for all alpha occupied

orbitals.

1.There are two possibilities for 𝑆+𝑆−

(a) same electron 𝑆+𝑆−=𝑖𝑠𝑖+𝑠𝑖−,



𝑖⟨𝑈𝐻𝐹 |𝑠𝑖+𝑠𝑖−|𝑈𝐻𝐹 ⟩=

𝑝𝑞 ⟨𝑝|𝑠+𝑠−|𝑞⟩𝛾𝑞𝑝 =𝑛𝛼

2) different electrons 𝑆+𝑆−=𝑠𝑖+𝑠𝑗−,(𝑖̸=𝑗). There are in total 𝑛(𝑛−1) terms. As a two-

particle operator,

⟨𝑆+𝑆−⟩=⟨𝑖𝑗|𝑠+𝑠−|𝑖𝑗⟩−⟨𝑖𝑗|𝑠+𝑠−|𝑗𝑖⟩=−⟨𝑖𝛼|𝑗𝛽⟩⟨𝑗𝛽|𝑖𝛼⟩

2.Similarly, for 𝑆−𝑆+

1.6. scf — Mean-ﬁeld methods 131

PySCF Documentation, Release 1.4.0

(a) same electron



𝑖⟨𝑠𝑖−𝑠𝑖+⟩=𝑛𝛽

(a) different electrons

⟨𝑆−𝑆+⟩=−⟨𝑖𝛽|𝑗𝛼⟩⟨𝑗𝛼|𝑖𝛽⟩

2.For 𝑆2

𝑧

(a) same electron

⟨𝑠2

𝑧⟩=1

4(𝑛𝛼+𝑛𝛽)

(a) different electrons

2

𝑖𝑗

(⟨𝑖𝑗|2𝑠𝑧1𝑠𝑧2|𝑖𝑗⟩−⟨𝑖𝑗|2𝑠𝑧1𝑠𝑧2|𝑗𝑖⟩)

4(⟨𝑖𝛼|𝑖𝛼⟩⟨𝑗𝛼|𝑗𝛼⟩−⟨𝑖𝛼|𝑖𝛼⟩⟨𝑗𝛽|𝑗𝛽⟩−⟨𝑖𝛽|𝑖𝛽⟩⟨𝑗𝛼|𝑗𝛼⟩+⟨𝑖𝛽|𝑖𝛽⟩⟨𝑗𝛽|𝑗𝛽⟩)

−1

4(⟨𝑖𝛼|𝑗𝛼⟩⟨𝑗𝛼|𝑖𝛼⟩+⟨𝑖𝛽|𝑗𝛽⟩⟨𝑗𝛽|𝑖𝛽⟩)

4(𝑛2

𝛼−𝑛𝛼𝑛𝛽−𝑛𝛽𝑛𝛼+𝑛2

𝛽)−1

4(𝑛𝛼+𝑛𝛽)

4((𝑛𝛼−𝑛𝛽)2−(𝑛𝛼+𝑛𝛽))

In total

⟨𝑆2⟩=1

2(𝑛𝛼−

𝑖𝑗 ⟨𝑖𝛼|𝑗𝛽⟩⟨𝑗𝛽|𝑖𝛼⟩+𝑛𝛽−

𝑖𝑗 ⟨𝑖𝛽|𝑗𝛼⟩⟨𝑗𝛼|𝑖𝛽⟩) + 1

4(𝑛𝛼−𝑛𝛽)2

Args:

mo [a list of 2 ndarrays] Occupied alpha and occupied beta orbitals

Kwargs:

s[ndarray] AO overlap

Returns: A list of two ﬂoats. The ﬁrst is the expectation value of S^2. The second is the corresponding 2S+1

Examples:

>>> mol =gto.M(atom='O000;H001;H010', basis='ccpvdz', charge=1,

˓→spin=1, verbose=0)

>>> mf =scf.UHF(mol)

>>> mf.kernel()

-75.623975516256706

>>> mo =(mf.mo_coeff[0][:,mf.mo_occ[0]>0], mf.mo_coeff[1][:,mf.mo_occ[1]>0])

>>> print('S^2 = %.7f, 2S+1 = %.7f'%spin_square(mo, mol.intor('int1e_ovlp_sph

˓→')))

S^2 = 0.7570150, 2S+1 = 2.0070027

Non-relativistic restricted Hartree-Fock with point group symmetry.

The symmetry are not handled in a separate data structure. Note that during the SCF iteration, the orbitals are

grouped in terms of symmetry irreps. But the orbitals in the result are sorted based on the orbital energies. Func-

tion symm.label_orb_symm can be used to detect the symmetry of the molecular orbitals.

132 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

class pyscf.scf.hf_symm.RHF(mol)

SCF base class. non-relativistic RHF.

Attributes:

verbose [int] Print level. Default value equals to Mole.verbose

max_memory [ﬂoat or int] Allowed memory in MB. Default equals to Mole.max_memory

chkﬁle [str] checkpoint ﬁle to save MOs, orbital energies etc.

conv_tol [ﬂoat] converge threshold. Default is 1e-10

conv_tol_grad [ﬂoat] gradients converge threshold. Default is sqrt(conv_tol)

max_cycle [int] max number of iterations. Default is 50

init_guess [str] initial guess method. It can be one of ‘minao’, ‘atom’, ‘1e’, ‘chkﬁle’. Default is ‘minao’

diis [boolean or object of DIIS class listed in scf.diis] Default is diis.SCF_DIIS. Set it to None

to turn off DIIS.

diis_space [int] DIIS space size. By default, 8 Fock matrices and errors vector are stored.

diis_start_cycle [int] The step to start DIIS. Default is 1.

diis_ﬁle: ‘str’ File to store DIIS vectors and error vectors.

level_shift [ﬂoat or int] Level shift (in AU) for virtual space. Default is 0.

direct_scf [bool] Direct SCF is used by default.

direct_scf_tol [ﬂoat] Direct SCF cutoff threshold. Default is 1e-13.

callback [function(envs_dict) => None] callback function takes one dict as the argument which is gener-

ated by the builtin function locals(), so that the callback function can access all local variables

in the current envrionment.

conv_check [bool] An extra cycle to check convergence after SCF iterations.

Saved results

converged [bool] SCF converged or not

e_tot [ﬂoat] Total HF energy (electronic energy plus nuclear repulsion)

mo_energy : Orbital energies

mo_occ Orbital occupancy

mo_coeff Orbital coefﬁcients

Examples:

>>> mol =gto.M(atom='H000;H001.1', basis='cc-pvdz')

>>> mf =scf.hf.SCF(mol)

>>> mf.verbose =0

>>> mf.level_shift = .4

>>> mf.scf()

-1.0811707843775884

Attributes for symmetry allowed RHF:

irrep_nelec [dict] Specify the number of electrons for particular irrep {‘ir_name’:int,...}. For the irreps

not listed in this dict, the program will choose the occupancy based on the orbital energies.

1.6. scf — Mean-ﬁeld methods 133

PySCF Documentation, Release 1.4.0

Examples:

>>> mol =gto.M(atom='O000;H001;H010', basis='ccpvdz', symmetry=True,

˓→verbose=0)

>>> mf =scf.RHF(mol)

>>> mf.scf()

-76.016789472074251

>>> mf.get_irrep_nelec()

{'A1': 6, 'A2': 0, 'B1': 2, 'B2': 2}

>>> mf.irrep_nelec ={'A2':2}

>>> mf.scf()

-72.768201804695622

>>> mf.get_irrep_nelec()

{'A1': 6, 'A2': 2, 'B1': 2, 'B2': 0}

canonicalize(mf,mo_coeff,mo_occ,fock=None)

Canonicalization diagonalizes the Fock matrix in occupied, open, virtual subspaces separatedly (without

change occupancy).

eig(mf,h,s)

Solve generalized eigenvalue problem, for each irrep. The eigenvalues and eigenvectors are not sorted to

ascending order. Instead, they are grouped based on irreps.

get_irrep_nelec(mol=None,mo_coeff=None,mo_occ=None,s=None)

Electron numbers for each irreducible representation.

Args:

mol [an instance of Mole] To provide irrep_id, and spin-adapted basis

mo_coeff [2D ndarray] Regular orbital coefﬁcients, without grouping for irreps

mo_occ [1D ndarray] Regular occupancy, without grouping for irreps

Returns:

irrep_nelec [dict] The number of electrons for each irrep {‘ir_name’:int,...}.

Examples:

>>> mol =gto.M(atom='O000;H001;H010', basis='ccpvdz',

˓→symmetry=True, verbose=0)

>>> mf =scf.RHF(mol)

>>> mf.scf()

-76.016789472074251

>>> scf.hf_symm.get_irrep_nelec(mol, mf.mo_coeff, mf.mo_occ)

{'A1': 6, 'A2': 0, 'B1': 2, 'B2': 2}

get_occ(mo_energy=None,mo_coeff=None)

We assumed mo_energy are grouped by symmetry irreps, (see function self.eig). The orbitals are sorted

after SCF.

class pyscf.scf.hf_symm.ROHF(mol)

SCF base class. non-relativistic RHF.

Attributes:

verbose [int] Print level. Default value equals to Mole.verbose

max_memory [ﬂoat or int] Allowed memory in MB. Default equals to Mole.max_memory

chkﬁle [str] checkpoint ﬁle to save MOs, orbital energies etc.

134 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

conv_tol [ﬂoat] converge threshold. Default is 1e-10

conv_tol_grad [ﬂoat] gradients converge threshold. Default is sqrt(conv_tol)

max_cycle [int] max number of iterations. Default is 50

init_guess [str] initial guess method. It can be one of ‘minao’, ‘atom’, ‘1e’, ‘chkﬁle’. Default is ‘minao’

diis [boolean or object of DIIS class listed in scf.diis] Default is diis.SCF_DIIS. Set it to None

to turn off DIIS.

diis_space [int] DIIS space size. By default, 8 Fock matrices and errors vector are stored.

diis_start_cycle [int] The step to start DIIS. Default is 1.

diis_ﬁle: ‘str’ File to store DIIS vectors and error vectors.

level_shift [ﬂoat or int] Level shift (in AU) for virtual space. Default is 0.

direct_scf [bool] Direct SCF is used by default.

direct_scf_tol [ﬂoat] Direct SCF cutoff threshold. Default is 1e-13.

callback [function(envs_dict) => None] callback function takes one dict as the argument which is gener-

ated by the builtin function locals(), so that the callback function can access all local variables

in the current envrionment.

conv_check [bool] An extra cycle to check convergence after SCF iterations.

Saved results

converged [bool] SCF converged or not

e_tot [ﬂoat] Total HF energy (electronic energy plus nuclear repulsion)

mo_energy : Orbital energies

mo_occ Orbital occupancy

mo_coeff Orbital coefﬁcients

Examples:

>>> mol =gto.M(atom='H000;H001.1', basis='cc-pvdz')

>>> mf =scf.hf.SCF(mol)

>>> mf.verbose =0

>>> mf.level_shift = .4

>>> mf.scf()

-1.0811707843775884

Attributes for symmetry allowed ROHF:

irrep_nelec [dict] Specify the number of alpha/beta electrons for particular irrep {‘ir_name’:(int,int), ...}.

For the irreps not listed in these dicts, the program will choose the occupancy based on the orbital

energies.

Examples:

>>> mol =gto.M(atom='O000;H001;H010', basis='ccpvdz', symmetry=True,

˓→charge=1, spin=1, verbose=0)

>>> mf =scf.RHF(mol)

>>> mf.scf()

-75.619358861084052

>>> mf.get_irrep_nelec()

{'A1': (3, 3), 'A2': (0, 0), 'B1': (1, 1), 'B2': (1, 0)}

1.6. scf — Mean-ﬁeld methods 135

PySCF Documentation, Release 1.4.0

>>> mf.irrep_nelec ={'B1': (1,0)}

>>> mf.scf()

-75.425669486776457

>>> mf.get_irrep_nelec()

{'A1': (3, 3), 'A2': (0, 0), 'B1': (1, 0), 'B2': (1, 1)}

canonicalize(mo_coeff,mo_occ,fock=None)

Canonicalization diagonalizes the Fock matrix in occupied, open, virtual subspaces separatedly (without

change occupancy).

eig(mf,h,s)

Solve generalized eigenvalue problem, for each irrep. The eigenvalues and eigenvectors are not sorted to

ascending order. Instead, they are grouped based on irreps.

pyscf.scf.hf_symm.analyze(mf,verbose=5,**kwargs)

Analyze the given SCF object: print orbital energies, occupancies; print orbital coefﬁcients; Occupancy for each

irreps; Mulliken population analysis

pyscf.scf.hf_symm.canonicalize(mf,mo_coeff,mo_occ,fock=None)

Canonicalization diagonalizes the Fock matrix in occupied, open, virtual subspaces separatedly (without change

occupancy).

pyscf.scf.hf_symm.eig(mf,h,s)

Solve generalized eigenvalue problem, for each irrep. The eigenvalues and eigenvectors are not sorted to as-

cending order. Instead, they are grouped based on irreps.

pyscf.scf.hf_symm.get_irrep_nelec(mol,mo_coeff,mo_occ,s=None)

Electron numbers for each irreducible representation.

Args:

mol [an instance of Mole] To provide irrep_id, and spin-adapted basis

mo_coeff [2D ndarray] Regular orbital coefﬁcients, without grouping for irreps

mo_occ [1D ndarray] Regular occupancy, without grouping for irreps

Returns:

irrep_nelec [dict] The number of electrons for each irrep {‘ir_name’:int,...}.

Examples:

>>> mol =gto.M(atom='O000;H001;H010', basis='ccpvdz', symmetry=True,

˓→verbose=0)

>>> mf =scf.RHF(mol)

>>> mf.scf()

-76.016789472074251

>>> scf.hf_symm.get_irrep_nelec(mol, mf.mo_coeff, mf.mo_occ)

{'A1': 6, 'A2': 0, 'B1': 2, 'B2': 2}

pyscf.scf.hf_symm.so2ao_mo_coeff(so,irrep_mo_coeff )

Transfer the basis of MO coefﬁcients, from spin-adapted basis to AO basis

Non-relativistic unrestricted Hartree-Fock with point group symmetry.

class pyscf.scf.uhf_symm.UHF(mol)

SCF base class. non-relativistic RHF.

Attributes:

136 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

verbose [int] Print level. Default value equals to Mole.verbose

max_memory [ﬂoat or int] Allowed memory in MB. Default equals to Mole.max_memory

chkﬁle [str] checkpoint ﬁle to save MOs, orbital energies etc.

conv_tol [ﬂoat] converge threshold. Default is 1e-10

conv_tol_grad [ﬂoat] gradients converge threshold. Default is sqrt(conv_tol)

max_cycle [int] max number of iterations. Default is 50

init_guess [str] initial guess method. It can be one of ‘minao’, ‘atom’, ‘1e’, ‘chkﬁle’. Default is ‘minao’

diis [boolean or object of DIIS class listed in scf.diis] Default is diis.SCF_DIIS. Set it to None

to turn off DIIS.

diis_space [int] DIIS space size. By default, 8 Fock matrices and errors vector are stored.

diis_start_cycle [int] The step to start DIIS. Default is 1.

diis_ﬁle: ‘str’ File to store DIIS vectors and error vectors.

level_shift [ﬂoat or int] Level shift (in AU) for virtual space. Default is 0.

direct_scf [bool] Direct SCF is used by default.

direct_scf_tol [ﬂoat] Direct SCF cutoff threshold. Default is 1e-13.

callback [function(envs_dict) => None] callback function takes one dict as the argument which is gener-

ated by the builtin function locals(), so that the callback function can access all local variables

in the current envrionment.

conv_check [bool] An extra cycle to check convergence after SCF iterations.

Saved results

converged [bool] SCF converged or not

e_tot [ﬂoat] Total HF energy (electronic energy plus nuclear repulsion)

mo_energy : Orbital energies

mo_occ Orbital occupancy

mo_coeff Orbital coefﬁcients

Examples:

>>> mol =gto.M(atom='H000;H001.1', basis='cc-pvdz')

>>> mf =scf.hf.SCF(mol)

>>> mf.verbose =0

>>> mf.level_shift = .4

>>> mf.scf()

-1.0811707843775884

Attributes for UHF:

nelec [(int, int)] If given, freeze the number of (alpha,beta) electrons to the given value.

level_shift [number or two-element list] level shift (in Eh) for alpha and beta Fock if two-element list is

given.

Examples:

1.6. scf — Mean-ﬁeld methods 137

PySCF Documentation, Release 1.4.0

>>> mol =gto.M(atom='O000;H001;H010', basis='ccpvdz', charge=1,

˓→spin=1, verbose=0)

>>> mf =scf.UHF(mol)

>>> mf.kernel()

-75.623975516256706

>>> print('S^2 = %.7f, 2S+1 = %.7f'%mf.spin_square())

S^2 = 0.7570150, 2S+1 = 2.0070027

Attributes for symmetry allowed UHF:

irrep_nelec [dict] Specify the number of alpha/beta electrons for particular irrep {‘ir_name’:(int,int), ...}.

For the irreps not listed in these dicts, the program will choose the occupancy based on the orbital

energies.

Examples:

>>> mol =gto.M(atom='O000;H001;H010', basis='ccpvdz', symmetry=True,

˓→charge=1, spin=1, verbose=0)

>>> mf =scf.RHF(mol)

>>> mf.scf()

-75.623975516256692

>>> mf.get_irrep_nelec()

{'A1': (3, 3), 'A2': (0, 0), 'B1': (1, 1), 'B2': (1, 0)}

>>> mf.irrep_nelec ={'B1': (1,0)}

>>> mf.scf()

-75.429189192031131

>>> mf.get_irrep_nelec()

{'A1': (3, 3), 'A2': (0, 0), 'B1': (1, 0), 'B2': (1, 1)}

canonicalize(mf,mo_coeff,mo_occ,fock=None)

Canonicalization diagonalizes the UHF Fock matrix in occupied, virtual subspaces separatedly (without

change occupancy).

get_irrep_nelec(mol=None,mo_coeff=None,mo_occ=None,s=None)

Alpha/beta electron numbers for each irreducible representation.

Args:

mol [an instance of Mole] To provide irrep_id, and spin-adapted basis

mo_occ [a list of 1D ndarray] Regular occupancy, without grouping for irreps

mo_coeff [a list of 2D ndarray] Regular orbital coefﬁcients, without grouping for irreps

Returns:

irrep_nelec [dict] The number of alpha/beta electrons for each irrep {‘ir_name’:(int,int), ...}.

Examples:

>>> mol =gto.M(atom='O000;H001;H010', basis='ccpvdz',

˓→symmetry=True, charge=1, spin=1, verbose=0)

>>> mf =scf.UHF(mol)

>>> mf.scf()

-75.623975516256721

>>> scf.uhf_symm.get_irrep_nelec(mol, mf.mo_coeff, mf.mo_occ)

{'A1': (3, 3), 'A2': (0, 0), 'B1': (1, 1), 'B2': (1, 0)}

138 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

get_occ(mo_energy=None,mo_coeff=None)

We assumed mo_energy are grouped by symmetry irreps, (see function self.eig). The orbitals are sorted

after SCF.

pyscf.scf.uhf_symm.canonicalize(mf,mo_coeff,mo_occ,fock=None)

Canonicalization diagonalizes the UHF Fock matrix in occupied, virtual subspaces separatedly (without change

occupancy).

pyscf.scf.uhf_symm.get_irrep_nelec(mol,mo_coeff,mo_occ,s=None)

Alpha/beta electron numbers for each irreducible representation.

Args:

mol [an instance of Mole] To provide irrep_id, and spin-adapted basis

mo_occ [a list of 1D ndarray] Regular occupancy, without grouping for irreps

mo_coeff [a list of 2D ndarray] Regular orbital coefﬁcients, without grouping for irreps

Returns:

irrep_nelec [dict] The number of alpha/beta electrons for each irrep {‘ir_name’:(int,int), ...}.

Examples:

>>> mol =gto.M(atom='O000;H001;H010', basis='ccpvdz', symmetry=True,

˓→charge=1, spin=1, verbose=0)

>>> mf =scf.UHF(mol)

>>> mf.scf()

-75.623975516256721

>>> scf.uhf_symm.get_irrep_nelec(mol, mf.mo_coeff, mf.mo_occ)

{'A1': (3, 3), 'A2': (0, 0), 'B1': (1, 1), 'B2': (1, 0)}

Relativistic Hartree-Fock

Dirac Hartree-Fock

pyscf.scf.dhf.DHF

alias of UHF

class pyscf.scf.dhf.RHF(mol)

Dirac-RHF

make_rdm1(mo_coeff=None,mo_occ=None)

D/2 = psi_i^dagpsi_i = psi_{Ti}^dagpsi_{Ti} D(UHF) = psi_i^dagpsi_i + psi_{Ti}^dagpsi_{Ti} RHF

average the density of spin up and spin down: D(RHF) = (D(UHF) + T[D(UHF)])/2

class pyscf.scf.dhf.UHF(mol)

SCF base class. non-relativistic RHF.

Attributes:

verbose [int] Print level. Default value equals to Mole.verbose

max_memory [ﬂoat or int] Allowed memory in MB. Default equals to Mole.max_memory

chkﬁle [str] checkpoint ﬁle to save MOs, orbital energies etc.

conv_tol [ﬂoat] converge threshold. Default is 1e-10

conv_tol_grad [ﬂoat] gradients converge threshold. Default is sqrt(conv_tol)

max_cycle [int] max number of iterations. Default is 50

1.6. scf — Mean-ﬁeld methods 139

PySCF Documentation, Release 1.4.0

init_guess [str] initial guess method. It can be one of ‘minao’, ‘atom’, ‘1e’, ‘chkﬁle’. Default is ‘minao’

diis [boolean or object of DIIS class listed in scf.diis] Default is diis.SCF_DIIS. Set it to None

to turn off DIIS.

diis_space [int] DIIS space size. By default, 8 Fock matrices and errors vector are stored.

diis_start_cycle [int] The step to start DIIS. Default is 1.

diis_ﬁle: ‘str’ File to store DIIS vectors and error vectors.

level_shift [ﬂoat or int] Level shift (in AU) for virtual space. Default is 0.

direct_scf [bool] Direct SCF is used by default.

direct_scf_tol [ﬂoat] Direct SCF cutoff threshold. Default is 1e-13.

callback [function(envs_dict) => None] callback function takes one dict as the argument which is gener-

ated by the builtin function locals(), so that the callback function can access all local variables

in the current envrionment.

conv_check [bool] An extra cycle to check convergence after SCF iterations.

Saved results

converged [bool] SCF converged or not

e_tot [ﬂoat] Total HF energy (electronic energy plus nuclear repulsion)

mo_energy : Orbital energies

mo_occ Orbital occupancy

mo_coeff Orbital coefﬁcients

Examples:

>>> mol =gto.M(atom='H000;H001.1', basis='cc-pvdz')

>>> mf =scf.hf.SCF(mol)

>>> mf.verbose =0

>>> mf.level_shift = .4

>>> mf.scf()

-1.0811707843775884

Attributes for Dirac-Hartree-Fock

with_ssss [bool, for Dirac-Hartree-Fock only] If False, ignore small component integrals (SS|SS). De-

fault is True.

with_gaunt [bool, for Dirac-Hartree-Fock only] Default is False.

with_breit [bool, for Dirac-Hartree-Fock only] Gaunt + gauge term. Default is False.

Examples:

>>> mol =gto.M(atom='H000;H001', basis='ccpvdz', verbose=0)

>>> mf =scf.RHF(mol)

>>> e0 =mf.scf()

>>> mf =scf.DHF(mol)

>>> e1 =mf.scf()

>>> print('Relativistic effects = %.12f'%(e1-e0))

Relativistic effects = -0.000008854205

140 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

get_veff(mol=None,dm=None,dm_last=0,vhf_last=0,hermi=1)

Dirac-Coulomb

init_guess_by_minao(mol=None)

Initial guess in terms of the overlap to minimal basis.

pyscf.scf.dhf.get_grad(mo_coeff,mo_occ,fock_ao)

DHF Gradients

pyscf.scf.dhf.init_guess_by_1e(mol)

Initial guess from one electron system.

pyscf.scf.dhf.init_guess_by_atom(mol)

Initial guess from atom calculation.

pyscf.scf.dhf.init_guess_by_minao(mol)

Initial guess in terms of the overlap to minimal basis.

pyscf.scf.dhf.kernel(mf,conv_tol=1e-09,conv_tol_grad=None,dump_chk=True,dm0=None,call-

back=None,conv_check=True)

the modiﬁed SCF kernel for Dirac-Hartree-Fock. In this kernel, the SCF is carried out in three steps. First the 2-

electron part is approximated by large component integrals (LL|LL); Next, (SS|LL) the interaction between large

and small components are added; Finally, converge the SCF with the small component contributions (SS|SS)

pyscf.scf.dhf.time_reversal_matrix(mol,mat)

T(A_ij) = A[T(i),T(j)]^*

addons

pyscf.scf.addons.convert_to_rhf(mf,out=None,convert_df=None)

Convert the given mean-ﬁeld object to the corresponding restricted HF/KS object

Args: mf : SCF object

Kwargs

convert_df [bool] Whether to convert the DF-SCF object to the normal SCF object. This conversion is

not applied by default.

Returns: An unrestricted SCF object

pyscf.scf.addons.convert_to_uhf(mf,out=None,convert_df=None)

Convert the given mean-ﬁeld object to the corresponding unrestricted HF/KS object

Args: mf : SCF object

Kwargs

convert_df [bool] Whether to convert the DF-SCF object to the normal SCF object. This conversion is

not applied by default.

Returns: An unrestricted SCF object

pyscf.scf.addons.dynamic_level_shift(mf,factor=1.0)

Dynamically change the level shift in each SCF cycle. The level shift value is set to (HF energy change * factor)

pyscf.scf.addons.dynamic_level_shift_(mf,factor=1.0)

Dynamically change the level shift in each SCF cycle. The level shift value is set to (HF energy change * factor)

pyscf.scf.addons.dynamic_sz_(mf )

For UHF, allowing the Sz value being changed during SCF iteration. Determine occupation of alpha and beta

electrons based on energy spectrum

1.6. scf — Mean-ﬁeld methods 141

PySCF Documentation, Release 1.4.0

pyscf.scf.addons.float_occ(mf )

For UHF, allowing the Sz value being changed during SCF iteration. Determine occupation of alpha and beta

electrons based on energy spectrum

pyscf.scf.addons.float_occ_(mf )

For UHF, allowing the Sz value being changed during SCF iteration. Determine occupation of alpha and beta

electrons based on energy spectrum

pyscf.scf.addons.mom_occ(mf,occorb,setocc)

Use maximum overlap method to determine occupation number for each orbital in every iteration. It can be

applied to unrestricted HF/KS and restricted open-shell HF/KS.

pyscf.scf.addons.mom_occ_(mf,occorb,setocc)

Use maximum overlap method to determine occupation number for each orbital in every iteration. It can be

applied to unrestricted HF/KS and restricted open-shell HF/KS.

pyscf.scf.addons.project_mo_nr2nr(mol1,mo1,mol2)

Project orbital coefﬁcients

|𝜓1>=|𝐴𝑂1> 𝐶1

|𝜓2>=𝑃|𝜓1>=|𝐴𝑂2> 𝑆−1< 𝐴𝑂2|𝐴𝑂1> 𝐶1 = |𝐴𝑂2> 𝐶2

𝐶2 = 𝑆−1< 𝐴𝑂2|𝐴𝑂1> 𝐶1

pyscf.scf.addons.symm_allow_occ(mf,tol=0.001)

search the unoccupied orbitals, choose the lowest sets which do not break symmetry as the occupied orbitals

pyscf.scf.addons.symm_allow_occ_(mf,tol=0.001)

search the unoccupied orbitals, choose the lowest sets which do not break symmetry as the occupied orbitals

pyscf.scf.chkfile.dump_scf(mol,chkﬁle,e_tot,mo_energy,mo_coeff,mo_occ,over-

write_mol=True)

save temporary results

DIIS

class pyscf.scf.diis.ADIIS(dev=None,ﬁlename=None)

Ref: JCP, 132, 054109

class pyscf.scf.diis.EDIIS(dev=None,ﬁlename=None)

SCF-EDIIS Ref: JCP 116, 8255

1.7 ao2mo — Integral transformations

1.7.1 General Integral transformation module

Simple usage:

>>> from pyscf import gto, scf, ao2mo

>>> mol =gto.M(atom='H000;F001')

>>> mf =scf.RHF(mol).run()

>>> mo_ints =ao2mo.kernel(mol, mf.mo_coeff)

142 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

1.7.2 incore

pyscf.ao2mo.incore.full(eri_ao,mo_coeff,verbose=0,compact=True,**kwargs)

MO integral transformation for the given orbital.

Args:

eri_ao [ndarray] AO integrals, can be either 8-fold or 4-fold symmetry.

mo_coeff [ndarray] Transform (ij|kl) with the same set of orbitals.

Kwargs:

verbose [int] Print level

compact [bool] When compact is True, the returned MO integrals have 4-fold symmetry. Otherwise,

return the “plain” MO integrals.

Returns: 2D array of transformed MO integrals. The MO integrals may or may not have the permutation

symmetry (controlled by the kwargs compact)

Examples:

>>> from pyscf import gto

>>> from pyscf.scf import _vhf

>>> from pyscf import ao2mo

>>> mol =gto.M(atom='O000;H010;H001', basis='sto3g')

>>> eri =mol.intor('int2e_sph', aosym='s8')

>>> mo1 =numpy.random.random((mol.nao_nr(), 10))

>>> eri1 =ao2mo.incore.full(eri, mo1)

>>> print(eri1.shape)

(55, 55)

>>> eri1 =ao2mo.incore.full(eri, mo1, compact=False)

>>> print(eri1.shape)

(100, 100)

pyscf.ao2mo.incore.general(eri_ao,mo_coeffs,verbose=0,compact=True,**kwargs)

For the given four sets of orbitals, transfer the 8-fold or 4-fold 2e AO integrals to MO integrals.

Args:

eri_ao [ndarray] AO integrals, can be either 8-fold or 4-fold symmetry.

mo_coeffs [4-item list of ndarray] Four sets of orbital coefﬁcients, corresponding to the four indices of

(ij|kl)

Kwargs:

verbose [int] Print level

compact [bool] When compact is True, depending on the four oribital sets, the returned MO integrals

has (up to 4-fold) permutation symmetry. If it’s False, the function will abandon any permutation

symmetry, and return the “plain” MO integrals

Returns: 2D array of transformed MO integrals. The MO integrals may or may not have the permutation

symmetry, depending on the given orbitals, and the kwargs compact. If the four sets of orbitals are

identical, the MO integrals will at most have 4-fold symmetry.

Examples:

>>> from pyscf import gto

>>> from pyscf.scf import _vhf

>>> from pyscf import ao2mo

1.7. ao2mo — Integral transformations 143

PySCF Documentation, Release 1.4.0

>>> mol =gto.M(atom='O000;H010;H001', basis='sto3g')

>>> eri =mol.intor('int2e_sph', aosym='s8')

>>> mo1 =numpy.random.random((mol.nao_nr(), 10))

>>> mo2 =numpy.random.random((mol.nao_nr(), 8))

>>> mo3 =numpy.random.random((mol.nao_nr(), 6))

>>> mo4 =numpy.random.random((mol.nao_nr(), 4))

>>> eri1 =ao2mo.incore.general(eri, (mo1,mo2,mo3,mo4))

>>> print(eri1.shape)

(80, 24)

>>> eri1 =ao2mo.incore.general(eri, (mo1,mo2,mo3,mo3))

>>> print(eri1.shape)

(80, 21)

>>> eri1 =ao2mo.incore.general(eri, (mo1,mo2,mo3,mo3), compact=False)

>>> print(eri1.shape)

(80, 36)

>>> eri1 =ao2mo.incore.general(eri, (mo1,mo1,mo2,mo2))

>>> print(eri1.shape)

(55, 36)

>>> eri1 =ao2mo.incore.general(eri, (mo1,mo2,mo1,mo2))

>>> print(eri1.shape)

(80, 80)

pyscf.ao2mo.incore.half_e1(eri_ao,mo_coeffs,compact=True)

Given two set of orbitals, half transform the (ij| pair of 8-fold or 4-fold AO integrals (ij|kl)

Args:

eri_ao [ndarray] AO integrals, can be either 8-fold or 4-fold symmetry.

mo_coeffs [list of ndarray] Two sets of orbital coefﬁcients, corresponding to the i, j indices of (ij|kl)

Kwargs:

compact [bool] When compact is True, the returned MO integrals uses the highest possible permutation

symmetry. If it’s False, the function will abandon any permutation symmetry, and return the “plain”

MO integrals

Returns: ndarray of transformed MO integrals. The MO integrals may or may not have the permutation sym-

metry, depending on the given orbitals, and the kwargs compact.

Examples:

>>> from pyscf import gto

>>> from pyscf import ao2mo

>>> mol =gto.M(atom='O000;H010;H001', basis='sto3g')

>>> eri =mol.intor('int2e_sph', aosym='s8')

>>> mo1 =numpy.random.random((mol.nao_nr(), 10))

>>> mo2 =numpy.random.random((mol.nao_nr(), 8))

>>> eri1 =ao2mo.incore.half_e1(eri, (mo1,mo2))

>>> print(eri1.shape)

(80, 28)

>>> eri1 =ao2mo.incore.half_e1(eri, (mo1,mo2), compact=False)

>>> print(eri1.shape)

(80, 28)

>>> eri1 =ao2mo.incore.half_e1(eri, (mo1,mo1))

>>> print(eri1.shape)

(55, 28)

144 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

1.7.3 outcore

pyscf.ao2mo.outcore.full(mol,mo_coeff,eriﬁle,dataname=’eri_mo’,tmpdir=None,in-

tor=’int2e_sph’,aosym=’s4’,comp=1,max_memory=2000,

ioblk_size=256,verbose=2,compact=True)

Transfer arbitrary spherical AO integrals to MO integrals for given orbitals

Args:

mol [Mole object] AO integrals will be generated in terms of mol._atm, mol._bas, mol._env

mo_coeff [ndarray] Transform (ij|kl) with the same set of orbitals.

eriﬁle [str or h5py File or h5py Group object] To store the transformed integrals, in HDF5 format.

Kwargs:

dataname [str] The dataset name in the eriﬁle (ref the hierarchy of HDF5 format http://www.hdfgroup.

org/HDF5/doc1.6/UG/09_Groups.html). By assigning different dataname, the existed integral ﬁle

can be reused. If the eriﬁle contains the dataname, the new integrals data will overwrite the old one.

tmpdir [str] The directory where to temporarily store the intermediate data (the half-transformed inte-

grals). By default, it’s controlled by shell environment variable TMPDIR. The disk space require-

ment is about comp*mo_coeffs[0].shape[1]*mo_coeffs[1].shape[1]*nao**2

intor [str] Name of the 2-electron integral. Ref to getints_by_shell() for the complete list of

available 2-electron integral names

aosym [int or str] Permutation symmetry for the AO integrals

4 or ‘4’ or ‘s4’: 4-fold symmetry (default)

‘2ij’ or ‘s2ij’ : symmetry between i, j in (ij|kl)

‘2kl’ or ‘s2kl’ : symmetry between k, l in (ij|kl)

1 or ‘1’ or ‘s1’: no symmetry

‘a4ij’ : 4-fold symmetry with anti-symmetry between i, j in (ij|kl) (TODO)

‘a4kl’ : 4-fold symmetry with anti-symmetry between k, l in (ij|kl) (TODO)

‘a2ij’ : anti-symmetry between i, j in (ij|kl) (TODO)

‘a2kl’ : anti-symmetry between k, l in (ij|kl) (TODO)

comp [int] Components of the integrals, e.g. int2e_ip_sph has 3 components.

max_memory [ﬂoat or int] The maximum size of cache to use (in MB), large cache may not improve

performance.

ioblk_size [ﬂoat or int] The block size for IO, large block size may not improve performance

verbose [int] Print level

compact [bool] When compact is True, depending on the four oribital sets, the returned MO integrals

has (up to 4-fold) permutation symmetry. If it’s False, the function will abandon any permutation

symmetry, and return the “plain” MO integrals

Returns: None

Examples:

>>> from pyscf import gto

>>> from pyscf import ao2mo

>>> import h5py

1.7. ao2mo — Integral transformations 145

PySCF Documentation, Release 1.4.0

>>> def view(h5file, dataname='eri_mo'):

... f5 =h5py.File(h5file)

... print('dataset %s, shape %s'%(str(f5.keys()), str(f5[dataname].shape)))

... f5.close()

>>> mol =gto.M(atom='O000;H010;H001', basis='sto3g')

>>> mo1 =numpy.random.random((mol.nao_nr(), 10))

>>> ao2mo.outcore.full(mol, mo1, 'full.h5')

>>> view('full.h5')

dataset ['eri_mo'], shape (55, 55)

>>> ao2mo.outcore.full(mol, mo1, 'full.h5', dataname='new', compact=False)

>>> view('full.h5','new')

dataset ['eri_mo', 'new'], shape (100, 100)

>>> ao2mo.outcore.full(mol, mo1, 'full.h5', intor='int2e_ip1_sph', aosym='s1',

˓→comp=3)

>>> view('full.h5')

dataset ['eri_mo', 'new'], shape (3, 100, 100)

>>> ao2mo.outcore.full(mol, mo1, 'full.h5', intor='int2e_ip1_sph', aosym='s2kl',

˓→comp=3)

>>> view('full.h5')

dataset ['eri_mo', 'new'], shape (3, 100, 55)

pyscf.ao2mo.outcore.full_iofree(mol,mo_coeff,intor=’int2e_sph’,aosym=’s4’,comp=1,

max_memory=2000,ioblk_size=256,verbose=2,com-

pact=True)

Transfer arbitrary spherical AO integrals to MO integrals for given orbitals This function is a wrap for

ao2mo.outcore.general(). It’s not really IO free. The returned MO integrals are held in memory.

For backward compatibility, it is used to replace the non-existed function direct.full_iofree.

Args:

mol [Mole object] AO integrals will be generated in terms of mol._atm, mol._bas, mol._env

mo_coeff [ndarray] Transform (ij|kl) with the same set of orbitals.

eriﬁle [str] To store the transformed integrals, in HDF5 format.

Kwargs

dataname [str] The dataset name in the eriﬁle (ref the hierarchy of HDF5 format http://www.hdfgroup.

org/HDF5/doc1.6/UG/09_Groups.html). By assigning different dataname, the existed integral ﬁle

can be reused. If the eriﬁle contains the dataname, the new integrals data will overwrite the old one.

tmpdir [str] The directory where to temporarily store the intermediate data (the half-transformed inte-

grals). By default, it’s controlled by shell environment variable TMPDIR. The disk space require-

ment is about comp*mo_coeffs[0].shape[1]*mo_coeffs[1].shape[1]*nao**2

intor [str] Name of the 2-electron integral. Ref to getints_by_shell() for the complete list of

available 2-electron integral names

aosym [int or str] Permutation symmetry for the AO integrals

4 or ‘4’ or ‘s4’: 4-fold symmetry (default)

‘2ij’ or ‘s2ij’ : symmetry between i, j in (ij|kl)

‘2kl’ or ‘s2kl’ : symmetry between k, l in (ij|kl)

1 or ‘1’ or ‘s1’: no symmetry

‘a4ij’ : 4-fold symmetry with anti-symmetry between i, j in (ij|kl) (TODO)

‘a4kl’ : 4-fold symmetry with anti-symmetry between k, l in (ij|kl) (TODO)

‘a2ij’ : anti-symmetry between i, j in (ij|kl) (TODO)

146 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

‘a2kl’ : anti-symmetry between k, l in (ij|kl) (TODO)

comp [int] Components of the integrals, e.g. int2e_ip_sph has 3 components.

verbose [int] Print level

max_memory [ﬂoat or int] The maximum size of cache to use (in MB), large cache may not improve

performance.

ioblk_size [ﬂoat or int] The block size for IO, large block size may not improve performance

verbose [int] Print level

compact [bool] When compact is True, depending on the four oribital sets, the returned MO integrals

has (up to 4-fold) permutation symmetry. If it’s False, the function will abandon any permutation

symmetry, and return the “plain” MO integrals

Returns: 2D/3D MO-integral array. They may or may not have the permutation symmetry, depending on the

given orbitals, and the kwargs compact. If the four sets of orbitals are identical, the MO integrals will at

most have 4-fold symmetry.

Examples:

>>> from pyscf import gto

>>> from pyscf import ao2mo

>>> mol =gto.M(atom='O000;H010;H001', basis='sto3g')

>>> mo1 =numpy.random.random((mol.nao_nr(), 10))

>>> eri1 =ao2mo.outcore.full_iofree(mol, mo1)

>>> print(eri1.shape)

(55, 55)

>>> eri1 =ao2mo.outcore.full_iofree(mol, mo1, compact=False)

>>> print(eri1.shape)

(100, 100)

>>> eri1 =ao2mo.outcore.full_iofree(mol, mo1, intor='int2e_ip1_sph', aosym='s1',

˓→comp=3)

>>> print(eri1.shape)

(3, 100, 100)

>>> eri1 =ao2mo.outcore.full_iofree(mol, mo1, intor='int2e_ip1_sph', aosym='s2kl

˓→', comp=3)

>>> print(eri1.shape)

(3, 100, 55)

pyscf.ao2mo.outcore.general(mol,mo_coeffs,eriﬁle,dataname=’eri_mo’,tmpdir=None,in-

tor=’int2e_sph’,aosym=’s4’,comp=1,max_memory=2000,

ioblk_size=256,verbose=2,compact=True)

For the given four sets of orbitals, transfer arbitrary spherical AO integrals to MO integrals on the ﬂy.

Args:

mol [Mole object] AO integrals will be generated in terms of mol._atm, mol._bas, mol._env

mo_coeffs [4-item list of ndarray] Four sets of orbital coefﬁcients, corresponding to the four indices of

(ij|kl)

eriﬁle [str or h5py File or h5py Group object] To store the transformed integrals, in HDF5 format.

Kwargs

dataname [str] The dataset name in the eriﬁle (ref the hierarchy of HDF5 format http://www.hdfgroup.

org/HDF5/doc1.6/UG/09_Groups.html). By assigning different dataname, the existed integral ﬁle

can be reused. If the eriﬁle contains the dataname, the new integrals data will overwrite the old one.

1.7. ao2mo — Integral transformations 147

PySCF Documentation, Release 1.4.0

tmpdir [str] The directory where to temporarily store the intermediate data (the half-transformed inte-

grals). By default, it’s controlled by shell environment variable TMPDIR. The disk space require-

ment is about comp*mo_coeffs[0].shape[1]*mo_coeffs[1].shape[1]*nao**2

intor [str] Name of the 2-electron integral. Ref to getints_by_shell() for the complete list of

available 2-electron integral names

aosym [int or str] Permutation symmetry for the AO integrals

4 or ‘4’ or ‘s4’: 4-fold symmetry (default)

‘2ij’ or ‘s2ij’ : symmetry between i, j in (ij|kl)

‘2kl’ or ‘s2kl’ : symmetry between k, l in (ij|kl)

1 or ‘1’ or ‘s1’: no symmetry

‘a4ij’ : 4-fold symmetry with anti-symmetry between i, j in (ij|kl) (TODO)

‘a4kl’ : 4-fold symmetry with anti-symmetry between k, l in (ij|kl) (TODO)

‘a2ij’ : anti-symmetry between i, j in (ij|kl) (TODO)

‘a2kl’ : anti-symmetry between k, l in (ij|kl) (TODO)

comp [int] Components of the integrals, e.g. int2e_ip_sph has 3 components.

max_memory [ﬂoat or int] The maximum size of cache to use (in MB), large cache may not improve

performance.

ioblk_size [ﬂoat or int] The block size for IO, large block size may not improve performance

verbose [int] Print level

compact [bool] When compact is True, depending on the four oribital sets, the returned MO integrals

has (up to 4-fold) permutation symmetry. If it’s False, the function will abandon any permutation

symmetry, and return the “plain” MO integrals

Returns: None

Examples:

>>> from pyscf import gto

>>> from pyscf import ao2mo

>>> import h5py

>>> def view(h5file, dataname='eri_mo'):

... f5 =h5py.File(h5file)

... print('dataset %s, shape %s'%(str(f5.keys()), str(f5[dataname].shape)))

... f5.close()

>>> mol =gto.M(atom='O000;H010;H001', basis='sto3g')

>>> mo1 =numpy.random.random((mol.nao_nr(), 10))

>>> mo2 =numpy.random.random((mol.nao_nr(), 8))

>>> mo3 =numpy.random.random((mol.nao_nr(), 6))

>>> mo4 =numpy.random.random((mol.nao_nr(), 4))

>>> ao2mo.outcore.general(mol, (mo1,mo2,mo3,mo4), 'oh2.h5')

>>> view('oh2.h5')

dataset ['eri_mo'], shape (80, 24)

>>> ao2mo.outcore.general(mol, (mo1,mo2,mo3,mo3), 'oh2.h5')

>>> view('oh2.h5')

dataset ['eri_mo'], shape (80, 21)

>>> ao2mo.outcore.general(mol, (mo1,mo2,mo3,mo3), 'oh2.h5', compact=False)

>>> view('oh2.h5')

dataset ['eri_mo'], shape (80, 36)

>>> ao2mo.outcore.general(mol, (mo1,mo1,mo2,mo2), 'oh2.h5')

148 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

>>> view('oh2.h5')

dataset ['eri_mo'], shape (55, 36)

>>> ao2mo.outcore.general(mol, (mo1,mo1,mo1,mo1), 'oh2.h5', dataname='new')

>>> view('oh2.h5','new')

dataset ['eri_mo', 'new'], shape (55, 55)

>>> ao2mo.outcore.general(mol, (mo1,mo1,mo1,mo1), 'oh2.h5', intor='int2e_ip1_sph

˓→', aosym='s1', comp=3)

>>> view('oh2.h5')

dataset ['eri_mo', 'new'], shape (3, 100, 100)

>>> ao2mo.outcore.general(mol, (mo1,mo1,mo1,mo1), 'oh2.h5', intor='int2e_ip1_sph

˓→', aosym='s2kl', comp=3)

>>> view('oh2.h5')

dataset ['eri_mo', 'new'], shape (3, 100, 55)

pyscf.ao2mo.outcore.general_iofree(mol,mo_coeffs,intor=’int2e_sph’,aosym=’s4’,comp=1,

max_memory=2000,ioblk_size=256,verbose=2,com-

pact=True)

For the given four sets of orbitals, transfer arbitrary spherical AO integrals to MO integrals on the ﬂy. This

function is a wrap for ao2mo.outcore.general(). It’s not really IO free. The returned MO integrals are

held in memory. For backward compatibility, it is used to replace the non-existed function direct.general_iofree.

Args:

mol [Mole object] AO integrals will be generated in terms of mol._atm, mol._bas, mol._env

mo_coeffs [4-item list of ndarray] Four sets of orbital coefﬁcients, corresponding to the four indices of

(ij|kl)

Kwargs

intor [str] Name of the 2-electron integral. Ref to getints_by_shell() for the complete list of

available 2-electron integral names

aosym [int or str] Permutation symmetry for the AO integrals

4 or ‘4’ or ‘s4’: 4-fold symmetry (default)

‘2ij’ or ‘s2ij’ : symmetry between i, j in (ij|kl)

‘2kl’ or ‘s2kl’ : symmetry between k, l in (ij|kl)

1 or ‘1’ or ‘s1’: no symmetry

‘a4ij’ : 4-fold symmetry with anti-symmetry between i, j in (ij|kl) (TODO)

‘a4kl’ : 4-fold symmetry with anti-symmetry between k, l in (ij|kl) (TODO)

‘a2ij’ : anti-symmetry between i, j in (ij|kl) (TODO)

‘a2kl’ : anti-symmetry between k, l in (ij|kl) (TODO)

comp [int] Components of the integrals, e.g. int2e_ip_sph has 3 components.

verbose [int] Print level

compact [bool] When compact is True, depending on the four oribital sets, the returned MO integrals

has (up to 4-fold) permutation symmetry. If it’s False, the function will abandon any permutation

symmetry, and return the “plain” MO integrals

Returns: 2D/3D MO-integral array. They may or may not have the permutation symmetry, depending on the

given orbitals, and the kwargs compact. If the four sets of orbitals are identical, the MO integrals will at

most have 4-fold symmetry.

1.7. ao2mo — Integral transformations 149

PySCF Documentation, Release 1.4.0

Examples:

>>> from pyscf import gto

>>> from pyscf import ao2mo

>>> import h5py

>>> def view(h5file, dataname='eri_mo'):

... f5 =h5py.File(h5file)

... print('dataset %s, shape %s'%(str(f5.keys()), str(f5[dataname].shape)))

... f5.close()

>>> mol =gto.M(atom='O000;H010;H001', basis='sto3g')

>>> mo1 =numpy.random.random((mol.nao_nr(), 10))

>>> mo2 =numpy.random.random((mol.nao_nr(), 8))

>>> mo3 =numpy.random.random((mol.nao_nr(), 6))

>>> mo4 =numpy.random.random((mol.nao_nr(), 4))

>>> eri1 =ao2mo.outcore.general_iofree(mol, (mo1,mo2,mo3,mo4))

>>> print(eri1.shape)

(80, 24)

>>> eri1 =ao2mo.outcore.general_iofree(mol, (mo1,mo2,mo3,mo3))

>>> print(eri1.shape)

(80, 21)

>>> eri1 =ao2mo.outcore.general_iofree(mol, (mo1,mo2,mo3,mo3), compact=False)

>>> print(eri1.shape)

(80, 36)

>>> eri1 =ao2mo.outcore.general_iofree(mol, (mo1,mo1,mo1,mo1), intor='int2e_ip1_

˓→sph', aosym='s1', comp=3)

>>> print(eri1.shape)

(3, 100, 100)

>>> eri1 =ao2mo.outcore.general_iofree(mol, (mo1,mo1,mo1,mo1), intor='int2e_ip1_

˓→sph', aosym='s2kl', comp=3)

>>> print(eri1.shape)

(3, 100, 55)

pyscf.ao2mo.outcore.half_e1(mol,mo_coeffs,swapﬁle,intor=’int2e_sph’,aosym=’s4’,comp=1,

max_memory=2000,ioblk_size=256,verbose=2,compact=True,

ao2mopt=None)

Half transform arbitrary spherical AO integrals to MO integrals for the given two sets of orbitals

Args:

mol [Mole object] AO integrals will be generated in terms of mol._atm, mol._bas, mol._env

mo_coeff [ndarray] Transform (ij|kl) with the same set of orbitals.

swapﬁle [str or h5py File or h5py Group object] To store the transformed integrals, in HDF5 format. The

transformed integrals are saved in blocks.

Kwargs

intor [str] Name of the 2-electron integral. Ref to getints_by_shell() for the complete list of

available 2-electron integral names

aosym [int or str] Permutation symmetry for the AO integrals

4 or ‘4’ or ‘s4’: 4-fold symmetry (default)

‘2ij’ or ‘s2ij’ : symmetry between i, j in (ij|kl)

‘2kl’ or ‘s2kl’ : symmetry between k, l in (ij|kl)

1 or ‘1’ or ‘s1’: no symmetry

‘a4ij’ : 4-fold symmetry with anti-symmetry between i, j in (ij|kl) (TODO)

150 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

‘a4kl’ : 4-fold symmetry with anti-symmetry between k, l in (ij|kl) (TODO)

‘a2ij’ : anti-symmetry between i, j in (ij|kl) (TODO)

‘a2kl’ : anti-symmetry between k, l in (ij|kl) (TODO)

comp [int] Components of the integrals, e.g. int2e_ip_sph has 3 components.

verbose [int] Print level

max_memory [ﬂoat or int] The maximum size of cache to use (in MB), large cache may not improve

performance.

ioblk_size [ﬂoat or int] The block size for IO, large block size may not improve performance

verbose [int] Print level

compact [bool] When compact is True, depending on the four oribital sets, the returned MO integrals

has (up to 4-fold) permutation symmetry. If it’s False, the function will abandon any permutation

symmetry, and return the “plain” MO integrals

ao2mopt [AO2MOpt object] Precomputed data to improve perfomance

Returns: None

1.7.4 addons

class pyscf.ao2mo.addons.load(eri,dataname=’eri_mo’)

load 2e integrals from hdf5 ﬁle

Usage:

with load(eriﬁle) as eri: print eri.shape

pyscf.ao2mo.addons.restore(symmetry,eri,norb,tao=None)

Convert the 2e integrals between different level of permutation symmetry (8-fold, 4-fold, or no symmetry)

Args:

symmetry [int or str] code to present the target symmetry of 2e integrals

‘s8’ or ‘8’ or 8 : 8-fold symmetry

‘s4’ or ‘4’ or 4 : 4-fold symmetry

‘s1’ or ‘1’ or 1 : no symmetry

‘s2ij’ or ‘2ij’ : symmetric ij pair for (ij|kl) (TODO)

‘s2ij’ or ‘2kl’ : symmetric kl pair for (ij|kl) (TODO)

eri [ndarray] The symmetry of eri is determined by the size of eri and norb

norb [int] The symmetry of eri is determined by the size of eri and norb

Returns: ndarray. The shape depends on the target symmetry.

8 : (norb*(norb+1)/2)*(norb*(norb+1)/2+1)/2

4 : (norb*(norb+1)/2, norb*(norb+1)/2)

1 : (norb, norb, norb, norb)

Examples:

1.7. ao2mo — Integral transformations 151

PySCF Documentation, Release 1.4.0

>>> from pyscf import gto

>>> from pyscf.scf import _vhf

>>> from pyscf import ao2mo

>>> mol =gto.M(atom='O000;H010;H001', basis='sto3g')

>>> eri =mol.intor('int2e')

>>> eri1 =ao2mo.restore(1, eri, mol.nao_nr())

>>> eri4 =ao2mo.restore(4, eri, mol.nao_nr())

>>> eri8 =ao2mo.restore(8, eri, mol.nao_nr())

>>> print(eri1.shape)

(7, 7, 7, 7)

>>> print(eri1.shape)

(28, 28)

>>> print(eri1.shape)

(406,)

1.8 mcscf — Multi-conﬁgurational self-consistent ﬁeld

CASCI and CASSCF

Simple usage:

>>> from pyscf import gto, scf, mcscf

>>> mol =gto.M(atom='N000;N001', basis='ccpvdz', verbose=0)

>>> mf =scf.RHF(mol).run()

>>> mc =mcscf.CASCI(mf, 6,6)

>>> mc.kernel()[0]

-108.980200816243354

>>> mc =mcscf.CASSCF(mf, 6,6)

>>> mc.kernel()[0]

-109.044401882238134

>>> mc =mcscf.CASSCF(mf, 4,4)

>>> cas_list =[5,6,8,9]# pick orbitals for CAS space, 1-based indices

>>> mo =mcscf.sort_mo(mc, mf.mo_coeff, cas_list)

>>> mc.kernel(mo)[0]

-109.007378939813691

mcscf.CASSCF() or mcscf.CASCI() returns a proper instance of CASSCF/CASCI class. There are some pa-

rameters to control the CASSCF/CASCI method.

verbose [int] Print level. Default value equals to Mole.verbose.

max_memory [ﬂoat or int] Allowed memory in MB. Default value equals to Mole.max_memory.

ncas [int] Active space size.

nelecas [tuple of int] Active (nelec_alpha, nelec_beta)

ncore [int or tuple of int] Core electron number. In UHF-CASSCF, it’s a tuple to indicate the different

core eletron numbers.

natorb [bool] Whether to restore the natural orbital during CASSCF optimization. Default is not.

canonicalization [bool] Whether to canonicalize orbitals. Default is True.

fcisolver [an instance of FCISolver] The pyscf.fci module provides several FCISolver for different

scenario. Generally, fci.direct_spin1.FCISolver can be used for all RHF-CASSCF. However, a

proper FCISolver can provide better performance and better numerical stability. One can either use

152 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

fci.solver() function to pick the FCISolver by the program or manually assigen the FCISolver

to this attribute, e.g.

>>> from pyscf import fci

>>> mc =mcscf.CASSCF(mf, 4,4)

>>> mc.fcisolver =fci.solver(mol, singlet=True)

>>> mc.fcisolver =fci.direct_spin1.FCISolver(mol)

You can control FCISolver by setting e.g.:

>>> mc.fcisolver.max_cycle =30

>>> mc.fcisolver.conv_tol =1e-7

For more details of the parameter for FCISolver, See fci.

By replacing this fcisolver, you can easily use the CASCI/CASSCF solver with other FCI replace-

ments, such as DMRG, QMC. See dmrgscf and fciqmcscf.

The Following attributes are used for CASSCF

conv_tol [ﬂoat] Converge threshold. Default is 1e-7

conv_tol_grad [ﬂoat] Converge threshold for CI gradients and orbital rotation gradients. Default is 1e-4

max_stepsize [ﬂoat] The step size for orbital rotation. Small step size is prefered. Default is 0.03.

(NOTE although the default step size is small enough for many systems, it happens that the orbital

optimizor crosses the barriar of local minimum and converge to the neighbour solution, e.g. the

CAS(4,4) for C2H4 in the test ﬁles. In these cases, one need to ﬁne the optimization by reducing

max_stepsize, max_ci_stepsize and max_cycle_micro, max_cycle_micro_inner and ah_start_tol.)

>>> mc =mcscf.CASSCF(mf, 6,6)

>>> mc.max_stepsize = .01

>>> mc.max_cycle_micro =1

>>> mc.max_cycle_macro =100

>>> mc.max_cycle_micro_inner =1

>>> mc.ah_start_tol =1e-6

max_ci_stepsize [ﬂoat] The max size for approximate CI updates. The approximate updates are used in

1-step algorithm, to estimate the change of CI wavefunction wrt the orbital rotation. Small step size

is prefered. Default is 0.01.

max_cycle_macro [int] Max number of macro iterations. Default is 50.

max_cycle_micro [int] Max number of micro iterations in each macro iteration. Depending on systems,

increasing this value might reduce the total macro iterations. Generally, 2 - 3 steps should be

enough. Default is 2.

max_cycle_micro_inner [int] Max number of steps for the orbital rotations allowed for the augmented

hessian solver. It can affect the actual size of orbital rotation. Even with a small max_stepsize, a

few max_cycle_micro_inner can accumulate the rotation and leads to a signiﬁcant change of the

CAS space. Depending on systems, increasing this value migh reduce the total number of macro

iterations. The value between 2 - 8 is preferred. Default is 4.

frozen [int or list] If integer is given, the inner-most orbitals are excluded from optimization. Given the

orbital indices (0-based) in a list, any doubly occupied core orbitals, active orbitals and external

orbitals can be frozen.

ah_level_shift [ﬂoat, for AH solver.] Level shift for the Davidson diagonalization in AH solver. Default

is 0.

1.8. mcscf — Multi-conﬁgurational self-consistent ﬁeld 153

PySCF Documentation, Release 1.4.0

ah_conv_tol [ﬂoat, for AH solver.] converge threshold for Davidson diagonalization in AH solver. De-

fault is 1e-8.

ah_max_cycle [ﬂoat, for AH solver.] Max number of iterations allowd in AH solver. Default is 20.

ah_lindep [ﬂoat, for AH solver.] Linear dependence threshold for AH solver. Default is 1e-16.

ah_start_tol [ﬂat, for AH solver.] In AH solver, the orbital rotation is started without completely solving

the AH problem. This value is to control the start point. Default is 1e-4.

ah_start_cycle [int, for AH solver.] In AH solver, the orbital rotation is started without completely

solving the AH problem. This value is to control the start point. Default is 3.

ah_conv_tol,ah_max_cycle,ah_lindep,ah_start_tol and ah_start_cycle

can affect the accuracy and performance of CASSCF solver. Lower ah_conv_tol and

ah_lindep can improve the accuracy of CASSCF optimization, but slow down the performance.

>>> from pyscf import gto, scf, mcscf

>>> mol =gto.M(atom='N000;N001', basis='ccpvdz', verbose=0)

>>> mf =scf.UHF(mol)

>>> mf.scf()

>>> mc =mcscf.CASSCF(mf, 6,6)

>>> mc.conv_tol =1e-10

>>> mc.ah_conv_tol =1e-5

>>> mc.kernel()

-109.044401898486001

>>> mc.ah_conv_tol =1e-10

>>> mc.kernel()

-109.044401887945668

chkﬁle [str] Checkpoint ﬁle to save the intermediate orbitals during the CASSCF optimization. Default

is the checkpoint ﬁle of mean ﬁeld object.

Saved results

e_tot [ﬂoat] Total MCSCF energy (electronic energy plus nuclear repulsion)

ci [ndarray] CAS space FCI coefﬁcients

converged [bool, for CASSCF only] It indicates CASSCF optimization converged or not.

mo_energy: ndarray, Diagonal elements of general Fock matrix

mo_coeff [ndarray, for CASSCF only] Optimized CASSCF orbitals coefﬁcients Note the orbitals are

NOT natural orbitals by default. There are two inbuilt methods to convert the mo_coeff to natural

orbitals. 1. Set .natorb attribute. It can be used before calculation. 2. call .cas_natorb_ method after

the calculation to in-place convert the orbitals

154 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

1.8.1 CASSCF active space solver

DMRG solver

FCIQMC solver

State-average FCI solver

State-average with mixed solver

1.8.2 Symmetry broken

1.8.3 Initial guess

1.8.4 Program reference

CASCI

class pyscf.mcscf.casci.CASCI(mf,ncas,nelecas,ncore=None)

Attributes:

verbose [int] Print level. Default value equals to Mole.verbose.

max_memory [ﬂoat or int] Allowed memory in MB. Default value equals to Mole.max_memory.

ncas [int] Active space size.

nelecas [tuple of int] Active (nelec_alpha, nelec_beta)

ncore [int or tuple of int] Core electron number. In UHF-CASSCF, it’s a tuple to indicate the different

core eletron numbers.

natorb [bool] Whether to restore the natural orbital in CAS space. Default is not. Be very careful to

set this parameter when CASCI/CASSCF are combined with DMRG solver because this parameter

changes the orbital ordering which DMRG relies on.

canonicalization [bool] Whether to canonicalize orbitals. Default is True.

fcisolver [an instance of FCISolver] The pyscf.fci module provides several FCISolver for different

scenario. Generally, fci.direct_spin1.FCISolver can be used for all RHF-CASSCF. However, a

proper FCISolver can provide better performance and better numerical stability. One can either use

fci.solver() function to pick the FCISolver by the program or manually assigen the FCISolver

to this attribute, e.g.

>>> from pyscf import fci

>>> mc =mcscf.CASSCF(mf, 4,4)

>>> mc.fcisolver =fci.solver(mol, singlet=True)

>>> mc.fcisolver =fci.direct_spin1.FCISolver(mol)

You can control FCISolver by setting e.g.:

>>> mc.fcisolver.max_cycle =30

>>> mc.fcisolver.conv_tol =1e-7

For more details of the parameter for FCISolver, See fci.

Saved results

1.8. mcscf — Multi-conﬁgurational self-consistent ﬁeld 155

PySCF Documentation, Release 1.4.0

e_tot [ﬂoat] Total MCSCF energy (electronic energy plus nuclear repulsion)

ci [ndarray] CAS space FCI coefﬁcients

Examples:

>>> from pyscf import gto, scf, mcscf

>>> mol =gto.M(atom='N000;N001', basis='ccpvdz', verbose=0)

>>> mf =scf.RHF(mol)

>>> mf.scf()

>>> mc =mcscf.CASCI(mf, 6,6)

>>> mc.kernel()[0]

-108.980200816243354

canonicalize(mc,mo_coeff=None,ci=None,eris=None,sort=False,cas_natorb=False,

casdm1=None,verbose=3)

Canonicalize CASCI/CASSCF orbitals

Args: mc : a CASSCF/CASCI object or RHF object

Returns: A tuple, (natural orbitals, CI coefﬁcients, orbital energies) The orbital energies are the diagonal

terms of general Fock matrix.

canonicalize_(mo_coeff=None,ci=None,eris=None,sort=False,cas_natorb=False,

casdm1=None,verbose=None)

Canonicalize CASCI/CASSCF orbitals

Args: mc : a CASSCF/CASCI object or RHF object

Returns: A tuple, (natural orbitals, CI coefﬁcients, orbital energies) The orbital energies are the diagonal

terms of general Fock matrix.

cas_natorb(mo_coeff=None,ci=None,eris=None,sort=False,casdm1=None,verbose=None)

Transform active orbitals to natrual orbitals, and update the CI wfn

Args: mc : a CASSCF/CASCI object or RHF object

Kwargs:

sort [bool] Sort natural orbitals wrt the occupancy. Be careful with this option since the resultant

natural orbitals might have the different symmetry to the irreps indicated by CASSCF.orbsym

Returns: A tuple, the ﬁrst item is natural orbitals, the second is updated CI coefﬁcients, the third is the

natural occupancy associated to the natural orbitals.

cas_natorb_(mo_coeff=None,ci=None,eris=None,sort=False,casdm1=None,verbose=None)

Transform active orbitals to natrual orbitals, and update the CI wfn

Args: mc : a CASSCF/CASCI object or RHF object

Kwargs:

sort [bool] Sort natural orbitals wrt the occupancy. Be careful with this option since the resultant

natural orbitals might have the different symmetry to the irreps indicated by CASSCF.orbsym

Returns: A tuple, the ﬁrst item is natural orbitals, the second is updated CI coefﬁcients, the third is the

natural occupancy associated to the natural orbitals.

fix_spin_(shift=0.2,ss=None)

Use level shift to control FCI solver spin.

(𝐻+𝑠ℎ𝑖𝑓𝑡 *𝑆2)|Ψ⟩=𝐸|Ψ⟩

Kwargs:

156 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

shift [ﬂoat] Level shift for states which have different spin

ss [number] S^2 expection value == s*(s+1)

get_h1cas(mo_coeff=None,ncas=None,ncore=None)

CAS sapce one-electron hamiltonian

Args: casci : a CASSCF/CASCI object or RHF object

Returns: A tuple, the ﬁrst is the effective one-electron hamiltonian deﬁned in CAS space, the second is

the electronic energy from core.

get_h1eff(mo_coeff=None,ncas=None,ncore=None)

CAS sapce one-electron hamiltonian

Args: casci : a CASSCF/CASCI object or RHF object

Returns: A tuple, the ﬁrst is the effective one-electron hamiltonian deﬁned in CAS space, the second is

the electronic energy from core.

h1e_for_cas(mo_coeff=None,ncas=None,ncore=None)

CAS sapce one-electron hamiltonian

Args: casci : a CASSCF/CASCI object or RHF object

Returns: A tuple, the ﬁrst is the effective one-electron hamiltonian deﬁned in CAS space, the second is

the electronic energy from core.

make_rdm1(mo_coeff=None,ci=None,ncas=None,nelecas=None,ncore=None)

One-particle density matrix in AO representation

make_rdm1s(mo_coeff=None,ci=None,ncas=None,nelecas=None,ncore=None)

One-particle density matrices for alpha and beta spin

sort_mo(caslst,mo_coeff=None,base=1)

Select active space. See also pyscf.mcscf.addons.sort_mo()

state_average_(weights=(0.5,0.5))

State average over the energy. The energy funcitonal is E = w1<psi1|H|psi1> + w2<psi2|H|psi2> + ...

Note we may need change the FCI solver to

mc.fcisolver = fci.solver(mol, False)

before calling state_average_(mc), to mix the singlet and triplet states

state_specific_(state=1)

For excited state

Kwargs: state : int 0 for ground state; 1 for ﬁrst excited state.

pyscf.mcscf.casci.canonicalize(mc,mo_coeff=None,ci=None,eris=None,sort=False,

cas_natorb=False,casdm1=None,verbose=3)

Canonicalize CASCI/CASSCF orbitals

Args: mc : a CASSCF/CASCI object or RHF object

Returns: A tuple, (natural orbitals, CI coefﬁcients, orbital energies) The orbital energies are the diagonal terms

of general Fock matrix.

pyscf.mcscf.casci.cas_natorb(mc,mo_coeff=None,ci=None,eris=None,sort=False,

casdm1=None,verbose=None)

Transform active orbitals to natrual orbitals, and update the CI wfn

Args: mc : a CASSCF/CASCI object or RHF object

Kwargs:

1.8. mcscf — Multi-conﬁgurational self-consistent ﬁeld 157

PySCF Documentation, Release 1.4.0

sort [bool] Sort natural orbitals wrt the occupancy. Be careful with this option since the resultant natural

orbitals might have the different symmetry to the irreps indicated by CASSCF.orbsym

Returns: A tuple, the ﬁrst item is natural orbitals, the second is updated CI coefﬁcients, the third is the natural

occupancy associated to the natural orbitals.

pyscf.mcscf.casci.get_fock(mc,mo_coeff=None,ci=None,eris=None,casdm1=None,ver-

bose=None)

Generalized Fock matrix in AO representation

pyscf.mcscf.casci.h1e_for_cas(casci,mo_coeff=None,ncas=None,ncore=None)

CAS sapce one-electron hamiltonian

Args: casci : a CASSCF/CASCI object or RHF object

Returns: A tuple, the ﬁrst is the effective one-electron hamiltonian deﬁned in CAS space, the second is the

electronic energy from core.

pyscf.mcscf.casci.kernel(casci,mo_coeff=None,ci0=None,verbose=3)

CASCI solver

pyscf.mcscf.casci_uhf.h1e_for_cas(casci,mo_coeff=None,ncas=None,ncore=None)

CAS sapce one-electron hamiltonian for UHF-CASCI or UHF-CASSCF

Args: casci : a U-CASSCF/U-CASCI object or UHF object

pyscf.mcscf.casci_uhf.kernel(casci,mo_coeff=None,ci0=None,verbose=3)

UHF-CASCI solver

CASSCF

class pyscf.mcscf.mc1step.CASSCF(mf,ncas,nelecas,ncore=None,frozen=None)

Attributes:

verbose [int] Print level. Default value equals to Mole.verbose.

max_memory [ﬂoat or int] Allowed memory in MB. Default value equals to Mole.max_memory.

ncas [int] Active space size.

nelecas [tuple of int] Active (nelec_alpha, nelec_beta)

ncore [int or tuple of int] Core electron number. In UHF-CASSCF, it’s a tuple to indicate the different

core eletron numbers.

natorb [bool] Whether to restore the natural orbital in CAS space. Default is not. Be very careful to

set this parameter when CASCI/CASSCF are combined with DMRG solver because this parameter

changes the orbital ordering which DMRG relies on.

canonicalization [bool] Whether to canonicalize orbitals. Default is True.

fcisolver [an instance of FCISolver] The pyscf.fci module provides several FCISolver for different

scenario. Generally, fci.direct_spin1.FCISolver can be used for all RHF-CASSCF. However, a

proper FCISolver can provide better performance and better numerical stability. One can either use

fci.solver() function to pick the FCISolver by the program or manually assigen the FCISolver

to this attribute, e.g.

>>> from pyscf import fci

>>> mc =mcscf.CASSCF(mf, 4,4)

>>> mc.fcisolver =fci.solver(mol, singlet=True)

>>> mc.fcisolver =fci.direct_spin1.FCISolver(mol)

158 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

You can control FCISolver by setting e.g.:

>>> mc.fcisolver.max_cycle =30

>>> mc.fcisolver.conv_tol =1e-7

For more details of the parameter for FCISolver, See fci.

Saved results

e_tot [ﬂoat] Total MCSCF energy (electronic energy plus nuclear repulsion)

ci [ndarray] CAS space FCI coefﬁcients

Examples:

>>> from pyscf import gto, scf, mcscf

>>> mol =gto.M(atom='N000;N001', basis='ccpvdz', verbose=0)

>>> mf =scf.RHF(mol)

>>> mf.scf()

>>> mc =mcscf.CASCI(mf, 6,6)

>>> mc.kernel()[0]

-108.980200816243354

CASSCF

Extra attributes for CASSCF:

conv_tol [ﬂoat] Converge threshold. Default is 1e-7

conv_tol_grad [ﬂoat] Converge threshold for CI gradients and orbital rotation gradients. Default

is 1e-4

max_stepsize [ﬂoat] The step size for orbital rotation. Small step (0.005 - 0.05) is prefered. (see

notes in max_cycle_micro_inner attribute) Default is 0.03.

max_cycle_macro [int] Max number of macro iterations. Default is 50.

max_cycle_micro [int] Max number of micro iterations in each macro iteration. Depending on

systems, increasing this value might reduce the total macro iterations. Generally, 2 - 5 steps

should be enough. Default is 3.

ah_level_shift [ﬂoat, for AH solver.] Level shift for the Davidson diagonalization in AH solver.

Default is 1e-8.

ah_conv_tol [ﬂoat, for AH solver.] converge threshold for AH solver. Default is 1e-12.

ah_max_cycle [ﬂoat, for AH solver.] Max number of iterations allowd in AH solver. Default is

30.

ah_lindep [ﬂoat, for AH solver.] Linear dependence threshold for AH solver. Default is 1e-14.

ah_start_tol [ﬂat, for AH solver.] In AH solver, the orbital rotation is started without completely

solving the AH problem. This value is to control the start point. Default is 0.2.

ah_start_cycle [int, for AH solver.] In AH solver, the orbital rotation is started without completely

solving the AH problem. This value is to control the start point. Default is 2.

ah_conv_tol,ah_max_cycle,ah_lindep,ah_start_tol and

ah_start_cycle can affect the accuracy and performance of CASSCF solver. Lower

ah_conv_tol and ah_lindep might improve the accuracy of CASSCF optimization, but

decrease the performance.

>>> from pyscf import gto, scf, mcscf

>>> mol =gto.M(atom='N000;N001', basis='ccpvdz', verbose=0)

1.8. mcscf — Multi-conﬁgurational self-consistent ﬁeld 159

PySCF Documentation, Release 1.4.0

>>> mf =scf.UHF(mol)

>>> mf.scf()

>>> mc =mcscf.CASSCF(mf, 6,6)

>>> mc.conv_tol =1e-10

>>> mc.ah_conv_tol =1e-5

>>> mc.kernel()

-109.044401898486001

>>> mc.ah_conv_tol =1e-10

>>> mc.kernel()

-109.044401887945668

chkﬁle [str] Checkpoint ﬁle to save the intermediate orbitals during the CASSCF optimization.

Default is the checkpoint ﬁle of mean ﬁeld object.

ci_response_space [int] subspace size to solve the CI vector response. Default is 3.

callback [function(envs_dict) => None] callback function takes one dict as the argument which is

generated by the builtin function locals(), so that the callback function can access all local

variables in the current envrionment.

Saved results

e_tot [ﬂoat] Total MCSCF energy (electronic energy plus nuclear repulsion)

ci [ndarray] CAS space FCI coefﬁcients

converged [bool] It indicates CASSCF optimization converged or not.

mo_coeff [ndarray] Optimized CASSCF orbitals coefﬁcients

Examples:

>>> from pyscf import gto, scf, mcscf

>>> mol =gto.M(atom='N000;N001', basis='ccpvdz', verbose=0)

>>> mf =scf.RHF(mol)

>>> mf.scf()

>>> mc =mcscf.CASSCF(mf, 6,6)

>>> mc.kernel()[0]

-109.044401882238134

rotate_mo(mo,u,log=None)

Rotate orbitals with the given unitary matrix

solve_approx_ci(h1,h2,ci0,ecore,e_ci,envs)

Solve CI eigenvalue/response problem approximately

pyscf.mcscf.mc1step.kernel(casscf,mo_coeff,tol=1e-07,conv_tol_grad=None,ci0=None,call-

back=None,verbose=3,dump_chk=True)

CASSCF solver

class pyscf.mcscf.mc1step_symm.CASSCF(mf,ncas,nelecas,ncore=None,frozen=None)

Attributes:

verbose [int] Print level. Default value equals to Mole.verbose.

max_memory [ﬂoat or int] Allowed memory in MB. Default value equals to Mole.max_memory.

ncas [int] Active space size.

nelecas [tuple of int] Active (nelec_alpha, nelec_beta)

ncore [int or tuple of int] Core electron number. In UHF-CASSCF, it’s a tuple to indicate the different

core eletron numbers.

160 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

natorb [bool] Whether to restore the natural orbital in CAS space. Default is not. Be very careful to

set this parameter when CASCI/CASSCF are combined with DMRG solver because this parameter

changes the orbital ordering which DMRG relies on.

canonicalization [bool] Whether to canonicalize orbitals. Default is True.

fcisolver [an instance of FCISolver] The pyscf.fci module provides several FCISolver for different

scenario. Generally, fci.direct_spin1.FCISolver can be used for all RHF-CASSCF. However, a

proper FCISolver can provide better performance and better numerical stability. One can either use

fci.solver() function to pick the FCISolver by the program or manually assigen the FCISolver

to this attribute, e.g.

>>> from pyscf import fci

>>> mc =mcscf.CASSCF(mf, 4,4)

>>> mc.fcisolver =fci.solver(mol, singlet=True)

>>> mc.fcisolver =fci.direct_spin1.FCISolver(mol)

You can control FCISolver by setting e.g.:

>>> mc.fcisolver.max_cycle =30

>>> mc.fcisolver.conv_tol =1e-7

For more details of the parameter for FCISolver, See fci.

Saved results

e_tot [ﬂoat] Total MCSCF energy (electronic energy plus nuclear repulsion)

ci [ndarray] CAS space FCI coefﬁcients

Examples:

>>> from pyscf import gto, scf, mcscf

>>> mol =gto.M(atom='N000;N001', basis='ccpvdz', verbose=0)

>>> mf =scf.RHF(mol)

>>> mf.scf()

>>> mc =mcscf.CASCI(mf, 6,6)

>>> mc.kernel()[0]

-108.980200816243354

CASSCF

Extra attributes for CASSCF:

conv_tol [ﬂoat] Converge threshold. Default is 1e-7

conv_tol_grad [ﬂoat] Converge threshold for CI gradients and orbital rotation gradients. Default

is 1e-4

max_stepsize [ﬂoat] The step size for orbital rotation. Small step (0.005 - 0.05) is prefered. (see

notes in max_cycle_micro_inner attribute) Default is 0.03.

max_cycle_macro [int] Max number of macro iterations. Default is 50.

max_cycle_micro [int] Max number of micro iterations in each macro iteration. Depending on

systems, increasing this value might reduce the total macro iterations. Generally, 2 - 5 steps

should be enough. Default is 3.

ah_level_shift [ﬂoat, for AH solver.] Level shift for the Davidson diagonalization in AH solver.

Default is 1e-8.

ah_conv_tol [ﬂoat, for AH solver.] converge threshold for AH solver. Default is 1e-12.

1.8. mcscf — Multi-conﬁgurational self-consistent ﬁeld 161

PySCF Documentation, Release 1.4.0

ah_max_cycle [ﬂoat, for AH solver.] Max number of iterations allowd in AH solver. Default is

30.

ah_lindep [ﬂoat, for AH solver.] Linear dependence threshold for AH solver. Default is 1e-14.

ah_start_tol [ﬂat, for AH solver.] In AH solver, the orbital rotation is started without completely

solving the AH problem. This value is to control the start point. Default is 0.2.

ah_start_cycle [int, for AH solver.] In AH solver, the orbital rotation is started without completely

solving the AH problem. This value is to control the start point. Default is 2.

ah_conv_tol,ah_max_cycle,ah_lindep,ah_start_tol and

ah_start_cycle can affect the accuracy and performance of CASSCF solver. Lower

ah_conv_tol and ah_lindep might improve the accuracy of CASSCF optimization, but

decrease the performance.

>>> from pyscf import gto, scf, mcscf

>>> mol =gto.M(atom='N000;N001', basis='ccpvdz', verbose=0)

>>> mf =scf.UHF(mol)

>>> mf.scf()

>>> mc =mcscf.CASSCF(mf, 6,6)

>>> mc.conv_tol =1e-10

>>> mc.ah_conv_tol =1e-5

>>> mc.kernel()

-109.044401898486001

>>> mc.ah_conv_tol =1e-10

>>> mc.kernel()

-109.044401887945668

chkﬁle [str] Checkpoint ﬁle to save the intermediate orbitals during the CASSCF optimization.

Default is the checkpoint ﬁle of mean ﬁeld object.

ci_response_space [int] subspace size to solve the CI vector response. Default is 3.

callback [function(envs_dict) => None] callback function takes one dict as the argument which is

generated by the builtin function locals(), so that the callback function can access all local

variables in the current envrionment.

Saved results

e_tot [ﬂoat] Total MCSCF energy (electronic energy plus nuclear repulsion)

ci [ndarray] CAS space FCI coefﬁcients

converged [bool] It indicates CASSCF optimization converged or not.

mo_coeff [ndarray] Optimized CASSCF orbitals coefﬁcients

Examples:

>>> from pyscf import gto, scf, mcscf

>>> mol =gto.M(atom='N000;N001', basis='ccpvdz', verbose=0)

>>> mf =scf.RHF(mol)

>>> mf.scf()

>>> mc =mcscf.CASSCF(mf, 6,6)

>>> mc.kernel()[0]

-109.044401882238134

162 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

addons

pyscf.mcscf.addons.cas_natorb(casscf,mo_coeff=None,ci=None,sort=False)

Natrual orbitals in CAS space

pyscf.mcscf.addons.caslst_by_irrep(casscf,mo_coeff,cas_irrep_nocc,cas_irrep_ncore=None,

s=None,base=1)

Given number of active orbitals for each irrep, return the orbital indices of active space

Args: casscf : an CASSCF or CASCI object

cas_irrep_nocc [list or dict] Number of active orbitals for each irrep. It can be a dict, eg {‘A1’: 2, ‘B2’:

4} to indicate the active space size based on irrep names, or {0: 2, 3: 4} for irrep Id, or a list [2, 0,

0, 4] (identical to {0: 2, 3: 4}) in which the list index is served as the irrep Id.

Kwargs:

cas_irrep_ncore [list or dict] Number of closed shells for each irrep. It can be a dict, eg {‘A1’: 6, ‘B2’:

4} to indicate the closed shells based on irrep names, or {0: 6, 3: 4} for irrep Id, or a list [6, 0, 0, 4]

(identical to {0: 6, 3: 4}) in which the list index is served as the irrep Id. If cas_irrep_ncore is not

given, the program will generate a guess based on the lowest CASCI.ncore orbitals.

s[ndarray] overlap matrix

base [int] 0-based (C-like) or 1-based (Fortran-like) caslst

Returns: A list of orbital indices

Examples:

>>> from pyscf import gto, scf, mcscf

>>> mol =gto.M(atom='N000;N001', basis='ccpvtz', symmetry=True, verbose=0)

>>> mf =scf.RHF(mol)

>>> mf.kernel()

>>> mc =mcscf.CASSCF(mf, 12,4)

>>> mcscf.caslst_by_irrep(mc, mf.mo_coeff, {'E1gx':4,'E1gy':4,'E1ux':2,'E1uy':

˓→2})

[5, 7, 8, 10, 11, 14, 15, 20, 25, 26, 31, 32]

pyscf.mcscf.addons.get_fock(casscf,mo_coeff=None,ci=None)

Generalized Fock matrix in AO representation

pyscf.mcscf.addons.hot_tuning_(casscf,conﬁgﬁle=None)

Allow you to tune CASSCF parameters on the runtime

pyscf.mcscf.addons.make_rdm1(casscf,mo_coeff=None,ci=None)

One-particle densit matrix in AO representation

Args: casscf : an CASSCF or CASCI object

Kwargs:

ci [ndarray] CAS space FCI coefﬁcients. If not given, take casscf.ci.

mo_coeff [ndarray] Orbital coefﬁcients. If not given, take casscf.mo_coeff.

Examples:

>>> import scipy.linalg

>>> from pyscf import gto, scf, mcscf

>>> mol =gto.M(atom='N000;N001', basis='sto-3g', verbose=0)

>>> mf =scf.RHF(mol)

>>> res =mf.scf()

1.8. mcscf — Multi-conﬁgurational self-consistent ﬁeld 163

PySCF Documentation, Release 1.4.0

>>> mc =mcscf.CASSCF(mf, 6,6)

>>> res =mc.kernel()

>>> natocc =numpy.linalg.eigh(mcscf.make_rdm1(mc), mf.get_ovlp(), type=2)[0]

>>> print(natocc)

[ 0.0121563 0.0494735 0.0494735 1.95040395 1.95040395 1.98808879

2. 2. 2. 2. ]

pyscf.mcscf.addons.make_rdm1s(casscf,mo_coeff=None,ci=None)

Alpha and beta one-particle densit matrices in AO representation

pyscf.mcscf.addons.map2hf(casscf,mf_mo=None,base=1,tol=0.5)

The overlap between the CASSCF optimized orbitals and the canonical HF orbitals.

pyscf.mcscf.addons.project_init_guess(casscf,init_mo,prev_mol=None)

Project the given initial guess to the current CASSCF problem. The projected initial guess has two parts. The

core orbitals are directly taken from the Hartree-Fock orbitals, and the active orbitals are projected from the

given initial guess.

Args: casscf : an CASSCF or CASCI object

init_mo [ndarray or list of ndarray] Initial guess orbitals which are not orth-normal for the current

molecule. When the casscf is UHF-CASSCF, the init_mo needs to be a list of two ndarrays, for

alpha and beta orbitals

Kwargs:

prev_mol [an instance of Mole] If given, the inital guess orbitals are associated to the geometry and

basis of prev_mol. Otherwise, the orbitals are based of the geometry and basis of casscf.mol

Returns: New orthogonal initial guess orbitals with the core taken from Hartree-Fock orbitals and projected

active space from original initial guess orbitals

Examples:

import numpy

from pyscf import gto, scf, mcscf

mol =gto.Mole()

mol.build(atom='H000;F000.8', basis='ccpvdz', verbose=0)

mf =scf.RHF(mol)

mf.scf()

mc =mcscf.CASSCF(mf, 6,6)

mo =mcscf.sort_mo(mc, mf.mo_coeff, [3,4,5,6,8,9])

print('E(0.8) = %.12f'%mc.kernel(mo)[0])

init_mo =mc.mo_coeff

for bin numpy.arange(1.0,3.,.2):

mol.atom =[['H', (0,0,0)], ['F', (0,0, b)]]

mol.build(0,0)

mf =scf.RHF(mol)

mf.scf()

mc =mcscf.CASSCF(mf, 6,6)

mo =mcscf.project_init_guess(mc, init_mo)

print('E(%2.1f) = %.12f'%(b, mc.kernel(mo)[0]))

init_mo =mc.mo_coeff

pyscf.mcscf.addons.sort_mo(casscf,mo_coeff,caslst,base=1)

Pick orbitals for CAS space

Args: casscf : an CASSCF or CASCI object

mo_coeff [ndarray or a list of ndarray] Orbitals for CASSCF initial guess. In the UHF-CASSCF, it’s a

list of two orbitals, for alpha and beta spin.

164 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

caslst [list of int or nested list of int] A list of orbital indices to represent the CAS space. In the UHF-

CASSCF, it’s consist of two lists, for alpha and beta spin.

Kwargs:

base [int] 0-based (C-style) or 1-based (Fortran-style) caslst

Returns: An reoreded mo_coeff, which put the orbitals given by caslst in the CAS space

Examples:

>>> from pyscf import gto, scf, mcscf

>>> mol =gto.M(atom='N000;N001', basis='ccpvdz', verbose=0)

>>> mf =scf.RHF(mol)

>>> mf.scf()

>>> mc =mcscf.CASSCF(mf, 4,4)

>>> cas_list =[5,6,8,9]# pi orbitals

>>> mo =mc.sort_mo(cas_list)

>>> mc.kernel(mo)[0]

-109.007378939813691

pyscf.mcscf.addons.sort_mo_by_irrep(casscf,mo_coeff,cas_irrep_nocc,

cas_irrep_ncore=None,s=None)

Given number of active orbitals for each irrep, construct the mo initial guess for CASSCF

Args: casscf : an CASSCF or CASCI object

cas_irrep_nocc [list or dict] Number of active orbitals for each irrep. It can be a dict, eg {‘A1’: 2, ‘B2’:

4} to indicate the active space size based on irrep names, or {0: 2, 3: 4} for irrep Id, or a list [2, 0,

0, 4] (identical to {0: 2, 3: 4}) in which the list index is served as the irrep Id.

Kwargs:

cas_irrep_ncore [list or dict] Number of closed shells for each irrep. It can be a dict, eg {‘A1’: 6, ‘B2’:

4} to indicate the closed shells based on irrep names, or {0: 6, 3: 4} for irrep Id, or a list [6, 0, 0, 4]

(identical to {0: 6, 3: 4}) in which the list index is served as the irrep Id. If cas_irrep_ncore is not

given, the program will generate a guess based on the lowest CASCI.ncore orbitals.

s[ndarray] overlap matrix

Returns: sorted orbitals, ordered as [c,..,c,a,..,a,v,..,v]

Examples:

>>> from pyscf import gto, scf, mcscf

>>> mol =gto.M(atom='N000;N001', basis='ccpvtz', symmetry=True, verbose=0)

>>> mf =scf.RHF(mol)

>>> mf.kernel()

>>> mc =mcscf.CASSCF(mf, 12,4)

>>> mo =mc.sort_mo_by_irrep({'E1gx':4,'E1gy':4,'E1ux':2,'E1uy':2})

>>> # Same to mo = sort_mo_by_irrep(mc, mf.mo_coeff, {2: 4, 3: 4, 6: 2, 7: 2})

>>> # Same to mo = sort_mo_by_irrep(mc, mf.mo_coeff, [0, 0, 4, 4, 0, 0, 2, 2])

>>> mc.kernel(mo)[0]

-108.162863845084

pyscf.mcscf.addons.spin_square(casscf,mo_coeff=None,ci=None,ovlp=None)

Spin square of the UHF-CASSCF wavefunction

Returns: A list of two ﬂoats. The ﬁrst is the expectation value of S^2. The second is the corresponding 2S+1

Examples:

1.8. mcscf — Multi-conﬁgurational self-consistent ﬁeld 165

PySCF Documentation, Release 1.4.0

>>> from pyscf import gto, scf, mcscf

>>> mol =gto.M(atom='O000;O001', basis='sto-3g', spin=2, verbose=0)

>>> mf =scf.UHF(mol)

>>> res =mf.scf()

>>> mc =mcscf.CASSCF(mf, 4,6)

>>> res =mc.kernel()

>>> print('S^2 = %.7f, 2S+1 = %.7f'%mcscf.spin_square(mc))

S^2 = 3.9831589, 2S+1 = 4.1149284

pyscf.mcscf.addons.state_average(casscf,weights=(0.5,0.5))

State average over the energy. The energy funcitonal is E = w1<psi1|H|psi1> + w2<psi2|H|psi2> + ...

Note we may need change the FCI solver to

mc.fcisolver = fci.solver(mol, False)

before calling state_average_(mc), to mix the singlet and triplet states

pyscf.mcscf.addons.state_average_(casscf,weights=(0.5,0.5))

State average over the energy. The energy funcitonal is E = w1<psi1|H|psi1> + w2<psi2|H|psi2> + ...

Note we may need change the FCI solver to

mc.fcisolver = fci.solver(mol, False)

before calling state_average_(mc), to mix the singlet and triplet states

pyscf.mcscf.addons.state_average_mix(casscf,fcisolvers,weights=(0.5,0.5))

State-average CASSCF over multiple FCI solvers.

pyscf.mcscf.addons.state_average_mix_(casscf,fcisolvers,weights=(0.5,0.5))

State-average CASSCF over multiple FCI solvers.

pyscf.mcscf.addons.state_specific(casscf,state=1)

For excited state

Kwargs: state : int 0 for ground state; 1 for ﬁrst excited state.

pyscf.mcscf.addons.state_specific_(casscf,state=1)

For excited state

Kwargs: state : int 0 for ground state; 1 for ﬁrst excited state.

1.9 fci — Full conﬁguration interaction

Different FCI solvers are implemented to support different type of symmetry. Symmetry

File Point group Spin singlet Real hermitian* Alpha/beta degeneracy direct_spin0_symm Yes Yes Yes Yes di-

rect_spin1_symm Yes No Yes Yes direct_spin0 No Yes Yes Yes direct_spin1 No No Yes Yes direct_uhf No No Yes

No direct_nosym No No No** Yes

• Real hermitian Hamiltonian implies (ij|kl) = (ji|kl) = (ij|lk) = (ji|lk)

** Hamiltonian is real but not hermitian, (ij|kl) != (ji|kl) ...

1.9.1 direct CI

Full CI solver for spin-free Hamiltonian. This solver can be used to compute doublet, triplet,...

166 Chapter 1. Contents

PySCF Documentation, Release 1.4.0

The CI wfn are stored as a 2D array [alpha,beta], where each row corresponds to an alpha string. For each row (alpha

string), there are total-num-beta-strings of columns. Each column corresponds to a beta string.

Different FCI solvers are implemented to support different type of symmetry. Symmetry

File Point group Spin singlet Real hermitian* Alpha/beta degeneracy direct_spin0_symm Yes Yes Yes Yes di-

rect_spin1_symm Yes No Yes Yes direct_spin0 No Yes Yes Yes direct_spin1 No No Yes Yes direct_uhf No No Yes

No direct_nosym No No No** Yes

• Real hermitian Hamiltonian implies (ij|kl) = (ji|kl) = (ij|lk) = (ji|lk)

** Hamiltonian is real but not hermitian, (ij|kl) != (ji|kl) ...

pyscf.fci.direct_spin1.FCI

alias of FCISolver

class pyscf.fci.direct_spin1.FCISolver(mol=None)

Full CI solver

Attributes:

verbose [int] Print level. Default value equals to Mole.verbose.

max_cycle [int] Total number of iterations. Default is 100

max_space [tuple of int] Davidson iteration space size. Default is 14.

conv_tol [ﬂoat] Energy convergence tolerance. Default is 1e-10.

level_shift [ﬂoat] Level shift applied in the preconditioner to avoid singularity. Default is 1e-3

davidson_only [bool] By default, the entire Hamiltonian matrix will be constructed and diagonalized

if the system is small (see attribute pspace_size). Setting this parameter to True will enforce the

eigenvalue problems being solved by Davidson subspace algorithm. This ﬂag should be enabled

when initial guess is given or particular spin symmetry or point-group symmetry is required because

the initial guess or symmetry are completely ignored in the direct diagonlization.

pspace_size [int] The dimension of Hamiltonian matrix over which Davidson iteration algorithm will be

used for the eigenvalue problem. Default is 400. This is roughly corresponding to a (6e,6o) system.

nroots [int] Number of states to be solved. Default is 1, the ground state.

spin [int or None] Spin (2S = nalpha-nbeta) of the system. If this attribute is None, spin will be deter-

mined by the argument nelec (number of electrons) of the kernel function.

wfnsym [str or int] Symmetry of wavefunction. It is used only in direct_spin1_symm and di-

rect_spin0_symm solver.

Saved results

converged [bool] Whether davidson iteration is converged

Examples:

>>> from pyscf import gto, scf, ao2mo, fci

>>> mol =gto.M(atom='Li000;Li001', basis='sto-3g')

>>> mf =scf.RHF(mol).run()

>>> h1 =mf.mo_coeff.T.dot(mf.get_hcore()).dot(mf.mo_coeff)

>>> eri =ao2mo.kernel(mol, mf.mo_coeff)

>>> cisolver =fci.direct_spin1.FCI(mol)

>>> e, ci =cisolver.kernel(h1, eri, h1.shape[1], mol.nelec, ecore=mol.energy_

˓→nuc())

>>> print(e)

-14.4197890826

1.9. fci — Full conﬁguration interaction 167

PySCF Documentation, Release 1.4.0

absorb_h1e(h1e,eri,norb,nelec,fac=1)

Modify 2e Hamiltonian to include 1e Hamiltonian contribution.

contract_1e(f1e,fcivec,norb,nelec,link_index=None,**kwargs)

Contract the 1-electron Hamiltonian with a FCI vector to get a new FCI vector.

contract_2e(eri,fcivec,norb,nelec,link_index=None,**kwargs)

Contract the 2-electron Hamiltonian with a FCI vector to get a new FCI vector.

Note the input arg eri is NOT the 2e hamiltonian matrix, the 2e hamiltonian is

ℎ2𝑒=𝑒𝑟𝑖𝑝𝑞,𝑟𝑠𝑝+𝑞𝑟+𝑠

= (𝑝𝑞|𝑟𝑠)𝑝+𝑟+𝑠𝑞 −(𝑝𝑞|𝑟𝑠)𝛿𝑞𝑟𝑝+𝑠

So eri is deﬁned as

𝑒𝑟𝑖𝑝𝑞,𝑟𝑠 = (𝑝𝑞|𝑟𝑠)−(1/𝑁 𝑒𝑙𝑒𝑐)

𝑞

(𝑝𝑞|𝑞𝑠)

to restore the symmetry between pq and rs,

𝑒𝑟𝑖𝑝𝑞,𝑟𝑠 = (𝑝𝑞|𝑟𝑠)−(.5/𝑁 𝑒𝑙𝑒𝑐)[

𝑞

(𝑝𝑞|𝑞𝑠) + 

𝑝

(𝑝𝑞|𝑟𝑝)]

Py SCF 1.4 Manual

Navigation menu

Versions of this User Manual:

Views

Navigation