11. Script commandline driver¶

The commandline driver (see Script commandline driver) provides support for passing common commandline options to programs and a sub-class for spaces called Script that can take advantage of the options.

Overview. Commandline options summarizes the commandline options supported by the commandline driver. The base classes for scripts that work together with the commandline driver are sketched in Scripts.

Important

Do not forget to add

#include <gecode/driver.hh>

to your program when you want to use the script commandline driver.

11.1. Commandline options¶

option	type	explanation
propagation options
`-ipl`	`def`, `val`, `bnd`, `dom`	integer propagation level
branching options
`-decay`	`double`	decay-factor
`-seed`	`unsigned int`	seed for random numbers
search options
`-solutions`	`unsigned int`	how many solutions (`0` for all)
`-threads`	`double`	how many threads
`-c-d`	`unsigned int`	commit recomputation distance
`-a-d`	`unsigned int`	adaptive recomputation distance
`-d-l`	`unsigned int`	discrepancy limit for `LDS`
`-node`	`unsigned long long int`	cutoff for number of nodes
`-fail`	`unsigned long long int`	cutoff for number of failures
`-time`	`double`	cutoff for time in milliseconds
`-step`	`double`	improvement step for floats
restart-based and portfolio search options
`-restart`	`none`, `constant`, `linear`, `geometric`, `luby`	enable restarts, define cutoff
`-restart-scale`	`unsigned int`	scale-factor for cutoff values
`-restart-base`	`double`	base for geometric cutoff values
`-nogoods`	`false`, `true`, `0`, `1`	whether to post no-goods
`-nogoods-limit`	`unsigned int`	depth limit for no-good recording
`-assets`	`unsigned int`	number of assets in a portfolio

Figure 11.1 Predefined commandline options¶

option	type	explanation
execution options
`-mode`	`solution`, `time`, `stat`, `gist`	script mode to run
`-samples`	`unsigned int`	how many samples
`-iterations`	`unsigned int`	how many iterations per sample
`-print-last`	`false`, `true`, `0`, `1`	whether to only print last solution
`-file-sol`	`stdout`, `stdlog`, `stderr`	where to print solutions
`-file-stat`	`stdout`, `stdlog`, `stderr`	where to print statistics
`-interrupt`	`false`, `true`, `0`, `1`	whether driver catches Ctrl-C
`-trace`	`init`, `prune`, `fix`, `fail`, `done`, `propagate`, `commit`, `none`, `all`	which events to trace
`-cp-profiler`	`int,int`	Comma separated pair of execution id and port number to connect to CPProfiler.

Figure 11.2 Predefined commandline options, continued¶

option	type	explanation
`-branching`	string	branching options
`-model`	string	general model options
`-propagation`	string	propagation options
`-symmetry`	string	symmetry breaking options
`-search`	string	search options

Figure 11.3 User-definable commandline options¶

The commandline driver provides classes Options, SizeOptions, and InstanceOptions that support parsing commandline options. All classes support the options as summarized in Figure 11.1, Figure 11.2, and Figure 11.3. Here, for a commandline option with name -name, the option classes provide two functions with name name(): one that takes no argument and returns the current value of the option, and one that takes an argument of the listed type and sets the option to that value. If the commandline options contains a hyphen -, then the member function contain an underscore _ instead. For example, for the options -c-d, -a-d, and -d-l the member functions are named c_d(), a_d(), d_l().

The values for -threads are interpreted as described in Search options.

Note that all commanline options can also be used with a starting double hyphen -- instead of a single hyphen.

Invoking help. The only option for which no value exists is -help: it prints some configuration information and a help text for the options and stops program execution.

Size and instance options. The class SizeOptions accepts an unsigned integer as the last value on the commandline (of course, without an option). The value can be retrieved or set by member functions size().

The class InstanceOptions accepts a string as the last value on the commandline (of course, without an option). The value can be retrieved or set by member functions instance().

Integer propagation level options. The command line option -ipl accepts a comma separated list of the basic integer propagation levels: def for the default level, val for value propagation, bnd for bounds propagation, and dom for domain propagation. In addition it accepts the modifiers speed, memory, basic, and advanced that are used by some constraints and can be given in addition to a basic integer propagation level.

Mode options. The different modes passed as argument for the option -mode have the following meaning:

solution prints solutions together with some runtime statistics.
time can be used for benchmarking: average runtime and coefficient of deviation is printed, where the example is run -samples times. For examples with short runtime, -iterations can be used to repeat the example several times before measuring runtime. Note that the runtime includes also setup time (the creation of the space for the model).
stat prints short execution statistics.
gist runs Gist rather than search engines that print information. Gist is put into depth-first mode, when a non best solution search engine is used (that is, DFS), and into branch-and-bound mode otherwise (that is, BAB).

If Gecode has not been compiled with support for Gist (see How Gecode has been configured for how to find out about Gecode’s configuration), the mode gist will be ignored and the mode solution is used instead.

Trace options. Which events to trace (see also Groups and tracing) can be specified by the -trace commandline option. It accepts a comma-separated list of the event types to trace, that is init, prune, fix for fixpoint, fail for failure, and done as well as none to trace no events and all to trace events of all types.

Examples with tracing include SEND+MORE=MONEY puzzle, Generating Hamming codes, and Folium of Descartes.

CPProfiler options. For more details on the CPProfiler, please consult Using the CPProfiler as the commandline arguments are used exactly as described there.

Examples. For an example, in particular, how to use the user-defined options, see Using the script commandline driver. As all examples that come with Gecode use the script commandline driver, a plethora of examples is available (see Example scripts (models)). Also adding additional options is straightforward, for an example see Golf tournament.

Gist inspectors and comparators. The driver options can pass inspectors and comparators (see Inspecting and comparing nodes) to Gist. To register an inspector i, use the inspect.click(&i), inspect.solution(&i), or inspect.move(&i) methods of the option object, for a comparator c, use inspect.compare(&c).

11.2. Scripts¶

Scripts (see Script classes) are subclasses of Space that are designed to work together with option objects of class Options and SizeOptions.

In particular, the driver module defines scripts IntMinimizeScript, IntMaximizeScript, IntLexMinimizeScript, IntLexMaximizeScript, FloatMinimizeScript, and FloatMaximizeScript that can be used for finding best solutions based on a virtual cost() function, see also Using a cost function and Support for cost-based optimization.

Subclasses of FloatMinimizeScript and FloatMaximizeScript use the value passed on the command line option -step as value for the improvement step (see Optimizing float cost with improvement step.). For an example, see Golden spiral.

As scripts are absolutely straightforward, all can be understood by following some examples. For an example see Using the script commandline driver or all examples that come with Gecode, see Example scripts (models).