Update docs

Author: lorenzotomada

docs/Documentation.ipynb

@@ -743,20 +743,20 @@
    "source": [
     "# Profiling of Divide and Conquer (memory and time)\n",
     "We discuss the results of the profiling of the Divide et Impera algorithm.\n",
-    "Profiling is performed using the `submit.sh` file in the `shell` folder, which internally \n",
+    "Profiling is performed using the `submit.sh` file in the `shell` folder, which internally calls `scripts/profiling_memory_and_time.py`. \n",
     "We begin by discussing the memory consumption of the method, studying how it varies with respect to the matrix size and number of processes, and comparing it to `numpy`'s and `scipy`'s `eig` built-in function.\n",
     "\n",
     "*IMPORTANT*: please notice that we did not use `scipy.sparse`'s solver as it cannot be used to retrieve all the eigenvalues, which would have make the comparison unfair.\n",
     "\n",
     "![Memory profiling](plots/memory_profiling.png)\n",
     "\n",
-    "It is possible to see that cumulative memory consumption does not really depend on the number of processes, and that for low values of $n$ it behaves better than `numpy` and `scipy`, while performance degradates for high values of $n$.\n",
+    "It is possible to see that cumulative memory consumption increases as the number of processes does.\n",
     "\n",
     "Now we do the same for runtime vs matrix size and number of processes.\n",
     "\n",
-    "![Time profiling](images/plot_time.png)\n",
+    "![Time profiling](plots/time_profiling.png)\n",
     "\n",
-    "Based on this plot, we would be tempted to say that not only the execution time is much bigger that it is for `numpy` and `scipy`, but it might also seem that our method does not scale with respect to the number of processes.\n",
+    "Based on the previous plot, we would be tempted to say that not only the execution time is much bigger that it is for `numpy` and `scipy`, but also that our method does not scale with respect to the number of processes.\n",
     "However, running a single time the file `shell/time_profile.sh`, we notice that this is likely a problem related to how `time.time()` saves the results.\n",
     "\n",
     "Running, for instance,\n",
@@ -765,21 +765,35 @@
     "```\n",
     "we get the following results:\n",
     "```mermaid\n",
-    "Some results\n",
+    "[D&I] Total execution time: 0.3199 s\n",
+    "[NumPy] Total execution time: 0.0388 s\n",
+    "[SciPy] Total execution time: 0.0690 s\n",
     "```\n",
     "Re-running with `n_procs=2`, we obtain\n",
     "```mermaid\n",
-    "Even more results\n",
+    "[D&I] Total execution time: 0.2230 s\n",
+    "[NumPy] Total execution time: 0.8741 s\n",
+    "[SciPy] Total execution time: 0.0364 s\n",
     "```\n",
     "Finally, for `n_procs=4`, we obtain\n",
     "```mermaid\n",
-    "Final results\n",
+    "[D&I] Total execution time: 0.1842 s\n",
+    "[NumPy] Total execution time: 0.0768 s\n",
+    "[SciPy] Total execution time: 0.0362 s\n",
     "```\n",
+    "(notice that there is some variance in the times taken by the other two methods as a result of the fact that `time.time()` is not extremely robust).\n",
+    "\n",
     "The previous results suggest that the method scales well with the number of processes, and that the performance (while worse than `numpy` and `scipy`) is such that the comparison goes much better than it seemed to do earlier.\n",
     "We believe that the reason for such a behavior is related to the execution of multiple scripts, which can have an impact on execution times as measured with `time.time()`.\n",
     "\n",
     "Notice that we parallelized everything that could be parallelized (except for the secular solver, which usually takes no more than $5\\%$ of the total time): the bottleneck is given by the Lanczos method, which cannot be parallelized.\n",
-    "If the Lanczos method is not needed (that is, if the matrix $A$ of which we want to compute the eigenvalues and eigenvectors is already tridiagonal), then the execution time of our solver becomes comparable to the one of `numpy` and `scipy`."
+    "If the Lanczos method is not needed (that is, if the matrix $A$ of which we want to compute the eigenvalues and eigenvectors is already tridiagonal), then the execution time of our solver becomes comparable to the one of `numpy` and `scipy`.\n",
+    "\n",
+    "*Remark*: in the plot used to profile execution times, the Lanczos method takes bigger values than D&I when just one process is used.\n",
+    "Of course this is not possible, since D&I includes Lanczos.\n",
+    "However, the value that we plot for all the functions not depending on `n_procs` (including the ones of `numpy` and `scipy` and Lanczos) is the average across all the runs with different numbers of processes.\n",
+    "As a result, similar to what was remarked earlier for `numpy`'s eigenvalues solver, the execution time for large values of `n_procs` seems to increase, causing the average to become bigger, eventually getting bigger than D&I. \n",
+    "However, notice that also this time running a single simulation with `shell/time_profile.sh` tells us that this is not truly the case, and that the execution time of the Lanczos algorithm remains pretty much the same as the number of processes increases. "
    ]
   },
   {