Implement SetPackPerturber and SetCoverPerturber

miplearn/problems/setpack.py

@@ -11,7 +11,7 @@ from gurobipy import GRB
 from scipy.stats import uniform, randint
 from scipy.stats.distributions import rv_frozen
 
-from .setcover import SetCoverGenerator
+from .setcover import SetCoverGenerator, SetCoverPerturber
 from miplearn.solvers.gurobi import GurobiModel
 from ..io import read_pkl_gz
 
@@ -23,24 +23,55 @@ class SetPackData:
 
 
 class SetPackGenerator:
+    """Random instance generator for the Set Packing Problem.
+
+    Generates instances by creating a new random incidence matrix for each
+    instance, where the number of elements, sets, density, and costs are sampled
+    from user-provided probability distributions.
+    """
+
     def __init__(
         self,
         n_elements: rv_frozen = randint(low=50, high=51),
         n_sets: rv_frozen = randint(low=100, high=101),
         costs: rv_frozen = uniform(loc=0.0, scale=100.0),
-        costs_jitter: rv_frozen = uniform(loc=-5.0, scale=10.0),
         K: rv_frozen = uniform(loc=25.0, scale=0.0),
         density: rv_frozen = uniform(loc=0.02, scale=0.00),
-        fix_sets: bool = True,
     ) -> None:
+        """Initialize the problem generator.
+
+        Parameters
+        ----------
+        n_elements: rv_discrete
+            Probability distribution for number of elements.
+        n_sets: rv_discrete
+            Probability distribution for number of sets.
+        costs: rv_continuous
+            Probability distribution for base set costs.
+        K: rv_continuous
+            Probability distribution for cost scaling factor based on set size.
+        density: rv_continuous
+            Probability distribution for incidence matrix density.
+        """
+        assert isinstance(
+            n_elements, rv_frozen
+        ), "n_elements should be a SciPy probability distribution"
+        assert isinstance(
+            n_sets, rv_frozen
+        ), "n_sets should be a SciPy probability distribution"
+        assert isinstance(
+            costs, rv_frozen
+        ), "costs should be a SciPy probability distribution"
+        assert isinstance(K, rv_frozen), "K should be a SciPy probability distribution"
+        assert isinstance(
+            density, rv_frozen
+        ), "density should be a SciPy probability distribution"
         self.gen = SetCoverGenerator(
             n_elements=n_elements,
             n_sets=n_sets,
             costs=costs,
-            costs_jitter=costs_jitter,
             K=K,
             density=density,
-            fix_sets=fix_sets,
         )
 
     def generate(self, n_samples: int) -> List[SetPackData]:
@@ -53,6 +84,47 @@ class SetPackGenerator:
         ]
 
 
+class SetPackPerturber:
+    """Perturbation generator for existing Set Packing instances.
+
+    Takes an existing SetPackData instance and generates new instances
+    by applying randomization factors to the existing costs while keeping the
+    incidence matrix fixed.
+    """
+
+    def __init__(
+        self,
+        costs_jitter: rv_frozen = uniform(loc=0.9, scale=0.2),
+    ):
+        """Initialize the perturbation generator.
+
+        Parameters
+        ----------
+        costs_jitter: rv_continuous
+            Probability distribution for randomization factors applied to set costs.
+        """
+        assert isinstance(
+            costs_jitter, rv_frozen
+        ), "costs_jitter should be a SciPy probability distribution"
+        self.costs_jitter = costs_jitter
+
+    def perturb(
+        self,
+        instance: SetPackData,
+        n_samples: int,
+    ) -> List[SetPackData]:
+        def _sample() -> SetPackData:
+            (_, n_sets) = instance.incidence_matrix.shape
+            jitter_factors = self.costs_jitter.rvs(n_sets)
+            costs = np.round(instance.costs * jitter_factors, 2)
+            return SetPackData(
+                costs=costs,
+                incidence_matrix=instance.incidence_matrix,
+            )
+
+        return [_sample() for _ in range(n_samples)]
+
+
 def build_setpack_model_gurobipy(data: Union[str, SetPackData]) -> GurobiModel:
     if isinstance(data, str):
         data = read_pkl_gz(data)