Usage Guide

This guide shows how to use qsvt-pennylane for practical Quantum Singular Value Transformation (QSVT) experiments.

The package is organized around one workflow:

  1. choose or design a bounded polynomial,

  2. inspect its scalar behavior,

  3. apply it to a matrix spectrum,

  4. compare the classical spectral transform with the QSVT output.

Installation

pip install qsvt-pennylane

For local development:

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

Core Idea

QSVT implements a polynomial transformation

\[ A \rightarrow P(A) \]

where A is a block-encoded operator with spectrum normalized to the QSVT domain and P(x) is a bounded polynomial. In the Hermitian examples in this repository, eigenvectors are preserved and eigenvalues are transformed.

Typical Workflow

1. Choose Or Design A Polynomial

Use a ready-made template:

from qsvt.templates import sign_approximation_polynomial

coeffs = sign_approximation_polynomial(
    degree=11,
    sharpness=8.0,
)

Construct a task-oriented polynomial:

from qsvt.design import design_inverse_polynomial

coeffs = design_inverse_polynomial(
    gamma=0.25,
    degree=13,
)

Fit a polynomial approximation directly:

from qsvt.approximation import chebyshev_fit_function

coeffs = chebyshev_fit_function(
    lambda x: x**2,
    degree=6,
)

2. Inspect The Scalar Transform

import numpy as np

xs = np.linspace(-1, 1, 200)
values = np.polynomial.polynomial.polyval(xs, coeffs)

Useful checks:

from qsvt.polynomials import is_bounded_on_interval, polynomial_parity

parity = polynomial_parity(coeffs)
bounded = is_bounded_on_interval(coeffs)

3. Apply The Polynomial To A Matrix

from qsvt.matrices import diagonal_matrix
from qsvt.spectral import apply_function_to_hermitian

A = diagonal_matrix([0.9, 0.6, 0.3, 0.1])

P_A = apply_function_to_hermitian(
    A,
    lambda x: np.polynomial.polynomial.polyval(x, coeffs),
)

4. Compare Classical And QSVT Output

from qsvt.qsvt import qsvt_diagonal_transform

vals_qsvt = qsvt_diagonal_transform(
    [0.9, 0.6, 0.3, 0.1],
    coeffs,
    encoding_wires=[0, 1, 2],
)

For a complete coefficient, diagnostic, and compatibility payload:

from qsvt.workflow import design_workflow

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

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

Common Tasks

Sign Transform

from qsvt.design import design_sign_polynomial

coeffs = design_sign_polynomial(
    gamma=0.25,
    degree=13,
)

This produces a bounded odd polynomial with

\[ P(x) \approx \mathrm{sign}(x) \]

away from the transition region around zero. It is useful for spectral separation, thresholding, and projector construction.

Spectral Projector

from qsvt.design import design_projector_polynomial

coeffs = design_projector_polynomial(
    gamma=0.25,
    degree=13,
)

This approximates

\[ \frac{1 + \mathrm{sign}(x)}{2}. \]

Inverse-Like Transform

from qsvt.design import design_inverse_polynomial

coeffs = design_inverse_polynomial(
    gamma=0.25,
    degree=13,
)

This approximates

\[ \frac{\gamma}{x} \quad \text{for } |x| \ge \gamma. \]

The scaling keeps the target bounded on the design interval.

Spectral Filtering

from qsvt.design import design_filter_polynomial

coeffs = design_filter_polynomial(
    cutoff=0.4,
    degree=12,
)

This suppresses small singular values while preserving larger ones.

Matrix Functions

from qsvt.design import design_power_polynomial

coeffs = design_power_polynomial(
    alpha=0.5,
    degree=12,
)

Examples:

function

alpha

square root

0.5

square

2

cube

3

Physics-Style Workflow

The physics helpers use the same bounded-polynomial pattern:

  1. build a Hamiltonian or PDE operator,

  2. rescale its spectrum,

  3. design a bounded matrix-function polynomial,

  4. validate against a classical spectral transform.

from qsvt.hamiltonians import tight_binding_chain
from qsvt.matrix_functions import design_real_time_evolution_polynomials
from qsvt.rescaling import rescale_hermitian_to_unit_interval
from qsvt.spectral import apply_polynomial_to_hermitian

H = tight_binding_chain(8)
scaled = rescale_hermitian_to_unit_interval(H)

polys = design_real_time_evolution_polynomials(
    time=1.0,
    scale=scaled.scale,
    degree=19,
)

cos_Ht = apply_polynomial_to_hermitian(scaled.matrix, polys.cos_coeffs)
sin_Ht = apply_polynomial_to_hermitian(scaled.matrix, polys.sin_coeffs)

See Physics workflows for the detailed physics API map.

Real Problem Workflow Example

For a small concrete physics or mathematics model, start with the dense operator you want to study and use a workflow report as the reproducible record. This example filters a tight-binding Hamiltonian toward its low-energy subspace and keeps both the numerical diagnostics and the claim boundary.

import numpy as np

from qsvt.algorithms import ground_state_filtering_workflow
from qsvt.hamiltonians import tight_binding_chain
from qsvt.reports import report_to_jsonable, save_report

H = tight_binding_chain(8)
trial_state = np.ones(H.shape[0])

result = ground_state_filtering_workflow(
    H,
    trial_state,
    degree=18,
    width=0.3,
    num_points=801,
)

report = report_to_jsonable(result.as_report())

print(report["ground_energy"])
print(report["ground_state_overlap"])
print(report["operator_relative_error"])
print(report["truth_contract"]["truth_status"])
print(report["truth_contract"]["is_end_to_end_quantum_algorithm"])

save_report(report, "tight-binding-filter-report.json")

Read the fields as follows:

  • operator_relative_error and reference_state_error quantify the dense polynomial approximation for this finite instance.

  • ground_state_overlap is the physics diagnostic for whether the filter emphasized the low-energy eigenspace.

  • truth_contract states that the report validates the spectral-polynomial core and does not include block-encoding construction, state preparation, readout, amplitude amplification, or hardware costs.

For research benchmarking, pair this workflow with a resource proxy:

from qsvt.resources import qsvt_resource_report

proxy = qsvt_resource_report(
    result.coeffs,
    matrix_dimension=H.shape[0],
    attempt_synthesis=False,
    diagnostics={
        "operator_relative_error": result.operator_relative_error,
        "ground_state_overlap": result.ground_state_overlap,
    },
)

print(proxy["resources"]["degree"])
print(proxy["resources"]["signal_operator_calls"])
print(proxy["truth_contract"]["truth_status"])

The proxy helps compare polynomial degree and signal-call requirements across models or tolerances. It should be cited as a polynomial-resource proxy, not as a full quantum runtime estimate.

CLI Usage

Scalar transform:

qsvt scalar --x 0.5 --poly "0,0,1"

Diagonal transform:

qsvt diag \
  --values "1.0,0.7,0.3,0.1" \
  --poly "0,0,1" \
  --wires 3

Chebyshev evaluation:

qsvt cheb --degree 3 --x 0.5

Complete design workflow report:

qsvt design-workflow \
  --kind sign \
  --gamma 0.2 \
  --degree 13 \
  --output sign-workflow.json

Degree/error/boundedness sweep:

qsvt design-sweep \
  --kind sign \
  --degrees "5,9,13,17" \
  --gamma 0.2 \
  --no-synthesis \
  --output sign-degree-sweep.json

The sweep command writes a compact manifest with one row per degree, including sampled maximum error, RMS error, boundedness margin, and compatibility-check metadata. Use it when comparing approximation quality across candidate degrees without opening a notebook.

Resource proxy report:

qsvt resource-report \
  --poly "0,0,1" \
  --matrix-dimension 4 \
  --no-synthesis

The resource report combines polynomial degree, coefficient count, QSP phase-count proxy, signal-call proxy, optional encoding width, and compatibility metadata. It is for comparing small workflows; it is not a hardware runtime or fault-tolerant resource estimate.

Linear-system comparison report:

qsvt linear-system-compare \
  --matrix "2,0.25;0.25,1.25" \
  --rhs "1,-0.5" \
  --degree 8 \
  --no-synthesis \
  --no-qsvt \
  --output results/algorithms/linear_system_comparison.json \
  --rows-output results/tables/linear_system_comparison_summary.csv

The comparison command reports dense solve, optional conjugate gradients, QSVT-style polynomial inverse, and optional PennyLane QSVT matrix-check rows. The CSV path is a compact artifact table, not a timing benchmark.

Use qsvt examples to list workflow families, benchmark subcommands, and compact command-line examples.

Classical benchmark report:

qsvt benchmark cg-solve \
  --matrix "4,1;1,3" \
  --rhs "1,2" \
  --tolerance 1e-10 \
  --qsvt-poly "0,1"

Benchmark subcommands include eigh, dense-solve, cg-solve, polynomial, and spectral-function. They report classical baseline timings, residuals or matrix-function metadata, and optional QSVT resource proxies.

Non-diagonal Hermitian matrix report:

qsvt matrix-report \
  --matrix "0.31351701,-0.23499807;-0.23499807,0.68648299" \
  --poly "0,0,1" \
  --output matrix-report.json

When a report command is given --output or --plot, it writes the full artifact to disk and prints a compact summary to stdout. Add --print-report to also emit the full JSON payload on stdout.

Compatibility reports distinguish bounded polynomial approximation from PennyLane QSVT synthesis compatibility.

For release validation from a local checkout, run python scripts/release_check.py to execute lint, formatting, type, fast test, documentation, build, and distribution metadata checks.

Where To Go Next