feat: added random_states func + tests

docs/rand.rst

@@ -15,4 +15,5 @@ Random
     toqito.rand.random_ginibre
     toqito.rand.random_povm
     toqito.rand.random_state_vector
+    toqito.rand.random_states
     toqito.rand.random_unitary

pyproject.toml

@@ -24,6 +24,7 @@ numpy = "1.26.2"
 scipy = "1.11.4"
 #scs = "3.2.4.post1"
 picos = "2.4.17"
+qiskit = "0.45.1"
 
 [tool.poetry.dev-dependencies]
 distlib = "0.3.8"

toqito/rand/__init__.py

@@ -4,3 +4,4 @@
 from toqito.rand.random_ginibre import random_ginibre
 from toqito.rand.random_povm import random_povm
 from toqito.rand.random_state_vector import random_state_vector
+from toqito.rand.random_states import random_states

toqito/rand/random_states.py

@@ -0,0 +1,35 @@
+"""Generate random quantum states using Qiskit."""
+
+import numpy as np
+from qiskit.quantum_info.states.random import random_statevector
+
+
+def random_states(n: int, d: int) -> list[np.ndarray]:
+    r"""Generate a list of random quantum states.
+
+    This function utilizes Qiskit's `random_statevector` to generate a list of quantum states,
+    each of a specified dimension. The states are valid quantum states distributed according
+    to the Haar measure.
+
+    Examples
+    ==========
+    Generating three quantum states each of dimension 4.
+
+    >>> from this_module import random_states
+    >>> states = random_states(3, 4)
+    >>> len(states)
+    3
+    >>> states[0].shape
+    (4, 1)
+
+
+    :param n: int
+        The number of random states to generate.
+    :param d: int
+        The dimension of each quantum state.
+
+    :return: list[numpy.ndarray]
+        A list of `n` numpy arrays, each representing a d-dimensional quantum state as a
+        column vector.
+    """
+    return [random_statevector(d).data.reshape(-1, 1) for _ in range(n)]

toqito/rand/tests/test_random_states.py

@@ -0,0 +1,36 @@
+"""Test random_states."""
+import numpy as np
+import pytest
+
+from toqito.rand import random_states
+from toqito.state_props import is_pure
+
+
+@pytest.mark.parametrize(
+    "num_states, dim",
+    [
+        # Test with a single quantum state of dimension 2.
+        (1, 2),
+        # Test with multiple quantum states of the same dimension.
+        (3, 2),
+        # Test with a single quantum state of higher dimension.
+        (1, 4),
+        # Test with multiple quantum states of higher dimension.
+        (2, 4),
+    ],
+)
+def test_random_states(num_states, dim):
+    """Test for random_states function."""
+    # Generate a list of random quantum states.
+    states = random_states(num_states, dim)
+
+    # Ensure the number of states generated is as expected.
+    assert len(states) == num_states
+
+    # Check each state is a valid quantum state.
+    for state in states:
+        assert state.shape == (dim, 1)
+        # Convert state vector to density matrix.
+        dm = np.outer(state, np.conj(state))
+        # Verify each state is pure.
+        assert is_pure(dm)