API reference
Public
ImplicitDifferentiation
— ModuleImplicitDifferentiation
A Julia package for automatic differentiation of implicit functions.
Its main export is the type ImplicitFunction
.
Main entry point
ImplicitDifferentiation.ImplicitFunction
— TypeImplicitFunction
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)
wherez
is an arbitrary byproduct of the solve. Bothx
andy
must be subtypes ofAbstractArray
, whilez
andargs
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 JacobianA
of the conditions with respect to the output is represented. It can be eitherMatrixRepresentation
orOperatorRepresentation
.linear_solver
: specifies how the linear systemA * J = -B
will be solved in the implicit function theorem. It can be eitherDirectLinearSolver
orIterativeLinearSolver
.backends::AbstractADType
: specifies how theconditions
will be differentiated with respect tox
andy
. 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.
Settings
ImplicitDifferentiation.MatrixRepresentation
— TypeMatrixRepresentation
Specify that the matrix A
involved in the implicit function theorem should be represented explicitly, with all its coefficients.
See also
ImplicitDifferentiation.OperatorRepresentation
— TypeOperatorRepresentation
Specify that the matrix A
involved in the implicit function theorem should be represented lazily, as a function.
See also
ImplicitDifferentiation.IterativeLinearSolver
— TypeIterativeLinearSolver
Specify that linear systems Ax = b
should be solved with an iterative method.
See also
ImplicitDifferentiation.DirectLinearSolver
— TypeDirectLinearSolver
Specify that linear systems Ax = b
should be solved with a direct method.
See also
Internals
ImplicitDifferentiation.ImplicitFunctionPreparation
— TypeImplicitFunctionPreparation
Fields
prep_A
: preparation forA
(derivative of conditions with respect toy
) in forward modeprep_Aᵀ
: preparation forA
(derivative of conditions with respect toy
) in reverse modeprep_B
: preparation forB
(derivative of conditions with respect tox
) in forward modeprep_Bᵀ
: preparation forB
(derivative of conditions with respect tox
) in reverse mode
ImplicitDifferentiation.Switch12
— TypeSwitch12
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)
ImplicitDifferentiation.prepare_implicit
— Methodprepare_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
).