API reference

ImplicitDifferentiation

A Julia package for automatic differentiation of implicit functions.

Its main export is the type ImplicitFunction.

ImplicitFunction

Wrapper for an implicit function defined by a solver and a set of conditions which the solution satisfies.

An ImplicitFunction object behaves like a function, with the following signature:

y, z = (implicit::ImplicitFunction)(x, args...)

The first output y is differentiable with respect to the first argument x, while the second output z (a byproduct of the solve) and the following positional arguments args are considered constant.

When a derivative is queried, the Jacobian of y(x) is computed using the implicit function theorem applied to the conditions c(x, y) (we ignore z for concision):

∂₂c(x, y(x)) * ∂y(x) = -∂₁c(x, y(x))

This requires solving a linear system A * J = -B where A = ∂₂c, B = ∂₁c and J = ∂y.

Constructor

ImplicitFunction(
    solver,
    conditions,
    linear_solver=KrylovLinearSolver(),
    representation=OperatorRepresentation(),
    backend=nothing,
    preparation=nothing,
    input_example=nothing,
)

Positional arguments

• solver: a callable returning (x, args...) -> (y, z) where z is an arbitrary byproduct of the solve. Both x and y must be subtypes of AbstractArray, while z and args can be anything.
• conditions: a callable returning a vector of optimality conditions (x, y, z, args...) -> c, must be compatible with automatic differentiation

Keyword arguments

• linear_solver: a callable to solve linear systems with two required methods, one for (A, b) (single solve) and one for (A, B) (batched solve) (defaults to KrylovLinearSolver)
• representation: either MatrixRepresentation or OperatorRepresentation
• backend::AbstractADType: either nothing or an object from ADTypes.jl dictating how how the conditions will be differentiated
• preparation: either nothing or a mode object from ADTypes.jl: ADTypes.ForwardMode(), ADTypes.ReverseMode() or ADTypes.ForwardOrReverseMode()
• input_example: either nothing or a tuple (x, args...) used to prepare differentiation

KrylovLinearSolver

Callable object that can solve linear systems Ax = b and AX = B in the same way as the built-in \. Uses an iterative solver from Krylov.jl under the hood.

Constructor

KrylovLinearSolver(; verbose=true)

If verbose is true, the solver logs a warning in case of failure. Otherwise it will fail silently, and may return solutions that do not exactly satisfy the linear system.

Callable behavior

(::KylovLinearSolver)(A, b::AbstractVector)

Solve a linear system with a single right-hand side.

(::KrylovLinearSolver)(A, B::AbstractMatrix)

Solve a linear system with multiple right-hand sides.

MatrixRepresentation

Specify that the matrices involved in the implicit function theorem should be represented explicitly, with all their coefficients.

See also

• ImplicitFunction
• OperatorRepresentation

OperatorRepresentation

Specify that the matrices involved in the implicit function theorem should be represented lazily, as linear operators from LinearOperators.jl.

See also

• ImplicitFunction
• MatrixRepresentation

NoPreparation

Specify that the derivatives of the conditions should not be prepared for subsequent differentiation of the implicit function.

ForwardPreparation

Specify that the derivatives of the conditions should be prepared for subsequent forward-mode differentiation of the implicit function.

ReversePreparation

Specify that the derivatives of the conditions should be prepared for subsequent reverse-mode differentiation of the implicit function.

BothPreparation

Specify that the derivatives of the conditions should be prepared for subsequent forward- or reverse-mode differentiation of the implicit function.

Switch12

Represent a function which behaves like f, except that the first and second arguments are switched: f(a1, a2, a3) = b becomes g(a2, a1, a3) = f(a1, a2, a3)

VecToVec

Represent a function which behaves like f, except that the first argument is expected as a vector, and the return is converted to a vector: f(a1, a2, a3) = b becomes g(a1vec, a2, a3) = vec(f(reshape(a1vec, size(a1)), a2, a3))