module FunctionChains

Implements chained functions (composed functions) beyond Base.ComposedFunction.

struct FunctionChains.AsFunction{F} <: Function

Wraps a callable object to make it a Function.

User code should typically not instantiate AsFunction objects directly, but use asfunction(f) instead.

struct FCartProd{FS}<:Function

Represents a Cartesian product of functions.

A FCartProd has a single field _fs which may be a Tuple, NamedTuple, an array or a generator/iterator of functions.

Use fcprod to construct products of functions instead of using the constructor FCartProd(fs) directly.

struct FFanout{FS}<:Function

Represents a function fanout.

A FFanout has a single field _fs which may be a Tuple, NamedTuple, an array or a generator/iterator of functions.

Use ffanout to construct a function fanout instead of using the constructor FFanout(fs) directly.

struct FunctionChain{FS}<:Function

Represents a chain of composed functions.

(fc::FunctionChain)(x) applies the functions in the chain in order of iteration over fc._fs.

Use fchain to construct function chains instead of using the constructor FunctionChain(fs) directly.

Use fchainfs(fc) to retrieve the components of a FunctionChain in order of function execution.

∘̂(f, n::Integer)
f∘̂ n

Create a chain of function f repeated n times, with support for n <= 0.

The type of the returned function depends on n:

• n == 0: return identity
• n == 1: return f
• n > 1: return frepeat(f, n)
• n == -1: return InverseFunctions.inverse(f)
• n < -1: return frepeat(InverseFunctions.inverse(f), -n)

applyf(f, xs...) = f(xs...)

Function application: Apply a function f to one or multiple arguments.

Primarily useful to broadcast collections of function over collections of arguments, e.g. applyf(fs, as, bs, ...) or to calculate derivatives in respect to function parameters (closure contents), e.g. Zygote.gradient(applyf, f_withargs, xs...).

asfunction(f)::Function
asfunction(f::Function) === f

Wraps a callable f to make it a Function.

If f isa Function, simply returns f. If f is a type (constructor), returns a properly typed function object.

fbcast(f)

Return a broadcasted version of the function f, so that fbcast(f)(A, ...) is semantically equivalent to f.(A, ...).

fbcast(f)(A) is also semantically equivalent to fcprod( Fill(f, size(A)) )(A).

Typically returns a Broadcast.BroadcastFunction, but may be specialized to return broadcasted implementations depending on the type of f. For example, fbcast(identity) === identity.

The resulting broadcasted function supports InverseFunctions.inverse and/or ChangesOfVariables.with_logabsdet_jacobian if f does so.

fchain()
fchain(fs)
fchain(fs...)

Construct a function chain of functions fs.

Typically returns a FunctionChain, but may be specialized to return other function chain types for specific types of functions.

fs must be iterable, it may be a tuple, vector, generator, etc. fchain(fs)(x) will apply the functions in fs in order of iteration. A chain of zero functions acts as the identity function.

The resulting function chain supports with_intermediate_results, and also supports InverseFunctions.inverse and/or ChangesOfVariables.with_logabsdet_jacobian if all functions in the chain do so.

Use fchainfs(fc) to retrieve fs.

fchainfs(fc)

Get the component functions of a function chain or composed function fc, in order of function execution.

See fchain for details.

fcomp()
fcomp(fs)
fcomp(fs...)

Construct a composition of the functions fs that is semantically equivalent to fs[1] ∘ fs[2] ∘ ... and fchain(reverse(fs)).

The resulting function composition supports with_intermediate_results, but note that the intermediate results are in order of function evaluation, not in the order of the functions in fs.

The composition also supports InverseFunctions.inverse and/or ChangesOfVariables.with_logabsdet_jacobian if all functions in the composition do so.

fcprod()
fcprod(fs)
fcprod(fs...)

Construct the Cartesian product of functions over the functions fs.

Typically returns a FCartProd, but may be specialized to return other product function types for specific types of element functions.

fs must be iterable, it may be a Tuple, NamedTuple, an array or a generator/iterator of functions.

fcprod behaves like

fcprod((f_a, f_b, ...))((x_a, x_b, ...)) = (f_a(x_a), f_b(x_b), ...)
fcprod((a = f_a, b = f_b, ...))((a = x_a, b = x_b, ...)) = (a = f_a(x_a), b = f_b(x_b), ...)
fcprod([f_a, f_b, ...])([x_a, x_b, ...]) = [f_a(x_a), f_b(x_b), ...]

This is similar, semantically, to Haskell's *** for arrows.

For fp = fcprod(fs), use fcprodfs(fp) to retrieve fs.

The resulting product of functions supports InverseFunctions.inverse and/or ChangesOfVariables.with_logabsdet_jacobian if all functions in the product do so.

fcprodfs(fp)

Get the component functions of a cartesian product of functions.

See fcprod for details.

ffanout()
ffanout(fs)
ffanout(fs...)

Construct a function fanout with the functions fs.

This is similar, semantically, to Haskell's &&& for arrows.

Typically returns a FFanout, but may be specialized to return other function fanout types for specific types of element functions.

fs must be iterable, it may be a Tuple, NamedTuple, an array or a generator/iterator of functions.

The resulting function fanout behaves like

ffanout((f_a, f_b, ...))(x) = (f_a(x), f_b(x), ...)
ffanout((a = f_a, b = f_b, ...))(x) = (a = f_a(x), b = f_b(x), ...)
ffanout([f_a, f_b, ...])(x) = [f_a(x), f_b(x), ...]

For ff = ffanout(fs), use ffanoutfs(ff) to retrieve fs.

ffanoutfs(fc)

Get the component functions of a function fanout.

See ffanout for details.

ffchain(f, g, hs...)
ffchain() = identity
ffchain(f) = f
ffchain(::Type{F}) where F = FunctionChains.AsFunction{Type{F}}(F)

Similar to fchain((f, g, hs...)), but flattens arguments of type ComposedFunction and merges FunctionChain arguments.

Tries to remove superfluous identity functions and to return a simple function instead of a FunctionChain if possible.

Behaves like ffcomp(hs..., g, f) (see ffcomp).

ffcomp(f, g, hs...)
ffcomp() = identity
ffcomp(f) = f
ffcomp(::Type{F}) where F = FunctionChains.AsFunction{Type{F}}(F)

Similar to fcomp((f, g, hs...)), but flattens arguments of type ComposedFunction and merges FunctionChain arguments.

Tries to remove superfluous identity functions and to return a simple function instead of a FunctionChain if possible.

Behaves like ffchain(hs..., g, f) (see ffchain).

frepeat(f, n::Integer)

Create a chain of function f repeated n times.

See also ∘̂(f, n) for a version that supports n <= 0.

The resulting function chain supports InverseFunctions.inverse and/or ChangesOfVariables.with_logabsdet_jacobian if f does so.

typed_callable(f)

Wraps a callable f in a typed function object if necessary, e.g. if f is a type (constructor).

with_intermediate_results(f, x)

Apply multi-step function f to x and return a collection that contains the intermediate results and the final result.