SparseObservable

__new__(data, /, num_qubits=None)

The default constructor of SparseObservable.

This delegates to one of the explicit conversion-constructor methods, based on the type of the data argument. If num_qubits is supplied and constructor implied by the type of data does not accept a number, the given integer must match the input.

Parameters

• data – The data type of the input. This can be another SparseObservable, in which case the input is copied, a Pauli or SparsePauliOp, in which case from_pauli() or from_sparse_pauli_op() are called as appropriate, or it can be a list in a valid format for either from_list() or from_sparse_list().
• num_qubits (int|None) – Optional number of qubits for the operator. For most data inputs, this can be inferred and need not be passed. It is only necessary for empty lists or the sparse-list format. If given unnecessarily, it must match the data input.

A flat list of single-qubit terms. This is more naturally a list of lists, but is stored flat for memory usage and locality reasons, with the sublists denoted by boundaries.

Indices that partition bit_terms and indices into sublists for each individual term in the sum. boundaries[0] : boundaries[1] is the range of indices into bit_terms and indices that correspond to the first term of the sum. All unspecified qubit indices are implicitly the identity. This is one item longer than coeffs, since boundaries[0] is always an explicit zero (for algorithmic ease).

The coefficients of each abstract term in in the sum. This has as many elements as terms in the sum.

A flat list of the qubit indices that the corresponding entries in bit_terms act on. This list must always be term-wise sorted, where a term is a sublist as denoted by boundaries.

The number of qubits the operator acts on.

This is not inferable from any other shape or values, since identities are not stored explicitly.

The number of terms in the sum this operator is tracking.

adjoint()

Calculate the adjoint of this observable.

This is well defined in the abstract mathematical sense. All the terms of the single-qubit alphabet are self-adjoint, so the result of this operation is the same observable, except its coefficients are all their complex conjugates.

Examples

>>> left = SparseObservable.from_list([("XY+-", 1j)])
>>> right = SparseObservable.from_list([("XY+-", -1j)])
>>> assert left.adjoint() == right

apply_layout(layout, num_qubits=None)

Apply a transpiler layout to this SparseObservable.

Typically you will have defined your observable in terms of the virtual qubits of the circuits you will use to prepare states. After transpilation, the virtual qubits are mapped to particular physical qubits on a device, which may be wider than your circuit. That mapping can also change over the course of the circuit. This method transforms the input observable on virtual qubits to an observable that is suitable to apply immediately after the fully transpiled physical circuit.

Parameters

• layout (TranspileLayout |list[int] | None) – The layout to apply. Most uses of this function should pass the QuantumCircuit.layout field from a circuit that was transpiled for hardware. In addition, you can pass a list of new qubit indices. If given as explicitly None, no remapping is applied (but you can still use num_qubits to expand the observable).
• num_qubits (int | None) – The number of qubits to expand the observable to. If not supplied, the output will be as wide as the given TranspileLayout, or the same width as the input if the layout is given in another form.

Returns

A new SparseObservable with the provided layout applied.

clear()

Clear all the terms from this operator, making it equal to the zero operator again.

This does not change the capacity of the internal allocations, so subsequent addition or substraction operations may not need to reallocate.

Examples

>>> obs = SparseObservable.from_list([("IX+-rl", 2.0), ("01YZII", -1j)])
>>> obs.clear()
>>> assert obs == SparseObservable.zero(obs.num_qubits)

conjugate()

Calculate the complex conjugation of this observable.

This operation is defined in terms of the standard matrix conventions of Qiskit, in that the matrix form is taken to be in the $Z$ computational basis. The $X$- and $Z$-related alphabet terms are unaffected by the complex conjugation, but $Y$-related terms modify their alphabet terms. Precisely:

• $Y$ conjguates to $-Y$
• $\lvert r\rangle\langle r\rvert$ conjugates to $\lvert l\rangle\langle l\rvert$
• $\lvert l\rangle\langle l\rvert$ conjugates to $\lvert r\rangle\langle r\rvert$

Additionally, all coefficients are conjugated.

Examples

>>> obs = SparseObservable([("III", 1j), ("Yrl", 0.5)])
>>> assert obs.conjugate() == SparseObservable([("III", -1j), ("Ylr", -0.5)])

copy()

Get a copy of this observable.

Examples

>>> obs = SparseObservable.from_list([("IXZ+lr01", 2.5), ("ZXI-rl10", 0.5j)])
>>> assert obs == obs.copy()
>>> assert obs is not obs.copy()

expand(other, /)

Reverse-order tensor product.

This is equivalent to other.tensor(self), except that other will first be type-cast to SparseObservable if it isn’t already one (by calling the default constructor).

Parameters

other – the observable to put on the left-hand side of the tensor product.

Examples

This is equivalent to tensor() with the order of the arguments flipped:

>>> left = SparseObservable.from_label("XYZ")
>>> right = SparseObservable.from_label("+-IIrl")
>>> assert left.tensor(right) == right.expand(left)

static from_label(label, /)

Construct a single-term observable from a dense string label.

The resulting operator will have a coefficient of 1. The label must be a sequence of the alphabet 'IXYZ+-rl01'. The label is interpreted analogously to a bitstring. In other words, the right-most letter is associated with qubit 0, and so on. This is the same as the labels for Pauli and SparsePauliOp.

Parameters

label (str) – the dense label.

Examples

>>> SparseObservable.from_label("IIII+ZI")
<SparseObservable with 1 term on 7 qubits: (1+0j)(+_2 Z_1)>
>>> label = "IYXZI"
>>> pauli = Pauli(label)
>>> assert SparseObservable.from_label(label) == SparseObservable.from_pauli(pauli)

static from_list(iter, /, *, num_qubits=None)

Construct an observable from a list of dense labels and coefficients.

This is analogous to SparsePauliOp.from_list(), except it uses the extended alphabet of SparseObservable. In this dense form, you must supply all identities explicitly in each label.

The label must be a sequence of the alphabet 'IXYZ+-rl01'. The label is interpreted analogously to a bitstring. In other words, the right-most letter is associated with qubit 0, and so on. This is the same as the labels for Pauli and SparsePauliOp.

Parameters

• iter (list[tuple[str, complex]]) – Pairs of labels and their associated coefficients to sum. The labels are interpreted the same way as in from_label().
• num_qubits (int | None) – It is not necessary to specify this if you are sure that iter is not an empty sequence, since it can be inferred from the label lengths. If iter may be empty, you must specify this argument to disambiguate how many qubits the observable is for. If this is given and iter is not empty, the value must match the label lengths.

Examples

Construct an observable from a list of labels of the same length:

>>> SparseObservable.from_list([
...     ("III++", 1.0),
...     ("II--I", 1.0j),
...     ("I++II", -0.5),
...     ("--III", -0.25j),
... ])
<SparseObservable with 4 terms on 5 qubits:
    (1+0j)(+_1 +_0) + (0+1j)(-_2 -_1) + (-0.5+0j)(+_3 +_2) + (-0-0.25j)(-_4 -_3)>

Use num_qubits to disambiguate potentially empty inputs:

>>> SparseObservable.from_list([], num_qubits=10)
<SparseObservable with 0 terms on 10 qubits: 0.0>

This method is equivalent to calls to from_sparse_list() with the explicit qubit-arguments field set to decreasing integers:

>>> labels = ["XY+Z", "rl01", "-lXZ"]
>>> coeffs = [1.5j, 2.0, -0.5]
>>> from_list = SparseObservable.from_list(list(zip(labels, coeffs)))
>>> from_sparse_list = SparseObservable.from_sparse_list([
...     (label, (3, 2, 1, 0), coeff)
...     for label, coeff in zip(labels, coeffs)
... ])
>>> assert from_list == from_sparse_list

static from_pauli(pauli, /)

Construct a SparseObservable from a single Pauli instance.

The output observable will have a single term, with a unitary coefficient dependent on the phase.

Parameters

pauli (Pauli) – the single Pauli to convert.

Examples

>>> label = "IYXZI"
>>> pauli = Pauli(label)
>>> SparseObservable.from_pauli(pauli)
<SparseObservable with 1 term on 5 qubits: (1+0j)(Y_3 X_2 Z_1)>
>>> assert SparseObservable.from_label(label) == SparseObservable.from_pauli(pauli)

static from_raw_parts(num_qubits, coeffs, bit_terms, indices, boundaries, check=True)

Construct a SparseObservable from raw Numpy arrays that match the required data representation described in the class-level documentation.

The data from each array is copied into fresh, growable Rust-space allocations.

Parameters

• num_qubits – number of qubits in the observable.

• coeffs – complex coefficients of each term of the observable. This should be a Numpy array with dtype complex128.

• bit_terms – flattened list of the single-qubit terms comprising all complete terms. This should be a Numpy array with dtype uint8 (which is compatible with BitTerm).

• indices – flattened term-wise sorted list of the qubits each single-qubit term corresponds to. This should be a Numpy array with dtype uint32.

• boundaries – the indices that partition bit_terms and indices into terms. This should be a Numpy array with dtype uintp.

• check –

  if True (the default), validate that the data satisfies all coherence guarantees. If False, no checks are done.

  Warning

  If check=False, the bit_terms absolutely must be all be valid values of SparseObservable.BitTerm. If they are not, Rust-space undefined behavior may occur, entirely invalidating the program execution.

Examples

Construct a sum of $Z$ on each individual qubit:

>>> num_qubits = 100
>>> terms = np.full((num_qubits,), SparseObservable.BitTerm.Z, dtype=np.uint8)
>>> indices = np.arange(num_qubits, dtype=np.uint32)
>>> coeffs = np.ones((num_qubits,), dtype=complex)
>>> boundaries = np.arange(num_qubits + 1, dtype=np.uintp)
>>> SparseObservable.from_raw_parts(num_qubits, coeffs, terms, indices, boundaries)
<SparseObservable with 100 terms on 100 qubits: (1+0j)(Z_0) + ... + (1+0j)(Z_99)>

static from_sparse_list(iter, /, num_qubits)

Construct an observable from a list of labels, the qubits each item applies to, and the coefficient of the whole term.

This is analogous to SparsePauliOp.from_sparse_list(), except it uses the extended alphabet of SparseObservable.

The “labels” and “indices” fields of the triples are associated by zipping them together. For example, this means that a call to from_list() can be converted to the form used by this method by setting the “indices” field of each triple to (num_qubits-1, ..., 1, 0).

Parameters

• iter (list[tuple[str, Sequence[int], complex]]) – triples of labels, the qubits each single-qubit term applies to, and the coefficient of the entire term.
• num_qubits (int) – the number of qubits in the operator.

Examples

Construct a simple operator:

>>> SparseObservable.from_sparse_list(
...     [("ZX", (1, 4), 1.0), ("YY", (0, 3), 2j)],
...     num_qubits=5,
... )
<SparseObservable with 2 terms on 5 qubits: (1+0j)(X_4 Z_1) + (0+2j)(Y_3 Y_0)>

Construct the identity observable (though really, just use identity()):

>>> SparseObservable.from_sparse_list([("", (), 1.0)], num_qubits=100)
<SparseObservable with 1 term on 100 qubits: (1+0j)()>

This method can replicate the behavior of from_list(), if the qubit-arguments field of the triple is set to decreasing integers:

>>> labels = ["XY+Z", "rl01", "-lXZ"]
>>> coeffs = [1.5j, 2.0, -0.5]
>>> from_list = SparseObservable.from_list(list(zip(labels, coeffs)))
>>> from_sparse_list = SparseObservable.from_sparse_list([
...     (label, (3, 2, 1, 0), coeff)
...     for label, coeff in zip(labels, coeffs)
... ])
>>> assert from_list == from_sparse_list

static from_sparse_pauli_op(op, /)

Construct a SparseObservable from a SparsePauliOp instance.

This will be a largely direct translation of the SparsePauliOp; in particular, there is no on-the-fly summing of like terms, nor any attempt to refactorize sums of Pauli terms into equivalent projection operators.

Parameters

op (SparsePauliOp) – the operator to convert.

Examples

>>> spo = SparsePauliOp.from_list([("III", 1.0), ("IIZ", 0.5), ("IZI", 0.5)])
>>> SparseObservable.from_sparse_pauli_op(spo)
<SparseObservable with 3 terms on 3 qubits: (1+0j)() + (0.5+0j)(Z_0) + (0.5+0j)(Z_1)>

static from_terms(obj, /, num_qubits=None)

Construct a SparseObservable out of individual terms.

All the terms must have the same number of qubits. If supplied, the num_qubits argument must match the terms.

No simplification is done as part of the observable creation.

Parameters

• obj (Iterable[Term]) – Iterable of individual terms to build the observable from.
• num_qubits (int | None) – The number of qubits the observable should act on. This is usually inferred from the input, but can be explicitly given to handle the case of an empty iterable.

Returns

The corresponding observable.

static identity(num_qubits)

Get the identity operator over the given number of qubits.

Examples

Get the identity operator for 100 qubits:

>>> SparseObservable.identity(100)
<SparseObservable with 1 term on 100 qubits: (1+0j)()>

pauli_bases()

Get a PauliList object that represents the measurement basis needed for each term (in order) in this observable.

For example, the projector 0l+ will return a Pauli ZXY. The resulting Pauli is dense, in the sense that explicit identities are stored. An identity in the Pauli output does not require a concrete measurement.

This will return an entry in the Pauli list for every term in the sum.

Returns

the Pauli operator list representing the necessary measurement bases.

Return type

PauliList

simplify(tol=1e-08)

Sum any like terms in this operator, removing them if the resulting complex coefficient has an absolute value within tolerance of zero.

As a side effect, this sorts the operator into canonical order.

Parameters

tol (float) – after summing like terms, any coefficients whose absolute value is less than the given absolute tolerance will be suppressed from the output.

Examples

Using simplify() to compare two operators that represent the same observable, but would compare unequal due to the structural tests by default:

>>> base = SparseObservable.from_sparse_list([
...     ("XZ", (2, 1), 1e-10),  # value too small
...     ("+-", (3, 1), 2j),
...     ("+-", (3, 1), 2j),     # can be combined with the above
...     ("01", (3, 1), 0.5),    # out of order compared to `expected`
... ], num_qubits=5)
>>> expected = SparseObservable.from_list([("I0I1I", 0.5), ("I+I-I", 4j)])
>>> assert base != expected  # non-canonical comparison
>>> assert base.simplify() == expected.simplify()

Note that in the above example, the coefficients are chosen such that all floating-point calculations are exact, and there are no intermediate rounding or associativity concerns. If this cannot be guaranteed to be the case, the safer form is:

>>> left = SparseObservable.from_list([("XYZ", 1.0/3.0)] * 3)   # sums to 1.0
>>> right = SparseObservable.from_list([("XYZ", 1.0/7.0)] * 7)  # doesn't sum to 1.0
>>> assert left.simplify() != right.simplify()
>>> assert (left - right).simplify() == SparseObservable.zero(left.num_qubits)

tensor(other, /)

Tensor product of two observables.

The bit ordering is defined such that the qubit indices of the argument will remain the same, and the indices of self will be offset by the number of qubits in other. This is the same convention as used by the rest of Qiskit’s quantum_info operators.

This function is used for the infix ^ operator. If using this operator, beware that Python’s operator-precedence rules may cause the evaluation order to be different to your expectation. In particular, the operator + binds more tightly than ^, just like * binds more tightly than +. Use parentheses to fix the evaluation order, if needed.

The argument will be cast to SparseObservable using its default constructor, if it is not already in the correct form.

Parameters

other – the observable to put on the right-hand side of the tensor product.

Examples

The bit ordering of this is such that the tensor product of two observables made from a single label “looks like” an observable made by concatenating the two strings:

>>> left = SparseObservable.from_label("XYZ")
>>> right = SparseObservable.from_label("+-IIrl")
>>> assert left.tensor(right) == SparseObservable.from_label("XYZ+-IIrl")

You can also use the infix ^ operator for tensor products, which will similarly cast the right-hand side of the operation if it is not already a SparseObservable:

>>> assert SparseObservable("rl") ^ Pauli("XYZ") == SparseObservable("rlXYZ")

transpose()

Calculate the matrix transposition of this observable.

This operation is defined in terms of the standard matrix conventions of Qiskit, in that the matrix form is taken to be in the $Z$ computational basis. The $X$- and $Z$-related alphabet terms are unaffected by the transposition, but $Y$-related terms modify their alphabet terms. Precisely:

• $Y$ transposes to $-Y$
• $\lvert r\rangle\langle r\rvert$ transposes to $\lvert l\rangle\langle l\rvert$
• $\lvert l\rangle\langle l\rvert$ transposes to $\lvert r\rangle\langle r\rvert$

Examples

>>> obs = SparseObservable([("III", 1j), ("Yrl", 0.5)])
>>> assert obs.transpose() == SparseObservable([("III", 1j), ("Ylr", -0.5)])

static zero(num_qubits)

Get the zero operator over the given number of qubits.

The zero operator is the operator whose expectation value is zero for all quantum states. It has no terms. It is the identity element for addition of two SparseObservable instances; anything added to the zero operator is equal to itself.

If you want the projector onto the all zeros state, use:

>>> num_qubits = 10
>>> all_zeros = SparseObservable.from_label("0" * num_qubits)

Examples

Get the zero operator for 100 qubits:

>>> SparseObservable.zero(100)
<SparseObservable with 0 terms on 100 qubits: 0.0>