qsvt-pennylane 0.1.23

Educational utilities and examples for Quantum Singular Value Transformation (QSVT) using PennyLane.

Quantum Singular Value Transformation (QSVT)

Lightweight tools for experimenting with Quantum Singular Value Transformation (QSVT) and bounded polynomial transforms using PennyLane.

This repository combines:

• a notebook-first introduction to QSVT and QSP
• a reusable Python package for polynomial design, spectral transforms, and small PennyLane QSVT checks
• reproducible examples for scalar, matrix, PDE, and small physics workflows

The focus is spectral intuition: how bounded polynomials transform singular values or eigenvalues through block encodings.

Links

• PyPI: qsvt-pennylane
• Website: project documentation
• Usage guide: USAGE.md
• Theory notes: THEORY.md
• Results index: RESULTS.md
• API reference: docs/qsvt/api_reference.md

Installation

Install from PyPI:

pip install qsvt-pennylane

Install from source:

git clone https://github.com/SidRichardsQuantum/Quantum_Singular_Value_Transformation.git
cd Quantum_Singular_Value_Transformation
pip install -e .

Requirements:

• Python >= 3.10
• PennyLane >= 0.36
• NumPy >= 1.23
• Matplotlib >= 3.7

Quick Example

Apply a scalar polynomial transform:

from qsvt.qsvt import qsvt_scalar_output

result = qsvt_scalar_output(
    x=0.5,
    poly=[0, 0, 1],  # x^2
    encoding_wires=[0],
)

Design a bounded sign polynomial and keep the diagnostics:

from qsvt.workflow import design_workflow

result = design_workflow(
    kind="sign",
    gamma=0.25,
    degree=13,
)

coeffs = result.coeffs
report = result.as_report()

Use the command line interface:

qsvt scalar --x 0.5 --poly "0,0,1"
qsvt design-workflow --kind sign --gamma 0.2 --degree 13
qsvt design-sweep --kind sign --degrees "5,9,13,17" --gamma 0.2 \
  --no-synthesis --output sign-degree-sweep.json
qsvt resource-report --poly "0,0,1" --matrix-dimension 4 --no-synthesis
qsvt benchmark cg-solve --matrix "4,1;1,3" --rhs "1,2" --qsvt-poly "0,1"
qsvt examples

See USAGE.md for full Python and CLI workflows.

Package Map

The public package lives under src/qsvt.

module	purpose
qsvt.polynomials	Chebyshev utilities, parity checks, boundedness checks
qsvt.approximation	polynomial fitting and approximation error helpers
qsvt.design	task-oriented polynomial builders
qsvt.algorithms	end-to-end simulator-scale algorithm workflows
qsvt.templates	ready-made bounded polynomial families
qsvt.workflow	combined coefficient, diagnostic, and compatibility workflows
qsvt.reports	JSON-safe reports and plot helpers
qsvt.resources	degree, phase-count, width, and compatibility proxy reports
qsvt.benchmarks	classical baselines and QSVT-oriented benchmark summaries
qsvt.matrices	small Hermitian test matrices
qsvt.spectral	classical spectral matrix-function references
qsvt.qsvt	PennyLane QSVT wrappers and comparisons
qsvt.hamiltonians, qsvt.pde, qsvt.rescaling	reusable physics and PDE helpers
qsvt.matrix_functions, qsvt.diagnostics	matrix-function designs and validation metrics

For detailed function-level documentation, use docs/qsvt/api_reference.md.

The package includes a py.typed marker so type checkers can consume the inline type annotations shipped with the public modules.

Documentation

• USAGE.md: practical package and CLI workflows
• THEORY.md: QSVT, QSP, polynomial constraints, and spectral interpretation
• RESULTS.md: result-producing notebooks and reproducible artefact conventions
• docs/qsvt/tutorial_results.md: generated tutorial notebook outputs
• docs/qsvt/real_example_results.md: generated real-example notebook outputs
• docs/qsvt/benchmark_results.md: generated benchmark notebook outputs
• docs/qsvt/classical_baselines.md: classical benchmark assumptions and baseline details
• docs/qsvt/qsvt_resource_model.md: QSVT proxy-resource interpretation and omitted costs
• docs/qsvt/design.md: polynomial design helpers
• docs/qsvt/algorithms.md: workflow-level algorithm notes, diagnostics, and limitations
• docs/qsvt/templates.md: template polynomial families
• docs/qsvt/physics.md: Hamiltonian, PDE, rescaling, and matrix-function workflows
• docs/qsvt/implementation.md: implementation conventions, report serialization, and API status
• docs/qsvt/notebooks.md: tutorial, benchmark, and real-example notebook index

Current release: 0.1.23

Notebooks

Tutorial notebooks live in notebooks/tutorials/ and introduce QSVT as polynomial functional calculus, from scalar transforms through sign functions, projectors, matrix functions, reusable design workflows, end-to-end algorithm workflows, reproducible reports, degree/error tradeoff studies, and resource-proxy limitations.

Real physics examples live in notebooks/real_examples/ and cover Hamiltonian simulation, ground-state filtering, quantum chemistry, Green's functions, spectral density estimation, Gibbs states, PDE systems, transport physics, spin-chain diagnostics, electronic occupations, photonic band gaps, graphene density of states, topological band projectors, and tensor-network hybrid filtering. Each real-example notebook includes a near-top orientation block for the system, QSVT implementation strategy, and quantum relevance.

Benchmark notebooks live in notebooks/benchmarks/ and compare classical linear-system, spectral, and polynomial matrix-function baselines against QSVT-oriented resource proxies and their underlying assumptions.

See docs/qsvt/notebooks.md for the full notebook map.

Scope

This project is intentionally educational, explicit, simulator-friendly, and polynomial-focused.

It does not aim to provide production-scale circuit optimization, resource estimation, fault-tolerant constructions, amplitude amplification, or state preparation methods. The emphasis is understanding how polynomial transforms act on spectra.

Support

If this repository is useful for research, learning, or experimentation, you can support continued development through GitHub Sponsors.

Author

Sid Richards

• GitHub: SidRichardsQuantum
• LinkedIn: Sid Richards

License

MIT License. See LICENSE.