quri_parts.core.estimator package#

class Estimate(*args, **kwargs)#

Bases: Protocol[EstimateValue]

Estimate is an interface for classes representing an estimate for a certain quantity.

This interface only contains read-only properties, so an implementation can be a (frozen) dataclass or a namedtuple.

abstract property value: EstimateValue#

The estimate (estimated value) itself.

abstract property error: float#

Represents the “error” of the estimate.

The precise meaning of the “error” depends on what type the estimate is. If the estimate is a sample mean calculated by sampling from some sample distribution, the error is the standard error calculated from the samples. If the estimate is an exact value calculated without sampling, the error is zero.

class Estimates(*args, **kwargs)#

Bases: Protocol[EstimateValue]

Estimates is an interface for classes representing estimates for a certain quantity.

This interface only contains read-only properties, so an implementation can be a (frozen) dataclass or a namedtuple.

abstract property values: Sequence[EstimateValue]#

The estimates (estimated values) themselves.

abstract property error_matrix: Sequence[Sequence[float]] | None#

Represents the “error” of estimate values.

The precise meaning of the “error” depends on what type the estimate is. Basically, if we can get N estimate values, this will return N x N covariance matrix.

class MatrixEstimates(*args, **kwargs)#

Bases: Protocol[EstimateValue]

MatrixEstimates is an interface for classes representing an N x N matrix estimate for a certain quantity.

This interface only contains read-only properties, so an implementation can be a (frozen) dataclass or a namedtuple.

abstract property values: Sequence[Sequence[EstimateValue]]#

The estimates (estimated values) themselves.

abstract property error_tensor: Sequence[Sequence[Sequence[Sequence[float]]]] | None#

Represents the “error” of estimate values.

The precise meaning of the “error” depends on what type the estimate is. Basically, if we can get N x N estimate values, this will return N x N x N x N error tensor.

Estimatable#

(Concurrent)QuantumEstimator accepts a single PauliLabel as well as an Operator. Here we call them an “Estimatable”.

alias of Union[Operator, PauliLabel]

QuantumEstimator#

QuantumEstimator represents a function that estimates an expectation value of a given Operator for a given non-parametric state. It theoretically corresponds to a value given by sandwiching the operator between a bra and a ket of the state. This is a generic type and you need to specify what kind of state classes it is applicable to.

alias of Callable[[Union[Operator, PauliLabel], _StateT], Estimate[complex]]

ConcurrentQuantumEstimator#

ConcurrentQuantumEstimator represents a function that estimates expectation values of given Operators for given non-parametric states. It basically works in the same way as QuantumEstimator, except that it performs estimation for multiple operators and states concurrently. Numbers of operators and states (i.e. lengths of the first and second arguments) should satisfy one of the followings:

  • Only one operator is specified.

  • Only one state is specified.

  • The number of the operators is the same as the number of the states. In this case, an operator and a state with the same index are used to estimate one expectation value.

This is a generic type and you need to specify what kind of state classes it is applicable to.

alias of Callable[[Sequence[Union[Operator, PauliLabel]], Sequence[_StateT]], Iterable[Estimate[complex]]]

ParametricQuantumEstimator#

ParametricQuantumEstimator represents a function that estimates an expectation value of a given Operator for a given parametric state with given parameter values (the third argument). This is a generic type and you need to specify what kind of state classes it is applicable to.

alias of Callable[[Union[Operator, PauliLabel], _ParametricStateT, Sequence[float]], Estimate[complex]]

ConcurrentParametricQuantumEstimator#

This is a generic type and you need to specify what kind of state classes it is applicable to.

alias of Callable[[Union[Operator, PauliLabel], _ParametricStateT, Sequence[Sequence[float]]], Iterable[Estimate[complex]]]

create_parametric_estimator(estimator: QuantumEstimator[CircuitQuantumState | QuantumStateVector]) ParametricQuantumEstimator[ParametricCircuitQuantumState | ParametricQuantumStateVector]#
create_parametric_estimator(estimator: QuantumEstimator[CircuitQuantumState]) ParametricQuantumEstimator[ParametricCircuitQuantumState]
create_parametric_estimator(estimator: QuantumEstimator[QuantumStateVector]) ParametricQuantumEstimator[ParametricQuantumStateVector]

Creates parametric estimator from estimator.

create_concurrent_parametric_estimator(parametric_estimator)#

Creates concurrent parametric estimator from parametric estimator.

Parameters:

parametric_estimator (ParametricQuantumEstimator[_ParametricStateT]) –

Return type:

ConcurrentParametricQuantumEstimator[_ParametricStateT]

GradientEstimator#

GradientEstimator represents a function that estimates gradient values of an expectation value of a given Operator for a given parametric state with given parameter values (the third argument). This is a generic type and you need to specify what kind of state classes it is applicable to.

alias of Callable[[Union[Operator, PauliLabel], _ParametricStateT, Sequence[float]], Estimates[complex]]

HessianEstimator#

HessianEstimator represents a function that estimates hessian values of an expectation value of a given Operator for a given parametric state with given parameter values (the third argument). This is a generic type and you need to specify what kind of state classes it is applicable to.

alias of Callable[[Union[Operator, PauliLabel], _ParametricStateT, Sequence[float]], MatrixEstimates[complex]]

OverlapEstimator#

OverlapEstimator represents a function that estimates the magnitude squared overlap of two non-parametric quantum states. This should be used when the magnitude of the inner product between two quantum states is needed. It should be symmetric in the input arguments. This is a generic type and you need to specify what kind of state classes it is applicable to.

alias of Callable[[_StateT, _StateT], Estimate[float]]

OverlapWeightedSumEstimator#

OverlapWeightedSumEstimator represents a function that estimates the magnitude squared overlaps of two sets of states and produces a weighted sum. It must be passed three :class:`~Sequence`s with the same length. This can be used to evaluate overlap based penalty terms in a Hamiltonian as is done with e.g. VQD. The output should be invariant under permutation of the first and second input arguments. This is a generic type and you need to specify what kind of state classes it is applicable to.

alias of Callable[[Sequence[_StateT], Sequence[_StateT], Sequence[complex]], Estimate[complex]]

ParametricOverlapWeightedSumEstimator#

ParametricOverlapWeightedSumEstimator represents a function that estimates the magnitude squared overlap of a set of parametric states and returns their weighted sum. This is intended for use in variational algorithms where a parametrized overlap penalty term is needed. The output should be invariant under permutation of the first and second input arguments. This is a generic type and you need to specify what kind of state classes it is applicable to.

alias of Callable[[tuple[_ParametricStateT, Sequence[Sequence[float]]], tuple[_ParametricStateT, Sequence[Sequence[float]]], Sequence[complex]], Estimate[complex]]

create_parametric_overlap_weighted_sum_estimator(estimator: OverlapWeightedSumEstimator[CircuitQuantumState | QuantumStateVector]) ParametricOverlapWeightedSumEstimator[ParametricCircuitQuantumState | ParametricQuantumStateVector]#
create_parametric_overlap_weighted_sum_estimator(estimator: OverlapWeightedSumEstimator[QuantumStateVector]) ParametricOverlapWeightedSumEstimator[ParametricQuantumStateVector]
create_parametric_overlap_weighted_sum_estimator(estimator: OverlapWeightedSumEstimator[CircuitQuantumState]) ParametricOverlapWeightedSumEstimator[ParametricCircuitQuantumState]
create_concurrent_parametric_estimator_from_concurrent_estimator(concurrent_estimator: ConcurrentQuantumEstimator[_StateT]) ConcurrentParametricQuantumEstimator[_ParametricStateT]#
create_concurrent_parametric_estimator_from_concurrent_estimator(concurrent_estimator: ConcurrentQuantumEstimator[CircuitQuantumState]) ConcurrentParametricQuantumEstimator[ParametricCircuitQuantumState]
create_concurrent_parametric_estimator_from_concurrent_estimator(concurrent_estimator: ConcurrentQuantumEstimator[QuantumStateVector]) ConcurrentParametricQuantumEstimator[ParametricQuantumStateVector]

Creates a concurrent parametric estimator from a concurrent estimator.

create_parametric_estimator_from_concurrent_estimator(concurrent_estimator: ConcurrentQuantumEstimator[_StateT]) ParametricQuantumEstimator[_ParametricStateT]#
create_parametric_estimator_from_concurrent_estimator(concurrent_estimator: ConcurrentQuantumEstimator[CircuitQuantumState]) ParametricQuantumEstimator[ParametricCircuitQuantumState]
create_parametric_estimator_from_concurrent_estimator(concurrent_estimator: ConcurrentQuantumEstimator[QuantumStateVector]) ParametricQuantumEstimator[ParametricQuantumStateVector]

Creates a parametric estimator from a concurrent estimator.

create_estimator_from_concurrent_estimator(concurrent_estimator)#

Creates an estimator from a concurrent estimator.

Parameters:

concurrent_estimator (ConcurrentQuantumEstimator[_StateT]) –

Return type:

QuantumEstimator[_StateT]

create_concurrent_estimator_from_estimator(estimator)#

Creates a concurrent estimator from an estimator.

Parameters:

estimator (QuantumEstimator[_StateT]) –

Return type:

ConcurrentQuantumEstimator[_StateT]

class GeneralQuantumEstimator(estimator, concurrent_estimator, parametric_estimator, concurrent_parametric_estimator)#

Bases: Generic[QuantumStateT, ParametricQuantumStateT]

A callable dataclass that holds QuantumEstimator, ConcurrentQuantumEstimator, ParametricQuantumEstimator, or ConcurrentParametricEstimator. When it is used as a callable function, it allows generic inputs for expectation value estimation. The allowed inputs for using it as a callable function are:

  • Act as QuantumEstimator:
    • Estimatable, QuantumStateT -> Estimate

  • Act as ConcurrentQuantumEstimator:
    • Estimatable, [QuantumStateT, …] -> [Estimate, …]

    • [Estimatable], [QuantumStateT, …] -> [Estimate, …]

    • [Estimatable, …], QuantumStateT -> [Estimate, …]

    • [Estimatable, …], [QuantumStateT] -> [Estimate, …]

    • [Estimatable, …], [QuantumStateT, …] -> [Estimate, …]

  • Act as ParametricQuantumEstimator:
    • Estimatable, ParametricQuantumStateT, [float, …] -> Estimate

  • Act as ConcurrentParametricQuantumEstimator:
    • Estimatable, ParametricQuantumStateT, [[float, …], …] -> [Estimate, …]

When a GeneralEstimator is called directly with one of the combinations above, it needs to parse the input arguments to figure out which of QuantumEstimator, ConcurrentQuantumEstimator, ParametricQuantumEstimator, or ConcurrentParametricEstimator is required to perform the estimation. To avoid such performance penalty, you may retrieve the desired estimator as a property directly.

Parameters:
estimator: QuantumEstimator[QuantumStateT]#
concurrent_estimator: ConcurrentQuantumEstimator[QuantumStateT]#
parametric_estimator: ParametricQuantumEstimator[ParametricQuantumStateT]#
concurrent_parametric_estimator: ConcurrentParametricQuantumEstimator[ParametricQuantumStateT]#
create_general_estimator_from_estimator(estimator: QuantumEstimator[CircuitQuantumState]) GeneralQuantumEstimator[CircuitQuantumState, ParametricCircuitQuantumState]#
create_general_estimator_from_estimator(estimator: QuantumEstimator[QuantumStateVector]) GeneralQuantumEstimator[QuantumStateVector, ParametricQuantumStateVector]

Creates a GeneralEstimator from a QuantumEstimator.

Note: - The concurrencies of the ConcurrentQuantumEstimaror and

ConcurrentParametricQuantumEstimaror will be set to 1 when a GeneralEstimator is created with this function.

  • When circuit conversion is involved in the estimator execution, the

    parametric estimator created from this function will bind the parameter first, and then convert the bound circuit every time the patametric estimator is called.

create_general_estimator_from_concurrent_estimator(concurrent_estimator: ConcurrentQuantumEstimator[CircuitQuantumState]) GeneralQuantumEstimator[CircuitQuantumState, ParametricCircuitQuantumState]#
create_general_estimator_from_concurrent_estimator(concurrent_estimator: ConcurrentQuantumEstimator[QuantumStateVector]) GeneralQuantumEstimator[QuantumStateVector, ParametricQuantumStateVector]

Creates a GeneralEstimator from a ConcurrentQuantumEstimator.

Note: - When circuit conversion is involved in the estimator execution, the

parametric estimator created from this function will bind the parameter first, and then convert the bound circuit every time the patametric estimator is called.

Subpackages#

Submodules#