pytket.utils#

Utility functions for performing high-level procedures in pytket

pytket.utils.append_pauli_measurement(pauli_string: pytket.pauli.QubitPauliString, circ: pytket.circuit.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: numpy.ndarray, second: numpy.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: numpy.ndarray, second: numpy.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: numpy.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: numpy.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: pytket.utils.QubitPauliOperator, reference_state: pytket.circuit.Circuit, partition_strat: pytket.partition.PauliPartitionStrat = PauliPartitionStrat.CommutingSets, colour_method: pytket.partition.GraphColourMethod = GraphColourMethod.Lazy) → pytket.circuit.Circuit#

Sequences QubitPauliOperator terms to generate a circuit made of CircBoxes. Each CircBox contains a sequence of PauliExpBox objects.

Parameters
pytket.utils.get_operator_expectation_value(state_circuit: pytket.circuit.Circuit, operator: pytket.utils.QubitPauliOperator, backend: Backend, n_shots: Optional[int] = None, partition_strat: Optional[pytket.partition.PauliPartitionStrat] = None, colour_method: pytket.partition.GraphColourMethod = GraphColourMethod.LargestFirst, **kwargs: Optional[Union[int, float, str]]) → 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: pytket.circuit.Circuit, pauli: pytket.pauli.QubitPauliString, backend: Backend, n_shots: Optional[int] = 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: numpy.ndarray, permutation: Tuple[int, ...]) → numpy.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: numpy.ndarray, permutation: Tuple[int, ...]) → numpy.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: numpy.ndarray, permutation: Tuple[int, ...]) → numpy.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: pytket.circuit.Circuit, allow_classical: bool = True, xcirc: Optional[pytket.circuit.Circuit] = None) → Tuple[pytket.circuit.Circuit, pytket.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: numpy.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[pytket.utils.OutcomeArray]) → Counter[Tuple[int, ...]]#

Convert counts from OutcomeArray types to tuples of ints.

class pytket.utils.OutcomeArray(input_array: numpy.ndarray, 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]) → pytket.utils.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[pytket.utils.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]) → pytket.utils.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) → pytket.utils.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: Union[numpy._typing._array_like._SupportsArray[numpy.dtype[Any]], numpy._typing._nested_sequence._NestedSequence[numpy._typing._array_like._SupportsArray[numpy.dtype[Any]]], bool, int, float, complex, str, bytes, numpy._typing._nested_sequence._NestedSequence[Union[bool, int, float, complex, str, bytes]]]) → pytket.utils.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() → numpy.ndarray#

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

to_readouts() → numpy.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: Optional[Dict[pytket.pauli.QubitPauliString, Union[int, float, complex, sympy.core.expr.Expr]]] = 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: Optional[Dict[pytket.pauli.QubitPauliString, Union[int, float, complex, sympy.core.expr.Expr]]] = 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: numpy.ndarray, qubits: Optional[List[pytket.circuit.Qubit]] = None) → numpy.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]]) → pytket.utils.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: numpy.ndarray, qubits: Optional[List[pytket.circuit.Qubit]] = 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[sympy.core.symbol.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: Optional[Union[List[pytket.circuit.Qubit], int]] = 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[pytket.circuit.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: pytket.circuit.Circuit)#
__init__(c: pytket.circuit.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() → networkx.classes.multidigraph.MultiDiGraph#

Return a logical representation of the circuit as a DAG.

Returns

Representation of the DAG

Return type

networkx.MultiDiGraph

get_DAG() → graphviz.graphs.Digraph#

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

Returns

Representation of the DAG

Return type

graphviz.DiGraph

get_qubit_graph() → graphviz.graphs.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[pytket.utils.distribution.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: pytket.utils.distribution.EmpiricalDistribution[pytket.utils.distribution.T0]) → pytket.utils.distribution.EmpiricalDistribution[pytket.utils.distribution.T0]#

Combine two distributions.

__eq__(other: object) → bool#

Compare distributions for equality.

__getitem__(x: pytket.utils.distribution.T0) → int#

Get the count associated with an observation.

as_counter() → Counter[pytket.utils.distribution.T0]#

Return the distribution as a collections.Counter object.

condition(criterion: Callable[[pytket.utils.distribution.T0], bool]) → pytket.utils.distribution.EmpiricalDistribution[pytket.utils.distribution.T0]#

Return a new distribution conditioned on the given criterion.

Parameters

criterion – A boolean function defined on all possible observations.

map(mapping: Callable[[pytket.utils.distribution.T0], pytket.utils.distribution.T1]) → pytket.utils.distribution.EmpiricalDistribution[pytket.utils.distribution.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[[pytket.utils.distribution.T0], Union[float, complex]]) → Union[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[[pytket.utils.distribution.T0], Union[float, complex]]) → Union[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[pytket.utils.distribution.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[pytket.utils.distribution.T0, float])#

Represents an exact probability distribution.

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

__getitem__(x: pytket.utils.distribution.T0) → float#

Get the probability associated with a possible outcome.

as_dict() → Dict[pytket.utils.distribution.T0, float]#

Return the distribution as a dict object.

as_rv_discrete() → Tuple[scipy.stats._distn_infrastructure.rv_discrete, List[pytket.utils.distribution.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[[pytket.utils.distribution.T0], bool]) → pytket.utils.distribution.ProbabilityDistribution[pytket.utils.distribution.T0]#

Return a new distribution conditioned on the given criterion.

Parameters

criterion – A boolean function defined on all possible outcomes.

expectation(f: Callable[[pytket.utils.distribution.T0], Union[float, complex]]) → Union[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: pytket.utils.distribution.EmpiricalDistribution[pytket.utils.distribution.T0]) → pytket.utils.distribution.ProbabilityDistribution[pytket.utils.distribution.T0]#

Estimate a probability distribution from an empirical distribution.

map(mapping: Callable[[pytket.utils.distribution.T0], pytket.utils.distribution.T1]) → pytket.utils.distribution.ProbabilityDistribution[pytket.utils.distribution.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[[pytket.utils.distribution.T0], Union[float, complex]]) → Union[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[pytket.utils.distribution.T0]#

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

pytket.utils.distribution.convex_combination(dists: List[Tuple[pytket.utils.distribution.ProbabilityDistribution[pytket.utils.distribution.T0], float]]) → pytket.utils.distribution.ProbabilityDistribution[pytket.utils.distribution.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]#

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[pytket.circuit.Node]], backend: Optional[pytket.backends.Backend] = 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[pytket.circuit.Node]], backend: Optional[pytket.backends.Backend] = 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[pytket.backends.backendresult.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[pytket.circuit.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: pytket.backends.backendresult.BackendResult, parallel_measures: List[Dict[pytket.circuit.Qubit, pytket.circuit.Bit]], method: str = 'bayesian', options: Optional[Dict] = None) → pytket.backends.backendresult.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) → pytket.utils.spam.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: pytket.circuit.Circuit) → List[Dict[pytket.circuit.Qubit, pytket.circuit.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.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: pytket.circuit.OpType) → Callable[[List[Union[sympy.core.expr.Expr, float]]], sympy.matrices.immutable.ImmutableDenseMatrix]#

Get registered callable.

classmethod is_registered(typ: pytket.circuit.OpType) → bool#

Check if type has a callable registered.

classmethod register_func(typ: pytket.circuit.OpType, f: Callable[[List[Union[sympy.core.expr.Expr, float]]], sympy.matrices.immutable.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: pytket.circuit.Circuit, input_qb: sympy.core.expr.Expr) → sympy.physics.quantum.qubit.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: pytket.circuit.Circuit, input_state: Optional[Union[numpy.ndarray, sympy.matrices.immutable.ImmutableDenseMatrix]] = None) → sympy.matrices.immutable.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: pytket.circuit.Circuit) → sympy.core.mul.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: pytket.circuit.Circuit) → sympy.matrices.immutable.ImmutableDenseMatrix#

Generate a symbolic unitary from Circuit.

Unitary matches pytket default ILO BasisOrder.

Parameters

circ (Circuit) – Input circuit

Returns

Symbolic unitary.

Return type

ImmutableMatrix