pyepo.metric.regret

True regret loss

Attributes

logger

Functions

regret(→ float | numpy.ndarray)

True regret (SPO loss) of a trained predictor.

calRegret(→ float)

True regret of a single instance.

Module Contents

pyepo.metric.regret.logger
pyepo.metric.regret.regret(predmodel: torch.nn.Module | collections.abc.Callable, optmodel: pyepo.model.opt.optModel, dataloader: torch.utils.data.DataLoader, processes: int = 1, reduction: str = 'normalized') → float | numpy.ndarray

True regret (SPO loss) of a trained predictor.

Solves the optimization problem on the predicted cost vector \(\hat{\mathbf{c}}\), then measures the excess true objective incurred by that decision: \(l_i = \mathbf{c}_i^\top \mathbf{w}^*(\hat{\mathbf{c}}_i) - z^*(\mathbf{c}_i)\). With the default reduction="normalized" the result is \(\sum_i l_i / \sum_i |z^*(\mathbf{c}_i)|\), dimensionless and comparable across problem scales; instances with near-zero true optima inflate the ratio. PyTorch predictors are evaluated under eval(); the original mode is restored afterwards.

predmodel may also be a plain callable f(x: np.ndarray) -> array-like for JAX/Flax models; pass a functools.partial that closes over the current parameter pytree, e.g. functools.partial(model.apply, params).

Parameters:

  • predmodel – a PyTorch nn.Module for cost prediction, or a JAX callable f(x_numpy) -> cost_array

  • optmodel – a PyEPO optimization model

  • dataloader – PyTorch DataLoader over an optDataset (yielding (x, c, w, z) tuples)

  • processes – number of processors, 1 for single-core, 0 for all of cores; a fresh worker pool is spawned per call, each worker rebuilding the model from its constructor args

  • reduction – “normalized” (sum of regrets over sum of absolute true optima), “sum”, “mean”, or “none” (per-instance array)

Returns:

aggregated regret, or per-instance regrets when reduction="none"

Return type:

float or np.ndarray

pyepo.metric.regret.calRegret(optmodel: pyepo.model.opt.optModel, pred_cost: numpy.ndarray, true_cost: numpy.ndarray, true_obj: float) → float

True regret of a single instance.

Parameters:

  • optmodel – optimization model

  • pred_cost – predicted cost vector

  • true_cost – true cost vector

  • true_obj – true optimal objective value

Returns:

true regret

Return type:

float