---------------------------------
Sampling the tensor network state
---------------------------------

The following code example illustrates how to sample the tensor network state (e.g., sampling the final quantum circuit state).
The full code can be found in the `NVIDIA/cuQuantum <https://github.com/NVIDIA/cuQuantum>`_ repository (`here <https://github.com/NVIDIA/cuQuantum/blob/main/samples/cutensornet/high_level/sampling_example.cu>`_).

--------------------------
Headers and error handling
--------------------------

.. literalinclude:: ../../../../tensor_network/samples/high_level/sampling_example.cu
   :language: c++
   :linenos:
   :lineno-match:
   :start-after: Sphinx: Sampler #1
   :end-before: Sphinx: Sampler #2

------------------------------------------------------------------------------------
Define the tensor network state and the desired number of output samples to generate
------------------------------------------------------------------------------------

Let's define a tensor network state corresponding to a 16-qubit quantum circuit
and request to produce 100 output samples for the full qubit register.

.. literalinclude:: ../../../../tensor_network/samples/high_level/sampling_example.cu
   :language: c++
   :linenos:
   :lineno-match:
   :start-after: Sphinx: Sampler #2
   :end-before: Sphinx: Sampler #3

-----------------------------------------
Initialize the cuTensorNet library handle
-----------------------------------------

.. literalinclude:: ../../../../tensor_network/samples/high_level/sampling_example.cu
   :language: c++
   :linenos:
   :lineno-match:
   :start-after: Sphinx: Sampler #3
   :end-before: Sphinx: Sampler #4

---------------------------
Define quantum gates on GPU
---------------------------

.. literalinclude:: ../../../../tensor_network/samples/high_level/sampling_example.cu
   :language: c++
   :linenos:
   :lineno-match:
   :start-after: Sphinx: Sampler #4
   :end-before: Sphinx: Sampler #5

----------------------------------
Create a pure tensor network state
----------------------------------

Now let's create a pure tensor network state for a 16-qubit quantum circuit.

.. literalinclude:: ../../../../tensor_network/samples/high_level/sampling_example.cu
   :language: c++
   :linenos:
   :lineno-match:
   :start-after: Sphinx: Sampler #5
   :end-before: Sphinx: Sampler #6

-------------------
Apply quantum gates
-------------------

Let's construct the GHZ quantum circuit by applying the corresponding quantum gates.

.. literalinclude:: ../../../../tensor_network/samples/high_level/sampling_example.cu
   :language: c++
   :linenos:
   :lineno-match:
   :start-after: Sphinx: Sampler #6
   :end-before: Sphinx: Sampler #7

---------------------------------------
Create the tensor network state sampler
---------------------------------------

Once the quantum circuit has been constructed, let's create the tensor network state sampler
for the full qubit register (all qubits).

.. literalinclude:: ../../../../tensor_network/samples/high_level/sampling_example.cu
   :language: c++
   :linenos:
   :lineno-match:
   :start-after: Sphinx: Sampler #7
   :end-before: Sphinx: Sampler #8

------------------------------------------
Configure the tensor network state sampler
------------------------------------------

Now we can configure the tensor network state sampler by setting the number
of hyper-samples to be used by the tensor network contraction path finder.

.. literalinclude:: ../../../../tensor_network/samples/high_level/sampling_example.cu
   :language: c++
   :linenos:
   :lineno-match:
   :start-after: Sphinx: Sampler #8
   :end-before: Sphinx: Sampler #9

----------------------------------------
Prepare the tensor network state sampler
----------------------------------------

Let's create a workspace descriptor and prepare the tensor network state sampler.

.. literalinclude:: ../../../../tensor_network/samples/high_level/sampling_example.cu
   :language: c++
   :linenos:
   :lineno-match:
   :start-after: Sphinx: Sampler #9
   :end-before: Sphinx: Sampler #10

------------------------------------------------------------
Allocate the workspace buffer on GPU and setup the workspace
------------------------------------------------------------

Allocate the required scratch workspace buffer, and provide extra buffer for cache workspace.

.. literalinclude:: ../../../../tensor_network/samples/high_level/sampling_example.cu
   :language: c++
   :linenos:
   :lineno-match:
   :start-after: Sphinx: Sampler #10
   :end-before: Sphinx: Sampler #11

---------------------------------------------------
Perform sampling of the final quantum circuit state
---------------------------------------------------

Once everything had been set up, we perform sampling of the quantum circuit state
and print the output samples.

.. literalinclude:: ../../../../tensor_network/samples/high_level/sampling_example.cu
   :language: c++
   :linenos:
   :lineno-match:
   :start-after: Sphinx: Sampler #11
   :end-before: Sphinx: Sampler #12

--------------
Free resources
--------------

.. literalinclude:: ../../../../tensor_network/samples/high_level/sampling_example.cu
   :language: c++
   :linenos:
   :lineno-match:
   :start-after: Sphinx: Sampler #12