\documentclass[12pt,a4paper]{article}

\usepackage{geometry}

\title{TOPCOM User Manual}
\author{J\"org Rambau\\
  joerg.rambau@uni-bayreuth.de}



\begin{document}
\maketitle

\begin{verbatim}
\end{verbatim}


\section{What is TOPCOM?}
\label{sec:whatis}

TOPCOM is a collection of clients to compute \emph{Triangulations Of Point
Configurations and Oriented Matroids}, resp.

The algorithms use only combinatorial data of the point configuration as is
given by its oriented matroid.  Some basic commands for computing and
manipulating oriented matroids can also be accessed by the user.


\section{How do I use TOPCOM?}
\label{sec:howto}

All programs read the input from \texttt{stdin} and write the result to
\texttt{stdout} so that you can pipe the results to the next command.

A point configuration is given by a matrix (enclosed in square brackets) whose
columns (enclosed in square brackets) are the homogeneous coordinates
(seperated by commas) of the points in the configuration.  A square could be
specified as follows.

\begin{verbatim}
    [[0,0,1],[0,1,1],[1,0,1],[1,1,1]]
\end{verbatim}

You may specify generators of the combinatorial symmetry of a point
configuration as permutations of the vertex numbers. The symmetry of the square
reads as follows (observe that the count starts at 0!):

\begin{verbatim}
    [[3,2,1,0],[2,3,0,1],[0,2,1,3]]
\end{verbatim}

\section{Commands}
\label{sec:commands}

The following commands are provided:
\begin{description}
\item[\texttt{points2chiro}] Computes the chirotope of a point configuration.

\item[\texttt{chiro2dual}] Computes the dual of a chirotope.
\item[\texttt{chiro2circuits}] Computes the circuits of a chirotope.
\item[\texttt{chiro2cocircuits}] Computes the circuits of a chirotope.
\item[\texttt{cocircuits2facets}] Computes the facets of a set of cocircuits.

\item[\texttt{points2facets}] Computes the facets of a point configuration.

\item[\texttt{points2nflips}] Computes the number of flips of a point
  configurations and the seed triangulation.
\item[\texttt{points2flips}] Computes all flips of a point configurations and the
  seed triangulation.

\item[\texttt{chiro2placingtriang}] Computes the placing triangulation of a
  chirotope given by the numbering of the elements.
\item[\texttt{points2placingtriang}] dto.\ for point configurations.

\item[\texttt{chiro2finetriang}] Computes a fine (i.e., using all vertices)
  triangulation by placing and pushing.
\item[\texttt{points2finetriang}] dto.\ for point configurations.

\item[\texttt{chiro2triangs}] Computes all triangulations of a chirotope that
  are connected by bistellar flips to the regular triangulations.
\item[\texttt{points2triangs}] dto.\ for point configurations.

\item[\texttt{chiro2ntriangs}] Computes the number of all triangulations of a
  chirotope that are connected by bistellar flips to the regular triangulations.
\item[\texttt{points2ntriangs}] dto.\ for point configurations.

\item[\texttt{chiro2finetriangs}] Computes all fine triangulations of a
  chirotope that are connected by bistellar flips to a fine seed
  triangulation.
\item[\texttt{points2finetriangs}] dto.\ for point configurations.

\item[\texttt{chiro2nfinetriangs}] Computes the number of all fine
  triangulations of a chirotope that are connected by bistellar flips to a fine
  seed triangulation.
\item[\texttt{points2nfinetriangs}] dto.\ for point configurations.

\item[\texttt{chiro2alltriangs}] Computes all triangulations of a chirotope.
\item[\texttt{points2alltriangs}] dto.\ for point configurations.

\item[\texttt{chiro2nalltriangs}] Computes the number of all triangulations of a
  chirotope.
\item[\texttt{points2nalltriangs}] dto.\ for point configurations.

\item[\texttt{chiro2allfinetriangs}] Computes all fine triangulations of a
  chirotope.
\item[\texttt{points2allfinetriangs}] dto.\ for point configurations.
  
\item[\texttt{chiro2nallfinetriangs}] Computes the number of all fine
  triangulations of a chirotope.
\item[\texttt{points2nallfinetriangs}] dto.\ for point configurations.

\item[\texttt{cube d}] Computes the vertices and symmetry generators of a
  $d$-cube.
\item[\texttt{cyclic n d}] Computes the vertices and symmetry generators of
  the cyclic $d$-polytope with $n$ vertices.
\item[\texttt{cross d}] Computes the vertices of the $d$-dimensional cross-polytope.
\item[\texttt{hypersimplex k d}] Computes the vertices and symmetry generators of 
  the $k$-th hypersimplex in dimension~$d$.
\item[\texttt{santos\_triang}] Computes the point configuration, the symmetry,
  and the Santos triangulation (without flips).
\end{description}



\section{Command Line Options}
\label{sec:options}

The following command line options are supported:

\subsection*{Options controlling the overall behaviour of clients}
\begin{description}
\item[\texttt{-d}] Debug.
\item[\texttt{-h}] Print a usage message.
\item[\texttt{-v}] Verbose.
\end{description}

\subsection*{Options controlling what is computed}
\begin{description}
\item[\texttt{-}\texttt{-cardinality $[k]$}] Count only triangulations with exactly $k$ simplices.
\item[\texttt{-}\texttt{-checktriang}] Check seed triangulation.
\item[\texttt{-}\texttt{-flipdeficiency}] Check triangulations for flip deficiency.
\item[\texttt{-}\texttt{-frequency $[k]$}] Check every $k$-th triangulation
  for regularity and stop if one is found.
\item[\texttt{-}\texttt{-heights}] Output a height vector for every regular triangulation (implies
  \texttt{-}\texttt{-regular}).
\item[\texttt{-}\texttt{-noinsertion}] Never add a point that is unused in the seed triangulation.
\item[\texttt{-}\texttt{-reducepoints}] Try to greedily minimize the number of vertices used; keep
  a global upper bound on the current minimal number of vertices and do not
  accept triangulations with more vertices.
\item[\texttt{-}\texttt{-regular}] Search for regular triangulations only (checked liftings are
  w.r.t.\ the last homogeneous coordinate, e.g., last coordinates all ones is
  fine); note that this may reduce the effort of exploration, since regular
  triangulations are connected by themselves.
\item[\texttt{-}\texttt{-nonregular}] Output non-regular triangulations only;
  note that this does not reduce the effort of exploration, since non-regular
  triangulations are in general not connected by themselves.
\end{description}

\subsection*{Options controlling the internals of the clients}
\begin{description}
\item[\texttt{-}\texttt{-chirocache $[n]$}] Set the chirotope cache to $n$ elements.
\item[\texttt{-}\texttt{-localcache $[n]$}] Set the cache for local operations.
\item[\texttt{-}\texttt{-memopt}] Save memory by using caching techniques.
\item[\texttt{-}\texttt{-soplex}] Use soplex instead of cdd for regularity checks (unstable).
\end{description}

\subsection{Options for warm starts from previous calculations}
\label{sec:options-warm-starts}
\begin{description}
\item[\texttt{-}\texttt{-dumpfile $[$dumpfilename$]$}] Write intermediate results into a file.
\item[\texttt{-}\texttt{-dumpfrequency $[k]$}] Dump the results of a
  BFS round if at least $k$ triangulations have been computed
  inbetween
\item[\texttt{-}\texttt{-dumprotations $[k]$}] Dump into $k$ different rotating files.
\item[\texttt{-}\texttt{-readfile $[$readfilename$]$}] Read intermediate results from a file.
\end{description}




\section{Examples}
\label{sec:examples}

In the subdirectory \texttt{examples} you find some example inputs for TOPCOM
routines.  For example,

\begin{verbatim}
  points2chiro < lattice_3_3.dat
\end{verbatim}

outputs the sign string of the chirotope of the sub-lattice of integer points
$(i,j)$ with $i, j = 0, 1, 2$.

\begin{verbatim}
  points2chiro < lattice_3_3.dat | chiro2ntriangs
\end{verbatim}

or 

\begin{verbatim}
  points2ntriangs < lattice_3_3.dat
\end{verbatim}

yields the number of triangulations that are connected to the regular ones by
bistellar flips.

\begin{verbatim}
  points2ntriangs -r --affine < moae_testfile
\end{verbatim}
counts all regular triangulations of the ``mother of all examples'', two nested 
triangles in the plane.

\begin{verbatim}
  points2chiro < lattice_3_3.dat | chiro2nalltriangs
\end{verbatim}

yields the number of all triangulations via a branch \& bound algorithm.
For large examples this routine may take a lot of time but since it branches in
a DFS manner it does not take a lot of memory.

The example \texttt{r12.chiro} is the chirotope of the oriented matroid $R12$
with disconnected realization space, constructed by J\"ur\"-gen
Richter-Gebert.  If you want to compute, e.g., a placing triangulation of $R12$
then type

\begin{verbatim}
  chiro2placingtriang < r12.chiro
\end{verbatim}

The facets of a $4$-cube can be computed by

\begin{verbatim}
  cube 4 | points2chiro | chiro2dual | \
  chiro2circuits | cocircuits2facets
\end{verbatim}

but be aware of the fact that this is not an efficient way of computing facets
of a point configuration.  It is, however, numerically stable because rational
arithmetics is used.

Finally, you can check the Santos triangulation by

\begin{verbatim}
  santos_triang | points2nflips -v --memopt --checktriang
\end{verbatim}

Recall that the options mean:

\begin{description}
\item[\texttt{-v}] verbose;
\item[\texttt{-}\texttt{--memopt}] save memory;
\item[\texttt{-}\texttt{--checktriang}] check seed triangulation.
\end{description}

\end{document}

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: t
%%% End: 
