Freecell Solver’s Command-Line Syntax and Usage

The scope of the options is mentioned along with them. Options can be:

Global

This option displays a help text on the screen. This help gives a help display summarizing some ways to use the program and get more help.

Global

This option displays the version number of the components that make the executable (and then exits).

Global

Some help on the various configurations of Freecell Solver.

Global

A help screen giving an overview of all available options.

Global

Explains how to change the default help screen to a different one.

Global

How to generate shorter solutions.

Global

The default help screen.

Global

This option will display the columns 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 column will be displayed horizontally, in its own line, while beginning with a :.

Global

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

For example, here is a command line using -p and -t:

Global

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.

Global

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.

For example:

Global

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 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://www.solitairelaboratory.com/solutioncatalog.html

Global

This option is similar to the previous one, except 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.

Global

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.

Global

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 BeFS (so-called a-star) or BFS scans.

Global

Outputs to a file instead of standard output. So for example:

Will put the solution to the file in 2405.board in the file 2405.solution.txt . This will also be done using:

Global

This option will display a different status message ("Iterations count exceeded.") instead of "I could not solve this game." in case the iterations count was exceeded. This is recommended because the "I could not solve this game." message can also mean that the entire game graph was fully traversed (within the limitations of the specified moves' types) and so no solution is possible.

This option is not the default, to retain compatibility with previous versions of Freecell Solver, and was added in version 3.12.0 of fc-solve.

Global

Presents the moves to the intermediate reached state, if the maximal number of iterations was reached without a conclusion (= "intractable").

This option is not the default, to retain compatibility with previous versions of Freecell Solver, and was added in version 4.20.0 of fc-solve.

Global

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 (or alternatively INSTALL.html) for details.

Global

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.

Global

This options specifies how many decks are found in the board. This number cannot exceed the maximal number of decks, which can be specified by the Freecell Solver build system.

Global

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

Global

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

Global

Specifies which cards can fill an empty stack.

Global

Specifies the type of game. Each preset implies several of the settings options above and sometimes even the moves’ order below. The default configuration is for Freecell.

Available presets:

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.

To solve PySol Eight Off game No. 1,000 type:

To solve PySol Baker’s Game No. 50, type:

If you want to solve a game similar to Freecell only with sequences built by rank, and unlimited sequence move, do:

Global

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

Not currently implemented

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 may become inaccessible.

Global

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.

Instance-wide

This also limits the number of trimmed stored states, but this time will try to trim them once the limit has been reached (which is time consuming and may cause states to be traversed again in the future).

Soft-thread-specific

This option specifies the order in which Freecell Solver will try the different types of moves (formerly termed "tests") 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 moves by not including their corresponding characters in the string.

The moves along with their characters are:

Manipulating the moves 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 moves' orders. Usually, one can find a moves order that solves a board very quickly.

Note that this moves order usually makes sense only for the Soft-DFS and Random DFS scans (see the --method option below).

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

Moves can be grouped together into groups using parenthesis (e.g: "(0123)") or square brackets ("[012][3456789]"). Such grouping is only relevant to the Random DFS scan (see below). A group may optionally be followed by the equal sign "=" and by an ordering specifier. If one specifies "=rand()", then the derived states will be randomised based on the seed (which is what happens if no equal sign is specified). On the other hand, if one specifies something like "=asw(5,0,5,0,0,5)", then the numbers inside the parentheses will be treated as weights for the same ordering function used by the -asw flag (see below).

If the order specifier is "=all()" then all the moves in the group will be run, even if some derived states have been yielded by earlier moves in the group. ( This was added in version 5.24.0. )

Soft-thread-specific

Sets the Moves' order starting from the minimal depth onwards. This way, if a Soft-DFS scan recurses deeply into the game, it will use a different moves' order.

Note that if you set the moves' order of a minimal depth of say 50, then it will override all the moves' order of 50 and above. As a result, it is recommended that you set the minimal depth moves order in an increasing depth.

It should be noted that the -to or --tests-order option above is equivalent to using this option with a minimal depth of 0.

Here are some examples:

This sets the moves' order to 0123456789 for all depths below 30 and to 0138924567 for all depths above it.

This sets the moves' order to 0123457 for depths -9 (those below 10), to 750123 for depths 10-24, and to 710235 for the depths 25 onwards.

This sorts the moves starting from 10 onward based on the asw() function.

This randomises the moves from 10 onward.

This does the same thing as the previous example.

Note : This option should be used instead of the older -dto option given below which mutilates the moves order parameter and is still provided for backward compatibility.

This is equivalent to specifying -dto2 [Min Depth],[Min Depth],[Moves' Order] - i.e: the "[Min Depth]," string is prefixed to the given moves order.

This option is provided for backward compatibility with older versions of Freecell Solver.

Soft-thread-specific

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

Starting from recent Freecell Solver versions there is no difference between dfs and soft-dfs. In earlier versions, use of soft-dfs is recommended. 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-star has a mixed behaviour, so for the time being I recommend using Soft-DFS or Random-DFS.

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

Soft-thread-specific

Specify weights for the a-star (= "Best-First Search") 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:

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

Soft-thread-specific

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.

Soft-thread-specific

This option sets the pruning algorithm for the soft thread. Current valid values are only the empty string ("") for no pruning and r:tf (short for "Run: to foundations") for Horne’s rule. See:

https://groups.yahoo.com/neo/groups/fc-solve-discuss/conversations/topics/214

Flare-wide

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

Flare-wide

This argument specifies the moves order for the optimization scan, in case it should be different than an order that contains all the moves that were used in all the normal scans.

Flare-wide

This option specifies that states that were encountered whose depth in the states graph can be improved should be reparented to the new parent. This option can possibly make solutions shorter.

Flare-wide

This option becomes 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.

Soft-thread-specific

Sets the patsolve’s scan X param (an integer) in position "pos" into "value".

Examples:

Soft-thread-specific

Sets the patsolve Y param (a floating point number) in position "pos" into "value".

Examples:

Hard-thread-specific

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

will run an BeFS scan and a Soft-DFS scan with a moves order of 0123467 on myboard.txt.

Soft-thread-specific

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.

Note: after some experimentation, we have concluded that the --prelude option normally yields better results, but -step can be used as a fallback.

Flare-wide

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.

Soft-thread-specific

This argument sets the name used to identify the current soft thread. This name can later be used to construct the prelude (see below).

Hard-thread-specific

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:

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.

Flare-wide

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.

Global

This option allows one 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 benefits of the meta-moves scan.

Instance-wide

Each instance contains several flares. Flares are various alternative scans, that are ran one after another, as specified in the --flares-plan below or defaulting to running only the first flare (which isn’t very useful). Out of all the flares that are successful in solving a board, Freecell Solver picks the one with the shortest solution.

Flare-wide

This is a name that identifies the flare for use in the flares' plan.

Instance-wide

This instance-wide parameter gives a plan for the flares as a big string. Here are some examples:

This plan will run the flare with the name FlareyFlare indefinitely, until it terminates. Once a RunIndef action is encountered, the rest of the plan is ignored.

Runs MyFlare for 500 iterations and FooFlare for 2,000 iterations. Note that both flares will be run and won’t share any resources between them, and then the minimal solution out of both flares (or only those that finished ). If no flares finished, then Freecell Solver will run them both again for the same number of iterations each, until at least one finishes (or it ran out of the iterations' limit).

This runs the flares identified by dfs and befs and then see if a solution was reached ("CP:" stands for "checkpoint"), and if so yield it. If both flares did not reach a solution yet, or failed to solve the board, it will run the flare funky for 10,000 iterations and yield its solution. And like the previous case, this solution will loop after it ended for as long as the no flare solved the board or the program did not run out of iterations.

Using checkpoints one can yield a possibly sub-optimal (as far as solution length is concerned) solution that will still solve faster than letting all the flares run.

Global

This dictates how to choose the winning flare based on if more than one yielded a solution. Possible options are:

Global

Sets a global, floating-point number, factor to multiply all the iterations counts in the flares plans. The higher it is, the longer the scans will take, but there is a greater chance more of them will succeed, and, as a result, the solution may be shorter.

As an example, the following:

Is equivalent to:

while:

Is equivalent to:

Global

This is a numeric limit to the LRU cache which only matters if Freecell Solver was compiled with FCS_RCS_STATES enabled. This value should be a positive integer and the higher it is, the more quickly it is likely that Freecell Solver will run, but it will also consume more memory. (The entire point of FCS_RCS_STATES is to conserve memory).

Global

This option resets the program to its initial state, losing all the configuration logic that was input to it up to that state. Afterwards, it can be set to a different configuration, again.

Global (but context-specific).

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 preceded by an optional number of the arguments to skip followed by a comma. (the default is 0)

Global (but context-specific).

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:

They can be abbreviated into their lowercase acronym (i.e: "ak" or "rtt").

Global

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.

Global

Prints the current iteration if -i is specified, only every [step] steps, where [step] is a positive integer. For example, if you do fc-solve -i --iter-output-step 100, you will see this:

This option has been added in Freecell Solver 4.20.0 and is useful for speeding up the runtime process, by avoiding excessive output.

Global

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.