Merge #40

40: Add RelativeSolutionTolerance option r=akshaysridhar a=akshaysridhar

Add new specialisation  `RelativeSolutionTolerance{FT} <: AbstractTolerance{FT}` + test + API docs update.
	modified:   src/RootSolvers.jl
	modified:   test/test_helper.jl
        modified:   docs/src/API.md
Bump minor version -> 0.3.4

# PULL REQUEST

## Purpose and Content
Adds a convergence criteria based on relative difference between consecutive iterations. 

## Benefits and Risks
Provides an additional option for convergence criteria. 
Risks: Can be mitigated through appropriate tests. 

## PR Checklist
- [ ] This PR has a corresponding issue OR is linked to an SDI.
- [x] I have followed CliMA's codebase [contribution](https://clima.github.io/ClimateMachine.jl/latest/Contributing/) and [style](https://clima.github.io/ClimateMachine.jl/latest/DevDocs/CodeStyle/) guidelines OR N/A.
- [x] I have followed CliMA's [documentation policy](https://github.com/CliMA/policies/wiki/Documentation-Policy).
- [x] I have checked all issues and PRs and I certify that this PR does not duplicate an open PR.
- [x] I linted my code on my local machine prior to submission OR N/A.
- [x] Unit tests are included OR N/A.
- [x] Code used in an integration test OR N/A.
- [x] All tests ran successfully on my local machine OR N/A.
- [x] All classes, modules, and function contain docstrings OR N/A.
- [x] Documentation has been added/updated OR N/A.


Co-authored-by: Akshay Sridhar <[email protected]>

Project.toml

@@ -1,7 +1,7 @@
 name = "RootSolvers"
 uuid = "7181ea78-2dcb-4de3-ab41-2b8ab5a31e74"
 authors = ["CliMA Contributors <[email protected]>"]
-version = "0.3.3"
+version = "0.3.4"
 
 [deps]
 DocStringExtensions = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"

docs/src/API.md

@@ -34,6 +34,7 @@ CompactSolutionResults
 ```@docs
 ResidualTolerance
 SolutionTolerance
+RelativeSolutionTolerance
 ```
 
 ## Internal helper methods

src/RootSolvers.jl

@@ -26,7 +26,7 @@ using DocStringExtensions: FIELDS
 export find_zero,
     SecantMethod, RegulaFalsiMethod, NewtonsMethodAD, NewtonsMethod
 export CompactSolution, VerboseSolution
-export AbstractTolerance, ResidualTolerance, SolutionTolerance
+export AbstractTolerance, ResidualTolerance, SolutionTolerance, RelativeSolutionTolerance
 
 import ForwardDiff
 
@@ -199,6 +199,22 @@ Evaluates solution tolerance, based on ``|x2-x1|``
 """
 (tol::SolutionTolerance)(x1, x2, y) = abs(x2 - x1) < tol.tol
 
+"""
+    RelativeSolutionTolerance
+
+A tolerance type based on consecutive iterations of solution ``x`` of the equation ``f(x) = 0``
+"""
+struct RelativeSolutionTolerance{FT} <: AbstractTolerance{FT}
+    tol::FT
+end
+
+"""
+    (tol::RelativeSolutionTolerance)(x1, x2, y)
+
+Evaluates solution tolerance, based on ``|(x2-x1)/x1|``
+"""
+(tol::RelativeSolutionTolerance)(x1, x2, y) = abs((x2 - x1)/x1) < tol.tol
+
 # TODO: CuArrays.jl has trouble with isapprox on 1.1
 # we use simple checks for now, will switch to relative checks later.
 

test/test_helper.jl

@@ -31,7 +31,7 @@ end
 problem_size() = 5
 problem_size(::RootSolvingProblem{S,F,F′,FT,FTA,N}) where {S,F,F′,FT,FTA,N} = N
 float_types() = [Float32, Float64]
-get_tolerances(FT) = [ResidualTolerance{FT}(1e-6), SolutionTolerance{FT}(1e-3), nothing]
+get_tolerances(FT) = [ResidualTolerance{FT}(1e-6), SolutionTolerance{FT}(1e-3), RelativeSolutionTolerance{FT}(sqrt(eps(FT))), nothing]
 
 test_verbose!(::CompactSolution, sol, problem, tol, converged) = nothing
 function test_verbose!(::VerboseSolution, sol, problem, tol, converged)