{"id":15683885,"url":"https://github.com/h1ghbre4k3r/swarm-simulation","last_synced_at":"2026-04-28T20:05:57.329Z","repository":{"id":43886801,"uuid":"426788265","full_name":"H1ghBre4k3r/swarm-simulation","owner":"H1ghBre4k3r","description":"Swarm simulation as part of my bacherlor's thesis, written in Go.","archived":false,"fork":false,"pushed_at":"2022-12-31T12:40:11.000Z","size":697,"stargazers_count":1,"open_issues_count":2,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-02-05T12:31:55.883Z","etag":null,"topics":["collision-avoidance","go","golang","orca","python","simulation"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/H1ghBre4k3r.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-11-10T21:51:14.000Z","updated_at":"2022-02-16T17:52:10.000Z","dependencies_parsed_at":"2023-01-31T19:01:46.880Z","dependency_job_id":null,"html_url":"https://github.com/H1ghBre4k3r/swarm-simulation","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/H1ghBre4k3r%2Fswarm-simulation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/H1ghBre4k3r%2Fswarm-simulation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/H1ghBre4k3r%2Fswarm-simulation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/H1ghBre4k3r%2Fswarm-simulation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/H1ghBre4k3r","download_url":"https://codeload.github.com/H1ghBre4k3r/swarm-simulation/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246307932,"owners_count":20756478,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["collision-avoidance","go","golang","orca","python","simulation"],"created_at":"2024-10-03T17:09:03.396Z","updated_at":"2026-04-28T20:05:52.294Z","avatar_url":"https://github.com/H1ghBre4k3r.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Swarm Simulation\n\n[![Test](https://github.com/H1ghBre4k3r/swarm-simulation/actions/workflows/test.yml/badge.svg)](https://github.com/H1ghBre4k3r/swarm-simulation/actions/workflows/test.yml)\n\nSwarm simulation written in Go.\n\n## Roadmap\n\n- [x] sub-process per entity\n- [x] rendering using SDL2\n- [x] participant configuration\n- [x] simulation configuration\n- [x] terminal only version (without SDL2 dependency)\n\neither...\n\n- [ ] switch to Rust (and use bevy)\n\n...or...\n\n- [ ] GLFW + OpenGL/BGFX for rendering\n- [ ] support for 3D\n\n## Requirements\n\n- Go v1.18 installed\n\n  - including correct environment variable setup\n    - **especially:** Add `~/go/bin` to your `$PATH` (may be done by installer on windows)\n\n- **Only for GUI version:** SDL2 (and some optional dependencies installed):\n\n  On **Ubuntu 14.04 and above**, type:\\\n   `apt install libsdl2{,-image,-mixer,-ttf,-gfx}-dev`\n\n  On **Fedora 25 and above**, type:\\\n   `yum install SDL2{,_image,_mixer,_ttf,_gfx}-devel`\n\n  On **Arch Linux**, type:\\\n   `pacman -S sdl2{,_image,_mixer,_ttf,_gfx}`\n\n  On **Gentoo**, type:\\\n   `emerge -av libsdl2 sdl2-{image,mixer,ttf,gfx}`\n\n  On **macOS**, install SDL2 via [Homebrew](http://brew.sh) like so:\\\n   `brew install sdl2{,_image,_mixer,_ttf,_gfx} pkg-config`\n\n  On **Windows**,\n\n  1. Install mingw-w64 from [Mingw-builds](http://mingw-w64.org/doku.php/download/mingw-builds)\n     - Version: latest (at time of writing 6.3.0)\n     - Architecture: x86_64\n     - Threads: win32\n     - Exception: seh\n     - Build revision: 1\n     - Destination Folder: Select a folder that your Windows user owns\n  2. Install SDL2 http://libsdl.org/download-2.0.php\n     - Extract the SDL2 folder from the archive using a tool like [7zip](http://7-zip.org)\n     - Inside the folder, copy the `i686-w64-mingw32` and/or `x86_64-w64-mingw32` depending on the architecture you chose into your mingw-w64 folder e.g. `C:\\Program Files\\mingw-w64\\x86_64-6.3.0-win32-seh-rt_v5-rev1\\mingw64`\n  3. Setup Path environment variable\n     - Put your mingw-w64 binaries location into your system Path environment variable. e.g. `C:\\Program Files\\mingw-w64\\x86_64-6.3.0-win32-seh-rt_v5-rev1\\mingw64\\bin` and `C:\\Program Files\\mingw-w64\\x86_64-6.3.0-win32-seh-rt_v5-rev1\\mingw64\\x86_64-w64-mingw32\\bin`\n  4. Open up a terminal such as `Git Bash` and run `go get -v github.com/veandco/go-sdl2/sdl`.\n  5. (Optional) You can repeat **Step 2** for [SDL_image](https://www.libsdl.org/projects/SDL_image), [SDL_mixer](https://www.libsdl.org/projects/SDL_mixer), [SDL_ttf](https://www.libsdl.org/projects/SDL_ttf)\n     - NOTE: pre-build the libraries for faster compilation by running `go install github.com/veandco/go-sdl2/{sdl,img,mix,ttf}`\n\n  - Or you can install SDL2 via [Msys2](https://msys2.github.io) like so:\n    `pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-SDL2{,_image,_mixer,_ttf,_gfx}`\n\n## Usage\n\nThe simulation provides two executables: One with (`cmd/swarm-simulation`) and one without GUI (`cmd/swarm-simulation-terminal`). The GUI version requires SDL2 to be installed on your system (see above). You can compile each one via make:\n\n```sh\n$ make gui\n```\n\nand\n\n```sh\n$ make terminal\n```\n\nTo run the simulation, you have to provide a configuration file via the `-c` flag.\n\n```sh\n$ ./bin/darwin_amd64/swarm-simulation -c ./examples/sample.json\n```\n\nThe file has to have the following format:\n\n```json\n{\n\t\"settings\": {\n\t\t// optional settings for the simulation\n\t\t\"tickLength\": 10, // [OPTIONAL, default=1] minimum length of a tick in the simulation\n\t\t\"tau\": 120, // [OPTIONAL, default=1] 'look ahead range' for ORCA\n\t\t\"noise\": 0.01 // [OPTIONAL, default=0] noise for the simulation (between 0 and 1 - everything else is not useful)\n\t},\n\t\"participants\": [\n\t\t// array of participants of the simulation\n\t\t{\n\t\t\t\"start\": {\n\t\t\t\t// start coordinates for this participant\n\t\t\t\t\"x\": 0.1, // number between 0 and 1\n\t\t\t\t\"y\": 0.5 // number between 0 and 1\n\t\t\t},\n\t\t\t\"radius\": 0.05, // the radius of this participant (also between 0 and 1)\n\t\t\t\"vmax\": 0.001, // the maximum velocity of this participant (between 0 and 1)\n\t\t\t\"target\": {\n\t\t\t\t// coordinates of the target for this participant\n\t\t\t\t\"x\": 0.9, // between 0 and 1\n\t\t\t\t\"y\": 0.5 // betweedn 0 and 1\n\t\t\t},\n\t\t\t\"script\": \"scripts/test.py\", // path to the script for this participant, RELATIVE to the location of this configuration file\n\t\t\t\"ignoreFinish\": true // [OPTIONAL, default=false] flag for indicating, if the simulation shall ignore the movement (and process) of this participant\n\t\t}\n\t\t//...\n\t]\n}\n```\n\nAdditionally, the simulation supports a number of command line flags:\n\n- `-h`: Show usage of the simulation\n- `-no-gui`: Don't start a GUI\n- `-no-grid`: Hide the grid within the simulation\n- `-c`: Path to the configuration file\n- `-n`: Noise for the simulation (this overwrites the value in the configuration file)\n- `-o`: Path to folder for output file. If this is set, a summary of the simulation will be printed after finish\n- `-consensus`: Flag for turning on shared state between participants\n- `-t`: Value for TAU in the simulation\n\nThe headless executable (only terminal - see **Headless**) supports only a part of the flags.\n\n## Development\n\nSimply open this folder in your favorite editor and start coding.\n\n### Running\n\n```sh\n$ make run\n```\n\n### Running Tests\n\n\u003e There are currently no tests :^)\n\n```sh\n$ make test\n```\n\n### Building (for development)\n\n```sh\n$ make build\n```\n\n### Building (for production)\n\n```sh\n$ make release\n```\n\n### Headless\n\nIf you want to build a headless version (i.e., without GUI support and SDL2), you can compile a specific, console-only version of the simulation.\n\n```sh\n$ make terminal\n```\n\n## Communication\n\nThe simulation starts a new process for each participant and communicates with it via `stdin`, `stdou`, and `stderr`:\n\n- `stdin` is used to pass information from the simulation to the participants\n- `stdout` is used to receive information from the participants\n- `stderr` _can_ be used to log arbitrary information to the output of the simulation\n\n### Procedure\n\nAt startup, the simulation sends some initial information to each participant:\n\n```json\n{\n\t\"position\": {\n\t\t// coordinates of the position of this participant\n\t\t\"x\": 0.2,\n\t\t\"y\": 0.5\n\t},\n\t\"radius\": 0.015, // radius of this participant\n\t, // radius of the stddev around this participant\n\t\"vmax\": 0.0005, // maximum velocity of this participant\n\t\"target\": {\n\t\t// coordinates of the target of this participant\n\t\t\"x\": 0.8,\n\t\t\"y\": 0.5\n\t},\n\t// tau for ORCA\n\t\"tau\": 100\n}\n```\n\nDuring each tick of the simulation, it sends its current position and information about all other participants to each participant:\n\n```json\n{\n\t\"position\": {\n\t\t// coordinates of the position of this participant\n\t\t// ...\n\t},\n\t\"participants\": [\n\t\t{\n\t\t\t\"position\": {\n\t\t\t\t// position of the participant\n\t\t\t},\n\t\t\t\"velocity\": {\n\t\t\t\t// current velocity of this participant\n\t\t\t\t\"x\": 0.0012,\n\t\t\t\t\"y\": 0.000004\n\t\t\t},\n\t\t\t\"distance\": 0.412, // relative distance to this participant\n\t\t\t\"radius\": 0.015, // radius of this participant\n\t\t\t\"stddev\": 0.0123 // stddev for this participant\n\t\t}\n\t]\n}\n```\n\nAfter this, it expects an answer of each participant:\n\n```json\n{\n\t\"action\": \"move\",\n\t\"payload\": {\n\t\t// new velocity of this participant\n\t\t\"x\": 0.00123,\n\t\t\"y\": 0.002\n\t}\n}\n```\n\n## Presets\n\n\u003e ⚠️ Attention: Every preset expects a compiled version of our ORCA implementation in **RELEASE** mode!\n\nFor testing purposes, there are currently some presets in `/examples`. `/examples/circle` contains setup with all participants placed in a circle, while `/examples/random/v...` contains different random examples (i.e., random start and end points for all participants). `v{0-7}` all contain examples with a tau value of 100, whereas `v{8,9,10}` contain examples with `tau`-values of 250, 500 and 1000 respectively. The names of the examples are pretty straight forward:\n\n```\n{n°-of-participants}-participants-{random|circle}.json\n```\n\n## ORCA\n\nWe added a sample implementation of ORCA in Rust to run for each participants. The source code can be found in [examples/scripts/rust-orca](examples/scripts/rust-orca).\n\n### Requirements\n\nYou need to have Rust installed. The usual way is via [rustup](https://rustup.rs). Furthermore, `make` is more or less required.\n\n### Compilation\n\nTo compile the rust implementation of ORCA, you can either run\n\n```sh\n$ make agent\n```\n\nfrom the root of this project or you can run\n\n```sh\n$ make release\n```\n\nfrom [examples/scripts/rust-orca](examples/scripts/rust-orca).\n\n#### Without make\n\nIf you do not have `make` installed on your system, you can compile ORCA without make. Simply run\n\n```sh\n$ cargo build --release\n```\n\nfrom [examples/scripts/rust-orca](examples/scripts/rust-orca).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fh1ghbre4k3r%2Fswarm-simulation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fh1ghbre4k3r%2Fswarm-simulation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fh1ghbre4k3r%2Fswarm-simulation/lists"}