inquanto.protocols
Protocols for Expectation Values
- class PauliAveraging(backend=None, shots_per_circuit=8000, pauli_partition_strategy=PauliPartitionStrat.NonConflictingSets, pauli_colour_method=GraphColourMethod.Lazy)
Bases:
ProtocolListItem
,PartiallyPickleable
,QermitRunMixin
,ComputableCompliantMixin
Calculates the expectation value of a Hermitian operator by operator averaging the system register.
Implements the ‘Operator Averaging’ procedure (see: arXiv:1407.7863, arXiv:1510.04279).
- Parameters:
backend (
Optional
[Backend
], default:None
) – The backend to use for quantum computations.shots_per_circuit (
int
, default:8000
) – Number of shots for each circuit. Default is 8000.pauli_partition_strategy (
Optional
[PauliPartitionStrat
], default:PauliPartitionStrat.NonConflictingSets
) – Strategy to partition Pauli operators.pauli_colour_method (
Optional
[GraphColourMethod
], default:GraphColourMethod.Lazy
) – Method to perform graph colouring.
- build(parameters, state, *operators, noise_mitigation=None, optimisation_level=1)
Builds the necessary circuits and measurement data for the state and Pauli strings in the operators.
Note
The coefficients in the operators are ignored.
- Parameters:
parameters (
Union
[SymbolDict
,Dict
]) – A dictionary orSymbolDict
containing the parameter values for the circuits.state (
GeneralAnsatz
) – Parametrized input state.operators (
QubitOperator
) – Qubit operators, the Pauli strings in theseQubitOperator
objects are used to generate measurement circuits.noise_mitigation (
Optional
[NoiseMitigation
], default:None
) – The noise mitigation instance containing pre and post mitigation strategies.optimisation_level (
int
, default:1
) – Passed to the backend’sget_compiled_circuits()
method.
- Returns:
PauliAveraging
– Self instance.
- build_from(parameters, computable, exclude=None, noise_mitigation=None)
Build the protocol based on given parameters and computable expression.
This method walks over the computable expression tree and collects all qubit operators appearing in nodes of type:
After it has walked over the tree, it calls the build method.
- Raises:
NotImplementedError – If not all
ExpectationValue
nodes in the computable tree contain the same state.- Parameters:
parameters (
Union
[SymbolDict
,Dict
]) – Parameters for building.computable (
ComputableNode
) – A root node of a computable expression tree, simply it is a computable expression.exclude (
Optional
[Callable
[[ComputableNode
],bool
]], default:None
) – Optional callable function to exclude certain nodes from processing.noise_mitigation (
Optional
[NoiseMitigation
], default:None
) – The noise mitigation instance containing pre and post mitigation strategies.
- Returns:
PauliAveraging
– Modified instance after building.
- classmethod build_protocols_from(parameters, computable, exclude=None, noise_mitigation=None, *args, **kwargs)
Build a list of protocols based on the given parameters and computable expression.
This method walks over the computable expression tree and collects all qubit operator kernels appearing in nodes of type:
After it has walked over the tree, it creates an instance of
PauliAveraging
for each distinct state and calls thebuild()
method with the kernel operators associated with the state. It collects all created protocols into aProtocolList
object to be returned.- Parameters:
parameters (
Union
[SymbolDict
,Dict
]) – Values for the parameters in the computable expression.computable (
ComputableNode
) – A root node of a computable expression tree.exclude (
Optional
[Callable
[[ComputableNode
],bool
]], default:None
) – Optional callable function to exclude certain nodes from processing.noise_mitigation (
Optional
[NoiseMitigation
], default:None
) – The noise mitigation instance containing pre and post mitigation strategies.*args – Arguments passed to the constructor of
PauliAveraging
.**kwargs – Keyword arguments passed to the constructor of
PauliAveraging
.
- Returns:
ProtocolList
– A list, containing all the newly instantiated and built protocols.
- clear()
Resets the internal state of the object by clearing all stored data.
This method clears all stored data including state hashes, operator hashes, measurement setups, parameters, and associated dataframes and circuits.
- Returns:
PauliAveraging
– self.
- cost()
Calculate a simple cost metric running the protocol.
The cost is calculated as the sum of the depth of each circuit multiplied by the number of shots.
- Returns:
int
– The cost value as an integer.
- credits(syntax_checker=None, use_websocket=None)
Evaluate an approximate cost for the measurement circuits built in Quantinuum credits.
Syntax checker will usually be automatically selected, but in some cases needs to be provided. If the measurement circuits are not built yet, the credits will be zero.
Note
This works only with
QuantinuumBackend
compatible backends.
- dataframe_circuit_shot()
Create a pandas
DataFrame
with circuit, shot, and depth information.- Returns:
DataFrame
– A pandasDataFrame
containing the circuit, shot, and depth information.
- dataframe_measurements()
Create a
DataFrame
consisting of computational details.- Returns:
DataFrame
– A pandasDataFrame
with columns'pauli_string'
,'mean'
, and'stderr'
. Each row represents a unique Pauli string and its associated mean and standard error.
- dataframe_partitioning()
Create a
DataFrame
consisting of partitioning info.- Returns:
DataFrame
– A pandasDataFrame
with columns'pauli_string'
,'circ_index'
, and'circ_name'
. Each row represents a Pauli string and its circuit index pairs.
- dump(file)
Save the object to a file using pickle.
- dumps()
Returns the object pickled as a bytes object.
- Returns:
bytes
– The object’s state pickled as a bytes object.
- evaluate_expectation_uvalue(state, kernel)
Evaluates the expectation value of a Hermitian kernel with linear error propagation theory.
Similarly to
evaluate_expectation_value()
, this can be only performed if before calling this protocol has been built for the state and kernel (or other operators composed of the same Pauli strings).Note
It is assumed the measurements for each Pauli strings are independent, that is not generally the case if measurement reduction is applied.
- Parameters:
state (
GeneralAnsatz
) – The quantum state for which the expectation value of the kernel is to be calculated.kernel (
QubitOperator
) – The operator for which the expectation value is being computed.
- Returns:
ufloat
– The expectation value of the kernel with respect to the given state with standard error.
- evaluate_expectation_value(state, kernel)
Evaluates the provided expectation value.
Computes the expectation value with the kernel and state provided.
This method can only be performed if, prior to calling this method, the protocol has been built for the input state and kernel (or other operators composed of the same Pauli strings), and the protocol has also been run.
- Parameters:
state (
GeneralAnsatz
) – The quantum state for which the expectation value of the kernel is to be calculated.kernel (
QubitOperator
) – The operator for which the expectation value is being computed.
- Returns:
float
– The expectation value of the kernel with respect to the given state.
- get_circuits()
Returns the quantum circuits built for this protocol.
- Returns:
List
[Circuit
] – List of circuits.
- get_circuitshots()
Generate the circuit shot pairs.
- Yields:
Pair of circuit and the associated number of shots.
- Return type:
Iterator
[CircuitShots
]
- get_evaluator(allow_partial=False)
Returns an evaluator function to evaluate quantum computables.
This method creates and returns a function (evaluator) that takes in a specific quantum computable and evaluates it based on its type.
Quantum computables the returned evaluator can handle:
- Parameters:
allow_partial (
bool
, default:False
) – IfFalse
, evaluation will fail when an unsupported computable node is encountered. IfTrue
, unsupported nodes will be skipped.
Note
This evaluator works for quantum computables the protocol has been built from.
- Raises:
NotImplementedError – If an unsupported computable is encountered, and
allow_partial==False
.- Returns:
Callable
[[Evaluatable
],Union
[Evaluatable
,Any
]] – A function that can evaluate quantum computables. If a computable is supported by this protocol, it is computed; otherwise, it returns the computable itself.
- get_runner(qc, compile_symbolic=False, *args, **kwargs)
Returns an end-to-end executor function for a quantum computable.
All nodes in the quantum computable must be evaluable by this protocol. That is, the leaf nodes need to be of one of the supported types:
Note
At every call of the returned function the internal state of the protocol changes.
- Parameters:
qc (
ComputableNode
) – The quantum computable node to be measured and evaluated at every call of the returned function.compile_symbolic (
bool
, default:False
) – IfTrue
, circuits are immediately built and compiled symbolically. Calling the returned function substitutes symbols, runs circuits, and evaluates the output. IfFalse
, circuits are built and compiled only when the returned function is called and parameters are provided. Note that circuits may be deeper whencompile_symbolic=True
, because circuit compilation cannot perform optimizations based on numerical parameter values. The advantage of this case is that compilation only takes place once.
- Returns:
Callable
[[Union
[SymbolDict
,Dict
]],Any
] – A function that takes the parameters, builds and measures the necessary circuits, and returns the evaluated result.
- get_shots()
Returns the number shots to be used for each circuit.
- property is_built: bool
Boolean flag indicating if the instance has been built.
- Returns:
True
if thebuild()
method has been successfully invoked, otherwiseFalse
.
- property is_numeric: bool
Boolean flag indicating if the measurement circuits contain free symbols.
- Returns:
False
if any built measurement circuit contains unsubstituted symbols, otherwiseTrue
.
- property is_run: bool
Boolean flag indicating if the instance has been run.
- Returns:
True
if therun()
method has been successfully invoked, otherwiseFalse
.
- property is_symbolic: bool
Boolean flag indicating if the measurement circuits contain free symbols.
- Returns:
True
if any built measurement circuit contains unsubstituted symbols, otherwiseFalse
.
- launch(*args, **kwargs)
Launch the circuits to the backend and return the handles for the results.
This method processes all the circuits and returns a list of
ResultHandle
objects representing the handles for the results.- Parameters:
*args – Additional arguments to be passed to
self.backend.process_circuits()
.**kwargs – Additional keyword arguments to be passed to
self.backend.process_circuits()
.
- Returns:
List
[ResultHandle
] – A list of pytketResultHandle
objects representing the handles for the launched circuits.
- classmethod load(file, *args, **kwargs)
Load a pickled object from a file.
- Parameters:
- Returns:
TypeVar
(T
, bound= PartiallyPickleable) – An instance of the class with its state loaded from the pickled data.
- classmethod loads(pickled_data, *args, **kwargs)
Load a pickled object from a bytes object.
- Parameters:
- Returns:
TypeVar
(T
, bound= PartiallyPickleable) – An instance of the class with its state loaded from the pickled data.
- rebuild(*args, **kwargs)
Rebuild the internal data structure.
It is equivalent to
clear().build(*args, **kwargs)
.
- retrieve(source, *args, **kwargs)
Retrieve distributions from the backend for the given source.
If the
source
is a list of pytketResultHandle
, the distributions are retrieved usingself.backend.get_results()
method. If thesource
is a list of pytketBackendResult
, it is assumed that the results are already provided.- Parameters:
- Returns:
PauliAveraging
– Returns self instance.
- run(*args, **kwargs)
Run the protocol and waiting for the results.
This method executes the following steps: 1. Launches the measurement circuits to obtain the circuit handles. 2. Retrieves the measurement distributions using the circuit handles.
- run_mitex(mitex, characterisation)
Run via Qermit
MitEx
instance with provided characterisation.The following steps will be executed: Step 1: State and Pauli strings are converted to
ObservableExperiment
experiments. Step 2: The experiments are run via theMitEx
instance. Step 3: Results are processed and internal data structures are updated.- Parameters:
mitex (
MitEx
) – The instance ofMitEx
to run.characterisation (
Dict
) – The characterisation to use for the run.
- Returns:
PauliAveraging
– An instance of the class with updated data.
- run_mitres(mitres, characterisation)
Run via Qermit
MitRes
instance with provided characterisation.The following steps will be executed: Step 1: circuits and shots will be generated and passed to
MitRes
instance to run. Step 2: the backend results from theMitRes
run is retrieved and internal data is updated.- Parameters:
mitres (
MitRes
) – The instance ofMitRes
to run.characterisation (
Dict
) – The characterisation to use for the run.
- Returns:
PauliAveraging
– An instance of the class with updated data.
- class HadamardTest(backend, shots_per_circuit=8000)
Bases:
ProtocolListItem
,PartiallyPickleable
,ComputableCompliantMixin
Calculate the expectation value of a qubit operator using Hadamard tests.
Given an operator as a linear combination of Pauli strings, \(H = \sum_i c_i P_i\), computes the expectation value \(\langle H \rangle\) by performing a set of Hadamard tests to measure the real expectation value of each pauli string (see also the wikipedia article).
- Parameters:
backend (
Backend
) – The backend to use for quantum computations.shots_per_circuit (
int
, default:8000
) – Number of shots for each circuit.
- build(parameters, state, *operators, optimisation_level=1)
Builds Hadamard test measurement circuits for each Pauli string.
Note
The coefficients in the operators are ignored.
- Parameters:
parameters (
Union
[SymbolDict
,Dict
]) – A dictionary orSymbolDict
containing the parameter values for the circuits.state (
GeneralAnsatz
) – Parametrized input state.operators (
QubitOperator
) – Qubit operators, the Pauli strings in theseQubitOperator
objects are used to generate measurement circuits.optimisation_level (
int
, default:1
) – Passed to the backend’sget_compiled_circuits()
method.
- Returns:
TypeVar
(T
, bound= HadamardTest) – Self instance.
- build_from(parameters, computable, exclude=None)
Build the protocol based on given parameters and computable expression.
This method walks over the computable expression tree and collects all qubit operators appearing in nodes of type:
After it has walked over the tree, it calls the build method.
- Raises:
NotImplementedError – If not all ExpectationValue nodes in the computable tree contain the same state.
- Parameters:
parameters (
Union
[SymbolDict
,Dict
]) – Parameters for building.computable (
ComputableNode
) – A root node of a computable expression tree, simply it is a computable expression.exclude (
Optional
[Callable
[[ComputableNode
],bool
]], default:None
) – Optional callable function to exclude certain nodes from processing.
- Returns:
HadamardTest
– The modified instance after building.
- classmethod build_protocols_from(parameters, computable, exclude=None, *args, **kwargs)
Build a
ProtocolList
based on the given parameters and a computable expression.This method walks over the computable expression tree and collects all qubit operator kernels appearing in nodes of type:
After walking over the tree, it creates an instance of
HadamardTest
for each distinct state and calls thebuild()
method with the kernel operators associated with the state. It collects all created protocols into aProtocolList
object to be returned.- Parameters:
parameters (
Union
[SymbolDict
,Dict
]) – Values for the parameters in the computable expression.computable (
ComputableNode
) – A root node of a computable expression tree.exclude (
Optional
[Callable
[[ComputableNode
],bool
]], default:None
) – Optional callable function to exclude certain nodes from processing*args – Arguments passed to the constructor of
HadamardTest
.**kwargs – Keyword arguments passed to the constructor of
HadamardTest
.
- Returns:
ProtocolList
–ProtocolList
of the newly instantiated and built protocols.
- clear()
Resets the internal state of the object by clearing all stored data.
This method clears all stored data including state hashes, operator hashes, measurement setups, parameters, and associated dataframes and circuits.
- Returns:
TypeVar
(T
, bound= HadamardTest) – self.
- cost()
Calculate a simple cost metric running the protocol.
The cost is calculated as the sum of the depth of each circuit multiplied by the number of shots.
- Returns:
int
– The cost value as an integer.
- credits(syntax_checker=None, use_websocket=None)
Evaluate an approximate cost for the measurement circuits built in Quantinuum credits.
Syntax checker will usually be automatically selected, but in some cases needs to be provided. If the measurement circuits are not built yet, the credits will be zero.
Note
This works only with
QuantinuumBackend
compatible backends.
- dataframe_circuit_shot()
Create a pandas
DataFrame
with circuit, shot, and depth information.- Returns:
DataFrame
– A pandasDataFrame
containing the circuit, shot, and depth information.
- dataframe_measurements()
Create a
DataFrame
consisting of computational details.- Returns:
DataFrame
– A pandasDataFrame
with columns'pauli_string'
,'mean'
, and'stderr'
. Each row represents a unique Pauli string and its associated mean and standard error.
- dump(file)
Save the object to a file using pickle.
- dumps()
Returns the object pickled as a bytes object.
- Returns:
bytes
– The object’s state pickled as a bytes object.
- evaluate_expectation_value(state, kernel)
Evaluates the provided expectation value.
Computes the expectation value with the kernel and state provided.
This method can only be performed if, prior to calling this method, the protocol has been built for the input state and kernel (or other operators composed of the same Pauli strings), and the protocol has also been run.
- Parameters:
state (
GeneralAnsatz
) – The quantum state for which the expectation value of the kernel is to be calculated.kernel (
Union
[QubitOperator
,QubitOperatorString
]) – The operator for which the expectation value is being computed.
- Returns:
float
– The expectation value of the kernel with respect to the given state.
- get_circuits()
Returns the quantum circuits built for this protocol.
- Returns:
List
[Circuit
] – List of circuits.
- get_circuitshots()
Generate the circuit shot pairs.
- Yields:
Pair of circuit and the associated number of shots.
- Return type:
Iterator
[CircuitShots
]
- get_evaluator(allow_partial=False)
Returns an evaluator function to evaluate quantum computables.
This method creates and returns a function (evaluator) that takes in a specific quantum computable and evaluates it based on its type.
Quantum computables the returned evaluator can handle:
- Parameters:
allow_partial (
bool
, default:False
) – IfFalse
, evaluation will fail when an unsupported computable node is encountered. IfTrue
, unsupported nodes will be skipped.- Raises:
NotImplementedError – If an unsupported computable is encountered, and
allow_partial==False
.
Note
This evaluator works for quantum computables the protocol has been built from.
- Returns:
Callable
[[Evaluatable
],Union
[Evaluatable
,Any
]] – A function that can evaluate quantum computables. If a computable is supported by this protocol, it is computed; otherwise, it returns the computable itself.
- get_runner(qc, compile_symbolic=False, *args, **kwargs)
Returns an end-to-end executor function for a quantum computable.
All nodes in the quantum computable must be evaluable by this protocol. That is, the leaf nodes need to be of one of the supported types:
Note
At every call of the returned function the internal state of the protocol changes.
- Parameters:
qc (
ComputableNode
) – The quantum computable node to be measured and evaluated at every call of the returned function.compile_symbolic (
bool
, default:False
) – IfTrue
, circuits are immediately built and compiled symbolically. Calling the returned function substitutes symbols, runs circuits, and evaluates the output. IfFalse
, circuits are built and compiled only when the returned function is called and parameters are provided. Note that circuits may be deeper whencompile_symbolic=True
, because circuit compilation cannot perform optimizations based on numerical parameter values. The advantage of this case is that compilation only takes place once.
- Returns:
Callable
[[Union
[SymbolDict
,Dict
]],Any
] – A function that takes the parameters, builds and measures the necessary circuits, and returns the evaluated result. If the result is not afloat
, it returnsmath.nan
.
- get_shots()
Returns the number shots to be used for each circuit.
- property is_built: bool
Boolean flag indicating if the instance has been built.
- Returns:
True
if thebuild()
method has been successfully invoked, otherwiseFalse
.
- property is_numeric: bool
Boolean flag indicating if the measurement circuits contain free symbols.
- Returns:
False
if any built measurement circuit contains unsubstituted symbols, otherwiseTrue
.
- property is_run: bool
Boolean flag indicating if the instance has been run.
- Returns:
True
if therun()
method has been successfully invoked, otherwiseFalse
.
- property is_symbolic: bool
Boolean flag indicating if the measurement circuits contain free symbols.
- Returns:
True
if any built measurement circuit contains unsubstituted symbols, otherwiseFalse
.
- launch(*args, **kwargs)
Launch the circuits to the backend and return the handles for the results.
This method processes all the circuits and returns a list of
ResultHandle
objects representing the handles for the results.- Parameters:
*args – Additional arguments to be passed to
self.backend.process_circuits()
.**kwargs – Additional keyword arguments to be passed to
self.backend.process_circuits()
.
- Returns:
List
[ResultHandle
] – A list of pytketResultHandle
objects representing the handles for the launched circuits.
- classmethod load(file, *args, **kwargs)
Load a pickled object from a file.
- Parameters:
- Returns:
TypeVar
(T
, bound= PartiallyPickleable) – An instance of the class with its state loaded from the pickled data.
- classmethod loads(pickled_data, *args, **kwargs)
Load a pickled object from a bytes object.
- Parameters:
- Returns:
TypeVar
(T
, bound= PartiallyPickleable) – An instance of the class with its state loaded from the pickled data.
- rebuild(*args, **kwargs)
Rebuild the internal data structure.
It is equivalent to
clear().build(*args, **kwargs)
.
- retrieve(source, *args, **kwargs)
Retrieve distributions from the backend for the given source.
If the
source
is a list of pytketResultHandle
, the distributions are retrieved usingself.backend.get_results()
method. If thesource
is a list of pytketBackendResult
, it is assumed that the results are already provided.- Parameters:
- Returns:
TypeVar
(T
, bound= HadamardTest) – Returns self instance.
- run(*args, **kwargs)
Run the protocol and waiting for the results.
This method executes the following steps: 1. Launches the measurement circuits to obtain the circuit handles. 2. Retrieves the measurement distributions using the circuit handles.
Protocols for Overlap Squared
- class ComputeUncompute(backend, n_shots=8000)
Bases:
BaseOverlapSquaredProtocol
Calculates the overlap squared with the compute-uncompute method.
For input states \(|{\psi}\rangle = U|{0}\rangle\) and \(|{\phi}\rangle = V|{0}\rangle\), prepares the state \(U^\dagger V|{0}\rangle\). The overlap squared \(|\langle{\psi|\phi}\rangle|^2\) is then given by the probability of measuring a vacuum state \(|{0}\rangle\). See https://arxiv.org/abs/1810.02327.
Supports calculation of overlap squared of the form: \(|\langle\psi|cP|\phi\rangle|^2\), where \(P\) is a Pauli word and \(c\) is a numeric constant.
- Parameters:
backend (
Backend
) – The backend to use for quantum computations.n_shots (
int
, default:8000
) – Number of shots to perform.
- build(parameters, bra_state, ket_state, kernel=None, optimisation_level=1)
Builds the necessary circuits and measurement data.
Note
Any coefficient in the operator kernel is ignored.
- Parameters:
parameters (
Union
[SymbolDict
,Dict
]) – Parameter values for the circuits.bra_state (
GeneralAnsatz
) – Left-hand state.ket_state (
GeneralAnsatz
) – Right-hand state.kernel (
Union
[QubitOperator
,QubitOperatorString
,None
], default:None
) – Optional operator kernel. Must be a single Pauli string.optimization_level – Passed as the
optimisation_level
arg to the backend’sget_compiled_circuits()
method.optimisation_level (
int
, default:1
)
- Returns:
TypeVar
(T
, bound= BaseOverlapSquaredProtocol) – Self instance after building the necessary circuits and measurement data.
- build_from(parameters, computable, exclude=None)
Builds the protocol based on given parameters and computable expression.
This method walks over the computable expression tree and calls the
build()
method when it encounters a node of typeOverlapSquared
.- Parameters:
parameters (
Union
[SymbolDict
,Dict
]) – Parameters for building.computable (
ComputableNode
) – A root node of a computable expression tree, simply it is a computable expression.exclude (
Optional
[Callable
[[ComputableNode
],bool
]], default:None
) – Optional callable function to exclude certain nodes from processing.
- Returns:
TypeVar
(T
, bound= BaseOverlapSquaredProtocol) – Returns the modified instance after building.
- classmethod build_protocols_from(parameters, computable, exclude=None, *args, **kwargs)
Build a list of protocols based on the given parameters and computable expression.
- This method walks over the computable expression tree and collects leaf nodes of type:
After it has walked over the tree, it creates an instance of this protocol for each distinct bra, ket, kernel trio and calls the
build()
method. It collects all created protocols into aProtocolList
object to be returned.- Parameters:
parameters (
Union
[SymbolDict
,Dict
]) – Values for the parameters in the computable expression.computable (
ComputableNode
) – A root node of a computable expression tree.exclude (
Optional
[Callable
[[ComputableNode
],bool
]], default:None
) – Optional callable function to exclude certain nodes from processing.*args – Arguments passed to the constructor of the overlap squared protocol.
**kwargs – Keyword arguments passed to the constructor of the overlap squared protocol.
- Returns:
ProtocolList
– A list, containing all the newly instantiated and built protocols.
- circuit: Optional[Circuit]
- clear()
Resets the internal state of the object by clearing all stored data.
This method clears all stored data including state hashes, operator hashes, measurement setups, parameters, and associated dataframes and circuits.
- Returns:
TypeVar
(T
, bound= BaseOverlapSquaredProtocol) – self.
- cost()
Calculate a simple cost metric running the protocol.
The cost is calculated as the sum of the depth of each circuit multiplied by the number of shots.
- Returns:
int
– The cost value as an integer.
- credits(syntax_checker=None, use_websocket=None)
Evaluate an approximate cost for the measurement circuits built in Quantinuum credits.
Syntax checker will usually be automatically selected, but in some cases needs to be provided. If the measurement circuits are not built yet, the credits will be zero.
Note
This works only with
QuantinuumBackend
compatible backends.
- dataframe_circuit_shot()
Create a pandas
DataFrame
with circuit, shot, and depth information.- Returns:
DataFrame
– A pandasDataFrame
containing the circuit, shot, and depth information.
- dump(file)
Save the object to a file using pickle.
- dumps()
Returns the object pickled as a bytes object.
- Returns:
bytes
– The object’s state pickled as a bytes object.
- evaluate_overlap_squared(bra_state, ket_state, kernel)
Evaluates the overlap squared for given states and kernel.
- Parameters:
bra_state (
GeneralAnsatz
) – Left-hand state.ket_state (
GeneralAnsatz
) – Right-hand state.kernel (
Union
[QubitOperator
,QubitOperatorString
]) – Overlap kernel. Must be a single Pauli string.
Note
Input states and pauli string in the kernel need to match with the states and pauli string the circuit was built for to correctly interpret the circuit output distribution.
- Returns:
Overlap squared.
- get_circuits()
Returns the quantum circuits built for this protocol.
- Returns:
List
[Circuit
] – List of circuits.
- get_circuitshots()
Generate the circuit shot pairs.
- Yields:
Pair of circuit and the associated number of shots.
- Return type:
Iterator
[CircuitShots
]
- get_evaluator(allow_partial=False)
Returns an evaluator function to evaluate quantum computables.
This method creates and returns a function (evaluator) that takes in a specific quantum computable and evaluates it based on its type.
Quantum computables the returned evaluator can handle:
- Parameters:
allow_partial (
bool
, default:False
) – IfFalse
, evaluation will fail when an unsupported computable node is encountered. IfTrue
, unsupported nodes will be skipped.- Raises:
NotImplementedError – If an unsupported computable is encountered, and
allow_partial==False
.
Note
This evaluator works for quantum computables the protocol has been built from.
- Returns:
Callable
[[Evaluatable
],Union
[Evaluatable
,Any
]] – A function that can evaluate quantum computables. If a computable is supported by this protocol, it is computed; otherwise, it returns the computable itself.
- get_runner(c, compile_symbolic=False, *args, **kwargs)
Returns an end-to-end executor function for a quantum computable.
Note
All nodes in the quantum computable must be evaluable by this protocol. That is, the leaf nodes need to be
OverlapSquared
.Note
At every call of the returned function the internal state of the protocol changes.
- Parameters:
c (
ComputableNode
) – The quantum computable node to be measured and evaluated at every call of the returned function.compile_symbolic (
bool
, default:False
) – IfTrue
, circuits are immediately built and compiled symbolically. Calling the returned function substitutes symbols, runs circuits, and evaluates the output. IfFalse
, circuits are built and compiled only when the returned function is called and parameters are provided. Note that circuits may be deeper whencompile_symbolic=True
, because circuit compilation cannot perform optimizations based on numerical parameter values. The advantage of this case is that compilation only takes place once.args (
Any
)kwargs (
Any
)
- Returns:
Callable
[[Union
[SymbolDict
,Dict
]],Any
] – A function that takes the parameters, builds and measures the necessary circuits, and returns the evaluated result. If the result is not afloat
, it returnsmath.nan
.
- get_shots()
Returns the number shots to be used for each circuit.
- property is_built: bool
Boolean flag indicating if the instance has been built.
- Returns:
True
if thebuild()
method has been successfully invoked, otherwiseFalse
.
- property is_numeric: bool
Boolean flag indicating if the measurement circuits contain free symbols.
- Returns:
False
if any built measurement circuit contains unsubstituted symbols, otherwiseTrue
.
- property is_run: bool
Boolean flag indicating if the instance has been run.
- Returns:
True
if therun()
method has been successfully invoked, otherwiseFalse
.
- property is_symbolic: bool
Boolean flag indicating if the measurement circuits contain free symbols.
- Returns:
True
if any built measurement circuit contains unsubstituted symbols, otherwiseFalse
.
- launch(*args, **kwargs)
Launch the circuits to the backend and return the handles for the results.
This method processes all the circuits and returns a list of
ResultHandle
objects representing the handles for the results.- Parameters:
- Returns:
List
[ResultHandle
] – A list of pytketResultHandle
objects representing the handles for the launched circuits.
- classmethod load(file, *args, **kwargs)
Load a pickled object from a file.
- Parameters:
- Returns:
TypeVar
(T
, bound= PartiallyPickleable) – An instance of the class with its state loaded from the pickled data.
- classmethod loads(pickled_data, *args, **kwargs)
Load a pickled object from a bytes object.
- Parameters:
- Returns:
TypeVar
(T
, bound= PartiallyPickleable) – An instance of the class with its state loaded from the pickled data.
- rebuild(*args, **kwargs)
Rebuild the internal data structure.
It is equivalent to
clear().build(*args, **kwargs)
.
- retrieve(source, **kwargs)
Retrieve distributions from the backend for the given source.
If the
source
is a list of pytketResultHandle
, the distributions are retrieved usingself.backend.get_results()
method. If thesource
is a list of pytketBackendResult
, it is assumed that the results are already provided.- Parameters:
- Returns:
TypeVar
(T
, bound= BaseOverlapSquaredProtocol) – Returns self instance.
- run(*args, **kwargs)
Run the protocol and waiting for the results.
This method executes the following steps: 1. Launches the measurement circuits to obtain the circuit handles. 2. Retrieves the measurement distributions using the circuit handles.
- class DestructiveSwapTest(backend, n_shots=8000)
Bases:
BaseOverlapSquaredProtocol
Calculate the overlap squared with the destructive swap test.
Based on https://arxiv.org/abs/1303.6814. Prepares both bra and ket states in parallel and performs a destructive swap test i.e. no ancilla qubit is required. The test succeeds when a bitwise AND between the output bra and ket state registers has even parity. The probability of success is given by \(\frac{1}{2}(1+|\langle{\psi|\phi}\rangle|^2)\).
The bra state register is used as the control, while the ket register is the target.
Supports calculation of overlap squared of the form: \(|\langle\psi|cP|\phi\rangle|^2\), where \(P\) is a Pauli word and \(c\) is a numeric constant.
- Parameters:
backend (
Backend
) – The backend to use for quantum computations.n_shots (
int
, default:8000
) – Number of shots to perform.
- build(parameters, bra_state, ket_state, kernel=None, optimisation_level=1)
Builds the necessary circuits and measurement data.
Note
Any coefficient in the operator kernel is ignored.
- Parameters:
parameters (
Union
[SymbolDict
,Dict
]) – Parameter values for the circuits.bra_state (
GeneralAnsatz
) – Left-hand state.ket_state (
GeneralAnsatz
) – Right-hand state.kernel (
Union
[QubitOperator
,QubitOperatorString
,None
], default:None
) – Optional operator kernel. Must be a single Pauli string.optimization_level – Passed as the
optimisation_level
arg to the backend’sget_compiled_circuits()
method.optimisation_level (
int
, default:1
)
- Returns:
TypeVar
(T
, bound= BaseOverlapSquaredProtocol) – Self instance after building the necessary circuits and measurement data.
- build_from(parameters, computable, exclude=None)
Builds the protocol based on given parameters and computable expression.
This method walks over the computable expression tree and calls the
build()
method when it encounters a node of typeOverlapSquared
.- Parameters:
parameters (
Union
[SymbolDict
,Dict
]) – Parameters for building.computable (
ComputableNode
) – A root node of a computable expression tree, simply it is a computable expression.exclude (
Optional
[Callable
[[ComputableNode
],bool
]], default:None
) – Optional callable function to exclude certain nodes from processing.
- Returns:
TypeVar
(T
, bound= BaseOverlapSquaredProtocol) – Returns the modified instance after building.
- classmethod build_protocols_from(parameters, computable, exclude=None, *args, **kwargs)
Build a list of protocols based on the given parameters and computable expression.
- This method walks over the computable expression tree and collects leaf nodes of type:
After it has walked over the tree, it creates an instance of this protocol for each distinct bra, ket, kernel trio and calls the
build()
method. It collects all created protocols into aProtocolList
object to be returned.- Parameters:
parameters (
Union
[SymbolDict
,Dict
]) – Values for the parameters in the computable expression.computable (
ComputableNode
) – A root node of a computable expression tree.exclude (
Optional
[Callable
[[ComputableNode
],bool
]], default:None
) – Optional callable function to exclude certain nodes from processing.*args – Arguments passed to the constructor of the overlap squared protocol.
**kwargs – Keyword arguments passed to the constructor of the overlap squared protocol.
- Returns:
ProtocolList
– A list, containing all the newly instantiated and built protocols.
- circuit: Optional[Circuit]
- clear()
Resets the internal state of the object by clearing all stored data.
This method clears all stored data including state hashes, operator hashes, measurement setups, parameters, and associated dataframes and circuits.
- Returns:
TypeVar
(T
, bound= BaseOverlapSquaredProtocol) – self.
- cost()
Calculate a simple cost metric running the protocol.
The cost is calculated as the sum of the depth of each circuit multiplied by the number of shots.
- Returns:
int
– The cost value as an integer.
- credits(syntax_checker=None, use_websocket=None)
Evaluate an approximate cost for the measurement circuits built in Quantinuum credits.
Syntax checker will usually be automatically selected, but in some cases needs to be provided. If the measurement circuits are not built yet, the credits will be zero.
Note
This works only with
QuantinuumBackend
compatible backends.
- dataframe_circuit_shot()
Create a pandas
DataFrame
with circuit, shot, and depth information.- Returns:
DataFrame
– A pandasDataFrame
containing the circuit, shot, and depth information.
- dump(file)
Save the object to a file using pickle.
- dumps()
Returns the object pickled as a bytes object.
- Returns:
bytes
– The object’s state pickled as a bytes object.
- evaluate_overlap_squared(bra_state, ket_state, kernel)
Evaluates the overlap squared for given states and kernel.
- Parameters:
bra_state (
GeneralAnsatz
) – Left-hand state.ket_state (
GeneralAnsatz
) – Right-hand state.kernel (
Union
[QubitOperator
,QubitOperatorString
]) – Overlap kernel. Must be a single Pauli string.
Note
Input states and pauli string in the kernel need to match with the states and pauli string the circuit was built for to correctly interpret the circuit output distribution.
- Returns:
Overlap squared.
- get_circuits()
Returns the quantum circuits built for this protocol.
- Returns:
List
[Circuit
] – List of circuits.
- get_circuitshots()
Generate the circuit shot pairs.
- Yields:
Pair of circuit and the associated number of shots.
- Return type:
Iterator
[CircuitShots
]
- get_evaluator(allow_partial=False)
Returns an evaluator function to evaluate quantum computables.
This method creates and returns a function (evaluator) that takes in a specific quantum computable and evaluates it based on its type.
Quantum computables the returned evaluator can handle:
- Parameters:
allow_partial (
bool
, default:False
) – IfFalse
, evaluation will fail when an unsupported computable node is encountered. IfTrue
, unsupported nodes will be skipped.- Raises:
NotImplementedError – If an unsupported computable is encountered, and
allow_partial==False
.
Note
This evaluator works for quantum computables the protocol has been built from.
- Returns:
Callable
[[Evaluatable
],Union
[Evaluatable
,Any
]] – A function that can evaluate quantum computables. If a computable is supported by this protocol, it is computed; otherwise, it returns the computable itself.
- get_runner(c, compile_symbolic=False, *args, **kwargs)
Returns an end-to-end executor function for a quantum computable.
Note
All nodes in the quantum computable must be evaluable by this protocol. That is, the leaf nodes need to be
OverlapSquared
.Note
At every call of the returned function the internal state of the protocol changes.
- Parameters:
c (
ComputableNode
) – The quantum computable node to be measured and evaluated at every call of the returned function.compile_symbolic (
bool
, default:False
) – IfTrue
, circuits are immediately built and compiled symbolically. Calling the returned function substitutes symbols, runs circuits, and evaluates the output. IfFalse
, circuits are built and compiled only when the returned function is called and parameters are provided. Note that circuits may be deeper whencompile_symbolic=True
, because circuit compilation cannot perform optimizations based on numerical parameter values. The advantage of this case is that compilation only takes place once.args (
Any
)kwargs (
Any
)
- Returns:
Callable
[[Union
[SymbolDict
,Dict
]],Any
] – A function that takes the parameters, builds and measures the necessary circuits, and returns the evaluated result. If the result is not afloat
, it returnsmath.nan
.
- get_shots()
Returns the number shots to be used for each circuit.
- property is_built: bool
Boolean flag indicating if the instance has been built.
- Returns:
True
if thebuild()
method has been successfully invoked, otherwiseFalse
.
- property is_numeric: bool
Boolean flag indicating if the measurement circuits contain free symbols.
- Returns:
False
if any built measurement circuit contains unsubstituted symbols, otherwiseTrue
.
- property is_run: bool
Boolean flag indicating if the instance has been run.
- Returns:
True
if therun()
method has been successfully invoked, otherwiseFalse
.
- property is_symbolic: bool
Boolean flag indicating if the measurement circuits contain free symbols.
- Returns:
True
if any built measurement circuit contains unsubstituted symbols, otherwiseFalse
.
- launch(*args, **kwargs)
Launch the circuits to the backend and return the handles for the results.
This method processes all the circuits and returns a list of
ResultHandle
objects representing the handles for the results.- Parameters:
- Returns:
List
[ResultHandle
] – A list of pytketResultHandle
objects representing the handles for the launched circuits.
- classmethod load(file, *args, **kwargs)
Load a pickled object from a file.
- Parameters:
- Returns:
TypeVar
(T
, bound= PartiallyPickleable) – An instance of the class with its state loaded from the pickled data.
- classmethod loads(pickled_data, *args, **kwargs)
Load a pickled object from a bytes object.
- Parameters:
- Returns:
TypeVar
(T
, bound= PartiallyPickleable) – An instance of the class with its state loaded from the pickled data.
- rebuild(*args, **kwargs)
Rebuild the internal data structure.
It is equivalent to
clear().build(*args, **kwargs)
.
- retrieve(source, **kwargs)
Retrieve distributions from the backend for the given source.
If the
source
is a list of pytketResultHandle
, the distributions are retrieved usingself.backend.get_results()
method. If thesource
is a list of pytketBackendResult
, it is assumed that the results are already provided.- Parameters:
- Returns:
TypeVar
(T
, bound= BaseOverlapSquaredProtocol) – Returns self instance.
- run(*args, **kwargs)
Run the protocol and waiting for the results.
This method executes the following steps: 1. Launches the measurement circuits to obtain the circuit handles. 2. Retrieves the measurement distributions using the circuit handles.
- class SwapTest(backend, n_shots=8000)
Bases:
BaseOverlapSquaredProtocol
Calculate the overlap squared with the canonical swap test.
Input states \(|\psi\rangle\) and \(|\phi\rangle\) are prepared in parallel alongside an ancilla qubit to generate the state \(|0, \psi, \phi\rangle\). A swap operation between \(\psi\) and \(\phi\) is controlled on the ancilla and wrapped by Hadamard gates so that the probability of measuring \(|0\rangle\) on the ancilla is given by \(\frac{1}{2}(1+|\langle\psi|\phi\rangle|^2)\). See https://en.wikipedia.org/wiki/Swap_test.
Supports calculation of overlap squared of the form: \(|\langle\psi|cP|\phi\rangle|^2\), where \(P\) is a Pauli word and \(c\) is a numeric constant.
- Parameters:
backend (
Backend
) – The backend to use for quantum computations.n_shots (
int
, default:8000
) – Number of shots to perform.
- build(parameters, bra_state, ket_state, kernel=None, optimisation_level=1)
Builds the necessary circuits and measurement data.
Note
Any coefficient in the operator kernel is ignored.
- Parameters:
parameters (
Union
[SymbolDict
,Dict
]) – Parameter values for the circuits.bra_state (
GeneralAnsatz
) – Left-hand state.ket_state (
GeneralAnsatz
) – Right-hand state.kernel (
Union
[QubitOperator
,QubitOperatorString
,None
], default:None
) – Optional operator kernel. Must be a single Pauli string.optimization_level – Passed as the
optimisation_level
arg to the backend’sget_compiled_circuits()
method.optimisation_level (
int
, default:1
)
- Returns:
TypeVar
(T
, bound= BaseOverlapSquaredProtocol) – Self instance after building the necessary circuits and measurement data.
- build_from(parameters, computable, exclude=None)
Builds the protocol based on given parameters and computable expression.
This method walks over the computable expression tree and calls the
build()
method when it encounters a node of typeOverlapSquared
.- Parameters:
parameters (
Union
[SymbolDict
,Dict
]) – Parameters for building.computable (
ComputableNode
) – A root node of a computable expression tree, simply it is a computable expression.exclude (
Optional
[Callable
[[ComputableNode
],bool
]], default:None
) – Optional callable function to exclude certain nodes from processing.
- Returns:
TypeVar
(T
, bound= BaseOverlapSquaredProtocol) – Returns the modified instance after building.
- classmethod build_protocols_from(parameters, computable, exclude=None, *args, **kwargs)
Build a list of protocols based on the given parameters and computable expression.
- This method walks over the computable expression tree and collects leaf nodes of type:
After it has walked over the tree, it creates an instance of this protocol for each distinct bra, ket, kernel trio and calls the
build()
method. It collects all created protocols into aProtocolList
object to be returned.- Parameters:
parameters (
Union
[SymbolDict
,Dict
]) – Values for the parameters in the computable expression.computable (
ComputableNode
) – A root node of a computable expression tree.exclude (
Optional
[Callable
[[ComputableNode
],bool
]], default:None
) – Optional callable function to exclude certain nodes from processing.*args – Arguments passed to the constructor of the overlap squared protocol.
**kwargs – Keyword arguments passed to the constructor of the overlap squared protocol.
- Returns:
ProtocolList
– A list, containing all the newly instantiated and built protocols.
- circuit: Optional[Circuit]
- clear()
Resets the internal state of the object by clearing all stored data.
This method clears all stored data including state hashes, operator hashes, measurement setups, parameters, and associated dataframes and circuits.
- Returns:
TypeVar
(T
, bound= BaseOverlapSquaredProtocol) – self.
- cost()
Calculate a simple cost metric running the protocol.
The cost is calculated as the sum of the depth of each circuit multiplied by the number of shots.
- Returns:
int
– The cost value as an integer.
- credits(syntax_checker=None, use_websocket=None)
Evaluate an approximate cost for the measurement circuits built in Quantinuum credits.
Syntax checker will usually be automatically selected, but in some cases needs to be provided. If the measurement circuits are not built yet, the credits will be zero.
Note
This works only with
QuantinuumBackend
compatible backends.
- dataframe_circuit_shot()
Create a pandas
DataFrame
with circuit, shot, and depth information.- Returns:
DataFrame
– A pandasDataFrame
containing the circuit, shot, and depth information.
- dump(file)
Save the object to a file using pickle.
- dumps()
Returns the object pickled as a bytes object.
- Returns:
bytes
– The object’s state pickled as a bytes object.
- evaluate_overlap_squared(bra_state, ket_state, kernel)
Evaluates the overlap squared for given states and kernel.
- Parameters:
bra_state (
GeneralAnsatz
) – Left-hand state.ket_state (
GeneralAnsatz
) – Right-hand state.kernel (
Union
[QubitOperator
,QubitOperatorString
]) – Overlap kernel. Must be a single Pauli string.
Note
Input states and pauli string in the kernel need to match with the states and pauli string the circuit was built for to correctly interpret the circuit output distribution.
- Returns:
Overlap squared.
- get_circuits()
Returns the quantum circuits built for this protocol.
- Returns:
List
[Circuit
] – List of circuits.
- get_circuitshots()
Generate the circuit shot pairs.
- Yields:
Pair of circuit and the associated number of shots.
- Return type:
Iterator
[CircuitShots
]
- get_evaluator(allow_partial=False)
Returns an evaluator function to evaluate quantum computables.
This method creates and returns a function (evaluator) that takes in a specific quantum computable and evaluates it based on its type.
Quantum computables the returned evaluator can handle:
- Parameters:
allow_partial (
bool
, default:False
) – IfFalse
, evaluation will fail when an unsupported computable node is encountered. IfTrue
, unsupported nodes will be skipped.- Raises:
NotImplementedError – If an unsupported computable is encountered, and
allow_partial==False
.
Note
This evaluator works for quantum computables the protocol has been built from.
- Returns:
Callable
[[Evaluatable
],Union
[Evaluatable
,Any
]] – A function that can evaluate quantum computables. If a computable is supported by this protocol, it is computed; otherwise, it returns the computable itself.
- get_runner(c, compile_symbolic=False, *args, **kwargs)
Returns an end-to-end executor function for a quantum computable.
Note
All nodes in the quantum computable must be evaluable by this protocol. That is, the leaf nodes need to be
OverlapSquared
.Note
At every call of the returned function the internal state of the protocol changes.
- Parameters:
c (
ComputableNode
) – The quantum computable node to be measured and evaluated at every call of the returned function.compile_symbolic (
bool
, default:False
) – IfTrue
, circuits are immediately built and compiled symbolically. Calling the returned function substitutes symbols, runs circuits, and evaluates the output. IfFalse
, circuits are built and compiled only when the returned function is called and parameters are provided. Note that circuits may be deeper whencompile_symbolic=True
, because circuit compilation cannot perform optimizations based on numerical parameter values. The advantage of this case is that compilation only takes place once.args (
Any
)kwargs (
Any
)
- Returns:
Callable
[[Union
[SymbolDict
,Dict
]],Any
] – A function that takes the parameters, builds and measures the necessary circuits, and returns the evaluated result. If the result is not afloat
, it returnsmath.nan
.
- get_shots()
Returns the number shots to be used for each circuit.
- property is_built: bool
Boolean flag indicating if the instance has been built.
- Returns:
True
if thebuild()
method has been successfully invoked, otherwiseFalse
.
- property is_numeric: bool
Boolean flag indicating if the measurement circuits contain free symbols.
- Returns:
False
if any built measurement circuit contains unsubstituted symbols, otherwiseTrue
.
- property is_run: bool
Boolean flag indicating if the instance has been run.
- Returns:
True
if therun()
method has been successfully invoked, otherwiseFalse
.
- property is_symbolic: bool
Boolean flag indicating if the measurement circuits contain free symbols.
- Returns:
True
if any built measurement circuit contains unsubstituted symbols, otherwiseFalse
.
- launch(*args, **kwargs)
Launch the circuits to the backend and return the handles for the results.
This method processes all the circuits and returns a list of
ResultHandle
objects representing the handles for the results.- Parameters:
- Returns:
List
[ResultHandle
] – A list of pytketResultHandle
objects representing the handles for the launched circuits.
- classmethod load(file, *args, **kwargs)
Load a pickled object from a file.
- Parameters:
- Returns:
TypeVar
(T
, bound= PartiallyPickleable) – An instance of the class with its state loaded from the pickled data.
- classmethod loads(pickled_data, *args, **kwargs)
Load a pickled object from a bytes object.
- Parameters:
- Returns:
TypeVar
(T
, bound= PartiallyPickleable) – An instance of the class with its state loaded from the pickled data.
- rebuild(*args, **kwargs)
Rebuild the internal data structure.
It is equivalent to
clear().build(*args, **kwargs)
.
- retrieve(source, **kwargs)
Retrieve distributions from the backend for the given source.
If the
source
is a list of pytketResultHandle
, the distributions are retrieved usingself.backend.get_results()
method. If thesource
is a list of pytketBackendResult
, it is assumed that the results are already provided.- Parameters:
- Returns:
TypeVar
(T
, bound= BaseOverlapSquaredProtocol) – Returns self instance.
- run(*args, **kwargs)
Run the protocol and waiting for the results.
This method executes the following steps: 1. Launches the measurement circuits to obtain the circuit handles. 2. Retrieves the measurement distributions using the circuit handles.
Protocols for Overlaps
- class HadamardTestOverlap(backend, shots_per_circuit, direct=False, pauli_partition_strategy=PauliPartitionStrat.NonConflictingSets, pauli_colour_method=GraphColourMethod.Lazy)
Bases:
BaseOverlapProtocol
Calculates the overlap of two states using a specialized Hadamard test.
Computes the real or imaginary part of \(\langle A | B \rangle\) where \(|A\rangle = U_A |0\rangle\) using the “linear combination of unitaries” method from https://journals.aps.org/pra/abstract/10.1103/PhysRevA.99.032331 (see figure 2). For
direct=True
, this method uses the approach from https://iopscience.iop.org/article/10.1088/1367-2630/ab867b to combine ancilla and state register measurements to compute overlaps with kernels.- Parameters:
backend (
Backend
) – The backend to use for quantum computations.shots_per_circuit (
int
) – Number of shots to perform.direct (
bool
, default:False
) – Relevant for overlaps with non-identity kernels. IfTrue
, Pauli words are divided into simultaneously measurable sets and computed using direct measurement of expectation values on the state register.pauli_partition_strategy (
Optional
[PauliPartitionStrat
], default:PauliPartitionStrat.NonConflictingSets
) – Fordirect=True
. Strategy to partition Pauli operators.pauli_colour_method (
Optional
[GraphColourMethod
], default:GraphColourMethod.Lazy
) – Fordirect=True
. Method to perform graph colouring.
- build(parameters, bra_state, ket_state, *operators, component, optimisation_level=1)
Builds and compiles the necessary circuits for computing an overlap.
- Parameters:
parameters (
Union
[SymbolDict
,Dict
]) – Parameter values for the circuits.bra_state (
GeneralAnsatz
) – Left-hand state.ket_state (
GeneralAnsatz
) – Right-hand state.operators (
QubitOperator
) – Operator kernel, default is the identity. Coefficients in the kernel are ignored; only the Pauli strings are used in circuit construction.component (
Union
[str
,NumberType
]) – Component of overlap to measure:real
,imag
, orcomplex
.optimisation_level (
int
, default:1
) – Passed to the backend’sget_compiled_circuits()
method.
- Returns:
BaseOverlapProtocol
– Self instance.
- build_from(parameters, computable, exclude=None)
Builds the protocol based on given parameters and computable expression.
This method walks over the computable expression tree and calls the
build()
method for leaves of typeOverlap
,OverlapReal
, andOverlapImag
.- Parameters:
- Returns:
BaseOverlapProtocol
– The modified instance after building.
- classmethod build_protocols_from(parameters, computable, exclude=None, *args, **kwargs)
Build a list of protocols based on the given parameters and computable expression.
This method walks over the computable expression tree and collects all qubit operator kernels appearing in nodes of type:
After it has walked over the tree, it creates an instance of
HadamardTestOverlap
for each distinct bra, ket pair of states, and calls thebuild()
method with the kernel operators associated with the states. It collects all created protocols into aProtocolList
object to be returned.- Parameters:
parameters (
Union
[SymbolDict
,Dict
]) – Values for the parameters in the computable expression.computable (
ComputableNode
) – A root node of a computable expression tree.exclude (
Optional
[Callable
[[ComputableNode
],bool
]], default:None
) – Optional callable function to exclude certain nodes from processing.*args – Arguments passed to the constructor of
HadamardTestOverlap
.**kwargs – Keyword arguments passed to the constructor of
HadamardTestOverlap
.
- Returns:
ProtocolList
– A list, containing all the newly instantiated and built protocols.
- circuits: Optional[List[Circuit]]
- clear()
Resets the internal state of the object by clearing all stored data.
This method clears all stored data including state hashes, operator hashes, measurement setups, parameters, and associated dataframes and circuits.
- Returns:
BaseOverlapProtocol
– self.
- cost()
Calculate a simple cost metric running the protocol.
The cost is calculated as the sum of the depth of each circuit multiplied by the number of shots.
- Returns:
int
– The cost value as an integer.
- credits(syntax_checker=None, use_websocket=None)
Evaluate an approximate cost for the measurement circuits built in Quantinuum credits.
Syntax checker will usually be automatically selected, but in some cases needs to be provided. If the measurement circuits are not built yet, the credits will be zero.
Note
This works only with
QuantinuumBackend
compatible backends.
- dataframe_circuit_shot()
Create a pandas
DataFrame
with circuit, shot, and depth information.- Returns:
DataFrame
– A pandasDataFrame
containing the circuit, shot, and depth information.
- evaluate_overlap(bra_state, ket_state, kernel={(): 1.0})
Evaluates the overlap for given states and kernel.
This method can only be performed if, prior to calling this method, the protocol has been built for
component='complex'
, with the same input states and kernel (or other operators composed of the same Pauli strings), and the protocol has also been run.- Parameters:
bra_state (
GeneralAnsatz
) – Left-hand state.ket_state (
GeneralAnsatz
) – Right-hand state.kernel (
QubitOperator
, default:{(): 1.0}
) – Operator kernel.
- Returns:
complex
– Real part of the overlap.
- evaluate_overlap_imag(bra_state, ket_state, kernel={(): 1.0})
Evaluates the imaginary part of the overlap for given states and kernel.
This method can only be performed if, prior to calling this method, the protocol has been built for
component='imag'
or'complex'
, with the same input states and kernel (or other operators composed of the same Pauli strings), and the protocol has also been run.- Parameters:
bra_state (
GeneralAnsatz
) – Left-hand state.ket_state (
GeneralAnsatz
) – Right-hand state.kernel (
QubitOperator
, default:{(): 1.0}
) – Operator kernel.
- Returns:
float
– Real part of the overlap.
- evaluate_overlap_real(bra_state, ket_state, kernel={(): 1.0})
Evaluates the real part of the overlap for given states and kernel.
This method can only be performed if, prior to calling this method, the protocol has been built for
component='real'
or'complex'
, with the same input states and kernel (or other operators composed of the same Pauli strings), and the protocol has also been run.- Parameters:
bra_state (
GeneralAnsatz
) – Left-hand state.ket_state (
GeneralAnsatz
) – Right-hand state.kernel (
QubitOperator
, default:{(): 1.0}
) – Operator kernel.
- Returns:
float
– Real part of the overlap.
- get_circuits()
Returns the quantum circuits built for this protocol.
- Returns:
List
[Circuit
] – List of circuits.
- get_circuitshots()
Generate the circuit shot pairs.
- Yields:
Pair of circuit and the associated number of shots.
- Return type:
Iterator
[CircuitShots
]
- get_evaluator(allow_partial=False)
Returns an evaluator function to evaluate quantum computables.
This method creates and returns a function (evaluator) that takes in a specific quantum computable and evaluates it based on its type.
Quantum computables the returned evaluator can handle:
- Parameters:
allow_partial (
bool
, default:False
) – IfFalse
, evaluation will fail when an unsupported computable node is encountered. IfTrue
, unsupported nodes will be skipped.
Note
This evaluator works for quantum computables the protocol has been built from.
- Raises:
NotImplementedError – If an unsupported computable is encountered, and
allow_partial==False
.- Returns:
Callable
[[Evaluatable
],Union
[Evaluatable
,Any
]] – A function that can evaluate quantum computables. If a computable is supported by this protocol, it is computed; otherwise, it returns the computable itself.
- get_runner(qc, compile_symbolic=False, *args, **kwargs)
Returns an end-to-end executor function for a quantum computable.
All nodes in the quantum computable must be evaluable by this protocol. That is, the leaf nodes need to be of one of the supported types:
Note
At every call of the returned function the internal state of the protocol changes.
- Parameters:
qc (
ComputableNode
) – The quantum computable node to be measured and evaluated at every call of the returned function.compile_symbolic (
bool
, default:False
) – IfTrue
, circuits are immediately built and compiled symbolically. Calling the returned function substitutes symbols, runs circuits, and evaluates the output. IfFalse
, circuits are built and compiled only when the returned function is called and parameters are provided. Note that circuits may be deeper whencompile_symbolic=True
, because circuit compilation cannot perform optimizations based on numerical parameter values. The advantage of this case is that compilation only takes place once.args (
Any
)kwargs (
Any
)
- Returns:
Callable
[[Union
[SymbolDict
,Dict
]],Any
] – A function that takes the parameters, builds and measures the necessary circuits, and returns the evaluated result. If the result is not afloat
, it returnsmath.nan
.
- get_shots()
Returns the number shots to be used for each circuit.
- property is_built: bool
Boolean flag indicating if the instance has been built.
- Returns:
True
if thebuild()
method has been successfully invoked, otherwiseFalse
.
- property is_numeric: bool
Boolean flag indicating if the measurement circuits contain free symbols.
- Returns:
False
if any built measurement circuit contains unsubstituted symbols, otherwiseTrue
.
- property is_run: bool
Boolean flag indicating if the instance has been run.
- Returns:
True
if therun()
method has been successfully invoked, otherwiseFalse
.
- property is_symbolic: bool
Boolean flag indicating if the measurement circuits contain free symbols.
- Returns:
True
if any built measurement circuit contains unsubstituted symbols, otherwiseFalse
.
- launch(*args, **kwargs)
Launch the circuits to the backend and return the handles for the results.
This method processes all the circuits and returns a list of
ResultHandle
objects representing the handles for the results.- Parameters:
- Returns:
List
[ResultHandle
] – A list of pytketResultHandle
objects representing the handles for the launched circuits.
- rebuild(*args, **kwargs)
Rebuild the internal data structure.
It is equivalent to
clear().build(*args, **kwargs)
.
- retrieve(source, **kwargs)
Retrieve distributions from the backend for the given source.
If the
source
is a list of pytketResultHandle
, the distributions are retrieved usingself.backend.get_results()
method. If thesource
is a list of pytketBackendResult
, it is assumed that the results are already provided.- Parameters:
- Returns:
BaseOverlapProtocol
– Returns self instance.
- run(*args, **kwargs)
Run the protocol and waiting for the results.
This method executes the following steps: 1. Launches the measurement circuits to obtain the circuit handles. 2. Retrieves the measurement distributions using the circuit handles.
- class FactorizedOverlap(backend, shots_per_circuit, direct=False, pauli_partition_strategy=PauliPartitionStrat.NonConflictingSets, pauli_colour_method=GraphColourMethod.Lazy)
Bases:
BaseOverlapProtocol
Abstract base class for specialized overlap protocols between ansatzes that factorize into a reference and a number conserving unitary.
Computes the real or imaginary part of \(\langle A | B \rangle\) where \(|A\rangle = U_A U_\text{ref}|0\rangle\) and \(|B\rangle = U_B U_\text{ref}|0\rangle\) in the manner shown in Figures 1 and 2 of https://journals.aps.org/prxquantum/abstract/10.1103/PRXQuantum.4.030307. These protocols make use of the property that \(U_A |0\rangle = |0\rangle\) to avoid the potentially large controlled state unitaries involved in e.g.
HadamardTestOverlap
.Warning
Only ansatzes with the property that \(U_A |0\rangle = |0\rangle\) are compatible with protocols of this type.
- Parameters:
- build(parameters, bra_state, ket_state, *operators, component, optimisation_level=1)
Builds and compiles the necessary circuits for computing an overlap.
- Parameters:
parameters (
Union
[SymbolDict
,Dict
]) – Parameter values for the circuits.bra_state (
GeneralAnsatz
) – Left-hand state.ket_state (
GeneralAnsatz
) – Right-hand state.operators (
QubitOperator
) – Operator kernel, default is the identity. Coefficients in the kernel are ignored; only the Pauli strings are used in circuit construction.component (
Union
[str
,NumberType
]) – Component of overlap to measure:real
,imag
, orcomplex
.optimisation_level (
int
, default:1
) – Passed to the backend’sget_compiled_circuits()
method.
- Returns:
BaseOverlapProtocol
– Self instance.