qrunch.quantum.algorithms.pauli.vqes.fast_gate_selector

Implementation of FAST-VQE (https://doi.org/10.1103/PhysRevA.108.052422).

The core logic that defines the FAST-specific behavior is defined in the FastGateSelector, and the class for running the FAST-VQE algorithm is just a class that calls the AdaptiveVqe class with the FastGateSelector and some standard options.

Module Attributes

DEFAULT_OPTIONS

Default options for the FAST GateSelector.

Functions

is_excitation_pool(gate_pool)

Check if gate pool contains only excitation operators.

Classes

`ExcludedGates`	Holds the gates which are excluded from the gate pool.
`FastGateSelector`	Implementation of the GateSelector for FAST-VQE.
`FastGateSelectorCreator`	Builder for FAST gate selector.
`FastGateSelectorOptions`	Options for the FAST gate selector.
`FastImportanceMetric`	Protocol for the FAST importance metric.
`FullHeuristicGradient`	Full Heuristic Gradient FAST importance metric.
`HeuristicGradient`	Heuristic Gradient FAST importance metric.
`HeuristicSelectedCi`	Heuristic Selected CI FAST importance metric.
`MetricThresholdExcludedGates`	Excludes gates based on a threshold for the metric.
`TouchedExcludedGates`	Excludes gates based on how many times a gate operators indices has been touched by other operators.

DEFAULT_OPTIONS = FastGateSelectorOptions(reset_excluded_gates_threshold=1e-10, measurement_state_probability_threshold=0.1, number_of_gates_to_recalculate=1000, period_for_full_recalculation=10, metric_batch_size=1000000, single_scaling_factor=1.0): Default options for the FAST GateSelector.

class ExcludedGates

Bases: Protocol

Holds the gates which are excluded from the gate pool.

__init__(*args, **kwargs)

reset() → None

Reset the excluded gates.

Return type:: None

update(gate_metrics: _GateMetrics, number_of_gates_to_exclude: int) → None

Update the excluded gates according to the implemented rule.

Parameters:

gate_metrics (_GateMetrics) – Gate metrics for all gate operators still in the gate pool.
number_of_gates_to_exclude (int) – Number of gates to exclude.

Return type:

None

class FastGateSelector

Bases: GateSelector

Implementation of the GateSelector for FAST-VQE.

This gate selector uses the gate parameter gradient as the importance metric and does not perform any modifications on the gate pool.

Using this in the AdaptiveVQE results in an implementation of the FAST-VQE algorithm.

__init__(shots: int | None, sampler: Sampler, importance_metric: FastImportanceMetric, options: FastGateSelectorOptions = FastGateSelectorOptions(reset_excluded_gates_threshold=1e-10, measurement_state_probability_threshold=0.1, number_of_gates_to_recalculate=1000, period_for_full_recalculation=10, metric_batch_size=1000000, single_scaling_factor=1.0), excluded_gates: ExcludedGates | None = None) → None

Initialize the FAST GateSelector.

Parameters:

shots (int | None) – Number of shots to use.
sampler (Sampler) – Sampler to use in sampling quantum measurements.
importance_metric (FastImportanceMetric) – The importance metric to use when evaluating gates.
options (FastGateSelectorOptions) – Options for the FAST Vqe.
excluded_gates (ExcludedGates | None) – Rules to use for exclusion of gates.

Return type:

None

exclude_gates(gates: list[GatePoolOperator]) → None

Exclude the given gates.

Parameters:: gates (list[GatePoolOperator])
Return type:: None

register_gate_pool(gate_pool: GatePool) → None

Register the gate pool.

Parameters:: gate_pool (GatePool) – the gate pool to register in the GateSelector. The GateSelector can only choose gates from this.
Return type:: None

select_gates(observable: HermitianPauliSum, circuit: Circuit, *, number_of_gates: int = 1) → list[GatePoolOperator]

Select the best gates from the gate pool for minimizing the expectation value of the observable.

Parameters:

observable (HermitianPauliSum) – The observable whose expectation value should be minimized.
circuit (Circuit) – The circuit to extend with a gate form the gate pool.
number_of_gates (int) – Number of gates to select.

Return type:

list[GatePoolOperator]

class FastGateSelectorCreator

Bases: object

Builder for FAST gate selector.

__init__() → None

Initialize builder for the Fast gate selector.

Return type:: None

create() → FastGateSelector

Create an instance of FastGateSelector.

Return type:: FastGateSelector

with_full_heuristic_gradient() → Self

Use full heuristic gradient for the importance metric.

The full heuristic gradient is the heuristic gradient defined in the FAST article (https://doi.org/10.1103/PhysRevA.108.052422), eq. (11). This importance metric corresponds to dropping all off diagonal terms in the double summation from the gradient used in the ADAPT-VQE algorithm, dropping all front-factors and reintroducing the second sum to include off-diagonal terms.

States with a probability less than \(threshold * mean(P_i)\) are excluded, where \(mean(P_i)\) is the mean probability of the measured states.

Return type:: Self

with_heuristic_gradient() → Self

Use heuristic gradient for the importance metric.

The heuristic gradient is a simplified version of the heuristic gradient defined in the FAST article (https://doi.org/10.1103/PhysRevA.108.052422), which corresponds to eq. (10). This importance metric corresponds to dropping all off diagonal terms in the double summation from the gradient used in the ADAPT-VQE algorithm.

States with a probability less than \(threshold * mean(P_i)\) are excluded, where \(mean(P_i)\) is the mean probability of the measured states.

Return type:: Self

with_heuristic_selected_ci(estimator: Estimator | None = None) → Self

Use heuristic selected CI for the importance metric.

The heuristic selected CI is defined in the FAST article (https://doi.org/10.1103/PhysRevA.108.052422), eq. (12). This importance metric is a heuristic version of a selected CI method.

States with a probability less than \(threshold * mean(P_i)\) are excluded, where \(mean(P_i)\) is the mean probability of the measured states.

Parameters:: estimator (Estimator | None) – Estimator to use, if None it uses same estimator as the adaptive VQE.
Return type:: Self

with_options(options: FastGateSelectorOptions) → Self

Set the options for the FAST gate selector.

Parameters:: options (FastGateSelectorOptions) – The options to use.
Return type:: Self

with_sampler(sampler: Sampler) → Self

Set the sampler to use for the FAST gate selector.

Parameters:: sampler (Sampler) – The sampler to use. Can be created using the sampler_creator().
Return type:: Self

with_shots(shots: int | None) → Self

Set the number of shots to use in the FAST gate selector.

Parameters:: shots (int | None) – Number of shots to use. If None, use exact sampling (requires an exact estimator like the excitation gate estimator).
Return type:: Self

with_threshold_exclusion_rule(threshold: float = 1e-10) → Self

Use a threshold to determine when gate operators are removed from exclusion.

Parameters:: threshold (float) – Threshold to compare the FAST metric to.
Return type:: Self

with_touched_exclusion_rule() → Self

Use as an exclusion rule how many times the qubits hit by a gate operator has been hit by others afterwards.

Return type:: Self

class FastGateSelectorOptions

Bases: DataclassPublicAPI

Options for the FAST gate selector.

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

Parameters:

reset_excluded_gates_threshold – Threshold for resetting the gate pool. (default=1.0e-10)
measurement_state_probability_threshold – Threshold used to exclude measured states with small probability from the calculation. States with a probability less than \(threshold * mean(P_i)\) are excluded, where \(mean(P_i)\) is the mean probability of the measured states. (default=0.1)
number_of_gates_to_recalculate – Number of gates to recalculate the metric for at every call. (default=1000)
period_for_full_recalculation – Period for full recalculation of the gate pool. (default=10)
metric_batch_size – Batch size for calculating the metric. (default=1_000_000)
single_scaling_factor – Factor used to scale importance metric for single excitations. (default=1.0)

__init__(*, reset_excluded_gates_threshold: float = 1e-10, measurement_state_probability_threshold: float = 0.1, number_of_gates_to_recalculate: int = 1000, period_for_full_recalculation: int = 10, metric_batch_size: int = 1000000, single_scaling_factor: float = 1.0) → None

Parameters:

reset_excluded_gates_threshold (float)
measurement_state_probability_threshold (float)
number_of_gates_to_recalculate (int)
period_for_full_recalculation (int)
metric_batch_size (int)
single_scaling_factor (float)

Return type:

None

measurement_state_probability_threshold: float = 0.1

metric_batch_size: int = 1000000

number_of_gates_to_recalculate: int = 1000

period_for_full_recalculation: int = 10

reset_excluded_gates_threshold: float = 1e-10

single_scaling_factor: float = 1.0

class FastImportanceMetric

Bases: Protocol

Protocol for the FAST importance metric.

__init__(*args, **kwargs)

classmethod calculate(observable: HermitianPauliSum, measurements: QuantumMeasurement, gate_pool_as_generator_indices: list[tuple[int, ...]], number_of_qubits: int, expectation_value: float) → list[float]

Calculate the importance metric of the gate from the gate generator.

The assumption here is that the gate pool operators are single-excitation double-excitation types

States with a probability less than \(threshold * mean(P_i)\) are excluded, where \(mean(P_i)\) is the mean probability of the measured states.

Parameters:

observable (HermitianPauliSum) – The observable whose expectation value is minimized.
measurements (QuantumMeasurement) – The measurements.
gate_pool_as_generator_indices (list[tuple[int, ...]]) – The gate pool operators as generator indices.
number_of_qubits (int) – The number of qubits.
expectation_value (float) – The current expectation value.

Return type:

list[float]

classmethod calculate_custom(observable: HermitianPauliSum, measurements: QuantumMeasurement, gate_pool_as_generator_dict_list: list[dict[tuple[int, int, int], complex]], number_of_qubits: int, expectation_value: float) → list[float]

Calculate the importance metric of the gate from the gate generator.

The assumption here is that the gate pool operators are custom gate pool types

States with a probability less than \(threshold * mean(P_i)\) are excluded, where \(mean(P_i)\) is the mean probability of the measured states.

Parameters:

observable (HermitianPauliSum) – The observable whose expectation value is minimized.
measurements (QuantumMeasurement) – The measurements.
gate_pool_as_generator_dict_list (list[dict[tuple[int, int, int], complex]]) – The gate pool operators as generator indices.
number_of_qubits (int) – The number of qubits.
expectation_value (float) – The current expectation value.

Return type:

list[float]

estimator() → Estimator | None

Return Estimator if the metric require the expectation value as input.

Return type:: Estimator | None

classmethod require_expectation_value() → bool

Return True, if the metric require the expectation value as input.

Return type:: bool

class FullHeuristicGradient

Bases: FastImportanceMetric

Full Heuristic Gradient FAST importance metric.

__init__(*args, **kwargs)

classmethod calculate(observable: HermitianPauliSum, measurements: QuantumMeasurement, gate_pool_as_generator_indices: list[tuple[int, ...]], number_of_qubits: int, expectation_value: float) → list[float]

Calculate the full heuristic gradient importance metric using rust functions.

The assumption here is that the gate pool operators are single-excitation double-excitation types

The full heuristic gradient is defined in the FAST article (https://doi.org/10.1103/PhysRevA.108.052422), eq. (11). This importance metric roughly corresponds to dropping the phases and pre-factors, and squaring the amplitudes, from the gradient used in the ADAPT-VQE algorithm.

States with a probability less than \(threshold * mean(P_i)\) are excluded, where \(mean(P_i)\) is the mean probability of the measured states.

Parameters:

observable (HermitianPauliSum) – The observable whose expectation value is minimized.
measurements (QuantumMeasurement) – The measurements.
gate_pool_as_generator_indices (list[tuple[int, ...]]) – The gate pool operators as generator indices.
number_of_qubits (int) – The number of qubits.
expectation_value (float) – The current expectation value.

Return type:

list[float]

classmethod calculate_custom(observable: HermitianPauliSum, measurements: QuantumMeasurement, gate_pool_as_generator_dict_list: list[dict[tuple[int, int, int], complex]], number_of_qubits: int, expectation_value: float) → list[float]

Calculate the full heuristic gradient importance metric using rust functions.

The assumption here is that the gate pool operators are custom gate pool types

The full heuristic gradient is defined in the FAST article (https://doi.org/10.1103/PhysRevA.108.052422), eq. (11). This importance metric roughly corresponds to dropping the phases and pre-factors, and squaring the amplitudes, from the gradient used in the ADAPT-VQE algorithm.

States with a probability less than \(threshold * mean(P_i)\) are excluded, where \(mean(P_i)\) is the mean probability of the measured states.

Parameters:

observable (HermitianPauliSum) – The observable whose expectation value is minimized.
measurements (QuantumMeasurement) – The measurements.
gate_pool_as_generator_dict_list (list[dict[tuple[int, int, int], complex]]) – The gate pool operators as generator indices.
number_of_qubits (int) – The number of qubits.
expectation_value (float) – The current expectation value.

Return type:

list[float]

estimator() → None

Return Estimator if the metric require the expectation value as input.

Return type:: None

classmethod require_expectation_value() → bool

Return True, if the metric require the expectation value as input.

Return type:: bool

class HeuristicGradient

Bases: FastImportanceMetric

Heuristic Gradient FAST importance metric.

__init__(*args, **kwargs)

classmethod calculate(observable: HermitianPauliSum, measurements: QuantumMeasurement, gate_pool_as_generator_indices: list[tuple[int, ...]], number_of_qubits: int, expectation_value: float) → list[float]

Calculate the heuristic gradient importance metric.

The assumption here is that the gate pool operators are single-excitation double-excitation types

The heuristic gradient is a simplified version of the heuristic gradient defined in the FAST article (https://doi.org/10.1103/PhysRevA.108.052422), which corresponds to eq. (10). This importance metric corresponds to dropping all off diagonal terms in the double summation from the gradient used in the ADAPT-VQE algorithm.

States with a probability less than \(threshold * mean(P_i)\) are excluded, where \(mean(P_i)\) is the mean probability of the measured states.

Parameters:

observable (HermitianPauliSum) – The observable whose expectation value is minimized.
measurements (QuantumMeasurement) – The measurements.
gate_pool_as_generator_indices (list[tuple[int, ...]]) – The gate pool operators as generator indices.
number_of_qubits (int) – The number of qubits.
expectation_value (float) – The current expectation value. Not used

Return type:

list[float]

classmethod calculate_custom(observable: HermitianPauliSum, measurements: QuantumMeasurement, gate_pool_as_generator_dict_list: list[dict[tuple[int, int, int], complex]], number_of_qubits: int, expectation_value: float) → list[float]

Calculate the heuristic gradient importance metric using rust functions.

The heuristic gradient is a simplified version of the heuristic gradient defined in the FAST article (https://doi.org/10.1103/PhysRevA.108.052422), which corresponds to eq. (10). This importance metric corresponds to dropping all off diagonal terms in the double summation from the gradient used in the ADAPT-VQE algorithm.

States with a probability less than \(threshold * mean(P_i)\) are excluded, where \(mean(P_i)\) is the mean probability of the measured states.

Parameters:

observable (HermitianPauliSum) – The observable whose expectation value is minimized.
measurements (QuantumMeasurement) – The measurements.
gate_pool_as_generator_dict_list (list[dict[tuple[int, int, int], complex]]) – The gate pool operators as generator indices.
number_of_qubits (int) – The number of qubits.
expectation_value (float) – The current expectation value.

Return type:

list[float]

estimator() → None

Return Estimator if the metric require the expectation value as input.

Return type:: None

classmethod require_expectation_value() → bool

Return True, if the metric require the expectation value as input.

Return type:: bool

class HeuristicSelectedCi

Bases: FastImportanceMetric

Heuristic Selected CI FAST importance metric.

__init__(estimator: Estimator) → None

Initialize Heuristic Selected CI importance metric.

Parameters:: estimator (Estimator) – The estimator for calculating expectation value.
Return type:: None

classmethod calculate(observable: HermitianPauliSum, measurements: QuantumMeasurement, gate_pool_as_generator_indices: list[tuple[int, ...]], number_of_qubits: int, expectation_value: float) → list[float]

Calculate the heuristic selected CI (Configuration Interaction).

The assumption here is that the gate pool operators are single-excitation double-excitation types

The heuristic selected CI is defined in the FAST article (https://doi.org/10.1103/PhysRevA.108.052422), eq. (12). This importance metric is a heuristic version of a selected CI method.

States with a probability less than \(threshold * mean(P_i)\) are excluded, where \(mean(P_i)\) is the mean probability of the measured states.

Parameters:

observable (HermitianPauliSum) – The observable whose expectation value is minimized.
measurements (QuantumMeasurement) – The measurements.
gate_pool_as_generator_indices (list[tuple[int, ...]]) – The gate pool operators as generator indices.
number_of_qubits (int) – The number of qubits.
expectation_value (float) – The current expectation value.

Return type:

list[float]

classmethod calculate_custom(observable: HermitianPauliSum, measurements: QuantumMeasurement, gate_pool_as_generator_dict_list: list[dict[tuple[int, int, int], complex]], number_of_qubits: int, expectation_value: float) → list[float]

Calculate the heuristic selected CI (Configuration Interaction).

The assumption here is that the gate pool operators are custom gate pool types

The heuristic selected CI is defined in the FAST article (https://doi.org/10.1103/PhysRevA.108.052422), eq. (12). This importance metric is a heuristic version of a selected CI method.

States with a probability less than \(threshold * mean(P_i)\) are excluded, where \(mean(P_i)\) is the mean probability of the measured states.

Parameters:

observable (HermitianPauliSum) – The observable whose expectation value is minimized.
measurements (QuantumMeasurement) – The measurements.
gate_pool_as_generator_dict_list (list[dict[tuple[int, int, int], complex]]) – The gate pool operators as generator indices.
number_of_qubits (int) – The number of qubits.
expectation_value (float) – The current expectation value.

Return type:

list[float]

estimator() → Estimator

Return Estimator if the metric require the expectation value as input.

Return type:: Estimator

classmethod require_expectation_value() → bool

Return True, if the metric require the expectation value as input.

Return type:: bool

class MetricThresholdExcludedGates

Bases: ExcludedGates

Excludes gates based on a threshold for the metric.

__init__(threshold: float = 1e-10) → None

Initialize a touched excluded gate list.

Parameters:: threshold (float)
Return type:: None

excluded_gates: list[GatePoolOperator]

reset() → None

Reset the excluded gates.

Return type:: None

update(gate_metrics: _GateMetrics, number_of_gates_to_exclude: int) → None

Update the excluded gates according to the implemented rule.

Parameters:

gate_metrics (_GateMetrics) – Gate metrics for all gate operators still in the gate pool.
number_of_gates_to_exclude (int) – Number of gates to exclude.

Return type:

None

class TouchedExcludedGates

Bases: ExcludedGates

Excludes gates based on how many times a gate operators indices has been touched by other operators.

__init__() → None

Initialize a touched excluded gate list.

Return type:: None

affected_factor: float: Factor describing how difficult it is for an index to be affected.

excluded_gates: list[_TouchedExcludedGate]

number_of_indices_to_be_affected_doubles: int

number_of_indices_to_be_affected_pauli: int

number_of_indices_to_be_affected_singles: int

reset() → None

Reset the excluded gates.

Return type:: None

update(gate_metrics: _GateMetrics, number_of_gates_to_exclude: int) → None

Update the excluded gates according to the implemented rule.

Parameters:

gate_metrics (_GateMetrics) – Gate metrics for all gate operators still in the gate pool.
number_of_gates_to_exclude (int) – Number of gates to exclude.

Return type:

None

is_excitation_pool(gate_pool: GatePool) → bool

Check if gate pool contains only excitation operators.

Parameters:: gate_pool (GatePool)
Return type:: bool