Running Forte computations

In this section, we will look at the basics of running computations in Forte.

There are two ways one can run Forte:

  1. Using the plugin interface in Psi4.

  2. Using Forte’s python API.

Running a FCI computation using the plugin interface

Let’s start by looking at how one can run Forte as a plugin to Psi4. The following text input (see examples/plugin/01_fci/input.dat) can be used to run a FCI computation on the lithium dimer:

# examples/plugin/01_fci/input.dat

import forte

molecule {
0 1
Li 0.0 0.0 0.0
Li 0.0 0.0 3.0
units bohr
}

set {
  basis sto-3g
  scf_type pk
  e_convergence 10
}

set forte {
  active_space_solver fci
}

energy('forte')

To understand the structure of the input file, we will go over each section of this input.

  • The file start with the import forte command, which loads the Forte module.

  • The next section specifies the molecular structure and the charge/multiplicity of the molecule. This section accepts inputs as specified in Psi4’s Molecule and Geometry Specification documentation, and accepts both Cartesian and Z-matrix coordinates

molecule {
0 1
Li 0.0 0.0 0.0
Li 0.0 0.0 3.0
units bohr
}

  • The options block that follows passes options to Psi4. Here we set the basis (basis sto-3g), the type of SCF integral algorithm (scf_type pk, which uses conventional integrals), and the energy convergence threshold (e_convergence 10, equivalent to \(10^{-10}\; E_\mathrm{h}\))

set {
  basis sto-3g
  scf_type pk
  e_convergence 10
}

  • The next section sets options specific to Forte. In a typical Forte job the user needs to specify two objects:

    • An active space solver, used to treat static correlation effects. The active space solver finds a solution to the Schrödinger equation in the subset of active orbitals.

    • A dynamical correlation solver, used to add dynamical electron correlation corrections on top of a wave function defined in the active space. To run a FCI computation, we only need to specify the active space solver, which is done by setting the option active_space_solver:

set forte {
  active_space_solver fci
}

  • The last line of the input calls the Psi4 energy method specifing that we want to run the forte module

energy('forte')

To run this computation we invoke psi4 on the command line

>>>psi4 input.dat

This will run psi4 and produce the output file output.dat, a copy of which is available in the file examples/plugin/01_fci/output.dat. From this output, we can read the CI coefficient of the most important determinants written in occupation number representation

220 0 0 200 0 0      0.89740847 <-- coefficient
200 0 0 200 0 2     -0.29206218
200 0 0 200 2 0     -0.29206218
200 0 0 220 0 0     -0.14391931

and a summary of the total energy of a state and the expectation value of the spin squared operator (\(\hat{S}^2\))

Multi.(2ms)  Irrep.  No.               Energy      <S^2>
--------------------------------------------------------
   1  (  0)    Ag     0      -14.595808852754  -0.000000
--------------------------------------------------------

Running a FCI computation using the python API

The following input runs the same FCI computation discussed above using the python API:

# examples/api/01_fci.py

import psi4
import forte

psi4.geometry("""
0 1
Li 0.0 0.0 0.0
Li 0.0 0.0 3.0
units bohr
""")

psi4.set_options({
    'basis': 'sto-3g',                    # <-- set the basis set
    'scf_type': 'pk',                     # <-- request conventional two-electron integrals
    'e_convergence': 10,                  # <-- set the energy convergence
    'forte__active_space_solver' : 'fci'} # <-- specify the reference
    )

psi4.energy('forte')

This python file mirrors the psi4 input file.

  • The file start with both the import psi4 and import forte commands, to load both the psi4 and Forte modules.

  • The next command creates a psi4 Molecule object calling the function psi4.geometry. This object is stored in a default memory location and automatically used by psi4

psi4.geometry("""
0 1
Li 0.0 0.0 0.0
Li 0.0 0.0 3.0
units bohr
""")

  • The options block that follows passes options to both Psi4 and Forte. Here we pass options as a python dictionary, prefixing options that are specific to Forte with forte__:

psi4.set_options({
    'basis': 'sto-3g',                    # <-- set the basis set
    'scf_type': 'pk',                     # <-- request conventional two-electron integrals
    'e_convergence': 10,                  # <-- set the energy convergence
    'forte__active_space_solver' : 'fci'} # <-- specify the active space solver
    )

  • The last line of the python code calls the Psi4 energy method specifing that we want to run the forte module

psi4.energy('forte')

This computation is identical to the previous one and produces the exact same output (see examples/plugin/01_fci.out).

Test cases and Jupyter Tutorials

  • Test cases. Forte provides test cases for most of all methods implemented. This is a good place to start if you are new to Forte. Test cases based on Psi4’s plugin interface can be found in the <fortedir>/tests/methods folder. Test cases based on Forte’s python API can be found in the <fortedir>/tests/pytest folder.

  • Jupyter Tutorials for Forte’s Python API. Forte is designed as a C++ library with a lot of the classes and functionality exposed in Python via the pybind11 library. Tutorials on how to use Forte’s API can be found here.