Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.
(Notice that the parallel and visualization components are excluded from codecov as are experimental ore release candidate)
krABMaga (Previously named Rust-AB) is a discrete events simulation engine for developing ABM simulation that is written in Rust language.
krABMaga 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.
Examples
All the examples are hosted in a separate repository here.
Usage
Add this to your Cargo.toml
:
[]
= 0.4.*
To get started using krABMaga, see the examples. There's also a template to set up the correct project structure and the required files here.
Model Visualization with Bevy Game Engine
Based on Bevy game engine, 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. To run a model with visualization enabled, you have to start the simulation with the command:
# Alternative command. Requires 'cargo make' installed
In addition to the classical visualization, you can run your krABMaga simulation inside your browser using Web Assembly. This is possible with the command:
# Requires 'cargo make' installed
Visualization FAQs
In case you have troubles compiling your visualization, consult this following list of common errors first before making an issue:
- Wasm related errors due to
bevy_log
: run this command to force thetracing-wasm
dependency to 0.2.0:
- "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.
- Out of memory error when running a simulation on the web, in chrome: run your simulation with the release profile.
Dependencies
The visualization framework requires certain dependencies to run the simulation properly.
- :desktop_computer: Windows: VS2019 build tools
- :apple: MacOS: No dependencies needed.
- :penguin: Linux: A few dependencies are needed. Check here for a list based on your distribution.
How to write your first model
If you don't start from our Template, add this to your Cargo.toml
:
[]
= 0.4.*
[]
= ["krabmaga/visualization"]
= ["krabmaga/visualization_wasm"]
We strongly recommend to use Template or any other example as base of a new project, especially if you want to provide any visualization.
Each 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 section.
The simplest part is main.rs
, because is similar for each example.
You can define two main functions using cfg directive, that can remove code based on which features are (not) enabled.
Without visualization, you have only to use simulate! to run simulation, passing a state, step number and how may time repeat your simulation.
With visualization, you have to set graphical settings (like dimension or background) and call start method.
// Main used when only the simulation should run, without any visualization.
// Main used when a visualization feature is applied.
Available features
Compilation Feature | Description | Experimental | Release Candidate | Stable |
---|---|---|---|---|
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. |
🦀 | ||
visualization | Based on Bevy engine , it makes possible to visualize your model elements, to understand better the behavior of your simulation. |
🦀 | ||
visualization-wasm | Based on Web Assembly , give you the possibility to execute your visualized simulation inside your own browser. |
🦀 | ||
distributed-mpi | Enable distributed model exploration using MPI. At each iteration, the amount of configurations are balanced among your nodes. | 🦀 | ||
bayesian | Use ML Rust libraries to use/create function to use Bayesian Optimization . |
🦀 | ||
parallel | Speed-up a single simulation parallelizing agent scheduling during a step. | 🦀 |
Macros for playing with Simulation Terminal
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..
That macro has a fourth optional parameter, a boolean. When false
is passed, Simulation Terminal
is disabled.
=>
You can create tabs and plot your data using two macro:
addplot!
let you create a new plot that will be displayed in its own tab.
addplot!;
plot!
to add a point to a plot. Points can be added during simulation execution, for example insideafter_step
method. You have to pass plot name, series name, x value and y value. Coordinate values need to bef64
.
plot!;
On Terminal home page there is also a log section, you can plot log messages when some event needs to be noticed.
You can navigate among all logs using ↑↓ arrows.
To add a log use the macro log!
, passing a LogType
(an enum) and the log message.
log!;
Are available four type of Logs:
Contributing FAQ
Support conference paper
If you find this code useful in your research, please consider citing:
@ARTICLE{AntelmiASIASIM2019,
author={Antelmi, A. and Cordasco, G. and D’Auria, M. and De Vinco, D. and Negro, A. and Spagnuolo, C.},
title={On Evaluating Rust as a Programming Language for the Future of Massive Agent-Based Simulations},
journal={Communications in Computer and Information Science},
note={Conference of 19th Asia Simulation Conference, AsiaSim 2019 ; Conference Date: 30 October 2019 Through 1 November 2019; Conference Code:233729},
year={2019},
volume={1094},
pages={15-28},
doi={10.1007/978-981-15-1078-6_2},
issn={18650929},
isbn={9789811510779},
}
🏆 Best Paper Nominee
License
The MIT License
Copyright (c) ISISLab, Università degli Studi di Salerno 2019.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.