qdk_chemistry.utils.phase module

Utility functions for manipulating phases produced by QPE.

qdk_chemistry.utils.phase.accumulated_phase_from_bits(bits_msb_first)

Compute Φ(1) directly from a measured bit string (MSB to LSB).

Return type:

float

Parameters:

bits_msb_first (Sequence[int]) – Sequence of measured bits ordered from MSB to LSB.

Returns:

Accumulated phase angle Φ(1).

qdk_chemistry.utils.phase.energy_alias_candidates(raw_energy, *, evolution_time, shift_range=range(-2, 3))

Enumerate alias energies compatible with raw_energy.

Return type:

list[float]

Parameters:

• raw_energy (float) – Energy derived from the measured phase.

• evolution_time (float) – Evolution time t used by the unitary.

• shift_range (Iterable[int]) –

  Integer shifts (in multiples of 2π / t) to explore.

  The default range(-2, 3) checks k = -2, -1, 0, 1, 2—a pragmatic window that typically covers chemical-energy estimates because they rarely deviate by more than one or two 2π / t periods from the raw measurement.

Returns:

Sorted list of alias energy values covering positive and negative branches.

qdk_chemistry.utils.phase.energy_from_phase(phase_fraction, *, evolution_time)

Convert a measured phase fraction to energy using E = angle / t.

Return type:

float

Parameters:

• phase_fraction (float) – Fractional phase obtained from the phase register.

• evolution_time (float) – Evolution time t used in U = exp(-i H t).

Returns:

Energy estimate corresponding to phase_fraction.

qdk_chemistry.utils.phase.iterative_phase_feedback_update(current_phase, measured_bit)

Update the feedback phase according to Kitaev’s recursion [Kit95].

Return type:

float

Parameters:

• current_phase (float) – Phase Φ(k+1) from the previous iteration.

• measured_bit (int) – Measured classical bit j_k (0 or 1).

Returns:

Updated feedback phase Φ(k) for the next iteration.

Raises:

ValueError – If measured_bit is not 0 or 1.

qdk_chemistry.utils.phase.phase_fraction_from_feedback(phase_feedback)

Convert the final feedback phase Φ(1) into the phase fraction φ.

Return type:

float

Parameters:

phase_feedback (float) – Final feedback phase angle returned by IQPE.

Returns:

Phase fraction corresponding to phase_feedback.

qdk_chemistry.utils.phase.resolve_energy_aliases(raw_energy, *, evolution_time, reference_energy, shift_range=range(-2, 3))

Select the alias energy closest to a known reference value.

Return type:

float

Parameters:

• raw_energy (float) – Energy derived from the measured phase.

• evolution_time (float) – Evolution time t used by the unitary.

• reference_energy (float) – External reference guiding alias selection.

• shift_range (Iterable[int]) –

  Integer shifts (in multiples of 2π / t) to explore.

  Use a wider window when the true value may sit multiple periods away from the raw estimate.

Returns:

Alias energy closest to reference_energy.