Limitations and common pitfalls
MatchMaker matches structurally, over the canonicalized symbolic DAG that SymbolicUtils produces. Most surprises come from the fact that the tree you write is not always the tree that gets matched — SymbolicUtils may fold, reorder, or reshape a term before the matcher ever sees it. This page collects the cases users most often trip over.
Canonicalization happens before matching
Both pattern and subject pass through SymbolicUtils construction first, so they are canonicalized identically. Consequences:
x + ymay print and store as+(y, x)— argument order inside+and*is canonical, not written order.x + xis2x— an*(2, x)term, not a+term. A pattern likeslot(a) + slot(a)(nonlineara) matches it via the*coercion path, butslot(a) + slot(b)treats it as a two-argument product.exp(0),sin(0),x * 1etc. evaluate to Julia values when all arguments are concrete numbers — see the next section.
Folded literals never reach the matcher
exp(0) written in Julia is an ordinary Base.exp(::Int) call — it returns 1 before SymbolicUtils is involved. There is no exp(0) term left to match, so mmrule(exp(0) => 1) cannot observe it (#7).
The fix is to write the literal symbolically: exp(Const{SymReal}(0)) wraps 0 in a symbolic constant, so the exp call survives as a term and matches literally:
@syms xr = mmrule(exp(Const{SymReal}(0)) => 1)ws = RuleWorkspace(RuleSet(CompiledRule[r]))ws(exp(Const{SymReal}(0))) # 1 — the symbolic exp(0) term matchedws(exp(x)) # nothing — no literal `0` argumentThe same applies to subjects: rewriting exp(0) means building it as exp(Const{SymReal}(0)). Two related details:
mmrule(lhs => 1)treats a non-symbolic, non-callable RHS as a literal — it is wrapped inConstrather than called;- when you need "the literal
0inside a bigger pattern" rather than an all-literal LHS, aslotspecpredicate comparing bound terms withisequaldoes the job — but prefer the literalConstform, which is simpler and indexable.
-x and -x*y have different shapes
-slot(v) matches cos(-a) but not cos(-a*b) (#8). Unary minus on a symbol is a *(-1, a) term; -a*b canonicalizes to the flat product *(-1, a, b) — there is no unary - node wrapping a product. A pattern -slot(v) therefore only sees subjects whose shape is a negation of a single factor.
If you want "a product containing a -1 factor", match the flat form with a segment:
@syms a b v sm = compile_pattern(cos(-1 * slot(v) * segment(s)))matchall(m, cos(-a)) # v => a, s => 1 (empty product = identity)matchall(m, cos(-a * b)) # v => a, s => b and v => b, s => aNote that the segment binds the multiplicative identity 1 when it captures zero arguments.
Untyped vs. typed variables
slot(x) is untyped (symtype Number-agnostic); slot(x; type = Real) or a Sym{Real} variable is typed. Type filtering happens at binding time, but it also affects the reconstructed result: instantiated RHS terms derive their symtype from the bound argument, so an untyped slot still produces terms equal to subjects built from typed symbols — this is what makes cos(-α) - cos(α) cancel under fixpoint_rewrite (#6). If you nevertheless see structurally-identical terms failing isequal, check symtype on both sides — a term rebuilt with a different declared type is a different term.
optional under non-associative heads
Optional slots are supported under associative and associative-commutative heads (+, *, and user operations via set_operation_traits). Under free (plain Call) and commutative-only heads they are rejected at compile time — see the design notes for the rationale.
Matching is structural, not semantic
0 * x, x - x, sin(x)^2 + cos(x)^2 — the matcher sees the terms as written, not their mathematical value. Rules are the mechanism for simplification; matching itself does no algebraic reasoning. If you need value equality, put it in a slotspec predicate or a Constraint rather than in the tree shape.