Docs preview for PR #2691.

Author: cuda-quantum-bot

pr-2691/_sources/using/backends/hardware/neutralatom.rst.txt

@@ -139,8 +139,11 @@ The currently available Pasqal QPUs are analog quantum computers, and one, named
 portal.
 
 In order to access Pasqal's devices you need an account for `Pasqal's cloud platform <https://portal.pasqal.cloud>`__
-and an active project. Although a different interface, `Pasqal's Pulser library <https://pulser.readthedocs.io/en/latest/>`__, is a good
-resource for getting started with analog neutral atom quantum computing. For support you can also use `Pasqal Community <https://community.pasqal.com/>`__.
+and an active project. Please see our `cloud documentation <https://docs.pasqal.cloud/cloud/>`__ for more details if needed.
+
+Although a different SDK, `Pasqal's Pulser library <https://pulser.readthedocs.io/en/latest/>`__, is a good
+resource for getting started with analog neutral atom quantum computing.
+For support you can also join the `Pasqal Community <https://community.pasqal.com/>`__.
 
 
 .. _pasqal-backend:
@@ -161,7 +164,8 @@ For example from Python one can use the `pasqal-cloud package <https://github.co
         password=os.environ.get('PASQAL_PASSWORD', None)
     )
 
-    token = sdk._client.authenticator.token_provider.get_token()
+    token = sdk.user_token()
+
     os.environ['PASQAL_AUTH_TOKEN'] = str(token)
     os.environ['PASQAL_PROJECT_ID'] = 'your project id'
 
@@ -184,10 +188,25 @@ can be controlled with the ``cudaq::set_target()`` function.
     cudaq.set_target('pasqal')
 
 
+This accepts an optional argument, ``machine``, which is used in the cloud platform to
+select the corresponding Pasqal QPU or emulator to execute on.
+See the `Pasqal cloud portal <https://portal.pasqal.cloud/>`__ for an up to date list.
+The default value is ``EMU_MPS`` which is an open-source tensor network emulator based on the
+Matrix Product State formalism running in Pasqal's cloud platform. You can see the
+documentation for the publicly accessible emulator `here <https://pasqal-io.github.io/emulators/latest/emu_mps/>`__.
+
+To target the QPU use the FRESNEL machine name. Note that there are restrictions
+regarding the values of the pulses as well as the register layout. We invite you to
+consult our `documentation <https://docs.pasqal.com/cloud/fresnel-job>`__. Note that
+the CUDA-Q integration currently only works with `arbitrary layouts <https://docs.pasqal.com/cloud/fresnel-job/#arbitrary-layouts>`__
+which are implemented with automatic calibration for less than 30 qubits. For jobs
+larger than 30 qubits please use the `atom_sites` to define the layout, and use the
+`atom_filling` to select sites as filled or not filled in order to define the register.
+
 Due to the nature of the underlying hardware, this target only supports the 
 ``evolve`` and ``evolve_async`` APIs.
-The `hamiltonian` must be an `Operator` of the type `RydbergHamiltonian`. Only 
-other parameters supported are `schedule` (mandatory) and `shots_count` (optional).
+The `hamiltonian` must be an `Operator` of the type `RydbergHamiltonian`. The only
+other supported parameters are `schedule` (mandatory) and `shots_count` (optional).
 
 For example,
 

pr-2691/applications/python/adapt_qaoa.html

@@ -783,7 +783,7 @@ <h1>ADAPT-QAOA algorithm<a class="headerlink" href="#ADAPT-QAOA-algorithm" title
 parameter</p>
 <p>3- Optimize all parameters currently in the Ansatz <span class="math notranslate nohighlight">\(\beta_m, \gamma_m = 1, 2, ...k\)</span> such that <span class="math notranslate nohighlight">\(\braket{\psi (k)|H_C|\psi(k)}\)</span> is minimized, and return to the second step.</p>
 <p>Below is a schematic representation of the ADAPT-QAOA algorithm explained above.</p>
-<div><p><img alt="0843aea15ee44e7dab227e95b2287b01" class="no-scaled-link" src="../../_images/adapt-qaoa.png" style="width: 600px;" /></p>
+<div><p><img alt="ce457d496ff64a2fb2eda01f62666ddb" class="no-scaled-link" src="../../_images/adapt-qaoa.png" style="width: 600px;" /></p>
 </div><div class="nbinput nblast docutils container">
 <div class="prompt highlight-none notranslate"><div class="highlight"><pre><span></span>[ ]:
 </pre></div>

pr-2691/applications/python/deutschs_algorithm.html

@@ -840,7 +840,7 @@ <h2>XOR <span class="math notranslate nohighlight">\(\oplus\)</span><a class="he
 </section>
 <section id="Quantum-oracles">
 <h2>Quantum oracles<a class="headerlink" href="#Quantum-oracles" title="Permalink to this heading">¶</a></h2>
-<p><img alt="763d7815f173412799295a8433b41c16" class="no-scaled-link" src="../../_images/oracle.png" style="width: 300px; height: 150px;" /></p>
+<p><img alt="06d9075282e14060805653effb7f0b37" class="no-scaled-link" src="../../_images/oracle.png" style="width: 300px; height: 150px;" /></p>
 <p>Suppose we have <span class="math notranslate nohighlight">\(f(x): \{0,1\} \longrightarrow \{0,1\}\)</span>. We can compute this function on a quantum computer using oracles which we treat as black box functions that yield the output with an appropriate sequence of logical gates.</p>
 <p>Above you see an oracle represented as <span class="math notranslate nohighlight">\(U_f\)</span> which allows us to transform the state <span class="math notranslate nohighlight">\(\ket{x}\ket{y}\)</span> into:</p>
 <div class="math notranslate nohighlight">
@@ -888,7 +888,7 @@ <h2>Quantum parallelism<a class="headerlink" href="#Quantum-parallelism" title="
 <h2>Deutsch’s Algorithm:<a class="headerlink" href="#Deutsch's-Algorithm:" title="Permalink to this heading">¶</a></h2>
 <p>Our aim is to find out if <span class="math notranslate nohighlight">\(f: \{0,1\} \longrightarrow \{0,1\}\)</span> is a constant or a balanced function? If constant, <span class="math notranslate nohighlight">\(f(0) = f(1)\)</span>, and if balanced, <span class="math notranslate nohighlight">\(f(0) \neq f(1)\)</span>.</p>
 <p>We step through the circuit diagram below and follow the math after the application of each gate.</p>
-<p><img alt="35281ac32ad84616a5eaf09e7466bc67" class="no-scaled-link" src="../../_images/deutsch.png" style="width: 500px; height: 210px;" /></p>
+<p><img alt="1f5362b863664bc284d8007f42a2504d" class="no-scaled-link" src="../../_images/deutsch.png" style="width: 500px; height: 210px;" /></p>
 <div class="math notranslate nohighlight">
 \[\ket{\psi_0}  =  \ket{01}
 \tag{1}\]</div>

pr-2691/applications/python/quantum_transformer.html

@@ -768,9 +768,9 @@ <h1>Optimizing Performance<a class="headerlink" href="#Optimizing-Performance" t
 <section id="Gate-Fusion">
 <h2>Gate Fusion<a class="headerlink" href="#Gate-Fusion" title="Permalink to this heading">¶</a></h2>
 <p>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 <code class="docutils literal notranslate"><span class="pre">nvidia-mgpu</span></code> backend and setting the <code class="docutils literal notranslate"><span class="pre">CUDAQ_MGPU_FUSE</span></code> environment variable, you can select the degree of fusion that takes place. A full command line example would look like <code class="docutils literal notranslate"><span class="pre">CUDAQ_MGPU_FUSE=4</span> <span class="pre">python</span> <span class="pre">c2h2VQE.py</span> <span class="pre">--target</span> <span class="pre">nvidia</span> <span class="pre">--target-option</span> <span class="pre">fp64,mgpu</span></code></p>
-<p><img alt="6b6099816c1142f2a7b938ba56812e2c" src="../../_images/gate-fuse.png" /></p>
+<p><img alt="83deec047f434431852b55ff79b8738b" src="../../_images/gate-fuse.png" /></p>
 <p>The importance of gate fusion is system dependent, but can have a large influence on the performance of the simulation. See the example below for a 24 qubit VQE experiment where changing the fusion level resulted in significant performance boosts.</p>
-<p><img alt="3815aae6a1c341be8ea978bfdba1161d" src="../../_images/gatefusion.png" /></p>
+<p><img alt="fc6b27fe9bdd4001b73760a6a1699be7" src="../../_images/gatefusion.png" /></p>
 </section>
 </section>
 

pr-2691/examples/python/performance_optimizations.html

@@ -6,6 +6,7 @@
 # the terms of the Apache License 2.0 which accompanies this distribution.     #
 # ============================================================================ #
 
+import time
 import os
 import re
 import sys
@@ -42,11 +43,14 @@ def execute(notebook_filename):
     notebook_filename_out = notebook_filename.replace('.ipynb',
                                                       '.nbconvert.ipynb')
     try:
+        start_time = time.perf_counter()
         subprocess.run([
             "jupyter", "nbconvert", "--to", "notebook", "--execute",
             notebook_filename
         ],
                        check=True)
+        elapsed = time.perf_counter() - start_time
+        print(f"Time taken for nbconvert: {elapsed:.2f} seconds")
         os.remove(notebook_filename_out)
         return True
     except subprocess.CalledProcessError:
@@ -98,21 +102,23 @@ def print_results(success, failed, skipped=[]):
 
         notebooks_success, notebooks_skipped, notebooks_failed = (
             [] for i in range(3))
+
+        ## `afqmc`:
+        ## See: https://github.com/NVIDIA/cuda-quantum/issues/2577
+        ## `quantum_transformer`:
+        ## See: https://github.com/NVIDIA/cuda-quantum/issues/2689
+        notebooks_skipped = ['afqmc.ipynb', 'quantum_transformer.ipynb']
+
         for notebook_filename in notebook_filenames:
-            ## See: https://github.com/NVIDIA/cuda-quantum/issues/2577
-            if os.path.basename(notebook_filename) in ["afqmc.ipynb"]:
-                notebooks_skipped.append(notebook_filename)
-            ## See: https://github.com/NVIDIA/cuda-quantum/issues/2689
-            if os.path.basename(notebook_filename) in [
-                    "quantum_transformer.ipynb"
-            ]:
-                notebooks_skipped.append(notebook_filename)
-            elif (validate(notebook_filename, available_backends)):
-                if (execute(notebook_filename)):
-                    notebooks_success.append(notebook_filename)
-                else:
-                    notebooks_failed.append(notebook_filename)
+            base_name = os.path.basename(notebook_filename)
+            if base_name in notebooks_skipped:
+                continue  # Already skipped, no need to re-check
+            if not validate(notebook_filename, available_backends):
+                notebooks_skipped.append(base_name)
+                continue
+            if execute(notebook_filename):
+                notebooks_success.append(notebook_filename)
             else:
-                notebooks_skipped.append(notebook_filename)
+                notebooks_failed.append(notebook_filename)
 
         print_results(notebooks_success, notebooks_failed, notebooks_skipped)

pr-2691/notebook_validation.py

@@ -0,0 +1,140 @@
+/*******************************************************************************
+ * Copyright (c) 2022 - 2025 NVIDIA Corporation & Affiliates.                  *
+ * All rights reserved.                                                        *
+ *                                                                             *
+ * This source code and the accompanying materials are made available under    *
+ * the terms of the Apache License 2.0 which accompanies this distribution.    *
+ ******************************************************************************/
+
+// Compile and run with:
+// ```
+// nvq++ --target dynamics cavity_qed.cpp -o a.out && ./a.out
+// ```
+
+#include "cudaq/algorithms/evolve.h"
+#include "cudaq/dynamics_integrators.h"
+#include "cudaq/operators.h"
+#include "export_csv_helper.h"
+#include <cudaq.h>
+
+int main() {
+
+  // Dimension of our composite quantum system:
+  // subsystem 0 (atom) has 2 levels (ground and excited states).
+  // subsystem 1 (cavity) has 10 levels (Fock states, representing photon number
+  // states).
+  cudaq::dimension_map dimensions{{0, 2}, {1, 10}};
+
+  // For the cavity subsystem 1
+  // We create the annihilation (a) and creation (a+) operators.
+  // These operators lower and raise the photon number, respectively.
+  auto a = cudaq::boson_operator::annihilate(1);
+  auto a_dag = cudaq::boson_operator::create(1);
+
+  // For the atom subsystem 0
+  // We create the annihilation (`sm`) and creation (`sm_dag`) operators.
+  // These operators lower and raise the excitation number, respectively.
+  auto sm = cudaq::boson_operator::annihilate(0);
+  auto sm_dag = cudaq::boson_operator::create(0);
+
+  // Number operators
+  // These operators count the number of excitations.
+  // For the atom (`subsytem` 0) and the cavity (`subsystem` 1) they give the
+  // population in each subsystem.
+  auto atom_occ_op = cudaq::matrix_operator::number(0);
+  auto cavity_occ_op = cudaq::matrix_operator::number(1);
+
+  // Hamiltonian
+  // The `hamiltonian` models the dynamics of the atom-cavity (cavity QED)
+  // system It has 3 parts:
+  // 1. Cavity energy: 2 * pi * photon_number_operator -> energy proportional to
+  // the number of photons.
+  // 2. Atomic energy: 2 * pi * atom_number_operator -> energy proportional to
+  // the atomic excitation.
+  // 3. Atomic-cavity interaction: 2 * pi * 0.25 * (`sm` * a_dag + `sm_dag` * a)
+  // -> represents the exchange of energy between the atom and the cavity. It is
+  // analogous to the Jaynes-Cummings model in cavity QED.
+  auto hamiltonian = (2 * M_PI * cavity_occ_op) + (2 * M_PI * atom_occ_op) +
+                     (2 * M_PI * 0.25 * (sm * a_dag + sm_dag * a));
+
+  // Build the initial state
+  // Atom (sub-system 0) in ground state.
+  // Cavity (sub-system 1) has 5 photons (Fock space).
+  // The overall Hilbert space is 2 * 10 = 20.
+  const int num_photons = 5;
+  std::vector<std::complex<double>> initial_state_vec(20, 0.0);
+  // The index is chosen such that the atom is in the ground state while the
+  // cavity is in the Fock state with 5 photons.
+  initial_state_vec[dimensions[0] * num_photons] = 1;
+
+  // Define a time evolution schedule
+  // We define a time grid from 0 to 10 (in arbitrary time units) with 201 time
+  // steps. This schedule is used by the integrator to simulate the dynamics.
+  const int num_steps = 201;
+  std::vector<double> steps = cudaq::linspace(0.0, 10.0, num_steps);
+  cudaq::schedule schedule(steps);
+
+  // Create a CUDA quantum state
+  // The initial state is converted into a quantum state object for evolution.
+  auto rho0 = cudaq::state::from_data(initial_state_vec);
+
+  // Numerical integrator
+  // Here we choose a Runge-`Kutta` method for time evolution.
+  // `dt` defines the time step for the numerical integration, and order 4
+  // indicates a 4`th` order method.
+  cudaq::integrators::runge_kutta integrator(4, 0.01);
+
+  // Evolve without collapse operators
+  // This evolution is ideal (closed system) dynamics governed solely by the
+  // Hamiltonian. The expectation values of the observables (cavity photon
+  // number and atom excitation probability) are recorded.
+  cudaq::evolve_result evolve_result =
+      cudaq::evolve(hamiltonian, dimensions, schedule, rho0, integrator, {},
+                    {cavity_occ_op, atom_occ_op}, true);
+
+  // Adding dissipation
+  // To simulate a realistic scenario, we introduce decay (dissipation).
+  // Here, the collapse operator represents photon loss from the cavity.
+  constexpr double decay_rate = 0.1;
+  auto collapse_operator = std::sqrt(decay_rate) * a;
+  // Evolve with the collapse operator to incorporate the effect of decay.
+  cudaq::evolve_result evolve_result_decay =
+      cudaq::evolve(hamiltonian, dimensions, schedule, rho0, integrator,
+                    {collapse_operator}, {cavity_occ_op, atom_occ_op}, true);
+
+  // Lambda to extract expectation values for a given observable index
+  // Here, index 0 corresponds to the cavity photon number and index 1
+  // corresponds to the atom excitation probability.
+  auto get_expectation = [](int idx, auto &result) -> std::vector<double> {
+    std::vector<double> expectations;
+
+    auto all_exps = result.get_expectation_values().value();
+    for (auto exp_vals : all_exps) {
+      expectations.push_back((double)exp_vals[idx]);
+    }
+    return expectations;
+  };
+
+  // Retrieve expectation values from both the ideal and decaying `evolutions`.
+  auto ideal_result0 = get_expectation(0, evolve_result);
+  auto ideal_result1 = get_expectation(1, evolve_result);
+  auto decay_result0 = get_expectation(0, evolve_result_decay);
+  auto decay_result1 = get_expectation(1, evolve_result_decay);
+
+  // Export the results to `CSV` files
+  // "cavity_`qed`_ideal_result.`csv`" contains the ideal evolution results.
+  // "cavity_`qed`_decay_result.`csv`" contains the evolution results with
+  // cavity decay.
+  export_csv("cavity_qed_ideal_result.csv", "time", steps,
+             "cavity_photon_number", ideal_result0,
+             "atom_excitation_probability", ideal_result1);
+  export_csv("cavity_qed_decay_result.csv", "time", steps,
+             "cavity_photon_number", decay_result0,
+             "atom_excitation_probability", decay_result1);
+
+  std::cout << "Simulation complete. The results are saved in "
+               "cavity_qed_ideal_result.csv "
+               "and cavity_qed_decay_result.csv files."
+            << std::endl;
+  return 0;
+}