Metadata-Version: 2.4
Name: qiskit-addon-slc
Version: 0.2.0
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Natural Language :: English
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Dist: matplotlib>=3.10.5,<4
Requires-Dist: plotly>=6.5.0,<8
Requires-Dist: qiskit[visualization]>=2.2,<3
Requires-Dist: pauli-prop>=0.1.0,<1
Requires-Dist: rustworkx
Requires-Dist: samplomatic>=0.16.0
Requires-Dist: pytest>=8.0 ; extra == 'basetest'
Requires-Dist: pytest-cov>=5.0 ; extra == 'basetest'
Requires-Dist: pytest-subtests>=0.14 ; extra == 'basetest'
Requires-Dist: qiskit-addon-slc[test,doctest,nbtest,lint,docs] ; extra == 'dev'
Requires-Dist: tox>=4.4.3 ; extra == 'dev'
Requires-Dist: qiskit-addon-slc[doctest] ; extra == 'docs'
Requires-Dist: qiskit-sphinx-theme~=2.1.0 ; extra == 'docs'
Requires-Dist: jupyter-sphinx ; extra == 'docs'
Requires-Dist: sphinx-design ; extra == 'docs'
Requires-Dist: sphinx-autodoc-typehints ; extra == 'docs'
Requires-Dist: sphinx-copybutton ; extra == 'docs'
Requires-Dist: sphinx-reredirects ; extra == 'docs'
Requires-Dist: nbsphinx>=0.9.4 ; extra == 'docs'
Requires-Dist: reno>=4.1 ; extra == 'docs'
Requires-Dist: qiskit-addon-slc[basetest,notebook-dependencies] ; extra == 'doctest'
Requires-Dist: pytest-doctestplus>=1.3.0 ; extra == 'doctest'
Requires-Dist: qiskit-addon-slc[style] ; extra == 'lint'
Requires-Dist: mypy==2.4.0 ; extra == 'lint'
Requires-Dist: pylint==4.1.2 ; extra == 'lint'
Requires-Dist: reno>=4.1 ; extra == 'lint'
Requires-Dist: toml>=0.9.6 ; extra == 'lint'
Requires-Dist: qiskit-addon-slc[basetest] ; extra == 'nbtest'
Requires-Dist: nbmake>=1.5.0 ; extra == 'nbtest'
Requires-Dist: qiskit-addon-slc ; extra == 'notebook-dependencies'
Requires-Dist: qiskit-addon-utils>=0.3.0 ; extra == 'notebook-dependencies'
Requires-Dist: qiskit-ibm-runtime>=0.47 ; extra == 'notebook-dependencies'
Requires-Dist: ruff==0.16.10 ; extra == 'style'
Requires-Dist: nbqa>=1.8.5 ; extra == 'style'
Requires-Dist: typos>=1.20.0 ; extra == 'style'
Requires-Dist: qiskit-addon-slc[basetest] ; extra == 'test'
Requires-Dist: qiskit-ibm-runtime>=0.47 ; extra == 'test'
Provides-Extra: basetest
Provides-Extra: dev
Provides-Extra: docs
Provides-Extra: doctest
Provides-Extra: lint
Provides-Extra: nbtest
Provides-Extra: notebook-dependencies
Provides-Extra: style
Provides-Extra: test
License-File: LICENSE.txt
Summary: Reducing PEC sampling overhead with shaded lightcones
License-Expression: Apache-2.0
Requires-Python: >=3.11
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

<!-- SHIELDS -->
<div align="left">

  [![Release](https://img.shields.io/pypi/v/qiskit-addon-slc.svg?label=Release)](https://github.com/Qiskit/qiskit-addon-slc/releases)
  ![Platform](https://img.shields.io/badge/%F0%9F%92%BB%20Platform-Linux%20%7C%20macOS%20%7C%20Windows-informational)
  [![Python](https://img.shields.io/pypi/pyversions/qiskit-addon-slc?label=Python&logo=python)](https://www.python.org/)
  [![Qiskit](https://img.shields.io/badge/Qiskit%20-%20%3E%3D2.2%20-%20%236133BD?logo=Qiskit)](https://github.com/Qiskit/qiskit)
<br />
  <!--[![DOI](https://zenodo.org/badge/TODO.svg)](https://zenodo.org/badge/latestdoi/TODO)-->
  [![License](https://img.shields.io/github/license/Qiskit/qiskit-addon-slc?label=License)](LICENSE.txt)
  [![Downloads](https://img.shields.io/pypi/dm/qiskit-addon-slc.svg?label=Downloads)](https://pypi.org/project/qiskit-addon-slc/)
  [![Tests](https://github.com/Qiskit/qiskit-addon-slc/actions/workflows/test_latest_versions.yml/badge.svg)](https://github.com/Qiskit/qiskit-addon-slc/actions/workflows/test_latest_versions.yml)
  [![Coverage](https://coveralls.io/repos/github/Qiskit/qiskit-addon-slc/badge.svg?branch=main)](https://coveralls.io/github/Qiskit/qiskit-addon-slc?branch=main)
</div>

# Shaded lightcones (SLC)

![Lightcones](https://raw.githubusercontent.com/Qiskit/qiskit-addon-slc/refs/heads/main/docs/images/lightcones.png)

`qiskit-addon-slc` is a package for computing the shaded lightcone (SLC) [[1]](#references) of an
observable with respect to a quantum circuit. In the context of probabilistic error cancellation (PEC), shaded lightcones
are similar to conventional binary lightcones in that not mitigating errors outside the
lightcone can reduce the variance (i.e. sampling cost). Lightcone shading allows this strategy to
be pushed further by assigning scales to Pauli error generators within the causal lightcone.
Errors that are assigned smaller scales have less effect on the observable; truncating them from the
noise model can reduce variance (i.e. sampling cost) at the cost of some bias. The `qiskit-addon-slc` package
gives users the ability to do lightcone shading and control the tradeoff between sampling cost and bias.

----------------------------------------------------------------------------------------------------

### Documentation

All documentation is available at https://quantum.cloud.ibm.com/docs/addons/qiskit-addon-slc.

----------------------------------------------------------------------------------------------------

### Installation

We encourage installing this package via `pip`, when possible:

```bash
pip install qiskit-addon-slc
```

For more installation information refer to these [installation instructions](docs/install.rst).

----------------------------------------------------------------------------------------------------

### Getting started

A simple guide to help you get started quickly with this package is available [here][docs/guides/quickstart.ipynb).

----------------------------------------------------------------------------------------------------

### Use case examples

This technique has been used to lower the sampling cost of probabilistic error cancellation (PEC) for
operator Loschmidt echo experiments with 56 qubits on an IBM Heron processor. [[2]](#references).

----------------------------------------------------------------------------------------------------

### Technical discussion

#### Method overview

Shaded lightcones are calculated and used in 5 steps:

1. Compute a bound on the effect of each Pauli error term on the observable at the end of the circuit (forward bound)
2. Compute a bound on the effect of each Pauli error term on the initial state at the beginning of the circuit (backward bound)

![Bounds](https://raw.githubusercontent.com/Qiskit/qiskit-addon-slc/refs/heads/main/docs/images/bounds.png)

3. Approximate a bias contribution for each Pauli error term using the forward/backward bounds and the term's error rate

![Merge bounds](https://raw.githubusercontent.com/Qiskit/qiskit-addon-slc/refs/heads/main/docs/images/merge_bounds.png)

4. Prioritize error terms based on their error rate and bounds. Truncate terms from the noise model which have the least effect on the observable expectation value until the user-specified bias tolerance is hit. Alternatively, one can add the most impactful error terms to a noise model until the user-specified sampling cost budget is filled. 

![Prioritize and truncate](https://raw.githubusercontent.com/Qiskit/qiskit-addon-slc/refs/heads/main/docs/images/prioritize_and_truncate.png)

5. Mitigate the truncated noise model. Using the [directed execution model](https://quantum.cloud.ibm.com/docs/guides/directed-execution-model) from Qiskit Runtime, specifying error terms to ignore during PEC sampling is straightforward. See the [tutorial](https://quantum.cloud.ibm.com/docs/tutorials/pec-with-shaded-lightcones) for details.

![Reduced PEC](https://raw.githubusercontent.com/Qiskit/qiskit-addon-slc/refs/heads/main/docs/images/reduced_pec.png)

#### Software features

- Parallel asynchronous bound computation
- [Rust-accelerated Pauli propagation](https://github.com/Qiskit/pauli-prop)
- Rust-accelerated eigenvalue computation for computing forward bounds
- Permits ahead-of-time bound computation (i.e. prior to the actual noise learning)

#### Known issues

- `InjectNoise(site="before")` not supported
- Does not support fine-grained bound merging

----------------------------------------------------------------------------------------------------

### Contributing

The source code is available [on GitHub](https://github.com/Qiskit/qiskit-addon-slc).

The developer guide is located at [CONTRIBUTING.md](https://github.com/Qiskit/qiskit-addon-slc/blob/main/CONTRIBUTING.md)
in the root of this project's repository.
By participating, you are expected to uphold Qiskit's [code of conduct](https://github.com/Qiskit/qiskit/blob/main/CODE_OF_CONDUCT.md).

----------------------------------------------------------------------------------------------------

### Citing this package

If you use this package in your research, use the [CITATION.bib](CITATION.bib) file in this project’s repository to cite the appropriate reference(s).

----------------------------------------------------------------------------------------------------

### License

[Apache License 2.0](LICENSE.txt)

----------------------------------------------------------------------------------------------------

### Deprecation Policy

We follow [semantic versioning](https://semver.org/). We may occasionally make breaking changes in
order to improve the user experience. When possible, we will keep old interfaces and mark them as
deprecated, as long as they can co-exist with the new ones. Each substantial improvement, breaking
change, or deprecation will be documented in the [release notes](https://quantum.cloud.ibm.com/docs/api/qiskit-addon-slc/release-notes).

----------------------------------------------------------------------------------------------------

### References

[1] Andrew Eddins, et al., [Lightcone shading for classically accelerated quantum error mitigation](https://arxiv.org/abs/2409.04401v1), arXiv:2409.04401v1 [quant-ph].

[2] Samantha V. Barron et al., [Observable Estimation in the Absence of Classical Verification](https://arxiv.org/pdf/2607.25998), arXiv:2607.25998 [quant-ph].

