[Docs] update gen_ham with UHF

docs/sphinx/components/solvers/introduction.rst

@@ -75,9 +75,6 @@ The :code:`molecule_options` structure provides extensive configuration for mole
 +---------------------+---------------+------------------+------------------------------------------+
 | integrals_casscf    | bool          | false            | Use CASSCF orbitals for integrals        |
 +---------------------+---------------+------------------+------------------------------------------+
-| potfile             | optional      | nullopt          | Path to external potential file          |
-|                     | <string>      |                  |                                          |
-+---------------------+---------------+------------------+------------------------------------------+
 | verbose             | bool          | false            | Enable detailed output logging           |
 +---------------------+---------------+------------------+------------------------------------------+
 

docs/sphinx/examples/solvers/python/generate_molecular_hamiltonians.py

@@ -9,7 +9,7 @@
 # [Begin Documentation]
 import cudaq_solvers as solvers
 
-# Generate active space Hamiltonian using HF molecular orbitals
+# Generate active space Hamiltonian using RHF molecular orbitals
 
 geometry = [('N', (0.0, 0.0, 0.5600)), ('N', (0.0, 0.0, -0.5600))]
 molecule = solvers.create_molecule(geometry,
@@ -20,7 +20,24 @@
                                    norb_cas=3,
                                    verbose=True)
 
-print('N2 HF Hamiltonian')
+print('N2 RHF Hamiltonian')
+print('Energies : ', molecule.energies)
+print('No. of orbitals: ', molecule.n_orbitals)
+print('No. of electrons: ', molecule.n_electrons)
+
+# Generate active space Hamiltonian using UHF molecular orbitals
+
+geometry = [('N', (0.0, 0.0, 0.5600)), ('N', (0.0, 0.0, -0.5600))]
+molecule = solvers.create_molecule(geometry,
+                                   'sto-3g',
+                                   0,
+                                   0,
+                                   nele_cas=2,
+                                   norb_cas=3,
+                                   UR=True,
+                                   verbose=True)
+
+print('N2 UHF Hamiltonian')
 print('Energies : ', molecule.energies)
 print('No. of orbitals: ', molecule.n_orbitals)
 print('No. of electrons: ', molecule.n_electrons)
@@ -83,3 +100,36 @@
 print('Energies: ', molecule.energies)
 print('No. of orbitals: ', molecule.n_orbitals)
 print('No. of electrons: ', molecule.n_electrons)
+
+# For open-shell systems: Generate active space Hamiltonian using ROHF molecular orbitals
+geometry = [('N', (0.0, 0.0, 0.5600)), ('N', (0.0, 0.0, -0.5600))]
+molecule = solvers.create_molecule(geometry,
+                                   'sto-3g',
+                                   1,
+                                   1,
+                                   nele_cas=3,
+                                   norb_cas=3,
+                                   ccsd=True,
+                                   verbose=True)
+
+print('N2+ ROHF Hamiltonian')
+print('Energies : ', molecule.energies)
+print('No. of orbitals: ', molecule.n_orbitals)
+print('No. of electrons: ', molecule.n_electrons)
+
+# For open-shell systems: Generate active space Hamiltonian using UHF molecular orbitals
+geometry = [('N', (0.0, 0.0, 0.5600)), ('N', (0.0, 0.0, -0.5600))]
+molecule = solvers.create_molecule(geometry,
+                                   'sto-3g',
+                                   1,
+                                   1,
+                                   nele_cas=3,
+                                   norb_cas=3,
+                                   ccsd=True,
+                                   UR=True,
+                                   verbose=True)
+
+print('N2+ UHF Hamiltonian')
+print('Energies : ', molecule.energies)
+print('No. of orbitals: ', molecule.n_orbitals)
+print('No. of electrons: ', molecule.n_electrons)

docs/sphinx/examples_rst/solvers/molecular_hamiltonians.rst

@@ -2,16 +2,16 @@ Generating Molecular Hamiltonians
 ----------------------------------
 
 The CUDA-Q Solvers library accelerates a wide range of applications in the domain of quantum chemistry.
-To facilitate these calculations, CUDA-Q Solvers provides the `solver.create_molecule` function to allow users to generate basis sets and Hamiltonians for many systems of interest.
-The molecule class contains basis set informations, and the Hamiltonian (`molecule.hamiltonian`) for the target systems.
+To facilitate these calculations, CUDA-Q Solvers provides the `solver.create_molecule` function to allow users to generate the electronic Hamiltonians for many systems of interest.
+The molecule class contains informations about the Hamiltonian (`molecule.hamiltonian`) for the target systems.
 These Hamiltonians can then be used as input into the hybrid quantum-classical solvers that the CUDA-Q Solvers API provides.
 
 
 Molecular Orbitals and Hamiltonians
 +++++++++++++++++++++++++++++++++++
 
-First we define the atomic geometry of the molecule by specifying a array of atomic symbols as strings, and coordinates in 3D space. We then get a molecule object from the `solvers.create_molecule` call.
-Here we create "default" Hamiltonian for the N2 system using complete active space molecular orbitals constructed from Hartree-Fock atomic orbitals.
+First, we define the atomic geometry of the molecule by specifying an array of atomic symbols as strings, and coordinates in 3D space. We then get a molecule object from the `solvers.create_molecule` call.
+Here, we create "default" Hamiltonian for the N2 system using complete active space molecular orbitals constructed from Restricted Hartree-Fock molecular orbitals.
 
 .. tab:: Python
 
@@ -27,15 +27,32 @@ Here we create "default" Hamiltonian for the N2 system using complete active spa
                                        verbose=True)
 
 We specify:
-  - The geometry previously created
-  - The single particle basis set (here STO-3G)
-  - The total spin
+  - The geometry previously created. User can also provide geometry through the path to the XYZ file. For example, `geometry='path/to/xyz/file.xyz'`.
+  - The basis set (here STO-3G)
+  - The total spin (2 * S)
   - The total charge
   - The number of electrons in the complete active space
-  - The number of orbitals in the complete activate space
+  - The number of orbitals in the complete active space
   - A verbosity flag to help introspect on the data what was generated.
 
-Along with the orbitals and Hamiltonian, we can also view various properties like the Hartree-Fock energy, and the energy of the frozen core orbitals by printing `molecule.energies`.
+Along with the Hamiltonian, we can also view various properties like the Hartree-Fock energy, and the energy of the frozen core orbitals by printing `molecule.energies`.
+
+For using Unrestricted Hartree-Fock (UHF) orbitals, user can set the `UR` parameter to `True` in the `create_molecule` function. Here's an example:
+
+.. tab:: Python
+
+  .. code-block:: python
+
+    geometry = [('N', (0.0, 0.0, 0.5600)), ('N', (0.0, 0.0, -0.5600))]
+    molecule = solvers.create_molecule(geometry,
+                                       'sto-3g',
+                                       0,
+                                       0,
+                                       nele_cas=2,
+                                       norb_cas=3,
+                                       UR=True,
+                                       verbose=True)
+
 
 Natural Orbitals from MP2
 ++++++++++++++++++++++++++
@@ -56,12 +73,15 @@ Now we take our same N2 molecule, but generate natural orbitals from second orde
                                        integrals_natorb=True,
                                        verbose=True)
 
-Note that we use the same API but,toggle `MP2=True` and `integrals_natorb=True`.
+Note that we use the same API but,toggle `MP2=True` and `integrals_natorb=True`. This will generate the molecular orbitals from MP2 natural orbitals, and compute the Hamiltonian integrals in this basis.
+This option is unallowed yet when using `UR=True`. When using `UR=True`, only UHF molecular orbitals are employed to generate the electronic Hamiltonian.
 
 CASSCF Orbitals
 +++++++++++++++
 
-Next, we can start from either Hartree-Fock or perturbation theory atomic orbitals and build complete active space self-consistent field (CASSCF) molecular orbitals.
+Next, we can start from either Hartree-Fock or perturbation theory natural orbitals and build complete active space self-consistent field (CASSCF) molecular orbitals.
+
+In the example below, we employ the CASSCF procedure starting from RHF molecular orbitals to generate the spin molecular Hamiltonian.
 
 .. tab:: Python
 
@@ -78,7 +98,8 @@ Next, we can start from either Hartree-Fock or perturbation theory atomic orbita
                                        integrals_casscf=True,
                                        verbose=True)
 
-For Hartree-Fock, or
+Alternatively, we can also start from RHF, then MP2 natural orbitals and then perform CASSCF to generate the spin molecular Hamiltonian.
+In this case, natural orbitals from MP2 are used to set the active space for the CASSCF procedure.
 
 .. tab:: Python
 
@@ -97,7 +118,42 @@ For Hartree-Fock, or
                                        integrals_casscf=True,
                                        verbose=True)
 
-for MP2. In these cases, printing the `molecule.energies` also shows the `R-CASSCF` energy for the system.
+In these cases, printing the `molecule.energies` also shows the `R-CASSCF` energy for the system.
 
-Now that we have seen how to generate basis sets and Hamiltonians for quantum chemistry systems, we can use these as inputs to hybrid quantum-classical methods like VQE or adapt VQE via the CUDA-Q Solvers API.
 
+For open-shell systems
+++++++++++++++++++++++++++
+
+For Restricted Open-shell Hartree-Fock (ROHF) orbitals, user can set the `spin` parameter to a non-zero value while keeping the `charge` parameter as needed. For example, for a molecule with one unpaired electron, you can set `spin=1` and `charge=1`. Here's an example:
+
+.. tab:: Python
+
+  .. code-block:: python
+
+    geometry = [('N', (0.0, 0.0, 0.5600)), ('N', (0.0, 0.0, -0.5600))]
+    molecule = solvers.create_molecule(geometry,
+                                       'sto-3g',
+                                       1,
+                                       1,
+                                       nele_cas=3,
+                                       norb_cas=3,
+                                       verbose=True)
+
+
+For Unrestricted Hartree-Fock (UHF) orbitals, user can set `UR=True` and the `spin` parameter to a non-zero value while keeping the `charge` parameter as needed. Here's an example:
+
+.. tab:: Python
+
+  .. code-block:: python
+
+    geometry = [('N', (0.0, 0.0, 0.5600)), ('N', (0.0, 0.0, -0.5600))]
+    molecule = solvers.create_molecule(geometry,
+                                       'sto-3g',
+                                       1,
+                                       1,
+                                       nele_cas=3,
+                                       norb_cas=3,
+                                       UR=True,
+                                       verbose=True)
+
+Now that we have seen how to generate the spin molecular Hamiltonians for quantum chemistry systems, we can use these as inputs to hybrid quantum-classical methods like VQE or adapt VQE via the CUDA-Q Solvers API.