From 0fb4df956e51816ecacad997749f1a006afb5374 Mon Sep 17 00:00:00 2001 From: marwafar Date: Wed, 5 Nov 2025 20:33:02 +0000 Subject: [PATCH 1/5] update gen_ham with UHF Signed-off-by: marwafar --- .../components/solvers/introduction.rst | 3 - .../python/generate_molecular_hamiltonians.py | 54 ++++++++++++++++- .../solvers/molecular_hamiltonians.rst | 59 ++++++++++++++++++- 3 files changed, 108 insertions(+), 8 deletions(-) diff --git a/docs/sphinx/components/solvers/introduction.rst b/docs/sphinx/components/solvers/introduction.rst index 3bd0c869..b6303a0b 100644 --- a/docs/sphinx/components/solvers/introduction.rst +++ b/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 | -| | | | | -+---------------------+---------------+------------------+------------------------------------------+ | verbose | bool | false | Enable detailed output logging | +---------------------+---------------+------------------+------------------------------------------+ diff --git a/docs/sphinx/examples/solvers/python/generate_molecular_hamiltonians.py b/docs/sphinx/examples/solvers/python/generate_molecular_hamiltonians.py index c5e719c2..45ef4143 100644 --- a/docs/sphinx/examples/solvers/python/generate_molecular_hamiltonians.py +++ b/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) diff --git a/docs/sphinx/examples_rst/solvers/molecular_hamiltonians.rst b/docs/sphinx/examples_rst/solvers/molecular_hamiltonians.rst index 8ba2d754..a8d6de1e 100644 --- a/docs/sphinx/examples_rst/solvers/molecular_hamiltonians.rst +++ b/docs/sphinx/examples_rst/solvers/molecular_hamiltonians.rst @@ -11,7 +11,7 @@ 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. +Here we create "default" Hamiltonian for the N2 system using complete active space molecular orbitals constructed from Restricted Hartree-Fock molecular orbitals. .. tab:: Python @@ -37,6 +37,23 @@ We specify: 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`. +For using Unrestricted Hartree-Fock (UHF) orbitals, you 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 ++++++++++++++++++++++++++ Now we take our same N2 molecule, but generate natural orbitals from second order Møller–Plesset perturbation theory as the basis. @@ -56,7 +73,8 @@ 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 +++++++++++++++ @@ -97,7 +115,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. +for MP2 natural orbitals. 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 +++++++++++++++++++++++++++ + +If you want to use Restricted Open-shell Hartree-Fock (ROHF) orbitals, you 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) + + +If you want to use Unrestricted Hartree-Fock (UHF) orbitals, you 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) \ No newline at end of file From a5be51a02298a282aea4f4bb061be82b3af2d5ba Mon Sep 17 00:00:00 2001 From: marwafar Date: Wed, 5 Nov 2025 20:39:24 +0000 Subject: [PATCH 2/5] yapf Signed-off-by: marwafar --- .../python/generate_molecular_hamiltonians.py | 30 +++++++++---------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/sphinx/examples/solvers/python/generate_molecular_hamiltonians.py b/docs/sphinx/examples/solvers/python/generate_molecular_hamiltonians.py index 45ef4143..732353c5 100644 --- a/docs/sphinx/examples/solvers/python/generate_molecular_hamiltonians.py +++ b/docs/sphinx/examples/solvers/python/generate_molecular_hamiltonians.py @@ -104,13 +104,13 @@ # 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) + 'sto-3g', + 1, + 1, + nele_cas=3, + norb_cas=3, + ccsd=True, + verbose=True) print('N2+ ROHF Hamiltonian') print('Energies : ', molecule.energies) @@ -120,14 +120,14 @@ # 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) + 'sto-3g', + 1, + 1, + nele_cas=3, + norb_cas=3, + ccsd=True, + UR=True, + verbose=True) print('N2+ UHF Hamiltonian') print('Energies : ', molecule.energies) From 2f844cb80f5292c98ffecffe1feb58bd799f5cf9 Mon Sep 17 00:00:00 2001 From: marwafar Date: Thu, 6 Nov 2025 00:44:02 +0000 Subject: [PATCH 3/5] update molecular_hamiltonian.rst Signed-off-by: marwafar --- .../solvers/molecular_hamiltonians.rst | 37 ++++++++++--------- 1 file changed, 20 insertions(+), 17 deletions(-) diff --git a/docs/sphinx/examples_rst/solvers/molecular_hamiltonians.rst b/docs/sphinx/examples_rst/solvers/molecular_hamiltonians.rst index a8d6de1e..cd1322b6 100644 --- a/docs/sphinx/examples_rst/solvers/molecular_hamiltonians.rst +++ b/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 Restricted Hartree-Fock molecular 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 @@ -28,16 +28,16 @@ Here we create "default" Hamiltonian for the N2 system using complete active spa We specify: - The geometry previously created - - The single particle basis set (here STO-3G) - - The total spin + - 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, you can set the `UR` parameter to `True` in the `create_molecule` function. Here's an example: +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 @@ -79,7 +79,9 @@ This option is unallowed yet when using `UR=True`. When using `UR=True`, only UH 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 @@ -96,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 @@ -115,15 +118,13 @@ For Hartree-Fock, or integrals_casscf=True, verbose=True) -for MP2 natural orbitals. 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. +In these cases, printing the `molecule.energies` also shows the `R-CASSCF` energy for the system. For open-shell systems ++++++++++++++++++++++++++ -If you want to use Restricted Open-shell Hartree-Fock (ROHF) orbitals, you 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: +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 @@ -139,7 +140,7 @@ If you want to use Restricted Open-shell Hartree-Fock (ROHF) orbitals, you can s verbose=True) -If you want to use Unrestricted Hartree-Fock (UHF) orbitals, you can set `UR=True` and the `spin` parameter to a non-zero value while keeping the `charge` parameter as needed. Here's an example: +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 @@ -153,4 +154,6 @@ If you want to use Unrestricted Hartree-Fock (UHF) orbitals, you can set `UR=Tru nele_cas=3, norb_cas=3, UR=True, - verbose=True) \ No newline at end of file + 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. From b5d70178f2c3fb7519a36db3f1ef7f33d27d7065 Mon Sep 17 00:00:00 2001 From: marwafar Date: Thu, 6 Nov 2025 01:10:14 +0000 Subject: [PATCH 4/5] xyz file in geometry Signed-off-by: marwafar --- docs/sphinx/examples_rst/solvers/molecular_hamiltonians.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sphinx/examples_rst/solvers/molecular_hamiltonians.rst b/docs/sphinx/examples_rst/solvers/molecular_hamiltonians.rst index cd1322b6..d4671496 100644 --- a/docs/sphinx/examples_rst/solvers/molecular_hamiltonians.rst +++ b/docs/sphinx/examples_rst/solvers/molecular_hamiltonians.rst @@ -27,7 +27,7 @@ Here, we create "default" Hamiltonian for the N2 system using complete active sp verbose=True) We specify: - - The geometry previously created + - 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 From b3511656576bafbf5deb9fd4fd4fd48aa2772d5e Mon Sep 17 00:00:00 2001 From: marwafar Date: Mon, 10 Nov 2025 15:49:15 +0000 Subject: [PATCH 5/5] update examples_rst Signed-off-by: marwafar --- docs/sphinx/examples_rst/solvers/molecular_hamiltonians.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sphinx/examples_rst/solvers/molecular_hamiltonians.rst b/docs/sphinx/examples_rst/solvers/molecular_hamiltonians.rst index d4671496..b912f257 100644 --- a/docs/sphinx/examples_rst/solvers/molecular_hamiltonians.rst +++ b/docs/sphinx/examples_rst/solvers/molecular_hamiltonians.rst @@ -74,7 +74,7 @@ Now we take our same N2 molecule, but generate natural orbitals from second orde verbose=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. +This option is not yet available when using `UR=True`. When using `UR=True`, only UHF molecular orbitals are employed to generate the electronic Hamiltonian. CASSCF Orbitals +++++++++++++++