Merge pull request #260 from TymonKilich/manual-smallfixes

Updates and adjustments for manual, especially rewriters section

Author: shashi

page/index.md

@@ -18,8 +18,8 @@ where appropriate -->
 **Features:**
 
 - Fast expressions
-- A [combinator library](/rewrite/#composing_rewriters) for making rewriters.
 - A [rule-based rewriting language](/rewrite/#rule-based_rewriting).
+- A [combinator library](/rewrite/#composing_rewriters) for making rewriters.
 - Type promotion:
   - Symbols (`Sym`s) carry type information. ([read more](#creating_symbolic_expressions))
   - Compound expressions composed of `Sym`s propagate type information. ([read more](#expression_interface))
@@ -65,17 +65,44 @@ Note however that they are not subtypes of these types!
 @show α isa Real
 ```
 
+As their types are different:
+
+```julia:symtype3
+@show typeof(w)
+@show typeof(α)
+```
+
 (see [this post](https://discourse.julialang.org/t/ann-symbolicutils-jl-groundwork-for-a-symbolic-ecosystem-in-julia/38455/13?u=shashi) for why they are all not just subtypes of `Number`)
 
 You can do basic arithmetic on symbols to get symbolic expressions:
 
 ```julia:expr
-expr1 = α*sin(w)^2 +  β*cos(z)^2
-expr2 = α*cos(z)^2 +  β*sin(w)^2
+expr1 = α*sin(w)^2 + β*cos(z)^2
+expr2 = α*cos(z)^2 + β*sin(w)^2
 
 expr1 + expr2
 ```
 
+SymbolicUtils automatically simplifies
+
+```julia:creating1
+2w + 3w - 3z + α
+```
+
+and reorders
+
+```julia:creating2
+(z + w)*(α + β)
+```
+
+expressions of type `Symbolic{<:Number}` (which includes `Sym{Real}`) when they are created. It also does constant elimination (including rational numbers)
+
+```julia:creating3
+5 + 2w - 3z + α - (β + 5//3) + 3w - 2 + 3//2 * β
+```
+
+It's worth remembering that the expression may be transformed with respect to the input when it's created.
+
 
 **Function-like symbols**
 
@@ -88,19 +115,18 @@ using SymbolicUtils
 f(z) + g(1, α) + sin(w)
 ```
 
+This does not work since `z` is a `Number`, not a `Real`.
 
 ```julia:sym3
 g(1, z)
 ```
 
-
-This does not work since `z` is a `Number`, not a `Real`.
+This works because `g` "returns" a `Real`.
 
 ```julia:sym4
 g(2//5, g(1, β))
 ```
 
-This works because `g` "returns" a `Real`.
 
 
 ## Expression interface
@@ -123,15 +149,21 @@ SymbolicUtils contains [a rule-based rewriting language](/rewrite/#rule-based_re
 
 ## Simplification
 
-By default `*` and `+` operations apply the most basic simplification upon construction.
+By default `*` and `+` operations apply the most basic simplification upon construction of the expression.
 
-The `simplify` function applies a built-in set of rules to rewrite expressions in order to simplify it.
+Commutativity and associativity are assumed over `+` and `*` operations on `Symbolic{<:Number}`.
 
 ```julia:simplify1
+2 * (w+w+α+β + sin(z)^2 + cos(z)^2 - 1)
+```
+
+The `simplify` function applies a built-in set of rules to rewrite expressions in order to simplify it.
+
+```julia:simplify2
 simplify(2 * (w+w+α+β + sin(z)^2 + cos(z)^2 - 1))
 ```
 
-The rules in the default simplify applies simple constant elemination, trigonometric identities.
+The rules in the default simplify applies simple constant elimination and trigonometric identities.
 
 If you read the previous section on the rules DSL, you should be able to read and understand the [rules](https://github.com/JuliaSymbolics/SymbolicUtils.jl/blob/master/src/simplify_rules.jl) that are used by `simplify`.
 

page/rewrite.md

@@ -2,9 +2,11 @@
 
 ## Rule-based rewriting
 
-Rewrite rules match and transform an expression. A rule is written using either the `@rule` macro or the `@acrule` macro.
+Rewrite rules match and transform an expression. A rule is written using either the `@rule` macro or the `@acrule` macro. It creates a callable `Rule` object.
 
-Here is a simple rewrite rule:
+### Basics of rule-based term rewriting in SymbolicUtils
+
+Here is a simple rewrite rule, that uses formula for the double angle of the sine function:
 
 ```julia:rewrite1
 using SymbolicUtils
@@ -13,37 +15,60 @@ using SymbolicUtils
 
 (w, z, α, β) # hide
 
-r1 = @rule ~x + ~x => 2 * (~x)
+r1 = @rule sin(2(~x)) => 2sin(~x)*cos(~x)
 
-r1(sin(1+z) + sin(1+z))
+r1(sin(2z))
 ```
 
 The `@rule` macro takes a pair of patterns -- the _matcher_ and the _consequent_ (`@rule matcher => consequent`). If an expression matches the matcher pattern, it is rewritten to the consequent pattern. `@rule` returns a callable object that applies the rule to an expression.
 
 `~x` in the example is what is a **slot variable** named `x`. In a matcher pattern, slot variables are placeholders that match exactly one expression. When used on the consequent side, they stand in for the matched expression. If a slot variable appears twice in a matcher pattern, all corresponding matches must be equal (as tested by `Base.isequal` function). Hence this rule says: if you see something added to itself, make it twice of that thing, and works as such.
 
-If you try to apply this rule to an expression where the two summands are not equal, it will return `nothing` -- this is the way a rule signifies failure to match.
+If you try to apply this rule to an expression with triple angle, it will return `nothing` -- this is the way a rule signifies failure to match.
 ```julia:rewrite2
-r1(sin(1+z) + sin(1+w)) === nothing
+r1(sin(3z)) === nothing
 ```
 
-If you want to match a variable number of subexpressions at once, you will need a **segment variable**. `~~xs` in the following example is a segment variable:
+Slot variable (matcher) is not necessary a single variable
 
 ```julia:rewrite3
+r1(sin(2*(w-z)))
+```
+
+but it must be a single expression
+
+```julia:rewrite4
+r1(sin(2*(w+z)*(α+β))) === nothing
+```
+
+Rules are of course not limited to single slot variable
+
+```julia:rewrite5
+r2 = @rule sin(~x + ~y) => sin(~x)*cos(~y) + cos(~x)*sin(~y);
+
+r2(sin(α+β))
+```
+
+If you want to match a variable number of subexpressions at once, you will need a **segment variable**. `~~xs` in the following example is a segment variable:
+
+```julia:rewrite6
 @syms x y z
 @rule(+(~~xs) => ~~xs)(x + y + z)
 ```
 
 `~~xs` is a vector of subexpressions matched. You can use it to construct something more useful:
 
-```julia:rewrite4
-r2 = @rule ~x * +(~~ys) => sum(map(y-> ~x * y, ~~ys));
+```julia:rewrite7
+r3 = @rule ~x * +(~~ys) => sum(map(y-> ~x * y, ~~ys));
 
-r2(2 * (w+w+α+β))
+r3(2 * (w+w+α+β))
 ```
 
-Notice that there is a subexpression `(2 * w) + (2 * w)` that could be simplified by the previous rule `r1`. Can we chain `r2` and `r1`?
+Notice that the expression was autosimplified before application of the rule.
 
+```julia:rewrite8
+2 * (w+w+α+β)
+```
 
 ### Predicates for matching
 
@@ -54,12 +79,14 @@ Similarly `~~x::g` is a way of attaching a predicate `g` to a segment variable.
 For example,
 
 ```julia:pred1
+@syms a b c d
 
-r = @rule ~x + ~~y::(ys->iseven(length(ys))) => "odd terms"
+r = @rule ~x + ~~y::(ys->iseven(length(ys))) => "odd terms";
 
-@show r(w + z + z + w)
-@show r(w + z + z)
-@show r(w + z)
+@show r(a + b + c + d)
+@show r(b + c + d)
+@show r(b + c + b)
+@show r(a + b)
 ```
 
 
@@ -68,13 +95,46 @@ r = @rule ~x + ~~y::(ys->iseven(length(ys))) => "odd terms"
 Given an expression `f(x, f(y, z, u), v, w)`, a `f` is said to be associative if the expression is equivalent to `f(x, y, z, u, v, w)` and commutative if the order of arguments does not matter.  SymbolicUtils has a special `@acrule` macro meant for rules on functions which are associate and commutative such as addition and multiplication of real and complex numbers.
 
 ```julia:acr
-@syms x y
+@syms x y z
 
-acr = @acrule((~y)^(~n) * ~y => (~y)^(~n+1))
+acr = @acrule((~a)^(~x) * (~a)^(~y) => (~a)^(~x + ~y))
 
-acr(x^2 * y * x)
+acr(x^y * x^z)
 ```
 
+although in case of `Number` it also works the same way with regular `@rule` since autosimplification orders and applies associativity and commutativity to the expression.
+
+### Example of applying the rules to simplify expression
+
+Consider expression `(cos(x) + sin(x))^2` that we would like simplify by applying some trigonometric rules. First, we need rule to expand square of `cos(x) + sin(x)`. First we try the simplest rule to expand square of the sum and try it on simple expression
+```julia:rewrite9
+using SymbolicUtils
+
+@syms x::Real y::Real
+
+sqexpand = @rule (~x + ~y)^2 => (~x)^2 + (~y)^2 + 2 * ~x * ~y
+
+sqexpand((cos(x) + sin(x))^2)
+```
+
+It works. This can be further simplified using Pythagorean identity and check it
+
+```julia:rewrite10
+pyid = @rule sin(~x)^2 + cos(~x)^2 => 1
+
+pyid(cos(x)^2 + sin(x)^2) === nothing
+```
+
+Why does it return `nothing`? If we look at the rule, we see that the order of `sin(x)` and `cos(x)` is different. Therefore, in order to work, the rule needs to be associative-commutative.
+
+```julia:rewrite11
+acpyid = @acrule sin(~x)^2 + cos(~x)^2 => 1
+
+acpyid(cos(x)^2 + sin(x)^2 + 2cos(x)*sin(x))
+```
+
+It has been some work. Fortunately rules may be [chained together](#chaining rewriters) into more sophisticated rewirters to avoid manual application of the rules.
+
 
 ## Composing rewriters
 
@@ -94,39 +154,63 @@ rewriters.
 - `IfElse(cond, rw1, rw2)` runs the `cond` function on the input, applies `rw1` if cond
    returns true, `rw2` if it retuns false
 - `If(cond, rw)` is the same as `IfElse(cond, rw, Empty())`
-- `Prewalk(rw; threaded=false, thread_cutoff=100)` returns a rewriter which does a pre-order
-   traversal of a given expression and applies the rewriter `rw`. `threaded=true` will
-   use multi threading for traversal. `thread_cutoff` is the minimum number of nodes
-   in a subtree which should be walked in a threaded spawn.
-- `Postwalk(rw; threaded=false, thread_cutoff=100)` similarly does post-order traversal.
+- `Prewalk(rw; threaded=false, thread_cutoff=100)` returns a rewriter which does a pre-order 
+   (*from top to bottom and from left to right*) traversal of a given expression and applies 
+   the rewriter `rw`. `threaded=true` will use multi threading for traversal. `thread_cutoff` 
+   is the minimum number of nodes in a subtree which should be walked in a threaded spawn.
+- `Postwalk(rw; threaded=false, thread_cutoff=100)` similarly does post-order 
+   (*from left to right and from bottom to top*) traversal.
 - `Fixpoint(rw)` returns a rewriter which applies `rw` repeatedly until there are no changes to be made.
 - `PassThrough(rw)` returns a rewriter which if `rw(x)` returns `nothing` will instead
    return `x` otherwise will return `rw(x)`.
 
+### Chaining rewriters
 
-Example using Postwalk, and Chain
+Several rules may be chained to give chain of rules. Chain is an array of rules which are subsequently applied to the expression.
 
-```julia:rewrite6
+To check that, we will combine rules from [previous example](#example of applying the rules to simplify expression) into a chain
 
+```julia:composing1
 using SymbolicUtils
 using SymbolicUtils.Rewriters
 
-r1 = @rule ~x + ~x => 2 * (~x)
-r2 = @rule ~x * +(~~ys) => sum(map(y-> ~x * y, ~~ys));
+sqexpand = @rule (~x + ~y)^2 => (~x)^2 + (~y)^2 + 2 * ~x * ~y
+acpyid = @acrule sin(~x)^2 + cos(~x)^2 => 1
 
-rset = Postwalk(Chain([r1, r2]))
-rset_result = rset(2 * (w+w+α+β))
+csa = Chain([sqexpand, acpyid])
 
-rset_result
+csa((cos(x) + sin(x))^2)
 ```
 
-It applied `r1`, but didn't get the opportunity to apply `r2`. So we need to apply the ruleset again on the result.
+Important feature of `Chain` is that it returns the expressiona instead of `nothing` if it doesn't change the expression
 
-```julia:rewrite7
-rset(rset_result)
+```julia:composing2
+Chain([@acrule sin(~x)^2 + cos(~x)^2 => 1])((cos(x) + sin(x))^2)
 ```
 
+its important to notice, that chain is ordered, so if rules are in different order it wouldn't work the same as in earlier example
+
+```julia:composing3
+cas = Chain([acpyid, sqexpand])
+
+cas((cos(x) + sin(x))^2)
+```
+since Pythagorean identity is applied before square expansion, so it is unable to match squares of sine and cosine.
+
+One way to circumvent the problem of order of applying rules in chain is to use `RestartedChain`
+
+```julia:composing4
+using SymbolicUtils.Rewriters: RestartedChain
+
+rcas = RestartedChain([acpyid, sqexpand])
+
+rcas((cos(x) + sin(x))^2)
+```
+
+It restarts the chain after each successful application of a rule, so after `sqexpand` is hit it (re)starts again and successfully applies `acpyid` to resulting expression.
+
 You can also use `Fixpoint` to apply the rules until there are no changes.
-```julia:rewrite8
-Fixpoint(rset)(2 * (w+w+α+β))
+
+```julia:composing5
+Fixpoint(cas)((cos(x) + sin(x))^2)
 ```

src/rule.jl

@@ -179,11 +179,11 @@ cos((1 + a))
 A rule with 2 segment variables
 
 ```julia
-julia> r = @rule ~x - ~y => ~x + (-(~y))
-~x - ~y => ~x + -(~y)
+julia> r = @rule sin(~x + ~y) => sin(~x)*cos(~y) + cos(~x)*sin(~y)
+sin(~x + ~y) => sin(~x) * cos(~y) + cos(~x) * sin(~y)
 
-julia> r(a-2b)
-(a + (-(2 * b)))
+julia> r(sin(a + b))
+cos(a)*sin(b) + sin(a)*cos(b)
 ```
 
 A rule that matches two of the same expressions: