% !TeX spellcheck = en_US

\documentclass[12pt,a4paper]{scrartcl}
\usepackage{amsmath}
\usepackage{amsfonts}
\usepackage[latin1]{inputenc}
\usepackage{mathptmx}
\usepackage{amscd}
\usepackage{array}
\usepackage{color}
\usepackage{hyperref}
\usepackage{url}
\usepackage{graphicx}

\usepackage{booktabs}

%\textwidth=15cm \textheight=22cm \topmargin=0.5cm
%\oddsidemargin=0.5cm \evensidemargin=0.5cm

\usepackage[T1]{fontenc}

\usepackage[scaled=0.8]{beramono}

\usepackage{fancyvrb} \RecustomVerbatimEnvironment{Verbatim}{Verbatim}
{xleftmargin=15pt, frame=single, fontsize=\small}


\newcounter{listi}
\newcommand{\stdli}{ \topsep0ex \partopsep0ex % .5ex plus.25ex minus.125ex%
    \parsep.2ex plus.1ex minus.1ex \itemsep0ex% .5ex plus.25ex minus.125ex%
    \leftmargin2.5em \labelwidth2em \labelsep.5em \rightmargin0em}% \samepage }
\newenvironment{arab}{\begin{list}{\textup{(\arabic{listi})}}%
    {\usecounter{listi}\stdli}}{\end{list}}
\newenvironment{rome}{\begin{list}{\textup{(\roman{listi})}}%
    {\usecounter{listi}\stdli}}{\end{list}}
\newenvironment{latin}{\begin{list}{\textup{(\alph{listi})}}%
    {\usecounter{listi}\stdli}}{\end{list}}
\renewenvironment{itemize}{\begin{list}{{$\bullet$}}{\stdli}}{\end{list}}
\newenvironment{myverb}{\begin{small}}{\end{small}\pagebreak[2]}  %%%%%  \vspace{-0.8\baselineskip}
\newenvironment{yourverb}{\begin{small}\begin{Verbatim}}{\end{Verbatim}\end{small}\pagebreak[2]}



\let\phi=\varphi

\def\CC{{\mathbb C}}
\def\ZZ{{\mathbb Z}}
\def\QQ{{\mathbb Q}}
\def\RR{{\mathbb R}}
\def\EE{{\mathbb E}}
\def\AA{{\mathbb A}}
\def\PP{{\mathbb P}}
\def\NN{{\mathbb N}}

\def\Ker{\operatorname{Ker}}
\def\Im{\operatorname{Im}}
\DeclareMathOperator{\gp}{gp}
\DeclareMathOperator{\rank}{rank}
\DeclareMathOperator{\totdeg}{totdeg}


\def\cG{{\mathcal G}}
\def\cR{{\mathcal R}}

\let\hat=\widehat
\let\tilde=\widetilde
\let\Bar=\overline

\let\iso=\cong

\let\epsilon=\varepsilon
\def\discuss#1{\marginparsep=1em\marginparwidth=60pt
     \marginpar{\tt \footnotesize \raggedright #1}}

\definecolor{darkgray}{gray}{0.00}

\addtokomafont{section}{\color{darkgray}}

\setkomafont{sectionentry}{\large}

\addtokomafont{subsection}{\color{darkgray}}

\addtokomafont{subsubsection}{\normalsize}

\parindent=0pt \parskip=4pt

\setcounter{tocdepth}{3}

%\def\Normaliz#1+{\textsf{Normaliz}}
%\def\jNormaliz#1+{\textsf{jNormaliz}}
%\def\NmzIntegrate#1+{\textsf{NmzIntegrate}}

\def\itemtt[#1]{\item[\ttt{#1}]}

\def\ttt{\texttt}


\begin{document}
\vspace*{2cm}

 \centerline{\Large\bf NmzIntegrate 1.3.1} \vspace*{0.5cm}
 
 \centerline{\today}
 
 \vspace*{1cm}


\begin{center}Winfried Bruns and Christof
Söger\\[14pt] \tt
\url{mailto:normaliz@uos.de}\\[14pt]
\url{https://normaliz.uos.de}
\end{center}
%\vspace*{1cm}


\tableofcontents

%\newpage

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%  INTRODUCTION  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%


\section{The objectives of NmzIntegrate}



We assume in the following that the reader is familiar with
Normaliz, in particular with its treatment of Ehrhart series
and quasipolynomials. NmzIntegrate 1.3.1 requires Normaliz 3.1.1.

Normaliz computes certain data for a monoid $$ M=C\cap L $$
where $C\subset\RR^n$ is a rational, polyhedral and pointed
cone, and $L\subset \ZZ^n$ is a sublattice. These data are
defined by the input to Normaliz. NmzIntegrate requires
that $M$ has been endowed with a grading $\deg$ (see the manual
of Normaliz 3.0).

For such graded monoids Normaliz can compute the volume of
the rational polytope
$$
P=\{x\in \RR_+ M: \deg x=1\},
$$
the Ehrhart series of $P$, and the quasipolynomial representing
the Ehrhart function. (Here $\RR_+M$ is the cone generated by
the elements of $M$; it may be smaller than $C$ if $L$ has rank
$<n$.)

These computations can be understood as integrals of the
constant polynomial $f=1$, namely with respect to the counting
measure defined by $L$ for the Ehrhart function, and with
respect to the (suitably normed) Lebesgue measure for the
volume. NmzIntegrate generalizes these computations to
arbitrary polynomials $f$ in $n$ variables with rational
coefficients. (Mathematically, there is no need to restrict
oneself to rational coefficients for $f$.)

More precisely, set
$$
E(f,k)=\sum_{x\in M, \deg x=k} f(x),
$$
and call $E(f,\_)$ the \emph{generalized Ehrhart function} for
$f$. (With $f=1$ we simply count lattice points.) The
\emph{generalized Ehrhart series} is the ordinary generating
function
$$
E_f(t)=\sum_{k=0}^\infty E(f,k)t^k.
$$
It turns out that $E_f(t)$ is the power series expansion of a
rational function at the origin, and can always be written in
the form
$$
E_f(t)=\frac{Q(t)}{(1-t^\ell)^{\totdeg f+\rank M}},\qquad Q(t)\in\QQ[t],\
\deg Q< \totdeg f+\rank M.
$$
Here $\totdeg f$ is the total degree of the polynomial $f$, and
$\ell$ is the least common  multiple of the degrees of the
extreme integral generators of $M$. See \cite{BS} for an
elementary account and the algorithm used by NmzIntegrate.

NmzIntegrate 1.3.1, like Normaliz 3.1.1 can compute Ehrhart series for
\emph{semiopen} cones. For them the monoid $M$ is replaced by the set
$$
M'=C'\cap L
$$
where $C'=C\setminus \mathcal F$ and $\mathcal F$ is the union of a set of
faces
(not necessarily facets) of $C$. What has been said above about the structure
of the generalized Ehrhart series remains true. We discuss an example in
Section \ref{output}.

It follows from the general theory of rational generating
functions that there exists a quasipolynomial $q(k)$ with
rational coefficients and of degree $\le \totdeg f+\rank M-1$ that
evaluates to $E(f,k)$ for all $k\ge 0$. A quasipolynomial is a
``polynomial'' with periodic coefficients: there exist a
\emph{period} $\pi\in\NN$ and true polynomials $q^{j}\in\QQ[X]$,
$j=0,\dots,\pi-1$, such that
$$
q(k)=q^{(j)}(k)\qquad \text{if}\quad k\equiv j\pod \pi.
$$
Each of the polynomials $q^{(j)}$ is given as
$$
q^{(j)}(k)=q^{(j)}_0+q^{(j)}_1X+\dots+q^{(j)}_{\totdeg f+\rank M-1}X^{\totdeg f+\rank M-1}
$$
with constant coefficients in $\QQ$. The period $\pi$ divides $\ell$.

Let $m=\totdeg f$ and $f_m$ be the degree $m$ homogeneous
component of $f$. By letting $k$ go to infinity and
approximating $f_m$ by a step function that is constant on the
meshes of $\frac 1kL$ (with respect to a fixed basis), one sees
$$
q^{(j)}_{\totdeg f+\rank M-1}=\int_P f_m\, d\lambda
$$
where $d\lambda$ is the Lebesgue measure that takes value $1$
on a basic mesh of $L\cap \RR M$ in the hyperplane of degree
$1$ elements in $\RR M$. In particular, the \emph{virtual
leading coefficient} $q^{(j)}_{\totdeg f+\rank M-1}$ is
constant and depends only on $f_m$. If the integral vanishes,
the quasipolynomial $q$ has smaller degree, and the true
leading coefficient need not be constant. Following the
terminology of commutative algebra and algebraic geometry, we
call
$$
(\totdeg f+\rank M-1)!\cdot q_{\totdeg f+\rank M-1}
$$
the \emph{virtual multiplicity} of $M$ and $f$. It is an
integer if $f_m$ has integral coefficients and $P$ is a lattice
polytope.

Since a semiopen cone $C'$ differs from its closure in a set of measure $0$,
the passage to $C'$ does not change the Lebesgue integrals just mentioned, and
is therefore irrelevant for their computation.

NmzIntegrate computes
\begin{itemize}
\item[(ES)] the generalized Ehrhart series and its
    quasipolynomial,
\item[(Int)] the Lebesgue integral of $f$ over $P$, or
\item[(LC)] the virtual leading coefficient and the virtual
    multiplicity.
\end{itemize}
The user controls the type of computation by a command line
option. (ES) contains (LC), and (LC) is just the evaluation of
(Int) on the highest homogeneous component of $f$. It is
presently not possible to compute the Ehrhart series and the
integral together if $f$ is not homogeneous, but the two
computations can be combined in one run of NmzIntegrate.
\bigskip

\emph{Acknowledgement.}\enspace We gratefully acknowledge the
support we received from John Abbott and Anna Bigatti in using
CoCoALib, on which the multivariate polynomial algebra in
NmzIntegrate is based.
\medskip

 The development of Normaliz is currently supported by the DFG SPP 1489 ``Algorithmische und ex\-pe\-rimentelle Methoden in Algebra, Geometrie und Zahlentheorie''.


\section{Major changes in this version}

None.

\section{Input files}

NmzIntegrate can be used in two ways:
\begin{enumerate}
\item by direct call from the command line,
\item by call from within Normaliz with the appropriate
    options.
\end{enumerate}

If NmzIntegrate misses an input file that should have been
produced by Normaliz, it calls Normaliz and makes it
produce the missing file(s). Normaliz is also called
if a file produced by it is older than the Normaliz input file,
provided the latter is accessible.

For mutual calls it is necessary that the executables of
Normaliz and NmzIntegrate reside in the same directory.

Note: NmzIntegrate can only use the \emph{homogeneous} input types of Normaliz (including \verb|excluded_faces|).

\subsection{Basic input files}

The files \verb+<project>.in+ and \verb+<polynomial>.pnm+ must be
provided by the user. Normaliz needs \verb+<project>.in+ in
order to produce the files read by NmzIntegrate. The file
\verb+<polynomial>.pnm+ contains the polynomial to be integrated.

Unless the user defines \verb+<polynomial>+ explicitly (see below), NmzIntegrate
sets \verb+<polymomial>=+ \verb+<project>+. The explicit choice of the
\verb+<polynomial>+ is only possible if NmzIntegrate is called from the
command line.

\subsection{Auxiliary files produced by Normaliz}

One runs Normaliz with the option
\begin{itemize}
\itemtt[-T] (or \ttt{-y}) for (Int) and (LC),
\itemtt[-y] for (ES).
\end{itemize}
(It is allowed to combine \ttt{-T} and \ttt{-y}.) If
NmzIntegrate calls Normaliz, then it chooses these options
automatically.

This will produce the files with the following suffixes (in
addition to \verb+<project>.out+ and possibly further output
files determined by the Normaliz options \ttt{-f} and \ttt{-a}):
\begin{itemize}
\itemtt[-T] \ttt{inv}, \ttt{tgn}, \ttt{tri}
\itemtt[-y] \ttt{inv}, \ttt{tgn}, \ttt{dec}.
\end{itemize}
NmzIntegrate reads
\begin{itemize}
\item the grading and the rank from \verb+<project>.inv+,
\item the rays of the triangulation from \verb+<project>.tgn+,
\item the triangulation from \verb+<project>.tri+ (for (Int) and (LC)) and
\item the Stanley decomposition from \verb+<project>.dec+ (for
(ES)).
\end{itemize}
If \verb+<project>.tri+ does not exist for one of the
tasks (Int) or (LC), NmzIntegrate checks for the existence of
\verb+<project>.dec+ and reads the triangulation from it.

NmzIntegrate itself does not read \ttt{<project>.in} nor any
other output file of Normaliz than those just mentioned.

\subsection{The polynomial}

The polynomial is read from the file \verb+<polynomial>.pnm+. The polynomial
can be defined by a usual polynomial expression using rational coefficients,
addition, subtraction, multiplication and exponentiation, following the
standard precedence rules for the evaluation of such expressions.

Note:
\begin{enumerate}
\item  The names of the variables are fixed:
\verb+x[1]+,\dots,\verb+x[<n>]+ where \ttt{<n>} represents the
number~$n$.
\item An explicit multiplication sign \verb+*+ is necessary for all multiplications, in particular between a coefficient and an indeterminate or between indeterminates.
\end{enumerate}

Examples:
\begin{Verbatim}
1/120*(x[1]+x[2]^2)*(-2*x[3]*x[4])^2+x[3]
\end{Verbatim}
is a well formed input polynomial, but

\begin{Verbatim}
1/120(x[1]+x[2]^2)*(-2x[3]*x[4])^2+x[3]
\end{Verbatim}

is not allowed.

NmzIntegrate is now using the CoCoALib input function for polynomials. In the previous version some multiplication signs that are now necessary had to be omitted.

\section{Running NmzIntegrate}

There are three ways to run NmzIntegrate:
\begin{enumerate}
\item direct call from the command line,
\item call from Normaliz (see Normaliz manual),
\item from jNormaliz via Normaliz.
\end{enumerate}

The shortest possible command to start NmzIntegrate is
\begin{Verbatim}
nmzIntegrate <project>
\end{Verbatim}
This will run the default computation (ES) on the
\verb+<project>+. The full input syntax is
\begin{Verbatim}
nmzIntegrate [-cEIL] [-x=<T>] [-F=<polynomial>] <project>
\end{Verbatim}
where \ttt{-c} and \ttt{-x=<T>} have the same meaning as for
Normaliz:
\begin{itemize}
\itemtt[-c] activates the verbose mode in which control
    information is written to the terminal,
\itemtt[-x=<T>] limits the number of parallel threads to
    \ttt{<T>}.
\end{itemize}

The following options control the type of computation:
\begin{itemize}
\itemtt[-E] activates the computation (ES) (the default
    mode, can be omitted),
\itemtt[-I] activates the computation (Int),
\itemtt[-L] activates the computation (LC).
\end{itemize}
These three options can be accumulated. If at least two options
are set, the computations are carried out according to the
following rules:
\begin{itemize}
\item If \ttt{-E} is present, \ttt{-L} will be suppressed since
its result is contained in that of \ttt{-E}.
\item If \ttt{-I} is present, then it will be suppressed if
    one of \ttt{-E} or \ttt{-L} is set and the polynomial is
    homogeneous since \ttt{-L} and \ttt{-I} are identical
    for homogeneous polynomials.
\end{itemize}
If two different computations are carried out, then their
output will appear consecutively in the output file.

If \verb+-F=<polynomial>+ appears, then the polynomial is read from the file
\verb+<polynomial>.pnm+. Note that \verb+<polynomial>.pnm+ must reside in the
directory defined by \verb+<project>+. It is not possible to prefix
\verb+<polynomial>+ by a path name (which may be necessary for
\verb+<project>+).

If the option \verb+-F=<polynomial>+ is omitted, the
polynomial is read from \verb+<project>.pnm+.

The options \verb+-c+ and \verb+-x=<T>+ are passed form
Normaliz to NmzIntegrate and vice versa. There is no need to worry about the integer precision of Normaliz or NmzIntegrate: Normaliz chooses it automatically and NmzIntegrate does always work with infinite precision.

It is not possible (presently) to use the option \verb+-F=<polynomial>.pnm+ if
NmzIntegrate is called from Normaliz.

Note that NmzIntegrate may need much more memory than
Normaliz, especially with a high number of parallel threads,
due to the fact that it may have to cope with very long
polynomials.

\section{The output file}\label{output}

If the option \verb+-F=<polynomial>+ is not set, the output is written to
the file \ttt{<project>.intOut}
(so that it is clearly distinguished from the Normaliz
output file). If \verb+-F=<polynomial>+ appears, the output is
written to \ttt{<project>.<polynomial>.intOut}.

NmzIntegrate factors the polynomial, and the factorization is
written to the output file. For the computation (LC) the
polynomial is first replaced by its leading form, and the
output file then contains the factorization of the leading
form.

The output file is essentially self explanatory. Nevertheless we have added two
examples below. In addition you can have a look at the files
\begin{center}
\ttt{rationalES.intOut},\quad \ttt{rationalInt.intOut}\quad and\quad
\ttt{rationalLC.intOut}.
\end{center}
They were all produced from the example file \ttt{rational.in}
in the Normaliz distribution and the file \ttt{rational.pnm},
and \ttt{rational.intOut} was suitably renamed.

The directory \ttt{example} contains further input files suited
for NmzIntegrate --- look out for files with the suffix
\ttt{pnm}.

\subsection{A generalized Ehrhart series}

We choose an example from combinatorial voting theory which is discussed in
more detail in \cite{BS}. The file \ttt{CondorcetSymm.in} from the directory
\ttt{examples} contains the following:

\begin{Verbatim}
amb_space 8
inequalities 3
1 -1 1 1 1 -1 -1 -1
1 1 -1 1 -1 1 -1 -1
1 1 1 -1 -1 -1 1 -1
nonnegative
total_degree
\end{Verbatim}


The \ttt{signs} describe the nonnegative orthant in $\RR^8$ and the linear
forms $\lambda_1,\lambda_2,\lambda_3$ specified by the \ttt{inequalities} cut out a cone from it by the conditions $\lambda_i(x)\ge 0$, $i=1,\dots,3$. The \ttt{grading} gives degree $1$ to every coordinate. The polynomial (counting the preimages of $x$ under a projection $\RR_+^{24}\to\RR_+^8$) is
$$
f(x)=\binom{x_1+5}{5}(x_2+1)(x_3+1)(x_4+1)(x_5+1)(x_6+1)(x_7+1)\binom{x_8+5}{5}.
$$
It is given in \ttt{CondorcetSymm.pnm} by

\begin{Verbatim}
1/120*(x[1]+5)*(x[1]+4)*(x[1]+3)*(x[1]+2)*(x[1]+1)*
(x[2]+1)*(x[3]+1)*(x[4]+1)*(x[5]+1)*(x[6]+1)*(x[7]+1)*
1/120*(x[8]+5)*(x[8]+4)*(x[8]+3)*(x[8]+2)*(x[8]+1)
\end{Verbatim}


From the Normaliz directory we invoke NmzIntegrate by

\begin{Verbatim}
nmzIntegrate -c example/CondorcetSymm
\end{Verbatim}

 (replace the slash by a backslash in MS Windows, and similarly
 below).
The file \ttt{CondorcetSymm.} \ttt{intOut} starts with the factorization:

\begin{Verbatim}
Factorization of polynomial:
x[8] +5  mult 1
x[8] +4  mult 1
...
x[1] +1  mult 1
Remaining factor 1/14400
\end{Verbatim}

Next we find the information on the Hilbert series:

\begin{Verbatim}
Generalized Ehrhart series:
1 5 133 363 ... 481 15 6
Common denominator of coefficients: 1
Series denominator with 24 factors:
1: 1  2: 14  4: 9
\end{Verbatim}

It is to be read as follows:
$$
H_{M,f}(t)=\frac{1+t^{}+5t^{1}+133t^{2}+363t^{3}+\dots+481t^{38}+15t^{39}+6t^{40}}{(1-t^1)(1-t^2)^{14}(1-t^4)^{9}}
$$
Next we find the presentation of $H_{M,f}(t)$ as a rational function with
coprime numerator and denominator (which in this case is the same as the
previous one, except that the denominator is factored differently):

\begin{Verbatim}
Generalized Ehrhart series with cyclotomic denominator:
1 5 133 363 ... 481 15 6
Common denominator of coefficients: 1
Series cyclotomic denominator:
1: 24  2: 23  4: 9
\end{Verbatim}

This means
$$
H_{M,f}(t)=\frac{1+t^{}+5t^{1}+133t^{2}+363t^{3}+\dots+481t^{38}+15t^{39}+6t^{40}}{\zeta_1\zeta_2^{23}\zeta_4^{9}}
$$
where $\zeta_i$ is the $i$-th cyclotomic polynomial. Now the quasipolynomial:


\begin{Verbatim}
Generalized Ehrhart quasi-polynomial of period 4:
 0:   6939597901822221635907747840000 20899225...000000 ... 56262656
 1:   2034750310223351797008092160000  7092764...648000 ... 56262656
 2:   6933081849299152199775682560000 20892455...168000 ... 56262656
 3:   2034750310223351797008092160000  7092764...648000 ... 56262656
with common denominator: 6939597901822221635907747840000
\end{Verbatim}

The left most column indicates the residue class modulo the period, and the
numbers in line $k$ are the coefficients of the $k$-th polynomial after
division by the common denominator. The list starts with $q_0^{(k)}$ and ends
with (the constant) $q_{23}^{(k)}$.
The interpretation of the remaining data is obvious:

\begin{Verbatim}
Degree of (quasi)polynomial: 23
Expected degree: 23
Virtual multiplicity: 1717/8192
\end{Verbatim}


Now suppose we want to work with the strict inequalities $\lambda_i(x)>0$, as
customary in voting theory (in order to exclude draws). Then we replace
\ttt{inequalities} by \ttt{excluded\_faces} to obtain the file
\ttt{CondorcetSmmSemi.in}. the polynomial hasn't changed, and so NmzIntegrate
is called by

\begin{Verbatim}
nmzIntegrate -c -F=CondorcetSymm example/CondorcetSymmSemi
\end{Verbatim}

The output file is now in \ttt{CondorcetSymmSemi.CondorcetSymm.intOut}.

\subsection{An integral}
The paper \cite{JMV} asks for the computation of the integral
$$
\int\limits_{\substack{[0,1]^m \\ \sum{x}= t}}(x_1\cdots x_{m})^{n-m}\prod_{1\le i<j \le m}(x_j-x_i)^2 \mathrm d{\mu}\
$$
taken over the intersection of the unit cube in $\RR^m$ and the hyperplane of constant coordinate sum $t$. It is supposed that $t\le m \le n$. We compute the integral for $t=2$, $m=4$ and $n=6$.

The polytope is specified in the input file \ttt{j462.in} (typeset in 2
columns):

\begin{Verbatim}
amb_space 5          -1 0 0 0 1   
inequalities 8       0 -1 0 0 1   
1 0 0 0 0            0 0 -1 0 1   
0 1 0 0 0            0 0 0 -1 1   
0 0 1 0 0            equations 1  
0 0 0 1 0            -1 -1 -1 -1 2
\end{Verbatim}

The $8$ inequalities describe the unit cube in $\RR^4$ by the inequalities  $0\le z_i\le 1$
and the equation gives the hyperplane $z_1+\dots+z_4=2$ (we must use homogenized coordinates!). There is no need to
specify the grading since Normaliz finds it because the polytope is a lattice
polytope. If one doesn't know this in advance, it is better to give the grading
explicitly by

\begin{Verbatim}
grading
unit_vector 5
\end{Verbatim}

See the Normaliz documentation, Section 3.2.5 how to define rational polytopes
by inequalities and equations.

The polynomial does not depend on $t$ so that we can use the same polynomial
for various $t$. It is contained in \ttt{j46.pnm}:

\begin{Verbatim}
(x[1]*x[2]*x[3]*x[4])^2*(x[1]-x[2])^2*(x[1]-x[3])^2*
(x[1]-x[4])^2*(x[2]-x[3])^2*(x[2]-x[4])^2*(x[3]-x[4])^2
\end{Verbatim}

NmzIntegrate is called by

\begin{Verbatim}
nmzIntegrate -cI -F=j46 example/j462
\end{Verbatim}

It produces the output in \ttt{j462.j46.intOut}:

\begin{Verbatim}
Factorization of polynomial:          x[1]  mult 2
x[4]  mult 2                          x[1] -x[2]  mult 2
x[3]  mult 2                          x[1] -x[3]  mult 2
x[3] -x[4]  mult 2                    x[1] -x[4]  mult 2
x[2]  mult 2                          Remaining factor 1
x[2] -x[3]  mult 2
x[2] -x[4]  mult 2                    Integral: 27773/29515186701000
\end{Verbatim}



\section{Distribution and installation}

The basic package (source, documentation, examples) for
NmzIntegrate is contained in the basic package of Normaliz
that you can download from
\medskip

\centerline{\url{https://normaliz.uos.de}}\medskip

The installation is described in the Normaliz documentation.

Likewise the executable of NmzIntegrate is contained in the
Normaliz executable package for your system.
Therefore NmzIntegrate does not need a separate installation.

\section{Compilation}\label{Comp}

Before the compilation of NmzIntegrate you must compile
Normaliz 3.1.1 and CoCoALib 0.99540 \cite{CoC} (not
contained in the Normaliz distribution).

First compile Normaliz including libnormaliz by running \ttt{make} in the source directory.
For the compilation of CoCoALib run

\centerline{\ttt{./configure -{}-threadsafe-hack}}

in the CoCoA root directory. The option \ttt{threadsafe-hack} is necessary to ensure correct parallel execution of nmzIntegrate.
If you want to use Normaliz inside CoCoA or CoCoALib also add

\centerline{\ttt{-{}-with-libnormaliz=/path/to/Normaliz3.0/source/libnormaliz/libnormaliz.a}}

to the configuration call, where the path to Normaliz has to be adjusted to your system. If the configuration was successful,

\centerline{\ttt{make library}}

will compile CoCoALib.

At last compile nmzIntegrate.
Navigate to the directory
\ttt{genEhrhart} and run \ttt{make}. You should move the
executable \ttt{nmzIntegrate} to the directory that contains
\ttt{normaliz}.

Depending on the location of CoCoALib, you may have to adjust
the path leading to it in the \ttt{Makefile} in
\ttt{genEhrhart}.

These instructions apply for Linux and Mac OS. If you should want to compile NmzIntegrate under MS Windows,
please contact the authors.



\section{Copyright and how to cite}

NmzIntegrate 1.1 is free software licensed under the GNU
General Public License, version 3. You can redistribute it
and/or modify it under the terms of the GNU General Public
License as published by the Free Software Foundation, either
version 3 of the License, or (at your option) any later
version.

It is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public
License along with the program. If not, see
http://www.gnu.org/licenses/.

Please refer to Normaliz in any publication for which
NmzIntegrate it has been used:
\begin{center}
	W. Bruns, B. Ichim, R. Sieg, T. Römer and C. Söger: Normaliz. Algorithms for
	rational cones and affine monoids. Available at
	\url{https://normaliz.uos.de}.
\end{center}
The corresponding \verb|\bibitem|:
\begin{Verbatim}
\bibitem W. Bruns, B. Ichim, R. Sieg, T. R\"omer and C. S\"oger:
Normaliz. Algorithms for rational cones and affine monoids.
Available at \url{https://normaliz.uos.de}.
\end{Verbatim}

A BibTeX entry:
\begin{Verbatim}
@Misc{Normaliz,
author = {W. Bruns and B. Ichim and R. Sieg and T. R\"omer and C. S\"oger},
title = Normaliz. Algorithms for rational cones and affine monoids,
howpublished ={Available at \url{https://normaliz.uos.de}.}
}
\end{Verbatim}

You can add a reference to \cite{BS} in order to indicate that
NmzIntegrate has been used.

\section{History}

\subsection{1.0 $\to$ 1.1}

\begin{enumerate}
\item NmzIntegrate can now be used on objects that do not
    have maximal dimension in their surrounding space.
\item NmzIntegrate calls Normaliz if input files are
    missing.
\item The input syntax for polynomials has been improved:
    white space is neglected.
\item The efficiency has been improved significantly by
    using integral arithmetic internally instead of
    rational arithmetic.
\end{enumerate}

\subsection{1.1 $\to$ 1.2}

\begin{enumerate}
\item Use of the (now existing) CoCoALib function for input of polynomials and
other small changes reflecting the development of CoCoALib.
\item Extension to semiopen cones.
\item Name of file with suffix \ttt{pnm} can be specified independently of the name of the
project.
\end{enumerate}

\subsection{1.2 $\to$ 1.3}

\begin{enumerate}
\item Adaptation to CoCoALib 0.99538.
\item Adaptation (of this manual) to Normaliz 3.0.

\end{enumerate}

\subsection{1.3 $\to$ 1.3.1}

\begin{enumerate}
\item Adaptation to CoCoALib 0.99540.
\item Changes implied by new features of Normaliz 3.1.1.

\end{enumerate}

\begin{thebibliography}{15.}

\bibitem{CoC} J. Abbott and A. Bigatti, \emph{CoCoALib}. A GPL
    C++ library for  doing Computations in Commutative Algebra.
    Available from \url{http://cocoa.dima.unige.it/cocoalib/}

\bibitem{BS} W. Bruns and C. Söger, \emph{Generalized Ehrhart
    series and integration in Normaliz}. J. Symb. Comp. 68 (2015) 75--86.

\bibitem{JMV} J. Jeffries, J. Montaño and M. Varbaro, \emph{Multiplicities of
classical varieties}.  Proc. Lond. Math. Soc. (3) 110 (2015), 1033--1055.


\end{thebibliography}


\end{document}
