Rename least_core_value to subsidy

The term value in pyDVL is meant for data values

Author: AnesBenmerzoug

src/pydvl/value/least_core/_common.py

@@ -77,19 +77,19 @@ def _solve_least_core_linear_program(
                 "maximum number of iterations in options",
                 RuntimeWarning,
             )
-        least_core_value = e.value.item()
-        # HACK: sometimes the returned least core value
+        subsidy = e.value.item()
+        # HACK: sometimes the returned least core subsidy
         # is negative but very close to 0
         # to avoid any problems with the subsequent quadratic program
         # we just set it to 0.0
-        if least_core_value < 0:
+        if subsidy < 0:
             warnings.warn(
-                f"Least core value '{least_core_value}' is negative but close to zero. "
+                f"Least core subsidy e={subsidy} is negative but close to zero. "
                 "It will be set to 0.0",
                 RuntimeWarning,
             )
-            least_core_value = 0.0
-        return x.value, least_core_value
+            subsidy = 0.0
+        return x.value, subsidy
 
     if problem.status in cp.settings.INF_OR_UNB:
         warnings.warn(
@@ -100,7 +100,7 @@ def _solve_least_core_linear_program(
 
 
 def _solve_egalitarian_least_core_quadratic_program(
-    least_core_value: float,
+    subsidy: float,
     A_eq: NDArray[np.float_],
     b_eq: NDArray[np.float_],
     A_lb: NDArray[np.float_],
@@ -122,7 +122,7 @@ def _solve_egalitarian_least_core_quadratic_program(
     :math:`b_{ub}`, :math:`b_{eq}`, :math:`l`, and :math:`u` are vectors; and
     :math:`A_{ub}` and :math:`A_{eq}` are matrices.
 
-    :param least_core_subsidy: Minimal subsidy returned by :func:`_solve_least_core_linear_program`
+    :param subsidy: Minimal subsidy returned by :func:`_solve_least_core_linear_program`
     :param A_eq: The equality constraint matrix. Each row of ``A_eq`` specifies the
         coefficients of a linear equality constraint on ``x``.
     :param b_eq: The equality constraint vector. Each element of ``A_eq @ x`` must equal
@@ -137,16 +137,16 @@ def _solve_egalitarian_least_core_quadratic_program(
     """
     logger.debug(f"Solving quadratic program : {A_eq=}, {b_eq=}, {A_lb=}, {b_lb=}")
 
-    if least_core_value < 0:
-        raise ValueError("Passed least core value should be positive.")
+    if subsidy < 0:
+        raise ValueError("The least core subsidy must be non-negative.")
 
     n_variables = A_eq.shape[1]
 
     x = cp.Variable(n_variables)
     objective = cp.Minimize(cp.norm2(x))
     constraints = [
         A_eq @ x == b_eq,
-        A_lb @ x + least_core_value * np.ones(len(A_lb)) >= b_lb,
+        A_lb @ x + subsidy * np.ones(len(A_lb)) >= b_lb,
     ]
     problem = cp.Problem(objective, constraints)
 

src/pydvl/value/least_core/montecarlo.py

@@ -165,29 +165,30 @@ def montecarlo_least_core(
     A_lb, unique_indices = np.unique(A_lb, return_index=True, axis=0)
     b_lb = b_lb[unique_indices]
 
-    _, least_core_value = _solve_least_core_linear_program(
+    _, subsidy = _solve_least_core_linear_program(
         A_eq=A_eq, b_eq=b_eq, A_lb=A_lb, b_lb=b_lb, **options
     )
 
     values: Optional[NDArray[np.float_]]
 
-    if least_core_value is None:
+    if subsidy is None:
         logger.debug("No values were found")
         status = ValuationStatus.Failed
         values = np.empty(n)
         values[:] = np.nan
-        least_core_value = np.nan
+        subsidy = np.nan
+
         return ValuationResult(
             algorithm="montecarlo_least_core",
             status=status,
             values=values,
+            subsidy=subsidy,
             stderr=None,
             data_names=u.data.data_names,
-            least_core_value=least_core_value,
         )
 
     values = _solve_egalitarian_least_core_quadratic_program(
-        least_core_value,
+        subsidy,
         A_eq=A_eq,
         b_eq=b_eq,
         A_lb=A_lb,
@@ -200,15 +201,15 @@ def montecarlo_least_core(
         status = ValuationStatus.Failed
         values = np.empty(n)
         values[:] = np.nan
-        least_core_value = np.nan
+        subsidy = np.nan
     else:
         status = ValuationStatus.Converged
 
     return ValuationResult(
         algorithm="montecarlo_least_core",
         status=status,
         values=values,
+        subsidy=subsidy,
         stderr=None,
         data_names=u.data.data_names,
-        least_core_value=least_core_value,
     )

src/pydvl/value/least_core/naive.py

@@ -82,29 +82,30 @@ def exact_least_core(
     b_lb = utility_values
     b_eq = utility_values[-1:]
 
-    _, least_core_value = _solve_least_core_linear_program(
+    _, subsidy = _solve_least_core_linear_program(
         A_eq=A_eq, b_eq=b_eq, A_lb=A_lb, b_lb=b_lb, **options
     )
 
     values: Optional[NDArray[np.float_]]
 
-    if least_core_value is None:
+    if subsidy is None:
         logger.debug("No values were found")
         status = ValuationStatus.Failed
         values = np.empty(n)
         values[:] = np.nan
-        least_core_value = np.nan
+        subsidy = np.nan
+
         return ValuationResult(
             algorithm="exact_least_core",
             status=status,
             values=values,
+            subsidy=subsidy,
             stderr=None,
             data_names=u.data.data_names,
-            least_core_value=least_core_value,
         )
 
     values = _solve_egalitarian_least_core_quadratic_program(
-        least_core_value,
+        subsidy,
         A_eq=A_eq,
         b_eq=b_eq,
         A_lb=A_lb,
@@ -117,15 +118,15 @@ def exact_least_core(
         status = ValuationStatus.Failed
         values = np.empty(n)
         values[:] = np.nan
-        least_core_value = np.nan
+        subsidy = np.nan
     else:
         status = ValuationStatus.Converged
 
     return ValuationResult(
         algorithm="exact_least_core",
         status=status,
         values=values,
+        subsidy=subsidy,
         stderr=None,
         data_names=u.data.data_names,
-        least_core_value=least_core_value,
     )

tests/value/least_core/conftest.py

@@ -56,14 +56,14 @@ def miner_utility(request) -> Tuple[Utility, ValuationResult]:
     u = MinerUtility(n_miners=n_miners)
     if n_miners % 2 == 0:
         exact_values = np.array([0.5] * n_miners)
-        least_core_value = 0.0
+        subsidy = 0.0
     else:
         exact_values = np.array([(n_miners - 1) / (2 * n_miners)] * n_miners)
-        least_core_value = (n_miners - 1) / (2 * n_miners)
+        subsidy = (n_miners - 1) / (2 * n_miners)
     result = ValuationResult(
         algorithm="exact",
         values=exact_values,
-        least_core_value=least_core_value,
+        subsidy=subsidy,
         stderr=np.zeros_like(exact_values),
         data_names=np.arange(len(exact_values)),
         status=ValuationStatus.Converged,

tests/value/least_core/test_montecarlo.py

@@ -22,9 +22,7 @@ def test_montecarlo_least_core(miner_utility, rtol, n_iterations):
     values = montecarlo_least_core(
         u, n_iterations=n_iterations, progress=False, n_jobs=4
     )
-    check_values(
-        values, exact_values, rtol=rtol, extra_values_names=["least_core_value"]
-    )
+    check_values(values, exact_values, rtol=rtol, extra_values_names=["subsidy"])
 
 
 @pytest.mark.parametrize(

tests/value/least_core/test_naive.py

@@ -13,4 +13,4 @@ def test_naive_least_core(miner_utility):
     u, exact_values = miner_utility
     values = exact_least_core(u, progress=False)
     check_total_value(u, values)
-    check_values(values, exact_values, extra_values_names=["least_core_value"])
+    check_values(values, exact_values, extra_values_names=["subsidy"])