qtree package

qtree.qtree

Quantum decision trees.

class qtree.qtree.QTree(max_depth, quantum_backend=None, d_weight=1.0, s_weight=1.0, a_weight=1.0, pareto_fitness=False, score_func=None, dist_func=None, acc_func=None, swap_func=None, mcswap_func=None, mct_func=None, pop_size=10, cx_pb=0.2, mut_pb=0.2, mut_ind_pb=0.2, select_tournsize=3, max_generations=10, reuse_G_calc=True, mean_fits=True, random_state=None, evo_callback=None, remove_inactive_qubits=True, eliminate_first_swap=False, simultaneous_circuit_evaluation=False, include_id=False, block_form=False, use_barriers=False, logger=None)

Bases: QTreeBase

Main class for quantum decision classifiers.

Parameters:

• max_depth (int) – Maximum depth of the decision tree. A tree of depth 0 consists only of the root.

• quantum_backend (qiskit.providers.Backend or None) – Qiskit quantum backend used for all calculations. Can be either a simulator or an actual backend. If set to None, use AerSimulator(). Defaults to None.

• d_weight (float) – Hyperparameter of tree growth. Weight of the distance function for fitness calculation. Should be >= 0. Defaults to 1.0.

• s_weight (float) – Hyperparameter of tree growth. Weight of the score function for fitness calculation. Should be >= 0. Defaults to 1.0.

• a_weight (float) – Hyperparameter of tree growth. Weight of the accuracy function for fitness calculation. Should be >= 0. Defaults to 1.0.

• pareto_fitness (bool) – Hyperparameter of tree growth. Determines , how the three fitness function components are treated. If False, use scalarized fitness. If True, use multi-criteria fitness. Defaults to False.

• score_func (callable or None) – Hyperparameter of tree growth. The score function maps from class probabilities in a leaf to a scalar, i.e., [py1, py2, ...] -> float. The result measures the concentration of the distribution and is used as the first fitness function component. If set to None, use QTree.score_func_entropy. Defaults to None.

• dist_func (callable or None) – Hyperparameter of tree growth. The distance function maps from class probabilities in two leaves to a scalar, i.e., [py1, py2, ..., py1', py2', ..] -> float. The result measures the distance between two distributions and is used as the second fitness function component. If set to None, use QTree.dist_func_proba_dist_norm. Defaults to None.

• acc_func (callable or None) – Hyperparameter of tree growth. The accuracy function maps from leaf to a scalar, i.e., [py1, py2, ...] -> float. The result measures the quality of the tree prediction and is used as the third fitness function component. If set to None, use QTree.acc_func_acc_balanced. Defaults to None.

• swap_func (callable or None) – Function (qiskit.Circuit, q1, q2 -> None) that defines how a swap gate between two qubits with indices q1 and q2 is realized. If set to None, the callable is used, see quant.QTreeCircuitManager. Defaults to None.

• mcswap_func (callable or None) – Function (qiskit.Circuit, q1, q2, qc_list, mct_func -> None) that defines how a multi-controlled swap gate between two qubits with indices q1 and q2 controlled by the qubits with indices qc_list is realized. Also see mct_func below. If set to None, the callable is used, see quant.QTreeCircuitManager. Defaults to None.

• mct_func (callable or None) – Function (qiskit.Circuit, q1, q2, qc_list -> None) that defines how a multi-control Toffoli gate between two qubits with indices q1 and q2 controlled by the qubits with indices qc_list is realized. If set to None, the callable is used, see quant.QTreeCircuitManager. Defaults to None.

• pop_size (int) – Hyperparameter of tree growth. Population size used in the evolution algorithm. See deap documentation for more details. Defults to 10.

• cx_pb (float) – Hyperparameter of tree growth. Crossover probability for tools.cxOnePoint used in the evolution algorithm. See deap documentation for more details. Defaults to 0.2.

• mut_pb (float) – Hyperparameter of tree growth. Mutation probability for tools.mutUniformInt used in the evolution algorithm. See deap documentation for more details. Defaults to 0.2.

• mut_ind_pb (float) – Hyperparameter of tree growth. Ìndividual gene mutation probability for tools.mutUniformInt used in the evolution algorithm. See deap documentation for more details. Defaults to 0.2.

• select_tournsize (int) – Hyperparameter of tree growth. Selection tournament size for tools.selTournament with k=pop_size-1 used in the evolution algorithm. See deap documentation for more details. Defaults to 3.

• max_generations (int) – Hyperparameter of tree growth. Maximum number of generations used in the evolution algorithm. See deap documentation for more details. Defaults to 10.

• reuse_G_calc (bool) – Hyperparameter of tree growth. Determines how tree evaluations are performed. If True, reuse tree evaluations. If False, repeat evaluations (e.g., to take noisy simulations and imperfect backends into account). Defaults to True.

• mean_fits (bool) – Hyperparameter of tree growth. Determines how multiple evaluation of the same tree should be treated. If True, fitnesses of identical trees are averaged (where differences can occur due to noise). If False, only the newest fitness is used. Defaults to True.

• random_state (int or None) – Hyperparameter of tree growth. Random seed. Can also be a numpy.random.RandomState. If set to None, an unspecified seed is used. Defaults to None.

• evo_callback (callable or None) – Callback function (current_generation, pop) -> None for tree growth. Called every iteration. If set to None, callback function is ignored. Defaults to None.

• remove_inactive_qubits (bool) – Affects the circuit representation of the decision tree. If True, inactive qubits are removed from the circuit. If False, they are included. Defaults to True.

• eliminate_first_swap (bool) – Affects the circuit representation of the decision tree. If True, the first swap gate is removed by changing the qubit ordering. If False, the first swap gate is included. Defaults to False.

• simultaneous_circuit_evaluation (bool) – Determines how trees (i.e., quantum circuits) are evaluated for the evolution algorithm when growing a tree. If True, all circuits of one iteration are evaluated simultaneously (i.e., in one job). If False, all circuits of one iteration are evaluated sequentially (i.e., as multiple jobs). Defaults to False.

• include_id (bool) – Affects the circuit representation of the decision tree. If True, identity gates are included. If False, they are omitted. Defaults to False.

• block_form (bool) – Affects the circuit representation of the decision tree. If True, tree layers are grouped and represented by custom gates. If False, all base gates are used instead. Defaults to False.

• use_barriers (bool) – Affects the circuit representation of the decision tree. If True, barriers are inserted between tree layers. If False, no barriers are used. Defaults to False.

• logger (logging.Logger or None) – Logger for all output purposes. If None, the default logger is used. Defaults to None.

property G

Raw tree structure.

Type:

list

G_to_features()

Extract splitting features from tree structure.

property X

Training data, features.

Type:

numpy.ndarray

static acc_func_acc_balanced(y_pred, y_true)

Accuracy function as argument for acc_func in __init__. See there for more details.

circuit(measure_y=True, measure_all_x=False, return_meta=False, return_depth=False)

Build circuit representation of the decision tree.

cl_tree_prediction(X, **kwargs)

Make class prediction with classical tree representation.

cl_tree_prediction_proba(X, **kwargs)

Make class probability prediction with classical tree representation.

property ct

Classical tree representation.

Type:

ctree.ClassicalTree

static dist_func_proba_dist_norm(py1, py2)

Distance function as argument for dist_func in __init__. See there for more details.

fit(X, y)

Fit classifier: grow the decision tree using an evolutionary algorithm.

Parameters:

• X (array-like of shape (n_samples, n_features)) – Feature vectors of training data. Note: will be converted into a binary array!

• y (array-like of shape (n_samples, n_labels)) – Target labels of training data. Note: will be converted into a binary array!

Returns:

self

Return type:

returns an instance of self.

grow(d_weight, s_weight, a_weight, pareto_fitness, max_depth, rng, pop_size, cx_pb, mut_pb, mut_ind_pb, select_tournsize, max_generations, reuse_G_calc, remove_inactive_qubits, eliminate_first_swap, include_id, block_form, use_barriers, simultaneous_circuit_evaluation, mean_fits)

Grow decision tree. (Advanced functionality.)

property path_result_dict

Tree traversal path summary.

Type:

dict

predict(X, **kwargs)

Make class predictions using a classical representation of the decision tree.

Parameters:

• X (array-like of shape (n_samples, n_features)) – Feature vectors of training data. Note: will be converted into a binary array!

• **kwargs – Additional arguments for the prediction. Will be passed to the classical tree.

Returns:

y – Predicted classes as a binary array.

Return type:

ndarray of shape (n_samples, n_labels)

predict_proba(X, **kwargs)

Make class probability predictions using a classical representation of the decision tree.

Parameters:

• X (array-like of shape (n_samples, n_features)) – Feature vectors of training data. Note: will be converted into a binary array!

• **kwargs – Additional arguments for the prediction. Will be passed to the classical tree.

Returns:

p – Predicted class probabilities.

Return type:

ndarray of shape (n_samples, 2, n_labels)

predict_query(query_probabilities)

Make class probability predictions using a probabilistic quantum circuit query.

Parameters:

query_probabilities (dict) – Quantum query of the form { key1 : probability1, key2 : probability2, ...}, where key is a bitstring of inputs/features and probability the corresponding probability. The sum of all probabilities has to be normalized. To predict a single key, use probability1 = 1.0.

Returns:

py – Predicted class probabilities as a binary array.

Return type:

ndarray of shape (n_classes,)

property qt

Circuit representation.

Type:

qiskit.Circuit

query_prediction(query_probabilities, path_result_dict=None, eliminate_first_swap=False, include_id=False, block_form=False, remove_inactive_qubits=False, return_additional_information=False)

Make class predictions using a probabilistic quantum circuit query.

static score_func_entropy(py)

Score function as argument for score_func in __init__. See there for more details.

set_score_request(*, sample_weight: bool | None | str = '$UNCHANGED$') → QTree

Request metadata passed to the score method.

Note that this method is only relevant if enable_metadata_routing=True (see sklearn.set_config()). Please see User Guide on how the routing mechanism works.

The options for each parameter are:

• True: metadata is requested, and passed to score if provided. The request is ignored if metadata is not provided.

• False: metadata is not requested and the meta-estimator will not pass it to score.

• None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.

• str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

New in version 1.3.

Note

This method is only relevant if this estimator is used as a sub-estimator of a meta-estimator, e.g. used inside a Pipeline. Otherwise it has no effect.

Parameters:

sample_weight (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for sample_weight parameter in score.

Returns:

self – The updated object.

Return type:

object

to_tree_dict(remove_inactive_qubits=False, eliminate_first_swap=False, include_id=False, block_form=False, use_barriers=False)

Build tree dict. (Advanced functionality.)

property tree_dict

Tree structure as dictionary containing the class probabilities of each leaf.

Type:

dict

property tree_dict_detailed

Tree structure as dictionary similar to tree_dict with more detailed information.

Type:

dict

property y

Training data, labels.

Type:

numpy.ndarray

class qtree.qtree.QTreeBase(max_depth, quantum_backend, d_weight, s_weight, a_weight, pareto_fitness, score_func, dist_func, acc_func, swap_func, mcswap_func, mct_func, pop_size, cx_pb, mut_pb, mut_ind_pb, select_tournsize, max_generations, reuse_G_calc, mean_fits, random_state, evo_callback, remove_inactive_qubits, eliminate_first_swap, simultaneous_circuit_evaluation, include_id, block_form, use_barriers, logger)

Bases: BaseEstimator, ClassifierMixin

Base class for quantum decision classifiers.

Parameters:

• max_depth (int) – Maximum depth of the decision tree. A tree of depth 0 consists only of the root.

• quantum_backend (qiskit.providers.Backend) – Qiskit quantum backend used for all calculations. Can be either a simulator or an actual backend.

• d_weight (float) – Hyperparameter of tree growth. Weight of the distance function for fitness calculation. Should be >= 0.

• s_weight (float) – Hyperparameter of tree growth. Weight of the score function for fitness calculation. Should be >= 0.

• a_weight (float) – Hyperparameter of tree growth. Weight of the accuracy function for fitness calculation. Should be >= 0.

• pareto_fitness (bool) – Hyperparameter of tree growth. Determines , how the three fitness function components are treated. If False, use scalarized fitness. If True, use multi-criteria fitness.

• score_func (callable) – Hyperparameter of tree growth. The score function maps from class probabilities in a leaf to a scalar, i.e., [py1, py2, ...] -> float. The result measures the concentration of the distribution and is used as the first fitness function component.

• dist_func (callable) – Hyperparameter of tree growth. The distance function maps from class probabilities in two leaves to a scalar, i.e., [py1, py2, ..., py1', py2', ..] -> float. The result measures the distance between two distributions and is used as the second fitness function component.

• acc_func (callable) – Hyperparameter of tree growth. The accuracy function maps from leaf to a scalar, i.e., [py1, py2, ...] -> float. The result measures the quality of the tree prediction and is used as the third fitness function component.

• swap_func (callable or None) – Function (qiskit.Circuit, q1, q2 -> None) that defines how a swap gate between two qubits with indices q1 and q2 is realized. If set to None, the callable is used, see quant.QTreeCircuitManager.

• mcswap_func (callable or None) – Function (qiskit.Circuit, q1, q2, qc_list, mct_func -> None) that defines how a multi-controlled swap gate between two qubits with indices q1 and q2 controlled by the qubits with indices qc_list is realized. Also see mct_func below. If set to None, the callable is used, see quant.QTreeCircuitManager.

• mct_func (callable or None) – Function (qiskit.Circuit, q1, q2, qc_list -> None) that defines how a multi-control Toffoli gate between two qubits with indices q1 and q2 controlled by the qubits with indices qc_list is realized. If set to None, the callable is used, see quant.QTreeCircuitManager.

• pop_size (int) – Hyperparameter of tree growth. Population size used in the evolution algorithm. See deap documentation for more details.

• cx_pb (float) – Hyperparameter of tree growth. Crossover probability for tools.cxOnePoint used in the evolution algorithm. See deap documentation for more details.

• mut_pb (float) – Hyperparameter of tree growth. Mutation probability for tools.mutUniformInt used in the evolution algorithm. See deap documentation for more details.

• mut_ind_pb (float) – Hyperparameter of tree growth. Ìndividual gene mutation probability for tools.mutUniformInt used in the evolution algorithm. See deap documentation for more details.

• select_tournsize (int) – Hyperparameter of tree growth. Selection tournament size for tools.selTournament with k=pop_size-1 used in the evolution algorithm. See deap documentation for more details.

• max_generations (int) – Hyperparameter of tree growth. Maximum number of generations used in the evolution algorithm. See deap documentation for more details.

• reuse_G_calc (bool) – Hyperparameter of tree growth. Determines how tree evaluations are performed. If True, reuse tree evaluations. If False, repeat evaluations (e.g., to take noisy simulations and imperfect backends into account).

• mean_fits (bool) – Hyperparameter of tree growth. Determines how multiple evaluation of the same tree should be treated. If True, fitnesses of identical trees are averaged (where differences can occur due to noise). If False, only the newest fitness is used.

• random_state (int or None) – Hyperparameter of tree growth. Random seed. Can also be a numpy.random.RandomState. If set to None, an unspecified seed is used.

• evo_callback (callable or None) – Callback function (current_generation, pop) -> None for tree growth. Called every iteration. If set to None, callback function is ignored.

• remove_inactive_qubits (bool) – Affects the circuit representation of the decision tree. If True, inactive qubits are removed from the circuit. If False, they are included.

• eliminate_first_swap (bool) – Affects the circuit representation of the decision tree. If True, the first swap gate is removed by changing the qubit ordering. If False, the first swap gate is included.

• simultaneous_circuit_evaluation (bool) – Determines how trees (i.e., quantum circuits) are evaluated for the evolution algorithm when growing a tree. If True, all circuits of one iteration are evaluated simultaneously (i.e., in one job). If False, all circuits of one iteration are evaluated sequentially (i.e., as multiple jobs).

• include_id (bool) – Affects the circuit representation of the decision tree. If True, identity gates are included. If False, they are omitted.

• block_form (bool) – Affects the circuit representation of the decision tree. If True, tree layers are grouped and represented by custom gates. If False, all base gates are used instead.

• use_barriers (bool) – Affects the circuit representation of the decision tree. If True, barriers are inserted between tree layers. If False, no barriers are used.

• logger (logging.Logger or None) – Logger for all output purposes. If None, the default logger is used.

static check_bool_array(a)

Check and convert boolean array.

static check_input_features(X, _X)

Check and convert input features for predictions.

static check_query_probabilities(query_probabilities, Nx)

Check probabilistic queries (in form of dictionaries) for predictions.

set_score_request(*, sample_weight: bool | None | str = '$UNCHANGED$') → QTreeBase

Request metadata passed to the score method.

Note that this method is only relevant if enable_metadata_routing=True (see sklearn.set_config()). Please see User Guide on how the routing mechanism works.

The options for each parameter are:

• True: metadata is requested, and passed to score if provided. The request is ignored if metadata is not provided.

• False: metadata is not requested and the meta-estimator will not pass it to score.

• None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.

• str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

New in version 1.3.

Note

This method is only relevant if this estimator is used as a sub-estimator of a meta-estimator, e.g. used inside a Pipeline. Otherwise it has no effect.

Parameters:

sample_weight (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for sample_weight parameter in score.

Returns:

self – The updated object.

Return type:

object

qtree.ctree

Classical decision trees.

class qtree.ctree.ClassicalTree(tree_dict, y_dim=None, y=None, tree_dict_detailed={}, logger=None)

Bases: ClassicalTreeBase

Classical decision tree base.

Parameters:

• tree_dict (dict) – Tree structure as dictionary, see qtree.QTree.

• y_dim (int or None) – Number of binary labels. If None, extract from tree_dict. Defaults to None.

• y (array-like of shape (n_samples, n_labels) or None) – Target labels of training data. Used to find majority classes for default predictions. If None, no defaults are used. Defaults to None.

• tree_dict_detailed (dict or None) – Tree structure as detailed dictionary, see qtree.QTree. Is used to add optional information to each node. Set to None to disable. Defaults to empty dictionary.

• logger (logging.Logger or None) – Logger for all output purposes. If None, print to std is used. Defaults to None.

calc_difference_to_exact(paths, tree_dict_exact, tree_dict_exact_data_probabilities={}, N=None, epsilon=None, omit_warnings=False)

Calculate the distance between the class probabilities in the leaves between the tree dictionary and another tree dictionary.

calc_exact_probabilities(X, y, omit_warnings=False)

Calculate the exact class prediction probabilities based on the data X and y.

get_classification_dict(X, y, omit_warnings=False)

Return classification report as dictionary.

predict(X, omit_warnings=False, verbose=False)

Make class prediction.

predict_proba(X, omit_warnings=False, verbose=False)

Make class probability prediction.

print_classification_report(X, y, omit_warnings=False)

Print classification report.

class qtree.ctree.ClassicalTreeBase(tree_dict, y_dim, y, tree_dict_detailed, logger)

Bases: Node

Classical decision tree base.

Parameters:

• tree_dict (dict) – Tree structure as dictionary, see qtree.QTree.

• y_dim (int or None) – Number of binary labels. If None, extract from tree_dict.

• y (array-like of shape (n_samples, n_labels) or None) – Target labels of training data. Used to find majority classes for default predictions. If None, no defaults are used.

• tree_dict_detailed (dict or None) – Tree structure as detailed dictionary, see qtree.QTree. Is used to add optional information to each node. Set to None to disable.

• logger (logging.Logger or None) – Logger for all output purposes. If None, print to std is used.

class qtree.ctree.Node(depth, y_dim, default_y=None, logger=None)

Bases: object

Classical decision tree node (root, inner node or leaf).

Parameters:

• depth (int) – Depth of this node. The root corresponds to depth=0.

• y_dim (int) – Number of binary labels.

• default_y (int or None) – Default value based on majority of classes in training data. Is used if a classification is ambiguous in a leaf. Set to None to disable.

• logger (logging.Logger or None) – Logger for all output purposes. If None, print to std is used.

qtree.quant

Quantum circuit realization for quantum decision trees.

class qtree.quant.QTreeCircuitManager(swap_func=None, mcswap_func=None, mct_func=None, logger=None)

Bases: object

Quantum circuit manager for quantum decision trees.

Parameters:

• swap_func (callable or None) – Function (qiskit.Circuit, q1, q2 -> None) that defines how a swap gate between two qubits with indices q1 and q2 is realized. If set to None, QTreeCircuitManager.gateop_swap_default is used. Defaults to None.

• mcswap_func (callable or None) – Function (qiskit.Circuit, q1, q2, qc_list, mct_func -> None) that defines how a multi-controlled swap gate between two qubits with indices q1 and q2 controlled by the qubits with indices qc_list is realized. Also see mct_func below. If set to None, QTreeCircuitManager.gateop_mcswap_u is used. Defaults to None.

• mct_func (callable or None) – Function (qiskit.Circuit, q1, q2, qc_list -> None) that defines how a multi-control Toffoli gate between two qubits with indices q1 and q2 controlled by the qubits with indices qc_list is realized. If set to None, QTreeCircuitManager.gateop_mct_default is used. Defaults to None.

• logger (logging.Logger or None) – Logger for all output purposes. If None, the default logger is used. Defaults to None.

build_circuit(G, Nx, Ny, init, measure_y=True, measure_all_x=False, remove_inactive_qubits=False, eliminate_first_swap=False, include_id=False, block_form=False, use_barriers=False)

Build circuit representation of decision tree.

static gateop_mcswap_u(circ, q1, q2, qc_list, mct_func)

MCSWAP function: use custom unitary representation. Used as argument for mcswap_func in __init__. See there for more details.

static gateop_mcswap_xmctx(circ, q1, q2, qc_list, mct_func)

MCSWAP function: use cnot mcswap representation. Used as argument for mcswap_func in __init__. See there for more details.

static gateop_mct_default(circ, q1, q2, qc_list)

MCT function: use default mct representation. Used as argument for mct_func in __init__. See there for more details.

static gateop_swap_cnot(circ, q1, q2)

SWAP function: use cnot swap representation. Used as argument for swap_func in __init__. See there for more details.

static gateop_swap_default(circ, q1, q2)

SWAP function: use default swap representation. Used as argument for swap_func in __init__. See there for more details.

run_circuits(circ_list, quantum_backend)

Evaluate a list of circuits and return the measured counts.

qtree.data

Data for quantum decision trees.

class qtree.data.BDS(**kwargs)

Bases: ABC

Abstract base class for binary data sets.

Parameters:

**kwargs (Arguments for data loader.) –

property X

Features.

Type:

numpy.ndarray of shape (n_samples,n_features)

property y

Labels.

Type:

numpy.ndarray of shape (n_samples,n_labels)

class qtree.data.BDS_test(**kwargs)

Bases: BDS

Binary data set: XOR test data set consisting of 7 features and 1 label.

Parameters:

**kwargs – N (int) determines the number of data points, defaults to 5.

class qtree.data.BDS_tic_tac_toe(root='', **kwargs)

Bases: BDS

Binary data set: Binarized version of the Tic-Tac-Toe Endgame Data Set. Each 15-dimensional feature vector represents a Tic-Tac-Toe playfield, the corresponding label represents the winning player.

Original source: https://archive.ics.uci.edu/ml/datasets/Tic-Tac-Toe+Endgame

Original creator: David W. Aha (aha@cs.jhu.edu)

Note: Encoding to binary and decoding from binary is realized via BDS_tic_tac_toe._encode_x and BDS_tic_tac_toe._decode_x, respectively.

Parameters:

• root (str) – Root directory to load data file data/tictactoe/tic-tac-toe.npz.

• **kwargs – Unused.

static print_playfield(x)

Print playfield represented by feature vector x.