Source code for qutip.random_objects

# -*- coding: utf-8 -*-
# The above line is so that UTF-8 comments won't break Py2.

# This file is part of QuTiP: Quantum Toolbox in Python.
#
#    Copyright (c) 2011 and later, Paul D. Nation and Robert J. Johansson.
#    All rights reserved.
#
#    Redistribution and use in source and binary forms, with or without
#    modification, are permitted provided that the following conditions are
#    met:
#
#    1. Redistributions of source code must retain the above copyright notice,
#       this list of conditions and the following disclaimer.
#
#    2. Redistributions in binary form must reproduce the above copyright
#       notice, this list of conditions and the following disclaimer in the
#       documentation and/or other materials provided with the distribution.
#
#    3. Neither the name of the QuTiP: Quantum Toolbox in Python nor the names
#       of its contributors may be used to endorse or promote products derived
#       from this software without specific prior written permission.
#
#    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
#    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
#    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
#    PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
#    HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
#    SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
#    LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
#    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
#    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
#    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
#    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
###############################################################################
"""
This module is a collection of random state and operator generators.
The sparsity of the ouput Qobj's is controlled by varing the
`density` parameter.
"""

__all__ = [
    'rand_herm', 'rand_unitary', 'rand_ket', 'rand_dm',
    'rand_unitary_haar', 'rand_ket_haar', 'rand_dm_ginibre',
    'rand_dm_hs', 'rand_super_bcsz', 'rand_stochastic', 'rand_super'
]

from scipy import arcsin, sqrt, pi
from scipy.linalg import sqrtm
import numpy as np
import numpy.linalg as la
import scipy.sparse as sp
from qutip.qobj import Qobj
from qutip.operators import create, destroy, jmat
from qutip.states import basis
import qutip.superop_reps as sr


UNITS = np.array([1, 1j])


def rand_jacobi_rotation(A):
    """Random Jacobi rotation of a sparse matrix.
    
    Parameters
    ----------
    A : spmatrix
        Input sparse matrix.
    
    Returns
    -------
    spmatrix
        Rotated sparse matrix.
    """
    if A.shape[0]!=A.shape[1]:
        raise Exception('Input matrix must be square.')
    n = A.shape[0]
    angle = 2*np.random.random()*np.pi
    a = 1.0/np.sqrt(2)*np.exp(-1j*angle)
    b = 1.0/np.sqrt(2)*np.exp(1j*angle)
    i = np.int(np.floor(np.random.random()*n))
    j = i
    while (i==j):
        j = np.int(np.floor(np.random.random()*n))
    data = np.hstack((np.array([a,-b,a,b],dtype=complex),np.ones(n-2,dtype=complex)))
    diag = np.delete(np.arange(n),[i,j])
    rows = np.hstack(([i,i,j,j],diag))
    cols = np.hstack(([i,j,i,j],diag))
    R = sp.coo_matrix((data,(rows,cols)),shape=[n,n], dtype=complex).tocsr()
    A = R*A*R.conj().transpose()
    return A

def randnz(shape, norm=1 / np.sqrt(2)):
    # This function is intended for internal use.
    """
    Returns an array of standard normal complex random variates.
    The Ginibre ensemble corresponds to setting ``norm = 1`` [Mis12]_.

    Parameters
    ----------
    shape : tuple
        Shape of the returned array of random variates.
    norm : float
        Scale of the returned random variates, or 'ginibre' to draw
        from the Ginibre ensemble.
    """
    if norm == 'ginibre':
        norm = 1
    return np.sum(np.random.randn(*(shape + (2,))) * UNITS, axis=-1) * norm


[docs]def rand_herm(N, density=0.75, dims=None, pos_def=False): """Creates a random NxN sparse Hermitian quantum object. If 'N' is an integer, uses :math:`H=0.5*(X+X^{+})` where :math:`X` is a randomly generated quantum operator with a given `density`. Else uses complex Jacobi rotations when 'N' is given by an array. Parameters ---------- N : int, list/ndarray If int, then shape of output operator. If list/ndarray then eigenvalues of generated operator. density : float Density between [0,1] of output Hermitian operator. dims : list Dimensions of quantum object. Used for specifying tensor structure. Default is dims=[[N],[N]]. pos_def : bool (default=False) Return a positive semi-definite matrix (by diagonal dominance). Returns ------- oper : qobj NxN Hermitian quantum operator. Note ---- If given a list/ndarray as input 'N', this function returns a random Hermitian object with eigenvalues given in the list/ndarray. This is accomplished via complex Jacobi rotations. While this method is ~50% faster than the corresponding (real only) Matlab code, it should not be repeatedly used for generating matrices larger than ~1000x1000. """ if isinstance(N,(np.ndarray,list)): M = sp.diags(N,0, dtype=complex, format='csr') N = len(N) if dims: _check_dims(dims, N, N) nvals = N**2*density while M.nnz < 0.95*nvals: M = rand_jacobi_rotation(M) elif isinstance(N, (int, np.int32, np.int64)): if dims: _check_dims(dims, N, N) num_elems = np.int(np.ceil(N*(N+1)*density)/2) data = (2*np.random.rand(num_elems)-1)+1j*(2*np.random.rand(num_elems)-1) row_idx = np.random.choice(N, num_elems) col_idx = np.random.choice(N, num_elems) M = sp.coo_matrix((data, (row_idx,col_idx)), dtype=complex, shape=(N,N)).tocsr() M = 0.5*(M+M.conj().transpose()) if pos_def: M = M.tocoo() M.setdiag(np.abs(M.diagonal())+np.sqrt(2)*N) M = M.tocsr() else: raise TypeError('Input N must be an integer or array_like.') M.sort_indices() if dims: return Qobj(M, dims=dims) else: return Qobj(M)
[docs]def rand_unitary(N, density=0.75, dims=None): """Creates a random NxN sparse unitary quantum object. Uses :math:`\exp(-iH)` where H is a randomly generated Hermitian operator. Parameters ---------- N : int Shape of output quantum operator. density : float Density between [0,1] of output Unitary operator. dims : list Dimensions of quantum object. Used for specifying tensor structure. Default is dims=[[N],[N]]. Returns ------- oper : qobj NxN Unitary quantum operator. """ if dims: _check_dims(dims, N, N) U = (-1.0j * rand_herm(N, density)).expm() U.data.sort_indices() if dims: return Qobj(U, dims=dims, shape=[N, N]) else: return Qobj(U)
[docs]def rand_unitary_haar(N=2, dims=None): """ Returns a Haar random unitary matrix of dimension ``dim``, using the algorithm of [Mez07]_. Parameters ---------- N : int Dimension of the unitary to be returned. dims : list of lists of int, or None Dimensions of quantum object. Used for specifying tensor structure. Default is dims=[[N],[N]]. Returns ------- U : Qobj Unitary of dims ``[[dim], [dim]]`` drawn from the Haar measure. """ if dims is not None: _check_dims(dims, N, N) else: dims = [[N], [N]] # Mez01 STEP 1: Generate an N × N matrix Z of complex standard # normal random variates. Z = randnz((N, N)) # Mez01 STEP 2: Find a QR decomposition Z = Q · R. Q, R = la.qr(Z) # Mez01 STEP 3: Create a diagonal matrix Lambda by rescaling # the diagonal elements of R. Lambda = np.diag(R).copy() Lambda /= np.abs(Lambda) # Mez01 STEP 4: Note that R' := Λ¯¹ · R has real and # strictly positive elements, such that # Q' = Q · Λ is Haar distributed. # NOTE: Λ is a diagonal matrix, represented as a vector # of the diagonal entries. Thus, the matrix dot product # is represented nicely by the NumPy broadcasting of # the *scalar* multiplication. In particular, # Q · Λ = Q_ij Λ_jk = Q_ij δ_jk λ_k = Q_ij λ_j. # As NumPy arrays, Q has shape (N, N) and # Lambda has shape (N, ), such that the broadcasting # represents precisely Q_ij λ_j. U = Qobj(Q * Lambda) U.dims = dims return U
[docs]def rand_ket(N, density=1, dims=None): """Creates a random Nx1 sparse ket vector. Parameters ---------- N : int Number of rows for output quantum operator. density : float Density between [0,1] of output ket state. dims : list Left-dimensions of quantum object. Used for specifying tensor structure. Default is dims=[[N]]. Returns ------- oper : qobj Nx1 ket state quantum operator. """ if dims: _check_ket_dims(dims, N) X = sp.rand(N, 1, density, format='csr') X.data = X.data - 0.5 Y = X.copy() Y.data = 1.0j * (np.random.random(len(X.data)) - 0.5) X = X + Y X.sort_indices() X = Qobj(X) if dims: return Qobj(X / X.norm(), dims=dims) else: return Qobj(X / X.norm())
[docs]def rand_ket_haar(N=2, dims=None): """ Returns a Haar random pure state of dimension ``dim`` by applying a Haar random unitary to a fixed pure state. Parameters ---------- N : int Dimension of the state vector to be returned. dims : list of ints, or None Left-dimensions of the resultant quantum object. If None, [N] is used. Returns ------- psi : Qobj A random state vector drawn from the Haar measure. """ if dims: _check_ket_dims(dims, N) else: dims = [[N],[1]] psi = rand_unitary_haar(N) * basis(N, 0) psi.dims = dims return psi
[docs]def rand_dm(N, density=0.75, pure=False, dims=None): """Creates a random NxN density matrix. Parameters ---------- N : int, ndarray, list If int, then shape of output operator. If list/ndarray then eigenvalues of generated density matrix. density : float Density between [0,1] of output density matrix. dims : list Dimensions of quantum object. Used for specifying tensor structure. Default is dims=[[N],[N]]. Returns ------- oper : qobj NxN density matrix quantum operator. Notes ----- For small density matrices., choosing a low density will result in an error as no diagonal elements will be generated such that :math:`Tr(\\rho)=1`. """ if isinstance(N,(np.ndarray,list)): if np.abs(np.sum(N)-1.0) > 1e-15: raise ValueError('Eigenvalues of a density matrix must sum to one.') H = sp.diags(N,0, dtype=complex, format='csr') N = len(N) if dims: _check_dims(dims, N, N) nvals = N**2*density while H.nnz < 0.95*nvals: H = rand_jacobi_rotation(H) H.sort_indices() elif isinstance(N, (int, np.int32, np.int64)): if dims: _check_dims(dims, N, N) if pure: dm_density = sqrt(density) psi = rand_ket(N, dm_density) H = psi * psi.dag() H.data.sort_indices() else: non_zero = 0 tries = 0 while non_zero == 0 and tries < 10: H = rand_herm(N, density) H = H.dag() * H non_zero = H.tr() tries += 1 if tries >= 10: raise ValueError( "Requested density is too low to generate density matrix.") H = H / H.tr() H.data.sort_indices() else: raise TypeError('Input N must be an integer or array_like.') if dims: return Qobj(H, dims=dims) else: return Qobj(H)
[docs]def rand_dm_ginibre(N=2, rank=None, dims=None): """ Returns a Ginibre random density operator of dimension ``dim`` and rank ``rank`` by using the algorithm of [BCSZ08]_. If ``rank`` is `None`, a full-rank (Hilbert-Schmidt ensemble) random density operator will be returned. Parameters ---------- N : int Dimension of the density operator to be returned. dims : list Dimensions of quantum object. Used for specifying tensor structure. Default is dims=[[N],[N]]. rank : int or None Rank of the sampled density operator. If None, a full-rank density operator is generated. Returns ------- rho : Qobj An N × N density operator sampled from the Ginibre or Hilbert-Schmidt distribution. """ if rank is None: rank = N if rank > N: raise ValueError("Rank cannot exceed dimension.") X = randnz((N, rank), norm='ginibre') rho = np.dot(X, X.T.conj()) rho /= np.trace(rho) return Qobj(rho, dims=dims)
[docs]def rand_dm_hs(N=2, dims=None): """ Returns a Hilbert-Schmidt random density operator of dimension ``dim`` and rank ``rank`` by using the algorithm of [BCSZ08]_. Parameters ---------- N : int Dimension of the density operator to be returned. dims : list Dimensions of quantum object. Used for specifying tensor structure. Default is dims=[[N],[N]]. Returns ------- rho : Qobj A dim × dim density operator sampled from the Ginibre or Hilbert-Schmidt distribution. """ return rand_dm_ginibre(N, rank=None, dims=dims)
def rand_kraus_map(N, dims=None): """ Creates a random CPTP map on an N-dimensional Hilbert space in Kraus form. Parameters ---------- N : int Length of input/output density matrix. dims : list Dimensions of quantum object. Used for specifying tensor structure. Default is dims=[[N],[N]]. Returns ------- oper_list : list of qobj N^2 x N x N qobj operators. """ if dims: _check_dims(dims, N, N) # Random unitary (Stinespring Dilation) big_unitary = rand_unitary(N ** 3).data.todense() orthog_cols = np.array(big_unitary[:, :N]) oper_list = np.reshape(orthog_cols, (N ** 2, N, N)) return list(map(lambda x: Qobj(inpt=x, dims=dims), oper_list))
[docs]def rand_super(N=5, dims=None): """ Returns a randomly drawn superoperator acting on operators acting on N dimensions. Parameters ---------- N : int Square root of the dimension of the superoperator to be returned. dims : list Dimensions of quantum object. Used for specifying tensor structure. Default is dims=[[[N],[N]], [[N],[N]]]. """ if dims is not None: # TODO: check! pass else: dims = [[[N],[N]], [[N],[N]]] H = rand_herm(N) S = propagator(H, np.random.rand(), [ create(N), destroy(N), jmat(float(N - 1) / 2.0, 'z') ]) S.dims = dims return S
[docs]def rand_super_bcsz(N=2, enforce_tp=True, rank=None, dims=None): """ Returns a random superoperator drawn from the Bruzda et al ensemble for CPTP maps [BCSZ08]_. Note that due to finite numerical precision, for ranks less than full-rank, zero eigenvalues may become slightly negative, such that the returned operator is not actually completely positive. Parameters ---------- N : int Square root of the dimension of the superoperator to be returned. enforce_tp : bool If True, the trace-preserving condition of [BCSZ08]_ is enforced; otherwise only complete positivity is enforced. rank : int or None Rank of the sampled superoperator. If None, a full-rank superoperator is generated. dims : list Dimensions of quantum object. Used for specifying tensor structure. Default is dims=[[[N],[N]], [[N],[N]]]. Returns ------- rho : Qobj A superoperator acting on vectorized dim × dim density operators, sampled from the BCSZ distribution. """ if dims is not None: # TODO: check! pass else: dims = [[[N],[N]], [[N],[N]]] if rank is None: rank = N**2 if rank > N**2: raise ValueError("Rank cannot exceed superoperator dimension.") # We use mainly dense matrices here for speed in low # dimensions. In the future, it would likely be better to switch off # between sparse and dense matrices as the dimension grows. # We start with a Ginibre uniform matrix X of the appropriate rank, # and use it to construct a positive semidefinite matrix X X⁺. X = randnz((N**2, rank), norm='ginibre') # Precompute X X⁺, as we'll need it in two different places. XXdag = np.dot(X, X.T.conj()) if enforce_tp: # We do the partial trace over the first index by using dense reshape # operations, so that we can avoid bouncing to a sparse representation # and back. Y = np.einsum('ijik->jk', XXdag.reshape((N, N, N, N))) # Now we have the matrix 𝟙 ⊗ Y^{-1/2}, which we can find by doing # the square root and the inverse separately. As a possible improvement, # iterative methods exist to find inverse square root matrices directly, # as this is important in statistics. Z = np.kron( np.eye(N), sqrtm(la.inv(Y)) ) # Finally, we dot everything together and pack it into a Qobj, # marking the dimensions as that of a type=super (that is, # with left and right compound indices, each representing # left and right indices on the underlying Hilbert space). D = Qobj(np.dot(Z, np.dot(XXdag, Z))) else: D = N * Qobj(XXdag / np.trace(XXdag)) D.dims = [ # Left dims [[N], [N]], # Right dims [[N], [N]] ] # Since [BCSZ08] gives a row-stacking Choi matrix, but QuTiP # expects a column-stacking Choi matrix, we must permute the indices. D = D.permute([[1], [0]]) D.dims = dims # Mark that we've made a Choi matrix. D.superrep = 'choi' return sr.to_super(D)
def rand_stochastic(N, density=0.75, kind='left', dims=None): """Generates a random stochastic matrix. Parameters ---------- N : int Dimension of matrix. density : float Density between [0,1] of output density matrix. kind : str (Default = 'left') Generate 'left' or 'right' stochastic matrix. dims : list Dimensions of quantum object. Used for specifying tensor structure. Default is dims=[[N],[N]]. Returns ------- oper : qobj Quantum operator form of stochastic matrix. """ if dims: _check_dims(dims, N, N) num_elems = np.int(np.ceil(N*(N+1)*density)/2) data = np.random.rand(num_elems) row_idx = np.random.choice(N, num_elems) col_idx = np.random.choice(N, num_elems) if kind=='left': M = sp.coo_matrix((data, (row_idx,col_idx)), dtype=float, shape=(N,N)).tocsc() else: M = sp.coo_matrix((data, (row_idx,col_idx)), dtype=float, shape=(N,N)).tocsr() M = 0.5*(M+M.conj().transpose()) if kind=='left': num_cols = M.indptr.shape[0]-1 for col in range(num_cols): col_start = M.indptr[col] col_end = M.indptr[col+1] col_sum = np.sum(M.data[col_start:col_end]) M.data[col_start:col_end] /= col_sum M = M.tocsr() else: num_rows = M.indptr.shape[0]-1 for row in range(num_rows): row_start = M.indptr[row] row_end = M.indptr[row+1] row_sum = np.sum(M.data[row_start:row_end]) M.data[row_start:row_end] /= row_sum if dims: return Qobj(M, dims=dims, shape=[N, N]) else: return Qobj(M) def _check_ket_dims(dims, N1): if (not isinstance(dims, list)) or (not isinstance(dims[0], list)): raise TypeError("Left and right Qobj dimensions must be lists of ints. E.g.: [2, 3].") if np.prod(dims) != N1: raise ValueError("Qobj dimensions must match matrix shape.") def _check_dims(dims, N1, N2): if len(dims) != 2: raise Exception("Qobj dimensions must be list of length 2.") if (not isinstance(dims[0], list)) or (not isinstance(dims[1], list)): raise TypeError( "Qobj dimension components must be lists. i.e. dims=[[N],[N]]") if np.prod(dims[0]) != N1 or np.prod(dims[1]) != N2: raise ValueError("Qobj dimensions must match matrix shape.") if len(dims[0]) != len(dims[1]): raise TypeError("Qobj dimension components must have same length.") # TRAILING IMPORTS # qutip.propagator depends on rand_dm, so we need to put this import last. from qutip.propagator import propagator