User guide docs

.github/workflows/deploy-mkdocs.yml

@@ -0,0 +1,35 @@
+name: Deploy MkDocs to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: |
+          pip install mkdocs pymdown-extensions mkdocs-bibtex mkdocs-macros-plugin mkdocs-jupyter
+
+      - name: Build MkDocs site
+        run: mkdocs build
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./site
+          keep_files: true  # Preserves existing files

README.md

@@ -9,10 +9,11 @@ realize a logical quantum operation, or state preparation that aims to drive the
 
 Quandary targets deployment on High-Performance Computing platforms, offering various levels for parallelization using the message passing paradigm. Quandary is written in C++ and executed by providing a text-based configuration file. Further, a Python interface is available to call the underlying C++ code from within a python interpreter, to ease usage.
 
-It is advised to look at the user guide in `doc/`, describing the underlying mathematical models, their implementation and usage in Quandary. 
-
 Feel free to reach out to Stefanie Guenther [guenther5@llnl.gov] for any question you may have. 
 
+# Documentation
+Both user and code documentation is available [here](https://software.llnl.gov/quandary).
+
 # Building
 Quandary uses CMake and [BLT](https://github.com/LLNL/blt) to handle builds. Since BLT is included as a
 submodule, first make sure you run:
@@ -152,8 +153,6 @@ See `tests/performance/README.md` for more information.
 
 Quandary is an open source project that is under heavy development. Contributions in all forms are very welcome, and can be anything from new features to bugfixes, documentation, or even discussions. Contributing is easy, work on your branch, create a pull request to `main` when you're good to go and the regression tests pass.
 
-Developer documentation is made with [Doxygen](https://www.doxygen.org) and is viewable [here](https://software.llnl.gov/quandary/doxygen).
-
 # Publications
 * S. Guenther, N.A. Petersson, J.L. DuBois: "Quantum Optimal Control for Pure-State Preparation Using One Initial State", AVS Quantum Science, vol. 3, arXiv preprint <https://arxiv.org/abs/2106.09148> (2021)
 * S. Guenther, N.A. Petersson, J.L. DuBois: "Quandary: An open-source C++ package for High-Performance Optimal Control of Open Quantum Systems", submitted to IEEE Supercomputing 2021, arXiv preprint <https://arxiv.org/abs/2110.10310> (2021)

docs/mkdocs/QuandaryWithPython_HowTo.ipynb

@@ -0,0 +1 @@
+../../examples/QuandaryWithPython_HowTo.ipynb

docs/mkdocs/config.md

@@ -0,0 +1,6 @@
+# Summary of all C++ configuration options
+Here is a list of all options available to the C++ Quandary code, this is the same as in `config_template.cfg`.
+
+```cfg
+--8<-- "config_template.cfg"
+```

docs/mkdocs/getting_started.md

@@ -0,0 +1,78 @@
+# Getting Started
+
+## Installation
+
+You have two options to install the Quandary binary:
+
+### Option 1: Install via Spack (Recommended)
+
+If you have [Spack](https://spack.readthedocs.io/en/latest/getting_started.html#installation) installed:
+```console
+spack install quandary
+```
+
+This automatically handles all dependencies including PETSc and MPI.
+
+### Option 2: Build from Source
+
+**Prerequisites for building from source:**
+
+- **PETSc** (Portable, Extensible Toolkit for Scientific Computation)
+- **MPI** implementation for parallel execution
+- **CMake** 3.23 or later
+- **C++ compiler** with C++14 support
+
+**Steps:**
+
+- Clone the repository:
+
+```console
+git clone https://github.com/LLNL/quandary.git
+cd quandary
+```
+
+- Follow the detailed build instructions in the [README.md](https://github.com/LLNL/quandary/blob/main/README.md)
+
+## Running
+
+### C++ Interface
+
+Test your installation with the provided template:
+```console
+./quandary config_template.cfg  # Serial execution
+mpirun -np 4 ./quandary config_template.cfg  # Parallel execution
+```
+
+Results are written as column-based text files in the output directory `data_out/`. The `config_template.cfg` is currently set to run a CNOT optimization test case. It lists all available options and configurations, and is filled with comments that should help users to set up new simulation and optimization runs, and match the input options to the equations found in this document.
+
+You can silence Quandary by adding the `--quiet` command line argument.
+
+### Python Interface
+
+For Python interface, after cloning quandary:
+```console
+pip install -e .
+```
+
+Test the Python interface with a working example:
+```console
+cd examples
+python example_cnot.py
+```
+
+This example demonstrates:
+
+- Setting up a 2-qubit system
+- Defining a CNOT gate target
+- Running optimization
+- Plotting results
+
+The output will show optimization progress and generate control pulse plots.
+
+## Next Steps
+
+- **[Examples](https://github.com/LLNL/quandary-examples/)**: Check out the quandary-examples repo
+- **[Jupyter Example](QuandaryWithPython_HowTo.ipynb)**: Check out the Jupyter Notebook Tutorial in these docs or in the above repo
+- **[User Guide](user_guide.md)**: Comprehensive documentation of Quandary's capabilities and details
+- **[C++ Config Reference](config.md)**: Reference listing configuration files in detail
+- **[Python API Reference](python_api.md)**: Reference listing the Python interface in detail

docs/mkdocs/index.md

@@ -0,0 +1,15 @@
+# Quandary: Optimal Control for Open and Closed Quantum Systems
+
+Quandary numerically simulates and optimizes the time evolution of closed and open quantum systems.
+
+## Basics
+
+- [Getting Started](getting_started.md)
+- [User Guide](user_guide.md) 
+- [Jupyter Notebook Tutorial](QuandaryWithPython_HowTo.ipynb)
+
+## Reference
+
+- [Python API Reference](python_api.md)
+- [C++ Config Reference](config.md)
+- [C++ Doxygen Documentation](https://software.llnl.gov/quandary/doxygen/)

docs/mkdocs/javascripts/mathjax.js

@@ -0,0 +1,26 @@
+window.MathJax = {
+  tex: {
+    tags: 'ams',  // Enable automatic equation numbering
+    processEscapes: true,
+    processEnvironments: true,
+    macros: {
+      Tr: "\\operatorname{Tr}",
+      Ell: "\\mathcal{L}",
+      R: "\\mathbb{R}",
+      N: "\\mathbb{N}",
+      C: "\\mathbb{C}",
+      bfa: "\\boldsymbol{\\alpha}",
+      bs: ["\\boldsymbol{#1}", 1]
+    }
+  },
+  options: {
+    ignoreHtmlClass: ".*|",
+    processHtmlClass: "arithmatex"
+  },
+  startup: {
+    ready: () => {
+      MathJax.startup.defaultReady();
+      console.log('MathJax is loaded and ready.');
+    }
+  }
+};

docs/mkdocs/python_api.md

@@ -0,0 +1,26 @@
+
+# Interfacing to Python environment
+The python interface eases the use of the C++ Quandary code, and adds additional functionality: 
+
+* Automatic estimation of the required time-step size based on eigenvalue decomposition of the system Hamiltonian
+* Automatic computation of carrier frequencies based on system transition frequencies (Hamiltonian eigenvalue differences)
+* Simulate and optimize with **custom system and control Hamiltonian operators**, other than the default model for superconducting quantum devices defined in [User Guide](user_guide.md). 
+
+All interface functions are defined in `./quandary.py`, which defines the `Quandary` dataclass that gathers all configuration options and sets default values. Default values are overwritten by user input either through the constructor call through `Quandary(<membervar>=<value>)` directly, or by accessing the member variables after construction and calling `update()` afterwards. A good place to get started is to look at the example `example_swap02.py`, or jump start with the [Jupyter Notebook Tutorial](QuandaryWithPython_HowTo.ipynb)
+
+Under the hood, the python interface dumps all configuration options to file and evokes (multiple) subprocesses that execute the C++ code on this configuration file. The C++ output files are loaded back into the python interpreter.
+It is therefore recommended to utilize the python interface only for smaller system sizes (fewer qubits), and switch to operate the C++ code directly when larger systems are considered (e.g. when parallel linear algebra is required.)
+
+### Custom Hamiltonian models 
+To enable custom Hamiltonians, pass the option `standardmodel=False` to the Quandary object and provide the complex-valued system Hamiltonian $H_d$ with `Hsys=<yourSystemHamiltonian>` as well as the real and imaginary parts of the custom control Hamiltonians per oscillator with `Hc_real=[<HcReal oscillator1, HcReal oscillator2, ...]` (will be multiplied by controls $p^k(t)$) `Hc_imag=[<HcImag oscillator1, HcImag oscillator2, ...]` (will be multiplied by controls $iq^k(t)$).
+
+  * The units of the system Hamiltonian should be angular frequency (multiply $2\pi$), whereas the control Hamiltonian operators should be 'unit-free', since those units come in through the multiplied control pulses $p$ and $q$.
+  * The control Hamiltonian operators are optional, but the system Hamiltonian is always required if `standardmodel=False`. 
+  * The matrix-free solver can not be used when custom Hamiltonians are provided. The code will therefore be slower.
+
+# Summary of all python interface options
+Here is a list of all options available to the python interface, including their default values. Use `help(Quandary)` to get additional information on available interface functions, such as `quandary.simulate(...)`, `quandary.optimize(...)`.
+
+```python
+--8<-- "quandary.py:13:100"
+```