traffic sim article intro and part of discrete sim section

docs/design/traffic_sim.md

@@ -2,34 +2,84 @@
 
 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
 
-what is a traffic simulation?
+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...
 
-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
+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.
 
-cars, buses, bikes only (things on the road in a queue)
+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.)
 
-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.
+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.
 
-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.
+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
 
-### Map model
+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.
 
-lanes, turns, conflicting turns
-lane-changing
+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
 
-idea of agents sensing, planning, acting in env every X seconds
-so what does a car care about? dont hit lead, stop for intersection if needed, obey speed limit and vehicle limit
-	(aka go as fast as possible otherwise -- but maybe would want fuel efficiency or smooth accel)
+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
-some of the math
 
 ### Retrospective
 
@@ -108,3 +158,20 @@ FSM for intersections, cars, peds
 
 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.