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
+export PYTHONPATH=./scripts/python
mkdocs serve
@@ -1195,11 +1195,23 @@ Linters
Code style checks are defined in .clang-tidy.
It is recommended to run these linters before pushing any change:
-python3 ./scripts/run_cpp_linters.py .
+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 to be installed on the system.
+
+- 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.
+
+
Docker
This tests the library in a container with the bare minimum requirements for libQASM.
diff --git a/latest/search/search_index.json b/latest/search/search_index.json
index d3885671..52e23549 100644
--- a/latest/search/search_index.json
+++ b/latest/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"index.html","title":"Home","text":"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:
- A syntactic or semantic AST (Abstract Syntax Tree) object. Depending on if we are parsing or analysing.
- A list of parsing or analysing errors. In case the input program was malformed.
- A JSON representation of either the AST or the list of errors.
It can be used from:
- C++ projects (as a Conan package).
- Python projects (as a Python package).
- Emscripten projects (via a Typescript frontend).
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.
- Fork the project.
- Create your feature branch (
git checkout -b feature/AmazingFeature). - Commit your changes (
git commit -m 'Add some AmazingFeature'). - Push to the branch (
git push origin feature/AmazingFeature). - Open a pull request.
"},{"location":"about/license.html","title":"License","text":"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_python.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\");\n
Example: auto 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\");\n
static 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\");\n
std::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.
"},{"location":"api/emscripten.html","title":"Emscripten","text":"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});\n
std::string get_version();
Returns the version of the libqasm library.
Example:
let version = cqasm.get_version()\n
std::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\")\n
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.
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\")\n
"},{"location":"api/python.html","title":"Python","text":"libQASM 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 Analyzer
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. 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\")\n
Example: program = 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.9 . -pr:a=tests-debug -b missing\n
You can test the C++ binaries:
cd test/Debug\nctest -C Debug --output-on-failure\n
"},{"location":"dev-guide/dev-guide.html","title":"Dev Guide","text":""},{"location":"dev-guide/dev-guide.html#file-organization","title":"File organization","text":"For development, see:
include/libqasm: 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.
"},{"location":"dev-guide/dev-guide.html#dependencies","title":"Dependencies","text":" - C++ compiler with C++20 support (gcc 11, clang 14, msvc 17)
CMake >= 3.12gitPython 3.x plus pip, with the following package: conan >= 2.0
SWIG
"},{"location":"dev-guide/dev-guide.html#arm-builds","title":"ARM builds","text":"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
"},{"location":"dev-guide/dev-guide.html#documentation","title":"Documentation","text":" doxygenmkdocs with the following packages: mike mkdocs-materialmkdocstringspymdown-extensions
"},{"location":"dev-guide/dev-guide.html#linters","title":"Linters","text":" clang-format-18clang-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\n chmod +x llvm_install.sh\n ./llvm_install.sh\n apt-get install -y clang-format-18 clang-tidy-18\n
"},{"location":"dev-guide/dev-guide.html#build","title":"Build","text":"This 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\n
Note
- 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...).
"},{"location":"dev-guide/dev-guide.html#profiles","title":"Profiles","text":"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.
"},{"location":"dev-guide/dev-guide.html#options","title":"Options","text":"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\n
This 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.
"},{"location":"dev-guide/dev-guide.html#documentation_1","title":"Documentation","text":"Build and serve on http://127.0.0.1:8000/.
export PTYHONPATH=./scripts/python\nmkdocs serve\n
Note
The export is needed to point mkdocs to the custom handlers used for the C++, emscripten, and Python APIs.
"},{"location":"dev-guide/dev-guide.html#linters_1","title":"Linters","text":"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 change:
python3 ./scripts/run_cpp_linters.py .\n
Note
The linters require clang-format-18 and clang-tidy-18 to be installed on the system.
"},{"location":"dev-guide/dev-guide.html#docker","title":"Docker","text":"This tests the library in a container with the bare minimum requirements for libQASM.
docker build .\n
Note
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\n
"},{"location":"dev-guide/emscripten.html","title":"Emscripten","text":"You 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\n
The 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\n
"},{"location":"dev-guide/python.html","title":"Python","text":"You can build and install the Python package from the project's root directory.
python3 -m pip install --verbose .\n
You can test the Python package:
python3 -m pytest\n
"},{"location":"user-guide/cpp.html","title":"C++","text":"libQASM can be requested as a Conan package from a conanfile.py.
def build_requirements(self):\n self.tool_requires(\"libqasm/0.6.9\")\ndef requirements(self):\n self.requires(\"libqasm/0.6.9\")\n
And then linked against from a CMakeLists.txt:
target_link_libraries(<your target> PUBLIC libqasm::libqasm)\n
Note
You will need to have Java JRE >= 11 installed in case Conan needs to build libQASM.
Example:
#include \"libqasm/v3x/cqasm_python.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);\n
"},{"location":"user-guide/docker.html","title":"Docker","text":"libQASM can be tested in a container with the bare minimum requirements.
docker build .\n
Note
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
"},{"location":"user-guide/emscripten.html","title":"Emscripten","text":"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});\n
"},{"location":"user-guide/python.html","title":"Python","text":"libQASM 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\")\n
"},{"location":"user-guide/user-guide.html","title":"User Guide","text":"libQASM can be used from:
- C++ projects (as a Conan package).
- Python projects (as a Python package).
- Emscripten projects (via a Typescript frontend).
- Docker.
"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"index.html","title":"Home","text":"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:
- A syntactic or semantic AST (Abstract Syntax Tree) object. Depending on if we are parsing or analysing.
- A list of parsing or analysing errors. In case the input program was malformed.
- A JSON representation of either the AST or the list of errors.
It can be used from:
- C++ projects (as a Conan package).
- Python projects (as a Python package).
- Emscripten projects (via a Typescript frontend).
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.
- Fork the project.
- Create your feature branch (
git checkout -b feature/AmazingFeature). - Commit your changes (
git commit -m 'Add some AmazingFeature'). - Push to the branch (
git push origin feature/AmazingFeature). - Open a pull request.
"},{"location":"about/license.html","title":"License","text":"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_python.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\");\n
Example: auto 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\");\n
static 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\");\n
std::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.
"},{"location":"api/emscripten.html","title":"Emscripten","text":"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});\n
std::string get_version();
Returns the version of the libqasm library.
Example:
let version = cqasm.get_version()\n
std::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\")\n
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.
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\")\n
"},{"location":"api/python.html","title":"Python","text":"libQASM 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 Analyzer
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. 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\")\n
Example: program = 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.9 . -pr:a=tests-debug -b missing\n
You can test the C++ binaries:
cd test/Debug\nctest -C Debug --output-on-failure\n
"},{"location":"dev-guide/dev-guide.html","title":"Dev Guide","text":""},{"location":"dev-guide/dev-guide.html#file-organization","title":"File organization","text":"For development, see:
include/libqasm: 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.
"},{"location":"dev-guide/dev-guide.html#dependencies","title":"Dependencies","text":" - C++ compiler with C++20 support (gcc 11, clang 14, msvc 17)
CMake >= 3.12gitPython 3.x plus pip, with the following package: conan >= 2.0
SWIG
"},{"location":"dev-guide/dev-guide.html#arm-builds","title":"ARM builds","text":"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
"},{"location":"dev-guide/dev-guide.html#documentation","title":"Documentation","text":" doxygenmkdocs with the following packages: mike mkdocs-materialmkdocstringspymdown-extensions
"},{"location":"dev-guide/dev-guide.html#linters","title":"Linters","text":" clang-format-18clang-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\n chmod +x llvm_install.sh\n ./llvm_install.sh\n apt-get install -y clang-format-18 clang-tidy-18\n
"},{"location":"dev-guide/dev-guide.html#build","title":"Build","text":"This 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\n
Note
- 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...).
"},{"location":"dev-guide/dev-guide.html#profiles","title":"Profiles","text":"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.
"},{"location":"dev-guide/dev-guide.html#options","title":"Options","text":"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\n
This 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.
"},{"location":"dev-guide/dev-guide.html#documentation_1","title":"Documentation","text":"Build and serve on http://127.0.0.1:8000/.
export PYTHONPATH=./scripts/python\nmkdocs serve\n
Note
The export is needed to point mkdocs to the custom handlers used for the C++, emscripten, and Python APIs.
"},{"location":"dev-guide/dev-guide.html#linters_1","title":"Linters","text":"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 change:
conan build . -pr:a=conan/profiles/tests-release-gcc-linux-x64 -b missing\npython3 ./scripts/run_cpp_linters.py .\n
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.
"},{"location":"dev-guide/dev-guide.html#docker","title":"Docker","text":"This tests the library in a container with the bare minimum requirements for libQASM.
docker build .\n
Note
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\n
"},{"location":"dev-guide/emscripten.html","title":"Emscripten","text":"You 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\n
The 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\n
"},{"location":"dev-guide/python.html","title":"Python","text":"You can build and install the Python package from the project's root directory.
python3 -m pip install --verbose .\n
You can test the Python package:
python3 -m pytest\n
"},{"location":"user-guide/cpp.html","title":"C++","text":"libQASM can be requested as a Conan package from a conanfile.py.
def build_requirements(self):\n self.tool_requires(\"libqasm/0.6.9\")\ndef requirements(self):\n self.requires(\"libqasm/0.6.9\")\n
And then linked against from a CMakeLists.txt:
target_link_libraries(<your target> PUBLIC libqasm::libqasm)\n
Note
You will need to have Java JRE >= 11 installed in case Conan needs to build libQASM.
Example:
#include \"libqasm/v3x/cqasm_python.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);\n
"},{"location":"user-guide/docker.html","title":"Docker","text":"libQASM can be tested in a container with the bare minimum requirements.
docker build .\n
Note
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
"},{"location":"user-guide/emscripten.html","title":"Emscripten","text":"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});\n
"},{"location":"user-guide/python.html","title":"Python","text":"libQASM 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\")\n
"},{"location":"user-guide/user-guide.html","title":"User Guide","text":"libQASM can be used from:
- C++ projects (as a Conan package).
- Python projects (as a Python package).
- Emscripten projects (via a Typescript frontend).
- Docker.
"}]}
\ No newline at end of file
diff --git a/latest/sitemap.xml.gz b/latest/sitemap.xml.gz
index 7607e6e63288faf0a885e256820b6f15379cc7ae..ad7e6c43a5224e331295b9f1fa848ef241d05d6c 100644
GIT binary patch
delta 13
Ucmb=gXP58h;9y|!oXB1Q02ado9RL6T
delta 13
Ucmb=gXP58h;9#h*o5)@P02tc?h5!Hn