Discontinuities and Inequality Helpers

These interfaces describe how a discontinuous function behaves at a root or across a discontinuity. They are used by symbolic solvers and by code that needs to preserve one-sided or approximate inequality semantics.

Symbolics.rootfunction — Function

rootfunction(f)

Given a function f with a discontinuity or discontinuous derivative, return the rootfinding function of f. The rootfinding function g takes the same arguments as f, and is such that f can be described as a piecewise function based on the sign of g, where each piece is continuous and has a continuous derivative. The pieces are obtained using left_continuous_function(f) and right_continuous_function(f).

More formally,

f(args...) = if g(args...) < 0
    left_continuous_function(f)(args...)
else
    right_continuous_function(f)(args...)
end

For example, if f is max(x, y), the root function is (x, y) -> x - y with left_continuous_function as (x, y) -> y and right_continuous_function as (x, y) -> x.

source

Symbolics.left_continuous_function — Function

left_continuous_function(f)

Given a function f with a discontinuity or discontinuous derivative, return a function taking the same arguments as f which is continuous and has a continuous derivative when rootfinding_function(f) is negative.

See also: rootfunction.

source

Symbolics.majorization_function — Function

majorization_function(f)

Given a function f, return a majorization function m for f. The function m should have the signature m(k, args...) where args... are the same arguments as f. k is a Real value which acts as an approximation factor. For higher k, the function m should more closely approximate f over the domain. A majorization function is such that m(k, args...) >= f(args...) for all args... in the domain.

source

Symbolics.minorization_function — Function

minorization_function(f)

Given a function f, return a minorization function m for f. The function m should have the signature m(k, args...) where args... are the same arguments as f. k is a Real value which acts as an approximation factor. For higher k, the function m should more closely approximate f over the domain. A minorization function is such that m(k, args...) <= f(args...) for all args... in the domain.

source

Symbolics.approximation_function — Function

approximation_function(f)

Given a function f, return an approximation function appr for f. The function appr should have the signature appr(k, args...) where args.. are the same arguments as f. k is a Real value acting as an approximation factor. For higher k, the function appr should more closely approximate f over the domain. The function appr offers no guarantees other than infinite differentiability over the domain. At any point in the domain, it may evaluate to a value greater or less than the value returned by f for the same point.

source

Symbolics.@register_discontinuity — Macro

@register_discontinuity f(arg1, arg2, ...) root_expr left_expr right_expr

Utility macro to register functions with discontinuities. The function f with arguments arg1, arg2, ... has a rootfunction of root_expr, a left_continuous_function of left_expr and right_continuous_function of right_expr. root_expr, left_expr and right_expr are all expressions in terms of arg1, arg2, ....

For example, max(x, y) can be registered as @register_discontinuity max(x, y) x - y y x.