Add AFQMC tutorials to docs.

docs/afqmc.rst

@@ -714,56 +714,6 @@ The following is a growing list of useful advice for new users, followed by a sa
       <parameter name="ortho">5</parameter>
     </execute>
 
-.. _pyscf:
-
-Using PySCF to generate integrals for AFQMC
--------------------------------------------
-
-
-PySCF (https://github.com/sunqm/pyscf) is a collection of electronic structure programs powered by Python. It is the recommended program for the generation of input for AFQMC calculations in QMCPACK. We refer the reader to the documentation of the code (http://sunqm.github.io/pyscf/) for a detailed description of the features and the functionality of the code. While the notes below are not meant to replace a detailed study of the PySCF documentation, these notes describe useful knowledge and tips in the use of pyscf for the generation of input for QMCPACK.
-
-For molecular systems or periodic calculations at the Gamma point, PySCF provides a routine that generates the integral file in Molpro's FCIDUMP format, which contains all the information needed to run AFQMC with a single determinant trial wave-function. Below is an example using this routine to generate the FCIDUMP file for an 8-atom unit cell of carbon in the diamond structure with HF orbitals. For a detailed description, see PySCF's documentation.
-
-.. code-block::
-  :caption: Simple example showing how to generate FCIDUMP files with PySCF
-  :name: Listing 57
-
-  import numpy
-  from pyscf.tools import fcidump
-  from pyscf.pbc import gto, scf, tools
-
-  cell = gto.Cell()
-  cell.a = '''
-    3.5668 0 0
-    0 3.5668 0
-    0 0 3.5668'''
-  cell.atom = '''
-    C 0. 0. 0.
-    C 0.8917 0.8917 0.8917
-    C 1.7834 1.7834 0.
-    C 2.6751 2.6751 0.8917
-    C 1.7834 0. 1.7834
-    C 2.6751 0.8917 2.6751
-    C 0. 1.7834 1.7834
-    C 0.8917 2.6751 2.6751'''
-  cell.basis = 'gth-szv'
-  cell.pseudo = 'gth-pade'
-  cell.gs = [10]*3 # for testing purposes, must be increased for converged results
-  cell.verbose = 4
-  cell.build()
-
-  mf = scf.RHF(cell)
-  ehf = mf.kernel()
-  print("HF energy (per unit cell) = %.17g" % ehf)
-
-  c = mf.mo_coeff
-  h1e = reduce(numpy.dot, (c.T, mf.get_hcore(), c))
-  eri = mf.with_df.ao2mo(c,compact=True)
-
-  # nuclear energy + electronic ewald
-  e0 = cell.energy_nuc() + tools.pbc.madelung(cell, numpy.zeros(3))*cell.nelectron * -.5
-  fcidump.from_integrals('fcidump.dat', h1e, eri, c.shape[1],cell.nelectron, ms=0, tol=1e-8, nuc=e0)
-
 .. centered:: ``afqmc`` method
 
 parameters in ``AFQMCInfo``
@@ -857,4 +807,10 @@ parameters in ``execute``
 | ``ortho``    | integer      | :math:`> 0`             | 1           | Number of steps between walker orthogonalization. |
 +--------------+--------------+-------------------------+-------------+---------------------------------------------------+
 
+
+.. _pyscf:
+
+Using PySCF to generate integrals and trial wavefunctions for AFQMC
+------------------------------------------------------------------
+
 .. bibliography:: /bibs/afqmc.bib

docs/index.rst

@@ -37,6 +37,7 @@ User's Guide and Developer's Manual
    lab_advanced_molecules
    lab_condensed_matter
    lab_excited
+   lab_afqmc
    additional_tools
    external_tools
    contributing

examples/afqmc/01-neon_atom/README.rst

@@ -1,5 +1,5 @@
 Example 1: Neon atom
-====================
+--------------------
 
 In this example we will go through the basic steps necessary to
 generate AFQMC input from a pyscf scf calculation on a simple closed

examples/afqmc/02-neon_frozen_core/README.rst

@@ -1,5 +1,5 @@
 Example 2: Frozen Core
-======================
+----------------------
 
 In this example we show how to perform a frozen core calculation, which only affects the
 integral generation step. We will use the the previous Neon example and freeze 2 core

examples/afqmc/03-carbon_triplet_uhf/README.rst

@@ -1,5 +1,5 @@
 Example 3: UHF Trial
-====================
+--------------------
 
 In this example we show how to use a unrestricted Hartree--Fock (UHF) style wavefunction
 to find the ph-AFQMC (triplet) ground state energy of the carbon atom (cc-pvtz). Again we

examples/afqmc/04-N2_nomsd/README.rst

@@ -1,5 +1,5 @@
 Example 4: NOMSD Trial
-======================
+----------------------
 
 In this example we will show how to format trial different wavefunctions in such a way
 that qmcpack can read them.

examples/afqmc/05-N2_phmsd/README.rst

@@ -1,10 +1,79 @@
 Example 5: CASSCF Trial
-=======================
+-----------------------
 
 In this example we will show how to format a casscf trial wavefunction.
 
 Rather than use the `pyscf_to_afqmc.py`, script we will break up the process to allow
 for more flexibility and show what is going on under the hood.
 
-The qmcpack input can be generated with the scf.py script. See the comments in
-scf.py for a breakdown of the steps involved.
+The qmcpack input can be generated with the scf.py script followed by gen_input.py.
+
+See the relevant code below for a breakdown of the steps involved.
+
+The first step is to run a CASSCF calculation. Here we'll consider N:sub:2. This
+replicates the calculations from Al-Saidi et al J. Chem. Phys. 127, 144101 (2007).
+They find a CASSCF energy of -108.916484 Ha, and a ph-AFQMC energy of -109.1975(6) Ha with
+a 97 determinant CASSCF trial.
+
+.. code-block:: python
+
+    mol = gto.M(atom=[['N', (0,0,0)], ['N', (0,0,3.0)]],
+                basis='cc-pvdz',
+                unit='Bohr')
+    nalpha, nbeta = mol.nelec
+    rhf = scf.RHF(mol)
+    rhf.chkfile = 'scf.chk'
+    rhf.kernel()
+
+    M = 12
+    N = 6
+    nmo = rhf.mo_coeff.shape[-1]
+    mc = mcscf.CASSCF(rhf, M, N)
+    mc.chkfile = 'scf.chk'
+    mc.kernel()
+
+Next we unpack the wavefunction
+
+.. code-block:: python
+
+    nalpha = 3
+    nbeta = 3
+    ci, occa, occb = zip(*fci.addons.large_ci(mc.ci, M, (nalpha,nbeta),
+                         tol=tol, return_strs=False))
+
+and sort the determinants by the magnitude of their weight:
+
+.. code-block:: python
+
+    ixs = numpy.argsort(numpy.abs(coeff))[::-1]
+    coeff = coeff[ixs]
+    occa = numpy.array(occa)[ixs]
+    occb = numpy.array(occb)[ixs]
+
+Next we reinsert the frozen core as the AFQMC simulation is not run using an active space:
+
+.. code-block:: python
+
+    core = [i for i in range(mc.ncore)]
+    occa = [numpy.array(core + [o + mc.ncore for o in oa]) for oa in occa]
+    occb = [numpy.array(core + [o + mc.ncore for o in ob]) for ob in occb]
+
+Next we need to generate the one- and two-electron integrals. Note that we need to use the
+CASSCF MO coefficients to rotate the integrals.
+
+.. code-block:: python
+
+    scf_data = load_from_pyscf_chk_mol('scf.chk', 'mcscf')
+    write_hamil_mol(scf_data, 'afqmc.h5', 1e-5, verbose=True)
+
+Finally we can write the wavefunction to the QMCPACK format:
+
+.. code-block:: python
+
+    ci = numpy.array(ci, dtype=numpy.complex128)
+    uhf = True # UHF always true for CI expansions.
+    write_qmcpack_wfn('afqmc.h5', (ci, occa, occb), uhf, mol.nelec, nmo)
+
+To generate the input file we again run ``gen_input.py``. Note the ``rediag`` option which
+is necessary if the CI code used uses a different convention for ordering creation and
+annihilation operations when defining determinant strings.

examples/afqmc/06-methane_converge_back_prop/README.rst

@@ -1,5 +1,5 @@
 Example 6: Back Propagation
-===========================
+---------------------------
 
 .. note::
     matplotlib is required to generate the figure in this example.
@@ -45,7 +45,7 @@ reduced density matrix (1RDM), given as
 
 .. math::
 
-    P^{\sigma}_{ij} = \langle c_{\sigma i}^{\dagger} c_{\sigma j} \rangle
+    P^{\sigma}_{ij} = \langle c_{i\sigma}^{\dagger} c_{j\sigma} \rangle
 
 Before we analyse the output we should question why we chose a back propagation time of 2
 au.  The back propagation time represents yet another parameter which must be carefully

examples/afqmc/07-diamond_2x2x2_supercell/README.rst

@@ -1,5 +1,5 @@
 Example 7: 2x2x2 Diamond supercell
-==================================
+----------------------------------
 
 In this example we will show how to generate the AFQMC input from a pbc pyscf calculation
 for a 2x2x2 supercell of diamond using a RHF trial wavefunction.

examples/afqmc/08-diamond_2x2x2_kpoint_sym/README.rst

@@ -1,5 +1,5 @@
 Example 8: 2x2x2 Diamond k-point symmetry
-==========================================
+-----------------------------------------
 
 In this example we will show how to run an AFQMC simulation that exploits k-point symmetry
 which is much more efficient that running in the supercell way discussed in the previous