toqito.rand.random_state_vector
===============================

.. py:module:: toqito.rand.random_state_vector

.. autoapi-nested-parse::

   Generates a random state vector.





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

.. py:function:: random_state_vector(dim, is_real = False, k_param = 0, seed = None)

   Generate a random pure state vector.

   Randomness model

   We sample entries independently from the standard normal distribution using ``numpy``'s
   ``default_rng``.  If ``is_real`` is ``False`` (default), the imaginary part is sampled in the
   same way and added with the factor \(i\); otherwise the vector is real.  The sampled vector
   is normalized to have unit Euclidean norm.  When ``k_param`` is strictly positive, the returned
   state describes a bipartite system of dimensions ``dim`` (or ``[dim, dim]`` if ``dim`` is an
   integer) with Schmidt rank at most ``k_param``.  This is achieved by drawing local factors and
   combining them with a maximally entangled resource state.

   .. rubric:: Examples

   We may generate a random state vector. For instance, here is an example where we can generate a
   \(2\)-dimensional random state vector.

   ```python exec="1" source="above" session="vec_example"
   from toqito.rand import random_state_vector

   vec = random_state_vector(2)

   print(vec)
   ```

   We can verify that this is in fact a valid state vector by computing the corresponding density
   matrix of the vector and checking if the density matrix is pure.

   ```python exec="1" source="above" session="vec_example"
   from toqito.state_props import is_pure

   dm = vec @ vec.conj().T

   print(is_pure(dm))
   ```

   It is also possible to pass a seed for reproducibility.

   ```python exec="1" source="above" session="vec_example"
   from toqito.rand import random_state_vector

   vec = random_state_vector(2, seed=42)

   print(vec)
   ```

   We can once again verify that this is in fact a valid state vector by computing the
   corresponding density matrix of the vector and checking if the density matrix is pure.

   ```python exec="1" source="above" session="vec_example"
   from toqito.state_props import is_pure

   dm = vec @ vec.conj().T

   print(is_pure(dm))
   ```

   :param dim: Either a positive integer giving the total Hilbert-space dimension, or a length-2 sequence specifying the
   :param individual subsystem dimensions for bipartite sampling.:
   :param is_real: Boolean denoting whether the returned vector has real entries. Default is `False`, which produces
   :param complex amplitudes.:
   :param k_param: Optional upper bound on the Schmidt rank when ``dim`` describes a bipartite system.  Set to `0`
   :param (default) to ignore the Schmidt rank constraint.  Must be non-negative and strictly less than the smaller:
   :param subsystem dimension when used.:
   :param seed: A seed used to instantiate numpy's random number generator.

   :returns: A normalized column vector of shape ``(total_dim, 1)`` where ``total_dim`` equals `dim` if ``dim`` is an integer
             and equals the product of entries in ``dim`` otherwise.