Implementation Notes

This package separates dense references, small matrix verification, and QNode execution. The implementation is organized so notebooks, tests, and CLI reports can share reusable helpers without blurring which layer actually ran.

Coefficient Conventions

Most public polynomial helpers use monomial coefficients in ascending order:

[c0, c1, c2] -> c0 + c1*x + c2*x^2

Chebyshev fitting is used internally for stable approximation on bounded intervals, then converted to monomial coefficients when a public polynomial is returned. This keeps downstream evaluation simple and matches NumPy’s numpy.polynomial.polynomial.polyval convention.

Boundedness And Parity

QSVT-compatible scalar polynomials must satisfy structural constraints, including boundedness on [-1, 1] and parity constraints tied to degree.

The package separates three ideas:

  • approximation quality: sampled error against a target function,

  • boundedness: sampled maximum absolute value on a design or compatibility interval,

  • synthesis compatibility: whether PennyLane accepts the coefficients for QSVT phase synthesis.

qsvt.compatibility.qsvt_compatibility_report collects these checks without pretending they are formal proofs.

Spectral Rescaling

QSVT polynomials act on normalized spectra. The rescaling helpers store the affine map explicitly:

scaled = (matrix - offset * I) / scale

The main conventions are:

  • Hermitian spectra are mapped to [-1, 1] for general matrix functions.

  • Positive-semidefinite spectra are divided by the largest eigenvalue for positive inverse workflows.

  • Cutoff-centered rescaling is available for low-energy projector examples.

Each helper returns a ScaledOperator containing the scaled matrix, offset, scale, and original eigenvalue bounds.

Classical References

The dense reference path uses eigendecomposition:

A = V diag(lambda_i) V^*
f(A) = V diag(f(lambda_i)) V^*

This gives exact small-matrix references for polynomial transforms, matrix functions, state errors, operator errors, and density-matrix comparisons. These references are intentionally classical; they make the notebook and regression tests transparent.

PennyLane QSVT Paths

The QSVT wrappers use PennyLane where practical to build explicit small operators and compare the top-left block or transformed output against the classical polynomial reference.

The implementation treats PennyLane synthesis as a validation path, not as the only source of truth. Report commands can allow QSVT failure and still record classical polynomial behavior, which is useful for studying polynomials that are educational but not accepted by a synthesis backend.

Circuit Execution Path

qsvt.execution.execute_qsvt_circuit is the circuit-level path. It prepares a logical input state inside a PennyLane QNode, queues qml.qsvt, and measures either the final statevector (shots=None) or output probabilities (finite shots).

This path is still simulator-scale when the input operator is an explicit dense matrix, but it is a true circuit execution model for the implemented finite instance:

  • it uses QNode state preparation,

  • it queues a PennyLane QSVT operation,

  • it measures through the QNode,

  • it records circuit resource metadata from PennyLane specs,

  • it keeps the dense polynomial output as a validation reference only.

The execution helper deliberately does not call qml.matrix internally. Tests guard that boundary so the circuit path cannot silently regress into explicit unitary extraction.

The circuit report still marks is_end_to_end_quantum_algorithm = false because scalable block-encoding construction, problem-specific state preparation cost, postselection/amplitude amplification, readout/tomography, and hardware compilation are separate layers.

Reports And JSON

Diagnostics often contain NumPy arrays, complex numbers, and NumPy scalars. qsvt.reports.report_to_jsonable recursively converts those values to plain JSON-safe containers.

Report-oriented APIs follow this pattern:

  1. compute a dictionary or dataclass report,

  2. convert arrays/scalars only at the serialization boundary,

  3. keep numerical arrays available for notebooks and tests.

The CLI mirrors this behavior: report commands print full JSON by default, and write compact stdout summaries when --output or --plot is used.

Algorithm Truth Contracts

High-level workflow, direct QSVT comparison, resource, and benchmark reports include a truth_contract field generated by shared report helpers. The field is intentionally machine-readable so downstream notebooks, benchmark tables, and papers can preserve the same claim boundary as the code:

  • implementation_kind is dense-spectral-polynomial-workflow.

  • truth_status is validated_polynomial_core.

  • is_end_to_end_quantum_algorithm is false.

  • implemented_components list the dense numerical operations actually run.

  • assumed_quantum_components and omitted_quantum_costs list the layers that must be supplied separately before making a full quantum-algorithm claim.

  • pennylane_qsvt_check records whether that run attempted and succeeded at a small backend QSVT block check.

Direct qsvt-transform-report and qsvt-matrix-transform-report payloads use implementation_kind = "pennylane-small-qsvt-verification" when they compare an explicit small QSVT block against a classical polynomial reference. Circuit execution payloads use an implementation kind beginning with pennylane-qnode-... and mean that a QNode was executed, not that a scalable problem oracle or hardware deployment was supplied. Classical benchmark payloads use implementation_kind = "classical-baseline-with-optional-qsvt-proxy" and mark is_quantum_runtime_benchmark = false.

This is stricter than prose-only documentation: if a report is serialized, the assumptions travel with the numbers.

Resource Proxy Reports

qsvt.resources.qsvt_resource_report combines polynomial degree, coefficient count, QSP phase-count proxy, signal-call proxy, optional matrix-register width, QSVT compatibility metadata, and optional diagnostics into one JSON-friendly report.

Design workflow results expose the same summary through DesignWorkflowResult.resource_report(...), which carries the workflow’s diagnostics into the resource report.

The CLI exposes the same path:

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

These reports are intentionally comparative and simulator-scale. They do not include block-encoding construction, state preparation, amplitude amplification, error correction, hardware compilation, or runtime estimates.

Notebooks And Artefacts

Notebooks remain executable examples. Committed plots and JSON files are release artefacts extracted from those workflows or generated by the CLI.

The intended split is:

  • notebooks explain and visualize,

  • package helpers implement reusable operations,

  • tests protect small deterministic behavior,

  • results/ stores stable release artefacts,

  • docs summarize and link to the artefacts.

Error Metrics

The package uses simple diagnostics:

  • maximum sampled scalar error,

  • RMS sampled scalar error,

  • relative operator Frobenius error,

  • phase-aligned relative state error,

  • residual norms for linear systems,

  • overlap and expectation diagnostics for state filtering,

  • trace-density and density-matrix relative errors.

These metrics are for small-matrix validation. They should not be read as asymptotic resource estimates.

Public API Status

The package root exposes __api_status__ = "alpha" and a __public_api_policy__ string. Names in qsvt.__all__ are the intended public surface, but the project is still in the 0.x series. Incompatible changes should be documented in the changelog and should use a deprecation period when practical.

Scope Boundaries

The implementation intentionally does not provide:

  • production-scale block encoding construction,

  • problem-specific scalable state preparation methods,

  • amplitude amplification,

  • fault-tolerant synthesis,

  • hardware optimization.

Those are separate engineering layers. The package now provides circuit-level QNode execution for finite instances plus the polynomial and spectral mechanics that larger systems would use.