Project 3: RanMaze

Random Maze Generation using Partition

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

Describe and elucidate the API for the Partition class
State and give intuitive arguments for the asymptotic runtime of Partition operations
Describe the supporting data structure for Partition
Explain how Union is implemented
Explain how Find is implemented without path compression
Explain how Find is implemented with path compression
Define a Maze
Define and explain the Walls Code used to define cells in a Maze
Define and explain the concept of self-consistency in a maze file
Explain how Maze relates to Graph
Explain how DFS or BFS can be applied to a Maze problem
Use Partition as a bookkeeping device to generate random mazes

Operational Objectives: Implement the Partition class and a client program that generates random mazes.

Deliverables: Two files:

partition.h  # contains template < typename N > class Partition
ranmaze.cpp  # client program of Partition <> generating random mazes

Procedural Requirements

The official development, testing, and assessment environment is g++47 -std=c++11 -Wall -Wextra on the linprog machines. Code should compile without error or warning.
Begin by copying the following files from the course directory into your proj3 directory:
```
LIB/proj3/fpartition.cpp        # test harness for Partition
LIB/proj3/makefile              # builds most executables
LIB/area51/fpartition.x         # sample executable
LIB/area51/ranmaze.x            # sample executable
LIB/area51/mazemaster.x         # maze analyzer
```
Execute ranmaze.x to generate maze files and mazemaster.x to analyze the resulting maze files. You will follow the same process in testing your own ranmaze and its resulting maze files. Also pay careful attention to the detailed I/O behavior of ranmaze, this is how your program should behave.

Create the file partition.h containing the definition and implementation of template<typename N> Partition. Test your class thoroughly using the supplied fpartition.cpp.

Create the file ranmaze.cpp, a client of Partition<>. Using mazemaster.x, test thoroughly to be sure the mazes it generates are self-consistent and that the behavior mimics that of LIB/area51/ranmaze.x, including the file name extensions for output files.

Check that ranmaze.cpp and Partition<> meet the specifications given below.

Copy the file LIB/proj3/proj3submit.sh into your project directory, change its permissions to executable, and submit the project by executing the script.

Warning: Submit scripts do not work on the program and linprog servers. Use shell.cs.fsu.edu 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 - Partition

Use the API defined by the following:

namespace fsu
{
  template < typename N = size_t >
  class Partition
  {
  public:
    explicit Partition     ( N size );       // create singletons {0} .. {size-1}
    void     Reset         ();               // reverts to singletons
    void     Reset         ( N newsize ); 
    void     PushSingleton ()                   { parent_.PushBack((N)parent_.Size()); rank_.PushBack(0); }
    void     Union         ( N x , N y )        { Link(Root(x),Root(y)); }
    bool     Find          ( N x , N y )        { return Root(x) == Root(y); }
    bool     Find          ( N x , N y ) const  { return Root(x) == Root(y); }

    size_t   Size          () const             { return rank_.Size(); }
    size_t   Components    () const;
    void     Display       ( std::ostream& os ) const;
    void     Dump          ( std::ostream& os ) const;

  private: // methods
    N    Root   ( N x );                // path compression changes state
    N    Root   ( N x ) const;          // no path compression
    void Link   ( N root1 , N root2 );  // union assuming arguments are roots

  private: // objects
    fsu::Vector <N> parent_;
    fsu::Vector <N> rank_;
  };
  ...
} // fsu

Follow the implementation started here. This is distinct from that of the lecture notes in that

N is assumed to be an unsigned type
Root nodes are recognized by (parent_[i] == (N)i)
Rank/height info is maintained in the separate vector rank_. Recall this starts out as the height of the tree rooted at i but is not maintained once i ceases to be a root in the forest.

Only a few key implementations are lacking.

Be sure that you implement path compression in the non-const version of Root. Of course, you will be forced to use the non-compression version for the const version of Root.
Use the distributed example executable area51/fpartition.x to see what behavior is expected from Display() and Components(). Because Dump() should display the internal data of the structure, which is of course different from that in the distributed example, you should consult the discussion forum to agree with other students on this behavior.

Code Requirements and Specifications - ranmaze

Output maze files according to the spec in the Union-Find notes Appendix: Maze Technology. Take care that all maze files are syntactically and semantically correct - mazemaster.x is helpful in testing your output.
The maze file should have the start as cell at the beginning (left-most cell) of the middle row and the goal at the end (right-most cell) of the same row.
ranmaze should expect three command line arguments: number of rows, number of columns, and filename.
ranmaze should output two versions of the random maze: (1) the first time goal is reachable from start, output the maze to the file "filename.[components]" where [components] is the actual number of components in the maze; and (2) after all cells are reachable from start, output the maze to the file "filename.1".
Take care that your mazes are correctly "random" in the sense that all walls have the same probability of being selected for inspection at each step. This is mostly a matter of judicious design, especially at boundary cases. For example: be sure that a cell face on an interior cell has the same chance of selection as a cell face of a boundary cell, where fewer faces are eligible.

Hints - Partition

The Partition constructor needs to call the correct Vector constructors in order to get the representation initialized to singletons:
```
Partition::Partition ( N size ) :  parent_((size_t)size, 0) , rank_((size_t)size, 0)
{
  // loop setting parent values
}
```
Be sure to explicitly cast when mixing the two types N and size_t.
Use the distributed executable area51/fpartition.x to see the expected behavior of Components and Display.
The Display method is somewhat involved. The solution compiled as part of area51/fpartition.x uses two data structures:
```
fsu::Vector < N > rootorder(Size(),(N)Size());
fsu::Vector < fsu::List < N > > setlist (components);
```
and about 20 lines of code. If you are unable to get this working correctly, just output "Display not implemented\n" so your code will run, and we'll take off 5 points.

Hints - ranmaze

A very handy way to generate unsigned integers is with the fsu random object generator. Include these files:

#include <xran.h>
#include <xran.cpp>

and declare an object and use it like this:

fsu::Random_unsigned_int ran;
...
x = ran(a,b); // x is a random unsigned int in the range a <= x < b
y = ran(0,4); // y is a random choice of 0,1,2,3 (N,E,S,W)
z = ran(0,2); // z is a random choice of 0 or 1 (coin flip)

This generator uses the Marsaglia KISS generator as its underlying engine.

An effective way to organize ranmaze.cpp is to write a function

void Connect(
              size_t beg , size_t end ,            // start and goal cells
              size_t numrows, size_t numcols,      // maze dimensions
              fsu::Vector<unsigned char>& maze ,   // walls codes for cells
              fsu::Partition<size_t>& p            // tracks component structure
            );

that can be called from main() once for the "first pass" maze and subsequently as often as needed for the "one component" maze. Note that the maze data and partition data are passed by reference so that modifications made in a call to Connect will affect the data in the calling process. The organization is then left to function main:

int main (int argc, char* argv[])
{
  ...
  size_t numcells = numrows * numcols;
  size_t numcells = numrows*numcols;
  start = ??;
  goal = ??;
  fsu::Vector<unsigned char> maze (numcells, 15);   // all closed boxes
  fsu::Partition<size_t> p (numcells);              // all singletons

  // ensure goal is reachable from start:
  std::cout << " components after 0 passes:   " << p.Components() << '\n';
  Connect (start, goal, numrows, numcols, maze, p);
  size_t components = p.Components();
  std::cout << " components after 1 pass:     " << components << '\n';
  if (components > 1)  // output intermediate result the first time goal is reachable
  {
    // build filename filec
    ...
    // output first pass maze
    out1.open(filec);
    WriteMaze(out1, start, goal, numrows, numcols, maze);
    out1.close();
    out1.clear();
    std::cout << "1-pass maze written to file " << filec << '\n';
  }

  // continue until all cells are reachable
  if (components > 1)
  {
    for (size_t cell = 1; cell < numcells; ++cell)
    {
      Connect (0, cell, numrows, numcols, maze, p);
    }
  }
  std::cout << " components after all passes: " << p.Components() << '\n';
  out1.open(file1);
  WriteMaze(out1, start, goal, numrows, numcols, maze);
  out1.close();
  out1.clear();
  std::cout << "n-pass maze written to file " << file1 << '\n';
  ...
}

Building the filename is just the metedious [meticulous + tedious] work of creating the correct size null-terminated character array and putting all the characters in the right place. You need two such file names "filec" and "file1" each of which is the user input filename "file" with an extension appended. To get the extension for filec, unfortunately there is no "itoa" in the library, so you need the number of digits = 1 + (size_t)log10(components) and a loop that finds the digits:
```
  for (size_t i = 0; i < digits; ++i)
  {
    char digit = '0' + (char)(components % 10);
    // put this digit in the correct place in filec
    components /= 10;
  }
```
This loop calculates the digits. You have to put them in the correct place in the file name array. Don't forget the null terminator. (You can also use std::stringstream if you prefer.)

Here is a way to get srated on the main program, including the handy constants for four atomic walls:

  const unsigned char NORTH = 0x01;
  const unsigned char EAST  = 0x02;
  const unsigned char SOUTH = 0x04;
  const unsigned char WEST  = 0x08;
  ...
  int main (int argc, char* argv[])
  {
    if (argc < 4)
    {
      std::cout << "** command line arguments required:\n"
                << "   1: number of rows\n"
                << "   2: number of cols\n"
                << "   3: file name for maze\n"
      return 0;
    }
    size_t numrows = atoi(argv[1]);
    size_t numcols = atoi(argv[2]);
    ...
  }

The wall constants are global, hence accessible from Connect()

Note that the supplied makefile has targets fpartition.x, ranmaze.x, and mazemaster.x.