pyepo.func.blackbox¶

Differentiable Black-box optimization function

Classes¶

`blackboxOpt`	Differentiable Black-Box Optimizer (DBB) -- gradient via solution interpolation.
`blackboxOptFunc`	An autograd function for differentiable black-box optimizer
`negativeIdentity`	Negative Identity Backpropagation (NID) -- hyperparameter-free DBB.
`negativeIdentityFunc`	An autograd function for negative identity optimizer

Module Contents¶

class pyepo.func.blackbox.blackboxOpt(optmodel: pyepo.model.opt.optModel, lambd: float = 10, processes: int = 1, solve_ratio: float = 1.0, dataset: pyepo.data.dataset.optDataset | None = None)¶

Bases: pyepo.func.abcmodule.optModule

Differentiable Black-Box Optimizer (DBB) – gradient via solution interpolation.

Replaces the zero gradient of the combinatorial solver with an interpolation-based estimate: given an upstream gradient \(\mathbf{d}\), DBB approximates the vector-Jacobian product as \((\mathbf{w}^*(\hat{\mathbf{c}} + \lambda \mathbf{d}) - \mathbf{w}^*(\hat{\mathbf{c}})) / \lambda\). Larger lambd smooths more aggressively; the recommended range is 10-20. The resulting surrogate is nonconvex in \(\hat{\mathbf{c}}\), so convergence guarantees are weaker than SPO+.

Returns a predicted solution – pair with an objective-value task loss such as L1 against \(z^*(\mathbf{c})\).

Reference: Vlastelica et al. (2019) https://arxiv.org/abs/1912.02175

lambd = 10¶

forward(pred_cost: torch.Tensor) → torch.Tensor¶: Forward pass

class pyepo.func.blackbox.blackboxOptFunc(*args, **kwargs)¶

Bases: torch.autograd.Function

An autograd function for differentiable black-box optimizer

static forward(ctx, pred_cost: torch.Tensor, module: blackboxOpt) → torch.Tensor¶

Forward pass for DBB

Parameters:

pred_cost – a batch of predicted values of the cost
module – blackboxOpt module

Returns:

predicted solutions

Return type:

torch.tensor

static backward(ctx, grad_output: torch.Tensor) → tuple[torch.Tensor | None, Ellipsis]¶: Backward pass for DBB

class pyepo.func.blackbox.negativeIdentity(optmodel: pyepo.model.opt.optModel, processes: int = 1, solve_ratio: float = 1.0, dataset: pyepo.data.dataset.optDataset | None = None)¶

Bases: pyepo.func.abcmodule.optModule

Negative Identity Backpropagation (NID) – hyperparameter-free DBB.

Treats the solver Jacobian as a (signed) identity: \(\partial \mathbf{w}^* / \partial \hat{\mathbf{c}} \approx -\mathbf{I}\) for minimization (and \(+\mathbf{I}\) for maximization), yielding a straight-through gradient estimator. This is the special case of DBB where \(\lambda\) is chosen so the interpolated solution coincides with the negative-identity update – with the bonus that no extra solver call is needed on the backward pass.

Returns a predicted solution; pair with an objective-value task loss (e.g., L1 against \(z^*(\mathbf{c})\)).

Reference: Sahoo et al. (2022) https://arxiv.org/abs/2205.15213

forward(pred_cost: torch.Tensor) → torch.Tensor¶: Forward pass

class pyepo.func.blackbox.negativeIdentityFunc(*args, **kwargs)¶

Bases: torch.autograd.Function

An autograd function for negative identity optimizer

static forward(ctx, pred_cost: torch.Tensor, module: negativeIdentity) → torch.Tensor¶

Forward pass for NID

Parameters:

pred_cost – a batch of predicted values of the cost
module – negativeIdentity module

Returns:

predicted solutions

Return type:

torch.tensor

static backward(ctx, grad_output: torch.Tensor) → tuple[torch.Tensor | None, Ellipsis]¶: Backward pass for NID