pytket.utils

Utility functions for performing high-level procedures in pytket

pytket.utils.append_pauli_measurement(pauli_string: QubitPauliString, circ: Circuit) → None

Appends measurement instructions to a given circuit, measuring each qubit in a given basis.

Parameters:

• pauli_string (QubitPauliString) – The pauli string to measure

• circ (Circuit) – Circuit to add measurement to.

pytket.utils.compare_statevectors(first: ndarray, second: ndarray) → bool

Check approximate equality up to global phase for statevectors.

Parameters:

• first (np.ndarray) – First statevector.

• second (np.ndarray) – Second statevector.

Returns:

Approximate equality.

Return type:

bool

pytket.utils.compare_unitaries(first: ndarray, second: ndarray) → bool

Check approximate equality up to global phase for unitaries.

Parameters:

• first (np.ndarray) – First unitary.

• second (np.ndarray) – Second unitary.

Returns:

Approximate equality.

Return type:

bool

pytket.utils.counts_from_shot_table(shot_table: ndarray) → Dict[Tuple[int, ...], int]

Summarises a shot table into a dictionary of counts for each observed outcome.

Parameters:

shot_table (np.ndarray) – Table of shots from a pytket backend.

Returns:

Dictionary mapping observed readouts to the number of times observed.

Return type:

Dict[Tuple[int, …], int]

pytket.utils.expectation_from_counts(counts: Dict[Tuple[int, ...], int]) → float

Estimates the expectation value of a circuit from shot counts. Computes the parity of ‘1’s across all bits to determine a +1 or -1 contribution from each readout, and returns the weighted average.

Parameters:

counts (Dict[Tuple[int, ...], int]) – Counts of each measurement outcome observed.

Returns:

The expectation value in the range [-1, 1].

Return type:

float

pytket.utils.expectation_from_shots(shot_table: ndarray) → float

Estimates the expectation value of a circuit from its shots. Computes the parity of ‘1’s across all bits to determine a +1 or -1 contribution from each row, and returns the average.

Parameters:

shot_table (np.ndarray) – The table of shots to interpret.

Returns:

The expectation value in the range [-1, 1].

Return type:

float

pytket.utils.gen_term_sequence_circuit(operator: QubitPauliOperator, reference_state: Circuit, partition_strat: PauliPartitionStrat = PauliPartitionStrat.CommutingSets, colour_method: GraphColourMethod = GraphColourMethod.Lazy) → Circuit

Sequences the terms of a QubitPauliOperator \(P\) to generate a circuit approximating \(e^{i \frac{\pi}{2} P}\). This method performs Trotterisation on \(P\) with a single Trotter step.

This method uses a given partitioning strategy and a graph colouring

method for term sequencing.

The resulting Circuit will contain a sequence of CircBoxes. Each CircBox corresponds to a set of Pauli strings. Each exponentiated Pauli string in the set is realised as a PauliExpBox.

The ordering of terms prioritises reducing the two qubit gate count of the circuit when the PauliSimp or GuidedPauliSimp passes are applied rather than minimising the trotter error.

Parameters:

• operator (QubitPauliOperator) – The operator terms to sequence

• reference_state (Circuit) – reference state to add sequenced terms to.

• partition_strat (PauliPartitionStrat, Optional) – a Partition strategy

• colour_method (GraphColourMethod, Optional) – a graph colouring method

pytket.utils.get_operator_expectation_value(state_circuit: Circuit, operator: QubitPauliOperator, backend: Backend, n_shots: int | None = None, partition_strat: PauliPartitionStrat | None = None, colour_method: GraphColourMethod = GraphColourMethod.LargestFirst, **kwargs: int | float | str | None) → complex

Estimates the expectation value of the given circuit with respect to the operator based on its individual Pauli terms. If the QubitPauliOperator has symbolic values the expectation value will also be symbolic. The input circuit must belong to the default qubit register and have contiguous qubit ordering.

Parameters:

• state_circuit (Circuit) – Circuit that generates the desired state \(\left|\psi\right>\)

• operator (QubitPauliOperator) – Operator \(H\). Currently does not support free symbols for the purpose of obtaining expectation values.

• backend (Backend) – pytket backend to run circuit on.

• n_shots (Optional[int], optional) – Number of shots to run if backend supports shots/counts. None will force the backend to give the full state if available. Defaults to None

• partition_strat (Optional[PauliPartitionStrat], optional) – If retrieving shots, can perform measurement reduction using a chosen strategy

Returns:

\(\left<\psi | H | \psi \right>\)

Return type:

complex

pytket.utils.get_pauli_expectation_value(state_circuit: Circuit, pauli: QubitPauliString, backend: Backend, n_shots: int | None = None) → complex

Estimates the expectation value of the given circuit with respect to the Pauli term by preparing measurements in the appropriate basis, running on the backend and interpreting the counts/statevector

Parameters:

• state_circuit (Circuit) – Circuit that generates the desired state \(\left|\psi\right>\).

• pauli (QubitPauliString) – Pauli operator

• backend (Backend) – pytket backend to run circuit on.

• n_shots (Optional[int], optional) – Number of shots to run if backend supports shots/counts. Set to None to calculate using statevector if supported by the backend. Defaults to None

Returns:

\(\left<\psi | P | \psi \right>\)

Return type:

float

pytket.utils.permute_basis_indexing(matrix: ndarray, permutation: Tuple[int, ...]) → ndarray

Rearranges the first dimensions of an array (statevector or unitary)

according to a permutation of the bit indices in the binary representation of row indices.

Parameters:

• matrix (np.ndarray) – Original unitary matrix

• permutation (Tuple[int, ...]) – Map from current qubit index (big-endian) to its new position, encoded as a list

Returns:

Updated unitary matrix

Return type:

np.ndarray

pytket.utils.permute_qubits_in_statevector(state: ndarray, permutation: Tuple[int, ...]) → ndarray

Rearranges a statevector according to a permutation of the qubit indices.

>>> # A 3-qubit state:
>>> state = np.array([0.0, 0.0625, 0.1875, 0.25, 0.375, 0.4375, 0.5, 0.5625])
>>> permutation = [1, 0, 2] # swap qubits 0 and 1
>>> # Apply the permutation that swaps indices 2 (="010") and 4 (="100"), and swaps
>>> # indices 3 (="011") and 5 (="101"):
>>> permute_qubits_in_statevector(state, permutation)
array([0.    , 0.0625, 0.375 , 0.4375, 0.1875, 0.25  , 0.5   , 0.5625])

Parameters:

• state (np.ndarray) – Original statevector.

• permutation (Tuple[int, ...]) – Map from current qubit index (big-endian) to its new position, encoded as a list.

Returns:

Updated statevector.

Return type:

np.ndarray

pytket.utils.permute_rows_cols_in_unitary(matrix: ndarray, permutation: Tuple[int, ...]) → ndarray

Rearranges the rows of a unitary matrix according to a permutation of the qubit indices.

Parameters:

• matrix (np.ndarray) – Original unitary matrix

• permutation (Tuple[int, ...]) – Map from current qubit index (big-endian) to its new position, encoded as a list

Returns:

Updated unitary matrix

Return type:

np.ndarray

pytket.utils.prepare_circuit(circ: Circuit, allow_classical: bool = True, xcirc: Circuit | None = None) → Tuple[Circuit, Circuit]

Prepare a circuit for processing by a backend device.

This method first makes all inputs into Create operations (assuming an initial all- zero state) and all outputs into Discard operations (so that the circuit can no longer be usefully extended or appended to another circuit). It then attempts to apply various simplifications that take advantage of the known initial state and the fact that any unmeasured state is discarded. Finally, it separates the circuit into two circuits, the first of which is to be run on the backend (after any further compilation has been applied), and the second of which is a pure-classical circuit (on the same bits) which encodes classical post-processing of the measurement results. This post-processing is applied automatically when you pass the classical circuit as the ppcirc argument to BackendResult.get_counts() or BackendResult.get_shots().

The original circuit is not modified by this method.

Parameters:

• circ – input circuit

• allow_classical – allow insertion of mid-circuit classical operations?

• xcirc – 1-qubit circuit implementing an X gate in the transformed circuit (if omitted, an X gate is used)

Returns:

(c0, ppcirc) where c0 is the simplified circuit and ppcirc should be passed to BackendResult.get_counts() or BackendResult.get_shots() when retrieving the final results.

pytket.utils.probs_from_counts(counts: Dict[Tuple[int, ...], int]) → Dict[Tuple[int, ...], float]

Converts raw counts of observed outcomes into the observed probability distribution.

Parameters:

counts (Dict[Tuple[int, ...], int]) – Dictionary mapping observed readouts to the number of times observed.

Returns:

Probability distribution over observed readouts.

Return type:

Dict[Tuple[int, …], float]

pytket.utils.probs_from_state(state: ndarray, min_p: float = 1e-10) → Dict[Tuple[int, ...], float]

Converts statevector to the probability distribution over readouts in the computational basis. Ignores probabilities lower than min_p.

Parameters:

• state (np.ndarray) – Full statevector with big-endian encoding.

• min_p (float) – Minimum probability to include in result

Returns:

Probability distribution over readouts.

Return type:

Dict[Tuple[int], float]

pytket.utils.readout_counts(ctr: Counter[OutcomeArray]) → Counter[Tuple[int, ...]]

Convert counts from OutcomeArray types to tuples of ints.

class pytket.utils.OutcomeArray(input_array: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], width: int)

Array of measured outcomes from qubits. Derived class of numpy.ndarray.

Bitwise outcomes are compressed into unsigned 8-bit integers, each representing up to 8 qubit measurements. Each row is a repeat measurement.

Parameters:

• width (int) – Number of bit entries stored, less than or equal to the bit capacity of the array.

• n_outcomes (int) – Number of outcomes stored.

choose_indices(indices: List[int]) → OutcomeArray

Permute ordering of bits in outcomes or choose subset of bits. e.g. [1, 0, 2] acting on a bitstring of length 4 swaps bit locations 0 & 1, leaves 2 in the same place and deletes location 3.

Parameters:

indices (List[int]) – New locations for readout bits.

Returns:

New array corresponding to given permutation.

Return type:

OutcomeArray

counts() → Counter[OutcomeArray]

Calculate counts of outcomes in OutcomeArray

Returns:

Counter of outcome, number of instances

Return type:

Counter[OutcomeArray]

classmethod from_dict(ar_dict: Dict[str, Any]) → OutcomeArray

Create an OutcomeArray from JSON serializable dictionary (as created by to_dict).

Parameters:

dict – Dictionary representation of OutcomeArray.

Returns:

Instance of OutcomeArray

Return type:

OutcomeArray

classmethod from_ints(ints: Sequence[int], width: int, big_endian: bool = True) → OutcomeArray

Create OutcomeArray from iterator of integers corresponding to outcomes

where the bitwise representation of the integer corresponds to the readouts.

Parameters:

• ints (Iterable[int]) – Iterable of outcome integers

• width (int) – Number of qubit measurements

• big_endian (bool, optional) – whether to use big endian encoding (or little endian if False), defaults to True

Returns:

OutcomeArray instance

Return type:

OutcomeArray

classmethod from_readouts(readouts: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) → OutcomeArray

Create OutcomeArray from a 2D array like object of read-out integers, e.g. [[1, 1, 0], [0, 1, 1]]

to_dict() → Dict[str, Any]

Return a JSON serializable dictionary representation of the OutcomeArray.

Returns:

JSON serializable dictionary

Return type:

Dict[str, Any]

to_intlist(big_endian: bool = True) → List[int]

Express each outcome as an integer corresponding to the bit values.

Parameters:

big_endian (bool, optional) – whether to use big endian encoding (or little endian if False), defaults to True

Returns:

List of integers, each corresponding to an outcome.

Return type:

List[int]

to_readout() → ndarray

Convert a singleton to a single readout (1D array)

to_readouts() → ndarray

Convert OutcomeArray to a 2D array of readouts, each row a separate outcome and each column a bit value.

property n_outcomes: Any

Number of outcomes stored.

property width: int

Number of bit entries stored, less than or equal to the bit capacity of the array.

class pytket.utils.QubitPauliOperator(dictionary: Dict[QubitPauliString, int | float | complex | Expr] | None = None)

Generic data structure for generation of circuits and expectation value calculation. Contains a dictionary from QubitPauliString to sympy Expr. Capacity for symbolic expressions allows the operator to be used to generate ansätze for variational algorithms.

Represents a mathematical object \(\sum_j \alpha_j P_j\), where each \(\alpha_j\) is a complex symbolic expression and \(P_j\) is a Pauli string, i.e. \(P_j \in \{ I, X, Y, Z\}^{\otimes n}\).

A prototypical example is a molecular Hamiltonian, for which one may wish to calculate the expectation value \(\langle \Psi | H | \Psi \rangle\) by decomposing \(H\) into individual Pauli measurements. Alternatively, one may wish to evolve a state by the operator \(e^{-iHt}\) for digital quantum simulation. In this case, the whole operator must be decomposed into native operations.

In both cases, \(H\) may be represented by a QubitPauliOperator.

__init__(dictionary: Dict[QubitPauliString, int | float | complex | Expr] | None = None) → None

compress(abs_tol: float = 1e-10) → None

Substitutes all free symbols in the QubitPauliOperator with 1, and then removes imaginary and real components which have magnitudes below the tolerance. If the resulting expression is 0, the term is removed entirely.

Warning: This methods assumes significant expression structure is known a priori, and is best suited to operators which have simple product expressions, such as excitation operators for VQE ansätze and digital quantum simulation. Otherwise, it may remove terms relevant to computation. Each expression is of the form \(f(a_1,a_2,\ldots,a_n)\) for some symbols \(a_i\). \(|f(a_1,a_2,\ldots,a_n)|\) is assumed to monotonically increase in both real and imaginary components for all \(a_i \in [0, 1]\).

Parameters:

abs_tol (float) – The threshold below which to remove values.

dot_state(state: ndarray, qubits: List[Qubit] | None = None) → ndarray

Applies the operator to the given state, mapping qubits to indexes according to qubits.

• When qubits is an explicit list, the qubits are ordered with qubits[0] as the most significant qubit for indexing into state.

• If None, qubits sequentially indexed from 0 in the default register and ordered by ILO-BE so Qubit(0) is the most significant.

Parameters:

• state (numpy.ndarray) – The initial statevector

• qubits (Union[List[Qubit], None], optional) – Sequencing of qubits in state, if not mapped to the default register. Defaults to None

Returns:

The dot product of the operator with the statevector

Return type:

numpy.ndarray

classmethod from_list(pauli_list: List[Dict[str, Any]]) → QubitPauliOperator

Construct a QubitPauliOperator from a serializable JSON list format, as returned by QubitPauliOperator.to_list()

Returns:

New QubitPauliOperator instance.

Return type:

QubitPauliOperator

state_expectation(state: ndarray, qubits: List[Qubit] | None = None) → complex

Calculates the expectation value of the given statevector with respect to the operator, mapping qubits to indexes according to qubits.

• When qubits is an explicit list, the qubits are ordered with qubits[0] as the most significant qubit for indexing into state.

• If None, qubits sequentially indexed from 0 in the default register and ordered by ILO-BE so Qubit(0) is the most significant.

Parameters:

• state (numpy.ndarray) – The initial statevector

• qubits (Union[List[Qubit], None], optional) – Sequencing of qubits in state, if not mapped to the default register. Defaults to None

Returns:

The expectation value of the statevector and operator

Return type:

complex

subs(symbol_dict: Dict[Symbol, complex]) → None

Substitutes any matching symbols in the QubitPauliOperator.

Parameters:

symbol_dict (Dict[Symbol, complex]) – A dictionary of symbols to fixed values.

to_list() → List[Dict[str, Any]]

Generate a list serialized representation of QubitPauliOperator,

suitable for writing to JSON.

Returns:

JSON serializable list of dictionaries.

Return type:

List[Dict[str, Any]]

to_sparse_matrix(qubits: List[Qubit] | int | None = None) → csc_matrix

Represents the sparse operator as a dense operator under the ordering scheme specified by qubits, and generates the corresponding matrix.

• When qubits is an explicit list, the qubits are ordered with qubits[0] as the most significant qubit for indexing into the matrix.

• If None, then no padding qubits are introduced and we use the ILO-BE convention, e.g. Qubit("a", 0) is more significant than Qubit("a", 1) or Qubit("b").

• Giving a number specifies the number of qubits to use in the final operator, treated as sequentially indexed from 0 in the default register (padding with identities as necessary) and ordered by ILO-BE so Qubit(0) is the most significant.

Parameters:

qubits (Union[List[Qubit], int, None], optional) – Sequencing of qubits in the matrix, either as an explicit list, number of qubits to pad to, or infer from the operator. Defaults to None

Returns:

A sparse matrix representation of the operator.

Return type:

csc_matrix

property all_qubits: Set[Qubit]

Returns:

The set of all qubits the operator ranges over (including qubits that were provided explicitly as identities)

Return type:

Set[Qubit]

class pytket.utils.Graph(c: Circuit)

__init__(c: Circuit)

A class for visualising a circuit as a directed acyclic graph (DAG).

Note: in order to use graph-rendering methods, such as Graph.save_DAG(), it is necessary to have the Graphviz tools installed and on your path. See the Graphviz website for instructions on how to install them.

Parameters:

c (pytket.Circuit) – Circuit

as_nx() → MultiDiGraph

Return a logical representation of the circuit as a DAG.

Returns:

Representation of the DAG

Return type:

networkx.MultiDiGraph

get_DAG() → Digraph

Return a visual representation of the DAG as a graphviz object.

Returns:

Representation of the DAG

Return type:

graphviz.DiGraph

get_qubit_graph() → Graph

Return a visual representation of the qubit connectivity graph as a graphviz object.

Returns:

Representation of the qubit connectivity graph of the circuit

Return type:

graphviz.Graph

save_DAG(name: str, fmt: str = 'pdf') → None

Save an image of the DAG to a file.

The actual filename will be “<name>.<fmt>”. A wide range of formats is supported. See https://graphviz.org/doc/info/output.html.

Parameters:

• name (str) – Prefix of file name

• fmt (str) – File format, e.g. “pdf”, “png”, …

save_qubit_graph(name: str, fmt: str = 'pdf') → None

Save an image of the qubit connectivity graph to a file.

The actual filename will be “<name>.<fmt>”. A wide range of formats is supported. See https://graphviz.org/doc/info/output.html.

Parameters:

• name (str) – Prefix of file name

• fmt (str) – File format, e.g. “pdf”, “png”, …

view_DAG() → str

View the DAG.

This method creates a temporary file, and returns its filename so that the caller may delete it afterwards.

Returns:

filename of temporary created file

view_qubit_graph() → str

View the qubit connectivity graph.

This method creates a temporary file, and returns its filename so that the caller may delete it afterwards.

Returns:

filename of temporary created file

pytket.utils.distribution

class pytket.utils.distribution.EmpiricalDistribution(C: Counter[T0])

Represents an empirical distribution of values.

Supports methods for combination, marginalization, expectation value, etc.

>>> dist1 = EmpiricalDistribution(Counter({(0, 0): 3, (0, 1): 2, (1, 0): 4, (1, 1):
... 0}))
>>> dist2 = EmpiricalDistribution(Counter({(0, 0): 1, (0, 1): 0, (1, 0): 2, (1, 1):
... 1}))
>>> dist1.sample_mean(lambda x : x[0] + 2*x[1])
0.8888888888888888
>>> dist3 = dist2.condition(lambda x: x[0] == 1)
>>> dist3
EmpiricalDistribution(Counter({(1, 0): 2, (1, 1): 1}))
>>> dist4 = dist1 + dist3
>>> dist4
EmpiricalDistribution(Counter({(1, 0): 6, (0, 0): 3, (0, 1): 2, (1, 1): 1}))

__add__(other: EmpiricalDistribution[T0]) → EmpiricalDistribution[T0]

Combine two distributions.

__eq__(other: object) → bool

Compare distributions for equality.

__getitem__(x: T0) → int

Get the count associated with an observation.

as_counter() → Counter[T0]

Return the distribution as a collections.Counter object.

condition(criterion: Callable[[T0], bool]) → EmpiricalDistribution[T0]

Return a new distribution conditioned on the given criterion.

Parameters:

criterion – A boolean function defined on all possible observations.

map(mapping: Callable[[T0], T1]) → EmpiricalDistribution[T1]

Return a distribution over a transformed domain.

The provided function maps elements in the original domain to new elements. If it is not injective, counts are combined.

Parameters:

mapping – A function defined on all possible observations, mapping them to another domain.

sample_mean(f: Callable[[T0], float | complex]) → float | complex

Compute the sample mean of a functional.

The provided function maps observations to numerical values.

Returns:

Estimate of the mean of the functional based on the observations.

sample_variance(f: Callable[[T0], float | complex]) → float | complex

Compute the sample variance of a functional.

The provided function maps observations to numerical values.

The sample variance is an unbiased estimate of the variance of the underlying distribution.

Returns:

Estimate of the variance of the functional based on the observations.

property support: Set[T0]

Return the support of the distribution (set of all observations).

property total: int

Return the total number of observations.

class pytket.utils.distribution.ProbabilityDistribution(P: Dict[T0, float], min_p: float = 0.0)

Represents an exact probability distribution.

Supports methods for combination, marginalization, expectation value, etc. May be derived from an EmpriricalDistribution.

__getitem__(x: T0) → float

Get the probability associated with a possible outcome.

as_dict() → Dict[T0, float]

Return the distribution as a dict object.

as_rv_discrete() → Tuple[rv_discrete, List[T0]]

Return the distribution as a scipy.stats.rv_discrete object.

This method returns an RV over integers {0, 1, …, k-1} where k is the size of the support, and a list whose i’th member is the item corresponding to the value i of the RV.

condition(criterion: Callable[[T0], bool]) → ProbabilityDistribution[T0]

Return a new distribution conditioned on the given criterion.

Parameters:

criterion – A boolean function defined on all possible outcomes.

expectation(f: Callable[[T0], float | complex]) → float | complex

Compute the expectation value of a functional.

The provided function maps possible outcomes to numerical values.

Returns:

Expectation of the functional.

classmethod from_empirical_distribution(ed: EmpiricalDistribution[T0]) → ProbabilityDistribution[T0]

Estimate a probability distribution from an empirical distribution.

map(mapping: Callable[[T0], T1]) → ProbabilityDistribution[T1]

Return a distribution over a transformed domain.

The provided function maps elements in the original domain to new elements. If it is not injective, probabilities are combined.

Parameters:

mapping – A function defined on all possible outcomes, mapping them to another domain.

variance(f: Callable[[T0], float | complex]) → float | complex

Compute the variance of a functional.

The provided function maps possible outcomes to numerical values.

Returns:

Variance of the functional.

property support: Set[T0]

Return the support of the distribution (set of all possible outcomes).

pytket.utils.distribution.convex_combination(dists: List[Tuple[ProbabilityDistribution[T0], float]]) → ProbabilityDistribution[T0]

Return a convex combination of probability distributions.

Each pair in the list comprises a distribution and a weight. The weights must be non-negative and sum to 1.

>>> dist1 = ProbabilityDistribution({0: 0.25, 1: 0.5, 2: 0.25})
>>> dist2 = ProbabilityDistribution({0: 0.5, 1: 0.5})
>>> dist3 = convex_combination([(dist1, 0.25), (dist2, 0.75)])
>>> dist3
ProbabilityDistribution({0: 0.4375, 1: 0.5, 2: 0.0625})
>>> dist3.expectation(lambda x : x**2)
0.75

pytket.utils.spam

pytket.utils.spam.compress_counts(counts: Dict[Tuple[int, ...], float], tol: float = 1e-06, round_to_int: bool = False) → Dict[Tuple[int, ...], int | float]

Filter counts to remove states that have a count value (which can be a floating-point number) below a tolerance, and optionally round to an integer.

Parameters:

• counts (Dict[StateTuple, float]) – Input counts

• tol (float, optional) – Value below which counts are pruned. Defaults to 1e-6.

• round_to_int (bool, optional) – Whether to round each count to an integer. Defaults to False.

Returns:

Filtered counts

Return type:

CountsDict

class pytket.utils.spam.SpamCorrecter(qubit_subsets: List[List[Node]], backend: Backend | None = None)

A class for generating “state preparation and measurement” (SPAM) calibration experiments for pytket backends, and correcting counts generated from them.

Supports saving calibrated state to a dictionary format, and restoring from the dictionary.

__init__(qubit_subsets: List[List[Node]], backend: Backend | None = None)

Construct a new SpamCorrecter.

Parameters:

• qubit_subsets (List[List[Node]]) – A list of lists of correlated Nodes of an Architecture. Qubits within the same list are assumed to only have SPAM errors correlated with each other. Thus to allow SPAM errors between all qubits you should provide a single list.

• backend – Backend on which the experiments are intended to be run (optional). If provided, the qubits in qubit_subsets must be nodes in the backend’s associated Architecture. If not provided, it is assumed that the experiment will be run on an Architecture`with the nodes in `qubit_subsets, and furthermore that the intended architecture natively supports X gates.

Raises:

ValueError – There are repeats in the qubit_subsets specification.

calculate_matrices(results_list: List[BackendResult]) → None

Calculate the calibration matrices from the results of running calibration circuits.

Parameters:

results_list – List of results from Backend. Must be in the same order as the corresponding circuits generated by calibration_circuits.

Raises:

RuntimeError – Calibration circuits have not been generated yet.

calibration_circuits() → List[Circuit]

Generate calibration circuits according to the specified correlations.

Returns:

A list of calibration circuits to be run on the machine. The circuits should be processed without compilation. Results from these circuits must be given back to this class (via the calculate_matrices method) in the same order.

Return type:

List[Circuit]

correct_counts(result: BackendResult, parallel_measures: List[Dict[Qubit, Bit]], method: str = 'bayesian', options: Dict | None = None) → BackendResult

Modifies count distribution for result, such that the inversion of the pure noise map represented by characterisation matrices is applied to it.

Parameters:

• result (BackendResult) – BackendResult object to be negated by pure noise object.

• parallel_measures (ParallelMeasures) – Used to permute corresponding BackendResult object so counts order matches noise characterisation and to amend characterisation matrices to correct the right bits. SpamCorrecter.get_parallel_measure returns the required object for a given circuit.

Raises:

ValueError – Measured qubit in result not characterised.

Returns:

A new result object with counts modified to reflect SPAM correction.

Return type:

BackendResult

classmethod from_dict(d: Dict) → SpamCorrecter

Build a SpamCorrecter instance from a dictionary in the format returned by to_dict.

Returns:

Dictionary of calibration information.

Return type:

SpamCorrecter

get_parallel_measure(circuit: Circuit) → List[Dict[Qubit, Bit]]

For a given circuit, produces and returns a ParallelMeasures object required

for correcting counts results.

Parameters:

circuit (Circuit) – Circuit with some Measure operations.

Returns:

A list of dictionaries mapping Qubit to Bit where each separate dictionary details some set of Measurement operations run in parallel.

Return type:

ParallelMeasures

to_dict() → Dict

Get calibration information as a dictionary.

Returns:

Dictionary output

Return type:

Dict

pytket.utils.stats

pytket.utils.stats.gate_counts(circ: Circuit) → Counter[OpType]

Count the number of gates of each type in a circuit.

Parameters:

circ – circuit

Returns:

count of gates of each type

pytket.utils.symbolic

Collection of methods to calculate symbolic statevectors and unitaries, for symbolic circuits. This uses the sympy.physics.quantum module and produces sympy objects. The implementations are slow and scale poorly, so this is only suitable for very small (up to 5 qubit) circuits.

class pytket.utils.symbolic.SymGateRegister

Static class holding mapping from OpType to callable generating symbolic matrix. Allows users to add their own definitions, or override existing definitions.

classmethod get_func(typ: OpType) → Callable[[List[Expr | float]], ImmutableDenseMatrix]

Get registered callable.

classmethod is_registered(typ: OpType) → bool

Check if type has a callable registered.

classmethod register_func(typ: OpType, f: Callable[[List[Expr | float]], ImmutableDenseMatrix], replace: bool = False) → None

Register a callable for an optype.

Parameters:

• typ (OpType) – OpType to register

• f (SymGateFunc) – Callable for generating symbolic matrix.

• replace (bool, optional) – Whether to replace existing entry, defaults to False

pytket.utils.symbolic.circuit_apply_symbolic_qubit(circ: Circuit, input_qb: Expr) → Qubit

Apply circuit to an input state to calculate output symbolic state.

Parameters:

• circ (Circuit) – Input Circuit.

• input_qb (Expr) – Sympy Qubit expression corresponding to a state.

Returns:

Output state after circuit acts on input_qb.

Return type:

Qubit

pytket.utils.symbolic.circuit_apply_symbolic_statevector(circ: Circuit, input_state: ndarray | ImmutableDenseMatrix | None = None) → ImmutableDenseMatrix

Apply circuit to an optional input statevector to calculate output symbolic statevector. If no input statevector given, the all zero state is assumed. Statevector follows pytket default ILO BasisOrder.

Parameters:

• circ (Circuit) – Input Circuit.

• input_state (Optional[Union[np.ndarray, ImmutableMatrix]], optional) – Input statevector as a column vector, defaults to None.

Returns:

Symbolic state after circ acts on input_state.

Return type:

ImmutableMatrix

pytket.utils.symbolic.circuit_to_symbolic_gates(circ: Circuit) → Mul

Generate a multiplication expression of sympy gates from Circuit

Parameters:

circ (Circuit) – Input circuit

Raises:

ValueError – If circ does not match a unitary operation.

Returns:

Symbolic gate multiplication expression.

Return type:

Mul

pytket.utils.symbolic.circuit_to_symbolic_unitary(circ: Circuit) → ImmutableDenseMatrix

Generate a symbolic unitary from Circuit.

Unitary matches pytket default ILO BasisOrder.

Parameters:

circ (Circuit) – Input circuit

Returns:

Symbolic unitary.

Return type:

ImmutableMatrix