Merge pull request #302 from JuliaSymbolics/ale/terminterface

TermInterface.jl integration

Author: shashi

Project.toml

@@ -1,7 +1,7 @@
 name = "SymbolicUtils"
 uuid = "d1185830-fcd6-423d-90d6-eec64667417b"
 authors = ["Shashi Gowda"]
-version = "0.14.0"
+version = "0.15.0"
 
 [deps]
 AbstractTrees = "1520ce14-60c1-5f80-bbc7-55ef81b5835c"
@@ -21,6 +21,7 @@ Setfield = "efcf1570-3423-57d1-acb7-fd33fddbac46"
 SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
 SpecialFunctions = "276daf66-3868-5448-9aa4-cd146d93841b"
 StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
+TermInterface = "8ea1fca8-c5ef-4a55-8b96-4e9afe9c9a3c"
 TimerOutputs = "a759f4b9-e2f1-59dc-863e-4aeb61b1ea8f"
 
 [compat]
@@ -39,6 +40,7 @@ NaNMath = "0.3"
 Setfield = "0.7"
 SpecialFunctions = "0.10, 1.0"
 StaticArrays = "0.12, 1.0"
+TermInterface = "0.1.7"
 TimerOutputs = "0.5"
 julia = "1.3"
 

page/interface.md

@@ -7,107 +7,23 @@ where appropriate -->
 
 # Interfacing with SymbolicUtils.jl
 
+<!-- TODO: document TermInterface.jl -->
+
 \tableofcontents <!-- you can use \toc as well -->
 
 This section is for Julia package developers who may want to use the `simplify` and rule rewriting system on their own expression types.
 
 ## Defining the interface
 
-SymbolicUtils matchers can match any Julia object that implements an interface to traverse it as a tree.
+SymbolicUtils matchers can match any Julia object that implements an interface to traverse it as a tree. The interface in question, is defined in the [TermInterface.jl](https://github.com/JuliaSymbolics/TermInterface.jl) package. Its purpose is to provide a shared interface between various symbolic programming Julia packages. 
 
-In particular, the following methods should be defined for an expression tree type `T` with symbol types `S` to  work
+In particular, you should define methods from TermInterface.jl for an expression tree type `T` with symbol types `S` to  work
 with SymbolicUtils.jl
 
-#### `istree(x::T)`
-
-Check if `x` represents an expression tree. If returns true,
-it will be assumed that `operation(::T)` and `arguments(::T)`
-methods are defined. Definining these three should allow use
-of `simplify` on custom types. Optionally `symtype(x)` can be
-defined to return the expected type of the symbolic expression.
-
-#### `operation(x::T)`
-
-Returns the operation (a function object) performed by an expression
-tree. Called only if `istree(::T)` is true. Part of the API required
-for `simplify` to work. Other required methods are `arguments` and `istree`
-
-#### `arguments(x::T)`
-
-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`
-
-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.
-
-#### `similarterm(t::MyType, f, args[, T])`
-
-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). T is the symtype of the output term. You can use `promote_symtype` to infer this type.
-
-The below two functions are internal to SymbolicUtils
-
-### Optional
-
-#### `symtype(x)`
-
-The supposed type of values in the domain of x. Tracing tools can use this type to
-pick the right method to run or analyse code.
-
-This defaults to `typeof(x)` if `x` is numeric, or `Any` otherwise.
-For the types defined in this package, namely `T<:Symbolic{S}` it is `S`.
+You can read the documentation of [TermInterface.jl](https://github.com/JuliaSymbolics/TermInterface.jl) on the [Github repository](https://github.com/JuliaSymbolics/TermInterface.jl).
 
-Define this for your symbolic types if you want `simplify` to apply rules
-specific to numbers (such as commutativity of multiplication). Or such
-rules that may be implemented in the future.
+## SymbolicUtils.jl only methods
 
 #### `promote_symtype(f, arg_symtypes...)`
 
 Returns the appropriate output type of applying `f` on arguments of type `arg_symtypes`.
-
-## Example
-
-Suppose you were feeling the temptations of type piracy and wanted to make a quick and dirty
-symbolic library built on top of Julia's `Expr` type, e.g.
-
-```julia:piracy1
-for f ∈ [:+, :-, :*, :/, :^] #Note, this is type piracy!
-    @eval begin
-        Base.$f(x::Union{Expr, Symbol}, y::Number) = Expr(:call, $f, x, y)
-        Base.$f(x::Number, y::Union{Expr, Symbol}) = Expr(:call, $f, x, y)
-        Base.$f(x::Union{Expr, Symbol}, y::Union{Expr, Symbol}) = (Expr(:call, $f, x, y))
-    end
-end
-
-
-ex = 1 + (:x - 2)
-```
-
-
-How can we use SymbolicUtils.jl to convert `ex` to `(-)(:x, 1)`? We simply implement `istree`,
-`operation`, `arguments` and we'll be able to do rule-based rewriting on `Expr`s:
-```julia:piracy2
-using SymbolicUtils
-
-SymbolicUtils.istree(ex::Expr) = ex.head == :call
-SymbolicUtils.operation(ex::Expr) = ex.args[1]
-SymbolicUtils.arguments(ex::Expr) = ex.args[2:end]
-
-@rule(~x => ~x - 1)(ex)
-```
-
-However, this is not enough to get SymbolicUtils to use its own algebraic simplification system on `Expr`s:
-```julia:piracy3
-simplify(ex)
-```
-
-The reason that the expression was not simplified is that the expression tree is untyped, so SymbolicUtils 
-doesn't know what rules to apply to the expression. To mimic the behaviour of most computer algebra 
-systems, the simplest thing to do would be to assume that all `Expr`s are of type `Number`:
-
-```julia:piracy4
-SymbolicUtils.symtype(s::Expr) = Number
-
-simplify(ex)
-```
-
-Now SymbolicUtils is able to apply the `Number` simplification rule to `Expr`.

src/SymbolicUtils.jl

@@ -6,6 +6,9 @@ module SymbolicUtils
 using DocStringExtensions
 export @syms, term, showraw, hasmetadata, getmetadata, setmetadata
 
+using TermInterface
+using TermInterface: node_count
+
 # Sym, Term,
 # Add, Mul and Pow
 using DataStructures
@@ -14,6 +17,7 @@ import Setfield: PropertyLens
 import Base: +, -, *, /, //, \, ^, ImmutableDict
 using ConstructionBase
 include("types.jl")
+export istree, operation, arguments, similarterm
 
 # Methods on symbolic objects
 using SpecialFunctions, NaNMath

src/api.jl

@@ -74,7 +74,7 @@ function substitute(expr, dict; fold=true)
         similarterm(expr,
                     op,
                     args,
-                    symtype(expr),
+                    symtype(expr);
                     metadata=metadata(expr))
     else
         expr

src/code.jl

@@ -118,6 +118,8 @@ end
 
 function_to_expr(::Sym, O, st) = get(st.symbolify, O, nothing)
 
+toexpr(O::Expr, st) = O
+
 function toexpr(O, st)
     !istree(O) && return O
     op = operation(O)

src/polyform.jl

@@ -28,14 +28,14 @@ PolyForm(sin((x+y)^2), recurse=true) #=> sin((x^2 + (2x)y + y^2))
 """
 struct PolyForm{T, M} <: Symbolic{T}
     p::MP.AbstractPolynomialLike
-    pvar2sym::Bijection{Any,Sym}   # @polyvar x --> @sym x  etc.
+    pvar2sym::Bijection{Any,Any}   # @polyvar x --> @sym x  etc.
     sym2term::Dict{Sym,Any}        # Symbol("sin-$hash(sin(x+y))") --> sin(x+y) => sin(PolyForm(...))
     metadata::M
 end
 
 function (::Type{PolyForm{T}})(p, d1, d2, m=nothing) where {T}
     p isa Number && return p
-    MP.isconstant(p) && return convert(Number, p)
+    p isa MP.AbstractPolynomialLike && MP.isconstant(p) && return convert(Number, p)
     PolyForm{T, typeof(m)}(p, d1, d2, m)
 end
 
@@ -51,7 +51,7 @@ clear_dicts() = (PVAR2SYM[] = WeakRef(nothing); SYM2TERM[] = WeakRef(nothing); n
 function get_pvar2sym()
     v = PVAR2SYM[].value
     if v === nothing
-        d = Bijection{Any,Sym}()
+        d = Bijection{Any,Any}()
         PVAR2SYM[] = WeakRef(d)
         return d
     else
@@ -93,7 +93,9 @@ end
 _isone(p::PolyForm) = isone(p.p)
 
 function polyize(x, pvar2sym, sym2term, vtype, pow, Fs, recurse)
-    if istree(x)
+    if x isa Number
+        return x
+    elseif istree(x)
         if !(symtype(x) <: Number)
             error("Cannot convert $x of symtype $(symtype(x)) into a PolyForm")
         end
@@ -139,9 +141,7 @@ function polyize(x, pvar2sym, sym2term, vtype, pow, Fs, recurse)
 
             return local_polyize(sym)
         end
-    elseif x isa Number
-        return x
-    elseif x isa Sym
+    elseif issym(x)
         if haskey(active_inv(pvar2sym), x)
             return pvar2sym(x)
         end
@@ -151,7 +151,7 @@ function polyize(x, pvar2sym, sym2term, vtype, pow, Fs, recurse)
     end
 end
 
-function PolyForm(x::Symbolic{<:Number},
+function PolyForm(x,
         pvar2sym=get_pvar2sym(),
         sym2term=get_sym2term(),
         vtype=DynamicPolynomials.PolyVar{true};
@@ -164,13 +164,11 @@ function PolyForm(x::Symbolic{<:Number},
     PolyForm{symtype(x)}(p, pvar2sym, sym2term, metadata)
 end
 
-PolyForm(x, args...;kw...) = x
-
-istree(x::PolyForm) = true
+TermInterface.istree(x::Type{PolyForm}) = true
 
-operation(x::PolyForm) = MP.nterms(x.p) == 1 ? (*) : (+)
+TermInterface.operation(x::PolyForm) = MP.nterms(x.p) == 1 ? (*) : (+)
 
-function arguments(x::PolyForm{T}) where {T}
+function TermInterface.arguments(x::PolyForm{T}) where {T}
 
     function is_var(v)
         MP.nterms(v) == 1 &&

src/rewriters.jl

@@ -29,7 +29,8 @@ rewriters.
 
 """
 module Rewriters
-using SymbolicUtils: @timer, is_operation, istree, operation, similarterm, arguments, node_count
+using SymbolicUtils: @timer
+using TermInterface: is_operation, istree, operation, similarterm, arguments, node_count
 
 export Empty, IfElse, If, Chain, RestartedChain, Fixpoint, Postwalk, Prewalk, PassThrough