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 can be either DirectLinearSolver, IterativeLinearSolver or IterativeLeastSquaresSolver.
• 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

IterativeLinearSolver

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

See also

• ImplicitFunction
• DirectLinearSolver
• IterativeLeastSquaresSolver

IterativeLeastSquaresSolver

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

See also

• ImplicitFunction
• DirectLinearSolver
• IterativeLinearSolver

DirectLinearSolver

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

See also

• ImplicitFunction
• IterativeLinearSolver
• IterativeLeastSquaresSolver

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).