m-driver.tex.in

% -*- mode: LaTeX; -*- 
\chapter{Script commandline driver}
\label{chap:m:driver}

The commandline driver (see \gecoderef[group]{TaskDriver})
provides support for passing common commandline options to
programs and a sub-class for spaces called \?Script? that can
take advantage of the options.

\paragraph{Overview.}

\mbox{}\autoref{sec:m:driver: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 \autoref{sec:m:driver:script}.

\begin{important}
Do not forget to add
\begin{code}
#include <gecode/driver.hh>
\end{code}
to your program when you want to use the script commandline
driver.
\end{important}

\section{Commandline options}
\label{sec:m:driver:options}

\begin{figure}
\begin{center}
\begin{tabular}{|l|l|l|}
\hline
option & type & explanation \\
\hline\hline
\multicolumn{3}{|c|}{propagation options}\\
\hline
\texttt{-ipl} &
$\{\mathtt{def},\mathtt{val},\mathtt{bnd},\mathtt{dom}\}$ &
integer propagation level\\
\hline\hline
\multicolumn{3}{|c|}{branching options}\\
\hline
\texttt{-decay} & \?double? & decay-factor\\
\texttt{-seed} & \?unsigned int? & seed for random numbers\\
\hline\hline
\multicolumn{3}{|c|}{search options}\\\hline
\texttt{-solutions} & \?unsigned int? & how many solutions ($0$ for all)\\
\texttt{-threads} & \?double? & how many threads \\
\texttt{-c-d} & \?unsigned int? & commit recomputation distance\\
\texttt{-a-d} & \?unsigned int? & adaptive recomputation distance\\
\texttt{-d-l} & \?unsigned int? & discrepancy limit for \?LDS?\\
\texttt{-node} & \?unsigned int? & cutoff for number of nodes\\
\texttt{-fail} & \?unsigned int? & cutoff for number of failures\\
\texttt{-time} & \?unsigned int? & cutoff for time in milliseconds\\
\texttt{-step} & \?double? & improvement step for floats\\
\hline\hline
\multicolumn{3}{|c|}{restart-based and portfolio search options}\\\hline
\texttt{-restart} &
$\{\mathtt{none},\mathtt{constant},\mathtt{linear},$ &
enable restarts, define cutoff\\
 &
$\;\mathtt{geometric},\mathtt{luby}\}$
& \\
\texttt{-restart-scale} &
\?unsigned int? &
scale-factor for cutoff values\\
\texttt{-restart-base} &
\?double? &
base for geometric cutoff values\\
\texttt{-nogoods} &
$\{\mathtt{false},\mathtt{true},\mathtt{0},\mathtt{1}\}$ &
whether to post no-goods\\
\texttt{-nogoods-limit} &
\?unsigned int? &
depth limit for no-good recording\\
\texttt{-assets} &
\?unsigned int? &
number of assets in a portfolio\\
\hline
\end{tabular}
\end{center}
\caption{Predefined commandline options}
\label{fig:m:driver:options:a}
\end{figure}

\begin{figure}
\begin{center}
\begin{tabular}{|l|l|l|}
\hline
option & type & explanation \\
\hline\hline
\multicolumn{3}{|c|}{execution options}\\\hline
\texttt{-mode} & $\{\mathtt{solution},\mathtt{time},\mathtt{stat},$ & script mode to run\\
        & $\;\mathtt{gist},\mathtt{cpprofiler}\}$ & \\
\texttt{-samples} & \?unsigned int? & how many samples\\
\texttt{-iterations} & \?unsigned int? & how many iterations per
sample\\
\texttt{-print-last} & $\{\mathtt{false},\mathtt{true},\mathtt{0},\mathtt{1}\}$ &
whether to only print last solution\\
\texttt{-file-sol} & $\{\mathtt{stdout},\mathtt{stdlog},\mathtt{stderr}\}$ &
where to print solutions\\
\texttt{-file-stat} & $\{\mathtt{stdout},\mathtt{stdlog},\mathtt{stderr}\}$ &
where to print statistics\\
\texttt{-interrupt} & $\{\mathtt{false},\mathtt{true},\mathtt{0},\mathtt{1}\}$ &
whether driver catches Ctrl-C\\
\texttt{-trace} &
$\{\mathtt{init},\mathtt{prune},\mathtt{fix},\mathtt{fail},\mathtt{done},$
& which events to trace\\
&$\;\mathtt{propagate},\mathtt{commit},\mathtt{none},\mathtt{all}\}$&\\
\hline
\texttt{-cpprofiler-id} & \?int? &
execution identifier for CPProfiler\\
\texttt{-cpprofiler-port} & \?unsigned int? &
port used to connect to CPProfiler\\
\texttt{-cpprofiler-info} & $\{\mathtt{false},\mathtt{true},\mathtt{0},\mathtt{1}\}$ &
whether to send node information\\
\hline
\end{tabular}
\end{center}
\caption{Predefined commandline options, continued}
\label{fig:m:driver:options:b}
\end{figure}

\begin{figure}
\begin{center}
\begin{tabular}{|l|l|l|}
\hline
option & type & explanation \\
\hline
\texttt{-branching} & string & branching options\\
\texttt{-model} & string & general model options\\
\texttt{-propagation} & string & propagation options\\
\texttt{-symmetry} & string & symmetry breaking options\\
\texttt{-search} & string & search options\\\hline
\end{tabular}
\end{center}
\caption{User-definable commandline options}
\label{fig:m:driver:options:user}
\end{figure}

The commandline driver provides classes
\gecoderef[class]{Options}, \gecoderef[class]{SizeOptions}, and
\gecoderef[class]{InstanceOptions} that support parsing
commandline options. All classes support the options as
summarized in \autoref{fig:m:driver:options:a},
\autoref{fig:m:driver:options:b}, and
\autoref{fig:m:driver:options:user}. 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 \texttt{-c-d}, \texttt{-a-d}, and \texttt{-d-l} the member
functions are named \?c_d()?, \?a_d()?, \?d_l()?.

The values for \?-threads? are interpreted as described in
\autoref{sec:m:search:options}.

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

\paragraph{Invoking help.}

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

\paragraph{Size and instance options.}

The class \gecoderef[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 \gecoderef[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()?.

\paragraph{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.

\paragraph{Mode options.}

The different modes passed as argument for the option \?-mode?
have the following meaning:
\begin{itemize}
\item \texttt{solution} prints solutions together with some
  runtime statistics.
\item \texttt{time} can be used for benchmarking: average runtime
  and coefficient of deviation is printed, where the example is
  run \texttt{-samples} times. For examples with short runtime,
  \texttt{-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).
\item \texttt{stat} prints short execution statistics.
\item \texttt{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
  \autoref{tip:m:comfy:conf} for how to find out about Gecode's
  configuration), the mode \texttt{gist} will be ignored and the
  mode \texttt{solution} is used instead.
\item \texttt{cpprofiler} runs the script in solution mode but
  also connects to the CPProfiler, see also
  \autoref{sec:m:search:cpprofiler}.  
  
  If Gecode has not been compiled with support for the CPProfiler (see
  \autoref{tip:m:comfy:conf} for how to find out about Gecode's
  configuration), the mode \texttt{cpprofiler} will be ignored and the
  mode \texttt{solution} is used instead.
\end{itemize}

\paragraph{Trace options.}

Which events to trace (see also \autoref{chap:m:group}) 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 \gecoderef[example]{money},
\gecoderef[example]{hamming}, and
\gecoderef[example]{descartes-folium}.

\paragraph{CPProfiler options.} For more details on the
CPProfiler, please consult \autoref{sec:m:search:cpprofiler} as
the commandline arguments are used exactly as described there.

\paragraph{Examples.}

For an example, in particular, how to use the user-defined
options, see \autoref{sec:m:comfy:driver}. As all examples that
come with Gecode use the script commandline driver, a plethora of
examples is available (see \gecoderef[group]{Example}).
Also adding additional options is straightforward, for an example see 
\gecoderef[example]{golf}.


\paragraph{Gist inspectors and comparators.}

The driver options can pass inspectors and comparators (see
\autoref{sec:m:gist:inspecting_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)?.

\section{Scripts}
\label{sec:m:driver:script}

Scripts (see \gecoderef[group]{TaskDriverScript}) are subclasses
of \?Space? that are designed to work together with option
objects of class \gecoderef[class]{Options} and
\gecoderef[class]{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 \autoref{sec:m:comfy:cost} and
\autoref{sec:m:minimodel:optimize}.

Subclasses of \?FloatMinimizeScript? and \?FloatMaximizeScript?
use the value passed on the command line option \?-step? as value
for the improvement step (see
\autoref{sec:m:minimodel:optimize:float}). For an example, see 
\gecoderef[example]{golden-spiral}.

As scripts are absolutely straightforward, all can be understood
by following some examples. For an example see
\autoref{sec:m:comfy:driver} or all examples that come with
Gecode, see \gecoderef[group]{Example}.