pyepo.metric.unambregret
========================

.. py:module:: pyepo.metric.unambregret

.. autoapi-nested-parse::

   Unambiguous regret loss



Attributes
----------

.. autoapisummary::

   pyepo.metric.unambregret.logger


Functions
---------

.. autoapisummary::

   pyepo.metric.unambregret.unambRegret
   pyepo.metric.unambregret.calUnambRegret


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

.. py:data:: logger

.. py:function:: unambRegret(predmodel: torch.nn.Module, optmodel: pyepo.model.opt.optModel, dataloader: torch.utils.data.DataLoader, tolerance: float = 1e-05, max_iter: int = 10) -> float

   Normalized unambiguous regret (worst-case-tie SPO loss).

   When the predicted cost vector :math:`\hat{\mathbf{c}}` yields multiple
   optimal solutions, ``regret`` reports the realized one while
   ``unambRegret`` reports the **worst case over all optima**:
   :math:`l_{\mathrm{URegret}}(\hat{\mathbf{c}}, \mathbf{c}) =
   \max_{\mathbf{w} \in W^*(\hat{\mathbf{c}})} \mathbf{c}^\top
   \mathbf{w} - z^*(\mathbf{c})`. More theoretically rigorous than
   ``regret``, but in practice the two are nearly identical and
   ``unambRegret`` is rarely required.
   The result is normalized by :math:`\sum_i |z^*(\mathbf{c}_i)|`; instances with near-zero true optima inflate the ratio.

   :param predmodel: a regression neural network for cost prediction
   :param optmodel: a PyEPO optimization model
   :param dataloader: PyTorch DataLoader over an ``optDataset`` (fields beyond
                      ``(x, c, w, z)`` are ignored)
   :param tolerance: precision used when rounding predicted costs to find ties
   :param max_iter: maximum number of solve retries with relaxed tolerance

   :returns: normalized unambiguous regret
   :rtype: float


.. py:function:: calUnambRegret(optmodel: pyepo.model.opt.optModel, pred_cost: numpy.ndarray, true_cost: numpy.ndarray, true_obj: float, tolerance: float = 1e-05, max_iter: int = 10) -> float

   Unambiguous (worst-case-tie) regret of a single instance.

   :param optmodel: optimization model
   :param pred_cost: predicted costs
   :param true_cost: true costs
   :param true_obj: true optimal objective value
   :param tolerance: tolerance for precision
   :param max_iter: maximum number of recursive retries

   :returns: unambiguous regret loss
   :rtype: float