Variable Substitution

Giac.jl provides a substitute function with a Symbolics.jl-compatible interface for variable substitution in symbolic expressions.

Basic Usage

Single Variable Substitution

using Giac

# Create symbolic variables
@giac_var x y

# Create an expression
expr = x^2 + 2*x + 1

# Substitute x = 3
result = substitute(expr, Dict(x => 3))
# Returns: 16 (which is 9 + 6 + 1)

# Substitute with symbolic value
result = substitute(expr, Dict(x => y))
# Returns: y^2 + 2*y + 1

Pair Syntax (Shorthand)

For single-variable substitutions, you can use the Pair syntax:

@giac_var x

substitute(x + 1, x => 5)  # Returns: 6

Multiple Variable Substitution

Substitute multiple variables simultaneously:

@giac_var x y z

expr = x*y + y*z + x*z

# Substitute multiple variables at once
result = substitute(expr, Dict(x => 1, y => 2, z => 3))
# Returns: 11 (which is 2 + 6 + 3)

Variable Swapping

The substitution is performed simultaneously, making variable swapping work correctly:

@giac_var a b

expr = a^2 + b

# Simultaneous substitution correctly swaps variables
result = substitute(expr, Dict(a => b, b => a))
# Returns: b^2 + a

With GIAC Functions

The substitute function works with any GIAC-supported functions:

@giac_var θ

expr = invoke_cmd(:sin, θ) + invoke_cmd(:cos, θ)

# Substitute θ = π/4
using Giac.Commands: simplify
result = substitute(expr, Dict(θ => giac_eval("pi/4"))) |> simplify
# Returns: sqrt(2)

Symbolic-to-Symbolic Substitution

Replace variables with complex expressions:

@giac_var x y

# x^2 with x = y + 1
result = substitute(x^2, Dict(x => y + 1))
# Returns: (y + 1)^2

Chained Substitution

Apply multiple substitutions in sequence:

@giac_var x y z

expr = x + y + z

step1 = substitute(expr, x => 1)
step2 = substitute(step1, y => 2)
final = substitute(step2, z => 3)
# Returns: 6

Comparison with Symbolics.jl

The API is designed to match Symbolics.jl's substitute function:

# Symbolics.jl style (works in Giac.jl)
substitute(expr, Dict(x => 2, y => 3))

# Single variable shorthand
substitute(expr, x => value)

Edge Cases

@giac_var x y

# Empty Dict returns original expression
substitute(x + 1, Dict{GiacExpr, Int}())  # Returns: x + 1

# Missing variable is ignored
substitute(x + 1, Dict(y => 5))  # Returns: x + 1 (y not in expr)

Matrix Substitution

The substitute function also works element-wise on GiacMatrix:

Single Variable in Matrix

@giac_var x

M = GiacMatrix([x x+1; 2*x x^2])

# Substitute x = 3 in all elements
result = substitute(M, x => 3)
# Returns: [[3, 4], [6, 9]]

Multiple Variables in Matrix

@giac_var x y

M = GiacMatrix([x+y x*y; x-y x/y])

# Substitute x = 6, y = 2 in all elements
result = substitute(M, Dict(x => 6, y => 2))
# Returns: [[8, 12], [4, 3]]

Partial Substitution

@giac_var x y

M = GiacMatrix([x y; x+y x*y])

# Only substitute x, leave y symbolic
result = substitute(M, Dict(x => 2))
# Returns: [[2, y], [2+y, 2*y]]

Symbolic Substitution in Matrix

@giac_var x y

M = GiacMatrix([x^2 x; 1 x+1])

# Replace x with y+1
result = substitute(M, Dict(x => y + 1))
# Returns: [[(y+1)^2, y+1], [1, y+2]]

API Reference

substitute(expr::GiacExpr, dict::AbstractDict{<:GiacExpr}) -> GiacExpr

@giac_var x y
expr = x^2 + y
substitute(expr, Dict(x => 2))        # Returns: 4 + y
substitute(expr, Dict(x => 2, y => 3)) # Returns: 7
substitute(expr, Dict(x => y, y => x)) # Swaps x and y: y^2 + x

substitute(expr::GiacExpr, pair::Pair{<:GiacExpr}) -> GiacExpr

@giac_var x
substitute(x + 1, x => 5)  # Returns: 6

substitute(m::GiacMatrix, dict::AbstractDict{<:GiacExpr}) -> GiacMatrix

@giac_var x y
M = GiacMatrix([x+1 2*x; y x*y])
substitute(M, Dict(x => 2))        # Returns matrix with x=2 substituted
substitute(M, Dict(x => 2, y => 3)) # Returns fully numeric matrix

substitute(m::GiacMatrix, pair::Pair{<:GiacExpr}) -> GiacMatrix

@giac_var x
M = GiacMatrix([x 2*x; x+1 x^2])
substitute(M, x => 3)  # Returns: [[3, 6], [4, 9]]