Merge pull request #31 from agustin-recoba/feature/usability

Varias mejoras de usabilidad y separación de responsabilidades

Author: agustin-recoba

Diff for: docs/conf.py

@@ -79,9 +79,9 @@
 # The short X.Y version.
 #
 # This should match the version in pyproject.toml
-version = "1.0.5"
+version = "1.0.7"
 # The full version, including alpha/beta/rc tags.
-release = "1.0.5.dev"
+release = "1.0.7.dev"
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

Diff for: docs/notebooks/animation.ipynb

@@ -16,10 +16,6 @@
    },
    "outputs": [],
    "source": [
-    "# If pydistsim is not installed and the script is run from docs/notebooks directory\n",
-    "# import sys\n",
-    "# sys.path.append(\"../../\")\n",
-    "\n",
     "# for interactive plots\n",
     "%matplotlib notebook\n",
     "\n",
@@ -7333,7 +7329,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.0rc1"
+   "version": "3.11.0"
   }
  },
  "nbformat": 4,

Diff for: docs/notebooks/behavior_viz.ipynb

@@ -13,7 +13,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 1,
+   "execution_count": 2,
    "metadata": {
     "id": "bQX5hbAmIKRO",
     "outputId": "10242ef7-4936-4970-9711-0379033b9d30"
@@ -49,7 +49,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 2,
+   "execution_count": 3,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -84,7 +84,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 3,
+   "execution_count": 4,
    "metadata": {
     "id": "dUU7kZ1wIKRR"
    },
@@ -104,7 +104,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 4,
+   "execution_count": 5,
    "metadata": {
     "id": "-vesDvtnIKRS",
     "outputId": "2f347168-f241-4d1e-c3c3-38ac871f9e24"
@@ -113,10 +113,10 @@
     {
      "data": {
       "text/plain": [
-       "<pydistsim.network.network.BidirectionalNetwork at 0x7f5dfb676a50>"
+       "<pydistsim.network.network.BidirectionalNetwork at 0x7fc1769ae210>"
       ]
      },
-     "execution_count": 4,
+     "execution_count": 5,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -136,7 +136,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 16,
+   "execution_count": 17,
    "metadata": {
     "id": "q0JVUYBcIKRS",
     "outputId": "16c3bf7f-07f3-4a14-ea51-7717abb88237"
@@ -149,7 +149,7 @@
        "<Figure size 640x480 with 1 Axes>"
       ]
      },
-     "execution_count": 16,
+     "execution_count": 17,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -167,14 +167,14 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 6,
+   "execution_count": 7,
    "metadata": {},
    "outputs": [
     {
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "\u001b[32m2024-09-02 21:37:09.829\u001b[0m | \u001b[1mINFO    \u001b[0m | \u001b[36mpydistsim.simulation\u001b[0m:\u001b[36m__init__\u001b[0m:\u001b[36m58\u001b[0m - \u001b[1mSimulation 0x7f5dfb567710 created successfully.\u001b[0m\n"
+      "\u001b[32m2024-09-22 21:10:53.707\u001b[0m | \u001b[1mINFO    \u001b[0m | \u001b[36mpydistsim.simulation\u001b[0m:\u001b[36m__init__\u001b[0m:\u001b[36m58\u001b[0m - \u001b[1mSimulation 0x7fc1a3f38e50 created successfully.\u001b[0m\n"
      ]
     }
    ],
@@ -197,7 +197,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 7,
+   "execution_count": 8,
    "metadata": {
     "id": "wwaAh2VeIKRS"
    },
@@ -304,14 +304,14 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 8,
+   "execution_count": 9,
    "metadata": {},
    "outputs": [
     {
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "\u001b[32m2024-09-02 21:37:09.862\u001b[0m | \u001b[1mINFO    \u001b[0m | \u001b[36mpydistsim.simulation\u001b[0m:\u001b[36m__init__\u001b[0m:\u001b[36m58\u001b[0m - \u001b[1mSimulation 0x7f5dfb54e090 created successfully.\u001b[0m\n"
+      "\u001b[32m2024-09-22 21:10:53.735\u001b[0m | \u001b[1mINFO    \u001b[0m | \u001b[36mpydistsim.simulation\u001b[0m:\u001b[36m__init__\u001b[0m:\u001b[36m58\u001b[0m - \u001b[1mSimulation 0x7fc1746c2c90 created successfully.\u001b[0m\n"
      ]
     }
    ],
@@ -339,14 +339,14 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 9,
+   "execution_count": 10,
    "metadata": {},
    "outputs": [
     {
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "\u001b[32m2024-09-02 21:37:09.881\u001b[0m | \u001b[1mINFO    \u001b[0m | \u001b[36mpydistsim.simulation\u001b[0m:\u001b[36m_run_algorithm\u001b[0m:\u001b[36m147\u001b[0m - \u001b[1m[Echo] Algorithm finished\u001b[0m\n"
+      "\u001b[32m2024-09-22 21:10:53.750\u001b[0m | \u001b[1mINFO    \u001b[0m | \u001b[36mpydistsim.simulation\u001b[0m:\u001b[36m_run_algorithm\u001b[0m:\u001b[36m147\u001b[0m - \u001b[1m[Echo] Algorithm finished\u001b[0m\n"
      ]
     }
    ],
@@ -365,7 +365,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 10,
+   "execution_count": 11,
    "metadata": {
     "id": "H2rsruiUIKRT",
     "outputId": "32e92d06-26d8-4892-d661-a84dabfe411e"
@@ -398,7 +398,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 11,
+   "execution_count": 12,
    "metadata": {
     "id": "mcc7XWTRIKRU",
     "outputId": "d437f0f2-9edd-4a33-c988-3be908afde73"
@@ -410,7 +410,7 @@
        "{'index': 0, 'step': 17, 'finished': True}"
       ]
      },
-     "execution_count": 11,
+     "execution_count": 12,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -430,7 +430,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 12,
+   "execution_count": 13,
    "metadata": {
     "id": "gprEPr49IKRU",
     "outputId": "439d8dbd-65e5-41f4-f5f7-2d9bce9eb7bd"
@@ -453,7 +453,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 13,
+   "execution_count": 14,
    "metadata": {
     "id": "jMTwzLRkIKRU",
     "outputId": "a1948897-04cd-4bc1-cb97-a45723f30493"
@@ -465,7 +465,7 @@
        "{'index': 0, 'step': 1, 'finished': False}"
       ]
      },
-     "execution_count": 13,
+     "execution_count": 14,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -485,7 +485,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 14,
+   "execution_count": 15,
    "metadata": {
     "id": "3AgVUCXcIKRU",
     "outputId": "e4dc9056-b8d0-435a-bd33-9892b9fc7e10"
@@ -507,7 +507,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 15,
+   "execution_count": 16,
    "metadata": {
     "id": "wG4Jq_s7IKRU",
     "outputId": "940c51e0-35c6-41ea-b511-81b6a51acf9f"
@@ -517,7 +517,7 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "\u001b[32m2024-09-02 21:37:09.934\u001b[0m | \u001b[1mINFO    \u001b[0m | \u001b[36mpydistsim.simulation\u001b[0m:\u001b[36m_run_algorithm\u001b[0m:\u001b[36m147\u001b[0m - \u001b[1m[Echo] Algorithm finished\u001b[0m\n"
+      "\u001b[32m2024-09-22 21:10:53.828\u001b[0m | \u001b[1mINFO    \u001b[0m | \u001b[36mpydistsim.simulation\u001b[0m:\u001b[36m_run_algorithm\u001b[0m:\u001b[36m147\u001b[0m - \u001b[1m[Echo] Algorithm finished\u001b[0m\n"
      ]
     }
    ],

Diff for: docs/notebooks/benchmarking.ipynb

@@ -16,10 +16,6 @@
    },
    "outputs": [],
    "source": [
-    "# If pydistsim is not installed and the script is run from docs/notebooks directory\n",
-    "# import sys\n",
-    "# sys.path.append(\"../../\")\n",
-    "\n",
     "# for interactive plots\n",
     "%matplotlib notebook\n",
     "\n",
@@ -278,7 +274,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.0rc1"
+   "version": "3.11.0"
   }
  },
  "nbformat": 4,

Diff for: docs/notebooks/custom_observer.ipynb

@@ -19,10 +19,6 @@
    },
    "outputs": [],
    "source": [
-    "# If pydistsim is not installed and the script is run from docs/notebooks directory\n",
-    "# import sys\n",
-    "# sys.path.append(\"../../\")\n",
-    "\n",
     "# for interactive plots\n",
     "%matplotlib notebook\n",
     "\n",
@@ -1600,7 +1596,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.0rc1"
+   "version": "3.11.0"
   }
  },
  "nbformat": 4,

Diff for: docs/notebooks/hello_distributed_world.ipynb

@@ -51,6 +51,7 @@ which are defined like this:
   * gradually increase number of nodes up to `n_max`
   * if comm_range is None gradually increase nodes commRange
   * if still not connected raise an exception
+
 3. if `degree` condition is defined and current network degree is
   * lower - repeat measures from the last step to increase current
     network degree

Diff for: docs/notebooks/network_generators.ipynb

@@ -51,12 +51,71 @@ sending messages and setting alarms.
     Actions without an implementation will only log a warning message, so for no-ops, it is not necessary to implement
     anything.
 
-*************************
+
+Node's own id and neighbor labels
+=================================
+
+The framework is designed to prevent the programmer from accessing information that should not be available to the
+nodes. For this reason, we provide two classes that act as proxies for the node and its neighbors, respectively.
+
+
+`NodeAccess` class
+------------------
+
+A :class:`NodeAccess` instance represents a node's own view, encapsulating the knowledge gathered so far (inside the
+``memory`` attribute) and inherent of the node (such as who are it's neighbors).
+
+By default, this class allows read-only access to the node's ``clock`` attribute and read-and-write access to the
+``memory`` and ``status`` attributes.
+
+In addition to this attributes, each NodeAccess instance has an integer ``id`` attribute, by default it's random and
+won't be unique in the network.
+
+
+These are the two main ways a programmer comes across a :class:`NodeAccess` instance:
+
+.. code-block:: python
+
+    @Status.IDLE
+    def receiving(self, node: NodeAccess, message: Message):
+                          ↑
+
+    def initializer(self):
+        for node in self.nwm.nodes():
+              ↑
+
+            node.memory['SPAM_COUNT'] = 0
+
+
+        for node in self.network.nodes():
+              ↑ NOT A NodeAccess INSTANCE
+
+`NeighborLabel` class
+---------------------
+
+A :class:`NeighborLabel` instance represents the knowledge of the neighbor respect to current processing node.
+
+Similar to the :class:`NodeAccess` class, the :class:`NeighborLabel` instances have an integer ``id`` attribute, by default it's random
+and won't match any other ``id`` in the network. It's only used to identify that neighbor among the other neighbors.
+
+These are the two main ways a programmer comes across a :class:`NeighborLabel` instance:
+
+.. code-block:: python
+
+    @Status.IDLE
+    def receiving(self, node: NodeAccess, message: Message):
+        source = message.source  # The node that sent the message
+          ↑
+
+        for neighbor in node.neighbors():
+               ↑
+
+
 "The Santoro's interface"
-*************************
+=========================
 
 Send a message
-==============
+--------------
 The :meth:`NodeAlgorithm.send_msg` method receives a source node and a message. The message will be sent to the destinations
 specified in the message itself. The destinations must be a list of nodes or a single node. The message will be sent to
 all the destinations.
@@ -66,20 +125,20 @@ The :meth:`NodeAlgorithm.send` method receives a source node, a message content
 a header. Is equivalent to the :meth:`NodeAlgorithm.send_msg` method, but the message is created automatically.
 
 Set an alarm
-============
+------------
 The :meth:`NodeAlgorithm.set_alarm` method receives a node and a time. An empty message will be sent to the node after
 the time has passed. The time is in algorithm steps, which behavior varies according to the algorithm and the simulation\
 parameters.
 
 
 Check the extended interface methods for advanced use of the alarm mechanism.
 
-*******************************************
+
 Helper functions and the extended interface
-*******************************************
+===========================================
 
 Alarm management
-================
+----------------
 
 The :meth:`NodeAlgorithm.set_alarm` method receives an extra, optional, parameter, the message. This message will be
 sent to the node when the alarm goes off. The message must be an instance of :class:`Message`. This, however, is not

Diff for: docs/notebooks/tree_construction_viz.ipynb

@@ -171,7 +171,10 @@ def check_restrictions(self):
             if issubclass(restriction, CheckableRestriction):
                 logger.debug("Checking restriction {}.", restriction.__name__)
                 if not restriction.check(self.network):
-                    raise AlgorithmException(f"Restriction {restriction.__name__} not satisfied for this network.")
+                    raise AlgorithmException(
+                        f"Restriction {restriction.__name__} not satisfied for this network.\n"
+                        + restriction.get_explanation(self.network)
+                    )
 
     def apply_restrictions(self):
         """