Structure and Sparsity Detection

Using the tracing system provided by Symbolics.jl expressions, Symbolics.jl can automatically detect the sparsity patterns of Julia functions efficiently. This functionality is described in more detail in the paper:

@article{gowda2019sparsity,
  title={Sparsity Programming: Automated Sparsity-Aware Optimizations in Differentiable Programming},
  author={Gowda, Shashi and Ma, Yingbo and Churavy, Valentin and Edelman, Alan and Rackauckas, Christopher},
  year={2019}
}

Please cite this work if the functionality is used.

Sparsity Detection

Symbolics.jacobian_sparsity — Function

jacobian_sparsity(
    exprs::AbstractArray,
    vars::AbstractArray
) -> SparseArrays.SparseMatrixCSC{Bool, Int64}

Return the sparsity pattern of the Jacobian of an array of expressions with respect to an array of variable expressions.

Arguments

exprs: an array of symbolic expressions.
vars: an array of symbolic variables.

Examples

julia> using Symbolics

julia> vars = @variables x₁ x₂;

julia> exprs = [2x₁, 3x₂, 4x₁ * x₂];

julia> Symbolics.jacobian_sparsity(exprs, vars)
3×2 SparseArrays.SparseMatrixCSC{Bool, Int64} with 4 stored entries:
 1  ⋅
 ⋅  1
 1  1

source

jacobian_sparsity(
    f!::Function,
    output::AbstractArray,
    input::AbstractArray,
    args...;
    kwargs...
) -> SparseArrays.SparseMatrixCSC{Bool, Int64}

Return the sparsity pattern of the Jacobian of the mutating function f!.

Arguments

f!: an in-place function f!(output, input, args...; kwargs...).
output: output array.
input: input array.

The eltype of output and input can be either symbolic or primitive.

Examples

julia> using Symbolics

julia> f!(y, x) = y .= [x[2], 2x[1], 3x[1] * x[2]];

julia> output = Vector{Float64}(undef, 3);

julia> input = Vector{Float64}(undef, 2);

julia> Symbolics.jacobian_sparsity(f!, output, input)
3×2 SparseArrays.SparseMatrixCSC{Bool, Int64} with 4 stored entries:
 ⋅  1
 1  ⋅
 1  1

source

Symbolics.hessian_sparsity — Function

hessian_sparsity(
    expr,
    vars::AbstractVector;
    full
) -> Union{SparseArrays.SparseMatrixCSC{Bool, Int64}, SparseArrays.SparseMatrixCSC{Int64, Int64}}

Return the sparsity pattern of the Hessian of an expression with respect to an array of variable expressions.

Arguments

expr: a symbolic expression.
vars: a vector of symbolic variables.

Examples

julia> using Symbolics

julia> vars = @variables x₁ x₂;

julia> expr = 3x₁^2 + 4x₁ * x₂;

julia> Symbolics.hessian_sparsity(expr, vars)
2×2 SparseArrays.SparseMatrixCSC{Bool, Int64} with 3 stored entries:
 1  1
 1  ⋅

source

hessian_sparsity(
    f::Function,
    input::AbstractVector,
    args...;
    full,
    kwargs...
) -> Union{SparseArrays.SparseMatrixCSC{Bool, Int64}, SparseArrays.SparseMatrixCSC{Int64, Int64}}

Return the sparsity pattern of the Hessian of the given function f.

Arguments

f: an out-of-place function f(input, args...; kwargs...).
input: a vector of input values whose eltype can be either symbolic or primitive.

Examples

julia> using Symbolics

julia> f(x) = 4x[1] * x[2] - 5x[2]^2;

julia> input = Vector{Float64}(undef, 2);

julia> Symbolics.hessian_sparsity(f, input)
2×2 SparseArrays.SparseMatrixCSC{Bool, Int64} with 3 stored entries:
 ⋅  1
 1  1

source

Structure Detection

Symbolics.islinear — Function

islinear(ex, u)

Check if an expression is linear with respect to a list of variable expressions.

source

Symbolics.isaffine — Function

isaffine(ex, u)

Check if an expression is affine with respect to a list of variable expressions.

source

ADTypes.jl interface

Symbolics.SymbolicsSparsityDetector — Type

SymbolicsSparsityDetector <: ADTypes.AbstractSparsityDetector

Sparsity detection algorithm based on the Symbolics.jl tracing system.

This type makes Symbolics.jl compatible with the ADTypes.jl sparsity detection framework. The following functions are implemented:

ADTypes.jacobian_sparsity based on Symbolics.jacobian_sparsity
ADTypes.hessian_sparsity based on Symbolics.hessian_sparsity

Reference

Sparsity Programming: Automated Sparsity-Aware Optimizations in Differentiable Programming, Gowda et al. (2019)

source