pydflt 0.1.0__tar.gz

pydflt-0.1.0/LICENSE.md

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2025 Noah Schutte, Kim van den Houten, Grigorii Veviurko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

pydflt-0.1.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: pydflt
+Version: 0.1.0
+Summary: PyDFLT
+Author-email: Noah Schutte <N.J.Schutte@tudelft.nl>, Kim van den Houten <K.C.vandenhouten@tudelft.nl>, Grigorii Veviurko <G.Veviurko@tudelft.nl>
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: torch>=2.7.1
+Requires-Dist: cvxpy>=1.4.1
+Requires-Dist: diffcp>=1.0.18
+Requires-Dist: cvxpylayers>=0.1.6
+Requires-Dist: numpy>=1.26.4
+Requires-Dist: ortools>=9.12.4544
+Requires-Dist: gurobipy>=11.0.3
+Requires-Dist: pyepo~=0.3.9
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: tomli>=2.0.1
+Requires-Dist: wandb>=0.19.11
+Requires-Dist: pandas>=2.2.3
+Requires-Dist: matplotlib>=3.6.3
+Requires-Dist: optuna>=4.2.1
+Requires-Dist: optuna-dashboard>=0.19.0
+Requires-Dist: scikit-learn>=1.6.1
+Requires-Dist: scipy>=1.13.1
+Requires-Dist: joblib>=1.4.2
+Requires-Dist: ipywidgets>=8.1.7
+Dynamic: license-file
+
+[![CI](https://github.com/PyDFLT/PyDFLT/actions/workflows/CI.yml/badge.svg)](https://github.com/PyDFLT/PyDFLT/actions/workflows/CI.yml)
+
+![alt text](https://github.com/PyDFLT/PyDFLT/blob/main/images/logo.png?raw=true)
+
+
+## A Python-based Decision-Focused Learning Toolbox
+**PyDFLT** is designed to help researchers apply and develop Decision Focused Learning (DFL) tools in Python. It uses **CVXPYLayers** [1] for differentiable models, **PyEPO** [2] for models with a linear objective and has an implementation of **SFGE** [3] and **Lancer** [4]. To help with research, it supports Weights & Biases (https://wandb.ai/) and Optuna (https://optuna.org).
+In the near future, we will publish PyDFLT on the Python Package Index, after which you can install it by running:
+
+`pip install pydflt`
+
+### Documentation
+
+Documentation can be found https://pydflt.github.io/documentation.
+
+### Contributing
+If you want to contribute, you can fork the repository and send a pull request. We make use of **uv** (https://github.com/astral-sh/uv) for the installation and testing. Install uv [here](https://docs.astral.sh/uv/getting-started/installation/). To create the virtual environment:
+
+`uv sync --all-extras --all-groups`
+
+Notice that your IDE might automatically create the environment, but does only install the basic package dependencies. Make sure to run above command to install all dependencies.
+
+#### Before committing
+
+We make use of **pre-commit** (https://pre-commit.com/) and **pytest** to ensure code is consistent and functioning properly. Both are part of the dev dependencies and therefore installed in the virtual environment. Before committing make sure to run both:
+
+`uv run pre-commit run --all-files`
+
+`uv run pytest`
+
+#### Documentation
+
+We use **Sphinx** (https://www.sphinx-doc.org/en/master/) for the documentation.  The Makefile in this directory can be used to build the documentation.
+
+You can run `uv run make html --directory=docs` rom the project root as well, which will build the documentation in the exact same way as it will be displayed on the website.
+
+Then, go to docs/build/html/api/src.html and drag the file into a browser.
+
+
+### Using Weights & Biases
+If you want to use Weights & Biases, either set an environment variable named `WANDB_KEY` with your key,
+or create a `.env` file with `WANDB_KEY = 'your-key-here'`.
+
+
+### References
+
+[1] Akshay Agrawal, Brandon Amos, Shane Barratt, Stephen Boyd, Steven Diamond, and J Zico Kolter. Differentiable convex optimization layers. Advances in neural information processing systems, 32, 2019. doi:10.48550/arXiv.1910.12430.
+
+[2] Bo Tang and Elias B. Khalil. Pyepo: a pytorch-based end-to-end predict-then-optimize library for linear and integer programming. Mathematical Programming Computation, 16(3):297–335, 2024. doi:10.1007/s12532-024-00255-x.
+
+[3] Mattia Silvestri, Senne Berden, Jayanta Mandi, Ali ˙Irfan Mahmuto˘gulları, Maxime Mulamba, Allegra De Filippo, Tias Guns, and Michele Lombardi. Score function gradient estimation to widen the applicability of decision-focused learning. CoRR, abs/2307.05213, 2023. doi:10.48550/arXiv.2307.05213.
+
+[4] Arman Zharmagambetov, Brandon Amos, Aaron Ferber, Taoan Huang, Bistra Dilkina, and Yuandong Tian. Landscape surrogate: Learning decision losses for mathematical optimization under partial information. Advances in Neural Information Processing Systems, 36:27332–27350, 2023. doi:10.48550/arXiv.2307.08964.

pydflt-0.1.0/README.md

@@ -0,0 +1,53 @@
+[![CI](https://github.com/PyDFLT/PyDFLT/actions/workflows/CI.yml/badge.svg)](https://github.com/PyDFLT/PyDFLT/actions/workflows/CI.yml)
+
+![alt text](https://github.com/PyDFLT/PyDFLT/blob/main/images/logo.png?raw=true)
+
+
+## A Python-based Decision-Focused Learning Toolbox
+**PyDFLT** is designed to help researchers apply and develop Decision Focused Learning (DFL) tools in Python. It uses **CVXPYLayers** [1] for differentiable models, **PyEPO** [2] for models with a linear objective and has an implementation of **SFGE** [3] and **Lancer** [4]. To help with research, it supports Weights & Biases (https://wandb.ai/) and Optuna (https://optuna.org).
+In the near future, we will publish PyDFLT on the Python Package Index, after which you can install it by running:
+
+`pip install pydflt`
+
+### Documentation
+
+Documentation can be found https://pydflt.github.io/documentation.
+
+### Contributing
+If you want to contribute, you can fork the repository and send a pull request. We make use of **uv** (https://github.com/astral-sh/uv) for the installation and testing. Install uv [here](https://docs.astral.sh/uv/getting-started/installation/). To create the virtual environment:
+
+`uv sync --all-extras --all-groups`
+
+Notice that your IDE might automatically create the environment, but does only install the basic package dependencies. Make sure to run above command to install all dependencies.
+
+#### Before committing
+
+We make use of **pre-commit** (https://pre-commit.com/) and **pytest** to ensure code is consistent and functioning properly. Both are part of the dev dependencies and therefore installed in the virtual environment. Before committing make sure to run both:
+
+`uv run pre-commit run --all-files`
+
+`uv run pytest`
+
+#### Documentation
+
+We use **Sphinx** (https://www.sphinx-doc.org/en/master/) for the documentation.  The Makefile in this directory can be used to build the documentation.
+
+You can run `uv run make html --directory=docs` rom the project root as well, which will build the documentation in the exact same way as it will be displayed on the website.
+
+Then, go to docs/build/html/api/src.html and drag the file into a browser.
+
+
+### Using Weights & Biases
+If you want to use Weights & Biases, either set an environment variable named `WANDB_KEY` with your key,
+or create a `.env` file with `WANDB_KEY = 'your-key-here'`.
+
+
+### References
+
+[1] Akshay Agrawal, Brandon Amos, Shane Barratt, Stephen Boyd, Steven Diamond, and J Zico Kolter. Differentiable convex optimization layers. Advances in neural information processing systems, 32, 2019. doi:10.48550/arXiv.1910.12430.
+
+[2] Bo Tang and Elias B. Khalil. Pyepo: a pytorch-based end-to-end predict-then-optimize library for linear and integer programming. Mathematical Programming Computation, 16(3):297–335, 2024. doi:10.1007/s12532-024-00255-x.
+
+[3] Mattia Silvestri, Senne Berden, Jayanta Mandi, Ali ˙Irfan Mahmuto˘gulları, Maxime Mulamba, Allegra De Filippo, Tias Guns, and Michele Lombardi. Score function gradient estimation to widen the applicability of decision-focused learning. CoRR, abs/2307.05213, 2023. doi:10.48550/arXiv.2307.05213.
+
+[4] Arman Zharmagambetov, Brandon Amos, Aaron Ferber, Taoan Huang, Bistra Dilkina, and Yuandong Tian. Landscape surrogate: Learning decision losses for mathematical optimization under partial information. Advances in Neural Information Processing Systems, 36:27332–27350, 2023. doi:10.48550/arXiv.2307.08964.

pydflt-0.1.0/pyproject.toml

@@ -0,0 +1,95 @@
+[project]
+name = "pydflt"
+version = "0.1.0"
+description = "PyDFLT"
+authors = [
+    { name = "Noah Schutte", email = "N.J.Schutte@tudelft.nl"},
+    { name = "Kim van den Houten", email = "K.C.vandenhouten@tudelft.nl"},
+    { name = "Grigorii Veviurko", email = "G.Veviurko@tudelft.nl"}
+]
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "torch>=2.7.1",
+    "cvxpy>=1.4.1",
+    "diffcp>=1.0.18",
+    "cvxpylayers>=0.1.6",
+    "numpy>=1.26.4",
+    "ortools>=9.12.4544",
+    "gurobipy>=11.0.3",
+    "pyepo~=0.3.9",
+    "pyyaml>=6.0.2",  # PyYAML is same package
+    "tomli>=2.0.1",
+    "wandb>=0.19.11",
+    "pandas>=2.2.3",
+    "matplotlib>=3.6.3",
+    "optuna>=4.2.1",
+    "optuna-dashboard>=0.19.0",
+    "scikit-learn>=1.6.1",
+    "scipy>=1.13.1",
+    "joblib>=1.4.2",
+    "ipywidgets>=8.1.7"
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3.2",
+    "pytest-cov>=5.0.0",
+    "nbmake>=1.5.5",
+    "codecov>=2.1.13",
+    "pre-commit>=3.8.0",
+    "ruff>=0.12.4",
+]
+
+docs = [
+    "sphinx>=7.4.7",
+    "nbsphinx>=0.9.5",
+    "numpydoc>=1.8.0",
+    "sphinx-immaterial>=0.12.2",
+    "myst-parser>=2.0.0",
+    "pypandoc-binary>=1.12",
+]
+
+examples = [
+    "jupyter>=1.0.0",
+]
+
+[tool.uv]
+required-version = "0.6.16"
+default-groups = ["dev", "docs"]
+
+[tool.black]
+line-length = 160
+
+[tool.ruff]
+line-length = 160
+extend-include = ["*.ipynb"]
+
+
+[tool.ruff.lint]
+select = [
+    "E",  # pycodestyle errors
+    "I",  # isort
+    "W",  # pycodestyle warnings,
+    "F",  # pyflakes,
+    "C",  # flake8-comprehensions,
+    "B",  # flake8-bugbear
+]
+ignore = [
+    "C901",  # too complex
+]
+
+[tool.ruff.lint.isort]
+known-third-party = ["numpy", "wandb"]  # can cause issues with pre-commit otherwise
+
+[tool.pytest.ini_options]
+addopts = "--cov=. --cov-report=xml --nbmake"
+testpaths = [
+    "tests",
+    "examples",
+]
+
+
+[build-system]
+requires = ["setuptools >= 61.0"]
+build-backend = "setuptools.build_meta"

pydflt-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pydflt-0.1.0/src/__init__.py

@@ -0,0 +1,23 @@
+import torch
+
+from src.registries.data import data_registry as data_registry
+from src.registries.data import get_data as get_data
+from src.registries.data import register_data as register_data
+from src.registries.decision_makers import (
+    decision_maker_registry as decision_maker_registry,
+)
+from src.registries.decision_makers import make_decision_maker as make_decision_maker
+from src.registries.decision_makers import (
+    register_decision_maker as register_decision_maker,
+)
+from src.registries.models import make_model as make_model
+from src.registries.models import model_registry as model_registry
+from src.registries.models import register_model as register_model
+
+from .dataset import DFLDataset as DFLDataset
+from .logger import Logger as Logger
+from .noisifier import Noisifier as Noisifier
+from .problem import Problem as Problem
+from .runner import Runner as Runner
+
+torch.set_default_dtype(torch.float32)

pydflt-0.1.0/src/abstract_models/__init__.py

@@ -0,0 +1,4 @@
+from .base import OptimizationModel as OptimizationModel
+from .cvxpy_diff import CVXPYDiffModel as CVXPYDiffModel
+from .grbpy import GRBPYModel as GRBPYModel
+from .grbpy_two_stage import GRBPYTwoStageModel as GRBPYTwoStageModel

pydflt-0.1.0/src/abstract_models/base.py

@@ -0,0 +1,263 @@
+import copy
+import inspect
+from abc import ABC, abstractmethod
+from typing import Literal
+
+import numpy as np
+import torch
+
+MAX = "MAX"
+MIN = "MIN"
+
+
+class OptimizationModel(ABC):
+    """
+    Base class that specifies the interface for all optimization models.
+    To implement your own model, it is recommended to inherit from one of the children of this class,
+    e.g., CVXPYModel or GRBPYModel.
+
+    Attributes:
+        var_names (list[str]): Sorted list of decision variable names.
+        var_shapes (dict[str, tuple[int, ...]]): Dictionary mapping decision variable names to their shapes.
+        param_to_predict_names (list[str]): Sorted list of parameter names that need to be predicted.
+        param_to_predict_shapes (dict[str, tuple[int, ...]]): Dictionary mapping parameters to predict to their shapes.
+        extra_param_names (list[str]): Sorted list of additional parameter names that change per sample but are known.
+        extra_param_shapes (dict[str, tuple[int, ...]]): Dictionary mapping extra parameters to their shapes.
+        all_param_names (list[str]): Concatenation of `param_to_predict_names` and `extra_param_names`.
+        num_predictions (int): Total number of elements across all parameters to be predicted.
+        num_vars (int): Total number of elements across all decision variables.
+        num_params (int): Total number of elements across all parameters.
+        model_sense (str): Specifies whether the model minimizes ('MIN') or maximizes ('MAX').
+        init_arguments (dict[str, Any]): Stores the initial arguments used to create this model instance,
+                                         used for creating variants or copies.
+    """
+
+    def __init__(
+        self,
+        var_shapes: dict[str, tuple[int, ...]],
+        param_to_predict_shapes: dict[str, tuple[int, ...]],
+        model_sense: Literal["MIN", "MAX"],
+        extra_param_shapes: dict[str, tuple[int, ...]] | None = None,
+        num_scenarios: int = 1,
+    ) -> None:
+        """
+        Initializes the OptimizationModel.
+
+        Args:
+            var_shapes (dict[str, tuple[int, ...]]): A dictionary specifying the names and shapes of
+                                                      decision variables (e.g., {'decision': (10,)}).
+            param_to_predict_shapes (dict[str, tuple[int, ...]]): A dictionary specifying the names and shapes of
+                                                                 parameters that must be provided prior to
+                                                                 running optimization.
+            model_sense (str): Specifies whether the model minimizes ('MIN') or maximizes ('MAX').
+                               Must be either 'MIN' or 'MAX'.
+            extra_param_shapes (dict[str, tuple[int, ...]] | None): An optional dictionary specifying additional
+                                                                    parameters that change from sample to sample
+                                                                    but are known.
+            num_scenarios (int): The number of scenarios for multi-scenario models. Defaults to 1.
+        """
+
+        assert model_sense.upper() in [
+            MIN,
+            MAX,
+        ], f"model_sense must be {MIN} for minimization or {MAX} for maximization!"
+
+        # We store the init_arguments from the child class, so we can create model variants with the same parameters
+        self.init_arguments = {
+            name: getattr(self, name) for name in inspect.signature(type(self).__init__).parameters if name != "self" and hasattr(self, name)
+        }
+
+        # Parse and save input arguments
+        self.var_names = sorted(var_shapes.keys())
+        self.var_shapes = var_shapes
+
+        self.param_to_predict_names = sorted(param_to_predict_shapes.keys())
+        self.param_to_predict_shapes = param_to_predict_shapes
+        extra_param_shapes = extra_param_shapes or {}
+        self.extra_param_names = sorted(extra_param_shapes.keys())
+        self.extra_param_shapes = extra_param_shapes
+        self.all_param_names = self.param_to_predict_names + self.extra_param_names
+
+        self.num_predictions = np.sum([np.prod(self.param_to_predict_shapes[name]) for name in self.param_to_predict_names])
+        self.num_vars = sum([np.prod(shape) for key, shape in var_shapes.items()])
+        self.num_params = sum([np.prod(shape) for shape in self.param_to_predict_shapes.values()])
+
+        self.model_sense = model_sense
+
+    @property
+    def model_sense_int(self) -> int:
+        """
+        Returns the model sense as an integer: 1 for minimization ('MIN') and -1 for maximization ('MAX').
+
+        Returns:
+            int: 1 if model_sense is 'MIN', -1 if model_sense is 'MAX'.
+        """
+        if self.model_sense == MIN:
+            return 1
+        elif self.model_sense == MAX:
+            return -1
+        else:
+            raise NotImplementedError
+
+    @abstractmethod
+    def solve_batch(self, data_batch: dict[str, torch.Tensor]) -> dict[str, torch.Tensor]:
+        """
+        Runs the optimization for a batch of data and computes the optimal decisions.
+        The `data_batch` must include all parameters specified in `param_to_predict_shapes`
+        and `extra_param_shapes`.
+
+        Args:
+            data_batch (dict[str, torch.Tensor]): A dictionary containing input data for the optimization,
+                                                  including predicted parameters and extra parameters.
+
+        Returns:
+            dict[str, torch.Tensor]: A dictionary containing the computed decision variables for the batch,
+                                     matching the keys in `var_shapes`.
+        """
+        raise NotImplementedError("Subclasses must implement solve_batch method.")
+
+    @abstractmethod
+    def get_objective(
+        self,
+        data_batch: dict[str, torch.Tensor],
+        decisions_batch: dict[str, torch.Tensor],
+        predictions_batch: dict[str, torch.Tensor] | None = None,
+    ) -> torch.Tensor:
+        """
+        Computes the objective function value achieved by `decisions_batch` for the given `data_batch`.
+
+        Args:
+            data_batch (dict[str, torch.Tensor]): A dictionary containing input data for the optimization.
+            decisions_batch (dict[str, torch.Tensor]): A dictionary containing the decision variables.
+            predictions_batch (dict[str, torch.Tensor] | None): An optional dictionary containing the
+                                                                predictions for relevant parameters, if applicable.
+                                                                Defaults to None.
+
+        Returns:
+            torch.Tensor: A tensor representing the objective function value(s) for the batch.
+        """
+        raise NotImplementedError("Subclasses must implement get_objective method.")
+
+    def get_penalty(self, x_u: torch.Tensor, data_batch: dict[str, torch.Tensor]) -> torch.Tensor:
+        """
+        Computes the constraint violation (penalty) for a given point `x_u`.
+        This method is used internally by some algorithms for constraint handling.
+
+        Args:
+            x_u (torch.Tensor): The point (decision variables) for which to compute the penalty.
+            data_batch (dict[str, torch.Tensor]): A dictionary containing input data.
+
+        Returns:
+            torch.Tensor: A tensor representing the penalty value(s).
+        """
+        raise NotImplementedError
+
+    def get_reward_gradient(
+        self,
+        decisions_batch: dict[str, torch.Tensor],
+        data_batch: dict[str, torch.Tensor],
+    ) -> torch.Tensor:
+        """
+        Computes the gradient of the reward (objective) function with respect to the solution.
+
+        Args:
+            decisions_batch (dict[str, torch.Tensor]): A dictionary containing the decision variables.
+            data_batch (dict[str, torch.Tensor]): A dictionary containing input data.
+
+        Returns:
+            torch.Tensor: A tensor representing the gradient of the reward function.
+        """
+        raise NotImplementedError
+
+    def create_quadratic_variant(self) -> "OptimizationModel":
+        """
+        Creates a quadratic proxy (QP) variant of the problem.
+        The new model will have the same constraints as the original, but its objective will be
+        to minimize the squared Euclidean distance (L2 norm) between the decision variables `x`
+        and predicted target vector `w` (i.e., minimize ||x-w||^2_2).
+
+        Returns:
+            OptimizationModel: A new instance of the model representing the QP variant.
+        """
+        raise NotImplementedError
+
+    def evaluate(
+        self,
+        data_batch: dict[str, torch.Tensor],
+        decisions_batch: dict[str, torch.Tensor],
+        predictions_batch: dict[str, torch.Tensor] | None = None,
+        epsilon: float = 1e-5,
+        metrics: list[str] | None = None,
+    ) -> dict[str, np.ndarray]:
+        """
+        Evaluates a batch of decisions by computing various metrics such as objective value,
+        absolute regret, relative regret, and symmetric relative regret.
+
+        Args:
+            data_batch (dict[str, torch.Tensor]): A dictionary containing input data for the evaluation.
+                                                  Expected to include 'objective_optimal' if regret is to be computed.
+            decisions_batch (dict[str, torch.Tensor]): A dictionary containing the computed decision variables.
+            predictions_batch (dict[str, torch.Tensor] | None): An optional dictionary containing the
+                                                                predictions for relevant parameters. Defaults to None.
+            epsilon (float): A small value added to the denominator in relative regret calculations to prevent
+                             division by zero. Defaults to 1e-5.
+            metrics (list[str] | None): List of metrics on which to evaluate.
+
+        Returns:
+            dict[str, np.ndarray]: A dictionary containing evaluation metrics, including:
+                                   - 'objective': The objective function value(s).
+                                   - 'abs_regret' (optional): Absolute regret if 'objective_optimal' is in `data_batch`.
+                                   - 'rel_regret' (optional): Relative regret if 'objective_optimal' is in `data_batch`.
+                                   - 'sym_rel_regret' (optional): Symmetric relative regret if 'objective_optimal'
+                                                                  is in `data_batch`.
+        """
+        if metrics is None:  # Check if metrics was not provided
+            metrics = ["abs_regret"]
+
+        eval_dict = {}
+        if "objective" in metrics or "abs_regret" in metrics or "rel_regret" in metrics or "sym_rel_regret" in metrics:
+            objectives = self.get_objective(data_batch, decisions_batch, predictions_batch)
+            if "objective" in metrics:
+                eval_dict["objective"] = objectives.cpu().cpu().detach().numpy().astype(np.float32)
+            if "abs_regret" in metrics or "rel_regret" in metrics or "sym_rel_regret" in metrics:
+                optimal_objectives = data_batch["objective_optimal"]
+                regret = (objectives - optimal_objectives) * float(self.model_sense_int)
+                if "abs_regret" in metrics:
+                    eval_dict["abs_regret"] = regret.cpu().detach().numpy().astype(np.float32)
+                if "rel_regret" in metrics or "sym_rel_regret" in metrics:
+                    relative_regret = regret / optimal_objectives
+                    if "rel_regret" in metrics:
+                        eval_dict["rel_regret"] = relative_regret.cpu().detach().numpy().astype(np.float32)
+                    if "sym_rel_regret" in metrics:
+                        symmetric_relative_regret = regret / (abs(optimal_objectives) + abs(objectives) + epsilon)
+                        eval_dict["sym_rel_regret"] = symmetric_relative_regret.cpu().detach().numpy().astype(np.float32)
+
+        return eval_dict
+
+    def create_saa_variant(self, num_scenarios: int) -> "OptimizationModel":
+        """
+        Creates a Sample Average Approximation (SAA) variant of the optimization problem.
+        This version incorporates multiple scenarios for stochastic optimization.
+
+        Args:
+            num_scenarios (int): The number of scenarios to include in the SAA variant.
+
+        Returns:
+            OptimizationModel: A new instance of the model representing the SAA variant.
+        """
+        assert "num_scenarios" in self.init_arguments, "Concrete model needs to have a num_scenarios argument if you want to create a SAA variant."
+        assert all(
+            arg in self.init_arguments for arg in inspect.signature(type(self).__init__).parameters if arg != "self"
+        ), "Concrete model needs to have all attributes set to arguments if you want to create a SAA variant."
+        init_arguments = {key: item for key, item in self.init_arguments.items() if key != "num_scenarios"}
+
+        return self.__class__(**init_arguments, num_scenarios=num_scenarios)
+
+    def create_copy(self) -> "OptimizationModel":
+        """
+        Creates a shallow copy of the current model instance.
+
+        Returns:
+            OptimizationModel: A new instance of the same model with the same attributes.
+        """
+        return copy.copy(self)