In a previous article I developed and presented a simple agent-based simulation model in Python. The model contained groups of agents on a battlefield grid. The model was coded in Python, using matplotlib for visualization. I went on to conduct a simple simulation run, showing one battle scenario and its outcome. In this article I remodel the problem. I thereby provide a more thorough introduction to agent-based modeling in Python.

Defining classes for agent-based modeling in Python

Below I remodel the problem from my previous article. I try to clean up the code and modularizing functionality into re-usable functions. The result is a modular framework and general appraoch. These can be reused for building even very advanced agent-based modeling in Python.

The agents are modelled as a class, as shown below:

# class, defining agents as abstract data types
class agent:
    # init-method, the constructor method for agents
    def __init__(self,x,y,group):
        self.life = 100 # agent's life score
        self.x = x
        self.y = y
        self.group = group

The battlefield itself is modelled as a two-dimensional grid array, as shown below:

# creating empty 100 x 100 list using list comprehension in python
battlefield = [[None for i in range(0,100)] for i in range(0,100)]

Defining helper functions for the simulation model

Agent groups can be populated onto the battlefield grid using the agentCreator-function.

# define a function for creating agents and assigning them to grid
def agentCreator(size,group,groupList,field,n,m):
    # loop through entire group, i.e. in this case 1000 units
    for j in range(0,size):
        # select random available location 
        while True:
            # random x coordinate
            x = random.choice(range(0,n))
            # random y coordinate
            y = random.choice(range(0,m))
            # check if spot is available; if not then re-iterate 
            if field[x][y] == None:
                field[x][y] = agent(x=x,y=y,group=group)
                # append agent object reference to group list
                groupList.append(field[x][y])
                # exit while loop; spot on field is taken
                break

For plotting agents with a positive life score as visual dots on the battlefield grid I create a plotting function, which can be called at any time throughout the simulation to get a snapshot of current battle status:

# import pyplot and colors from matplotlib
from matplotlib import pyplot, colors
# define function for plotting battlefield (all agents that are still alive)
def plotBattlefield(populationArr, plotTitle):
    # using colors from matplotlib, define a color map
    colormap = colors.ListedColormap(["lightgrey","green","blue"])
    # define figure size using pyplot
    pyplot.figure(figsize = (12,12))
    # using pyplot add a title
    pyplot.title(plotTitle, fontsize = 24)
    # using pyplot add x and y labels
    pyplot.xlabel("x coordinates", fontsize = 20)
    pyplot.ylabel("y coordinates", fontsize = 20)
    # adjust x and y axis ticks, using pyplot
    pyplot.xticks(fontsize = 16)
    pyplot.yticks(fontsize = 16)
    # use .imshow() method from pyplot to visualize agent locations
    pyplot.imshow(X = populationArr, cmap = colormap)

Another function I will need is a function that can map a battlefield status to a numeric two-dimensional array containing values of 1.0 if an agent of type A is still located and alive within a given cell of the two-dimensional battlefield grid, or the value 2.0 if there is an agent of type B. I use this mapping process to feed my plotting function a numeric grid instead of a grid with objects of an abstract i.e. customized class:

# this function maps a battlefield grid to a numeric grid with 1 for agents of type A, 2 for type B and 0 for no agent
def mapBattlefield(battlefieldArr):
    #.imshow() needs a matrix with float elements;
    populationArr = [[0.0 for i in range(0,100)] for i in range(0,100)]
    # if agent is of type A, put a 1.0, if of type B, pyt a 2.0
    for i in range(1,100):
        for j in range(1,100):
            if battlefieldArr[i][j] == None: # empty
                pass # leave 0.0 in population cell
            elif battlefieldArr[i][j].group == "A": # group A agents
                populationArr[i][j] = 1.0 # 1.0 means "A"
            else: # group B agents
                populationArr[i][j] = 2.0 # 2.0 means "B"
    # return mapped values
    return(populationArr)

Using these model components I created an initial battlefield population and plotted agent locations using matplotlib. This is done in the code below and similar to my previous posts, only that in this case I use modularized functionality. The functionality of setting up an initial battlefield grid is transferred to a separate function below. That function is then executed.

# function for creating an initial battlefield grid
def initBattlefield(populationSizeA,populationSizeB,battlefieldArr):
    # initializing new empty battlefield grid, using list comprehension in Python
    battlefieldArr = [[None for i in range(0,100)] for i in range(0,100)]
    # create empty list for containing agent references in future, type A & B
    agents_A = []
    agents_B = []
    # assigning random spots to agents of group A and B; 
    import random
    agentCreator(size = populationSizeA,
                    group = "A",
                    groupList = agents_A,
                    field = battlefieldArr,
                    n = 100,
                    m = 100)
    agentCreator(size = populationSizeB,
                    group = "B",
                    groupList = agents_B,
                    field = battlefieldArr,
                    n = 100,
                    m = 100)
    # return populated battlefield grid
    return(battlefieldArr)

# executing above function for a population size of 1000 for both groups
battlefield = initBattlefield(populationSizeA=1000,populationSizeB=1000,battlefieldArr = battlefield)

# plot battlefield status
plotBattlefield(populationArr = mapBattlefield(battlefield), 
                    plotTitle = "battlefield before simulation run (green = A, blue = B)")

In the next section I will now define the rules for interaction, defining the basic strategies of the agent-based simulation.

Interaction rules for agent-based modeling in Python

In my previous post I then ran a simulation run based on the following rules:

Group A has the strategy of always hitting the same agent in each round

Group B has a random and independent strategy for attacking enemies. This means that each agent of type B will attack a randomly selected agent within that agents reach.

The simulation was conducted under the following conditions:

1) Each round is one iteration

2) In each round, each agent can attack one agent from within its reach

3) The reach of an agent is defined at the start of the simulation and defaults to 10

4) If an agent dies he will no longer be located on the battle field

5) An agent dies when his life score equals or goes below zero

6) Each agent has a randomly distributed attack damage, ranging from 10 to 60

7) In each round all agents get to launch an attack

Like in one of my previous posts I will now iterate through 50 rounds of battle. After each round, agents with a non-positive life score will be removed from the battlefield grid. As a deviation from my previous post I will however now modularize functionality.

Implementing rules and strategies into the model

First, I define a function for removing agents from the battlefield grid:

# function for removing agents from battlefield grid when life score is not strictly positive
def removeDeadAgents(battlefieldArr):
    # identifying agents with life score of score or below - and removing them from the grid
    for i in range(0,len(battlefieldArr)):
        for j in range(0,len(battlefieldArr)):
            if battlefieldArr[i][j]:
                if battlefieldArr[i][j].life <= 0:
                    # remove this agent since life score is not strictly positive
                    battlefieldArr[i][j] = None

Next, I define a function implementing the fighting strategy for agents of type A:

# function implementing one round of fighting, for an agent of type A
def oneRoundAgentA(i,j,attackRange):
    found_i = None
    found_j = None
    # look in neigbouring cells in same order for each iteration
    for k in range(i-attackRange,i+attackRange+1):
        for l in range(j-attackRange,j+attackRange+1):
            # check for negative index values; if so - break!
            if k < 0 or l < 0:
                break
                # check for index values above 99, if so break!
            if k > 99 or l > 99:
                break
            if battlefield[k][l]:
                if battlefield[k][l].group == "B": # then this is an enemy
                    if found_i == None:
                        found_i = k
                        found_j = l
                    
    # deal damage to identified enemies
    if found_i:
        battlefield[found_i][found_j].life = battlefield[found_i][found_j].life - random.randint(10,60)

Then I do the same for agents of type B:

# function implementing one round of fighting, for an agent of type B
def oneRoundAgentB(i,j,attackRange):
    # first check if there even is an enemy in one of the surrounding cells
    enemy_found = False
    for k in range(i-attackRange,i+attackRange+1):
        for l in range(j-attackRange,j+attackRange+1):
            # check for negative index, if so break to next iteration
            if k < 0 or l < 0:
                break
                # check for index values above 99, if so break
            if k > 99 or l > 99:
                break
            if battlefield[k][l] != None:
                if battlefield[k][l].group == "A":
                    enemy_found = True
    # select a random row and a random column
    found_i = None
    found_j = None
    while enemy_found and found_i == None:
        k = random.randint(i-attackRange,i+attackRange)
        l = random.randint(j-attackRange,j+attackRange)
        # check for negative index, if so continue to next iteration
        if k < 0 or l < 0:
            continue
        # check for index value > 99, if so continue
        if k > 99 or l > 99:
            continue
        if k != i:
            if battlefield[k][l]: 
                if battlefield[k][l].group == "A":
                    found_i = k
                    found_j = l
        else:
            if l != j:
                if battlefield[k][l]:
                    if battlefield[k][l].group == "A":
                        found_i = k
                        found_j = l
    # deal damage to identified enemy
    if found_i:
        battlefield[found_i][found_j].life = battlefield[found_i][found_j].life - random.randint(10,60)

I proceed to simulating the battle, using the functions already implemented:

for counter in range(0,50): # in this case I am conducting 50 iterations 
    # iterating through all cells on the battlefield
    for x in range(0,len(battlefield)):
        for y in range(0,len(battlefield)):
            # print("top tier iteration, i: "+str(i)+", j: "+str(j))
            # check if there is an agent within the respective cell
            if battlefield[x][y] != None:
                # depending on the type: execute respective attack strategy
                if battlefield[x][y].group == "A":
                    # one round of battle for this agent of type A
                    oneRoundAgentA(i = x, j = y,attackRange=10)
                else: 
                    # one round of battle for this agent of type B
                    oneRoundAgentB(i = x, j = y,attackRange=10)
    # identifying agents with life score of score or below - and removing them from the grid
    removeDeadAgents(battlefieldArr = battlefield)
# plot battlefield status
plotBattlefield(populationArr = mapBattlefield(battlefield), 
                plotTitle = "battlefield after 50 iterations (green = A, blue = B)")

So far, this has content-wise been identical to the simple simulation study presented in a previous post.

I now want to add a graph to analyze battle outcome and the progression of the battle itself. I thus define an additional plotting function which plots the number of agents by type, being still alive.

I also implement a function for updating the time series of agents still being alive.

# function for updating the time series of agents being alive
def calcAgentsAliveA(resultsA,battlefieldArr):
    # these variables will be used for counting the number of agents alive
    countA = 0
    countB = 0
    # iterate through grid, find agents and update count if relevant
    for i in range(0,len(battlefieldArr)):
        for j in range(0,len(battlefieldArr)):
            if battlefieldArr[i][j]:
                if battlefieldArr[i][j].group == "A":
                    countA = countA + 1
                else:
                    countB = countB + 1
    # update results list and return it
    resultsA.append(countA)
    return(resultsA)

# function for updating the time series of agents being alive
def calcAgentsAliveB(resultsB,battlefieldArr):
    # these variables will be used for counting the number of agents alive
    countA = 0
    countB = 0
    # iterate through grid, find agents and update count if relevant
    for i in range(0,len(battlefieldArr)):
        for j in range(0,len(battlefieldArr)):
            if battlefieldArr[i][j]:
                if battlefieldArr[i][j].group == "A":
                    countA = countA + 1
                else:
                    countB = countB + 1
    # update results list and return it
    resultsB.append(countB)
    return(resultsB)

# function for plotting the number of agents still alive
def plotNumberOfAgentsAlive(plotTitle,iterations,resultsA,resultsB):
    from matplotlib import pyplot
    pyplot.figure(figsize = (12,12))
    pyplot.title(plotTitle, fontsize = 24)
    pyplot.xlabel("iteration", fontsize = 20)
    pyplot.ylabel("agents still alive", fontsize = 20)
    pyplot.xticks(fontsize = 16)
    pyplot.yticks(fontsize = 16)
    ax = pyplot.subplot()
    ax.plot(iterations,resultsA, label = "type a agents")
    ax.plot(iterations,resultsB, label = "type b agents")
    ax.legend(fontsize=16)

Now, I can conduct another simulation run using, displaying the graph. Since I will be running various simulation scenarios I will write the simulation run to a function as well:

# defining function for conducting a simulation run
def simulationRun(iterationLimit,attackRange,showPlot):
    iterations = []
    resultsA = []
    resultsB = []
    for counter in range(0,iterationLimit): # in this case I am conducting 50 iterations 
        # update iterations
        # update results
        iterations.append(counter+1)
        resultsA = calcAgentsAliveA(resultsA,battlefield)
        resultsB = calcAgentsAliveB(resultsB,battlefield)
        # iterating through all cells on the battlefield
        for x in range(0,len(battlefield)):
            for y in range(0,len(battlefield)):
                # print("top tier iteration, i: "+str(i)+", j: "+str(j))
                # check if there is an agent within the respective cell
                if battlefield[x][y]:
                    # depending on the type: execute respective attack strategy
                    if battlefield[x][y].group == "A":
                        # one round of battle for this agent of type A
                        oneRoundAgentA(i = x, j = y, attackRange = attackRange)
                    else: 
                        # one round of battle for this agent of type B
                        oneRoundAgentB(i = x, j = y, attackRange = attackRange)
        # identifying agents with life score of score or below - and removing them from the grid
        removeDeadAgents(battlefieldArr = battlefield)
    # plot battle progression, but only if plot should be displayed
    if showPlot:
        plotNumberOfAgentsAlive("battle progression",iterations,resultsA,resultsB)
    # return results
    return([resultsA,resultsB])

Executing the simulation run and reporting statistics

I can now conduct a simulation run using one line of code only:

battlefield = initBattlefield(populationSizeA = 1000,populationSizeB = 1000,battlefieldArr = battlefield)
results = simulationRun(iterationLimit = 50, attackRange = 10, showPlot = True)

It seems agents of type B have a somewhat effective attack strategy. But what if their number count is slightly lower when battle begins? Below I plot battle progression in a fight with 1000 initial A and 950 initial B agents.

battlefield = initBattlefield(populationSizeA = 1000,populationSizeB = 950,battlefieldArr = battlefield)
results = simulationRun(iterationLimit = 50, attackRange = 10, showPlot = True)

What happens if attack range is reduced to 5?

battlefield = initBattlefield(populationSizeA = 1000,populationSizeB = 1000,battlefieldArr = battlefield)
results = simulationRun(iterationLimit = 50, attackRange = 5, showPlot = True)

Initial battlefield location of agents is random. Final battle outcome might thus be randomly distributed as well. I want to investigate to what extent results are randomized. For this I implement a sensitivity test function that conduct repeats the simulation over and over again. This function will return results that can be visualized in a histogram, representing the total amount of agents alive at simulation end. In this case I repeat the simulation 50 times.

Below I implement the function conducting the sensitivity test:

# this function is used for conducting a sensitivity test with regards to battle outcome
def sensitivityTest(iterationLimit,attackRange,runs):
    # indicate that battlefield is a global variable
    global battlefield
    # empty lists which will contain the final number of agents of respective type, at the end of battle
    outcomeA = []
    outcomeB = []
    # repeating the simulation with defined attack range and iteration limit, for "runs" number of times
    for i in range(0,runs):
        # before each simulation run battlefield must be initialized
        battlefield = initBattlefield(populationSizeA = 1000,populationSizeB = 950,battlefieldArr = battlefield)
        # conduct simulation run
        results = simulationRun(iterationLimit=iterationLimit,attackRange = attackRange,showPlot = False)
        # append result to relevant outcome list
        outcomeA.append(results[0][iterationLimit-1])
        outcomeB.append(results[1][iterationLimit-1])
    # returning the result in a list with two-sublist
    return([outcomeA,outcomeB])

Below I implement the histogram plotting function:

# function for plotting a histogram
def plotHistogram(plotTitle,resultsA,resultsB):
    from matplotlib import pyplot
    pyplot.figure(figsize = (12,12))
    pyplot.title(plotTitle, fontsize = 24)
    pyplot.xlabel("number of agents still alive", fontsize = 20)
    pyplot.ylabel("absolute frequency", fontsize = 20)
    pyplot.xticks(fontsize = 16)
    pyplot.yticks(fontsize = 16)
    ax = pyplot.subplot()
    ax.hist(resultsA, bins=20, histtype="bar",color="red",label="agent A",alpha=0.25)
    ax.hist(resultsB, bins=20, histtype="bar",color="blue",label="agent B",alpha=0.25)
    ax.legend(fontsize=16)

Finally, the code below executes the seensitivity test and plots the result.

# executing the sensitivityTest
results = sensitivityTest(iterationLimit = 50,attackRange = 5,runs = 50)
plotHistogram(plotTitle = "distribution of agents",resultsA = results[0], resultsB = results[1])

This result is for an attack range of 5.

Using this approach, a very advanced agent-based simulation model can be developed.

Other references for agent-based modeling in Python

I list some links to related content below:

• Link: A simple agent-based simulation run visualized using matplotlib in Python
• Link: Developing a simple agent-based model in Python
• Link: Visualizing 2D grids and arrays using matplotlib in Python
• Link: Towards a comprehensive agent-based simulation framework incorporating joint activity-scheduling and ride-sharing within households