Quandary simulates and optimizes the time evolution of closed and open quantum systems, given a Hamiltonian that models driven superconducting quantum devices. The underlying dynamics are modelled by either Schroedinger's equation (closed systems, state vector), or Lindblad's master equation (open systems, density matrix). Quandary solves the respective ordinary differential equation (ODE) numerically by applying a time-stepping integration scheme, and applies a gradient-based optimization scheme to design optimal control pulses that drive the quantum system to desired targets. The target can be a unitary gate, i.e. optimizing for pulses that realize a logical quantum operation, or state preparation that aims to drive the quantum system from one (or multiple) initial state to a desired target state, such as the ground state.
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 [[email protected]] for any question you may have.
Quandary uses CMake and BLT to handle builds. Since BLT is included as a submodule, first make sure you run:
git submodule init && git submodule update
This project relies on Petsc [https://petsc.org/release/] to handle (parallel) linear algebra. You can either use Spack to install Quandary alongside Petsc, or use CMake to install Quandary given an existing Petsc installation.
Spack can be used to install Quandary, including the required dependency on Petsc, as well as Python packages and interface.
-
To install Spack, clone the repo and add to your shell following the steps here.
-
To setup your compilers in your local Spack configuration:
spack compiler find -
To activate Quandary's spack environment, run the following in your local Quandary folder:
spack env activate .spack_env/ -
Trust Spack's binary mirror so we can speed up the installation process (optional):
spack buildcache keys --install --trust -
Finally, to install the necessary dependencies and build Quandary run:
spack installNote: This step could take a while the first time. The second time you run this is should be much faster, only looking for changes in the environment or local code.
Note that spack install will build Quandary using CMake from your local source code and install the binary in your Spack environment. To install Quandary's python interface and the python dependencies, use
pip install -e .
The Spack environment used to build Quandary is defined in .spack_env/spack.yaml.
You can add or remove packages from the specs list as needed or use different variants of these.
For instance, if you want to use the debug variant (which builds Petsc in debug mode) you can use quandary@develop+test+debug.
To use a specific version of Petsc instead of the latest release, you can do e.g. quandary@develop^[email protected].
The +test variant (by default on in .spack_env/spack.yaml) adds python and pip to the Spack environment.
This allows pip install to install python packages to your Spack virtual environment rather than a global one.
If you don't want to use Spack to install all dependencies as explained above, you can follow these steps to install Petsc yourself, and then use CMake to install Quandary using the existing Petsc intallation, see below.
On MacOS, you can brew install petsc, or check out [https://petsc.org/release/] for the latest installation guide. As a quick start, you can try this:
- Download tarball for Petsc here [https://ftp.mcs.anl.gov/pub/petsc/release-snapshots/] and extract
tar -xf petsc-<version>.tar.gz && cd petsc-<version> - Configure Petsc with
./configure. Check [https://petsc.org/release/install/install_tutorial] for optional arguments. For example,./configure --prefix=/YOUR/INSTALL/DIR --with-debugging=0 --with-fc=0 --with-cxx=mpicxx --with-cc=mpicc COPTFLAGS='-O3' CXXOPTFLAGS='-O3' - The output of
./configurereports on how to set thePETSC_DIRandPETSC_ARCHvariables. You can export them or just note them, they are only needed to configure CMake within the PkgConfig step below.export PETSC_DIR=/YOUR/INSTALL/DIRexport PETSC_ARCH=/YOUR/ARCH/PREFIX
- Compile petsc with `make all check'
Given an existing Petsc installation, located in $PETSC_DIR/$PETSC_ARCH, you can build Quandary directly with CMake.
First tell PkgConfig (used by CMake) where to find your Petsc installation:
export PKG_CONFIG_PATH=$PETSC_DIR/$PETSC_ARCH/lib/pkgconfig/:$PKG_CONFIG_PATH
Then build Quandary using:
mkdir build && cd build
cmake ..
make
Add the path to Quandary to your PATH variable with export PATH=/path/to/quandary/:$PATH, so your binary can be found.
Alternatively, you can install the Quandary executable in a specific path (such as the default /usr/local/bin to have it in your PATH automatically):
sudo cmake --install . --prefix /your/install/path
Create a virtual environment (e.g. with conda, venv, ...) and then use pip install -e . to install the python dependencies and activate Quandary's python interface. For example, for Conda environments, do:
conda create --name myenv
conda activate myenv
pip install -e .
Or for venv, do:
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
In additional to installing dependencies, the pip install command also enables that your python scripts can find Quandary's python interface functions, which are defined in quandary.py.
The C++ code builds into the executable quandary,
which takes one argument being the name of the test-case's configuration file. The file config_template.cfg, lists all possible configuration options and is filled with comments that should help users set up their own test case and match the options to the description in the user guide.
quandary config_template.cfg(serial execution)mpirun -np 4 quandary config_template.cfg(on 4 cores)
You can silence Quandary output by adding the --quiet argument to the above commands.
The examples/pythoninterface folder exemplifies the usage of Quandary's Python interface.
python example_cnot.py
Regression tests are defined in regression_tests/ and can be run with
pytest
See regression_tests/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.
- 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)
Quandary is distributed under the terms of the MIT license. All new contributions must be made under this license. See LICENSE, and NOTICE, for details.
SPDX-License-Identifier: MIT
