Split `PySparseObservable` off `SparseObservable` #13595

Cryoris · 2024-12-23T10:50:33Z

Summary

Closes #13594 to prepare for SparseObservable's C API. This change has been tested with our basic C API for SparseObservable, which will come in a separate PR to keep the review load in balance 🙂

Details and comments

This PR splits the sparse observable class into a Rust-only SparseObservable struct and a PySparseObservable, which serves as Python interface. As suggested in #13391, the Python interface keeps an Arc to a read-write-locked SparseObservable. The API Change label is only due to some minuscule change in an error message, the Python interface remains unchanged.

The implementation is based on

#[pyclass(name = "SparseObservable", ...)]  // exposed as qiskit.quantum_info.SparseObservable, as before
struct PySparseObservable {
    // This class keeps a pointer to a pure Rust-SparseTerm and serves as interface from Python.
    inner: Arc<RwLock<SparseObservable>>,
}

and methods on PySparseObservable first acquire the read- or write-lock to perform actions on the inner data. For example, implementing transpose becomes

    fn transpose(&self) -> PyResult<Self> {
        // acquire the read lock, mapping the PoisonError into our own error that can be cast to a PyErr
        let inner = self.inner.read().map_err(|_| InnerReadError)?;

        // perform the action
        let result = inner.transpose();  
        
        // return a new Arc<RwLock> (if we did an inplace operation, we would just return nothing)
        Ok(Self { inner: Arc::new(RwLock::new(result)) })
    }

Some notes/questions:

For SparseTerm we analogously split off PySparseTerm, since it can be returned to Python. The view/mutable view versions are not returned to Python and don't need a specific interface.
We couldn't implement IntoPy to PoisonError (coming from RwLock::read/write), so as solution we introduced custom InnerReadErrors and InnerWriteErrors.
We moved some methods from the pymethods into the core Rust object and restricted direct access to the inner data, in favor of using public getters/methods.
The SparseObservable docstring is moved to the Python interface for now, though we might want to add a bit more Rust-specific info.

qiskit-bot · 2024-12-23T10:50:39Z

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

@Qiskit/terra-core

coveralls · 2024-12-23T11:15:28Z

Pull Request Test Coverage Report for Build 12465601613

Details

1192 of 1245 (95.74%) changed or added relevant lines in 4 files are covered.
4 unchanged lines in 2 files lost coverage.
Overall coverage increased (+0.02%) to 88.974%

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
crates/accelerate/src/sparse_observable.rs	149	151	98.68%
crates/accelerate/src/py_sparse_observable.rs	1041	1092	95.33%

Files with Coverage Reduction	New Missed Lines	%
crates/qasm2/src/lex.rs	1	92.73%
crates/accelerate/src/sparse_observable.rs	3	93.37%

Totals
Change from base Build 12420636821:	0.02%
Covered Lines:	79695
Relevant Lines:	89571

💛 - Coveralls

jakelishman

Thanks for doing this.

This is just a quick high-level overview - I'll look more in detail in the new year, especially since I'll have to use a lot more local tools to do a good comparison - with the file move and changes to the code, it's hard to see what's gone on here.

Top level questions:

Why split py_sparse_observable into a separate flat file? I'd have expected any of:
- keep both in the same file
- make a sparse_observable module to put them in
- make a separate crate that contains only the C components
  with a rough preference to just keeping everything in the same file for now. This form to me has meant that a lot of logically private functions have had to become pub(crate), and now there's more places to look to understand the code.
For everything that's become pub(crate): in some cases, I think pub(crate) just indicates that a function is defined in the wrong file. In many others, since this PR is looking to a future when SparseObservable is consumable by non-Qiskit crates directly from Rust, I suspect that anything that became pub(crate) should be either private or fully pub. If it's useful for the Python wrapper, feels highly likely it ought to be a proper public interface.

jakelishman · 2024-12-23T11:10:24Z