! MIT License
!
! Copyright (c) 2017-2026 Jason Christopherson
!
! Permission is hereby granted, free of charge, to any person obtaining a copy
! of this software and associated documentation files (the "Software"), to deal
! in the Software without restriction, including without limitation the rights
! to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
! copies of the Software, and to permit persons to whom the Software is
! furnished to do so, subject to the following conditions:
!
! The above copyright notice and this permission notice shall be included in all
! copies or substantial portions of the Software.
!
! THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
! IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
! FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
! AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
! LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
! OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
! SOFTWARE.
!
! nonlin_continuation.f90
module nonlin_continuation
    use iso_fortran_env
    use ieee_arithmetic, only : ieee_is_finite, ieee_value, ieee_quiet_nan
    use lapack, only : dgelsy
    use nonlin_multi_eqn_mult_var
    use nonlin_error_handling
    use nonlin_types
    implicit none
    private
    public :: continuation_solver

    type :: continuation_workspace
        !! Scratch storage reused between solves with the same system size.
        real(real64), allocatable :: x0(:), xbase(:), trial_x(:)
        real(real64), allocatable :: residual(:), trial_residual(:), direction(:)
        real(real64), allocatable :: z(:), tangent(:), predictor(:), candidate(:)
        real(real64), allocatable :: corrector_base(:)
        real(real64), allocatable :: jacobian(:,:), lambda_jacobian(:)
        real(real64), allocatable :: augmented(:,:), rhs(:), delta(:)
        real(real64), allocatable :: ls_matrix(:,:), ls_rhs(:), ls_work(:)
        integer :: ls_lwork = 0
        integer, allocatable :: pivots(:)
    end type

    type, extends(equation_solver) :: continuation_solver
        !! Adaptive parameter continuation for square nonlinear systems.
        !! The default homotopy connects the initial guess x0 to the target
        !! system F(x)=0. Its Jacobian uses vecfcn_helper, which selects an
        !! analytic Jacobian, AD, or finite differences for the target system.
        !! A custom homotopy must satisfy H(x0,0)=0 and H(x,1)=F(x).
        !!
        !! Fixed-parameter continuation is the default. Pseudo-arclength mode
        !! augments the corrector and can follow regular folds in the path.
        !! Extend this type and override homotopy and homotopy_jacobian to
        !! change the path without replacing the continuation algorithm.
        real(real64), private :: m_initialStep = 0.2d0
            !! Initial and maximum continuation step in lambda.
        real(real64), private :: m_minimumStep = 1.0d-5
            !! Minimum continuation step attempted before failure.
        integer, private :: m_maxCorrectorIterations = 12
            !! Maximum Newton corrections attempted at each lambda value.
        logical, private :: m_usePseudoArclength = .false.
            !! Select pseudo-arclength instead of fixed-lambda continuation.
        type(continuation_workspace), private :: m_workspace
            !! Reusable solve and pivoted-QR scratch storage.
    contains
        procedure, public :: solve => cs_solve
        procedure, private :: solve_fixed_lambda => cs_solve_fixed
        procedure, private :: solve_pseudo_arclength => cs_solve_pseudo
        procedure, private :: ensure_workspace => cs_ensure_workspace
        procedure, private :: solve_dgelsy => cs_solve_dgelsy
        procedure, public :: homotopy => cs_homotopy
        procedure, public :: homotopy_jacobian => cs_homotopy_jacobian
        procedure, public :: homotopy_lambda_derivative => cs_homotopy_lambda_derivative
        procedure, public :: get_use_pseudo_arclength => cs_get_use_pseudo_arclength
        procedure, public :: set_use_pseudo_arclength => cs_set_use_pseudo_arclength
        procedure, public :: get_initial_step => cs_get_initial_step
        procedure, public :: set_initial_step => cs_set_initial_step
        procedure, public :: get_minimum_step => cs_get_minimum_step
        procedure, public :: set_minimum_step => cs_set_minimum_step
        procedure, public :: get_max_corrector_iterations => cs_get_max_corrector_iterations
        procedure, public :: set_max_corrector_iterations => cs_set_max_corrector_iterations
    end type

contains
! ------------------------------------------------------------------------------
    subroutine cs_ensure_workspace(this, n)
        !! Allocate or resize solver-owned work arrays only when the problem
        !! dimension changes. The extra slot accommodates lambda and the
        !! augmented pseudo-arclength system.
        class(continuation_solver), intent(inout), target :: this
        integer, intent(in) :: n
        integer :: nw, info, rank
        real(real64) :: rank_tolerance, work_query(1)

        nw = n + 1
        if (allocated(this%m_workspace%x0)) then
            if (size(this%m_workspace%x0) == n .and. &
                size(this%m_workspace%z) == nw) return
            deallocate(this%m_workspace%x0, this%m_workspace%xbase, &
                this%m_workspace%trial_x, this%m_workspace%residual, &
                this%m_workspace%trial_residual, this%m_workspace%direction, &
                this%m_workspace%z, this%m_workspace%tangent, &
                this%m_workspace%predictor, this%m_workspace%candidate, &
                this%m_workspace%corrector_base, &
                this%m_workspace%jacobian, this%m_workspace%lambda_jacobian, &
                this%m_workspace%augmented, this%m_workspace%rhs, &
                this%m_workspace%delta, this%m_workspace%ls_matrix, &
                this%m_workspace%ls_rhs, this%m_workspace%ls_work, &
                this%m_workspace%pivots)
        end if

        allocate(this%m_workspace%x0(n), this%m_workspace%xbase(n), &
            this%m_workspace%trial_x(n), this%m_workspace%residual(n), &
            this%m_workspace%trial_residual(n), this%m_workspace%direction(n))
        allocate(this%m_workspace%z(nw), this%m_workspace%tangent(nw), &
            this%m_workspace%predictor(nw), this%m_workspace%candidate(nw), &
            this%m_workspace%corrector_base(nw))
        allocate(this%m_workspace%jacobian(n,n), &
            this%m_workspace%lambda_jacobian(n))
        allocate(this%m_workspace%augmented(nw,nw), this%m_workspace%rhs(nw), &
            this%m_workspace%delta(nw))
        allocate(this%m_workspace%ls_matrix(nw,nw), &
            this%m_workspace%ls_rhs(nw), this%m_workspace%pivots(nw))

        ! Query the optimal DGELSY workspace once for the largest system used
        ! by either mode, N+1 in the pseudo-arclength corrector.
        this%m_workspace%ls_matrix = 0.0d0
        this%m_workspace%ls_rhs = 0.0d0
        this%m_workspace%pivots = 0
        rank_tolerance = epsilon(1.0d0)
        call dgelsy(nw, nw, 1, this%m_workspace%ls_matrix, nw, &
            this%m_workspace%ls_rhs, nw, this%m_workspace%pivots, &
            rank_tolerance, rank, work_query, -1, info)
        if (info /= 0 .or. .not.ieee_is_finite(work_query(1))) &
            error stop NL_CONVERGENCE_ERROR
        this%m_workspace%ls_lwork = max(1, ceiling(work_query(1)))
        allocate(this%m_workspace%ls_work(this%m_workspace%ls_lwork))
    end subroutine

! ------------------------------------------------------------------------------
    subroutine cs_solve_dgelsy(this, a, b, x, success)
        !! Solve a square system using LAPACK DGELSY. Its complete orthogonal
        !! factorization returns a minimum-norm solution for rank-deficient
        !! systems; it cannot select a unique branch at a singular point.
        class(continuation_solver), intent(inout), target :: this
        real(real64), intent(in), dimension(:,:) :: a
        real(real64), intent(in), dimension(:) :: b
        real(real64), intent(out), dimension(:) :: x
        logical, intent(out) :: success

        integer :: n, rank, info
        real(real64) :: rank_tolerance

        n = size(b)
        success = .false.
        if (size(a,1) /= n .or. size(a,2) /= n .or. size(x) /= n) return
        if (size(this%m_workspace%ls_matrix,1) < n) return

        ! DGELSY interprets nonzero input pivot entries as pinned columns.
        ! Clear them before every solve so all columns are eligible to pivot.
        this%m_workspace%ls_matrix(1:n,1:n) = a
        this%m_workspace%ls_rhs = 0.0d0
        this%m_workspace%ls_rhs(1:n) = b
        this%m_workspace%pivots(1:n) = 0
        rank_tolerance = epsilon(1.0d0)
        call dgelsy(n, n, 1, this%m_workspace%ls_matrix, &
            size(this%m_workspace%ls_matrix,1), this%m_workspace%ls_rhs, &
            size(this%m_workspace%ls_rhs), this%m_workspace%pivots, &
            rank_tolerance, rank, this%m_workspace%ls_work, &
            this%m_workspace%ls_lwork, info)
        if (info /= 0) return
        x = this%m_workspace%ls_rhs(1:n)
        success = all(ieee_is_finite(x))
    end subroutine

! ------------------------------------------------------------------------------
    subroutine cs_solve(this, fcn, x, fvec, ib, args)
        !! Dispatch to the selected continuation strategy.
        class(continuation_solver), intent(inout) :: this
        class(vecfcn_helper), intent(inout) :: fcn
        real(real64), intent(inout), dimension(:) :: x
        real(real64), intent(out), dimension(:) :: fvec
        type(iteration_behavior), intent(out), optional :: ib
        class(*), intent(in), optional :: args

        if (this%m_usePseudoArclength) then
            call this%solve_pseudo_arclength(fcn, x, fvec, ib, args)
        else
            call this%solve_fixed_lambda(fcn, x, fvec, ib, args)
        end if
    end subroutine

! ------------------------------------------------------------------------------
    subroutine cs_solve_fixed(this, fcn, x, fvec, ib, args)
        !! Follow the homotopy from \(\lambda=0\) to \(\lambda=1\) using damped 
        !! Newton corrections. Failed corrections are retried with smaller 
        !! \(\lambda\) steps; successful steps allow the step size to grow 
        !! again.
        class(continuation_solver), intent(inout), target :: this
            !! The [[continuation_solver]] object.
        class(vecfcn_helper), intent(inout) :: fcn
            !! The [[vecfcn_helper]] object containing the equations to solve.
        real(real64), intent(inout), dimension(:) :: x
            !! On input, an N-element array containing an initial estimate to
            !! the solution.  On output, the updated solution estimate.
        real(real64), intent(out), dimension(:) :: fvec
            !! On success, the target residual F(x). On failure, NaNs.
        type(iteration_behavior), intent(out), optional :: ib
            !! An optional output, that if provided, allows the caller to obtain
            !! iteration performance statistics.
        class(*), intent(in), optional :: args
            !! An optional argument to allow the user to communicate with the
            !! routine.

        integer :: n, neval, njac, niter, maxeval
        integer :: corrector_iteration, backtrack_iteration
        real(real64) :: lambda, target_lambda, step, alpha, residual_norm
        real(real64) :: trial_norm, ftol, nan
        logical :: corrected, accepted, reached_end
        logical :: qr_success
        type(continuation_workspace), pointer :: work
        real(real64), pointer :: x0(:), xbase(:), trial_x(:), residual(:)
        real(real64), pointer :: trial_residual(:), jac(:,:), direction(:)

        ! Initialize statistics before validating inputs.
        n = fcn%get_variable_count()
        neval = 0
        njac = 0
        niter = 0
        reached_end = .false.
        maxeval = this%get_max_fcn_evals()
        ftol = this%get_fcn_tolerance()
        nan = ieee_value(nan, ieee_quiet_nan)
        if (present(ib)) then
            ib = iteration_behavior(maxeval)
        end if

        ! This continuation method follows a square system from the supplied
        ! initial point, which also anchors the default homotopy.
        if (.not.fcn%is_fcn_defined()) error stop NL_UNDEFINED_FUNCTION_ERROR
        if (n /= fcn%get_equation_count()) error stop NL_INVALID_INPUT_ERROR
        if (size(x) /= n) error stop 3
        if (size(fvec) /= n) error stop 4

        call this%ensure_workspace(n)
        work => this%m_workspace
        x0 => work%x0
        xbase => work%xbase
        trial_x => work%trial_x
        residual => work%residual
        trial_residual => work%trial_residual
        jac => work%jacobian
        direction => work%direction
        x0 = x
        if (.not.all(ieee_is_finite(x0)) .or. maxeval <= 0) then
            fvec = ieee_value(0.0d0, ieee_quiet_nan)
            return
        end if

        lambda = 0.0d0
        step = this%m_initialStep

        ! Correct the solution at each target lambda. On failure, restore the
        ! last accepted point and retry with a smaller continuation step.
        do while (lambda < 1.0d0)
            target_lambda = min(1.0d0, lambda + step)
            xbase = x
            corrected = .false.

            do corrector_iteration = 1, this%m_maxCorrectorIterations
                if (neval >= maxeval) exit
                call this%homotopy(fcn, x, x0, target_lambda, residual, args)
                neval = neval + 1
                if (.not.all(ieee_is_finite(residual))) exit
                residual_norm = maxval(abs(residual))
                if (residual_norm <= ftol) then
                    corrected = .true.
                    exit
                end if

                ! The default binding gets J_F from vecfcn_helper, which uses
                ! AD whenever an AD-compatible function is registered.
                call this%homotopy_jacobian(fcn, x, x0, target_lambda, jac, args)
                njac = njac + 1
                if (.not.all(ieee_is_finite(jac))) exit

                ! Solve J_H*dx=-H. A singular factorization fails this lambda
                ! attempt and triggers a smaller continuation step.
                call this%solve_dgelsy(jac, -residual, direction, qr_success)
                if (.not.qr_success) exit

                ! Backtrack until the corrector reduces the homotopy residual.
                accepted = .false.
                alpha = 1.0d0
                trial_norm = residual_norm
                do backtrack_iteration = 1, 12
                    if (neval >= maxeval) exit
                    trial_x = x + alpha * direction
                    if (.not.all(ieee_is_finite(trial_x))) then
                        alpha = 0.5d0 * alpha
                        cycle
                    end if
                    call this%homotopy(fcn, trial_x, x0, target_lambda, &
                        trial_residual, args)
                    neval = neval + 1
                    if (all(ieee_is_finite(trial_residual))) then
                        trial_norm = maxval(abs(trial_residual))
                        if (trial_norm < residual_norm) then
                            x = trial_x
                            residual = trial_residual
                            accepted = .true.
                            exit
                        end if
                    end if
                    alpha = 0.5d0 * alpha
                end do
                niter = niter + 1
                if (present(ib)) then
                    call ib%log_iteration(trial_norm, nan, nan)
                end if
                if (.not.accepted) exit
                if (maxval(abs(residual)) <= ftol) then
                    corrected = .true.
                    exit
                end if
            end do

            if (corrected) then
                lambda = target_lambda
                step = min(this%m_initialStep, 1.5d0 * step)
            else
                x = xbase
                if (neval >= maxeval) exit
                step = 0.5d0 * step
                if (step < this%m_minimumStep) exit
            end if
        end do

        if (lambda >= 1.0d0) then
            reached_end = .true.
            fvec = residual
        else
            fvec = ieee_value(0.0d0, ieee_quiet_nan)
        end if

        if (present(ib)) then
            ib%iter_count = niter
            ib%fcn_count = neval
            ib%jacobian_count = njac
            ib%gradient_count = 0
            ib%converge_on_fcn = reached_end
            ib%converge_on_chng = .false.
            ib%converge_on_zero_diff = .false.
        end if
    end subroutine

! ------------------------------------------------------------------------------
    subroutine cs_solve_pseudo(this, fcn, x, fvec, ib, args)
        !! Trace the solution curve using a tangent predictor and an augmented
        !! arclength corrector. Lambda is allowed to reverse direction at folds.
        class(continuation_solver), intent(inout), target :: this
        class(vecfcn_helper), intent(inout) :: fcn
        real(real64), intent(inout), dimension(:) :: x
        real(real64), intent(out), dimension(:) :: fvec
        type(iteration_behavior), intent(out), optional :: ib
        class(*), intent(in), optional :: args

        integer :: n, neval, njac, niter, maxeval
        integer :: corrector_iteration, backtrack_iteration
        real(real64) :: ftol, xtol, ds, lambda_tol, lambda, ds_used
        real(real64) :: arc_error, merit, trial_merit, alpha, tangent_norm
        real(real64) :: history_residual
        real(real64) :: lambda_new, nan
        logical :: success, corrected, accepted, endpoint_step, qr_success
        type(continuation_workspace), pointer :: work
        real(real64), pointer :: x0(:), z(:), tangent(:), predictor(:)
        real(real64), pointer :: candidate(:), corrector_base(:), residual(:)
        real(real64), pointer :: trial_residual(:)
        real(real64), pointer :: jac(:,:), lambda_jac(:), augmented(:,:)
        real(real64), pointer :: rhs(:), delta(:)

        n = fcn%get_variable_count()
        neval = 0
        njac = 0
        niter = 0
        success = .false.
        fvec = ieee_value(0.0d0, ieee_quiet_nan)
        maxeval = this%get_max_fcn_evals()
        ftol = this%get_fcn_tolerance()
        xtol = this%get_var_tolerance()
        nan = ieee_value(nan, ieee_quiet_nan)
        if (present(ib)) then
            ib = iteration_behavior(maxeval)
        end if

        if (.not.fcn%is_fcn_defined()) error stop NL_UNDEFINED_FUNCTION_ERROR
        if (n /= fcn%get_equation_count()) error stop NL_INVALID_INPUT_ERROR
        if (size(x) /= n) error stop 3
        if (size(fvec) /= n) error stop 4
        if (.not.all(ieee_is_finite(x)) .or. maxeval <= 0) return

        call this%ensure_workspace(n)
        work => this%m_workspace
        x0 => work%x0
        z => work%z
        tangent => work%tangent
        predictor => work%predictor
        candidate => work%candidate
        corrector_base => work%corrector_base
        residual => work%residual
        trial_residual => work%trial_residual
        jac => work%jacobian
        lambda_jac => work%lambda_jacobian
        augmented => work%augmented
        rhs => work%rhs
        delta => work%delta
        x0 = x
        lambda = 0.0d0
        ds = this%m_initialStep
        lambda_tol = max(ftol, 10.0d0 * epsilon(1.0d0))

        ! The initial tangent is oriented toward increasing lambda. For the
        ! default homotopy, J_H is the identity at lambda=0.
        if (.not.get_derivatives(x, lambda, jac, lambda_jac)) go to 900
        augmented = 0.0d0
        augmented(1:n,1:n) = jac
        augmented(1:n,n+1) = lambda_jac
        augmented(n+1,n+1) = 1.0d0
        rhs = 0.0d0
        rhs(1:n) = -lambda_jac
        rhs(n+1) = 1.0d0
        call this%solve_dgelsy(augmented, rhs, delta, qr_success)
        if (.not.qr_success) go to 900
        tangent_norm = norm2(delta)
        if (tangent_norm <= tiny(tangent_norm)) go to 900
        tangent = delta / tangent_norm

        do while (neval < maxeval)
            z(1:n) = x
            z(n+1) = lambda
            ds_used = ds
            endpoint_step = .false.

            ! Aim the predictor at lambda=1 whenever the tangent points toward
            ! the endpoint. At folds, its lambda component naturally changes sign.
            if (tangent(n+1) > 0.0d0 .and. lambda < 1.0d0) then
                if (lambda + ds_used * tangent(n+1) >= 1.0d0) then
                    ds_used = (1.0d0 - lambda) / tangent(n+1)
                    endpoint_step = .true.
                end if
            end if
            if (ds_used <= 0.0d0) exit

            predictor = z + ds_used * tangent
            candidate = predictor
            corrected = .false.

            do corrector_iteration = 1, this%m_maxCorrectorIterations
                if (.not.evaluate_homotopy(candidate(1:n), candidate(n+1), &
                    residual)) exit
                arc_error = dot_product(tangent, candidate - predictor)
                merit = sqrt(dot_product(residual, residual) + arc_error**2)
                if (maxval(abs(residual)) <= ftol .and. abs(arc_error) <= xtol) then
                    corrected = .true.
                    exit
                end if

                if (.not.get_derivatives(candidate(1:n), candidate(n+1), &
                    jac, lambda_jac)) exit
                augmented(1:n,1:n) = jac
                augmented(1:n,n+1) = lambda_jac
                augmented(n+1,:) = tangent
                rhs(1:n) = -residual
                rhs(n+1) = -arc_error
                call this%solve_dgelsy(augmented, rhs, delta, qr_success)
                if (.not.qr_success) exit

                accepted = .false.
                alpha = 1.0d0
                trial_merit = merit
                history_residual = maxval(abs(residual))
                corrector_base = candidate
                do backtrack_iteration = 1, 12
                    candidate = corrector_base + alpha * delta
                    if (.not.all(ieee_is_finite(candidate))) then
                        alpha = 0.5d0 * alpha
                        cycle
                    end if
                    if (.not.evaluate_homotopy(candidate(1:n), candidate(n+1), &
                        trial_residual)) exit
                    arc_error = dot_product(tangent, candidate - predictor)
                    trial_merit = sqrt(dot_product(trial_residual, trial_residual) + &
                        arc_error**2)
                    if (ieee_is_finite(trial_merit) .and. trial_merit < merit) then
                        accepted = .true.
                        history_residual = maxval(abs(trial_residual))
                        exit
                    end if
                    alpha = 0.5d0 * alpha
                end do
                niter = niter + 1
                if (present(ib)) then
                    call ib%log_iteration(history_residual, nan, nan)
                end if
                if (.not.accepted) exit
            end do

            lambda_new = candidate(n+1)
            if (corrected .and. (endpoint_step .or. lambda_new >= 1.0d0)) then
                ! Interpolate the last arclength segment to lambda=1 and accept
                ! only after checking the actual target-system residual.
                if (lambda_new > lambda) then
                    alpha = min(1.0d0, max(0.0d0, (1.0d0-lambda) / &
                        (lambda_new-lambda)))
                    x = x + alpha * (candidate(1:n)-x)
                    if (neval >= maxeval) exit
                    call fcn%fcn(x, fvec, args)
                    neval = neval + 1
                    success = all(ieee_is_finite(fvec)) .and. maxval(abs(fvec)) <= ftol
                    if (success) exit
                end if
                x = z(1:n)
                lambda = z(n+1)
                ds = 0.5d0 * ds
                if (ds < this%m_minimumStep) exit
                cycle
            end if

            if (corrected) then
                x = candidate(1:n)
                lambda = lambda_new
                if (abs(1.0d0-lambda) <= lambda_tol) then
                    if (neval >= maxeval) exit
                    call fcn%fcn(x, fvec, args)
                    neval = neval + 1
                    success = all(ieee_is_finite(fvec)) .and. maxval(abs(fvec)) <= ftol
                    if (success) exit
                end if

                ! The bordered system selects the tangent consistent with the
                ! previous direction, preventing arbitrary sign reversals.
                if (.not.get_derivatives(x, lambda, jac, lambda_jac)) exit
                augmented = 0.0d0
                augmented(1:n,1:n) = jac
                augmented(1:n,n+1) = lambda_jac
                augmented(n+1,:) = tangent
                rhs = 0.0d0
                rhs(n+1) = 1.0d0
                call this%solve_dgelsy(augmented, rhs, delta, qr_success)
                if (.not.qr_success) exit
                tangent = delta
                tangent_norm = norm2(tangent)
                if (tangent_norm <= tiny(tangent_norm)) exit
                tangent = tangent / tangent_norm
                ds = min(this%m_initialStep, 1.25d0 * ds)
            else
                x = z(1:n)
                lambda = z(n+1)
                ds = 0.5d0 * ds
                if (ds < this%m_minimumStep) exit
            end if
        end do

900     continue
        if (present(ib)) then
            ib%iter_count = niter
            ib%fcn_count = neval
            ib%jacobian_count = njac
            ib%gradient_count = 0
            ib%converge_on_fcn = success
            ib%converge_on_chng = .false.
            ib%converge_on_zero_diff = .false.
        end if

    contains
        logical function evaluate_homotopy(point, parameter, value)
            real(real64), intent(in), dimension(:) :: point
            real(real64), intent(in) :: parameter
            real(real64), intent(out), dimension(:) :: value
            if (neval >= maxeval) then
                evaluate_homotopy = .false.
                return
            end if
            call this%homotopy(fcn, point, x0, parameter, value, args)
            neval = neval + 1
            evaluate_homotopy = all(ieee_is_finite(value))
        end function

        logical function get_derivatives(point, parameter, point_jac, lambda_jacobian)
            real(real64), intent(inout), dimension(:) :: point
            real(real64), intent(in) :: parameter
            real(real64), intent(out), dimension(:,:) :: point_jac
            real(real64), intent(out), dimension(:) :: lambda_jacobian
            call this%homotopy_jacobian(fcn, point, x0, parameter, point_jac, args)
            call this%homotopy_lambda_derivative(fcn, point, x0, parameter, &
                lambda_jacobian, args)
            njac = njac + 1
            get_derivatives = all(ieee_is_finite(point_jac)) .and. &
                all(ieee_is_finite(lambda_jacobian))
        end function
    end subroutine

! ------------------------------------------------------------------------------
    subroutine cs_homotopy(this, fcn, x, x0, lambda, h, args)
        !! Evaluate \(H(x,\lambda)=(1-\lambda)*(x-x0)+\lambda*F(x)\).
        !! Extend [[continuation_solver]] and override this binding to change
        !! the path while reusing the continuation and corrector logic. Keep
        !! \(H(x0,0)=0\) and \(H(x,1)=F(x)\), and override homotopy_jacobian 
        !! with its derivative with respect to \(x\).
        class(continuation_solver), intent(inout) :: this
            !! The continuation solver instance.
        class(vecfcn_helper), intent(inout) :: fcn
            !! Helper containing the target system F.
        real(real64), intent(in), dimension(:) :: x
            !! Point at which the homotopy is evaluated.
        real(real64), intent(in), dimension(:) :: x0
            !! Initial point that anchors the default path.
        real(real64), intent(in) :: lambda
            !! Continuation parameter in [0,1].
        real(real64), intent(out), dimension(:) :: h
            !! Homotopy residual.
        class(*), intent(in), optional :: args
            !! User arguments forwarded to F.
        call fcn%fcn(x, h, args)
        h = (1.0d0 - lambda) * (x - x0) + lambda * h
    end subroutine

! ------------------------------------------------------------------------------
    subroutine cs_homotopy_jacobian(this, fcn, x, x0, lambda, jac, args)
        !! Evaluate \(J_H=(1-\lambda)I+\lambda*J_F\). [[vecfcn_helper]] selects 
        !! an analytic Jacobian, AD, or finite differences for \(J_F\). A custom
        !! homotopy override should also override this binding accordingly.
        class(continuation_solver), intent(inout) :: this
            !! The continuation solver instance.
        class(vecfcn_helper), intent(inout) :: fcn
            !! Helper containing the target system and its Jacobian behavior.
        real(real64), intent(inout), dimension(:) :: x
            !! Point at which the Jacobian is evaluated; unchanged on return.
        real(real64), intent(in), dimension(:) :: x0
            !! Initial point that anchors the default path.
        real(real64), intent(in) :: lambda
            !! Continuation parameter in [0,1].
        real(real64), intent(out), dimension(:,:) :: jac
            !! Jacobian of the homotopy with respect to x.
        class(*), intent(in), optional :: args
            !! User arguments forwarded to F.
        integer :: i
        call fcn%jacobian(x, jac, args = args)
        jac = lambda * jac
        do i = 1, size(jac,1)
            jac(i,i) = jac(i,i) + 1.0d0 - lambda
        end do
    end subroutine

! ------------------------------------------------------------------------------
    subroutine cs_homotopy_lambda_derivative(this, fcn, x, x0, lambda, deriv, args)
        !! Evaluate the default path derivative H_lambda=F(x)-(x-x0).
        !! Override this binding along with homotopy and homotopy_jacobian when
        !! defining a custom homotopy.
        class(continuation_solver), intent(inout) :: this
        class(vecfcn_helper), intent(inout) :: fcn
        real(real64), intent(in), dimension(:) :: x
        real(real64), intent(in), dimension(:) :: x0
        real(real64), intent(in) :: lambda
        real(real64), intent(out), dimension(:) :: deriv
        class(*), intent(in), optional :: args
        call fcn%fcn(x, deriv, args)
        deriv = deriv - (x - x0)
    end subroutine

! ------------------------------------------------------------------------------
    pure function cs_get_use_pseudo_arclength(this) result(use_pseudo)
        !! Query whether pseudo-arclength continuation is enabled.
        class(continuation_solver), intent(in) :: this
        logical :: use_pseudo
        use_pseudo = this%m_usePseudoArclength
    end function

! ------------------------------------------------------------------------------
    subroutine cs_set_use_pseudo_arclength(this, use_pseudo)
        !! Select pseudo-arclength continuation instead of fixed-lambda steps.
        class(continuation_solver), intent(inout) :: this
        logical, intent(in) :: use_pseudo
        this%m_usePseudoArclength = use_pseudo
    end subroutine

! ------------------------------------------------------------------------------
    pure function cs_get_initial_step(this) result(step)
        !! Get the initial and maximum continuation step.
        class(continuation_solver), intent(in) :: this
            !! Solver whose step size is queried.
        real(real64) :: step
            !! Current initial/maximum lambda increment.
        step = this%m_initialStep
    end function

! ------------------------------------------------------------------------------
    subroutine cs_set_initial_step(this, step)
        !! Set the initial and maximum continuation step, clamped to (0,1].
        class(continuation_solver), intent(inout) :: this
            !! Solver whose step size is changed.
        real(real64), intent(in) :: step
            !! Requested lambda increment. Values outside (0,1] are clamped.
        this%m_initialStep = max(this%m_minimumStep, min(1.0d0, step))
    end subroutine

! ------------------------------------------------------------------------------
    pure function cs_get_minimum_step(this) result(step)
        !! Get the minimum continuation step before failure is reported.
        class(continuation_solver), intent(in) :: this
            !! Solver whose minimum step is queried.
        real(real64) :: step
            !! Current minimum lambda increment.
        step = this%m_minimumStep
    end function

! ------------------------------------------------------------------------------
    subroutine cs_set_minimum_step(this, step)
        !! Set the smallest continuation step that the solver will attempt.
        class(continuation_solver), intent(inout) :: this
            !! Solver whose minimum step is changed.
        real(real64), intent(in) :: step
            !! Requested minimum lambda increment, clamped to [epsilon,1].
        this%m_minimumStep = max(epsilon(1.0d0), min(1.0d0, step))
        this%m_initialStep = max(this%m_initialStep, this%m_minimumStep)
    end subroutine

! ------------------------------------------------------------------------------
    pure function cs_get_max_corrector_iterations(this) result(n)
        !! Get the maximum Newton corrections allowed per continuation step.
        class(continuation_solver), intent(in) :: this
            !! Solver whose corrector limit is queried.
        integer :: n
            !! Current corrector iteration limit.
        n = this%m_maxCorrectorIterations
    end function

! ------------------------------------------------------------------------------
    subroutine cs_set_max_corrector_iterations(this, n)
        !! Set the maximum Newton corrections allowed per continuation step.
        class(continuation_solver), intent(inout) :: this
            !! Solver whose corrector limit is changed.
        integer, intent(in) :: n
            !! Requested limit. Values below one are clamped to one.
        this%m_maxCorrectorIterations = max(1, n)
    end subroutine

! ------------------------------------------------------------------------------
end module