numqi.manifold

numqi.manifold.PositiveReal

Bases: Module

__init__(batch_size=None, method='softplus', requires_grad=True, dtype=torch.float64, device=_CPU)

positive real number

Parameters:

Name	Type	Description	Default
batch_size	(int, None)	batch size.	None
method	str	method to map real vector to a positive real number. 'softplus': softplus function. 'exp': exponential function.	'softplus'
requires_grad	bool	whether to track the gradients of the parameters.	True
dtype	dtype	data type of the parameters, either torch.float32 or torch.float64	float64
device	device	device of the parameters.	_CPU

numqi.manifold.to_positive_real_softplus(theta)

map real vector to a positive real number using softplus function

Parameters:

Name	Type	Description	Default
theta	(ndarray, Tensor)	array of any shape.	required

Returns:

Name	Type	Description
ret	(ndarray, Tensor)	array of the same shape as theta.

numqi.manifold.to_positive_real_exp(theta)

map real vector to a positive real number using exponential function

Parameters:

Name	Type	Description	Default
theta	(ndarray, Tensor)	array of any shape.	required

Returns:

Name	Type	Description
ret	(ndarray, Tensor)	array of the same shape as theta.

numqi.manifold.OpenInterval

Bases: Module

__init__(lower, upper, batch_size=None, requires_grad=True, dtype=torch.float64, device=_CPU)

open interval manifold (lower,upper) using sigmoid function

Parameters:

Name	Type	Description	Default
lower	float	lower bound.	required
upper	float	upper bound.	required
requires_grad	bool	whether to track the gradients of the parameters.	True
dtype	dtype	data type of the parameters, either torch.float32 or torch.float64	float64
device	device	device of the parameters.	_CPU

numqi.manifold.to_open_interval(theta, lower, upper)

map a real number into a bounded interval (lower,upper) using sigmoid function

Parameters:

Name	Type	Description	Default
theta	(ndarray, tensor)	array of any shape.	required
lower	float	lower bound.	required
upper	float	upper bound.	required

Returns:

Name	Type	Description
ret	(ndarray, tensor)	array of the same shape as theta.

numqi.manifold.Trace1PSD

Bases: Module

__init__(dim, rank=None, batch_size=None, method='cholesky', requires_grad=True, dtype=torch.float64, device=_CPU)

positive semi-definite (PSD) matrix with trace 1 of rank rank using Cholesky decomposition

Parameters:

Name	Type	Description	Default
dim	int	dimension of the matrix.	required
rank	int	rank of the matrix.	None
batch_size	(int, None)	batch size.	None
method	str	method to map real vector to a PSD matrix. 'cholesky': Cholesky decomposition. 'ensemble': ensemble decomposition.	'cholesky'
requires_grad	bool	whether to track the gradients of the parameters.	True
dtype	dtype	data type of the parameters torch.float32 / torch.float64: real PSD matrix torch.complex64 / torch.complex128: complex PSD matrix	float64
device	device	device of the parameters.	_CPU

numqi.manifold.to_trace1_psd_ensemble(theta, dim, rank=None)

map real vector to a positive semi-definite (PSD) matrix with trace 1 using ensemble method

Parameters:

Name	Type	Description	Default
theta	(ndarray, Tensor)	if ndim>1, then the last dimension will be expanded to the matrix and the rest dimensions will be batch dimensions	required
dim	int	dimension of the matrix.	required
rank	int	rank of the matrix.	None

Returns:

Name	Type	Description
ret	(ndarray, Tensor)	array of shape theta.shape[:-1]+(dim,dim)

numqi.manifold.to_trace1_psd_cholesky(theta, dim, rank=None)

map real vector to a positive semi-definite (PSD) matrix with trace 1 of rank rank using Cholesky decomposition

Parameters:

Name	Type	Description	Default
theta	(ndarray, Tensor)	if ndim>1, then the last dimension will be expanded to the matrix and the rest dimensions will be batch dimensions.	required
dim	int	dimension of the matrix.	required
rank	int	rank of the matrix.	None

Returns:

Name	Type	Description
ret	(ndarray, Tensor)	array of shape theta.shape[:-1]+(dim,dim)

numqi.manifold.from_trace1_psd_cholesky(np0, rank, zero_eps=1e-10)

map a positive semi-definite (PSD) matrix with trace 1 of rank rank to a real vector using Cholesky decomposition

Parameters:

Name	Type	Description	Default
np0	ndarray	array of shape (dim,dim).	required
rank	int	rank of the matrix.	required
zero_eps	float	zero threshold.	1e-10

Returns:

Name	Type	Description
theta	ndarray	array of shape (dim*(2*dim-rank+1))//2 for real case or (2*dim*(dim-rank)) for complex case.

numqi.manifold.SymmetricMatrix

Bases: Module

__init__(dim, batch_size=None, is_trace0=False, is_norm1=False, requires_grad=True, dtype=torch.float64, device=_CPU)

symmetric matrix, hermitian, is_trace0, is_norm1

Parameters:

Name	Type	Description	Default
dim	int	dimension of the matrix.	required
batch_size	(int, None)	batch size.	None
is_trace0	bool	whether the trace of the matrix is 0.	False
is_norm1	bool	whether the frobenius norm of the matrix is 1.	False
requires_grad	bool	whether to track the gradients of the parameters.	True
dtype	dtype	data type of the parameters torch.float32 / torch.float64: real symmetric matrix torch.complex64 / torch.complex128: complex hermitian matrix	float64
device	device	device of the parameters.	_CPU

numqi.manifold.to_symmetric_matrix(theta, dim, is_trace0=False, is_norm1=False)

map real vector to a symmetric matrix

Parameters:

Name	Type	Description	Default
theta	(ndarray, Tensor)	if ndim>1, then the last dimension will be expanded to the matrix and the rest dimensions will be batch dimensions. symmetric matrix: (dim(dim+1))//2 hermitian matrix: dimdim traceless symmetric matrix: (dim(dim+1))//2-1 traceless hermitian matrix: dimdim-1	required
dim	int	dimension of the matrix.	required
is_trace0	bool	whether the trace of the matrix is 0.	False
is_norm1	bool	whether the frobenius norm of the matrix is 1.	False

Returns:

Name	Type	Description
ret	(ndarray, Tensor)	array of shape theta.shape[:-1]+(dim,dim)

numqi.manifold.Ball

Bases: Module

__init__(dim, batch_size=None, requires_grad=True, dtype=torch.float64, device=_CPU)

ball manifold

Parameters:

Name	Type	Description	Default
dim	int	dimension of the ball.	required
batch_size	(int, None)	batch size.	None
requires_grad	bool	whether to track the gradients of the parameters.	True
dtype	dtype	data type of the parameters, either torch.float32 or torch.float64	float64
device	device	device of the parameters.	_CPU

numqi.manifold.to_ball(theta, is_real=True)

map real vector to a point in the ball

Parameters:

Name	Type	Description	Default
theta	(ndarray, Tensor)	if ndim>1, then the last dimension will be expanded to the point and the rest dimensions will be batch dimensions.	required
is_real	bool	whether the output is real	True

Returns:

Name	Type	Description
ret	(ndarray, Tensor)	array of shape theta.shape[:-1]+(dim,)

numqi.manifold.Sphere

Bases: Module

__init__(dim, batch_size=None, method='quotient', requires_grad=True, dtype=torch.float64, device=_CPU)

sphere manifold

Parameters:

Name	Type	Description	Default
dim	int	size of point in Euclidean space, must be at least 2.	required
batch_size	(int, None)	batch size.	None
method	str	method to map real vector to a point on the sphere. 'quotient': quotient map. 'coordinate': cosine and sine functions.	'quotient'
requires_grad	bool	whether to track the gradients of the parameters.	True
dtype	dtype	data type of the parameters, either torch.float32 or torch.float64	float64
device	device	device of the parameters.	_CPU

numqi.manifold.to_sphere_quotient(theta, is_real=True)

map real vector to a point on the sphere via quotient

Parameters:

Name	Type	Description	Default
theta	(ndarray, Tensor)	if ndim>1, then the last dimension will be expanded to the point and the rest dimensions will be batch dimensions.	required
is_real	bool	whether the output is real	True

Returns:

Name	Type	Description
ret	(ndarray, Tensor)	array of shape theta.shape[:-1]+(dim,)

numqi.manifold.to_sphere_coordinate(theta, is_real=True)

map real vector to a point on the sphere via cosine and sine functions

reference: A Derivation of n-Dimensional Spherical Coordinates doi-link

Parameters:

Name	Type	Description	Default
theta	(ndarray, Tensor)	if ndim>1, then the last dimension will be expanded to the point and the rest dimensions will be batch dimensions.	required
is_real	bool	whether the output is real	True

Returns:

Name	Type	Description
ret	(ndarray, Tensor)	array of shape theta.shape[:-1]+(dim,)

numqi.manifold.DiscreteProbability

Bases: Module

__init__(dim, batch_size=None, method='softmax', weight=None, requires_grad=True, dtype=torch.float64, device=_CPU)

discrete probability distribution

Parameters:

Name	Type	Description	Default
dim	int	dimension of the probability vector.	required
batch_size	(int, None)	batch size.	None
method	str	method to map real vector to a probability vector. 'softmax': softmax function. 'sphere': quotient map.	'softmax'
weight	(ndarray, Tensor)	weight of each dimension.	None
requires_grad	bool	whether to track the gradients of the parameters.	True
dtype	dtype	data type of the parameters, either torch.float32 or torch.float64	float64
device	device	device of the parameters.	_CPU

numqi.manifold.to_discrete_probability_sphere(theta)

map real vector to a point on the discrete probability via square of sphere

Parameters:

Name	Type	Description	Default
theta	(ndarray, Tensor)	if ndim>1, then the last dimension will be expanded to the point and the rest dimensions will be batch dimensions.	required

Returns:

Name	Type	Description
ret	(ndarray, Tensor)	array of shape theta.shape

numqi.manifold.to_discrete_probability_softmax(theta)

map real vector to a probability vector using softmax function

Parameters:

Name	Type	Description	Default
theta	(ndarray, Tensor)	if ndim>1, then the last dimension will be expanded to the probability vector and the rest dimensions will be batch dimensions.	required

Returns:

Name	Type	Description
ret	(ndarray, Tensor)	array of shape theta.shape

numqi.manifold.Stiefel

Bases: Module

__init__(dim, rank, batch_size=None, method='polar', euler_with_phase=False, requires_grad=True, dtype=torch.float64, device=_CPU)

Stiefel manifold

Parameters:

Name	Type	Description	Default
dim	int	dimension of the matrix.	required
rank	int	rank of the matrix.	required
batch_size	(int, None)	batch size.	None
method	str	method to map real vector to a Stiefel matrix. 'choleskyL': Cholesky decomposition. 'euler': Euler-Hurwitz angles. 'qr': QR decomposition. 'polar': square root of a matrix. 'so-exp': exponential map of special orthogonal group. 'so-cayley': Cayley transform of special orthogonal group.	'polar'
euler_with_phase	bool	whether to append phase for method='euler'.	False
requires_grad	bool	whether to track the gradients of the parameters.	True
dtype	dtype	data type of the parameters torch.float32 / torch.float64: real Stiefel matrix torch.complex64 / torch.complex128: complex Stiefel matrix	float64
device	device	device of the parameters.	_CPU

numqi.manifold.to_stiefel_polar(theta, dim, rank)

map real vector to a Stiefel manifold via polar decomposition

wiki-link

\[ \left\{ x\in\mathbb{K}^{m\times n}:x^\dagger x=I_n \right\}\]

where \(\mathbb{K}=\mathbb{R}\) or \(\mathbb{C}\). Matrix square root is used so the backward might be several times slower than the forward. QR decomposition

Parameters:

Name	Type	Description	Default
theta	(ndarray, Tensor)	if ndim>1, then the last dimension will be expanded to the matrix and the rest dimensions will be batch dimensions.	required
dim	int	dimension of the matrix.	required
rank	int	rank of the matrix.	required

Returns:

Name	Type	Description
ret	(ndarray, Tensor)	array of shape theta.shape[:-1]+(dim,rank)

numqi.manifold.from_stiefel_polar(np0)

map a Stiefel manifold to real vector via polar decomposition

Parameters:

Name	Type	Description	Default
np0	ndarray	array of shape (dim,rank)	required

Returns:

Name	Type	Description
ret	ndarray	array of shape (dimrank) for real Stiefel, and (2dim*rank) for complex Stiefel.

numqi.manifold.to_stiefel_choleskyL(theta, dim, rank)

map real vector to a Stiefel manifold via Cholesky decomposition

minimum parameters but bad convergance

Parameters:

Name	Type	Description	Default
theta	(ndarray, Tensor)	the last dimension will be expanded to the matrix and the rest dimensions will be batch dimensions. For real case, the last dimension should be dim*rank-((rank*(rank+1))//2), and for complex case, the last dimension should be 2*dim*rank-rank*(rank+1).	required
dim	int	dimension of the matrix.	required
rank	int	rank of the matrix.	required

Returns:

Name	Type	Description
ret	(ndarray, Tensor)	array of shape theta.shape[:-1]+(dim,rank)

numqi.manifold.to_stiefel_qr(theta, dim, rank)

map real vector to a Stiefel manifold via QR decomposition

Parameters:

Name	Type	Description	Default
theta	(ndarray, Tensor)	the last dimension will be expanded to the matrix and the rest dimensions will be batch dimensions. For real case, the last dimension should be dim*rank, and for complex case, the last dimension should be 2*dim*rank.	required
dim	int	dimension of the matrix.	required
rank	int	rank of the matrix.	required

Returns:

Name	Type	Description
ret	(ndarray, Tensor)	array of shape theta.shape[:-1]+(dim,rank)

numqi.manifold.SpecialOrthogonal

Bases: Module

__init__(dim, batch_size=None, method='exp', cayley_order=2, requires_grad=True, dtype=torch.float64, device=_CPU)

orthogonal matrix

Parameters:

Name	Type	Description	Default
dim	int	dimension of the matrix.	required
batch_size	(int, None)	batch size.	None
method	str	method to map real vector to an orthogonal matrix. 'exp': exponential map. 'cayley': cayley transformation	'exp'
requires_grad	bool	whether to track the gradients of the parameters.	True
dtype	dtype	data type of the parameters torch.float32 / torch.float64: SO(d) manifold, torch.complex64 / torch.complex128: SU(d) manifold	float64
device	device	device of the parameters.	_CPU

\[ \mathrm{SU}(d)=\left\{ A\in\mathbb{C}^{d\times d}:\mathrm{det}(A)=1,AA^{\dagger}=I_{d}\right\} \]

\[ \mathrm{SO}(d)=\left\{ A\in\mathbb{R}^{d\times d}:\mathrm{det}(A)=1,AA^{T}=I_{d}\right\} \]

numqi.manifold.to_special_orthogonal_exp(theta, dim)

map real vector to a special orthogonal (unitary) manifold via exponential map

Parameters:

Name	Type	Description	Default
theta	(ndarray, Tensor)	if ndim>1, then the last dimension will be expanded to the matrix and the rest dimensions will be batch dimensions. special orthogonal matrix: (dim(dim-1))//2 special unitary matrix: dimdim-1	required
dim	int	dimension of the matrix.	required

Returns:

Name	Type	Description
ret	(ndarray, Tensor)	array of shape theta.shape[:-1]+(dim,dim)

numqi.manifold.to_special_orthogonal_cayley(theta, dim, order=2)

map real vector to a special orthogonal (unitary) manifold via Cayley transform

wiki/Cayley-transform

Parameters:

Name	Type	Description	Default
theta	(ndarray, Tensor)	if ndim>1, then the last dimension will be expanded to the matrix and the rest dimensions will be batch dimensions. special orthogonal matrix: (dim(dim-1))//2 special unitary matrix: dimdim-1	required
dim	int	dimension of the matrix.	required
order	int	order of the Cayley transformation.	2

Returns:

Name	Type	Description
ret	(ndarray, Tensor)	array of shape theta.shape[:-1]+(dim,dim)

numqi.manifold.quantum_state(dim, batch_size=None, method='quotient', requires_grad=True, dtype=torch.complex128, device=_CPU)

manifold of quantum state, wrapper of numqi.manifold.Sphere

Parameters:

Name	Type	Description	Default
dim	int	dimension of the quantum state	required
batch_size	int | None	batch size of quantum state	None
method	str	method to represent quantum state. 'quotient' or 'coordinates'	'quotient'
requires_grad	bool	whether to require gradient	True
dtype	dtype	data type of quantum state	complex128
device	device	device of quantum state	_CPU

Returns:

Name	Type	Description
ret	Sphere	manifold of quantum state.

numqi.manifold.density_matrix(dim, rank=None, batch_size=None, method='cholesky', requires_grad=True, dtype=torch.complex128, device=_CPU)

manifold of density matrix, wrapper of numqi.manifold.Trace1PSD

Parameters:

Name	Type	Description	Default
dim	int	dimension of the density matrix	required
rank	int | None	rank of the density matrix	None
batch_size	int | None	batch size of density matrix	None
method	str	method to represent density matrix, 'cholesky' or 'ensemble'	'cholesky'
requires_grad	bool	whether to require gradient	True
dtype	dtype	data type of density matrix	complex128
device	device	device of density matrix	_CPU

Returns:

Name	Type	Description
ret	Trace1PSD	manifold of density matrix.

numqi.manifold.SeparableDensityMatrix

Bases: Module

__init__(dimA, dimB, num_cha=None, batch_size=None, requires_grad=True, dtype=torch.complex128, device=_CPU)

manifold of separable density matrix

Parameters:

Name	Type	Description	Default
dimA	int	dimension of the first subsystem	required
dimB	int	dimension of the second subsystem	required
num_cha	int | None	number of product states	None
batch_size	int | None	batch size of density matrix	None
requires_grad	bool	whether to require gradient	True
dtype	dtype	data type of density matrix	complex128
device	device	device of density matrix	_CPU

numqi.manifold.quantum_gate(dim, batch_size=None, method='exp', cayley_order=2, requires_grad=True, dtype=torch.complex128, device=_CPU)

manifold of quantum gate, wrapper of numqi.manifold.SpecialOrthogonal

Parameters:

Name	Type	Description	Default
dim	int	dimension of the quantum gate	required
batch_size	int | None	batch size of quantum gate	None
method	str	method to represent quantum gate, 'exp' or 'cayley'	'exp'
cayley_order	int	order of Cayley transform	2
requires_grad	bool	whether to require gradient	True
dtype	dtype	data type of quantum gate	complex128
device	device	device of quantum gate	_CPU

Returns:

Name	Type	Description
ret	SpecialOrthogonal	manifold of quantum gate.

numqi.manifold.QuantumChannel

Bases: Module

__init__(dim_in, dim_out, choi_rank=None, batch_size=None, method='qr', euler_with_phase=False, return_kind='kraus', requires_grad=True, dtype=torch.complex128, device=_CPU)

manifold of quantum channel, wrapper of numqi.manifold.Stiefel

Parameters:

Name	Type	Description	Default
dim_in	int	dimension of the input quantum state	required
dim_out	int	dimension of the output quantum state	required
choi_rank	int | None	rank of the Choi matrix	None
batch_size	int | None	batch size of quantum channel	None
method	str	method to represent quantum channel, choleskyL / qr / polar / so-exp / so-cayley	'qr'
euler_with_phase	bool	whether to use Euler angles with phase	False
return_kind	str	return kind of quantum channel, 'kraus' or 'choi'	'kraus'
requires_grad	bool	whether to require gradient	True
dtype	dtype	data type of quantum channel	complex128
device	device	device of quantum channel	_CPU

numqi.manifold.StiefelManifoldDistanceModel (TODO)

numqi.manifold.GrassmannManifoldDistanceModel (TODO)

numqi.manifold.TwoHermitianSumModel (TODO)

TAG-LIST-ALL