discopt.ml.formulations.base

discopt.ml.formulations.base#

Formulation wrappers for embedding trained ML models into discopt.

Classes#

NNFormulation

Embed a trained neural network into a discopt optimization model.

TreeFormulation

Embed a trained tree ensemble into a discopt optimization model.

Module Contents#

class discopt.ml.formulations.base.NNFormulation(model: discopt.modeling.core.Model, network: discopt.ml.network.NetworkDefinition, strategy: str = 'full_space', prefix: str = 'nn', scaling: discopt.ml.scaling.OffsetScaling | None = None)#

Embed a trained neural network into a discopt optimization model.

Follows the builder pattern: takes an existing Model, adds variables and constraints to represent the neural network, and exposes input/output variable handles for connecting to the rest of the optimization model.

Parameters:

  • model (discopt.Model) – The optimization model to embed the network into.

  • network (NetworkDefinition) – The trained network to embed.

  • strategy (str) – Formulation strategy. One of "full_space" (smooth activations), "relu_bigm" (ReLU via big-M MILP), or "reduced_space" (nested expressions, no intermediate variables).

  • prefix (str) – Name prefix for created variables and constraints.

  • scaling (OffsetScaling or None) – Optional input/output scaling.

Example

>>> nn = NNFormulation(model, network, strategy="relu_bigm")
>>> nn.formulate()
>>> model.minimize(dm.sum(nn.outputs))
property inputs: discopt.modeling.core.Variable#

Input variables (unscaled, in the user’s domain).

property outputs: discopt.modeling.core.Variable#

Output variables (unscaled, in the user’s domain).

formulate() → None#

Add all variables and constraints to the model.

This method can only be called once per NNFormulation instance.

class discopt.ml.formulations.base.TreeFormulation(model: discopt.modeling.core.Model, ensemble: discopt.ml.tree.TreeEnsembleDefinition, prefix: str = 'tree', scaling: discopt.ml.scaling.OffsetScaling | None = None, split_eps: float = 1e-05)#

Embed a trained tree ensemble into a discopt optimization model.

Parameters:

  • model (discopt.Model) – The optimization model to embed the tree ensemble into.

  • ensemble (TreeEnsembleDefinition) – The trained tree ensemble.

  • prefix (str) – Name prefix for created variables and constraints.

  • scaling (OffsetScaling or None) – Optional input/output scaling.

  • split_eps (float) – Half-width of the separation band around each split threshold (default 1e-5). It must exceed the solver’s absolute feasibility tolerance (1e-6): a tree is discontinuous at its thresholds, so tolerance-sized slack becomes an O(1) prediction error. The default matches TreeEnsembleFormulation (#1447, #1620); see that class for the measured rationale.

Example

>>> tf = TreeFormulation(model, ensemble)
>>> tf.formulate()
>>> model.minimize(tf.outputs[0])
property inputs: discopt.modeling.core.Variable#

Input variables.

property outputs: discopt.modeling.core.Variable#

Output variables.

formulate() → None#

Add all variables and constraints to the model.