Environment

• 1: Grid Environment
• 2: Geographical Environment

public class MyMage extends Mage {
	
	@Override
	protected void setup() {
		// create an environment named "MyEnvironment"
		Environment environment = create(new Environment("MyEnvironment"));
         ...
    }
    ...
}   

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

for (int i = 0; i < numOfAgents; i++) {
    Agent agent = create(new Agent() {
        //... agent setup code ...
    });
}

environment.as(Groupanager.class).add(agent).execute();

1 - 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.

2 - Geographical Environment

Overview

In MAGE, a geographical environment refers to a spatial structure that represents the world or space as a continuous and varied landscape, rather than being divided into discrete cells. This environment provides a naturalistic framework in which agents can move, interact, and make decisions. Here are some key points about geographical environments in MAGE:

• Continuous Space: Unlike the grid-based approach, the geographical environment does not constrain agents to discrete cells. For example, in a simulation of wildlife migration, agents representing animals can move freely across a continuous landscape, encountering various terrains such as forests, rivers, and mountains that affect their behavior and movement.

• Agent Interaction: Agents in the simulation navigate the landscape, interacting with each other and the environment based on their location. These interactions can be influenced by geographical features and distances, with rules that might consider the terrain’s impact on visibility, movement speed, and resource availability.

• Boundaries: The geographical environment can have natural boundaries, such as oceans, mountain ranges, or rivers, which limit the movement of agents or define their habitats.

• Scale and Granularity: The resolution of the geographical data and the scale of the simulation determine its detail and computational requirements. High-resolution data allows for more detailed simulations but requires greater computational resources.

• Variability: Geographical environments inherently include a variety of terrains and ecosystems, offering a rich context for agent interactions. Agents might experience different conditions based on their location, such as varying weather, terrain ruggedness, and resource availability.

• Dynamics: The state of the environment and its components can change over time, influenced by natural processes or the actions of agents within the simulation. For example, vegetation might grow or be consumed by herbivores, and rivers might change course.

• Heterogeneity: Agents operating within a geographical environment can be highly diverse, with different species or entities having unique attributes, behaviors, and decision-making processes that are influenced by the environment.

In summary, a geographical environment in MAGE offers a realistic and dynamic spatial framework that supports complex agent interactions and decision-making. This type of environment is especially valuable in simulations that aim to mimic real-world ecological systems, geological processes, or human-environment interactions, where the continuous and varied nature of the landscape plays a critical role.

Defining of a Geographical Environment

In MAGE, a geographical environment is defined using the GeoEnvironment agent.

1. Create the Geographical Environment

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

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

Adding Agents to a Geographical 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 GeoEnvironment which adds the agent to the next grid cell:

environment.add(agent, latitude, longitude);

Upon being added to the geographical environment, GeoEnvironment assigns the GeoElement 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 Position

The agent can get its current cell in a geographical environment using:

final public double getLatitude();

final public double getLongitude();

2. Setting the Current Position

The agent can set its current position in a geographical environment using:

final public void setPosition(double latitude, double longitude);

3. Moving the Agent

The agent can move to specific row and column in a geographical environment using:

 final public Action moveTo(double latitude, double longitude);

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

final public Action moveTo(Direction direction);

4. Wandering the Agent

The agent can move around in a geographical environment 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();

5. Upcoming Methods

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

• Move Towards a Target Position:

  @Deprecated
  public Action moveTowardTarget(double targetLatitude, double targetLongitude);
  

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