Operations

`trueq.Operation`	Parent class of all primitive quantum operations.
`trueq.Gate`	Represents a unitary quantum gate.
`trueq.Meas`	A measurement of a single qubit in the computational basis.
`trueq.NativeGate`	A subclass of `Gate` which introduces metadata attributes.
`trueq.Prep`	A preparation of a single qubit into the ground state of the computational basis.

Operation

class trueq.Operation: Parent class of all primitive quantum operations.

Gate

class trueq.Gate(u)

Represents a unitary quantum gate.

import trueq as tq

tq.Gate([[0, 1], [1, 0]])

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".

Many standard gates are predefined as attributes:

import trueq as tq

print("All available predefined gate names:")
print(list(tq.Gate.ALIASES))

# Accessing a predefined gate:
tq.Gate.cx

All available predefined gate names:
['id', 'x', 'y', 'z', 'cx', 'cy', 'cz', 'swap', 'iswap', 'h', 's', 'sx', 'sy', 't', 'ch', 'i', 'sz', 'f', 'cnot', 'cliff0', 'cliff1', 'cliff2', 'cliff3', 'cliff4', 'cliff5', 'cliff6', 'cliff7', 'cliff8', 'cliff9', 'cliff10', 'cliff11', 'cliff12', 'cliff13', 'cliff14', 'cliff15', 'cliff16', 'cliff17', 'cliff18', 'cliff19', 'cliff20', 'cliff21', 'cliff22', 'cliff23', 'id3', 'x3', 'y3', 'z3', 'cx3', 'cz3', 'f3', 'x3pow2', 'y3pow2', 'x3pow1', 'y3pow1', 'cnot3', 'id5', 'x5', 'y5', 'z5', 'cx5', 'cz5', 'f5', 'x5pow2', 'x5pow3', 'x5pow4', 'y5pow2', 'y5pow3', 'y5pow4', 'x5pow1', 'y5pow1', 'cnot5', 'id7', 'x7', 'y7', 'z7', 'cx7', 'cz7', 'f7', 'x7pow2', 'x7pow3', 'x7pow4', 'x7pow5', 'x7pow6', 'y7pow2', 'y7pow3', 'y7pow4', 'y7pow5', 'y7pow6', 'x7pow1', 'y7pow1', 'cnot7']

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".

The static method from_generators() can be used to construct gates from Pauli rotations.

Note

Gates are not checked to be unitary on instantiation; call is_unitary manually to check.

Parameters: u (numpy.ndarray-like | dict) – A unitary matrix in the computational basis.

ALIASES = {'ch': Gate.ch, 'cliff0': Gate.id, 'cliff1': Gate.x, 'cliff10': Gate.cliff10, 'cliff11': Gate.cliff11, 'cliff12': Gate.h, 'cliff13': Gate.cliff13, 'cliff14': Gate.cliff14, 'cliff15': Gate.cliff15, 'cliff16': Gate.cliff16, 'cliff17': Gate.cliff17, 'cliff18': Gate.cliff18, 'cliff19': Gate.cliff19, 'cliff2': Gate.y, 'cliff20': Gate.cliff20, 'cliff21': Gate.cliff21, 'cliff22': Gate.cliff22, 'cliff23': Gate.cliff23, 'cliff3': Gate.z, 'cliff4': Gate.cliff4, 'cliff5': Gate.sx, 'cliff6': Gate.cliff6, 'cliff7': Gate.sy, 'cliff8': Gate.cliff8, 'cliff9': Gate.s, 'cnot': Gate.cx, 'cnot3': Gate.cx3, 'cnot5': Gate.cx5, 'cnot7': Gate.cx7, 'cx': Gate.cx, 'cx3': Gate.cx3, 'cx5': Gate.cx5, 'cx7': Gate.cx7, 'cy': Gate.cy, 'cz': Gate.cz, 'cz3': Gate.cz3, 'cz5': Gate.cz5, 'cz7': Gate.cz7, 'f': Gate.h, 'f3': Gate.f3, 'f5': Gate.f5, 'f7': Gate.f7, 'h': Gate.h, 'i': Gate.id, 'id': Gate.id, 'id3': Gate.id3, 'id5': Gate.id5, 'id7': Gate.id7, 'iswap': Gate.iswap, 's': Gate.s, 'swap': Gate.swap, 'sx': Gate.sx, 'sy': Gate.sy, 'sz': Gate.s, 't': Gate.t, 'x': Gate.x, 'x3': Gate.x3, 'x3pow1': Gate.x3, 'x3pow2': Gate.x3pow2, 'x5': Gate.x5, 'x5pow1': Gate.x5, 'x5pow2': Gate.x5pow2, 'x5pow3': Gate.x5pow3, 'x5pow4': Gate.x5pow4, 'x7': Gate.x7, 'x7pow1': Gate.x7, 'x7pow2': Gate.x7pow2, 'x7pow3': Gate.x7pow3, 'x7pow4': Gate.x7pow4, 'x7pow5': Gate.x7pow5, 'x7pow6': Gate.x7pow6, 'y': Gate.y, 'y3': Gate.y3, 'y3pow1': Gate.y3, 'y3pow2': Gate.y3pow2, 'y5': Gate.y5, 'y5pow1': Gate.y5, 'y5pow2': Gate.y5pow2, 'y5pow3': Gate.y5pow3, 'y5pow4': Gate.y5pow4, 'y7': Gate.y7, 'y7pow1': Gate.y7, 'y7pow2': Gate.y7pow2, 'y7pow3': Gate.y7pow3, 'y7pow4': Gate.y7pow4, 'y7pow5': Gate.y7pow5, 'y7pow6': Gate.y7pow6, 'z': Gate.z, 'z3': Gate.z3, 'z5': Gate.z5, 'z7': Gate.z7}

A dictionary containing pre-defined qudit gates for dimensions 2, 3, 5, and 7, where the keys are the gate names, for example CNOT, or H. Gates in this dictionary can be accessed using trueq.Gate.<gate_name>, for example:

import trueq as tq

tq.Gate.cnot

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".

QUDIT_DIM2_ALIASES = {'ch': Gate.ch, 'cliff0': Gate.id, 'cliff1': Gate.x, 'cliff10': Gate.cliff10, 'cliff11': Gate.cliff11, 'cliff12': Gate.h, 'cliff13': Gate.cliff13, 'cliff14': Gate.cliff14, 'cliff15': Gate.cliff15, 'cliff16': Gate.cliff16, 'cliff17': Gate.cliff17, 'cliff18': Gate.cliff18, 'cliff19': Gate.cliff19, 'cliff2': Gate.y, 'cliff20': Gate.cliff20, 'cliff21': Gate.cliff21, 'cliff22': Gate.cliff22, 'cliff23': Gate.cliff23, 'cliff3': Gate.z, 'cliff4': Gate.cliff4, 'cliff5': Gate.sx, 'cliff6': Gate.cliff6, 'cliff7': Gate.sy, 'cliff8': Gate.cliff8, 'cliff9': Gate.s, 'cnot': Gate.cx, 'cx': Gate.cx, 'cy': Gate.cy, 'cz': Gate.cz, 'f': Gate.h, 'h': Gate.h, 'i': Gate.id, 'id': Gate.id, 'iswap': Gate.iswap, 's': Gate.s, 'swap': Gate.swap, 'sx': Gate.sx, 'sy': Gate.sy, 'sz': Gate.s, 't': Gate.t, 'x': Gate.x, 'y': Gate.y, 'z': Gate.z}

A dictionary containing pre-defined qubit gates where the keys are the gate names, for example CNOT, or H. Gates in this dictionary can be accessed using trueq.Gate.<gate_name>, for example:

import trueq as tq

tq.Gate.cx

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".

QUDIT_DIM3_ALIASES = {'cnot3': Gate.cx3, 'cx3': Gate.cx3, 'cz3': Gate.cz3, 'f3': Gate.f3, 'id3': Gate.id3, 'x3': Gate.x3, 'x3pow1': Gate.x3, 'x3pow2': Gate.x3pow2, 'y3': Gate.y3, 'y3pow1': Gate.y3, 'y3pow2': Gate.y3pow2, 'z3': Gate.z3}

A dictionary containing pre-defined gates for qudits of dimension 3, where the keys are the gate names, for example CNOT3, or X3. Gates in this dictionary can be accessed using trueq.Gate.<gate_name>, for example:

import trueq as tq

tq.Gate.cnot3

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".

QUDIT_DIM5_ALIASES = {'cnot5': Gate.cx5, 'cx5': Gate.cx5, 'cz5': Gate.cz5, 'f5': Gate.f5, 'id5': Gate.id5, 'x5': Gate.x5, 'x5pow1': Gate.x5, 'x5pow2': Gate.x5pow2, 'x5pow3': Gate.x5pow3, 'x5pow4': Gate.x5pow4, 'y5': Gate.y5, 'y5pow1': Gate.y5, 'y5pow2': Gate.y5pow2, 'y5pow3': Gate.y5pow3, 'y5pow4': Gate.y5pow4, 'z5': Gate.z5}: A dictionary containing pre-defined gates for qudits of dimension 5, where the keys are the gate names, for example CNOT5, or X5. Gates in this dictionary can be accessed using trueq.Gate.<gate_name>, e.g. trueq.Gate.cnot5.

QUDIT_DIM7_ALIASES = {'cnot7': Gate.cx7, 'cx7': Gate.cx7, 'cz7': Gate.cz7, 'f7': Gate.f7, 'id7': Gate.id7, 'x7': Gate.x7, 'x7pow1': Gate.x7, 'x7pow2': Gate.x7pow2, 'x7pow3': Gate.x7pow3, 'x7pow4': Gate.x7pow4, 'x7pow5': Gate.x7pow5, 'x7pow6': Gate.x7pow6, 'y7': Gate.y7, 'y7pow1': Gate.y7, 'y7pow2': Gate.y7pow2, 'y7pow3': Gate.y7pow3, 'y7pow4': Gate.y7pow4, 'y7pow5': Gate.y7pow5, 'y7pow6': Gate.y7pow6, 'z7': Gate.z7}: A dictionary containing pre-defined gates for qudits of dimension 7, where the keys are the gate names, for example CNOT7, or X7. Gates in this dictionary can be accessed using trueq.Gate.<gate_name>, e.g. trueq.Gate.cnot7.

static from_generators(*args, dim=None)

Constructs a Gate instance from a compound rotation about Pauli axes. Specifically, the gate is constructed as \(exp(-1j * \sum_i (\pi\theta_i/180) W_i/ 2)\) where \(W_i\) are the input Paulis (of Weyls for qudit systems) and \(\theta_i\) are the input rotation angles in degrees. This can be input either as an alternating sequence of Weyl strings and angles, or as a dict.

import trueq as tq

g1 = tq.Gate.from_generators("X", 90)
g2 = tq.Gate.from_generators("XX", 90, "YY", 180)
g3 = tq.Gate.from_generators({"XX": 90, "YY": 180})
g4 = tq.Gate.from_generators("W01W02", 90, "W10W20", 180, dim=3)

g2

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".

Note

For rotations around a single Pauli term, it is faster to use rp().

Parameters

*args – A single dictionary mapping Pauli strings to angles in degrees, or an alternating sequence thereof.
dim (int) – 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

Gate

get_alias(default=None)

Returns the first matching alias of the gate if possible, or default if no aliases are found.

Parameters: default (NoneType | str) – A string to return if no alias is found for this gate. If no string is specified, None will be returned.
Returns: The alias of this gate if it exists, default otherwise.
Return type: str | NoneType

property is_clifford

Whether or not this gate is Clifford.

If width is not a power of a small prime integer, implying that this gate does not act on \(n\) qudits of dimension in SMALL_PRIMES, this is set to False by convention.

Type: bool

property is_unitary

Whether or not this gate is unitary to numerical precision.

Type: bool

property is_identity

Whether or not this gate is the identity gate to numerical precision.

Type: bool

property mat

The matrix representation of this gate in the canonical basis.

Type: numpy.ndarray

property width

The number of columns of the matrix representation of this gate.

Type: int

property expansion

A sparse representation of this gate in terms of the Weyl operators; when this gate acts on qubits, a dictionary mapping Pauli strings to (complex) coefficients.

Type: dict

static from_alias(alias)

Returns a Gate from common names, such as CX, swap, H, S, etc.

Parameters: alias (str) – A string representing a common gate name found in the ALIASES dictionary, which stores available gates.
Return type: Gate
Raises: KeyError – If the gate is not found.

property generators

Assumes this gate acts on qubits and returns rotations about Pauli axes performed by this Gate. Specifically, outputs a description of this gate in the form: \(exp(-1j * \sum_i (\pi\theta_i/180) P_i/ 2)\) where \(P_i\) are the Pauli strings and \(\theta_i\) are the rotation angles in degrees.

import trueq as tq
import numpy as np

gens = tq.Gate.from_generators("X", 90, "Z", 20).generators
assert np.isclose(gens["X"], 90)
assert np.isclose(gens["Z"], 20)

Type: dict

property adj

A new Gate instance which is the conjugate transpose of this gate.

Type: Gate

property sqrt

A new Gate instance which is a square root of this gate, respecting the global phase. That is, this method guarantees that \(U^{1/2}U^{1/2}=U\) for any unitary gate \(U\). This differs from the general power method on Gate which chooses a certain scheme for global phases tailored for overrotation errors.

Type: Gate

controlled(control_on='1', pos=- 1, exclusive=True, dim=None)

A new Gate instance which is a controlled version of this gate.

The gate is applied to the qudit(s) in positions pos if and only if the rest of the qudits are in the computational basis state control_on, assuming the default value exclusive=True is used.

import trueq as tq

# Toffoli gate
tq.Gate.x.controlled("11")

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".

If exclusive=False, however, the alternate definition \(\sum_{k\in\mathbb{Z}_d^c} |k+m\rangle\langle k+m| \otimes U^{\sum_{i=1}^c k_i}\) is used, where \(m\) is given by control_on, and where \(c\) is the length of \(m\). For example, the CSUM (controlled sum) gate is given by \(\sum_{k=0}^{d-1} |k\rangle\langle k| \otimes X^{k}\) where \(X\) is the qudit shift operator, or W10 in the string syntax of WeylBase. The subsystems are permuted to match pos.

import trueq as tq

# CSUM gate for qutrits
tq.Gate(tq.math.Weyls("W10", dim=3)).controlled("0", exclusive=False)

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".

Parameters

control_on (Iterable | str) – The ditstring specifying the computational state to condition on. This can be any iterable whose elements are castable to integers representing dits. The default setting conditions on the computational basis state \(|1\rangle\).
pos (int | tuple) – The position of the subsystem on which the controlled gate acts. The default is the last subsystem.
exclusive (int | None) – If True, control_on represents the exclusive ditstring state of the control qudits which cause this gate to be applied. If False, the definition provided earlier is applied.
dim – The subsystem dimension. This can usually be left at the default value of None because the subsystem dimension can be inferred from the length of pos and the size of this gate. However, in the edge case that this gate is \(1\times 1\), this is not possible, in which case the value of dim is used, or taken from get_dim() if dim is None.

Return type

Gate

to_clifford()

Returns the Clifford representation of a Clifford gate.

import trueq as tq

tq.Gate.cz.to_clifford()

Clifford('XZ_ZX_ZI_IZ', [0, 0, 0, 0])

Return type

Clifford

Raises

RuntimeError – If width is not a power of a small prime integer in SMALL_PRIMES.
RuntimeError – If the gate is not Clifford.

static cw(weyl, dim=None)

A convenience method to construct a controlled-Weyl Gate defined as \(\sum_{k\in\mathbb{Z}_d} |k\rangle\langle k| \otimes W^{k}\), where \(W\) is the input weyl operator.

import trueq as tq

# this is a cz for qubits
g1 = tq.Gate.cw("W01", 2)

# this is the generalization of cz to qutrits
g2 = tq.Gate.cw("W01", 3)

Parameters

weyl (Weyls | Iterable) – A Weyls, or a Weyl string and a dimension specifying the desired operation.
dim (int) – 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

Gate

embed(extra_dim, n_sys=None)

Returns a Gate that is equal to this gate embedded in a larger Hilbert space. That is, if this gate acts on the space \((\mathbb{C}^d)^{\otimes n}\), then the returned gate will act on the space \((\mathbb{C}^{d+d'})^{\otimes n}\).

Parameters

extra_dim (int) – The number of extra dimensions, \(d'\), to add to each subsystem.
n_sys (int | NoneType) – The number of subsystems that this gate acts on. If unspecified, it is inferred automatically by using auto_base().

Return type

Gate

static random(dim)

Generate a Haar random unitary gate of dimension dim.

Parameters: dim (int) – The dimension of the gate.
Return type: Gate

plot(abs_max=None, ax=None)

Plots the matrix representation of this gate.

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) – An existing axis to plot on. If not given, a new figure will be created.

static rp(pauli, angle, dim=None)

Construct a Gate from a Pauli or Weyl rotation by the specified angle.

import trueq as tq
import numpy as np

gens = tq.Gate.rp("XX", 10).generators
assert np.isclose(gens["XX"], 10)

g_weyl = tq.Gate.rp("W02", 10, dim=3)

Note

For single pauli rotations this is faster numerically than from_generators().

Note

The methods rp() and rw() are identical. They both exist to make searching the documentation easier.

Parameters

pauli (str) – The Pauli axis of rotation, or the Weyl axis for qudit systems.
angle (float) – The angle of the rotation in degrees.
dim (int) – 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

Gate

static rw(pauli, angle, dim=None)

Construct a Gate from a Pauli or Weyl rotation by the specified angle.

import trueq as tq
import numpy as np

gens = tq.Gate.rp("XX", 10).generators
assert np.isclose(gens["XX"], 10)

g_weyl = tq.Gate.rp("W02", 10, dim=3)

Note

For single pauli rotations this is faster numerically than from_generators().

Note

The methods rp() and rw() are identical. They both exist to make searching the documentation easier.

Parameters

pauli (str) – The Pauli axis of rotation, or the Weyl axis for qudit systems.
angle (float) – The angle of the rotation in degrees.
dim (int) – 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

Gate

static rx(angle)

Constructs a Gate from a Pauli X rotation by the specified angle.

import trueq as tq
import numpy as np

gens = tq.Gate.rx(10).generators
assert np.isclose(gens["X"], 10)

Parameters: angle (float) – The angle of the rotation in degrees.
Return type: Gate

static ry(angle)

Constructs a Gate from a Pauli Y rotation by the specified angle.

import trueq as tq
import numpy as np

gens = tq.Gate.ry(10).generators
assert np.isclose(gens["Y"], 10)

Parameters: angle (float) – The angle of the rotation in degrees.
Return type: Gate

static rz(angle)

Constructs a Gate from a Pauli Z rotation by the specified angle.

import trueq as tq
import numpy as np

gens = tq.Gate.rz(10).generators
assert np.isclose(gens["Z"], 10)

Parameters: angle (float) – The angle of the rotation in degrees.
Return type: Gate

static fourier(dim=None)

Returns a Fourier Gate acting on a qudit of dimension dim, as defined in [18]. The Fourier Gate maps \(X \rightarrow Z, Z \rightarrow X^{-1}\), and can thus be regarded as a generalization of the Hadamard gate to qudits.

Parameters: dim (int) – 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: Gate

static w(weyl, dim=None)

Constructs a Gate implementing a Weyls operation. The desired operation can be input either as Weyl strings and associated dimention, or as a Weyls.

import trueq as tq
from trueq.math import Weyls

g1 = tq.Gate.w("W02", 3)
g2 = tq.Gate.w(Weyls("W02", dim=3))

Parameters

weyl (Weyls | str) – A Weyls, or a Weyl string and a dimension specifying the desired operation.
dim (int) – 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

Gate

Measurement

class trueq.Meas

A measurement of a single qubit in the computational basis.

This class holds no information, it allows a trueq.Circuit to keep track of where a measurement has taken place.

This is a singleton class; the constructor always yields the same instance.

Native Gate

class trueq.NativeGate(name, u, params=None)

A subclass of Gate which introduces metadata attributes.

name is a string giving a name to the gate.

(optional) parameters is a dictionary that maps parameter names to parameter values.

These attributes are entirely metadata; there are no automatic consistency checks between them and the matrix representation. The purpose of these attributes is to provide tools, such as transpilers to third-party circuit formats, with a fast method of identifying gates without introspecting matrices. This requires trust that these metadata were generated correctly and in good faith.

Native gates are typically (and most easily) constructed by GateFactorys, which are usually owned by Config objects.

import trueq as tq

config = tq.Config.basic()
config.sx()

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".

Native gates are not intended to be mutable, and the parameters and names should not be changed after instantiation.

Parameters

name (str) – Name of the gate operation.
u (dict) – See Gate.
params (dict) – Any parameters that the gate needs in order to be constructed.

static from_generators(name, *args, params=None)

Constructs a NativeGate instance from rotations about Paulis. Also adds a name and any parameters used to construct the native gate. Specifically, the output gate in this case is given by \(exp(-1j * \sum_i (\pi\theta_i/180) P_i/ 2)\) where \(P_i\) are the input Pauli strings and \(\theta_i\) are the input rotation angles in degrees. This can be input either as an alternating sequence of Pauli strings and angles, or as a dict.

import trueq as tq

g1 = tq.NativeGate.from_generators("name", "X", 90, params={"theta": 90})
g2 = tq.NativeGate.from_generators("name", "XX", 90, "YY", 180)
g3 = tq.NativeGate.from_generators("name", {"XX": 90, "YY": 180})

g1

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".

Parameters

name (str) – Name of the gate operation.
*args – A single dictionary mapping Pauli strings to angles in degrees, or an alternating sequence thereof.
params (dict) – Any parameters that the gate needs in order to be constructed.

Return type

NativeGate

property parameters

The stored parameters.

Type: dict

property name

The name of this native gate.

Type: str

Preparation

class trueq.Prep

A preparation of a single qubit into the ground state of the computational basis.

This class holds no information, it allows a trueq.Circuit to keep track of where a state preparation has taken place.

This is a singleton class; the constructor always yields the same instance.