more dev docs

Author: oameye

benchmark/benchmarks.jl

@@ -123,9 +123,7 @@ SUITE["fourier"]["trig_to_exp_product"] = @benchmarkable trig_to_exp($trig_expr_
 exp_sum = unwrap(exp(im * a) + exp(-im * a) + exp(im * (a + b)))
 SUITE["fourier"]["exp_to_trig_sum"] = @benchmarkable exp_to_trig($exp_sum)
 
-SUITE["fourier"]["add_div"] = @benchmarkable add_div(
-    $(a / (b + c) + b / (a + c))
-)
+SUITE["fourier"]["add_div"] = @benchmarkable add_div($(a / (b + c) + b / (a + c)))
 
 SUITE["fourier"]["trig_reduce_simple"] = @benchmarkable trig_reduce($trig_expr_sq)
 SUITE["fourier"]["trig_reduce_product"] = @benchmarkable trig_reduce($trig_expr_product)
@@ -203,13 +201,12 @@ SUITE["construction"]["DifferentialEquation_coupled"] = @benchmarkable Different
 
 # Rearrangement benchmark
 diff_eq_for_rearrange = DifferentialEquation(
-    [d(x, t, 2) + ω0^2 * x - k * y ~ F * cos(ω * t),
-     d(y, t, 2) + ω0^2 * y - k * x ~ 0],
+    [d(x, t, 2) + ω0^2 * x - k * y ~ F * cos(ω * t), d(y, t, 2) + ω0^2 * y - k * x ~ 0],
     [x, y],
 )
-SUITE["construction"]["rearrange_standard"] = @benchmarkable rearrange_standard!(
-    eom
-) setup = (eom = deepcopy($diff_eq_for_rearrange))
+SUITE["construction"]["rearrange_standard"] = @benchmarkable rearrange_standard!(eom) setup = (
+    eom = deepcopy($diff_eq_for_rearrange)
+)
 
 # ==========================================================================
 # Harmonic checks

docs/src/dev/symbolic_rewriting.md

@@ -100,3 +100,89 @@ QuestBase's small, targeted transformations.
 
 `Postwalk` is still used where it works well: `expand_all` and `add_div`, where the
 rewriter needs to visit all nodes anyway.
+
+## Function-by-Function Analysis
+
+Every function in `src/Symbolics/` was analyzed for rule-based rewriting potential.
+This section serves as a reference for future optimization attempts.
+
+### Candidates That Were Tried (manual is faster for now)
+
+| Function | `@rule` pattern | Slowdown | Notes |
+|---|---|---|---|
+| `expand_exp_power` | `exp(~x)^~n => exp(~x * ~n)` | 1.9x | Single pattern, `Postwalk` overhead dominates on small trees |
+| `simplify_exp_products` | `@acrule exp(~a) * exp(~b) => exp(~a + ~b)` | 6.8x | Needs `Fixpoint` + 3 chained rules; n-ary `findall` is faster |
+| `expand_fraction` | `(+(~~xs)) / ~c => sum(x/~c for x in ~~xs)` | 1.5x | Segment variable `~~xs` works but `_apply_termwise` is leaner |
+| `exp_to_trig` | Custom node function via `PassThrough` | 2500x (no-op) | `_apply_termwise` skips non-exp subtrees; `Postwalk` visits all |
+
+These could become faster than manual code if expression sizes grow significantly
+(100+ nodes) or if SymbolicUtils optimizes the rewriter overhead in the future.
+
+### Potentially Worth Revisiting
+
+| Function | Possible `@rule` | Why it might help |
+|---|---|---|
+| `trig_to_exp` (both `Num` and `BasicSymbolic` versions) | `@rule sin(~x)^~n => im^n * ((exp(-im*~x) - exp(im*~x))/2)^n` and similar for `cos` | Currently builds a substitution dict manually by iterating `get_all_terms` and filtering trigs. A `Postwalk` with two rules would be more declarative. Worth trying if `trig_to_exp` becomes a bottleneck. |
+| `simplify_complex` | `@rule` on `Const`-wrapped complex with zero imaginary | Currently uses `_apply_termwise` + `unwrap_const`. A single rule could handle the leaf case but traversal still needed. |
+| `is_trig` | `@capture` macro | Could use `@capture expr (sin(~x) or cos(~x))` instead of manual `ispow` + `operation` check. Cleaner but unlikely faster. |
+
+### Not Candidates (complex logic, not pattern-based)
+
+| Function | File | Why rules don't fit |
+|---|---|---|
+| `get_independent` | `Symbolics_utils.jl` | Requires semantic `is_function()` check per argument — each term needs a variable-dependence query, not a structural pattern match |
+| `exp_to_trig` (inner logic) | `fourier.jl` | Sign normalization uses alphabetic ordering of `sorted_arguments` and `_has_negative_coefficient` heuristics — too stateful for a rule |
+| `drop_powers` | `drop_powers.jl` | Uses algebraic ε-substitution strategy: replaces `var → ε*var`, expands, removes high powers of ε. Not tree-pattern-based at all |
+| `_fourier_term` | `fourier.jl` | Multi-step pipeline: `trig_reduce` → `get_independent` → complex simplification. Orchestration logic, not a rewrite |
+| `_get_all_terms` | `Symbolics_utils.jl` | Collects terms into a flat list — accumulation, not transformation |
+| `power_of` / `max_power` | `drop_powers.jl` | Query functions returning integers, not expression rewrites |
+| `count_derivatives` | `Symbolics_utils.jl` | Single-node field access (`op.order`), not a traversal |
+| `is_harmonic` | `Symbolics_utils.jl` | Predicate combining `get_all_terms`, `is_trig`, and `max_power` — orchestration |
+
+### Already Using `Postwalk` Effectively
+
+| Function | How | Why it works |
+|---|---|---|
+| `expand_all` | `Postwalk(expand_exp_power)` after `SymbolicUtils.expand` | Needs to visit all nodes; `expand_exp_power` is a simple leaf check |
+| `add_div` | `Postwalk(add_with_div)` | Uses SymbolicUtils-provided `add_with_div` rewriter |
+
+## SymbolicUtils API Quick Reference
+
+For QuestBase developers working with symbolic expressions.
+
+### Expression Type Predicates
+- `isadd(x)`, `ismul(x)`, `isdiv(x)`, `ispow(x)` — check structural type
+- `isterm(x)` — true for Pow and Term nodes (compound expressions)
+- `issym(x)` — true for leaf symbols
+- `iscall(x)` — true for ALL compound nodes (more general than `isterm`)
+- `is_literal_number(x)` — true for numeric literals
+- `is_derivative(x)` — true for derivative expressions
+
+### Expression Accessors
+- `arguments(x)` — child expressions (order depends on auto-simplification)
+- `sorted_arguments(x)` — children in deterministic order
+- `operation(x)` — head operation (`+`, `*`, `sin`, `exp`, etc.)
+- `unwrap_const(x)` — extract value from `Const`-wrapped numbers (SymbolicUtils v4)
+- `unwrap(x)` / `wrap(x)` — convert between `Num` and `BasicSymbolic`
+
+### Rule System
+- `@rule LHS => RHS` — basic pattern rule with `~x` (slot) and `~~xs` (segment)
+- `@acrule` — associative-commutative (tries permutations, expensive)
+- `@ordered_acrule` — cheaper than `@acrule` (combinations instead of permutations)
+- `@capture expr pattern` — one-off pattern match, injects bindings into scope
+- `~x::predicate` — slot with predicate filter (e.g., `~x::is_literal_number`)
+- `~!x` — default slot (defaults to 0 in `+`, 1 in `*`, 1 in `^` exponent)
+
+### Rewriter Combinators
+- `Chain((r1, r2, ...))` — apply in order (use **tuples** for `@generated` unrolling)
+- `RestartedChain((r1, r2, ...))` — restart from beginning on any match
+- `Fixpoint(rw)` — repeat until no change
+- `Postwalk(rw)` / `Prewalk(rw)` — bottom-up / top-down tree traversal
+- `PassThrough(rw)` — convert `nothing` return to identity (pass-through)
+- `If(cond, rw)` / `IfElse(cond, rw1, rw2)` — conditional dispatch
+
+### Performance Tips
+- `COMM_CHECKS_LIMIT` (default 10): commutative matching disabled for 10+ args
+- `Postwalk` uses copy-on-write: unchanged subtrees are not rebuilt
+- Hash-consing makes `===` checks O(1) for `Fixpoint` termination
+- Guard rule groups with `If(predicate, ...)` to skip irrelevant subtrees

src/QuestBase.jl

@@ -16,12 +16,12 @@ using SymbolicUtils:
     issym,
     add_with_div,
     is_literal_number,
-    unwrap_const
+    unwrap_const,
+    unwrap
 
 using Symbolics:
     Symbolics,
     Num,
-    unwrap,
     wrap,
     get_variables,
     Equation,