docs: add more documentation

Author: AayushSabharwal

docs/pages.jl

@@ -3,6 +3,8 @@ pages = Any["index.md",
                             "manual/rewrite.md",
                             "manual/interface.md",
                             "manual/codegen.md",
+                            "manual/caching.md",
+                            "manual/recursive_utils.md",
                             ],
             "api.md",
             "upgrade.md"

docs/src/api.md

@@ -58,35 +58,3 @@ SymbolicUtils.simplify_fractions
 SymbolicUtils.quick_cancel
 SymbolicUtils.flatten_fractions
 ```
-
-## Code Generation
-
-### Core Functions
-```@docs
-SymbolicUtils.Code.toexpr
-SymbolicUtils.Code.cse
-```
-
-### Code Generation Types
-```@docs
-SymbolicUtils.Code.Assignment
-SymbolicUtils.Code.Let
-SymbolicUtils.Code.Func
-SymbolicUtils.Code.DestructuredArgs
-SymbolicUtils.Code.LiteralExpr
-SymbolicUtils.Code.ForLoop
-```
-
-### Array Operations
-```@docs
-SymbolicUtils.Code.SetArray
-SymbolicUtils.Code.MakeArray
-SymbolicUtils.Code.MakeSparseArray
-SymbolicUtils.Code.MakeTuple
-```
-
-### Parallelism
-```@docs
-SymbolicUtils.Code.SpawnFetch
-SymbolicUtils.Code.Multithreaded
-```

docs/src/manual/caching.md

@@ -0,0 +1,18 @@
+# Caching recursive functions
+
+Many functions benefit greatly from caching their results such that repeated calls with the same arguments
+can return cached values. As an example, `getindex` on symbolic arrays is a cached function since the operation can
+be expensive. SymbolicUtils.jl provides the `@cache` macro to allow easily caching such functions, with special
+benefits when the arguments are symbolic.
+
+```@docs
+SymbolicUtils.@cache
+SymbolicUtils.associated_cache
+SymbolicUtils.get_limit
+SymbolicUtils.set_limit
+SymbolicUtils.get_retain_fractions
+SymbolicUtils.set_retain_fractions
+SymbolicUtils.toggle_caching
+SymbolicUtils.is_caching_enabled
+SymbolicUtils.clear_cache
+```

docs/src/manual/codegen.md

@@ -35,4 +35,18 @@ SymbolicUtils.Code.MakeArray
 SymbolicUtils.Code.MakeSparseArray
 SymbolicUtils.Code.MakeTuple
 SymbolicUtils.Code.LiteralExpr
-```
+SymbolicUtils.Code.ForLoop
+```
+
+## Optimizations
+
+### Common Subexpression Elimination (CSE)
+
+SymbolicUtils can perform CSE on symbolic expressions, and codegen primitives composed of the above "Code Combinators".
+This ensures that common subexpressions in the expression are only computed once. Note that this assumes that all functions
+called within the expression are pure. SymbolicUtils can and will change the number and order of function calls.
+
+```@docs
+SymbolicUtils.Code.cse
+SymbolicUtils.Code.cse_inside_expr
+```

docs/src/manual/recursive_utils.md

@@ -0,0 +1,17 @@
+# Recursive utility functions
+
+SymbolicUtils.jl provides several utility functions to perform common operations that
+require recursing over the expression tree.
+
+```@docs
+SymbolicUtils.substitute
+SymbolicUtils.Substituter
+SymbolicUtils.default_substitute_filter
+SymbolicUtils.evaluate
+SymbolicUtils.query
+SymbolicUtils.search_variables
+SymbolicUtils.search_variables!
+SymbolicUtils.default_is_atomic
+SymbolicUtils.scalarize
+SymbolicUtils.scalarization_function
+```

docs/src/manual/variants.md

@@ -336,7 +336,7 @@ to Base-like behavior:
   doing so requires the function(s) passed to `map` and `mapreduce` instead of their types
   or shapes.
 - Since `ndims` information is not present in the type, `eachindex`, `iterate`, `size`,
-  `axes`, `ndims`, `collect` are type-unstable. [`safe_eachindex`](@ref) is useful as
+  `axes`, `ndims`, `collect` are type-unstable. [`stable_eachindex`](@ref) is useful as
   a type-stable iteration alternative.
 - `ifelse` requires that both the true and false cases have identical shape.
 - Symbolic arrays _only_ support cartesian indexing. For example, given `@syms x[1:3, 1:3]`
@@ -458,9 +458,9 @@ SymbolicUtils.promote_shape
 ### Symbolic array utilities
 
 ```@docs
-SymbolicUtils.safe_eachindex
-SymbolicUtils.SafeIndices
-SymbolicUtils.SafeIndex
+SymbolicUtils.stable_eachindex
+SymbolicUtils.StableIndices
+SymbolicUtils.StableIndex
 BS
 ```