Add OptimKit interlinks and use @extref for OptimKit references

docs/make.jl

@@ -28,6 +28,7 @@ links = InterLinks(
     # "Zygote" => "https://fluxml.ai/Zygote.jl/stable/",
     "ChainRulesCore" => "https://juliadiff.org/ChainRulesCore.jl/stable/",
     "MatrixAlgebraKit" => "https://quantumkithub.github.io/MatrixAlgebraKit.jl/stable/",
+    "OptimKit" => "https://jutho.github.io/OptimKit.jl/stable/",
 )
 
 # explicitly set math engine

docs/src/examples/3d_ising_partition_function/index.md

@@ -205,7 +205,7 @@ end;
 ````
 
 There are a few things to note about this cost function definition. Since we will pass it to
-the `OptimKit.optimize`, we require it to return both our cost function and the
+[`OptimKit.optimize`](@extref), we require it to return both our cost function and the
 corresponding gradient. To do this, we simply use the `withgradient` method from Zygote.jl
 to automatically compute the gradient of the cost function straight from the primal
 computation. Since our cost function involves contractions using `leading_boundary`, we also
@@ -231,12 +231,12 @@ contractions and we don't need to think about them much, optimizing over the man
 
 In particular, we need to define two kinds of operations on this manifold: a retraction and
 a transport. The retraction, corresponding to the `retract` keyword argument of
-`OptimKit.optimize`, specifies how to move from a point on a manifold along a given descent
+[`OptimKit.optimize`](@extref), specifies how to move from a point on a manifold along a given descent
 direction to obtain a new manifold point. The transport, corresponding to the `transport!`
-keyword argument of `OptimKit.optimize`, specifies how to transport a descent direction at a
+keyword argument of [`OptimKit.optimize`](@extref), specifies how to transport a descent direction at a
 given manifold point to a valid descent direction at a different manifold point according to
 the appropriate metric. For a more detailed explanation we refer to the
-[OptimKit.jl README](https://github.com/Jutho/OptimKit.jl). In PEPSKit.jl, these two
+[OptimKit.jl documentation](@extref OptimKit Optimization-API). In PEPSKit.jl, these two
 procedures are defined through the [`PEPSKit.peps_retract`](@ref) and
 [`PEPSKit.peps_transport!`](@ref) methods. While it is instructive to read the corresponding
 docstrings in order to understand what these actually do, here we can just blindly reuse
@@ -267,7 +267,7 @@ end;
 
 All that is left then is to specify the virtual spaces of the PEPS and the two environments,
 initialize them in the appropriate way, choose an optimization algortithm and call the
-`optimize` function from OptimKit.jl to get our desired PEPS fixed point.
+[`optimize`](@extref OptimKit.optimize) function from OptimKit.jl to get our desired PEPS fixed point.
 
 ````julia
 Vpeps = ℂ^2

docs/src/examples/3d_ising_partition_function/main.ipynb

@@ -247,7 +247,7 @@
    "metadata": {},
    "source": [
     "There are a few things to note about this cost function definition. Since we will pass it to\n",
-    "the `OptimKit.optimize`, we require it to return both our cost function and the\n",
+    "[`OptimKit.optimize`](@extref), we require it to return both our cost function and the\n",
     "corresponding gradient. To do this, we simply use the `withgradient` method from Zygote.jl\n",
     "to automatically compute the gradient of the cost function straight from the primal\n",
     "computation. Since our cost function involves contractions using `leading_boundary`, we also\n",
@@ -273,12 +273,12 @@
     "\n",
     "In particular, we need to define two kinds of operations on this manifold: a retraction and\n",
     "a transport. The retraction, corresponding to the `retract` keyword argument of\n",
-    "`OptimKit.optimize`, specifies how to move from a point on a manifold along a given descent\n",
+    "[`OptimKit.optimize`](@extref), specifies how to move from a point on a manifold along a given descent\n",
     "direction to obtain a new manifold point. The transport, corresponding to the `transport!`\n",
-    "keyword argument of `OptimKit.optimize`, specifies how to transport a descent direction at a\n",
+    "keyword argument of [`OptimKit.optimize`](@extref), specifies how to transport a descent direction at a\n",
     "given manifold point to a valid descent direction at a different manifold point according to\n",
     "the appropriate metric. For a more detailed explanation we refer to the\n",
-    "[OptimKit.jl README](https://github.com/Jutho/OptimKit.jl). In PEPSKit.jl, these two\n",
+    "[OptimKit.jl documentation](@extref OptimKit Optimization-API). In PEPSKit.jl, these two\n",
     "procedures are defined through the `PEPSKit.peps_retract` and\n",
     "`PEPSKit.peps_transport!` methods. While it is instructive to read the corresponding\n",
     "docstrings in order to understand what these actually do, here we can just blindly reuse\n",
@@ -319,7 +319,7 @@
     "\n",
     "All that is left then is to specify the virtual spaces of the PEPS and the two environments,\n",
     "initialize them in the appropriate way, choose an optimization algortithm and call the\n",
-    "`optimize` function from OptimKit.jl to get our desired PEPS fixed point."
+    "[`optimize`](@extref OptimKit.optimize) function from OptimKit.jl to get our desired PEPS fixed point."
    ]
   },
   {

docs/src/examples/heisenberg/index.md

@@ -77,7 +77,7 @@ boundary_alg = (; tol = 1.0e-10, trunc = (; alg = :FixedSpaceTruncation));
 ````
 
 Let us also configure the optimizer algorithm. We are going to optimize the PEPS using the
-L-BFGS optimizer from [OptimKit](https://github.com/Jutho/OptimKit.jl). Again, we specify
+[L-BFGS optimizer](@extref OptimKit.LBFGS) from [OptimKit](https://github.com/Jutho/OptimKit.jl). Again, we specify
 the convergence tolerance (for the gradient norm) as well as the maximal number of iterations
 and the BFGS memory size (which is used to approximate the Hessian):
 

docs/src/examples/heisenberg/main.ipynb

@@ -124,7 +124,7 @@
    "metadata": {},
    "source": [
     "Let us also configure the optimizer algorithm. We are going to optimize the PEPS using the\n",
-    "L-BFGS optimizer from [OptimKit](https://github.com/Jutho/OptimKit.jl). Again, we specify\n",
+    "[L-BFGS optimizer](@extref OptimKit.LBFGS) from [OptimKit](https://github.com/Jutho/OptimKit.jl). Again, we specify\n",
     "the convergence tolerance (for the gradient norm) as well as the maximal number of iterations\n",
     "and the BFGS memory size (which is used to approximate the Hessian):"
    ]

examples/3d_ising_partition_function/main.jl

@@ -194,7 +194,7 @@ end;
 
 md"""
 There are a few things to note about this cost function definition. Since we will pass it to
-the `OptimKit.optimize`, we require it to return both our cost function and the
+[`OptimKit.optimize`](@extref), we require it to return both our cost function and the
 corresponding gradient. To do this, we simply use the `withgradient` method from Zygote.jl
 to automatically compute the gradient of the cost function straight from the primal
 computation. Since our cost function involves contractions using `leading_boundary`, we also
@@ -220,12 +220,12 @@ contractions and we don't need to think about them much, optimizing over the man
 
 In particular, we need to define two kinds of operations on this manifold: a retraction and
 a transport. The retraction, corresponding to the `retract` keyword argument of
-`OptimKit.optimize`, specifies how to move from a point on a manifold along a given descent
+[`OptimKit.optimize`](@extref), specifies how to move from a point on a manifold along a given descent
 direction to obtain a new manifold point. The transport, corresponding to the `transport!`
-keyword argument of `OptimKit.optimize`, specifies how to transport a descent direction at a
+keyword argument of [`OptimKit.optimize`](@extref), specifies how to transport a descent direction at a
 given manifold point to a valid descent direction at a different manifold point according to
 the appropriate metric. For a more detailed explanation we refer to the
-[OptimKit.jl README](https://github.com/Jutho/OptimKit.jl). In PEPSKit.jl, these two
+[OptimKit.jl documentation](@extref OptimKit Optimization-API). In PEPSKit.jl, these two
 procedures are defined through the [`PEPSKit.peps_retract`](@ref) and
 [`PEPSKit.peps_transport!`](@ref) methods. While it is instructive to read the corresponding
 docstrings in order to understand what these actually do, here we can just blindly reuse
@@ -256,7 +256,7 @@ md"""
 
 All that is left then is to specify the virtual spaces of the PEPS and the two environments,
 initialize them in the appropriate way, choose an optimization algortithm and call the
-`optimize` function from OptimKit.jl to get our desired PEPS fixed point.
+[`optimize`](@extref OptimKit.optimize) function from OptimKit.jl to get our desired PEPS fixed point.
 """
 
 Vpeps = ℂ^2

examples/Cache.toml

@@ -4,8 +4,8 @@ bose_hubbard = "19b4cffef158787be173fae44ea9507430762aab2824895d1d1d632aaab0c9b3
 c4v_ctmrg = "275a6e6fd010e5c39001ed05c11e904ec00f11ba265fc339cec61ffb2993f05e"
 j1j2_su = "3703e4474b114e6e535bbf46728cb2e5698ba644fe71506a439d9f327e1a7c40"
 hubbard_su = "1d737f84999852680157f7daab9897ca4ca2fca2e5f6c781eacd2d8d39fa91c1"
-heisenberg = "9a51a621f079cbcf3257ebe52574fa62aa249bbbb3a7c8cd0c396f75a1c1210e"
+heisenberg = "536dfa7586738327883ee2cfd720ce3653c93cc0475a0934ba327a4482fd31b5"
 2d_ising_partition_function = "043e1b0b97197ed611559f4a4683cb8f166c01af82a97f71364f2f5421abe3d2"
-3d_ising_partition_function = "140becfcb6bcb57895cc7e7935487608607e86e06242f6cf8e0beaf8896d0b04"
+3d_ising_partition_function = "6ab985667e7d2fd80a932b230c3c1a8fbf780c3b2833cb48d5734a54ae83d5c0"
 xxz = "bcbdc95e6f0d0e0586484807ea15693859d2573a006bfe2d89b2317ed3d334a4"
 fermi_hubbard = "f557ce22972d49ee3f2c17398b1f57214a010b0e1400b24803d0c744a353689f"

examples/heisenberg/main.jl

@@ -66,7 +66,7 @@ boundary_alg = (; tol = 1.0e-10, trunc = (; alg = :FixedSpaceTruncation));
 
 md"""
 Let us also configure the optimizer algorithm. We are going to optimize the PEPS using the
-L-BFGS optimizer from [OptimKit](https://github.com/Jutho/OptimKit.jl). Again, we specify
+[L-BFGS optimizer](@extref OptimKit.LBFGS) from [OptimKit](https://github.com/Jutho/OptimKit.jl). Again, we specify
 the convergence tolerance (for the gradient norm) as well as the maximal number of iterations
 and the BFGS memory size (which is used to approximate the Hessian):
 """

src/Defaults.jl

@@ -117,10 +117,10 @@ Module containing default algorithm parameter values and arguments.
 * `optimizer_tol=$(Defaults.optimizer_tol)` : Gradient norm tolerance of the optimizer.
 * `optimizer_maxiter=$(Defaults.optimizer_maxiter)` : Maximal number of optimization steps.
 * `optimizer_verbosity=$(Defaults.optimizer_verbosity)` : Optimizer output information verbosity.
-* `optimizer_alg=:$(Defaults.optimizer_alg)` : Default `OptimKit.OptimizerAlgorithm` for PEPS optimization.
-    - `:GradientDescent` : Gradient descent algorithm, see the [OptimKit README](https://github.com/Jutho/OptimKit.jl)
-    - `:ConjugateGradient` : Conjugate gradient algorithm, see the [OptimKit README](https://github.com/Jutho/OptimKit.jl)
-    - `:LBFGS` : L-BFGS algorithm, see the [OptimKit README](https://github.com/Jutho/OptimKit.jl)
+* `optimizer_alg=:$(Defaults.optimizer_alg)` : Default `OptimKit.OptimizationAlgorithm` for PEPS optimization.
+    - `:GradientDescent` : Gradient descent algorithm, OptimKit's [`GradientDescent`](@extref OptimKit.GradientDescent)
+    - `:ConjugateGradient` : Conjugate gradient algorithm, OptimKit's [`ConjugateGradient`](@extref OptimKit.ConjugateGradient)
+    - `:LBFGS` : L-BFGS algorithm, OptimKit's [`LBFGS`](@extref OptimKit.LBFGS)
 * `ls_maxiter=$(Defaults.ls_maxiter)` : Maximum number of iterations for the line search in each step of the optimization.
 * `ls_maxfg=$(Defaults.ls_maxfg)` : Maximum number of function evaluations for the line search in each step of the optimization.
 * `lbfgs_memory=$(Defaults.lbfgs_memory)` : Size of limited memory representation of BFGS Hessian matrix.

src/algorithms/optimization/peps_optimization.jl

@@ -132,9 +132,9 @@ The optimization parameters can be supplied via the keyword arguments or directl
     4. Debug info including AD outputs
 * `reuse_env::Bool=$(Defaults.reuse_env)` : If `true`, the current optimization step is initialized on the previous environment, otherwise a random environment is used.
 * `symmetrization::Union{Nothing,SymmetrizationStyle}=nothing` : Accepts `nothing` or a `SymmetrizationStyle`, in which case the PEPS and PEPS gradient are symmetrized after each optimization iteration.
-* `hasconverged=OptimKit.DefaultHasConverged(optimizer_alg.gradtol)` : Function specifying the convergence criterion with signature `bool = hasconverged(state, cost, grad, gradnorm)`, see [OptimKit.optimize](https://github.com/Jutho/OptimKit.jl/blob/master/src/OptimKit.jl) for specifics. Note that this overrides the default convergence criterion.
-* `shouldstop=OptimKit.DefaultShouldStop(optimizer_alg.maxiter)` : Function specifying the stopping criterion with signature `bool = shouldstop(state, cost, grad, numfg, iter, timespent)`, see [OptimKit.optimize](https://github.com/Jutho/OptimKit.jl/blob/master/src/OptimKit.jl) for specifics. Note that this overrides the default stopping criterion.
-* `(finalize!)=OptimKit._finalize!` : Inserts a `finalize!` function call after each optimization step by utilizing the `finalize!` kwarg of `OptimKit.optimize`. The function maps `(state, env), f, g = finalize!((state, env), cost, grad, numiter)`.
+* `hasconverged=OptimKit.DefaultHasConverged(optimizer_alg.gradtol)` : Function specifying the convergence criterion with signature `bool = hasconverged(state, cost, grad, gradnorm)`, see [`OptimKit.optimize`](@extref) for specifics. Note that this overrides the default convergence criterion.
+* `shouldstop=OptimKit.DefaultShouldStop(optimizer_alg.maxiter)` : Function specifying the stopping criterion with signature `bool = shouldstop(state, cost, grad, numfg, iter, timespent)`, see [`OptimKit.optimize`](@extref) for specifics. Note that this overrides the default stopping criterion.
+* `(finalize!)=OptimKit._finalize!` : Inserts a `finalize!` function call after each optimization step by utilizing the `finalize!` kwarg of [`OptimKit.optimize`](@extref). The function maps `(state, env), f, g = finalize!((state, env), cost, grad, numiter)`.
 
 ### Boundary algorithm
 
@@ -195,13 +195,13 @@ variational optimization, not for standalone [`leading_boundary`](@ref) calls.
 
 Supply the optimizer algorithm via `optimizer_alg::Union{NamedTuple,<:OptimKit.OptimizationAlgorithm}`
 using either a `NamedTuple` of keyword arguments or a `OptimKit.OptimizationAlgorithm` directly. By default,
-`OptimKit.LBFGS` is used in combination with a `HagerZhangLineSearch`. The supported
+[`OptimKit.LBFGS`](@extref) is used in combination with a [`HagerZhangLineSearch`](@extref OptimKit :jl:type:`OptimKit.HagerZhangLineSearch`). The supported
 keyword arguments are:
 
 * `alg::Symbol=:$(Defaults.optimizer_alg)` : Optimizer algorithm, can be one of the following:
-    - `:GradientDescent` : Gradient descent algorithm, see the [OptimKit README](https://github.com/Jutho/OptimKit.jl)
-    - `:ConjugateGradient` : Conjugate gradient algorithm, see the [OptimKit README](https://github.com/Jutho/OptimKit.jl)
-    - `:LBFGS` : L-BFGS algorithm, see the [OptimKit README](https://github.com/Jutho/OptimKit.jl)
+    - `:GradientDescent` : Gradient descent algorithm, OptimKit's [`GradientDescent`](@extref OptimKit.GradientDescent)
+    - `:ConjugateGradient` : Conjugate gradient algorithm, OptimKit's [`ConjugateGradient`](@extref OptimKit.ConjugateGradient)
+    - `:LBFGS` : L-BFGS algorithm, OptimKit's [`LBFGS`](@extref OptimKit.LBFGS)
 * `tol::Real=tol` : Gradient norm tolerance of the optimizer.
 * `maxiter::Int=$(Defaults.optimizer_maxiter)` : Maximal number of optimization steps.
 * `verbosity::Int=$(Defaults.optimizer_verbosity)` : Optimizer output verbosity.
@@ -433,7 +433,7 @@ end
 """
 $(TYPEDEF)
 
-Callable that acts as the `finalize!` function passed to `OptimKit.optimize`.
+Callable that acts as the `finalize!` function passed to [`OptimKit.optimize`](@extref).
 Keeps track of the optimization iteration number and gradient norm of the last accepted
 optimization step, and records the contraction metrics, gradient norms and execution times
 of each optimization step.