Accuracy and verification¶

Check a Result against an accuracy tolerance, run a Method's verification checks, and keep both together in a Certificate. The Check accuracy and verify a result guide explains each check and what it costs.

from nwqlib.evidence import Certificate
from nwqlib.evidence.verification import ProjectedVerificationOptions

Both operations read what a Result already holds: its error bounds, result.facts, and its stored data. Neither runs the Method again, and only an explicit verify call computes new check values.

Check a result against a tolerance¶

result.assess combines the Result's error bounds and returns a ClaimAssessment whose status answers whether the error is within the tolerance:

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

problem = Eigenproblem(A=[[1.5, -1], [-1, 0.5]])
method = Lanczos(initial_state=[1, 0], krylov_dimension=2)
result = solve(problem, method=method, seed=7)

total = result.assess(absolute_tolerance=1e-6)
print(total.status)
print(total.remaining)
sampling = result.assess(absolute_tolerance=1e-6, component="sampling")
print(sampling.status, sampling.covered_subtotal.numerator)

INCONCLUSIVE
('native_preparation', 'native_simulation', 'projected_solve', 'ground_identification', 'physical_model')
PASS 0

The total-error criterion is INCONCLUSIVE because five of the error sources that Lanczos lists have no bound. INCONCLUSIVE does not mean the error exceeds the tolerance. With exact readout and no random draw, the sampling error is zero by definition, so the sampling component passes. A component criterion never covers total error. A relative criterion, result.assess(relative_tolerance=0.05, reference=reference), needs a TargetReference that sets the scale.

Each entry of result.facts is a FramedFact: a value with its frame and its evidence. The frame, an ErrorFrame, names the quantity, metric, unit, scope and conditions the value refers to. The kind of its Evidence says whether the value is a proof, a certified bound, a numerical estimate, an observation or an assertion, and the value is witnessed when its evidence names the record of the computation that produced it. Only witnessed proofs and certified bounds without open assumptions can make an assessment pass.

Run a verification check¶

result.verify(checks=options) runs the checks that one options record selects and returns (receipt, facts). receipt is the VerificationReceipt of this computation, with its raw values and numerical calls, and facts holds one FramedFact per check that cites receipt. Result.verify accepts these options records:

Options record	Methods	Returned `facts`
`ProjectedVerificationOptions`	Lanczos, FixedGCIM, ADAPT	One per selected criterion
`EnergyShiftOptions`	Lanczos, FixedGCIM	The energy-shift discrepancy
`NumberSectorOptions`	QHD with the one-hot encoding	The observed number-sector leakage
`AdaptVerificationOptions`	ADAPT	One per scalar of the selected checks
`LCHSVerification`	LCHS	The reference discrepancy, and for `ivp_closed_form` the reference consistency
`LCHSRefinement`	LCHS	Refined output-error components for `result.assess`, which answer no check
`QLSVerification`	QLS	The top-level fact of each selected comparison
`QPEVerification`	QPE	`component_error` and `overlap_deficit`
`QHDVerification`	QHD	`grid_minimum` and the infidelity of each selected fidelity comparison

The projected, energy-shift and number-sector checks read values the Results already store. The verification guide defines what each one computes and what it does not show: projected quantities, two-result energy shift and measured number-sector leakage. The other checks can compute a reference solution, and the guide's cost table states what each one costs.

Keep an assessment and its checks together¶

A Certificate holds one assessment and the checks attached to it with with_verification. Continuing the example above:

from nwqlib.evidence import Certificate
from nwqlib.evidence.verification import ProjectedVerificationOptions

options = ProjectedVerificationOptions(
    name="projected",
    comparisons=("gram_hermiticity", "gram_psd_deficit"),
    tolerance=1e-10,
)
receipt, facts = result.verify(checks=options)
certificate = Certificate(plan_id=result.plan_id, result_id=result.content_id,
                          assessment=total, checks=())
certificate = certificate.with_verification(result, options=options,
                                            evidence=facts)
for check in certificate.checks:
    print(check.status, check.fact.fact.quantity)
print(certificate.assessment.status)

PASS projected.gram_hermiticity
PASS projected.gram_psd_deficit
INCONCLUSIVE

Both checks pass their own threshold, and the assessment stays INCONCLUSIVE, because a check concerns its own scalar only. The returned facts attach only with the options object that produced them. To use another tolerance, run result.verify again with the new options.

Exact comparisons check the bit length of each numerator and denominator against max_integer_bits, default 4096, before every operation, and refuse rather than round (engineering constants). This limits the size of exact numbers, not time or memory.

Verification options¶

ProjectedVerificationOptions ¶

Bases: Record

Options of the projected checks of a Lanczos, FixedGCIM or ADAPT Result.

Build it with keyword arguments, for example ProjectedVerificationOptions(name="projected", comparisons=("gram_psd_deficit",), tolerance=1e-10), and pass it to result.verify(checks=...) or verify_projected. name, comparisons and tolerance are required. Each criterion is a dimensionless value on [0, inf), compared with tolerance as an acceptance threshold. Nothing is repaired, and the values are read from what the Result already stores (result.projected_diagnostics()), so no solve runs again:

overlap_normalization: the stored absolute error of the coefficient vector's normalization in the overlap (Gram) matrix S.
gram_psd_deficit: max(0, -min(spectrum)) of the raw overlap spectrum, before positive-subspace filtering.
gram_hermiticity: the largest absolute real or imaginary component of S - S† of the stored overlap matrix.
projected_backward_error: the stored backward error of the projected generalized eigenproblem, on the normalized pencil (K, S) for Lanczos and on the physical pencil (H, S) for FixedGCIM and ADAPT. Equal thresholds mean different things for the two, so compare values only within one family (formula in the verification guide).

The criteria concern the projected problem only. They give no full-state residual, ground-state identification or total physical-error bound.

Attributes:

name (Text) –

Required. Prefix of the check names, which are name + "." + criterion.
comparisons (tuple[ProjectedCriterion, ...]) –

Required. Nonempty tuple of distinct criteria from the list above.
tolerance (Nonnegative) –

Required. Nonnegative threshold shared by the criteria.

Raises:

ValueError –

If comparisons is empty or repeats a criterion.

verify_projected ¶

verify_projected(result, *, options: ProjectedVerificationOptions, max_integer_bits=DEFAULT_MAX_INTEGER_BITS)

Run the projected checks on a Result's stored diagnostics, without solving again.

result.verify(checks=options) calls this for Lanczos, FixedGCIM and ADAPT. The Result must supply projected_diagnostics(). The criteria concern the projected problem only, not a full-state residual or ground-state identification.

Parameters:

result (Result) –

A Lanczos, FixedGCIM or ADAPT Result with its Plan.
options (ProjectedVerificationOptions) –

The selected criteria.
max_integer_bits (int, default: DEFAULT_MAX_INTEGER_BITS ) –

Bit limit of the exact arithmetic. Default 4096.

Returns:

verification ( tuple ) –

(receipt, facts): the VerificationReceipt of this computation, and one FramedFact per criterion that cites it. A criterion whose stored value is missing gives an unknown fact.

Raises:

TypeError –

If options is not a ProjectedVerificationOptions, or the Result supplies no projected diagnostics.

ProjectedDiagnostics ¶

ProjectedDiagnostics(overlap: tuple | None, spectrum: tuple | None, normalization: float | None, backward_error: float | None)

The stored diagnostics of a projected eigenvalue solve: overlap matrix, its spectrum and two error values.

result.projected_diagnostics() returns it for a Lanczos, FixedGCIM or ADAPT Result, and the checks of ProjectedVerificationOptions read it. It holds values the solve already produced, in the Method's own coordinates, so getting it runs no solve, reconstruction or decomposition. A value the Result did not store is None. The fields below are read-only.

Attributes:

overlap (tuple | None) –

The overlap (Gram) matrix S of the trial basis, as rows: the raw Chebyshev Gram matrix of Lanczos, with float entries, or the acquired matrix of FixedGCIM and ADAPT, completed from its upper triangle by conjugation, with Complex128 entries. None when unavailable.
spectrum (tuple | None) –

The eigenvalues of S before the overlap cutoff, negative ones included. None when unavailable.
normalization (float | None) –

abs(c† S c - 1) for the coefficient vector c of the reported, lowest Ritz pair, or None.
backward_error (float | None) –

The dimensionless backward error ||A c - x S c|| / ((||A||_F + |x| ||S||_F) ||c||) of the lowest Ritz pair (x, c), or None. Lanczos states it on the normalized pencil (K, S) of its solve, with K = (H - center S) / alpha and x = (E - center) / alpha. FixedGCIM and ADAPT state it on the physical pencil (H, S) in the Problem's energy unit, with x = E. Equal thresholds therefore mean different things for Lanczos and for FixedGCIM and ADAPT (verification guide).

EnergyShiftOptions ¶

Bases: Record

Options of the energy-shift check, which compares an energy Result with a saved baseline for H_target = H_baseline + c I.

Build it with for_result from the baseline Result, for example EnergyShiftOptions.for_result(baseline, name="shift", shift=0.5, tolerance=1e-10), and pass it to the target's result.verify(checks=...) or verify_energy_shift. It applies to Lanczos and FixedGCIM Results.

The check reports abs(E_target - E_baseline - c) in the output unit, on [0, inf), against tolerance. With the trial space held fixed, every Ritz value shifts by exactly c in exact arithmetic, so the value is zero in exact arithmetic. The verification guide derives this (Kirby, Motta and Mezzacapo, arXiv:2208.00567v4, Eq. (14)) and states what the value measures for exact, classical and sampled moments. This comparison is NWQLib's own design.

Both Results must share the output frame and sector. With relation="pauli_table" or "matrix_entries", the check first establishes H_target - H_baseline = c I exactly from the stored binary64 operator tables, with absent entries meaning zero. It also requires the same basis, unit, preparations and subspace rule and order, so that the two trial spaces are the same. A valid operator relation does not imply a zero discrepancy between independently rounded or sampled Ritz values. With relation="asserted" the stated assumption stays an open prerequisite, which keeps the check INCONCLUSIVE, and numerical agreement does not prove it. Neither workload runs again.

Attributes:

name (Text) –

Required. Prefix of the check name, which is name + ".energy_shift".
baseline (EnergyEndpoint) –

Required. Energy endpoint of the saved baseline Result. for_result fills it.
shift (Real) –

Required. The constant c in H_target = H_baseline + c I, in the output unit.
tolerance (Nonnegative) –

Required. Nonnegative threshold on abs(E_target - E_baseline - c).
relation (Literal['pauli_table', 'matrix_entries', 'asserted']) –

Default "pauli_table", and for_result picks the table kind of the baseline. How the operator relation is established: "pauli_table" or "matrix_entries" for an exact comparison, "asserted" for a stated assumption.
assertion (Text | None) –

Default None. The stated assumption, set exactly when relation="asserted".

Raises:

ValueError –

If assertion is set without relation="asserted" or missing with it.

for_result ¶

for_result(result, **choices)

Build options with result as the baseline and its operator table kind as the default relation.

Parameters:

result (Result) –

The baseline Lanczos or FixedGCIM Result, with its Plan.
**choices (object, default: {} ) –

The other fields, name, shift and tolerance, and optionally relation and assertion.

Returns:

options ( EnergyShiftOptions ) –

Options with the baseline's energy endpoint.

Raises:

TypeError –

If the Result has no saved energy endpoint.

verify_energy_shift ¶

verify_energy_shift(result, *, options: EnergyShiftOptions, max_integer_bits=DEFAULT_MAX_INTEGER_BITS)

Run the energy-shift check of a target Result against the baseline in options, running neither method again.

result.verify(checks=options) calls this for Lanczos and FixedGCIM. The target's stored energy, operator table and preparations are read once. The exact operator relation is checked first, and the discrepancy abs(E_target - E_baseline - c) is computed in exact arithmetic.

Parameters:

result (Result) –

The target Lanczos or FixedGCIM Result, with its Plan.
options (EnergyShiftOptions) –

The baseline, shift and tolerance.
max_integer_bits (int, default: DEFAULT_MAX_INTEGER_BITS ) –

Bit limit of the exact arithmetic. Default 4096.

Returns:

verification ( tuple ) –

(receipt, facts): the VerificationReceipt of this comparison, and a one-element tuple with the discrepancy as a FramedFact that cites it. The fact is unknown when either energy is missing.

Raises:

TypeError –

If options is not an EnergyShiftOptions, or the Result has no saved energy endpoint.
ValueError –

If the Results differ in frame or sector, basis, unit, preparations or subspace rule, or the stored tables do not establish the relation exactly.

NumberSectorOptions ¶

Bases: Record

Options of the number-sector check: the fraction of measured shots outside Hamming weight N.

Build it with keyword arguments, for example NumberSectorOptions(name="number", particles=1, tolerance=0.01), and pass it to result.verify(checks=...) or verify_number_sector. name, particles and tolerance are required. The checked value is the fraction of stored complete-register shots whose bitstring does not have exactly N ones, on [0, 1], against tolerance. It needs a Result that stores complete computational-register counts, such as QHD with the one-hot encoding (verification guide).

This observed fraction differs from the mean particle number, and zero observed leakage does not prove that a pure state lies in the sector. The guide gives a counterexample for the mean.

Attributes:

name (Text) –

Required. Prefix of the check name, which is name + ".number_sector_leakage".
particles (Count) –

Required. Hamming weight N of the sector, at most the measured register width.
tolerance (Nonnegative) –

Required. Threshold on the observed fraction outside N, in [0, 1].

Raises:

ValueError –

If tolerance exceeds 1.

verify_number_sector ¶

verify_number_sector(result, *, options: NumberSectorOptions, max_integer_bits=DEFAULT_MAX_INTEGER_BITS)

Run the number-sector check on a Result's stored counts, running no analysis or circuit again.

result.verify(checks=options) calls this for QHD. The particle number of an outcome is the number of set bits of its index, over all words for a register wider than 64 bits. The total and the outside count are exact integer sums of the counts, and the value outside/total is exact.

Parameters:

result (Result) –

A Result that stores complete computational-register counts, with its Plan.
options (NumberSectorOptions) –

The sector and tolerance.
max_integer_bits (int, default: DEFAULT_MAX_INTEGER_BITS ) –

Bit limit of the exact arithmetic. Default 4096.

Returns:

verification ( tuple ) –

(receipt, facts): the VerificationReceipt of this computation, and a one-element tuple with the leakage fraction as a FramedFact that cites it. The fact is unknown when no shots were counted.

Raises:

TypeError –

If options is not a NumberSectorOptions.
ValueError –

If the Result supplies no complete-register counts, particles exceeds the register width, or the stored counts are not unconditional counts of the whole register that sum to the returned shots.

Verification records¶

VerificationReceipt ¶

Bases: Record

The record of one verification: what was checked, the reference, and each numerical call with its raw values.

result.verify(checks=...) returns it as the first element of (receipt, facts), and so do verify_projected, verify_energy_shift and verify_number_sector. The raw values sit in the facts of each entry of applications. Each returned fact with a value cites this verification record: its fact.evidence.artifact is receipt.content_id. Loading a saved verification record creates no new invocation and repeats no computation. A missing verification record does not show whether a reference ran, and two verification records do not show that their calls were statistically independent. The fields below are read-only.

Attributes:

schema_version (Literal[2]) –

Format version of the record, 2.
plan_id (ContentID) –

Content hash of the Plan of the checked Result.
invocation_id (Text | None) –

Identifier of the verify call that produced the record, which tells two calls with equal inputs apart. None for a record built by hand or of unknown origin.
result_id (ContentID) –

Content hash of the checked Result.
construction_id (ContentID) –

Content hash of the construction of that Plan.
artifact_ids (tuple[ContentID, ...]) –

Content hashes of the stored arrays that the check read, distinct. Empty when it read none.
reference (Source) –

The Source of the reference computation or check.
options_id (ContentID) –

Content hash of the options record passed to verify.
applications (tuple[KernelApplication, ...]) –

The numerical calls, each a KernelApplication with a distinct name.

Examples:

Compare an LCHS solution with the matrix exponential, then read the raw discrepancy and the call counts from the verification record:

>>> import numpy as np
>>> from nwqlib import LinearDynamics, solve
>>> from nwqlib.algorithms import LCHS
>>> from nwqlib.algorithms.lchs import LCHSVerification
>>> A = np.array([[0.4, 0.15], [0.05, 0.25]])
>>> problem = LinearDynamics(A=A, initial_state=[1.0, 0.0], time=0.1)
>>> result = solve(problem, method=LCHS())
>>> checks = LCHSVerification(reference="expm", metric="absolute_l2",
...                           threshold=0.01)
>>> receipt, facts = result.verify(checks=checks)
>>> call = receipt.applications[0]
>>> for fact in call.facts:
...     print(fact.fact.quantity, fact.fact.value.value)
reference_error 0.0008214720329548587
reference_error.reference_norm 0.9608378411789008
>>> counts = {item.parameter: item.value for item in call.arguments}
>>> print(counts["expm_completed"], counts["matvec_completed"])
1 1
>>> print(facts[0].fact.evidence.artifact == receipt.content_id)
True

KernelApplication ¶

Bases: Record

One classical numerical call, with its arguments and the raw values it produced.

A VerificationReceipt lists the calls of one verification in applications, and an observation computed by a classical routine lists its calls the same way. The fields below are read-only.

Attributes:

name (Text) –

Name of the call, distinct within its record, for example reference_error for the expm reference of an LCHS check.
implementation (Source) –

The Source that names the routine, its version, domain and literature reference. It describes the routine and cannot load it.
arguments (tuple[Binding, ...]) –

The parameters that the Method set for the call, as Binding records with distinct names, including schedule counts. The LCHS reference records the attempted and completed numerical calls here, for example expm_attempts and expm_completed.
facts (tuple[FramedFact, ...]) –

The raw values of the call, each a FramedFact with its error frame. A value the call could not compute keeps the evidence that says why.

Assessments and certificates¶

ClaimAssessment ¶

Bases: Record

The outcome of checking a Result against an accuracy criterion.

Result.assess returns it (see Check a result against a tolerance). The answer is status:

PASS: every error source the Method lists has a bound that applies at the assessed point and, with its conditions and inputs, has witnessed proved or certified support and no open assumption. The sum of the bounds is at most threshold, and their combined failure probability meets the requested confidence.
INCONCLUSIVE: otherwise. remaining lists the sources without a bound, unverified the bounded sources without that support, and prerequisites the reasons. A sum of bounds above the threshold is INCONCLUSIVE, not evidence that the error exceeds the tolerance.
NOT_APPLICABLE: a component="sampling" criterion on an error model that lists no sampling source.

The bounds are added by the triangle inequality and their failure probabilities by the union bound, with the assumptions stated under ErrorModel.assess. A component="sampling" criterion assesses the sampling contribution only and never covers total error. The assessment is a separate record, so assessing with another criterion changes neither the Result nor its Plan. The fields below are read-only.

Attributes:

model_id (ContentID) –

Content hash of the error model assessed against.
accuracy (Accuracy) –

The criterion as an Accuracy: tolerance, confidence and component.
absolute_fallback (Real | None) –

Absolute tolerance used only when the relative scale cannot be established, or None.
output_id (ContentID) –

Content hash of the output whose error is assessed.
context (AssessmentContext) –

Identities of the Problem, circuit description, Plan, observations and Result of the assessed data, with the parameter point.
frame (ErrorFrame) –

The ErrorFrame of the output.
method (Text) –

How the bounds were combined.
reference (TargetReference | None) –

The TargetReference of a relative criterion, or None.
status (ClaimStatus) –

"PASS", "INCONCLUSIVE" or "NOT_APPLICABLE", as above.
threshold (Rational | None) –

Absolute threshold in the output unit, or None when a relative scale was not established.
covered_subtotal (Rational) –

Sum of the bounds that entered the triangle inequality, an exact rational.
covered (tuple[Text, ...]) –

Sources whose bounds entered the sum.
remaining (tuple[Text, ...]) –

Required sources without an applicable additive bound.
unverified (tuple[Text, ...]) –

Covered sources whose bound, conditions or inputs lack witnessed proved or certified support.
prerequisites (tuple[Text, ...]) –

Reasons that prevent PASS.
failure_probability (Rational | None) –

Union-bound failure probability of the covered bounds and the reference, capped at one, or None when any probability is unknown.
facts (tuple[FramedFact, ...]) –

The FramedFact records used, with their assumptions and failure probabilities.

TargetReference ¶

Bases: Record

A reference value of the target that sets the scale of a relative criterion.

Pass it as reference= to Result.assess(relative_tolerance=...). For the criterion |error| <= r*|target|, a proved lower bound L <= |target| gives the sufficient threshold r*L, and an exact nonzero target gives r*|target|. An upper bound on the magnitude or an observed estimate gives none, and neither does a reference whose failure probability is unknown or whose evidence is not witnessed proved or certified support. The reference's failure probability joins the union bound of the assessment. Build it with keyword arguments. All three fields are required.

Attributes:

relation (Literal['exact_target', 'magnitude_lower_bound', 'magnitude_upper_bound']) –

Required. "exact_target", "magnitude_lower_bound" or "magnitude_upper_bound".
fact (FramedFact) –

Required. A FramedFact whose quantity is the frame's target quantity. It holds the reference's whole frame.
failure_probability (Real | None) –

Required. Probability in [0, 1) that the reference fails, or None when unknown.

Raises:

ValueError –

If the fact names another quantity or is not a real scalar, or a magnitude upper bound, or an exact target of a norm_squared quantity, is negative.

Certificate ¶

Bases: Record

An accuracy assessment of one Result together with its completed verification checks.

Build it with keyword arguments from an assessment, for example Certificate(plan_id=result.plan_id, result_id=result.content_id, assessment=result.assess(absolute_tolerance=1e-6), checks=()), then attach the facts that Result.verify returned with with_verification (see Keep an assessment and its checks together). All four fields are required. Checks and the assessment stay separate, so a check that passes its own threshold does not change an INCONCLUSIVE assessment.

Attributes:

plan_id (ContentID) –

Required. Content hash of the Result's Plan.
result_id (ContentID) –

Required. Content hash of the Result.
assessment (ClaimAssessment) –

Required. The ClaimAssessment of that Result.
checks (tuple[CheckAssessment, ...]) –

Required. Completed checks as CheckAssessment records, () to start.

Raises:

ValueError –

If the assessment belongs to another Plan or Result, or a check to another Result.

with_verification ¶

with_verification(result, *, options, evidence, max_integer_bits=DEFAULT_MAX_INTEGER_BITS)

Return a new Certificate with the facts of a completed verification attached as checks.

Nothing is verified or assessed again. Each fact from a verification must come from these same options, compared by their complete content hash, and answer the check it records. The hash covers every field and the revision history (parent_id), so keep the options object you passed to Result.verify, or its saved JSON. Changing any option, even only a threshold, needs a new Result.verify call with the new options, because the old facts were never produced for it. An attached check replaces an earlier check of the same CheckSpec.

Parameters:

result (Result) –

The certified Result, with its Plan attached.
options (object) –

The options record passed to Result.verify.
evidence (tuple[FramedFact, ...]) –

The facts that Result.verify returned.
max_integer_bits (int, default: DEFAULT_MAX_INTEGER_BITS ) –

Bit limit of the exact arithmetic. Default 4096.

Returns:

certificate ( Certificate ) –

A revision with the checks attached.

Raises:

ValueError –

If result is not the certified Result, a fact names no check of options or repeats one, or a fact was produced by other options or for another check.

CheckAssessment ¶

Bases: Record

Outcome of one scalar check: its status and the fact it was decided on.

Certificate.checks holds them, and assemble_check returns one. PASS or FAIL concerns only this check's threshold, and the evidence kind of the fact is unchanged. The fields below are read-only.

Attributes:

check_id (ContentID) –

Content hash of the CheckSpec.
artifact_id (ContentID) –

Content hash of the Result the check concerns.
status (CheckStatus) –

"PASS" or "FAIL" compares the value with the threshold. "NOT_RUN" means no fact was supplied. "INCONCLUSIVE" means the value, the threshold, the assessed point or support bound to this Result is missing, or an assumption is open. "NOT_APPLICABLE" means the fact states that the check does not apply.
fact (FramedFact | None) –

The supplied fact, with its raw value and evidence kind, or None.
reason (Text) –

Explanation of the status, including any roundoff-window adjustment.

Error values¶

FramedFact ¶

Bases: Record

A Fact tied to its ErrorFrame and parameter point.

Result.facts, ClaimAssessment.facts and the facts that Result.verify returns hold them. A value is used only in its own frame and at its own parameter point, and the open assumptions of its fact stay attached when an assessed value is reused. Build one with keyword arguments to supply a bound to Result.assess(facts=...). frame, bindings and fact are required.

Attributes:

frame (ErrorFrame) –

Required. The frame of the value.
bindings (tuple[Binding, ...]) –

Required. Parameter values the statement is restricted to. () declares no restriction.
fact (Fact) –

Required. The value. Its quantity names the role the value plays for the code that reads it, for example the sampling source of an expectation value.
failure_probability (Real | None) –

Default None, which means unknown. Probability in [0, 1) that this bound fails. A bound supplied in place of another does not inherit the other's probability, so a replacement without one has unknown confidence.

Raises:

ValueError –

If the fact's unit or scope differs from the frame's, or a parameter is restricted twice.

ErrorFrame ¶

Bases: Record

What an error value refers to: quantity, metric, unit, scope, conditions and domain.

Every error bound and check carries one, and the frame of a Result's output is result.plan.error_model.frame. A value answers a claim only when the two frames are compatible, which requires all six fields to agree in meaning, with units compared by symbol and dimension and scopes by kind and domain. A value for the projected problem or for a zero input therefore cannot answer a claim about the target quantity, and missing context is never read as an absence of conditions. Build one with keyword arguments to state a value you supply. Every field except domain is required.

Attributes:

quantity (Text) –

Required. Name of the quantity the error describes.
metric (Text) –

Required. Error metric, for example an absolute difference or variance.
unit (Unit) –

Required. Unit of the metric's value.
scope (Scope) –

Required. Scope of the Problem the quantity belongs to.
conditioning (Text) –

Required. Conditions under which the value is meaningful.
domain (Literal['target', 'full_operator', 'projected', 'zero_input']) –

Default "target", the requested quantity. "full_operator" is a property of the whole operator, "projected" one of the projected problem of a subspace method, and "zero_input" the error of a preparation applied to the all-zero input.

Fact ¶

Bases: Record

One value with its availability, unit, scope and evidence.

A concrete fact has a value and its Evidence. A symbolic fact has only a symbol that names an expression. An unknown or not-applicable fact has a reason and no value, so missing information never reads as zero. Build one with keyword arguments to supply a value. quantity, unit, scope and availability are required.

Attributes:

quantity (Text) –

Required. Name of the quantity.
unit (Unit) –

Required. Unit of the value.
scope (Scope) –

Required. Scope in which the value holds.
availability (Literal['concrete', 'symbolic', 'unknown', 'not_applicable']) –

Required. "concrete", "symbolic", "unknown" or "not_applicable".
value (Scalar | StrictBool | None) –

Default None. An exact Rational, a Float64, a Complex128 or, for a predicate, a boolean. Set exactly when concrete.
symbol (Symbol | None) –

Default None. Symbol naming an expression, set exactly when symbolic.
reason (Text | None) –

Default None. Why the value is unknown or not applicable, set exactly then.
evidence (Evidence | None) –

Default None. Required for a concrete value, absent when the value is unknown or not applicable.
assumptions (tuple[Text, ...]) –

Default (). Open assumptions the value depends on.

Raises:

ValueError –

If the fields set do not match availability as above.

Evidence ¶

Bases: Record

The basis of a value (proof, bound, estimate, assertion or observation) and the record that produced it.

Fact.evidence holds it. kind is a declaration, and validating the record never turns it into a verified result. A value is witnessed only when status is "witnessed" and the evidence names the record of the computation that produced the value (artifact), its scope and its subject. Without that, even a declared proved_relation stays an unverified declaration. A user assertion can be witnessed, meaning it was received, without becoming proof of the asserted value. Evidence from a verification also names the options record that produced the value, and the value answers only those options. When it answers a check, check_id names that exact CheckSpec, so a check revised afterwards, for example with another threshold, is not answered by it. A verification value that answers no check, such as an output-error component, has no check_id.

Build it with keyword arguments to state the basis of a value you supply, for example Evidence(kind="user_assertion", source=source). kind and source are required. The other fields describe a witnessed value and default to None or empty.

Attributes:

kind (EvidenceKind) –

Required. Declared basis of the value: "proved_relation" or "certified_bound" (the only kinds that can support an accuracy PASS), "numerical_estimate", "empirical_prediction", "user_assertion", "external_specification" or "observed".
source (Source) –

Required. Versioned Source that declares the basis.
work (tuple[WorkProvenance, ...]) –

Default (). WorkProvenance records of the work done to obtain the value.
status (Literal['declared', 'witnessed']) –

Default "declared", a declaration alone. "witnessed" means the evidence names the record of the computation that produced the value.
artifact (Text | None) –

Default None. Identifier of that record, set exactly when witnessed.
artifact_kind (Literal['verification_receipt'] | None) –

Default None. "verification_receipt" when that record is a verification record.
witnessed_scope (Scope | None) –

Default None. Scope that the record covers, set exactly when witnessed.
subject_id (ContentID | None) –

Default None. Content hash of the witnessed subject, such as a Result or an operator input, set exactly when witnessed.
options_id (ContentID | None) –

Default None. Content hash of the verification options that produced the value, set exactly for a verification record.
check_id (ContentID | None) –

Default None. Content hash of the CheckSpec the value answers.

Raises:

ValueError –

If the witnessed fields are not all set exactly when status is "witnessed", or options_id or check_id is set without a verification record.

WorkProvenance ¶

Bases: Record

Work done to obtain a value: when it ran, what it computed and where its output is.

Evidence.work holds these records. The fields below are read-only.

Attributes:

stage (Stage) –

Workflow stage in which the work ran.
description (Text) –

What was computed and its size, for example entries scanned and scalar operations.
artifact (Text) –

Identifier of the record that holds the output of the work.

Error models and checks¶

A Method states its error sources in an ErrorModel and its checks as CheckSpec records. These entries serve readers who build or inspect them directly.

ErrorModel ¶

Bases: Record

The error sources a Method lists for its output, each already propagated into the output's frame.

result.plan.error_model holds it, and Result.assess calls assess with result.facts. The Method lists every error source its output needs, including any subspace or ground-state identification. The library does not check that list for completeness. The fields below are read-only.

Attributes:

output_id (ContentID) –

Content hash of the output the model describes.
subject_id (ContentID) –

Content hash of the Problem.
construction_id (ContentID) –

Content hash of the planned circuit description.
frame (ErrorFrame) –

The ErrorFrame of the output, shared by every additive term.
required_sources (tuple[Text, ...]) –

Names of the sources a total-error claim needs.
terms (tuple[ErrorTerm, ...]) –

The ErrorTerm records.
source (Source) –

Where the model comes from.

Raises:

ValueError –

If source names repeat, no source is required, or an additive term has another frame.

assess ¶

assess(accuracy, *, context, facts=(), reference=None, absolute_fallback=None, max_integer_bits=DEFAULT_MAX_INTEGER_BITS)

Assess an accuracy criterion against the model's bounds at an existing parameter point, measuring nothing.

Most callers use Result.assess, which supplies the context and the error bounds in result.facts. Two rules combine the bounds, each with its assumption:

Triangle inequality. Its assumption, which the code does not check, is that the Method has propagated every source into this output's frame, so the output error is the sum e = sum_k e_k of the propagated source errors. The code checks only that the frames agree. Where each bound |e_k| <= b_k holds, |e| <= sum_k b_k. The sum covers the error only when every required source has a bound, so a missing source keeps the result INCONCLUSIVE.
Union bound. If bound k fails with probability at most delta_k, all bounds, and a relative reference, hold together with probability at least 1 - sum_k delta_k, whatever their dependence, so no independence is assumed. Confidence c needs sum_k delta_k <= 1 - c, and an unknown delta_k makes the total unknown.

PASS also requires the sum to be at most the threshold and every covered bound to apply at the assessed point, carry no open assumption and have witnessed proved_relation or certified_bound evidence for a subject of the context. Numerical estimates, observations and assertions never qualify, however small their value. component="sampling" assesses that contribution only, so missing hardware, preparation or model terms cannot give it total-error coverage. A model that lists no sampling source, as QLS and QHD do with exact readout, has no sampling contribution to bound, so that criterion is NOT_APPLICABLE rather than missing.

Parameters:

accuracy (Accuracy) –

The criterion.
context (AssessmentContext) –

Identities and parameter point of the assessed data. Result.assess builds it from the Result.
facts (tuple[FramedFact, ...], default: () ) –

Bounds that replace the model's terms of the same name.
reference (TargetReference | None, default: None ) –

Scale of a relative criterion.
absolute_fallback (float | None, default: None ) –

Positive absolute tolerance used only when the relative scale cannot be established. Requires a relative criterion.
max_integer_bits (int, default: DEFAULT_MAX_INTEGER_BITS ) –

Bit limit of the exact arithmetic. Default 4096.

Returns:

assessment ( ClaimAssessment ) –

The status with its threshold, covered sum, covered, remaining and unverified sources, reasons and capped failure probability.

Raises:

TypeError –

If accuracy, context or reference has another type.
ValueError –

If the context belongs to another Problem or circuit description, a supplied fact names no source or repeats one, a bound does not apply in its frame or is a negative additive bound, or absolute_fallback is not positive or lacks a relative criterion.

ErrorTerm ¶

Bases: Record

One error source of an ErrorModel, already propagated into the output's frame.

Methods build these. role is independent of the value's availability and evidence, and coverage cannot remove another required source of the model. The fields below are read-only.

Attributes:

name (Text) –

Name of the source, equal to fact.fact.quantity.
stage (Stage) –

Workflow stage where the error arises.
source (Source) –

Where the bound comes from.
formula (Text) –

Text form of the bound.
fact (FramedFact) –

The bound as a FramedFact.
coverage (Text) –

Text saying what the bound covers.
role (Literal['additive_bound', 'amplification', 'covariance_contribution', 'conditional_term', 'listed_only']) –

Default "additive_bound", a nonnegative bound added in the triangle inequality. The other roles, "amplification", "covariance_contribution", "conditional_term" and "listed_only", are listed but not added.
conditions (tuple[FramedFact, ...]) –

Boolean predicates that must hold, in the dimensionless predicate frame of this term.
inputs (tuple[FramedFact, ...]) –

Values the bound depends on.
failure_probability (Real | None) –

Probability in [0, 1) that this bound fails, not a variance. None when unknown.

Raises:

ValueError –

If name differs from the fact's quantity, the value is not a real scalar, or an additive bound is negative.

CheckSpec ¶

Bases: Record

One scalar check: the quantity, its threshold and domain, and what running it costs.

A verification options record produces one per selected criterion, and Result.verify returns one fact per check. Each verification fact records the content hash of its check, so any revision of the check, including only a new threshold, needs a new verification. The fields below are read-only.

Attributes:

name (Text) –

Check name, which the answering fact's quantity repeats.
claim_id (ContentID) –

Content hash of the output the check concerns.
frame (ErrorFrame) –

The ErrorFrame of the checked value.
domain (CheckDomain) –

The CheckDomain of valid values. The threshold compares a valid value and does not define the domain, and the domain does not depend on how the metric is named.
source (Source) –

Implementation that computes the value.
options_id (ContentID | None) –

Content hash of the options record that selected the check, or None for a check of a supplied value.
threshold (Nonnegative | None) –

Nonnegative threshold. PASS means value <= threshold. None keeps the check INCONCLUSIVE.
prerequisites (tuple[Text, ...]) –

Open assumptions, which keep the check INCONCLUSIVE.
access (tuple[Text, ...]) –

Data the check reads.
experiments (Count) –

Number of new experiments the check runs.
classical_work (Text) –

Text form of its classical computation.
reference_work (Text) –

Text form of its reference computation.
data_description (Text) –

What the check stores.

CheckDomain ¶

Bases: Record

Mathematical range of a check value, in the check's unit.

CheckSpec.domain holds it. A value outside the range is rejected before any status is decided. The fields below are read-only.

Attributes:

lower (Real | None) –

Inclusive lower end, or None for no lower end.
upper (Real | None) –

Inclusive upper end, or None for no upper end.
integer (StrictBool) –

Whether the value must be a whole number, for example a zero-one flag.
roundoff_tolerance (Nonnegative) –

Absolute window at each end, in the check's unit. A value outside the range by at most this amount is compared at the end, and its raw value stays in the fact. Zero means exact comparison. The code that sets a nonzero window must justify its scale, because a number alone does not bound rounding error. The built-in checks of nonnegative errors use zero.

Raises:

ValueError –

If lower exceeds upper, or a nonzero window is set on an integer domain or a domain without ends.

assemble_check ¶

assemble_check(check: CheckSpec, *, artifact_id: str, fact: FramedFact | None = None, max_integer_bits=DEFAULT_MAX_INTEGER_BITS) -> CheckAssessment

Decide one check from a supplied fact, outside a Certificate.

The status is decided as in Certificate.with_verification, without a Result context. A fact restricted to a parameter point therefore stays INCONCLUSIVE here. A fact from a verification answers only the unmodified check that it records, so a check revised afterwards, for example with another threshold, is rejected. Run Result.verify again with new options instead. A value outside the check's domain raises before any status is decided.

Parameters:

check (CheckSpec) –

The check.
artifact_id (str) –

Content hash of the Result the check concerns.
fact (FramedFact | None, default: None ) –

The value, or None, which gives NOT_RUN.
max_integer_bits (int, default: DEFAULT_MAX_INTEGER_BITS ) –

Bit limit of the exact arithmetic. Default 4096.

Returns:

outcome ( CheckAssessment ) –

The status and reason.

Raises:

ValueError –

If the fact names another quantity or frame, was produced by other options or for another check, or lies outside the check's domain.

Variance and sample size¶

linear_variance ¶

linear_variance(*, joint_id: str, frame: ErrorFrame, contributions: tuple[EstimatorContribution, ...], covariance: tuple[CrossCovariance, ...] = (), independence: IndependenceLaw | None = None, max_integer_bits=DEFAULT_MAX_INTEGER_BITS) -> VarianceAssessment

Compute Var(sum_i a_i X_i) exactly from supplied variances and covariances.

Var(sum a_i X_i) = sum a_i^2 Var(X_i) + 2 sum_{i<j} a_i a_j Cov(X_i, X_j), after terms with one data_id are merged into one variable by adding their coefficients. The merge accounts for the correlation between two estimators that share calibration data, whose derivatives with respect to the shared data add before squaring. So Var(2X) = 4 Var(X), and X - X = 0 needs no variance at all. Every pair of variables with nonzero merged coefficients needs a supplied covariance or a declared IndependenceLaw, and a missing one leaves the result unknown. Independence is never assumed. A supplied covariance c must satisfy the Cauchy-Schwarz inequality c**2 <= Var(X) Var(Y). That pairwise test does not show that the whole covariance matrix is positive semidefinite, and no impossible value is repaired. The record space is O(number of terms + supplied pairs), and no dense matrix is formed.

The evidence of the result is proved_relation only when every input used is witnessed proof. An asserted or externally specified input makes it user_assertion, and any other mix numerical_estimate.

Parameters:

joint_id (str) –

Content hash of the joint data the variables belong to.
frame (ErrorFrame) –

Frame with metric "variance" and the squared output unit.
contributions (tuple[EstimatorContribution, ...]) –

One term per (variable, coefficient).
covariance (tuple[CrossCovariance, ...], default: () ) –

Covariances of distinct variables. Default ().
independence (IndependenceLaw | None, default: None ) –

Declared independence in place of covariances. Default None.
max_integer_bits (int, default: DEFAULT_MAX_INTEGER_BITS ) –

Bit limit of the exact arithmetic. Default 4096.

Returns:

assessment ( VarianceAssessment ) –

The variance, concrete with its evidence kind, or unknown when a needed variance or covariance is missing.

Raises:

ValueError –

If the frame's metric is not "variance", both covariances and an IndependenceLaw are given, a variance is negative, a covariance pair repeats or names an unknown variable, a covariance violates Cauchy-Schwarz, or the complete sum is negative.
TypeError –

If independence is not an IndependenceLaw.

EstimatorContribution ¶

Bases: Record

One term a_i X_i of a linear estimator, for linear_variance.

Build it with keyword arguments. All three fields are required. Terms with the same data_id are the same random variable, never independent samples.

Attributes:

data_id (ContentID) –

Required. Content hash of the data that defines X_i.
coefficient (Real) –

Required. The real coefficient a_i.
variance (FramedFact) –

Required. Var(X_i) as a FramedFact, in the squared unit of X_i.

CrossCovariance ¶

Bases: Record

The covariance of two distinct random variables, for linear_variance.

A pair without a supplied covariance is unknown, never zero. Build it with keyword arguments. All three fields are required.

Attributes:

left (ContentID) –

Required. Content hash of the data of one variable.
right (ContentID) –

Required. Content hash of the other variable, distinct from left.
fact (FramedFact) –

Required. The covariance as a FramedFact.

Raises:

ValueError –

If left equals right. A variance belongs to its EstimatorContribution.

IndependenceLaw ¶

Bases: Record

A declared independence of the variables of one joint data set, in place of covariances.

Pass it as independence= to linear_variance. It keeps its own frame, parameter restrictions, predicates and evidence. Build it with keyword arguments. joint_id, frame, bindings and evidence are required.

Attributes:

joint_id (ContentID) –

Required. Content hash of the joint data.
frame (ErrorFrame) –

Required. The variance frame the independence applies in.
bindings (tuple[Binding, ...]) –

Required. Parameter values the independence is restricted to.
evidence (Evidence) –

Required. The basis of the independence claim.
conditions (tuple[FramedFact, ...]) –

Default (). Boolean predicates that must hold, in the predicate frame of frame.

Raises:

ValueError –

If a parameter is restricted twice, or a condition is not a predicate in that frame.

VarianceAssessment ¶

Bases: Record

What linear_variance returns: the variance and the inputs it was computed from.

The answer is value, a variance in squared units with its frame. It is not a standard deviation or a confidence bound, and it does not check that a covariance matrix is positive semidefinite. The fields below are read-only.

Attributes:

joint_id (ContentID) –

Content hash of the joint data.
value (FramedFact) –

The variance as a FramedFact, unknown when a needed variance or covariance is missing.
contributions (tuple[EstimatorContribution, ...]) –

The supplied terms.
covariance (tuple[CrossCovariance, ...]) –

The supplied covariances.
independence (IndependenceLaw | None) –

The supplied IndependenceLaw, or None.

resolve_scalar_bound ¶

resolve_scalar_bound(coefficient: int | float | Fraction | Rational | Float64 | FramedFact | None, tolerance: int | float | Fraction | Rational | Float64 | FramedFact | None, *, maximum: int, minimum: int = 1, fixed_error: int | float | Fraction | Rational | Float64 | FramedFact | None = 0, decay: Literal['inverse', 'inverse_sqrt'] = 'inverse', fixed: int | None = None, conditions: Iterable[FramedFact | bool | None] = (), assumptions: Iterable[str] = (), work_per_unit: int | float | Fraction | Rational | Float64 | None = None, max_integer_bits: int = DEFAULT_MAX_INTEGER_BITS) -> ScalarBoundResult

Find the smallest integer n with e_0 + c/n <= epsilon (or c/sqrt(n)) in a finite range.

The supplied model is e(n) = e_0 + c/n or e(n) = e_0 + c/sqrt(n). For epsilon > e_0 and c > 0, e(n) <= epsilon holds exactly when n >= c/(epsilon - e_0) for c/n and when n >= (c/(epsilon - e_0))**2 for c/sqrt(n), so the smallest permitted integer is an exact rational ceiling, with no search over n. For example, with e_0 = 1/8, epsilon = 3/8 and c = 1, the answer is 4 for c/n and 16 for c/sqrt(n).

All error quantities must share an absolute metric, unit and scope. FramedFact inputs are checked for that, and plain numbers assume it. Unknown quantities do not become zero. A false condition prevents a choice, and an unspecified condition makes the result conditional. The supplied bounds need not cover every error of a method, so the result is not a total-accuracy claim. It also sets no Method parameter. Use the answer in a new Method configuration yourself when the model describes that parameter.

Parameters:

coefficient (number | FramedFact) –

c, nonnegative.
tolerance (number | FramedFact) –

epsilon, the allowed error, nonnegative.
maximum (int) –

Largest permitted n, positive.
minimum (int, default: 1 ) –

Smallest permitted n, positive. Default 1.
fixed_error (number | FramedFact, default: 0 ) –

e_0, the part of the error that does not depend on n, nonnegative. Default 0.
decay (str, default: 'inverse' ) –

"inverse" for c/n, the default, or "inverse_sqrt" for c/sqrt(n).
fixed (int | None, default: None ) –

An n to check instead of choosing the smallest one.
conditions (Iterable, default: () ) –

Conditions of the model, as framed boolean predicates, booleans, or None for an unspecified condition.
assumptions (Iterable[str], default: () ) –

Further assumptions stated as text.
work_per_unit (number | None, default: None ) –

Declared work per unit of n, multiplied by the chosen n.
max_integer_bits (int, default: DEFAULT_MAX_INTEGER_BITS ) –

Bit limit of the exact arithmetic. Default 4096.

Returns:

bound ( ScalarBoundResult ) –

The chosen n, its status, a rational upper bound on e(n) and the conditions and assumptions it depends on.

Raises:

ValueError –

If minimum, maximum or fixed is not a positive integer in order, decay is another value, a quantity is negative, the framed quantities disagree in frame or parameter point, or a condition is not a boolean predicate.

ScalarBoundResult ¶

ScalarBoundResult(integer: int | None, status: str, reason: str, covered_bound: Fraction | None, conditions: tuple, assumptions: tuple[str, ...], declared_work: Fraction | None = None)

What resolve_scalar_bound returns: a sufficient integer for the supplied error model, with its conditions and assumptions.

The answer is integer. covered_bound is a rational upper bound on the modeled error, not its exact value and not a total-accuracy certificate. The fields below are read-only.

Attributes:

integer (int | None) –

The smallest sufficient positive integer n in the supplied domain, the checked fixed value, or None when none is established.
status (str) –

Outcome of the bound and its conditions, not of an execution: "resolved", "conditional" (it rests on assumptions or unspecified conditions), "unresolved" (a quantity or condition is unknown), "inapplicable" (a condition is false or does not apply) or "infeasible" (no permitted n meets the tolerance).
reason (str) –

Explanation of the choice, or why no sufficient choice was established.
covered_bound (Fraction | None) –

Rational upper bound on e(n) in the supplied error metric, or None without a choice.
conditions (tuple) –

The supplied conditions the bound depends on.
assumptions (tuple[str, ...]) –

Every stated assumption, including unverified ones.
declared_work (Fraction | None) –

The supplied linear work model at the chosen n, or None without a model or a choice.

to_dict ¶

to_dict()

Return the fields as a JSON-ready dictionary, with rationals as numerator and denominator.