qdk_chemistry.data.unitary_representation.containers.block_encoding module

QDK/Chemistry block encoding container module.

class qdk_chemistry.data.unitary_representation.containers.block_encoding.BlockEncodingContainer[source]

Bases: UnitaryContainer

Abstract base class for block encoding containers.

abstract property power: int[source]

Number of times to apply the block encoding.

class qdk_chemistry.data.unitary_representation.containers.block_encoding.ControlledOperation(ctrl_state, operation)[source]

Bases: object

A single controlled unitary operation in the SELECT oracle.

Parameters:

  • ctrl_state (int)

  • operation (str)

ctrl_state: int

Integer encoding of the control state that activates this operation.

operation: str

Operation descriptor (e.g., a Pauli string like "XZI").

to_hdf5(group)[source]

Save the ControlledOperation to an HDF5 group.

Return type:

None

Parameters:

group (h5py.Group) – HDF5 group to write attributes to.

classmethod from_hdf5(group)[source]

Load a ControlledOperation from an HDF5 group.

Return type:

ControlledOperation

Parameters:

group (h5py.Group) – HDF5 group to read attributes from.

Returns:

The deserialized instance.

Return type:

ControlledOperation

__init__(ctrl_state, operation)
Parameters:

  • ctrl_state (int)

  • operation (str)

Return type:

None

class qdk_chemistry.data.unitary_representation.containers.block_encoding.LCUContainer(prepare, select, power=1)[source]

Bases: BlockEncodingContainer

Container for a Linear Combination of Unitaries (LCU) decomposition.

Stores the pre-computed PREPARE and SELECT sub-objects that define a block-encoding circuit. This container is agnostic to the specific method used to compute these objects — that logic lives in the builder.

\[W = \text{PREPARE}^\dagger \cdot \text{SELECT} \cdot \text{PREPARE}\]
Parameters:
__init__(prepare, select, power=1)[source]

Initialize an LCUContainer.

Parameters:

  • prepare (Wavefunction) – The prepare wavefunction encoding coefficients for the block encoded Hamiltonian.

  • select (Select) – The select oracle for controlled operations.

  • power (int) – Number of times to apply the block encoding (for B[H]^power).

Return type:

None

property power: int[source]

Number of times to apply the block encoding.

Returns:

The power value.

Return type:

int

property num_prepare_ancillas: int[source]

Number of qubits in the prepare ancillary register.

Derived from the orbital basis size of the prepare wavefunction.

Returns:

The ancilla qubit count.

Return type:

int

property num_qubits: int[source]

Total number of qubits (system + ancilla).

Returns:

The combined qubit count.

Return type:

int

property type: str[source]

Get the type of the unitary container.

Returns:

The type string "lcu".

Return type:

str

to_json()[source]

Save the LCUContainer to a JSON-serializable dictionary.

Return type:

dict[str, Any]

Returns:

Dictionary representation including container type, power,

prepare, and select fields.

Return type:

dict[str, Any]

to_hdf5(group)[source]

Save the LCUContainer to an HDF5 group.

Return type:

None

Parameters:

group (h5py.Group) – HDF5 group to write container data to.

classmethod from_json(json_data)[source]

Create an LCUContainer from a JSON dictionary.

Return type:

LCUContainer

Parameters:

json_data (dict[str, Any]) – Dictionary containing the serialized LCU data.

Returns:

The deserialized instance.

Return type:

LCUContainer

classmethod from_hdf5(group)[source]

Load an LCUContainer from an HDF5 group.

Return type:

LCUContainer

Parameters:

group (h5py.Group) – HDF5 group to read container data from.

Returns:

The deserialized instance.

Return type:

LCUContainer

get_summary()[source]

Get a human-readable summary of the LCU container.

Return type:

str

Returns:

Multi-line summary describing power, prepare, and select settings.

Return type:

str

eigenvalue_from_phase(phase_fraction)[source]

Not applicable for a raw block encoding.

A plain block encoding does not define an eigenvalue-phase relationship on its own. Use LCUWalkContainer for QPE with qubitization.

Return type:

float

Raises:

NotImplementedError – Always.

Parameters:

phase_fraction (float)

class qdk_chemistry.data.unitary_representation.containers.block_encoding.Select(controlled_operations, phases, num_prepare_ancillas, num_target_qubits, prepare_qubits, target_qubits)[source]

Bases: object

Class representing the SELECT oracle for block encoding.

Parameters:
controlled_operations: list[ControlledOperation]

List of controlled operations.

phases: ndarray

Array of +1/-1 phase corrections (uncontrolled global phase per term).

num_prepare_ancillas: int

Number of control qubits.

num_target_qubits: int

Number of target (system) qubits.

prepare_qubits: list[int]

List of qubit indices for the prepare register.

target_qubits: list[int]

List of qubit indices for the target (system) register.

to_hdf5(group)[source]

Save the Select oracle to an HDF5 group.

Return type:

None

Parameters:

group (h5py.Group) – HDF5 group to write phases, attributes, and controlled operations to.

classmethod from_hdf5(group)[source]

Load a Select oracle from an HDF5 group.

Return type:

Select

Parameters:

group (h5py.Group) – HDF5 group to read phases, attributes, and controlled operations from.

Returns:

The deserialized instance.

Return type:

Select

__init__(controlled_operations, phases, num_prepare_ancillas, num_target_qubits, prepare_qubits, target_qubits)
Parameters:
Return type:

None