update docs

docs/source/algorithms.rst

@@ -1,6 +1,16 @@
 Algorithms
 ====================================
 
+Qlasskit implements high level representation of quantum algorithms that relies on black boxes functions and oracles.
 
 Grover search
 -----------------
+
+
+Simon periodicity
+----------------------
+
+
+
+Deutsch Jozsa
+----------------------

docs/source/example_grover.ipynb

@@ -6,7 +6,8 @@
    "source": [
     "# Grover search\n",
     "\n",
-    "We define a function named `and_all` that returns `True` iff all the element of an input list `a_list` are `True`. We want to use a Grover search to find the input value that led to a `True` result of the function."
+    "Qlasskit offer a class to easily perform a `Grover` search over a qlasskit oracle. \n",
+    "First, we define a function named `and_all` that returns `True` iff all the element of an input list `a_list` are `True`. We want to use a Grover search to find the input value that led to a `True` result of the function."
    ]
   },
   {
@@ -104,9 +105,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Now we can use our prefered framework and simulator for sampling the result; this is an example using `qiskit` with `aer_simulator`.\n",
+    "Then we use our prefered framework and simulator for sampling the result; this is an example using `qiskit` with `aer_simulator`.\n",
     "\n",
-    "The `Grover` class, along with all circuit wrappers in qlasskit, provides utilities to encode inputs and decode outputs from a quantum circuit using the high level type definition. In the output histogram, it's now evident that the input leading to a `True` result in the `and_all` function is a list where all elements are set to `True`, aligning with our expectations.\n"
+    "The `Grover` class, along with all circuit wrappers in qlasskit, provides utilities to encode inputs and decode outputs from a quantum circuit using the high level type definitions. In the output histogram, it's now evident that the input leading to a `True` result in the `and_all` function is a list where all elements are set to `True`, aligning with our expectations.\n"
    ]
   },
   {

docs/source/example_grover_hash.ipynb

@@ -62,7 +62,7 @@
    "source": [
     "We got that `hash_simp` is following an uniform distribution. \n",
     "\n",
-    "We now can use our quantum function as an oracle for a Grover search, in order to find which input maps to the value `ca`."
+    "Now we use our quantum function as an oracle for a Grover search, in order to find which input maps to the value `0xca`."
    ]
   },
   {
@@ -80,7 +80,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Now we can use our prefered framework and simulator for sampling the result; this is an example using `qiskit` with `aer_simulator`."
+    "Then we use our prefered framework and simulator for sampling the result; this is an example using `qiskit` with `aer_simulator`."
    ]
   },
   {
@@ -119,7 +119,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "We now double check using `original_f`; calling it with the tuple `(12,12)` must result in the hash value `0xca`."
+    "Using `QlassF.original_f` we can double check the result without invoking a quantum simulator; calling it with the tuple `(12,12)` must result in the hash value `0xca`."
    ]
   },
   {

docs/source/example_grover_subset.ipynb

@@ -28,7 +28,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "We now can use our quantum function as an oracle for a Grover search. For instance, we want to find the input value that produce the value `7`. Since we know that there are at least two result (`(i,j)` and `(j,i)`), we set `n_matching=2`."
+    "Our quantum function `subset_sum` will be used as an oracle for a Grover search. For instance, here we want to find the input value that produce the value `7`. Since we know that there are at least two result (`(i,j)` and `(j,i)`), we set `n_matching=2`."
    ]
   },
   {
@@ -46,7 +46,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Now we can use our prefered framework and simulator for sampling the result; this is an example using `qiskit` with `aer_simulator`.\n",
+    "Then we use our prefered framework and simulator for sampling the result; this is an example using `qiskit` with `aer_simulator`.\n",
     "\n",
     "In the output histogram, it's now evident that the input leading to a value of `7` are the tuples `(1,2)` and `(2,1)` (5+2 and 2+5), aligning with our expectations.\n"
    ]

docs/source/example_grover_sudoku.ipynb

@@ -6,10 +6,10 @@
    "source": [
     "# Grover search: sudoku solver\n",
     "\n",
-    "In this example we are going to solve a sudoku puzzle. Since we have few qubits, we need to simplify the puzzle and so we use a 2x2 matrix where a valid solution is when in every row and every column there are no repeated values (`0` or `1`). We encode these xor-ing the values for each row and column. \n",
+    "In this example we are going to solve a sudoku puzzle. Since we have few qubits, we cannot solve a real 9x9 sudoku puzzle; our toy examples uses a 2x2 matrix where a valid solution is when in every row and every column there are no repeated values (`0` or `1`). We encode these xor-ing the values for each row and column. \n",
     "Since we want a specific solution, we add a constraint `constr`: we want the `[0][0]` element to be `True`.\n",
     "\n",
-    "We instantiate the `Grover` algorithm without value, since sudoku_check is already an oracle."
+    "`sudoku_check` is already an oracle so this time we instantiate the `Grover` algorithm without value."
    ]
   },
   {
@@ -37,7 +37,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Now we can use our prefered framework and simulator for sampling the result; this is an example using `qiskit` with `aer_simulator`.\n",
+    "Then we use our prefered framework and simulator for sampling the result; this is an example using `qiskit` with `aer_simulator`.\n",
     "\n",
     "We obtain that the solution for this puzzle is the matrix `[[True, False], [False, True]]`."
    ]

docs/source/example_unitary_of_f.ipynb

@@ -4,7 +4,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Unitary of qlasskit function"
+    "# Unitary of qlasskit function\n",
+    "\n",
+    "In qlasskit, we can exploit external low-level frameworks to perform operations on the resulting quantum circuit. In this example, we use qiskit in order to obtain the unitary matrix of our `QlassF` function."
    ]
   },
   {

docs/source/quickstart.ipynb

@@ -59,7 +59,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The qlassf function can be also exported as a gate, if the destination framwork supports it. We can use `encode_input` and `decode_output` in order to conver from/to high level types of qlasskit without worrying about the binary representation."
+    "The qlassf function can be also exported as a gate, if the destination framwork supports it. We can use `encode_input` and `decode_output` in order to convert from/to high level types of qlasskit without worrying about the binary representation."
    ]
   },
   {
@@ -127,8 +127,14 @@
   }
  ],
  "metadata": {
+  "kernelspec": {
+   "display_name": "qlasskit_310-env",
+   "language": "python",
+   "name": "python3"
+  },
   "language_info": {
-   "name": "python"
+   "name": "python",
+   "version": "3.10.13"
   }
  },
  "nbformat": 4,

setup.py

@@ -34,7 +34,7 @@
         "Programming Language :: Python :: 3.10",
         "Programming Language :: Python :: 3.11",
         "Programming Language :: Python :: 3.12",
-    ],    
+    ],
     url="https://github.com/dakk/qlasskit",
     project_urls={
         "Bug Tracker": "https://github.com/dakk/qlasskit/issues/",