API Reference

@syms <lhs_expr>[::T1] <lhs_expr>[::T2]...

For instance:

@syms foo::Real bar baz(x, y::Real)::Complex

Create one or more variables. <lhs_expr> can be just a symbol in which case it will be the name of the variable, or a function call in which case a function-like variable which has the same name as the function being called. The Sym type, or in the case of a function-like Sym, the output type of calling the function can be set using the ::T syntax.

Examples:

• @syms foo bar::Real baz::Int will create

variable foo of symtype Number (the default), bar of symtype Real and baz of symtype Int

• @syms f(x) g(y::Real, x)::Int h(a::Int, f(b)) creates 1-arg f 2-arg g

and 2 arg h. The second argument to h must be a one argument function-like variable. So, h(1, g) will fail and h(1, f) will work.

Formal syntax

Following is a semi-formal CFG of the syntax accepted by this macro:

# any variable accepted by this macro must be a `var`.
# `var` can represent a quantity (`value`) or a function `(fn)`.
var = value | fn
# A `value` is represented as a name followed by a suffix
value = name suffix
# A `name` can be a valid Julia identifier
name = ident |
# Or it can be an interpolated variable, in which case `ident` is assumed to refer to
# a variable in the current scope of type `Symbol` containing the name of this variable.
# Note that in this case the created symbolic variable will be bound to a randomized
# Julia identifier.
       "$" ident |
# Or it can be of the form `Foo.Bar.baz` referencing a value accessible as `Foo.Bar.baz`
# in the current scope.
       getproperty_literal
getproperty_literal = ident "." getproperty_literal | ident "." ident
# The `suffix` can be empty (no suffix) which defaults the type to `Number`
suffix = "" |
# or it can be a type annotation (setting the type of the prefix). The shape of the result
# is inferred from the type as best it can be. In particular, `Array{T, N}` is inferred
# to have shape `Unknown(N)`.
         "::" type |
# or it can be a shape annotation, which sets the shape to the one specified by `ranges`.
# The type defaults to `Array{Number, length(ranges)}`
         "[" ranges "]" |
# lastly, it can be a combined shape and type annotation. Here, the type annotation
# sets the `eltype` of the symbolic array.
         "[" ranges "]::" type
# `ranges` is either a single `range` or a single range followed by one or more `ranges`.
ranges = range | range "," ranges
# A `range` is simply two bounds separated by a colon, as standard Julia ranges work.
# The range must be non-empty. Each bound can be a literal integer or an identifier
# representing an integer in the current scope.
range = (int | ident) ":" (int | ident) |
# Alternatively, a range can be a Julia expression that evaluates to a range. All identifiers
# used in `expr` are assumed to exist in the current scope.
        expr |
# Alternatively, a range can be a Julia expression evaluating to an iterable of ranges,
# followed by the splat operator.
        expr "..."
# A function is represented by a function-call syntax `fncall` followed by the `suffix`
# above. The type and shape from `suffix` represent the type and shape of the value
# returned by the symbolic function.
fn = fncall suffix
# a function call is a call `head` followed by a parenthesized list of arguments.
fncall = head "(" args ")"
# A function call head can be a name, representing the name of the symbolic function.
head = ident |
# Alternatively, it can be a parenthesized type-annotated name, where the type annotation
# represents the intended supertype of the function. In other words, if this symbolic
# function were to be replaced by an "actual" function, the type-annotation constrains the
# type of the "actual" function.
       "(" ident "::" type ")"
# Arguments to a function is a list of one or more arguments
args = arg | arg "," args
# An argument can take the syntax of a variable (which means we can represent functions of
# functions of functions of...). The type of the variable constrains the type of the
# corresponding argument of the function. The name and shape information is discarded.
arg = var |
# Or an argument can be an unnamed type-annotation, which constrains the type without
# requiring a name.
      "::" type |
# Or an argument can be the identifier `..`, which is used as a stand-in for `Vararg{Any}`
      ".." |
# Or an argument can be a type-annotated `..`, representing `Vararg{type}`. Note that this
# and the previous version of `arg` can only be the last element in `args` due to Julia's
# `Tuple` semantics.
      "(..)::" type |
# Or an argument can be a Julia expression followed by a splat operator. This assumes the
# expression evaluates to an iterable of symbolic variables whose `symtype` should be used
# as the argument types. Note that `expr` may be evaluated multiple times in the macro
# expansion.
      expr "..."

term(f, args...; vartype = SymReal, type = promote_symtype(f, symtype.(args)...), shape = promote_shape(f, SymbolicUtils.shape.(args)...))

Create a symbolic term with operation f and arguments args.

Arguments

• f: The operation or function head of the term
• args...: The arguments to the operation
• vartype: The variant type for the term (default: SymReal)
• type: The symbolic type of the term. If not provided, it is inferred using promote_symtype on the function and argument types.
• shape: The shape of the term. If not provided, it is inferred using promote_shape on the function and argument shapes.

Examples

julia> @syms x y
(x, y)

julia> term(+, x, y)
x + y

julia> term(sin, x)
sin(x)

julia> term(^, x, 2)
x^2

hasmetadata(s::Symbolic, ctx)

Check if a symbolic expression has metadata for a given context.

Arguments

• s::Symbolic: The symbolic expression to check
• ctx: The metadata context key (typically a DataType)

Returns

• true if the expression has metadata for the given context, false otherwise

Examples

julia> @syms x
x

julia> hasmetadata(x, Float64)
false

getmetadata(s::Symbolic, ctx)

Retrieve metadata associated with a symbolic expression for a given context.

Arguments

• s::Symbolic: The symbolic expression
• ctx: The metadata context key (typically a DataType)

Returns

The metadata value associated with the given context

Throws

• ArgumentError if the expression does not have metadata for the given context

Examples

julia> @syms x::Float64
x

julia> getmetadata(x, symtype)  # Get the type metadata
Float64

getmetadata(s::Symbolic, ctx, default)

Retrieve metadata associated with a symbolic expression for a given context, returning a default value if not found.

Arguments

• s::Symbolic: The symbolic expression
• ctx: The metadata context key (typically a DataType)
• default: The default value to return if metadata is not found

Returns

The metadata value associated with the given context, or default if not found

Examples

julia> @syms x
x

julia> getmetadata(x, Float64, "no type")
"no type"

setmetadata(s::Symbolic, ctx::DataType, val)

Set metadata for a symbolic expression in a given context.

Arguments

• s::Symbolic: The symbolic expression
• ctx::DataType: The metadata context key
• val: The metadata value to set

Returns

A new symbolic expression with the updated metadata

Examples

julia> @syms x
x

julia> x_with_meta = setmetadata(x, Float64, "custom value")
x

julia> getmetadata(x_with_meta, Float64)
"custom value"

promote_symtype(f, Ts...) -> Type{Bool}

The result of applying f to arguments of SymbolicUtils.symtype Ts...

julia> promote_symtype(+, Real, Real)
Real

julia> promote_symtype(+, Complex, Real)
Number

julia> @syms f(x)::Complex
(f(::Number)::Complex,)

julia> promote_symtype(f, Number)
Complex

When constructing expressions without an explicit symtype, promote_symtype is used to figure out the symtype of the Term.

It is recommended that all type arguments be annotated with SymbolicUtils.TypeT and one method be implemented for any combination of f and the number of arguments. For example, one method is implemented for unary - and one method for binary -. Each method has an if..elseif chain to handle possible types. Any call to promote_type should be typeasserted with ::TypeT.

promote_symtype(f::FnType{X,Y}, arg_symtypes...)

The output symtype of applying variable f to arguments of symtype arg_symtypes.... if the arguments are of the wrong type then this function will error.

@rule LHS => RHS

Creates a Rule object. A rule object is callable, and takes an expression and rewrites it if it matches the LHS pattern to the RHS pattern, returns nothing otherwise. The rule language is described below.

LHS can be any possibly nested function call expression where any of the arguments can optionally be a Slot (~x), Default Value Slot (~!x also called DefSlot) or a Segment (~~x) (described below).

If an expression matches LHS entirely, then it is rewritten to the pattern in the RHS. Slot, DefSlot and Segment variables on the RHS will substitute the result of the matches found for these variables in the LHS.

Slot:

A Slot variable is written as ~x and matches a single expression. x is the name of the variable. If a slot appears more than once in an LHS expression then expression matched at every such location must be equal (as shown by isequal).

Example:

Simple rule to turn any sin into cos:

julia> @syms a b c
(a, b, c)

julia> r = @rule sin(~x) => cos(~x)
sin(~x) => cos(~x)

julia> r(sin(1+a))
cos((1 + a))

A rule with 2 segment variables

julia> r = @rule sin(~x + ~y) => sin(~x)*cos(~y) + cos(~x)*sin(~y)
sin(~x + ~y) => sin(~x) * cos(~y) + cos(~x) * sin(~y)

julia> r(sin(a + b))
cos(a)*sin(b) + sin(a)*cos(b)

A rule that matches two of the same expressions:

julia> r = @rule sin(~x)^2 + cos(~x)^2 => 1
sin(~x) ^ 2 + cos(~x) ^ 2 => 1

julia> r(sin(2a)^2 + cos(2a)^2)
1

julia> r(sin(2a)^2 + cos(a)^2)
# nothing

DefSlot:

A DefSlot variable is written as ~!x. Works like a normal slot, but can also take default values if not present in the expression.

Example in power:

julia> r_pow = @rule (~x)^(~!m) => ~m
(~x) ^ ~(!m) => ~m

julia> r_pow(x^2)
2

julia> r_pow(x)
1

Example in sum:

julia> r_sum = @rule ~x + ~!y => ~y
~x + ~(!y) => ~y

julia> r_sum(x+2)
x

julia> r_sum(x)
0

Currently DefSlot is implemented in:

Segment:

A Segment variable is written as ~~x and matches zero or more expressions in the function call.

Example:

This implements the distributive property of multiplication: +(~~ys) matches expressions like a + b, a+b+c and so on. On the RHS ~~ys presents as any old julia array.

julia> r = @rule ~x * +((~~ys)) => sum(map(y-> ~x * y, ~~ys));

julia> r(2 * (a+b+c))
((2 * a) + (2 * b) + (2 * c))

Predicates:

There are two kinds of predicates, namely over slot variables and over the whole rule. For the former, predicates can be used on both ~x and ~~x by using the ~x::f or ~~x::f. Here f can be any julia function. In the case of a slot the function gets a single matched subexpression, in the case of segment, it gets an array of matched expressions.

The predicate should return true if the current match is acceptable, and false otherwise.

julia> two_πs(x::Number) = abs(round(x/(2π)) - x/(2π)) < 10^-9
two_πs (generic function with 1 method)

julia> two_πs(x) = false
two_πs (generic function with 2 methods)

julia> r = @rule sin(~~x + ~y::two_πs + ~~z) => sin(+(~~x..., ~~z...))
sin(~(~x) + ~(y::two_πs) + ~(~z)) => sin(+(~(~x)..., ~(~z)...))

julia> r(sin(a+3π))

julia> r(sin(a+6π))
sin(a)

julia> r(sin(a+6π+c))
sin((a + c))

Predicate function gets an array of values if attached to a segment variable (~~x).

For the predicate over the whole rule, use @rule <LHS> => <RHS> where <predicate>:

julia> @syms a b;

julia> predicate(x) = x === a;

julia> r = @rule ~x => ~x where predicate(~x);

julia> r(a)
a

julia> r(b) === nothing
true

Note that this is syntactic sugar and that it is the same as something like @rule ~x => f(~x) ? ~x : nothing.

Debugging Rules: Note that if the RHS is a single tilde ~, then the rule returns a a dictionary of all [slot variable, expression matched], this is useful for debugging.

Example:

julia> r = @rule (~x + (~y)^(~m)) => ~
~x + (~y) ^ ~m => (~)

julia> r(a + b^2)
Base.ImmutableDict{Symbol, Any} with 5 entries:
  :MATCH => a + b^2
  :m     => 2
  :y     => b
  :x     => a
  :____  => nothing

Context:

In predicates: Contextual predicates are functions wrapped in the Contextual type. The function is called with 2 arguments: the expression and a context object passed during a call to the Rule object (maybe done by passing a context to simplify or a RuleSet object).

The function can use the inputs however it wants, and must return a boolean indicating whether the predicate holds or not.

In the consequent pattern: Use (@ctx) to access the context object on the right hand side of an expression.

@acrule(lhs => rhs)

Create an associative-commutative rule that matches all permutations of the arguments.

This macro creates a rule that can match patterns regardless of the order of arguments in associative and commutative operations like addition and multiplication.

Arguments

• lhs: The pattern to match (left-hand side)
• rhs: The replacement expression (right-hand side)

Examples

julia> @syms x y z
(x, y, z)

julia> r = @acrule x + y => 2x  # Matches both x + y and y + x
ACRule(x + y => 2x)

julia> r(x + y)
2x

julia> r(y + x)
2x

See also: @rule, @ordered_acrule

A rewriter is any function which takes an expression and returns an expression or nothing. If nothing is returned that means there was no changes applicable to the input expression.

The Rewriters module contains some types which create and transform rewriters.

• Empty() is a rewriter which always returns nothing
• Chain(itr) chain an iterator of rewriters into a single rewriter which applies each chained rewriter in the given order. If a rewriter returns nothing this is treated as a no-change.
• RestartedChain(itr) like Chain(itr) but restarts from the first rewriter once on the first successful application of one of the chained rewriters.
• IfElse(cond, rw1, rw2) runs the cond function on the input, applies rw1 if cond returns true, rw2 if it returns false
• If(cond, rw) is the same as IfElse(cond, rw, Empty())
• Prewalk(rw; threaded=false, thread_cutoff=100) returns a rewriter which does a pre-order traversal of a given expression and applies the rewriter rw. Note that if rw returns nothing when a match is not found, then Prewalk(rw) will also return nothing unless a match is found at every level of the walk. threaded=true will use multi threading for traversal. thread_cutoff is the minimum number of nodes in a subtree which should be walked in a threaded spawn.
• Postwalk(rw; threaded=false, thread_cutoff=100) similarly does post-order traversal.
• Fixpoint(rw) returns a rewriter which applies rw repeatedly until there are no changes to be made.
• FixpointNoCycle behaves like Fixpoint but instead it applies rw repeatedly only while it is returning new results.
• PassThrough(rw) returns a rewriter which if rw(x) returns nothing will instead return x otherwise will return rw(x).

Empty()

A rewriter that always returns nothing, indicating no rewrite occurred.

This is useful as a placeholder or for conditional rewriting patterns.

Examples

julia> Empty()(x)
nothing

IfElse(cond, yes, no)

A conditional rewriter that applies yes if cond(x) is true, otherwise applies no.

Arguments

• cond: A function that returns true or false for the input
• yes: The rewriter to apply if the condition is true
• no: The rewriter to apply if the condition is false

Examples

julia> r = IfElse(x -> x > 0, x -> -x, x -> x)
julia> r(5)  # Returns -5
julia> r(-3) # Returns -3

See also: If

If(cond, yes)

A conditional rewriter that applies yes if cond(x) is true, otherwise returns the input unchanged.

This is equivalent to IfElse(cond, yes, Empty()).

Arguments

• cond: A function that returns true or false for the input
• yes: The rewriter to apply if the condition is true

Examples

julia> r = If(x -> x > 0, x -> -x)
julia> r(5)  # Returns -5
julia> r(-3) # Returns -3 (unchanged)

Chain(rws; stop_on_match=false)

Apply a sequence of rewriters to an expression, chaining the results.

Each rewriter in the chain receives the result of the previous rewriter. If a rewriter returns nothing, the input is passed unchanged to the next rewriter.

Arguments

• rws: A collection of rewriters to apply in sequence
• stop_on_match: If true, stop at the first rewriter that produces a change

Examples

julia> r1 = @rule sin(~x)^2 + cos(~x)^2 => 1
julia> r2 = @rule sin(2*(~x)) => 2*sin(~x)*cos(~x)
julia> chain = Chain([r1, r2])
julia> chain(sin(x)^2 + cos(x)^2)  # Returns 1

RestartedChain(rws)

Apply rewriters in sequence, restarting the chain when any rewriter produces a change.

When any rewriter in the chain produces a non-nothing result, the entire chain is restarted with that result as the new input.

Arguments

• rws: A collection of rewriters to apply

Examples

julia> r1 = @rule ~x + ~x => 2 * ~x
julia> r2 = @rule 2 * ~x => ~x * 2
julia> chain = RestartedChain([r1, r2])
julia> chain(x + x)  # Applies r1, then restarts and applies r2

Fixpoint(rw)

Apply a rewriter repeatedly until a fixed point is reached.

The rewriter is applied repeatedly until the output equals the input (either by identity or by isequal), indicating a fixed point has been reached.

Arguments

• rw: The rewriter to apply repeatedly

Examples

julia> r = @rule ~x + ~x => 2 * ~x
julia> fp = Fixpoint(r)
julia> fp(x + x + x + x)  # Keeps applying until no more changes

See also: FixpointNoCycle

FixpointNoCycle(rw)

FixpointNoCycle behaves like Fixpoint, but returns a rewriter which applies rw repeatedly until it produces a result that was already produced before, for example, if the repeated application of rw produces results a, b, c, d, b in order, FixpointNoCycle stops because b has been already produced.

Postwalk(rw; threaded=false, thread_cutoff=100, maketerm=maketerm)

Apply a rewriter to a symbolic expression tree in post-order (bottom-up).

Post-order traversal visits child nodes before their parents, allowing for simplification of subexpressions before the containing expression.

Arguments

• rw: The rewriter to apply at each node
• threaded: If true, use multi-threading for large expressions
• thread_cutoff: Minimum node count to trigger threading
• maketerm: Function to construct terms (defaults to maketerm)
• filter: Function which returns whether to search into a subtree

Examples

julia> r = @rule ~x + ~x => 2 * ~x
julia> pw = Postwalk(r)
julia> pw((x + x) * (y + y))  # Simplifies both additions
2x * 2y

See also: Prewalk

Prewalk(rw; threaded=false, thread_cutoff=100, maketerm=maketerm)

Apply a rewriter to a symbolic expression tree in pre-order (top-down).

Pre-order traversal visits parent nodes before their children, allowing for transformation of the overall structure before processing subexpressions.

Arguments

• rw: The rewriter to apply at each node
• threaded: If true, use multi-threading for large expressions
• thread_cutoff: Minimum node count to trigger threading
• maketerm: Function to construct terms (defaults to maketerm)
• filter: Function which returns whether to search into a subtree

Examples

julia> r = @rule sin(~x) => cos(~x)
julia> pw = Prewalk(r)
julia> pw(sin(sin(x)))  # Transforms outer sin first
cos(cos(x))

See also: Postwalk

PassThrough(rw)

A rewriter that returns the input unchanged if the wrapped rewriter returns nothing.

This is useful for making rewriters that preserve the input when no rule applies.

Arguments

• rw: The rewriter to wrap

Examples

julia> r = @rule sin(~x) => cos(~x)
julia> pt = PassThrough(r)
julia> pt(sin(x))  # Returns cos(x)
julia> pt(tan(x))  # Returns tan(x) unchanged

simplify(x; expand=false,
            threaded=false,
            thread_subtree_cutoff=100,
            rewriter=nothing)

Simplify an expression (x) by applying rewriter until there are no changes. expand=true applies expand in the beginning of each fixpoint iteration.

By default, simplify will assume denominators are not zero and allow cancellation in fractions. Pass simplify_fractions=false to prevent this.

expand(expr)

Expand expressions by distributing multiplication over addition, e.g., a*(b+c) becomes ab+ac.

expand uses replace symbols and non-algebraic expressions by variables of type variable_type to compute the distribution using a specialized sparse multivariate polynomials implementation. variable_type can be any subtype of MultivariatePolynomials.AbstractVariable.

substitute(expr, dict; fold=Val(false))

substitute any subexpression that matches a key in dict with the corresponding value. If fold=Val(false), expressions which can be evaluated won't be evaluated.

julia> substitute(1+sqrt(y), Dict(y => 2), fold=Val(true))
2.414213562373095
julia> substitute(1+sqrt(y), Dict(y => 2), fold=Val(false))
1 + sqrt(2)

simplify_fractions(x; polyform=false)

Find Div nodes and simplify them by cancelling a set of factors of numerators and denominators.

quick_cancel(d)

Cancel out matching factors from numerator and denominator. This is not as effective as simplify_fractions, for example, it wouldn't simplify (x^2 + 15 - 8x) / (x - 5) to (x - 3). But it will simplify (x - 5)^2*(x - 3) / (x - 5) to (x - 5)*(x - 3). Has optimized processes for Mul and Pow terms.

flatten_fractions(x)

Flatten nested fractions that are added together.

julia> flatten_fractions((1+(1+1/a)/a)/a)
(1 + a + a^2) / (a^3)