intro.autodoc

@Chapter Introduction

@Section What is the purpose of the this package?

Normaliz <Cite Key="normaliz" /> is a software for computations with rational cones and affine
monoids. It pursues two main computational goals: finding the Hilbert
basis, a minimal generating system of the monoid of lattice points of a
cone; and counting elements degree-wise in a generating function, the
Hilbert series.
As a recent extension, Normaliz can handle unbounded polyhedra. The
Hilbert basis computation can be considered as solving a linear
diophantine system of inhomogeneous equations, inequalities and
congruences.  <P/>

This package encapsulates a libnormaliz cone and gives access to it in the
&GAP; environment. In this way &GAP; can be used as interactive interface to
libnormaliz.  <P/>

@Chapter Functions

In this chapter we describe the functions offered by <A>NormalizInterface</A>.
All functions supplied by this package start with <Q>Nmz</Q>.
For examples see the chapter <Ref Chap="Chapter_Examples" Style="Text"/>.


@Section Create a NmzCone

To create a cone object use <A>NmzCone</A>.

@Section Use a NmzCone

@Section Cone properties

@Chapter Examples

@Section Generators

@InsertChunk Demo example

@Section System of equations
@InsertChunk Demo example equation

@Section System of inhomogeneous equations
@InsertChunk Demo example inhom equation

@Section Combined input
Normaliz also allows the combination of different kinds of input, e.g.
multiple constraint types, or additional data like a grading.

Suppose that you have a 3 by 3 <Q>square</Q> of nonnegative integers such that
the 3 numbers in all rows, all columns, and both diagonals sum to the same
constant <M>M</M>. Sometimes such squares are called magic and <M>M</M> is the
magic constant. This leads to a linear system of equations. The magic constant
is a natural choice for the grading. Additionally we force here the 4 corner
to have even value by adding congruences.

@InsertChunk Demo example 3x3magiceven

@Section Using the dual mode
For solving systems of equations and inequalities it is often faster to use
the dual Normaliz algorithm. We demonstrate how to use it with an
inhomogeneous system of equations and inequalities.

The input consists of a system of 8 inhomogeneous equations in R^3. The first
row of the matrix M encodes the inequality <M>8x + 8y + 8z + 7 \geq 0</M>.
Additionally we say that <M>x, y, z</M> should be non-negative by giving the
sign vector and use the total degree.
@InsertChunk example dual

As result we get the Hilbert basis of the cone of the solutions to the
homogeneous system and the module generators which are the base
solutions to the inhomogeneous system.

@Chapter Installing NormalizInterface

@Section Compiling

NormalizInterface supports GAP 4.8.0 or later, and Normaliz 3.0.0 or later.
<P/>

For technical reasons, installing and using NormalizInterface requires
that your version of GAP is compiled in a special way. Specifically, GAP
must be compiled against the exact same version of the GMP library as
Normaliz. By default, GAP compiles its own version of GMP; however, we
cannot use that, as it lacks C++ support, which is required by Normaliz.
<P/>

Thus as the very first step, please install a version of GMP in your
system. On most Linux and BSD distributions, there should be a GMP
package available with your system's package manager. On Mac OS X, you
can install GMP via Fink, MacPorts or Homebrew.
<P/>

Next, make sure your GAP installation is compiled against the system
wide GMP installation. To do so, switch to the GAP root directory, and
enter the following commands:
<P/>

<Listing><![CDATA[
    make clean
    ./configure --with-gmp=system
    make
]]></Listing>

Next you need to compile a recent version of Normaliz. This requires the
presence of several further system software packages, which you install
via your system's package manager. At least the following are required:
<P/>

 * git
 * cmake
 * boost

Once you have installed these, you can build Normaliz by using
the build-normaliz.sh script we provide. It takes a single,
optional parameter: the location of the GAP root directory.
<P/>

<Listing><![CDATA[
    ./build-normaliz.sh GAPDIR
]]></Listing>

Once it completed successfully, you can then build NormalizInterface
like this:
<P/>

<Listing><![CDATA[
    ./configure --with-gaproot=GAPDIR
    make
]]></Listing>

If you need to customize the normaliz compilation, please have a look at
Normaliz.git/source/INSTALL. Remember to use the same compiler and GMP
version as for GAP.
<P/>