pyepo.func.blackbox
===================

.. py:module:: pyepo.func.blackbox

.. autoapi-nested-parse::

   Differentiable Black-box optimization function



Attributes
----------

.. autoapisummary::

   pyepo.func.blackbox.DBB
   pyepo.func.blackbox.NID


Classes
-------

.. autoapisummary::

   pyepo.func.blackbox.blackboxOpt
   pyepo.func.blackbox.blackboxOptFunc
   pyepo.func.blackbox.negativeIdentity
   pyepo.func.blackbox.negativeIdentityFunc


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

.. py:class:: 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: :py:obj:`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
   :math:`\mathbf{d}`, DBB approximates the vector-Jacobian product as
   :math:`(\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 :math:`\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 :math:`z^*(\mathbf{c})`.

   Reference: Vlastelica et al. (2020) `<https://openreview.net/forum?id=BkevoJSYPB>`_


   .. py:attribute:: lambd
      :value: 10



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

      Forward pass



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

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


   An autograd function for differentiable black-box optimizer


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


      Forward pass for DBB

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

      :returns: predicted solutions
      :rtype: torch.tensor



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


      Backward pass for DBB



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

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


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

   Treats the solver Jacobian as a (signed) identity:
   :math:`\partial \mathbf{w}^* / \partial \hat{\mathbf{c}} \approx
   -\mathbf{I}` for minimization (and :math:`+\mathbf{I}` for
   maximization), yielding a straight-through gradient estimator. This is
   the special case of DBB where :math:`\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 :math:`z^*(\mathbf{c})`).

   Reference: Sahoo et al. (2023) `<https://openreview.net/forum?id=JZMR727O29>`_


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

      Forward pass



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

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


   An autograd function for negative identity optimizer


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


      Forward pass for NID

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

      :returns: predicted solutions
      :rtype: torch.tensor



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


      Backward pass for NID



.. py:data:: DBB

.. py:data:: NID