Skip to content

Commit a06a493

Browse files
docs: add more documentation
1 parent b07dba7 commit a06a493

File tree

6 files changed

+56
-37
lines changed

6 files changed

+56
-37
lines changed

docs/pages.jl

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,8 @@ pages = Any["index.md",
33
"manual/rewrite.md",
44
"manual/interface.md",
55
"manual/codegen.md",
6+
"manual/caching.md",
7+
"manual/recursive_utils.md",
68
],
79
"api.md",
810
"upgrade.md"

docs/src/api.md

Lines changed: 0 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -58,35 +58,3 @@ SymbolicUtils.simplify_fractions
5858
SymbolicUtils.quick_cancel
5959
SymbolicUtils.flatten_fractions
6060
```
61-
62-
## Code Generation
63-
64-
### Core Functions
65-
```@docs
66-
SymbolicUtils.Code.toexpr
67-
SymbolicUtils.Code.cse
68-
```
69-
70-
### Code Generation Types
71-
```@docs
72-
SymbolicUtils.Code.Assignment
73-
SymbolicUtils.Code.Let
74-
SymbolicUtils.Code.Func
75-
SymbolicUtils.Code.DestructuredArgs
76-
SymbolicUtils.Code.LiteralExpr
77-
SymbolicUtils.Code.ForLoop
78-
```
79-
80-
### Array Operations
81-
```@docs
82-
SymbolicUtils.Code.SetArray
83-
SymbolicUtils.Code.MakeArray
84-
SymbolicUtils.Code.MakeSparseArray
85-
SymbolicUtils.Code.MakeTuple
86-
```
87-
88-
### Parallelism
89-
```@docs
90-
SymbolicUtils.Code.SpawnFetch
91-
SymbolicUtils.Code.Multithreaded
92-
```

docs/src/manual/caching.md

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Caching recursive functions
2+
3+
Many functions benefit greatly from caching their results such that repeated calls with the same arguments
4+
can return cached values. As an example, `getindex` on symbolic arrays is a cached function since the operation can
5+
be expensive. SymbolicUtils.jl provides the `@cache` macro to allow easily caching such functions, with special
6+
benefits when the arguments are symbolic.
7+
8+
```@docs
9+
SymbolicUtils.@cache
10+
SymbolicUtils.associated_cache
11+
SymbolicUtils.get_limit
12+
SymbolicUtils.set_limit
13+
SymbolicUtils.get_retain_fractions
14+
SymbolicUtils.set_retain_fractions
15+
SymbolicUtils.toggle_caching
16+
SymbolicUtils.is_caching_enabled
17+
SymbolicUtils.clear_cache
18+
```

docs/src/manual/codegen.md

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,4 +35,18 @@ SymbolicUtils.Code.MakeArray
3535
SymbolicUtils.Code.MakeSparseArray
3636
SymbolicUtils.Code.MakeTuple
3737
SymbolicUtils.Code.LiteralExpr
38-
```
38+
SymbolicUtils.Code.ForLoop
39+
```
40+
41+
## Optimizations
42+
43+
### Common Subexpression Elimination (CSE)
44+
45+
SymbolicUtils can perform CSE on symbolic expressions, and codegen primitives composed of the above "Code Combinators".
46+
This ensures that common subexpressions in the expression are only computed once. Note that this assumes that all functions
47+
called within the expression are pure. SymbolicUtils can and will change the number and order of function calls.
48+
49+
```@docs
50+
SymbolicUtils.Code.cse
51+
SymbolicUtils.Code.cse_inside_expr
52+
```

docs/src/manual/recursive_utils.md

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Recursive utility functions
2+
3+
SymbolicUtils.jl provides several utility functions to perform common operations that
4+
require recursing over the expression tree.
5+
6+
```@docs
7+
SymbolicUtils.substitute
8+
SymbolicUtils.Substituter
9+
SymbolicUtils.default_substitute_filter
10+
SymbolicUtils.evaluate
11+
SymbolicUtils.query
12+
SymbolicUtils.search_variables
13+
SymbolicUtils.search_variables!
14+
SymbolicUtils.default_is_atomic
15+
SymbolicUtils.scalarize
16+
SymbolicUtils.scalarization_function
17+
```

docs/src/manual/variants.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -336,7 +336,7 @@ to Base-like behavior:
336336
doing so requires the function(s) passed to `map` and `mapreduce` instead of their types
337337
or shapes.
338338
- Since `ndims` information is not present in the type, `eachindex`, `iterate`, `size`,
339-
`axes`, `ndims`, `collect` are type-unstable. [`safe_eachindex`](@ref) is useful as
339+
`axes`, `ndims`, `collect` are type-unstable. [`stable_eachindex`](@ref) is useful as
340340
a type-stable iteration alternative.
341341
- `ifelse` requires that both the true and false cases have identical shape.
342342
- Symbolic arrays _only_ support cartesian indexing. For example, given `@syms x[1:3, 1:3]`
@@ -458,9 +458,9 @@ SymbolicUtils.promote_shape
458458
### Symbolic array utilities
459459

460460
```@docs
461-
SymbolicUtils.safe_eachindex
462-
SymbolicUtils.SafeIndices
463-
SymbolicUtils.SafeIndex
461+
SymbolicUtils.stable_eachindex
462+
SymbolicUtils.StableIndices
463+
SymbolicUtils.StableIndex
464464
BS
465465
```
466466

0 commit comments

Comments
 (0)