fedoo.problem.NonLinear.add_line_search

NonLinear.add_line_search(method='Quadratic', name=None)

Add line search algorithm for the Newton-Raphson solver.

Line search improves global convergence by scaling the displacement increment \(dX\) by a step size \(\alpha \in (0, 1]\). This is particularly useful for problems with sharp non-linearities or when the initial guess is far from the equilibrium.

Parameters:

• method ({'Armijo', 'Residual', 'Energy', 'Quadratic'} or callable, default 'Quadratic') –

  The strategy used to determine or refine the step size:

  • ’Armijo’: Ensures a “sufficient decrease” in the residual using a least-square assumption. Standard for most nonlinear applications.

  • ’Residual’: Simple backtracking that accepts any step reducing the residual norm. Fast but less robust.

  • ’Energy’: Minimizes the out-of-balance work (residual projected onto the search direction). Ideal for snap-through/buckling.

  • ’Quadratic’: Performs a parabolic interpolation of the objective function to jump directly to the estimated minimum.

  • callable: If a function is provided, it must follow the signature user_line_search(pb, dX) -> float and will be assigned directly as the line search callback.

• name (str, optional) – A unique identifier for the line search. If not provided, it defaults to ‘standard’ for built-in methods, or the function’s name for callables.

Notes

• Implementation: This method sets the _step_size_callback attribute of the problem instance. Parameters like ls_max_iter and ls_method are stored within the self.nr_parameters dictionary.

• Objective Function: For ‘Armijo’ and ‘Quadratic’ methods, the solver minimizes the squared L2-norm of the residual:

  \[\phi(\alpha) = \frac{1}{2} \|R(u + \alpha dX)\|^2\]

• Work Criterion: The ‘Energy’ method minimizes the directional derivative of the potential energy (the external work).

• Safeguards: To prevent solver stagnation, interpolated values are clipped such that \(\alpha_{new} \in [0.1\alpha, 0.5\alpha]\).

Example

>>> # Using a built-in method
>>> my_problem.add_line_search(method="Quadratic")
>>> # Using a custom function
>>> def my_ls(pb, dX): return 0.5
>>> my_problem.add_line_search(method=my_ls)