Docs preview for PR #1027.

pr-1027/_sources/specification/cudaq/algorithmic_primitives.rst.txt

@@ -132,6 +132,72 @@ of an NOT operation. The :code:`sample_result` returned for this sampling
 tasks contains the default :code:`__global__` register as well as the user 
 specified :code:`reg1` register. 
 
+The order of the bits in the :code:`__global__` register will depend on how your
+kernel is written:
+
+1. If no measurements appear in the kernel, or if any quantum operations occur
+   after the final measurements in the kernel, then the :code:`__global__`
+   register is formed with implicit measurements being added for *all* the
+   qubits defined in the kernel, and the measurements all occur at the end of
+   the kernel. The order of the bits in the bitstring corresponds to the *order
+   that the qubits were defined in the kernel*.  That is - the :code:`[0]`
+   element in the :code:`__global__` bitstring corresponds with the first
+   declared qubit in the kernel. For example,
+
+   .. code-block:: cpp
+
+       auto kernel = []() __qpu__ {
+         cudaq::qubit a, b;
+         x(a);
+       };
+       cudaq::sample(kernel).dump();
+
+   should produce 
+
+   .. code-block:: bash 
+
+       { 
+         __global__ : { 10:1000 }
+       }
+
+2. Conversely, if any measurements appear in the kernel and the final quantum
+   operation of the kernel is a measurement, then the :code:`__global__`
+   register is formed such that the order of the bits in the bitstring
+   corresponds to the *order of the measurements performed in the kernel*.
+   However, similar to #1, the values of the sampled qubits always correspond to
+   the values *at the end of the kernel execution*. That is - if a qubit is
+   measured in the middle of a kernel and subsequent operations change the state
+   of the qubit, the qubit will be implicitly re-measured at the end of the
+   kernel, and that re-measured value is the value that will appear in the
+   :code:`__global__` register. For example,
+
+   .. code-block:: cpp
+
+       auto kernel = []() __qpu__ {
+         cudaq::qubit a, b;
+         x(a);
+         mz(b);
+         mz(a);
+       };
+       cudaq::sample(kernel).dump();
+
+   should produce 
+
+   .. code-block:: bash 
+
+       { 
+         __global__ : { 01:1000 }
+       }
+
+.. note::
+
+  If you don't specify any measurements in your kernel and allow the :code:`nvq++`
+  compiler to perform passes that introduce ancilla qubits into your kernel, it
+  may be difficult to discern which qubits are the ancilla qubits vs which ones
+  are your qubits. In this case, it is recommend that you provide explicit
+  measurements in your kernel in order to only receive measurements from your
+  qubits and silently discard the measurements from the ancillary qubits.
+
 The API exposed by the :code:`sample_result` data type allows one to extract
 the information contained at a variety of levels and for each available 
 register name. One can get the number of times a bit string was observed via 

pr-1027/api/languages/cpp_api.html

@@ -1223,6 +1223,17 @@ <h2>Common<a class="headerlink" href="#common" title="Permalink to this heading"
 <dd><p>Nullary constructor. </p>
 </dd></dl>
 
+<dl class="cpp function">
+<dt class="sig sig-object cpp" id="_CPPv4N5cudaq13sample_result13sample_resultERR15ExecutionResult">
+<span class="target" id="classcudaq_1_1sample__result_1ab6d5dd37a325832f89d8ee70130d6b80"></span><span class="sig-name descname"><span class="n"><span class="pre">sample_result</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#_CPPv4N5cudaq15ExecutionResultE" title="cudaq::ExecutionResult"><span class="n"><span class="pre">ExecutionResult</span></span></a><span class="w"> </span><span class="p"><span class="pre">&amp;</span></span><span class="p"><span class="pre">&amp;</span></span><span class="n sig-param"><span class="pre">result</span></span><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv4N5cudaq13sample_result13sample_resultERR15ExecutionResult" title="Permalink to this definition">¶</a><br /></dt>
+<dd><p>The constructor, sets the <strong>global</strong> sample result. </p>
+<dl class="field-list simple">
+<dt class="field-odd">Parameters<span class="colon">:</span></dt>
+<dd class="field-odd"><p><strong>result</strong> – </p>
+</dd>
+</dl>
+</dd></dl>
+
 <dl class="cpp function">
 <dt class="sig sig-object cpp" id="_CPPv4N5cudaq13sample_result13sample_resultER15ExecutionResult">
 <span class="target" id="classcudaq_1_1sample__result_1a3435574a1e7adc5b540aa13649e4c202"></span><span class="sig-name descname"><span class="n"><span class="pre">sample_result</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#_CPPv4N5cudaq15ExecutionResultE" title="cudaq::ExecutionResult"><span class="n"><span class="pre">ExecutionResult</span></span></a><span class="w"> </span><span class="p"><span class="pre">&amp;</span></span><span class="n sig-param"><span class="pre">result</span></span><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv4N5cudaq13sample_result13sample_resultER15ExecutionResult" title="Permalink to this definition">¶</a><br /></dt>
@@ -1493,7 +1504,7 @@ <h2>Common<a class="headerlink" href="#common" title="Permalink to this heading"
 <dl class="field-list simple">
 <dt class="field-odd">Parameters<span class="colon">:</span></dt>
 <dd class="field-odd"><ul class="simple">
-<li><p><strong>idx</strong> – Vector of indices such that newBitStr(:) = oldBitStr(idx(:)) </p></li>
+<li><p><strong>idx</strong> – Vector of indices such that <code class="docutils literal notranslate"><span class="pre">newBitStr(:)</span> <span class="pre">=</span> <span class="pre">oldBitStr(idx(:))</span></code> </p></li>
 <li><p><strong>registerName</strong> – register name to process (defaults to global) </p></li>
 </ul>
 </dd>

pr-1027/api/languages/python_api.html

@@ -3626,7 +3626,7 @@ <h2>Data Types<a class="headerlink" href="#data-types" title="Permalink to this
 <em class="property"><span class="pre">static</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">random</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#cudaq.SpinOperator.random" title="Permalink to this definition">¶</a></dt>
 <dd><dl class="py function">
 <dt class="sig sig-object py">
-<span class="sig-name descname"><span class="pre">random</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">qubit_count</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.12)"><span class="pre">int</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">term_count</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.12)"><span class="pre">int</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">seed</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.12)"><span class="pre">int</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">2135729819</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference internal" href="#cudaq.SpinOperator" title="cudaq.SpinOperator"><span class="pre">cudaq.SpinOperator</span></a></span></span></dt>
+<span class="sig-name descname"><span class="pre">random</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">qubit_count</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.12)"><span class="pre">int</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">term_count</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.12)"><span class="pre">int</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">seed</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.12)"><span class="pre">int</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">2512440913</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference internal" href="#cudaq.SpinOperator" title="cudaq.SpinOperator"><span class="pre">cudaq.SpinOperator</span></a></span></span></dt>
 <dd></dd></dl>
 
 <p>Return a random <a class="reference internal" href="#cudaq.SpinOperator" title="cudaq.SpinOperator"><code class="xref py py-class docutils literal notranslate"><span class="pre">SpinOperator</span></code></a> on the given number of qubits (<code class="code docutils literal notranslate"><span class="pre">qubit_count</span></code>) and composed of the given number of terms (<code class="code docutils literal notranslate"><span class="pre">term_count</span></code>). An optional seed value may also be provided.</p>

pr-1027/genindex.html

@@ -1085,7 +1085,7 @@ <h2 id="C">C</h2>
 </li>
       <li><a href="api/languages/cpp_api.html#_CPPv4N5cudaq13sample_result7reorderERKNSt6vectorINSt6size_tEEEKNSt11string_viewE">cudaq::sample_result::reorder (C++ function)</a>
 </li>
-      <li><a href="api/languages/cpp_api.html#_CPPv4N5cudaq13sample_result13sample_resultER15ExecutionResult">cudaq::sample_result::sample_result (C++ function)</a>, <a href="api/languages/cpp_api.html#_CPPv4N5cudaq13sample_result13sample_resultERK13sample_result">[1]</a>, <a href="api/languages/cpp_api.html#_CPPv4N5cudaq13sample_result13sample_resultERNSt6vectorI15ExecutionResultEE">[2]</a>, <a href="api/languages/cpp_api.html#_CPPv4N5cudaq13sample_result13sample_resultEdRNSt6vectorI15ExecutionResultEE">[3]</a>, <a href="api/languages/cpp_api.html#_CPPv4N5cudaq13sample_result13sample_resultEv">[4]</a>
+      <li><a href="api/languages/cpp_api.html#_CPPv4N5cudaq13sample_result13sample_resultER15ExecutionResult">cudaq::sample_result::sample_result (C++ function)</a>, <a href="api/languages/cpp_api.html#_CPPv4N5cudaq13sample_result13sample_resultERK13sample_result">[1]</a>, <a href="api/languages/cpp_api.html#_CPPv4N5cudaq13sample_result13sample_resultERNSt6vectorI15ExecutionResultEE">[2]</a>, <a href="api/languages/cpp_api.html#_CPPv4N5cudaq13sample_result13sample_resultERR15ExecutionResult">[3]</a>, <a href="api/languages/cpp_api.html#_CPPv4N5cudaq13sample_result13sample_resultEdRNSt6vectorI15ExecutionResultEE">[4]</a>, <a href="api/languages/cpp_api.html#_CPPv4N5cudaq13sample_result13sample_resultEv">[5]</a>
 </li>
       <li><a href="api/languages/cpp_api.html#_CPPv4N5cudaq13sample_result9serializeEv">cudaq::sample_result::serialize (C++ function)</a>
 </li>

pr-1027/specification/cudaq/algorithmic_primitives.html

@@ -548,6 +548,67 @@ <h1><span class="section-number">12. </span>Quantum Algorithmic Primitives<a cla
 of an NOT operation. The <code class="code docutils literal notranslate"><span class="pre">sample_result</span></code> returned for this sampling
 tasks contains the default <code class="code docutils literal notranslate"><span class="pre">__global__</span></code> register as well as the user
 specified <code class="code docutils literal notranslate"><span class="pre">reg1</span></code> register.</p>
+<p>The order of the bits in the <code class="code docutils literal notranslate"><span class="pre">__global__</span></code> register will depend on how your
+kernel is written:</p>
+<ol class="arabic">
+<li><p>If no measurements appear in the kernel, or if any quantum operations occur
+after the final measurements in the kernel, then the <code class="code docutils literal notranslate"><span class="pre">__global__</span></code>
+register is formed with implicit measurements being added for <em>all</em> the
+qubits defined in the kernel, and the measurements all occur at the end of
+the kernel. The order of the bits in the bitstring corresponds to the <em>order
+that the qubits were defined in the kernel</em>.  That is - the <code class="code docutils literal notranslate"><span class="pre">[0]</span></code>
+element in the <code class="code docutils literal notranslate"><span class="pre">__global__</span></code> bitstring corresponds with the first
+declared qubit in the kernel. For example,</p>
+<div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="k">auto</span><span class="w"> </span><span class="n">kernel</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[]()</span><span class="w"> </span><span class="n">__qpu__</span><span class="w"> </span><span class="p">{</span>
+<span class="w">  </span><span class="n">cudaq</span><span class="o">::</span><span class="n">qubit</span><span class="w"> </span><span class="n">a</span><span class="p">,</span><span class="w"> </span><span class="n">b</span><span class="p">;</span>
+<span class="w">  </span><span class="n">x</span><span class="p">(</span><span class="n">a</span><span class="p">);</span>
+<span class="p">};</span>
+<span class="n">cudaq</span><span class="o">::</span><span class="n">sample</span><span class="p">(</span><span class="n">kernel</span><span class="p">).</span><span class="n">dump</span><span class="p">();</span>
+</pre></div>
+</div>
+<p>should produce</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="o">{</span>
+<span class="w">  </span>__global__<span class="w"> </span>:<span class="w"> </span><span class="o">{</span><span class="w"> </span><span class="m">10</span>:1000<span class="w"> </span><span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+</div>
+</li>
+<li><p>Conversely, if any measurements appear in the kernel and the final quantum
+operation of the kernel is a measurement, then the <code class="code docutils literal notranslate"><span class="pre">__global__</span></code>
+register is formed such that the order of the bits in the bitstring
+corresponds to the <em>order of the measurements performed in the kernel</em>.
+However, similar to #1, the values of the sampled qubits always correspond to
+the values <em>at the end of the kernel execution</em>. That is - if a qubit is
+measured in the middle of a kernel and subsequent operations change the state
+of the qubit, the qubit will be implicitly re-measured at the end of the
+kernel, and that re-measured value is the value that will appear in the
+<code class="code docutils literal notranslate"><span class="pre">__global__</span></code> register. For example,</p>
+<div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="k">auto</span><span class="w"> </span><span class="n">kernel</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[]()</span><span class="w"> </span><span class="n">__qpu__</span><span class="w"> </span><span class="p">{</span>
+<span class="w">  </span><span class="n">cudaq</span><span class="o">::</span><span class="n">qubit</span><span class="w"> </span><span class="n">a</span><span class="p">,</span><span class="w"> </span><span class="n">b</span><span class="p">;</span>
+<span class="w">  </span><span class="n">x</span><span class="p">(</span><span class="n">a</span><span class="p">);</span>
+<span class="w">  </span><span class="n">mz</span><span class="p">(</span><span class="n">b</span><span class="p">);</span>
+<span class="w">  </span><span class="n">mz</span><span class="p">(</span><span class="n">a</span><span class="p">);</span>
+<span class="p">};</span>
+<span class="n">cudaq</span><span class="o">::</span><span class="n">sample</span><span class="p">(</span><span class="n">kernel</span><span class="p">).</span><span class="n">dump</span><span class="p">();</span>
+</pre></div>
+</div>
+<p>should produce</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="o">{</span>
+<span class="w">  </span>__global__<span class="w"> </span>:<span class="w"> </span><span class="o">{</span><span class="w"> </span><span class="m">01</span>:1000<span class="w"> </span><span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+</div>
+</li>
+</ol>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<p>If you don’t specify any measurements in your kernel and allow the <code class="code docutils literal notranslate"><span class="pre">nvq++</span></code>
+compiler to perform passes that introduce ancilla qubits into your kernel, it
+may be difficult to discern which qubits are the ancilla qubits vs which ones
+are your qubits. In this case, it is recommend that you provide explicit
+measurements in your kernel in order to only receive measurements from your
+qubits and silently discard the measurements from the ancillary qubits.</p>
+</div>
 <p>The API exposed by the <code class="code docutils literal notranslate"><span class="pre">sample_result</span></code> data type allows one to extract
 the information contained at a variety of levels and for each available
 register name. One can get the number of times a bit string was observed via

pr-1027/sphinx/examples/cpp/algorithms/amplitude_estimation.cpp

@@ -58,7 +58,7 @@ int num_oracles(std::vector<int> &vec, const int N_shots) {
 } // namespace mlae
 
 struct statePrep_A {
-  void operator()(cudaq::qreg<> &q, const double bmax) __qpu__ {
+  void operator()(cudaq::qvector<> &q, const double bmax) __qpu__ {
 
     int n = q.size();
     // all qubits sans auxiliary
@@ -75,7 +75,7 @@ struct statePrep_A {
 };
 
 struct S_0 {
-  void operator()(cudaq::qreg<> &q) __qpu__ {
+  void operator()(cudaq::qvector<> &q) __qpu__ {
 
     auto ctrl_qubits = q.front(q.size() - 1);
     auto &last_qubit = q.back();
@@ -93,7 +93,7 @@ struct run_circuit {
   auto operator()(const int n_qubits, const int n_itrs,
                   const double bmax) __qpu__ {
 
-    cudaq::qreg q(n_qubits + 1); // last is auxiliary
+    cudaq::qvector q(n_qubits + 1); // last is auxiliary
     auto &last_qubit = q.back();
 
     // State preparation

pr-1027/sphinx/examples/cpp/algorithms/bernstein_vazirani.cpp

@@ -34,7 +34,7 @@ std::bitset<nrOfBits> random_bits(int seed) {
 
 template <int nrOfBits>
 struct oracle {
-  auto operator()(std::bitset<nrOfBits> bitvector, cudaq::qspan<> qs,
+  auto operator()(std::bitset<nrOfBits> bitvector, cudaq::qview<> qs,
                   cudaq::qubit &aux) __qpu__ {
 
     for (size_t i = 0; i < nrOfBits; i++) {
@@ -49,7 +49,7 @@ template <int nrOfBits>
 struct bernstein_vazirani {
   auto operator()(std::bitset<nrOfBits> bitvector) __qpu__ {
 
-    cudaq::qreg<nrOfBits> qs;
+    cudaq::qarray<nrOfBits> qs;
     cudaq::qubit aux;
     h(aux);
     z(aux);

pr-1027/sphinx/examples/cpp/algorithms/grover.cpp

@@ -5,7 +5,7 @@
 
 #include <cudaq.h>
 
-__qpu__ void reflect_about_uniform(cudaq::qspan<> q) {
+__qpu__ void reflect_about_uniform(cudaq::qview<> q) {
   auto ctrlQubits = q.front(q.size() - 1);
   auto &lastQubit = q.back();
 
@@ -20,7 +20,7 @@ struct run_grover {
   template <typename CallableKernel>
   __qpu__ auto operator()(const int n_qubits, const int n_iterations,
                           CallableKernel &&oracle) {
-    cudaq::qreg q(n_qubits);
+    cudaq::qvector q(n_qubits);
     h(q);
     for (int i = 0; i < n_iterations; i++) {
       oracle(q);
@@ -31,7 +31,7 @@ struct run_grover {
 };
 
 struct oracle {
-  void operator()(cudaq::qreg<> &q) __qpu__ {
+  void operator()(cudaq::qvector<> &q) __qpu__ {
     z<cudaq::ctrl>(q[0], q[2]);
     z<cudaq::ctrl>(q[1], q[2]);
   }