discopt.ml.tree

discopt.ml.tree#

Tree ensemble data structures for MILP embedding.

Provides DecisionTree and TreeEnsembleDefinition for representing trained decision tree ensembles (random forests, gradient boosting) in a solver-agnostic format suitable for MILP encoding.

Classes#

DecisionTree

A single decision tree stored as parallel arrays.

TreeEnsembleDefinition

An ensemble of decision trees (random forest, gradient boosting, etc.).

Module Contents#

class discopt.ml.tree.DecisionTree#

A single decision tree stored as parallel arrays.

Node i is a leaf when feature[i] == -1. Otherwise it is a split node that branches on x[feature[i]] <= threshold[i].

Parameters:

  • n_features (int) – Number of input features.

  • feature (np.ndarray) – (n_nodes,) int array. Feature index for each split node, -1 for leaves.

  • threshold (np.ndarray) – (n_nodes,) float array. Split threshold (ignored at leaves).

  • left_child (np.ndarray) – (n_nodes,) int array. Index of left child (-1 at leaves).

  • right_child (np.ndarray) – (n_nodes,) int array. Index of right child (-1 at leaves).

  • value (np.ndarray) – (n_nodes,) float array. Prediction value at each leaf.

n_features: int#
feature: numpy.ndarray#
threshold: numpy.ndarray#
left_child: numpy.ndarray#
right_child: numpy.ndarray#
value: numpy.ndarray#
property leaves: numpy.ndarray#

Indices of leaf nodes.

property n_leaves: int#
leaf_ancestors(leaf_idx: int) → list[tuple[int, str]]#

Return the root-to-leaf path as (node, 'left'|'right') pairs.

Parameters:

leaf_idx (int) – Index of a leaf node.

Returns:

Each entry is (split_node_index, direction) where direction indicates which branch was taken to reach the leaf.

Return type:

list of (int, str)

predict(x: numpy.ndarray) → float#

Evaluate the tree on a single input vector.

class discopt.ml.tree.TreeEnsembleDefinition#

An ensemble of decision trees (random forest, gradient boosting, etc.).

Parameters:

  • trees (list of DecisionTree) – Individual trees in the ensemble.

  • n_features (int) – Number of input features.

  • base_score (float) – Additive intercept (e.g. XGBoost base_score).

  • input_bounds (tuple of np.ndarray, optional) – (lower, upper) bounds on each feature. Required for MILP formulation.

trees: list[DecisionTree]#
n_features: int#
base_score: float = 0.0#
input_bounds: tuple[numpy.ndarray, numpy.ndarray] | None = None#
predict(x: numpy.ndarray) → float#

Evaluate the ensemble on a single input vector.