edit concurrency chapter

Author: Kristian Rother

concurrency/README.rst

@@ -8,28 +8,23 @@ good reasons to be very cautious with it.
 
 ----
 
-Why is Concurrency risky?
--------------------------
+Pros and Cons of Concurrency
+----------------------------
 
-Many times, the devil is so much in the details that it is even a bad idea.
+Often concurrency is a bad idea. The devil is lurking in the details:
 
 -  Coordinating parallel sub-programs is very difficult to debug (look up the words *“race condition”* and *“heisenbug”*).
--  Starting multiple Python processes instead is really easy (e.g. from a batch script or the `multiprocessing` module).
 -  Python has a strange thing called the **GIL (Global Interpreter Lock)**. That means, Python can really only execute one command at a time.
--  There are great existing solutions for the most typical applications.
+-  There are great existing solutions for many typical applications (web scraping, web servers).
 
-----
-
-When could concurrency be a good idea?
---------------------------------------
+On the other hand, concurrency can be a good idea:
 
-Here is one example:
+-  if your tasks are waiting for some I/O anyway, the speed of Python does not matter.
+-  starting multiple separate Python processes is rather easy (with the `multiprocessing` module).
+-  if you are looking for a challenge.
 
-You are writing a computer game for fun and would like many sprites to
-move at the same time **AND** you are looking for difficult problems to solve.
-
-There are two noteworthy approaches to concurrency in Python:
-**threads** and **coroutines**.
+There are three noteworthy approaches to concurrency in Python:
+**threads**, **coroutines** and **multiple processes**.
 
 ----
 
@@ -64,14 +59,19 @@ This is the most flexible approach, but also has the highest overhead.
 
 .. literalinclude:: factorial.py
 
-
 ----
 
-Alternatives
-------------
+Challenge: Gaussian Elimination
+-------------------------------
+
+In :download:`gauss_elim.py` you find an implementation of the `Gauss Elimination Algorithm <https://en.wikipedia.org/wiki/Gaussian_elimination>`__ to solve linear equation systems.
+The algorithm has a **cubic time complexity**.
+
+Parallelize the execution of the algorithm and check whether it gets any faster.
+
+In :download:`test_gauss_elim.py` you find unit tests for the module.
 
--  if you want to read/write data, use a database
--  if you want to scrape web pages, use the ``scrapy`` framework.
--  if you want to build a web server, use ``FastAPI`, ``Flask`` or ``Django``.
--  if you want to do number crunching, use ``Spark``, ``Dask``, ``Pytorch`` or ``Tensorflow``
+.. note::
 
+   The linear equation solver is written in plain Python.
+   Of course, Numpy would also speed up the execution considerably.

concurrency/gauss_elim.py

@@ -0,0 +1,56 @@
+
+from copy import deepcopy
+import numpy as np
+
+def solve_linear(data: list[float]) -> list[float]:
+    """solves linear equations with the Gauss Elimination method"""
+    nrows = len(data)
+    ncols = len(data[0])
+    M = deepcopy(data)
+    for i in range(ncols - 1):
+        # normalize each row by position i
+        for row in M[i:]:
+            first = row[i]
+            for j in range(i, ncols):
+                row[j] = row[j] / first
+        # subtract equation i from all
+        for j in range(i + 1, nrows):
+            for k in range(i, ncols):
+                M[j][k] -= M[i][k]
+    
+    # retrieve coefficients from triangular form
+    coef = [0.0] * nrows
+    for i in range(nrows - 1, -1, -1):  # process rows in reverse order
+        temp = 0.0
+        for j in range(i + 1, ncols - 1):
+            temp -= M[i][j] * coef[j]
+        temp += M[i][-1]
+        coef[i] = temp
+
+    return coef
+
+
+def create_linear_equation_sys(size):
+    """creates a solvable linear equation system"""
+    A = np.random.rand(size, size)
+    # Ensure matrix A is invertible by checking the determinant
+    while np.linalg.det(A) == 0:
+        A = np.random.rand(size, size)
+
+    solution = np.random.randint(-100, 100, size=size)  # random solution vector
+
+    b = np.dot(A, solution)  # right-hand-side vector
+
+    mtx = np.hstack([A, b.reshape(-1, 1)])
+    return mtx
+
+def round_output(v, digits=3):
+    return [round(x, digits) for x in v]
+
+if __name__ == '__main__':
+    # solve subsequent tasks (slow)
+    tasks = [create_linear_equation_sys(200) for _ in range(10)]
+    for i, M in enumerate(tasks, 1):
+        print(f"\ntask {i}")
+        result = round_output(solve_linear(M))
+        print("done")

concurrency/test_gauss_elim.py

@@ -0,0 +1,35 @@
+
+import pytest
+
+from gauss_elim import solve_linear
+
+
+EXAMPLES = [
+    (
+        [
+            [2, 3, 3, 3],
+            [3, -2, -9, 4],
+            [5, -1, -18, -1],
+        ],
+        [3, -2, 1]),
+    (
+        [
+            [1, 2, 3],
+            [4, 1, 5],
+        ],
+        [1, 1],
+    ),
+    (
+        [
+            [1, 2, 3],
+            [1, 2, 3],
+        ],
+        [1, 1],
+    ),
+]
+
+@pytest.mark.parametrize("matrix,expected", EXAMPLES)
+def test_solve(matrix, expected):
+    result = solve_linear(matrix)
+    result = [round(x, 3) for x in result]
+    assert result == expected

concurrency/thread_factorial.py

@@ -15,14 +15,14 @@ def __init__(self, number):
         self.number = number
 
     @staticmethod
-    def fibo(n):
-        if n == 0:
-            return 1
-        else:
-            return n * FactorialThread.fibo(n - 1)
+    def factorial(n):
+        return (
+            1 if n == 0
+            else n * FactorialThread.factorial(n - 1)
+        )
 
     def run(self):
-        result = self.fibo(self.number)
+        result = self.factorial(self.number)
         time.sleep(random.randint(5, 20))
         print(f"{self.number}! = {result}")