{"data":{"markdownRemark":{"html":"

Model overview

\n

In this tutorial we will present an implementation of the forest fire model. This model illustrates how a wild fire spreads through a 2-dimensional grid. Each cell of this grid can either be occupied by a tree or empty. If a tree catches fire, it will ignite its neighboring trees. The model investigates how the fire spread through the environment based on the density of trees (versus empty cells) and the way the fire spreads (i.e. whether it spreads only between nearest neighbor trees or whether it can also affect the next nearest neighbors).

\n

While modelling of a wild fire might appear as a niche endeavor, this model can be seen as a more general framework for modelling contagion in a system, providing many applications. A direct translation of such model would be to model the spread of a disease in different locations of an environment. However, the model can even provide a template for contagion in a more general sense. For instance, this template could be adapted for modelling the spread of misinformation in a social network.

\n

Summary of the model implementation

\n

The model has the following key components:

\n\n

Globals

\n

The following global variables are defined in the forest fire model.

\n
\n

ForestFireModel.java

\n
\n
     @Input(name = \"gridSize\") 1  \n     public int gridSize = 50;  \n      \n      @Input(name = \"Empty Cells Proportion\")  \n            public double emptyCellsPcg = 0.4;  \n      \n      @Input(name = \"Probability of spontaneous ignition\")  \n            public double probabilityIgnite = 0.01;  \n      \n      @Input(name = \"Neighborhood type: 1 Moore; 2= Von Neumann; 3=customized\")  \n            public int neighborhood = 2;  \n      \n      @Input(name = \"Neighbors distance\")  \n            public int similarityThreshold = 2;  \n      \n     public GridParameters gridParameters;
\n\n

Connectors and agent neighborhoods

\n

As explained above, in this model there are different ways to connect the cells/agents. The chosen way of connecting the agents will result in different types of neighborhoods. Importantly, this way of connecting agents will dramatically effect how the fire will spread through the environment. Therefore, the way the environment (or network) is structured is a core component for investigating how the model will behave. Since this is a critical part of the model, we will use this to demonstrate different strategies for forming networks in the SDK.

\n

Importantly, we will also demonstrate how you can build your own customized connectors and connect agents in a flexible way.

\n

Moore Neighborhood

\n

In a Moore neighborhood, each cell is connected to its nearest and next nearest neighbors, i.e. the central cell is connected to its 8 surrounding cells. To connect the cells in a Moore neighborhood, we can use a built-in connector of the SDK in the setup function:

\n
\n

ForestFireModel.java

\n
\n
    @Override  \n    public void setup() {  \n      Group<ContagionAgent> agentGroup = generateGroup(ContagionAgent.class, getGlobals().gridParameters.nbTotal, agents -> {  \n    \n    ...\n      \n     if(getGlobals().neighborhood == 1) {  \n            agentGroup.gridConnected(Links.AgentLink.class).mooreConnected();  \n      } \n\t
\n

Von Neumann Neighborhood

\n

In a Von Neumann neighborhood, each cell is connected to its nearest neighbors, i.e. the central cell is connected to its 4 adjacent cells. To connect the cells in a Von Neumann neighborhood, we can use a built-in connector of the SDK in the setup function:

\n
\n

ForestFireModel.java

\n
\n
@Override  \npublic void setup() {  \n  Group<ContagionAgent> agentGroup = generateGroup(ContagionAgent.class, getGlobals().gridParameters.nbTotal, agents -> {  \n\n...\n  \n if(getGlobals().neighborhood == 2) {  \n\tagentGroup.gridConnected(Links.AgentLink.class).vonNeumannConnected();\n  }
\n

Customized connector

\n

While the built-in connectors are a great way of easily and efficiently connecting agents, under some circumstance you might wish to design you own custom-made connectors to allow for more flexibility when connecting agents in you simulation.\nIn the context of this forest fire model, one might wish to connect agents based on their location, however, allowing for slightly further distances between agents (e.g. connect to the closest 12 agents instead to the closest 8 agents). Here, it will be demonstrated how to achieve such functionality within the SDK.

\n

Attributes defining similarity

\n

In the 2-d environment, agents are connected if they are in physical proximity. Thus, agents are connected based on their similarity with respect to their x- and y-coordinate in the grid. Importantly, this is a special case of a very general principle of homophily. Homophily describes the finding that agents are more likely to connect if they are similar in some attributes, and this principle applies to a wide range of situations such as social networks where people are more likely to connect to each other if they share similar views. Therefore, connecting agents based on their location should be seen as an illustration and can easily be applied to other attributes.\nFirst, each agent needs to be assigned some attributes based on which they can be connected. This happens in the setup() function where the agents are initialized.

\n
\n

ForestFireModel.java

\n
\n
    @Override  \n    public void setup() {  \n        getGlobals().gridParameters = new GridParameters(gridSize2, getGlobals().emptyCellsPcg);  \n\n      Group<ContagionAgent> agentGroup = generateGroup(ContagionAgent.class, getGlobals().gridParameters.nbTotal, agents -> {  \n            Cell newCell = getGlobals().gridParameters.assignCell();  \n\t\t    if(getGlobals().neighborhood != 1 && getGlobals().neighborhood != 2) {  \n                agents.attribute1 = newCell.getXCoordinate();  \n\t\t\t    agents.attribute2 = newCell.getYCoordinate();  \n      }  \n       agents.initializeState(newCell.isEmpty());  \n      agents.frequencyIgnition = getGlobals().probabilityIgnite;  \n      });
\n

Each agent is initialized with their x- and y-coordinates as attribute. These coordinates are defined in the gridParameters class as follows:

\n
\n

GridParameter.java

\n
\n
    public class GridParameters {  \n     public int nbTotal;  \n     public int nbOccupied;  \n     public int nbEmpty;  \n     public ArrayList<Integer> yCoordinates = new ArrayList<Integer>();  \n     public ArrayList<Integer> xCoordinates = new ArrayList<Integer>();  \n     public ArrayList<Boolean> stateList = new ArrayList<>();  \n     public ArrayList<Cell> cellList = new ArrayList<Cell>();  \n      \n     public GridParameters(int gridSize, double emptyCellsPcg) {  \n\t     nbTotal = (int) Math.pow(gridSize, 2);  \n\t     nbEmpty = (int) Math.ceil(nbTotal * emptyCellsPcg);  \n\t     nbOccupied = nbTotal - nbEmpty;  \n\t     int counter = 0;  \n      \n\t     for (int i = 0; i < gridSize; ++i) {  \n                for (int j = 0; j < gridSize; ++j) {  \n                    xCoordinates.add(i);  \n\t\t\t\t    yCoordinates.add(j);  \n\t\t\t\t\t     if(counter < nbOccupied) {  \n\t                        stateList.add(false);  \n\t\t\t\t\t      } else {  \n\t                        stateList.add(true);  \n\t\t\t\t\t      }  \n                    counter++;  \n\t\t\t      }  \n\t\t     }\t  \n      \n\t     Collections.shuffle(stateList);  \n\t     for (int k =0; k < nbTotal; k++){  \n                    Cell newCell= new Cell((int) xCoordinates.get(k), (int) yCoordinates.get(k), stateList.get(k));  \n\t      cellList.add(newCell);  \n\t      }  \n     }  \n      \n    public Cell assignCell(){  \n      Cell outputCell = cellList.get(0);  \n      cellList.remove(0);  \n     return outputCell;  \n      }  \n    }
\n

Each cell has now two attributes, defining their x- and y-coordinate.

\n

Start with a fully connected network

\n

To define your customized network, we start with a fully connected network and later prune this network based on the (dis)similarity between agents. Therefore, in the setup() function, a fully connected network is initialized:

\n
\n

ForestFireModel.java

\n
\n
    @Override  \n    public void setup() {  \n      Group<ContagionAgent> agentGroup = generateGroup(ContagionAgent.class, getGlobals().gridParameters.nbTotal, \n      if(getGlobals().neighborhood == 3) {  \n\t\tagentGroup.fullyConnected(agentGroup, Links.AgentLink.class);\n      }
\n

Prune the network

\n

On the first tick of the simulation, the network needs to be pruned. This happens with the following commands in the step() function:

\n
\n

ForestFireModel.java

\n
\n
if (getContext().getTick() == 0) {  \n    if(getGlobals().neighborhood !=1 && getGlobals().neighborhood != 2){  \n        run(ContagionAgent.informNeighborAttribute(), ContagionAgent.pruneConnection());  \n    }\n}
\n

There are two relevant component here. First, each agent sends a message to all other agents, informing them about its attributes (i.e. its x- and y-coordinate). Second, each agent takes the information received from the other agents to prune their network.

\n
\n

ContagionAgent.java

\n
\n
    private void sendAttribute(int attribute1, int attribute2){  \n        getLinks(Links.AgentLink.class).send(Messages.AttributeMessage.class, (msg, link) -> {  \n            msg.attribute1=attribute1;  \n      msg.attribute2=attribute2;  \n      });  \n    }
\n

Here, each agent sends a message with its attributes (in this case x- and y-coordinate) to all other agents.

\n
\n

ContagionAgent.java

\n
\n
    public static Action<ContagionAgent> pruneConnection() {  \n        return Action.create(  \n                ContagionAgent.class, contagionAgent ->  \n                        contagionAgent.getMessagesOfType(Messages.AttributeMessage.class).forEach(msg -> {  \n                            double dissimilarity = Math.pow((msg.attribute1 - contagionAgent.attribute1), 2) + \t\t    Math.pow((msg.attribute2 - contagionAgent.attribute2), 2);  \n\t\t\t\t\t\t    if (dissimilarity > contagionAgent.getGlobals().similarityThreshold) {  \n                                contagionAgent.removeLinksTo(msg.getSender());  \n\t\t\t\t\t\t      }  \n                        }));  \n    }
\n

Each agent receives a message from all other agents, stating their attributes. Based on this, the agent calculates a dissimilarity (in this case a distance) to each other agent. If the other agent is further away than a predefined threshold, the link to this agent is removed. Through this process only the links between neighboring agents remain. Importantly, a similar pruning process can be applied to other attributes, enabling to create neighborhoods based on similarity of any attribute.

\n

Spreading contagion

\n

After having established a network structure, we are interested in how the fire spreads through the environment.\nOn the first step, some trees will spontaneously catch fire (e.g. due to a lightning bolt). This creates the starting condition for the spread of fire:

\n
\n

ForestFire.java

\n
\n
    public void step() {  \n        super.step();  \n     if (getContext().getTick() == 0) {  \n     \n     ...\n     \n         run(ContagionAgent.spontaneousIgnite());  \n\t     return;  \n      }
\n
\n

ContagionAgent.java

\n
\n
    public static Action<ContagionAgent> spontaneousIgnite() {  \n        return Action.create(  \n                ContagionAgent.class, contagionAgent -> {  \n                    double igniteSpontaneous = Math.random();  \n\t\t\t\t    if (igniteSpontaneous < contagionAgent.frequencyIgnition) {  \n\t                        contagionAgent.switchToInfected();  \n\t                         }  \n                });  \n    }
\n

Hereby, each tree will be ignited with a predefined probability (e.g. 1%).\nAfter the initial ignition, the burning trees will spread fire to their neighbors:

\n
\n

ContagionAgent.java

\n
\n
    public static Action<ContagionAgent> sendContagion() {  \n        return Action.create(  \n                ContagionAgent.class, contagionAgent -> {  \n                    if(contagionAgent.getState() == State.INFECTED) {  \n                        contagionAgent.getLinks(Links.AgentLink.class).send(Messages.SendContagion.class);  \n\t\t\t\t\t    contagionAgent.switchToRecovered();  \n\t\t\t\t      }  \n                });  \n    }
\n

After spreading the fire to its neighbors, the each tree switch their status to BURNED indicating that this tree won't be susceptible for catching fire in the future.\nFinally, each tree that has been ignited switches their status to BURNING:

\n
    public static Action<ContagionAgent> receiveContagion() {  \n        return Action.create(  \n                ContagionAgent.class, contagionAgent ->  \n                    contagionAgent.getMessagesOfType(ForestFire.Messages.SendContagion.class).forEach(msg ->  \n                        contagionAgent.switchToInfected()));  \n    }
\n

In this implementation, the transmission of fire is deterministic (i.e. every neighbor of a burning tree will catch fire), however, it would be easy to include a more sophisticated mechanism here for transmission (e.g. a probabilistic function).

\n

Visualizing the output in the console

\n

The model can be easily visualized in the console. Going to the Network view and stepping through the ticks will show you how the fire spreads through the network. This is a very simple way of sense checking whether the model behaves in predicted ways.\n\n \n \n \n ].iloc[-1]\n data_timepointZero= data[data['tick']==1]\n dimensions=int(math.sqrt(len(data_timepointZero)))\n timePointGrid_full=np.array([[[0 for k in range(dimensions)] for j in range(dimensions)]for j in range(ticks)])\n \n for tick in range(1, ticks): \n data_timepoint= data[data['tick']==tick]\n timePointGrid=np.array([[0 for k in range(dimensions)] for j in range(dimensions)])\n for cell in range(len(data_timepoint)): \n row = int(data_timepoint['agentID'].iloc[cell]%dimensions)\n column = int(data_timepoint['agentID'].iloc[cell]/dimensions)\n value=-99\n if data_timepoint['agent_status'].iloc[cell] == b'EMPTY': \n value=-1\n elif data_timepoint['agent_status'].iloc[cell] == b'HEALTHY': \n value =0\n elif data_timepoint['agent_status'].iloc[cell] == b'INFECTED': \n value =1\n elif data_timepoint['agent_status'].iloc[cell] == b'RESISTANT': \n value =2\n timePointGrid[column, row]=value\n timePointGrid_full[tick, column, row]=value\n\n\n dim1=timePointGrid_full.shape\n values = np.unique(timePointGrid_full.ravel())\n print(values)\n fig=plt.figure(figsize=(8, 8))\n cmap = matplotlib.colors.ListedColormap(['lightgrey', 'green', 'red', 'black'])\n grid =plt.imshow(timePointGrid_full[1,:,:], cmap=cmap, interpolation='none')\n colors = [grid.cmap(grid.norm(value)) for value in values]\n patches = [mpatches.Patch(color=colors[0], label=\"empty\"), mpatches.Patch(color=colors[1], label=\"healthy\") , mpatches.Patch(color=colors[2], label=\"burning\"), mpatches.Patch(color=colors[3], label=\"burned\")]\n plt.legend(handles=patches, bbox_to_anchor=(0.8, 0),\n ncol=4, fancybox=True, shadow=True)\n plt.grid(True)\n plt.axis('off')\n \n def animate_noise(i):\n grid.set_array(timePointGrid_full[i,:,:])\n return [grid]\n anim = animation.FuncAnimation(fig, animate_noise, frames=dim1[0], interval=500, blit=True)\n plt.close(fig)\n \n HTML(anim.to_html5_video())\n

\n \n
\n

Summary

\n

In this tutorial we have walked through an implementation of the forest fire model. Besides the specific topic of the model, this can be used as template for modelling contagion in a system, enabling multiple applications.\nBesides the specific model, we also illustrated how to create customized connectors to create flexible rules for forming connections between agents. Moreover, we also showcased how to export data using the parquet writers and import this data into a Jupyter Notebook for further analysis and visualization.

","headings":[{"value":"Model overview","depth":2},{"value":"Summary of the model implementation","depth":2},{"value":"Globals","depth":2},{"value":"Connectors and agent neighborhoods","depth":2},{"value":"Moore Neighborhood","depth":3},{"value":"Von Neumann Neighborhood","depth":3},{"value":"Customized connector","depth":3},{"value":"Attributes defining similarity","depth":4},{"value":"Start with a fully connected network","depth":4},{"value":"Prune the network","depth":4},{"value":"Spreading contagion","depth":2},{"value":"Visualizing the output in the console","depth":2},{"value":"Data output","depth":2},{"value":"Analyzing data output in Jupyter Notebook","depth":2},{"value":"Summary","depth":2}],"frontmatter":{"title":"Forest Fire Tutorial","toc":true,"experimental":null}},"site":{"siteMetadata":{"title":"Simudyne Docs","latestVersion":"2.6"}}},"pageContext":{"absolutePath":"/home/vsts/work/1/s/content/2.4/docs/tutorials/forestfire.md","versioned":true,"version":"2.4","kind":"docs","pagePath":"/tutorials/forestfire","chronology":{"prev":{"name":"SIR Epidemiology Tutorial","path":"/tutorials/sir"},"next":{"name":"Chiarella Calibration Tutorial","path":"/tutorials/extended_chiarella"}},"lastUpdated":"2026-04-21T13:56:54.849Z"}}