qrunch.chemistry.ground_state_problem.calculators.tools.excitations.excitation_gate_pool_rankers

Generate a gate pool from particle-hole excitations for VQE.

Functions

build_initial_gate_pool_ranker_for_molecular_excitations(...)

Build the initial gate pool ranker for pair excitations based on the provided options.

build_initial_gate_pool_ranker_for_pair_excitations(...)

Build the initial gate pool ranker for pair excitations based on the provided options.

Classes

ElectronPairExcitationGatePoolRanker

Build the initial gate pool ranking directly from molecular integrals.

ExcitationGatePoolOptions

Options controlling InitialExcitationGatePoolRankers and excitation pool behaviour.

ExcitationGatePoolRankerProtocol

Protocol for computing the initial ranking of excitation gates in the gate pool.

MolecularElectronExcitationGatePoolRanker

Build the initial gate pool ranking directly from molecular integrals.
class ElectronPairExcitationGatePoolRanker

Bases: ExcitationGatePoolRankerProtocol

Build the initial gate pool ranking directly from molecular integrals.

This avoids constructing the full qubit Hamiltonian by evaluating Slater-Condon matrix elements in the integral basis.

__init__(single_excitations: Array) → None

Initialise the integral-based cache initiator.

Parameters:

single_excitations (Array) – One-body coefficients for single excitations.

Return type:

None

top_candidates(top_k: int, excitations: Excitations) → InitialGatePoolRanking

Compute the initial ranking of excitation gates in the gate pool.

Parameters:

  • top_k (int) – The maximum number of top candidates to consider for initial ranking.

  • excitations (Excitations) – The excitations defining the gate pool for which to compute the initial ranking.

Return type:

InitialGatePoolRanking

class ExcitationGatePoolOptions

Bases: DataclassPublicAPI

Options controlling InitialExcitationGatePoolRankers and excitation pool behaviour.

All fields are immutable (frozen=True) so an instance can be safely reused.

Parameters:

  • initial_gate_pool_ranking_method – The method to compute the initial gate pool ranking. If off, skip computing the initial ranking and start with an empty cache.

  • initial_gate_pool_ranking_use_first_order_single_metrics – If True, use the first-order BCH expansion metric for single excitations in the initial gate pool ranking.

  • initial_gate_pool_ranking_use_second_order_single_metrics – If True, use the second-order BCH expansion metric for single excitations in the initial gate pool ranking.

  • initial_gate_pool_ranking_single_ratio – Fraction of candidates reserved for single excitations in the initial gate pool ranking (must be in [0, 1]).

__init__(*, initial_gate_pool_ranking_method: Literal['heuristic_gradient', 'off'] = 'heuristic_gradient', initial_gate_pool_ranking_use_first_order_single_metrics: bool = False, initial_gate_pool_ranking_use_second_order_single_metrics: bool = True, initial_gate_pool_ranking_single_ratio: float = 0.1) → None
Parameters:

  • initial_gate_pool_ranking_method (Literal['heuristic_gradient', 'off'])

  • initial_gate_pool_ranking_use_first_order_single_metrics (bool)

  • initial_gate_pool_ranking_use_second_order_single_metrics (bool)

  • initial_gate_pool_ranking_single_ratio (float)

Return type:

None

initial_gate_pool_ranking_method: Literal['heuristic_gradient', 'off'] = 'heuristic_gradient'
initial_gate_pool_ranking_single_ratio: float = 0.1
initial_gate_pool_ranking_use_first_order_single_metrics: bool = False
initial_gate_pool_ranking_use_second_order_single_metrics: bool = True
class ExcitationGatePoolRankerProtocol

Bases: Protocol

Protocol for computing the initial ranking of excitation gates in the gate pool.

__init__(*args, **kwargs)
top_candidates(top_k: int, excitations: Excitations) → InitialGatePoolRanking

Compute the initial ranking of excitation gates in the gate pool.

Parameters:

  • top_k (int) – The maximum number of top candidates to consider for initial ranking.

  • excitations (Excitations) – The excitations defining the gate pool for which to compute the initial ranking.

Returns:

An InitialGatePoolRanking containing the top candidates and their metrics.

Return type:

InitialGatePoolRanking

class MolecularElectronExcitationGatePoolRanker

Bases: ExcitationGatePoolRankerProtocol

Build the initial gate pool ranking directly from molecular integrals.

This avoids constructing the full qubit Hamiltonian by evaluating Slater-Condon matrix elements in the integral basis.

__init__(electronic_structure_integrals: RestrictedElectronicStructureIntegrals | UnrestrictedElectronicStructureIntegrals, *, use_first_order_single_metrics: bool = False, use_second_order_single_metrics: bool = True, single_ratio: float = 0.1) → None

Initialise the integral-based cache initiator.

Parameters:

  • electronic_structure_integrals (RestrictedElectronicStructureIntegrals | UnrestrictedElectronicStructureIntegrals) – One- and two-body integrals.

  • use_first_order_single_metrics (bool) – If True, use the first-order BCH metric for singles.

  • use_second_order_single_metrics (bool) – If True, use the second-order BCH metric for singles.

  • single_ratio (float) – Fraction of candidates slots reserved for single excitations.

Return type:

None

top_candidates(top_k: int, excitations: Excitations) → InitialGatePoolRanking

Compute the initial ranking of excitation gates in the gate pool.

Parameters:

  • top_k (int) – The maximum number of top candidates to consider for initial ranking.

  • excitations (Excitations) – The excitations defining the gate pool for which to compute the initial ranking.

Return type:

InitialGatePoolRanking

build_initial_gate_pool_ranker_for_molecular_excitations(excitation_gate_pool_options: ExcitationGatePoolOptions, electronic_structure_integrals: RestrictedElectronicStructureIntegrals | UnrestrictedElectronicStructureIntegrals) → ExcitationGatePoolRankerProtocol | None

Build the initial gate pool ranker for pair excitations based on the provided options.

Parameters:

  • excitation_gate_pool_options (ExcitationGatePoolOptions)

  • electronic_structure_integrals (RestrictedElectronicStructureIntegrals | UnrestrictedElectronicStructureIntegrals)

Return type:

ExcitationGatePoolRankerProtocol | None

build_initial_gate_pool_ranker_for_pair_excitations(excitation_gate_pool_options: ExcitationGatePoolOptions, single_excitations: Array) → ExcitationGatePoolRankerProtocol | None

Build the initial gate pool ranker for pair excitations based on the provided options.

Parameters:
Return type:

ExcitationGatePoolRankerProtocol | None