{"id":13475048,"url":"https://github.com/krABMaga/krABMaga","last_synced_at":"2025-03-26T22:31:49.109Z","repository":{"id":41177168,"uuid":"173146655","full_name":"krABMaga/krABMaga","owner":"krABMaga","description":"krABMaga: A modern developing art for reliable and efficient Agent-based Model (ABM) simulation with the Rust language","archived":false,"fork":false,"pushed_at":"2024-07-22T14:19:51.000Z","size":66704,"stargazers_count":183,"open_issues_count":5,"forks_count":12,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-03-21T16:11:10.736Z","etag":null,"topics":["abm","agent-based-modeling","agent-based-simulation","agents","boids-simulation","discrete-event-simulation","multiprocessing","multithreading","parallel","parallel-computing","parallel-programming","physics-simulation","rust","rust-lang","simulation","simulation-engine","wasm"],"latest_commit_sha":null,"homepage":"http://krABMaga.github.io","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/krABMaga.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","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":"2019-02-28T16:26:41.000Z","updated_at":"2025-03-09T11:45:11.000Z","dependencies_parsed_at":"2023-02-14T07:45:59.703Z","dependency_job_id":"bb2a5414-9b6c-4413-93bd-cea059e0f3cf","html_url":"https://github.com/krABMaga/krABMaga","commit_stats":{"total_commits":411,"total_committers":13,"mean_commits":"31.615384615384617","dds":0.781021897810219,"last_synced_commit":"f474e45089e4e795c762601044a6b4a8b3db370b"},"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krABMaga%2FkrABMaga","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krABMaga%2FkrABMaga/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krABMaga%2FkrABMaga/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krABMaga%2FkrABMaga/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/krABMaga","download_url":"https://codeload.github.com/krABMaga/krABMaga/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245747949,"owners_count":20665896,"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":["abm","agent-based-modeling","agent-based-simulation","agents","boids-simulation","discrete-event-simulation","multiprocessing","multithreading","parallel","parallel-computing","parallel-programming","physics-simulation","rust","rust-lang","simulation","simulation-engine","wasm"],"created_at":"2024-07-31T16:01:16.952Z","updated_at":"2025-03-26T22:31:45.326Z","avatar_url":"https://github.com/krABMaga.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/krABMaga/krABMaga.github.io/main/static/images/krabmaga.gif\" alt=\"krabmaga animated logo\" width=\"150\" height=\"130\"\u003e\n  \u003ch1\u003e krABMaga \u003c/h1\u003e\n  \u003ch4\u003e \u003ci\u003eA modern developing art for reliable and efficient ABM simulation with the Rust language\u003c/i\u003e\u003c/h4\u003e\n  \u003cimg alt=\"Crates.io\" src=\"https://img.shields.io/crates/l/krabmaga\"\u003e\n  \u003ca href=\"https://crates.io/crates/krabmaga\"\u003e\u003cimg alt=\"Crates.io\" src=\"https://img.shields.io/crates/v/krabmaga\"\u003e \u003c/a\u003e\n  \u003ca href=\"https://docs.rs/krabmaga/latest/krabmaga\"\u003e\u003cimg alt=\"docs.rs\" src=\"https://img.shields.io/docsrs/krabmaga\"\u003e \u003c/a\u003e\n  \u003cimg alt=\"Rust CI\" src=\"https://github.com/krABMaga/krABMaga/workflows/Rust%20CI/badge.svg\"\u003e\n  \u003ca href=\"https://codecov.io/gh/krABMaga/krABMaga\"\u003e\u003cimg alt=\"codecov\" src=\"https://codecov.io/gh/krABMaga/krABMaga/branch/main/graph/badge.svg?token=GWYP2UBPIZ\"\u003e \u003c/a\u003e\n\u003c/div\u003e\n\n(Notice that the *parallel* and *visualization* components are excluded from _codecov_ as are experimental ore release candidate)\n\n**krABMaga** (Previously named Rust-AB) is a discrete events simulation engine for developing ABM simulation that is written in Rust language. \n\nkrABMaga is designed to be a _ready-to-use_ tool for the ABM community and for this reason the architectural concepts of the well-adopted MASON library were re-engineered to exploit the Rust peculiarities and programming model.\n\n**Developed by** [![ISISLab](https://raw.githubusercontent.com/krABMaga/krABMaga.github.io/main/static/images/isislab.png)](https://www.isislab.it)\n\n# Examples\n\nAll the examples are hosted in a separate repository [here](https://github.com/krABMaga/examples).\n- [Ants Foraging](https://github.com/krABMaga/examples/tree/main/antsforaging)\n- [Flockers](https://github.com/krABMaga/examples/tree/main/flockers)\n- [Forest Fire](https://github.com/krABMaga/examples/tree/main/forestfire)\n- [Schelling Model](https://github.com/krABMaga/examples/tree/main/schelling)\n- [Virus on Network](https://github.com/krABMaga/examples/tree/main/virusnetwork)\n- [Wolf Sheep Grass](https://github.com/krABMaga/examples/tree/main/wolfsheepgrass)\n\n### Usage\n\nAdd this to your `Cargo.toml`:\n\n```toml\n[dependencies]\nkrabmaga = 0.5.*\n```\n\nTo get started using krABMaga, see [the examples](https://github.com/krABMaga/examples).\nThere's also a template to set up the correct project structure and the required files [here](https://github.com/krABMaga/examples/tree/main/template).\n\n**Model Visualization with Bevy Game Engine**\n\nBased on [Bevy game engine](https://bevyengine.org/), it's possible to run simulation with visualization. It's also available a menu to start and stop simulations and a slider to set simulation speed.\nTo run a model with visualization enabled, you have to start the simulation with the command:\n```sh\ncargo run --release --features  visualization\n\n# Alternative command. Requires 'cargo make' installed\ncargo make run --release \n```\n\nIn addition to the classical visualization, you can run your krABMaga simulation inside your browser using [*Web Assembly*](https://webassembly.org). \nThis is possible with the command:\n```sh\n# Requires 'cargo make' installed\ncargo make serve --release \n```\n\n***Visualization FAQs***\n\nIn case you have troubles compiling your visualization, consult this following list of common errors first before making\nan issue:\n- [Wasm related errors due to `bevy_log`](https://github.com/bevyengine/bevy/issues/3099): run this command to force the `tracing-wasm` dependency to 0.2.0:\n```sh\ncargo update -p tracing-wasm --precise 0.2.0\n```\n- \"Data remaining\" issue or \"len is 0 but index is 0\" when running a simulation on the web: Force update your wasm-bindgen-cli local installation to version 0.2.79.\n- Out of memory error when running a simulation on the web, in chrome: run your simulation with the release profile.\n\n### Dependencies\nThe visualization framework requires certain dependencies to run the simulation properly.\n- :desktop_computer: Windows: [VS2019 build tools](https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=BuildTools\u0026rel=16)\n- :apple: MacOS: No dependencies needed.\n- :penguin: Linux: A few dependencies are needed. Check [here](https://github.com/bevyengine/bevy/blob/main/docs/linux_dependencies.md) for a list based on your distribution.\n\n---\n\n### How to write your first model\n\nIf you don't start from our [Template](https://github.com/krABMaga/examples/tree/main/template), add this to your `Cargo.toml`:\n```toml\n[dependencies]\nkrabmaga = 0.5.*\n\n[features]\nvisualization = [\"krabmaga/visualization\"]\nvisualization_wasm = [\"krabmaga/visualization_wasm\"]\n```\n\nWe **strongly** recommend to use [Template](https://github.com/krABMaga/examples/tree/main/template) or any other example as base of a new project, especially if you want to provide any visualization.\n\nEach krABMaga model needs structs that implements our *Traits*, one for *State* and the other for *Agent*. In the *State* struct you have to put *Agent* field(s), because it represents the ecosystem of a simulation. More details for each krABMaga componenet are in the [Architecture](#architecture) section.\n\nThe simplest part is `main.rs`, because is similar for each example.\nYou can define two *main* functions using **cfg** directive, that can remove code based on which features are (not) enabled.  \nWithout visualization, you have only to use *simulate!* to run simulation, passing a state, step number and how may time repeat your simulation. \nWith visualization, you have to set graphical settings (like dimension or background) and call *start* method.\n```rs\n// Main used when only the simulation should run, without any visualization.\n#[cfg(not(any(feature = \"visualization\", feature = \"visualization_wasm\")))]\nfn main() {\n  let dim = (200., 200.);\n  let num_agents = 100;  \n  let state = Flocker::new(dim, num_agents);\n  let step = 10;\n  let reps = 1;\n  let _ = simulate!(state, step, reps);\n}\n\n// Main used when a visualization feature is applied.\n#[cfg(any(feature = \"visualization\", feature = \"visualization_wasm\"))]\nfn main() {\n  let dim = (200., 200.);\n  let num_agents = 100;\n  let state = Flocker::new(dim, num_agents);\n  Visualization::default()\n      .with_window_dimensions(1000., 700.)\n      .with_simulation_dimensions(dim.0 as f32, dim.1 as f32)\n      .with_background_color(Color::rgb(0., 0., 0.))\n      .with_name(\"Flockers\")\n      .start::\u003cVisState, Flocker\u003e(VisState, state);\n}\n\n```\n---\n\n### Available features\n\n| Compilation Feature  | Description |  Experimental | Release Candidate  | Stable  |\n|:----:|:---------:|:---:|:---:|:---:|\n| **No Features** | Possibility to run model using `Simulation Terminal` and setup model-exploration experiments (Parameter Sweeping, Genetic and Random) in sequential/parallel mode. It's enough to create your base simulations. |   |   | 🦀 |\n| **visualization**  | Based on `Bevy engine`, it makes possible to visualize your model elements, to understand better the behavior of your simulation. |   | 🦀 |   |\n| **visualization-wasm** | Based on `Web Assembly`, give you the possibility to execute your visualized simulation inside your own browser. |   | 🦀 |   |\n| **distributed-mpi** | Enable distributed model exploration using MPI. At each iteration, the amount of configurations are balanced among your nodes.  |   |  🦀 |   |\n| **bayesian**  | Use ML Rust libraries to use/create function to use `Bayesian Optimization`.|   | 🦀  |   |\n| **parallel**  | Speed-up a single simulation parallelizing agent scheduling during a step.| 🦀  |   |   |\n\n\n---\n\n### Macros for playing with Simulation Terminal\n\n`Simulation Terminal` is enabled by default using macro `simulate!`, so can be used passing a state, step number and how may time repeat your simulation..\nThat macro has a fourth optional parameter, a boolean. When `false` is passed, `Simulation Terminal` is disabled.\n```rs\n($s:expr, $step:expr, $reps:expr $(, $flag:expr)?) =\u003e {{\n      // Macro code \n}}\n```\n\nYou can create tabs and plot your data using two macro:\n- `addplot!` let you create a new plot that will be displayed in its own tab.\n```rs\naddplot!(String::from(\"Chart Name\"), String::from(\"xxxx\"), String::from(\"yyyyy\"));\n```\n- `plot!` to add a point to a plot. Points can be added during simulation execution, for example inside `after_step` method.\n  You have to pass plot name, series name, x value and y value. Coordinate values need to be `f64`.\n```rs\nplot!(String::from(\"Chart name\"), String::from(\"s1\"), x, y);\n```\n\nOn Terminal home page there is also a *log section*, you can plot log messages when some event needs to be noticed.\nYou can navigate among all logs using ↑↓ arrows.\nTo add a log use the macro `log!`, passing a `LogType` (an enum) and the log message.\n```rs\n log!(LogType::Info, String::from(\"Log Message\"));\n```\n\nAre available four type of Logs:\n```rs\npub enum LogType {\n    Info,\n    Warning,\n    Error,\n    Critical,\n}\n```\n\n\n### [Contributing FAQ](CONTRIBUTING.md)\n \n## Support conference paper\n\nIf you find this code useful in your research, please consider citing:\n\n```\n@ARTICLE{AntelmiASIASIM2019,\n  author={Antelmi, A. and Cordasco, G. and D’Auria, M. and De Vinco, D. and Negro, A. and Spagnuolo, C.},\n  title={On Evaluating Rust as a Programming Language for the Future of Massive Agent-Based Simulations},\n  journal={Communications in Computer and Information Science},\n  note={Conference of 19th Asia Simulation Conference, AsiaSim 2019 ; Conference Date: 30 October 2019 Through 1 November 2019;  Conference Code:233729},\n  year={2019},\n  volume={1094},\n  pages={15-28},\n  doi={10.1007/978-981-15-1078-6_2},\n  issn={18650929},\n  isbn={9789811510779},\n}\n\n```\n🏆 Best Paper Nominee\n\n\n## License\n\nThe MIT License\n\nCopyright (c) ISISLab, Università degli Studi di Salerno 2019.\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN\nTHE SOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FkrABMaga%2FkrABMaga","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FkrABMaga%2FkrABMaga","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FkrABMaga%2FkrABMaga/lists"}