toqito.rand.random_povm
=======================

.. py:module:: toqito.rand.random_povm

.. autoapi-nested-parse::

   Generates a random POVM.





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

.. py:function:: random_povm(dim, num_inputs, num_outputs, seed = None)

   Generate random positive operator valued measurements (POVMs) [@WikiPOVM].

   Randomness model
   ----------------

   For each input we draw \(n_{\text{out}}\) matrices from the real Ginibre ensemble, i.e., each
   entry is sampled independently from the standard normal distribution using ``numpy``'s
   ``default_rng``.  We interpret these matrices as Kraus operators \(A_{x,a}\) and normalize
   them so that the measurement is complete.  Concretely, for each input \(x\) we form

   \[
       G_x = \sum_a A_{x,a}^\dagger A_{x,a}, \qquad
       B_{x,a} = G_x^{-1/2} A_{x,a}, \qquad
       M_{x,a} = B_{x,a}^\dagger B_{x,a}.
   \]

   The matrices \(M_{x,a}\) constitute a POVM satisfying
   \(\sum_a M_{x,a} = \mathbb{I}\).  This procedure induces the (Hilbert–Schmidt) normalized
   Wishart measure on the POVM effects.  Supplying ``seed`` reproduces the same sample sequence.

   .. rubric:: Examples

   We can generate a set of `dim`-by-`dim` POVMs consisting of a specific dimension along with a given number of
   measurement inputs and measurement outputs. As an example, we can construct a random set of \(2\)-by-\(2\)
   POVMs of dimension with \(2\) inputs and \(2\) outputs.

   ```python exec="1" source="above" session="povm_example"
   import numpy as np
   from toqito.rand import random_povm

   dim, num_inputs, num_outputs = 2, 2, 2

   povms = random_povm(dim, num_inputs, num_outputs)

   print(povms)
   ```


   We can verify that this constitutes a valid set of POVM elements as checking that these operators all sum to the
   identity operator.

   ```python exec="1" source="above" session="povm_example"
   print(np.round(povms[:, :, 0, 0] + povms[:, :, 0, 1]))
   ```

   It is also possible to add a seed for reproducibility.

   ```python exec="1" source="above" session="povm_example"
   import numpy as np
   from toqito.rand import random_povm

   dim, num_inputs, num_outputs = 2, 2, 2

   povms = random_povm(dim, num_inputs, num_outputs, seed=42)

   print(povms)
   ```

   We can once again verify that this constitutes a valid set of POVM elements as checking that
   these operators all sum to the identity operator.

   ```python exec="1" source="above" session="povm_example"
   print(np.round(povms[:, :, 0, 0] + povms[:, :, 0, 1]))
   ```

   :param dim: The dimensions of the measurements.
   :param num_inputs: The number of inputs for the measurement.
   :param num_outputs: The number of outputs for the measurement.
   :param seed: A seed used to instantiate numpy's random number generator (Ginibre sampling).

   :returns: A set of `dim`-by-`dim` POVMs of shape `(dim, dim, num_inputs, num_outputs)`.