Measurement¶
This section covers the API reference for obtaining the expectation value of a (molecular) Hamiltonian, either from a state vector simulation, or from sample measurements.
Expectation value of Hamiltonian¶
- qibochem.measurement.result.expectation(circuit: Circuit, hamiltonian: SymbolicHamiltonian)¶
Expectation value using state vector simulations
- Parameters:
circuit (
qibo.models.Circuit
) – Quantum circuit ansatzhamiltonian (
qibo.hamiltonians.SymbolicHamiltonian
) – Molecular Hamiltonian
- Returns:
Expectation value of the Hamiltonian for the given circuit
- Return type:
- qibochem.measurement.result.expectation_from_samples(circuit: Circuit, hamiltonian: SymbolicHamiltonian, n_shots: int = 1000, grouping=None, n_shots_per_pauli_term: bool = True, shot_allocation=None) float ¶
Calculate expectation value of some Hamiltonian using sample measurements from running a Qibo quantum circuit
- Parameters:
circuit (
qibo.models.Circuit
) – Quantum circuit ansatzhamiltonian (
qibo.hamiltonians.SymbolicHamiltonian
) – Molecular Hamiltoniann_shots (int) – Number of times the circuit is run. Default:
1000
grouping (str) – Whether or not to group Hamiltonian terms together to reduce the measurement cost. Available options:
None
: (Default) No grouping of Hamiltonian terms, and"qwc"
: Terms that commute qubitwise are grouped togethern_shots_per_pauli_term (bool) – Whether or not
n_shots
is used for each Pauli term (or group of terms) in the Hamiltonian, or for all the (group of) terms in the Hamiltonian. Default:True
;n_shots
are used to get the expectation value for each term (group of terms) in the Hamiltonian.shot_allocation (list) – Iterable containing the number of shots to be allocated to each term (or group of terms) in the Hamiltonian respectively if the n_shots_per_pauli_term argument is
False
. Default:None
; shots are allocated based on the magnitudes of the coefficients of the Hamiltonian terms.
- Returns:
Hamiltonian expectation value for the given circuit using sample measurements
- Return type:
- qibochem.measurement.result.v_expectation(circuit, hamiltonian, n_shots, n_trial_shots, grouping=None, method='vmsa')¶
An alternative loss function for finding the expectation value of a Hamiltonian using shots. Shots are allocated according to the Variance-Minimized Shot Assignment (VMSA) or Variance-Preserved Shot Reduction (VPSR) approaches suggested in the reference paper (given below).
Essentially, a uniform number of trial shots are first used to find the sample variance for each term (group) in the Hamiltonian. For the VMSA method, the remaining shots are all allocated to minimise the total variance (calculated as the sum of the variances), while for the VPSR method, a sufficient number of shots are allocated to each term (group) to keep their variance - and by extension, the total variance - below a certain threshold. Unlike in the VMSA method, the VPSR method does not allocate all of the remaining shots.
- Parameters:
circuit (
qibo.models.Circuit
) – Circuit ansatz for running VQEhamiltonian (
qibo.hamiltonians.SymbolicHamiltonian
) – Hamiltonian of interestn_shots (int) – Total number of shots for finding the Hamiltonian expectation value
n_trial_shots (int) – Number of shots to use for finding the sample variance for each Hamiltonian term
grouping (str) – Whether or not to group Hamiltonian terms together. Available options:
None
: (Default) No grouping of Hamiltonian terms, and"qwc"
: Terms that commute qubitwise are grouped togethermethod (str) – Which variance-based method to use; must be either “vmsa” (default) or “vpsr”.
- Returns:
Hamiltonian expectation value obtained using a variance-based shot allocation scheme
- Return type:
- Reference:
1. L. Zhu, S. Liang, C. Yang, X. Li, Optimizing Shot Assignment in Variational Quantum Eigensolver Measurement, Journal of Chemical Theory and Computation, 2024, 20, 2390-2403 (link)
Measurement cost reduction¶
The following functions are used for reducing and optimising the measurement cost of obtaining the Hamiltonian expectation value using sample measurements instead of a state vector simulation.
- qibochem.measurement.optimization.measurement_basis_rotations(hamiltonian, grouping=None)¶
Split up and sort the Hamiltonian terms to get the basis rotation gates to be applied to a quantum circuit for the respective (group of) terms in the Hamiltonian
- Parameters:
hamiltonian (
qibo.hamiltonians.SymbolicHamiltonian
) – Hamiltonian of interestgrouping (str) – Whether or not to group Hamiltonian terms together, i.e. use the same set of measurements to get the expectation values of a group of terms simultaneously. Default value of
None
will not group any terms together, while"qwc"
will group qubitwise commuting terms together, and return the measurement gates associated with each group of terms
- Returns:
List of two-tuples; the first item in the tuple is a group of Pauli terms (
sympy.Expr
), and the second is a list of measurement gates (qibo.gates.M
) that can be used to get the expectation value for the corresponding expression.- Return type:
- qibochem.measurement.shot_allocation.allocate_shots(grouped_terms, n_shots, method=None, max_shots_per_term=None)¶
Allocate shots to each group of terms in the Hamiltonian for calculating the expectation value of the Hamiltonian.
- Parameters:
grouped_terms (list) – Output of measurement_basis_rotations; list of two-tuples with the first term a
sympy.Expr
and the second the list of corresponding measurement gates (not used here).n_shots (int) – Total number of shots to be allocated
method (str) – How to allocate the shots. The available options are:
"c"
/"coefficients"
:n_shots
is distributed based on the relative magnitudes of the term coefficients,"u"
/"uniform"
:n_shots
is distributed evenly amongst each term. Default value:"c"
.max_shots_per_term (int) – Upper limit for the number of shots allocated to an individual group of terms. If not given, will be defined as a fraction (largest coefficient over the sum of all coefficients in the Hamiltonian) of
n_shots
.
- Returns:
A list containing the number of shots to be used for each group of Pauli terms respectively.
- Return type:
Utility functions¶
- qibochem.measurement.result.sample_statistics(circuit, grouped_terms, n_shots=100)¶
An alternative to the expectation_from_samples function when both the expectation values and sample variances are of interest. Unlike expectation_from_samples, this function does not have the flexibility of allocating shots specifically to each term (group) in the Hamiltonian; a fixed number of shots will be allocated to each term (group) instead.
- Parameters:
circuit (
qibo.models.Circuit
) – Quantum circuit ansatzgrouped_terms (list) – List of two-tuples; the first item in the tuple is a group of Pauli terms (
sympy.Expr
), and the second is a list of measurement gates (qibo.gates.M
) that can be used to get the expectation value for the corresponding expressionn_shots (int) – Number of times the circuit is run for each Hamiltonian term (group). Default:
1000
- Returns:
A two-tuple of lists, corresponding to the sample means (expectation values) and variances for each Hamiltonian term (group) with respect to the given circuit.
- Return type: