{
"cells": [
{
"cell_type": "markdown",
"id": "e5f7930c7774",
"metadata": {},
"source": [
"# Chapter 21: Markets, Teams, and Institutions\n",
"\n",
"A team adds a shortcut between two workflow stages. Every participant sees a privately attractive route, yet their collective routing can increase delay. The missing ingredient is congestion: each choice changes the cost other participants face.\n",
"\n",
"This notebook solves a symmetric continuous-flow Braess construction. Two outer routes share a new shortcut route, with linear congestion and fixed delays. It calculates private equilibrium and total social travel time, then compares a toll intervention and an exact social optimum. The example is a declared institution model. It does not estimate a real market or suggest that every new workflow interface causes a paradox.\n",
"\n",
"**Outcome:** Compare Braess equilibrium, social optimum, tolls, and overhead.\n",
"\n",
"- Inspect the declared input contract\n",
"- Predict the hand-checkable case\n",
"- Run the shared computation\n",
"- Change the critical assumption\n",
"- Apply the method to the transfer data\n",
"\n",
"**Guided route:** Run the worked calculation, inspect its figure, change the stated assumption, and try the transfer case. Read the explanations beside each result before opening the answers.\n",
"\n",
"**Deeper route:** First read the mathematics and canonical equation reference. Audit the input contract, predict the changed result, then inspect the shared chapter implementation and solve the questions independently. Both routes use the same calculations and preserve the equations."
]
},
{
"cell_type": "markdown",
"id": "a7781f3ee7dc",
"metadata": {},
"source": [
"## Technical Requirements\n",
"\n",
"Python 3.11 or later, the complete laboratory folder, and the notebook dependencies listed in `requirements-notebooks.txt` (the launcher's **Install notebook tools** choice installs them; see START-HERE). Standard-library chapter commands also support Python 3.10. No API key, model account or network call is used by this experiment.\n",
"\n",
"Prior knowledge:\n",
"\n",
"- Python lists and dictionaries\n",
"- The mapped chapter and its notation"
]
},
{
"cell_type": "markdown",
"id": "b8921855fc15",
"metadata": {},
"source": [
"## The question and its mathematics\n",
"\n",
"Let total demand be D. Symmetry assigns x to each outer route and z to the shortcut, so 2x+z=D. Each congestible edge carries x+z and takes time v=(x+z)/capacity. Outer path time is v+c; shortcut time is 2v+overhead. The shortcut also pays a private toll.\n",
"\n",
"At an interior equilibrium, used routes have equal private cost. Solving v+c=2v+overhead+toll gives z=2 capacity(c-overhead-toll)-D, clipped to [0,D]. Boundary clipping handles unused outer or shortcut routes. Without the shortcut, outer flow is D/2 and total travel time is D[D/(2 capacity)+c].\n",
"\n",
"Social travel time excludes toll transfers and equals 2x(v+c)+z(2v+overhead). After substitution it is (D+z)^2/(2 capacity)+c(D-z)+overhead*z. This convex quadratic is minimized at z=capacity(c-overhead)-D, clipped to [0,D]. The price of anarchy compares equilibrium social time with that minimum, not with toll-inclusive private expense."
]
},
{
"cell_type": "markdown",
"id": "0134acecc887",
"metadata": {},
"source": [
"## A calculation you can run\n",
"\n",
"Declare demand, congestion capacity, outer constant delay, shortcut overhead, and toll. Validation requires positive demand and capacity and nonnegative other quantities. The function computes symmetric equilibrium flow, path costs, total delay, optimal shortcut flow, and toll revenue.\n",
"\n",
"The figure varies shortcut flow from zero to total demand and plots exact social travel time. Its minimum should match the reported optimum. In the changed case add toll 0.5 without changing physical travel times. Predict how it shifts equilibrium, then compare social cost. The transfer case reduces demand, checking that a shortcut need not worsen performance under every loading condition.\n",
"\n",
"The next cell finds the bundle and imports the same computation used by the chapter skill. It does not change your system Python."
]
},
{
"cell_type": "code",
"execution_count": 1,
"id": "42ebefc0e5c1",
"metadata": {},
"outputs": [],
"source": [
"from pathlib import Path\n",
"import sys, json\n",
"LAB_ROOT = next((p for p in [Path.cwd(), *Path.cwd().parents] if (p / \"lab-manifest.json\").is_file()), None)\n",
"if LAB_ROOT is None:\n",
" raise RuntimeError(\"Open this notebook from the complete extracted laboratory folder.\")\n",
"sys.path.insert(0, str(LAB_ROOT / \"src\"))\n",
"from math_ai_agents.core import analyze, report_text\n",
"from math_ai_agents.plotting import figure_svg\n",
"from IPython.display import SVG, display\n"
]
},
{
"cell_type": "markdown",
"id": "7fffde8c0edb",
"metadata": {},
"source": [
"Set the declared inputs below. These are constructed teaching values, not measurements from a production agent. Change a value only after predicting what it should change."
]
},
{
"cell_type": "code",
"execution_count": 2,
"id": "6875f8982178",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Chapter 21: congestion-incentives\n",
"Can a faster-looking route make the whole workflow slower?\n",
"Evidence: constructed teaching example\n",
"\n",
"Calculated quantities:\n",
"{\n",
" \"without_shortcut_total_time\": 1.5,\n",
" \"equilibrium_shortcut_flow\": 1.0,\n",
" \"equilibrium_outer_flow_each\": 0.0,\n",
" \"equilibrium_social_time\": 2.0,\n",
" \"equilibrium_private_outer_time\": 2.0,\n",
" \"equilibrium_private_shortcut_time\": 2.0,\n",
" \"optimal_shortcut_flow\": 0,\n",
" \"optimal_social_time\": 1.5,\n",
" \"price_of_anarchy\": 1.333333333,\n",
" \"braess_worsens\": true,\n",
" \"toll_revenue\": 0.0\n",
"}\n",
"\n",
"Interpretation:\n",
"A new route can change private incentives and increase total delay. Tolls enter private cost; toll payments are excluded from travel-time social cost.\n",
"\n",
"Assumptions:\n",
"- Symmetric continuous flow, linear congestible edges, constant outer edges.\n",
"- All travelers choose minimum private path cost at nonatomic equilibrium.\n",
"\n",
"Limitations:\n",
"- This construction does not estimate a real workflow equilibrium.\n",
"- Discrete teams and heterogeneous incentives need additional modeling.\n",
"\n",
"Execution: completed locally; constructed inputs are not deployment measurements.\n"
]
}
],
"source": [
"chapter = 21\n",
"inputs = {'demand': 1,\n",
" 'capacity': 1,\n",
" 'constant_time': 1,\n",
" 'shortcut_overhead': 0,\n",
" 'shortcut_toll': 0}\n",
"report = analyze(chapter, inputs)\n",
"# This input was explicitly taken from the teaching fixture.\n",
"report['evidence_kind'] = 'constructed teaching example'\n",
"print(report_text(report))"
]
},
{
"cell_type": "markdown",
"id": "fdbe133ae5d1",
"metadata": {},
"source": [
"Without the shortcut, default total time is 1(0.5+1)=1.5. With a zero-cost shortcut, equilibrium sends all demand through it, giving path time 2 and total time 2. The social optimum uses no shortcut and remains at 1.5. Price of anarchy is 2/1.5=4/3.\n",
"\n",
"A toll 0.5 changes the equilibrium shortcut flow to zero. Outer private time is 1.5, while an unused shortcut would also cost 1.5 including toll. Total travel time returns to 1.5. The toll affects incentives; it is not counted as destroyed travel time or an extra physical delay.\n",
"\n",
"The toll 0.5 sits exactly at the break-even value, so this teaching case is knife-edge. At toll 0.49 the lab returns shortcut flow 0.02 and equilibrium social time 1.5002, and at 0.51 it returns flow 0 and time 1.5. Try nearby tolls to see the threshold rather than reading 0.5 as a robust remedy.\n",
"\n",
"The plot below uses the calculated quantities. Read each panel's units before comparing its values."
]
},
{
"cell_type": "code",
"execution_count": 3,
"id": "590f57e74048",
"metadata": {},
"outputs": [
{
"name": "stderr",
"output_type": "stream",
"text": [
"Matplotlib is building the font cache; this may take a moment.\n"
]
},
{
"data": {
"image/svg+xml": [
""
],
"text/plain": [
""
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"display(SVG(figure_svg(report)))"
]
},
{
"cell_type": "markdown",
"id": "623a8169d7e3",
"metadata": {},
"source": [
"**Figure 21.L1:** Calculated chapter experiment. Each panel labels its input and output units; interpret it under the assumptions printed in the report."
]
},
{
"cell_type": "markdown",
"id": "69b7a9983c66",
"metadata": {},
"source": [
"## Change the assumption\n",
"\n",
"The paradox relies on a particular network and demand regime. At low demand, the shortcut can be socially useful and privately efficient. Presenting the default construction as a law against connectivity would erase those conditions.\n",
"\n",
"Institutional metrics can also confuse transfers with resource costs. A toll payment changes who bears money but is excluded from this travel-time objective. A real institution may care about distributional effects or administrative overhead, which should be modeled separately. Shortcut overhead here is a real delay and therefore enters social cost.\n",
"\n",
"Continuous equilibrium assumes many small participants choosing minimum private cost. A small team with indivisible jobs, strategic coordination, or centralized routing may behave differently. The calculation is an exact finite model result under those assumptions, not a fitted causal claim about organizational performance."
]
},
{
"cell_type": "code",
"execution_count": 4,
"id": "970e70c18a40",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Chapter 21: congestion-incentives\n",
"Can a faster-looking route make the whole workflow slower?\n",
"Evidence: constructed changed-assumption example\n",
"\n",
"Calculated quantities:\n",
"{\n",
" \"without_shortcut_total_time\": 1.5,\n",
" \"equilibrium_shortcut_flow\": 0,\n",
" \"equilibrium_outer_flow_each\": 0.5,\n",
" \"equilibrium_social_time\": 1.5,\n",
" \"equilibrium_private_outer_time\": 1.5,\n",
" \"equilibrium_private_shortcut_time\": 1.5,\n",
" \"optimal_shortcut_flow\": 0,\n",
" \"optimal_social_time\": 1.5,\n",
" \"price_of_anarchy\": 1.0,\n",
" \"braess_worsens\": false,\n",
" \"toll_revenue\": 0.0\n",
"}\n",
"\n",
"Interpretation:\n",
"A new route can change private incentives and increase total delay. Tolls enter private cost; toll payments are excluded from travel-time social cost.\n",
"\n",
"Assumptions:\n",
"- Symmetric continuous flow, linear congestible edges, constant outer edges.\n",
"- All travelers choose minimum private path cost at nonatomic equilibrium.\n",
"\n",
"Limitations:\n",
"- This construction does not estimate a real workflow equilibrium.\n",
"- Discrete teams and heterogeneous incentives need additional modeling.\n",
"\n",
"Execution: completed locally; constructed inputs are not deployment measurements.\n"
]
},
{
"data": {
"image/svg+xml": [
""
],
"text/plain": [
""
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"changed_inputs = {'demand': 1,\n",
" 'capacity': 1,\n",
" 'constant_time': 1,\n",
" 'shortcut_overhead': 0,\n",
" 'shortcut_toll': 0.5}\n",
"changed = analyze(chapter, changed_inputs)\n",
"changed['evidence_kind'] = 'constructed changed-assumption example'\n",
"print(report_text(changed))\n",
"display(SVG(figure_svg(changed)))"
]
},
{
"cell_type": "markdown",
"id": "bcb325454107",
"metadata": {},
"source": [
"**Figure 21.L2:** The changed-assumption result. Compare the printed quantities and the stated assumptions with the first run. A different input need not imply a causal effect in a deployed agent."
]
},
{
"cell_type": "markdown",
"id": "91a47d118b9d",
"metadata": {},
"source": [
"## Try a new case\n",
"\n",
"At demand 0.5, capacity 1, and constant delay 1, equilibrium sends all flow through the shortcut. Its total time is 0.5, below the no-shortcut total 0.625. The social optimum also uses shortcut flow 0.5, so price of anarchy is 1.\n",
"\n",
"For local workflow analysis, identify who selects routes and which costs they internalize. Separate routing overhead from incentive charges and preserve demand units. Compare local choice with a collective objective before adding a new interface. If route delays are estimated, collect measurements under several loads rather than assuming a linear congestion law."
]
},
{
"cell_type": "code",
"execution_count": 5,
"id": "dd273a9b53be",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Chapter 21: congestion-incentives\n",
"Can a faster-looking route make the whole workflow slower?\n",
"Evidence: constructed transfer example\n",
"\n",
"Calculated quantities:\n",
"{\n",
" \"without_shortcut_total_time\": 0.625,\n",
" \"equilibrium_shortcut_flow\": 0.5,\n",
" \"equilibrium_outer_flow_each\": 0.0,\n",
" \"equilibrium_social_time\": 0.5,\n",
" \"equilibrium_private_outer_time\": 1.5,\n",
" \"equilibrium_private_shortcut_time\": 1.0,\n",
" \"optimal_shortcut_flow\": 0.5,\n",
" \"optimal_social_time\": 0.5,\n",
" \"price_of_anarchy\": 1.0,\n",
" \"braess_worsens\": false,\n",
" \"toll_revenue\": 0.0\n",
"}\n",
"\n",
"Interpretation:\n",
"A new route can change private incentives and increase total delay. Tolls enter private cost; toll payments are excluded from travel-time social cost.\n",
"\n",
"Assumptions:\n",
"- Symmetric continuous flow, linear congestible edges, constant outer edges.\n",
"- All travelers choose minimum private path cost at nonatomic equilibrium.\n",
"\n",
"Limitations:\n",
"- This construction does not estimate a real workflow equilibrium.\n",
"- Discrete teams and heterogeneous incentives need additional modeling.\n",
"\n",
"Execution: completed locally; constructed inputs are not deployment measurements.\n"
]
}
],
"source": [
"transfer_inputs = {'demand': 0.5,\n",
" 'capacity': 1,\n",
" 'constant_time': 1,\n",
" 'shortcut_overhead': 0,\n",
" 'shortcut_toll': 0}\n",
"transfer = analyze(chapter, transfer_inputs)\n",
"transfer['evidence_kind'] = 'constructed transfer example'\n",
"print(report_text(transfer))"
]
},
{
"cell_type": "markdown",
"id": "1c513e3454cd",
"metadata": {},
"source": [
"## Apply the method to your inputs\n",
"\n",
"The example file below has the exact input shape the method accepts. Copy it to a new file, replace its values, then point `reader_file` at your copy. Run the cell again. Supplied inputs retain their stated provenance; the program cannot establish that they are representative observations.\n",
"\n",
"- **demand:** Positive continuous traveler or job flow in normalized units.\n",
"- **capacity:** Positive flow scale of each linear congestible edge.\n",
"- **constant_time:** Nonnegative fixed delay of each outer constant edge.\n",
"- **shortcut_overhead:** Nonnegative real delay on the shortcut.\n",
"- **shortcut_toll:** Nonnegative private incentive charge, excluded from travel-time social cost."
]
},
{
"cell_type": "code",
"execution_count": 6,
"id": "15ee3bffbd28",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Chapter 21: congestion-incentives\n",
"Can a faster-looking route make the whole workflow slower?\n",
"Evidence: supplied local inputs; provenance not independently verified\n",
"\n",
"Calculated quantities:\n",
"{\n",
" \"without_shortcut_total_time\": 0.625,\n",
" \"equilibrium_shortcut_flow\": 0.5,\n",
" \"equilibrium_outer_flow_each\": 0.0,\n",
" \"equilibrium_social_time\": 0.5,\n",
" \"equilibrium_private_outer_time\": 1.5,\n",
" \"equilibrium_private_shortcut_time\": 1.0,\n",
" \"optimal_shortcut_flow\": 0.5,\n",
" \"optimal_social_time\": 0.5,\n",
" \"price_of_anarchy\": 1.0,\n",
" \"braess_worsens\": false,\n",
" \"toll_revenue\": 0.0\n",
"}\n",
"\n",
"Interpretation:\n",
"A new route can change private incentives and increase total delay. Tolls enter private cost; toll payments are excluded from travel-time social cost.\n",
"\n",
"Assumptions:\n",
"- Symmetric continuous flow, linear congestible edges, constant outer edges.\n",
"- All travelers choose minimum private path cost at nonatomic equilibrium.\n",
"\n",
"Limitations:\n",
"- This construction does not estimate a real workflow equilibrium.\n",
"- Discrete teams and heterogeneous incentives need additional modeling.\n",
"\n",
"Execution: completed locally; constructed inputs are not deployment measurements.\n"
]
}
],
"source": [
"reader_file = LAB_ROOT / 'data/examples/ch21.json'\n",
"reader_inputs = json.loads(reader_file.read_text())\n",
"reader_report = analyze(chapter, reader_inputs)\n",
"print(report_text(reader_report))"
]
},
{
"cell_type": "markdown",
"id": "93f75333e8fe",
"metadata": {},
"source": [
"## Questions\n",
"\n",
"1. Compute default price of anarchy.\n",
"\n",
"2. Why exclude toll revenue from social travel time?\n",
"\n",
"3. Compute transfer social optimum.\n",
"\n",
"Answers: [separate solutions](../solutions/ch21.md). Try the calculation before opening them."
]
},
{
"cell_type": "markdown",
"id": "2f7445d25f6f",
"metadata": {},
"source": [
"## Summary\n",
"\n",
"Local incentives and collective outcomes can diverge. The Braess construction makes that divergence exact: a shortcut worsens default equilibrium, a toll restores efficient routing, and low-demand transfer removes the paradox. The notebook distinguishes physical overhead from private incentive charges and compares equilibrium with a convex social optimum. Its conclusions depend on the supplied network form, continuous flow, and cost law. It does not infer how a real team will respond.\n",
"\n",
"Limits of this experiment:\n",
"\n",
"- This is a local calculation under declared inputs, not an empirical claim about a deployed agent.\n",
"- Read the returned assumptions and limitations before applying the numerical result.\n",
"\n",
"The assistant skill is [`maa-21-congestion-incentives`](../skills/maa-21-congestion-incentives/SKILL.md). It uses this notebook's tested computation and input contract."
]
},
{
"cell_type": "markdown",
"id": "9cc9f25ba898",
"metadata": {},
"source": [
"## Equations from the chapter\n",
"\n",
"These are the unchanged display equations and their explanations from the canonical chapter. They are a reference for the experiment, not a claim that every equation is numerically implemented by this one method."
]
},
{
"cell_type": "markdown",
"id": "aac160861da5",
"metadata": {},
"source": [
"### Equation 21.1\n",
"\n",
"\n",
"\n",
"Equation (21.1) adds each edge's delay across all flow using that edge, producing the system's total time.\n",
"\n",
"Multiply traffic on every edge by its experienced latency, then add the products over the whole network.\n",
"\n",
"LaTeX source, preserved for inspection:\n",
"\n",
"```latex\n",
"\\operatorname{TL}(q) \\;=\\; \\sum_{e\\in\\mathcal E} q_e\\,\\ell_e(q_e).\n",
"\\tag{21.1}\n",
"```"
]
},
{
"cell_type": "markdown",
"id": "2b422832800c",
"metadata": {},
"source": [
"### Equation 21.2\n",
"\n",
"\n",
"\n",
"Equation (21.2) bounds self-directed routing's total delay against best feasible routing when every edge delay is linear.\n",
"\n",
"Divide equilibrium delay by optimal delay; under nonnegative straight-line latency rules, ratio never exceeds four thirds.\n",
"\n",
"LaTeX source, preserved for inspection:\n",
"\n",
"```latex\n",
"\\frac{\\operatorname{TL}(q^{\\mathrm{NE}})}{\\operatorname{TL}(q^{\\star})} \\;\\leq\\; \\frac{4}{3}\n",
"\\qquad\\text{when every }\\ell_e(q_e)=a_e q_e+b_e\\text{ with }a_e,b_e\\geq0.\n",
"\\tag{21.2}\n",
"```"
]
},
{
"cell_type": "markdown",
"id": "1d324cfd3fe9",
"metadata": {},
"source": [
"### Equation 21.3\n",
"\n",
"\n",
"\n",
"Equation (21.3) converts an edge's experienced delay into a local price that includes congestion imposed on existing users.\n",
"\n",
"Add the direct delay to flow times its slope; for straight-line delay, double only the congestion term.\n",
"\n",
"LaTeX source, preserved for inspection:\n",
"\n",
"```latex\n",
"\\ell^{\\mathrm{mc}}_e(q_e) \\;=\\; \\ell_e(q_e)+q_e\\ell'_e(q_e),\n",
"\\qquad\n",
"\\ell_e(q_e)=a_e q_e+b_e\\;\\Longrightarrow\\;\\ell^{\\mathrm{mc}}_e(q_e)=2a_e q_e+b_e.\n",
"\\tag{21.3}\n",
"```"
]
}
],
"metadata": {
"kernelspec": {
"display_name": "Mathematics of AI Agents",
"language": "python",
"name": "maa-lab"
},
"lab_chapter": 21,
"lab_execution": {
"code_cells": 6,
"created_utc": "2026-10-02T05:16:05.318833+00:00",
"elapsed_seconds": 8.971499166917056,
"method": "fresh process; new ipykernel InProcessKernelManager; cells submitted as Jupyter execute requests",
"network_transport_tested": false,
"python": "3.11.15",
"source_sha256": "3852c283b08d8c766153fe9a95ac6c0662a90c2438aaa0c02cfe44bb127a7588"
},
"language_info": {
"name": "python"
}
},
"nbformat": 4,
"nbformat_minor": 5
}