pyepo.func.regularized
======================

.. py:module:: pyepo.func.regularized

.. autoapi-nested-parse::

   Regularized differentiable optimization function



Classes
-------

.. autoapisummary::

   pyepo.func.regularized.regularizedFrankWolfeOpt
   pyepo.func.regularized.regularizedFrankWolfeOptFunc
   pyepo.func.regularized.regularizedFrankWolfeFenchelYoung
   pyepo.func.regularized.regularizedFrankWolfeFenchelYoungFunc


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

.. py:class:: regularizedFrankWolfeOpt(optmodel: pyepo.model.opt.optModel, lambd: float = 1.0, max_iter: int = 20, tol: float = 1e-06, processes: int = 1, solve_ratio: float = 1.0, dataset: pyepo.data.dataset.optDataset | None = None)

   Bases: :py:obj:`pyepo.func.abcmodule.optModule`


   L2-Regularized Frank-Wolfe Optimizer (RFWO) -- differentiable smoothed solver.

   Adds an L2 regularizer :math:`\tfrac{\lambda}{2}\|\mathbf{w}\|_2^2`
   to the linear objective and returns the regularized minimizer
   :math:`\hat{\mathbf{w}}_\lambda(\hat{\mathbf{c}}) =
   \arg\min_{\mathbf{w} \in \mathrm{conv}(\mathcal{S})}
   \hat{\mathbf{c}}^\top \mathbf{w} + \tfrac{\lambda}{2}\|\mathbf{w}\|_2^2`,
   which is unique, lies inside :math:`\mathrm{conv}(\mathcal{S})`, and
   varies continuously with :math:`\hat{\mathbf{c}}`. The program is
   solved by batched Frank-Wolfe iteration; the only oracle needed is the
   underlying linear solver (PyEPO's standard ``optModel.solve``).

   Returns a regularized solution -- not a loss. Pair with a user-defined
   task loss (MSE against :math:`\mathbf{w}^*(\mathbf{c})` matches the
   imitation setting in the paper), or use ``regularizedFrankWolfeFenchelYoung``
   for the loss-returning variant.

   Reference: Dalle et al. (2022) `<https://arxiv.org/abs/2207.13513>`_


   .. py:attribute:: lambd


   .. py:attribute:: max_iter
      :value: 20



   .. py:attribute:: tol
      :value: 1e-06



   .. py:method:: forward(pred_cost: torch.Tensor) -> torch.Tensor

      Forward pass



   .. py:method:: compute_regularization(y: torch.Tensor) -> torch.Tensor

      L2 regularizer Omega(y) = (lambd / 2) ||y||^2 per instance



.. py:class:: regularizedFrankWolfeOptFunc(*args, **kwargs)

   Bases: :py:obj:`torch.autograd.Function`


   An autograd function for regularized Frank-Wolfe


   .. py:method:: forward(ctx, pred_cost: torch.Tensor, module: regularizedFrankWolfeOpt) -> torch.Tensor
      :staticmethod:


      Forward pass for regularized Frank-Wolfe

      :param pred_cost: a batch of predicted values of the cost
      :param module: regularizedFrankWolfeOpt module

      :returns: regularized solutions
      :rtype: torch.tensor



   .. py:method:: backward(ctx, grad_output: torch.Tensor) -> tuple[torch.Tensor | None, Ellipsis]
      :staticmethod:


      Backward pass for regularized Frank-Wolfe



.. py:class:: regularizedFrankWolfeFenchelYoung(optmodel: pyepo.model.opt.optModel, lambd: float = 1.0, max_iter: int = 20, tol: float = 1e-06, processes: int = 1, solve_ratio: float = 1.0, reduction: pyepo.func.abcmodule.Reduction = 'mean', dataset: pyepo.data.dataset.optDataset | None = None)

   Bases: :py:obj:`pyepo.func.abcmodule.optModule`


   L2-Regularized Frank-Wolfe with Fenchel-Young loss (RFYL).

   Pairs the RFWO regularized solver with the Fenchel-Young loss of the L2
   regularizer, returning a convex scalar loss that compares the predicted
   cost :math:`\hat{\mathbf{c}}` to the true optimum
   :math:`\mathbf{w}^*(\mathbf{c})` directly -- no user-defined task loss
   needed. Specialized to :math:`\Omega(\mathbf{w}) =
   \tfrac{\lambda}{2}\|\mathbf{w}\|_2^2`, the loss collapses to a
   transparent "compare regularizers + linear residual" form.

   By Danskin's theorem the gradient is the simple residual
   :math:`\mathbf{w}^*(\mathbf{c}) - \hat{\mathbf{w}}_\lambda
   (\hat{\mathbf{c}})`, so the backward path skips implicit
   differentiation through the Frank-Wolfe iterate.

   Reference: Dalle et al. (2022) `<https://arxiv.org/abs/2207.13513>`_


   .. py:attribute:: lambd


   .. py:attribute:: max_iter
      :value: 20



   .. py:attribute:: tol
      :value: 1e-06



   .. py:method:: forward(pred_cost: torch.Tensor, true_sol: torch.Tensor) -> torch.Tensor

      Forward pass



.. py:class:: regularizedFrankWolfeFenchelYoungFunc(*args, **kwargs)

   Bases: :py:obj:`torch.autograd.Function`


   An autograd function for regularized Frank-Wolfe with Fenchel-Young loss


   .. py:method:: forward(ctx, pred_cost: torch.Tensor, true_sol: torch.Tensor, module: regularizedFrankWolfeFenchelYoung) -> torch.Tensor
      :staticmethod:


      Forward pass for regularized Frank-Wolfe with Fenchel-Young loss

      :param pred_cost: a batch of predicted values of the cost
      :param true_sol: a batch of true optimal solutions
      :param module: regularizedFrankWolfeFenchelYoung module

      :returns: Fenchel-Young loss
      :rtype: torch.tensor



   .. py:method:: backward(ctx, grad_output: torch.Tensor) -> tuple[torch.Tensor | None, Ellipsis]
      :staticmethod:


      Backward pass for regularized Frank-Wolfe with Fenchel-Young loss