📝 Add Documentation (#24)

* docs: 📝 Add RTD docs

* docs: 📝 Write library documentation

* docs: ♻️ Align "MQT Debug" vs "MQT Debugger" to "MQT Debugger"

* docs: 📝 Add docstrings to python bindings

* docs: 📝 Add interactive debugging section to docs and add docstrings to python bindings

* fix: ✏️ Fix links to QCEC instead of mqt debugger

* fix: 💄 Fix linter issues

* refactor: 🏷️ Ann py.typed marker and pyi file for _version

* fix: 👷 Remove CMAKE_GENERATOR = Ninja from windows cibuildwheel tool

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -8,9 +8,9 @@ body:
         **Thank you for wanting to report a bug for this project!**
 
         ⚠
-        Verify first that your issue is not [already reported on GitHub](https://github.com/cda-tum/qcec/search?q=is%3Aissue&type=issues).
+        Verify first that your issue is not [already reported on GitHub](https://github.com/cda-tum/mqt-debugger/search?q=is%3Aissue&type=issues).
 
-        If you have general questions, please consider [starting a discussion](https://github.com/cda-tum/qcec/discussions).
+        If you have general questions, please consider [starting a discussion](https://github.com/cda-tum/mqt-debugger/discussions).
   - type: textarea
     attributes:
       label: Environment information

.github/ISSUE_TEMPLATE/feature-request.yml

@@ -8,7 +8,7 @@ body:
         **Thank you for wanting to suggest a feature for this project!**
 
         ⚠
-        Verify first that your idea is not [already requested on GitHub](https://github.com/cda-tum/qcec/search?q=is%3Aissue&type=issues).
+        Verify first that your idea is not [already requested on GitHub](https://github.com/cda-tum/mqt-debugger/search?q=is%3Aissue&type=issues).
 
   - type: textarea
     attributes:

.github/codecov.yml

@@ -2,8 +2,8 @@ ignore:
   - "extern/**/*"
   - "**/python"
   - "test/**/*"
-  - "src/mqt/debug/dap/**/*"
-  - "src/mqt/debug/dap/*"
+  - "src/mqt/debugger/dap/**/*"
+  - "src/mqt/debugger/dap/*"
   - "app/*"
   - "src/frontend/**/*"
 

.github/contributing.rst

@@ -6,7 +6,7 @@ We value contributions from people with all levels of experience.
 In particular if this is your first pull request not everything has to be perfect.
 We will guide you through the process.
 
-We use GitHub to `host code <https://github.com/cda-tum/mqt-debug>`_, to `track issues and feature requests <https://github.com/cda-tum/mqt-debug/issues>`_, as well as accept `pull requests <https://github.com/cda-tum/mqt-debug/pulls>`_.
+We use GitHub to `host code <https://github.com/cda-tum/mqt-debugger>`_, to `track issues and feature requests <https://github.com/cda-tum/mqt-debugger/issues>`_, as well as accept `pull requests <https://github.com/cda-tum/mqt-debugger/pulls>`_.
 See https://docs.github.com/en/get-started/quickstart for a general introduction to working with GitHub and contributing to projects.
 
 Types of Contributions
@@ -15,24 +15,24 @@ Types of Contributions
 You can contribute in several ways:
 
 - 🐛 Report Bugs
-    Report bugs at https://github.com/cda-tum/mqt-debug/issues using the *🐛 Bug report* issue template. Please make sure to fill out all relevant information in the respective issue form.
+    Report bugs at https://github.com/cda-tum/mqt-debugger/issues using the *🐛 Bug report* issue template. Please make sure to fill out all relevant information in the respective issue form.
 
 - 🐛 Fix Bugs
-    Look through the `GitHub Issues <https://github.com/cda-tum/mqt-debug/issues>`_ for bugs. Anything tagged with "bug" is open to whoever wants to try and fix it.
+    Look through the `GitHub Issues <https://github.com/cda-tum/mqt-debugger/issues>`_ for bugs. Anything tagged with "bug" is open to whoever wants to try and fix it.
 
 - ✨ Propose New Features
-    Propose new features at https://github.com/cda-tum/mqt-debug/issues using the *✨ Feature request* issue template. Please make sure to fill out all relevant information in the respective issue form.
+    Propose new features at https://github.com/cda-tum/mqt-debugger/issues using the *✨ Feature request* issue template. Please make sure to fill out all relevant information in the respective issue form.
 
 - ✨ Implement New Features
-    Look through the `GitHub Issues <https://github.com/cda-tum/mqt-debug/issues>`_ for features. Anything tagged with "feature" is open to whoever wants to implement it. We highly appreciate external contributions to the project.
+    Look through the `GitHub Issues <https://github.com/cda-tum/mqt-debugger/issues>`_ for features. Anything tagged with "feature" is open to whoever wants to implement it. We highly appreciate external contributions to the project.
 
 - 📝 Write Documentation
-    MQT Debug could always use some more `documentation <https://mqt.readthedocs.io/projects/debug>`_, and we appreciate any help with that.
+    MQT Debugger could always use some more `documentation <https://mqt.readthedocs.io/projects/debugger>`_, and we appreciate any help with that.
 
 🎉 Get Started
 ##############
 
-Ready to contribute? Check out the :doc:`Development Guide <DevelopmentGuide>` to set up MQT Debug for local development and learn about the style guidelines and conventions used throughout the project.
+Ready to contribute? Check out the :doc:`Development Guide <DevelopmentGuide>` to set up MQT Debugger for local development and learn about the style guidelines and conventions used throughout the project.
 
 We value contributions from people with all levels of experience.
 In particular if this is your first PR not everything has to be perfect.
@@ -62,7 +62,7 @@ Pull Request Workflow
   - If any of the :code:`Python Packaging/\*` checks fail, this indicates an error in the Python bindings or creation of the Python wheels and/or source distribution. Look through the respective logs on GitHub for any error or failure messages.
   - If any of the :code:`Python/\*` checks fail, this indicates an error in the Python part of the code base. Look through the respective logs on GitHub for any error or failure messages.
   - If any of the :code:`codecov/\*` checks fail, this means that your changes are not appropriately covered by tests or that the overall project coverage decreased too much. Ensure that you include tests for all your changes in the PR.
-  - If the :code:`docs/readthedocs.org:debug` check fails, the documentation could not be built properly. Inspect the corresponding log file for any errors.
+  - If the :code:`docs/readthedocs.org:debugger` check fails, the documentation could not be built properly. Inspect the corresponding log file for any errors.
   - If :code:`cpp-linter` comments on your PR with a list of warnings, these have been raised by :code:`clang-tidy` when checking the C++ part of your changes for warnings or style guideline violations. The individual messages frequently provide helpful suggestions on how to fix the warnings.
   - If the :code:`pre-commit.ci` check fails, some of the :code:`pre-commit` checks failed and could not be fixed automatically by the *pre-commit.ci* bot. Such failures are most likely related to the Python part of the code base. The individual log messages frequently provide helpful suggestions on how to fix the warnings.
 

.github/release-drafter.yml

@@ -1,4 +1,4 @@
-name-template: "MQT Debug $RESOLVED_VERSION Release"
+name-template: "MQT Debugger $RESOLVED_VERSION Release"
 tag-template: "v$RESOLVED_VERSION"
 categories:
   - title: "🚀 Features and Enhancements"

.github/support.rst

@@ -1,12 +1,12 @@
 Support
 =======
 
-If you are stuck with a problem using MQT Debug or are having questions, please do get in touch at our `Issues <https://github.com/cda-tum/mqt-debug/issues>`_ or `Discussions <https://github.com/cda-tum/mqt-debug/discussions>`_. We'd love to help.
+If you are stuck with a problem using MQT Debugger or are having questions, please do get in touch at our `Issues <https://github.com/cda-tum/mqt-debugger/issues>`_ or `Discussions <https://github.com/cda-tum/mqt-debugger/discussions>`_. We'd love to help.
 
 You can save time by following this procedure when reporting a problem:
 
-- Do try to solve the problem on your own first. Make sure to consult the `Documentation <https://mqt.readthedocs.io/projects/debug>`_.
-- Search through past `Issues <https://github.com/cda-tum/mqt-debug/issues>`_ to see if someone else already had the same problem.
+- Do try to solve the problem on your own first. Make sure to consult the `Documentation <https://mqt.readthedocs.io/projects/debugger>`_.
+- Search through past `Issues <https://github.com/cda-tum/mqt-debugger/issues>`_ to see if someone else already had the same problem.
 - Before filing a bug report, try to create a minimal working example (MWE) that reproduces the problem. It's much easier to identify the cause for the problem if a handful of lines suffice to show that something isn't working.
 
 You can also always reach us at `quantum.cda@xcit.tum.de <mailto:quantum.cda@xcit.tum.de>`_.

.github/workflows/cd.yml

@@ -18,7 +18,7 @@ jobs:
     runs-on: ubuntu-latest
     environment:
       name: pypi
-      url: https://pypi.org/p/mqt.qcec
+      url: https://pypi.org/p/mqt.debugger
     permissions:
       id-token: write
       attestations: write

CMakeLists.txt

@@ -1,15 +1,16 @@
 cmake_minimum_required(VERSION 3.26)
 project(
-  mqt_debug
+  mqt_debugger
   LANGUAGES CXX
-  DESCRIPTION "MQT Debug - A debugging tool for Quantum Circuits")
+  DESCRIPTION "MQT Debugger - A debugging tool for Quantum Circuits")
 
-option(BUILD_MQT_DEBUG_BINDINGS "Build the MQT DEBUG Python bindings" OFF)
-option(BUILD_MQT_DEBUG_TESTS "Also build tests for the MQT QCEC project" ON)
+option(BUILD_MQT_DEBUGGER_BINDINGS "Build the MQT Debugger Python bindings" OFF)
+option(BUILD_MQT_DEBUGGER_TESTS "Also build tests for the MQT Debugger project" ON)
+option(BUILD_MQT_DEBUGGER_APP "Also build the CLI app for the MQT Debugger project" ON)
 
 set(CMAKE_CXX_STANDARD 17)
 
-if(BUILD_MQT_DEBUG_BINDINGS)
+if(BUILD_MQT_DEBUGGER_BINDINGS)
   # ensure that the BINDINGS option is set
   set(BINDINGS
       ON
@@ -41,16 +42,18 @@ include(cmake/ExternalDependencies.cmake)
 add_subdirectory(src)
 
 # add test app
-add_subdirectory(app)
+if(BUILD_MQT_DEBUGGER_APP)
+  add_subdirectory(app)
+endif()
 
 # add test code
-if(BUILD_MQT_DEBUG_TESTS)
+if(BUILD_MQT_DEBUGGER_TESTS)
   enable_testing()
   include(GoogleTest)
   add_subdirectory(test)
 endif()
 
 configure_file(${CMAKE_CURRENT_SOURCE_DIR}/cmake/cmake_uninstall.cmake.in
                ${CMAKE_CURRENT_BINARY_DIR}/cmake_uninstall.cmake IMMEDIATE @ONLY)
-add_custom_target(uninstall-debug COMMAND ${CMAKE_COMMAND} -P
-                                          ${CMAKE_CURRENT_BINARY_DIR}/cmake_uninstall.cmake)
+add_custom_target(uninstall-debugger COMMAND ${CMAKE_COMMAND} -P
+                                             ${CMAKE_CURRENT_BINARY_DIR}/cmake_uninstall.cmake)

README.md

@@ -1,10 +1,10 @@
-[![PyPI](https://img.shields.io/pypi/v/mqt.debug?logo=pypi&style=flat-square)](https://pypi.org/project/mqt.debug/)
+[![PyPI](https://img.shields.io/pypi/v/mqt.debugger?logo=pypi&style=flat-square)](https://pypi.org/project/mqt.debugger/)
 ![OS](https://img.shields.io/badge/os-linux%20%7C%20macos%20%7C%20windows-blue?style=flat-square)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](https://opensource.org/licenses/MIT)
-[![CI](https://img.shields.io/github/actions/workflow/status/cda-tum/mqt-debug/ci.yml?branch=main&style=flat-square&logo=github&label=ci)](https://github.com/cda-tum/mqt-debug/actions/workflows/ci.yml)
-[![CD](https://img.shields.io/github/actions/workflow/status/cda-tum/mqt-debug/cd.yml?style=flat-square&logo=github&label=cd)](https://github.com/cda-tum/mqt-debug/actions/workflows/cd.yml)
-[![Documentation](https://img.shields.io/readthedocs/debug?logo=readthedocs&style=flat-square)](https://mqt.readthedocs.io/projects/debug)
-[![codecov](https://img.shields.io/codecov/c/github/cda-tum/mqt-debug?style=flat-square&logo=codecov)](https://codecov.io/gh/cda-tum/mqt-debug)
+[![CI](https://img.shields.io/github/actions/workflow/status/cda-tum/mqt-debugger/ci.yml?branch=main&style=flat-square&logo=github&label=ci)](https://github.com/cda-tum/mqt-debugger/actions/workflows/ci.yml)
+[![CD](https://img.shields.io/github/actions/workflow/status/cda-tum/mqt-debugger/cd.yml?style=flat-square&logo=github&label=cd)](https://github.com/cda-tum/mqt-debugger/actions/workflows/cd.yml)
+[![Documentation](https://img.shields.io/readthedocs/debugger?logo=readthedocs&style=flat-square)](https://mqt.readthedocs.io/projects/debugger)
+[![codecov](https://img.shields.io/codecov/c/github/cda-tum/mqt-debugger?style=flat-square&logo=codecov)](https://codecov.io/gh/cda-tum/mqt-debugger)
 
 <p align="center">
   <a href="https://mqt.readthedocs.io">
@@ -15,54 +15,52 @@
   </a>
 </p>
 
-# MQT Debug - A Quantum Circuit Debugging Tool
+# MQT Debugger - A Quantum Circuit Debugging Tool
 
 A tool for debugging quantum circuits developed as part of the [_Munich Quantum Toolkit (MQT)_](https://mqt.readthedocs.io) by the [Chair for Design Automation](https://www.cda.cit.tum.de/) at the [Technical University of Munich](https://www.tum.de/).
 It proposes an interface for the simulation of circuits and diagnosis of errors and provides a base implementation built upon [MQT Core](https://github.com/cda-tum/mqt-core), which forms the backbone of the MQT.
 It also provides a Debugger Adapter Protocol (DAP) server that can be used to integrate the debugger into IDEs.
 
 <p align="center">
-  <a href="https://mqt.readthedocs.io/projects/debug">
+  <a href="https://mqt.readthedocs.io/projects/debugger">
   <img width=30% src="https://img.shields.io/badge/documentation-blue?style=for-the-badge&logo=read%20the%20docs" alt="Documentation" />
   </a>
 </p>
 
-If you have any questions, feel free to contact us via [quantum.cda@xcit.tum.de](mailto:quantum.cda@xcit.tum.de) or by creating an issue on [GitHub](https://github.com/cda-tum/mqt-debug/issues).
+If you have any questions, feel free to contact us via [quantum.cda@xcit.tum.de](mailto:quantum.cda@xcit.tum.de) or by creating an issue on [GitHub](https://github.com/cda-tum/mqt-debugger/issues).
 
 ## Getting Started
 
-MQT Debug is available via [PyPI](https://pypi.org/project/mqt.debug/) for Linux, macOS, and Windows and supports Python 3.8 to 3.12.
+MQT Debugger is available via [PyPI](https://pypi.org/project/mqt.debugger/) for Linux, macOS, and Windows and supports Python 3.8 to 3.12.
 
 ```console
-(venv) $ pip install mqt.debug
+(venv) $ pip install mqt.debugger
 ```
 
 The following code gives an example on the usage:
 
 ```python3
-from mqt import debug
+from mqt import debugger
 
-state = debug.create_ddsim_simulation_state()
+state = debugger.create_ddsim_simulation_state()
 with open("code.qasm", "r") as f:
     state.load_code(f.read())
 f.run_simulation()
 print(f.get_state_vector_full())
 ```
 
-**Detailed documentation on all available methods, options, and input formats is available at [ReadTheDocs](https://mqt.readthedocs.io/projects/debug).**
+**Detailed documentation on all available methods, options, and input formats is available at [ReadTheDocs](https://mqt.readthedocs.io/projects/debugger).**
 
 ## System Requirements and Building
 
 The implementation is compatible with any C++20 compiler, a minimum CMake version of 3.19, and Python 3.8+.
-Please refer to the [documentation](https://mqt.readthedocs.io/projects/debug) on how to build the project.
+Please refer to the [documentation](https://mqt.readthedocs.io/projects/debugger) on how to build the project.
 
 Building (and running) is continuously tested under Linux, macOS, and Windows using the [latest available system versions for GitHub Actions](https://github.com/actions/virtual-environments).
 
 ## References
 
-MQT Debug has been developed based on methods proposed in the following papers:
-
-TODO
+MQT Debugger has been developed based on methods proposed in a scientific paper that has not been released yet.
 
 ## Acknowledgements
 

app/CMakeLists.txt

@@ -1,10 +1,10 @@
-add_executable(mqt_debug_app testDDSimDebugger.cpp)
+add_executable(mqt_debugger_app testDDSimDebugger.cpp)
 
 # set include directories
-target_include_directories(mqt_debug_app PUBLIC ${PROJECT_SOURCE_DIR}/include
-                                                ${PROJECT_BINARY_DIR}/include)
+target_include_directories(mqt_debugger_app PUBLIC ${PROJECT_SOURCE_DIR}/include
+                                                   ${PROJECT_BINARY_DIR}/include)
 
 # link to the MQT::Core libraries
-target_link_libraries(mqt_debug_app PRIVATE ${PROJECT_NAME})
-target_link_libraries(mqt_debug_app PUBLIC MQT::CoreDD)
-target_link_libraries(mqt_debug_app PRIVATE MQT::ProjectWarnings MQT::ProjectOptions)
+target_link_libraries(mqt_debugger_app PRIVATE ${PROJECT_NAME})
+target_link_libraries(mqt_debugger_app PUBLIC MQT::CoreDD)
+target_link_libraries(mqt_debugger_app PRIVATE MQT::ProjectWarnings MQT::ProjectOptions)

app/testDDSimDebugger.cpp

@@ -8,19 +8,25 @@
 
 #include <fstream>
 #include <iostream>
-#include <iterator>
+#include <sstream>
 #include <string>
 
 int main() {
-  std::ifstream file("../../app/code/test"
-                     ".qasm");
+  std::ifstream file("program.qasm");
+  if (!file.is_open()) {
+    file.open("../../app/code/test"
+              ".qasm");
+  }
   if (!file.is_open()) {
     std::cerr << "Could not open file\n";
     file.close();
     return 1;
   }
-  const std::string code((std::istreambuf_iterator<char>(file)),
-                         std::istreambuf_iterator<char>());
+
+  std::stringstream buffer;
+  buffer << file.rdbuf();
+
+  const std::string code = buffer.str();
 
   DDSimulationState state;
   createDDSimulationState(&state);

cmake/ExternalDependencies.cmake

@@ -1,7 +1,7 @@
 include(FetchContent)
 set(FETCH_PACKAGES "")
 
-if(BUILD_MQT_DEBUG_BINDINGS)
+if(BUILD_MQT_DEBUGGER_BINDINGS)
   if(NOT SKBUILD)
     # Manually detect the installed pybind11 package.
     execute_process(
@@ -87,7 +87,7 @@ else()
   endif()
 endif()
 
-if(BUILD_MQT_DEBUG_TESTS)
+if(BUILD_MQT_DEBUGGER_TESTS)
   set(gtest_force_shared_crt
       ON
       CACHE BOOL "" FORCE)
@@ -107,7 +107,7 @@ if(BUILD_MQT_DEBUG_TESTS)
   endif()
 endif()
 
-if(BUILD_MQT_DEBUG_BINDINGS)
+if(BUILD_MQT_DEBUGGER_BINDINGS)
   # add pybind11_json library
   if(CMAKE_VERSION VERSION_GREATER_EQUAL 3.24)
     FetchContent_Declare(

docs/.gitignore

@@ -0,0 +1,2 @@
+build/
+doxygen/