CAS-nSF-IP/EA Package

Installation

Clone the program from the GitHub repository:

$ git clone https://github.com/shannonhouck/sf-ip-ea.git

Then naviate into the directory and use pip to install:

$ cd sf-ip-ea/
$ pip install -e .

You can now import this package into Python. Note that some dependencies may be required (ex. numpy, scipy, Psi4).

Running CAS-SF/IP/EA

The RAS-SF-IP/EA code is run by calling the fock_ci function. A sample input file (using the Psi4 interface) can be found below:

import psi4
import sf_ip_ea

# Psi4 Molecule object
n2_7 = psi4.core.Molecule.from_string("""
0 7
N 0 0 0
N 0 0 2.5
symmetry c1
""")

# Psi4 options
options = {"BASIS": "cc-pvdz"}
# Fock CI options
sf_options = {'NUM_ROOTS': 2}

# do RAS(p)-1SF
wfn = sf_ip_ea.fock_ci( 1, 1, n2_7, conf_space="p", ref_opts=options,
                        sf_opts=sf_options)

A few important things to note:

• The number of spin-flips and IP/EA is determined by the first two numbers passed into fock_ci. The first integer is the number of alpha electrons to remove, relative to the reference wavefunction; the second is the number of beta electrons to add. For more information about method selection, see [TODO: add table link].

• The object returned is a wfn_sf object. Any additional information needed can then be extracted from this object (ex. Sz values, information about RAS spaces, or eigenvectors). For example, you could get an array of the eigenvalues using wfn.e. For more information about the wfn_sf object, see [TODO: link to wfn_sf page].

This input file can then be run from the command line:

$ python input.py

For additional information about fock_ci, see [TODO: add link].

Selecting nSF-IP/EA Method

As mentioned previously, the number of spin-flips and IP/EA is determined exclusively by the number of alpha electrons removed and beta electrons added. A table of currently-supported options is shown below.

Scheme	n_alpha	n_beta
1SF	1	1
2SF	2	2
IP	1	0
EA	0	1
1SF-IP	2	1
1SF-EA	1	2

Note that if you do not see your desired scheme here, you can use our slower but more general Psi4 version run using DETCI [TODO: add link].

Adding Hole and Particle Excitations

Hole and particle excitations are often needed to provide orbital relaxation, particularly in the SF-IP/EA schemes (see [TODO: ref]). The following excitation schemes are currently implemented in our code:

	CAS	RAS(h)	RAS(p)	RAS(h,p)
1SF	Y	Y	Y	Y
2SF	Y
IP	Y	Y	Y
EA	Y	Y	Y
1SF-IP	Y	Y
1SF-EA	Y		Y

In order to perform hole and particle excitations, use the conf_space keyword passed into fock_ci. Schemes are called as follows:

Scheme	conf_space
CAS	""
RAS(h)	"h"
RAS(p)	"p"
RAS(h,p)	"h,p"

So, for example, to do RAS(h)-1SF-IP, one would do:

wfn = fock_ci( 2, 1, mol, conf_space="h")

If you do not see your desired scheme here, please revert to the Psi4 plugin version using DETCI [TODO: add link].

Reference Options: REF_OPTS

The ref_opts keyword allows the user to pass in additional options for the program running the reference SCF portion of the calculation. These are set uniquely for each program (Psi4, PySCF, etc). It is passed like follows:

psi4_options = {"basis": "cc-pvtz", "reference": "rohf", "guess": "gwh"}
wfn = fock_ci(1, 1, mol, ref_opts=psi4_options)

See the documentation for each package for details.

Additional Options: SF_OPTS

The sf_opts keyword holds a dictionary that defines all other options for the fock_ci method. It can be used to select the diagonalization method, the CI guess type, which types of integrals to use, and more. These options are passed as an optional argument to fock_ci as follows:

sf_options = {'sf_diag_method': 'lanczos', 'num_roots': 5}
wfn = fock_ci(1, 1, mol, sf_opts=sf_options)

Number of Roots

By default, the program solves for only one root. To solve for multiple roots, use the NUM_ROOTS keyword:

sf_options = {'num_roots': 5}
wfn = fock_ci(1, 1, mol, sf_opts=sf_options)

Passing In A Reference

At times, the user may want to use their own pre-converged ROHF reference wavefunction, rather than allowing fock_ci to do the SCF steps itself. (This is helpful in cases where orbitals need to be localized, for example, or when one ROHF solution can be used for multiple calculations.) In such a circumstance, the user may use the READ_PSI4_WFN keyword and the PSI4_WFN keyword like so:

# converge Psi4 ROHF wfn
options = {"basis": "cc-pvtz", "reference": "rohf"}
psi4.set_options(options)
e, psi4_wfn = psi4.energy('scf', molecule=mol, return_wfn=True)

# do SF portion
sf_options = {'READ_PSI4_WFN': True, 'PSI4_WFN': psi4_wfn}
wfn = fock_ci(1, 1, mol, ref_opts=options, sf_opts=sf_options)

Diagonalization Methods

Multiple options are available for diagonalization. To select one, choose from the following keywords:

• RSP: Full diagonalization (deprecated)

• LANCZOS: Use NumPy’s built-in Lanczos solver (default)

• DAVIDSON: Use our Davidson (needs testing)

Currently, LANCZOS is the default, due to a lack of rigorous testing in the Davidson implementation. In the future, Davidson will be the default.

In addition, one can pass in DO_MATRIX to obtain the full Hamiltonian without diagonalization steps. This is stored in sf_wfn.H and can be accessed after a fock_ci call:

sf_options = {'SF_DIAG_METHOD': 'DO_MATRIX'}
wfn = fock_ci( 1, 1, n2_7, ref_opts=options, sf_opts=sf_options)
print(wfn.H)

The guess for the diagonalization is set using GUESS_TYPE. Currently, a random orthonormal basis is the default. In the future we will implement a rigorous CAS guess and an option to read guess vectors from a NumPy file.

Integral Type

The INTEGRAL_TYPE keyword allows the user to choose whether to use density-fitted or full integrals:

• DF: Use density-fitted integrals

• FULL: Use full integrals

Note that the auxiliary basis is chosen based on the Psi4 settings.

Bloch Effective Hamiltonian Analysis

A Bloch effective Hamiltonian can be built in order to extract information about coupling in complexes with more than two centers (for example in some mixed-valent complexes, or lanthanide dimers in fullerene cages). A sample input file for such a situation is shown below:

import psi4
import sf_ip_ea
from sf_ip_ea import bloch

mol = psi4.core.Molecule.from_string("""
0 7
O 0 0 0
O 2 0 0
O 4 0 0
symmetry c1
""")

options = {"BASIS": "sto-3g"}
sf_options = {'NUM_ROOTS': 3}

wfn = sf_ip_ea.fock_ci( 1, 1, mol, ref_opts=options, sf_opts=sf_options)
n_sites = 3
H = bloch.do_bloch(wfn, n_sites)

Note that Bloch is only supported for the Psi4 interface right now, and that the program only supports 1SF calculations at the moment.

Defining Sites

By default, each orbital in the CAS space is treated as its own site. This behavior can be overridden by specifying either of the following keywords:

• site_list: A list of atom indexes, where each atom corresponds to one site. The numbering here follows the ordering of atoms in the Psi4 Molecule object and starts at 0. For example:

  H = bloch.do_bloch(wfn, n_sites, site_list=[0,1,2])
  

• site_list_orbs: A list of lists of orbital indexes, with each sub-list counted as its own site. For example:

  H = bloch.do_bloch(wfn, n_sites,
                     site_list_orbs=[[10,11,13],[12,14,15]],
                     skip_localization=True)
  

  Ordering follows Psi4 ordering, and orbital indexing starts at 1. In this case, the user should localize the orbitals themselves, make the assignments by hand, and set skip_localization=True in the function call.

Modules

For more information on modules, see below.

sf_ip_ea	A program for running RAS-SF-IP/EA calculations.
bloch	Bloch effective Hamiltonian solver.
f	Handling of the Fock matrix.
fock_wfn	Fock CI calculation information storage.
linop	LinOp module responsible for performing Hamiltonian-vector multiplication.
np_sf	NumPy-based Fock-space CI.
post_ci_analysis	Handling post-CI analysis.
psi4_sf	Fock-space CI using Psi4’s interface.
solvers	Davidson solver module.
tei	Two-electron integral object handling.

References

The following pages have been useful in the making of this code:

• Crawford Tutorials (http://sirius.chem.vt.edu/wiki/doku.php)

• DePrince Tutorials (https://www.chem.fsu.edu/~deprince/programming_projects/cis/)

• Sherrill Notes (http://vergil.chemistry.gatech.edu/notes/cis/cis.html)

• Psi4NumPy Tutorials

Indices and tables

• Index

• Module Index

• Search Page