module yaeos__math_nonlinearsolvers !! # Nonlinear equation solvers !! !! # Description !! Newton-type solvers for systems of nonlinear equations, including the !! damped multivariate Newton method [[newton]]. !! `newton` is the damped Newton method; `homotopy` gradually deforms an !! identity problem into the target system. !! !! # Examples !! ```fortran !! call newton(residual_jacobian, x, tol, max_its, iterations) !! ``` use yaeos__constants, only: pr use yaeos__math_linalg, only: solve_system implicit none interface to_solve subroutine to_solve(X, F, J) !! Callback interface for a square nonlinear system and dense Jacobian. import pr real(pr), intent(in) :: X(:) !! Current unknown vector. real(pr), intent(out) :: F(:) !! Residual vector \(F(X)\). real(pr), intent(out) :: J(:, :) !! Jacobian \(\partial F_i/\partial X_j\). end subroutine to_solve end interface to_solve contains subroutine newton(sub, x, tol, max_its, its) !! # `newton` !! Multidimensional Newton method with simple step damping. !! !! # Description !! Solves \(F(X)=0\) with Newton-Raphson. Each step is repeatedly halved !! until its largest component is at most 0.1; this limits step size but !! is not a residual-based line search. `its` is the loop count and does !! not distinguish all convergence/failure cases. procedure(to_solve) :: sub !! Callback returning residuals and the Jacobian. real(pr), intent(in out) :: x(:) !! Initial guess, overwritten by the current solution estimate. real(pr), intent(in) :: tol !! Absolute infinity-norm tolerance on the residual. integer, intent(in) :: max_its !! Maximum number of Newton iterations. integer, intent(out) :: its !! Iteration count at exit. real(pr) :: F(size(X)) real(pr) :: J(size(X), size(X)) !! Jacobian matrix. real(pr) :: dX(size(X)) real(pr) :: F2(size(X)) real(pr) :: J2(size(X), size(X)) call sub(x, F, J) do its = 1, max_its dX = solve_system(J, -F) if (maxval(abs(F)) < tol) exit do while(maxval(abs(dX)) > 0.1) dX = dX/2 end do X = X + dX call sub(x, F, J) end do end subroutine newton subroutine homotopy(sub, x, tol, max_its, its) !! # homotopy !! !! # Description !! Attempt a homotopy solve from an easy identity system to the target. !! !! The internal residual is \(H(X,t)=tF(X)+(1-t)(X-X_0)\), where !! \(X_0\) is the initial guess. The implementation advances `t` through !! ten equally spaced values and calls the damped Newton routine at each !! stage. It is a legacy helper with limited failure diagnostics. use yaeos__math, only: powel_hybrid procedure(to_solve) :: sub !! Target residual/Jacobian callback. real(pr), intent(in out) :: x(:) !! Initial guess, updated homotopy solution. real(pr), intent(in) :: tol !! Absolute residual tolerance at each stage. integer, intent(in) :: max_its !! Present for interface compatibility; current implementation uses a fixed stage limit. integer, intent(out) :: its !! Iterations reported by the last Newton stage. real(pr) :: dX(size(x)) real(pr) :: F(size(X)) real(pr) :: dF(size(X), size(X)) real(pr) :: G(size(X)) real(pr) :: dG(size(X), size(X)) real(pr) :: H(size(X)) real(pr) :: dH(size(X), size(X)) real(pr) :: t real(pr) :: dt real(pr) :: X0(size(X)) integer :: i !! Loop/index variable. integer :: nt integer :: info !! Solver status code. nt = 10 dt = 1.0_pr/real(nt, pr) do i=0,nt t = dt*i X0 = X call newton(wrap, X, tol, 500, its) call wrap(X, H, dH) end do contains subroutine wrap(X, H, dH) !! # wrap !! !! # Description !! Evaluate the homotopy residual and Jacobian at the current stage. real(pr), intent(in) :: X(:) !! Current homotopy unknown vector. real(pr), intent(out) :: H(:) !! Homotopy residual vector. real(pr), intent(out) :: dH(:,:) !! Homotopy Jacobian with respect to `X`. real(pr) :: F(size(X)) real(pr) :: dF(size(X), size(X)) real(pr) :: G(size(X)) real(pr) :: dG(size(X), size(X)) real(pr) :: diag(size(X), size(X)) real(pr) :: id(size(X), size(X)) integer :: i !! Loop index `i`. integer :: j !! Loop index `j`. G = X - X0 dG = 0 do i=1,size(x) dG(i, i) = 1 end do call sub(X, F, dF) H = t * F + (1-t) * G dH = t * dF + (1-t) * dG end subroutine wrap subroutine fun(n, x, fvec, iflag) !! # fun !! !! # Description !! MINPACK-style adapter for the homotopy residual callback. integer, intent(in) :: n !! Number of unknowns. real(pr), intent(in) :: x(n) !! Current unknown vector. real(pr), intent(out) :: fvec(n) !! Residual vector. integer, intent(in out) :: iflag !! Solver callback status flag. call wrap(X, FVEC, dH) end subroutine fun end subroutine homotopy end module yaeos__math_nonlinearsolvers