optimiz-rs/examples/notebooks/15_agent_based.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "993c4ff4",
   "metadata": {},
   "source": [
    "# 15 — Agent-based consensus dynamics\n",
    "\n",
    "Doc page: [agent_based.rst](../../docs/source/algorithms/agent_based.rst).\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "139a21f8",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-05-12T14:05:56.273834Z",
     "iopub.status.busy": "2026-05-12T14:05:56.273478Z",
     "iopub.status.idle": "2026-05-12T14:05:56.865083Z",
     "shell.execute_reply": "2026-05-12T14:05:56.863813Z"
    }
   },
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "import matplotlib.pyplot as plt\n",
    "from optimizr import _core as opt\n",
    "plt.rcParams['figure.figsize'] = (8.5, 4.5)\n",
    "plt.rcParams['figure.dpi'] = 110\n",
    "plt.rcParams['axes.grid'] = True\n",
    "plt.rcParams['grid.alpha'] = 0.3\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a77569c5",
   "metadata": {},
   "source": [
    "## Cellule 1 — Convergence vers le consensus\n",
    "\n",
    "**Théorème (consensus DeGroot, version $\\alpha$-pondérée).** Pour la\n",
    "dynamique discrète\n",
    "$$X^i_{k+1} = (1 - \\alpha)\\,X^i_k + \\alpha\\,\\bar X_k + \\sigma\\,\\varepsilon_k^i,$$\n",
    "la moyenne $\\bar X_k$ est conservée en espérance et la variance\n",
    "décroît à taux $(1 - \\alpha)^2$ par pas (pour $\\sigma = 0$).\n",
    "\n",
    "**Équation pivot.**\n",
    "$$\\mathbb{E}[\\text{Var}(X_k)] = (1 - \\alpha)^{2k}\\,\\text{Var}(X_0).$$\n",
    "\n",
    "**Démonstration.** Récurrence linéaire : la composante hors moyenne\n",
    "est multipliée par $(1-\\alpha)$ à chaque pas.  $\\square$\n",
    "\n",
    "**Ce que la cellule vérifie.** `consensus_dynamics(initial, alpha,\n",
    "noise_sigma, n_steps, seed)` reproduit la décroissance géométrique.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "aff03dd6",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-05-12T14:05:56.868502Z",
     "iopub.status.busy": "2026-05-12T14:05:56.868174Z",
     "iopub.status.idle": "2026-05-12T14:05:57.662174Z",
     "shell.execute_reply": "2026-05-12T14:05:57.660763Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Moyenne initiale : 0.079\n",
      "Moyenne finale   : 0.079\n",
      "Var init / final : 1.230 / 3.174e-19\n"
     ]
    },
    {
     "data": {
      "image/png": "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
      "text/plain": [
       "<Figure size 1320x440 with 2 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "N, alpha, sigma, n_steps = 50, 0.3, 0.0, 60\n",
    "rng = np.random.default_rng(1)\n",
    "x0 = rng.uniform(-2, 2, N).tolist()\n",
    "\n",
    "res = opt.consensus_dynamics(x0, alpha=alpha, noise_sigma=sigma,\n",
    "                              n_steps=n_steps, seed=0)\n",
    "states = np.array(res['states_flat']).reshape(n_steps + 1, N)\n",
    "mean_traj = np.array(res['mean_trajectory'])\n",
    "\n",
    "variances = states.var(axis=1)\n",
    "print(f\"Moyenne initiale : {np.mean(x0):.3f}\")\n",
    "print(f\"Moyenne finale   : {mean_traj[-1]:.3f}\")\n",
    "print(f\"Var init / final : {variances[0]:.3f} / {variances[-1]:.3e}\")\n",
    "\n",
    "fig, axes = plt.subplots(1, 2, figsize=(12, 4))\n",
    "for i in range(N):\n",
    "    axes[0].plot(states[:, i], lw=0.8, alpha=0.5)\n",
    "axes[0].plot(mean_traj, 'k-', lw=2, label='moyenne')\n",
    "axes[0].set_xlabel('itération k'); axes[0].set_ylabel(r'$X_k^i$')\n",
    "axes[0].set_title(f\"Consensus (α = {alpha}, σ = {sigma})\")\n",
    "axes[0].legend()\n",
    "axes[1].semilogy(variances, lw=2, label='variance empirique')\n",
    "axes[1].semilogy(variances[0] * (1 - alpha) ** (2 * np.arange(n_steps + 1)),\n",
    "                 ':', label=r'$(1-\\alpha)^{2k}$ Var$(X_0)$')\n",
    "axes[1].set_xlabel('itération k'); axes[1].set_ylabel(r'Var($X_k$)')\n",
    "axes[1].set_title(\"Décroissance géométrique\")\n",
    "axes[1].legend()\n",
    "fig.tight_layout(); plt.show()\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fb8eccea",
   "metadata": {},
   "source": [
    "**Résultat attendu.** Variance qui décroît exponentiellement.\n",
    "\n",
    "**Lecture du graphique.** Faisceau qui se concentre vers la moyenne\n",
    "(ligne noire) ; pente log-linéaire conforme à la prédiction.\n",
    "\n",
    "**Conclusion.** Le primitive est validé sur la convergence\n",
    "géométrique.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5a91c57b",
   "metadata": {},
   "source": [
    "## Cellule 2 — Effet du bruit\n",
    "\n",
    "**Théorème.** Lorsque $\\sigma > 0$, la variance ne tombe pas à zéro\n",
    "mais se stabilise à un niveau d'équilibre proportionnel à $\\sigma^2$.\n",
    "\n",
    "**Équation pivot.** Variance asymptotique croissante en $\\sigma^2$.\n",
    "\n",
    "**Ce que la cellule vérifie.** Sweep sur $\\sigma \\in \\{0.05, 0.1,\n",
    "0.2\\}$ pour $\\alpha = 0.3$.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "dc879366",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-05-12T14:05:57.665702Z",
     "iopub.status.busy": "2026-05-12T14:05:57.665355Z",
     "iopub.status.idle": "2026-05-12T14:05:58.012408Z",
     "shell.execute_reply": "2026-05-12T14:05:58.011304Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "σ = 0.05 : Var(K) numérique = 0.0048\n",
      "σ = 0.10 : Var(K) numérique = 0.0191\n",
      "σ = 0.20 : Var(K) numérique = 0.0762\n"
     ]
    },
    {
     "data": {
      "image/png": "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
      "text/plain": [
       "<Figure size 935x495 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "N, alpha, n_steps = 80, 0.3, 200\n",
    "rng = np.random.default_rng(11)\n",
    "x0 = rng.uniform(-2, 2, N).tolist()\n",
    "\n",
    "fig, ax = plt.subplots()\n",
    "for sigma in [0.05, 0.1, 0.2]:\n",
    "    r = opt.consensus_dynamics(x0, alpha, sigma, n_steps, seed=42)\n",
    "    states = np.array(r['states_flat']).reshape(n_steps + 1, N)\n",
    "    var = states.var(axis=1)\n",
    "    ax.plot(var, label=fr'$\\sigma = {sigma}$')\n",
    "    print(f\"σ = {sigma:.2f} : Var(K) numérique = {var[-1]:.4f}\")\n",
    "ax.set_xlabel('itération k'); ax.set_ylabel(r'Var($X_k$)')\n",
    "ax.set_title(\"Variance asymptotique vs bruit\")\n",
    "ax.legend()\n",
    "fig.tight_layout(); plt.show()\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "54036a62",
   "metadata": {},
   "source": [
    "**Résultat attendu.** Variance qui plateauise à un niveau\n",
    "croissant avec $\\sigma^2$.\n",
    "\n",
    "**Lecture du graphique.** Trois courbes décroissantes qui se\n",
    "stabilisent à des paliers proportionnels à $\\sigma^2$.\n",
    "\n",
    "**Conclusion.** Le compromis bruit / convergence est gouverné par\n",
    "$\\alpha$ et $\\sigma$.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "15bd197c",
   "metadata": {},
   "source": [
    "## Cellule 3 — Exemple concret : émergence d'une décision collective\n",
    "\n",
    "**Modèle.** $N = 100$ agents au sein d'un comité décident d'un\n",
    "nombre (par exemple un score entre $-1$ et $+1$).  Chaque agent\n",
    "ajuste sa position vers la moyenne avec un peu de bruit.\n",
    "\n",
    "**Équation pivot.**\n",
    "$$X^i_{k+1} = (1 - \\alpha) X^i_k + \\alpha \\bar X_k + \\sigma \\varepsilon^i_k.$$\n",
    "\n",
    "**Ce que la cellule vérifie.** Visualisation : densité des\n",
    "opinions au cours du temps converge vers une distribution unimodale.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "11ad58dc",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-05-12T14:05:58.015710Z",
     "iopub.status.busy": "2026-05-12T14:05:58.015433Z",
     "iopub.status.idle": "2026-05-12T14:05:58.679005Z",
     "shell.execute_reply": "2026-05-12T14:05:58.677754Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Moyenne initiale : -0.061\n",
      "Moyenne finale   : -0.075\n"
     ]
    },
    {
     "data": {
      "image/png": "iVBORw0KGgoAAAANSUhEUgAABRsAAAHCCAYAAABvxR5EAAAAOXRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjguNCwgaHR0cHM6Ly9tYXRwbG90bGliLm9yZy8fJSN1AAAACXBIWXMAABDrAAAQ6wFQlOh8AAEAAElEQVR4nOydd5xVxd3/PzPn3LZ9lyKLSFMpRlQUEayACg/GgooIYiGKyKPYMJqIUSmCmtgSS8yjRJRIJBZ8jMGKEs1j+9liRSyIRFFkWbbdes7M74/dvexlvgP3shX5vl+vfSmzc+ZMPXvu987nM0JrrcEwDMMwDMMwDMMwDMMwDNNMZHtXgGEYhmEYhmEYhmEYhmGYnwYcbGQYhmEYhmEYhmEYhmEYpkXgYCPDMAzDMAzDMAzDMAzDMC0CBxsZhmEYhmEYhmEYhmEYhmkRONjIMAzDMAzDMAzDMAzDMEyLwMFGhmEYhmEYhmEYhmEYhmFaBA42MgzDMAzDMAzDMAzDMAzTInCwkWEYhmEYhmEYhmEYhmGYFoGDjQzDMAzDMAzDMAzDMAzDtAgcbGRy4u6778Z9993X3tVgGIZhGIZhGIZhGIZhOiBue1eA2XmYPXs2/vznP+Pll19u76owDMMwDMMwDMMwDMMwHRDe2chkxcaNGyGEwCuvvII999yzvavDMAzDMAzDMAzTqrzyyiuYPXs21qxZ095VaTYvvPAC5syZg++++669q8IwzC4ABxuZrOjcuTOuv/569O7du83vPWXKFAghWq38ESNGtEu7smXlypUQQmDRokXtXZUWpyX6XgiBKVOmtEh9WpvWnMvUPGnu3Mn1+tmzZ0MIga+//nqH7pcr1Pxp7ecFwzAMw7QmX3/9NYQQmD17dpvel/r72V5/U9urDygOOeQQvPHGG/j5z3+OzZs3t2jZ1HuT7V1qzZo1GDduHLp06ZLx7quUwuzZs9G3b1+4rmsdr7fffhsnnXQSAoEAunfv3qLt6Ijw+yDDtD8cbGSsNAYatvWzatWq9q5mVsyePRtPPvlke1eDYRiGYRiG2QXY+j3acRwUFxejf//+mDBhApYsWYJkMtni95w9e3aLB8Vag/fffx+zZ89usy8od5RQKIQnn3wSu+++O8aPHw/P89qlHlOmTME///lP/OpXv8LixYtxwQUXAAAefPBBzJkzByNHjsTChQuxePFi49pvv/0WJ510Eq688krMmjWrratu5euvv8bs2bPx/vvvt3dVdpj2msc/hb5jfvqwZyOzXcaPH4+TTjqJ/N3O8s3YnDlzcM4552DcuHHG755//nlordu+UkyL9H0sFoPjOC1Uo9blvvvuw7333ttm9zvyyCMRi8UQCATa5XqGYRiG2dVp+h5dW1uLNWvW4JlnnsHkyZNxww034PHHH8fAgQPT+Xv16oVYLAbXzf1j2sqVKzFnzhxMmTIFJSUlOV3b1u8o77//PubMmUOqFJrTB61BOBzGU089hTvuuAMffPABDjzwwFa7129+8xv8+te/RigUSqclEgm8+uqrmDFjBn75y19m5H/hhRdQXFyM+++/37qT76233sLcuXNx3nnntVq9d4Svv/4ac+bMQe/evXHAAQe0aNltNZ+3NY9bk9bsO4ZpKTrGE5zp0Oy///4488wz27sarUYwGGzvKuyytETfh8PhFqhJ2xAIBNo0cCelbFb/NPd6hmEYhtnVod6jb775ZixatAhTp07FmDFj8NFHH6GoqAhAvT1MW/3t1Vqjrq4OBQUFbf6Osi3asg+yJRKJ4Oqrr271+7iuawRZf/jhB2itUVZWZuT//vvvUVJSsk3J8Mknn5xzPXzfRyKRQF5eXs7XdgQ60nxmmF0VllEzLcLhhx+O4uJixGIx43fr1q2D4zg466yzMtIffvhhHHLIIcjPz0d+fj6GDRuGRx55JKv7bevbo6Y+Jo0SFqBeZtBUzrK9st58800cf/zxKCsrQzgcxoABAzBv3jxD8tLorbJ69Wpcd9116NWrF0KhEAYOHIiHH344q/Y08oc//AH9+/dHKBRCnz59MG/ePKtcI5lM4re//S32228/RCIRFBUV4ZhjjsErr7xi5H344YcxfPhwlJWVIRKJoGfPnjjllFPwySefZFWvXPvik08+wcyZM7H77rsjHA5j//33J8eW6vvGtO+//x5nnXUWOnXqhEgkgiOPPBJvv/22UYbNszHb+ZXr/ZrTl9vyQ6qursbFF1+M8vJyhEIhHHjggXjuuefIcrKdJ1t7Ln7xxRcQQuD8888ny73hhhsghMCKFSvI6xupqanBpZdeivLyckQiERx44IF49NFHyTKzXatNefzxx3HUUUehqKgIkUgEgwcPxv3330+WkS0//PADLr74YvTu3RvBYBC77bYbzjzzTEP2kkgkMG/ePOyzzz7Iz89HUVER+vfvj3PPPZd8vjEMwzDMjjBlyhRcccUVWLduHe6+++50us2vcHvvHyNGjMCcOXMAAH369Em/7zaWs2jRIggh8OKLL+LGG29Ev379EAqFcMstt6TrYwtYVVRU4Nxzz0WXLl0QiUQwfPjw9LvC9urd9N4rV65M3+sXv/gFAGDkyJHpuja+E9jKUkrhD3/4A/bff//0u++oUaPwwgsvGPfs3bs3RowYgdWrV+Okk05CcXExCgoKcNxxx+GLL74g27k1NTU1uPbaazFs2DB06dIFwWAQvXv3xowZM7Bp06asymgsJ9v3pq09G0eMGIFevXoBqFdqNfZVY5++/PLLWLt2rdGHAPDll19iypQp6N69O4LBIHr06IELL7wQGzduJO/5ySef4Kqrrkp/lvnb3/4GoD4ofd9992Ho0KHp9+pDDz2UtKhqrMNbb72FUaNGoaCgACUlJZg4cSI2bNiQcc+RI0cCAH7xi1+k6z9ixIh0nvZ+53722WcxatQodO3aFeFwGD169MDYsWPx6quvpsvb1jxWSmHBggUYMWIEysvLEQwGsfvuu+Occ87BN99802H7jmFaCt7ZyGyXaDRq/FECAMdxUFpaCqD+YXv++efjiSeewOTJkzPyPfjgg1BKZfzxu+666zBv3jwMGjQI119/PbTW+Mtf/oJJkybhq6++ajE/kYEDB2Lx4sU466yzcMQRR2DatGlZXffss8/ixBNPRFFRES688EJ069YNy5cvx3XXXYfXXnsN//jHPyBlZqz+nHPOgRACl1xyCaSUuOeee3DmmWdizz33xLBhw7Z7z1//+te4+eabcdBBB2HBggVIJBJYuHAh/vd//9fI63kejjvuOPzzn//EpEmTMH36dESjUfzlL3/BqFGj8OSTT+L4448HUP/H5swzz8Rhhx2G66+/HgUFBfj222/x0ksv4bPPPsM+++zT4n1x9tlnQ2uNmTNnIpFIYNGiRZg0aRJqa2sxderU7fZFXV0djjjiCBx00EGYN28efvjhB9x+++0YO3YsvvrqKxQWFm7z+lznV7b3a25fbosxY8agpKQEV199NaLRKO644w6ceOKJ+Pzzz9GzZ890vlzmydbstddeOOyww/C3v/0Nf/jDHxCJRDJ+/+CDD6Jnz54YNWqUtQzP8zB27Fj83//9H04++WQcffTR+Oabb3DuueeiX79+O9z+Rq6//nrMnTsXI0eOxPXXX49IJILnnnsO559/Pr744gvcdNNNOZe5bt06HHrooaitrcV5552Hfv364dtvv8Uf//hHPP/883j77bfTfTxjxgzcf//9mDx5Mi655BIA9absTz/9NOrq6ow+YxiGYZgd5YILLsBvf/tbPP3009vcNZfN+8c111yDsrIyLFu2DLfffjs6d+4MANhvv/0yyrryyisRjUZxzjnnoEuXLthjjz22W88xY8agqKgI1157LTZt2oQ//elP+K//+i/8/e9/x3/913/tULtDoRD+53/+B7NmzUrLyPfcc89tXjdlyhQsXrwYhx12GBYsWIDa2lrcf//9GDNmDB566CFjB+m3336LI488EieeeCJuvvlmfP7557jzzjtx0kkn4cMPPzTeX7fm22+/xf/8z//glFNOwemnn45wOIy33noLf/rTn/Cvf/0
      "text/plain": [
       "<Figure size 1320x462 with 3 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "N = 100\n",
    "n_steps = 80\n",
    "alpha, sigma = 0.2, 0.04\n",
    "rng = np.random.default_rng(7)\n",
    "# distribution initiale : trois clusters\n",
    "x0 = np.concatenate([\n",
    "    rng.normal(-0.7, 0.15, 35),\n",
    "    rng.normal(0.0, 0.10, 35),\n",
    "    rng.normal(+0.7, 0.15, 30),\n",
    "]).tolist()\n",
    "\n",
    "r = opt.consensus_dynamics(x0, alpha, sigma, n_steps, seed=0)\n",
    "states = np.array(r['states_flat']).reshape(n_steps + 1, N)\n",
    "mean_traj = np.array(r['mean_trajectory'])\n",
    "\n",
    "print(f\"Moyenne initiale : {np.mean(x0):.3f}\")\n",
    "print(f\"Moyenne finale   : {mean_traj[-1]:.3f}\")\n",
    "\n",
    "fig, axes = plt.subplots(1, 2, figsize=(12, 4.2))\n",
    "im = axes[0].imshow(states.T, aspect='auto', cmap='coolwarm',\n",
    "                    interpolation='nearest', origin='lower',\n",
    "                    extent=[0, n_steps, 0, N])\n",
    "axes[0].set_xlabel('itération k')\n",
    "axes[0].set_ylabel('agent i')\n",
    "axes[0].set_title(\"Évolution des opinions individuelles\")\n",
    "plt.colorbar(im, ax=axes[0], label='X_k^i')\n",
    "for k, color in zip([0, 20, n_steps], ['C0', 'C2', 'C3']):\n",
    "    axes[1].hist(states[k], bins=20, alpha=0.55, color=color,\n",
    "                 density=True, label=f'k={k}', edgecolor='white')\n",
    "axes[1].set_xlabel('opinion'); axes[1].set_ylabel('densité')\n",
    "axes[1].set_title(\"Distribution à différents instants\")\n",
    "axes[1].legend()\n",
    "fig.tight_layout(); plt.show()\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0540fb0c",
   "metadata": {},
   "source": [
    "**Résultat attendu.** Les trois clusters initiaux fusionnent en\n",
    "distribution unimodale concentrée près de $\\bar X_0$.\n",
    "\n",
    "**Lecture du graphique.** Gauche : la heatmap montre l'horizon de\n",
    "fusion.  Droite : trois distributions superposées (initiale tri-modale,\n",
    "intermédiaire, finale unimodale).\n",
    "\n",
    "**Conclusion.** Le primitive `consensus_dynamics` modélise toute\n",
    "dynamique de moyennage par interaction (vote pondéré, opinion\n",
    "publique, scoring collectif).\n"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "rhftlab",
   "language": "python",
   "name": "rhftlab"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.11.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}