Random

numqi.random

This module use random seed widely, most likely you will get different results. Most functions accept seed as an argument, you can set it to a fixed value to get reproducible results.

quantum state

numqi.random.rand_haar_state(dim, tag_complex=True, batch_size=None, seed=None)

Return a random state vector from the Haar measure on the unit sphere in \(\mathbb{C}^{d}\).

\[\left\{ |\psi \rangle \in \mathbb{C} ^d\,\,: \left\| |\psi \rangle \right\| _2=1 \right\}\]

reference: qetlab/RandomStateVector

Parameters:

Name	Type	Description	Default
dim	int	The dimension of the Hilbert space that the state should be sampled from.	required
tag_complex	bool	If True, use complex normal distribution. If False, use real normal distribution.	True
batch_size	(int, None)	If None, return a single state vector. If int, return a batch of state vectors.	None
seed	([None], int, RandomState)	If int or RandomState, use it for RNG. If None, use default RNG.	None

Returns:

Name	Type	Description
ret	ndarray	shape=(dim,), dtype=np.complex128

numqi.random.rand_bipartite_state(dimA, dimB=None, k=None, seed=None, return_dm=False)

Generate random bipartite pure state

\[\left\{ |\psi \rangle \in \mathbb{C} ^{d_1d_2}\,\,: \left\| |\psi \rangle \right\| _2=1 \right\}\]

see also qetlab/RandomStateVector

Parameters:

Name	Type	Description	Default
dimA	int	dimension of subsystem A	required
dimB	(int, None)	dimension of subsystem B, if None, dimB=dimA	None
k	int	rank of the state	None
seed	(int, None, RandomState)	random seed	None
return_dm	bool	if True, return density matrix, otherwise return state vector (default)	False

Returns:

Name	Type	Description
ret	ndarray	if return_dm=True, density matrix, shape=(dimAdimB, dimAdimB), dtype=complex128 if return_dm=False, state vector, shape=(dimA*dimB,), dtype=complex128

density matrix

numqi.random.rand_density_matrix(dim, k=None, kind='haar', seed=None)

Generate random density matrix

\[\left\{ \rho \in \mathbb{C} ^{d\times d}\,: \rho \succeq 0,\mathrm{Tr}\left[ \rho \right] =1 \right\}\]

Parameters:

Name	Type	Description	Default
dim	int	The dimension of the Hilbert space that the state should be sampled from.	required
k	int	The rank of the density matrix. If None, k=dim.	None
kind	str	'haar' or 'bures'	'haar'
seed	([None], int, RandomState)	If int or RandomState, use it for RNG. If None, use default RNG.	None

see also: qetlab/RandomDensityMatrix

Returns:

Name	Type	Description
ret	ndarray	shape=(dim,dim), dtype=np.complex128

numqi.random.rand_separable_dm(dimA, dimB=None, k=2, seed=None, pure_term=False)

Generate random separable density matrix

\[\left\{ \rho \in \mathbb{C} ^{d_1d_2\times d_1d_2}\,\,: \rho =\sum_k{p_i\rho _{i}^{\left( A \right)}\otimes \rho _{i}^{\left( B \right)}} \right\}\]

Parameters:

Name	Type	Description	Default
dimA	int	dimension of subsystem A	required
dimB	(int, None)	dimension of subsystem B, if None, dimB=dimA	None
k	int	number of terms in the separable state	2
seed	(int, None, RandomState)	random seed	None
pure_term	bool	if True, each term is a pure state, otherwise each term is a density matrix	False

Returns:

Name	Type	Description
ret	ndarray	density matrix, shape=(dimAdimB, dimAdimB), dtype=complex128

hermitian matrix

numqi.random.rand_hermitian_matrix(d, eig=None, tag_complex=True, seed=None)

Generate random Hermitian matrix

\[\left\{ H\in \mathbb{C} ^{d\times d}\,\,: H=H^{\dagger } \right\}\]

Parameters:

Name	Type	Description	Default
d	int	dimension of matrix	required
eig	(None, tuple)	eigenvalue range (min_eig,max_eig), if None, eigenvalue is not constrained	None
tag_complex	bool	If True, ret is a complex Hermitian matrix. If False, ret is a real symmetric matrix.	True
seed	(None, int, RandomState)	If int or RandomState, use it for RNG. If None, use default RNG.	None

Returns:

Name	Type	Description
ret	ndarray	shape=(d,d), dtype=np.complex128 if tag_complex=True else np.float64

unitary matrix

numqi.random.rand_haar_unitary(dim, batch_size=None, seed=None)

Return a random unitary matrix from the Haar measure on the unitary group \(U(N)\).

also see qetlab-link pennylane-docs

Parameters:

Name	Type	Description	Default
dim	int	the column (row) of matrix	required
batch_size	(int, None)	If None, return a single matrix. If int, return a batch of matrices.	None
seed	([None], int, RandomState)	If int or RandomState, use it for RNG. If None, use default RNG.	None

Returns:

Name	Type	Description
ret	ndarray	shape=(dim,dim), dtype=np.complex128

numqi.random.rand_special_orthogonal_matrix(dim, batch_size=None, tag_complex=False, seed=None)

generate random special orthogonal matrix

Parameters:

Name	Type	Description	Default
dim	int	the column (row) of matrix	required
batch_size	(int, None)	If None, return a single matrix. If int, return a batch of matrices.	None
tag_complex	bool	If True, ret is a special unitary matrix. If False, ret is a special orthogonal matrix.	False
seed	([None], int, RandomState)	If int or RandomState, use it for RNG. If None, use default RNG.	None

Returns:

Name	Type	Description
ret	ndarray	shape=(batch_size,dim,dim), dtype=np.complex128 if tag_complex=True else np.float64

numqi.random.rand_Stiefel_matrix(dim, rank, iscomplex=False, batch_size=None, seed=None)

Generate random Stiefel matrix

wiki-link

Parameters:

Name	Type	Description	Default
dim	int	dimension of the matrix	required
rank	int	rank of the matrix	required
iscomplex	bool	If True, ret is a complex Stiefel matrix. If False, ret is a real Stiefel matrix.	False
batch_size	(None, int)	If None, return a single matrix. If int, return a batch of matrices.	None
seed	(int, None, RandomState)	random seed	None

Returns:

Name	Type	Description
ret	ndarray	shape=(batch_size,dim,rank), dtype=np.float64 if iscomplex=False else np.complex128

quantum channel

numqi.random.rand_kraus_op(num_term, dim_in, dim_out, tag_complex=True, seed=None)

Generate random Kraus operator

\[ \lbrace K\in \mathbb{C} ^{k\times d_o\times d_i}\,\,: \sum_s{K_{s}^{\dagger}K_s}=I_{d_i} \rbrace \]

Parameters:

Name	Type	Description	Default
num_term	int	number of terms in the Kraus operator	required
dim_in	int	dimension of input space	required
dim_out	int	dimension of output space	required
tag_complex	bool	If True, ret is a complex Kraus operator. If False, ret is a real Kraus operator.	True
seed	(int, None, RandomState)	random seed	None

Returns:

Name	Type	Description
ret	ndarray	shape=(num_term,dim_out,dim_in), dtype=np.complex128 if tag_complex=True else np.float64

numqi.random.rand_choi_op(dim_in, dim_out, rank=None, seed=None)

Generate random Choi operator

\[ \lbrace C\in \mathbb{C} ^{d_id_o\times d_id_o}\,\,:C\succeq 0,\mathrm{Tr}_{d_o}\left[ C \right] =I_{d_i} \rbrace \]

Parameters:

Name	Type	Description	Default
dim_in	int	dimension of input space	required
dim_out	int	dimension of output space	required
seed	(int, None, RandomState)	random seed	None

Returns:

Name	Type	Description
ret	ndarray	shape=(dim_in*dim_out,dim_in*dim_out), dtype=np.complex128 A reasonable reshape is ret.reshape(dim_in,dim_out,dim_in,dim_out)

finite field F2

numqi.random.rand_F2(*size, not_zero=False, not_one=False, seed=None)

generate random uint8 binary ndarray with shape size and values in {0,1}

Parameters:

Name	Type	Description	Default
*size	tuple of int	shape of the ndarray	()
not_zero	bool	if True, the generated ndarray cannot be all zero	False
not_one	bool	if True, the generated ndarray cannot be all one	False
seed	(int, None, Generator)	seed for the random number generator	None

Returns:

Name	Type	Description
ret	ndarray	random uint8 binary ndarray with shape size and values in {0,1}

numqi.random.rand_SpF2(n, return_kind='matrix', seed=None)

generate random Symplectic matrix over finite field F2

Parameters:

Name	Type	Description	Default
n	int	half of the column/row of the matrix	required
return_kind	str	return kind, one of {'matrix', 'int_tuple', 'int_tuple-matrix'}	'matrix'
seed	(int, None, Generator)	seed for the random number generator	None

Returns:

Name	Type	Description
ret	(ndarray, tuple[int], tuple[int, ndarray])	random Symplectic matrix over finite field F2 if return_kind=='matrix', return a matrix. shape=(2n,2n) if return_kind=='int_tuple', return a integer tuple representation. length=2*n if return_kind=='int_tuple-matrix', return a integer tuple representation and a matrix

numqi.random.rand_Clifford_group(n, seed=None)

generate random Clifford group element in the symplectic representation

Parameters:

Name	Type	Description	Default
n	int	half of the column/row of the matrix	required
seed	(int, None, Generator)	seed for the random number generator	None

Returns:

Name	Type	Description
cli_r	ndarray	shape (2n,)
cli_mat	ndarray	shape (2n,2n)

numqi.random.rand_pauli(n, is_hermitian=None, seed=None)

generate random Pauli operator

Parameters:

Name	Type	Description	Default
n	int	number of qubits	required
is_hermitian	bool	if True, the returned Pauli operator is Hermitian, if False, anti-Hermitian, if None, either Hermitian or anti-Hermitian	None
seed	(int, None, Generator)	seed for the random number generator	None

Returns:

Name	Type	Description
pauli	PauliOperator	random Pauli operator

miscellaneous

numqi.random.get_random_rng(rng_or_seed=None)

Get random.Random object

Parameters:

Name	Type	Description	Default
rng_or_seed	([None], int, Random)	If int or Random, use it for RNG. If None, use default RNG.	None

Returns:

Name	Type	Description
ret	Random	random.Random object

numqi.random.get_numpy_rng(rng_or_seed=None)

Get numpy.random.Generator object

Parameters:

Name	Type	Description	Default
rng_or_seed	([None], int, Generator)	If int or Generator, use it for RNG. If None, use default RNG.	None

Returns:

Name	Type	Description
ret	Generator	numpy.random.Generator object

numqi.random.rand_discrete_probability(dim, batch_size=None, seed=None)

Generate random discrete probability distribution

Parameters:

Name	Type	Description	Default
dim	int	number of outcomes	required
batch_size	(None, int)	If None, return a single distribution. If int, return a batch of distributions.	None
seed	(int, None, RandomState)	random seed	None

Returns:

Name	Type	Description
ret	ndarray	shape=(batch_size,dim), dtype=np.float64

numqi.random.rand_n_sphere(dim, size=None, seed=None)

Generate random vector from n-sphere

wiki-link

Parameters:

Name	Type	Description	Default
dim	int	dimension of the vector	required
size	(None, int, tuple)	size of the output array	None
seed	(int, None, RandomState)	random seed	None

Returns:

Name	Type	Description
ret	ndarray	shape=size+(dim,), dtype=np.float64

numqi.random.rand_n_ball(dim, size=None, seed=None)

Generate random vector from n-ball

Ball wiki-link

Box-Muller transform: wiki-link

stackexchange-link

Parameters:

Name	Type	Description	Default
dim	int	dimension of the vector	required
size	(None, int, tuple)	size of the output array	None
seed	(int, None, RandomState)	random seed	None

Returns:

Name	Type	Description
ret	ndarray	shape=size+(dim,), dtype=np.float64

numqi.random.rand_adjacent_matrix(dim, seed=None)

Generate random adjacent matrix of undirected graph

Parameters:

Name	Type	Description	Default
dim	int	number of verteces	required
seed	(int, None, RandomState)	random seed	None

Returns:

Name	Type	Description
ret	ndarray	adjacent matrix, shape=(dim,dim), dtype=np.uint8

numqi.random.rand_povm(dim, num_term, seed=None)

generate random positive operator-valued measure (POVM)

Parameters:

Name	Type	Description	Default
dim	int	dimension of the Hilbert space	required
num_term	int	number of terms in the POVM	required
seed	(int, None, RandomState)	random seed	None

Returns:

Name	Type	Description
ret	ndarray	shape=(num_term,dim,dim), dtype=np.float64