Skip to content

Commit

Permalink
Docs preview for PR #2502.
Browse files Browse the repository at this point in the history
  • Loading branch information
@cuda-quantum-bot
cuda-quantum-bot committed Jan 16, 2025
1 parent e18d385 commit 2461da5
Show file tree
Hide file tree
Showing 97 changed files with 1,225 additions and 552 deletions.
108 changes: 100 additions & 8 deletions pr-2502/_sources/using/backends/simulators.rst.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,11 @@ and multi-QPU (`mqpu` :ref:`platform <mqpu-platform>`) distribution whereby each
Host CPU memory can be leveraged in addition to GPU memory to accommodate the state vector
(i.e., maximizing the number of qubits to be simulated).

* Trajectory simulation for noisy quantum circuits

The :code:`nvidia` target supports noisy quantum circuit simulations using quantum trajectory method across all configurations: single GPU, multi-node multi-GPU, and with host memory.
When simulating many trajectories with small state vectors, the simulation is batched for optimal performance.

.. _cuQuantum single-GPU:


Expand Down Expand Up @@ -266,6 +271,100 @@ environment variable to another integer value as shown below.
nvq++ --target nvidia --target-option mgpu,fp64 program.cpp [...] -o program.x
CUDAQ_MGPU_FUSE=5 mpiexec -np 2 ./program.x
Trajectory Noisy Simulation
++++++++++++++++++++++++++++++++++

When a :code:`noise_model` is provided to CUDA-Q, the :code:`nvidia` target will incorporate quantum noise into the quantum circuit simulation according to the noise model specified.


.. tab:: Python

.. literalinclude:: ../../snippets/python/using/backends/trajectory.py
:language: python
:start-after: [Begin Docs]

.. code:: bash
python3 program.py
{ 00:15 01:92 10:81 11:812 }
.. tab:: C++
.. literalinclude:: ../../snippets/cpp/using/backends/trajectory.cpp
:language: cpp
:start-after: [Begin Documentation]
.. code:: bash
nvq++ --target nvidia program.cpp [...] -o program.x
./program.x
{ 00:15 01:92 10:81 11:812 }
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.
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.
Hence, depending on the required level of accuracy, the number of trajectories can be specified accordingly.
.. tab:: Python
.. literalinclude:: ../../snippets/python/using/backends/trajectory_observe.py
:language: python
:start-after: [Begin Docs]
.. code:: bash
python3 program.py
Noisy <Z> with 1024 trajectories = -0.810546875
Noisy <Z> with 8192 trajectories = -0.800048828125
.. tab:: C++
.. literalinclude:: ../../snippets/cpp/using/backends/trajectory_observe.cpp
:language: cpp
:start-after: [Begin Documentation]
.. code:: bash
nvq++ --target nvidia program.cpp [...] -o program.x
./program.x
Noisy <Z> with 1024 trajectories = -0.810547
Noisy <Z> with 8192 trajectories = -0.800049
The following environment variable options are applicable to the :code:`nvidia` target for trajectory noisy simulation. Any environment variables must be set
prior to setting the target.
.. list-table:: **Additional environment variable options for trajectory simulation**
:widths: 20 30 50
* - Option
- Value
- Description
* - ``CUDAQ_OBSERVE_NUM_TRAJECTORIES``
- positive integer
- The default number of trajectories for observe simulation if none was provided in the `observe` call. The default value is 1000.
* - ``CUDAQ_BATCH_SIZE``
- positive integer or `NONE`
- 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`.
* - ``CUDAQ_BATCHED_SIM_MAX_BRANCHES``
- positive integer
- The number of trajectory branches to be tracked simultaneously in the gate fusion. Default is 16.
* - ``CUDAQ_BATCHED_SIM_MAX_QUBITS``
- positive integer
- 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.
* - ``CUDAQ_BATCHED_SIM_MIN_BATCH_SIZE``
- positive integer
- 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.
.. note::
Batched trajectory simulation is only available on the single-GPU execution mode of the :code:`nvidia` target.
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.
.. _OpenMP CPU-only:
OpenMP CPU-only
Expand Down Expand Up @@ -382,17 +481,14 @@ Specific aspects of the simulation can be configured by setting the following of
* **`CUDA_VISIBLE_DEVICES=X`**: Makes the process only see GPU X on multi-GPU nodes. Each MPI process must only see its own dedicated GPU. For example, if you run 8 MPI processes on a DGX system with 8 GPUs, each MPI process should be assigned its own dedicated GPU via `CUDA_VISIBLE_DEVICES` when invoking `mpiexec` (or `mpirun`) commands.
* **`OMP_PLACES=cores`**: Set this environment variable to improve CPU parallelization.
* **`OMP_NUM_THREADS=X`**: To enable CPU parallelization, set X to `NUMBER_OF_CORES_PER_NODE/NUMBER_OF_GPUS_PER_NODE`.
* **`CUDAQ_TENSORNET_CONTROLLED_RANK=X`**: Specify the number of controlled qubits whereby the full tensor body of the controlled gate is expanded. If the number of controlled qubits is greater than this value, the gate is applied as a controlled tensor operator to the tensor network state. Default value is 1.
.. note::
This backend requires an NVIDIA GPU and CUDA runtime libraries.
If you do not have these dependencies installed, you may encounter an error stating `Invalid simulator requested`.
See the section :ref:`dependencies-and-compatibility` for more information about how to install dependencies.
.. note::

Setting random seed, via :code:`cudaq::set_random_seed`, is not supported for this backend due to a limitation of the :code:`cuTensorNet` library. This will be fixed in future release once this feature becomes available.

Matrix product state
+++++++++++++++++++++++++++++++++++
Expand Down Expand Up @@ -436,10 +532,6 @@ Specific aspects of the simulation can be configured by defining the following e
If you do not have these dependencies installed, you may encounter an error stating `Invalid simulator requested`.
See the section :ref:`dependencies-and-compatibility` for more information about how to install dependencies.
.. note::

Setting random seed, via :code:`cudaq::set_random_seed`, is not supported for this backend due to a limitation of the :code:`cuTensorNet` library. This will be fixed in future release once this feature becomes available.

.. note::
The parallelism of Jacobi method (the default `CUDAQ_MPS_SVD_ALGO` setting) gives GPU better performance on small and medium size matrices.
If you expect a large number of singular values (e.g., increasing the `CUDAQ_MPS_MAX_BOND` setting), please adjust the `CUDAQ_MPS_SVD_ALGO` setting accordingly.
Expand Down
72 changes: 36 additions & 36 deletions pr-2502/_static/pygments.css
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,34 +4,34 @@ span.linenos { color: #3c4354; background-color: transparent; padding-left: 5px;
td.linenos .special { color: #3c4354; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }
span.linenos.special { color: #3c4354; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }
.highlight .hll { background-color: #6e7681 }
.highlight { background: #1d2331; color: #d4d2c8 }
.highlight .c { color: #7e8aa1 } /* Comment */
.highlight .err { color: #f88f7f } /* Error */
.highlight .esc { color: #d4d2c8 } /* Escape */
.highlight .g { color: #d4d2c8 } /* Generic */
.highlight { background: #1d2331; color: #D4D2C8 }
.highlight .c { color: #7E8AA1 } /* Comment */
.highlight .err { color: #F88F7F } /* Error */
.highlight .esc { color: #D4D2C8 } /* Escape */
.highlight .g { color: #D4D2C8 } /* Generic */
.highlight .k { color: #FFAD66 } /* Keyword */
.highlight .l { color: #D5FF80 } /* Literal */
.highlight .n { color: #d4d2c8 } /* Name */
.highlight .n { color: #D4D2C8 } /* Name */
.highlight .o { color: #FFAD66 } /* Operator */
.highlight .x { color: #d4d2c8 } /* Other */
.highlight .p { color: #d4d2c8 } /* Punctuation */
.highlight .ch { color: #f88f7f; font-style: italic } /* Comment.Hashbang */
.highlight .cm { color: #7e8aa1 } /* Comment.Multiline */
.highlight .x { color: #D4D2C8 } /* Other */
.highlight .p { color: #D4D2C8 } /* Punctuation */
.highlight .ch { color: #F88F7F; font-style: italic } /* Comment.Hashbang */
.highlight .cm { color: #7E8AA1 } /* Comment.Multiline */
.highlight .cp { color: #FFAD66; font-weight: bold } /* Comment.Preproc */
.highlight .cpf { color: #7e8aa1 } /* Comment.PreprocFile */
.highlight .c1 { color: #7e8aa1 } /* Comment.Single */
.highlight .cs { color: #7e8aa1; font-style: italic } /* Comment.Special */
.highlight .gd { color: #f88f7f; background-color: #3d1e20 } /* Generic.Deleted */
.highlight .ge { color: #d4d2c8; font-style: italic } /* Generic.Emph */
.highlight .ges { color: #d4d2c8 } /* Generic.EmphStrong */
.highlight .gr { color: #f88f7f } /* Generic.Error */
.highlight .gh { color: #d4d2c8 } /* Generic.Heading */
.highlight .gi { color: #6ad4af; background-color: #19362c } /* Generic.Inserted */
.highlight .go { color: #7e8aa1 } /* Generic.Output */
.highlight .gp { color: #d4d2c8 } /* Generic.Prompt */
.highlight .gs { color: #d4d2c8; font-weight: bold } /* Generic.Strong */
.highlight .gu { color: #d4d2c8 } /* Generic.Subheading */
.highlight .gt { color: #f88f7f } /* Generic.Traceback */
.highlight .cpf { color: #7E8AA1 } /* Comment.PreprocFile */
.highlight .c1 { color: #7E8AA1 } /* Comment.Single */
.highlight .cs { color: #7E8AA1; font-style: italic } /* Comment.Special */
.highlight .gd { color: #F88F7F; background-color: #3D1E20 } /* Generic.Deleted */
.highlight .ge { color: #D4D2C8; font-style: italic } /* Generic.Emph */
.highlight .ges { color: #D4D2C8 } /* Generic.EmphStrong */
.highlight .gr { color: #F88F7F } /* Generic.Error */
.highlight .gh { color: #D4D2C8 } /* Generic.Heading */
.highlight .gi { color: #6AD4AF; background-color: #19362C } /* Generic.Inserted */
.highlight .go { color: #7E8AA1 } /* Generic.Output */
.highlight .gp { color: #D4D2C8 } /* Generic.Prompt */
.highlight .gs { color: #D4D2C8; font-weight: bold } /* Generic.Strong */
.highlight .gu { color: #D4D2C8 } /* Generic.Subheading */
.highlight .gt { color: #F88F7F } /* Generic.Traceback */
.highlight .kc { color: #FFAD66 } /* Keyword.Constant */
.highlight .kd { color: #FFAD66 } /* Keyword.Declaration */
.highlight .kn { color: #FFAD66 } /* Keyword.Namespace */
Expand All @@ -45,19 +45,19 @@ span.linenos.special { color: #3c4354; background-color: #ffffc0; padding-left:
.highlight .nb { color: #FFD173 } /* Name.Builtin */
.highlight .nc { color: #73D0FF } /* Name.Class */
.highlight .no { color: #FFD173 } /* Name.Constant */
.highlight .nd { color: #7e8aa1; font-weight: bold; font-style: italic } /* Name.Decorator */
.highlight .nd { color: #7E8AA1; font-weight: bold; font-style: italic } /* Name.Decorator */
.highlight .ni { color: #95E6CB } /* Name.Entity */
.highlight .ne { color: #73D0FF } /* Name.Exception */
.highlight .nf { color: #FFD173 } /* Name.Function */
.highlight .nl { color: #d4d2c8 } /* Name.Label */
.highlight .nn { color: #d4d2c8 } /* Name.Namespace */
.highlight .nx { color: #d4d2c8 } /* Name.Other */
.highlight .nl { color: #D4D2C8 } /* Name.Label */
.highlight .nn { color: #D4D2C8 } /* Name.Namespace */
.highlight .nx { color: #D4D2C8 } /* Name.Other */
.highlight .py { color: #FFD173 } /* Name.Property */
.highlight .nt { color: #5CCFE6 } /* Name.Tag */
.highlight .nv { color: #d4d2c8 } /* Name.Variable */
.highlight .nv { color: #D4D2C8 } /* Name.Variable */
.highlight .ow { color: #FFAD66 } /* Operator.Word */
.highlight .pm { color: #d4d2c8 } /* Punctuation.Marker */
.highlight .w { color: #d4d2c8 } /* Text.Whitespace */
.highlight .pm { color: #D4D2C8 } /* Punctuation.Marker */
.highlight .w { color: #D4D2C8 } /* Text.Whitespace */
.highlight .mb { color: #DFBFFF } /* Literal.Number.Bin */
.highlight .mf { color: #DFBFFF } /* Literal.Number.Float */
.highlight .mh { color: #DFBFFF } /* Literal.Number.Hex */
Expand All @@ -67,7 +67,7 @@ span.linenos.special { color: #3c4354; background-color: #ffffc0; padding-left:
.highlight .sb { color: #D5FF80 } /* Literal.String.Backtick */
.highlight .sc { color: #D5FF80 } /* Literal.String.Char */
.highlight .dl { color: #D5FF80 } /* Literal.String.Delimiter */
.highlight .sd { color: #7e8aa1 } /* Literal.String.Doc */
.highlight .sd { color: #7E8AA1 } /* Literal.String.Doc */
.highlight .s2 { color: #D5FF80 } /* Literal.String.Double */
.highlight .se { color: #95E6CB } /* Literal.String.Escape */
.highlight .sh { color: #D5FF80 } /* Literal.String.Heredoc */
Expand All @@ -78,8 +78,8 @@ span.linenos.special { color: #3c4354; background-color: #ffffc0; padding-left:
.highlight .ss { color: #DFBFFF } /* Literal.String.Symbol */
.highlight .bp { color: #5CCFE6 } /* Name.Builtin.Pseudo */
.highlight .fm { color: #FFD173 } /* Name.Function.Magic */
.highlight .vc { color: #d4d2c8 } /* Name.Variable.Class */
.highlight .vg { color: #d4d2c8 } /* Name.Variable.Global */
.highlight .vi { color: #d4d2c8 } /* Name.Variable.Instance */
.highlight .vm { color: #d4d2c8 } /* Name.Variable.Magic */
.highlight .vc { color: #D4D2C8 } /* Name.Variable.Class */
.highlight .vg { color: #D4D2C8 } /* Name.Variable.Global */
.highlight .vi { color: #D4D2C8 } /* Name.Variable.Instance */
.highlight .vm { color: #D4D2C8 } /* Name.Variable.Magic */
.highlight .il { color: #DFBFFF } /* Literal.Number.Integer.Long */
1 change: 1 addition & 0 deletions pr-2502/api/api.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -331,6 +331,7 @@
<li class="toctree-l4"><a class="reference internal" href="../using/backends/simulators.html#features">Features</a></li>
<li class="toctree-l4"><a class="reference internal" href="../using/backends/simulators.html#single-gpu">Single-GPU</a></li>
<li class="toctree-l4"><a class="reference internal" href="../using/backends/simulators.html#multi-node-multi-gpu">Multi-node multi-GPU</a></li>
<li class="toctree-l4"><a class="reference internal" href="../using/backends/simulators.html#trajectory-noisy-simulation">Trajectory Noisy Simulation</a></li>
<li class="toctree-l4"><a class="reference internal" href="../using/backends/simulators.html#openmp-cpu-only">OpenMP CPU-only</a></li>
</ul>
</li>
Expand Down
Loading

0 comments on commit 2461da5

Please sign in to comment.