【创新应用】QSEncode-Insight：面向误差预算的资源感知量子态制备与审计工具

[Mack-blip-space]

参赛方向：创新应用类
关联赛题：#13
团队名称：这很量子
团队成员：@Mack-blip-space、@totoy0312

Summary

This PR adds QSEncode-Insight alongside the existing QSpare_Code API. It turns
error-budgeted coefficient truncation into an end-to-end, resource-aware state
preparation workflow and preserves the legacy implementation unchanged.

QSEncode-Insight is submitted as an innovation-application tool. It does not
claim to invent the PyQPanda3 amplitude_encode, sparse_isometry, or
ds_quantum_state_preparation primitives. Its contribution is the reproducible
decision and audit layer around those primitives: fidelity-budgeted truncation,
capability filtering, compiled-resource comparison, deterministic selection,
semantic verification, attribution, and an explicit refusal path.

This differs from PR #51, which focuses on legacy QSEncode tests and
documentation, and PR #52, which optimizes Walsh/Top-K implementation details
inside the legacy module. This PR leaves QSpare_Code.py byte-for-byte
unchanged and contributes a separate end-to-end application and public API.

Motivation

A fixed coefficient cut does not directly express a fidelity requirement, and a
smaller coefficient set does not necessarily produce a cheaper compiled circuit.
Different state-preparation methods also have different compatibility and resource
profiles. QSEncode-Insight therefore evaluates the complete path from fidelity
budget to compiled resource selection and can explicitly decline compression when
no candidate improves on the dense baseline.

What changed

• Added canonical probability validation, normalization, padding, and stable input
  hashes.
• Added an O(N log N) FWHT implementation and an orthonormal Fourier mode.
• Added fidelity-targeted minimal k* analysis and the frozen neighboring-candidate
  policy.
• Added capability adapters for amplitude_encode, sparse_isometry, and
  DS_quantum_state_preparation.
• Added five-repeat compiled resource auditing, required-width accounting, and
  deterministic resource-aware selection.
• Added explicit COMPRESS / DO_NOT_COMPRESS results and truncation/preparation
  resource attribution.
• Added standard verification and five-repeat audit semantic certification.
• Activated the public QSEncodeInsight.analyze() and prepare() facade with
  result/input/config binding checks.
• Added a minimal JSON CLI, a Run-All notebook demo, user documentation, benchmark
  evidence boundaries, and regression coverage.
• Added a visual benchmark summary that exposes dimension/family behavior and
  DO_NOT_COMPRESS decisions instead of presenting only the pooled headline.

Validation

• Full repository suite: 254 passed on both the frozen Python 3.14.2
  environment and a clean Python 3.12.10 compatibility environment, using
  PyQPanda3 0.3.5, NumPy 2.4.6, SciPy 1.17.1, and SymPy 1.14.0.
• Clean Python 3.12.10 submission checks: 237 QSEncode tests passed, wheel
  build/install passed, and installed-wheel API, CLI, and notebook Run-All
  smoke checks passed.
• Sealed Gaussian N=8 regression:
  • Walsh: k*=4, DO_NOT_COMPRESS, dense baseline about 21 two-qubit gates / 37
    depth.
  • Fourier: k*=4, selects sparse_isometry, about 37 two-qubit gates / 61-62
    depth versus the dense baseline's about 114 / 205.
  • Audit mode: 5/5 compiled semantic certifications with minimum fidelity at least
    1 - 1e-10.
• Notebook cells execute top-to-bottom in one clean namespace.
• CLI help, inline/file JSON analysis, invalid basis, and invalid input paths are
  covered by tests.

Reproduction commands from the repository root:

python -m pip install -r pyqpanda-algorithm/requirements-qseencode-insight-test.txt
python -m pytest -c pyqpanda-algorithm/pytest-qseencode.ini
python -m pytest -c test/pytest.ini -o "addopts=-q -p no:cacheprovider"

The preregistered 480-cell generalization benchmark completed all cells and reached
strong_pass in both explicitly selected basis modes under the selector-all metric:

Basis	Compiled 2q reduction	Compiled depth reduction
Walsh	45.27%	48.78%
Fourier	71.11%	69.82%

These are compiled-resource results within the declared test scope; they are not a
claim of quantum advantage or hardware runtime acceleration.

Backward compatibility

• QSpare_Code.py is byte-for-byte unchanged.
• The existing QSpare_Code export remains available.
• QSEncode-Insight is an additional public API and does not import frozen benchmark
  artifacts at runtime.

Scope and limitations

• The validated-default evidence scope is fidelity_target=0.99, explicitly chosen
  Walsh or Fourier mode, N in {8,16,32,64}, default method order, five technical
  repetitions, and the frozen compiler profile on PyQPanda3 0.3.5.
• There is no automatic cross-basis selector in this version.
• Some candidate constructors are incompatible with some inputs; capability
  filtering and fallback are expected product behavior.
• Dirichlet inputs were materially weaker than the other preregistered primary
  families, and DO_NOT_COMPRESS remains a normal result.
• Behavior outside the validated scope is reported as outside_validated_scope.