\section{Affine monoid algebras and binomial ideals by examples}\label{AffMon}

The role of binomials in the computation of affine monoids and their algebras is briefly explained in Sections \ref{aff_mon_bin_id} and \ref{binomials}. We assume that the user is familiar with them.

\subsection{Computations for affine monoids}

\subsubsection{Input and default computation goals}\label{moninp_def}
Affine monoids are given to Normaliz by the input type 
\begin{itemize}
	\itemtt[monoid]
\end{itemize}
as in \verb|monoid.in|:
\begin{Verbatim}
amb_space 3
monoid 6
1 0 0
2 3 5
0 0 1
1 1 2
0 1 3
3 1 0
/* grading 1 -2 1*/
/*HilbertSeries*/
/*GroebnerBasis*/
/*Lex*/
/*MarkovBasis*/
/*gb_degree_bound 11*/
/*gb_min_degree 9*/
/*Multiplicity*/
/*SingularLocus*/
/*CodimSingularLocus*/
/*IsSerreR1*/
\end{Verbatim}
Positivity of the monoid does \emph{not} mean that all components of the input vectors are nonnegative. It only means that $x=0$ if both $x$ and $-x$ belong to it.

Let us translate this example into multiplicative notation. We have binomials in $K[X_1,X_2,X_3]$, namely 
$$
M_1 = X_1,\qquad M_2 = X_1^2X_2^3X_3^5,\dots, \qquad M_6 =X_1^3X_2.
$$

In the output file we see
\begin{Verbatim}
...
original monoid is not integrally closed in chosen lattice
...
6 Hilbert basis elements:
0 0 1
1 0 0
0 1 3
1 1 2
3 1 0
2 3 5

5 support hyperplanes:
0   0 1
0   1 0
1   0 0
2  -3 1
5 -15 7
\end{Verbatim}
The support hyperplanes re those of the cone generated by the monoid. They are used in auxiliary computations, for example in finding the Hilbert basis, i.e., the unique minimal system of generators of our monoid. In this case the input vectors are all in the Hilbert basis, but thins need not be the case. The Hilbert basis is ordered by degree and lexicographically within each degree. In fact, we have a grading
\begin{Verbatim}
grading:
1 1 1 
\end{Verbatim}
For the default choice of the grading we start from the standard grading on the ambient lattice. Then the grading, whether the default choice or an explicit grading in the input, is divided by the greatest common divisor of he degrees of the generators. In the context of monomial algebras it is the most natural choice. The division by the gcd can be suppressed by \verb|NoGradingDenom|. In our example the gcd is $1$.

Our monoid actually has another grading, in which all generators have degree $1$: \verb|grading 1 -2 1| in the input file. Activate it and study the changes.

\textbf{Note:}\enspace The input type \verb|monoid| is close to \verb|cone_and_lattice| if the monoid is normal.But there are two differences in the default choices: (1) The default computation goals and (2) the default grading. In fact, for \verb|monoid| is is derived from the standard grading on the ambient lattice, whereas or \verb|cone_and_lattice| it gives degree $1$ to the extreme integral generators, provided this is possible.

The input type \verb|monoid| allows fewer computation goals and options than \ttt{cone\_and\_lattice}. These are

\texttt{
\begin{tabular}{llll} 
HilbertBasis & HilbertSeries & IsIntegrallyClosed  &Multiplicity\\
Grading &   IsSerreR1 & HilbertQuasiPolynomial &  Automorphisms \\
 MarkovBasis & Representations & AmbientAutomorphisms & SingularLocus\\
GroebnerBasis &CodimSingularLocus  & InputAutomorphisms & Revlex \\
Lex & DegLex 
\end{tabular}
}

Automorphism groups of monoids are discussed in Section \ref{mon_auto}.



\subsubsection{Markov and Gröbner bases, Representations}\label{markov}
The purpose of the computations in this section is to understand the defining ideal of the subalgebra $A$ of $K[X_1,X_2,X_3]$ generated by our binomials $M_1,\dots,M_6$ introduced above. To this end we activate
\begin{itemize}
	\itemtt[MarkovBasis]
\end{itemize}
in \verb|monoid.in|, the Markov basis is computed and returned in the file with suffix 
\begin{itemize}
	\itemtt[mrk] file containing the Markov basis	
\end{itemize}
In our case \verb|monoid.mrk|:
\begin{Verbatim}
7
6
1 0 -1 -1 1 0 
-2 0 2 -1 0 1 
-1 0 1 -2 1 1 
2 1 0 -1 -1 -1 
0 0 0 -3 2 1 
1 1 1 -3 0 0 
0 1 2 -2 -1 0
\end{Verbatim}
Each column corresponds to an input vector, and the rows are indeed relations: the scalar product of a row listed in the Markov basis and a column of the matrix \verb|monoid| is $0$. The binomials in $P=K[Y_1,\dots,Y_6]$ corresponding to the rows in the Markov basis form a system of generators of the binomial ideal defining our monoid algebra as a residue class ring of $P$. The binomials are
$$
b_1 = Y_1Y_5 - Y_3Y_4, \qquad b_2 = Y_3^2Y_6 - Y_1^2Y_3,\dots,\qquad b_7 = Y_2Y_3^2 - Y_4^2Y_5.
$$
and indeed the binomials vanish if we substitute $M_i$ for $Y_i$, $i=1,\dots,7$. That they generate the defining ideal is claimed by Normaliz.

For easier reference the input matrix is mirrored in the file with suffix 
\begin{itemize}
	\itemtt[ogn] file with the original generators
\end{itemize}
in our case \verb|monoid.ogn|:
\begin{Verbatim}
6
3
1 0 0 
2 3 5 
0 0 1 
1 1 2 
0 1 3 
3 1 0
\end{Verbatim}

In order to compute a Gröbner basis of our binomial ideal, we activate
\begin{itemize}
	\itemtt[GroebnerBasis]
\end{itemize}
and get the output file with suffix
\begin{itemize}
	\itemtt[grb] containing the Gröbner basis.
\end{itemize}
For the Gröbner basis one has to choose a monomial order. The default choice is degree reverse lexicographic'' In our case it yields
\begin{Verbatim}
8
6
-1 0 1 1 -1 0 
0 0 0 3 -2 -1 
1 0 -1 2 -1 -1 
2 0 -2 1 0 -1 
0 1 2 -2 -1 0 
1 1 1 0 -2 -1 
2 1 0 -1 -1 -1 
3 0 -3 0 1 -1 
\end{Verbatim}
More precisely: the indeterminates in the polynomial ring housing the binomials are ordered $Y_1 > \dots Y_6$ and we take the degree reverse lexicographic extension, where`  degree'' means the total standard degree on the polynomial ring $P$. The file with suffix \verb|ogn| is also created for the Gröbner basis. There is no output of the (minimal) Markov basis, unless you ask for it explicitly. 

Despite of being the default choice, the degree reverse lexicographic order is in the list of pertaining computation goals:
\begin{itemize}
	\itemtt[RevLex] degree reverse lexicographic order (with respect to the standard grading on the polynomial ring)
	\itemtt[Lex] lexicographic order
	\itemtt[DegLex] degree lexicographic order (with the same degree as RevLex)
\end{itemize}
Activate also \verb|Lex| in our example and see what changes. \verb|DegLex| is taken with respect to the total standard degree as well, and makes no difference in our case, since the generating binomials are homogeneous in this grading. It is also possible to apply a weight vector specified by 
\begin{itemize}
	\itemtt[gb\_weight]
\end{itemize}
Its length is the number of variables of the binomial ideal. For the input type \verb|monoid| it is the number of input generators of the monoid. (For \verb|lattice_ideal| and  \verb|toric_ideal| it is \verb|amb_space; see below.|) Monomials of equal weight must be distinguished by a monomial order that serves as a tie breaker. The choices are \verb|RevLex| (default) or \verb|Lex|. (\verb|DegLex| has a fixed weight namely the standard grading.) Note that the entries of the weight vector must be positive if \verb|RevLex| is the tie breaker, and nonnegative for \verb|Lex|. An example (\verb|monoid_weight.in|):
\begin{Verbatim}
amb_space 3
monoid 6
1 0 0
...
3 1 0
GroebnerBasis
gb_weight
1 2 3 4 5 6
\end{Verbatim}
and the Gröbner basis is
\begin{Verbatim}
9
6
-1 0 1 1 -1 0 
-1 -1 -1 3 0 0 
-2 0 2 -1 0 1 
0 -1 -2 2 1 0 
-1 0 1 -2 1 1 
-2 -1 0 1 1 1 
1 -1 -3 1 2 0 
-1 -1 -1 0 2 1 
2 -1 -4 0 3 0
\end{Verbatim}

\textbf{Warning:} \enspace Don't confuse \verb|grading| and \verb|gb_weight|. The binomials must be homogeneous polynomials for the grading so that the grading has no effect on picking the initial monomial. Therefore a grading (or homogeneous weight) has no effect on the Grobner basis computation.

A grading of the monomial algebra induces a grading on the binomials in its defining ideal such that the latter are homogeneous polynomials. With respect to this grading  the output of Markov and Gröbner bases can be restricted:
\begin{itemize}
	\itemtt[gb\_degree\_bound <n>] sets upper degree bound \verb|<n>| for binomials,
	\itemtt[gb\_min\_degree <n>] sets lower degree bound  \verb|<n>| for binomials. 
\end{itemize}

There is one more computation goal for monoids that complements \verb|HilbertBasis| (switched on by default):
\begin{itemize}
	\itemtt[Representations] representations of reducible elements in \verb|monoid| in terms of the Hilbert basis
\end{itemize}
The output is a list of binomials in the file with suffix
\begin{itemize}
	\itemtt[rep] representations  of reducible elements in terms of the Hilbert basis.
\end{itemize}
Also the file with suffix \verb|ogn| is written.

As a simple example we consider \verb|representations.in|
\begin{Verbatim}
amb_space 3
monoid 8
1 0 0
2 3 5
0 1 1
0 0 1
1 1 2
0 1 3
3 1 0
1 2 5
Representations
/*BinomialsPacked*/
\end{Verbatim}
with
\begin{Verbatim}
4 Hilbert basis elements:
0 0 1
1 0 0
0 1 1
3 1 0
\end{Verbatim}
and representations of the other $4$ elements in the input:
\begin{Verbatim}
4
8
-1 0 -1 -1 1 0 0 0 
0 0 -1 -2 0 1 0 0 
-1 0 -2 -3 0 0 0 1 
-2 1 -3 -2 0 0 0 0
\end{Verbatim}
The entries $1$ in each row mark the reducible elements and the row should be read as a binomial vanishing on the input vectors (or monomials).

If you want to see computations that take longer than our toy example so far, run \verb|A443monoid.in| and \verb|Kwak80.in|.


\subsubsection{Hilbert series and multiplicity}

If we activate both (!) \verb|HilbertSeries| and \verb|Multiplicity| in \verb|monoid.in|, the result is
\begin{Verbatim}
multiplicity = 19/40
multiplicity (float) = 0.475

Hilbert series:
1 1 0 0 3 2 -2 -1 6 2 -4 0 6 1 -3 1 4 0 0 1 1 
denominator with 3 factors:
1:1  2:1  20:1 
... 
\end{Verbatim}
followed by the representation with cyclotomic denominator and the Hilbert quasipolynomial.Activate \verb|grading 1 -2 1| and observe the changes.



\subsubsection{Binomial ideals from cone input}

Defining binomial ideals can be computed not only for monoids defined by the input type \verb|monoid|, but also for the monoids that defined by other input types as intersections of cones and lattices, for example \verb|cone|, \verb|cone_and_lattice|, \verb|equations|, \verb|inequalities| etc.In the case of generator input there are actually two monoids, the ``original monoid'' as discussed in Section \ref{MinMod}, and its integral closure in the lattice defined by the input. So, if we ask for the Markov basis of the defining ideal, which monoid is taken? Answer: always the integral closure generated by its Hilbert basis, unless the property makes only sense for the original monoid: if we ask \verb|IsIntegrallyClosed|, the answer is always `yes''  for the integral closure.

As an example we take \verb|cone_latt_markov.in| (\verb|monoid.in| with a different input type):
\begin{Verbatim}
amb_space 3
cone_and_lattice 6
1 0 0
2 3 5
0 0 1
1 1 2
0 1 3
3 1 0
MarkovBasis
SingularLocus
\end{Verbatim}

The output file contains
\begin{Verbatim}
original monoid is not integrally closed in chosen lattice
...
codim singular locus = 2
18 Markov basis elements

***********************************************************************

9 lattice points in polytope (Hilbert basis elements of degree 1):
0 0 1
0 1 3
1 0 0
1 1 2
1 2 4
2 1 1
2 2 3
2 3 5
3 1 0

0 further Hilbert basis elements of higher degree:
\end{Verbatim}
The Markov basis is contained in \verb|cone_latt_markov.mrk|:
\begin{Verbatim}
18
9
-1 0 1 0 0 1 0 0 -1 
0 0 0 -1 0 2 0 0 -1 
...
0 -1 0 0 2 0 0 -1 0 
\end{Verbatim}
\emph{The columns correspond to the Hilbert basis elements in the order they are listed above.} For completeness the file with suffix \verb|ogn| is written also in this case. It contains the Hilbert basis as listed in the \verb|out| file.

The singular locus has codimension $2$, the minimum for a normal monoid (algebra). The singular locus is stored in \verb|cone_latt_markov.sng|.

We could equally well start from the inequalities defining the integral closure (the generators above generate the lattice $\RR^3$) in \verb|cone_latt_markov_supp.in|,
\begin{Verbatim}
amb_space 3
inequalities 5
0   0 1
0   1 0
1   0 0
2  -3 1
5 -15 7
MarkovBasis
SingularLocus
\end{Verbatim}
with the same result as above, except that there is no original monoid.

Since the number of monoid generators is impossible to predict for cone input, it is not possible to give a weight vector.

\subsection{Monoids from binomials}\label{binom_ex}

As an example, we consider the binomial ideal generated by
$$
Y_1^2Y_2-Y_4Y_5Y_6,\ \ Y_1Y_4^2-Y_3Y_5Y_6,\ \ Y_1Y_2Y_3-Y_5^2Y_6.
$$
in the polynomial ring $P=K[Y_1,\dots, Y_6]$. We want to find an embedding of the toric ring it defines. When we say ``defines'', then we do not claim that the residue ring  $P/I$ is a toric ring. But there is a unique smallest binomial ideal $J\supset I$ with this property, and Normaliz finds the monoid and, if wanted, also a Markov (or Gröbner) basis of $J$. A priori $R=P/J$ is only defined as a residue class ring. It doesn't have a ``canonical'' embedding into another polynomial ring, but Normaliz computes such an embedding if the monoid underlying $R/J$ is positive. As pointed out already, non-positive affine monoids an only be computed by Normaliz if they are normal.

\subsubsection{Affine monoids from binomial ideals}\label{toric_ideal}
The input type that asks for a toric ring from binomial input is
\begin{itemize}
	\itemtt[toric\_ideal]
\end{itemize}
The input vectors are obtained as the differences of the two exponent vectors in the binomials. So the input ideal \verb+toric_ideal.in+ for our $3$ binomials is
\begin{Verbatim}
amb_space 6
toric_ideal 3
2 1  0 -1 -1  -1
1 0 -1  2 -1  -1
1 1  1  0 -2  -1
/* total_degree */
\end{Verbatim}
In order to avoid special input rules for this case in which our object is not defined as a subset of an ambient space, but as a quotient of type \emph{generators/relations}, we abuse the name \verb|amb_space|: it determines the space in which the input vectors live.

It is possible to define a \verb|grading|. It must give positive degree to the unit vectors of the ambient space and degree $0$ to the vectors representing the binomials so that the latter become homogeneous polynomials with respect to this grading.

In the output we get
\begin{Verbatim}
6 original generators:
1 0 0
2 3 5
0 0 1
1 1 2
0 1 3
3 1 0
\end{Verbatim}
namely the residue classes of the indeterminates realized in an embedding. Test the binomials on the original generators! We know this monoid already from \verb|monid.in|, and you can try the other computation goals discussed for the latter.

We see
\begin{Verbatim}
grading:
1 1 1 
\end{Verbatim}
So Normaliz uses the standard grading on the ambient polynomial ring into which $R/J$ has been embedded. This is the default choice, as it is for the input type \verb|monoid|. Our toric ring actually has its own standard grading: activate \verb|total_degree| in the input file and look at the output. In fact, the binomials above are homogeneous in the standard gadding on $P$, and \verb|total_degree| sets this grading.

The generators are repeated (in this case) in a different order,m as we know already:
\begin{Verbatim}
6 Hilbert basis elements:
0 0 1
1 0 0
0 1 3
1 1 2
3 1 0
2 3 5
\end{Verbatim}
Now they are sorted by degree and then lexicographically, as we always sort Hilbert bases.

As a trivial example in which the Hilbert basis does not simply repeat the original generators in a different order, compute \verb|lin_bin.in|:
\begin{Verbatim}
amb_space 2
toric_ideal 1
1 -1
\end{Verbatim}
The output contains
\begin{Verbatim}
2 original generators:
1
1

1 Hilbert basis elements:
1
\end{Verbatim}

Normaliz transforms \verb|toric_ideal| into \verb|monoid|. Therefore only the computation goals of \verb|monoid| are allowed with the exception of \verb|AmbientAutomorphisms| and \verb|InputAutomorphisms|.

A weight vector for a Gröbner basis computation can be given. Its number of components is \verb|amb_space|. Example (\verb|toric_ideal_grb|):
\begin{Verbatim}
amb_space 6
toric_ideal 3
2 1  0 -1 -1  -1
1 0 -1  2 -1  -1
1 1  1  0 -2  -1
total_degree
GroebnerBasis
gb_weight
1 2 3 4 5 6
Lex
\end{Verbatim}
and the Gröbner basis is the same as for \verb|monoid_weight.in|

\subsubsection{Normalization of monoids from binomials}\label{normal_toric_ideal}

One go can a step further, using the input type
\begin{itemize}
	\itemtt[normal\_toric\_ideal]
\end{itemize}
It asks for the \emph{normalization} of the toric ring defined by the binomials. In \verb|normal_toric_ideal.in| we take the same binomials  as above:
\begin{Verbatim}
amb_space 6
normal_toric_ideal 3
2 1  0 -1 -1  -1
1 0 -1  2 -1  -1
1 1  1  0 -2  -1
\end{Verbatim}
In the output file we find
\begin{Verbatim}
6 original generators:
1 0 0
2 3 5
0 0 1
1 1 2
0 1 3
3 1 0

2 lattice points in polytope (Hilbert basis elements of degree 1):
0 0 1
1 0 0

7 further Hilbert basis elements of higher degree:
0 1 3
1 1 2
2 1 1
3 1 0
1 2 4
2 2 3
2 3 5
\end{Verbatim}
The ``original generators" are the same as above, as they should be. Also the default grading is the same, and the default computation goals are identical as well. But the Hilbert series, Markov basis, Gröbner basis etc. are computed for the normalization, as the user can see by playing with the commented out computation goals. A weight vector for the Gröbner basis is not allowed since the generators of the normalization are not predictable.

\textbf{Note:}\enspace Until version 3.9.4 the input type \verb|normal_toric_ideal| was called \verb|lattice_ideal|, which has a different meaning now and is discussed in the next subsection.

\verb|normal_toric_ideal| is transformed into \verb|cone_and_lattice|. Thus all computation goals and options of \verb|cone_and_lattice| can be used with the exception of \verb|AmbientAutomorphisms| and \verb|InputAutomorphisms|.

\subsection{Lattice ideals}\label{lattice_ideal}

A lattice ideal $I$ in a polynomial ring $P$ is a binomial ideal modulo which all monomials are nonzerodivisors. This implies that $P/J$ is a monoid ring whose underlying monoid is the natural image of the monoid of monomials in $P$. Moreover, it is a cancellative monoid, but not necessarily affine---the latter property requires torsion freeness additionally. The input type is
\begin{itemize}
	\itemtt[lattice\_ideal] 
\end{itemize}
Normaliz tests whether the lattice ideal is toric and indicates it in the input file, but does not automatically treat the input like \verb|toric_ideal| in the positive case.

A simple example of a non-toric lattice ideal is \verb|non_toric.in|
\begin{Verbatim}
amb_space 4
lattice_ideal 4
2 -2 0 0
1 1 -1 -1
2 -1 1 -2
-1 -1 1 -1
/*GroebnerBasis
DegLex*/
\end{Verbatim}
The default computation goal is \verb|MarkovBsis|. In our case the result is
\begin{Verbatim}
4
4
-4 -1 1 0 
-3 0 0 1 
-2 2 0 0 
6 0 0 0
\end{Verbatim}
Attention: the last binomial is $x_1^6-1$ so that the residue class of $x_1$ is a torsion element in the monoid of residue classes.

For internal reasons and the exchange of data with external programs we can ask
\begin{itemize}
 \itemtt[IsLatticeIdealToric]
\end{itemize}

In addition to \verb|MarkovBasis| nd \verb|IsLatticeIdealToric| there is only one more allowed computation goal, namely \verb|GroebnerBasis|. There are no monoid generators for \verb|lattice_ideal| (not even if the ideal is toric).

\textbf{Note:} In versions until 3.9.4 \verb|lattice_ideal| had the meaning of \verb|normal_toric_ideal|.