Merge pull request #78 from garland-culbreth/doc/overview-and-model-c…

…oncepts

Doc/overview and model concepts

.github/workflows/mkdocs.yml

@@ -26,5 +26,5 @@ jobs:
             mkdocs-material-
       - run: pip install mkdocs-material 
       - run: pip install "mkdocstrings[python]"
+      - run: pip install mkdocs-jupyter
       - run: mkdocs gh-deploy --force
-

docs/concepts/model.md

@@ -4,7 +4,7 @@
 
 ### Network generation
 
-At initialization, a social network, $\mathcal{G}$, is constructed according to standard network construction algorithms the user can select from.
+The initial social network, network, $\mathcal{G}$, is constructed according to standard network construction algorithms the user can select from.
 
 ??? abstract "Available network constructors"
 

docs/concepts/overview.md

@@ -0,0 +1,19 @@
+# Overview
+
+Network echos treats the dynamics of a network self-organizing in response to information diffusion as the result of two network properties, connections and attitudes, which are interdependent and change over time according to a reinforecement mechanism.
+
+## Connections and attitudes
+
+Connections are represented by the adjacency matrix of the network as weighted edges with weights constrained to the interval $[0, 1]$. These edge weights are used as the probability of each pair of nodes interacting over time.
+
+Attitudes are represented as positions on the unit semicircle from $[-\frac{\pi}{2}, \frac{\pi}{2}$]. This maps the sine of each attitude to the interval $[-1, 1]$.
+
+## Interaction and adaptation
+
+Each time step, nodes interact randomly with the weights of edges in the adjacency matrix acting as interaction probabilities. When two nodes interact, each node's attitude is reinforced, positively or negatively according to whether they agree or disagree, by an amount proportional to the magnitude of attitude difference between them and their existing edge weight. Simultaneously, the weight of the edge connecting the interacting nodes is also reinforced, again positively or negatively, by an amount proportional to the magnitude of attitude difference between them.
+
+## Reinforcement dynamics
+
+The model uses two parameters, $\alpha$ and $\beta$, to govern the reinforcement dynamics. The $\alpha$ parameter tunes the amount by which nodes' attitudes are reinforced by acting as an exponent on the adjacency matrix. The sign of this parameter determines whether interaction with opposing attitude nodes strengthens (positive) or weakens (negative) the nodes' attitudes.
+
+The parameter $\beta$ governs the speed at which nodes change their attitudes. It is a constant which modulates the magnitude of attitude reinforcement. When $\beta$ is large, attitudes change rapidly, and as $\beta$ becomes smaller they change more slowly. The sign of this parameter governs whether the network tends to polarize or synchronize over time. If positive, as default, the reinforcemnt tends to polarize the network, if negative the reinforcement tends to synchronize the network.

examples/getting-started.ipynb → docs/user-guide/getting-started.ipynb

@@ -4,7 +4,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Network Echos: Getting started\n",
+    "# Getting started\n",
     "---"
    ]
   },
@@ -38,6 +38,13 @@
     "import netechos.plot\n"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Initializing a model"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -60,7 +67,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "With the model object instantiated as `nemodel`, you can use its attached methods to perform operations. For example, if you wanted to simulate with a GNP-random network as your basis, you could initialize the basis network for that like so:"
+    "With the model object instantiated as `nemodel`, you can use its attached methods to perform operations. For example, if you wanted to simulate with an Erdős-Rényi random network as your basis, you could initialize the starting network for that like so:"
    ]
   },
   {
@@ -118,6 +125,13 @@
     "The `initialize_connections()` and `initialize_attitudes()` methods each include several optional arguments you can specify to customize how the initial connections and attitudes are assigned."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Running a simulation"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -149,6 +163,13 @@
     "Once the simulation is complete, the model object can be passed to `NetworkPlot` from the `netechos.plot` module to see how the simulation went. This module allows quick access to simple aspects of the simulation results."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Reviewing a simulation"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 38,

mkdocs.yml

@@ -18,6 +18,8 @@ plugins:
               ignore_init_summary: true
             merge_init_into_class: true
             show_root_toc_entry: false
+  - mkdocs-jupyter:
+      ignore_h1_titles: True
 
 theme:
   name: material
@@ -75,10 +77,11 @@ nav:
   - Home:
     - index.md
   - Concepts:
+    - concepts/overview.md
     - concepts/model.md
     - concepts/notation.md
   - API reference:
     - api-reference/core.md
     - api-reference/plot.md
   - User guide:
-    - user-guide/getting-started.md
+    - user-guide/getting-started.ipynb

netechos/core.py

@@ -1,8 +1,4 @@
-"""Core functionality for the network infodemic model.
-
-Defines the core class and methods for constructing and running an
-instance of the model.
-"""
+"""Core functionality for the network echos model."""
 
 from typing import Literal, Self
 
@@ -18,7 +14,7 @@ class NetworkModel:
     def __init__(
         self: Self,
         number_of_nodes: int,
-        interaction_type: str,
+        interaction_type: Literal["symmetric", "asymmetric"],
         alpha: float = 1,
         beta: float = 1e-3,
     ) -> Self:
@@ -28,7 +24,7 @@ def __init__(
         ----------
         number_of_nodes : int
             Number of nodes to add to the network model.
-        interaction_type : str {"symmetric", "asymmetric"}
+        interaction_type : Literal["symmetric", "asymmetric"]
             Type of interaction between nodes. If "symmetric"
             interactions will be reciprocated. If "asymmetric",
             interactions may be one-directional.
@@ -94,15 +90,15 @@ def create_network(
 
         Parameters
         ----------
-        network_type: str
+        network_type: Literal["complete", "erdos_renyi", "watts_strogatz", "newman_watts_strogatz", "barabasi_albert"]
             Type of network to create.
         p : float, optional, default: 0.1
-            Required if network_type is one of {'erdos_renyi',
-            'watts_strogatz', 'newman_watts_strogatz'}. Probability for
+            Required if network_type is one of 'erdos_renyi',
+            'watts_strogatz', 'newman_watts_strogatz'. Probability for
             edge creation.
         k : int, optional, default: 2
-            Required if network_type is one of {'watts_strogatz',
-            'newman_watts_strogatz'}. Each node is joined with its `k`
+            Required if network_type is one of 'watts_strogatz',
+            'newman_watts_strogatz'. Each node is joined with its `k`
             nearest neighbors in a ring topology.
         m : float, optional, default: 1.0
             Required if network_type is 'barabasi_albert'. Number
@@ -113,7 +109,7 @@ def create_network(
         self : Self@NetworkModel
             An instance of the NetworkModel object.
 
-        """
+        """  # noqa: E501
         if network_type == "complete":
             g_initial = nx.complete_graph(n=self.number_of_nodes)
         if network_type == "erdos_renyi":
@@ -188,7 +184,7 @@ def initialize_attitudes(
 
         Parameters
         ----------
-        distribution : str {'normal', 'uniform', 'laplace', 'vonmises'}, default: 'vonmises'
+        distribution : Literal['normal', 'uniform', 'laplace', 'vonmises'], default: 'vonmises'
             Type of probability distribution to sample attitudes from.
         a : float, default: 0.0
             First parameter for `distribution`. If `distribution` is

pyproject.toml

@@ -19,7 +19,8 @@ dependencies = [
   "pytest",
   "ruff",
   "mkdocs-material",
-  "mkdocstrings[python]>=0.18"]
+  "mkdocstrings[python]>=0.18",
+  "mkdocs-jupyter"]
 
 [tool.ruff.lint]
 select = ["ALL"]