pyepo.metric.regret
===================

.. py:module:: pyepo.metric.regret

.. autoapi-nested-parse::

   True regret loss



Attributes
----------

.. autoapisummary::

   pyepo.metric.regret.logger


Functions
---------

.. autoapisummary::

   pyepo.metric.regret.regret
   pyepo.metric.regret.calRegret


Module Contents
---------------

.. py:data:: logger

.. py:function:: 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
   :math:`\hat{\mathbf{c}}`, then measures the excess true objective
   incurred by that decision:
   :math:`l_i = \mathbf{c}_i^\top \mathbf{w}^*(\hat{\mathbf{c}}_i) -
   z^*(\mathbf{c}_i)`. With the default ``reduction="normalized"`` the
   result is :math:`\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)``.

   :param predmodel: a PyTorch ``nn.Module`` for cost prediction, or a
                     JAX callable ``f(x_numpy) -> cost_array``
   :param optmodel: a PyEPO optimization model
   :param dataloader: PyTorch DataLoader over an ``optDataset`` (yielding
                      ``(x, c, w, z, ...)`` tuples; fields beyond the first four,
                      e.g. CaVE tight constraints, are ignored)
   :param 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
   :param 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"``
   :rtype: float or np.ndarray


.. py:function:: calRegret(optmodel: pyepo.model.opt.optModel, pred_cost: numpy.ndarray, true_cost: numpy.ndarray, true_obj: float) -> float

   True regret of a single instance.

   :param optmodel: optimization model
   :param pred_cost: predicted cost vector
   :param true_cost: true cost vector
   :param true_obj: true optimal objective value

   :returns: true regret
   :rtype: float