-----------------------------------------------------------
Computing tensor network state marginal distribution tensor
-----------------------------------------------------------

The following code example illustrates how to define a tensor network state
and then compute the tensor network state marginal distribution tensor.
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/marginal_example.cu>`_).

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

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

----------------------------------------------------------------------------
Define the tensor network state and the desired marginal distribution tensor
----------------------------------------------------------------------------

Let's define a tensor network state corresponding to a 16-qubit quantum circuit
and request the marginal distribution tensor for qubits 0 and 1.

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

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

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

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

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

------------------------------------------------
Allocate the marginal distribution tensor on GPU
------------------------------------------------

Here we allocate the marginal distribution tensor, that is,
the reduced density matrix for qubits 0 and 1 on GPU.

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

----------------------------------
Allocate the scratch buffer on GPU
----------------------------------

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

----------------------------------
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/marginal_example.cu
   :language: c++
   :linenos:
   :lineno-match:
   :start-after: Sphinx: Marginal #7
   :end-before: Sphinx: Marginal #8

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

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

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

---------------------------------------
Create the marginal distribution object
---------------------------------------

Once the quantum circuit has been constructed, let's create the marginal distribution object
that will compute the marginal distribution tensor (reduced density matrix) for qubits 0 and 1.

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

------------------------------------------
Configure the marginal distribution object
------------------------------------------

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

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

-----------------------------------------------------------
Prepare the computation of the marginal distribution tensor
-----------------------------------------------------------

Let's create a workspace descriptor and prepare the computation of the
marginal distribution tensor.

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

--------------------
Set up the workspace
--------------------

Now we can set up the required workspace buffer.

.. literalinclude:: ../../../../tensor_network/samples/high_level/marginal_example.cu
   :language: c++
   :linenos:
   :lineno-match:
   :start-after: Sphinx: Marginal #12
   :end-before: Sphinx: Marginal #13

----------------------------------------
Compute the marginal distribution tensor
----------------------------------------

Once everything has been set up, we compute the requested marginal distribution tensor
(reduced density matrix) for qubits 0 and 1, copy it back to Host memory, and print it.

.. literalinclude:: ../../../../tensor_network/samples/high_level/marginal_example.cu
   :language: c++
   :linenos:
   :lineno-match:
   :start-after: Sphinx: Marginal #13
   :end-before: Sphinx: Marginal #14

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

.. literalinclude:: ../../../../tensor_network/samples/high_level/marginal_example.cu
   :language: c++
   :linenos:
   :lineno-match:
   :start-after: Sphinx: Marginal #14