Symbolic Arrays

.github/workflows/ci.yml

@@ -10,6 +10,7 @@ jobs:
   test:
     runs-on: ubuntu-latest
     strategy:
+      fail-fast: false
       matrix:
         group:
           - Core

Project.toml

@@ -1,10 +1,11 @@
 name = "Symbolics"
 uuid = "0c5d862f-8b57-4792-8d23-62f2024744c7"
 authors = ["Shashi Gowda <[email protected]>"]
-version = "0.1.33"
+version = "1.0.0"
 
 [deps]
 AbstractAlgebra = "c3fe647b-3220-5bb0-a1ea-a7954cac585d"
+ConstructionBase = "187b0558-2788-49d3-abe0-74a17ed4e7c9"
 DiffRules = "b552c78f-8df3-52c6-915a-8e097449b14b"
 Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
 DocStringExtensions = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
@@ -23,6 +24,7 @@ SciMLBase = "0bca4576-84f4-4d90-8ffe-ffa030f20462"
 Setfield = "efcf1570-3423-57d1-acb7-fd33fddbac46"
 SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
 SpecialFunctions = "276daf66-3868-5448-9aa4-cd146d93841b"
+StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
 SymbolicUtils = "d1185830-fcd6-423d-90d6-eec64667417b"
 TreeViews = "a2a6695c-b41b-5b7d-aed9-dbfdeacea5d7"
 
@@ -45,7 +47,8 @@ SafeTestsets = "0"
 SciMLBase = "1.8"
 Setfield = "0.7"
 SpecialFunctions = "0.7, 0.8, 0.9, 0.10, 1.0"
-SymbolicUtils = "0.10.1, 0.11"
+StaticArrays = "1.1"
+SymbolicUtils = "0.12"
 TreeViews = "0.3"
 julia = "1.5"
 

docs/src/manual/arrays.md

@@ -0,0 +1,130 @@
+# Symbolic arrays
+
+Symbolic array-valued expressions (symbolic arrays) are supported by Symbolics. Symbolic array expressions propagate useful metadata that depends on input arrays: array dimension, element type and shape.
+
+You can create a symbolic array variable with the following syntax:
+
+```julia
+@variables A[1:5, 1:3] b[1:3]
+```
+
+Here `A` is a symbolic matrix of size `(5, 3)` and `b` is a symbolic vector of length 3.
+
+```julia
+julia> size(A)
+(5, 3)
+
+julia> size(b)
+(3,)
+
+julia> ndims(A)
+2
+
+julia> ndims(b)
+1
+
+julia> eltype(A)
+Real
+
+julia> eltype(b)
+Real
+```
+
+## Array operations
+
+Operations on symbolic arrays return symbolic array expressions:
+
+```julia
+julia> c = A * b
+(A*b)[1:5]
+
+julia> size(c)
+(5,)
+
+julia> eltype(c)
+Real
+```
+
+Adjoints, matrix-matrix, and matrix-vector multiplications are supported. Dot product returns a scalar-valued expression:
+
+```julia
+julia> b'b
+adjoint(b)*b
+
+julia> size(b'b)
+()
+```
+
+Outer product returns a matrix:
+
+```julia
+julia> b * b'
+(b*adjoint(b))[1:3,1:3]
+
+julia> size(b*b')
+(3, 3)
+```
+
+### Broadcast, map and reduce
+
+
+```julia
+julia> A .* b'
+(broadcast(*, A, adjoint(b))[1:5,1:3]
+```
+
+```julia
+julia> map(asin, (A*b))
+(map(asin, A*b))[1:5]
+```
+
+``julia
+julia> sum(A)
+...
+
+julia> typeof(sum(A))
+Num # it's a scalar!
+
+julia> typeof(sum(A, dims=2))
+Arr{Real, 2} # it's a vector
+```
+
+### Indexing and delayed computation
+
+Indexing array expressions is fairly flexible in Symbolics. Let's go through all the possible ways to index arrays.
+
+#### Scalar indexing and scalarization
+
+```julia
+julia> AAt = A*A'
+(A*adjoint(A))[1:5,1:5]
+
+julia> AAt[2,3]
+(A*adjoint(A))[2,3]
+```
+
+Here we indexed for the element (2,3), but we got back a symbolic indexing expression. You may want to force the element to be computed in terms of the elements of A. This can be done, using `scalarize` function.
+
+```julia
+julia> Symbolics.scalarize(AAt[2,3])
+A[2, 1]*A[3, 1] + A[2, 2]*A[3, 2] + A[2, 3]*A[3, 3]
+
+julia> @syms i::Int j::Int
+(i, j)
+
+julia> Symbolics.scalarize(AAt[i,j])
+A[i, 1]*A[j, 1] + A[i, 2]*A[j, 2] + A[i, 3]*A[j, 3]
+```
+
+In general any scalar expression which is derived from array expressions can be scalarized.
+
+```julia
+julia> sum(A[:,1]) + sum(A[2,:])
+Symbolics._mapreduce(identity, +, A[Colon(), 1], Colon(), (:init => false,)) + Symbolics._mapreduce(identity, +, A[2, Colon()], Colon(), (:init => false,))
+
+julia> Symbolics.scalarize(sum(A[:,1]) + sum(A[2,:]))
+A[1, 1] + A[2, 2] + A[2, 3] + A[4, 1] + A[5, 1] + 2A[2, 1] + A[3, 1]
+
+```
+
+## How arrays work

docs/src/manual/expression_manipulation.md

@@ -23,7 +23,6 @@ Other additional manipulation functions are given below.
 ```@docs
 Symbolics.get_variables
 Symbolics.tosymbol
-Symbolics.makesym
 Symbolics.diff2term
 Symbolics.solve_for
 ```

src/Symbolics.jl

@@ -25,6 +25,10 @@ export simplify, substitute
 
 using SciMLBase, IfElse
 export Num
+using MacroTools
+import MacroTools: splitdef, combinedef, postwalk, striplines
+include("wrapper-types.jl")
+
 include("num.jl")
 
 export Equation, ConstrainedEquation
@@ -33,8 +37,9 @@ include("equations.jl")
 include("utils.jl")
 export degree
 
-using MacroTools
-import MacroTools: splitdef, combinedef, postwalk, striplines
+using ConstructionBase
+include("arrays.jl")
+
 export @register
 include("register.jl")
 
@@ -52,13 +57,15 @@ export Differential, expand_derivatives
 
 include("diff.jl")
 
+include("array-lib.jl")
+
 include("linear_algebra.jl")
 
 import Libdl
 include("build_function.jl")
 export build_function
 
-using Distributions
+import Distributions
 include("extra_functions.jl")
 
 using Latexify