Project 3: Graph Search

Version 10/20/16

Educational Objectives: After completing this assignment, the student should be able to accomplish the following:

• Define and implement graph classes
• Implement the adjacency list representation for a graph
• Design and implement graph algorithms operating on a standard graph interface
• Accurately describe the Depth First Search [DFS] algorithm
• Accurately describe the Breadth First Search [BFS] algorithm
• Efficiently implement DFS operating on a standard graph API
• Efficiently implement BFS operating on a standard graph API
• Analyze the runtime and runspace requirements of DFS on adjacency list representations
• Analyze the runtime and runspace requirements of BFS on adjacency list representations
• Analyze the runtime and runspace requirements of DFS on adjacency matrix representations
• Analyze the runtime and runspace requirements of BFS on adjacency matrix representations
• Design and implement an isomorphic representation of rectangular mazes as graphs
• Apply graph search algorithms to the solution of maze problems

Operational Objectives: Design, implement, and test various graph algorithms using the Graphs framework. Apply these algorithms to solve maze problems.

Deliverables: Three files with contents as follows:

filename            items requiring completion
--------            --------------------------
survey_util.h       Postorder
graph_util.h        OutDegreeDistribution, Path_BFS, Path_DFS
log.txt             work log

Graph Framework

The fsu Graph Framework consists of a number of classes, utility functions, and test harnesses. The following is a brief description of the files and their contents. These are discussed in considerably more detail in a companion guide.

FSU Graph Framework
Filename	Contents
graph.h	Class templates ALUGraph, ALDGraph. These implement adjacency list representations for undirected and directed graphs, respectively.
bfsurvey.h	Class template BFSurvey. This class implements breadth-first survey as described in lecture notes. Important engineering details are implemented that are not discussed in the class notes.
dfsurvey.h	Class template DFSurvey. This class implements depth-first survey as described in lecture notes. Important engineering details are implemented that are not discussed in the class notes.
graph_util.h	A number of stand-alone functions assisting clients of the graph classes, including Load, Save, InDegreeFrequencyDistribution, ShowAL, Path_BFS, Path_DFS, and CheckSymmetry, along with several functions specifically supporting the test harnesses.
survey_util.h	Stand-alone functions primarily supporting the test harnesses for graph surveys. Includes Levelorder, Preorder, Postorder, and WriteData.
topsort.h	Function template TopSort implementing the Knuth topological sort algorithm.
fgraph.cpp	Client test harness for graph class templates. Arguments: (1) graph file (req), (2) log file (opt)
fbfsurvey.cpp	Client test harness for BFSurvey class template. Can be configured for either undirected or directed graphs. Arguments (all req): (1) graph file, (2) 'f'/'s' (full or single search), (3) start vertex number, (4) 1/0 (trace/no-trace).
fdfsurvey.cpp	Client test harness for DFSurvey class template. Can be configured for either undirected or directed graphs. Arguments (all req): (1) graph file, (2) 'f'/'s' (full or single search), (3) start vertex number, (4) 1/0 (trace/no-trace).
fpath.cpp	Client test harness for Load, Path_BFS and Path_DFS. Reads graph file and displays BFS and DFS paths from x to y. Does both undirected and directed graphs. Arguments (all req): (1) graph file, (2) from vertex, (3) to vertex.
ftopsort.cpp	Client test harness for TopSort function template. Argument: (1) graph file (req)
Maze Apps
maze_util.h	Functions supporting the study of mazes using the graph framework, including LoadMaze and Maze2Graph
solvemaze.cpp	Client test harness for Path_DFS, CheckSymmetry, and LoadMaze. Reads maze file, checks for consistency, solves the maze, and appends solution in maze file with ".dfs" extension. Argument: (1) maze file (req).
maze2graph.cpp	Client test harness for Maze2Graph. Reads maze file, writes graph file containing directed graph model of maze. Graph file same as maze filename with ".dg" extension. Arguments: (1) maze file (req), (2) 1/0 (directed/undirected) (optional - default is directed)
printmaze.x	Executable. Creates postscript file from maze file (with solution). Useful to print graphics and to include graphics in pdf documents. Use with file redirect, and be sure to write to a file with ".ps" extension. (Written by Bret Whissel.)
ps2png.sh	Executable. Converts postscript file to png file for visual display. Assumes "$1.ps" and writes "$1.png". Argument: (1) .ps filename without ".ps" extension (req)
mazemaster.x	Executable. Menu-driven maze analysis tool. Argument: command file (optional)

Please note: It is very important to understand all of the code listed above in complete detail and as it fits into the theory discussed in the lecture notes. Mastery of this software is part of the assignment.

Procedural Requirements

1. Begin by copying all files from LIB/proj3 into your proj3 directory. All of these files require your familiarization with code, in conjunction with reading from the lecture notes.

   In addition you will want to copy the following executables:

   fgraph.x
   ftopsort.x
   fbfs_ug.x
   fbfs_dg.x
   fdfs_ug.x
   fdfs_dg.x
   

   After completing the project, You should be able to create these with the distributed makefile, but you should become familier with them while preparing your knowledge for the project. All of the executables are important to use to assist in understanding graphs and graph search algorithms.

   You may also want to copy some or all of the files from the graph framework, located in LIB/tcpp, since you will need to understand them in detail. If you copy these library files, be sure your code does not depend on these files being located in your project directory - that will not be true in your portfolio.

2. Maintain your work log in the text file log.txt as documentation of effort, testing results, and development history. This file may also be used to report on any relevant issues encountered during project development.

3. Create the deliverables listed above conforming to the requirements and specifications below.

4. When logged in to shell or quake, submit the project by executing "submit.sh deliverables.sh". Read the screen and watch for processing errors.

   Warning: The submit process does not work on the program and linprog servers. Use shell or quake to submit projects. If you do not receive the second confirmation with the contents of your project, there has been a malfunction.

Code Requirements and Specifications

1. The official development | testing | assessment environment is g++ -std=c++11 -Wall -Wextra on the linprog machines. Code should compile without error or warning.

2. Algorithms should be fully compatibility with the fsu graph framework as released in the course library and should use that library whenever possible. Re-inventing the various features and components of the library is not appropriate.

3. Graph and Maze file specifications, as given in the course notes and previous assignments, should be adhered to.

4. Where appropriate, algorithms should be tested on both undirected and directed cases. Note that a number of examples are given, and the graph file format can be interpreted as both undirected and directed graph.

5. OutDegreeDistribution

   Use the following header:

   template < class G >
   void OutDegreeDistribution (const G& g, size_t maxToDisplay = 10, std::ostream& os = std::cout)
   

   Collects degrees in a vector and presents "top 10" after sorting.

6. Path_BFS

   Use the following header:

   template < class G >
   bool Path_BFS (const G& g, typename G::Vertex x, typename G::Vertex y, fsu::List<typename G::Vertex>& p)
   

   Applies BFSurvey to graph g, calculates BFS path from x to y and stores result in list p. Uses error stream to report errors, otherwise does no I/O. Returns true/false whether path exists.

7. Path_DFS

   Use the following header:

   template < class G >
   bool Path_DFS (const G& g, typename G::Vertex x, typename G::Vertex y, fsu::List<typename G::Vertex>& p)
   

   Applies DFSurvey to graph g, calculates DFS path from x to y and stores result in list p. Uses error stream to report errors, otherwise does no I/O. Returns true/false whether path exists.

8. Postorder

   Use the following header:

   template <class G>
   void Postorder (const fsu::DFSurvey<G>& dfs, std::ostream∓ os)
   

   Prints vertices in finishing order.

9. log.txt

   In addition to your work log, use this text file to report on testing and other experieneces. Also describe how you chose to visualize the reults of your maze generator/solver system (see hints below).

Hints

• A makefile is part of the distribution. You will need to un-comment one of the two ways to create ranmaze.x. Use the first method if possible.

• The functionality for solvemaze.cpp is embodied in LoadMaze, CheckSymmetry, and Path_DFS, some of which you are supplying. The client itself is supplied and should not be modified, because we will use the same client in our testing.

• Similarly, functionality for fpath.cpp is embodied in Path_DFS and Path_BFS which you supply.

• Finally, functionality for the finishing order portion of the survey tests is embodied in Postorder which you supply. These client tests are supplied and should not be modified.

Fun with Mazes

• The following maze was generated by ranmaze with solution (red to green) obtained using Path_DFS in the graph model.

  

• If you have web space on ww2.cs.fsu.edu, you can set up a quick maze viewer as follows:

  1. Put a script "mazegen.sh" in your space with contents:

     #!/bin/sh
     ranmaze.x $1 $2 _TEMPMAZE
     cp _TEMPMAZE.1 maze$1x$2.1
     solvemaze.x _TEMPMAZE.1
     printmaze.x -h12 -w12 < _TEMPMAZE.1.dfs > _TEMPMAZE.ps
     pstopnm -stdout -yborder=0 -xborder=0 -portrait -xsize=1000 _TEMPMAZE.ps |
           pnmtopng > maze.png
     chmod 644 maze.png
     rm _TEMPMAZE*
     echo "maze graphic in maze.png"
     

  2. Make a simple web page "viewmaze.html" with contents as follows:

     <html>
     <head>
     <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=windows-1252">
     <title>ViewMaze</title>
     <style type = "text/css"></style>
     </head>
     <body link="black" vlink="black" alink="#808080">
      <br>
     <blockquote>
     <IMG SRC="maze.png" ALT="maze.png"><br>
     Maze generated by ranmaze. Solution obtained using Path_DFS in graph model.
     </body>
     </html>
     

  3. Put copies of solvemaze.x and printmaze.x in the same directory.

  4. Change permissions of *.x and *.sh to 700.

  5. Change permissions of viewmaze.html to 644.

  Then running "mazegen.sh $1 $2" followed by a refresh of the page will display the newly generated maze.

Graph Survey Study Experiment Guide

• Even though our typical use of these classes will have the template argument N = size_t, it will be very useful in your implementation code to distinguish between type Vertex and type size_t and carefully cast between the two when the two types have different connotations. For example, if Vertex x and size_t i, then Begin((Vertex)i) and parent[(size_t)x].

• Several graph files are distributed in LIB/proj3. Some of these are named graph.v.e and some are named dag.v.e, where v is the number of vertices and e the number of edges of the graph represented by the file. DO NOT rely on these suffixes in your programs, they are for human convenience only (and in some instances may not even be accurate). Those named dag are purported to be acyclic when interpreted as directed graphs, but may have cycles when interpreted as undirected graphs.

• A thorough understandiing of the material on the Graphs 1 Lecture Notes will be helpful.

• Sample executables are created using the distributed makefile. These show some elaborations such as digraphs, topological sort for digraphs, and output from the surveys that isn't direct. I added discovery time to BFSurvey, which is handy information to have, as illustrated by the post-survey computation of discovery order. Decode the names as follows:

  fgraph.x   # general test of Graph classes  - can supply detailed log
  fdfs_ud.x  # functionality test of DFSurvey - undirected graphs
  fdfs_dg.x  # functionality test of DFSurvey - directed graphs
  fbfs_ud.x  # functionality test of BFSurvey - undirected graphs
  fbfs_dg.x  # functionality test of BFSurvey - directed graphs
  ftopsort.x # functionality test of TopSort  - directed graphs only
  fpath.x    # functionality test of Path_BFS and Path_DFS in both un- and di- graphs
  

• The following is output from a test of DFSurvey run on G1 (undirected case):

  linprog2> fdfsug.x graph1.10.10
  
  Begin DFSurvey functionality test
  graph type: undirected adjacency list
   Load complete
   Input file: graph1.10.10
    VrtxSize = 10
    EdgeSize = 10
  
     df survey data
     ==============
     vertex     dtime      ftime      parent        color
     ------     -----      -----      ------        -----
          0         0         19        NULL            b
          1         1          2           0            b
          2         6         15           5            b
          3         3         18           0            b
          4         4         17           3            b
          5         5         16           4            b
          6         7         14           2            b
          7         8         13           6            b
          8        10         11           9            b
          9         9         12           7            b
  
  Vertex discovery order: 0 1 3 4 5 2 6 7 9 8
  Vertex finishing order: 1 8 9 7 6 2 5 4 3 0
  
  End DFSurvey functionality test
  linprog2>
  

  Note the table of survey data and the output of the vertices in preorder and postorder.

• The following is output from a test of BFSSurvey run on G1 (directed case):

  linprog2> fbfsdg.x graph1.10.10
  
  Begin BFSurvey functionality test
  graph type: directed adjacency list
   Load complete
   Input file: graph1.10.10
    VrtxSize = 10
    EdgeSize = 10
  
     df survey data
     ==============
     vertex  distance      dtime      parent        color
     ------  --------      -----      ------        -----
          0         0          0        NULL            b
          1         1          1           0            b
          2         0          7        NULL            b
          3         1          2           0            b
          4         2          3           3            b
          5         3          4           4            b
          6         1          8           2            b
          7         2          9           6            b
          8         4          5           5            b
          9         5          6           8            b
  
  Vertex discovery order: 0 1 3 4 5 8 9 2 6 7
     grouped by distance: [ ( 0 ) ( 1 3 ) ( 4 ) ( 5 ) ( 8 ) ( 9 ) ] [ ( 2 ) ( 6 ) ( 7 ) ]
  
  End BFSurvey functionality test
  linprog2>
  

  Again the table shows the survey data. The vertex discovery order, grouped by distance from the search vertex, is also shown. (BFS discovers and finishes vertices in the same order.) The discovery order grouped by distance uses [ ] to delimit trees in the forest and ( ) to delimit vertices the same distance away from the root of the tree.

• The discovery and finishing order are computed post-survey from the timestamps. (Discovery time was added to the usual BFS to facilitate this.) The discovery order "grouped by distance" output in fbfsurvey uses both distance and time. One could also output a Lisp-syntax record of the search forest for either survey.