\input texinfo    @c -*-texinfo-*-
@comment $Id: singular.doc,v 1.17 1998-05-07 16:38:56 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 ------------------------
@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 Commutative Algebra, Algebraic Geometry
@center and Singularity Theory
@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, K. Krueger, B. Martin, M. Messollen,
@center 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
q:quit, m:menu item, n:next node, p:previous node, u:up, g:goto node
@sp 1
@center Singular - Manual
@center Version @value{VERSION}
@center A Computer Algebra System for Singularity Theory, Algebraic Geometry
@center  and Commutative Algebra
@sp 2
@center University of Kaiserslautern
@center Department of Mathematics
@center and
@center Centre for Computer Algebra
@end ifinfo
@menu
* Preface::
* Introduction::
* General concepts::
* Data types::
* Functions and variables::
* Tricks and pitfalls::
* Examples::
* 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 variables, General concepts, Top
@chapter Data types
@cindex Data types
@include types.tex

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

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

@menu
* Limitations::
* Major differences to the C programming language::
* Miscellaneous oddities::
@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:
@table @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 the line is undefined. (Therefore do not put anything but spaces between @code{@}} and the end of the line.)
@end table

@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 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::
* No rvalue of assignments::
* Evaluation of logical expressions::
* No case/switch statement::
* Usage of commas::
* Usage of brackets::
* Behaviour of continue::
@end menu
@c ---------------------------------------
@node No rvalue of increments, No rvalue of assignments,,Major differences to the C programming language 
@subsection No rvalue of increments
@cindex rvalue of increments
The increment @code{++} (resp. decrement operator @code{--}) has no rvalue 
rvalue, i.e. can not be used on the right-hand sides of 
assignments. So, instead of 
@*@code{j = i++;  // WRONG!!!}
@*(which results in an error), it must be written
@*@code{i++; j = i;}

@c ---------------------------------------
@node No rvalue of assignments, Evaluation of logical expressions, No rvalue of increments, Major differences to the C programming language
@subsection No rvalue of assignments
@cindex rvalue of assignments 
An assignment expression does not have a result, i.e., does not have an rvalue.
Therefore, compound assignments like @code{i = j = k;} are not allowed.
However, the following works:
@*@code{string s; int i;}
@*@code{s, i = "Hello", 2;}

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

@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} and @code{b}, even though the value of
@code{b} has no influence on the value of @code{(a || b)}. Note that
this is different from the left-to-right evaluation of logical
expressions (as found in most programming languages like C) which, for
example, determine the @code{(1 || b)} without evaluating @code{b}.
Hence, in Singular, the following results in a syntax error
@example
if (defined(i) && i > 0) @{@}
@end example
if the variable @code{i} is undefined and must be written intead as
@example
if (defined(i)) 
@{ 
  if (i > 0) @{@}
@}
@end example
However, there are several short work-arounds for this problem:
@enumerate
@item 
If a variable (say, @code{i}) can  only have two values (say, 1 and 0),
then define (value equals 1) and undefine (value equals 0) @code{i}
instead of assigning a value. Then it is sufficient to simply write
@example
if (defined(i))
@end example
in order to check whether @code{i} has the value 1.
@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 the existence of the variable @code{DEBUG} remains hidden from the
user. However, if @code{DEBUG} exists globally, then its local default
value is overwritten.
@end enumerate

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

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/switch statement, Major differences to the C programming language
@subsection Usage of commas
@cindex comma

In 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<j; i++, j++) @{@dots{}@} // WRONG!!!!!! 
@end example
you have to write
@example
 for (i,j = 1,5; i<j; i++, j++) @{@dots{}@}
@end example

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

In Singular, curly brackets (i.e. "@code{@{@}}") @strong{must always} be
used to enclose the (statement) body following such constructs like
@code{if, else, for, while}, even if this block consists of only a
single statement. Similarly, in the return statement a procedure round
brackets (i.e. "@code{()}") @strong{must always} be used to enclose the
return value.
For example,
@example
  if (i == 1) return i;    // WRONG!!!!!
@end example
results in a errors. Instead, it must be written as
@example
  if (i == 1) @{ return (i); @} 
@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  Behaviour of continue,, Usage of brackets, Major differences to the C programming language
@subsection Behaviour of continue
@cindex continue 
Singular's @code{continue} construct is only valid inside the body of
the @code{for} construct. It skips the rest of the loop-body and jumps
to the beginning of the block. Unlike the C-construct 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 Miscellaneous oddities,,Major differences to the C programming language, Tricks and pitfalls
@section Miscellaneous oddities

@enumerate
@item integer division
@cindex integer division
@cindex mod

A sequence of digits and @code{/} without spaces is of type number.
With spaces it is an expression of type ints
(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;
  xy^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 sizeof

@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

Singular computes in a @code{qring} as long as possible with the given
representative of a polynomial, i.e. it usually does not reduce a
polynom w.r.t. the qutient ideal. This is only doen during standard
bases computations.

@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 collects them as strings.
In particular,
@example
@c example
  string s = "hello";
  s[1,4];
  intvec v = 1,4;
  s[v];
  size(s[1,4]);
  size(s[v]);
@c example
@end example

@item return type of procedures

The type of the return value of a procedure does not need to be fixed,
i.e., the return type may depend on the input. However, the retun value
of such a procedures can 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
@end enumerate


@c ----------------------------------------------------------------------------
@node Examples, Mathematical background, Tricks and pitfalls, Top
@chapter Examples
@cindex Examples
@include examples.tex

@c ----------------------------------------------------------------------------
@node Mathematical background, SINGULAR libraries, Examples, Top
@chapter Mathematical background
@cindex Mathematical background
@include math.tex
@c ----------------------------------------------------------------------------
@node SINGULAR libraries, Library function index, Mathematical background, Top
@chapter SINGULAR libraries
@cindex SINGULAR libraries
@cindex LIBs

@sc{Singular} comes with a set of standard libraries:
@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
* factor_lib:: procedures for calling external factorizer (UNIX)
* 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
* tex_lib:: procedures for typeseting in TeX
* hnoether_lib:: procedures for the Hamburger-Noether-development
* classify_lib:: procedures for classifying hypersurface singularities
@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 will be automatically loaded
during the start of @code{Singular}.
It contains:
@menu
* stdfglm::
* stdhilbert::
@end menu
@iftex
@*@code{stdfglm}:@ref{stdfglm};
@*@code{stdhilbert}:@ref{stdhilbert}.
@end iftex
@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,factor_lib,homolog_lib, SINGULAR libraries
@section poly_lib
@cindex poly_lib
@c lib poly.lib
@c ----------------------------------------------------------
@node factor_lib,ring_lib,poly_lib, SINGULAR libraries
@section factor_lib
@cindex factor_lib
@c lib factor.lib
@c ----------------------------------------------------------
@node ring_lib,finvar_lib,factor_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,tex_lib,primdec_lib, SINGULAR libraries
@section invar_lib
@cindex invar_lib
@c lib invar.lib
@c ---------------------------------------------------------
@node tex_lib,hnoether_lib,invar_lib, SINGULAR libraries
@section tex_lib
@cindex tex_lib
@c lib tex.lib
@c ---------------------------------------------------------
@node hnoether_lib,classify_lib,tex_lib, SINGULAR libraries
@section hnoether_lib
@cindex hnoether_lib
@c lib hnoether.lib
@c ---------------------------------------------------------
@node classify_lib,,hnoether_lib, SINGULAR libraries
@section classify_lib
@cindex classify_lib
@c lib classify.lib
@c ----------------------------------------------------------
@node Library function index, Index, SINGULAR libraries, Top
@chapter Library function index
@printindex fn
@c ----------------------------------------------------------
@node Index, ,Library function index, Top
@chapter Index
@printindex cp
@c ---------------------------------------------------------
@contents
@bye