-
Notifications
You must be signed in to change notification settings - Fork 9
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #178 from kestrelquantum/feature/mutlidocs-refactor
Feature/mutlidocs refactor
- Loading branch information
Showing
35 changed files
with
216 additions
and
2,511 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,128 +1,116 @@ | ||
| # QuantumCollocation.jl | ||
|
|
||
| <div align="center"> <a href="https://github.com/kestrelquantum/Piccolo.jl"> | ||
| <img src="docs/src/assets/logo.svg" alt="logo" width="35%"/> | ||
| </a> </div> | ||
|
|
||
|
|
||
| <!--```@raw html--> | ||
| <div align="center"> | ||
| <a href="https://github.com/kestrelquantum/Piccolo.jl"> | ||
| <img src="assets/logo.svg" alt="Piccolo.jl" width="25%"/> | ||
| </a> | ||
| </div> | ||
|
|
||
| | **Documentation** | **Build Status** | **Support** | **Paper** | **License** | | ||
| |:-----------------:|:----------------:|:-----------:|:---------:|:-----------:| | ||
| | [](https://kestrelquantum.github.io/QuantumCollocation.jl/dev/) | [](https://github.com/kestrelquantum/QuantumCollocation.jl/actions/workflows/CI.yml?query=branch%3Amain) [](https://codecov.io/gh/kestrelquantum/QuantumCollocation.jl)| [](https://unitary.fund) | [](https://arxiv.org/abs/2305.03261) | [](https://opensource.org/licenses/MIT) | ||
|
|
||
|
|
||
| <div align="center"> | ||
| <table> | ||
| <tr> | ||
| <td align="center"> | ||
| <b>Documentation</b> | ||
| <br> | ||
| <a href="https://kestrelquantum.github.io/QuantumCollocation.jl/stable/"> | ||
| <img src="https://img.shields.io/badge/docs-stable-blue.svg" alt="Stable"/> | ||
| </a> | ||
| <a href="https://kestrelquantum.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/kestrelquantum/QuantumCollocation.jl/actions/workflows/CI.yml?query=branch%3Amain"> | ||
| <img src="https://github.com/kestrelquantum/QuantumCollocation.jl/actions/workflows/CI.yml/badge.svg?branch=main" alt="Build Status"/> | ||
| </a> | ||
| <a href="https://codecov.io/gh/kestrelquantum/QuantumCollocation.jl"> | ||
| <img src="https://codecov.io/gh/kestrelquantum/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** uses [NamedTrajectories.jl](https://github.com/kestrelquantum/NamedTrajectories.jl) to set up and solve direct collocation problems specific to quantum optimal control, i.e. generating a *pulse* sequence $a_{1:T-1}$ to drive a quantum system and realize a target gate $U_{\text{goal}}$. We formulate this problem as a nonlinear program (NLP) of the form | ||
| # 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} | ||
| \underset{U, a, \Delta t}{\text{minimize}} & \quad \ell(U_T, U_{\text{goal}})\\ | ||
| \text{ subject to } & \quad U_{t+1} = \exp(-i \Delta t H(a_t)) U_t | ||
| \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/kestrelquantum/NamedTrajectories.jl). | ||
|
|
||
| Where 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 | ||
|
|
||
| QuantumCollocation.jl gives 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. | ||
| *Problem Templates* are reusable design patterns for setting up and solving common quantum control problems. | ||
|
|
||
| ## :warning: Notice :warning: | ||
| 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} | ||
| ``` | ||
|
|
||
| This package is under active development and issues may arise -- please be patient and report any issues you find! | ||
| 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:! | ||
|
|
||
| ## Installation | ||
| 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. | ||
|
|
||
| QuantumCollocation.jl is registered! To install: | ||
| ## Installation | ||
|
|
||
| This package is registered! To install, enter the Julia REPL, type `]` to enter pkg mode, and then run: | ||
| ```julia | ||
| using Pkg | ||
| Pkg.add(QuantumCollocation) | ||
| pkg> add QuantumCollocation | ||
| ``` | ||
|
|
||
| ## Example | ||
|
|
||
| ### Single Qubit X-Gate | ||
| ### 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, GATES[:H], T, Δt) | ||
| prob = UnitarySmoothPulseProblem(system, U_goal, T, Δt) | ||
| solve!(prob, max_iter=100) | ||
|
|
||
| plot_unitary_populations(prob) | ||
| ``` | ||
|  | ||
|
|
||
| ## Quickstart developers guide | ||
|
|
||
| __Install Julia__ [Juliaup](https://github.com/JuliaLang/juliaup) is an installer and version manager. This is one useful way to manage Julia versions and keep up with the latest changes. After installing, run `julia` to obtain the Julia _REPL_. | ||
|
|
||
| __Julia environments__ | ||
| [(Documentation)](https://pkgdocs.julialang.org/v1/environments/#Using-someone-else's-project) Your project's environment is stored in _Project.toml_. You can interactively add packages to an environment by using the Julia command line _REPL_ and _package manager_. Start Julia in the project folder. Type `]` to enter the package manager. Type `activate .` to activate or create an environment specified by _Project.toml_ located in the current folder. Separately, you generate a manifest (solving the versions to create a valid environment) by running `instantiate`; instantiate will check that the environment is correct after you add all the packages you want. | ||
|
|
||
| __Adding packages__ | ||
| [(Documentation)](https://pkgdocs.julialang.org/v1/managing-packages/#Adding-packages) The initial cell for a Piccolo notebook might look something like the following: | ||
| ```Julia | ||
| # Standard packages | ||
| using LinearAlgebra | ||
| using CairoMakie | ||
|
|
||
| # Piccolo packages | ||
| using QuantumCollocation | ||
| using NamedTrajectories | ||
| using TrajectoryIndexingUtils | ||
| ``` | ||
|
|
||
| First, let's install some standard packages (these are like Numpy and Matplotlib). Open the package manager in the current environment (type `julia`, `]`, and `activate .`), type `add LinearAlgebra` to install and precompile _LinearAlgebra_. Same with `CairoMakie`. | ||
|
|
||
| Second, let's install _Piccolo_. There are three packages (_QuantumCollocation_, _NamedTrajetories_, _TrajectoryIndexingUtils_) inside [Piccolo](https://docs.juliahub.com/General/Piccolo/stable/). We could do `add Piccolo` to get the three as a bundle from the Julia repository. Instead of individually calling `using ...` for each, this approach only requires `using Piccolo` at the start of a file or notebook. | ||
|
|
||
| As a developer, we want to use the git repositories directly from [the Kestrel Quantum Github page](https://github.com/kestrelquantum). Clone, then add the local packages to the Project file with e.g. `dev ../relative/path/to/repo/QuantumCollocation`. This command installs the development version of _QuantumCollocation_ pointing to the local Github code instead of the package repository. You can repeat this for the others, also. | ||
|
|
||
| __Developing__ | ||
| [Revise.jl](https://timholy.github.io/Revise.jl/stable/) will let you edit source code, update packages, and reload the changes in a notebook---automatically! This is a great tool for development. `add Revise` from the REPL and then include it before any packages you intend to edit: | ||
| ```Julia | ||
| using Revise | ||
| using QuantumCollocation | ||
| ``` | ||
|
|
||
| ### Documentation | ||
|
|
||
| Documentation is built using [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl) and uses [Literate.jl](https://github.com/fredrikekre/Literate.jl) to generate markdown files from scripts stored in [docs/literate](docs/literate). To build the documentation locally, start julia with the docs environment: | ||
|
|
||
| ```bash | ||
| julia --project=docs | ||
| ``` | ||
|
|
||
| Then run the following commands in the Julia REPL: | ||
|
|
||
| ``` | ||
| ] instantiate | ||
| ``` | ||
|
|
||
| Then (for ease of development) load the following packages: | ||
|
|
||
| ```julia | ||
| using Revise, LiveServer, QuantumCollocation | ||
| ``` | ||
|
|
||
| To live-serve the docs, run | ||
| ```julia | ||
| servedocs(literate_dir="docs/literate", skip_dir="docs/src/generated") | ||
| ``` | ||
|
|
||
| Changes made to files in the docs directory should be automatically reflected in the live server. To reflect changes in the source code (e.g. doc strings), since we are using Revise, simply kill the live server running in the REPL (with, e.g., Ctrl-C) and restart it with the above command. | ||
|
|
||
| ### Tips for Visual Studio Code | ||
| __Julia extension__ You can run Julia notebooks and much more with [the Julia extension](https://code.visualstudio.com/docs/languages/julia). Upon opening your project folder in VS code and attempting to run an `.ipynb`, you will see that VS Code finds the interpreters managed by juliaup and defaults to using the environment based on the _Project.toml_ in the project directory. | ||
|
|
||
| __Fonts__ VS Code will not display all characters allowed by Julia. You can change the editor font family in the settings to `'JuliaMono'` to get full support. If you don't want to mix and mash, you can create a new VS Code settings profile for working in Julia at _File>Preferences>Profile_. | ||
|
|
||
| __Tests__ Tests should automatically populate in VS Code when working with a Piccolo package. For example, just by adding the `QuantumCollocation.jl` folder to your workspace, you should see tests appear if you click on the _Testing_ sidebar icon. If you run one of these tests, a new Julia kernel is spawned for the test. You can find the kernel if you click on the _Julia_ sidebar icon (after installing the Julia extensions). Sometimes, for the tests to recognize new changes, you may need to manually kill this kernel to see your changes reflected. | ||
|
|
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Oops, something went wrong.