qasp.expressivity_analyzer computes the Fourier series of an encoded circuit at its current weights. Pass an RL policy, Q-function, classifier, fidelity kernel, or projected kernel using QASP’s AngleEmbedding or NeuralEmbedding with AngleAnsatz, IQPAnsatz, or an encoding-only kernel.
from qasp import expressivity_analyzer
s = expressivity_analyzer(model, observables=["X 0", "Z 0"])
print(s.output_labels, s.n_frequencies, s.active_counts)
for omega, c, magnitude in zip(s.frequencies, s.coefficients, s.magnitudes):
print(omega, c, magnitude)
expectations = s.evaluate(x) # one value per observable, also accepts batchesFor output
Allowed and active frequencies. Each Pauli rotation through s.n_frequencies counts distinct allowed vectors, including DC. s.active_counts[a] counts rows with atol (default
The cross-module notebook checks each model family against direct outputs and plots complex coefficients across qubit widths.
With explicit observables, each output is a separate expectation on the configured circuit. Accepts QASP Pauli strings or fixed Hermitian PennyLane operators. Omitting the argument selects the following readouts.
| Model | Fourier outputs |
|---|---|
PQCSoftmax |
Forward logits including output scaling and the affine head, before softmax |
PQCBornVariance (factory name PQCBorn) |
Decoded action probabilities before optional softmax. Local Pauli sampling mode returns the measured expectations. |
Legacy PQCBorn / adaptive LearnablePQCBorn |
The legacy sampler exposes its basis probabilities or expectations. The adaptive policy requires explicit fixed observables. |
PQDQN |
Q-values including the current affine head and bias. With the default input activation, reconstruct as s.evaluate(np.tanh(state)). |
PQCClassifier |
Grouped, scaled expectation scores or decoded Born probabilities before temperature/scale calibration |
FidelityKernel |
The mean of its configured global or local overlap projectors |
ProjectedKernel |
The labeled observable features before the Gaussian kernel |
The finite series applies to the ideal circuit and its affine readouts. Sampling noise, truncated simulation and nonlinear classical activations can change the predictions. The legacy Fisher score kernel uses discrete bit strings and has no continuous input embedding.
For a fidelity kernel, the default expansion varies both reference=y0 to obtain a smaller single-input spectrum for a fixed comparison point.
joint = expressivity_analyzer(fidelity_kernel)
k_xy = joint.evaluate(x, y)[0]
slice_at_y = expressivity_analyzer(fidelity_kernel, reference=y)
k_xy_from_slice = slice_at_y.evaluate(x)[0]
# Reconstruct the full projected kernel from the finite feature spectra.
import numpy as np
features = expressivity_analyzer(projected_kernel)
delta = features.evaluate(x) - features.evaluate(y)
k_xy_projected = np.exp(-projected_kernel.gamma * np.sum(projected_kernel.weights * delta**2))Supply a factory that builds or loads the intended model at each width. To isolate the effect of width, keep the input features and weight preparation comparable. An observable factory can choose the corresponding operator on each register.
sweep = expressivity_analyzer(
model_factory=make_classifier,
qubit_list=[2, 4, 6, 8],
observables=lambda n: ["Z 0", "Z" * n],
)
print(sweep.frequency_counts) # aligned with qubit_list
print(sweep.summary()) # counts, peak magnitude and non-DC power per readout
s4 = sweep.results_by_qubit[4] # retains every frequency, coefficient and magnitudeThe runnable plotting example encodes one scalar as
The analyzer traces the encoding with the current scale tensors, then evaluates an ideal statevector circuit on a grid of independent gate phases. A direction used
The product of the grid sizes can grow exponentially. n_evaluations reports the grid size used. The default max_evaluations=65_536 applies per width and can be raised explicitly. The implementation also bounds statevector batches, total circuit wires (21, including ancillas) and the output array (four million phase-grid/output entries). A fixed reference can reduce the cost of a fidelity spectrum.
tools/validate_expressivity.py compares complete complex spectra with a separate spectral-projector density-matrix calculation. It covers unscaled/scaled AngleEmbedding with one or n features and one/two uploads, plus NeuralEmbedding with one/two features on one/all wires. Both commuting and entangled circuits are tested through classifier scores, policy logits, and classifier/policy parity and strict-majority probabilities. The commuting cases are also checked against closed-form coefficient convolutions.
Run from this source checkout:
python tools/validate_expressivity.py --source . --output /tmp/qasp-fourier-validationThe default matrix uses widths 2, 3, 4 and seeds 17, 29, 43. It writes full spectra, actual parameters, direct evaluations, and summary tables. The regression wrapper in tests/test_expressivity_reference.py runs the same matrix at widths 2 and 3 with one seed. These are finite configuration checks, not a proof covering every circuit the library can construct.
The executed training workflow compares a classifier, a softmax policy, and a Born policy. Save the initial spectrum, train the same model, and recompute:
initial = expressivity_analyzer(model)
# Run your existing classifier or policy training loop here.
final = expressivity_analyzer(model)
print(initial.active_counts, final.active_counts)Each result is a snapshot. It does not change when the model is trained later. The analyzer preserves model weights, existing gradients, and training mode. For fixed unscaled encodings the allowed frequencies stay fixed, although their coefficients can change. Learned input scales and neural projections can change frequency locations too. Compare predictions, coefficient magnitudes and non-DC power as well as active counts; a larger count is not a guarantee of better learning. Softmax policy spectra reconstruct logits, not the nonlinear softmax; apply softmax to reconstructed logits if action probabilities are needed.
The regression matrix trains binary classifiers (expectation and probability readouts), softmax and Born policies, with Angle/Neural embeddings, fixed/learned scales, Angle/IQP ansätze, two initializations, and multiple qubit widths. Policy tests optimize exact expected reward on a small contextual bandit. These are short correctness experiments, not evidence of convergence on a benchmark. Each snapshot is checked against direct outputs at independent inputs, with complex conjugate symmetry and snapshot/state-preservation checks. A structured width sweep through 16 qubits additionally checks every coefficient against cos(x) and cos(x)^n. Nine CPU execution settings are compared where supported; VN uses exact enumeration in this regression matrix.
Analysis itself uses an ideal statevector circuit, independently of the model's execution backend. Consequently it does not inherit a simulator's large-qubit scaling or model noise, sampling error, or Pauli truncation. General independent input directions can make the Fourier grid exponential, even when a structured shared-input sweep is inexpensive. Guardrails still apply.
To rerun the training matrix and retain the complex spectra:
PYTHONPATH=.:tests QASP_EXPRESSIVITY_RESULTS=validation/expressivity/training \
python -m pytest tests/test_expressivity_training.py -qEach training case writes before/after frequency vectors and complex coefficients
in an .npz file, together with inputs, reconstructed predictions and losses.
Adjacent JSON files summarize active counts and non-DC power. For a combined
installed-wheel audit, build/install the candidate first and run
QASP_VALIDATION_OUTPUT=validation/expressivity/installed python tools/validate_installed_configuration.py.