[Transformation] Make ExpPauli decomposition phase exact

[cabreraam]

Warning

This PR depends on #4976, #5022, #5044, #5058, #5062, #5066, #5071, and #5081 so it shouldn't be reviewed until each of those PRs has been upstreamed.

Summary

Makes ExpPauliDecomposition phase exact whenever it applies.

All-identity Pauli words are no longer erased as “only global phase. They now emit an exact quake.phase correction that preserves the source operation’s adjoint sign, ordered controls, negative-control polarities, and wire results.

Motivation

For an all-identity Pauli word:

$$\exp(i\theta I^{\otimes n}) = e^{i\theta} I^{\otimes n}$$

Erasing that factor is not an exact rewrite. It becomes observable when the operation is controlled, and it must remain represented in the IR until the phase lifecycle reaches its intentional lowering boundary.

The revised design requires ordinary decomposition to have one contract:

A successful rewrite preserves the complete unitary, including scalar phase. Otherwise, it must leave the source operation unchanged.

What changed

• Add reusable, IR-free static target planning in QuakeOperatorUtilities.h.

  • Select a deterministic scalar target without creating quake.extract_ref.
  • Materialize an extraction only after all failure-prone validation succeeds.

• Make identity-only exp_pauli exact.

  • exp_pauli(theta) ... to "III" becomes quake.phase(theta).
  • Adjoint identity words use quake.phase(-theta).
  • Controls, negative-control attributes, and wire values are threaded exactly.
  • Literal zero phases are omitted.

• Preserve the existing exact non-identity lowering:

  • basis changes for X/Y;
  • CNOT parity ladder over non-identity support;
  • Rz(-2 * theta) on the parity accumulator;
  • reverse parity ladder and inverse basis changes.

• Restrict non-identity rewriting to forms the current lowering can represent exactly.

  • Controlled non-identity ExpPauli remains unchanged.
  • Wire-form non-identity ExpPauli remains unchanged.
  • Unsupported non-identity float forms remain unchanged.

• Add conservative Phase anchor/predicate validation in PhaseUtilities.h.

  • Reject an anchor that may overlap a control predicate.
  • Reject predicates with repeated or structurally overlapping controls.
  • Share the same structural check with LowerPhase.

Anchor safety

quake.phase requires one scalar !quake.ref or !quake.wire anchor. For identity ExpPauli, the rewrite selects the last legal statically identifiable target.

The implementation deliberately does not assume that distinct vector indices imply distinct qubits: a vector may be built from repeated references, for example through quake.concat. If the compiler cannot prove a legal anchor outside the predicate, the source ExpPauli is retained.

Tests

• Add strict ExpPauli equivalence coverage using CircuitCheck without global-phase relaxation.
• Cover forward and adjoint identity words.
• Cover positive, negative, and mixed control predicates.
• Cover static vector targets, mixed scalar/vector targets, and wire threading.
• Cover exact non-identity X, Y, Z, and mixed Pauli-word lowering.
• Verify ordinary basis conversion selects the exact decomposition without a special policy path.
• Add retention regressions for dynamic/empty/mismatched targets, unknown or invalid Pauli words, malformed predicates, control/anchor aliases, duplicate controls, unsupported controlled/wire non-identity forms, and unsupported float types.
• Preserve and update existing ExpPauli decomposition regression expectations for deterministic target materialization.

[github-actions]

CI Summary (push) — ❌ failed

Run #31641458347 · ✅ 3 · ⏩ 8 · ❌ 2 · ⛔ 0

❌ Failed or cancelled

Job	Result	Link
wheeldeps	❌ failure	view
build_and_test	❌ failure	view

Top-level jobs (13)

Job	Result
binaries	⏩ skipped
build_and_test	❌ failure
config_devdeps	✅ success
config_source_build	⏩ skipped
config_wheeldeps	⏩ skipped
devdeps	✅ success
docker_image	⏩ skipped
gen_code_coverage	⏩ skipped
metadata	✅ success
python_metapackages	⏩ skipped
python_wheels	⏩ skipped
source_build	⏩ skipped
wheeldeps	❌ failure

⏩ Skipped jobs (8) — intentionally skipped on PR builds; run on merge_group / workflow_dispatch

Job
binaries
config_source_build
config_wheeldeps
docker_image
gen_code_coverage
python_metapackages
python_wheels
source_build

All sub-jobs (42) — every matrix leg, with links

Job	Status	Link
Build and test (amd64, gcc12, openmpi) / Dev environment (Debug)	❌ failure	view
Build and test (amd64, gcc12, openmpi) / Dev environment (Python)	❌ failure	view
Build and test (amd64, llvm, openmpi) / Dev environment (Debug)	❌ failure	view
Build and test (amd64, llvm, openmpi) / Dev environment (Python)	❌ failure	view
Build and test (arm64, llvm, openmpi) / Dev environment (Debug)	❌ failure	view
Build and test (arm64, llvm, openmpi) / Dev environment (Python)	❌ failure	view
CI Summary	❔ in_progress	view
Configure build (devdeps)	✅ success	view
Configure build (source_build)	⏩ skipped	view
Configure build (wheeldeps)	⏩ skipped	view
Create CUDA Quantum installer	⏩ skipped	view
Create Docker images	⏩ skipped	view
Create Python metapackages	⏩ skipped	view
Create Python wheels	⏩ skipped	view
Gen code coverage	⏩ skipped	view
Load dependencies (amd64, gcc12) / Caching	✅ success	view
Load dependencies (amd64, gcc12) / Finalize	✅ success	view
Load dependencies (amd64, gcc12) / Metadata	✅ success	view
Load dependencies (amd64, llvm) / Caching	✅ success	view
Load dependencies (amd64, llvm) / Finalize	✅ success	view
Load dependencies (amd64, llvm) / Metadata	✅ success	view
Load dependencies (arm64, gcc12) / Caching	✅ success	view
Load dependencies (arm64, gcc12) / Finalize	✅ success	view
Load dependencies (arm64, gcc12) / Metadata	✅ success	view
Load dependencies (arm64, llvm) / Caching	✅ success	view
Load dependencies (arm64, llvm) / Finalize	✅ success	view
Load dependencies (arm64, llvm) / Metadata	✅ success	view
Load source build cache	⏩ skipped	view
Load wheel dependencies (amd64, 12.6) / Caching	❌ failure	view
Load wheel dependencies (amd64, 12.6) / Finalize	✅ success	view
Load wheel dependencies (amd64, 12.6) / Metadata	✅ success	view
Load wheel dependencies (amd64, 13.0) / Caching	✅ success	view
Load wheel dependencies (amd64, 13.0) / Finalize	✅ success	view
Load wheel dependencies (amd64, 13.0) / Metadata	✅ success	view
Load wheel dependencies (arm64, 12.6) / Caching	✅ success	view
Load wheel dependencies (arm64, 12.6) / Finalize	✅ success	view
Load wheel dependencies (arm64, 12.6) / Metadata	✅ success	view
Load wheel dependencies (arm64, 13.0) / Caching	✅ success	view
Load wheel dependencies (arm64, 13.0) / Finalize	✅ success	view
Load wheel dependencies (arm64, 13.0) / Metadata	✅ success	view
Prepare cache clean-up	❔ queued	view
Retrieve PR info	✅ success	view

⚠️ Required checks (0/6) — 6 missing — declared in .github/required-checks.yml for push

Required check	Status	Link
Build and test (amd64, llvm, openmpi) / Dev environment (Debug)	❌ failure	view
Build and test (amd64, llvm, openmpi) / Dev environment (Python)	❌ failure	view
Build and test (arm64, llvm, openmpi) / Dev environment (Debug)	❌ failure	view
Build and test (arm64, llvm, openmpi) / Dev environment (Python)	❌ failure	view
Build and test (amd64, gcc12, openmpi) / Dev environment (Debug)	❌ failure	view
Build and test (amd64, gcc12, openmpi) / Dev environment (Python)	❌ failure	view