Merge pull request #266 from Suavesito-Olimpiada/suave/canon

Extend and document canonical form of `Symbolic{<:Number}`

Author: shashi

page/index.md

@@ -149,9 +149,24 @@ SymbolicUtils contains [a rule-based rewriting language](/rewrite/#rule-based_re
 
 ## Simplification
 
-By default `*` and `+` operations apply the most basic simplification upon construction of the expression.
+By default `+`, `*` and `^` operations apply the most basic simplification upon construction of the expression.
 
-Commutativity and associativity are assumed over `+` and `*` operations on `Symbolic{<:Number}`.
+The rules with which the canonical form of `Symbolic{<:Number}` terms are constructed are the next (where `x isa Symbolic` and `c isa Number`)
+
+ -  `0 + x`, `1 * x` and `x^1` always gives `x`
+ -  `0 * x` always gives `0` and `x ^ 0` gives `1`
+ -  `-x`, `1/x` and `x\1` get transformed into `(-1)*x`, `x^(-1)` and `x^(-1)`.
+ -  commutativity and associativity over `+` and `*` are assumed. Re-ordering of terms will be done under a [total order](https://github.com/JuliaSymbolics/SymbolicUtils.jl/blob/master/src/ordering.jl)
+ -  `x + ... + x` will be fused into `n*x` with type `Mul`
+ -  `x * ... * x` will be fused into `x^n` with type `Pow`
+ -  sum of `Add`'s are fused
+ -  product of `Mul`'s are fused
+ -  `c * (c₁x₁ + ... + cₙxₙ)` will be converted into `c*c₁*x₁ + ... + c*cₙ*xₙ`
+ -  `(x₁^c₁ * ... * xₙ^cₙ)^c` will be converted into `x₁^(c*c₁) * ... * xₙ^(c*cₙ)`
+ -  there are come other simplifications on construction that you can check [here](https://github.com/JuliaSymbolics/SymbolicUtils.jl/blob/master/src/methods.jl)
+
+
+Here is an example of this
 
 ```julia:simplify1
 2 * (w+w+α+β + sin(z)^2 + cos(z)^2 - 1)

src/types.jl

@@ -831,7 +831,7 @@ function (::Type{<:Pow{T}})(a, b; metadata=NO_METADATA) where {T}
     Pow{T, typeof(a), typeof(b), typeof(metadata)}(a,b,metadata)
 end
 function Pow(a, b; metadata=NO_METADATA)
-    Pow{promote_symtype(^, symtype(a), symtype(b))}(a, b, metadata=metadata)
+    Pow{promote_symtype(^, symtype(a), symtype(b))}(makepow(a, b)..., metadata=metadata)
 end
 symtype(a::Pow{X}) where {X} = X
 
@@ -847,6 +847,16 @@ Base.isequal(p::Pow, b::Pow) = isequal(p.base, b.base) && isequal(p.exp, b.exp)
 
 Base.show(io::IO, p::Pow) = show_term(io, p)
 
+function makepow(a, b)
+    base = a
+    exp = b
+    if a isa Pow
+        base = a.base
+        exp = a.exp * b
+    end
+    return (base, exp)
+end
+
 ^(a::SN, b) = Pow(a, b)
 
 ^(a::SN, b::SN) = Pow(a, b)

test/basics.jl

@@ -195,6 +195,7 @@ end
         @test x - x === 0
         @test isequal(-x, -1x)
         @test isequal(x^1, x)
+        @test isequal((x^-1)*inv(x^-1), 1)
     end
 end