Examples¶
Five worked cases. Four ship as study directories in the open-source
repository's studies/ — artifacts, grounding ledger and, where a run exists,
the rendered report (run stores are gitignored, so re-run a study to query its
trajectory). Chicago and Sugarscape also need the companion
SocioVerse-ABM checkout, and
consumer confidence needs ConsumerSim (companion repositories).
Drug procurement is documented as a pattern and is not part of the open-source
release. They are
grouped here into the same three case families the technical report uses,
and inside each family they still cover the different shapes a study can
take: a wrapped legacy simulator, an external forecasting pipeline, a
from-scratch hybrid port, an external MARL training job, and a benchmark shell.
Simulation mechanisms¶
Cases that examine the mechanics of LLM social simulation itself — whether the
instrument reproduces known dynamics before it is pointed at a policy question
or a forecast. Both of them vary the behaviour function f across versions
while P and E are held fixed.
| case | path taken | what it demonstrates | results? |
|---|---|---|---|
| Sugarscape (ABM benchmark) | umbrella shell over a sibling benchmark | does an LLM f reproduce a rule f, with exact parity against the original implementation as the test |
no — structure only; re-run required |
| Hybrid opinion dynamics | B — from scratch | a hybrid population: 8 LLM agents and 12 rule agents in one panel, one environment, one metric set | yes — 5 metric rows, 20 agents |
Policy simulation¶
Cases that ask what follows from an intervention before it is administered: populations grounded in real records, and behaviour that evolves with a changing environment.
| case | path taken | what it demonstrates | results? |
|---|---|---|---|
| Chicago segregation | C — wrapped legacy | census-grounded P, a scheduled intervention plus audience-scoped broadcasts, and a falsified hypothesis faithfully recorded | yes — 4 metric rows, 570 households |
| Drug procurement (MARL) | external MARL pipeline | the run_note mechanism — a study fully materialized here whose training runs elsewhere and imports back |
no — setup-only report, 0 training episodes |
Macro-index forecasting¶
Cases that reconstruct an aggregate economic quantity bottom-up from agent-level decisions, under a point-in-time information guarantee, and read it against the official statistic.
| case | path taken | what it demonstrates | results? |
|---|---|---|---|
| Consumer confidence | C — wrapped legacy | a longitudinal axis made of information accrual (as_of cutoffs), and an LLM core with Bayesian expansion to the rest of the pool |
yes — 3 forecast steps, 12 personas |
The two "no" rows are not gaps to apologize for. Drug procurement is the pattern for a study whose run belongs to a heavy external job, and it carries the honest artifact of that: a setup report that says 0 episodes. Sugarscape is a benchmark shell whose entire content is delegation plus a parity test.
What every case page contains¶
The pages share one shape, so the gallery doubles as a pattern library:
- the research question and what the case is a pattern for;
- P / E / B — the population, the environment layers with their modality / scope / dynamics, and what the behaviour function actually emits;
- what one step means and the horizon — which differs sharply across cases (a relocation round, an information cutoff, a platform turn, a training episode);
- results — the real trajectory table with interpretation, or an explicit statement that the study ships as structure only;
- grounding — what is
sourcedvsproxyvsassumed, concretely; - what you can change — the study's
adjustable_params, each framed as "change this to ask that question", and whether that change lands as a new version or as a counterfactual branch.
The catalog is the real index¶
Once you have the repository, the up-to-date list of available studies is the
catalog itself — every studies/*/study.yaml with its discovery fields
(domain, tags, demonstrates, adjustable_params, reference, and each
reference study's teaches line, which says what pattern it exemplifies).
sv-init routes new questions against those fields automatically: a match
becomes a fork (Path A) rather than a rebuild, and reference: true
studies are templates that are never edited in place.
There are more studies in the catalog than there are pages here — the eleven
abm_* benchmark shells alone, of which
Sugarscape is the worked example. The shipped
from-scratch template (studies/opinion_diffusion/) is also fully functional
and documented in
Build a Study from Scratch.
Start from Anatomy of a Study to read any of these directories, and Quickstart to route your own question into one.