Function Registration and Tracing

@register_symbolic(expr, define_promotion = true, Ts = [Real])

Overload appropriate methods so that Symbolics can stop tracing into the registered function. If define_promotion is true, then a promotion method in the form of

SymbolicUtils.promote_symtype(::typeof(f_registered), args...) = Real # or the annotated return type

is defined for the register function. Note that when defining multiple register overloads for one function, all the rest of the registers must set define_promotion to false except for the first one, to avoid method overwriting.

Examples

@register_symbolic foo(x, y)
@register_symbolic foo(x, y::Bool) false # do not overload a duplicate promotion rule
@register_symbolic goo(x, y::Int) # `y` is not overloaded to take symbolic objects
@register_symbolic hoo(x, y)::Int # `hoo` returns `Int`

See @register_array_symbolic to register functions which return arrays.

@register_array_symbolic(expr, define_promotion = true)

Example:

# Let's say vandermonde takes an n-vector and returns an n x n matrix
@register_array_symbolic vandermonde(x::AbstractVector) begin
    size=(length(x), length(x))
    eltype=eltype(x) # optional, will default to the promoted eltypes of x
end

You can also register calls on callable structs:

@register_array_symbolic (c::Conv)(x::AbstractMatrix) begin
    size=size(x) .- size(c.kernel) .+ 1
    eltype=promote_type(eltype(x), eltype(c))
end

If define_promotion = true then a promotion method in the form of

SymbolicUtils.promote_symtype(::typeof(f_registered), args...) = # inferred or annotated return type

is defined for the register function. Note that when defining multiple register overloads for one function, all the rest of the registers must set define_promotion to false except for the first one, to avoid method overwriting.

@register_derivative fn(args...) Ith_arg derivative

Register a symbolic derivative for a function. This typically accompanies a call to @register_symbolic or @register_array_symbolic and defines how expand_derivatives will behave when it tries to differentiate the registered function.

The first argument to the macro is a call to the function whose derivative is being defined. The call cannot have keyword arguments or default arguments. The call must have either an exact number of arguments or a single variadic argument. For example, f(a), f(a, b), f(a, b, c) and f(args...) are valid signatures. f(a, b, args...) is invalid. If an exact number of arguments is provided, the defined derivative is specific to that number of arguments. If the variadic signature is used, the defined derivative is valid for all numbers of arguments. In case multiple derivatives are registered for the same function, they must have different numbers of arguments. A derivative for an exact number of arguments is more specific than a variadic definition. For example, @register_derivatives f(a, b) #... is more specific than @register_derivatives f(args...) #... for a 2-argument call to f. The arguments can be referred to with their declared names inside the derivative definition.

The second argument to the macro is the argument with respect to which the derivative rule is defined. For example, @register_derivative f(a, b) 2 #... is a derivative rule with respect to the second argument of f. Mathematically, it represents $\frac{ \partial f(a, b) }{ \partial b }$. To define a generic derivative, this argument can be an identifier. For example, @register_derivative f(a, b) I #... makes I available in the derivative definition as the index of the argument with respect to which the derivative is being taken.

The third argument to the macro is the derivative expression. This should be a symbolically traceable expression returning the derivative of the specified function with respect to the specified argument. In case of a variadic definition, the identifier Nargs is available to denote the number of arguments provided to the function. In case the variadic form is used, the arguments are available as a read-only array (mutation will error). Mutating the array is unsafe and undefined behavior.

Following are example definitions of derivatives:

@register_derivative sin(x) 1 cos(x)
@register_derivative max(x, y) 2 ifelse(x >= y, 0, 1)
@register_derivative min(args...) I begin
  error("The rule for the derivative of `min` with $Nargs arguments w.r.t the $I-th argument is undefined.")
end
@register_derivative (foo::MyCallableStruct)(args...) I begin
  error("Oops! Didn't implement the derivative for $foo")
end

@derivative_rule f(args...) I

Query Symbolics.jl's derivative rule system for the derivative of f(args...) with respect to args[I]. Returns a symbolic result representing the derivative. In case the derivative rule is not defined, evaluates to nothing.

The first argument to the macro must be a valid function call syntax. Splatting of arguments is permitted. The second argument must be an expression or literal evaluating to the index of the argument with respect to which the derivative is required.

The derivative rule can dispatch statically if f, the number of arguments and I are known at compile time. Example invocations are:

# static dispatch
@derivative_rule sin(x) 1
# static dispatch if `xs` is a tuple
@derivative_rule max(xs...) 2
# static dispatch if `y` and `w` are tuples, and `N + 2K` is a compile-time constant
@derivative_rule foo(x, y..., z, w...) (N + 2K)

inverse(f)

Given a single-input single-output function f, return its inverse g. This requires that f is bijective. If inverse is defined for a function, left_inverse and right_inverse should return inverse(f). inverse(g) should also be defined to return f.

See also: left_inverse, right_inverse, @register_inverse.

left_inverse(f)

Given a single-input single-output function f, return its left inverse g. This requires that f is injective. If left_inverse is defined for a function, right_inverse and inverse must not be defined and should error. right_inverse(g) should also be defined to return f.

See also: inverse, right_inverse, @register_inverse.

right_inverse(f)

Given a single-input single-output function f, return its right inverse g. This requires that f is surjective. If right_inverse is defined for a function, left_inverse and inverse must not be defined and should error. left_inverse(g) should also be defined to return f.

See also inverse, left_inverse, @register_inverse.

@register_inverse f g
@register_inverse f g left
@register_inverse f g right

Mark f and g as inverses of each other. By default, assume that f and g are bijective. Also defines left_inverse and right_inverse to call inverse. If the third argument is left, assume that f is injective and g is its left inverse. If the third argument is right, assume that f is surjective and g is its right inverse.

has_inverse(_) -> Bool

Check if the provided function has an inverse defined via inverse. Uses hasmethod to perform the check.

has_left_inverse(_) -> Bool

Check if the provided function has a left inverse defined via left_inverse Uses hasmethod to perform the check.

has_right_inverse(_) -> Bool

Check if the provided function has a left inverse defined via left_inverse Uses hasmethod to perform the check.