void register_instruction(const std::string& name, const std::string& param_types);void register_instruction(const std::string& name, const std::optional<std::string>& param_types);Registers an instruction type.
The param_types can be:
libQASM is a library to parse cQASM programs, developed by QuTech.
At the moment, libQASM only supports cQASM v3.0 programs (see cQASM-spec for the language specification).
It performs lexical, syntactic, and semantic analysis of an input program received via a file or a string. It produces one of the following results:
It can be used from:
Check out QX simulator and OpenSquirrel compiler for an example of use in a C++ and a Python project, respectively.
"},{"location":"about/authors.html","title":"Authors","text":"libQASM is developed as part of the Quantum Inspire project: support@quantum-inspire.com
"},{"location":"about/contributing.html","title":"Contributing","text":"Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.
If you have a suggestion that would make this better, please fork the repo and create a pull request.
git checkout -b feature/AmazingFeature).git commit -m 'Add some AmazingFeature').git push origin feature/AmazingFeature).libQASM is licensed under the Apache License, Version 2.0. See LICENSE for the full license text.
"},{"location":"about/release-notes.html","title":"Release Notes","text":"Coming soon
"},{"location":"api/cpp.html","title":"C++","text":"libQASM C++ API is defined in include/v3x/cqasm-py.hpp.
The only exported class is V3xAnalyzer. This is actually a C++ class that works as a binding for accessing C++ code from Python.
class V3xAnalyzer;Main class for parsing and analyzing cQASM v3.0 files.
This class works as a binding for accessing C++ code from Python.
The parsing methods are static because they do not change the status of the analyzer. Instead, they just invoke free functions that create a temporary instance of a parser.
None of the parsing or the analyzing methods perform any version check.
parse_file, parse_string, analyze_file, and analyze_string:
Return a vector of strings. The first string is reserved for the CBOR serialization of the syntactic/semantic (in the case of parsing/analyzing) Abstract Syntax Tree (AST) of the input program. Any additional strings represent error messages. Notice that the AST and error messages will not be available at the same time.
parse_file_to_json, parse_string_to_json, analyze_file_to_json, and analyze_string_to_json:
Return a string in JSON format. If the parsing was successful, that string contains a JSON representation of the AST of the input program. Otherwise, it will contain a list of errors. The JSON representation of each error follows the Language Server Protocol (LSP) specification. Every error is mapped to an LSP Diagnostic structure: severity is hardcoded to 1 at the moment (value corresponding to an Error level).
parse_string, parse_string_to_json, analyze_string, andanalyze_string_to_json`:
have an optional second argument: file_name. It is only used when reporting errors.
Example:
auto result = analyze_file(\"grover.cq\");\nauto program = std::string{ R\"(\n version 3.0\n qubit[2] q\n bit[2] b\n H q[0]\n CNOT q[0], q[1]\n b = measure q\n)\" };\nauto result = parse_string_to_json(program, \"bell.cq\");\nstatic std::vector<std::string> parse_file(const std::string& file_name);Parses a file containing a cQASM v3.0 program.
static std::string parse_file_to_json(const std::string& file_name);Parses a file containing a cQASM v3.0 program.
static std::vector<std::string> parse_string(const std::string& data, const std::string& file_name);Parses a string containing a cQASM v3.0 program.
file_name is optional. It is only used when reporting errors.
static std::string parse_string_to_json(const std::string& data, const std::string& file_name);Parses a string containing a cQASM v3.0 program.
file_name is optional. It is only used when reporting errors.
V3xAnalyzer(const std::string& max_version, bool without_defaults);Creates a new cQASM v3.0 semantic analyzer.
max_version is optional. It has a default value of 3.0. The maximum cQASM version supported by the analyzer.
without_defaults is optional. If set, the default instruction set is not loaded into the instruction table, so you have to specify the entire instruction set using register_instruction(). Otherwise, those functions only add to the defaults.
The initial mappings and functions are not configurable. The defaults for these are always used.
~V3xAnalyzer();Default destructor.
void register_instruction(const std::string& name, const std::string& param_types);Registers an instruction type.
The param_types can be:
Q = qubit.
V = qubit array.
B = bit.
W = bit array.
i = int.
f = float.
Example:
register_instruction(\"H\", \"Q\");\nstd::vector<std::string> analyze_file(const std::string& file_name);Parses and analyzes a file containing a cQASM v3.0 program.
std::string analyze_file_to_json(const std::string& file_name);Parses and analyzes a file containing a cQASM v3.0 program.
std::vector<std::string> analyze_string(const std::string& data, const std::string& file_name);Parses and analyzes a string containing a cQASM v3.0 program.
file_name is optional. It is only used when reporting errors.
std::string analyze_string_to_json(const std::string& data, const std::string& file_name);Parses and analyzes a string containing a cQASM v3.0 program.
file_name is optional. It is only used when reporting errors.
libQASM is also deployed as an Emscripten binary with a Typescript frontend.
libQASM Typescript API is defined in emscripten/emscripten_wrapper.hpp.
The only exported class is EmscriptenWrapper. This is actually a C++ class that works as a binding for accessing C++ code from Typescript.
struct EmscriptenWrapper;Main class for parsing and analyzing cQASM files.
This class works as a binding for accessing C++ code from Typescript.
Example:
import { default as wrapper } from 'cqasm_emscripten.mjs';\n\nwrapper().then(function(result: any) {\n let cqasm = new result[\"EmscriptenWrapper\"]()\n let program = ...\n let output = cqasm.parse_string_to_json(program, ...)\n cqasm.delete()\n}).catch((error: any) => {\n console.error(\"unhandledRejection\", error, \"\\n\");\n});\nstd::string get_version();Returns the version of the libqasm library.
Example:
let version = cqasm.get_version()\nstd::string parse_string_to_json(const std::string& data, const std::string& file_name);Parses a string containing a cQASM v3.0 program.
No version check is performed.
The file_name is only used when reporting errors.
Returns a string. If the parsing was successful, the string contains a syntactic Abstract Syntax Tree (AST). Otherwise, it will contain a list of errors. The JSON representation of each error follows the Language Server Protocol (LSP) specification. Every error is mapped to an LSP Diagnostic structure: severity is hardcoded to 1 at the moment (value corresponding to an Error level).
Example:
let program = `\n version 3\n qubit[2] q\n bit[2] b\n H q[0]\n CNOT q[0], q[1]\n b = measure q\n`\nlet output = parse_string_to_json(program, \"bell.cq\")\nstd::string analyze_string_to_json(const std::string& data, const std::string& file_name);Parses and analyzes a string containing a cQASM v3.0 program.
No version check is performed.
The file_name is only used when reporting errors.
Returns a string. If the parsing was successful, the string contains a semantic Abstract Syntax Tree (AST). Otherwise, it will contain a list of errors. The JSON representation of each error follows the Language Server Protocol (LSP) specification. Every error is mapped to an LSP Diagnostic structure: severity is hardcoded to 1 at the moment (value corresponding to an Error level).
Example:
let program = `\n version 3\n qubit[2] q\n bit[2] b\n H q[0]\n CNOT q[0], q[1]\n b = measure q\n`\nlet output = analyze_string_to_json(program, \"bell.cq\")\nlibQASM Python API is defined in python/module/cqasm/v3x/__init__.py.
The only exported class is Analyzer. This is actually a Python class that works as a binding for accessing C++ code from Python.
class AnalyzerMain class for parsing and analyzing cQASM v3.0 files.
This class works as a binding for accessing C++ code from Python.
The parsing methods are static because they do not change the status of the analyzer. Instead, they just invoke free functions that create a temporary instance of a parser.
None of the parsing or the analyzing methods perform any version check.
parse_file, parse_string, analyze_file, and analyze_string:
return a vector of strings. If the length of the vector is 1, the string is a serialization of the syntactic/semantic (in the case of parsing/analyzing) Abstract Syntax Tree (AST) of the input program. Otherwise, it is a list of errors.
parse_file_to_json, parse_string_to_json, analyze_file_to_json, and analyze_string_to_json:
return a string in JSON format. If the parsing was successful, the string contains a JSON representation of the AST of the input program. Otherwise, it will contain a list of errors. The JSON representation of each error follows the Language Server Protocol (LSP) specification. Every error is mapped to an LSP Diagnostic structure: severity is hardcoded to 1 at the moment (value corresponding to an Error level).
parse_string, parse_string_to_json, analyze_string, andanalyze_string_to_json`:
have an optional second argument: file_name. It is only used when reporting errors.
Example:
result = libqasm.analyze_file(\"grover.cq\")\nprogram = r'''\n version 3.0\n qubit[2] q\n bit[2] b\n H q[0]\n CNOT q[0], q[1]\n b = measure q\n'''\nresult = libqasm.parse_string_to_json(program, \"bell.cq\")\n@staticmethod\nparse_file(*args) -> list[str]:Parses a file containing a cQASM v3.0 program.
@staticmethod\nparse_file_to_json(*args) -> str:Parses a file containing a cQASM v3.0 program.
@staticmethod\nparse_string(*args) -> list[str]:Parses a string containing a cQASM v3.0 program.
@staticmethod\nparse_string_to_json(*args) -> str:Parses a string containing a cQASM v3.0 program.
analyze_file(self, *args) -> list[str]:Parses and analyzes a file containing a cQASM v3.0 program.
analyze_file_to_json(self, *args) -> str:Parses and analyzes a file containing a cQASM v3.0 program.
analyze_string(self, *args) -> list[str]:Parses and analyzes a string containing a cQASM v3.0 program.
analyze_string_to_json(self, *args) -> str:Parses and analyzes a string containing a cQASM v3.0 program.
"},{"location":"dev-guide/cpp.html","title":"C++","text":"You can build the C++ binaries from the project's root directory. The following line will also build and cache the libqasm Conan package.
Note
You may need to execute the conan profile detect command if this is the first time you run Conan.
conan profile detect\nconan create --version 0.6.7 . -pr:a=tests-debug -b missing\nYou can test the C++ binaries:
cd test/Debug\nctest -C Debug --output-on-failure\nFor development, see:
include: public headers.src: source files.test: test files.python: SWIG interface.res: resource files, for testing.For build process, continuous integration, and documentation:
conan: Conan profiles.emscripten: bindings and test for the Emscripten binaries.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.CMake >= 3.12gitPython 3.x plus pip, with the following package:conan >= 2.0SWIGWe 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 >= 11doxygenmkdocs with the following packages:mike mkdocs-materialmkdocstringspymdown-extensionsThis version of libQASM 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/libqasm.git\ncd libqasm\nconan profile detect\nconan build . -pr:a=conan/profiles/tests-debug -b missing\nNote
conan profile command only has to be run only once, and not before every build.conan build command is building libQASM in Debug mode with tests using the tests-debug profile.-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...).A group of predefined profiles is provided under the conan/profiles folder. They follow the [tests-|docs-](build_type)(-compiler)(-os)(-arch)[-shared] naming convention:
tests: if tests are being built.docs: if docs are being built.build_type: can be debug or release.compiler: apple-clang, clang, gcc, msvc.os: emscripten, linux, macos, windows.arch: arm64, wasm, x64.shared: if the library is being built in shared mode.All the profiles set the C++ standard to 20. All the tests, except for linux-x64 profiles, enable Address Sanitizer.
Profiles are a shorthand for command line options. The command above could be written, similarly, as:
conan build . -s:a compiler.cppstd=20 -s:a libqasm/*:build_type=Debug -o libqasm/*:asan_enabled=True -c tools.build:skip_test=False -b missing\nThis is the list of options that could be specified either in a profile or in the command line:
libqasm/*:asan_enabled={True,False}: enables Address Sanitizer.libqasm/*:build_type={Debug,Release}: builds in debug or release mode.libqasm/*:shared={True,False}: builds a shared object library instead of a static library, if applicable.Tests are disabled by default. To enable them, use -c tools.build:skip_test=False.
Build and serve on http://127.0.0.1:8000/.
export PTYHONPATH=./scripts/python\nmkdocs serve\nNote
The export is needed to point mkdocs to the custom handlers used for the C++, emscripten, and Python APIs.
This tests the library in a container with the bare minimum requirements for libQASM.
docker build .\nNote
The above might fail on Windows due to the autocrlf transformation that git does. If you run into this issue, then create new clone of this repository:
git clone --config core.autocrlf=input git@github.com:QuTech-Delft/libqasm.git\nYou can build the Emscripten binaries from the project's root directory. The generation of Emscripten binaries has been tested as a cross-compilation from an ubuntu/x64 platform.
conan build . -pr=conan/profiles/release-clang-emscripten-wasm -pr:b=conan/profiles/release -b missing\nThe output of this build lives in build/Release/emscripten:
cqasm_emscripten.js.cqasm_emscripten.wasm.Note
cqasm_emscripten.js is an ES6 module. Its extension has to be renamed to .mjs before using it from Typescript code.
You can test the Emscripten binaries:
cd build/Release/emscripten\nmv cqasm_emscripten.js cqasm_emscripten.mjs\ncd ../../../emscripten\ndeno run -A test_libqasm.ts\nYou can build and install the Python package from the project's root directory.
python3 -m pip install --verbose .\nYou can test the Python package:
python3 -m pytest\nlibQASM can be requested as a Conan package from a conanfile.py.
def build_requirements(self):\n self.tool_requires(\"libqasm/0.6.7\")\ndef requirements(self):\n self.requires(\"libqasm/0.6.7\")\nAnd then linked against from a CMakeLists.txt:
target_link_libraries(<your target> PUBLIC libqasm::libqasm)\nNote
You will need to have Java JRE >= 11 installed in case Conan needs to build libQASM.
Example:
#include \"v3x/cqasm-py.hpp\"\n\nauto program = std::string{ R\"(\n version 3.0\n qubit[2] q\n bit[2] b\n H q[0]\n CNOT q[0], q[1]\n b = measure q\n)\" };\n\nauto parse_result = V3xAnalyzer::parse_string(program);\n\nauto analyzer = V3xAnalyzer();\nauto analysis_result = analyzer.analyze_string(program);\nlibQASM can be tested in a container with the bare minimum requirements.
docker build .\nNote
The above might fail on Windows due 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 git@github.com:QuTech-Delft/libqasm.git
libQASM can be used from a web environment via a Typescript frontend.
Emscripten API only allows to input a cQASM program via a string and always returns a JSON string output.
Example:
import { default as wrapper } from 'cqasm_emscripten.mjs';\n\nwrapper().then(function(result: any) {\n let cqasm = new result[\"EmscriptenWrapper\"]()\n let program = `version 3.0 \n qubit[2] q \n bit[2] b \n H q[0]\n CNOT q[0], q[1]\n b = measure q`\n let output = cqasm.parse_string_to_json(program, \"bell.cq\")\n cqasm.delete()\n}).catch((error: any) => {\n console.error(\"unhandledRejection\", error, \"\\n\");\n});\nlibQASM can be imported as a Python package.
Example:
from libqasm import Analyzer\n\nprogram = r'''\n version 3.0\n qubit[2] q\n bit[2] b\n H q[0]\n CNOT q[0], q[1]\n b = measure q\n'''\n\nparse_result = Analyzer.parse_string(program, \"bell.cq\")\n\nanalyzer = Analyzer()\nanalysis_result = analyzer.analyze_string(program, \"bell.cq\")\nlibQASM can be used from:
libQASM is a library to parse cQASM programs, developed by QuTech.
At the moment, libQASM only supports cQASM v3.0 programs (see cQASM-spec for the language specification).
It performs lexical, syntactic, and semantic analysis of an input program received via a file or a string. It produces one of the following results:
It can be used from:
Check out QX simulator and OpenSquirrel compiler for an example of use in a C++ and a Python project, respectively.
"},{"location":"about/authors.html","title":"Authors","text":"libQASM is developed as part of the Quantum Inspire project: support@quantum-inspire.com
"},{"location":"about/contributing.html","title":"Contributing","text":"Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.
If you have a suggestion that would make this better, please fork the repo and create a pull request.
git checkout -b feature/AmazingFeature).git commit -m 'Add some AmazingFeature').git push origin feature/AmazingFeature).libQASM is licensed under the Apache License, Version 2.0. See LICENSE for the full license text.
"},{"location":"about/release-notes.html","title":"Release Notes","text":"Coming soon
"},{"location":"api/cpp.html","title":"C++","text":"libQASM C++ API is defined in include/v3x/cqasm-py.hpp.
The only exported class is V3xAnalyzer. This is actually a C++ class that works as a binding for accessing C++ code from Python.
class V3xAnalyzer;Main class for parsing and analyzing cQASM v3.0 files.
This class works as a binding for accessing C++ code from Python.
The parsing methods are static because they do not change the status of the analyzer. Instead, they just invoke free functions that create a temporary instance of a parser.
None of the parsing or the analyzing methods perform any version check.
parse_file, parse_string, analyze_file, and analyze_string:
Return a vector of strings. The first string is reserved for the CBOR serialization of the syntactic/semantic (in the case of parsing/analyzing) Abstract Syntax Tree (AST) of the input program. Any additional strings represent error messages. Notice that the AST and error messages will not be available at the same time.
parse_file_to_json, parse_string_to_json, analyze_file_to_json, and analyze_string_to_json:
Return a string in JSON format. If the parsing was successful, that string contains a JSON representation of the AST of the input program. Otherwise, it will contain a list of errors. The JSON representation of each error follows the Language Server Protocol (LSP) specification. Every error is mapped to an LSP Diagnostic structure: severity is hardcoded to 1 at the moment (value corresponding to an Error level).
parse_string, parse_string_to_json, analyze_string, andanalyze_string_to_json`:
have an optional second argument: file_name. It is only used when reporting errors.
Example:
auto result = analyze_file(\"grover.cq\");\nauto program = std::string{ R\"(\n version 3.0\n qubit[2] q\n bit[2] b\n H q[0]\n CNOT q[0], q[1]\n b = measure q\n)\" };\nauto result = parse_string_to_json(program, \"bell.cq\");\nstatic std::vector<std::string> parse_file(const std::string& file_name);Parses a file containing a cQASM v3.0 program.
static std::string parse_file_to_json(const std::string& file_name);Parses a file containing a cQASM v3.0 program.
static std::vector<std::string> parse_string(const std::string& data, const std::string& file_name);Parses a string containing a cQASM v3.0 program.
file_name is optional. It is only used when reporting errors.
static std::string parse_string_to_json(const std::string& data, const std::string& file_name);Parses a string containing a cQASM v3.0 program.
file_name is optional. It is only used when reporting errors.
V3xAnalyzer(const std::string& max_version, bool without_defaults);Creates a new cQASM v3.0 semantic analyzer.
max_version is optional. It has a default value of 3.0. The maximum cQASM version supported by the analyzer.
without_defaults is optional. If set, the default instruction set is not loaded into the instruction table, so you have to specify the entire instruction set using register_instruction(). Otherwise, those functions only add to the defaults.
The initial mappings and functions are not configurable. The defaults for these are always used.
~V3xAnalyzer();Default destructor.
void register_instruction(const std::string& name, const std::optional<std::string>& param_types);Registers an instruction type.
The param_types can be:
Q = qubit.
V = qubit array.
B = bit.
W = bit array.
i = int.
f = float.
Example:
register_instruction(\"H\", \"Q\");\nstd::vector<std::string> analyze_file(const std::string& file_name);Parses and analyzes a file containing a cQASM v3.0 program.
std::string analyze_file_to_json(const std::string& file_name);Parses and analyzes a file containing a cQASM v3.0 program.
std::vector<std::string> analyze_string(const std::string& data, const std::string& file_name);Parses and analyzes a string containing a cQASM v3.0 program.
file_name is optional. It is only used when reporting errors.
std::string analyze_string_to_json(const std::string& data, const std::string& file_name);Parses and analyzes a string containing a cQASM v3.0 program.
file_name is optional. It is only used when reporting errors.
libQASM is also deployed as an Emscripten binary with a Typescript frontend.
libQASM Typescript API is defined in emscripten/emscripten_wrapper.hpp.
The only exported class is EmscriptenWrapper. This is actually a C++ class that works as a binding for accessing C++ code from Typescript.
struct EmscriptenWrapper;Main class for parsing and analyzing cQASM files.
This class works as a binding for accessing C++ code from Typescript.
Example:
import { default as wrapper } from 'cqasm_emscripten.mjs';\n\nwrapper().then(function(result: any) {\n let cqasm = new result[\"EmscriptenWrapper\"]()\n let program = ...\n let output = cqasm.parse_string_to_json(program, ...)\n cqasm.delete()\n}).catch((error: any) => {\n console.error(\"unhandledRejection\", error, \"\\n\");\n});\nstd::string get_version();Returns the version of the libqasm library.
Example:
let version = cqasm.get_version()\nstd::string parse_string_to_json(const std::string& data, const std::string& file_name);Parses a string containing a cQASM v3.0 program.
No version check is performed.
The file_name is only used when reporting errors.
Returns a string. If the parsing was successful, the string contains a syntactic Abstract Syntax Tree (AST). Otherwise, it will contain a list of errors. The JSON representation of each error follows the Language Server Protocol (LSP) specification. Every error is mapped to an LSP Diagnostic structure: severity is hardcoded to 1 at the moment (value corresponding to an Error level).
Example:
let program = `\n version 3\n qubit[2] q\n bit[2] b\n H q[0]\n CNOT q[0], q[1]\n b = measure q\n`\nlet output = parse_string_to_json(program, \"bell.cq\")\nstd::string analyze_string_to_json(const std::string& data, const std::string& file_name);Parses and analyzes a string containing a cQASM v3.0 program.
No version check is performed.
The file_name is only used when reporting errors.
Returns a string. If the parsing was successful, the string contains a semantic Abstract Syntax Tree (AST). Otherwise, it will contain a list of errors. The JSON representation of each error follows the Language Server Protocol (LSP) specification. Every error is mapped to an LSP Diagnostic structure: severity is hardcoded to 1 at the moment (value corresponding to an Error level).
Example:
let program = `\n version 3\n qubit[2] q\n bit[2] b\n H q[0]\n CNOT q[0], q[1]\n b = measure q\n`\nlet output = analyze_string_to_json(program, \"bell.cq\")\nlibQASM Python API is defined in python/module/cqasm/v3x/__init__.py.
The only exported class is Analyzer. This is actually a Python class that works as a binding for accessing C++ code from Python.
class AnalyzerMain class for parsing and analyzing cQASM v3.0 files.
This class works as a binding for accessing C++ code from Python.
The parsing methods are static because they do not change the status of the analyzer. Instead, they just invoke free functions that create a temporary instance of a parser.
None of the parsing or the analyzing methods perform any version check.
parse_file, parse_string, analyze_file, and analyze_string:
return a vector of strings. If the length of the vector is 1, the string is a serialization of the syntactic/semantic (in the case of parsing/analyzing) Abstract Syntax Tree (AST) of the input program. Otherwise, it is a list of errors.
parse_file_to_json, parse_string_to_json, analyze_file_to_json, and analyze_string_to_json:
return a string in JSON format. If the parsing was successful, the string contains a JSON representation of the AST of the input program. Otherwise, it will contain a list of errors. The JSON representation of each error follows the Language Server Protocol (LSP) specification. Every error is mapped to an LSP Diagnostic structure: severity is hardcoded to 1 at the moment (value corresponding to an Error level).
parse_string, parse_string_to_json, analyze_string, andanalyze_string_to_json`:
have an optional second argument: file_name. It is only used when reporting errors.
Example:
result = libqasm.analyze_file(\"grover.cq\")\nprogram = r'''\n version 3.0\n qubit[2] q\n bit[2] b\n H q[0]\n CNOT q[0], q[1]\n b = measure q\n'''\nresult = libqasm.parse_string_to_json(program, \"bell.cq\")\n@staticmethod\nparse_file(*args) -> list[str]:Parses a file containing a cQASM v3.0 program.
@staticmethod\nparse_file_to_json(*args) -> str:Parses a file containing a cQASM v3.0 program.
@staticmethod\nparse_string(*args) -> list[str]:Parses a string containing a cQASM v3.0 program.
@staticmethod\nparse_string_to_json(*args) -> str:Parses a string containing a cQASM v3.0 program.
analyze_file(self, *args) -> list[str]:Parses and analyzes a file containing a cQASM v3.0 program.
analyze_file_to_json(self, *args) -> str:Parses and analyzes a file containing a cQASM v3.0 program.
analyze_string(self, *args) -> list[str]:Parses and analyzes a string containing a cQASM v3.0 program.
analyze_string_to_json(self, *args) -> str:Parses and analyzes a string containing a cQASM v3.0 program.
"},{"location":"dev-guide/cpp.html","title":"C++","text":"You can build the C++ binaries from the project's root directory. The following line will also build and cache the libqasm Conan package.
Note
You may need to execute the conan profile detect command if this is the first time you run Conan.
conan profile detect\nconan create --version 0.6.7 . -pr:a=tests-debug -b missing\nYou can test the C++ binaries:
cd test/Debug\nctest -C Debug --output-on-failure\nFor development, see:
include: public headers.src: source files.test: test files.python: SWIG interface.res: resource files, for testing.For build process, continuous integration, and documentation:
conan: Conan profiles.emscripten: bindings and test for the Emscripten binaries.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.CMake >= 3.12gitPython 3.x plus pip, with the following package:conan >= 2.0SWIGWe 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 >= 11doxygenmkdocs with the following packages:mike mkdocs-materialmkdocstringspymdown-extensionsThis version of libQASM 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/libqasm.git\ncd libqasm\nconan profile detect\nconan build . -pr:a=conan/profiles/tests-debug -b missing\nNote
conan profile command only has to be run only once, and not before every build.conan build command is building libQASM in Debug mode with tests using the tests-debug profile.-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...).A group of predefined profiles is provided under the conan/profiles folder. They follow the [tests-|docs-](build_type)(-compiler)(-os)(-arch)[-shared] naming convention:
tests: if tests are being built.docs: if docs are being built.build_type: can be debug or release.compiler: apple-clang, clang, gcc, msvc.os: emscripten, linux, macos, windows.arch: arm64, wasm, x64.shared: if the library is being built in shared mode.All the profiles set the C++ standard to 20. All the tests, except for linux-x64 profiles, enable Address Sanitizer.
Profiles are a shorthand for command line options. The command above could be written, similarly, as:
conan build . -s:a compiler.cppstd=20 -s:a libqasm/*:build_type=Debug -o libqasm/*:asan_enabled=True -c tools.build:skip_test=False -b missing\nThis is the list of options that could be specified either in a profile or in the command line:
libqasm/*:asan_enabled={True,False}: enables Address Sanitizer.libqasm/*:build_type={Debug,Release}: builds in debug or release mode.libqasm/*:shared={True,False}: builds a shared object library instead of a static library, if applicable.Tests are disabled by default. To enable them, use -c tools.build:skip_test=False.
Build and serve on http://127.0.0.1:8000/.
export PTYHONPATH=./scripts/python\nmkdocs serve\nNote
The export is needed to point mkdocs to the custom handlers used for the C++, emscripten, and Python APIs.
This tests the library in a container with the bare minimum requirements for libQASM.
docker build .\nNote
The above might fail on Windows due to the autocrlf transformation that git does. If you run into this issue, then create new clone of this repository:
git clone --config core.autocrlf=input git@github.com:QuTech-Delft/libqasm.git\nYou can build the Emscripten binaries from the project's root directory. The generation of Emscripten binaries has been tested as a cross-compilation from an ubuntu/x64 platform.
conan build . -pr=conan/profiles/release-clang-emscripten-wasm -pr:b=conan/profiles/release -b missing\nThe output of this build lives in build/Release/emscripten:
cqasm_emscripten.js.cqasm_emscripten.wasm.Note
cqasm_emscripten.js is an ES6 module. Its extension has to be renamed to .mjs before using it from Typescript code.
You can test the Emscripten binaries:
cd build/Release/emscripten\nmv cqasm_emscripten.js cqasm_emscripten.mjs\ncd ../../../emscripten\ndeno run -A test_libqasm.ts\nYou can build and install the Python package from the project's root directory.
python3 -m pip install --verbose .\nYou can test the Python package:
python3 -m pytest\nlibQASM can be requested as a Conan package from a conanfile.py.
def build_requirements(self):\n self.tool_requires(\"libqasm/0.6.7\")\ndef requirements(self):\n self.requires(\"libqasm/0.6.7\")\nAnd then linked against from a CMakeLists.txt:
target_link_libraries(<your target> PUBLIC libqasm::libqasm)\nNote
You will need to have Java JRE >= 11 installed in case Conan needs to build libQASM.
Example:
#include \"v3x/cqasm-py.hpp\"\n\nauto program = std::string{ R\"(\n version 3.0\n qubit[2] q\n bit[2] b\n H q[0]\n CNOT q[0], q[1]\n b = measure q\n)\" };\n\nauto parse_result = V3xAnalyzer::parse_string(program);\n\nauto analyzer = V3xAnalyzer();\nauto analysis_result = analyzer.analyze_string(program);\nlibQASM can be tested in a container with the bare minimum requirements.
docker build .\nNote
The above might fail on Windows due 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 git@github.com:QuTech-Delft/libqasm.git
libQASM can be used from a web environment via a Typescript frontend.
Emscripten API only allows to input a cQASM program via a string and always returns a JSON string output.
Example:
import { default as wrapper } from 'cqasm_emscripten.mjs';\n\nwrapper().then(function(result: any) {\n let cqasm = new result[\"EmscriptenWrapper\"]()\n let program = `version 3.0 \n qubit[2] q \n bit[2] b \n H q[0]\n CNOT q[0], q[1]\n b = measure q`\n let output = cqasm.parse_string_to_json(program, \"bell.cq\")\n cqasm.delete()\n}).catch((error: any) => {\n console.error(\"unhandledRejection\", error, \"\\n\");\n});\nlibQASM can be imported as a Python package.
Example:
from libqasm import Analyzer\n\nprogram = r'''\n version 3.0\n qubit[2] q\n bit[2] b\n H q[0]\n CNOT q[0], q[1]\n b = measure q\n'''\n\nparse_result = Analyzer.parse_string(program, \"bell.cq\")\n\nanalyzer = Analyzer()\nanalysis_result = analyzer.analyze_string(program, \"bell.cq\")\nlibQASM can be used from: