toqito.rand.random_density_matrix
=================================

.. py:module:: toqito.rand.random_density_matrix

.. autoapi-nested-parse::

   Generates a random density matrix.





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

.. py:function:: random_density_matrix(dim, is_real = False, k_param = None, distance_metric = 'haar', seed = None)

   Generate a random density matrix.

   Generates a random `dim`-by-`dim` density matrix distributed according to the Hilbert-Schmidt measure.
   The matrix is of rank <= `k_param` distributed according to the distribution `distance_metric` If
   `is_real = True`, then all of its entries will be real. The variable `distance_metric` must be one of:

   - `haar` (default):
       Generate a larger pure state according to the Haar measure and trace out the extra dimensions. Sometimes
       called the Hilbert-Schmidt measure when `k_param = dim`.

   - `bures`:
       The Bures measure.

   .. rubric:: Examples

   Using `|toqito⟩`, we may generate a random complex-valued \(n\)- dimensional density matrix. For
   \(d=2\), this can be accomplished as follows.

   ```python exec="1" source="above" session="complex_dm_example"
   from toqito.rand import random_density_matrix

   complex_dm = random_density_matrix(2)

   print(complex_dm)
   ```


   We can verify that this is in fact a valid density matrix using the `is_density` function from
   `|toqito⟩` as follows

   ```python exec="1" source="above" session="complex_dm_example"
   from toqito.matrix_props import is_density

   print(is_density(complex_dm))
   ```


   We can also generate random density matrices that are real-valued as follows.

   ```python exec="1" source="above" session="real_dm_example"
   from toqito.rand import random_density_matrix

   real_dm = random_density_matrix(2, is_real=True)

   print(real_dm)
   ```



   Again, verifying that this is a valid density matrix can be done as follows.

   ```python exec="1" source="above" session="real_dm_example"
   from toqito.matrix_props import is_density

   print(is_density(real_dm))
   ```

   By default, the random density operators are constructed using the Haar measure. We can select to generate the
   random density matrix according to the Bures metric instead as follows.

   ```python exec="1" source="above" session="bures_dm_example"
   from toqito.rand import random_density_matrix

   bures_mat = random_density_matrix(2, distance_metric="bures")

   print(bures_mat)
   ```


   As before, we can verify that this matrix generated is a valid density matrix.

   ```python exec="1" source="above" session="bures_dm_example"
   from toqito.matrix_props import is_density

   print(is_density(bures_mat))
   ```

   It is also possible to pass a seed to this function for reproducibility.
   ```python exec="1" source="above" session="seeded_dm_example"
   from toqito.rand import random_density_matrix

   seeded = random_density_matrix(2, seed=42)

   print(seeded)
   ```

   We can once again verify that this is in fact a valid density matrix using the
   `is_density` function from `|toqito⟩` as follows

   ```python exec="1" source="above" session="seeded_dm_example"
   from toqito.matrix_props import is_density

   seeded = random_density_matrix(2, seed=42)

   print(is_density(seeded))
   ```

   :param dim: The number of rows (and columns) of the density matrix.
   :param is_real: Boolean denoting whether the returned matrix will have all real entries or not.
   :param k_param: Default value is equal to `dim`.
   :param distance_metric: The distance metric used to randomly generate the density matrix. This metric is either the
   :param Haar measure or the Bures measure. Default value is to use the Haar measure.:
   :param seed: A seed used to instantiate numpy's random number generator.

   :returns: A `dim`-by-`dim` random density matrix.