From 71b8e1c82e547e4e101d4bfd38a0e3d3682421da Mon Sep 17 00:00:00 2001
From: Michael Goerz <mail@michaelgoerz.net>
Date: Sat, 21 Sep 2024 16:17:30 -0400
Subject: [PATCH] Define Krotov-specific optimization functional

---
 docs/make.jl    | 30 ++++++++++++++++++++++++++----
 src/optimize.jl | 37 ++++++++++++++++++++++++++++++++++++-
 2 files changed, 62 insertions(+), 5 deletions(-)

diff --git a/docs/make.jl b/docs/make.jl
index 89c51ef..b8fe384 100644
--- a/docs/make.jl
+++ b/docs/make.jl
@@ -2,6 +2,7 @@ using QuantumControl
 using QuantumPropagators
 using Krotov
 using Documenter
+using Documenter.HTMLWriter: KaTeX
 using DocumenterCitations
 using DocumenterInterLinks
 using Pkg
@@ -22,6 +23,17 @@ if endswith(VERSION, "dev")
     DEV_OR_STABLE = "dev/"
 end
 
+
+function org_inv(pkgname)
+    objects_inv =
+        joinpath(@__DIR__, "..", "..", "$pkgname.jl", "docs", "build", "objects.inv")
+    if isfile(objects_inv)
+        return ("https://juliaquantumcontrol.github.io/$pkgname.jl/dev/", objects_inv,)
+    else
+        return "https://juliaquantumcontrol.github.io/$pkgname.jl/$DEV_OR_STABLE"
+    end
+end
+
 links = InterLinks(
     "Julia" => (
         "https://docs.julialang.org/en/v1/",
@@ -32,9 +44,9 @@ links = InterLinks(
         "https://github.com/KristofferC/TimerOutputs.jl",
         joinpath(@__DIR__, "src", "inventories", "TimerOutputs.toml")
     ),
-    "QuantumPropagators" => "https://juliaquantumcontrol.github.io/QuantumPropagators.jl/$DEV_OR_STABLE",
-    "QuantumControl" => "https://juliaquantumcontrol.github.io/QuantumControl.jl/$DEV_OR_STABLE",
-    "GRAPE" => "https://juliaquantumcontrol.github.io/GRAPE.jl/$DEV_OR_STABLE",
+    "QuantumPropagators" => org_inv("QuantumPropagators"),
+    "QuantumControl" => org_inv("QuantumControl"),
+    "GRAPE" => org_inv("GRAPE"),
     "Examples" => "https://juliaquantumcontrol.github.io/QuantumControlExamples.jl/$DEV_OR_STABLE",
     "ComponentArrays" => (
         "https://jonniedie.github.io/ComponentArrays.jl/stable/",
@@ -79,7 +91,17 @@ makedocs(;
             ),
         ],
         size_threshold_ignore=["externals.md"],
-        mathengine=KaTeX(),
+        mathengine=KaTeX(
+            Dict(
+                :macros => Dict(
+                    "\\Op" => "\\hat{#1}",
+                    "\\ket" => "\\vert#1\\rangle",
+                    "\\bra" => "\\langle#1\\vert",
+                    "\\Im" => "\\operatorname{Im}",
+                    "\\Re" => "\\operatorname{Re}",
+                ),
+            ),
+        ),
         footer="[$NAME.jl]($GITHUB) v$VERSION docs powered by [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl).",
     ),
     pages=PAGES,
diff --git a/src/optimize.jl b/src/optimize.jl
index c7803ff..f6ebcc6 100644
--- a/src/optimize.jl
+++ b/src/optimize.jl
@@ -20,7 +20,42 @@ result = optimize(problem; method=Krotov, kwargs...)
 ```
 
 optimizes the given control [`problem`](@ref QuantumControl.ControlProblem)
-using Krotov's method, returning a [`KrotovResult`](@ref).
+using Krotov's method, by minimizing the functional
+
+```math
+J(\{ϵ_l(t)\}) =
+    J_T(\{|Ψ_k(T)⟩\})
+    + ∑_l \int_{0}^{T} \frac{λ_{a,l}}{S_l(t)} [ϵ_l(t) - ϵ_l^{(0)}(t)]^2 \, dt\,,
+```
+
+cf. the [general form of a quantum control functional](@ref "Functional").
+The "reference field" ``ϵ_l^{(0)}(t)`` is the guess control for that particular
+iteration. The above functional implies a first-order update equation
+
+```math
+Δϵ_l(t) = \frac{S_l(t)}{λ_{a,l}} \Im ∑_k \left[
+\Big\langle
+    \chi_k^{(0)}(t)
+\Big\vert
+    \frac{\partial \hat{H}_k}{\partial ϵ_l(t)}
+\Big\vert
+    \Psi_k(t)
+\Big\rangle
+\right]\,,
+```
+
+where ``|\chi^{(0)}_k(t)⟩`` is the state backward-propagated under
+``Ĥ_k^{\dagger}(\{ϵ_l^{(0)}(t)\})`` with the boundary condition
+``|\chi_k(T)⟩ = \partial J_T / \partial ⟨Ψ_k^{(0)}(T)|`` and ``Ĥ_k`` is
+the `generator` of the ``k``'th trajectory.
+
+Note that the particular control-dependent running cost in the above functional
+is required to obtain the given Krotov update equation. Other running costs, or
+state-dependent running costs are not supported in this implementation of
+Krotov's method (even though *some* running costs are mathematically compatible
+with Krotov's method).
+
+Returns a [`KrotovResult`](@ref).
 
 Keyword arguments that control the optimization are taken from the keyword
 arguments used in the instantiation of `problem`; any of these can be overridden