% This is suited for xdvi (using -paper a4r option) and for making a PDF file, including hyperlinks.

% Open questions:
%  - How to generate clear text hyperreferences in the in the foot line
%  - How to let automatically start xdvi in landscape mode: use option dvips!


\documentclass[a4paper,11pt,twoside]{book}
\usepackage{latexsym}
\usepackage[landscape,inner=2cm,outer=1.5cm,top=2.5cm,bottom=2.5cm]{geometry}
\usepackage{epsf,graphicx}
\usepackage{fancyhdr}
\usepackage{multicol}
\usepackage{makeidx}
\usepackage[hypertex,colorlinks=true,linkcolor=blue,extension=dvi,bookmarks,bookmarksnumbered,pdfpagemode=UseOutlines]{hyperref}


\renewcommand{\textfraction}{0}
\renewcommand{\topfraction}{1}
\setlength{\columnsep}{1cm}
%\fancyfoot[RE,LO]{\ref{slb_solve_shortest_path} \thepage}
%\lhead{\leftmark}
\fancyfoot[LE,RO]{\thepage}
\cfoot{}


\include{def}
\makeindex



\begin{document}
\pagestyle{empty}
\setcounter{page}{-1}
\makeatletter
\newenvironment{tablehere}
  {\def\@captype{table}}
  {}

\newenvironment{figurehere}
  {\def\@captype{figure}}
  {}
\makeatother

\thispagestyle{empty}
\begin{center}
\vspace*{0.01cm}
{\bf\Huge GOBLIN}

\vspace*{1cm}
{\bf\huge A Library for Graph Matching and
Network Programming Problems}

\vspace{1.0cm}
\epsfxsize=12cm
\epsfbox{stnumber.eps}

\vspace{1.0cm}
{\bf\huge Release 2.8 -- Reference Manual}

\medskip
\today
\end{center}



\cleardoublepage
\begin{multicols}{2}


\markboth{CONTENTS}{CONTENTS}
\tableofcontents



\cleardoublepage
\pagestyle{fancy}

\end{multicols}
\part{Introduction}
\thispagestyle{empty}
\begin{multicols}{2}
\pagestyle{fancy}

\markboth{GENERAL STATEMENTS}{SCOPE}
\chapter{General Statements}
\thispagestyle{fancy}
\section{Scope}

GOBLIN is a \verb/C++/ class library focussed on \nt{network programming
problems}. Roughly speaking, a network programming problem is a graph
optimization problem which can be solved efficiently by linear programming
techniques. More explicitly, GOBLIN includes solvers for the following
problems:
\begin{myitemize}
\item Shortest paths
\item Negative length cycles
\item Minimum mean cycles
\item Minimum spanning trees, arborescences and $1$-trees
\item Maximum packing with arborescences
\item Maximum $st$-flows and min-cost $st$-flows
\item Several types of minimum cuts and connected compenents
\item Feasible [min-cost] circulations and $b$-flows
\item Maximum cardinality  and min-cost (perfect) assignments
\item Directed Chinese postman problems
\item Transportation problems
\item Maximum cardinality and min-cost (perfect) matchings
\item Undirected Chinese postman problems and $T$-joins
\item (Weighted) $b$-matching problems
\item (Weighted) $f$-factor problems
\item (Weighted) capacitated $b$-matchings
\end{myitemize}
The library also includes algorithms for some NP-hard problems in graph theory,
namely:
\begin{myitemize}
\item $\Delta$-TSP, TSP and ATSP
\item Stable sets, vertex covers and maximum cliques
\item Graph colourings and clique partitions
\end{myitemize}
There is a generic branch and bound module which is applied for the metric TSP solver
and the computation of independent sets. Since GOBLIN does not support cutting planes, the solvers
cannot compare with state-of-the-art codes for these problems, but should work for
problems up to 100 nodes. 

Release 2.6 comes with a basic LP simplex code and a generic interface for
integration with more sophisticated LP solvers. So far, this module is
utilized by the min-cost flow solver only. Branch and cut applications will
follow.




\markright{HISTORY}
\section{History}
GOBLIN is result from the {\it Deutsche Forschungsgemeinschaft (DFG)} research
project {\it Balanced Network Flows}. This project is dedicated to the design,
analysis and implementation of algorithms for generalized matching problems. 

The extensive source code for network flow algorithms in GOBLIN is due to the
strong dependencies between network flow and matching problems: Some of the
matching algorithms explicitly require solvers for certain network flow
problems. Furthermore, the {\it layered shrinking graphs} which appear in our
matching code reuse the {\it layered auxiliary networks} which form part of the
well-known Dinic max-flow method.



\markright{PURPOSE AND APPLICATIONS}
\section{Purpose and Applications}

GOBLIN has been designed for researchers, developers, people who just need to
solve network flow or matching (sub)problems, but also for educational
purposes. Since the needs of all these potential users are sometimes
contradictory,
GOBLIN provides several configuration mechanisms, both at compile time and at
runtime:

The GOBLIN runtime configuration includes the selection of logging information,
of graph layouts, of tracing breakpoints and of the mathematical methods and
the data structures which are used.

The graphical display together with the logging module allows the rapid
preparation of adequate runtime examples for teaching and documenting network
programming algorithms. Of course, this functionality is also helpful for the
debugging of such algorithms.

Before GOBLIN is compiled, one may edit the file \verb/config.h/ in order to
suppress the compilation of this GOBLIN functionality which is not needed for
the final version of a problem solver, but which causes considerable
computational overhead and large binaries.

Note that this compile time configuration is possible only with open source
software. Hence the open source concept is an important prerequisite for
the success of this project.

The library comes with source code for executable solver programs which support
the runtime configurability. The experienced \verb/C++/ programmer, however, will
find it easy to build GOBLIN problem instances immediately from his domestic
data structures.

The library also comes with source code for a Tcl/Tk based interpreter
\verb/gosh/ which can process complex scripts and user interactions, and with
the graphical front end \verb/goblet/. Both parts heavily depend on the open
source Tcl/Tk library which must be installed to get the full functionality
of GOBLIN.


\markright{PROJECT OVERVIEW}
\section{Project Overview}

\begin{figurehere}
\begin{center}
\epsfxsize=8cm
\epsfbox{design.eps}
\vspace{0.5cm}
\caption{\label{flb_design}$3$-Level Architecture}
\end{center}
\end{figurehere}

\noindent
The GOBLIN programming project essentially splits into four parts each of
which provides its own interface to the graph optimization methods of the
GOBLIN library:
\begin{itemize}
\item The C++ Class library (64000 lines of source code)
\item An extension of the Tcl/Tk shell sript language to graph objects (6000
    lines)
\item A graph browser and editor tool (13000 lines)
\item Solver executables (2000 lines)
\end{itemize}
Here we have listed the respective source code sizes which may indicate the
efforts of implementation. The Tcl wrapper is indeed a rather simple
task and strongly recommended for other mathematical programming projects.
Generally, the GOSH shell is compliant with other Tcl/Tk extensions. One only
has to merge the project file \verb/goshAppInit.cpp/ and the other
\verb/AppInit/ file. Alternatively, one can build a shared object and load the
library dynamically into a Tcl shell.

This document describes the C++ API of the library functions and the Tcl
wrapper extensively. The solver programs and the graph browser GOBLET are
discussed within a few pages only.


\markright{FUNDAMENTAL LIBRARY CONCEPTS}
\section{Fundamental Library Concepts}

The design of the GOBLIN library follows the object-oriented paradigm.
This means a rather restrictive data encapsulation in order to obtain:
\begin{myitemize}
\item compliance with other mathematical libraries, especially LP-Solvers.
\item a user interface which is as simple as possible.
\end{myitemize}
Merely the configuration parameters associated with controller objects are
public.

The extensive use of polymorphisms leads to a class hierarchy which is
adequate and intuitive from the point of view of mathematics: High-level
methods are separated from data structures, and problem transformations are
established by separate classes.

In general, the C++ implementation of mathematical algorithms is somewhat
slower than straight C code. This stems from so-called {\bf late binding
operations} which assign a method name to a method implementation at runtime.

On the other hand, polymorphism eases the development and debugging of new
algorithms a lot. Even more, this mechanism is compliant with the idea of open
source projects where nobody is responsible for the correctness of the source
code: Every new algorithm which uses an old part of the library is a
certificate that this old code fragment works correctly.

We tried a careful trade off between a C and C++ like implementation. That is,
to some extent we ignore the OO paradigm: Nodes and arcs are base types, and
vectors are implemented as ordinary arrays.

We briefly describe the various classes of GOBLIN: The design distinguishes
between graph objects, iterator objects, explicit data structures which are all
{\bf data objects}, and {\bf controller objects} which allow to select
solution methods as well as logging information and tracing points. Controllers
also keep track of the dependencies among the various data objects.

The term {\bf explicit data structure} shall indicate that such objects have
a meaning which is independent from graph theory. Apart from this, there are
implicit data structures such as incidence lists, subgraphs, distance labels
etc. which are encapsulated in graph objects. The explicit data structures
are discussed in Chapter \ref{clb4}, the implicit ones in Chapter \ref{clb_proto}.

The GOBLIN design is completed by {\bf export} and {\bf import} objects
which manage the file interface of GOBLIN.



\markright{MATHEMATICAL REFERENCES}
\section{Mathematical References}
\label{slb_mathref}

Most GOBLIN algorithms are based on the textbooks
\begin{quote}
Network Flows \\
R.K.Ahuja, T.L.Magnanti, J.B.Orlin \\
Prentice Hall (1993)
\end{quote}
\begin{quote}
Combinatorial Optimization \\
W.J.Cook, W.H.Cunningham, W.R.Pulleyblank, A.Schrijver \\
Wiley (1998)
\end{quote}
\begin{quote}
Graphs, Networks and Algorithms \\
D.Jungnickel \\
Springer (1999)
\end{quote}
and
\begin{quote}
Graphs and Algorithms \\
M.Gondran, N.Minoux \\
Wiley (1984)
\end{quote}
The matching code is described in a series of papers of Christian Fremuth-Pager
and Dieter Jungnickel:
\begin{quote}
Balanced Networks Flows (I):
    A unifying framework for design and analysis of matching
    algorithms. Networks, 33::1-28, 1999

Balanced Networks Flows (II):
    Simple augmentation algorithms. \\
    Networks, 33::29-41, 1999

Balanced Networks Flows (III):
    Strongly polynomial algorithms. \\
    Networks, 33::43-56, 1999

Balanced Networks Flows (V): Cycle canceling algorithms. \\
    Networks, 37::202-209, 2001

Balanced Networks Flows (VII): Primal-dual algorithms. \\
    To appear in Networks

\end{quote}
which constitute part of the theoretical output of the mentioned DFG project.


\markright{CONTRIBUTIONS}
\section{Contributions}
\label{slb_contrib}

The core library has been written and is maintained by Dr. Christian
Fremuth-Paeger (University of Augsburg). The same applies for this reference
manual and the GUI application.

The following people have reviewed earlier versions of this reference manual:
Dr. Andreas Enge (now at Ecole Polytechnique, Paris), Prof.Dr. Dieter
Jungnickel and Priv.Doz. Bernhard Schmidt (both at the University of Augsburg).

Andreas Hefele (University of Augsburg) has tested Release 2.1, Bernhard
Schmidt has tested the releases 2.2, 2.5 and 2.6. Markus Eisensehr (KUKA
Controls Augsburg) and Bernhard Schmidt (University Augsburg) have tested
the Windows XP setup of release 2.7.

Many thanks to Dr.Petra Huhn (University of Augsburg), Priv.Doz. Dirk
Hachenberger (University of Augsburg) and Priv.Doz. Bernhard Schmidt for
several helpful talks and their suggestions. Bernhard Schmidt has also
contributed the GOBLET overview to this document.

Prof. Fernando de Oliveira Durao (Technical University of Lisboa)
has prepared a self-installing GOBLET 2.5 package for Windows 98/2000/XP.

The tree packing method and the ATSP subgradient optimization which is new
in GOBLIN 2.2 is written by Markus Schwank (University of Augsburg).

The basic LP simplex code which is attached to this release has been
written by Priv.Doz. Bernhard Schmidt and integrated by Christian
Fremuth-Paeger.

Birk Eisermann (University Augsburg) has contributed a planarity test, a
makefile revision and a doxygen configuration file for release 2.6.2.

Further informations about code authors can be obtained by using the module
browser in the GOBLET application.


\markright{READING THIS DOCUMENT}
\section{Reading this document}

This reference guide is extensive, but not exhaustive. For example, exception
and const declarations have been generally omitted, and class member variables
are described only is a few cases.

We are currently growing a doxygen reference which should close the gaps and which
might be more timely on the long run. See the installation part of this document
(Section \ref{slb_make}) how the doxygen reference can be extracted from your
source code distribution.



\cleardoublepage
\markboth{INSTALLATION}{LICENCE AGREEMENT}
\chapter{Installation}
\thispagestyle{fancy}
\label{clb11}
% Most recent revision: CFP, 2005-11-30

\markright{LICENCE AGREEMENT}
\section{Licence Agreement}

The GOBLIN core library was written by
\begin{quote}
Christian Fremuth-Paeger \\
Department of Mathematics \\
University of Augsburg, Germany

\medskip
E-Mail: Fremuth@Math.Uni-Augsburg.DE

\medskip
(C) Dr. Christian Fremuth-Paeger et al. 1998-2005
\end{quote}
For details about the contributions by other authors see Section
\ref{slb_contrib}. All copyrights remain with the authors.

GOBLIN is open source software and covered by the GNU Lesser Public License
(LGPL). That is, GOBLIN may be downloaded, compiled and used for scientific,
educational and other purposes free of charge. For the details, in particular
the statements about redistribution and changes of the source code, note the
\verb/LGPL/ document which is attached to the package.


\markright{SOFTWARE REQUIREMENTS}
\section{Software Requirements}

To unpack and compile the GOBLIN library, the following software is necessary:
\verb/gzip/, \verb/tar/, \verb/gmake/ and a C++ compiler, preferred \verb/gcc/.
All tools should be available on any UNIX machine, and existence can be verified
by typing \verb/which <toolname>/.

We have verified the compilation of the core library in the following environments:
\begin{itemize}
\item Suse Linux 7.3 with GNU C++ 2.95.3 (GOBLIN 2.6.4)
\item Suse Linux 10.0 with GNU C++ 4.0.2 (GOBLIN 2.8)
\item Redhat Linux 7.3 with GNU C++ 2.96 (GOBLIN 2.5)
\item Redhat Linux 8.0 with GNU C++ 3.2 (GOBLIN 2.5.3)
\item Solaris 5.6 with GNU C++ 2.8.1 (early GOBLIN versions)
\item Aix 4.3 with GNU C++ (early GOBLIN versions)
\item Aix 4.3 with xlC (GOBLIN 2.8)
\item Cygwin 1.5.9 with GNU C++ 3.3.1 (GOBLIN 2.6.4)
\item Cygwin 1.5.21 with GNU C++ 3.4.4 (GOBLIN 2.8)
\end{itemize}
To run the graphical tool GOBLET, one also needs to compile the \verb/gosh/
shell which in turn requires some implementation of POSIX threads and a Tcl/Tk
installation. From the latter, the \verb/wish/ interpreter is not used directly,
but the library files \verb/libtcl*.*/ and \verb/libtk*.*/ are linked with the
new shell tool.

It has turned out that Tcl/Tk is widely available, but most system come with
a Tcl library which does not support multiple threads of execution. One can
either ignore this fact (on some platforms, the GUI is stable even then),
recompile from the sources or install a distribution from
\begin{verbatim}
    http://www.activestate.com/Products/ActiveTcl/
\end{verbatim}
Sometimes, unreachable or even missing Tcl/Tk or X11 headers occur. The
latter happens with the default package selections for linux and cygwin
distributions which split Tcl/Tk in two or more packages.

To compile this reference manual, a \verb/latex/ installation is needed.
Finally, we recommend to install the graphical tools \verb/xv/ and \verb/xfig/
which supply GOBLET with several export filters, especially the postscript
filter needed for printing. The \verb/xfig/ canvas drawing tool is useful for
the postprocessing of figures also.

Problem solvers can be compiled and linked even if the Tcl/Tk package is not
present, but the possible graphical output has to be processed manually then.
In particular, the \verb/.fig/ files can be input to the \verb/xfig/ drawing
tool.



\markright{UNPACKING}
\section{Unpacking the Source}

The source code is coming as a single zipped file \verb/goblin.<version>.tgz/
which can be extracted from a shell prompt by typing
\begin{verbatim}
    tar xfz goblin.<version>.tgz
\end{verbatim}
and then generates a folder goblin.<version> including the Makefile. With elder
\verb/tar/ versions, it may be necessary to extract the file in two steps:
\begin{verbatim}
    gunzip goblin.<version>.tgz
    tar xf goblin.<version>.tar
\end{verbatim}




\markright{CONFIGURATION}
\section{Configuration}
% Most recent revision: CFP, 2005-11-30

Throughout this document, especially in Chapter \ref{clb7}, we will describe
the run time configurability of the core library. This section adresses some
some possibilities for configuration at compile time by means of the source
file \verb/configuration.h/, and the general build options by means of
\verb/Makefile.conf/.

The latter file is intended to do the platform dependent settings. Currently,
only Linux and Windows/Cygwin are well-supported. Advanced Unix users will find
it obvious how to configure the compiler and linker for their own Unix platform.
There are some more build parameters to set but some options are experimental,
and the default values achieve the most stable code.

This \verb/Makefile.conf/ has been set up to run on a SuSE linux machine with
default parameters. Cygwin and Aix are explicitly supported, that is, editing
the platform specifier \verb/os/ in should be sufficient. Generally, before
applying the \verb/Makefile/, you have to edit some further lines in it. You
may specify your compiler \verb/CC/ and \verb/CXX/, the linker \verb/LD/, the
compression tool \verb/zip/ and the linkage names of the Tcl/Tk libraries
\verb/libtcl/ and \verb/libtk/ which are installed on your machine. Probably,
you need to change only some of of the defaults. If no Tcl/Tk libraries are
available, you may build the GOBLIN library but not the the GOSH interpreter
and the shared objects.

The file \verb/configuration.h/ contains some pragmas which may help to improve
the performance and/or stability of the final C++ code. Probably it is not
worth reading the following lines unless you encounter respective problems.

First at all in this file, the index types \verb/TNode/, \verb/TArc/ are
declared implicitly. You can choose from three different scalings
by uncommenting one of the rows
\begin{verbatim}
    // #define _SMALL_NODES_
    // #define _BIG_ARCS_
    // #define _BIG_NODES_
\end{verbatim}
The scaling which is adequate for your purposes depends on the kind of
problems you want to solve: A large scale (but solvable in a few minutes)
spanning tree problem may have several 10000s of nodes, and hence requires the
\verb/_BIG_NODES_/ pragma. On the other hand weighted matching problems
which have a few 1000s of nodes, would require the \verb/_BIG_ARCS_/
pragma.

The default configuration is chosen to support the full functionality of GOBLIN.
If you want to compile the final version of a problem solver, you may delete
the pragma definitions
\begin{verbatim}
    #define _LOGGING_
    #define _FAILSAVE_
    #define _TRACING_
    #define _HEAP_MON_
\end{verbatim}
from the file \verb/configuration.h/.
In our experience, this may decrease the running times by somewhat like 30
percent. The final code is much smaller, too. We mention what is lost if these
pragmas are unset:

The \verb/_LOGGING_/ pragma filters only the low level logging information.
The \verb/_FAILSAVE_/ pragma enables or disables most error detections,
including wrong instrumentation of the C++ API and excluding some buffer
overflows. This pragma seems to be the most important for code optimization,
but if your solver includes any bugs, you have to recompile the entire library
to get some hints. The \verb/_HEAP_MON_/ define enables the compilation of
special versions of \verb/new/ and \verb/delete/ and should be omitted in case
of incompatibility with other C++ modules.

If the \verb/_TRACING_/ pragma is not present, the graphical display and the
options \verb/traceLevel>1/ are disabled. The option \verb/traceLevel==1/ which
helps you to decide whether your solver is still alive works even then. If the
GOSH interpreter is compiled without the \verb/_TRACING_/ pragma, the GOBLET
graph browser does not produce trace files.



\markright{THE MAKEFILE}
\section{The Makefile and UNIX Installation}
\label{slb_make}

The GOBLIN \verb/Makefile/ controls the compilation and linkage of the library,
the GOSH shell tool and the executable solvers, the generation of this
documentation and the generation of new GOBLIN packages, which either include
all sources or binaries.

In what follows, it is supposed that your current working directory is the root
directory of the source code distribution. The GOBLIN library \verb/libgoblin.a/
is then generated from console prompt by typing:
\begin{verbatim}
    gmake goblin
\end{verbatim}
As the next step of GOBLIN installation, generate the GOSH shell interpreter.
For this goal, set in \verb/Makefile/ the variables \verb/libtcl/ and
\verb/libtk/ to the Tcl/Tk versions installed on your machine, and then type
\begin{verbatim}
    gmake
\end{verbatim}
Similarly,
\begin{verbatim}
    gmake shared
\end{verbatim}
creates a shared object \verb/libgoblin.so/ which includes the core library
functions in \verb/goblin.a/ plus the Tcl/Tk command registrations, and which
can be dynamically loaded into the original \verb/tclsh/ shell. The call
\begin{verbatim}
    gmake manual
\end{verbatim}
produces the two files \verb/mgoblin.<version>.ps/ and
\verb/mgoblin.<version>.pdf/. This is the reference manual which
you are just reading. The document can be viewed and printed by using:
\begin{verbatim}
    ghostview mgoblin.<version>.ps &
\end{verbatim}
or
\begin{verbatim}
    acroread mgoblin.<version>.pdf &
\end{verbatim}
Once the shell tool is available, one can start the GUI by typing
\verb!./goblet!, but this works from the \verb/Makefile/ directory only. If you
don't have root privileges, exectute the \nt{personal installation} by typing
\begin{verbatim}
    gmake private
\end{verbatim}
or
\begin{verbatim}
    gmake privclean
\end{verbatim}
where the second command also deletes the C++ source files and the build
resources. Add the new \verb/bin/ directory to your \verb/PATH/ variable and
the \verb/lib/ directory to \verb/LD_LIBRARY_PATH/ in your user profile.
To perform a \nt{system installation}, become a super user and then type
\begin{verbatim}
    gmake install
\end{verbatim}
The default installation directories are \verb!/usr/lib!, \verb!/usr/include!
and \verb!/usr/bin!. Take care to set up these directories if you are working
in a system other than linux. Any existing installation (if it is not too old)
is properly removed from the system. One can manually delete a system
installation by typing
\begin{verbatim}
    gmake sysclean
\end{verbatim}
or, if the \verb/Makefile/ is not available, by executing
\begin{verbatim}
    sh /usr/bin/goblin_uninstall.sh
\end{verbatim}
A binary distribution, say \verb/goblin.<version>.<platform>.tbz2/, is installed
as follows: Become a super user, copy the archive to the file system root
directory \verb!/!, change to this directory and type in
\begin{verbatim}
    tar xfj goblin.<version>.<platform>.tbz2
\end{verbatim}
and then
\begin{verbatim}
    sh goblin_install.sh
\end{verbatim}
The \verb/gmake install/ command discussed before exactly generates such a
binary distribution (via the \verb/gmake bin/ option) and then tries to
execute the \verb/goblin_install.sh/. So there is good hope that your package
will install also on other machines. If you have made changes to the source
code, you may like to bind a new GOBLIN tarball by typing:
\begin{verbatim}
    gmake pkg
\end{verbatim}
The resulting package includes the source code for the library and the
executables, the latex sources for the reference manual including the figures,
the tk scripts, the definition files for the examples, and a file
\verb!doku/history! which keeps track of the ancestor tarballs.

This GOBLIN package contains some source code which helps to generate
executable solvers for various optimization problems. In the same manner,
one can obtain some instance generators. The respective project names are
listed in Table \ref{tlb_exe} and coincide with the
file names for the main routines. If you just need a problem solver,
say \verb/optflow/, you may generate this executable by typing:
\begin{verbatim}
    gmake exe pr=optflow
\end{verbatim}
For all purposes, \verb/gmake/ must be called from the GOBLIN root directory
where the produced files can be found. On linux computers and in a CYGWIN
environment, one can type \verb/make/ instead of \verb/gmake/. On other UNIX
platforms, \verb/make/ possibly cannot interprete the \verb/Makefile/.


\begin{tablehere}
\begin{center}
\begin{tabular}{|l|l|}
\hline
Project Name        & Purpose \\
\hline
\hline
\verb/optmatch/     & All kinds of matching problems \\
\hline
\verb/optflow/      & Max-Flow, feasible $b$-flows and min-cost flows \\
\hline
\verb/postman/      & Directed and undirected Chinese Postman Problem \\
\hline
\verb/mintree/      & Minimum spanning trees and $1$-trees \\
\hline
\verb/gsearch/      & Shortest paths and shortest path trees \\
\hline
\verb/connect/      & (Strongly) connected components \\
\hline
\verb/opttour/      & Heuristics and lower bounds for the (metric) TSP \\
\hline
\verb/colour/       & Heuristic colouring \\
\hline
\verb/optbflow/     & Maximum and min-cost balanced $st$-flows \\
\hline
\end{tabular}
\end{center}
\caption{\label{tlb_exe}Executable Solver Programs}
\end{tablehere}


\markright{TCL COMPATIBILITY}
\section{Tcl Compatibility Issues}

Generally, GOBLIN can be linked with every Tcl/Tk 8.x release. Since Tcl/Tk 8.4,
a minor patch of the \verb/Makefile.conf/ is necessary: Activate the define
\begin{verbatim}
    tcl_flags = -D_CONST_QUAL_="const"
\end{verbatim}
to compensate some changes of the Tcl prototypes between the releases 8.3 and
8.4.


\markright{CYGWIN BUILD}
\section{Cygwin Build}

Cygwin is an environment which admits to compile and/or run Unix software
on Windows machines. Similar to Linux distributions, Cygwin can be downloaded
from internet and installed online. A setup program can be found at:
\begin{verbatim}
    http://www.redhat.com/download/cygwin.html
\end{verbatim}
The first manual and non-trivial step is to choose from a large set of module
packages. In view of the later GOBLIN installation, select the following
packages:
\begin{itemize}
\item \verb/gmake/
\item \verb/gcc/ and \verb/gpp/, including the libraries
\item \verb/TclTk/ (for building the gosh shell)
\item \verb/X11devel/ (included by the Tcl/Tk header)
\item \verb/transfig/, \verb/ghostscript/ and \verb/netpbm/
      (only for the graphical export of images from GOBLET)
\end{itemize}
The setup will detect package dependencies and hence add a lot of further
packages to your selection. So far, \verb/netpbm/ does not form part of the
standard Cygwin installation and hence must be downloaded separately. It is
not required to install a \verb/X/ server.

In a final installation step, one has to extend the Windows system variables:
Provided that the Cygwin installation directory is \verb/c:\cygwin/, the
\verb/Path/ system variable must be extended by a sequence
\begin{verbatim}
    ;c:\cygwin\bin;c:\cygwin\usr\X11R6/bin
\end{verbatim}
and an environment variable
\begin{verbatim}
    HOME=c:/cygwin/home
\end{verbatim}
should be added. Now, Windows is prepared to build the GOBLET graph browser.
Before compiling the gosh interpreter, just set \verb/os = cygwin/ in the
\verb/Makefile/. Then start a \verb/bash/ shell and follow the description of
the previous section.

Starting with Release 2.7, we will also distribute Cygwin binaries with each
major build. This makes some of the comments obsolete, but the packages
\verb/TclTk/, \verb/transfig/, \verb/ghostscript/ and \verb/netpbm/ are still
required. Start a \verb/bash/ shell or command prompt, copy the downloaded file
to the Cygwin (not Windows!) root directory, change to this directory in the
shell and type in:
\begin{verbatim}
    tar xfj goblin.<version>.tbz2
\end{verbatim}


\markright{WINDOWS SETUP PACKAGE}
\section{Windows Setup Package}

There are currently some efforts to make GOBLIN run out of the box on Windows
machines. The preliminary setup which is available consists of a compact
Cygwin environment, not just a Cywin dll. Unfortunately, this package does not
run with any concurrent Cygwin installation because of the \verb/path/ variable
extensions. Especially, \verb/latex/ makes trouble.

To be safe with other programs running Cygwin, check the Windows registry for
\verb/cygwin/ keys and values before executing the setup. If you have trouble
when starting the GOBLET graph browser, check the \verb/path/ directories for
other \verb/cygwin1.dll/'s and occasionally change the order of directories.

If you are already working with Cygwin, do not run the setup but revert to the
description of the previous section.

Since the \verb/tar/ and \verb/bunzip2/ tools forms part of the GOBLIN setup,
an existing installation can be 'patched' with subsequent versions of the
\verb/goblin.<version>.cygwin.tbz2/ binary distribution (It is not really a
patch since all GOBLIN specific files will be replaced).

We mention that there are intrinsic problems with file names including blanks.
The graph browser can handle this in the most cases but we did not find a way
to save a GIF bitmap to a file in \verb/Documents and settings/ yet.



\markright{DOWNLOAD}
\section{Download of new GOBLIN Versions}

New versions of GOBLIN will be distributed via the internet, URL:
\begin{verbatim}
    http://www.math.uni-augsburg.de/~fremuth/goblin.html
\end{verbatim}
The project is presented at
\begin{verbatim}
    http://www.freshmeat.net
\end{verbatim}
under the project name \verb/goblin/. By subscribing to the project, you
obtain regular infos about updates via e-mail. Do not miss to make a project
rating!


\markright{BUG REPORTS}
\section{Bug Reports}

The authors appreciate any kind of suggestions and bug reports. E-mail to:
\begin{verbatim}
    goblin@math.uni-augsburg.de
\end{verbatim}
In the folder \verb/project/ of this installation, you can find a form for bug
reports.



\cleardoublepage
\markboth{GETTING STARTED}{THE GOBLET GRAPH BROWSER}
\chapter{Getting Started}
\thispagestyle{fancy}

This chapter will give you a first idea of how GOBLIN can apply to your own
graph optimization problem. More explicitly, it describes the four different
interfaces to the GOBLIN library functions by some instructive examples.


\markright{THE GOBLET GRAPH BROWSER}
\section{The GOBLET Graph Browser}
GOBLET is the graphical user interface to the GOBLIN library. It can be used
to edit graphs, to configure the core library, to run problem solvers and
to view the computational results. This graphical output can be printed, and
exported to bitmaps but also to canvases.

First, try the following example: Change to the root directory of the GOBLIN
installation
\footnote{If you are working with a system installation, you can download and
unpack the sources to get access to the samples library.}
and type in:
\begin{quote}
\begin{verbatim}
goblet samples/strong4
\end{verbatim}
\end{quote}
Up to the missing node colours, the browser starts with a screen as depicted
in Figure \ref{flb_goblet}. The main window is structed as follows:
\begin{itemize}
\item The leftmost icon bar refers to general tools for file management,
switches for the various operating modes, a reset button for the messenger
and a start/stop button for the problem solvers. By clicking on the camera,
you can save the current graph object into a trace image. This tool bar is
always available.
\item The second icon bar and the canvas region form the built-in graph editor.
The editor mode is default, but if no geometric embedding is available, GOBLET
starts with the messenger window instead.
\item The bottom line displays the operating mode, some status info depending
on the operating mode and, rightmost, an info about the usage of ressources.
\end{itemize}
Now click on the \verb/Optimize/ menu and, in that menu, select
\begin{quote}
\begin{verbatim}
Connectivity... -> Strong Edge Connectivity -> Go
\end{verbatim}
\end{quote}
If nothing went wrong, the configuration shown in Figure \ref{flb_goblet}
results in which the strong components are represented by node colours.

\bigskip
\begin{figurehere}
\begin{center}
\includegraphics*[scale=0.5]{goblet.ps}
\vspace{0.5cm}
\caption{\label{flb_goblet}GOBLET}
\end{center}
\end{figurehere}

\noindent
Next, type \verb/Control-d/ in order to switch to the navigator mode. You now
can access a couple of images which illustrate the process of computing the
strong components. More explicitly, these images show the iterated depth first
search trees. If you like, you can print any of the displayed images by typing
\verb/Control-p/.

If you do not like to generate such intermediate results, you can turn off the
tracing functionality by selecting:
\begin{quote}
\begin{verbatim}
Browser -> Tracing Options...
    -> No Tracing -> Reset -> Done
\end{verbatim}
\end{quote}
If you want to see a descriptive log file, select
\begin{quote}
\begin{verbatim}
Browser -> Logging Options...
    -> Detailed Information -> Done
\end{verbatim}
\end{quote}
restart the computation by \verb/Control-c/ and display the log file by
\verb/Control-l/. In this example, the logfile does not provide much additional
information compared with the figures. In general, it contains informations
about recursive method calls, search orders, variable assignments and, which is
also helpful, about the writing of trace images.

\bigskip
\begin{figurehere}
\begin{center}
\includegraphics*[scale=0.5]{browse.ps}
\vspace{0.5cm}
\caption{\label{flb_browse}GOBLET Browser}
\end{center}
\end{figurehere}

\noindent
Suppose you want to make the graph strongly connected. You can add some arcs
by selecting \verb/Edit -> Insert Arcs/. For example, click with the left
mouse button on the node $23$, place some interpolation nodes, and then click
on the node $20$. Finally, you are asked to specify the placement of arc
labels (click with the left button again) which is immaterial in this example.

These manipulations result in a new graph arc $(23,20)$. You may run the
computation with \verb/Control-c/ again, and observe that the number of strong
components effectively reduces. Try and find out how many arcs must be added
to the original graph to make it strongly connected!

\bigskip
\begin{figurehere}
\begin{center}
\includegraphics*[scale=0.5]{edit.ps}
\vspace{0.5cm}
\caption{\label{flb_edit}GOBLET Editor}
\end{center}
\end{figurehere}

\noindent
We do not give a complete description of the GOBLET editor tool here.
The status line helps you stepping through the chosen editor function.
The most GOBLET menus and dialogs are intuitive, and this document describes
the various components of the GOBLIN library rather than the tool GOBLET.

Note that GOBLET may handle graph objects without any geometrical embedding,
but does not provide sophisticted tools for graph layout. Be careful when
tracing a computation: Without any special effort, GOBLET may generate several
thousands of files and, by that, cause a collapse of your file system.


\markright{GOSH SHELL SCRIPTS}
\section{GOSH Shell Scripts}

The GOSH shell script interpreter extends the well known Tcl/Tk script
language by the possibility of defining and manipulating graph objects.
Tcl/Tk is an excellent tool to prepare prototype algorithms, instance
generators and import/export filters with a minimum of code and effort.
\begin{mysample}
\begin{verbatim}
set n [lindex $argv 0]

goblin sparse graph G

for {set i 1} {$i<=$n} {incr i} {
    for {set j [expr $i+1]} {$j<=$n} {incr j} {
        set node($i-$j) [G node insert]

        for {set k 1} {$k<$i} {incr k} {
            G arc insert $node($i-$j) $node($k-$j)
        }

        for {set k [expr $i+1]} {$k<$j} {incr k} {
            G arc insert $node($i-$j) $node($i-$k)
        }

        for {set k 1} {$k<$i} {incr k} {
            G arc insert $node($i-$j) $node($k-$i)
        }
    }
}

set FileName [file rootname [lindex $argv 1]]
G write "$FileName.gob"
G delete

exit
\end{verbatim}
\end{mysample}
This script generates so-called {\bf triangular graphs}\index{triangular graph}
which are interesting for their regularity. The message
\verb/goblin sparse graph G/ instanciates a graph object \verb/G/ which is
written to file and
disallocated again by the messages \verb/G write/ and \verb/G delete/
respectively. Before file export, some node and arc insertion operations occur
which will not be explained in detail.
\begin{mysample}
\begin{verbatim}
set fileName [file rootname [lindex $argv 0]]

set file [open "$fileName.max" r]
goblin sparse digraph G
set n 0

while {[gets $file thisLine] >= 0} {
    if {[scan $thisLine "p max %d %d" n m]==2} {
        for {set i 1} {$i<=$n} {incr i} {G node insert}
    }

    if {[scan $thisLine "n %d %s" u type]==2} {
        if {$type=="s"} {set source [expr $u-1]}
        if {$type=="t"} {set target [expr $u-1]}
    }

    if {[scan $thisLine "a %d %d %d" u v cap]==3} {
        if {$n==0} {
            puts "File conversion failed!"
            exit 1
        }

        set a [G arc insert [expr $u-1] [expr $v-1]]
        G arc $a set ucap $cap
    }
}

close $file

if {$source=="*" || $target =="*"} {
   puts "Missing source and/or target node!"
   exit 1
}

G maxflow $source $target
\end{verbatim}
\end{mysample}
This script reads a graph from a foreign file format, namely the DIMACS max
flow format, and computes a maximum $st$-flow.

These two examples illustrate how graph objects can be manipulated easily from
within a Tcl/Tk/GOSH script. On the other hand, the variable substitution is
sometimes difficult to read, and long scripts are more difficult to handle
than equivalent C++ code. 



\markright{USING THE LIBRARY}
\section{Using the Library}

The bulk of this reference manual deals with the C++ library objects and
methods. This is so since direct application of the library produces the most
efficient code. Of course we also want to give other researchers the
opportunity to develop the GOBLIN library further.
\begin{mysample}
\begin{verbatim}
graph G((TNode)0,(TOption)0);
TNode **node = new TNode*[n];

TNode i = NoNode;
for (i=0;i<n;i++)
{
    node[i] = new TNode[n];
    TNode j = NoNode;
    for (j=i+1;j<n;j++)
    {
        node[i][j] = G.InsertNode();

        TNode k = NoNode;
        for (k=0;k<i;k++)
            G.InsertArc(node[i][j],node[k][j]);
        for (k=i+1;k<j;k++)
            G.InsertArc(node[i][j],node[i][k]);
        for (k=0;k<i;k++)
            G.InsertArc(node[i][j],node[k][i]);
    }
}

delete[] node;
\end{verbatim}
\end{mysample}
This C++ code is equivalent to the described GOSH script given before which
generates a triangular graph for a set with $n$ elements. Using this instance
generator as a benchmark indicates that C++ code is almost five times faster
than equivalent Tcl code.



\markright{SOLVER EXECUTABLES}
\section{Solver Executables}

GOBLIN comes with source code for solver executables. These main routines do
not cover the entire GOBLIN functionality, but only the most frequently asked
standard problem solvers. To work with these solvers, you must compile them
separately (see Section \ref{slb_make}).

You can customize the main routines which are distributed with the GOBLIN
source code to your own convenience without much effort. This is probably the
easiest way to become familiar with the library.

But note that every additional binary may include a lot of library functions,
and hence require a lot of disk space. Moreover, if you want to call a GOBLIN
solver from another C/C++ program, you may waste a lot of cpu time and disk
space for the file export and import.


\cleardoublepage
\markboth{GOBLET}{GOBLET}
\chapter{The GOBLET Graph Browser}
\thispagestyle{fancy}
% Latest revision: CFP, 07.11.2005

This chapter gives an rough overview about the graphical front end of the
GOBLIN library. The GOBLET browser has been designed to test and debug new
implementations of graph algorithms, to visualize standard graph methods in
undergraduate courses and just to play with the combinatorial structure of
graphs.

Intentionally, GOBLET is no graph drawing software. But in order to have a
self-contained tool, we have added a graph editor. All graph layout methods
provided by the core C++ library can be accessed from the GUI.

The GOBLET tool utilizes the graphical filter software \verb/fig2dev/,
\verb/ghostscript/ and \verb/transfig/ which supply to GOBLET an almost
universal export filter. This allows to prepare figures for latex documents
which can be included directly or post-processed by the canvas drawing tool
\verb/xFig/. 

Every table lists a single pull-down menu. There are no inline descriptions of
how the tools work but only references to the C++ API functionality for each
item. A user manual would be more gentle, but many features are still floating
and it is hard to keep this document up to date.

One menu is missing, namely
the info menu which provides the problem statistics and system ressources info:
The statistics dialog gives some insight about problem type, dimensions and
numerics. In any case of trouble, consult the problem statistics and the GOSH
transscript. The system ressources info displays some information about the
heap (dynamic) memory occupied by GOBLIN.

Note that the browser does not support the entire GOBLIN functionality but
somewhat like 95 percent. For example, the matching solver can only be fed
with one degree sequence while the C++ API allows to specify upper and
lower bounds on the node degrees.

We mention that one can solve moderate size optimization problems without much
knowledge of the library, but it requires some care and experience to produce
graphical output which is useful for teaching purposes. Then it is the
combination of trace objects and the messages which is instructive.

\end{multicols}
\pagestyle{fancy}

\vfill
\section{File Management (Menu Item: File)}

\begin{tabular}{p{3cm}|p{2cm}|p{18cm}|p{1.5cm}} 
\large\bf Option & \large\bf Shortcut & \large\bf Effect & \large\bf Section \\
[1mm] \hline \hline
\bf New... & &
    Generate a new graph object or linear program \\ \hline
\bf Open... & \bf Ctrl+o &
    Read a graph object from file. Supported formats:
    GOBLIN, DIMACS, TSPLIB and STEINLIB problems.
    If the check button is unset, the current graph is replaced by the selected
    object. Otherwise, the graphs are merged &
    \ref{slb_format}, \ref{slb_standard_formats} \\ \hline
\bf Save & \bf Ctrl+s &
    Write current graph object to a GOBLIN file &
    \ref{slb_format} \\ \hline
\bf Print Object... & \bf Ctrl+p &
    Print the current graph or trace object. Assign a shell print command \\ \hline
\bf Save as... & &
    Export the current graph object or the selected trace object to file.
    The supported file formats include problem instances (GOBLIN, DIMACS,
    TSPLIB), solutions, bitmaps (GIF,JPEG) and canvasses (Postscript, EPS).
    If a trace file is exported to a GOBLIN file, the browser switches to
    the trace object as the current graph &
    \ref{slb_standard_formats} \\ \hline
\bf Compression... & &
    Specify the shell commands used for file compression and decompression \\ \hline
\bf Save Settings & &
    Export the current configuration to the file \verb/.goshrc/ which is
    read when the GOSH interpreter is started &
    \ref{slb_gosh_ressources}  \\ \hline
\bf Quit & \bf Ctrl+q &
    Quit GOBLET
\end{tabular}


\vfill
\bigskip
\section{Graph Editor Dialogs (Menu Item: Edit)}

\begin{tabular}{p{4cm}|p{2cm}|p{17cm}|p{1.5cm}} 
\large\bf Option &  \large\bf Shortcut & \large\bf Effect & \large\bf Section \\
[1mm] \hline \hline
\bf Constant Labels... &\bf Ctrl+C&
    Dialog for constant node and arc labelings \\ \hline
\bf Metrics &\bf & 
    Choose edge length metrics (Only for dense graphs). Either explicit length
    labels are used during optimization or length labels are computed with respect
    to the selected metrics. GOBLIN supports Euclidian, Manhattan, coordinate
    maximum and spheric distances (as specified in the TSPLIB) &
    \ref{slb_length} \\ \hline
\bf Delete Solutions... & \bf Ctrl+X &
    Computational results can be deleted. This is important if algorithms support
    postoptimization but computation shall be started from scratch \\ \hline
\bf Extract Solutions... & \bf Ctrl+E &
    Predecessor labels representing trees, $1$-matchings or cycles can be
    extracted from the subgraph labels. Node colourings representing
    bipartitions and edge-cuts can be extracted from the distance labels. &
    \ref{slb_pred}
\end{tabular}


\vfill
\bigskip
\section{Editing Graphs (Menu Item: Edit)}

\begin{tabular}{p{7.5cm}|p{2cm}|p{13.5cm}|p{1.5cm}} 
\large\bf Option &  \large\bf Shortcut & \large\bf Effect & \large\bf Section \\
[1mm] \hline \hline
\bf Insert Arcs & \bf Ctrl+a &
    Left button click selects start node. Subsequent clicks place bend nodes.
    Final click selects end node. Then the arc label can be placed by another
    left button click. Alternatively, a right button click enables automatic
    alignment of the arc label (only available if no bends are present) &
    \ref{slb_spsstruc} \\ \hline
\bf Insert Nodes&\bf Ctrl+v &
    Left button click in unoccupied area inserts a new graph node &
    \ref{slb_spsstruc} \\ \hline
\bf Redirect Arcs&\bf Ctrl+r &
    For sparse graphs only: Left button click reverts any directed arc, right
    button click changes undirected edges into arcs and vice versa &
    \ref{slb_spsstruc} \\ \hline
\bf Incidences $\rightarrow$ Reorder Manually &\bf Ctrl+i &
    For sparse graphs only: Left button on a node steps over its incidences,
    right button click admits to change the ordering &
    \ref{slb_spsstruc} \\ \hline
\bf Incidences $\rightarrow$ Planar Ordering & &
    For sparse planar graphs: Compute a combinatorial representation. This
    operation does not produce a drawing &
    \ref{slb_planarity} \\ \hline
\bf Incidences $\rightarrow$ Series Parallel Ordering & &
    For series-parallel graphs: Compute a combinatorial representation. This
    operation does not produce a drawing &
    \ref{slb_series_parallel} \\ \hline
\bf Incidences $\rightarrow$ Random Ordering & &
    Random ordering of the node incidences &
    \ref{slb_incidence_lists} \\ \hline
\bf Incidences $\rightarrow$ Extract Order From Drawing & &
    Order the node incidences so that arcs appear in clockwise order in the
    current drawing. This procedure does not work correctly with all big node
    models &
    \ref{slb_incidence_lists} \\ \hline
\bf Delete Objects&\bf Ctrl+x &
    Left button click on existing graph nodes and arc labels deletes objects &
    \ref{slb_spsstruc} \\ \hline
\bf Explicit Parallels & &
    For sparse graphs only: Replace edges with non-unit capacity labels by simple,
    parallel arcs &
    \ref{slb_spsstruc} \\ \hline
\bf Move Nodes &\bf Ctrl+m &
    Left button drag and drop graph nodes, arc labels and bend nodes \\ \hline
\bf Edit Labels &\bf Ctrl+e &
    Left button click on nodes and arc labels opens a dialog to manipulate the
    labels which are associated with graph nodes and arcs &
    \ref{slb_sol} \\ \hline
\bf Set Colours & &
    Left button click decreases, right button click increases the colour index
    of the highlighted node or edge &
    \ref{slb_colour} \\ \hline
\bf Set Predecessors & &
    Left button click selects a node whose predessor arc can be deleted (click
    right button) or replace by another arc (click with left button on an
    adjacent node or incident arc) &
    \ref{slb_pred} \\ \hline
\end{tabular}


\vfill
\clearpage
\noindent
\begin{tabular}{p{7.5cm}|p{2cm}|p{13.5cm}|p{1.5cm}} 
\large\bf Option &  \large\bf Shortcut & \large\bf Effect & \large\bf Section \\
[1mm] \hline \hline
\bf Randomize $\rightarrow$ Add Arcs... & &
    Add a specified number of random arcs to the current graph \\ \hline
\bf Randomize $\rightarrow$ Add Eulerian Cycle... & &
    Add to the current graph a random Eulerian cycle of specified length \\ \hline
\bf Randomize $\rightarrow$ Make Graph Regular... & &
    Complete the current graph to a $k$-regular graph. For this goal, the degrees
    in the current graph must not exeed $k$, and $k$ must be even if the number of
    nodes is even \\ \hline
\bf Randomize $\rightarrow$ Random Generator... &\bf Ctrl+R &
    Generate random labels for the existing graph nodes and arcs, and/or configure
    the random generator which is also used for arc insertions and the graph
    composition described in this menu
\end{tabular}


\vfill
\section{LP Editor Dialogs (Menu Item: Edit)}

\begin{tabular}{p{3.5cm}|p{2cm}|p{17.5cm}|p{1.5cm}} 
\large\bf Option &  \large\bf Shortcut & \large\bf Effect & \large\bf Section \\
[1mm] \hline \hline
\bf Edit Columns... &\bf Ctrl+C &
    Dialog for variable based data: Bounds, cost coefficients, labels.
    Mark variables as float or integers. Edit restriction matrix \\ \hline
\bf Edit Rows... &\bf Ctrl+R & 
    Dialog for restriction based data: Right hand sides, labels.
    Edit restriction matrix \\ \hline
\bf Reset Basis & \bf Ctrl+X &
    Basis solution is set to the lower variable bounds \\ \hline
\bf Pivoting... & \bf Ctrl+P &
    Perform pivoting steps manually
\end{tabular}


\vfill
\section{Composing Graphs (Menu Item: Compose)}

The composition methods in this pulldown menu generate a new object from the
currently controlled graph object. The original graph is not manipulated.

\bigskip
\noindent
\begin{tabular}{p{7cm}|p{16.3cm}|p{1.5cm}} 
\large\bf Option &  \large\bf Effect & \large\bf Section \\
[1mm] \hline \hline
\bf Underlying Graph &
    Replace every class of parallel / antiparallel arcs by a single arc &
    \ref{slb_copy} \\ \hline
\bf Orientation $\rightarrow$ Complete &
    Replace every undirected edge by a pair of antiparallel arcs &
    \ref{sbl_complete_orientation} \\ \hline
\bf Orientation $\rightarrow$ Induced by Colours &
    Orient every undirected edge from the lower to the higher colour index &
    \ref{sbl_induced_orientation} \\ \hline
\bf Shrink Colours &
    Contract nodes by colours &
    \ref{sbl_colour_contraction} \\ \hline
\bf Subgraph $\rightarrow$ By Node Colours... &
    Export the subgraph induced by a node colour &
    \ref{sbl_induced_subgraph} \\ \hline
\bf Subgraph $\rightarrow$ By Edge Colours... &
    Export the subgraph induced by an edge colour &
    \ref{sbl_induced_subgraph} \\ \hline
\bf Subgraph $\rightarrow$ Induced Bigraph... &
    Export the bigraph induced by a pair of node colours &
    \ref{sbl_induced_bigraph} \\ \hline
\bf Subgraph $\rightarrow$ Explicit Subgraph &
    Export subgraph into a separate object &
    \ref{slb_copy} \\ \hline
\bf Subgraph $\rightarrow$ Transitive Closure &
    For directed acyclic graphs only: Add all transitive arcs
    (arcs which represent non-trivial directed paths &
    \ref{sbl_transitive_closure} \\ \hline
\bf Subgraph $\rightarrow$ Intransitive Reduction &
    For directed acyclic graphs only: Remove all transitive arcs &
    \ref{sbl_intransitive_reduction} \\ \hline
\bf Complement &
    Switch to the complementary graph &
    \ref{sbl_complementary_graph} \\ \hline
\bf Line Graph &
    Switch to the line graph &
    \ref{sbl_line_graph} \\ \hline
\bf Node Splitting &
    Switch to the node splitting &
    \ref{slb_node_splitting} \\ \hline
\bf Distance Graph &
    Generate a complete digraph where the length label of any arc
    $uv$ is the length of a shortest $uv$-path in the original graph &
    \ref{sbl_distance_graph} \\ \hline
\bf Metric Graph &
    Undirected counterpart of the distance graph &
    \ref{slb_metric_closure}
\end{tabular}

\vfill
\clearpage
\noindent
\begin{tabular}{p{7cm}|p{16.3cm}|p{1.5cm}} 
\large\bf Option &  \large\bf Effect & \large\bf Section \\
[1mm] \hline \hline
\bf Planar $\rightarrow$ Undirected Dual Graph &
    Switch to the dual graph (only for plane graph objects) &
    \ref{sbl_dual_graph} \\ \hline
\bf Planar $\rightarrow$ Directed Dual Graph &
    Switch to the directed dual graph (only for bipolar plane digraphs and
    for plane graphs with a given st-numbering) &
    \ref{sbl_dual_graph} \\ \hline
\bf Planar $\rightarrow$ Planar Line Graph &
    Replace all original nodes by faces of the same degree. The original
    arcs are all contracted to nodes &
    \ref{sbl_line_graph} \\ \hline
\bf Planar $\rightarrow$ Truncate Vertices &
    Replace all original nodes by faces of the same degree,
    and keep the original edges connecting the new faces &
    \ref{sbl_line_graph} \\ \hline
\bf Planar $\rightarrow$ Tear Regions Apart &
    Replace the original nodes by faces of the same degree,
    and the original edges by 4-sided faces &
    \ref{sbl_facet_separation} \\ \hline
\bf Planar $\rightarrow$ Tear \& Turn Left / Right &
    As before, but triangulate the faces representing the original edges &
    \ref{sbl_facet_separation} \\ \hline
\bf Planar $\rightarrow$ Spread To Outerplanar &
    Requires an regular graph and a spanning tree. Double the tree
    arcs to obtain the exterior face of an outerplanar graph. The
    result is a cutting pattern for the original graph &
    \ref{sbl_spread_out} \\ \hline
\bf Tiling... &
    Compose a graph from tiles. Open one of the templates
    \verb/tile*.gob/ in the example data base (folder \verb/samples/).
    Specify the number of tiles in $x$ and $y$-direction &
    \ref{slb_tiling} \\ \hline
\bf Split Graph... &
    Swich to the skew-symmetric version of a network flow problem &
    \ref{slb_split_graph} \\ \hline
\bf Integer / Linear $\rightarrow$ &
    Generate the (integer) linear formulation for the selected graph based
    optimization model. Do not actually solve the ILP model &
\end{tabular}


\vfill
\bigskip
\section{Graph Visualization (Menu Item: Layout)}

The operations in this pull-down menu manipulate the display coordinates of
the current graph object. Partially, pure display entities such as arc
bend nodes are added or deleted, and sometimes the order of node incidences
are mainipulated to conform with the produced drawing.

\bigskip
\noindent
\begin{tabular}{p{4.7cm}|p{2cm}|p{16.3cm}|p{1.5cm}} 
\large\bf Option & \large\bf Shortcut & \large\bf Effect & \large\bf Section \\
[1mm] \hline \hline
\bf Strip Geometry &\bf &
    Translate the node coordinates so that all coordinate are in the positive
    orthant. At least one x-coordinate and one y-coordinate are zero.
    {\bf Attention:} Do not manipulate the geometrical embedding when working
    with spheric distances, use layout options instead &
    \ref{slb_translate_drawing} \\ \hline
\bf Scale Geometry... &\bf &
    Scale the geometric embedding to fit into a specified bounding box &
    \ref{slb_translate_drawing} \\ \hline
\bf Node Grids... &\bf &
    Configure separate, invisible grids for graph nodes, bend nodes and arc
    label alignment points. Objects are aligned with this grid during editor
    operations automatically. Optionally move existing nodes to the grid &
    \ref{slb_layout_options} \\ \hline
\bf Fit into Window & \bf Ctrl+w &
    Fits the graph display into the GOBLET main window \\ \hline
\bf Zoom In &\bf Ctrl+ &
    Enlarge the graph display \\ \hline
\bf Zoom Out &\bf Ctrl- &
    Lessen the graph display \\ \hline
\bf Planarity &\bf &
    Check for planarity, compute a combinatorial representation explicitly,
    maximize the number of exterior nodes or derive a plane drawing
    from an existing combinatorial representation &
    \ref{slb_planarity} \\ \hline
\bf Force Directed Drawing $\rightarrow$ Unrestricted &\bf &
    Basically models the graph nodes as loaded particles and the graph arcs as
    springs. Searches for equilibriance of the nodes.  &
    \ref{slb_force_directed} \\ \hline
\bf Force Directed Drawing $\rightarrow$ Preserve Geometry &\bf &
    Similar to the previous method but maintains edge crossing properties.
    That is, if the input is a planar straight line drawing, the result is
    a planar drawing with the same dual geometry &
    \ref{slb_force_directed} \\ \hline
\bf Layered Drawing &\bf &
    Assign the node to horizontal layers, add bend nodes whenever arcs cross
    layers and align the nodes in the respective layer &
    \ref{slb_layered_drawing} \\ \hline
\bf Predecessor Tree &\bf &
    Manipulate the geometric embedding in order to expose a given tree of
    predecessor arcs &
    \ref{slb_tree_layout} \\ \hline
\bf Circular Drawing &\bf &
    Draw all nodes on a cycle. The order is either given by the predecessor
    arcs or by the node colours &
    \ref{slb_circular_layout} \\ \hline
\bf Orthogonal Drawing &\bf &
    Draw the graph on grid lines. The Kandinsky model applies to general
    graphs. The other models are limited to planar graphs and/or small node
    degrees &
    \ref{slb_orthogonal_layout} \\ \hline
\bf Clean Up Arc Routing &\bf &
    Redraw arcs such that loops become visible and parallel arcs can be
    distinguished. All other arcs are drawn as straight lines &
    \ref{slb_auto_arc_alignment} \\ \hline
\end{tabular}

\vfill
\bigskip
\noindent
\begin{tabular}{p{4.7cm}|p{2cm}|p{16.3cm}|p{1.5cm}} 
\large\bf Option & \large\bf Shortcut & \large\bf Effect & \large\bf Section \\
[1mm] \hline \hline
\bf Arc Display... &\bf Ctrl+A&
    Specify the arc and arc label display &
    \ref{slb_display} \\ \hline
\bf Node Display... &\bf Ctrl+N &
    Specify the node and node label display &
    \ref{slb_display} \\ \hline
\bf Layout Options... &\bf Ctrl+W &
    Specify layout parameters (scaling, node and arrow size) without
    changing the geometric embedding and/or activate the graph legenda &
    \ref{slb_layout_options}
\end{tabular}


\vfill
\bigskip
\section{Problem Solvers (Menu Item: Optimize)}

This pulldown menu lists all available solvers for graph based optimization
models. Calls to a solver can be interupted and / or repeated by pressing
{\bf Ctrl+c}. Before repeating a solver call, one can use the node context
menus to select a different root, source or target node.

\bigskip
\noindent
\begin{tabular}{p{9.3cm}|p{14cm}|p{1.5cm}} 
\large\bf Option & \large\bf Effect & \large\bf Section \\
[1mm] \hline \hline
\bf  Vertex Routing $\rightarrow$ Minimum Spanning Tree &
     Compute a minimum spanning tree and return it by the predecessor labels &
     \ref{slb_solve_mintree} \\ \hline
\bf  Vertex Routing $\rightarrow$ Maximum Spanning Tree &
     Compute a minimum spanning tree and return it by the predecessor labels &
     \ref{slb_solve_mintree} \\ \hline
\bf  Vertex Routing $\rightarrow$ Travelling Salesman &
     Compute a minimum Hamiltonian cycle return it by the predecessor labels &
     \ref{slb_solve_tsp} \\ \hline
\bf  Vertex Routing $\rightarrow$ Minimum 1-Cycle Tree &
     Compute a minimum 1-cycle tree and return it by the predecessor labels &
     \ref{slb_solve_tsp} \\ \hline
\bf  Vertex Routing $\rightarrow$ Minimum Steiner Tree &
     Compute a minimum Steiner tree and return it by the predecessor labels.
     The terminal nodes are specified by the node demands &
     \ref{slb_steiner} \\ \hline
\bf  Edge Routing $\rightarrow$ Shortest Path Tree &
     For a given source node $s$, compute a shortest $s$-path tree. If a target
     node $t$ is specified, the computation stops once a shortest $st$-path has been
     found. The results are returned by the predecessor and the distance labels &
     \ref{slb_solve_shortest_path} \\ \hline
\bf  Edge Routing $\rightarrow$ Residual Shortest Path Tree &
     For digraphs only: Similar to the previous operation, but search the residual
     network as it occurs in min-cost flow algorithms &
     \ref{slb_solve_shortest_path} \\ \hline
\bf  Edge Routing $\rightarrow$ Critical Path &
     For directed acyclic graphs only: Compute a forest such that every node
     is reached from a root node by a maximum length path &
     \ref{slb_dag_search} \\ \hline
\bf  Edge Routing $\rightarrow$ Maximum $st$-Flow &
     For digraphs only: Compute a maximum $st$-flow. Return the
     subgraph and a minimum $st$-cut by the distance labels. A subgraph must be
     given in advance which satisfies the node demands other than for $s$ and $t$
     (usually the zero flow) &
     \ref{slb_solve_maxflow} \\ \hline
\bf  Edge Routing $\rightarrow$ Feasible $b$-Flow &
     For digraphs only: Compute a subgraph which satisfies all
     node demands &
     \ref{slb_solve_maxflow} \\ \hline
\bf  Edge Routing $\rightarrow$ Minimum Cost $st$-Flow &
     For digraphs only: Compute a maximum $st$-flow of minimum
     costs. Return the optimal subgraph and node potentials. A subgraph must be
     given in advance which satisfies the node demands other than for $s$ and $t$
     and which is optimal among all $st$-flows with the same flow value (usually
     the zero flow) &
     \ref{slb_solve_mcflow} \\ \hline
\bf  Edge Routing $\rightarrow$ Minimum Cost $b$-Flow &
     For digraphs only: Compute a subgraph of minimum costs
     satisfying all node demands. Return the optimal subgraph and node potentials &
     \ref{slb_solve_mcflow} \\ \hline
\bf  Edge Routing $\rightarrow$ Eulerian Cycle &
     Check if the graph object is Eulerian. Occasionally return an Eulerian walk
     by the edge colours &
     \ref{slb_euler} \\ \hline
\bf  Edge Routing $\rightarrow$ Minimum Eulerian Supergraph &
     Increase the capacity bounds so that the graph becomes Eulerian &
     \ref{slb_solve_t_join}
\end{tabular}

\vfill
\bigskip
\noindent
\begin{tabular}{p{7.5cm}|p{15.8cm}|p{1.5cm}} 
\large\bf Option & \large\bf Effect & \large\bf Section \\
[1mm] \hline \hline
\bf  Bipartitions $\rightarrow$ Maximum Edge Cut &
     Compute a maximum capacity edge cut and return it by the node colours &
     \ref{slb_solve_maxcut} \\ \hline
\bf  Bipartitions $\rightarrow$ Maximum Stable Set &
     Compute a maximum stable set and return it by the node colours &
     \ref{slb_solve_stable} \\ \hline
\bf  Bipartitions $\rightarrow$ Minimum Vertex Cover &
     Compute a minimum vertex cover and return it by the node colours &
     \ref{slb_solve_stable} \\ \hline
\bf  Bipartitions $\rightarrow$ Maximum Clique &
     Compute a maximum clique and return it by the node colours &
     \ref{slb_solve_stable} \\ \hline
\bf  Graph Partitions... &
     Compute a node colouring, a cover with node disjoint cliques or an edge
     colouring. Optionally, the number of sets can be restricted &
     \ref{slb_solve_colours} \\ \hline
\bf  Connectivity... &
     Compute the (strongly) (edge) connected components for a given degree
     of connectivity or determine some connectivity number &
     \ref{slb_components}, \ref{slb_solve_mincut} \\ \hline
\bf  Matching Problems... &
     Compute a maximum capacitated $b$-matching, a minimum cost perfect
     $b$-matching, a optimal $T$-join or a minimal Eulerian supergraph
     (Chinese Postman Problem). The vector $b$ and the set $T$ are determined
     by the current node demands &
     \ref{slb_solve_matching}, \ref{slb_solve_t_join} \\ \hline
\bf  Ordering Problems $\rightarrow$ st-Numbering &
     Compute an st-numbering and return it by the node colours &
     \ref{slb_components} \\ \hline
\bf  Ordering Problems $\rightarrow$ Topologic Order &
     For directed acyclic graphs only: Compute a topological order and return
     it by the node colours &
     \ref{slb_dag_search} \\ \hline
\bf  Balanced Network Flows... &
     Compute (min-cost) maximum balanced $st$-flow for a given source node $s$
     or (min-cost) $st$-flow. The sink node $t$ is determined by the graph
     symmetry &
     \ref{slb_solve_balanced_flow}, \ref{slb_solve_balanced_weighted} \\ \hline
\bf  Solve LP Relaxation &
     Solve a linear program, neglect all integrality requirements &
     \ref{slb_solve_lp}
\end{tabular}


\vfill
\bigskip
\section{Solver Configuration (Menu Item: Optimize)}

\begin{tabular}{p{4cm}|p{2cm}|p{17cm}|p{1.5cm}} 
\large\bf Option & \large\bf Shortcut & \large\bf Effect & \large\bf Section \\
[1mm] \hline \hline
\bf  Restart/Stop Solver &\bf Ctrl+c &
     Resolve problem with the same parameters or stop the current computation &
     \ref{slb_solver_signals} \\ \hline
\bf  Optimization Level... &\bf Ctrl+O &
     Restrict the computational efforts when solving NP-hard problem.
     Attention: Candidate sets work for weighted matching problems also. &
     \ref{slb_options_hard} \\ \hline
\bf  Method Options... &\bf Ctrl+M &
     Configure the various problem solvers &
     \ref{slb_options_solver} \\ \hline
\bf  Data Structures... &\bf Ctrl+S&
     Select from alternative data structures for priority queues, union-find
     processes and node adjacencies &
     \ref{slb_options_data}
\end{tabular}

\vspace*{1cm}
\section{Browser Configuration (Menu Item: Browser)}

\begin{tabular}{p{5cm}|p{2cm}|p{16cm}|p{1.5cm}} 
\large\bf Option & \large\bf Shortcut & \large\bf Effect & \large\bf Section \\
[1mm] \hline \hline
\bf  Toggle Editor/Navigator &\bf Ctrl+d &
     Switches from edit mode to display mode or switches between edit and
     navigation mode \\ \hline
\bf  Snapshot Image &\bf Ctrl+t &
     Generates a new trace image and switches to navigation mode \\ \hline
\bf  View/Update Messenger &\bf Ctrl+l &
     Open messenger window \\ \hline
\bf  Tracing Options... &\bf Ctrl+T &
     Configure the tracing module. That is, specify how often trace objects
     are generated &
     \ref{slb_tracing} \\ \hline
\bf  Browser Options... &\bf Ctrl+B &
     Configure the browser, especially the file handling and
     windowing features \\ \hline
\bf  Logging Options... &\bf Ctrl+L &
     Specify which amount of logging information shall be written by
     the problem solvers &
     \ref{slb_logging} \\ \hline
\bf  Save Browser Options &\bf & ...to a file in the \verb/.goblet/ folder
\end{tabular}



\part{Data Objects}
\thispagestyle{empty}

\begin{multicols}{2}
\pagestyle{fancy}
\markboth{PRELIMINARY STATEMENTS}{CONVENTIONS}
\chapter{Preliminary Statements}
\thispagestyle{fancy}

\section{Some Conventions}

Before we start the description of data objects, we give some general remarks
about GOBLIN files, classes and methods which are omitted later in this document.
\begin{myitemize}
\item If not stated otherwise, operations are {\bf elementary}\index{elementary operation},
    that is, they take only a constant number of computing steps. Sometimes operations take
    constant time in practice, but an exact statement about their theoretical
    complexity is beyond the scope of this document, and therefore omitted.
\item If not stated otherwise, the amount of computer storage required by any
    algorithm is proportional to the number of arcs or less.
\item A GOBLIN source code file contains the definition of a single class,
    and the file name ends with \verb/.cpp/. This class is declared in the
    header file whose name only differs by the extention \verb/.h/.

    As an exception, a class definition may include a method of another class if
    this method instanciates the former class, so that an external definition would
    only complicate the dependencies among the source code files. For example, the
    TSP branch and bound method is defined in \verb/branchSymmTSP.cpp/ which implements the
    branch node data structure.
\item Iterators are declared with their graphs, but defined in a separate file
    whose name differs from the graph definition file name by a leading
    \verb/i/.
\item Every section starts with a listing of the declaration of the methods
    which are discussed. The header file where these methods are declared
    is listed likewise.
\item If not stated otherwise, all listed methods are declared \verb/public/.
\end{myitemize}


\markright{BASE TYPES}
\section{Base Types}

There are a few GOBLIN objects which are rather basic values than instances
of a C++ class. The corresponding types can be configured at compile time.
We just considered late binding and dereferencing to be too expensive
operations at that low logical level.


\subsection{Node Indices}

Graph nodes are distinguished by their indices which are integers of a special
type \verb/TNode/. The sequence of node indices associated with a graph is
\verb/0,1,..,n-1/, where \verb/n/ is a \verb/protected/ instance variable of
every graph object. In addition to the nodes of a graph, a global constant
\verb/NoNode/ is defined for the management of undefined node references. This
constant appears in GOBLIN files and in GOBLET as an asterisk \verb/*/.

In bipartite graphs, the node set splits into \nt{left-hand nodes} and
\nt{right-hand nodes}. The left-hand nodes have the indices \verb/0,1,..,n1-1/,
the right-hand nodes have the indices \verb/n1,n1+1,..,n1+n2-1/. Again, \verb/n1/
and \verb/n2/ are \verb/protected/ instance variables of a bigraph object, and
satisfy \verb/n==n1+n2/.

In balanced flow networks, nodes are arranged in \nt{complementary pairs} where
the complementary node \verb/v/ of the node \verb/u/ can be obtained by the
operation \verb/v = (u^1)/, that is, by changing the least significant bit.

With every graph, up to three special nodes can be associated. These nodes can
be accessed by the methods \verb/Source()/, \verb/Target()/, \verb/Root()/. For
represented objects but not for problem transformations, these nodes can be
manipulated by the methods \verb/SetSourceNode()/, \verb/SetTargetNode()/,
\verb/SetRootNode()/ respectively.


\subsection{Arc Indices}

Graph arcs are distinguished by their indices which are integers of a special
type \verb/TArc/. The sequence of arc indices is \verb/0,1,..,2*m-1/, where
\verb/m/ is a \verb/protected/ instance variable of every graph object. In
addition to the arcs of a graph, a constant \verb/NoArc/ is defined for
the management of undefined arc references. This constant appears
in GOBLIN files and in GOBLET as an asterisk \verb/*/.

With every arc, the reverse arc also exists. Both arcs have indices which
differ in the least significant bit. {\bf Forward arcs}\index{forward arcs}
have even indices,
\nt{backward arcs} have odd indices. This is arranged such that a reverse arc
is computed by the operation \verb/a2 = (a1^1)/. Note that attributes are
assigned to such antiparallel arc pairs.

In balanced flow networks, arcs are arranged in \nt{complementary pairs}.
Complementary arcs differ by the second least significant bit, that is, a
complementary arc is computed by the operation \verb/a2 = (a1^2)/. Note that
flow values are assigned to single arcs, but capacity labels and length
labels are assigned to complementary arc pairs.


\subsection{Capacity Values}

Capacity labels and node demands are held in numbers of a type \verb/TCap/.
This may either be an integral type or a floating point type. We do not strictly
exclude the possibility of non-integral capacities. But note that matching solvers
require integral values.

There is a constant \verb/InfCap/ which represents infinite capacities.
This constant appears in GOBLIN files an in GOBLET as an asterisk \verb/*/.


\subsection{Floating Point Numbers}

Length labels, distance labels, flow values and subgraph labels are held in
floating point numbers of a type \verb/TFloat/. There is a constant
\verb/InfFloat/ which is used for undefined values and which appears in GOBLIN
files and in GOBLET as an asterisk \verb/*/.

Explicit length labels are considered integral, and metric distances are roun\-ded
to integrality. Even if length and capacity labels are all integral, several
algorithms (cost-scaling method for min-cost flow, subgradient optimization for
TSP) deal with fractional node potentials and reduced length labels. Weighted
matching algorithms deal with half-integral potentials, modified lengths and
flow values. Note that the cost-scaling algorithm may end up with a suboptimal
solution if the length labels are not integral.


\subsection{Handles}

Handles are integer numbers of a type \verb/THandle/ which are used to identify
objects. There is a constant \verb/NoHandle/ to determine undefined handles
which appears in GOBLIN files and in GOBLET as an asterisk \verb/*/.


\subsection{Matrix Indices}

General matrix indices are integer numbers of a type \verb/TIndex/. There is
a constant \verb/NoIndex/ to determine an undefined index. When working with
linear programs, two additional types \verb/TVar/, \verb/TRestr/ occur with
special constants \verb/NoVar/ and \verb/NoRestr/. Although all three types
are interchangable, the latter types are helpful to distinguish the primal
respectively dual side of a linear program.


\subsection{Class Local Types}

Apart from these global base types, there are some more types which are used
with a few methods only and which are declared within one of the root classes
\verb/managedObject/ and \verb/goblinILPWrapper/ respectively. Generally,
the scope is obvious and not described explicitly in this document.


\markright{BOUNDS AND PRECISIONS}
\section{Bounds and Precisions of Numbers}

The width of matrix indices is an upper bound to the width of arc indices
which in turn bounds the width of node indices.

Node index values are bounded by the number of nodes in the corresponding
graph object. This number of nodes is in turn bounded by the \verb/maxNode/
parameter defined in the context. Finally, \verb/maxNode/ is bounded by
the constant \verb/NoNode/ which cannot be manipulated at runtime.

The method \verb/goblinController::SetMaxNode/ manipulates the \verb/maxNode/
parameter. There is a method \verb/goblinController::SetMaxArc/ which works in
the same way for arc indices, the parameter \verb/maxArc/ and the constant
\verb/NoArc/.

The context variable \verb/goblinController::epsilon/ denotes the smallest
number which is treated different from zero. It may apply in any situation
where the numerical stability needs to be improved.


\markright{OWNERSHIP}
\section{Ownership of Objects}
\label{slb_ownership}
\myinclude\verb/globals.h/
\begin{mymethods}
\begin{verbatim}
class goblinAbstractObject
{

    enum TOwnership {OWNED_BY_SENDER, OWNED_BY_RECEIVER};

};
\end{verbatim}
\end{mymethods}
When passing an object pointer by a method call or returning an object pointer,
it may be necessary for permanent access to specify which context owns the
passed object:
\begin{itemize}
\item If the calling context specifies \verb/OWNED_BY_SENDER/ and passes an
    object pointer, the message receiver must make a copy of the
    object for permanent access.
\item If the calling context specifies \verb/OWNED_BY_RECEIVER/ and passes
    an object pointer, the passed object is already a copy or not
    needed by the message sender any longer.
\item If the calling context specifies \verb/OWNED_BY_SENDER/ and an object
    pointer is returned, the method instanciates a copy to which the
    returned pointer refers.
\item If the calling context specifies \verb/OWNED_BY_RECEIVER/ and an object
    pointer is returned, the calling object either does not use the reference
    on the long run or makes a copy.
\end{itemize}
That is, the \verb/SENDER/ denotes the sender of the message rather than the
sender of the object pointer.



\cleardoublepage
\markboth{GRAPH OBJECTS}{ABSTRACT CLASSES}
\chapter{Graph Objects}
\thispagestyle{fancy}
\label{clb2}

Graph object classes are devided into three groups: {\bf Abstract} classes which
declare general interfaces and which also implement most mathematical methods,
{\bf represented} objects which can be manipulated and written to and read
from a file, and {\bf logical views} which implement the problem transformations
which are so important in network programming.


\section{Abstract Classes}

Abstract classes allow an high level description of solvers for graph
optimization problems. They separate the fundamental algorithms from the data
structures which are defined in dedicated classes called
\nt{implementation classes} or \nt{concrete classes}.

Every abstract class definition is endowed with file export methods for problem
instances and potential solutions. These methods are inherited by all
implementation classes. That is, the external formats are almost implementation
independent. Details can be found in Chapter \ref{clb8}.


\subsection{Mixed Graphs}
\label{slb211}
\myinclude\verb/abstractMixedGraph.h/

\bigskip\noindent
The class \verb/abstractMixedGraph/ is the base class for all graph structures.
It is not a pure interface but implements optimization methods on unspecified graph
representing data structures. It also handles the so-called \nt{registers} which are the
potential solutions of optimization methods (see Chapter \ref{slb_registers} for
a detailed description).

The first exception to this rule are subgraphs [flows] for which
\verb/abstractMixedGraph/ provides some prototypes, but which are not implemented.
This polymorphism results from the fact that subgraphs [flows] are subject to
problem (back)transformations, and that dense graph objects
should admit a sparse subgraph structure. Based on these prototypes,
\verb/abstractMixedGraph/ implements methods to extract trees, paths, cycles
and $1$-matchings from a subgraph data structure.

On the other hand, one might think that node adjacencies which are implemented in
\verb/abstractMixedGraph/ constitute a graph representing data structure.
But note that graph defintions are based on node incidence lists in the default
setting, and that node adjacencies are represented explicitly only on demand and
just to speed up algorithms:
If the context flag \verb/methAdjacency/ is enabled, the first call to
\verb/Adjacency()/ generates a hash table for efficient access to node adjacencies.
That is, this first call requires $O(m)$ computing steps, but the other calls can
be considered elementary operations. This data structure is not useful for dense
implementations where the index of an adjacent arc can be computed directly from
the node indices. Hence \verb/Adjacency()/ is overloaded in some classes.

One of the most important features of this class are the methods
\verb/Display()/ and \verb/TextDisplay()/ on which the tracing of all
graph objects depends.


\subsection{Undirected Graphs}
\myinclude\verb/abstractGraph.h/

\bigskip\noindent
Abstract graphs inherit from the abstract mixed graph interface. Several
optimization problems are associated with this class, namely all kinds of
matching problems and minimum spanning tree problems, including the
$1$-tree problem. There are also some algorithms for the symmetric TSP and the
metric TSP. The matching code and the Christofides heuristics are defined
in the file \verb/gra2bal.cpp/.


\subsection{Digraphs and Flow Networks}
\myinclude\verb/abstractDigraph.h/

\bigskip\noindent
Abstract digraphs inherit from abstract mixed graphs. This class contains only a
few graph theoretical methods, but also models abstract flow networks which
supply lot of additional functionality:
\begin{myitemize}
\item Residual capacities \verb/ResCap(TArc)/
\item Node imbalances \verb/Div(TNode)/
\item Computation of path capacities \verb/FindCap(TArc*,TNode,TNode)/
\item Push operations \verb/Push(TArc,TFloat)/ and
    \verb/AdjustDegree(TArc,TFloat)/
\item Augmentation \verb/Augment(TArc*,TNode,TNode,TFloat)/
\item Max flow algorithms (Push-Relabel, augmentation, capacity scaling)
\item Min cost flow algorithms (SAP, cycle canceling, cost-scaling, minimum
    mean cycles)
\end{myitemize}
These methods are defined in the file \verb/absdig.cpp/. There are further
definition files including network flow algorithms which directly utilize a
special problem transformation:
\begin{myitemize}
\item \verb/auxnet.cpp/: Defines layered auxiliary networks which form part of
the well-known Dinic max flow algorithm. This file also defines the method
\verb/abstractDiGraph::Dinic(TNode,TNode)/.
\item \verb/fnw2fnw.cpp/: The reduction of circulation problems
to $st$-flow problems: \verb/abstractDiGraph::ShortestAugmentingPath(TNode,TNode)/.
\end{myitemize}


\subsection{Bipartite Graphs}
\myinclude\verb/abstractBigraph.h/

\bigskip\noindent
Abstract bigraphs inherit from undirected graphs, and specify a bipartition
of the node set by parameters $n_1$ and $n_2$ which can be accessed by the
methods \verb/N1()/ and \verb/N2()/. The \nt{left-hand nodes} have indices
$0,1,\dots,n_1$ and the \nt{right-hand nodes} have indices
$n_1,n_1+1,\dots,n_1+n_2=n$. All edges connect left-hand nodes to right-hand nodes.

Bigraphs overload the matching algorithms by dedicated assignment algorithms.
The file \verb/big2fnw.cpp/ which defines the reduction of assignment problems
to network flow problems also defines these assignment methods. The remaining
methods are defined in \verb/abstractBigraph.cpp/, including specialized methods
for colouring and stable sets.


\subsection{Balanced Flow Networks}
\myinclude\verb/abstractBalancedDigraph.h/

\bigskip\noindent
Abstract balanced flow networks inherit from digraphs, but have a certain symmetry
based on the complementarity of nodes and arcs. The additional functionality is:
\begin{myitemize}
\item Pairwise push operations (\verb/BalPush(TArc,TFloat)/),
    symmetrical residual capacities (\verb/BalCap(TArc)/).
\item Symmetrical path capacities (\verb/FindBalCap(TNode,TNode)/),
    pairwise augmentation (\verb/BalAugment(TNode,TNode,TFloat)/).
\item Balanced network search methods which constitute the balanced augmentation
    algorithm (Kocay/Stone, Kameda/Munro and other heuristics).
\item Maximum balanced flow algorithms which essentially solve non-weighted
    matching problems (Anstee, Micali/Vazirani, augmentation, capacity
    scaling).
\item Min-Cost balanced flow algorithms which essentially solve weighted \\
    matching problems (Primal-dual, primal-dual starting with min-cost flow
    optimum).
\end{myitemize}
The new functionality is needed if one is interested in integral symmetric
flows only. But this is the case for the reduction of matching problems which is
implemented by the class \verb/gra2bal/.

All class methods are defined in the file \verb/absbal.cpp/ except for the
methods
\begin{quote}
\begin{verbatim}
abstractBalancedFNW::MicaliVazirani(TNode);
abstractBalancedFNW::BNSMicaliVazirani(TNode,TNode);
\end{verbatim}
\end{quote}
which are defined in the file \verb/shrnet.cpp/, the method
\begin{quote}
\begin{verbatim}
void abstractBalancedFNW::PrimalDual(TNode)
\end{verbatim}
\end{quote}
which is defined in the file \verb/surgra.cpp/, and the methods
\begin{quote}
\begin{verbatim}
void abstractBalancedFNW::CancelOdd()
void abstractBalancedFNW::CancelPD()
\end{verbatim}
\end{quote}
which are defined in the file \verb/bal2bal.cpp/.



\markright{REPRESENTED GRAPH OBJECTS}
\section{Represented Graph Objects}

A graph object is called \nt{represented}\index{represented graph object} if all
its attributes can be modified, not just the registers (see \ref{slb_registers}).
To every category of graph objects, potentially two represented implementation
classes exist: A \nt{sparse representation} based on incidence lists, and a
\nt{dense representation} based on adjacency matrices. The available represented
graphs are the following:
\begin{itemize}
\item \verb/mixedGraph/: sparse mixed graph objects
\item \verb/graph/     : sparse undirected graph objects
\item \verb/diGraph/   : sparse directed graph objects
\item \verb/biGraph/   : sparse bipartite graph objects
\item \verb/balancedFNW/ : sparse balanced flow networks
\item \verb/denseGraph/  : dense undirected graph objects
\item \verb/denseDiGraph/ : dense directed graph objects
\item \verb/denseBiGraph/ : dense bipartite graph objects
\end{itemize}
Each of these classes is declared in a header file of the same name.

Represented graph objects are of little mathematical interest since algorithms
are implemented by the interface classes, and problem reduction principles are
implemented by dedicated logical view classes. Also the graph manipulation
methods are inmplemented somewhere else, namely by the \nt{representational
objects} which are discussed next. Represented graph object classes mainly
implement constructor methods and attribute queries.


\subsection{Representational Objects}
\myinclude\verb/graphRepresentation.h/

\bigskip\noindent
Represented graph objects are not defined independently from each other but are
composed either of a \verb/sparseRepresentation/ or of a \verb/denseRepresentation/
object. The common base class \verb/graphRepresentation/ provides the most graph
attributes: Capacities, arc length labels, node demands, node coordinates, arc
orientations. The class \verb/denseRepresentation/ adds the management of sparse
subgraphs, \verb/sparseRepresentation/ contributes node incidence lists and the
arc routing.

When a graph has to be manipulated, commands are addressed to its
representational object:
\sample
\begin{quote}
\begin{verbatim}
graphRepresentation* X = Representation();

if (X && IsSparse())
{
    static_cast<sparseRepresentation*>(X) -> FlipArc(a);
}
\end{verbatim}
\end{quote}
This example code would apply in every graph object context. If and only if the
graph is represented, \verb/X/ is defined. If the graph is also sparse, the
displayed cast operation is valid, and the orientation of the arc \verb/a/
can be reverted.

It would also be possible to address graph attribute queries to the
representational object. But the declaration of retrieval methods is
lifted to all represented graph objects in order to satisfy the general graph
object interface. To avoid literal repetitions, there are special include files
named \verb/graphInclude.h/, \verb/sparseInclude.h/, \verb/denseInclude.h/ which
collect the rspective inline method definitions.


\subsection{Dense Representations}
\label{slb_dnsstruc}
\myinclude\verb/denseRepresentation.h/
\begin{mymethods}
\begin{verbatim}
class denseRepresentation : public graphRepresentation
{
    void        NewSubgraph(TArc);
    void        ReleaseSubgraph();

    TFloat      Sub(TArc);
    void        SetSub(TArc,TFloat);
    void        SetSubRelative(TArc,TFloat);
}
\end{verbatim}
\end{mymethods}
To handle sparse subgraphs in complete and geometrical graph instances,
\verb/denseRepresentation/ implements a hash table for subgraph labels. This
data structure is generated automatically by the first \verb/SetSub()/ or
\verb/SetSubRelative()/ call. By that, the total subgraph multiplicity is
initialized to twice the number of graph nodes. This is satisfactory for
working with trees, $1$-trees, $1$-matchings and $2$-factors.

One can also allocate the subgraph data structure explicitly by calling
\verb/NewSubgraph(l)/ which takes the maximum size $l$ as a parameter
and requires $O(l)$ computing steps. Note that the capacity of any hash
table is automatically doubled when the current capacity bound is exeeded.


\subsection{Sparse Representations}
\label{slb_spsstruc}
\myinclude\verb/sparseRepresentation.h/
\begin{mymethods}
\begin{verbatim}
class sparseRepresentation : public graphRepresentation
{
    void        SetCapacity(TNode,TArc);

    TArc        InsertArc(TNode,TNode,TCap,TCap,TFloat);
    TArc        InsertArc(TNode,TNode);
    TNode       InsertNode();
    TNode       InsertArtificalNode();
    TNode       InsertArcLabelAnchor(TArc);
    TNode       InsertThreadSuccessor(TNode);

    void        ExplicitParallels();

    void        SwapArcs(TArc,TArc);
    void        SwapNodes(TNode,TNode);
    void        FlipArc(TArc a);
    void        CancelArc(TArc);
    void        CancelNode(TNode);
    bool        ReleaseBendNodes(TArc);
    bool        ReleaseDoubleBendNodes();
    bool        ReleaseCoveredBendNodes();
    bool        ReleaseShapeNodes(TNode);
    void        DeleteArc(TArc);
    void        DeleteNode(TNode);
    void        DeleteArcs();
    void        DeleteNodes();
    void        ContractArc(TArc);
    void        IdentifyNodes(TNode,TNode);
}
\end{verbatim}
\end{mymethods}
Other than dense graph objects, sparse graphs involve data structures
for node-arc incidences and several layout entities. In addition, the methods
\verb/StartNode(TArc)/ and \verb/EndNode(TArc)/ depend on explicit but redundant
arrays.

Since sparse graphs are usually grown from scratch (only file constructors work
somewhat differently), the class \verb/sparseRepresentation/ allows to predefine
the final dimensions by the method \verb/SetCapacity(TNode,TArc)/ which effectively
prevents the iterated reallocation of the data structures.

The insertion of an arc connecting the nodes with indices \verb/v/ and \verb/w/
is achieved by \verb/InsertArc(v,w)/, \verb/InsertArc(v,w,uc,ll)/ or
\verb/InsertArc(v,w,uc,lc,ll)/ respectively. Each of the methods return the
index of the new arc. One may explicitly assign an upper capacity bound
\verb/uc/, a lower capacity bound \verb/lc/ and a length label \verb/ll/ to
the new arc. If no labels are specified, the labels are set to default values
or to random values depending on how the random generator is configured.

Once an arc is present, an alignment point for the arc label and bend nodes
for the arc drawing can be defined by the methods \verb/InsertAlignmentPoint()/
and \verb/InsertThreadSuccessor()/ respectively.
\sample
\begin{quote}
\begin{verbatim}

TArc a = InsertArc(v,v);
TNode x = InsertArcLabelAnchor(a);
TNode y = InsertThreadSuccessor(x);
TNode z = InsertThreadSuccessor(y);

\end{verbatim}
\end{quote}
introduces a new graph edge, namely a loop, which has two bend nodes $y$ and
$z$, and whose labels are drawn at the position of $x$. The coordinates have
to be specified by the method \verb/SetC/ separately.

To delete arcs, the following operations are provided: \verb/CancelArc(TArc)/
which deletes an arc and its reverse arc from the incidence lists, and
\verb/DeleteArc(TArc)/ which eventually deletes the canceled arc from all data
structures. Note that the latter operation may change the index of other arcs,
and hence must be applied very carefully. A call to \verb/DeleteArcs()/
eliminates all canceled arcs. This operation should not be used in algorithms
intermediately but rather as a concluding step.

Similarly, a call to \verb/CancelNode(TNode)/ cancels all arcs incident with
this node and \verb/DeleteNodes()/ eliminates all canceled and isolated nodes.
The methods \verb/DeleteNode(TNode)/ and \verb/DeleteNodes()/ potentially
change all node and arc indices.

Calling \verb/ReleaseBendNodes(a)/ eliminates the alignment point for the arc
label and all bend nodes assigned with $a$. Similarly,
\verb/ReleaseShapeNodes(v)/ deletes all artifical nodes assigned with the
vertex $v$. The method \verb/ReleaseDoubleBendNodes()/ checks for pairs of
consecutive bend nodes with the same position in a drawing and occasionally
deletes some bend nodes. This check includes the end nodes of all edges.
The method \verb/ReleaseCoveredBendNodes()/ also deletes bend nodes which
are a convex combination of the respective predecessor and successor node.

The method \verb/ContractArc(TArc)/ merges the incidence list of the end node
into the incidence list of the start node of the given arc and cancels the
arc and the end node. If the incidence lists provide a planar embedding, the
contraction preserves planarity.

More generally, \verb/IdentifyNodes(x,y)/ merges the incidence list of the
node \verb/y/ into the incidence list of the node \verb/x/ and cancels node
\verb/y/. The nodes to be identified may be non-adjacent.

The method \verb/ExplicitParallels()/ splits the arcs $a$ with capacity
\verb/UCap(a)>1/ into a couple of arcs which all have capacity $\leq 1$.
The total upper and lower bounds as well as sum of potential flows remain
unchanged.


\subsection{Node-Arc Incidences}
\label{slb_incidence_lists}
\myinclude\verb/sparseRepresentation.h/
\begin{mymethods}
\begin{verbatim}
class sparseRepresentation : public graphRepresentation
{
    TNode   StartNode(TArc);
    TNode   EndNode(TArc);

    TArc    First(TNode);
    void    SetFirst(TNode,TArc);
    TArc    Right(TArc);
    void    SetRight(TArc,TArc,TArc = NoArc);
    TArc    Left(TArc);

    void    ReorderIncidences(const TArc*,bool = false);
    void    RandomizeIncidenceOrder();
    void    GeometricIncidenceOrder();
}
\end{verbatim}
\end{mymethods}
By \nt{incidences}, one denotes the relation between geometric entities,
here: graphs nodes and arcs. For a given arc $a$, the two incident nodes
are retrieved by \verb/StartNode(a)/ and \verb/EndNode(a)/. The returned
node indices depend on the arc orientation, that is,
\verb/StartNode(a) == EndNode(a^1)/. Both methods are
defined for all graph objects. Dense graphs merely evaluate the arc index,
but sparse representations store an array for one of the methods.

For a given node $v$, the arcs $a$ with \verb/StartNode(a) == v/ form the
\nt{incidence list} of $v$. Indeed, the order of appearance on these lists
is important in many situations. Incidence lists are managed by iterator
objects which allow to iterate on the node incidences.
More information about iterators can be found in Chapter \ref{clb_it}.

The class \verb/abstractMixedGraph/ declares prototype methods \verb/First(TNode)/
and \verb/Right(TArc,TNode)/ which admit a generic class of iterators. More
explicitly, \verb/First(v)/ returns some arc with start node $v$, and
\verb/Right(a,u)/ returns the \nt{successor}\index{node incidence!successor}
of $a$ in the incidence list of $u$.

All graph objects implement the node incidence list defining methods
\verb/First()/ and \verb/Right()/. Again, dense graphs evaluate the arc index.
In the class \verb/sparseRepresentation/, data structures apply. In addition
to the general functionality of node incidence lists, sparse graph objects
admit the following operations:
\begin{itemize}
\item
The {\bf predecessor}\index{node incidence!predecessor} of any arc in the
incidence list of its start node is returned by \verb/Left(TArc)/. An explicit
data structure is generated from the successor incidences by the first call of
\verb/Left()/ which therefore takes $O(m)$ computing steps. Subsequent calls
are $O(1)$.
\item Node incidence lists can be low-level sorted by a method
    \verb/SwapArcs(TArc,TArc)/.
\item The first arc on a list can be set by a method \verb/SetFirst(TNode,TArc)/.
\item Arc directions can be changed by a method \verb/FlipArc(TArc)/.
\item \verb/SetRight(a1,a2,a3)/ makes $a_2$ the successor of $a_1$ in the start
    nodes incidence list and makes the original successor of $a_1$ the new
    successor of $a_3$. If only two arguments are specified, $a_2=a_3$ is assumed.
    Provided that the previous right-hand incidence order is $\dots a_1\dots a_2\dots a_3\dots$,
    circular lists are maintained for \verb/Left()/ and \verb/Right()/.
\end{itemize}
The most convenient way to manipulate the node incidence order is to call \verb/ReorderIncidences(pred,forward)/. This manipulates all \verb/Right()/
values simultaneously, depending on the value of \verb/forward/:
\begin{itemize}
\item If \verb/forward==true/, \verb/pred[a1] == a2/ results in \verb/Right(a2)==a1/.
\item If \verb/forward==false/, \verb/pred[a1] == a2/ results in \verb/Right(a2^1)==a1/.
\end{itemize}
There is a virtual method \verb/ReorderIncidences()/ for abstract mixed graphs
which does nothing and which is occasionally overwritten with the described sparse
implementations. By this, planarity recognition algorithms apply to all kinds of
graph objects, but planar representations are assigned only when the graph is
represented by incidence lists.

We mention two application codes from that, \verb/RandomizeIncidenceOrder()/ and
\verb/IncidenceOrderFromDrawing()/. The latter procedure tries to extract a
displayed incidence order. It works perfect with striaght line drawings but some
of the big node layout models are not handled yet.


\subsection{Sparse Bigraphs}
\label{slb_spsbig}
\myinclude\verb/sparseBigraph.h/
\begin{mymethods}
\begin{verbatim}
class biGraph
{
    TNode       SwapNode(TNode);
}
\end{verbatim}
\end{mymethods}
For the manipulation of bigraph nodes, an additional method \verb/SwapNode(v)/
is provided which moves the passed node $v$ to the other component. The return
value is the new index of $v$, say $u$. Effectively, the nodes $u$ and $v$ are
swapped. Deletions of outer nodes include an implicit \verb/SwapNode()/
operation.


\subsection{Planarity Issues}
\label{slb_planarity1}
\myinclude\verb/abstractMixedGraph.h/
\begin{mymethods}
\begin{verbatim}
class abstractMixedGraph
{
    void    MarkExteriorFace(TArc);
    TArc    ExteriorArc();
    bool    ExteriorNode(TNode,TNode = NoNode);

    enum    TOptExtractEmbedding {
                PLANEXT_DEFAULT = 0,
                PLANEXT_GROW = 1,
                PLANEXT_DUAL = 2,
                PLANEXT_CONNECT = 3
            };

    TNode   ExtractEmbedding(
                TOptExtractEmbedding = PLANEXT_DEFAULT,
                void* = NULL);
    TNode   Face(TArc);
    TNode   ND();
    void    ReleaseEmbedding();
}
\end{verbatim}
\end{mymethods}
A graph is \nt{planar} if it can be drawn in the plane without any edge
crossings. If for every node $v$ (and some virtual plane drawing), the arcs
starting at $v$ are listed in clockwise order by the incidence lists, the graph
is called \nt{combinatorially embedded}. In embedded graphs, the face left
hand of a given arc $a_0$ can be traversed as follows:
\sample
\begin{quote}
\begin{verbatim}
    TArc a = a0;
    do
    {
        a = Right(a^1);
        ...
    }
    while (a!=a0);
\end{verbatim}
\end{quote}
Supposed that the graph is connected, all faces are traversed counter clockwise,
except for the exterior face which is traversed clockwise.

Every graph object may provide a plane combinatorial representation from its own
but only sparse graph objects admit manipulation of the incidence lists. Arc
deletions and contractions maintain a planar representation but some care is
necessary when edges are inserted into an incidence structure:

The idea is that arcs are always inserted into the exterior face.
Calling \verb/MarkExteriorFace(a)/ sets the \verb/First()/ incidences
appropriately so that inserting an arc into the face left hand of $a$
will preserve the embedding. The arc $a$ is saved as a representant of the
exterior face and can be retrieved again by calling \verb/ExteriorArc()/.

Of course, it is possible to mark a face exterior, insert edges and then
revert to the original exterior face. The running time of
\verb/MarkExteriorFace()/ is proportional to the number of arcs of the
selected face.

Another effect of this method is that the face of a given arc $a_0$ can be
traversed in the converse (usually clockwise) direction of the previous example,
but only if the graph is biconnected:
\sample
\begin{quote}
\begin{verbatim}
    TArc aExt = ExteriorArc();
    MarkExteriorFace(a0);

    TArc a = a0;
    do
    {
        TNode v = StartNode(a);
        a = First(v)^1;
        ...
    }
    while (a!=a0);

    MarkExteriorFace(aExt);
\end{verbatim}
\end{quote}
There is no need to store a planar embedding in a special data structure
persistently. If one calls \verb/ExtractEmbedding()/, to every arc the
left hand face is saved internally. The procedure also determines a face
with a maximum number $\gamma$ of incident edges, marks this face exterior
and returns $\gamma$. The running time is $O(m)$ in the default setting.

If the graph is disconnected, the procedure processes each connected component
separately and exports the connected components by the node colours. Note
that for disconnected graphs, a distinction between \nt{regions} (of the
complement of plane drawing) and \nt{faces} (cycles in the boundary of a region)
is necessary and that this code handles faces rather than regions.

Depending on the optional parameters, the procedure performs additional
operations:
\begin{itemize}
\item For \verb/PLANEXT_DUAL/, the \verb/void*/ pointer is interpreted as a
    \verb/abstractMixedGraph*/ pointer to an empty graph which is filled with
    the dual incidence structure.
\item For \verb/PLANEXT_GROW/, the incidence lists are manipulated to obtain an
    embedding with the maximum of exterior nodes. In the extreme case, an
    outerplanar embedding results. Here the running time is $O(m^2)$ due to
    nested graph search for exterior separating edges.
\item For \verb/PLANEXT_CONNECT/, the connected components are linked such that
    in the resulting embedding, all original components are exterior. This graph
    augmentation effectively corrupts the face assignments. Hence a second pass
    with \verb/PLANEXT_DEFAULT/ would be necessary to rebuild the indices.
\end{itemize}
The number of faces is retrieved by \verb/ND()/ and the face left hand to a
given arc $a$ is obtained by \verb/Face(a)/. If the embedding has not been
extracted explicitly, \verb/Face()/ will initiate this operation in its first
occurence. So, for connected graphs, $a$ is an exterior arc if
\begin{verbatim}
    Face(a) == Face(ExteriorArc())
\end{verbatim}
provided that the graph is implicitly or explicitly embedded. In order to
decide if a given node $v$ is on the exterior face, one just calls
\verb/ExteriorNode(v)/.

Note that arc insertions and deletions call \verb/ReleaseEmbedding()/ and after
that the dual incidences must be extracted again.


\markright{LOGICAL OBJECTS}
\section{Logical Objects}
Logical objects describe a special view of another object. Roughly speaking,
a logical class defines the reduction mechanism of one optimization problem
to another. The referenced object may either be persistent or logical.

Logical objects keep reference of the original object all of their lifetime.
A referenced object may not be disallocated while logical views are present.
The benefit is a hidden back transformation of potential solutions of
the respective optimization problems. More precisely, the potential solutions
are merely logical views of solutions for the original problem.

\bigskip
\begin{figurehere}
\begin{center}
\epsfxsize=4cm
\epsfbox{canonical1.eps}
\epsfxsize=7cm
\hspace*{1cm}
\epsfbox{canonical2.eps}
\vspace{0.5cm}
\caption{\label{flb_canonical}Transformation of Network Flow Problems}
\end{center}
\end{figurehere}


\subsection{Canonical Flow Networks}
\label{slb231}
\myinclude\verb/digraphToDigraph.h/
\begin{mymethods}
\begin{verbatim}
class FNW2FNW : public virtual abstractDiGraph
{
    FNW2FNW(abstractDiGraph &);

    TNode       Source();
    TNode       Target();
    bool        Perfect();
}
\end{verbatim}
\end{mymethods}
A {\bf canonical} network flow problem is a flow network whose lower capacity
bounds are all zero and such that, except for a special node pair, all node
demands are zero. The class \verb/FNW2FNW/ allows to transform a given network
flow problem into an equivalent canonical problem. More explicitly, it manages:
\begin{myitemize}
\item[(1)] the reduction of the feasible circulation problem to the maximum
    $st$-flow problem,
\item[(2)] the reduction of the min-cost circulation problem to the min-cost
    $st$-flow problem.
\end{myitemize}
The reduction technique is adding an artificial source node and an artificial
target node, and adding some arcs to the network. The artificial nodes may be
accessed by the respective methods \verb/Source()/ and \verb/Target()/.

Any flow on the logical graph object corresponds to a pseudoflow of the
referenced flow network which respects the capacity bounds. For example,
a zero flow corresponds to a pseudoflow with \verb/Flow(a)==LCap(a)/.

If a feasible $b$-flow (circulation) of the referenced networks exists, any
maximum flow of the logical object will give such a $b$-flow. A maximum flow
of minimum costs corresponds to a minimum cost $b$-flow then. Given any
logical flow, it may be checked whether it maps to a feasible $b$-flow or
not by a call to the method \verb/Perfect()/.

The constructor method does not initialize the flow on the \verb/FNW2FNW/
object to zero, but to the image of the original flow. Some augmentation steps
on the artificial arcs are done immediately which do not affect the flow on
the original network.
\sample
\begin{quote}
\begin{verbatim}
G1 = new diGraph("sample.gob");
G2 = new FNW2FNW(G1);
G2 -> MaxFlow(G2->Source(),G2->Target());
if (G2->Perfect())
{
    F1 = new export("sample.rst");
    G1 -> WriteFlow(F1);
    delete F1;
}
delete G2;
delete G1;
\end{verbatim}
\end{quote}


\subsection{Layered Auxiliary Networks}
\label{slb232}
\myinclude\verb/auxiliaryNetwork.h/
\begin{mymethods}
\begin{verbatim}
class layeredAuxNetwork : public abstractDiGraph
{
    layeredAuxNetwork(abstractDiGraph &,TNode);

    void            Phase1();
    void            InsertProp(TArc);

    void            Phase2();
    bool            Blocked(TNode);
    TFloat          FindPath(TNode);
    void            TopErasure(TArc);
}
\end{verbatim}
\end{mymethods}
Layered auxiliary networks are instanciated by the Dinic maximum flow algorithm,
and, via inheritance, by the Micali/Vazirani cardinality matching algorithm.

A layered network is a logical view of a flow network, but with a different
incidence structure. Nodes and arcs are the same as for the orginal network,
and the arc capacities are the residual capacities of the original network.
The new incidence structure can be manipulated by two specific operations:
Arc insertions which are implemented by the method \verb/InsertProp(TArc)/, and
\nt{topological erasure} which is done by the method \verb/TopErasure(TArc)/.

\bigskip
\begin{figurehere}
\begin{center}
\epsfxsize=6cm
\epsfbox{auxiliary1.eps}
\epsfxsize=6cm
\hspace*{0.5cm}
\epsfbox{auxiliary2.eps}
\vspace{0.5cm}
\caption{\label{flb_auxiliary}A flow and a layered auxiliary network}
\end{center}
\end{figurehere}

\noindent
Topological erasure is the arc deletion process, but in a very efficient
implementation. If an arc is deleted, some node \verb/v/ may become
non-reachable from the source node \verb/ss/ specified in the constructor.
In this case, all arcs with start node \verb/v/ are deleted likewise. After
the topological erasure of \verb/v/, one has \verb/Blocked(v)==1/.

By that technique, the search procedure \verb/FindPath(t)/ which determines
an $st$-path with residual capacity is prevented from performing backtracking
operations. Note that the information about this path has to be passed from the
\verb/layeredAuxNetwork/ object to the original network for augmentation.
In the Dinic algorithm, both graphs share the predecessor data structure.

During augmentation, \verb/TopErasure(a)/ is called for every arc which has no
more residual capacity. Finally, the arc insertions and the topological erasure
operations are separated by calls to \verb/Phase1()/ and \verb/Phase2()/
respectively.

The topological erasure process needs $O(m)$ time during the construction of
a single blocking flow (called a {\bf phase})\index{phase of the Dinic method},
and the time needed for a \verb/FindPath()/ operation is proportional to the
length of the constructed path.

\bigskip
\begin{figurehere}
\begin{center}
\epsfxsize=3cm
\epsfbox{bipartite1.eps}
\epsfxsize=6cm
\hspace*{1cm}
\epsfbox{bipartite2.eps}
\vspace{0.5cm}
\caption{\label{flb_bipartite}A Maximum Assignment with Corresponding Flow}
\end{center}
\end{figurehere}


\subsection{Bipartite Matching Problems as Network Flow Problems}
\myinclude\verb/bigraphToDigraph.h/
\begin{mymethods}
\begin{verbatim}
class big2FNW : public virtual abstractDiGraph
{
    big2FNW(abstractBiGraph &,TCap *,TCap * = NULL);
    big2FNW(abstractBiGraph &,TCap);
    big2FNW(abstractBiGraph &);

    TNode       Source();
    TNode       Target();
}
\end{verbatim}
\end{mymethods}
This class handles the reduction of bipartite matching problems to network flow
problems ans is closely relates to the class of canonical flow networks which
were introduced before.

Technically, an artificial source node, an artificial target node, and
some arcs are added to the network. The arcs of the original bigraph
are directed from one part of the bigraph to the other part. The artificial
nodes may be accessed by the respective methods \verb/Source()/ and
\verb/Target()/.

Any flow on the logical graph object corresponds to a subgraph of the
referenced bigraph, and a zero flow corresponds to the empty subgraph.
If a perfect matching of the referenced bigraph exists, any maximum flow of
the logical object will give such a matching. In that case, a maximum flow of
minimum cost corresponds to a minimum cost perfect matching. It may be checked
whether a logical flow maps to a perfect matching or not by a call to the
method \verb/Perfect()/.

One may pass optional values by the displayed constructor methods: Using the
first method, upper and lower degree bounds are defined which appear
as capacity bounds of the artificial arcs. Even if lower degree bounds are
specified, the \verb/big2fnw/ object is always in canonical form.

The second constructor method is used to solve a $k$-factor problem. If no
parameters (up to the bigraph) are specified, the node demand labels
encapsulated in the bigraph come into play.
\sample
\begin{quote}
\begin{verbatim}
G1 = new bigraph("sample.gob");
G2 = new big2FNW(G1,1);
G2 -> MaxFlow(G2->Source(),G2->Target());
if (G2->Perfect())
{
    F1 = new export("sample.rst");
    G1 -> WriteSubgraph(F1);
    delete F1;
};
delete G2;
delete G1;
\end{verbatim}
\end{quote}
effectively determines a mximum 1-matching of the graph object \verb/G1/.

\bigskip
\begin{figurehere}
\begin{center}
\epsfxsize=4cm
\epsfbox{general2.eps}
\epsfxsize=6cm
\hspace*{1cm}
\epsfbox{general1.eps}
\vspace{0.5cm}
\caption{\label{flb_general}A Maximum Matching with Corresponding Balanced Flow}
\end{center}
\end{figurehere}


\subsection{General Matching Problems as Balanced Flow Problems}
\label{slb233}
\myinclude\verb/graphToBalanced.h/
\begin{mymethods}
\begin{verbatim}
class gra2bal : public virtual abstractBalancedFNW
{
    gra2bal(abstractGraph &,TCap *,TCap * = NULL);
    gra2bal(abstractGraph &,TCap);
    gra2bal(abstractGraph &);

    TNode       Source();
    TNode       Target();

    void        InitFlow();
    void        Update();
}
\end{verbatim}
\end{mymethods}
The idea of this problem transformation is to split the nodes and arcs into
symmetrical pairs and reduce to a balanced network flow problem. Similar
to the bipartite situation, artificial nodes and arcs are added. The resulting
flow network is bipartite, and the image of an original node consists of an
outer and an inner node.

The constructors and some other methods are defined in analogy to the bipartite
situation. If lower degree bounds are specified, the elimination of the lower
capacity bounds is done immediately. (If we would apply the class
\verb/fnw2fnw/, the complementarity relationship would be lost!)

Balanced network flow methods (not ordinary network flow methods!) manipulate
the subgraph encoded into the referenced object. However, a \verb/gra2bal/
object may maintain a flow which is non-symmetric, and independent from the
referenced object. One can generate and access this flow simply by calling any
network flow method or by explicit call to the method \verb/InitFlow()/.
By that, the flow is initialized to the symmetric logical flow, but can be
treated as an ordinary flow afterwards.

Every call to a balanced network flow method requires the symmetric flow.
If necessary, \verb/Update()/ is called which symmetrizes the flow again.
The subgraph of the referenced object is updated, and the physical flow is
disallocated. Note that \verb/Update()/ is called by the \verb/gra2bal/
destructor also.

Hence, there are two kinds of flow associated with a \verb/gra2bal/ object,
exactly one of these flows is present at each point of lifetime, and the object
is generated and destructed with a balanced flow.
\sample
\begin{quote}
\begin{verbatim}
G1 = new graph("sample.gob");
G2 = new gra2bal(G1,1);
G2 -> MaxFlow(G2->Source(),G2->Target());
G2 -> CancelEven();
if (G2->CancelOdd()>1) G2->MaxBalFlow(G2->Source());
delete G2;
F1 = new export("sample.rst");
G1 -> WriteSubgraph(F1);
delete F1;
delete G1;
\end{verbatim}
\end{quote}
determines a maximum 1-matching of the graph in \verb/"sample.gob"/ as follows:
First an ordinary maximum flow of the object \verb/G2/ is computed
(starting with a call to \verb/InitFlow/). The call of \verb/CancelEven()/
implies a call to \verb/Update()/. All subsequent operations immediately
manipulate the subgraph of the object \verb/G1/.


\subsection{Layered Shrinking Networks}
\label{slb234}
\myinclude\verb/shrinkingNetwork.h/
\begin{mymethods}
\begin{verbatim}
class layeredShrNetwork : public layeredAuxNetwork
{
    layeredShrNetwork(abstractBalancedFNW &,TNode,
                      staticQueue<TNode,TFloat> **,
                      staticQueue<TArc,TFloat> **,
                      staticQueue<TArc,TFloat> **);

    TNode           StartNode(TArc);

    TNode           DDFS(TArc);
    void            ShrinkBlossom(TNode,TArc,TFloat);

    TFloat          FindPath(TNode);
    void            Expand(TNode,TNode);
    void            CoExpand(TNode,TNode);
    void            Traverse(TNode,TNode,TNode,
                             TArc,TArc *,TArc *);

    void            Augment(TArc);
}
\end{verbatim}
\end{mymethods}
This class makes the topological erasure technique of
layered auxiliary networks available to matching and balanced network flow
problems. But this class has a lot of additional data structure and
functionality.

If one looks at the constructor interface only, it is obvious that there are
a lot of dependencies between the \verb/layeredShrNetwork/ objects and the
algorithm which constructs the object. We do not go into the details, but need
to describe the functionality and the running times of some of the methods.

Roughly speaking, a \nt{double depth first search} \verb/DDFS(a)/ determines the
blossom which occurs if the arc \verb/a/ is added to the layered auxiliary
network, and returns the base \verb/b/ of this blossom. Then the blossom can
either be shrunk by a call \verb/ShrinkBlossom(b,a,..)/, or a minimum length
augmenting path is found which can be extracted by a call of
\verb/FindPath(s^1)/.

Note that \verb/FindPath()/ recursively calls \verb/Expand()/, \verb/CoExpand()/
and \verb/Traverse()/ which are only needed at this point. The method
\verb/Augment()/ actually does the augmentation and triggers off the necessary
topological erasure operations.

All these operations must be separated from the \verb/InsertProp()/ operations
by using the methods \verb/Phase2()/ and a \verb/Phase1()/.
The complexity of these new operations can be bounded for
a whole phase, and is $O(m)$ for the \verb/DDFS()/ operations. The time needed
for \verb/FindPath()/ operations is proportional to the length of the constructed
paths again.



\subsection{Surface Graphs}
\label{slb235}
\myinclude\verb/surfaceGraph.h/
\begin{mymethods}
\begin{verbatim}
class surfaceGraph : public abstractBalancedFNW
{
    surfaceGraph(abstractBalancedFNW &);

    TFloat      ModLength(TArc);
    TFloat      RModLength(TArc);
    void        ShiftPotential(TNode,TFloat);
    void        ShiftModLength(TArc,TFloat);
    bool        Compatible();
    void        CheckDual();

    TArc        FindSupport(TNode,TArc,
                            dynamicStack<TNode,TFloat> &);
    void        Traverse(TArc*,TArc,TArc);
    void        Expand(TArc*,TArc,TArc);
    void        ExpandAndAugment(TArc,TArc);

    TFloat      ComputeEpsilon(TFloat*);
    void        PrimalDual0(TNode);
    void        Explore(TFloat*,goblinQueue<TArc,TFloat> &,
                        THandle,TNode);
    TFloat      ComputeEpsilon1(TFloat*);
    void        PrimalDual1(TNode);
}
\end{verbatim}
\end{mymethods}
Surface graphs are data structures which are needed by all weighted matching
algorithms. A surface graph object keeps a
shrinking family of a given balanced flow network and forms a new graph in
which some of the original nodes are identified, and some arcs are redirected.

While shrinking families will be discussed later in Section \ref{slb42}, we
need to describe the other components of the primal-dual algorithm here:

{\bf Modified length labels}\index{modified length labels} are the reduced
costs known from linear programming and are available by the method
\verb/ModLength()/. They may be present by an own data structure, or must be
computed recursively by \verb/RModLength()/
which evaluates the node potentials and the shrinking family data structure.
This recursive computation is needed when working with large scale geometrical
matching problems and is enabled by the context flag \verb/methModLength/.

If disabled, mismatchs between physical and computed modified lengths can be
detected by a call of \verb/CheckDual()/. This is done automatically before
the primal-dual methods halt, but only if the context flag \verb/methFailSave/
is set. In that case, \verb/Compatible()/ is called likewise to check for
reduced costs optimality.

Note that a single \verb/RModLength()/ call takes $O(n)$ operations, and that
exhaustive computation may increase the running time of the whole algorithm by
a factor of $n$. Hence some care is recommended when setting
\verb/methModLength/ and \verb/methFailSave/. The complexity statements which
follow are true only if both variables are zero.

The method \verb/FindSupport/ determines the nodes of a blossom, and prepares
the data structures which are necessary to reconstruct an augmenting path
traversing this blossom. The latter task is managed by the methods
\verb/Traverse/, \verb/Expand/ and \verb/ExpandAndAugment/ which take
$O(n\log{n})$ time per each augmentation. The \verb/FindSupport/ operations
take $O(n)$ time per {\bf phase}\index{phase of the Dinic method}, that is the
period between two augmentations of the PD algorithm.

GOBLIN includes three implementations of the PD algorithm which can be selected
by the context flag \verb/methPrimalDual/. The options \verb/methPrimalDual==0/
and \verb/methPrimalDual==1/ depend on \verb/ComputeEpsilon()/, whereas
the option \verb/methPrimalDual==2/ depends on \verb/ComputeEpsilon1()/.
Both methods determine the amount of a \nt{dual update}, that is an update on
the node potentials. The first procedure searches all arcs and takes $O(m)$
time, whereas the second procedure searches only one arc for each node and
hence takes $O(n)$ time.

In the current state of development, \verb/methPrimalDual=0/ causes the use
of \verb/PrimalDual0/, whereas \verb/methPrimalDual=1/ and
\verb/methPrimalDual=2/ cause the use of \verb/PrimalDual1/. Both methods
use a dual update technique which takes $O(m)$ time so that the overall
complexity is $O(nm)$ per phase, independent of which implementation in used.
It is planned, however, to improve \verb/PrimalDual1/ to $O(n^2)$ time.


\subsection{Suboptimal Balanced Flows}
\myinclude\verb/balancedToalanced.h/

\bigskip\noindent
The class \verb/bal2bal/ is the symmetrical counterpart of the class \verb/FNW2FNW/,
and hence manages:
\begin{myitemize}
\item[(1)] the reduction of the feasible balanced circulation problem
    to the maximum balanced $st$-flow problem,
\item[(2)] the reduction of the min-cost balanced circulation problem
    to the min-cost balanced $st$-flow problem.
\end{myitemize}
The main application is the reduction of the \nt{odd cycle canceling problem}
for balanced network flows to a balanced $st$-flow problem. This problem occurs
if an integral circulation is symmetrized so that some flow values become
non-integral.

These reductions eventually extend the Anstee maximum balanced flow algorithm
to the general setting of balanced flow networks, and allow a strongly
poynomial implementation of the primal-dual algorithm respectively.


\subsection{Making Logical Objects Persistent}

Logical objects turn into persistent objects by writing them to file and
loading them again. By running optimization methods on the persistent object,
one can avoid the time consuming dereferencing steps to the original data
object.

However, the capability of back transformation of computational results to the
original problem instance is lost. If necessary, the results can be written
to a file and reimported into the logical object. 
\sample
\begin{quote}
\begin{verbatim}
G1 = new diGraph("sample.gob");
G2 = new FNW2FNW(G1);
F1 = new export("sample.tmp");
G2 -> Write(F1);
delete F1;

G3 = new diGraph("sample.tmp");
G3 -> MaxFlow(G2->Source(),G2->Target());

F1 = new export("sample.tmp");
G3 -> WriteFlow(F1);
delete F1;
delete G3;

F2 = new import("sample.tmp");
G2 -> ReadFlow(F2);
delete F2;

if (G2->Perfect())
{
    F1 = new export("sample.rst");
    G1 -> WriteFlow(F1);
    delete F1;
}

delete G2;
delete G1;
\end{verbatim}
\end{quote}
It has turned out that file export is rather expensive, and should be used by
extremely search intensive problem solvers only. With some additional efforts
for mapping the potential solutions, copy constructors as presented in Section
\ref{slb_copy} are highly preferable.



\markright{DERIVED REPRESENTED OBJECTS}
\section{Derived Represented Objects}

There are some situations where the implementation of a logical class without
an own incidence structure is inappropriate for the problem transformation:
\begin{myitemize}
\item If the transformation mechanisms would be very expensive,
\item If the problem to solve is very complicated so that the instances
    are rather small,
\item If the transformation is of academic interest rather than practical need.
\end{myitemize}
In what follows, classes are listed which inherit a representation from other
represented classes. Typically, the class interface only consist of a
constructor method.


\subsection{Copy Constructors}
\label{slb_copy}

Each of the persistent base classes provides a copy constructor which supports
the following general purpose options:
\begin{itemize}
\item \verb/OPT_CLONE/: Generate a plain copy of the graph. That is, map
    every node and every arc of the original graph. If this option is absent,
    arcs with zero capacity are not mapped.
\item \verb/OPT_PARALLELS/: Allow parallel edges. If this option is absent,
    an arbitrary arc of every parallel class is mapped. The option is
    immaterial if mapping to dense implementations.
\item \verb/OPT_SUB/: Export the subgraph labels into a separate object. That
    is, the capacity of a mapped arc is the subgraph label of the original arc.
\end{itemize}
The \verb/graph/ and the \verb/denseGraph/ copy constructors accept arbitrary
mixed graphs and just forget about the orientations. The directed classed also
accept mixed graphs and, in principle, generate antiparallel arc pairs for
undirected arcs in the original graph. But be careful with the constructor
method \verb/digraph(G,opt)/: If the input graph is bipartite and
\verb/OPT_CLONE/ is absent, the arcs are just oriented from one partition
(the end node with smaller index) to the other.


\subsection{Mapping Back Derived Graph Objects}
\methods
\begin{quote}
\begin{verbatim}
class abstractMixedGraph
{
    TNode   OriginalNode(TNode);
    TArc    OriginalArc(TArc);
    void    ReleaseNodeMapping();
    void    ReleaseArcMapping();
}
\end{verbatim}
\end{quote}
When generating graph objects from others, it is sometimes useful to
maintain the mappings of nodes and arcs from the derived to the original
graph. In principle, this information can be accessed by the methods
\verb/OriginalNode()/ and \verb/OriginalArc()/.

However, these mappings must be generated explicitly by the constructor option
\verb/OPT_MAPPINGS/ and only few classes implement this option yet now. Even
more, the mappings are invalidated by every node or arc deletion operation.
If there is no predecessor in the original graph, or if no mappings are
available, \verb/NoNode/ (\verb/NoArc/) is returned.


\subsection{Line Graphs and Truncation of the vertices}
\label{sbl_line_graph}
\myinclude\verb/sparseGraph.h/
\begin{mymethods}
\begin{verbatim}
class lineGraph : public mixedGraph
{
    enum TOptLineGraph {
        LG_UNDIRECTED = 0,
        LG_DIRECTED   = 1
    };

    lineGraph(abstractMixedGraph& G,TOption = LG_DIRECTED);
}

class planarLineGraph : public graph
{
    planarLineGraph(abstractMixedGraph &,
                    TOption option = 0);
}

class vertexTruncation : public graph
{
    vertexTruncation(abstractMixedGraph&,TOption = 0);

};
\end{verbatim}
\end{mymethods}
In a \nt{line graph} the nodes are the arcs of the original graph $G$, and nodes
are adjacent if and only if the arcs share an end node in the original graph.
The constructor method \verb/lineGraph(G)/ matches this graph-theoretical definition
of line graphs if the \verb/LG_DIRECTED/ option is not specified.

If \verb/LG_DIRECTED/ is specified, arcs in the line graph are directed if one of
the original arcs is directed, and then preserve the original direction. But the
underlying graph of a directed line graph is not the same as the undirected line
graph: Two directed arcs with the same end node do not map to an arc in a directed
line graph.

By the constructor \verb/planarLineGraph(G)/, edges are generated only for
pairs of edges which are neighbors in the incidence lists of $G$. We refer to
this as \nt{planar line graphs} since planar input graphs are mapped to planar
graphs by this procedure. More explicitly, the faces are mapped to face of the same
length, and the boundary cycle is directed counter clockwise. The nodes of the
original graph are also mapped to faces where the boundary cycle is directed
clockwise and its length is the degree of the original node.

If $G$ is the surface graph of some non-degenerate polyhedron (all vertices have
degree 3), both definitions coincide. If $G$ is the surface graph of some regular
polyhedron (all faces are equilateral), the planar surface graph has the same
geometric interpretation.

By the constructor \verb/vertexTruncation(G)/, the vertices of the original graph
are also replaced by cycles of the adjacent edges, and these cycles form faces
of the newly generated graph. Other than for the planar line graph, the original
arcs are maintained, and all vertices have degree 3.

Loosely speaking, both planar transformations rasp off the vertices of the
original polyhedron, and the planar line graph is the extremal case where the
original edges collapse the vertices.


\bigskip
\begin{figurehere}
\begin{center}
\epsfxsize=3.5cm
\epsfbox{lgraph1.eps}
\epsfxsize=3.5cm
\hspace*{2cm}
\epsfbox{lgraph2.eps}
\vspace{0.5cm}
\caption{\label{flb_lgraph}A Graph and its Line Graph}
\end{center}
\end{figurehere}


\subsection{Tearing Apart the Regions of a Planar Graph}
\label{sbl_facet_separation}
\myinclude\verb/sparseGraph.h/
\begin{mymethods}
\begin{verbatim}
class facetSeparation : public graph
{
    enum TOptRotation {
        ROT_NONE = 0,
        ROT_LEFT = 1,
        ROT_RIGHT = 2
    };

    facetSeparation(abstractMixedGraph&,
                    TOptRotation = ROT_NONE);
}
\end{verbatim}
\end{mymethods}
This constructor method is another technique to generate regular
graphs.
\begin{itemize}
\item \verb/ROT_NONE/: Grow the original nodes to faces of the same degree,
    and the original edges to 4-sided faces. The resulting graph is 4-regular.
\item \verb/ROT_LEFT/: As before, but triangulate the faces representing the
    original edges such that every node is incident with exactly one
    triangulation arc and the resulting graph is 5-regular. Two different
    triangulations are possible. Choose the one which can be interpreted as
    rotating the original faces counterclockwise.
\item \verb/ROT_RIGHT/: Analogous to the \verb/ROT_LEFT/ option but rotate
    clockwise.
\end{itemize}
This construction is well-defined for every graph with a planar representation,
and a planar representation is provided for the resulting graph.

As an example, if \verb/G/ is a tetrahedron, \verb/facetSeparation(G,facetSeparation::ROT_LEFT)/
will produce an icosahedron.


\subsection{Complementary Graph}
\label{sbl_complementary_graph}
\myinclude\verb/sparseGraph.h/
\begin{mymethods}
\begin{verbatim}
class complementaryGraph : public graph
{
    complementaryGraph(abstractMixedGraph &,TOption);
}
\end{verbatim}
\end{mymethods}
The \nt{complementary graph} is defined on the same node set as the original graph,
and two nodes are adjacent if and only if they are non-adjacent in the original graph.
Complementary graphs are used to switch between stable set and clique problems.

Note that the complement of a graph with many nodes but few edges requires a lot of
computer storage.


\subsection{Dual Graphs}
\label{sbl_dual_graph}
\myinclude\verb/sparseGraph.h/
\begin{mymethods}
\begin{verbatim}
class dualGraph : public graph
{
    dualGraph(abstractMixedGraph&,TOption = 0);
}

class directedDual : public diGraph
{
    directedDual(abstractMixedGraph&,TOption = 0);
}
\end{verbatim}
\end{mymethods}
To generate a \nt{dual graph}, the input graph mustprovide a planar representation.
A geometric embedding is not required. The nodes of the new graph are the regions
of the original graph and the arcs map one-to-one. Nodes are adjacent if and only
if the regions share an arc in the original graph.

Dualization preserves planarity. That is, the dual of a dual graph can be computed
instantly and, by that, the original graph and planar representation will result.
An existing drawing of the original graph is translated to the dual graph in a
very simple way. This drawing does not map back to the original drawing and
produces edge crossings at least for the unbounded region.

It is also possible to generate \nt{directed dual graphs} where the arcs are
oriented as follows:
\begin{itemize}
\item Exterior edges of the primal graph are pointing towards the exterior
    region.
\item If an interior edge is directed in the primal graph, the dual arc will
    cross from the left-hand face to the right-hand face (provided that the
    edges are ordered clockwise in the primal graph)
\item If an interior edge does not have an explicit orientation, the colours of
    its end nodes are compared, and the edge is directed from the smaller
    colour index to the higher one.
\end{itemize}
By this procedure, \nt{bipolar digraphs} (acyclic digraphs with a unique source
and a unique sink node) are mapped to bipolar dual digraphs. The dual source
and target nodes are available by \verb/Source()/ and \verb/Target()/ for
further processing. These nodes are adjacent by the \verb/ExteriorArc()/.


\subsection{Spread Out Planar Graphs}
\label{sbl_spread_out}
\myinclude\verb/sparseGraph.h/
\begin{mymethods}
\begin{verbatim}
class spreadOutRegular : public graph
{
    spreadOutRegular(abstractMixedGraph&,TOption = 0);
}
\end{verbatim}
\end{mymethods}
This class is intended for displaying regular polyhedra in the plane. The input
graph must already have a planar representation. Furthermore, a spanning tree
must be available by the predecessor labels.

The tree edges are replaced by an Hamiltonian cycle in which every of the former
edges occurs twice. The resulting graph is outerplanar with the new cycle forming
the exterior face. The graph is drawn with the specialized method described in
Section \ref{slb_equilateral},

Formally, \verb/spreadOutRegular/ objects can be obtained from any planar graph.
But the final drawing step produces readable output only in the situation of
regular polyhedra.


\subsection{Metric Closure}
\label{slb_metric_closure}
\myinclude\verb/denseGraph.h/
\begin{mymethods}
\begin{verbatim}
class metricGraph : public denseGraph
{
    metricGraph(abstractGraph &);
}
\end{verbatim}
\end{mymethods}
This class defines the \nt{metric closure} of undirected graphs, in which the
length of an arc corresponds to the minimum length of a path in the original
graph. The metric closure is used to generate heuristic hamiltonian cycles for
sparse graphs.

\bigskip
\begin{figurehere}
\begin{center}
\epsfxsize=4cm
\epsfbox{closure1.eps}
\epsfxsize=4cm
\hspace*{1cm}
\epsfbox{closure2.eps}
\vspace{0.5cm}
\caption{\label{flb_closure}A Graph and its Metric Closure}
\end{center}
\end{figurehere}


\subsection{Distance Graphs}
\label{sbl_distance_graph}
\myinclude\verb/denseDigraph.h/
\begin{mymethods}
\begin{verbatim}
class distanceGraph : public denseDiGraph
{
    distanceGraph(abstractMixedGraph &);
}
\end{verbatim}
\end{mymethods}
This is the asymetric counterpart to the metric closure, in which the length of
an arc corresponds to the minimum length of a directed path in the original
(possibly mixed) graph object.


\subsection{Complete Orientation}
\label{sbl_complete_orientation}
\myinclude\verb/sparseDigraph.h/
\begin{mymethods}
\begin{verbatim}
class completeOrientation : public diGraph
{
    completeOrientation(abstractMixedGraph &G,
                            TOption options = 0);

    TArc    OriginalArc(TArc);
}
\end{verbatim}
\end{mymethods}
The \nt{complete orientation} of a mixed graph is the digraph in which every
undirected edge of the original object is replaced by a pair of antiparallel
arcs. If the optional parameter is \verb/OPT_REVERSE/, directed arcs are
mapped to a pair of arcs likewise. For every arc \verb/a/ in the orientation,
the origin can be obtained by the call \verb/OriginalArc(a)/.


\subsection{Induced Orientation}
\label{sbl_induced_orientation}
\myinclude\verb/sparseDigraph.h/
\begin{mymethods}
\begin{verbatim}
class inducedOrientation : public diGraph
{
    inducedOrientation(abstractMixedGraph &G,
                            TOption options = 0);
}
\end{verbatim}
\end{mymethods}
The \nt{complete orientation} of a mixed graph is the digraph in which every
undirected edge of the original graph object is oriented from the smaller node
colour index to the higher index. Since edges with equal colour indices are
omitted, this construction can be used to achieve oriented bigraphs. Another
application is the generation of \nt{$st$-orientations} from $st$-numberings.


\subsection{Node Splitting}
\label{slb_node_splitting}
\myinclude\verb/sparseDigraph.h/
\begin{mymethods}
\begin{verbatim}
class nodeSplitting : public diGraph
{
    nodeSplitting(abstractMixedGraph &,TOption = 0);
}
\end{verbatim}
\end{mymethods}
The \nt{node splitting} of a mixed graph is similar to its complete
orientation. In addition, every node $v$ of the original graph is replaced
by a pair $v_1$, $v_2$ and an arc $v_1 v_2$ whose capacity bound is the
demand of the original node. Every eligible arc $uv$ in the original graph are
represented by the arc $u_2 v_1$ in the node splitting.
Note that the origins of the arcs in a node splitting cannot be dereferenced.


\subsection{Tilings}
\label{slb_tiling}
\myinclude\verb/sparseGraph.h/
\begin{mymethods}
\begin{verbatim}
class tiling : public graph
{
    tiling(abstractMixedGraph &,TOption,TNode,TNode);
}
\end{verbatim}
\end{mymethods}
A tiling of a given graph consists of several copies of the original. The original
graph should provide a plane embedding, and the nodes 0,1,2,3 should form a rectangle
with the remaining nodes in the interior. The corner nodes are identified in the tiling.

By this construction principle, one obtains a series of planar triangulated graphs
each of which has an exponential number of $1$-factors and $2$-factors, and also an
exponential number of odd cycles.

\bigskip
\begin{figurehere}
\begin{center}
\epsfxsize=11cm
\epsfbox{tiling.eps}
\vspace{0.5cm}
\caption{\label{flb_tiling}A Tiling}
\end{center}
\end{figurehere}


\subsection{Split Graphs}
\label{slb_split_graph}
\myinclude\verb/balancedDigraph.h/
\begin{mymethods}
\begin{verbatim}
class splitGraph : public balancedFNW
{
    splitGraph(abstractDiGraph &G,TNode s,TNode t);

    TNode Source() {return n-1;};
    TNode Target() {return n-2;};
}
\end{verbatim}
\end{mymethods}
Split graphs establish balanced network flow (matching) formulations of
ordinary $st$-flow problems with integral capacities. Since matching algorithms
are technically much more complicated than network flow methods, split graphs
are not useful for practical computations but rather for the debugging of
matching algorithms.

\bigskip
\begin{figurehere}
\begin{center}
\epsfxsize=3.5cm
\epsfbox{split1.eps}
\epsfxsize=7cm
\hspace*{1cm}
\epsfbox{split2.eps}
\vspace{0.5cm}
\caption{\label{flb_splitgraph}A Digraph and its Split Graph}
\end{center}
\end{figurehere}


\subsection{Subgraph induced by a Node or Arc Set}
\label{sbl_induced_subgraph}
\myinclude\verb/mixedGraph.h/
\begin{mymethods}
\begin{verbatim}
class inducedSubgraph : public mixedGraph
{
    inducedSubgraph(abstractMixedGraph&,indexSet<TNode>&,
        TOption = OPT_PARALLELS);
    inducedSubgraph(abstractMixedGraph&,indexSet<TNode>&,
        indexSet<TArc>&,TOption = OPT_PARALLELS);
}
\end{verbatim}
\end{mymethods}
Other than the subgraphs which can be generated by a \verb/mixedGraph/
constructor and which map every node of the original graph, this class handles
subgraphs which are induced by a given node set. This node set is passed as an
index set (see Chapter \ref{clb_index_set} for a description) and may be 
further restricted by an arc index set.

More explicitly, the graph \verb/inducedSubgraph(G,V,A,opt)/ consists of all
nodes in the index set $V$. Only the original arcs in $A$ are mapped, namely
iff both end nodes are in $V$. If no arc set $A$ is specified, the resulting
\nt{induced subgraph} is as in the literature.

If the option \verb/OPT_PARALLELS/ is specified or if the parameter $opt$ is
omitted, parallel arcs are allowed. Otherwise, some minimum length edge is
mapped. The other supported options are \verb/OPT_NO_LOOPS/, \verb/OPT_SUB/
and \verb/OPT_MAPPINGS/ with the already described semantics.


\subsection{Bigraph induced by two Node Colours}
\label{sbl_induced_bigraph}
\myinclude\verb/sparseBigraph.h/
\begin{mymethods}
\begin{verbatim}
class inducedBigraph : public biGraph
{
    inducedBigraph(abstractMixedGraph&,indexSet<TNode>&,
        indexSet<TNode>&,TOption = OPT_PARALLELS);
}
\end{verbatim}
\end{mymethods}
This constructor \verb/inducedBigraph(G,U,V,opt)/ works much like for the
previously described class \verb/inducedSubgraph/. Two specified node sets
$U$ and $V$ are mapped. Edges are mapped only if one end node is in $U$
and the other end node is in $V$ and implicitly oriented from $U$ to $V$ then.
Both sets must be disjoint; otherwise an exception \verb/ERRejected()/ is
raised. The options are handled as before.


\subsection{Colour Contraction}
\label{sbl_colour_contraction}
\myinclude\verb/mixedGraph.h/
\begin{mymethods}
\begin{verbatim}
class colourContraction : public mixedGraph
{
    colourContraction(abstractMixedGraph&,TOption = 0);
}
\end{verbatim}
\end{mymethods}
The nodes of \verb/colourContraction(G,opt)/ are the colour classes of $G$.
That is, all nodes are mapped and equally coloured nodes of $G$ are mapped to
the same node. Edges are mapped only if the end nodes belong to different
colour classes.

Two options are supported: If the option \verb/OPT_PARALLELS/ is specified,
parallel arcs are allowed. Otherwise, some minimum length edge is mapped. If
the option \verb/OPT_SUB/ is specified, the subgraph data structure is
exported to an own graph object.


\subsection{Transitive Closure}
\label{sbl_transitive_closure}
\myinclude\verb/sparseDigraph.h/
\begin{mymethods}
\begin{verbatim}
class transitiveClosure : public diGraph
{
    transitiveClosure(abstractDiGraph&G,TOption = 0);
}
\end{verbatim}
\end{mymethods}
This constructor \verb/transitiveClosure(G,opt)/ copies the input digraph and
augments it by all \nt{transitive arcs} (whose end nodes are connected by a
directed path with at least two arcs length). The running time is $O(nm)$. If the
option \verb/OPT_SUB/ is specified, the input graph is encoded by the edge
colours.


\subsection{Intransitive Reduction}
\label{sbl_intransitive_reduction}
\myinclude\verb/sparseDigraph.h/
\begin{mymethods}
\begin{verbatim}
class intransitiveReduction : public diGraph
{
    intransitiveReduction(abstractDiGraph&,TOption = 0);
}
\end{verbatim}
\end{mymethods}
For a given acyclic digraph \verb/G/, the constructor
\verb/intransitiveReduction(G,opt)/ determines a maximal subgraph without any
transitive and parallel arcs. The running time is $O(nm)$. If the option
\verb/OPT_SUB/ is specified, the input DAG is copied, and the intransitive
subgraph is encoded by the edge colours.


\subsection{Explicit Surface Graphs}
\myinclude\verb/mixedGraph.h/
\begin{mymethods}
\begin{verbatim}
class explicitSurfaceGraph : public mixedGraph
{
    explicitSurfaceGraph(abstractMixedGraph&,
            nestedFamily<TNode>&,TFloat*,TArc*);
}
\end{verbatim}
\end{mymethods}
This class has been added for the graphical tracing of the Edmonds'
spanning arborescence method only. In a future release, it may also be
used to trace matching algorithms.

The constructor parameters are the digraph for which the arborescence is
computed, the current shrinking family, the modified length labels and the
predecessors of the original digraph.


\subsection{Explicit Subdivision}
\myinclude\verb/mixedGraph.h/
\begin{mymethods}
\begin{verbatim}
class explicitSubdivision : public mixedGraph
{
    explicitSubdivision(abstractMixedGraph&);
}
\end{verbatim}
\end{mymethods}
This constructor method replaces every edge of the input graph by a path in
which every intermediary node represents a bend node in the original graph.
Straight line edge are unchanged, and the original drawing is preserved. The
method is intended for layout postprocessing.


\subsection{Voronoi Diagram}
\myinclude\verb/sparseGraph.h/
\begin{mymethods}
\begin{verbatim}
class voronoiDiagram : public graph
{
    voronoiDiagram(abstractMixedGraph&);
    ~voronoiDiagram();

    TFloat UpdateSubgraph();
}
\end{verbatim}
\end{mymethods}
This class has been introduced for the Mehlhorn Steiner tree Heuristic. Other
applications seem obvious, especially to the $T$-join solver. The name
indicates a relationship to the well-known geometric structure, but do not
confuse both notions.

The constructor method generates a copy of the given graph in which the node
sets of the partition data structure are contracted. The mapping of the nodes
and edges is preserved transparently.

The procedure assumes that in the original graph the predecessor labels form
partial trees which span the node partition sets and which are rooted at some
terminal node (see Section \ref{slb_steiner}. The needed data structures for
the original graph are implicitly set up by calling the method
\verb/VoronoiRegions()/. By that, the partial trees consist of shortest paths,
corresponding distance labels are given, and hence the transformed graph edges
are shortest paths between different terminal nodes.

The method \verb/UpdateSubgraph()/ considers the predecessor arcs of the
transformed graph and maps them back to paths in the original problem
instance. The result is a subgraph, not a set of modified predecessor labels!



\markright{GRAPH OBJECT TEMPLATES}
\section{Graph Object Templates}

\subsection{Open Grids}
\label{slb_open_grid}
\myinclude\verb/sparseGraph.h/
\begin{mymethods}
\begin{verbatim}
class openGrid : public graph
{
    enum TOptGrid {
        GRID_TRIANGULAR,GRID_SQUARE,GRID_HEXAGONAL
    };

    openGrid(TNode,TNode,TOptGrid,goblinController&);
}
\end{verbatim}
\end{mymethods}
An \nt{open grid} is a planar graph which is drawn in the plane with congruent
regular interior faces. All three possible face types are supported and can be
specified by the \verb/TOptGrid/ parameter. The overall shape is a four-sided
figure, as long as two positive values are passed by the dimensional parameters.
If only one dimensional parameter is passed, and the second one is zero, the
overall shape repeats the interior face type.

For example, \verb/openGrid(6,15,GRID_HEXAGONAL)/ generates the graph depicted
in Figure \ref{flb_open_grid}. Note the restriction on the parity of the
dimensional parameters in the hexagonal case!

\bigskip
\begin{figurehere}
\begin{center}
\epsfxsize=8cm
\epsfbox{eps/hexagonalGrid.eps}
\vspace{0.5cm}
\caption{\label{flb_open_grid}An Hexagonal Open Grid}
\end{center}
\end{figurehere}


\subsection{Polar Grids}
\label{slb_polar_grid}
\myinclude\verb/sparseGraph.h/
\begin{mymethods}
\begin{verbatim}
class polarGrid : public graph
{
    enum TOptPolar {
        POLAR_DEFAULT,
        POLAR_TRIANGULAR,POLAR_SQUARE,
        POLAR_CONE,POLAR_HEMISPHERE,POLAR_TUBE
    };

    polarGrid(TNode,TNode,TNode,TOptPolar,
                TOptPolar,goblinController&);
}
\end{verbatim}
\end{mymethods}
A \nt{polar grid} is a planar graph which is drawn on a 3D surface. Basically,
\verb/polarGrid(k,l,p,faceType,surfaceType)/ consists of a regular grid, either
with triangular or four-sided faces, depending on the \verb/faceType/ parameter.
The first and the last column are identified. The first and the last {\it row}
are not identified but potentially connected to the at most two additional pole
nodes.

For example, \verb/polarGrid(4,11,1,POLAR_TRIANGULAR,POLAR_CONE)/ generates the
graph depicted in Figure \ref{flb_polar_grid}. The concept is flexible enough to
admit the construction of the most regular polyhedra:
\begin{itemize}
\item \verb/polarGrid(1,n,0,..)/ gives cycles of length $n$.
\item \verb/polarGrid(2,n,0,POLAR_SQUARE,..)/ gives prisms.
\item In particular, \verb/polarGrid(2,4,0,..)/ is the hexahedron.
\item \verb/polarGrid(2,n,0,POLAR_TRIANGULAR,..)/ gives antiprisms.
\item \verb/polarGrid(1,n,1,..)/ gives pyramids, also known as wheels.
\item Especially, \verb/polarGrid(1,3,1,..)/ is the tetrahedron.
\item \verb/polarGrid(1,n,2,..)/ gives bipyramids.
\item In particular, \verb/polarGrid(1,4,2,..)/ is the octahedron.
\item The icosahedron is \verb/polarGrid(2,5,2,POLAR_TRIANGULAR,..)/
\end{itemize}
All Archimedian solids missing in this list can be derived from polar grid objects
by composing the \verb/dualGraph/, \verb/planarLineGraph/, \verb/vertexTruncation/
or \verb/facetSeparation/.

\bigskip
\begin{figurehere}
\begin{center}
\epsfxsize=8cm
\epsfbox{eps/polarGrid.eps}
\vspace{0.5cm}
\caption{\label{flb_polar_grid}A Unipolar Triangular Grid and a Minimum Clique Cover}
\end{center}
\end{figurehere}


\subsection{Torus Grids}
\label{slb_torus_grid}
\myinclude\verb/sparseGraph.h/
\begin{mymethods}
\begin{verbatim}
class torusGrid : public graph
{
    enum TOptTorus {
        TORUS_DEFAULT,TORUS_HEMISPHERE,
        TORUS_TRIANGULAR,TORUS_SQUARE,TORUS_HEXAGONAL
    };

    torusGrid(TNode,TNode,TOptTorus,TOptTorus,
                goblinController&);
}
\end{verbatim}
\end{mymethods}
A \nt{torus grid} is a graph whose nodes are placed on the surface of a torus.
Basically, \verb/torusGrid(k,l,faceType)/ consists of a regular grid, either
with triangular, hexagonal or four-sided faces, depending on the \verb/faceType/
parameter. The first and the last column, and also the first and the last row
are identified.

\bigskip
\begin{figurehere}
\begin{center}
\epsfxsize=8cm
\epsfbox{torusGrid.eps}
\vspace{0.5cm}
\caption{\label{flb_torus_grid}A Triangular Grid on a Torus}
\end{center}
\end{figurehere}


\subsection{Triangular Graphs}
\myinclude\verb/sparseGraph.h/
\begin{mymethods}
\begin{verbatim}
class triangularGraph : public graph
{
    triangularGraph(TNode,goblinController&);
}
\end{verbatim}
\end{mymethods}
The nodes of a \nt{triangular graph} are the 2-element subsets of a finite
ground set. Two nodes are adjacent if they have an element in common.
Triangular graphs are interesting for their node and edge degree regularity.
Figure \ref{flb_triangular} shows \verb/triangularGraph(4)/ which is the
largest planar instance.

\bigskip
\begin{figurehere}
\begin{center}
\epsfxsize=7cm
\epsfbox{triangular.eps}
\vspace{0.5cm}
\caption{\label{flb_triangular}A Triangular Graph}
\end{center}
\end{figurehere}


\subsection{Sierpinski Triangles}
\myinclude\verb/sparseGraph.h/
\begin{mymethods}
\begin{verbatim}
class sierpinskiTriangle : public graph
{
public:

    sierpinskiTriangle(TNode,goblinController&);
}
\end{verbatim}
\end{mymethods}
By \nt{Sierpinski triangles}, one denotes a infinite series of plane graphs.
Each graph is obtained by starting with a regular triangle which is subdivided
into four congruent triangles. Three of these four triangles are subdivided
recursively. Figure \ref{flb_triangular} shows \verb/triangularGraph(5)/ where
the parameter \verb/5/ specifies the recursion depth. 

\bigskip
\begin{figurehere}
\begin{center}
\epsfxsize=7cm
\epsfbox{sierpinski.eps}
\vspace{0.5cm}
\caption{\label{flb_sierpinski}A Sierpinski Triangle}
\end{center}
\end{figurehere}



\subsection{Regular trees}
\myinclude\verb/sparseDigraph.h/
\begin{mymethods}
\begin{verbatim}
class regularTree : public diGraph
{
public:

    regularTree(TNode,TNode,TNode,goblinController&);

};
\end{verbatim}
\end{mymethods}
A \nt{regular tree} is a tree such that every node is either a leave node
or has a fixed, specified number of descendants. In that sense,
\verb/regularTree(5,3)/ generates a ternary tree (every non-leave node has
three descendants) with depth (root-leave distance) 5. It is further
possible to specify an upper bound on the number of tree nodes. For example,
\verb/regularTree(5,2,25)/ generates a tree with 25 nodes, depth 5, where
every node has at most 2 descendants.



\cleardoublepage
\markboth{ATTRIBUTES AND POOLS}{ATTRIBUTES AND POOLS}
\chapter{Attributes and Attribute Pools}
\thispagestyle{fancy}
\label{clb_attributes}
All information which is associated with graph nodes and arcs might be imagined
to be stored like vectors. But this only partially true since some graph objects
are logical views. In represented graph objects, node and arc attributes
are indeed composed from an STL vector (the \nt{representational vector},
but supplemented with additional functionality for handling value ranges and
constant attribute values.

Attributes are grouped into \nt{pools}, and this grouping is reflected by the file
structure. It is possible to access attributes, the hidden STL vector and even
the C arrays by knowing the responsible attribute pool and the \nt{token} which
identifies the attribute within its pool.

Basically, attributes are hidden behind interface methods which apply to
represented graphs as well as logical objects. So it not requisite to know about
the implementational details. On the other hand, direct access to attributes,
STL vectors or even C arrays may speed up application code and improve the
interoperability with other C++ libraries.


\markright{DEFINING POOLS}
\section{Defining Attribute Pools}
\myinclude\verb/attributePool.h/
\begin{mymethods}
\begin{verbatim}
typedef unsigned short TPoolEnum;

enum TBaseType {
    TYPE_NODE_INDEX,
    TYPE_ARC_INDEX,
    ...
    TYPE_SPECIAL
}

enum TArrayDim {
    DIM_GRAPH_NODES,
    DIM_GRAPH_ARCS,
    ...
    DIM_SINGLETON
}

struct TPoolTable {
    char*           tokenLabel;
    TBaseType       arrayType;
    TArrayDim       arrayDim;
    TPoolEnum       primaryIndex;
}

class attributePool
{
    enum TAttributeType {ATTR_FULL_RANK,ATTR_ALLOW_NULL};

    attributePool(TPoolTable*,TPoolEnum,TAttributeType);
}
\end{verbatim}
\end{mymethods}
As mentioned, an \verb/attributePool/ is a container for attributes. It manages
the access to and the manipulation of attributes, and file I/O for attributes and
nested pools.

Attributes and pools do not store data about the object which is composed from.
All a pool can see is a table with some information about the managed
attributes. The pool constructor is supplied with a pointer to this table, the
number of records in this table, and the desired strategy for handling attribute
constants.

The pool table specifies for all admissible tokens, a \verb/tokenLabel/ which is
used in external representations (basically files), the \verb/arrayType/ of
attribute values and \verb/arrayDim/ which specifies with which object dimension
the attribute has to be synchronzed. The \verb/primaryIndex/ allows to define
aliases for attribute labels which apply when the pool is loaded from file.

Pool tables are constants shared by all graph objects, and so do not
introduce significant memory usage. All that an attribute pool must know about
graph objects is passed when methods are called. Plain attributes
do not know about the referencing data objects at all.

The strategy for handling constant attributes can be one of the following:
\begin{itemize}
\item \verb/ATTR_FULL_RANK/ : Attributes either have full rank or are disallocated
    at all. The data object referencing the pool object does not store default
    values at any other place, but the defaults are hard coded.
\item \verb/ATTR_ALLOW_NULL/ : Attributes either have full rank or are shrunk to
    a zero length vector and then only store a default value. Other than for the
    previous strategy, default values can be set dynamically and are object specific.
\end{itemize}
So, considering a fixed graph attribute, either a value is stored for every graph
entity (node or edge), or a default value is stored for all all entities in common,
or nothing is stored at all.


\markright{ACCESSING ATTRIBUTES}
\section{Accessing Attributes}
\myinclude\verb/attributePool.h/
\begin{mymethods}
\begin{verbatim}
template<typename T>
class attribute
{
    vector<T>*  GetVector();
    T*          GetArray();
}

class attributePool
{
    template <typename T> attribute<T>*
                    GetAttribute(TPoolEnum);
    template <typename T> vector<T>*
                    GetVector(TPoolEnum);
    template <typename T> T*
                    GetArray(TPoolEnum);
}
\end{verbatim}
\end{mymethods}
Provided that an attribute has been allocated in advance, the referencing pool
object looks up on \verb/GetAttribute()/ the attribute object by means
of its token and returns a pointer to the attribute. If the desired attribute
does not exist, a \verb/NULL/ pointer is returned.

This attribute lookup is done by linear search in an STL list. Pool objects list
only the allocated attributes and the respective tokens. Aliases in the pool
tables produce few overhead since the rspective tokens do not occur in the searched
lists. Practically, pools should be restricted to 10-20 effective elements.

It is further possible to access the representational STL vector or even the C
array. Pointers can be requested from the attribute itself, and also from the
referencing pool object. Keep in mind that these pointers may be invalidated when the
referencing data object is manipulated!


\markright{GENERATING ATTRIBUTES}
\section{Generation and Initialization of Attributes}
\myinclude\verb/attributePool.h/
\begin{mymethods}
\begin{verbatim}
class attributePool
{
    template <typename T> attribute<T>*
        InitAttribute(goblinRootObject&,TPoolEnum,T);
    template <typename T> vector<T>*
        InitVector(goblinRootObject&,TPoolEnum,T);
    template <typename T> T*
        InitArray(goblinRootObject&,TPoolEnum,T);

    template <typename T> attribute<T>*
        RawAttribute(goblinRootObject&,TPoolEnum);
    template <typename T> vector<T>*
        RawVector(goblinRootObject&,TPoolEnum);
    template <typename T> T*
        RawArray(goblinRootObject&,TPoolEnum);
}

enum TSizeInfo {SIZE_ACTUAL,SIZE_RESERVED};

class goblinRootObject
{
    virtual size_t SizeInfo(TArrayDim,TSizeInfo);
}
\end{verbatim}
\end{mymethods}
All methods listed above produce full rank attributes. That is, the
representational vector size and its capacity conform with the dimensions set
in the referencing object. As a concrete example, when applied in a graph object
scope, \verb/Registers().InitAttribute<TArc>(*this,TokRegEdgeColour,NoArc)/
does the following:
\begin{itemize}
\item It applies to the predefined attribute pool \verb/Registers()/. This
    is the only pool which is available for both represented and logical
    graph objects.
\item It looks up \verb/TokRegEdgeColour/ in the associated pool table
    \verb/listOfRegisters[]/. This turns out that the attribute values
    are indeed of the instanciated type \verb/TArc/, and the dimensional
    specifier \verb/DIM_GRAPH_ARCS/.
\item It calls \verb/SizeInfo(DIM_GRAPH_ARCS)/ twice to determine the
    required attribute size which is \verb/M()/, the number of graph edges,
    and an attribute capacity. (If the graph is represented, a special capacity
    might have been set in advance. For other graph objects, the size and the
    capacity are the same)
\item It looks up \verb/TokRegEdgeColour/ in the list of allocated attributes.
    If the attribute does not exist yet, it is allocated and put in front of
    the list. Especially in the \verb/Registers()/ pool, all attributes have
    full rank. In other cases, \verb/InitAttribute()/ expands zero size vectors.
\item It assigns the value \verb/NoArc/ to every attribute element.
\item It returns a pointer to this attribute.
\end{itemize}
The methods \verb/InitAttribute()/ and \verb/RawAttribute()/ only differ by
the value initialization which is omitted by using the latter method. The other
listed methods work the same, but denote shortcuts to access the representational
vector or the C array.


\markright{SYNCHRONIZING ATTRIBUTES}
\section{Synchronizing Attributes with Object Manipulations}
\myinclude\verb/attributePool.h/
\begin{mymethods}
\begin{verbatim}
template<typename T>
class attribute
{
    void IncreaseSize(TIndex);
    void SetCapacity(TIndex);
    void ReserveItems(TIndex);
    void AppendItems(TIndex);
    void EraseItems(TIndex);
    void SwapItems(TIndex,TIndex);
}

class attributePool
{
    void ReserveItems(TArrayDim,TIndex);
    void AppendItems(TArrayDim,TIndex);
    void EraseItems(TArrayDim,TIndex);
    void SwapItems(TArrayDim,TIndex,TIndex);
}
\end{verbatim}
\end{mymethods}
One important fact about attributes is that they grow and shrink with the
referencing object. This concerns the following operations on represented
graph objects:
\begin{itemize}
\item Node insertions and deletions,
\item arc insertions and deletions (which can only occur for sparse graphs),
\item \verb/SetCapacity()/ calls to modify the attribute capacities,
\item and, for the \verb/LayoutData()/ pool, insertion and deletion of layout
    nodes. Nearly all high-level layout methods call \verb/ReleaseBendNodes()/!
\end{itemize}
Most of these synchronisation operations take place in the manipulation methods
of the class \verb/sparseRepresentation/.

Maybe, you just want to apply manipulation methods for graphs while having
direct access to represetational arrays. Then, you only need some guideline
for avoiding pointer invalidation:
\begin{itemize}
\item Instead of deleting nodes and arcs one by one, apply the analogous cancel
    operation (e.g. \verb/CancelArc(a)/ in replace of \verb/DeleteArc(a)/) and
    perform a delayed deletion of all entities in one pass (in the example
    \verb/DeleteArcs()/).
\item Before inserting nodes or arcs, assign the final capacities by using
    \verb/SetCapacity()/.
\end{itemize}


\markright{RETRIEVING ELEMENTS}
\section{Retrieving Attribute Elements}
\myinclude\verb/attributePool.h/
\begin{mymethods}
\begin{verbatim}
template<typename T>
class attribute
{
    T       GetValue(TIndex);
    TIndex  MinIndex();
    TIndex  MaxIndex();
    T       MinValue();
    T       MaxValue();
    T       DefaultValue();
    bool    IsConstant();
    void    ReleaseBounds();
    void    ComputeBounds();
}

class attributePool
{
    template <typename T> T GetValue(TPoolEnum,TIndex,T);
    template <typename T> T DefaultValue(TPoolEnum,T);
    template <typename T> T MinValue(TPoolEnum,T);
    template <typename T> T MaxValue(TPoolEnum,T);
    template <typename T> TIndex MinIndex(TPoolEnum);
    template <typename T> TIndex MaxIndex(TPoolEnum);
    template <typename T> bool IsConstant(TPoolEnum);
}
\end{verbatim}
\end{mymethods}
The call \verb/GetValue(i)/ looks up the indexed element in the representational
vector and returns this value. For any index \verb/i/ beyond the scope of the
vector, \verb/GetValue(i)/ and \verb/DefaultValue()/ coincide. The default value
also comes into play when the vector size is increased.

It is possible to query the \verb/MinValue()/ which is the minimal value in the
representational vector. The default value does not contribute here. The value
is evaluated once and then is maintained as long as this is possible without
computational overhead. Actually, the \verb/MinIndex()/ is saved, and this can
also be queried. Of course, \verb/MaxValue()/ and \verb/MinValue()/ behave analogously.

The query \verb/IsConstant()/ returns \verb/true/ if the size of the
representational vector is zero. Otherwise, \verb/MinValue()/ and \verb/MaxValue()/
are compared which may cause a scan of the complete vector. Note that this method
does not deallocate the representational vector in the positive case.

If you override the data encapsulation, and modify the vector or array elements
without using the attribute interface (presented in the next section), the saved
extremal values are invalidated. In that case, \verb/ReleaseBounds()/ must be
called to notify the attribute object about this invalidation.

The behavior of the listed pool methods is as expected: Lookup of the specified
attribute and then application of the respective attribute method. But note the
overhead for attribute lookup when methods are applied several times to the same
attribute.


\markright{ASSIGNING VALUES}
\section{Assigning Attribute Values}
\myinclude\verb/attributePool.h/
\begin{mymethods}
\begin{verbatim}
template<typename T>
class attribute
{
    void    SetValue(TIndex,T);
    void    SetDefaultValue(T);
    void    SetConstant(T);
    void    Assign(T);
}
\end{verbatim}
\end{mymethods}
The following attribute methods are available for the value manipulation:
\begin{itemize}
\item \verb/SetValue()/ changes the attribute value for a given index. If this
    index exeeds the current vector size, the size or even capacity is increased
    first. In that case, the current default value is aasigned to all new vector
    elements.
\item \verb/Assign()/ assigns the given value to all represented vector elements,
    and a new default value. The representational vector size does not change.
\item \verb/SetConstant()/ assigns a new default value and reduces the
    representational vector size to zero.
\item \verb/SetDefaultValue()/ assigns a new default value, but leaves the
    representional vector unchanged.
\end{itemize}
This list is completed by the pool method \verb/InitAttribute()/ which makes an
attribute full rank and then assigns a given value to all representional vector
elements.

Modifying attribute values might but not necessarily does invalidate the saved
minima and maxima. So, if possible, separate queries of extremal values and value
modification processes.


\markright{PREDEFINED POOLS}
\section{Predefined Pools}
\myinclude\verb/abstractMixedGraph.h/
\begin{mymethods}
\begin{verbatim}
class abstractMixedGraph
{
    virtual attributePool*  RepresentationalData();
    virtual attributePool*  Geometry();
    virtual attributePool*  LayoutData();
    attributePool*          Registers();
}
\end{verbatim}
\end{mymethods}
Graph object have at least one member attribute pool which can be accessed by
calling \verb/Registers()/. This pool collects data structures to save
computational results of the high-level algorithms and is described in Chapter
\ref{slb_registers}.

Represented graph objects own some more pools, and these can be accessed by the
methods listed above. For any other graph object, a \verb/NULL/ pointer is
returned.



\cleardoublepage
\markboth{ITERATORS}{ITERATOR OBJECTS}
\chapter{Iterators}
\thispagestyle{fancy}
\label{clb_it}

An iterator is an object which allows to access listed information which is
encapsulated into another data object. In the context of graphs, an iterator
supplies with a stream of incident arcs for each of the nodes.


\markright{INCIDENCE LISTS}
\section{Incidence Lists}
\label{slb_inci}
\myinclude\verb/abstractMixedGraph.h/
\begin{mymethods}
\begin{verbatim}
class abstractMixedGraph
{
    TArc                First(TNode);
    TArc                Right(TNode,TArc);
};
\end{verbatim}
\end{mymethods}
Node incidence lists are implicitly defined by the methods \verb/First()/ and
\verb/Right()/ which are available in arbitrary graphs, but implemented
differently. In any implementation, the method call \verb/First(v)/ should
return an arbitrary arc with start node \verb/v/, and the call \verb/Right(u,a)/
should return an arc which has the same start node as \verb/a/, namely the node
\verb/u/. The repetition of the start node is needed to improve the efficiency
of the iterator oprations.

Moreover, node incidence lists must be circular, and contain all arcs which
have the same start node. That is, for every pair \verb/a1/, \verb/a2/
of arcs with common start node \verb/a1/ must be derefencable from \verb/a2/
by the method \verb/Right()/.

The method name \verb/Right()/ may suggest that one traverses the node incidences
clockwise. In fact, this makes sense for sparse graphs embedded in plane.
The most algorithms which run on planar graphs require that \verb/Right()/
defines a planar representation.

Accordingly, the method \verb/Left()/ which is available for sparse graph objects,
supplies with reverse incidence lists. In the planar case, \verb/Left()/
defines a planar representation and traverses the node incidences anti-clockwise.



\markright{INVESTIGATOR OBJECTS}
\section{Investigator Objects}
\myinclude\verb/investigator.h/
\begin{mymethods}
\begin{verbatim}
class investigator : public virtual managedObject
{
    investigator(abstractMixedGraph &);

    void        Reset() = 0;
    void        Reset(TNode) = 0;
    TArc        Read(TNode) = 0;
    TArc        Peek(TNode) = 0;
    void        Skip(TNode) = 0;
    bool        Active(TNode) = 0;
}
\end{verbatim}
\end{mymethods}
Node incidences may either be accessed directly using the methods \verb/First()/
and \verb/Right()/, or by an iterator object which has some advantages:
\begin{myitemize}
\item The code looks more tidy, more like a high-level description.
\item There is a mechanism for caching iterator objects. By that, the frequency
    of memory allocation and deallocation operations is reduced.
\item Development is speeded up since memory faults can be avoided.
\end{myitemize}
The possible iterator methods can be described within a few words: 
The method \verb/Reset()/ is used to reinitialize incidence streams,
either of a single node or the whole node set.

The method \verb/Active()/ checks if there are unread incidences of a given
node. In that case, the methods \verb/Read()/ and \verb/Peek()/ return such an
unread incidence. Otherwise, \verb/Read()/ and \verb/Peek()/ throw an exception
\verb/ERRejected/.

The difference between \verb/Read/ and \verb/Peek/ is that the latter method
does not mark any incidences unread. To do this explicitly, that is, to proceed
in the incidence list, one calls \verb/Skip()/. A statement
\verb/a = I.Read(v)/ does the same as the sequence \verb/a = I.Peek(v)/;
\verb/I.Skip(v)/.
\sample
\begin{quote}
\begin{verbatim}
...
investigator *I = new goblinIterator(G);
TFloat L = -InfFloat;
for (v=0;v<G.N();v++)
   while (G.Dist(v)<InfFloat && I->Active(v))
   {
      a = I->Read(v);
      TNode w = G.EndNode(a);
      if (G.Dist(w)<InfFloat && G.Length(a)>L)
         L=G.Length(a);
   };
delete I;
...
\end{verbatim}
\end{quote}
determines the maximum length of an arc spanned by the nodes with
finite distance labels in the graph \verb/G/. Note that this code is
optimal only if the node set is rather small.


\markright{IMPLICIT ACCESS}
\section{Implicit Access}
\myinclude\verb/abstractMixedGraph.h/
\begin{mymethods}
\begin{verbatim}
class abstractMixedGraph
{
    THandle             Investigate();
    investigator &      Investigator(THandle);
    void                Reset(THandle,TNode=NoNode);
    TArc                Read(THandle,TNode);
    bool                Active(THandle,TNode);
    void                Close(THandle);
    void                ReleaseInvestigator();
};
\end{verbatim}
\end{mymethods}
Node incidences are accessed by iterators. This may be done explicitly as
described in the previous section. There is, however, an equivalent
formulation where all iterator functionality is encapsulated into the
referenced graph object:
\sample
\begin{quote}
\begin{verbatim}
...
TFloat L = -InfFloat;
THandle H = G.Investigate();
for (v=0;v<N();v++)
   while (G.Dist(v)<InfFloat && G.Active(H,v))
   {
      a = G.Read(H,v);
      TNode w = G.EndNode(a);
      if (G.Dist(w)<InfFloat && G.Length(a)>L)
         L=G.Length(a);
   };
Close(H);
...
\end{verbatim}
\end{quote}
The latter approach requires additional effort for dereferencing the
iterator. The benefit is caching of the 'used' iterator which effectively
decreases the effort of memory allocation and defragmentation.

The method \verb/Investigate()/ returns a handle to an iterator object. If
there is a cached iterator, the cached object is initialized, and the handle
is returned. Otherwise a new iterator is allocated and assigned to a handle.

The method \verb/Close(THandle)/ finishes a graph search. If the cache space
is exhausted, the iterator is disallocated. Otherwise the iterator object is
cached, and can be reused later.
If the \verb/Close/ statement is omitted, GOBLIN will return an error when
the referneced graph object is deleted.

The method \verb/RelaseInvestigators()/ deletes all cached iterator objects.
This method is called by destructor methods automatically.
The \verb/Reset()/, \verb/Read()/ and \verb/Active()/ operations work just
as if the investigator would be accessed directly.

The most efficient way to work with iterators is to combine the caching
functionality with explicit access as described in the previous section.
This is accomplished by the method \verb/Investigator(THandle)/ which returns the
address of the iterator object associated with some handle.


\markright{IMPLEMENTATIONS}
\section{Implementations}
\myincludes\verb/abstractMixedGraph.h, auxiliaryNetwork.h, surfaceGraph.h/
\begin{mymethods}
\begin{verbatim}
class abstractMixedGraph
{
    virtual goblinIterator * NewIterator();
};
\end{verbatim}
\end{mymethods}
Just as graph objects, GOBLIN iterators are polymorphic. There is, however,
the class \verb/iGraph/ which supplies with iterators for most graph
objects. Such an iterator is returned by the method
\verb/abstractMixedGraph::NewIterator()/ and utilizes the methods \verb/First/
and \verb/Right/ which have been discussed before.

Under some circumstances, the methods \verb/First/ and \verb/Right/ do not
provide an efficient implementation. For this reason, surface graphs and
layered auxiliary networks implement own iterators which keep some temporary
information.

Accordingly, the method \verb/NewIterator/ is overloaded in order to supply
\verb/Investigate/ with a proprietary iterator object.



\cleardoublepage
\markboth{EXPLICIT DATA STRUCTURES}{EXPLICIT DATA STRUCTURES}
\chapter{Explicit Data Structures}
\thispagestyle{fancy}
\label{clb4}

This chapter describes the GOBLIN classes which are \nt{data structures} in
the usual sense and for some of which equivalent data structures can be found
in the C++ standard template library (STL). The template data structures which
are discussed here support the GOBLIN memory management and tracing
functionality.

In general, the template parameter \verb/<TItem>/ has to be integral and the
GOBLIN library file contains template instances for the types \verb/TNode/ and
\verb/TArc/. To generate additional template instances, one may include the
corresponding \verb/.cpp/ file directly.

\bigskip
\begin{figurehere}
\begin{center}
\epsfxsize=12cm
\epsfbox{fibheap.eps}
\vspace{0.5cm}
\caption{\label{flb_fibheap}Fibonacci Heaps}
\end{center}
\end{figurehere}


\markright{CONTAINER OBJECTS}
\section{Container Objects}
\myinclude\verb/goblinQueue.h/
\begin{mymethods}
\begin{verbatim}
template <class TItem,class TPriority>
class goblinContainer : public virtual managedObject
{
    virtual void    Init() = 0;

    virtual void    Insert(TItem,TKey) = 0;
    virtual void    ChangeKey(TItem,TKey) = 0;
    virtual TItem   Delete() = 0;
    virtual TItem   Peek() = 0;
    virtual bool    Empty();
    virtual TItem   Cardinality() = 0;
}
\end{verbatim}
\end{mymethods}
Container objects are either set or multiset objects. One can also classify
containers into queues, stacks and priority queues by the order in which
elements can be deleted.

The members of a container are \verb/TItem/ objects which are
inserted and deleted by the listed prototype methods.
The second template parameter \verb/TKey/ is the optional priority
of the members of a priority queue. It is declared in a more general context
to preserve compatibility among the various container classes. The same holds
for the operation \verb/ChangeKey/.
\begin{mysample}
\begin{verbatim}
...
binaryHeap<TArc,TFloat> Q(M());
for (a=0;a<M();a++) Q.Insert(a,Length(2*a));
while (!Q.Empty())
{
    a = Q.Delete();
    ...
}
\end{verbatim}
\end{mysample}
effectively sorts the arcs of a graph object by their length labels. This is
simply done by putting the arcs on a priority queue from where they are taken
for further processing.

All GOBLIN container classes are defined by \nt{templates}. That is, the member
type \verb/TItem/ is abstract. This type is not resolved at run time, but by
the C++ compiler.

In our example, the template instance \verb/binaryHeap<TArc,TFloat>/ can be
already found by the linker in the library \verb/goblin.a/. If no pre-compiled
code would be available, one would include \verb/binheap.cpp/ rather than
\verb/binheap.h/ to force the compiler to generate such code.

A container may be {\bf dynamic}\index{container!dynamic} where every member is
represented by an individual struct object. Otherwise the container is
{\bf static}\index{container!static}, and all members are
represented by arrays which are maintained during the entire lifetime of the
container object. The latter concept has some serious drawbacks:
\begin{myitemize}
\item The member type \verb/TItem/ must be integral. That is, the members are
    indices rather than objects.
\item No repetitions are allowed. That is, static containers are set objects
    rather than multisets.
\item A maximum index must be passed to the constructor which determines the
    size of all arrays encapsulated into the set object.
\end{myitemize}
Note that a static data structure is adequate in the example from above.
Even if inefficient, static sets may be useful during the testing
phase of an algorithm to detect unwanted repetitions, and can be replaced
by a dynamic structure in the final version.

For static containers, one can check efficently if an item is missing
(\verb/IsMember()/). Furthermore, static containers may share memory with
other containers. However, it must be clear that all these sets are disjoint:
\begin{mysample}
\begin{verbatim}
...
staticQueue<TNode,TFloat> **Q
    = new staticQueue<TNode,TFloat>*[n];
Q[0] = new staticQueue<TNode,TFloat>(n);
for (v=1;v<n;v++)
   Q[v] = new staticQueue<TNode,TFloat>(Q[0]);
for (v=1;v<n;v++)
   Q[d[v]] -> Insert(v);
...
\end{verbatim}
\end{mysample}
These lines of code form part of the Micali/Vazirani algorithm which distributes
the node set of a balanced flow network over all queues
\verb/Q[0],Q[1],...,Q[n-1]/ where \verb/Q[i]/ consists of the node with
distance label \verb/i/. In this special situation, the static implementation
is indeed the most efficient data structure.

Every container object can be 'emptied' by the method \verb/Init()/.  This is
particularly useful for static implementations. One could also think of some
caching mechanism of dynamic queue member objects, but this is not implemented
yet.


\subsection{Queues}
\myincludes\verb/staticQueue.h, staticQueue.cpp, dynamicQueue.h, dynamicQueue.cpp/

\bigskip\noindent
Queues are container objects which follow the \nt{first-in first-out principle} principle.
There are two implementations: The class \verb/staticQueue/ which models sets,
and the class \verb/dynamicQueue/ which models multisets.

For both classes, the GOBLIN library contains precompiled code for the template
instances \verb/<TNode,TFloat>/ and \verb/<TArc,TFloat>/. Note that the choice
of \verb/TKey/ is immaterial to some extent.
Except for the construction of a static queue and the destruction of a dynamic
queue, all operations are elementary, that is, they take $O(1)$ time.


\subsection{Stacks}
\myincludes\verb/staticStack.h, staticStack.cpp, dynamicStack.h, dynamicStack.cpp/

\bigskip\noindent
Stacks are container objects which follow the \nt{last-in first-out principle}.
There are two implementations: The class \verb/staticStack/ which models sets,
and the class \verb/dynamicStack/ which models multisets.

For both classes, the GOBLIN library contains precompiled code for the template
instances \verb/<TNode,TFloat>/ and \verb/<TArc,TFloat>/. Again, the choice of
\verb/TKey/ is immaterial. Except for the construction of a static stack,
and the destruction of a dynamic stack, all operations are elementary.


\subsection{Priority Queues}
\myincludes
\begin{verbatim}
    basicHeap.h, basicHeap.cpp, binaryHeap.h,
    binaryHeap.cpp, fibonacciHeap.h, fibonacciHeap.cpp
\end{verbatim}
\begin{mymethods}
\begin{verbatim}
template <class TItem,class TKey>
class goblinQueue : public virtual managedObject
{
    void            Insert(TItem,TKey);
    TKey            Key(TItem);
    void            ChangeKey(TItem,TKey);
};
\end{verbatim}
\end{mymethods}
Priority queues are container objects to which \verb/TItem/ objects are added
together with a specific priority. The item to be deleted is the set member
with the highest \nt{priority}. This value is usually called the {\bf key} of
an item, a notation which is somewhat misleading since two members may have the same
priority.

GOBLIN priority queues are all static and differ only by their run time
behaviour. From a theoretical point of view (only), a \verb/fibonacciHeap/ performs
better than a \verb/binaryHeap/ which in turn performs better than a
\verb/basicHeap/ object in general. Binary and Fibonacci heaps can be traced
graphically, see Section \ref{slb_tracing} for some details.


\markright{DISJOINT SET SYSTEMS}
\section{Disjoint Set Systems}
\label{slb42}
\myinclude\verb/abstractFamily.h/
\begin{mymethods}
\begin{verbatim}
template <class TItem>
class goblinDisjointSetSystem : public managedObject
{
    virtual void            Bud(TItem) = 0;
    virtual void            Merge(TItem,TItem) = 0;
    virtual TItem           Find(TItem) = 0;
    virtual bool            Reversible() = 0;
};
\end{verbatim}
\end{mymethods}
Disjoint set systems are objects which have been designed to perform a
so-called \nt{union-find process} on the node set of a graph object.
This process is fully described by the listed operations.

The call \verb/Bud(v)/ creates a single node set containing \verb/v/, while
\verb/Merge(u,v)/ effectively merges the sets containing \verb/u/ and \verb/v/
into a single set. Each of these operations is
{\bf elementary}\index{elementary operation}, that is, it
requires a constant amount of time.

The call \verb/Find(v)/ returns the set containing the node \verb/v/ in terms of a
\nt{canonical element}. That is, sets are identified with one of their elements.
To check whether \verb/u/ and \verb/v/ are in the same set, one would evaluate
the expression \verb/Find(u)==Find(v)/.
\begin{mysample}
\begin{verbatim}
...
disjointFamily<TNode> F(n);
for (v=0;v<n;v++) F.Bud(v);
for (a=0;a<m;a++) F.Merge(StartNode(a),EndNode(a));
return F.Find(x)==F.Find(y);
...
\end{verbatim}
\end{mysample}
determines the connected components of a graph, and checks whether \verb/x/ and
\verb/y/ are in the same component. The running times of a \verb/Find(v)/
operation are implementation dependent.

Disjoint set families can be traced graphically, see Section
\ref{slb_tracing} for some more details. The method \verb/Reversible()/ helps
to distinguish the two available implementations at run time. The notation
refers to the fact that shrinking families allow to expand sets in the reverse
order.


\subsection{Static Disjoint Set Systems}
\label{slb_dsu}
\myincludes\verb/disjointFamily.h, disjointFamily.cpp/

\bigskip\noindent
A \verb/Find(v)/ operation runs in $O(1)$ amortized time. That is, the running
time can be considered constant if the the total number of \verb/Find/s is
large enough. If the number $m$ of \verb/Find/s is small, a worst-case bound is
$O(\alpha(m,n))$ where $\alpha$ denotes some inverse of the Ackermann
function. In practice, \verb/Find(v)/ operations can be considered to be
elementary operation.

This data structure is particularly useful for non-weighted matching algorithms.


\subsection{Shrinking Families}
\label{slb_shrfam}
\myincludes\verb/nestedFamily.h, nestedFamily.cpp/
\begin{mymethods}
\begin{verbatim}
template <class TItem>
class nestedFamily: public goblinDisjointSetSystem<TItem>
{
    nestedFamily(TItem,TItem,goblinController& = goblinDefaultContext);

    void            Bud(TItem);
    TItem           MakeSet();
    void            Merge(TItem,TItem);
    void            FixSet(TItem);

    bool            Top(TItem);
    TItem           Set(TItem);

    TItem           First(TItem);
    TItem           Next(TItem);

    void            Split(TItem);

    void            Block(TItem v);
    void            UnBlock(TItem v);
}
\end{verbatim}
\end{mymethods}
This data structure is required for weighted matching solvers and the minimum
spanning arborescence method. Beside the inherited functionality, it allows to
split a set $S$ into the subsets which previously were merged into $S$.
Actually there is a lot of new functionality associated with the class
\verb/nestedFamily/:

We first mention that a constructor call \verb/nestedFamily(k,l,...)/
specifies two dimensions $k$ and $l$. The constructed shrinking family has
$k+l$ elements where the indices $0,1,\dots,k-1$ represent {\bf real items}
\index{shrinking family!real items} whereas the indices $k,k+1,\dots,k+l-1$
represent sets, called {\bf virtual items}\index{shrinking family!virtual items}.

A \verb/Find(v)/ operation runs in $O(\log n)$ time in the worst case. The
operations \verb/Block(w)/ and \verb/UnBlock(w)/ split and then shrink a virtual
item again. They are needed for the construction of augmenting paths in the
primal-dual method for weighted matching problems. The calls to \verb/Block(w)/
and \verb/UnBlock(w)/ take $O(n\log{n})$ time alltogether for one augmenting path
computation.



\markright{HASH TABLES}
\section{Hash Tables}
\myinclude\verb/hashTable.h/
\begin{mymethods}
\begin{verbatim}
template <class TItem,class TKey>
class goblinHashTable : public managedObject
{
    goblinHashTable(TItem,TItem,TKey,goblinController &);

    TKey            Key(TItem);
    void            ChangeKey(TItem,TKey);
}
\end{verbatim}
\end{mymethods}
A \nt{hash table} is a data structure which allows to store a sparse vector or
matrix, say of length $r$ in an array whose dimension is proportional to the
maximal number $l$ of non-zero entries. Actually, the size of the hash table
is not $l$ but some number $s>l$.

The definition of a hash table includes the choice of $k$, a \nt{hash function}
which maps the index set $\{0,1,\dots,r-1\}$ onto the $\{0,1,\dots,s-1\}$ so
that the preimages of any two indices have approximately equal size, and a
strategy for resolving {\bf collisions}\index{hash table!collisions} between
two indices which need to be stored but which have the same image.

In the class \verb/goblinHashTable/, collisions are resolved by searching
through implicit set objects which model the images, the hash value is the
remainder modulo $s$ and $s=2l$. The constructor call
\verb/goblinHashTable(r,l,k0,...)/ specifies the dimensions $r$, $l$ and
a default value $k_0$ for the vector entries.

There are only two operations to be described here: A statement \verb/Key(i)/
returns the current vector entry at index $i$, and statement
\verb/ChangeKey(i,k)/ would change this vector entry to $k$.
In practice, only a few collisions occur so that one can treat these
operations as if they were elementary. But note that \verb/Key/ and
\verb/ChangeKey/ operations take $O(s)$ steps in the worst case.

A drawback of hash tables is that the number $l$ must be known a priori or
reallocations occur. Two main applications of hash tables in GOBLIN are
adjacency matrices of sparse graphs and sparse subgraphs (matchings, paths,
trees) of geometrical graphs. Here, the maximum size can be easily determined.
Additionally, sparse matrices are implemented by hash tables.

The template parameter \verb/TItem/ must be an unsigned integer type but there
are no restrictions about the data type \verb/TKey/.


\markright{DICTIONARIES}
\section{Dictionaries}
\myinclude\verb/dictionary.h/
\begin{mymethods}
\begin{verbatim}
template <class TKey>
class goblinDictionary : public managedObject
{
    goblinDictionary(TIndex,TKey,goblinController&);
    TKey    Key(char*,TIndex = NoIndex);
    void    ChangeKey(char*,TKey,TIndex = NoIndex,
                        TOwnership = OWNED_BY_RECEIVER);
}
\end{verbatim}
\end{mymethods}
A \nt{dictionary} is the pendant of an hash table which maps arbitrary C
strings to values of an unspecified type \verb/TKey/. This data structure is
obviously needed to compute object indices from a tuple of node, arc or
variable labels.

The constructor call \verb/goblinDictionary(l,k0,CT)/ sets the default value
$k_0$ and the maximum number of non-zero entries $l$. The retrieval operation
\verb/Key(pStr,i)/ takes a string and an optional object index to compute
a hash value. That is, dictionaries do not only apply to the inverse mapping
problem but also to support free style node and arc labels. For the first
application, no index is specified at all. In the second case, an index denotes
an arc or node and a missing index denotes a constant arc or node labelling.

Since references are used, \verb/ChangeKey(pStr,k,i,tp)/ operations specify if
the dictionary shall work with a copy of the look-up string or if the string
ownership moves to the dictionary.



\markright{MATRICES}
\section{Matrices}
\label{clb_matrix}
\myinclude\verb/matrix.h/
\begin{mymethods}
\begin{verbatim}
template <class TItem,class TCoeff>
class goblinMatrix : public virtual managedObject
{
    goblinMatrix(TItem,TItem) throw();

    TItem   K();
    TItem   L();

    void    Transpose();

    virtual void    SetCoeff(TItem,TItem,TCoeff) = 0;
    virtual TCoeff  Coeff(TItem,TItem) = 0;

    void    Add(goblinMatrix&);
    void    Sum(goblinMatrix&,goblinMatrix&);
    void    Product(goblinMatrix&,goblinMatrix&);

    void    GaussElim(goblinMatrix&,TFloat=0);
}
\end{verbatim}
\end{mymethods}
GOBLIN matrices are declared with two template parameters. The first parameter
\verb/TItem/ specifies the type of row and column indices, the second
\verb/TCoeff/ specifies the type of the matrix entries. The only precompiled
template instance uses \verb/TIndex/ indices and \verb/TFloat/ coefficients.

There is a base class \verb/goblinMatrix/ which declares the mathematical
functionality, and two implementational classes \verb/denseMatrix/ and
\verb/sparseMatrix/ which merely have to implement the methods \verb/Coeff()/
and \verb/SetCoeff()/. The sparse implementation is based on hash tables.

Each matrix has a row dimension \verb/K()/ and a column dimension \verb/L()/.
Matrices can be transposed implicitly by using \verb/Transpose()/ without
affecting the physical representation.

The very basic matrix algebra is implemented by the methods \verb/Add()/,
\verb/Sum()/ and \verb/Product()/. The adressed matrix object denotes the
place where the results are stored. Either two input matrices are passed as
parameters or the adressed matrix also acts as an input. The running time
complexities are $O(kl)$ and $O(klm)$ where $m$ denotes the number of
right-hand columns.

The method \verb/GaussElim()/ applies to squares matrices only and tries to
solve a linear equation system where the matrix parameter acts as the
right-hand side. The second parameter denotes the absolut value at which matrix
entries are treated as zero. If omitted, the context parameter \verb/epsilon/
is used. Of course, both matrices must have compliant dimensions.

Be aware that both input matrices are manipulated by the method. If the
initial left-hand matrix is regular, it is transformed to the identity.
If the right-hand matrix is a column vector, it is transformed to the unique
solution vector. By passing a right-hand identity, the left-hand matrix is
effectively inverted. If the initial left-hand matrix is singular, an exception
is thrown without reaching a triangular left-hand form.

Since the method indeed implements Gauss elimination, the complexity is
$O(k^2(k+l))$ where $k$ denotes the left-hand dimensions and $l$ is the number
of right-hand columns.

The matrix functionality may increase in future, but only to speed up certain
high-level operations. It is not planned to grow a linear algebra package.


\cleardoublepage
\markboth{INDEX SETS}{INDEX SETS}
% Initial writing: CFP, 2005-09-18
\chapter{Index Sets}
\thispagestyle{fancy}
\label{clb_index_set}

Index sets encode lists of integers which refer to node or arc indices in a
graph or to rows or columns in an LP object. Other than the container objects
which have been described in the previous chapter, an index set is basically
determined by its constructor call. It is not possible to manipulate the
content or order of indices.

The general purpose of index sets is to supply high-level algorithms with input
data. The concept is related to STL iterators, though, not as elaborate and,
currently, with only few applications. What is passed to algorithms, in the STL
language, are rather containers than iterators.

There are basic class templates to specify all, none or single indices of an
interval $[0,1,\dots,r-1]$. But there are also classes to collect all graph
entities with a specific property.


\markright{INTERFACE}
\section{Interface}
\myinclude\verb/indexSet.h/
\begin{mymethods}
\begin{verbatim}
template <class TItem>
class indexSet
{
    virtual bool    IsMember(const TItem) const = 0;

    virtual TItem   First() const;
    virtual TItem   Successor(const TItem) const;
}
\end{verbatim}
\end{mymethods}
All index sets provide the following operations:
\begin{itemize}
\item \verb/IsMember(i)/ checks if the index $i$ is in the set.
\item \verb/First()/ returns a contained index if one exists, and an arbitrary
    index out of range otherwise.
\item \verb/Successor(i)/ returns the successor of index $I$ in an arbitrary but
fixed ordering of all contained indices, and an arbitrary index out of range
for the final index in that list.
\end{itemize}
When inheriting from this base class, it is mandatory to implement
\verb/IsMember()/. It is recommended to reimplement \verb/First()/ and
\verb/Successor()/ whenever it is possible to enumerate the contained indices
more efficiently than enumerating all indices in range (as the default codes do).


\markright{TEMPLATES}
\section{Templates}
\myinclude\verb/indexSet.h/
\begin{mymethods}
\begin{verbatim}
singletonIndex(TItem,TItem,
    goblinController& = goblinDefaultContext);
fullIndex(TItem,goblinController& = goblinDefaultContext);
voidIndex(TItem,goblinController& = goblinDefaultContext);
\end{verbatim}
\end{mymethods}
These three class templates are almost self explanatory: \verb/TItem/
represents the template parameter, that is the type of indices. The
constructors require to specify an index range by a \verb/TItem/ valued bound.
For example,
\begin{verbatim}
    fullIndex<TArc>(G.M())
\end{verbatim}
denotes the entire arc set of graph \verb/G/. And
\begin{verbatim}
    singletonIndex<TNode>(G.Root(),G.N())
\end{verbatim}
denotes a set of nodes in the same graph, consisting of the predefined root
node.

All classes implement the methods \verb/First()/ and \verb/Successor()/ in the
obvious, efficient way.


\markright{GRAPH BASED IMPLEMENTATIONS}
\section{Graph Based Implementations}
\myinclude\verb/abstractMixedGraph.h/
\begin{mymethods}
\begin{verbatim}
demandNodes(abstractMixedGraph&);
colouredNodes(abstractMixedGraph&,TNode);
colouredArcs(abstractMixedGraph&,TArc);
\end{verbatim}
\end{mymethods}
\myinclude\verb/abstractDigraph.h/
\begin{mymethods}
\begin{verbatim}
supersaturatedNodes(abstractDiGraph&);
deficientNodes(abstractDiGraph&);
\end{verbatim}
\end{mymethods}
\myinclude\verb/abstractBigraph.h/
\begin{mymethods}
\begin{verbatim}
leftHandNodes(abstractBiGraph&);
rightHandNodes(abstractBiGraph&);
\end{verbatim}
\end{mymethods}
Again, the purpose of the listed classes is the obvious. But other than the
basic templates described in the previous section, enumeration of the 'good'
indices is not really efficient; the default implementations of the \verb/indexSet/
base class apply. No lists of 'good' indices are allocated!

If lists are read more than once, it is worth to generate a container object
with the same content and to use this as an index set.


\markright{CONTAINERS AS INDEX SETS}
\section{Containers as Index Sets}
\myinclude\verb/staticQueue.h/, \verb/staticStack.h/

\medskip
\noindent
Sometimes, it makes sense to use containers as index sets:
\begin{itemize}
\item There is no predefined index set with the desired property or this set
    must be post-processed.
\item As pointed out in the previous section, if an index set has few elements
    compared with the value range, it may be inefficient to enumerate its
    indices several times. Exporting the indices to a container prevents from
    searching deselected indices.
\item In particular, when the index range is divided in different sets,
    contiguous memory containers may operate on the same chunk of memory.
\end{itemize}
Using containers as index sets has the following limitations:
\begin{itemize}
\item Adding or deleting items from a container can
    {\bf invalidate}\index{index set!ivalidation} running enumeration
    processes.
\item Only the classes \verb/staticQueue/ and \verb/staticStack/ provide the
    index set functionality. Node based containers potentially repeat indices,
    and elements may be of a non-integral data type also.
\end{itemize}



\cleardoublepage
\markboth{BRANCH AND BOUND}{BRANCH AND BOUND}
\chapter{Branch and Bound}
\thispagestyle{fancy}
\label{clb_bb}
% Most recent revision: CFP, 2005-08-20

{\bf Branch and bound}\index{branch and bound} is a strategy for solving hard
integer optimization problems, not only for problems on graphs. The basic
concept is combinatorial and does not involve LP formulations.

The GOBLIN branch and bound module operates on vectors of a specified dimension.
To the vector components, we refer as the \nt{problem variables}. These
variables have values of a scalar type \verb/TObj/ and are indexed
by values of an integer type \verb/TIndex/. Initially, there are certain
upper and lower integer bounds on the problem variables, but the concrete
bounds, variable values and the objective function are unknown to the branch
and bound module.

In order to derive a solver for a specific integer programming problem,
basically the following must be supplied:
\begin{itemize}
\item A fast method which solves a {\bf relaxed problem}
    \index{problem relaxation} to optimality and returns the objective value.
    That is, an easier problem with fewer restrictions is solved instead of
    the original problem.
\item A method to decide if a given integral vector is feasible for the
    original problem. This is the only way for the branch and bound module to
    get access to the combinatorial structure of a specific optimization
    problem.
\item Code to tighten the bounds of problem variables. The generic solver
    changes only one variable bound at a time, but efficient implementations
    derive benefit from the combinatorial structure and implicitly restrict
    further variables.
\end{itemize}
To the relaxed problem instance, together with the original variable bounds,
we refer as the \nt{root node} (of the binary branch tree which is generate as
follows).

The branch and bound scheme adds this root node to a list of active
{\bf branch nodes}\index{branch and bound!branch node} or {\bf subproblems},
and then iteratively deletes one of the active nodes and splits it into two
new subproblems by putting disjoint bounds on one of the problem variables.
For these new branch nodes, a relaxation is solved which either yields the
optimal objective or an infeasibility proof for the relaxed subproblem.

Newly generated branch nodes which admit feasible solutions (for the relaxed
subproblem) and objective values not exeeding the best known objective of a
feasible solution (for the original problem), are added to the list of active
branch nodes.

Sometimes, the optimal solution of a relaxed subproblem is feasible for the
original problem and improves the best known solution. Then the new solution
is saved (after some post optimzation steps); and the new bound decreases the
number of active subproblems.

Implementing a branch and bound solver means implementing a class for the
branch nodes which occur. From this class, the root nodes are explicitly
instanciated and passed to the \verb/branchScheme/ constructor which
internally performs the branching operations. That is, the branch nodes
keep the problem dependent information, and the branch scheme models the
problem independent data and methods.


\markright{BRANCH NODES}
\section{Branch Nodes}
\label{slb_bbnode}
\myinclude\verb/branchScheme.h/
\begin{mymethods}
\begin{verbatim}
template <class TIndex,class TObj>
class branchNode : public managedObject
{
    branchNode(TIndex,goblinController&,
            branchScheme<TIndex,TObj>* = NULL);

    TObj            Objective();
    virtual bool    Feasible();
    TIndex          Unfixed();

    virtual TIndex  SelectVariable() = 0;

    enum TBranchDir {LOWER_FIRST=0,RAISE_FIRST=1};

    virtual TBranchDir DirectionConstructive(TIndex) = 0;
    virtual TBranchDir DirectionExhaustive(TIndex) = 0;

    virtual branchNode<TIndex,TObj>* Clone() = 0;

    virtual void            Raise(TIndex) = 0;
    virtual void            Lower(TIndex) = 0;
    virtual TObj            SolveRelaxation() = 0;
    virtual TObjectSense    ObjectSense() = 0;
    virtual TObj            Infeasibility() = 0;
    virtual void            SaveSolution() = 0;
    virtual void            LocalSearch() {};
}
\end{verbatim}
\end{mymethods}
This class describes the interface between the generic branch scheme and the
problem dependent branch nodes. In order to implement a concrete branch and
bound solver, one just defines a subclass of \verb/branchNode/ which implements
all listed prototypes. We describe all methods in the order of occurence in the
branch scheme.

The method \verb/SelectVariable()/ returns the index \verb/i/ of a problem
variable for which the lower and the upper bound still differ and which is
relevant in the following sense: The current variable value is non-integral,
or restricting this variable promises a large change of the optimal objective 
in one of the new subproblems, and a feasible solution in the other subproblem.

To generate the two new subproblems, the branch scheme first calls
\verb/Clone()/ which returns a copy of the branch node which is currently
expanded. Then, \verb/Lower(i)/ is called for the original, and \verb/Raise(i)/
is called for the clone. This restricts the value of the variable \verb/i/ to
disjoint intervals in both subproblems. To the new problems, we
refer as the {\bf left} \index{branch and bound!left successor} and the
{\bf right}\index{branch and bound!right successor} successor. The parent node
is not needed any longer!

The methods \verb/DirectionConstructive()/ and \verb/DirectionExhaustive()/
tell the branch scheme which of the two new subproblems is inspected first.
A return value \verb/RAISE_FIRST/ causes that the left subproblem is inspected
first.
Note that \verb/DirectionConstructive()/ is called before the first feasible
solution for the original problem is found; and \verb/DirectionExhaustive()/
is called afterwards.

Then, the branch scheme evaluates the left and the right subproblem using the
following methods:
\begin{itemize}
\item \verb/SolveRelaxation()/ actually computes the objective value for the
relaxed subproblem while \verb/Objective()/ retrieves the cached objective
value when possible. The objective value is compared with the class constant
\verb/Infeasibility()/ in order to detect infeasible relaxed subproblems.
It is not allowed that \verb/SolveRelaxation()/ operates on the original graph
or LP data structures since these are needed to save the best solution found
so far.
\item \verb/ObjectSense()/ is a class constant and specifies either a
maximization or minimization problem.
\item \verb/Unfixed()/ returns the number of variables for which the lower and
the upper bound still differ. A subproblem with \verb/Unfixed()==0/ must be
either feasible for the original problem or infeasible for the relaxation.
For all other subproblems, let \verb/SelectVariable()/ return some branching
variable.
\item \verb/Feasible()/ checks if the optimal solution returned by
\verb/SolveRelaxation()/ is feasible for the original problem. The default
implementation considers every fixed solution to be problem-feasible.
\item If the relaxed optimum is feasible and improves the best known solution
for the original problem, then \verb/SaveSolution()/ is called in order to send
this solution to the original graph or LP data structures. It is useful to
implement \verb/LocalSearch()/ such that a post optimization procedure is
applied to all saved solutions. This local search method should be
defined for the hidden graph objects rather than the branch nodes so that it
can be used independently from branch and bound.
\end{itemize}

\bigskip
\begin{figurehere}
\begin{center}
\epsfxsize=12cm
\epsfbox{branch.eps}
\vspace{0.5cm}
\caption{\label{flb_branch}A Branch Tree}
\end{center}
\end{figurehere}

Nothing else is needed for an executable branch and bound solver. With respect
to efficiency, the following should be kept in mind:
\begin{itemize}
\item Let the branch nodes consume as few as possible memory if you want to
    solve large scale instances with optimality proof. In the constructive
    mode, the number of active nodes is somewhat like the DFS search depth
    and memory usage is not the most important issue.
\item The tradeoff between the running times and the obtained objective of
    \verb/SolveRelaxation()/ can be bothering. It depends on the DFS search
    depth and hence on the instance sizes. Generally, the quality of the
    obtained bounds is more important than the running times.
\item Consider if \verb/LocalSearch()/ is beneficial. It is not obvious whether
    feasible solutions obtained by the branch scheme are locally optimal. On
    the other hand, this method will be called only rarely.
\end{itemize}


\markright{GENERIC ALGORITHM}
\section{Generic Algorithm}
\label{slb_bbscheme}
\myinclude\verb/branchScheme.h/
\begin{mymethods}
\begin{verbatim}
template <class TIndex,class TObj>
class branchScheme : public managedObject
{
private:

    branchNode<TIndex,TObj> *firstActive;

    diGraph *       Tree;

protected:

    void Optimize() throw();
    bool Inspect(branchNode<TIndex,TObj> *);
    branchNode<TIndex,TObj> *SelectActiveNode();
    void QueueExploredNode(branchNode<TIndex,TObj> *);
    void StripQueue();

public:

    TIndex  nActive;
    TIndex  nIterations;
    TIndex  nDFS;
    bool    feasible;

    TObj    savedObjective;
    TObj    bestBound;

    enum TSearchLevel {
        SEARCH_FEASIBLE = 0,
        SEARCH_CONSTRUCT = 1,
        SEARCH_EXHAUSTIVE = 2};

    TSearchLevel level;

    branchScheme(branchNode<TIndex,TObj> *,TObj,
                  TSearchLevel = SEARCH_EXHAUSTIVE);

    enum TSearchState {
        INITIAL_DFS = 0,
        CONSTRUCT_BFS = 1,
        EXHAUSTIVE_BFS = 2,
        EXHAUSTIVE_DFS = 3};

    TSearchState SearchState();

    unsigned long   Size();
    unsigned long   Allocated();
};
\end{verbatim}
\end{mymethods}
Once a class of branch nodes is available, the application of the branch and
bound algorithm is as simple as possible: Just instanciate the root node (an
object which inherits from \verb/branchNode/), and then a \verb/branchScheme/
object. The \verb/branchScheme/ constructor takes the root node as a parameter
and implicitly calls the solver method \verb/Optimize()/. As the second
constructor parameter, either pass the objective value of a solution known in
advance, or the \verb/Infeasibility()/ constant if no feasible solution is
known.

The \verb/Optimize()/ method consists of the main loop and of iterated calls to
\verb/SelectActiveNode()/ and \verb/Inspect()/. The method
\verb/SelectActiveNode()/ selects an active subproblem which is split as
described in the previous section; \verb/Inspect()/ evaluates the new
subproblems; and \verb/StripQueue()/ deletes irrelevant branch nodes when an
improving feasible solution is found.

We have already described the problem specific parts of branch and bound codes,
and how these parts apply to the general algorithm. We have seen that the
branch strategy is partially controlled by the methods \verb/SelectVariable()/,
\verb/DirectionConstructive()/ and \verb/DirectionExhaustive()/. The method
\verb/SelectActiveNode()/ contributes the general strategy of switching between
best-first and depth-first steps. This strategy depends on the specified search
level:
\begin{itemize}
\item \verb/SEARCH_CONSTRUCT/: Branching starts with a certain (rather large)
    number of DFS steps in order to obtain an initial bound. After that, series
    of depth-first steps alternate with a few best-first steps so that the
    solver cannot get stuck in non-profitable regions of the branch tree. When
    getting close to \verb/maxBBNodes/, the maximal configured number of active
    branch nodes, only DFS steps are performed.
\item \verb/SEARCH_EXHAUSTIVE/: It is assumed that the initial bound is very
    close to the optimum. Best-first steps are performed unless the number
    of active branch nodes is getting close to \verb/maxBBNodes*100/ (in that
    case, DFS steps are performed).
\item \verb/SEARCH_FEASIBLE/: The search strategy is the same as in the
    \verb/SEARCH_CONSTRUCT/ case, but the solver stops when the first feasible
    solution has been found.
\end{itemize}
If the number of active nodes exeeds \verb/maxBBNodes*100/, or if the total
number \verb/nIterations/ of solved subproblems exeeds
\verb/maxBBIterations*1000/, then the solver halts in any case.

The current state of computation is given by \verb/SearchState()/. Especially
for \verb/SolveRelaxation()/ codes, it can be useful to retrieve
this search level and to apply a dual bounding procedure which is worse but
faster to compute in the inital DFS phase.

The transitions between the search states depend on the \verb/branchNode::depth/
parameter which is copied once from the root node to the branch scheme object.
It basically denotes an estimation the depth of the branch tree. This may
be the maximum number of non-zero problem variables, for example. If this depth
is underestimated, the solver may halt prematurely by reaching the configured
maximal number of active branch nodes; or the constructive DFS search is
interrupted before any leaves of the branch tree have been considered. If the
depth is overrated, no best-first steps can take place. By default, the
\verb/depth/ is the number of problem variables.

\bigskip
\begin{figurehere}
\begin{quote}
{\tiny
\begin{verbatim}
Iteration      Objective  Free  Status     Best Bound       Best Lower  Active  Select
--------------------------------------------------------------------------------------
        0             -5    12  QUEUED              0               -5       1  DEPTH
        1             -4    11  QUEUED              0               -5       1
        2             -4     7  QUEUED              0               -5       2  DEPTH
        3             -4     6  QUEUED              0               -5       2
        4             -4     3  QUEUED              0               -5       3  DEPTH
        5             -3     2  QUEUED              0               -5       3
        6             -4     1  QUEUED              0               -5       4  DEPTH
        7             -3     0  SAVED              -3               -5       3
        8             -4     0  SAVED              -4               -5       3  DEPTH
        9             -3     1  CUTOFF             -4               -5       2
       10             -3     0  CUTOFF             -4               -5       2  DEPTH
       11             -3     5  CUTOFF             -4               -5       1
       12             -4     3  CUTOFF             -4               -5       1  DEPTH
       13             -4    10  CUTOFF             -4               -5       0
       14             -4     7  CUTOFF             -4               -5       0
\end{verbatim}
}
\end{quote}
\begin{center}
\caption{\label{flb_branch2}A Branching Protocol}
\end{center}
\end{figurehere}

\noindent
The variable \verb/Tree/ maintains the \nt{branch tree} which can be displayed
graphically. An example of a branch tree can be found in Figure \ref{flb_branch}
and the corresponding logging information is shown in Figure \ref{flb_branch2}.
The labels of the tree nodes denote the iteration number, and the arc labels
denote the branching variable.


\markright{IMPLEMENTATIONS}
\section{Implementations}

\subsection{Stable Sets}
\label{slb_bbstable}
\myinclude\verb/branchStable.h/

\noindent
In the class \verb/branchStable/, all problem variables are associated with
graph nodes. Nodes can either be unfixed, selected or excluded. Every time
a node is selected, all of its neighbours are excluded. A node selection
corresponds to a call to \verb/Raise()/, excluding a node is done by calling
\verb/Lower()/.

Let $X$ denote the set of selected nodes and let $\Gamma(X)$ denote the set of
excluded nodes. The method \verb/SelectVariable()/ returns the index of a node
which has minimum degree in the graph restricted to
$V\setminus(X\cup\Gamma(X))$. By the definitions of
\verb/DirectionConstructive()/ and \verb/DirectionExhaustive()/, the selected
node is selected first in the DFS search, and then excluded.

The constructor of the root node determines a heuristic clique cover. This
clique cover is maintained for all subproblems. For a given subproblem, the
method \verb/SolveRelaxation()/ searches for all cliques which contain at least
one unfixed node. The number of these cliques plus the number of selected nodes
gives an upper bound which is returned.

A possible extension of this class to the weighted stable set problem seems
straightforward and desirable.


\subsection{Symmetric TSP}
\label{slb_branchSymmTSP}
\myinclude\verb/branchSymmTSP.h/

\noindent
In the class \verb/branchSymmTSP/, all problem variables are associated with
graph edges. Every branch and bound node owns a copy of the original
graph where the some of the arc capacities have been restricted to 0 or 1.
More explicitly, \verb/Lower()/ sets the upper capacity bound to 0 and
\verb/Raise()/ sets the lower capacity bound to 1. A raise operation checks if
two incident edges have been selected for one of the end nodes. Both procedures
can reduce the complexity by implicitly fixing arcs.

The arc returned by \verb/SelectVariable()/ is always in the current 1-tree,
and one of the end nodes has degree higher than 2 in the 1-tree. If possible,
the arc is chosen such that the high degree end node is already adjacent to a
fixed arc. Arcs are selected first in the DFS search, and then excluded.

\bigskip
\begin{figurehere}
\begin{center}
\epsfxsize=7cm
\epsfbox{candidates.eps}
\vspace{0.5cm}
\caption{\label{flb_candidates}A Candidate Graph}
\end{center}
\end{figurehere}

\noindent
The bounding procedure \verb/SolveRelaxation()/ is as follows: First,
it is checked that for all nodes at most two incident edges have been selected,
and that the subproblem is still 2-connected. If one of these conditions is
violated, \verb/InfFloat/ is returned.

Otherwise, a minimum spanning tree method is called which has been modified to
compute the optimal extension of the selected arcs to a 1-tree. The used node
potentials are inherited from the parent branch node.  The root node for the
1-tree computations is the same for all subproblems.

If \verb/methRelaxTSP2>0/, if the inital DFS phase has been passed, and if the
the length of the optimal 1-tree does not exeed the feasibility bound,
subgradient optimization is applied to increase the relaxation bound. This
procedure stops immediately, when the 1-tree length exeeds the feasibility
bound. When setting \verb/methRelaxTSP2=1/, the subgradient method runs in the
fast mode. When setting \verb/methRelaxTSP2=2/, the number of branch nodes is
minimized.

If the original graph is complete and \verb/CT.methCandidates==k/ where
$k\geq 0$, the constructor of the root branch node computes a candidate
subgraph which consists of
\begin{itemize}
\item the current predecessor arcs (usually the best known tour)
\item 20 random tours (one should set \verb/methLocal==1/ to force the tours
    to local optimality)
\item and the $k$ least cost edges incident with every graph node.
\end{itemize}
It has been experienced that even for $k=0$, often an optimal tour can be
obtained from the candidate graph. A TSP candidate graph is shown in Figure
\ref{flb_candidates}.

It is useful to run the branch and bound procedure twice. First, perform a
candidate search with a limit on the number of branch nodes (Take care that
some sequences of best-first steps can occur). Then either run the candidate
search again (The candidate graph includes the tour found before, so the
''good'' arcs are accumulated) or run an exhaustive search which can also
improve tours if the gap is small.

Experiments show that the TSP solver is able to evaluate complete graphs
with less than 150 nodes, and to candidate graphs with less than 200 nodes. See
the appendix for some computational results.


\subsection{Asymmetric TSP}
\label{slb_branchAsyTSP}
\myinclude\verb/branchAsyTSP.h/

\noindent
Nearly all statements of the previous section also apply to the TSP solver for
directed graphs. However, the applied spanning tree method is much
less performant, and the subgradient optimization is converging slower than in
the undirected setting. Also, only node insertion is available for local search
so that optimal tours are found later. Experiments have turned out that it is
possible to completely evaluate digraphs up to a size of 50 nodes.


\subsection{Node Colouring}
\label{slb_branchColour}
\myinclude\verb/branchColour.h/
\index{node colouring}
\noindent
The class \verb/branchColour/ defines an enumeration scheme rather than a branch
and bound solver. That is, the solver does not minimize the number $k$ of
colours but tries to find a $k$-colouring for a given number $k$. The strategy
is as follows:

Initially, all nodes are {\bf active}\index{node colouring!active node}.
Nodes become inactive if they are coloured or dominated by the current
(partial) colouring. Here a node $v$ is called {\bf dominated}
\index{node colouring!dominated node} if every consistent extension of the
current colouring to the active nodes can be extended to $v$ consistently. Some
nodes can be marked dominated a priori. For example, if the graph is planar
and $k\geq 6$, then all nodes are marked dominated.

The constructor for the master problem checks if the node colour data structure
of the original graph provides a clique. In the positive case, the clique nodes
are coloured $0,1,2,\dots$ immediately. Otherwise a maximum degree node is
coloured with colour $0$, and one of its neighbours is coloured with colour $1$.

Here, \verb/SelectVariable()/ determines the minimum available colour $c$ and
returns an active node $u$ which can be coloured with $c$. A call
\verb/Lower(u)/ will fix this colour and \verb/Raise(u)/ will forbid this
colour for $u$. The former method calls \verb/SetColour(u,c)/ which actually
fixes the colour of $u$ and checks for every active neighbour of $u$ if the
number of conflicts falls below $k$. In that situation, \verb/Reduce(u)/ is
called which marks the node as dominated.

The method \verb/SolveRelaxation()/ returns number of colours which are used
in this subproblem or detects infeasibility. If there are nodes for which
only one colour is available, then \verb/SetColour()/ to fix these node colours.
If there are no active nodes left, the dominated nodes are coloured by a call
to the method \verb/Complete()/.


\subsection{Maximum Cut}
\label{slb_branchMaxCut}
\myinclude\verb/branchMaxCut.h/

\noindent
In a \verb/branchMaxCut/ object, the problem variables represent the nodes of
a graph. A zero value denotes a left hand node, and a value of 2 denotes a right
hand node. A variable value 1 represents a node which is not fixed yet.
Depending on the status of the end nodes, arcs are either selected, dismissed
or unfixed.

In the undirected case, it is possible to extend the partial cut by at least
1/2 of the unfixed edges. To this end, \verb/SelectVariable()/ returns a
maximum capacity unfixed node, and \verb/DirectionConstructive()/ guides a DFS
search to add this node to the more profitable component.

The dual bound computed by \verb/SolveRelaxation()/ counts all selected and all
unfixed edges. This simple bounding procedure performs really poor, and only
allows to evaluate undirected graphs with up to 30 nodes. It is obvious (but not
implemented yet) that the bounds can be improved by considering odd length
cycles and chains of directed arcs.


\subsection{Mixed Integer Programming}
\label{slb_branchMIP}
\myinclude\verb/branchMIP.h/

\noindent
The class \verb/branchMIP/ implements a plain integer branch and bound. That is,
there is no code for cutting plane generation and pool management yet. The
problem variable returned by \verb/SelectVariable()/ has a maximum fractional
remainder among all integer variables; and a solution is considered
\verb/Feasible()/ when all fractional remainders fall beyond the context
parameter \verb/epsilon/.



\end{multicols}
\part{Methods}
\thispagestyle{empty}
\begin{multicols}{2}

\markboth{PROTOTYPES AND DATA STRUCTURES}{GRAPH DEFINITION}
\chapter{Prototypes and Data Structures}
\thispagestyle{fancy}
\label{clb_proto}

\section{Graph Definition}
\label{slb_definition}
In this section, we describe how problem instances, namely graph objects,
are specified in GOBLIN. In Section \ref{slb_sol}, we will also discuss the
potential solutions of graph optimization problems.

We have already mentioned that a class of graph objects may either represent
physical objects or logical views of other data objects. Hence we are concerned
with prototype methods rather than data structures.


\subsection{Incidences and Adjacencies}
\methods
\begin{quote}
\begin{verbatim}
class abstractMixedGraph
{
protected:

    goblinHashTable<TArc,TArc> *        adj;

public:

    virtual TArc    First(TNode) = 0;
    virtual TArc    Right(TArc,TNode) = 0;

    virtual TNode   StartNode(TArc) = 0;
    virtual TNode   EndNode(TArc);

    enum TMethAdjacency {ADJ_SEARCH,ADJ_MATRIX};

    virtual TArc    Adjacency(TNode,TNode,TMethAdjacency);
    void            MarkAdjacency(TNode,TNode,TArc);
    void            ReleaseAdjacencies();
}
\end{verbatim}
\end{quote}
Node incidences are the very core of any implementation of graph objects.
They can be accessed by iterator objects which were discussed in Chapter
\ref{clb_it} and which in turn require an implementation of the methods
\verb/First()/ and \verb/Right()/ (see Section \ref{slb_inci} for the details).

In a similar way any graph implementation must provide \nt{arc incidences},
that are the end nodes of a given arc, by defining a method \verb/StartNode/.
A call to the generic method \verb/EndNode()/ effectively determines the start
node of the reverse arc. We mention that \verb/StartNode()/ utilizes an array
in sparse graphs, but merely evaluates the arc indices in dense graphs.

Once node and arc incidences are available, GOBLIN can automatically compute
\nt{node adjacencies}, that are arcs joining two given nodes, by maintaining
an adequate data structure. Hence node adjacencies are not really graph
defining data structures but rather redundant information which can be
generated and disposed dynamically.

The data structure used for node adjacencies is a hash table which is generated
by the first call to \verb/Adjacency()/. The generation of this hash table can
be suppressed by passing an optional \verb/ADJ_SEARCH/ value. Note that the
operations on the hash table do not strictly run in constant time, but the
computation of an adjacency can be practically considered an elementary operation.

The returned arc is always non-blocking. That is, in digraphs, no backward arcs
are returned. If the adjacency is ambiguous (that is, if parallel arc exist),
the returned arc index is the minimal one.

The method call \verb/MarkAdjacency(u,v,a)/ specifies the arc $a$ to be returned
by \verb/Adjacency(u,v)/. This is needed to maintain the adjacency table during
graph insertion and deletion operations.

Some classes override the generic implementations of \verb/EndNode()/
and \verb/Adjacency()/ for reasons of efficiency. In any case, the generic code is
helpful for the writing of preliminary versions of graph implementations.


\subsection{Arc Capacities and Node Demands}
\methods
\begin{quote}
\begin{verbatim}
class abstractMixedGraph
{
    virtual TCap    UCap(TArc) = 0;
    virtual TCap    MaxUCap();
    virtual bool    CUCap() = 0;

    virtual TCap    LCap(TArc) = 0;
    virtual TCap    MaxLCap();
    virtual bool    CLCap() = 0;

    virtual TCap    Demand(TNode);
    virtual TCap    MaxDemand();
    virtual bool    CDemand();
}
\end{verbatim}
\end{quote}
Arc capacities and node demands are numbers which determine the set of feasible
subgraphs respectively flows of a network programming problem. Although not
checked exhaustively in GOBLIN, arc capacities and node demands are supposed to
satisfy some properties:

For digraphs and flow networks, the node demands must resolve, that is, the
sum of demands must be zero. The arc capacities have to be non-negative,
but may be non-integral or even infinite. Needless to say that the lower bounds
should not exeed the respective upper bounds.

For undirected graphs, all arc capacities and node demands must be non-negative
numbers which are either integral or infinite. The sum of the node demands must
be an even number which is at most twice the sum of the arc capacities.

The methods \verb/MaxUCap/, \verb/MaxLCap/, \verb/MaxDemand/ return the
respective maximum label and the methods \verb/CUCap/, \verb/CLCap/,
\verb/CDemand/ decide whether the labels are constant or not.


\subsection{Length Labels}
\label{slb_length}
\methods
\begin{quote}
\begin{verbatim}
class abstractMixedGraph
{
    virtual TFloat  Length(TArc) = 0;
    virtual TFloat  MaxLength();
    virtual bool    CLength() = 0;
}
\end{verbatim}
\end{quote}
Length labels install linear objective functions which apply to most kinds
of network programming problems. For physical graph objects, length labels can
either be implemented by a simple array or determined by the geometric
embedding of the graph.

More explicitly, if the context variable \verb/methGeometry/ is zero, length
labels are read from an array data structure. Otherwise a certain metric of
the graph embedding is evaluated. The methods \verb/MaxLength/ return the
maximum length label and the methods \verb/CLength/, \verb/CDemand/ decide
whether the labels are constant or not.

\bigskip
\begin{tablehere}
\begin{center}
\begin{tabular}{|l|l|l|}
\hline
\verb/methGeometry/ & {\bf 0} & Explicit length labels \\
                    & 1 & Manhattan distances \\
                    & 2 & Euclidian distances \\
                    & 3 & Maximum coordinate distances \\
                    & 3 & Spheric distances \\
\hline
\end{tabular}
\end{center}
\caption{\label{tlb_metric_options}Selection of Length Labels}
\end{tablehere}


\subsection{Geometric Embedding}
\label{slb_geo}
\methods
\begin{quote}
\begin{verbatim}
class abstractMixedGraph
{
    virtual TFloat  C(TNode,TDim);
    virtual TFloat  CMax(TDim);
    virtual TDim    Dim();
}
\end{verbatim}
\end{quote}
Any class may or may not provide a geometrical embedding for their
graph objects. This embedding is needed for the graphical display. In case
of physical graphs, the geometrical embedding may also determine the length
labels.

The method \verb/Dim()/ specifies the {\bf dimension}
\index{geometric embedding!dimension} of the embedding, that is
the number of coordinates of each graph node. The actual \verb/i/th coordinate
of the node \verb/v/ can be obtained by \verb/C(v,i)/. A call \verb/CMax(i)/
returns the maximum extension of the graph in the \verb/i/th coordinate.

We mention that the graphical display uses the first two coordinates only,
and hence logical views are generally embedded into two-dimensional space.
Note also that the embedding includes the possible arc bend nodes and the
alignment points for arc labels.


\subsection{Layout}
\label{slb_layout}
\methods
\begin{quote}
\begin{verbatim}
class abstractMixedGraph
{
    virtual TNode   NI();
    virtual TNode   ArcLabelAnchor(TArc);
    virtual bool    NoArcLabelAnchors();
    virtual TNode   ThreadNode(TNode);
    virtual bool    NoThreadPoints();
    virtual bool    HiddenNode(TNode);
    virtual bool    HiddenArc(TArc);
}
\end{verbatim}
\end{quote}
Here we have listed several graph properties which do not influence the
behaviour of any problem solver but which are sometimes necessary to enhance
the graphical output.

The boolean functions \verb/HiddenNode()/ and \verb/HiddenArc()/ suppress the
drawing of certain nodes and arcs. The call \verb/ArcLabelAnchor(a)/ returns the
potential first artificial node for the arc \verb/a/. Actually, this point
determines the alignment of the arc label. If \verb/NoArcLabelAnchors()/ is true,
no arc label points and no bend nodes are present, and the labels are
aligned by a generic strategy.

Using \verb/ArcLabelAnchor(a)/ as the initial point, the ordered list of bend nodes
can be reconstructed by the iterated call of \verb/ThreadNode()/. If
\verb/NoThreadPoints()/ is true, no bend nodes are present, and the
graph arcs are visualized by straight lines.

The thread and alignment points together are the \nt{artificial nodes}.
The total number of artificial nodes is returned by \verb/NI()/.

So far, the layout of logical views is not too elaborate, in particular, the
definitions of \verb/ArcLabelAnchor()/ and \verb/ThreadNode()/ are only dummies. In a later
release, these two methods may also control the drawing of graph nodes.


\subsection{Arc Orientations}
\label{slb_orient}
\methods
\begin{quote}
\begin{verbatim}
class abstractMixedGraph
{
    virtual bool    Blocking(TArc) = 0;
}
\end{verbatim}
\end{quote}
This functionality is needed to distiguish directed arcs from undirected arcs.
More explicitly, \verb/Blocking(a)/ is true if the arc \verb/a/ is directed,
but a backward arc. In most classes, this method returns a constant, but
for physical mixed graphs the method is the public interface to an array data
structure.


\section{Registers}
\markright{REGISTERS}
\label{slb_registers}
By a \nt{register}, we denote all graph attributes handled by the pool of the same
name. Registers are used to store algorithmic solutions. They are all multipurpose,
and cover the often used combinations of base types and array dimensions.
\verb/Registers()/

\subsection{Predecessor Labels}
\label{slb_pred}
\methods
\begin{quote}
\begin{verbatim}
class abstractMixedGraph
{
protected:

    TArc *          P;

public:

    void            InitPredecessors();
    TArc            Pred(TNode);
    void            SetPred(TNode,TArc);
    void            ReleasePredecessors();
    void            WritePredecessors(goblinExport*);
    void            ReadPredecessors(goblinImport*);

    void            ExtractTrees();
    void            ExtractTree(TNode);
    TNode           ExtractPath(TNode,TNode);
    TNode           ExtractCycles();
    void            Extract1Matching();
    void            ExtractEdgeCover();
}
\end{verbatim}
\end{quote}
The general purpose of this data structure is to keep track of paths, cycles,
trees and any disjoint collection of such subgraphs with a minimum of computer
storage. Since predecessor labels define arborescences rather than
undirected trees, subgraphs can be searched much faster if they are encoded
into predecessor labels. Hence at least shortest path algorithms and TSP
algorithms depend on this data structure.

There is a public method \verb/Pred/ to read the current predecessor arc of
a given node, and methods \verb/SetPred/ and \verb/InitPredecessors/ which
manipulate the data structure in the obvious way. In addition, one can assign 
the complete set of predecessors with a subgraph present by the subgraph data
structure. There are several such methods each of which requires a special kind
of subgraph: 
\begin{itemize}
\item \verb/ExtractTrees()/ generates a set of rooted trees covering
    all graph nodes and corresponding to the connected components of the
    subgraph. An exception \verb/ERCheck/ is returned if the subgraph contains
    cycles.
\item \verb/ExtractTree(r)/ generates a tree rooted at \verb/r/. If the
    subgraph is disconnected or if the subgraph contains cycles, an exception
    \verb/ERCheck/ is returned. If the context flag \verb/meth1Tree/ is
    enabled, a unique cycle must exist, and \verb/r/ must be on this cycle.
\item \verb/ExtractPath(u,v)/ generates a directed path starting at
    \verb/u/ and ending at \verb/v/. An exception \verb/ERCheck/ is returned if
    \verb/u/ and \verb/v/ are disconnected in the subgraph of if the connected
    component of \verb/u/ and \verb/v/ contains {\bf branches}, that are nodes
    with degree at least 3.
\item \verb/ExtractCycles()/ generates a set of directed cycles
    which cover all graph nodes. Such a subgraph is called a \nt{2-factor}.
    An exception \verb/ERCheck/ is returned if the original subgraph is not a
    2-factor.
\item \verb/Extract1Matching()/ checks if the arcs of the subgraph
    are pairwise non-ajacent. If so, the predecessor labels are assigned with
    this \nt{1-matching} such that predecessors are always arcs with even
    indices. If there are adjacent arcs, an exception \verb/ERCheck/ is returned.
\item \verb/ExtractEdgeCover()/ checks if the arcs of the subgraph
    are pairwise non-ajacent. If so, the predecessor labels are assigned with
    this \nt{1-matching} and augmented to an edge cover. If the input subgraph
    is a maximum cardinality matching, a minimum edge cover results. The graph
    must not have isolated nodes.
\item \verb/ExtractColours()/ generates from the node partition data structure
    equivalent node colours such that the colour classes occur consecutively.
\end{itemize}


\subsection{Subgraphs}
\label{slb_sub}
\methods
\begin{quote}
\begin{verbatim}
class abstractMixedGraph
{
    void            InitSubgraph();
    void            WriteSubgraph(goblinExport*);
    void            ReadSubgraph(goblinImport*);

    virtual TFloat  Sub(TArc) = 0;
    virtual void    SetSub(TArc,TFloat);
    virtual void    SetSubRelative(TArc,TFloat);

    TCap            Cardinality();
    TCap            Length();

    void            AddToSubgraph(TNode = NoNode);
}
\end{verbatim}
\end{quote}
A \nt{subgraph} is a (possibly fractional) arc labelling which satisfies the
capacity bounds. If integral, a subgraph label $\verb/Sub(a)/$ may be interpreted
as the number of arcs in the subgraph which are parallel to $\verb/a/$ and is
therefore called the \nt{subgraph multiplicity} of $a$. Subgraphs of directed
graphs are also called \nt{pseudo-flow}.

This data structure differs from the other registers by the fact that it is
implementation dependent. That is, a subgraph of a sparse graph
object is a vector, a subgraph of a dense graph object is essentially a hash
table, and subgraphs of logical views can be defined completely differently.

More explicitly, every class must implement two methods \verb/SetSubRelative()/
and \verb/Sub()/. The first method increases or decreases a subgraph multiplicity
by a specified amount. If no subgraph data structure is present, \verb/Sub()/
returns the lower capacity bound. Every implementation of \verb/SetSubRelative()/
verifies that the resulting subgraph still observes the capacity bounds. There is
a method \verb/SetSub()/ which allows to subgraph multiplicities explicitly, and
which calls \verb/SetSubRelative()/ in the default implementation.

On the other hand, a subgraph may be {\bf infeasible}\index{subgraph!infeasible},
that is, node degrees and node demands may differ. A subgraph may also be
{\bf non-optimal}\index{subgraph!non-optimal}, that is, there is a subgraph
whose {\bf weight}\index{subgraph!weight} $\sum_a length(a)sub(a)$ is smaller.
The length of a subgraph can be computed in $O(m)$ time by \verb/Weight()/.
A corresponding method \verb/Cardinality()/ exists which determines the
{\bf cardinality}\index{subgraph!cardinality} $\sum_a sub(a)$ of a subgraph.

The method \verb/InitSubgraph()/ initializes the data structure with a
subgraph identical to the lower degree bound. Finally, the method
\verb/AddToSubgraph()/ takes the characteristic vector of the subgraph determined
by the predecessor labels, and adds it to the subgraph data structure.
If an optional node $v$ is specified, only the way back to the root of
$v$ respectively the cycle containing $v$ is added.

When working with subgraphs of dense graph objects, it is necessary either to
disable the subgraph hash table or to initialize the subgraph data structure
its maximum cardinality \verb/card/ by calling the representational object method
\verb/NewSubgraph(card)/. See also Section \ref{slb_dnsstruc}.


\subsection{Flow Labels}
\label{slb_flow}
\methods
\begin{quote}
\begin{verbatim}
class abstractMixedGraph
{
    virtual TFloat  Flow(TArc) = 0;
    virtual void    Push(TArc,TFloat) = 0;
}

class abstractBalancedFNW
{
    virtual TFloat  BalFlow(TArc) = 0;
    virtual void    BalPush(TArc,TFloat) = 0;

    virtual void    Symmetrize() = 0;
    virtual void    Relax() = 0;
}
\end{verbatim}
\end{quote}
Flow labels are an alias for subgraph multiplicities and used for network flow
problems. That is, \verb/Flow(a)/ and \verb/Sub(a)/ return the same value, and
\verb/Push(a,lambda)/ does the same as \verb/SetSubRelative(a,lambda)/up to the
sign of \verb/lambda/ which depends on the implicit orientation of the arc $a$.
Note that the node degrees are affected as well.

In balanced flow networks, a symmetric version of flow labels exists which
admit the analogous operations \verb/BalFlow/ and \verb/BalPush/. Note that
the call \verb/BalPush(a,lambda)/ essentially performs both
\verb/Push(a,lambda)/ and the symmetric operation \verb/Push(a^2,lambda)/.

There is a logical or even physical distinction
between symmetric and non-symmetric flow labels. Flow labels can be symmetrized
explicitly by calling \verb/Symmetrize()/, and the non-symmetric labels are
initilized with their balanced counterparts by calling \verb/Relax()/.


\subsection{Node Degrees}
\label{slb_deg}
\begin{quote}
\begin{verbatim}
class abstractMixedGraph
{
protected:

    TFloat *    sDeg;
    TFloat *    sDegIn;
    TFloat *    sDegOut;

public:

    void        InitDegrees();
    void        InitDegIO();
    TFloat      Deg(TNode);
    TFloat      DegIn(TNode);
    TFloat      DegOut(TNode);
    TFloat      Divergence(TNode);
    void        AdjustDegrees(TArc,TFloat);
    void        ReleaseDegrees();
}
\end{verbatim}
\end{quote}
Node degrees are rather an auxiliary data structure than a potential solution.
They are completely determined by the subgraph labels. The call \verb/Deg(v)/
returns the sum over all subgraph labels of undirected arcs adjacent with
the node \verb/v/. In the same manner, \verb/DegIn(v)/ is the sum of all
directed arcs with end node \verb/v/, and \verb/DegOut(v)/ is the sum of all
directed arcs with start node \verb/v/.

The necessary data structures are generated by the first calls of \verb/Deg()/,
\verb/DegIn()/ or \verb/DegOut()/ respectively. To keep the degree labels and the
subgraph multiplicities compliant, every implementation of \verb/SetSub()/ and
\verb/SetSubRelative()/ must include a call to \verb/AdjustDegrees()/. If not
needed any longer, degree labels may be disposed (other than the subgraph
multiplicities).

In order to obtain the node degrees in the original graph rather than in a
subgraph, one may set the lower capacity bounds to the value of the upper bounds.
Then the subgraph multiplicities and the node degrees will be set implicitly.


\subsection{Distance Labels}
\methods
\begin{quote}
\begin{verbatim}
class abstractMixedGraph
{
protected:

    TFloat *        d;

public:

    void            InitLabels(TFloat = InfFloat);
    virtual TFloat  Dist(TNode);
    void            SetDist(TNode,TFloat);
    void            ReleaseLabels();
    void            WriteLabels(goblinExport*);
    void            ReadLabels(goblinImport*);
}
\end{verbatim}
\end{quote}
Distance labels are not only utilized by shortest path algorithms, but more
generally to store the length of the paths which are encoded into the
predecessor labels. They are also used to specify cuts
(see Section \ref{slb_colour}).

A distance label may be read the method \verb/Dist/ and changed by
\verb/SetDist/. There is an initialization procedure \verb/InitLabels/
which sets some default value. This initilization routine supports the
reusage of the data structure to avoid repeated reallocation. Note that most
algorithms access the data structure directly for reasons of efficiency.

The methods \verb/ReadLabels/ and \verb/WriteLabels/ admit file import and
export of the data structure. The file format forms part of the general file
format for graph objects presented in Section \ref{slb_format}. Equivalent
statements hold for the other data structures described in what follows.


\subsection{Node Potentials}
\label{slb_pot}
\methods
\begin{quote}
\begin{verbatim}
class abstractMixedGraph
{
protected:

    TFloat *        pi;

public:

    void            InitPotentials(TFloat = 0);
    TFloat          Pi(TNode);
    void            SetPotential(TNode,TFloat);
    void            PushPotential(TNode,TFloat);
    void            UpdatePotentials(TFloat);
    void            ReleasePotentials();
    void            WritePotentials(goblinExport*);
    void            ReadPotentials(goblinImport*);

    virtual TFloat  RedLength(TArc);
}
\end{verbatim}
\end{quote}
Node potentials form the LP dual solutions of network flows and matchings.
This data structure can be accessed directly by network flow algorithms.
Even if not accessed directly, they come into play via the reduced or modified
length labels (see Section \ref{slb_length}). Reduced length labels also
appear in the subgradient method \verb/TSPSubOpt1Tree/ for the TSP.

The public interface allows to read node potentials (\verb/Pi/), to set
a single potential to the value (\verb/SetPotential/) and to add some amount
to the current potential (\verb/PushPotential/).

If this data structure is not present, all potentials are treated as zero.
Accordingly, a call to \verb/InitPotentials/ generates the data structure and
sets all potentials to zero. Note that \verb/InitPotentials/ may be called by
\verb/SetPotential/ and \verb/PushPotential/ recursively.

A call \verb/UpdatePotentials(alpha)/ adds the current distance labels to the
current potentials. But note that only those potentials are changed for which
the corresponding distance label is less than \verb/alpha/. This procedure is
used by the min-cost flow algorithm \verb/EdmondsKarp2/ which recursively calls
the \verb/Dijkstra/ method. The latter procedure searches the reduced length
labels but keeps the result via the distance labels. The threshold \verb/alpha/
is needed since the \verb/Dijkstra/ graph search is incomplete in general.

The reduced length labels combine the length labels and the node potentials
to the optimality certificates well-known in linear programming. If \verb/a/
denotes some arc with end nodes \verb/u/ and \verb/v/, then \verb/RedLength(a)/
is defined as \verb/Length(a)+Pi(u)+Pi(v)/ in undirected graphs, and as
\verb/Length(a)+Pi(u)-Pi(v)/ in directed graphs. Shortest path problems
and weighted network flow problems are solved optimally if and only if all
reduced length labels are non-negative.

There are two further methods \verb/ModLength/ and \verb/RModLength/ which
extend the concept of reduced cost optimality to balanced network flow and
matching problems. Since the computation of modified length labels is
expensive, \verb/RModLength/ allows the recursive computation whereas
\verb/ModLength/ utilizes an explicit data structure.


\subsection{Node Colours}
\label{slb_colour}
\methods
\begin{quote}
\begin{verbatim}
class abstractMixedGraph
{
protected:

    TNode *         colour;

public:

    void            InitColours(TNode = NoNode);
    virtual TNode   Colour(TNode);
    void            SetColour(TNode,TNode);
    void            ReleaseColours();
    void            WriteColours(goblinExport*);
    void            ReadColours(goblinImport*);

    void            UpdateColours();
    void            ExtractCut();
    void            ExtractBipartition();
    void            ExtractColours();
}
\end{verbatim}
\end{quote}
Node colours are not only used to store graph colourings, but can also
represent cuts and connected components with a minimum of computer storage.
For example, the matching procedures return the blossom structure as node
colours. More explicitly, the \verb/gra2bal/ destructor assigns to each node
the blossom base as its colour.

\verb/ExtractCut()/ assigns colour zero to all nodes with finite distance labels,
and colour 1 to the remaining nodes. \verb/ExtractBipartition()/ assigns colour
zero to all nodes with even finite distance labels, and colour 1 to the
remaining nodes. \verb/ExtractColours()/ saves a (non-persistent) node
partition into a consecutive series of node colours.


\subsection{Partitions of the Node Set}
\label{slb_part}
\methods
\begin{quote}
\begin{verbatim}
class abstractMixedGraph
{
protected:

    goblinDisjointSetSystem<TNode> *    partition;

public:

    virtual void    InitPartition();
    virtual void    Bud(TNode v);
    virtual void    Merge(TNode u,TNode v);
    virtual TNode   Find(TNode v);
    virtual void    ReleasePartition();
}
\end{verbatim}
\end{quote}
The partition data structure is a disjoint set union data structure.
In contrast to the most data structures which were discussed here,
a partition is a high-level data structure which cannot be
written to a file and reconstructed properly.

The methods are only shortcuts for the operations described in Section
\ref{slb_dsu}. That is, \verb/Bud(v)/ generates a one elementary set which
consists of $v$, \verb/Merge(x,y)/ unifies the sets containing $x$ and $y$,
and \verb/Find(w)/ returns the canonical element of the set cotaining $w$.


\subsection{Blossoms}
\label{slb_blossom}
\methods
\begin{quote}
\begin{verbatim}
class abstractBalancedFNW
{
protected:

    TNode *         base;

public:

    void            InitBlossoms();
    void            ReleaseBlossoms();
    TNode           Base(TNode v);
    void            Shrink(TNode u,TNode v);
}
\end{verbatim}
\end{quote}
\index{blossom}
Blossoms are the symmetric specialization of the node partition data structure,
and override the general definitions. In contrast to general partitions,
complementary nodes are always in the same part of thepartition. The method
\verb/Base/ does not return an arbitrary canonical element, but a special node 
which is called the {\bf blossom base}\index{blossom!base}.

This node can be defined algorithmically as follows: \verb/Bud(v)/ implies that
\verb/Base(v)==v/. If one has \verb/Base(u)==v/ and \verb/Base(x)==y/, then the
operation \verb/Shrink(u,x)/ implies that \verb/Base(u)==Base(x)==v/. That is,
the first parameter of \verb/Shrink/ determines the blossom base.


\subsection{Props and Petals}
\label{slb_prop}
\methods
\begin{quote}
\begin{verbatim}
class abstractBalancedFNW
{
protected:

    TArc *          prop;
    TArc *          petal;

public:

    void            InitProps();
    void            ReleaseProps();

    void            InitPetals();
    void            ReleasePetals();
}
\end{verbatim}
\end{quote}
Props and petals determine augmenting paths in a balanced flow network. The
labels are set by the balanced network search methods which are discussed in
Section \ref{slb_bns}. Augmenting paths can be extracted by the recursive call of
the methods \verb/Expand/ and \verb/CoExpand/. The resulting path is assigned to
the predecessor labels.


\subsection{Odd Cycles}
\label{slb_odd}
\methods
\begin{quote}
\begin{verbatim}
class abstractBalancedFNW
{
protected:

    TArc *          Q;

public:

    void            InitCycles();
    void            ReleaseCycles();
}
\end{verbatim}
\end{quote}
This data structure is used quite analogously to the predecessor labels, in
particular, to store a system of disjoint cycles in a balanced flow network.
These odd cycles occur during the symmetrization of the flow labels and denote
the arcs with non-integral flow labels after a call of \verb/CancelEven()/.
The odd cycles are cancelled again by \verb/CancelOdd()/ and \verb/CancelPD()/.
Both methods form part of the \verb/Anstee/ and the \verb/EnhancedPD/ method.
See Sections \ref{slb_cancel} and \ref{slb_enhanced} for the details.


\section{Manipulating Graphs}
\markright{MANIPULATING GRAPHS}
The following methods are available for physical graph objects only. That is,
we are now talking about data structures, not only about prototype methods.

\subsection{Changes of the Incidence Structure}
\methods
\begin{quote}
\begin{verbatim}
class sparseRepresentation
{
    TArc    InsertArc(TNode,TNode,TCap,TCap,TFloat);
    TArc    InsertArc(TNode,TNode);
    TNode   InsertNode();
    TNode   InsertArtificialNode();
    TNode   InsertArcLabelAnchor(TArc);
    TNode   InsertThreadSuccessor(TNode);

    void    SwapArcs(TArc,TArc);
    void    SwapNodes(TNode,TNode);
    void    FlipArc(TArc);
    void    CancelArc(TArc);
    void    CancelNode(TNode);
    void    DeleteArc(TArc);
    void    DeleteNode(TNode);
    void    DeleteArcs();
    void    DeleteNodes();
    void    ContractArc(TArc);
    void    IdentifyNodes(TNode,TNode);

    void    SetCapacity(TNode,TArc);
}

class denseRepresentation
{
    TArc    InsertArc(TArc,TCap,TCap,TFloat);
}
\end{verbatim}
\end{quote}
In sparse graph objects, \verb/InsertArc(u,v,uu,ll,cc)/ generates a new
incidence with start node $u$, end node $v$, upper capacity bound $uu$,
lower capacity bound $ll$ and length label $cc$. In order to avoid
multiple reallocation of the data structures when several new arcs are
generated, one can call \verb/SetCapacity(n,m)/ initially to set the final
dimensions. In the same way, \verb/InsertArc(u,v)/ generates a new
incidence with random or constant capacities. This depends on the configuration
flags \verb/randLength/, \verb/randUCap/, \verb/randLCap/.

Dense graph objects also admit an operation
\verb/InsertArc(a,uu,ll,cc)/. Actually, such an operation
does not generate a new incidence but increases the lower bound
of an existing arc $a$ by an amount of $ll$, and the upper bound
by an amount of $uu$. The new length label overwrites the old one.

The other operations which apply to sparse graph objects only, have been
described in Section \ref{slb_spsstruc}. Note that node insertions maintain
colours, distance labels and node potentials but destroy node partition data
structure. Arc and node canceling operations do not influence the potential
solutions, but node deletions effectively destroy all potential solutions.

None of the listed methods does apply if another data object references the
graph which has to be manipulated.


\subsection{Invalidation Policy}
When the incidence structure of a graph is modified, the following internal
data structures are \nt{invalidated}, that is, they do not apply to the
modified graph object:
\begin{itemize}
\item Iterators
\item Potential solutions
\item Dual incidences
\item Node ajacencies
\end{itemize}
There is no exhaustive code that keeps these data structures up to date. It is
only guaranteed that invalid data structures are deleted transparently. In the
case of node adjacencies, node degrees and graph duality data, this strategy
is adequate since the data structure can be rebuilt implicitly.

With some exceptions (required in the library) potential solutions are lost
irreversibly if they are invalidated.

Special care is required with iterators if maintained independently from the
graph object. To be safe, generate a graph clone, manipulate this copy but
iterate on the original graph. If you want to delete nodes or arcs, apply
cancel operations instead and delete the canceled items in a final step.

The following is a list of graph manipulation operations ordered by their
impact on the discussed data structures:
\begin{itemize}
\item Arc insertions
\item Node insertions
\item Arc cancel and contraction operations
\item Arc deletions
\item Node deletions
\end{itemize}


\subsection{Updates on the Node and Arc Labels}
\methods
\begin{quote}
\begin{verbatim}
class graphRepresentation
{
    void            SetUCap(TArc,TCap);
    void            SetLCap(TArc,TCap);
    void            SetDemand(TNode,TCap);
    void            SetLength(TArc,TFloat);
    void            SetOrientation(TArc,char);
    void            SetC(TNode,bool,TFloat);

    void            SetCUCap(TCap);
    void            SetCLCap(TCap);
    void            SetCDemand(TCap);
    void            SetCLength(TFloat);
    void            SetCOrientation(char);
}
\end{verbatim}
\end{quote}
For physical graph objects, each of the labels discussed in Section
\ref{slb_definition} can be set to another value by the methods
\verb/SetUCap/, \verb/SetLCap/, \verb/SetDemand/, \verb/SetLength/,
\verb/SetOrientation/ and \verb/SetC/ respectively. All methods maintain the
respective maximal labels in a way such that an exhaustive computation is
avoided.

The methods \verb/SetCUCap/, \verb/SetCLCap/, \verb/SetCDemand/,
\verb/SetCOrientation/ and \verb/SetCLength/ set the current labeling
to a constant and disallocate the respective data structures.

Note that the updates described usually lead to non-optimal or even infeasible
solutions. Post-Optimality procedures are problem-dependent and hence cannot be
supported here.


\subsection{Merging Graphs}
\methods
\begin{quote}
\begin{verbatim}
class abstractMixedGraph
{
    void Merge(abstractMixedGraph&);
}
\end{verbatim}
\end{quote}
This method merges a specified graph object into another graph without
identifying any of the graph nodes. The passed graph is not manipulated
(but only a copy is generated). The addressed graph which stores the result
is layouted.


\cleardoublepage
\markboth{GRAPH DRAWING}{PRELIMINARY REMARKS}
\chapter{Graph Drawing}
\thispagestyle{fancy}
\label{clb_graph_drawing}
% Latest revision: CFP, 19.11.2005

\section{Preliminary Remarks}
By \nt{graph drawing}, we denote techniques to manipulate the graph node
coordinates and to add some artificial points for better readability. This
task is distinguished from the {\bf graph display} process which maps a drawing
to a computer screen and which assigns some textual information to the
nodes and edges in the drawing. When dealing with planar graphs, drawing is
also distinguished from the {\bf embedding} phase which determines an
appropriate order of the node incidences and selects an exterior face.

In case of \nt{geometric optimization instances}, the node coordinates also
define the edge lengths. Here, layout methods generally do not apply.

All produced drawings are 2-dimensional. This is frequently used for inline
drawing when graph objects are derived from others.


\subsection{Layout Models}
\label{slb_layout_models}
\myinclude\verb/globals.h/, \verb/abstractMixedGraph.h/
\begin{mymethods}
\begin{verbatim}
enum TLayoutModel {
    LAYOUT_DEFAULT = -1,
    LAYOUT_FREESTYLE_POLYGONES = 0,
    LAYOUT_FREESTYLE_CURVES = 1,
    LAYOUT_ORTHO_SMALL = 2,
    LAYOUT_ORTHO_BIG = 3,
    LAYOUT_VISIBILITY = 4,
    LAYOUT_KANDINSKI = 5,
    LAYOUT_STRAIGHT_2DIM = 6,
    LAYOUT_LAYERED = 7,
    LAYOUT_NONE = 8
};

class goblinController
{
    void    SetDisplayParameters(TLayoutModel);
}

class abstractMixedGraph
{
    void    Layout_ConvertModel(TLayoutModel);
}
\end{verbatim}
\end{mymethods}
\nt{Layout models} denote general drawing styles with precise properties
allowing to improve given drawings and to convert to other laout models.
All drawing methods activate the appropriate \nt{layout model} by calling
\verb/Layout_ConvertModel()/ and, recursively, \verb/SetDisplayParameters()/.

The latter procedure effectively overwrites the various display parameters
(listed in Section \ref{slb_display}) with layout model dependent default
values. One can customize the display style by setting some of the context
parameters. Note that custom values are overwritten with the next call to
\verb/SetLayoutParameters()/.

In addition, \verb/Layout_ConvertModel(model)/ has the capability to adjust the
current drawing: If the target layout model is \verb/LAYOUT_STRAIGHT_2DIM/,
all bends and shape nodes are eliminated. Conversely, if the target model is
\verb/LAYOUT_FREESTYLE_POLYGONES/ or \verb/LAYOUT_FREESTYLE_CURVES/, the edges
are redrawn to exhibit parallel edges and loops. If neither the target model
nor the original model is \verb/LAYOUT_STRAIGHT_2DIM/, by default, an
intermediary conversion to the \verb/LAYOUT_STRAIGHT_2DIM/ model takes place.

Future development will bear more sophisticated conversion rules, but only for
particular pairs of layout models. The procedure is not intended to perform
drawing algorithms inline.


\subsection{Grid Lines}
\label{slb_grid lines}
\begin{mymethods}
\begin{verbatim}
class goblinController
{
    int    nodeSep;
    int    bendSep;
    int    fineSep;
}
\end{verbatim}
\end{mymethods}
Most layout algorithms place nodes on integer coordinates.


\markright{LOW LEVEL OPERATIONS}
\section{Low Level Operations}

\subsection{Translations of the Current Drawing}
\label{slb_translate_drawing}
\myinclude\verb/abstractMixedGraph.h/
\begin{mymethods}
\begin{verbatim}
class abstractMixedGraph
{
    void    Layout_StripEmbedding();
    void    Layout_ScaleEmbedding(
                TFloat,TFloat,TFloat,TFloat);
}
\end{verbatim}
\end{mymethods}
There are two methods \verb/Layout_StripEmbedding()/ and
\verb/Layout_ScaleEmbedding(x,X,y,Y)/ which shift respectively scale the
current drawing. The strip operation shifts the drawing to the non-negative
orthant such that every coordinate becomes zero for at least one graph node.

The parameters of the scale operation specify a tight bounding box for the
updated coordinates. By taking \verb/X<x/ or \verb/Y<y/, the scale operation
can be used to flip the layout along the ordinate or abscissa.

Do not confuse this functionality with the display parameters which are
discussed in Section \ref{slb_display} and which change the view independently
from the saved coordiantes and the geometric distance labels.


\subsection{Automatic Alignment of Arcs}
\label{slb_auto_arc_alignment}
\myinclude\verb/abstractMixedGraph.h/
\begin{mymethods}
\begin{verbatim}
class abstractMixedGraph
{
    void    Layout_ArcAlignment(TFloat = 0);
}
\end{verbatim}
\end{mymethods}
The method \verb/Layout_ArcAlignment(d)/ eliminates all arc alignment points
from the present layout and then redraws the arcs where simple graphs are
drawn with straight lines. Parallel arcs are separated by using the parameter
\verb/d/. If no value is specified, the context variable \verb/bendSep/ comes
into play. Loops which are usually invisible (unless interpolation points are
associated with them) are also drawn.
All of the layout methods which are discussed next perform this arc alignment
procedure as a final step.


\subsection{Arc Subdivision}
\myinclude\verb/abstractMixedGraph.h/
\begin{mymethods}
\begin{verbatim}
class abstractMixedGraph
{
    void    Layout_SubdivideArcs(TFloat = 0);
}
\end{verbatim}
\end{mymethods}
Calling \verb/Layout_ArcAlignment(d)/ eliminates all arc alignment points from
the present layout. Then the nodes are virtually moved to the grid specified
by the parameter $d$. For every arc $a$ and every horizontal grid line crossed
by $a$, a bend node is placed on this grid line. And bend nodes of $a$ are
aligned vertically, centered between its end nodes.



\markright{CIRCULAR LAYOUT}
\section{Circular Layout}
\label{slb_circular_layout}
\myinclude\verb/abstractMixedGraph.h/
\begin{mymethods}
\begin{verbatim}
class abstractMixedGraph
{
    void    Layout_Circular(int = 0);
    void    Layout_CircularByPredecessors(int = 0);
    void    Layout_CircularByColours(int = 0);
    bool    Layout_Outerplanar(int = 0);
}
\end{verbatim}
\end{mymethods}
The method \verb/Layout_Circular(spacing)/ draws the graph nodes as a regular
polyhedron in the x-y plane. If \verb/spacing/ is specified, this overwrites
the context parameter \verb/nodeSep/. There are some variants of the method
which differ by the order of the nodes on the resulting circle:
\begin{itemize}
\item \verb/Layout_CircularByPredecessors()/: If predecessor arcs are
    available, the method starts at some node, tracks back the predecessor arcs
    and consecutively places the nodes until a node is reached with is already
    placed. Then, a new thread of search is started. In particular, the procedure
    exhibits Hamiltonian cycles. If no predecessor labels are available, nodes
    are placed by their indices.
\item \verb/Layout_CircularByColours()/: The nodes are displayed by their colour
    index. By that, colour clusters and special node orderings can be exhibited.
    If no predecessor labels are available, nodes are placed by their indices.
\item \verb/Layout_Outerplanar()/: This checks if an outerplanar embedding
    is available and, occasionally, exhibits this embedding. If \verb/methLocal/
    is set, the planar FDP method is called to improve the circular drawing.
\end{itemize}
When calling \verb/Layout_Circular()/, it applies on of the described methods
(in that order of preference).


\markright{FORCE DIRECTED PLACEMENT}
\section{Force Directed Placement}
\label{slb_force_directed}
\begin{mymethods}
\begin{verbatim}
class abstractMixedGraph
{
    enum    TOptFDP {
                FDP_DEFAULT = -1,
                FDP_DEFAULT = -1,
                FDP_GEM = 0,
                FDP_SPRING = 1,
                FDP_RESTRICTED = 2,
                FDP_LAYERED = 4,
                FDP_LAYERED_RESTR = 6
            };

    void    Layout_ForceDirected(
                TOptFDP = FDP_DEFAULT,int = 0);
    void    Layout_PlanarFDP(int = 0);

    void    Layout_SpringEmbedder(TFloat = 0,TFloat = 0);
    void    Layout_GEMDrawing(TOptFDP = FDP_GEM,int = 0);
}
\end{verbatim}
\end{mymethods}
The method \verb/Layout_ForceDirected(method,spacing)/ is the interface to a
couple of layout methods which all are \nt{force directed}. These kind of
methods apply to general graph objects and can help to exhibit graph symmetries.
If \verb/method/ does not specified otherwise, the applied method is determined
by the context parameter \verb/methFDP/. The role of the parameter
\verb/spacing/ is the same as for the circular layout method.

The method \verb/Layout_SpringEmbedder(gamma,delta)/ models the graph nodes as
loaded particles and the graph arcs as springs in the x-y plane. The parameters
work as constants for the respective forces. Starting with the present
embedding, a Newton iteration scheme searches for equilibriance of the modelled
forces. The main disadvantage of this algorithm is its poor performance. The
input graph should be connected for otherwise the connected components diverge.

For practical purposes, it is recommended to apply \verb/Layout_GEMDrawing()/
instead of the classic spring embedder. This algorithm moves only one node at a
time. In addition to the forces discussed before, attraction to the center of
gravity is modelled. The step length is determined by the nodes' temperatures
and the sophisticated temperature adjustment rule is the reason for the good
performance. The resulting drawings do not differ significantly compared with
the spring embedder.

There is another method \verb/Layout_PlanarFDP()/ which preserves the edge
crossing properties of the initial layout. It applies to general graphs but, of
course, is intended to allow post processing of planar layouts. The procedure
augments the GEM algorithm by additional forces and certain restrictions.
It is less performant than the unrestricted GEM code.


\markright{STRAIGHT LINE DRAWING}
\section{Planar Straight Line Drawing}
\begin{mymethods}
\begin{verbatim}
class abstractMixedGraph
{
    void    Layout_StraightLineDrawing(
                TArc = NoArc,int = 0);
    void    Layout_ConvexDrawing(
                TArc = NoArc,int = 0);
}
\end{verbatim}
\end{mymethods}
The method \verb/Layout_ConvexDrawing(a,spacing)/ computes a straight line grid
drawing without edge crossings for triconnected planar graphs such that all
interior faces are convex. A combinatorial representation must be already assigned.

The shape of drawing is a triangle with the specified arc $a$ forming the basis.
By that, the exterior face is set to the left hand side of $a$. If no arc is
specified, the basis arc is the same as \verb/ExteriorArc()/. If the latter arc
is undefined, the exterior arc is chosen on a face which maximizes the number
of exterior nodes. The tip node is set implicitly and is "half way" on the
exterior face. All nodes are placed at integer coordinates, depending on
\verb/spacing/ or the context parameter \verb/nodeSep/. The time complexity is
$O(m)$.

The procedure uses the canonically ordered partition which is discussed in the
next chapter. This structure and the convexity of the interior faces require
that the input graph is triconnected.

When calling \verb/Layout_StraightLineDrawing(a,spacing)/, the graph is
triangulated and to the triangulation, the convex drawing method is applied.
The time complexity is $O(n^2)$. If \verb/methLocal/ is set, the planar FDP
method is called to improve the drawing of the original graph. This
postprocessing is necessary at least if a lot of artificial edges have been
added. See Section \ref{slb_planarity} for more details about triangulations.


\clearpage
\markright{ORTHOGONAL DRAWING}
\section{Orthogonal Drawing}
\label{slb_orthogonal_layout}
\myinclude\verb/abstractMixedGraph.h/
\begin{mymethods}
\begin{verbatim}
class abstractMixedGraph
{
    enum TOptOrthogonal {
        ORTHO_DEFAULT,ORTHO_EXPLICIT,ORTHO_EULER,
        ORTHO_DEG4,ORTHO_4PLANAR,ORTHO_VISIBILITY,
        ORTHO_VISIBILITY_TRIM,ORTHO_VISIBILITY_GIOTTO
    };

    void    Layout_Orthogonal1Bent(
                TOptOrthogonal = ORTHO_DEFAULT,int = 0);
    void    Layout_OrthogonalDeg4(
                TOptOrthogonal = ORTHO_4PLANAR,int = 0);
    void    Layout_VisibilityRepresentation(
                TOptOrthogonal = ORTHO_VISIBILITY_TRIM,
                int = 0);
    void    Layout_StaircaseDrawing(TArc = NoArc,int = 0);
    void    Layout_StaircaseTriconnected(TArc = NoArc,int = 0);
}
\end{verbatim}
\end{mymethods}
In an orthogonal drawing, every edge is represented by an alternating sequence
of horizontal and vertical line segments. If the nodes are drawn without
dimension, this approach is restricted to graphs with maximum degree 4 or less.
The literature comes up with at least four layout models for drawing high
degree graphs:
\begin{itemize}
\item \nt{GIOTTO}, where the nodes are rectangles in a square grid. Edges are drawn
    by placing ports at each end node and a sequence of bend nodes within the
    same grid as the rectangles. No bound on the size of the rectangles is
    imposed by this model.
\item \nt{Kandinsky}, where the nodes are squares of a common size centered in a
    sparse square grid. Edge ports and bend nodes are placed in a subdivided
    square grid. The size of the node squares is the maximum number of ports
    $d$ assigned to one side of a square.
\item \nt{Proportional growth}, which is similar to GIOTTO but also requires
    that the height of a node equals the number of ports on either the left or
    the right side, and that the width equals the number of ports on the top or
    the bottom line.
\item \nt{Visibility representations}, in which nodes are horizontal and edges
    are vertical line segments. The length of node segments does not depend
    on the node degrees.
\end{itemize}
In every model, the edges must be drawn on the grid lines. Edges and node
representations may not overlap or cross each other, but edges may cross other
edges when planarity is not required. The known algorithms for graphs with
maximum degree 4 produce drawings which fit into the first three models.
General methods, applied to degree-4 graphs, are not as smart. That is, large
nodes with several ports on one side of a node may result.

GOBLIN provides Kandinsky drawings of general graphs, visibility representations
and GIOTTO drawings for planar graphs and drawings with small nodes for
2-connected graphs with maximum node degree 4. There are also codes for the
orthogonal drawing of trees, see Section \ref{slb_tree_layout}.

By calling \verb/Layout_Orthogonal1Bent(opt,grid)/, the following steps
are performed in order to obtain a drawing in the Kandinsky model:
\begin{itemize}
\item The nodes are placed in \nt{general position}, that is with only node
    in one column or row. This placement preserves the order of coordinate
    values in the preceding drawing.
\item The edges are distributed to the four sides of each node. The node size
    is also computed. This procedure depends on the \verb/opt/ parameter.
\item A couple of context parameters are set according to the Kandinsky layout
    model and the grids used for this drawing.
\item The edges on each side of a node are ordered so that the drawing does
    not include crossings of adjacent arcs.
\item Every arc is drawn with exactly one bend node and with the arc
    label in the neighbourhood of this bend node.
\end{itemize}
If the graph layout and incidence structure is not changed intermediately,
calling this layout tool several times results in the same drawing. But 
the procedure supports some pre- and postprocessing techniques:
\begin{itemize}
\item The preceding node placement: It is useful to start with a readable
    drawing, not necessarily in an orthogonal layout model. One can move
    nodes manually and rerun the method to improve the node placement.
\item When using \verb/opt = ORTHO_EXPLICIT/, directed arcs leave on the
    top or the bottom side of the start node and enter the end node on the
    left or the right side. The same is true for the inherent orientation of
    undirected edges. It follows that one can revert the the orientations
    of undirected edges in order to reduce the number of edge crossings
    and the node size $d$.
\end{itemize}
The running time is $O(m)$, the number of bends is $m$ and the square area is
$(2n(d+1)-1)^2$. The parameter $d$ is trivially bounded by the maximum node
degree $\Delta$ and for \verb/opt = ORTHO_EULER/, one has $d\leq\Delta/2$.

The call \verb/Layout_StaircaseDrawing(aBasis,grid)/ applies to a planar graph
and then computes a plane Kandinsky drawing with one-bent arcs. The arc
\verb/aBasis/ herein is drawn on the the exterior face, covering two sides of
the drawing. The graph is implicitly triangulated since the core method only
applies to triconnected graphs. For this reason, a shortcut
\verb/Layout_StaircaseTriconnected(aBasis,grid)/ exists which saves the
triangulation part.

By calling \verb/Layout_OrthogonalDeg4(opt,grid)/, an $st$-numbering is
computed and the nodes are placed one-by-one with respect to this ordering,
each node on a new grid row. Columns may carry several graph nodes and at most
two bends. The input graph must be 2-connected and without loops.

If the graph is planar and if \verb/opt = ORTHO_4PLANAR/ is used, a plane drawing
results and the inherent combinatorial representation is visualized. In this case,
the running time is $O(n)$. Otherwise, the running time is $O(n^2)$ due to the iterated
computation of horizontal coordinates. The achieved grid size is $(m-n+1)n$ in
the worst case. Every edge is drawn with at most two bends. Only one edge
incident with the final node may be drawn with 3 bends.

For all drawing method described so far, post-processing techniques exist to
reduce the number of bend nodes and the overall grid size. This is in particular
useful if the graph was augmented to achieve a certain degree of connectivity:
After drawing the augmented graph and then releasing the artificial edges, the
routing of the original edges looks unnatural, and the grid size may be far too
large. The post-processing enabled by setting the context flag
\verb/methLocalSearch/. Note that the post-processing codes might take much more
computational time than the drawing from scratch!

By calling \verb/Layout_VisibilityRepresentation(opt,grid)/, the input graph is
augmented to a 2-connected planar graph. Then, a bipolar orientation and a
directed dual graph are generated. For both the primal and the dual digraph,
the distance labels with respect to the source nodes are computed. The primal
distances give assigment of rows to the nodes in the drawing, and the dual
distances determine the columns for the drawing of arcs. The method option
applies as follows:
\begin{itemize}
\item Using \verb/opt = ORTHO_VISIBILITY_RAW/, the drawing is as usually
    described in the literature. That is, the node width may exceed the size
    required by the vertical edge segments.
\item Using \verb/opt = ORTHO_VISIBILITY_TRIM/, the nodes are shrunk in a way
    that edges are still drawn vertically without bends.
\item Using \verb/opt = ORTHO_VISIBILITY_GIOTTO/, the node widths are minimized
    and every edge is drawn with at most two bends. If the input graph is
    2-connected and all nodes have degree 2 or 3, the final drawing is in the
    small node model. Otherwise, a GIOTTO drawing results.
\end{itemize}
In any circumstances, the input graph must be without loops. The running time
is $O(n)$ and the achieved grid size is $(2n-5)(n-1)$ in the worst case.

Post-processing techniques for the GIOTTO and the visibility represetation
models are desirable but not available yet.


\markright{LAYERED DRAWING}
\section{Layered Drawing}
\label{slb_layered_drawing}
\myinclude\verb/abstractMixedGraph.h/
\begin{mymethods}
\begin{verbatim}
class abstractMixedGraph
{
    enum TOptLayered {
        LAYERED_DEFAULT,LAYERED_FEEDBACK,LAYERED_EDGE_SPAN,
        LAYERED_VERTICAL,LAYERED_COLOURS,LAYERED_FDP,
        LAYERED_ALIGN,LAYERED_SWEEP,LAYERED_HORIZONTAL
    };

    void    Layout_Layered(
                int method = LAYERED_DEFAULT,
                int = 0,int = 0);
}
\end{verbatim}
\end{mymethods}
In a \nt{layered drawing}, the node set is partitioned into horizontal layers,
and bend nodes are placed wherever edges would cross layers in a straight line
drawing. Assigning nodes to layers is done by so-called \nt{vertical methods}.
Then a \nt{horizontal method} is used to arrange the nodes within their layers.
Hereby, original graph nodes and bend nodes are treated the same.

The public interface to the compound layout tool is \verb/Layout_Layered(method,x,y)/
where $x$ and $y$ are node separation parameters, and \verb/method/ is a
bitfield of options. Every bit represents a private class method. The vertical
methods are:
\begin{itemize}
\item \verb/LAYERED_FEEDBACK/: Arc orientations are computed such that the
    resulting digraph is acyclic. Arcs are not really reverted but the
    orientations are encoded into edge colours (0: Directed as is, 1: Reverted).
    If the graph is undirected, a bipolar orientation is computed. Otherwise,
    the feedback arc set solver is called.
\item \verb/LAYERED_EDGE_SPAN/: For a given feedback arc set, vertices are
    placed such that a minimum number of bend nodes is needed. This uses linear
    programming techniques and is highly efficient. If no feedback arc set is
    provided, the arcs are implicitly oriented by the $y$-coordinates.
\item \verb/LAYERED_COLOURS/: If node colours are available, the layering is
    done accordingly. If the colouring is incomplete, the minimum edge span
    code is run to fill the gaps (But this requires a feedback arc set).
\end{itemize}
The results of the vertical methods are the assigned y-coordinates. Horizontal
methods only depend on the provided node coordinates. The vertical phase can be
entirely skipped or, at least, the preset x-coordinates apply. In order to extract
the correct layering, all nodes must be placed on the integer grid defined by
the \verb/x/ parameter. The horizontal methods are as follows:
\begin{itemize}
\item \verb/LAYERED_SWEEP/: Starting with the first layer, refine the
    order of the nodes in the second layer in order to minimize the number of
    edge crossings between these two layers. Proceed from layer to layer with this
    1-layer crossing minimization. When the final layer is reached, sweep back
    to the first layer. Repeat the procedure until no further improvement is
    achieved. This step is important for readable layouts; but it is also performance
    critical.
\item \verb/LAYERED_ALIGN/: Shift nodes horizontally, but preserve the present
    order. The goal is to draw arcs as steep as possible, in particular the
    segments between bend nodes. This procedure uses linear programming techniques.
\item \verb/LAYERED_FDP/: Apply a specialized FDP method which only manipulates
    the horizontal node positions. If other horizontal methods are used,
    preserve the current order of nodes in any layer. Practically, the convergence
    is insufficient even for moderate size graphs.
\end{itemize}
All procedures run in the displayed order. It is obvious that not all
combinations make sense. When calling the layout tool with the
\verb/LAYERED_DEFAULT/ option, \verb/LAYERED_VERTICAL|LAYERED_HORIZONTAL/
is substituted.

Layered drawing codes are so popular since no restrictions are imposed on the
input graphs (up to loops which are not handled). The best results are achieved
with upward planar digraphs. Planar undirected graphs are not displayed so
readable, due to the insufficient layering: The minimum edge span method produces
only few layers since arc orientations are almost arbitrary. The display quality
can be improved drastically by specifying an orientation.


\markright{TREE LAYOUT}
\section{Tree Layout}
\label{slb_tree_layout}
\myinclude\verb/abstractMixedGraph.h/
\begin{mymethods}
\begin{verbatim}
class abstractMixedGraph
{
    enum TOptAlign {
        ALIGN_OPTIMIZE,ALIGN_LEFT,ALIGN_CENTER,
        ALIGN_FDP,ALIGN_RIGHT
    };

    void    Layout_PredecessorTree(
                TOptAlign = ALIGN_CENTER,
                int = 0,int = 0);

    void    Layout_KandinskyTree(TNode = NoNode,int = 0);
    bool    Layout_HorizontalVerticalTree(TNode = NoNode,int = 0);
}
\end{verbatim}
\end{mymethods}
The method \verb/Layout_PredecessorTree(method,dx,dy)/ draws a graph directed
by the predecessor labels which must form a forest of rooted trees.
Connectivity is not required. The parameters \verb/dx/ and \verb/dy/ denote
the horizontal respectively the vertical node distance. If no values are
specified, the context variable \verb/nodeSep/ comes into play.

The \verb/method/ parameter determines how nodes are aligned vertically with
their parent nodes:
\begin{itemize}
\item \verb/ALIGN_LEFT/: Non-leave nodes are aligned with the left-most child
\item \verb/ALIGN_RIGHT/: Non-leave nodes are aligned with the right-most child
\item \verb/ALIGN_CENTER/: Non-leave nodes are centered among their children
\item \verb/ALIGN_OPTIMIZE/: This is equivalent with using the \verb/ALIGN_CENTER/
    option and then calling \verb/Layout_Layered(LAYERED_ALIGN,x,y)/
\item \verb/ALIGN_FDP/: This is equivalent with using the \verb/ALIGN_CENTER/
    option and then calling \verb/Layout_Layered(LAYERED_FDP,x,y)/
\end{itemize}
The displayed order of child nodes is independent of the \verb/method/ option.
If the graph does not contain edges other than the predecessor arcs, the drawing
is plane and represents the node incidence orders. Additional non-predecessor
arcs are displayed somewhat arbitrarily.

The basic tree drawing method runs in linear time, but the additional operations
from the layered drawing tool do not.

For binary trees, the call \verb/Layout_HorizontalVerticalTree(root,grid)/ produces
a so-called \nt{HV-drawing}, where is every node is placed atop and/or left-hand of
its descendants. That is, subtree root nodes are displayed in the upper left corner
of the tight subtree bounding box. HV-drawings are very special case of orthogonal
drawings.

The procedure exposes a predecessor tree in any circumstances. If predecessor
labels exist in advance, it is checked if the predecessor arcs form a binary
tree. If not, \verb/false/ is returned. Otherwise this predecessor tree is
displayed, and true is returned, ignoring all non-tree arcs which might exist.

If no predecessor labels exist in advance, it is asssumed that the entire graph
forms a binary tree. If not, \verb/false/ might be returned. Otherwise, if not
passed explicitly, an appropriate \verb/root/ node is chosen (degree two nodes
are preferred, but degree 1 nodes are also accepted). From this root node, a BFS
tree is computed, saved to the predecessor labels and visualized. Note that the
procedure is successful if a binary subtree has been found, not only if the
entire graph forms a binary tree.

\bigskip
\begin{figurehere}
\begin{center}
\epsfxsize=7cm
\epsfbox{eps/binTree.eps}
\vspace{0.5cm}
\caption{\label{flb_hv_tree}A HV-drawing of a binary tree}
\end{center}
\end{figurehere}

The method \verb/Layout_KandinskyTree(method,root,grid)/ combines the ideas from
both layered and orthogonal grid drawing. The tree is displayed top-down, and
nodes are centered among their descendants. The drawing is in the Kandinsky model
(see Section \ref{slb_orthogonal_layout}). All nodes have equal size
${(\Delta-2)/2}$ where $\Delta$ denotes the maximum degree.

Both orthogonal tree drawing codes run in linear time, but only if the layout
compaction is turned of. Both procedures do not complain about non-tree arcs,
but also do not take care of drawing such arcs.


\markright{EQUILATERAL DRAWING}
\section{Equilateral Drawing}
\label{slb_equilateral}
\myinclude\verb/abstractMixedGraph.h/
\begin{mymethods}
\begin{verbatim}
class abstractMixedGraph
{
    void    Layout_Equilateral(int = 0);
}
\end{verbatim}
\end{mymethods}
This method requires an outerplanar, 2-connected graph. All faces other than
the exterior region are drawn as equilateral polygones. The constant edge length
is either passed explicitly or given by the context parameter \verb/nodeSep/.

The procedure is intended for drawing regular polyhedra, including Platonic
solids, after unrolling the surface to plane.



\cleardoublepage
\markboth{HIGH LEVEL ALGORITHMS}{SHORTEST PATH ALGORITHMS}
\chapter{High Level Algorithms}
\thispagestyle{fancy}
\label{clb6}
This chapter shows how GOBLIN problem solvers are called and configured.
It also includes a brief introduction to the respective problem settings,
and to the general ideas behind the algorithms implemented.
With some text book about graph theory at hand and using the GOBLET browser,
any interested people should be able to understand the source code.

For the most problems, the implemented algorithms do not reflect the current
state of research. But the library covers all of the standard problems and
careful implementations of all of the algorithms which one can find in text
books about graph optimization. The non-weighted matching code which was
the original authors research interest clearly stands out.

Up to the max-cut and the Steiner tree codes which can only be viewed as an
interface for future implementations, all solvers are configured to solve
practical problem instances. This ranges from several 10000 node instances for
shortest path, min-tree, max-flow and non-weighted matching problems, a few
thousand node problems for min-cost flow, arborescence and weighted matching
problems to 150 node instances for the exact solution of NP-hard problems
(we have restricted ourselves to pure combinatorial methods).
Note that there was considerable effort to provide codes which support post
optimization and which apply to the most general problem formulations possible.



\section{Shortest Paths}
\label{slb_solve_shortest_path}
\methods
\begin{quote}
\begin{verbatim}
class abstractMixedGraph
{
    enum    TNethSPX {
                SPX_DEFAULT = -1,
                SPX_FIFO = 0,
                SPX_DIJKSTRA = 1,
                SPX_BELLMAN = 2,
                SPX_BFS = 3,
                SPX_DAG = 4,
                SPX_TJOIN = 5
            };

    enum    TOptSPX {
                SPX_PLAIN = 0,
                SPX_SUBGRAPH = 1,
                SPX_RESIDUAL = 2,
                SPX_REDUCED = 4,
                SPX_REDUCED_RESIDUAL = 6
            };

    bool    ShortestPath(TNode s,TNode t = NoNode);
    bool    ShortestPath(TMethSPX,TOptSPX,
                TNode,TNode = NoNode);

    bool    Eligible(TOptSPX,TArc);

    bool    BFS(TOptSPX,TNode,TNode = NoNode);
    TNode   SPX_Dijkstra(TOptSPX,
                const indexSet<TNode>&,
                const indexSet<TNode>&);
    bool    SPX_FIFOLabelCorrecting(TOptSPX,
                TNode,TNode = NoNode);
    bool    SPX_BellmanFord(TOptSPX,
                TNode,TNode = NoNode);

    TNode   VoronoiRegions();
}

class abstractGraph
{
    bool    SPX_TJoin(TNode,TNode);
}
\end{verbatim}
\end{quote}

\subsection{Eligible Arcs}
\index{eligible arc}
The method \verb/Eligible()/ qualifies the arcs which may appear on a shortest
path (tree). Basically, it guides shortest path algorithms to compute directed
paths for digraph objects, and arbitrary paths in undirected graphs. If the
\verb/SPX_RESIDUAL/ option is used, paths with residual capacity are
determined. If the \verb/SPX_SUBGRAPH/ option is used, the subgraph defined
by the arcs $a$ with \verb/Subgraph(a)>0/ is searched.

An {\bf eligible}\index{$st$-path!eligible} $st$-path is a simple path starting
at node $s$ and ending at node $t$ which entirely consists of eligible arcs. A
{\bf shortest} $st$-path is an eligible $st$-path of minimum length. A
\nt{shortest path tree} is a tree such that any path from the root to another
node is a shortest path.

\bigskip
\begin{figurehere}
\begin{center}
\epsfxsize=11cm
\epsfbox{gsearch.eps}
\vspace{0.5cm}
\caption{\label{flb_gsearch}A Shortest Path Tree}
\end{center}
\end{figurehere}


\subsection{Solver Interface}
The solver is called like \verb/ShortestPath(method,characteristic,s,t)/.
There is a shortcut \verb/ShortestPath(s,t)/ which applies the options \verb/method = SPX_DEFAULT/
and \verb/characteristic = SPX_PLAIN/. A \verb/method = SPX_DEFAULT/ value
is eventually replaced by the value of the context variable \verb/methSPX/.

The parameter $s$ denotes the root of the requested shortest path tree.
The parameter $t$ is optional and denotes a node to be reached. If no $t$ is
specified, the member \verb/targetNode/ is used. If this is also undefined,
a full shortest path tree is determined. If $t$ is specified and reachable from $s$
by eligible arcs, the computation may stop prematurely for sake of performance.
The return value is \verb/true/ if $t$ is $s$-reachable, and \verb/false/ otherwise.
Shortest paths are returned by the predecessor labels together with the matching
distance labels.

The \verb/characteristic/ parameter switches between applying the original length
labels and the reduced length labels (when using \verb/SPX_REDUCED/ or
\verb/SPX_REDUCED_RESIDUAL/).

A shortest path tree with respect to the reduced length labels is also a shortest
path tree for the original length labels. The length of cycles does not depend
on the \verb/characteristic/ option and the concrete node potentials. But
searching the reduced length labels is useful since those labels can be usually
kept non-negative, and this is required by some shortest path methods.

In what follows, the particular shortest path algorithms are described.
Most methods can be accessed by the hub \verb/ShortestPath()/, but this does mean
that the codes are interchangeable: Each algorithms applies to a special
(and often restrictive) setting. The label correcting algorithms are the most
general ones, but even those cannot handle the computation of a shortest path
when the graph admits negative length cycles and, in particular, when undirected
edges of negative length exist.

In any situation where the selected method does not apply, an \verb/ERRejected/
exception is raised.


\subsection{Breadth First Search}
This method computes an eligible $sv$-path with a minimum number of arcs for
every node $v$ of the graph. So this procedure solves the shortest path problem
for graph with constant non-negative edge lengths. The running time is $O(m)$.
When calling \verb/BFS()/ directly, the length labels are ignored. When calling
this method by using \verb/ShortestPath()/, and if the length labels are
not constant or negative, an exception is raised.


\subsection{The Dijkstra Algorithm}
\label{dijkstra}
This is a multi-terminal version of the Dijkstra method. One index set
is passed to specify the root nodes, the second index set specifies the
target nodes. The return value is some target node which could be reached
from any root node.

The Dijkstra method cannot handle negative length arcs at all.It will,
however, complain only if a negative length arc is actually searched.

The algorithm utilizes a priority queue data structure. This may
either be passed by the member pointer variable \verb/nHeap/ or, if
\verb/nHeap==NULL/, generated by the method itself. In the latter case,
the type of the priority queue is chosen according to the context parameter
\verb/methPQ/. The respective running times are $O(n^2)$, $O(m\log{n})$ with
the binary heaps and $O(m+n\log{n})$ with the Fibonacci heaps.

If one needs to compute all-pair shortest paths, it is reasonable to apply
a label-correcting method (but only if negative lengths can occur) and then
to compute a shortest path tree for each graph node with the Dijkstra method.
This requires $O(n(m+n\log{n}))$ time and only $O(m)$ storage compared with
$O(n^2)$ for the Floyd-Warshall code.


\subsection{Discrete Voronoi Regions}
\label{slb_voronoi}
This is a variation of the Dijkstra method which treats all graph nodes with
\verb/Demand()/ different from zero a root nodes. The set of target nodes is
empty and, by that, all full graph search is performed. If every connected
component includes at least one terminal node, the procedure returns with
partial trees which connect every node to some terminal, and with corresponding
distance labels.

The \nt{Voronoi regions} are also returned by the node partition data structure.
The formal return value is the number of terminals and the running times are
essentially the same as for \verb/SPX_Dijkstra()/.


\subsection{The Bellman-Ford Algorithm}
This method determines a shortest $sv$-path for every node $v$ of the graph.
Negative length labels are allowed. If a negative length cycle is detected,
the procedure returns an exception \verb/ERCheck/. The running time
is $O(mn)$.


\subsection{The FIFO Label-Correcting Algorithm}
This method determines a shortest $sv$-path for every node $v$ of the graph.
Negative length labels are allowed. If a negative length cycle is detected,
the procedure returns an exception \verb/ERCheck/. The running time
is $O(mn)$. This algorithm is a practical improvement of the Bellman-Ford
procedure.

\bigskip
\begin{figurehere}
\begin{center}
\epsfxsize=9cm
\epsfbox{eps/tjoinShortestPath.eps}
\vspace{0.5cm}
\caption{\label{flb_tjoin}A $T$-Join Shortest Path}
\end{center}
\end{figurehere}


\subsection{The $T$-Join Algorithm}
The method \verb/SPX_TJoin()/ differs from the previous shortest path algorithms
in several ways: First of all, it does not compute a shortest path tree but
only a single simple path. Furthermore, it applies to undirected graphs only.

In any circumsatnces, the method returns an optimal $T$-join by the subgraph
labels, and this subgraph splits into an $st$-path and a couple of (not
necessarily node-disjoint) cycles. The following situations
may arise:
\begin{itemize}
\item The $T$-join is a simple $st$-path. Then this path is a shortest $st$-path
    and is returned by the predecessor labels.
\item There is no $T$-join. Then also no $st$-path exists.
\item The $T$-join splits into a simple $st$-path plus some more connected
    components. Then this $st$-path is returned by the predecessor labels,
    but this is not necessarily a shortest path.
\item In the $T$-join, $s$ and $t$ are in a common non-trivial component.
    From this component, an arbitrary $st$-path is extracted.
\end{itemize}
That is, the method can deal with negative length arcs, at least, if there are
no negative length cycles. When it is not possible to compute an exact solution
for the shortest path problem from the optimal $T$-join, at least, a heuristic
solution is returned.

The method consists of $O(n)$ calls of the Dijkstra method and the solution of
a weighted $1$-matching problem with at most $n$ nodes (the problem size depends
on the number negative length edges). This matching problem dominates the running
times.


\subsection{The Floyd-Warshall Algorithm}
This method determines the distances between every pair of nodes in $O(n^3)$
time. It is encoded into the constructor of the class \verb/distanceGraph/
and, by that, generates a complete digraph which has the original node
distances as its length labels.


\subsection{Proposed Extension}
A dequeue label-correcting algorithm.



\markright{NEGATIVE CYCLES}
\label{slb620}
\section{Negative Cycles}
\methods
\begin{quote}
\begin{verbatim}
class abstractMixedGraph
{
    TNode   NegativeCycle(TNode = NoNode);
}

class abstractDiGraph
{
protected:
    TCap    mu;

public:
    TNode   MinimumMeanCycle();
}
\end{verbatim}
\end{quote}
Primal min-cost flow algorithm traditionally try to find an augmenting cycle
of negative length. GOBLIN supplies two methods which are useful in this
context. Both methods apply for digraphs only.


\subsection{Negative Cycles}
The method \verb/NegativeCycle()/ determines an arbitrary eligible cycle with
negative length. The return value is a node on this cycle. The cycle itself is
returned via the predecessor labels. If an optional node is passed, this node is
considered to be the root of a graph search, and essentially the FIFO
label correcting algorithm results.


\subsection{Minimum Mean Cycles}
The method \verb/MinimumMeanCycle()/ determines an eligible cycle such that the
ratio of the sum of length labels and the number of arcs on this cycle is
minimum. Again, the return value is a node on the cycle, and the cycle itself
is returned via the predecessor labels. The minimum ratio is kept by the
variable \verb/mu/ for further processing. The method also works if this ratio
is negative.

An important drawback of the algorithm is that it requires $\Theta(n^2)$
storage units which makes it inapplicable to large-scale problems, say with
$n>10^5$.


\subsection{Proposed Extension}
A mean cycle algorithm which runs with linear storage requirements.



\markright{DAG SEARCH}
\label{slb_dag_search}
\section{DAG Search}
\methods
\begin{quote}
\begin{verbatim}
class abstractDigraph
{
    enum    TDAGSearch {
                DAG_TOPSORT,
                DAG_CRITICAL,
                DAG_SPTREE
            };

    TNode   DAGSearch(TDAGSearch,
                TNode=NoNode,TNode=NoNode);
    TNode   TopSort();
    TNode   CriticalPath();
}
\end{verbatim}
\end{quote}
A \nt{DAG} is a directed acyclic graph object. The procedure
\verb/DAGSearch(opt)/ handles the recognition of DAGs and does some additional
computations depending on the value of \verb/opt/:
\begin{itemize}
\item For \verb/DAG_TOPSORT/ and \verb/DAG_SPTREE/, a topological oerdering is
    exported by the node colour data structure. If the graph contains directed
    cycles, a node on a cycle is returned.
\item For \verb/DAG_SPTREE/, a shortest path tree and the distance labels are
    exported.
\item For \verb/DAG_CRITICAL/, a directed path of maximum length is computed
    and its end node is returned (unless cycles are found). For every node,
    the distance label denotes the maximum path lengths from a root node.
\end{itemize}
The methods \verb/CriticalPath()/ and \verb/TopSort()/ are shortcuts which
should be used as entry points. The shortest path version is handled by
\verb/ShortestPath()/. The running time of a DAG search is $O(m)$ in every
instance. Note that eligible (residual capacity) arcs are searched instead of
the original directions.



\markright{EULER CYCLES}
\label{slb_euler}
\section{Euler Cycles}
\methods
\begin{quote}
\begin{verbatim}
class abstractMixedGraph
{
    bool        EulerCycle(TArc* = NULL);
}
\end{verbatim}
\end{quote}
An Euler cycle is a closed walk which traverses all graph edges exactly once.
It can be computed by the call \verb/EulerCycle(pred)/ in $O(m)$ time. This method
implements the Hierholzer algorithm and returns false if no Euler cycle
exists. Otherwise an Euler cycle is returned by the passed array \verb/pred/
which must be allocated by the calling context as \verb/TArc[M()]/.
The Euler cycle is decoded from the array as follows:
\begin{mysample}
\begin{verbatim}
TArc* pred = new TArc[M()];

if (!EulerCycle(pred)) {/* Handle exception */};

TArc a = pred[0];
for (TArc i=0;i<=M();i++)
{
    a = pred[a>>1];
    // Process the arc a
}
\end{verbatim}
\end{mysample}
If one calls \verb/EulerCycle()/ without parameters, the Euler cycle is translated
to an edge numbering and saved to the edge colours.

Note that the procedure does not inspect the arc capacities. If capacities are
considered as multiplicities (as in the Chinese postman solver), the graph must
be preprocessed with \verb/ExplicitParallels()/ to eliminate the capacities.
Zero capacity arcs must be eliminated manually. Be aware of the problem size and
the running time which grows linearly with the sum of multiplicities!



\vfill
\markright{SPANNING TREES}
\section{Spanning Trees}
\label{slb_solve_mintree}
\methods
\begin{quote}
\begin{verbatim}
class abstractMixedGraph
{
    enum        TMethMST {
                    MST_DEFAULT = -1,
                    MST_PRIM = 0,
                    MST_PRIM2 = 1,
                    MST_KRUSKAL = 2,
                    MST_EDMONDS = 3
                };

    enum        TOptMST {
                    MST_PLAIN = 0,
                    MST_ONE_CYCLE = 1,
                    MST_REDUCED = 8,
                    MST_MAX = 16
                };

    TFloat MinTree(TNode r = NoNode);
    TFloat MinTree(TMethMST,
               TOptMST,TNode = NoNode);

    TFloat MST_Prim(TMethMST,
               TOptMST,TNode = NoNode);
    TFloat MST_Edmonds(TOptMST,TNode = NoNode);
    TFloat MST_Kruskal(TOptMST,TNode = NoNode);
}

class abstractDiGraph
{
    TCap                TreePacking(TNode);
    abstractDiGraph*    TreePKGInit();
    TCap                TreePKGStripTree(
                            abstractDiGraph*,TCap,TNode);
}
\end{verbatim}
\end{quote}
A spanning tree of a graph is a subgraph which connects all nodes but does
not contain cycles. There is no reason to distinguish between a minimization
and a maximization problem for spanning trees. We follow the convention to
formulate the minimization problem, at least as the default setting.

The spanning tree solver is called like \verb/MinTree(method,characteristic,r)/.
The shortcut \verb/MinTree(r)/ applies \verb/method = MST_DEFAULT/
and \verb/characteristic = MST_PLAIN/. A \verb/method = MST_DEFAULT/ value
is eventually replaced by the value of the context variable \verb/methMST/.
The parameter $r$ is optional and denotes the root node. If $r$ is not
specified, the member \verb/rootNode/ is used.

Other than in earlier releases, the \verb/MinTree()/ interface function is used
for both the directed and the undirected setting. Accordingly, the Edmonds
arborescence method can run on undirected graphs (with a similar behavior as
the Kruskal method, at least when the edge lengths are mutually distinct)
and the Prim and the Kruskal method apply to mixed and to directed graphs
(ignoring the edge orientation).

There is a couple of options which can be passed with \verb/characteristic/ and
which all methods allow for:
\begin{itemize}
\item \verb/MST_MAX/: Changes the object sense to maximization
\item \verb/MST_REDUCED/: Consider the reduced length labels instead of the
    original length labels
\item \verb/MST_ONE_CYCLE/: Construct a one cycle tree instead of a spanning tree
\end{itemize}
The Kruskal method, the enhanced Prim method and the method for mixed graphs
can handle arcs with non-trivial capacity lower bounds which denote mandatory
arcs. This mechanism is applied in the branch and bound module of the TSP solver.


\subsection{The (Enhanced) Prim Algorithm}
This procedure grows the spanning tree from the root node to the tips.
If no root node is passed, one is selected automatically. The resulting tree
is returned by the predecessor labels.

Two versions of this method are provided. The running time of the basic
version is $O(n^2)$. The enhanced code differs from the basic version mainly
by using a priority queue for node selection. The complexity depends on the
special choice of this queue, and matches the running times for the Dijkstra
algorithm (see Section \ref{dijkstra}).

\begin{figurehere}
\begin{center}
\epsfxsize=8cm
\epsfbox{mintree.eps}
\vspace{0.5cm}
\caption{\label{flb_mintree}Intermediate Step in the Prim Method}
\end{center}
\end{figurehere}


\subsection{The Kruskal Algorithm}
The procedure returns a spanning tree via the subgraph data structure if one
exists. If not, the connected components are maintained by the partition data
structure. The running time is $O(m\log{n})$ due to the needed sorting of the
edge by their lengths.


\subsection{Arborescences}
The method \verb/MST_Edmonds()/ is an $O(nm)$ implementation of Edmond's
arborescence algorithm and determines a maximum spanning forest. If a root
node is passed, and this is actually a root node, an arborescence is returned
by the predecessor labels. If no root node is passed, one is selected
automatically. The procedure uses the shrinking family data structure
(see Section \ref{slb_shrfam}).


\subsection{One Cycle Trees}
\label{slb733}
All spanning tree methods described above can be used to compute an
\nt{$r$-tree}. In the undirected setting, this is a minimum spanning tree of
the nodes other than $r$ plus the two shortest edges incident with $r$.
In the directed setting, an $r$-tree is an minimum arborescence rooted at
$r$ plus the shortest arc entering $r$.

When the spanning tree solver is called with the \verb/MST_ONE_CYCLE/ and a
root node $r$, it will determine predecessor labels such that $r$ is on the
unique directed cycle defined by these labels. For every node $v$ not on this
cycle, there is a unique directed path of predecessor arcs connecting the cycle
and $v$.

The worst case complexities are the same as for constructing ordinary spanning
trees.


\subsection{Tree Packings}
The method \verb/TreePacking(TNode)/ determines a maximum cardinality set of
pairwise disjoint arborescences rooted at a specified node. If the arc capacities
are non-trivial, the algorithm computes some tree capacities and for every arc
the sum of the tree capacities satisfies the capacity bound.

If the main procedure \verb/TreePacking()/ is called, the tree capacities
are provided by the log file and, if \verb/traceLevel>2/, the found
arborescences are written to trace files. But one can also call the component
\verb/TreePKGStrip()/ which manipulates a copy of the digraph and
one-by-one returns the arborescences via the predecessor labels of the original
graph and also returns the corresponding tree capacity. The graph copy is
generated by the method \verb/TreePKGInit()/. The complete method looks like
this:
\begin{mysample}
\begin{verbatim}
TCap totalMultiplicity = StrongEdgeConnectivity(r);
abstractDiGraph* G = TreePKGInit();
while (totalMultiplicity>0)
{
    TreePKGStrip(G,&totalMultiplicity,r);
    // Use the predecessor labels
}
delete G;
\end{verbatim}
\end{mysample}
The tree packing method is non-polynomial, also slow in practice and applies to
directed graphs only. Note that the application to the complete orientation
does not yield a tree packing in the undirected sense.


\subsection{Proposed Extension}
A cycle canceling method for post-optimization of spanning trees.



\vfill
\markright{CONNECTED COMPONENTS}
\section{Connected Components}
\label{slb_components}
\methods
\begin{quote}
\begin{verbatim}
class abstractMixedGraph
{
    bool    Connected();
    bool    StronglyConnected();
    bool    TwoConnected();

    enum    TRetDFS {
                DFS_DISCONNECTED = 0,
                DFS_BICONNECTED = 1,
                DFS_MULTIPLE_BLOCKS = 2,
                DFS_ALMOST_BICONNECTED = 3
            };

    bool    CutNodes(TArc = NoArc,
                TNode* = NULL,TArc* = NULL);
    bool    STNumbering(TArc = NoArc,
                TNode = NoNode,TNode = NoNode);
}
\end{verbatim}
\end{quote}

\subsection{First Order Connectivity}
The DFS method \verb/Connected()/ decides whether a graph is connected or
not, and returns 1 or 0 respectively. In the latter case, the connected
components are available by the node colour data structure. The running
time is $O(m)$.

Note that the Kruskal algorithm also applies to this problem but returns the
connected components by the node partition data structure.


\subsection{Strong Connectivity}
Two nodes $x$, $y$ of a graph are {\bf strongly connected}
\index{strongly connected node pair} if there are
an eligible $xy$-path and an eligible $yx$-path. A \nt{strong component}
is a maximal node set such that each pair of nodes is strongly connected.

The method \verb/StronglyConnected()/ decides whether a graph is strongly
connected or not, and returns 1 or 0 respectively. In the latter case, the
strong components are available by the node colour data structure. The running
time is $O(m)$.


\subsection{Second Order Connectivity}
A \nt{cut node} [\nt{bridge}] of a graph is a node [arc] whose deletion increases
the number of connected components. A \nt{block} is a maximal edge set such that each
spanned pair of nodes is traversed by a simple cycle. A \nt{$2$-edge connected component}
is a maximal node set such that the induced subgraph contains no bridges.

The method \verb/CutNodes()/ checks if the graph has cut nodes. In that case,
the cut nodes are represented by the nodes coloured $0$. The remaining nodes
are coloured block by block. The edge colour register also represents the blocks,
and node and edge colours match each other.

The return value is a \verb/TRetDFS/
enum value. While \verb/DFS_DISCONNECTED/ and \verb/DFS_BICONNECTED/ do not
need any explanations, it is worth to note that \verb/DFS_ALMOST_BICONNECTED/
is returned only if a root arc $st$ is specified, if the blocks form a linear chain,
if $st$ is in an extremal block, and if $s$ is not a cut node.

For the described 2-connectivity application, no parameters need to be passed
to \verb/CutNodes()/. More generally, the method performs a DFS search and
saves the search tree arcs by the predecessor register. Passing a root arc $st$
means to fix the first tree arc. If $s$ is not a cut node, $st$ will be the
only tree arc emanating from $s$.

The method \verb/TwoConnected()/ checks if the graph is $2$-edge connected.
It calls \verb/CutNodes()/ with some extra data structures, maintains the edge
colours which still represent the blocks, and determines node colours which represent
the $2$-edge connectivity components. For both procedures, the running time is
$O(m)$.

\bigskip
\begin{figurehere}
\begin{center}
\epsfxsize=11cm
\epsfbox{connect2.eps}
\vspace{0.5cm}
\caption{\label{flb_connect2}Blocks and 2-Edge Connectivity}
\end{center}
\end{figurehere}


\subsection{Open Ear Decomposition and st-Numbering}
An \nt{ear decomposition} partitions the edge set into simple paths
$P_1,P_2,\dots,P_k$ such that both end nodes of $P_{i+1}$, $i>1$ occur on
$P_1,P_2,\dots,P_i$ but the intermediate nodes do not. Ear decompositions are
stored as edge colours. If no cycles occur among $P_1,P_2,\dots,P_k$, the ear
decomposition is called an \nt{open ear decomposition}.

For given nodes $s$ and $t$, an \nt{$st$-numbering} or \nt{bipolar numbering}
is an assignment to the node colours with \verb/colour[s] = 0/,
\verb/colour[t] = n-1/ and such that for every other node $v$, two neighbors
$u$ and $w$ with
\begin{verbatim}
    colour[u] < colour[v] < colour[w]
\end{verbatim}
exist. If $s$ and $t$ denote the end nodes of the path $P_1$ in an open ear
decomposition, one can obtain an $st$-numbering by inserting the nodes of each
path in the order of appearance, right after the start node of the path.

The call \verb/STNumbering(a,s,t)/ computes a bipolar numbering (delivered by
the node colours) and an open ear decomposition (delivered by the edge colours)
from a DFS tree which stems from \verb/CutNodes()/.

It is either possible to specify a root arc $a=st$ or to specify two nodes $s$
and $t$. If $a$ is passed, the graph must be 2-connected. Otherwise, adding the
edge $st$ must make the graph 2-connected.


\vfill
\markright{PLANARITY}
\section{Planarity}
\label{slb_planarity}
\methods
\begin{quote}
\begin{verbatim}
class abstractMixedGraph
{
private:
    bool    PlanarityDMP64(TArc*);
    bool    PlanarityHopcroftTarjan(TArc* predArc,
                bool extractMinor);

public:
    enum TMethPlanarity {
        PLANAR_DEFAULT   = -1,
        PLANAR_HO_TA     =  0,
        PLANAR_DMP       =  1
    };

    enum TOptPlanarity {
        PLANAR_NO_OPT    =  0,
        PLANAR_MINOR     =  1
    };

    void    PlanarizeIncidenceOrder();
    bool    IsPlanar(TMethPlanarity method = PLANAR_DEFAULT,
                TOptPlanarity options = PLANAR_MINOR);
    TNode   LMCOrderedPartition(TArc*,TArc*,TNode*)
    void    GrowExteriorFace();
    void    PlanarConnectivityAugmentation();
    void    PlanarBiconnectivityAugmentation();
    void    Triangulation();

    enum    TOptSeriesParallel {
                ESP_UNDIRECTED = 0,
                ESP_DIRECTED   = 1,
                ESP_EMBEDDING  = 2,
                ESP_ORIENT     = 4,
                ESP_VISIBILITY = 8
            };

    abstractMixedGraph*
            SeriesParallelDecompositionTree(
                TOptSeriesParallel = ESP_DIRECTED,
                TNode = NoNode,TNode = NoNode);
    bool    EdgeSeriesParallelMethod(
                TOptSeriesParallel = ESP_EMBEDDING,
                TNode = NoNode,TNode = NoNode,
                abstractMixedGraph* = NULL);
}
\end{verbatim}
\end{quote}
A \nt{planar graph} is a graph which can be drawn in the plane without any
edge crossings. Many optimization problems admit special solvers for planar
graphs which perform much better than the general codes (see the max-cut
section for an example). Usually, it is not necessary to know an explicit
drawing.

The method \verb/IsPlanar()/ is the general entry point for planarity tests.
It checks if the graph is planar but does not export a representation.
The pure planarity test is implemented for general graph objects.
Explicit planarization is restricted to sparse graph objects which are stored
by incidence lists.


\subsection{The Method of Demoucron, Malgrange and Pertuiset}
The implemented planarity test \verb/PlanarityDMP64()/ first adds some arcs
to obtain a 2-connected graph. Then an initial cycle and two regions are
generated. The remaining graph arcs are partitioned into \nt{segments}. In the
main loop of the algorithm, a segment is determined which can be embedded into
a minimum number of regions. From this segment, an arbitrary path is embedded
into some feasible region and this region is split.
All loops and parallel arcs are embedded in a post processing step to prevent
from computational overhead.
The running time of this method is $O(m^3)$ and, by that, $O(n^3)$ for planar
graphs.

Currently, the required storage can be bounded only by $O(nm)$. If the input
graph is non-planar, no forbidden configuration is exported yet.


\subsection{The Method of Hopcraft and Tarjan}
This planarity test \verb/PlanarityHopcroftTarjan()/ uses two depth first
searches to determinate if a graph is planar. The first one calculates an arc
partition of the original graph, which is called \nt{path tree}. The second one
traverses the path tree. By examinating parts of the path tree step by step,
it tests, if the current subgraph is planar, and at the end, if the whole
graph is planar.
The running time and the required storage of this method is $O(m)$ and, by
that, $O(n)$ for planar graphs.

In the case of a planar input graph, a combinatorial representation can be
calculated in $O(n)$.

If the input graph is non-planar, a forbidden configuration ($K_{3,3}$ or
$K_5$) can be exported by setting argument \verb/options/ to
\verb/PLANAR_MINOR/ (default setting).


\subsection{Combinatorial Representation}
For sparse graph objects, the method \verb/PlanarizeIncidenceOrder()/ calls the
planarity test and then exports a \nt{combinatorial representation} to the node
incidences: To this end, the method \verb/ReorderIncidences()/
is called which actually orders the incidence lists. It takes an array which
specifies the predecessor of each arc when traversing the regions.
This array must be filled by any prospective planarization method.


\subsection{Outerplanar Representation}
An \nt{outerplanar graph} is a graph which can be drawn in the plane without
edge crossings and such that all nodes are incident with the unbounded region
to which we refer as the \nt{exterior face}.

The method \verb/GrowExteriorFace()/ requires a combinatorial representation and
selects from this representation a region with the maximum number of adjacent nodes.
Then, all exterior \nt{cut edges} (whose end nodes form cutting pairs and which
are no bridges) swapped to the interior. By that, the number of external nodes
strictly increases. The running time is bounded by $O(n^2)$.

If the input graph is (implicitly) outerplanar, a respective combinatorial
representation results. But even in the case of general planar graphs, more
appealing layouts can be achieved with this procedure. Furthermore, one can
determine $st$-numberings with both $v_1 v_2$ and $v_1 v_n$ on the exterior
face of the refined representation.

The procedure also applies if the input graph is disconnected. It is only a
wrapper around the call \verb/ExtractEmbedding(PLANEXT_GROW)/. See section
\ref{slb_planarity1} for more details.


\subsection{Edge Series Parallel Graphs}
\label{slb_series_parallel}
A graph is called \nt{edge series parallel} if it can be reduced to a
single arc, only using the following operations:
\begin{itemize}
\item Parallel rule: Replace two parallel arcs by a single arc
\item Serial Rule: Replace a degree-two node and the incident arcs by a single arc
\end{itemize}
It is convenient to represent the reduction process by a so-called
\nt{decomposition tree}: The leave nodes of this tree are the arcs of the
original graph, and the other nodes represent the reduction steps.
Decomposition trees are all but unique. In the undirected setting,
not even the final arc is unique.

Calling \verb/SeriesParallelDecompositionTree(options,s,t)/ checks
if the graph can be entirely decomposed, occasionally returns a
binary decomposition tree, and returns \verb/NULL/ otherwise. If the
\verb/ESP_DIRECTED/ bit is not set in \verb/options/, the arc orientations
are ignored. If one specifies node indices $s$ and $t$, these nodes are not
canceled by serial reduction steps, that is, the root arc is $st$. The
running time of the method is $O(m)$.

All further codes for edge series parallel graphs can be accessed by
calling \verb/EdgeSeriesParallelMethod(options,s,t,T)/. If \verb/T != NULL/,
this pointer passes a decomposition tree to operate with. Otherwise, a tree
is computed internally (but not exported), and $s$ and $t$ apply as before.
The possible operations can be combined arbitrarily, and are specified by
the bit field \verb/options/. The used bits are as follows:
\begin{itemize}
\item \verb/ESP_VISIBILITY/: Draw the graph in the 1-visibility model
\item \verb/ESP_EMBEDDING/: Reorder the node incidence lists according to the
    decomposition tree. In particular, a planar representation results
\item \verb/ESP_ORIENT/: Orient the arcs according to the decomposition tree.
    In particular, an $st$-orientation results
\item \verb/ESP_DIRECTED/: If a decomposition tree is generated, the arc
    orientations are ignored in that initial phase
\item \verb/ESP_MINOR/: If the graph is not series-parallel (if the decomposition
    tree is incomplete), a forbidden minor is exported by the edge colours
\end{itemize}
The overall running time is $O(m)$.

\subsection{Connectivity Augmentation}
Most planar graph drawing algorithms require a certain level of connectivity of
the input graph. One can link the connected components of a planely represented
graph arbitrarily without corrupting the combinatorial representation. Even more,
if the connected components are linked tree like, this gives a minimal
connected planar supergraph in linear time. The only advanced feature of the
procedure \verb/PlanarConnectivityAugmentation()/ is that it selects a maximal
exterior face of each component. This procedure is a wrapper around the call
\verb/ExtractEmbedding(PLANEXT_CONNECT)/ and runs in linear time.

Things are more complicated with the biconnectivity and triconnectivity
augmentation problems. One can compute in polynomial time minimal biconnected
and triconnected supergraphs but these are, in general, not planar. The planar
versions of these problems are NP-hard.

GOBLIN includes a procedure \verb/PlanarBiconnectivityAugmentation()/ which
computes a (probably not minimal) planar biconnected supergraph in linear time.
The restriction to the original graph gives the original combinatorial
representation. The input graph must be connected.

There is also a procedure \verb/Triangulation()/ to compute a maximum planar
supergraph of the adressed graph object. Such graphs are always triconnected
and called \nt{triangulations} since all faces form triangles. 
As before, the restriction to the original graph gives the original representation.
The time complexity is $O(m)$ up to the lookup of node adjacencies. The input
graph must be biconnected.

All procedures modify the incidence structure of the original graph!


\subsection{Canonically Ordered Partition}
The \nt{canonically ordered partition} splits a simple triconnected planar
graph $G$ into components which can be inserted one by one into a partial plane
drawing. This structure applies to convex as well as orthogonal drawing methods.
In some sense, it is the triconnectivity analogon of ear decompositions and
$st$-numberings discussed earlier. More explicitly, the discussed partition
consists of disjoint node sets $X_1,X_2,\dots,X_k$ such that
$V(G)=\bigcup_{i=1}^k X_i$ and
\begin{itemize}
\item $X_1 = \{v_1,v_2\}$, $v_1$ and $v_2$ are neighbors on the exterior
    face of $G$ and $v_1 v_2$ is called the \nt{basis arc}.
\item The induced subgraph $G_j$ of $G$ to $\bigcup_{i=1}^j X_i$ is biconnected
    and \nt{internally triconnected} for every $j=2,\dots,k$. That is, deleting
    two interior nodes preserves connectivity.
\item For $j=1,\dots,k$, all nodes in $X_j$ are exterior with respect to $G_j$.
\item For $j=2,\dots,k-1$, the component $X_j$ is adjacent to
    $\bigcup_{i=j+1}^k X_i$ and has at least two \nt{contact nodes} in $G_{j-1}$.
\item For $j=2,\dots,k-1$, the component $X_j$ is either a single node or a path
    $v_{r_1},v_{r_2},\dots,v_{r_s}$ with exactly two contact nodes, one adjacent
    to $v_{r_1}$ and the other adjacent to $v_{r_s}$.
\item $X_k = \{v_n\}$ consists of a single node.
\end{itemize}
Provided that the original graph is simple, triconnected and combinatorially
embedded (not just implicitly planar), the call
\begin{quote}
\begin{verbatim}
TNode k = LMCOrderedPartition(aLeft,aRight,vRight);
\end{verbatim}
\end{quote}
returns the following information:
\begin{itemize}
\item The number $k$ of components.
\item The components by the node colours where \verb/Colour(v)/ is the index of
    the component of $v$, $i\in\{0,1,\dots,k-1\}$.
\item The components by the array \verb/vRight/ where \verb/vRight[v]/ is the
    right-hand neighbor of the node $v$ in its component or \verb/NoNode/ if
    $v$ is right-most.
\item The left-most contact arc \verb/aLeft[i]/ directed to the component $i$.
\item The right-most contact arc \verb/aRight[i]/ directed from the component
    $i$.
\item If no exterior face and basis arc have been defined in advance, both
    data are computed and stored internally. See Section \ref{slb_planarity1}
    for details about the data structures.
\end{itemize}
The running time is $O(m)$. We only mention that the procedure computes the
left-most canonical ordered partition and refer to the literature for the
mathematical details.



\markright{MAXIMUM FLOWS AND CIRCULATIONS}
\section{Maximum Flows and Circulations}
\label{slb_solve_maxflow}
\methods
\begin{quote}
\begin{verbatim}
class abstractMixedGraph
{
    enum TMethMXF {
        MXF_DEFAULT = -1,
        MXF_SAP = 0,
        MXF_DINIC = 1,
        MXF_PREFLOW_FIFO = 2,
        MXF_PREFLOW_HIGH = 3,
        MXF_PREFLOW_SCALE = 4,
        MXF_SAP_SCALE = 5
    };

    TFloat  MaxFlow(TNode,TNode);
    TFloat  MaxFlow(TMethMXF,TNode,TNode);
}

class abstractDiGraph
{
    TFloat  MXF_EdmondsKarp(TNode,TNode);
    TFloat  MXF_CapacityScaling(TNode,TNode);
    TFloat  MXF_GoldbergTarjan(TNode,TNode);
    TFloat  MXF_Dinic(TNode,TNode);

    bool    AdmissibleCirculation();
}
\end{verbatim}
\end{quote}
An $st$-flow in a directed graph is a subgraph such that every node $v\neq s,t$
is {\bf balanced}\index{node!balanced} (\verb/Divergence(v)==Demand(v)/).
A {\bf maximum}\index{$st$-flow!maximum} $st$-flow is an $st$-flow such that
\verb/Divergence(s)/, the \nt{flow value}, is maximal. There is a generic
problem solver \verb/MaxFlow()/ which is either called with a \verb/TMethMXF/
enum value or applies a particular method depending on the value of the context
variable \verb/methMXF/. If the context flag \verb/methFailSave/ is enabled,
a reduced costs optimality criterion is checked, that is, a minimum cut is
computed. All methods return the maximum flow value.

\bigskip
\begin{figurehere}
\begin{center}
\epsfxsize=11cm
\epsfbox{eps/maxFlow.eps}
\vspace{0.5cm}
\caption{\label{flb_maxflow}A Maximum Flow Problem}
\end{center}
\end{figurehere}

All max-flow methods have to be started with a feasible $st$-flow. Supposed
that all lower bound are zero, one can start the solver with the zero flow.
If you have already compute an $st$-flow and you have only increased some
capacity or inserted a new arc, no special initialization of the flow labels
is required. But if the source or target node have changed, you have to start
with the zero flow again. If the lower bounds are non-trivial, you either need
a feasible $st$-flow or you can fix the desired flow value by setting the
demands of the root and the target node, and then search for an admissible
$b$-flow instead.


\subsection{Application to Undirected Graphs}
When the \verb/MaxFlow()/ solver is called for an undirected or a mixed graph,
the optimization method is applied to its complete orientation: In this digraph,
all undirected edges are replaced by antiparallel arc pairs. The arc capacities
and length labels, and the node demands are inherited from the original graph.

Mapping back flow to undirected edges means taking the difference of flow values
in the digraph. For this reason, it is required that the lower capacity bounds
are all zero.


\subsection{The Augmentation Algorithm by Edmonds and Karp}
This is the basic max-flow algorithm which depends on the search method
\verb/BFS()/. The used data structures are the subgraph, the predecessor
labels and the distance labels which determine a corresponding minimum cut
eventually. The method runs in $O(nm^2)$ computing steps.


\subsection{The Capacity Scaling Algorithm}
The method \verb/MXF_CapacityScaling()/ splits the balanced augmentation algorithm
into scaling phases. In the \verb/delta/-phase, only the arcs with
\verb/ResCap(a)>delta/ are eligible. The parameter \verb/delta/ is
initialized to the maximum capacity, and divided by $2$ if no more
augmenting paths can be found in this scaling phase. The resulting time bound
is $O(m^2\log{U})$ where $U:=\max_{a=0}^{m-1}ucap(a)$.


\subsection{The Blocking Flow Algorithm by Dinic}
This method heavily depends on the class \verb/layeredAuxNetwork/ which is
described in Section \ref{slb232}. In contrast to the augmentation algorithm,
the Dinic method does not compute the distance and predecessor labels before
every augmentation step, but grows an acyclic incidence structure to perform a
couple of augmentations. 

The method runs in $O(n^2m)$ computing steps which is inferior to the push and
relabel algorithm, but performs better in many practical situations. At least
in the case where all arc capacities are one, the Dinic method is the most
efficient and robust of the max-flow algorithms implemented.


\subsection{The Push \& Relabel Algorithm by Goldberg and Tarjan}
This method iteratively chooses an {\bf active}
\index{push and relabel method!active node} node, that is a node $v$ which
has \verb/Divergence(v)>Demand(v)/. This node can either be relabeled so that
the distance label increases, or a certain amount of flow is pushed to an
appropriate neighbour of $v$.

The procedure \verb/MXF_GoldbergTarjan()/ supports three different strategies:
\begin{itemize}
\item If \verb/methMXF==MXF_PREFLOW_FIFO/, active nodes are selected by a FIFO strategy
    and an $O(n^3)$ algorithm results.
\item If \verb/methMXF==MXF_PREFLOW_SCALE/, the set of active nodes is restricted to nodes
    whose flow excess exeeds a lower bound. This bound is decreased everytime
    when no more active nodes exist. This strategy is known as
    \nt{excess scaling}. The running time is bounded by $O(nm+n^2\log{U})$.
\item Otherwise, the active nodes are stored on a priority queue, and the
    priority of a node increases with its distance label. Here, the context
    variable \verb/methPQ/ determines the used PQ data structure, and the best
    possible complexity bound is $O(n^2\sqrt{m})$.
\end{itemize}
In either case, several push operations from a selected active node are
performed and, if no further push is possible, the node is relabelled
immediately.

We have experienced that the push \& relabel technique can be even more
efficient than blocking flow algorithms, but only if no flow has to be pushed
back to the source node. In odd cases, not even a percent of the running time
is needed to send the maximum flow to the sink node.


\subsection{Admissible Circulations and $b$-Flows}
An \nt{$b$-flow} of a flow-network is a pseudo-flow such that all nodes are
balanced. In the special situation where all node demands are zero,
the $b$-flows are also called {\bf circulations}\index{circulation}.

The method \verb/AdmissibleCirculation()/ decides whether an admissible
$b$-flow exists or not. This is achieved by using the class \verb/FNW2FNW/
which is described in Section \ref{slb231}, and the generic solver method
\verb/MaxFlow()/. Since the parameters $n$, $m$ and $U$ grow only by a
constant factor during the problem transformation, the complexity bounds are
the same as for the used max-flow methods.


\subsection{Proposed Extension}
The MKM blocking flow algorithm.


\markright{MINIMUM CUTS AND CONNECTIVITY NUMBERS}
\section{Minimum Cuts and Connectivity Numbers}
\label{slb_solve_mincut}
\methods
\begin{quote}
\begin{verbatim}
class abstractMixedGraph
{
    virtual bool    Connected(TCap);
    virtual bool    EdgeConnected(TCap);
    virtual bool    StronglyConnected(TCap);
    virtual bool    StronglyEdgeConnected(TCap);

    TCap            Connectivity();
    TCap            EdgeConnectivity();
    virtual TCap    StrongConnectivity();
    virtual TCap    StrongEdgeConnectivity();

    virtual TFloat  StrongEdgeConnectivity(TNode);
    virtual TFloat  StrongEdgeConnectivity(TNode,TNode);

    TCap            MinCutLegalOrdering(TNode,TNode&,TNode&);
    TCap            MinCutNodeIdentification();
}

class abstractDiGraph
{
    TCap            MinCutHaoOrlin(TNode);
}
\end{verbatim}
\end{quote}
The \nt{vertex connectivity number} is the minimum number of nodes which
must be removed from the graph so that some nodes become disconnected.
Correspondingly, the \nt{edge connectivity number} is the minimum number of
edges which must be removed so that two nodes become disconnected.
The strong counterparts require that all connecting paths are eligible.

\begin{tablehere}
\begin{center}
\vspace*{1cm}
\begin{tabular}{|l|l|l|}
\hline
\verb/methMinCut/   & 0 & Iterated Max-Flows \\
                    & 1 & Push/Relabel, FIFO \\
                    & {\bf 2} & Push/Relabel, Highest Order \\
                    & 3 & Node Identification \\
\hline
\end{tabular}
\end{center}
\caption{\label{tlb_mincut}Minimum Cut Solver Options}
\end{tablehere}

\noindent
In GOBLIN, there are two sets of methods which check for graph connectivity
and which are listed above. The methods of the first series take the desired
connectivity order $k$ as an input parameter and check if the graph actually
is $k$-connected. If $k$ is small, one of the basic methods described in
Section \ref{slb_components} is used. For (strong) edge connectivity of higher
order, the connected components are determined by computing minimum cuts on
the subgraph induced by a single colour and splitting the node set with respect
to this cut. This requires the solution of $O(n^2)$ max-flow problems.
For vertex connectivity of higher order, merely the method \verb/Connectivity()/
respectively \verb/StrongConnectivity()/ are called since connected components
are immaterial here.

The methods of the second series compute a minimum cut and return the cut
capacity. The cut is returned by the node colours where the colours of edge
cuts are 0-1, and cut edge are directed from colour 1 to colour 0. Node cuts
are coloured 0 and directed from the nodes with colour 1 to the nodes with
colour 2.

\bigskip
\begin{figurehere}
\begin{center}
\epsfxsize=10cm
\epsfbox{connect3.eps}
\vspace{0.5cm}
\caption{\label{flb_connect3}Edge Connected Components of Order 3}
\end{center}
\end{figurehere}

\noindent
Note that the methods \verb/Connectivity()/ and \verb/StrongConnectivity()/
utilize node splittings which were described in Section \ref{slb_node_splitting}
and essentially solve $O(n^2)$ max-flow problems. Since the node demands in the
original graph map to arc capacities in the node splitting, the vertex
connectivity methods observe \nt{node capacities}. In order to compute vertex
connectivity in the traditional sense, one must set all node demands to 1.

\bigskip
\begin{figurehere}
\begin{center}
\epsfxsize=6.5cm
\epsfbox{mincut2.eps}
\vspace{0.5cm}
\caption{\label{flb_mincut1}A Legal Ordering}
\end{center}
\end{figurehere}

\noindent
If \verb/methMinCut==0/ is configured, each of the three edge connectivity
methods solves $O(n)$ max-flow problems. If \verb/StrongEdgeConnectivity(TNode)/
or \verb/EdgeConnectivity()/ is called with \verb/methMinCut>0/, a modified
version of the push and relabel method \verb/MinCutHaoOrlin()/ is called which
has the same worst-case time complexity as the original max-flow algorithm.
To our experience, the highest order implementation performs much better than
the FIFO version and the iterated max-flow strategy.

The method \verb/EdgeConnectivity()/ which works for the global min-cut problem
supports a further algorithm: The method \verb/MinCutNodeIdentification()/ can
be called which iteratively chooses a pair $x$, $y$ of nodes, determines a minimum $(x,y)$-cut and then identifies the
nodes $x$ and $y$. These nodes and the $(x,y)$-cut capacity are supplied by
\verb/MinCutLegalOrdering(r,x,y)/ where $r$ is an arbitrary root of search.
The search for a legal ordering is very similar to the Dijkstra and the
enhanced Prim algorithm and hence runs in $O(n^2)$, $O(m\log{n})$ or in
$O(m+n\log{n})$ time depending on the setting of \verb/methPQ/. In practice,
the node identification method performs much worse than the push/relabel method.


\markright{MINIMUM COST FLOWS}
\section{Minimum Cost Flows}
\label{slb_solve_mcflow}
\methods
\begin{quote}
\begin{verbatim}
class abstractMixedGraph
{
    enum        TMethMCFST {
                    MCF_ST_DEFAULT = -1,
                    MCF_ST_DIJKSTRA = 0,
                    MCF_ST_SAP = 1,
                    MCF_ST_BFLOW = 2
                };

    TFloat      MinCostSTFlow(TNode,TNode,TMethMCFST);

    enum        TMethMCF {
                    MCF_BF_DEFAULT = -1,
                    MCF_BF_CYCLE = 0,
                    MCF_BF_COST = 1,
                    MCF_BF_TIGHT = 2,
                    MCF_BF_MEAN = 3,
                    MCF_BF_SAP = 4,
                    MCF_BF_SIMPLEX = 5,
                    MCF_BF_LINEAR = 6,
                    MCF_BF_CAPA = 7
                };

    TFloat      MinCostBFlow(TMethMCF);
}

class abstractDiGraph
{
    TFloat      MCF_BusackerGowen(TNode,TNode);
    TFloat      MCF_EdmondsKarp(TNode,TNode);

    TFloat      MCF_CycleCanceling();
    TFloat      MCF_MinMeanCycleCanceling();
    TFloat      MCF_CostScaling(TMethMCF);
    TFloat      MCF_ShortestAugmentingPath();
    TFloat      MCF_CapacityScaling();

    TFloat      MCF_NWSimplex();
    void        MCF_NWSimplexCancelFree();
    void        MCF_NWSimplexStrongTree();
}
\end{verbatim}
\end{quote}
Two formulations of the min-cost flow problem are supported: $st$-flows and
$b$-flows. All algorithms are accessed by the respective entry methods
\verb/MinCostSTFlow()/ and \verb/MinCostBFlow()/.

An {\bf $st$-flow}\index{$st$-flow} is a pseudoflow such that all nodes are
balanced, up to a fixed pair $s$, $t$ of nodes, and the imbalance at node $t$
is called the {\bf value}\index{value!$st$-flow} of this flow.
An {\bf extreme}\index{$st$-flow!extreme} or {\bf ($\nu$)-optimal}
\index{$st$-flow!($\nu$)-optimal} $st$-flow is an $st$-flow which is optimal
among all $st$-flows with the same value $\nu$.

When calling the first solver, \verb/MinCostSTFlow(s,t)/, a series of
($\nu$)-optimal $st$-flows is computed, and the flow value $\nu$ is strictly
increasing. This process halts when either a maximum flow has been determined or
if the sink node $t$ becomes balanced. This scheme is usually known as the
{\bf shortest augmenting path (SAP)} \index{SAP algorithm} algorithm, referring
to the fact that every intermediary extreme flow differs from its predecessor
by a shortest augmenting path.

It is required that the input flow is also an extreme $st$-flow. In many
situations, one can call the solver with the zero-flow which is ($0$)-optimal
if the length labels are non-negative. The zero flow is admissible also for
negative edge lengths if the digraph is acyclic. If node potentials are not
already present, the solver is smart enough to compute a compatible dual
solution before starting with augmentations.

The second solver, \verb/MinCostBFlow()/, determines {\bf $b$-flows}\index{$b$-flow}
(in which all node imbalances match the given node demand vector $b$) of
minimum costs. This includes the special case of \nt{circulations} where the
node demands are zero. The applied method can either be
{\bf primal}\index{primal algorithms}, that is, it starts with determining an
arbitrary feasible $b$-flow. This solution is improved iteratively, and stays
feasible throughout the computation.

Or the solver applies an SAP like algorithm to the $b$-flow problem with the
slight difference to the $st$-flow solver that multiple terminal nodes occur.
This stems from the fact that only complementary slackness but not primal
feasibility is maintained, and that all supersaturated nodes are sources when
searching for shortest augmenting paths.

The general drawback of SAP methods is that the running time complexity is
polynomial only if the number of augmentations can be bounded polynomially.
When optimizing from scratch, this is true for the capacity scaling method only.

The generic solver methods \verb/MinCostSTFlow()/ and \verb/MinCostBFlow()/
accept optional parameters in order to specify a particular algorithm.
If these parameter are omitted, the context variables \verb/methMCFST/ and
\verb/methMCF/ apply. The possible values match the symbolic enum values
which are listed above.

In all possible configurations, the solvers check if the node demamds sum up
to zero, and raise an \verb/ERRejected/ exception otherwise. If the problem is
infeasible for other reasons, \verb/InfFloat/ is returned. All methods preserve
optimal flows as far as possible. As an exception, starting $b$-flow SAP codes
with an optimal $b$-flow but with suboptimal node potentials may lead to a
different final flow.


\subsection{The SAP Algorithm by Busacker and Gowen}
This method iteratively computes shortest paths using the generic method
\verb/ShortestPath()/, and augments on these paths. The running time is
$O(\nu mn)$. The code is not for practical computations, but rather for
comparison with the refined method which is discussed next.


\subsection{The Refined SAP Algorithm by Edmonds and Karp}
This method depends on the Dijkstra shortest path algorithm and on the reduced
length labels. The running time is $O(\nu(m+n\log{n}))$. This method is of
practical importance, since it solves the assignment problem in $O(n(m+n\log{n}))$
computing steps and can produce a near-optimal solution for the general
$1$-matching problem in the same order of complexity.

The method may be called with an $st$-flow and with node potentials such that
the residual network contains negative length arcs. In that case, a label
setting shortest path method is called, and the node potentials are corrected.
Doing so, it may turn out that the input flow is not extreme. In that case, an
\verb/ERRejected/ exception is raised.


\bigskip
\begin{figurehere}
\begin{center}
\epsfxsize=8cm
\epsfbox{optcirc4.eps}
\vspace{0.5cm}
\caption{\label{flb_minmean}A Minimum Mean Cycle}
\end{center}
\end{figurehere}


\subsection{The Cycle Canceling Algorithm by Klein}
This is the very basic primal min-cost flow method. It iteratively searches for
negative length cycles and augments on these cycles. Consult Section
\ref{slb620} for information on the method \verb/NegativeCycle()/ which
is applied. If no negative length cycle exists, the circulation is optimal,
and the procedure halts.

The procedure is non-polynomial and also performs very badly in practice. It
is only useful for post-optimization and educational purposes.


\subsection{The Minimum Mean Cycle Canceling Algorithm}
This is a strongly polynomial specialization of the cycle canceling method
where all augmenting cycles are minimum mean cycles. The running time is
$O(n^2m^3\log{n})$ and $O(n^2m\log{(nC)})$ where
$C:=\max_{i=0}^{m-1}\{length(a)\}$.
The major drawback is the fact that the procedure requires $\Theta(n^2)$
units of storage. In our experience, it is also too slow to solve practical
min-cost flow problems.


\subsection{The Cost Scaling Algorithm}
An {\bf $\epsilon$-optimal}\index{$b$-flow!$\epsilon$-optimal} $b$-flow is a
$b$-flow such that one can find node potentials with
\verb/RedLength(a)>=-epsilon/ for every arc
which satisfies \verb/ResCap(a)>0/. A $b$-flow is {\bf $\epsilon$-tight}
\index{$b$-flow!$\epsilon$-optimal} if it is $\epsilon$-optimal, but it is not
$\delta$-optimal for any $\delta<\epsilon$.

The cost scaling algorithm iteratively transforms a $2\epsilon$-optimal
$b$-flow and compliant node potentials into an $\epsilon$-optimal
$b$-flow and a corresponding set of potentials.

During such a scaling phase, the method manipulates an $\epsilon$-optimal
pseudo-flow rather than a $b$-flow. It performs push and relabel operations
similar to the non-weighted algorithm until every node is balanced.

The running time is $O(n^3\log(nC))$ for the basic version without
$epsilon$-tightening. If tightening operations are enabled (depending on the
value of \verb/methMCF/, the method \verb/MinimumMeanCycle()/ is called to
check for optimality after each scaling phase, and the running time is
$O(mn^3\log{n})$. Each of the tightening steps derives potentials for which
the $b$-flow is $epsilon$-tight. It can been experienced that the method
performs much better without applying \verb/MinimumMeanCycle()/.


\subsection{The Multi Terminal SAP Method}
The SAP algorithm starts with sending flow on all arcs which have residual
capacity but the reduced length is negative. After that operation, the
complementary slackness condition is satisfied, but many nodes are unbalanced.
So the remainder of the procedure is sending flow on shortest paths in the
residual network and updating the node potentials correspondingly.

Only a non-polynomial complexity order $O(m\;U(m+n\log{n}))$ for the running
times is achieved here, but the method performs well in practice. In particular,
it is well-suited for post-optimization.


\subsection{The Capacity Scaling Method}
The capacity scaling method \verb/MCF_CapacityScaling()/ is a variant of this
SAP method which limitates the number of augmentation steps by choosing
augmenting paths with sufficiently high capacity.

The running time is bounded by $O(m\log(U)(m+n\log{n}))$ but, frankly, can be
achieved only for graphs which have infinite capacity paths between each pair
of nodes. Practically, the capacity scaling method performs slightly better
than the cost scaling method.


\subsection{The Primal Network Simplex Method}
The network simplex method can be considered an adaption of the general simplex
method to network flows but also a clever specialization of the Klein cycle
canceling algorithm. In order to generate negative cycles, the network simplex
method maintains node potentials and a spanning tree which entirely consists of
arcs with zero reduced length.

\bigskip
\begin{figurehere}
\begin{center}
\epsfxsize=13cm
\epsfbox{nwsimplex.eps}
\vspace{0.5cm}
\caption{\label{flb_nwsimplex}A Strongly Feasible Spanning Tree}
\end{center}
\end{figurehere}

\noindent
Every arc not in the tree which has negative reduced length can be extended
by tree arcs to a cycle with negative length. One selects such a \nt{pivot arc}
with positive residual capacity, but even then it is impossible to guarantee
that the \nt{pivot cycle} has residual capacity different from zero. Such
\nt{degenerate pivot steps} do not affect the flows but change the node
potentials and the spanning tree structure. To fix up the problems with
degeneracy, one uses \nt{strongly feasible spanning tree structures} where
every arc can send flow up the tree and the leaving arc on the pivot cycle
is chosen carefully.

In our implementation, connectivity is neither required for the input graph
nor forced by a problem transformation. The method must start with a feasible
$b$-flow. In a first step, a procedure \verb/NWSimplexCancelFree()/
transforms the initial $b$-flow into a \nt{cycle free solution} by a depth
first search strategy in $O(m^2)$ time. Then \verb/NWSimplexStrongTree()/
computes a strongly feasible spanning tree structure from any given cycle
free $b$-flow in $O(m\;n)$ time.

The main functionality is located in a separate class \verb/networkSimplex/,
especially the management of spanning tree indices and the data structures
which are needed for the pricing step. The initilization phase ends by calls
to methods \verb/InitThreadIndex()/ and \verb/ComputePotentials()/ of this
class which take $O(n)$ steps together. If the network simplex method is
started with a cycle free solution, the neccesary data are reconstructed
without modifying the $b$-flow!

The cyclic part consists of alternating calls to \verb/PivotArc()/
and \verb/PivotOperation()/. The pivot arc determination takes $O(m)$
steps and the pivot step $O(n)$ steps. The practical perfomance depends
on a good \nt{pricing rule} which is fixed by the context parameter
\verb/methNetworkPricing/. All possible rules are based on the idea of
choosing the arc with the most negative reduced length for pivoting.
By the \nt{Dantzig rule}, all arcs are considered. By the \nt{partial pricing}
and the \nt{multiple partial pricing} rules, only a few arcs are considered.
The extreme case is the {first eligible arc rule} where only one admissible
pivot arc is generated.

The network simplex code performs much better than the cost scaling method
up to the case where Dantzigs rule is applied. The other rules show a similar
performance and partial pricing performs best of all methods.



\begin{tablehere}
\begin{center}
\vspace*{1cm}
\begin{tabular}{|l|l|l|}
\hline
\verb/methMCFST/    & {\bf 0} & Revised shortest path \\
                    & 1 & Shortest path \\
                    & 2 & Transformation to b-flows \\
\hline
\verb/methMCF/      & 0 & Klein (cycle canceling) \\
                    & 1 & Cost scaling \\
                    & 2 & Cost scaling with $\epsilon$-tightening \\
                    & 3 & Minimum mean cycle canceling \\
                    & 4 & Shortest Augmenting Path \\
                    & {\bf 5} & Primal network simplex \\
                    & 6 & Reduction to linear program \\
                    & 7 & Capacity scaling \\
\hline
\verb/methNetworkPricing/
                    & {\bf 0} & Partial pricing \\
                    & 1 & Multiple partial pricing \\
                    & 2 & Dantzig \\
                    & 3 & First eligible arc \\
\hline
\end{tabular}
\end{center}
\caption{\label{tlb704}Min-Cost Flow Solver Options}
\end{tablehere}



\section{Balanced Network Search}
\markright{BALANCED NETWORK SEARCH}
\label{slb_bns}
\methods
\begin{quote}
\begin{verbatim}
class abstractBalancedFNW
{
    bool    BNS(TNode,TNode = NoNode);
    bool    BNSKocayStone(TNode,TNode = NoNode);
    bool    BNSKamedaMunro(TNode,TNode = NoNode);
    bool    BNSHeuristicsBF(TNode,TNode = NoNode);
    bool    BNSMicaliVazirani(TNode,TNode = NoNode);

    void    Expand(TNode,TNode);
    void    CoExpand(TNode,TNode);
}
\end{verbatim}
\end{quote}
A {\bf valid}\index{valid path} path in a balanced flow network is an eligible
path which does not traverse a pair of complementary arcs with
\verb/BalCap(a)==BalCap(a^2)==1/. A \nt{balanced network search (BNS)} method
is a procedure which decides which nodes are reachable by a valid path from a
specified root node.

All procedures take one or two parameters. The first one is the root of search
while the second optional parameter is a target node which should be reached on
a valid path. If such a target $t$ is specified, the method effectively decides
whether $t$ is reachable and halts once $t$ has been reached. The BNS methods
may either be exact, that is, a valid path is determined for every node which
is reachable on a valid path, or heuristic.

For every BNS method and every node with finite distance label, a valid
augmenting path can be expanded by using the method \verb/Expand/. This method
recursively calls \verb/CoExpand/, and utilizes the \verb/prop/ and the
\verb/petal/ data structures which are returned by all BNS methods. The exact
methods \verb/BNSKocayStone/ and \verb/BNSMicaliVazirani/ also return an
odd set system by the partition data structure.

The generic solver method \verb/BNS/ calls one of the various BNS methods
according to the context variable \verb/methBNS/. Note that the DFS heuristics
and the Kameda-Munro heuristics are both encoded into the method
\verb/BNSKamedaMunro/ which also reads \verb/methBNS/. If a heuristical method
is selected but the target is missed, the method \verb/BNSKocayStone/
is called to verify the negative result.


\subsection{The Algorithm by Kocay and Stone}
This method is in the tradition of the Edmonds/Gabow cardinality matching
algorithm and uses a BFS approach. It is exact, that is, it finds a valid
augmenting path if there is one. Although improved to $O(m)$ complexity, it
cannot beat the running times of the heuristic methods. It also fails to
compute paths of minimum length, but is much simpler than the
Micali/Vazirani algorithm. 


\subsection{The Breadth First Heuristics}
This is the most simple BNS procedure since it totally ignores the neccessity
of blossom shrinking and does not use any high level data structures. It runs
in $O(n^2)$ time, but performs better than the Kocay/Stone algorithm up to a
size of 5000 nodes approximately. Just as the other heuristics,
\verb/BNSHeuristicsBF/ does not compute a dual solution (odd set system).


\subsection{The Depth First Heuristics by Kameda and Munro}
This is the most efficient method according to our experiments and runs in
$O(m)$ time. It utilizes two stacks for the management of blossoms instead of
a disjoint set system. Both version are only an heuristics which may miss to
find a balanced augmenting path even if there is one. The enhanced version
requires some additional storage for time stamps but misses a node only in
pathological situations.


\subsection{The Algorithm by Micali and Vazirani}
This method finds the distance labels with respect to the specified root node
in $O(m)$ time. It depends on layered auxiliary shrinking networks, into which
the shortest augmenting paths are encoded. For the time being, no $st$-path
is extracted to the \verb/prop/ and \verb/petal/ data structures.

\begin{tablehere}
\begin{center}
\vspace*{1cm}
\begin{tabular}{|l|l|l|}
\hline
\verb/methBNS/      & {\bf 0} & Breadth-First (Kocay/Stone) \\
                    & 1 & Depth-First Heuristics \\
                    & 2 & Depth-First Heuristics (Time Stamps) \\
                    & 3 & Breadth-First Heuristics \\
\hline
\end{tabular}
\end{center}
\caption{\label{tlb705}Balanced Network Search Options}
\end{tablehere}



\section{Maximum Balanced Network Flows}
\markright{MAXIMUM BALANCED NETWORK FLOWS}
\label{slb_solve_balanced_flow}
\methods
\begin{quote}
\begin{verbatim}
class abstractBalancedFNW
{
    TFloat  MaxBalFlow(TNode);
    TFloat  BNSAndAugment(TNode);
    TFloat  BalancedScaling(TNode);
    TFloat  Anstee(TNode);
    TFloat  MicaliVazirani(TNode,TNode = NoNode);

    void            CancelEven();
    virtual TFloat  CancelOdd();
}
\end{verbatim}
\end{quote}
A \nt{balanced pseudo-flow} on a balanced flow network is a pseudo-flow such
that for every arc $a$, \verb/BalFlow(a)==BalFlow(a^2)/ holds. In contrast to
the ordinary max-flow solvers, one only specifies the source node \verb/s/.
The sink note \verb/t == (s^1)/ is determined by the flow symmetry.

The generic solver method \verb/MaxBalFlow/ calls one of the actual problem
solvers according to the value of \verb/methMaxBalFlow/.


\subsection{The Balanced Augmentation Algorithm}
The method \verb/BNSAndAugment/ is the most simple method which iteratively
calls \verb/BNS/. It solves a $k$-factor problem in $O(nm)$ time for fixed $k$,
and the general maximum balanced flow problem in $O(\nu m)$ time. 


\subsection{The Capacity Scaling Algorithm}
The method \verb/CapacityScaling/ splits the balanced augmentation algorithm
into scaling phases. In the \verb/delta/-phase, only the arcs with
\verb/BalCap(a)>=delta/ are considered. The parameter \verb/delta/ is
initialized to the maximum capacity, and is divided by $2$ if no further
augmenting path can be found. The resulting time bound is $O(m^2\log{U})$.

Except for the final scaling phase, every augmenting path is valid. Hence, the
balanced network search is replaced by an ordinary BFS for the bulk of the
computation. Effectively, the effort decreases to the solution of an ordinary
network flow problem.


\subsection{The Phase-Ordered Algorithm}
The method \verb/MicaliVazirani/ is the fastest cardinality matching algorithm
both in practice and theory achieving the complexity bound $O(\sqrt{n}m)$.
The general problem of maximum balanced network flows is solved in $O(n^2m)$
time.

In fact, the GOBLIN implementation is not the original Micali/Vazirani
algorithm but a careful extension to balanced network flows. It is the most
involved of the maximum balanced flow solvers and implemented by its own class
(see Section \ref{slb234} for the details).


\subsection{The Cycle Canceling Algorithm}
\label{slb_cancel}
The method \verb/Anstee/ computes an ordinary maximum $st$-flow which is
symmetrized afterwards resulting in a balanced flow which is half-integral
but not integral. The non-integral flow values are deleted successively by
calling the methods \verb/CancelEven/ and \verb/CancelOdd/. The latter method
may decrease the flow value and perform some balanced augmentation steps which 
conclude the computation.

Note that the generic method \verb/MaxFlow/ is used which allows to select from
all implemented max-flow algorithms. On the other hand, \verb/CancelOdd/ calls
the procedure \verb/BNSKocayStone/ directly which is needed to perform the
balanced augmentations.

Hence the complexity of the \verb/Anstee/ algorithm is dominated by the
max-flow algorithm used. If one uses the push and relabel algorithm, this
yield the best complexity bound, namely $O(\sqrt{m}n^2)$, but the Dinic
algorithm performs much better for explicit matching problems. In our
experience, \verb/MicaliVazirani/ and \verb/Anstee/ perform much better than
the augmentation methods, but neither beats the other.

\begin{tablehere}
\begin{center}
\vspace*{1cm}
\begin{tabular}{|l|l|l|}
\hline
\verb/methMaxBalFlow/& 0 & Successive augmentation \\
                    & 1 & Phase-Ordered augmentation \\
                    & {\bf 2} & Phase-Ordered augmentation with look-ahead \\
                    & 3 & Phase-Ordered augmentation with look-ahead \\
                    &   & and augmentation \\
                    & 4 & Capacity scaling \\
                    & 5 & Cycle canceling \\
\hline
\end{tabular}
\end{center}
\caption{\label{tlb706}Maximum Balanced Flow Options}
\end{tablehere}

\noindent
In the situation of $k$-factor problems, \verb/Anstee/ runs in $O(nm)$ time
which is the same as for the basic method \verb/BNSAndAugment/. However, it
has turned out that \verb/CancelOdd/ decreases the flow value only by a very
small amount (probably $<10$ for $10^5$ nodes). Since balanced augmentation
steps are considerably more expensive than ordinary augmentations, the method
\verb/Anstee/ performs much better than \verb/BNSAndAugment/ in practice.

Note that the method \verb/CancelOdd()/ has two different implementations.
The general procedure depends on the problem transformation class
\verb/bal2bal/. The second, simpler implementation, is in the class
\verb/gra2bal/, and hence applies to explicit matching problems only.



\markright{WEIGHTED BALANCED NETWORK FLOW ALGORITHMS}
\section{Weighted Balanced Network Flow Algorithms}
\label{slb_solve_balanced_weighted}
\methods
\begin{quote}
\begin{verbatim}
class abstractBalancedFNW
{
    TFloat  MinCBalFlow(TNode s);
    TFloat  PrimalDual(TNode s);
    TFloat  EnhancedPD(TNode s);
    TFloat  CancelPD();
}
\end{verbatim}
\end{quote}


\subsection{The Primal-Dual Algorithm}
The primal-dual algorithm for ordinary flows maintains an $st$-flow and a set
of potentials which satisfy a reduced length optimality criterion. If these
solutions admit an augmenting path such that all arcs on this path have zero
reduced length, the PD algorithm augments as long as possible. Otherwise
several dual updates (updates on the node potentials) are performed,
each of which extends the set of $s$-reachable nodes.

In the setting of balanced networks, the dual solution consists of node
potentials, a shrinking family, and variables assigned with the sets of this
family. These data structures are managed by a special class
\verb/surfaceGraph/ whose incidence structure is the graph in which all blossoms
(sets in the shrinking family) are contracted to a single node. This class has
been described in Section \ref{slb235}.

The GOBLIN implementations are still rather basic. That is, they do not use
splitable priority queues or multiple search trees. The complexity so far is
$O(\nu nm)$ where $\nu$ denotes the value of a maximum balanced $st$-flow (minus
the vlaue of the initial flow). A later release of GOBLIN should achieve a
$O(\nu n^2)$ implementation. See Table \ref{tlb707} for the available variations
of the PD algorithm.

Note that all PD methods can run with modified length labels which are not
physically present, but computed from the dual variables. This recursive
computation takes $O(n)$ time, and hence may increase the complexity of the PD
method by a factor $n$. It has the benefit that only $O(n)$ storage is needed
for keeping the modified length labels compared to $O(m)$. This is important
for large scale geometrical matching problems, say with $>10^5$ nodes.

The recursive computation of modified length labels is enabled by the context
flag \verb/methModLength/, and can be performed explicitly if \verb/RModLength/
is called.


\subsection{The Enhanced Primal-Dual Algorithm}
\label{slb_enhanced}
This is an improvement of the PD algorithm resambling the cycle
canceling method \verb/Anstee/ discussed in Section \ref{slb_cancel}.
More explicitly, the method \verb/EnhancedPD/ first calls the generic solver
\verb/MinCFlow/ to compute an ordinary extreme maximum $st$-flow.

This flow is symmetrized by using \verb/CancelEven/ and \verb/CancelPD/. The
latter method is essentially the same as the general implementation of
\verb/CancelOdd/, but calls \verb/PrimalDual/ for the final balanced
augmentation steps. The mere symmetrization takes $O(m)$ steps.

By this preprocessing, \verb/PrimalDual/ is started with a complementary pair
where the flow value is at most $n$ less than the value of a maximum balanced
$st$-flow, and therefore runs in $O(n^2m)$ time. The overall complexity is
dominated by the min-cost flow solver which comes into play. If one enables
the cost-scaling or minimum-mean cycle canceling method (see Section
\ref{slb_solve_mcflow}), a strongly polynomial procedure results.

If one applies \verb/EnhancedPD/ and the shortest path method
\verb/EdmondsKarp2/ to a $k$-factor problem, the time complexity
is the same as for the straight primal-dual method. However, the actual running
times may decrease dramatically, since Dijkstra augmentations are
conceptually much more simple and can be performed in $O(m+n\log{n})$ time
instead of $O(mn)$ time.

\begin{tablehere}
\begin{center}
\vspace*{1cm}
\begin{tabular}{|l|l|l|}
\hline
\verb/methMinCBalFlow/& 0 & Primal-Dual \\
                    & {\bf 1} & Enhanced primal-dual \\
\hline
\verb/methPrimalDual/& 0 & Restart BNS after each dual update \\
                    & 1 & Restart BNS after changes in the shrinking family \\
                    & {\bf 2} & Restart BNS after blossom expansions \\
\hline
\verb/methModLength/& {\bf 0} & Recursive computation \\
                    & 1 & Store modified length labels \\
\hline
\end{tabular}
\end{center}
\caption{\label{tlb707}Min-Cost Balanced Flow Options}
\end{tablehere}



\markright{MATCHING SOLVERS}
\section{Matching Solvers}
\label{slb_solve_matching}
\methods
\begin{quote}
\begin{verbatim}
class abstractGraph
{
    virtual bool    MaximumMatching();
    virtual bool    MaximumMatching(TCap);
    virtual bool    MaximumMatching(TCap*,TCap* = NULL);

    virtual bool    MinCMatching();
    virtual bool    MinCMatching(TCap);
    virtual bool    MinCMatching(TCap*,TCap* = NULL);

    TFloat          MinCEdgeCover();
}
\end{verbatim}
\end{quote}
Matching problems are solved in GOBLIN by transformation to balanced flow
networks generally. This involves the class \verb/gra2bal/ which was
discussed in Section \ref{slb233}. Note that the general methods are overridden
for bipartite graphs by another problem transformation which depends on the
class \verb/big2fnw/.

If the matching solver is called without any parameters, a subgraph with
\verb/Deg(v)==Demand(v)/ for every node $v$ is computed. It may also be called
with an integer $k$, and then returns a $k$-factor, that is, \verb/Deg(v)==k/
for every node. Finally, the matching solver may be called with two degree
sequences $a$ and $b$. Then \verb/a[v]<=Deg(v)<=b[v]/ will hold for the
resulting subgraph.

\bigskip
\begin{figurehere}
\begin{center}
\epsfxsize=7cm
\epsfbox{eps/optMatch.eps}
\vspace{0.5cm}
\caption{\label{flb_optmatch}A Minimum $1$-Factor}
\end{center}
\end{figurehere}

\noindent
For complete graphs and bigraphs, one can solve the matching problem on a
sparse subgraph either heuristically (if \verb/methSolve==0/) or to optimality.
The candidate graph consists of 10 greedy like heuristic matchings and the
\verb/k/ nearest neighbours of each node where \verb/k=methCandidates/.
Note that this option is provided for optimization with the internal node
demands only. If the graph is non-bipartite, only the fractional matching
problem is solved on the candidate graph.

\bigskip
\begin{figurehere}
\begin{center}
\epsfxsize=11cm
\epsfbox{gedecomp2.eps}
\vspace{0.5cm}
\caption{\label{flb_gedecomp}Gallai-Edmonds Decomposition}
\end{center}
\end{figurehere}

\noindent
There is a procedure \verb/MinCEdgeCover()/ which determines an edge cover
with minimum weight. This uses the well-known reduction to the 1-factor problem.
In particular, the worst-case time complexity is the same as for the underlying
matching solver. A procedure to compute a minimum size edge cover from a given
maximum cardinality maching is discussed in Section \ref{slb_sol}.



\markright{T-JOIN AND POSTMAN PROBLEMS}
\section{$T$-Join and Postman Problems}
\label{slb_solve_t_join}
\methods
\begin{quote}
\begin{verbatim}
class abstractMixedGraph
{
    virtual void  ChinesePostman(bool);
}

class abstractGraph
{
    void    ComputeTJoin(const indexSet<TNode>&);
    void    MinCTJoin(const indexSet<TNode>&);
    void    MinCTJoin(TNode,TNode);
    void    ChinesePostman(bool);
}

class abstractDiGraph
{
    void    ChinesePostman(bool);
}
\end{verbatim}
\end{quote}
An \nt{Eulerian cycle} is an eligible closed walk which traverses every arc $a$
exactly \verb/UCap(a)/ times. A graph is {\bf Eulerian} \index{graph!Eulerian}
if it admits an Eulerian cycle.

The \nt{Chinese postman problem (CPP)} asks for an Eulerian supergraph such
that Eulerian cycles have minimum length. This problem is NP-hard for
general mixed graphs, but can be reduced to matching problems if the graph
is either directed or undirected. These cases are handled in GOBLIN.

Given a node set $T$ of even cardinality, a \nt{$T$-join} is a subgraph in which
all nodes in $T$ have odd degree and all other nodes have even degree.
The undirected CPP is a special case of the minimum $T$-join problem which is
actually solved in GOBLIN. Note that the minimum $T$-join problem has several
further interesting special cases: $1$-matching, shortest paths and
optimization on the \nt{cycle space}.

All methods require $\Theta(n^2)$ storage for the complete graph on which the
respective matching problems are solved. Hence the CPP solvers do not work for
large scale problems, say with $n>10^5$ nodes.


\subsection{$T$-Joins}
The method \verb/ComputeTJoin(T)/ requires non-negative length labels and
a node set $T$. This procedure reduces the $T$-join problem to a $1$-matching
problem so that the running time is dominated by the matching solver used.

The methods \verb/MinCTJoin(TNode,TNode)/, \verb/graph::ChinesePostman()/ and
\verb/MinCTJoin()/ can handle negative length labels. These
latter procedures set the demand labels and then call \verb/ComputeTJoin()/
which actually determines the $T$-join.

\bigskip
\begin{figurehere}
\begin{center}
\epsfxsize=4cm
\epsfbox{eps/postmanBefore.eps}
\epsfxsize=4cm
\hspace*{1.5cm}
\epsfbox{eps/postmanAfter.eps}
\vspace{0.5cm}
\caption{\label{flb_postman}A Graph and a Minimum Eulerian Supergraph}
\end{center}
\end{figurehere}


\subsection{The Undirected CPP}
The call \verb/abstractGraph::ChinesePostman(adjustUCap)/ returns an Eulerian
subgraph which has maximum weight rather than a comcrete Eulerian cycle. It calls
the method \verb/ComputeTJoin()/ which has been described before. If
\verb/adjustUCap == true/ and if the graph is represented, the edge capacities
are increased to obtain a minimal Eulerian supergraph.


\subsection{The Directed CPP}
The call \verb/abstractDiGraph::ChinesePostman(adjustUCap)/ reduces the CPP to a
bipartite $b$-matching problem, and the running time is dominated by the matching
solver used. If \verb/adjustUCap == true/ and if the graph is represented, the
edge capacities are increased to obtain a minimal Eulerian supergraph. In any case,
a maximum weight Eulerian subgraph is provided.



\markright{TSP ALGORITHMS}
\section{TSP Algorithms}
\label{slb_solve_tsp}
\methods
\begin{quote}
\begin{verbatim}
class abstractMixedGraph
{
    TFloat          TSP(TNode = NoNode);
    virtual TFloat  TSPHeuristics(TNode);
    TFloat          TSPHeuristicsRandom();
    TFloat          TSPHeuristicsInsert();
    TFloat          TSPHeuristicsInsert(TNode);
    TFloat          TSPHeuristicsTree();
    TFloat          TSPHeuristicsTree(TNode);
    virtual TFloat  TSPLocalSearch(TArc*);
    bool            TSPNodeExchange(TArc*,TFloat = 0);
    TFloat          TSPSubOpt1Tree(TNode,
                        TFloat = InfFloat,TOption = 1);
    TFloat          TSPBranchAndBound(TNode,
                        TFloat = InfFloat);
}

class abstractGraph
{
    virtual TFloat  TSPHeuristics(TNode);
    TFloat          TSPHeuristicsChristofides(
                        TNode = NoNode);
    TFloat          TSPLocalSearch(TArc*);
    bool            TSP2Exchange(TArc*,TFloat = 0);
    TFloat          TSPSubOpt1Tree(TNode,
                        TFloat = InfFloat,TOption = 1);
    TFloat          TSPBranchAndBound(TNode,
                        TFloat = InfFloat);
}

class denseDiGraph
{
    TFloat          TSPHeuristics(TNode);
}

class denseGraph
{
    TFloat          TSPHeuristics(TNode);
}
\end{verbatim}
\end{quote}
A \nt{hamiltonian cycle} or {\bf tour} is an eligible cycle which traverses
every node exactly once. The \nt{traveling salesman problem (TSP)} asks for a
tour of minimum length. In GOBLIN, tours are represented by the predecessor
labels.

The general TSP solver is defined by the method \verb/TSP()/. This method is
controlled by the configuration parameters \verb/methTSP/, \verb/methSolve/
and \verb/methLocal/. The parameters \verb/methTSP/ allows to select from
several TSP heuristics, and \verb/methLocal/
enables or disables local search routines.
 
The parameter \verb/methSolve/ determines the general optimization
level. If its value is zero, only a heuristic tour is computed. If its value
is one, a subgradient optimization is performed to obtain good lower bounds.
For higher values of \verb/methSolve/, the problem can be solved to optimality
by branch and bound. When the TSP solver starts, it first checks if a 1-tree
exists to sort out some infeasible instances.

The configuration parameters \verb/methSolve/ and \verb/methLocal/ are designed
to control other hard problem solvers too, but there is no application yet.

The optional node passed to \verb/TSP()/ is used by the TSP heuristics in
different ways and may help to produce good starting solutions. In our
experience, the subgradient optimization produces the best heuristic tours.


\subsection{The Insertion Heuristics}
The method \verb/TSPHeuristicsInsert(r)/ starts with a cycle through $r$ 
and a neighbour of $r$ and successively inserts nodes into this cycle.
The node to be inserted is the node with maximum distance from the cycle.
It is inserted at the position where it causes the smallest possible costs.
If one neglects the computation of node adjacencies, the running time is
$O(n^3)$.


\subsection{The Tree Approximation}
The method \verb/TSPHeuristicsTree(r)/ expects an $r$-tree stored in the
predecessor labels. This $r$-tree is transformed into a tour which is at most
twice as long as the original tree if the graph is metric. If one neglects the
computation of node adjacencies, the running time is $O(n)$.


\subsection{The Christofides Approximation}
The method \verb/TSPHeuristicsChristofides(r)/ combines the ideas of the tree
heuristics and the Chinese postman algorithm. It first computes a minimum
$r$-tree. Then a complete graph on the nodes with odd degree is instanciated,
a perfect $1$-matching of this graph is determined, and added to the graph.
Then an Eulerian cycle results which can be contracted to a tour which is at
most 50 percent longer than the initial $r$-tree if the graph is metric.

The final tour is returned by the predecessor labels, and its length is the
return value. If one neglects the computation of node adjacencies, the running
time is dominated by the complexity of the selected matching solver.


\subsection{Local Search}
GOBLIN provides a local search routine \verb/TSPLocalSearch()/ which can be used
to improve the heuristic tours discussed so far. Local search is enabled by the
configuration parameter \verb/methLocal/. One can also start this post-optimization
routine with a random tour by calling \verb/TSPHeuristicsRandom/.

The method \verb/TSPLocalSearch()/ iteratively tries to improve the present tour
by recursive calls to \verb/TSP2Exchange()/ and/or \verb/TSP2NodeExchange()/
The first method iteratively tries to improve a given tour by deleting two
arbitrary arcs which are replaced by two new (and entirely determined) arcs.
The second procedure selects a node which is deleted and inserted at another
point of the tour.

Both local search procedures take an array of predecessor labels and an optional
parameter which denotes the minimal improvement accepted for a local exchange.
If this value is positive, a local exchange may increase the tour length by the
specified amount.

\bigskip
\begin{figurehere}
\begin{center}
\epsfxsize=4cm
\epsfbox{local1.eps}
\epsfxsize=4cm
\hspace*{1.5cm}
\epsfbox{local2.eps}
\vspace{0.5cm}
\caption{\label{flb_2opt}A 2-Opt Step}
\end{center}
\end{figurehere}


\subsection{The Subgradient Method by Held and Karp}
The method \verb/TSPSubOpt1Tree(r)/ iteratively calls \verb/MinTree(r)/ which
returns an $r$-tree as described in Section \ref{slb733} by the subgraph data
structure. If all nodes have \verb/Deg(v)==2/, a tour is found, and the
procedure halts.

\bigskip
\begin{figurehere}
\begin{center}
\epsfxsize=12cm
\epsfbox{eps/tspSubOpt.eps}
\vspace{0.5cm}
\caption{\label{flb_subgradient}An optimal 1-Tree which forms a tour}
\end{center}
\end{figurehere}

Otherwise, the potentials of the nodes with \verb/Deg(v)>2/ are increased
and the potentials of the nodes with \verb/Deg(v)<2/ are decreased by some
amount, and the min tree solver is called again. If the TSP problem cannot be
solved within a certain number of iterations, the procedure returns the best
lower bound and the corresponding $r$-tree by the subgraph data structure.

If it looks promising, \verb/TSPSubOpt1Tree()/ calls \verb/TSPHeuristicsTree(r)/
which determines a feasible tour and hence an upper bound.  The best tour found
is returned by the predecessor labels. One may pass the length of a known tour
by an optional parameter in order to initialize the upper bound.

This procedure yields very strong lower bounds on the length of an optimal tour,
but one cannot expect that an optimal tour is found for practical instances.
The quality of the bound depends on the third parameter which acts as follows:
If a value of zero is passed, only a single 1-tree is computed without changing
any node potentials. If a value of one is passed, good potentials are computed
within a reasonable number of iterations, say 100, roughly. For a value of two,
a large number of iterations occurs, 3000 approximately. The found bound is much
better for some instances, but on the average the fast strategy already achieves
the optimal bound.

This calling parameter is matched by the context parameters \verb/methRelaxTSP1/
and \verb/methRelaxTSP2/ which specify how the 1-tree method is applied to find
the initial bound respectively the partial bounds for the branch and bound scheme.
A value of \verb/methRelaxTSP2=2/ does not yield a practical method.


\subsection{Branch and Bound}
There is a branch and bound solver \verb/TSPBranchAndBound/ which depends on
the $1$-tree relaxation. It also uses the node potentials found by subgradient
optimization. If the configuration parameter \verb/methCandidates/ is negative,
the branch and bound module evaluates the entire graph. Otherwise, a candidate
graph is generated which consists of the best tour found so far, several random
locally optimal tours and the nearest neighbours of each node. In that case,
the value of \verb/methCandidates/ denotes a lower bound on the node degrees.
See Section \ref{slb_branchSymmTSP} for the details of the branch and bound module.


\subsection{Application to Sparse Graphs}
The TSP solver also applies to sparse graph objects and to graphs with
non-trivial capacity bounds. The latter can be used to restrict the
set of feasible solutions.

None of the implemented heuristics would be helpful, if applied to the original
graph. Instead of this, the method \verb/TSPHeuristics()/ computes the metric
closure of the graph (see Section \ref{slb_metric_closure} for
more details). On this \verb/metricGraph/ object, the heuristics
and the subgradient optimization are run irrespecitive of the current value
of \verb/methSolve/. If the tour of the metric closure maps to the original
graph, this tour returned.

If branch and bound is enabled, this applies to the original graph. No candidate
search is performed but the entire graph is evaluated.

\begin{tablehere}
\begin{center}
\vspace*{1cm}
\begin{tabular}{|l|l|l|}
\hline
\verb/methTSP/   & {\bf 0} & Random tour \\
                    & 1 & Insertion heuristics \\
                    & 2 & Tree heuristics \\
                    & 3 & Christofides (undirected graphs only) \\
\hline
\verb/methRelaxTSP1/   & 0 & Straight 1-tree bound \\
                    & {\bf 1} & Subgradient optimization (fast) \\
                    & 2 & Subgradient optimization (stable) \\
\hline
\end{tabular}
\end{center}
\caption{\label{tlb_methTSP}TSP Solver Methods}
\end{tablehere}



\markright{GRAPH COLOURINGS}
\section{Graph Colourings and Clique Covers}
\label{slb_solve_colours}
\methods
\begin{quote}
\begin{verbatim}
class abstractMixedGraph
{
    TNode           NodeColouring(TNode);
    TNode           PlanarColouring();
    TNode           NCLocalSearch();
    bool            NCKempeExchange(TNode*,TNode,TNode);
    TNode           CliqueCover(TNode);
    TNode           EdgeColouring(TNode);
}
\end{verbatim}
\end{quote}
A \nt{node colouring} is an assignment of colours to the graph nodes such that
the nodes with equal colour are non-adjacent. A \nt{clique cover} is an
assignment of colours to the graph nodes such that every colour class forms
a clique.

The procedure \verb/NodeColouring/ calls the enumeration scheme which is described
in Section \ref{slb_branchColour}. The parameter denotes the acceptable number of
colours. This value $k$ has strong impact on the practical performance of the
solver. For example, for a planar graph and a value of $6$, the branch and
bound would end within a single iteration. If $k$ is very close to the
chromatic number $\chi$, the computational efforts are tremendous even for a 50
node graph. In the case of $k=5$ and $n\leq 3m-6$, the method \verb/PlanarColouring/
is called, and enumeration occurs only if the specialized method does not return
a 5-colouring. The colouring of planar graphs requires $O(nm)$ time.

\bigskip
\begin{figurehere}
\begin{center}
\epsfxsize=8cm
\epsfbox{eps/dodekahedron.eps}
\vspace{0.5cm}
\caption{\label{flb_dodeka}A $3$-Colouring of the dodecahedron}
\end{center}
\end{figurehere}

\noindent
If no $k$ is specified, the method produces a decreasing sequence of values for
$k$, for which the enumeration scheme is started. By this strategy, one can
produce colourings which come close to $\chi$. Note that cliques sizes are lower
bounds for $\chi$. Hence, with some luck, it is possible to bound the chromatic
number to a small interval.

The clique cover and the edge colouring method essentially perform a node
colouring of the complementary graph and the line graph respectively. More
precisely, if $\Delta$ denotes the maximum node degree, then
\verb/EdgeColouring(k)/ computes an approximative edge colouring with either
$\Delta$ or $\Delta+1$ colours in $O(m\Delta(m+\Delta\log{\Delta}))$ time. If
$k>\Delta$, this colouring is returned by the subgraph labels. If $k<\Delta$,
no $k$-edge colouring exists. Only if $k=\Delta$ and if the approximation
method has obtained a $\Delta+1$-colouring, the enumeration scheme is used for
an potential improvement.

All described methods return the number of colours in the final solution or
the constant \verb/NoNode/ if no colouring was found.
 
If the context flag \verb/methLocal/ is set, the procedure \verb/NCLocalSearch/
is called with the final colouring obtained by the enumeration scheme. Each of
the methods \verb/NCLocalSearch()/, \verb/PlanarColouring()/ and \verb/EdgeColouring()/
depend on the method \verb/NCKempeExchange()/ which takes the colours of the two
specified nodes and flips the colours in the Kempe component of the first node.
If both nodes are in the same Kempe component, \verb/false/ is returned and
\verb/true/ otherwise. Such an exchange operation needs $O(m)$ time.




\markright{STABLE SETS AND CLIQUES}
\section{Stable Sets and Cliques}
\label{slb_solve_stable}
\methods
\begin{quote}
\begin{verbatim}
class abstractMixedGraph
{
    void            StableSet();
    void            Clique();
    void            VertexCover();
}
\end{verbatim}
\end{quote}
A \nt{stable set} is a set of pairwise non-ajacent nodes whereas a \nt{clique}
consists of pairwise adjacent nodes and a \nt{vertex cover} is a node set which
contains at least one end node of every egde. The three listed methods return
the maximum cardinality of a respective node set. The set itself consists of
the nodes with colour 1.

All methods call the branch and bound solver for the stable set problem
described in Section \ref{slb_bbstable} and use heuristic graph colouring.
Our experiments have turned out that one can compute cliques in graphs with
150-200 nodes depending on the graph density and on the quality of the
heuristic colouring.

\bigskip
\begin{figurehere}
\begin{center}
\epsfxsize=8cm
\epsfbox{eps/queensBoard.eps}
\vspace{0.5cm}
\caption{\label{flb_queens}A Maximum Stable Set of Queens on a Chessboard}
\end{center}
\end{figurehere}



\markright{DISCRETE STEINER TREES}
\section{Discrete Steiner Trees}
\label{slb_steiner}
\methods
\begin{quote}
\begin{verbatim}
class abstractMixedGraph
{
    TFloat          SteinerTree(const indexSet<TNode>&,TNode);
    TFloat          SteinerTrimLeaves(const indexSet<TNode>&,TArc*);
    virtual TFloat  SteinerHeuristics(const indexSet<TNode>&,TNode);
    virtual TFloat  SteinerEnumerate(const indexSet<TNode>&,TNode);
}

class abstractGraph
{
    TFloat          SteinerHeuristics(const indexSet<TNode>&,TNode = NoNode);
    TFloat          SteinerEnumerate(const indexSet<TNode>&,TNode = NoNode);
}
\end{verbatim}
\end{quote}
The method \verb/SteinerTree(Terminals,r)/determines a \nt{Steiner tree}, that
is a tree or arborescence rooted  at $r$ which spans all \nt{terminal} nodes.
The remaining nodes are called \nt{Steiner nodes} and are spanned only if they
denote shortcuts.

The method \verb/SteinerEnumerate()/ enumerates on all possibilities for the
Steiner nodes and iteratively calls the generic min-tree solver. Hence, the
algorithm is non-polynomial and the running times are acceptable for at most
ten Steiner nodes.

The method \verb/SteinerTrimLeaves()/ turns a given spanning tree
(arborescence) into a Steiner tree by successively deleting all Steiner nodes
which are leaves. The running time is $O(n)$, the return value is the sum of
lengths of the deleted arcs. The general implementation of
\verb/SteinerHeuristics()/ does nothing more than calling \verb/MinTree()/ and
\verb/SteinerTrimLeaves()/.

In undirected graphs, \verb/SteinerHeuristics()/ implements the Mehlhorn
2-approximation algorithm. This method utilizes the Prim spanning tree method
and some discrete adaption of the Voronio geometry. The running time is
$O(m+n\log n)$ and is dominated by the shortest path problem which must be
solved to the compute the Voronoi regions (see Section \ref{slb_voronoi} for
the details).

The compound solver method \verb/SteinerTree()/ calls the heuristics and, if
\verb/methSolve>1/, the enumeration scheme. Lower bounds can be obtained
without complete enumeration in the undirected case only.


\markright{MAXIMUM EDGE CUTS}
\section{Maximum Edge Cuts}
\label{slb_solve_maxcut}
\methods
\begin{quote}
\begin{verbatim}
class abstractMixedGraph
{
    TFloat MaxCut(TNode=NoNode,TNode=NoNode);
    virtual TFloat MaxCutHeuristics(
                TNode=NoNode,TNode=NoNode);
    TFloat  MaxCutHeuristicsGRASP(
                TNode=NoNode,TNode=NoNode);
    TFloat  MaxCutLocalSearch(
                TNode*,TNode=NoNode,TNode=NoNode);
    TFloat  MaxCutBranchAndBound(TNode=NoNode,
                TNode=NoNode,TFloat=InfFloat);
}

class abstractGraph
{
    TFloat  MaxCutHeuristics(
                TNode=NoNode,TNode=NoNode);
    TFloat  MaxCutHeuristicsTree(
                TNode=NoNode,TNode=NoNode);
    TFloat MaxCutDualTJoin(TNode=NoNode);
}
\end{verbatim}
\end{quote}
A \nt{maximum cut} is a strong edge cut with the maximum sum of weights where
the \nt{weight} of an arc $a$ is defined as \verb/UCap(a)*Length(a)/.
In undirected graphs with unit edge capacities and lengths, a maximum cut
corresponds to a maximum bipartite subgraph.

For all described max-cut algorithms, the return value is the cut weight. The
cut is returned by the node colours which can be either 0 or 1. Cut arcs are
directed from colour 0 to colour 1 and only non-blocking arcs are counted for
the cut weight. If one or two optional nodes are specified, the first node is
always coloured 0 and the second node is coloured 1.

Apart from the exact methods, GOBLIN provides two starting heuristics:
\begin{itemize}
\item In the general setting, \verb/MaxCutHeuristicsGRASP()/ applies which
    assigns colours to the nodes step by step. In each iteration, a candidate
    list with a few nodes is generated and from this list, an arbitrary node
    is chosen. Then, this node is always added to the most profitable component.
    If the graph is undirected, the cut weight is at least $1/2$ of the sum of
    arc weights.
\item In undirected graphs, \verb/MaxCutHeuristicsTree()/ computes a minimum
    spanning tree where the length labels are substituted by the arc weights.
    After that, the bipartition is chosen with respect to the tree.
\end{itemize}

\bigskip
\begin{figurehere}
\begin{center}
\epsfxsize=10cm
\epsfbox{maxcut1.eps}
\vspace{0.5cm}
\caption{\label{flb_maxcut}A Maximum Edge Cut}
\end{center}
\end{figurehere}

\noindent
The local search procedure \verb/MaxCutLocalSearch()/ iteratively shifts a
single node from one component to another if the cut capacity strictly
increases by that operation. Every iteration takes $O(m)$ computing steps but
the number of iterations cannot be bounded polynomially. As for other solvers,
the local search procedure is integrated into the heuristics and executed when
the context flag \verb/methLocal/ is set.

For planar undirected graphs with non-negative arc weights, the method
\verb/MaxCutDualTJoin()/ determines a maximum $\emptyset$-join of the dual
graph and maps it back to an edge cut. This is an exact algorithm, not just
a heuristic! The running time is dominated by the used T-join method.

The method \verb/MaxCutBranchAndBound()/ applies to the general setting but
can solve and proof optimality for small graphs only (with roughly 30 nodes
and less).



\end{multicols}
\part{Miscellaneous}
\begin{multicols}{2}

\markboth{THE OBJECT CONTROLLER}{THE OBJECT CONTROLLER}
\chapter{The Object Controller}
\thispagestyle{fancy}
\label{clb7}

With any object derived from the base class \verb/managedObject/ (graph
objects, iterator objects and data structures), a \verb/goblinController/
object is associated. To this controller object, we refer as the {\bf context}
of the data object.

Data objects may share their controller with other data objects. In particular,
iterators, logical views and temporary data structures used in algorithms are
in the same context as the referenced graph object.

There is a global controller object, namely the \verb/goblinDefaultContext/.
For the most default and file constructors of GOBLIN data objects, a reference
to \verb/goblinDefaultContext/ appears as a default parameter.



\markright{CONSTRUCTION}
\section{Construction}
\begin{mymethods}
\begin{verbatim}
class goblinController
{
    goblinController();
    goblinController(goblinController&);
}
\end{verbatim}
\end{mymethods}
Whenever a controller object is instanciated, this generates a couple of
timer objects and an object hash table which allows to dereference the dependent
data objects from a given integer handle. All other context parameters are
initialized either with default values or the respective value of the master
context.

The \nt{copy constructor} method produces a clone of the controller object
passed by its reference. All built-in type and \verb/char*/ string values are
copied, event handlers and module entry points are inherited from the master
context.

For example, a display configuration is a volatile controller object and copied
from the context of the object to be displayed. This controller is modified
with some class dependent display parameters before the object is actually
mapped or written to file: 
\begin{verbatim}
    exportToTk E(*this,"dummy.tk");
    ConfigDisplay(E.Configuration());
    E.DisplayGraph();
\end{verbatim}
Controller objects which are constructed by the \nt{default constructor}, are
somewhat like clones of the global object \verb/goblinDefaultContext/.

Other than for the subsequent controller instanciations, the construction of
\verb/goblinDefaultContext/ also generates a controller object hash table which
allows to dereference all valid controller and data objects from their handle.



\markright{INTERACTION}
\section{Interaction with Data Objects}
\begin{mymethods}
\begin{verbatim}
class goblinController
{
public:

    THandle         InsertObject(managedObject*);
    void            DeleteObject(THandle);

    goblinRootObject*   ObjectPointer(THandle) const;
    goblinRootObject*   Lookup(THandle) const;
}

class managedObject : public goblinRootObject
{
protected:

    goblinController &CT;
    THandle &H;

public:

    managedObject(goblinController &
                            = goblinDefaultContext);
    goblinController &Context();
    THandle &Handle();
}
\end{verbatim}
\end{mymethods}
Every constructor of a GOBLIN data object subscribes to the controller object
which forms its context. This is managed by the method \verb/InsertObject/
which returns a globally unique {\bf object handle}.

This functionality is transparent to the programmer. If a new class is derived
from \verb/managedObject/ or its descendants, the programmer merely writes
a call \verb/managedObject(CT)/ into all constructors of the new class.
Here, \verb/CT/ denotes the desired context.

The context of a \verb/managedObject/ and its respective handle can be
accessed by the class methods \verb/Context()/ and \verb/Handle()/. Conversely,
controllers can determine the addresses of the hosted data objects from their
handles by means of \verb/ObjectPointer()/. If only the handle \verb/H/ but not
the context is known, \verb/goblinDefaultContext.Lookup(H)/ returns the address.

It is particular useful to store handles instead of addresses if the referenced
object may be deleted within the life time of the referencing object.
\verb/Lookup()/ returns a \verb/NULL/ pointer when dereferencing raises a
segmentation fault!

Internally, all data objects hosted by the same controller object are in a
linked list. Since all controller objects are also in a linked list, it is
possible to enumerate all valid GOBLIN data objects. The method
\verb/DisplayAll()/ is a straight forward application.

To every controller object, one can assign a {\bf master object} by calling
\verb/SetMaster()/ with the handle of the desired master object. This handle
can be questioned by the method \verb/Master()/. The master object determines
the context label and, implicitly, the labels of all unnamed objects in that
context.



\markright{LOGGING}
\section{Logging}
\label{slb_logging}
GOBLIN is fitted with an elaborate logging module. Like the tracing module
which is discussed later, it can be used for debugging, and also for
preparation of runtime examples.


\subsection{Event Handlers}
\begin{mymethods}
\begin{verbatim}
class goblinController
{
private:
    
    unsigned long suppressCount;

public:
    
    void (*logEventHandler)(msgType,TModule,THandle,char*);

    void PlainLogEventHandler(msgType,TModule,THandle,char*);
    void DefaultLogEventHandler(msgType,TModule,THandle,char*);

    void SuppressLogging();
    void RestoreLogging();
}
\end{verbatim}
\end{mymethods}
In order to keep any multitasking code out of the core library, we have
introduced a function pointer \verb/logEventHandler/ which originally
references the method \verb/DefaultLogEventHandler()/. This method writes
all passed logging information to the file or device referenced by
\verb/logStream/. There is an alternative procedure
\verb/PlainLogEventHandler()/ which processes user-readable output to the
same stream but only handles plain message texts.

The messenger and the GOSH shell which are discussed later provide more complex
event handlers. These procedures call \verb/DefaultLogEventHandler()/ in turn.

The method \verb/SuppressLogging()/ saves and deregisters the current event
handler, \verb/RestoreLogging()/ registers the saved event handler again.
Calls must be matching, but it is save to use these methods in a nested way.


\subsection{Writing Log Entries}
\begin{mymethods}
\begin{verbatim}
class goblinController
{
private:

    THandle LogFilter(msgType,THandle,char*);

public:

    char logBuffer[LOGBUFFERSIZE];

    void    LogEntry(msgType,THandle,char*);
    THandle LogStart(msgType,THandle,char*);
    void    LogAppend(THandle,char*);
    void    LogEnd(THandle,char* = NULL);
}
\end{verbatim}
\end{mymethods}
Data objects do not call the registered event handler directly but rather
the context methods listed above. If no handler is registered, nothing happens.
Otherwise the information delivered by the data object is extended by some
structural information and passed to the event handler.

Logging information is grouped into several classes each of which is
represented by a token of the enumeration type \verb/msgType/. Table
\ref{slb_log_select} shows the tokens which are used for the GOBLIN core
library logging information. The tokens associated with errors and with the
GOSH shell are discussed later in this document.

The parameters of \verb/LogFilter()/ are such a token, an object handle and a
text line which has to be logged. It manages the filtering of message types
and handles the event handlers.

The method \verb/LogEntry()/ does nothing else than calling \verb/LogFilter()/
and suppressing messages nested into compound log entries. One can use the
predefined buffer \verb/logBuffer/ to pass the message text but only for
strings up to a size of \verb/LOGBUFFERSIZE-1/.

The methods \verb/LogStart()/, \verb/LogAppend()/ and \verb/LogEnd()/ are used
to grow compound messages from a series of strings. To this end,
\verb/LogFilter()/ and, eventually, the event handler are called with a special
message type \verb/MSG_APPEND/. The handle returned from \verb/LogStart()/ must
be passed for the trailing components. Calls to \verb/LogStart()/ and
\verb/LogEnd()/ must be matching.

% % ----- Hier meine Vorschlag:
% To log a single string the method \verb/LogEntry()/ can be called. The
% parameters of \verb/LogEntry()/ are a token of type \verb/msgType/, an object
% handle and a text line which has to be logged. This method manages the
% filtering of message types and handles the event handlers. Logging will be
% suppressed, if \verb/LogEntry()/ follows a call of \verb/LogStart()/ which is
% not been ended by a call of \verb/LogEnd()/.
% 
% The methods \verb/LogStart()/, \verb/LogAppend()/ and \verb/LogEnd()/ are used
% to grow compound messages from a series of strings. For the beginning of the
% message \verb/LogStart()/ have to be called. It manages the filtering of
% message types and handles the event handlers. The handle returned from
% \verb/LogStart()/ must be passed for the trailing components, which are logged
% by \verb/LogAppend()/ and \verb/LogEnd()/. They use the same filtering and
% event handler setting as \verb/LogStart()/. After calling \verb/LogStart()/ all
% subsequent logging is suppressed until a call of \verb/LogEnd()/ with the
% handle returned by \verb/LogStart()/. Thus, calls to \verb/LogStart()/ and
% \verb/LogEnd()/ must be matching.
% 
% For all these methods, one can use the predefined buffer \verb/logBuffer/
% to pass the message text but only for strings up to a size of
% \verb/LOGBUFFERSIZE-1/.
% 
% % Ich finde das Detail, dass alle vier Log-Methoden die Funktion LogFilter()
% % aufrufen, kann weggelassen werden. Der interessierte Programmierer kann
% % sich den Quellcode anschauen, der normale Programmierer kann sowieso nicht
% % auf die private Methode zugreifen. Statt der Beschreibung von LogFilter()
% % waere ein Hinweis, dass alle vier Methoden den userLogEventHandler()
% % aufrufen, vielleicht nuetzlich.
% % ----- Ende -----

To prevent obvious overhead, data objects also implement a method
\verb/LogEntry()/ which substitutes the own object handle in the context
method. Compound messages can be written by data object methods likewise.

The method \verb/Error()/ calls the log event handler with a message composed
from the two strings passed as arguments. The first string describes the scope
where the exception occured and the second one describes the exceptional
situation. All information about the most recent exception is saved internally.
Finally, \verb/Error()/ throws a C++ exception depending on the delivered
\verb/msgType/ token. See Chapter \ref{clb9} for more details.


\newpage
\subsection{Structured Source Code}
\begin{mymethods}
\begin{verbatim}
class goblinController
{
private:

    TModule nestedModule[MAX_MODULE_NESTING];
    int     moduleNestingLevel;

public:
    
    char logDepth;
    char logLevel;

    void IncreaseLogLevel();
    void DecreaseLogLevel();

    enum TFoldOptions {
        NO_INDENT = 1,
        SHOW_TITLE = 2
    };

    void OpenFold(TModule,TOption = 0);
    void CloseFold(TModule,TOption = 0);
}
\end{verbatim}
\end{mymethods}
The event handlers do some alignment of the log entries depending on the
current \verb/logLevel/ which can be manipulated by calls to
\verb/IncreaseLogLevel()/ and \verb/DecreaseLogLevel()/. The maximum
indentation level is specified by \verb/logDepth/.

In the same way, \verb/OpenFold()/ and \verb/CloseFold()/ manipulate the
parameter \verb/moduleNestingLevel/ and set the current code module context:
\verb/OpenFold()/ saves the new context on the stack \verb/nestedModule/ (if
the maximum depth \verb/MAX_MODULE_NESTING/ has been reached, the context
does not change effectively) and \verb/CloseFold()/ recovers the parent
context.

If the \verb/NO_INDENT/ option is specified, \verb/OpenFold()/
[\verb/CloseFold()/] implicitly calls \verb/IncreaseLogLevel()/
[\verb/DecreaseLogLevel()/]. The option \verb/SHOW_TITLE/ causes
\verb/OpenFold()/ to send the module name to the log event handler.

Note that data objects also implement \verb/OpenFold()/ and \verb/CloseFold()/
methods which cover the described functionality and, in addition, start and
stop the module timers. See Section \ref{slb_modules} for more details.


\subsection{Filtering the output}
The information which is actually logged can be filtered by several context
parameters. The available flags are listed in Table \ref{slb_log_select}.
Note that all values higher than the default values may result in a tremendous
increase of logging information. But for rather small problem instances, the
options \verb/logMeth==2/ and \verb/logRes==2/ allow a good understanding of
the various optimization algorithms. Other than the preliminary version of the
logging module, the output is now filtered by the controller object internally.

The flags \verb/logWarn/ and \verb/logMem/ have been added for debugging
purposes. The flag \verb/logMem/ is discussed in Section \ref{slb530}. The flag
\verb/logWarn/ concerns GOBLIN exceptions (see Chapter \ref{clb9}) which do
not affect the general data integrity. More explicitly:
\begin{itemize}
\item By \verb/Error(MSG_WARN,..)/, an error message is printed only if
\verb/logWarn/ is set but no exception is raised.
\item By \verb/Error(ERR_CHECK,..)/, an error message is printed only if
\verb/logWarn/ is set and an exception \verb/ERCheck/ is raised in any
circumstances.
\item By \verb/Error(ERR_REJECTED,..)/ an exception \verb/ERRejected/ is raised
and an error message is printed independently of the value of the flag
\verb/logWarn/.
\end{itemize}
This is so since the exception class \verb/ERCheck/ does not necessarily
indicate errors. For example, a call \verb/FlowValue(s,t)/ returns an exception
\verb/ERCheck/ if the subgraph does not form an $st$-flow. Algorithms may
check feasibility by this method, and treat the exception as a standard
functionality. If tests are needed several times by an algorithm,
the log file should not include corresponding error messages.

There is pragma \verb/_LOGGING_/ which is defined in the file \verb/config.h/.
This definition may be omitted in order to improve the performance.
Note, however, that only a certain part of the logging module is compiled
conditionally, namely the information which is assigned with \verb/LOG_METH2/,
\verb/LOG_RES2/, \verb/MSG_WARN/, and some of the \verb/IncreaseLogLevel()/ and
\verb/DecreaseLogLevel()/ statements.


\subsection{Selection of logging information}
\label{slb_log_select}
\medskip
\begin{center}
\begin{tabular}{|p{1.7cm}|p{0.8cm}|p{2.5cm}|p{5.8cm}|}
\hline
{\bf Variable} & {\bf Def} & {\bf Token} & {\bf Information} \\
\hline
\hline
\verb/logMeth/  & 1 & LOG\_METH, LOG\_METH2 & Course of algorithms (two levels) \\
\verb/logMem/   & 0 & LOG\_MEM, LOG\_MEM2   & Memory allocations (two levels) \\
\verb/logMan/   & 1 & LOG\_MAN              & Object manipulations \\
\verb/logIO/    & 1 & LOG\_IO               & File management \\
\verb/logRes/   & 1 & LOG\_RES, LOG\_RES2   & Computational results (two levels) \\
\verb/logTimers/& 1 & LOG\_TIMERS           & Timer statistics \\
\verb/logGaps/  & 1 & LOG\_GAPS             & Duality gaps \\
\verb/logWarn/  & 0 & MSG\_WARN             & Warnings \\
\hline
\end{tabular}
\end{center}



\newpage
\markright{METHOD SELECTION}
\section{Method Selection}
\begin{mymethods}
\begin{verbatim}
class goblinController
{
    int     methFailSave;
    int     methAdjacency;
    int     methDSU;
    int     methPQ;
    int     methModLength;

    int     methGeometry;

    int     methSPX;
    int     methMST;
    int     methMXF;
    int     methMCFST;
    int     methMCF;
    int     meth1Tree;
    int     methMaxBalFlow;
    int     methBNS;
    int     methMinCBalFlow;
    int     methPrimalDual;
    int     methTSP;

    int     methLocal;
    int     methSolve;

    int     maxBBIterations;
    int     maxBBNodes;
}
\end{verbatim}
\end{mymethods}
This section merely summarizes the method selector flags which have been
described with the respective problem solver methods. For details, we refer to
the Chapters \ref{clb4} and \ref{clb_proto}.


\newpage
\subsection{Optional Data Structures}
\label{slb_options_data}
\medskip
\begin{center}
\begin{tabular}{|p{3cm}|p{1cm}|p{8cm}|}
\hline
{\bf Variable} & {\bf Value} & {\bf Description} \\
\hline
\hline
\verb/methFailSave/ & {\bf 0} & No special certificate checking \\
                    & 1 & Network flow and matching solvers are forced \\
                    &   & to verify a reduced costs optimality criterion \\
\hline
\verb/methAdjacency/& 0 & Search incidence lists \\
                    & {\bf 1} & Generate hash table \\
\hline
\verb/methDSU/      & 0 & Path compression disabled \\
                    & {\bf 1} & Path compression enabled \\
\hline
\verb/methPQ/       & 0 & Use basic priority queue \\
                    & {\bf 1} & Use binary Heaps \\
                    & 2 & Use Fibonacci Heaps \\
\hline
\verb/methModLength/& 0 & Recursive computation of reduced length labels \\
                    & {\bf 1} & Explicit data structure \\
\hline
\end{tabular}
\end{center}
\bigskip


\subsection{Solver Options for NP-hard problems}
\label{slb_options_hard}
\begin{center}
\begin{tabular}{|p{3cm}|p{1cm}|p{8cm}|}
\hline
{\bf Variable} & {\bf Value} & {\bf Description} \\
\hline
\hline
\verb/methSolve/    & 0 & Apply only heuristics \\
                    & 1 & Compute lower and upper bounds \\
                    & {\bf 2} & Apply branch and bound \\
\hline
\verb/methLocal/    & 0 & Apply only construction heuristics \\
                    & {\bf 1} & Apply local search heuristics \\
\hline
\verb/maxBBIterations/ & {\bf 100} & Maximum number of branch and bound \\
                    & & iterations divided by 1000 \\
\hline
\verb/maxBBNodes/   & {\bf 20} & Maximum number of active leaves in \\
                    & & the branch tree divided by 100 \\
\hline
\verb/methCandidates/& {\bf -1} & Minimum degree in the candidate graph. \\
                    & & If negative, candidate search is disabled. \\
                    & & Used for TSP and weighted matching. \\
\hline
\end{tabular}
\end{center}


\newpage
\subsection{Problem Specific Solver Options}
\label{slb_options_solver}
\medskip
\begin{center}
\begin{tabular}{|p{3cm}|p{1cm}|p{8cm}|}
\hline
{\bf Variable} & {\bf Value} & {\bf Description} \\
\hline
\hline
\verb/methSPX/      & {\bf 0} & FIFO label correcting \\
                    & 1 & Dijkstra \\
                    & 2 & Bellman/Ford \\
                    & 3 & BFS \\
\hline
\verb/methMST/      & 0 & Prim \\
                    & {\bf 1} & Enhanced Prim \\
                    & 2 & Kruskal \\
\hline
\verb/methMXF/      & 0 & Successive augmentation \\
                    & {\bf 1} & Dinic \\
                    & 2 & Push/Relabel, FIFO \\
                    & 3 & Push/Relabel, Highest Order \\
                    & 4 & Capacity scaling \\
\hline
\verb/methMCFST/    & {\bf 0} & Revised shortest path \\
                    & 1 & Shortest path \\
                    & 2 & Capacity scaling (Not implemented) \\
                    & 3 & Transformation to circulations \\
\hline
\verb/methMCF/      & 0 & Klein (cycle canceling) \\
                    & {\bf 1} & Cost scaling \\
                    & 2 & Cost scaling with $\epsilon$-tightening \\
                    & 3 & Minimum mean cycle canceling \\
                    & 4 & Transformation to $st$-flows \\
\hline
\verb/meth1Tree/    & {\bf 0} & Ordinary spanning tree \\
                    & 1 & Minimum $1$-trees \\
\hline
\verb/methMaxBalFlow/& 0 & Successive augmentation \\
                    & 1 & Phase-Ordered augmentation \\
                    & {\bf 2} & Phase-Ordered augmentation with look-ahead \\
                    & 3 & Phase-Ordered augmentation with look-ahead \\
                    &   & and augmentation \\
                    & 4 & Capacity scaling \\
                    & 5 & Max-Flow start up \\
\hline
\verb/methBNS/      & {\bf 0} & Breadth-First \\
                    & 1 & Depth-First Heuristics \\
                    & 2 & Depth-First Heuristics \\
                    & 3 & Breadth-First Heuristics\\
\hline
\end{tabular}

\newpage
\begin{tabular}{|p{3cm}|p{1cm}|p{8cm}|}
\hline
{\bf Variable} & {\bf Value} & {\bf Description} \\
\hline
\hline
\verb/methMinCBalFlow/& 0 & Primal-Dual \\
                    & {\bf 1} & Enhanced primal-dual \\
\hline
\verb/methPrimalDual/& 0 & Restart BNS after each dual update \\
                    & 1 & Restart BNS after changes in the shrinking family \\
                    & {\bf 2} & Restart BNS after blossom expansion \\
\hline
\verb/methTSP/   & {\bf 0} & Random tour \\
                    & 1 & Insertion heuristics \\
                    & 2 & Tree heuristics \\
                    & 3 & Christofides (undirected graphs only) \\
\hline
\end{tabular}
\end{center}
\bigskip



\markright{TRACING}
\section{Tracing}
\label{slb_tracing}
\begin{mymethods}
\begin{verbatim}
class goblinController
{
    int     traceLevel;
    int     threshold;
    int     fileCounter;
    int     traceStep;
    int     traceData;
    int     commLevel;
    int     breakLevel;

    void    Ping(THandle,unsigned long);
    void    ResetCounter();
    void    IncreaseCounter();
    ostream &Display();
}
\end{verbatim}
\end{mymethods}
The tracing functionality is a valuable tool both for debugging and for
visualising of the course of an algorithm. The tracing can be controlled
by the following members of the controller object:

A class method can be traced only if it defines a \nt{breakpoint}. By this,
we denote a method call \verb/CT.Ping(H,priority)/ which does the following:

The handle \verb/H/ specifies the object to be traced.
The value of \verb/priority/ is added to the current value of
\verb/traceCounter/. If the new value of the counter exeeds \verb/traceStep/,
then \verb/traceCounter/ is reset to zero, and some information
is written to an output device. To this situation, we refer as a
\nt{tracing point}. If one has \verb/traceStep == 1/, every breakpoint triggers
off a tracing operation.

The concrete output depends on the value of \verb/traceLevel/. Table
\ref{slb_trace_level} gives an overview. A higher trace level generally
generates more tracing information. Levels 3 and 4 are reasonable for small
examples only, and may generate several megabyte of tracing files.

It is possible to suppress the first $k$ tracing operations
by setting the context variable \verb/threshold/ to $k$. Note that any
error prompt contains a line
\begin{verbatim}
    Before tracing point #...
\end{verbatim}
which allows to debug large problems graphically by setting \verb/threshold/
to a reasonable value.

The message \verb/Display()/ which is mentioned in Table \ref{slb_trace_level}
is available for every GOBLIN data object. In order to trace an object, its
class must implement the \verb/Display()/ method. So far, graph objects can be
displayed both graphically and textually, and most data structures can
be displayed textually. If textual output is configured, the output stream
is obtained by the context method \verb/ostream & goblinController::Display()/.

Otherwise a so-called {trace file} is written which, by default, consists of
the graph object and the context information with some modifications in the
GOBLIN native format. The file name is the concatenation of the context label
obtained by the method \verb/Label()/, the current value of \verb/fileCounter/
and one of the extensions \verb/.gob/, \verb/.fig/ or \verb/.tk/. Every trace
file export will trigger off an increase in the value of \verb/fileCounter/. 

Note that the value of \verb/priority/ has strong impact on the quality of
a tracing session. We propose a value of \verb/1/ if the expected time
between two breakpoints is $O(1)$, and a value of \verb/n*m/ if the expected
time is $O(nm)$, for example.

A data object can be traced only if its class implements a
method \verb/Display()/ which should show relevant information
encapsulated into the object.
The object to be displayed should reveal some relevant information about the
course of an algorithm, and the breakpoint should be placed right behind an
update of this object.

Sometimes, it may be useful to have more than one breakpoint in order to trace
different objects. For example, the Dinic maxflow algorithm contains two
breakpoints \verb/CT.Ping(Aux.Handle(),m)/ and \verb/CT.Ping(Handle(),m)/.
The first one is placed between the construction of the layered auxiliary
network \verb/Aux/ (which actually is displayed) and the augmentation step.
The second breakpoint displays the flow network which has been augmented just
before.

To use the tracing functionality and the graphical display, make sure that the
\verb/_TRACING_/ pragma is defined in \verb/config.h/. If this pragma is
undefined, the breakpoints are still found, but only trace level 1 is available.


\subsection{Trace Level Options}
\label{slb_trace_level}
\medskip
\begin{center}
\begin{tabular}{|p{1.5cm}|p{10.5cm}|}
\hline
{\bf Level} & {\bf Description} \\
\hline
\hline
0 & No output is written \\
\hline
{\bf 1} & A dot (\verb/./) is written to the standard output device \\
\hline
2 & As before, but a method \verb/Display()/ is called by the constructors
    of classes which support this functionality.
    \verb/Display()/ either writes information in tabular form
    to the standard output device or graphical information to
    trace files which can viewed via Xfig or, GOBLET or the Tcl/Tk script
    \verb/display/. \\
\hline
3 & The method \verb/Display()/ is called at each tracing point. \\
\hline
4 & The method \verb/Display()/ is called at each tracing point.
    Every output must be prompted by the user. Only useful
    for console applications. \\
\hline
\end{tabular}
\end{center}
\bigskip


\subsection{Tracing Data Structures}
\label{slb_trace_data}

The GOBLIN data structures discussed in Chapter \ref{clb4} can be traced
separately from general objects by setting the \verb/traceData/ flag.
In that case, every elementary operation on the used data structures is
subject to graphical tracing. The tracing mechanism is restricted to binary
heaps, Fibonnacci heaps and disjoint set families. Stacks and queues do not
produce any graphical output.



\newpage
\markright{GRAPHICAL DISPLAY}
\section{Graphical Display}
\label{slb_display}
\begin{mymethods}
\begin{verbatim}
class goblinController
{
    int    displayMode;

    int    xShift;
    int    yShift;
    double xZoom;
    double yZoom;

    int    nodeSize;
    int    nodeStyle;
    int    nodeLabels;
    int    nodeColours;

    int    arcStyle;
    int    arcLabels;
    int    arcLabels2;
    int    arcLabels3;
    int    arrows;
    int    arrowSize;

    int    subgraph;
    int    predecessors;
    int    legenda;

    char*  nodeFormatting;
    char*  arcFormatting;
}
\end{verbatim}
\end{mymethods}
Every GOBLIN data object accepts a message \verb/Display()/ which may write
some tracing information to the standard output device or to a trace file.
Graph objects admit textual output which is generated by
\verb/TextDisplay()/, but also graphical output which is
generated by \verb/Display()/.

The latter method may call \verb/TextDisplay()/ again, but may
also write trace files which can be read by GOBLET or the Xfig drawing tool.
More explicitly, the output depends on the context variable \verb/displayMode/
which admits the alternatives shown in Table \ref{slb_display_mode}. 

Trace files either consist of the graph object, its current potential solutions
and context information in the GOBLIN native format, or an explicit canvas,
depending on the value of \verb/diplayMode/. See Section \ref{slb_tracing} for
the file naming policy.


\subsection{Display Mode Options}
\label{slb_display_mode}
\medskip
\begin{center}
\begin{tabular}{|p{1.2cm}|p{10.9cm}|}
\hline
{\bf Mode} & {\bf Description} \\
\hline
\hline
0 & Textual output \\
\hline
1 & Graphical output: A \verb/*.fig/ file is written and Xfig is called. \\
\hline
2 & Graphical output: A \verb/*.tk/ file is written and the tk script
    \verb/display/ is called. \\
\hline
{\bf 3} & Graphical output: A \verb/*.gob/ file is written which is processed 
    by the GOBLET graph browser. \\
\hline
\end{tabular}
\end{center}
\bigskip

\subsection{Export of Graphical Information}

GOBLIN provides two export filters for graph layouts which are implemented by
the classes \verb/exportToTk/ and \verb/exportToXFig/ respectively. As the names
suggest, the first class generates some kind of Tcl/Tk scripts while the second
class generates canvases for the xFig drawing tool. The xFig files can be
converted to other graphics formats by using the tool \verb/fig2dev/ which
usually forms part of the xFig distribution.

Note that the Tk files generated by \verb/exportToTk/ cannot be executed directly,
but are input to the GOBLET graph browser. If you want to display a trace file
on screen without using GOBLET, you can use the small Tk script \verb/display/
which does not require the complete installation of the GOSH interpreter. This
script is called if \verb/displayMode=2/ is configured. See Section
\ref{slb_standard_formats} for a description of the explicit canvas export methods.


\newpage
\subsection{Device Independent Layout}
\begin{mymethods}
\begin{verbatim}
class canvasBuilder
{
protected:

    char* predColour;
    char* inftyColour;

    long int width;
    long int height;

public:

    virtual void canvasBuilder(abstractMixedGraph&,float);

    long int        CanvasCX(TNode v);
    long int        CanvasCY(TNode v);
    long int        AlignedCX(TNode u,TNode v);
    long int        AlignedCY(TNode u,TNode v);

    goblinController &Configuration();

    virtual void    DisplayGraph();

    char*           ArcLabel(TArc,int);
    char*           NodeLabel(TNode);
    char*           ArcLegenda(int);
    char*           NodeLegenda(char*);
    char*           FixedColour(TNode);
    char*           SmoothColour(TNode);

    virtual void    DisplayArc(TArc) = 0;
    virtual void    DisplayNode(TNode) = 0;
    virtual void    DisplayLegenda(long int,long int,
                                        long int) = 0;
}
\end{verbatim}
\end{mymethods}
The class \verb/canvasBuilder/ organizes the device independent drawing
of GOBLIN graph objects. This class is abstract, and instances are implicitly
generated by the method \verb/abstractMixedGraph::Display()/ which also calls
a virtual method \verb/ConfigDisplay()/.

The \verb/canvasBuilder/ constructor generates a clone of the controller
object. This clone, the configuration, can be accessed by the method
\verb/Configuration()/. The method \verb/ConfigDisplay()/ which is called with
the display configuration makes some class-dependent changes of the layout
parameters.

The class \verb/canvasBuilder/ provides some other ressources such as
colours and the bounding box. This guarantees that the graphical output
generated by the classes \verb/exportToTk/ and \verb/exportToXFig/ has the same
appearance. The colours \verb/predColour/ and \verb/inftyColour/ are used for
the display of predecessor arcs and the display of unreachable nodes
respectively. The method \verb/FixedColour()/ provides an explicit scheme for the
node and arc colours. \verb/SmoothColour()/ can be used if the fixed colours are
not exhausted (20 colours are defined) of if adjacent colour indices should
be displayed with similar colours. All returned strings are in 24 bit rgb format.

\bigskip
\begin{figurehere}
\begin{center}
\epsfxsize=9cm
\epsfbox{display1.eps}
\vspace{0.5cm}
\caption{\label{flb_display1}A Graph Layout with Subgraph and Predecessor Arcs}
\end{center}
\end{figurehere}

The class \verb/canvasBuilder/ also supplies with the node and the arc labels
and the labels of the legenda. Note that two sets of arc labels can be
displayed simultaniously, that is, the \verb/arcLabels/ or \verb/arcLabels2/
option must be passed to the methods \verb/ArcLabel/ and \verb/ArcLegenda/
explicitly. Figure \ref{flb_maxflow} shows a graph layout with two sets of
arc labels and a legenda.

The layout is based on the geometric information which is encapsulated into the
graph object. Up to the layout of trees, GOBLIN does not compute any graph
embeddings. If no embedding is present, the graph object cannot be viewed.
The parameters \verb/xShift/, \verb/xZoom/, \verb/yShift/
and \verb/yZoom/ define an affine transformation of this embedding, and the
transformed coordinates can be accessed by \verb/CanvasCX/ and \verb/CanvasCY/.

The parameter \verb/legenda/ enables or disables the generation of a legenda.
This legenda shows which node and arc labels are displayed in the layout.
If \verb/legenda==0/, no legenda is printed. Otherwise, the value of
\verb/legenda/ specifies the space between the graph and the legenda.

The other layout parameters, together with their possible alternatives
(defaults boldfaced), are listed in the following subsections. The layout
of graph arcs deserves some further statements:

If the node \verb/x=ArcLabelAnchor(a)/ is undefined, the arc is drawn as a straight
line between the geometrical embedding of the two end nodes \verb/u/ and
\verb/v/, and the potential label is aligned with the center of this line.
Otherwise, the label is aligned with the transparent node \verb/x/.

If \verb/y=ThreadNode(x)/ is undefined, the arc is drawn as line between
\verb/u/ and \verb/v/ again. Finally, if \verb/y!=NoNode/, the interpolation
points are \verb/y/ and the iterated points \verb/y=ThreadNode(y)/ (until
\verb/y==NoNode/ is reached). This list of points either defines a spline or a
polyline object in the graph drawing.

The end nodes of a spline or polyline object are aligned with the graph
node objects which depend on the \verb/nodeStyle/ and the \verb/nodeSize/
parameters. This is done by the methods \verb/AlignedCX/, \verb/AlignedCY/
which shift the second nodes coordinates in the direction of the first graph
node so that it becomes visible.


\subsection{Formatting Arc and Node Labels}
There are two ways how labels can be formatted: By setting the format strings
\verb/arcFormatting/ and  \verb/nodeFormatting/, one can produce almost
universal labels. If these strings are left blank, the node and arc labels
are computed in the way known from earlier releases. 

In the format strings, only two characters are special: The token \verb/%1/
refers to the current values of the context variables \verb/arcLabels/ or
\verb/nodeLabels/ respectively. The tokens \verb/#1/, \verb/#2/, .. each
represent one of the potential values of \verb/arcLabels/ and \verb/nodeLabels/
as listed in the Tables \ref{slb_arc_display} and \ref{slb_node_display}.
As a simple and useful example,
\begin{quote}
\begin{verbatim}
arcFormatting = "$e_#7$"
\end{verbatim}
\end{quote}
would result in a set of arc labels \verb/$e_1$/, \verb/$e_2$/, .. in the
GOBLIN canvas. If this canvas is imported to LaTeX, the labels $e_1, e_2,\dots$
would result. If one sets
\begin{quote}
\begin{verbatim}
arcFormatting = "%1 [%2,%3]"
\end{verbatim}
\end{quote}
the \verb/ConfigDiplay()/ methods can determine which data shall be displayed
by setting the variables \verb/arcLabels/, \verb/arcLabels2/, \verb/arcLabels3/.
The appearance is left to the user. In this example, a label \verb/1.5 [1,3]/
may result, a flow value with according capacity bounds.

The default layout of arc labels can be expressed as \verb|%1/%2/%3| provided
that none of the context variables \verb/arcLabels/, \verb/arcLabels2/,
\verb/arcLabels3/ is unset. If \verb/arcLabels/ is unset, the equivalent format
string is \verb|%2/%3|. 


\subsection{Arc Display Options}
\label{slb_arc_display}
\medskip
\begin{center}
\begin{tabular}{|p{2.5cm}|p{1.2cm}|p{8.0cm}|}
\hline
{\bf Parameter} & {\bf Value} & {\bf Description} \\
\hline
\hline
\verb/arcStyle/     & {\bf 0} & lines and polygons \\
                    & 1 & interpolated splines \\
                    & 2 & pipes (othogonal polygons) \\
\hline
\verb/arcLabels/,   & {\bf 0} & no labels \\
\verb/arcLabels2/,  & 1 & indices $0,1,2,...$\\
\verb/arcLabels3/   & 2 & capacities \\
                    & 3 & subgraph (flow) \\
                    & 4 & length labels \\
                    & 5 & reduced length labels \\
                    & 6 & lower capacity bounds \\
                    & 7 & indices $1,2,3,...$ \\
\hline
\verb/arrows/       & {\bf 0} & aligned with node objects \\
                    & 1 & centered \\
\hline
\verb/subgraph/     & 0 & draw predecessor arcs only \\
                    & 1 & draw non-empty arcs only \\
                    & 2 & draw predecessor arcs only \\
                    & {\bf 4} & draw all arcs \\
\hline
\verb/predecessors/ & 0 & nothing special \\
                    & {\bf 1} & highlight predecessor arcs \\
\hline
\end{tabular}
\end{center}
\bigskip


\subsection{Node Display Options}
\label{slb_node_display}
\medskip
\begin{center}
\begin{tabular}{|p{2.5cm}|p{1.2cm}|p{8.0cm}|}
\hline
{\bf Parameter} & {\bf Value} & {\bf Description} \\
\hline
\hline
\verb/nodeStyle/    & 0 & dots \\
                    & {\bf 1} & circles \\
                    & 2 & boxes \\
\hline
\verb/nodeLabels/   & 0 & no labels \\
                    & {\bf 1} & indices $0,1,2,...$\\
                    & 2 & distance labels \\
                    & 3 & node potentials \\
                    & 4 & node colours \\
                    & 5 & node demands \\
                    & 6 & indices $1,2,3,...$ \\
\hline
\verb/nodeColours/  & 0 & no colours \\
                    & {\bf 1} & highlight nodes with finite distance labels \\
                    & 2 & node colours \\
                    & 3 & node demands \\
                    & 4 & node partition \\
\hline
\end{tabular}
\end{center}
\bigskip


\subsection{General Layout Options}
\label{slb_layout_options}
\medskip
\begin{center}
\begin{tabular}{|p{2cm}|p{2.7cm}|p{7cm}|}
\hline
{\bf Parameter} & {\bf Default Value} & {\bf Description} \\
\hline
\hline
\verb/xShift/   & 400 & Shift on the ordinate \\
\hline
\verb/xZoom/    & 150 & Scaling of the ordiante \\
\hline
\verb/yShift/   & 400 & Shift on the abscissa \\
\hline
\verb/yZoom/    & 150 & Scaling of the abscissa \\
\hline
\verb/nodeSize/ & 100 & Diameter of graph nodes \\
\hline
\verb/arrowSize/& 300 & Width of arrows \\
\hline
\verb/legenda/  & 0   & Separator for the legenda. \\
                & & If zero, no legenda is generated \\
\hline
\verb/nodeSep/  & 10  & Grid size for the graph nodes. \\
                & & Used in several graph layout methods \\
\hline
\verb/bendSep/  & 5  & Grid size for the bend nodes. \\
                & & Used in AutoArcAlignment() \\
\hline
\verb/fineSep/  & 2  & Grid size for node and arc labels. \\
                & & Currently used by the browser only \\
\hline
\end{tabular}
\end{center}
\bigskip



\newpage
\section{Random Instance Generators}
\label{slb_random}
\begin{mymethods}
\begin{verbatim}
class goblinController
{
    unsigned long   Rand(unsigned long);
    TFloat          UnsignedRand();
    TFloat          SignedRand();

    int     randMin;
    int     randMax;
    
    int     randUCap;
    int     randLCap;
    int     randLength;
    int     randGeometry;
    int     randParallels;
}
\end{verbatim}
\end{mymethods}
Many instance generators are prepared to generate random arc and node labels
depending on which of the context flags \verb/randLength/, \verb/randUCap/, 
\verb/randLCap/ and \verb/randGeometry/ are set. The flag \verb/randParallels/
enables or disables the generation of parallel arcs.

Random labels can be generated by every graph constructor method and by every
call to the method \verb/InsertArc(TNode,TNode)/ and \verb/InsertNode()/. If
you do not want to generate labels, keep in mind to unset the respective flags.

Edge length labels and node coordinates are generated by the method
\verb/SignedRand()/ and arc capacities are genrated by \verb/UnsignedRand()/.
The numbers returned by \verb/SignedRand()/ are equally distributed integers
from the interval \verb/[randMin,..,randMax]/. The numbers returned
by \verb/UnsignedRand()/ are in the same range if \verb/randMin/ is
non-negative and from the interval \verb/[0,..,randMax]/ otherwise.
A method call \verb/Rand(k)/ returns equally distributed
integers from the interval \verb/[0,..,k-1]/.



\newpage
\section{Runtime Configuration}
\label{slb_rconf}
\begin{mymethods}
\begin{verbatim}
class goblinController
{
    void    Configure(int ParamCount,char* ParamStr[]);
}
\end{verbatim}
\end{mymethods}
Throughout this chapter, we have described the various configuration
parameters which are available in GOBLIN. We finally need to explain how the
controller objects are configured in practice:

If you call GOBLIN from within a C++ program, you can access all variables
directly. If you call the library from a GOSH script, the GOBLIN context
variables have a prefix \verb/goblin/. For example, the tracing module is
switched off by the command \verb/set goblinTraceLevel 0/.
 
Sometimes, it is more efficient to call the method \verb/Configure/ which can
change several parameters in one pass. This method is called with an array of
strings each of which represents a variable name, value or a general option.
One can set a context variable by adding a parameter which is composed from
\verb/-/, the variable name and the desired value.

The \verb/Configure()/ method can be called from any C/C++ main routine and then
passes the console input to GOBLIN. It can also be called from GOSH scripts.
For example, the GOBLIN branch and bound module is enabled by the command
\verb/goblin configure -methSolve 2/.

The logging module admits some general settings which can be selected from the options
\verb/-silent/, \verb/-report/, \verb/-details/ and \verb/-debug/ with increasing
order of logging information.

Note that string context variables are generally read-only in the GOSH shell.
Strings can be set with the \verb/goblin configure/ command only. Even from
C++ level it is recommended to use this mechanism to avoid inconsistencies
with the memory management.



\cleardoublepage
\markboth{THE MESSENGER}{THE MESSENGER}
\chapter{The Messenger}
\thispagestyle{fancy}
\label{clb_msg}

A messenger object manages the interaction of two threads of execution, namely
a problem solver and a user interface. It implements methods to browse and edit
the logging information, provides the possibility to interrupt the solver from
the user interface, and it keeps control of the trace files.

Internally, the messenger is \nt{thread safe}, that is, its data structures
are locked by so-called \nt{semaphores} to prevent different threads from
accessing the data at the same time. The solver thread takes semaphores for a
short period only, but the user interface may block the solver in order to read
some volatile information and to make online changes.

The GOBLIN core library does not utilise semaphores at all. But for the GOSH
shell the function pointers \verb/solverStopSignalHandler/,
\verb/logEventHandler/ and \verb/traceEventHandler/ essentially refer to
messenger methods. Hence editing a graph which is subject to some computation
can (but does not necessarily) corrupt the object and the solver process.


\newpage
\markright{SOLVER MANAGEMENT}
\section{Problem Solver Management}
\label{slb_solver_signals}
\myinclude\verb/messenger.h/
\begin{mymethods}
\begin{verbatim}
class goblinMessenger
{
    bool        SolverRunning();
    bool        SolverIdle();
    void        SolverSignalPending();
    void        SolverSignalStarted();
    void        SolverSignalStop();
    void        SolverSignalIdle();
}
\end{verbatim}
\end{mymethods}
The first goal of task communication is to force a solver to stop the
optimization with a suboptimal solution. The complete schedule is as follows:
\begin{itemize}
\item The user interface checks if the flag \verb/SolverIdle()/ is true and,
    if so, calls \verb/SolverSignalPending()/ and then sets up a new thread of
    execution. At this stage, both \verb/SolverIdle()/ and \verb/SolverRunning()/
    are false.
\item The new thread calls \verb/SolverSignalStarted()/ and then the solver
    method. Now \verb/SolverRunning()/ is true.
\item Occasionally, the user interface calls \verb/SolverSignalStop()/ so that
    the flag \verb/SolverRunning()/ becomes false again.
\item The solver thread stops the computation before time (if the core library
    includes \verb/solverStopSignalHandler/ retrieval operations). The thread
    calls \verb/SolverSignalIdle()/ and then exits.
\end{itemize}
The messenger also allows to interrupt the solver temporarily, and this feature
is described in Section \ref{slb_msg_trace}.


\newpage
\markright{MESSAGE QUEUE}
\section{The Message Queue}
\label{slb_msg_queue}
\myinclude\verb/messenger.h/
\begin{mymethods}
\begin{verbatim}
class goblinMessenger
{
    void        MsgAppend(msgType,TModule,THandle,char*);

    void        MsgReset();
    bool        MsgEOF();
    bool        MsgVoid();
    void        MsgSkip();

    char*       MsgText();
    msgType     MsgClass();
    TModule     MsgModule(); 
    int         MsgLevel();
    THandle     MsgHandle();
}
\end{verbatim}
\end{mymethods}
The message queue buffers the most recent log entries generated by the solver
thread. It is just large enough to fill a single screen, but does not occupy
much system ressources. The log event handler also writes an incremental log
file for later evaluations.

A new log entry is added to the queue by calling \verb/MsgAppend()/ which takes
the class of information and an object handle as parameters. If the class is
\verb/MSG_APPEND/, the passed string is appended at the most recent log entry.
Otherwise the oldest log entry on the queue is deleted and replaced by the new
data.

The other functions are needed by the user interface for reading the messages
which are currently queued. The method \verb/MsgReset()/ initializes a pointer
to the oldest message in the queue. The method \verb/MsgSkip()/ then moves from
one entry to another. If no more unread log entries exist, the flag
\verb/MsgEOF()/ becomes true. The flag \verb/MsgVoid()/ indicates if no message
is queued at all.

The following properties of the currently referenced message can be retrieved:
The message text, the class of information, the module index and the object
handle which all have been passed by the respective \verb/LogEntry()/ and
\verb/MsgAppend()/ calls. The \verb/MsgLevel()/ is the context parameter
\verb/logLevel/ at the time of writing the log entry.

In later releases, it will be possible to switch between the described online
mode and a mode for importing the incremental log file into the messenger and
editing.


\markright{TRACING}
\section{Tracing}
\label{slb_msg_trace}
\myinclude\verb/messenger.h/
\begin{mymethods}
\begin{verbatim}
class goblinMessenger
{
    void        TraceAppend(char*);
    void        TraceSemTake();

    char*       TraceFilename();
    bool        TraceEvent();
    void        TraceUnblock();
}
\end{verbatim}
\end{mymethods}
The tracing module has two ressources each of which is locked by an own
semaphore: A list of trace file names and a flag which indicates if there are
unhandled trace events and which can be read by calling \verb/TraceEvent()/.

To the list of trace files, the solver thread declares every trace file name by
calling \verb/TraceAppend()/. This also sets the event flag. The solver thread
then calls \verb/TraceSemTake()/ before continuing its computations.
The latter method returns only if the trace event is handled in the user
interface.

The user interface handles a trace event as follows: It reads the last trace
file name by calling \verb/TraceFileName()/ and then calls \verb/TraceUnblock()/
which effectively resets the event flag.

We mention that \verb/TraceAppend()/ and \verb/TraceFileName()/ allocate copies
of the file name string and that the string returned by \verb/TraceFileName()/
must be disallocated by the calling context.
 
Some future work is at hand: It should be possible to read the complete
list of trace file names, and this list should be editable in the same way as
the message queue.



\cleardoublepage
\markboth{LINEAR PROGRAMMING SUPPORT}{LINEAR PROGRAMMING SUPPORT}
\chapter{Linear Programming Support}
\thispagestyle{fancy}
\label{clb_lpsolve}
In order to allow development of this library beyond the scope of pure
combinatorial algorithms, the author has decided to add some support for
linear and integer programming techniques. This currently includes:
\begin{itemize}
\item An abstract class \verb/goblinILPWrapper/ which models mixed integer
    problems and the interface to the GOBLIN core library.
\item A basic simplex code which applies to problems with a few 100s of
    variables but which does not utilize LU decomposition and sophisticated
    pricing techniques yet.
\item An LP module entry point which is also designed as an abstract class
    \verb/goblinILPModule/ and which can be overloaded with plugins for other
    LP codes.
\item File import and export filters which can supply to LP solvers other than
    the native simplex code.
\end{itemize}
Future releases may come up with a more efficient simplex code as well as with
branch and cut techniques. Additionally, plugins for popular LP codes are
desirable.

This chapter mainly discusses the method prototypes. Of course, all pure virtual
messages must be implemented by any prospective LP wrapper. Some virtual
functions provide default implementations which can be overloaded with more
immediate code. Others are needed for user interaction only and hence
provide dummy implementations which throw exceptions if called from the GOBLET
browser.


\newpage
\markright{PUBLIC INTERFACE}
\section{Public Interface}

\subsection{Entry Point}
\myinclude\verb/ilpWrapper.h/
\begin{mymethods}
\begin{verbatim}
class goblinController
{
    void const*     pLPModule;
}

class goblinILPModule
{
    goblinILPModule();

    virtual goblinILPWrapper*
        NewInstance(TRestr,TVar,TIndex,TObjectSense,
                                goblinController&) = 0;

    virtual goblinILPWrapper*
        ReadInstance(char*,goblinController&) = 0;

    virtual goblinILPWrapper*
        Reinterprete(void*) = 0;

    virtual char*   Authors() = 0;
    virtual int     MajorRelease() = 0;
    virtual int     MinorRelease() = 0;
    virtual char*   PatchLevel() = 0;
    virtual char*   BuildDate() = 0;
    virtual char*   License() = 0;

    enum TLPOrientation {
        ROW_ORIENTED = 0,
        COLUMN_ORIENTED = 1
    };
    virtual TLPOrientation  Orientation() = 0;
}
\end{verbatim}
\end{mymethods}
The LP module is accessed by a context pointer to a \verb/goblinILPModule/
object. The purpose of this class is instance generation (\verb/NewInstance()/
and \verb/ReadInstance()/), explicit runtime time information about the
LP instances (\verb/Reinterprete()/) plus some general module information.

The method \verb/ReadInstance()/ expects a filename as an input parameter.
The input file format may differ among the various implementations. The
method \verb/NewInstance()/ takes the desired number of restrictions, variables
and non-zero matrix coefficients as well as the direction of optimization.
Note that the \verb/goblinILPModule/ object is in the
\verb/goblinDefaultContext/ but LP instances may be inserted into other
contexts.

In order to generate LP instances from this abstract interface, one needs
to cast back the entry pointer before problem instanciation:
\begin{mysample}
\begin{verbatim}
...
goblinILPModule* X =
    (goblinILPModule*)goblinController::pLPModule;
goblinILPWrapper* myLP =
    X->ReadInstance(fileName,thisContext);
...
\end{verbatim}
\end{mysample}
Accordingly, the registration of an LP module looks like
\begin{mysample}
\begin{verbatim}
...
goblinILPModule* tmpPtr = new myLPModule();
goblinController::pLPModule = (void*)tmpPtr;
...
\end{verbatim}
\end{mysample}
where \verb/myLPModule/ may denote some implementation of
\verb/goblinILPModule/. The extra assignment is needed to reconstruct
a valid pointer later!

The parameter \verb/Orientation()/ is needed only for access to the
current bases or tableaus of LP instances. Then a return value of
\verb/ROW_ORIENTED/ indicates that restrictions are treated as artificial
columns whereas \verb/COLUMN_ORIENTED/ indicates that variables also form
restrictions. Row and column indices are partially orientation dependent!


\newpage
\subsection{LP Instance Retrieval Operations}
\myinclude\verb/ilpWrapper.h/
\begin{mymethods}
\begin{verbatim}
class goblinILPWrapper
{
    virtual TRestr      K();
    virtual TVar        L();
    virtual TIndex      NZ() = 0;
    
    virtual TFloat      Cost(TVar);
    virtual TFloat      URange(TVar);
    virtual TFloat      LRange(TVar);
    virtual TFloat      UBound(TRestr);
    virtual TFloat      LBound(TRestr);
    
    enum TVarType {
        VAR_FLOAT=0,
        VAR_INT=1,
        VAR_CANCELED=2
    };
    virtual TVarType    VarType(TVar);

    virtual TObjectSense    ObjectSense();

    virtual TFloat      Coeff(TRestr,TVar);
    virtual TVar        GetRow(TRestr,TVar*,double*);
    virtual TRestr      GetColumn(TVar,TRestr*,double*);

    virtual char*       VarLabel(TVar,TOwnership);
    virtual char*       RestrLabel(TRestr,TOwnership);
}
\end{verbatim}
\end{mymethods}

\noindent
A \verb/goblinILPWrapper/ object models a general form \nt{linear program}
\begin{center}
\begin{tabular}{p{3cm}}
\bf{minimize}\\
$\;\;\;\;\;\; c^T x$\\
\bf{subject to}  \\
$\;\;\;\;\;\; a \leq Ax \leq b$ \\
$\;\;\;\;\;\; l \leq x \leq u$
\end{tabular}
\end{center}
with the dual form
\begin{center}
\begin{tabular}{p{5cm}}
\bf{maximize}\\
$\;\;\;\;\;\; a^T y_+ - b^T y_- + l^T z_+ - u^T z_+$\\
\bf{subject to}  \\
$\;\;\;\;\;\; A^T(y_- - y_+) + z_- - z_+ = c$ \\
$\;\;\;\;\;\; y_+, y_-, z_+, z_- \geq 0$
\end{tabular}
\end{center}
Each of the vectors $a$, $b$, $l$ and $u$ may include symbolic infinite
coefficients. In that case, the associated dual variables are fixed to zero
implicitly. In the primal form, lower and upper bounds may coincide to
represent equality restrictions respectively fixed variables. This
mathematical description translates to the C++ model as follows:
\begin{itemize}
\item A \verb/TRestr/ value denotes a row index running from $0$ to either
    \verb/K()-1/ or \verb/K()+L()-1/ depending on wether only \nt{structural
    restrictions} or also \nt{variable range restrictions} are valid arguments.
\item A \verb/TVar/ value denotes a column index running from $0$ to
    \verb/L()-1/ or \verb/K()+L()-1/ if \nt{auxiliary variables} are also
    valid arguments (which then occupy the indices $0,\dots,K()-1$).
\item The direction of optimization is determined by \verb/ObjectSense()/ with
    the possible values \verb/MAXIMIZE/, \verb/MINIMIZE/ and \verb/NO_OBJECTIVE/.
\item The method \verb/Cost()/ represents the cost vector $c$.
\item The methods \verb/LRange()/ and \verb/URange()/ represent the vectors
    $l$ and $u$.
\item The methods \verb/LBound()/ and \verb/UBound()/ represent the vectors
    $a$ and $b$ which are extended to the variable range restrictions in the
    obvious way.
\item The matrix $A$ is represented by the method \verb/Coeff()/ which is
    restricted to the structural restrictions. The number of non-zero matrix
    coefficients is obtained by \verb/NZ()/.
\item The \verb/VarType()/ of a variable is either \verb/VAR_FLOAT/,
    \verb/VAR_INT/ (which indicate rational or integer variables) or
    \verb/VAR_CANCELED/ (which indicates deleted variables).
\item The methods \verb/VarLabel()/ and \verb/RestrLabel()/ supply with
    variable names and symbolic row labels. Generally, rows and columns
    are referenced by indices rather than labels.
\end{itemize}


\newpage
\subsection{LP Instance Manipulation}
\myinclude\verb/ilpWrapper.h/
\begin{mymethods}
\begin{verbatim}
class goblinILPWrapper
{
    virtual TVar    AddVar(TFloat,TFloat,TFloat,TVarType);
    virtual TRestr  AddRestr(TFloat,TFloat);

    virtual void    DeleteVar(TVar);
    virtual void    DeleteRestr(TRestr);

    virtual void    SetURange(TVar,TFloat);
    virtual void    SetLRange(TVar,TFloat);
    virtual void    SetUBound(TRestr,TFloat);
    virtual void    SetLBound(TRestr,TFloat);
    virtual void    SetCost(TVar,TFloat);
    virtual void    SetVarType(TVar,TVarType);

    virtual void    SetVarLabel(TVar,char*,TOwnership);
    virtual void    SetRestrLabel(TRestr,char*,TOwnership);

    virtual void    SetObjectSense(TObjectSense);
    void            FlipObjectSense();

    virtual void    SetCoeff(TRestr,TVar,TFloat);
    virtual void    SetRow(TRestr,TVar,TVar*,double*)
    virtual void    SetColumn(TVar,TRestr,TRestr*,double*)

    virtual void    Resize(TRestr,TVar,TIndex);
    virtual void    Strip();
}
\end{verbatim}
\end{mymethods}
Every \verb/goblinILPWrapper/ object is instanciated with a couple of problem
dimensions. These quantities are not the actual dimensions but rather the
amount of reserved memory which can be adjusted dynamically by using
\verb/Resize(k,l,r)/. This concerns the number of rows $k$, the number of
variables $l$ and the number of non-zero matrix coefficients $r$. A
\verb/Strip()/ operation performs a \verb/Resize()/ with the actual problem
dimensions.

The obvious purpose of this functionality is to save memory reallocations.
Any possible implementation class other than the native \verb/goblinLPSolver/
may ignore these implicit problem dimensions up to that adding rows
and variables must be possible even if this requires a reallocation.

An \verb/AddRestr()/ operation sets a lower and an upper bound, an
\verb/AddVar()/ operation sets the bounds, the cost coefficient and
a variable type (in that order). The variable type must be \verb/VAR_INT/
or \verb/VAR_FLOAT/. The matrix coefficients associated with a restriction and
variable are initialized as zero and have to be set one by one using
\verb/SetCoeff()/.

Deleting rows (\verb/DeleteRestr()/) or variables (\verb/DeleteVar()/) may not
change the remaining indices. It essentially marks the row or column as
canceled. If deletions cannot be implemented otherwise, a delete operation may
zero out rows and columns.

Calling \verb/FlipObjectSense()/ changes the object sense and inverts the
objective vector. By that, optimum solutions are preserved but the objective
value changes. Calling \verb/SetObjectSense(MAXIMIZE)/ or
\verb/SetObjectSense(MINIMIZE)/ only changes the object sense whereas
\verb/SetObjectSense(NO_OBJECTIVE)/ assigns a zero objective vector.

The implementation of the other methods is obvious. Specifying incompatible
bounds should raise an exception. If setting a matrix coefficient corrupts
the active basis, this should be checked by the next access to some basis
dependent data only.


\newpage
\subsection{Basis Dependent Methods}
\myinclude\verb/ilpWrapper.h/
\begin{mymethods}
\begin{verbatim}
class goblinILPWrapper
{
    virtual void    ResetBasis();
    virtual bool    Initial();
    
    enum TRestrType {
        BASIC_LB=0,
        BASIC_UB=1,
        NON_BASIC=2,
        RESTR_CANCELED=3
    };
    virtual TRestrType  RestrType(TRestr);
    virtual TRestr      Index(TVar);
    virtual TRestr      RowIndex(TRestr);
    virtual TVar        RevIndex(TRestr);

    enum TLowerUpper {
        LOWER=0,
        UPPER=1
    };
    virtual void    SetRestrType(TRestr,TLowerUpper);
    virtual void    SetIndex(TRestr,TVar,TLowerUpper);
    virtual void    Pivot(TIndex,TIndex,TLowerUpper);

    virtual TFloat  X(TVar) throw(ERRange);
    virtual TFloat  Y(TRestr,TLowerUpper) throw(ERRange);

    virtual TFloat  ObjVal();
    virtual TFloat  Slack(TRestr,TLowerUpper);
    virtual TFloat  Tableau(TIndex,TIndex);
    virtual TFloat  BaseInverse(TIndex,TIndex);

    virtual bool    PrimalFeasible();
    virtual bool    DualFeasible();
}
\end{verbatim}
\end{mymethods}
All throughout lifetime, a \verb/goblinILPWrapper/ maintains some kind of
basis. An initial basis is provided by the method \verb/ResetBasis()/.
This basis may consist of the variable range restrictions but other mechanisms
are also possible. The flag \verb/Initial()/ indicates the state of the basis
correspondingly.

The current row \nt{basis} is accessed by the mappings \verb/Index()/ and
\verb/RevIndex()/ which are inverse. The method \verb/Index()/ returns the
\nt{basis row} assigned with a given variable. More precisely,
\verb/RestrType(i)/ is either \verb/RESTR_CANCELED/ or \verb/NON_BASIC/,
or \verb/RevIndex(i)!=NoVar/ is defined. In the latter case, the type is either
\verb/BASIC_LB/ or \verb/BASIC_UB/. In a column oriented implementation, the
basis data can be manipulated as follows:
\begin{itemize}
\item The operation \verb/SetIndex(i,j,tp)/ results in \verb/RevIndex(i)==j/
    and \verb/Index(j)==i/. The passed type $tp$ has to be either \verb/LOWER/
    or \verb/UPPER/. If previously \verb/Index(k)==i/, then $k$ must be matched
    elsewhere, ideally with the former \verb/Index(j)/. It is not checked that
    the basis rows are linear independent after the operation!
\item The operation \verb/Pivot(i,j,tp)/ has similar effects on the indices but
    requires that the entering row $j$ is non-basic (Exception: $j==i$). The
    indexed rows must be linearly independent afterwards.
\item Switching between \verb/RestrType==BASIC_LB/ and \verb/BASIC_UB/ is also
    achieved by \verb/SetRestrType()/. Of course, this applies to
    basis rows only.
\end{itemize}
The methods \verb/Index()/ and \verb/SetIndex()/ are also mandatory for row
oriented implementations. Additionally, the current (column) basis has to be
determined by the method \verb/RowIndex()/ and the row and column indices
have to be partially inverse: If \verb/RowIndex(i)/ is a structural variable,
\verb/Index(RowIndex(i))==i/ must hold. Both indices are completed by
artificial variables and variable range restrictions respectively. Column
oriented solver do not need to implement a \verb/RowIndex()/!

The primal and dual solutions which are associated with the current basis are
returned by the methods \verb/X()/ (only structural variables are handled) and
\verb/Y()/ respectively. The violation
of the primal restrictions is checked with the methods \verb/Slack()/ and
\verb/PrimalFeasible()/. The method \verb/DualFeasible()/ essentially checks
the signs of the dual variable values. How the solutions are computed from the
basis indices are implementation details.

The methods \verb/Tableau()/, \verb/BaseInverse()/ and \verb/Pivot()/ have been
added for didactic purposes. In order to get a unique interface for both column
and row oriented solvers, all methods accept indices running from $0$ to
$K()+L()-1$. For \verb/Tableau()/ and \verb/Pivot()/, the first parameter
specifies a basic index and the second parameter is a non-basic index.
For \verb/BaseInverse()/, the first parameter denotes a basic index running
from $0$ to $K()+L()-1$ and the second parameter denotes a row index ranged in
$0,\dots,K()-1$ or a column index ranged in $0,\dots,L()-1$ respectively!

Finally, it must be mentioned how the basis changes if the problem definition
changes. If the right-hand sides or the cost coefficients are modified, the
basis remains intact. If some matrix coefficients are modified,
the indexed rows may become linearly dependent, but this may be detected by
the next pivoting step only.

If a variable is added, a basis row must be assigned immediately, ideally the
variable range restriction (this is always feasible). A new structural
restriction does not affect the (row) basis and the primal solution and slacks
of the existing restrictions (although the solution may become primally
infeasible and the indices must be recomputed). It shall not possible to delete
a row in the current basis. The deletion of a variable must mark the matched
basis row non-basic.


\newpage
\subsection{Problem Transformations}
\myinclude\verb/ilpWrapper.h/
\begin{mymethods}
\begin{verbatim}
class goblinILPWrapper
{
    goblinILPWrapper*   Clone();
    goblinILPWrapper*   DualForm();
    goblinILPWrapper*   StandardForm();
    goblinILPWrapper*   CanonicalForm();
}
\end{verbatim}
\end{mymethods}
The LP interface supports the well-known transformations of linear programs.
All methods do not modify the addressed object but return a new LP
instance of the requested form:
\begin{itemize}
\item If the original LP instance is a standard or canonical form, the
    \verb/DualForm()/ flips the role of rows and variables but does not
    introduce new items. Generally, lower and upper bounds are replaced by
    two variables or two rows, and the object sense is reverted.
\item The \verb/CanonicalForm()/ replaces all variable range restrictions by
    structural restrictions and all equality restrictions by a pair of
    inequalities. Computing the canonical form of a canonical form, does not
    change anything. Canonical forms are maximization problems.
\item The \verb/StandardForm()/ fills inequality restrictions with slack
    variables and substitutes variables with non-trivial bounds. Computing the
    standard form of a standard form, does not change anything. Standard forms
    are minimization problems.
\item The \verb/Clone()/ is a plain copy of the addressed MIP object. It can be
    used for explicit manipulation without changing the original LP.
\end{itemize}
All transformations preserve the optimum objective value.

Generally, the new variable [row] names can clash with original names. To be
safe, the original names should consist of a letter followed by digits. For
example, you can use the internal naming scheme.


\newpage
\subsection{Solving Problems}
\myinclude\verb/ilpWrapper.h/
\label{slb_solve_lp}
\begin{mymethods}
\begin{verbatim}
class goblinILPWrapper
{
    enum TSimplexMethod {
        SIMPLEX_AUTO=0,
        SIMPLEX_PRIMAL=1,
        SIMPLEX_DUAL=2
    };
    enum TStartBasis {
        START_AUTO=0,
        START_LRANGE=1,
        START_CURRENT=2
    };

    virtual TFloat  SolveLP();
    virtual TFloat  SolvePrimal();
    virtual TFloat  SolveDual();
    virtual bool    StartPrimal();
    virtual bool    StartDual();
}
\end{verbatim}
\end{mymethods}
This is the most straightforward part of the LP interface description:
The entry point \verb/SolveLP()/ calls one of the methods \verb/SolvePrimal()/
and \verb/SolveDual()/ based on the value of the context variable \verb/methLP/.
There is a default implementation provided for \verb/SolveLP()/ which can be
used from later plugins in order to support the GOBLET browser messaging.
The relationship between the options \verb/methLP/, \verb/methLPStart/ and the
types \verb/TSimplexMethod/, \verb/TStartBasis/ is the obvious one.

The methods \verb/StartPrimal()/ and \verb/StartDual()/ can be used to
determine feasible rather than optimal solutions.


\begin{tablehere}
\begin{center}
\vspace*{1cm}
\begin{tabular}{|p{3cm}|p{1cm}|p{5cm}|}
\hline
{\bf Variable} & {\bf Value} & {\bf Description} \\
\hline
\hline
\verb/methLP/       & {\bf 0} & Automatic selection \\
                    & 1 & Primal Simplex \\
                    & 2 & Dual simplex method \\
\hline
\verb/methLPStart/  & {\bf 0} & Automatic selection \\
                    & 1 & Start with lower bounds \\
                    & 2 & Start with current basis \\
\hline
\end{tabular}
\end{center}
\caption{\label{tlb_lp_opt}LP Solver Options}
\end{tablehere}


\newpage
\subsection{File I/O}
\myinclude\verb/ilpWrapper.h/
\begin{mymethods}
\begin{verbatim}
class goblinILPWrapper
{
    enum TLPFormat {
        MPS_FORMAT=0,
        LP_FORMAT=1,
        MPS_CPLEX=2,
        BAS_CPLEX=3,
        BAS_GOBLIN=4
    };

    void    Write(char*,TOption = 0);
    void    Write(char*,TLPFormat,TOption = 0);
    void    WriteMPSFile(char*,TLPFormat = MPS_CPLEX);
    void    WriteMPSFile(ofstream&,TLPFormat = MPS_CPLEX);
    void    WriteBASFile(char*,TLPFormat = BAS_CPLEX);
    void    WriteBASFile(ofstream&,TLPFormat = BAS_CPLEX);

    void    ReadMPSFile(char*);
    void    ReadMPSFile(ifstream&);
    void    ReadBASFile(char*);
    void    ReadBASFile(ifstream&);
}
\end{verbatim}
\end{mymethods}
The LP file interface supports the standard MPS format and the CPLEX MPS
variant for both reading and writing files, and the CPLEX LP format for
writing files only. The output methods work implementation independent, the
input MPS method requires a void LP to run and, by that, a default constructor
in the LP plugin. Additionally, one can read and write MPS basis files.
Again, reading a basis requires that the LP plugin supports setting a special
basis.

The native LP file format generated by the method \verb/Write(char*,TOption)/
consists of a certain header part, an MPS problem description and an MPS basis
file. In order to implement this efficiently, all file I/O methods exist in two
versions, writing to or reading from a file specified either by the file name
or an open stream. A more detailed specification of the native format can be
found in Section \ref{slb_format_lp}. The LP format generator is discussed next.


\newpage
\subsection{Text Display}
\label{slb_lp_text_form}
\myinclude\verb/ilpWrapper.h/
\begin{mymethods}
\begin{verbatim}
class goblinILPWrapper
{
    enum TDisplayOpt {
        DISPLAY_OBJECTIVE = 1,
        DISPLAY_RESTRICTIONS = 2,
        DISPLAY_BOUNDS = 4,
        DISPLAY_INTEGERS = 8,
        DISPLAY_FIXED = 16,
        DISPLAY_PRIMAL = 32,
        DISPLAY_DUAL = 64,
        DISPLAY_SLACKS = 128,
        DISPLAY_BASIS = 256,
        DISPLAY_TABLEAU = 512,
        DISPLAY_INVERSE = 1024
    };
    
    void WriteLPNaive(char*,TDisplayOpt = 0);
}
\end{verbatim}
\end{mymethods}
There is an implementation independent layout method \verb/WriteLPNaive()/
which can display the complete problem description and tableau data. This
information is grouped into several sections rather than filled into a single
table. The calling parameters are an output file name and a bit field which is
composed from the following flags:
\begin{itemize}
\item \verb/DISPLAY_OBJECTIVE/: Write the direction of optimization and the
    linear objective function. Variables with zero coefficients are omitted.
\item \verb/DISPLAY_RESTRICTIONS/: Write the structural restrictions. Fields
    with zero coefficients are left blank. Displayed are either equations or
    inequalities with one or two right-hand sides.
\item \verb/DISPLAY_BOUNDS/:  Write the variable range restrictions. Free
    variables are not listed. Non-negative, non-positive and binary variables
    are grouped together. The remaining variables are displayed by  equations
    or inequalities with one or two right-hand sides.
\item \verb/DISPLAY_INTEGERS/: Write the list of integer variables.
\item \verb/DISPLAY_FIXED/: Write the list of fixed variables.
\item \verb/DISPLAY_PRIMAL/: Write the variable values. Zero values are omitted.
\item \verb/DISPLAY_DUAL/: Write the dual variable values associated with the
    structural and the range restrictions. Lower and upper bound restrictions
    are grouped together. Zero values are omitted, especially those of
    unbounded restrictions.
\item \verb/DISPLAY_SLACKS/: Write the primal slacks.  Lower and upper bounds
    are grouped together. Unbounded restrictions and zero slacks are not listed.
\item \verb/DISPLAY_BASIS/: Write the mapping from variables to basis
    restrictions. 
\item \verb/DISPLAY_TABLEAU/: Write the transposed tableau matrix where the
    basis column are omitted. Zero matrix entries are not displayed.
\item \verb/DISPLAY_INVERSE/: Write the transposed inverse of the basis matrix.
    Zero matrix entries are not displayed.
\end{itemize}
If no display option or a zero value is specified, the output is in CPLEX LP
format. This essentially consists of the first three listed sections.

All sections list variable and restriction labels rather than indices. The
tableau and basis inverse output is always formatted (take care with large
scale problems). If the width does not exeed 120 characters, the objective
function and the structural restrictions are aligned together. The remaining
sections are written in blocks of 5 or 10 entries.

In this format, a given basis is primally feasible if all displayed slacks are
non-negative. Optimality can be checked with the dual variable values which
must have the correct sign (depending on the direction of optimization and
differing for lower and upper bound restrictions).


\newpage
\markright{Native LP Solver}
\section{Native LP Solver}
\myinclude\verb/lpSolver.h/
\begin{mymethods}
\begin{verbatim}
class goblinLPSolver
{
private:

    bool    baseInitial;
    bool    baseValid;
    bool    dataValid;

    void    DefaultBasisInverse();
    void    EvaluateBasis();
    void    BasisUpdate(TRestr,TVar);
    void    SolutionUpdate();
    
    void    PrimallyFeasibleBasis();
    TVar    PricePrimal();
    TRestr  QTestPrimal(TVar);
    
    void    DuallyFeasibleBasis();
    TRestr  PriceDual();
    TVar    QTestDual(TRestr);

public:

    void    Pivot(TRestr,TVar,TLowerUpper);
    
}
\end{verbatim}
\end{mymethods}
The native LP solver is preliminary, and currently only a very basic
simplex code is available. For this reason, a detailed documentation of pricing
techniques, ratio tests and the used data structures is postponed. We give a
few remarks about the basis update strategies so far and about some flags used
internally:
\begin{itemize}
\item The flag \verb/baseInitial/ is equivalent with the method \verb/Initial()/.
    It is set by constructors and by \verb/ResetBasis()/ operations. It
    indicates the basis consisting of the lower variable bounds.
    The flag is cleared by every \verb/SetIndex()/ operation.
\item The flag \verb/baseValid/ indicates if a basis inverse matrix exists and
    if it is up to date with the basis indices and the coefficient matrix.
    It is set by \verb/DefaultBasisInverse()/, \verb/EvaluateBasis()/ and
    \verb/BasisUpdate()/. The flag is cleared initially and by
    \verb/ResetBasis()/, \verb/SetIndex()/ and \verb/SetCoeff()/ operations.
\item The flag \verb/dataValid/ indicates if the basic solutions are up to date
    with the problem definiton and the basis inverse matrix. It set by calls to
    \verb/DefaultBasisInverse()/ and \verb/SolutionUpdate()/, and cleared
    whenever the problem is modified or the basis indices change.
\end{itemize}
The method \verb/EvaluateBasis()/ computes the basis inverse matrix and a pair
of basis solutions from scratch. This operation takes $O(l^3)$ time and is
used only if optimization is started from a given basis without knowing the
initial basis inverse, especially if \verb/SetIndex()/ has been called
explicitly.

A \verb/Pivot()/ operation also calls \verb/SetIndex()/ but then updates the
basis inverse by a subsequent call to \verb/BasisUpdate()/. The update of the
basic solutions is delayed until values are actually requested.


\newpage
\markright{GLPK WRAPPER}
\section{GLPK Wrapper}
\myinclude\verb/glpkWrapper.h/
\begin{mymethods}
\begin{verbatim}
class goblinGLPKWrapper
\end{verbatim}
\end{mymethods}
There are some conceptual differences between GLPK and the GOBLIN native code:
\begin{itemize}
\item In GLPK, cost coefficients can be associated with restrictions which are
    considered auxiliary variables.
\item In GLPK, efficient access to the constraint matrix is provided by row and
    column operations.
\item GLPK is distributed under the terms of the GNU public licence.
\end{itemize}



\cleardoublepage
\markboth{RESSOURCE MANAGEMENT}{RESSOURCE MANAGEMENT}
\thispagestyle{fancy}
\chapter{Ressource Management}

\section{Memory Management}
\label{slb530}
\myincludes\verb/globals.h/, \verb/goblinController.h/
\begin{mymethods}
\begin{verbatim}
long unsigned goblinHeapSize;
long unsigned goblinMaxSize;
long unsigned goblinNFragments;
long unsigned goblinNAllocs;
long unsigned goblinNObjects;

void* operator new(size_t size);
void* operator new[](size_t size);
void* GoblinRealloc(void* p,size_t size);
void operator delete(void *p);
void operator delete[](void *p);

class goblinAbstractObject
{
    virtual unsigned long   Size() = 0;
};

class goblinController
{
    unsigned long   Size();
};
\end{verbatim}
\end{mymethods}
The GOBLIN memory management keeps track of all changes of the dynamic memory
(heap) referenced by the data objects. Other than in previous releases, the
counters are global rather than context relative. The counters inform about the
current heap size (\verb/goblinHeapSize/), the maximum heap size
(\verb/goblinMaxSize/), the current number of data objects
(\verb/goblinNObjects/), the current number of memory fragments
(\verb/goblinNFragments/) and the total number of memory allocations
(\verb/goblinNAllocs/).

To this end, the operators \verb/new/, \verb/new[]/, \verb/delete/ and
\verb/delete[]/ have been overwritten. If conflicts with other C++ modules
arise, the entire functionality can be turned off at compile time via the
pragma \verb/_HEAP_MON_/. The function \verb/GoblinRealloc()/ does the same
as the C function, but a new name has been chosen to separate from C memory
management.

Note that a block of memory which was allocated with the default implementation
of \verb/new()/ cannot be disallocated with the GOBLIN version of
\verb/delete()/. Do also take care that \verb/new[]()/ and \verb/delete[]()/
are matching for sake of later redesigns.

If desired, the calling class method has to provide meaningful logging
information about allocation and disallocation of implicit objects (objects
which are not GOBLIN data objects). A typical sequence of statements is like
follows:
\begin{mysample}
\begin{verbatim}
...
thisArray = new TFloat[100];
LogEntry(LOG_MEM,Handle(),"...Array allocated!");
...
thisArray = TFloat(GoblinRealloc(sizeof(TFloat)*200);
LogEntry(LOG_MEM,Handle(),"...Array resized!");
...
delete[] thisArray;
LogEntry(LOG_MEM,Handle(),"...Array disallocated!");
...
\end{verbatim}
\end{mysample}
Independently from the described heap information one can retrieve the
size of any object by calling \verb/Size()/. The returned amount is the
actual object size via \verb/sizeof()/ plus the amount of heap memory
referenced by this object (other than GOBLIN data objects). Calling
\verb/Size()/ for an object controller would return its actual object size
plus the size of all managed data objects.


\section{Timers}
\label{slb_timers}
\myincludes\verb/timers.h/
\begin{mymethods}
\begin{verbatim}
class goblinTimer
{
    goblinTimer(goblinTimer** = NULL);
                    
    void        Reset();
    bool        Enable();
    bool        Disable();

    double      AccTime();
    double      AvTime();
    double      MaxTime();
    double      MinTime();
    double      PrevTime();

    bool        Enabled();
};
\end{verbatim}
\end{mymethods}
The class \verb/goblinTimer/ provides timer objects to keep track of
roundtrip times (\verb/PrevTime()/), accumulated times (\verb/AccTime()/),
minimum (\verb/MinTime()/), maximum (\verb/MaxTime()/) and average
(\verb/AvTime()/) roundtrip times for a special unit of code.

Timer are started by the method \verb/Enable()/ and stopped by
\verb/Disable()/. A \verb/Reset()/ operation clears the timer statistics
and also stops the timer. One can check if the timer is currently running by
calling \verb/Enabled()/.

If nested starts and stops of the same timer occur, the timer object maintains
the nesting depth and effectively stops only if all starts are matched by stop
operations.

The compilation of the entire timer functionality is suppressed if the pragma
\verb/_TIMERS_/ is unset.


\subsection{Basic and Full Featured Timers}
\myincludes\verb/timers.h/
\begin{mymethods}
\begin{verbatim}
class goblinTimer
{
    double      ChildTime(TTimer);

    bool        FullInfo();
};
\end{verbatim}
\end{mymethods}
A timer can report about explicit starts and stops but also about relative
running times of other timers (\nt{child timers}). For this goal, a pointer
to a list of \nt{global timers} must be passed to the constructor method.

Whenever a timer is started, all child running times are reset. Since several
timers can be active at a time, the child times do not sum up to the parent
timer value.

if no or a \verb/NULL/ pointer is passed to the constructor method, a
\nt{basic timer} is instanciated. Such timers do not keep track of nested
timer starts and stops. A given timer is basic if \verb/FullInfo()/ returns
\verb/false/.


\subsection{Global Timers}
\label{slb_global_timers}
\myincludes\verb/globals.h/, \verb/goblinController.h/
\begin{mymethods}
\begin{verbatim}
enum TTimer {..., NoTimer};

struct TTimerStruct {
    char*           timerName;
    bool            fullFeatured;
};

const TTimerStruct listOfTimers[];

class goblinController
{
    pGoblinTimer*   globalTimer;
};
\end{verbatim}
\end{mymethods}
There is a list of global timers, declared by the enum index type \verb/TTimer/
and the global array \verb/listOfTimers/. From this structural information,
every controller object instanciates its own timer table. This table can be
addressed by the pointer \verb/globalTimer/ and the enum index values.

Global timers are intended to split the code into functional units whereas the
source code modules discussed later represent special authorship. Several
modules may share a global timer.

Some basic global timers are utilized explicitly by the high-level data
structures and the file interface whereas the other global timers are
(de)activated by \verb/OpenFold()/ and \verb/CloseFold()/ operations implicitly.

If the context flag \verb/logTimers/ is set, every \verb/CloseFold()/ operation
files the complete timer status including child times. Zero timer values are
not displayed.



\subsection{Lower and Upper Problem Bounds}
\label{slb_bounds}
\myincludes\verb/timers.h/, \verb/dataObject.h/
\begin{mymethods}
\begin{verbatim}
class goblinTimer
{
    bool    SetLowerBound(TFloat);
    bool    SetUpperBound(TFloat);
    
    TFloat  LowerBound();
    TFloat  UpperBound();
};

class managedObject
{
    void    SetLowerBound(TTimer,TFloat);
    void    SetUpperBound(TTimer,TFloat);
    void    SetBounds(TTimer,TFloat,TFloat);

    TFloat  LowerBound(TTimer);
    TFloat  UpperBound(TTimer);
};
\end{verbatim}
\end{mymethods}
With every timer, a pair of problem bounds is associated which can be
manipulated in the obvious way. For global timers, an additional wrapper
exists which simplifies the access from data object methods.

If the context flag \verb/logGaps/ is set, every \verb/SetBounds()/ operation
which strictly decreases the duality gap writes some logging information.



\section{Source Code Modules}
\label{slb_modules}
\myincludes\verb/globals.h/
\begin{mymethods}
\begin{verbatim}
enum TModule {..., NoModule};

struct TModuleStruct {
    char*           moduleName;
    TTimer          moduleTimer;
    TAuthor         implementor1;
    TAuthor         implementor2;
    char*           encodingDate;
    char*           revisionDate;
    TBibliography   originalReference;
    TBibliography   authorsReference;
    TBibliography   textBook;
};

const TModuleStruct listOfModules[];

class managedObject
{
    void    OpenFold();
    void    CloseFold();

    void    OpenFold(TModule,TOption = 0);
    void    CloseFold(TModule,TOption = 0);
};
\end{verbatim}
\end{mymethods}
As mentioned before, a \nt{code module} denotes a specific implementation
rather than a functional unit. Source code is assigned to a module
\verb/modSample/ by the method calls \verb/OpenFold(modSample,opt)/ and
\verb/CloseFold(modSample,opt)/ which must match each other.

By default, folds signal indentations to the messenger. To suppress such
indentations, one can pass an optional parameter \verb/NO_INDENT/. Conversely,
if the module context has already been set, additional indentations can be
forced by calling \verb/OpenFold()/ and \verb/CloseFold()/ without any
parameters.

Opening a fold enables the associated timer. If the timer was not already
running, the problem bounds are also reset.


\subsection{Authorship}
\label{slb_authors}
\myincludes\verb/globals.h/
\begin{mymethods}
\begin{verbatim}
enum TAuthor {..., NoAuthor};

struct TAuthorStruct {
    char*           name;
    char*           affiliation;
    char*           e_mail;
};

const TAuthorStruct listOfAuthors[];
\end{verbatim}
\end{mymethods}


\subsection{Bibliography Data Base}
\label{slb_bibliography}
\myincludes\verb/globals.h/
\begin{mymethods}
\begin{verbatim}
enum TBibliography {..., NoBibliography};

struct TBibliographyStruct {
    char*           refKey;
    char*           authors;
    char*           title;
    char*           type;
    char*           collection;
    char*           editors;
    int             volume;
    char*           publisher;
    int             year;
}

const TBibliographyStruct listOfReferences[];
\end{verbatim}
\end{mymethods}


\section{Progress Measurement}
\label{slb_progress}
A description of this functionality is delayed until the interface has become
stable.



\cleardoublepage
\markboth{PERSISTENCY}{PERSISTENCY}
\chapter{Persistency}
\thispagestyle{fancy}
\label{clb8}

\markright{OBJECT EXPORT}
\section{Export of Data Objects}
\myinclude\verb/fileExport.h/
\begin{mymethods}
\begin{verbatim}
class goblinExport
{
    goblinExport(char*,goblinController &
                            = goblinDefaultContext);

    void        StartTuple(char*,char,char = 0);
    void        StartTuple(unsigned long,char,char = 0);
    void        EndTuple();
    template <typename T>
                void MakeItem(T value,char length);
    void        MakeNoItem(char);
}
\end{verbatim}
\end{mymethods}
This class supports file export of data objects into a hierarchical format.
In this format, a data object is essentially a tree. The non-leaf nodes of this
tree are called {\bf tuples}\index{GOBLIN file!tuple}; they start and end with
a parenthesis. Between these two parenthesis, a label and the child nodes are
listed.

All child nodes must be of the same type, that is, either they are all tuples
or they are all numbers of a certain type. Needless to say that this simple
concept does not only work for graph objects, but is adequate for any data
object which essentially consists of vectors.

Every \verb/StartTuple()/ operation must be matched by an \verb/EndTuple()/
operation and vice versa. These operations write parenthesis \verb/(/ and
\verb/)/ respectively. It is checked if the number of parentheses resolve
in the end, and if there are unmatched opening parenthesis intermediately.

The first parameter of a \verb/StartTuple(label,type)/ call is a header
information which is written, either a string (which should not contain any
white spaces) or an integer number (which represents some kind of index).

The second parameter is the {\bf type}\index{GOBLIN file!tuple!type} of the
tuple. If zero, the tuple is a structured object, and the next operation must be another call to
\verb/StartTuple()/. Otherwise, the tuple represents a vector or a constant.
If the type $k$ is one, the entire vector is written to a single line.
Finally, if $k>1$, the entries are written in batches of $k$ numbers.

The third optional parameter denotes the maximum length of an entry if written
to file. This parameter is needed for formatting the output only.

A call \verb/MakeItem<T>(x,l)/ writes a value $x$ of type T into a field of width
$l$. In case of floats, one can use the context method \verb/SetExternalPrecision()/
to control the formatting. Finally, \verb/MakeNoItem(l)/ writes an asterisk \verb/*/
which represents undefined values. All items are aligned to the right-hand side.



\markright{OBJECT IMPORT}
\section{Import of General Data Objects}
\myinclude\verb/fileImport.h/
\begin{mymethods}
\begin{verbatim}
enum TBaseType {
    TYPE_NODE_INDEX,    TYPE_ARC_INDEX,     TYPE_FLOAT_VALUE,
    TYPE_CAP_VALUE,     TYPE_INDEX,         TYPE_ORIENTATION,
    TYPE_INT,           TYPE_BOOL
};

enum TArrayDim {
    DIM_GRAPH_NODES,    DIM_GRAPH_ARCS,     DIM_ARCS_TWICE,
    DIM_ALL_NODES,      DIM_LAYOUT_NODES,   DIM_SINGLETON
};

class goblinImport
{
    goblinImport(char*,goblinController&
                            = goblinDefaultContext);

    char*       Scan(char* = NULL);
    bool        Seek(char*);
    bool        Head();
    bool        Tail();
    bool        Eof();

    TNode*          GetTNodeTuple(unsigned long);
    TArc*           GetTArcTuple(unsigned long);
    TCap*           GetTCapTuple(unsigned long);
    TFloat*         GetTFloatTuple(unsigned long);
    TIndex*         GetTIndexTuple(unsigned long);
    char*           GetCharTuple(unsigned long);
    bool            Constant();
    unsigned long   Length();

    size_t      AllocateTuple(TBaseType,TArrayDim);
    void        ReadTupleValues(TBaseType,size_t);

    template <class TEntry>     TEntry* GetTuple();

    template <class TToken>     TToken ReadTuple(
            const TTokenTable listOfParameters[],
            TToken endToken,TToken undefToken)
}
\end{verbatim}
\end{mymethods}
Only a few comments are needed regarded the import of data objects:
The most basic method is \verb/Scan()/ which reads a string separated by white
spaces and parentheses, called {\bf token}\index{GOBLIN file!token} in what
follows. Note that an opening parenthesis may not be followed by a white space.
If string argument is passed to \verb/Scan()/, the method checks if this tring
equals the scanned token and throws an \verb/ERParse/ exception otherwise.
If no argument is passed, a pointer to the read token is returned.

The method \verb/Seek()/ scans the input, searching for the string which
has been passed as argument. It returns \verb/true/ if the string has been
found in the context, and \verb/false/ otherwise.

The methods \verb/Head()/ and \verb/Tail()/ can be used to determine the
position of the last read token within its tuple. Accordingly, \verb/EOF()/
detects the end of an object definition which should coincide with the file end.

For each base type used in GOBLIN, a special method exists which reads a
complete tuple. These methods take a parameter which specifies the desired
length of the tuple, and the input is accepted if either the actual length
matches this parameter value or if the actual length is one. This fact is
used to read constant graph labelings more economically.

The method \verb/Length()/ returns the length of the last read tuple and,
accordingly, \verb/Constant()/ decides whether the last read tuple has length
$1$.



\markright{IMPORT}
\section{Import of Graph Objects}
\myinclude\verb/fileImport.h/
\begin{mymethods}
\begin{verbatim}
class goblinImport
{
    TOptDefTokens       ReadDefPar();
    TOptLayoutTokens    ReadLayoutPar();
    TOptRegTokens       ReadRegister();
}
\end{verbatim}
\end{mymethods}



\newpage
\markright{FILE FORMAT FOR GRAPH OBJECTS}
\section{File Format for Graph Objects}
\label{slb_format}
The general file format for graph objects is as follows:
\begin{quote}
$<graph\;object> :=$\verb/    /\\
\verb/    /\\
\verb/    (/$<class\;label>$\\
\verb/     /$<definition>$\\
\verb/     /$<objectives>$\\
\verb/     /$<geometry>$\\
\verb/     /$<layout>$\\
\verb/     /$<solutions>$\\
\verb/     /$<configuration>$\\
\verb!    )[CR/LF]!\\
\end{quote}
where
\begin{quote}
$<class\;label> :=$\verb/    /\\
\verb/    /\\
\verb/    graph/        $|$ \verb/dense_graph/      $|$
\verb/digraph/      $|$ \verb/dense_digraph/    $|$\\
\verb/    bigraph/      $|$ \verb/dense_bigraph/    $|$
\verb/balanced_fnw/ $|$ \verb/mixed_graph/
\end{quote}
Usually, the information associated with some node or arc is stored by a file
record. Instead of this, GOBLIN stores {\bf vectors}\index{GOBLIN file!vector}, that are lists of numbers
which represent a specific node or arc labeling. Many fields in the file format
can be filled either with such a vector or with a single value which then
denotes a constant labeling.

This may be inconvenient for reading and editing the files by hand, but a lot
of information is immaterial for concrete problems. In that sense, the GOBLIN
file format keeps the file sizes small.
Some items merely keep place for future extensions of GOBLIN.

In what follows, a term $<arc>^x$ can be replaced either by a single
arc index or by a list of arc indices with exact length $x$. Corresponding
terms are used for node indices, booleans, capacities and floating numbers.


\newpage
\subsection{Definition}
\begin{quote}
$<definition> :=$\verb/    /\\
\verb/    /\\
\verb/    (definition/\\
\verb/     (nodes / $<n1>$ $<n2>$ $<n3>$\verb/)/\\
\verb/     /$[$\verb/(arcs / $<m=$ number of arcs $>$\verb/)/\\
\verb/     (incidences/\\
\verb/      (inc0        / $<$ arcs incident with node 0 $>$\verb/)/\\
\verb/      (inc1        / $<$ arcs incident with node 1 $>$\verb/)/\\
\verb/      ./\\
\verb/      ./\\
\verb/      (inc/$<n-1>$\verb/ / $<$ arcs incident with node $n-1 >$\verb/)/\\
\verb/     )/$]$\\
\verb/     (ucap        / $<capacity>^m$\verb/)/\\
\verb/     (lcap        / $<capacity>^m$\verb/)/\\
\verb/     (demand      / $<capacity>^n$\verb/)/\\
\verb/     (directed    / $<boolean>^m$\verb/)/\\
\verb/    )/\\
\end{quote}
The definition part essentially describes the feasibility region of a network
programming problem. For concrete classes, the following items can be omitted:
\begin{itemize}
\item For bipartite graphs, the cardinality of both partitions is specified by
    the numbers $n1$ and $n2$, and the total number of nodes is $n:=n1+n2$.
    Otherwise, the number of graph nodes is $n:=n1$. The number $n3$ denotes
    interpolation points which are needed for the graph layout sometimes.
    In what follows, some vectors have length $n^*:=n+n3$.
\item Incidence lists are specified for sparse graphs only. In dense graphs,
    the incidences are determined by the arc indices implicitly.
\item A list of arc directions are specified for mixed graphs only.
    Otherwise, this field is filled with a constant $0$ or $1$.
\end{itemize}
The incidence lists must be disjoint and cover the integers
$0,1,\dots,2m-2,2m-1$. The node whose incidence list contains the integer
$a$ is the start node of the arc \verb/a/, and the node whose incidence list
contains the integer \verb/a^1/ is the end node. As mentioned earlier, an even
index $2i$ denotes a forward arc, $2i+1$ is the corresponding backward arc.


\newpage
\subsection{Objectives}
\begin{quote}
$<objectives> :=$\verb/    /\\
\verb/    /\\
\verb/    (objectives/\\
\verb/     (commodities / $<c=$ number of commodities $>$\verb/)/\\
\verb/     /$[$\verb/(bound       / $<float>^c$\verb/)/\\
\verb/     (length/\\
\verb/      (comm0      / $<float>^m$\verb/)/\\
\verb/      (comm1      / $<float>^m$\verb/)/\\
\verb/      ./\\
\verb/      ./\\
\verb/      (comm/$<c-1>$\verb/   / $<float>^m$\verb/)/\\
\verb/     )/$]$\\
\verb/    )/\\
\end{quote}
An \nt{objective function} is a cost vector on the arc set of a graph,
essentially a set of arc length labels. A
\nt{network programming problem with side constraints}
asks for a certain subgraph such that for each objective the total length does
not exeed a respective bound or which minimizes the maximal objective.

This part has been added to support such problems at least by an adequate file
format. So far, no algorithms and no internal data structures for problems with
multiple objectives are available in GOBLIN, and this part should look like
\begin{quote}
\verb/    (objectives/\\
\verb/     (commodities 1)/\\
\verb/     (bound       *)/\\
\verb/     (length/\\
\verb/      (comm0      / $<float>^m$\verb/)/\\
\verb/     )/\\
\verb/    )/\\
\end{quote}


\newpage
\subsection{Geometry}
\begin{quote}
$<geometry> :=$\verb/    /\\
\verb/    /\\
\verb/    (geometry/\\
\verb/     (metrics     / $<type\;of\;metrics>$\verb/)/\\
\verb/     (dim         / $<d=$ dimension of the embedding$>$\verb/)/\\
\verb/     /$[$\verb/(coordinates/\\
\verb/      (axis0       / $<float>^{n^*}$\verb/)/\\
\verb/      (axis1       / $<float>^{n^*}$\verb/)/\\
\verb/      ./\\
\verb/      ./\\
\verb/      (axis/$<d-1>$\verb/   / $<float>^{n^*}$\verb/)/\\
\verb/     )/$]$\\
\verb/    )/\\
\end{quote}
This information becomes important if one needs to solve geometrical problems,
but is also used for the graphical display.

The field $<type\;of\;metrics>$ denotes the method by which length labels
are computed internally and overwrites the context variable \verb/methGeometry/.
If this parameter is zero, the length labels are specified in the objectives
part. Otherwise, GOBLIN takes the geometric embedding specified here and
computes the distances with respect to the specified metric.

In the current release, the dimension $d$ must be either $0$ or $2$, that is,
a graph either has a plane embedding or is not embedded at all.


\subsection{Layout}
\begin{quote}
$<layout> :=$\verb/    /\\
\verb/    /\\
\verb/    (layout/\\
\verb/     (model       / $<layout\;model>$\verb/)/\\
\verb/     (align       / $<node>^m$\verb/)/\\
\verb/     (thread      / $<node>^{n^*}$\verb/)/\\
\verb/     (exteriorArc / $<arc>$\verb/)/\\
\verb/    )/\\
\end{quote}
This information is needed only for the graphical display.
Reading the value of $<layout\;model>$ overwrites the corresponding context
variable. Even more, \verb/SetLayoutParameters()/ is called with this value
and effectively sets all default values for this layout model. The
configuration part is used to customize the layout model. 

If you do not want any graphical output, or if the pure geometric embedding
is satisfactory, the dimension $n3$ should be zero, and the layout part should
look as follows:
\begin{quote}
\begin{verbatim}
     (layout
      (model        6)
      (align        *)
      (thread       *)
     )
\end{verbatim}
\end{quote}
The displayed order of tuples is realized by the file export interface.
When reading from file, the order is immaterial and tuples can be omitted
instead of passing default values.


\subsection{Potential Solutions}
\begin{quote}
$<solutions> :=$\verb/    /\\
\verb/    /\\
\verb/    (solutions/\\
\verb/     (label       / $<float>^n$\verb/)/\\
\verb/     (predecessor / $<arc>^n$\verb/)/\\
\verb/     (subgraph    / $<float>^m$\verb/)/\\
\verb/     (potential   / $<float>^n$\verb/)/\\
\verb/     (nodeColour  / $<node>^n$\verb/)/\\
\verb/     (edgeColour  / $<arc>^{2m}$\verb/)/\\
\verb/    )/\\
\end{quote}
This part keeps the computational results and corresponds to the internal data
structures discussed in Chapter \ref{clb6}. If an object is imported from file,
the internal data structures are initialized with the external data. This can
be used for post-optimization procedures.

Some care is recommended when a graph object is exported:
All internal data structures which are not needed any longer should be deleted
explicitly before file export. If possible, subgraphs should be converted to
predecessor labels. There are methods available for the conversion of paths,
trees and matchings, see Section \ref{slb_pred} for details.

The displayed order of tuples is realized by the file export interface.
When reading from file, the order is immaterial and tuples can be omitted
instead of passing default values.


\subsection{Configuration}
\label{slb_config}
\begin{quote}
$<configuration> :=$\verb/    /\\
\verb/    /\\
\verb/    (configure/\\
\verb/     /$\{$\verb/-/$<context\;parameter>$\verb/ /$<integer>\}^*$\verb//\\
\verb/    )/\\
\end{quote}
This part may keep any kind of context parameters: logging, method selection
as well as layout information. When a graph object is imported from file, the
method \verb/goblinImport::ReadConfiguration()/ is called, and the information
from file overwrites the respective context variables. The method
\begin{verbatim}
  goblinExport::WriteConfiguration(goblinController&,
                                    TConfig = CONF_DIFF)
\end{verbatim}
allows to write the configuration of the specified controller object to file.
If the optional parameter is \verb/CONF_DIFF/, the values of the configuration
parameters are compared with the default context, and only differing values are
written to the output file. Alternatively, \verb/CONF_FULL/ can be specified to
write a complete set of parameters. During graph export, the method
\begin{verbatim}
  goblinExport::WriteConfiguration(managedObject*)
\end{verbatim}
is used which calls the graph method \verb/ConfigDisplay()/ and then writes
the resulting configuration.



\markright{FILE FORMAT FOR LINEAR PROGRAMS}
\section{File Format for Linear Programs}
\label{slb_format_lp}
The native file format for linear programs and mixed integer problems consists
of a GOBLIN specific header followed by the problem definition and some basis:
\begin{quote}
$<mip\;object> :=$\verb/    /\\
\verb/    /\\
\verb/    (mixed_integer/ \\
\verb/     (rows /$<integer>$\verb/)/\\
\verb/     (columns /$<integer>$\verb/)/\\
\verb/     (size /$<integer>$\verb/)/\\
\verb/     (pivot /$\{$ \verb/*/ $| <integer>\;\;<integer>\;\;\{0|1\}\}$\verb/)/\\
\verb/     (rowvis /$<boolean>^k$\verb/)/\\
\verb/     (colvis /$<boolean>^l$\verb/)/\\
\verb/     /$<configuration>$\\
\verb!    )!\\
\verb!    !\\
\verb/    /$<mps\;problem>$\\
\verb!    !\\
\verb/    /$<mps\;basis>$\\
\end{quote}
Here $<mps\;problem>$ denotes the full description of a mixed integer linear
program in CPLEX MPS format, and $<mps\;basis>$ denotes a respective basis.
The fields in the header are as follows:
\begin{itemize}
\item \verb/rows/ specifies the number $k$ of structural restrictions.
\item \verb/columns/ specifies the number $l$ of variables.
\item \verb/size/ denotes the number of non-zero matrix coefficients.
\item \verb/pivot/ specifies a potential pivot element, listing the row index,
    the column index and if the lower (0) or upper bound (1) is achieved after
    the pivot step. Alternatively, an asterisk indicates that no pivot element
    is defined.
\item \verb/rowviz/ and \verb/colviz/ are currently not in use and must be
    set to 1 constantly.
\item The $<configuration>$ part is formatted as in graph objects files.
\end{itemize}



\markright{CANVAS AND TEXT FORM}
\section{Canvas and Text Form}
\label{slb_viz_formats}
\myinclude\verb/abstractMixedGraph.h/
\begin{mymethods}
\begin{verbatim}
class managedObject
{

    void    ExportToXFig(char*);
    void    ExportToTk(char*);
    void    ExportToAscii(char*);

};
\end{verbatim}
\end{mymethods}
In principle, every data object can be exported into some user readable form.
The method prototypes are listed above and are, so far, implemented for graph
objects (canvas and text forms) and mixed integer problems (only text form).

The text form provided by \verb/ExportToAscii()/ is used by the GOBLET browser.
The exact format for mixed integer problems is described in Section
\ref{slb_lp_text_form}. For mixed graphs, a node oriented format is generated
which lists the node attributes and all node incidences. An incidence record
possibly starts with a mark \verb/P/ to indicate the predecessor arc and with
a mark \verb/B/ to indicate backward arcs. All constant arc labellings are
listed at the end of the file.

Graph can also be written to some canvas formats. The method \verb/ExportToTk()/
generates a Tcl/Tk canvas and is needed by the GOBLET browser again. The
method \verb/ExportToXFig()/ generates a canvas format which can be processed
by the \verb/xfig/ drawing program and the \verb/transfig/ filter software.
By the latter tool, one can obtain a series of other canvas and bitmap formats.
More details about the GOBLIN graph layout functionality can be found in
Section \ref{slb_display}.


\markright{STANDARD FILE FORMATS}
\section{Support of Standard File Formats}
\label{slb_standard_formats}
We have already mentioned that MPS file can be read and written from C++ level.
The GOBLIN library does not support additional graph and lp formats directly,
but there are GOSH scripts \verb/import.tk/ and \verb/export.tk/ which can be
used to read and write DIMACS and TSPLIB problems. Solutions can be exported,
but not imported into the GOSH interpreter. For example, you may input at the
GOSH prompt the following:
\begin{mysample}
\begin{verbatim}
source tcl/import.tk
goblinImport G sample.tsp tsp
G tsp
source tcl/export.tk
goblinExport G sample.tour tour
\end{verbatim}
\end{mysample}
This sequence would load the filter precedures, read a problem in TSPLIB format
from the file \verb/sample.tsp/, compute a tour and save this tour to the file
\verb/sample.tour/ which is again in TSPLIB format.

Do not confuse the Tcl/Tk canvasses which have been discussed in the last
section with the Tcl library graph objects which can be generated from script
level.

\subsection{Import Filters}
\bigskip
\begin{center}
\begin{tabular}{|p{2.1cm}|p{10.1cm}|}
\hline
{\bf Type}       & {\bf Description} \\
\hline
\hline
\verb/gob/   & GOBLIN native format\\
\verb/edge/  & DIMACS generic format for undirected graphs \\
\verb/max/   & DIMACS max-flow instance \\
\verb/min/   & DIMACS min-cost flow instance \\
\verb/asn/   & DIMACS assignment problem instance \\
\verb/geom/  & DIMACS geometric matching instance \\
\verb/tsp/   & TSPLIB symmetric TSP instance \\
\verb/atsp/  & TSPLIB asymetric TSP instance \\
\verb/stp/   & Steinlib instance \\
\verb/mps/   & MPS linear program (standard and CPLEX) \\
\verb/bas/   & MPS basis \\
\hline
\end{tabular}
\end{center}


\subsection{Export Filters}
\bigskip
\begin{center}
\begin{tabular}{|p{2.1cm}|p{10.1cm}|}
\hline
{\bf Type}       & {\bf Description} \\
\hline
\hline
\verb/gob/   & GOBLIN native format \\
\verb/tcl/   & Tcl library graph Object \\
\verb/edge/  & DIMACS generic format for undirected graphs \\
\verb/max/   & DIMACS max-flow instance \\
\verb/min/   & DIMACS min-cost flow instance \\
\verb/asn/   & DIMACS assignment problem instance \\
\verb/flow/  & DIMACS flow labels \\
\verb/geom/  & DIMACS geometric matching instance \\
\verb/match/ & DIMACS matching solution \\
\verb/tsp/   & TSPLIB symmetric TSP instance \\
\verb/atsp/  & TSPLIB asymetric TSP instance \\
\verb/tour/  & TSPLIB solution \\
\verb/mps/   & Standard MPS linear program \\
\verb/cplex/ & CPLEX MPS linear program \\
\verb/lp/    & CPLEX LP format \\
\verb/bas/   & MPS basis \\
\hline
\end{tabular}
\end{center}



\cleardoublepage
\markboth{EXCEPTION HANDLING}{EXCEPTION HANDLING}
\chapter{Exception Handling}
\thispagestyle{fancy}
\label{clb9}
\myinclude\verb/globals.h/
\begin{mymethods}
\begin{verbatim}
class ERGoblin                              {};

class ERIO          : protected ERGoblin    {};
class ERFile        : protected ERIO        {};
class ERParse       : protected ERIO        {};

class ERInternal    : protected ERGoblin    {};

class ERRejected    : protected ERGoblin    {};
class ERRange       : protected ERRejected  {};
class ERCheck       : protected ERRejected  {};

\end{verbatim}
\end{mymethods}
Throughout this document, we have described the exceptions which are thrown by
the various methods. On the other hand, we did not list any declarations of
exceptions. Instead of this, we formulate the general policy which exceptions
should be used in which circumstances:

An exception \verb/ERInternal/ indicates that a data structure has been
corrupted by an error prone method. The calling context is asked to destruct
this object. This error class is a dummy. That is, such exceptions may be
thrown, but should not occur in a method signature. Hence, instead of the
GOBLIN exceptions, an \verb/unexpected/ exception is thrown which usually
causes the termination of a program.

We mention that \verb/absobj.h/ defines macros \verb/InternalError(scope,event)/
and \verb/InternalError1(scope)/ which write some debug information including
file and line information and then raise an internal error. The first macro
takes two strings, the second reads the event description from
\verb/CT.logBuffer/. Use these macros consequently, but be aware that they can
be applied from data object methods only.

An exception \verb/ERRange/ is returned if an array index exeeds the limits.
Occasionally, another data structure has been corrupted by the calling context
before and the calling context cannot handle the exception. In that sense,
\verb/ERRange/ may also denote an internal error.

An exception \verb/ERRejected/ indicates that a method failed its task, but
leaves consistent data structures. This does not mean that the method undoes
all object manipulations which probably would result in very inefficient code.

It is impossible to formalize the notion of consistency from this general point
of view, but only when the concrete algorithm or data structure has been
specified.

For example, the method \verb/abstractGraph::ExtractCycles()/ translates
$2$-factors from the subgraph data structure into predecessor labels. If the
subgraph is not a $2$-factor, the method will use the predecessor labels as
well, but later call the method \verb/ReleasePredecessors()/ to guarantee
consistency.

On the other hand, the method \verb/abstractGraph::ExtractTree(TNode x)/
would return some spanning tree via the predecessor labels even if the
subgraph contains cycles. Nevertheless, an exception \verb/ERCheck/ is returned
to indicate the special situation. If the calling context considers this an
error, it may release the predecessor labels from its own.

The detection of GOBLIN errors heavily depends on the presence of the pragma
\verb/_FAILSAVE_/ which is defined in the file \verb/config.h/. If this pragma
is undefined, no error messages are generated, and no errors are detected.
This substantially increases the performance and decreases the binary size
of problem solvers.

Note that GOBLIN may throw an exception \verb/ERCheck/ even if the pragma
\verb/_FAILSAVE_/ is undefined. Hence, if algorithms work correctly, the
definition of \verb/_FAILSAVE_/ does not change the functionality of a problem
solver, and should be omitted in the final version.



\end{multicols}
\part{GOBLIN Executables}
\begin{multicols}{2}

\markboth{THE GOSH INTERPRETER}{THE GOSH INTERPRETER}
\chapter{The GOSH Interpreter}
\thispagestyle{fancy}
\label{clb_gosh}
The \verb/gosh/ interpreter is based on the Tcl/Tk libraries which are the
outcome of one of the most successful open source projects.
The Tcl interpreter can process complex scripts, but can also be used
interactively. Without much effort, it allows to construct adequate user
interfaces for any kind of mathematical software.

GOSH extends the Tcl/Tk scripting language to graph objects in a natural way.
Although Tcl is a rather traditional language, the windowing commands in Tk and
the GOSH graph commands support some of the ideas of object orientation.

The interpreter is called by the console command \verb/gosh/ and then
starts in the interactive mode. If the name of a script is passed as a
parameter, this script is evaluated. A script \verb/example.gosh/ can also be
evaluated by typing \verb/source example.gosh/ in the interactive mode.

Note that the Tcl interface of the GOBLIN library does not support all of the
library functions, but mainly those which were useful for the graph browser
GOBLET. Note also that the Tcl interface does not check the parameter lists
of a GOSH command exhaustively. Inappropriate parameters are detected by the
library functions, and instructive error reports are available by the log file
in addition to the Tcl return value.

If you have built the shared object \verb/libgoblin.so/, this dynamic library
can be imported to an existing \verb/tcl/ interpreter by the command
\begin{verbatim}
    load $libgoblin goblin
\end{verbatim}
where \verb/$libgoblin/ stands for the complete path to the shared object. So
far, this shared object does not form part of the system installation.


\markright{GOSH RESSOURCES}
\section{GOSH Ressources}
\label{slb_gosh_ressources}
There are two files which are important when using the GOSH shell, namely the
\nt{transscript} and the \nt{configuration file}. Both files are located in the
user root directory.

The transscript file \verb/gosh.log/ is an important source of information
since most GOSH commands do not return instructive error messages. It can be
flushed explicitly by the command \verb/goblin restart/.

The configuration file \verb/.goshrc/ is read during the initialization of
the \verb/gosh/ interpreter and whenever an object is read from file, this
overwrites the default configuration parameters with some user dependent
settings. The format is the same as described in Section \ref{slb_config} for
the graph object files. The current context variable settings may be saved to
\verb/.goshrc/ by the command \verb/goblin export settings/.


\markright{CONTEXT VARIABLES}
\section{Context Variables}
All configuration parameters discussed in Chapter \ref{clb7} can be manipulated
by GOSH scripts. The variable name in GOSH differs from the C++ variable name
just by the prefix \verb/goblin/. For example, the Tcl variable
\verb/goblinMethSolve/ matches the C++ variable \verb/methSolve/. Note that
all configuration parameters are global Tcl variables. If you want to access
\verb/goblinMethSolve/ within a procedure, you have to declare this variable by
\verb/global goblinMethSolve/.


\end{multicols}
\markright{ROOT COMMAND}
\section{Root Command}
After its initilization, a GOSH interpreter provides only one new command
compared with Tcl/Tk. There is a many-to-one correspondence between GOSH
interpreters and GOBLIN controller objects. All options of the root command
\verb/goblin/ manipulate the controller or generate a new GOSH command and, by
that, a new object.
\begin{mysample}
\begin{verbatim}
goblin sparse digraph G 10
G generate arcs 20
\end{verbatim}
\end{mysample}
The first command generates a directed graph with 10 nodes whose Tcl name is
\verb/G/. Initially, this graph does not contain any arcs. Hence the second
command is used to generate 20 random arcs for \verb/G/. If you want to generate
bipartite graphs, specify the number of nodes in each component.

\bigskip
\begin{center}
\begin{tabular}{|p{3cm}|p{9cm}|p{12.5cm}|}
\hline
{\bf Message}       & {\bf Parameters} & {\bf Effects} \\
\hline
\hline
\verb/restart/      & & Reset logging and tracing module \\
\hline
\verb/configure/    & & Set some context flags \\
\hline
\verb/read/         & Object name, file name & Read graph object from file \\
\hline
\verb/mixed graph/ & Object name, number of nodes & Generate graph object \\
\verb/sparse graph/ &  & \\
\verb/sparse digraph/ & & \\
\verb/sparse bigraph/ & & \\
\verb/dense graph/ & & \\
\verb/dense digraph/ & & \\
\verb/dense bigraph/ & & \\
\hline
\verb/ilp/  & Object name, number of rows, number of variables
            & Generate (mixed integer) linear program \\
\verb/lp/   & & \\
\verb/mip/  & & \\
\hline
\verb/export/ & \verb/tk/ $|$ \verb/xfig/ $|$ \verb/goblet/, input file name,
                output file name
              & Read data object from file and translate it to a canvas.
                Uses a separate context \\
\hline
\verb/export ascii/ & input file name, output file name, optional integer
                    & Similar, but export to a text based form.
                      Mainly used for linear programs \\
\hline
\verb/export settings/ & & Write configuration file \\
\hline
\verb/echo/ & \verb/-nonewline/, string & Write string to goblin transscript \\
\hline
\end{tabular}
\end{center}
\bigskip


\subsection{Ressource Management}
\label{slb_tcl_ressource}

\bigskip
\begin{center}
\begin{tabular}{|p{4.3cm}|p{11cm}|}
\hline
{\bf Message}       & {\bf Return value} \\
\hline
\hline
\verb/size/         & Current heap size \\
\hline
\verb/maxsize/      & Maximum heap size \\
\hline
\verb/#allocs/      & Total number of mallocs \\
\hline
\verb/#fragments/   & Current number memory fragments \\
\hline
\verb/#objects/     & Number of currently managed objects \\
\hline
\verb/#timers/      & Number of managed timers \\
\hline
\end{tabular}
\end{center}
\bigskip


\subsection{Thread Support}
\label{slb_thread_support}
The GOSH shell is all but thread-safe, and the thread support is intended for
the GOBLET browser only. The browser utilizes a master thread for the graphical
interface and one slave thread for the computations. Both threads (interpreters)
share the GOBLIN controller and occasionally some graph objects.
The slave interpreter uses an \verb/alias/ for the graph object which can be
traced by the master but should not be edited during computations. All listed
messages start by \verb/goblin solver .../

The master thread can try to terminate the slave thread by the command
\verb/stop/ and wait for termination by testing \verb/goblin solver idle/
which returns \verb/false/ if the computation is still running. Note that only
some solver routines support this termination mechanism. Eventually, the solver
thread returns some information before exiting by using the \verb/return/ and
\verb/throw/ commands. The information is received on master side by the
command \verb/result/.

\begin{center}
\begin{tabular}{|p{3cm}|p{6cm}|p{15.5cm}|}
\hline
{\bf Message}       & {\bf Parameter} & {\bf Description} \\
\hline
\hline
\verb/thread/ & Script name & Evaluate script in an own thread of execution \\
\hline
\verb/alias/  & Object name, object handle & Assign a Tcl command name
                      to an existing graph object \\
\hline
\verb/return/ & Return code & Set return value of a thread \\
\hline
\verb/throw/  & Return code & Set return value of a thread and signal an error \\
\hline
\verb/result/ & & Acknowledge the return code of a thread \\
\hline
\verb/stop/   & & Try to terminate the solver thread \\
\hline
\verb/idle/   & & Check if the solver thread is active \\
\hline
\end{tabular}
\end{center}
\bigskip


\subsection{Messenger Access}
\label{slb_messenger_access}
Just as the context, ther is one messenger object shared by all GOSH shells.
The explicit access to the messenger is restricted to the methods described in
Section \ref{slb_msg_queue}. Note that posting a message from Tcl level is
implemented by the \verb/goblin echo/ command. All listed messages start by
\verb/goblin messenger .../

The messenger does not keep all raised messages but only the most recent ones.
The buffer size is just large enough to fill a screen. Complete and persistent
information is provided by the transscript file.

\bigskip
\begin{center}
\begin{tabular}{|p{4.3cm}|p{11cm}|}
\hline
{\bf Message}   & {\bf Operation / Return value} \\
\hline
\hline
\verb/restart/  & Flush the message queue \\
\hline
\verb/reset/    & Reset the iterator to the first queued message \\
\hline
\verb/eof/      & Are there unread messages? \\
\hline
\verb/void/     & Is the queue empty? \\
\hline
\verb/skip/     & Move iterator to the next message \\
\hline
\verb/text/     & Message text \\
\hline
\verb/class/    & Message class ID \\
\hline
\verb/handle/   & Originators handle \\
\hline
\verb/level/    & Nesting level \\
\hline
\verb/hidden/   & Is message marked as hidden? \\
\hline
\verb/filename/ & Name of the most recent trace file \\
\hline
\verb/blocked/  & Is the solver thread currently waiting at trace point? \\
\hline
\verb/unblock/  & Free the solver thread from waiting at trace point \\
\hline
\end{tabular}
\end{center}
\bigskip


\subsection{Accessing Timers}
\label{slb_timer_access}
The commands listed here wrap the functionality described in Section
\ref{slb_timers}. All messages start by the prefix \verb/goblin timer .../
and the timer index which must be ranged in \verb/0/ to
\verb/[expr [goblin #timers]-1]/.

\bigskip
\begin{center}
\begin{tabular}{|p{4.3cm}|p{11cm}|}
\hline
{\bf Message}   & {\bf Operation / Return value} \\
\hline
\hline
\verb/reset/    & Reset the timer \\
\hline
\verb/enable/   & Enable the timer \\
\hline
\verb/disable/  & Disable the timer \\
\hline
\verb/label/    & Return the label \\
\hline
\verb/acc/      & Return the accumulated times \\
\hline
\verb/prev/     & Return the previous timer value \\
\hline
\verb/max/      & Return the maximum timer value \\
\hline
\verb/min/      & Return the minimum timer value \\
\hline
\verb/av/       & Return the average timer value \\
\hline
\end{tabular}
\end{center}

\bigskip
\noindent
The running time of timer $j$ relative to the previous cycle of timer $i$ is
retrieved by the command \verb/goblin timer $i child $j/.


\markright{GENERAL OBJECT MESSAGES}
\section{General Object Messages}
All commands other than the \verb/goblin/ root command are associated with
data objects to which messages can be sent. Messages may manipulate the
addressed object, generate new objects from existing or call a solver routine.
In many cases, the correspondence between the Tcl message and the signature of
the GOBLIN C++ method called is obvious. A detailed documentation of the Tcl
commands is therefore omitted.

\begin{center}
\begin{tabular}{|p{2cm}|p{14.5cm}|p{8cm}|}
\hline
{\bf Message}       & {\bf Parameters} & {\bf Description} \\
\hline
\hline
\verb/delete/       & & Delete object and Tcl command \\
\hline
\verb/trace/        & & Write trace object \\
\hline
\verb/handle/       & & Return object handle \\
\hline
\verb/master/       & & Register this object as the master object \\
\hline
\verb/is/           & \verb/graph/ $|$ \verb/mip/ $|$ \verb/sparse/ $|$ 
                      \verb/undirected/ $|$ \verb/directed/ $|$ 
                      \verb/bipartite/ $|$ \verb/balanced/
                    & Evaluate object type  \\
\hline
\verb/set name/     & file name & Assign a file name \\
\hline
\end{tabular}
\end{center}

\bigskip
\noindent
The above messages apply to all GOBLIN data objects.
In the following, we list the messages for special classes of data objects.
Currently, graph objects and linear problems are covered by the Tcl wrapper.
The Tcl interpreter adopts the graph polymorphism from the core library.



\markright{GRAPH RETRIEVAL MESSAGES}
\section{Graph Retrieval Messages}
\begin{center}
\begin{tabular}{|p{3cm}|p{9cm}|p{12.5cm}|}
\hline
{\bf Message}       & {\bf Parameter} & {\bf Description} \\
\hline
\hline
\verb/write/        & File name & Write object to file \\
\hline
\verb/#nodes/       &  &  Return number of nodes \\
\hline
\verb/#arcs/        &  &  Return number of arcs \\
\hline
\verb/#artificial/  &  &  Return number of bend nodes \\
\hline
\verb/source/       &  &  Return the default source node \\
\hline
\verb/target/       &  &  Return the default target node \\
\hline
\verb/root/         &  &  Return the default root node \\
\hline
\verb/cardinality/  &  &  Return subgraph cardinality \\
\hline
\verb/weight/       &  &  Return subgraph weight \\
\hline
\verb/length/       &  &  Return total length of predecessor arcs \\
\hline
\verb/max/          & \verb/ucap/ $|$ \verb/lcap/ $|$ \verb/length/ $|$
                      \verb/demand/ $|$ \verb/cx/ $|$ \verb/cy/
                    & Return maximum label \\
\hline
\verb/is/           & \verb/planar/ 
                    & Perform planarity test \\
\hline
\verb/constant/     & \verb/ucap/ $|$ \verb/lcap/ $|$ \verb/length/ $|$ \verb/demand/
                    & Is this a constant labeling? \\
\hline
\verb/adjacency/    & Start node, end node & Return an adjacency or \verb/*/ \\
\hline
\end{tabular}
\end{center}



\markright{GRAPH MANIPULATION MESSAGES}
\section{Graph Manipulation Messages}
\begin{center}
\begin{tabular}{|p{2cm}|p{7cm}|p{15.5cm}|}
\hline
{\bf Message}       & {\bf Parameters} & {\bf Description} \\
\hline
\hline
\verb/node/         & \verb/insert/     & Insert graph node \\
\hline
\verb/arc/          & \verb/insert/, head, tail & Insert arc \\
\hline
\verb/generate/     & \verb/arcs/, number of arcs  & Generate random arcs \\
\hline
                    & \verb/eulerian/, number of arcs & Generate random cycle \\
\hline
                    & \verb/regular/, node degree & Generate random regular graph \\
\hline
                    & \verb/length/, \verb/ucap/, \verb/lcap/, \verb/geometry/,
                    & Generate random node and arc labels \\
\hline
                    & \verb/parallels/
                    & Split arcs so that every arc has capacity $\leq 1$\\
\hline
\end{tabular}
\end{center}

\vfill
\begin{center}
\begin{tabular}{|p{2cm}|p{7cm}|p{15.5cm}|}
\hline
{\bf Message}       & {\bf Parameters} & {\bf Description} \\
\hline
\hline
\verb/extract/      & \verb/tree/, root node
                    & Check if the subgraph forms a rooted tree. Generate
                      predecessor labels \\
\hline
                    & \verb/trees/
                    & Check if the subgraph splits into trees. Generate
                      predecessor labels \\
\hline
                    & \verb/path/, start node $s$ and end node $t$
                    & Check if $s$ and $t$ are in the same connected
                      component of the subgraph. Generate predecessor labels
                      for some $st$-path \\
\hline
                    & \verb/cycles/
                    & Check if the subgraph forms a $2$-factor. Generate
                      predecessor labels. Return the number of cycles\\
\hline
                    & \verb/matching/
                    & Check if the subgraph forms a $1$-matching. Generate
                      predecessor labels\\
\hline
                    & \verb/edgecover/
                    & Check if the subgraph forms a (maximum cardinality)
                      $1$-matching. Return a (minimum size) edge cover by the
                      predecessor labels\\
\hline
                    & \verb/cut/
                    & Generate colours which separate the nodes with finite
                      and infinite distance labels \\
\hline
                    & \verb/bipartition/
                    & Generate colours which separate the nodes with odd and
                      even distance labels\\
\hline
                    & \verb/colours/
                    & Generate node colours equivalent (not equal) with the
                      node partition \\
\hline
\verb/delete/       & \verb/subgraph/, \verb/labels/,
                        & Delete the specified data structure \\
                    & \verb/predecessors/, \verb/colours/, & \\
                    & \verb/potentials/, \verb/partition/ & \\
\hline
\verb/set/          & \verb/ucap/ $|$ \verb/lcap/ $|$ \verb/length/ $|$ \verb/demand/
                    & Assign a constant labeling \\
\hline
                    & \verb/source/ $|$ \verb/target/ $|$ \verb/root/, node index
                    & Assign special nodes \\
\hline
\end{tabular}
\end{center}


\clearpage
\markright{PLANARITY MESSAGES}
\section{Sparse Graphs and Planarity}
All listed methods manipulate the order of incidences of each node. Partially, first incidences, arc orientations
and/or an exterior face are also assigned.
The series parallelity methods can be combined and provide further general options:
\begin{itemize}
\item \verb/-source/: Fix the upper terminal node in the single arc reduction
\item \verb/-target/: Fix the lower terminal node in the single arc reduction
\item \verb/-undirected/: Ignore the arc orientations in the recognition phase
\end{itemize}

\bigskip
\begin{center}
\begin{tabular}{|p{3cm}|p{2cm}|p{19.5cm}|}
\hline
{\bf Message}       & {\bf Parameter} & {\bf Description} \\
\hline
\hline
\verb/incidences/   & \verb/planarize/
                    & Check if the graph is planar. In occasion, export a planar representation \\
                    & \verb/randomize/
                    & Random order of the incidences \\
                    & \verb/geometric/
                    & Reorder the incidences according to the current drawing \\
                    & \verb/outerplanar/
                    & For planar graph objects: Refine the present planar representation to an outerplane
                      representation and return an arc on the exterior face \\
\hline
\verb/series-parallel/  & \verb/-embedding/
                    & Check if the graph is edge series-parallel. In occasion, export a planar representation \\
                        & \verb/-orient/
                    & Check if the graph is edge series-parallel. In occasion, reorient the graph arcs accordingly \\
                        & \verb/-layout/
                    & Check if the graph is edge series-parallel. In occasion, export a visibility representation \\
                        & \verb/-minor/
                    & Check if the graph is edge series-parallel. If not, export a forbidden minor \\
\hline
\verb/exterior/     & arc index & For planar graph objects:
                        Set the exterior face to the left hand side of the
                        specified arc. Adjust the first incidence of the
                        exterior nodes \\
\hline
\end{tabular}
\end{center}

\clearpage
\markright{LAYOUT MESSAGES}
\section{Graph Layout Messages}
% Most recent revision: CFP, 2005-11-19
The following messages apply to every graph object \verb/G/ with the prefix
\begin{verbatim}
    G layout ...
\end{verbatim}
and manipulate the node coordinates. Atificial nodes (which are only used for
layout purposes) are also added, deleted or shifted. Most methods allow to
specify \verb/-spacing/ followed by the desired minimum distance between two
nodes. For grid drawings, the keyword \verb/-grid/ is synonymous. Whenever
\verb/-dx/ and \verb/-dy/ are available, \verb/-spacing/ can also be used.

\bigskip
\begin{center}
\begin{tabular}{|p{2.0cm}|p{8cm}|p{14.5cm}|}
\hline
{\bf Message}       & {\bf Options} & {\bf Description} \\
\hline
\hline
\verb/scale/        & bounding box (minX maxX minY maxY)
                    & Scale geometric embedding to the specified size. When
                      max < min, the drawing is mirrored \\
\hline
\verb/strip/        &
                    & Shift the geometric embedding so that the upper left corner
                      of the bounding box becomes the origin \\
\hline
\verb/align/        & \verb/-spacing/
                    & Reroute arcs so that parallel arcs and loops can be
                      distinguished \\
\hline
\verb/tree/         & \verb/-dx/, \verb/-dy/, \verb/-left/, \verb/-right/
                    & Embedding guided by the predecessor arcs. A tree or forest
                      is drawn, and the nodes are aligned atop of its successors
                      as specified \\
\hline
\verb/circular/     & \verb/-spacing/, \verb/-colours/, \verb/-predecessors/, \verb/-outerplanar/
                    & Embedding of the graph on a cycle. Use an option
                      to control the node order \\
\hline
\verb/orthogonal/   & \verb/-grid/, \verb/-small/
                    & Embedding of the graph in a grid. The small node option
                      applies to 2-connected graphs with maximum degree 4 or
                      less \\
\hline
\verb/fdp/          & \verb/-spacing/, \verb/-preserve/, \verb/-unrestricted/
                    & Force directed layout. Using the preserve option, nodes
                      are shifted without modifying the edge crossing properties \\
\hline
\verb/layered/      & \verb/-dx/, \verb/-dy/, \verb/-colours/, \verb/-span/, \verb/-vertical/,
                      \verb/-sweep/, \verb/-align/, \verb/-fdp/, \verb/-horizontal/
                    & Layered drawing tool box \\
\hline
\verb/plane/        & \verb/-grid/, \verb/-convex/, \verb/-basis/
                    & For planar graph objects: Straight line drawing of the
                      current embedding and the specified basis arc. Convex
                      drawing requires 3-connectivity \\
\hline
\verb/visibility/   & \verb/-grid/, \verb/-giotto/, \verb/-raw/, \verb/-series-parallel/
                    & For planar graph objects: Visibility representation or
                      an follow-up Giotto drawing \\
\hline
\verb/equilateral/  & \verb/-spacing/
                    & For 2-connected outerplanar graphs: Draw every interior
                      face as a regular polygone \\
\hline
\end{tabular}
\end{center}



\newpage
\markright{NODE AND ARC MESSAGES}
\section{Graph Node and Arc Messages}
The most significant difference between the C++ library functions and the GOSH
message concerns the nodes and arcs of a graph. All messages which address the
node $3$ and the arc $7$ of a graph \verb/G/ start
\begin{verbatim}
    G node 3 ...
\end{verbatim}
and
\begin{verbatim}
    G arc 7 ...
\end{verbatim}
respectively. This applies to all messages listed in Table
\ref{slb_node_messages} and Table \ref{slb_arc_messages}. All
arc indices range between $0$ and $2m-1$, and arc directions are
specified by the least significant bit. On the other hand, arc insertion
messages return the new arc index without this additional bit.
\begin{mysample}
\begin{verbatim}
G spath $s
set a [expr 2*[G arc insert $u $v]]
G arc $a set length [expr -[G node $u potential]
                          +[G node $v potential]]
\end{verbatim}
\end{mysample}
would generate a new arc with start node \verb/u/ and end node \verb/v/.
The new arc is initialized with zero reduced length so that it can replace one
of the arcs in the shortest path tree which was computed before.

In order to specify the drawing of a graph arc \verb/a/, first add an alignment
point by the command
\begin{verbatim}
    G arc $a set align $x $y
\end{verbatim}
where \verb/x/ and \verb/y/ are the coordinates of the alignment point
(This denotes the point where the arc labels are printed). Then interpolation
points are successively defined by
\begin{verbatim}
    G arc $a interpolate $x $y
\end{verbatim}
where \verb/x/ and \verb/y/ are the coordinates again.
New interpolation points are placed at the end of the list. If an arc
is deleted, its alignment point and all interpolation point are deleted
recursively. If a node is deleted, all incident arcs are deleted
recursively.

\begin{mysample}
\begin{verbatim}
for {set a 0} {$a<[G #arcs]} {incr a} {
    set a2 [expr 2*$a]
    if {[G arc $a2 head] == [G arc $a2 tail]} {
        set $x0 [G node [G arc $a2 head] cx]
        set $y0 [G node [G arc $a2 head] cy]
        G arc $a2 set align $x0 [expr $y0-10]
        G arc $a2 interpolate [expr $x0-10] [expr $y0-10]
        G arc $a2 interpolate $x0 [expr $y0-20]
        G arc $a2 interpolate [expr $x0+10] [expr $y0-10]
    }
}
\end{verbatim}
\end{mysample}
checks the graph for loops which cannot be displayed without interpolation
points. For every loop, an alignment point for the arc label and three
interpolation points for a spline drawing are defined.

Whenever undefined or infinite labels are needed they are replaced by an
asterisk \verb/*/.

\subsection{Node Based Messages}
\label{slb_node_messages}
\medskip
\begin{center}
\begin{tabular}{|p{3cm}|p{21.5cm}|}
\hline
{\bf Message}       & {\bf Description} \\
\hline
\hline
\verb/delete/       & Delete node \\
\hline
\verb/demand/       & Return the node demand \\
\hline
\verb/cx/           & Return the $x$-coordiante \\
\hline
\verb/cy/           & Return the $y$-coordinate \\
\hline
\verb/colour/       & Return the node colour or \verb/*/ \\
\hline
\verb/degree/       & Return the subgraph degree \\
\hline
\verb/distance/     & Return the distance label or \verb/*/ \\
\hline
\verb/potential/    & Return the node potential \\
\hline
\verb/predecessor/  & Return the predecessor arc or \verb/*/ \\
\hline
\verb/first/        & Return some outgoing arc or \verb/*/ \\
\hline
\verb/thread/       & Return the next bend node index or \verb/*/ \\
\hline
\verb/hidden/       & Check if the node is displayed \\
\hline
\verb/set thread/   & For artificial nodes: Insert new bend nodes
                      after that node with the given coordinates \\
\hline
\verb/set/          & Manipulate one of the listed node ressources \\
\hline
\end{tabular}
\end{center}
\bigskip


\subsection{Arc Based Messages}
\label{slb_arc_messages}
\medskip
\begin{center}
\begin{tabular}{|p{3cm}|p{21.5cm}|}
\hline
{\bf Message}       & {\bf Description} \\
\hline
\hline
\verb/delete/       & Delete arc \\
\hline
\verb/contract/     & Contract arc \\
\hline
\verb/straight/     & Release all bend node of this arc \\
\hline
\verb/ucap/         & Return the upper capacity bound or \verb/*/ \\
\hline
\verb/lcap/         & Return the lower capacity bound \\
\hline
\verb/length/       & Return the arc length \\
\hline
\verb/subgraph/     & Return the subgraph label \\
\hline
\verb/orientation/  & Return the orientation \\
\hline
\verb/head/         & Return the start node \\
\hline
\verb/tail/         & Return the end node \\
\hline
\verb/right/        & Return a further arc with the same start node \\
\hline
\verb/align/        & Return the label alignment point index or \verb/*/ \\
\hline
\verb/set align/    & Generate an alignment point with the given coordinates \\
\hline
\verb/hidden/       & Check if the arc is displayed \\
\hline
\verb/set/          & Manipulate one of the listed arc ressources \\
\hline
\end{tabular}
\end{center}


\clearpage
\markright{GRAPH OPTIMIZATION MESSAGES}
\section{Graph Optimization Messages}
The Tcl API of the C++ problem solver methods on script level is obvious:
\begin{mysample}
\begin{verbatim}
goblin read G "example.gob"
G set demand 2
G set ucap *
G maxmatch
G write "example.rst"
\end{verbatim}
\end{mysample}
computes a $2$-matching of the graph whereas
\begin{quote}
\begin{verbatim}
G set demand 2
G set ucap 1
G maxmatch
\end{verbatim}
\end{quote}
determines a $2$-factor.

Note that a matching solver is defined for undirected graphs only while network
flow methods can be accessed with digraphs only. The Tables
\ref{slb_undirected_messages}, \ref{slb_directed_messages},
\ref{slb_bipartite_messages} and \ref{slb_balanced_messages} list all messages
which are restricted to special classes.

In order to simplify contributions by other authors, some solver messages are
available from script level for every graph object even if there are no solver
methods for mixed graphs yet. This applies for the tree packing and the Chinese
postman solver.

\bigskip
\begin{center}
\begin{tabular}{|p{3cm}|p{8cm}|p{12.5cm}|}
\hline
{\bf Message}          & {\bf Parameter} & {\bf Description} \\
\hline
\hline
\verb/spath/            & Root node
                        & Compute a shortest path tree and return its length \\
\hline
\verb/components/       & \verb/-strong/, \verb/-kappa/ (Order of Connectivity)
                        & Determine edge connected components \\
\hline
\verb/connectivity/     & \verb/-strong/, \verb/-edge/
                        & Determine a minimum cut \\
\hline
\verb/colouring/        & Accepted number of colours (optional)
                        & Compute a node colouring \\
\hline
\verb/edgecolouring/    & Accepted number of colours (optional)
                        & Compute an edge colouring \\
\hline
\verb/cliques/          & Accepted number of cliques (optional)
                        & Compute a cliques cover \\
\hline
\verb/clique/           &
                        & Compute a maximum clique and return its cardinality \\
\hline
\verb/vertexcover/      &
                        & Compute a vertex cover and return its cardinality \\
\hline
\verb/stable/           &
                        & Compute a maximum stable set and return its cardinality \\
\hline
\verb/eulerian/         & & Compute an Euler cycle if one exists. Return if the Graph
                          is Eulerian \\
\hline
\verb/bipolar/          &
                        & Compute an $st$-numbering if the graph is 2-connected \\
\hline
\verb/topsort/          &
                        & Compute a topological ordering or return a node on a cycle \\
\hline
\verb/critical/         &
                        & Compute a critical path and return its end node \\
\hline
\verb/mintree/          & \verb/-root/ Root node (optional)
                        & Compute a minimum spanning arborescence and return its length \\
\hline
\verb/mintree/          & \verb/-max/
                        & Compute a maximum spanning arborescence \\
\hline
\verb/mintree/          & \verb/-cycle/
                        & Compute a minimum 1-cycle tree \\
\hline
\verb/tsp/              & Root node (optional)
                        & Compute an Hamiltonian cycle and return its length \\
\hline
\verb/steiner/          & Root node
                        & Compute a minimum steiner tree and return its length \\
\hline
\verb/treepacking/      & Root node
                        & Compute a maximum packing of arborescences \\
\hline
\verb/maxcut/           &
                        & Compute a cut of maximum capacity and return this capacity \\
\hline
\verb/postman/          &
                        & Compute a minimum Eulerian supergraph and return its weight \\
\hline
\verb/maxflow/          & Source, target
                        & Compute a maximum $st$-flow and return the flow value \\
\hline
\verb/mincflow/         & Source, target 
                        & Compute a maximum $st$-flow of minimum weight and return this weight \\
\hline
\verb/circulation/      & & Compute an admissible circulation or $b$-flow \\
\hline
\verb/minccirc/         & & Compute an admissible circulation or $b$-flow
                            of minimum weight and return this weight \\
\hline
\end{tabular}
\end{center}


\markright{DERIVED GRAPH CONSTRUCTORS}
\section{Derived Graph Constructors}
\medskip
\begin{center}
\begin{tabular}{|p{5.3cm}|p{10cm}|}
\hline
{\bf Message}        & {\bf Description} \\
\hline
\hline
\verb/linegraph/     & Generate line graph \\
\hline
\verb/linegraph -planar/ & Generate a planar line graph \\
\hline
\verb/truncate/      & Replace the verices by cycles \\
\hline
\verb/complement/    & Generate complementary graph \\
\hline
\verb/underlying/    & Generate underlying graph \\
\hline
\verb/dualgraph/     & Generate the dual graph of a plane graph \\
\hline
\verb/spread/        & Generate an outerplanar representaion of a plane graph \\
\hline
\verb/induced subgraph/ & Subgraph induced by a specified node colour \\
\hline
\verb/induced orientation/ & Orientation induced by the node colours \\
\hline
\verb/induced bigraph/  & Bigraph induced by two specified node colours \\
\hline
\verb/transitive/    & Generate transitive closure \\
\hline
\verb/intransitive/  & Generate intransitive reduction \\
\hline
\verb/contraction/   & Contract every node colour into a single node \\
\hline
\verb/nodesplitting/ & Generate node splitting \\
\hline
\verb/orientation/   & Generate complete orientation \\
\hline
\verb/distances/     & Generate distance graph \\
\hline
\end{tabular}
\end{center}


\markright{MESSAGES FOR UNDIRECTED GRAPHS}
\section{Messages for Undirected Graphs}
\label{slb_undirected_messages}
\medskip
\begin{center}
\begin{tabular}{|p{3cm}|p{8cm}|p{12.5cm}|}
\hline
{\bf Message}       & {\bf Parameters} & {\bf Description} \\
\hline
\hline
\verb/subgraph/     & Object name & Export subgraph into a separate object \\
\hline
\verb/metric/       & Object name & Generate metric closure \\
\hline
\verb/tiling/       & Object name, number of rows, number of columns
                    &  Generate graph which consists of several copies of
                    the addressed graph \\
\hline
\verb/maxmatch/     & & Compute maximum matching and return its cardinality \\
\hline
\verb/mincmatch/    & & Compute perfect matching of minimum weight, return
                        this weight or \verb/*/ \\
\hline
\verb/edgecover/    & & Compute an edge cover of minimum weight and return
                        this weight \\
\hline
\verb/tjoin/        & & Compute minimum $t$-join and return its weight or \verb/*/ \\
\hline
\end{tabular}
\end{center}


\markright{MESSAGES FOR DIRECTED GRAPHS}
\section{Messages for Directed Graphs}
\label{slb_directed_messages}
\medskip
\begin{center}
\begin{tabular}{|p{3cm}|p{8cm}|p{12.5cm}|}
\hline
{\bf Message}       & {\bf Parameters} & {\bf Description} \\
\hline
\hline
\verb/subgraph/     & Object name & Export subgraph into a separate object \\
\hline
\verb/splitgraph/   & & Generate a balanced version of the network flow problem \\
\hline
\end{tabular}
\end{center}


\markright{MESSAGES FOR BIPARTITE GRAPHS}
\section{Messages for Bipartite Graphs}
\label{slb_bipartite_messages}
\medskip
\begin{center}
\begin{tabular}{|p{3cm}|p{8cm}|p{12.5cm}|}
\hline
{\bf Message}       & {\bf Parameters} & {\bf Description} \\
\hline
\hline
\verb/#outer/,      & & Cardinality of the left hand component\\
\hline
\verb/#inner/,      & & Cardinality of the right hand component \\
\hline
\verb/node/ & index, \verb/swap/ & Move node the other component \\
\hline
\end{tabular}
\end{center}


\markright{MESSAGES FOR BALANCED FLOW NETWORKS}
\section{Messages for Balanced Flow Networks}
\label{slb_balanced_messages}
\medskip
\begin{center}
\begin{tabular}{|p{3cm}|p{8cm}|p{12.5cm}|}
\hline
{\bf Message}       & {\bf Parameters} & {\bf Description} \\
\hline
\hline
\verb/maxbalflow/      & Source
                    & Compute a maximum balanced $st$-flow, return the flow value \\
\hline
\verb/mincbalflow/     & Source
                    & Compute a maximum balanced $st$-flow of minimum weight and return this weight \\
\hline
\end{tabular}
\end{center}


\newpage
\markright{LINEAR PROGRAMMING}
\section{Linear Programming}

\subsection{Instance Manipulation Messages}
\medskip
\begin{center}
\begin{tabular}{|p{3cm}|p{9cm}|p{11.5cm}|}
\hline
{\bf Message}       & {\bf Parameters} & {\bf Operation} \\
\hline
\hline
\verb/read/         & \verb/bas/, \verb/basis/, \verb/mps/
                      or \verb/problem/, file name
                    & Read MIP instance or basis \\
\hline
\verb/maximize/     & & Mark as maximization problem \\
\hline
\verb/minimize/     & & Mark as minimization problem \\
\hline
\verb/invert/       & & Invert the object vector and sense \\
\hline
\verb/nullify/      & & Dismiss the objective vector \\
\hline
\verb/resize/       & Number of rows, number of
                      columns, number of non-zero coefficients
                    & Reallocate MIP instance with
                      the specified dimensions \\
\hline
\verb/strip/        & & Reallocate MIP instance within
                        a minimum of memory \\
\hline
\verb/set/          & \verb/coeff/ or \verb/coefficient/, row
                      index, column index, float value
                    & Set a coefficient in the restriction matrix \\
\hline
                    & \verb/index/, row index, variable
                      index, \verb/upper/ or \verb/lower/
                    & Specify a basis restriction \\
\hline
\verb/reset/        & & Reset basis to the lower
                        variable range restrictions \\
\hline
\end{tabular}
\end{center}


\vfill
\subsection{Instance Retrieval Messages and Basis Access}
\medskip
\begin{center}
\begin{tabular}{|p{3cm}|p{9cm}|p{12.5cm}|}
\hline
{\bf Message}       & {\bf Parameter} & {\bf Operation / Return Value} \\
\hline
\hline
\verb/write/        & \verb/lp/, \verb/mps/, \verb/cplex/,
                      \verb/bas/ or \verb/basis/, file name
                    & Write instance or basis to file \\
\hline
\verb/#rows/ or     & & The number of restrictions \\
\verb/#restrictions/& & \\
\hline
\verb/#columns/ or  & & The number of variables \\
\verb/#variables/   & & \\
\hline
\verb/orientation/  & & \verb/row/ or \verb/column/\\
\hline
\verb/direction/    & & \verb/maximize/ or \verb/minimize/\\
\hline
\verb/coeff/ or \verb/coefficient/
                    & row index, variable index
                    & A coefficient of the restriction matrix \\
\hline
\verb/tableau/      & \verb/coeff/ or \verb/coefficient/,
                      row index, column index
                    & A tableau coefficient \\
\hline
\verb/inverse/      & \verb/coeff/ or \verb/coefficient/,
                      row index, column index
                    & A basis inverse coefficient \\
\hline
\verb/feasible/     & \verb/primal/ or \verb/dual/
                    & Is the current basis feasible? \\
\hline
\verb/pivot/        & \verb/veriable/ or \verb/column/
                    & Return the pivot column \\
\hline
                    & \verb/row/ or \verb/restriction/
                    & Return the pivot row \\
\hline
                    & \verb/direction/
                    & Return \verb/upper/ or \verb/lower/ \\
\hline
\verb/objective/    & \verb/primal/ or \verb/dual/
                    & Return the objective value \\
\hline
\verb/row index/    & restriction label
                    & Corresponding index or \verb/*/ \\
\hline
\verb/column index/ & variable label
                    & Corresponding index or \verb/*/ \\
\hline
\end{tabular}
\end{center}


\bigskip
\subsection{Row and Column Based Messages}

All messages which address the restriction $3$ and the variable $7$ of a
mixed integer problem \verb/X/ start
\begin{verbatim}
    X row 3 ...
\end{verbatim}
and
\begin{verbatim}
    X column 7 ...
\end{verbatim}
respectively. You may also use the keywords \verb/restriction/ instead of
\verb/row/ and the keyword \verb/variable/ instead of \verb/column/.
This syntax applies to all messages listed in Table \ref{slb_row_messages}
and Table \ref{slb_col_messages}. All column indices range between $0$ and
$l-1$. The row indices range between $0$ and $k-1$ respectively $k+l-1$
depending on whether variable range restrictions are included. Here, $k$ and
$l$ denote the effective dimensions returned by \verb/[X #restrictions]/ and
\verb/[X #variables]/ respectively.

Whenever infinite labels are needed they are replaced by an asterisk \verb/*/.
Lower bounds cannot be set to $+\infty$, upper bounds are never $-\infty$ which
makes the procedure unique.
\begin{mysample}
\begin{verbatim}
if {[X row $i type]=="non_basic"} {
    set k [X column $j index]
    catch {X pivot $i $j upper}
}

puts [X row $i type]
\end{verbatim}
\end{mysample}
would check if the $i$th row is in the current basis and occasionally try to
exchange the current basis row $k$ matched with variable $j$ with $i$. If the
pivoting is successful, that is, if a basis structure can be maintained,
the output is \verb/upper/.


\bigskip
\subsection{Row Based Messages}
\label{slb_row_messages}
\medskip
\begin{center}
\begin{tabular}{|p{3cm}|p{9cm}|p{12.5cm}|}
\hline
{\bf Message}           & {\bf Parameter} & {\bf Operation / Return Value} \\
\hline
\hline
\verb/insert/           & Upper and lower bound (or \verb/*/), variable type
                        & Add a variable (column) \\
\hline
\verb/cancel/           & 
                        & Effectively deletes the restriction \\
\hline
\verb/ubound/           & 
                        & Upper right-hand side bound \\
\hline
\verb/lbound/           & 
                        & Lower right-hand side bound \\
\hline
\verb/label/            & 
                        & The restriction label \\
\hline
\verb/type/             & 
                        & The restriction type \\
\hline
\verb/index/            & 
                        & The variable associated with the restriction in
                          basis or \verb/*/ \\
\hline
\verb/value/            & \verb/upper/ or \verb/lower/
                        & The (dual) variable value \\
\hline
\verb/slack/            & \verb/upper/ or \verb/lower/
                        & The slack \\
\hline
\verb/set/              & \verb/ubound/, \verb/lbound/ or \verb/label/,
                          ressource value
                        & Change one of the listed ressources \\
\hline
\end{tabular}
\end{center}


\bigskip
\subsection{Column Based Messages}
\label{slb_col_messages}
\medskip
\begin{center}
\begin{tabular}{|p{3cm}|p{9cm}|p{12.5cm}|}
\hline
{\bf Message}           & {\bf Parameter} & {\bf Operation / Return Value} \\
\hline
\hline
\verb/insert/           & Upper and lower bound (or \verb/*/), variable type
                        & Add a variable (column) \\
\hline
\verb/cancel/           & 
                        & Effectively deletes the variable \\
\hline
\verb/urange/           & 
                        & The upper variable bound \\
\hline
\verb/lrange/           & 
                        & The lower variable bound \\
\hline
\verb/cost/             & 
                        & The cost coefficient \\
\hline
\verb/type/             & 
                        & The variable type \\
\hline
\verb/label/            & 
                        & The variable name \\
\hline
\verb/index/            & 
                        & The basis row associated with the variable\\
\hline
\verb/value/            & 
                        & The (primal) variable value \\
\hline
\verb/mark/             & \verb/float/, \verb/int/ or \verb/integer/
                        & Set variable type \\
\hline
\verb/set/              & \verb/urange/, \verb/lrange/, \verb/cost/ or
                          \verb/label/, ressource value
                        & Change one of the listed ressources \\
\hline
\end{tabular}
\end{center}


\bigskip
\subsection{Optimization Messages}
\medskip
\begin{center}
\begin{tabular}{|p{3cm}|p{9cm}|p{12.5cm}|}
\hline
{\bf Message}       & {\bf Parameter} & {\bf Operation} \\
\hline
\hline
\verb/solve/        & \verb/lp/, \verb/primal/ or \verb/dual/
                    & Solve linear relaxation \\
\hline
                    & \verb/mixed/ or \verb/mip/
                    & Solve mixed integer problem \\
\hline
\verb/start/        & \verb/primal/ or \verb/dual/
                    & Determine feasible solution of
                      the linear relaxation \\
\hline
\verb/pivot/        & Variable index, incoming row
                      index, \verb/upper/ or \verb/lower/
                    & Move from one basis to another \\
\hline
\end{tabular}
\end{center}



\cleardoublepage
\begin{multicols}{2}
\markboth{GOBLIN EXECUTABLES}{SOLVER APPLICATIONS}
\chapter{Solver Applications}
\thispagestyle{fancy}
\label{clb13}
One may argue that explicit solver programs are immaterial by the existence of
the GOSH interpreter. But the overhead for tracing and the graphical display 
is obvious, and the compilation of efficient solvers does not require a Tcl/Tk
installation.

All GOBLIN executables support the runtime configuration as described in
Section \ref{slb_rconf}. That is, one can control the logging and tracing
functionality (including the graphical display) from the console. 


\markright{SOLVER APPLICATIONS}
\section{Solver Applications}
The last argument passed to a problem solver is the input file name, say
\verb/xyz/. The solver expects a file \verb/xyz.gob/ which
consists of a graph definition (see Section \ref{slb_format} for the file
formats). Do not specify the extension \verb/.gob/ explicitly!

The computational results are written to a file \verb/xyz.rst/, and the logging
information is written to a file \verb/xyz.log/. By default, the output is the
entire graph definition which can be read by the program \verb/gobshow/ to
display the results. One can produce a more economic output by using the
options \verb/-sh/ and \verb/-silent/. The first option forces the solver to
write only the relevant data structure (subgraph, predecessor labels, etc.)
to file, the second option suppresses the writing of a log file completely.

Note that the main routines do not support any error handling yet.
In case of trouble, consult the log file. The return value indicates the
existence of a feasible solution rather than internal errors. If the log file
does not give evidence of what has gone wrong, please contact the author.



\subsection{Matching Problems}
The program \verb/optmatch/ is the GOBLIN solver for all kinds of matching
problems. The input graph may be any undirected graph, either sparse or
complete. For bipartite graphs, specialized methods are used.

If one specifies \verb/-w/, either a perfect matching of minimal costs is
computed or the program shows that no perfect matching exists. If this option
is omitted, the objective is a maximal or minimum deficiency matching. For
example,
\begin{verbatim}
    optmatch -w samples/optmatch12
\end{verbatim}
would return the $1$-factor depicted in Figure \ref{flb_optmatch} since all
node demands defined in the input file are 1.

The node demands are specified in the input file. If you want to distinguish
upper and lower bounds on the node degrees, you may use the option \verb/-deg/.
Then the solver expects two additional input files whose names differ from
the graph definition file only by the extensions \verb/.adg/ respectively
\verb/.bdg/. The first file consists of the lower degree bounds, the second
consists of the upper degree bounds. The formats are the same as for the
graph definition.

If you want to solve a geometrical problem, you must set the \verb/metrics/ in
the input file to a value other than zero (see Section \ref{slb_length} for the
details).


\subsection{Network Flow Problems}
The program \verb/optflow/ is the GOBLIN solver for all kinds of network flow
problems. The input graph must be a directed graph, either sparse or complete.

There are two ways to use this solver: One may use the \verb/-div/ option
and specify a source $s$ and a target node $t$. The solver will try to find a
pseudo-flow such that all divergences are zero, except for $s$ and $t$. The
divergence of $s$ is maximized, and the divergence of $t$ is minimized
simultaneously. This solver requires that
\begin{itemize}
\item all lower arc capacities are zero,
\item all node demands are zero, except for the nodes $s$ and $t$,
\item all arc length labels are non-negative.
\end{itemize}
For example,
\begin{verbatim}
    optflow -div 0 7 samples/maxflow
\end{verbatim}
would return the $(0,7)$-flow depicted in Figure \ref{flb_maxflow}, and a
minimum $(0,7)$-cut likewise.

If no source node and no target node are specified, the solver will determine
a pseudo-flow such that all divergences match the node demands, called a
$b$-flow. If the \verb/-w/ option is used, the solver returns a $b$-flow with
minimum costs.  This solver requires that
\begin{itemize}
\item all lower capacity bounds are non-negative,
\item the node demands sum up to zero.
\end{itemize}
If the maximum value of an $st$-flow is known a priori, one can assign
the demands of $s$ and $t$ accordingly such that the second solver applies.
For example,
\begin{verbatim}
    optflow samples/maxflow
\end{verbatim}
determines a maximum $(0,7)$-flow due to the node demands specified in the file.


\subsection{Minimum Spanning Tree Problems}
The program \verb/mintree/ is the GOBLIN solver for minimum spanning tree and
$1$-tree problems. The input graph must be a graph or a digraph object, either
sparse or complete.

One may specify a root node $r$ by the option \verb/-r/. In that case, the
predecessors will form a rooted tree or, for $1$-trees, a directed cycle
through $r$ plus several node disjoint arborescences with their root nodes on
the cycle.

If the input graph is undirected and no root node is specified, a subgraph is
returned which consists of the tree arcs. The $1$-tree solver is enabled by
the parameter \verb/-1/. For example,
\begin{verbatim}
    mintree -r 9 -1 samples/mintree1
\end{verbatim}
would return the $1$-tree depicted in Figure \ref{flb_mintree2}.

\bigskip
\begin{figurehere}
\begin{center}
\epsfxsize=8cm
\epsfbox{mintree1.eps}
\vspace{0.5cm}
\caption{\label{flb_mintree2}A Minimum 1-Cycle Tree}
\end{center}
\end{figurehere}


\subsection{Shortest Path Problems}
The program \verb/gsearch/ is the GOBLIN solver for shortest path problems.
The input graph must be a graph or a digraph object, either sparse or complete.

One has to specify a root node $s$ by using the \verb/-s/ option. The output
are the predecessor labels which determine a shortest path tree rooted at $s$.
If the complete output form is used, the distance labels are also returned.

One may optionally specify a target node by using the \verb/-t/ option. In that
case, the Dijkstra label setting method may halt once the target has been
reached.

Note that all shortest path algorithms require that no negative length cycles
exist, and some methods that the length labels are even non-negative. If the
input graph and the method configured are incompatible, this will be reported
in the log file. For example,
\begin{verbatim}
    gsearch -s 0 samples/gsearch1
\end{verbatim}
would return the shortest path tree depicted in Figure \ref{flb_gsearch}.


\subsection{Chinese Postman Problems}
The program \verb/postman/ is the solver for Chinese postamn problems. The input
file must denote a {\it sparse} graph object, either directed or undirected. No
mixed or bipartite graphs are allowed. The output is an Eulerian supergraph
with minimum costs. For example,
\begin{verbatim}
    postman samples/postmanBefore
\end{verbatim}
would return the graph depicted in Figure \ref{flb_postman}.


\subsection{Other Solvers}
Table \ref{tlb_exe} lists some more problem solvers some of which are
experimental. For this reason we omit a documentation of these programs, but
refer to the source files of the main routine which easily exhibit how
the solvers apply.



\markright{LINEAR PROGRAMMING}
\section{Linear Programming}
The last argument passed to \verb/lpsolve/ is the LP instance name, say
\verb/xyz/. The solver expects an input file \verb/xyz.mps/ which contains
a linear program in CPLEX MPS format. Do not specify the extension \verb/.mps/
explicitly!

The optimal basis is written to a file named \verb/xyz.bas/, and the logging
information is written to \verb/xyz.log/. If the option \verb/-b/ is given,
the start basis is read from \verb/xyz.bas/ and overwritten with the final
basis. If \verb/-f/ is specified, the computation stops with a suboptimal but
primal or dual feasible basis depending on which method is configured in
\verb/methLP/. The option \verb/-silent/ suppresses the writing of a log file.



\markright{RANDOM INSTANCE GENERATORS}
\section{Random Instance Generators}
These tools can be used to generate random graph objects.
The last argument passed to an instance generator is the output file name, say
\verb/xyz/. In any case, the solver writes a file \verb/xyz.gob/, but never a
log file. All tools work in a very similar way, and Table \ref{tlb_genopt}
describes the command line options. By default, no random arc labels and no
parallel arcs are generated.
\begin{tablehere}
\begin{center}
\begin{tabular}{|l|l|}
\hline
Option              & Description \\
\hline
\verb/-n/           & Number of nodes \\
\hline
\verb/-m/           & Number of arcs, only for sparse objects \\
\hline
\verb/-dns/         & Complete graph \\
\hline
\verb/-euler/        & Generate Eulerian graph \\
\hline
\verb/-regular/      & Generate regular graph \\
\hline
\end{tabular}
\end{center}
\caption{\label{tlb_genopt}Instance Generator Options}
\end{tablehere}


\subsection{Random Digraphs}
The tool \verb/rgraph/ generates directed graphs. The option \verb/-euler/ can be used
to obtain Eulerian digraphs. For example,
\begin{verbatim}
    rdigraph -n 5 -m 6 -randUCap 1 -randLCap 1 example1
\end{verbatim}
would generate a flow network with 5 nodes, 6 arcs and random upper and lower
capacity bounds, and
\begin{verbatim}
    rdigraph -n 5 -m 22 -euler -randParallels 1 example2
\end{verbatim}
would generate an Eulerian digraph with 5 nodes and 22 arcs. Note that the
\verb/-randParallels 1/ option cannot be omitted here since a simple digraph
on 5 nodes may only consist of 20 arcs.



\subsection{Random Bigraphs}
The tool \verb/rbigraph/ generates bipartite graphs. The option \verb/-regular/ can be used
to obtain regular bigraphs. In that case, the \verb/-n/ and the \verb/-m/
option are immaterial. Otherwise the size of both partitions is passed by the
\verb/-n/ option. For example,
\begin{verbatim}
    rbigraph -n 3 4 -m 5 -randLength 1 example3
\end{verbatim}
would generate a bigraph with 5 arcs, 3 outer nodes, 4 inner nodes and random
length labels. On the other hand,
\begin{verbatim}
    rbigraph -regular 3 2 example4
\end{verbatim}
would generate a $2$-regular bigraph with 6 arcs, 3 outer nodes and 3 inner
nodes. That is, the \verb/-regular/ option replaces or overrides the
\verb/-n/ and the \verb/-m/ option.


\subsection{Random Graphs}
The tool \verb/rgraph/ generates undirected non-bipartite graphs. There are two additional
options \verb/-euler/ and \verb/-regular/ to obtain Eulerian and regular graphs
respectively. For example,
\begin{verbatim}
    rgraph -n 5 -m 6 example5
\end{verbatim}
would generate a sparse graph with 5 nodes and 6 edges, whereas
\begin{verbatim}
    rgraph -n 5 -randGeometry 1 -dns -seed 77 example6
\end{verbatim}
would generate a complete graph with 5 nodes and 10 and a random embedding into
plane. The random generator is initialized with a special seed.


\markright{GRAPHICAL DISPLAY}
\section{Graphical Display}
Every problem solver has the capability to produce graphical information
if the tracing module is configured that way. But sometimes it is more
convenient to display a graph directly. This is achieved by the program
\verb/gobshow/. Note that the file extension must be specified. For example,
\begin{verbatim}
    gobshow -arcLabels 4 samples/optasgn1.gob
\end{verbatim}
would show the graph defined in the file \verb/optasgn1.gob/, especially its
length labels. This program should be redundant in view of the existence of the
GOBLET graph browser. Since the compilation of the GOSH interpreter is the most
difficult part of the GOBLIN installation, it may be useful in case of trouble.



\end{multicols}
\part{Appendix}
\begin{multicols}{2}

\markboth{APPENDIX}{COMPUTATIONAL RESULTS}
\chapter{Computational Results}
\thispagestyle{fancy}
\label{clb_results}

\markright{SYMMETRIC TSP}
\section{Symmetric TSP}
All computations were performed with the GOBLET graph browser 2.7.1 on an
Athlon XP 1800 PC with 256 MB RAM and SuSE Linux 7.3. and with gcc optimization
level -O5. The test problems are all from the TSPLIB:
\begin{verbatim}
    http://www.iwr.uni-heidelberg.de/groups
                    /comopt/software/TSPLIB95/
\end{verbatim}
The following methods have been tested here:
\begin{itemize}
\item SGO: The fast version of the 1-tree subgradient optimization
    with local search enabled. This method has produced the most heuristic tours.
\item SGO2: Exhaustive 1-tree subgradient optimization with local
    search enabled.
\item CAND: Branch and bound on a candidate graph with
    local search enabled and with \verb/methCandidates=0/.
\item CND2: As before but with \verb/methRelaxTSP2=2/.
\item EXH: Branch and bound on the entire graph with local search
    disabled.
\item EXH2: As before but with \verb/methRelaxTSP2=2/.
\end{itemize}
The initial tours were obtained from random tours with local search enabled.
Note that the candidate graph generation also includes such random tours. The
performance of the available construction heuristics is not tested.

With a few exceptions (marked by an asterisk), the branch and bound has not
been restricted in terms of running times or memory usage. Practically, one
would interrupt the candidate search after a certain number of branching steps.


\vfill
\begin{center}
\small
\begin{tabular}{|lrlrrrr|}
\hline
{\bf Instance} & {\bf Opt} & {\bf Method} & {\bf Root} & {\bf Found Gap} & {\bf Time} & {\bf Branch} \\
\hline
\hline
burma14      &     3323 &  SGO &  13 &           3323  &     0s & \\
ulysses16    &     6859 &  SGO &  14 &           6859  &     1s & \\
gr17         &     2085 &  SGO &   0 &           2085  &     1s & \\
gr21         &     2707 &  SGO &   0 &           2707  &     0s & \\
ulysses22    &     7013 &  SGO &  14 &           7013  &     1s & \\
gr24         &     1272 &  SGO &   0 &           1272  &     1s & \\
fri26        &      937 &  SGO &   0 &            937  &     1s & \\
bayg29       &     1610 &  EXH &   4 &           1610  &     2s &       8 \\
bays29       &     2020 &  EXH &   4 &           2020  &     2s &      12 \\
dantzig42    &      699 &  SGO &  27 & [   697,   699] &     3s & \\
dantzig42    &      699 &  EXH &  27 &            699  &     3s &       8 \\
swiss42      &     1273 &  SGO &   4 & [  1272,  1273] &     3s & \\
swiss42      &     1273 &  EXH &   4 &           1273  &     3s &       8 \\
hk48         &    11461 &  SGO &  40 & [ 11445, 11461] &     4s & \\
hk48         &    11461 &  EXH &  40 &          11461  &     1s &      12 \\
gr48         &     5046 &  SGO &  40 & [  4959,  5055] &     4s & \\
gr48         &     5046 & CAND &  40 & [  4959,  5046] &     8s &    1614 \\
gr48         &     5046 &  EXH &  37 &           5046  &   201s &     816 \\
eil51        &      426 &  SGO &  21 & [   423,   432] &     3s & \\
eil51        &      426 & CAND &  21 & [   423,   426] &     7s &    1830 \\
eil51        &      426 &  EXH &  21 &            426  &    32s &     228 \\
berlin52     &     7542 &  SGO &  42 &           7542  &     3s & \\
\hline
\end{tabular}
\end{center}


\vfill
\begin{center}
\small
\begin{tabular}{|lrlrrrr|}
\hline
{\bf Instance} & {\bf Opt} & {\bf Method} & {\bf Root} & {\bf Found Gap} & {\bf Time} & {\bf Branch} \\
\hline
\hline
brazil58     &    25395 &  SGO &  30 & [ 25355, 25395] &     8s & \\
brazil58     &    25395 &  EXH &  30 &          25395  &    17s &      56 \\
st70         &      675 &  SGO &  16 & [   671,   684] &     6s & \\
st70         &      675 & CAND &  16 & [   671,   675] &    11s &    2844 \\
st70         &      675 &  EXH &  16 &            675  &    18s &      64 \\
eil76        &      538 &  SGO &   6 & [   537,   543] &     7s & \\
eil76        &      538 & CAND &   6 & [   537,   538] &    19s &    3324 \\
eil76        &      538 &  EXH &   6 &            538  &     2s &       8 \\
pr76         &   108159 &  SGO &  39 & [105120,108879] &    12s & \\
pr76         &   108159 & CAND &  39 & [105120,108159] &   345s &    6158 \\
pr76         &   108159 & EXH* &  39 & [106509,108159] &  1516s &    1000 \\
gr96         &    55209 &  SGO &  79 & [ 54570, 55462] &    34s & \\
gr96         &    55209 & CAND &  79 & [ 54570, 55209] &    45s &    4664 \\
gr96         &    55209 &  EXH &  79 &           55209 &   715s &     760 \\
rat99        &     1211 &  SGO &  63 & [  1206,  1220] &    14s & \\
rat99        &     1211 & CAND &  63 & [  1206,  1211] &    15s &    4544 \\
rat99        &     1211 &  EXH &  63 &           1211  &    36s &      62   \\
rd100        &     7910 &  SGO &  15 & [  7898,  8046] &    17s & \\
rd100        &     7910 & SGO2 &  15 & [  7900,  8046] &    29s & \\
rd100        &     7910 & CAND &  15 & [  7900,  7910] &    16s &    4612 \\
rd100        &     7910 &  EXH &  15 &           7910  &     9s &      18 \\
kroA100      &    21282 &  SGO &  86 & [ 20937, 21583] &    20s & \\
kroA100      &    21282 & CAND &  86 & [ 20937, 21282] &    61s &    4946 \\
kroA100      &    21282 &  EXH &  86 &           21282 &  5016s &    5180 \\
kroB100      &    22141 &  SGO &  53 & [ 21834, 23698] &    15s & \\
kroB100      &    22141 & CAND &  53 & [ 21834, 22141] &    51s &    4914 \\
kroB100      &    22141 &  EXH &  53 &           22141 &  1338s &    1274 \\
kroC100      &    20749 &  SGO &  49 & [ 20473, 20812] &    17s & \\
kroC100      &    20749 & CAND &  49 & [ 20473, 20749] &    21s &    4706 \\
kroC100      &    20749 &  EXH &  49 &          20749  &  1422s &    1402 \\
kroD100      &    21294 &  SGO &  45 & [ 21142, 21493] &    18s & \\
kroD100      &    21294 & CAND &  45 & [ 21142, 21294] &    19s &    4674 \\
kroD100      &    21294 &  EXH &  45 &          21294  &   148s &     156 \\
kroE100      &    22068 &  SGO &  71 & [ 21800, 22141] &    36s & \\
kroE100      &    22068 & CAND &  71 & [ 21800, 22068] &    61s &    5100 \\
kroE100      &    22068 &  EXH &  71 &           22068 &  1195s &    1142 \\
\hline
\end{tabular}
\end{center}

\vfill
\begin{center}
\small
\begin{tabular}{|lrlrrrr|}
\hline
{\bf Instance} & {\bf Opt} & {\bf Method} & {\bf Root} & {\bf Found Gap} & {\bf Time} & {\bf Branch} \\
\hline
\hline
eil101       &      629 &  SGO &  41 & [   628,   647] &    13s & \\
eil101       &      629 & CAND &  51 & [   628,   629] &    43s &    5112 \\
eil101       &      629 &  EXH &  51 &            629  &    98s &     196 \\
lin105       &    14379 &  SGO & 103 & [ 14371, 14379] &    29s & \\
lin105       &    14379 &  EXH & 103 &          14379  &     5s &       6 \\
pr107        &    44303 & SGO2 &  86 & [ 44116, 44744] &   144s &         \\
pr107        &    44303 & CND2 &  86 & [ 44116, 44438] &    92s &    5210 \\
pr107        &    44303 & EXH2 &  86 &          44303  &    25s &       8 \\
gr120        &     6942 &  SGO &  17 & [  6912,  7082] &    21s & \\
gr120        &     6942 & CAND &  17 & [  6912,  6942] &   104s &    6614 \\
gr120        &     6942 &  EXH &  17 &            6942 &   611s &     446 \\
pr124        &    59030 &  SGO &  59 & [ 58068, 59076] &    26s & \\
pr124        &    59030 & CAND &  59 & [ 58068, 59030] &    12s &    1534 \\
pr124        &    59030 &  EXH &  59 &           59030 &  1489s &     786 \\
bier127      &   118282 &  SGO &  93 & [117431,118580] &    39s & \\
bier127      &   118282 & CAND &  93 & [117431,118282] &    28s &    6500 \\
bier127      &   118282 &  EXH &  93 &          118282 &   112s &      66 \\
ch130        &     6110 &  SGO &  81 & [  6075,  6216] &    29s & \\
ch130        &     6110 & SGO2 &  81 & [  6076,  6216] &    45s & \\
ch130        &     6110 & CAND &  81 & [  6076,  6110] &   109s &    7338 \\
ch130        &     6110 &  EXH &  81 &           6110  &  4428s &    3052 \\
pr136        &    96772 &  SGO &  34 & [ 95720, 98650] &    40s & \\
pr136        &    96772 & SGO2 &  34 & [ 95935, 98650] &   177s & \\
pr136        &    96772 & CAND &  34 & [ 95935, 96772] &  2757s &   23861 \\
gr137        &    69853 &  SGO &  87 & [ 69120, 70240] &    55s & \\
gr137        &    69853 & CAND &  87 & [ 69120, 69853] &    78s &    7462 \\
gr137        &    69853 &  EXH &  87 &           69853 &  2894s &    1508 \\
pr144        &    58537 &  SGO &  29 & [ 58190, 59113] &    25s & \\
pr144        &    58537 & CAND &  29 & [ 58190, 58537] &    19s &    3670 \\
pr144        &    58537 &  EXH &  29 &           58537 &   818s &     324 \\
ch150        &     6528 &  SGO &  39 & [  6490,  6610] &    40s & \\
ch150        &     6528 & CAND &  39 & [  6490,  6528] &   422s &   10930 \\
ch150        &     6528 &  EXH &  39 &            6528 &  6318s &    3470 \\
kroA150      &    26524 &  SGO & 112 & [ 26265, 26725] &    49s & \\
kroA150      &    26524 & SGO2 & 112 & [ 26299, 26725] &    92s & \\
kroA150      &    26524 & CAND & 112 & [ 26299, 26525] &   264s &    9428 \\
kroA150      &    26524 &  EXH & 112 &          26524  & 22472s &     \\
\hline
\end{tabular}
\end{center}

\vfill
\begin{center}
\small
\begin{tabular}{|lrlrrrr|}
\hline
{\bf Instance} & {\bf Opt} & {\bf Method} & {\bf Root} & {\bf Found Gap} & {\bf Time} & {\bf Branch} \\
\hline
\hline
kroB150      &    26130 & SGO2 &  68 & [ 25733, 26678] &   164s & \\
kroB150      &    26130 & CAND &  68 & [ 25733, 26130] &   905s &   13410 \\
pr152        &    73682 & SGO2 & 120 & [ 73209, 74279] &   223s & \\
pr152        &    73682 & CAND & 120 & [ 73209, 73682] &    52s &    8356 \\
pr152        &    73682 &  EXH & 120 &           73682 & 18547s &    1136 \\
u159         &    42080 &  SGO &  86 & [ 41925, 42168] &    56s & \\
u159         &    42080 & CAND &  86 & [ 41925, 42080] &   132s &   9352 \\
u159         &    42080 &  EXH &  86 &           42080 &   430s &    204 \\
si175        &    21407 & SGO2 &   1 & [ 21375, 21426] &   278s & \\
brg180       &     1950 & SGO2 & 111 & [  1950,  2020] &   513s & \\
brg180       &     1950 & CND2 & 111 &            1950 &   248s &   10478 \\
rat195       &     2323 & SGO2 &  43 & [  2300,  2379] &   297s & \\
rat195       &     2323 & CAND &  43 & [  2300,  2323] &  2145s &   23784 \\
d198         &    15780 & SGO2 & 167 & [ 15712, 15825] &   450s & \\
d198         &    15780 & CAND & 167 & [ 15712, 15780] &   802s &   15196 \\
kroA200      &    29368 &  SGO &  40 & [ 29065, 30043] &   104s & \\
kroA200      &    29368 & CAND &  40 & [ 29065, 29368] & 17015s &   91520 \\
kroB200      &    29437 &  SGO &  57 & [ 29165, 30364] &    87s & \\
\hline
\end{tabular}
\end{center}


\markright{ASYMMETRIC TSP}
\section{Asymmetric TSP}
All computations were performed with the GOBLET graph browser 2.7.2 on an
Athlon XP 1800 PC with 256 MB RAM and SuSE Linux 10.0 and without gcc optimization.
The test problems are all from the TSPLIB:
\begin{verbatim}
    http://www.iwr.uni-heidelberg.de/groups
                    /comopt/software/TSPLIB95/
\end{verbatim}
The following methods have been tested here:
\begin{itemize}
\item SGO: The fast version of the 1-tree subgradient optimization
    with local search enabled. This method has produced the most heuristic
    tours.
\item SGO2: Exhaustive 1-tree subgradient optimization with local
    search enabled.
\item CAND: Branch and bound on a candidate graph with
    local search enabled and with \verb/methCandidates=0/.
\item CAND: Branch and bound on the entire graph with local search
    disabled. For difficult problems, the number of branch nodes has been
    restricted to 1000 so that no optimality proof is obtained but the lower
    bound is improved.
\end{itemize}


\bigskip
\begin{center}
\small
\begin{tabular}{|lrlrrrr|}
\hline
{\bf Instance} & {\bf Opt} & {\bf Method} & {\bf Root} & {\bf Found Gap} & {\bf Time} & {\bf Branch} \\
\hline
\hline
br17      &     39 &  SGO &   7 &            39  &     1s & \\
ftv33     &   1286 &  SGO &  11 &          1286  &     0s & \\
ftv35     &   1473 &  SGO &  11 & [ 1456,  1484] &     4s & \\
ftv35     &   1473 &  EXH &  11 &          1473  &    11s &    23 \\
ftv38     &   1530 &  SGO &   7 & [ 1512,  1541] &     2s & \\
ftv38     &   1530 & CAND &   7 & [ 1514,  1530] &     5s &   284 \\
ftv38     &   1530 &  EXH &   7 &          1530  &    30s &    56 \\
p43       &   5620 & SGO2 &  40 & [ 5611,  5629] &    29s & \\
p43       &   5620 & CAND &  40 & [ 5611,  5620] &  1629s &  5000 \\
p43       &   5620 &  EXH &  40 & [ 5614,  5620] &  1133s &   100 \\
ftv44     &   1613 &  SGO &  17 & [ 1581,  1708] &     3s & \\
ftv44     &   1613 & CAND &  17 & [ 1583,  1634] &    35s &   596 \\
ftv44     &   1613 &  EXH &  17 &          1613  &   175s &   164 \\
ftv47     &   1776 &  SGO &  17 & [ 1748,  1932] &     4s & \\
ftv47     &   1776 & CAND &  17 & [ 1748,  1776] &    27s &   542 \\
ftv47     &   1776 &  EXH &  17 &          1776  &   156s &   190 \\
ry48p     &  14422 & SGO2 &  40 & [14290, 14429] &    21s & \\
ry48p     &  14422 &  EXH &  40 &         14422  &    75s &    46 \\
ft53      &   6905 & SGO2 &  52 &          6905  &    10s & \\
ftv55     &   1608 & SGO2 &  30 & [ 1584,  1758] &     9s & \\
ftv55     &   1608 & CAND &  30 & [ 1584,  1608] &    31s &   612 \\
ftv55     &   1608 &  EXH &  30 &          1608  &   883s &   882 \\
ftv64     &   1839 & SGO2 &  20 & [ 1808,  1958] &    26s & \\
ftv64     &   1839 & CAND &  20 & [ 1808,  1839] &    30s &  738 \\
ftv64     &   1839 &  EXH &  20 &          1839  &  5816s & 3996 \\
\hline
\end{tabular}
\end{center}

\vfill
\begin{center}
\small
\begin{tabular}{|lrlrrrr|}
\hline
{\bf Instance} & {\bf Opt} & {\bf Method} & {\bf Root} & {\bf Found Gap} & {\bf Time} & {\bf Branch} \\
\hline
\hline
ft70      &  38673 &  SGO &  47 & [38632, 38793] &    22s & \\
ft70      &  38673 & CAND &  47 & [38632, 38694] &    14s &  708 \\
ft70      &  38673 &  EXH &  47 &         38673  &    43s &   16 \\
ftv70     &   1950 &  SGO &  70 & [ 1907,  2176] &     7s & \\
ftv70     &   1950 & CAND &  70 & [ 1907,  1973] &  2181s & 12804 \\
ftv70     &   1950 & CAND &  70 & [ 1908,  1950] &   335s &  2510 \\
ftv70     &   1950 &  EXH &  70 & [ 1928,  1950] &  2589s &  1000 \\
kro124p   &  36230 &  SGO &  90 & [35974, 39278] &    27s & \\
kro124p   &  36230 & SGO2 &  90 & [35998, 39278] &    64s & \\
kro124p   &  36230 & CAND &  90 & [35999, 36230] &   207s &  1496 \\
kro124p   &  36230 &  EXH &  90 &         36230  &   427s &    52 \\
ftv170    &   2755 &  SGO & 123 & [ 2682,  2932] &    40s & \\
ftv170    &   2755 & SGO2 & 123 & [ 2707,  2932] &   182s & \\
ftv170    &   2755 & CAND & 123 & [ 2707,  2780] &  4622s & 10000 \\
ftv170    &   2755 & CAND & 123 & [ 2707,  2772] &  4516s & 10000 \\
ftv170    &   2755 & CAND & 123 & [ 2707,  2755] &  6031s & 10000 \\
\hline
\end{tabular}
\end{center}



\markright{MIN-COST FLOW}
\section{Min-Cost Flow}
All computations were performed with the GOBLET graph browser 2.5.1 on an
Athlon XP 1800 PC with 256 MB RAM and SuSE Linux 7.3. The test sets are
NETGEN problems taken from
\begin{verbatim}
    http://elib.zib.de/pub/Packages/mp-testdata
                            /mincost/netg/index.html
\end{verbatim}
The tested methods are the cost scaling algorithm ({\bf CS}, \verb/methMCF=MCF_BF_COST/)
and the network simplex method ({\bf NW}, \verb/methMinCCirc=MCF_BF_SIMPLEX/).
The columns for the respective solution times with \verb/gcc/ optimization
level \verb/-O5/ and the pragmas \verb/_LOGGING_/ and \verb/_FAILSAVE_/ unset.


\bigskip
\begin{center}
\small
\begin{tabular}{|lrrrrrrr|}
\hline
{\bf Instance} & {\bf Nds} & {\bf Arcs} & {\bf Cap} & {\bf Len} & {\bf Objective} & {\bf CS} & {\bf NW} \\
\hline
\hline
\verb/big5/    &    5000 &   80101 &    10000 &     1000 &       15817090 &      198s &    9s \\
\verb/big6/    &    5000 &   60092 &    10000 &     1000 &       15864843 &      165s &    7s \\
\verb/big7/    &    5000 &   40105 &    10000 &     1000 &       13970599 &      138s &    6s \\
\verb/cap1/    &    1000 &   10000 &   500000 &    10000 &     2572055650 &        7s &    1s \\
\verb/cap2/    &    1000 &   30000 &  1199995 &    10000 &      868553404 &       14s &    1s \\
\verb/cap3/    &    1000 &   40000 &  1199995 &    10000 &      835752895 &       23s &    1s \\
\verb/cap4/    &    5000 &   30000 &   600000 &    10000 &     6572052044 &      107s &    1s \\
\verb/cap5/    &    5000 &   40000 &   600000 &    10000 &     4596714758 &      130s &    2s \\
\verb/cap6/    &    5000 &   49999 &   600000 &   120756 &     3905503120 &      130s &    2s \\
\verb/cap7/    &    5000 &   60000 &   600000 &    10000 &     3514982153 &      142s &    2s \\
\verb/cap8/    &   10000 &   40000 &  1000000 &    10000 &    13836268653 &      473s &    4s \\
\verb/cap9/    &   10000 &   50000 &  1000000 &    10000 &    12273727410 &      389s &    5s \\
\verb/transp1/ &     800 &   10028 &   200000 &     9997 &      258178684 &        9s &    0s \\
\verb/transp2/ &     800 &   20000 &   200000 &    10000 &      147794030 &       16s &    1s \\
\verb/transp3/ &     800 &   30000 &   200000 &    10000 &       93015638 &       24s &    1s \\
\verb/transp4/ &     800 &   40002 &   200000 &    10000 &       75304321 &       37s &    1s \\
\verb/transp5/ &    1000 &   20049 &   200000 &    10000 &      176263777 &       22s &    1s \\
\verb/transp6/ &     800 &   40002 &   200000 &    10000 &      124416104 &       34s &    1s \\
\verb/transp7/ &    1000 &   40025 &   200000 &    10000 &       96121936 &       34s &    2s \\
\verb/transp8/ &    1000 &   50055 &   200000 &    10000 &       92366438 &       51s &    2s \\
\verb/transp9/ &     400 &   10000 &   200000 &    10000 &      158058350 &        6s &    0s \\
\verb/transp10/&     400 &   19969 &   200000 &    10000 &       94008769 &       13s &    1s \\
\verb/transp11/&     600 &   10020 &   200000 &     9997 &      220335437 &        9s &    0s \\
\verb/transp12/&     600 &   20000 &   200000 &    10000 &      126443694 &       15s &    0s \\
\verb/transp13/&     600 &   30000 &   200000 &    10000 &      110331273 &       25s &    1s \\
\verb/transp14/&     600 &   40000 &   200000 &    10000 &       85534936 &       28s &    1s \\
\hline
\end{tabular}
\end{center}

\vfill
\begin{center}
\small
\begin{tabular}{|lrrrrrrr|}
\hline
{\bf Instance} & {\bf Nds} & {\bf Arcs} & {\bf Cap} & {\bf Len} & {\bf Objective} & {\bf CS} & {\bf NW} \\
\hline
\hline
\verb/stndrd1/ &     200 &    1308 &   100000 &     9998 &      196587626 &        1s &    0s \\
\verb/stndrd2/ &     200 &    1511 &   100000 &     9998 &      194072029 &        1s &    0s \\
\verb/stndrd3/ &     200 &    2000 &   100000 &     9998 &      159442947 &        2s &    1s \\
\verb/stndrd4/ &     200 &    2200 &   100000 &     9998 &      138936551 &        2s &    1s \\
\verb/stndrd5/ &     200 &    2900 &   100000 &     9997 &      102950805 &        1s &    1s \\
\verb/stndrd6/ &     300 &    3174 &   150000 &     9996 &      191968577 &        2s &    0s \\
\verb/stndrd7/ &     300 &    4519 &   150000 &     9998 &      172742047 &        3s &    0s \\
\verb/stndrd8/ &     300 &    5168 &   150000 &     9997 &      164468452 &        4s &    1s \\
\verb/stndrd9/ &     300 &    6075 &   150000 &     9996 &      144994180 &        4s &    0s \\
\verb/stndrd10/&     300 &    6320 &   150000 &     9996 &      148675665 &        4s &    0s \\
\verb/stndrd16/&     400 &    1306 &   400000 &    10000 &     6815524469 &        1s &    0s \\
\verb/stndrd17/&     400 &    2443 &   400000 &    10000 &     2646770386 &        1s &    1s \\
\verb/stndrd18/&     400 &    1306 &   400000 &    10000 &     6663684919 &        1s &    0s \\
\verb/stndrd19/&     400 &    2443 &   400000 &    10000 &     2618979806 &        1s &    0s \\
\verb/stndrd20/&     400 &    1400 &   400000 &    10000 &     6708097873 &        1s &    0s \\
\verb/stndrd21/&     400 &    2836 &   400000 &    10000 &     2631027973 &        2s &    1s \\
\verb/stndrd22/&     400 &    1416 &   400000 &    10000 &     6621515104 &        2s &    0s \\
\verb/stndrd23/&     400 &    2836 &   400000 &    10000 &     2630071408 &        1s &    1s \\
\verb/stndrd24/&     400 &    1382 &   400000 &    10000 &     6829799687 &        2s &    0s \\
\verb/stndrd25/&     400 &    2676 &   400000 &    10000 &     6396423129 &        2s &    1s \\
\verb/stndrd26/&     400 &    1382 &   400000 &    10000 &     5297702923 &        1s &    0s \\
\verb/stndrd27/&     400 &    2676 &   400000 &    10000 &     4863992745 &        1s &    0s \\
\verb/stndrd28/&    1000 &    2900 &  1000000 &     9998 &    11599233408 &        6s &    0s \\
\verb/stndrd29/&    1000 &    3400 &  1000000 &     9997 &    11700773092 &        6s &    0s \\
\verb/stndrd30/&    1000 &    4400 &  1000000 &     9997 &     8782721260 &        6s &    0s \\
\verb/stndrd31/&    1000 &    4800 &  1000000 &     9998 &     8577913734 &        6s &    1s \\
\verb/stndrd32/&    1500 &    4342 &  1500000 &     9997 &    17996365110 &       13s &    0s \\
\verb/stndrd33/&    1500 &    4385 &  1500000 &     9995 &    18424893900 &       13s &    1s \\
\verb/stndrd34/&    1500 &    5107 &  1500000 &     9998 &    14596094907 &       11s &    0s \\
\verb/stndrd35/&    1500 &    5730 &  1500000 &     9997 &    14350903861 &       13s &    1s \\
\verb/stndrd36/&    8000 &   15000 &  4000000 &    10000 &    87957673940 &      329s &    2s \\
\verb/stndrd37/&    5000 &   23000 &  4000000 &    10000 &    35607266430 &      149s &    2s \\
\verb/stndrd38/&    3000 &   35000 &  2000000 &    10000 &     7265734372 &       84s &    2s \\
\verb/stndrd39/&    5000 &   15000 &  4000000 &    10000 &    48660418428 &      145s &    2s \\
\verb/stndrd40/&    3000 &   23000 &  2000000 &    10000 &    11068572024 &       62s &    2s \\
\verb/stndrd45/&    4000 &   20000 &     5000 &   -50000 & -1864582590629 &       16s &   15s \\
\verb/stndrd50/&     350 &    4500 &   300000 &      100 &        4024557 &        2s &    0s \\
\hline
\end{tabular}
\end{center}



\markright{NON-WEIGHTED MATCHING}
\section{Non-Weighted Matching}
All computations were performed with the GOBLET graph browser 2.3 on a Pentium
III/850 MHz notebook with 256 MB RAM and SuSE Linux 7.3. The test problems
\verb/r10000/ to \verb/r30000/ are random graphs while \verb/reg3/ is a
$3$-regular random graph and \verb/tiling1/, \verb/tiling2/ are tilings with
different base graphs. The following methods have been tested here:
\begin{itemize}
\item ''Phase'': The phase ordered augmentation algorithm. We report the
    running times and the number of phases which occur.
\item ''Cancel'': The cycle canceling method. We report the running times and
    the number of odd cycles after the call of \verb/CancelEven/.
\end{itemize}
Note that the respective numbers of phases and odd cycles are much less than the
worst-case bounds may suggest.

\bigskip
\begin{center}
\small
\begin{tabular}{|lrrrrrr|}
\hline
{\bf Instance} & {\bf Nodes} & {\bf Arcs} & {\bf Type} & {\bf Phase} & {\bf Cancel} & {\bf Objective} \\
\hline
\hline
\verb/r10000/  & 10000 & 10000 & 1-factor & 2s (13)  & 1s (0)  &  3932 \\
               &       &       & 2-factor & 1s (7)   & 1s (0)  &  6815 \\
\verb/r15000/  & 10000 & 15000 & 1-factor & 4s (24)  & 4s (0)  &  4634 \\
               &       &       & 2-factor & 4s (22)  & 4s (0)  &  8488 \\
\verb/r20000/  & 10000 & 20000 & 1-factor & 2s (15)  & 4s (6)  &  4896 \\
               &       &       & 2-factor & 2s (15)  & 4s (6)  &  9407 \\
\verb/r25000/  & 10000 & 25000 & 1-factor & 1s (12)  & 4s (8)  &  4963 \\
               &       &       & 2-factor & 2s (11)  & 4s (6)  &  9755 \\
\verb/r30000/  & 10000 & 30000 & 1-factor & 1s (9)   & 4s (2)  &  4989 \\
               &       &       & 2-factor & 2s (9)   & 4s (2)  &  9903 \\
\verb/reg3/    & 10000 & 15000 & 1-factor & 1s (10)  & 2s (0)  &  5000 \\
               &       &       & 2-factor & 1s (11)  & 2s (2)  & 10000 \\
\verb/tiling1/ & 10166 & 30361 & 1-factor & 2s (3)   & 1s (2144) & 5083 \\
               &       &       & 2-factor & 1s (5)   & 2s (34) & 10166 \\
\verb/tiling2/ &  9941 & 29540 & 1-factor & 1s (2)   & 2s (70) &  4970 \\
               &       &       & 2-factor & 2s (3)   & 3s (132) & 9941 \\
\hline
{\bf Average}  & 10013 & 21863 & 1-factor & 1.8s (11)   & 4.6s (279) &  \\
               &       &       & 2-factor & 1.8s (10.4) & 3s  (23) &  \\
\hline
\end{tabular}
\end{center}



\markright{WEIGHTED MATCHING}
\section{Weighted Matching}
All computations were performed with the GOBLET graph browser 2.2 on a Pentium
III/850 MHz notebook with 256 MB RAM and SuSE Linux 7.3. The test problems are
from TSPLIB and defined on complete graphs. The instances \verb/pr1002/ and
\verb/u1060/ are geometric while \verb/si1032/ is defined by a matrix. The
problem \verb/rnd1000/ is a matrix problem with random length labels equally
distributed in the interval $[0,49999]$.

The following methods have been tested here:
\begin{itemize}
\item ''heuristic'': The problem is solved on a sparse subgraph only where
    \verb/methCandidates=10/.
\item ''candidates'': The fractional matching problem is solved on a candidate
    graph with \verb/methCandidates=10/ converted into a optimal fractional
    matching on the entire graph, and then converted into a optimal integral
    solution.
\item ''exhaustive'': The matching solver is applied to the complete graph
    directly, that is with \verb/methCandidates=-1/.
\end{itemize}
The results indicate that the candidate graph is constructed slowly, but provides
excellent solutions. The price\&repair strategy for the fractional matching problem
cannot reach the performance of price\&repair methods for the 1-matching problem.
The running times of the price\&repair method strongly depend on the performance
of the primal-dual method since the number of expensive PD-operations does not
decrease via candidate search. Note the significant differences in the running
times for the geometric and the matrix problems.

\bigskip
\begin{center}
\small
\begin{tabular}{|lrrrrrr|}
\hline
{\bf Instance} & {\bf Type} & {\bf Method} & {\bf Objective} & {\bf Time}
& {\bf Dual} & {\bf Expand} \\
\hline
\hline
\verb/pr1002/  &   1-factor & heuristics  & 112630 &   84s & 583 & 189 \\
\verb/pr1002/  &   1-factor & candidates  & 112630 & 1263s & 250 & 120 \\
\verb/pr1002/  &   1-factor & complete    & 112630 & 5224s & 248 & 119 \\
\verb/pr1002/  &   2-factor & heuristics  & 244062 &  104s & 419 &  87 \\
\verb/pr1002/  &   2-factor & candidates  & 244062 & 2029s & 428 & 106 \\
\verb/pr1002/  &   2-factor & complete    & 244062 & 5435s & 428 & 106 \\
\verb/si1032/  &   1-factor & heuristics  &  45448 &   39s &   6 &   0 \\
\verb/si1032/  &   1-factor & candidates  &  45448 &   60s &   6 &   0 \\
\verb/si1032/  &   1-factor & complete    &  45448 & 1019s &   7 &   0 \\
\verb/si1032/  &   2-factor & heuristics  &  91940 &   59s &  65 &  10 \\
\verb/si1032/  &   2-factor & candidates  &  91939 &  562s &  93 &   8 \\
\verb/si1032/  &   2-factor & complete    &  91939 & 2163s &  76 &  10 \\
\verb/u1060/   &   1-factor & heuristics  & 100651 &   98s & 590 & 130 \\
\verb/u1060/   &   1-factor & candidates  & 100356 & 1898s & 519 &  89 \\
\verb/u1060/   &   1-factor & complete    & 100356 & 3461s & 519 &  80 \\
\verb/u1060/   &   2-factor & heuristics  & 210931 &  123s & 409 &  77 \\
\verb/u1060/   &   2-factor & candidates  & 210931 & 1439s & 405 &  94 \\
\verb/u1060/   &   2-factor & complete    & 210931 & 5372s & 410 &  89 \\
\verb/rnd1000/ &   1-factor & heuristics  &  41284 &   56s &   0 &   0 \\
\verb/rnd1000/ &   1-factor & candidates  &  41284 &  937s &  69 &   0 \\
\verb/rnd1000/ &   1-factor & complete    &  41284 & 2628s &  69 &   0 \\
\verb/rnd1000/ &   2-factor & heuristics  & 103401 &   77s &  42 &   4 \\
\verb/rnd1000/ &   2-factor & candidates  & 103282 &  274s &  22 &   0 \\
\verb/rnd1000/ &   2-factor & complete    & 103282 & 2752s &  24 &   0 \\
\hline
\end{tabular}
\end{center}



\markright{CLIQUES AND NODE COLOURING}
\section{Cliques and Node Colouring}
All computations were performed with the GOBLET graph browser 2.1d/2.2a/2.3c on a Pentium
III/850 MHz notebook with 256 MB RAM, SuSE Linux 7.2/7.3 and without any code
optimization. The test sets are from Michael Tricks graph colouring page
\begin{verbatim}
    http://mat.gsia.cmu.edu/COLOR/instances.html
\end{verbatim}
All computation times were restricted to 5 minutes (exceptions are marked with an
asterisk *). Note that node k-colourings and k-clique covers have been computed for
a series of fixed, decreasing k. A successful k-colouring usually takes less than
one second, times for negative results mainly depend on the branch and bound
configuration.

For the series \verb/fpsol*/, \verb/inithx*/ and \verb/le450*/, the k-colour
enumeration scheme requires too much computer memory to obtain the optimal 
colouring. Moreover, the computation times for cliques and clique covers are
dominated by the explicit construction of complementary graphs. Results are
therefore omitted.

\bigskip
\begin{center}
\small
\begin{tabular}{|lrrrrrr|}
\hline
{\bf Instance} & {\bf Nodes} & {\bf Arcs} & {\bf Clique} & {\bf Colour} & {\bf Stable} & {\bf Cover} \\
\hline
\hline
\verb/anna/      &   138 &     586 &         11  &         11  &          80  &          80 \\
\verb/david/     &    87 &     812 &         11  &         11  &          36  &          36 \\
\verb/homer/     &   561 &    3258 &         13  &         13  &         341  &         341 \\
\verb/huck/      &    74 &     602 &         11  &         11  &          27  &          27 \\
\verb/jean/      &    80 &     508 &         10  &         10  &          38  &          38 \\
&&&&&&\\
\verb/DSJC125.1/ &   125 &     736 &          4  &     [ 5, 6] &    [ 32, 48] &    [ 32, 48] \\
\verb/DSJC125.5/ &   125 &    3891 &         10  &     [10,21] &          10  &    [ 10, 20] \\
\verb/DSJC125.9/ &   125 &    6961 &     [32,46] &     [32,46] &           4  &    [  4,  6] \\
&&&&&&\\
\verb/flat300_20/&   300 &   21375 &     [10,40] &     [10,41] &    [ 12, 43] &    [ 12, 44] \\
&&&&&&\\
\verb/fpsol2.i.1/&   496 &   11654 &     [45,65] &     [45,65] &         307  &         307 \\
&&&&&&\\
\verb/games120/  &   120 &    1276 &          9  &          9  &    [ 22, 24] &    [ 22, 24] \\
&&&&&&\\
\verb/le450_5a/  &   450 &    5714 &     [ 5, 8] &     [ 5, 8] &    [ 78,141] &    [ 78,141] \\
&&&&&&\\
\verb/miles250/  &   128 &     774 &          8  &          8  &          44  &         44 \\
\verb/miles500/  &   128 &    2340 &         20  &         20  &          18  &  [ 18, 19] \\
\verb/miles750/  &   128 &    4226 &         31  &         31  &          12  &         12 \\
\verb/miles1000/ &   128 &    6432 &         42  &         42  &           8  &          8 \\
\verb/miles1500/ &   128 &   10396 &         73  &         73  &           5  &          5 \\
\hline
\end{tabular}
\end{center}

\vfill
\begin{center}
\small
\begin{tabular}{|lrrrrrr|}
\hline
{\bf Instance} & {\bf Nodes} & {\bf Arcs} & {\bf Clique} & {\bf Colour} & {\bf Stable} & {\bf Cover} \\
\hline
\hline
\verb/mulsol.i.1/ & 197  &   3925   &       49*   &       49   &        100   &        100 \\
\verb/mulsol.i.2/ & 188  &   3885   &       31    &       31   &         90   &         90 \\
\verb/mulsol.i.3/ & 184  &   3916   &       31    &       31   &         86   &         86 \\
\verb/mulsol.i.4/ & 185  &   3946   &       31    &       31   &         86   &         86 \\
\verb/mulsol.i.5/ & 186  &   3973   &       31    &       31   &         88   &         88 \\
&&&&&&\\
\verb/myciel3/   &   11  &     20   &        2    &        4   &          5   &          6 \\
\verb/myciel4/   &   23  &     71   &        2    &        5   &         11   &         12 \\
\verb/myciel5/   &   47  &    236   &        2    &   [ 4, 6]  &         23   &         24 \\
\verb/myciel6/   &   95  &    755   &        2    &   [ 4, 7]  &         47   &         48 \\
\verb/myciel7/   &  191  &   2360   &        2    &   [ 4, 8]  &         95   &         96 \\
&&&&&&\\
\verb/queen5_5/  &   25  &    320    &       5   &         5   &          5   &          5 \\
\verb/queen6_6/  &   36  &    580    &       6   &         7   &          6   &          6 \\
\verb/queen7_7/  &   49  &    952    &       7   &         7*  &          7   &          7 \\
\verb/queen8_8/  &   64  &   1456    &       8   &    [ 8,10]* &          8   &          8 \\ 
\verb/queen9_9/  &   81  &   2112    &       9   &    [ 9,11]* &          9   &          9 \\
\verb/queen8_12/ &   96  &   2736    &      12   &    [12,14]  &          8   &          8 \\ 
\verb/queen10_10/&  100  &   2940    &      10   &    [10,13]* &         10   &         10 \\
\verb/queen11_11/&  121  &   3960    &      11   &    [11,15]  &         11   &         11 \\
\verb/queen12_12/&  144  &   5192    &      12   &    [12,17]  &         12   &         12 \\
\verb/queen13_13/&  169  &   6656    &      13   &    [13,17]* &         13   &         13 \\
\verb/queen14_14/&  196  &   8372    &      14   &    [14,20]  &         14   &         14 \\
\verb/queen15_15/&  225  &  10360    &      15   &    [15,21]  &         15   &         15 \\
\verb/queen16_16/&  256  &  12640    &      16   &    [16,22]  &         16   &         16 \\
&&&&&&\\
\verb/school1/    & 385  &  19095   &       14   &         14  &   [ 40, 48]  &  [ 40, 47] \\
\verb/school1_nsh/& 352  &  14612   &   [14,17]  &    [14,17]  &   [ 37, 47]  &  [ 37, 47] \\
&&&&&&\\
\verb/zeroin.i.1/ & 211  &    4100  &        49  &         49  &         120  &        120 \\
\verb/zeroin.i.2/ & 211  &    3541  &        30  &         30  &         127  &        127 \\
\verb/zeroin.i.3/ & 206  &    3540  &        30  &         30  &         123  &        123 \\
\hline
\end{tabular}
\end{center}
\end{multicols}

\cleardoublepage
\printindex

\end{document}

