ISAES quantum evidence methods

This document describes the released, bounded methods in pf_reporting/domain.py. These methods analyze saved results in the reporting worker. They do not submit hardware jobs, retrieve current calibration, generate missing scientific observations, or require an AI provider. Library installation and scientific qualification are separate properties.

Common record and evidence origin

A dataset declaration identifies an immutable result location. Its source is a JSON pointer or an existing artifact: reference supported by the reporting engine. Here is an example result fragment for a saved Bell state:

{
  "data": {
    "bell": {"real": [0.7071067811865475, 0, 0, 0.7071067811865475], "imag": [0, 0, 0, 0]},
    "reporting": {
      "datasets": [{
        "name": "bell",
        "kind": "quantum_state",
        "source": "/data/bell",
        "origin": "numerical_state",
        "basis": "computational",
        "qubit_order": "little_endian",
        "observables": ["XX", "ZZ"],
        "reduced_subsystems": [[0, 1]],
        "entanglement_partition": [0]
      }],
      "require": ["quantum_state:bell"]
    }
  }
}

Use one of these exact origin values: numerical_state, sampled_simulation, hardware_observation, reconstructed_estimate, mitigated_estimate, model_prediction, or unverified_import. Missing origin becomes unverified_import and the finding is insufficient. This preserves usable numerical evidence without presenting its provenance as verified.

For hardware observations, include backend, acquired_at and circuit_or_protocol_id in the dataset or its provenance object. acquired_at must be an ISO timestamp with a timezone, for example 2026-09-27T14:00:00Z. The identifier may also be supplied as circuit_id, protocol_id or protocol. Calibration payloads may supply these acquisition fields directly. Mitigated results whose acquisition_origin is hardware also require them. These fields are supplied declarations; their presence does not authenticate a provider or validate a hardware claim.

{"provenance": {
  "backend": "retained-device-name",
  "acquired_at": "2026-09-27T14:00:00Z",
  "circuit_or_protocol_id": "retained-circuit-content-hash"
}}

All findings retain source references, origin, the method/version, assumptions, limitations, missing information and physicality checks. Incomplete inputs produce an insufficient finding or an unavailable-method decision, so a required analysis cannot silently pass. Figures use the same retained values and origin. Source bytes and values are never renormalized, projected to a physical state, or overwritten by these methods.

Ordering conventions

State, count, checkpoint and shadow methods require basis="computational" and an explicit qubit_order. For little_endian, qubit zero is the least significant bit of a state index or bitstring; for big_endian, qubit zero is the left tensor factor. Every Pauli string and measurement-basis string is in qubit-index order: character zero describes qubit zero. Thus the interpretation of an input bitstring is ordered separately from the character positions of an observable string.

A returned reduced-state matrix orders its listed qubits from the most significant tensor factor to the least significant. A reduced state for [2, 0] therefore uses qubit 2 as its left factor regardless of the original full-state storage order.

1. Complete quantum states

Kind: quantum_state (alias statevector). Payload: {"real": [...], "imag": [...]} for a statevector, or nested square arrays for a density matrix. imag may be omitted when it is zero. A payload wrapper {"state": {"real": ..., "imag": ...}} is also accepted.

Supported states have one to eight qubits. Dataset options are tolerance (default 1e-8, permitted range 0..0.001), subsystem_dimensions (all entries must equal two), up to 128 unique Pauli observables, up to 16 reduced_subsystems, and an entanglement_partition (default [0] when more than one qubit exists).

The method checks trace, Hermiticity and positive semidefiniteness. Failed checks retain the input matrix visualization and diagnostic values, but withhold entropy, local states and entanglement interpretation. Passing states yield purity, entropy, reduced density matrices, local Bloch vectors, requested Pauli expectations and partial-transpose negativity for the declared cut. Pure states additionally yield the entropy of the reduced subsystem. Small negative eigenvalues within the declared tolerance are omitted only for entropy arithmetic; the retained state is unchanged.

A nonzero negative partial-transpose eigenvalue beyond tolerance detects entanglement for that cut. Failure to detect it is not a general separability proof. Local Bloch vectors and pair correlations are not a general entanglement map: Bell and separable 00/11 mixtures have the same local Bloch vectors, while a GHZ state has global entanglement absent from its two-qubit reduced-state negativity.

2. Counts and compatible Pauli estimates

Kind: quantum_counts. Example payload:

{"counts": {"00": 50, "11": 50}, "shots": 100,
 "measurement": {"basis": "ZZ", "sampling": "iid"}}

Counts use equal-width binary strings of one to sixteen bits and nonnegative integers. Up to 65,536 retained outcome keys and a total of 10^12 shots are accepted; the declared shots, when supplied, must match the sum. Dataset observables can request up to 128 compatible Pauli strings. Each nonidentity factor must match the measurement axis. An incompatible request remains explicitly unavailable while compatible observations are retained.

With a declared measurement basis and sampling="iid", the method computes observed probabilities, Wilson marginal intervals, and matching Pauli parity means/intervals. The dataset confidence defaults to 0.95 and must lie strictly between 0.5 and 0.999999. These are marginal intervals, not simultaneous coverage of every outcome. Plots retain asymmetric interval geometry. If measurement or independence information is absent, raw counts and frequencies remain available but intervals are withheld. Counts do not produce a statevector, unknown phase, reconstructed state or general entanglement conclusion.

3. Supplied observable estimates

Kind: quantum_observable. Example payload:

{"observables": [{"observable": "Z0", "estimate": 0.2, "standard_error": 0.1,
                  "units": "dimensionless"}],
 "estimator": "sample_mean_v1", "measurement": {"basis": "Z"}}

Up to 256 estimates are accepted. The method retains supplied values and computes normal-approximation intervals from nonnegative supplied standard errors and dataset confidence. This assumes valid standard errors and an appropriate normal approximation. Missing standard errors, estimator identity or measurement protocol make the result insufficient; uncertainty is never manufactured. Provider-specific covariance and non-normal intervals require a separately qualified method.

4. Retained evolution checkpoints

Kind: quantum_checkpoints. Example payload:

{"coordinate": "cycle", "checkpoints": [
  {"at": 0, "state": {"real": [1, 0], "imag": [0, 0]}},
  {"at": 8, "state": {"real": [0, 1], "imag": [0, 0]}}
 ],
 "dynamics": {"hamiltonian": "retained-H-definition", "initial_state": "0",
              "integrator": "declared-method", "step_size": 0.1,
              "term_order": ["X", "Z"], "reference": "retained-reference-id"}}

There may be one to 64 saved checkpoints with strictly increasing coordinates and matching qubit dimensions. Coordinates are cycle, model_time, circuit_duration, or wall_clock; all time coordinates require units. Dataset observables are evaluated only for valid retained states. The explorer displays actual saved state matrices, and line views use the same saved times/expectations. It does not create calculated states between checkpoints. Missing dynamics provenance is insufficient. A declared provenance object is not itself a convergence test; use the separate convergence method and a matched reference/refinement study to assess approximation error.

5. Error-mitigation evidence

Kind: quantum_mitigation; dataset origin must be mitigated_estimate. Both methods require raw_estimate, observable, noise_model_id, and acquisition_origin (sampled_simulation, hardware_observation or numerical_state). Underlying hardware observations retain their acquisition requirements. Optional reference_estimate requires a reference_id; comparisons preserve whether mitigation made reference error worse.

Polynomial ZNE example:

{"method": "zne", "raw_estimate": 0.8, "noise_factors": [1, 2, 3],
 "estimates": [0.8, 0.6, 0.4], "standard_errors": [0.01, 0.01, 0.01],
 "degree": 1, "observable": "Z", "noise_model_id": "retained-noise-scaling-protocol",
 "acquisition_origin": "sampled_simulation"}

ZNE supports polynomial degrees one to three, at least degree+2 observations and at most 64 unique factors greater than or equal to one. A factor-one estimate must match the raw result. Fits extrapolate the explicitly declared polynomial to noise factor zero. With strictly positive independent supplied standard errors, weighted least squares propagates them into the intercept uncertainty; without them the fit remains available but uncertainty and completeness are withheld. Ill-conditioned fits are rejected. Fits, residuals and measured data remain distinguishable. Sampling intervals do not include extrapolation-model bias.

Signed-sample PEC example:

{"method": "pec", "raw_estimate": 0.3, "signed_samples": [-2, 2, 2, 2],
 "quasi_probability_norm": 2, "sampling": "iid", "observable": "Z",
 "noise_model_id": "retained-characterization-model", "acquisition_origin": "sampled_simulation"}

PEC analyzes two to 100,000 supplied noise-model-weighted signed samples with quasi-probability norm at least one. It computes their mean and sample standard error with a normal interval. The caller must supply the estimator-weighted samples and the IID sampling declaration. This method does not infer or fit a noise inverse from a final number. Neither method creates a corrected quantum state or guarantees an ideal estimate. Values are not clipped to a physical-looking range; model bias and unsuccessful mitigation remain visible.

6. Variational history

Kind: variational_history. Example payload:

{"objective": [-0.5, -0.8, -0.9], "evaluations": [1, 2, 3], "direction": "minimize",
 "optimizer": "declared-optimizer", "ansatz": "retained-circuit-id", "initialization": 12,
 "stopping_rule": "evaluation_budget", "budget": {"evaluations": 3},
 "shots": [100, 100, 100], "run_id": "retained-run-id", "units": "hartree"}

Up to 10,000 finite objectives with strictly increasing evaluation coordinates are supported. Omitted coordinates use the explicit ordinal sequence 1..N. Direction must be minimize or maximize. Optional shots are nonnegative integer costs per evaluation. The method records best/final objective, tail variation over at most five evaluations, and retained cost metadata. The default stagnation_tolerance is 1e-8. Missing optimizer, ansatz, initialization, stopping rule or budget is insufficient.

A flat trace is reported as observed stagnation, never as a diagnosed barren plateau. That diagnosis needs a suitable gradient ensemble and scaling study. Single-run optimizer improvement does not establish general optimizer superiority.

7. Device characterization and calibration

Kind: quantum_calibration. Example payload:

{"backend": "retained-device", "acquired_at": "2026-09-27T14:00:00Z",
 "calibration_id": "retained-calibration-id", "protocol": "T1-delay-v1",
 "metrics": [{"name": "T1", "qubits": [0], "units": "us", "value": 100}]}

Up to 2,048 metrics and 64 distinct metric/unit groups are accepted. Every metric needs a name, nonempty valid physical qubit indices, units and a finite value. Missing backend, acquisition time, calibration ID or protocol produces insufficient evidence. Charts group matching metrics/units, preserving the supplied acquisition snapshot. No current calibration is fetched. A gate-error metric is not an observed error in the reported run, and calibration alone does not establish crosstalk or a physical root cause.

8. Chemistry energy bookkeeping

Kind: quantum_chemistry. Example payload:

{"electronic_energy": -2.0, "nuclear_repulsion_energy": 0.7,
 "energy_offsets": {"active_space": 0.1}, "reported_total_energy": -1.2,
 "geometry": [["H", [0, 0, 0]], ["H", [0, 0, 0.74]]], "geometry_units": "angstrom",
 "charge": 0, "spin": 0, "basis_set": "sto-3g", "active_space": [2, 2],
 "mapping": "JordanWigner", "energy_units": "hartree"}

The total is the sum of explicit electronic energy, nuclear repulsion and up to 32 named offsets, all declared in one energy convention. Optional reported_total_energy is checked against this sum using dataset tolerance (default 1e-8). All molecular/context fields in the example are required except the reported total and offsets. Missing context or inconsistent totals is insufficient. Avoid double-counting contributions already present in the chosen driver's electronic-energy definition.

This is energy bookkeeping for supplied finite-model results. It does not run an electronic-structure driver, validate the chemistry approximation or infer spatial orbitals. Energy values alone cannot produce an orbital diagram. Spatial orbital and phase-space methods are not part of this released nine-method catalog.

9. Local-Pauli classical shadows

Kind: classical_shadows. Example payload and dataset options:

{"bases": ["X", "X", "Y", "Y", "Z", "Z"],
 "bits": ["0", "1", "0", "1", "0", "0"],
 "randomization": "independent_uniform_local_pauli"}

Use dataset observables, for example ["X", "Y", "Z"], and explicit basis/order. Every measurement basis uses qubit-index character order, while every bitstring follows qubit_order. For each Pauli string the estimator is zero when an active axis does not match, otherwise the product of outcomes multiplied by 3^weight. It averages these per-shot values, retains empirical standard errors, and uses conservative Hoeffding intervals with Bonferroni simultaneous coverage at dataset confidence. Identity estimates are exactly one. Intervals are not clipped.

The protocol requires independent, uniformly chosen local axes and independently prepared identical states. Inputs must contain two to 100,000 paired basis/bit rows, one to sixteen qubits and one to 128 unique requested observables. The combined work budget is shots × requested_observables × qubits <= 2,000,000; select a smaller scientifically justified retained batch or fewer observables when necessary. High-weight estimates may have wide intervals. Supplied metadata does not independently prove that an acquisition randomized correctly, and this estimator does not reconstruct a full state or bypass measurement disturbance.

SDK and supplied-record adapters

All adapters return {"schema_version": 1, "dataset": {...}, "value": ...}; the executed-result adapter returns a list. The workflow must store value at the declared source and append dataset to its reporting declarations. Adapters do not write artifacts, attach literature, bypass storage ownership or execute acquisition.

The Qiskit counts adapter requires metadata["measurement"]["qubit_mapping"] to equal the identity list of measured classical bit positions. Remap a nonidentity layout explicitly before adaptation; a counts result alone does not reveal that mapping. Qiskit register-separating spaces are removed while preserving binary bit width. Noninteger counts are rejected. A saved final state remains a single saved state, never a fabricated time sequence.

from qiskit.quantum_info import Statevector
from pf_reporting.domain import adapt_qiskit_state

# circuit is an existing, explicitly defined simulation circuit.
record = adapt_qiskit_state(
    Statevector.from_instruction(circuit),
    name='final_state', source='/data/final_state',
    metadata={'origin': 'numerical_state', 'observables': ['XX', 'ZZ']})
result['data']['final_state'] = record['value']
result['data'].setdefault('reporting', {}).setdefault('datasets', []).append(record['dataset'])

capabilities() reports whether optional Qiskit, Aer, QuTiP, Qiskit Experiments, Mitiq, Qiskit Nature and PySCF modules can be found. This is an installation check, not qualification or full API integration. Missing specialist packages do not disable the NumPy-based methods. Remote acquisition, tomography fitting, spatial orbital calculation and oscillator phase-space analysis require separately qualified integrations; they are not implied by this catalog.

Scientific verification scope

tests/test_isaes_domain.py contains independent Bell/separable/mixed/GHZ fixtures, explicit ordering/phase checks, rejected invalid-state and malformed-data cases, seeded binomial interval coverage, noncommuting-Hamiltonian refinement against a matrix exponential, retained checkpoint fidelity, known and mismatched ZNE models, signed PEC samples, conservative classical-shadow estimates, metadata incompleteness, and SDK object adaptation. SDK tests use installed Qiskit/Aer and QuTiP when available. Exact fresh test counts and environment versions belong to the release validation evidence, not a permanent claim in this method guide. Numerical fixtures do not constitute hardware validation.

Protocol completion and linked retained checkpoints

The separately qualified bounded protocols are documented in ISAES_QUANTUM_PROTOCOLS.md: complete local-Pauli linear-inversion tomography from supplied counts (one–three qubits), and Husimi Q evaluation for an explicitly declared oscillator Fock or spin representation. A generic multi-qubit array is not automatically reinterpreted as an oscillator. No protocol fetches hardware data or repairs an unphysical estimate silently.

Checkpoint findings now retain unique observation identities for every saved coordinate. Their state-frame frame_observation_ids and observable-chart observation_ids share one link_group; selecting one saved cycle can therefore navigate only to the state actually retained for that cycle. Nonuniform saved coordinates remain nonuniform and no intermediate state is invented.

documentation/workflow_examples/qiskit_floquet_isaes.json keeps its original scientific Python program unchanged while its reporting extension links all retained observable series by actual cycle. The explicitly versioned qiskit_floquet_isaes_v2.json additionally calculates and retains the reduced state of q0 after preparation and each full cycle, using Qiskit's partial trace on the actual evolving density matrix. Its observable table, six series, reduced-state heatmap frames and local-Z line share floquet-cycle:N IDs and floquet-cycles group. The reduced-state view is not a full intermediate-state claim. The complete final density matrix and ideal statevector remain retained as before. A six-qubit/eight-cycle fixture compares the original and v2 metrics, series and final state exactly and checks the initial/one-cycle local-Z reference.