Merge pull request #47 from cirKITers/docs

Documentation

CONTRIBUTING.md

@@ -59,11 +59,8 @@ We use MkDocs for our documentation. To run a server locally, run:
 ```
 poetry run mkdocs serve
 ```
-
-If you make changes to the documentation in the meantime, trigger a build by running
-```
-poetry run mkdocs build
-```
+This will automatically trigger a rebuild each time you make changes.
+See the [MkDocs Documentation](https://cirkiters.github.io/qml-essentials/usage/) for more details.
 
 For pushing to Github pages:
 ```

docs/ansaetze.md

@@ -0,0 +1,13 @@
+# Ansaetze
+
+.. or Ansatzes as preferred by the english community.
+Anyway, we got various of the most-used Ansaetze implemented in this package.
+
+You can load them manually by
+```python
+from qml_essentials.ansaetze import Ansaetze
+print(Ansaetze.get_available())
+```
+
+However, usually you just want reference to them (by name) when instantiating a model.
+To get an overview of all the available Ansaetze, checkout the [references](https://cirkiters.github.io/qml-essentials/references/).

docs/coefficients.md

@@ -0,0 +1,18 @@
+# Coefficients
+
+A characteristic property of any Fourier model are its coefficients.
+Our package can, given a model, calculate the corresponding coefficients by utilizing the [Pennylane Fourier Coefficients](https://docs.pennylane.ai/en/stable/_modules/pennylane/fourier/coefficients.html) method.
+
+In the simplest case, this could look as follows:
+```python
+from qml_essentials.model import Model
+from qml_essentials.coefficients import Coefficients
+
+model = Model(
+            n_qubits=2
+            n_layers=1
+            circuit_type="HardwareEfficient",
+        )
+
+coeffs = Coefficients.sample_coefficients(model)
+```

docs/entanglement.md

@@ -0,0 +1,30 @@
+# Entanglement
+
+As one of the fundamental aspects of quantum computing, entanglement plays also an important role in quantum machine learning.
+Our package offers methods for calculating the entangling capability of a particular model.
+Currently, only the "Meyer-Wallach" measure is implemented, but other will be added soon!
+
+In the simplest case, this could look as follows:
+```python
+from qml_essentials.model import Model
+from qml_essentials.entanglement import Entanglement
+
+model = Model(
+            n_qubits=2,
+            n_layers=1,
+            circuit_type="HardwareEfficient",
+        )
+
+ent_cap = Entanglement.meyer_wallach(
+    model, n_samples=1000, seed=1000
+)
+```
+
+Note, that every function in this class accepts keyword-arguments which are being passed to the model call, so you could e.g. enable caching by
+```python
+ent_cap = Entanglement.meyer_wallach(
+    model, n_samples=1000, seed=1000, cache=True
+)
+```
+
+If you set `n_samples=None`, we will use the currently stored parameters of the model to estimate the degree of entanglement.

docs/expressibility.md

@@ -0,0 +1,36 @@
+# Expressibility
+
+Our package includes tool to estimate the expressiblity of a particularly chosen Ansatz.
+
+```python
+model = Model(
+    n_qubits=2,
+    n_layers=1,
+    circuit_type=HardwareEfficient,
+)
+
+input_domain, bins, dist_circuit = Expressibility.state_fidelities(
+    n_bins=10,
+    n_samples=200,
+    n_input_samples=5,
+    seed=1000,
+    model=model,
+)
+```
+
+Note that `state_fidelities` accepts keyword arguments that are being passed to the model call.
+This allows you to utilize e.g. caching.
+
+Next, you can calculate the Haar integral (as reference), by
+```python
+input_domain, dist_haar = Expressibility.haar_integral(
+    n_qubits=2,
+    n_bins=10,
+    cache=False,
+)
+```
+
+Finally, the Kullback-Leibler divergence allows you to see how well the particular circuit performs compared to the Haar integral:
+```python
+kl_dist = Expressibility.kullback_leibler_divergence(dist_circuit, dist_haar).mean()
+```

docs/index.md

@@ -1,19 +1,4 @@
 [![Pipx Status](https://servers.stroblme.de/api/badge/3/uptime/72?color=%2331c754&labelColor=%233f4850)](https://servers.stroblme.de/status/open) [![Lint and Pytest](https://github.com/cirKITers/qml-essentials/actions/workflows/python-app.yml/badge.svg)](https://github.com/cirKITers/qml-essentials/actions/workflows/python-app.yml) [![Page Build](https://github.com/cirKITers/qml-essentials/actions/workflows/pages/pages-build-deployment/badge.svg)](https://github.com/cirKITers/qml-essentials/actions/workflows/pages/pages-build-deployment)
 
 This repo contains some of the commonly used Ansaetze and coding stuff required for working with QML and Data-Reuploading models.
-There are also dedicated classes to calculate entanglement and expressiblity of a provided model as well as its Fourier coefficients.
-
-## Installation
-
-The package is available at [this index](https://ea3a0fbb-599f-4d83-86f1-0e71abe27513.ka.bw-cloud-instance.org/lc3267/quantum).
-
-There are two installation methods:
-
-### [Poetry](https://python-poetry.org/)
-
-- `poetry source add --priority=supplemental quantum https://ea3a0fbb-599f-4d83-86f1-0e71abe27513.ka.bw-cloud-instance.org/lc3267/quantum/+simple/`
-- `poetry add --source quantum qml-essentials`
-
-### pip
-
-- `pip install --index-url https://ea3a0fbb-599f-4d83-86f1-0e71abe27513.ka.bw-cloud-instance.org/lc3267/quantum/+simple/ qml-essentials`
+There are also dedicated classes to calculate entanglement and expressiblity of a provided model as well as its Fourier coefficients.

docs/setup.md

@@ -0,0 +1,14 @@
+# Setup
+
+The package is available at [this index](https://ea3a0fbb-599f-4d83-86f1-0e71abe27513.ka.bw-cloud-instance.org/lc3267/quantum).
+
+There are two installation methods:
+
+### [Poetry](https://python-poetry.org/)
+
+- `poetry source add --priority=supplemental quantum https://ea3a0fbb-599f-4d83-86f1-0e71abe27513.ka.bw-cloud-instance.org/lc3267/quantum/+simple/`
+- `poetry add --source quantum qml-essentials`
+
+### pip
+
+- `pip install --index-url https://ea3a0fbb-599f-4d83-86f1-0e71abe27513.ka.bw-cloud-instance.org/lc3267/quantum/+simple/ qml-essentials`

docs/usage.md

@@ -0,0 +1,72 @@
+# Usage
+
+Central component of our package is the Fourier model which you can import with 
+```python
+from qml_essentials.model import Model
+```
+
+In the simplest scenario, one would instantiate such a model with $2$ qubits and a single layer using the "Hardware Efficient" ansatz by:
+```python
+model = Model(
+    n_qubits=2
+    n_layers=1
+    circuit_type="HardwareEfficient"
+)
+```
+
+You can take a look at your model, by simply calling
+```python
+print(model)
+```
+
+Calling the model without any (`None`) values for the `params` and `inputs` argument, will implicitly call the model with the recently (or initial) parameters and `0`s as input.
+
+In the following we will describe some concepts of this class.
+For a more detailled reference on the methods and arguments that are available, please see the [references page](https://cirkiters.github.io/qml-essentials/references).
+
+## The essentials
+
+There is much more to this package, than just providing a Fourier model.
+You can calculate the [Expressibility](expressibility.md) or [Entangling Capability](entanglement.md) besides the [Coefficients](coefficients.md) which are unique to this kind of QML interpretation.
+Also checkout the available [Ansaetze](ansaetze.md) that we provide with this package.
+
+## Output Shape
+
+The output shape is determined by the `output_qubit` argument, provided in the instantiation of the model.
+When set to -1 all qubits are measured which will result in the shape being of size $n$ by default (depending on the execution type, see below).
+
+If `force_mean` flag is set when calling the model, the output is averaged to a single value (while keeping the batch dimension).
+
+## Execution Type
+
+Our model be simulated in different ways by setting the `execution_type` property, when calling the model, to:
+- `exp_val`: Returns the expectation value between $0$ and $1$
+- `density`: Calculates the density matrix
+- `probs`: Simulates the model with the number of shots, set by `model.shots`
+
+## Noise
+
+Noise can be added to the model by providing a `noise_params` argument, when calling the model, which is a dictionary with following keys
+- `BitFlip`
+- `PhaseFlip`
+- `AmplitudeDamping`
+- `PhaseDamping`
+- `DepolarizingChannel`
+with values between $0$ and $1$.
+
+This will apply the corresponding noise in each layer with the provided factor.
+
+## Caching
+
+To speed up calculation, you can add `cache=True` when calling the model.
+The result of the model call will then be stored in a numpy format in a folder `.cache`.
+Each result is being identified by a md5 hash that is a representation of the following model properties:
+- number of qubits
+- number of layers
+- ansatz
+- data-reuploading flag
+- parameters
+- noise parameters
+- execution type
+- inputs
+- output qubit(s)

mkdocs.yml

@@ -1,4 +1,14 @@
 site_name: QML Essentials
+nav:
+  - index.md
+  - setup.md
+  - usage.md
+  - Advanced:
+    - ansaetze.md
+    - coefficients.md
+    - entanglement.md
+    - expressibility.md
+  - references.md
 theme:
   name: material
   highlightjs: true