From 9a943321025ba2e701cf7a747a178e1570ddd4aa Mon Sep 17 00:00:00 2001 From: leburgel Date: Wed, 14 Oct 2026 12:02:50 +0200 Subject: [PATCH] Add OptimKit interlinks and use @extref for OptimKit references --- docs/make.jl | 1 + .../3d_ising_partition_function/index.md | 10 +++++----- .../3d_ising_partition_function/main.ipynb | 10 +++++----- docs/src/examples/heisenberg/index.md | 2 +- docs/src/examples/heisenberg/main.ipynb | 2 +- examples/3d_ising_partition_function/main.jl | 10 +++++----- examples/Cache.toml | 4 ++-- examples/heisenberg/main.jl | 2 +- src/Defaults.jl | 8 ++++---- src/algorithms/optimization/peps_optimization.jl | 16 ++++++++-------- 10 files changed, 33 insertions(+), 32 deletions(-) diff --git a/docs/make.jl b/docs/make.jl index 9f82c9980..88b8b812b 100644 --- a/docs/make.jl +++ b/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 diff --git a/docs/src/examples/3d_ising_partition_function/index.md b/docs/src/examples/3d_ising_partition_function/index.md index 10b3f66e8..3df0dabc1 100644 --- a/docs/src/examples/3d_ising_partition_function/index.md +++ b/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 diff --git a/docs/src/examples/3d_ising_partition_function/main.ipynb b/docs/src/examples/3d_ising_partition_function/main.ipynb index 3a2adf36c..621613f77 100644 --- a/docs/src/examples/3d_ising_partition_function/main.ipynb +++ b/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." ] }, { diff --git a/docs/src/examples/heisenberg/index.md b/docs/src/examples/heisenberg/index.md index 24438b941..26fb8735a 100644 --- a/docs/src/examples/heisenberg/index.md +++ b/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): diff --git a/docs/src/examples/heisenberg/main.ipynb b/docs/src/examples/heisenberg/main.ipynb index 95a37a5f6..61164e5d6 100644 --- a/docs/src/examples/heisenberg/main.ipynb +++ b/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):" ] diff --git a/examples/3d_ising_partition_function/main.jl b/examples/3d_ising_partition_function/main.jl index e63afa667..9f148f500 100644 --- a/examples/3d_ising_partition_function/main.jl +++ b/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 diff --git a/examples/Cache.toml b/examples/Cache.toml index c617a4f4f..b8803ad0a 100644 --- a/examples/Cache.toml +++ b/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" diff --git a/examples/heisenberg/main.jl b/examples/heisenberg/main.jl index 948a8588a..6b9215b7c 100644 --- a/examples/heisenberg/main.jl +++ b/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): """ diff --git a/src/Defaults.jl b/src/Defaults.jl index 17c22c72d..da8afab9a 100644 --- a/src/Defaults.jl +++ b/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. diff --git a/src/algorithms/optimization/peps_optimization.jl b/src/algorithms/optimization/peps_optimization.jl index 634292d3e..a886bf82f 100644 --- a/src/algorithms/optimization/peps_optimization.jl +++ b/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.