skfolio 0.5.2__py3-none-any.whl → 0.6.0__py3-none-any.whl

skfolio/optimization/convex/_base.py

@@ -18,6 +18,7 @@ import numpy.typing as npt
 import scipy as sc
 import scipy.sparse.linalg as scl
 import sklearn.utils.metadata_routing as skm
+from cvxpy.reductions.solvers.defines import MI_SOLVERS
 
 import skfolio.typing as skt
 from skfolio.measures import RiskMeasure, owa_gmd_weights
@@ -28,7 +29,7 @@ from skfolio.uncertainty_set import (
     BaseMuUncertaintySet,
     UncertaintySet,
 )
-from skfolio.utils.equations import equations_to_matrix
+from skfolio.utils.equations import equations_to_matrix, group_cardinalities_to_matrix
 from skfolio.utils.tools import AutoEnum, cache_method, input_to_array
 
 INSTALLED_SOLVERS = cp.installed_solvers()
@@ -169,6 +170,36 @@ class ConvexOptimization(BaseOptimization, ABC):
         weights.
         The default (`None`) means no maximum long position.
 
+    cardinality : int, optional
+        Specifies the cardinality constraint to limit the number of invested assets
+        (non-zero weights). This feature requires a mixed-integer solver. For an
+        open-source option, we recommend using SCIP by setting `solver="SCIP"`.
+        To install it, use: `pip install cvxpy[SCIP]`. For commercial solvers,
+        supported options include MOSEK, GUROBI, or CPLEX.
+
+    group_cardinalities : dict[str, int], optional
+        A dictionary specifying cardinality constraints for specific groups of assets.
+        The keys represent group names (strings), and the values specify the maximum
+        number of assets allowed in each group. You must provide the groups using the
+        `groups` parameter. This requires a mixed-integer solver (see `cardinality`
+        for more details).
+
+    threshold_long : float | dict[str, float] | array-like of shape (n_assets, ), optional
+        Specifies the minimum weight threshold for assets in the portfolio to be
+        considered as a long position. Assets with weights below this threshold
+        will not be included as part of the portfolio's long positions. This
+        constraint can help eliminate insignificant allocations.
+        This requires a mixed-integer solver (see `cardinality` for more details).
+        It follows the same format as `min_weights` and `max_weights`.
+
+    threshold_short : float | dict[str, float] | array-like of shape (n_assets, ), optional
+        Specifies the maximum weight threshold for assets in the portfolio to be
+        considered as a short position. Assets with weights above this threshold
+        will not be included as part of the portfolio's short positions. This
+        constraint can help control the magnitude of short positions.
+        This requires a mixed-integer solver (see `cardinality` for more details).
+        It follows the same format as `min_weights` and `max_weights`.
+
     transaction_costs : float | dict[str, float] | array-like of shape (n_assets, ), default=0.0
         Transaction costs of the assets. It is used to add linear transaction costs to
         the optimization problem:
@@ -382,7 +413,7 @@ class ConvexOptimization(BaseOptimization, ABC):
         The default (`None`) is use `{"tol_gap_abs": 1e-9, "tol_gap_rel": 1e-9}`
         for the solver "CLARABEL" and the CVXPY default otherwise.
         For more details about solver arguments, check the CVXPY documentation:
-        https://www.cvxpy.org/tutorial/advanced/index.html#setting-solver-options
+        https://www.cvxpy.org/tutorial/solvers
 
     scale_objective : float, optional
         Scale each objective element by this value.
@@ -453,6 +484,10 @@ class ConvexOptimization(BaseOptimization, ABC):
         max_budget: float | None = None,
         max_short: float | None = None,
         max_long: float | None = None,
+        cardinality: int | None = None,
+        group_cardinalities: dict[str, int] | None = None,
+        threshold_long: skt.MultiInput | None = None,
+        threshold_short: skt.MultiInput | None = None,
         transaction_costs: skt.MultiInput = 0.0,
         management_fees: skt.MultiInput = 0.0,
         previous_weights: skt.MultiInput | None = None,
@@ -502,6 +537,10 @@ class ConvexOptimization(BaseOptimization, ABC):
         self.max_budget = max_budget
         self.max_short = max_short
         self.max_long = max_long
+        self.cardinality = cardinality
+        self.group_cardinalities = group_cardinalities
+        self.threshold_long = threshold_long
+        self.threshold_short = threshold_short
         self.min_acceptable_return = min_acceptable_return
         self.transaction_costs = transaction_costs
         self.management_fees = management_fees
@@ -648,32 +687,92 @@ class ConvexOptimization(BaseOptimization, ABC):
         """
         constraints = []
 
-        if self.min_weights is not None:
+        # Clean and convert to array
+        min_weights = self.min_weights
+        max_weights = self.max_weights
+        threshold_long = self.threshold_long
+        threshold_short = self.threshold_short
+        groups = self.groups
+
+        if min_weights is not None:
             min_weights = self._clean_input(
-                self.min_weights,
+                min_weights,
                 n_assets=n_assets,
                 fill_value=0,
                 name="min_weights",
             )
 
+        if max_weights is not None:
+            max_weights = self._clean_input(
+                max_weights,
+                n_assets=n_assets,
+                fill_value=1,
+                name="max_weights",
+            )
+
+        if threshold_long is not None:
+            threshold_long = self._clean_input(
+                threshold_long,
+                n_assets=n_assets,
+                fill_value=0,
+                name="threshold_long",
+            )
+            if np.all(threshold_long == 0):
+                threshold_long = None
+
+        if threshold_short is not None:
+            threshold_short = self._clean_input(
+                threshold_short,
+                n_assets=n_assets,
+                fill_value=0,
+                name="threshold_short",
+            )
+            if np.all(threshold_short == 0):
+                threshold_short = None
+
+        if groups is not None:
+            groups = input_to_array(
+                items=groups,
+                n_assets=n_assets,
+                fill_value="",
+                dim=2,
+                assets_names=(
+                    self.feature_names_in_
+                    if hasattr(self, "feature_names_in_")
+                    else None
+                ),
+                name="groups",
+            )
+
+        is_mip = (
+            (self.cardinality is not None and self.cardinality < n_assets)
+            or (self.group_cardinalities is not None)
+            or self.threshold_long is not None
+            or self.threshold_short is not None
+        )
+
+        if is_mip and self.solver not in MI_SOLVERS:
+            raise ValueError(
+                "You are using constraints that require a mixed-integer solver and "
+                f"{self.solver} doesn't support MIP problems. For an open-source "
+                "option, we recommend using SCIP by setting `solver='SCIP'`. "
+                "To install it, use: `pip install cvxpy[SCIP]`. For commercial "
+                "solvers, supported options include MOSEK, GUROBI, or CPLEX."
+            )
+
+        # Constraints
+        if min_weights is not None:
             if not allow_negative_weights and np.any(min_weights < 0):
                 raise ValueError(
                     f"{self.__class__.__name__} must have non negative `min_weights` "
                     f"constraint otherwise the problem becomes non-convex."
                 )
-
             constraints.append(
                 w * self._scale_constraints
                 >= min_weights * factor * self._scale_constraints
             )
 
-        if self.max_weights is not None:
-            max_weights = self._clean_input(
-                self.max_weights,
-                n_assets=n_assets,
-                fill_value=1,
-                name="max_weights",
-            )
+        if max_weights is not None:
             constraints.append(
                 w * self._scale_constraints
                 <= max_weights * factor * self._scale_constraints
@@ -723,27 +822,80 @@ class ConvexOptimization(BaseOptimization, ABC):
                 == float(self.budget) * factor * self._scale_constraints
             )
 
+        if is_mip:
+            is_short = np.any(min_weights < 0)
+
+            if max_weights is None or min_weights is None:
+                raise ValueError(
+                    "'max_weights' and 'min_weights' must be provided with cardinality "
+                    "constraint"
+                )
+            if np.all(min_weights > 0):
+                raise ValueError(
+                    "Cardinality and Threshold constraint can only be applied "
+                    "if 'min_weights' are not all strictly positive (you allow some "
+                    "weights to be 0)"
+                )
+
+            if self.group_cardinalities is not None and groups is None:
+                raise ValueError(
+                    "When 'group_cardinalities' is provided, you must also "
+                    "also provide 'groups'"
+                )
+
+            if (
+                self.threshold_long is not None
+                and self.threshold_short is None
+                and is_short
+            ):
+                raise ValueError(
+                    "When 'threshold_long' is provided and 'min_weights' can be negative "
+                    "(short position are allowed), then 'threshold_short' must also be "
+                    "provided"
+                )
+
+            if threshold_short is not None and threshold_long is None:
+                raise ValueError(
+                    "When 'threshold_short' is provided, 'threshold_long' must also be "
+                    "provided"
+                )
+
+            if self.threshold_short is not None and is_short:
+                constraints += _mip_weight_constraints_threshold_short(
+                    n_assets=n_assets,
+                    w=w,
+                    factor=factor,
+                    scale_constraints=self._scale_constraints,
+                    cardinality=self.cardinality,
+                    group_cardinalities=self.group_cardinalities,
+                    max_weights=max_weights,
+                    groups=groups,
+                    min_weights=min_weights,
+                    threshold_long=threshold_long,
+                    threshold_short=threshold_short,
+                )
+            else:
+                constraints += _mip_weight_constraints_no_short_threshold(
+                    n_assets=n_assets,
+                    w=w,
+                    factor=factor,
+                    scale_constraints=self._scale_constraints,
+                    cardinality=self.cardinality,
+                    group_cardinalities=self.group_cardinalities,
+                    max_weights=max_weights,
+                    groups=groups,
+                    min_weights=min_weights,
+                    threshold_long=threshold_long,
+                )
+
         if self.linear_constraints is not None:
-            if self.groups is None:
+            if groups is None:
                 if not hasattr(self, "feature_names_in_"):
                     raise ValueError(
                         "If `linear_constraints` is provided you must provide either"
                         " `groups` or `X` as a DataFrame with asset names in columns"
                     )
                 groups = np.asarray([self.feature_names_in_])
-            else:
-                groups = input_to_array(
-                    items=self.groups,
-                    n_assets=n_assets,
-                    fill_value="",
-                    dim=2,
-                    assets_names=(
-                        self.feature_names_in_
-                        if hasattr(self, "feature_names_in_")
-                        else None
-                    ),
-                    name="groups",
-                )
             a_eq, b_eq, a_ineq, b_ineq = equations_to_matrix(
                 groups=groups,
                 equations=self.linear_constraints,
@@ -975,6 +1127,8 @@ class ConvexOptimization(BaseOptimization, ABC):
                 weights = w.value / factor.value
                 problem_values = {
                     name: expression.value / factor.value
+                    if name != "factor"
+                    else expression.value
                     for name, expression in expressions.items()
                 }
                 problem_values["objective"] = (
@@ -1000,7 +1154,7 @@ class ConvexOptimization(BaseOptimization, ABC):
                 if len(params_string) != 0:
                     params_string = f" with parameters {params_string}"
                 msg = (
-                    f"Solver '{self.solver}' failed for {params_string}. Try another"
+                    f"Solver '{self.solver}' failed{params_string}. Try another"
                     " solver, or solve with solver_params=dict(verbose=True) for more"
                     " information"
                 )
@@ -1525,8 +1679,8 @@ class ConvexOptimization(BaseOptimization, ABC):
         n_assets = prior_model.returns.shape[1]
         x = cp.Variable((n_assets, n_assets), symmetric=True)
         y = cp.Variable((n_assets, n_assets), symmetric=True)
-        w_reshaped = cp.reshape(w, (n_assets, 1))
-        factor_reshaped = cp.reshape(factor, (1, 1))
+        w_reshaped = cp.reshape(w, (n_assets, 1), order="F")
+        factor_reshaped = cp.reshape(factor, (1, 1), order="F")
         z1 = cp.vstack([x, w_reshaped.T])
         z2 = cp.vstack([w_reshaped, factor_reshaped])
 
@@ -1972,7 +2126,7 @@ class ConvexOptimization(BaseOptimization, ABC):
             ptf_returns * self._scale_constraints
             - ptf_transaction_cost * self._scale_constraints
             - ptf_management_fee * self._scale_constraints
-            == cp.reshape(z, (observation_nb,)) * self._scale_constraints,
+            == cp.reshape(z, (observation_nb,), order="F") * self._scale_constraints,
             z @ gmd_w.T <= ones @ x.T + y @ ones.T,
         ]
         return risk, constraints
@@ -1988,3 +2142,161 @@ class ConvexOptimization(BaseOptimization, ABC):
     @abstractmethod
     def fit(self, X: npt.ArrayLike, y: npt.ArrayLike | None = None, **fit_params):
         pass
+
+
+def _mip_weight_constraints_no_short_threshold(
+    n_assets: int,
+    w: cp.Variable,
+    factor: skt.Factor,
+    scale_constraints: cp.Constant,
+    cardinality: int | None,
+    group_cardinalities: dict[str, int] | None,
+    max_weights: np.ndarray | None,
+    groups: np.ndarray | None,
+    min_weights: np.ndarray | None,
+    threshold_long: np.ndarray | None,
+) -> list[cp.Expression]:
+    """
+    Create a list of MIP constraints for cardinality and threshold conditions
+    when no short threshold is present. This only requires the creation of a single
+    boolean variable array.
+    """
+    constraints = []
+
+    is_short = np.any(min_weights < 0)
+
+    is_invested_bool = cp.Variable(n_assets, boolean=True)
+
+    if cardinality is not None and cardinality < n_assets:
+        constraints.append(cp.sum(is_invested_bool) <= cardinality)
+
+    if group_cardinalities is not None:
+        a_card, b_card = group_cardinalities_to_matrix(
+            groups=groups,
+            group_cardinalities=group_cardinalities,
+            raise_if_group_missing=False,
+        )
+        constraints.append(a_card @ is_invested_bool - b_card <= 0)
+
+    if isinstance(factor, cp.Variable):
+        is_invested_factor = cp.Variable(n_assets, nonneg=True)
+        # We want (w <= cp.multiply(is_invested_short_bool, max_weights) * factor
+        # but this is not DCP. So we introduce another variable and set
+        # constraint to ensure its value is equal to is_invested_short_bool * factor
+
+        M = 1e3
+        # Big M method to activate or deactivate constraints
+        # In the ratio homogenization procedure, the factor has been calibrated
+        # to be around 0.1-10. By using M=1e3, we ensure that M is large enough while
+        # not too large for improved MIP convergence.
+
+        constraints += [
+            is_invested_factor <= factor,
+            is_invested_factor <= M * is_invested_bool,
+            is_invested_factor >= factor - M * (1 - is_invested_bool),
+        ]
+        is_invested = is_invested_factor
+    else:
+        is_invested = is_invested_bool
+
+    if threshold_long is not None:
+        constraints.append(
+            w * scale_constraints
+            >= cp.multiply(is_invested, threshold_long) * scale_constraints
+        )
+
+    constraints.append(
+        w * scale_constraints
+        <= cp.multiply(is_invested, max_weights) * scale_constraints
+    )
+
+    if is_short:
+        constraints.append(
+            w * scale_constraints
+            >= cp.multiply(is_invested, min_weights) * scale_constraints
+        )
+
+    return constraints
+
+
+def _mip_weight_constraints_threshold_short(
+    n_assets: int,
+    w: cp.Variable,
+    factor: skt.Factor,
+    scale_constraints: cp.Constant,
+    max_weights: np.ndarray,
+    min_weights: np.ndarray,
+    threshold_long: np.ndarray,
+    threshold_short: np.ndarray,
+    cardinality: int | None,
+    group_cardinalities: dict[str, int] | None,
+    groups: np.ndarray | None,
+) -> list[cp.Expression]:
+    """
+    Create a list of MIP constraints for cardinality and threshold constraints
+    when a short threshold is allowed. This requires the creation of two boolean
+    variable arrays, one for long positions and one for short positions.
+    """
+    constraints = []
+
+    is_invested_short_bool = cp.Variable(n_assets, boolean=True)
+    is_invested_long_bool = cp.Variable(n_assets, boolean=True)
+    is_invested_bool = is_invested_short_bool + is_invested_long_bool
+
+    if cardinality is not None and cardinality < n_assets:
+        constraints.append(cp.sum(is_invested_bool) <= cardinality)
+
+    if group_cardinalities is not None:
+        a_card, b_card = group_cardinalities_to_matrix(
+            groups=groups,
+            group_cardinalities=group_cardinalities,
+            raise_if_group_missing=False,
+        )
+        constraints.append(a_card @ is_invested_bool - b_card <= 0)
+
+    M = 1e3
+    # Big M method to activate or deactivate constraints
+    # In the ratio homogenization procedure, the factor has been calibrated
+    # to be around 0.1-10. By using M=1e3, we ensure that M is large enough while
+    # not too large for improved MIP convergence.
+
+    if isinstance(factor, cp.Variable):
+        is_invested_short_factor = cp.Variable(n_assets, nonneg=True)
+        is_invested_long_factor = cp.Variable(n_assets, nonneg=True)
+        # We want (w <= cp.multiply(is_invested_short_bool, max_weights) * factor
+        # but this is not DCP. So we introduce another variable and set
+        # constraint to ensure its value is equal to is_invested_short_bool * factor
+
+        constraints += [
+            is_invested_short_factor <= factor,
+            is_invested_long_factor <= factor,
+            is_invested_short_factor <= M * is_invested_short_bool,
+            is_invested_long_factor <= M * is_invested_long_bool,
+            is_invested_short_factor >= factor - M * (1 - is_invested_short_bool),
+            is_invested_long_factor >= factor - M * (1 - is_invested_long_bool),
+        ]
+        is_invested_short = is_invested_short_factor
+        is_invested_long = is_invested_long_factor
+    else:
+        is_invested_short = is_invested_short_bool
+        is_invested_long = is_invested_long_bool
+
+    constraints += [
+        is_invested_bool <= 1.0,
+        w * scale_constraints
+        <= cp.multiply(is_invested_long, max_weights) * scale_constraints,
+        w * scale_constraints
+        >= cp.multiply(is_invested_short, min_weights) * scale_constraints,
+        # Apply threshold_long if is_invested_long == 1,
+        # unrestricted if is_invested_long == 0
+        w * scale_constraints
+        >= cp.multiply(is_invested_long, threshold_long) * scale_constraints
+        - M * (1 - is_invested_long_bool) * scale_constraints,
+        # # Apply threshold_short if is_invested_short == 1,
+        # # unrestricted if is_invested_short == 0
+        w * scale_constraints
+        <= cp.multiply(is_invested_short, threshold_short) * scale_constraints
+        + M * (1 - is_invested_short_bool) * scale_constraints,
+    ]
+
+    return constraints

skfolio/optimization/convex/_maximum_diversification.py

@@ -364,7 +364,7 @@ class MaximumDiversification(MeanRisk):
     ):
         super().__init__(
             objective_function=ObjectiveFunction.MAXIMIZE_RATIO,
-            risk_measure=RiskMeasure.VARIANCE,
+            risk_measure=RiskMeasure.STANDARD_DEVIATION,
             prior_estimator=prior_estimator,
             min_weights=min_weights,
             max_weights=max_weights,

skfolio/optimization/convex/_mean_risk.py

@@ -1,11 +1,12 @@
 """Mean Risk Optimization estimator."""
 
+import warnings
+
 # Copyright (c) 2023
 # Author: Hugo Delatte <delatte.hugo@gmail.com>
 # License: BSD 3 clause
 # The optimization features are derived
 # from Riskfolio-Lib, Copyright (c) 2020-2023, Dany Cajas, Licensed under BSD 3 clause.
-
 import cvxpy as cp
 import numpy as np
 import numpy.typing as npt
@@ -144,6 +145,11 @@ class MeanRisk(ConvexOptimization):
         returns and Cholesky decomposition of the covariance.
         The default (`None`) is to use :class:`~skfolio.prior.EmpiricalPrior`.
 
+    efficient_frontier_size : int, optional
+        If provided, it represents the number of Pareto-optimal portfolios along the
+        efficient frontier to be computed. This parameter can only be used with
+        `objective_function = ObjectiveFunction.MINIMIZE_RISK`.
+
     min_weights : float | dict[str, float] | array-like of shape (n_assets, ) | None, default=0.0
         Minimum assets weights (weights lower bounds).
         If a float is provided, it is applied to each asset.
@@ -213,6 +219,36 @@ class MeanRisk(ConvexOptimization):
         weights.
         The default (`None`) means no maximum long position.
 
+    cardinality : int, optional
+        Specifies the cardinality constraint to limit the number of invested assets
+        (non-zero weights). This feature requires a mixed-integer solver. For an
+        open-source option, we recommend using SCIP by setting `solver="SCIP"`.
+        To install it, use: `pip install cvxpy[SCIP]`. For commercial solvers,
+        supported options include MOSEK, GUROBI, or CPLEX.
+
+    group_cardinalities : dict[str, int], optional
+        A dictionary specifying cardinality constraints for specific groups of assets.
+        The keys represent group names (strings), and the values specify the maximum
+        number of assets allowed in each group. You must provide the groups using the
+        `groups` parameter. This requires a mixed-integer solver (see `cardinality`
+        for more details).
+
+    threshold_long : float | dict[str, float] | array-like of shape (n_assets, ), optional
+        Specifies the minimum weight threshold for assets in the portfolio to be
+        considered as a long position. Assets with weights below this threshold
+        will not be included as part of the portfolio's long positions. This
+        constraint can help eliminate insignificant allocations.
+        This requires a mixed-integer solver (see `cardinality` for more details).
+        It follows the same format as `min_weights` and `max_weights`.
+
+    threshold_short : float | dict[str, float] | array-like of shape (n_assets, ), optional
+        Specifies the maximum weight threshold for assets in the portfolio to be
+        considered as a short position. Assets with weights above this threshold
+        will not be included as part of the portfolio's short positions. This
+        constraint can help control the magnitude of short positions.
+        This requires a mixed-integer solver (see `cardinality` for more details).
+        It follows the same format as `min_weights` and `max_weights`.
+
     transaction_costs : float | dict[str, float] | array-like of shape (n_assets, ), default=0.0
         Transaction costs of the assets. It is used to add linear transaction costs to
         the optimization problem:
@@ -486,9 +522,10 @@ class MeanRisk(ConvexOptimization):
     solver_params : dict, optional
         Solver parameters. For example, `solver_params=dict(verbose=True)`.
         The default (`None`) is use `{"tol_gap_abs": 1e-9, "tol_gap_rel": 1e-9}`
-        for the solver "CLARABEL" and the CVXPY default otherwise.
+        for "CLARABEL", `{"numerics/feastol": 1e-8, "limits/gap": 1e-8}` for SCIP
+        and the solver default otherwise.
         For more details about solver arguments, check the CVXPY documentation:
-        https://www.cvxpy.org/tutorial/advanced/index.html#setting-solver-options
+        https://www.cvxpy.org/tutorial/solvers
 
     scale_objective : float, optional
         Scale each objective element by this value.
@@ -511,7 +548,7 @@ class MeanRisk(ConvexOptimization):
     portfolio_params :  dict, optional
         Portfolio parameters passed to the portfolio evaluated by the `predict` and
         `score` methods. If not provided, the `name`, `transaction_costs`,
-        `management_fees`, `previous_weights` and `risk_free_rate` are copied from the 
+        `management_fees`, `previous_weights` and `risk_free_rate` are copied from the
         optimization model and passed to the portfolio.
 
     Attributes
@@ -557,6 +594,10 @@ class MeanRisk(ConvexOptimization):
         max_budget: float | None = None,
         max_short: float | None = None,
         max_long: float | None = None,
+        cardinality: int | None = None,
+        group_cardinalities: dict[str, int] | None = None,
+        threshold_long: skt.MultiInput | None = None,
+        threshold_short: skt.MultiInput | None = None,
         transaction_costs: skt.MultiInput = 0.0,
         management_fees: skt.MultiInput = 0.0,
         previous_weights: skt.MultiInput | None = None,
@@ -617,6 +658,10 @@ class MeanRisk(ConvexOptimization):
             max_budget=max_budget,
             max_short=max_short,
             max_long=max_long,
+            cardinality=cardinality,
+            group_cardinalities=group_cardinalities,
+            threshold_long=threshold_long,
+            threshold_short=threshold_short,
             transaction_costs=transaction_costs,
             management_fees=management_fees,
             previous_weights=previous_weights,
@@ -734,13 +779,42 @@ class MeanRisk(ConvexOptimization):
         n_observations, n_assets = prior_model.returns.shape
 
         # set solvers params
-        if self.solver == "CLARABEL":
-            self._set_solver_params(default={"tol_gap_abs": 1e-9, "tol_gap_rel": 1e-9})
-        else:
-            self._set_solver_params(default=None)
+        match self.solver:
+            case "CLARABEL":
+                self._set_solver_params(
+                    default={"tol_gap_abs": 1e-9, "tol_gap_rel": 1e-9}
+                )
+            case "SCIP":
+                self._set_solver_params(
+                    default={"numerics/feastol": 1e-8, "limits/gap": 1e-8}
+                )
+            case _:
+                self._set_solver_params(default=None)
 
-        # set scales
+        # set scales and check measure
         if self.objective_function == ObjectiveFunction.MAXIMIZE_RATIO:
+            if self.overwrite_expected_return is not None:
+                if self.risk_measure == RiskMeasure.VARIANCE:
+                    warnings.warn(
+                        "When selecting 'MAXIMIZE_RATIO' with 'VARIANCE', the "
+                        "optimization will return the maximum Sharpe Ratio portfolio. "
+                        "This is because the mean/variance ratio is not a "
+                        "1-homogeneous function, unlike the mean/std. To suppress this"
+                        "warning, replace 'VARIANCE' by 'STANDARD_DEVIATION'",
+                        stacklevel=2,
+                    )
+
+                elif self.risk_measure == RiskMeasure.SEMI_VARIANCE:
+                    warnings.warn(
+                        "When selecting 'MAXIMIZE_RATIO' with 'SEMI_VARIANCE', the "
+                        "optimization will return the maximum Sortino Ratio portfolio. "
+                        "This is because the mean/semi-variance ratio is not a "
+                        "1-homogeneous function, unlike the mean/semi-std ratio. To "
+                        "suppress this warning, replace 'SEMI_VARIANCE' by "
+                        "'SEMI_DEVIATION'",
+                        stacklevel=2,
+                    )
+
             self._set_scale_objective(default=1)
             self._set_scale_constraints(default=1)
         else:
@@ -959,31 +1033,38 @@ class MeanRisk(ConvexOptimization):
                     + custom_objective * self._scale_objective
                 )
             case ObjectiveFunction.MAXIMIZE_RATIO:
+                homogenization_factor = _optimal_homogenization_factor(
+                    mu=prior_model.mu
+                )
+
                 if expected_return.is_affine():
                     # Charnes-Cooper's variable transformation for Fractional
-                    # Programming problem :Max(f1/f2) with f2 linear
+                    # Programming problem Max(f1/f2) with f2 linear and with
+                    # 1-homogeneous function (homogeneous technique)
                     constraints += [
                         expected_return * self._scale_constraints
                         - cp.Constant(self.risk_free_rate)
                         * factor
                         * self._scale_constraints
-                        == cp.Constant(1) * self._scale_constraints
+                        == cp.Constant(homogenization_factor) * self._scale_constraints
                     ]
                 else:
                     # Schaible's generalization of Charnes-Cooper's variable
                     # transformation for Fractional Programming problem :Max(f1/f2)
-                    # with f1 concave instead of linear: Schaible,"Parameter-free
-                    # Convex Equivalent and Dual Programs of Fractional Programming
-                    # Problems".
+                    # with f1 concave instead of linear and with 1-homogeneous function.
+                    # (homogeneous technique)
+                    # Schaible,"Parameter-free Convex Equivalent and Dual Programs of
+                    # Fractional Programming Problems".
                     # The condition to work is f1 >= 0, so we need to raise an user
                     # warning when it's not the case.
                     # TODO: raise user warning when f1<0
+
                     constraints += [
                         expected_return * self._scale_constraints
                         - cp.Constant(self.risk_free_rate)
                         * factor
                         * self._scale_constraints
-                        >= cp.Constant(1) * self._scale_constraints
+                        >= cp.Constant(homogenization_factor) * self._scale_constraints
                     ]
                 objective = cp.Minimize(
                     risk * self._scale_objective
@@ -1014,3 +1095,27 @@ class MeanRisk(ConvexOptimization):
         )
 
         return self
+
+
+def _optimal_homogenization_factor(mu: np.ndarray) -> float:
+    """
+    Compute the optimal homogenization factor for ratio optimization based on expected
+    returns.
+
+    While a default value of 1 is commonly used in textbooks for simplicity,
+    fine-tuning this factor based on the underlying data can enhance convergence.
+    Additionally, using a data-driven approach to determine this factor can improve the
+    robustness of certain constraints, such as the calibration of big M methods.
+
+    Parameters
+    ----------
+    mu : ndarray of shape (n_assets,)
+        Vector of expected returns.
+
+    Returns
+    -------
+    value : float
+        Homogenization factor.
+    """
+
+    return min(1e3, max(1e-3, np.mean(np.abs(mu))))

skfolio/utils/equations.py

@@ -16,7 +16,7 @@ from skfolio.exceptions import (
     GroupNotFoundError,
 )
 
-__all__ = ["equations_to_matrix"]
+__all__ = ["equations_to_matrix", "group_cardinalities_to_matrix"]
 
 _EQUALITY_OPERATORS = {"==", "="}
 _INEQUALITY_OPERATORS = {">=", "<="}
@@ -132,6 +132,63 @@ def equations_to_matrix(
     )
 
 
+def group_cardinalities_to_matrix(
+    groups: npt.ArrayLike,
+    group_cardinalities: dict[str, int],
+    raise_if_group_missing: bool = False,
+) -> tuple[np.ndarray, np.ndarray]:
+    """Convert a list of linear equations into the left and right matrices of the
+    inequality A <= B and equality A == B.
+
+    Parameters
+    ----------
+    groups : array-like of shape (n_groups, n_assets)
+       2D array of assets groups.
+
+       Examples:
+             groups = np.array(
+                [
+                    ["Equity", "Equity", "Equity", "Bond"],
+                    ["US", "Europe", "Japan", "US"],
+                ]
+            )
+
+    group_cardinalities : dict[str, int]
+       Dictionary of cardinality constraint per group.
+       Examples: {"Equity": 1, "US": 3}
+
+    raise_if_group_missing : bool, default=False
+        If this is set to True, an error is raised when a group is not found in the
+        groups, otherwise only a warning is shown.
+        The default is False.
+
+    Returns
+    -------
+    left_inequality: ndarray of shape (n_constraints, n_assets)
+    right_inequality: ndarray of shape (n_constraints,)
+        The left and right matrices of the cardinality inequality.
+    """
+    groups = _validate_groups(groups, name="group")
+
+    a_inequality = []
+    b_inequality = []
+
+    for group, card in group_cardinalities.items():
+        try:
+            arr = _matching_array(values=groups, key=group, sum_to_one=False)
+            a_inequality.append(arr)
+            b_inequality.append(card)
+
+        except GroupNotFoundError as e:
+            if raise_if_group_missing:
+                raise
+            warnings.warn(str(e), stacklevel=2)
+    return (
+        np.array(a_inequality),
+        np.array(b_inequality),
+    )
+
+
 def _validate_groups(groups: npt.ArrayLike, name: str = "groups") -> np.ndarray:
     """Validate groups by checking its dim and if group names don't appear in multiple
     levels and convert to numpy array.

{skfolio-0.5.2.dist-info → skfolio-0.6.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: skfolio
-Version: 0.5.2
+Version: 0.6.0
 Summary: Portfolio optimization built on top of scikit-learn
 Author-email: Hugo Delatte <delatte.hugo@gmail.com>
 Maintainer-email: Hugo Delatte <delatte.hugo@gmail.com>
@@ -64,6 +64,7 @@ Requires-Dist: scikit-learn >=1.5.0
 Requires-Dist: joblib >=1.3.2
 Requires-Dist: plotly >=5.22.0
 Provides-Extra: docs
+Requires-Dist: cvxpy[scip] ; extra == 'docs'
 Requires-Dist: Sphinx ; extra == 'docs'
 Requires-Dist: sphinx-gallery ; extra == 'docs'
 Requires-Dist: sphinx-design ; extra == 'docs'
@@ -81,6 +82,7 @@ Requires-Dist: jupyterlite-sphinx ; extra == 'docs'
 Requires-Dist: jupyterlite-pyodide-kernel ; extra == 'docs'
 Requires-Dist: nbformat ; extra == 'docs'
 Provides-Extra: tests
+Requires-Dist: cvxpy[scip] ; extra == 'tests'
 Requires-Dist: pytest ; extra == 'tests'
 Requires-Dist: pytest-cov ; extra == 'tests'
 Requires-Dist: ruff ; extra == 'tests'

{skfolio-0.5.2.dist-info → skfolio-0.6.0.dist-info}/RECORD

@@ -49,10 +49,10 @@ skfolio/optimization/cluster/hierarchical/_base.py,sha256=l8rJHCH_79FOPdDL2I0dmA
 skfolio/optimization/cluster/hierarchical/_herc.py,sha256=LPtUrvyW9G60OZhMWlZH_GHZHdX8mJHksrYGB-WPRVg,20358
 skfolio/optimization/cluster/hierarchical/_hrp.py,sha256=dn6EKiTJ1wkoFhPdst6vlXnSQvXSYsMtB2zaGNVPpyA,18115
 skfolio/optimization/convex/__init__.py,sha256=F6BPFikTo0B-7JCKazqLGEwM3RkgTNbFm5GAGkaq9Uo,570
-skfolio/optimization/convex/_base.py,sha256=P1rSw1oJAZR_BuOxJeXJrYHlkFD0AwCOaBl3mj54E8U,76413
+skfolio/optimization/convex/_base.py,sha256=6x3W7bk1mxcTQMW1eWZiO-OqF1KbumrPVuzBSHMJoEA,89396
 skfolio/optimization/convex/_distributionally_robust.py,sha256=tw_UNSDfAXP02khE10hpmcdlz3DQXQD7ttDqFDSHV1E,17811
-skfolio/optimization/convex/_maximum_diversification.py,sha256=IVKVbK7bh4KPkhpNWLLerl-qx9Qcmf2cIIRotP8r8nI,19500
-skfolio/optimization/convex/_mean_risk.py,sha256=H4Ik6vvIETdAZnNCA4Jhk_OTirHJg26KQZ5iLsXgaHo,44176
+skfolio/optimization/convex/_maximum_diversification.py,sha256=TDJN39E6whFxBlUIEanAyTDxNZ6X2rAf17gQ4H_bN60,19510
+skfolio/optimization/convex/_mean_risk.py,sha256=yN15Gjv-JoLrhIta2PQJ9WBzIiohd8ofETSl7ELE7xc,49383
 skfolio/optimization/convex/_risk_budgeting.py,sha256=VXm6vUeB-BDEn6KhWxg1-9UmjqpFR1E04SM4NLcNuBY,23510
 skfolio/optimization/ensemble/__init__.py,sha256=8TXxcxH2_gG3C1xtgQj9OHHr0Le8lhdejtlURL6T3ZY,158
 skfolio/optimization/ensemble/_base.py,sha256=GaNDQu6ivosYuwMrb-b0PhToCsNrmhSYyXkxeM8W4rU,3399
@@ -84,12 +84,12 @@ skfolio/uncertainty_set/_bootstrap.py,sha256=BRD8LhGKULkqqCBjLqU1EtCAMBkLJKEXJyg
 skfolio/uncertainty_set/_empirical.py,sha256=ACqMVTBKibJm6E3IP4TOi3MYsxKMhiEoix5D_fp9X-w,9364
 skfolio/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 skfolio/utils/bootstrap.py,sha256=3zY2kO_GQURKEcQMCasJOSByde9Mt2IAi3KJH0_a4mk,3550
-skfolio/utils/equations.py,sha256=MQ1w3VSM2n_j9bTIKAQA716aWKYyUqtw5yM2bU-9t-M,13745
+skfolio/utils/equations.py,sha256=9XFcRB6_UuxlAR-dWwf1XPxAHO9p5DfcC-bF5onr7Ws,15539
 skfolio/utils/sorting.py,sha256=lSjMvH2L-sSj-06B3MlwBrH1rtjCeGEe4hG894W7TE0,3504
 skfolio/utils/stats.py,sha256=mWMpJ_XBy400kx7GlwBvR4Fwo8ValOZ9J3VDLODDaHQ,16995
 skfolio/utils/tools.py,sha256=4KrmBR9jOLiI6j0hb27gsPC--OHXo4Sp1xl-6i-k9Tg,20925
-skfolio-0.5.2.dist-info/LICENSE,sha256=F6Gi-ZJX5BlVzYK8R9NcvAkAsKa7KO29xB1OScbrH6Q,1526
-skfolio-0.5.2.dist-info/METADATA,sha256=YCnMzyRfmhzQpJ6P6VySw-DJlYuHBdw4bkcfIrR_Gc8,19906
-skfolio-0.5.2.dist-info/WHEEL,sha256=R06PA3UVYHThwHvxuRWMqaGcr-PuniXahwjmQRFMEkY,91
-skfolio-0.5.2.dist-info/top_level.txt,sha256=NXEaoS9Ms7t32gxkb867nV0OKlU0KmssL7IJBVo0fJs,8
-skfolio-0.5.2.dist-info/RECORD,,
+skfolio-0.6.0.dist-info/LICENSE,sha256=F6Gi-ZJX5BlVzYK8R9NcvAkAsKa7KO29xB1OScbrH6Q,1526
+skfolio-0.6.0.dist-info/METADATA,sha256=BhIndmPyWFZBZCS5pPV62urBCBuF98-s5mPC3z_g8ss,19997
+skfolio-0.6.0.dist-info/WHEEL,sha256=R06PA3UVYHThwHvxuRWMqaGcr-PuniXahwjmQRFMEkY,91
+skfolio-0.6.0.dist-info/top_level.txt,sha256=NXEaoS9Ms7t32gxkb867nV0OKlU0KmssL7IJBVo0fJs,8
+skfolio-0.6.0.dist-info/RECORD,,