##################################################
/**************************************************************
*                                                             *
* scabble - calculates the unit scl ball in a subspace spanned*
*           by two or three chains                            *
*                                                             *
*   Copyright Danny Calegari and                              *
*    Alden Walker 2010                                        *
*                                                             *
*  Uses code from exlp by Masashi Kiyomi                      *
*  and calls glpk and gmp by the GNU project                  *
*                                                             *
*  Released under the GPL license                             *
*                                                             *
**************************************************************/
##################################################

Version 3d.0 - January 20, 2011


scabble will produce the unit ball in either a 2d or a 3d slice of B_1^H.  It
automatically decides which based on how many input chains it gets

The syntax is:
./scabble [-v] [-mn] [-glpk] filename chain1 , chain2 [, chain3]
for example, 
./scabble test aabAAB , abAB
or
./scallop test aabAAB , abAB , abAABB ab

For 2d:
It outputs a drawing of the unit ball to filename.eps.
For 3d:
It produces filename.pov, which can be input to povray, for example with the
command:
povray -w1024 -h768 -a0.1 test.pov
and it produces filename.txt, which is a Mathematica list of polygons

-mn overrides the number of polygon sides to n
-v causes verbose output


By default, scabble uses exlp and GMP for all computations.  To use glpk instead,
use the -glpk option.

scabble will take integer coefficients on the input words, so 
./scabble test 5aabAAB , 7abAB
works.



-----------
Compilation:
-----------

Requirements:
You need glpk and gmp installed in your path (i.e. somewhere that g++ can find
the header files and libraries).  You technically need gmpxx (the C++ gmp library),
but actually, all it's used for is printing, so just get rid of that in 
rational.cc, and you're fine.


To compile, just type:

make





-------
License:
-------

Scallop is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 3 of the License, or (at your
option) any later version.

Scallop is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public
License for more details.

You should have received a copy of the GNU General Public License
along with scallop.  If not, see http://www.gnu.org/licenses/.


Because scabble uses the same strategy to compute scl as scallop, the same 
comments on rigor are appropriate (and the same fix applicable):

------
Rigour:
------

The algorithm that scallop uses to compute scl is rigorous
for (finite linear combinations of) *alternating words*:
those where the letters (cyclically) alternate between one
of a,A and b,B. Hence: abAB is alternating, aaab is not, a is not.

For nonalternating input, scallop rigorously computes upper
bounds on scl. Moreover, the output is "statistically" correct
on *most* input, especially if the value of scl is small.

To rigorously compute scl for nonalternating input, take any
input w and replace it by f(w) where f rewrites letters as string
by the substitution rule:

	a -> aaa
  b -> bbb

After rewriting, scallop f(w) will rigorously compute scl(w) even
if w is nonalternating. However, in practice, the computation is
much slower, and runs into memory issues much sooner.