qrunch.quantum.algorithms.pauli.vqes.gate_pool

Module containing everything needed to create gate pools used in adaptive VQEs.

Classes

`CustomGatePool`	Class to build and generate a custom gate pool.
`CustomGatePoolOperator`	Custom gate pool operator used in a gate pool.
`DoubleExcitationGatePoolOperator`	Double excitation gate used in a gate pool.
`DoubleExcitationOperator`	Represents a double excitation operator and hold the indices of the operation.
`ExcitationGatePoolProtocol`	Protocol for gate pools that support fast excitation-based index generation.
`ExcitationPoolConfiguration`	Configuration for excitation-based gate pools.
`GatePool`	Class to build and generate a gate pool.
`GatePoolOperator`	Interface for a gate pool operator.
`InitialGatePoolRanking`	Results from a gate pool ranking.
`SingleExcitationGatePoolOperator`	Single excitation gate used in a gate pool.
`SingleExcitationOperator`	Represents a single excitation operator and hold the indices of the operation.

class CustomGatePool

Bases: GatePool

Class to build and generate a custom gate pool.

__init__(gate_pool_operators: Sequence[GatePoolOperator]) → None

Initiate custom gate pool with the given operators.

Parameters:: gate_pool_operators (Sequence[GatePoolOperator]) – List of gate pool operators in the custom gate pool.
Return type:: None

calculate_initial_gate_pool_ranking(top_k: int) → InitialGatePoolRanking | None

Build the initial ranking for the gate pool. Custom gate pool does not support initial ranking.

Parameters:: top_k (int)
Return type:: InitialGatePoolRanking | None

supports_fast_index_generation() → bool

Check if the gate pool support fast rust index generation.

Return type:: bool

class CustomGatePoolOperator

Bases: GatePoolOperator

Custom gate pool operator used in a gate pool.

__init__(gate: Gate, generator: AntiHermitianPauliSum | Expression[PauliOperators]) → None

Initiate a custom gate pool operator with the given gate and generator.

The gate implementing an operator \(\hat{G}\) is related to the generator \(\hat{A}\) through:

\[\hat{G}(\phi) = e^{\phi \hat{A}}.\]

NB. It is not validated that the gate and generator fulfills this relation.

Parameters:

gate (Gate) – Gate for the gate pool operator.
generator (AntiHermitianPauliSum | Expression[PauliOperators]) – generator for the gate pool operator.

Raises:

GatePoolError – If the gate does not contain exactly one free parameter.

Return type:

None

get_gate(parameter: Parameter) → Gate

Get gate for the gate pool operator.

Parameters:: parameter (Parameter) – Parameter to be used in gate.
Return type:: Gate

get_generator() → SingleExcitationOperator | DoubleExcitationOperator | AntiHermitianPauliSum

Get generator for the gate pool operator.

Parameters:: parameter – Parameter to be used in gate.
Return type:: SingleExcitationOperator | DoubleExcitationOperator | AntiHermitianPauliSum

get_generator_indices() → tuple[int, ...]

Get the generator indices directly without creating an intermediate operator.

Returns:: Tuple of (creation_qubit_index, annihilation_qubit_index).
Return type:: tuple[int, …]

class DoubleExcitationGatePoolOperator

Bases: GatePoolOperator

Double excitation gate used in a gate pool.

The gate is a qrunch.core.circuit.composite_gates.DoubleExcitationGate and the generator is a \(A = Q_p^\dagger Q_q^\dagger Q_r Q_s - Q_r^\dagger Q_s^\dagger Q_p Q_q\), where \(Q_i\) and \(Q_i^\dagger\) removes and adds one qubit excitation for the \(i\)’th site, respectively.

__init__(creation_qubit_index_1: int, creation_qubit_index_2: int, annihilation_qubit_index_1: int, annihilation_qubit_index_2: int) → None

Initiate an instance of the double excitation gate pool gate.

Parameters:

creation_qubit_index_1 (int) – First qubit index for the gate.
creation_qubit_index_2 (int) – Second qubit index for the gate.
annihilation_qubit_index_1 (int) – Third qubit index for the gate.
annihilation_qubit_index_2 (int) – Four qubit index for the gate.

Return type:

None

get_gate(parameter: Parameter) → DoubleExcitationGate

Get gate for the gate pool operator.

Parameters:: parameter (Parameter) – Parameter to be used in gate.
Return type:: DoubleExcitationGate

get_generator() → DoubleExcitationOperator

Get generator for the gate pool operator.

Parameters:: parameter – Parameter to be used in gate.
Return type:: DoubleExcitationOperator

get_generator_indices() → tuple[int, int, int, int]

Get the generator indices directly without creating an intermediate operator.

Returns:

Tuple of (creation_qubit_index_1, creation_qubit_index_2,: annihilation_qubit_index_1, annihilation_qubit_index_2).

Return type:

tuple[int, int, int, int]

class DoubleExcitationOperator

Bases: object

Represents a double excitation operator and hold the indices of the operation.

This operator is the generator of the DoubleExcitationGate. All fields are immutable (frozen=True) so an instance can be safely reused.

Parameters:

creation_qubit_index_1 – The index of the first qubit where the excitation is created.
creation_qubit_index_2 – The index of the second qubit where the excitation is created.
annihilation_qubit_index_1 – The index of the first qubit where the excitation is annihilated.
annihilation_qubit_index_2 – The index of the second qubit where the excitation is annihilated.

__init__(creation_qubit_index_1: int, creation_qubit_index_2: int, annihilation_qubit_index_1: int, annihilation_qubit_index_2: int) → None

Parameters:

creation_qubit_index_1 (int)
creation_qubit_index_2 (int)
annihilation_qubit_index_1 (int)
annihilation_qubit_index_2 (int)

Return type:

None

annihilation_qubit_index_1: int

annihilation_qubit_index_2: int

creation_qubit_index_1: int

creation_qubit_index_2: int

indices() → tuple[int, ...]

Get indices of the operator.

Return type:: tuple[int, …]

class ExcitationGatePoolProtocol

Bases: GatePool, Protocol

Protocol for gate pools that support fast excitation-based index generation.

This protocol extends GatePool with methods required by the combined Rust pipeline: fast index generation, batched iteration.

__init__(*args, **kwargs)

calculate_initial_gate_pool_ranking(top_k: int) → InitialGatePoolRanking | None

Build the initial ranking for the gate pool.

Returns None if the gate pool does not support initial ranking.

Parameters:: top_k (int) – The number of top gates to include in the initial cache.
Return type:: InitialGatePoolRanking | None

get_excitation_config() → ExcitationPoolConfiguration

Return the electron configuration parameters for the combined Rust pipeline.

Return type:: ExcitationPoolConfiguration

supports_fast_index_generation() → bool

Check if fast Rust-based index generation is supported for this gate pool.

Return type:: bool

class ExcitationPoolConfiguration

Bases: object

Configuration for excitation-based gate pools.

__init__(number_of_alpha_electrons: int, number_of_beta_electrons: int, number_of_spatial_orbitals: int, include_single: bool, include_double: bool, paired: bool) → None

Parameters:

number_of_alpha_electrons (int)
number_of_beta_electrons (int)
number_of_spatial_orbitals (int)
include_single (bool)
include_double (bool)
paired (bool)

Return type:

None

include_double: bool

include_single: bool

number_of_alpha_electrons: int

number_of_beta_electrons: int

number_of_spatial_orbitals: int

paired: bool

class GatePool

Bases: Protocol

Class to build and generate a gate pool.

__init__(*args, **kwargs)

calculate_initial_gate_pool_ranking(top_k: int) → InitialGatePoolRanking | None

Build the initial ranking for the gate pool.

Returns None if the gate pool does not support initial ranking.

Parameters:: top_k (int) – The number of top gates to include in the initial cache.
Return type:: InitialGatePoolRanking | None

supports_fast_index_generation() → bool

Check if fast Rust-based index generation is supported for this gate pool.

Return type:: bool

class GatePoolOperator

Bases: Protocol

Interface for a gate pool operator.

A gate pool operator contains a gate which can be added to a circuit and a generator for the gate which can be used for judging the usefulness of a given gate pool operator. The gate pool gate implementing an operator \(\hat{G}\) is related to the generator \(\hat{A}\) through:

\[\hat{G}(\phi) = e^{\phi \hat{A}}\]

__init__(*args, **kwargs)

get_gate(parameter: Parameter) → Gate

Get gate for the gate pool operator.

Parameters:: parameter (Parameter) – Parameter to be used in gate.
Return type:: Gate

get_generator() → SingleExcitationOperator | DoubleExcitationOperator | AntiHermitianPauliSum

Get generator for the gate pool operator.

Return type:: SingleExcitationOperator | DoubleExcitationOperator | AntiHermitianPauliSum

get_generator_indices() → tuple[int, ...]

Get the generator indices directly without creating an intermediate operator.

Returns:: Tuple of (creation_qubit_index, annihilation_qubit_index).
Return type:: tuple[int, …]

class InitialGatePoolRanking

Bases: object

Results from a gate pool ranking.

Parameters:

topk_operators – The top-k gate pool operators, sorted by some metric descending.
topk_metrics – The corresponding scaled metric values.
total_metric_sum – The total sum of all scaled metrics (not just top-k).

__init__(topk_operators: list[GatePoolOperator], topk_metrics: list[float], total_metric_sum: float) → None

Parameters:

topk_operators (list[GatePoolOperator])
topk_metrics (list[float])
total_metric_sum (float)

Return type:

None

topk_metrics: list[float]

topk_operators: list[GatePoolOperator]

total_metric_sum: float

class SingleExcitationGatePoolOperator

Bases: GatePoolOperator

Single excitation gate used in a gate pool.

The gate is a qrunch.core.circuit.composite_gates.SingleExcitationGate and the generator is a \(A = Q_p^\dagger Q_q - Q_q^\dagger Q_p\), where \(Q_i\) and \(Q_i^\dagger\) removes and adds one qubit excitation for the \(i\)’th site, respectively.

__init__(creation_qubit_index: int, annihilation_qubit_index: int) → None

Initiate an instance of the single excitation gate pool gate.

Parameters:

creation_qubit_index (int) – First qubit index for the gate.
annihilation_qubit_index (int) – Second qubit index for the gate.

Return type:

None

get_gate(parameter: Parameter) → SingleExcitationGate

Get gate for the gate pool operator.

Parameters:: parameter (Parameter) – Parameter to be used in gate.
Return type:: SingleExcitationGate

get_generator() → SingleExcitationOperator

Get generator for the gate pool operator.

Parameters:: parameter – Parameter to be used in gate.
Return type:: SingleExcitationOperator

get_generator_indices() → tuple[int, int]

Get the generator indices directly without creating an intermediate operator.

Returns:: Tuple of (creation_qubit_index, annihilation_qubit_index).
Return type:: tuple[int, int]

class SingleExcitationOperator

Bases: object

Represents a single excitation operator and hold the indices of the operation.

This operator is the generator of the SingleExcitationGate. All fields are immutable (frozen=True) so an instance can be safely reused.

Parameters:

creation_qubit_index – The index of the qubit where the excitation is created.
annihilation_qubit_index – The index of the qubit where the excitation is annihilated.

__init__(creation_qubit_index: int, annihilation_qubit_index: int) → None

Parameters:

creation_qubit_index (int)
annihilation_qubit_index (int)

Return type:

None

annihilation_qubit_index: int

creation_qubit_index: int

indices() → tuple[int, ...]

Get indices of the operator.

Return type:: tuple[int, …]