Homework 3, A Sable Match.

Short Description:

Write and test a program that will perform stable matching.

This assignment is worth 80 points.

60 points for a properly functioning program.
20 points for the spreadsheet and report.

Goals

When you finish this homework, you should have:

Performed an efficient implementation of the Gale Shapley Algorithm.
Performed an empirical study to demonstrate your implementation is efficient.

Formal Description

Implement the Gale Shapley algorithm to find a stable match in a dataset. Your program should be implemented with women proposing to men.

Input

Your input should come from a file. The file name will be specified as argv[1] and will contain

An integer $n$ representing the number of people in each category (men and women)
- Both men and women are represented by a number $i \ni 0 \le i \lt n$.
$2n$ lines of data each containing $n$ integer entries.
The first $0 \le i \lt n$ lines represent the preference choice for man $i$, ranked high to low.
The next $n \le i \lt 2n$ lines represent the preference choice for woman $i$, ranked high to low.

The file data1 is an valid example input file corresponding to one of the examples from class.

You do not need to be overly concerned about the file name, the following code should be sufficient to open the file:

int main(int argc, char * argv[]) {
     ifstream inFile;
     if (argc !=2 ) {
         cout << argv[0] << " datafile" << endl;
         return 1;
     } else {
         inFile.open(argv[1]);
     }

You may rearrange this code to meet your style preferences.

Your program should find a stable match and print that to standard out in the following format:

An integer $n$ representing the number of people in each category (men and women)
$n$ lines containing the matches found
Each line $i$ should contain
- The id of the man in match $i$
- A space
- The id of the woman in match $i$

An example output file is MatchData1 but this was produced by the men proposing from data1 above, so you might not get this result. In fact, I am pretty sure the last two matches should be different.

I have written a program that checks to see that a match is stable. The executable is located at ~dbennett/385/hw3/checker on cslab103. This executable is compiled to run on this platform and will probably not run elsewhere. The command line arguments are the match file and the datafile, where the match file is the output of the stable match program and the data file is the input to the stable match program.

 
./checker MatchData1  data1

If all is well, checker exits silently. If there is a problem it reports the first unstable match it finds. This program may not be completely correct, and will probably break under extreme test conditions.

This directory also contains code for a data set generator called maker.cpp. This program takes a single command line argument, the size of the input, and produces a random test case.

Timing your code

I used the following additions to my program to produce the time taken by the GS function

#include <chrono>
     auto start = chrono::high_resolution_clock::now();
     GS(men, women);
     auto end = chrono::high_resolution_clock::now();
     chrono::duration<double> diff = end - start;
     cerr << diff.count() << " " ;

I printed to cerr so the output does not get written to the output file on redirection.

To perform the timing tests, I used a script called runner.sh this is a bash script and it will run your program over a set of input values. Be cautioned this will take a while. I run the script with:

bash runner.sh > time.txt

This will produce a file time.txt. Each line begins with the size of the input file and then has the time results for 40 runs at each size. You may need to add ./ before program names, remember I have that automated in my shell. Runner.sh assumes that your program is called stable. You can call the program whatever you wish, but you need to edit runner.sh and change the name.

Using runner will produce a set of files called data.nnnIN and data.nnnOUT, the results of the maker and stable program.

If you have problems with the previous section, please see me. This will take some time so please do not let this for 11:00pm on the due date.

Analysis of your run should be performed in a spreadsheet. You should

Label the columns as you work
- N, t1, t2, .... t40 will do for the raw data.
Compute the average time $t$ for each different input size, $n$.
Compute $\frac{t}{n}$, $\frac{t}{n^2}$ and $\frac{t}{n^3}$ for all input sizes.
Graph $n$ on the x axis vs $t$ on the y axis

Create a word document and

Provide a discussion of your implementation.
- Describe, discuss and justify your choice of data structures.
- Discuss any other interesting implementation details.
Present your data (spreadsheet)
Present your graph
If you wish, draw some other graphs as well, lg(n) vs log(t) might be interesting.
Provide an interpretation of your data.
Discuss why you think your implementation is $O(n^2)$.

Discussion

You may use vectors for this program.

Your program must compile and run on cslab103 without errors or warnings using the following command line flags:

CXXFLAGS = -g -O3 -Wpedantic -Wall -Wextra -Wmisleading-indentation -Wunused -Wu
ninitialized -Wshadow -Wconversion -Wfloat-equal -Wparentheses -Wunreachable-cod
e -std=c++17

Required Files A single tar or zip file containing the source code, Makefile, spreadsheet, and word document for this program.

Submission

Submit the assignment to the D2L folder homework 3 by the due date.