------------------------------------------------
Computing tensor network state expectation value
------------------------------------------------

The following code example illustrates how to define a tensor network state,
a tensor network operator, and then compute the expectation value of the
tensor network operator over the tensor network 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/expectation_example.cu>`_).

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

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

-------------------------------
Define the tensor network state
-------------------------------

Let's define a tensor network state corresponding to a 16-qubit quantum circuit.

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

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

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

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

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

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

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

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

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

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

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

-----------------------------------
Construct a tensor network operator 
-----------------------------------

Now let's create an empty tensor network operator for 16-qubit states
and then append three components to it, where each component is a
direct product of Pauli matrices scaled by some complex coefficient
(like in the Jordan-Wigner representation).

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

-----------------------------------
Create the expectation value object
-----------------------------------

Once the quantum circuit and the tensor network operator have been constructed,
let's create the expectation value object that will compute the expectation value
of the specified tensor network operator over the final state of the specified
quantum circuit.

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

-------------------------------------------
Configure the expectation value calculation
-------------------------------------------

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

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

-----------------------------------------
Prepare the expectation value calculation
-----------------------------------------

Let's create a workspace descriptor and prepare the computation
of the desired expectation value.

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

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

Now we can set up the required workspace buffer.

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

---------------------------------------
Compute the requested expectation value
---------------------------------------

Once everything has been set up, we compute the requested expectation value
and print it. Note that the returned expectation value is not normalized.
The 2-norm of the tensor network state is returned as a separate argument.

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

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

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