Merge pull request #118 from JuliaSymbolics/s/generic

use interface on the matched expression instead of requiring it to be a `Term`

Author: shashi

docs/api.md

@@ -24,14 +24,14 @@ using SymbolicUtils # hide
 
 ## Interfacing
 
-{{doc to_symbolic to_symbolic fn}}
-
 {{doc istree istree fn}}
 
 {{doc operation operation fn}}
 
 {{doc arguments arguments fn}}
 
+{{doc similarterm similarterm fn}}
+
 ## Rewriters
 
 {{doc @rule @rule macro}}

docs/interface.md

@@ -17,13 +17,7 @@ This may sound like a roundabout way of doing it, but it can be really fast. In
 
 ## Defining the interface
 
-SymbolicUtils uses a function `to_symbolic` to convert aribtrarty types to it's own internal types. Our intention is for SymbolicUtils to be useful even for packages with their own custom symbolic types which
-differ from those offered by SymbolicUtils. To this end, SymbolicUtils provides an interface which if implemented, will enable automatic conversion of types to SymbolicUtils types.
-
-*  an `operation`, (i.e. function to apply)
-* `arguments` which the `operation` is applied to
-* `variable` types which are the atoms from which the expression tree is built 
-* optionally, a type which should `typeof(operation(arguments...))` should return if it were to be run.
+SymbolicUtils matchers can match any Julia object that implements an interface to traverse it as a tree.
 
 In particular, the following methods should be defined for an expression tree type `T` with symbol types `S` to  work
 with SymbolicUtils.jl
@@ -48,20 +42,16 @@ Returns the arguments (a `Vector`) for an expression tree.
 Called only if `istree(x)` is `true`. Part of the API required
 for `simplify` to work. Other required methods are `operation` and `istree`
 
-#### `to_symbolic(x::S)`
-Convert your variable type to a `SymbolicUtils.Sym`. Suppose you have
-```julia
-struct MySymbol
-   s::Symbol
-end
-```
-which could represent any type symbolically, then you would define 
-```julia
-SymbolicUtils.to_symbolic(s::MySymbol) = SymbolicUtils.Sym(s.s)
-```
+In addition, the methods for `Base.hash` and `Base.isequal` should also be implemented by the types for the purposes of substitution and equality matching respectively.
 
 ### Optional
 
+#### `similarterm(t::MyType, f, args)`
+
+Construct a new term with the operation `f` and arguments `args`, the term should be similar to `t` in type. if `t` is a `Term` object a new Term is created with the same symtype as `t`. If not, the result is computed as `f(args...)`. Defining this method for your term type will reduce any performance loss in performing `f(args...)` (esp. the splatting, and redundant type computation).
+
+The below two functions are internal to SymbolicUtils
+
 #### `symtype(x)`
 
 The supposed type of values in the domain of x. Tracing tools can use this type to
@@ -102,38 +92,24 @@ How can we use SymbolicUtils.jl to convert `ex` to `(-)(:x, 1)`? We simply imple
 `operation`, `arguments` and `to_symbolic` and we'll be off to the races:
 ```julia:piracy2
 using SymbolicUtils
-using SymbolicUtils: Sym, Term, istree, operation, arguments, to_symbolic
+using SymbolicUtils: istree, operation, arguments, similarterm
 
 SymbolicUtils.istree(ex::Expr) = ex.head == :call
 SymbolicUtils.operation(ex::Expr) = ex.args[1]
 SymbolicUtils.arguments(ex::Expr) = ex.args[2:end]
-SymbolicUtils.to_symbolic(s::Symbol) = Sym(s)
 
 @show simplify(ex)
 
 dump(simplify(ex))
 ```
-\out{piracy2}
-
-this thing returns a `Term{Any}`, but it's not hard to convert back to `Expr`:
-
-```julia:piracy3
-to_expr(t::Term) = Expr(:call, operation(t), to_expr.(arguments(t))...) 
-to_expr(x) = x
-
-@show expr = to_expr(simplify(ex))
-
-dump(expr)
-```
-\out{piracy3}
 
+There was no simplification, because by default SymbolicUtils assumes that the expressoins are of type Any and no particular rules apply. Let's change this by saying that the symbolic type (symtype) of an Expr or Symbol object is actually Real.
 
-Now suppose we actaully wanted all `Symbol`s to be treated as `Real` numbers. We can simply define
 ```julia:piracy4
-SymbolicUtils.symtype(s::Symbol) = Real
+SymbolicUtils.symtype(s::Expr) = Real
 
 dump(simplify(ex))
 ```
 \out{piracy4}
 
-and now all our analysis is able to figure out that the `Term`s are `Number`s.
+Now SymbolicUtils is able to apply the Number simplification rule to Expr.

src/SymbolicUtils.jl

@@ -1,6 +1,6 @@
 module SymbolicUtils
 
-export @syms, term, @fun, showraw
+export @syms, term, showraw
 
 # Sym, Term and other types
 include("types.jl")
@@ -21,7 +21,7 @@ include("rewriters.jl")
 using .Rewriters
 
 using Combinatorics: permutations, combinations
-export @rule, @acrule, @arule, RuleSet
+export @rule, @acrule, RuleSet
 
 # Rule type and @rule macro
 include("rule.jl")

src/abstractalgebra.jl

@@ -21,22 +21,22 @@ end
 function labels!(dicts, t)
     if t isa Integer
         return t
-    elseif t isa Term && (operation(t) == (*) || operation(t) == (+) || operation(t) == (-))
+    elseif istree(t) && (operation(t) == (*) || operation(t) == (+) || operation(t) == (-))
         tt = arguments(t)
-        return Term{symtype(t)}(operation(t), map(x->labels!(dicts, x), arguments(t)))
-    elseif t isa Term && operation(t) == (^) && length(arguments(t)) > 1 && isnonnegint(arguments(t)[2])
-        return Term{symtype(t)}(operation(t), map(x->labels!(dicts, x), arguments(t)))
+        return similarterm(t, operation(t), map(x->labels!(dicts, x), arguments(t)))
+    elseif istree(t) && operation(t) == (^) && length(arguments(t)) > 1 && isnonnegint(arguments(t)[2])
+        return similarterm(t, operation(t), map(x->labels!(dicts, x), arguments(t)))
     else
         sym2term, term2sym = dicts
         if haskey(term2sym, t)
             return term2sym[t]
         end
-        if t isa Term
+        if istree(t)
             tt = arguments(t)
             sym = Sym{symtype(t)}(gensym(nameof(operation(t))))
             dicts2 = _dicts(dicts[2])
-            sym2term[sym] = Term{symtype(t)}(operation(t),
-                                             map(x->to_mpoly(x, dicts)[1], arguments(t)))
+            sym2term[sym] = similarterm(t, operation(t),
+                                        map(x->to_mpoly(x, dicts)[1], arguments(t)))
         else
             sym = Sym{symtype(t)}(gensym("literal"))
             sym2term[sym] = t
@@ -92,16 +92,16 @@ let
     end
 end
 
-function to_term(x, dict)
+function to_term(reference, x, dict)
     syms = Dict(zip(nameof.(keys(dict)), keys(dict)))
     dict = copy(dict)
     for (k, v) in dict
-        dict[k] = _to_term(v, dict, syms)
+        dict[k] = _to_term(reference, v, dict, syms)
     end
-    _to_term(x, dict, syms)
+    _to_term(reference, x, dict, syms)
 end
 
-function _to_term(x::MPoly, dict, syms)
+function _to_term(reference, x::MPoly, dict, syms)
 
     function mul_coeffs(exps, ring)
         l = length(syms)
@@ -112,8 +112,7 @@ function _to_term(x::MPoly, dict, syms)
         elseif length(monics) == 0
             return 1
         else
-            T = reduce((x,y)->promote_symtype(*, x,y), symtype.(monics))
-            return Term{T}(*, monics)
+            return similarterm(reference, *, monics)
         end
     end
 
@@ -123,27 +122,29 @@ function _to_term(x::MPoly, dict, syms)
     elseif length(monoms) == 1
         t = !isone(x.coeffs[1]) ?  monoms[1] * x.coeffs[1] : monoms[1]
     else
-        T = reduce((x,y)->promote_symtype(+, x,y), symtype.(monoms))
-        t = Term{T}(+, map((x,y)->isone(y) ? x : y*x, monoms, x.coeffs[1:length(monoms)]))
+        t = similarterm(reference,
+                        +,
+                        map((x,y)->isone(y) ? x : y*x,
+                            monoms, x.coeffs[1:length(monoms)]))
     end
 
     substitute(t, dict, fold=false)
 end
 
-function _to_term(x, dict, vars)
-    if haskey(dict, x)
-        return dict[x]
+function _to_term(reference, x, dict, vars)
+    if istree(x)
+        t=similarterm(x, operation(x), _to_term.((reference,), arguments(x), (dict,), (vars,)))
     else
-        return x
+        if haskey(dict, x)
+            return dict[x]
+        else
+            return x
+        end
     end
 end
 
-function _to_term(x::Term, dict, vars)
-    t=Term{symtype(x)}(operation(x), _to_term.(arguments(x), (dict,), (vars,)))
-end
-
 <ₑ(a::MPoly, b::MPoly) = false
 
 function polynormalize(x)
-    to_term(to_mpoly(x)...)
+    to_term(x, to_mpoly(x)...)
 end

src/matchers.jl

@@ -7,13 +7,13 @@
 #
 function matcher(val::Any)
     function literal_matcher(next, data, bindings)
-        !isempty(data) && isequal(car(data), val) ? next(bindings, 1) : nothing
+        islist(data) && isequal(car(data), val) ? next(bindings, 1) : nothing
     end
 end
 
 function matcher(slot::Slot)
     function slot_matcher(next, data, bindings)
-        isempty(data) && return
+        !islist(data) && return
         val = get(bindings, slot.name, nothing)
         if val !== nothing
             if isequal(val, car(data))
@@ -29,10 +29,10 @@ end
 
 # returns n == offset, 0 if failed
 function trymatchexpr(data, value, n)
-    if isempty(value)
+    if !islist(value)
         return n
     elseif islist(value) && islist(data)
-        if isempty(data)
+        if !islist(data)
             # didn't fully match
             return nothing
         end
@@ -42,14 +42,14 @@ function trymatchexpr(data, value, n)
             value = cdr(value)
             data = cdr(data)
 
-            if isempty(value)
+            if !islist(value)
                 return n
-            elseif isempty(data)
+            elseif !islist(data)
                 return nothing
             end
         end
 
-        return isempty(value) ? n : nothing
+        return !islist(value) ? n : nothing
     elseif isequal(value, data)
         return n + 1
     end
@@ -87,12 +87,12 @@ function matcher(term::Term)
     matchers = (matcher(operation(term)), map(matcher, arguments(term))...,)
     function term_matcher(success, data, bindings)
 
-        isempty(data) && return nothing
-        !(car(data) isa Term) && return nothing
+        !islist(data) && return nothing
+        !(istree(car(data))) && return nothing
 
         function loop(term, bindings′, matchers′) # Get it to compile faster
-            if isempty(matchers′)
-                if  isempty(term)
+            if !islist(matchers′)
+                if  !islist(term)
                     return success(bindings′, 1)
                 end
                 return nothing

src/ordering.jl

@@ -9,33 +9,43 @@
 <ₑ(a::Number,   b::Symbolic) = true
 
 arglength(a) = length(arguments(a))
-function <ₑ(a::Sym, b::Term)
-    args = arguments(b)
-    if length(args) === 2
-        n1, n2 = !isnumber(args[1]) , !isnumber(args[2])
-        if n1 && n2
-            # both subterms are terms, so it's definitely firster
-            return true
-        elseif n1
-            return isequal(a, args[1]) || a <ₑ args[1]
-        elseif n2
-            return isequal(a, args[2]) || a <ₑ args[2]
+function <ₑ(a, b)
+    if !istree(a) && !istree(b)
+        T = typeof(a)
+        S = typeof(b)
+        T===S ? isless(a, b) : nameof(T) < nameof(S)
+    elseif istree(b) && !istree(a)
+        args = arguments(b)
+        if length(args) === 2
+            n1, n2 = !isnumber(args[1]) , !isnumber(args[2])
+            if n1 && n2
+                # both subterms are terms, so it's definitely firster
+                return true
+            elseif n1
+                return isequal(a, args[1]) || a <ₑ args[1]
+            elseif n2
+                return isequal(a, args[2]) || a <ₑ args[2]
+            else
+                # both arguments are not numbers
+                # This case when a <ₑ Term(^, [1,-1])
+                # so this term should go to the left.
+                return false
+            end
+        elseif length(args) === 1
+            # make sure a < sin(a) < b^2 < b
+            if isequal(a, args[1])
+                return true # e.g sin(a)*a should become a*sin(a)
+            else
+                return a<ₑargs[1]
+            end
         else
-            # both arguments are not numbers
-            # This case when a <ₑ Term(^, [1,-1])
-            # so this term should go to the left.
+            # variables to the right
             return false
         end
-    elseif length(args) === 1
-        # make sure a < sin(a) < b^2 < b
-        if isequal(a, args[1])
-            return true # e.g sin(a)*a should become a*sin(a)
-        else
-            return a<ₑargs[1]
-        end
+    elseif istree(a) && istree(b)
+        cmp_term_term(a,b)
     else
-        # variables to the right
-        return false
+        !(b <ₑ a)
     end
 end
 
@@ -61,9 +71,8 @@ function <ₑ(a::Symbol, b::Symbol)
 end
 
 <ₑ(a::Sym, b::Sym) = a.name < b.name
-<ₑ(a::T, b::S) where {T, S} = T===S ? isless(a, b) : nameof(T) < nameof(S)
 
-function <ₑ(a::Term, b::Term)
+function cmp_term_term(a, b)
     la = arglength(a)
     lb = arglength(b)
 

src/rewriters.jl

@@ -26,8 +26,7 @@ rewriters.
 
 """
 module Rewriters
-using SymbolicUtils: @timer, is_operation, istree, symtype, Term, operation, arguments,
-                     node_count
+using SymbolicUtils: @timer, is_operation, istree, operation, similarterm, arguments, node_count
 
 export Empty, IfElse, If, Chain, RestartedChain, Fixpoint, Postwalk, Prewalk, PassThrough
 
@@ -149,9 +148,7 @@ function (p::Walk{ord, C, false})(x) where {ord, C}
             x = p.rw(x)
         end
         if istree(x)
-            x = Term{symtype(x)}(operation(x),
-                                 map(t->PassThrough(p)(t),
-                                     arguments(x)))
+            x = similarterm(x, operation(x), map(PassThrough(p), arguments(x)))
         end
         return ord === :post ? p.rw(x) : x
     else
@@ -174,7 +171,7 @@ function (p::Walk{ord, C, true})(x) where {ord, C}
                 end
             end
             args = map((t,a) -> passthrough(t isa Task ? fetch(t) : t, a), _args, arguments(x))
-            t = Term{symtype(x)}(operation(x), args)
+            t = similarterm(x, operation(x), args)
         end
         return ord === :post ? p.rw(t) : t
     else