%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                  %
% Titre  : p.tex                   %
% Sujet  : PT-Scotch user's guide  %
%          Document body           %
% Auteur : Francois Pellegrini     %
%                                  %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% pdflatex -sPAPERSIZE=a4 p.tex
% dvips -sPAPERSIZE=a4 p.dvi -o ptscotch_userX.X.ps
% ps2pdf -sPAPERSIZE=a4 ptscotch_userX.X.ps ptscotch_userX.X.pdf

%% Formatage et pagination.

\documentclass{article}
\usepackage{a4}
\usepackage{url}
\usepackage{hyperref}
\usepackage{breakurl}
\hypersetup{pdfborder={0 0 0},colorlinks=false}
\usepackage{xspace}
\usepackage[dvips]{graphicx}
%\documentstyle[11pt,a4,fullpage,epsf]{article}
%\textwidth      16.0cm
%\oddsidemargin   -0.5cm
%\evensidemargin  -0.5cm
%\marginparwidth  0.0cm
%\marginparsep    0.0cm
%\marginparpush   0.0cm
%\topmargin        0.5cm
%\headheight      0.0cm
%\headsep         0.0cm
%\textheight     25.0cm
%\footheight      0.0cm
%\footskip        0.0cm

\sloppy                                          % Gestion des overfull hbox
\renewcommand{\baselinestretch}{1.05}            % Hauteur lignes x 1.05

\setcounter{secnumdepth}{3}                      % Sous-sous-sections numerotees
\setcounter{tocdepth}{3}                         % Sous-sous-sections dans la table

%% Macros et commandes utiles.

\makeatletter
\@definecounter{enumv}                           % 8 niveaux d'itemizations
\@definecounter{enumvi}
\@definecounter{enumvii}
\@definecounter{enumviii}
\def\itemize{\ifnum \@itemdepth >8 \@toodeep\else \advance\@itemdepth \@ne
\edef\@itemitem{labelitem\romannumeral\the\@itemdepth}%
\list{\csname\@itemitem\endcsname}{\def\makelabel##1{\hss\llap{##1}}}\fi}
\let\enditemize =\endlist

\def\@iteme[#1]{\if@noparitem \@donoparitem      % Item long pour options
  \else \if@inlabel \indent \par \fi
         \ifhmode \unskip\unskip \par \fi
         \if@newlist \if@nobreak \@nbitem \else
                        \addpenalty\@beginparpenalty
                        \addvspace\@topsep \addvspace{-\parskip}\fi
           \else \addpenalty\@itempenalty \addvspace\itemsep
          \fi
    \global\@inlabeltrue
\fi
\everypar{\global\@minipagefalse\global\@newlistfalse
          \if@inlabel\global\@inlabelfalse
             \setbox\@tempboxa\hbox{#1}\relax
             \hskip \itemindent \hskip -\parindent
             \hskip -\labelwidth \hskip -\labelsep
             \ifdim \wd\@tempboxa > \labelwidth
               \box\@tempboxa\hfil\break
             \else
               \hbox to\labelwidth{\box\@tempboxa\hfil}\relax
               \hskip \labelsep
             \fi
             \penalty\z@ \fi
          \everypar{}}\global\@nobreakfalse
\if@noitemarg \@noitemargfalse \if@nmbrlist \refstepcounter{\@listctr}\fi \fi
\ignorespaces}
\def\iteme{\@ifnextchar [{\@iteme}{\@noitemargtrue \@iteme[\@itemlabel]}}

\let\@Hxfloat\@xfloat
\def\@xfloat#1[{\@ifnextchar{H}{\@HHfloat{#1}[}{\@Hxfloat{#1}[}}
\def\@HHfloat#1[H]{%
\expandafter\let\csname end#1\endcsname\end@Hfloat
\vskip\intextsep\def\@captype{#1}\parindent\z@
\ignorespaces}
\def\end@Hfloat{\vskip \intextsep}
\makeatother

\def\progsyn{\item[{\makebox[1.5em][l]{\bf Synopsis}}]\ ~\linebreak[0]\\*[1em]}
\def\progdes{\item[{\makebox[1.5em][l]{\bf Description}}]\ ~\linebreak[0]\\*[1em]}
\def\progopt{\item[{\makebox[1.5em][l]{\bf Options}}]~\linebreak[0]}
\def\progret{\item[{\makebox[1.5em][l]{\bf Return values}}]~\linebreak[0]}

\newcommand{\bn}{\begin{displaymath}}            % Equations non-numerotees
\newcommand{\en}{\end{displaymath}}
\newcommand{\bq}{\begin{equation}}               % Equations numerotees
\newcommand{\eq}{\end{equation}}

\newcommand{\lbo}{\linebreak[0]}
\newcommand{\lbt}{\linebreak[2]}
\newcommand{\noi}{{\noindent}}                   % Pas d'indentation
\newcommand{\spa}{{\protect \vspace{\bigskipamount}}} % Espace vertical

\newcommand{\eg}{\textit{e\@.g\@.}\xspace}       % e.g.
\newcommand{\ie}{\textit{i\@.e\@.}\xspace}       % i.e.

\newcommand{\chaco}{{\sc Chaco}}                 % "Chaco"
\newcommand{\metis}{\mbox{\sc Me$\!$T$\!$iS}}    % "MeTiS"
\newcommand{\parmetis}{\mbox{\sc ParMe$\!$T$\!$iS}}
\newcommand{\scotch}{{\sc Scotch}}               % "Scotch"
\newcommand{\libscotch}{{\sc libScotch}}         % "libScotch"
\newcommand{\ptscotch}{{\sc PT-Scotch}}          % "PT-Scotch"
\newcommand{\libptscotch}{{\sc libPTScotch}}     % "libPTScotch"

\newcommand{\eqdef}{\stackrel{\scriptscriptstyle \rm def}{=}}       % = as definition
\newcommand{\isapprox}{\mathop{\approx}\limits}

\newcommand{\lefta}{\longleftarrow}
\newcommand{\rghta}{\longrightarrow}
\newcommand{\botha}{\longleftrightarrow}
\newcommand{\Lefta}{\Longleftarrow}
\newcommand{\Rghta}{\Longrightarrow}
\newcommand{\Botha}{\Longleftrightarrow}

\newcommand{\HY}{{\rm H}}                        % H
\newcommand{\KP}{{\rm K}}                        % K
\newcommand{\MK}[1]{{\rm M}_{#1}}                % Mk
\newcommand{\MD}{\MK{2}}                         % M2
\newcommand{\PA}{{\rm P}}                        % P
\newcommand{\UB}{{\rm UB}}                       % UB
\newcommand{\SE}{{\rm SE}}                       % SE
\newcommand{\FFT}{{\rm FFT}}                     % FFT
\newcommand{\BF}{{\rm BF}}                       % BF
\newcommand{\BFB}{{\overline{\rm BF}}}           % BF bar
\newcommand{\CCC}{{\rm CCC}}                     % CCC
\newcommand{\CCCB}{{\overline{\rm CCC}}}         % CCC bar

\newcommand{\roo}[1]{{\rho_{\scriptscriptstyle {#1}}}} % Rho avec petit argument
\newcommand{\too}[1]{{\tau_{\scriptscriptstyle {#1}}}} % Tau avec petit argument
\newcommand{\xio}[1]{{\xi_{\scriptscriptstyle {#1}}}} % Xi avec petit argument

\newcommand{\SB}[1]{{\cal C}'_S\left({#1}\right)} % Comportement en espace
\newcommand{\TB}[1]{{\cal C}'_T\left({#1}\right)} % Comportement en temps
\newcommand{\SC}[1]{{\cal C}_S\left({#1}\right)} % Complexite en espace
\newcommand{\TC}[1]{{\cal C}_T\left({#1}\right)} % Complexite en temps

\newcommand{\dmap}{\mbox{$\delta_{map}$}}
\newcommand{\dexp}{\mbox{$\delta_{exp}$}}
\newcommand{\mmap}{\mbox{$\mu_{map}$}}
\newcommand{\mdil}{\mbox{$\mu_{dil}$}}
\newcommand{\mcom}{\mbox{$\mu_{com}$}}
\newcommand{\mexp}{\mbox{$\mu_{exp}$}}

\newcommand{\NNZ}{\mbox{NNZ}}
\newcommand{\OPC}{\mbox{OPC}}
\newcommand{\hnbr}{\mbox{$h_{\rm nbr}$}}
\newcommand{\hmin}{\mbox{$h_{\rm min}$}}
\newcommand{\hmax}{\mbox{$h_{\rm max}$}}
\newcommand{\havg}{\mbox{$h_{\rm avg}$}}
\newcommand{\hdlt}{\mbox{$h_{\rm dlt}$}}

%% Version du document.

\input{../version.tex}

\newcommand{\scotchcitepuser}{\protect\cite{pell08c}}
\newcommand{\scotchcitesuser}{\protect\cite{pell08b}}

%% Page de garde.

\begin{document}

\date{\today}

\title{\includegraphics[scale=0.8]{../misc/ptscotch_logo_color.ps}\\[1em]
       {\LARGE\bf \ptscotch\ and \libptscotch\ {\sc \scotchver} \mbox{User's Guide}}\\[1em]%
       {\normalsize (version \scotchversub)}
}

\author{Fran\c cois Pellegrini\\
Universit\'e de Bordeaux \& LaBRI, UMR CNRS 5800\\
TadAAM team, INRIA Bordeaux Sud-Ouest\\
351 cours de la Lib\'eration, 33405 TALENCE, FRANCE\\
{\tt pelegrin@labri.fr}}

\maketitle

\begin{abstract}

This document describes the capabilities and operations of
\ptscotch\ and \libscotch, a software package and a software library
which compute parallel static mappings and parallel sparse matrix
block orderings of distributed graphs. It gives brief descriptions of
the algorithms, details the input/output formats, instructions for
use, installation procedures, and provides a number of examples.

\ptscotch\ is distributed as free/libre software, and has been
designed such that new partitioning or ordering methods can be added
in a straightforward manner. It can therefore be used as a testbed for
the easy and quick coding and testing of such new methods, and may
also be redistributed, as a library, along with third-party software
that makes use of it, either in its original or in updated forms.
\end{abstract}

\clearpage

%% Table des matieres.

\tableofcontents

%% Corps du document.

\input{p_i.tex}                                  % Introductions
\input{p_c.tex}                                  % Changes since previous versions
\input{p_f.tex}                                  % Formats de fichiers
\input{p_p.tex}                                  % Programmes
\input{p_l.tex}                                  % Bibliotheque
\input{p_d.tex}                                  % Distribution
\input{p_e.tex}                                  % Relevant examples
%\input{p_n.tex}                                  % Addition of a new method

%% Remerciements.

\section*{Credits}

I wish to thank all of the following people:
\begin{itemize}
\item
C\'edric Chevalier, during his PhD at LaBRI, did research on efficient
parallel matching algorithms and coded the parallel multilevel
algorithm of \ptscotch. He also studied parallel genetic refinement
algorithms. Many thanks to him for the great job!
\item
Amaury Jacques improved the development environment and contributed to
the consistency checking and non-regression testing routines;
\item
Selmane Lebdaoui coded the prototype of the threaded version of the
distributed coarse graph building algorithm;
\item
Yves Secretan contributed to the MinGW32 port.
\end{itemize}

%% Bibliographie.

\bibliographystyle{plain}
\bibliography{p}

\end{document}
