Add base representation of SparseObservable

[jakelishman]

Summary

This adds the base representation of SparseObservable, including the simple constructors from Python space and the ability to view the data buffers.

This commit does not include the mathematical manipulations of the operators, nor some of the helper methods that will be used to manipulate the operators in the context of primitives execution. These will follow in subsequent patches.

The design and implementation notes of SparseObservable are described in a Qiskit RFC that preceeded this patch series¹, and it's best to consult that document for full details on the operator considerations.

Details and comments

This is the beginnings of the implementation of Qiskit/RFCs#74, and subject to change based on decisions made there.

A current simple example of what works with the PR:

import numpy as np
from qiskit.quantum_info import SparseObservable

# Using the copy-in constructor to make the Z_0 + Z_1 + Z_2 + ... operator
# by manually providing the data buffers.
num_qubits = 100
terms = np.full((num_qubits,), SparseObservable.BitTerm["+"], 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)
# This copies out of the buffers, because we need the base allocations to be
# owned by Rust space.
so = SparseObservable.from_raw_parts(num_qubits, coeffs, terms, indices, boundaries)

print(so.bit_terms)

This PR depends on #12669.

Close #12282. This PR only adds the representation of such operators, but that's sufficient to immediately fulfil the feature as an MVP. Qiskit/RFCs#75 tracks the rest of the implementation of the RFC.

Footnotes

1. https://github.com/Qiskit/RFCs/blob/7a74b08793475b7b0142d3a3f7142cabcfd33ab8/0021-sparse-observable.md ↩

[jakelishman]

No longer "on hold" because its dependency merged, but I do still need to write a lot more of the initialisation methods for this.

[qiskit-bot]

One or more of the following people are relevant to this code:

• @Qiskit/terra-core

[jakelishman]

This base PR for SparseObservable is now ready for review. I'll follow it (at some point) with another adding mathematical operators to the observable, and one (or more) adding helper methods for use by and for the primitives.

[coveralls]

Pull Request Test Coverage Report for Build 11458543910

Warning: This coverage report may be inaccurate.

This pull request's base commit is no longer the HEAD commit of its target branch. This means it includes changes from outside the original pull request, including, potentially, unrelated coverage changes.

• For more information on this, see Tracking coverage changes with pull request builds.
• To avoid this issue with future PRs, see these Recommended CI Configurations.
• For a quick fix, rebase this PR at GitHub. Your next report should be accurate.

Details

• 710 of 725 (97.93%) changed or added relevant lines in 4 files are covered.
• 13 unchanged lines in 3 files lost coverage.
• Overall coverage increased (+0.08%) to 88.634%

---

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
crates/accelerate/src/sparse_observable.rs	707	722	97.92%

Files with Coverage Reduction	New Missed Lines	%
qiskit/transpiler/passes/synthesis/unitary_synthesis.py	2	61.59%
crates/qasm2/src/lex.rs	5	92.23%
qiskit/synthesis/two_qubit/xx_decompose/decomposer.py	6	90.77%

Totals
Change from base Build 11411236768:	0.08%
Covered Lines:	74571
Relevant Lines:	84134

---

💛 - Coveralls

[jakelishman]

The only missing lines in the coverage report are ones that are unreachable, either clearly from the code, or because they're error paths to handle things like a SparsePauliOp that violates its internal data structures during the extraction of the data to Rust space.

(Also there's a line about copy=False in an __array__ method, but that actually is tested, it's just the coverage run uses numpy<2 due to some transitive dependency, which suppresses that test.)

[Cryoris]

I'm not quite through with the first look, but there's some bits I don't 100% understand (like how bytemuck works) but overall this looks really nice and the the comments help a ton to understand it 🙂 I have mainly questions below for now and will have a look at the rest (and play with it) in a bit!

[Cryoris]

Thanks for the detailed comments and responses, this looks really nice (and I learned quite a bunch in reviewing 😄)!