Lanczos

Use Eigenproblem(A=...) with Lanczos to estimate the smallest eigenvalue of A from Chebyshev moments <psi|T_k(K)|psi> of the shifted and rescaled operator K. Configure the initial state and the trial dimension on Lanczos, and supply the operator through Eigenproblem. The result is a projected Ritz value, which does not establish the smallest full-space eigenvalue.

from nwqlib import Eigenproblem, solve
from nwqlib.algorithms import Lanczos, LanczosResult, SensitivitySampling

The construction follows Kirby, Motta and Mezzacapo, arXiv:2208.00567v4, Sections 2.1–3.1. The shift and rescaling follow Oumarou et al., arXiv:2603.15552v1, whose sensitivity allocation NWQLib adapts, and the thresholded pencil solve follows Epperly, Lin and Nakatsukasa, arXiv:2110.07492v2, Algorithm 1.1. The Lanczos guide explains the cutoff analysis and sensitivity sampling, and its source and code map gives the equation, page and implementing function of each step.

Configure the method

Lanczos

Bases: Method

Chebyshev Lanczos method for the smallest eigenvalue of an Eigenproblem.

Build it with keyword arguments and pass it as method=, for example solve(Eigenproblem(A=matrix), method=Lanczos(krylov_dimension=4)). Every argument is optional. The result is a LanczosResult whose eigenvalue is the lowest Ritz value of the target in the trial space span{T_k(K)|psi>, k<m} (Kirby, Motta and Mezzacapo, arXiv:2208.00567v4, Section 3.1). Here |psi> is the initial state, and K = (A - center*I) / alpha is A shifted and scaled so that its spectrum lies in [-1, 1] (Oumarou et al., arXiv:2603.15552v1, Section 2, Eqs. (1) and (4)). A projected Ritz value does not identify the ground state. Quantum execution obtains the moments through the qubitized walk, and classical execution evaluates the same moments with the three-term recurrence. Both feed one projected solve. The four overlap_* settings can be changed after the run with result.analyze(...), which reuses the same moments. The Lanczos guide describes the construction, the cutoff analysis and sensitivity sampling.

Attributes:

• initial_state (StateData | None) –

  Default None. Reference state |psi>. None draws the Method's default reference from the planning random generator. A Problem with an explicit sector requires a supplied state.

• krylov_dimension (PositiveInt | None) –

  Default None, which selects min(8, d) for problem dimension d. Trial dimension m, a positive integer that must not exceed d.

• degrees (tuple[PositiveInt, ...] | None) –

  Default None, which requests every degree 1 to 2m-1. Distinct positive moment degrees below 2m.

• overlap_cutoff (Real | None) –

  Default None. Positive cutoff on the Gram (overlap) eigenvalues. None uses overlap_cutoff_policy, or the numerical floor 1e-12 for exact moments.

• overlap_cutoff_policy (Literal['empirical', 'confidence']) –

  Default "empirical", empirical noise filtering. "confidence" selects explicit confidence regularization. Neither establishes the accuracy of the Ritz energy.

• overlap_noise_multiplier (Real) –

  Default 1.0. Positive scale of the empirical Gram RMS noise, a tunable exploratory threshold.

• overlap_failure_probability (Real) –

  Default 0.05, strictly between 0 and 1. Tail probability of the reported Gram sampling bound under independent bounded shots.

• sampling (SensitivitySampling | None) –

  Default None. A two-stage SensitivitySampling shot allocation. It conflicts with shots= and with classical execution.

• max_bytes (PositiveInt) –

  Default 10 GB (decimal, 10_000_000_000 bytes). Limit on the known bytes of input, moments and projected numerical workspace.

• max_analysis_work (PositiveInt) –

  Default 1e8. Limit on the work of the projected analysis, including matrix assembly and solve. Planning checks it before any moment is obtained.

• max_classical_products (PositiveInt) –

  Default 1e8. Limit on the counted classical Chebyshev operator applications.

• input_conversion (Literal['auto', 'dense_pauli']) –

  Default "auto", which keeps the accepted input access. "dense_pauli" permits explicit dense-to-Pauli conversion, which quantum execution needs for sparse input and for dense input of dimension above 16.

• max_conversion_work (PositiveInt) –

  Default 1e8. Limit on the work of operator conversion, counted as q*D² transform work, where D includes the quantum embedding. It is not a time estimate.

Examples:

H = ZZ + 0.5*(XI + IX) on two qubits has lowest eigenvalue -sqrt(2) = -1.4142135623..., which a three-dimensional trial space built from |00> recovers on Aer with exact readout:

>>> from qiskit.quantum_info import SparsePauliOp
>>> from nwqlib import Eigenproblem, solve
>>> from nwqlib.algorithms import Lanczos
>>> H = SparsePauliOp.from_list([("ZZ", 1), ("XI", 0.5), ("IX", 0.5)])
>>> method = Lanczos(initial_state=[1, 0, 0, 0], krylov_dimension=3)
>>> result = solve(Eigenproblem(A=H), method=method, seed=7)
>>> print(round(result.eigenvalue, 10))
-1.4142135624

SensitivitySampling

Bases: Record

Two-stage shot allocation for Lanczos, weighted by each moment's effect on the energy.

Build it with keyword arguments, for example SensitivitySampling(total_shots=1400, pilot_fraction=0.2), and pass it as Lanczos(sampling=...). Both arguments are required. It replaces shots=, which must then be omitted, and it conflicts with classical execution. A pilot stage spends about pilot_fraction of the shots uniformly. One allocation decision then weights the main stage by each moment's pilot energy sensitivity, following the measured-pilot suggestion of Oumarou et al., arXiv:2603.15552v1, Section 3.3.2. Only main-stage moments enter the final estimate. The weights abs(g_k)*sqrt(v_k), the pilot floor and the fallback rules are NWQLib's choices, described in the Lanczos guide. The allocation is an empirical rule, not a proven optimum. Because the main stage allocates its shots from the pilot, prepare(plan, settings="all") is refused, and prepare(plan) prepares the next setting.

Attributes:

• total_shots (PositiveInt) –

  Required. Positive number of shots across both stages and all settings, at least four per setting.

• pilot_fraction (Real) –

  Required, strictly between 0 and 1. Requested pilot share of total_shots, adjusted so that each stage keeps two shots per setting.

Read the result

LanczosResult

Bases: Result

Projected estimate of the smallest eigenvalue from a Lanczos run.

solve returns it for a Lanczos method, and load_result reopens a saved one. The answer is eigenvalue, the lowest physical Ritz value center + alpha*x, in the unit of the Eigenproblem. Here center and alpha shift and scale A so that (A - center*I) / alpha has its spectrum in [-1, 1] (Oumarou et al., arXiv:2603.15552v1, Section 2, Eqs. (1) and (4)), and x is the lowest Ritz value of that rescaled operator. eigenvalue is None when no Ritz value is available, and failure then gives the reason. The value is a projected estimate with unresolved error sources, and it does not establish the smallest full-space eigenvalue. print(result) shows it with its cutoff and rank notes, and result.analyze(...) recomputes it from the same moments with other overlap_* settings. The fields below are read-only. The fields of Result are present too.

result.plan.reconstruction stores center, alpha and the trial dimension m as krylov_dimension, so overlap and hamiltonian are m by m, in raw Chebyshev coordinates of the trial basis rather than the full Hilbert space. Missing moments are None. Moments shared by several pencil entries make those entries correlated, and moment_variances are empirical values, not confidence bounds.

Attributes:

• eigenvalue (Real | None) –

  Lowest physical Ritz value center + alpha*x of the pencil after the Gram eigenvalues at or below cutoff are discarded, or None when unavailable.

• eigenvalues (tuple[Real, ...] | None) –

  Physical Ritz values of the kept pencil in ascending order.

• coefficients (tuple[Real, ...] | None) –

  S-normalized lowest Ritz vector in raw Chebyshev coordinates.

• moments (tuple[Real | None, ...]) –

  mu_0 to mu_(2m-1), with mu_k = <psi|T_k(K)|psi> for the normalized initial state, used by the analysis, None where missing.

• moment_variances (tuple[Real | None, ...]) –

  Empirical sample-mean variance per moment, 0 for known moments and None when unavailable.

• hamiltonian (tuple[tuple[Real, ...], ...] | None) –

  Physical projected matrix center*S + alpha*K_proj, where K_proj_ij = (mu_(i+j+1) + mu_|i+j-1| + mu_|i-j+1| + mu_|i-j-1|)/4 is K projected onto the trial space, or None when not representable.

• overlap (tuple[tuple[Real, ...], ...] | None) –

  Raw Chebyshev Gram matrix S_ij = (mu_(i+j) + mu_|i-j|)/2. Its diagonal need not equal one.

• kept_rank (int | None) –

  Number of kept directions, the overlap eigenvalues above the cutoff.

• projected_backward_error (Nonnegative | None) –

  Dimensionless backward error ||K_proj c - x S c|| / ((||K_proj||_F + |x| ||S||_F) ||c||) of the lowest pair (x, c) of the normalized pencil (K_proj, S) that the solve uses, with K_proj = (H - center S) / alpha and x = (E - center) / alpha. Adding c_I I to a Pauli input, or scaling it by a positive factor, leaves K_proj and this value unchanged in exact arithmetic. For a matrix input the Gershgorin enclosure that sets center and alpha is widened by a roundoff allowance proportional to |center|, so an offset c_I changes alpha and the value by a relative amount of order eps |c_I| / alpha. FixedGCIM and ADAPT state theirs on the physical pencil (H, S) instead, so the two values are not comparable.

• overlap_normalization_error (Nonnegative | None) –

  Defect in c^dagger S c = 1 for the returned coefficients.

• overlap_spectrum (tuple[Real, ...] | None) –

  Eigenvalues of S before thresholding.

• cutoff (Real | None) –

  Overlap-eigenvalue cutoff that the analysis applied.

• cutoff_source (Literal['scalar_operator', 'not_evaluated', 'user_fixed', 'deterministic_default', 'hoeffding_gram_bound', 'unavailable_sampling_population', 'empirical_gram_rms', 'unavailable_empirical_variance']) –

  Rule that set the cutoff.

• gram_sampling_bound (Nonnegative | None) –

  m*e with e = sqrt(2*log(2*r/delta)/n_min), where m is krylov_dimension, r counts the sampled moments that enter S, n_min is the smallest of their shot counts and delta is analysis_failure_probability. With probability at least 1 - delta it bounds the spectral norm of the Gram sampling error, provided the shots are independent outcomes in [-1, 1] and the measurements are unbiased (Hoeffding (1963), doi:10.1080/01621459.1963.10500830, Theorem 2, Eq. (2.6), p. 16, made two-sided as in Eq. (1.4), p. 13, with a union bound over the r moments). Proposition 12 derives ||Delta S||_2 <= ||Delta S||_F <= m*e from the moment errors. It is independent of the cutoff policy. It does not bound the error of eigenvalue.

• empirical_gram_noise_frobenius_rms (Nonnegative | None) –

  Estimate, from sample variances, of the root-mean-square Frobenius norm of the same Gram sampling error, without a coverage claim. It does not bound the error of eigenvalue.

• failure (Text | None) –

  Reason no Ritz value is available, or None.

• missing (tuple[int, ...]) –

  Moment degrees without data.

• statistics (tuple[tuple[int, MomentStatistics], ...]) –

  Pooled per-degree moment statistics that entered the analysis.

• physical_scale (PhysicalScale) –

  Physical scale of the supplied reference state.

• subspace (InputRef) –

  Reference, by content hash, to the Chebyshev trial subspace that the Plan chose.

• selected_construction_ids (tuple[ContentID, ...]) –

  Content hash of the circuit construction behind each entry of contribution_ids, in the same order.

• analysis_cutoff (Real | None) –

  Cutoff requested for this analysis, or None for the default rule.

• analysis_cutoff_policy (Literal['empirical', 'confidence']) –

  Empirical or confidence policy requested for this analysis.

• analysis_noise_multiplier (Real) –

  Empirical-noise multiplier used by this analysis.

• analysis_failure_probability (Real) –

  Tail probability used for this analysis's Gram sampling bound.

• target_identification (Text) –

  Statement that the value is a projected estimate, not an identified ground state.

projected_diagnostics

projected_diagnostics()

Return the stored Gram matrix and solve diagnostics for projected checks.

It reads stored fields and runs no reconstruction or solve. result.verify(checks=ProjectedVerificationOptions(...)) uses it.

Returns:

• diagnostics ( ProjectedDiagnostics ) –

  Its overlap, spectrum, normalization and backward_error are this Result's overlap, overlap_spectrum, overlap_normalization_error and projected_backward_error, in raw Chebyshev coordinates.

MomentStatistics

Bases: Record

Sample mean and second moment of one acquired Chebyshev moment, with its shots.

LanczosResult.statistics pairs each acquired degree with one. The property variance is the unbiased sample-mean variance (second_moment - mean**2)/(shots - 1), an empirical value only, and None without shots or for one shot. The fields below are read-only.

Attributes:

• mean (Real) –

  Mean of the per-shot values of the moment.

• second_moment (Real) –

  Mean of their squares.

• shots (PositiveInt | None) –

  Shots behind the mean, or None for a numerical marginal.

solve calls plan and the other hooks of a Method. Extending NWQLib describes them.