pyxfem.core.nonlinear_solver module

Nonlinear solvers and arc-length continuation routines.

This module provides numerical algorithms for solving nonlinear systems of equations and tracing equilibrium paths in structural and continuum mechanics:

  • Newton-Raphson solvers with customizable linear solvers, finite-difference fallback for Jacobians, and step-by-step convergence controls.

  • Unified root-finding interface dispatching to internal solvers or SciPy.

  • High-order arc-length (continuation) predictor routines based on Taylor expansions and adaptive step-size estimation for path following.

pyxfem.core.nonlinear_solver.arc_lenght_predictor(drdx, drdl, fd2rdx2_u, d2rdxdl, du_prev=None, dl_prev=None, pred_order=2, alpha=None, a=None, delta=None, afac=None, amax=0.1)[source]

Compute Taylor expansion terms of the arc-length path with respect to the arc parameter.

Parameters:

  • drdx (ndarray or scipy.sparse matrix) – Tangent operator dR/dx.

  • drdl (ndarray) – Load tangent vector dR/dlambda.

  • fd2rdx2_u (callable) – Function computing the directional second derivative of residual with respect to state: fd2rdx2_u(u=du).

  • d2rdxdl (ndarray or scipy.sparse matrix) – Mixed second derivative d^2R/(dx dlambda).

  • du_prev (ndarray, optional) – State increment from previous step.

  • dl_prev (float, optional) – Load increment from previous step.

  • pred_order ({1, 2}, optional) – Expansion order (default is 2).

  • alpha (float, optional) – Metric parameter weighting the load factor increment. Computed automatically if None.

Returns:

  • dus (list of ndarray) – List containing the 1st (and 2nd if pred_order == 2) derivatives of state.

  • dls (list of float) – List containing the 1st (and 2nd if pred_order == 2) derivatives of load parameter.

  • alpha (float) – Metric scaling parameter.

Raises:

ValueError – If pred_order is not 1 or 2.

pyxfem.core.nonlinear_solver.arc_lenght_predictor_a(du_terms, dl_terms, alpha, delta, afac, amax)[source]

Compute optimal step size ‘a’ for a 2nd-order arc-length expansion.

Parameters:

  • du_terms (list of ndarray) – List containing [du1, du2] state derivative vectors.

  • dl_terms (list of float) – List containing [dl1, dl2] load parameter derivative scalars.

  • alpha (float) – Arc-length scaling factor.

  • delta (float) – Error tolerance parameter.

  • afac (float) – Scale factor applied to the computed step size.

  • amax (float) – Maximum allowable step size.

Returns:

Computed step size a bounded by amax.

Return type:

float

Raises:

ValueError – If du_terms does not contain exactly 2 terms.

pyxfem.core.nonlinear_solver.arc_lenght_predictor_eval(du_terms, dl_terms, a)[source]

Evaluate total state and load increments using a polynomial expansion.

Parameters:

  • du_terms (list of ndarray) – First-order (and optionally second-order) state derivative vectors.

  • dl_terms (list of float) – First-order (and optionally second-order) load derivative scalars.

  • a (float) – Step size parameter.

Returns:

  • du (ndarray) – Combined state increment: a * du1 + a^2 * du2 (if order 2).

  • dl (float) – Combined load increment: a * dl1 + a^2 * dl2 (if order 2).

pyxfem.core.nonlinear_solver.arc_lenght_predictor_expansion(drdx, drdl, fd2rdx2_u, d2rdxdl, du_prev=None, dl_prev=None, pred_order=2, alpha=None)[source]

Compute optimal step size ‘a’ for a 2nd-order arc-length expansion.

Parameters:

  • du_terms (list of ndarray) – List containing [du1, du2] state derivative vectors.

  • dl_terms (list of float) – List containing [dl1, dl2] load parameter derivative scalars.

  • alpha (float) – Arc-length scaling factor.

  • delta (float) – Error tolerance parameter.

  • afac (float) – Scale factor applied to the computed step size.

  • amax (float) – Maximum allowable step size.

Returns:

Computed step size a bounded by amax.

Return type:

float

Raises:

ValueError – If du_terms does not contain exactly 2 terms.

pyxfem.core.nonlinear_solver.newton(fun, x0: ~numpy._typing._array_like.NDArray[~numpy.float64] | tuple[~numpy._typing._array_like.NDArray[~numpy.float64], ~numpy._typing._array_like.NDArray[~numpy.float64]] | list[~numpy._typing._array_like.NDArray[~numpy.float64]], jac=None, linsolver=None, norm=<function norm>, inplace_sub=<built-in function isub>, rtol: float = 1e-06, atol: float = 1e-06, nitermax=10, fail_on_increasing_res=False, verbose=True) → OptimizeResult[source]

Solve a non-linear system of equations f(x) = 0 using Newton’s method.

Parameters:

  • fun (callable) – Objective function returning the residual vector at x.

  • x0 (FloatArray, tuple of FloatArray, or list of FloatArray) – Initial guess for the solution.

  • jac (callable, optional) – Jacobian of fun. If None, a finite-difference approximation is used.

  • linsolver (callable, optional) – Linear solver of the form linsolver(A, b). Defaults to numpy.linalg.solve.

  • norm (callable, optional) – Norm used to compute the scalar residual norm. Defaults to numpy.linalg.norm.

  • inplace_sub (callable, optional) – In-place subtraction operator used to update the solution vector. Defaults to operator.isub.

  • rtol (float, optional) – Relative tolerance for convergence criteria (default is 1e-6).

  • atol (float, optional) – Absolute tolerance for convergence criteria (default is 1e-6).

  • nitermax (int, optional) – Maximum number of Newton iterations (default is 10).

  • fail_on_increasing_res (bool, optional) – If True, terminates iteration early if the residual increases. Defaults to False.

  • verbose (bool, optional) – Whether to print convergence progress at each iteration (default is True).

Returns:

Optimization result containing: - x: Solution array. - success: Boolean flag indicating successful convergence. - message: Termination description. - nit: Number of iterations performed. - nfev: Number of function evaluations. - njev: Number of Jacobian evaluations.

Return type:

scipy.optimize.OptimizeResult

pyxfem.core.nonlinear_solver.root(fun, x0, args=(), method='newton', jac=None, tol=None, callback=None, options=None)[source]

Find a root of a vector function.

Provides a unified interface dispatching either to the custom Newton solver or to scipy.optimize.root.

Parameters:

  • fun (callable) – Vector function to find a root of.

  • x0 (ndarray) – Initial guess.

  • args (tuple, optional) – Extra arguments passed to the objective function (used when method != ‘newton’).

  • method (str, optional) – Solver type. Defaults to 'newton'. Any other value is delegated to scipy.optimize.root.

  • jac (bool or callable, optional) – Jacobian evaluation function.

  • tol (float, optional) – Tolerance for termination. Defaults to 1e-6 for method='newton'.

  • callback (callable, optional) – Callback called after each iteration (passed to SciPy solver).

  • options (dict, optional) – Dictionary of solver options (passed to SciPy solver).

Returns:

The solution represented as an OptimizeResult object.

Return type:

scipy.optimize.OptimizeResult