README.txt file for qbsolv example of coloring a US state map

This directory contains the following files:
- README.txt: 		this file
- demoStates.sh:	a bash script that runs the demo
- usa.adj:		a text file that defines the adjacencies between US 
			states, obtained from https://
			  writeonly.wordpress.com/2009/03/20/
			  adjacency-list-of-states-of-the-united-states-us/
- adj2qubo.py:		a Python program that converts the adjacency file to
			the qbsolv QUBO input format
- plotmap.sh:		a bash script that creates a colored map
- color_states.py:	a Python program that performs the detailed coloring
- blank_US_state_map.svg:	the uncolored US state map, obtained from 
			https://commons.wikimedia.org/wiki/
			    File:Blank_US_Map_(states_only).svg
			[Note: see license details below]

Noteworthy output of the demo consists of
- A set of 9 distinct colorings of the US state map, in files named 
  usa.qbout.xa[a-i].svg.  These colorings can be easily viewed in a browser.
  These colorings will typically change at each execution of the demo.
- The QUBO itself, generated by adj2qubo.py, in usa.qubo.  

The demo can be run by invoking, at the shell prompt,

	$ ./demoStates.sh


The mapping of the original problem to a quadratic unconstrained binary 
optimization (QUBO) problem is done as follows:
- We know that a map (planar graph) can be colored with 4 colors
- The color of each state is represented by a 4-bit unary encoding; i.e.,
  the bit representing the color is on and all the other bits are off
- The adjacencies of states with each other, represented in the usa.adj
  file, indicate which state-colors (sets of 4 bits) must be different
  from each other.  The exact representation of the state adjacency 
  constraints is created by the adj2qubo.py program.


----License information for Blank_US_Map_(states_only).svg

License: GNU Free Documentation License, version 1.2 and Creative Commons 
    Attribution-Share Alike 3.0 Unported.
- GNU Free Documentation License, version 1.2: Permission is granted to copy, 
distribute and/or modify this document under the terms of the GNU Free 
Documentation License, Version 1.2 or any later version published by
the Free Software Foundation; with no Invariant Sections, no Front-Cover
Texts, and no Back-Cover Texts. A copy of the license is included in the
section entitled GNU Free Documentation License
(https://en.wikipedia.org/wiki/GNU_Free_Documentation_License).
- Creative Commons Attribution-Share Alike 3.0 Unported: This file is
licensed under the Creative Commons Attribution-Share Alike 3.0 Unported
license (https://creativecommons.org/licenses/by-sa/3.0/legalcode).