Merge pull request #15 from s-celles/feat/commonsolve-integration

feat: integrate CommonSolve.jl (subsume PR #7)

Author: s-celles

CHANGELOG.md

@@ -62,6 +62,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `true` for free identifiers, ordinary symbolic expressions, and finite
   numbers; `false` for `inf`, `-inf`, and `1/0` (which GIAC normalizes to
   infinity). Implemented as `!to_julia(isinf(expr))::Bool`.
+- **CommonSolve.jl integration**: `Giac.Commands.solve` is now the same generic
+  function as `CommonSolve.solve` (`Giac.Commands.solve === CommonSolve.solve`),
+  so Giac's `solve` participates in the broader Julia "solve" verb ecosystem
+  alongside `DifferentialEquations.jl`, `NLsolve.jl`, `Symbolics.jl`, etc.
+  Dispatch is by argument type, so there is no conflict — `solve(::GiacExpr, …)`
+  routes to GIAC, `solve(::ODEProblem, …)` routes to DifferentialEquations,
+  and so on. `CommonSolve` is a tiny hard dependency (~50 LOC, compat `0.2`).
+  Note that `CommonSolve` also exports `init` and `solve!` as part of an
+  iterative-solver protocol; Giac is a symbolic CAS (non-iterative) so only
+  `solve` is extended — `init` and `solve!` are left untouched and remain
+  available for other packages to extend without conflict.
+  Contributed by [@jverzani](https://github.com/jverzani) in
+  [PR #7](https://github.com/s-celles/Giac.jl/pull/7).
 
 ### Changed
 

Project.toml

@@ -4,6 +4,7 @@ version = "0.12.0"
 authors = ["Sébastien Celles <s.celles@gmail.com>"]
 
 [deps]
+CommonSolve = "38540f10-b2f7-11e9-35d8-d573e4eb0ff2"
 CxxWrap = "1f15a43c-97ca-5a2a-ae31-89f07a497df4"
 GIAC_jll = "cf749d6c-42f5-550d-8800-4812740c2942"
 Libdl = "8f399da3-3557-5675-b5ff-fb832c97cbdb"
@@ -25,6 +26,7 @@ GiacTermInterfaceExt = "TermInterface"
 [compat]
 Aqua = "0.8"
 CSV = "0.10"
+CommonSolve = "0.2"
 CxxWrap = "0.16, 0.17"
 DataFrames = "1.6, 1.7, 1.8"
 Documenter = "1"

docs/src/mathematics/linear_algebra.md

@@ -260,6 +260,46 @@ solve([x + y ~ 3, x - y ~ 1], [x, y])
 # Returns the solution
 ```
 
+`Giac.Commands.solve` is the same generic function as
+[`CommonSolve.solve`](https://github.com/SciML/CommonSolve.jl), so it shares
+the "solve" verb with `DifferentialEquations.jl`, `NLsolve.jl`, `Symbolics.jl`,
+etc. Dispatch is by argument type, so there is no name conflict when both
+packages are loaded — `solve(eq::GiacExpr, var)` routes to Giac,
+`solve(prob::ODEProblem, …)` routes to DifferentialEquations, and so on.
+
+```julia
+using Giac.Commands: solve   # this is the same function as CommonSolve.solve
+
+solve(x^2 - 1 ~ 0, x)   # → list[-1, 1]
+# The `~` operator builds a symbolic equation; Giac dispatches the
+# CommonSolve.solve verb to its CAS solver.
+```
+
+Either side of the equation works:
+
+```julia
+solve(x^2 ~ 1, x)        # → list[-1, 1]
+solve(x^2 - 1, x)        # → list[-1, 1]   (Giac infers `= 0`)
+```
+
+!!! note "Why `solve` only, and not `init` / `solve!`"
+
+    `CommonSolve` defines three verbs — `init`, `solve`, and `solve!` — to
+    support the iterative-solver protocol used by `DifferentialEquations.jl`
+    and friends (`init(prob, …)` builds an integrator, `solve!` advances it,
+    `solve` is a one-shot wrapper that does both). Giac is a one-shot
+    symbolic solver — there is no integrator state to advance — so only
+    `solve` has a natural meaning here. `Giac` therefore extends
+    `CommonSolve.solve` and leaves `init` and `solve!` untouched, so
+    packages that *do* implement the iterative protocol can extend them
+    without any conflict.
+
+    Giac also has its own ODE solver, `Giac.Commands.desolve` (symbolic) and
+    `Giac.Commands.odesolve` (numerical) — see
+    [Differential Equations](differential_equations.md). Those are
+    intentionally separate verbs (not aliased to `solve`) because their
+    signatures don't fit the algebraic `solve(eq, var)` shape.
+
 ## Matrix Rank
 
 Compute the rank of a matrix using `invoke_cmd(:rank, ...)`:

src/Commands.jl

@@ -62,6 +62,8 @@ using ..Giac: GiacExpr, GiacMatrix, GiacInput, GiacError, giac_eval, with_giac_l
               HeldCmd
 import LinearAlgebra
 
+import CommonSolve: solve
+
 # ============================================================================
 # Core Command Invocation (invoke_cmd)
 # ============================================================================

test/runtests.jl

@@ -33,6 +33,9 @@ using LinearAlgebra
     # Commands submodule tests (009-commands-submodule)
     include("test_commands_submodule.jl")
 
+    # CommonSolve integration (PR #7)
+    include("test_commonsolve.jl")
+
 
     # Macro tests (011-giac-symbol-macro)
     include("test_macros.jl")

test/test_commonsolve.jl

@@ -0,0 +1,65 @@
+# Tests for CommonSolve.solve integration (PR #7 by @jverzani)
+# Verifies that Giac.Commands.solve and CommonSolve.solve refer to the same
+# generic function, so Giac plays well with the broader Julia "solve" verb
+# ecosystem (DifferentialEquations.jl, NLsolve.jl, Symbolics.jl, …).
+
+using CommonSolve
+
+@testset "CommonSolve integration" begin
+
+    @testset "solve identity: Giac.Commands.solve === CommonSolve.solve" begin
+        @test Giac.Commands.solve === CommonSolve.solve
+    end
+
+    @testset "solve dispatches Giac methods through CommonSolve" begin
+        @giac_var x
+
+        # Calling CommonSolve.solve on a GiacExpr equation routes to Giac's
+        # auto-generated solve method (added to CommonSolve.solve via Julia's
+        # extend-imported-function mechanism).
+        result = CommonSolve.solve(x^2 - 1, x)
+        @test result isa GiacExpr
+
+        result_str = string(result)
+        @test occursin("-1", result_str)
+        @test occursin("1", result_str)
+    end
+
+    @testset "solve via Giac.Commands and via CommonSolve produce equal results" begin
+        using Giac.Commands: solve as gsolve
+        @giac_var x y
+
+        # Single equation
+        @test string(gsolve(x^2 - 4, x))         == string(CommonSolve.solve(x^2 - 4, x))
+
+        # System of equations
+        @test string(gsolve([x + y ~ 3, x - y ~ 1], [x, y])) ==
+              string(CommonSolve.solve([x + y ~ 3, x - y ~ 1], [x, y]))
+    end
+
+    @testset "GiacMatrix path also extends CommonSolve.solve" begin
+        # The auto-generator emits a GiacMatrix overload for every command, so
+        # CommonSolve.solve(::GiacMatrix, …) should dispatch the same way.
+        @giac_var x
+        # `solve` on a matrix isn't a typical use case, but the method must
+        # exist for dispatch consistency.
+        @test hasmethod(CommonSolve.solve, Tuple{GiacMatrix, Vararg{Any}})
+    end
+
+    @testset "init / solve! are NOT extended by Giac" begin
+        # Giac is a symbolic CAS (non-iterative), so only CommonSolve.solve is
+        # integrated. CommonSolve.init and CommonSolve.solve! must remain
+        # un-shadowed by anything in Giac so packages implementing the
+        # iterative-solver protocol can extend them without conflict.
+        @giac_var x
+
+        # No Giac method on init or solve! for symbolic inputs.
+        @test !hasmethod(CommonSolve.init,   Tuple{GiacExpr, Vararg{Any}})
+        @test !hasmethod(CommonSolve.solve!, Tuple{GiacExpr, Vararg{Any}})
+
+        # And the bindings themselves are not aliased by Giac (they live in
+        # CommonSolve only).
+        @test parentmodule(CommonSolve.init)   === CommonSolve
+        @test parentmodule(CommonSolve.solve!) === CommonSolve
+    end
+end