% generated by GAPDoc2LaTeX from XML source (Frank Luebeck)
\documentclass[a4paper,11pt]{report}

\usepackage{a4wide}
\sloppy
\pagestyle{myheadings}
\usepackage{amssymb}
\usepackage[latin1]{inputenc}
\usepackage{makeidx}
\makeindex
\usepackage{color}
\definecolor{FireBrick}{rgb}{0.5812,0.0074,0.0083}
\definecolor{RoyalBlue}{rgb}{0.0236,0.0894,0.6179}
\definecolor{RoyalGreen}{rgb}{0.0236,0.6179,0.0894}
\definecolor{RoyalRed}{rgb}{0.6179,0.0236,0.0894}
\definecolor{LightBlue}{rgb}{0.8544,0.9511,1.0000}
\definecolor{Black}{rgb}{0.0,0.0,0.0}

\definecolor{linkColor}{rgb}{0.0,0.0,0.554}
\definecolor{citeColor}{rgb}{0.0,0.0,0.554}
\definecolor{fileColor}{rgb}{0.0,0.0,0.554}
\definecolor{urlColor}{rgb}{0.0,0.0,0.554}
\definecolor{promptColor}{rgb}{0.0,0.0,0.589}
\definecolor{brkpromptColor}{rgb}{0.589,0.0,0.0}
\definecolor{gapinputColor}{rgb}{0.589,0.0,0.0}
\definecolor{gapoutputColor}{rgb}{0.0,0.0,0.0}

%%  for a long time these were red and blue by default,
%%  now black, but keep variables to overwrite
\definecolor{FuncColor}{rgb}{0.0,0.0,0.0}
%% strange name because of pdflatex bug:
\definecolor{Chapter }{rgb}{0.0,0.0,0.0}
\definecolor{DarkOlive}{rgb}{0.1047,0.2412,0.0064}


\usepackage{fancyvrb}

\usepackage{mathptmx,helvet}
\usepackage[T1]{fontenc}
\usepackage{textcomp}


\usepackage[
            pdftex=true,
            bookmarks=true,        
            a4paper=true,
            pdftitle={Written with GAPDoc},
            pdfcreator={LaTeX with hyperref package / GAPDoc},
            colorlinks=true,
            backref=page,
            breaklinks=true,
            linkcolor=linkColor,
            citecolor=citeColor,
            filecolor=fileColor,
            urlcolor=urlColor,
            pdfpagemode={UseNone}, 
           ]{hyperref}

\newcommand{\maintitlesize}{\fontsize{50}{55}\selectfont}

% write page numbers to a .pnr log file for online help
\newwrite\pagenrlog
\immediate\openout\pagenrlog =\jobname.pnr
\immediate\write\pagenrlog{PAGENRS := [}
\newcommand{\logpage}[1]{\protect\write\pagenrlog{#1, \thepage,}}
%% were never documented, give conflicts with some additional packages

\newcommand{\GAP}{\textsf{GAP}}

%% nicer description environments, allows long labels
\usepackage{enumitem}
\setdescription{style=nextline}

%% depth of toc
\setcounter{tocdepth}{1}





%% command for ColorPrompt style examples
\newcommand{\gapprompt}[1]{\color{promptColor}{\bfseries #1}}
\newcommand{\gapbrkprompt}[1]{\color{brkpromptColor}{\bfseries #1}}
\newcommand{\gapinput}[1]{\color{gapinputColor}{#1}}


\begin{document}

\logpage{[ 0, 0, 0 ]}
\begin{titlepage}
\mbox{}\vfill

\begin{center}{\maintitlesize \textbf{\textsf{singular}\mbox{}}}\\
\vfill

\hypersetup{pdftitle=\textsf{singular}}
\markright{\scriptsize \mbox{}\hfill \textsf{singular} \hfill\mbox{}}
{\Huge \textbf{the \textsf{GAP} interface to \textsf{Singular}\mbox{}}}\\
\vfill

{\Huge Version 12.04.28\mbox{}}\\[1cm]
{28 April 2012\mbox{}}\\[1cm]
\mbox{}\\[2cm]
{\Large \textbf{Marco Costantini   \mbox{}}}\\
{\Large \textbf{Willem A. de Graaf   \mbox{}}}\\
\hypersetup{pdfauthor=Marco Costantini   ; Willem A. de Graaf   }
\end{center}\vfill

\mbox{}\\
{\mbox{}\\
\small \noindent \textbf{Marco Costantini   }  Email: \href{mailto://costanti@science.unitn.it} {\texttt{costanti@science.unitn.it}}\\
  Homepage: \href{http://www-math.science.unitn.it/~costanti/} {\texttt{http://www-math.science.unitn.it/\texttt{\symbol{126}}costanti/}}}\\
{\mbox{}\\
\small \noindent \textbf{Willem A. de Graaf   }  Email: \href{mailto://degraaf@science.unitn.it} {\texttt{degraaf@science.unitn.it}}\\
  Homepage: \href{http://www.science.unitn.it/~degraaf/} {\texttt{http://www.science.unitn.it/\texttt{\symbol{126}}degraaf/}}}\\
\end{titlepage}

\newpage\setcounter{page}{2}
{\small 
\section*{Copyright}
\logpage{[ 0, 0, 1 ]}
{\copyright} 2003, 2004, 2005, 2006 Marco Costantini and Willem A. de Graaf \mbox{}}\\[1cm]
\newpage

\def\contentsname{Contents\logpage{[ 0, 0, 2 ]}}

\tableofcontents
\newpage

 
\chapter{\textcolor{Chapter }{\textsf{singular}: the \textsf{GAP} interface to \textsf{Singular}}}\logpage{[ 1, 0, 0 ]}
\hyperdef{L}{X7D18BDD17A88ED33}{}
{
  
\section{\textcolor{Chapter }{Introduction}}\label{Introduction}
\logpage{[ 1, 1, 0 ]}
\hyperdef{L}{X7DFB63A97E67C0A1}{}
{
  This is the manual of the \textsf{GAP} package ``\textsf{singular}'' that provides an interface from the \textsf{GAP} computer algebra system to the \textsf{Singular} computer algebra system. 

 This package allows the \textsf{GAP} user to access functions of \textsf{Singular} from within \textsf{GAP}, and to apply these functions to the \textsf{GAP} objects. With this package, the user keeps working with \textsf{GAP} and, if he needs a function of \textsf{Singular} that is not present in \textsf{GAP}, he can use this function via the interface; see the function \texttt{SingularInterface} (\ref{SingularInterface}). 

 This package provides also a function that computes Groebner bases of ideals
in polynomial rings of \textsf{GAP}. This function uses the \textsf{Singular} implementation, which is very fast; see the function \texttt{GroebnerBasis} (\ref{GroebnerBasis}). 

 The interface is expected to work with every version of \textsf{GAP} 4, every (not very old) version of \textsf{Singular}, and on every platform, on which both \textsf{GAP} and \textsf{Singular} run; see paragraph \ref{platforms} for details. 

 If you have used this package in the preparation of a paper please cite it as
described in \href{http://www.gap-system.org/Contacts/cite.html} {\texttt{http://www.gap-system.org/Contacts/cite.html}}. 

 If \textsf{GAP}, \textsf{Singular}, and the \textsf{GAP} package \textsf{singular} are already installed and working on his computer, the user of this interface
needs to read only the subsection \texttt{sing{\textunderscore}exec} (\ref{singexec}), the section \ref{Interaction}, and in case of problems the subsection \ref{common}.  
\subsection{\textcolor{Chapter }{Package evolution}}\logpage{[ 1, 1, 1 ]}
\hyperdef{L}{X7FE24D6E8258CC49}{}
{
  The work for the package \textsf{singular} has been started by Willem de Graaf, that planned this package as an interface
to the function of \textsf{Singular} that calculates the Groebner bases. To this purpose, Willem de Graaf wrote the
code for the conversion of rings and ideals from \textsf{GAP} to \textsf{Singular}, and the code for the conversion of numbers and polynomials in both
directions. 

 Marco Costantini has widened the aim of the package, in order to make it a
general interface to each possible function of \textsf{Singular}: with the function \texttt{SingularInterface} (\ref{SingularInterface}) it is possible to use from within \textsf{GAP} any function of \textsf{Singular}, including user-defined ones and future implementations. To this purpose,
Marco Costantini has generalized the previous code for the conversion of
objects in the new more general context, has written the code for the
conversion of the various other types of objects, and has written the code for
the low-level communication between \textsf{GAP} and \textsf{Singular}. 

 David Joyner has developed the code for the algebraic-geometric codes
functions, and has written the corresponding section \ref{AlgebraicGeometricCodes} of this manual. 

 Gema M. Diaz has helped with some testing and reports. }

 
\subsection{\textcolor{Chapter }{The system \textsf{Singular}}}\logpage{[ 1, 1, 2 ]}
\hyperdef{L}{X7EA60A8284C4635B}{}
{
  \textsf{Singular} is ``A Computer Algebra System for Polynomial Computations'' developed by G.-M. Greuel, G. Pfister, and H. Sch\texttt{\symbol{92}}"onemann,
at Centre for Computer Algebra, University of Kaiserslautern. The authors of
the \textsf{GAP} package \textsf{singular} are not involved in the development of the system \textsf{Singular}, and vice versa. 

 \textsf{Singular} is not included in this package, and can be obtained for free from \href{http://www.singular.uni-kl.de} {\texttt{http://www.singular.uni-kl.de}}. There, one can find also its documentation, installing instructions, the
source code if wanted, and support if needed. \textsf{Singular} is available for several platforms. 

 A description of \textsf{Singular}, copied from its manual (paragraph ``2.1 Background''), version 2-0-5, is the
following: 

 `` \textsf{Singular} is a Computer Algebra system for polynomial computations with emphasis on the
special needs of commutative algebra, algebraic geometry, and singularity
theory. 

 \textsf{Singular}'s main computational objects are ideals and modules over a large variety of
baserings. The baserings are polynomial rings or localizations thereof over a
field (e.g., finite fields, the rationals, floats, algebraic extensions,
transcendental extensions) or quotient rings with respect to an ideal. 

 \textsf{Singular} features one of the fastest and most general implementations of various
algorithms for computing Groebner resp. standard bases. The implementation
includes Buchberger's algorithm (if the ordering is a well ordering) and
Mora's algorithm (if the ordering is a tangent cone ordering) as special
cases. Furthermore, it provides polynomial factorizations, resultant,
characteristic set and gcd computations, syzygy and free-resolution
computations, and many more related functionalities. 

 Based on an easy-to-use interactive shell and a C-like programming language, \textsf{Singular}'s internal functionality is augmented and user-extendible by libraries
written in the \textsf{Singular} programming language. A general and efficient implementation of communication
links allows \textsf{Singular} to make its functionality available to other programs. 

 \textsf{Singular}'s development started in 1984 with an implementation of Mora's Tangent Cone
algorithm in Modula-2 on an Atari computer (K.P. Neuendorf, G. Pfister, H.
Sch{\"o}nemann; Humboldt-Universit{\"a}t zu Berlin). The need for a new system
arose from the investigation of mathematical problems coming from singularity
theory which none of the existing systems was able to compute. 

 In the early 1990s \textsf{Singular}'s ``home-town'' moved to Kaiserslautern, a general standard basis algorithm
was implemented in C, and \textsf{Singular} was ported to Unix, MS-DOS, Windows NT, and MacOS. 

 Continuous extensions (like polynomial factorization, gcd computations, links)
and refinements led in 1997 to the release of \textsf{Singular} version 1.0 and in 1998 to the release of version 1.2 (much faster standard
and Groebner bases computations based on Hilbert series and on improved
implementations of the algorithms, libraries for primary decomposition, ring
normalization, etc.) ''. }

 
\subsection{\textcolor{Chapter }{The system \textsf{GAP}}}\logpage{[ 1, 1, 3 ]}
\hyperdef{L}{X832B25F28009C024}{}
{
 \textsf{GAP} stands for ``Groups, Algorithms, and Programming'', and is developed by several people (``The \textsf{GAP} Group''). 

 \textsf{GAP} is not included in this package, and can be obtained for free from \href{http://www.gap-system.org/} {\texttt{http://www.gap-system.org/}}. There, one can find also its documentation, installing instructions, the
source code, and support if needed. The \textsf{GAP} system will run on any machine with an Unix-like or recent Windows or MacOS
operating system and with a reasonable amount of ram and disk space. 

 A description of \textsf{GAP}, copied from its web site, is the following: ``\textsf{GAP} is a system for computational discrete algebra, with particular emphasis on
Computational Group Theory. \textsf{GAP} provides a programming language, a library of thousands of functions
implementing algebraic algorithms written in the \textsf{GAP} language as well as large data libraries of algebraic objects. See the web
site the overview and the description of the mathematical capabilities. \textsf{GAP} is used in research and teaching for studying groups and their
representations, rings, vector spaces, algebras, combinatorial structures, and
more. The system, including source, is distributed freely. You can study and
easily modify or extend it for your special use.'' }

 }

 
\section{\textcolor{Chapter }{Installation}}\label{Installation}
\logpage{[ 1, 2, 0 ]}
\hyperdef{L}{X8360C04082558A12}{}
{
  In order to use this interface one must have both \textsf{GAP} version 4 and \textsf{Singular} installed. 
\subsection{\textcolor{Chapter }{Installing the system \textsf{Singular}}}\logpage{[ 1, 2, 1 ]}
\hyperdef{L}{X7BDF8BDD7CD556FF}{}
{
  Follow the \textsf{Singular} installing instructions. 

 However, for a Unix system, one needs to download two files: 
\begin{itemize}
\item  \texttt{Singular-{\textless}version{\textgreater}-share.tar.gz}, that contains architecture independent data like documentation and
libraries; 
\item  \texttt{Singular-{\textless}version{\textgreater}-{\textless}uname{\textgreater}.tar.gz}, that contains architecture dependent executables, like the \textsf{Singular} program (precompiled). {\textless}uname{\textgreater} is a description of the
processor and operating system for which \textsf{Singular} is compiled.
\end{itemize}
 

 \textsf{Singular} specific subdirectories will be created in such a way that multiple versions
and multiple architecture dependent files of \textsf{Singular} can peaceably coexist under the same \texttt{/usr/local/} tree. 

 Before trying the interface, make sure that \textsf{Singular} is installed and working as stand-alone program. }

 
\subsection{\textcolor{Chapter }{Installing the system \textsf{GAP}}}\logpage{[ 1, 2, 2 ]}
\hyperdef{L}{X866DB233812830A9}{}
{
  Follow the \textsf{GAP} installing instructions. 

 However, the basic steps of a \textsf{GAP} installation are: 
\begin{itemize}
\item Choose your preferred archive format and download the archives.
\item Unpack the archives.
\item On Unix: Compile \textsf{GAP}. (Compiled executables for Windows and Mac are in the archives.)
\item On Unix: Some packages need further installation for full functionality (which
is not available on Windows or Mac).
\item Adjust some links/scripts/icons ..., depending on your system, to make the new
version of \textsf{GAP} available to the users of your machine.
\item Optional: Run a few tests.
\item Optional, but appreciated: Give some feedback on your installation.
\end{itemize}
 There is also an experimental Linux binary distribution via remote
synchronization with a reference installation, which includes all packages and
some optimizations. Furthermore, the Debian GNU/Linux distribution contains
.deb-packages with the core part of \textsf{GAP} and some of the \textsf{GAP} packages. }

 
\subsection{\textcolor{Chapter }{Installing the package \textsf{singular}}}\logpage{[ 1, 2, 3 ]}
\hyperdef{L}{X8091731F7E019B20}{}
{
  The package \textsf{singular} is installed and loaded as a normal \textsf{GAP} package: see the \textsf{GAP} documentation  (\textbf{Reference: GAP Packages}). 

 Starting with version 4.4 of \textsf{GAP}, the package \textsf{singular} is distributed together with \textsf{GAP}. Hence, if \textsf{GAP} is already installed with all the distributed packages, then also the package \textsf{singular} is installed. However, if the package \textsf{singular} is not included in your \textsf{GAP} installation, it can be downloaded and unpacked in the \texttt{pkg/} directory of the \textsf{GAP} installation. If you don't have write access to the \texttt{pkg/} directory in your main \textsf{GAP} installation you can use private directories as explained in the \textsf{GAP} documentation  (\textbf{Reference: GAP Root Directories}). The package \textsf{singular} doesn't require compilation. }

 

\subsection{\textcolor{Chapter }{sing{\textunderscore}exec}}
\logpage{[ 1, 2, 4 ]}\nobreak
\label{sing_exec}
\hyperdef{L}{X8229A3C4793932BA}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{sing{\textunderscore}exec\index{singexec@\texttt{sing{\textunderscore}exec}}
\label{singexec}
}\hfill{\scriptsize (global variable)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{sing{\textunderscore}exec{\textunderscore}options\index{singexecoptions@\texttt{sing{\textunderscore}exec{\textunderscore}options}}
\label{singexecoptions}
}\hfill{\scriptsize (global variable)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{SingularTempDirectory\index{SingularTempDirectory@\texttt{SingularTempDirectory}}
\label{SingularTempDirectory}
}\hfill{\scriptsize (global variable)}}\\


 In order to use the interface, \textsf{GAP} has to be told where to find \textsf{Singular}. This can be done in three ways. First, if the \textsf{Singular} executable file is in the search path, then \textsf{GAP} will find it. Second, it is possible to edit (before loading the package) one
of the first lines of the file \texttt{singular/gap/singular.g} (that comes with this package). Third, it is possible to give the path of the \textsf{Singular} executable file directly during each \textsf{GAP} session assigning it to the variable \mbox{\texttt{\mdseries\slshape sing{\textunderscore}exec}} (after this package has been loaded, and before starting \textsf{Singular}), as in the example below. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@LoadPackage( "singular" );|
  The GAP interface to Singular, by Marco Costantini and Willem de Graaf
  true
  !gapprompt@gap>| !gapinput@sing_exec:= "/home/wdg/Singular/2-0-3/ix86-Linux/Singular";;|
\end{Verbatim}
 The directory separator is always '\texttt{/}', even under DOS/Windows or MacOS. The value of \mbox{\texttt{\mdseries\slshape sing{\textunderscore}exec}} must refer to the text-only version of \textsf{Singular} (\mbox{\texttt{\mdseries\slshape Singular}}), and not to the Emacs version (\mbox{\texttt{\mdseries\slshape ESingular}}), nor to the terminal window version (\mbox{\texttt{\mdseries\slshape TSingular}}). 

 In a similar way, it is possible to supply \textsf{Singular} with some command line options (or files to read containing user defined
functions), assigning them to the variable \mbox{\texttt{\mdseries\slshape sing{\textunderscore}exec{\textunderscore}options}}. This can be done by editing (before loading the package) one of the first
lines of the file \texttt{singular/gap/singular.g} (that comes with this package), or directly during each \textsf{GAP} session (after this package has been loaded, and before starting \textsf{Singular}), as in the example below. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@Add( sing_exec_options, "--no-rc" );|
  !gapprompt@gap>| !gapinput@Add( sing_exec_options, "/full_path/my_file" );|
\end{Verbatim}
 The variable \mbox{\texttt{\mdseries\slshape sing{\textunderscore}exec{\textunderscore}options}} is initialized to \mbox{\texttt{\mdseries\slshape [ "-t" ]}}; the user can add further options, but must keep \mbox{\texttt{\mdseries\slshape "-t"}}, which is required. The possible options are described in the \textsf{Singular} documentation, paragraph ``3.1.6 Command line options''. 

 \textsf{Singular} is not executed in the current directory, but in a user-specified one, or in a
temporary one. It is possible to supply this directory assigning it to the
variable \mbox{\texttt{\mdseries\slshape SingularTempDirectory}}. This can be done by editing (before loading the package) one of the first
lines of the file \texttt{singular/gap/singular.g} (that comes with this package), or directly during each \textsf{GAP} session (after this package has been loaded, and before starting \textsf{Singular}), as in the example below. If \mbox{\texttt{\mdseries\slshape SingularTempDirectory}} is not assigned, \textsf{GAP} will create and use a temporary directory, which will be removed when \textsf{GAP} quits. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@SingularTempDirectory := Directory( "/tmp" );|
  dir("/tmp/")
\end{Verbatim}
 On Windows, \textsf{Singular} version 3 may be not executed directly, but may be executed as \mbox{\texttt{\mdseries\slshape bash Singular}}. In this case, the variables \mbox{\texttt{\mdseries\slshape sing{\textunderscore}exec}}, \mbox{\texttt{\mdseries\slshape sing{\textunderscore}exec{\textunderscore}options}}, \mbox{\texttt{\mdseries\slshape SingularTempDirectory}} must reflect this, otherwise Windows complains that \mbox{\texttt{\mdseries\slshape cygwin1.dll}} is not found. The following works on my Windows machine. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@LoadPackage("singular");|
  true
  !gapprompt@gap>| !gapinput@SingularTempDirectory := Directory("c:/cygwin/bin");|
  dir("c:/cygwin/bin/")
  !gapprompt@gap>| !gapinput@sing_exec := "c:/cygwin/bin/bash.exe";|
  "c:/cygwin/bin/bash.exe"
  !gapprompt@gap>| !gapinput@sing_exec_options := [ "Singular", "-t" ];|
  [ "Singular", "-t" ]
  !gapprompt@gap>| !gapinput@StartSingular();|
\end{Verbatim}
 Another possibility is to run Gap from within the Cygwin shell. In this case,
with a standard installation of Cygwin and \textsf{Singular}, no change is required, }

 }

 
\section{\textcolor{Chapter }{Interaction with \textsf{Singular}}}\label{Interaction}
\logpage{[ 1, 3, 0 ]}
\hyperdef{L}{X795A815178AA90C7}{}
{
  The user must load the package \textsf{singular} with \texttt{LoadPackage} (\textbf{Reference: LoadPackage}) (or with \texttt{RequirePackage} (\textbf{Reference: RequirePackage}) if using \textsf{GAP} version 4.x, x {\textless} 4). 

\subsection{\textcolor{Chapter }{StartSingular}}
\logpage{[ 1, 3, 1 ]}\nobreak
\hyperdef{L}{X79C5E6F27C37DA10}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{StartSingular({\mdseries\slshape })\index{StartSingular@\texttt{StartSingular}}
\label{StartSingular}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{CloseSingular({\mdseries\slshape })\index{CloseSingular@\texttt{CloseSingular}}
\label{CloseSingular}
}\hfill{\scriptsize (function)}}\\


 After the package \textsf{singular} has been loaded, \textsf{Singular} is started automatically when one of the functions of the interface is called.
Alternatively, one can start \textsf{Singular} with the command \mbox{\texttt{\mdseries\slshape StartSingular}}. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@StartSingular();|
\end{Verbatim}
 See \ref{platforms} for technical details. Explicit use of \mbox{\texttt{\mdseries\slshape StartSingular}} is not necessary. If \mbox{\texttt{\mdseries\slshape StartSingular}} is called when a previous \textsf{Singular} session is running, than session will be closed, and a new session will be
started. 

 If at some point \textsf{Singular} is no longer needed, then it can be closed (in order to save system resources)
with the command \mbox{\texttt{\mdseries\slshape CloseSingular}}. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@CloseSingular();|
\end{Verbatim}
 However, when \textsf{GAP} exits, it is expected to close Singular, and remove any temporary directory,
except in the case of abnormal \textsf{GAP} termination. }

 

\subsection{\textcolor{Chapter }{SingularHelp}}
\logpage{[ 1, 3, 2 ]}\nobreak
\hyperdef{L}{X81FDDDE47EBA9698}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{SingularHelp({\mdseries\slshape topic})\index{SingularHelp@\texttt{SingularHelp}}
\label{SingularHelp}
}\hfill{\scriptsize (function)}}\\


 Here \mbox{\texttt{\mdseries\slshape topic}} is a string containing the name of a \textsf{Singular} topic. This function provides help on that topic using the \textsf{Singular} help system: see the \textsf{Singular} documentation, paragraphs ``3.1.3 The online help system'' and ``5.1.43
help''. If \mbox{\texttt{\mdseries\slshape topic}} is the empty string "", then the title/index page of the manual is displayed. 

 This function can be used to display the \textsf{Singular} documentation referenced in this manual; \mbox{\texttt{\mdseries\slshape topic}} must be given without the leading numbers. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@SingularHelp( "" ); # a Mozilla window appears|
  #I  // ** Displaying help in browser 'mozilla'.
  // ** Use 'system("--browser", <browser>);' to change browser,
  // ** where <browser> can be: "mozilla", "xinfo", "info", "builtin", "dummy", \
  "emacs".
\end{Verbatim}
 The \textsf{Singular} function \mbox{\texttt{\mdseries\slshape system}} can be accessed via the function \texttt{SingularInterface} (\ref{SingularInterface}). Some only-text browsers may be not supported by the interface. }

 
\subsection{\textcolor{Chapter }{Rings and orderings}}\logpage{[ 1, 3, 3 ]}
\hyperdef{L}{X86C329A285955655}{}
{
  All non-trivial algorithms in \textsf{Singular} require the prior definition of a (polynomial) ring, that will be called the
``base-ring''. Any polynomial (respectively vector) in \textsf{Singular} is ordered with respect to a term ordering (or, monomial ordering), that has
to be specified together with the declaration of a ring. See the documentation
of \textsf{Singular}, paragraph ``3.3 Rings and orderings'', for further information. 

 After defining in \textsf{GAP} a ring, a term ordering can be assigned to it using the function \texttt{SetTermOrdering} (\ref{SetTermOrdering}), and \emph{after} the term ordering is assigned, the interface and \textsf{Singular} can be told to use this ring as the base-ring, with the function \texttt{SingularSetBaseRing} (\ref{SingularSetBaseRing}). }

 
\subsection{\textcolor{Chapter }{Supported coefficients fields}}\logpage{[ 1, 3, 4 ]}
\hyperdef{L}{X840BA4C9839D3CF4}{}
{
  Let \mbox{\texttt{\mdseries\slshape p}} be a prime, \mbox{\texttt{\mdseries\slshape pol}} an irreducible polynomial, and \mbox{\texttt{\mdseries\slshape arg}} an appropriate argument for the given function. The coefficient fields of the
base-ring may be of the following form: 
\begin{itemize}
\item \mbox{\texttt{\mdseries\slshape Rationals}},
\item \mbox{\texttt{\mdseries\slshape CyclotomicField( arg )}},
\item \mbox{\texttt{\mdseries\slshape AlgebraicExtension( Rationals, pol )}},
\item \mbox{\texttt{\mdseries\slshape GaloisField( arg )}} (both prime and non-prime),
\item \mbox{\texttt{\mdseries\slshape AlgebraicExtension( GaloisField( p ), pol )}}.
\end{itemize}
 For some example see those for the function \texttt{SetTermOrdering} (\ref{SetTermOrdering}). 

 Let us remember that \mbox{\texttt{\mdseries\slshape CyclotomicField}} and \mbox{\texttt{\mdseries\slshape GaloisField}} can be abbreviated respectively to \mbox{\texttt{\mdseries\slshape CF}} and \mbox{\texttt{\mdseries\slshape GF}}; these forms are used also when \textsf{GAP} prints cyclotomic or Galois fields. See the \textsf{GAP} documentation about the functions: \texttt{CyclotomicField} (\textbf{Reference: CyclotomicField (for (subfield and) conductor)}), \texttt{GaloisField} (\textbf{Reference: GaloisField (for field size)}), \texttt{AlgebraicExtension} (\textbf{Reference: AlgebraicExtension}), and the chapters:  (\textbf{Reference: Rational Numbers}),  (\textbf{Reference: Abelian Number Fields}),  (\textbf{Reference: Finite Fields}),  (\textbf{Reference: Algebraic extensions of fields}). }

 

\subsection{\textcolor{Chapter }{SetTermOrdering}}
\logpage{[ 1, 3, 5 ]}\nobreak
\hyperdef{L}{X813A17AF85BFACB9}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{SetTermOrdering({\mdseries\slshape R})\index{SetTermOrdering@\texttt{SetTermOrdering}}
\label{SetTermOrdering}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{TermOrdering({\mdseries\slshape R})\index{TermOrdering@\texttt{TermOrdering}}
\label{TermOrdering}
}\hfill{\scriptsize (attribute)}}\\


 Let \mbox{\texttt{\mdseries\slshape R}} be a polynomial ring. The value of \mbox{\texttt{\mdseries\slshape TermOrdering( R )}} describes the term ordering of \mbox{\texttt{\mdseries\slshape R}}, and can be a string, a list, or a monomial ordering of \textsf{GAP}. (The term orderings of \textsf{Singular} are explained in its documentation, paragraphs ``3.3.3 Term orderings'' and
``B.2.1 Introduction to orderings''.) 

 If this value is a string, for instance \mbox{\texttt{\mdseries\slshape "lp"}} (lexicographical ordering), \mbox{\texttt{\mdseries\slshape "dp"}} (degree reverse lexicographical ordering), or \mbox{\texttt{\mdseries\slshape "Dp"}} (degree lexicographical ordering), this value will be passed to \textsf{Singular} without being interpreted or parsed by the interface. 

 If this value is a list, it must be of the form \mbox{\texttt{\mdseries\slshape [ str{\textunderscore}1, d{\textunderscore}1, str{\textunderscore}2,
d{\textunderscore}2, ... ]}}, where each \mbox{\texttt{\mdseries\slshape str{\textunderscore}i}} is a \textsf{Singular} ordering given as a string. Each \mbox{\texttt{\mdseries\slshape d{\textunderscore}i}} must be a number, and specifies the number of variables having that ordering;
however, if \mbox{\texttt{\mdseries\slshape str{\textunderscore}i}} is a weighted order, like \mbox{\texttt{\mdseries\slshape "wp"}} (weighted reverse lexicographical ordering) or \mbox{\texttt{\mdseries\slshape "Wp"}} (weighted lexicographical ordering), then the corresponding \mbox{\texttt{\mdseries\slshape d{\textunderscore}i}} must be a list of positive integers that specifies the weight of each
variable. The sum of the \mbox{\texttt{\mdseries\slshape d{\textunderscore}i}}'s (if numbers) or of their lengths (if lists) must be equal to the number of
variables of the ring \mbox{\texttt{\mdseries\slshape R}}. 

 This value can also be a monomial ordering of \textsf{GAP}: currently supported are \mbox{\texttt{\mdseries\slshape MonomialLexOrdering}}, \mbox{\texttt{\mdseries\slshape MonomialGrevlexOrdering}}, and \mbox{\texttt{\mdseries\slshape MonomialGrlexOrdering}}  (\textbf{Reference: Monomial Orderings}). 

 \mbox{\texttt{\mdseries\slshape TermOrdering}} is a mutable attribute, see the \textsf{GAP} documentation of \texttt{DeclareAttribute} (\textbf{Reference: DeclareAttribute}); if it is changed on the \textsf{GAP} side, it is necessary thereafter to send again the ring to \textsf{Singular} with \texttt{SingularSetBaseRing} (\ref{SingularSetBaseRing}). 

 \mbox{\texttt{\mdseries\slshape SetTermOrdering}} can be used to set the term ordering of a ring. It is not mandatory to assign
a term ordering: if no term ordering is set, then the default \mbox{\texttt{\mdseries\slshape "dp"}} will be used. If it is set, the term ordering must be set \emph{before} the ring is sent to \textsf{Singular} with \texttt{SingularSetBaseRing} (\ref{SingularSetBaseRing}), otherwise, \textsf{Singular} will ignore that term ordering, and will use the previous value if any, or the
default \mbox{\texttt{\mdseries\slshape "dp"}}. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@R1:= PolynomialRing( Rationals, ["x","y","z"] : old );;|
  !gapprompt@gap>| !gapinput@SetTermOrdering( R1, "lp" );|
  !gapprompt@gap>| !gapinput@R2:= PolynomialRing( GaloisField(9), 3 );;|
  !gapprompt@gap>| !gapinput@SetTermOrdering( R2, [ "wp", [1,1,2] ] );|
  !gapprompt@gap>| !gapinput@R3:= PolynomialRing( CyclotomicField(25), ["x","y","z"] : old );;|
  !gapprompt@gap>| !gapinput@SetTermOrdering( R3, MonomialLexOrdering() );|
  !gapprompt@gap>| !gapinput@x:=Indeterminate(Rationals);;|
  !gapprompt@gap>| !gapinput@F:=AlgebraicExtension(Rationals, x^5+4*x+1);;|
  !gapprompt@gap>| !gapinput@R4:= PolynomialRing( F, 6 );;|
  !gapprompt@gap>| !gapinput@SetTermOrdering( R4, [ "dp", 1, "wp", [1,1,2], "lp", 2 ] );|
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{SingularSetBaseRing}}
\logpage{[ 1, 3, 6 ]}\nobreak
\hyperdef{L}{X84A3CD498011A10C}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{SingularSetBaseRing({\mdseries\slshape R})\index{SingularSetBaseRing@\texttt{SingularSetBaseRing}}
\label{SingularSetBaseRing}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{SingularBaseRing\index{SingularBaseRing@\texttt{SingularBaseRing}}
\label{SingularBaseRing}
}\hfill{\scriptsize (global variable)}}\\


 Here \mbox{\texttt{\mdseries\slshape R}} is a polynomial ring. \mbox{\texttt{\mdseries\slshape SingularSetBaseRing}} sets the base-ring in \textsf{Singular} equal to \mbox{\texttt{\mdseries\slshape R}}. This ring will be also kept in \textsf{GAP} in the variable \mbox{\texttt{\mdseries\slshape SingularBaseRing}}. After this assignment, all the functions of the interface will work with
this ring. However, for some functions (those having rings, ideals, or modules
as arguments) it is not necessary to explicitly set the base ring first,
because in these cases the functions arguments contains information about a
ring that will be used as a base-ring. This will be specified for each
function in the corresponding section of this manual. (Unnecessary use of \mbox{\texttt{\mdseries\slshape SingularSetBaseRing}} doesn't harm; forgetting to use \mbox{\texttt{\mdseries\slshape SingularSetBaseRing}} produces the problem described in the paragraph \ref{common}.) The results of the computations may depend on the choice of the base-ring:
see an example at \texttt{FactorsUsingSingular} (\ref{FactorsUsingSingular}), in which the factorization of $ x^2 + y^2 $ is calculated. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@R:= PolynomialRing( Rationals, ["x","y","z"] : old );;|
  !gapprompt@gap>| !gapinput@SingularSetBaseRing( R );|
\end{Verbatim}
 The value of \mbox{\texttt{\mdseries\slshape SingularBaseRing}} when the package is loaded is \mbox{\texttt{\mdseries\slshape PolynomialRing( GF( 32003 ), 3 )}}, in order to match the default base-ring of \textsf{Singular}. 

 }

 

\subsection{\textcolor{Chapter }{SingularLibrary}}
\logpage{[ 1, 3, 7 ]}\nobreak
\hyperdef{L}{X871A5AF87DAE21E6}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{SingularLibrary({\mdseries\slshape string})\index{SingularLibrary@\texttt{SingularLibrary}}
\label{SingularLibrary}
}\hfill{\scriptsize (function)}}\\


 In \textsf{Singular} some functionality is provided by separate libraries that must be explicitly
loaded in order to be used (see the \textsf{Singular} documentation, chapter ``D. SINGULAR libraries''), see the example in \texttt{SingularInterface} (\ref{SingularInterface}). 

 The argument \mbox{\texttt{\mdseries\slshape string}} is a string containing the name of a \textsf{Singular} library. This function makes sure that this library is loaded into \textsf{Singular}. 

 The functions provided by the library \mbox{\texttt{\mdseries\slshape ring.lib}} could be not yet supported by the interface. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@SingularLibrary( "general.lib" );|
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{SingularInterface}}
\logpage{[ 1, 3, 8 ]}\nobreak
\hyperdef{L}{X876BA78F7CF049C3}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{SingularInterface({\mdseries\slshape singcom, arguments, type{\textunderscore}output})\index{SingularInterface@\texttt{SingularInterface}}
\label{SingularInterface}
}\hfill{\scriptsize (function)}}\\


 The function \mbox{\texttt{\mdseries\slshape SingularInterface}} provides the general interface that enables to apply the \textsf{Singular} functions to the \textsf{GAP} objects. Its arguments are the following: 
\begin{itemize}
\item  \mbox{\texttt{\mdseries\slshape singcom}} is a \textsf{Singular} command or function (given as a string). 
\item  \mbox{\texttt{\mdseries\slshape arguments}} is a list of \textsf{GAP} objects, $O_1, O_2, ..., O_n$, that will be used as arguments of \mbox{\texttt{\mdseries\slshape singcom}} (it may be the empty list). \mbox{\texttt{\mdseries\slshape arguments}} may also be a string: in this case it is assumed that it contains one or more \textsf{Singular} identifiers, or a \textsf{Singular} valid expression, or something else meaningful for \textsf{Singular}, and it is passed to \textsf{Singular} without parsing or checking on the \textsf{GAP} side. 
\item  \mbox{\texttt{\mdseries\slshape type{\textunderscore}output}} is the data type (given as a string) in \textsf{Singular} of the output. The data types are the following (see the \textsf{Singular} documentation, chapter ``4. Data types''): "bigint", "def", "ideal", "int",
"intmat", "intvec", "link", "list", "map", "matrix", "module", "number",
"poly", "proc", "qring", "resolution", "ring", "string", "vector" (some of
them were not available in previous versions of \textsf{Singular}). The empty string "" can be used if no output is expected. If in doubt you
can use "def" (see the \textsf{Singular} documentation, paragraph ``4.1 def''). Usually, in the documentation of each \textsf{Singular} function is given its output type. 
\end{itemize}
 Of course, the objects in the list \mbox{\texttt{\mdseries\slshape arguments}} and the \mbox{\texttt{\mdseries\slshape type{\textunderscore}output}} must be appropriate for the function \mbox{\texttt{\mdseries\slshape singcom}}: no check is done by the interface. 

 The function \mbox{\texttt{\mdseries\slshape SingularInterface}} does the following: 
\begin{enumerate}
\item  converts each object $O_1, O_2, ..., O_n$ in \mbox{\texttt{\mdseries\slshape arguments}} into the corresponding object $P_1, P_2, ..., P_n$, of \textsf{Singular}, 
\item  sends to \textsf{Singular} the command to calculate $singcom ( P_1, P_2, ..., P_n )$, 
\item  gets the output (of type \mbox{\texttt{\mdseries\slshape type{\textunderscore}output}}) from \textsf{Singular}, 
\item  converts it to the corresponding Gap object, and returns it to the user. 
\end{enumerate}
 

 The function \mbox{\texttt{\mdseries\slshape SingularInterface}} is oriented towards the kind-of-objects/data-types, and not to the functions
of \textsf{Singular}, because in this way it is much more general. The user can use ``all'' the
existing functions of \textsf{Singular} and the interface is not bounded to the state of implementation of \textsf{Singular}: future functions and user-defined functions will be automatically supported. 

 The conversion of objects from Gap to \textsf{Singular} and from it back to Gap is done using some `ad hoc' functions. Currently, the
conversion of objects from \textsf{GAP} to \textsf{Singular} is implemented for the following types: "ideal", "int", "intmat", "intvec",
"list", "matrix", "module", "number", "poly", "ring", "string", "vector".
Objects of other types are not supported, or are even not yet implemented in \textsf{GAP}. 

 The conversion of objects from \textsf{Singular} to \textsf{GAP} is currently implemented for the following types: "bigint", "def", "ideal",
"int", "intmat", "intvec", "list", "matrix", "module", "number", "poly",
"proc" (experimental), "string", "vector". Objects of other types are returned
as strings. 

 Before passing polynomials (or numbers, vectors, matrices, or lists of them)
to \textsf{Singular}, it is necessary to have sent the base-ring to \textsf{Singular} with the function \texttt{SingularSetBaseRing} (\ref{SingularSetBaseRing}), in order to ensure that \textsf{Singular} knows about them. This is not necessary if in the input there is a ring, an
ideal, or a module (before the polynomials), because these objects contain
information about the ring to be used as base-ring. All the input must be
relative to at most one ring; furthermore, at most one object of type "ring"
can be in the input. 

 As SingularInterface is a rather general function, it is not guaranteed that
it always works, and some functions are not supported. For instance, in \textsf{Singular} there is the function \mbox{\texttt{\mdseries\slshape pause}} that waits until a keystroke is pressed; but the interface instead waits for
the \textsf{Singular} prompt before sending it any new keystroke, and so calling \mbox{\texttt{\mdseries\slshape pause}} would hang the interface. However, the unsupported functions like \mbox{\texttt{\mdseries\slshape pause}} are only a few, and are not mathematically useful. SingularInterface tries to
block calls to known unsupported functions. 

 Some \textsf{Singular} functions may return more than one value, see the \textsf{Singular} documentation, paragraph ``6.2.7 Return type of procedures''. In order to use
one of these functions via \mbox{\texttt{\mdseries\slshape SingularInterface}}, the type \mbox{\texttt{\mdseries\slshape type{\textunderscore}output}} must be "list". The output in \textsf{GAP} will be a list containing the values returned by the \textsf{Singular} function. 

 In the next example we compute the primary decomposition of an ideal. Note
that for that we need to load the \textsf{Singular} library \mbox{\texttt{\mdseries\slshape primdec.lib}}. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@R:= PolynomialRing( Rationals, ["x","y","z"] : old );;|
  !gapprompt@gap>| !gapinput@i:= IndeterminatesOfPolynomialRing(R);;|
  !gapprompt@gap>| !gapinput@x:= i[1];; y:= i[2];; z:= i[3];;|
  !gapprompt@gap>| !gapinput@f:= (x*y-z)*(x*y*z+y^2*z+x^2*z);;|
  !gapprompt@gap>| !gapinput@g:= (x*y-z)*(x*y*z^2+x*y^2*z+x^2*y*z);;|
  !gapprompt@gap>| !gapinput@I:= Ideal( R, [f,g] );;|
  !gapprompt@gap>| !gapinput@SingularLibrary( "primdec.lib" );|
  !gapprompt@gap>| !gapinput@SingularInterface( "primdecGTZ", [ I ], "def" );|
  #I  Singular output of type "list"
  [ [ <two-sided ideal in Rationals[x,y,z], (1 generators)>,
        <two-sided ideal in Rationals[x,y,z], (1 generators)> ],
    [ <two-sided ideal in Rationals[x,y,z], (1 generators)>,
        <two-sided ideal in Rationals[x,y,z], (1 generators)> ],
    [ <two-sided ideal in Rationals[x,y,z], (2 generators)>,
        <two-sided ideal in Rationals[x,y,z], (2 generators)> ],
    [ <two-sided ideal in Rationals[x,y,z], (3 generators)>,
        <two-sided ideal in Rationals[x,y,z], (2 generators)> ] ]
\end{Verbatim}
 In the next example are calculated the first syzygy module of an ideal, and
the resultant of two polynomials with respect a variable. Note that in this
case it is not necessary to set the base-ring with \texttt{SingularSetBaseRing} (\ref{SingularSetBaseRing}), in the first case because the input \mbox{\texttt{\mdseries\slshape I}} is of type "ideal", and in the second case because the base-ring was already
sent to \textsf{Singular} in the former case. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@R:= PolynomialRing( Rationals, ["x","y","z"] : old );;|
  !gapprompt@gap>| !gapinput@i:= IndeterminatesOfPolynomialRing( R );;|
  !gapprompt@gap>| !gapinput@x:= i[1];; y:= i[2];; z:= i[3];;|
  !gapprompt@gap>| !gapinput@f:= 3*(x+2)^3+y;;|
  !gapprompt@gap>| !gapinput@g:= x+y+z;;|
  !gapprompt@gap>| !gapinput@I:= Ideal( R, [f,g] );;|
  !gapprompt@gap>| !gapinput@M := SingularInterface( "syz", [ I ], "module" );;|
  !gapprompt@gap>| !gapinput@GeneratorsOfLeftOperatorAdditiveGroup( M );|
  [ [ -x-y-z, 3*x^3+18*x^2+36*x+y+24 ] ]
  !gapprompt@gap>| !gapinput@SingularInterface( "resultant", [ f, g, z ], "poly");|
  3*x^3+18*x^2+36*x+y+24
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{SingularType}}
\logpage{[ 1, 3, 9 ]}\nobreak
\hyperdef{L}{X79B84D5C7AC98756}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{SingularType({\mdseries\slshape obj})\index{SingularType@\texttt{SingularType}}
\label{SingularType}
}\hfill{\scriptsize (function)}}\\


 to be written }

 }

 
\section{\textcolor{Chapter }{Interaction with \textsf{Singular} at low level}}\label{InteractionLow}
\logpage{[ 1, 4, 0 ]}
\hyperdef{L}{X8767E71280DA90D8}{}
{
  

\subsection{\textcolor{Chapter }{SingularCommand}}
\logpage{[ 1, 4, 1 ]}\nobreak
\hyperdef{L}{X85EEFDDE8111A67B}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{SingularCommand({\mdseries\slshape precommand, command})\index{SingularCommand@\texttt{SingularCommand}}
\label{SingularCommand}
}\hfill{\scriptsize (function)}}\\


 to be written }

 

\subsection{\textcolor{Chapter }{GapInterface}}
\logpage{[ 1, 4, 2 ]}\nobreak
\hyperdef{L}{X7B8471948055DD90}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{GapInterface({\mdseries\slshape func, arg, out})\index{GapInterface@\texttt{GapInterface}}
\label{GapInterface}
}\hfill{\scriptsize (function)}}\\


 to be written }

 }

 
\section{\textcolor{Chapter }{Other mathematical functions of the package}}\label{Other}
\logpage{[ 1, 5, 0 ]}
\hyperdef{L}{X82726C947AFEC357}{}
{
  

\subsection{\textcolor{Chapter }{GroebnerBasis}}
\logpage{[ 1, 5, 1 ]}\nobreak
\hyperdef{L}{X7A43611E876B7560}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{GroebnerBasis({\mdseries\slshape I})\index{GroebnerBasis@\texttt{GroebnerBasis}}
\label{GroebnerBasis}
}\hfill{\scriptsize (operation)}}\\


 Here \mbox{\texttt{\mdseries\slshape I}} is an ideal of a polynomial ring. This function computes a Groebner basis of \mbox{\texttt{\mdseries\slshape I}} (that will be returned as a list of polynomials). For this function it is \emph{not} necessary to set the base-ring with \texttt{SingularSetBaseRing} (\ref{SingularSetBaseRing}). 

 As term ordering, \textsf{Singular} will use the value of \texttt{TermOrdering} (\ref{TermOrdering}) of the polynomial ring containing \mbox{\texttt{\mdseries\slshape I}}. Again, if this value is not set, then the degree reverse lexicographical
ordering (\mbox{\texttt{\mdseries\slshape "dp"}}) will be used. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@R:= PolynomialRing( Rationals, ["x","y","z"] : old );;|
  !gapprompt@gap>| !gapinput@x := R.1;; y := R.2;; z := R.3;;|
  !gapprompt@gap>| !gapinput@r:= [ x*y*z -x^2*z, x^2*y*z-x*y^2*z-x*y*z^2, x*y-x*z-y*z ];;|
  !gapprompt@gap>| !gapinput@I:= Ideal( R, r );|
  <two-sided ideal in Rationals[x,y,z], (3 generators)>
  !gapprompt@gap>| !gapinput@GroebnerBasis( I );|
  [ x*y-x*z-y*z, x^2*z-x*z^2-y*z^2, x*z^3+y*z^3, -x*z^3+y^2*z^2-y*z^3 ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{SINGULARGBASIS}}
\logpage{[ 1, 5, 2 ]}\nobreak
\hyperdef{L}{X7A594BFA7B521F98}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{SINGULARGBASIS\index{SINGULARGBASIS@\texttt{SINGULARGBASIS}}
\label{SINGULARGBASIS}
}\hfill{\scriptsize (global variable)}}\\


 This variable is a record containing the component \mbox{\texttt{\mdseries\slshape GroebnerBasis}}. When the variable SINGULARGBASIS is assigned to the \textsf{GAP} global variable \mbox{\texttt{\mdseries\slshape GBASIS}}, then the computations of Groebner bases via \textsf{GAP}'s internal function for that, \texttt{GroebnerBasis} (\textbf{Reference: GroebnerBasis}), are done by \textsf{Singular}. 

 \textsf{Singular} claims that it ``features one of the fastest and most general implementations of various
algorithms for computing Groebner bases''. The \textsf{GAP}'s internal function claims to be ``a
na\texttt{\symbol{123}}\texttt{\symbol{92}}"\texttt{\symbol{92}}i\texttt{\symbol{125}}ve
implementation of Buchberger's algorithm (which is mainly intended as a
teaching tool): it might not be sufficient for serious problems.'' 

 (Note in the following example that the Groebner bases calculated by the \textsf{GAP} internal function are in general not reduced; for reduced bases see the \textsf{GAP} function \texttt{ReducedGroebnerBasis} (\textbf{Reference: ReducedGroebnerBasis}).) 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@R:= PolynomialRing( Rationals, 3 );;|
  !gapprompt@gap>| !gapinput@i:= IndeterminatesOfPolynomialRing( R );;|
  !gapprompt@gap>| !gapinput@pols:= [i[1]+i[2]+i[3], i[1]*i[2]+i[1]*i[3]+i[2]*i[3], i[1]*i[2]*i[3]];;|
  !gapprompt@gap>| !gapinput@o:= MonomialLexOrdering();;|
  !gapprompt@gap>| !gapinput@GBASIS:= GAPGBASIS;;|
  !gapprompt@gap>| !gapinput@GroebnerBasis( pols, o ); # This is the internal GAP method.|
  [ x+y+z, x*y+x*z+y*z, x*y*z, -y^2-y*z-z^2, z^3 ]
  !gapprompt@gap>| !gapinput@GBASIS:= SINGULARGBASIS;;|
  !gapprompt@gap>| !gapinput@GroebnerBasis( pols, o ); # This uses Singular via the interface.|
  [ z^3, y^2+y*z+z^2, x+y+z ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{HasTrivialGroebnerBasis}}
\logpage{[ 1, 5, 3 ]}\nobreak
\hyperdef{L}{X83668E317A047D24}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{HasTrivialGroebnerBasis({\mdseries\slshape I})\index{HasTrivialGroebnerBasis@\texttt{HasTrivialGroebnerBasis}}
\label{HasTrivialGroebnerBasis}
}\hfill{\scriptsize (function)}}\\


 The function \mbox{\texttt{\mdseries\slshape HasTrivialGroebnerBasis}} returns \mbox{\texttt{\mdseries\slshape true}} if the Groebner basis of the ideal \mbox{\texttt{\mdseries\slshape I}} is trivial, false otherwise. This function can be used if it is not necessary
to know the Groebner basis of an ideal, but it suffices to know only whether
it is trivial or not. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@x:= Indeterminate( Rationals, "x" : old );;|
  !gapprompt@gap>| !gapinput@y:= Indeterminate( Rationals, "y", [ x ] : old );;|
  !gapprompt@gap>| !gapinput@z:= Indeterminate( Rationals, "z", [ x, y ] : old );;|
  !gapprompt@gap>| !gapinput@R:= PolynomialRing( Rationals, [ x, y, z] );;|
  !gapprompt@gap>| !gapinput@f:= (x*y-z)*(x*y*z+y^2*z+x^2*z);;|
  !gapprompt@gap>| !gapinput@g:= (x*y-z)*(x*y*z^2+x*y^2*z+x^2*y*z);;|
  !gapprompt@gap>| !gapinput@I:= Ideal( R, [f,g] );;|
  !gapprompt@gap>| !gapinput@HasTrivialGroebnerBasis( I );|
  false
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{GcdUsingSingular (for polynomials)}}
\logpage{[ 1, 5, 4 ]}\nobreak
\hyperdef{L}{X877960128076E656}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{GcdUsingSingular({\mdseries\slshape pol{\textunderscore}1, pol{\textunderscore}2, ..., pol{\textunderscore}n})\index{GcdUsingSingular@\texttt{GcdUsingSingular}!for polynomials}
\label{GcdUsingSingular:for polynomials}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{GcdUsingSingular({\mdseries\slshape [pol{\textunderscore}1, pol{\textunderscore}2, ..., pol{\textunderscore}n]})\index{GcdUsingSingular@\texttt{GcdUsingSingular}!for a list of polynomials}
\label{GcdUsingSingular:for a list of polynomials}
}\hfill{\scriptsize (function)}}\\


 The arguments of this function are (possibly multivariate) polynomials
separated by commas, or it is a list of polynomials. This function returns the
greatest common divisor of these polynomials. For this function it is \emph{necessary} for the polynomials to lie in the base-ring, as set by \texttt{SingularSetBaseRing} (\ref{SingularSetBaseRing}). 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@R:= PolynomialRing( Rationals, ["x","y","z"] : old );;|
  !gapprompt@gap>| !gapinput@SingularSetBaseRing( R );|
  !gapprompt@gap>| !gapinput@i:= IndeterminatesOfPolynomialRing(R);;|
  !gapprompt@gap>| !gapinput@x:= i[1];; y:= i[2];; z:= i[3];;|
  !gapprompt@gap>| !gapinput@f:= (x*y-z)*(x*y*z+y^2*z+x^2*z);|
  x^3*y*z+x^2*y^2*z+x*y^3*z-x^2*z^2-x*y*z^2-y^2*z^2
  !gapprompt@gap>| !gapinput@g:= (x*y-z)*(x*y*z^2+x*y^2*z+x^2*y*z);|
  x^3*y^2*z+x^2*y^3*z+x^2*y^2*z^2-x^2*y*z^2-x*y^2*z^2-x*y*z^3
  !gapprompt@gap>| !gapinput@GcdUsingSingular( f, g );|
  -x*y*z+z^2
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{FactorsUsingSingularNC}}
\logpage{[ 1, 5, 5 ]}\nobreak
\hyperdef{L}{X84AC005C837CE13C}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{FactorsUsingSingularNC({\mdseries\slshape f})\index{FactorsUsingSingularNC@\texttt{FactorsUsingSingularNC}}
\label{FactorsUsingSingularNC}
}\hfill{\scriptsize (function)}}\\


 Here \mbox{\texttt{\mdseries\slshape f}} is a (possibly multivariate) polynomial. This function returns the
factorization of \mbox{\texttt{\mdseries\slshape f}} into irreducible factors. The first element in the output is a constant
coefficient, and the others may be monic (with respect to the term ordering)
polynomials, as returned by \textsf{Singular}. For this function it is \emph{necessary} that \mbox{\texttt{\mdseries\slshape f}} lies in the base-ring, as set by \texttt{SingularSetBaseRing} (\ref{SingularSetBaseRing}). 

 The function does not check that the product of these factors gives \mbox{\texttt{\mdseries\slshape f}} (for that use \texttt{FactorsUsingSingular} (\ref{FactorsUsingSingular})): \textsf{Singular} version 2-0-3 contains a bug so that the \textsf{Singular} function \mbox{\texttt{\mdseries\slshape factorize}} may give wrong results (therefore \textsf{Singular} version at least 2-0-4 is recommended). 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@R:= PolynomialRing( Rationals, ["x","y","z"] : old );;|
  !gapprompt@gap>| !gapinput@SingularSetBaseRing( R );|
  !gapprompt@gap>| !gapinput@i:= IndeterminatesOfPolynomialRing( R );;|
  !gapprompt@gap>| !gapinput@x:= i[1];; y:= i[2];; z:= i[3];;|
  !gapprompt@gap>| !gapinput@f:= (x*y-z)*(3*x*y*z+4*y^2*z+5*x^2*z);|
  5*x^3*y*z+3*x^2*y^2*z+4*x*y^3*z-5*x^2*z^2-3*x*y*z^2-4*y^2*z^2
  !gapprompt@gap>| !gapinput@FactorsUsingSingularNC( f );|
  [ 1, -5*x^2-3*x*y-4*y^2, -x*y+z, z ]
  !gapprompt@gap>| !gapinput@f:= (x*y-z)*(5/3*x*y*z+4*y^2*z+6*x^2*z);|
  6*x^3*y*z+5/3*x^2*y^2*z+4*x*y^3*z-6*x^2*z^2-5/3*x*y*z^2-4*y^2*z^2
  !gapprompt@gap>| !gapinput@FactorsUsingSingularNC( f );|
  [ 1/3, -18*x^2-5*x*y-12*y^2, -x*y+z, z ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{FactorsUsingSingular}}
\logpage{[ 1, 5, 6 ]}\nobreak
\hyperdef{L}{X87A0E69B81E52AA2}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{FactorsUsingSingular({\mdseries\slshape f})\index{FactorsUsingSingular@\texttt{FactorsUsingSingular}}
\label{FactorsUsingSingular}
}\hfill{\scriptsize (function)}}\\


 This does the same as \texttt{FactorsUsingSingularNC} (\ref{FactorsUsingSingularNC}), except that on the \textsf{GAP} level it is checked that the product of these factors gives \mbox{\texttt{\mdseries\slshape f}}. Again it is \emph{necessary} that \mbox{\texttt{\mdseries\slshape f}} lies in the base-ring, as set by \texttt{SingularSetBaseRing} (\ref{SingularSetBaseRing}). 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@R:= PolynomialRing( Rationals, ["x","y"] : old );;|
  !gapprompt@gap>| !gapinput@SingularSetBaseRing( R );|
  !gapprompt@gap>| !gapinput@x := R.1;; y := R.2;;|
  !gapprompt@gap>| !gapinput@FactorsUsingSingular( x^2 + y^2 );|
  [ 1, x^2+y^2 ]
  !gapprompt@gap>| !gapinput@R:= PolynomialRing( GaussianRationals, ["x","y"] : old);;|
  !gapprompt@gap>| !gapinput@SingularSetBaseRing( R );|
  !gapprompt@gap>| !gapinput@x := R.1;; y := R.2;;|
  !gapprompt@gap>| !gapinput@FactorsUsingSingular( x^2 + y^2 );|
  [ 1, x+E(4)*y, x-E(4)*y ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{GeneratorsOfInvariantRing}}
\logpage{[ 1, 5, 7 ]}\nobreak
\hyperdef{L}{X7EAC34C984599470}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{GeneratorsOfInvariantRing({\mdseries\slshape R, G})\index{GeneratorsOfInvariantRing@\texttt{GeneratorsOfInvariantRing}}
\label{GeneratorsOfInvariantRing}
}\hfill{\scriptsize (function)}}\\


 Here \mbox{\texttt{\mdseries\slshape R}} is a polynomial ring, and \mbox{\texttt{\mdseries\slshape G}} a finite group, which is either a matrix group or a permutation group. If \mbox{\texttt{\mdseries\slshape G}} is a matrix group, then its degree must be less than or equal to the number of
indeterminates of \mbox{\texttt{\mdseries\slshape R}}. If \mbox{\texttt{\mdseries\slshape G}} is a permutation group, then its maximal moved point must be less than or
equal to the number of indeterminates of \mbox{\texttt{\mdseries\slshape R}}. This function computes a list of generators of the invariant ring of \mbox{\texttt{\mdseries\slshape G}}, corresponding to its action on \mbox{\texttt{\mdseries\slshape R}}. This action is taken to be from the left. 

 For this function it is \emph{not} necessary to set the base-ring with \texttt{SingularSetBaseRing} (\ref{SingularSetBaseRing}). 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@m:=[[1,1,1],[0,1,1],[0,0,1]] * One( GF(3) );;|
  !gapprompt@gap>| !gapinput@G:= Group( [m] );;|
  !gapprompt@gap>| !gapinput@R:= PolynomialRing( GF(3), 3 );;|
  !gapprompt@gap>| !gapinput@GeneratorsOfInvariantRing( R, G );|
  [ x_3, x_1*x_3+x_2^2+x_2*x_3, x_1^3+x_1^2*x_3-x_1*x_2^2-x_1*x_2*x_3 ]
\end{Verbatim}
 }

 }

 
\section{\textcolor{Chapter }{Algebraic-geometric codes functions}}\label{AlgebraicGeometricCodes}
\logpage{[ 1, 6, 0 ]}
\hyperdef{L}{X7E4CD3FF8230789C}{}
{
  This section of \textsf{GAP}'s \textsf{singular} package and the corresponding code were written by David Joyner, \href{mailto://wdj@usna.edu} {\texttt{wdj@usna.edu}}, (with help from Christoph Lossen and Marco Costantini). It has been tested
with \textsf{Singular} versrion 2.0.x. 

 To start off, several new \textsf{Singular} commands must be loaded. The following command loads the necessary \textsf{Singular} and \textsf{GAP} commands, the packages \textsf{singular} and \textsf{GUAVA} (if not already loaded), and (re)starts \textsf{Singular}. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@ReadPackage("singular", "contrib/agcode.g");;|
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{AllPointsOnCurve}}
\logpage{[ 1, 6, 1 ]}\nobreak
\hyperdef{L}{X80553C51807FA705}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{AllPointsOnCurve({\mdseries\slshape f, F})\index{AllPointsOnCurve@\texttt{AllPointsOnCurve}}
\label{AllPointsOnCurve}
}\hfill{\scriptsize (function)}}\\


 Let $F$ be a finite and prime field. The function \mbox{\texttt{\mdseries\slshape AllPointsOnCurve( f, F )}} computes a list of generators of maximal ideals representing rationals points
on a curve $X$ defined by $f(x,y)=0$. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@F:=GF(7);;|
  !gapprompt@gap>| !gapinput@R2:= PolynomialRing( F, 2 );;|
  !gapprompt@gap>| !gapinput@SetTermOrdering( R2, "lp" );; # --- the term ordering must be "lp"|
  !gapprompt@gap>| !gapinput@indet:= IndeterminatesOfPolynomialRing(R2);;|
  !gapprompt@gap>| !gapinput@x:= indet[1];; y:= indet[2];;|
  !gapprompt@gap>| !gapinput@f:=x^7-y^2-x;;|
  !gapprompt@gap>| !gapinput@AllPointsOnCurve(f,F);|
  [ [ x_1 ], [ x_1-Z(7)^0 ], [ x_1+Z(7)^4 ], [ x_1+Z(7)^5 ], [ x_1+Z(7)^0 ], 
    [ x_1+Z(7) ], [ x_1+Z(7)^2 ] ]
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{AGCode}}
\logpage{[ 1, 6, 2 ]}\nobreak
\hyperdef{L}{X78E2235083D9FDCC}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{AGCode({\mdseries\slshape f, G, D})\index{AGCode@\texttt{AGCode}}
\label{AGCode}
}\hfill{\scriptsize (function)}}\\


 Let f be a polynomial in x,y over F=GF(p) representing plane curve $X$ defined by $f(x,y)=0$, where p is a prime (prime powers are not yet supported by the underlying \textsf{Singular} function). Let G, D be disjoint rational divisors on $X$, where D is a sum of distinct points, $supp(D)={P_1, ..., P_n}$. The AG code associated to f, G, D is the F defined to be the image of the
evaluation map $f \mapsto (f(P_1),...,f(P_n))$. The function \mbox{\texttt{\mdseries\slshape AGCode}} computes a list of length three, [G, n, k], where G is a generator matrix of
the AG code C, n is its length, and k is its dimension. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@F:=GF(7);;|
  !gapprompt@gap>| !gapinput@R2:= PolynomialRing( F, 2 );;|
  !gapprompt@gap>| !gapinput@SetTermOrdering( R2, "lp" );; # --- the term ordering must be "lp"|
  !gapprompt@gap>| !gapinput@SingularSetBaseRing(R2);|
  !gapprompt@gap>| !gapinput@indet:= IndeterminatesOfPolynomialRing(R2);;|
  !gapprompt@gap>| !gapinput@x:= indet[1];; y:= indet[2];;|
  !gapprompt@gap>| !gapinput@f:=x^7-y^2-x;;|
  !gapprompt@gap>| !gapinput@G:=[2,2,0,0,0,0,0]; D:=[4..8];|
  [ 2, 2, 0, 0, 0, 0, 0 ]
  [ 4 .. 8 ]
  !gapprompt@gap>| !gapinput@agc:=AGCode(f,G,D);|
  [ [ [ Z(7)^3, Z(7), 0*Z(7), Z(7)^4, Z(7)^5 ],
        [ 0*Z(7), Z(7)^4, Z(7)^0, Z(7)^5, Z(7)^3 ],
        [ 0*Z(7), 0*Z(7), Z(7)^3, Z(7), Z(7)^2 ] ], 5, 3 ]
\end{Verbatim}
 This generator matrix can be fed into the \textsf{GUAVA} command \texttt{GeneratorMatCode} (\textbf{GUAVA: GeneratorMatCode}) to create a linear code in \textsf{GAP}, which in turn can be fed into the \textsf{GUAVA} command \texttt{MinimumDistance} (\textbf{GUAVA: MinimumDistance}) to compute the minimum distance of the code. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@ag_mat:=agc[1];;|
  !gapprompt@gap>| !gapinput@C := GeneratorMatCode( ag_mat, GF(7) );|
  a linear [5,3,1..3]2 code defined by generator matrix over GF(7)
  !gapprompt@gap>| !gapinput@MinimumDistance(C);|
  3
\end{Verbatim}
 }

 }

 
\section{\textcolor{Chapter }{Troubleshooting and technical stuff}}\label{Troubleshooting}
\logpage{[ 1, 7, 0 ]}
\hyperdef{L}{X8562222580239DA6}{}
{
  
\subsection{\textcolor{Chapter }{Supported platforms and underlying \textsf{GAP} functions}}\logpage{[ 1, 7, 1 ]}
\hyperdef{L}{X848ADB537FE0D95B}{}
{
  \label{platforms} This package has been developed mainly on a Linux platform, with \textsf{GAP} version 4.4, and \textsf{Singular} version 2-0-4. A reasonable work has been done to ensure backward
compatibility with previous versions of \textsf{GAP} 4, but some features may be missing. This package has been tested also with
some other versions of Singular, including 2-0-3, 2-0-5, and 2-0-6, and on
other Unix systems. It has been tested also on Windows, but it is reported to
be slower that on Linux. 

 There is an extension of \textsf{Singular}, named \textsf{Plural}, which deals with certain noncommutative polynomial rings; see the \textsf{Singular} documentation, section ``7. PLURAL''. Currently, \textsf{GAP} doesn't support these noncommutative polynomial rings. The user of the \textsf{Singular} may use the features of \textsf{Plural} by calling the \textsf{Singular} function \mbox{\texttt{\mdseries\slshape ncalgebra}} via \mbox{\texttt{\mdseries\slshape SingularInterface}}. In this case, extreme care is needed, because on the \textsf{GAP} side the polynomial will still be commutative. 

 For the low-level communication with \textsf{Singular}, the interface relies on the \textsf{GAP} function \texttt{InputOutputLocalProcess} (\textbf{Reference: InputOutputLocalProcess}), and this function is available only in \textsf{GAP} 4.2 (or newer) on a Unix environment or in \textsf{GAP} 4.4 (or newer) on Windows; auto-detection is used. In this case, \textsf{GAP} interacts with a unique continuous session of \textsf{Singular}. 

 In the case that the \textsf{GAP} function \mbox{\texttt{\mdseries\slshape InputOutputLocalProcess}} is not available, then the singular interface will use the \textsf{GAP} function \texttt{Process} (\textbf{Reference: Process}). In this case only a limited subset of the functionality of the interface are
available: for example \texttt{StartSingular} (\ref{StartSingular}) and \texttt{GeneratorsOfInvariantRing} (\ref{GeneratorsOfInvariantRing}) are not available, but \texttt{GroebnerBasis} (\ref{GroebnerBasis}) is; \texttt{SingularInterface} (\ref{SingularInterface}) supports less data types. In this case, for each function call, a new session
of \textsf{Singular} is started and quitted. }

 
\subsection{\textcolor{Chapter }{How different versions of \textsf{GAP} display polynomial rings and polynomials}}\logpage{[ 1, 7, 2 ]}
\hyperdef{L}{X86A232F5840204DD}{}
{
  The way in which \textsf{GAP} displays polynomials has changed passing from version 4.3 to 4.4 and the way
in which \textsf{GAP} displays polynomial rings has changed passing from version 4.4 to 4.5. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@# GAP 4.3 or older|
  !gapprompt@gap>| !gapinput@R := PolynomialRing( Rationals, [ "x" ] : new );|
  PolynomialRing(..., [ x ])
  !gapprompt@gap>| !gapinput@x := IndeterminatesOfPolynomialRing( R )[1];;|
  !gapprompt@gap>| !gapinput@x^2 + x;|
  x+x^2
\end{Verbatim}
 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@# GAP 4.4|
  !gapprompt@gap>| !gapinput@R := PolynomialRing( Rationals, [ "x" ] : new );|
  PolynomialRing(..., [ x ])
  !gapprompt@gap>| !gapinput@x := IndeterminatesOfPolynomialRing( R )[1];;|
  !gapprompt@gap>| !gapinput@x^2 + x;|
  x^2+x
\end{Verbatim}
 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@# GAP 4.5 or newer|
  !gapprompt@gap>| !gapinput@R := PolynomialRing( Rationals, [ "x" ] : new );|
  Rationals[x]
  !gapprompt@gap>| !gapinput@x := IndeterminatesOfPolynomialRing( R )[1];;|
  !gapprompt@gap>| !gapinput@x^2 + x;|
  x^2+x
\end{Verbatim}
 The examples in this manual use the way of displaying of the newest \textsf{GAP}. }

 
\subsection{\textcolor{Chapter }{Test file}}\logpage{[ 1, 7, 3 ]}
\hyperdef{L}{X7DE6DC637A7FAC93}{}
{
  The following performs a test of the package functionality using a test file  (\textbf{Reference: Test Files}). 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@fn := Filename( DirectoriesPackageLibrary( "singular", "tst" ), "test" );;|
  !gapprompt@gap>| !gapinput@ReadTest( fn );|
  true
\end{Verbatim}
 }

 
\subsection{\textcolor{Chapter }{Common problems}}\logpage{[ 1, 7, 4 ]}
\hyperdef{L}{X82260C8E82090E87}{}
{
  \label{common} A common error is forgetting to use \texttt{SingularSetBaseRing} (\ref{SingularSetBaseRing}). In the next example, \mbox{\texttt{\mdseries\slshape SingularInterface}} works only after having used \mbox{\texttt{\mdseries\slshape SingularSetBaseRing}}. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@a:=Indeterminate( Rationals );;|
  !gapprompt@gap>| !gapinput@F:=AlgebraicExtension( Rationals, a^5+4*a+1 );;|
  !gapprompt@gap>| !gapinput@R:=PolynomialRing( F, ["x","y"] : old );;|
  !gapprompt@gap>| !gapinput@x := R.1;; y := R.2;;|
  !gapprompt@gap>| !gapinput@SingularInterface( "lead", [x^3*y+x*y+y^2], "poly" );|
  Error, sorry: Singular, or the interface to Singular, or the current
  SingularBaseRing, do not support the object x^3*y+x*y+y^2.
  Did you remember to use 'SingularSetBaseRing' ?
  [...]
  !gapbrkprompt@brk>| !gapinput@quit;|
  !gapprompt@gap>| !gapinput@SingularSetBaseRing( R );|
  !gapprompt@gap>| !gapinput@SingularInterface( "lead", [x^3*y+x*y+y^2], "poly" );|
  x^3*y
\end{Verbatim}
 A corresponding problem would happen if the user works directly with \textsf{Singular} and forgets to define the base-ring at first. 

 As explained in the \textsf{GAP} documentation  (\textbf{Reference: Polynomials and Rational Functions}), given a ring \mbox{\texttt{\mdseries\slshape R}}, \textsf{GAP} does not consider \mbox{\texttt{\mdseries\slshape R}} as a subset of a polynomial ring over \mbox{\texttt{\mdseries\slshape R}}: for example the zero of \mbox{\texttt{\mdseries\slshape R}} ($0$) and the zero of the polynomial ring ($0x^0$) are different objects. \textsf{GAP} prints these different objects in the same way, and this fact may be
misleading. This is a feature of \textsf{GAP} independent from the package \textsf{singular}, but it is important to keep it in mind, as most of the objects used by \textsf{Singular} are polynomials, or their coefficients. }

 
\subsection{\textcolor{Chapter }{Errors on the \textsf{Singular} side}}\logpage{[ 1, 7, 5 ]}
\hyperdef{L}{X7B3FBAFE7DBF433F}{}
{
 Errors may occur on the \textsf{Singular} side, for instance using \texttt{SingularInterface} (\ref{SingularInterface}) if the arguments supplied are not appropriate for the called function. In
general, it is still an open problem to find a satisfactory way to handle in \textsf{GAP} the errors of this kind. 

 At the moment, when an error on the \textsf{Singular} side happens, \textsf{Singular} may print an error message on the so-called ``standard error''; this message
may appear on the screen, but it is not logged by the \textsf{GAP} function \texttt{LogTo} (\textbf{Reference: LogTo}). The interface prints \mbox{\texttt{\mdseries\slshape No output from Singular}}, and then the trivial object (of the type specified as the third argument of \mbox{\texttt{\mdseries\slshape SingularInterface}}) may be returned. }

 
\subsection{\textcolor{Chapter }{Sending a report}}\logpage{[ 1, 7, 6 ]}
\hyperdef{L}{X7C8AE6BD787CD237}{}
{
  As every software, also this package may contain bugs. If you find a bug, or a
missing feature, or some other problem, or if you have comments and
suggestions, or if you need some help, write an e-mail to both the authors.
Please use an e-mail subject that begins with ``\mbox{\texttt{\mdseries\slshape singular package: }}''. Please include in the report the code that causes the problem, so that we
can replicate the problem. 

 If appropriate, you can set \texttt{InfoSingular} (\ref{InfoSingular}) to \mbox{\texttt{\mdseries\slshape 3}}, to see what happens between \textsf{GAP} and \textsf{Singular} (but this may give a lot of output). Note that \texttt{LogTo} (\textbf{Reference: LogTo}) does not log messages written directly on the screen by \textsf{Singular}. 

 Every report about this package is welcome, however the probability that your
problem will be fixed quickly increases if you read the text ``How to Report
Bugs Effectively'', \href{http://www.chiark.greenend.org.uk/~sgtatham/bugs.html} {\texttt{http://www.chiark.greenend.org.uk/\texttt{\symbol{126}}sgtatham/bugs.html}} , and send a bug report according to this text. If the report is about the
manual, please cite also its revision: 

 \texttt{@(\#)\$Id: singular.xml,v 1.34 2012/04/27 22:42:10 alexk Exp \$}. }

 

\subsection{\textcolor{Chapter }{SingularReportInformation}}
\logpage{[ 1, 7, 7 ]}\nobreak
\hyperdef{L}{X78BE74C97BF4E287}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{SingularReportInformation({\mdseries\slshape })\index{SingularReportInformation@\texttt{SingularReportInformation}}
\label{SingularReportInformation}
}\hfill{\scriptsize (function)}}\\


 The function \mbox{\texttt{\mdseries\slshape SingularReportInformation}} collects a description of the system, which should be included in any bug
report. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@SingularReportInformation();|
  Pkg_Version := "4.04.15";
  Gap_Version := "4.dev";
  Gap_Architecture := "i686-pc-linux-gnu-gcc";
  Gap_BytesPerVariable := 4;
  uname := "Linux 2.4.20 i686";
  Singular_Version: := 2004;
  Singular_Name: := "/usr/local/Singular/2-0-4/ix86-Linux/Singular";
  
  "Pkg_Version := \"4.04.15\";\nGap_Version := \"4.dev\";\nGap_Architecture := \
  \"i686-pc-linux-gnu-gcc\";\nGap_BytesPerVariable := 4;\nuname := \"Linux 2.4.2\
  0 i686\";\nSingular_Version: := 2004;\nSingular_Name: := \"/usr/local/Singular\
  /2-0-4/ix86-Linux/Singular\";\n"
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{InfoSingular}}
\logpage{[ 1, 7, 8 ]}\nobreak
\hyperdef{L}{X843C50B18098609A}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\ \ \texttt{InfoSingular\index{InfoSingular@\texttt{InfoSingular}}
\label{InfoSingular}
}\hfill{\scriptsize (info class)}}\\


 This is the info class  (\textbf{Reference: Info Functions}) used by the interface. It can be set to levels 0, 1, 2, and 3. At level 0 no
information is printed on the screen. At level 1 (default) the interface
prints a message about the \mbox{\texttt{\mdseries\slshape type{\textunderscore}output}}, when "def" is used in \mbox{\texttt{\mdseries\slshape SingularInterface}}, see the example at \texttt{SingularInterface} (\ref{SingularInterface}). At level 2, information on the activities of the interface is printed (e.g.,
messages when a \textsf{Singular} session, or a Groebner basis calculation, is started or terminated). At level
3 all strings that \textsf{GAP} sends to \textsf{Singular} are printed, as well as all strings that \textsf{Singular} sends back. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@SetInfoLevel( InfoSingular, 2 );|
  !gapprompt@gap>| !gapinput@G:= SymmetricGroup( 3 );;|
  !gapprompt@gap>| !gapinput@R:= PolynomialRing( GF(2), 3 );;|
  !gapprompt@gap>| !gapinput@GeneratorsOfInvariantRing( R, G );|
  #I  running SingularInterface( "invariant_ring", [ "matrix", "matrix"
   ], "list" )...
  #I  done SingularInterface.
  [ x_1+x_2+x_3, x_1*x_2+x_1*x_3+x_2*x_3, x_1*x_2*x_3 ]
  !gapprompt@gap>| !gapinput@I:= Ideal( R, last );;|
  !gapprompt@gap>| !gapinput@GroebnerBasis( I );|
  #I  running GroebnerBasis...
  #I  done GroebnerBasis.
  [ x_1+x_2+x_3, x_2^2+x_2*x_3+x_3^2, x_3^3 ]
  !gapprompt@gap>| !gapinput@SetInfoLevel( InfoSingular, 1 );|
\end{Verbatim}
 }

 }

 }

 \def\indexname{Index\logpage{[ "Ind", 0, 0 ]}
\hyperdef{L}{X83A0356F839C696F}{}
}

\cleardoublepage
\phantomsection
\addcontentsline{toc}{chapter}{Index}


\printindex

\newpage
\immediate\write\pagenrlog{["End"], \arabic{page}];}
\immediate\closeout\pagenrlog
\end{document}
