toqito.state_metrics.measured_relative_entropy
==============================================

.. py:module:: toqito.state_metrics.measured_relative_entropy

.. autoapi-nested-parse::

   Measured relative entropy quantifies how well two states can be distinguished by measuring individual copies.





Module Contents
---------------

.. py:function:: measured_relative_entropy(rho, sigma, eps = 1e-05)

   Compute the measured relative entropy of two quantum states. [@Huang_2025_Msrd_Rel_Entr].

   Given a quantum state \(\rho\) and a positive semi-definite operator \(\sigma\),
   the measured relative entropy is defined by optimizing the relative entropy over all
   possible measurements:

   \[
       D^M(\rho \| \sigma) := \sup_{\mathcal{X}, (\Lambda_x)_{x \in \mathcal{X}}}
       \sum_{x \in \mathcal{X}} \operatorname{Tr}[\Lambda_x \rho] \ln \left(
       \frac{\operatorname{Tr}[\Lambda_x \rho]}{\operatorname{Tr}[\Lambda_x \sigma]} \right),
   \]

   where the supremum is over every finite alphabet \(\mathcal{X}\) and every
   positive-operator valued measure (POVM) \((\Lambda_x)_{x \in \mathcal{X}}\)
   (i.e., satisfying \(\Lambda_x \geq 0\) for all \(x \in \mathcal{X}\) and
   \(\sum_{x \in \mathcal{X}}\Lambda_x = I\)).

   When \(\rho\) and \(\sigma\) are \(d \times d\) matrices, the quantity
   \(D^M(\rho \| \sigma)\) can be efficiently calculated by means of a semi-definite
   program up to an additive error \(\varepsilon\), by means of
   \(O(\sqrt{\ln(1/\varepsilon)})\) linear matrix inequalities, each of size
   \(2d \times 2d\). Specifically, there exist \(m, k \in \mathbb{N}\) such that
   \(m+k = O(\sqrt{\ln(1/\varepsilon)})\) and the following inequality holds:

   \[
       |D^M(\rho \| \sigma) - D_{m,k}^M(\rho \| \sigma)| \leq \varepsilon,
   \]

   where

   \[
       D_{m,k}^M(\rho \| \sigma) :=
       \mathop{\sup}\limits_{\substack{
           \omega > 0,\; \theta \in \mathbb{H},\\
           T_1,\dots,T_m \in \mathbb{H},\\
           Z_0,\dots,Z_k \in \mathbb{H}}}
       \left\{
       \begin{array}{c}
       \operatorname{Tr}[\theta \rho] - \operatorname{Tr}[\omega \sigma] + 1 : \\[6pt]
       Z_0 = \omega, \qquad \sum_{j=1}^m w_j T_j = 2^{-k} \theta, \\[6pt]
       \left\{\begin{bmatrix}
       Z_i & Z_{i+1}\\
       Z_{i+1} & I
       \end{bmatrix}
       \ge 0 \right\}_{i=0}^{k-1}, \\[10pt]
       \left\{\begin{bmatrix}
       Z_k - I - T_j & -\sqrt{t_j}T_j \\
       -\sqrt{t_j}T_j & I - t_jT_j
       \end{bmatrix}
       \ge 0
       \right\}_{j=1}^{m} \end{array}
       \right\}
   \]


   and, for all \(j \in \{1, \dots, m\}\), \(w_j\) and \(t_j\)
   are the weights and nodes, respectively, for the \(m\)-point Gauss--Legendre quadrature
   on the interval \([0, 1]\).

   .. rubric:: Examples

   Consider the following quantum state \(\rho = \frac{1}{2}(I + r \cdot \mathbf{\sigma})\)
   and the PSD operator \(\sigma = \frac{1}{2}(I + s \cdot \mathbf{\sigma})\), where
   \(r = (0.9, 0.05, -0.02)\), \(s = (-0.8, 0.1, 0.1)\), and \(\mathbf{\sigma} =
   (\sigma_x, \sigma_y, \sigma_z)\) are the Pauli operators.

   Calculating the measured relative entropy can be done as follows.

   ```python exec="1" source="above"
   from toqito.matrices import pauli
   from toqito.state_metrics import measured_relative_entropy
   import numpy as np

   r = np.array([0.9, 0.05, -0.02])
   s = np.array([-0.8, 0.1, 0.1])
   rho = 0.5 * (pauli("I") + r[0] * pauli("X") + r[1] * pauli("Y") + r[2] * pauli("Z"))
   sigma = 0.5 * (pauli("I") + s[0] * pauli("X") + s[1] * pauli("Y") + s[2] * pauli("Z"))
   print(measured_relative_entropy(rho, sigma, 1e-5))
   ```

   :raises ValueError: If `rho` if not a density operator or if `sigma` is not positive semi-definite.

   :param rho: Density operator.
   :param sigma: Positive semi-definite operator.
   :param eps: Tolerance level.

   :returns: The measured relative entropy between `rho` and `sigma`.