Skip to content

Commit 256b3d2

Browse files
Docs preview for PR #2635.
1 parent 2c5029c commit 256b3d2

File tree

102 files changed

+599
-36
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

102 files changed

+599
-36
lines changed

pr-2635/_sources/using/backends/sims/noisy.rst.txt

+101-2
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,106 @@
1-
2-
Density Matrix Simulators
1+
Noisy Simulators
32
==================================
43

4+
Trajectory Noisy Simulation
5+
++++++++++++++++++++++++++++++++++
6+
7+
The :code:`nvidia` target supports noisy quantum circuit simulations using
8+
quantum trajectory method across all configurations: single GPU, multi-node
9+
multi-GPU, and with host memory. When simulating many trajectories with small
10+
state vectors, the simulation is batched for optimal performance.
11+
12+
When a :code:`noise_model` is provided to CUDA-Q, the :code:`nvidia` target
13+
will incorporate quantum noise into the quantum circuit simulation according
14+
to the noise model specified.
15+
16+
17+
.. tab:: Python
18+
19+
.. literalinclude:: ../../../snippets/python/using/backends/trajectory.py
20+
:language: python
21+
:start-after: [Begin Docs]
22+
23+
.. code:: bash
24+
25+
python3 program.py
26+
{ 00:15 01:92 10:81 11:812 }
27+
28+
.. tab:: C++
29+
30+
.. literalinclude:: ../../../snippets/cpp/using/backends/trajectory.cpp
31+
:language: cpp
32+
:start-after: [Begin Documentation]
33+
34+
.. code:: bash
35+
36+
nvq++ --target nvidia program.cpp [...] -o program.x
37+
./program.x
38+
{ 00:15 01:92 10:81 11:812 }
39+
40+
41+
In the case of bit-string measurement sampling as in the above example, each measurement 'shot' is executed as a trajectory, whereby Kraus operators specified in the noise model are sampled.
42+
43+
For observable expectation value estimation, the statistical error scales asymptotically as :math:`1/\sqrt{N_{trajectories}}`, where :math:`N_{trajectories}` is the number of trajectories.
44+
Hence, depending on the required level of accuracy, the number of trajectories can be specified accordingly.
45+
46+
.. tab:: Python
47+
48+
.. literalinclude:: ../../../snippets/python/using/backends/trajectory_observe.py
49+
:language: python
50+
:start-after: [Begin Docs]
51+
52+
.. code:: bash
53+
54+
python3 program.py
55+
Noisy <Z> with 1024 trajectories = -0.810546875
56+
Noisy <Z> with 8192 trajectories = -0.800048828125
57+
58+
.. tab:: C++
59+
60+
.. literalinclude:: ../../../snippets/cpp/using/backends/trajectory_observe.cpp
61+
:language: cpp
62+
:start-after: [Begin Documentation]
63+
64+
.. code:: bash
65+
66+
nvq++ --target nvidia program.cpp [...] -o program.x
67+
./program.x
68+
Noisy <Z> with 1024 trajectories = -0.810547
69+
Noisy <Z> with 8192 trajectories = -0.800049
70+
71+
72+
The following environment variable options are applicable to the :code:`nvidia` target for trajectory noisy simulation. Any environment variables must be set
73+
prior to setting the target.
74+
75+
.. list-table:: **Additional environment variable options for trajectory simulation**
76+
:widths: 20 30 50
77+
78+
* - Option
79+
- Value
80+
- Description
81+
* - ``CUDAQ_OBSERVE_NUM_TRAJECTORIES``
82+
- positive integer
83+
- The default number of trajectories for observe simulation if none was provided in the `observe` call. The default value is 1000.
84+
* - ``CUDAQ_BATCH_SIZE``
85+
- positive integer or `NONE`
86+
- The number of state vectors in the batched mode. If `NONE`, the batch size will be calculated based on the available device memory. Default is `NONE`.
87+
* - ``CUDAQ_BATCHED_SIM_MAX_BRANCHES``
88+
- positive integer
89+
- The number of trajectory branches to be tracked simultaneously in the gate fusion. Default is 16.
90+
* - ``CUDAQ_BATCHED_SIM_MAX_QUBITS``
91+
- positive integer
92+
- The max number of qubits for batching. If the qubit count in the circuit is more than this value, batched trajectory simulation will be disabled. The default value is 20.
93+
* - ``CUDAQ_BATCHED_SIM_MIN_BATCH_SIZE``
94+
- positive integer
95+
- The minimum number of trajectories for batching. If the number of trajectories is less than this value, batched trajectory simulation will be disabled. Default value is 4.
96+
97+
.. note::
98+
99+
Batched trajectory simulation is only available on the single-GPU execution mode of the :code:`nvidia` target.
100+
101+
If batched trajectory simulation is not activated, e.g., due to problem size, number of trajectories, or the nature of the circuit (dynamic circuits with mid-circuit measurements and conditional branching), the required number of trajectories will be executed sequentially.
102+
103+
5104
6105
Density Matrix
7106
++++++++++++++++

pr-2635/_sources/using/backends/simulators.rst.txt

+3-3
Original file line numberDiff line numberDiff line change
@@ -24,11 +24,11 @@ technical details and code examples for using each circuit simulator.
2424
- State Vector
2525
- Testing and small applications
2626
- CPU
27-
- single
27+
- double
2828
- < 28
2929
* - `nvidia`
3030
- State Vector
31-
- General purpose (default)
31+
- General purpose (default); Trajectory simulation for noisy circuits
3232
- Single GPU
3333
- single / double
3434
- < 33 / 32 (64 GB)
@@ -72,7 +72,7 @@ technical details and code examples for using each circuit simulator.
7272
- Density Matrix
7373
- Noisy simulations
7474
- CPU
75-
- single
75+
- double
7676
- < 14
7777
* - `stim`
7878
- Stabilizer

pr-2635/api/api.html

+1
Original file line numberDiff line numberDiff line change
@@ -364,6 +364,7 @@
364364
</ul>
365365
</li>
366366
<li class="toctree-l3"><a class="reference internal" href="../using/backends/sims/noisy.html"> Noisy Simulators</a><ul>
367+
<li class="toctree-l4"><a class="reference internal" href="../using/backends/sims/noisy.html#trajectory-noisy-simulation">Trajectory Noisy Simulation</a></li>
367368
<li class="toctree-l4"><a class="reference internal" href="../using/backends/sims/noisy.html#density-matrix">Density Matrix</a></li>
368369
<li class="toctree-l4"><a class="reference internal" href="../using/backends/sims/noisy.html#stim">Stim</a></li>
369370
</ul>

pr-2635/api/default_ops.html

+1
Original file line numberDiff line numberDiff line change
@@ -366,6 +366,7 @@
366366
</ul>
367367
</li>
368368
<li class="toctree-l3"><a class="reference internal" href="../using/backends/sims/noisy.html"> Noisy Simulators</a><ul>
369+
<li class="toctree-l4"><a class="reference internal" href="../using/backends/sims/noisy.html#trajectory-noisy-simulation">Trajectory Noisy Simulation</a></li>
369370
<li class="toctree-l4"><a class="reference internal" href="../using/backends/sims/noisy.html#density-matrix">Density Matrix</a></li>
370371
<li class="toctree-l4"><a class="reference internal" href="../using/backends/sims/noisy.html#stim">Stim</a></li>
371372
</ul>

pr-2635/api/languages/cpp_api.html

+32-2
Original file line numberDiff line numberDiff line change
@@ -364,6 +364,7 @@
364364
</ul>
365365
</li>
366366
<li class="toctree-l3"><a class="reference internal" href="../../using/backends/sims/noisy.html"> Noisy Simulators</a><ul>
367+
<li class="toctree-l4"><a class="reference internal" href="../../using/backends/sims/noisy.html#trajectory-noisy-simulation">Trajectory Noisy Simulation</a></li>
367368
<li class="toctree-l4"><a class="reference internal" href="../../using/backends/sims/noisy.html#density-matrix">Density Matrix</a></li>
368369
<li class="toctree-l4"><a class="reference internal" href="../../using/backends/sims/noisy.html#stim">Stim</a></li>
369370
</ul>
@@ -2656,6 +2657,18 @@ <h2>Noise Modeling<a class="headerlink" href="#noise-modeling" title="Permalink
26562657
<dd><p>Add a <a class="reference internal" href="#structcudaq_1_1kraus__op"><span class="std std-ref">kraus_op</span></a> to this channel. </p>
26572658
</dd></dl>
26582659

2660+
<dl class="cpp function">
2661+
<dt class="sig sig-object cpp" id="_CPPv4NK5cudaq13kraus_channel18is_unitary_mixtureEv">
2662+
<span class="target" id="classcudaq_1_1kraus__channel_1abf8effbbbb302ff37450202b25ffe721"></span><span class="k"><span class="pre">inline</span></span><span class="w"> </span><span class="kt"><span class="pre">bool</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">is_unitary_mixture</span></span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><span class="w"> </span><span class="k"><span class="pre">const</span></span><a class="headerlink" href="#_CPPv4NK5cudaq13kraus_channel18is_unitary_mixtureEv" title="Permalink to this definition">¶</a><br /></dt>
2663+
<dd><p>Returns whether or not this is a unitary mixture. </p>
2664+
</dd></dl>
2665+
2666+
<dl class="cpp function">
2667+
<dt class="sig sig-object cpp" id="_CPPv4N5cudaq13kraus_channel25generateUnitaryParametersEv">
2668+
<span class="target" id="classcudaq_1_1kraus__channel_1a49b36a2b346c14e4cbd6bdabdc2b04fa"></span><span class="k"><span class="pre">inline</span></span><span class="w"> </span><span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">generateUnitaryParameters</span></span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv4N5cudaq13kraus_channel25generateUnitaryParametersEv" title="Permalink to this definition">¶</a><br /></dt>
2669+
<dd><p>Checks if Kraus ops have unitary representations and saves them if they do. Users should only need to call this if they have modified the Kraus ops and want to recompute these values. </p>
2670+
</dd></dl>
2671+
26592672
</div>
26602673
<div class="breathe-sectiondef docutils container">
26612674
<p class="breathe-sectiondef-title rubric" id="breathe-section-title-public-members">Public Members</p>
@@ -2671,6 +2684,18 @@ <h2>Noise Modeling<a class="headerlink" href="#noise-modeling" title="Permalink
26712684
<dd><p>Noise parameter values. </p>
26722685
</dd></dl>
26732686

2687+
<dl class="cpp var">
2688+
<dt class="sig sig-object cpp" id="_CPPv4N5cudaq13kraus_channel11unitary_opsE">
2689+
<span class="target" id="classcudaq_1_1kraus__channel_1a96c9b610069e9ff86ef5597bff834c28"></span><span class="n"><span class="pre">std</span></span><span class="p"><span class="pre">::</span></span><span class="n"><span class="pre">vector</span></span><span class="p"><span class="pre">&lt;</span></span><span class="n"><span class="pre">std</span></span><span class="p"><span class="pre">::</span></span><span class="n"><span class="pre">vector</span></span><span class="p"><span class="pre">&lt;</span></span><span class="n"><span class="pre">std</span></span><span class="p"><span class="pre">::</span></span><span class="n"><span class="pre">complex</span></span><span class="p"><span class="pre">&lt;</span></span><span class="kt"><span class="pre">double</span></span><span class="p"><span class="pre">&gt;</span></span><span class="p"><span class="pre">&gt;</span></span><span class="p"><span class="pre">&gt;</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">unitary_ops</span></span></span><a class="headerlink" href="#_CPPv4N5cudaq13kraus_channel11unitary_opsE" title="Permalink to this definition">¶</a><br /></dt>
2690+
<dd><p>If all Kraus ops are - when scaled - unitary, this holds the unitary versions of those ops. These values are always “double” regardless of whether cudaq::real is float or double. </p>
2691+
</dd></dl>
2692+
2693+
<dl class="cpp var">
2694+
<dt class="sig sig-object cpp" id="_CPPv4N5cudaq13kraus_channel13probabilitiesE">
2695+
<span class="target" id="classcudaq_1_1kraus__channel_1a9f9cfb565a7013493a72d67602442bca"></span><span class="n"><span class="pre">std</span></span><span class="p"><span class="pre">::</span></span><span class="n"><span class="pre">vector</span></span><span class="p"><span class="pre">&lt;</span></span><span class="kt"><span class="pre">double</span></span><span class="p"><span class="pre">&gt;</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">probabilities</span></span></span><a class="headerlink" href="#_CPPv4N5cudaq13kraus_channel13probabilitiesE" title="Permalink to this definition">¶</a><br /></dt>
2696+
<dd><p>If all Kraus ops are - when scaled - unitary, this holds the probabilities of those ops. These values are always “double” regardless of whether cudaq::real is float or double. </p>
2697+
</dd></dl>
2698+
26742699
</div>
26752700
</dd></dl>
26762701

@@ -2801,8 +2826,7 @@ <h2>Noise Modeling<a class="headerlink" href="#noise-modeling" title="Permalink
28012826
<dl class="cpp enum-class">
28022827
<dt class="sig sig-object cpp" id="_CPPv4N5cudaq16noise_model_typeE">
28032828
<span class="target" id="NoiseModel_8h_1a8410c9abbed0e7dfcf2c5db0919e46e5"></span><span class="k"><span class="pre">enum</span></span><span class="w"> </span><span class="k"><span class="pre">class</span></span><span class="w"> </span><span class="sig-prename descclassname"><a class="reference internal" href="#_CPPv45cudaq" title="cudaq"><span class="n"><span class="pre">cudaq</span></span></a><span class="p"><span class="pre">::</span></span></span><span class="sig-name descname"><span class="n"><span class="pre">noise_model_type</span></span></span><a class="headerlink" href="#_CPPv4N5cudaq16noise_model_typeE" title="Permalink to this definition">¶</a><br /></dt>
2804-
<dd><p>Noise model enumerated type that allows downstream simulators of <code class="docutils literal notranslate"><a class="reference internal" href="#classcudaq_1_1kraus__channel"><span class="std std-ref"><span class="pre">kraus_channel</span></span></a></code> objects to apply simulator-specific logic for well-known noise models. </p>
2805-
<p><em>Values:</em></p>
2829+
<dd><p><em>Values:</em></p>
28062830
<dl class="cpp enumerator">
28072831
<dt class="sig sig-object cpp" id="_CPPv4N5cudaq16noise_model_type7unknownE">
28082832
<span class="target" id="NoiseModel_8h_1a8410c9abbed0e7dfcf2c5db0919e46e5aad921d60486366258809553a3db49a4a"></span><span class="k"><span class="pre">enumerator</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">unknown</span></span></span><a class="headerlink" href="#_CPPv4N5cudaq16noise_model_type7unknownE" title="Permalink to this definition">¶</a><br /></dt>
@@ -3885,6 +3909,12 @@ <h2>Platform<a class="headerlink" href="#platform" title="Permalink to this head
38853909
<dd><p>Set the noise model for future invocations of quantum kernels. </p>
38863910
</dd></dl>
38873911

3912+
<dl class="cpp function">
3913+
<dt class="sig sig-object cpp" id="_CPPv4N5cudaq16quantum_platform9get_noiseEv">
3914+
<span class="target" id="classcudaq_1_1quantum__platform_1aa523466e2bde7c9d7e4bce7ef4322f73"></span><span class="k"><span class="pre">const</span></span><span class="w"> </span><a class="reference internal" href="#_CPPv4N5cudaq11noise_modelE" title="cudaq::noise_model"><span class="n"><span class="pre">noise_model</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">get_noise</span></span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv4N5cudaq16quantum_platform9get_noiseEv" title="Permalink to this definition">¶</a><br /></dt>
3915+
<dd><p>Return the current noise model or <code class="docutils literal notranslate"><span class="pre">nullptr</span></code> if none set. </p>
3916+
</dd></dl>
3917+
38883918
<dl class="cpp function">
38893919
<dt class="sig sig-object cpp" id="_CPPv4NK5cudaq16quantum_platform23get_remote_capabilitiesEKNSt6size_tE">
38903920
<span class="target" id="classcudaq_1_1quantum__platform_1a1459a03708bb0236c804148fb6775cbf"></span><a class="reference internal" href="#_CPPv4N5cudaq18RemoteCapabilitiesE" title="cudaq::RemoteCapabilities"><span class="n"><span class="pre">RemoteCapabilities</span></span></a><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">get_remote_capabilities</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="n"><span class="pre">std</span></span><span class="p"><span class="pre">::</span></span><span class="n"><span class="pre">size_t</span></span><span class="w"> </span><span class="n sig-param"><span class="pre">qpuId</span></span><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="m"><span class="pre">0</span></span><span class="sig-paren">)</span><span class="w"> </span><span class="k"><span class="pre">const</span></span><a class="headerlink" href="#_CPPv4NK5cudaq16quantum_platform23get_remote_capabilitiesEKNSt6size_tE" title="Permalink to this definition">¶</a><br /></dt>

pr-2635/api/languages/python_api.html

+1
Original file line numberDiff line numberDiff line change
@@ -364,6 +364,7 @@
364364
</ul>
365365
</li>
366366
<li class="toctree-l3"><a class="reference internal" href="../../using/backends/sims/noisy.html"> Noisy Simulators</a><ul>
367+
<li class="toctree-l4"><a class="reference internal" href="../../using/backends/sims/noisy.html#trajectory-noisy-simulation">Trajectory Noisy Simulation</a></li>
367368
<li class="toctree-l4"><a class="reference internal" href="../../using/backends/sims/noisy.html#density-matrix">Density Matrix</a></li>
368369
<li class="toctree-l4"><a class="reference internal" href="../../using/backends/sims/noisy.html#stim">Stim</a></li>
369370
</ul>

pr-2635/applications/python/afqmc.html

+1
Original file line numberDiff line numberDiff line change
@@ -367,6 +367,7 @@
367367
</ul>
368368
</li>
369369
<li class="toctree-l3"><a class="reference internal" href="../../using/backends/sims/noisy.html"> Noisy Simulators</a><ul>
370+
<li class="toctree-l4"><a class="reference internal" href="../../using/backends/sims/noisy.html#trajectory-noisy-simulation">Trajectory Noisy Simulation</a></li>
370371
<li class="toctree-l4"><a class="reference internal" href="../../using/backends/sims/noisy.html#density-matrix">Density Matrix</a></li>
371372
<li class="toctree-l4"><a class="reference internal" href="../../using/backends/sims/noisy.html#stim">Stim</a></li>
372373
</ul>

pr-2635/applications/python/bernstein_vazirani.html

+1
Original file line numberDiff line numberDiff line change
@@ -367,6 +367,7 @@
367367
</ul>
368368
</li>
369369
<li class="toctree-l3"><a class="reference internal" href="../../using/backends/sims/noisy.html"> Noisy Simulators</a><ul>
370+
<li class="toctree-l4"><a class="reference internal" href="../../using/backends/sims/noisy.html#trajectory-noisy-simulation">Trajectory Noisy Simulation</a></li>
370371
<li class="toctree-l4"><a class="reference internal" href="../../using/backends/sims/noisy.html#density-matrix">Density Matrix</a></li>
371372
<li class="toctree-l4"><a class="reference internal" href="../../using/backends/sims/noisy.html#stim">Stim</a></li>
372373
</ul>

pr-2635/applications/python/cost_minimization.html

+1
Original file line numberDiff line numberDiff line change
@@ -367,6 +367,7 @@
367367
</ul>
368368
</li>
369369
<li class="toctree-l3"><a class="reference internal" href="../../using/backends/sims/noisy.html"> Noisy Simulators</a><ul>
370+
<li class="toctree-l4"><a class="reference internal" href="../../using/backends/sims/noisy.html#trajectory-noisy-simulation">Trajectory Noisy Simulation</a></li>
370371
<li class="toctree-l4"><a class="reference internal" href="../../using/backends/sims/noisy.html#density-matrix">Density Matrix</a></li>
371372
<li class="toctree-l4"><a class="reference internal" href="../../using/backends/sims/noisy.html#stim">Stim</a></li>
372373
</ul>

pr-2635/applications/python/deutsch_jozsa.html

+1
Original file line numberDiff line numberDiff line change
@@ -367,6 +367,7 @@
367367
</ul>
368368
</li>
369369
<li class="toctree-l3"><a class="reference internal" href="../../using/backends/sims/noisy.html"> Noisy Simulators</a><ul>
370+
<li class="toctree-l4"><a class="reference internal" href="../../using/backends/sims/noisy.html#trajectory-noisy-simulation">Trajectory Noisy Simulation</a></li>
370371
<li class="toctree-l4"><a class="reference internal" href="../../using/backends/sims/noisy.html#density-matrix">Density Matrix</a></li>
371372
<li class="toctree-l4"><a class="reference internal" href="../../using/backends/sims/noisy.html#stim">Stim</a></li>
372373
</ul>

0 commit comments

Comments
 (0)