Circuits¶
TrueQ™ uses the following highlevel classes to define circuits, their components, and their results:
Operation
: a quantum operationCycle
: a clock cycle of a quantum circuitCircuit
: a list of cycles and other metadataResults
: stores the results when a quantum circuit is run on hardware
Operations¶
The Operation
object is an abstract base class for
general quantum operations. TrueQ™ uses four different types of primitive
quantum operations:
Gate
: a generic unitary operation applied during a quantum circuit.NativeGate
: a unitary operation that is native to a given hardware platform.Prep
: an input to a quantum circuit.Meas
: generates the output of a quantum circuit.
Gates¶
The Gate
class is a thin wrapper over a NumPy matrix. The primary
difference is that the equality for TrueQ™ gates ignores an overall phase (that is, a
complex number with unit modulus), which has no physical meaning in quantum information.
Any userspecified gate should be a unitary matrix. Although this is not checked upon
construction for performance reasons, it can be checked as shown below. Common gates for
qubits are aliased for convenience. All instances of Gate
are
immutable.
import trueq as tq
# view the list of aliased gates
print(tq.Gate.ALIASES)
# construct a Pauli X gate and visualize it using visualization.plot_mat()
gate = tq.Gate.x
tq.visualization.plot_mat(gate.mat)
# construct a gate from a matrix
phased_gate = tq.Gate([[0, 1j], [1j, 0]])
tq.visualization.plot_mat(phased_gate.mat)
# check that equality holds up to an overall phase
print("Equality holds up to a phase:", phased_gate == gate)
# check that equality holds up to an overall phase
scaled_gate = tq.Gate([[0, 2], [2, 0]])
print("scaled_gate is unitary:", scaled_gate.is_unitary)
print("Equality holds for arbitary constants:", phased_gate == scaled_gate)
{'id': Gate.id, 'x': Gate.x, 'y': Gate.y, 'z': Gate.z, 'cx': Gate.cx, 'cy': Gate.cy, 'cz': Gate.cz, 'swap': Gate.swap, 'iswap': Gate.iswap, 'h': Gate.h, 's': Gate.s, 'sx': Gate.sx, 'sy': Gate.sy, 't': Gate.t, 'ch': Gate.ch, 'i': Gate.id, 'sz': Gate.s, 'cnot': Gate.cx, 'cliff0': Gate.id, 'cliff1': Gate.x, 'cliff2': Gate.y, 'cliff3': Gate.z, 'cliff4': Gate.cliff4, 'cliff5': Gate.sx, 'cliff6': Gate.cliff6, 'cliff7': Gate.sy, 'cliff8': Gate.cliff8, 'cliff9': Gate.s, '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, 'cliff20': Gate.cliff20, 'cliff21': Gate.cliff21, 'cliff22': Gate.cliff22, 'cliff23': Gate.cliff23}
Equality holds up to a phase: True
scaled_gate is unitary: False
Equality holds for arbitary constants: False
We provide additional methods to determine the generators of a gate and to construct gates via generators.
import trueq as tq
# generators can be obtained for generic gates
print(tq.Gate.h.generators)
# gates can be constructed from generators
gate = tq.Gate.from_generators("XX", 90, "YZ", 180)
tq.visualization.plot_mat(gate.mat)
{'X': (127.27922061357854+0j), 'Z': (127.27922061357856+0j)}
NativeGate¶
NativeGate
is a subclass of Gate
which introduces
three new 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 corresponding matrix. The purpose of these attributes is to provide tools such as transpilers to thirdparty 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.
Instances of NativeGate
are often constructed by
GateFactory
s, which are in turn are typically constructed by
Config
objects (see Configuration for more
details).
import trueq as tq
# make a factory that produces z rotations
rz = tq.config.GateFactory.from_matrix("Rz", [[1, 0], [0, "exp(1j*pi*theta/180)"]])
# construct a native gate
rz(90)
 Name:

 Rz(theta)
 Aliases:

 Gate.s
 Gate.sz
 Gate.cliff9
 Parameters:

 theta = 90
 Generators:

 'Z': 90.0
 Matrix:

Measurements¶
Meas
is a singleton class that records where measurements occur
in a Circuit
. This is always a singlequbit operation. The
results
attribute of a circuit must be consistent with the
total number of Meas
that are present.
Typically, all measurement objects are found in the last cycle in a circuit, however the API does not enforce this. Presently, the simulator fails if this is not the case.
Preparations¶
Prep
is a singleton class that records where state preparations
occur in a circuit. This is always a singlequbit operation. These objects are optional
in circuits and exist mainly:
To allow conversion to and from thirdparty circuit formats that use them.
To allow the simulator to add state preparation noise.
Cycles¶
A Cycle
is a round of operations on a quantum device, which is
essentially a wrapper for a dictionary from tuples of qubit labels to instances of
Operation
s discussed in the previous section. Any system that
does not have a specified Operation
is implicitly acted upon by
an identity Gate
.
import trueq as tq
tq.Cycle({(0, 2): tq.Gate.cz, 1: tq.Gate.x})

(0, 2):
Gate.cz

(1):
Gate.x

Note
The order of system labels in the keys is important. For example, the
controlledX gate is controlled by the first qubit, so that
Cycle({(0, 1): tq.Gate.cx})
flips the state of qubit 1
based
on the state of qubit 0
, whereas Cycle({(1, 0): tq.Gate.cx})
flips the state of 0
based on the state of qubit 1
.
A Cycle
can also be marked with a marker
,
which is an identifier that’s used to label related Cycle
s for
compiler and benchmarking tools. A group of two or more contiguous
Cycle
s which share the same marker
are
treated as a subcircuits during recompilation by various compiler
Pass
es.
Generally speaking, compiler tools are free to merge and expand
Gate
s within a contiguous block of Cycle
s
with equal marker
s; for example, most benchmarking circuits
without marker
s would be compiled down to a single cycle. The
randomly_compile()
function inserts random gates at the edges of
contiguous blocks with equal nonzero markers.
import trueq as tq
tq.Cycle({0: tq.Gate.x, (1, 2): tq.Gate.cz}, marker=3)
3

(1, 2):
Gate.cz

(0):
Gate.x

Results¶
Experimental results can be stored in a Results
object. This results
object is a thin wrapper for a dictionary class whose keys are concatenated strings
of outcomes (e.g., "001"
) to either relative frequencies or to the number of
observations. A results object also contains attributes such as the timestamp from when
the results were last modified, the dimension of the system, the total number of
measurements (i.e. the length of the strings), and the total number of shots.
Outcomes that were not observed should not be entered.
For instance, the results of flipping two coins 20 times and recording the results might be stored as follows:
import trueq as tq
tq.Results({"10": 5, "00": 2, "01": "10", "11": 3})
Results({'10': 5, '00': 2, '01': '10', '11': 3})
Circuits¶
A Circuit
objects holds three pieces of information:
A Circuit
is intended to be constructed from a list of
Cycle
s and a Key
containing any relevant
information. Results
s can be passed into the constructor, but
would typically be added after the circuit is executed on hardware or a simulator
as in the following example. Furthermore, two adjacent cycles that are marked with
marker=1
will be treated as a subcircuit during recompilation by various compiler
Pass
es.
import trueq as tq
key = tq.Key(foo="bar", fruits=("apples", "oranges"))
circuit = tq.Circuit(cycles=[
tq.Cycle({0: tq.Gate.x, 1: tq.Gate.y, (2, 3): tq.Gate.cnot}),
tq.Cycle({(1, 3): tq.Gate.cz, 4: tq.Gate.x}, marker=1),
tq.Cycle({0: tq.Gate.y, (2, 4): tq.Gate.cx}, marker=1),
tq.Cycle({2: tq.Gate.h, 3: tq.Gate.s, 4: tq.Gate.z}),
tq.Cycle({(0, 4): tq.Gate.cnot, 2: tq.Gate.y}, marker=2),
], key=key).measure_all()
circuit.results = {"01000": 3, "01001": 2, "01010": 1, "01011": 4}
circuit
Circuit



(2, 3):
Gate.cx

(0):
Gate.x

(1):
Gate.y


1

(1, 3):
Gate.cz

(4):
Gate.x


1

(2, 4):
Gate.cx

(0):
Gate.y



(2):
Gate.h

(3):
Gate.s

(4):
Gate.z


2

(0, 4):
Gate.cx

(2):
Gate.y


3

(0):
Meas()

(1):
Meas()

(2):
Meas()

(3):
Meas()

(4):
Meas()
