{"id":23105771,"url":"https://github.com/maxwellmatthis/cellular-automaton-traffic-simulation","last_synced_at":"2026-04-26T12:32:23.326Z","repository":{"id":245926756,"uuid":"779193016","full_name":"maxwellmatthis/cellular-automaton-traffic-simulation","owner":"maxwellmatthis","description":"A cellular automaton for traffic simulation based on the Nagel-Schreckenberg model. (See: https://en.wikipedia.org/wiki/Nagel–Schreckenberg_model, https://de.wikipedia.org/wiki/Nagel-Schreckenberg-Modell) Extended to support multiple lanes, construction sites, traffic lights, different vehicle types and more.","archived":false,"fork":false,"pushed_at":"2024-06-23T20:02:04.000Z","size":9124,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-03T22:29:28.648Z","etag":null,"topics":["cellular-automaton","freeway-simulation","matplotlib","nagel-schreckenberg-model","python","rust","simulation","simulator","traffic-simulation"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/maxwellmatthis.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-03-29T08:52:59.000Z","updated_at":"2024-06-24T18:56:18.000Z","dependencies_parsed_at":"2024-06-24T21:44:22.288Z","dependency_job_id":"4879270d-8202-4b58-bf38-6620eafbae3e","html_url":"https://github.com/maxwellmatthis/cellular-automaton-traffic-simulation","commit_stats":null,"previous_names":["maxwellmatthis/cellular-automaton-traffic-simulation"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/maxwellmatthis/cellular-automaton-traffic-simulation","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxwellmatthis%2Fcellular-automaton-traffic-simulation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxwellmatthis%2Fcellular-automaton-traffic-simulation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxwellmatthis%2Fcellular-automaton-traffic-simulation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxwellmatthis%2Fcellular-automaton-traffic-simulation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maxwellmatthis","download_url":"https://codeload.github.com/maxwellmatthis/cellular-automaton-traffic-simulation/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxwellmatthis%2Fcellular-automaton-traffic-simulation/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32297893,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T09:34:17.070Z","status":"ssl_error","status_checked_at":"2026-04-26T09:34:00.993Z","response_time":129,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cellular-automaton","freeway-simulation","matplotlib","nagel-schreckenberg-model","python","rust","simulation","simulator","traffic-simulation"],"created_at":"2024-12-17T00:54:50.234Z","updated_at":"2026-04-26T12:32:23.309Z","avatar_url":"https://github.com/maxwellmatthis.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cellular Automaton Traffic Simulation\n\nA cellular automaton for traffic simulation based on the Nagel-Schreckenberg model. (See: [Nagel-Schreckenberg model (Wikipedia/DE)](https://en.wikipedia.org/wiki/Nagel–Schreckenberg_model), [Nagel-Schreckenberg-Modell (Wikipedia/DE)](https://de.wikipedia.org/wiki/Nagel-Schreckenberg-Modell)) Extended to support multiple lanes, construction sites, traffic lights, different vehicle types and more.\n\n## Table of Contents\n\n- [Installation \u0026 Setup](#installation--setup)\n  - [Simulator](#simulator)\n  - [Benchmark Tools](#benchmark-tools)\n- [Usage](#usage)\n  - [Simulator](#simulator-1)\n  - [Benchmarking](#benchmarking)\n- [Model](#model)\n  - [Basics](#basics)\n  - [Update Rules](#update-rules)\n  - [Multi Lane Extension](#multi-lane-extension)\n  - [Cell Blocking Extension](#cell-blocking-extension)\n  - [Traffic Light Extension](#traffic-light-extension)\n  - [Vehicle Types Extension](#vehicle-types-extension)\n\n## Installation \u0026 Setup\n\n### Simulator\n\nThe simulator is written in [Rust](https://rust-lang.org/learn/get-started) and can be compiled and run using Rust's package manager `cargo`.\n\n```sh\n# Run the simulator and show the usage\ncargo run -- -h\n\n# Build the simulator binary to use without cargo\ncargo build --release\n# Run the release binary and show the usage\ntarget/release/cellular-automaton-traffic-simulation -h\n```\n\n### Benchmark Tools\n\nThe benchmarking tools are written in Python, mainly to take advantage of matplotlib.\nYou'll need to have Python3 (`\u003e=3.11`), as well as matplotlib and numpy installed on your system.\n\n```sh\n# Quickly install requirements\npip install -r benchmarks/requirements.txt\n```\n\n__Note:__ The benchmarking tools can run the simulator through cargo or directly.\nThe default is running the release binary directly, howevery, you'll need to compile it first using\n`cargo build --release`. Directly running the release binary is recommended as its faster and\ndoesn't print every time like cargo does. If you'd like to run the simulator through cargo, go to\nbenchmarks/adapter.py:6 and change the comment.\n\n## Usage\n\n### Simulator\n\nEvery constant used in the simulation has a reasonable default value but can also be set\nwhen running the simulator from the command line (see usage below) or from a yaml definition using\nthe `-y` argument. __Note:__ when using a yaml definition, all arguments must be manually set. (See\n[example.yaml](example.yaml))\n\nThe simulator can print the details of each round to stdout using the `-v` (verbose) switch or in an\nanimated way using the `-a` (animate) switch and generate an image using the `-i` (image) switch.\n__Tip:__ In image mode cars are represented as pixels ranging from red (stopped) to green (max_speed).\nEach row represents a round. The image is read from the bottom up.\n\nThe simulator always ends the simulation by printing relevant settings and useful\nmetrics about the simulation as JSON.\n\n```sh\nUsage: cellular-automaton-traffic-simulation [OPTIONS]\n\nOptions:\n  -r, --rounds \u003cROUNDS\u003e\n          The number of rounds to run the simulation for [default: 4096]\n      --lanes \u003cLANES\u003e\n          The number of lanes that make up the road [default: 1]\n  -l, --length \u003cLENGTH\u003e\n          The number of cells in each lane that make up the road [default: 1000]\n      --vehicles \u003cVEHICLES\u003e\n          Allows specifying different vehicle types and with which density they occur. Format: `(max_speed, acceleration_time, traffic_density); ...` Corresponding model with units: `(x * 7.5m/s, (1 / x) * 7.5m/s^2, x * 100% of road on lane-by-lane basis)` [default: \"(5, 1, 0.2)\"]\n  -d, --dilly-dally-probability \u003cDILLY_DALLY_PROBABILITY\u003e\n          The probability with which cars dilly-dally. (slow down randomly) [default: 0.2]\n  -s, --stay-in-lane-probability \u003cSTAY_IN_LANE_PROBABILITY\u003e\n          The probability with which cars stay in their lane, even when it would be best to switch lanes [default: 0.2]\n      --monitor \u003cMONITOR\u003e\n          The locations, specified as `(lane_index, cell_index); ...`, of the cells that are to be monitored. (Note: all cells are passively monitored but only those specified will be added to the simulation result [default: (0,0)]\n      --traffic-lights \u003cTRAFFIC_LIGHTS\u003e\n          The locations, specified as `(lane_index, cell_index); ...`, of the cells that represent traffic lights. Traffic lights will be green for 100 rounds and then be red for 100 rounds [default: ]\n      --block \u003cBLOCK\u003e\n          The locations, specified as `(lane_index, cell_index_start - cell_index_end_exclusive); ...` or `(lane_index, cell_index); ...`, of the cells that may not be driven over. This simulates blockages as they occur when construction work is being done [default: ]\n  -v, --verbose\n          Whether to print the states of the road to stdout\n  -a, --animate\n          Whether to print the states of the road to stdout using color and overwriting for greater viewing pleasure. This option trumps the `verbose` option\n  -i, --image\n          Whether to create a visualization image of the simulation\n  -o, --out-path \u003cOUT_PATH\u003e\n          Where to save the visualization image [default: traffic.png]\n  -y, --yaml \u003cYAML\u003e\n          Optionally provide simulator settings as a yaml file to avoid using the command line for detailed simulations. Note: All Options except `yaml` must be used!\n  -h, --help\n          Print help\n  -V, --version\n          Print version\n```\n\nHere's an example of what a simulation image looks like:\n\n![traffic](https://github.com/maxwellmatthis/cellular-automaton-traffic-simulation/assets/58150536/c449c61a-d267-4255-8412-61ecf133157d)\n\n### Benchmarking\n\nThe [python adapter](./benchmarks/adapter.py) provides interfaces and convenience functions that\nrun the simulator and return the metrics in a pythonic way. The\n[plot helper](./benchmarks/plot_helper.py) provides simple utility functions for plotting metrics\nusing Matplotlib.\n\nHere's an example of a script using both to benchmark what happens to the metrics as the maximum speed increases:\n\n```python\n# from: benchmarks/max_speed.py\n\nimport numpy as np\nfrom adapter import run_average, SimulationOptions\nfrom plot_helper import plot\n\nVARIABLE = \"Dilly Dally Probability\"\nSIMULATIONS_EACH = 100\n\n# x-axis\ndilly_dally_probabilities = np.arange(0, 1, 0.05)\n\n# y-axes\naverage_speeds = []\nfirst_cell_flows = []\naccelerations = []\ndeaccelerations = []\n\nfor dilly_dally_probability in dilly_dally_probabilities:\n    metrics = run_average(SimulationOptions(vehicles=[(5, 1, 0.3)], dilly_dally_probability=dilly_dally_probability), SIMULATIONS_EACH)\n    average_speeds.append(metrics.average_speed_kilometers_per_hour)\n    first_cell_flows.append(metrics.monitor_cells_flow_cars_per_minute[0])\n    accelerations.append(metrics.average_accelerations_n_per_car_per_round)\n    deaccelerations.append(metrics.average_accelerations_n_per_car_per_round)\n\nplot(VARIABLE, \"Average Speed (km/h)\", dilly_dally_probabilities, average_speeds)\nplot(VARIABLE, \"First Cell Flow (car/min)\", dilly_dally_probabilities, first_cell_flows)\nplot(VARIABLE, \"Accelerations (n/car/round)\", dilly_dally_probabilities, accelerations)\nplot(VARIABLE, \"Deaccelerations (n/car/round)\", dilly_dally_probabilities, deaccelerations)\n```\n\nThe results from all benchmarks are stored in [benchmarks/results/](./benchmarks/results/).\n\n## Model\n\n### Basics\n\n- The road is a closed loop, which means that the number of cars is constant and driving forever is possible.\n- The road is a made up of cells, where each cell may contain exactly one or no car.\n- Cars are `7.5m` long. =\u003e Each cell is `7.5m` long.\n- Each round is 1s long.\n- Cars can move a natural number of cells (equal to their speed) each round. =\u003e Cars move at `n * 7.5m/s` (`n * 27km/h`).\n- The default maximum speed is set to `5cells/round`, although it can be set to any number. (Note: It does not make sense to set the maximum speed any higher than `10cells/round` (`10 * 27km/h =\u003e 270km/h`) since there are almost no cars that can reach and almost no drivers willing to pay for the gasoline needed to sustain such speeds.)\n\n### Update Rules\n\nThe following steps are executed in order for each car each round.\n\n1. Increase speed by `7.5m/s`.\n2. Decrease speed to `cells_to_next_car * 7.5m/s`.\n3. Decrease speed by `7.5m/s` with a chance of `dilly_dally_probability`.\n\n### Multi-Lane Extension\n\nThe multilane extension adds support for multiple lanes and lane switching to the model.\n\n- Cars can only switch to adjacent lanes.\n- Switching is only allowed if there is no one (1) directly in front of or (2) next to the car. Exception: Switching is with a car directly in front is allowed for cars moving at `1cell/round`.\n- Passing directly on the right is not allowed.\n- Cars that switch lanes do not dilly-dally. (This avoids cars going sideways by switching lanes at `v=0cells/round` and break checking people behind them.)\n- Cars may stay in their lane `stay_in_lane_probability * 100`% of the time. This models how drivers forget or choose not to switch lanes when they have the chance and should.\n\n- Cars always switch to the right lane if there is enough space (speed + 1 cells) for them to drive without slowing down.\n- Cars always switch to the lane with the most space if none of the lanes have enough space to drive without slowing down.\n\nSince all cars theoretically move at the same time but it is very hard to make the computer\nsimulate all cars at the same time, the cars are simulated lane-by-lane, starting on the left.\nThis functions without hard-to-resolve conflicts, because passing on the right is not allowed.\n\n__Examples:__\n\nThe following examples show the options and behaviour of the red car (`v=5cells/round`) for one round. The columns represent lanes 1-4.\n\n(Legend: 🚙 : other car, ❌ : not allowed, ✅ : allowed, 🎯 : where the car will move to)\n\n| 1 | 2 | 3 | 4 |\n| --- | --- | --- | --- |\n|❌ |🚙 |❌ |🚙 |\n|❌ |🚙 |❌ |🚙 |\n|❌ |🚙 |❌ |❌ |\n|❌ |🚙 |❌ |❌ |\n|❌ |🚙 |❌ |❌ |\n|❌ |🚗 |❌ |❌ |\n\n| 1 | 2 | 3 | 4 |\n| --- | --- | --- | --- |\n|🎯 |🚙 |🚙 |🚙 |\n|✅ |🚙 |🚙 |🚙 |\n|✅ |❌ |❌ |❌ |\n|✅ |🚙 |✅ |❌ |\n|✅ |✅ |✅ |❌ |\n|❌ |🚗 |❌ |❌ |\n\n| 1 | 2 | 3 | 4 |\n| --- | --- | --- | --- |\n|❌ |🚙 |🚙 |🚙 |\n|❌ |🚙 |🎯 |❌ |\n|❌ |✅ |✅ |❌ |\n|🚙 |🚗 |✅ |❌ |\n|❌ |❌ |🚙 |❌ |\n\n| 1 | 2 | 3 | 4 |\n| --- | --- | --- | --- |\n|❌ |❌ |🚙 |❌ |\n|❌ |❌ |❌ |❌ |\n|✅ |✅ |🎯 |❌ |\n|✅ |✅ |✅ |❌ |\n|✅ |✅ |✅ |❌ |\n|✅ |✅ |✅ |❌ |\n|✅ |✅ |✅ |❌ |\n|❌ |🚗 |❌ |❌ |\n\n| 1 | 2 | 3 | 4 |\n| --- | --- | --- | --- |\n|❌ |❌ |🚙 |❌ |\n|✅ |🎯 |✅ |❌ |\n|✅ |✅ |✅ |❌ |\n|✅ |✅ |✅ |❌ |\n|✅ |✅ |✅ |❌ |\n|✅ |✅ |✅ |❌ |\n|❌ |🚗 |❌ |❌ |\n\n### Cell Blocking Extension\n\nThe lane blocking extension adds the option to block individual cells or ranges of cells. The feature can be used to simulate a construction site or accident.\n\n### Traffic Light Extension\n\nThe traffic light extension add traffic lights to the model. All traffic lights turn red and green at the same time. Switching occurs every 100 model seconds (100 simulation rounds).\n\n### Vehicle Types Extension\n\nThe vehicle types extension adds the option to specify no only the density of traffic but the maximum speed, acceleration and traffic density of each different vehicle type. (See: `--vehicles` flag in [usage](#usage)).\n\nSome realistic values to play around with:\n\n| Vehicle Type | Maximum Speed (cells/round) | Maximum Speed (km/h) | Acceleration (1/x * cells/round^2) | Acceleration (m/s^2) | Traffic Density |\n| ------------ | --------------------------- | -------------------- | ---------------------------- | -------------------- | --------------- |\n| Sports Car 🏎️     | 9 | 243 | 1 | 7.5  | 0.01 |\n| Car 🚗            | 5 | 135 | 2 | 3.75 | 0.19 |\n| Truck 🚛 / Bus 🚌 | 4 | 108 | 6 | 1.25 | 0.05 |\n\nThe conversion factor from cells/round to km/h is `7.5*3.6`.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxwellmatthis%2Fcellular-automaton-traffic-simulation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaxwellmatthis%2Fcellular-automaton-traffic-simulation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxwellmatthis%2Fcellular-automaton-traffic-simulation/lists"}