krABMaga

使用Rust语言构建可靠且高效的ABM模拟的现代开发艺术

（请注意，并行和可视化组件不包括在codecov中，以及实验性或候选版本也是如此）

krABMaga（之前命名为Rust-AB）是一个用Rust语言编写的离散事件模拟引擎，用于开发ABM模拟。

krABMaga旨在成为ABM社区的现成工具，因此重新设计了广泛采用的MASON库的架构概念，以利用Rust的特性编程模型。

开发人员

示例

所有示例都托管在单独的仓库这里。

• 蚂蚁觅食
• 鸟群
• 森林火灾
• 谢林模型
• 网络上的病毒
• 狼羊草

使用方法

将此添加到您的 Cargo.toml

[dependencies]
krabmaga = 0.4.*

要开始使用krABMaga，请参阅示例。还有一个模板，用于设置正确的项目结构和所需文件这里。

使用Bevy游戏引擎进行模型可视化

基于Bevy游戏引擎，可以进行带可视化的模拟运行。还有一个菜单可以开始和停止模拟，以及一个滑块可以设置模拟速度。要启用可视化运行模型，必须使用以下命令启动模拟：

cargo run --release --features  visualization

# Alternative command. Requires 'cargo make' installed
cargo make run --release 

除了传统的可视化外，您还可以使用 Web Assembly 在浏览器中运行您的 krABMaga 模拟。这可以通过以下命令实现：

# Requires 'cargo make' installed
cargo make serve --release 

可视化常见问题解答

如果您在编译可视化时遇到问题，请先查看以下常见错误列表，然后再提交问题。

• 由于 bevy_log 导致的 Wasm 相关错误： 运行此命令以强制将 tracing-wasm 依赖项设置为 0.2.0。

cargo update -p tracing-wasm --precise 0.2.0

• 在网络上运行模拟时出现“数据剩余”问题或“len 为 0 但索引为 0”问题：强制更新您的 wasm-bindgen-cli 本地安装到版本 0.2.79。
• 在 Chrome 中运行网络模拟时出现内存不足错误：以发布配置运行您的模拟。

依赖项

可视化框架需要某些依赖项来正确运行模拟。

• 🖥️ Windows: VS2019 编译工具
• 🍎 MacOS: 无需依赖项。
• 🐧 Linux: 需要一些依赖项。根据您的发行版，请参阅此处的列表。

如何编写您的第一个模型

如果您不从我们的 模板 开始，请将以下内容添加到您的 Cargo.toml 中：

[dependencies]
krabmaga = 0.4.*

[features]
visualization = ["krabmaga/visualization"]
visualization_wasm = ["krabmaga/visualization_wasm"]

我们 强烈 建议使用 模板 或其他示例作为新项目的基础，特别是如果您想提供任何可视化。

每个 krABMaga 模型都需要实现我们的 Traits 的结构体，一个是 State，另一个是 Agent。在 State 结构体中，您必须放置 Agent 字段（因为它们代表模拟的生态系统）。每个 krABMaga 组件的更多详细信息请参阅架构部分。

最简单的是 main.rs，因为它对每个示例都是相似的。您可以使用 cfg 指令定义两个 main 函数，根据是否启用了哪些功能来删除代码。
没有可视化时，您只需使用 simulate! 来运行模拟，传递状态、步数和重复模拟的次数。具有可视化时，您必须设置图形设置（如维度或背景）并调用 start 方法。

// Main used when only the simulation should run, without any visualization.
#[cfg(not(any(feature = "visualization", feature = "visualization_wasm")))]
fn main() {
  let dim = (200., 200.);
  let num_agents = 100;  
  let state = Flocker::new(dim, num_agents);
  let step = 10;
  let reps = 1;
  let _ = simulate!(state, step, reps);
}

// Main used when a visualization feature is applied.
#[cfg(any(feature = "visualization", feature = "visualization_wasm"))]
fn main() {
  let dim = (200., 200.);
  let num_agents = 100;
  let state = Flocker::new(dim, num_agents);
  Visualization::default()
      .with_window_dimensions(1000., 700.)
      .with_simulation_dimensions(dim.0 as f32, dim.1 as f32)
      .with_background_color(Color::rgb(0., 0., 0.))
      .with_name("Flockers")
      .start::<VisState, Flocker>(VisState, state);
}

可用功能

用于与 Simulation Terminal 交互的宏

模拟终端默认通过宏simulate!启用，因此可以使用状态、步数以及重复模拟的次数。此宏有第四个可选参数，一个布尔值。当传递false时，模拟终端将被禁用。

($s:expr, $step:expr, $reps:expr $(, $flag:expr)?) => {{
      // Macro code 
}}

您可以使用两个宏创建标签并绘制数据。

• addplot!允许您创建一个新图表，该图表将在自己的标签中显示。

addplot!(String::from("Chart Name"), String::from("xxxx"), String::from("yyyyy"));

• plot!用于向图表添加点。点可以在模拟执行期间添加，例如在after_step方法中。您需要传递图表名称、系列名称、x值和y值。坐标值需要为f64。

plot!(String::from("Chart name"), String::from("s1"), x, y);

在终端主页上还有一个日志部分，当某些事件需要注意时，可以绘制日志消息。您可以使用↑↓箭头在所有日志之间导航。要添加日志，请使用宏log!，传递一个LogType（一个枚举）和日志消息。

 log!(LogType::Info, String::from("Log Message"));

有四种日志类型可用。

pub enum LogType {
    Info,
    Warning,
    Error,
    Critical,
}

贡献常见问题解答

支持会议论文

如果您在研究中发现此代码有用，请考虑引用

@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},
}

🏆 最佳论文提名

许可协议

MIT 许可证

版权所有 (c) ISISLab，萨勒诺大学 2019。

特此授予任何获得本软件及其相关文档副本（“软件”）的个人免费使用软件的权利，不受任何限制，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或出售软件副本的权利，并允许软件的受让人执行上述操作，但需遵守以下条件

上述版权声明和本许可声明应包含在软件的所有副本或实质性部分中。

软件按“原样”提供，不提供任何形式的保证，明示或暗示，包括但不限于适销性、特定用途的适用性和非侵权性保证。在任何情况下，作者或版权所有者不应对任何索赔、损害或其他责任承担责任，无论源于合同、侵权或其他原因，以及与软件或其使用或其他方式有关。