feat: add tariff war ABM with realistic calibration and visualization

[echo-xiao]

Adds a new Mesa 3 example: Tariff War — an ABM simulating the 2018–2025
US–China trade war with three agent types (State, Organization, Resident)
across three countries (USA, China, Neutral Asia).

Key emergent phenomena

• Higgs Ratchet: step-wise government expansion that never fully contracts
• Trade Diversion: Neutral Asia gains from USA–China conflict
• CEE-SAC recession spiral: firm pessimism becomes self-fulfilling
• Endogenous lobbying: tariff rents lock in high tariffs post-crisis

Visualization
7 real-time Solara charts covering tariffs, GDP, firm bankruptcy,
consumer welfare, and expectation gaps.

Parameters calibrated to real data (WTO baseline 3%, peak 35%,
government size 20% GDP).

[echo-xiao]

closes #279

[EwoutH]

Thanks for the PR, looks like a cool model.

Could you:

• Checkout the test failure
• Add a screenshot or gif of the visualisation to the PR description
• Request a peer-review (and maybe do one or two yourself)

[abhinavk0220]

Peer Review — Tariff War ABM

Reviewed agent.py, model.py, app.py, requirements.txt, and readme.md in full.

---

Overall

The most economically sophisticated example I've reviewed in this repo. The CEE-SAC recession spiral mechanics (β expectations, lobbying ratchet, firm bankruptcy) are well thought out and go meaningfully beyond toy models. The visualisation is rich and the calibration against real 2018–2025 tariff data is a genuine contribution. A few structural issues need fixing.

---

Critical: __init__.py added to repo root

diff --git a/__init__.py b/__init__.py

An empty __init__.py was added to the root of mesa-examples. This should not be there — it would make the entire repo importable as a Python package and interfere with CI and other tooling. This file should be removed from the PR.

---

Typo in directory name: tarrif_war → tariff_war

The example lives at examples/tarrif_war/ (double-r, single-f). The correct spelling is tariff. This affects the import from tarrif_war.model import TariffWarModel throughout app.py and the package __init__.py. Worth fixing before merge so the directory name is consistent with the model name.

---

matplotlib.use("Agg") called globally in app.py

matplotlib.use("Agg")

Calling matplotlib.use() at import time changes the backend globally for the entire Python process. If multiple examples run in the same Solara server or if this file is imported before other matplotlib-using code, it can silently break rendering elsewhere. Solara already handles the Agg backend for server-side rendering this line is unnecessary and should be removed.

---

app.py is 457 lines complexity concern

The visualization file alone is longer than most complete examples in the repo. Six custom Solara components with dual-axis charts, fill-between shading, and formatted tick labels are impressive but push this beyond what a newcomer can follow. Consider whether the same economic story can be told with 2–3 charts instead of 6, or move the chart components to a separate charts.py file to keep app.py readable.

---

Model-level correctness: β update rule

The CEE (Consistent Expectations Equilibrium) β update is core to the model's recession spiral mechanic. Worth confirming in the README or code comments that the update rule matches the theoretical specification specifically whether β is updated before or after production decisions each step, as order-of-operations affects whether you get a self-fulfilling spiral or dampened oscillation.

---

Sector calibration is documented clearly ✅

The inline comments explaining tariff_sens, lobby_eff, and prod_mult for each sector are excellent:

# Tech: high tariff sensitivity (supply chains), high lobbying (FAANG-style)
# Agriculture: low tariff sensitivity domestically, very low lobbying efficiency

This level of documentation is exactly what makes an ABM reviewable. ✅

---

readme.md → README.md

The file is named readme.md (lowercase). Mesa-examples convention is README.md (uppercase). Minor but consistent with every other example in the repo.

---

Summary

The economic model is ambitious and technically sound. Three things to fix before merge: (1) remove the root-level __init__.py, (2) rename tarrif_war → tariff_war throughout, and (3) remove the global matplotlib.use("Agg") call. The visualization complexity is advisory the model works but consider trimming for accessibility. Strong contribution overall.

[savirpatil]

Hi @echo-xiao,

Does it belong?
This contribution has no meaningful overlap with existing examples. The three-agent-type structure (State, Organization, Resident) and the Higgs Ratchet, trade diversion, CEE-SAC recession spiral, and endogenous lobbying , are all well-motivated and go well beyond what any current example covers. The model is ambitious yet reasonably scoped given the complexity of what it is trying to demonstrate, and the calibration to real 2018–2025 trade war data gives it credibility as well.

Is it correct and current?
The model uses current Mesa APIs correctly throughout, agents_by_type, shuffle_do, and DataCollector are all used appropriately and no deprecated patterns were found. However, there is a root-level init.py committed to the repository that should not be there, as it would make the entire repo importable as a Python package and could interfere with CI tooling.

Is it clean?
The agent code is well-structured and the inline comments explaining sector calibration (tariff sensitivity, lobbying efficiency, production multipliers) are great for clarity. This level of documentation makes the model reviewable and easy to follow. The charts are impressive but it would be worth considering whether 2–3 well-chosen charts could tell the same story more accessibly, or whether the chart components could be moved to a separate charts.py to keep app.py manageable. The README file is completely empty, which needs to be addressed before this can merge as well.

Summary
The economic depth here is impressive, the CEE-SAC expectation mechanics, and the lobbying ratchet show a level of care and research that really stands out. The calibration to real trade war data is a thoughtful touch that makes the model feel grounded rather than abstract. Once the root init.py is removed and the README is filled in, this will be one of the stronger examples in the repo. Great work!