krABMaga

https://krabmaga.github.io
Admin
krABMaga is a discrete events simulation engine for developing agent-based modeling simulations in...
Tokens:6,189
Snippets:88
Trust Score:9.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Serve krABMaga Simulation (Web Assembly)

Source: https://krabmaga.github.io/

Run a krABMaga simulation in the browser using Web Assembly. This command requires 'cargo make' to be installed.

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

```

--------------------------------

### Main Function for Simulation with Visualization

Source: https://krabmaga.github.io/

Use this main function when a visualization feature is applied. It sets up graphical settings and starts the visualization.

```rust
// 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);
}

```

--------------------------------

### Run krABMaga Simulation (With Visualization - Makefile)

Source: https://krabmaga.github.io/

Alternative command to run a krABMaga simulation with visualization using 'cargo make'. Ensure 'cargo make' is installed.

```bash
cargo make run --release 

```

--------------------------------

### Add krABMaga Dependency to Cargo.toml

Source: https://krabmaga.github.io/

Add this to your Cargo.toml if you are not starting from a template. Includes features for visualization.

```toml
[dependencies]
krABMaga = { git="https://github.com/krABMaga/krABMaga.git" }

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

```

--------------------------------

### Run Simulation with Features

Source: https://krabmaga.github.io/

Command to run the simulation with specific features enabled. Replace <name_feature> with the desired feature.

```bash
cargo run --release --features <name_feature>

```

--------------------------------

### Main Function for Simulation without Visualization

Source: https://krabmaga.github.io/

Use this main function when only the simulation should run, without any visualization. It initializes the state and runs the simulation using the simulate! macro.

```rust
// 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 state = Flocker::new(dim, num_agents);
  let step = 10;
  let reps = 1;
  let num_agents = 100;  
  let _ = simulate!(state, step, reps);
}

```

--------------------------------

### Sequential Evolutionary Search in Rust

Source: https://krabmaga.github.io/model_exp

Use this macro for sequential parameter optimization with a genetic algorithm. Ensure all required functions (init_population, fitness, selection, mutation, crossover, cmp) and parameters (State, DESIRED_FITNESS, MAX_GENERATION, STEP, REPETITIONS) are correctly defined.

```rust
let result = evolutionary_search!(
    init_population,
    fitness,
    selection,   //with macro u can pass function you define
    mutation,
    crossover,
    cmp,  // function to compare two fitness
    State,
    DESIRED_FITNESS,
    MAX_GENERATION,
    STEP,
    REPETITIONS, // optional
);
```

--------------------------------

### Run krABMaga Simulation (With Visualization)

Source: https://krabmaga.github.io/

Execute a krABMaga simulation with graphical visualization enabled. This requires the 'visualization' feature to be enabled and uses the Bevy game engine for rendering.

```bash
cargo run --release --features  visualization

```

--------------------------------

### Parallel Parameter Sweeping with explore! Macro

Source: https://krabmaga.github.io/model_exp

Enable parallel execution for parameter sweeping by specifying ComputingMode::Parallel. This requires the 'distributed-mpi' feature to be enabled for distributed or cloud computing.

```rust
let result = explore!(
  STEP, REPS, State,  // Simulation Step, Repetitions for each configuration, name of your State struct
  input{
    par1: u32   // Parameters generated
    par2: f64  
  },
  output [ output: f64], 
  ExploreMode::Matched,
  ComputingMode::Parallel // Distributed or Cloud as other options
);
```

--------------------------------

### Bayesian Optimization in Rust

Source: https://krabmaga.github.io/model_exp

Utilize this macro for Bayesian optimization, ideal for expensive black-box functions. It requires initial points, a costly function (simulation execution), an acquisition function, and functions to generate and validate points within the parameter space. The 'bayesian' feature must be enabled.

```rust
let (x, y) = bayesian_opt!(
    init_population, // initial points to setup algorithm
    costly_function, // setup and exectution of a simulation, returning a cost
    acquisition_function,
    get_points, // generate point from parameter space as base of the iteration
    check_domain, // check the point returned from an iteration of the algorithm
    ITERATIONS, 
);
```

--------------------------------

### Sequential Parameter Sweeping with explore! Macro

Source: https://krabmaga.github.io/model_exp

Use this macro for sequential parameter sweeping when parallel processing is not required. Ensure input and output parameters in your State struct match the generated names.

```rust
let result = explore!(
  STEP, REPS, State,  // Simulation Step, Repetitions for each configuration, name of your State struct
  input{
    par1: u32   // Parameters generated
    par2: f64  
  },
  output [ output: f64], 
  ExploreMode::Matched
);
```

--------------------------------

### Simulate Macro Usage

Source: https://krabmaga.github.io/

The simulate! macro is used to run the simulation. It takes the state, step number, and number of repetitions as arguments. An optional boolean flag can disable the Simulation Terminal.

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

```

--------------------------------

### Create Network with Preferential Attachment

Source: https://krabmaga.github.io/virusnetwork

Uses the preferential_attachment_BA macro to create a network with nodes and edges based on node degree. Ensure nodes_set and state.network are properly initialized.

```rust
preferential_attachment_BA!(nodes_set, state.network, NetNode, String, INIT_EDGE);
```

--------------------------------

### Parallel Evolutionary Search in Rust

Source: https://krabmaga.github.io/model_exp

This macro enables parallel execution of the genetic algorithm for parameter optimization. Specify 'ComputingMode::Parallel' (or 'Distributed', 'Cloud') to leverage multiple cores or nodes. Requires the same function and parameter definitions as the sequential version.

```rust
let result = evolutionary_search!(
    init_population,
    fitness,
    selection,   //with macro u can pass function you define
    mutation,
    crossover,
    cmp,  // function to compare two fitness
    State,
    DESIRED_FITNESS,
    MAX_GENERATION,
    STEP,
    REPETITIONS, // optional
    ComputingMode::Parallel // Distributed or Cloud as other options
);
```

--------------------------------

### Implement Flocker New Function

Source: https://krabmaga.github.io/flockers

Constructor for the Flocker struct, initializing the simulation state with dimensions and the number of flockers.

```rust
impl Flocker {
    pub fn new(dim: (f32, f32), initial_flockers: u32) -> Self {
        Flocker {
            step: 0,
            field1: Field2D::new(dim.0, dim.1, DISCRETIZATION, TOROIDAL),
            initial_flockers,
            dim,
        }
    }
}

```

--------------------------------

### Run krABMaga Simulation (No Visualization)

Source: https://krabmaga.github.io/

Execute a krABMaga simulation without graphical visualization. This command runs the simulation in the terminal, allowing interaction with the Simulation Terminal.

```bash
cargo run --release

```

--------------------------------

### Log Message Macro

Source: https://krabmaga.github.io/

Use the log! macro to add a log message to the Simulation Terminal. Requires a LogType and the message string.

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

```

--------------------------------

### Add Plot Tab Macro

Source: https://krabmaga.github.io/

Use the addplot! macro to create a new plot that will be displayed in its own tab. Requires a chart name, x-axis label, and y-axis label.

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

```

--------------------------------

### Local krABMaga Dependency Path

Source: https://krabmaga.github.io/

Change the dependency in Cargo.toml to point to a local path for testing or development of the krABMaga engine.

```toml
[dependencies]
# krABMaga = { git="https://github.com/krABMaga/krABMaga.git" }
krABMaga = { path="path/to/krABMaga"}

```

--------------------------------

### Simulation State Structure

Source: https://krabmaga.github.io/antsforaging

Defines the overall state of the simulation, including various grids for ants, obstacles, and pheromones, along with simulation status flags and step count.

```rust
pub struct State {
    pub ants_grid: AntsGrid,
    pub ants_grid: SparseGrid2D<Ant>,
    pub obstacles_grid: SparseGrid2D<Item>,
    pub to_food_grid: ToFoodGrid,
    pub to_home_grid: ToHomeGrid,
    pub food_source_found: RwLock<bool>,
    pub food_returned_home: RwLock<bool>,
    pub step: u128,
}

```

--------------------------------

### Define Bird Agent Structure

Source: https://krabmaga.github.io/flockers

Defines the structure for a single bird agent, including its ID, current position, and last known position.

```rust
#[derive(Clone, Copy)]
pub struct Bird {
    pub id: u32,
    pub pos: Real2D,
    pub last_d: Real2D,
}

```

--------------------------------

### LogType Enum

Source: https://krabmaga.github.io/

Available types for log messages: Info, Warning, Error, Critical.

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

```

--------------------------------

### Define Network Node Structure

Source: https://krabmaga.github.io/virusnetwork

Defines the NetNode struct, representing a node in the network. It includes an ID, position for visualization, its current status, and a flag indicating if a virus has been detected.

```rust
#[derive(Clone, Copy)]
pub struct NetNode {
    pub id: u32,
    pub pos: Real2D,
    pub status: NodeStatus,
    pub virus_detected: bool,
}
```

--------------------------------

### Define Flocker State Structure

Source: https://krabmaga.github.io/flockers

Defines the state of the flocking simulation, including the current step, the environment field, the initial number of flockers, and dimensions.

```rust
pub struct Flocker {
    pub step: u64,
    pub field1: Field2D<Bird>,
    pub initial_flockers: u32,
    pub dim: (f32, f32),
}

```

--------------------------------

### Ant Agent Structure

Source: https://krabmaga.github.io/antsforaging

Defines the structure of an individual ant agent, including its ID, location, food status, and reward value.

```rust
#[derive(Copy, Clone)]
pub struct Ant {
    pub id: u128,
    pub loc: Int2D,
    pub last: Option<Int2D>,
    /// False means the agent will try to find food by following food pheromones if possible, or by
    /// flooding the grid until it is found. True means the agent will try to return home by using the
    /// previously deposited pheromones.
    pub has_food: bool,
    /// Value used to increase the pheromones in the nest and in the food source.
    /// This will let the agents spread pheromones in the surrounding areas from point of interests
    /// so that other agents will know which path to take to do their job.
    pub reward: f64,
}

```

--------------------------------

### Add Point to Plot Macro

Source: https://krabmaga.github.io/

Use the plot! macro to add a point to an existing plot. Points can be added during simulation execution. Requires plot name, series name, x value, and y value (f64).

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

```

--------------------------------

### Define Node Status Enum

Source: https://krabmaga.github.io/virusnetwork

Defines the possible states a node can be in: Susceptible, Infected, or Resistent. This enum is used to track the status of each node in the network simulation.

```rust
#[derive(Clone, Copy, Debug)]
pub enum NodeStatus {
    Susceptible,
    Infected,
    Resistent,
}
```

--------------------------------

### Define Eater Agent Structure

Source: https://krabmaga.github.io/sugarscape

Defines the `Eater` struct, representing an agent in the Sugarscape simulation. It includes attributes like ID, position, vision, metabolism, age, maximum age, and wealth. Use this struct to initialize and manage agents.

```rust
#[derive(Clone, Copy)]
pub struct Eater {
    pub id: u32,
    pub position: Int2D,
    pub vision: u32,
    pub metabolism: u32,
    pub age: u32,
    pub max_age: u32,
    pub wealth: i32,
}

```

--------------------------------

### Sheep/Wolf Struct Definition in Rust

Source: https://krabmaga.github.io/wolfsheepgrass

Defines the common fields for Sheep and Wolf agents, including their ID, life state, location, energy levels, and reproduction probability. These agents are part of a simulation that models predator-prey dynamics.

```rust
#[derive(Copy, Clone)]
pub struct Sheep/Wolf {
    pub id: u32,
    pub animal_state: LifeState,
    pub loc: Int2D,
    pub last: Option<Int2D>,
    pub energy: f64,
    pub gain_energy: f64,
    pub prob_reproduction: f64,
}

```

--------------------------------

### LifeState Enum Definition in Rust

Source: https://krabmaga.github.io/wolfsheepgrass

Defines the possible states for an animal agent within the simulation: Alive or Dead. This enum is used to manage the life cycle of agents and is crucial for determining interactions and survival.

```rust
#[derive(Clone, Copy, PartialEq)]
pub enum LifeState {
    Alive,
    Dead,
}

```

--------------------------------

### Define Agent Status Enum in Rust

Source: https://krabmaga.github.io/schelling

Defines the possible statuses for agents in the simulation, representing their group affiliation. This enum is used to distinguish between red and blue agents.

```rust
#[derive(Copy, Clone, PartialEq, Eq, Hash)]
pub enum Status {
    Red,
    Blue,
}

```
Tokens:
Raw