cherab.inversion.regularization.criteria.Lcurve¶

class cherab.inversion.regularization.criteria.LcurveSource ¶

Bases: Criterion

L-curve criterion.

The L-curve is a log-log plot of the residual norm versus the regularization norm. The L-curve criterion for Tikhonov regularization gives the optimal regularization parameter \(\lambda\) as the corner point of the L-curve by maximizing the curvature of the L-curve.

Note

The theory and implementation of the L-curve criterion are described here.

Methods

`curvature`(solver, beta)	Calculate L-curve curvature.
`optimize`(solver, bounds[, stepsize])	Find optimal parameter by maximizing curvature (continuous).
`optimize_discrete`(solver)	Find optimal TSVD truncation via the discrete Menger curvature of the L-curve.
`plot_L_curve`()	Plot the curvature of L-curve as function of regularization parameter.
`plot_curvature`()	Plot the curvature of L-curve as function of regularization parameter.

curvature(solver: _SVDBase, beta: float) → floatSource ¶

Calculate L-curve curvature.

This method calculates the curvature of L-curve at the point \((\sqrt{\rho}, \sqrt{\eta})\) as function of regularization parameter \(\lambda\).

If the curvature is positive, the L-curve is concave at the point. If the curvature is negative, the L-curve is convex at the point.

Parameters:

solver: _SVDBase¶: An _SVDBase instance providing rho, eta, and eta_diff.
beta: float¶: Regularization parameter \(\lambda\).

Returns:

float – Value of calculated curvature.

Examples

>>> svd = SVD(s, U, basis, data=data)
>>> lcurve = Lcurve()
>>> curvature = lcurve.curvature(svd, 1.0e-5)

optimize(solver: _SVDBase, bounds: tuple[float, float], stepsize: float = 10, **kwargs: Any) → tuple[float, OptimizeResult]Source ¶

Find optimal parameter by maximizing curvature (continuous).

This method finds the optimal regularization parameter by maximizing the curvature of the L-curve using the basinhopping global optimization algorithm. The search is performed in log-space, so the bounds are specified as (log10_lower, log10_upper).

Parameters:

solver: _SVDBase¶: An _SVDBase instance providing rho, eta, and eta_diff.
bounds: tuple[float, float]¶: (log10_lower, log10_upper) search interval for the regularization parameter in log-space.
stepsize: float = 10¶: Step-size for the underlying global optimizer.
**kwargs: Any¶: Extra arguments forwarded to the optimizer.

Returns:

lambda_opt (float) – Optimal regularization parameter that maximizes the curvature of the L-curve.
result (OptimizeResult) – Optimizer result object returned by basinhopping.

optimize_discrete(solver: _SVDBase) → tuple[float, dict[str, int | NDArray[float64]]]Source ¶

Find optimal TSVD truncation via the discrete Menger curvature of the L-curve.

The TSVD filter factors are piecewise-constant (0 or 1), so the analytical derivative eta_diff is identically zero. Instead the Menger curvature — the reciprocal of the circumradius of three consecutive points — is used. For three points \(P_{k-1}, P_k, P_{k+1}\) in log–log space (\(\xi = \log\|\mathbf{r}\|\), \(\chi = \log\|\mathbf{x}\|\)):

\[\kappa_k = \frac{2\,A(P_{k-1}, P_k, P_{k+1})} {|P_{k-1}P_k|\,|P_k P_{k+1}|\,|P_{k-1}P_{k+1}|}\]

where \(A\) is the signed area of the triangle (positive when the turn \(P_{k-1}\to P_k\to P_{k+1}\) is counter-clockwise). The endpoint indices (\(k=1\) and \(k=r\)) are assigned \(\kappa = 0\).

Parameters:

solver: _SVDBase¶: An _SVDBase instance providing rho and eta.

Returns:

lambda_opt (float) – Optimal regularization parameter corresponding to the index of maximum curvature.
result (dict[str, int | numpy.ndarray]) – Dictionary containing the following keys: - k: Index of the optimal truncation point (1-based). - curvatures: Array of curvature values for all candidate truncation points.

Notes

This approach avoids computing second-order finite differences, which can amplify noise. It matches the method of .

plot_L_curve(solver: _SVDBase | None = None, axes: None = None, bounds: Collection[float | None] | None = None, n_beta: int = 500, scatter_plot: int | None = None, scatter_annotate: bool = True, plot_lambda_opt: bool = True) → tuple[Axes, Figure]Source ¶

plot_L_curve(solver: _SVDBase | None = None, axes: Axes | None = None, bounds: Collection[float | None] | None = None, n_beta: int = 500, scatter_plot: int | None = None, scatter_annotate: bool = True, plot_lambda_opt: bool = True) → Axes

Plot the curvature of L-curve as function of regularization parameter.

The curvature of L-curve is calculated by curvature() method.

Parameters:

solver: _SVDBase | None = None¶: An _SVDBase instance.
axes: None = None¶
axes: Axes | None = None: A matplotlib Axes object, by default None.
bounds: Collection[float | None] | None = None¶: Boundary pair of log10 of regularization parameters, by default None. If None, the bounds are generated by the solver as described in SVD._generate_bounds(). If you set the bounds like (-10, None), the higher bound is set to \(\log_{10}\sigma_1^2\). Raise an error if a >= b in (a, b).
n_beta: int = 500¶: Number of regularization parameters, by default 500.
scatter_plot: int | None = None¶: Whether or not to plot some L-curve points as a 10 ^x format, by default None. If you want to manually define the number of points, enter the numbers like scatter_plot=10 then around 10 points corresponding to 10 ^x format are plotted.
scatter_annotate: bool = True¶: Whether or not to annotate the scatter_points, by default True. This key argument is valid if only scatter_plot is not None.
plot_lambda_opt: bool = True¶: Whether or not to plot the L-curve corner point, by default True.

Returns:

axes (Axes) – A matplotlib Axes object.
fig (Figure) – A matplotlib figure object if axes is None, otherwise None.

plot_curvature(solver: _SVDBase | None = None, axes: None = None, bounds: Collection[float | None] | None = None, n_beta: int = 500, show_max_curvature_line: bool = True) → tuple[Axes, Figure]Source ¶

plot_curvature(solver: _SVDBase | None = None, axes: Axes | None = None, bounds: Collection[float | None] | None = None, n_beta: int = 500, show_max_curvature_line: bool = True) → Axes

Plot the curvature of L-curve as function of regularization parameter.

The curvature of L-curve is calculated by curvature() method.

Parameters:

solver: _SVDBase | None = None¶: An _SVDBase instance. If None, the last solver used in optimize() is used.
axes: None = None¶
axes: Axes | None = None: A matplotlib Axes object, by default None.
bounds: Collection[float | None] | None = None¶: Boundary pair of log10 of regularization parameters, by default None. If None, the bounds are generated by the solver as described in SVD._generate_bounds(). If you set the bounds like (-10, None), the higher bound is set to \(\log_{10}\sigma_1^2\). Raise an error if a >= b in (a, b).
n_beta: int = 500¶: Number of regularization parameters, by default 500.
show_max_curvature_line: bool = True¶: Whether or not to plot the vertical red dashed line at the maximum curvature point, by default True.

Returns:

axes (Axes) – A matplotlib Axes object.
fig (Figure) – A matplotlib figure object if axes is None, otherwise None.