add unitary problem templates to docs

docs/Project.toml

@@ -3,9 +3,6 @@ Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
 LiveServer = "16fef848-5104-11e9-1b77-fb7a48bbb589"
 NamedTrajectories = "538bc3a1-5ab9-4fc3-b776-35ca1e893e08"
+PiccoloQuantumObjects = "5a402ddf-f93c-42eb-975e-5582dcda653d"
 QuantumCollocation = "0dc23a59-5ffb-49af-b6bd-932a8ae77adf"
-DirectTrajOpt = "2b384925-53cb-4042-a8d2-6faa627467e1"
 Revise = "295af30f-e4ad-537b-8983-00126c2a3abe"
-
-[compat]
-NamedTrajectories = "0.2"

docs/literate/man/ipopt_callbacks.jl → docs/dev/ipopt_callbacks.jl

@@ -1,9 +1,9 @@
 # ```@meta
 # CollapsedDocStrings = true
 # ```
-# # IpOpt Callbacks
+# # IPOPT Callbacks
 
-# This page describes the callback functions that can be used with the IpOpt solver (in the future, may describe more general callback behavior).
+# This page describes the callback functions that can be used with the IPOPT solver (in the future, may describe more general callback behavior).
 
 # ## Callbacks
 
@@ -13,7 +13,7 @@ using NamedTrajectories
 import ..QuantumStateSmoothPulseProblem
 import ..Callbacks
 
-# By default, IpOpt callbacks are called at each optimization step with the following signature:
+# By default, IPOPT callbacks are called at each optimization step with the following signature:
 function full_argument_list_callback(
     alg_mod::Cint,
     iter_count::Cint,

docs/literate/man/problem_templates.jl

@@ -1,19 +1,145 @@
 # ```@meta
 # CollapsedDocStrings = true
 # ```
+using NamedTrajectories
+using PiccoloQuantumObjects
+using QuantumCollocation
 
-# # Problem Templates
+#=
+# Problem Templates
 
-# We provide a number of problem templates for making it simple and easy to set up and solve certain types of quantum optimal control problems. These templates all construct a `DirectTrajOptProblem` object.  The problem templates are:
+We provide a number of problem templates for making it simple and easy to set up and solve 
+certain types of quantum optimal control problems. These templates all construct a 
+`DirectTrajOptProblem` object, which stores all the parts of the optimal control problem.
 
-# ## Unitary Smooth Pulse Problem
+This page provides a brief overview of each problem template, broken down by the state of
+the problem being solved.
 
-# ```@docs; canonical = false
-# UnitarySmoothPulseProblem
-# ```
+Unitary Problem Templates:
+- [Unitary Smooth Pulse Problem](#Unitary-Smooth-Pulse-Problem)
+- [Unitary Minimum Time Problem](#Unitary-Minimum-Time-Problem)
+- [Unitary Sampling Problem](#Unitary-Sampling-Problem)
 
-# ## Unitary Minimum Time Problem
+Ket Problem Templates:
+- [Quantum State Smooth Pulse Problem](#Quantum-State-Smooth-Pulse-Problem)
+- [Quantum State Minimum Time Problem](#Quantum-State-Minimum-Time-Problem)
+- [Quantum State Sampling Problem](#Quantum-State-Sampling-Problem)
+=#
 
-# ```@docs; canonical = false
-# UnitaryMinimumTimeProblem
-# ```
+# -----
+# ## Unitary Problem Templates
+
+#=
+#### Unitary Smooth Pulse Problem
+
+```@docs; canonical = false
+UnitarySmoothPulseProblem
+```
+
+Each problem starts with a `QuantumSystem` object, which is used to define the system's
+Hamiltonian and control operators. The goal is to find a control pulse that drives the
+system to a target unitary operator, `U_goal`. The problem is solved by minimizing the 
+difference between the target unitary and the unitary generated by the control pulse.
+=#
+
+system = QuantumSystem(0.1 * PAULIS.Z, [PAULIS.X, PAULIS.Y])
+U_goal = GATES.H
+T = 51
+Δt = 0.2
+
+prob = UnitarySmoothPulseProblem(system, U_goal, T, Δt); 
+
+# _check the fidelity before solving_
+println("Before: ", unitary_rollout_fidelity(prob.trajectory, system))
+
+# _finding an optimal control is as simple as calling `solve!`_
+solve!(prob, max_iter=100, verbose=true, print_level=1);
+
+# _check the fidelity after solving_
+println("After: ", unitary_rollout_fidelity(prob.trajectory, system))
+
+#=
+The `NamedTrajectory` object stores the control pulse, state variables, and the time grid.
+=#
+
+# _extract the control pulses_
+prob.trajectory.a |> size
+
+#=
+#### Unitary Minimum Time Problem
+
+```@docs; canonical = false
+UnitaryMinimumTimeProblem
+```
+
+The goal of this problem is to find the shortest time it takes to drive the system to a
+target unitary operator, `U_goal`. The problem is solved by minimizing the sum of all of 
+the time steps. It is constructed from `prob` in the previous example.
+=#
+
+min_prob = UnitaryMinimumTimeProblem(prob, U_goal);
+
+# _check the previous duration_
+println("Duration before: ", get_duration(prob.trajectory))
+
+# _solve the minimum time problem_
+solve!(min_prob, max_iter=100, verbose=true, print_level=1);
+
+# _check the new duration_
+println("Duration after: ", get_duration(min_prob.trajectory))
+
+# _the fidelity is preserved by a constraint_
+println("Fidelity after: ", unitary_rollout_fidelity(min_prob.trajectory, system))
+
+#=
+#### Unitary Sampling Problem 
+
+```@docs; canonical = false
+UnitarySamplingProblem
+```
+
+A sampling problem is used to solve over multiple quantum systems with the same control.
+This can be useful for exploring robustness, for example.
+=#
+
+# _create a sampling problem_
+driftless_system = QuantumSystem([PAULIS.X, PAULIS.Y])
+sampling_prob = UnitarySamplingProblem([system, driftless_system], U_goal, T, Δt);
+
+# _solve the sampling problem_
+solve!(sampling_prob, max_iter=100, verbose=true, print_level=1);
+
+# _new keys are addded to the trajectory for the new states_
+println(sampling_prob.trajectory.state_names)
+
+# _check the fidelity of the sampling problem_
+println("After on original system: ", unitary_rollout_fidelity(sampling_prob.trajectory, system, unitary_name=:Ũ⃗_system_1))
+println("After on new system: ", unitary_rollout_fidelity(sampling_prob.trajectory, driftless_system, unitary_name=:Ũ⃗_system_1))
+
+# _compare this to using the original problem on the new system_
+println("After on new system with original problem: ", unitary_rollout_fidelity(prob.trajectory, driftless_system))
+
+
+# -----
+# ## Ket Problem Templates
+
+#=
+#### Quantum State Smooth Pulse Problem
+```@docs; canonical = false
+QuantumStateSmoothPulseProblem
+```
+=#
+
+#=
+#### Quantum State Minimum Time Problem 
+```@docs; canonical = false
+QuantumStateMinimumTimeProblem
+```
+=#
+
+#=
+#### Quantum State Sampling Problem
+```@docs; canonical = false
+QuantumStateSamplingProblem
+```
+=#

docs/make.jl

@@ -16,12 +16,11 @@ open(joinpath(@__DIR__, "src", "index.md"), write = true) do io
     end
 end
 
+# TODO: Callbacks are currently broken
 pages = [
     "Home" => "index.md",
     "Manual" => [
         "Problem Templates" => "generated/man/problem_templates.md",
-        "Rollouts" => "generated/man/rollouts.md",
-        "Callbacks" => "generated/man/ipopt_callbacks.md",
     ],
     "Library" => "lib.md",
 ]

docs/src/index.md

@@ -0,0 +1,116 @@
+```@raw html
+<div align="center">
+  <a href="https://github.com/harmoniqs/Piccolo.jl">
+    <img src="assets/logo.svg" alt="Piccolo.jl" width="25%"/>
+  </a>
+</div>
+
+<div align="center">
+  <table>
+    <tr>
+      <td align="center">
+        <b>Documentation</b>
+        <br>
+        <a href="https://harmoniqs.github.io/QuantumCollocation.jl/stable/">
+          <img src="https://img.shields.io/badge/docs-stable-blue.svg" alt="Stable"/>
+        </a>
+        <a href="https://harmoniqs.github.io/QuantumCollocation.jl/dev/">
+          <img src="https://img.shields.io/badge/docs-dev-blue.svg" alt="Dev"/>
+        </a>
+        <a href="https://arxiv.org/abs/2305.03261">
+          <img src="https://img.shields.io/badge/arXiv-2305.03261-b31b1b.svg" alt="arXiv"/>
+        </a>
+      </td>
+      <td align="center">
+        <b>Build Status</b>
+        <br>
+        <a href="https://github.com/harmoniqs/QuantumCollocation.jl/actions/workflows/CI.yml?query=branch%3Amain">
+          <img src="https://github.com/harmoniqs/QuantumCollocation.jl/actions/workflows/CI.yml/badge.svg?branch=main" alt="Build Status"/>
+        </a>
+        <a href="https://codecov.io/gh/harmoniqs/QuantumCollocation.jl">
+          <img src="https://codecov.io/gh/harmoniqs/QuantumCollocation.jl/branch/main/graph/badge.svg" alt="Coverage"/>
+        </a>
+      </td>
+      <td align="center">
+        <b>License</b>
+        <br>
+        <a href="https://opensource.org/licenses/MIT">
+          <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="MIT License"/>
+        </a>
+      </td>
+      <td align="center">
+        <b>Support</b>
+        <br>
+        <a href="https://unitary.fund">
+          <img src="https://img.shields.io/badge/Supported%20By-Unitary%20Fund-FFFF00.svg" alt="Unitary Fund"/>
+        </a>
+      </td>
+    </tr>
+  </table>
+</div>
+
+<div align="center">
+  <i> Quickly set up and solve problem templates for quantum optimal control</i>
+  <br>
+</div>
+```
+
+# QuantumCollocation.jl
+
+**QuantumCollocation.jl** sets up and solves *quantum control problems* as nonlinear programs (NLPs). In this context, a generic quantum control problem looks like
+```math
+\begin{aligned}
+    \arg \min_{\mathbf{Z}}\quad & J(\mathbf{Z}) \\
+    \nonumber \text{s.t.}\qquad & \mathbf{f}(\mathbf{Z}) = 0 \\
+    \nonumber & \mathbf{g}(\mathbf{Z}) \le 0  
+\end{aligned}
+```
+where $\mathbf{Z}$ is a trajectory  containing states and controls, from [NamedTrajectories.jl](https://github.com/harmoniqs/NamedTrajectories.jl).
+
+### Problem Templates 
+
+*Problem Templates* are reusable design patterns for setting up and solving common quantum control problems. 
+
+For example, a *UnitarySmoothPulseProblem* is tasked with generating a *pulse* sequence $a_{1:T-1}$ in orderd to minimize infidelity, subject to constraints from the Schroedinger equation,
+```math
+    \begin{aligned}
+        \arg \min_{\mathbf{Z}}\quad & |1 - \mathcal{F}(U_T, U_\text{goal})|  \\
+        \nonumber \text{s.t.}
+        \qquad & U_{t+1} = \exp\{- i H(a_t) \Delta t_t \} U_t, \quad \forall\, t \\
+    \end{aligned}
+```
+while a *UnitaryMinimumTimeProblem* minimizes time and constrains fidelity,
+```math
+    \begin{aligned}
+        \arg \min_{\mathbf{Z}}\quad & \sum_{t=1}^T \Delta t_t \\
+        \qquad & U_{t+1} = \exp\{- i H(a_t) \Delta t_t \} U_t, \quad \forall\, t \\
+        \nonumber & \mathcal{F}(U_T, U_\text{goal}) \ge 0.9999
+    \end{aligned}
+```
+
+In each case, the dynamics between *knot points* $(U_t, a_t)$ and $(U_{t+1}, a_{t+1})$ are enforced as constraints on the states, which are free variables in the solver; this optimization framework is called *direct collocation*. For details of our implementation please see our award-winning IEEE QCE 2023 paper, [Direct Collocation for Quantum Optimal Control](https://arxiv.org/abs/2305.03261). If you use QuantumCollocation.jl in your work, please cite :raised_hands:!
+
+Problem templates give the user the ability to add other constraints and objective functions to this problem and solve it efficiently using [Ipopt.jl](https://github.com/jump-dev/Ipopt.jl) and [MathOptInterface.jl](https://github.com/jump-dev/MathOptInterface.jl) under the hood.
+
+## Installation
+
+This package is registered! To install, enter the Julia REPL, type `]` to enter pkg mode, and then run:
+```julia
+pkg> add QuantumCollocation
+```
+
+## Example
+
+### Single Qubit Hadamard Gate
+```Julia
+using QuantumCollocation
+
+T = 50
+Δt = 0.2
+system = QuantumSystem([PAULIS[:X], PAULIS[:Y]])
+U_goal = GATES.H
+
+# Hadamard Gate
+prob = UnitarySmoothPulseProblem(system, U_goal, T, Δt)
+solve!(prob, max_iter=100)
+```

docs/src/lib.md

@@ -10,16 +10,6 @@ Modules = [QuantumCollocation.ProblemTemplates]
 Modules = [QuantumCollocation.Options]
 ```
 
-## Rollouts
-```@autodocs
-Modules = [QuantumCollocation.Rollouts]
-```
-
-## Direct Sums
-```@autodocs
-Modules = [QuantumCollocation.DirectSums]
-```
-
 ## Trajectory Initialization
 ```@autodocs
 Modules = [QuantumCollocation.TrajectoryInitialization]