[QRE] Automatic error analysis for empty resource estimates

[Dima Fedoriaka (fedimser)]

Summary

Improve diagnostics when QRE returns an empty EstimationTable, so users can understand why no estimates were retained and which parameters or transforms require attention.

Changes

• Add structured diagnostics to EstimationCollection:
  • total candidates rejected for exceeding max_error
  • minimum final error among otherwise successful candidates
  • instruction IDs required by traces but unavailable in every ISA
• Run a conditional diagnostic pass without the finite error cutoff when all candidates exceed max_error.
  • Reports an exact completed estimate error rather than the partial error at the first cutoff crossing.
  • Supports both direct ISA enumeration and graph estimation.
  • Runs only when the original estimation produced no successful results.
• Detect missing instructions across both estimation paths.
  • Direct estimation compares required trace instructions with the union of available ISA instructions.
  • Graph estimation records required instructions with no provenance graph nodes.
• Expose structured diagnostics through the Python bindings and _qre.pyi.
  • Missing instruction IDs are returned in stable sorted order.
• Replace error-string parsing with a concise structured warning containing:
  • trace, ISA, candidate-job, and successful-estimate counts
  • error-budget rejection details and the exact minimum error threshold
  • missing instruction names and numeric IDs
  • deduplicated detailed estimator errors
• Report results removed by application post-processing separately from initial estimation failures.
• Preserve initial estimation statistics when post-processing removes all results.
• Add zero_estimates.ipynb, demonstrating:
  • an error budget that excludes every otherwise valid estimate
  • incompatible trace and ISA transforms caused by a missing LATTICE_SURGERY instruction
• Add ERROR_ANALYSIS_SPEC.md describing the intended behavior and constraints.

Example Diagnostics

For an error budget that excludes all estimates:

32 candidate estimate(s) exceeded the application's error budget.
The minimum error among candidates that otherwise estimated successfully was
0.000746000035. If max_error were greater than this value, at least one
estimate would succeed.

For incompatible transforms:

No enumerated ISA provides all instructions required by the traces.
Instructions absent from every ISA: LATTICE_SURGERY (4352).

[Copilot]

Pull request overview

This PR enhances the QRE “zero results” experience by adding structured diagnostics to EstimationCollection (error-budget rejection counts, minimum attainable error, and missing required instruction IDs) and surfacing those diagnostics through the Python bindings, along with updated tests and a sample notebook demonstrating common failure modes.

Changes:

• Added structured diagnostic fields to EstimationCollection and populated them in both direct parallel estimation and provenance-graph estimation paths.
• Reworked Python-side “zero results” messaging to use structured diagnostics (instead of parsing error strings) and updated Python/Rust tests accordingly.
• Added a new zero_estimates.ipynb sample that demonstrates error-budget exclusion and transform incompatibility due to missing instructions.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
source/qre/src/trace/tests.rs	Adds Rust tests validating missing-instruction reporting and exact-min-error diagnostics.
source/qre/src/trace/estimation.rs	Implements diagnostic collection (missing instructions, max-error rejections, min successful error) across both estimation paths, including conditional “no cutoff” diagnostic passes.
source/qre/src/result.rs	Extends EstimationCollection with new diagnostic fields and accessors.
source/qre/src/isa/provenance.rs	Adds ProvenanceGraph::nodes() iterator to support diagnostic enumeration.
source/qdk_package/tests/qre/test_estimation.py	Adds Python tests for the new structured zero-results warning behavior.
source/qdk_package/src/qre.rs	Exposes new diagnostics through Python bindings (sorted missing-instruction IDs).
source/qdk_package/qdk/qre/_qre.pyi	Updates Python type stubs with the new EstimationCollection properties.
source/qdk_package/qdk/qre/_estimation.py	Implements structured zero-results warning construction and updates estimation flow to print it.
samples/qre/zero_estimates.ipynb	Adds a notebook demonstrating the new diagnostics for common “zero estimates” scenarios.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.