Math 

static eye(total_dim, dim=None)

Constructs a new identity superoperator.

Parameters:

total_dim (int) – The total dimension the superoperator acts on, e.g. 16 for four qubits.
dim (int | NoneType) – The dimension of each subsystem this superoperator acts on, e.g. 2 for qubits. If None, the constructor will try to automatically infer the subsystem dimension by using auto_base().

Return type:

static random_bcsz(total_dim, rank=None, dim=None)

Constructs a new random superoperator drawn from the BCSZ distribution ([17]).

import trueq.math as tqm

s = tqm.Superop.random_bcsz(9, 5)
assert s.is_cptp
assert s.choi_rank == 5

Parameters:

total_dim (int) – The total dimension the superoperator acts on, e.g. 16 for four qubits.
dim (int | NoneType) – The dimension of each subsystem this superoperator acts on, e.g. 2 for qubits. If None, the constructor will try to automatically infer the subsystem dimension by using auto_base().
rank (int | NoneTye) – A positive integer specifying the output Choi rank. If None, then the value total_dim ** 2 is used. A value of 1 results in a random unitary superoperator.

Return type:

static random_constrained_cptp(total_dim, infidelity, coherent_fraction, equibility=1, rank=None, dim=None)

Constructs a random CPTP (see is_cptp) channel whose process infidelity and level of unitary are (approximately) given. This is done by composing a random unitary channel of fidelity coherent_fraction (see random_constrained_unitary()) with a random decoherent channel (see random_decoherent()) of infidelity (1 - coherent_fraction) * infidelity. The infidelity and stochastic infidelity of the resulting composition is accurate up to \(O(r^2)\) with \(r\) the infidelity, see [8].

import trueq.math as tqm

# random 2-qutrit gate
s = tqm.Superop.random_constrained_cptp(9, 0.01, 0.4)
assert s.is_cptp
print(s.infidelity, s.stochastic_infidelity)

0.009976033935446327 0.005997357403861647

Parameters:

total_dim (int) – The total dimension the superoperator acts on, e.g. 16 for four qubits.
infidelity (float) – The desired process infidelity; a number in \([0,1]\).
coherent_fraction (float) – The desired fraction of the process infidelity to be unitary or coherent in nature; a number in \([0,1]\).
equibility – A positive number indicating the equibility of the resulting channel in arbitrary units. A large value (say, 100) results in very uniform singular values of the leading kraus term, whereas they are more varied for a small value like 1.
rank (int | NoneTye) – A positive integer specifying the output Choi rank. If None, then the value total_dim ** 2 is used. A value of 1 results in a random unitary superoperator.
dim (int | NoneType) – The dimension of each subsystem this superoperator acts on, e.g. 2 for qubits. If None, the constructor will try to automatically infer the subsystem dimension by using auto_base().

Return type:

static random_constrained_unitary(total_dim, infidelity, dim=None)

Constructs a random unitary channel constrained to have the given process infidelity, see infidelity.

import trueq.math as tqm

s = tqm.Superop.random_constrained_unitary(9, 0.1)
assert s.is_unitary
assert abs(s.infidelity - 0.1) < 1e-10

Parameters:

total_dim (int) – The total dimension the superoperator acts on, e.g. 16 for four qubits.
infidelity (float) – The desired process infidelity; a number in \([0,1]\).
dim (int | NoneType) – The dimension of each subsystem this superoperator acts on, e.g. 2 for qubits. If None, the constructor will try to automatically infer the subsystem dimension by using auto_base().

Return type:

static random_decoherent(total_dim, infidelity, equibility=1, rank=None, dim=None)

Constructs a random decoherent channel with a given process infidelity (approximately), see infidelity. A decoherent channel is one whose polar decomposition of the leading Kraus term (see lkpd()) returns a unitary portion equal to the identity, i.e. the main unitary action of the channel is trivial. The infidelity of the resulting composition is accurate up to \(O(r^2)\) with \(r\) the infidelity, see [8].

import trueq.math as tqm

s = tqm.Superop.random_decoherent(9, 0.1)
assert s.is_cptp
print(s.infidelity, s.stochastic_infidelity)

0.0999977112438637 0.09767799574902236

Parameters:

total_dim (int) – The total dimension the superoperator acts on, e.g. 16 for four qubits.
infidelity (float) – The desired process infidelity; a number in \([0,1]\).
equibility (float) – A positive number indicating the equibility of the resulting channel in arbitrary units. A large value (say, 100) results in very uniform singular values of the leading kraus term, whereas they are more varied for a small value like 1.
rank (int | NoneTye) – A positive integer specifying the output Choi rank. If None, then the value total_dim ** 2 is used. A value of 1 results in a random unitary superoperator.
dim (int | NoneType) – The dimension of each subsystem this superoperator acts on, e.g. 2 for qubits. If None, the constructor will try to automatically infer the subsystem dimension by using auto_base().

Return type:

Raises:

ValueError – If the rank and infidelity are inconsistent—the rank can only be 1 when the infidelity is 0.0, and vise versa.

static random_stochastic(total_dim, infidelity, rank=None, dim=None)

Constructs a random stochastic channel with a given process infidelity, see infidelity. For the purposes of this function, a stochastic channel is one that can be written as convex mixture of orthogonal unitary channels, one of which is the identity, and the rest of which are traceless with evenly distributed eigenvalues. Such a channel is CPTP (see is_cptp), and the process fidelity is given by the weight of the identity mixture component.

The main difference between this method and random_decoherent() is that this method does not allow non-unital (e.g. \(T_1\) noise is non-unital because the completely mixed state reverts to something with polarization) behaviour or state-dependent leakage.

import trueq.math as tqm

s = tqm.Superop.random_stochastic(9, 0.1)
assert s.is_cptp
print(s.infidelity)

0.10000000000000031

Parameters:

total_dim (int) – The total dimension the superoperator acts on, e.g. 16 for four qubits.
infidelity (float) – The desired process infidelity; a number in \([0,1]\).
rank (int | NoneTye) – A positive integer specifying the output Choi rank. If None, then the value total_dim ** 2 is used. A value of 1 results in a random unitary superoperator.
dim (int | NoneType) – The dimension of each subsystem this superoperator acts on, e.g. 2 for qubits. If None, the constructor will try to automatically infer the subsystem dimension by using auto_base().

Return type:

Raises:

ValueError – If the rank and infidelity are inconsistent—the rank can only be 1 when the infidelity is 0.0, and vise versa.

static random_unitary(total_dim, dim=None)

Constructs a Haar-random unitary channel.

import trueq.math as tqm

s = tqm.Superop.random_unitary(9)
assert s.is_unitary

Parameters:

total_dim (int) – The total dimension the superoperator acts on, e.g. 16 for four qubits.
dim (int | NoneType) – The dimension of each subsystem this superoperator acts on, e.g. 2 for qubits. If None, the constructor will try to automatically infer the subsystem dimension by using auto_base().

Return type:

static zero(total_dim, dim=None)

Constructs a new superoperator that sends all inputs to the zero matrix.

Parameters:

total_dim (int) – The total dimension the superoperator acts on, e.g. 16 for four qubits.
dim (int | NoneType) – The dimension of each subsystem this superoperator acts on, e.g. 2 for qubits. If None, the constructor will try to automatically infer the subsystem dimension by using auto_base().

Return type:

static from_chi(chi)

Instantiates a new Superop from a \(\chi\)-matrix in the Pauli basis (or Weyl basis for subsystem dimension greater than two). The \(\chi\)-matrix is also known as the process matrix. For an ordered orthogonal basis \(B_1,\ldots,B_{d^{2n}}\) of \(d^n\times d^n\) complex matrices, the \(\chi\)-matrix of a quantum channel \(\mathcal{E}\) is a matrix \(\chi\) such that

\[\mathcal{E}(\rho) = \sum_{i,j}\chi_{ij}B_i \rho B_j^\dagger\]

for any density matrix \(\rho\). The basis used is the same as described in from_ptm(). In particular, the subsystem dimension must be prime.

Parameters:: chi (numpy.ndarray) – A square matrix.
Returns:: The superoperator for a given \(\chi\)-matrix representation.
Return type:: Superop
Raises:: ValueError – If the \(\chi\)-matrix does not have a width that is an even power of a small prime number.

property chi

The \(\chi\)-matrix representation of this superoperator; see from_chi() for details on this representation.

Type:: numpy.ndarray

plot_chi(abs_max=None, ax=None)

Plots the \(\chi\)-matrix representation of this superoperator; see from_chi() for details on this representation.

Parameters:

abs_max (NoneType | float) – The value to scale absolute values of the matrix by; the value at which plotted colors become fully opaque. By default, this is the largest absolute magnitude of the input matrix.
ax (matplotlib.Axis | NoneType) – An existing axis to plot on. One is created otherwise.

static from_kraus(*ops, dim=None)

Instantiates a new Superop from a given set of Kraus operators. A superoperator in the Kraus representation is a set of \(m\) operators \({K_0,\ldots,K_{m-1}}\) that act on a given density matrix by the formula \(\rho\mapsto\sum_{i=0}^{m-1}K_i \rho K^\dagger_i\). A superoperator admits a Kraus representation if and only if it is completely positive (see is_cp), but it is only trace preserving (see is_tp) if \(\sum_{k=0}^{m-1}K^\dagger_i K_i = \mathbb{I}\).

import numpy as np
import trueq as tq

# instantiate a depolarizing channel
p = 0.05
superop = tq.math.Superop.from_kraus(
    np.sqrt(1 - p) * tq.Gate.id.mat,
    np.sqrt(p / 3) * tq.Gate.x.mat,
    np.sqrt(p / 3) * tq.Gate.y.mat,
    np.sqrt(p / 3) * tq.Gate.z.mat,
)

Parameters:

*ops – One or more array_like Kraus operators.
dim (int | NoneType) – The dimension of each subsystem this superoperator acts on, e.g. 2 for qubits. If None, the constructor will try to automatically infer the subsystem dimension by using auto_base().

Returns:

The superoperator corresponding to the given set of Kraus operators.

Return type:

property kraus

The Kraus representation of this superoperator; see from_kraus() for details about the representation. Note that Kraus representations are not unique, and this decomposition is only possible if the superoperator is CP (see is_cp). The format is a 3-D array ops of shape (n_ops, dim, dim) where ops[i,:,:] is the \(i^{th}\) Kraus operator.

Note

Although this attribute is not the underlying superoperator storage format, it is memoized when called, so that subsequent calls do not need to compute the value.

Type:: numpy.ndarray

plot_kraus(n_columns=4, abs_max=None, axes=None)

Plots a Kraus representation of this superoperator; see from_kraus() for details about the representation. Note that Kraus representations are not unique.

Parameters:

n_columns (int) – If new axes are made, how many columns of subplots to use.
abs_max (NoneType | float) – The value to scale absolute values of the matrix by; the value at which plotted colors become fully opaque. By default, this is the largest absolute magnitude of the input matrix.
axes (Iterable | NoneType) – An existing list of axes to plot on. They are created otherwise.

static from_unitary(u, dim=None)

Instantiates a new Superop from a given unitary matrix. A unitary matrix \(U\) acts on a given matrix by the formula \(\rho\mapsto U\rho U^\dagger\).

import trueq as tq

# instantiate a CNOT as a superoperator
superop = tq.math.Superop.from_unitary(tq.Gate.cnot.mat)

Parameters:

u (numpy.ndarray) – A unitary matrix.
dim (int | NoneType) – The dimension of each subsystem this superoperator acts on, e.g. 2 for qubits. If None, the constructor will try to automatically infer the subsystem dimension by using auto_base().

Returns:

The superoperator that conjugates input states by the given unitary matrix.

Return type:

static from_function(fcn, total_dim=None, dim=None)

Instantiates a new Superop from a python function.

import trueq as tq


def depolarizing(rho, p=0.05):
    d = rho.shape[0]
    return (1 - p) * rho + p * np.eye(d) * np.trace(rho) / d


# instantiate a qubit depolarizing channel
superop = tq.math.Superop.from_function(depolarizing, 2)

# instantiate a qutrit depolarizing channel
superop = tq.math.Superop.from_function(depolarizing, 3)

Note

The function is assumed to be a linear function of a single density matrix. Passing a nonlinear function will result in a linear approximation that reproduces the action of the function on a basis of the operator space.

Parameters:

fcn (function) – A function that takes a density matrix and returns a density matrix of the same shape.
total_dim (int | NoneType) – The total Hilbert space dimension that this superoperator acts on. This will control the size of density matrix that is input into fcn. The default value of None will result in the default dimension obtained from get_dim().
dim (int | NoneType) – The dimension of each subsystem this superoperator acts on, e.g. 2 for qubits. If None, the constructor will try to automatically infer the subsystem dimension by using auto_base().

Returns:

The superoperator that maps a density matrix to the state returned by the given function.

Return type:

Raises:

ValueError – If dim does not divide total_dim.

from_qobj()

Instantiates a new Superop from a QuTiP operator object.

import qutip as qt
import trueq as tq

# make some QuTiP operator
cx = qt.sigmax()

# convert to a Superop and plot
s = tq.math.Superop.from_qobj(cx)
s.plot_ptm()

Parameters:

qobj (qutip.Qobj) – A QuTiP superoperator object.

Returns:

The superoperator for a given qobj.

Return type:

Raises:

RuntimeError – :If QuTiP is not imported.
ValueError – If the given qobj has non-uniform subsystem dimensions.

property qobj

A new QuTiP superoperator object generated by this instance.

import qutip as qt
import trueq as tq

# construct a Superop from a simulation
sim = tq.Simulator().add_stochastic_pauli(px=0.04).add_overrotation(0, 0.03)
s = tq.math.Superop(sim.operator(tq.Cycle({(0, 1): tq.Gate.cx})).mat())

# convert to a Qobj and plot
o = s.qobj
qt.visualization.matrix_histogram_complex(o)

(<Figure size 640x480 with 2 Axes>, <Axes3D:>)

QuTiP is an optional dependency and must be installed for this function to work.

Type:: qutip.Qobj
Raises:: RuntimeError – If QuTiP is not imported.

static from_ptm(ptm)

Instantiates a new Superop from a Pauli transfer matrix (PTM). A PTM represents how density matrices are transformed when expanded in the Pauli basis. In particular, suppose that for \(n\) qubits the Pauli matrices are denoted by \(\{P_i\}_{i=0}^{4^n-1}\), and sorted lexicographically. For example with \(n=2\), we have the ordering

\[\{P_i\}_{i=0}^{15} =\{II, IX, IY, IZ, XI, XX, XY, XZ, YI, YX, YY, YZ, ZI, ZX, ZY, ZZ\}.\]

Given any density matrix \(\rho\), we can expand it in the Pauli basis as \(\rho=\sum_{i=4^n-1} c_i P_i\). A PTM \(A\) performs the transformation \(c\mapsto A c\) where \(c\) is the vector \(c=(c_0,c_1,...,c_{4^n-1})\).

import numpy as np
import trueq as tq

# instantiate a qubit depolarizing channel
superop = tq.math.Superop.from_ptm(np.diag([1, 0.99, 0.99, 0.99]))

The PTM can be generalized to subsystems with \(d>2\) using the Weyl operators, which are a set of \(d^2\) mutually orthogonal unitary matrices. However, unlike the Paulis, they are not generally Hermitian which leads to non-real elements of the PTM for CP (see is_cp) maps. The expected order corresponds to lex=False in all.

This representation is identical to from_herm_ptm for \(d=2\). For \(d>2\), this method differs from from_herm_ptm only in that mat is used to create the representation basis instead of herm_mat.

import trueq as tq
import matplotlib.pyplot as plt

# plot ptm of the Z operator on the left, and herm_ptm on the right
z = tq.math.Superop.from_unitary(tq.math.Weyls("W01", 3).mat)
_, (ax1, ax2) = plt.subplots(1, 2, figsize=(9, 4))
z.plot_ptm(ax=ax1)
z.plot_herm_ptm(ax=ax2)

Parameters:: ptm (numpy.ndarray) – A square matrix.
Returns:: The superoperator for a given PTM.
Return type:: Superop
Raises:: ValueError – If the PTM does not have a width that is an even power of a small prime number.

property ptm

The Pauli transfer matrix representation of this superoperator; see from_ptm() for details on this representation.

Type:: numpy.ndarray

plot_ptm(abs_max=None, ax=None)

Plots the Pauli transfer matrix representation of this superoperator; see from_ptm() for details on this representation.

Parameters:

abs_max (NoneType | float) – The value to scale absolute values of the matrix by; the value at which plotted colors become fully opaque. By default, this is the largest absolute magnitude of the input matrix.
ax (matplotlib.Axis | NoneType) – An existing axis to plot on. One is created otherwise.

static from_herm_ptm(ptm)

Instantiates a new Superop from a Pauli transfer matrix (PTM). A PTM represents how density matrices are transformed when expanded in the Pauli basis. In particular, suppose that for \(n\) qubits the Pauli matrices are denoted by \(\{P_i\}_{i=0}^{4^n-1}\), and sorted lexicographically. For example with \(n=2\), we have the ordering

\[\{P_i\}_{i=0}^{15} =\{II, IX, IY, IZ, XI, XX, XY, XZ, YI, YX, YY, YZ, ZI, ZX, ZY, ZZ\}.\]

Given any density matrix \(\rho\), we can expand it in the Pauli basis as \(\rho=\sum_{i=4^n-1} c_i P_i\). A PTM \(A\) performs the transformation \(c\mapsto A c\) where \(c\) is the vector \(c=(c_0,c_1,...,c_{4^n-1})\).

import numpy as np
import trueq as tq

# instantiate a qubit depolarizing channel
superop = tq.math.Superop.from_ptm(np.diag([1, 0.99, 0.99, 0.99]))

The PTM can be generalized to subsystems with \(d>2\) using the Weyl operators, which are a set of \(d^2\) mutually orthogonal unitary matrices. However, unlike the Paulis, they are not generally Hermitian which would lead to non-real elements of the PTM for CP (see is_cp) maps. Therefore, we use a symmetrized version of the Weyl matrices, herm_mat for details. The expected order corresponds to lex=False in all.

This representation is identical to from_ptm for \(d=2\). For \(d>2\), this method differs from from_ptm only in that herm_mat is used to create the representation basis instead of mat.

import trueq as tq
import matplotlib.pyplot as plt

# plot ptm of the Z operator on the left, and herm_ptm on the right
z = tq.math.Superop.from_unitary(tq.math.Weyls("W01", 3).mat)
_, (ax1, ax2) = plt.subplots(1, 2, figsize=(9, 4))
z.plot_ptm(ax=ax1)
z.plot_herm_ptm(ax=ax2)

Parameters:: ptm (numpy.ndarray) – A square matrix.
Returns:: The superoperator for a given PTM.
Return type:: Superop
Raises:: ValueError – If the PTM does not have a width that is an even power of a small prime number.

property herm_ptm

The Pauli transfer matrix representation of this superoperator; see from_ptm() for details on this representation.

Type:: numpy.ndarray

plot_herm_ptm(abs_max=None, ax=None)

Plots the Pauli transfer matrix representation of this superoperator; see from_ptm() for details on this representation.

Parameters:

abs_max (NoneType | float) – The value to scale absolute values of the matrix by; the value at which plotted colors become fully opaque. By default, this is the largest absolute magnitude of the input matrix.
ax (matplotlib.Axis | NoneType) – An existing axis to plot on. One is created otherwise.

static from_choi(choi, dim=None)

Instantiates a new Superop from a Choi matrix. If a channel \(\Lambda\) transforms a given density matrix as \(\rho\mapsto \Lambda(\rho)\), then the Choi matrix (in the row convention) is equal to \(\Lambda_r=\sum_{i,j=0}^{d-1}\Lambda(E_{i,j})\otimes E_{i,j}\) where \(d\) is the dimension, and \(E_{i,j}\) is the \(d\times d\) matrix of zeros with a 1 in the \((i,j)^\text{th}\) entry.

The Choi matrix is positive semidefinite if and only if the superoperator it represents is completely positive (see is_cp). Therefore, there is a correspondence between completely positive superoperators and density matrices (which must also be positive semidefinite) that is often called the Choi-Jamiolkowski isomorphism.

import numpy as np
import trueq as tq

# instantiate a random CP qubit channel
superop = tq.math.Superop.from_choi(2 * tq.math.random_density(4))

Parameters:

choi (numpy.ndarray) – A Choi matrix.
dim (int | NoneType) – The dimension of each subsystem this superoperator acts on, e.g. 2 for qubits. If None, the constructor will try to automatically infer the subsystem dimension by using auto_base().

Returns:

The superoperator for a given Choi matrix.

Return type:

property choi

The Choi matrix representation of this superoperator; see from_choi() for details on this representation.

Type:: numpy.ndarray

plot_choi(abs_max=None, ax=None)

Plots the Choi representation of this superoperator; see from_choi() for details on this representation.

Parameters:

abs_max (NoneType | float) – The value to scale absolute values of the matrix by; the value at which plotted colors become fully opaque. By default, this is the largest absolute magnitude of the input matrix.
ax (matplotlib.Axis | NoneType) – An existing axis to plot on. If omitted, a new one is created.

static from_rowstack(mat, dim=None)

Instantiates a new Superop from a Liouville superoperator matrix in the row-stacking basis. Note that since this is the native basis of the Superop class, this method is equivalent to the constructor.

This is the best representation for superopertors for simulation if density matrices are C-ordered (i.e. row-major, so that entire rows are contiguous in memory). This is because if our row-stacking superoperator matrix is \(M\) and our density matrix \(\rho\), then if we take the rows of \(\rho\) and stack them together into one column vector, denoted \(\operatorname{vec}(\rho)\), then the output density matrix is given by regular matrix multiplication, \(\operatorname{vec}^{-1}(M\operatorname{vec}(\rho))\), where \(\operatorname{vec}^{-1}\) is the unstacking operator.

import numpy as np
import trueq as tq

# instantiate the identity channel on a qutrit
superop = tq.math.Superop.from_rowstack(np.eye(9))

Parameters:

mat (numpy.ndarray) – A superoperator in the row-stacking basis.
dim (int | NoneType) – The dimension of each subsystem this superoperator acts on, e.g. 2 for qubits. If None, the constructor will try to automatically infer the subsystem dimension by using auto_base().

Return type:

property rowstack

The matrix representation of this superoperator in the row-stacking basis; see from_rowstack() for details on this representation.

Type:: numpy.ndarray

plot_rowstack(abs_max=None, ax=None)

Plots the matrix representation of this superoperator in the row-stacking basis; see from_rowstack() for details on this representation.

Parameters:

abs_max (NoneType | float) – The value to scale absolute values of the matrix by; the value at which plotted colors become fully opaque. By default, this is the largest absolute magnitude of the input matrix.
ax (matplotlib.Axis | NoneType) – An existing axis to plot on. If omitted, a new one is created.

static from_rowstack_subsys(mat, dim=None)

Instantiates a new Superop from a Liouville superoperator matrix in the row-stacking subsystem-wise basis. If a unitary \(U=U_1\otimes U_2\) acts on some bipartite Hilbert space, then rowstack (which is also the native representation used by this class) is equal to

\[U\otimes \overline{U} =U_1 \otimes U_2 \otimes \overline{U}_1 \otimes \overline{U}_2\]

which we call the global rowstacking convention. It is sometimes more useful to use the subsystem-wise rowstacking convention where the wires of each subsystem are grouped together, corresponding to the unitary

\[U\otimes \overline{U} =U_1 \otimes \overline{U}_1 \otimes U_2 \otimes \overline{U}_2\]

Indeed, this is the convention used by OperatorTensor and hence also by the Simulator. This idea generalizes to n-partite superoperators.

import numpy as np
import trueq as tq

# instantiate the identity channel on two qubits
superop = tq.math.Superop.from_rowstack_subsys(np.eye(16))

Parameters:

mat (numpy.ndarray) – A superoperator in the row-stacking subsystem-wise basis.
dim (int | NoneType) – The dimension of each subsystem this superoperator acts on, e.g. 2 for qubits. If None, the constructor will try to automatically infer the subsystem dimension by using auto_base().

Return type:

property rowstack_subsys

The matrix representation of this superoperator in the row-stacking basis; see from_rowstack_subsys() for details on this representation.

Note

Although this attribute is not the underlying superoperator storage format, it is memoized when called, so that subsequent calls do not need to compute the value.

Type:: numpy.ndarray

plot_rowstack_subsys(abs_max=None, ax=None)

Plots the matrix representation of this superoperator in the row-stacking subsystem-wise basis; see from_rowstack_subsys() for details on this representation.

Parameters:

dim (int) – The dimension of each Hilbert space subsystem, e.g. 2 for qubits.
abs_max (NoneType | float) – The value to scale absolute values of the matrix by; the value at which plotted colors become fully opaque. By default, this is the largest absolute magnitude of the input matrix.
ax (matplotlib.Axis | NoneType) – An existing axis to plot on. If omitted, a new one is created.

static from_colstack(mat, dim=None)

Instantiates a new Superop from a superoperator in the column-stacking basis.

This is the best representation for superopertors for simulation if density matrices are Fortran-ordered (i.e. column-major, so that entire columns are contiguous in memory). This is because if our column-stacking superoperator matrix is \(M\) and our density matrix \(\rho\), then if we take the columns of \(\rho\) and stack them together into one column vector, denoted \(\operatorname{vec}(\rho)\), then the output density matrix is given by regular matrix multiplication, \(\operatorname{vec}^{-1}(M\operatorname{vec}(\rho))\), where \(\operatorname{vec}^{-1}\) is the unstacking operator.

import numpy as np
import trueq as tq

# instantiate the identity channel on a qutrit
superop = tq.math.Superop.from_colstack(np.eye(9))

Parameters:

mat (numpy.ndarray) – A superoperator in the column-stacking basis.
dim (int | NoneType) – The dimension of each subsystem this superoperator acts on, e.g. 2 for qubits. If None, the constructor will try to automatically infer the subsystem dimension by using auto_base().

Return type:

property colstack

The matrix representation of this superoperator in the column-stacking basis; see from_colstack() for details on this representation.

Type:: numpy.ndarray

plot_colstack(abs_max=None, ax=None)

Plots the matrix representation of this superoperator in the col-stacking basis; see from_colstack() for details on this representation.

Parameters:

abs_max (NoneType | float) – The value to scale absolute values of the matrix by; the value at which plotted colors become fully opaque. By default, this is the largest absolute magnitude of the input matrix.
ax (matplotlib.Axis | NoneType) – An existing axis to plot on. If omitted, a new one is created.

property lkpd

The leading Kraus polar decomposition (LKPD) of this superoperator. This is a tuple u, p where u is unitary and p is positive semi-definite, and the product u @ p is equal to the leading Kraus term.

See [8] for a comprehensive overview of this form. In short, when eigenvectors of a positive semi-definite Choi matrix are scaled by the square-roots of their eigenvalues and devectorized into square matrices, they form a set of mutually orthogonal Kraus operators for the channel. The Kraus operator corresponding to the largest eigenvalue forms a convenient approximation to the channel when the channel is nearly unitary. The QR decomposition of this leading Kraus term separates leading dynamics of the channel into unitary and stochastic behaviour.

Note

This is a partial representation because it does not contain all information about the superoperator; non-leading terms of the Kraus representation are dropped.

Type:: tuple

plot_lkpd(axes=None, abs_max=None)

Plots both matrices of the polar decomposition of the leading Kraus term of this superoperator; see lkpd() for details on this (partial) representation.

Parameters:

abs_max (NoneType | float) – The value to scale absolute values of the matrix by; the value at which plotted colors become fully opaque. By default, this is the largest absolute magnitude of the input matrix.
axes (Iterable | NoneType) – An existing list of axes to plot on. They are created otherwise.

apply(state)

Applies this superoperator to a given density matrix or pure state. The output is always a density matrix of shape (dim, dim).

import numpy as np
import trueq as tq

# make a superoperator acting on a qutrit
s = tqm.Superop.random_constrained_cptp(3, 0.01, 0.4)

# apply to a pure state
s.apply([1, 0, 0])

array([[ 9.88721415e-01-8.52773244e-21j, -1.66179129e-02+5.96737018e-02j,
        -2.63626149e-02-1.80983027e-02j],
       [-1.66179129e-02-5.96737018e-02j,  6.59267678e-03+9.51405575e-21j,
        -7.16093875e-04+1.93990931e-03j],
       [-2.63626149e-02+1.80983027e-02j, -7.16093875e-04-1.93990931e-03j,
         4.68590827e-03+8.93794200e-22j]])

Parameters:: state (numpy.ndarray-like) – An input density matrix or pure state of the correct shape.
Returns:: The image of state under this superoperator.
Return type:: numpy.ndarray

Tensors

class trueq.math.tensor.Tensor(output_shape, input_shape=None, spawn=None, value=None, dtype=None)

Represents a multipartite tensor on an arbitrary number of subsystems. Each subsystem owns a number of ordered wires (or indices), which can each be input or output wires (e.g., lower and upper indices in Einstein’s notation). One important restriction is that all subsystems have the same wire description: the same number, dimensions, and order for input and output wires.

Here are some motivating cases for various output and input shapes output, input:

(d,), (): Pure states on a multipartite qubit system. Each subsystem has a single output wire of dimension \(d\) and no input wires (i.e., a column vector). See StateTensor.

(d,), (): Probability distributions over Cartesian products of dits. Each subsystem has a single output wire of dimension \(d\) and no input wires (i.e., a column vector).

(d,d), (): Vectorized mixed states on a multipartite qubit system. Each subsystem has two output wires each with dimension \(d\) and no input wires. The first output wire represents the output wire of the unvectorized state, and the second output wire the input wire of the unvectorized state (this is the row-stacking convention). See StateTensor.

(d,), (d,): Unitaries acting on a multipartite qubit system. Each subsystem has a single output wire of dimension \(d\) and a single input wire of dimension \(d\) (i.e., a square matrix). See OperatorTensor.

(d,d), (d,d): Superoperators acting on a multipartite qubit system. Each subsystem has two input wires and two output wires, all of dimension \(d\). The two input wires act on a vectorized density matrix (or contract against another superoperator in composition). See OperatorTensor.

A main feature of this class is the ability to efficiently left-multiply square matrices onto specific subsystems (see apply_matrix()), which can be strictly smaller than all of the subsystems present in the tensor. Therefore this class can be used to maintain the state of a simulation, and is general enough to track pure states, mixed states, unitaries, and superoperators.

import trueq as tq
import numpy as np

t = tq.math.Tensor(2, 2, spawn=np.eye(2))
t.apply_matrix((0, 2), tq.Gate.cnot.mat)
t.apply_matrix((1,), tq.Gate.h.mat)

# display the matrix corresponding to the circuit {(0, 2): cnot, (1,): h}
tq.plot_mat(t.mat().reshape(8, 8))

The internal storage format of this class is a dictionary mapping labels to NumPy arrays, such as the following:

{
    (0,): [[0, 1], [1, 0]],
    (2, 3): [[1, 0, 0, 0], [0, 1, 0, 0], [0, 0, 0, 1], [0, 0, 1, 0]],
}

{(0,): [[0, 1], [1, 0]],
 (2, 3): [[1, 0, 0, 0], [0, 1, 0, 0], [0, 0, 0, 1], [0, 0, 1, 0]]}

In the above example, the label (0,) stores an X gate, and the labels (2, 3) store a CNOT gate.

Parameters:

output_shape (tuple | int) – The output wire dimension, or a tuple of output wire dimensions. Set to an empty tuple for no output wires.
input_shape (tuple | int | NoneType) – The input wire dimension, or a tuple of input wire dimensions. Set to an empty tuple or None for no input wires.
spawn (numpy.ndarray-like) – The default value to assign to new subsystems. The size must match the provided input and output shapes. By default, this parameter is set to the tensor of all zeros, except the first element, which is 1.
value (dict) – The initial value of the tensor, set as a dictionary mapping tuples of subsystem indexes to tensors of the correct shape.
dtype – The data type of the arrays, numpy.float64 by default.

property dtype

The data type of this tensor.

Type:: type

property labels

Which subsystem labels of this tensor have a value.

Type:: tuple

property n_sys

The number of subsystem labels with a value

Type:: int

property shape

The output and input shape of each subsystem, e.g., ((2, 2), (2, 2)). See the arguments input_shape and output_shape of the constructor of Tensor.

Type:: tuple

property total_dim

The total dimension of this tensor; the total subsystem dimension to the power of the number of subsystems.

Type:: int

property spawn

The array that is assigned to new subsystems by default.

Type:: numpy.ndarray

conj(copy=True)

Takes the complex conjugate of each array in this tensor.

Parameters:: copy (bool) – Whether to mutate the given tensor, or to create a copy and leave the original intact.
Returns:: This instance or a copy.
Return type:: Tensor

adj(copy=True)

Takes the complex conjugate and transpose of each array in this tensor. Here, transpose refers to swapping the input shape with the output shape.

Parameters:: copy (bool) – Whether to mutate the given tensor, or to create a copy and leave the original intact.
Returns:: This instance or a copy.
Return type:: Tensor

transpose(output_perm, input_perm, copy=True)

Permutes wire dimensions of this tensor, possibly switching input wires with output wires.

from trueq.math import Tensor

# turn a column vector into a row vector
t = Tensor((2,))
print(t.shape, t.transpose([], [0]).shape)

# vectorize a matrix with row-stacking
t = Tensor((2,), (2,))
print(t.shape, t.transpose([0, 1], []).shape)

# vectorize a matrix with column-stacking
t = Tensor((2,), (3,))
print(t.shape, t.transpose([1, 0], []).shape)

# shuffle some wires
t = Tensor((2, 3), (5,))
print(t.shape, t.transpose([2, 1], [0]).shape)

((2,), ()) ((), (2,))
((2,), (2,)) ((2, 2), ())
((2,), (3,)) ((3, 2), ())
((2, 3), (5,)) ((5, 3), (2,))

Parameters:

output_perm (Iterable) – A list of indices referencing positions in the joint tuple shape = output_shape + input_shape. Therefore output_perm + input_perm must be a permutation of range(len(shape)).
input_perm (Iterable) – A list of indices referencing positions in the joint tuple output_shape + input_shape.
copy (bool) – Whether to mutate the given tensor, or to create a copy and leave the original intact.

Returns:

This instance or a copy.

Return type:

value(order='subsystem')

Returns the value of this tensor: a dictionary mapping tuples of subsystem labels to array values.

The argument of this method changes the order of indexes of the arrays. For simulation performance reasons, the internal storage arranges them subsystem-wise, so that all input wires for a given subsystem are contiguous, and likewise all output wires for a given subsystem are contiguous, and this is the default order of this method. This can optionally be changed so that indices are riffled over subsystems.

As an example, suppose the input shape is (2, 4) and the output shape is (5,) and that there are 3 subsystems in an array. Then the array will have shape (2, 4, 2, 4, 2, 4, 5, 5, 5) if the order is "subsystem" (default), or the array will have shape (2, 2, 2, 4, 4, 4, 5, 5, 5) if the order is "composite".

As a convenience, appending "-flat" to the order flattens all inputs and all outputs separately, giving a shape (512, 125) in this example, whether the order is composite or subsystem based. Further, appending "-group" to composite order flattens each group of subsystems, giving a shape (8, 64, 125) in this example.

Parameters:: order (str) – Which order to arrange the wires, either "subsystem", "subsystem-flat", "composite", "composite-group", or "composite-flat". Or, one of "s", "sf", "c", "cg", or "cf" for short.
Return type:: dict

mat(order='subsystem', labels=None)

Returns the full matrix representation of this tensor, with subsystems ordered by sorted labels.

Note

Note that this property will create an array that is exponentially large in the number of subsystems, and causes any distinct subsystems found in value() to be permanently merged; calling this attribute mutates the tensor’s internal representation.

Parameters:

order (str) – Advanced users see Tensor.value().
labels (Iterable) – The desired subsystem label order, which must be a permutation of labels. By default, labels are ordered from smallest to biggest.

Return type:

numpy.ndarray

add_labels(labels)

Updates the number of subsystems to include labels provided, if they do not already exist. If the labels are already present, this call doesn’t change anything.

Parameters:: labels (Iterable) – A list of labels to be added to this tensor.
Returns:: This instance.
Return type:: Tensor

merge(labels)

Merges the given labels together after adding any labels that are not already present.

Parameters:: labels (Iterable) – A list of labels.
Returns:: An unsorted tuple containing all of the labels in the partite resulting from this merge.
Return type:: tuple

upgrade()

Does nothing. This is to be used by subclasses that require a mutation of shape on a call to marginalize(). See, for instance, StateTensor.upgrade() and OperatorTensor.upgrade().

Returns:: This instance.
Return type:: Tensor

marginalize(labels, assume_unital=True, copy=True)

Keeps the provided labels of this tensor by marginalizing the remaining labels. Here, marginalization is defined as the sum over all tensor indices of the remaining labels.

import trueq as tq
import numpy as np

# Make a random probability distribution on length-4 bitstrings
s = tq.settings.get_rng().random(16)
p = tq.math.Tensor(2, value={(0, 1, 2, 3): s / s.sum()})

# Keep two of the bitstrings and marginalize the rest
p.marginalize((1, 2))

Tensor(<[(2,), ()] on labels [(1, 2)]>)

Parameters:

labels (tuple) – Which labels to keep. The order does not matter.
assume_unital (bool) – Assumes that each factor in the tensor has a sum of 1. Otherwise, in the case where entire entries in value() need to be removed, sums are still computed and multiplied onto some other entry so that the overall sum of the tensor is preserved. In the case where all labels in the tensor are marginalized, label (0,) is re-added so that the total sum of the tensor can be preserved.
copy (bool) – Whether to make a copy of this tensor, or mutate it in place.

Returns:

This instance.

Return type:

update(other)

Updates this tensor with some new values. If values are placed on labels that do not exist, creates and sets them. If values are placed on labels that already exist, they are first removed by calling marginalize().

Parameters:: other (dict | Tensor) – A dictionary or another Tensor. In either case, the size of subsystems in other needs to match this tensor.
Returns:: This instance.
Return type:: Tensor

apply_matrix(labels, matrix)

Mutates this tensor by applying the given square matrix to the given labels.

The size of the matrix must be compatible with the output shape of this tensor; just as with regular matrix multiplication, \(AB\), the number of columns of \(A\) must match the number of rows of \(B\). The rule enforced here is that the number of rows of the given matrix, when reshaped into a square, must be equal to the product of this tensor’s output wire dimensions. Square matrices are enforced to avoid changing the shape of the tensor.

import trueq as tq
import numpy as np

rng = tq.settings.get_rng()

t = tq.math.Tensor((2, 3), (2,))

# we need a 6x6 since output shape is (2, 3)
t.apply_matrix((0,), rng.standard_normal((6, 6)))

# we need a 36x36 since we are applying to 2 systems
t.apply_matrix((0, 3), rng.standard_normal((36, 36)))

(0, 3)

Parameters:

labels (Iterable) – Which subsystems to apply the matrix to.
matrix (numpy.ndarray-like) – A square matrix.

Returns:

The labels to which the matrix was applied, including labels that needed to be merged together.

Return type:

tuple

apply_to_all(mat, copy=False)

Applies a matrix to every subsystem of this tensor.

Parameters:

mat (numpy.ndarray) – A matrix to apply to this system, which must be square if copy == False.
copy (bool) – Whether to make a copy of this tensor, or mutate it in place.

Returns:

This instance, or the copied instance.

Return type:

apply_ufunc(ufunc)

Applies a NumPy universal function to every array in this tensor.

Parameters:: ufunc (numpy.ufunc) – A universal function to apply to every array.

dot(rhs, dtype=None, overwrite_rhs=False)

Contracts this tensor with another tensor, returning a new tensor. The only shape restriction is that this tensor’s input shape must match the output tensor’s output shape. The returned tensor has input-output shapes (this.output_shape, rhs.input_shape); the inner shapes have been contracted against each other.

import trueq.math as tqm
import numpy as np

rng = np.random.default_rng()
lhs = tqm.Tensor(5, (2, 3), value={(0, 1): rng.standard_normal((25, 36))})
rhs = tqm.Tensor((2, 3), 4, value={(1, 5): rng.standard_normal((36, 16))})
product = lhs.dot(rhs)

print(product.shape)
print(product.labels)

((5,), (4,))
(0, 1, 5)

Parameters:

rhs (Tensor) – Another tensor with a compatible shape.
dtype (numpy.dtype) – The data type of the output tensor. If either of the inputs are complex, and the output is real, the real part is taken without warning.
overwrite_rhs (bool) – Whether to mutate rhs so that its final value is the product. Otherwise, a copy of rhs is made.

Return type:

sample(n_shots=1, labels=None)

Assumes that this tensor represents a categorical probability distribution over ditstrings and samples n_shots from it, or a marginalized version of it if labels are provided.

import trueq.math as tqm

probs = tqm.Tensor(2, value={(0,): [0, 1], (1, 2): [0, 0.5, 0, 0.5]})

probs.sample(100)
# Results({"101": 52, "111": 48})

probs.sample(100, labels=(0, 2))
# Results({"11": 100})

Results({'11': 100})

Parameters:

n_shots (int) – The number of samples to draw from the distribution.
labels (Iterable) – A list of labels to sample from.

Return type:

Results

to_results(labels=None, clip=True)

Constructs a new Results object whose ditstring values are equal to the corresponding matrix entries of this tensor.

import trueq.math as tqm

probs = tqm.Tensor(2, value={(1,): [0, 1], (0, 2): [0, 0.5, 0, 0.5]})
probs.to_results()

Results({'011': 0.5, '111': 0.5})

Parameters:

labels (Iterable) – A list of labels to slice, in case a subset of all labels present in this tensor is desired. If None, all labels present in the tensor are used (in sorted order).
clip (bool) – Whether or not to clip the values to the interval \([0, 1]\).

Return type:

Results

class trueq.math.tensor.StateTensor(dim=None, spawn=None, value=None)

Represents a pure or mixed state on a multipartite qubit system. This is one of the main output formats of the Simulator. It differs from just a pure matrix, such as a numpy.ndarray, in that it also stores qubit label information, and attempts to store a sparse representation when the state is not entangled between various subsystems.

Depending on the types of noise in your simulator, this state could be pure or mixed. This will affect the dimension. You can check which case you have with is_mixed. You can get the matrix representation with mat().

import trueq as tq

# construct a circuit that makes a 3-qubit cat state
circuit = tq.Circuit()
circuit.append({(0,): tq.Gate.h})
circuit.append({(0, 1): tq.Gate.cnot})
circuit.append({(1, 2): tq.Gate.cnot})

# use a simulator to fetch the state of this circuit as a StateTensor
state = tq.Simulator().state(circuit)

# print the 1D pure state vector
print(state.mat())

# get the density matrix representation
state.upgrade()
tq.plot_mat(state.mat())

[0.70710678+0.j 0.        +0.j 0.        +0.j 0.        +0.j
 0.        +0.j 0.        +0.j 0.        +0.j 0.70710678+0.j]

What follows is information intended for users that want to do a bit more than get the matrix representation of a state. This class has a few main distinctions from its parent class Tensor:

The datatype is always numpy.complex128.
The mat() and value() methods return a more convenient tensor order and shape by default.
The upgrade() method, which transforms this state from a pure state into a mixed state by taking appropriate outer products and changing the output shape from (d,) to (d,d). Certain methods automatically call upgrade(), for example, when a superoperator-shaped matrix is given to apply_matrix().
Certain functions like marginalize have been special-cased to quantum states.

import trueq as tq
import numpy as np

# make a pure state on a tensor product of qubits
psi = tq.math.StateTensor(2)

# we can manually upgrade it to a mixed state
rho = psi.upgrade()

# or we can automatically upgrade it to a mixed state by doing something that
# requires a mixed state. here, we apply something of superoperator size, rather
# than unitary size
psi = tq.math.StateTensor(2)
psi.apply_matrix((0,), np.eye(4))

# we can also create a mixed state on instatiation based on spawn/value shapes
rho = tq.math.StateTensor(2, spawn=[[1, 0], [0, 0]])

Note

This class does not assume that the represented state is positive or that it has unit trace, or that applied operators are unitary, CP , TP, unital, etc.: it just stores and manipulates complex numerical arrays.

Parameters:

dim (int | NoneType) – The Hilbert space dimension of a single subsystem. The default value of None will result in the default dimension obtained from get_dim().
spawn (numpy.ndarray-like) – The default state to set a subsystem to when its label is refered to, but it does not exist yet. This spawn can be pure or mixed. See also the constructor of Tensor.
value (dict) – The initial value of this state, which can either be pure or mixed. See also the constructor of Tensor.

property is_mixed

Whether this state currently is a mixed state (as opposed to a pure state). Equivalent to is_upgraded.

Type:: bool

property is_upgraded

Whether this state currently is a mixed state (as opposed to a pure state). Equivalent to is_mixed.

Type:: bool

property dim

The Hilbert space dimension of the subsystems of this state.

Type:: int

upgrade()

If this state represents a pure state, upgrades it to a mixed state by taking outer products. If this state is already a mixed state, does nothing.

Returns:: This instance.
Return type:: StateTensor

value(order='composite-group')

Returns a dictionary mapping tuples of subsystem labels to states on those subsystems. If this state is currently pure, then states will be 1D vectors, and if mixed, then states will be 2D density matrices.

Parameters:: order (str) – Advanced users see Tensor.value().
Return type:: dict

mat(order='composite-group', labels=None)

If this state is currently pure, returns the pure state vector, otherwise returns the density matrix.

Note

Note that this property will create an array that is exponentially large in the number of subsystems, and causes any distinct subsystems found in value() to be permanently merged; calling this attribute mutates the tensor’s internal representation.

Parameters:

order (str) – Advanced users see Tensor.value().
labels (Iterable) – The desired subsystem label order, which must be a permutation of labels. By default, labels are ordered from smallest to biggest.

Return type:

numpy.ndarray

apply_matrix(labels, matrix)

Mutates this state by applying the given square matrix to the given labels.

If acting on \(n\) subsystems, this matrix can be a \(d^n \times d^n\) unitary, or a \(d^{2n}\times d^{2n}\) superoparator. If this state is currently pure and a superoperator is applied, upgrade() is called. If this state is currently mixed and a unitary is applied, the unitary is made into a superoperator before applying.

import trueq as tq
import numpy as np

t = tq.math.StateTensor(2)

# apply a 2-qubit unitary
t.apply_matrix((0, 1), tq.Gate.cnot.mat)

# apply a 1% bitflip superoperator to qubit 1. This upgrades to mixed state
s = 0.99 * np.eye(4) + 0.01 * np.kron(tq.Gate.x.mat, tq.Gate.x.mat)
t.apply_matrix((1,), s)

# display the final mixed state
tq.plot_mat(t.mat())

The vectorization convention of superoperators is important. Mixed states are stored in a subsystem-wise row-stacked vectorization convention, and therefore superoperators need to use this convention too. See to_rowstack_super().

Parameters:

labels (Iterable) – Which subsystems to apply the matrix to.
matrix (numpy.ndarray-like) – A square matrix.

marginalize(labels, assume_unital=False, copy=False)

Keeps the provided labels of this tensor by taking the partial trace of the remaining labels. This will usually upgrade() a pure state to a mixed state.

The special case of no upgrade happens when this state is pure and all the labels being traced out are known to be unentangled with other labels (this is known when every label tuple in the keys of value() is either a strict subset of the given labels, or does not intersect at all with the given labels).

Parameters:

labels (tuple) – Which labels to keep. The order does not matter.
assume_unital (bool) – Assumes that each factor in the tensor has a trace of 1. Otherwise, in the case where entire entries in value() need to be removed, traces are still computed and multiplied onto some other entry so that the overall trace of the tensor is preserved. In the case where all labels in the tensor are traced out, label (0,) is re-added so that the total trace of the tensor can be preserved.
copy (bool) – Whether to make a copy of this tensor, or mutate it in place.

Returns:

This instance.

Return type:

StateTensor

probabilities(povm=None)

Computes the probabilities of all possible measurement outcomes. A Positive Operator Valued Measurement (POVM), if provided, defines the measurement outcomes. Otherwise, the outcomes are computational basis measurements.

import trueq.math as tqm
import numpy as np

# compute probability distribution of a qubit superposition
psi = tqm.StateTensor(2, value={(0,): np.array([1, -1j]) / np.sqrt(2)})
print(psi.probabilities().value())

# define a POVM corresponding to readout error that has a 1% chance of
# flipping a |0> measurement and a 10% chance of flipping a |1> measurement
p00 = 0.99
p11 = 0.9
povm = [[[p00, 0], [0, 1 - p11]], [[1 - p00, 0], [0, p11]]]
povm = tqm.Tensor((2,), (2, 2), spawn=povm)
print(psi.probabilities(povm).value())

# a more efficient implementation of the above, using a stochastic confusion
# matrix instead of quantum measurement operators
povm = tqm.Tensor(2, 2, spawn=[[p00, 1 - p11], [1 - p00, p11]])
print(psi.probabilities(povm).value())

{(0,): array([0.5, 0.5])}
{(0,): array([0.545, 0.455])}
{(0,): array([0.545, 0.455])}

Parameters:: povm (Tensor) – A Tensor with shape ((k,), (d, d)) or ((k,), (d,)) where d is the Hilbert space dimension, and (k,) is the number of possible outcomes per subsystem. In the former case, each slice [i,:,:] should be a positive matrix representing a measurement operator, and the sum over i should be the identity matrix to be probability preserving. In the latter case, the tensor represents a confusion matrix with which to modify the computational basis probabilities, and the sum of each row should be one to be probability preserving.
Return type:: dict

class trueq.math.tensor.OperatorTensor(dim=None, spawn=None, value=None, dtype=None)

Represents an operator (e.g., unitary) or superoperator (e.g., CPTP channel) on a multipartite qubit system. This is one of the main output formats of the Simulator. It differs from just a pure matrix, such as a numpy.ndarray, in that it also stores qubit label information, and attempts to store a sparse representation when the operator is not entangling between various subsystems.

Depending on the types of noise in your simulator, this operator could be a unitary or a superoperator. This will affect the dimension. You can check which case you have with is_superop. You can get the matrix representation with mat().

import trueq as tq

# construct a circuit that makes a 3-qubit cat state
circuit = tq.Circuit()
circuit.append({(0,): tq.Gate.h})
circuit.append({(0, 1): tq.Gate.cnot})
circuit.append({(1, 2): tq.Gate.cnot})

# use a simulator to fetch the unitary of this circuit as an OperatorTensor
op = tq.Simulator().operator(circuit)

# display the unitary matrix itself
tq.plot_mat(op.mat())

What follows is information intended for users that want to do a bit more than get the matrix representation of an operator. This class has a few distinctions from its parent class Tensor:

The datatype is numpy.complex128 by default.
The mat() and value() methods return a more convenient tensor order and shape by default.
The upgrade() method, which transforms this operator into a superoperator mixed state by taking appropriate kroneckers and changing the input and output shapes from (d,) to (d,d). Certain methods automatically call upgrade(), for example, when a superoperator shaped matrix is given to apply_matrix().
Certain functions like marginalize have been special-cased to quantum operators.

import trueq as tq
import numpy as np

# make a unitary channel for a tensor product of qubits
psi = tq.math.OperatorTensor(2)

# we can manually upgrade it to a superoperator
rho = psi.upgrade()

# or we can automatically upgrade it to a superoperator by doing something that
# requires a superoperator. here, we apply something of superoperator size,
# rather than unitary size
psi = tq.math.OperatorTensor(2)
psi.apply_matrix((0,), np.eye(4))

# we can also create superoperators on instantiation based on spawn/value shapes
rho = tq.math.OperatorTensor(2, spawn=np.eye(4))

Note

This class does not assume that the represented channel or anything applied to it is unitary, CP, TP, unital, etc.: it is just stores and manipulates numerical arrays.

Parameters:

dim (int | NoneType) – The Hilbert space dimension of a single subsystem. The default value of None will result in the default dimension obtained from get_dim().
spawn (numpy.ndarray-like) – The default operator to set a subsystem to when its label is referred to, but it does not exist yet. This spawn can be operator or superoperator. See also the constructor Tensor.
value (dict) – The initial value of this state, which can either be an operator or a superoperator. See also the constructor of Tensor.
dtype (type) – The datatype of this operator.

property is_superop

Whether this tensor represents a superoperator (as opposed to a unitary).

Type:: bool

property is_upgraded

Whether this tensor represents a superoperator (as opposed to a unitary). Equivalent to is_superop.

Type:: bool

property dim

The Hilbert space dimension that subsystems of this state act on.

Type:: int

marginalize(labels, assume_unital=False, copy=False)

Keeps the provided labels of this tensor by taking the partial trace of the remaining labels. This will usually upgrade() a unitary tensor into a superoperator tensor.

The special case of no upgrade happens when this state is pure and all the labels being traced out are known to be unentangled with other labels (this is known when every label tuple in the keys of value() is either a strict subset of the given labels, or does not intersect at all with the given labels).

Parameters:

labels (tuple) – Which labels to keep. The order does not matter.
assume_unital (bool) – Assumes that each factor in the tensor has a trace of 1. Otherwise, in the case where entire entries in value() need to be removed, traces are still computed and multiplied onto some other entry so that the overall trace of the tensor is preserved. In the case where all labels in the tensor are traced out, label (0,) is re-added so that the total trace of the tensor can be preserved.
copy (bool) – Whether to make a copy of this tensor, or mutate it in place.

Returns:

This instance.

Return type:

StateTensor

upgrade()

If this operator represents a unitary, upgrades it to a tensor representing a superoperator. If this tensor already represents a superoperator, does nothing.

Returns:: This instance.
Return type:: OperatorTensor

value(order='composite-flat')

Returns a dictionary mapping tuples of subsystem labels to operators on those subsystems. Operators acting on n subsystems will have shape (d**n,d**n) or (d**(2*n),d**(2*n)) depending on the current value of is_superop.

Parameters:: order (str) – Advanced users see Tensor.value().
Return type:: dict

mat(order='composite-flat', labels=None)

Returns the matrix form of this operator. The tensor order is the sorted list of all present labels. If n subsystems are present, this matrix will have shape (d**n,d**n) or (d**(2*n),d**(2*n)) depending on the current value of is_superop.

If this is a superoperator, then the basis used is the composite row-stacking basis.

Note

Calling this method will create an array that is exponentially large in the number of subsystems, and causes any distinct subsystems found in value to be permanently merged; calling this method mutates the tensor’s internal representation.

Parameters:

order (str) – Advanced users see Tensor.value().
labels (Iterable) – The desired subsystem label order, which must be a permutation of labels. By default, labels are ordered from smallest to biggest.

Return type:

numpy.ndarray

apply_matrix(labels, matrix)

Mutates this operator by applying the given square matrix to the given labels.

If acting on \(n\) subsystems, this matrix can be a \(d^n \times d^n\) unitary, or a \(d^{2n}\times d^{2n}\) superoparator. If this operator is currently a unitary and a superoperator is applied, upgrade() is called. If this state is currently a superoperator and a unitary is applied, the unitary is made into a superoperator before applying.

import trueq as tq
import numpy as np

t = tq.math.OperatorTensor(2)

# apply a unitary to qubits 0 and 1
t.apply_matrix((0, 1), tq.Gate.cnot.mat)

# apply a 1% bitflip superoperator. this upgrades to a superoperator
s = 0.99 * np.eye(4) + 0.01 * np.kron(tq.Gate.x.mat, tq.Gate.x.mat)
t.apply_matrix((1,), s)

# show the full superoperator
tq.plot_mat(t.mat())

The vectorization convention of superoperators is important. Mixed states are stored in a subsystem-wise row-stacked vectorization convention, and therefore superoperators need to use this convention too. See to_rowstack_super().

Parameters:

labels (Iterable) – Which subsystems to apply the matrix to.
matrix (numpy.ndarray-like) – A square matrix.

diagonal(mat=None, force_real=True)

Returns a new 1D Tensor whose values are the diagonal elements of this operator conjugated by the given matrix.

For example, if the matrix is the change of basis matrix from the vectorized Pauli basis to the row-stacking basis, then the result is proportional to the Pauli transfer matrix diagonal:

import trueq as tq

circuit = tq.Circuit([{(0, 1): tq.Gate.cnot}])
s = tq.Simulator().add_depolarizing(0.01).operator(circuit)

# the PTM off by a scale of 2 on every subsystem
basis = [tq.math.Weyls(pauli).herm_mat.ravel() for pauli in "IXYZ"]
s.diagonal(np.array(basis).T).mat("f")

array([ 4.00000000e+00,  1.98000000e+00,  1.98000000e+00,  2.22044605e-16,
        0.00000000e+00,  0.00000000e+00,  0.00000000e+00,  0.00000000e+00,
        0.00000000e+00,  0.00000000e+00,  0.00000000e+00,  0.00000000e+00,
        3.96000000e+00,  1.96020000e+00,  1.96020000e+00, -1.11022302e-16])

Parameters:

mat (numpy.ndarray) – A dimension-compatible square matrix to change the basis by.
force_real (bool) – Forces the dtype of the returned tensor to be real.

Return type:

trueq.math.tensor.to_rowstack_super(A, B, d, n)

Returns the superoperator of the operation \(X\mapsto AXB^T\) in the subsystem-wise row stacking basis.

See https://arxiv.org/abs/1111.6950 Section V for details on subsystem-wise vs. composite stacking vectorization bases (though beware that this reference uses the column stacking convention).

Parameters:

A – The left-multiplication operator, a square matrix.
B (numpy.ndarray) – The right-multiplication operator, a matrix with the same shape as A.
d (int) – The subsystem dimension.
n (int) – The number of subsystems.

Returns:

The superoperator corresponding to conjugating an input by the given matrices.

Return type:

numpy.ndarray

Weyl Operators

class trueq.math.weyl.WeylBase(powers, dim=None)

Base class for symplectic representations of collections and mappings of qudit Weyl operators.

Common to all subclasses, and present in this base class, is a matrix of integer powers which represent the desired operator(s). Each row of the powers matrix corresponds to a tensor product of single-qudit Weyls, \(W_{x,z}=\otimes_{j=1,\ldots, n} W_{x_j,z_j}\) where \(x,z\in\mathbb{Z}_d^n\) and \(d\geq 2\) is the subsystem dimension. A single-qudit Weyl is the product of a power of the shift operator, \(X=\sum_{i\in\mathbb{Z}_d}|i+1\rangle\langle i|\), and the clock operator, \(Z=\sum_{i\in\mathbb{Z}_d}e^{2\pi i/d}|i\rangle\langle i|\), given as \(W_{x,z}=X^x Z^z\) for \(x,z\in\mathbb{Z}_d\). For \(d=2\), these correspond to the Pauli operators up to a phase for \(Y\).

In a given row of the powers matrix, the first half of a row, \(x\), stores the shift operator powers, and the second half of a row, \(z\), stores the clock operator powers; each row of the powers matrix represents a multi-qudit Weyl operator. Some subclasses of this base class may contain a vector of phases with one phase for each row of the matrix.

For convenience, the constructor allows the powers matrix to be specified as a string. For \(d=2\), the strings may be upper case Pauli strings, where multiple multi-qubit Paulis are separated by the _ character:

from trueq.math.weyl.base import WeylBase

p = WeylBase("XXYZ_IXYZ")
print(p)
p.powers

XXYZ_IXYZ

array([[1, 1, 1, 0, 0, 0, 1, 1],
       [0, 1, 1, 0, 0, 0, 1, 1]], dtype=uint64)

For \(d\geq 2\), single-qudit Weyl operators can be entered in the form, e.g., W21 which represents \(W_{2,1}\). These are concatenated together, and multiple multi-qudit Weyl operators are separate by the _ character:

from trueq.math.weyl.base import WeylBase

p = WeylBase("W20W11W01_W21W00W02", dim=3)
print(p)
p.powers

W20W11W01_W21W00W02

array([[2, 1, 0, 0, 1, 1],
       [2, 0, 0, 1, 0, 2]], dtype=uint64)

Parameters:

powers (array_like | string | WeylBase) – An array of powers or a string representation, both of which are described above. All numbers are taken the modulo of the dimension at construction. Alternatively, this can also be another WeylBase (or child class) instance, from which the powers and dimension will be taken.
dim (int | NoneType) – The qudit dimension, which must be one of SMALL_PRIMES. The default value of None will result in the default dimension obtained from get_dim(). This value is unused if powers is given as another WeylBase instance.

Raises:

ValueError – If powers argument is empty.
ValueError – If a string specification is ragged.
ValueError – If a Pauli string is given but \(d\neq 2\).
ValueError – If an array is given with an odd number of columns.

DTYPE: alias of uint64

ROW_CHAR = '_': The row separation character for string representations.

WEYL_CHAR = 'W': The Weyl prefix character for string representations.

property dim

The dimension of each subsystem.

Type:: int

property powers

The array storing the symplectic representation via powers of the shift and clock operators. See also x (shift powers) and z (clock powers).

Type:: numpy.ndarray

property powers_str

An array of strings representing each element in powers.

Type:: array_like

property n_sys

The number of qudits in each multi-qudit Weyl.

Type:: int

property x

The 2D array of shift powers; the left half of powers.

Type:: numpy.ndarray

property z

The 2D array of clock powers; the right half of powers.

Type:: numpy.ndarray

classmethod eye(n_sys, dim=None)

Returns an identity instance of this class.

Parameters:

n_sys (int) – The number of subsystems.
dim (int | NoneType) – The subsystem dimension.

Return type:

classmethod random(n_sys, n_weyls=1, dim=None, include_id=True)

Returns a random instance of this class.

Parameters:

n_sys (int) – The number of subsystems.
n_weyls (int) – The number of multi-qudit Weyls.
dim (int | NoneType) – The qudit dimension, which must be one of SMALL_PRIMES. The default value of None will result in the default dimension obtained from get_dim().
include_id (bool) – Whether to include any identites in the output.

Return type:

classmethod from_dict(dic)

Converts a dictionary representation into a Weyl instance, see also to_dict().

Parameters:: dic (dict) – The dictionary representation of the Weyls.
Return type:: WeylBase

to_dict()

Converts this instance into a dictionary representation, see also from_dict().

Return type:: dict

class trueq.math.weyl.WeylDecomp(powers, coeffs, dim=None)

Represents the decomposition of a multi-qudit operator in the Weyl operator basis.

Each operator is decomposed into a vector of coefficients that correspond to each of the Weyl operators. See WeylBase for information about the storage format of the Weyl operators.

import trueq as tq
import trueq.math as tqm
import numpy as np

# construct a Weyl Decomposition with a list of Weyls and vector of coefficients
decomp1 = tqm.WeylDecomp("X_Z", [0.5, 3 - 2j])

# assert that the resulting matrix is as expected
mat = 0.5 * tq.Gate.x.mat + (3 - 2j) * tq.Gate.z.mat
assert np.allclose(decomp1.mat, mat)

# alternatively start with the matrix operator and then calculate decomposition
decomp2 = tqm.WeylDecomp.from_mat(mat)
assert np.allclose(decomp2.powers, tqm.Weyls("X_Z").powers)
assert np.allclose(decomp2.coeffs, [0.5, 3 - 2j])
assert decomp1 == decomp2

Parameters:

powers (array_like | string | WeylBase) – A powers matrix specification, as described by WeylBase.
coeffs (array_like) – A vector of complex floats corresponding to the coefficients of each Weyl operator specified by powers.
dim (int | NoneType) – The qudit dimension, which must be one of SMALL_PRIMES. The default value of None will result in the default dimension obtained from get_dim().

Raises:

ValueError – If either the powers matrix or coeffs vector have an invalid shape.

property coeffs

Returns the vector of coefficients that corresponds to each Weyl operator for this instance.

Type:: ndarray

classmethod eye(n_sys, dim=None)

Returns an identity instance of this class.

Parameters:

n_sys (int) – The number of subsystems.
dim (int | NoneType) – The subsystem dimension.

Return type:

classmethod from_mat(mat)

Returns a new instance of this class, as generated by the given operator.

Parameters:

mat (array_like) – A mulit-qudit operator, in matrix form.
dim (int | NoneType) – The qudit dimension, which must be one of SMALL_PRIMES. The default value of None will result in the default dimension obtained from get_dim().

Raises:

ValueError – If mat is not square.
ValueError – If mat size is greater than 50.
ValueError – If mat size is not a power of dim.

property mat

Returns the matrix representation of the decomposition stored by this instance. Calculates the summation of the product of each Weyl operator and its corresponding coefficient.

Type:: ndarray

classmethod random(n_sys, dim=None)

Returns a random instance of this class. All Weyl operators will be used as a basis for powers, while coeffs will be randomly distributed.

Parameters:

n_sys (int) – The number of subsystems.
n_weyls (int) – The number of multi-qudit Weyls.
dim (int | NoneType) – The qudit dimension, which must be one of SMALL_PRIMES. The default value of None will result in the default dimension obtained from get_dim().

Return type:

property y_shifted_coeffs

When \(d=2\), returns the vector of coefficients that corresponds to each Pauli operator for this instance. Coefficients for operators with \(Y\) parts will have their phases corrected to match the Paulis rather than \(X^x Z^z\).

Type:: ndarray
Raises:: ValueError – If dim is not 2.

class trueq.math.weyl.Weyls(powers, dim=None)

Represents a list of multi-qudit projective Weyl operators.

If the dimension is 2, then this is equivalent to a list of multi-qubit Pauli operators. This class inherits the methods of WeylBase, and also features additional functions such as all() that would not be suitable for all child classes of WeylBase. See WeylBase for information about the storage format.

import trueq.math as tqm

# create a list of two three-qubit Paulis, XYZ and ZIY
tqm.Weyls("XYZ_ZIY")

# create a list of two three-qutrit Weyls
tqm.Weyls("W00W02W11_W11W01W20", 3)

True-Q formatting will not be loaded without trusting this notebook or rerunning the affected cells. Notebooks can be marked as trusted by clicking "File -> Trust Notebook".

Type:

Weyls

Dim:

3

Powers:

Here are examples exploring some of the main feature of this class:

import trueq.math as tqm

# two equivalent ways of creating W_{1, 0}, equal to Pauli X
assert tqm.Weyls("X") == tqm.Weyls([1, 0])

# two ways of creating W_{0, 1} W_{2, 3} in dimension 5
assert tqm.Weyls("W01W23", 5) == tqm.Weyls([[0, 2, 1, 3]], 5)

# two equivalent ways to list all single qubit Weyls, I, X, Y, Z
assert tqm.Weyls("I_X_Y_Z") == tqm.Weyls([[0, 0], [1, 0], [1, 1], [0, 1]])

# get the first three qubit Pauli from a list
assert tqm.Weyls("XYZ_ZIY")[0, :] == tqm.Weyls("XYZ")

# get a list of the Weyl operators acting on only the second qutrit
assert tqm.Weyls("W00W02W11_W11W01W20", 3)[:, 1] == tqm.Weyls("W02_W01", 3)

# Weyls can be multiplied, up to a phase
assert tqm.Weyls("X") @ tqm.Weyls("Y") == tqm.Weyls("Z")

# mutliplication distributes across broadcastable shapes
assert tqm.Weyls("X") @ tqm.Weyls("X_Y_Z_I") == tqm.Weyls("I_Z_Y_X")

Parameters:

powers (array_like | string | WeylBase) – A powers matrix specification, as described by WeylBase.
dim (int | NoneType) – The qudit dimension, which must be one of SMALL_PRIMES. The default value of None will result in the default dimension obtained from get_dim(). This value is unused if powers is given as another WeylBase instance.

property adj

A new instance of the same type where the adjoint of each has been taken.

Type:: Weyls

property iter_sys

An iterator yielding each subsystem of this instance as a new single-qudit Weyls.

Type:: generator

property n_weyls

The number of multi-qudit Weyls stored in this instance.

Type:: int

property gate

Constructs and returns the unitary matrix representation of this Weyl operator in the canonical basis as a Gate. If this instance contains multiple Weyl operators, that is, if n_weyls is greater than 1, an error will be raised. In this case, consider gates instead.

For example,

import trueq as tq
import trueq.math as tqm

assert tqm.Weyls("XX").gate == tq.Gate.x & tq.Gate.x

# note that there is a -I phase difference here which Gate equality ignores
assert tqm.Weyls("Y").gate == tq.Gate.y

Type:: Gate
Raises:: ValueError – If this instance contains more than one multi-qudit Weyl.

property gates

Constructs and returns a list containing the unitary matrix representations of each Weyl operator in this instance, in the canonical basis as a Gate.

For example,

import trueq as tq
import trueq.math as tqm

assert tqm.Weyls("Y").gates == [tq.Gate.y]

assert tqm.Weyls("XX").gates == [tq.Gate.x & tq.Gate.x]

assert tqm.Weyls("I_Z").gates == [tq.Gate.id, tq.Gate.z]

Type:: list

property herm_mat

A Hermitian version of mat such that:

Each distinct multi-qudit Weyl operator results in a fixed, unique Hermitian matrix.

Matrices on \(n\) \(d\)-dimensional subsystems are normalized to \(\sqrt{d^n}\).

Unequal multi-qudit Weyl operators result in orthogonal matrices.

When \(d=2\) the usual multi-qubit Pauli matrices are used, where, in particular, \(Y=\left(\begin{smallmatrix}0&-i\\i&0\end{smallmatrix}\right)\) rather than \(XZ=iY\), as used by mat.

The span of any set of multi-qudit Weyl operators along with their adjoints results in the corresponding span of these Hermitian matrices.

The above properties are obtained with the following construction, where, unlike other methods and attributes of this class, we use the phase convention \(W_{x,z}=e^{i \pi xz}X^xZ^z\) for a pair of powers \(x,z\in\mathbb{Z}_d\). This is done to ensure the orthogonality criterion. Given some \(W_{x,z}\), its adjoint is \(W_{x,z}^\dagger=W_{-x,-z}=e^{i \pi xz}X^{-x}Z^{-z}\), and a Hermitian matrix is constructed from it by normalizing either \(W_{x,z}+W_{x,z}^\dagger\) or \(iW_{x,z}-iW_{x,z}^\dagger\). The former choice is made whenever \((x,z)>=(d-x,d-z)\mathrm{mod}d\) lexicographically, and the latter choice is made otherwise.

Like mat, the return shape is 3D if n_weyls is greater than one, where the output’s first index is over multi-qudit Weyls, otherwise the return shape is 2D.

Type:: ndarray

property mat

The matrix representation, or an array of matrix representations, of the Weyl(s) contained in this instance, in the canonical basis. The return shape is 3D if n_weyls is greater than one where the first index is over multi-qudit Weyls, otherwise the return shape is 2D.

Type:: ndarray

classmethod all(n_sys, dim=None, include_id=True, lex=True)

Returns a new Weyls instance where every possible projective multi-qudit Weyl operator appears as a row.

If lex is True, then the order is primarily lexicographic in the subsystems with the right-most subsystem rastering fastest, and secondarily lexicographic in the integer pair (x, z) for each subsystem. Otherwise, the secondary ordering is chosen so that operators that are adjoints of each other are adjacent, and also so that when \(d=2\), the subsystem order is \(I, X, Y, Z\).

Parameters:

n_sys (int) – The number of subsystems.
dim (int | NoneType) – The subsystem dimension.
include_id (bool) – Whether to include any identites in the output.
lex (bool) – Whether to order subsystems lexicographically in \((x,z)\), as described above.

Return type:

delete_duplicates(herm_equal=False)

Returns a new instance where the rows have been sliced to only contain Weyls which are not equal to each other. Optionally, two rows can be treated as equal when they are adjoints of each other. The returned instance will have rows sorted in the same way that all() sorts rows when lex=False.

import trueq.math as tqm

# remove duplicate rows
assert tqm.Weyls("XX_YY_XY_XX").delete_duplicates() == tqm.Weyls("XX_XY_YY")

# remove duplicate rows, including adjoints
weyl1 = tqm.Weyls("W11_W12_W22", dim=3)
weyl2 = tqm.Weyls("W11_W12", dim=3)
assert weyl1.delete_duplicates(True) == weyl2

Parameters:: herm_equal (bool) – Whether or not to treat rows which are equal to each other up to an adjoint as equal. In such a case, the row with the lower indices() (with lex=False) is kept. This flag is not relevant for qubit systems because no distinct Paulis are adjoints of each other.
Return type:: Weyls

indices(lex=True)

Returns the index of every row in this Weyls with respect to the order defined by all().

Parameters:: lex (bool) – Whether to order subsystems lexicographically in \((x,z)\), as described in all().
Return type:: numpy.ndarray

class trueq.math.weyl.WeylSet(powers, dim=None)

Represents a set of multi-qudit projective Weyl operators.

If the dimension is 2, then this is equivalent to a set of multi-qubit Pauli operators. See WeylBase for information about the storage format.

The only difference between this class and its parent, Weyls, is that this class automatically sorts and deletes duplicate rows of the given powers matrix during construction.

import trueq.math as tqm

# create a set of three-qubit Paulis, and note that the duplicate row is removed
# and that the remaining rows are sorted.
tqm.Weyls("XYZ_XYZ_ZIY_XYZ")

True-Q formatting will not be loaded without trusting this notebook or rerunning the affected cells. Notebooks can be marked as trusted by clicking "File -> Trust Notebook".

Type:

Weyls

Dim:

2

Powers:

Parameters:

powers (array_like | string | WeylBase) – A powers matrix specification, as described by WeylBase.
dim (int | NoneType) – The qudit dimension, which must be one of SMALL_PRIMES. The default value of None will result in the default dimension obtained from get_dim(). This value is unused if powers is given as another WeylBase instance.

classmethod all(n_sys, dim=None, include_id=True)

Returns a new Weyls instance where every possible projective multi-qudit Weyl operator appears as a row.

Parameters:

n_sys (int) – The number of subsystems.
dim (int | NoneType) – The subsystem dimension.
include_id (bool) – Whether to include any identites in the output.

Return type:

class trueq.math.weyl.Stabilizers(powers, phase_ints, dim=None)

Class that represents a list of multi-qudit Weyl operators with associated phases that are constrained to certain discrete values on the unit circle.

Specifically, each multi-qudit Weyl operator in an instance of this class must leave a nontrivial subspace invariant and so cannot generate a group that contains nontrivial multiples of the identity. Common parent class to Clifford and StabilizerGroup.

An instance of this class contains a representation in terms of two integer arrays. The first is an array of powers, where the left half contains powers of the single-qudit \(X\) operator, and the right half contains powers of the single-qudit \(Z\) operator, so that each row represents a multi-qudit operator. The second is a vector of phase powers, one for each multi-qudit operator. For a particular multi-qudit operator with length-\(n\) power vectors \(x\) and \(z\), a phase integer of value \(j\) results in a phase of \(exp(\pi i (2j + (x.z \% 2)) / d)\) for \(d=2\), and a phase of \(exp(2\pi ij/ d)\) for \(d>2\).

import trueq.math as tqm

# define stabilizers using two Weyls and a list of phases
stab_pauli = tqm.Stabilizers(tqm.Weyls("W00W11_W00W22"), [0, 1])

# get the list of phases in complex form
stab_pauli.phases

array([ 6.123234e-17+1.0000000e+00j, -1.000000e+00+1.2246468e-16j])

Parameters:

powers (array_like | string | WeylBase) – A powers matrix specification, as described by WeylBase.
phase_ints (array_like) – A vector of integers corresponding to the phases of each Weyl operator specified by powers.
dim (int | NoneType) – The qudit dimension, which must be one of SMALL_PRIMES. The default value of None will result in the default dimension obtained from get_dim().

Raises:

ValueError – If either the powers matrix or phase_ints vector have an invalid shape.

property phase_ints

The array corresponding to the phases of each Weyl generator in the stabilizer group, represented as integers modulo dim.

Type:: numpy.ndarray

property phases

The array corresponding to the phases of each Weyl generator in the stabilizer group, evaluated to their complex values.

Type:: numpy.ndarray

apply(clifford, subsystems=None)

Returns a new Stabilizers object with the same type as self where (a subset of subsystems of) rows have been taken to their image under the Clifford operation.

When self is also a Clifford operation, this results in standard Clifford multiplication, where subsystems provides the option to multiply a small Clifford into selected subsystems of some larger Clifford.

import trueq.math as tqm

cx = tqm.Clifford.cx()

# apply a random single-qubit Clifford onto the second half of a CX
cx.apply(tqm.Clifford.random(1), [1])

True-Q formatting will not be loaded without trusting this notebook or rerunning the affected cells. Notebooks can be marked as trusted by clicking "File -> Trust Notebook".

Type:

Clifford

Dim:

2

Generator images:

Note

When subsystems=None, the Clifford is applied to all subsystems of this object, so that this method becomes identical to other @ self. Notice, in particular, that other comes before self (in contrast to self.apply(other)) because @ has been implemented to conform to the standard matrix multiplication ordering.

Parameters:

cliff (Clifford) – A Clifford operation to apply to a subset of subsystems.
subsystems (NoneType | Iterable) – Which subsystems to apply to; an iterable of integers indexed from 0 to one minus n_sys. The order is respected. Or, None which indicates that it should be applied to all subsystems.

Return type:

Stabilizers

classmethod eye(n_sys, dim=None)

Returns an identity instance of this class.

Parameters:

n_sys (int) – The number of subsystems.
dim (int | NoneType) – The subsystem dimension.

Return type:

classmethod random(n_sys, n_weyls=1, dim=None)

Returns a random instance of this class.

Parameters:

n_sys (int) – The number of subsystems.
n_weyls (int) – The number of multi-qudit Weyls.
dim (int | NoneType) – The qudit dimension, which must be one of SMALL_PRIMES. The default value of None will result in the default dimension obtained from get_dim().

Return type: