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_sparsityFunction
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_sparsityFunction
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.islinearFunction
islinear(ex, u)

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

source
Symbolics.isaffineFunction
isaffine(ex, u)

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

source

ADTypes.jl interface

Symbolics.SymbolicsSparsityDetectorType
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:

Reference

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

source