`squlearn.util`.OpTree

class squlearn.util.OpTree

Static class containing functions for working with OpTrees objects.

class OpTreeDerivative

Static class for differentiation of a OpTrees, circuits, or operators.

Calculates the derivative of a OpTree (or circuit) w.r.t. to a parameter or a list of parameters.

Parameters:

element (Union[OpTreeNodeBase, OpTreeLeafCircuit, QuantumCircuit]) – OpTree (or circuit) to be differentiated.
parameters (Union[ParameterExpression, List[ParameterExpression], ParameterVector]) – Parameter(s) w.r.t. the OpTree is differentiated

Returns:

The derivative of the OpTree (or circuit) in OpTree form.

Calculates the derivative of a OpTree (or circuit) w.r.t. to a parameter or a list of parameters.

Second implementation, in which the derivative is calculated during the recursive derivative computation.

Parameters:

element (Union[OpTreeNodeBase, OpTreeLeafCircuit, QuantumCircuit]) – OpTree (or circuit) to be differentiated.
parameters (Union[ParameterExpression, List[ParameterExpression], ParameterVector]) – Parameter(s) w.r.t. the OpTree is differentiated

Returns:

The derivative of the OpTree (or circuit) in OpTree form.

static transpile_to_supported_instructions(circuit: QuantumCircuit, supported_gates: Set[str] = {'cx', 'cy', 'cz', 'ecr', 'h', 'p', 'rx', 'ry', 'rz', 's', 'sdg', 'sx', 't', 'tdg', 'x', 'y', 'z'}) → QuantumCircuit

Function for transpiling a circuit to a supported instruction set for gradient calculation.

Parameters:

circuit (QuantumCircuit) – Circuit to transpile.
supported_gates (Set[str]) – Set of supported gates (Default set given).

Returns:

Circuit which is transpiled to the supported instruction set.

class OpTreeEvaluate

Static class for evaluating OpTree structures with Qiskit’s primitives.

static evaluate_tree_with_estimator(expectation_tree: OpTreeNodeBase | OpTreeExpectationValue, dictionary: List[dict] | dict, estimator: BaseEstimatorV1 | BaseEstimatorV2, detect_duplicates: bool = False) → float | ndarray

Evaluate a expectation tree with an estimator.

The OpTree can only contain expectation values, and the estimator is used to evaluate the expectation values. Dictionary can be a list of dictionaries, in which case the function evaluates the expectation value for all combinations of the dictionaries. The function also checks if the same expectation value occurs multiple times, and only adds it once to the evaluation list. This can be turned off with the detect_duplicates flag.

Parameters:

expectation_tree (Union[OpTreeNodeBase,OpTreeExpectationValue]) – The expectation OpTree to be evaluated.
dictionary (Union[List(dict),dict]) – The dictionary that contains the parameter and their values. Can be list for the evaluation of multiple dictionaries.
estimator (Union[BaseEstimatorV1,BaseEstimatorV2]) – The estimator primitive that is used for the evaluation.
detect_expectation_duplicates (bool, optional) – If True, duplicate expectation values are detected and only evaluated once. Defaults to True.

Returns:

The expectation value of the expectation OpTree as a numpy array.

static evaluate_tree_with_sampler(expectation_tree: OpTreeNodeBase | OpTreeExpectationValue, dictionary: List[dict] | dict, sampler: BaseSamplerV1 | BaseSamplerV2, detect_duplicates: bool = True)

Evaluate a expectation tree with a sampler.

The OpTree can only contain expectation values, and the sampler is used to evaluate the expectation values. Dictionary can be a list of dictionaries, in which case the function evaluates the expectation value for all combinations of the dictionaries. The function also checks if the same circuit or expectation value occurs multiple times, and only adds it once to the evaluation list. This can be turned off with the detect_duplicates flag.

Parameters:

expectation_tree (Union[OpTreeNodeBase, OpTreeExpectationValue]) – The expectation OpTree to be evaluated.
dictionary (Union[List(dict),dict]) – The dictionary that contains the parameter and their values. Can be list for the evaluation of multiple dictionaries.
sampler (Union[BaseSamplerV1, BaseSamplerV2]) – The sampler primitive that is used for the evaluation.
detect_expectation_duplicates (bool, optional) – If True, duplicate expectation values and circuits are detected and only evaluated once.

Returns:

The expectation value of the expectation OpTree as a numpy array.

Function for evaluating the expectation value with the estimator primitive.

Inputted are a circuit and operator in OpTree format, and a dictionaries that contain the values for the parameters in the circuit and operator. Dictionary can be a list of dictionaries, in which case the function evaluates the expectation value for all combinations of the dictionaries, or if dictionaries_combined==True, the function evaluates the expectation value for the same index of the dictionaries.

The function also checks if the same circuit or operator occurs multiple times, and only adds it once to the evaluation list. This can be turned off with the detect_duplicates flag.

Parameters:

circuit (Union[OpTreeNodeBase, OpTreeLeafCircuit, QuantumCircuit]) – The circuit or OpTree with circuits to be evaluated.
operator (Union[OpTreeNodeBase, OpTreeLeafOperator, SparsePauliOp]) – The operator or OpTree in the expectation values.
dictionary_circuit (Union[dict, List[dict]]) – The dictionary or list of dictionaries that contain the values for the parameters in the circuit (or the circuit OpTree).
dictionary_operator (Union[dict, List[dict]]) – The dictionary or list of dictionaries that contain the values for the parameters in the operator (or the operator OpTree).
estimator (Union[BaseEstimatorV1,BaseEstimatorV2]) – The estimator primitive that is used for the evaluation.
dictionaries_combined (bool) – If True, the function evaluates the expectation value for the same index of the dictionaries (both have to be Lists). Defaults to False.
detect_duplicates (bool) – If True, the removes duplicate circuits and operators from the evaluation list. Defaults to True.

Returns:

The expectation value of the expectation values as a numpy array.

Function for evaluating the expectation value with the sampler primitive.

Inputted are a circuit and operator in OpTree format, and a dictionaries that contain the values for the parameters in the circuit and operator. Dictionary can be a list of dictionaries, in which case the function evaluates the expectation value for all combinations of the dictionaries, or if dictionaries_combined==True, the function evaluates the expectation value for the same index of the dictionaries.

The function also checks if the same circuit or operator occurs multiple times, and only adds it once to the evaluation list. This can be turned off with the detect_duplicates flag.

Parameters:

circuit (Union[OpTreeNodeBase, OpTreeLeafCircuit, QuantumCircuit]) – The circuit or OpTree with circuits to be evaluated.
operator (Union[OpTreeNodeBase, OpTreeLeafOperator, SparsePauliOp, OpTreeLeafMeasuredOperator]) – The operator or OpTree in the expectation values.
dictionary_circuit (Union[dict, List[dict]]) – The dictionary or list of dictionaries that contain the values for the parameters in the circuit (or the circuit OpTree).
dictionary_operator (Union[dict, List[dict]]) – The dictionary or list of dictionaries that contain the values for the parameters in the operator (or the operator OpTree).
sampler (Union[BaseSamplerV1, BaseSamplerV2]) – The sampler primitive that is used for the evaluation.
dictionaries_combined (bool) – If True, the function evaluates the expectation value for the same index of the dictionaries (both have to be Lists). Defaults to False.
detect_duplicates (bool) – If True, the removes duplicate circuits and operators from the evaluation list. Defaults to True.

Returns:

The expectation value of the expectation values as a numpy array.

static transform_to_zbasis(optree_element: OpTreeNodeBase | OpTreeOperator | OpTreeExpectationValue | SparsePauliOp, abelian_grouping: bool = True)

Function for transforming an OpTree structure to the Z basis.

This can be applied to OpTree structures that contain operators or expectation values. The function transforms the operators to the Z basis by adding measurement circuits.

Parameters:

optree_element (Union[OpTreeNodeBase, OpTreeLeafOperator, OpTreeLeafExpectationValue, SparsePauliOp]) – The OpTree structure to be transformed.
abelian_grouping (bool, optional) – If True, the operator is grouped into commuting terms. Defaults to True.

Returns:

The transformed OpTree structure.

static assign_parameters(element: OpTreeNodeBase | OpTreeCircuit | QuantumCircuit, dictionary, inplace: bool = False)

Assigns the parameters of the OpTree structure to the values in the dictionary.

Parameters:

element (Union[OpTreeNodeBase, OpTreeLeafCircuit, QuantumCircuit]) – The OpTree for which all parameters are assigned.
dictionary (dict) – The dictionary that contains the parameter names as keys and the parameter values as values.

Returns:

The OpTree structure with all parameters assigned, (copied if inplace=False)

derivative: alias of OpTreeDerivative

evaluate: alias of OpTreeEvaluate

Function that generates an expectation tree from a circuit tree and an operator tree.

The operator tree is applied to each leaf of the circuit tree and the resulting expectation values are returned as OpTreeExpectationValue.

Parameters:

circuit_tree (Union[OpTreeNodeBase, OpTreeLeafCircuit, QuantumCircuit]) – The circuit tree.
operator_tree (Union[OpTreeNodeBase, OpTreeLeafMeasuredOperator, OpTreeLeafOperator, SparsePauliOp]) – The operator tree.

Returns:

The combined tree with OpTreeExpectationValue at the leafs.

Returns the first leaf of the supplied OpTree.

Parameters:: element (Union[OpTreeNodeBase, OpTreeLeafBase, QuantumCircuit, SparsePauliOp]) – The OpTree.
Returns:: The first found leaf of the OpTree.

static get_num_nested_lists(tree: OpTreeElementBase) → int

Returns the number of nested lists in the OpTree.

Parameters:: tree (OpTreeElementBase) – The OpTree.
Returns:: The depth of the OpTree.
Return type:: int

static get_number_of_leafs(tree: OpTreeElementBase) → int

Returns the number of leafs of the OpTree.

Parameters:: tree (OpTreeElementBase) – The OpTree.
Returns:: The number of leafs of the OpTree.
Return type:: int

static get_tree_depth(tree: OpTreeElementBase) → int

Returns the depth of the OpTree.

Parameters:: tree (OpTreeElementBase) – The OpTree.
Returns:: The depth of the OpTree.
Return type:: int

static hash_circuit(circuit: QuantumCircuit) → tuple

Hashes a circuit using the qiskit _circuit_key function.

Parameters:: circuit (QuantumCircuit) – The circuit to be hashed.
Returns:: a tuple containing the circuit information that can be used for comparison.

static hash_operator(operator: SparsePauliOp) → tuple

Hashes an operator using the qiskit _observable_key function.

Parameters:: operator (SparsePauliOp) – The operator to be hashed.
Returns:: A tuple containing the operator information that can be used for comparison.

Function for simplifying an OpTree structure, the input is kept untouched.

Merges double sums and identifies identical branches or leafs in sums.

Parameters:: element (Union[OpTreeNodeBase, OpTreeLeafBase, QuantumCircuit, SparsePauliOp]) – The OpTree to be simplified.
Returns:: A simplified copy of the OpTree.