\input texinfo    @c -*-texinfo-*-
@comment $Id: singular.doc,v 1.50 1998-07-27 11:31:18 Singular Exp $
@comment this file contains the main structure of the manual
@c ------------------------
@comment %**start of header
@c ------------------------
@setfilename singular.hlp
@settitle Singular Manual
@iftex
@afourpaper
@finalout
@end iftex
@comment %**end of header
@c redirect funtion index:
@c @syncodeindex fn cp
@c ------------------------
@set singularmanual 1
@set VERSION 1.2
@c @set manual 1
@c ------------------------
@c <CENTER><IMG SRC="Singular2.gif"></CENTER><BR>
@html
<CENTER><A HREF="http://www.mathematik.uni-kl.de/~zca/Singular" TARGET="_parent">
<IMG SRC="images/singular.jpg"></A></CENTER><BR>
@end html
@ifinfo
this is the texinfo file describing Singular (version @value{VERSION})
@end ifinfo
@c
@titlepage
@sp 2
@center @titlefont{Singular}
@sp 2
@center A Computer Algebra System for Polynomial Computations
@sp 5
@center @titlefont{Manual}
@center Version @value{VERSION}
@sp 2
@center Singular is created and its development is directed and coordinated by
@center G.-M. Greuel, G. Pfister, and H. Schoenemann
@sp 2
@center with contributions by
@center O. Bachmann, W. Decker, C. Gorzel, H. Grassmann, A. Heydtmann, K. Krueger, M. Lamm,
@center B. Martin, M. Messollen, W. Neumann, T. Nuessler, W. Pohl, T. Siebert, R. Stobbe, T. Wichmann
@sp 2
@author Fachbereich Mathematik
@author und
@author Zentrum fuer Computeralgebra
@author Universitaet Kaiserslautern
@author D-67653 Kaiserslautern
@end titlepage
@c ----------------------------------------------------------------------------
@node Top, Preface, (dir), (dir)
@ifinfo
@c @manual
@c q:quit, m:menu item, n:next node, p:previous node, u:up, g:goto node
@c @end manual
@sp 1
@center Singular - Manual
@center Version @value{VERSION}
@center A Computer Algebra System for Polynomial Computations
@sp 2
@center @url{http://www.uni-kl.de/,University of Kaiserslautern}
@center @url{http://www.mathematik.uni-kl.de/,Department of Mathematics}
@center and
@center @url{http://www.mathematik.uni-kl.de/~zca/,Centre for Computer Algebra}
@end ifinfo
@menu
* Preface::
* Introduction::
* General concepts::
* Data types::
* Functions and system variables::
* Tricks and pitfalls::
* Examples::
* Polynomial data::
* Mathematical background::
* SINGULAR libraries::
* Library function index::
* Index::
@end menu
@c ----------------------------------------------------------------------------
@node Preface, Introduction, Top, Top
@chapter Preface
@cindex Preface

@include copyright.tex
@c ----------------------------------------------------------------------------
@node Introduction, General concepts, Preface, Top
@chapter Introduction
@cindex Introduction

@include start.tex
@c ----------------------------------------------------------------------------
@node General concepts, Data types, Introduction, Top
@chapter General concepts
@cindex General concepts
@include general.tex

@c ----------------------------------------------------------------------------
@node Data types, Functions and system variables, General concepts, Top
@chapter Data types
@cindex Data types
@include types.tex

@c ----------------------------------------------------------------------------
@node Functions and system variables, Tricks and pitfalls, Data types, Top
@chapter Functions and system variables
@cindex Commands
@include reference.tex

@c ----------------------------------------------------------------------------
@node Tricks and pitfalls, Examples, Functions and system variables, Top
@chapter Tricks and pitfalls
@cindex Tricks and pitfalls

@menu
* Limitations::
* Major differences to the C programming language::
* Miscellaneous oddities::
* Identifier resolution::
@end menu
@c -------------------------------------------------------------------------
@node Limitations,Major differences to the C programming language,,Tricks and pitfalls
@section Limitations
@cindex Limitations

@sc{Singular} has the following limitations:
@itemize @bullet
@item
the characteristic of a prime field must be less than 32004
@item
the (weighted) degree of a monomial must be smaller than 2147483648
@item
the exponent of a ring variable must be smaller than 32768
@item
a ring must have 505 variables or less
@*(501 on a DEC Alpha)
@item
integers (of type @code{int}) have the limited range
from -2147483647 to 2147483647
@c @item
@c a token (in the input) must have 16383 characters or less.
@c @*(Tokens are strings, blocks of statements, numbers)
@c @*This does not apply to proc in libraries but to blocks
@c within a procedure
@item
the length of an identifier is unlimited but @code{listvar}
displays only the first 20 characters
@c @item
@c the interpretation of text between a closing @code{@}} and the end of
@c the line is undefined. (Therefore do not put anything but spaces between
@c @code{@}} and the end of the line.)
@end itemize

@c -------------------------------------------------------------------------
@node Major differences to the C programming language,Miscellaneous oddities,Limitations,Tricks and pitfalls
@section Major differences to the C programming language
@cindex C programming language

Although many constructs from @sc{Singular}'s programming language are similar
to those from the C programming language, there are some subtle
differences. Most notably:

@menu
* No rvalue of increments and assignments::
* Evaluation of logical expressions::
* No case or switch statement::
* Usage of commas::
* Usage of brackets::
* Behaviour of continue::
* Return type of procedures::
@end menu
@c ---------------------------------------
@node No rvalue of increments and assignments, Evaluation of logical expressions,,Major differences to the C programming language
@heading No rvalue of increments and assignments
@cindex rvalue

The increment @code{++} (resp.@: decrement operator @code{--}) has no
rvalue, i.e., cannot be used on the right-hand sides of assignments.
So, instead of

@example
j = i++;  // WRONG!!!
@end example

@noindent (which results in an error), it must be written

@example
i++; j = i;
@end example

Likewise, an assignment expression does not have a result.  Therefore,
compound assignments like @code{i = j = k;} are not allowed and result
in an error.

@c ---------------------------------------
@node Evaluation of logical expressions, No case or switch statement, No rvalue of increments and assignments, Major differences to the C programming language
@heading Evaluation of logical expressions
@cindex Evaluation of logical expressions
@cindex and
@cindex or

@c ------------------------------------------------------------
@c   This piece of text partially exists also in the file types.doc,
@c   chapter "boolean expressions".
@c   If you change something here, change it there, too!
@c ------------------------------------------------------------
@strong{All} arguments of a logical expressions are first evaluated and
then the value of the logical expression is determined. For example, the
logical expressions @code{(a || b)} is evaluated by first evaluating
@code{a} @emph{and} @code{b}, even though the value of @code{b} has no
influence on the value of @code{(a || b)}, if @code{a} evaluates to
true. Therefore, the following results in a syntax error

@example
if (defined(i) && i > 0) @{@} // WRONG!!!
@end example

@noindent if the variable @code{i} is undefined. This must be written
instead as

@example
if (defined(i))
@{
  if (i > 0) @{@}
@}
@end example

Note that this evaluation is different from the left-to-right, conditional
evaluation of logical expressions (as found in most programming
languages). For example, in these other languages, the value of @code{(1
|| b)} is determined without ever evaluating @code{b}.
@c ------------------------------------------------------------
@c end of duplicate text
@c ------------------------------------------------------------

However, there are several short work-arounds for this problem:
@enumerate
@item
If a variable (say, @code{i}) is only to be used as a boolean flag, then
define (value is true) and undefine (value is false) @code{i} instead of
assigning a value. Using this scheme, it is sufficient to simply write

@example
if (defined(i))
@end example

in order to check whether @code{i} is true. Use the command @code{kill}
to undefine a variable (@pxref{kill}).
@item
If a variable  can have more than two values, then
define it, if necessary, before it is used for the first time.
For example, if the following is used within a procedure

@example
if (! defined(DEBUG)) @{ int DEBUG = 1;@}
@dots{}
if (DEBUG == 3)  @{@dots{}@}
if (DEBUG == 2)  @{@dots{}@}
@dots{}
@end example

then a user of this procedure does not need to care about the existence
of the @code{DEBUG} variable -- this remains hidden from the
user. However, if @code{DEBUG} exists globally, then its local default
value is overwritten by its global one.
@end enumerate

@c ---------------------------------------
@node No case or switch statement,  Usage of commas, Evaluation of logical expressions, Major differences to the C programming language
@heading No case or switch statement
@cindex case
@cindex switch

@sc{Singular} does not offer a @code{case} (or, @code{switch})
statement. However, it can be imitated in the following way:

@example
while (1)
@{
   if (choice == choice_1) @{ @dots{}; break;@}
   @dots{}
   if (choice == choice_n) @{ @dots{}; break;@}
   // default case
   @dots{}; break;
@}
@end example

@c ---------------------------------------
@node Usage of commas, Usage of brackets, No case or switch statement, Major differences to the C programming language
@heading Usage of commas
@cindex comma

In @sc{Singular}, a comma separates list elements and the value of a comma
expression is a list.
Hence, commas can not be used to combine several expressions into
a single expression. For example, instead of writing

@example
for (i=1, j=5; i<5 || j<10; i++, j++) @{@dots{}@} // WRONG!!!!!!
@end example

@noindent one has to write

@example
for (i,j = 1,5; i<5 || j<10; i++, j++) @{@dots{}@}
@end example

@c ---------------------------------------
@node Usage of brackets, Behaviour of continue, Usage of commas, Major differences to the C programming language
@heading Usage of brackets
@cindex bracket

In @sc{Singular}, curly brackets (@code{@{} @code{@}}) @strong{must
always} be used to enclose the statement body following such constructs
like @code{if}, @code{else}, @code{for}, @code{while}, even if this
block consists of only a single statement. Similarly, in the return
statement of a procedure parentheses (@code{(} @code{)}) @strong{must
always} be used to enclose the return value.  Even if there is no value
to return, parentheses have to be used after a return statement
(i.e., @code{return();}).  For example,

@example
if (i == 1) return i;    // WRONG!!!!!
@end example

@noindent results in a errors. Instead, it must be written as

@example
if (i == 1) @{ return (i); @}
@end example

@c ---------------------------------------
@node  Behaviour of continue, Return type of procedures, Usage of brackets, Major differences to the C programming language
@heading Behaviour of continue
@cindex continue
@sc{Singular}'s @code{continue} construct is only valid inside the body
of a @code{for} or @code{while} construct. It skips the rest of the
loop-body and jumps to the beginning of the block. Unlike the
C-construct @sc{Singular}'s @code{continue} @strong{does not execute the
increment statement}. For example,

@example
for (int i = 1 ; i<=10; i=i+1)
@{
   @dots{}
   if (i==3) @{ i=8;continue; @}
     // skip the rest if i is 3 and
     // continue with the next i: 8
   i;
@}
@expansion{} 1
@expansion{} 2
@expansion{} 8
@expansion{} 9
@expansion{} 10
@end example

@c ---------------------------------------
@node Return type of procedures,,Behaviour of continue, Major differences to the C programming language

Although the @sc{Singular} language is a strongly typed programming
language, the type of the
return value of a procedure does not need to be specified. As a
consequence, the return type of a procedure may vary, i.e., may, for
example, depend on the input. However, the return value
of such a procedures may then only be assigned to a variable of type
@code{def}.

@example
@c example
proc type_return (int i)
{
  if (i > 0) {return (i);}
  else {return (list(i));}
}
def t1 = type_return(1);
def t2 = type_return(-1);
typeof(t1); typeof(t2);
@c example
@end example

Furthermore, it is mandatory to assign the return value of a procedure
to a variable of type def, if a procedure changes the current ring using
the @code{keepring} command (@pxref{keepring}) and returns a
ring-dependent value (like a polynomial or module).

@example
@c example
proc def_return
{
  ring r=0,(x,y),dp;
  poly p = x;
  keepring r;
  return (x);
}
def p = def_return();
// poly p = def_return(); would be WRONG!!!
typeof(p);
@c example
@end example

On the other hand, more than one value can be returned by a single
@code{return} statement. For example,

@example
proc tworeturn () @{ return (1,2); @}
int i,j = tworeturn();
@end example


@c -------------------------------------------------------------------------
@node Miscellaneous oddities, Identifier resolution, Major differences to the C programming language, Tricks and pitfalls
@section Miscellaneous oddities

@enumerate
@item integer division
@cindex integer division
@cindex div

A sequence of digits and @code{/} without spaces is of type number.
With spaces it is an expression of type int
(and @code{/} is the integer division).
To avoid confusion use the operand @code{div}.
@example
@c example
  ring r=32002,x,dp;
  3/2;
  3 / 2;
  3 div 2;
  number(3) / number(2);
  number a=3;
  number b=2;
  a / b;
  a div b;
@c example
@end example


@item monomials and precedence
@cindex monomials and precedence

The computation of a monomial has precedence over all operators:
@example
@c example
  ring r=0,(x,y),dp;
  2xy^2 == (2*x*y)^2;
  2xy^2 == 2x*y^2;
  2x*y^2 == 2*x * (y^2);
@c example
@end example

@item meaning of mult
@cindex mult
@cindex degree

A standard mistake is to interpret @code{degree(i)} or @code{mult(i)}
for an inhomogeneous ideal @code{i} as the degree of the homogenization
or as something like the 'degree of the affine part'. For the ordering
dp (degree reverse lexicographical) the converse is true: if @code{i} is
given by a standard basis, @code{mult(i)} is the degree of the
homogeneous ideal obtained by homogenization of @code{i} and then
putting the homogenizing variable to 0, hence it is the degree of the
part at infinity (this can also be checked by looking at the initial
ideal).

@item size of ideals
@cindex ideals
@cindex siz

@code{size} counts the non-zero entries of an ideal (resp.@:
module). Use @code{ncols} to determine the actual number of entries in
the ideal (resp.@: module).

@item computations in qrings

@sc{Singular} computes in a quotient rings as long as possible with the
given representative of a polynomial, say, @code{f}.  I.e., it usually
does not reduce @code{f} w.r.t. the quotient ideal.  This is only done
when necessary
during standard bases computations or by an explicit reduction using
the command @code{reduce(f, std(0))} (@pxref{reduce}).

@item substring selection

Two comma -- separated @code{int}s in square brackets after a string select a
substring. An @code{intvec} in square brackets after a string selects
the respective single characters of the string and returns them as an
expression list of two strings.
In particular,

@example
@c example
  string s = "one-word";
  s[2,6];     // a substring starting at the second char
  size(_);
  intvec v = 2,6;
  s[v];      // the second and the sixth char
  string st = _;  // stick toghter by an assignment
  st;
  size(_);
  v = 2,6,8;
  s[v];
@c example
@end example
@end enumerate

@c ----------------------------------------------
@node Identifier resolution,, Miscellaneous oddities, Tricks and pitfalls
@section Identifier resolution
@cindex identifier

In @sc{Singular}, an identifier (i.e., a "word") is resolved in the
following way and order: It is checked for
@enumerate
@item
a reserved name,
@item
a local  variable (w.r.t. a procedure),
@item
a local ring variable (w.r.t. a ring locally set in a procedure),
@item
a global variable,
@item
a monom consisting of local ring variables written without operators,
@item
a monom consisting of global ring variables written without operators.
@end enumerate

Consequently, it is allowed to have general variables with the same name
as ring  variables. However, the above identifier resolution order must
be kept in mind. Otherwise, surprising results may come up.

@example
@c example
ring r=0,(x,y),dp;
int x;
x*y; // resolved product int*poly, i.e. 0*y
xy; // "xy" is one identifier and resolved to monom xy
@c example
@end example

For these reasons, we strongly disrecommend the usage of variables which
have the same name(s) as ring variables.

@c ----------------------------------------------------------------------------
@node Examples, Polynomial data, Tricks and pitfalls, Top
@appendix Examples
@cindex Examples
@include examples.tex

@c ----------------------------------------------------------------------------
@node Polynomial data,Mathematical background, Examples, Top
@appendix Polynomial data
@cindex Polynomial data
@include pdata.tex

@c ----------------------------------------------------------------------------
@node Mathematical background, SINGULAR libraries, Polynomial data, Top
@appendix Mathematical background
@cindex Mathematical background
@include math.tex
@c ----------------------------------------------------------------------------
@node SINGULAR libraries, Library function index, Mathematical background, Top
@appendix SINGULAR libraries
@cindex SINGULAR libraries
@cindex LIBs

@sc{Singular} comes with a set of standard libraries. Their content is
described in the following subsections.
@menu
* standard_lib:: extensions of singular kernel
* all_lib:: load all other libraries
* general_lib:: procedures of general type
* matrix_lib:: procedures for matrix operations
* sing_lib:: procedures for computing invariants of singularities
* elim_lib:: procedures for elimination, saturation and blowing up
* inout_lib:: procedures for manipulating in- and output
* random_lib:: procedures of random/sparse  matrix and poly operations
* deform_lib:: procedures for computing miniversal deformation
* homolog_lib:: procedures for homological algebra
* poly_lib:: procedures for manipulating polynomials and ideals
* ring_lib:: procedures for manipulating rings and maps
* finvar_lib:: procedures to calculate invariant rings & more
* primdec_lib:: procedures for primary decomposition
* invar_lib:: procedures to compute the ring of invariants
* latex_lib:: procedures for typeseting in TeX
* hnoether_lib:: procedures for the Hamburger-Noether-development
* classify_lib:: procedures for classifying hypersurface singularities
* graphics_lib:: procedures to draw  with Mathematica
* normal_lib:: procedure for normalization
@end menu
@c ----------------------------------------------------------
@node standard_lib, all_lib, SINGULAR libraries, SINGULAR libraries
@section standard_lib
@cindex standard_lib
The library @code{standard.lib} provides extensions to the
set of built-in commands and is automatically loaded
during the start of @sc{Singular}.
It contains:
@table @code
@item groebner
see @ref{groebner}.
@item stdfglm
see @ref{stdfglm}.
@item stdhilb
see @ref{stdhilb}.
@end table
@c ----------------------------------------------------------
@node all_lib, general_lib, standard_lib, SINGULAR libraries
@section all_lib
@cindex all_lib
@c lib  all.lib
@c ----------------------------------------------------------
@node general_lib, matrix_lib, all_lib, SINGULAR libraries
@section general_lib
@cindex general_lib
@c lib  general.lib
@c ----------------------------------------------------------
@node matrix_lib, sing_lib, general_lib, SINGULAR libraries
@section matrix_lib
@cindex matrix_lib
@c lib matrix.lib
@c ----------------------------------------------------------
@node sing_lib, elim_lib, matrix_lib, SINGULAR libraries
@section sing_lib
@cindex sing_lib
@c lib sing.lib
@c ----------------------------------------------------------
@node elim_lib, inout_lib, sing_lib, SINGULAR libraries
@section elim_lib
@cindex elim_lib
@c lib elim.lib
@c ----------------------------------------------------------
@node inout_lib, random_lib,elim_lib, SINGULAR libraries
@section inout_lib
@cindex inout_lib
@c lib inout.lib
@c ----------------------------------------------------------
@node random_lib, deform_lib, inout_lib, SINGULAR libraries
@section random_lib
@cindex random_lib
@c lib random.lib
@c ----------------------------------------------------------
@node deform_lib,homolog_lib,random_lib, SINGULAR libraries
@section deform_lib
@cindex deform_lib
@c lib deform.lib
@c ----------------------------------------------------------
@node homolog_lib,poly_lib,deform_lib, SINGULAR libraries
@section homolog_lib
@cindex homolog_lib
@c lib homolog.lib
@c ----------------------------------------------------------
@node poly_lib,ring_lib,homolog_lib, SINGULAR libraries
@section poly_lib
@cindex poly_lib
@c lib poly.lib
@c ----------------------------------------------------------
@c @node factor_lib,ring_lib,poly_lib, SINGULAR libraries
@c @section factor_lib
@c @cindex factor_lib
@c @c lib factor.lib
@c ----------------------------------------------------------
@node ring_lib,finvar_lib,poly_lib, SINGULAR libraries
@section ring_lib
@cindex ring_lib
@c lib ring.lib
@c ----------------------------------------------------------
@node finvar_lib,primdec_lib,ring_lib, SINGULAR libraries
@section finvar_lib
@cindex finvar_lib
@c lib finvar.lib
@c ----------------------------------------------------------
@node primdec_lib,invar_lib,finvar_lib, SINGULAR libraries
@section primdec_lib
@cindex primdec_lib
@c lib primdec.lib
@c ----------------------------------------------------------
@node invar_lib,latex_lib,primdec_lib, SINGULAR libraries
@section invar_lib
@cindex invar_lib
@c lib invar.lib
@c ---------------------------------------------------------
@node latex_lib,hnoether_lib,invar_lib, SINGULAR libraries
@section latex_lib
@cindex latex_lib
@c lib latex.lib
@c ---------------------------------------------------------
@node hnoether_lib,classify_lib,latex_lib, SINGULAR libraries
@section hnoether_lib
@cindex hnoether_lib
@c lib hnoether.lib
@c ---------------------------------------------------------
@node classify_lib,graphics_lib,hnoether_lib, SINGULAR libraries
@section classify_lib
@cindex classify_lib
@c lib classify.lib
@c ---------------------------------------------------------
@node graphics_lib,normal_lib,classify_lib, SINGULAR libraries
@section graphics_lib
@cindex graphics_lib
@c lib graphics.lib
@c ---------------------------------------------------------
@node normal_lib,,graphics_lib, SINGULAR libraries
@section normal_lib
@cindex normal_lib
@c lib normal.lib
@c ----------------------------------------------------------
@node Library function index, Index, SINGULAR libraries, Top
@appendix Library function index
@printindex fn
@c ----------------------------------------------------------
@node Index, ,Library function index, Top
@chapter Index
@printindex cp
@c ---------------------------------------------------------
@shortcontents
@contents
@bye