{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "6df10fec5b84",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-06-19T07:41:04.449480Z",
     "iopub.status.busy": "2026-06-19T07:41:04.449139Z",
     "iopub.status.idle": "2026-06-19T07:41:09.570222Z",
     "shell.execute_reply": "2026-06-19T07:41:09.569290Z"
    },
    "tags": [
     "remove-cell"
    ]
   },
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "An NVIDIA GPU may be present on this machine, but a CUDA-enabled jaxlib is not installed. Falling back to cpu.\n"
     ]
    }
   ],
   "source": [
    "%matplotlib inline\n",
    "import warnings\n",
    "import time\n",
    "import numpy as np\n",
    "import matplotlib.pyplot as plt\n",
    "import jax\n",
    "import jax.numpy as jnp\n",
    "import brainstate\n",
    "import braintools\n",
    "import brainunit as u\n",
    "import brainmass\n",
    "from brainmass import objectives\n",
    "from brainstate.nn import Param\n",
    "brainstate.environ.set(dt=0.1 * u.ms)\n",
    "brainstate.random.seed(0)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "91c021d6ba76",
   "metadata": {},
   "source": [
    "# Custom Coupling\n",
    "\n",
    "**Goal:** choose and configure the coupling that connects regions in a `brainmass`\n",
    "network — linear (`diffusive` / `additive` / `laplacian`) or nonlinear\n",
    "(`sigmoidal` / `tanh` / `sigmoidal_jansen_rit`) — and understand when to use each.\n",
    "\n",
    "The fastest path is the `coupling=` argument of `brainmass.Network`, which wires\n",
    "the right coupling object onto a delayed connectome read for you. We use that\n",
    "throughout, then peek at the underlying coupling classes for the cases where you\n",
    "need direct control. See {doc}`/tutorials/04_building_a_network` for general\n",
    "network setup.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a580aeaa5528",
   "metadata": {},
   "source": [
    "## The coupling family\n",
    "\n",
    "A coupling turns the connectome `W` and the (optionally delayed) source states\n",
    "into a per-region input current `C_i`. `brainmass` ships two families:\n",
    "\n",
    "**Linear** — the input is a weighted sum of source states:\n",
    "\n",
    "| `coupling=` | Class | Formula |\n",
    "| --- | --- | --- |\n",
    "| `'diffusive'` | `DiffusiveCoupling` | $C_i = k \\sum_j W_{ij}(x_j - x_i)$ |\n",
    "| `'additive'` | `AdditiveCoupling` | $C_i = k \\sum_j W_{ij} x_j + b$ |\n",
    "| `'laplacian'` | `AdditiveCoupling` + Laplacian | $C_i = -k\\,(L x)_i$ |\n",
    "\n",
    "**Nonlinear** — a saturating function is applied either *after* the sum\n",
    "(post-nonlinearity) or to *each source* before it (pre-nonlinearity):\n",
    "\n",
    "| `coupling=` | Class | Formula | When |\n",
    "| --- | --- | --- | --- |\n",
    "| `'tanh'` | `HyperbolicTangentCoupling` | $C_i = k\\,\\tanh(\\mathrm{scale}\\sum_j W_{ij}x_j)$ | symmetric saturation to $\\pm k$ |\n",
    "| `'sigmoidal'` | `SigmoidalCoupling` | $C_i = k\\,\\sigma(\\mathrm{slope}(a\\sum_j W_{ij}x_j + b - \\mathrm{mid}))$ | asymmetric firing-rate saturation |\n",
    "| `'sigmoidal_jansen_rit'` | `SigmoidalJansenRitCoupling` | $C_i = k\\sum_j W_{ij}\\,\\sigma_{JR}(x_j)$ | Jansen-Rit pre-synaptic transfer |\n",
    "\n",
    "The global strength `k` is TVB's `G` (`G ≡ k`).\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8ea1efa1bf58",
   "metadata": {},
   "source": [
    "## Build a network and swap couplings\n",
    "\n",
    "Set up a connectome and a node once, then change only `coupling=`. We use the\n",
    "bundled 8-region connectome and a Hopf node; the `Simulator` drives the network.\n",
    "\n",
    ":::{note}\n",
    "A delay-coupled `Network` sizes its delay buffers from the global `dt` **at\n",
    "construction time**, so set `brainstate.environ.set(dt=...)` once before building\n",
    "any network. The `Simulator` also supplies `dt` at run time.\n",
    ":::\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "d9c6b4ecafbc",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-06-19T07:41:09.572809Z",
     "iopub.status.busy": "2026-06-19T07:41:09.572308Z",
     "iopub.status.idle": "2026-06-19T07:41:11.006202Z",
     "shell.execute_reply": "2026-06-19T07:41:11.005327Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "diffusive    -> trajectory (2500, 8), mean|x| = 0.117\n",
      "additive     -> trajectory (2500, 8), mean|x| = 1.359\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "tanh         -> trajectory (2500, 8), mean|x| = 0.727\n",
      "sigmoidal    -> trajectory (2500, 8), mean|x| = 0.692\n"
     ]
    }
   ],
   "source": [
    "conn = brainmass.datasets.load_dataset('example_connectome')\n",
    "W, D = conn.weights, conn.distances\n",
    "N = W.shape[0]\n",
    "brainstate.environ.set(dt=0.1 * u.ms)\n",
    "\n",
    "def run_with(coupling, **kw):\n",
    "    kw.setdefault('k', 0.5)\n",
    "    node = brainmass.HopfStep(in_size=N, a=0.2, w=0.3,\n",
    "                              init_x=braintools.init.Constant(0.3))\n",
    "    net = brainmass.Network(node, conn=W, distance=D, speed=10 * u.mm / u.ms,\n",
    "                            coupling=coupling, coupled_var='x', **kw)\n",
    "    res = brainmass.Simulator(net, dt=0.1 * u.ms).run(\n",
    "        300 * u.ms, monitors=lambda m: m.node.x.value, transient=50 * u.ms)\n",
    "    return u.get_magnitude(res['output'])\n",
    "\n",
    "for c in ['diffusive', 'additive', 'tanh', 'sigmoidal']:\n",
    "    sig = run_with(c)\n",
    "    print(f\"{c:12s} -> trajectory {sig.shape}, mean|x| = {np.abs(sig).mean():.3f}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9b5d434cbb06",
   "metadata": {},
   "source": [
    "## Linear couplings\n",
    "\n",
    "### Diffusive\n",
    "\n",
    "Diffusive coupling drives each node toward its neighbours' states — the\n",
    "$x_j - x_i$ difference vanishes when the network synchronizes, so it is the\n",
    "natural model for **synchronization** and the default for brain networks.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "ac9714cc449c",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-06-19T07:41:11.009627Z",
     "iopub.status.busy": "2026-06-19T07:41:11.009347Z",
     "iopub.status.idle": "2026-06-19T07:41:11.340456Z",
     "shell.execute_reply": "2026-06-19T07:41:11.339608Z"
    }
   },
   "outputs": [
    {
     "data": {
      "image/png": "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ERERuSU2skRERETkltjIEhEREZFbYiNLRERERG6JjSwRERERuSU2skRERETkltjIEhG5mfz8fCiKgtraWmenQkTkVLyzFxGRi7vjjjtw880348033wQAXLx4ETU1NQgODoaiKM5NjojIiTycnQAREV0bjUYDo9Ho7DSIiJyOpxYQEbmw9PR0bN26FW+99RYURYGiKMjJybE7tSAnJwd6vR6fffYZYmJi4OPjg2nTpqGhoQF/+tOfEBERgYCAADz++OOwWCy2dTc1NSErKwthYWHo0aMH4uPjkZ+f75wNJSL6CXhElojIhb311lv4/vvvMXjwYLz44osAgH379rWLa2howNtvv43c3FyYzWbce++9mDJlCvR6PdavX4+jR49i6tSpGDNmDFJTUwEAmZmZ2L9/P3JzcxEaGoo1a9YgOTkZe/fuRf/+/R26nUREPwUbWSIiF+bv7w+NRgMfHx/b6QQHDx5sF9fc3IwVK1agX79+AIBp06bhww8/RGVlJXx9fREbG4vx48djy5YtSE1NRVlZGbKzs1FWVobQ0FAAQFZWFvLy8pCdnY2XX37ZcRtJRPQTsZElIroB+Pj42JpYAAgODkZERAR8fX3tHquqqgIA7N27FxaLBQMGDLBbT1NTE3r16uWYpImIrhMbWSKiG4Cnp6fdz4qidPiY1WoFANTX10OtVqOoqAhqtdou7ofNLxGRK2MjS0Tk4jQajd1FWp3hlltugcViQVVVFcaOHdup6yYichTOWkBE5OIiIiJQWFiIY8eO4ezZs7ajqtdjwIABSEtLw8yZM7F69WqUlpZi+/btWLZsGT7//PNOyJqIqOuxkSUicnFZWVlQq9WIjY1FYGAgysrKOmW92dnZmDlzJubPn4+YmBjcc8892LFjB8LDwztl/UREXY139iIiIiIit8QjskRERETkltjIEhEREZFbYiNLRERERG6JjSwRERERuSU2skRERETkltjIEhEREZFbYiNLRERERG6JjSwRERERuSU2skRERETkltjIEhEREZFbYiNLRERERG6JjSwRERERuaV/A4llorGY6WXLAAAAAElFTkSuQmCC",
      "text/plain": [
       "<Figure size 700x300 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "sig_diff = run_with('diffusive')\n",
    "fig, ax = plt.subplots(figsize=(7, 3))\n",
    "brainmass.viz.plot_timeseries(sig_diff[:, :4], ax=ax)\n",
    "ax.set_title(\"Diffusive coupling (k=0.5)\")\n",
    "fig.tight_layout(); plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c7cb9e9426b9",
   "metadata": {},
   "source": [
    "### Additive\n",
    "\n",
    "Additive coupling sums neighbour inputs directly ($\\sum_j W_{ij} x_j$, no\n",
    "self-term) — simpler, and the right choice when the drive is a genuine *input*\n",
    "rather than a pull toward consensus. It also accepts a constant bias `b`.\n",
    "\n",
    "### Laplacian\n",
    "\n",
    "`coupling='laplacian'` expresses diffusive coupling through the graph Laplacian\n",
    "$L = D - W$. It is mathematically equivalent to diffusive coupling on a symmetric\n",
    "`W` but lets you reuse a precomputed Laplacian; `brainmass.laplacian_connectivity`\n",
    "builds normalized variants.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "0ba00b59c1f3",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-06-19T07:41:11.342834Z",
     "iopub.status.busy": "2026-06-19T07:41:11.342546Z",
     "iopub.status.idle": "2026-06-19T07:41:11.811290Z",
     "shell.execute_reply": "2026-06-19T07:41:11.810654Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Laplacian row sums (~0): 4.440892098500626e-16\n",
      "normalized Laplacians: (8, 8) (8, 8)\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "/home/chaoming/miniconda3/lib/python3.13/site-packages/jax/_src/numpy/lax_numpy.py:5737: UserWarning: Explicitly requested dtype float64 requested in eye is not available, and will be truncated to dtype float32. To enable more dtypes, set the jax_enable_x64 configuration option or the JAX_ENABLE_X64 shell environment variable. See https://github.com/jax-ml/jax#current-gotchas for more.\n",
      "  output = _eye(N, M=M, k=k, dtype=dtype)\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "laplacian network ran: (2500, 8)\n"
     ]
    }
   ],
   "source": [
    "L = brainmass.laplacian_connectivity(W, normalize=None)\n",
    "print(\"Laplacian row sums (~0):\", float(jnp.abs(L.sum(axis=1)).max()))\n",
    "L_sym = brainmass.laplacian_connectivity(W, normalize=\"sym\")   # symmetric-normalized\n",
    "L_rw = brainmass.laplacian_connectivity(W, normalize=\"rw\")     # random-walk\n",
    "print(\"normalized Laplacians:\", L_sym.shape, L_rw.shape)\n",
    "\n",
    "sig_lap = run_with('laplacian')\n",
    "print(\"laplacian network ran:\", sig_lap.shape)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6a4d99889e74",
   "metadata": {},
   "source": [
    "## Nonlinear couplings\n",
    "\n",
    "Nonlinear couplings **saturate** the transmitted signal, which keeps a strongly\n",
    "coupled network from blowing up and better matches the bounded firing rates of\n",
    "real neural populations.\n",
    "\n",
    "### Hyperbolic tangent (`tanh`) — symmetric saturation\n",
    "\n",
    "`HyperbolicTangentCoupling` applies `tanh` *after* the network sum, so the\n",
    "coupling current saturates smoothly to $\\pm k$. Use it when you want a symmetric,\n",
    "bounded version of additive coupling. Tune `scale` (steepness) and `k` (the\n",
    "saturation level).\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "df47790e5b5f",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-06-19T07:41:11.813622Z",
     "iopub.status.busy": "2026-06-19T07:41:11.813349Z",
     "iopub.status.idle": "2026-06-19T07:41:12.072760Z",
     "shell.execute_reply": "2026-06-19T07:41:12.071880Z"
    }
   },
   "outputs": [
    {
     "data": {
      "image/png": "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MWP09mFpaQk7OzvZRkREREQtY9Dlt6KjozF16lT4+fnB398fCQkJqKmpkR68ioiIgLu7O+Lj42X7JSYmIiwsTCtJVavVGDduHHJycrB161Y0NDRI820dHR1hYWEhtd2zZw/y8/N1zrH95ptvYG5uDh8fH1haWuLAgQNYsGABJk6cKCW9+/fvR1FREXx9fVFUVITFixdDo9Hg9ddfb9VrRERERES6GTSRnThxIs6dO4e4uDiUlpbC19cXO3bskB4AKyws1JpzmpeXh71792LXrl1a/RUVFWHLli0AAF9fX1ldWloagoODpdeJiYkIDAyEt7e3Vj9mZmZYvnw5jh8/DiEEunTpgqioKLzyyitSmytXrmDhwoU4deoUbGxs8MQTT+Drr7/WuzoCEREREbUug64je7/jOrJEREREckaxjiwRERER0e1gIktERERERomJLBEREREZJSayRERERGSUmMgSERERkVFiIktERERERomJLBEREREZJSayRERERGSUmMgSERERkVFiIktERERERomJLBEREREZJSayRERERGSUmMgSERERkVFiIktERERERomJLBEREREZJSayRERERGSUmMgSERERkVFiIktERERERomJLBEREREZJTNDB0Btr76gABWff27oMIiIiMjI2QYHwzYkxNBhSJjI3geuVlZCtekHQ4dBRERERs68Y0cmsnRnmbu5ocMrrxg6DCIiIjJy7R7ub+gQZJjI3gfMXV3h/NwsQ4dBRERE1Kr4sBcRERERGSUmskRERERklAyeyK5evRqenp5QKpUICAhAZmam3rbBwcFQKBRa28iRIwEAarUaMTEx8PHxgbW1Ndzc3BAREYHi4mKpj/T0dJ19KBQKZGVlAQDy8vLw2GOPwcXFBUqlEl27dsXChQuhVqtl8SQkJKBXr16wsrKCh4cHXnnlFVy5cqUNrhIRERER3cigc2Q3bNiA6OhorF27FgEBAUhISEBoaCjy8vLQsWNHrfYpKSmor6+XXldWVqJfv34YP348AKC2thY5OTmIjY1Fv379cOHCBbz88ssYPXo0Dhw4AAAIDAxESUmJrN/Y2FikpqbCz88PAGBubo6IiAg8/PDDcHBwwB9//IGZM2dCo9Fg2bJlAIBvv/0W8+fPxxdffIHAwEAcP34c06ZNg0KhwMqVK9vkehERERHR/yiEEMJQBw8ICMDAgQOxatUqAIBGo4GHhwfmzJmD+fPnN7l/QkIC4uLiUFJSAmtra51tsrKy4O/vj4KCAnTu3FmrXq1Ww93dHXPmzEFsbKzeY0VHRyMrKwu//fYbACAqKgr//e9/kZqaKrWZN28e9u/fj7179zYZOwBUV1fD3t4eKpUKdnZ2zdqHiIiI6F52K/mRwaYW1NfXIzs7GyHXrUVmYmKCkJAQZGRkNKuPxMRETJo0SW8SCwAqlQoKhQIODg4667ds2YLKykpMnz5dbx8nT57Ejh07MHToUKksMDAQ2dnZ0lSIU6dOYfv27XjiiSf09lNXV4fq6mrZRkREREQtY7CpBRUVFWhoaICLi4us3MXFBceOHWty/8zMTOTm5iIxMVFvmytXriAmJgbh4eF6M/rExESEhoaiU6dOWnWBgYHIyclBXV0dZs2ahaVLl0p1kydPRkVFBQYPHgwhBK5evYrnn38eb7zxht544uPjsWTJEq1yJrRERERE1zTmRc2aNCAMpKioSAAQ+/btk5W/9tprwt/fv8n9Z82aJXx8fPTW19fXi1GjRon+/fsLlUqls82ZM2eEiYmJ2LRpk876wsJCceTIEfHtt98Kd3d3sXz5cqkuLS1NuLi4iM8//1wcPnxYpKSkCA8PD7F06VK9MV25ckWoVCppO3r0qADAjRs3bty4cePG7YbtzJkzTeaDBrsj6+zsDFNTU5SVlcnKy8rK4OrqetN9a2pqkJycLLtDej21Wo0JEyagoKAAe/bs0Xs3NikpCU5OThg9erTOeg8PDwBAnz590NDQgFmzZmHevHkwNTVFbGwsnnnmGURGRgIAfHx8UFNTg1mzZuHNN9+EiYn2rA1LS0tYWlpKr21sbHDmzBnY2tpCoVDc9JxvV3V1NTw8PHDmzBnOx72LcZyMA8fJOHCcjAfHyjjcqXESQuDixYtwc3Nrsq3BElkLCwsMGDAAqampCAsLA3DtYa/U1FRERUXddN+NGzeirq4OU6ZM0aprTGJPnDiBtLQ0ODk56exDCIGkpCRERETA3Ny8yXg1Gg3UajU0Gg1MTU1RW1urlayamppKfTeHiYmJzikNbcnOzo4fEkaA42QcOE7GgeNkPDhWxuFOjJO9vX2z2hl0+a3o6GhMnToVfn5+8Pf3R0JCAmpqaqQHryIiIuDu7o74+HjZfomJiQgLC9NKUtVqNcaNG4ecnBxs3boVDQ0NKC0tBQA4OjrCwsJCartnzx7k5+dLd1Sv980338Dc3Bw+Pj6wtLTEgQMHsGDBAkycOFFKekeNGoWVK1eif//+CAgIwMmTJxEbG4tRo0ZJCS0RERERtR2DJrITJ07EuXPnEBcXh9LSUvj6+mLHjh3SA2CFhYVadz3z8vKwd+9e7Nq1S6u/oqIibNmyBQDg6+srq0tLS0NwcLD0OjExEYGBgfD29tbqx8zMDMuXL8fx48chhECXLl0QFRWFV155RWqzcOFCKBQKLFy4EEVFRejQoQNGjRqFt99+u6WXg4iIiIhugUHXkaU7p66uDvHx8ViwYIFsni7dXThOxoHjZBw4TsaDY2Uc7sZxYiJLREREREbJYF+IQERERER0O5jIEhEREZFRYiJLREREREaJiex9YPXq1fD09IRSqURAQAAyMzMNHdJ9ZfHixVAoFLLt+tUyrly5gtmzZ8PJyQk2NjZ46qmntL4opLCwECNHjkS7du3QsWNHvPbaa7h69eqdPpV7yq+//opRo0bBzc0NCoUCmzdvltULIRAXF4cHHngAVlZWCAkJwYkTJ2Rtzp8/j6effhp2dnZwcHDAjBkzcOnSJVmbw4cPY8iQIVAqlfDw8MC7777b1qd2T2lqnKZNm6b18zVixAhZG45T24uPj8fAgQNha2uLjh07IiwsDHl5ebI2rfVZl56ejocffhiWlpbo3r071q1b19and89ozjgFBwdr/Uw9//zzsjZ31Tg1+d1fZNSSk5OFhYWF+OKLL8SRI0fEzJkzhYODgygrKzN0aPeNRYsWiQcffFCUlJRI27lz56T6559/Xnh4eIjU1FRx4MAB8cgjj4jAwECp/urVq6Jv374iJCREHDx4UGzfvl04OzuLBQsWGOJ07hnbt28Xb775pkhJSREAxI8//iirf+edd4S9vb3YvHmz+OOPP8To0aOFl5eXuHz5stRmxIgRol+/fuL3338Xv/32m+jevbsIDw+X6lUqlXBxcRFPP/20yM3NFd99952wsrISn3766Z06TaPX1DhNnTpVjBgxQvbzdf78eVkbjlPbCw0NFUlJSSI3N1ccOnRIPPHEE6Jz587i0qVLUpvW+Kw7deqUaNeunYiOjhZHjx4VH3/8sTA1NRU7duy4o+drrJozTkOHDhUzZ86U/UypVCqp/m4bJyay9zh/f38xe/Zs6XVDQ4Nwc3MT8fHxBozq/rJo0SLRr18/nXVVVVXC3NxcbNy4USr773//KwCIjIwMIcS1f8hNTExEaWmp1GbNmjXCzs5O1NXVtWns94sbEySNRiNcXV3Fe++9J5VVVVUJS0tL8d133wkhhDh69KgAILKysqQ2//73v4VCoRBFRUVCCCE++eQT0b59e9k4xcTEiF69erXxGd2b9CWyY8aM0bsPx8kwysvLBQDxyy+/CCFa77Pu9ddfFw8++KDsWBMnThShoaFtfUr3pBvHSYhriezLL7+sd5+7bZw4teAeVl9fj+zsbISEhEhlJiYmCAkJQUZGhgEju/+cOHECbm5u6Nq1K55++mkUFhYCALKzs6FWq2Vj5O3tjc6dO0tjlJGRAR8fH+mLQgAgNDQU1dXVOHLkyJ09kftEfn4+SktLZeNib2+PgIAA2bg4ODjAz89PahMSEgITExPs379fahMUFCT7VsHQ0FDk5eXhwoULd+hs7n3p6eno2LEjevXqhRdeeAGVlZVSHcfJMFQqFYBr36oJtN5nXUZGhqyPxjb8N61lbhynRt988w2cnZ3Rt29fLFiwALW1tVLd3TZOBv1mL2pbFRUVaGhokL3ZAMDFxQXHjh0zUFT3n4CAAKxbtw69evVCSUkJlixZgiFDhiA3NxelpaWwsLCAg4ODbB8XFxfp65VLS0t1jmFjHbW+xuuq67pfPy4dO3aU1ZuZmcHR0VHWxsvLS6uPxrr27du3Sfz3kxEjRmDs2LHw8vLCX3/9hTfeeAOPP/44MjIyYGpqynEyAI1Gg7lz5+LRRx9F3759AaDVPuv0tamursbly5dhZWXVFqd0T9I1TgAwefJkdOnSBW5ubjh8+DBiYmKQl5eHlJQUAHffODGRJWpjjz/+uPT/Dz30EAICAtClSxd8//33/NAluk2TJk2S/t/HxwcPPfQQunXrhvT0dAwbNsyAkd2/Zs+ejdzcXOzdu9fQodBN6BunWbNmSf/v4+ODBx54AMOGDcNff/2Fbt263ekwm8SpBfcwZ2dnmJqaaj0VWlZWBldXVwNFRQ4ODujZsydOnjwJV1dX1NfXo6qqStbm+jFydXXVOYaNddT6Gq/rzX52XF1dUV5eLqu/evUqzp8/z7EzoK5du8LZ2RknT54EwHG606KiorB161akpaWhU6dOUnlrfdbpa2NnZ8cbA7dA3zjpEhAQAACyn6m7aZyYyN7DLCwsMGDAAKSmpkplGo0GqampGDRokAEju79dunQJf/31Fx544AEMGDAA5ubmsjHKy8tDYWGhNEaDBg3Cn3/+KfvHePfu3bCzs0OfPn3uePz3Ay8vL7i6usrGpbq6Gvv375eNS1VVFbKzs6U2e/bsgUajkT74Bw0ahF9//RVqtVpqs3v3bvTq1Yt/rm4jZ8+eRWVlJR544AEAHKc7RQiBqKgo/Pjjj9izZ4/WVI3W+qwbNGiQrI/GNvw3rXmaGiddDh06BACyn6m7apxa/fExuqskJycLS0tLsW7dOnH06FExa9Ys4eDgIHvakNrWvHnzRHp6usjPzxf/+c9/REhIiHB2dhbl5eVCiGtL0nTu3Fns2bNHHDhwQAwaNEgMGjRI2r9xqZPhw4eLQ4cOiR07dogOHTpw+a3bdPHiRXHw4EFx8OBBAUCsXLlSHDx4UBQUFAghri2/5eDgIH766Sdx+PBhMWbMGJ3Lb/Xv31/s379f7N27V/To0UO2rFNVVZVwcXERzzzzjMjNzRXJycmiXbt2XNbpFtxsnC5evCheffVVkZGRIfLz88XPP/8sHn74YdGjRw9x5coVqQ+OU9t74YUXhL29vUhPT5ct21RbWyu1aY3PusZlnV577TXx3//+V6xevZrLb92Cpsbp5MmTYunSpeLAgQMiPz9f/PTTT6Jr164iKChI6uNuGycmsveBjz/+WHTu3FlYWFgIf39/8fvvvxs6pPvKxIkTxQMPPCAsLCyEu7u7mDhxojh58qRUf/nyZfHiiy+K9u3bi3bt2oknn3xSlJSUyPo4ffq0ePzxx4WVlZVwdnYW8+bNE2q1+k6fyj0lLS1NANDapk6dKoS4tgRXbGyscHFxEZaWlmLYsGEiLy9P1kdlZaUIDw8XNjY2ws7OTkyfPl1cvHhR1uaPP/4QgwcPFpaWlsLd3V288847d+oU7wk3G6fa2loxfPhw0aFDB2Fubi66dOkiZs6cqfWLOsep7ekaIwAiKSlJatNan3VpaWnC19dXWFhYiK5du8qOQTfX1DgVFhaKoKAg4ejoKCwtLUX37t3Fa6+9JltHVoi7a5wU///EiIiIiIiMCufIEhEREZFRYiJLREREREaJiSwRERERGSUmskRERERklJjIEhEREZFRYiJLREREREaJiSwRERERGSUmskRERERklJjIEhHd49LT06FQKFBVVWXoUIiIWhW/2YuI6B4THBwMX19fJCQkAADq6+tx/vx5uLi4QKFQGDY4IqJWZGboAIiIqG1ZWFjA1dXV0GEQEbU6Ti0gIrqHTJs2Db/88gs+/PBDKBQKKBQKrFu3Tja1YN26dXBwcMDWrVvRq1cvtGvXDuPGjUNtbS2+/PJLeHp6on379njppZfQ0NAg9V1XV4dXX30V7u7usLa2RkBAANLT0w1zokRE4B1ZIqJ7yocffojjx4+jb9++WLp0KQDgyJEjWu1qa2vx0UcfITk5GRcvXsTYsWPx5JNPwsHBAdu3b8epU6fw1FNP4dFHH8XEiRMBAFFRUTh69CiSk5Ph5uaGH3/8ESNGjMCff/6JHj163NHzJCICmMgSEd1T7O3tYWFhgXbt2knTCY4dO6bVTq1WY82aNejWrRsAYNy4cfj6669RVlYGGxsb9OnTB4899hjS0tIwceJEFBYWIikpCYWFhXBzcwMAvPrqq9ixYweSkpKwbNmyO3eSRET/HxNZIqL7ULt27aQkFgBcXFzg6ekJGxsbWVl5eTkA4M8//0RDQwN69uwp66eurg5OTk53JmgiohswkSUiug+Zm5vLXisUCp1lGo0GAHDp0iWYmpoiOzsbpqamsnbXJ79ERHcSE1kionuMhYWF7CGt1tC/f380NDSgvLwcQ4YMadW+iYhaiqsWEBHdYzw9PbF//36cPn0aFRUV0l3V29GzZ088/fTTiIiIQEpKCvLz85GZmYn4+Hhs27atFaImIrp1TGSJiO4xr776KkxNTdGnTx906NABhYWFrdJvUlISIiIiMG/ePPTq1QthYWHIyspC586dW6V/IqJbxW/2IiIiIiKjxDuyRERERGSUmMgSERERkVFiIktERERERomJLBEREREZJSayRERERGSUmMgSERERkVFiIktERERERomJLBEREREZJSayRERERGSUmMgSERERkVFiIktERERERomJLBEREREZpf8HpLCe350/PboAAAAASUVORK5CYII=",
      "text/plain": [
       "<Figure size 700x300 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "# Network uses the coupling's defaults (tanh: k forwarded, scale=2.0); for full\n",
    "# control over `scale` build the coupling directly (see \"Direct construction\").\n",
    "sig_tanh = run_with('tanh', k=0.5)\n",
    "fig, ax = plt.subplots(figsize=(7, 3))\n",
    "brainmass.viz.plot_timeseries(sig_tanh[:, :4], ax=ax)\n",
    "ax.set_title(\"Hyperbolic-tangent coupling (saturates to +/- k)\")\n",
    "fig.tight_layout(); plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "df572a101623",
   "metadata": {},
   "source": [
    "### Sigmoidal — asymmetric (firing-rate) saturation\n",
    "\n",
    "`SigmoidalCoupling` applies a logistic $\\sigma$ after the sum, mapping the input\n",
    "to a bounded, *one-sided* range — the shape of a population firing-rate transfer\n",
    "function. `slope` controls steepness, `midpoint` the threshold, `a`/`b` an\n",
    "affine pre-scaling. At zero input the current is $k\\,\\sigma(-\\mathrm{slope}\\cdot\n",
    "\\mathrm{midpoint})$.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "c3736874e004",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-06-19T07:41:12.075252Z",
     "iopub.status.busy": "2026-06-19T07:41:12.074963Z",
     "iopub.status.idle": "2026-06-19T07:41:12.346152Z",
     "shell.execute_reply": "2026-06-19T07:41:12.345404Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "sigmoidal network ran: (2500, 8)\n"
     ]
    },
    {
     "data": {
      "image/png": "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ggULFqBBgwaIiIiAo6MjpkyZAnt7+xrLU6fTSWuhxsbGws7ODi+//DL++c9/IiAg4KH7zp8/H/b29khISMDu3buh1WqxY8cO9O/f3yLu3XffRVFREb766its2rQJHTp0wPbt2zFr1qxq5ezk5ISffvoJc+bMwTfffIO1a9fC09MTPXv2RMOGDQEADg4O2LNnD2bNmoW1a9fCYDAgKCgIq1evLvfyiaVLl6KkpAQJCQlQqVT461//ivj4+AofKFMoFEhKSsKECRMwffp0ODs7S9eutjzJnwci+vNkgrPciYjKiYyMxOeff47CwkK+7tQKRo0ahS1btqCwsNDaqQDgzwPR04pzZInouXfv3j2L77du3cK6devw4osvsmh5DvHngch2cGoBET33QkJC0L17d7Ro0QK5ublYuXIlDAYDZs+ebe3UyAr480BkO1jIEtFzr1+/ftiyZQtWrFgBmUyGDh06YOXKlXjppZesnRpZAX8eiGwH58gSERERkU3iHFkiIiIiskksZImIiIjIJnGObC0ym824du0anJ2duYg2ERER0WMQQuDOnTvw9va2eO11RVjI1qJr167B19fX2mkQERER2ZzLly9LL16pDAvZWlT2WsbLly/DxcXFytkQERERPf0MBgN8fX2lOuphWMjWorLpBC4uLixkiYiIiKrgcaZl8mEvIiIiIrJJLGSJiIiIyCY9FYXs8uXL4e/vD3t7e2i1WqSlpVUa2717d8hksnKf/v37SzFCCMTGxkKj0cDBwQE6nQ5nz56Vtl+4cAFjx45FQEAAHBwc0KRJE8yZMwdGo9EipqLj/PLLL7VzEYiIiIioSqxeyG7atAnR0dGYM2cODh06hLZt2yI0NBTXr1+vMH7r1q3Izs6WPhkZGVAoFBg6dKgU8+GHH2LJkiVISEhAamoqHB0dERoaivv37wMATp8+DbPZjM8//xwnTpzAJ598goSEBLz77rvljvfjjz9aHC84OLh2LgQRERERVYnVX1Gr1WrRqVMnLFu2DMCDtVd9fX0xefJkzJo165H7L168GLGxscjOzoajoyOEEPD29sY777yDadOmAQAKCgqgVquxZs0aDBs2rMJ+4uPj8dlnn+HcuXMAHtyRDQgIwOHDh9GuXbtqnZvBYICrqysKCgr4sBcRERHRY6hK/WTVVQuMRiPS09MRExMjtcnlcuh0Ouj1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",
      "text/plain": [
       "<Figure size 700x300 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "sig_sig = run_with('sigmoidal', k=0.5)   # defaults slope=1, midpoint=0\n",
    "print(\"sigmoidal network ran:\", sig_sig.shape)\n",
    "fig, ax = plt.subplots(figsize=(7, 3))\n",
    "brainmass.viz.plot_timeseries(sig_sig[:, :4], ax=ax)\n",
    "ax.set_title(\"Sigmoidal coupling\")\n",
    "fig.tight_layout(); plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "00124da75d47",
   "metadata": {},
   "source": [
    "### Sigmoidal Jansen-Rit — pre-nonlinearity transfer\n",
    "\n",
    "`SigmoidalJansenRitCoupling` is a **pre**-nonlinearity: the sigmoid\n",
    "$\\sigma_{JR}$ is applied to *each source* before the weighted sum, modelling the\n",
    "presynaptic potential-to-rate transfer in the Jansen-Rit column. It is the\n",
    "coupling to use for Jansen-Rit whole-brain networks, where the source is the\n",
    "pyramidal input `y1 - y2`. Parameters `cmin`/`cmax` bound the rate, `midpoint`/`r`\n",
    "shape the curve.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "40785f5db259",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-06-19T07:41:12.347899Z",
     "iopub.status.busy": "2026-06-19T07:41:12.347729Z",
     "iopub.status.idle": "2026-06-19T07:41:12.726683Z",
     "shell.execute_reply": "2026-06-19T07:41:12.725868Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "sigmoidal_jansen_rit output: (8,)  (bounded firing-rate currents)\n",
      "range: 0.004580279812216759 -> 0.01149471290409565\n"
     ]
    }
   ],
   "source": [
    "# Demonstrate the kernel directly on a synthetic source (pre-nonlinearity form).\n",
    "src = jnp.linspace(0.0, 12.0, N)                  # presynaptic potentials\n",
    "W_jr = jnp.asarray(W)\n",
    "c = brainmass.sigmoidal_jansen_rit_coupling(\n",
    "    src[None, :] * jnp.ones((N, N)),              # each target reads every source\n",
    "    conn=W_jr, k=1.0, cmin=0.0, cmax=0.005, midpoint=6.0, r=0.56,\n",
    ")\n",
    "print(\"sigmoidal_jansen_rit output:\", c.shape, \" (bounded firing-rate currents)\")\n",
    "print(\"range:\", float(c.min()), \"->\", float(c.max()))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "79a0d650cf9d",
   "metadata": {},
   "source": [
    "When wiring it into a Jansen-Rit `Network`, select it with\n",
    "`coupling='sigmoidal_jansen_rit'` and `coupled_var='y1'` (or whatever pyramidal\n",
    "observable your node exposes) — the `Network` plugs the delayed source read into\n",
    "the coupling exactly as above.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d1f998ffd7e5",
   "metadata": {},
   "source": [
    "## Choosing a coupling\n",
    "\n",
    "- **`diffusive`** — default for brain networks; models synchronization. Start here.\n",
    "- **`additive`** — when the connectome is a genuine input current, not a\n",
    "  consensus pull. Cheapest.\n",
    "- **`laplacian`** — diffusive coupling via a (possibly normalized) graph\n",
    "  Laplacian; reuse a precomputed `L`.\n",
    "- **`tanh`** — when strong coupling would otherwise destabilize the network and you\n",
    "  want a symmetric bound.\n",
    "- **`sigmoidal`** — when the coupling should act like a population firing-rate\n",
    "  (bounded, one-sided, thresholded).\n",
    "- **`sigmoidal_jansen_rit`** — the canonical Jansen-Rit pre-synaptic transfer.\n",
    "\n",
    "Tuning `k`:\n",
    "\n",
    "1. Start around `k ~ 0.1`–`0.5`.\n",
    "2. Increase until the network shows the connectivity / synchrony you expect.\n",
    "3. Too high → everything synchronizes (unphysical); too low → no functional\n",
    "   connectivity. Sweep it (see {doc}`/howto/parameter_sweeps`).\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2eec39271f33",
   "metadata": {},
   "source": [
    "## Direct construction (advanced)\n",
    "\n",
    "`Network` is the convenient path, but you can build a coupling object directly\n",
    "from *prefetch* references to a node's state — useful for custom wiring (e.g.\n",
    "coupling two different state variables, or asymmetric forward/backward weights).\n",
    "A diffusive coupling needs a delayed `(N, N)` source read (each target reads every\n",
    "source) plus a `(N,)` self read.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "2c57736ec32a",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-06-19T07:41:12.728804Z",
     "iopub.status.busy": "2026-06-19T07:41:12.728459Z",
     "iopub.status.idle": "2026-06-19T07:41:13.274076Z",
     "shell.execute_reply": "2026-06-19T07:41:13.273281Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "manual diffusive current: (8,)\n"
     ]
    }
   ],
   "source": [
    "from brainmass import delay_index\n",
    "nodes = brainmass.HopfStep(in_size=N, a=0.2, w=0.3)\n",
    "\n",
    "delays = jnp.ones((N, N)) * (1.0 * u.ms)\n",
    "idx = delay_index(N)                                    # standard (N, N) source index\n",
    "x_src = nodes.prefetch_delay('x', (delays, idx),\n",
    "                             init=braintools.init.Constant(0.0))   # (N, N)\n",
    "x_self = nodes.prefetch('x')                            # (N,)\n",
    "\n",
    "coupling = brainmass.DiffusiveCoupling(x_src, x_self, conn=W, k=0.5)\n",
    "brainstate.nn.init_all_states(nodes)\n",
    "brainstate.nn.init_all_states(coupling)\n",
    "with brainstate.environ.context(i=0, t=0. * u.ms):\n",
    "    current = coupling.update()                          # (N,) per-node current\n",
    "print(\"manual diffusive current:\", current.shape)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a6fb4f751a74",
   "metadata": {},
   "source": [
    "The nonlinear classes (`SigmoidalCoupling`, `HyperbolicTangentCoupling`,\n",
    "`SigmoidalJansenRitCoupling`) construct the same way — pass the prefetched source,\n",
    "`conn`, and the shape parameters. Any of these parameters can be a trainable\n",
    "`Param` for fitting (see {doc}`/tutorials/06_fitting_with_gradients`).\n",
    "\n",
    "## Troubleshooting\n",
    "\n",
    "- **Network explodes** → lower `k`, normalize `W` (divide by row sums or max), or\n",
    "  switch to a saturating (`tanh` / `sigmoidal`) coupling.\n",
    "- **No synchronization** → raise `k`; check for isolated nodes in `W`; run longer.\n",
    "- **Shape error from a coupling** → diffusive coupling needs a `(N, N)` *source*\n",
    "  read (via `prefetch_delay`) and a `(N,)` *self* read; a plain `prefetch('x')`\n",
    "  for the source is too small.\n",
    "\n",
    "## Next steps\n",
    "\n",
    "- {doc}`/tutorials/04_building_a_network` — full network construction.\n",
    "- {doc}`/howto/parameter_sweeps` — sweep the coupling strength `k`.\n",
    "- {doc}`/howto/analyze_results` — measure the FC the coupling produces.\n",
    "- {doc}`/reference/coupling` — the coupling API reference.\n"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "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.13.11"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}