# API

`Krotov.KrotovResult`

— TypeResult object returned by `optimize_krotov`

.

**Attributes**

The attributes of a `KrotovResult`

object include

`iter`

: The number of the current iteration`J_T`

: The value of the final-time functional in the current iteration`J_T_prev`

: The value of the final-time functional in the previous iteration`tlist`

: The time grid on which the control are discretized.`guess_controls`

: A vector of the original control fields (each field discretized to the points of`tlist`

)`optimized_controls`

: A vector of the optimized control fields. Calculated only at the end of the optimization, not after each iteration.`tau_vals`

: For any trajectory that defines a`target_state`

, the complex overlap of that target state with the propagated state. For any trajectory for which the`target_state`

is`nothing`

, the value is zero.`records`

: A vector of tuples with values returned by a`callback`

routine passed to`optimize`

`converged`

: A boolean flag on whether the optimization is converged. This may be set to`true`

by a`check_convergence`

function.`message`

: A message string to explain the reason for convergence. This may be set by a`check_convergence`

function.

All of the above attributes may be referenced in a `check_convergence`

function passed to `optimize(problem; method=Krotov)`

`Krotov.KrotovWrk`

— TypeKrotov workspace.

The workspace is for internal use. However, it is also accessible in a `callback`

function. The callback may use or modify some of the following attributes:

`trajectories`

: a copy of the trajectories defining the control problem`adjoint_trajectories`

: The`trajectories`

with the adjoint generator`kwargs`

: The keyword arguments from the`ControlProblem`

or the call to`optimize`

.`controls`

: A tuple of the original controls (probably functions)`ga_a_int`

: The current value of $∫gₐ(t)dt$ for each control`update_shapes`

: The update shapes $S(t)$ for each pulse, discretized on the intervals of the time grid.`lambda_vals`

: The current value of λₐ for each control`result`

: The current result object`fw_storage`

: The storage of states for the forward propagation`fw_propagators`

: The propagators used for the forward propagation`bw_propagators`

: The propagators used for the backward propagation`use_threads`

: Flag indicating whether the propagations are performed in parallel.

`Krotov.optimize_krotov`

— Method`QuantumControl.optimize`

— Method```
using Krotov
result = optimize(problem; method=Krotov, kwargs...)
```

optimizes the given control `problem`

using Krotov's method, by minimizing the functional

\[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. The "reference field" $ϵ_l^{(0)}(t)$ is the guess control for that particular iteration. The above functional implies a first-order update equation

\[Δϵ_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`

.

Keyword arguments that control the optimization are taken from the keyword arguments used in the instantiation of `problem`

; any of these can be overridden with explicit keyword arguments to `optimize`

.

**Required problem keyword arguments**

`J_T`

: A function`J_T(Ψ, trajectories)`

that evaluates the final time functional from a list`Ψ`

of forward-propagated states and`problem.trajectories`

. The function`J_T`

may also take a keyword argument`tau`

. If it does, a vector containing the complex overlaps of the target states (`target_state`

property of each trajectory in`problem.trajectories`

) with the propagated states will be passed to`J_T`

.

**Recommended problem keyword arguments**

`lambda_a=1.0`

: The inverse Krotov step width λₐ for every pulse.`update_shape=(t->1.0)`

: A function`S(t)`

for the "update shape" that scales the update for every pulse.

If different controls require different `lambda_a`

or `update_shape`

, a dict `pulse_options`

must be given instead of a global `lambda_a`

and `update_shape`

; see below.

**Optional problem keyword arguments**

The following keyword arguments are supported (with default values):

`pulse_options`

: A dictionary that maps every control (as obtained by`get_controls`

from the`problem.trajectories`

) to the following dict:`:lambda_a`

: The value for inverse Krotov step width λₐ.`:update_shape`

: A function`S(t)`

for the "update shape" that scales the Krotov pulse update.

This overrides the global

`lambda_a`

and`update_shape`

arguments.`chi`

: A function`chi(Ψ, trajectories)`

that receives a list`Ψ`

of the forward propagated states and returns a vector of states $|χₖ⟩ = -∂J_T/∂⟨Ψₖ|$. If not given, it will be automatically determined from`J_T`

via`make_chi`

with the default parameters. Similarly to`J_T`

, if`chi`

accepts a keyword argument`tau`

, it will be passed a vector of complex overlaps.`sigma=nothing`

: A function that calculates the second-order contribution. If not given, the first-order Krotov method is used.`iter_start=0`

: The initial iteration number.`iter_stop=5000`

: The maximum iteration number.`prop_method`

: The propagation method to use for each trajectory; see below.`print_iters=true`

: Whether to print information after each iteration.`store_iter_info=Set()`

: Which fields from`print_iters`

to store in`result.records`

. A subset of`Set(["iter.", "J_T", "∫gₐ(t)dt", "J", "ΔJ_T", "ΔJ", "secs"])`

.`callback`

: A function (or tuple of functions) that receives the Krotov workspace, the iteration number, the list of updated pulses, and the list of guess pulses as positional arguments. The function may return a tuple of values which are stored in the`KrotovResult`

object`result.records`

. The function can also mutate any of its arguments, in particular the updated pulses. This may be used, e.g., to apply a spectral filter to the updated pulses or to perform similar manipulations. Note that`print_iters=true`

(default) adds an automatic callback to print information after each iteration. With`store_iter_info`

, that callback automatically stores a subset of the printed information.`check_convergence`

: A function to check whether convergence has been reached. Receives a`KrotovResult`

object`result`

, and should set`result.converged`

to`true`

and`result.message`

to an appropriate string in case of convergence. Multiple convergence checks can be performed by chaining functions with`∘`

. The convergence check is performed after any`callback`

.`verbose=false`

: If`true`

, print information during initialization.`rethrow_exceptions`

: By default, any exception ends the optimization but still returns a`KrotovResult`

that captures the message associated with the exception. This is to avoid losing results from a long-running optimization when an exception occurs in a later iteration. If`rethrow_exceptions=true`

, instead of capturing the exception, it will be thrown normally.

**Trajectory propagation**

Krotov's method involves the forward and backward propagation for every `Trajectory`

in the `problem`

. The keyword arguments for each propagation (see `propagate`

) are determined from any properties of each `Trajectory`

that have a `prop_`

prefix, cf. `init_prop_trajectory`

.

In situations where different parameters are required for the forward and backward propagation, instead of the `prop_`

prefix, the `fw_prop_`

and `bw_prop_`

prefixes can be used, respectively. These override any setting with the `prop_`

prefix. This applies both to the properties of each `Trajectory`

and the problem keyword arguments.

Note that the propagation method for each propagation must be specified. In most cases, it is sufficient (and recommended) to pass a global `prop_method`

problem keyword argument.