fedoo.problem.NonLinear.add_line_search

NonLinear.add_line_search(method='Quadratic', mode='natural', apply_to_bc=True, 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 residual-descent strategy used when mode='minimize':

  • ’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 (mode is then ignored).

    A custom callback may scale a pending Dirichlet increment. A returned alpha < 1 defers its unapplied part to subsequent Newton corrections, and convergence is declared only after the complete prescribed increment has been applied. The callback must therefore eventually accept the remaining increment.

• mode ({'natural', 'minimize', 'safeguard'}, default 'natural') –

  The overall line search policy:

  • ’natural’ (default): validity filter, then the step is accepted when EITHER the classical Armijo test on \(\|R\|\) OR Deuflhard’s affine-invariant test on the simplified Newton correction \(K^{-1} R(u + \alpha dX)\) passes (see fedoo.problem.line_search._natural_test()). The first one throttles the overshoot of penalty contact and elastic-plastic transitions, the second one lets the legitimate large steps of soft modes under force control through. method is ignored. Factorization reuse (set_reuse_factorization()) is enabled automatically with a direct solver so that each trial costs one back-substitution.

  • ’minimize’: classical residual-descent line search using method below. Throttles the step against overshoot but may strangle Newton on soft modes under force control.

  • ’safeguard’: pure validity filter. The full Newton step is accepted whenever the trial state is kinematically valid; geometric backtracking is applied only on a degenerated trial state (\(\det F \le 0\)). This never throttles the legitimate large steps of soft modes (whose quadratic remainder inflates the residual norm as \(\alpha^2\) while remaining excellent steps), which any residual-monotone rule would strangle – the right choice for force control of soft (bending) modes. method is ignored.

• apply_to_bc (bool, default True) – If True, the built-in line search applies its kinematic-validity filter to a pending Dirichlet increment. An invalid advance is scaled, its unapplied part is carried by the next Newton correction, and convergence is accepted only after the complete prescribed increment has been applied. Residual and natural acceptance tests start after that remainder reaches zero. If False, the built-in line search applies the complete Dirichlet increment without a validity check. This option does not alter custom callbacks.

• 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 ls_mode, ls_method, ls_max_iter and ls_apply_to_bc are stored within the self.nr_parameters dictionary (they may also be set through set_nr_criterion()).

• 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]\). Invalid kinematic trials are reduced geometrically. If no valid trial exists down to the minimum step, the complete increment is rejected through the normal time-step reduction machinery. If the natural-mode acceptance tests are exhausted, its last valid trial is used and the Newton solver decides whether the increment converges.

Example

>>> # Default: natural monotonicity test
>>> my_problem.add_line_search()
>>> # Classical residual-descent line search
>>> my_problem.add_line_search(mode="minimize", method="Quadratic")
>>> # Validity safeguard only (soft-mode force control)
>>> my_problem.add_line_search(mode="safeguard")
>>> # Apply prescribed displacement in one full step
>>> my_problem.add_line_search(apply_to_bc=False)
>>> # Using a custom function
>>> def my_ls(pb, dX): return 0.5
>>> my_problem.add_line_search(method=my_ls)