######################################
find_all_cpss.scr <max_order>

    SUMMARY
        This script prints all CPSSs up to order "max_order".  This script illustrates how the other scripts
        and programs work together to find all compound perfect squared squares.  The script does not
        parallelize the search which needs to be done for any practical large search.  It is just intended
        to illustrate the algorithm and usage of the other scripts and programs.

######################################
find_all_spss.scr <max_order>

    SUMMARY
        This script prints all SPSSs up to order "max_order".  The search is parallelized four ways to 
        illustrate the parallelization.  A practical script to search larger orders would likely
        need a higher level of parallelization.

######################################
build.scr
    This is a simple script that builds all C++ programs.  Edit this file to change compile options.

######################################
gen_grahps -e <max_edges> [-n <max_nodes>] [-c <connectivity>] [-m <modulus> -r <residue>] [-s] [-a] [-t]

    SUMMARY
        This program generates all simple planar graphs with nodes having a minimum degree of 3.  Connectivity
        may be specified as 2-connected or 3-connected.   Output format is ascii format chosen to be 
        compatible with plantri.  Each output line (written to stdout) contains one graphs. Format looks like this.
                7 bcde,aefc,abfd,acg,agb,bgc,dfe
        First number is the number of nodes. Each node is represented by a letter: a, b, c, ...  Each node is
        listed in order separated by commas and contains a list of the connecting nodes in clockwise order.

    OPTIONS
        -e <max_edges>
            This is the only required option and specifies the maximum number of edges in the graph.  All graphs
            with less than or equal to that number of edges, and which meet the other requirements, are output.

        -n <max_nodes>
            This options specifies the maximum number of nodes.  Only graphs with less than or equal to this
            number of nodes are output.  If omitted, then max_nodes defaults to "max_edges/2 + 1" which is usually
            what you want anyway.

        -c <connectivity>
            "connectivity" must be 2 or 3.  If this options is omitted, then connectivity defaults to 2.  If searching
            for SPSS, then this should be set to 3.  Usually set to 2 for most other uses.

        -s <min_square_side>
            This applies a determinant check to all output graphs.  Unless half the determinant of the associated matrix
            (equal to the graph complexity) has a square factor of at least "min_square_side" the graph is usually
            not output.  Because the determinant check is quick and applied before some other necessary checks, this
            option not only drastically reduces the quantity of output but also provides a 25% speedup of the 
            gen_graphs program.  This option should be used when searching for SPSS. A value of 100 works fine for
            that.

        -a  This option applies a different determinant filter.  If the number of edges is equal to "max_edges" then
            the graph is output only if the determinant is divisible by 13.  If the number of edges is equal to 
            "max_edges-1" then the graph is output only if the determinant is either divisible by 13 or divisible by 21.
            This filter should be used when generating perfect rectangles that can be paired with APS to form CPSS.

        -m <modulus> -r <residue>
            This options allow subdividing a problem to facilitate parallelization.  The entire set of graphs
            corresponding to specified parameters is divided into a number of pieces with the number equal to "modulus".
            Only the piece designated by "residue" is printed. "residue" should range from zero to "modulus" minus one.

        -t  <mod_threshold>
            Changes the mod threshold to <mod_threshold>.  If not specified, then mod_threshold will default to 25.
            mod/res algorithm generates all graphs with number of edges less than or equal to mod_threshold and only
            prints every M'th one where M is the modulus.  For graphs with more than mod_threshold edges, there are
            generated and printed only if they are extensions of a graph that was printed.  Increasing mod_threshold
            will increase the compute overhead but make the compute time and number of outputs more equal for different 
            values of "res".  The default value, 25, seems like a good compromise that usually works well.

######################################
findpr [-s] [-d] [-a <augmentation_limit>] [-o <max_cpss_order> -f <filter_file>]

    SUMMARY
        This program accepts as standard input the output of gen_graphs.  Using each graph input it checks to see
        if any perfect rectangles can be constructed from the graph and prints the Bouwkamp codes for the rectangles.

    OPTIONS
        -s
            If this option is given, only squares will be printed.  Use this to search for perfect squares.

        -d
            Print duals.  By default, dual suppression is implemented.  Any graph with more nodes than faces will be
            ignored, and any graph with equal number of nodes and faces, will reject any perfect rectangle if the
            preferred orientation requires a 90 degree rotation.  If this option is specified, all PRs will be
            printed including duals.

        -a <augmentation_limit>
            Any perfect rectangle can be augmented by adding an additional square adjacent where the square size
            is equal to the full width or height of the original rectangle.  This process may be iterated.
            So a non-augmented PR of order N will create two augmented PRs of order N+1, two augmented PRs
            of order N+2, etc.  With this option, all augmented rectangles will be printed up to order
            "augmentation_limit".

        -o <max_cpss_order> -f <filter_file>
            This option applies a filter to the generated perfect rectangles.  This is used when searching for 
            rectangles that pair with an APS to form a CPSS.  The aspect ratio of the rectangle is checked 
            against the list in "filter_file" to see if there is an APS with the same aspect ratio such that the
            combined order of the rectangle and the APS is less than or equal to "max_cpss_order".

            The format of the filter_file should be as follows:
                <order> <width> <height>
                <order> <width> <height>
                <order> <width> <height>
                <order> <width> <height>
            <order> is the order of the corresponding APS.  This is a count of all the component squares of the
            APS but not including the embedded rectangle.  <width> and <height> are the width and height of 
            the embedded rectangle with width being the greater of the two, and the pair expressed in least
            terms (no common factors).  The file must be sorted in ascending order of aspect ratio,
            where the aspect ratio is width divided by height.

            Note that the filter test is applied only to the base rectangle, not to any augmentations.  Therefore
            the original APS should be "de-augmented" for purposes of creating the filter file.  For example
            if an APS of order N has an embedded rectangle which is 14 by 9, then the filter file should contain
            the following lines. (Example does not show them correctly sorted.)
                N   14 9
                N+1  9 5
                N+2  5 4
                N+3  4 1
            One can think of these as derived APSes where a square is iteratively cut off the end of the embedded
            rectangle.
            
######################################
findaps [-s] [-d] [-a <augmentation_limit>] [-o <max_cpss_order> -f <filter_file>]

    SUMMARY
        This program accepts as standard input the output of gen_graphs.  Using each graph input it checks to see
        if any APS (almost perfect squares) can be created from the graphs.  An APS is defined as a subdivision
        of a square into a number of squares, each of different size, plus one rectangle.  In the general case
        the rectangle may be a square and may be the same size as one of the other squares.

    OPTIONS
        -o <max_cpss_order> -f <filter_file>
            This option applies a filter to the generated APS.  This is used when searching for APS that pair with
            a perfect rectangle to form a CPSS.  The aspect ratio of the embedded rectangle in the APS is checked
            against the list in "filter_file" to see if there is any PR with the same aspect ratio such that the
            combined order of the rectangle and the APS is less than or equal to "max_cpss_order".

            The format of the filter_file should be as follows:
                <order> <width> <height>
                <order> <width> <height>
                <order> <width> <height>
                <order> <width> <height>
            <order> is the order of the corresponding PR.  <width> and <height> are the width and height of
            the perfect rectangle with width being the greater of the two, and the pair expressed in least
            terms (no common factors).  The file must be sorted in ascending order of aspect ratio,
            where the aspect ratio is width divided by height.

######################################
find_basic_isomers [-a] [-b] [-c] [-r] [-S] [-C]

    SUMMARY
        This program accepts as standard input a list of squared squares or squared rectangles in either
        bouwkamp code or table code format.  The output is determined by the command line options, but the
        default behavior is to generate all basic isomers and print the preferred one.  Basic isomers are
        defined as all isomers (rearangement of the component squares) that can be created by either 
        rotating or reflecting rectangular regions contained in the PSS or PSR.  The preferred one is
        the lexically largest one, comparing each number of its output code in succession.

    OPTIONS
        -a
            This option causes the program to print all basic isomers.  Only the preferred orientation
            of each isomer is printed.  Default behavior is to print only the preferred isomer.

        -b
            Causes the output to be Bouwkamp code.  Default is table code.

        -c
            Prints an isomer count at the end of each output line.

        -r
            Prints all rotations and reflections.  Default behavior is to print only preferred orientation.

        -S
            Prints only simple squared squares or squared rectangles.  Default is to print both simple
            and compound.

        -C
            Prints only compound squared squares or squared rectangles.  Default is to print both simple
            and compound.

######################################
build.scr

    SUMMARY
        Simple script that compiles all the C++ programs.
         
######################################
create_pr_filter_list.scr

    SUMMARY
        Accepts as standard input a list of APS.  Output is a filter file in the format to be used by "findpr".
    
######################################
create_aps_filter_list.scr

    SUMMARY
        Accepts as standard input a list of PRs.  Output is a filter file in the format to be used by "findaps".
    
######################################
convert_pr_to_aps.scr

    SUMMARY
        Any perfect rectangle can be converted to an APS by adding an additional complementary rectangle 
        adjecent to its entire width.  This script accepts as standard input a list of PRs and outputs
        the generated APSes.

######################################
sort_pr_aps.scr

    SUMMARY
        This scripts accepts as standard input a list of PRs and APSes and sorts them by aspect ratio.
        The output of this script is what is required by "find_candidate_pairs.scr"

######################################
find_candidate_pairs.scr

    SUMMARY
        This script accepts as standard intput a list of PRs and APSes.  The list must be sorted by
        aspect ratio.  For PR, the aspect ratio is the width divide by height of the entier rectangle,
        and for APS it is the width divide by height of the embedded rectangle.

        Output from the script is a list of pairs, each pair consisting of on PR and one APS with the
        same aspect ratio.  Each line of output contains one such pair, with "##" as the separator.

######################################
pairs2cpss.scr

    SUMMARY
        This script accepts as standard input a list of pairs as generated by "find_candidate_pairs.scr"
        and outputs a list of CPSS that can be generated from the pairs.  Format of the output is 
        bracket code.  The script scales the rectangle and the APS, checks there are no duplicate 
        square sizes.  The bracket code places the embedded rectangle in brackets, or double brackets
        if it needs to be rotated 90 degress.

######################################
bracket2bcode

    SUMMARY
        This program accepts as standard intput the bracket code output by "pairs2cpss.scr".  It performs
        the mechanical but messy operation of converting the bracket code to standard Bouwkamp code which
        is then output.




