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,
    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

• representation: defines how the partial Jacobian A of the conditions with respect to the output is represented, either MatrixRepresentation or OperatorRepresentation.
• linear_solver: a callable to solve linear systems with two required methods, one for (A, b::AbstractVector) (single solve) and one for (A, B::AbstractMatrix) (batched solve). It defaults to IterativeLinearSolver but can also be the built-in \, or a user-provided function.
• 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.
• 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.
• strict::Val=Val(true): whether or not to enforce a strict match in DifferentiationInterface.jl between the preparation and the execution types.

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.

Constructors

OperatorRepresentation(;
    symmetric=false, hermitian=false, posdef=false, keep_input_type=false
)
OperatorRepresentation{package}(;
    symmetric=false, hermitian=false, posdef=false, keep_input_type=false
)

The type parameter package can be either:

• :LinearOperators to use a wrapper from LinearOperators.jl (the default)
• :LinearMaps to use a wrapper from LinearMaps.jl

The keyword arguments symmetric, hermitian and posdef give additional properties of the Jacobian of the conditions with respect to the solution y, which are useful to the solver in case you can prove them.

The keyword argument keep_input_type dictates whether to force the linear operator to work with the provided input type, or fall back on a default.

See also

• ImplicitFunction
• MatrixRepresentation

IterativeLinearSolver

Callable object that can solve linear systems Ax = b and AX = B in the same way as the built-in \.

Constructor

IterativeLinearSolver(; kwargs...)
IterativeLinearSolver{package}(; kwargs...)

The type parameter package can be either:

• :Krylov to use the solver gmres or block_gmres from Krylov.jl (the default)
• :IterativeSolvers to use the solver gmres from IterativeSolvers.jl

Keyword arguments are passed on to the respective solver.

Callable behavior

(::IterativeLinearSolver)(A, b::AbstractVector)

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

(::IterativeLinearSolver)(A, B::AbstractMatrix)

Solve a linear system with multiple right-hand sides.

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