Freecell Solver's Command-Line Syntax and Usage
===============================================


1. The programs
---------------

Most command-line switches have two versions: a short POSIX one which
is a dash followed by a letter; and a long GNU one which is two dashes
followed by the command string. Note, that Freecell Solver does not
support specifing more than one command letter after a dash, (e.g:
"-sip"). Furthermore, a command that accepts a parameter, will require
this paramter to be present in the next command-line argument, not in
the GNU manner of "--command=option".

I don't use getopt because I want Freecell Solver to be a pure ANSI C
program, so I'm sorry for the inconvenience.


2. Getting Help
---------------

-h      --help

This option displays a help text on the screen. This help
text summarizes the command-line options and their meaning, as well as
the signal combinations that fc-solve accepts.


3. Output Options
-----------------

-p      --parseable-output

This option will display the stacks in a format that can be more easily
manipulated by text-processing programs such as grep or perl. Namely,
The freecells will be displayed in one line, and the foundations in a
separate line. Plus, Each stack will be displayed horizontally, in its
own line, while beginning with a ":".


-t      --display-10-as-t

This option will display the 10 cards as a capital T instead of a 10.
Thus, the cards will be more properly aligned.


-c      --canonized-order-output

Freecell Solver re-arranges the stacks and freecells in a given state
according to their first card. It keeps their actual position in a
separate place, but internally it uses their canonized place. Use
this option, if you want Freecell Solver to display them in that order.
One should be warned that that way the place of a given stack in the
board will not be preserved throughout the solution.


-m      --display-moves

This option will display the moves instead of the intermediate states.
Each move will be displayed in a separate line, in a format that is
human-readable, but that can also be parsed and analyzed by a computer
program with some effort on the programmer's part.


-sn     --standard-notation

This option will display the moves in standard notation in which every
move consists of two bytes and they are ten moves in a line. Naturally,
this option will only become apparent if the display moves is specified.
(it does not implicitly specify it, though).

For more information regarding standard notation refer to the following 
web-page:

http://home.earthlink.net/~fomalhaut/freecell.html


-sam      --display-states-and-moves

This option will display both the intermediate states and the moves that 
are needed to move from one to another. The standard notation
option applies to it to.


-pi       --display-parent-iter

This option (assuming the -s and -i options are specified) will also
display the iteration index of the state from which the current state
was derived. This is especially useful for A* or BFS scans.

4. Game Variants Options
------------------------


--freecells-num [Number of Freecells]

This option specifies the number of freecells which are available to
the program. Freecell Solver can use any number of freecells as long as
it does not exceed its maximal number.

This maximum is hard-coded into the program, and can be specified at
compile-time by modifying the file "config.h". See the file INSTALL for
details.


--stacks-num [Number of Stacks]

This option specifies the number of stacks present in the board. Again,
this number cannot exceed the maximal number of stacks, which can be
specified in the file "config.h" during compile-time of Freecell
Solver.


--decks-num [Number of Decks]

This options specifies how many decks are found in the board. This number
cannot exceed the maximal number of decks, which can be specified in the
file "config.h" during compile time of Freecell Solver.


--sequences-are-built-by {suit|alternate_color|rank}

This option specifies whether a card sequence is built by suit or by
alternate colour or by rank regardless of suit.


--sequence-move {limited|unlimited}

This option specifies whether the sequence move is limited by the
number of freecells or vacant stacks or not. 


--empty-stacks-filled-by {kings|none|all}

Specifies which cards can fill an empty stack.


--game [game]
--preset [game]
-g [game]

Specifies the type of game. Each preset implies several of the
settings options above and sometimes even the tests order below. 
Available presets:

     bakers_dozen         - Baker's Dozen
     bakers_game          - Baker's Game
     beleaguered_castle   - Beleaguered Castle
     citadel              - Citadel
     cruel                - Cruel
     der_katz             - Der Katzenschwanz
     die_schlange         - Die Schlange
     eight_off            - Eight Off
     forecell             - Forecell
     freecell             - Freecell
     good_measure         - Good Measure
     ko_bakers_game       - Kings' Only Baker's Game
     relaxed_freecell     - Relaxed Freecell
     relaxed_sehaven      - Relaxed Seahaven Towers
     seahaven             - Seahaven Towers
     simple_simon         - Simple Simon
     streets_and_alleys   - Streets and Alleys

Note: in order to solve Der Katzenschwanz and Die Schlange I recommend you
compile Freecell Solver with the INDIRECT_STACK_STATES option, or else it will
consume much more memory. For details consult the file INSTALL.

5. Solving Algorithm Options
----------------------------

-mi [Maximal number of iterations]
--max-iters [Maximal number of iterations]

This parameter limits the maximal number of states to check. This will
give a rough estimate on the time spent to solve a given board.


-md [Maximal depth]
--max-depth [Maximal depth]

Freecell Solver recurses into the solution. This paramter specifies a
maximal recursion depth. Generally speaking, it's not a good idea to
set it, because that way several important intermediate states become
inaccesible.

-mss [Maximal States' Number]
--max-stored-states [Maximal States' Number]

Limits the number of the states stored by the program in the computer's
memory. This differs from the maximal number of iterations in the sense, that
it is possible that a stored state was not checked yet.


-to [Test's Order]
--tests-order [Test's Order]

This option specifies the order in which Freecell Solver will try the
differnet types of moves that it can perform. Each move is specified by
one character, and they are performed in the order in which they appear
in the paramter string. You can omit tests by not including their
correpsonding characters in the string.

The tests along with their characters are:

Freecell Tests:

'0' - put top stack cards in the foundations.
'1' - put freecell cards in the foundations.
'2' - put freecell cards on top of stacks.
'3' - put non-top stack cards in the foundations.
'4' - move stack cards to different stacks.
'5' - move stack cards to a parent card on the same stack.
'6' - move sequences of cards onto free stacks.
'7' - put freecell cards on empty stacks.
'8' - move cards to a different parent.
'9' - empty an entire stack into the freecells.

Simple Simon Tests:

'a' - move a full sequence to the foundations.
'b' - move a sequence to a true parent of his. 
'c' - move a whole stack sequence to a false parent (in order to clear 
      the stack) 
'd' - move a sequence to a true parent that has some cards above it. 
'e' - move a sequence with some cards above it to a true parent. 
'f' - move a sequence with a junk sequence above it to a true parent that 
      has some cards above it. 
'g' - move a whole stack sequence to a false parent which has some 
      cards above it.
'h' - move a sequence to a parent on the same stack.

Mainuplating the tests order can be very helpful to the quick solution
of a given board. If you found that a certain board cannot be solved in
after a long time or in a certain maximal number of iterations, you
should try different tests' orders. Usually, one can find a test order
that solves a board very quickly.

Note that this test order usually makes sense only for the Depth-First 
Search scans (see the "--method" option below).

Also note that Freecell tests are not suitable for solving Simple Simon games
and Simple Simon tests are not suitable for solving anything except Simple
Simon.

Tests can be grouped together into random groups using parenthesis
(e.g: "(0123)") or square brackets ("[012][3456789]"). Such grouping is
only relevant to the Random DFS scan (see below).


-me [Solving Method]
--method [Solving Method]

This option specifies the solving method that will be used to solve the
board. Currently, the following methods are available:

a-star     - An A* scan
bfs        - A Breadth-First Search (or BFS) scan
dfs        - A Depth-First Search (or DFS) scan
random-dfs - A randomized DFS scan
soft-dfs   - A "soft" DFS scan

The difference between "dfs" and "soft-dfs" is that the soft DFS does not
use procedural recursion but rather its own internal stack. "random-dfs" is
similar to "soft-dfs" only it determines to which states to recurse into 
randomly. Its behaviour will differ depenending on the seed you supply to it.
(see the "-seed" option below.)

BFS does not yield good results, and A* has a mixed behaviour, so for 
the time being I recommend using either DFS or Soft-DFS.

The Random-DFS scan processes every tests' random group, randomizes the
states that it found and recurses into them one by one. Renegade tests
that do not belong to any group, are processed in a non-random manner.


-asw [A* Weights]   
--a-star-weight [A* Weights]

Specify weights for the A* scan, assuming it is used. The parameter
should be a comma-separated list of numbers, each one is proportional
to the weight of its corresponding test.

The numbers are, in order:
1. The number of cards out.
2. The maximal sequence move.
3. The number of cards under sequences.
4. The length of the sequences which are found over renegade cards.
5. The depth of the board in the solution.

The default weights are respectively: 0.5,0,0.3,0,0.2


-seed [Seed Number]

Specifies a seed to be used by Freecell Solver's internal random number 
generator. This seed may alter the behaviour and speed of the "random-dfs"
scan.


-opt
--optimize-solution

This option instructs Freecell Solver to try and optimize the solution
path so it will have a smaller number of moves.


6. Running Several Scans in Parallel:
-------------------------------------

Starting from Version 2.4.0, Freecell Solver can run several scans in 
parallel on the same state collection. Each scan resides in its own
"Soft Thread". By specifying several soft threads on the command line
one can create use several parallel scans. Once one of the scans 
reaches a solution, the solution will be displayed.


-nst
--next-soft-thread

This option creates a new soft-thread and let the other scan-specific options
initialize it. For example:

# fc-solve --method a-star -nst --method soft-dfs -to 0123467 myboard.txt

will run an A* scan and a Soft-DFS scan with a tests order of 0123467 on
myboard.txt.


-step [Number of Iterations in the Step]
--soft-thread-step [Number of Iterations in the Step]

This option will set the number of iterations with which to run the 
soft thread before switching to the next one. By specifying a larger 
step, one can give a certain scan a longer run-time and a higher priority.


-nht
--next-hard-thread

This argument lets one initialize the next hard thread. If Freecell Solver was
compiled with such support, then it is possible to run each hard thread in its
own system thread. Each hard-thread contains one or more soft threads.

7. Run-time Display Options
---------------------------


-i
--iter-output

This option tells fc-solve to print the iteration number and the
recursion depth of every state which is checked, to the standard
output. It's a good way to keep track of how it's doing, but the output
slows it down a bit.

-s
--state-output

This option makes little sense by itself, and is applicable only if
-i/--iter-ouput was also specified at the command-line. If specified,
this option also output the cards and formation of the board itself,
for every state that is checked. "fc-solve -i -s" yields a nice
real-time display of the progress of Freecell Solver, but you usually
cannot make what is going on because it is so fast.


8. Signal Combinations
----------------------

If you are working on a UNIX or a simliar system then you can set some
run-time options in "fc-solve" by sending it some signal
combinations.

If you send the signal USR1, without sending any other signals before
that, then "fc-solve" will output the present number of
iterations. This method is a good way to monitor an instance that takes
a long time to solve.

If you send it the signal USR2 and then USR1, then "fc-solve"
will print the iteration number and depth on every state that it
checks. It is the equivalent of specifiying (or unspecifiying) the
option -i/--iter-output.

If you send it two USR2 signals and then USR1, then "fc-solve"
will also print the board of every state. Again, this will only be done
assuming the iteration output is turned on.