Grid Environment

Overview

In MAGE, a grid environment refers to a spatial structure where the world or space is divided into a set of discrete cells in the shape of a grid (like a chessboard). This grid provides a framework in which agents can move, interact, and make decisions. Here are some key points about grid environments in MAGE:

• Discrete Cells: Each cell in the grid can contain (or not contain) one or several agents. For example, in a simulation of forest fire spread, each cell might contain a tree agent of forest that can play a combustible roles whose state can be in one of several states: unburned, burning, or burned.

• Agent Interaction: Agents in the simulation move across the grid and interact with each other or with the cells themselves based on their position. Their interactions might be governed by rules related to their proximity to other agents or specific cell attributes.

• Boundaries: The grid have hard boundaries where agents can’t move beyond the edge of the grid.

• Scale and Granularity: The size of the cells in the grid and the overall dimensions of the grid determine the scale and granularity of the simulation. Smaller cells can provide more detail but may require more computational resources.

• Neighborhoods: The concept of “neighborhood” is crucial in grid environments. A neighborhood refers to the set of cells surrounding a given cell. Agents might interact with or be influenced by agents in their neighborhood. The definition of a neighborhood can vary; for instance, it might include only directly adjacent cells (von Neumann neighborhood) or might also include diagonally adjacent cells (Moore neighborhood).

• Dynamics: The state of cells in the grid is dependent on the agents occupying them and can change over time based on certain rules or interactions among agents. For instance, in the classic Game of Life simulation, agents in the cells can “live” or “die” based on the number of agents in the neighboring cells that are alive.

• Heterogeneity: While the grid provides a structured environment, the agents moving within it can be heterogeneous, meaning they can have diverse roles (i.e. attributes, behaviors, and decision-making rules).

In summary, a grid environment in MAGE offers a structured spatial framework that facilitates agent interactions, movement, and decision-making. This kind of environment is particularly useful in simulations where spatial relationships and interactions are critical, such as in ecology, urban planning, and epidemiology.

Defining of a Grid Environment

In MAGE, a grid environment is defined using the GridEnvironment agent.

2. Define the Grid Size

The grid size (number of rows and columns) and the cell size must be defined as parameter in the config.json file:

...
"MyGridEnvironment" : {
    "GRID_NUMBER_OF_COLUMNS" : {
      "type" : "integer",
      "description" : " The integer value that represents the number of columns for the environment.",
      "exclusiveMinimum" : 0,
      "multipleOf" : 1,
      "default" : 50,
      "displayName" : "Number of Columns",
      "value" : 50
    },
    "GRID_NUMBER_OF_ROWS" : {
      "type" : "integer",
      "description" : " The integer value that represents the number of rows for the environment.",
      "exclusiveMinimum" : 0,
      "multipleOf" : 1,
      "default" : 50,
      "displayName" : "Number of Rows",
      "value" : 50
    },
    "GRID_CELL_SIZE" : {
      "type" : "integer",
      "description" : "The integer value that represents the size of each cell in the grid.",
      "minimum" : 6,
      "maximum" : 14,
      "multipleOf" : 1,
      "default" : 8,
      "displayName" : "Cell size",
      "value" : 12
    }
  },
...

3. Create the Grid Environment

Within the setup method of the Mage of the simulation model, an instance of GridEnvironment is created, which is named “MyGridEnvironment”:

var environment = create(new GridEnvironment("MyGridEnvironment"));

Adding Agents to a Grid Environment

To create agents for the grid environment, nothing special needs to be done.

1. Create Agents

Agents can be created one by one:

Agent agent = create(new Agent() {
    //... agent setup code ...
});
//... environment add code ...

or in a loop, usually that iterates over the total number of cells in the grid (rows multiplied by columns):

for (int i = 0; i < numOfRows * numOfColumns; i++) {
    Agent agent = create(new Agent() {
        //... agent setup code ...
    });
    //... environment add code ...
}

2. Add Agents to the Grid

After an agent is created, it can be added to the grid environment using the add method of GridEnvironment which adds the agent to the next grid cell:

environment.add(agent);

using the add method of GridEnvironment which adds the agent to a grid cell at a specific location in the grid:

environment.add(agent, row, column);

Upon being added to the grid environment, GridEnvironment assigns the GridElement role to the agents.

Agent Behaviors in a Grid Environment

The GridElement role in the SCOP Framework provides a set of behaviors that an agent can perform in a grid environment. These behaviors enable the agent to interact with the environment, move within it, and gather information about neighboring agents.

1. Getting the Current Cell

The agent can get its current cell in the grid environment using:

public GridCell getCell();

2. Setting the Current Cell

The agent can set its current cell in the grid environment using:

public void setCell(GridCell gridCell);

3. Fetching Neighboring Agents

The agent can retrieves a list of all agents in the neighboring cells of the agent’s current cell using:

final public List<Agent> getNeighborAgents();

The agent can retrieve a list of agents of a specific type in the neighboring cells of the agent’s current cell using:

final public <T extends Agent> List<T> getNeighborAgents(Class<T> agentType);

As well as, the agent retrieves a list of all agent in the neighboring cells with in a range using:

final public List<Agent> getNeighbourAgents(int range);

It can also retrieve a list of agents of a specific type using:

final public <T extends Agent> List<T> getNeighbourAgents(Class<T> agentType, int range)

4. Moving the Agent

The agent can move to specific row and column in the grid using:

public Action moveTo(int row, int column);

The agent can move towards a specific direction (e.g., NORTH, SOUTH, EAST, WEST) in the grid using:

public Action moveTo(Direction direction);

5. Wandering the Agent

The agent can move around in the grid without a specific course, aim or goal by either sweeping the grid:

final public Action sweep();

or doing a random walk using its four neighbors:

final public Action randomWalk4();

or doing a random walk using its eight neighbours:

final public Action randomWalk8();

6. Upcoming Methods

The following methods are marked as deprecated, meaning they have not been implemented yet:

• Move Towards a Target Cell:

  @Deprecated
  public Action moveTowardTarget(GridCell target);
  

This method is intended to move the agent one point towards a target cell, but it’s not yet implemented.

• Move to a GridCell Instance:

  @Deprecated
  final public Action moveTo(GridCell gridCell);
  

This method is intended to move the agent to a specific GridCell instance, but it’s not yet implemented.

By using these behaviors, agents can actively navigate and interact within the grid environment in the SCOP Framework.