Project 1 - Segregation

Submission Due: Monday November 16, 2015, 11:59PM

Learning Objectives
Using the C language, you will learn and practice the following on this project:

command line argument processing

I/O: input processing and output using cursor-controlled graphical displays
structures, array and matrix operations, argument passing and pointer syntax for
arrays
random number generation and basic statistics.

Problem Introduction
Segregation by economic levels has always been a part of cultures. In the United States,
there is also segregation by race as a consequence of the history of slavery, despite long
term attempts to desegregate.
It turns out that segregation happens even when people are happy living in a diverse
community. In 1969 an economist, Thomas Schelling, wrote Models of Segregation in
which agents moved based on how happy they were with their neighbors. He showed
that polarized population distributions (i.e. segregation) happen when one subgroup of
the population is much larger than another, as is the case with white and black
Americans. One of the curious simulation results however, was the discovery that
segregation happened despite programming the agents to be happy with, and accept a
high diversity of, their neighbors.
The Quantitative Economics web site has a description of Schelling's model based on
points in two dimensional space. Professor Scott Page has developed a Coursera Model
Thinking video lecture that presents Schelling's model; watch this for background and
details.
You will write a program that simulates the segregation model of Thomas Schelling
and experiment with running the program using various inputs to the measures of
population distribution and happiness. Your program will model locations based on a

grid of character locations, and it will simulate the segregation model of Schelling using
cursor controls to display characters.
Rather than represent race in this model, you will consider the simulation of varying
proportions of 'rich' and 'poor' agents.

How the Segregation Model Works

Two groups of agents are needed to partially fill a grid that represents a city grid of
locations where all agents reside (only one agent per grid location). Using empty space
for vacant, and 'X' and 'O' for the classes of agent, an initial, set of 5 vacancies and 10
'X' and 10 'Y' agents might look like this:

Each agent calculates their happiness, or satisfaction, based on the percentage of

neighbors similar to them. In a grid implementation, the neighbors are the 8-way
connected neighbors.
There is a 'satisfaction threshold' that determines the point beyond which an agent
wishes to move to seek greater satisfaction. Each agent is either satisfied or unsatisfied
with the percent of like neighbors, and the possibilities below provide examples for the
case when the satisfaction threshold is 50%.

How the Simulation Cycles Work

The simulation runs as a potentially endless sequence of cycles. Each cycle measures
the happiness of each agent, moves agents who are unsatisfied (if possible), generates
a new arrangement and displays the new arrangement.
If the satisfaction of an agent is below the satisfaction threshold, then the simulation
moves the agent to one of the vacant locations in the city. The simulation does this for
every location that is occupied by an agent.
One possibility of moves for the given example is shown below. The left picture is the
'before', and the right is the 'after' -- the result of the cycle's moves. The agents marked
by the asterisk are unsatisfied and move to the new locations shown in the right picture.

Requirements
Example Interactive Mode Program Display
For this assignment, the 'rich' are the '+' characters. Your solution must use the '+'
character for the 'rich' agent symbol. The 'poor' are the '-' characters. Your solution
must use the '-' character for the 'poor' agent symbol. The vacant locations in the city
grid are '.' characters. Your program should look like the following example when run
with this command:
$ segregation 20 50 10 75
++.+.+--++++++-.+.++
++.++++++-++-+-+--++
-+++--++-++---+++-++
++-.++-++-.++++++-.+
+++.+++-++-++-++++-++++++++-+++.+++++++
++++-.+++++-++-+.+++
-+++.+++++++-.+++.++
+-+++++++++.+++--+-+
++-++-++++.-++++.+.+++-+-++-++++++++-++
---.++++-++.--++++-+
-++-++++--+-++--+++.
+-++.+++++-+++.+.++.
.+++++-+.++.++-++-.-++.+++-+--++.-+++-+
-+--+++-+++--++-++++
-.++.+.+-.++-+++.++.
+---+-+++++-+-+-+++++++-+++.+++++.+-+-+
cycle: 0
moves this cycle: 0
segregation measure: 0.6190
state: paused
(/)stop/go, (.)step (r)eset, (s)at N, (v)ac N, (p)rop N, (q)uit, (i)nfo,
(h)elp
>

In interactive mode, the lines under the display of the city grid of vacant, 'rich' and
'poor', contain this information:

the cycle of the simulation, which starts at cycle 0 -- the initial state.
the number of agents moved during the latest cycle.
the segregation measure records the degree of segregation present in the
simulation. (see the section 'The Segregation Measure'.)

the state of the simulation -- 'running' or 'paused'. The simulation begins in

'paused' state, and the user can step one cycle or start/stop its running of multiple
cycles at a time.
a list of user command instructions available. (see the section 'Runtime User
Commands: Interactive Mode Inputs'.)
a prompt ('> ') where the user can enter a command.

Command Line Inputs

The program should run in one of two modes: interactive mode and print mode.
For the interactive mode(shown above), each simulation cycle appears in a cursorcontrolled terminal display, and the user may interact to control the simulation. With
cursor control, each cycle overwrites the previous cycle's output.
For the print mode (see the section 'Print Mode Program Run'), each simulation moving
cycle appears sequentially in a terminal display; the simulation prints one cycle after
the other, and the terminal screen scrolls the output.
There are several required command line arguments and one optional argument. By
convention, the usage message places brackets [] around optional arguments.
Below are some examples of running the program. Note that all required command line
arguments must be positive; values of 0 or negative are not accepted. On the other hand,
it is legal for -pN to have a 0 value.
$ segregation
usage: segregation [-pN] size satisfaction vacancy proportion
$ segregation 0
usage: segregation [-pN] size satisfaction vacancy proportion
$ segregation 22 50 10 75

The following are the command line arguments for the program. With the exception of
the -pN option, the order and number of command line arguments is fixed; the order
given is the required order, and all are required.

is the width of the grid in characters and the height in rows. The simulation
space is set to (size by size) locations that are either vacant or occupied by a
'rich' agent or a 'poor' one. The minimum size of the grid should be ( 5 by 5). The
maximum size of the grid should be (39 by 39).
satisfaction is the satisfaction threshold in percentage terms expressed as
an integer. For example, a satisfaction threshold of 60 means that each agent will
be happy/satisfied only if the percentage of its neighbors is 60%.
size

is the proportion of the simulation space that is vacant expressed as

an integer. The program receives this value and interprets it as the percentage of
the entire space (size by size) that is to be vacant.
vacancy

For example, a vacancy of 10 means that the percentage of vacant locations

is 10%. For grid sizes that are not evenly divisible by the percentage of vacancy,
use the integer-truncated value for the number of vacant locations. If the grid size
was 5 by 5, and the vacancy was 10, then the number of vacant locations should
be 2, which is 25 / 10 truncated.

is the proportion of the population that is 'rich' expressed as

an integer. The program receives this value and interprets it as a percentage. For
example, a proportion of 60means that the proportion of 'rich' agents is 60% of the
entire (size by size) space minus the number of vacant spaces.
-pN is the only optional argument, and it turns on non-interactive, print mode to
print output of N cycles of simulation rather than display using cursor control.
The value of N must be non-negative; a value of 0 simply prints the initial starting
state of the simulation and terminates.
proportion

The -pN may be entered either as -p N or -pN. For example, to get print 2
simulation steps, you could start the command line with either segregation -p 2
... or segregation -p2 ... to start the simulation run.

Runtime User Commands: Interactive Mode Inputs

The user may control the simulation when it runs in interactive mode. The user
commands available while the simulation is running or paused are described below.
(/)stop/go, (.)step (r)eset, (s)at N, (v)ac N, (p)rop N, (q)uit, (i)nfo, (h)elp

'/' makes the simulation run or pause.

'.' makes the simulation step through one cycle. This command sets the state to
'paused'.
'r' resets the simulation to cycle 0 in a paused state, and computes the satisfaction
measure for the new initial state.
's N' changes the satisfaction threshold to the value of N, which must be an
integer greater than 0 and less than 100. This is a live change to any current
running simulation; the program will simply begin using the new threshold.
'v N' changes the proportion of empty, vacant locations. The N must be an integer
greater than 0 and less than 100, and its value is the proportion of vacant cells in
the total grid. This is a reset change for any current running simulation; the

program will reset a running simulation to create a new cycle 0 with the given
percentage of vacant locations.
'p N' changes the proportion of 'rich' to 'poor' agents. The N must be an integer
greater than 0 and less than 100, and its value is the proportion of 'rich' in the
whole grid. (As with vacancy, the actual number of 'rich' is truncated if the whole
grid capacity is not evenly divisible.)
The proportion of 'poor' in the grid would be computed by the following:
number_poor = (size * size) - number_vacancies - number_rich

This is a reset change for any current running simulation; the program will reset
a running simulation to create a new cycle 0 with the given percentage of vacant
locations.

'i' prints the current settings of the simulation.

'q' terminates the simulation.

Live Change vs. Reset Change

The interactive mode can not always process user commands on the fly; some inputs
cause a reset change that restarts the simulation. A reset change will reset a running
simulation to create a new cycle 0 with the given percentage of vacant locations. For
a live change on the other hand, the program will simply begin using the new threshold.

Print Mode Program Run

In print mode, the user specifies the number of cycles to simulate and does not
control the simulation. The simulation simulates the specified number of cycles and
prints the result of each one to standard output sequentially. The simulation then
terminates.
Here is a link to an example print mode output. The example was produced by this
command:
$ segregation -p9 10 50 15 50

Program Operation and Processing

Your solution will need to do the following:
1. Get command line inputs, convert and store them to integers.

2. Initialize the simulation data structures using the values from the command line
inputs. If the command line option -pN is present, the program runs in print mode.
Otherwise the program runs in interactive mode.
3. Either run non-interactively:
o executing the given number of simulation cycles requested, and
o printing each cycle's result in sequence.
4. Or run interactively:
o displaying the initial simulation at cycle 0, and
o looping to:
Check for user command input waiting at most 4 seconds.
Handle user command inputs, if any, based on the state of the
simulation and the rules for the given command (remember that
some reset the simulation.). The loop and the program end if the
user indicates that they want to quit.
Perform a simulation move cycle and display the resulting grid and
associated information if the state is 'running' or a single-cycle step
was requested.

Requirement Details
This section has details on optional command line arguments, the grid layout, the
satisfaction measure, the move algorithm, the interaction loop, and more information
on output of the running modes.
Getting Optional Command Line Arguments
A useful way to process the command line option -pN is with the getopt function, which
processes command line arguments that begin with the minus (-) sign. The man -s 3
getopt command gives more information, and there is a demonstration program in the
course lecture materials.
Random Layout of the Grid
When the program starts, it has to initialize the grid so that the vacancies and 'rich' and
'poor' agents are randomly distributed through the grid according to the proportions
specified by the command line arguments.
In order to test your code against a reference result, you will need to use
the srandom library function with a specific seed value. You should use the value 41 as

the fixed seed value. That will produce consistent results during development and
testing.
Here is a code fragment showing what will be required.
#include <stdlib.h>
...
// code in function that does the initialization
...
random() ...
...
int main( int argc, char * argv[] ) {
...
srandom( 41 ); // please use 41 as a fixed seed value
...
}

You will need to define _BSD_SOURCE to use the random function. The man
random command gives more information.

-s

The Segregation Measure

It is useful to have a measure of the overall satisfaction of the whole community in the
city. Based on the satisfactions of all the agents, this can be used to compare different
simulations.
Professor Scott Page has developed a useful measure in a Coursera Model
Thinking video lecture; watch this and learn how to compute his measure of
segregation.
In a nutshell, Professor Page's measure is between 0.0 for perfect diversity (i.e. no
segregation) and 1.0 for absolute segregation.
The Move Algorithm
When the simulation moves an agent, it must choose a vacant location as the new
location. The rules for moving during a simulation cycle are as follows:
1. You cannot choose a location that is not vacant; you cannot 'bump' another agent
out of its location. The only place an agent can move into is a vacant location.
2. The only candidate locations for a destination are vacant locations available at
the start of a simulation cycle. This prevents an earlier move from becoming
'undone' by a later move.

You have to check that any move destination was available and vacant at the
beginning of the current move cycle. If the candidate move location was not
vacant at the start of the cycle, it is not a valid destination.
3. Each agent should move no more than once per cycle. If a vacant site was already
used by an earlier move, and an agent now occupies it, the cycle must not move
that agent again even if the agent is not satisfied with its new location.
You may choose your own algorithm for choosing a vacant while following the rules.
For example, you might choose:

the first vacant location as the move destination.

the last vacant location.
a random vacant location.
a vacant location whose satisfaction is greater than or equal to the agent's current
satisfaction.
some other algorithm? You should discuss other options with your instructor.

Note: You must document your move algorithm in your report.txt.

The Interactive Mode Simulation Loop
Running the interactive mode simulation loop involves handling user input that might
alter simulation settings while applying the move algorithm to every location in the
'city'.
What's complicated about the interactive mode loop is the need to check whether there
is input to process. If the code tries to perform any kind of input (e.g. fgets), the
simulation will block and stop the simulation's progress.
Getting select-ive
It happens that there is a utility function called select which checks if there is input (or
output) ready and returns a value that you can use to learn that input is available and
ready to get.
One of the parameters is a timeout value that limits the time spent in the select call. By
using a timeout, you can call the function, let it time out and check whether there was
input ready. If there was input, you can process it. Otherwise you can write the loop
code to perform the next cycle of moves and segregation measure calculations. The man
select command gives more information, and there is a demonstration program in the
course lecture materials.

A useful function for using select is the fileno function, which returns the file
descriptor for a stream such as stdin. You will need to define _POSIX_SOURCE to use
the fileno function. The man fileno command gives more information.
Interactive Mode Program Outputs
As shown earlier, the simulation output consists of the city grid and a sequence of lines
reporting or controlling the simulation. Interactive mode clears the terminal window
before starting display. Each cycle of the simulation begins the display with the grid
which appears as the first line of the terminal window in interactive mode. You should
use the supplied display.c to control the positioning of the cursor for the grid display.
After displaying the last line of the grid, interactive mode displays the simulation grid,
cycle, move and status information. Then it checks to see if there was a user command
input to process before looping again.
Print Mode Program Outputs
The print mode output is structurally similar to interactive mode, but outputs different
information. The print mode does not clear the screen, allow interactive input, or display
help prompts for user interaction.
The print mode prints the initial state of the simulation (display of the cycle 0 grid and
status information), followed by the N cycles of simulation in a sequence. With this
option, you can save the output to a file and examine the cycle-to-cycle changes to the
grid at a later time.
Below are some links to example print mode outputs; their names identify the command
line arguments used to produce the output. Use these examples as models for what
output structure and format your program should produce in print mode.

output-p9-10-50-15-50.txt
output-p7-9-40-15-60.txt
output-p9-5-50-10-65.txt

Program Error Outputs

The user may enter incomplete or incorrect values as command line arguments. The
program should send these error messages to the error output descriptor
called standard error: stderr.

When the user enters an incomplete set of arguments, then print the standard usage
message (shown earlier), and terminate with an error code returned to the operating
system.
When the user enters an incorrect value, the program should print information about
the problem, then print its standard usage message (shown earlier), and finally terminate
with an error code returned to the operating system.
Below is a list of the specific error messages that apply to different cases of incorrect
command line arguments. A value that represents a user-entered value is shown
as {vvv}.

size ({vvv}) must be an integer in [5...39]

satisfaction ({vvv}) must be an integer in [1...99]
vacancy ({vvv}) must be an integer in [1...99]
proportion ({vvv}) must be an integer in [1...99]

Here is a complete example for the case when the user entered 101 for the proportion
of 'rich' agents:
proportion (101) must be an integer in [1...99]
usage: segregation [-pN] size satisfaction vacancy proportion

Supplied Files

report-spec.txt:

outline of content for the report you must submit with your
program. This contains questions to answer regarding this assignment. The
format is plain text with linefeed line endings.
display.c: the implementation file. You must not change this file.
display.h: the header file that is the interface for functions that manipulate the
terminal window contents to clear the screen, position the cursor or output a
single character You must not change this file.

Grading
Your grade will be based on the program's functionality, style and documentation, and
your written report.

15% Implementing, populating and displaying the city grid.

15% Calculating and displaying the segregation measure.

10% Running the print mode simulation.
25% Calculating satisfaction and implementing the move algorithm.
15% Running the interactive mode simulation loop and handling user input to
alter the simulation settings.
10% Style and Documentation: The program code conforms to style and
documentation
guidelines
for
the
course
found
in C-StyleRecommendations.pdf.
10% Report: Complete your report following the instructions in reportspec.txt. Make your answers short (phrases or bullet points are preferred),
complete and thoughtful.

Submission
You are responsible for submitting these files:
1.
2.

segregation.c:

implements your simulation of Schelling's segregation model.

The file reports on your implementation and its status. It also
contains your answers to the questions that were posed in the supplied reportspec.txt.
report.txt:

When finished, submit your work on mycourses

segregation.c report.txt [other...]

Note that the [other...] represents optional additional .h and .c files which might be
part of your solution code.
To check your submission, you can use the try query command like this: