Defines the StabilizerState and StabilizerFrame classes

Module Contents



Encapsulates a stabilizer frame (linear combo of stabilizer states).



Computes a tensor-product StabilizerFrame from a set of factors.

class pygsti.evotypes.stabilizer_slow.stabilizer.StabilizerFrame(state_s, state_ps=None, amps=None)

Bases: object

Encapsulates a stabilizer frame (linear combo of stabilizer states).

Stores stabilizer elements in the first n, and antistabilizer elements in the latter n columns of the “state matrix” (to facilitate composition), and phase vectors & amplitudes in parallel arrays.

  • state_s (numpy.ndarray) – A 2n x 2n binary matrix, where n is the number of qubits. The first n columns specify stabilizer elements and the latter n colunns specify anti-stabilizer elements. In each column, bits (i,i+n) encode a Pauli on the i-th qubit: 00 = I, 10 = X, 01 = Z, 11 = -iY. (Note the -iY is different from some representations in the literature which encode 11 = Y.)

  • state_ps (numpy.ndarray, optional) – A mod-4 array of shape (k,2n) where n is the number of qubits and k is the number of components in the stabilizer frame. Each row of state_ps is the phase vector for the corresponding to to an amplitude in amps. A phase vector encodes the overall phase of each of the stabilizer and anti-stabilizer elements (the columns of state_s) by specyfing the number of ‘i’ factors (0 to 3). If None, then no phase vectors are stored.

  • amps (numpy.ndarray, optional) – The (complex) amplitudes for each stabilizer-state component of the frame. The length of this 1D array must equal ‘k’, the first dimension of state_ps. amps should be None when and only when state_ps is None, corresponding to the case of zero components.


The number of qubits in the state this frame represents



classmethod from_zvals(cls, nqubits=None, zvals=None)

Create a StabilizerFrame for a computational basis state.

  • nqubits (int, optional) – The number of qubits. If None, inferred from the length of zvals.

  • zvals (iterable, optional) – An iterable over anything that can be cast as True/False to indicate the 0/1 value of each qubit in the Z basis. If None, the all-zeros state is created.



to_rep(self, state_space)

Return a “representation” object for this StabilizerFrame

Such objects are primarily used internally by pyGSTi to compute things like probabilities more efficiently.




Copy this stabilizer frame.

Note that this also copies “view filters” setup via push_view calls.



push_view(self, qubit_filter)

Applies a filter to the action of clifford_update.

After calling push_view, the stabilizer frame looks to some extent as though it were only a frame on the subset of qubits given by qubit_fitler. In particular, calls to clifford_update should specify clifford operations that act only on the filtered qubits. Furthermore, views can be nested. For example, if on a frame starting with 10 qubits (labeled 0 to 9) push_view([3,4,5,6]) and then push_view([0,2]) are called, the current “view” will be of the original qubits 3 and 5.

This is useful for applying “embedded” gates (those acting on just a subset of the state space).


qubit_filter (list) – A list of qubit indices to view, relative to the current view.




Removes the last-applied (via :method:`push_view`) view filter.


list – A list of qubit indices to view (a “view filter”).

property nqubits(self)

The number of qubits in the state this frame represents



_colsum(self, i, j)

Col_i = Col_j * Col_i where ‘*’ is group action

_colswap(self, i, j)

Swaps Col_i & Col_j


Update self.s and to be in reduced/canonical form Based on arXiv: 1210.6646v3 “Efficient Inner-product Algorithm for Stabilizer States”

_canonical_amplitudes(self, ip, target=None, qs_to_sample=None)

Canonical amplitudes are the ones that we assign to the components of a stabilizer state even though they’re not actually specified by the stabilizer group – these serve as an arbitrary baseline so that we can keep track of how amplitudes change by keeping track of amplitudes relative to these fixed “canonical” amplitudes.

Extracts one or more canonical amplitudes from the ip-th stabilizer state: one if target is specified, otherwise a full set of values for the qubit indices in qs_to_sample (which, if it’s the empty tuple, means that only one – most convenient – amplitude needs to be returned.

_canonical_amplitude(self, ip, zvals)

Return the “intrinsic” amplitude of the given comp. basis state as encoded within the s,p matrices of the ip-th stabilizer state (alone)

_sample_amplitude(self, ip, qs_to_sample=1)

extract count convenient canonical amplitudes from the ip-th stabilizer state

_apply_clifford_to_frame(self, s, p, qubit_filter)

Applies a clifford in the symplectic representation to this stabilize frame – similar to apply_clifford_to_stabilizer_state but operates on an entire frame

  • s (numpy array) – The symplectic matrix over the integers mod 2 representing the Clifford

  • p (numpy array) – The ‘phase vector’ over the integers mod 4 representing the Clifford


Get a string representing the full ip-th stabilizer state (w/global phase)




Get a dictionary of the full amplitudes of each present computational basis state.

This may take a while for many-qubit states, as it requires getting 2^(num_qubits) amplitudes.


dict – Keys are tuples of z-values specifying the different computational basis states. Values are the complex amplitudes.


Convert this stabilizer frame to dense length-2^(num_qubits) complex state vector of amplitudes.



extract_amplitude(self, zvals)

Get the full (not just “canonical”) amplitude of a given computational basis state.


zvals (numpy.ndarray) – An array of 0/1 elements specifying the desired basis state.



clifford_update(self, smatrix, svector, u_mx, qubit_filter=None)

Update this stabilizer frame by the action of a Clifford operation.

The Clifford operation is given in the usual symplectic representation. If there are any active views (from calling :method:`push_view`) and/or if qubit_filter is not None, then smatrix, svector, and u_mx should be sized for just the number of qubits in the current view.

  • smatrix (numpy.ndarray) – The symplectic matrix of shape (2n,2n), where n is the number of qubits (in the current view if applicable), representing the Clifford operation.

  • svector (numpy.ndarray) – The phase vector of shape (2n,) representing the Clifford operation.

  • u_mx (numpy.ndarray) – The dense unitary representation of the Clifford action, which is needed in order to track the global phase of the frame (state). This is a complex matrix of shape (2^n,2^n), where n is the number of qubits (in the current view if applicable).

  • qubit_filter (list, optional) – An additional view filter to apply just for this function call (i.e. it is not stored on a stack as it is for :method:`push_view`.



measurement_probability(self, zvals, qubit_filter=None, return_state=False, check=False)

Extract the probability of obtaining a given computation-basis-measurement outcome.

  • zvals (numpy.ndarray) – An array of 0/1 elements specifying the computational basis outcomes.

  • qubit_filter (list, optional) – A list specifying a subset of the qubits to measure. len(zvals) should always equal len(qubit_filter). If None, then all qubits are measured. Currently unsupported.

  • return_state (bool, optional) – Whether the post-measurement state (frame) should be returned. Currently unsupported.

  • check (bool, optional) – Whether to perform internal self-consistency checks (for debugging, makes function run more slowly).




Return str(self).


Computes a tensor-product StabilizerFrame from a set of factors.


sframe_factors (list of StabilizerFrame objects) – The factors to tensor together in the given left-to-right order.