@node Introduction, Getting started, Preface, Top
@chapter Introduction
@cindex Introduction


@sc{Singular} is a computer algebra system designed for special needs
in commutative algebra and algebraic geometry, with special features for
singularity theory.
@sc{Singular} can compute with ideals and modules
generated by polynomials or polynomial vectors over polynomial
rings or, more generally, over the localization of a
polynomial ring with respect to any ordering on the set of monomials
which is compatible with the semigroup structure.
Hence, there is a wide range of applications in local and global algebraic
geometry (but @sc{Singular} is not limited to these areas).

We tried to set up the user interface as a consistent and flexible
language:
@enumerate
@item commands end with a semicolon (@code{;}), they are not
bound to one line
@item types of objects are numbers, polynomials, ideals, vectors, modules,
(polynomial) matrices, maps and integers, integer vectors and matrices, strings, lists,
(communication) links
@item there is an automatic type conversion whenever it is useful
@item the system is capable of executing procedures
with parameters, local variables
and return values
@item there are libraries of useful functions from several areas
@item this manual (and other documenation)
is also available as online information
@c @item @dots{} and much more documentation
@end enumerate

@c ---------------------------------------
@section Notations

@code{Typewriter style} is used for @sc{Singular}  input and output,
@expansion{} in front of a line indicates output. @code{//} makes
the rest of the line a comment.
@c ---------------------------------------
@node Getting started,Command Syntax,Introduction, Top
@include start.tex
@c ---------------------------------------
@node Command Syntax,Expressions,Getting started, Top
@chapter Command Syntax
@cindex Command Syntax

@menu
* How to enter and exit::
* General syntax::
* Singular prompt and error recovery::
* Special characters::
* Usage of Names::
* Monomial orderings::
@end menu

@c --------------------------------------------------------------------------
@node General syntax,Singular prompt and error recovery,How to enter and exit,Command Syntax
@section General syntax
@cindex General syntax
@cindex =
@c ---------------------------------------
@c -----------------------------------------
@node Special characters,Usage of Names,Singular prompt and error recovery,Command Syntax
@section Special characters
@cindex Special characters
@c ---------------------------------------
@node  Usage of Names, Monomial orderings, Special characters, Command Syntax
@section Usage of Names
@menu
* Reserved names::
* User defined names::
* Names in proc::
@end menu
@c ---------------------------------------
@node Reserved names, User defined names, ,Usage of Names
@subsection Reserved names

@c ---------------------------------------
@node User defined names, Names in proc, Reserved names, Usage of Names
@subsection User defined names

@c ---------------------------------------
@node Names in proc, , User defined names, Usage of Names
@subsection Names in proc
@cindex Names in proc
@cindex local names

All variables are local to the procedure they are defined in.
These names cannot interfere with names in other
proc and are automatically deleted after having executed
the proc.
Names can be made global by @code{export} (see @ref{export}).
These global names will not be deleted automatically.
@smallexample
  proc xxx
  @{
    int k=4;        //defines a local variable k
    int result=k+2;
    export result;  //defines the global variable "result".
  @}
@end smallexample
If you type @code{listvar(all);} after having executed a proc you will
see that the variable @code{result} is still there while @code{k}
has been deleted.

The parameters of a proc can be accessed by their position, i.e.
@code{#[1]} for parameter 1 up
to the number of arguments.
Procedures can define argument lists, see @ref{procedures and Libraries}.
While interpreting a proc without a parameter list
there is a special variable:
@code{#} (of type list) holds all arguments,
@code{size(#)} is the number of arguments the proc was called with.
@smallexample
  if (size(#) > 0)  @{ int i=#[size(#)]; @}
  //assign the last argument to the local variable i
@end smallexample
Internally parameters and local variables are stored using
the nesting level,
you will see the nesting level
if you do a @code{listvar();} command inside a proc.
@c ---------------------------------------------------------------------------
@c --------------------------------------------------------------------------
@node global orderings, local orderings, , Monomial orderings
@subsection global orderings
@cindex global orderings

For all these orderings: Loc K[x] = K[x]

@table @asis
@item lp:
lexicographical ordering.
@*
@ifinfo
x^a < x^b  <==> there is an i,  1 <= i <= n :
@* a_1 = b_1, @dots{}, a_(i-1) = b_(i-1), a_i < b_i.
@end ifinfo
@tex
$x^\alpha < x^\beta  \Leftrightarrow  \exists\; 1 \le i \le n :
\alpha_1 = \beta_1, \ldots, \alpha_{i-1} = \beta_{i-1}, \alpha_i <
\beta_i$.
@end tex
@item dp:
degree reverse lexicographical ordering.
@*
@ifinfo
x^a < x^b <==>
@* deg(x^a) < deg(x^b), where deg(x^a) = a_1 + @dots{} + a_n,
@* or
@* deg(x^a) = deg(x^b) and there exist an i, 1 <= i <= n:
@*     a_n = b_n, @dots{}, a_(i+1) = b_(i+1), a_i > b_i.
@end ifinfo
@tex
    $x^\alpha < x^\beta \Leftrightarrow \deg(x^\alpha) < \deg(x^\beta)$,
where $\deg(x^\alpha) = \alpha_1 + \cdots + \alpha_n,$ or
@end tex
@*@tex
    \phantom{$x^\alpha < x^\beta \Leftrightarrow $}$ \deg(x^\alpha) =
    \deg(x^\beta)$ and $\exists\ 1 \le i \le n:$
@end tex
@*@tex
    \phantom{$x^\alpha < x^\beta \Leftrightarrow$}$\alpha_n = \beta_n,
    \ldots, \alpha_{i+1} = \beta_{i+1}, \alpha_i > \beta_i$.
@end tex
@item Dp:
degree lexicographical ordering.
@*
@ifinfo
x^a < x^b <==>
@* deg(x^a) < deg(x^b)
@* or
@* deg(x^a) = deg(x^b) and there exist an i, 1 <= i <= n:
@*     a_1 = b_1, @dots{}, a_(i-1) = b_(i-1), a_i < b_i.
@end ifinfo
@tex
    $x^\alpha < x^\beta \Leftrightarrow \deg(x^\alpha) < \deg(x^\beta)$,
where $\deg(x^\alpha) = \alpha_1 + \cdots + \alpha_n,$ or
@end tex
@*@tex
    \phantom{ $x^\alpha < x^\beta \Leftrightarrow $} $\deg(x^\alpha) =
    \deg(x^\beta)$ and $\exists\ 1 \le i \le n:$
@end tex
@*@tex
    \phantom{ $x^\alpha < x^\beta \Leftrightarrow $} $\alpha_1 = \beta_1,
    \ldots, \alpha_{i-1} = \beta_{i-1}, \alpha_i < \beta_i$.
@end tex
@item wp:
weighted reverse lexicographical ordering.
@*
@ifinfo
 wp(w_1, @dots{}, w_n), w_i
@end ifinfo
@tex
${\tt wp}(w_1, \ldots, w_n),\; w_i$
@end tex
 positive integers,
 is defined as @code{dp}
 but with
@ifinfo
  deg(x^a) = w_1 a_1 + @dots{} + w_n a_n.
@end ifinfo
@tex
$\deg(x^\alpha) = w_1 \alpha_1 + \cdots + w_n\alpha_n.$
@end tex
@item Wp:
weighted lexicographical ordering.
@*
@ifinfo
 Wp(w_1, @dots{}, w_n), w_i
@end ifinfo
@tex
${\tt Wp}(w_1, \ldots, w_n),\; w_i$
@end tex
 positive integers,
 is defined as @code{Dp}
 but with
@ifinfo
  deg(x^a) = w_1 a_1 + @dots{} + w_n a_n.
@end ifinfo
@tex
$\deg(x^\alpha) = w_1 \alpha_1 + \cdots + w_n\alpha_n.$
@end tex
@end table
@c --------------------------------------------------------------------------
@node local orderings, module orderings, global orderings, Monomial orderings
@subsection local orderings
@cindex local orderings

For ls, ds, Ds and, if the weights are positive integers, also for ws and
Ws,  we have
@ifinfo
Loc K[x] = K[x]_(x),
@end ifinfo
@tex
$Loc\, K[x] = K[x]_{(x)}$,
@end tex
 the localization of K[x] at the
maximal ideal
@ifinfo
 (x_1, @dots{}, x_n).
@end ifinfo
@tex
\ $(x_1, ..., x_n)$.
@end tex

@table @asis
@item ls:
negative lexicographical ordering.
@*
@ifinfo
x^a < x^b  <==> there is an i,  1 <= i <= n :
@* a_1 = b_1, @dots{}, a_(i-1) = b_(i-1), a_i > b_i.
@end ifinfo
@tex
$x^\alpha < x^\beta  \Leftrightarrow  \exists\; 1 \le i \le n :
\alpha_1 = \beta_1, \ldots, \alpha_{i-1} = \beta_{i-1}, \alpha_i >
\beta_i$.
@end tex
@item ds:
negative degree reverse lexicographical ordering.
@*
@ifinfo
x^a < x^b <==>
@* deg(x^a) > deg(x^b), where deg(x^a) = a_1 + @dots{} + a_n,
@* or
@* deg(x^a) = deg(x^b) and there exist an i, 1 <= i <= n:
@*     a_n = b_n, @dots{}, a_(i+1) = b_(i+1), a_i > b_i.
@end ifinfo
@tex
    $x^\alpha < x^\beta \Leftrightarrow \deg(x^\alpha) > \deg(x^\beta)$,
where $\deg(x^\alpha) = \alpha_1 + \cdots + \alpha_n,$ or
@end tex
@*@tex
    \phantom{ $x^\alpha < x^\beta \Leftrightarrow$ } $\deg(x^\alpha) =
    \deg(x^\beta)$ and $\exists\ 1 \le i \le n:$
@end tex
@*@tex
    \phantom{ $x^\alpha < x^\beta \Leftrightarrow $} $\alpha_n = \beta_n,
    \ldots, \alpha_{i+1} = \beta_{i+1}, \alpha_i > \beta_i$.
@end tex
@item Ds:
negative degree lexicographical ordering.
@*
@ifinfo
x^a < x^b <==>
@* deg(x^a) > deg(x^b)
@* or
@* deg(x^a) = deg(x^b) and there exist an i, 1 <= i <= n:
@*     a_1 = b_1, @dots{}, a_(i-1) = b_(i-1), a_i < b_i.
@end ifinfo
@tex
    $x^\alpha < x^\beta \Leftrightarrow \deg(x^\alpha) > \deg(x^\beta)$,
where $\deg(x^\alpha) = \alpha_1 + \cdots + \alpha_n,$ or
@end tex
@*@tex
    \phantom{$ x^\alpha < x^\beta \Leftrightarrow$ }$ \deg(x^\alpha) =
    \deg(x^\beta)$ and $\exists\ 1 \le i \le n:$
@end tex
@*@tex
    \phantom{$ x^\alpha < x^\beta \Leftrightarrow$ } $\alpha_1 = \beta_1,
    \ldots, \alpha_{i-1} = \beta_{i-1}, \alpha_i < \beta_i$.
@end tex
@item ws:
(general) weighted reverse lexicographical ordering.
@*
@ifinfo
 ws(w_1, @dots{}, w_n), w_1
@end ifinfo
@tex
${\tt ws}(w_1, \ldots, w_n),\; w_1$
@end tex
 a nonzero integer,
@ifinfo
w_2,@dots{},w_n
@end ifinfo
@tex
$w_2,\ldots,w_n$
@end tex
 any integer (including 0),
 is defined as @code{ds}
 but with
@ifinfo
  deg(x^a) = w_1 a_1 + @dots{} + w_n a_n.
@end ifinfo
@tex
$\deg(x^\alpha) = w_1 \alpha_1 + \cdots + w_n\alpha_n.$
@end tex
@item Ws:
(general) weighted lexicographical ordering.
@*
@ifinfo
 Ws(w_1, @dots{}, w_n), w_1
@end ifinfo
@tex
${\tt Ws}(w_1, \ldots, w_n),\; w_1$
@end tex
 a nonzero integer,
@ifinfo
w_2,@dots{},w_n
@end ifinfo
@tex
$w_2,\ldots,w_n$
@end tex
 any integer (including 0),
 is defined as @code{Ds}
 but with
@ifinfo
  deg(x^a) = w_1 a_1 + @dots{} + w_n a_n.
@end ifinfo
@tex
$\deg(x^\alpha) = w_1 \alpha_1 + \cdots + w_n\alpha_n.$
@end tex
@end table

@c --------------------------------------------------------------------------
@node module orderings, matrix orderings, local orderings, Monomial orderings
@subsection module orderings
@cindex module orderings

@sc{Singular} offers also orderings on the set of ``monomials''
@ifinfo
@{ x^a*gen(i) | a in N^n, 1 <= i <= r @} on Loc K[x]^r = Loc K[x]gen(1)
+ @dots{} + Loc K[x]gen(r), where gen(1), @dots{}, gen(r) denote the canonical
generators of Loc K[x]^r, the r-fold direct sum of Loc K[x].
@end ifinfo
@tex
$\{ x^a gen(i) | a \in N^n, 1 \leq i \leq r \}$ on Loc K$[x]^r$ = Loc K[x]$gen(1)
+ \ldots +$Loc K[x]$gen(r)$, where $gen(1), \ldots, gen(r)$ denote the canonical
generators of Loc K[x]$^r$, the r-fold direct sum of Loc K[x].
@end tex

We have two possibilities, either to give priority to the component of a
vector of
@ifinfo
Loc K[x]^r
@end ifinfo
@tex
\ $Loc K[x]^r$\
@end tex
or (which is the default in @sc{Singular}) to give priority
to the coefficients.
The orderings @code{(<,c)} and @code{(<,C)} give priority to the coefficients;
@code{(c,<)} and @code{(C,<)} give priority to the components.
@*Let < be any of the monomial orderings of Loc K[x] as above.

@table @asis
@item (<,C):
@ifinfo
<_m = (<,C) denotes the module ordering (giving priority to the coefficients):
@* x^a*gen(i) <_m x^b*gen(j) <==>
@* x^a < x^b
@* or
@* x^a = x^b  and  i < j.
@end ifinfo
@tex
$<_m = (<,C)$ denotes the module ordering (giving priority to the coefficients):
@end tex
@iftex
@*
@end iftex
@tex
\quad \quad $x^\alpha gen(i) <_m x^\beta gen(j) \Leftrightarrow x^\alpha < x^\beta$,
@end tex
@iftex
@*
@end iftex
@tex
    \phantom{\quad \quad $x^\alpha gen(i) <_m x^\beta gen(j) \Leftrightarrow $}
      or $x^\alpha = x^\beta $ and $ i < j$.
@end tex

@strong{Example:}
@smallexample
@c example
  ring r = 0, (x,y,z), ds;
  // the same as ring r = 0, (x,y,z), (ds, C);
  [x+y2,z3+xy];
  [x,x,x];
@c example
@end smallexample

@item (C,<):
@ifinfo
<_m = (C, <) denotes the module ordering (giving priority to the
component):
@* x^a*gen(i) <_m x^b*gen(j) <==>
@* i<j
@* or
@* i = j and x^a < x^b.
@end ifinfo
@tex
$<_m = (C, <)$ denotes the module ordering (giving priority to the component):
@end tex
@iftex
@*
@end iftex
@tex
\quad \quad   $x^\alpha gen(i) <_m x^\beta gen(j) \Leftrightarrow i < j$,
@end tex
@iftex
@*
@end iftex
@tex
    \phantom{$\quad \quad x^\alpha gen(i) <_m x^\beta gen(j) \Leftrightarrow $}
      or $ i = j $ and $ x^\alpha < x^\beta $.
@end tex

@strong{Example:}
@smallexample
@c example
  ring r = 0, (x,y,z), (C,lp);
  [x+y2,z3+xy];
  [x,x,x];
@c example
@end smallexample

@item (<,c):
@ifinfo
<_m = (<,c) denotes the module ordering (giving priority to the coefficients):
@* x^a*gen(i) <_m x^b*gen(j) <==>
@* x^a < x^b
@* or
@* x^a = x^b  and  i > j.
@end ifinfo
@tex
$<_m = (<,c)$ denotes the module ordering (giving priority to the coefficients):
@end tex
@iftex
@*
@end iftex
@tex
\quad \quad $x^\alpha gen(i) <_m x^\beta gen(j) \Leftrightarrow x^\alpha < x^\beta$,
@end tex
@iftex
@*
@end iftex
@tex
    \phantom{\quad \quad $x^\alpha gen(i) <_m x^\beta gen(j) \Leftrightarrow $}
      or $x^\alpha = x^\beta $ and $ i > j$.
@end tex

@strong{Example:}
@smallexample
@c example
  ring r = 0, (x,y,z), (lp,c);
  [x+y2,z3+xy];
  [x,x,x];
@c example
@end smallexample

@item (c,<):
@ifinfo
<_m = (c, <) denotes the module ordering (giving priority to the
component):
@* x^a*gen(i) <_m x^b*gen(j) <==>
@* i>j
@* or
@* i = j and x^a < x^b.
@end ifinfo
@tex
$<_m = (c, <)$ denotes the module ordering (giving priority to the component):
@end tex
@iftex
@*
@end iftex
@tex
\quad \quad   $x^\alpha gen(i) <_m x^\beta gen(j) \Leftrightarrow i > j$,
@end tex
@iftex
@*
@end iftex
@tex
    \phantom{$\quad \quad x^\alpha gen(i) <_m x^\beta gen(j) \Leftrightarrow $}
      or $ i = j $ and $ x^\alpha < x^\beta $.
@end tex

@strong{Example:}
@smallexample
@c example
  ring r = 0, (x,y,z), (c,lp);
  [x+y2,z3+xy];
  [x,x,x];
@c example
@end smallexample
@end table

@ifinfo
The output of a vector v in K[x]^r with components v_1,
@dots{}, v_r has the format v_1 * gen(1) + @dots{} + v_r * gen(r)
@end ifinfo
@tex
The output of a vector $v$ in $K[x]^r$ with components $v_1,
\ldots, v_r$ has the format $v_1 * gen(1) + \ldots + v_r * gen(r)$
@end tex
unless the ordering starts with @code{c}.
@ifinfo
In this case a vector will be written as [v_1, @dots{}, v_r].
@end ifinfo
@tex
In this case a vector will be written as $[v_1, \ldots, v_r]$.
@end tex
In all cases @sc{Singular} can read the
input in both formats.

@c --------------------------------------------------------------------------
@node matrix orderings, product orderings, module orderings,Monomial orderings
@subsection matrix orderings
@cindex matrix orderings

Let M be an invertible n x n matrix with integer coefficients and
@ifinfo
M_1, @dots{}, M_n
@end ifinfo
@tex
M$_1, \ldots,$ M$_n$
@end tex
 the rows of M.

The M-ordering < is the following:
@ifinfo
x^a < x^b <==> there exists an i: 1 <= i <= n :
M_1*a = M_1*b, @dots{}, M_(i-1)*a = M_(i-1)*b, M_i*a < M_i*b.
@end ifinfo
@tex
$x^a < x^b \Leftrightarrow$  there exists an $i: 1 <= i <= n :$
M$_1*a = $M$_1*b, \ldots, $M$_{i-1}*a = $M$_{i-1}*b$ and M$_i*a < $M$_i*b$.
@end tex

Thus,
@ifinfo
x^a < x^b
@end ifinfo
@tex
$x^a < x^b$
@end tex
if and only if M*a is smaller than M*b
with respect to the lexicographical ordering.

It is known that any monomial ordering can be represented by a matrix M in
GL(n,R), but, of course, only integer coefficients are of relevance in
practice.

The following matrices represent (for 3 variables) the global and
local orderings defined above (note that the matrix is not uniquely determined
by the ordering):

@ifinfo
@table @asis
@item lp:
 1   0   0
@* 0   1   0
@* 0   0   1
@item dp:
 1   1   1
@* 0   0  -1
@* 0  -1   0
@item Dp:
 1   1   1
@* 1   0   0
@* 0   1   0
@item wp(1,2,3):
 1   2   3
@* 0   0  -1
@* 0  -1   0
@item Wp(1,2,3):
 1   2   3
@* 1   0   0
@* 0   1   0
@item ls:
-1   0   0
@* 0  -1   0
@* 0   0  -1
@item ds:
-1  -1  -1
@* 0   0  -1
@* 0  -1   0
@item Ds:
-1  -1  -1
@* 1   0   0
@* 0   1   0
@item ws(1,2,3):
-1  -2  -3
@* 0   0  -1
@* 0  -1   0
@item Ws(1,2,3):
-1  -2  -3
@* 1   0   0
@* 0   1   0
@end table
@end ifinfo
@tex

lp:
$\left(\matrix{
 1 & 0 & 0 \cr
 0 & 1 & 0 \cr
 0 & 0 & 1 \cr
 }\right)$
\quad dp:
$\left(\matrix{
 1 & 1 & 1 \cr
 0 & 0 &-1 \cr
 0 &-1 & 0 \cr
 }\right)$
\quad Dp:
$\left(\matrix{
 1 & 1 & 1 \cr
 1 & 0 & 0 \cr
 0 & 1 & 0 \cr
 }\right)$

wp(1,2,3):
$\left(\matrix{
 1 & 2 & 3 \cr
 0 & 0 &-1 \cr
 0 &-1 & 0 \cr
 }\right)$
\quad Wp(1,2,3):
$\left(\matrix{
 1 & 2 & 3 \cr
 1 & 0 & 0 \cr
 0 & 1 & 0 \cr
 }\right)$

ls:
$\left(\matrix{
-1 & 0 & 0 \cr
 0 &-1 & 0 \cr
 0 & 0 &-1 \cr
 }\right)$
\quad ds:
$\left(\matrix{
-1 &-1 &-1 \cr
 0 & 0 &-1 \cr
 0 &-1 & 0 \cr
 }\right)$
\quad Ds:
$\left(\matrix{
-1 &-1 &-1 \cr
 1 & 0 & 0 \cr
 0 & 1 & 0 \cr
 }\right)$

ws(1,2,3):
$\left(\matrix{
-1 &-2 &-3 \cr
 0 & 0 &-1 \cr
 0 &-1 & 0 \cr
 }\right)$
\quad Ws(1,2,3):
$\left(\matrix{
-1 &-2 &-3 \cr
 1 & 0 & 0 \cr
 0 & 1 & 0 \cr
 }\right)$
@end tex

Product orderings represented by  a matrix:

@ifinfo
@table @asis
@item (dp(3), wp(1,2,3)):
1  1  1  0  0  0
@*0  0  -1  0  0  0
@*0  -1  0  0  0  0
@*0  0  0  1  2  3
@*0  0  0  0  0  -1
@*0  0  0  0  -1  0
@item (Dp(3), ds(3)):
1  1  1  0  0  0
@*1  0  0  0  0  0
@*0  1  0  0  0  0
@*0  0  0  -1  -1  -1
@*0  0  0  0  0  -1
@*0  0  0  0  -1  0
@end table
@end ifinfo
@tex
@table @asis
@item (dp(3), wp(1,2,3)):
$\left(\matrix{
1&  1&  1&  0&  0&  0 \cr
0&  0&  -1&  0&  0&  0 \cr
0&  -1&  0&  0&  0&  0 \cr
0&  0&  0&  1&  2&  3 \cr
0&  0&  0&  0&  0&  -1 \cr
0&  0&  0&  0&  -1&  0 \cr
 }\right)$
@item (Dp(3), ds(3)):
$\left(\matrix{
1&  1&  1&  0&  0&  0 \cr
1&  0&  0&  0&  0&  0 \cr
0&  1&  0&  0&  0&  0 \cr
0&  0&  0&  -1&  -1&  -1 \cr
0&  0&  0&  0&  0&  -1 \cr
0&  0&  0&  0&  -1&  0 \cr
 }\right)$
@end table
@end tex

Orderings with extra weight vector (see below) represented by  a matrix:

@ifinfo
@table @asis
@item (dp(3), a(1,2,3),dp(3)):
1  1  1  0  0  0
@*0  0  -1  0  0  0
@*0  -1  0  0  0  0
@*0  0  0  1  2  3
@*0  0  0  1  1  1
@*0  0  0  0  0  -1
@*0  0  0  0  -1  0
@item (a(1,2,3,4,5),Dp(3), ds(3)):
1  2  3  4  5  0
@*1  1  1  0  0  0
@*1  0  0  0  0  0
@*0  1  0  0  0  0
@*0  0  0  -1  -1  -1
@*0  0  0  0  0  -1
@*0  0  0  0  -1  0
@end table
@end ifinfo
@tex
@table @asis
@item (dp(3), a(1,2,3),dp(3)):
$\left(\matrix{
1&  1&  1&  0&  0&  0 \cr
0&  0&  -1&  0&  0&  0 \cr
0&  -1&  0&  0&  0&  0 \cr
0&  0&  0&  1&  2&  3 \cr
0&  0&  0&  1&  1&  1 \cr
0&  0&  0&  0&  0&  -1 \cr
0&  0&  0&  0&  -1&  0 \cr
 }\right)$
@item (a(1,2,3,4,5),Dp(3), ds(3)):
$\left(\matrix{
1&  2&  3&  4&  5&  0 \cr
1&  1&  1&  0&  0&  0 \cr
1&  0&  0&  0&  0&  0 \cr
0&  1&  0&  0&  0&  0 \cr
0&  0&  0&  -1&  -1&  -1 \cr
0&  0&  0&  0&  0 & -1 \cr
0&  0&  0&  0&  -1&  0 \cr
 }\right)$
@end table
@end tex

@*@strong{Example}:
@smallexample
@c example
  ring r = 0, (x,y,z), M(1, 0, 0,
                         0, 1, 0,
                         0, 0, 1);
@c example
@end smallexample
@*which may also be written as:
@smallexample
@c example
  intmat m[3][3]=1, 0, 0, 0, 1, 0, 0, 0, 1;
  m;
  ring r = 0, (x,y,z), M(m);
  r;
@c example
@end smallexample

If the ring has n variables and the matrix contains less than n x n entries
an error message is given, if there are more entries,
the last ones will be ignored.

@strong{WARNING:} @sc{Singular}
does not check whether the matrix has full rank.   In such a case some
computations might not terminate, others might give a nonsense result.

Having these matrix orderings @sc{Singular} can compute standard bases for
any monomial ordering which is compatible with the natural semigroup structure.
In practice the global and local orderings together with block orderings should be
sufficient in most cases. These orderings are faster than the corresponding
matrix orderings, since evaluating a matrix product is time consuming.

@c --------------------------------------------------------------------------
@node product orderings, extra weight vector, matrix orderings, Monomial orderings
@subsection product orderings
@cindex product orderings

Let
@ifinfo
x = (x_1, @dots{}, x_n) = x(1..n) and y = (y_1, @dots{}, y_m) =
y(1..m)
@end ifinfo
@tex
$x = (x_1, \ldots, x_n) = x(1..n)$ and $y = (y_1, \ldots, y_m) =
y(1..m)$
@end tex
 be two ordered sets of variables,
@ifinfo
<_1 a monomial
ordering on Loc K[x] and <_2 a monomial ordering on Loc K[y].   The product
ordering (or block ordering) < = (<_1,<_2) on Loc K[x,y] is the following:
@*x^a y^b < x^A y^B <==>
@*x^a <_1 x^A
@*or
@*x^a = x^A  and  y^b <_2 y^B.
@end ifinfo
@iftex
@tex
$<_1$ a monomial
ordering on $Loc K[x]$ and $<_2$ a monomial ordering on $Loc K[y]$.   The product
ordering (or block ordering) $<\ := (<_1,<_2)$ on $Loc K[x,y]$ is the following:
@end tex
@*@tex
\quad \quad $x^a y^b < x^A y^B \Leftrightarrow x^a <_1 x^A$
@end tex
@*@tex
\phantom{\quad \quad $x^a y^b < x^A y^B \Leftrightarrow$}
or $x^a = x^A$ and $y^b <_2 y^B$.
@end tex
@end iftex

Inductively one defines the product ordering of more than two monomial
orderings.

In @sc{Singular}, any of the above global orderings, local orderings or matrix
ordering may be combined (in an arbitrary manner and length) to a product
ordering.   E.g. @code{(lp(3), M(1, 2, 3, 1, 1, 1, 1, 0, 0), ds(4), ws(1,2,3))}
defines: @code{lp} on the first 3 variables, the matrix ordering
@code{M(1, 2, 3, 1, 1, 1, 1, 0, 0)} on the next 3 variables,
@code{ds} on the next 4 variables and
@code{ws(1,2,3)} on the last 3 variables.

@c ------------------------------
@node rings, poly expression, intmat expression, Expressions
@section rings
@cindex rings
Every number, polynomial, vector, ideal, module and every matrix
(but not intmat)
in @sc{Singular} must be defined over a
base ring which is a polynomial ring over a field
or a localization hereof
(depending on the monomial ordering, see @ref{Monomial orderings})
or a quotient ring (factor ring) hereof modulo a standard basis.
The @code{ring} (resp. @code{qring} for quotient ring) command informs
@code{@sc{Singular}} about the coefficient field,
the names of indeterminants and the monomial ordering.
A definition of a ring sets this ring as the actual base ring.
The reserved word @code{basering} is an alias for the actual ring.
All subsequent definitions of
polynomials, vectors, ideals, modules and matrices
refer to this ring and are "local" to it
until a new ring is defined with a @code{ring} or a @code{qring}
or @code{setring} command.
Access to objects belonging to other rings
is only possible via a ring map,
i.e. via @code{map}, @code{imap} or @code{fetch}
(@code{imap} and @code{fetch} require that the rings are similiar enough).
@enumerate
@item
Coefficient fields are Z/p (p a prime <= 32003),
Galois fields GF(q) (q<=32761),
Q (the rational numbers), algebraic or transcedental extensions of Z/p or Q,
and real numbers (floats)
@item
The indeterminants (variables) of polynomials are names or indexed names
(e.g. @code{x,y} or @code{x(0),x(2),...} or @code{a(1..5)} for
@code{a(1),...,a(5)} or @code{b(5..1)} for @code{b(5),...,b(1)}
or @code{x1,x2,y1,y2}).
The set of indeterminants is always ordered.
@item
Monomial orderings are
the lexicographical ordering (@code{lp, ls}),
the degree reverse lexicographical ordering with weights 1 (@code{dp, ds})
or arbitrary weights (@code{wp, ws}),
the degree lexicographical ordering with weights 1 (@code{Dp, Ds})
or arbitrary weights (@code{Wp, Ws}),
or the matrix ordering (@code{M}).

The orderings @code{ls,ds,Ds,ws,Ws} describe orderings in series
rings; @code{lp,dp,Dp,wp,Wp} orderings in polynomial rings.
The orderings @code{lp,ls,dp,ds,wp,ws,Dp,Ds,Wp,Ws} can be combined
(yielding a block ordering).
They can also be combined with the special orderings @code{c, C}
(ordering of the components of a vector) and @code{a}
(inserting a weight vector into the order matrix).
See @ref{Monomial orderings}.
@end enumerate
See @ref{ring}; @ref{setring}; @ref{qring}; @ref{maps};
@ref{fetch}.
@c ---------------------------------------
@node links, procedures, list expression, Expressions
@section links
@cindex links

@table @code
@item @strong{Defintion:}
@*link_expression = previously declared link
@*link_expression = property_string @code{+} name_string
@*where
@*property_string = @code{""}, or type_string @code{+ ":" +} mode_string
@code{+ " "}
@*and
@*type_string = @code{""}, or @code{"Ascii"}, or @code{"MPfile"}, or
@code{"MPtcp"}, or @code{"DBM"}
@end table

@menu
* Link operations::
* Ascii links::
* MP links::
* DBM links::
@end menu
@iftex
See @ref{Ascii links}; @ref{MP links};  @ref{DBM links};
@end iftex

@c ---------------------------------------
@node Link operations, Ascii links, links, links
@subsection Link operations
@cindex Link operations
@c ---------------------------------------
@node Ascii links, MP links, Link operations, links
@subsection Ascii links
@cindex Ascii links
@table @code
@item @code{type_string:}
@code{"Ascii"} or @code{""}
@item @code{mode_string:}
@*@code{""}  // mode is set by first read/write
@*@code{"a"} // append mode (default for writing)
@*@code{"w"} // overwrite mode
@*@code{"r"} // read mode
@item @code{name_string:}
filename
@item @strong{Operations:}
@ref{open}, @ref{close}, @ref{status}, @ref{read}, @ref{write},
@ref{dump}, @ref{getdump}.
@item @strong{Restrictions:}

@end table
@c ---------------------------------------
@node MP links, DBM links, Ascii links, links
@subsection MP links
@cindex MP links
@menu
* MPfile links::
* MPtcp links::
@end menu

@c ---------------------------------------
@node MPfile links, MPtcp links, MP links, MP links
@subsubsection MPfile links
@cindex MPfile links

@table @code
@item @code{type_string:}
@code{"MPfile"}
@item @code{mode_string:}
@code{""} // mode is set by first read/write
@*@code{"a"} // append mode (default for writing)
@*@code{"w"} // overwrite mode
@*@code{"r"} // read mode
@item @code{name_string:}
filename
@item @strong{Operations:}
@ref{open}, @ref{close}, @ref{status}, @ref{read}, @ref{write},
@ref{dump}, @ref{getdump}, @ref{quote}, @ref{eval}.
@item @strong{Restrictions:}
@end table
@c ---------------------------------------
@node MPtcp links, , MPfile links, MP links
@subsubsection MPtcp links
@cindex MPtcp links

@table @code
@item type_string:
@code{"MPtcp"}
@sp 1
@item mode_string:
@code{"fork"}
@*@code{""} // default MPtcp mode is fork
@item mode_string:
@code{"launch"}
@item name_string:
host_spec @code{+} application_spec
@sp 1
@item mode_string:
@code{"listen"}
@item name_string:
port_spec
@sp 1
@item mode_string:
@code{"connect"}
@item name_string:
host_spec @code{+} port_spec
@sp 1
@item application_spec
@code{""} // "Singular -b" is used as default MPapplication
@*@code{" --MPapplication "+} application // application to launch; must be in search path
@item host_spec
@code{""} // localhost is used as default MPhost
@*@code{" --MPhost "} hostname // used host for connection
@item port_spec
@code{" --MPport "} portnumber // string specifying the port to use
@sp 1
@item @strong{Operations:}
@ref{open}, @ref{close}, @ref{status}, @ref{read}, @ref{write},
@ref{dump}, @ref{getdump}, @ref{quote}, @ref{eval}.
@end table
@c ---------------------------------------
@node DBM links, , MP links, links
@subsection DBM links
@cindex DBM links
@table @code
@item @code{type_string:}
@code{"DBM"}
@item @code{mode_string:}
@code{""} // mode is set by first read to "r"
@*@code{"r"} // read mode
@*@code{"rw"} // read and overwrite mode
@item @code{arguments:}
filename
@item @strong{Usage}
@code{read} ( link ) @expansion{} string
@*returns the key of the next entry of the data base
@sp 1
@code{read} ( link , key ) @expansion{} string
@*@code{read} returns the value to the key from the data base
@sp 1
@code{write} ( link , key , value )
@*inserts the pairs of strings (key, value) into the data base
(requires mode @code{"rw"})
@sp 1
@code{write} ( link , key )
@*delete the pair with key @code{key} from the data base
(requires mode @code{"rw"})
@item @strong{Restrictions:}
Arguments to @code{read} and @code{write} must be strings.
@end table
@c ---------------------------------------
@node procedures, maps, links, Expressions
@section procedures
@cindex procedures

Procedures are user defined functions with an arbritrary number of arguments
of any type which return a result.
They contain sequences of @sc{Singular} commands in a special format.
Procedures are used to extend the set of functions with your own functions.
Procedures are kept in the main memory (or in library files, see @ref{LIB}).
You can also store more than one procedure in a single file
(see @ref{procedures and Libraries}).
(E.g. the file @code{sing.lib} may contain the procedures @code{milnor} and @code{tjurina}.
After reading @code{sing.lib} the functions @code{milnor} and @code{tjurina} may be used
as if they were @sc{Singular} functions.) @*
Procedures can be "called" like a normal function by
typing their name followed by the list of arguments
in parentheses. If the procedure is not already in
main memory it will be loaded and kept there. The call then executes
the sequence of commands stored in the specified procedure.
@* See @ref{proc}; @ref{LIB}.
@c ---------------------------------------
@node untyped definitions, expression list, maps, Expressions
@section untyped definitions
@cindex untyped definitions

@* See @ref{def}.
@c ---------------------------------------
@node expression list, block, untyped definitions,Expressions
@section expression list
@c ------------------------------
@node block,implicit type conversions,expression list,Expressions
@section block
@c ------------------------------
@node implicit type conversions, type casting, block, Expressions
@section implicit type conversions
@cindex implicit type conversions
@c ---------------------------------------
@node Commands, procedures and Libraries, Expressions, Top
@chapter Commands
@cindex Commands
@ifinfo
@*List of all supported commands.
@end ifinfo
@menu
* Declaration commands::
* Functions::
* Control structures::
* Proc commands::
* Other commands::
* System variables::
@end menu
@c ---------------------------------------
@node Declaration commands, Functions, Commands, Commands
@section Declaration commands
@cindex Declaration commands
@c ---------------------------------------
@cindex proc
@table @code
@item @strong{Syntax:}
@code{proc} name block
@*@code{proc} name parameter_list block
@item @strong{Purpose:}
define a new function
@item @strong{Default:}
none
@item @strong{Example (for a procedure without an argument list):}
@smallexample
  // this proc tests if it is called with exactly one argument n
  // and print the numbers 1 to n
  // If the proc is called without an argument or with more
  // than one argument, a message is displayed
  // # is a reserved name and denotes the list of arguments,
  // #[i] is the i-th argument
  proc print_n
  @{
    if (size(#) != 1)
    @{
      "USAGE: print_n ( int_expression );";
      return();
    @}
    int i;
    for(i=1;i<=#[1];i=i+1)
    @{
      i;
    @}
  @}

  print_n();
  @expansion{} USAGE: print_n ( int_expression );
  print_n(1+2);
  @expansion{} 1
  @expansion{} 2
  @expansion{} 3
  print_n(1,2);
  @expansion{} USAGE: print_n ( int_expression );
@end smallexample
@end table
For a description of the paramter_list see @ref{parameter list}.
A convenient and recommended way to define procedures is to prepare a file
(see @ref{procedures and Libraries})
and read this file with the @code{LIB} command.
The difference between procedures from libraries and
other procedures is the missing help and example part
which may be provided in a library file.
@menu
* LIB::
* procedures and Libraries::
* procedures::
* proc in a library::
* Examples::
* Control structures::
* return::
@end menu
@iftex
See @ref{LIB}; @ref{procedures}; @ref{Examples}; @ref{Control structures}; @ref{return}.
@end iftex
@c ---------------------------------------
@node link,,proc,  Declaration commands
@subsection link
@cindex link
@table @code
@item @strong{Syntax:}
@code{link} name @code{=} string_expression @code{;}
@item @strong{Purpose:}
defines a new communcation link
@item @strong{Default:}
stdin/stdout
@end table
@menu
* links::
* read::
* write::
* open::
* close::
@end menu
@iftex
See @ref{links}; @ref{read}; @ref{write}; @ref{open}; @ref{close}.
@end iftex
@c ---------------------------------------------------------
@bye