SymbolicUtils.jl

SymbolicUtils uses FnType{A, R, T} to represent symbolic functions, where A is a tuple of argument symtypes, R is the return symtype, and T is the function's supertype (or Nothing).

Symbolic Functions

Use the @syms macro with explicit argument types to create a symbolic function:

@syms f(::T1, ::T2)::R

This creates f with symtype FnType{Tuple{T1, T2}, R, Nothing}.

Dependent Variables

If you omit argument types, the variable is treated as a dependent variable with unspecified independent variables:

@syms f(..)::R

In the expression f(x), f is considered a dependent variable that depends on x rather than a symbolic function call.

Use SymbolicUtils.is_function_symbolic, SymbolicUtils.is_function_symtype, and SymbolicUtils.is_called_function_symbolic to distinguish between these cases.

# A symbolic function
@syms f(::Real)::Real

# A dependent variable
@syms g(..)::Real

# Usage
f(x) # Treated as a symbolic function call
g(x) # Treated as a dependent variable

SymbolicUtils uses an Algebraic Data Type (ADT) named BasicSymbolicImpl (aliased as BSImpl) to represent symbolic trees. The primary type is BasicSymbolic.

Important: Immutability BasicSymbolic objects are IMMUTABLE. Although ismutabletype(BasicSymbolic) returns true, any mutation (including internal field mutation like AddMul.dict) is undefined behavior and will cause hard-to-debug issues. Arrays returned by TermInterface.arguments and TermInterface.sorted_arguments are read-only.

The vartype Tag In v4, the type parameter in BasicSymbolic{T} represents the vartype, which determines the assumptions made about the symbolic algebra. An expression must be pure in its vartype; operations do not support mixing different vartypes.

Available vartype values:

• SymReal: The default behavior.
• SafeReal: Identical to SymReal, but common factors in the numerator and denominator of a division are not cancelled.
• TreeReal: Assumes nothing about the algebra and always uses the Term variant to represent an expression.

using SymbolicUtils
# BasicSymbolic is the core type
# vartype (SymReal, SafeReal, TreeReal) determines algebraic assumptions

For associative-commutative addition and multiplication, SymbolicUtils.jl uses a specialized AddMul variant to improve efficiency. This is distinguished by the AddMulVariant enum: AddMulVariant.ADD or AddMulVariant.MUL.

Multiplication (Mul)

Represented as coeff * (term1^exp1 * term2^exp2 * ...).

• coeff: A non-symbolic constant.
• dict: A map from terms to their exponents.
• Best Practice: Use the Mul{T}(coeff, dict; type, shape, metadata) constructor. It validates constraints (e.g., coeff must not be zero, dict must not be empty) and returns the appropriate form.

Addition (Add)

Represented as coeff + (term1*c1 + term2*c2 + ...).

• coeff: A non-symbolic constant. 0- dict: A map from terms to their constant non-symbolic coefficients.
• Best Practice: Use the Add{T}(coeff, dict; type, shape, metadata) constructor. It validates constraints and returns the appropriate form.

Warning: Using the raw BSImpl.AddMul{T} constructor is faster but skips validation and can lead to undefined behavior if constraints are violated.

# Preferred way to create multiplication
m = Mul{T}(2, Dict(x => 2, y => 1); type=T, shape=S, metadata=M)

# Preferred way to create addition
a = Add{T}(1, Dict(x => 2, y => 3); type=T, shape=S, metadata=M)

SymbolicUtils implements an array algebra designed to mimic Base Julia Array behavior.

Key Behaviors:

• Scalar reduction: Operations like adjoint(::Vector) * (::Vector) return a symbolic scalar rather than a one-element vector.
• Indexing: Symbolic arrays only support Cartesian indexing. Valid indices include Int, Colon, AbstractRange{Int}, symbolic expressions with integer symtype, or a single CartesianIndex of appropriate dimension. Accessing x[4] on a 2D array is invalid; use x[1, 2] instead.

Important Limitations:

• map and mapreduce: All input arrays must have the same shape. promote_symtype and promote_shape are not implemented for these because they require the function itself rather than just its type/shape.
• Type Instability: Functions like eachindex, iterate, size, axes, ndims, and collect are type-unstable because ndims is not present in the type. Use SymbolicUtils.stable_eachindex for type-stable iteration.
• ifelse: Both the true and false branches must have identical shapes.
• Array of Symbolics: To perform symbolic array operations on an array of symbolics, at least one argument must be a symbolic value (not just an array of symbolics) to trigger SymbolicUtils dispatch instead of Base dispatch.

SymbolicUtils v4 treats arrays as first-class citizens by storing a shape. You can query this using SymbolicUtils.shape(x). There are three categories of shapes:

1. Known Shape: For variables defined with specific ranges (e.g., @syms x[1:2]), shape(x) returns a vector of UnitRange{Int} (similar to Base.axes). Scalar variables return an empty vector.
2. Known ndims: For variables where the exact size is unknown but the number of dimensions is specified (e.g., @syms x::Vector{Number}), shape(x) returns a SymbolicUtils.Unknown(ndims) object. Array operations perform best-effort validation and shape calculation.
3. Unknown ndims: For variables where only the array nature is known (e.g., @syms x::Array{Number}), shape(x) returns SymbolicUtils.Unknown(-1). This disables most shape checking for array operations.

using SymbolicUtils

# 1. Known shape
@syms x[1:2] y[-3:6, 4:7] z
shape(x) # Returns vector of UnitRanges

# 2. Known ndims
@syms a::Vector{Number} b::Matrix{Number} c::Array{Number, 3}
shape(a) # Returns SymbolicUtils.Unknown(1)

# 3. Unknown ndims
@syms d::Array{Number}
shape(d) # Returns SymbolicUtils.Unknown(-1)