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;
    representation=OperatorRepresentation(),
    linear_solver=IterativeLinearSolver(),
    backends=nothing,
    strict=Val(true),
)

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

• representation: defines how the partial Jacobian A of the conditions with respect to the output is represented. It can be either MatrixRepresentation or OperatorRepresentation.
• linear_solver: specifies how the linear system A * J = -B will be solved in the implicit function theorem. It must be a subtype of AbstractSolver.
• backends::AbstractADType: specifies how the conditions will be differentiated with respect to x and y. It can be either, nothing, which means that the external autodiff system will be used, or a named tuple (; x=AutoSomething(), y=AutoSomethingElse()) of backend objects from ADTypes.jl.
• strict::Val: specifies whether preparation inside DifferentiationInterface.jl should enforce a strict match between the primal variables and the provided tangents.

MatrixRepresentation

Specify that the matrix A involved in the implicit function theorem should be represented explicitly, with all its coefficients.

See also

• ImplicitFunction
• OperatorRepresentation

OperatorRepresentation

Specify that the matrix A involved in the implicit function theorem should be represented lazily, as a function.

See also

• ImplicitFunction
• MatrixRepresentation

AbstractSolver

Abstract supertype for linear solvers to be used within an ImplicitFunction.

Interface

The only requirement on any concrete subtype MySolver is that it should be callable, with the following signature:

(s::MySolver)(A, Aᵀ, x0, b)

This method should solve the linear system Ax = b, possibly using the transpose Aᵀ or starting from an initial point x0. Depending on the representation chosen for the ImplicitFunction, the arguments A and Aᵀ might be either matrix-like or functional objects.

Implementations

This package provides three default implementations:

• DirectLinearSolver
• IterativeLinearSolver
• IterativeLeastSquaresSolver

IterativeLinearSolver <: AbstractSolver

Specify that linear systems Ax = b should be solved with an iterative method.

See also

• ImplicitFunction
• AbstractSolver

IterativeLeastSquaresSolver <: AbstractSolver

Specify that linear systems Ax = b should be solved with an iterative least-squares method.

See also

• ImplicitFunction
• AbstractSolver

DirectLinearSolver <: AbstractSolver

Specify that linear systems Ax = b should be solved with a direct method.

f = ImplicitFunction(
    forward,
    conditions;
    solver = DirectLinearSolver(),
    representation = MatrixRepresentation()
)

See also

• ImplicitFunction
• AbstractSolver

ImplicitFunctionPreparation

Fields

• prep_A: preparation for A (derivative of conditions with respect to y) in forward mode
• prep_Aᵀ: preparation for A (derivative of conditions with respect to y) in reverse mode
• prep_B: preparation for B (derivative of conditions with respect to x) in forward mode
• prep_Bᵀ: preparation for B (derivative of conditions with respect to x) in reverse mode

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)

prepare_implicit(
    mode::ADTypes.AbstractMode,
    implicit::ImplicitFunction,
    x_prep,
    args_prep...;
    strict=Val(true)
)

Uses the preparation mechanism from DifferentiationInterface.jl to speed up subsequent differentiated calls to implicit(x, args...) where (x, args...) are similar to (x_prep, args_prep...).

The mode argument is an object from ADTypes.jl that specifies whether the preparation should target ForwardMode, ReverseMode or both (ForwardOrReverseMode).