improve explanations

Author: Dror Segman

tutorials/Classiq_tutorial/Qmod_tutorial_part1.ipynb

@@ -89,17 +89,18 @@
     "2. Function `main`:\\\n",
     "   A complete Qmod model, that is, a description that can be synthesized and executed, must define a function called `main`. Function `main` is the quantum entry point - it specifies the inputs and outputs of the quantum program, that is, its interface with the external classical execution logic. Similar to conventional programming languages, function `main`, can call other functions.\n",
     "\n",
-    "3. Quantum variable initialization:\\\n",
-    "    ## TODO: Dror - variables are initialized to reference some quantum object..\n",
-    "   Every quantum variable must be initialized. Initialization means __allocating qubits to the variable and determining its initial state__. There are several ways to initialize a quantum variable:\n",
-    "   - The simplest way (demonstrated above) is using `allocate`. It can optionally specify the number of qubits to be allocated to the variable. The state of all these qubits is automatically set to the default $|0\\rangle$. \n",
-    "   - More methods (to be covered later) include assigning an arithmetic expression to the variable, or passing it as argument to an output parameter of a function - such methods automatically determine the number of qubits to allocate based on the information that we wish the variable to represent.\n",
+    "3. Working with quantum variables:\\\n",
+    "   Quantum objects (numeric, boolean or other values that are stored in specific qubits) are managed in Qmod using quantum variables. All variables need to be declarded and initialized.\\\n",
+    "   The model above demonstrates two important kinds of declaration:\n",
+    "   -  Function `foo` declares `q` as follows: `q: QBit`. Such declaration (a normal, or \"inout\" declaration) means that `foo` expects to be passed an already-initialized variable `q`, of type `QBit`.\n",
+    "   -  Function `main` declares `q` as follows: `q: Output[QBit]`. Such declaration means that `q` is only an output - it is to be initialized inside the scope of `main`.\\\n",
     "   \n",
-    "4. The `Output` modifier:\\\n",
-    "   The `Output` modifier indicates that a quantum variable is not initialized outside the scope of the function, and hence must be initialized inside the scope of the function.\\\n",
-    "   For example, in the above `main` function definition, `q` is declared with the `Output` modifier, so `main` expects it to not yet be initialized when called. `foo`, on the other hand, declares its input `q` without the modifier, hence it is essential to initialize `q` before passing it to `foo` (see the call to `allocate` in the code).\n",
-    "   - Since `main` is the quantum entry point, all of its inputs must be declared with the `Output` modifier. Please take a moment to think about it: suppose that we would decalre an input `x` to `main` without the `Output` modifier. It follows that `x` must have been initialized before calling `main`, and was passed to main already initialized, but it would be impossible because `main` is the origin of any quantum logic - all its external interfaces are classical.\n",
-    "   - Other functions can declare their inputs with or without the `Output` modifier depending on wether or not they expect them to be initialized when called."
+    "   The meaning of initialization is specifying to which quantum object the variable refers. Without initialization, a variable is just \"a name\", not pointing to any specific object, and hence no operation can be done it. There are several ways to initialize variables in Qmod:\n",
+    "   -  One way is using `allocate`. An `allocate` statement allocates yet-unused qubits to the variable.\n",
+    "   -  Other ways include arithmetic assignment, state-preparation and more.\n",
+    "  \n",
+    "   Note: it is useful to notice that all the variables in `main` must be declared as `Output`, as `main` is the entry point of the model (Think about it: where could a variable be initialized before `main` was called?). Other functions use both kinds of declaration.\n",
+    "    "
    ]
   },
   {
@@ -108,7 +109,7 @@
    "source": [
     "### Exercise #0\n",
     "Rewrite the above model, so that `q` is initilized inside `foo`.\\\n",
-    "Solution is provided in the end of the notebook.\\\n",
+    "A solution is provided in the end of the notebook.\\\n",
     "Hint: it only requires to move one line of code and add the `Output` modifier in the correct place."
    ]
   },