pyepo.data.dataset ================== .. py:module:: pyepo.data.dataset .. autoapi-nested-parse:: optDataset class based on PyTorch Dataset Attributes ---------- .. autoapisummary:: pyepo.data.dataset.logger Classes ------- .. autoapisummary:: pyepo.data.dataset.optDataset pyepo.data.dataset.optDatasetKNN pyepo.data.dataset.optDatasetConstrs pyepo.data.dataset.optDataLoader Functions --------- .. autoapisummary:: pyepo.data.dataset.collate_tight_constraints Module Contents --------------- .. py:data:: logger .. py:class:: optDataset(model: pyepo.model.opt.optModel, feats: numpy.ndarray | torch.Tensor, costs: numpy.ndarray | torch.Tensor) Bases: :py:obj:`torch.utils.data.Dataset` PyTorch ``Dataset`` for predict-then-optimize problems. At construction time it solves the optimization problem for every cost vector and caches the optimal solution :math:`\mathbf{w}^*(\mathbf{c})` and objective value :math:`z^*(\mathbf{c})`. This precomputation removes solver overhead from the training loop, making ``optDataset`` the standard input format for end-to-end training in PyEPO. When labels are already available from another source, ``optDataset`` can be skipped and batches fed directly to ``pyepo.func`` modules. :ivar model: Optimization model :vartype model: optModel :ivar feats: Data features :vartype feats: torch.Tensor :ivar costs: Cost vectors :vartype costs: torch.Tensor :ivar sols: Cached optimal solutions w*(c) :vartype sols: torch.Tensor :ivar objs: Cached optimal objective values z*(c) :vartype objs: torch.Tensor .. py:attribute:: model .. py:attribute:: feats .. py:attribute:: costs .. py:attribute:: sols .. py:attribute:: objs .. py:class:: optDatasetKNN(model: pyepo.model.opt.optModel, feats: numpy.ndarray | torch.Tensor, costs: numpy.ndarray | torch.Tensor, k: int = 10, weight: float = 0.5) Bases: :py:obj:`optDataset` PyTorch ``Dataset`` for the kNN-robust decision-focused loss. For each instance the cost vector is replaced with a convex combination of its k nearest neighbours in feature space, and the optimization problem is solved on the smoothed costs. The mean kNN solutions and objective values are cached for training, providing a robust supervision signal under noisy or out-of-distribution feature observations. Reference: Schutte et al. (2024) ``_ :ivar model: Optimization model :vartype model: optModel :ivar k: number of nearest neighbours selected :vartype k: int :ivar weight: self-weight in the kNN convex combination (1.0 = no smoothing) :vartype weight: float :ivar feats: Data features :vartype feats: torch.Tensor :ivar costs: kNN-smoothed cost vectors :vartype costs: torch.Tensor :ivar sols: Mean kNN optimal solutions :vartype sols: torch.Tensor :ivar objs: Mean kNN optimal objective values :vartype objs: torch.Tensor .. py:attribute:: model .. py:attribute:: k :value: 10 .. py:attribute:: weight :value: 0.5 .. py:attribute:: feats .. py:attribute:: costs .. py:attribute:: sols .. py:attribute:: objs .. py:class:: optDatasetConstrs(model: pyepo.model.opt.optModel, feats: numpy.ndarray | torch.Tensor, costs: numpy.ndarray | torch.Tensor, skip_infeas: bool = False) Bases: :py:obj:`optDataset` PyTorch ``Dataset`` for the CaVE cone-aligned loss. Stores features and cost coefficients, solves each instance, and extracts the **normals of the binding constraints at the optimal vertex** in canonical ``<=`` orientation. These normals span the polyhedral cone onto which ``coneAlignedCosine`` projects the predicted cost vector during training. CaVE is defined for binary linear programs only, so the optimal vertex must be binary; instances that are infeasible or have non-binary optima raise (or are skipped when ``skip_infeas=True``). Binding-constraint extraction uses Gurobi's sparse-matrix API, which is why this dataset currently requires a Gurobi-backed ``optModel``. Per-instance row counts differ (different constraints bind at different vertices), so batch with ``optDataLoader`` or pass ``collate_tight_constraints`` to a PyTorch ``DataLoader``. Reference: Tang & Khalil (2024) ``_ :ivar model: Gurobi-backed optimization model :vartype model: optModel :ivar feats: Data features :vartype feats: torch.Tensor :ivar costs: Cost vectors :vartype costs: torch.Tensor :ivar sols: Optimal solutions :vartype sols: torch.Tensor :ivar objs: Optimal objective values :vartype objs: torch.Tensor :ivar ctrs: Per-instance binding-constraint normals in canonical ``<=`` orientation (ragged row counts) :vartype ctrs: list[torch.Tensor] .. py:attribute:: model .. py:attribute:: skip_infeas :value: False .. py:attribute:: feats .. py:attribute:: costs .. py:attribute:: sols .. py:attribute:: objs .. py:attribute:: ctrs .. py:function:: collate_tight_constraints(batch) Collate function for ``optDatasetConstrs`` batches. Stacks the standard ``(x, c, w, z)`` tensors and zero-pads the ragged per-instance binding-constraint matrices to a common row count so they can be assembled into a single ``(batch, max_rows, num_cost)`` tensor for ``coneAlignedCosine``. .. py:class:: optDataLoader(dataset, *args, **kwargs) Bases: :py:obj:`torch.utils.data.DataLoader` ``DataLoader`` that applies a dataset's own ``collate_fn`` when present. Datasets with ragged samples (e.g. ``optDatasetConstrs``, whose binding-constraint matrices vary in row count) carry a ``collate_fn``; this loader uses it so the caller never passes one explicitly. Plain datasets fall back to the default PyTorch collation.