Updating to new 3D visualizer molgallery3D and need to restart space to install

.cursorrules

@@ -0,0 +1,8 @@
+Write out code in a way that is easy to understand and follow.
+
+For each large task update make an update in @history.md file with the date and the changes made.
+New Entries should be added to the top of the file. This will provide a history of the changes made to the code.
+
+If things are unclear ask for clarification.
+
+If you are unsure about the best way to do something, propose a solution and ask for clarification.

.gitattributes

@@ -0,0 +1,35 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,79 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual Environment
+venv/
+env/
+ENV/
+.env
+.venv
+env.bak/
+venv.bak/
+
+# IDE specific files
+.idea/
+.vscode/
+*.swp
+*.swo
+.project
+.pydevproject
+.settings/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+*.ipynb_checkpoints/
+
+# Distribution / packaging
+.Python
+*.manifest
+*.spec
+
+# Logs and databases
+*.log
+*.sqlite
+*.db
+
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Testing
+.coverage
+.tox/
+.pytest_cache/
+htmlcov/
+.coverage.*
+coverage.xml
+*.cover
+
+# Documentation
+docs/_build/
+docs/generated/
+
+# Local development settings
+local_settings.py
+*.env 

README.md

@@ -0,0 +1,68 @@
+---
+title: Cuda Quantum Molecular Playground
+emoji: 📈
+colorFrom: pink
+colorTo: gray
+sdk: gradio
+sdk_version: 5.9.1
+app_file: app.py
+pinned: false
+license: apache-2.0
+suggested_hardware: t4-small
+short_description: Nvidia Cuda Quantum accelerator to demo to simulate bonds
+---
+
+# CUDA Quantum Molecular Playground
+
+An interactive web demo using NVIDIA's CUDA Quantum Library (CUDA-Q) for quantum computations. This project focuses on the Variational Quantum Eigensolver (VQE) algorithm to estimate molecular energy, providing an educational interface for quantum control and simulation.
+
+## Interface Features
+
+1. **Molecule Selection & Parameters**
+   - Choose from available molecules
+   - View detailed molecular parameters (formula, orbitals, charge, basis)
+   - Adjust bond length using an interactive scale factor slider
+
+2. **Simulation Controls**
+   - Run VQE simulations with real-time visualization
+   - View simulation results including:
+     - Final energy
+     - Parameter count
+     - Hamiltonian terms
+     - Optimization status
+     - Iteration count
+
+3. **Visualization**
+   - Interactive 3D molecular structure viewer
+   - Real-time energy convergence plots
+   - Detailed simulation results display
+
+## Installation
+
+```bash
+pip install -r requirements.txt
+```
+
+## Running the Demo
+
+1. Launch the application:
+```bash
+python app.py
+```
+
+2. Open your browser to the local URL displayed in the terminal (typically http://localhost:7860)
+
+## Key Technologies
+
+- **CUDA-Q**: Quantum computations and hardware acceleration
+- **OpenFermion**: Quantum simulations and electronic structure calculations
+- **PySCF**: Molecular Hamiltonian preparation and quantum chemistry simulations
+- **Gradio**: Interactive web interface
+- **Plotly**: Data visualization
+- **py3Dmol**: Molecular structure visualization
+
+## Hardware Requirements
+
+The demo automatically detects available hardware:
+- With NVIDIA GPU: Uses CUDA-Q's nvidia backend for acceleration
+- Without GPU: Falls back to CPU-based quantum simulation

app.py

@@ -0,0 +1,308 @@
+"""
+NVIDIA CUDA-Q VQE Demo
+=====================
+
+This Gradio application demonstrates the Variational Quantum Eigensolver (VQE) 
+algorithm using NVIDIA's CUDA Quantum library. The demo allows users to:
+
+1. Select from available molecules
+2. Adjust bond length parameters
+3. Run VQE simulations with real-time visualization
+4. View energy convergence and molecular structure in 3D
+
+Running the Demo
+---------------
+1. Ensure you have all dependencies installed:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+2. Launch the application:
+   ```bash
+   python app.py
+   ```
+
+3. Open your browser to the local URL displayed in the terminal
+   (typically http://localhost:7860)
+
+Using the Interface
+-----------------
+- Select a molecule from the dropdown
+- Adjust bond length using the slider (0.5 to 2.5 Å)
+- Click "Run VQE Simulation" or watch real-time updates as you adjust parameters
+- View results in three panels:
+  * Simulation Results: Shows final energy and optimization status
+  * VQE Convergence: Plots energy vs. iteration
+  * Molecule Visualization: 3D representation of the molecule
+
+GPU Acceleration
+--------------
+The app automatically detects if NVIDIA GPUs are available:
+- With GPU: Uses CUDA-Q's nvidia backend for acceleration
+- Without GPU: Falls back to CPU-based quantum simulation
+
+References
+---------
+- Installation: See Cuda-Q_install.md
+- VQE Implementation: See VQE_Example.md
+- Project Structure: See quantum-demo-blueprint.md
+"""
+
+import subprocess
+import sys
+import json
+import os
+
+# Load molecule definitions
+def load_molecules():
+    """Load molecule definitions from JSON file."""
+    try:
+        with open('molecules.json', 'r') as f:
+            return json.load(f)
+    except Exception as e:
+        print(f"Error loading molecules.json: {e}", file=sys.stderr)
+        return {}
+
+# Test if cudaq is already installed
+try:
+    import cudaq
+    print("CUDA-Q already installed, skipping dependency installation")
+except ImportError:
+    print("CUDA-Q not found, installing dependencies...")
+    # Run installation before any other imports
+    install_dependencies()
+
+# Now import the rest of the modules
+import gradio as gr
+import numpy as np
+from quantum_utils import run_vqe_simulation
+from visualization import plot_convergence, create_molecule_viewer, format_molecule_params
+import spaces
+
+# Add immediate logging
+print("Imported all modules successfully", file=sys.stderr, flush=True)
+
+def update_simulation(molecule_choice: str, scale_factor: float) -> tuple:
+    """
+    Run VQE simulation and update visualizations.
+    
+    Args:
+        molecule_choice: Selected molecule from available options
+        scale_factor: Factor to scale the molecule geometry by (1.0 = original size)
+    Returns:
+        Tuple of (energy text, convergence plot, molecule HTML)
+    """
+    print("UPDATE_SIMULATION CALLED", file=sys.stderr, flush=True)
+    try:
+        # Get molecule data
+        molecules = load_molecules()
+        if molecule_choice not in molecules:
+            raise ValueError(f"Unknown molecule: {molecule_choice}")
+        
+        molecule_data = molecules[molecule_choice]
+        print(f"Starting simulation with molecule: {molecule_choice}, scale: {scale_factor}", 
+              file=sys.stderr, flush=True)
+        
+        # Run VQE simulation
+        results = run_vqe_simulation(
+            molecule_data=molecule_data,
+            scale_factor=scale_factor
+        )
+        
+        print(f"VQE simulation completed with results: {results}", 
+              file=sys.stderr, flush=True)
+        
+        # Create plots
+        print("Creating convergence plot...", file=sys.stderr)
+        convergence_plot = plot_convergence(results)
+        print("Convergence plot created", file=sys.stderr)
+        
+        print("Creating molecule visualization...", file=sys.stderr)
+        molecule_html = create_molecule_viewer(molecule_choice, scale_factor)
+        print("Molecule visualization created", file=sys.stderr)
+        
+        # Format energy output
+        energy_text = f"""
+        Final Energy: {results['final_energy']:.6f} Hartree
+        Optimization Status: {'Success' if results['success'] else 'Failed'}
+        Message: {results['message']}
+        Number of Iterations: {len(results['history'])}
+        Scale Factor: {scale_factor:.2f}
+        """
+        
+        print("Returning results...", file=sys.stderr)
+        return energy_text, convergence_plot, molecule_html
+    
+    except Exception as e:
+        import traceback
+        error_msg = f"Error in simulation:\n{str(e)}\n\nTraceback:\n{traceback.format_exc()}"
+        print(error_msg, file=sys.stderr)  # This will show in the server logs
+        return error_msg, None, None
+
+def create_interface():
+    """Create the Gradio interface for the VQE demo."""
+    
+    # Load available molecules
+    molecules = load_molecules()
+    if not molecules:
+        raise ValueError("No molecules found in molecules.json")
+    
+    with gr.Blocks(title="CUDA-Q VQE Demo") as demo:
+        gr.Markdown("# NVIDIA CUDA-Q VQE Demo")
+        gr.Markdown("""
+        This demo shows a Variational Quantum Eigensolver (VQE) simulation
+        using NVIDIA's CUDA Quantum library.
+        """)
+        
+        state = gr.State({})  # Store current molecule data
+        
+        with gr.Row():
+            with gr.Column(scale=1):
+                # Molecule selection controls
+                molecule_choice = gr.Dropdown(
+                    choices=list(molecules.keys()),
+                    value=list(molecules.keys())[0],
+                    label="Select Molecule"
+                )
+                
+                # Get scale range from selected molecule
+                default_molecule = molecules[list(molecules.keys())[0]]
+                scale_factor = gr.Slider(
+                    minimum=default_molecule['scale_range']['min'],
+                    maximum=default_molecule['scale_range']['max'],
+                    value=default_molecule['default_scale'],
+                    step=default_molecule['scale_range']['step'],
+                    label="Scale Factor (1.0 = original size)",
+                    interactive=True
+                )
+                
+                run_button = gr.Button("Run VQE Simulation")
+                
+            with gr.Column(scale=1):
+                # Molecule parameters display
+                params_display = gr.HTML(
+                    label="Molecule Parameters",
+                    value=format_molecule_params(default_molecule)
+                )
+        
+        # Simulation results box below controls
+        with gr.Row():
+            simulation_results = gr.HTML(
+                label="Simulation Results",
+                value="<div style='padding: 10px; background-color: #f5f5f5; border-radius: 5px;'>" +
+                      "Click 'Run VQE Simulation' to start the calculation.</div>"
+            )
+        
+        # Plots and visualization
+        with gr.Row():
+            convergence_plot = gr.Plot(
+                label="VQE Convergence",
+                show_label=True
+            )
+            # Create MolGallery3D component
+            molecule_viz = MolGallery3D(
+                columns=1,
+                height=400,
+                label="3D Molecule Viewer",
+                automatic_rotation=True
+            )
+        
+        def update_molecule_info(molecule_choice):
+            """Update description and scale range when molecule is selected."""
+            try:
+                mol_data = molecules[molecule_choice]
+                
+                # Format parameters display
+                params_html = format_molecule_params(mol_data)
+                
+                # Get scale range values with defaults
+                min_scale = mol_data.get('scale_range', {}).get('min', 0.1)
+                max_scale = mol_data.get('scale_range', {}).get('max', 3.0)
+                default_scale = mol_data.get('default_scale', 1.0)
+                step_size = mol_data.get('scale_range', {}).get('step', 0.05)
+                
+                # Create molecule visualization
+                mol_list = create_molecule_viewer(molecule_choice, default_scale)
+                if mol_list is None:
+                    mol_list = []  # Empty list if molecule creation failed
+                
+                return [
+                    params_html,  # Update params display
+                    gr.update(    # Update slider
+                        minimum=min_scale,
+                        maximum=max_scale,
+                        value=default_scale,
+                        step=step_size
+                    ),
+                    mol_list  # Update 3D view
+                ]
+            except Exception as e:
+                print(f"Error updating molecule info: {e}", file=sys.stderr)
+                return [
+                    "<div>Error loading molecule parameters</div>",
+                    gr.update(
+                        minimum=0.1,
+                        maximum=3.0,
+                        value=1.0,
+                        step=0.05
+                    ),
+                    []  # Empty list for molecule visualization
+                ]
+        
+        def update_simulation_with_details(molecule_choice: str, scale_factor: float) -> tuple:
+            """Enhanced simulation update with parameter count and Hamiltonian terms."""
+            try:
+                # Get molecule data
+                molecule_data = molecules[molecule_choice]
+                
+                # Run VQE simulation
+                results = run_vqe_simulation(
+                    molecule_data=molecule_data,
+                    scale_factor=scale_factor
+                )
+                
+                # Create plots
+                convergence_plot = plot_convergence(results)
+                
+                # Format simulation results with additional details
+                simulation_html = f"""
+                <div style='padding: 10px; background-color: #f5f5f5; border-radius: 5px;'>
+                    <h3>Simulation Results:</h3>
+                    <ul style='list-style-type: none; padding-left: 0;'>
+                        <li><b>Final Energy:</b> {results['final_energy']:.6f} Hartree</li>
+                        <li><b>Parameter Count:</b> {results.get('parameter_count', 'N/A')}</li>
+                        <li><b>Hamiltonian Terms:</b> {results.get('hamiltonian_terms', 'N/A')}</li>
+                        <li><b>Optimization Status:</b> {'Success' if results.get('success', False) else 'Failed'}</li>
+                        <li><b>Iterations:</b> {len(results['history'])}</li>
+                        <li><b>Scale Factor:</b> {scale_factor:.2f}</li>
+                    </ul>
+                    <p><i>{results.get('message', '')}</i></p>
+                </div>
+                """
+                
+                return simulation_html, convergence_plot
+            
+            except Exception as e:
+                import traceback
+                error_msg = f"<div style='color: red;'>Error in simulation:<br>{str(e)}</div>"
+                return error_msg, None
+        
+        # Update parameters and 3D view when molecule changes
+        molecule_choice.change(
+            fn=update_molecule_info,
+            inputs=[molecule_choice],
+            outputs=[params_display, scale_factor, molecule_viz]
+        )
+        
+        # Run simulation when button is clicked
+        run_button.click(
+            fn=update_simulation_with_details,
+            inputs=[molecule_choice, scale_factor],
+            outputs=[simulation_results, convergence_plot]
+        )
+    
+    return demo
+
+if __name__ == "__main__":
+    demo = create_interface()
+    demo.launch(share=False) 

docref/Example_cudaq_logical_aim_agk.py

@@ -0,0 +1,712 @@
+# -*- coding: utf-8 -*-
+"""Copy of cudaq_logical_aim_agk.ipynb
+
+Automatically generated by Colab.
+
+Original file is located at
+    https://colab.research.google.com/drive/1Jsf9Le8eoCJgddNzYvfQO4E7g--N-DyC
+
+# AIM: Logical Anderson Impurity Model on Sqale using CUDA-Q
+
+[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Infleqtion/client-superstaq/blob/main/docs/source/apps/cudaq_logical_aim.ipynb) [![Launch Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/Infleqtion/client-superstaq/HEAD?labpath=docs/source/apps/cudaq_logical_aim.ipynb)
+
+Ground state quantum chemistry—computing total energies of molecular configurations to within chemical accuracy—is perhaps the most highly-touted industrial application of fault-tolerant quantum computers. Strongly correlated materials, for example, are particularly interesting, and tools like dynamical mean-field theory (DMFT) allow one to account for the effect of their strong, localized electronic correlations. These DMFT models help predict material properties by approximating the system as a single site impurity inside a “bath” that encompasses the rest of the system. Simulating such dynamics can be a tough task using classical methods, but can be done efficiently on a quantum computer via quantum simulation.
+
+In this notebook, we showcase a workflow for preparing the ground state of the minimal single-impurity Anderson model (SIAM) using the Hamiltonian Variational Ansatz for a range of realistic parameters. As a first step towards running DMFT on a fault-tolerant quantum computer, we will use logical qubits encoded in the `[[4, 2, 2]]` code. Using this workflow, we will obtain the ground state energy estimates via noisy simulation, and then also execute the corresponding optimized circuits on Infleqtion's gate-based neutral-atom quantum computer, making the benefits of logical qubits apparent. More details can be found in our [paper](https://arxiv.org/abs/2412.07670).
+
+[agk] - 2024-12-23 Reference chats to understand AIM model - https://gemini.google.com/app/fce0538c8dc2b6ac and https://x.com/i/grok/share/AV9UkWb4LNtfqm1HfLPEQ78HG
+
+This demo notebook uses CUDA-Q (`cudaq`) and a CUDA-QX library, `cudaq-solvers`; let us first begin by importing (and installing as needed) these packages:
+"""
+
+# Commented out IPython magic to ensure Python compatibility.
+try:
+    import cudaq_solvers as solvers
+    import cudaq
+    import matplotlib.pyplot as plt
+except ImportError:
+    print("Installing required packages...")
+#     %pip install --quiet 'cudaq-solvers' 'matplotlib'
+    print("Installed `cudaq`, `cudaq-solvers`, and `matplotlib` packages.")
+    print("You may need to restart the kernel to import newly installed packages.")
+    import cudaq_solvers as solvers
+    import cudaq
+    import matplotlib.pyplot as plt
+
+from collections.abc import Mapping, Sequence
+import numpy as np
+from scipy.optimize import minimize
+import os
+
+from IPython.core.display import HTML
+print("restarting Kernel")
+HTML("<script>Jupyter.notebook.kernel.restart()</script>")
+print("Kernel restarted. Probably, I don't know... I'm not magic")
+
+"""## Performing logical Variational Quantum Eigensolver (VQE) with CUDA-QX
+
+To prepare our ground state quantum Anderson impurity model circuits (referred to as AIM circuits in this notebook for short), we use VQE to train an ansatz to minimize a Hamiltonian and obtain optimal angles that can be used to set the AIM circuits. As described in our [paper](https://arxiv.org/abs/2412.07670), the associated restricted Hamiltonian for our SIAM can be reduced to,
+$$  
+\begin{equation}
+H_{(U, V)} = U (Z_0 Z_2 - 1) / 4 + V (X_0 + X_2),
+\end{equation}
+$$
+where $U$ is the Coulomb interaction and $V$ the hybridization strength. In this notebook workflow, we will optimize over a 2-dimensional grid of Hamiltonian parameter values, namely $U\in \{1, 5, 9\}$ and $V\in \{-9, -1, 7\}$ (with all values assumed to be in units of eV), to ensure that the ansatz is generally trainable and expressive, and obtain 9 different circuit layers identified by the key $(U, V)$. We will simulate the VQE on GPU (or optionally on CPU if you do not have GPU access), enabled by CUDA-Q, in the absence of noise:
+"""
+
+if cudaq.num_available_gpus() == 0:
+    cudaq.set_target("qpp-cpu", option="fp64")
+
+    print("Using CPU no Cuda gpu found")
+else:
+    cudaq.set_target("nvidia", option="fp64")
+    print("Using GPU")
+
+"""This workflow can be easily defined in CUDA-Q as shown in the cell below, using the CUDA-QX Solvers library (which accelerates quantum algorithms like the VQE):"""
+
+def ansatz(n_qubits: int) -> cudaq.Kernel:
+    # Create a CUDA-Q parameterized kernel
+    paramterized_ansatz, variational_angles = cudaq.make_kernel(list)
+    qubits = paramterized_ansatz.qalloc(n_qubits)
+
+    # Using |+> as the initial state:
+    paramterized_ansatz.h(qubits[0])
+    paramterized_ansatz.cx(qubits[0], qubits[1])
+
+    paramterized_ansatz.rx(variational_angles[0], qubits[0])
+    paramterized_ansatz.cx(qubits[0], qubits[1])
+    paramterized_ansatz.rz(variational_angles[1], qubits[1])
+    paramterized_ansatz.cx(qubits[0], qubits[1])
+    return paramterized_ansatz
+
+
+def run_logical_vqe(cudaq_hamiltonian: cudaq.SpinOperator) -> tuple[float, list[float]]:
+    # Set seed for easier reproduction
+    np.random.seed(42)
+
+    # Initial angles for the optimizer
+    init_angles = np.random.random(2) * 1e-1
+
+    # Obtain CUDA-Q Ansatz
+    num_qubits = cudaq_hamiltonian.get_qubit_count()
+    variational_kernel = ansatz(num_qubits)
+
+    # Perform VQE optimization
+    energy, params, _ = solvers.vqe(
+        variational_kernel,
+        cudaq_hamiltonian,
+        init_angles,
+        optimizer=minimize,
+        method="SLSQP",
+        tol=1e-10,
+    )
+    return energy, params
+
+"""## Constructing circuits in the `[[4,2,2]]` encoding
+
+The `[[4,2,2]]` code is a quantum error detection code that uses four physical qubits to encode two logical qubits. In this notebook, we will construct two variants of quantum circuits: physical (bare, unencoded) and logical (encoded). These circuits will be informed by the Hamiltonian Variational Ansatz described earlier. To measure all the terms in our Hamiltonian, we will measure the data qubits in both the $Z$- and $X$-basis, as allowed by the `[[4,2,2]]` logical gateset. Full details on the circuit constructions are outlined in our [paper](https://arxiv.org/abs/2412.07670).
+
+Below, we create functions to build our CUDA-Q AIM circuits, both physical and logical versions. As we consider noisy simulation in this notebook, we will include some noisy gates. Here, for simplicity, we will just register a custom identity gate -- to be later used as a noisy operation to model readout error:
+"""
+
+cudaq.register_operation("meas_id", np.identity(2))
+
+def aim_physical_circuit(
+    angles: list[float], basis: str, *, ignore_meas_id: bool = False
+) -> cudaq.Kernel:
+    kernel = cudaq.make_kernel()
+    qubits = kernel.qalloc(2)
+
+    # Bell state prep
+    kernel.h(qubits[0])
+    kernel.cx(qubits[0], qubits[1])
+
+    # Rx Gate
+    kernel.rx(angles[0], qubits[0])
+
+    # ZZ rotation
+    kernel.cx(qubits[0], qubits[1])
+    kernel.rz(angles[1], qubits[1])
+    kernel.cx(qubits[0], qubits[1])
+
+    if basis == "z_basis":
+        if not ignore_meas_id:
+            kernel.for_loop(
+                start=0, stop=2, function=lambda q_idx: getattr(kernel, "meas_id")(qubits[q_idx])
+            )
+        kernel.mz(qubits)
+    elif basis == "x_basis":
+        kernel.h(qubits)
+        if not ignore_meas_id:
+            kernel.for_loop(
+                start=0, stop=2, function=lambda q_idx: getattr(kernel, "meas_id")(qubits[q_idx])
+            )
+        kernel.mz(qubits)
+    else:
+        raise ValueError("Unsupported basis provided:", basis)
+    return kernel
+
+def aim_logical_circuit(
+    angles: list[float], basis: str, *, ignore_meas_id: bool = False
+) -> cudaq.Kernel:
+    kernel = cudaq.make_kernel()
+    qubits = kernel.qalloc(6)
+
+    kernel.for_loop(start=0, stop=3, function=lambda idx: kernel.h(qubits[idx]))
+    kernel.cx(qubits[1], qubits[4])
+    kernel.cx(qubits[2], qubits[3])
+    kernel.cx(qubits[0], qubits[1])
+    kernel.cx(qubits[0], qubits[3])
+
+    # Rx teleportation
+    kernel.rx(angles[0], qubits[0])
+
+    kernel.cx(qubits[0], qubits[1])
+    kernel.cx(qubits[0], qubits[3])
+    kernel.h(qubits[0])
+
+    if basis == "z_basis":
+        if not ignore_meas_id:
+            kernel.for_loop(
+                start=0, stop=5, function=lambda idx: getattr(kernel, "meas_id")(qubits[idx])
+            )
+        kernel.mz(qubits)
+    elif basis == "x_basis":
+        # ZZ rotation and teleportation
+        kernel.cx(qubits[3], qubits[5])
+        kernel.cx(qubits[2], qubits[5])
+        kernel.rz(angles[1], qubits[5])
+        kernel.cx(qubits[1], qubits[5])
+        kernel.cx(qubits[4], qubits[5])
+        kernel.for_loop(start=1, stop=5, function=lambda idx: kernel.h(qubits[idx]))
+        if not ignore_meas_id:
+            kernel.for_loop(
+                start=0, stop=6, function=lambda idx: getattr(kernel, "meas_id")(qubits[idx])
+            )
+        kernel.mz(qubits)
+    else:
+        raise ValueError("Unsupported basis provided:", basis)
+    return kernel
+
+"""With the circuit definitions above, we can now define a function that automatically runs the VQE and constructs a dictionary containing all the AIM circuits we want to submit to hardware (or noisily simulate):"""
+
+def generate_circuit_set(ignore_meas_id: bool = False) -> object:
+    u_vals = [1, 5, 9]
+    v_vals = [-9, -1, 7]
+    circuit_dict = {}
+    for u in u_vals:
+        for v in v_vals:
+            qubit_hamiltonian = (
+                0.25 * u * cudaq.spin.z(0) * cudaq.spin.z(1)
+                - 0.25 * u
+                + v * cudaq.spin.x(0)
+                + v * cudaq.spin.x(1)
+            )
+            _, opt_params = run_logical_vqe(qubit_hamiltonian)
+            angles = [float(angle) for angle in opt_params]
+            print(f"Computed optimal angles={angles} for U={u}, V={v}")
+
+            tmp_physical_dict = {}
+            tmp_logical_dict = {}
+            for basis in ("z_basis", "x_basis"):
+                tmp_physical_dict[basis] = aim_physical_circuit(
+                    angles, basis, ignore_meas_id=ignore_meas_id
+                )
+                tmp_logical_dict[basis] = aim_logical_circuit(
+                    angles, basis, ignore_meas_id=ignore_meas_id
+                )
+
+            circuit_dict[f"{u}:{v}"] = {
+                "physical": tmp_physical_dict,
+                "logical": tmp_logical_dict,
+            }
+    print("\nFinished building optimized circuits!")
+    return circuit_dict
+
+sim_circuit_dict = generate_circuit_set()
+circuit_layers = sim_circuit_dict.keys()
+
+"""## Setting up submission and decoding workflow
+
+In this section, we define various helper functions that will play a role in generating the associated energies of the AIM circuits based on the circuit samples (in the different bases), as well as decode the logical circuits with post-selection informed by the `[[4,2,2]]` code:
+"""
+
+def _num_qubits(counts: Mapping[str, float]) -> int:
+    for key in counts:
+        if key.isdecimal():
+            return len(key)
+    return 0
+
+
+def process_counts(
+    counts: Mapping[str, float],
+    data_qubits: Sequence[int],
+    flag_qubits: Sequence[int] = (),
+) -> dict[str, float]:
+    new_data: dict[str, float] = {}
+    for key, val in counts.items():
+        if not all(key[i] == "0" for i in flag_qubits):
+            continue
+
+        new_key = "".join(key[i] for i in data_qubits)
+
+        if not set("01").issuperset(new_key):
+            continue
+
+        new_data.setdefault(new_key, 0)
+        new_data[new_key] += val
+
+    return new_data
+
+
+def decode(counts: Mapping[str, float]) -> dict[str, float]:
+    """Decode physical counts into logical counts. Should be called after `process_counts`."""
+
+    if not counts:
+        return {}
+
+    num_qubits = _num_qubits(counts)
+    assert num_qubits % 4 == 0
+
+    physical_to_logical = {
+        "0000": "00",
+        "1111": "00",
+        "0011": "01",
+        "1100": "01",
+        "0101": "10",
+        "1010": "10",
+        "0110": "11",
+        "1001": "11",
+    }
+
+    new_data: dict[str, float] = {}
+    for key, val in counts.items():
+        physical_keys = [key[i : i + 4] for i in range(0, num_qubits, 4)]
+        logical_keys = [physical_to_logical.get(physical_key) for physical_key in physical_keys]
+        if None not in logical_keys:
+            new_key = "".join(logical_keys)
+            new_data.setdefault(new_key, 0)
+            new_data[new_key] += val
+
+    return new_data
+
+
+def ev_x(counts: Mapping[str, float]) -> float:
+    ev = 0.0
+
+    for k, val in counts.items():
+        ev += val * ((-1) ** int(k[0]) + (-1) ** int(k[1]))
+
+    total = sum(counts.values())
+    ev /= total
+    return ev
+
+
+def ev_xx(counts: Mapping[str, float]) -> float:
+    ev = 0.0
+
+    for k, val in counts.items():
+        ev += val * (-1) ** k.count("1")
+
+    total = sum(counts.values())
+    ev /= total
+    return ev
+
+
+def ev_zz(counts: Mapping[str, float]) -> float:
+    ev = 0.0
+
+    for k, val in counts.items():
+        ev += val * (-1) ** k.count("1")
+
+    total = sum(counts.values())
+    ev /= total
+    return ev
+
+
+def aim_logical_energies(
+    data_ordering: object, counts_list: Sequence[dict[str, float]]
+) -> tuple[dict[tuple[int, int], float], dict[tuple[int, int], float]]:
+    counts_data = {
+        data_ordering[i]: decode(
+            process_counts(
+                counts,
+                data_qubits=[1, 2, 3, 4],
+                flag_qubits=[0, 5],
+            )
+        )
+        for i, counts in enumerate(counts_list)
+    }
+    return _aim_energies(counts_data)
+
+
+def aim_physical_energies(
+    data_ordering: object, counts_list: Sequence[dict[str, float]]
+) -> tuple[dict[tuple[int, int], float], dict[tuple[int, int], float]]:
+    counts_data = {
+        data_ordering[i]: process_counts(
+            counts,
+            data_qubits=[0, 1],
+        )
+        for i, counts in enumerate(counts_list)
+    }
+    return _aim_energies(counts_data)
+
+
+def _aim_energies(
+    counts_data: Mapping[tuple[int, int, str], dict[str, float]],
+) -> tuple[dict[tuple[int, int], float], dict[tuple[int, int], float]]:
+    evxs: dict[tuple[int, int], float] = {}
+    evxxs: dict[tuple[int, int], float] = {}
+    evzzs: dict[tuple[int, int], float] = {}
+    totals: dict[tuple[int, int], float] = {}
+
+    for key, counts in counts_data.items():
+        h_params, basis = key
+        key_a, key_b = h_params.split(":")
+        u, v = int(key_a), int(key_b)
+        if basis.startswith("x"):
+            evxs[u, v] = ev_x(counts)
+            evxxs[u, v] = ev_xx(counts)
+        else:
+            evzzs[u, v] = ev_zz(counts)
+
+        totals.setdefault((u, v), 0)
+        totals[u, v] += sum(counts.values())
+
+    energies = {}
+    uncertainties = {}
+    for u, v in evxs.keys() & evzzs.keys():
+        string_key = f"{u}:{v}"
+        energies[string_key] = u * (evzzs[u, v] - 1) / 4 + v * evxs[u, v]
+
+        uncertainty_xx = 2 * v**2 * (1 + evxxs[u, v]) - u * v * evxs[u, v] / 2
+        uncertainty_zz = u**2 * (1 - evzzs[u, v]) / 2
+
+        uncertainties[string_key] = np.sqrt(
+            (uncertainty_zz + uncertainty_xx - energies[string_key] ** 2) / (totals[u, v] / 2)
+        )
+
+    return energies, uncertainties
+
+
+def _get_energy_diff(
+    bf_energies: dict[str, float],
+    physical_energies: dict[str, float],
+    logical_energies: dict[str, float],
+) -> tuple[list[float], list[float]]:
+    physical_energy_diff = []
+    logical_energy_diff = []
+
+    # Data ordering following `bf_energies` keys
+    for layer in bf_energies.keys():
+        physical_sim_energy = physical_energies[layer]
+        logical_sim_energy = logical_energies[layer]
+        true_energy = bf_energies[layer]
+        u, v = layer.split(":")
+        print(f"Layer=({u}, {v}) has brute-force energy of: {true_energy}")
+        print(f"Physical circuit of layer=({u}, {v}) got an energy of: {physical_sim_energy}")
+        print(f"Logical circuit of layer=({u}, {v}) got an energy of: {logical_sim_energy}")
+        print("-" * 72)
+
+        if logical_sim_energy < physical_sim_energy:
+            print("Logical circuit achieved the lower energy!")
+        else:
+            print("Physical circuit achieved the lower energy")
+        print("-" * 72, "\n")
+
+        physical_energy_diff.append(
+            -1 * (true_energy - physical_sim_energy)
+        )  # Multiply by -1 since negative energies
+        logical_energy_diff.append(-1 * (true_energy - logical_sim_energy))
+    return physical_energy_diff, logical_energy_diff
+
+def submit_aim_circuits(
+    circuit_dict: object,
+    *,
+    folder_path: str = "future_aim_results",
+    shots_count: int = 1000,
+    noise_model: cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.NoiseModel | None = None,
+    run_async: bool = False,
+) -> dict[str, list[dict[str, int]]] | None:
+    if run_async:
+        os.makedirs(folder_path, exist_ok=True)
+    else:
+        aim_results = {"physical": [], "logical": []}
+
+    for layer in circuit_dict.keys():
+        if run_async:
+            print(f"Posting circuits associated with layer=('{layer}')")
+        else:
+            print(f"Running circuits associated with layer=('{layer}')")
+
+        for basis in ("z_basis", "x_basis"):
+            if run_async:
+                u, v = layer.split(":")
+
+                tmp_physical_results = cudaq.sample_async(
+                    circuit_dict[layer]["physical"][basis], shots_count=shots_count
+                )
+                file = open(f"{folder_path}/physical_{basis}_job_u={u}_v={v}_result.txt", "w")
+                file.write(str(tmp_physical_results))
+                file.close()
+
+                tmp_logical_results = cudaq.sample_async(
+                    circuit_dict[layer]["logical"][basis], shots_count=shots_count
+                )
+                file = open(f"{folder_path}/logical_{basis}_job_u={u}_v={v}_result.txt", "w")
+                file.write(str(tmp_logical_results))
+                file.close()
+            else:
+                tmp_physical_results = cudaq.sample(
+                    circuit_dict[layer]["physical"][basis],
+                    shots_count=shots_count,
+                    noise_model=noise_model,
+                )
+                tmp_logical_results = cudaq.sample(
+                    circuit_dict[layer]["logical"][basis],
+                    shots_count=shots_count,
+                    noise_model=noise_model,
+                )
+                aim_results["physical"].append({k: v for k, v in tmp_physical_results.items()})
+                aim_results["logical"].append({k: v for k, v in tmp_logical_results.items()})
+    if not run_async:
+        print("\nCompleted all circuit sampling!")
+        return aim_results
+    else:
+        print("\nAll circuits submitted for async sampling!")
+
+def _get_async_results(
+    layers: object, *, folder_path: str = "future_aim_results"
+) -> dict[str, list[dict[str, int]]]:
+    aim_results = {"physical": [], "logical": []}
+    for layer in layers:
+        print(f"Retrieving all circuits counts associated with layer=('{layer}')")
+        u, v = layer.split(":")
+        for basis in ("z_basis", "x_basis"):
+            file = open(f"{folder_path}/physical_{basis}_job_u={u}_v={v}_result.txt", "r")
+            tmp_physical_results = cudaq.AsyncSampleResult(str(file.read()))
+            physical_counts = tmp_physical_results.get()
+
+            file = open(f"{folder_path}/logical_{basis}_job_u={u}_v={v}_result.txt", "r")
+            tmp_logical_results = cudaq.AsyncSampleResult(str(file.read()))
+            logical_counts = tmp_logical_results.get()
+
+            aim_results["physical"].append({k: v for k, v in physical_counts.items()})
+            aim_results["logical"].append({k: v for k, v in logical_counts.items()})
+
+    print("\nObtained all circuit samples!")
+    return aim_results
+
+"""## Running a CUDA-Q noisy simulation
+
+In this section, we will first explore the performance of the physical and logical circuits under the influence of a device noise model. This will help us predict experimental results, as well as understand the dominant error sources at play. Such a simulation can be achieved via CUDA-Q's density matrix simulator:
+"""
+
+cudaq.reset_target()
+cudaq.set_target("density-matrix-cpu")
+
+
+
+def get_device_noise(
+    depolar_prob_1q: float,
+    depolar_prob_2q: float,
+    *,
+    readout_error_prob: float | None = None,
+    custom_gates: list[str] | None = None,
+) -> cudaq.mlir._mlir_libs._quakeDialects.cudaq_runtime.NoiseModel:
+    noise = cudaq.NoiseModel()
+    depolar_noise = cudaq.DepolarizationChannel(depolar_prob_1q)
+
+    noisy_ops = ["z", "s", "x", "h", "rx", "rz"]
+    for op in noisy_ops:
+        noise.add_all_qubit_channel(op, depolar_noise)
+
+    if custom_gates:
+        custom_depolar_channel = cudaq.DepolarizationChannel(depolar_prob_1q)
+        for op in custom_gates:
+            noise.add_all_qubit_channel(op, custom_depolar_channel)
+
+    # Two qubit depolarization error
+    p_0 = 1 - depolar_prob_2q
+    p_1 = np.sqrt((1 - p_0**2) / 3)
+
+    k0 = np.array(
+        [[p_0, 0.0, 0.0, 0.0], [0.0, p_0, 0.0, 0.0], [0.0, 0.0, p_0, 0.0], [0.0, 0.0, 0.0, p_0]],
+        dtype=np.complex128,
+    )
+    k1 = np.array(
+        [[0.0, 0.0, p_1, 0.0], [0.0, 0.0, 0.0, p_1], [p_1, 0.0, 0.0, 0.0], [0.0, p_1, 0.0, 0.0]],
+        dtype=np.complex128,
+    )
+    k2 = np.array(
+        [
+            [0.0, 0.0, -1j * p_1, 0.0],
+            [0.0, 0.0, 0.0, -1j * p_1],
+            [1j * p_1, 0.0, 0.0, 0.0],
+            [0.0, 1j * p_1, 0.0, 0.0],
+        ],
+        dtype=np.complex128,
+    )
+    k3 = np.array(
+        [[p_1, 0.0, 0.0, 0.0], [0.0, p_1, 0.0, 0.0], [0.0, 0.0, -p_1, 0.0], [0.0, 0.0, 0.0, -p_1]],
+        dtype=np.complex128,
+    )
+    kraus_channel = cudaq.KrausChannel([k0, k1, k2, k3])
+
+    noise.add_all_qubit_channel("cz", kraus_channel)
+    noise.add_all_qubit_channel("cx", kraus_channel)
+
+    if readout_error_prob is not None:
+        # Readout error modeled with a Bit flip channel on identity before measurement
+        bit_flip = cudaq.BitFlipChannel(readout_error_prob)
+        noise.add_all_qubit_channel("meas_id", bit_flip)
+    return noise
+
+"""Finally, with our example noise model defined above, we can synchronously & noisily sample all of our AIM circuits by passing `noise_model=cudaq_noise_model` to the workflow containing function `submit_aim_circuits()`:"""
+
+# Example parameters that can model execution on hardware at the high, simulation, level:
+# Take single-qubit gate depolarization rate: ~0.2% or better (fidelity ≥99.8%)
+# Take two-qubit gate depolarization rate: ~1–2% (fidelity ~98–99%)
+cudaq_noise_model = get_device_noise(0.002, 0.02, readout_error_prob=0.02)
+
+
+
+aim_sim_data = submit_aim_circuits(sim_circuit_dict, noise_model=cudaq_noise_model)
+
+data_ordering = []
+for key in circuit_layers:
+    for basis in ("z_basis", "x_basis"):
+        data_ordering.append((key, basis))
+
+sim_physical_energies, sim_physical_uncertainties = aim_physical_energies(
+    data_ordering, aim_sim_data["physical"]
+)
+
+sim_logical_energies, sim_logical_uncertainties = aim_logical_energies(
+    data_ordering, aim_sim_data["logical"]
+)
+
+"""To analyze our simulated energy results in the above cells, we will compare them to the brute-force computed exact ground state energies for the AIM Hamiltonian. For simplicity, these are already stored in the dictionary `bf_energies` below:"""
+
+bf_energies = {
+    "1:-9": -18.251736027394713,
+    "1:-1": -2.265564437074638,
+    "1:7": -14.252231964940428,
+    "5:-9": -19.293350575766127,
+    "5:-1": -3.608495283014149,
+    "5:7": -15.305692796870582,
+    "9:-9": -20.39007993367173,
+    "9:-1": -5.260398644698076,
+    "9:7": -16.429650912487233,
+}
+
+"""With the above metric, we can assess the performance of the logical circuits against the physical circuits by considering how far away the respective energies are from the brute-force expected energies. The cell below computes these energy deviations:"""
+
+sim_physical_energy_diff, sim_logical_energy_diff = _get_energy_diff(
+    bf_energies, sim_physical_energies, sim_logical_energies
+)
+
+"""Both physical and logical circuits were subject to the same noise model, but the `[[4,2,2]]` provides additional information that can help overcome some errors. Visualizing the computed energy differences from the above the cell, our noisy simulation provides a preview of the benefits logical qubits can offer:"""
+
+# Diagnostic block because next code block was getting stuck and throwing many errors
+print("=== Creating layer labels ===")
+layer_labels = [(int(key.split(":")[0]), int(key.split(":")[1])) for key in bf_energies.keys()]
+print("=== ge nerating strings ===")
+plot_labels = [str(item) for item in layer_labels]
+
+print("=== Variable Type Check ===")
+print(f"Type of sim_physical_energy_diff: {type(sim_physical_energy_diff)}")
+print(f"Type of sim_physical_uncertainties: {type(sim_physical_uncertainties)}")
+
+print("\n=== Values Preview ===")
+print(f"bf_energies keys: {list(bf_energies.keys())[:5]}...") # First 5 keys
+print(f"layer_labels: {layer_labels[:5]}...") # First 5 labels
+
+print("\n=== Shape/Length Check ===")
+ print(f"Length of plot_labels: {len(plot_labels)}")
+
+print(f"Length of sim_physical_energy_diff: {len(sim_physical_energy_diff) if hasattr(sim_physical_energy_diff, 'len') else 'N/A'}")
+
+print(f"Number of uncertainties: {len(sim_physical_uncertainties.values()) if hasattr(sim_physical_uncertainties.values(), 'len') else 'N/A'}")
+sim_physical_energy_diff
+
+print("=== Examining sim_physical_uncertainties ===")
+print(f"Type: {type(sim_physical_uncertainties)}")
+print("\nFirst few key-value pairs:")
+for i, (key, value) in enumerate(sim_physical_uncertainties.items()):
+    if i < 5:  # Show first 5 items
+        print(f"{key}: {value}")
+    else:
+        break
+
+print("\n=== Examining sim_physical_energy_diff ===")
+print(f"Type: {type(sim_physical_energy_diff)}")
+if hasattr(sim_physical_energy_diff, '__iter__'):
+    print("First few values:")
+    try:
+        print(list(sim_physical_energy_diff)[:5])
+    except:
+        print("Could not convert to list")
+
+# Convert uncertainties to a list of values
+physical_uncertainties = list(sim_physical_uncertainties.values())
+logical_uncertainties = list(sim_logical_uncertainties.values())
+
+# Convert energy differences if needed
+if isinstance(sim_physical_energy_diff, dict):
+    energy_diff = list(sim_physical_energy_diff.values())
+else:
+    energy_diff = sim_physical_energy_diff
+
+fig, ax = plt.subplots(figsize=(11, 7), dpi=200)
+print("1")
+layer_labels = [(int(key.split(":")[0]), int(key.split(":")[1])) for key in bf_energies.keys()]
+plot_labels = [str(item) for item in layer_labels]
+print("here")
+plt.errorbar(
+    plot_labels,
+    sim_physical_energy_diff,
+    yerr=physical_uncertainties,
+    ecolor=(20 / 255.0, 26 / 255.0, 94 / 255.0),
+    color=(20 / 255.0, 26 / 255.0, 94 / 255.0),
+    capsize=4,
+    elinewidth=1.5,
+    fmt="o",
+    markersize=8,
+    markeredgewidth=1,
+    label="Physical",
+)
+print("2")
+
+plt.errorbar(
+    plot_labels,
+    sim_logical_energy_diff,
+    yerr=logical_uncertainties,
+    color=(0, 177 / 255.0, 152 / 255.0),
+    ecolor=(0, 177 / 255.0, 152 / 255.0),
+    capsize=4,
+    elinewidth=1.5,
+    fmt="o",
+    markersize=8,
+    markeredgewidth=1,
+    label="Logical",
+)
+print("3")
+
+ax.set_xlabel("Hamiltonian Parameters (U, V)", fontsize=18)
+ax.set_ylabel("Energy above true ground state (in eV)", fontsize=18)
+ax.set_title("CUDA-Q AIM Circuits Simulation (lower is better)", fontsize=20)
+ax.legend(loc="upper right", fontsize=18.5)
+plt.xticks(fontsize=16)
+plt.yticks(fontsize=16)
+
+print("4")
+
+ax.axhline(y=0, color="black", linestyle="--", linewidth=2)
+plt.ylim(
+    top=max(sim_physical_energy_diff) + max(sim_physical_uncertainties.values()) + 0.2, bottom=-0.2
+)
+print("5")
+plt.tight_layout()
+plt.show()

docref/VQE_Example.md

@@ -0,0 +1,345 @@
+VQE with gradients, active spaces, and gate fusion¶
+This tutorial will explore the Variational Quantum Eigensolver, a hybrid quantum classical algorithm for determining the ground state energy of molecules. The first part of this tutorial will walk through the key aspects of the VQE algorithm and how to implement it with CUDA-Q. The following sections explore advanced topics: parallel gradients, active spaces, and gate fusion
+
+The Basics of VQE¶
+The VQE algorithm is hybrid quantum-classical algorithm, meaning some subroutines run on a quantum computer or quantum simulator and others run on a traditional (super)computer.
+
+The goal is to take a parameterized quantum circuit and a qubit form of the molecular Hamiltonian, measure an expectation value that corresponds to the ground state energy of the molecule, and then repeat the process to variationally minimize the energy with respect to the parameters in the quantum circuit. The optimization is performed on a classical device while the expectation values are determined on a quantum device. See the figure below.
+
+VQE.png
+
+The next few cells will elaborate on each part of the VQE procedure and show you how to build a VQE simulation to compute the ground state energy of the water molecule.
+
+Installing/Loading Relevant Packages¶
+# Install the relevant packages.
+!pip install pyscf==2.6.2 openfermionpyscf==0.5 matplotlib==3.8.4 openfermion==1.6.1 -q
+import openfermion
+import openfermionpyscf
+from openfermion.transforms import jordan_wigner, get_fermion_operator
+
+import os
+import timeit
+
+import cudaq
+import matplotlib.pyplot as plt
+from scipy.optimize import minimize
+import numpy as np
+Implementing VQE in CUDA-Q¶
+Like most quantum chemistry programs, the first step is to specify a molecular geometry, basis set, charge, and multiplicity.
+
+geometry = [('O', (0.1173, 0.0, 0.0)), ('H', (-0.4691, 0.7570, 0.0)),
+            ('H', (-0.4691, -0.7570, 0.0))]
+basis = 'sto3g'
+multiplicity = 1
+charge = 0
+The VQE procedure requires some classical preprocessing. The code below uses the PySCF package and OpenFermion to compute the Hartree Fock reference state and compute the integrals required for the Hamiltonian.
+
+molecule = openfermionpyscf.run_pyscf(
+    openfermion.MolecularData(geometry, basis, multiplicity, charge))
+Next, the Hamiltonian is built using get_molecular_hamiltonian. The Hamiltonian must then be converted to a qubit Hamiltonian consisting of qubit operators. The standard Jordan-Wigner transformation is used to perform this mapping.
+
+Finally, the Jordan-Wigner qubit Hamiltonian is converted into a CUDA-Q spin operator which can be used to evaluate an expectation value given a quantum circuit.
+
+molecular_hamiltonian = molecule.get_molecular_hamiltonian()
+
+fermion_hamiltonian = get_fermion_operator(molecular_hamiltonian)
+
+qubit_hamiltonian = jordan_wigner(fermion_hamiltonian)
+
+spin_ham = cudaq.SpinOperator(qubit_hamiltonian)
+Next, the quantum circuit needs to be defined, which models the wavefunction. This is done in CUDA-Q by specifying a CUDA-Q kernel. The kernel takes as an input the number of qubits, the number of electrons, and the parameters of the circuit ansatz (form of the wavefunction) yet to be defined.
+
+The number of qubits corresponds to the potential positions of electrons and is therefore twice the number of spatial orbitals constructed with the chosen basis set, as each can be occupied by two electrons.
+
+The Hartree-Fock reference is constructed by applying 
+ bitflip operations to each of the first 
+ qubits where 
+ is the number of electrons. Next, a parameterized ansatz is chosen. Theoretically, any set of operations can work as an ansatz, however, it is good practice to use an ansatz that captures the underlying physics of the problem. The most common choice for chemistry is the Unitary Coupled Cluster Ansatz with Single and Double excitations (UCCSD). This UCCSD hate operations are automatically added to the kernel with the cudaq.kernels.uccsd(qubits, thetas, electron_num, qubit_num) function.
+
+The STO-3G water molecuule UCCSD ansatz requires optimization of 140 parameters.
+
+electron_count = 10
+qubit_count = 2 * 7
+
+
+@cudaq.kernel
+def kernel(qubit_num: int, electron_num: int, thetas: list[float]):
+    qubits = cudaq.qvector(qubit_num)
+
+    for i in range(electron_num):
+        x(qubits[i])
+
+    cudaq.kernels.uccsd(qubits, thetas, electron_num, qubit_num)
+
+
+parameter_count = cudaq.kernels.uccsd_num_parameters(electron_count,
+                                                     qubit_count)
+
+print(parameter_count)
+140
+The classical optimizer requires a custom cost function which is defined below. The cudaq.observe() function computes an expectation given the Hamiltonian and the kernel defined above.
+
+def cost(theta):
+
+    exp_val = cudaq.observe(kernel, spin_ham, qubit_count, electron_count,
+                            theta).expectation()
+
+    return exp_val
+
+
+exp_vals = []
+
+
+def callback(xk):
+    exp_vals.append(cost(xk))
+
+
+# Initial variational parameters.
+np.random.seed(42)
+x0 = np.random.normal(0, 1, parameter_count)
+The final step is to run the optimization using the scipy minimize function and a selected optimizer, in this case COBYLA.
+
+cudaq.set_target('nvidia')
+start_time = timeit.default_timer()
+result = minimize(cost,
+                  x0,
+                  method='COBYLA',
+                  callback=callback,
+                  options={'maxiter': 50})
+end_time = timeit.default_timer()
+
+print('UCCSD-VQE energy =  ', result.fun)
+print('Total number of qubits = ', qubit_count)
+print('Total number of parameters = ', parameter_count)
+print('Total number of terms in the spin hamiltonian = ',
+      spin_ham.get_term_count())
+print('Total elapsed time (s) = ', end_time - start_time)
+
+plt.plot(exp_vals)
+plt.xlabel('Epochs')
+plt.ylabel('Energy')
+plt.title('VQE')
+plt.show()
+UCCSD-VQE energy =   -70.21455023422772
+Total number of qubits =  14
+Total number of parameters =  140
+Total number of terms in the spin hamiltonian =  1086
+Total elapsed time (s) =  3.9171073289999185
+../../_images/applications_python_vqe_advanced_21_1.png
+The result of this procedure is an estimate of the ground state energy of water. However, the convergence behavior is not perfect, more iterations would greatly improve the result, but would take a few minutes to run.
+
+Parallel Parameter Shift Gradients¶
+One way to accelerate VQE is to use an optimizer that accepts a gradient. This can drastically lower the number of VQE iterations required at the cost of computing the gradient on the quantum side of the algorithm.
+
+The parameter shift rule is a common technique to compute the gradient for parameterized circuits. It is obtained by computing two expectation values for each parameter corresponding to a small forward and backward shift in the ith parameter. These results are used to estimate finite difference contribution to the gradient.
+
+parametershift.png
+
+This procedure can become cost prohibitive as the number of parameters becomes large.
+
+Each of the expectation values needed to evaluate a parameter shift gradient can be computed independently. The CUDA-Q nvidia-mqpu backend is designed for parallel computations across multiple simulated QPUs. The function below uses cudaq.observe_asynch to distribute all of the expectation values evaluations across as many GPUs that are available. First, try it with num_qpus set to 1.
+
+np.random.seed(42)
+x0 = np.random.normal(0, 1, parameter_count)
+
+cudaq.set_target("nvidia-mqpu")
+
+num_qpus = cudaq.get_target().num_qpus()
+
+epsilon = np.pi / 4
+
+
+def batched_gradient_function(kernel, parameters, hamiltonian, epsilon):
+
+    x = np.tile(parameters, (len(parameters), 1))
+
+    xplus = x + (np.eye(x.shape[0]) * epsilon)
+
+    xminus = x - (np.eye(x.shape[0]) * epsilon)
+
+    g_plus = []
+    g_minus = []
+    gradients = []
+
+    qpu_counter = 0  # Iterate over the number of GPU resources available
+    for i in range(x.shape[0]):
+
+        g_plus.append(
+            cudaq.observe_async(kernel,
+                                hamiltonian,
+                                qubit_count,
+                                electron_count,
+                                xplus[i],
+                                qpu_id=qpu_counter%num_qpus))
+        qpu_counter += 1
+
+        g_minus.append(
+            cudaq.observe_async(kernel,
+                                hamiltonian,
+                                qubit_count,
+                                electron_count,
+                                xminus[i],
+                                qpu_id=qpu_counter%num_qpus))
+        qpu_counter += 1
+
+    gradients = [
+        (g_plus[i].get().expectation() - g_minus[i].get().expectation()) /
+        (2 * epsilon) for i in range(len(g_minus))
+    ]
+
+    assert len(gradients) == len(
+        parameters) == x.shape[0] == xplus.shape[0] == xminus.shape[0]
+
+    return gradients
+[warning] Target nvidia-mqpu: This target is deprecating. Please use the 'nvidia' target with option 'mqpu,fp32' or 'mqpu' (fp32 is the default precision option) by adding the command line option '--target-option mqpu,fp32' or passing it as cudaq.set_target('nvidia', option='mqpu,fp32') in Python. Please refer to CUDA-Q ]8;;https://nvidia.github.io/cuda-quantum/latest/using/backends/platform\documentation]8;;\ for more information.
+The cost function needs to be slightly updated to make use of the gradient in the optimization procedure and allow for a gradient based optimizer like L-BFGS-B to be used.
+
+gradient = batched_gradient_function(kernel, x0, spin_ham, epsilon)
+
+exp_vals = []
+
+
+def objective_function(parameter_vector: list[float], \
+                       gradient=gradient, hamiltonian=spin_ham, kernel=kernel):
+
+    get_result = lambda parameter_vector: cudaq.observe\
+        (kernel, hamiltonian, qubit_count, electron_count, parameter_vector).expectation()
+
+    cost = get_result(parameter_vector)
+    exp_vals.append(cost)
+    gradient_vector = batched_gradient_function(kernel, parameter_vector,
+                                                spin_ham, epsilon)
+
+    return cost, gradient_vector
+Run the code below. Notice how the result is converged to a lower energy using only 10% of the steps as optimization above without a gradient.
+
+np.random.seed(42)
+init_params = np.random.normal(0, 1, parameter_count)
+
+start_time = timeit.default_timer()
+result_vqe = minimize(objective_function,
+                      init_params,
+                      method='L-BFGS-B',
+                      jac=True,
+                      tol=1e-8,
+                      options={'maxiter': 5})
+end_time = timeit.default_timer()
+
+print('VQE-UCCSD energy= ', result_vqe.fun)
+print('Total elapsed time (s) = ', end_time - start_time)
+
+plt.plot(exp_vals)
+plt.xlabel('Epochs')
+plt.ylabel('Energy')
+plt.title('VQE')
+plt.show()
+VQE-UCCSD energy=  -73.19471262288755
+Total elapsed time (s) =  57.27010986900132
+../../_images/applications_python_vqe_advanced_30_1.png
+Now, run the code again (the three previous cells) and specify num_qpus to be more than one if you have access to multiple GPUs and notice resulting speedup. Thanks to CUDA-Q, this code could be used without modification in a setting where multiple physical QPUs were availible.
+
+Using an Active Space¶
+Performing electronic structure computations with all electrons and orbitals is often prohibitively expensive and unnecessary. Most of the interesting chemistry can be modeled by restricting simulations to the highest energy occupied molecular orbitals and lowest energy unoccupied molecular orbitals. This is known as the active space approximation.
+
+Below is an example of STO-3G water modeled with a 4 electron 3 orbital active space simulated with UCCSD-VQE. Using an active space means you can run VQE for the same molecule using fewer qubits and a more shallow circuit.
+
+cas.png
+
+The molecule is defined the same way, expect for you now include variables nele_cas and norb_cas to define the active space. The ncore
+
+geometry = [('O', (0.1173, 0.0, 0.0)), ('H', (-0.4691, 0.7570, 0.0)),
+            ('H', (-0.4691, -0.7570, 0.0))]
+basis = 'sto3g'
+multiplicity = 1
+charge = 0
+ncore = 3
+nele_cas, norb_cas = (4, 3)
+
+molecule = openfermionpyscf.run_pyscf(
+    openfermion.MolecularData(geometry, basis, multiplicity, charge))
+The Hamiltonian is now constrcuted with the same steps, but only models the active space.
+
+molecular_hamiltonian = molecule.get_molecular_hamiltonian(
+    occupied_indices=range(ncore),
+    active_indices=range(ncore, ncore + norb_cas))
+
+fermion_hamiltonian = get_fermion_operator(molecular_hamiltonian)
+
+qubit_hamiltonian = jordan_wigner(fermion_hamiltonian)
+
+spin_ham = cudaq.SpinOperator(qubit_hamiltonian)
+Similarly, the kernel is defined only by the orbitals and electrons in the active space. Notice how this means you only need to optimize 8 parameters now.
+
+electron_count = nele_cas
+qubit_count = 2 * norb_cas
+
+
+@cudaq.kernel
+def kernel(qubit_num: int, electron_num: int, thetas: list[float]):
+    qubits = cudaq.qvector(qubit_num)
+
+    for i in range(electron_num):
+        x(qubits[i])
+
+    cudaq.kernels.uccsd(qubits, thetas, electron_num, qubit_num)
+
+
+parameter_count = cudaq.kernels.uccsd_num_parameters(electron_count,
+                                                     qubit_count)
+
+print(parameter_count)
+8
+def cost(theta):
+
+    exp_val = cudaq.observe(kernel, spin_ham, qubit_count, electron_count,
+                            theta).expectation()
+    thetas = theta
+    return exp_val
+
+
+exp_vals = []
+
+
+def callback(xk):
+    exp_vals.append(cost(xk))
+
+
+# Initial variational parameters.
+np.random.seed(42)
+x0 = np.random.normal(0, 1, parameter_count)
+The VQE procedure below is much faster using an active space compared to inclusion of all orbitals and electrons.
+
+cudaq.set_target("nvidia")
+
+start_time = timeit.default_timer()
+result = minimize(cost,
+                  x0,
+                  method='COBYLA',
+                  callback=callback,
+                  options={'maxiter': 500})
+end_time = timeit.default_timer()
+
+print('UCCSD-VQE energy =  ', result.fun)
+print('Total number of qubits = ', qubit_count)
+print('Total number of parameters = ', parameter_count)
+print('Total number of terms in the spin hamiltonian = ',
+      spin_ham.get_term_count())
+print('Total elapsed time (s) = ', end_time - start_time)
+
+plt.plot(exp_vals)
+plt.xlabel('Epochs')
+plt.ylabel('Energy')
+plt.title('VQE')
+plt.show()
+UCCSD-VQE energy =   -74.96341992791962
+Total number of qubits =  6
+Total number of parameters =  8
+Total number of terms in the spin hamiltonian =  62
+Total elapsed time (s) =  1.754178541001238
+../../_images/applications_python_vqe_advanced_43_1.png
+Gate Fusion for Larger Circuits¶
+CUDA-Q simulations take advantage of a technique called gate fusion. Gate fusion is an optimization technique where consecutive gates are combined into a single gate operation to improve the efficiency of the simulation (See figure below). By targeting the nvidia-mgpu backend and setting the CUDAQ_MGPU_FUSE environment variable, you can select the degree of fusion that takes place.
+
+gate-fuse.png
+
+This is particularly important for larger circuits and can have a significant impact on the performance of the simulation. Each system is different, so you should test different gate fusion levels to find out what is best for your system. You can find more information here.

docref/molgallery_demo.md

@@ -0,0 +1,39 @@
+The gradio_molgallery3d package is a custom component for Gradio, designed specifically for displaying an interactive gallery of 3D molecular structures. Here are some key features and details:
+Installation: You can install this component using pip install gradio_molgallery3d.
+Input: It accepts inputs in the form of RDKit objects, which are commonly used for cheminformatics and molecular modeling.
+Features:
+Automatic Rotation: When the automatic_rotation parameter is set to True, the molecular structures rotate automatically, providing a dynamic view of the molecule.
+Download Capability: Users can download the 3D structure as a .png file by clicking the right mouse button on the structure.
+Known Issues: Web browsers have limitations on the number of canvas objects that can be displayed on a single page, which might result in some structures not being drawn. This limitation varies by browser.
+Example Usage for Visualizing H2O:
+Here's a code snippet to show how you can use gradio_molgallery3d to visualize the H2O molecule:
+
+
+import gradio as gr
+from rdkit import Chem
+from gradio_molgallery import MolGallery3D
+
+# Create an RDKit molecule object for H2O
+h2o_mol = Chem.MolFromSmiles('O')
+
+# Set up the gallery
+gallery3d = MolGallery3D(
+    columns=1,  # Since we're showing only one molecule
+    height=400,  # Adjust the height as needed
+    label="3D Structure of H2O",
+    automatic_rotation=True
+)
+
+# Define a function to return the molecule
+def show_h2o():
+    return [h2o_mol]
+
+# Create the Gradio interface
+with gr.Blocks() as demo:
+    gr.Markdown("# 3D Visualization of H2O")
+    gallery = gallery3d
+    btn = gr.Button("Show H2O")
+    btn.click(fn=show_h2o, outputs=gallery)
+
+# Launch the demo
+demo.launch()

docref/py3dmol_demo.md

@@ -0,0 +1,45 @@
+Here's a sample code to show an H2 molecule and a water molecule in a py3Dmol flow inside a Gradio display:
+
+Explanation:
+Molecule Creation: The molecule_viewer function takes a molecule_type parameter to determine which molecule to visualize. It uses RDKit to create the molecule from SMILES strings, add hydrogens, and embed the molecule in 3D space.
+Visualization: The molecule is then converted to a MolBlock format, which py3Dmol can read. The view object is created with the molecule data, and styles are applied to show the molecule in stick and sphere representations.
+Gradio Interface: The Gradio interface allows users to select between H2 and H2O molecules using a radio button. The selected molecule is then visualized in the HTML output.
+Launch: The Gradio app is launched, providing an interactive web interface where users can view the 3D models of the selected molecules.
+This code provides a simple yet effective way to visualize H2 and H2O molecules in 3D within a Gradio interface. Users can rotate, zoom, and interact with the molecules to explore their structures.
+
+
+import gradio as gr
+from rdkit import Chem
+from rdkit.Chem import AllChem
+import py3Dmol
+
+def molecule_viewer(molecule_type):
+    if molecule_type == "H2":
+        # Create an H2 molecule
+        h2 = Chem.MolFromSmiles("H[H]")
+        h2 = AllChem.AddHs(h2)
+        AllChem.EmbedMolecule(h2)
+        mol_block = Chem.MolToMolBlock(h2)
+    elif molecule_type == "H2O":
+        # Create a water molecule
+        water = Chem.MolFromSmiles("O")
+        water = AllChem.AddHs(water)
+        AllChem.EmbedMolecule(water)
+        mol_block = Chem.MolToMolBlock(water)
+    else:
+        return "Invalid molecule type"
+
+    # Create the 3Dmol view
+    view = py3Dmol.view(data=mol_block, style={"stick": {}, "sphere": {"scale": 0.3}})
+    view.zoomTo()
+    return view
+
+# Define the Gradio interface
+demo = gr.Interface(
+    fn=molecule_viewer,
+    inputs=gr.Radio(choices=["H2", "H2O"], label="Select Molecule"),
+    outputs=gr.HTML(label="3D Molecule Viewer")
+)
+
+# Launch the Gradio app
+demo.launch()

docref/quantum-demo-blueprint.md

@@ -0,0 +1,254 @@
+# NVIDIA Quantum Library Gradio Demo - Project Blueprint
+
+## Overview
+This project creates an interactive web demo showcasing NVIDIA's CUDA Quantum Library (CUDA-Q) for quantum computations. The demo focuses on the Variational Quantum Eigensolver (VQE) algorithm for molecular energy estimation, providing users with an educational interface for quantum control and simulation.
+
+## Project Objectives
+- Create an intuitive, interactive demo of quantum computations using CUDA-Q
+- Visualize molecular energy estimation using the VQE algorithm
+- Provide real-time feedback on quantum simulation parameters
+- Educate users about quantum chemistry concepts
+
+## Core Features
+
+### Molecule Selection
+- Simple molecule options: H₂, LiH, and HeH⁺
+- Intuitive dropdown or button-based selection interface
+- Expandable framework for additional molecules
+
+### Parameter Controls
+- **Bond Length Control**
+  - Range: 0.5 Å to 2.5 Å
+  - Real-time updates of molecular geometry
+  - Continuous slider interface
+
+- **Bond Angle Adjustment**
+  - Range: 90° to 180° (for multi-atom molecules)
+  - Dynamic updates of molecular structure
+  - Visual feedback on angle changes
+
+### Visualization Components
+- **Energy Convergence Display**
+  - Real-time line plot showing VQE optimization
+  - Interactive zoom and pan capabilities
+  - Clear indication of convergence points
+
+- **3D Molecular Visualization**
+  - Dynamic molecular structure rendering
+  - Rotation and zoom capabilities
+  - Real-time updates with parameter changes
+
+### Backend Features
+- CUDA-Q integration for quantum calculations
+- VQE algorithm implementation
+- GPU-accelerated computations
+- Real-time parameter optimization
+
+## Technology Stack
+
+### Frontend Framework
+- **Gradio**
+  - Version: Latest stable
+  - Purpose: Web interface construction
+  - Key components: Sliders, buttons, plots
+
+- **Bokeh**
+  - Version: Latest stable
+  - Purpose: Interactive plotting
+  - Features: Real-time updates, zoom, pan
+
+### Quantum Computing Stack
+- **NVIDIA CUDA Quantum Library**
+  - Core quantum simulation engine
+  - GPU acceleration support
+  - Hybrid quantum-classical optimization
+
+- **Supporting Libraries**
+  - PySCF (optional): Molecular Hamiltonian preparation
+  - Qiskit (optional): Additional quantum tools
+
+### Visualization Tools
+- **ASE (Atomic Simulation Environment)**
+  - Molecular geometry handling
+  - Structure visualization
+  - Real-time updates
+
+- **Matplotlib**
+  - Backup plotting capability
+  - Static visualizations
+  - Export functionality
+
+### Core Dependencies
+- NumPy (≥1.20.0)
+- SciPy (≥1.7.0)
+- CUDA Toolkit (≥11.0)
+- Python (≥3.8)
+
+## Implementation Guide
+
+### 1. Environment Setup
+```bash
+# Core dependencies
+pip install gradio>=3.50.0 bokeh>=3.0.0 matplotlib>=3.5.0
+pip install ase>=3.22.0 numpy>=1.20.0 scipy>=1.7.0
+
+# NVIDIA components
+# Follow NVIDIA documentation for CUDA Toolkit installation
+# Install CUDA-Q as per NVIDIA guidelines
+```
+
+### 2. Molecular System Implementation
+```python
+# Example molecular system setup
+def setup_molecule(name: str, bond_length: float):
+    molecules = {
+        'H2': create_h2_molecule,
+        'LiH': create_lih_molecule,
+        'HeH+': create_heh_molecule
+    }
+    return molecules[name](bond_length)
+```
+
+### 3. VQE Algorithm Setup
+```python
+# Basic VQE implementation structure
+class VQESimulation:
+    def __init__(self, molecule, ansatz):
+        self.molecule = molecule
+        self.ansatz = ansatz
+        
+    # Implementation using CUDA-Q
+result = optimizer.minimize(self.cost_function, initial_parameters, callback=self.callback)
+return result
+def cost_function(self, parameters):
+# Compute expectation value
+exp_val = cudaq.observe(self.ansatz, self.molecule.hamiltonian, parameters).expectation()
+return exp_val
+
+def callback(self, parameters):
+# Optionally store or display intermediate results
+pass
+```
+
+
+
+### 4. Ansatz Implementation
+```python
+# Example UCCSD Ansatz implementation
+def create_uccsd_ansatz(qubit_num: int, electron_num: int):
+@cudaq.kernel
+def kernel(qubit_num: int, electron_num: int, thetas: list[float]):
+qubits = cudaq.qvector(qubit_num)
+for i in range(electron_num):
+x(qubits[i])
+cudaq.kernels.uccsd(qubits, thetas, electron_num, qubit_num)
+return kernel
+Cost function using CUDA-Q observe
+def cost(theta, kernel, hamiltonian, qubit_count, electron_count):
+exp_val = cudaq.observe(kernel, hamiltonian, qubit_count, electron_count, theta).expectation()
+return exp_val
+Optimization procedure
+def run_optimization(initial_params, kernel, hamiltonian, qubit_count, electron_count):
+from scipy.optimize import minimize
+exp_vals = []
+def callback(xk):
+exp_vals.append(cost(xk, kernel, hamiltonian, qubit_count, electron_count))
+result = minimize(
+cost,
+initial_params,
+args=(kernel, hamiltonian, qubit_count, electron_count),
+method='COBYLA',
+callback=callback,
+options={'maxiter': 500}
+)
+return result, exp_vals
+UI
+python:src/ui.py
+Gradio interface setup with VQE integration
+def create_interface(vqe_simulation):
+with gr.Blocks() as demo:
+gr.Markdown("# Quantum Chemistry Simulator")
+# Molecule Selection
+molecule = gr.Dropdown(choices=['H2', 'LiH', 'HeH+'], label="Select Molecule")
+# Parameter Controls
+bond_length = gr.Slider(0.5, 2.5, step=0.1, label="Bond Length (Å)")
+bond_angle = gr.Slider(90, 180, step=1, label="Bond Angle (°)")
+electric_field = gr.Slider(0, 10, step=0.1, label="Electric Field (V/nm)")
+# Run VQE Button
+run_button = gr.Button("Run VQE")
+# Output Display
+energy_output = gr.Textbox(label="Computed Energy")
+convergence_plot = gr.Plot(label="Energy Convergence")
+def run_vqe(selected_molecule, bond_len, bond_ang, e_field):
+molecule = setup_molecule(selected_molecule, bond_len)
+# Update molecular system parameters based on UI inputs
+vqe_simulation = VQESimulation(molecule, ansatz)
+initial_params = np.random.normal(0, 1, vqe_simulation.ansatz.parameter_count)
+result, exp_vals = run_optimization(initial_params, vqe_simulation.ansatz, molecule.hamiltonian, molecule.qubit_count, molecule.electron_count)
+energy = result.fun
+# Plot convergence
+plt.plot(exp_vals)
+plt.xlabel('Iterations')
+plt.ylabel('Energy')
+plt.title('VQE Energy Convergence')
+return energy, plt
+run_button.click(run_vqe, inputs=[molecule, bond_length, bond_angle, electric_field], outputs=[energy_output, convergence_plot])
+return demo
+integration
+
+### 7. Advanced VQE Features
+- **Parallel Gradients:** Implement parameter shift rule with parallel computations using multiple QPUs for gradient calculations to accelerate optimization.
+- **Active Space Reduction:** Allow users to select active space parameters, reducing the number of qubits and parameters for larger molecules, enhancing performance.
+- **Gate Fusion:** Optimize larger circuits by implementing gate fusion techniques to improve simulation efficiency on GPU backends.
+
+
+## Deployment Workflow
+
+### Local Development
+1. Clone repository
+2. Install dependencies
+3. Configure CUDA environment
+4. Run development server
+
+### Production Deployment
+1. Package application
+2. Verify CUDA compatibility
+3. Deploy to target platform
+4. Configure monitoring
+
+## Testing Strategy
+
+### Unit Tests
+- Molecular system creation
+- Parameter validation
+- Energy calculation accuracy
+
+### Integration Tests
+- UI component interaction
+- Data flow verification
+- GPU utilization
+
+### Performance Tests
+- Load testing
+- GPU memory usage
+- Calculation speed
+
+## Future Enhancements
+- Support for larger molecular systems
+- Advanced visualization features
+- Additional quantum algorithms
+- Export functionality for results
+- Multi-GPU support
+
+## Documentation
+- User guide
+- API documentation
+- Installation instructions
+- Troubleshooting guide
+
+## Maintenance
+- Regular dependency updates
+- Performance optimization
+- Bug fixes and improvements
+- User feedback integration
+

gitpush.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+
+# Check if a commit message was provided
+if [ $# -eq 0 ]; then
+    echo "Error: Please provide a commit message"
+    echo "Usage: ./git_push.sh \"Your commit message\""
+    exit 1
+fi
+
+# Store the commit message
+commit_message="$1"
+
+# Echo and execute git add
+echo "➡️ Adding all files..."
+git add .
+
+# Echo and show status
+echo -e "\n📋 Current git status:"
+git status
+
+# Echo and commit with provided message
+echo -e "\n💾 Committing changes with message: '$commit_message'"
+git commit -m "$commit_message"
+
+# Echo and push to main
+echo -e "\n⬆️ Pushing to main branch..."
+git push origin main
+
+echo -e "\n✅ Done!"

history.md

@@ -0,0 +1,159 @@
+# Development History
+
+## 2024-01-06 (Update 9)
+- Fixed scale factor slider behavior:
+  * Added initial placeholder text for visualization and results
+  * Removed all automatic updates except molecule description
+  * Made scale factor slider explicitly interactive
+  * Added state management for molecule data
+  * Improved user feedback by showing "Click Run" messages
+
+## 2024-01-06 (Update 8)
+- Improved interface stability for multi-molecule support:
+  * Removed automatic simulation updates on parameter changes
+  * Combined molecule info updates into single atomic operation
+  * Fixed component creation order and initialization
+  * Added proper error handling for molecule selection
+  * Addressed "Casting complex values to real" warning (normal for quantum chemistry)
+
+## 2024-01-06 (Update 7)
+- Major update to handle molecular geometry scaling:
+  * Replaced bond length with universal scale factor for all molecules
+  * Added expand_geometry function to scale molecules from their center
+  * Updated molecules.json to use scale ranges (0.1 to 3.0) instead of bond lengths
+  * Fixed molecules.json structure by removing extra nesting level
+  * Added dynamic scale factor range updates in UI
+  * Updated all molecule descriptions to reflect scaling approach
+
+## 2024-01-06 (Update 6)
+- Major restructuring to support multiple molecules:
+  * Created molecules.json to store all molecule metadata
+  * Updated app.py to load molecule data and create dynamic interface
+  * Modified quantum_utils.py to use molecule metadata instead of hardcoded values
+  * Updated visualization.py to use molecule data from JSON
+  * Added molecule descriptions and dynamic bond length ranges
+  * Improved error handling across all components
+
+## 2024-01-06 (Update 5)
+- Fixed 3D molecule viewer to properly render in Gradio
+- Modified create_molecule_viewer to return HTML string instead of view object
+- Added explicit width and height to py3Dmol view
+- Added more detailed logging for visualization debugging
+
+## 2024-01-06 (Update 4)
+- Simplified molecule visualization to match py3dmol_demo.md exactly
+- Fixed SMILES format for H2 molecule to "[H][H]"
+- Removed overcomplicated bond length adjustment code
+- Fixed py3Dmol view creation parameters
+
+## 2024-01-06 (Update 3)
+- Completely revamped molecule visualization to use RDKit for proper molecular structure generation
+- Added RDKit dependency to requirements.txt
+- Updated create_molecule_viewer to handle proper 3D coordinates and bond length adjustments
+- Improved molecule viewer to return py3Dmol view object directly instead of HTML
+
+## 2024-01-06 (Update 2)
+- Fixed py3Dmol viewer in Gradio by using _repr_html_() instead of _make_html()
+- This resolved the JupyterLab extension error message in the 3D viewer
+
+## 2024-01-06
+- Fixed import error by updating app.py to import create_molecule_viewer instead of draw_molecule_2d
+- This resolved the application crash that occurred after the 3D visualization update
+
+## 2024-01-04 (Update 9)
+- Successfully integrated HuggingFace ZeroGPU functionality with CUDA-Q
+- First known working CUDA-Q demo on HuggingFace Spaces platform
+- Implemented @spaces.GPU decorator for GPU-dependent functions
+- Added appropriate duration parameter (120s) for VQE simulation
+- Historic milestone: First functional CUDA-Q HuggingFace Space demo by Alex Krause and... possibly ever, he found no other examples of this.
+- Current Status: Fully functional GPU-accelerated quantum simulation with dynamic GPU allocation
+
+## 2024-01-04 (Update 8)
+- Completely refactored visualization system to use Plotly instead of Matplotlib
+- Removed complex base64 encoding/file handling for plots
+- Switched to direct Plotly integration with Gradio's Plot component
+- Added interactive features to plots (zoom, pan, hover tooltips)
+- Fixed font debug message spam by adjusting logging levels
+- Added plotly==5.18.0 to requirements.txt
+- Current Status: Clean, interactive plotting with proper Gradio integration
+
+## 2024-01-02 (Update 7)
+- Modified quantum_utils.py to store iterations as integers instead of strings
+- Simplified visualization.py to handle native integer iterations
+- Improved type consistency across the codebase
+- Current Status: Cleaner data handling with proper numeric types
+
+## 2024-01-02 (Update 6)
+- Enhanced visualization.py to handle string iteration numbers robustly
+- Added error handling for iteration and energy value conversions
+- Implemented safe type conversion with try-except blocks
+- Current Status: Visualization properly handles all data types from results dictionary
+
+## 2024-01-02 (Update 5)
+- Fixed type conversion in visualization.py for iteration numbers
+- Modified energy extraction to use actual iteration energy values
+- Resolved "list indices must be integers or slices, not str" error
+- Current Status: Visualization properly handles string iteration numbers from results
+
+## 2024-01-02 (Update 4)
+- Modified visualization.py to handle full results dictionary
+- Updated plot_convergence to extract iteration data from results history
+- Added final energy reference line to convergence plot
+- Maintained rich data structure between modules for future extensibility
+- Current Status: Improved integration between quantum_utils.py and visualization.py while preserving data
+
+## 2024-01-02 (Update 2)
+- Fixed "unhashable type: 'dict'" error in results processing
+- Modified results dictionary structure to ensure all keys are strings
+- Added energy values to iteration history entries
+- Improved type handling in results dictionary to prevent hashing issues
+- Current Status: VQE optimization and results processing working correctly
+
+## 2024-01-02 (Update 1)
+- Fixed iteration history processing in VQE simulation
+- Added more robust data extraction from solver results
+- Implemented fallback mechanism for iteration history
+- Current Status: VQE optimization successfully completes with final energy: -1.8513513513513509
+- Added better error handling and logging for iteration data processing
+- Previous warning about missing 'energy' attribute has been addressed with more flexible data extraction
+
+## Current Status (2024-01-02)
+- VQE optimization now successfully completes with final energy: -1.8513513513513509
+- Fixed several major issues:
+  1. Replaced `@cudaq.kernel` decorator with `cudaq.make_kernel()` to properly handle variational parameters
+  2. Modified parameter handling to use list type instead of float
+  3. Successfully implemented proper logging to both file and console
+- Current Issue:
+  Unable to process iteration history data from VQE solver. Error indicates the solver's iteration objects 
+  don't have expected 'energy' attribute. Need to investigate CUDA-Q solver's iteration data structure.
+  Error: "'cudaq_solvers._pycudaqx_solvers_the_suffix_matters' object has no attribute 'energy'"
+
+## Bug Fixes (2024-01-02)
+- Fixed VQE kernel initialization error by replacing `@cudaq.kernel` decorator with `cudaq.make_kernel()`. 
+  This resolved the "local variable 'id' referenced before assignment" error by properly creating a parameterized kernel 
+  that can handle variational parameters in the VQE optimization process.
+  The `make_kernel()` approach matches CUDA-Q's expected way of handling parameterized quantum circuits.
+
+## Current Investigation (2024-12-30)
+Investigating error: "capi_return is NULL Call-back cb_calcfc_in__cobyla__user__routines failed"
+
+Steps tried so far:
+1. Initially used direct CUDA-Q optimizer (cudaq.optimizers.COBYLA)
+2. Switched to cudaq_solvers.vqe with scipy.minimize
+3. Added args=() tuple based on StackOverflow solution for similar COBYLA callback error
+4. Added explicit measurement operations to quantum kernel
+
+## Bug Fixes
+
+### 2024-12-30
+- Fixed CUDA-Q kernel return type issue: Modified `h2_ansatz` kernel to have void return type (removed `return qubits` statement) to comply with CUDA-Q's requirement that kernels passed to `observe` must have void return type.
+- Fixed Hamiltonian construction to use proper CUDA-Q spin operators (`cudaq.spin.x/y/z`) instead of string-based operator construction.
+- Fixed missing operation error: Added registration of `meas_id` operation using `cudaq.register_operation("meas_id", np.identity(2))` for noise modeling.
+- Fixed optimization error: Added empty args tuple to VQE solver call to properly handle callback arguments in scipy.optimize.minimize.
+- Fixed measurement error: Added explicit measurement operation (`mz`) to the quantum kernel to ensure proper state measurement.
+
+## 2024-03-19
+- Enhanced molecular visualization by replacing 2D Plotly plots with interactive 3D visualization using py3Dmol
+- Added py3Dmol dependency to requirements.txt
+- Updated app interface to use HTML component for 3D molecule viewer
+- Improved H2 molecule representation with proper 3D coordinates and styling

install.py

@@ -0,0 +1,8 @@
+import subprocess
+import sys
+
+def install_requirements():
+    subprocess.check_call([sys.executable, "-m", "pip", "install", "-r", "requirements.txt"])
+
+if __name__ == "__main__":
+    install_requirements()

molecules.json

@@ -0,0 +1,157 @@
+{
+    "H2": {
+        "name": "Hydrogen molecule",
+        "formula": "H₂",
+        "smiles": "[H][H]",
+        "basis": "sto-3g",
+        "multiplicity": 1,
+        "charge": 0,
+        "spatial_orbitals": 2,
+        "electron_count": 2,
+        "default_scale": 1.0,
+        "scale_range": {
+            "min": 0.1,
+            "max": 3.0,
+            "step": 0.05
+        },
+        "geometry_template": [
+            ["H", [0.0, 0.0, 0.0]],
+            ["H", [0.74, 0.0, 0.0]]
+        ],
+        "description": "Diatomic hydrogen molecule, the simplest neutral molecule. Scale factor affects the overall size of the molecule."
+    },
+    "H2O": {
+        "name": "Water",
+        "formula": "H₂O",
+        "smiles": "O",
+        "basis": "sto-3g",
+        "multiplicity": 1,
+        "charge": 0,
+        "spatial_orbitals": 7,
+        "electron_count": 10,
+        "default_scale": 1.0,
+        "scale_range": {
+            "min": 0.1,
+            "max": 3.0,
+            "step": 0.05
+        },
+        "geometry_template": [
+            ["O", [0.1173, 0.0, 0.0]],
+            ["H", [-0.4691, 0.7570, 0.0]],
+            ["H", [-0.4691, -0.7570, 0.0]]
+        ],
+        "description": "Triatomic water molecule with bent geometry. Scale factor affects the overall size of the molecule."
+    },
+    "CH4": {
+        "name": "Methane",
+        "formula": "CH₄",
+        "smiles": "C",
+        "basis": "sto-3g",
+        "multiplicity": 1,
+        "charge": 0,
+        "spatial_orbitals": 9,
+        "electron_count": 10,
+        "default_scale": 1.0,
+        "scale_range": {
+            "min": 0.1,
+            "max": 3.0,
+            "step": 0.05
+        },
+        "geometry_template": [
+            ["C", [0.0, 0.0, 0.0]],
+            ["H", [1.09, 0.0, 0.0]],
+            ["H", [-0.363, 1.03, 0.0]],
+            ["H", [-0.363, -0.515, 0.891]],
+            ["H", [-0.363, -0.515, -0.891]]
+        ],
+        "description": "Tetrahedral methane molecule with single bonds. Scale factor affects the overall size of the molecule."
+    },
+    "BeH2": {
+        "name": "Beryllium hydride",
+        "formula": "BeH₂",
+        "smiles": "[BeH2]",
+        "basis": "sto-3g",
+        "multiplicity": 1,
+        "charge": 0,
+        "spatial_orbitals": 7,
+        "electron_count": 4,
+        "default_scale": 1.0,
+        "scale_range": {
+            "min": 0.1,
+            "max": 3.0,
+            "step": 0.05
+        },
+        "geometry_template": [
+            ["Be", [0.0, 0.0, 0.0]],
+            ["H", [1.33, 0.0, 0.0]],
+            ["H", [-1.33, 0.0, 0.0]]
+        ],
+        "description": "Linear beryllium hydride molecule. Scale factor affects the overall size of the molecule."
+    },
+    "CO": {
+        "name": "Carbon monoxide",
+        "formula": "CO",
+        "smiles": "[C-]#[O+]",
+        "basis": "sto-3g",
+        "multiplicity": 1,
+        "charge": 0,
+        "spatial_orbitals": 10,
+        "electron_count": 14,
+        "default_scale": 1.0,
+        "scale_range": {
+            "min": 0.1,
+            "max": 3.0,
+            "step": 0.05
+        },
+        "geometry_template": [
+            ["C", [0.0, 0.0, 0.0]],
+            ["O", [1.13, 0.0, 0.0]]
+        ],
+        "description": "Diatomic carbon monoxide molecule with a triple bond. Scale factor affects the overall size of the molecule."
+    },
+    "N2": {
+        "name": "Nitrogen molecule",
+        "formula": "N₂",
+        "smiles": "N#N",
+        "basis": "sto-3g",
+        "multiplicity": 1,
+        "charge": 0,
+        "spatial_orbitals": 10,
+        "electron_count": 14,
+        "default_scale": 1.0,
+        "scale_range": {
+            "min": 0.1,
+            "max": 3.0,
+            "step": 0.05
+        },
+        "geometry_template": [
+            ["N", [0.0, 0.0, 0.0]],
+            ["N", [1.1, 0.0, 0.0]]
+        ],
+        "description": "Diatomic nitrogen molecule with a triple bond. Scale factor affects the overall size of the molecule."
+    },
+    "NH3": {
+        "name": "Ammonia",
+        "formula": "NH₃",
+        "smiles": "N",
+        "basis": "sto-3g",
+        "multiplicity": 1,
+        "charge": 0,
+        "spatial_orbitals": 9,
+        "electron_count": 10,
+        "default_scale": 1.0,
+        "scale_range": {
+            "min": 0.1,
+            "max": 3.0,
+            "step": 0.05
+        },
+        "geometry_template": [
+            ["N", [0.0, 0.0, 0.0]],
+            ["H", [1.01, 0.0, 0.0]],
+            ["H", [-0.505, 0.875, 0.0]],
+            ["H", [-0.505, -0.875, 0.0]]
+        ],
+        "description": "Trigonal pyramidal ammonia molecule with lone pair on nitrogen. Scale factor affects the overall size of the molecule."
+    }
+}
+  

packages.txt

@@ -0,0 +1,3 @@
+python3-dev
+python3-pip
+build-essential 

quantum_utils.py

@@ -0,0 +1,332 @@
+"""
+quantum_utils.py
+Helper library for running a simplified VQE or quantum simulation
+that references CUDA-Q for computations.
+
+References:
+ - @Cuda-Q_install.md for installation details
+ - @VQE_Example.md for example VQE code using nvidia or nvidia-mqpu backend
+"""
+
+import cudaq
+import cudaq_solvers as solvers  # Import solvers from cudaq_solvers package
+import numpy as np
+from scipy.optimize import minimize
+import spaces
+from typing import Dict, List, Union, Any, Tuple
+import sys
+import logging
+import os
+from logging.handlers import RotatingFileHandler
+import openfermion
+import openfermionpyscf
+from openfermion.transforms import jordan_wigner, get_fermion_operator
+
+# Create logs directory if it doesn't exist
+os.makedirs('logs', exist_ok=True)
+
+# Configure logging to write to both file and stderr
+# Create a formatter
+formatter = logging.Formatter('%(asctime)s - %(levelname)s - %(message)s')
+
+# Set up file handler with rotation
+file_handler = RotatingFileHandler(
+    'logs/vqe_simulation.log',
+    maxBytes=10*1024*1024,  # 10MB
+    backupCount=5
+)
+file_handler.setFormatter(formatter)
+
+# Set up console handler
+console_handler = logging.StreamHandler()
+console_handler.setFormatter(formatter)
+
+# Configure root logger
+logger = logging.getLogger()
+logger.setLevel(logging.DEBUG)
+logger.addHandler(file_handler)
+logger.addHandler(console_handler)
+
+# Log startup message
+logging.info("VQE Simulation logging initialized")
+
+print("quantum_utils imported", file=sys.stderr, flush=True)
+
+@spaces.GPU
+def setup_target():
+    """Set up CUDA-Q target based on available hardware."""
+    try:
+        print("Setting up target...", file=sys.stderr, flush=True)
+        gpu_count = cudaq.num_available_gpus()
+        print(f"Number of available GPUs: {gpu_count}", file=sys.stderr, flush=True)
+        
+        if gpu_count > 0:
+            print("Attempting to set NVIDIA GPU target...", file=sys.stderr, flush=True)
+            cudaq.set_target("nvidia")
+            print("Successfully set NVIDIA GPU target", file=sys.stderr, flush=True)
+        else:
+            print("No GPU found, attempting to set CPU target...", file=sys.stderr, flush=True)
+            cudaq.set_target("qpp-cpu")
+            print("Successfully set CPU target", file=sys.stderr, flush=True)
+    except Exception as e:
+        print(f"Error setting up quantum target: {str(e)}", file=sys.stderr, flush=True)
+        import traceback
+        print(f"Traceback:\n{traceback.format_exc()}", file=sys.stderr, flush=True)
+        raise
+
+def vqe_callback(xk):
+    """Callback function for VQE optimization to track progress."""
+    try:
+        logging.info(f"VQE iteration - Current parameters: {xk}")
+        return True
+    except Exception as e:
+        logging.error(f"Error in VQE callback: {str(e)}")
+        return False
+
+@spaces.GPU
+def validate_ansatz(kernel_generator, init_params, qubit_num, electron_num):
+    """Validate the ansatz kernel before VQE."""
+    try:
+        logging.debug("Validating ansatz kernel...")
+        # Set up target before validation
+        setup_target()
+        
+        # Generate the kernel with the correct number of qubits and electrons
+        kernel = kernel_generator(qubit_num, electron_num)
+        
+        # Log the types and values of parameters and qubits
+        logging.debug(f"Kernel parameters type: {type(init_params)}, values: {init_params}")
+        logging.debug(f"Kernel qubits type: {type(qubit_num)}, value: {qubit_num}")
+        logging.debug(f"Kernel electrons type: {type(electron_num)}, value: {electron_num}")
+        
+        # Try running the kernel with initial parameters
+        result = cudaq.sample(kernel, init_params.tolist())  # Convert to list for validation
+        logging.debug(f"Ansatz validation successful. Sample result: {result}")
+        return True
+    except Exception as e:
+        logging.error(f"Ansatz validation failed: {str(e)}")
+        return False
+
+# ----------------------------------------------------------
+# New or updated utility function for generating a Hamiltonian
+# ----------------------------------------------------------
+def create_molecular_hamiltonian(geometry: list[tuple[str, tuple[float, float, float]]],
+                                 basis: str,
+                                 multiplicity: int,
+                                 charge: int) -> cudaq.SpinOperator:
+    """
+    Create a SpinOperator for a given molecule using PySCF + OpenFermion + CUDA-Q.
+
+    Parameters
+    ----------
+    geometry : list of (str, (float, float, float)))
+        List describing each atom, e.g. [('H', (0.,0.,0.)), ('H',(0.,0.,bond_length))]
+    basis : str
+        Basis set, e.g. "sto-3g"
+    multiplicity : int
+        Spin multiplicity
+    charge : int
+        Net charge of the molecule
+
+    Returns
+    -------
+    cudaq.SpinOperator
+        The qubit Hamiltonian in CUDA-Q spin-operator form.
+    """
+    try:
+        # Use PySCF + OpenFermion to build a molecular object
+        molecule = openfermionpyscf.run_pyscf(
+            openfermion.MolecularData(geometry, basis, multiplicity, charge)
+        )
+
+        # Construct the fermionic Hamiltonian
+        molecular_hamiltonian = molecule.get_molecular_hamiltonian()
+        fermion_hamiltonian = get_fermion_operator(molecular_hamiltonian)
+        qubit_hamiltonian = jordan_wigner(fermion_hamiltonian)
+
+        # Convert to CUDA-Q SpinOperator
+        spin_op = cudaq.SpinOperator(qubit_hamiltonian)
+        return spin_op
+    except Exception as e:
+        logging.error(f"Failed to create molecular Hamiltonian: {str(e)}")
+        raise
+
+# ----------------------------------------------------------
+# New or updated function for generating a UCCSD ansatz kernel
+# ----------------------------------------------------------
+@cudaq.kernel
+def kernel(qubit_num: int, electron_num: int, thetas: list[float]):
+    """
+    Generate a UCCSD ansatz kernel given the number of qubits and electrons.
+
+    Parameters
+    ----------
+    qubit_num : int
+        Number of qubits in the system
+    electron_num : int
+        Number of electrons (which is the same as number of X gates for HF ref.)
+
+    Returns
+    -------
+    A CUDA-Q kernel that accepts parameters for the UCCSD ansatz.
+    """
+    qubits = cudaq.qvector(qubit_num)
+    # Prepare the Hartree-Fock reference: X on each occupied orbital
+    for i in range(electron_num):
+        x(qubits[i]) # Apply X gate to each occupied orbital it is defined in the cuda kernel decorator space
+
+    # Add the UCCSD terms
+    cudaq.kernels.uccsd(qubits, thetas, electron_num, qubit_num)
+
+# define the cost function as the observation of the spin_hamiltonian w.r.t. the ansatz
+def cost_function(kernel, spin_hamiltonian, qubit_count, electron_count, thetas):
+    # The "cost" is the expectation of the spin_operator w.r.t. the ansatz, for these params
+    exp_val = cudaq.observe(kernel, spin_hamiltonian, qubit_count, electron_count, thetas).expectation()
+    
+    logging.info(f"Cost function evaluation: {exp_val:.6f}")
+    return exp_val
+
+def expand_geometry(geometry_template: List[List[Any]], scale_factor: float) -> List[Tuple[str, Tuple[float, float, float]]]:
+    """
+    Expand or contract a molecule's geometry by a scale factor.
+    
+    Args:
+        geometry_template: List of [atom_symbol, [x, y, z]] coordinates
+        scale_factor: Factor to scale the geometry by (1.0 = no change)
+    
+    Returns:
+        List of (atom_symbol, (x, y, z)) tuples with scaled coordinates
+    """
+    scaled_geometry = []
+    # Find the center of mass (assuming equal weights for simplicity)
+    coords = np.array([coord for _, coord in geometry_template])
+    center = np.mean(coords, axis=0)
+    
+    for atom_symbol, coord in geometry_template:
+        # Convert coord to numpy array for vector operations
+        coord = np.array(coord)
+        # Calculate vector from center
+        vec = coord - center
+        # Scale the vector and add back to center
+        scaled_coord = center + vec * scale_factor
+        # Convert back to tuple
+        scaled_geometry.append((atom_symbol, tuple(scaled_coord)))
+    
+    return scaled_geometry
+
+# ----------------------------------------------------------
+# Edits in run_vqe_simulation to use the new approach
+# and a CUDA-Q optimizer
+# ----------------------------------------------------------
+@spaces.GPU(duration=20)
+def run_vqe_simulation(molecule_data: Dict[str, Any],
+                      scale_factor: float) -> Dict[str, Any]:
+    """
+    Run a VQE simulation using CUDA-Q.
+
+    Parameters
+    ----------
+    molecule_data : Dict[str, Any]
+        Dictionary containing all molecule metadata and parameters
+    scale_factor : float
+        Factor to scale the molecule geometry by (1.0 = original size)
+
+    Returns
+    -------
+    Dict[str, Any]
+        The dictionary has the following keys:
+        - 'final_energy': (float) the final VQE energy
+        - 'parameters': (list) the optimized ansatz parameters
+        - 'success': (bool) indicates if optimization converged
+        - 'iterations': (int) the maximum number of optimizer iterations
+        - 'history': (list) energy values from each iteration
+        - 'message': (str) status or error message
+    """
+    logging.info(f"Starting VQE simulation for {molecule_data['name']} with scale factor {scale_factor}")
+
+    # Ensure the correct GPU/CPU target is set
+    setup_target()
+
+    # Create scaled geometry
+    geometry = expand_geometry(molecule_data['geometry_template'], scale_factor)
+    logging.info(f"Created scaled geometry with factor = {scale_factor}")
+
+    spin_hamiltonian = create_molecular_hamiltonian(
+        geometry=geometry,
+        basis=molecule_data['basis'],
+        multiplicity=molecule_data['multiplicity'],
+        charge=molecule_data['charge']
+    )
+
+    # Log debugging info about the Hamiltonian
+    term_count = spin_hamiltonian.get_term_count()
+    logging.debug(f"Hamiltonian has {term_count} terms.")
+    logging.debug(f"Hamiltonian details:\n{spin_hamiltonian}")
+
+    # Create the UCCSD ansatz kernel
+    qubit_count = 2 * molecule_data['spatial_orbitals']
+    electron_count = molecule_data['electron_count']
+    optimizer_max_iterations = 10
+
+    # Compute how many UCCSD parameters we need to optimize
+    parameter_count = cudaq.kernels.uccsd_num_parameters(electron_count, qubit_count)
+    logging.info(f"Number of UCCSD parameters to optimize = {parameter_count}")
+
+    # Initialize the parameters for the UCCSD ansatz
+    thetas0 = np.random.normal(0, 1, parameter_count)
+    logging.info(f"Initial parameters: {thetas0}")
+
+    # Create a wrapper function that only takes the parameters to optimize
+    def objective_wrapper(thetas):
+        return cost_function(kernel, spin_hamiltonian, qubit_count, electron_count, thetas)
+
+    # Define the callback function that uses the wrapper
+    exp_vals = []
+    def callback(xk):
+        val = objective_wrapper(xk)
+        exp_vals.append(val)
+        return True
+
+    try:
+        # Test the wrapper function before optimization
+        test_val = objective_wrapper(thetas0)
+        logging.info(f"Debug cost check (initial params): {test_val:.6f}")
+
+        if not np.isfinite(test_val):
+            logging.warning("Debug cost check returned non-finite value. The optimizer may fail.")
+
+        # Perform the VQE optimization using the wrapper function
+        result = minimize(objective_wrapper,
+                        thetas0,
+                        method='COBYLA',
+                        callback=callback,
+                        options={'maxiter': optimizer_max_iterations})
+
+        energy = result.fun
+        parameters = result.x
+        success = result.success
+        message = "VQE optimization completed successfully."
+        
+    except Exception as e:
+        logging.error(f"VQE optimization failed: {str(e)}")
+        energy = float("inf")
+        parameters = []
+        success = False
+        message = f"VQE optimization failed: {str(e)}"
+
+    logging.info(message)
+    logging.debug(f"Final energy: {energy}")
+    logging.debug(f"Optimized parameters: {parameters}")
+
+    # Build the results dictionary
+    results = {
+        "final_energy": float(energy),
+        "parameters": list(parameters),
+        "success": success,
+        "iterations": optimizer_max_iterations,
+        "history": exp_vals,
+        "message": message,
+        "parameter_count": parameter_count,
+        "hamiltonian_terms": term_count
+    }
+    return results

requirements.txt

@@ -0,0 +1,31 @@
+# requirements.txt
+# Lists the essential Python dependencies for the CUDA-Q Gradio VQE demo.
+
+# Core packages with specific versions
+numpy==1.24.3
+scipy==1.10.1
+
+# Gradio and visualization components
+gradio==4.44.1
+gradio_molgallery3d>=0.0.4
+
+# Plotting and visualization libraries
+plotly==5.18.0
+bokeh==3.2.2
+matplotlib==3.7.1
+rdkit==2023.09.1
+
+# ASE for molecular geometry handling
+ase==3.22.1
+
+# CUDA-Q libraries for quantum simulation
+cudaq
+cudaq_solvers
+
+# Optional extras for quantum chemistry
+pyscf==2.6.2
+openfermion==1.6.1
+openfermionpyscf==0.5
+
+# (Optional) Qiskit if desired
+# qiskit>=0.42.0 

visualization.py

@@ -0,0 +1,189 @@
+"""
+visualization.py
+Routines for plotting VQE results and molecular visualization using Plotly and MolGallery3D
+"""
+
+import plotly.graph_objects as go
+import numpy as np
+import logging
+from rdkit import Chem
+from rdkit.Chem import AllChem
+from gradio_molgallery import MolGallery3D
+import json
+
+# Configure logging
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.INFO)
+
+def format_molecule_params(molecule_data: dict) -> str:
+    """
+    Format molecule parameters into a readable HTML string.
+    
+    Args:
+        molecule_data: Dictionary containing molecule parameters
+    Returns:
+        HTML formatted string of parameters
+    """
+    try:
+        # Create a formatted HTML string with molecule parameters
+        params_html = f"""
+        <div style='font-family: monospace; padding: 10px;'>
+            <h3>Molecule Parameters:</h3>
+            <ul style='list-style-type: none; padding-left: 0;'>
+                <li><b>Name:</b> {molecule_data.get('name', 'N/A')} - {molecule_data.get('formula', 'N/A')}</li>
+                <li><b>Electrons:</b> {molecule_data.get('electron_count', 'N/A')}</li>
+                <li><b>Basis:</b> {molecule_data.get('basis', 'N/A')}, <b>Spatial Orbitals:</b> {molecule_data.get('spatial_orbitals', 'N/A')}</li>
+                <li><b>Charge:</b> {molecule_data.get('charge', 'N/A')}</li>
+            </ul>
+        </div>
+        """
+        return params_html
+    except Exception as e:
+        logger.error(f"Error formatting molecule parameters: {e}")
+        return "<div>Error: Could not format molecule parameters</div>"
+
+def plot_convergence(results):
+    """
+    Create a convergence plot from VQE iteration history using Plotly.
+    Returns Plotly figure
+    
+    Args:
+        results: Dictionary containing VQE results including history of energy values,
+                or list of energy values directly
+    """
+    logger.info(f"Plotting convergence with results type: {type(results)}")
+    
+    # Extract iteration numbers and energies
+    iterations = []
+    energies = []
+    
+    # Handle different input formats
+    if isinstance(results, dict):
+        history = results.get('history', [])
+    else:
+        history = results
+        
+    logger.info(f"History type: {type(history)}, length: {len(history)}")
+    
+    # Handle both dictionary entries and direct energy values
+    for i, entry in enumerate(history):
+        if isinstance(entry, dict):
+            # Handle dictionary format
+            try:
+                iterations.append(entry.get('iteration', i))
+                energies.append(entry['energy'])
+            except Exception as e:
+                logger.warning(f"Skipping invalid entry {i}: {str(e)}")
+                continue
+        else:
+            # Handle direct energy values
+            try:
+                iterations.append(i)
+                energies.append(float(entry))
+            except (ValueError, TypeError) as e:
+                logger.warning(f"Skipping invalid entry {i}: {str(e)}")
+                continue
+    
+    if not iterations or not energies:
+        raise ValueError("No valid iteration data found in results")
+    
+    # Create Plotly figure
+    fig = go.Figure()
+    
+    # Add energy convergence line
+    fig.add_trace(go.Scatter(
+        x=iterations,
+        y=energies,
+        mode='lines+markers',
+        name='Energy',
+        line=dict(color='blue')
+    ))
+    
+    # Add final energy line if available
+    final_energy = None
+    if isinstance(results, dict) and 'final_energy' in results:
+        try:
+            final_energy = float(results['final_energy'])
+        except (ValueError, TypeError):
+            pass
+    
+    if final_energy is None and energies:
+        final_energy = energies[-1]
+        
+    if final_energy is not None:
+        fig.add_hline(
+            y=final_energy,
+            line_dash="dash",
+            line_color="red",
+            annotation_text=f"Final Energy: {final_energy:.6f}",
+            annotation_position="bottom right"
+        )
+    
+    # Update layout
+    fig.update_layout(
+        title='VQE Convergence',
+        xaxis_title='Iteration',
+        yaxis_title='Energy (Hartree)',
+        showlegend=True,
+        hovermode='x',
+        width=800,
+        height=600
+    )
+    
+    return fig
+
+def create_molecule_viewer(molecule_id: str, scale_factor: float) -> MolGallery3D:
+    """
+    Create a 3D visualization of the molecule using MolGallery3D and RDKit.
+    Returns MolGallery3D component for Gradio display
+    
+    Args:
+        molecule_id: Molecule identifier (e.g., "H2")
+        scale_factor: Bond length scaling factor (1.0 = original size)
+    """
+    logger.info(f"Creating 3D view for {molecule_id} with scale_factor={scale_factor}")
+    
+    try:
+        # Load molecule data
+        with open('molecules.json', 'r') as f:
+            molecules = json.load(f)
+            
+        if molecule_id not in molecules:
+            logger.error(f"Unknown molecule {molecule_id}")
+            return None
+        
+        molecule_data = molecules[molecule_id]
+        
+        # Create molecule using SMILES
+        mol = Chem.MolFromSmiles(molecule_data['smiles'])
+        if mol is None:
+            logger.error(f"Could not create molecule from SMILES: {molecule_data['smiles']}")
+            return None
+        
+        mol = AllChem.AddHs(mol)
+        AllChem.EmbedMolecule(mol, randomSeed=42)  # Use fixed seed for consistency
+        
+        # Scale the molecule coordinates
+        conf = mol.GetConformer()
+        positions = conf.GetPositions()
+        centroid = np.mean(positions, axis=0)
+        
+        for i in range(mol.GetNumAtoms()):
+            pos = positions[i]
+            scaled_pos = centroid + (pos - centroid) * scale_factor
+            conf.SetAtomPosition(i, scaled_pos)
+        
+        # Create the MolGallery3D component
+        gallery = MolGallery3D(
+            columns=1,
+            height=400,
+            label=f"{molecule_data.get('name', molecule_id)} (Scale: {scale_factor:.2f})",
+            automatic_rotation=True
+        )
+        
+        logger.info("Created MolGallery3D component")
+        return [mol]  # Return the molecule as a list as expected by MolGallery3D
+        
+    except Exception as e:
+        logger.error(f"Failed to create molecule viewer: {e}")
+        return None