Port userdoc to mdbook (#141)

* initial structure

* structure updated

* additiond + finished intro

* all files populated

* corrections

* deleting old docs

* correction + missing example

.gitignore

@@ -15,4 +15,5 @@ doc/generated*
 *.vscode*
 *generated*
 tmp*
-*.ipynb_checkpoints*
+*.ipynb_checkpoints*
+*/book/*

book.toml

@@ -0,0 +1,21 @@
+[book]
+title = "HQS qoqo-qryd User Documentation"
+author = "HQS Quantum Simulations GmbH"
+description = "User guide for the roqoqo-qryd/qoqo-qryd packages."
+src = "documentation/src"
+
+[rust]
+edition="2021"
+
+[build]
+build-dir = "documentation/book"
+create-missing = false
+
+[output.html]
+mathjax-support = true
+
+[output.html.search]
+limit-results = 15
+
+[output.html.playground]
+runnable = false

documentation/book.toml

@@ -0,0 +1,6 @@
+[book]
+authors = ["HQS Quantum Simulations", "mlodi-hqs"]
+language = "en"
+multilingual = false
+src = "src"
+title = "HQS qoqo-qryd User Documentation"

documentation/src/SUMMARY.md

@@ -0,0 +1,10 @@
+# Summary
+
+[Index](index.md)
+
+- [Introduction](introduction.md)
+- [Execution](execution.md)
+- [WebAPI](webapi.md)
+- [QRyd Specifics](qrydspecifics.md)
+- [Examples](examples.md)
+- [qoqo-qryd API](qoqo_qryd_api.md)

documentation/src/examples.md

@@ -0,0 +1,21 @@
+qoqo-qryd Examples
+==================
+
+
+Using qubit shift operations
+----------------------------
+```python
+{{#include ../../qoqo-qryd/examples/shift_qubits_example.py}}
+```
+
+Changing the device layout
+--------------------------
+```python
+{{#include ../../qoqo-qryd/examples/switch_layout_example.py}}
+```
+
+Using multi-qubit operations
+----------------------------
+```python
+{{#include ../../qoqo-qryd/examples/multi_qubit_example.py}}
+```

userdoc/src/execution.rst → documentation/src/execution.md

@@ -1,29 +1,26 @@
-Executing quantum programs
+Executing Quantum Programs
 ==========================
 
 To obtain results from a QuantumProgram, Measurement or Circuit it needs to be executed on real quantum computing hardware or run on a simulator.
 
-Qoqo uses separate backends for this evaluation. For each hardware or simulator a backend can be created that implements qoqo's ``EvaluatingBackend`` interface and runs QuantumPrograms. For an overview of backends see the `qoqo <https://github.com/HQSquantumsimulations/qoqo>`_ website. Backends which provide the functionality to run a single circuit are so-called ``EvaluatingBackend``. The QRydDemo backends fall in this category.
+Qoqo uses separate backends for this evaluation. For each hardware or simulator a backend can be created that implements qoqo's ``EvaluatingBackend`` interface and runs QuantumPrograms. For an overview of backends see the [qoqo](https://github.com/HQSquantumsimulations/qoqo) website. Backends which provide the functionality to run a single circuit are so-called ``EvaluatingBackend``. The QRydDemo backends fall in this category.
 
 An ``EvaluatingBackend`` can run:
 
-1. A single circuit. The backend will execute just the circuit and return the measurement results of all registers in a tuple (bit-registers, float-registers, complex-registers). bit_registers is a dictionary of all registers with bit values, float_registers of all registers with float values and complex_registers of all registers with complex values. All the post-processing needs to be done manually.
+1. **A single circuit**. The backend will execute just the circuit and return the measurement results of all registers in a tuple (bit-registers, float-registers, complex-registers). bit_registers is a dictionary of all registers with bit values, float_registers of all registers with float values and complex_registers of all registers with complex values. All the post-processing needs to be done manually.
 
-2. A measurement. All circuits in the measurement are run and the post-processed expectation values are returned.
+2. **A measurement**. All circuits in the measurement are run and the post-processed expectation values are returned.
 
-3. A quantum program. A ``QuantumProgram`` also handles replacement of variables. It provides its own ``run`` method and calls a provided backend internally.
+3. **A quantum program**. A ``QuantumProgram`` also handles replacement of variables. It provides its own ``run`` method and calls a provided backend internally.
 
-As an example we will use the quantum program from :doc:`introduction` and the `qoqo-quest <https://github.com/HQSquantumsimulations/qoqo-quest>`_ simulator backend. Here we show three alternative options that can be ran: a single circuit, a measurement, and a quantum program.
+As an example we will use the quantum program from [Introduction](introduction.md) and the [qoqo-quest](https://github.com/HQSquantumsimulations/qoqo-quest) simulator backend. Here we show three alternative options that can be ran: a single circuit, a measurement, and a quantum program.
 
-
-.. code-block:: python
-
-   from qoqo import Circuit
+```python
+   from qoqo import Circuit, QuantumProgram
    from qoqo import operations as ops
    from qoqo.measurements import PauliZProduct, PauliZProductInput
-   from qoqo import QuantumProgram
    from qoqo_quest import Backend
-   # initialize |psi>
+   # Initialize |psi>
    init_circuit = Circuit()
    # Apply a RotateY gate with a symbolic angle
    # To execute the circuit this symbolic parameter needs to be replaced 
@@ -69,29 +66,30 @@ As an example we will use the quantum program from :doc:`introduction` and the `
 
    # b) To run a measurement we need to replace the free parameter by hand
    executable_measurement = measurement.substitute_parameters({"angle": 0.2})
-   expecation_values = backend.run_measurement(executable_measurement)
-   print(expecation_values)
+   expectation_values = backend.run_measurement(executable_measurement)
+   print(expectation_values)
 
    # c) Run a quantum program
    # The QuantumProgram now has one free parameter that needs to bet set when executing it.
    # The symbolic value "angle" in the circuits will be replaced by that free parameter
    # during execution.
    program = QuantumProgram(measurement=measurement, input_parameter_names=["angle"])
    # Run the program with  0.1 substituting `angle`
-   expecation_values = program.run(backend, [0.1])
+   expectation_values = program.run(backend, [0.1])
+```
 
-Note: The QuantumProgram can be run in the same way with the qoqo_qryd ``SimulatorBackend`` when all quantum operations are replaced by sequences of operations directly supported by the QRydDemo hardware. However, in order to use the qoqo_qryd ``SimulatorBackend``, a device needs to be defined first, as shown in the SimulatorBackend subsection of  :doc:`qrydspecifics`.
+Note: The QuantumProgram can be run in the same way with the qoqo_qryd ``SimulatorBackend`` when all quantum operations are replaced by sequences of operations directly supported by the QRydDemo hardware. However, in order to use the qoqo_qryd ``SimulatorBackend``, a device needs to be defined first, as shown in the SimulatorBackend subsection of [QRyd Specifics](qrydspecifics.md).
 
-In general, to distinguish between a command returning expectation values and a program returning register the command ``run_registers`` is used here.
 
-.. code-block:: python
+In general, to distinguish between a command returning expectation values and a program returning register the command ``run_registers`` is used here.
 
+```python
    from qoqo import Circuit
    from qoqo import operations as ops
    from qoqo.measurements import ClassicalRegister
    from qoqo import QuantumProgram
    from qoqo_quest import Backend
-   # initialize |psi>
+   # Initialize |psi>
    init_circuit = Circuit()
    # Apply a RotateY gate with a symbolic angle
    # To execute the circuit this symbolic parameter needs to be replaced 
@@ -119,14 +117,15 @@ In general, to distinguish between a command returning expectation values and a
    backend = Backend(1)
    (bit_registers, float_registers, complex_registers) = program.run_registers(backend, [0.1])
    print(bit_registers)
+```
 
 
 Executing QuantumPrograms without returning expecation values
 ---------------------------------------------------------------------
 
-As described in :doc:`introduction` the ``ClassicalRegister`` measurement can be used to return the full measurement record. 
+As described in [Introduction](introduction.md) the ``ClassicalRegister`` measurement can be used to return the full measurement record. 
 
 Non-executing backends
 ----------------------
 
-Qoqo also has backends that cannot be used to run or evaluate a quantum circuit. These backends typically are used to translate qoqo circuits to other quantum toolkits or languages. One example is `qoqo_qasm <https://github.com/HQSquantumsimulations/qoqo_qasm>`_ .
+Qoqo also has backends that cannot be used to run or evaluate a quantum circuit. These backends typically are used to translate qoqo circuits to other quantum toolkits or languages. One example is [qoqo_qasm](https://github.com/HQSquantumsimulations/qoqo_qasm)

userdoc/index.rst → documentation/src/index.md

@@ -1,61 +1,44 @@
 Welcome to the qoqo-qryd/roqoqo-qryd user documentation!
 ========================================================
 
-This software is designed to support the `QRydDemo <https://thequantumlaend.de/qryddemo/>`_ project on quantum computing with Rydberg atoms. It provides components to support QRydDemo quantum computers based on the `qoqo <https://github.com/HQSquantumsimulations/qoqo>`_ quantum toolkit by `HQS Quantum Simulations <https://quantumsimulations.de>`_ used to represent quantum circuits.
+This software is designed to support the [QRydDemo](<https://thequantumlaend.de/qryddemo/>) project on quantum computing with Rydberg atoms. It provides components to support QRydDemo quantum computers based on the [qoqo](<https://github.com/HQSquantumsimulations/qoqo>) quantum toolkit by [HQS Quantum Simulations](<https://quantumsimulations.de>) used to represent quantum circuits.
 
-To learn more about the general approach to create quantum programs and executing them in qoqo see :doc:`src/introduction` and :doc:`src/execution`.
+To learn more about the general approach to create quantum programs and executing them in qoqo see [Introduction](src/introduction.md) and [Execution](src/execution.md).
 
 This software is split into two packages:
 
 * roqoqo-qryd: Implementing the core functionality and a Rust interface.
 * qoqo-qryd: The Python interface.
 
+The packages are based on the open source [qoqo](<https://github.com/HQSquantumsimulations/qoqo>) quantum computing toolkit.
 
-The packages are based on the open source `qoqo <https://github.com/HQSquantumsimulations/qoqo>`_ quantum computing toolkit.
-
-The packages provide the following functionalities:
 
 Interface to the current QRydDemo WebAPI
 ----------------------------------------
 
 At the moment QRydDemo WebAPI allows access to Quantum Hardware Emulators of different device topologies. 
-qoqo-qryd/roqoqo-qryd support interfacing with the corresponding REST-API with low level calls, i.e. using `Circuit`,  as well as with high-level backend based functionalities, i.e. by using `QuantumPrograms` in qoqo. For more details see :doc:`src/webapi`.
+qoqo-qryd/roqoqo-qryd support interfacing with the corresponding REST-API with low level calls, i.e. using `Circuit`,  as well as with high-level backend based functionalities, i.e. by using `QuantumPrograms` in qoqo. For more details see [WebAPI](webapi.md).
+
 
 QRydDemo specific hardware operations (prototype)
 -------------------------------------------------
 
 Rydberg atom based quantum devices support, in principle, operations not commonly found in other quantum hardware.
 Changes in device topology are one of these operations. 
-roqoqo-qryd/qoqo-qryd adds support for changes in device topology to qoqo. For more details see :doc:`src/qrydspecifics`.
+roqoqo-qryd/qoqo-qryd adds support for changes in device topology to qoqo. For more details see [QRyd Specifics](qrydspecifics.md).
 Note that this is a preview prototype and does not represent a finalized set of operations on the QRydDemo hardware.
 
+
 Local simulator supporting specific hardware operations
 -------------------------------------------------------
 
-qoqo-qryd/roqoqo-qryd include a local `QuEST <https://github.com/QuEST-Kit/QuEST>`_ based simulator for quantum devices supporting the Rydberg specific quantum operations. The simulator is intended to let users test the capabilities of quantum hardware with the additional operations. For more details see :doc:`src/qrydspecifics`. Note that the devices for the simulator do not represent a finalized design for QRydDemo.
-
-
-A collection of example python programs can be found in :doc:`src/examples`.
-
-.. toctree::
-   :maxdepth: 2
-   :caption: Contents:
-
-   src/installation.md
-   src/introduction
-   src/execution
-   src/webapi
-   src/qrydspecifics
-   src/examples
-   src/qoqo_qryd_api
+qoqo-qryd/roqoqo-qryd include a local [QuEST](https://github.com/QuEST-Kit/QuEST>) based simulator for quantum devices supporting the Rydberg specific quantum operations. The simulator is intended to let users test the capabilities of quantum hardware with the additional operations. For more details see [QRyd Specifics](qrydspecifics.md). Note that the devices for the simulator do not represent a finalized design for QRydDemo.
 
 
-Indices and tables
-==================
+Examples
+--------
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+A collection of example python programs can be found in [Examples](examples.md).
 
 
 OpenSSL