Evaluating Computables with Protocols

Protocols are designed to manage the lower-level details of calculations. In particular, in workflows that require quantum measurements, a protocol builds and compiles measurement circuits, post-processes measurement results, and interprets distributions. While protocols and computables are independent data structures, several protocols are provided that can help evaluate some of the atomic computables.

One of the most versatile protocols is the SparseStatevectorProtocol, which internally performs statevector calculations for various quantum expressions with the help of a statevector pytket backend. More details on InQuanto protocols can be found here and in the API reference.

An instance of SparseStatevectorProtocol can provide an evaluator function via the get_evaluator() method. Computables may be symbolic objects, that is, they may depend on Sympy symbols originating from a symbolic ansatz. As a result, the get_evaluator() method requires a symbol-value map to substitute the numerical values in place of the symbols before the statevector computation takes place. The resulting evaluator function (sv_evaluator below) may then be passed to the computable’s evaluate() method, to obtain the final results. We continue with the same example as the previous section to compute the Hamiltonian variance:

from pytket.extensions.qiskit import AerStateBackend
from inquanto.express import get_system
from inquanto.core import SymbolDict
from inquanto.operators import QubitOperatorList
from inquanto.ansatzes import TrotterAnsatz
from inquanto.protocols import SparseStatevectorProtocol
from inquanto.computables import ExpectationValue
from inquanto.computables.primitive import ComputableFunction

ham, _, _ = get_system("h2_sto3g.h5")
qubit_hamiltonian = ham.qubit_encode().hermitian_part()

ansatz = TrotterAnsatz(
    exponents=QubitOperatorList.from_string("theta [(1j, Y0 X1 X2 X3)]"),
    reference=[1, 1, 0, 0],
)
parameters = SymbolDict(theta=-0.41)

c_variance = ComputableFunction(lambda x, y: x - y,
                ExpectationValue(ansatz, qubit_hamiltonian ** 2),
                ComputableFunction(lambda x: x ** 2, ExpectationValue(ansatz, qubit_hamiltonian))
            )

sv = SparseStatevectorProtocol(AerStateBackend())
sv_evaluator = sv.get_evaluator(parameters)
print(c_variance.evaluate(evaluator=sv_evaluator))
0.23089952010568726

The SparseStatevectorProtocol does not generate measurement circuits, but uses the backend to obtain the statevector of the ansatz, therefore the computational cost exponentially increases with the number of qubits.

In contrast, a more specialized protocol PauliAveraging is able to use a quantum device to calculate expectation values. This protocol builds measurement circuits, which may be submitted to a quantum device or shot-based simulator:

from pytket.extensions.qiskit import AerBackend
from inquanto.protocols import PauliAveraging
from pytket.partition import PauliPartitionStrat

pa = PauliAveraging(
    AerBackend(),
    shots_per_circuit=1000,
    pauli_partition_strategy=PauliPartitionStrat.CommutingSets,
)

pa.build_from(parameters, c_variance)
pa.run(seed=0)

pa_evaluator = pa.get_evaluator()
print(c_variance.evaluate(evaluator=pa_evaluator))
0.20430236328482176

It is important to note that since this protocol needs to build and run the measurement circuits, it requires the build_from() method, which builds the non-symbolic measurement circuits that are necessary to eventually evaluate c_variance, and requires the run() method which submits the circuits to the backend and retrieves results. The build phase is when measurement reduction takes place using the commuting set strategy. Since the protocol is built from a computable, this measurement reduction is applied to the entire computable expression tree, which is more advantageous than measuring the expectation values in the variance expression separately, in this particular example.

After the run phase, the protocol is ready to provide an evaluator with get_evaluator(). In this case there is no need to pass the symbol-value map to the evaluator; the build phase performs symbol subsitution so that measurement circuits are already fully numerical.

Note that the run() method submits circuits to the backend, and waits for retrieval. As a result, it is ill-suited to submitted circuits to real quantum hardware, where there may be a long wait time. In this case, it is recommended to use the launch() and retrieve() methods:

handles = pa.launch(seed=0)
pa.retrieve(handles)
<inquanto.protocols.averaging._pauli_averaging.PauliAveraging at 0x7ff7f8b12f90>

Together, these methods are equivalent to run(), but launch() does not block the runtime. The quantum computational details are stored in the protocol in this case, therefore all optimizations, redundancies, uncertainties and resources that are necessary to evaluate c_variance can be requested from the protocol for analysis.

Sometimes, details of the workflow are not important, therefore some protocols provide the get_runner() method which returns a function that takes in a symbol-value map and returns the value of the computable it was made for:

sv_runner_variance = sv.get_runner(c_variance)
print(sv_runner_variance(parameters))

pa_runner_variance = pa.get_runner(c_variance)
print(pa_runner_variance(parameters))
0.23089952010568726
0.1813152953458652

And it is often useful to get the result quickly for a computable, during prototyping for example. For this purpose, one can use:

print(c_variance.default_evaluate(parameters))
0.23089952010568726

which internally instantiates a SparseStatevectorProtocol protocol and calculates the result with it. This statevector protocol will attempt to use an AerStateBackend instance from pytket-qiskit then a QulacsBackend from pytket-qulacs to evaluate the protocol if the former is unavailable.

Note that there may be several protocols which are capable of calculating the same quantity, but by quite different methods. Also, some protocols can calculate various quantities, while others are capable of calculating only one specific quantity. It is recommended to refer to the protocols manual page, and the API documentation to familiarize yourself with the capabilities and scopes of specific computables and protocols.

Evaluating Composite Computables with ProtocolList

This section contains some more advanced topics in the use of computables and protocols. It is recommended that the reader first familiarizes themselves with the use of statevector and averaging protocols and with primitive computable objects before reading this section.

Composite computable objects may require more than one shot-based protocol to build and run all of the circuits required for evaluation. One such example of this is a simple pair of expectation values with respect to two different states:

from inquanto.computables import ComputableTuple

ansatz2 = ansatz.copy().symbol_substitution("{}_2")
parameters = SymbolDict(theta=-0.41, theta_2=1.0)

computable_tuple = ComputableTuple(
    ExpectationValue(ansatz, qubit_hamiltonian),
    ExpectationValue(ansatz2, qubit_hamiltonian),
)

The PauliAveraging protocol is capable of evaluating expectation values, but a single instance of any averaging protocol supports only a single ansatz state (or pair of states in the case of overlap and overlap squared protocols). Evaluating an object like this in InQuanto is made easier and more efficient using the ProtocolList class:

protocols = PauliAveraging.build_protocols_from(
    parameters=parameters,
    computable=computable_tuple,
    backend=AerBackend(),
    shots_per_circuit=10000,
    pauli_partition_strategy=PauliPartitionStrat.CommutingSets,
)

print(f"Number of protocols: {len(protocols)}\n")
print(protocols.dataframe_protocol_circuit())
Number of protocols: 2

       Protocol ID   Protocol Type  Qubits  Depth2q  Shots
0  140702947678736  PauliAveraging       4        6  10000
1  140702947678736  PauliAveraging       4        8  10000
2  140703005419344  PauliAveraging       4        6  10000
3  140703005419344  PauliAveraging       4        8  10000

The build_protocols_from() method parses the input computable and builds protocols for computable nodes that the chosen protocol is capable of evaluating, storing them in a ProtocolList. In this case, two PauliAveraging protocols are required, totaling four circuits.

We may then run all circuits through the ProtocolList interface, and generate an evaluator function for this composite computable:

protocols.run(seed=0)
computable_tuple.evaluate(protocols.get_evaluator())
(-0.9869527172517868, 0.20709664898096042)

If our composite computable contains two expectation values with respect to the same state, build_protocols_from() will collect all measurements required for both nodes into a single protocol. This allows measurement reduction (the collection of Pauli words into simultaneously measurable sets) over all Pauli words in both expectation values, potentially reducing the total number of circuits required. For example:

computable_tuple2 = ComputableTuple(
    ExpectationValue(ansatz, qubit_hamiltonian),
    ExpectationValue(ansatz, qubit_hamiltonian**2),
)

protocols = PauliAveraging.build_protocols_from(
    parameters=parameters,
    computable=computable_tuple2,
    backend=AerBackend(),
    shots_per_circuit=10000,
    pauli_partition_strategy=PauliPartitionStrat.CommutingSets,
)

print(f"Number of protocols: {len(protocols)}\n")
print(protocols.dataframe_protocol_circuit())
Number of protocols: 1

       Protocol ID   Protocol Type  Qubits  Depth2q  Shots
0  140702944480400  PauliAveraging       4        6  10000
1  140702944480400  PauliAveraging       4        8  10000
2  140702944480400  PauliAveraging       4        8  10000

Other averaging protocols will perform similar measurement reduction when parsing composite computables with build_protocols_from().

Composite computables may also consist of a mixture of different physical quantities. Again, we consider a simple example: a tuple containing two expectation values, and an overlap squared:

from inquanto.computables import OverlapSquared

computable_tuple_mix = ComputableTuple(
    ExpectationValue(ansatz, qubit_hamiltonian),
    ExpectationValue(ansatz2, qubit_hamiltonian),
    OverlapSquared(ansatz, ansatz2),
)

For this computable we will use two averaging protocols, SwapTest and PauliAveraging. We use build_protocols_from() again to parse the computable, and then compose a single ProtocolList for running and evaluating:

from inquanto.protocols import SwapTest

ovlp_protocols = SwapTest.build_protocols_from(
    parameters=parameters,
    computable=computable_tuple_mix,
    backend=AerBackend(),
    n_shots=10000,
)

eval_protocols = PauliAveraging.build_protocols_from(
    parameters=parameters,
    computable=computable_tuple_mix,
    backend=AerBackend(),
    shots_per_circuit=10000,
    pauli_partition_strategy=PauliPartitionStrat.CommutingSets,
)

# Join together all protocols into a single ProtocolList
protocols = ovlp_protocols + eval_protocols
print(protocols.dataframe_protocol_circuit())

protocols.run(seed=0)
computable_tuple_mix.evaluate(protocols.get_evaluator())
       Protocol ID   Protocol Type  Qubits  Depth2q  Shots
0  140702947680848        SwapTest       9       27  10000
1  140702948096144  PauliAveraging       4        6  10000
2  140702948096144  PauliAveraging       4        8  10000
3  140702982452880  PauliAveraging       4        6  10000
4  140702982452880  PauliAveraging       4        8  10000
(-0.9869527172517868, 0.20709664898096042, 0.02899999999999997)

If we wish to evaluate part of the computable with a shot-based protocol, and another part with statevector simulation, we may use partial evaluation. For example, below we consider the same tuple of overlap squared and expectation values, but evaluate the overlap squared part using statevector simulation:

# First, build and run protocols for the expectation value nodes
protocol_list = PauliAveraging.build_protocols_from(
    parameters=parameters,
    computable=computable_tuple_mix,
    backend=AerBackend(),
    shots_per_circuit=10000,
    pauli_partition_strategy=PauliPartitionStrat.CommutingSets,
)
protocol_list.run(seed=1)

# Note the use of allow_partial=True for building a partial evaluator
shot_evaluator = protocol_list.get_evaluator(allow_partial=True)
partial_result = computable_tuple_mix.evaluate(shot_evaluator)
print(f"Partially evaluated computable:\n{partial_result}\n")

# Define statevector protocol to evaluate remaining node
sv_evaluator = SparseStatevectorProtocol(AerStateBackend()).get_evaluator(parameters)
final_result = partial_result.evaluate(sv_evaluator)
print(f"Fully evaluated computable:\n{final_result}")
Partially evaluated computable:
(-0.9869804954120792, 0.22476991621493542, OverlapSquared(bra_state=<inquanto.ansatzes._trotter_ansatz.TrotterAnsatz, qubits=4, gates=33, symbols=1>, ket_state=<inquanto.ansatzes._trotter_ansatz.TrotterAnsatz, qubits=4, gates=33, symbols=1>, kernel={(): 1.0}))

Fully evaluated computable:
(-0.9869804954120792, 0.22476991621493542, 0.025633390578446377)

Beyond these simple cases, ProtocolList is useful for evaluating composite protocols in general. A natural example of this is the overlap matrix, which consists of expectation values along the diagonal, and complex overlaps on the off-diagonal elements.