abstreet/docs/design/traffic_sim.md

# Traffic Simulation from scratch

The goal of this article is to explain the traffic simulation model that A/B
Street uses. There's a large amount of traffic simulation research in academia,
but the papers are often paywalled or require background knowledge. This article
is meant to be accessible to anybody with a basic background in software
engineering and high-school kinematics.

Disclaimers... my background is in software engineering, not civil engineering.
The design space that A/B Street explores is absolutely massive; there are so
many alternate ways of doing everything from modeling the map, to representing
agents and their movement and conflict... Please send any critique/feedback/etc

## Introduction

My other goal with this article is to explain what I work on to my friends and
family. It's very easy to say "I'm not a computer programmer or a math expert,
there's no way I could understand this," and despite how frustrating this is,
I've previously accepted this. But today I want more. Driving, moving around a
city, and getting stuck in traffic are common experiences, and I think they can
help...

Imagine there's an incredibly rainy afternoon and we've got lots of paper. I
draw a to-scale map of your hometown, showing detail like how many lanes are on
every road, noting the speed limits, and marking all the stop signs and traffic
lights. Then I place a bunch of color-coded Hot Wheels and, I don't know, bits
of paper around the map. Each of the cars will start somewhere and wants to go
to their colored square. To make it easy, let's pretend they all start driving
at the same time. My challenge for you is to show me exactly where the cars are
30 seconds after starting to drive, then 5 minutes in, and then an hour later.
Maybe I'm interested in figuring out where the traffic jams happen. Or maybe we
throw in some buses and little toy soldiers, and I want to know how long people
after waiting for their bus because it's delayed in traffic. Or maybe I'm just
sadistic and want to watch you squirm.

How would you figure out what happens to all of the cars after some amount of
time? You'll probably start by figuring out the route each of them will take to
their destination -- probably some approximation of the shortest path (by pure
distance) or fastest (a longer route on a highway might be faster than a short
one through residential roads). You'll inch the cars forward on their lane, not
moving them (too much) faster than the speed limit. When two cars are near each
other, you'll make one follow the other at a reasonable distance, or maybe
change lanes and try to overtake them if there's room. You'll make the cars stop
at stop signs and for red lights. When you accidentally push too many cars
through a green light turned feisty yellow then somber red, you'll make the
opposing lane's cars angrily honk at the jerk blocking the box by making odd
little squeaks out of the corner of your mouth. (And I will laugh at you, of
course.)

Of course, you won't be able to tell me with perfect accuracy where all the cars
are 45.2 seconds into our little game. There are potholes that'll slow some
drivers down a bit that aren't marked on the map, and some cars that take a
little longer to accelerate or notice the light's green. That's fine -- complete
realism isn't so important, as long as things look reasonable.

For this to be interesting for me to watch, there have to be a realistic number
of cars -- 10 little Hot Wheels squeaking around all of Seattle won't tell me
anything interesting about how the city flows. By now, you might be thinking
this is going to be slightly tedious. Your fingers are going to get a bit
cramped from budging 500,000 cars around a bit at a time. So I'll cut you a deal
-- if you'll describe rules for how to move each of the cars forward a bit in
sufficient detail, then I'll make a computer do all of the tedious bits.

And that's all programming a traffic simulator is. You don't need to know what
arrays and entity-component systems and trans-finite agent-based cellular RAM
drives are (I made up that last one maybe). Let's get started!

## The map

Let's start with deciding exactly what our map of Seattle looks like. One of the
trickiest and most satisfying parts about computer programming is figuring out
what parts of the world to represent. Too much irrelevant detail makes it harder
to... Yes, a tree partly blocking a tight corner might make people slow down,
but it's probably a bit too much detail to worry about. Your choice of
abstraction should, it turns out, depend on what you're actually trying to do.
In this case, I'll cheat momentarily and describe how we should model the map.
Later, I'll explain what I want A/B Street to be and how that led to including
some things while omitting others.

Let's also clear up terminology. Diagram goes here...

Let's start with **roads**. A road goes between exactly two **intersections**.
You might think of 2nd Ave as a long road through all of downtown, but we'll
chop it up as 2nd Ave between Bell St and Lenora, 2nd Ave from Lenora to Seneca,
etc. Most intersections have two or more roads connected to them, but of course,
we might also have dead-ends and cul-de-sacs. Each road has individual **lanes**
going in some direction. Most roads have lanes going both directions, but a few
one-ways only have lanes going in one direction. Cars will travel along a lane
in single file and, to keep things simple, never change lanes in the middle of a
road. When the car reaches the end of a lane, it can perform one of several
**turns** through the intersection. After finishing the turn, the car will be at
the beginning of a lane in another road. Some turns conflict, meaning it's not
safe for two cars to do them simultaneously, while others don't conflict.

If cars can't ever change lanes, couldn't they get stuck? Maybe a car starts on
the rightmost lane and is only allowed to turn right, but actually needs to be
in a middle lane to go straight through the intersection. Don't worry -- you can
assume that there's a path between any two lanes. Instead of changing lanes in
the middle of a road, cars in our game will change lanes when they turn. EXAMPLE
PIC. I'll describe later why this is a good idea.

For now, let's assume cars start on some lane. When their front bumper hits
their colored square on their destination, they just immediately vanish. The
colored square could be at the end of their destination lane, or somewhere in
the middle.

(could mention borders or not, maybe footnote)

Don't worry about parking, pedestrians, bicycles, or buses. These things are all
important to A/B Street, but we'll ad them in later.

## Disrete-time model

Whoa, fancy name! Ignore it for a moment.

How do people drive? Very roughly, they look at things around them, take an
action (press the gas some amount, press the brake some amount, turn the wheel a
bit), and then do the same thing a half-second (or so) later. That's the essence
of agent-based modeling -- sense the environment, plan what to do next, do it,
then repeat some time later. We'll call the amount of time between each choice
the **timestep** and say it's about 0.1 seconds. Let's try simulating traffic
roughly this way -- every single car will take an action every 0.1 seconds that
advances them through the world. Breaking up time in these regular 0.1s
intervals is how we get the term "discrete-time model."

What kind of controls do we want to give each driver? If we let them turn the
steering wheel a few degrees left or right and apply some pressure to the gas
pedal, then we have to figure out how this affects the position of the car and
worry about how to make sure cars stay in their lane. That's way too
complicated, and not interesting for our purposes. So let's say that for every
car, we keep track of a few details:

- current lane or turn
- **dist_along**: distance of the front bumper along that lane or turn (starting
  at 0 for the beginning of the lane)
- current speed
- the remaining path to the goal (lane1, turn2, lane3, turn5, ..., lane10)
- vehicle length
- maximum acceleration (some cars can start more quickly)
- maximum deceleration (some cars can slam on their brakes and stop faster)

The first four will change every 0.1s, while the last three don't ever change.

So what controls can a driver do? Accelerate (or decelerate) some amount. That's
all. When the dist_along is bigger than the current lane/turn's length, we make
the new current lane be the first thing from the remaining path, discard the
path, and reset the dist_along to 0.

(this section got weird -- talk about controls first, brief bit of kinematics,
then state. follow along curve of lanes automatically.)

### Constraints

What kind of things influence a driver's decision each timestep, and what do
they need to be able to sense about their environment to use the rule? I can
think of three:

1. Don't exceed the speed limit of the current road

- so the driver needs to be able to look at the speed limit of the current road

2. Don't hit the car in front of me

- need to see the current dist_along, speed, length, accel and deaccel of the
  next car in the queue
- actually, humans can't eyeball another car and know how quickly it can speed
  up or slow down. maybe they just assume some reasonable safe estimate.

3. Maybe stop at the end of the lane

- for stop signs or red/yellow lights

And of course, whatever acceleration the driver picks gets clamped by their
physical limits. Other than these constraints, let's assume every driver will
want to go as fast as possible and isn't trying to drive smoothly or hyper-mile.
Not realistic, but makes our lives easier. So if each of these three constraints
gives an acceleration, we have to pick the smallest one to be safe. Rule 1 says
hit the gas and go 5m/s^2, but rule 2 says we can safely go 2m/s^2 and not hit
the next car and rule 3 actually says wait, we need to hit the brakes and go
-1m/s^2 right now. Have to go with rule 3.

### Some math

Skip this section freely. The takeaways are:

- there's a way to figure out the acceleration to obey the 3 constraints
- the math gets tricky because (1) the car will only be doing that acceleration
  for 0.1s and then getting to act again, and (2) floating point math is tricky

### Lookahead

lookahead (worst case analyses), cover multiple lane->turn->lanes maybe

### Retrospective

1. It's fundamentally slow; there's lots of busy work. Cars in freeflow with
   nothing blocking them yet, or cars

2. Figuring out acceleration in order to do something for the next tick is
   complicated.

- floating pt bugs, apply accel but make sure speed doesnt go negative or dist
  doesnt exceed end of lane if they were supposed to stop... wind up storing an
  intent of what they wanted to do, make corrections based on that. hacky.

3. The realism of having cars accel and deaccel doesnt really add much, and
   since the approach has silly assumptions anyway (slam on brakes and
   accelerator as much as possible), unrealistic

## Discrete-event model take 1: time-space intervals

things that were not finished / still hard:

- cover a short lane
- real quadratic distance over time was breaking stuff
- impossible accel/deaccel happened
- faster lead car made adjusting follower very hard

## Discrete-event model take 2

Let's try again, but even simpler and more incremental this time.

### v0: one car

Forget about speed, acceleration, and even multiple cars momentarily. What is a
car's basic state machine? They enter a lane, travel across it, maybe stop and
wait for the intersection, execute a turn through the intersection, and then
enter the next lane. We could assign reasonable times for each of these --
crossing a lane takes lane_distance / min(road's speed limit, car's max speed)
at minimum. Intersections could become responsible for telling cars when to move
-- stop signs would keep a FIFO queue of waiting cars and wake up each car as
the last one completes their turn, while traffic signals could wake up all
relevant cars when the cycle changes.

### v1: queueing

Alright, but what about multiple cars? In one lane, they form a queue -- no
over-taking or lane-changing. The FSM doesn't get much more complicated: a car
enters a lane, spends at least the freeflow_time to cross it, and then either
winds up front of the queue or behind somebody else. If they're in the front,
similar logic from before applies -- except they first need to make sure the
target lane they want to turn to has room. Maybe cars are already backed up all
the way there. If so, they could just wait until that target lane has at least
one car leave. When the car is queued behind another, they don't have anything
interesting to do until they become the queue's lead vehicle.

Another way to understand this system is to picture every lane as having two
parts -- the empty portion where cars cross in freeflow and a queue at the end.
Cars have to pay a minimum amount of time to cross the lane, and then they wind
up in the queue. The time to go from the end of the queue to the front requires
crunching through the queue front-to-back, figuring out when each successive
lead vehicle can start their turn and get out of the way.

### Drawing

An intermission -- we haven't pinned down exactly where cars are at some point
in time, so how do we draw them? The idea for this DES model began without
worrying about this too much -- when the map is zoomed out, individual cars are
hard to see anyway; the player probably just wants to know roughly where lots of
cars are moving and stuck waiting. This can be calculated easily at any time --
just count the number of cars in each queue and see if they're in the Crossing
or Queued state.

But when zoomed in, we do want to draw individual cars at exact positions
through time! Luckily, this isn't hard at all. The only change from the timestep
model is that we have to process a queue at a time; we can't randomly query an
individual car. This is fine from a performance perspective -- we almost always
want to draw all cars on lanes visible on-screen anyway.

So how does it work? First consider the queue's lead vehicle. If they're Queued,
then the front of the car must be at the end of the lane waiting to turn. If
they're Crossing, then we can just linearly interpolate their front position
from (0, lane_length) using the time-interval of their crossing and the current
time. Then we consider the queue's second car. In an ideal world where they're
the lead car, we do the same calculation based on Queued or Crossing state. But
the second car is limited by the first. So as we process the queue, we track the
bound -- a car's front position + the car's length + a fixed following distance
of 1m. The second car might be farther back, or directly following the first and
blocked by them. We just take min(ideal distance, bound), and repeat for the
third car.

### v2: preventing discontinuities

There's an obvious problem happening when the lead vehicle of a queue leaves the
queue -- everybody queued behind them suddenly jump forward. Discontinuities
like this are of course unrealistic, but more importantly for A/B St's purpose,
looks confusing to watch. So let's try a simple fix: when a lead car exits a
queue, update its follower to know to cross the remaining distance properly. The
follower might be Queued right behind the lead, or they might still be Crossing.
If they're still Crossing, no worries -- they'll continue to smoothly Cross to
the end of the lane. But if they're Queued, then reset the follower to Crossing,
but instead make them cover a smaller distance -- (lane_length - lead car's
length - FOLLOWING_DISTANCE, lane_length), using the usual min(lane speed limit,
car's max speed). Since they're Queued, we know that's exactly where the
follower must be.

This smoothness comes at a price -- instead of a car taking one event to cross a
lane, it now might go through a bunch of Crossing states -- the lane's max
capacity for vehicles, at worst. That's not so bad, and it's worth it though.

### v3: starting and stopping early

The basic traffic model is now in-place. As we add more elements of A/B Street
in, we need one last tweak to the driving model. Cars don't always enter a lane
at the beginning or exit at the very end. Cars sometimes start in the middle of
a lane by exiting an adjacent parking spot. They sometimes end in the middle of
a lane, by parking somewhere. And buses will idle in the middle of a lane,
waiting at a bus stop for some amount of time.

When we update a car, so far we've never needed to calculate exact distances of
everybody on the queue at that time. That's just for drawing. But now, we'll
actually need those distances in two cases: when a car is finished parking or
when a car is somewhere along their last lane. (Note that buses idling at a stop
satisfy this second case -- when they leave the stop, they start following a new
path to the next stop.) When the lead car vanishes from the driving lane (by
shifting into the adjacent parking spot, for example), we simply update the
follower to the Crossing state, starting at the exact position they are at that
time (because we calculated it). If they were Queued behind the vanishing car,
we know their exact position without having to calculate all of them. But
Crossing cars still paying the minimum time to cross the lane might jump forward
when the car in front vanishes. To prevent this, we refresh the Crossing state
to explicitly start from where they became unblocked.

### Remaining work

There's one more discontinuity remaining. Since cars have length, they can
occupy more than one lane at a time. When the lead car leaves a queue, the
follower is updated to cross the remaining distance to the end. But if the
leader is moving slowly through their turn, then the follower will actually hit
the back end of the lead vehicle! We need a way to mark that the back of a
vehicle is still in the queue. Maybe just tracking the back of cars would make
more sense? But intersections need to know when a car has started a turn, and
cars spawning on the next lane might care when the front (but not back) of a car
is on the new lane. So maybe we just need to explicitly stick a car in multiple
queues at a time and know when to update the follower on the old lane. Except
knowing when the lead car has advanced some minimum distance into the new lane
seemingly requires calculating exact distances frequently!

This jump bug also happens when a lead car vanishes at a border node. They
vanish when their front hits the border, even though they should really only
vanish when their back makes it through.

The other big thing to fix is blind retries. In almost all cases, we can
calculate exactly when to update a car. Except for three:

1. Car initially spawning, but maybe not room to start. Describe the rules for
   that anyway.

2. Car on the last lane, but haven't reached end_distance yet. Tried a more
   accurate prediction thing, but it caused more events than a blind retry of
   5s.

3. Cars waiting to turn, but not starting because target lane is full. Could
   register a dependency and get waked up when that queue's size falls below its
   max capacity. Could use this also for gridlock detection. Oops, but can't
   start because of no room_at_end. That's different than target lane being
   full, and it's hard to predict when there'll be room to inch forward at the
   end.

#### Notes on fixing the jump bug

- can track a laggy leader per queue. there's 0 or 1 of these, impossible to be more.
- a car can be a laggy leader in several queues, like long bus on short lanes. last_steps is kinda equivalent to this. 


is it possible for get_car_positions to think something should still be blocked but the rest of the state machine to not?
	- dont change somebody to WaitingToAdvance until theres no laggy leader.


TODO impl:
- get_car_positions needs to recurse
- trim_last_steps needs to do something different




the eager impl:
- anytime we update a Car with last_steps, try to go erase those. need full distances. when we successfully erase, update followers that are Queued.
	- - follower only starts moving once the laggy lead is totally out. wrong. they were Queued, so immediately promote them to WaitingToAdvance. smoothly draw in the meantime by recursing
- optimistic check in the middle of Crossing, but use a different event for this to be clear. the retry should only be expensive in gridlocky cases.
	- BLIND_RETRY after... similar to end_dist checking.
	- note other routines dont even do checks that could hit numerical precision, we just assume events are scheduled for correct time.
- maybe v1: dont recurse in get_car_positions, just block off entire laggy leader length until they're totally out.
- v2: do have to recurse. :(


the lazy impl:
- when we become WaitingToAdvance on a queue of length > vehicle len, clean up last_steps if needed
- when we vanish, clean up all last_steps
- when a follower gets to ithin laggy leader length of the queue end, need to resolve earlier
	- resolving early needs to get exact distances. expensive, but common case is theyre clear. if somebody gets stuck fully leaving a queue, then this will spam, but thats also gridlocky and we want to avoid that anyway



other ideas:
- can we cheat and ensure that we only clip into laggy leaders briefly?
	- if laggy leaders never get stuck at end of their next queue...
- alt: store front and back of each car in queues separately
	- compute crossing state and stuff for those individually? double the work?


## A/B Street's full simulation architecture

start from step(), the master event queue, how each event is dispatched, each
agent's states

FSM for intersections, cars, peds (need to represent stuff like updating a
follower, or being updated by a leader)

## Appendix

pedestrian, transit, bikes, buses, etc limits... overtaking (especially cars and
bikes on roads)

Traffic modeling is a complex space, but for the purposes of this article, a
traffic simulation is a computer program that takes a map with roads and
intersections and a list of trips (depart from here at this time, go there using
a car or bus or by foot) and shows where all of the moving agents wind up over
time. I'm sure you can imagine a great many uses for them both professional and
nefarious, but our mission today is to understand one particular traffic
simulation works. A/B Street is a computer game I've been building to experiment
with the traffic in Seattle. My goal for A/B Street is to make it easy for
anybody to ask what-if questions.

a/b st is a game, needs performance (city scale -- X road segments, X
intersections, X agents total), determinism, not complete realism agent-based,
rule out others complex maps

cars, buses, bikes only (things on the road in a queue)

abst is a game, what's the essence of scarcity? contention at intersections,
lanes restricting usage, parking. NOT modeling pedestrians queueing on a
sidewalk, bc in practice, doesnt happen (except maybe around pike place or at
festivals). not modeling bike racks at all -- in practice, can lock up within a
block of destination without effort.

if modeling big highways, this wouldnt be great. but we're focused on intra-city
seattle -- modeling phenomena like jam waves not so important. if the player
does parking->bus lane and the bus moves faster, but more cars circle around
looking for parking, then the model is sufficiently interesting to answer the
questions i want. dont need to model stopping distance for that.