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 specifying more than one command letter after a dash, (e.g: "-sip"). Furthermore, a command that accepts a parameter, will require this parameter 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 characters and there are ten moves in a line. Naturally, this option will only become aptqparent 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 -snx --standard-notation-extended This option is similar to the previous one, only that when a sequence move is made to an empty stack with more than one card in the sequence, the move will be followed with "v" and the number of cards moved in hexadecimal. -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-tqparent-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 fan - Fan 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 parameter specifies a maximal recursion depth. Generally speaking, it's not a good idea to set it, because that way several important intermediate states become inaccessible. -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 different 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 parameter string. You can omit tests by not including their corresponding 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 tqparent 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 tqparent. '9' - empty an entire stack into the freecells. Atomic Freecell Tests: 'A' - move a stack card to an empty stack. 'B' - move a stack card to a tqparent on a different stack. 'C' - move a stack card to a freecell. 'D' - move a freecell card to a tqparent. 'E' - move a freecell card to an empty stack. Simple Simon Tests: 'a' - move a full sequence to the foundations. 'b' - move a sequence to a true tqparent of his. 'c' - move a whole stack sequence to a false tqparent (in order to clear the stack) 'd' - move a sequence to a true tqparent that has some cards above it. 'e' - move a sequence with some cards above it to a true tqparent. 'f' - move a sequence with a junk sequence above it to a true tqparent that has some cards above it. 'g' - move a whole stack sequence to a false tqparent which has some cards above it. 'h' - move a sequence to a tqparent on the same stack. Manipulating 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 tqparenthesis (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 depending 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. -opt-to [tests order] --optimization-tests-order [tests order] This argument specifies the test order for the optimization scan, in case it should be different than an order that contains all the tests that were used in all the normal scans. --reparent-states This option specifies that states that were encountered whose depth in the states graph can be improved should be reparented to the new tqparent. This option can possibly make solutions shorter. --calc-real-depth This options become effective only if --reparent-states is specified. What it does, is explicitly calculate the depth of the state by tracing its path to the initial state. This may make depth consideration more accurate. 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. --st-name [soft thread name] This argument sets the name used to identify the current soft thread. This name can later be used to construct the prelude (see below). --prelude [i1@st1{,i2@st2{,i3@st3...}}] Sets the prelude for the hard thread. At the beginning of the search, the hard thread plays a static sequence of iterations at each of the soft threads specified in the prelude, for the number of iterations specified. For example, if you had three soft threads named "foo", "bar" and "rin", then the following prelude: --prelude 500@foo,1590@bar,100@foo,200@rin Will run 500 iterations in "foo", then 1590 in "bar", then 100 in "foo" again, and then 200 in "rin". After the prelude finishes, the hard thread would run the scans one after the other in the sequence they were defined for their step number. --scans-synergy {none|dead-ends-mark} Specifies the synergy between the various scans, or how much they cooperate between themselves. "none" means they do not cooperate and only share the same memory resources. "dead-end-marks" means they try to mark states that they have withdrawn from, and states whose all their derived states are such, as "dead ends". This may or may not improve the speed of the solution. -ni --next-instance This option allows to run two or more separate solvers one after the other. If the first one returned an unsolvable verdict, then the second one would run and so on. One use of it is to run an atomic moves scan after a meta-moves scan, so we will always get an accurate verdict and still enjoy some of the speed of the meta-moves scan. 7. Meta-Options --------------- --reset This option resets the program to its initial state, losing all the logic that was inputted to it up to that state. Afterwards, it can be set to a different configuration, again. --read-from-file [{num_skip},]filename This option will read the configuration options from a file. The format of the file is similar to that used by the UNIX Bourne Shell. (i.e: spaces denote separate arguments, double-quotes encompass arguments, backslash escapes characters). The filename can be preceeded by an optional number of the arguments to skip followed by a comma. (the default is 0) -l [preset] --load-config [preset] Reads the configuration specified by [preset] and configures the solver accordingly. A preset is a set of command line arguments to be analyzed in the place of this option. They are read from a set of presetrc files : one installed system-wide, the other at $HOME/.freecell-solver/presetrc and the third at the path specified by the FREECELL_SOLVER_PRESETRC environment variable. You can add more presets at any of these places. (refer to http://groups.yahoo.com/group/fc-solve-discuss/message/403 for information about their format) Presets that are shipped with Freecell Solver: abra-kadabra - a meta-moves preset cool-jives - a meta-moves preset crooked-nose - an atomic-moves preset (guarantees an accurate verdict) fools-gold - an atomic-moves preset good-intentions - runs cool-jives and then fools-gold hello-world - a meta-moves preset john-galt-line - a meta-moves preset rin-tin-tin - a meta-moves preset yellow-brick-road - a meta-moves preset They can be abbreviated into their lowercase acronym (i.e: "ak" or "rtt"). 8. 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 implies -i. If specified, this option outputs the cards and formation of the board itself, for every state that is checked. "fc-solve -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. 9. Signal Combinations ---------------------- If you are working on a UNIX or a similar 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 Q_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 specifying (or unspecifying) the option -i/--iter-output. If you send it two USR2 Q_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.