qdk_chemistry.algorithms.controlled_circuit_mapper package

QDK/Chemistry controlled circuit mapper module.

class qdk_chemistry.algorithms.controlled_circuit_mapper.ControlledCircuitMapperFactory

Bases: AlgorithmFactory

Factory class for creating ControlledCircuitMapper instances.

algorithm_type_name()

Return controlled_circuit_mapper as the algorithm type name.

Return type:

str

default_algorithm_name()

Return pauli_sequence as the default algorithm name.

Return type:

str

class qdk_chemistry.algorithms.controlled_circuit_mapper.ControlledCircuitMapperSettings

Bases: Settings

Settings for the ControlledCircuitMapper.

control_indices

The control qubit indices. Defaults to [0].

target_indices

The target qubit indices. An empty list means auto-fill based on the unitary’s qubit count and control indices.

__init__()

Initialize the settings for ControlledCircuitMapper.

class qdk_chemistry.algorithms.controlled_circuit_mapper.ControlledPSPMapper

Bases: ControlledCircuitMapper

Controlled circuit mapper using the PREPARE-SELECT-PREPARE pattern.

A wrapper over PSPMapper, which owns the PREPARE and SELECT oracles:

\[B[H] = \mathrm{PREPARE}^\dagger \cdot \mathrm{SELECT} \cdot \mathrm{PREPARE}\]

When the input is an LCUWalkContainer, the block encoding is additionally wrapped with the reflection operator to form a quantum walk:

\[W = (2|0\rangle\langle 0| - I) \cdot B[H]\]
__init__()

Initialize the ControlledPSPMapper.

name()

Return the algorithm name.

Returns:

The name "prepare_select_prepare".

Return type:

str

type_name()

Return the algorithm type name.

Returns:

The type name "controlled_circuit_mapper".

Return type:

str

class qdk_chemistry.algorithms.controlled_circuit_mapper.ControlledPSPMapperSettings

Bases: ControlledCircuitMapperSettings

Settings for the ControlledPSPMapper.

prepare

Algorithm reference for the PREPARE oracle state preparation. Defaults to DensePureStatePreparation.

__init__()

Initialize the settings for ControlledPSPMapper.

class qdk_chemistry.algorithms.controlled_circuit_mapper.ControlledPauliSequenceMapper

Bases: ControlledCircuitMapper

Controlled evolution circuit mapper using Pauli product formula term sequences.

Given a time-evolution operator expressed as a Pauli product formula \(U(t) \approx \left[ U_{\mathrm{step}}(t / r) \right]^{r}\), this mapper constructs a controlled version of \(U(t)\) using the following pattern:

  1. Each Pauli operator \(P_j\) is basis-rotated into the \(Z\) basis.

  2. Qubits involved in \(P_j\) are entangled into a sequence using CNOT gates.

  3. A controlled \(R_z\) rotation implements

    \(e^{-i\,\theta_j\,P_j} \;\rightarrow\; \text{CRZ}(2 \theta_j)\).

  4. The basis rotations and entangling operations are uncomputed.

Notes

  • Currently supports only single-control-qubit scenarios.

  • Requires a PauliProductFormulaContainer for the time evolution unitary.

__init__()

Initialize the PauliSequenceMapper.

name()

Return the algorithm name.

Return type:

str

type_name()

Return controlled_circuit_mapper as the algorithm type name.

Return type:

str

class qdk_chemistry.algorithms.controlled_circuit_mapper.ControlledSwapPauliSequenceMapper

Bases: ControlledCircuitMapper

Controlled evolution circuit mapper using a CSWAP-sandwich construction.

Given a time evolution as a Pauli product formula \(U(t) \approx \left[ U_{\mathrm{step}}(t / r) \right]^{r}\), this mapper builds a controlled \(U(t)\) without controlling every gate. An internally allocated vacuum register (\(|0\ldots0\rangle\)) is conditionally swapped with the system, the uncontrolled evolution runs on the vacuum (step_reps times), and the swap is uncomputed. The eigenphase accumulates on the \(|1\rangle\) control branch, as with a directly controlled evolution, using an additional system-sized register and two layers of system-wide controlled-\(\mathrm{SWAP}\) gates.

Vacuum phase. The \(|0\rangle\) branch acquires \(U|0\ldots0\rangle = e^{i\varphi_0}|0\ldots0\rangle\) with \(\varphi_0 = -E_0 t\) and \(E_0 = \langle 0\ldots0|H|0\ldots0\rangle\). Only the diagonal (\(I\)/\(Z\)) terms of the product formula contribute, so \(\varphi_0\) is known classically and is cancelled by an \(R_1(\varphi_0)\) on the control. The circuit is then a genuine \(C\text{-}U\) up to a global phase for any \(E_0\).

Grouping requirement. The vacuum must stay an eigenstate, which is what particle conservation buys: \(H\) cannot connect \(|0\ldots0\rangle\) to any other occupation number. Leaked amplitude entangles the vacuum register with the control and destroys the control coherence. A fermionic term annihilates the vacuum only through the weighted sum of its Pauli strings, so a Trotterised \(U\) preserves the vacuum only when those strings are exponentiated as one contiguous, mutually commuting block:

\[U|0\ldots0\rangle = e^{-it\sum_i P_i}|0\ldots0\rangle \approx \prod_i e^{-it P_i}|0\ldots0\rangle = |0\ldots0\rangle .\]

Grouping the Hamiltonian with the vacuum_annihilating term grouper (VacuumAnnihilatingTermGrouper) produces that ordering. The incoming formula is validated and rejected otherwise; interleaving cancellation partners, say XX, Z0, YY, I for \(H = \tfrac12(XX + YY) + \tfrac12(I - Z_0)\), leaks half the vacuum amplitude.

Notes

  • Applies to particle-conserving Hamiltonians.

  • The requirement is on the mapped operator, not the encoding: after qubit tapering the all-zero state belongs to the retained sector, which the Hamiltonian need not annihilate.

  • Currently supports only single-control-qubit scenarios.

  • Requires a PauliProductFormulaContainer for the time evolution unitary.

  • The vacuum register is allocated internally by the Q# operation.

__init__()

Initialize the ControlledSwapPauliSequenceMapper.

name()

Return the algorithm name.

Return type:

str

type_name()

Return controlled_circuit_mapper as the algorithm type name.

Return type:

str

class qdk_chemistry.algorithms.controlled_circuit_mapper.ControlledSwapPauliSequenceMapperSettings

Bases: ControlledCircuitMapperSettings

Settings for the ControlledSwapPauliSequenceMapper.

vacuum_preservation_tolerance

Absolute tolerance on the amplitude leaked out of the vacuum, aggregated over every flipped-qubit set and over all step_reps repetitions.

__init__()

Initialize the settings for ControlledSwapPauliSequenceMapper.

Submodules