Possibly incorrect tolerance in NLsolve

[bclyons12]

Describe the bug 🐞

In NonlinearSolve, I can set abstol and reltol. In NLsolve, you can set ftol and xtol. Right now, NonlinearSolve/ext/NonlinearSolveNLsolveExt.jl sets ftol = abstol, but according to NLsolve.jl, ftol is defined as the "infinite norm of residuals under which convergence is declared." My understanding of NonlinearSolve.jl is that abstol is a tolerance on u, not the residual, so abstol would be more equivalent to xtol than ftol. Note that xtol is defined as the "norm difference in x between two successive iterates under which convergence is declared."

So there are two issues:

1. Should NonlinearSolveNLsolveExt.jl set xtol=abstol instead?
2. Is there a way to provide the other NLsolve tolerance through NonlinearSolve?

Expected behavior

Tolerance definitions should be consistent between NonlinearSolve and NLsolve.

Minimal Reproducible Example 👇

using NLsolve

abstol = 1e-12
x0 = [0.9, 0.9]
function f!(F, x)
   ε = 1e-1

    # shift to u = x − 1 for more compact formulas
    u1, u2 = x[1] - 1, x[2] - 1

    # a little nonlinear “bump” to help initial convergence
    q = u1^2 * u2^2

    # nearly singular linear part + small nonlinear correction
    F[1] =  u1 - u2 +      q
    F[2] = -u1 + (1+ε)*u2  + q
end

#= 
ftol=abstol gives:
Iter     f(x) inf-norm    Step 2-norm 
------   --------------   --------------
     1     9.900000e-03              NaN
     2     4.909565e-03     1.089805e-05
     3     4.672043e-03     1.040635e-05
     4     2.797769e-04     3.913756e-08
     5     4.434413e-06     9.832007e-12
     6     1.686321e-11     1.421815e-22
     7     1.097655e-09     5.730556e-19
     8     1.097974e-09     5.733886e-19
     9     4.965806e-13     1.126204e-25
=#
res = NLsolve.nlsolve(f!, x0;
                show_trace=true,
                store_trace=false,
                extended_trace=false,
                iterations=100,
                ftol=abstol,
                method=:anderson, m=4, beta=-0.5);

#= 
xtol=abstol gives:
Iter     f(x) inf-norm    Step 2-norm 
------   --------------   --------------
     1     9.900000e-03              NaN
     2     4.909565e-03     1.089805e-05
     3     4.672043e-03     1.040635e-05
     4     2.797769e-04     3.913756e-08
     5     4.434413e-06     9.832007e-12
     6     1.686321e-11     1.421815e-22
=#
res = NLsolve.nlsolve(f!, x0;
                show_trace=true,
                store_trace=false,
                extended_trace=false,
                iterations=100,
                xtol=abstol,
                method=:anderson, m=4, beta=-0.5);

using NonlinearSolve

g! = (F, u, _p) -> f!(F, u)

problem = NonlinearSolve.NonlinearProblem(g!, x0)

alg = NonlinearSolve.NLsolveJL(method = :anderson, m = 4, beta = -0.5)


#= 
Here abstol behaves like ftol
Iter     f(x) inf-norm    Step 2-norm 
------   --------------   --------------
     1     9.900000e-03              NaN
     2     4.909565e-03     1.089805e-05
     3     4.672043e-03     1.040635e-05
     4     2.797769e-04     3.913756e-08
     5     4.434413e-06     9.832007e-12
     6     1.686321e-11     1.421815e-22
     7     1.097655e-09     5.730556e-19
     8     1.097974e-09     5.733886e-19
     9     4.965806e-13     1.126204e-25
=#
sol = NonlinearSolve.solve(problem, alg;
            abstol,
            maxiters = 100,
            show_trace = Val(true),
            store_trace = Val(false),
            verbose    = false);

Environment (please complete the following information):

• Output of using Pkg; Pkg.status()

  [2774e3e8] NLsolve v4.5.1
  [8913a72c] NonlinearSolve v4.8.0

• Output of using Pkg; Pkg.status(; mode = PKGMODE_MANIFEST)

  [47edcb42] ADTypes v1.14.0
  [7d9f7c33] Accessors v0.1.42
  [79e6a3ab] Adapt v4.3.0
  [4fba245c] ArrayInterface v7.18.0
  [4c555306] ArrayLayouts v1.11.1
  [62783981] BitTwiddlingConvenienceFunctions v0.1.6
  [70df07ce] BracketingNonlinearSolve v1.2.0
  [2a0fbf3d] CPUSummary v0.2.6
  [d360d2e6] ChainRulesCore v1.25.1
  [fb6a15b2] CloseOpenIntervals v0.1.13
  [38540f10] CommonSolve v0.2.4
  [bbf7d656] CommonSubexpressions v0.3.1
  [f70d9fcc] CommonWorldInvalidations v1.0.0
  [34da2185] Compat v4.16.0
  [a33af91c] CompositionsBase v0.1.2
  [2569d6c7] ConcreteStructs v0.2.3
  [187b0558] ConstructionBase v1.5.8
  [adafc99b] CpuId v0.3.1
  [a8cc5b0e] Crayons v4.1.1
  [9a962f9c] DataAPI v1.16.0
  [864edb3b] DataStructures v0.18.22
  [e2d170a0] DataValueInterfaces v1.0.0
  [2b5f629d] DiffEqBase v6.170.1
  [163ba53b] DiffResults v1.1.0
  [b552c78f] DiffRules v1.15.1
  [a0c0ee7d] DifferentiationInterface v0.6.52
  [b4f34e82] Distances v0.10.12
  [ffbed154] DocStringExtensions v0.9.4
  [4e289a0a] EnumX v1.0.5
  [f151be2c] EnzymeCore v0.8.8
  [e2ba6199] ExprTools v0.1.10
  [55351af7] ExproniconLite v0.10.14
  [7034ab61] FastBroadcast v0.3.5
  [9aa1b823] FastClosures v0.3.2
  [a4df4552] FastPower v1.1.2
  [1a297f60] FillArrays v1.13.0
  [6a86dc24] FiniteDiff v2.27.0
  [f6369f11] ForwardDiff v1.0.1
  [069b7b12] FunctionWrappers v1.1.3
  [77dc65aa] FunctionWrappersWrappers v0.1.3
  [46192b85] GPUArraysCore v0.2.0
  [615f187c] IfElse v0.1.1
  [3587e190] InverseFunctions v0.1.17
  [92d709cd] IrrationalConstants v0.2.4
  [82899510] IteratorInterfaceExtensions v1.0.0
  [692b3bcd] JLLWrappers v1.7.0
  [ae98c720] Jieko v0.2.1
  [ba0b0d4f] Krylov v0.10.0
  [b964fa9f] LaTeXStrings v1.4.0
  [10f19ff3] LayoutPointers v0.1.17
  [5078a376] LazyArrays v2.6.1
  [87fe0de2] LineSearch v0.1.4
  [d3d80556] LineSearches v7.3.0
  [7ed4a6bd] LinearSolve v3.9.0
  [2ab3a3ac] LogExpFunctions v0.3.29
  [1914dd2f] MacroTools v0.5.16
  [d125e4d3] ManualMemory v0.1.8
  [bb5d69b7] MaybeInplace v0.1.4
  [2e0e35c7] Moshi v0.3.5
  [46d2c3a1] MuladdMacro v0.2.4
  [d41bc354] NLSolversBase v7.9.1
  [2774e3e8] NLsolve v4.5.1
  [77ba4419] NaNMath v1.1.3
  [8913a72c] NonlinearSolve v4.8.0
  [be0214bd] NonlinearSolveBase v1.6.0
  [5959db7a] NonlinearSolveFirstOrder v1.4.0
  [9a2c21bd] NonlinearSolveQuasiNewton v1.3.0
  [26075421] NonlinearSolveSpectralMethods v1.2.0
  [bac558e1] OrderedCollections v1.8.0
  [d96e819e] Parameters v0.12.3
  [f517fe37] Polyester v0.7.16
  [1d0040c9] PolyesterWeave v0.2.2
⌅ [aea7be01] PrecompileTools v1.2.1
  [21216c6a] Preferences v1.4.3
  [08abe8d2] PrettyTables v2.4.0
  [3cdcf5f2] RecipesBase v1.3.4
  [731186ca] RecursiveArrayTools v3.33.0
  [189a3867] Reexport v1.2.2
  [ae029012] Requires v1.3.1
  [7e49a35a] RuntimeGeneratedFunctions v0.5.14
  [94e857df] SIMDTypes v0.1.0
  [0bca4576] SciMLBase v2.86.2
  [19f34311] SciMLJacobianOperators v0.1.3
  [c0aeaf25] SciMLOperators v0.3.13
  [53ae85a6] SciMLStructures v1.7.0
  [efcf1570] Setfield v1.1.2
  [727e6d20] SimpleNonlinearSolve v2.3.0
  [0a514795] SparseMatrixColorings v0.4.19
  [276daf66] SpecialFunctions v2.5.1
  [aedffcd0] Static v1.2.0
  [0d7ed370] StaticArrayInterface v1.8.0
  [1e83bf80] StaticArraysCore v1.4.3
  [10745b16] Statistics v1.11.1
  [82ae8749] StatsAPI v1.7.0
  [7792a7ef] StrideArraysCore v0.5.7
  [892a3eda] StringManipulation v0.4.1
  [2efcf032] SymbolicIndexingInterface v0.3.40
  [3783bdb8] TableTraits v1.0.1
  [bd369af6] Tables v1.12.0
  [8290d209] ThreadingUtilities v0.5.3
  [a759f4b9] TimerOutputs v0.5.28
  [781d530d] TruncatedStacktraces v1.4.0
  [3a884ed6] UnPack v1.0.2
  [1d5cc7b8] IntelOpenMP_jll v2025.0.4+0
  [856f044c] MKL_jll v2025.0.1+1
  [efe28fd5] OpenSpecFun_jll v0.5.6+0
  [1317d2d5] oneTBB_jll v2022.0.0+0
  [0dad84c5] ArgTools v1.1.2
  [56f22d72] Artifacts v1.11.0
  [2a0f44e3] Base64 v1.11.0
  [ade2ca70] Dates v1.11.0
  [8ba89e20] Distributed v1.11.0
  [f43a241f] Downloads v1.6.0
  [7b1f6079] FileWatching v1.11.0
  [9fa8497b] Future v1.11.0
  [b77e0a4c] InteractiveUtils v1.11.0
  [4af54fe1] LazyArtifacts v1.11.0
  [b27032c2] LibCURL v0.6.4
  [76f85450] LibGit2 v1.11.0
  [8f399da3] Libdl v1.11.0
  [37e2e46d] LinearAlgebra v1.11.0
  [56ddb016] Logging v1.11.0
  [d6f4376e] Markdown v1.11.0
  [ca575930] NetworkOptions v1.2.0
  [44cfe95a] Pkg v1.11.0
  [de0858da] Printf v1.11.0
  [9a3f8284] Random v1.11.0
  [ea8e919c] SHA v0.7.0
  [9e88b42a] Serialization v1.11.0
  [6462fe0b] Sockets v1.11.0
  [2f01184e] SparseArrays v1.11.0
  [fa267f1f] TOML v1.0.3
  [a4e569a6] Tar v1.10.0
  [cf7118a7] UUIDs v1.11.0
  [4ec0a83e] Unicode v1.11.0
  [e66e0078] CompilerSupportLibraries_jll v1.1.1+0
  [deac9b47] LibCURL_jll v8.6.0+0
  [e37daf67] LibGit2_jll v1.7.2+0
  [29816b5a] LibSSH2_jll v1.11.0+1
  [c8ffd9c3] MbedTLS_jll v2.28.6+0
  [14a3606d] MozillaCACerts_jll v2023.12.12
  [4536629a] OpenBLAS_jll v0.3.27+1
  [05823500] OpenLibm_jll v0.8.5+0
  [bea87d4a] SuiteSparse_jll v7.7.0+0
  [83775a58] Zlib_jll v1.2.13+1
  [8e850b90] libblastrampoline_jll v5.11.0+0
  [8e850ede] nghttp2_jll v1.59.0+0
  [3f19e933] p7zip_jll v17.4.0+2

• Output of versioninfo()

Julia Version 1.11.5
Commit 760b2e5b739 (2025-04-14 06:53 UTC)
Build Info:
  Official https://julialang.org/ release
Platform Info:
  OS: macOS (arm64-apple-darwin24.0.0)
  CPU: 12 × Apple M4 Pro
  WORD_SIZE: 64
  LLVM: libLLVM-16.0.6 (ORCJIT, apple-m1)
Threads: 10 default, 0 interactive, 5 GC (on 8 virtual cores)
Environment:
  JULIA_NUM_THREADS = 10

[oscardssmith]

My understanding of NonlinearSolve.jl is that abstol is a tolerance on u, not the residual

This is incorrect. for NonlinearSolve.jl abstol is the tolerance on the residual. xtol in NLSolve.jl isn't really a good termination condition since it refers only to local behavior, not global behavior.

If you want to customize termination, see https://docs.sciml.ai/NonlinearSolve/stable/basics/termination_condition/ which allows for more highly customized options.

[bclyons12]

@oscardssmith In https://docs.sciml.ai/NonlinearSolve/stable/basics/termination_condition/ , all the terminations conditions are based on u, not f(u). Could you please direct me to a reference for your statement:

for NonlinearSolve.jl abstol is the tolerance on the residual.

[oscardssmith]

@avik-pal I'm pretty sure these docs are incorrect. Can you confirm?