Skip to content

Commit 626699e

Browse files
[docs] Restore the docs for trajectory noisy simulators (#2648)
Ported from PR #2466 Follow-up to PR #2481 Signed-off-by: Pradnya Khalate <[email protected]>
1 parent 7e1c691 commit 626699e

File tree

2 files changed

+102
-3
lines changed

2 files changed

+102
-3
lines changed

docs/sphinx/using/backends/sims/noisy.rst

+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
++++++++++++++++

docs/sphinx/using/backends/simulators.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ technical details and code examples for using each circuit simulator.
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)

0 commit comments

Comments
 (0)