Metadata-Version: 2.3
Name: qsp-proc
Version: 0.1.0
Summary: Add your description here
Requires-Dist: matplotlib>=3.10.8
Requires-Dist: numpy>=2.4.3
Requires-Dist: pennylane>=0.44.1
Requires-Dist: qiskit>=2.3.0
Requires-Dist: scipy>=1.17.1
Requires-Dist: torch>=2.10.0
Requires-Python: >=3.14
Description-Content-Type: text/markdown

# qsp-proc

A QSP phase-finding package implementing the preprocessing pipeline from Skelton 2025.

## Features

- **Completion methods (4):** Wilson/Fejér, BerSün (FFT-based), optimization-based completion, and root-finding/Prony-style completion.
- **QSP conventions (4):** base conventions, Angle-QSP (Lemma 1), Laurent-QSP (Lemma 3), and G-QSP (Lemma 4).
- **Metasolver pipeline:** compose approximation, completion, decomposition, and phase extraction into a single workflow.
- **Recursive decomposition:** carve \(F(z)\) into \(\{P_j\}\) and \(E_0\) for downstream synthesis.
- **Circuit generation:** build Qiskit circuits for basic QSP, controlled variants, and LCU constructions.

## Installation

Install in editable mode with `uv`:

```bash
uv pip install -e .
```

## Quick Start

Use the preprocessing pipeline with a Jacobi-Anger Laurent approximation:

```python
from qsp_proc import qsp_preprocess
from qsp_proc.polynomials.approximations import jacobi_anger_laurent

target = jacobi_anger_laurent(tau=50, epsilon=1e-10)
result = qsp_preprocess(target=target)
print(result.summary())
```

## CLI Usage

Run the CLI entry script with typical parameters:

```bash
uv run python main.py --tau 50 --epsilon 1e-10
```

## Project Structure

```text
src/qsp_proc/
├── polynomials/      # Chebyshev/Laurent polynomial tools and approximations (Jacobi-Anger, Remez).
├── conventions/      # Angle, Laurent, and G-QSP convention mappings and shared interfaces.
├── completion/       # Complementary polynomial solvers (Wilson, BerSün, optimization, rootfinding, Prony).
├── decomposition/    # Recursive carving routines for Laurent matrix polynomial factorization.
├── circuits/         # Qiskit circuit constructors for basic, controlled, and LCU QSP forms.
└── pipeline.py       # End-to-end preprocessing pipeline from target function to phases/circuits.
```

## Documentation

Full docs available at [https://bawa27.github.io/qsp-proc/](https://bawa27.github.io/qsp-proc/).

## References

- Skelton, 2025. *Hitchhiker's Guide to QSP Pre-processing*. arXiv:2501.05977.
- Berntson and Sunderhauf, 2025. *Complementary polynomials in quantum signal processing*. arXiv:2406.04246.

## License

MIT.