libqasm 0.5.1

libQasm Python Package

libQASM: Library to parse cQASM v1.0 files

File organization

The original paper and BNF specification for the cQASM v1.0 are located in the doc/v10 directory. Please note however that the language has changed to some degree since then, and the qasm.bnf has never fully corresponded with the flex/bison grammar.

There are currently two C++ API versions contained in this repository: a new API (v1.2) and the original API (v1.0) maintained for backward compatibility purposes. The new API lives in v1x directories, and the older API in v10 directories.

• src/v1x: sources of the new API, and the grammar files for flex/bison.
• include/v1x: headers of the new API.
• include/v10: compatibility layer for the original API, now built on top of the new API instead of the original flex/bison parser.
• test/v1x: tests for the new API.
• test/v10: tests for the original API, as well as its Python bindings.

The following folders may be generated:

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

WIP: cQASM v3.0

We have started working on the parsing of cQASM v3.0 files, and that's why you will also see some v3x folders around.

However, the development of the new parser is still in a very early stage so its use through the API is completely unsupported.

Dependencies

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

ARM specific dependencies

We are having problems when using the m4 and zulu-opendjk Conan packages on an ARMv8 architecture. m4 is required by Flex/Bison and zulu-openjdk provides the Java JRE required by the ANTLR generator. So, for the time being, we are installing Flex/Bison and Java manually for this platform.

• Flex >= 2.6.4
• Bison >= 3.0
• Java JRE >= 11

Build

This version of libqasm can only be compiled via the Conan package manager. You'll 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/libqasm.git
cd libqasm
conan profile detect
conan build . -pr=conan/profiles/tests-debug -b missing

Notice:

• the conan profile command only has to be run only once, and not before every build.
• the conan build command is building libqasm 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...).

Build profiles

A group of predefined profiles is provided under the conan/profiles folder. They follow the [tests-](debug|release)[-compat] naming convention. For example:

• release is a Release build without tests and compatibility with the original API.
• tests-debug-compat is a Debug build with tests and compatibility enabled.

All the profiles set the C++ standard to 20. All the tests profiles enable Address Sanitizer.

Build options

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

conan build . -s:h compiler.cppstd=20 -s:h libqasm/*:build_type=Debug -o libqasm/*:asan_enabled=True -o libqasm/*:build_tests=True -o libqasm/*:compat=False -b missing

These are the list of options that could be specified whether in a profile or in the command line:

• libqasm/*:build_tests={True,False}: builds tests or not.
• libqasm/*:build_type={Debug,Release}: builds in debug or release mode.
• libqasm/*:asan_enabled={True,False}: enables Address Sanitizer.
• libqasm/*:compat={True,False}: enables installation of the headers for the original API, on top of the ones for the new API.
• libqasm/*:shared={True,False}: builds a shared object library instead of a static library, if applicable.

Install

From Python

Install from the project root directory as follows:

python3 -m pip install --verbose .

or if you'd rather use conda:

conda build python/conda
conda install libqasm --use-local

You can test if it works by running:

python3 -m pytest

From C++

The CMakeLists.txt file in the root directory includes install targets:

conan create --version 0.4.1 . -pr=tests-debug -b missing

You can test if it works by doing:

cd test/Debug
ctest -C Debug --output-on-failure

Use from another project

From Python

After installation, you should be able to use the bindings for the original API by just import libQasm. The new API doesn't have Python bindings yet.

From C++

The easiest way to use libqasm in a CMake project is to fetch the library and then link against it.

include(FetchContent)
FetchContent_Declare(cqasm
    GIT_REPOSITORY https://github.com/QuTech-Delft/libqasm.git
    GIT_TAG "<a given cqasm git tag>"
)
FetchContent_MakeAvailable(cqasm)
target_include_directories(<your target> SYSTEM PRIVATE "${cqasm_SOURCE_DIR}/include")
target_link_libraries(<your target> PUBLIC cqasm)

Note that the following dependencies are required for libqasm to build:

• Flex >= 2.6.4
• Bison >= 3.0
• Java JRE >= 11

The original API headers are not included by default. To enable those, pass -o libqasm/*:compat=True as a build option to Conan.

Docker

This tests the library in a container with the bare minimum requirements for libqasm.

docker build .

Note for Windows users: The above might fail on Windows to the autocrlf transformation that git does. If you are having trouble with this just create new clone of this repository using:

git clone --config core.autocrlf=input [e-mail]:QuTech-Delft/libqasm.git