Merge pull request #50 from entropicalabs/update_plugins

Update plugins

docs/challenges/intro.md

@@ -10,7 +10,7 @@ We believe some of these challenges may be very interesting for any young quantu
  - **Error Mitigation with Mitiq**: Can we make OpenQAOA compatible with [Mitiq](https://unitary.fund/mitiq.html)?
  - **NVIDIA Backend**: Can we add some of the [NVIDIA](https://docs.nvidia.com/cuda/cuquantum/) simulators to the OpenQAOA stack?
  - **TensorFlow Quantum Simulator**: Add [TensorFlow Quantum](https://www.tensorflow.org/quantum) as a valid simulator to OpenQAOA
- - **Make OpenQAOA compatible with Qiskit Runtime**: [Qiskit Runtime](https://qiskit.org/documentation/partners/qiskit_ibm_runtime/) is an amazing tool to streamline and improve the execution of variational quantum algorithms. Can we make OpenQAOA compatible with it?
+ - **Make OpenQAOA compatible with Qiskit Runtime**: [Qiskit Runtime](https://qiskit.org/ecosystem/ibm-runtime/) is an amazing tool to streamline and improve the execution of variational quantum algorithms. Can we make OpenQAOA compatible with it?
  - **Make OpenQAOA available through qBraid**: [qBraid](https://qbraid.com/) is a fully hosted ecosystem for computing and it would be very nice to have OpenQAOA available to simplify the execution of QAOA computations and enhance QAOA research!
 
 

docs/contributing/add_new_backend.md

@@ -11,18 +11,25 @@ In similar spirit, one can add new backends that add a new hardware provider to
 
 This folder will contain all the necessary code to support the new `XYZ` plugin. 
 Within this folder will be the following files containing instructions to convert the plugin into an installable package:
-- LICENSE: Since OpenQAOA is licensed using MIT License, the individual plugins will follow the same license as well.
-- MANIFEST.in: This file will include the requirements file to install package dependencies for `openqaoa-xyz`
-- pyproject.toml: This file should contain the following instructions
+
+- `LICENSE`: Since OpenQAOA is licensed using MIT License, the individual plugins will follow the same license as well.
+
+- `MANIFEST.in`: This file will include the requirements file to install package dependencies for `openqaoa-xyz`
+
+- `pyproject.toml`: This file should contain the following instructions
+
 	```Python
 	[build-system]
 	requires = ["setuptools>=61.0"]
 	build-backend = "setuptools.build_meta"
 	```
-- README.md: A readme file to describe the plugin
-- requirements.txt: A textfile describing all the necessary python dependencies for the plugin
-- setup.py: Setup instructions to install the package as a python module
-- tests/ : A tests folder containing all backend specific unit-tests for the new plugin
+- `README.md`: A readme file to describe the plugin
+
+- `requirements.txt`: A textfile describing all the necessary python dependencies for the plugin
+
+- `setup.py`: Setup instructions to install the package as a python module
+
+- `tests/` : A tests folder containing all backend specific unit-tests for the new plugin
 
 All the code supporting this new plugin will go inside a `src/openqaoa-xyz/openqaoa_xyz`. The naming conventions of all files and folders are crucial for the proper functioning of the plugin.
 

docs/devices/azure-quantum.md

@@ -73,4 +73,20 @@ az_device.available_qpus
 
 The attribute `check_connection` authenticates your Azure credentials while `available_qpus` returns a list of Azure devices available to your Azure account and specified Workspace.
 
-Once you've selected the desired device, recreate the device object with the selected device's name as `name` in the `create_device` function.
+Once you've selected the desired device, recreate the device object with the selected device's name as `name` in the `create_device` function.
+
+
+## Using Azure job submission or sessions
+
+Now that the device has been created and passed to the QAOA object, `optimize` will perform the job submission to the Azure backend automatically (remember that you need to specify what problem you want to solve with QAOA). OpenQAOA is also compatible with Azure [sessions](https://learn.microsoft.com/en-us/azure/quantum/hybrid-computing-interactive) which allows you to group submitted jobs such that they are prioritized in the queue of the target hardware. Instead of submitting jobs one at a time using the usual
+
+```python
+q.optimize()
+```
+
+, you may create an Azure session using the attributes of `q.device` as follows:
+
+```python
+with q.device.backend_device.open_session(name="QAOA") as session:
+    q.optimize()
+```

docs/devices/device.md

@@ -1,8 +1,8 @@
 # Devices
 
-OpenQAOA gives access to a large set of local simulators, and Quantum Computers hosted on public (and private) clouds.
+Through its selection of plugins, OpenQAOA gives access to a large set of local simulators, and Quantum Computers hosted on public (and private) clouds.
 
-Before going through the details of each provider, please note that  **financial costs** may be associated to the execution of quantum (and classical) computations on public (and private) cloud. Be careful and always make sure you know what you are doing before trying to send a computation to a third party! 
+Before going through the details of each provider, please note that **financial costs** may be associated to the execution of quantum (and classical) computations on public (and private) cloud. Be careful and always make sure you know what you are doing before trying to send a computation to a third party! 
 
 Conversely, all the local simulators run on your own machine and there is no extra cost associated.
 

docs/devices/entropica-labs-vectorized.md

@@ -41,7 +41,7 @@ Firstly, the cost hamiltonian used in QAOAs are diagonal, since they can only co
 
 Secondly, the simulator converts the actions of single and two-pauli rotation gates into permutations of wavefunction coefficients.
 
-If you're interested in the exact procedure used to achieve this, you can check out the vectorized backend docstring [here](https://el-openqaoa.readthedocs.io/en/main/backends.html#openqaoa.backends.simulators.qaoa_vectorized.QAOAvectorizedBackendSimulator).
+If you're interested in the exact procedure used to achieve this, you can check out the vectorized backend docstring [here](https://el-openqaoa.readthedocs.io/en/stable/openqaoa_core/backends.html#openqaoa.backends.qaoa_vectorized.QAOAvectorizedBackendSimulator).
 
 Lastly, since the operations are performed directly on the wavefunction, the memory usage of the simulator scales with $2^{n}$, where n is the number of qubits in the circuit. As compared to $2^{2n}$ if the matrices were not compressed.
 

docs/devices/rigetti-qvm.md

@@ -38,7 +38,7 @@ rigetti_device = create_device(location='qcs', name=f'{n_qubits}q-qvm', **rigett
 q_qvm.set_device(rigetti_device)
 ```
 
-First, this device requires extra arguments. The source code can be viewed [here](https://github.com/entropicalabs/openqaoa/blob/dev/openqaoa/devices.py#L278)
+First, this device requires extra arguments. The source code can be viewed [here](https://github.com/entropicalabs/openqaoa/blob/main/src/openqaoa-pyquil/openqaoa_pyquil/backends/devices.py)
 
 ```Python
 rigetti_args ={

docs/hackatons/bath-challenge.md

@@ -152,7 +152,7 @@ def graph_coloring_qubo(graph, k) -> QUBO:
 ```
 
 !!! hint
-    If you are stuck, and you need some inspiration you can check how some of the other problem classes are structured in OpenQAOA by checking out the [OpenQAOA github page](https://github.com/entropicalabs/openqaoa/tree/main/src/openqaoa-core/problems). In particular, the method `get_qubo_problem()` has the same functionality that you are tackling here. 
+    If you are stuck, and you need some inspiration you can check how some of the other problem classes are structured in OpenQAOA by checking out the [OpenQAOA github page](https://github.com/entropicalabs/openqaoa/tree/main/src/openqaoa-core/openqaoa/problems). In particular, the method `get_qubo_problem()` has the same functionality that you are tackling here. 
 
 
 #### **STEP 2.2. Run QAOA**

docs/install-openqaoa.md

@@ -10,6 +10,23 @@ Once the virtual environment is activated, then simply pip install openqaoa with
 pip install openqaoa
 ```
 
+!!! note
+    This command installs the whole openqaoa package including all available plugins
+
+OpenQAOA is now divided into plugins to let users selectively install modules correspondinng to their needs. Each plugin is available through pip and allows you to access the different providers and backends. Currently, OpenQAOA counts 5 different plugins:
+
+- openqaoa-core: Implements the core functionalities of OpenQAOA and allows you to use standalone simulators.
+- openqaoa-qiskit: Gives access to standalone simulators, qiskit simulators and hardware.
+- openqaoa-braket: Gives access to standalone simulators, braket simulators and hardware, and braket jobs.
+- openqaoa-azure: Gives access to standalone simulators, qiskit simulators and hardware, azure simulators and hardware.
+- openqaoa-pyquil: Gives access to standalone simulators, pyquil simulators and hardware.
+
+Each plugin can be installed using the following command (replacing "core" with the plugin of interest)
+
+```bash
+pip install openqaoa-core
+```
+
 ## Install dev and experimental features
 
 Alternatively, you can install it manually directly from the GitHub. This may be relevant if you plan to contribute to the development of OpenQAOA or if you want to try out the latest features parked on the `dev` branch on our github repository.

docs/problems/knapsack.md

@@ -37,4 +37,66 @@ This cost function can be converted in the form of an Ising formulation (so that
 
 ## Knapsack in OpenQAOA
 
-TODO
+The knapsack problem can be defined by the value of each item, the weight of each item, the total capacity of the knapsack and the penalty associated with overloading the knapsack. We can create the Knapsack problem easily:
+
+```Python
+from openqaoa.problems import Knapsack
+
+knapsack_prob = Knapsack.random_instance(n_items=4, seed=42)
+knapsack_qubo = knapsack_prob.qubo
+```
+
+We can then access the underlying cost hamiltonian 
+
+```Python
+knapsack.qubo.hamiltonian.expression
+```
+
+$$
+-17.0Z_{5} - 18.0Z_{0} - 35.5Z_{3} - 36.0Z_{1} - 52.5Z_{4} - 53.0Z_{6} - 72.0Z_{2} + 116.0 + 12.0Z_{0}Z_{2} + 12.0Z_{1}Z_{3} + 12.0Z_{2}Z_{5} + 18.0Z_{1}Z_{4} + 18.0Z_{1}Z_{6} + 18.0Z_{3}Z_{4} + 18.0Z_{3}Z_{6} + 24.0Z_{1}Z_{2} + 24.0Z_{2}Z_{3} + 27.0Z_{4}Z_{6} + 3.0Z_{0}Z_{5} + 36.0Z_{2}Z_{4} + 36.0Z_{2}Z_{6} + 6.0Z_{0}Z_{1} + 6.0Z_{0}Z_{3} + 6.0Z_{1}Z_{5} + 6.0Z_{3}Z_{5} + 9.0Z_{0}Z_{4} + 9.0Z_{0}Z_{6} + 9.0Z_{4}Z_{5} + 9.0Z_{5}Z_{6}
+$$
+
+You may also check all details of the problem instance in the form of a dictionary:
+
+```Python
+> knapsack_qubo.asdict()
+
+{'constant': 116.0,
+ 'metadata': {},
+ 'n': 7,
+ 'problem_instance': {'n_items': 4,
+                      'penalty': 6,
+                      'problem_type': 'knapsack',
+                      'values': [1, 3, 2, 2],
+                      'weight_capacity': 5,
+                      'weights': [2, 3, 1, 3]},
+ 'terms': [[0, 1],
+           [0, 2],
+           [1, 2],
+           [3, 4],
+           [3, 5],
+           [3, 6],
+           [4, 5],
+           [4, 6],
+           [5, 6],
+           [0, 3],
+           [0, 4],
+           [0, 5],
+           [0, 6],
+           [1, 3],
+           [1, 4],
+           [1, 5],
+           [1, 6],
+           [2, 3],
+           [2, 4],
+           [2, 5],
+           [2, 6],
+           [0],
+           [1],
+           [2],
+           [3],
+           [4],
+           [5],
+           [6]],
+ 'weights': [6.0, 12.0, 24.0, 18.0, 6.0, 18.0, 9.0, 27.0, 9.0, 6.0, 9.0, 3.0, 9.0, 12.0, 18.0, 6.0, 18.0, 24.0, 36.0, 12.0, 36.0, -18.0, -36.0, -72.0, -35.5, -52.5, -17.0, -53.0]}
+```

docs/problems/maximum-cut.md

@@ -43,7 +43,7 @@ plot_graph(G)
 Once the graph is defined, creating a MaxCut problem class requires only a few lines of code:
 
 ```Python
-from openqaoa.problems.problem import MaximumCut
+from openqaoa.problems import MaximumCut
 
 maxcut_prob = MaximumCut(G)
 maxcut_qubo = maxcut_prob.qubo
@@ -59,6 +59,7 @@ $$
 1.0Z_{0}Z_{2} + 1.0Z_{0}Z_{3} + 1.0Z_{0}Z_{4} + 1.0Z_{1}Z_{2} + 1.0Z_{1}Z_{3} + 1.0Z_{1}Z_{5} + 1.0Z_{2}Z_{4} + 1.0Z_{2}Z_{5} + 1.0Z_{3}Z_{5} + 1.0Z_{4}Z_{5}
 $$
 
+You may also check all details of the problem instance in the form of a dictionary:
 
 ```Python
 > maxcut_qubo.asdict()

docs/problems/minimum-vertex-cover.md

@@ -10,7 +10,7 @@ $$
 C(\textbf{x}) = \sum_{i \in V}x_i + P\sum_{(i, j) \in E}\left(1-x_i\right)\left(1-x_j\right),
 $$
 
-where $\textbf{x}\in \{0, 1\}^{|V|}$ and $P>1$ is a parameter controlling the strength of penalization of configurations which are not covers. 
+where $\textbf{x}\in \{0, 1\}^{|V|}$ and $P>1$ is the penalty, a parameter controlling the strength of penalization of configurations which are not covers. 
 
 Interpreting a variable $x_i$ being equal to 1 as being part of the vertex cover, the first summation counts the size of the selected cover while the second summation ensures that the selected cover indeed covers all edges. Hence, minimizing it ensures we find the minimum vertex cover.
 
@@ -35,13 +35,13 @@ plot_graph(G)
 
 ![seed_42_graph](/img/seed_42_graph.png)
 
-Once the graph is defined, creating a MVC problem class requires only a few lines of code:
+Once the graph is defined, creating a MVC problem class requires only a few lines of code, including the graph as well as two extra parameters, field and penalty:
 
 ```Python
-from openqaoa.problems.problem import MinimumVertexCover
+from openqaoa.problems import MinimumVertexCover
 
-mvc_prob = MinimumVertexCover(G)
-mvc_qubo = maxcut_prob.qubo
+mvc_prob = MinimumVertexCover(G, field=1.0, penalty=10)
+mvc_qubo = mvc_prob.qubo
 ```
 
 We can then access the underlying cost hamiltonian 
@@ -50,4 +50,55 @@ We can then access the underlying cost hamiltonian
 mvc_qubo.hamiltonian.expression
 ```
 
-TBA: OUTPUT OF THIS command
+$$
+2.5Z_{0}Z_{2} + 2.5Z_{0}Z_{3} + 2.5Z_{0}Z_{4} + 2.5Z_{1}Z_{2} + 2.5Z_{1}Z_{3} + 2.5Z_{1}Z_{5} + 2.5Z_{2}Z_{4} + 2.5Z_{2}Z_{5} + 2.5Z_{3}Z_{5} + 2.5Z_{4}Z_{5} + 28.0 + 7.0Z_{0} + 7.0Z_{1} + 7.0Z_{3} + 7.0Z_{4} + 9.5Z_{2} + 9.5Z_{5}
+$$
+
+You may also check all details of the problem instance in the form of a dictionary:
+
+```Python
+> mvc_qubo.asdict()
+
+{'constant': 28.0,
+ 'metadata': {},
+ 'n': 6,
+ 'problem_instance': {'G': {'directed': False,
+                            'graph': {},
+                            'links': [{'source': 0, 'target': 2},
+                                      {'source': 0, 'target': 3},
+                                      {'source': 0, 'target': 4},
+                                      {'source': 1, 'target': 2},
+                                      {'source': 1, 'target': 3},
+                                      {'source': 1, 'target': 5},
+                                      {'source': 2, 'target': 4},
+                                      {'source': 2, 'target': 5},
+                                      {'source': 3, 'target': 5},
+                                      {'source': 4, 'target': 5}],
+                            'multigraph': False,
+                            'nodes': [{'id': 0},
+                                      {'id': 1},
+                                      {'id': 2},
+                                      {'id': 3},
+                                      {'id': 4},
+                                      {'id': 5}]},
+                      'field': 1.0,
+                      'penalty': 10,
+                      'problem_type': 'minimum_vertex_cover'},
+ 'terms': [[0, 2],
+           [0, 3],
+           [0, 4],
+           [1, 2],
+           [1, 3],
+           [1, 5],
+           [2, 4],
+           [2, 5],
+           [3, 5],
+           [4, 5],
+           [0],
+           [1],
+           [2],
+           [3],
+           [4],
+           [5]],
+ 'weights': [2.5, 2.5, 2.5, 2.5, 2.5, 2.5, 2.5, 2.5, 2.5, 2.5, 7.0, 7.0, 9.5, 7.0, 7.0, 9.5]}
+```

docs/problems/number-partition.md

@@ -11,12 +11,57 @@ For example, given the set of numbers $S=\{1, 2, 3, 6, 10\}$, one can find that
 
 The function to minimize can be defined as
 
-$$C(\textbf{\sigma}) = \left(\sum_{i=1}^k n_i\sigma_i\right)^2 = \sum_{i, j=1}^kn_in_j\sigma_i\sigma_j,$$
+$$
+C(\sigma) = \left(\sum_{i=1}^k n_i\sigma_i\right)^2 = \sum_{i, j=1}^kn_in_j\sigma_i\sigma_j,
+$$
 
-where $\textbf{\sigma}\in \{-1, 1\}^k$. That is, a variable $\sigma_i$ is attached to each number $n_i$, and the variable's value determines on which side of the partition the number is assigned to. The smallest value $C(\cdot)$ can take is 0, which happens when $\textbf{\sigma}$ is a perfect partition.
+where $\sigma \in \{-1, 1\}^k$. That is, a variable $\sigma_i$ is attached to each number $n_i$, and the variable's value determines on which side of the partition the number is assigned to. The smallest value $C(\cdot)$ can take is 0, which happens when $\sigma$ is a perfect partition.
 
 Since this formulation is already in terms of Ising variables, it can be used directly in QAOA.
 
 ## Number Partitioning in OpenQAOA
 
-TODO
+The Number Partitioning problem is defined by a set of integers, you can thus define the problem as follows:
+
+```Python
+from openqaoa.problems import NumberPartition
+
+int_set = [1,2,3,4,10]
+
+np_prob = NumberPartition(numbers=int_set)
+np_qubo = np_prob.qubo
+```
+
+We can then access the underlying cost hamiltonian 
+
+```Python
+np_qubo.hamiltonian.expression
+```
+
+$$
+12.0Z_{1}Z_{2} + 130 + 16.0Z_{1}Z_{3} + 20.0Z_{0}Z_{4} + 24.0Z_{2}Z_{3} + 4.0Z_{0}Z_{1} + 40.0Z_{1}Z_{4} + 6.0Z_{0}Z_{2} + 60.0Z_{2}Z_{4} + 8.0Z_{0}Z_{3} + 80.0Z_{3}Z_{4}
+$$
+
+You may also check all details of the problem instance in the form of a dictionary:
+
+```Python
+> np_qubo.asdict()
+
+{'constant': 130,
+ 'metadata': {},
+ 'n': 5,
+ 'problem_instance': {'n_numbers': 5,
+                      'numbers': [1, 2, 3, 4, 10],
+                      'problem_type': 'number_partition'},
+ 'terms': [[0, 1],
+           [0, 2],
+           [0, 3],
+           [0, 4],
+           [1, 2],
+           [1, 3],
+           [1, 4],
+           [2, 3],
+           [2, 4],
+           [3, 4]],
+ 'weights': [4.0, 6.0, 8.0, 20.0, 12.0, 16.0, 40.0, 24.0, 60.0, 80.0]}
+```