What happens to the world when you change the rules?

How this project actually started

Before any of the simulator was written, somebody sat down and wrote out exactly what they wanted to be able to ask of it. The four original questions are still visible in the codebase today, because every feature ended up being a tool built to answer one of them.

The original mission, in one sentence

Build a research grade simulator that can honestly answer what the world looks like under different border policies, where people end up moving when cities run out of room, how resources and trade routes shape the economy over time, and which infrastructure decisions actually pay off under a real budget constraint.

That sentence is the reason every other piece of the project exists. The migration model is there because of borders and crowding. The three sector economy is there because of resources and trade. The autonomous infrastructure planner with its budget cap is there because of the infrastructure question. When you look at a feature in the simulator and wonder why it is there, the answer is almost always “because somebody needed to be able to answer one of the four original questions.”

The four research questions, in plain English

The original framing broke that mission into four specific questions. They are worth stating individually because each one is deliberately structured to admit a tradeoff rather than to have a single right answer:

• Migration dynamics. How strongly do wages, housing costs, amenities, and connectivity actually drive where people move? And at what point do crowding and rent in the destination start to self-limit how many more people will keep coming?
• Infrastructure policy. Which kinds of infrastructure (rail, pipeline, shipping, road) produce the highest long run GDP gain per dollar spent? Under a real budget, when should you build now versus wait?
• Resource economy. How do extraction, depletion, logistics, and market pricing interact in practice? Does better connectivity make resource prices more competitive, or does it just shift who captures the profit?
• Stability and equity. Can a policy raise GDP while also controlling overcrowding, urban concentration, and economic volatility? Which policy mixes hold up best when something unexpected hits (a resource crunch, a broken trade route, a wave of migration)?

Notice that each question has two halves that pull against each other. Growth versus crowding. Investment now versus investment later. Prices versus rents. Aggregate output versus distribution. The project assumed from day one that good policy is a negotiation, not a maximum.

The honesty pledge

The third commitment the project made to itself was a hard line against fantasy modeling. The statement, more or less verbatim:

100 percent real-world accuracy is not achievable in complex social and economic systems. The goal is high fidelity calibrated modeling with quantified uncertainty, not perfect prediction.

That sentence is doing a lot of work. It is the difference between an honest simulator and a crystal ball pretending to be one. A lot of policy modeling fails because the modeler quietly forgets that their assumptions are assumptions. The project committed up front to treating the simulator as a calibrated estimator rather than a forecast. You can see that commitment in the user interface today: every run displays a confidence level (the trust stoplight in the top bar) and the right panel has a “factor coverage disclosure” section that lists every economic factor the model knows about along with how complete the underlying data actually is. The simulator tells you when it is guessing.

The eight non-negotiable design principles

Eight principles were written down as non-negotiable. They are not features. They are constraints on what counts as a valid version of the project. Each one shows up later as something concrete you can actually see:

• Deterministic replay. Every run can be reproduced bit for bit by anyone with the same seed. (This is why every result in this report uses seed 42.)
• Real budget constraints on infrastructure. The autonomous planner cannot build forever. It runs out of money and stops.
• Explicit affordability and capacity limits. Housing costs respond to density. People cannot ignore the cost of where they choose to live.
• Real resource stocks that get depleted. A mineral rich city cannot pump forever. Reserves draw down over time.
• Real supply and demand pricing. Three economic sectors (resources, goods, IP) each have their own price index that affects both GDP and the migration choice.
• Full causality logging. Every timestep produces a written record of what happened and why, in plain text. Any decision the simulator made can be reviewed after the fact.
• Scenario testing under shocks. A library of 24 contrasting scenarios is built in, and the optimizer evaluates candidates under randomized shocks. Policy that breaks under stress gets penalized.
• Explainability. The optimizer does not just output a winning parameter set. It outputs the learning curve, the spread of candidates, and the score breakdown. You can argue with its answer.

Architecture, briefly

Two services run locally. A Python backend on port 8010 does all the math. A web frontend on port 5173 draws the map and the dashboards. They talk over WebSocket so the simulation can stream timestep updates to the browser in real time, up to about thirty steps per second.

How a single timestep actually works, in plain English

This is the part the README does not explain. Every timestep, the simulator does the same five things, in order, over every city in parallel. Once you understand them, the findings later in this report start to feel inevitable rather than mysterious.

Step 1: Every city gets an attractiveness score

Imagine you are deciding where to move. You probably do not consciously calculate a number, but you do weigh things: how much money you can make there, how nice it is to live there, how expensive it is to put a roof over your head, and how many of your industry's jobs are nearby. The simulator does the same thing, just explicitly. Every city, every step, gets a single number called its “destination utility,” which is roughly: wages, plus productivity, plus amenity, plus an agglomeration bonus for being big, minus housing cost, plus a bonus for being near other things you might need (resources, factories, ports, universities, talent).

The most important word in that sentence is “bonus for being big.” The simulator gives a city extra attractiveness just because a lot of people already live there. That single mechanic, called agglomeration, is responsible for almost every interesting dynamic in the model. It is the reason Tokyo keeps growing. It is the reason Pittsburgh shrank for fifty years. It is also a feedback loop: bigger cities attract more people, who make them bigger, who attract more people. Without a counterweight (like housing cost), the model would collapse the entire world into one mega city.

Step 2: Residents pick where to go

Once every city has a score, each city's residents decide whether to move and, if so, where. The simulator does this with a mechanism called softmax, which is just a fancy way of saying “the probability you move to city X is the score of city X divided by the sum of scores for every place you might go, with a temperature knob that controls how rational the choice is.”

Two things happen during this step that matter for everything downstream. The first is that the score of a destination from your point of view depends not just on how attractive it is, but on how hard it is to get there. That is where friction comes in. Distance friction, the connectivity multiplier, and most importantly, border friction (an extra penalty if the destination is in a different group from where you currently live) all apply here. Crank up border friction and people stop crossing groups, even if the other side is much more attractive. Crank it down and the borders effectively dissolve.

The second is that the total number of movers each step is just migration_propensity × population. The “Migration Surge” scenario in this report cranks that propensity up three times. But (and this is the key insight that explains finding number one in the next section) more movers does not mean different choices. The softmax is still the softmax. The first ten percent of your population making the optimal choice and the next twenty percent making the optimal choice end up at roughly the same destinations. That is why tripling migration does not triple GDP growth.

Step 3: Cities update themselves based on who came and went

After the migration round, every city has a new population. From there, a chain of feedback effects fires. Cities that grew get a small bump to productivity (the agglomeration loop strikes again, this time on the supply side). Housing costs respond to the new density, rising in growing cities and falling in shrinking ones, at a rate set by the housing elasticity parameter. Wages follow a formula that goes up with productivity and down with housing cost.

Housing elasticity is the single most important parameter for explaining the surprise finding later in this report. Low elasticity means housing supply cannot easily expand, so when a city grows, its rent skyrockets. That makes the city much less attractive to the next wave of movers, even though its productivity is still high. The math forces growth to spread out instead of piling up. High elasticity means housing absorbs growth easily, so productive cities just keep growing without paying a price. The default in the simulator is 0.08. The Housing Constrained scenario uses 0.04, which is enough to flip the model from “mega cities win” to “distributed networks win.”

Step 4: Three sectors of the economy produce output

Every city makes three kinds of things every step. Resources (proportional to its mineral, energy, and agriculture deposits, with the deposits getting drawn down over time). Manufactured goods (a function of industrial capacity, manufacturing specialization, and proximity to raw materials). IP and technology (knowledge stock times tech specialization times human capital, with an R&D efficiency multiplier on top).

Total city GDP combines wage income with monetized sector output, weighted by the three price indices that the scenario sets. That is why scenarios like Resource Crunch can shift GDP composition without shifting GDP magnitude much: they raise the per unit value of resource output but do not change the physical production amount.

Step 5: Every fifteen steps, the AI planner builds something

By default this happens every fifteenth timestep. The autonomous infrastructure planner scans for the single highest scoring pair of currently unconnected cities and builds a new link between them. We cover how it decides in the next section.

What we ran, and how

The ML optimizer's verdict

The optimizer is the most interesting feature in the project that you cannot see in the UI. It is a cross entropy parameter search that asks: across all the possible combinations of these twelve economy levers, which combination does best when shocks hit? Here is what cross entropy actually means, why this project uses it, and what it found.

What cross entropy optimization is, in plain English

Imagine you are trying to find the best spot in a darkened field for a picnic. You cannot see the whole field, but you can drop a friend at any point and they will tell you how nice it is there. Cross entropy works like this: you scatter a dozen friends around the field. They each report back. You note which spots got the highest scores (the top thirty percent are your “elites”). You scatter a new dozen friends around the average location of the elites, with a spread roughly equal to how spread out the elites were. They report back. You keep doing this. Over time, your cloud of friends drifts toward whatever spot in the field is best.

That is exactly what the optimizer does, except instead of friends it samples parameter sets, and instead of asking how nice a spot is, it runs a full simulation under randomized shocks and computes a score. It is gradient free (it never needs the derivative of the objective), it is parallel (each sample is independent), and it works fine on noisy, expensive, discontinuous objectives. Which is exactly what an agent based simulation under shocks is.

What “score” means here

The score the optimizer is maximizing is a weighted combination of five things. Higher final GDP is good. Higher GDP growth is good. Lower volatility is good (a stable economy beats a roller coaster). Lower concentration is good (a world with growth spread across many cities scores better than a world dominated by a few). Lower overpopulation is good (cities that exceed their carrying capacity get penalized). And finally there is a small extra penalty for spending more than ninety two percent of the available infrastructure budget, which discourages the optimizer from blowing the bank just to chase a few more percentage points of GDP.

The learning curve

The recommended blend

After four iterations of twelve trials each, here is the parameter set the optimizer landed on:

What all of this actually means for the real world

Reading the findings as a research artifact is one thing. Reading them as a guide to thinking about real policy and real urbanization over the next thirty years is something else. This section is the longest in the report because, honestly, the findings raise more interesting questions than the findings themselves answer. Below are the big takeaways, the ones we think actually transfer outside the simulator.

Housing is the lever the discourse underestimates

Most popular conversations about urbanization and growth treat housing policy as a downstream problem: cities get successful, housing costs rise, we then debate what to do about it. The simulator suggests something stranger and more provocative. Housing elasticity might be the single most important upstream lever in the entire urban system. Not borders. Not infrastructure budget. Not migration propensity. Just how easily housing supply responds to demand.

The reason this matters is that in the real world, housing elasticity is largely a policy choice. It is set by zoning regulations, building codes, height limits, parking requirements, environmental review processes, and historic preservation rules. Different countries and different cities have wildly different effective elasticities. Tokyo has loose zoning and high elasticity. San Francisco has the opposite. The simulator suggests that the answer to “why is one of these cities thriving and the other one is exporting its tech industry?” is not really about taxes or talent. It is about whether housing supply can keep up with demand.

Now flip that. The simulator also suggests that restricting housing supply in the most productive cities, like San Francisco does, might actually produce higher aggregate growth, because it forces growth out to Austin, Boise, Salt Lake City, Miami, Denver, and so on. That is exactly the pattern the United States has experienced over the past fifteen years. The simulator predicts it as a logical consequence of the agglomeration plus housing dynamic, without being told about any of those cities specifically.

The honest implication is awkward: the cities with the worst housing policies may be inadvertently doing the rest of the country a favor, by acting as innovation seedlings whose graduates have to relocate to afford a life. That is not a great policy to be running on purpose, because it imposes enormous local costs on the people who live in the constrained cities. But it does explain why aggregate growth has held up better than the housing data alone would suggest.

Open borders is a distributive lever, not a growth lever

Almost every popular argument for or against open borders treats them as a question of total economic output. Pro side: more people, more productive matching, higher GDP. Con side: pressure on services, wage suppression, lower per capita GDP. The simulator suggests both sides are talking about the wrong thing.

In the simulator, Open Borders did not produce particularly high GDP growth. It produced the lowest growth of any scenario in the study. What it produced instead was a flatter distribution: less concentration in megahubs, more activity in secondary cities, and (as we saw in the deep dive) huge individual swings as small cities consolidate into larger ones. That is not a growth story. That is a distribution story.

The real world implication is that the open borders debate should probably be reframed. The question is not “will this make us richer?” The question is “where will the prosperity end up, and which places will hollow out?” The simulator says the answer to that question is mostly determined by geography (which small cities are next to which big cities) and by housing policy (whether the receiving big cities can absorb growth). Border policy mostly just opens or closes the valve. It does not determine the destination of the flow.

The agglomeration loop is the most powerful force in the model

Every interesting dynamic in the simulator, when you trace it back, depends on the agglomeration feedback loop: bigger cities are more attractive, attract more people, become more productive, become even more attractive. This is not a controversial claim in academic economic geography. Edward Glaeser has spent thirty years writing about it. But the simulator makes the force visible in a way that prose arguments cannot. You can literally watch the rich cities pull harder over the course of a run.

The implication is that any policy that ignores or fights agglomeration is going to underperform. “Spread investment evenly across regions” sounds fair but is, in the model, a recipe for slower aggregate growth. The optimizer figured this out on its own. Its winning blend includes three times default agglomeration strength. It wanted big cities to pull harder, not less hard. Combined with inelastic housing in those big cities to redirect the spillover, this is the closest thing to a real model output that says “the policy mix many countries are running today is wrong in a specific identifiable way.”

Infrastructure planning, in a smart world, is about optionality more than about building

The single weirdest result in the optimizer output is that the winning policy spent only 3.1 percent of its infrastructure budget. The natural reaction is “then why have such a big budget?” The model's implicit answer is “because optionality is valuable when shocks hit.”

In real terms, this maps onto a fairly well known principle in corporate finance and emergency management: you do not want to spend down your reserves in normal times, because the value of the reserves comes from being able to deploy them quickly when something breaks. Public infrastructure has the same property. A country with a large, mostly unused capacity to build emergency rail or power links is more resilient than a country that has already built every link it could afford. The simulator's optimizer reinvented this principle from first principles, which is mildly remarkable given that nobody told it about financial reserves or option value.

The implication for actual infrastructure policy is that big visible projects are not necessarily better than maintained capacity. Spending the budget all at once might score well on next year's PR but it is, in the model's terms, throwing away your shock absorber.

Aggregates can lie. Always look at the city level.

Finding number seven (top winners and top losers per scenario) was the most uncomfortable one to write up, because it shows that every scenario, including the “stable” ones, contained at least one city losing more than ninety percent of its population. The world's total GDP went up in all of them. The total population was nearly the same. But underneath, individual cities were completely transformed.

The real world version of this is the question of who pays the cost of any policy. A policy that raises aggregate GDP while wiping out half a dozen mid sized cities is not the same as a policy that raises aggregate GDP while preserving them, even if the GDP numbers are identical. The simulator's contribution to this debate is that you can now see which cities the policy is wiping out. Bahawalpur, Athlone, Bhubaneswar, Jaffna. They are named. They are on the map. They were not just data points. Whether the policy is worth the cost is a value judgment, but the cost itself is no longer abstract.

What the model is missing, and why that matters

Honesty time. The simulator has real strengths in demographic and migration dynamics, agglomeration feedback, and the budget logic for infrastructure. It has real weaknesses too. Here is what is notably absent and what each absence means for how you should read the findings.

• Climate is not modeled. Cities do not get more or less attractive based on heat, sea level rise, drought, or natural disasters. In the real world, this is going to be one of the dominant migration forces over the next thirty years. The model's predictions about who wins and who loses should be read as “absent climate change.”
• Remote work is not modeled. The migration utility function assumes you need to physically be in a place to work there. The growing share of fully remote knowledge work decouples wage from location in a way the model does not capture.
• Political instability is not modeled. Cities cannot become unsafe, lose their institutions, or have their governments collapse. The model assumes a globally stable institutional environment, which is generous.
• Demographic transition is not modeled. The model does not include birth rates, death rates, or aging. In a real run over centuries, fertility collapse in East Asia and Europe would dwarf any of the migration effects we observed.
• AI productivity shocks are not modeled. The IP and tech sectors grow at a smooth multiplier. If artificial intelligence dramatically raises the productivity of knowledge workers over the next decade, the agglomeration winners in this simulator (cities with high knowledge stock) would get a much bigger boost than the model currently shows.
• Returns are not redistributed. There are no taxes, no transfer payments, no social safety nets. The model treats wages as flowing entirely to the people in the city that earned them. Adding redistribution would change which cities are attractive and how shocks propagate.

Each of these omissions is fixable in principle. None of them are trivial. The right way to think about the current findings is that they describe the dynamics of a world that has resolved every obvious uncertainty (climate is stable, work requires presence, governments function) and is just being asked the narrow question of how migration, infrastructure, and prices interact. That is a smaller question than “what will the world look like in 2050,” but it is a sharper question, and the model's answers to it are correspondingly more trustworthy.

Caveats, honestly

Every claim in this report should come with the following asterisks. The point of a research artifact is to be honest about what it can and cannot say.

• Single seed. Every result here is from seed 42. The deterministic property is great for replayability, but a serious study would re-run with twenty seeds and report means and confidence intervals. The 1.15x GDP spread across scenarios may be larger than seed noise, but we have not formally proven it.
• 200 steps may be too short. Some scenarios' GDP curves had only just started to fan apart by timestep 200 (see the Housing Constrained breakaway in chart 1). A 500 step horizon would make the late stage divergence much clearer.
• Identical migration totals appeared for Baseline, Network Fragmentation, and Resource Crunch, suggesting either that the migration system reaches steady state extremely fast, or that those scenarios do not actually differ in any parameter the migration calculation uses. Worth checking before drawing strong conclusions from any one of the three.
• The optimizer was budget constrained. Four iterations of twelve trials. A real research run would use eight iterations of forty plus trials, plus multiple seeds, and would probably take eight hours instead of twenty minutes. The 3.41x result is suggestive, not conclusive.
• The autonomous planner appears to ignore scenario regime (finding number four). We hypothesized this is because the scoring function reads only static city attributes. That is a hypothesis based on code reading, not on a controlled experiment.
• The sector composition stability in finding number six is at least partially an artifact of the price indices controlling monetization rather than physical output. The model is currently labor and demography heavy, supply response light.
• The predictions section is speculation. It explicitly extends model findings to real world expectations. Models are wrong in proportion to how much they extrapolate. Treat each prediction as a falsifiable claim, not a forecast.
• This is a model. FlowWorld is a policy laboratory, not a forecast. The point is to probe which directions outcomes move when you twist the rules, not to predict actual city populations in 2050. Treat the magnitudes as ordinal, not cardinal.