pygsti.models.fogistore

Defines the FirstOrderGaugeInvariantStore class and supporting functionality.

Module Contents

Classes

FirstOrderGaugeInvariantStore

An object that computes and stores the first-order-gauge-invariant quantities of a model.

class pygsti.models.fogistore.FirstOrderGaugeInvariantStore(primitive_op_labels, gauge_space, elem_errorgen_labels_by_op, op_errorgen_indices, fogi_directions, fogi_metadata, dependent_dir_indices, fogv_directions, allop_gauge_action, gauge_space_directions, norm_order='auto', dependent_fogi_action='drop')

Bases: pygsti.baseobjs.nicelyserializable.NicelySerializable

An object that computes and stores the first-order-gauge-invariant quantities of a model.

Currently, it is only compatible with ExplicitOpModel objects.

Parameters

primitive_op_labelstuple of Label

Labels describing the gate set operations

gauge_spaceErrorgenSpace

Special way of intersecting the gauge spaces of all ops, see the beginning of from_gauge_action_matrices() for a more detailed description.

elem_errorgen_labels_by_opdict of Label keys with GlobalElementaryErrorgenLabel or GlobalElementaryErrorgenLabel values

Elementary error generator labels for every operation in the gate set

op_errorgen_indicesdict of Label keys with Slices values

Specifies which indices from the error generator space labels correspond to which operation. For example, these allows us to index accordingly into the rows of allop_gauge_action which contain all error generators from every operation stacked on top of each other.

fogi_directionsnumpy array

Array where each column is a FOGI direction, the rows represent the modelmember parameters from which they were derived (typically elementary error generators)

fogi_metadatalist of dictionaries

Entry number k of this list contains metadata information about fogi quantity k (column k of fogi_directions). It is organized as a dictionary with the following entries:

• ‘name’ (str) : Label describing the FOGI quantity

• ‘abbrev’ (str) : An abbreviated version of the label above TODO: more details

• ‘r’ (float)constant that allows us to convert between the gauge-space-normalized

  FOGI direction to the errgen-space-normalized version of it. fogi_dir = r * dot(M, epsilon) = r * dot(inv_diff_gauge_action, int_vec)

• ‘gaugespace_dir’ (numpy array)A corresponding gauge direction TODO: more details on their relationship

  to FOGI quantities

• ‘opset’ (list of Label)The set of model member operations that are affected by the corresponding FOGI

  quantity

• ‘raw’ (str) : Another version of ‘name’ without abbreviations

dependent_dir_indiceslist of int

Specifies the indices of a set of FOGI quantities which, if removed, the remaining FOGI quantities are linearly independent.

fogv_directionsnumpy array

A list of gauge directions that span the gauge space of the target gate set

allop_gauge_actionlil_matrix

Stands for “All operations gauge action”. It is a restricted version of each operation’s gauge_action stacked together. Ignores elemgens that are not included in the common gauge space. The common gauge space is the intersection of all the individual gauge spaces. TODO: I believe this is done to remove the “trivial”/”meta” gauge from SPAM operations. We should verify this and if so, include it in this docstring

gauge_space_directionsnumpy array

Contains, when applicable, a gauge-space direction that correspondings to the FOGI quantity in fogi_directions. Such a gauge-space direction exists for relational FOGI quantities, where the FOGI quantity is constructed by taking the difference of a gauge-space action (given by the gauge-space direction) on two operations (or sets of operations). TODO: How does one know the corresponding fogi direction? each one of these is computed from fogv_directions.

norm_order : str or int

Defines the order of the norm to normalize FOGI directions. It should be 1 for normalizing ‘S’ quantities and 2 for ‘H’, so ‘auto’ utilizes intelligence.

dependent_fogi_action : ‘drop’ or ‘mark’

If ‘drop’, all linearly dependent FOGI directions are not returned, resulting in a linearly independent set of quantities. If ‘mark’ linearly dependent FOGI directions are kept and marked by dependent_dir_indices.

property errorgen_space_dim

property gauge_space_dim

property num_fogi_directions

property num_fogv_directions

primitive_op_labels

gauge_space

elem_errorgen_labels_by_op

op_errorgen_indices

fogi_directions

fogi_metadata

dependent_dir_indices

fogv_directions

allop_gauge_action

gauge_space_directions

norm_order = "'auto'"

errorgen_space_op_elem_labels

fogv_labels

classmethod from_gauge_action_matrices(gauge_action_matrices_by_op, gauge_action_gauge_spaces_by_op, errorgen_coefficient_labels_by_op, op_label_abbrevs=None, dependent_fogi_action='drop', norm_order='auto')

Receives the matrices describing the individual gauge action of each operation within the gate set, and massages them into appropriate from to be fed into construct_fogi_quantities() which finds FOGI quantities for the corresponding gate set. Aditionally, gauge space vectors are computed, and gauge directions that “correspond” to FOGI quantities are identified. With all of this, a FOGIStore object is created and returned.

Parameters

gauge_action_matrices_by_opdict of Label keys and numpy array values

Gauge action of the primitive operator described by Label. For SPAM, “gauge action” matrix is just the identity on the relevant space of gauge transformations. For gates, it is K - UKU^dag where K is a gauge generator, and U is the ideal gate.

gauge_action_gauge_spaces_by_opdict of Label keys and numpy array values

“Formatted” gauge spaces corresponding to each gauge action from gauge_action_matrices_by_op. This formatting occurs in model.py:_format_gauge_action_matrix() TODO: More details

errorgen_coefficient_labels_by_opdict of Label keys and list of Label values

If indexed by an operation Label, this variable returns a list of error generator labels that identify every row of their corresponding gauge action matrix in gauge_action_matrices_by_op

op_label_abbrevsdict of Label keys with str values

The user is able to fill the values of this dictionary with any strings to represent the operations in the gate set. typically used to choose shorter names to avoid FOGI names that are too long/complicated to read.

norm_order : int or ‘auto’ (Defaults to ‘auto’)

Defines the order of the norm to normalize FOGI directions. It should be 1 for normalizing ‘S’ quantities and 2 for ‘H’, so ‘auto’ utilizes intelligence.

dependent_fogi_action : ‘drop’ or ‘mark’ (Defaults to ‘drop’)

If ‘drop’, all linearly dependent FOGI directions are not returned, resulting in a linearly independent set of quantities. If ‘mark’ linearly dependent FOGI directions are kept and marked by dependent_dir_indices.

find_nice_fogiv_directions()

fogi_errorgen_direction_labels(typ='normal')

typ can be ‘raw’ or ‘abbrev’ too

fogv_errorgen_direction_labels(typ='normal')

errorgen_vec_to_fogi_components_array(errorgen_vec)

errorgen_vec_to_fogv_components_array(errorgen_vec)

opcoeffs_to_fogi_components_array(op_coeffs)

opcoeffs_to_fogv_components_array(op_coeffs)

opcoeffs_to_fogiv_components_array(op_coeffs)

fogi_components_array_to_errorgen_vec(fogi_components)

fogv_components_array_to_errorgen_vec(fogv_components)

fogiv_components_array_to_errorgen_vec(fogi_components, fogv_components)

errorgen_vec_to_opcoeffs(errorgen_vec)

fogi_components_array_to_opcoeffs(fogi_components)

fogv_components_array_to_opcoeffs(fogv_components)

fogiv_components_array_to_opcoeffs(fogi_components, fogv_components)

create_binned_fogi_infos(tol=1e-05)

Creates an ‘info’ dictionary for each FOGI quantity and places it within a nested dictionary structure by the operators involved, the types of error generators, and the qubits acted upon (a.k.a. the “target” qubits). TODO: docstring

Returns

dict

create_elementary_errorgen_space(op_elem_errgen_labels)

Construct a matrix whose column space spans the given list of elementary error generators.

Parameters

op_elem_errgen_labelsiterable

A list of (operation_label, elementary_error_generator_label) tuples, where operation_label is one of the primitive operation labels in self.primitive_op_labels and elementary_error_generator_label is a GlobalElementaryErrorgenLabel object.

Returns

numpy.ndarray

A two-dimensional array of shape (self.errorgen_space_dim, len(op_elem_errgen_labels)). Columns correspond to elements of op_elem_errgen_labels and the rowspace is the full elementary error generator space of this FOGI analysis.

create_fogi_aggregate_space(op_set='all', errorgen_types='all', target='all')

Construct a matrix with columns equal to the FOGI directions within the specified categories.

Projecting a model’s error-generator vector onto such a space can be used to obtain the contribution of a desired subset of the model’s errors.

Parameters

op_settuple or “all”

Restrict to (intrinsic) FOGI quantities of a single operation, given as a 1-tuple, e.g. ((‘Gxpi2’,0),) or relational error between multiple operations, e.g., ((‘Gxpi2’,0), (‘Gypi2’,0)). The special “all” value includes quantities on all operations (no restriction).

errorgen_typestuple of {“H”, “S”} or “all”

Restrict to FOGI quantities containing elementary error generators of the given type(s). Note that a tuple with multiple types only selects FOGI quantities containing all the give types (e.g., (‘H’,’S’) will not match quantities composed of solely Hamiltonian-type generators). The special “all” value includes quantities of all types (no restriction).

targettuple or “all”

A tuple of state space (qubit) labels to restrict to, e.g., (‘Q0’,’Q1’). Note that includeing multiple labels selects only those quantities that target all the labels. The special “all” value includes quantities on all targets (no restriction).

Returns

numpy.ndarray

A two-dimensional array with self.errorgen_space_dim rows and a number of columns dependent on the number of FOGI quantities matching the argument criteria.

create_fogi_aggregate_single_op_space(op_label, errorgen_type='H', intrinsic_or_relational='intrinsic', target='all')

Construct a matrix with columns spanning a particular FOGI subspace for a single operation.

This is a subspace of the full error-generator space of this FOGI analysis, and projecting a model’s error-generator vector onto this space can be used to obtain the contribution of a desired subset of the op_label’s errors.

Parameters

op_labelLabel or str

The operation to construct a subspace for. This should be an element of self.primitive_op_labels.

errorgen_type{“H”, “S”, “all”}

Potentially restrict to the subspace containing just Hamiltonian (H) or Pauli stochastic (S) errors. “all” imposes no restriction.

intrinsic_or_relational{“intrinsic”, “relational”, “all”}

Restrict to intrinsic or relational errors (or not, using “all”).

targettuple or “all”

A tuple of state space (qubit) labels to restrict to, e.g., (‘Q0’,’Q1’). Note that including multiple labels selects only those quantities that target all the labels. The special “all” value includes quantities on all targets (no restriction).

Returns

numpy.ndarray

A two-dimensional array with self.errorgen_space_dim rows and a number of columns dependent on the dimension of the selected subspace.

classmethod merge_binned_fogi_infos(binned_fogi_infos, index_offsets)

Merge together multiple FOGI-info dictionaries created by create_binned_fogi_infos().

Parameters

binned_fogi_infoslist

A list of FOGI-info dictionaries.

index_offsetslist

A list of length len(binned_fogi_infos) that gives the offset into an assumed-to-exist corresponding vector of components for all the FOGI infos.

Returns

dict

The merged dictionary