SimpleExpressions.jl

SimpleExpressions

A very lightweight means to create callable functions using expressions. This uses CallableExpressions as a backend. See also DynamicExpressions for a performant package with similar abilities.

The @symbolic macro, the lone export, can create a symbolic variable and optional symbolic parameter. When expressions are created with these variables, evaluation is deferred until the expression is called like a function. The expressions subtype Function so are intended to be useful with Julia's higher-order functions.

The expressions can be evaluated as a univariate function, u(x), a univariate function with parameter, u(x, p), or as a bivariate function, u(x,y) (with y being a parameter). These are all typical calling patterns when a function is passed to a numeric routine. For expressions without a symbolic value (as can happen through substitution) u() will evaluate the value.

To substitute in for either the variable or the parameter, leaving a symbolic expression, we have the calling patterns u(:,p), u(x,:) to substitute in for the parameter and variable respectively. The colon can also be nothing or missing.

When using positional arguments in a call, as above, all symbolic variables are treated identically, as are all symbolic parameters.

There are also methods for replace that allow more complicated substitutions. For replace, symbolic objects are returned. For replace, variables are distinct and identified by their symbol. Pairs may be specified to the call notation as a convenience for replace.

There are no performance claims, this package is all about convenience. Similar convenience is available in some form with SymPy, SymEngine, Symbolics, etc. As well, placeholder syntax is available in Underscores.jl, Chain.jl, DataPipes.jl etc., This package only has value in that it is very lightweight and, hopefully, intuitively simple.

Performance is good though, as CallableExpressions is performant. A benchmark case of finding a zero of a function runs without allocations in 1.099 μs with 0 allocations, with a symbolic expression in 1.231 μs with 0 allocations, SymEngine is two orders of magnitude slower (302.329 μs with 1731 allocations), and SymPy is about four orders slower (and with 80k allocations).

Extensions are provided for SpecialFunctions, AbstractTrees, Latexify, and RecipesBase.

Example

using SimpleExpressions
@symbolic x       # (x,)
u = sin(x) - (x - x^3/6)
u(0.5)  # 0.000258...
u = u - x^5/120
u(0.5) # -1.544...e-6

map(x^2, (1, 2))  # (1, 4)

using Plots
@symbolic x p     # (x, p)
u = x^5 - x - p   # (x ^ 5) + (-1 * x) + (-1 * p)
plot(u(:, 1), 0, 1.5)
plot!(u(:, 2))    # or plot(u.(:, 1:2), 0, 1.5)
eq = cos(x) ~ 2x
plot(eq, 0, pi/2) # like plot([eq...], 0, pi/2)

a ~ b

Create a SymbolicEquation.

The equation has a left and right-hand side, which can be found by tuple destructing; calling first and last; by index; or field access using .lhs and .rhs.

Symbolic equations can be evaluated, in which case the value of a-b is returned.

When a symbolic equation is passed as an argument to a symbolic expression, the pair a => b is passed to replace.

The diff function differentiates both sides.

The solve function tries to move x terms to the left-hand side; and non-x terms to the right-hand side.

eachmatch(pattern::AbstractSymbolic, expression::AbstractSymbolic)

Return iterator of all matches. See match for just the first match.

match(pattern::AbstractSymbolic, expression::AbstractSymbolic)

Match expression using a pattern with possible wildcards. Uses a partial implementation of Non-linear Associative-Commutative Many-to-One Pattern Matching with Sequence Variables by Manuel Krebber.

If there is no match: returns nothing.

If there is a match: returns a σ – with the property pattern(σ...) == expression is true (save possibly when star variables are used). An iterator for all matches is returned by eachmatch(pattern, expression).

Wildcards are just symbolic variables with a naming convention: use one trailing underscore to indicate a single match, two trailing underscores for a match of one or more (a plus variable), and three trailing underscores for a match on 0, 1, or more (a star variable).

Examples

julia> using SimpleExpressions

julia> SimpleExpressions.@symbolic_variables a b x_ x__ x___
(a, b, x_, x__, x___)

julia> pat, sub= x_*cos(x__), a*cos(2 + b)
(x_ * cos(x__), a * cos(2 + b))

julia> σ = match(pat, sub)
(x__ => 2 + b, x_ => a)

julia> pat(σ...) == sub
true

julia> pat, sub = x_ + x__ + x___,  a + b + a + b + a
(x_ + x__ + x___, a + b + a + b + a)

julia> Θ = eachmatch(pat, sub);

julia> length(collect(Θ))   # 37 matches
37

julia> σ = last(Θ)
(x_ => a, x__ => a, x___ => a + b + b)

julia> pat(σ...)
a + a + (a + b + b)

julia> σ = first(Θ)
(x__ => a + a + b + b, x_ => a) # x___ star variable has 0 elements in σ

julia> pat(σ..., x___ => 0)
a + (a + a + b + b) + 0

replace(ex::SymbolicExpression, args::Pair...)

Replace parts of the expression with something else.

Returns a symbolic object.

The replacement is specified using variable => value; these are processed left to right.

There are different methods depending on the type of key in the the key => value pairs specified:

• A symbolic variable is replaced by the right-hand side, like ex(val,:), though the latter is more performant
• A symbolic parameter is replaced by the right-hand side, like ex(:,val)
• A function is replaced by the corresponding specified function, as the head of the sub-expression
• A sub-expression is replaced by the new expression.
• A sub-expression containing a wildcard is replaced by the new expression, possibly containing a wildcard, in which the arguments are called.

The first two are straightforward.

julia> using SimpleExpressions

julia> @symbolic x p
(x, p)

julia> ex = cos(x) - x*p
cos(x) + (-1 * x * p)

julia> replace(ex, x => 2) == ex(2, :)
true

julia> replace(ex, p => 2) == ex(:, 2)
true

The third, is illustrated by:

julia> replace(sin(x + sin(x + sin(x))), sin => cos)
cos(x + cos(x + cos(x)))

The fourth is similar to the third, only an entire expression (not just its head) is replaced

julia> ex = cos(x)^2 + cos(x) + 1
(cos(x) ^ 2) + cos(x) + 1

julia> @symbolic u
(u,)

julia> replace(ex, cos(x) => u)
(u ^ 2) + u + 1

Replacements occur only if an entire node in the expression tree is matched:

julia> u = 1 + x
1 + x

julia> replace(u + exp(-u), u => x^2)
1 + x + exp(-1 * (x ^ 2))

(As this addition has three terms, 1+x is not a subtree in the expression tree.)

The fifth needs more explanation, as there can be wildcards in the expression.

Wildcards have a naming convention using trailing underscores. One matches one value; two matches one or more values; three match 0, 1, or more values. In addition, the special symbol ⋯ (entered with \cdots[tab] is wild.

julia> @symbolic x p; @symbolic x_
(x_,)

julia> replace(cos(pi + x^2), cos(pi + x_) => -cos(x_))
-1 * cos(x ^ 2)

julia> ex = log(sin(x)) + tan(sin(x^2))
log(sin(x)) + tan(sin(x ^ 2))

julia> replace(ex, sin(x_) => tan((x_) / 2))
log(tan(x / 2)) + tan(tan((x ^ 2) / 2))

julia> replace(ex, sin(x_) => x_)
log(x) + tan(x ^ 2)

julia> replace(x*p, (x_) * x => x_)
p

Picture

The AbstractTrees package can print this tree-representation of the expression ex = sin(x + x*log(x) + cos(x + p + x^2)):

julia> print_tree(ex;maxdepth=10)
sin
└─ +
   ├─ x
   ├─ *
   │  ├─ x
   │  └─ log
   │     └─ x
   └─ cos              <--
      └─ +             ...
         ├─ x          <--
         ├─ p          ...
         └─ ^          ...
            ├─ x       ...
            └─ 2       ...

The command wildcard expression cos(x + ...) looks at the part of the tree that has cos as a node, and the lone child is an expression with node + and child x. The ⋯ then matches p + x^2.

solve(eq::SymboliclEquation, x)

Very simple symbolic equations can be solved with the unexported solve method. This example shows a usage.

@symbolic w p; @symbolic h  # two variables, one parameter
import SimpleExpressions: solve, D
constraint = p ~ 2w + 2h
A = w * h

u = solve(constraint, h)
A = A(u) # use equation in replacement
v = solve(D(A, w) ~ 0, w)

coefficients(ex, x)

If expression or equation is a polynomial in x, return the coefficients. Otherwise return nothing.

Example

julia> @symbolic x p;

julia> eq = x*(x+2)*(x-p) ~ 2;

julia> a0, as... = cs = SimpleExpressions.coefficients(eq, x)
(a₀ = -2, a₁ = -2 * p, a₂ = 2 + (-1 * p), a₃ = 1)

julia> a0 + sum(aᵢ*x^i for (i,aᵢ) ∈ enumerate(Iterators.rest(cs,2)) if !iszero(aᵢ))
-2 + (-2 * p * (x ^ 1)) + ((2 + (-1 * p)) * (x ^ 2)) + (1 * (x ^ 3))

Not exported.

combine(ex)

Lightly simplify symbolic expressions.

Example

julia> using SimpleExpressions: @symbolic, combine

julia> @symbolic x
(x,)

julia> ex = 1 + x + 2x + 3x
1 + x + (2 * x) + (3 * x)

julia> combine(ex)
1 + (6 * x)

julia> ex = 1 + x^2 + 2x^2 + 3x*x + x^4/x
1 + (x ^ 2) + (2 * (x ^ 2)) + (3 * x * x) + ((x ^ 4) / x)

julia> combine(ex)
1 + (x ^ 3) + (6 * (x ^ 2)) 

Not exported.

map_matched(ex, is_match, f)

Traverse expression. If is_match is true, apply f to that part of expression tree and reassemble.

Basically CallableExpressions.expression_map_matched.

Not exported.

@symbolic x [p]

Create a symbolic variable and optional symbolic parameter.

Expressions and equations

Expressions created using these variables subclass Function so may be used where functions are expected.

The ~ infix operator can be used to create equations, which, by default, are treated as lhs - rhs when called as functions.

Extended help

Calling or substituting into expressions

To call a symbolic expression regular call notation with positional arguments are used. The first argument maps to any symbolic variable; the second – when given – to any symbolic parameter. It is an error to call an expression with a parameter using just a single argument; for that substitution is needed.

Example

using SimpleExpressions
@symbolic x p
u = x^5 - x - 1
u(2) # 29 call is u(x)

u.((0,1,2)) # (-1, -1, 29)

u = 2x + p
u(1)    # errors!
u(1, 2) # 2(1)+2 or 4

u = sum(x .* p)
u(2, [1,2]) # 6  call is u(x, p)

Calling with nothing, missing, or : in a slot substitutes in the specified value leaving a symbolic expression, possibly with no variable or parameter.

@symbolic x p
u = cos(x) - p*x
u(nothing, 2)  # cos(x) - 2 * x
u(:, 2)        #  cos(x) - 2 * x, alternate calling form
u(pi, nothing) # -1.0 - p * π
v = u(1,:)(:,2)    # (cos(1)-(2*1)),

The latter can be evaluated using a zero-argument call, e.g. v().

With substitution in this manner, any symbolic variable and any symbolic parameters will receive the same substituted value.

The replace generic for symbolic objects takes pairs of values and replaces the left one with the right one working from left to right, leaving a symbolic expression. The replace method treats symbolic variables and symbolic parameters with different symbols as unique.

A symbolic equation, defined through ~, may also be used to specify a left- and right-hand value.

The main use is as an easier-to-type replacement for anonymous functions, though with differences:

1 |> sin(x) |> x^2  # 0.708… from sin(1)^2
u = cos(x) - p*x
2 |> u(:, 3) # -6.4161…, a alternative to u(2,3)

map(x^2, (1, 2)) # (1,4)

Symbolic expressions an be used with other packages, to simplify some function calls at the expense of being non-idiomatic:

using Roots
@symbolic x p
find_zero(x^5 - x - 1, 1)       # 1.167…
find_zero(x^5 - x ~ p, 1; p=4)  # 1.401…

using ForwardDiff
Base.adjoint(𝑓::Function) = x -> ForwardDiff.derivative(𝑓, x)
u = x^5 - x - 1
find_zero((u,u'), 1, Roots.Newton()) # 1.167…

Or

using Plots
plot(x^5 - x - 1, 0, 1.5)

Or using both positions, so that we call as a bivariate function:

@symbolic x y
xs = ys = range(-5, 5, length=100)
contour(xs, ys, x^2 - y^2 + 2x*y)

Symbolic derivatives can be taken with respect to the symbolic value, symbolic parameters are treated as constant. We use diff as an interface

@symbolic x p
u = x^5 - p*x - 1
diff(u, x)           # (5 * (x ^ 4)) - p
u = u(:, 1)    # set parameter
a, b = 1, 2
find_zeros(diff(u,x) ~ (u(b)-u(a)) / (b-a), (a,b)) # [1.577…]

Idiosyncrasies

Using this is a convenience for simple cases. It is easy to run into idiosyncrasies.

Expressions are not functions in terms of scope

Unlike functions, expressions are defined with variables at the time of definition, not when called. For example, with a clean environment:

@symbolic x
u = m*x + b    # errors, `m` not defined
f(x) = m*x + b # ok
m, b = 1, 2
u = m*x + b    # defined using `m` amd `b` at time of assignment
u(3)           # 1 * 3 + 2
f(3)           # 1 * 3 + 2 values of `m` and `b` when called
m, b = 3, 4
u(3)           # still computing 1 * 3 + 2
f(3)           # computing 3 * 3 + 4, using values of `m` and `b` when called

Symbolic values are really singletons when calling by position

Though one can make different symbolic variables, the basic call notation by position treats them as the same:

@symbolic x
@symbolic y    # both x, y are `SymbolicVariable` type
u = x + 2y
u(3)           # 9 coming from 3 + 2*(3)

However, this is only to simplify the call interface. Using keyword arguments allows evaluation with different values:

u(;x=3, y=2)   # 7

Using replace, we have:

u(x=>3, y=>2)  # 3 + (2 * 2); evaluate with u(x=>3, y=>2)()

The underlying CallableExpressions object is directly called in the above manner; that package does not have the narrowed design of this package.

Containers

The variables may be used as placeholders for containers, e.g.

u = sum(xi*pi for (xi, pi) in zip(x,p))
u((1,2),(3,4))  # 11

Broadcasting as a function

Broadcasting a function call works as expected

@symbolic x
u = x^2
u.((1,2)) # (1, 4)

Symbolic expressions can also be constructed that will broadcast the call

u = x.^2 .+ sin.(p)
u((1,2),3)

u = @. x^2 + sin(p)
u((1,2),(3,4))

@symbolic_variables w x[1:3] y() z=>"𝑧" Ω::isinteger

Define multiple symbolic variables or symbolic functions. Guards are currently ignored.

Not exported.

julia> using SimpleExpressions: @symbolic_variables

julia> @symbolic_variables  w x[1:3] y() z=>"𝑧" Ω::isinteger
(w, SimpleExpressions.SymbolicVariable[x₁, x₂, x₃], y, 𝑧, Ω)

julia> x
3-element Vector{SimpleExpressions.SymbolicVariable}:
 x₁
 x₂
 x₃