From f3a7cccbcca370cd7995ac98907c47d0fcd1c254 Mon Sep 17 00:00:00 2001 From: Avik Pal Date: Tue, 22 Oct 2024 18:16:46 -0400 Subject: [PATCH] docs: update documentation --- .github/workflows/Documentation.yml | 2 +- .github/workflows/Downgrade.yml | 34 ++++++++++++++++++--- docs/Project.toml | 7 +++-- docs/make.jl | 8 +++-- docs/pages.jl | 4 ++- docs/src/basics/diagnostics_api.md | 20 +++++------- docs/src/basics/solve.md | 2 +- docs/src/basics/termination_condition.md | 22 ++++++++----- docs/src/devdocs/algorithm_helpers.md | 3 -- docs/src/native/bracketingnonlinearsolve.md | 21 +++++++++++++ docs/src/native/simplenonlinearsolve.md | 16 +--------- docs/src/tutorials/modelingtoolkit.md | 28 ++++++++--------- lib/BracketingNonlinearSolve/README.md | 23 ++++++++++++++ lib/NonlinearSolveBase/src/public.jl | 2 +- lib/SimpleNonlinearSolve/README.md | 23 ++++++++++++++ 15 files changed, 149 insertions(+), 66 deletions(-) create mode 100644 docs/src/native/bracketingnonlinearsolve.md create mode 100644 lib/BracketingNonlinearSolve/README.md create mode 100644 lib/SimpleNonlinearSolve/README.md diff --git a/.github/workflows/Documentation.yml b/.github/workflows/Documentation.yml index 84f38404f..9dc416799 100644 --- a/.github/workflows/Documentation.yml +++ b/.github/workflows/Documentation.yml @@ -15,7 +15,7 @@ jobs: - uses: actions/checkout@v4 - uses: julia-actions/setup-julia@latest with: - version: '1' + version: '1.10' - name: Install dependencies run: | import Pkg diff --git a/.github/workflows/Downgrade.yml b/.github/workflows/Downgrade.yml index 83001be29..39633e263 100644 --- a/.github/workflows/Downgrade.yml +++ b/.github/workflows/Downgrade.yml @@ -15,14 +15,40 @@ jobs: runs-on: ubuntu-latest strategy: matrix: - version: ["1.10"] + version: + - "1.10" + group: + - Core + - Downstream + - Misc + - Wrappers steps: - uses: actions/checkout@v4 - uses: julia-actions/setup-julia@v2 with: version: ${{ matrix.version }} - uses: julia-actions/julia-downgrade-compat@v1 + - name: "Install Dependencies and Run Tests" + run: | + import Pkg + Pkg.Registry.update() + # Install packages present in subdirectories + dev_pks = Pkg.PackageSpec[] + for path in ("lib/SciMLJacobianOperators", "lib/BracketingNonlinearSolve", "lib/NonlinearSolveBase", "lib/SimpleNonlinearSolve") + push!(dev_pks, Pkg.PackageSpec(; path)) + end + Pkg.develop(dev_pks) + Pkg.instantiate() + Pkg.test(; coverage=true) + shell: julia --color=yes --code-coverage=user --depwarn=yes --project=. {0} + env: + GROUP: ${{ matrix.group }} + - uses: julia-actions/julia-processcoverage@v1 with: - skip: Pkg,TOML - - uses: julia-actions/julia-buildpkg@v1 - - uses: julia-actions/julia-runtest@v1 + directories: src,ext,lib/SciMLJacobianOperators/src + - uses: codecov/codecov-action@v4 + with: + file: lcov.info + token: ${{ secrets.CODECOV_TOKEN }} + verbose: true + fail_ci_if_error: true diff --git a/docs/Project.toml b/docs/Project.toml index d01ae32a1..2f2e1bab5 100644 --- a/docs/Project.toml +++ b/docs/Project.toml @@ -3,6 +3,7 @@ ADTypes = "47edcb42-4c32-4615-8424-f2b9edc5f35b" AlgebraicMultigrid = "2169fc97-5a83-5252-b627-83903c6c433c" ArrayInterface = "4fba245c-0d91-5ea0-9b3e-6abc04ee57a9" BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf" +BracketingNonlinearSolve = "70df07ce-3d50-431d-a3e7-ca6ddb60ac1e" DiffEqBase = "2b5f629d-d688-5b77-993f-72d75c75574e" DifferentiationInterface = "a0c0ee7d-e4b9-4e03-894e-1c5f64a51d63" Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" @@ -11,8 +12,8 @@ DocumenterInterLinks = "d12716ef-a0f6-4df4-a9f1-a5a34e75c656" IncompleteLU = "40713840-3770-5561-ab4c-a76e7d0d7895" InteractiveUtils = "b77e0a4c-d291-57a0-90e8-8db25a27a240" LinearSolve = "7ed4a6bd-45f5-4d41-b270-4a48e9bafcae" -ModelingToolkit = "961ee093-0014-501f-94e3-6117800e7a78" NonlinearSolve = "8913a72c-1f9b-4ce2-8d82-65094dcecaec" +NonlinearSolveBase = "be0214bd-f91f-a760-ac4e-3421ce2b2da0" OrdinaryDiffEqTsit5 = "b1df2697-797e-41e3-8120-5422d3b24e4a" Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80" Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c" @@ -29,7 +30,7 @@ ADTypes = "1.9.0" AlgebraicMultigrid = "0.5, 0.6" ArrayInterface = "6, 7" BenchmarkTools = "1" -DiffEqBase = "6.136" +BracketingNonlinearSolve = "1" DifferentiationInterface = "0.6.1" Documenter = "1" DocumenterCitations = "1" @@ -37,8 +38,8 @@ DocumenterInterLinks = "1.0.0" IncompleteLU = "0.2" InteractiveUtils = "<0.0.1, 1" LinearSolve = "2" -ModelingToolkit = "9" NonlinearSolve = "4" +NonlinearSolveBase = "1" OrdinaryDiffEqTsit5 = "1.1.0" Plots = "1" Random = "1.10" diff --git a/docs/make.jl b/docs/make.jl index eec25f4f7..bdc2b7fe9 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -1,7 +1,8 @@ using Documenter, DocumenterCitations, DocumenterInterLinks using NonlinearSolve, SimpleNonlinearSolve, Sundials, SteadyStateDiffEq, SciMLBase, - DiffEqBase + BracketingNonlinearSolve, NonlinearSolveBase using SciMLJacobianOperators +import DiffEqBase cp(joinpath(@__DIR__, "Manifest.toml"), joinpath(@__DIR__, "src/assets/Manifest.toml"), force = true) @@ -20,8 +21,9 @@ interlinks = InterLinks( makedocs(; sitename = "NonlinearSolve.jl", authors = "Chris Rackauckas", - modules = [NonlinearSolve, SimpleNonlinearSolve, SteadyStateDiffEq, - Sundials, DiffEqBase, SciMLBase, SciMLJacobianOperators], + modules = [NonlinearSolve, SimpleNonlinearSolve, SteadyStateDiffEq, DiffEqBase, + Sundials, NonlinearSolveBase, SciMLBase, SciMLJacobianOperators, + BracketingNonlinearSolve], clean = true, doctest = false, linkcheck = true, diff --git a/docs/pages.jl b/docs/pages.jl index cfb2754c0..8da01762a 100644 --- a/docs/pages.jl +++ b/docs/pages.jl @@ -1,6 +1,7 @@ # Put in a separate page so it can be used by SciMLDocs.jl -pages = ["index.md", +pages = [ + "index.md", "Getting Started with Nonlinear Rootfinding in Julia" => "tutorials/getting_started.md", "Tutorials" => Any[ "tutorials/code_optimization.md", @@ -31,6 +32,7 @@ pages = ["index.md", "Native Functionalities" => Any[ "native/solvers.md", "native/simplenonlinearsolve.md", + "native/bracketingnonlinearsolve.md", "native/steadystatediffeq.md", "native/descent.md", "native/globalization.md", diff --git a/docs/src/basics/diagnostics_api.md b/docs/src/basics/diagnostics_api.md index c8b207544..795348bd6 100644 --- a/docs/src/basics/diagnostics_api.md +++ b/docs/src/basics/diagnostics_api.md @@ -27,20 +27,16 @@ Note that you will have to restart Julia to disable the timer outputs once enabl ## Example Usage ```@example diagnostics_example -using ModelingToolkit, NonlinearSolve +using NonlinearSolve -@variables x y z -@parameters σ ρ β +function nlfunc(resid, u0, p) + resid[1] = u0[1] * u0[1] - p + resid[2] = u0[2] * u0[2] - p + resid[3] = u0[3] * u0[3] - p + nothing +end -# Define a nonlinear system -eqs = [0 ~ σ * (y - x), 0 ~ x * (ρ - z) - y, 0 ~ x * y - β * z] -@mtkbuild ns = NonlinearSystem(eqs, [x, y, z], [σ, ρ, β]) - -u0 = [x => 1.0, y => 0.0, z => 0.0] - -ps = [σ => 10.0 ρ => 26.0 β => 8 / 3] - -prob = NonlinearProblem(ns, u0, ps) +prob = NonlinearProblem(nlfunc, [1.0, 3.0, 5.0], 2.0) solve(prob) ``` diff --git a/docs/src/basics/solve.md b/docs/src/basics/solve.md index f7c238966..3bc7df056 100644 --- a/docs/src/basics/solve.md +++ b/docs/src/basics/solve.md @@ -1,7 +1,7 @@ # [Common Solver Options (Solve Keyword Arguments)](@id solver_options) ```@docs -solve(prob::SciMLBase.NonlinearProblem, args...; kwargs...) +solve(::NonlinearProblem, args...; kwargs...) ``` ## General Controls diff --git a/docs/src/basics/termination_condition.md b/docs/src/basics/termination_condition.md index 9a7c718ec..4ea98b4a5 100644 --- a/docs/src/basics/termination_condition.md +++ b/docs/src/basics/termination_condition.md @@ -23,17 +23,23 @@ terminated = cache(du, u, uprev) ### Absolute Tolerance ```@docs -AbsTerminationMode -AbsNormTerminationMode -AbsNormSafeTerminationMode -AbsNormSafeBestTerminationMode +NonlinearSolveBase.AbsTerminationMode +NonlinearSolveBase.AbsNormTerminationMode +NonlinearSolveBase.AbsNormSafeTerminationMode +NonlinearSolveBase.AbsNormSafeBestTerminationMode ``` ### Relative Tolerance ```@docs -RelTerminationMode -RelNormTerminationMode -RelNormSafeTerminationMode -RelNormSafeBestTerminationMode +NonlinearSolveBase.RelTerminationMode +NonlinearSolveBase.RelNormTerminationMode +NonlinearSolveBase.RelNormSafeTerminationMode +NonlinearSolveBase.RelNormSafeBestTerminationMode +``` + +### Both Tolerances + +```@docs +NonlinearSolveBase.NormTerminationMode ``` diff --git a/docs/src/devdocs/algorithm_helpers.md b/docs/src/devdocs/algorithm_helpers.md index 7b0f91a9f..c945b6003 100644 --- a/docs/src/devdocs/algorithm_helpers.md +++ b/docs/src/devdocs/algorithm_helpers.md @@ -60,9 +60,6 @@ NonlinearSolve.GenericTrustRegionScheme ## Miscellaneous ```@docs -SimpleNonlinearSolve.__nextfloat_tdir -SimpleNonlinearSolve.__prevfloat_tdir -SimpleNonlinearSolve.__max_tdir NonlinearSolve.callback_into_cache! NonlinearSolve.concrete_jac ``` diff --git a/docs/src/native/bracketingnonlinearsolve.md b/docs/src/native/bracketingnonlinearsolve.md new file mode 100644 index 000000000..2201378e1 --- /dev/null +++ b/docs/src/native/bracketingnonlinearsolve.md @@ -0,0 +1,21 @@ +# BracketingNonlinearSolve.jl + +These methods can be used independently of the rest of NonlinearSolve.jl + +```@index +Pages = ["bracketingnonlinearsolve.md"] +``` + +## Interval Methods + +These methods are suited for interval (scalar) root-finding problems, +i.e. [`IntervalNonlinearProblem`](@ref). + +```@docs +ITP +Alefeld +Bisection +Falsi +Ridder +Brent +``` diff --git a/docs/src/native/simplenonlinearsolve.md b/docs/src/native/simplenonlinearsolve.md index 0ff386898..777a81ef8 100644 --- a/docs/src/native/simplenonlinearsolve.md +++ b/docs/src/native/simplenonlinearsolve.md @@ -6,20 +6,6 @@ These methods can be used independently of the rest of NonlinearSolve.jl Pages = ["simplenonlinearsolve.md"] ``` -## Interval Methods - -These methods are suited for interval (scalar) root-finding problems, -i.e. `IntervalNonlinearProblem`. - -```@docs -ITP -Alefeld -Bisection -Falsi -Ridder -Brent -``` - ## General Methods These methods are suited for any general nonlinear root-finding problem, i.e. @@ -54,6 +40,6 @@ Squares problems. [^1]: Needs [`StaticArrays.jl`](https://github.com/JuliaArrays/StaticArrays.jl) to be installed and loaded for the non-allocating version. [^2]: This method is non-allocating if the termination condition is set to either `nothing` - (default) or [`AbsNormTerminationMode`](@ref). + (default) or [`NonlinearSolveBase.AbsNormTerminationMode`](@ref). [^3]: Only the defaults are guaranteed to work inside kernels. We try to provide warnings if the used version is not non-allocating. diff --git a/docs/src/tutorials/modelingtoolkit.md b/docs/src/tutorials/modelingtoolkit.md index 87b0a4405..e2016dde0 100644 --- a/docs/src/tutorials/modelingtoolkit.md +++ b/docs/src/tutorials/modelingtoolkit.md @@ -5,7 +5,7 @@ modeling system for the Julia SciML ecosystem. It adds a high-level interactive for the numerical solvers which can make it easy to symbolically modify and generate equations to be solved. The basic form of using ModelingToolkit looks as follows: -```@example mtk +```julia using ModelingToolkit, NonlinearSolve @variables x y z @@ -30,20 +30,20 @@ sol = solve(prob, NewtonRaphson()) As a symbolic system, ModelingToolkit can be used to represent the equations and derive new forms. For example, let's look at the equations: -```@example mtk +```julia equations(ns) ``` We can ask it what the Jacobian of our system is via `calculate_jacobian`: -```@example mtk +```julia calculate_jacobian(ns) ``` We can tell MTK to generate a computable form of this analytical Jacobian via `jac = true` to help the solver use efficient forms: -```@example mtk +```julia prob = NonlinearProblem(ns, u0, ps, jac = true) sol = solve(prob, NewtonRaphson()) ``` @@ -54,7 +54,7 @@ One of the major reasons for using ModelingToolkit is to allow structural simpli the systems. It's very easy to write down a mathematical model that, in theory, could be solved more simply. Let's take a look at a quick system: -```@example mtk +```julia @variables u1 u2 u3 u4 u5 eqs = [0 ~ u1 - sin(u5), 0 ~ u2 - cos(u1), 0 ~ u3 - hypot(u1, u2), 0 ~ u4 - hypot(u2, u3), 0 ~ u5 - hypot(u4, u1)] @@ -63,23 +63,23 @@ eqs = [0 ~ u1 - sin(u5), 0 ~ u2 - cos(u1), 0 ~ u3 - hypot(u1, u2), If we run structural simplification, we receive the following form: -```@example mtk +```julia sys = structural_simplify(sys) ``` -```@example mtk +```julia equations(sys) ``` How did it do this? Let's look at the `observed` to see the relationships that it found: -```@example mtk +```julia observed(sys) ``` Using ModelingToolkit, we can build and solve the simplified system: -```@example mtk +```julia u0 = [u5 .=> 1.0] prob = NonlinearProblem(sys, u0) sol = solve(prob, NewtonRaphson()) @@ -87,23 +87,23 @@ sol = solve(prob, NewtonRaphson()) We can then use symbolic indexing to retrieve any variable: -```@example mtk +```julia sol[u1] ``` -```@example mtk +```julia sol[u2] ``` -```@example mtk +```julia sol[u3] ``` -```@example mtk +```julia sol[u4] ``` -```@example mtk +```julia sol[u5] ``` diff --git a/lib/BracketingNonlinearSolve/README.md b/lib/BracketingNonlinearSolve/README.md new file mode 100644 index 000000000..85839107e --- /dev/null +++ b/lib/BracketingNonlinearSolve/README.md @@ -0,0 +1,23 @@ +# BracketingNonlinearSolve.jl + +Fast implementations of interval root finding algorithms in Julia that satisfy the SciML +common interface. BracketingNonlinearSolve.jl focuses on low-dependency implementations of +very fast methods for very small and simple problems. For the full set of solvers, see +[NonlinearSolve.jl](https://github.com/SciML/NonlinearSolve.jl), of which +BracketingNonlinearSolve.jl is just one solver set. + +For information on using the package, +[see the stable documentation](https://docs.sciml.ai/NonlinearSolve/stable/). Use the +[in-development documentation](https://docs.sciml.ai/NonlinearSolve/dev/) for the version of +the documentation which contains the unreleased features. + +## High Level Examples + +```julia +using BracketingNonlinearSolve + +f(u, p) = u .* u .- 2.0 +u0 = (1.0, 2.0) # brackets +probB = IntervalNonlinearProblem(f, u0) +sol = solve(probB, ITP()) +``` diff --git a/lib/NonlinearSolveBase/src/public.jl b/lib/NonlinearSolveBase/src/public.jl index eceea6d75..b39aa26d2 100644 --- a/lib/NonlinearSolveBase/src/public.jl +++ b/lib/NonlinearSolveBase/src/public.jl @@ -81,7 +81,7 @@ for norm_type in (:RelNorm, :AbsNorm), safety in (:Safe, :SafeBest) supertype_name = Symbol(:Abstract, safety, :NonlinearTerminationMode) doctring = safety == :Safe ? - "Essentially [`$(norm_type)NormTerminationMode`](@ref) + terminate if there \ + "Essentially [`$(norm_type)TerminationMode`](@ref) + terminate if there \ has been no improvement for the last `patience_steps` + terminate if the \ solution blows up (diverges)." : "Essentially [`$(norm_type)SafeTerminationMode`](@ref), but caches the best\ diff --git a/lib/SimpleNonlinearSolve/README.md b/lib/SimpleNonlinearSolve/README.md new file mode 100644 index 000000000..562a5a4ae --- /dev/null +++ b/lib/SimpleNonlinearSolve/README.md @@ -0,0 +1,23 @@ +# SimpleNonlinearSolve.jl + +Fast implementations of root finding algorithms in Julia that satisfy the SciML common interface. +SimpleNonlinearSolve.jl focuses on low-dependency implementations of very fast methods for +very small and simple problems. For the full set of solvers, see +[NonlinearSolve.jl](https://github.com/SciML/NonlinearSolve.jl), of which +SimpleNonlinearSolve.jl is just one solver set. + +For information on using the package, +[see the stable documentation](https://docs.sciml.ai/NonlinearSolve/stable/). Use the +[in-development documentation](https://docs.sciml.ai/NonlinearSolve/dev/) for the version of +the documentation which contains the unreleased features. + +## High Level Examples + +```julia +using SimpleNonlinearSolve, StaticArrays + +f(u, p) = u .* u .- 2 +u0 = @SVector[1.0, 1.0] +probN = NonlinearProblem{false}(f, u0) +solver = solve(probN, SimpleNewtonRaphson(), abstol = 1e-9) +```