% !TeX spellcheck = en_US

\section{Introduction}\label{facil}

\subsection{The objectives of Normaliz}

The program Normaliz is a tool for computing
the Hilbert bases and enumerative data of rational cones and, more generally, sets of lattice points in rational polyhedra. Moreover, Normaliz computes algebraic polyhedra, i.e., polyhedra defined over algebraic number fields embedded into $\RR$.

Since version 3.10.0 Normaliz can also compute data of general affine monoids: their minimal systems of generators, Hilbert series, Markov and Gröbner bases of defining ideals and some local data, such as the singular locus.

The mathematical background and the terminology of this manual are explained in Appendix~\ref{AppBackground}. For a thorough treatment of the mathematics involved we refer the reader to~\cite{BG}.
The terminology follows~\cite{BG}. For
algorithms of Normaliz see \cite{BruAuto}, \cite{BruVol}, \cite{BHIKS}, \cite{BI}, \cite{BI2},
\cite{BIS}, \cite{BK02}, \cite{BSS}, and~\cite{BS}. Some new developments are briefly explained in this manual.

Both polyhedra and lattices can be given by
\begin{arab}
	\item systems of generators and/or
	\item constraints.
\end{arab}
Since version~3.1, cones need not be pointed and polyhedra need not have vertices, but are allowed to contain a positive-dimensional affine subspace.

Affine monoids can be defined by generators and by toric ideals, in other words, by binomial equations.

In order to describe a rational polyhedron by \emph{generators}, one specifies a finite set of vertices $x_1,\dots,x_n\in\QQ^d$ and a set $y_1,\dots,y_m\in\ZZ^d$ generating a rational cone $C$. The polyhedron defined by these generators is
$$
P=\conv(x_1,\dots,x_n)+C,\qquad C=\RR_+y_1+\dots+\RR_+y_m.
$$
An affine lattice defined by generators is a subset of $\ZZ^d$ given as
$$
L=w+L_0,\qquad L_0=\ZZ z_1+\dots+\ZZ z_r, \qquad w,z_1,\dots,z_r\in \ZZ^d.
$$
\emph{Constraints} defining a polyhedron are affine-linear inequalities with integral coefficients, and the constraints for an affine lattice are affine-linear diophantine equations and congruences. The conversion between generators and constraints is an important task of Normaliz.


The first main goal of Normaliz is to compute a system of generators for
$$
P\cap L.
$$
The minimal system of generators of the monoid $M=C\cap L_0$ is the Hilbert basis $\Hilb(M)$ of $M$. The homogeneous case, in which $P=C$ and $L=L_0$, is undoubtedly the most important one, and in this case $\Hilb(M)$ is the system of generators to be computed. In the general case the system of generators consists of $\Hilb(M)$ and finitely many points $u_1,\dots,u_s\in P\cap L$ such that
$$
P\cap L=\bigcup_{j=1}^s u_j+M.
$$

The second main goal are enumerative data that depend on a grading
of the ambient lattice. Normaliz computes the Hilbert series and
the Hilbert quasipolynomial of the monoid or set of lattice points in a polyhedron. In combinatorial terminology: Normaliz computes Ehrhart series and quasipolynomials of rational polyhedra. Normaliz also computes weighted
Ehrhart series and Lebesgue integrals of polynomials over
rational polytopes.

For algebraic polyhedra Normaliz realizes the computation goals above that make sense without the finite generation of the monoid of lattice points in a cone: convex hull and vertex enumeration for all algebraic polyhedra, and, for polytopes, lattice points, volumes and triangulations.

Lattice points in polytopes can be constrained by polynomial equations and inequalities. This necessary for fusion rings for which Normaliz provides input types and special computation goals.

The computation goals of Normaliz can be set by the user. In particular, they can be restricted to subtasks, such as the lattice points in a polytope or the leading coefficient of the Hilbert (quasi)polynomial.

Performance data of Normaliz can be found in~\cite{BruVol}, \cite{BI2}, \cite{BIS} and~\cite{BIS2}.

\emph{Acknowledgment.}\enspace In~2013--2016 the development of Normaliz has been supported by the DFG SPP~1489 ``Algorithmische und experimentelle Methoden in Algebra, Geometrie und Zahlentheorie''. From November~2020 to October~2021 Normaliz was supported by the DFG~project ``Normaliz: development and long term sustainability''.

\subsection{Platforms, implementation and access from other systems}

Executables for Normaliz are provided for Mac~OS, Linux and MS~Windows. If the executables prepared cannot be run on your system, then you can compile Normaliz yourself (see Section~\ref{Compile}). The statically linked Linux binaries provided by us can be run in the Linux subsystem of MS~Windows~10. A Docker image of Normaliz is available.

Normaliz is written in C++, and should be compilable on every system that has a GCC compatible compiler. It uses the standard package GMP (see Section~\ref{Compile}). The parallelization is based on OpenMP. CoCoALib~\cite{CoCoA}, Flint~\cite{Flint} and HashLibrary \cite{has} are optional packages. The computation of algebraic polytopes is based on e-antic~\cite{e-antic}.

Normaliz consists of two parts: the front end ``normaliz'' for input and output and the C++ library ``libnormaliz'' that does the computations.

Normaliz can be accessed from the interactive general purpose system \textsc{Python} via the interface \textsc{PyNormaliz} written by Sebastian Gutsche, with contributions by Winfried Bruns, wJustin Shenk and Richard Sieg.

Normaliz can also be accessed from the following systems:
\begin{itemize}
	\item \textsc{Singular} via the library \ttt{normaliz.lib},
	\item \textsc{Macaulay2} via the package \ttt{Normaliz.m2},
	\item \textsc{CoCoA} via an external library and libnormaliz,
	\item \textsc{GAP} via the GAP package \textsc{NormalizInterface}~\cite{GAP-NmzInterface} which uses libnormaliz,
	\item \textsc{polymake} (thanks to the \textsc{polymake}
	team),
	\item \textsc{SageMath} via PyNormaliz.
\end{itemize}

The Singular and Macaulay2 interfaces are contained in the
Normaliz distribution. At present, their functionality is limited to Normaliz~2.10. Nevertheless they profit from newer versions.

Furthermore, Normaliz is used by B.~Burton's system
\textsc{Regina} and in \textsc{SecDec} by S.~Borowka et~al.

Normaliz does not have its own interactive shell. We recommend the access via PyNormaliz, GAP or SageMath for interactive use. \textsc{PyNormaliz} is documented in Appendix~\ref{PyNormaliz}.


\subsection{Major changes relative since version~3.10.0}


In 3.10.0:

\begin{arab}
	\item Improvements in patching algorithm with polynomoial equations.
	\item Input types \verb|monoid|, \verb|lattice_ideal| (changed), \verb|toric_ideal|, \verb|normal_toric_ideal|.
	\item  Markov and Gröbnber bases of lattice ideals.
	\item Hilbert series for all positive affine monoids.
	\item Computation of the singular locus.
\end{arab}

In 3.10.1:

\begin{arab}
	\item Weight vector for Gröbner bases of lattice ideals.
	\item Substantial improvements in the patching variant of project-and-lift.
	\item Time bound can be set (so far only in project-and-lift).
	\item Option NoOutputOnInterrupt. 
\end{arab}

In 3.10.2:

\begin{arab}
	\item Extensive improvements of the patching variant of project-and-lift, algorithms and HPC management.
	\item Computations of fusion rings based only on type and duality.
	\item Processing lists of input files.
	\item Orbit versions of (dual) face lattice and f-vector.
\end{arab}

In 3.10.3:

\begin{arab}
	\item computation goals \verb*|SingleFusionRing| and \verb*|ModularGradings|.
	\item Algorithmic variant \verb*|UseModularGrading|.
\end{arab}

In 3.10.4:

\begin{arab}
	\item Computation goal InductionMatrices for fuasion rings.
	\item Ring homomorphiams dereived from induction matrices.
	\item Directive \verb*|no_coord_transf|.
\end{arab}

In 3.10.5:

\begin{arab}
	\item  bugfix in minimization of Markov bases with degree bound.
	\item \verb*|ExploitAutomsVectors| activated.
	\item \verb*|NoQuasiPolynomial| and \verb*|OnlyCyclotomicHilbSer| introduced.
	\item Better transfer of options for Hilbert series of monoids and symmetrization.
	\item Induction matrices for noncommutative fusion rings of rank $\le 8$.
\end{arab}

In 3.11.0:

\begin{arab}
	\item Better choice of linear forms for support hyperplanes in cases of nonuniqueness.
	\item Extended effect of \verb*|NoLLL|.
	\item Introduction of \verb*|BoolOptions| for \verb*|Cone| in libnormaliz.
	\item Bug fixes related to subdivision in the primal algorithm. 
\end{arab}

In 3.11.1:

\begin{arab}
	\item Induction matrices also for non-integral fusion rings.
	item  Complete change to integer computations for non-integral fusion nrings.
	\item  Internal improvements.
\end{arab}
See the file \verb|CHANGELOG| in the Normaliz directory for more information on the history of Normaliz.


\subsection{Future extensions}

\begin{arab}
	\item Exploitation of automorphism groups,
	\item addition of linear programming methods,
	\item multigraded Hilbert series,
	\item access from further systems,
	\item heterogeneous parallelization.
\end{arab}

\subsection{Download and installation}

In order to install Normaliz you should have a look at
\begin{center}
	\url{https://normaliz.uos.de/download/}.
\end{center}
It guides you to our GitHub repository
\begin{center}
	\url{https://github.com/Normaliz/Normaliz/releases}.
\end{center}
There you will also find binary releases for Linux, Mac~OS and MS~Windows. Unzip the package for your system in a directory of your choice. In it, a
directory \ttt{\NmzDir} (called Normaliz directory in the
following) is created with several subdirectories.

Another source for the executables of all three systems is the package manager Conda. See
\begin{center}
	\url{https://github.com/conda-forge/normaliz-feedstock}
\end{center}


An alternative to the (system dependent) executable is the
\begin{center}
	Docker image\qquad \verb|normaliz/normaliz|
\end{center}
that is automatically downloaded from the Docker repository if you ask for it. (In the Docker container, the Normaliz directory is called \verb|Normaliz|, independently of the version number.)

See Section~\ref{Distr} for more details on the distribution and the Docker image.

A source package is available as well. See Section~\ref{Compile} if you want to compile Normaliz yourself.
%\newpage

\subsection{Exploring Normaliz online}

You can explore Normaliz online at
\begin{center}
	\url{https://mybinder.org/v2/gh/Normaliz/NormalizJupyter/master}.
\end{center}
(may take a while.) The button ``New'' offers you a terminal. Choose it, and you will be in a Docker container based on the Normaliz Docker image. Your username is \verb|norm|, and Normaliz is contained in the subdirectory \verb|Normaliz| of your home directory. Moreover, it is installed, and can be invoked by the command \verb|normaliz| from anywhere. Just type
\begin{Verbatim}
normaliz -c Normaliz/example/rational
\end{Verbatim}
to run a small computation. You van also have a Python shell and run PyNormaliz or study the tutorial of PyNormaliz (a Jupyter notebook).

It is possible to upload and download files, but please refrain from using Binder as a platform for heavy computations.