Add SciPy wrapper documentation and fix doc build

Author: AdityaPandeyCN

docs/make.jl

@@ -1,11 +1,16 @@
 using Documenter, DocumenterCitations, DocumenterInterLinks
 import DiffEqBase
+import Pkg
+
+# Make sure the local solver sub-package is available inside the docs environment
+Pkg.develop(path = joinpath(@__DIR__, "..", "lib", "NonlinearSolveSciPy"))
 
 using Sundials
 using NonlinearSolveBase, SciMLBase, DiffEqBase
 using SimpleNonlinearSolve, BracketingNonlinearSolve
 using NonlinearSolveFirstOrder, NonlinearSolveQuasiNewton, NonlinearSolveSpectralMethods
 using NonlinearSolveHomotopyContinuation
+using NonlinearSolveSciPy
 using SciMLJacobianOperators
 using NonlinearSolve, SteadyStateDiffEq
 
@@ -37,6 +42,7 @@ makedocs(;
         SimpleNonlinearSolve, BracketingNonlinearSolve,
         NonlinearSolveFirstOrder, NonlinearSolveQuasiNewton, NonlinearSolveSpectralMethods,
         NonlinearSolveHomotopyContinuation,
+        NonlinearSolveSciPy,
         Sundials,
         SciMLJacobianOperators,
         NonlinearSolve, SteadyStateDiffEq

docs/pages.jl

@@ -48,6 +48,7 @@ pages = [
         "api/nlsolve.md",
         "api/nlsolvers.md",
         "api/petsc.md",
+        "api/scipy.md",
         "api/siamfanlequations.md",
         "api/speedmapping.md",
         "api/sundials.md",

docs/src/api/scipy.md

@@ -0,0 +1,89 @@
+# SciPy Wrappers
+
+NonlinearSolve provides thin wrappers around selected algorithms from the
+[SciPy](https://scipy.org/) Python library via
+[`PythonCall.jl`](https://github.com/cjdoris/PythonCall.jl).  They allow you to
+call the original `scipy.optimize` routines while keeping the standard
+`SciMLBase`‐style problem / solution interface.
+
+!!! note "Python dependency"
+    These algorithms require a working Python installation with the `scipy`
+    package available.  When the wrapper is first used, `PythonCall` will
+    automatically create a private Conda environment and install SciPy via
+    `CondaPkg`.  No manual setup is necessary on typical CI or end‐user
+    systems.
+
+## Algorithms
+
+| Julia type                     | SciPy function                     | Problem type |
+|--------------------------------|------------------------------------|--------------|
+| `SciPyLeastSquares` (default)  | `scipy.optimize.least_squares`     | nonlinear least-squares |
+| `SciPyLeastSquaresTRF`         | `scipy.optimize.least_squares` with `method="trf"` | nonlinear least-squares |
+| `SciPyRoot`                    | `scipy.optimize.root`              | vector root-finding |
+| `SciPyRootScalar`              | `scipy.optimize.root_scalar`       | scalar bracketing root |
+
+!!! warning "Single-process restriction"
+    SciPy itself is written in C/Fortran and **is not thread-safe across
+    multiple embedded Python interpreters**.  For that reason the
+    `NonlinearSolveSciPy` test suite runs single-process; you should avoid
+    launching many Julia processes that each call SciPy in parallel.
+
+## Basic usage
+
+```julia
+using NonlinearSolve, NonlinearSolveSciPy
+
+# --- nonlinear least-squares ---------------------------------------------
+
+xdata = 0:0.1:1
+ydata = 2 .* xdata .+ 1                           # exact line, no noise
+
+residuals(p, _) = ydata .- (p[1] .* xdata .+ p[2])
+prob = NonlinearLeastSquaresProblem(residuals, [1.0, 0.0])
+
+sol = solve(prob, SciPyLeastSquares())            # defaults to method="trf"
+```
+
+```julia
+# --- vector root-finding --------------------------------------------------
+
+f(u, p) = [2 - 2u[1]; u[1] - 4u[2]]
+prob_vec = NonlinearProblem(f, zeros(2))
+sol_vec  = solve(prob_vec, SciPyRoot())
+```
+
+```julia
+# --- scalar bracketing root ----------------------------------------------
+
+g(x, p) = x^2 - 2
+prob_scalar = IntervalNonlinearProblem(g, (1.0, 2.0))
+sol_scalar  = solve(prob_scalar, SciPyRootScalar())
+```
+
+All three calls return a standard `SciMLBase.NonlinearSolution` with the usual
+`u`, `resid`, `retcode`, etc.  If SciPy raises an error the wrapper translates
+it to an appropriate `ReturnCode` and propagates the original Python message
+through `solution.message`.
+
+## Keyword options
+
+The constructors forward most keywords verbatim to the underlying SciPy
+functions.  Refer to the [SciPy documentation](https://docs.scipy.org/doc/) for
+exhaustive lists.
+
+Examples:
+
+```julia
+# switch least-squares loss function
+solve(prob, SciPyLeastSquares(loss="soft_l1"))
+
+# change the scalar root solver method
+solve(prob_scalar, SciPyRootScalar(method="brentq"))
+```
+
+## Implementation notes
+
+The wrapper lives in the standalone sub-package `NonlinearSolveSciPy` rather
+than as a conditional extension.  This lets its code be developed and tested
+independently while still integrating smoothly with the main
+`NonlinearSolve.jl` umbrella package. 

docs/src/solvers/nonlinear_least_squares_solvers.md

@@ -84,7 +84,7 @@ Submethod choices for this algorithm include:
 A wrapper over `scipy.optimize.least_squares`.  Requires that the Python
 package `scipy` is available to PythonCall.
 
-  - [`SciPyLeastSquares()`](@ref) with convenience constructors
+  - [SciPyLeastSquares](../api/scipy.md#algorithms) (wrapper around `scipy.optimize.least_squares`) with convenience constructors
     `SciPyLeastSquaresTRF()`, `SciPyLeastSquaresDogbox()`, and
     `SciPyLeastSquaresLM()` for the common method choices.
 

docs/src/solvers/nonlinear_system_solvers.md

@@ -194,5 +194,5 @@ These wrappers let you use the algorithms from
 without leaving Julia.  SciPy is loaded lazily through PythonCall, so these
 methods are available whenever the `scipy` Python package can be imported.
 
-  - [`SciPyRoot()`](@ref): wrapper for `scipy.optimize.root` (vector problems)
-  - [`SciPyRootScalar()`](@ref): wrapper for `scipy.optimize.root_scalar` (scalar/bracketed problems)
+  - [SciPyRoot](../api/scipy.md#algorithms): wrapper for `scipy.optimize.root` (vector problems)
+  - [SciPyRootScalar](../api/scipy.md#algorithms): wrapper for `scipy.optimize.root_scalar` (scalar/bracketed problems)