WIP: Code matching and Expr generation

Project.toml

@@ -7,8 +7,11 @@ version = "0.7.7"
 AbstractAlgebra = "c3fe647b-3220-5bb0-a1ea-a7954cac585d"
 Combinatorics = "861a8166-3701-5b0c-9a16-15d98fcdc6aa"
 DataStructures = "864edb3b-99cc-5e75-8d2d-829cb0a9cfe8"
+LabelledArrays = "2ee39098-c373-598a-b85f-a56591580800"
 NaNMath = "77ba4419-2d1f-58cd-9bb1-8ffee604a2e3"
+SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
 SpecialFunctions = "276daf66-3868-5448-9aa4-cd146d93841b"
+StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
 TimerOutputs = "a759f4b9-e2f1-59dc-863e-4aeb61b1ea8f"
 
 [compat]

docs/codegen.md

@@ -0,0 +1,40 @@
+@def title = "SymbolicUtils.jl — Code generation"
+@def hasmath = false
+@def hascode = true
+
+# Generating executable code from Symbolics
+
+**Note: this feature is experimental and the API might change frequently**
+
+`toexpr(ex)` turns any expression (`ex`) into the equivalent `Expr` which is suitable for `eval`. The `SymbolicUtils.Code` module provides some combinators which provides the ability to construct more complex expressions than just function calls. These include:
+
+- Let blocks
+- Functions with arguments and keyword arguments
+  - Functions with arguments which are to be de-structured
+- Expressions that set array elements in-place
+- Expressions that create an array similar in type to a reference array (currently supports `Array`, `StaticArrays.SArray`, and `LabelledArrays.SLArray`)
+- Expressions that create sparse arrays
+
+## `toexpr(ex, [st,])`
+
+{{doc toexpr toexpr fn}}
+
+## Code Combinators
+
+These are all exported when you do `using SymbolicUtils.Code`
+
+{{doc Assignment Assignment type}}
+
+{{doc Let Let type}}
+
+{{doc Func Func type}}
+
+{{doc SetArray SetArray type}}
+
+{{doc MakeArray MakeArray type}}
+
+{{doc MakeSparseArray MakeSparseArray type}}
+
+{{doc MakeTuple MakeTuple type}}
+
+{{doc LiteralExpr LiteralExpr type}}

docs/index.md

@@ -258,6 +258,14 @@ The rules in the default simplify applies simple constant elemination, trigonome
 
 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`.
 
+## Code generation
+
+**Experimental feature**
+
+It is common to want to generate executable code from symbolic expressions and blocks of them. We are working on experimental support for turning Symbolic expressions into executable functions with specific focus on array input and output and performance which is critical to the Differential Equations ecosystem which is making heavy use of this package.
+
+See [Code generation](/codegen/) for more about this.
+
 ## Learn more
 
 If you have a package that you would like to utilize rule-based rewriting in, look at the suggestions in the [Interfacing](/interface/) section to find out how you can do that without any fundamental changes to your package. Look at the [API documentation](/api/) for docstrings about specific functions or macros.

src/SymbolicUtils.jl

@@ -47,4 +47,6 @@ include("simplify_rules.jl")
 export simplify, substitute
 include("api.jl")
 
+include("code.jl")
+
 end # module