Skip to content

Update molecular QPE tutorial to current sparse-isometry API #669

Description

Context

The molecular QPE tutorial currently creates state preparation with the factory key:

create("state_prep", "sparse_isometry_gf2x")

PR #435, merged into main as 02c50634, renamed the implementation to sparse_isometry. Current source keeps sparse_isometry_gf2x as a deprecated alias that emits DeprecationWarning and resolves to the same SparseIsometryStatePreparation type.

The tutorial is pinned to published QDK/Chemistry 2.1.0. PR #435 merged after v2.1.0 and is not contained in any published release, so the tutorial cannot adopt the new key until it points to a release containing #435.

Blockers

Do not begin this migration until:

  1. a QDK/Chemistry release containing PR Implement sparse isometry with binary encoding #435 is published; and
  2. GROUND_STATE_TUTORIAL_VERSION points to that release.

This work should follow #625 / PR #664, which owns the next tutorial release-pin update.

Scope

  • Replace sparse_isometry_gf2x with sparse_isometry in:
    • tutorial_prepare_trial_state.py;
    • tutorial_qpe_setup.py; and
    • Chapter 5 prose, links, and API terminology.
  • Remove the deprecation warnings from tutorial tests and script execution.
  • Confirm whether default sparse_isometry settings reproduce the tutorial's existing GF(2^x) behavior or whether settings must be explicit.
  • Regenerate and review trial-state circuit data and any dependent static circuit assets.
  • Revalidate downstream IQPE circuit construction and execution.

Risks to validate

Although the deprecated key currently resolves to the same implementation type on main, do not assume all observable tutorial outputs are unchanged. Check:

  • generated Q# circuit structure;
  • compute-register width;
  • logical gate totals and gate-family counts for one-, two-, and four-determinant trial states;
  • trial-state fidelities;
  • rendered notebook circuits;
  • state-preparation comparison images and other committed circuit assets;
  • IQPE iteration circuits and exact tutorial snapshots.

Any intentional output change should be documented and reviewed separately from the API rename.

Acceptance criteria

  • The ground-state QPE tutorial contains no sparse_isometry_gf2x reference.
  • Tutorial scripts and setup checks run without sparse-isometry deprecation warnings.
  • Chapter 5 uses the current factory name and links to current state-preparation documentation.
  • Trial-state and IQPE scripts and notebooks pass against the pinned published wheel.
  • Exact snapshots are unchanged, or reviewed updates clearly explain every intentional difference.
  • Circuit images/assets are confirmed current or regenerated as needed.
  • The change is delivered through a focused PR separate from the script-readability cleanup in Clean up molecular QPE tutorial notebook support scripts #665 / PR Simplify molecular QPE tutorial scripts #667.

Related: #435, #625, #665, #667

Metadata

Metadata

Labels

blockedPR which is blocked by another pending changedocumentationImprovements or additions to documentationrefactor/cleaningSmaller change to clean up or clarify code.

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions