pygsti.extras.idletomography
¶
Idle Tomography Subpackage
Submodules¶
Package Contents¶
Classes¶
A container for idle tomography results: intrinsic and observable errors, 

Class responsible for logging things to stdout or a file. 

A quantum circuit. 

A table of all the intrinsic rates found by idle tomography. 

A table of the largest N (in absolute value) observed error rates. 

A plot showing how an observed error rate is obtained by fitting a sequence 

A table showing the observed error rates relevant for determining a 

A container for idle tomography results: intrinsic and observable errors, 

Labels an elementary error generator on n qubits that includes the state 

A Nqubit state that is the tensor product of N 

A Nqubit pauli operator, consisting of 

A string of 0's and 1's representing a definite outcome in the Zbasis. 
Functions¶

Computes the Jacobian matrix element for a Hamiltonian error: how the 

Computes the "expected" outcome when the stochastic error error 

Computes the Jacobian matrix element for a Stochastic error: how the 

Computes the Jacobian matrix element for a Affine error: how the 

Computes the Jacobian matrix element for a Affine error: how the 

Construct a list of Paulibasis fiducial pairs for idle tomography. 

Infers what the preferred basis signs are based on the length of gatename 

Translate 

Intelligently determine preparation and measurement Pauli basis 

Construct the list of experiments needed to perform idle tomography. 

Construct lists of experiments, one for each maximumlength value, needed 

Extract the observed error rate from a series of experiments which prepares 

Extract the observed error rate from a series of experiments which prepares 

Analyze dataset using the idle tomography protocol to characterize 

Creates an Idle Tomography report, summarizing the results of running 

Lists every "error bit string" that co1uld be caused by an error of weight 

Lists every Pauli error operator for nqubits qubits with weight <= maxweight 

Lists every weight <= maxweight observable whose expectation value can be 

Tiles a set of base fiducial pairs on maxweight qubits to a 
List all nontrivial paulis of given weight wt. 


Set specific or random error terms (typically for a datagenerating model) 

Get error rates on the global idle operation withina 

Get the exact intrinsic rates that would be produced by simulating model 

Get the exact observable rates that would be produced by simulating 
 class pygsti.extras.idletomography._IdleTomographyResults(dataset, max_lengths, max_error_weight, fit_order, pauli_dicts, idle_str, error_list, intrinsic_rates, pauli_fidpairs, observed_rate_infos)¶
Bases:
object
A container for idle tomography results: intrinsic and observable errors, along with supporting information.
 __str__(self)¶
Return str(self).
 class pygsti.extras.idletomography._VerbosityPrinter(verbosity=1, filename=None, comm=None, warnings=True, split=False, clear_file=True)¶
Bases:
object
Class responsible for logging things to stdout or a file.
Controls verbosity and can print progress bars. ex:
>>> VerbosityPrinter(1)
would construct a printer that printed out messages of level one or higher to the screen.
>>> VerbosityPrinter(3, 'output.txt')
would construct a printer that sends verbose output to a text file
The static function
create_printer()
will construct a printer from either an integer or an already existing printer. it is a static method of the VerbosityPrinter class, so it is called like so:>>> VerbosityPrinter.create_printer(2)
or
>>> VerbostityPrinter.create_printer(VerbosityPrinter(3, 'output.txt'))
printer.log('status')
would log ‘status’ if the printers verbosity was one or higher.printer.log('status2', 2)
would log ‘status2’ if the printer’s verbosity was two or higherprinter.error('something terrible happened')
would ALWAYS log ‘something terrible happened’.printer.warning('something worrisome happened')
would log if verbosity was one or higher  the same as a normal status.Both printer.error and printer.warning will prepend ‘ERROR: ‘ or ‘WARNING: ‘ to the message they are given. Optionally, printer.log() can also prepend ‘Status_n’ to the message, where n is the message level.
Logging of progress bars/iterations:
>>> with printer_instance.progress_logging(verbosity): >>> for i, item in enumerate(data): >>> printer.show_progress(i, len(data)) >>> printer.log(...)
will output either a progress bar or iteration statuses depending on the printer’s verbosity
 Parameters
verbosity (int) – How verbose the printer should be.
filename (str, optional) – Where to put output (If none, output goes to screen)
comm (mpi4py.MPI.Comm or ResourceAllocation, optional) – Restricts output if the program is running in parallel (By default, if the rank is 0, output is sent to screen, and otherwise sent to commfiles 1, 2, …
warnings (bool, optional) – Whether or not to print warnings
split (bool, optional) – Whether to split output between stdout and stderr as appropriate, or to combine the streams so everything is sent to stdout.
clear_file (bool, optional) – Whether or not filename should be cleared (overwritten) or simply appended to.
 _comm_path¶
relative path where comm files (outputs of nonroot ranks) are stored.
 Type
str
 _comm_file_name¶
root filename for comm files (outputs of nonroot ranks).
 Type
str
 _comm_file_ext¶
filename extension for comm files (outputs of nonroot ranks).
 Type
str
 _comm_path =¶
 _comm_file_name =¶
 _comm_file_ext = .txt¶
 _create_file(self, filename)¶
 _get_comm_file(self, comm_id)¶
 clone(self)¶
Instead of deepcopy, initialize a new printer object and feed it some select deepcopied members
 Returns
VerbosityPrinter
 static create_printer(verbosity, comm=None)¶
Function for converting between interfaces
 Parameters
verbosity (int or VerbosityPrinter object, required:) – object to build a printer from
comm (mpi4py.MPI.Comm object, optional) – Comm object to build printers with. !Will override!
 Returns
VerbosityPrinter – The printer object, constructed from either an integer or another printer
 __add__(self, other)¶
Increase the verbosity of a VerbosityPrinter
 __sub__(self, other)¶
Decrease the verbosity of a VerbosityPrinter
 __getstate__(self)¶
 __setstate__(self, state_dict)¶
 _append_to(self, filename, message)¶
 _put(self, message, flush=True, stderr=False)¶
 _record(self, typ, level, message)¶
 error(self, message)¶
Log an error to the screen/file
 Parameters
message (str) – the error message
 Returns
None
 warning(self, message)¶
Log a warning to the screen/file if verbosity > 1
 Parameters
message (str) – the warning message
 Returns
None
 log(self, message, message_level=None, indent_char=' ', show_statustype=False, do_indent=True, indent_offset=0, end='\n', flush=True)¶
Log a status message to screen/file.
Determines whether the message should be printed based on current verbosity setting, then sends the message to the appropriate output
 Parameters
message (str) – the message to print (or log)
message_level (int, optional) – the minimum verbosity level at which this level is printed.
indent_char (str, optional) – what constitutes an “indent” (messages at higher levels are indented more when do_indent=True).
show_statustype (bool, optional) – if True, prepend lines with “Status Level X” indicating the message_level.
do_indent (bool, optional) – whether messages at higher message levels should be indented. Note that if this is False it may be helpful to set show_statustype=True.
indent_offset (int, optional) – an additional number of indentations to add, on top of any due to the message level.
end (str, optional) – the character (or string) to end message lines with.
flush (bool, optional) – whether stdout should be flushed right after this message is printed (this avoids delays in onscreen output due to buffering).
 Returns
None
 _progress_bar(self, iteration, total, bar_length, num_decimals, fill_char, empty_char, prefix, suffix, indent)¶
 _verbose_iteration(self, iteration, total, prefix, suffix, verbose_messages, indent, end)¶
 __str__(self)¶
Return str(self).
 verbosity_env(self, level)¶
Create a temporary environment with a different verbosity level.
This is context manager, controlled using Python’s with statement:
>>> with printer.verbosity_env(2): printer.log('Message1') # printed at verbosity level 2 printer.log('Message2') # printed at verbosity level 2
 Parameters
level (int) – the verbosity level of the environment.
 progress_logging(self, message_level=1)¶
Context manager for logging progress bars/iterations.
(The printer will return to its normal, unrestricted state when the progress logging has finished)
 Parameters
message_level (int, optional) – progress messages will not be shown until the verbosity level reaches message_level.
 show_progress(self, iteration, total, bar_length=50, num_decimals=2, fill_char='#', empty_char='', prefix='Progress:', suffix='', verbose_messages=[], indent_char=' ', end='\n')¶
Displays a progress message (to be used within a progress_logging block).
 Parameters
iteration (int) – the 0based current iteration – the interation number this message is for.
total (int) – the total number of iterations expected.
bar_length (int, optional) – the length, in characters, of a textformat progress bar (only used when the verbosity level is exactly equal to the progress_logging message level.
num_decimals (int, optional) – number of places after the decimal point that are displayed in progress bar’s percentage complete.
fill_char (str, optional) – replaces ‘#’ as the barfilling character
empty_char (str, optional) – replaces ‘’ as the emptybar character
prefix (str, optional) – message in front of the bar
suffix (str, optional) – message after the bar
verbose_messages (list, optional) – A list of strings to display after an initial “Iter X of Y” line when the verbosity level is higher than the progress_logging message level and so more verbose messages are shown (and a progress bar is not). The elements of verbose_messages will occur, one per line, after the initial “Iter X of Y” line.
indent_char (str, optional) – what constitutes an “indentation”.
end (str, optional) – the character (or string) to end message lines with.
 Returns
None
 _end_progress(self)¶
 start_recording(self)¶
Begins recording the output (to memory).
Begins recording (in memory) a list of (type, verbosityLevel, message) tuples that is returned by the next call to :method:`stop_recording`.
 Returns
None
 is_recording(self)¶
Returns whether this VerbosityPrinter is currently recording.
 Returns
bool
 stop_recording(self)¶
Stops recording and returns recorded output.
Stops a “recording” started by :method:`start_recording` and returns the list of (type, verbosityLevel, message) tuples that have been recorded since then.
 Returns
list
 class pygsti.extras.idletomography._Circuit(layer_labels=(), line_labels='auto', num_lines=None, editable=False, stringrep=None, name='', check=True, expand_subcircuits='default', occurrence=None, compilable_layer_indices=None)¶
Bases:
object
A quantum circuit.
A Circuit represents a quantum circuit, consisting of state preparation, gates, and measurement operations. It is composed of some number of “lines”, typically one per qubit, and stores the operations on these lines as a sequence of
Label
objects, one per circuit layer, whose .sslbls members indicate which line(s) the label belongs on. When a circuit is created with ‘editable=True’, a rich set of operations may be used to construct the circuit in place, after which done_editing() should be called so that the Circuit can be properly hashed as needed. Parameters
layer_labels (iterable of Labels or str) –
This argument provides a list of the layer labels specifying the state preparations, gates, and measurements for the circuit. This argument can also be a
Circuit
or a string, in which case it is parsed as a textformatted circuit. Internally this will eventually be converted to a list of Label objects, one per layer, but it may be specified using anything that can be readily converted to a Label objects. For example, any of the following are allowed:[‘Gx’,’Gx’] : X gate on each of 2 layers
`[Label(‘Gx’),Label(‘Gx’)] : same as above
[(‘Gx’,0),(‘Gy’,0)] : X then Y on qubit 0 (2 layers)
[[(‘Gx’,0),(‘Gx’,1)],[(‘Gy’,0),(‘Gy’,1)]] : parallel X then Y on qubits 0 & 1
line_labels (iterable, optional) – The (string valued) label for each circuit line. If ‘auto’, then line_labels is taken to be the list of all statespace labels present within layer_labels. If there are no such labels (e.g. if layer_labels contains just gate names like (‘Gx’,’Gy’)), then the special value ‘*’ is used as a single line label.
num_lines (int, optional) – Specify this instead of line_labels to set the latter to the integers between 0 and num_lines1.
editable (bool, optional) – Whether the created Circuit is created in able to be modified. If True, then you should call done_editing() once the circuit is completely assembled, as this makes the circuit readonly and allows it to be hashed.
stringrep (string, optional) – A string representation for the circuit. If None (the default), then this will be generated automatically when needed. One reason you’d want to specify this is if you know of a nice compact string representation that you’d rather use, e.g. “Gx^4” instead of the automatically generated “GxGxGxGx”. If you want to initialize a Circuit entirely from a string representation you can either specify the string in as layer_labels or set layer_labels to None and stringrep to any valid (oneline) circuit string.
name (str, optional) – A name for this circuit (useful if/when used as a block within larger circuits).
check (bool, optional) – Whether stringrep should be checked against layer_labels to ensure they are consistent, and whether the labels in layer_labels are a subset of line_labels. The only reason you’d want to set this to False is if you’re absolutely sure stringrep and line_labels are consistent and want to save computation time.
expand_subcircuits (bool or "default") – If “default”, then the value of Circuit.default_expand_subcircuits is used. If True, then any subcircuits (e.g. anything exponentiated like “(GxGy)^4”) will be expanded when it is stored within the created Circuit. If False, then such subcircuits will be left asis. It’s typically more robust to expand subcircuits as this facilitates comparison (e.g. so “GxGx” == “Gx^2”), but in cases when you have massive exponents (e.g. “Gx^8192”) it may improve performance to set expand_subcircuits=False.
occurrence (hashable, optional) – A value to set as the “occurrence id” for this circuit. This value doesn’t affect the circuit an any way except by affecting it’s hashing and equivalence testing. Circuits with different occurrence ids are not equivalent. Occurrence values effectively allow multiple copies of the same ciruit to be stored in a dictionary or
DataSet
.compilable_layer_indices (tuple, optional) – The circuitlayer indices that may be internally altered (but retaining the same target operation) and/or combined with the following circuit layer by a hardware compiler.when executing this circuit. Layers that are not “compilable” are effectively followed by a barrier which prevents the hardward compiler from restructuring the circuit across the layer boundary.
 default_expand_subcircuits¶
By default, expand subcircuit labels.
 Type
bool
 line_labels¶
The line labels (often qubit labels) of this circuit.
 Type
tuple
 layertup¶
This Circuit’s layers as a standard Python tuple of layer Labels.
 Type
tuple
 tup¶
This Circuit as a standard Python tuple of layer Labels and line labels.
 Type
tuple
 str¶
The Python string representation of this Circuit.
 Type
str
 default_expand_subcircuits = True¶
 classmethod cast(cls, obj)¶
Convert obj into a
Circuit
. Parameters
obj (object) – Object to convert
 Returns
Circuit
 classmethod from_tuple(cls, tup)¶
Creates a
Circuit
from a tuple Parameters
tup (tuple) – The tuple to convert.
 Returns
Circuit
 classmethod _fastinit(cls, labels, line_labels, editable, name='', stringrep=None, occurrence=None, compilable_layer_indices=None)¶
 _bare_init(self, labels, line_labels, editable, name='', stringrep=None, occurrence=None, compilable_layer_indices=None)¶
 to_label(self, nreps=1)¶
Construct and return this entire circuit as a
CircuitLabel
.Note: occurrenceid information is not stored in a circuit label, so circuits that differ only in their occurence_id will return circuit labels that are equal.
 Parameters
nreps (int, optional) – The number of times this circuit will be repeated (CircuitLabels support exponentiation and you can specify this here).
 Returns
CircuitLabel
 property line_labels(self)¶
The line labels (often qubit labels) of this circuit.
 property name(self)¶
The name of this circuit.
Note: the name is not a part of the hashed value. The name is used to name the
CircuitLabel
returned from :method:`to_label`.
 property occurrence(self)¶
The occurrence id of this circuit.
 property layertup(self)¶
This Circuit’s layers as a standard Python tuple of layer Labels.
 Returns
tuple
 property tup(self)¶
This Circuit as a standard Python tuple of layer Labels and line labels.
 Returns
tuple
 property compilable_layer_indices(self)¶
Tuple of the layer indices corresponding to “compilable” layers.
 property compilable_by_layer(self)¶
Boolean array indicating whether each layer is “compilable” or not.
 property str(self)¶
The Python string representation of this Circuit.
 Returns
str
 property layerstr(self)¶
Just the string representation of the circuit layers (no ‘@<line_labels>’ suffix)
 property linesstr(self)¶
Just the string representation of the circuit’s line labels (the ‘@<line_labels>’ suffix)
 _labels_lines_str(self)¶
Split the string representation up into layerlabels & linelabels parts
 __hash__(self)¶
Return hash(self).
 __len__(self)¶
 __iter__(self)¶
 __contains__(self, x)¶
Note: this is not covered by __iter__ for case of contained CircuitLabels
 __radd__(self, x)¶
 __add__(self, x)¶
 repeat(self, ntimes, expand='default')¶
Repeat this circuit ntimes times.
 Parameters
ntimes (int) – Number of repetitions.
expand (bool or "default", optional) – When False, the returned circuit will contain a
CircuitLabel
encapsulating the repetitions without explicitly storing them. When True, the returned circuit will be expanded into the ntimes repetitions. “default” means to use the value in the class variable Circuit.default_expand_subcircuits.
 __mul__(self, x)¶
 __pow__(self, x)¶
 __eq__(self, x)¶
Return self==value.
 __lt__(self, x)¶
Return self<value.
 __gt__(self, x)¶
Return self>value.
 property num_lines(self)¶
The number of lines in this circuit.
 Returns
int
 copy(self, editable='auto')¶
Returns a copy of the circuit.
 Parameters
editable ({True,False,"auto"}) – Whether returned copy is editable. If “auto” is given, then the copy is editable if and only if this Circuit is.
 Returns
Circuit
 clear(self)¶
Removes all the gates in a circuit (preserving the number of lines).
 Returns
None
 _proc_layers_arg(self, layers)¶
Preprocess the layers argument used by many methods
 _proc_lines_arg(self, lines)¶
Preprocess the lines argument used by many methods
 _proc_key_arg(self, key)¶
Preprocess the key argument used by many methods
 _layer_components(self, ilayer)¶
Get the components of the ilayerth layer as a list/tuple.
 _remove_layer_component(self, ilayer, indx)¶
Removes the indxth component from the ilayerth layer
 _append_layer_component(self, ilayer, val)¶
Add val to the ilayerth layer
 _replace_layer_component(self, ilayer, indx, val)¶
 extract_labels(self, layers=None, lines=None, strict=True)¶
Get a subregion  a “rectangle”  of this Circuit.
This can be used to select multiple layers and/or lines of this Circuit. The strict argument controls whether gates need to be entirely within the given rectangle or can be intersecting it. If layers is a single integer then a
Label
is returned (representing a layer or a part of a layer), otherwise aCircuit
is returned. Parameters
layers (int, slice, or list/tuple of ints) – Which layers to select (the horizontal dimension of the selection rectangle). Layers are always selected by index, and this argument can be a single (integer) index  in which case a Label is returned  or multiple indices as given by a slice or list  in which case a Circuit is returned. Note that, even though we speak of a “rectangle”, layer indices do not need to be contiguous. The special value None selects all layers.
lines (str/int, slice, or list/tuple of strs/ints) – Which lines to select (the vertical dimension of the selection rectangle). Lines are selected by their linelabels (elements of the circuit’s .line_labels property), which can be strings and/or integers. A single or multiple linelabels can be specified. If the line labels are integers a slice can be used, otherwise a list or tuple of labels is the only way to select multiple of them. Note that linelabels do not need to be contiguous. The special value None selects all lines.
strict (bool, optional) – When True, only gates lying completely within the selected region are included in the return value. If a gate straddles the region boundary (e.g. if we select just line 1 and the circuit contains “Gcnot:1:2”) then it is silently notincluded in the returned label or circuit. If False, then gates which straddle the region boundary are included. Note that this may result in a Label or Circuit containing more line labels than where requested in the call to extract_labels(…)..
 Returns
Label or Circuit – The requested portion of this circuit, given as a Label if layers is a single integer and as a Circuit otherwise. Note: if you want a Circuit when only selecting one layer, set layers to a slice or tuple containing just a single index.
 set_labels(self, lbls, layers=None, lines=None)¶
Write lbls to the block defined by the layers and lines arguments.
Note that lbls can be anything interpretable as a
Label
or list of labels. Parameters
lbls (Label, list/tuple of Labels, or Circuit) – When layers is a single integer, lbls should be a single “layer label” of type Label. Otherwise, lbls should be a list or tuple of Label objects with length equal to the number of layers being set. A Circuit may also be used in this case.
layers (int, slice, or list/tuple of ints) – Which layers to set (the horizontal dimension of the destination rectangle). Layers are always selected by index, and this argument can be a single (integer) index or multiple indices as given by a slice or list. Note that these indices do not need to be contiguous. The special value None stands for all layers.
lines (str/int, slice, or list/tuple of strs/ints) – Which lines to set (the vertical dimension of the destination rectangle). Lines are selected by their linelabels, which can be strings and/or integers. A single or multiple linelabels can be specified. If the line labels are integers a slice can be used, otherwise a list or tuple of labels is the only way to specify multiple of them. The linelabels do not need to be contiguous. The special value None stands for all lines, and in this case new lines will be created if there are new statespace labels in lbls (when lines is not None an error is raised instead).
 Returns
None
 insert_idling_layers(self, insert_before, num_to_insert, lines=None)¶
Inserts into this circuit one or more idling (blank) layers.
By default, complete layer(s) are inserted. The lines argument allows you to insert partial layers (on only a subset of the lines).
 Parameters
insert_before (int) – The layer index to insert the new layers before. Can be from 0 (insert at the beginning) to len(self)1 (insert at end), and negative indexing can be used to insert relative to the last layer. The special value None inserts at the end.
num_to_insert (int) – The number of new layers to insert.
lines (str/int, slice, or list/tuple of strs/ints, optional) – Which lines should have new layers (blank circuit space) inserted into them. A single or multiple linelabels can be specified, similarly as in :method:`extract_labels`. The default value None stands for all lines.
 Returns
Circuit
 insert_idling_layers_inplace(self, insert_before, num_to_insert, lines=None)¶
Inserts into this circuit one or more idling (blank) layers.
By default, complete layer(s) are inserted. The lines argument allows you to insert partial layers (on only a subset of the lines).
 Parameters
insert_before (int) – The layer index to insert the new layers before. Can be from 0 (insert at the beginning) to len(self)1 (insert at end), and negative indexing can be used to insert relative to the last layer. The special value None inserts at the end.
num_to_insert (int) – The number of new layers to insert.
lines (str/int, slice, or list/tuple of strs/ints, optional) – Which lines should have new layers (blank circuit space) inserted into them. A single or multiple linelabels can be specified, similarly as in :method:`extract_labels`. The default value None stands for all lines.
 Returns
None
 _append_idling_layers_inplace(self, num_to_insert, lines=None)¶
Adds one or more idling (blank) layers to the end of this circuit.
By default, complete layer(s) are appended. The lines argument allows you to add partial layers (on only a subset of the lines).
 Parameters
num_to_insert (int) – The number of new layers to append.
lines (str/int, slice, or list/tuple of strs/ints, optional) – Which lines should have new layers (blank circuit space) inserted into them. A single or multiple linelabels can be specified, similarly as in :method:`extract_labels`. The default value None stands for all lines.
 Returns
None
 insert_labels_into_layers(self, lbls, layer_to_insert_before, lines=None)¶
Inserts into this circuit the contents of lbls into new full or partial layers.
By default, complete layer(s) are inserted. The lines argument allows you to insert partial layers (on only a subset of the lines).
 Parameters
lbls (list/tuple of Labels, or Circuit) – The full or partial layer labels to insert. The length of this list, tuple, or circuit determines the number of layers which are inserted.
layer_to_insert_before (int) – The layer index to insert lbls before. Can be from 0 (insert at the beginning) to len(self)1 (insert at end), and negative indexing can be used to insert relative to the last layer. The special value None inserts at the end.
lines (str/int, slice, or list/tuple of strs/ints, optional) – Which lines should have lbls inserted into them. Currently this can only be a larger set than the set of line labels present in lbls (in future versions this may allow filtering of lbls). value None stands for all lines.
 Returns
Circuit
 insert_labels_into_layers_inplace(self, lbls, layer_to_insert_before, lines=None)¶
Inserts into this circuit the contents of lbls into new full or partial layers.
By default, complete layer(s) are inserted. The lines argument allows you to insert partial layers (on only a subset of the lines).
 Parameters
lbls (list/tuple of Labels, or Circuit) – The full or partial layer labels to insert. The length of this list, tuple, or circuit determines the number of layers which are inserted.
layer_to_insert_before (int) – The layer index to insert lbls before. Can be from 0 (insert at the beginning) to len(self)1 (insert at end), and negative indexing can be used to insert relative to the last layer. The special value None inserts at the end.
lines (str/int, slice, or list/tuple of strs/ints, optional) – Which lines should have lbls inserted into them. Currently this can only be a larger set than the set of line labels present in lbls (in future versions this may allow filtering of lbls). value None stands for all lines.
 Returns
None
 insert_idling_lines(self, insert_before, line_labels)¶
Insert one or more idling (blank) lines into this circuit.
 Parameters
insert_before (str or int) – The line label to insert new lines before. The special value None inserts lines at the bottom of this circuit.
line_labels (list or tuple) – A list or tuple of the new line labels to insert (can be integers and/or strings).
 Returns
Circuit
 insert_idling_lines_inplace(self, insert_before, line_labels)¶
Insert one or more idling (blank) lines into this circuit.
 Parameters
insert_before (str or int) – The line label to insert new lines before. The special value None inserts lines at the bottom of this circuit.
line_labels (list or tuple) – A list or tuple of the new line labels to insert (can be integers and/or strings).
 Returns
None
 _append_idling_lines(self, line_labels)¶
Add one or more idling (blank) lines onto the bottom of this circuit.
 Parameters
line_labels (list or tuple) – A list or tuple of the new line labels to insert (can be integers and/or strings).
 Returns
None
 insert_labels_as_lines_inplace(self, lbls, layer_to_insert_before=None, line_to_insert_before=None, line_labels='auto')¶
Inserts into this circuit the contents of lbls into new lines.
By default, lbls is inserted at the beginning of the new lines(s). The layer_to_insert_before argument allows you to insert lbls beginning at a layer of your choice.
 Parameters
lbls (list/tuple of Labels, or Circuit) – A list of layer labels to insert as new lines. The statespace (line) labels within lbls must not overlap with that of this circuit or an error is raised. If lbls contains more layers than this circuit currently has, new layers are added automatically.
layer_to_insert_before (int) – The layer index to insert lbls before. Can be from 0 (insert at the beginning) to len(self)1 (insert at end), and negative indexing can be used to insert relative to the last layer. The default value of None inserts at the beginning.
line_to_insert_before (str or int) – The line label to insert the new lines before. The default value of None inserts lines at the bottom of the circuit.
line_labels (list, tuple, or "auto") – The labels of the new lines being inserted. If “auto”, then these are inferred from lbls.
 Returns
None
 insert_labels_as_lines(self, lbls, layer_to_insert_before=None, line_to_insert_before=None, line_labels='auto')¶
Inserts into this circuit the contents of lbls into new lines.
By default, lbls is inserted at the beginning of the new lines(s). The layer_to_insert_before argument allows you to insert lbls beginning at a layer of your choice.
 Parameters
lbls (list/tuple of Labels, or Circuit) – A list of layer labels to insert as new lines. The statespace (line) labels within lbls must not overlap with that of this circuit or an error is raised. If lbls contains more layers than this circuit currently has, new layers are added automatically.
layer_to_insert_before (int) – The layer index to insert lbls before. Can be from 0 (insert at the beginning) to len(self)1 (insert at end), and negative indexing can be used to insert relative to the last layer. The default value of None inserts at the beginning.
line_to_insert_before (str or int) – The line label to insert the new lines before. The default value of None inserts lines at the bottom of the circuit.
line_labels (list, tuple, or "auto") – The labels of the new lines being inserted. If “auto”, then these are inferred from lbls.
 Returns
None
 _append_labels_as_lines(self, lbls, layer_to_insert_before=None, line_labels='auto')¶
Adds the contents of lbls as new lines at the bottom of this circuit.
By default, lbls is inserted at the beginning of the new lines(s). The layer_to_insert_before argument allows you to insert lbls beginning at a layer of your choice.
 Parameters
lbls (list/tuple of Labels, or Circuit) – A list of layer labels to append as new lines. The statespace (line) labels within lbls must not overlap with that of this circuit or an error is raised. If lbls contains more layers than this circuit currently has, new layers are added automatically.
layer_to_insert_before (int) – The layer index to insert lbls before. Can be from 0 (insert at the beginning) to len(self)1 (insert at end), and negative indexing can be used to insert relative to the last layer. The default value of None inserts at the beginning.
line_labels (list, tuple, or "auto") – The labels of the new lines being added. If “auto”, then these are inferred from lbls.
 Returns
None
 _clear_labels(self, layers, lines, clear_straddlers=False)¶
remove all labels in a block given by layers and lines Note: layers & lines must be lists/tuples of values; they can’t be slices or single vals
 clear_labels(self, layers=None, lines=None, clear_straddlers=False)¶
Removes all the gates within the given circuit region. Does not reduce the number of layers or lines.
 Parameters
layers (int, slice, or list/tuple of ints) – Defines the horizontal dimension of the region to clear. See :method:`extract_labels` for details.
lines (str/int, slice, or list/tuple of strs/ints) – Defines the vertical dimension of the region to clear. See :method:`extract_labels` for details.
clear_straddlers (bool, optional) – Whether or not gates which straddle cleared and noncleared lines should be cleared. If False and straddling gates exist, an error will be raised.
 Returns
None
 delete_layers(self, layers=None)¶
Deletes one or more layers from the circuit.
 Parameters
layers (int, slice, or list/tuple of ints) – The layer index or indices to delete. See :method:`extract_labels` for details.
 Returns
None
 delete_lines(self, lines, delete_straddlers=False)¶
Deletes one or more lines from the circuit.
 Parameters
lines (str/int, slice, or list/tuple of strs/ints) – The line label(s) to delete. See :method:`extract_labels` for details.
delete_straddlers (bool, optional) – Whether or not gates which straddle deleted and nondeleted lines should be removed. If False and straddling gates exist, an error will be raised.
 Returns
None
 __getitem__(self, key)¶
 __setitem__(self, key, val)¶
 __delitem__(self, key)¶
 to_pythonstr(self, op_labels)¶
Convert this circuit to an “encoded” python string.
In the returned string each operation label is represented as a single character, starting with ‘A’ and continuing down the alphabet. This can be useful for processing operation sequences using python’s string tools (regex in particular).
 Parameters
op_labels (tuple) – An iterable containing at least all the layerLabels that appear in this Circuit, and which will be mapped to alphabet characters, beginning with ‘A’.
 Returns
string – The converted operation sequence.
Examples
(‘Gx’,’Gx’,’Gy’,’Gx’) => “AABA”
 classmethod from_pythonstr(cls, python_string, op_labels)¶
Decode an “encoded string” into a
Circuit
.Create a Circuit from a python string where each operation label is represented as a single character, starting with ‘A’ and continuing down the alphabet. This performs the inverse of :method:`to_pythonstr`.
 Parameters
python_string (string) – string whose individual characters correspond to the operation labels of a operation sequence.
op_labels (tuple) – tuple containing all the operation labels that will be mapped from alphabet characters, beginning with ‘A’.
 Returns
Circuit
Examples
“AABA” => (‘Gx’,’Gx’,’Gy’,’Gx’)
 serialize(self)¶
Serialize the parallel gate operations of this Circuit.
Construct a new Circuit whereby all layers containing multiple gates are converted to separate singlegate layers, effectively putting each elementary gate operation into its own layer. Ordering is dictated by the ordering of the compound layer labels.
 Returns
Circuit
 parallelize(self, can_break_labels=True, adjacent_only=False)¶
Compress a circuit’s gates by performing them in parallel.
Construct a circuit with the same underlying labels as this one, but with as many gates performed in parallel as possible (with some restrictions  see the Parameters section below). Generally, gates are moved as far left (toward the start) of the circuit as possible.
 Parameters
can_break_labels (bool, optional) – Whether compound (parallelgate) labels in this Circuit can be separated during the parallelization process. For example, if can_break_labels=True then “Gx:0[Gy:0Gy:1]” => “[Gx:0Gy:1]Gy:0” whereas if can_break_labels=False the result would remain “Gx:0[Gy:0Gy:1]” because [Gy:0Gy:1] cannot be separated.
adjacent_only (bool, optional) – It True, then operation labels are only allowed to move into an adjacent label, that is, they cannot move “through” other operation labels. For example, if adjacent_only=True then “Gx:0Gy:0Gy:1” => “Gx:0[Gy:0Gy:1]” whereas if adjacent_only=False the result would be “[Gx:0Gy:1]Gy:0. Setting this to True is sometimes useful if you want to parallelize a serial string in such a way that subsequently calling .serialize() will give you back the original string.
 Returns
Circuit
 expand_subcircuits_inplace(self)¶
Expands all
CircuitLabel
labels within this circuit.This operation is done in place and so can only be performed on an editable
Circuit
. Returns
None
 expand_subcircuits(self)¶
Returns a new circuit with
CircuitLabel
labels expanded. Returns
Circuit
 factorize_repetitions_inplace(self)¶
Attempt to replace repeated subcircuits with
CircuitLabel
objects.More or less the reverse of :method:`expand_subcircuits`, this method attempts to collapse repetitions of the same labels into single
CircuitLabel
labels within this circuit.This operation is done in place and so can only be performed on an editable
Circuit
. Returns
None
 insert_layer(self, circuit_layer, j)¶
Inserts a single layer into a circuit.
The input layer does not need to contain a gate that acts on every qubit, but it should not contain more than one gate on a qubit.
 Parameters
circuit_layer (Label) – The layer to insert. A (possibly compound) Label object or something that can be converted into one, e.g. ((‘Gx’,0),(‘Gcnot’,1,2)) or just ‘Gx’.
j (int) – The layer index (depth) at which to insert the circuit_layer.
 Returns
Circuit
 insert_layer_inplace(self, circuit_layer, j)¶
Inserts a single layer into a circuit.
The input layer does not need to contain a gate that acts on every qubit, but it should not contain more than one gate on a qubit.
 Parameters
circuit_layer (Label) – The layer to insert. A (possibly compound) Label object or something that can be converted into one, e.g. ((‘Gx’,0),(‘Gcnot’,1,2)) or just ‘Gx’.
j (int) – The layer index (depth) at which to insert the circuit_layer.
 Returns
None
 insert_circuit(self, circuit, j)¶
Inserts a circuit into this circuit.
The circuit to insert can be over more qubits than this circuit, as long as all qubits that are not part of this circuit are idling. In this case, the idling qubits are all discarded. The circuit to insert can also be on less qubits than this circuit: all other qubits are set to idling. So, the labels of the circuit to insert for all nonidling qubits must be a subset of the labels of this circuit.
 Parameters
circuit (Circuit) – The circuit to be inserted.
j (int) – The layer index (depth) at which to insert the circuit.
 Returns
Circuit
 insert_circuit_inplace(self, circuit, j)¶
Inserts a circuit into this circuit.
The circuit to insert can be over more qubits than this circuit, as long as all qubits that are not part of this circuit are idling. In this case, the idling qubits are all discarded. The circuit to insert can also be on less qubits than this circuit: all other qubits are set to idling. So, the labels of the circuit to insert for all nonidling qubits must be a subset of the labels of this circuit.
 Parameters
circuit (Circuit) – The circuit to be inserted.
j (int) – The layer index (depth) at which to insert the circuit.
 Returns
None
 append_circuit(self, circuit)¶
Append a circuit to the end of this circuit.
This circuit must satisfy the requirements of :method:`insert_circuit()`. See that method for more details.
 Parameters
circuit (A Circuit object) – The circuit to be appended.
 Returns
Circuit
 append_circuit_inplace(self, circuit)¶
Append a circuit to the end of this circuit.
This circuit must satisfy the requirements of :method:`insert_circuit()`. See that method for more details.
 Parameters
circuit (A Circuit object) – The circuit to be appended.
 Returns
None
 prefix_circuit(self, circuit)¶
Prefix a circuit to the beginning of this circuit.
This circuit must satisfy the requirements of the :method:`insert_circuit()`. See that method for more details.
 Parameters
circuit (A Circuit object) – The circuit to be prefixed.
 Returns
Circuit
 prefix_circuit_inplace(self, circuit)¶
Prefix a circuit to the beginning of this circuit.
This circuit must satisfy the requirements of the :method:`insert_circuit()`. See that method for more details.
 Parameters
circuit (A Circuit object) – The circuit to be prefixed.
 Returns
None
 tensor_circuit_inplace(self, circuit, line_order=None)¶
The tensor product of this circuit and circuit.
That is, it adds circuit to this circuit as new lines. The line labels of circuit must be disjoint from the line labels of this circuit, as otherwise applying the circuits in parallel does not make sense.
 Parameters
circuit (A Circuit object) – The circuit to be tensored.
line_order (List, optional) – A list of all the line labels specifying the order of the circuit in the updated circuit. If None, the lines of circuit are added below the lines of this circuit. Note that, for many purposes, the ordering of lines of the circuit is irrelevant.
 Returns
None
 tensor_circuit(self, circuit, line_order=None)¶
The tensor product of this circuit and circuit.
That is, it adds circuit to this circuit as new lines. The line labels of circuit must be disjoint from the line labels of this circuit, as otherwise applying the circuits in parallel does not make sense.
 Parameters
circuit (A Circuit object) – The circuit to be tensored.
line_order (List, optional) – A list of all the line labels specifying the order of the circuit in the updated circuit. If None, the lines of circuit are added below the lines of this circuit. Note that, for many purposes, the ordering of lines of the circuit is irrelevant.
 Returns
Circuit
 replace_layer_with_circuit_inplace(self, circuit, j)¶
Replaces the jth layer of this circuit with circuit.
 Parameters
circuit (Circuit) – The circuit to insert
j (int) – The layer index to replace.
 Returns
None
 replace_layer_with_circuit(self, circuit, j)¶
Replaces the jth layer of this circuit with circuit.
 Parameters
circuit (Circuit) – The circuit to insert
j (int) – The layer index to replace.
 Returns
Circuit
 replace_gatename_inplace(self, old_gatename, new_gatename)¶
Changes the name of a gate throughout this Circuit.
Note that the name is only a part of the label identifying each gate, and doesn’t include the lines (qubits) a gate acts upon. For example, the “Gx:0” and “Gx:1” labels both have the same name but act on different qubits.
 Parameters
old_gatename (str) – The gate name to replace.
new_gatename (str) – The name to replace old_gatename with.
 Returns
None
 replace_gatename(self, old_gatename, new_gatename)¶
Returns a copy of this Circuit except that old_gatename is changed to new_gatename.
Note that the “name” is only a part of the “label” identifying each gate, and doesn’t include the lines (qubits) a gate acts upon. For example, the “Gx:0” and “Gx:1” labels both have the same name but act on different qubits.
 Parameters
old_gatename (str) – The gate name to replace.
new_gatename (str) – The name to replace old_gatename with.
 Returns
Circuit
 replace_gatename_with_idle_inplace(self, gatename)¶
Treats a given gatename as an idle gate throughout this Circuit.
This effectively removes this gate name from the circuit, and replaces a layer containing only this gate name with an idle layer.
 Parameters
gatename (str) – The gate name to replace.
 Returns
None
 replace_gatename_with_idle(self, gatename)¶
Returns a copy of this Circuit with a given gatename treated as an idle gate.
This effectively removes this gate name from the circuit, and replaces a layer containing only this gate name with an idle layer.
 Parameters
gatename (str) – The gate name to replace.
 Returns
Circuit
 replace_layer(self, old_layer, new_layer)¶
Returns a copy of this Circuit except that old_layer is changed to new_layer.
 replace_layers_with_aliases(self, alias_dict)¶
Performs a find and replace using layer aliases.
Returns a copy of this Circuit except that it’s layers that match keys of alias_dict are replaced with the corresponding values.
 Parameters
alias_dict (dict) – A dictionary whose keys are layer Labels (or equivalent tuples or strings), and whose values are Circuits.
 Returns
Circuit
 change_gate_library(self, compilation, allowed_filter=None, allow_unchanged_gates=False, depth_compression=True, one_q_gate_relations=None)¶
Reexpress a circuit over a different model.
 Parameters
compilation (dict or CompilationLibrary.) –
If a dictionary, the keys are some or all of the gates that appear in the circuit, and the values are replacement circuits that are normally compilations for each of these gates (if they are not, the action of the circuit will be changed). The circuits need not be on all of the qubits, and need only satisfy the requirements of the insert_circuit method. There must be a key for every gate except the self.identity gate, unless allow_unchanged_gates is False. In that case, gate that aren’t a key in this dictionary are left unchanged.
If a CompilationLibrary, this will be queried via the retrieve_compilation_of() method to find compilations for all of the gates in the circuit. So this CompilationLibrary must contain or be able to autogenerate compilations for the requested gates, except when allow_unchanged_gates is True. In that case, gates that a compilation is not returned for are left unchanged.
allowed_filter (dict or set, optional) – Specifies which gates are allowed to be used when generating compilations from compilation. Can only be not None if compilation is a CompilationLibrary. If a dict, keys must be gate names (like “Gcnot”) and values
QubitGraph
objects indicating where that gate (if it’s present in the library) may be used. If a set, then it specifies a set of qubits and any gate in the current library that is confined within that set is allowed. If None, then all gates within the library are allowed.allow_unchanged_gates (bool, optional) – Whether to allow some gates to remain unchanged, and therefore to be absent from compilation. When True such gates are left alone; when False an error is raised if any such gates are encountered.
depth_compression (bool, optional) – Whether to perform depth compression after changing the gate library. If one_q_gate_relations is None this will only remove idle layers and compress the circuit by moving everything as far forward as is possible without knowledge of the action of any gates other than self.identity. See the depth_compression method for more details. Under most circumstances this should be true; if it is False changing gate library will often result in a massive increase in circuit depth.
one_q_gate_relations (dict, optional) – Gate relations for the onequbit gates in the new gate library, that are used in the depth compression, to cancel / combine gates. E.g., one keyvalue pair might be (‘Gh’,’Gh’) : ‘I’, to signify that two Hadamards c ompose to the idle gate ‘Gi’. See the depth_compression() method for more details.
 Returns
None
 map_names_inplace(self, mapper)¶
The names of all of the simple labels are updated inplace according to the mapping function mapper.
 Parameters
mapper (dict or function) – A dictionary whose keys are the existing gate name values and whose values are the new names (strings) or a function which takes a single (existing name) argument and returns a new name.
 Returns
None
 map_state_space_labels_inplace(self, mapper)¶
The labels of all of the lines (wires/qubits) are updated according to the mapping function mapper.
 Parameters
mapper (dict or function) – A dictionary whose keys are the existing self.line_labels values and whose value are the new labels, or a function which takes a single (existing linelabel) argument and returns a new linelabel.
 Returns
None
 map_state_space_labels(self, mapper)¶
Creates a new Circuit whose line labels are updated according to the mapping function mapper.
 Parameters
mapper (dict or function) – A dictionary whose keys are the existing self.line_labels values and whose value are the new labels, or a function which takes a single (existing linelabel) argument and returns a new linelabel.
 Returns
Circuit
 reorder_lines_inplace(self, order)¶
Reorders the lines (wires/qubits) of the circuit.
Note that the ordering of the lines is unimportant for most purposes.
 Parameters
order (list) – A list containing all of the circuit line labels (self.line_labels) in the order that the should be converted to.
 Returns
None
 reorder_lines(self, order)¶
Reorders the lines (wires/qubits) of the circuit.
Note that the ordering of the lines is unimportant for most purposes.
 Parameters
order (list) – A list containing all of the circuit line labels (self.line_labels) in the order that the should be converted to.
 Returns
Circuit
 _is_line_idling(self, line_label, idle_layer_labels=None)¶
Whether the line in question is idling in every circuit layer.
 Parameters
line_label (str or int) – The label of the line (i.e., “wire” or qubit).
idle_layer_labels (iterable, optional) – A list or tuple of layerlabels that should be treated as idle operations, so their presence will not disqualify a line from being “idle”. E.g. [“Gi”] will cause “Gi” layers to be considered idle layers.
 Returns
bool – True if the line is idling. False otherwise.
 idling_lines(self, idle_layer_labels=None)¶
Returns the line labels corresponding to idling lines.
 Parameters
idle_layer_labels (iterable, optional) – A list or tuple of layerlabels that should be treated as idle operations, so their presence will not disqualify a line from being “idle”. E.g. [“Gi”] will cause “Gi” layers to be considered idle layers.
 Returns
tuple
 delete_idling_lines_inplace(self, idle_layer_labels=None)¶
Removes from this circuit all lines that are idling at every layer.
 Parameters
idle_layer_labels (iterable, optional) – A list or tuple of layerlabels that should be treated as idle operations, so their presence will not disqualify a line from being “idle”. E.g. [“Gi”] will cause “Gi” layers to be considered idle layers.
 Returns
None
 delete_idling_lines(self, idle_layer_labels=None)¶
Removes from this circuit all lines that are idling at every layer.
 Parameters
idle_layer_labels (iterable, optional) – A list or tuple of layerlabels that should be treated as idle operations, so their presence will not disqualify a line from being “idle”. E.g. [“Gi”] will cause “Gi” layers to be considered idle layers.
 Returns
Circuit
 replace_with_idling_line_inplace(self, line_label, clear_straddlers=True)¶
Converts the specified line to an idling line, by removing all its gates.
If there are any multiqubit gates acting on this line, this function will raise an error when clear_straddlers=False.
 Parameters
line_label (str or int) – The label of the line to convert to an idling line.
clear_straddlers (bool, optional) – Whether or not gates which straddle the line_label should also be cleared. If False and straddling gates exist, an error will be raised.
 Returns
None
 reverse_inplace(self)¶
Reverses the order of the circuit.
 Returns
None
 _combine_one_q_gates_inplace(self, one_q_gate_relations)¶
Compresses sequences of 1qubit gates in the circuit, using the provided gate relations.
One of the steps of the depth_compression() method, and in most cases that method will be more useful.
 Parameters
one_q_gate_relations (dict) –
Keys that are pairs of strings, corresponding to 1qubit gate names, with values that are a single string, also corresponding to a 1qubit gate name. Whenever a 1qubit gate with name name1 is followed in the circuit by a 1qubit gate with name2 then, if one_q_gate_relations[name1,name2] = name3, name1 > name3 and name2 > self.identity, the identity name in the circuit. Moreover, this is still implemented when there are self.identity gates between these 1qubit gates, and it is implemented iteratively in the sense that if there is a sequence of 1qubit gates with names name1, name2, name3, … and there are relations for all of (name1,name2) > name12, (name12,name3) > name123 etc then the entire sequence of 1qubit gates will be compressed into a single possibly nonidle 1qubit gate followed by idle gates in place of the previous 1qubit gates. Note that None can be used as name3 to signify that the result is the identity (no gate labels).
If a QubitProcessorSpec object has been created for the gates/device in question, the QubitProcessorSpec.oneQgate_relations is the appropriate (and autogenerated) one_q_gate_relations.
Note that this function will not compress sequences of 1qubit gates that cannot be compressed by independently inspecting sequential nonidle pairs (as would be the case with, for example, Gxpi Gzpi Gxpi Gzpi, if the relation did not know that (Gxpi,Gzpi) > Gypi, even though the sequence is the identity).
 Returns
bool – False if the circuit is unchanged, and True otherwise.
 _shift_gates_forward_inplace(self)¶
Shift all gates forward (left) as far as is possible.
This operation is performed without any knowledge of what any of the gates are. One of the steps of :method:`depth_compression()`.
 Returns
bool – False if the circuit is unchanged, and True otherwise.
 delete_idle_layers_inplace(self)¶
Deletes all layers in this circuit that contain no gate operations.
One of the steps of the depth_compression() method.
 Returns
bool – False if the circuit is unchanged, and True otherwise.
 compress_depth_inplace(self, one_q_gate_relations=None, verbosity=0)¶
Compresses the depth of this circuit using very simple rewrite rules.
If one_q_gate_relations is provided, all sequences of 1qubit gates in the circuit are compressed as far as is possible using only the pairwise combination rules provided by this dict (see below).
All gates are shifted forwarded as far as is possible without any knowledge of what any of the gates are.
All idleonly layers are deleted.
 Parameters
one_q_gate_relations (dict) –
Keys that are pairs of strings, corresponding to 1qubit gate names, with values that are a single string, also corresponding to a 1qubit gate name. Whenever a 1qubit gate with name name1 is followed in the circuit by a 1qubit gate with name2 then, if one_q_gate_relations[name1,name2] = name3, name1 > name3 and name2 > self.identity, the identity name in the circuit. Moreover, this is still implemented when there are self.identity gates between these 1qubit gates, and it is implemented iteratively in the sense that if there is a sequence of 1qubit gates with names name1, name2, name3, … and there are relations for all of (name1,name2) > name12, (name12,name3) > name123 etc then the entire sequence of 1qubit gates will be compressed into a single possibly nonidle 1qubit gate followed by idle gates in place of the previous 1qubit gates.
If a QubitProcessorSpec object has been created for the gates/device in question, the QubitProcessorSpec.oneQgate_relations is the appropriate (and autogenerated) one_q_gate_relations.
Note that this function will not compress sequences of 1qubit gates that cannot be compressed by independently inspecting sequential nonidle pairs (as would be the case with, for example, Gxpi Gzpi Gxpi Gzpi, if the relation did not know that (Gxpi,Gzpi) > Gypi, even though the sequence is the identity).
verbosity (int, optional) – If > 0, information about the depth compression is printed to screen.
 Returns
None
 layer(self, j)¶
Returns a tuple of the components, i.e. the (nonidentity) gates, in the layer at depth j.
These are the .components of the
Label
returned by indexing this Circuit (using square brackets) with j, i.e. this returns this_circuit[j].components. Parameters
j (int) – The index (depth) of the layer to be returned
 Returns
tuple
 layer_label(self, j)¶
Returns the layer, as a
Label
, at depth j.This label contains as components all the (nonidentity) gates in the layer..
 Parameters
j (int) – The index (depth) of the layer to be returned
 Returns
Label
 layer_with_idles(self, j, idle_gate_name='I')¶
Returns a tuple of the components of the layer at depth j, with idle_gate_name at empty circuit locations.
This effectively places an explicit idle_gate_name gates wherever there is an implied identity operation in the circuit.
 Parameters
j (int) – The index (depth) of the layer to be returned
idle_gate_name (str, optional) – The idle gate name to use. Note that state space (qubit) labels will be added to this name to form a
Label
.
 Returns
tuple
 layer_label_with_idles(self, j, idle_gate_name='I')¶
Returns the layer, as a
Label
, at depth j, with idle_gate_name at empty circuit locations.This effectively places an explicit idle_gate_name gates wherever there is an implied identity operation in the circuit.
 Parameters
j (int) – The index (depth) of the layer to be returned
idle_gate_name (str, optional) – The idle gate name to use. Note that state space (qubit) labels will be added to this name to form a
Label
.
 Returns
Label
 property num_layers(self)¶
The number of circuit layers.
In simple circuits, this is the same as the depth (given by :method:`depth`). For circuits containing subcircuit blocks, this gives the number of toplevel layers in this circuit.
 Returns
int
 property depth(self)¶
The circuit depth.
This is the number of layers in simple circuits. For circuits containing subcircuit blocks, this includes the full depth of these blocks. If you just want the number of toplevel layers, use :method:`num_layers`.
 Returns
int
 property width(self)¶
The circuit width.
This is the number of qubits on which the circuit acts. This includes qubits that only idle, but are included as part of the circuit according to self.line_labels.
 Returns
int
 property size(self)¶
Returns the circuit size.
This is the sum of the sizes of all the gates in the circuit. A gate that acts on nqubits has a size of n, with the exception of the idle which has a size of 0. Hence, the circuit is given by: size = depth * num_lines  num_1Q_idles.
 Returns
int
 property duration(self)¶
 two_q_gate_count(self)¶
The number of twoqubit gates in the circuit.
(Note that this cannot distinguish between “true” 2qubit gates and gate that have been defined to act on two qubits but that represent some tensorproduct gate.)
 Returns
int
 num_nq_gates(self, nq)¶
The number of nqqubit gates in the circuit.
(Note that this cannot distinguish between “true” nqqubit gates and gate that have been defined to act on nq qubits but that represent some tensorproduct gate.)
 Parameters
nq (int) – The qubitcount of the gates to count. For example, if nq == 3, this function returns the number of 3qubit gates.
 Returns
int
 property num_multiq_gates(self)¶
The number of multiqubit (2+ qubits) gates in the circuit.
(Note that this cannot distinguish between “true” multiqubit gates and gate that have been defined to act on more than one qubit but that represent some tensorproduct gate.)
 Returns
int
 _togrid(self, identity_name)¶
return a listoflists rep?
 __str__(self)¶
A text rendering of the circuit.
 __repr__(self)¶
Return repr(self).
 format_display_str(self, width=80)¶
Formats a string for displaying this circuit suject to a maximum width.
 Parameters
width (int, optional) – The maximum width in characters. If the circuit is longer than this width it is wrapped using multiple lines (like a musical score).
 Returns
str
 _print_labelinfo(self)¶
A useful debug routine for printing the internal label structure of a circuit
 abstract _write_q_circuit_tex(self, filename)¶
Writes a LaTeX file for rendering this circuit nicely.
Creates a file containing LaTex that will display this circuit using the Qcircuit.tex LaTex import (compiling the LaTex requires that you have the Qcircuit.tex file).
 Parameters
filename (str) – The file to write the LaTex into. Should end with ‘.tex’
 Returns
None
 convert_to_cirq(self, qubit_conversion, wait_duration=None, gatename_conversion=None, idle_gate_name='Gi')¶
Converts this circuit to a Cirq circuit.
 Parameters
qubit_conversion (dict) – Mapping from qubit labels (e.g. integers) to Cirq qubit objects.
wait_duration (cirq.Duration, optional) – If no gatename_conversion dict is given, the idle operation is not converted to a gate. If wait_diration is specified and gatename_conversion is not specified, then the idle operation will be converted to a cirq.WaitGate with the specified duration.
gatename_conversion (dict, optional) – If not None, a dictionary that converts the gatenames in the circuit to the Cirq gates that will appear in the Cirq circuit. If only standard pyGSTi names are used (e.g., ‘Gh’, ‘Gp’, ‘Gcnot’, ‘Gcphase’, etc) this dictionary need not be specified, and an automatic conversion to the standard Cirq names will be implemented.
idle_gate_name (str, optional) – Name to use for idle gates. Defaults to ‘Gi’
 Returns
A Cirq Circuit object.
 convert_to_quil(self, num_qubits=None, gatename_conversion=None, qubit_conversion=None, readout_conversion=None, block_between_layers=True, block_idles=True, gate_declarations=None)¶
Converts this circuit to a quil string.
 Parameters
num_qubits (int, optional) – The number of qubits for the quil file. If None, then this is assumed to equal the number of line labels in this circuit.
gatename_conversion (dict, optional) – A dictionary mapping gate names contained in this circuit to the corresponding gate names used in the rendered quil. If None, a standard set of conversions is used (see :function:`standard_gatenames_quil_conversions`).
qubit_conversion (dict, optional) – If not None, a dictionary converting the qubit labels in the circuit to the desired qubit labels in the quil output. Can be left as None if the qubit labels are either (1) integers, or (2) of the form ‘Qi’ for integer i. In this case they are converted to integers (i.e., for (1) the mapping is trivial, for (2) the mapping strips the ‘Q’).
readout_conversion (dict, optional) – If not None, a dictionary converting the qubit labels mapped through qubit_conversion to the bit labels for readot. E.g. Suppose only qubit 2 (on Rigetti hardware) is in use. Then the pyGSTi string will have only one qubit (labeled 0); it will get remapped to 2 via qubit_conversion={0:2}. At the end of the quil circuit, readout should go recorded in bit 0, so readout_conversion = {0:0}. (That is, qubit with pyGSTi label 0 gets read to Rigetti bit 0, even though that qubit has Rigetti label 2.)
block_between_layers (bool, optional) – When True, add in a barrier after every circuit layer. Including such “pragma” blocks can be important for QCVV testing, as this can help reduce the “behindthescenes” compilation (beyond necessary conversion to native instructions) experience by the circuit.
block_idles (bool, optional) – In the special case of global idle gates, pragmablock barriers are inserted even when block_between_layers=False. Set block_idles=False to disable this behavior, whcih typically results in global idle gates being removed by the compiler.
gate_declarations (dict, optional) – If not None, a dictionary that provides unitary maps for particular gates that are not already in the quil syntax.
 Returns
str – A quil string.
 convert_to_openqasm(self, num_qubits=None, standard_gates_version='u3', gatename_conversion=None, qubit_conversion=None, block_between_layers=True, block_between_gates=False, gateargs_map=None)¶
Converts this circuit to an openqasm string.
 Parameters
num_qubits (int, optional) – The number of qubits for the openqasm file. If None, then this is assumed to equal the number of line labels in this circuit.
version (string, optional) – Either ‘u3’ or ‘xsxrz’. Specifies the naming convention for the QASM gates. With ‘u3’, all singlequbit gates are specified in terms of the ‘u3’ gate, used by IBM and QisKit until ~2021 (see the qasm_u3 function). With ‘xsxrz’, all singlegates are specified in terms of ‘x’ (an x pi rotation), ‘sx’ (an x pi/2 rotation) and ‘rz’ (a parameterized rotation around z by an angle theta).
gatename_conversion (dict, optional) – If not None, a dictionary that converts the gatenames in the circuit to the gatenames that will appear in the openqasm output. If only standard pyGSTi names are used (e.g., ‘Gh’, ‘Gp’, ‘Gcnot’, ‘Gcphase’, etc) this dictionary need not be specified, and an automatic conversion to the standard openqasm names will be implemented.
qubit_conversion (dict, optional) – If not None, a dictionary converting the qubit labels in the circuit to the desired qubit labels in the openqasm output. Can be left as None if the qubit labels are either (1) integers, or (2) of the form ‘Qi’ for integer i. In this case they are converted to integers (i.e., for (1) the mapping is trivial, for (2) the mapping strips the ‘Q’).
block_between_layers (bool, optional) – When True, add in a barrier after every circuit layer. Including such barriers can be important for QCVV testing, as this can help reduce the “behindthescenes” compilation (beyond necessary conversion to native instructions) experience by the circuit.
gateargs_map (dict, optional) – If not None, a dict that maps strings (representing pyGSTi standard gate names) to functions that map the parameters of a pyGSTi gate to a string to be combined with the QASM name to specify the specific gate, in QASM. If only standard pyGSTi names are used (e.g., ‘Gh’, ‘Gzr’, ‘Gczr, etc) or none of the gates are parameterized, this dictionary need not be specified, and an automatic conversion to the standard openqasm format will be implemented.
 Returns
str – An openqasm string.
 simulate(self, model, return_all_outcomes=False)¶
Compute the outcome probabilities of this Circuit using model as a model for the gates.
The order of the outcome strings (e.g., ‘0100’) is w.r.t. to the ordering of the qubits in the circuit. That is, the ith element of the outcome string corresponds to the qubit with label self.line_labels[i].
 Parameters
model (Model) – A description of the gate and SPAM operations corresponding to the labels stored in this Circuit. If this model is over more qubits than the circuit, the output will be the probabilities for the qubits in the circuit marginalized, if possible over the other qubits. But, the simulation is over the full set of qubits in the model, and so the time taken for the simulation scales with the number of qubits in the model. For models where “spectator” qubits do not affect the qubits in this circuit (such as with perfect gates), more efficient simulations will be obtained by first creating a model only over the qubits in this circuit.
return_all_outcomes (bool, optional) – Whether to include outcomes in the returned dictionary that have zero probability. When False, the threshold for discarding an outcome as z ero probability is 10^12.
 Returns
probs (dictionary) – A dictionary with keys equal to all (return_all_outcomes is True) or possibly only some (return_all_outcomes is False) of the possible outcomes, and values that are float probabilities.
 done_editing(self)¶
Make this circuit readonly, so that it can be hashed (e.g. used as a dictionary key).
This is done automatically when attempting to hash a
Circuit
for the first time, so there’s calling this function can usually be skipped (but it’s good for code clarity). Returns
None
 expand_instruments_and_separate_povm(self, model, observed_outcomes=None)¶
Creates a dictionary of
SeparatePOVMCircuit
objects from expanding the instruments of this circuit.Each key of the returned dictionary replaces the instruments in this circuit with a selection of their members. (The size of the resulting dictionary is the product of the sizes of each instrument appearing in this circuit when observed_outcomes is None). Keys are stored as
SeparatePOVMCircuit
objects so it’s easy to keep track of which POVM outcomes (effects) correspond to observed data. This function is, for the most part, used internally to process a circuit before computing its outcome probabilities. Parameters
model (Model) –
The model used to provide necessary details regarding the expansion, including:
default SPAM layers
definitions of instrumentcontaining layers
expansions of individual instruments and POVMs
 Returns
OrderedDict – A dict whose keys are
SeparatePOVMCircuit
objects and whose values are tuples of the outcome labels corresponding to this circuit, one per POVM effect held in the key.
 pygsti.extras.idletomography.hamiltonian_jac_element(prep, error, observable)¶
Computes the Jacobian matrix element for a Hamiltonian error: how the expectation value of observable in state prep changes due to Hamiltonian error.
 Parameters
prep (NQPauliState) – The state that is prepared.
error (NQPauliOp) – The type (as a pauli operator) of Hamiltonian error.
observable (NQPauliOp) – The observable whose expectation value is measured. Note: giving a NQPauliState will be treated as an Nqubit Pauli operator whose sign is the product of the signs of the NQPauliState’s perqubit basis signs.
 Returns
float
 pygsti.extras.idletomography.stochastic_outcome(prep, error, meas)¶
Computes the “expected” outcome when the stochastic error error occurs between preparing in prep and measuring in basis meas.
Note: currently, the preparation and measurement bases must be the same (up to signs) or an AssertionError is raised. (If they’re not, there isn’t a single expected outcome).
 Parameters
prep (NQPauliState) – The state that is prepared.
error (NQPauliOp) – The type (as a pauli operator) of Stochastic error.
meas (NQPauliState) – The basis which is measured. The ‘signs’ of the basis Paulis determine which state is measured as a ‘0’ vs. a ‘1’. (essentially the POVM.)
 Returns
NQOutcome
 pygsti.extras.idletomography.stochastic_jac_element(prep, error, meas, outcome)¶
Computes the Jacobian matrix element for a Stochastic error: how the probability of outcome changes with respect to the rate of error when preparing state prep and measuring in basis meas.
 Parameters
prep (NQPauliState) – The state that is prepared.
error (NQPauliOp) – The type (as a pauli operator) of Stochastic error.
meas (NQPauliState) – The basis that is measured (essentially the POVM).
outcome (NQOutcome) – The measurement outcome that is considered.
 Returns
float
 pygsti.extras.idletomography.affine_jac_element(prep, error, meas, outcome)¶
Computes the Jacobian matrix element for a Affine error: how the probability of outcome changes with respect to the rate of error when preparing state prep and measuring in basis meas.
Note: Affine error maps leave qubits corresponging to I’s in error alone. An affine error is defined as replacing portions of the density matrix corresponding to nontrivial Pauli operators with those operators.
 Parameters
prep (NQPauliState) – The state that is prepared.
error (NQPauliOp) – The type (as a pauli operator) of Affine error.
meas (NQPauliState) – The basis that is measured (essentially the POVM).
outcome (NQOutcome) – The measurement outcome that is considered.
 Returns
float
 pygsti.extras.idletomography.affine_jac_obs_element(prep, error, observable)¶
Computes the Jacobian matrix element for a Affine error: how the expectation value of observable changes with respect to the rate of error when preparing state prep.
Note: Affine error maps leave qubits corresponging to I’s in error alone. An affine error is defined as replacing portions of the density matrix corresponding to nontrivial Pauli operators with those operators.
 Parameters
prep (NQPauliState) – The state that is prepared.
error (NQPauliOp) – The type (as a pauli operator) of Affine error.
observable (NQPauliOp) – The observable whose expectation value is measured.
 Returns
float
 pygsti.extras.idletomography.idle_tomography_fidpairs(nqubits, maxweight=2, include_hamiltonian=True, include_stochastic=True, include_affine=True, ham_tmpl='auto', preferred_prep_basis_signs=('+', '+', '+'), preferred_meas_basis_signs=('+', '+', '+'))¶
Construct a list of Paulibasis fiducial pairs for idle tomography.
This function constructs the “standard” set of fiducial pairs used to generate idle tomography sequences which probe Hamiltonian, Stochastic, and/or Affine errors in an idle gate.
 Parameters
nqubits (int) – The number of qubits.
maxweight (int, optional) – The maximum weight of errors to consider.
include_hamiltonian (bool, optional) – Whether to include fiducial pairs for finding Hamiltonian, Stochastic, and Affinetype errors.
include_stochastic (bool, optional) – Whether to include fiducial pairs for finding Hamiltonian, Stochastic, and Affinetype errors.
include_affine (bool, optional) – Whether to include fiducial pairs for finding Hamiltonian, Stochastic, and Affinetype errors.
ham_tmpl (tuple, optional) – A tuple of lengthmaxweight Pauli strings (i.e. string w/letters “X”, “Y”, or “Z”), describing how to construct the fiducial pairs used to detect Hamiltonian errors. The special (and default) value “auto” uses (“X”,”Y”,”Z”) and (“ZY”,”ZX”,”XZ”,”YZ”,”YX”,”XY”) for maxweight equal to 1 and 2, repectively, and will generate an error if maxweight > 2.
preferred_prep_basis_signs (tuple, optional) – A 3tuple of “+” or “” strings indicating which sign for preparing or measuring in the X, Y, and Z bases is preferable. Usually one orientation if preferred because it’s easier to achieve using the native model.
preferred_meas_basis_signs (tuple, optional) – A 3tuple of “+” or “” strings indicating which sign for preparing or measuring in the X, Y, and Z bases is preferable. Usually one orientation if preferred because it’s easier to achieve using the native model.
 Returns
list – a list of (prep,meas) 2tuples of NQPauliState objects, each of length nqubits, representing the fiducial pairs.
 pygsti.extras.idletomography.preferred_signs_from_paulidict(pauli_basis_dict)¶
Infers what the preferred basis signs are based on the length of gatename strings in pauli_basis_dict (shorter strings are preferred).
 Parameters
pauli_basis_dict (dict) – A dictionary w/keys like “+X” or “Y” and values that are tuples of gate names (not labels, which include qubit or other statespace designations), e.g. (“Gx”,”Gx”).
 Returns
tuple – A 3tuple of elements in {“+”, ““}, exactly the format expected by preferred_*_basis_signs arguments of :function:`idle_tomography_fidpairs`.
 pygsti.extras.idletomography.fidpairs_to_pauli_fidpairs(fidpairs_list, pauli_basis_dicts, nqubits)¶
Translate
GatesString
type fiducial pairs toNQPauliState
type “Pauli fiducial pairs” using pauli_basis_dicts. Parameters
fidpairs_list (list) – A list whose elements are 2tuples of
Circuit
objects.pauli_basis_dicts (tuple) – A (prepPauliBasisDict,measPauliBasisDict) tuple of dictionaries specifying the way to prepare and measure in Pauli bases. See :function:`preferred_signs_from_paulidict` for details on each dictionary’s format.
nqubits (int) – The number of qubits. Needed because
Circuit
objects don’t contain this information.
 Returns
list – A list of 2tuples of
NQPauliState
objects.
 pygsti.extras.idletomography.determine_paulidicts(model)¶
Intelligently determine preparation and measurement Pauli basis dictionaries from a
Model
.The returned dictionaries are required for various parts of idle tomography, as they bridge the native model’s gates to the “Pauli basis language” used in idle tomography.
 Parameters
model (Model) – The model which defines the available preparation, measurement, and operations. It is assumed that model’s operation are expressed in a Pauliproduct basis.
 Returns
pauli_basis_dicts or None – If successful, a (prepDict,measureDict) 2tuple of Pauli basis dictionaries. If unsuccessful, None.
 pygsti.extras.idletomography.make_idle_tomography_list(nqubits, max_lenghts, pauli_basis_dicts, maxweight=2, idle_string=((),), include_hamiltonian=True, include_stochastic=True, include_affine=True, ham_tmpl='auto', preferred_prep_basis_signs='auto', preferred_meas_basis_signs='auto')¶
Construct the list of experiments needed to perform idle tomography.
 Parameters
nqubits (int) – The number of qubits.
max_lenghts (list) – A list of maximum germpower lengths. Each specifies a number many times to repeat the idle gate, and typically this is a list of the powers of 2 preceded by zero, e.g. [0,1,2,4,16]. The largest value in this list should be chosen to be the maximum number of idle gates you want to perform in a row (typically limited by performance or time constraints).
pauli_basis_dicts (tuple) – A (prepPauliBasisDict,measPauliBasisDict) tuple of dictionaries specifying the way to prepare and measure in Pauli bases. See :function:`preferred_signs_from_paulidict` for details on each dictionary’s format.
maxweight (int, optional) – The maximum weight of errors to consider.
idle_string (Circuitlike, optional) – A Circuit or tuple of operation labels that represents the idle gate being characterized by idle tomography.
include_hamiltonian (bool, optional) – Whether to include fiducial pairs for finding Hamiltonian, Stochastic, and Affinetype errors.
include_stochastic (bool, optional) – Whether to include fiducial pairs for finding Hamiltonian, Stochastic, and Affinetype errors.
include_affine (bool, optional) – Whether to include fiducial pairs for finding Hamiltonian, Stochastic, and Affinetype errors.
ham_tmpl (tuple, optional) – A tuple of lengthmaxweight Pauli strings (i.e. string w/letters “X”, “Y”, or “Z”), describing how to construct the fiducial pairs used to detect Hamiltonian errors. The special (and default) value “auto” uses (“X”,”Y”,”Z”) and (“ZY”,”ZX”,”XZ”,”YZ”,”YX”,”XY”) for maxweight equal to 1 and 2, repectively, and will generate an error if maxweight > 2.
preferred_prep_basis_signs (tuple, optional) – A 3tuple of “+” or “” strings indicating which sign for preparing or measuring in the X, Y, and Z bases is preferable. Usually one orientation if preferred because it’s easier to achieve using the native model. Additionally, the special (and default) value “auto” may be used, in which case :function:`preferred_signs_from_paulidict` is used to choose preferred signs based on pauli_basis_dicts.
preferred_meas_basis_signs (tuple, optional) – A 3tuple of “+” or “” strings indicating which sign for preparing or measuring in the X, Y, and Z bases is preferable. Usually one orientation if preferred because it’s easier to achieve using the native model. Additionally, the special (and default) value “auto” may be used, in which case :function:`preferred_signs_from_paulidict` is used to choose preferred signs based on pauli_basis_dicts.
 Returns
list – A list of
Circuit
objects.
 pygsti.extras.idletomography.make_idle_tomography_lists(nqubits, max_lenghts, pauli_basis_dicts, maxweight=2, idle_string=((),), include_hamiltonian=True, include_stochastic=True, include_affine=True, ham_tmpl='auto', preferred_prep_basis_signs='auto', preferred_meas_basis_signs='auto')¶
Construct lists of experiments, one for each maximumlength value, needed to perform idle tomography. This is potentiall useful for running GST on idle tomography data.
 Parameters
nqubits (int) – The number of qubits.
max_lenghts (list) – A list of maximum germpower lengths. Each specifies a number many times to repeat the idle gate, and typically this is a list of the powers of 2 preceded by zero, e.g. [0,1,2,4,16]. The largest value in this list should be chosen to be the maximum number of idle gates you want to perform in a row (typically limited by performance or time constraints).
pauli_basis_dicts (tuple) – A (prepPauliBasisDict,measPauliBasisDict) tuple of dictionaries specifying the way to prepare and measure in Pauli bases. See :function:`preferred_signs_from_paulidict` for details on each dictionary’s format.
maxweight (int, optional) – The maximum weight of errors to consider.
idle_string (Circuitlike, optional) – A Circuit or tuple of operation labels that represents the idle gate being characterized by idle tomography.
include_hamiltonian (bool, optional) – Whether to include fiducial pairs for finding Hamiltonian, Stochastic, and Affinetype errors.
include_stochastic (bool, optional) – Whether to include fiducial pairs for finding Hamiltonian, Stochastic, and Affinetype errors.
include_affine (bool, optional) – Whether to include fiducial pairs for finding Hamiltonian, Stochastic, and Affinetype errors.
ham_tmpl (tuple, optional) – A tuple of lengthmaxweight Pauli strings (i.e. string w/letters “X”, “Y”, or “Z”), describing how to construct the fiducial pairs used to detect Hamiltonian errors. The special (and default) value “auto” uses (“X”,”Y”,”Z”) and (“ZY”,”ZX”,”XZ”,”YZ”,”YX”,”XY”) for maxweight equal to 1 and 2, repectively, and will generate an error if maxweight > 2.
preferred_prep_basis_signs (tuple, optional) – A 3tuple of “+” or “” strings indicating which sign for preparing or measuring in the X, Y, and Z bases is preferable. Usually one orientation if preferred because it’s easier to achieve using the native model. Additionally, the special (and default) value “auto” may be used, in which case :function:`preferred_signs_from_paulidict` is used to choose preferred signs based on pauli_basis_dicts.
preferred_meas_basis_signs (tuple, optional) – A 3tuple of “+” or “” strings indicating which sign for preparing or measuring in the X, Y, and Z bases is preferable. Usually one orientation if preferred because it’s easier to achieve using the native model. Additionally, the special (and default) value “auto” may be used, in which case :function:`preferred_signs_from_paulidict` is used to choose preferred signs based on pauli_basis_dicts.
 Returns
list – A list of lists of
Circuit
objects, one list per maxL value.
 pygsti.extras.idletomography.compute_observed_samebasis_err_rate(dataset, pauli_fidpair, pauli_basis_dicts, idle_string, outcome, max_lenghts, fit_order=1)¶
Extract the observed error rate from a series of experiments which prepares and measures in the same Pauli basis and tracks a particular outcome.
 Parameters
dataset (DataSet) – The set of data counts (observations) to use.
pauli_fidpair (tuple) – A (prep,measure) 2tuple of
NQPauliState
objects specifying the prepation state and measurement basis.pauli_basis_dicts (tuple) – A (prepPauliBasisDict,measPauliBasisDict) tuple of dictionaries specifying the way to prepare and measure in Pauli bases. See :function:`preferred_signs_from_paulidict` for details on each dictionary’s format.
idle_string (Circuit) – The Circuit representing the idle operation being characterized.
outcome (NQOutcome) – The outcome being tracked.
max_lenghts (list) – A list of maximum germpower lengths. The seriese of sequences considered is prepFiducial + idle_string^L + measFiducial, where L ranges over the values in max_lenghts.
fit_order (int, optional) – The polynomial order used to fit the observed data probabilities.
 Returns
dict – A dictionary of information about the fit, including the observed error rate and the data points that were fit.
 pygsti.extras.idletomography.compute_observed_diffbasis_err_rate(dataset, pauli_fidpair, pauli_basis_dicts, idle_string, observable, max_lenghts, fit_order=1)¶
Extract the observed error rate from a series of experiments which prepares and measures in different Pauli basis and tracks the expectation value of a particular observable.
 Parameters
dataset (DataSet) – The set of data counts (observations) to use.
pauli_fidpair (tuple) – A (prep,measure) 2tuple of
NQPauliState
objects specifying the prepation state and measurement basis.pauli_basis_dicts (tuple) – A (prepPauliBasisDict,measPauliBasisDict) tuple of dictionaries specifying the way to prepare and measure in Pauli bases. See :function:`preferred_signs_from_paulidict` for details on each dictionary’s format.
idle_string (Circuit) – The Circuit representing the idle operation being characterized.
observable (NQPauliOp) – The observable whose expectation value is being tracked.
max_lenghts (list) – A list of maximum germpower lengths. The seriese of sequences considered is prepFiducial + idle_string^L + measFiducial, where L ranges over the values in max_lenghts.
fit_order (int, optional) – The polynomial order used to fit the observed data probabilities.
 Returns
dict – A dictionary of information about the fit, including the observed error rate and the data points that were fit.
 pygsti.extras.idletomography.do_idle_tomography(nqubits, dataset, max_lenghts, pauli_basis_dicts, maxweight=2, idle_string=((),), include_hamiltonian='auto', include_stochastic='auto', include_affine='auto', advanced_options=None, verbosity=0, comm=None)¶
Analyze dataset using the idle tomography protocol to characterize idle_string.
 Parameters
nqubits (int) – The number of qubits.
dataset (DataSet) – The set of data counts (observations) to use.
max_lenghts (list) – A list of maximum germpower lengths. Each specifies a number many times to repeat the idle gate, and typically this is a list of the powers of 2 preceded by zero, e.g. [0,1,2,4,16]. The largest value in this list should be chosen to be the maximum number of idle gates you want to perform in a row (typically limited by performance or time constraints).
pauli_basis_dicts (tuple) – A (prepPauliBasisDict,measPauliBasisDict) tuple of dictionaries specifying the way to prepare and measure in Pauli bases. See :function:`preferred_signs_from_paulidict` for details on each dictionary’s format.
maxweight (int, optional) – The maximum weight of errors to consider.
idle_string (Circuitlike, optional) – A Circuit or tuple of operation labels that represents the idle gate being characterized by idle tomography.
include_hamiltonian ({True,False,"auto"}) – Whether to extract Hamiltonian, Stochastic, and Affinetype intrinsic errors. If “auto” is specified, then the corresponding errortype is extracted only if there is enough data to reliably infer them (i.e. enough data to construct “full rank” Jacobian matrices).
include_stochastic ({True,False,"auto"}) – Whether to extract Hamiltonian, Stochastic, and Affinetype intrinsic errors. If “auto” is specified, then the corresponding errortype is extracted only if there is enough data to reliably infer them (i.e. enough data to construct “full rank” Jacobian matrices).
include_affine ({True,False,"auto"}) – Whether to extract Hamiltonian, Stochastic, and Affinetype intrinsic errors. If “auto” is specified, then the corresponding errortype is extracted only if there is enough data to reliably infer them (i.e. enough data to construct “full rank” Jacobian matrices).
advanced_options (dict, optional) –
A dictionary of optional advanced arguments which influence the way idle tomography is performed. Allowed keys are:
”jacobian mode”: {“separate”,”together”} how to evaluate jacobians
”preferred_prep_basis_signs” : 3tuple of “+”/”” or default=”auto”
”preferred_meas_basis_signs” : 3tuple of “+”/”” or default=”auto”
”pauli_fidpairs”: alternate list of pauli fiducial pairs to use
”fit order” : integer order for polynomial fits to data
”ham_tmpl” : see :function:`make_idle_tomography_list`
verbosity (int, optional) – How much detail to send to stdout.
comm (mpi4py.MPI.Comm, optional) – When not None, an MPI communicator for distributing the computation across multiple processors.
 Returns
IdleTomographyResults
 class pygsti.extras.idletomography.IdleTomographyIntrinsicErrorsTable(ws, idtresults, display=('H', 'S', 'A'), display_as='boxes')¶
Bases:
pygsti.report.workspace.WorkspaceTable
A table of all the intrinsic rates found by idle tomography.
 _create(self, idtresults, display, display_as)¶
 class pygsti.extras.idletomography.IdleTomographyObservedRatesTable(ws, idtresults, threshold=1.0, mdl_simulator=None)¶
Bases:
pygsti.report.workspace.WorkspaceTable
A table of the largest N (in absolute value) observed error rates.
 _create(self, idtresults, threshold, mdl_simulator)¶
 class pygsti.extras.idletomography.IdleTomographyObservedRatePlot(ws, idtresults, typ, fidpair, obs_or_outcome, title='auto', scale=1.0, mdl_simulator=None)¶
Bases:
pygsti.report.workspace.WorkspacePlot
A plot showing how an observed error rate is obtained by fitting a sequence of observed data to a simple polynomial.
 _create(self, idtresults, typ, fidpair, obs_or_outcome, title, scale, mdl_simulator)¶
 class pygsti.extras.idletomography.IdleTomographyObservedRatesForIntrinsicRateTable(ws, idtresults, typ, error_op, threshold=1.0, mdl_simulator=None)¶
Bases:
pygsti.report.workspace.WorkspaceTable
A table showing the observed error rates relevant for determining a particular intrinsic rate. Output can be limited to just the largest observed rates.
 _create(self, idtresults, typ, error_op, threshold, mdl_simulator)¶
 pygsti.extras.idletomography.create_idletomography_report(results, filename, title='auto', ws=None, auto_open=False, link_to=None, brevity=0, advanced_options=None, verbosity=1)¶
Creates an Idle Tomography report, summarizing the results of running idle tomography on a data set.
 Parameters
results (IdleTomographyResults) – An object which represents the set of results from an idle tomography run, typically obtained from running
do_idle_tomography()
OR a dictionary of such objects, representing multiple idle tomography runs to be compared (typically all with different data sets). The keys of this dictionary are used to label different data sets that are selectable in the report.filename (string, optional) – The output filename where the report file(s) will be saved. If None, then no output file is produced (but returned Workspace still caches all intermediate results).
title (string, optional) – The title of the report. “auto” causes a random title to be generated (which you may or may not like).
ws (Workspace, optional) – The workspace used as a scratch space for performing the calculations and visualizations required for this report. If you’re creating multiple reports with similar tables, plots, etc., it may boost performance to use a single Workspace for all the report generation.
auto_open (bool, optional) – If True, automatically open the report in a web browser after it has been generated.
link_to (list, optional) – If not None, a list of one or more items from the set {“tex”, “pdf”, “pkl”} indicating whether or not to create and include links to Latex, PDF, and Python pickle files, respectively. “tex” creates latex source files for tables; “pdf” renders PDFs of tables and plots ; “pkl” creates Python versions of plots (pickled python data) and tables (pickled pandas DataFrams).
advanced_options (dict, optional) –
A dictionary of advanced options for which the default values aer usually are fine. Here are the possible keys of advanced_options:
 connectedbool, optional
Whether output HTML should assume an active internet connection. If True, then the resulting HTML file size will be reduced because it will link to web resources (e.g. CDN libraries) instead of embedding them.
 cachefilestr, optional
filename with cached workspace results
 precisionint or dict, optional
The amount of precision to display. A dictionary with keys “polar”, “sci”, and “normal” can separately specify the precision for complex angles, numbers in scientific notation, and everything else, respectively. If an integer is given, it this same value is taken for all precision types. If None, then {‘normal’: 6, ‘polar’: 3, ‘sci’: 0} is used.
 resizablebool, optional
Whether plots and tables are made with resize handles and can be resized within the report.
 autosize{‘none’, ‘initial’, ‘continual’}
Whether tables and plots should be resized, either initially – i.e. just upon first rendering (“initial”) – or whenever the browser window is resized (“continual”).
verbosity (int, optional) – How much detail to send to stdout.
 Returns
Workspace – The workspace object used to create the report
 class pygsti.extras.idletomography.IdleTomographyResults(dataset, max_lengths, max_error_weight, fit_order, pauli_dicts, idle_str, error_list, intrinsic_rates, pauli_fidpairs, observed_rate_infos)¶
Bases:
object
A container for idle tomography results: intrinsic and observable errors, along with supporting information.
 __str__(self)¶
Return str(self).
 class pygsti.extras.idletomography._GlobalElementaryErrorgenLabel(errorgen_type, basis_element_labels, sslbls)¶
Bases:
ElementaryErrorgenLabel
Labels an elementary error generator on n qubits that includes the state space labels on which the generator acts (unlike a “local” label, i.e. a
LocalElementaryErrorgenLabel
which doesn’t) classmethod cast(cls, obj, sslbls=None, identity_label='I')¶
TODO: docstring  lots in this module
 __hash__(self)¶
Return hash(self).
 __eq__(self, other)¶
Return self==value.
 __str__(self)¶
Return str(self).
 __repr__(self)¶
Return repr(self).
 pygsti.extras.idletomography.alloutcomes(prep, meas, maxweight)¶
Lists every “error bit string” that co1uld be caused by an error of weight up to maxweight when performing prep & meas (must be in same basis, but may have different signs).
 Parameters
prep (NQPauliState) –
meas (NQPauliState) –
maxweight (int) –
 Returns
list – A list of
NQOutcome
objects.
 pygsti.extras.idletomography.allerrors(nqubits, maxweight)¶
Lists every Pauli error operator for nqubits qubits with weight <= maxweight
 Parameters
nqubits (int) –
maxweight (int) –
 Returns
list – A list of
NQPauliOp
objects.
 pygsti.extras.idletomography.allobservables(meas, maxweight)¶
Lists every weight <= maxweight observable whose expectation value can be extracted from the local Pauli measurement described by meas.
 Parameters
meas (NQPauliState) –
maxweight (int) –
 Returns
list – A list of
NQPauliOp
objects.
 pygsti.extras.idletomography.tile_pauli_fidpairs(base_fidpairs, nqubits, maxweight)¶
Tiles a set of base fiducial pairs on maxweight qubits to a set of fiducial pairs on nqubits qubits such that every set of maxweight qubits takes on the values in each base pair in at least one of the returned pairs.
 Parameters
base_fidpairs (list) – A list of 2tuples of
NQPauliState
objects (on maxweight qubits).nqubits (int) – The number of qubits.
maxweight (int) – The maximum weight errors the base qubits are meant to detect. Equal to the number of qubits in the base pairs.
 Returns
list – A list of 2tuples of
NQPauliState
objects (on nqubits qubits).
 pygsti.extras.idletomography.nontrivial_paulis(wt)¶
List all nontrivial paulis of given weight wt.
 Parameters
wt (int) –
 Returns
list – A list of tuples of ‘X’, ‘Y’, and ‘Z’, e.g. (‘X’,’Z’).
 pygsti.extras.idletomography.set_idle_errors(nqubits, model, errdict, rand_default=None, hamiltonian=True, stochastic=True, affine=True)¶
Set specific or random error terms (typically for a datagenerating model) within a noise model (a
CloudNoiseModel
object). Parameters
nqubits (int) – The number of qubits.
model (CloudNoiseModel) – The model, to set the idle errors of.
errdict (dict) – A dictionary of errors to include. Keys are “S(<>)”, “H(<>)”, and “A(<>)” where <> is a string of ‘X’,’Y’,’Z’,and ‘I’ (e.g. “S(XIZ)”) and values are floating point error rates.
rand_default (float or numpy array, optional) – Random error rates to insert into values not specified in errdict. If a floating point number, a random value between 0 and rand_default is used. If an array, then values are taken directly and sequentially from this array (typically of random rates). The array must be long enough to provide values for all unspecified rates.
hamiltonian (bool, optional) – Whether model includes Hamiltonian, Stochastic, and/or Affine errors (e.g. if the model was built with “H+S” parameterization, then only hamiltonian and stochastic should be set to True).
stochastic (bool, optional) – Whether model includes Hamiltonian, Stochastic, and/or Affine errors (e.g. if the model was built with “H+S” parameterization, then only hamiltonian and stochastic should be set to True).
affine (bool, optional) – Whether model includes Hamiltonian, Stochastic, and/or Affine errors (e.g. if the model was built with “H+S” parameterization, then only hamiltonian and stochastic should be set to True).
 Returns
numpy.ndarray – The random rates the were used.
 pygsti.extras.idletomography.extract_idle_errors(nqubits, model, hamiltonian=True, stochastic=True, affine=True, scale_for_idt=True)¶
Get error rates on the global idle operation withina
CloudNoiseModel
object. Parameters
nqubits (int) – The number of qubits.
model (CloudNoiseModel) – The model, to get the idle errors of.
hamiltonian (bool, optional) – Whether model includes Hamiltonian, Stochastic, and/or Affine errors (e.g. if the model was built with “H+S” parameterization, then only hamiltonian and stochastic should be set to True).
stochastic (bool, optional) – Whether model includes Hamiltonian, Stochastic, and/or Affine errors (e.g. if the model was built with “H+S” parameterization, then only hamiltonian and stochastic should be set to True).
affine (bool, optional) – Whether model includes Hamiltonian, Stochastic, and/or Affine errors (e.g. if the model was built with “H+S” parameterization, then only hamiltonian and stochastic should be set to True).
scale_for_idt (bool, optional) – Whether rates should be scaled to match the intrinsic rates output by idle tomography. If False, then the rates are simply the coefficients of corresponding terms in the error generator.
 Returns
hamiltonian_rates, stochastic_rates, affine_rates (dict) – Dictionaries of error rates. Keys are Pauli labels of length nqubits, e.g. “XIX”, “IIX”, “XZY”. Only nonzero rates are returned.
 pygsti.extras.idletomography.predicted_intrinsic_rates(nqubits, maxweight, model, hamiltonian=True, stochastic=True, affine=True)¶
Get the exact intrinsic rates that would be produced by simulating model (for comparison with idle tomography results).
 Parameters
nqubits (int) – The number of qubits.
maxweight (int, optional) – The maximum weight of errors to consider.
model (CloudNoiseModel) – The model to extract intrinsic error rates from.
hamiltonian (bool, optional) – Whether model includes Hamiltonian, Stochastic, and/or Affine errors (e.g. if the model was built with “H+S” parameterization, then only hamiltonian and stochastic should be set to True).
stochastic (bool, optional) – Whether model includes Hamiltonian, Stochastic, and/or Affine errors (e.g. if the model was built with “H+S” parameterization, then only hamiltonian and stochastic should be set to True).
affine (bool, optional) – Whether model includes Hamiltonian, Stochastic, and/or Affine errors (e.g. if the model was built with “H+S” parameterization, then only hamiltonian and stochastic should be set to True).
 Returns
ham_intrinsic_rates, sto_intrinsic_rates, aff_intrinsic_rates (numpy.ndarray) – Arrays of intrinsic rates. None if corresponding hamiltonian, stochastic or affine is set to False.
 pygsti.extras.idletomography.predicted_observable_rates(idtresults, typ, nqubits, maxweight, model)¶
Get the exact observable rates that would be produced by simulating model (for comparison with idle tomography results).
 Parameters
idtresults (IdleTomographyResults) – The idle tomography results object used to determing which observable rates should be computed, and the provider of the Jacobian relating the intrinsic rates internal to model to these observable rates.
typ ({"samebasis","diffbasis"}) – The type of observable rates to predict and return.
nqubits (int) – The number of qubits.
maxweight (int) – The maximum weight of errors to consider.
model (CloudNoiseModel) – The noise model to extract error rates from.
 Returns
rates (dict) – A dictionary of the form: rate = rates[pauli_fidpair][obsORoutcome], to match the structure of an IdleTomographyResults object’s `
 class pygsti.extras.idletomography.NQPauliState(string_rep, signs=None)¶
Bases:
object
A Nqubit state that is the tensor product of N 1qubit Pauli eigenstates. These can be represented as a string of Xs, Ys and Zz (but not Is) each with a +/ sign indicating which of the two eigenstates is meant.
A NQPauliState object can also be used to represent a POVM whose effects are the projections onto the 2^N tensor products of (the given) Pauli eigenstates. The +/ sign in this case indicates which eigenstate is equated with the “0” (vs “1”) outcome.
 __len__(self)¶
 __str__(self)¶
Return str(self).
 __repr__(self)¶
Return repr(self).
 __eq__(self, other)¶
Return self==value.
 __hash__(self)¶
Return hash(self).
 to_circuit(self, pauli_basis_dict)¶
Convert this Pauli basis state or measurement to a fiducial operation sequence.
When the returned operation sequence follows a preparation in the 0…0> Zbasis state or is followed by a Zbasis measurement (with all “+” signs), then the Pauli state preparation or measurement described by this object will be performed.
 Parameters
pauli_basis_dict (dict) – A dictionary w/keys like “+X” or “Y” and values that are tuples of gate names (not labels, which include qubit or other statespace designations), e.g. (“Gx”,”Gx”). This dictionary describes how to prepare or measure in Pauli bases.
 Returns
Circuit
 class pygsti.extras.idletomography.NQPauliOp(string_rep, sign=1)¶
Bases:
object
A Nqubit pauli operator, consisting of a 1qubit Pauli operation on each qubits.
 classmethod weight_1_pauli(cls, n, i, pauli)¶
Creates a nqubit Pauli operator with the Pauli indexed by pauli in location i.
 Parameters
n (int) – The number of qubits
i (int) – The index of the single nontrivial Pauli operator.
pauli (int) – An integer 0 <= P <= 2 indexing the nontrivial Pauli at location i as follows: 0=’X’, 1=’Y’, 2=’Z’.
 Returns
NQPauliOp
 classmethod weight_2_pauli(cls, n, i, j, pauli1, pauli2)¶
Creates a nqubit Pauli operator with the Paulis indexed by pauli1 and pauli2 in locations i and j respectively.
 Parameters
n (int) – The number of qubits
i (int) – The indices of the nontrivial Pauli operators.
j (int) – The indices of the nontrivial Pauli operators.
pauli1 (int) – Integers 0 <= pauli <= 2 indexing the nontrivial Paulis at locations i and j, respectively, as follows: 0=’X’, 1=’Y’, 2=’Z’.
pauli2 (int) – Integers 0 <= pauli <= 2 indexing the nontrivial Paulis at locations i and j, respectively, as follows: 0=’X’, 1=’Y’, 2=’Z’.
 Returns
NQPauliOp
 __len__(self)¶
 __str__(self)¶
Return str(self).
 __repr__(self)¶
Return repr(self).
 __eq__(self, other)¶
Return self==value.
 __hash__(self)¶
Return hash(self).
 subpauli(self, indices)¶
Returns a new NQPauliOp object which sets all (1qubit) operators to “I” except those in indices, which remain as they are in this object.
 Parameters
indices (iterable) – A sequence of integer indices between 0 and N1, where N is the number of qubits in this pauli operator.
 Returns
NQPauliOp
 dot(self, other)¶
Computes the HilbertSchmidt dot product (normed to 1) between this Pauli operator and other.
 Parameters
other (NQPauliOp) – The other operator to take a dot product with.
 Returns
integer – Either 0, 1, or 1.
 statedot(self, state)¶
Computes a dot product between state and this operator. (note that an Xbasis ‘+’ state is represented by (I+X) not just X)
 Parameters
state (NQPauliState) –
 Returns
int
 commuteswith(self, other)¶
Determine whether this operator commutes (or anticommutes) with other.
 Parameters
other (NQPauliOp) –
 Returns
bool
 icommutator_over_2(self, other)¶
Compute i[self, other]/2 where [,] is the commutator.
 Parameters
other (NQPauliOp or NQPauliState) – The operator to take a commutator with. A NQPauliState is treated as an operator (i.e. ‘X’ basis state => ‘X’ Pauli operation) with sign given by the product of its 1qubit basis signs.
 Returns
NQPauliOp
 class pygsti.extras.idletomography.NQOutcome(string_rep)¶
Bases:
object
A string of 0’s and 1’s representing a definite outcome in the Zbasis.
 classmethod weight_1_string(cls, n, i)¶
creates a nbit string with a 1 in location i.
 classmethod weight_2_string(cls, n, i, j)¶
creates a nbit string with 1s in locations i and j.
 __str__(self)¶
Return str(self).
 __repr__(self)¶
Return repr(self).
 __eq__(self, other)¶
Return self==value.
 __hash__(self)¶
Return hash(self).
 flip(self, *indices)¶
Flip “0” <> “1” at any number of indices. This function takes a variable number of integer arguments specifying the qubit indices whose value should be flipped.
 Returns
NQOutcome – A new outcome object with flipped bits.