Matt Christie, 2014-2016

This set of modules was developed to explore a question about graphs and some
mathematical objects that can be generated from them. Here's the question:

Let G be a connected graph whose vertex set is {1, ..., n}. G can be traversed from a
starting node k according to some traversal algorithm (here, either breadth-first search
(BFS) or depth-first search (DFS)). Since G is connected, traversing the graph from
vertex k will produce a sequence of vertices k1, ..., kn where k1 = k. This can be
interpreted as a permutation of G's vertices, where 1 is mapped to k1, 2 is mapped to k2,
etc. Let this permutation be called a traversal permutation of G from vertex k.

Given a graph G, a subset of G's vertices S, and a traversal algorithm A,
what group is generated by G's traversal permutations from elements in S?

Let such a group be called a traversal group.

For the definition of a group:
https://en.wikipedia.org/wiki/Group_(mathematics)

See also:
https://en.wikipedia.org/wiki/Group_theory

### Installation ###

$ mkvirtualenv traversalgroup
$ cd /just/within/the/folder/traversalgroup
$ pip install -r requirements.txt
$ python setup.py install

Notes:

Don't rely on the setup script to correctly install dependencies; 
use pip directly with the requirements file.

The above uses virtualenvwrapper; using just virtualenv or no virtual
environment at all should work just fine too, although the exact commands
will look a little different (you'll need to add sudo in front of the
last two commands if you're not using a virtual environment). Google
pip, virtualenv, and virtualenvwrapper for more details.

### Generating data ###

Start generating traversal groups of graphs:

$ python -m traversalgroup <json-config-file>

Generate pictorial representations of graphs' traversal permutations
when the set of starting vertices is the entire vertex set {1, ..., n}:

$ python -m graphprint <json-config-file>

Each row in the picture represents a single traversal permutation, with
each colored cell in the row representing a vertex.

If the config file is not passed in the above commands, the scripts
will search for a config file with the name config.json in the current
working directory.

### Configuration ###

Example config file for traversalgroup:
{
    "db": "traversalgroup.db",
    "min_n": 3,
    "max_n": 7,
    "min_trials": 10000,
    "certainty": 0.95,
    "secs": 300
}

db:
The name of the file to use as a SQLite3 database.

min_n:
The minimum number of vertices for a generated graph.

max_n:
The maximum number of vertices for a generated graph.

min_trials:
A minimum number of connected graphs to generate.

certainty:
How certain it is that a good distribution of graphs will have been generated
after min_trials number of trials.

secs:
How many seconds to wait between giving updates to the console of how many
graphs have been generated. Use a keyboard interrupt to see immediate counts.

Example config file for graphprint:
{
	"directory":   "print",
	"algorithm":   "bfs",
	"file_type":   "png",
	"num_imgs":     10,
	"num_nodes":    35,
	"cell_length":  10,
	"start_color": [49, 185, 174],
	"act_color":   [121, 82, 169]
}

directory:
The directory to save images in.

algorithm:
The algorithm to use to traverse the graph. Choices are "bfs" or "dfs".

file_type:
The type of images that should be saved; identical to the file extension
for that file type. "png" and "jpg" work, although other common file formats
are likely to work, too.

num_imgs:
The number of images to generate.

num_nodes:
The number of nodes in the random connected graphs generated.

cell_length:
The side length of a square cell in the image.

start_color:
A color s given with RGB values. The color of vertex 1.

act_color:
A color a given with RGB values.

Using the field operations of vector addition and scalar multiplication,
vertex i is assigned the color (s + (i - 1) * a) % 256, where the modulo
operation is defined component-wise on the vector.