feat: add NonlinearSolveHomotopyContinuation.jl

.github/workflows/CI_NonlinearSolveHomotopyContinuation.yml

@@ -0,0 +1,108 @@
+name: CI (NonlinearSolveHomotopyContinuation)
+
+on:
+  pull_request:
+    branches:
+      - master
+    paths:
+      - "lib/NonlinearSolveHomotopyContinuation/**"
+      - ".github/workflows/CI_NonlinearSolveHomotopyContinuation.yml"
+      - "lib/NonlinearSolveBase/**"
+  push:
+    branches:
+      - master
+
+concurrency:
+  # Skip intermediate builds: always.
+  # Cancel intermediate builds: only if it is a pull request build.
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        version:
+          - "1.10"
+          - "1"
+        os:
+          - ubuntu-latest
+          - macos-latest
+          - windows-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v2
+        with:
+          version: ${{ matrix.version }}
+      - uses: actions/cache@v4
+        env:
+          cache-name: cache-artifacts
+        with:
+          path: ~/.julia/artifacts
+          key: ${{ runner.os }}-test-${{ env.cache-name }}-${{ hashFiles('**/Project.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-test-${{ env.cache-name }}-
+            ${{ runner.os }}-test-
+            ${{ runner.os }}-
+      - 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/NonlinearSolveBase",)
+              push!(dev_pks, Pkg.PackageSpec(; path))
+          end
+          Pkg.develop(dev_pks)
+          Pkg.instantiate()
+          Pkg.test(; coverage="user")
+        shell: julia --color=yes --code-coverage=user --depwarn=yes --project=lib/NonlinearSolveHomotopyContinuation {0}
+      - uses: julia-actions/julia-processcoverage@v1
+        with:
+          directories: lib/NonlinearSolveBase/src,lib/NonlinearSolveBase/ext,lib/NonlinearSolveHomotopyContinuation/src
+      - uses: codecov/codecov-action@v5
+        with:
+          file: lcov.info
+          token: ${{ secrets.CODECOV_TOKEN }}
+          verbose: true
+          fail_ci_if_error: false
+
+  downgrade:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        version:
+          - "1.10"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v2
+        with:
+          version: ${{ matrix.version }}
+      - uses: julia-actions/julia-downgrade-compat@v1
+        with:
+          skip: NonlinearSolveBase, SciMLJacobianOperators
+      - 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/NonlinearSolveBase",)
+              push!(dev_pks, Pkg.PackageSpec(; path))
+          end
+          Pkg.develop(dev_pks)
+          Pkg.instantiate()
+          Pkg.test(; coverage="user")
+        shell: julia --color=yes --code-coverage=user --depwarn=yes --project=lib/NonlinearSolveHomotopyContinuation {0}
+      - uses: julia-actions/julia-processcoverage@v1
+        with:
+          directories: lib/NonlinearSolveBase/src,lib/NonlinearSolveBase/ext,lib/NonlinearSolveHomtopyContinuation/src
+      - uses: codecov/codecov-action@v5
+        with:
+          file: lcov.info
+          token: ${{ secrets.CODECOV_TOKEN }}
+          verbose: true
+          fail_ci_if_error: false

.github/workflows/Documentation.yml

@@ -22,7 +22,7 @@ jobs:
           Pkg.Registry.update()
           # Install packages present in subdirectories
           dev_pks = Pkg.PackageSpec[]
-          for path in ("lib/SciMLJacobianOperators", ".", "lib/SimpleNonlinearSolve", "lib/NonlinearSolveBase", "lib/BracketingNonlinearSolve", "lib/NonlinearSolveFirstOrder", "lib/NonlinearSolveQuasiNewton", "lib/NonlinearSolveSpectralMethods")
+          for path in ("lib/SciMLJacobianOperators", ".", "lib/SimpleNonlinearSolve", "lib/NonlinearSolveBase", "lib/BracketingNonlinearSolve", "lib/NonlinearSolveFirstOrder", "lib/NonlinearSolveQuasiNewton", "lib/NonlinearSolveSpectralMethods", "lib/NonlinearSolveHomotopyContinuation")
               push!(dev_pks, Pkg.PackageSpec(; path))
           end
           Pkg.develop(dev_pks)

docs/Project.toml

@@ -15,6 +15,7 @@ LinearSolve = "7ed4a6bd-45f5-4d41-b270-4a48e9bafcae"
 NonlinearSolve = "8913a72c-1f9b-4ce2-8d82-65094dcecaec"
 NonlinearSolveBase = "be0214bd-f91f-a760-ac4e-3421ce2b2da0"
 NonlinearSolveFirstOrder = "5959db7a-ea39-4486-b5fe-2dd0bf03d60d"
+NonlinearSolveHomotopyContinuation = "2ac3b008-d579-4536-8c91-a1a5998c2f8b"
 NonlinearSolveQuasiNewton = "9a2c21bd-3a47-402d-9113-8faf9a0ee114"
 NonlinearSolveSpectralMethods = "26075421-4e9a-44e1-8bd1-420ed7ad02b2"
 OrdinaryDiffEqTsit5 = "b1df2697-797e-41e3-8120-5422d3b24e4a"

docs/pages.jl

@@ -49,7 +49,8 @@ pages = [
         "api/petsc.md",
         "api/siamfanlequations.md",
         "api/speedmapping.md",
-        "api/sundials.md"
+        "api/sundials.md",
+        "api/homotopycontinuation.md"
     ],
     "Sub-Packages" => Any[
         "api/SciMLJacobianOperators.md",

docs/src/api/homotopycontinuation.md

@@ -0,0 +1,18 @@
+# HomotopyContinuation.jl
+
+NonlinearSolve wraps the homotopy continuation algorithm implemented in
+HomotopyContinuation.jl. This solver is not included by default and needs
+to be installed separately:
+
+```julia
+using Pkg
+Pkg.add("NonlinearSolveHomotopyContinuation")
+using NonlinearSolveHomotopyContinuation, NonlinearSolve
+```
+
+# Solver API
+
+```@docs
+HomotopyContinuationJL
+SciMLBase.HomotopyContinuationFunction
+```

lib/NonlinearSolveHomotopyContinuation/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Aayush Sabharwal <[email protected]> and contributors
+
+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.

lib/NonlinearSolveHomotopyContinuation/Project.toml

@@ -0,0 +1,42 @@
+name = "NonlinearSolveHomotopyContinuation"
+uuid = "2ac3b008-d579-4536-8c91-a1a5998c2f8b"
+authors = ["Aayush Sabharwal <[email protected]> and contributors"]
+version = "0.1.0"
+
+[deps]
+ADTypes = "47edcb42-4c32-4615-8424-f2b9edc5f35b"
+CommonSolve = "38540f10-b2f7-11e9-35d8-d573e4eb0ff2"
+ConcreteStructs = "2569d6c7-a4a2-43d3-a901-331e8e4be471"
+DifferentiationInterface = "a0c0ee7d-e4b9-4e03-894e-1c5f64a51d63"
+DocStringExtensions = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
+HomotopyContinuation = "f213a82b-91d6-5c5d-acf7-10f1c761b327"
+LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
+NonlinearSolveBase = "be0214bd-f91f-a760-ac4e-3421ce2b2da0"
+SciMLBase = "0bca4576-84f4-4d90-8ffe-ffa030f20462"
+SymbolicIndexingInterface = "2efcf032-c050-4f8e-a9bb-153293bab1f5"
+TaylorSeries = "6aa5eb33-94cf-58f4-a9d0-e4b2c4fc25ea"
+
+[compat]
+ADTypes = "1.11.0"
+Aqua = "0.8"
+CommonSolve = "0.2.4"
+ConcreteStructs = "0.2.3"
+DifferentiationInterface = "0.6.27"
+DocStringExtensions = "0.9.3"
+HomotopyContinuation = "2.12.0"
+LinearAlgebra = "1.10"
+NonlinearSolve = "4"
+NonlinearSolveBase = "1.3.3"
+SciMLBase = "2.71"
+SymbolicIndexingInterface = "0.3.36"
+TaylorSeries = "0.18.2"
+Test = "1.10"
+julia = "1.10"
+
+[extras]
+Aqua = "4c88cf16-eb10-579e-8560-4a9242c79595"
+NonlinearSolve = "8913a72c-1f9b-4ce2-8d82-65094dcecaec"
+Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+
+[targets]
+test = ["Aqua", "Test", "NonlinearSolve"]

lib/NonlinearSolveHomotopyContinuation/src/NonlinearSolveHomotopyContinuation.jl

@@ -0,0 +1,65 @@
+module NonlinearSolveHomotopyContinuation
+
+using SciMLBase: AbstractNonlinearProblem
+using SciMLBase
+using NonlinearSolveBase
+using SymbolicIndexingInterface
+using LinearAlgebra
+using ADTypes
+using TaylorSeries
+using DocStringExtensions
+import CommonSolve
+import HomotopyContinuation as HC
+import DifferentiationInterface as DI
+
+using ConcreteStructs: @concrete
+
+export HomotopyContinuationJL, HomotopyNonlinearFunction
+
+"""
+    HomotopyContinuationJL{AllRoots}(; autodiff = true, kwargs...)
+    HomotopyContinuationJL(; kwargs...) = HomotopyContinuationJL{false}(; kwargs...)
+
+This algorithm is an interface to `HomotopyContinuation.jl`. It is only valid for
+fully determined polynomial systems. The `AllRoots` type parameter can be `true` or
+`false` and controls whether the solver will find all roots of the polynomial
+or a single root close to the initial guess provided to the `NonlinearProblem`.
+The polynomial function must allow complex numbers to be provided as the state.
+
+If `AllRoots` is `true`, the initial guess in the `NonlinearProblem` is ignored.
+The function must be traceable using HomotopyContinuation.jl's symbolic variables.
+Note that higher degree polynomials and systems with multiple unknowns can increase
+solve time significantly.
+
+If `AllRoots` is `false`, a single path is traced during the homotopy. The traced path
+depends on the initial guess provided to the `NonlinearProblem` being solved. This method
+does not require that the polynomial function is traceable via HomotopyContinuation.jl's
+symbolic variables.
+
+HomotopyContinuation.jl requires the jacobian of the system. In case a jacobian function
+is provided, it will be used. Otherwise, the `autodiff` keyword argument controls the
+autodiff method used to compute the jacobian. A value of `true` refers to
+`AutoForwardDiff` and `false` refers to `AutoFiniteDiff`. Alternate algorithms can be
+specified using ADTypes.jl.
+
+HomotopyContinuation.jl requires the taylor series of the polynomial system for the single
+root method. This is automatically computed using TaylorSeries.jl.
+"""
+@concrete struct HomotopyContinuationJL{AllRoots} <: NonlinearSolveBase.AbstractNonlinearSolveAlgorithm
+    autodiff
+    kwargs
+end
+
+function HomotopyContinuationJL{AllRoots}(; autodiff = true, kwargs...) where {AllRoots}
+    if autodiff isa Bool
+        autodiff = autodiff ? AutoForwardDiff() : AutoFiniteDiff()
+    end
+    HomotopyContinuationJL{AllRoots}(autodiff, kwargs)
+end
+
+HomotopyContinuationJL(; kwargs...) = HomotopyContinuationJL{false}(; kwargs...)
+
+include("interface_types.jl")
+include("solve.jl")
+
+end