Doc/improvements for ExternalActiveSpaceMethod

docs/source/howto.rst

@@ -12,3 +12,4 @@ HOWTOs
    methods/avas
    utils/plotting
    nb_api_intro
+   methods/external_solver

docs/source/methods/external_solver.rst

@@ -0,0 +1,186 @@
+.. _`sec:methods:external`:
+
+Read external RDMs, Export integrals
+====================================
+
+.. sectionauthor:: Renke Huang
+
+Forte implements the ``ExternalActiveSpaceMethod`` class to provide users with more flexilibity with the correlation computations.
+
+
+Read external RDMs for correlation computations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The Forte external solver will check if there is a json file named ``rdms.json`` present in the current working directory. 
+See `the test case <https://github.com/RenkeHuang/forte/blob/ext_doc/tests/methods/external_solver-1/rdms.json>`_ for the data format used in ``rdms.json``. 
+If the file is present, the external solver will read the RDMs and compute the reference energy. 
+Here is the simplest input for a DSRG-MRPT2 computation using external RDMs::
+
+    import forte
+    molecule h2{
+        0 1
+        H
+        H 1 0.7
+    }
+
+    set {
+        basis                cc-pVDZ
+        scf_type             pk
+        e_convergence        12
+    }
+
+    set forte {
+        active_space_solver  external    # read rdms.json, generate as_ints.json
+        active               [1, 0, 0, 0, 0, 1, 0, 0]
+        restricted_docc      [0, 0, 0, 0, 0, 0, 0, 0]
+        correlation_solver   dsrg-mrpt2
+        dsrg_s               0.5
+    }
+
+    energy('forte')
+
+
+
+Export integrals to disk
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Forte can export two types of integrals: 
+1) active space integrals from an ``ActiveSpaceSolver`` (which define a bare Hamiltonian), 
+2) DSRG-dressed integrals.
+The minimal input for writing active space integrals to disk (save as ``as_ints.json``) is::
+
+    import forte
+    molecule h2{
+        0 1
+        H
+        H 1 0.7
+    }
+
+    set {
+        basis                cc-pVDZ
+        scf_type             pk
+        e_convergence        12
+    }
+
+    set forte {
+        active_space_solver  external    # generate as_ints.json
+        write_wfn            true        # save coeff.json
+        active               [1, 0, 0, 0, 0, 1, 0, 0]
+        restricted_docc      [0, 0, 0, 0, 0, 0, 0, 0]
+    }
+
+    energy('forte')
+
+See `this example <https://github.com/RenkeHuang/forte/blob/ext_doc/tests/methods/external_solver-1/as_ints.json>`_ for the data and the data format used in ``as_ints.json``
+Note that saving the ``wfn.Ca()`` to ``coeff.json`` is always recommended to avoid sign flips and confusions in defining orbitals.
+
+For DSRG-dressed integrals, to enable the pipeline of the external active space solver and a correlation solver (computes the dressed integrals) that follows, 
+two files ``rdms.json`` and ``coeff.json`` are required in the working directory. 
+Then run the following input to export DSRG-dressed integrals to disk (save as ``dsrg_ints.json``)::
+
+    import forte
+    molecule h2{
+        0 1
+        H
+        H 1 0.7
+    }
+
+    set {
+        basis                cc-pVDZ
+        scf_type             pk
+        e_convergence        12
+    }
+
+    set forte {
+        active_space_solver  external    # read rdms.json, generate as_ints.json
+        read_wfn             true        # read coeff.json
+        active               [1, 0, 0, 0, 0, 1, 0, 0]
+        restricted_docc      [0, 0, 0, 0, 0, 0, 0, 0]
+        correlation_solver   dsrg-mrpt2
+        dsrg_s               0.5
+        relax_ref            once        # generate dsrg_ints.json
+        external_partial_relax true
+    }
+
+    energy('forte')
+
+Note that the data format used in JSON file is the same for both types of integrals (``as_ints.json`` and ``dsrg_ints.json``).
+
+
+Save RDMs to disk
+^^^^^^^^^^^^^^^^^
+Forte also provides the functionality of exporting the reference RDMs (from an ``ActiveSpaceSolver``) to disk (save as ``ref_rdms.json``). 
+This file shares the same data format as ``rdms.json``, so you can simply rename it for the purpose of quick testing of the external solver. 
+Note that the external solver is only an I/O interface and cannot compute the RDMs on its own. 
+To generate RDMs, we need to use another active space solver that implements the RDM calculations (for example, ``FCI``, ``CAS``, ``ACI``). 
+::
+
+    import forte
+    molecule h2{
+        0 1
+        H
+        H 1 0.7
+    }
+
+    set {
+        basis                cc-pVDZ
+        scf_type             pk
+        e_convergence        12
+    }
+
+    set forte {
+        active_space_solver  fci         # use: fci, cas, aci
+        write_rdm            true        # save ref_rdms.json
+        write_wfn            true        # save coeff.json
+        active               [1, 0, 0, 0, 0, 1, 0, 0]
+        restricted_docc      [0, 0, 0, 0, 0, 0, 0, 0]
+    }
+
+    energy('forte')
+
+
+Options
+^^^^^^^
+
+**WRITE_RDM**
+
+Save RDMs to ``ref_rdms.json`` for external computations.
+
+* Type: bool
+* Default: False
+
+**WRITE_WFN**
+
+Save ``ref_wfn.Ca()`` to ``coeff.json`` for external computations.
+
+* Type: bool
+* Default: False
+
+**READ_WFN**
+
+Read ``ref_wfn.Ca()/ref_wfn.Cb()`` from ``coeff.json`` for external active space solver.
+
+* Type: bool
+* Default: False
+
+**EXTERNAL_PARTIAL_RELAX**
+
+Perform one relaxation step after building the DSRG effective Hamiltonian when using external active space solver.
+
+* Type: bool
+* Default: False
+
+**EXT_RELAX_SOLVER**
+
+Active space solver used in the relaxation when using external active space solver.
+
+* Type: string
+* Options: FCI, DETCI, CAS
+* Default: FCI
+
+**SAVE_SA_DSRG_INTS**
+
+Save SA-DSRG dressed integrals to ``dsrg_ints.json``.
+
+* Type: bool
+* Default: False

forte/proc/external_active_space_solver.py

@@ -44,11 +44,14 @@ def read_wavefunction(ref_wfn):
 def write_external_active_space_file(as_ints, state_map, mo_space_info, json_file="forte_ints.json"):
     ndocc = mo_space_info.size("INACTIVE_DOCC")
 
+    # `state_map` only contains one state.
     for state, nroots in state_map.items():
         file = {}
 
         nmo = as_ints.nmo()
 
+        file['point_group'] = {"data": mo_space_info.point_group_label(), "description": "Point group of the system"}
+
         file['state_symmetry'] = {"data": state.irrep(), "description": "Symmetry of the state"}
 
         file['na'] = {"data": state.na() - ndocc, "description": "number of alpha electrons in the active space"}
@@ -140,7 +143,7 @@ def make_hamiltonian(as_ints, state_map):
                 H[I][J] = as_ints.slater_rules(detI,detJ)
                 # if I == J:
                 #     H[I][J] += scalar_e
-                          
+
         print(f'\n==> Active Space Hamiltonian <==\n')
         print(f'\n{H}')