Update

docs/build/html/_sources/autoapi/pyepo/data/dataset/index.rst.txt

@@ -18,6 +18,7 @@ Classes
 .. autoapisummary::
 
  pyepo.data.dataset.optDataset
+ pyepo.data.dataset.optDatasetKNN
 
 
 
@@ -95,3 +96,65 @@ Classes
 
 
 
+.. py:class:: optDatasetKNN(model, feats, costs, k=10, weight=0.5)
+
+
+ Bases: :py:obj:`optDataset`
+
+ This class is Torch Dataset for optimization problems, when using the robust kNN-loss.
+
+ Reference: <https://arxiv.org/abs/2310.04328>
+
+ .. attribute:: model
+
+ Optimization models
+
+ :type: optModel
+
+ .. attribute:: k
+
+ number of nearest neighbours selected
+
+ :type: int
+
+ .. attribute:: weight
+
+ weight of kNN-loss
+
+ :type: float
+
+ .. attribute:: feats
+
+ Data features
+
+ :type: np.ndarray
+
+ .. attribute:: costs
+
+ Cost vectors
+
+ :type: np.ndarray
+
+ .. attribute:: sols
+
+ Optimal solutions
+
+ :type: np.ndarray
+
+ .. attribute:: objs
+
+ Optimal objective values
+
+ :type: np.ndarray
+
+ .. py:method:: _getSols()
+
+ A method to get optimal solutions for all cost vectors
+
+
+ .. py:method:: _getKNN()
+
+ A method to get kNN costs
+
+
+

docs/build/html/_sources/autoapi/pyepo/model/grb/index.rst.txt

@@ -390,7 +390,7 @@ Classes
 
  Bases: :py:obj:`pyepo.model.grb.grbmodel.optGrbModel`
 
- This class is optimization model for portfolio problem
+ This class is an optimization model for portfolio problem
 
  .. attribute:: _model
 
@@ -404,7 +404,7 @@ Classes
 
  :type: int
 
- .. attribute:: cov
+ .. attribute:: covariance
 
  covariance matrix of the returns
 
@@ -418,7 +418,7 @@ Classes
 
  .. py:method:: _getRiskLevel(gamma)
 
- A method to calculate risk level
+ A method to calculate the risk level
 
  :returns: risk level
  :rtype: float

docs/build/html/_sources/autoapi/pyepo/model/grb/portfolio/index.rst.txt

@@ -35,7 +35,7 @@ Attributes
 
  Bases: :py:obj:`pyepo.model.grb.grbmodel.optGrbModel`
 
- This class is optimization model for portfolio problem
+ This class is an optimization model for portfolio problem
 
  .. attribute:: _model
 
@@ -49,7 +49,7 @@ Attributes
 
  :type: int
 
- .. attribute:: cov
+ .. attribute:: covariance
 
  covariance matrix of the returns
 
@@ -63,7 +63,7 @@ Attributes
 
  .. py:method:: _getRiskLevel(gamma)
 
- A method to calculate risk level
+ A method to calculate the risk level
 
  :returns: risk level
  :rtype: float

docs/build/html/_sources/content/examples/data.rst.txt

@@ -140,3 +140,38 @@ As the following example, ``optDataset`` and Pytorch ``DataLoader`` wrap the dat
 
  # get data loader
  dataloader = DataLoader(dataset, batch_size=32, shuffle=True)
+
+
+optDatasetKNN
+=============
+
+``pyepo.data.optDatasetKNN`` is a PyTorch Dataset designed for implementing k-nearest neighbors (kNN) robust loss [#f1]_ in decision-focused learning. It stores the features and their corresponding costs of the objective function and solves optimization problems to get **mean kNN solutions and optimal objective values**.
+
+.. autoclass:: pyepo.data.dataset.optDatasetKNN
+ :noindex:
+
+As the following example, ``optDatasetKNN`` and Pytorch ``DataLoader`` wrap the data samples, which can make the model training cleaner and more organized.
+
+.. code-block:: python
+
+ import pyepo
+ from torch.utils.data import DataLoader
+
+ # model for shortest path
+ grid = (5,5) # grid size
+ model = pyepo.model.grb.shortestPathModel(grid)
+
+ # generate data
+ num_data = 1000 # number of data
+ num_feat = 5 # size of feature
+ deg = 4 # polynomial degree
+ noise_width = 0 # noise width
+ x, c = pyepo.data.shortestpath.genData(num_data, num_feat, grid, deg, noise_width, seed=135)
+
+ # build dataset
+ dataset = pyepo.data.dataset.optDatasetKNN(model, x, c, k=10, weight=0.5)
+
+ # get data loader
+ dataloader = DataLoader(dataset, batch_size=32, shuffle=True)
+
+.. [#f1] Schutte, N., Postek, K., & Yorke-Smith, N. (2023). Robust Losses for Decision-Focused Learning. arXiv preprint arXiv:2310.04328.

docs/build/html/_sources/content/examples/training.rst.txt

@@ -178,7 +178,7 @@ The example to learn shortest path with linear model is as follows:
  # set optimizer
  optimizer = torch.optim.Adam(predmodel.parameters(), lr=1e-3)
  # init perturbed optimizer
- ptb = pyepo.func.perturbedOpt(optmodel, n_samples=10, epsilon=0.5, processes=2)
+ ptb = pyepo.func.perturbedOpt(optmodel, n_samples=10, sigma=0.5, processes=2)
  # init loss
  criterion = nn.MSELoss()
 
@@ -243,7 +243,7 @@ The example to learn shortest path with linear model is as follows:
  # set optimizer
  optimizer = torch.optim.Adam(predmodel.parameters(), lr=1e-3)
  # init PFY loss
- pfy = pyepo.func.perturbedFenchelYoung(optmodel, n_samples=10, epsilon=0.5, processes=2)
+ pfy = pyepo.func.perturbedFenchelYoung(optmodel, n_samples=10, sigma=0.5, processes=2)
 
  # training
  num_epochs = 20

docs/build/html/_sources/content/modules/pyepo.data.dataset.rst.txt

@@ -18,6 +18,7 @@
  .. autosummary::
 
  optDataset
+ optDatasetKNN
 
 
 

docs/build/html/autoapi/pyepo/data/dataset/index.html

@@ -111,6 +111,9 @@ <h3>Classes<a class="headerlink" href="#classes" title="Link to this heading">
 <tr class="row-odd"><td><p><a class="reference internal" href="#pyepo.data.dataset.optDataset" title="pyepo.data.dataset.optDataset"><code class="xref py py-obj docutils literal notranslate"><span class="pre">optDataset</span></code></a></p></td>
 <td><p>This class is Torch Dataset for optimization problems.</p></td>
 </tr>
+<tr class="row-even"><td><p><a class="reference internal" href="#pyepo.data.dataset.optDatasetKNN" title="pyepo.data.dataset.optDatasetKNN"><code class="xref py py-obj docutils literal notranslate"><span class="pre">optDatasetKNN</span></code></a></p></td>
+<td><p>This class is Torch Dataset for optimization problems, when using the robust kNN-loss.</p></td>
+</tr>
 </tbody>
 </table>
 <dl class="py class">
@@ -229,6 +232,103 @@ <h3>Classes<a class="headerlink" href="#classes" title="Link to this heading">
 
 </dd></dl>
 
+<dl class="py class">
+<dt class="sig sig-object py" id="pyepo.data.dataset.optDatasetKNN">
+<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">pyepo.data.dataset.</span></span><span class="sig-name descname"><span class="pre">optDatasetKNN</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">model</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">feats</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">costs</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">k</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">10</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">weight</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0.5</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pyepo.data.dataset.optDatasetKNN" title="Link to this definition"></a></dt>
+<dd><p>Bases: <a class="reference internal" href="#pyepo.data.dataset.optDataset" title="pyepo.data.dataset.optDataset"><code class="xref py py-obj docutils literal notranslate"><span class="pre">optDataset</span></code></a></p>
+<p>This class is Torch Dataset for optimization problems, when using the robust kNN-loss.</p>
+<p>Reference: &lt;<a class="reference external" href="https://arxiv.org/abs/2310.04328">https://arxiv.org/abs/2310.04328</a>&gt;</p>
+<dl class="py attribute">
+<dt class="sig sig-object py" id="pyepo.data.dataset.optDatasetKNN.model">
+<span class="sig-name descname"><span class="pre">model</span></span><a class="headerlink" href="#pyepo.data.dataset.optDatasetKNN.model" title="Link to this definition"></a></dt>
+<dd><p>Optimization models</p>
+<dl class="field-list simple">
+<dt class="field-odd">Type<span class="colon">:</span></dt>
+<dd class="field-odd"><p><a class="reference internal" href="../../model/opt/index.html#pyepo.model.opt.optModel" title="pyepo.model.opt.optModel">optModel</a></p>
+</dd>
+</dl>
+</dd></dl>
+
+<dl class="py attribute">
+<dt class="sig sig-object py" id="pyepo.data.dataset.optDatasetKNN.k">
+<span class="sig-name descname"><span class="pre">k</span></span><a class="headerlink" href="#pyepo.data.dataset.optDatasetKNN.k" title="Link to this definition"></a></dt>
+<dd><p>number of nearest neighbours selected</p>
+<dl class="field-list simple">
+<dt class="field-odd">Type<span class="colon">:</span></dt>
+<dd class="field-odd"><p>int</p>
+</dd>
+</dl>
+</dd></dl>
+
+<dl class="py attribute">
+<dt class="sig sig-object py" id="pyepo.data.dataset.optDatasetKNN.weight">
+<span class="sig-name descname"><span class="pre">weight</span></span><a class="headerlink" href="#pyepo.data.dataset.optDatasetKNN.weight" title="Link to this definition"></a></dt>
+<dd><p>weight of kNN-loss</p>
+<dl class="field-list simple">
+<dt class="field-odd">Type<span class="colon">:</span></dt>
+<dd class="field-odd"><p>float</p>
+</dd>
+</dl>
+</dd></dl>
+
+<dl class="py attribute">
+<dt class="sig sig-object py" id="pyepo.data.dataset.optDatasetKNN.feats">
+<span class="sig-name descname"><span class="pre">feats</span></span><a class="headerlink" href="#pyepo.data.dataset.optDatasetKNN.feats" title="Link to this definition"></a></dt>
+<dd><p>Data features</p>
+<dl class="field-list simple">
+<dt class="field-odd">Type<span class="colon">:</span></dt>
+<dd class="field-odd"><p>np.ndarray</p>
+</dd>
+</dl>
+</dd></dl>
+
+<dl class="py attribute">
+<dt class="sig sig-object py" id="pyepo.data.dataset.optDatasetKNN.costs">
+<span class="sig-name descname"><span class="pre">costs</span></span><a class="headerlink" href="#pyepo.data.dataset.optDatasetKNN.costs" title="Link to this definition"></a></dt>
+<dd><p>Cost vectors</p>
+<dl class="field-list simple">
+<dt class="field-odd">Type<span class="colon">:</span></dt>
+<dd class="field-odd"><p>np.ndarray</p>
+</dd>
+</dl>
+</dd></dl>
+
+<dl class="py attribute">
+<dt class="sig sig-object py" id="pyepo.data.dataset.optDatasetKNN.sols">
+<span class="sig-name descname"><span class="pre">sols</span></span><a class="headerlink" href="#pyepo.data.dataset.optDatasetKNN.sols" title="Link to this definition"></a></dt>
+<dd><p>Optimal solutions</p>
+<dl class="field-list simple">
+<dt class="field-odd">Type<span class="colon">:</span></dt>
+<dd class="field-odd"><p>np.ndarray</p>
+</dd>
+</dl>
+</dd></dl>
+
+<dl class="py attribute">
+<dt class="sig sig-object py" id="pyepo.data.dataset.optDatasetKNN.objs">
+<span class="sig-name descname"><span class="pre">objs</span></span><a class="headerlink" href="#pyepo.data.dataset.optDatasetKNN.objs" title="Link to this definition"></a></dt>
+<dd><p>Optimal objective values</p>
+<dl class="field-list simple">
+<dt class="field-odd">Type<span class="colon">:</span></dt>
+<dd class="field-odd"><p>np.ndarray</p>
+</dd>
+</dl>
+</dd></dl>
+
+<dl class="py method">
+<dt class="sig sig-object py" id="pyepo.data.dataset.optDatasetKNN._getSols">
+<span class="sig-name descname"><span class="pre">_getSols</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pyepo.data.dataset.optDatasetKNN._getSols" title="Link to this definition"></a></dt>
+<dd><p>A method to get optimal solutions for all cost vectors</p>
+</dd></dl>
+
+<dl class="py method">
+<dt class="sig sig-object py" id="pyepo.data.dataset.optDatasetKNN._getKNN">
+<span class="sig-name descname"><span class="pre">_getKNN</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pyepo.data.dataset.optDatasetKNN._getKNN" title="Link to this definition"></a></dt>
+<dd><p>A method to get kNN costs</p>
+</dd></dl>
+
+</dd></dl>
+
 </section>
 </section>
 </section>

docs/build/html/autoapi/pyepo/model/grb/index.html

@@ -139,7 +139,7 @@ <h3>Classes<a class="headerlink" href="#classes" title="Link to this heading">
 <td><p>This class is optimization model for traveling salesman problem based on Miller-Tucker-Zemlin (MTZ) formulation.</p></td>
 </tr>
 <tr class="row-odd"><td><p><a class="reference internal" href="#pyepo.model.grb.portfolioModel" title="pyepo.model.grb.portfolioModel"><code class="xref py py-obj docutils literal notranslate"><span class="pre">portfolioModel</span></code></a></p></td>
-<td><p>This class is optimization model for portfolio problem</p></td>
+<td><p>This class is an optimization model for portfolio problem</p></td>
 </tr>
 </tbody>
 </table>
@@ -667,7 +667,7 @@ <h3>Classes<a class="headerlink" href="#classes" title="Link to this heading">
 <dt class="sig sig-object py" id="pyepo.model.grb.portfolioModel">
 <em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">pyepo.model.grb.</span></span><span class="sig-name descname"><span class="pre">portfolioModel</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">num_assets</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">covariance</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">gamma</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">2.25</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pyepo.model.grb.portfolioModel" title="Link to this definition"></a></dt>
 <dd><p>Bases: <a class="reference internal" href="grbmodel/index.html#pyepo.model.grb.grbmodel.optGrbModel" title="pyepo.model.grb.grbmodel.optGrbModel"><code class="xref py py-obj docutils literal notranslate"><span class="pre">pyepo.model.grb.grbmodel.optGrbModel</span></code></a></p>
-<p>This class is optimization model for portfolio problem</p>
+<p>This class is an optimization model for portfolio problem</p>
 <dl class="py attribute">
 <dt class="sig sig-object py" id="pyepo.model.grb.portfolioModel._model">
 <span class="sig-name descname"><span class="pre">_model</span></span><a class="headerlink" href="#pyepo.model.grb.portfolioModel._model" title="Link to this definition"></a></dt>
@@ -691,8 +691,8 @@ <h3>Classes<a class="headerlink" href="#classes" title="Link to this heading">
 </dd></dl>
 
 <dl class="py attribute">
-<dt class="sig sig-object py" id="pyepo.model.grb.portfolioModel.cov">
-<span class="sig-name descname"><span class="pre">cov</span></span><a class="headerlink" href="#pyepo.model.grb.portfolioModel.cov" title="Link to this definition"></a></dt>
+<dt class="sig sig-object py" id="pyepo.model.grb.portfolioModel.covariance">
+<span class="sig-name descname"><span class="pre">covariance</span></span><a class="headerlink" href="#pyepo.model.grb.portfolioModel.covariance" title="Link to this definition"></a></dt>
 <dd><p>covariance matrix of the returns</p>
 <dl class="field-list simple">
 <dt class="field-odd">Type<span class="colon">:</span></dt>
@@ -715,7 +715,7 @@ <h3>Classes<a class="headerlink" href="#classes" title="Link to this heading">
 <dl class="py method">
 <dt class="sig sig-object py" id="pyepo.model.grb.portfolioModel._getRiskLevel">
 <span class="sig-name descname"><span class="pre">_getRiskLevel</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">gamma</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pyepo.model.grb.portfolioModel._getRiskLevel" title="Link to this definition"></a></dt>
-<dd><p>A method to calculate risk level</p>
+<dd><p>A method to calculate the risk level</p>
 <dl class="field-list simple">
 <dt class="field-odd">Returns<span class="colon">:</span></dt>
 <dd class="field-odd"><p>risk level</p>

docs/build/html/autoapi/pyepo/model/grb/portfolio/index.html

@@ -110,7 +110,7 @@ <h3>Classes<a class="headerlink" href="#classes" title="Link to this heading">
 <table class="autosummary longtable docutils align-default">
 <tbody>
 <tr class="row-odd"><td><p><a class="reference internal" href="#pyepo.model.grb.portfolio.portfolioModel" title="pyepo.model.grb.portfolio.portfolioModel"><code class="xref py py-obj docutils literal notranslate"><span class="pre">portfolioModel</span></code></a></p></td>
-<td><p>This class is optimization model for portfolio problem</p></td>
+<td><p>This class is an optimization model for portfolio problem</p></td>
 </tr>
 </tbody>
 </table>
@@ -128,7 +128,7 @@ <h3>Attributes<a class="headerlink" href="#attributes" title="Link to this headi
 <dt class="sig sig-object py" id="pyepo.model.grb.portfolio.portfolioModel">
 <em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">pyepo.model.grb.portfolio.</span></span><span class="sig-name descname"><span class="pre">portfolioModel</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">num_assets</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">covariance</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">gamma</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">2.25</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pyepo.model.grb.portfolio.portfolioModel" title="Link to this definition"></a></dt>
 <dd><p>Bases: <a class="reference internal" href="../grbmodel/index.html#pyepo.model.grb.grbmodel.optGrbModel" title="pyepo.model.grb.grbmodel.optGrbModel"><code class="xref py py-obj docutils literal notranslate"><span class="pre">pyepo.model.grb.grbmodel.optGrbModel</span></code></a></p>
-<p>This class is optimization model for portfolio problem</p>
+<p>This class is an optimization model for portfolio problem</p>
 <dl class="py attribute">
 <dt class="sig sig-object py" id="pyepo.model.grb.portfolio.portfolioModel._model">
 <span class="sig-name descname"><span class="pre">_model</span></span><a class="headerlink" href="#pyepo.model.grb.portfolio.portfolioModel._model" title="Link to this definition"></a></dt>
@@ -152,8 +152,8 @@ <h3>Attributes<a class="headerlink" href="#attributes" title="Link to this headi
 </dd></dl>
 
 <dl class="py attribute">
-<dt class="sig sig-object py" id="pyepo.model.grb.portfolio.portfolioModel.cov">
-<span class="sig-name descname"><span class="pre">cov</span></span><a class="headerlink" href="#pyepo.model.grb.portfolio.portfolioModel.cov" title="Link to this definition"></a></dt>
+<dt class="sig sig-object py" id="pyepo.model.grb.portfolio.portfolioModel.covariance">
+<span class="sig-name descname"><span class="pre">covariance</span></span><a class="headerlink" href="#pyepo.model.grb.portfolio.portfolioModel.covariance" title="Link to this definition"></a></dt>
 <dd><p>covariance matrix of the returns</p>
 <dl class="field-list simple">
 <dt class="field-odd">Type<span class="colon">:</span></dt>
@@ -176,7 +176,7 @@ <h3>Attributes<a class="headerlink" href="#attributes" title="Link to this headi
 <dl class="py method">
 <dt class="sig sig-object py" id="pyepo.model.grb.portfolio.portfolioModel._getRiskLevel">
 <span class="sig-name descname"><span class="pre">_getRiskLevel</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">gamma</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pyepo.model.grb.portfolio.portfolioModel._getRiskLevel" title="Link to this definition"></a></dt>
-<dd><p>A method to calculate risk level</p>
+<dd><p>A method to calculate the risk level</p>
 <dl class="field-list simple">
 <dt class="field-odd">Returns<span class="colon">:</span></dt>
 <dd class="field-odd"><p>risk level</p>