2003-07-18 (July 18, 2003)
-----------------------------------------------
C-Library cddlib (version 0.93) README FILE
-----------------------------------------------
1. The C-library  cddlib is a C implementation of the Double Description 
Method of Motzkin et al. for generating all vertices (i.e. extreme points)
and extreme rays of a general convex polyhedron in R^d given by a system 
of linear inequalities:

   P = { x=(x1, ..., xd)^T :  b - A  x  >= 0 }

where  A  is a given m x d real matrix, b is a given m-vector 
and 0 is the m-vector of all zeros.

The program can be used for the reverse operation (i.e. convex hull
computation).  This means that  one can move back and forth between 
an inequality representation  and a generator (i.e. vertex and ray) 
representation of a polyhedron with cdd.  Also, cdd can solve a linear
programming problem, i.e. a problem of maximizing and minimizing 
a linear function over P.

The version 0.93 is the sixth release of libcdd. New functions
added in this release include  dd_Matrix2Adjacency, 
dd_FourierElimination, and dd_BlockElimination.
One major change is how the linear programming solver
dd_LPSolve works in the GMP exact arithmetics mode.
It solves an LP with floating-point arithmetics first
and it checks with GMP whether the output is
correct.  If so, it outputs a correct exact solution.
Otherwise, it solves the problem from scrach with GMP. 
It runs much faster for most of the cases. 

Both cdd libraries libcdd.a and libcddgmp.a are compatible with
the previous version 092.   One significant change is an extension
of libcddgmp.a.  The GMP based library libcddgmp.a now contains 
both the GMP arithmetics and the C double floating-point arithmetics functions
in one.  The functions using GMP are accessible as before, and
the same functions using the floating-point arithmetics are
also included in the same library libcddgmp.a.  To call 
the floating-point versions, you need to use ddf_ prefix
instead of the usual dd_ prefix.  In addition, there are
two types of numbers, the default mytype and an additional
myfloat type that is to be used with the ddf_* functions.
This "duplex" functionality is in fact exploited in the new 
LP solver dd_LPSolve.

If you find some problems or bugs, please kindly report them to
fukuda@ifor.math.ethz.ch.  Please read README.whatsnew for the changes 
over the last release.

The documentation (cddlibman.tex) is still incomplete but contains 
descriptions of the most important functions. Please look at the examples,
testcdd*.c, testlp*.c, simplecdd.c, lcdd.c, redcheck,c for how 
the library functions can be used in user's C-codes.

2. One convenient feature of cddlib is the ability
to handle essentially any data.  More precisely, it can
generate an H-representation of a V-polyhedron which is not
full-dimensional, and it can generate a V-representation
of an H-polyhedron which has no extreme points.

3. A little caution is in order.  Many people have seen 
numerical problems when the floating version of cddlib
is used.   As we all know, floating-point computation
might not give a correct answer, especially when an input
data is very sensitive to a small perturbation.  When
some strange behavior is observed, it is always wise
to create a rational approximation of the input
(for example, one can replace 0.3333333 with 1/3)
and to compute it with cddlib compiled with gmp rational
to see what a correct behavior should be.  Whenever the time
is not important, it is safer to use gmp rational arithmetic.

If you need speedy computation with floating-point arithmetic, 
you might want to "play with" the constant "dd_almostzero" defined 
in cdd.h:

   #define dd_almostzero  1.0E-7

This number is used to recognize whether a number is zero: 
a number whose absolute value is smaller
than dd_almostzero is considered zero, and nonzero otherwise.
You might want to change this to modify the behavior of cddlib.
Another thing one can do is scaling.  If the values in one column of
an input is of smaller magnitude than those in another column, 
scale one so that they become comparable.

4. cddlib comes with a MatheLink version of cddlib that can be
called from Mathematica (tested only for Mathematica 2.2 and 3.0).
A few Mathematica notebooks are included to explain how one can 
use this program "cddmathlink" from Mathematica
to manipulate polytopes.  Please check the files, 
cddml-notbook.ma, cddml-PolytopeSkeleton.ma, cddml-DietProblem.ma,
and cddml-Zonotope.ma, in the mma subdirectory.  I could 
compile cddmathlink.c for Macintosh and Windows.  I have put
binaries for different platforms in 
http://www.cs.mcgill.ca/~fukuda/download/cdd/cddlibml_binary/  .

5. The cddlib package is in "tar"ed and "gzip"ed format with name
cddlib-***.tar.gz, where *** is the version number.  The standard
download site for the package is

     web site : http://www.cs.mcgill.ca/~fukuda/cdd 
     file name: cddlib-***.tar.gz

In order to unpack the package in a standard unix environment, type 
   
     % gunzip cddlib-***.tar.gz
     % tar xvf cddlib-***.tar

where *** must be replaced by the appropriate version number, and
% is a unix prompt. 

For compilation of libcdd, go to the cddlib top directorycddlib
and follow the general instruction of autoconf.  In generic
unix/linux environment, use "./configure" and "make".
To enforce a certain compiler to be use, specify it as

   CXX=gcc ./configure

One must install GMP-4.1 (or GMP-3.*) first.  For compilation of MathLink programs,
you need a binary "mprep", MathLink library "libML.a" and include file
"mathlink.h" which come with Mathematica.   I have tested for Mathematica 4.1
and 3.* on MacOSX and Linux.  This part is not "autoconf"igured
and thus one needs to edit Makefile in the src-mathlink and src-mathlink2 subdirectories. 

To install the library in public directory of unix environment, 
just type "make install".  The default installation directory
is /usr/local.  If you want to select other places, use
"./configure --prefix=<DIRNAME>" to configure with your favorite
<DIRNAME>. 

One might have to make the files publicly readable by chmod.
Once the files are properly installed, any user can use compile
one's own code (e.g. testcdd1.c) and link it with libcdd by
  
   % gcc -I/usr/local/include -L/usr/local/lib testcdd1.c -lcdd

or (with GMP rational arithmetic)

   % gcc -I/usr/local/include -L/usr/local/lib -DGMPRATIONAL testcdd1.c -lcddgmp -lgmp

The library cddlib is free software, but if cddlib turns out to be useful, 
please kindly send to me (at the address below) a note or a paper mentioning 
for what purpose and how cdd has been used. The most powerful support 
for free software development is user's appreciation.   

For more information, contact
   Komei Fukuda
   School of Computer Science
   McGill University
   McConnel Engineering Building
   3480 University Street
   Montreal, Quebec
   Canada H3A 2A7

// END of README 

