diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b9f14a6..4f237f9 100644 --- a/CONTRIBUTING.md +++ b/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: ``` diff --git a/docs/ansaetze.md b/docs/ansaetze.md new file mode 100644 index 0000000..ce86e3e --- /dev/null +++ b/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/). \ No newline at end of file diff --git a/docs/coefficients.md b/docs/coefficients.md new file mode 100644 index 0000000..55c8070 --- /dev/null +++ b/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) +``` \ No newline at end of file diff --git a/docs/entanglement.md b/docs/entanglement.md new file mode 100644 index 0000000..4fc414b --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/expressibility.md b/docs/expressibility.md new file mode 100644 index 0000000..b3c4834 --- /dev/null +++ b/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() +``` \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index b30b4dc..b343a1c 100644 --- a/docs/index.md +++ b/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. \ No newline at end of file diff --git a/docs/setup.md b/docs/setup.md new file mode 100644 index 0000000..78200cc --- /dev/null +++ b/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` \ No newline at end of file diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 0000000..19c2458 --- /dev/null +++ b/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) \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 91193e0..4c667a3 100644 --- a/mkdocs.yml +++ b/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