DOC better internal docstring for Cython enet_coordinate_descent (#31919)

lorentzenchr · web-flow · commit 3adeabd5aa34 · 2025-08-12T04:24:21.000+05:00
diff --git a/sklearn/linear_model/_cd_fast.pyx b/sklearn/linear_model/_cd_fast.pyx
@@ -110,12 +110,40 @@ def enet_coordinate_descent(
     bint random=0,
     bint positive=0
 ):
-    """Cython version of the coordinate descent algorithm
-        for Elastic-Net regression
+    """
+    Cython version of the coordinate descent algorithm for Elastic-Net regression.
 
-        We minimize
+    The algorithm mostly follows [Friedman 2010].
+    We minimize the primal
+
+        P(w) = 1/2 ||y - X w||_2^2 + alpha ||w||_1 + beta/2 ||w||_2^2
+
+    The dual for beta = 0, see e.g. [Fercoq 2015] with v = alpha * theta, is
+
+        D(v) = -1/2 ||v||_2^2 + y v
+
+    with dual feasible condition ||X^T v||_inf <= alpha.
+    For beta > 0, one uses extended versions of X and y by adding n_features rows
 
-        (1/2) * norm(y - X w, 2)^2 + alpha norm(w, 1) + (beta/2) norm(w, 2)^2
+        X -> (           X)    y -> (y)
+             (sqrt(beta) I)         (0)
+
+    Note that the residual y - X w is an important ingredient for the estimation of a
+    dual feasible point v.
+    At optimum of primal w* and dual v*, one has
+
+        v = y* - X w*
+
+    The duality gap is
+
+        G(w, v) = P(w) - D(v) <= P(w) - P(w*)
+
+    The final stopping criterion is based on the duality gap
+
+        tol ||y||_2^2 < G(w, v)
+
+    The tolerance here is multiplied by ||y||_2^2 to have an inequality that scales the
+    same on both sides and because one has G(0, 0) = 1/2 ||y||_2^2.
 
     Returns
     -------
@@ -127,6 +155,18 @@ def enet_coordinate_descent(
         Equals input `tol` times `np.dot(y, y)`. The tolerance used for the dual gap.
     n_iter : int
         Number of coordinate descent iterations.
+
+    References
+    ----------
+    .. [Friedman 2010]
+       Jerome H. Friedman, Trevor Hastie, Rob Tibshirani. (2010)
+       Regularization Paths for Generalized Linear Models via Coordinate Descent
+       https://www.jstatsoft.org/article/view/v033i01
+
+    .. [Fercoq 2015]
+       Olivier Fercoq, Alexandre Gramfort, Joseph Salmon. (2015)
+       Mind the duality gap: safer rules for the Lasso
+       https://arxiv.org/abs/1505.03410
     """
 
     if floating is float:
