Skip to content

Add an energy-accounting figure to the molecular QPE tutorial #627

Description

Problem

Chapter 6 of the ground-state molecular-QPE tutorial explains energy accounting
through equations and prose:

  1. IQPE estimates an active-space qubit-Hamiltonian eigenvalue.
  2. The classically stored core energy is added to reconstruct the selected-space
    molecular total.
  3. That reconstructed total is compared with the CASCI energy of the same
    selected-space Hamiltonian.

These quantities have different physical and algorithmic roles, but students must
currently hold the complete relationship in working memory while moving between
the equations, script output, and final interpretation questions.

A compact visual could clarify the bookkeeping without introducing another
calculation or changing the tutorial workflow.

Desired outcome

Add an accessible Chapter 6 figure that distinguishes:

  • measured active energy, E_active^IQPE;
  • classically added core energy, E_core;
  • reconstructed molecular total, E_total^IQPE;
  • matching selected-space CASCI reference, E_CASCI; and
  • signed algorithmic difference, Delta E_algorithm.

The visual should make the two relationships explicit:

E_total^IQPE = E_active^IQPE + E_core
Delta E_algorithm = E_total^IQPE - E_CASCI

Design constraints

  • Keep algorithmic error separate from basis-set and active-space model error.
  • Do not imply that IQPE measures the core energy.
  • Do not compare the result with experiment or a larger-space reference.
  • Use the existing tutorial values only if they improve interpretation; avoid
    making a reusable conceptual figure unnecessarily parameter-specific.
  • Follow the tutorial's established visual conventions.
  • Provide alt text, a useful caption, and an equivalent textual explanation.
  • If the figure is generated quantitatively, commit a reproducible maintenance
    script outside the Sphinx build.

Suggested placement

Place the figure in Chapter 6 after the equations defining
E_total^IQPE and Delta E_algorithm, before the question asking which energy
comparison determines whether the workflow meets the teaching target.

Acceptance criteria

  • The figure clearly separates measured, classically added, reconstructed, and
    reference quantities.
  • The direction and sign of Delta E_algorithm are unambiguous.
  • The surrounding text and cumulative lab-notebook assignment use the same
    terminology.
  • Alt text and caption communicate the bookkeeping without relying on color or
    layout alone.
  • Sphinx builds successfully and the figure remains legible on a student laptop.
  • The relevant student and specialist reviews find no misleading energy or error
    interpretation.

Additional context

This is post-merge visual follow-up from the ground-state QPE tutorial TODO. The
current prose is scientifically complete; this issue is an optional pedagogical
improvement rather than a correctness blocker.

Metadata

Metadata

Labels

documentationImprovements or additions to documentationenhancementNew feature or request

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions