12. 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.
12.1. Commandline options¶
option |
type |
explanation |
|---|---|---|
propagation options |
||
|
|
integer propagation level |
branching options |
||
|
|
decay-factor |
|
|
seed for random numbers |
search options |
||
|
|
how many solutions ( |
|
|
how many threads |
|
|
commit recomputation distance |
|
|
adaptive recomputation distance |
|
|
discrepancy limit for |
|
|
cutoff for number of nodes |
|
|
cutoff for number of failures |
|
|
cutoff for time in milliseconds |
|
|
improvement step for floats |
restart-based and portfolio search options |
||
|
|
enable restarts, define cutoff |
|
|
scale-factor for cutoff values |
|
|
base for geometric cutoff values |
|
|
whether to post no-goods |
|
|
depth limit for no-good recording |
|
|
number of assets in a portfolio |
Figure 12.1 Predefined commandline options¶
option |
type |
explanation |
|---|---|---|
execution options |
||
|
|
script mode to run |
|
|
how many samples |
|
|
how many iterations per sample |
|
|
whether to only print last solution |
|
|
where to print solutions |
|
|
where to print statistics |
|
|
whether driver catches Ctrl-C |
|
|
which events to trace |
|
|
Comma separated pair of execution id and port number to connect to CPProfiler. |
Figure 12.2 Predefined commandline options, continued¶
option |
type |
explanation |
|---|---|---|
|
string |
branching options |
|
string |
general model options |
|
string |
propagation options |
|
string |
symmetry breaking options |
|
string |
search options |
Figure 12.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 12.1, Figure 12.2, and Figure 12.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.
Parsing options. The member function parse(argc,argv) reads options from argv and removes them, leaving the remaining arguments in argv. It stops at the first argument that it does not recognise and leaves that argument in place without a message. A misspelled option therefore goes unnoticed, and the program runs with its default values. A program that accepts only options can call parse_strict(argc,argv) instead: it reports the first unrecognised argument, prints the help text, and stops the program with an error. With SizeOptions and InstanceOptions, the size or the instance may follow the options; the size must be a number, and the instance must not start with a hyphen. The member function parse_permissive(argc,argv) is the same as parse(argc,argv). Strict parsing will become the default in a future major release, so a program that processes further arguments itself should call parse_permissive(argc,argv).
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(). The value can also name an instance file, see Reading instance files.
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:
solutionprints solutions together with some runtime statistics.timecan be used for benchmarking: average runtime and coefficient of deviation is printed, where the example is run-samplestimes. For examples with short runtime,-iterationscan 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).statprints short execution statistics.gistruns 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
gistwill be ignored and the modesolutionis 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).
12.2. Reading instance files¶
Scripts that solve benchmark instances can read them from files. The commandline driver uses Gecode’s instance reader for this: a short reader spec describes the layout of a textual format, and reading a file yields named values. A script supplies the spec for its format, typically as a string literal. The SAT, TSP, TSPTW, job shop, sudoku, advanced sudoku, and nonogram examples that come with Gecode contain specs for their formats.
Instance file options. An InstanceOptions object created with a reader spec as second argument reads instance files. The last value on the commandline then names a file, and the member function data() reads it and returns the values as an object of class Instance::Data. The file is read only once, so data() can be called both in main(), to report errors before solving starts, and in the script’s constructor. Errors in the file are reported by an exception of class Instance::Error. The member function is_file() tests whether the value names a readable file, and builtin(i) tests whether it is the number i of an instance built into the script, so a script can support both. The option -spec reads files with the spec in another file instead. The script may rely on the checks in its own spec, so a replacement spec must define the same data and perform the same checks. The option -param gives a value to a parameter of the spec as name=value. For several parameters, repeat the option or separate the pairs by commas, as in -param a=1,b=2. Program 12.1 sketches a SAT solver reading DIMACS CNF files. The driver library requires the instance library (gecodeinstance), so scripts that link the driver also link the instance library.
const char* dimacs = R"(format dimacs-cnf
comment "c"
line "p cnf {vars:int} {clauses:int}"
repeat clauses { list clause: int until 0 }
)";
class Sat : public Script {
BoolVarArray x;
public:
Sat(const InstanceOptions& opt) : Script(opt) {
Instance::Data d = opt.data();
int n = static_cast<int>(d.integer("vars"));
x = BoolVarArray(*this, n, 0, 1);
for (int c=0; c<d.size("clause"); c++) {
IntArgs literals = d.ints("clause", {c});
...
}
...
}
...
};
int main(int argc, char* argv[]) {
InstanceOptions opt("SAT", dimacs);
opt.parse(argc,argv);
try {
(void) opt.data();
} catch (const Instance::Error& e) {
std::cerr << e.what() << std::endl;
return 1;
}
Script::run<Sat,DFS,InstanceOptions>(opt);
return 0;
}
Instance data. Every value read has a name, a type (integer, float, or string), and a depth: scalars have depth 0, arrays depth 1, arrays of rows depth 2, and so on. Rows can have different lengths. The fields of repeated records are stored column-wise: for a job shop instance, machine and duration are arrays with one row per job. The member functions integer(), number(), and text() return single values, ints() and numbers() return arrays (or a row, when given row indices such as {3}), and size() returns lengths. If a file does not match its format, the message of the Instance::Error gives the file, line, and column, together with the place in the spec.
Some files contain several instances, such as the job shop collection jobshop1.txt from the OR-Library. A spec reads them with an instances block, and the parameter instance selects one by number or name: for example, job-shop -param instance=la01 jobshop1.txt. A file with a single instance needs no selection.
Reader specs. A spec is a sequence of statements that read the input from top to bottom. The spec for DIMACS CNF in the SAT example is:
format dimacs-cnf
comment "c"
stop "%"
line "p cnf {vars:0..gecode.int_max} {clauses:0..}"
repeat clauses {
list clause: -vars..vars until 0
}
The header line captures two integers. Their types are ranges, so vars must be a valid Gecode integer and clauses must not be negative. Each clause is then a list of literals ended by 0, which is not stored. The range -vars..vars rejects a literal that names no variable, and the error message gives the place in the file. A type can also be written int, float, or word, as in the sketch in Program 12.1.
The tool gecode-instance reads a file with a spec file (-spec) and prints a summary of the values or the values as MiniZinc data (-dzn), which helps when writing a spec. With -list it lists the instances in a file. The spec language is documented with the instance reader in the reference documentation.
12.3. Scripts¶
Scripts (see Script classes) are subclasses of Space that are designed to work together with option objects of class Options, SizeOptions, and InstanceOptions.
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).