Merge branch 'main' into train_trt_decoder_docs

Author: bmhowe23

.gitignore

@@ -98,6 +98,9 @@ apps/
 # vim files
 *.tmp
 
+# Wheel files
+*.whl
+
 # Temporary build files for metapackages
 libs/*/python/metapackages/LICENSE
 libs/*/python/metapackages/NOTICE

README.md

@@ -1,29 +1,37 @@
 # Welcome to the CUDA-QX repository
 
-This repository contains a set of libraries that build on 
-NVIDIA CUDA-Q. These libraries enable the rapid development of hybrid quantum-classical 
-application code leveraging state-of-the-art CPUs, GPUs, and QPUs. 
+This repository contains a set of libraries that build on
+NVIDIA CUDA-Q. These libraries enable the rapid development of hybrid quantum-classical
+application code leveraging state-of-the-art CPUs, GPUs, and QPUs.
 
 ## Getting Started
-To learn more about how to work with the CUDA-QX libraries, please take a look at the 
-[CUDA-QX Documentation][cudaqx_docs]. The page contains detailed 
-[installation instructions][official_install] for officially released packages. 
+
+To learn more about how to work with the CUDA-QX libraries, please take a look at the
+[CUDA-QX Documentation][cudaqx_docs]. The page contains detailed
+[installation instructions][official_install] for officially released packages.
 
 [cudaqx_docs]: https://nvidia.github.io/cudaqx
 [official_install]: https://nvidia.github.io/cudaqx/quickstart/installation.html
 
 ## Contributing
 
 There are many ways in which you can get involved with CUDA-QX. If you are
-interested in developing quantum applications with the CUDA-QX libraries, 
-this repository is a great place to get started! For more information about 
-contributing to the CUDA-QX platform, please take a look at 
+interested in developing quantum applications with the CUDA-QX libraries,
+this repository is a great place to get started! For more information about
+contributing to the CUDA-QX platform, please take a look at
 [Contributing.md](./Contributing.md).
 
 ## License
 
 The code in this repository is licensed under [Apache License 2.0](./LICENSE).
 
+When distributed via PyPI, GHCR, or NGC, the binaries generated from this source
+code are also distributed under the Apache License 2.0; however, the
+`libcudaq-qec-nv-qldpc-decoder.so` library is closed source and is subject to
+the [NVIDIA Software License Agreement][github_qec_license]
+
+[github_qec_license]: https://github.com/NVIDIA/cudaqx/blob/main/libs/qec/LICENSE
+
 Contributing a pull request to this repository requires accepting the
 Contributor License Agreement (CLA) declaring that you have the right to, and
 actually do, grant us the rights to use your contribution. A CLA-bot will

docker/release/Dockerfile

@@ -27,6 +27,11 @@ ARG TARGETARCH
 
 USER root
 
+# Update the copyright notification:
+RUN echo -e "This container also includes CUDA-Q QEC and CUDA-Q Solvers.\n"\
+"Use of this container implies consent to the NVIDIA Software License agreement at\n"\
+"https://github.com/NVIDIA/cudaqx/blob/main/libs/qec/LICENSE\n" >> "$CUDA_QUANTUM_PATH/Copyright.txt"
+
 # Determine the appropriate zip file
 COPY installed_files-${TARGETARCH}.zip /tmp/
 

docs/sphinx/api/qec/cpp_api.rst

@@ -51,6 +51,11 @@ NVIDIA QLDPC Decoder
 
 .. include:: nv_qldpc_decoder_api.rst
 
+Sliding Window Decoder
+----------------------
+
+.. include:: sliding_window_api.rst
+
 Parity Check Matrix Utilities
 =============================
 

docs/sphinx/api/qec/nv_qldpc_decoder_api.rst

@@ -82,13 +82,14 @@
           (defaults to 1). Ignored unless `use_osd` is true.
         - `osd_order` (int): OSD postprocessor order (defaults to 0). Ref:
           `Decoding Across the Quantum LDPC Code Landscape <https://arxiv.org/pdf/2005.07016>`_
-            - For `osd_method=2` (Exhaustive), the number of possible
-              permutations searched after OSD-0 grows by 2^osd_order.
-            - For `osd_method=3` (Combination Sweep), this is the λ parameter. All
-              weight 1 permutations and the first λ bits worth of weight 2
-              permutations are searched after OSD-0. This is (syndrome_length -
-              block_size + λ * (λ - 1) / 2) additional permutations.
-            - For other `osd_method` values, this is ignored.
+
+          - For `osd_method=2` (Exhaustive), the number of possible
+            permutations searched after OSD-0 grows by 2^osd_order.
+          - For `osd_method=3` (Combination Sweep), this is the λ parameter. All
+            weight 1 permutations and the first λ bits worth of weight 2
+            permutations are searched after OSD-0. This is (syndrome_length -
+            block_size + λ * (λ - 1) / 2) additional permutations.
+          - For other `osd_method` values, this is ignored.
         - `bp_batch_size` (int): Number of syndromes that will be decoded in
           parallel for the BP decoder (defaults to 1)
         - `osd_batch_size` (int): Number of syndromes that will be decoded in
@@ -113,6 +114,8 @@
         - `scale_factor` (float): The scale factor to use for min-sum. Defaults to 1.0.
           When set to 0.0, the scale factor is dynamically computed based on the
           number of iterations. Introduced in 0.4.0.
+        - `proc_float` (string): The processing float type to use. Defaults to
+          "fp64". Valid values are "fp32" and "fp64". Introduced in 0.5.0.
         - `gamma0` (float): Memory strength parameter. Required for `bp_method=2`, and for
           `composition=1` (sequential relay). Introduced in 0.5.0.
         - `gamma_dist` (vector<float>): Gamma distribution interval [min, max] for disordered

docs/sphinx/api/qec/python_api.rst

@@ -39,6 +39,11 @@ NVIDIA QLDPC Decoder
 
 .. include:: nv_qldpc_decoder_api.rst
 
+Sliding Window Decoder
+----------------------
+
+.. include:: sliding_window_api.rst
+
 .. _tensor_network_decoder_api_python:
 
 Tensor Network Decoder

docs/sphinx/api/solvers/cpp_api.rst

@@ -6,6 +6,7 @@ CUDA-Q Solvers C++ API
 
 .. doxygenclass:: cudaq::solvers::spin_complement_gsd 
 .. doxygenclass:: cudaq::solvers::uccsd 
+.. doxygenclass:: cudaq::solvers::uccgsd 
 .. doxygenclass:: cudaq::solvers::qaoa_pool 
 
 .. doxygenfunction:: cudaq::solvers::get_operator_pool 
@@ -67,6 +68,8 @@ CUDA-Q Solvers C++ API
 .. doxygenfunction:: cudaq::solvers::stateprep::double_excitation
 .. doxygenfunction:: cudaq::solvers::stateprep::uccsd(cudaq::qview<>, const std::vector<double>&, std::size_t, std::size_t)
 .. doxygenfunction:: cudaq::solvers::stateprep::uccsd(cudaq::qview<>, const std::vector<double>&, std::size_t)
+.. doxygenfunction:: cudaq::solvers::stateprep::get_uccgsd_pauli_lists
+.. doxygenfunction:: cudaq::solvers::stateprep::uccgsd(cudaq::qview<>, const std::vector<double>&, const std::vector<std::vector<cudaq::pauli_word>>&, const std::vector<std::vector<double>>&)
 
 
 .. doxygenstruct:: cudaq::solvers::qaoa_result

docs/sphinx/api/solvers/python_api.rst

@@ -27,6 +27,8 @@ CUDA-Q Solvers Python API
 .. autofunction:: cudaq_solvers.stateprep.double_excitation
 .. autofunction:: cudaq_solvers.stateprep.get_num_uccsd_parameters
 .. autofunction:: cudaq_solvers.stateprep.get_uccsd_excitations    
+.. autofunction:: cudaq_solvers.stateprep.get_uccgsd_pauli_lists
+.. autofunction:: cudaq_solvers.stateprep.uccgsd
 
 .. autofunction:: cudaq_solvers.get_num_qaoa_parameters
 

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           |
 +---------------------+---------------+------------------+------------------------------------------+
 
@@ -495,12 +492,32 @@ Available Operator Pools
 
 CUDA-QX provides several pre-built operator pools for ADAPT-VQE:
 
-* **spin_complement_gsd**: Spin-complemented generalized singles and doubles
-* **uccsd**: UCCSD operators
+* **spin_complement_gsd**: Spin-complemented generalized singles and doubles.
+    This operator pool combines generalized excitations with enforced spin symmetry. It is 
+    more powerful than UCCSD because its generalized operators capture more electron correlation,
+     and it is more reliable than both UCCSD and UCCGSD because its spin-complemented 
+     construction prevents the unphysical "spin-symmetry breaking".
+* **uccsd**: UCCSD operators. 
+    The standard, chemically-inspired ansatz. Excitation Space 
+    is Restricted. It only includes single and double excitations 
+    where electrons move from a reference-occupied orbital (i) 
+    to a reference-virtual orbital (a), 
+    relative to the starting Hartree-Fock state. Excellent at capturing dynamic correlation 
+    (short-range, instantaneous electron interactions).
+* **uccgsd**: UCC generalized singles and doubles.
+    More expressive than UCCSD, as it includes all possible 
+    single and double excitations, regardless of their occupied/virtual status in the reference state.
+    Capable of capturing both dynamic and static (strong) correlation
+    but at the cost of increased circuit depth and parameter count.
 * **qaoa**: QAOA mixer excitation operators
-
+    It generates all possible single-qubit X and Y terms, along with all possible 
+    two-qubit interaction terms (XX, YY, XY, YX, XZ, ZX, YZ, ZY) across every pair of qubits. 
+    This pool offers a rich basis for constructing the mixer Hamiltonian for ADAPT-QAOA algorithms.
+    
 .. code-block:: python
 
+    import cudaq_solvers as solvers
+
     # Generate different operator pools
     gsd_ops = solvers.get_operator_pool(
         "spin_complement_gsd",
@@ -513,6 +530,60 @@ CUDA-QX provides several pre-built operator pools for ADAPT-VQE:
         num_electrons=molecule.n_electrons
     )
 
+    uccgsd_ops = solvers.get_operator_pool(
+        "uccgsd",
+        num_orbitals=molecule.n_orbitals
+    )
+
+Available Ansatz
+^^^^^^^^^^^^^^^^^^
+
+CUDA-QX provides several state preparations ansatz for VQE.
+
+* **uccsd**: UCCSD operators
+* **uccgsd**: UCC generalized singles and doubles
+
+.. code-block:: python
+
+    import cudaq_solvers as solvers
+
+    # Using UCCSD ansatz
+    geometry = [('H', (0., 0., 0.)), ('H', (0., 0., .7474))]
+    molecule = solvers.create_molecule(geometry, 'sto-3g', 0, 0, casci=True)
+
+    numQubits = molecule.n_orbitals * 2
+    numElectrons = molecule.n_electrons
+    spin = 0
+
+    @cudaq.kernel
+    def ansatz(thetas: list[float]):
+        q = cudaq.qvector(numQubits)
+        for i in range(numElectrons):
+            x(q[i])
+        solvers.stateprep.uccsd(q, thetas, numElectrons, spin)
+
+    
+    # Using UCCGSD ansatz
+    geometry = [('H', (0., 0., 0.)), ('H', (0., 0., .7474))]
+    molecule = solvers.create_molecule(geometry, 'sto-3g', 0, 0, casci=True)
+
+    numQubits = molecule.n_orbitals * 2
+    numElectrons = molecule.n_electrons
+
+    # Get grouped Pauli words and coefficients from UCCGSD pool
+    pauliWordsList, coefficientsList = solvers.stateprep.get_uccgsd_pauli_lists(
+        numQubits, only_singles=False, only_doubles=False)
+    
+    @cudaq.kernel
+    def ansatz(numQubits: int, numElectrons: int, thetas: list[float],
+               pauliWordsList: list[list[cudaq.pauli_word]],
+               coefficientsList: list[list[float]]):
+        q = cudaq.qvector(numQubits)
+        for i in range(numElectrons):
+            x(q[i])
+        solvers.stateprep.uccgsd(q, thetas, pauliWordsList, coefficientsList)
+
+
 Algorithm Parameters
 ^^^^^^^^^^^^^^^^^^^^^^
 

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)