Skip to content

Dev Guide

File organization

For development, see:

  • include/qx: public headers.
  • src/qx: source files.
  • src/qx-simulator: command line executable entry point.
  • test: test files.
  • python: SWIG interface.

For build process, continuous integration, and documentation:

  • conan: Conan profiles.
  • scripts: helper scripts used during the build process.
  • .github: GitHub Actions configuration files.
  • doc: documentation.

Build outputs may go into:

  • build/<build type>: the C++ library output files generated by Conan.
  • pybuild: the Python library output files generated by setup.py.

Dependencies

  • C++ compiler with C++23 support (gcc 11, clang 14, msvc 17)
  • CMake >= 3.12
  • git
  • Python 3.x plus pip, with the following package:
    • conan >= 2.0
  • SWIG

ARM builds

We are having problems when using the zulu-openjdk Conan package on an ARMv8 architecture. zulu-openjdk provides the Java JRE required by the ANTLR generator. For the time being, we install Java manually for this platform.

  • Java JRE >= 11

Documentation

  • doxygen
  • mkdocs with the following packages:
    • mike
    • mkdocs-material
    • mkdocstrings
    • pymdown-extensions

Linters

  • clang-format-18
  • clang-tidy-18

On a Linux machine, these linters can be installed with the following commands:

wget https://apt.llvm.org/llvm.sh -O llvm_install.sh
chmod +x llvm_install.sh
./llvm_install.sh
apt-get install -y clang-format-18 clang-tidy-18

Build

This version of QX simulator can only be compiled via the Conan package manager. You will need to create a default profile before using it for the first time.

The installation of dependencies, as well as the compilation, can be done in one go.

git clone https://github.com/QuTech-Delft/qx-simulator.git
cd qx-simulator
conan profile detect
conan build . -pr:a=conan/profiles/tests-debug -b missing

Note

  • the conan profile command has to be run only once, and not before every build.
  • the conan build command is building QX simulator in Debug mode with tests using the tests-debug profile.
  • the -b missing parameter asks conan to build packages from sources in case it cannot find the binary packages for the current configuration (platform, OS, compiler, build type...).

Profiles

A group of predefined profiles is provided under the conan/profiles folder.
They follow the [tests-](build_type)(-compiler)(-os)(-arch) naming convention:

  • tests: if tests are being built.
  • build_type: can be debug or release.
  • compiler: apple-clang, clang, gcc, msvc.
  • os: linux, macos, windows.
  • arch: arm64, x64.

All the profiles set the C++ standard to 23.
Address Sanitizer is currently disabled for all profiles.

Options

Profiles are a shorthand for command line options. The command above could be written, similarly, as:

conan build . -s:a compiler.cppstd=23 -s:a qx/*:build_type=Debug -c tools.build:skip_test=False -b missing

This is the list of options that could be specified either in a profile or in the command line:

  • qx/*:asan_enabled={True,False}: enables Address Sanitizer.
  • qx/*:build_type={Debug,Release}: builds in Debug or Release mode.

Tests are disabled by default. To enable them, use -c tools.build:skip_test=False.

Documentation

Build and serve on http://127.0.0.1:8000/.

export PYTHONPATH=./scripts/python
mkdocs serve

Note

The export is needed to point mkdocs to the custom handlers used for the C++ and Python APIs.

Linters

Continuous Integration will fail if the files do not adhere to a series of formatting and code style guidelines:

  • Formatting checks are defined in .clang-format.
  • Code style checks are defined in .clang-tidy.

It is recommended to run these linters before pushing any changes:

conan build . -pr:a=conan/profiles/tests-release-gcc-linux-x64 -b missing
python3 ./scripts/run_cpp_linters.py .

Note

  • The linters require clang-format-18 and clang-tidy-18.
  • It is mandatory to have a build before running the linters.
    • clang-tidy expects to find a compile_commands.json in a build folder.
  • It is recommended to build with gcc in Release mode.
    • We have observed clang-tidy fails to find some standard headers when compiling with clang.
    • run_cpp_linters.py can receive a build folder as second argument, but defaults to build/Release.

Simulator internals

Sparse state vector

QX simulator internally represents a quantum state using a hash table mapping kets (e.g., |0010110>) to their associated complex amplitudes, and omits zero (or near-zero) amplitudes.

You can read about this approach in this paper by Samuel Jaques and Thomas Häner. Note however that QX simulator was developed independently and the internal implementation differs.

Representing a quantum state in this way is, in many cases, very beneficial in terms of simulation runtime and memory usage.

Error models

Error models allow the introduction of probabilistic errors during the execution of the quantum circuit. They are useful for simulating more realistically a real quantum computer.

The only supported error model is currently the depolarizing channel. This model is implemented as described in Quantum Computation and Quantum Information by Nielsen & Chuang. Note that the book uses the density matrix/quantum computation formalism, while QX simulator only uses state vector simulation.

The model is parametrized by a probability of error p. Between each gate of the circuit, an error on a uniformly randomly chosen qubit is applied with probability p. The error is uniformly an X (bit-flip), Y, or Z (phase-flip) gate.

Warning

The current cQASM 3.0 language specification does not allow for the specification of an error model. Thus, while the QX simulator offers support for working with an error model, this feature cannot be exercised.