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

Model overview

\n

In this tutorial we will present an implementation of the classic Schelling model of segregation. This model illustrates how the interaction of people with \"mild\" in-group preference towards their own group can lead to highly segregated societies.

\n

This model is embedded in a 2-dimensional grid forming the model environment. This model environment is inhabited by two types of agents (blue and red agents). Every agent occupies one cell in the 2-d grid. All agents have a preference for living in a neighborhood with agents of the same type, with a threshold parameter defining the level of similarity needed for an agent to be satisfied.\nIf there are not enough similar agents (i.e. agents of the same colour) in a neighborhood, agents can decide to move to a cell where the neighborhood has more agents of similar type.

\n

The model simulates the segregation of neighborhoods over time based on the agents' preferences for similarity.

\n

The code for this tutorial is available as a zip download, containing a complete model as a Maven project. This project should be able to be run from any Maven or Java IDE environment.

\n\n\tDownload Tutorial Files\n\n

Summary of the model implementation

\n

In the Simudyne SDK implementation, the model has the following core components:

\n\n

Globals

\n

The following global variables are defined in the Schelling model.

\n
\n

SchellingModel.java

\n
\n
  public static final class Globals extends GlobalState {  \n    @Input(name = \"Grid Size\")  \n    public int gridSize = 40;  \n    @Input(name = \"Empty Cells Proportion\")  \n    public double emptyCellsPcg = 0.1;  \n    @Input(name = \"Similarity Threshold\")  \n    public double similarityThreshold = 0.4;  \n    @Input(name = \"Data Export Tick\")  \n    public int dataExportTick = 49;  \n    public GridParameters gridParameters;}
\n\n

Setup

\n

In the setup, the environment, all agents and all links are initialized to setup the initial state of the model.\nCreating the initial agents is done through the concept of a topology of groups. A group represents a set of agents, where each group has a type of agent, a number of agents in that group, and optionally an initialiser, which can customise the state for each agent.

\n

In this model, we have a group of Schelling agents and an environment.

\n
\n

SchellingModel.java

\n
\n
     Group<BlueAgent> blueAgentGroup = generateGroup(BlueAgent.class, getGlobals().gridParameters.nbBlue,  \n         blueAgent -> blueAgent.similarityThreshold = getGlobals().similarityThreshold);  \n        Group<RedAgent> redAgentGroup = generateGroup(RedAgent.class, getGlobals().gridParameters.nbRed,  \n         redAgent -> redAgent.similarityThreshold = getGlobals().similarityThreshold);
\n

The Schelling agents are further divided into a group of blue and red agents, whereby both groups have the same number of agents which is defined by the number of cells minus the percentage of empty cells. On initialization, each agents similarityThreshold is equated to the variable similarityThreshold defined in Globals.

\n
\n

SchellingModel.java

\n
\n
getGlobals().gridParameters = new GridParameters(getGlobals().gridSize, getGlobals().emptyCellsPcg);  \nGroup<Environment> environmentGroup = generateGroup(Environment.class, 1, Environment::initEnvironment);
\n

In addition to the agent groups, there is also the environment which saves the information about the 2-d grid, the type of agent occupying a cell, the similarity of neighborhood and a list of empty cells. the The environment can provide the Schelling agents with information about their surrounding and point towards empty cells in case an agent decides to move.

\n
\n

SchellingModel.java

\n
\n
environmentGroup.fullyConnected(blueAgentGroup, Links.EnvironmentToSchellingLink.class);  \nenvironmentGroup.fullyConnected(redAgentGroup, Links.EnvironmentToSchellingLink.class);  \nblueAgentGroup.fullyConnected(environmentGroup, Links.SchellingToEnvironmentLink.class);  \nredAgentGroup.fullyConnected(environmentGroup, Links.SchellingToEnvironmentLink.class);
\n

To enable the interaction between agents and environment, all agents display a connection to the environment and conversely the environment has a connection will all agents.

\n

Step

\n

The step takes care of the logic that happens between each tick, in an ABM this is mostly concerned with running behavioural sequences over the system to move the system forwards through time.

\n

In this model, the main components of each step are evaluating an agents environment and moving cells in case an agent is unhappy with its neighborhood.

\n

The line run(Environment.updateAgentStates(), SchellingAgent.updateState()); runs an evaluation of the agents environment based on movement that occurred in the previous step. After this process, each agent has an updated measure of the percentage of similar agents in its neighborhood.

\n

After the update, each agent will evaluate whether its neighborhood is similar enough, and if not move to a different cell. This evaluation is conducted in the SchellingAgent.step() function. If an agent decides to move, the movement to a new empty cell is coordinated by the Environment.moveAgents() function.

\n

Moreover, on the first step, the function run(SchellingAgent.registerToEnvironment(), Environment.receiveRegistrations()) is executed in order to assign an initial location for each agent in the 2-d grid.

\n

Each of these behaviors will be explained in more detail in the following section.

\n

Behaviors

\n

We'll run through the actions in this sequence in order, to see how they progress. When we see each agent for the first time, we'll also have a quick look at how it's defined.

\n

SchellingAgent#registerToEnvironment

\n
\n

SchellingAgent.java

\n
\n
   public abstract class SchellingAgent extends Agent<SchellingModel.Globals> {  \n        public final AgentState.AgentRace race;  \n        public double similarityThreshold;  \n        public AgentState state;\n        public SchellingAgent(AgentState.AgentRace race) {  \n            this.race = race;  \n  }
\n

Each Schelling Agent has a race which describes whether the agent is of type blue or red. Moreover, the Schelling agents have a similarityThreshold which is the same for all Schelling agents and is defined in the Globals. Moreover, each agent has a state which describes whether this agent is happy or unhappy in its environment (i.e. whether the agents wants to move or not), its current location and the similarity of its neighborhood.

\n
\n

SchellingAgent.java

\n
\n
     public static Action<SchellingAgent> registerToEnvironment() {\n    \t return Action.create(SchellingAgent.class, schellingAgent -> {  \n\t         schellingAgent.state = new AgentState(schellingAgent.race);  \n\t\t\t AgentState state = new AgentState(schellingAgent.race);\n\t\t\t schellingAgent.getLinks(Links.SchellingToEnvironmentLink.class)\n\t\t\t  .send(Messages.StateMessage.class,  \n\t            (msg, link) -> msg.state = state);  \n         });  \n      }
\n

On the first tick of each simulation, each Schelling agent registers to the environment by sending a StateMessage to the environment.

\n
\n

Messages.java

\n
\n
   public static class StateMessage extends Message {  \n        public AgentState state;}
\n

Such StateMessage entails a state object which encorporates all relevant information about the agent, such as whether the agent is happy or not and its type.

\n

Environment#receiveRegistrations

\n

The environment stores all information about the 2-d grid and the agents such as their position and state.

\n
\n

Environment.java

\n
\n
public class Environmenenter link description heret extends Agent<SchellingModel.Globals> {  \n     public HashMap<Long, AgentState> agentMap;  \n     public Random random;  \n     public Grid grid;  \n     public DataOutput dataOutput;  \n     @Variable  \n     public double averageSimilarity;  \n     @Variable  \n     public int unhappyAgentCount;
\n

In the field agentMap the environment saves a hashmap with each agents identifier as key and their state as value.\nMoreover, the environment saves the grid and overall statistics such as averageSimilarity and unhappyAgentCount which are displayed as outputs in the console.

\n
public static Action<Environment> receiveRegistrations() {  \n\treturn Action.create(Environment.class, environment ->  \n        environment.getMessagesOfType(Messages.StateMessage.class).forEach(stateMessage ->  \n                environment.agentMap.put(stateMessage.getSender(), stateMessage.state)));}
\n

When the agents register to the environment, each agent is added to the agentMap saving their identifier and their state.

\n

Environment#initPositions

\n

During the first step, the environment also assigns an initial location to each agent to create the starting conditions of the 2-d grid.

\n
\n

Environment.java

\n
\n
public static Action<Environment> initPositions() {  \n    return Action.create(Environment.class, environment -> environment.agentMap.forEach((agentID, \t\t\t\t agentState) -> {  \n        Optional<Cell> optionalCell = environment.grid.cellList.stream()  \n                .filter(x -> x.sameAgentState(agentState.race) && !x.occupied).findFirst();  \n\t\tif (!optionalCell.isPresent())  \n            throw new IllegalArgumentException(\"No position found.\");  \n  \n  Cell cell = optionalCell.get();  \n  cell.switchState(agentState.race);  \n  agentState.position = cell;  \n  }));  \n}
\n

Here, the environment searches for empty cells that are also in line with the agents preferences (i.e. enough similar agents in the surrounding neighborhood) and if a cell exists that satisfies these constraints the agent is assigned to this cell.

\n

Environment#updateAgentStates

\n

After the initialization, the first action in each tick is to update the state associated with each agent.

\n
\n

Environment.java

\n
\n
public static Action<Environment> updateAgentStates() {  \n    return Action.create(Environment.class, environment -> {  \n        environment.averageSimilarity = 0;  \n\t    environment.agentMap.forEach((agentID, agentState) -> {  \n            double similarityMetric = environment.calculateSimilarityMetric(agentState.position.coordinates, agentState.race);  \n\t\t    agentState.changeSimilarityMetric(similarityMetric);  \n\t\t    environment.averageSimilarity += similarityMetric;  \n\t\t    environment.getLinksTo(agentID).send(Messages.StateMessage.class, (msg, link) ->  \n                    msg.state = agentState);  });  \n\t   environment.averageSimilarity = environment.averageSimilarity / environment.agentMap.size();  \n  });  \n}
\n

For each agent, the similarity of agents in the neighborhood is calculated and each agent is informed about the new similarity of its surrounding by the environment. This is done by sending a StateMessage entailing an altered state object which incorporates the new similarityMetric for the agent's cell.

\n

SchellingAgent#updateState

\n
\n

SchellingAgent.java

\n
\n
 public static Action<SchellingAgent> updateState() {  \n        return Action.create(SchellingAgent.class, schellingAgent ->  \n              schellingAgent.state.update(schellingAgent.getMessageOfType(Messages.StateMessage.class).state));  \n    }
\n

Based on the newly calculated similarity of each agents' neighborhood the agents' update their states to incorporate this new information about their environment.

\n

SchellingAgent#step

\n
\n

SchellingAgent.java

\n
\n
 public static Action<SchellingAgent> step() {  \n            return Action.create(SchellingAgent.class, schellingAgent -> {  \n                schellingAgent.state.changeSatisfaction(schellingAgent.state.similarityMetric < schellingAgent.similarityThreshold ? AgentState.Satisfaction.UNHAPPY : AgentState.Satisfaction.HAPPY);  \n if (schellingAgent.state.satisfaction == AgentState.Satisfaction.UNHAPPY) {  \n                    schellingAgent.getLinks(Links.SchellingToEnvironmentLink.class).send(Messages.UnhappyMessage.class);  \n\t\t\t\t    }  \n\t\t\t\t});   \n\t\t\t}
\n

After updating the similarity of its neighborhood, each agent needs to decide whether to move or not. For this, the agent compares its neighborhood similarity to its similarity threshold and decides whether it is still happy in the current cell.\nIf the agent is unhappy, it will send a message to the environment indicating that it would like to move.

\n
\n

Messages.java

\n
\n
   public static class UnhappyMessage extends Message.Empty {}
\n

The UnhappyMessage is an empty message, as no additional information is needed besides the agent's wish to move cells.

\n

Environment#moveAgents

\n
\n

Environment.java

\n
\n
public static Action<Environment> moveAgents() {  \n    return Action.create(Environment.class, environment -> {  \n        ArrayList<Long> unhappyAgents = new ArrayList<>();  \n\t    environment.getMessagesOfType(Messages.UnhappyMessage.class).forEach(msg -> unhappyAgents.add(msg.getSender()));  \n\t    Collections.sort(unhappyAgents);  \n\t    Collections.shuffle(unhappyAgents, environment.random);  \n\t    environment.unhappyAgentCount = unhappyAgents.size();  \n        unhappyAgents.forEach(agentID -> {  \n                    AgentState.AgentRace race = environment.agentMap.get(agentID).race;  \n\t\t\t\t    Optional<Cell> optionalCell = environment.grid.cellList.stream().filter(x ->  \n                            !x.occupied && environment.calculateSimilarityMetric(x.coordinates, race)>= environment.getGlobals().similarityThreshold).findAny();  \n\t\t\t\t    if (!optionalCell.isPresent())  \n                        return;  \n\t\t\t\t    Cell oldCell = environment.agentMap.get(agentID).position;  \n\t\t\t\t    oldCell.vacate();  \n \t\t\t\t    Cell newCell = optionalCell.get();  \n\t\t\t\t    newCell.switchState(race);  \n\t\t\t\t    environment.agentMap.get(agentID).changePosition(newCell);  \n\t\t\t    }  \n        );  \n  });  \n}
\n

The environment will receive messages from all agents that wish to move their cell. Based on this list of agents, the environment aims to find an appropriate cell available for each agent. This means the environment goes through the list of empty cells and evaluates whether this empty cell is in line with the similarity requirements of the agent. If a suitable cell is available, the environment indicates this to the agent and the agent moves to the new location.

\n

Environment#writeData

\n

At the end of each tick, the configuration of the 2-d grid is saved to enable exporting data for additional analysis outside the SDK.

\n
   public static Action<Environment> writeData() {  \n        return Action.create(Environment.class, environment -> {  \n            environment.dataOutput.addDataValue(environment.getContext().getTick(), new DataValue(environment.grid.cells));  \n      });  \n    }
\n

Environment#exportJSONOutput

\n

At the end of the simulation (i.e. on the last tick), the data is exported as JSON file.

\n
\n

Environment.java

\n
\n
  public static Action<Environment> exportJSONOutput() {  \n        return Action.create(Environment.class, environment -> {  \n            try {  \n                PrintWriter pw = new PrintWriter(\"Grid_History.json\");  \n\t\t\t    pw.write(environment.dataOutput.gridHistory.toString());  \n\t\t      pw.flush();  \n\t\t      pw.close();  \n\t\t      } catch (FileNotFoundException e) {  \n                e.printStackTrace();  \n\t\t      }  \n        });  \n    }
\n

The data export enables to further analyze the simulation data in any data science tool of choice.

\n

Analyzing data output in Jupyter Notebook

\n

After having exported the simulation data as JSON file, this provides us with a great opportunity to exemplify how to conduct more detailed analysis of the simulation by pulling the data into an external analysis tool. In this example, we will use a Jupyter Notebook to analysis and visualize this data.

\n

The JSON file contains information about the 2-d grid at every tick. In the Jupyter Notebook we load in the JSON file and animate the change in the position of agents over time.

\n
    import numpy as np\n    import pprint\n    import matplotlib.pyplot as plt\n    import matplotlib\n    from IPython.display import HTML\n    import matplotlib.patches as mpatches\n    import matplotlib.animation as animation\n   \n    with open('GridHistory.json') as f:\n    \tdata = json.load(f)\n    time_steps = [int(step) for step in data.keys()]\n    grid_idx = [int(idx) for idx in data[str(time_steps[0])].keys()]\n    grid_history = np.array([[[0 for k in range(len(grid_idx))] for j in range(len(grid_idx))] for i in range(len(time_steps))]) \n    \n    for t in time_steps:\n        for i in grid_idx:\n            for j in grid_idx:\n                grid_history[t, i, j] = int(data[str(t)][str(i)][str(j)])\n    \n    im1=grid_history.shape\n    values = np.unique(grid_history.ravel())\n    \n    fig=plt.figure(figsize=(8, 8))\n    \n    cmap = matplotlib.colors.ListedColormap(['royalblue', 'lightgrey', 'red'])\n    schelling =plt.imshow(grid_history[0,:,:], cmap=cmap, interpolation='none')\n    colors = [schelling.cmap(schelling.norm(value)) for value in values]\n    patches = [mpatches.Patch(color=colors[0], label=\"blue agents\"), mpatches.Patch(color=colors[1], label=\"empty cells\") , mpatches.Patch(color=colors[2], label=\"red agents\")]\n    plt.legend(handles=patches, bbox_to_anchor=(0.8, 0),\n              ncol=3, fancybox=True, shadow=True)\n    plt.grid(True)\n    plt.axis('off')\n    \n    def animate_noise(i):\n        schelling.set_array(grid_history[i,:,:])\n        return [schelling]\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

Summary

\n

In this tutorial we have walked through an implementation of the classic Schelling model. This is an example of how a geospatial component (2-d grid) can be incorporated within the SDK.\nIn this implementation, information about the 2-d grid is saved in the environment which communicates information about this grid to the Schelling agents. Based on this information, the Schelling agents decide whether to move cells or remain in their current cell. Through multiple iterations the model will show how people segregate based on their preferences for similarity. enter link description here

","headings":[{"value":"Model overview","depth":2},{"value":"Summary of the model implementation","depth":2},{"value":"Globals","depth":2},{"value":"Setup","depth":2},{"value":"Step","depth":2},{"value":"Behaviors","depth":2},{"value":"SchellingAgent#registerToEnvironment","depth":3},{"value":"Environment#receiveRegistrations","depth":3},{"value":"Environment#initPositions","depth":3},{"value":"Environment#updateAgentStates","depth":3},{"value":"SchellingAgent#updateState","depth":3},{"value":"SchellingAgent#step","depth":3},{"value":"Environment#moveAgents","depth":3},{"value":"Environment#writeData","depth":3},{"value":"Environment#exportJSONOutput","depth":3},{"value":"Analyzing data output in Jupyter Notebook","depth":2},{"value":"Summary","depth":2}],"frontmatter":{"title":"Schelling Segregation Tutorial","toc":true,"experimental":null}},"site":{"siteMetadata":{"title":"Simudyne Docs","latestVersion":"2.6"}}},"pageContext":{"absolutePath":"/home/vsts/work/1/s/content/2.5/docs/tutorials/schelling.md","versioned":true,"version":"2.5","kind":"docs","pagePath":"/tutorials/schelling","chronology":{"prev":{"name":"Mortgage Portfolio Tutorial","path":"/tutorials/mortgage"},"next":{"name":"SIR Epidemiology Tutorial","path":"/tutorials/sir"}},"lastUpdated":"2026-04-21T13:56:54.858Z"}}