Cycle

class trueq.Cycle(content=None, immutable=None)

Represents a “clock cycle” of a Circuit; a set of Gates that happen in parallel to a disjoint set of systems. The storage format is a dict that maps tuples of system labels to Gate objects. Any given system can only be addressed once in a Cycle.

This class is iterable, yielding tuples of the form (labels, gate).

import trueq as tq
# Single system operations can be applied to multiple systems at once
cycle = tq.Cycle({(0, 1): tq.Gate.cnot, (2, 3, 4): tq.Gate.t})

for labels, operation in cycle:
    print(f'Labels: {str(labels): <8}\tOperation: {operation}')

Labels: (0, 1)  	Operation: Gate.cx
Labels: (2,)    	Operation: Gate.t
Labels: (3,)    	Operation: Gate.t
Labels: (4,)    	Operation: Gate.t

Cycles can also be labeled as immutable. If a cycle is set to be immutable it is then hashable, which among other properties of hashable objects it means that it may be used as a key in a dictionary. Once a cycle is set to be immutable is cannot be unset. By default if there is an operation in the cycle which acts on more than one system then the cycle is set to be immutable by default. This may be overwritten by manually settings immutable to be False at the time of instantiation.

import trueq as tq
# By default a cycle containing 2 system operations will be immutable
tq.Cycle({(0, 1): tq.Gate.cx, 2: tq.Meas()})
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".
imm
(0, 1): Gate.cx
Name:
  • Gate.cx
Aliases:
  • Gate.cx
  • Gate.cnot
Likeness:
  • CNOT
Generators:
  • 'IX': 90.0
  • 'ZI': 90.0
  • 'ZX': -90.0
Matrix:
  • 1.00 1.00 1.00 1.00
(2): Meas()
Name:
  • Meas()
 
import trueq as tq
# This default may be mantually overwritten
cycle = tq.Cycle({(0, 1): tq.Gate.cx, 2: tq.Meas()}, immutable=False)
print("Cycle immutable: ", cycle.immutable)

cycle.immutable = True
# Trying to set immutable to False after this will raise a RuntimeError
print("Cycle immutable after setting: ", cycle.immutable)

Cycle immutable:  False
Cycle immutable after setting:  True
Parameters

  • content (dict) – A dict whose keys are tuples and whose values are Operations; the method add() is called on each pair.

  • immutable (bool) – If true, the contents of this Cycle cannot be mutated by tools such as randomly_compile().

add(labels, operation)

Adds a Operation to this Cycle. In particular, this can be a Gate, NativeGate, Prep, Block, or Meas.

import trueq as tq
cycle = tq.Cycle()
cycle.add((0, 1), tq.Gate.cnot)
cycle.add((2, 3, 4), tq.Gate.t)
cycle
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".
 
(0, 1): Gate.cx
Name:
  • Gate.cx
Aliases:
  • Gate.cx
  • Gate.cnot
Likeness:
  • CNOT
Generators:
  • 'IX': 90.0
  • 'ZI': 90.0
  • 'ZX': -90.0
Matrix:
  • 1.00 1.00 1.00 1.00
(2): Gate.t
Name:
  • Gate.t
Aliases:
  • Gate.t
Generators:
  • 'Z': 45.0
Matrix:
  • 0.92 -0.38j 0.92 0.38j
(3): Gate.t
Name:
  • Gate.t
Aliases:
  • Gate.t
Generators:
  • 'Z': 45.0
Matrix:
  • 0.92 -0.38j 0.92 0.38j
(4): Gate.t
Name:
  • Gate.t
Aliases:
  • Gate.t
Generators:
  • 'Z': 45.0
Matrix:
  • 0.92 -0.38j 0.92 0.38j

As a convenience, if the operation acts on one qubit (such as single qubit gates, Meas, or Prep), then this operation is added to each label, even when multiple labels are provided.

Parameters

  • labels (int | tuple) – Which systems this gate targets. Note that the order of labels is relevant for multi-system gates. For example, it controls the direction of a CNOT.

  • operation (Operation) – The operation to add to the cycle.

Raises

ValueError – If the Cycle is immutable, if the provided labels contain duplicates or overlap with existing labels, or if the provided gates/labels are incompatible with the Cycle dimensions.

property dim

The dimension of each subsystem, e.g. 2 if this cycle acts on qubits. However, if no gates have been added to this cycle, then the dimension is unknown and this value is equal to None.

import trueq as tq
cycle = tq.Cycle({(0, 1): tq.Gate.cnot, (2, 3, 4): tq.Gate.t})
cycle.dim

2
Type

int | None

property immutable

Whether or not this cycle is immutable.

import trueq as tq
cycle = tq.Cycle({(0, 1): tq.Gate.cnot, (2, 3, 4): tq.Gate.t})
cycle.immutable

True
Type

bool

property labels

The sorted union of all system labels acted on by Operations in this Cycle.

import trueq as tq
cycle = tq.Cycle({(0, 1): tq.Gate.cnot,
                  (2, 3, 4): tq.Gate.t,
                  5: tq.Meas(),
                  6: tq.Prep(),
                  7: tq.Block()})
cycle.labels

(0, 1, 2, 3, 4, 5, 6, 7)
Type

tuple

property n_gates

The number of gates in this Cycle.

import trueq as tq
cycle = tq.Cycle({(0, 1): tq.Gate.cnot,
                  (2, 3, 4): tq.Gate.t,
                  5: tq.Meas(),
                  6: tq.Prep(),
                  7: tq.Block()})
cycle.n_gates

4
Type

int

property n_meas

The number of measurements (Meas) in this Cycle.

import trueq as tq
cycle = tq.Cycle({(0, 1): tq.Gate.cnot,
                  (2, 3, 4): tq.Gate.t,
                  5: tq.Meas(),
                  6: tq.Prep(),
                  7: tq.Block()})
cycle.n_meas

1
Type

int

property n_prep

The number of preparations (Prep) in this Cycle.

import trueq as tq
cycle = tq.Cycle({(0, 1): tq.Gate.cnot,
                  (2, 3, 4): tq.Gate.t,
                  5: tq.Meas(),
                  6: tq.Prep(),
                  7: tq.Block()})
cycle.n_prep

1
Type

int

property n_block

The number of preparations (Prep) in this Cycle.

import trueq as tq
cycle = tq.Cycle({(0, 1): tq.Gate.cnot,
                  (2, 3, 4): tq.Gate.t,
                  5: tq.Meas(),
                  6: tq.Prep(),
                  7: tq.Block()})
cycle.n_block

1
Type

int

property n_operations

The total number of operations in this Cycle, equal to the sum of n_gates, n_meas, and n_prep.

import trueq as tq
cycle = tq.Cycle({(0, 1): tq.Gate.cnot,
                  (2, 3, 4): tq.Gate.t,
                  5: tq.Meas(),
                  6: tq.Prep(),
                  7: tq.Block()})
cycle.n_operations

7
Type

int

property n_sys

The number of distinct systems participating in this Cycle.

import trueq as tq
cycle = tq.Cycle({(0, 1): tq.Gate.cnot,
                  (2, 3, 4): tq.Gate.t,
                  5: tq.Meas(),
                  6: tq.Prep(),
                  7: tq.Block()})
cycle.n_sys

8
Type

int

property gates

The dict of Gates in this Cycle.

import trueq as tq
cycle = tq.Cycle({(0, 1): tq.Gate.cnot,
                  (2, 3, 4): tq.Gate.t,
                  5: tq.Meas(),
                  6: tq.Prep(),
                  7: tq.Block()})
cycle.gates

{(0, 1): Gate.cx, (2,): Gate.t, (3,): Gate.t, (4,): Gate.t}
Type

dict

property gates_single

The single-qubit gates of this cycle; a dict of Gates in this Cycle that act on one subsystem.

import trueq as tq
cycle = tq.Cycle({(0, 1): tq.Gate.cnot,
                  (2, 3, 4): tq.Gate.t,
                  5: tq.Meas(),
                  6: tq.Prep(),
                  7: tq.Block()})
cycle.gates_single

{(2,): Gate.t, (3,): Gate.t, (4,): Gate.t}
Type

dict

property gates_multi

The multi-qubit gates of this cycle; a dict of Gates in this Cycle that act on at least two subsystems.

import trueq as tq
cycle = tq.Cycle({(0, 1): tq.Gate.cnot,
                  (2, 3, 4): tq.Gate.t,
                  5: tq.Meas(),
                  6: tq.Prep(),
                  7: tq.Block()})
cycle.gates_multi

{(0, 1): Gate.cx}
Type

dict

property gate_labels

A sorted tuple of all labels in the cycle that have gates (i.e. labels that point to a Gate operation).

import trueq as tq
cycle = tq.Cycle({(0, 1): tq.Gate.cnot,
                  (2, 3, 4): tq.Gate.t,
                  5: tq.Meas(),
                  6: tq.Prep(),
                  7: tq.Block()})
cycle.gate_labels

(0, 1, 2, 3, 4)
Type

list

property prep

The dict of Preps in this Cycle.

import trueq as tq
cycle = tq.Cycle({(0, 1): tq.Gate.cnot,
                  (2, 3, 4): tq.Gate.t,
                  5: tq.Meas(),
                  6: tq.Prep(),
                  7: tq.Block()})
cycle.prep

{(6,): Prep()}
Type

dict

property prep_labels

A sorted tuple of all labels in the cycle that are a preparation (i.e. labels that point to a Prep operation).

import trueq as tq
cycle = tq.Cycle({(0, 1): tq.Gate.cnot,
                  (2, 3, 4): tq.Gate.t,
                  5: tq.Meas(),
                  6: tq.Prep(),
                  7: tq.Block()})
cycle.prep_labels

(6,)
Type

list

property meas

The dict of Meass in this Cycle.

import trueq as tq
cycle = tq.Cycle({(0, 1): tq.Gate.cnot,
                  (2, 3, 4): tq.Gate.t,
                  5: tq.Meas(),
                  6: tq.Prep(),
                  7: tq.Block()})
cycle.meas

{(5,): Meas()}
Type

dict

property meas_labels

A sorted tuple of all labels in the cycle that are a preparation (i.e. labels that point to a Meas operation).

import trueq as tq
cycle = tq.Cycle({(0, 1): tq.Gate.cnot,
                  (2, 3, 4): tq.Gate.t,
                  5: tq.Meas(),
                  6: tq.Prep(),
                  7: tq.Block()})
cycle.meas_labels

(5,)
Type

list

property block

The dict of Blocks in this Cycle.

import trueq as tq
cycle = tq.Cycle({(0, 1): tq.Gate.cnot,
                  (2, 3, 4): tq.Gate.t,
                  5: tq.Meas(),
                  6: tq.Prep(),
                  7: tq.Block()})
cycle.block

{(7,): Block()}
Type

dict

property block_labels

A sorted tuple of all labels in the cycle that are blocked (i.e. labels that point to a Block operation).

import trueq as tq
cycle = tq.Cycle({(0, 1): tq.Gate.cnot,
                  (2, 3, 4): tq.Gate.t,
                  5: tq.Meas(),
                  6: tq.Prep(),
                  7: tq.Block()})
cycle.block_labels

(7,)
Type

list

property operations

The total dict of Operations in this Cycle.

import trueq as tq
cycle = tq.Cycle({(0, 1): tq.Gate.cnot,
                  (2, 3, 4): tq.Gate.t,
                  5: tq.Meas(),
                  6: tq.Prep(),
                  7: tq.Block()})
cycle.operations

{(0, 1): Gate.cx,
 (2,): Gate.t,
 (3,): Gate.t,
 (4,): Gate.t,
 (6,): Prep(),
 (5,): Meas(),
 (7,): Block()}
Type

dict

tensor(labels=None)

Returns a Tensor representation of the Gates in this Cycle.

The matrix representation (which will be exponentially sized in the number of systems!) of this cycle can be obtained with:

import trueq as tq

cycle = tq.Cycle({(0, 1): tq.Gate.cx, 2: tq.Gate.i})
matrix = cycle.tensor().mat()
tq.visualization.plot_mat(matrix)
../_images/cycle_24_0.png
Parameters

labels (list) – An optional list of labels to force into the tensor in case they are not already present as labels in this cycle.

Return type

Tensor

is_equivalent(other, ignore_imm=True, ignore_id=True)

Checks if this cycle is equivalent to another cycle.

import trueq as tq
cycle1 = tq.Cycle({(0, 1): tq.Gate.cx}, immutable=True)
cycle2 = tq.Cycle({(0, 1): tq.Gate.cx}, immutable=False)
cycle1.is_equivalent(cycle2)

True
Parameters

  • other (Cycle) – Another cycle to compare this one to.

  • ignore_imm (bool) – Whether to return false if this cycle and the other cycle have different values of immutable. Default is True.

  • ignore_id (bool) – Whether to treat all identity gates as though they are not present. Default is True.

Return type

bool

to_dict()

Returns a dictionary representation of a Cycle object. This dictionary representation contains only base Python classes.

import trueq as tq
cycle = tq.Cycle({(0, 1): tq.Gate.cx}, immutable=True)
cycle.to_dict()

{'content': {(0, 1): ('Gate',
   {'u': (((1+0j), 0j, 0j, 0j),
     (0j, (1+0j), 0j, 0j),
     (0j, 0j, 0j, (1+0j)),
     (0j, 0j, (1+0j), 0j))})},
 'immutable': True}
Return type

dict

static from_dict(dic)

Returns a Cycle constructed from a dictionary representation.

import trueq as tq
cycle = tq.Cycle({(0, 1): tq.Gate.cx}, immutable=True)
cycle.from_dict(cycle.to_dict())
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".
imm
(0, 1): Gate.cx
Name:
  • Gate.cx
Aliases:
  • Gate.cx
  • Gate.cnot
Likeness:
  • CNOT
Generators:
  • 'IX': 90.0
  • 'ZI': 90.0
  • 'ZX': -90.0
Matrix:
  • 1.00 1.00 1.00 1.00
Parameters

dic (dict) – A dictionary used to construct a new Cycle.

Return type

Cycle

pop(item)

Deletes the operation from this cycle that acts on the given label tuple and returns it.

import trueq as tq
cycle = tq.Cycle({(0,): tq.Gate.x, (1,): tq.Meas()})
print(cycle.pop(0))
cycle

Gate.x
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".
 
(1): Meas()
Name:
  • Meas()
Parameters

item (tuple) – A tuple of qubit labels.

Returns

The operation that acts on the given label tuple.

Return type

Operation

Raises

  • KeyError – If no operation acts on the given label tuple.

  • ValueError – If the cycle is immutable.