@comment -*-texinfo-*-
@comment $Id$
@comment this file contains the type definitions

@c The following directives are necessary for proper compilation
@c with emacs (C-c C-e C-r).  Please keep it as it is.  Since it
@c is wrapped in `@ignore' and `@end ignore' it does not harm `tex' or
@c `makeinfo' but is a great help in editing this file (emacs
@c ignores the conditionals).

@ignore
%**start
\input texinfo.tex
@setfilename reference.info
@node Top, Data types
@menu
* Data types::
@end menu

@node Data types, Functions and system Variables, General concepts, Top
@chapter Data types
%**end
@end ignore

@cindex expression list
This chapter explains all data types of @sc{Singular} in
alphabetical order. For every type, there is a description of the
declaration syntax as well as information about how to build expressions
of certain types.

The term expression list in @sc{Singular} refers to any comma separated
list of expressions.

For the general syntax of a declaration see @ref{General command syntax}.

@menu
* bigint::
* def::
* ideal::
* int::
* intmat::
* intvec::
* link::
* list::
* map::
* matrix::
* module::
* number::
* package::
* poly::
* proc::
* qring::
* resolution::
* ring::
* string::
* vector::
* User defined types::
* pyobject::
@end menu

@c ---------------------------------------
@node bigint, def, Data types, Data types
@section bigint
@cindex bigint

Variables of type bigint represent the arbitrary long integers.
They can only be contructed from other types (int, number).

@menu
* bigint declarations::
* bigint expressions::
* bigint operations::
* bigint related functions::
@end menu

@c ---------------------------------------
@node bigint declarations, bigint expressions, bigint, bigint
@subsection bigint declarations
@cindex bigint declarations

@table @strong
@item Syntax:
@code{bigint} name @code{=} int_expression @code{;}

@item Purpose:
defines a long integer variable

@item Default:
0

@item Example:
@smallexample
@c example
  bigint i = 42;
  ring r=0,x,dp;
  number n=2;
  bigint j = i + bigint(n)^50; j;
@c example
@end smallexample
@end table

@c ------------------------------
@node bigint expressions, bigint operations, bigint declarations, bigint
@subsection bigint expressions
@cindex bigint expressions

A bigint expression is:
@enumerate
@item
an identifier of type bigint
@item
a function returning bigint
@item
an expression involving bigints and the arithmetic operations
@code{+}, @code{-}, @code{*}, @code{div},
@code{%} (@code{mod}), or @code{^}
@item
a type cast to bigint.
@end enumerate

@*@strong{Example:}
@smallexample
@c example
// Note: 11*13*17*100*200*2000*503*1111*222222
// returns a machine integer:
11*13*17*100*200*2000*503*1111*222222;
// using the type cast number for a greater allowed range
bigint(11)*13*17*100*200*2000*503*1111*222222;
@c example
@end smallexample

@c ref
See
@ref{int};
@ref{number};
@ref{Type conversion and casting}.
@c ref

@c ------------------------------
@node bigint operations, bigint related functions, bigint expressions, bigint
@subsection bigint operations
@cindex bigint operations
@cindex mod
@cindex div
@cindex +
@cindex -
@cindex *
@cindex /
@cindex ^

@c remark: the following table should have style @asis, since the
@c   commas below should not by set in style @code.
@table @asis
@item @code{+}
addition
@item @code{-}
negation or subtraction
@item @code{*}
multiplication
@item @code{div}
integer division (omitting the remainder >= 0)
@item @code{mod}
integer modulo (the remainder of the division @code{div}), always non-negative
@item @code{^}, @code{**}
exponentiation (exponent must be non-negative)
@item @code{<}, @code{>}, @code{<=}, @code{>=}, @code{==}, @code{<>}
comparators
@end table

@*@strong{Example:}
@smallexample
@c example
bigint(5)*2, bigint(2)^100-10;
bigint(-5) div 2, bigint(-5) mod 2;
@c example
@end smallexample

@c ------------------------------
@node bigint related functions, ,bigint operations, bigint
@subsection bigint related functions
@cindex bigint related functions

@table @code
@item gcd
greatest common divisor (see @ref{gcd})
@item memory
memory usage (see @ref{memory})
@end table

@c ref
See
@ref{memory};
@c ref

@c ---------------------------------------
@node def, ideal, bigint, Data types
@section def
@cindex def
@cindex untyped definitions
@cindex basering

Objects may be defined without a specific type: they inherit their
type from the first assignment to them.
E.g., @code{ideal i=x,y,z; def j=i^2;} defines the ideal @code{i^2}
with the name @code{j}.

@strong{Note:} Unlike other assignments a ring as an untyped object
is not a copy but another reference to the same (possibly unnamed) ring.
This means that entries in one of these rings appear also in the other ones.
The following defines a ring @code{s} which is just another reference (or name)
for the basering @code{r}.
The name @code{basering} is an alias for the current ring.

@smallexample
@c example
  ring r=32003,(x,y,z),dp;
  poly f = x;
  def s=basering;
  setring s;
  nameof(basering);
  listvar();
  poly g = y;
  kill f;
  listvar(r);
  ring t=32003,(u,w),dp;
  def rt=r+t;
  rt;
@c example
@end smallexample

This reference to a ring with def is useful if the basering
is not local to the procedure (so it cannot be accessed by its name) but one
needs a name for it (e.g., for a use with @code{setring} or @code{map}).
@code{setring r;} does not work in this case, because
@code{r} may not be local to the procedure.

@menu
* def declarations::
@end menu

@c ------------------------------
@node def declarations,  , def, def
@subsection def declarations
@cindex def declarations

@table @strong
@item Syntax:
@code{def} name @code{=} expression @code{;}

@item Purpose:
defines an object of the same type as the right-hand side.

@item Default:
none

@item Note:
This is useful if the right-hand side may be of
variable type as a consequence of a computation (e.g., ideal or module or
matrix). It may also be used in procedures to give the basering a name which
is local to the procedure.

@item Example:
@smallexample
@c example
  def i=2;
  typeof(i);
@c example
@end smallexample
@end table

@c ref
See
@ref{typeof}.
@c ref

@c ---------------------------------------
@node ideal, int, def, Data types
@section ideal
@cindex ideal

Ideals are represented as lists of polynomials which generate the ideal.
Like polynomials they
can only be defined or accessed with respect to a basering.

@strong{Note:} @code{size} counts only the non-zero generators of an ideal
whereas @code{ncols} counts all generators; see @ref{size}, @ref{ncols}.
@menu
* ideal declarations::
* ideal expressions::
* ideal operations::
* ideal related functions::
@end menu

@c ---------------------------------------
@node ideal declarations, ideal expressions, ideal, ideal
@subsection ideal declarations
@cindex ideal declarations

@table @strong
@item Syntax:
@code{ideal} name @code{=} list_of_poly_and_ideal_expressions @code{;}
@*@code{ideal} name @code{=} ideal_expression @code{;}

@item Purpose:
defines an ideal.

@item Default:
0

@item Example:
@smallexample
@c example
  ring r=0,(x,y,z),dp;
  poly s1 = x2;
  poly s2 = y3;
  poly s3 = z;
  ideal i =  s1, s2-s1, 0,s2*s3, s3^4;
  i;
  size(i);
  ncols(i);
@c example
@end smallexample
@end table

@c ------------------------------
@node ideal expressions, ideal operations, ideal declarations, ideal
@subsection ideal expressions
@cindex ideal expressions

An ideal expression is:
@enumerate
@item
an identifier of type ideal
@item
a function returning an ideal
@item
a combination of ideal expressions by the arithmetic operations
@code{+} or @code{*}
@item
a power of an ideal expression (operator @code{^} or @code{**})
@*Note that the computation of the product @code{i*i} involves
all products of generators of @code{i} while @code{i^2} involves
only the different ones, and is therefore faster.
@item
a type cast to ideal
@end enumerate

@*@strong{Example:}
@smallexample
@c example
  ring r=0,(x,y,z),dp;
  ideal m = maxideal(1);
  m;
  poly f = x2;
  poly g = y3;
  ideal i = x*y*z , f-g, g*(x-y) + f^4 ,0, 2x-z2y;
  ideal M = i + maxideal(10);
  timer =0;
  i = M*M;
  timer;
  ncols(i);
  timer =0;
  i = M^2;
  ncols(i);
  timer;
  i[ncols(i)];
  vector v = [x,y-z,x2,y-x,x2yz2-y];
  ideal j = ideal(v);
@c example
@end smallexample

@c ------------------------------
@node ideal operations, ideal related functions, ideal expressions, ideal
@subsection ideal operations
@cindex ideal operations
@cindex +
@cindex *
@cindex ^

@table @asis
@item @code{+}
addition (concatenation of the generators and simplification)

@item @code{*}
multiplication (with ideal, poly, vector, module; simplification in case of
multiplication with ideal)

@item @code{^}
exponentiation (by a non-negative integer)

@item ideal_expression @code{[} intvec_expression @code{]}
are polynomial generators of the ideal, index 1 gives the first generator.
@end table

@strong{Note:} For simplification of an ideal, see also @ref{simplify}.

@*@strong{Example:}
@smallexample
@c example
  ring r=0,(x,y,z),dp;
  ideal I = 0,x,0,1;
  I;
  I + 0;    // simplification
  ideal J = I,0,x,x-z;;
  J;
  I * J;   //  multiplication with simplification
  I*x;
  vector V = [x,y,z];
  print(V*I);
  ideal m = maxideal(1);
  m^2;
  ideal II = I[2..4];
  II;
@c example
@end smallexample

@c ------------------------------
@node ideal related functions,  , ideal operations, ideal
@subsection ideal related functions
@cindex ideal related functions

@table @code
@item char_series
irreducible characteristic series (see @ref{char_series})
@item coeffs
matrix of coefficients (see @ref{coeffs})
@item contract
contraction by an ideal (see @ref{contract})
@item diff
partial derivative (see @ref{diff})
@item degree
multiplicity, dimension and codimension of the ideal of leading terms (see @ref{degree})
@item dim
Krull dimension of basering modulo the ideal of leading terms (see @ref{dim})
@item eliminate
elimination of variables (see @ref{eliminate})
@item facstd
factorizing Groebner basis algorithm (see @ref{facstd})
@item factorize
ideal of factors of a polynomial (see @ref{factorize})
@item fglm
Groebner basis computation from a Groebner basis w.r.t.@: a different
ordering (see @ref{fglm})
@item finduni
computation of univariate polynomials lying in a zero dimensional ideal
(see @ref{finduni})
@item groebner
Groebner basis computation (a wrapper around @code{std,stdhilb,stdfglm},...)
(see @ref{groebner})
@item highcorner
the smallest monomial not contained in the ideal.
The ideal has to be zero-dimensional.
(see @ref{highcorner})
@item homog
homogenization with respect to a variable (see @ref{homog})
@item hilb
Hilbert series of a standard basis (see @ref{hilb})
@item indepSet
sets of independent variables of an ideal (see @ref{indepSet})
@item interred
interreduction of an ideal (see @ref{interred})
@item intersect
ideal intersection (see @ref{intersect})
@item jacob
ideal of all partial derivatives resp.@: jacobian matrix (see @ref{jacob})
@item jet
Taylor series up to a given order (see @ref{jet})
@item kbase
vector space basis of basering modulo ideal of leading terms
(see @ref{kbase})
@item koszul
Koszul matrix (see @ref{koszul})
@item lead
leading terms of a set of generators (see @ref{lead})
@item lift
lift-matrix (see @ref{lift})
@item liftstd
standard basis and transformation matrix computation (see @ref{liftstd})
@item lres
free resolution for homogeneous ideals (see @ref{lres})
@item maxideal
power of the maximal ideal at 0 (see @ref{maxideal})
@item minbase
minimal generating set of a homogeneous ideal, resp.@: module, or an ideal, resp.@: module, in a local ring
(see @ref{minbase})
@item minor
set of minors of a matrix (see @ref{minor})
@item modulo
representation of
@tex
$(h1+h2)/h1 \cong h2/(h1 \cap h2)$
@end tex
@ifinfo
(h1+h2)/h1=h2/(h1 intersect h2)
@end ifinfo
(see @ref{modulo})
@item mres
minimal free resolution of an ideal resp.@: module w.r.t. a minimal set of generators of the given ideal resp.@: module
(see @ref{mres})
@item mstd
standard basis and minimal generating set of an ideal (see @ref{mstd})
@item mult
multiplicity, resp.@: degree, of the ideal of leading terms (see @ref{mult})
@item ncols
number of columns (see @ref{ncols})
@item nres
a free resolution of an ideal resp.@: module M which is
minimized from the second free module on (see @ref{nres})
@item preimage
preimage under a ring map (see @ref{preimage})
@item qhweight
quasihomogeneous weights of an ideal (see @ref{qhweight})
@item quotient
ideal quotient (see @ref{quotient})
@item reduce
normalform with respect to a standard basis (see @ref{reduce})
@item res
free resolution of an ideal resp.@: module but not changing the given ideal resp.@: module
(see @ref{res})
@item simplify
simplification of a set of polynomials (see @ref{simplify})
@item size
number of non-zero generators (see @ref{size})
@item slimgb
Groebner basis computation with slim technique (see @ref{slimgb})
@item sortvec
permutation for sorting ideals resp@:. modules (see @ref{sortvec})
@item sres
free resolution of a standard basis (see @ref{sres})
@item std
standard basis computation (see @ref{std})
@item stdfglm
standard basis computation with fglm technique (see @ref{stdfglm})
@item stdhilb
Hilbert driven standard basis computation (see @ref{stdhilb})
@item subst
substitution of a ring variable (see @ref{subst})
@item syz
computation of the first syzygy module (see @ref{syz})
@item vdim
vector space dimension of basering modulo ideal of leading terms
(see @ref{vdim})
@item weight
optimal weights (see @ref{weight})
@end table

@c ---------------------------------------
@node int, intmat, ideal, Data types
@section int
@cindex int

Variables of type int represent the machine integers and are, therefore,
limited  in their range (e.g., the range is between
-2147483647 and 2147483647 on 32-bit machines). They are mainly used
to count things (dimension, rank, etc.),
in loops (see @ref{for}), and
to represent boolean values
(FALSE is represented by 0, every other value means TRUE, see
@ref{boolean expressions}).

Integers consist of a sequence of digits, possibly preceded by a sign.
A space is considered as a separator, so it is not allowed between digits.
A sequence of digits outside the allowed range is converted to the type
@code{bigint}, see @ref{bigint}.

@menu
* int declarations::
* int expressions::
* int operations::
* boolean expressions::
* boolean operations::
* int related functions::
@end menu

@c ---------------------------------------
@node int declarations, int expressions, int, int
@subsection int declarations
@cindex int declarations

@table @strong
@item Syntax:
@code{int} name @code{=} int_expression @code{;}

@item Purpose:
defines an integer variable.

@item Default:
0

@item Example:
@smallexample
@c example
  int i = 42;
  int j = i + 3; j;
  i = i * 3 - j; i;
  int k;   // assigning the default value 0 to k
  k;
@c example
@end smallexample
@end table

@c ------------------------------
@node int expressions, int operations, int declarations, int
@subsection int expressions
@cindex int expressions

An int expression is:
@enumerate
@item
a sequence of digits (if the number represented by this sequence is too
large to fit into the range of integers it is automatically
converted to the type number, if a basering is defined)
@item
an identifier of type int
@item
a function returning int
@item
an expression involving ints and the arithmetic operations
@code{+}, @code{-}, @code{*}, @code{div}, @code{/},
@code{%} (@code{mod}), or @code{^}
@item a boolean expression
@item
a type cast to int
@end enumerate

@strong{Note:}
Variables of type int represent the compiler integers  and are, therefore,
limited  in their range (see @ref{Limitations}). If this range is too small
the expression must be converted to the type number over a ring with
characteristic 0.

@*@strong{Example:}
@smallexample
@c example error
12345678901; // too large
typeof(_);
ring r=0,x,dp;
12345678901;
typeof(_);
// Note: 11*13*17*100*200*2000*503*1111*222222
// returns a machine integer:
11*13*17*100*200*2000*503*1111*222222;
// using the type cast number for a greater allowed range
number(11)*13*17*100*200*2000*503*1111*222222;
ring rp=32003,x,dp;
12345678901;
typeof(_);
intmat m[2][2] = 1,2,3,4;
m;
m[2,2];
typeof(_);
det(m);
m[1,1] + m[2,1] == trace(m);
! 0;
1 and 2;
intvec v = 1,2,3;
def d =transpose(v)*v;    // scalarproduct gives an 1x1 intvec
typeof(d);
int i = d[1];             // access the first (the only) entry in the intvec
ring rr=31,(x,y,z),dp;
poly f = 1;
i = int(f);               // cast to int
// Integers may be converted to constant  polynomials by an assignment,
poly g=37;
// define the constant polynomial g equal to the image of
// the integer 37 in the actual coefficient field, here it equals 6
g;
@c example
@end smallexample

@c ref
See
@ref{number};
@ref{Type conversion and casting}.
@c ref

@c ------------------------------
@node int operations, int related functions, int expressions, int
@subsection int operations
@cindex int operations
@cindex mod
@cindex div
@cindex +
@cindex -
@cindex *
@cindex /
@cindex %

@c remark: the following table should have style @asis, since the
@c   commas below should not by set in style @code.
@table @asis
@item @code{++}
changes its operand to its successor, is itself no int expression
@item @code{--}
changes its operand to its predecessor, is itself no int expression
@item @code{+}
addition
@item @code{-}
negation or subtraction
@item @code{*}
multiplication
@item @code{/}
integer division (omitting the remainder), rounding toward 0
@item @code{div}
integer division (omitting the remainder >= 0)
@item @code{%}
integer modulo (the remainder of the division @code{/})
@item @code{mod}
integer modulo (the remainder of the division @code{div}), always non-negative
@item @code{^}, @code{**}
exponentiation (exponent must be non-negative)
@item @code{<}, @code{>}, @code{<=}, @code{>=}, @code{==}, @code{<>}
comparators
@end table

@strong{Note:} An assignment @code{j=i++;} or @code{j=i--;} is not allowed,
in particular it does not change
the value of @code{j}, see @ref{Limitations}.

@c @strong{Note:} @code{/} might no longer be available in the future.

@*@strong{Example:}
@smallexample
@c example error
  int i=1;
  int j;
  i++; i;  i--; i;
  // ++ and -- do not return a value as in C, cannot assign
  j = i++;
  // the value of j is unchanged
  j; i;
  i+2, 2-i, 5^2;
  5 div 2, 8%3;
  -5 div 2, -5 / 2, -5 mod 2, -5 % 2;
  1<2, 2<=2;
@c example
@end smallexample

@c ------------------------------
@node int related functions, boolean expressions,int operations, int
@subsection int related functions
@cindex int related functions

@table @code
@item char
characteristic of the coefficient field of a ring (see @ref{char})
@item deg
degree of a polynomial resp.@: vector (see @ref{deg})
@item det
determinant (see @ref{det})
@item dim
Krull dimension of basering modulo ideal of leading terms, resp.@:
dimension of module of leading terms (see @ref{dim})
@item extgcd
Bezout representation of gcd (see @ref{extgcd})
@item find
position of a substring in a string (see @ref{find})
@item gcd
greatest common divisor (see @ref{gcd})
@item koszul
Koszul matrix (see @ref{koszul})
@item memory
memory usage (see @ref{memory})
@item mult
multiplicity of an ideal, resp.@: module, of leading terms (see @ref{mult})
@item ncols
number of columns (see @ref{ncols})
@item npars
number of ring parameters (see @ref{npars})
@item nrows
number of rows of a matrix, resp.@:
the rank of the free module where the vector or module lives
(see @ref{nrows})
@item nvars
number of ring variables (see @ref{nvars})
@item ord
degree of the leading term of a polynomial resp.@: vector (see @ref{ord})
@item par
n-th parameter of the basering (see @ref{par})
@item pardeg
degree of a number considered as a polynomial in the ring parameters (see @ref{pardeg})
@item prime
the next lower prime (see @ref{prime})
@item random
a pseudo random integer between the given limits (see @ref{random})
@item regularity
regularity of a resolution (see @ref{regularity})
@item rvar
test, if the given expression or string is a ring variable (see @ref{rvar})
@item size
number of elements in an object (see @ref{size})
@item trace
trace of an integer matrix (see @ref{trace})
@item var
n-th ring variable of the basering (see @ref{var})
@item vdim
vector space dimension of basering modulo ideal of leading terms,
resp.@: of freemodule modulo module of leading terms (see @ref{vdim})
@end table

@c ------------------------------
@node boolean expressions, boolean operations, int related functions, int
@subsection boolean expressions
@cindex boolean expressions
@cindex ==
@cindex !=
@cindex <>
@cindex <=
@cindex >=

A boolean expression is an int expression used in a logical context:

@c item
@*An int expression <> 0 evaluates to @emph{TRUE} (represented by 1),
0 evaluates to @emph{FALSE} (represented by 0).

The following is the list of available comparisons of objects of the same type.

@strong{Note:} There are no comparisons for ideals and modules, resolutions
and maps.

@enumerate
@item
integer comparisons:
@smallexample
  i == j
  i != j    // or     i <> j
  i <= j
  i >= j
  i > j
  i < j
@end smallexample
@item
number comparisons:
@smallexample
  m == n
  m != n    // or     m <> n
  m < n
  m > n
  m <= n
  m >= n
@end smallexample
For numbers from Z/p or from field extensions not all operations are useful:
@* - 0 is always the smallest element,
@* - in Z/p the representatives in the range -(p-1)/2..(p-1)/2 when p>2 resp.
     0 and 1 for p=2 are used for comparisons,
@* - in field extensions the last two operations
(@code{>=,<=}) yield always TRUE (1) and
the @code{<} and @code{>} are equivalent to @code{!=}.
@item
polynomial or vector comparisons:
@smallexample
  f == g
  f != g    // or     f <> g
  f <= g    // comparing the leading term w.r.t. the monomial order
  f <  g
  f >= g
  f >  g
@end smallexample
@item
intmat or matrix comparisons:
@smallexample
  v == w
  v != w    // or     v <> w
@end smallexample
@item
intvec or  string comparisons:
@smallexample
  f == g
  f != g    // or     f <> g
  f <= g    // comparing lexicographically
  f >= g    // w.r.t. the order specified by ASCII
  f >  g
  f <  g
@end smallexample
@item
boolean expressions combined by boolean operations (@code{and},
@code{or}, @code{not})
@end enumerate

@strong{Note:}
@c ------------------------------------------------------------
@c   This piece of text exists also in the file singular.doc,
@c   chapter "Evaluation of logical expressions".
@c   If you change something here, change it there, too!
@c ------------------------------------------------------------
All arguments of a logical expression are first evaluated and
then the value of the logical expression is determined. For example, the
logical expression @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.

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}.

See @ref{Major differences to the C programming language}.

@c ------------------------------
@node boolean operations, , boolean expressions, int
@subsection boolean operations
@cindex boolean operations
@cindex and
@cindex &&
@cindex or
@cindex ||
@cindex not

@table @code
@item and
logical @code{and}, may also be written as @code{&&}

@item or
logical @code{or}, may also be written as @code{||}

@item not
logical @code{not}, may also be written as @code{!}
@end table

The precedence of the boolean operations is:

@enumerate
@item parentheses
@item comparisons
@item not
@item and
@item or
@end enumerate

@*@strong{Example:}
@smallexample
@c example
  (1>2) and 3;
  1 > 2 and 3;
  ! 0 or 1;
  !(0 or 1);
@c example
@end smallexample

@c ---------------------------------------
@node intmat, intvec, int, Data types
@section intmat
@cindex intmat

Integer matrices are matrices with integer entries. For the range of
integers see @ref{Limitations}. Integer matrices do not belong to a
ring, they may be defined without a basering being defined. An intmat
can be multiplied by and added to an int; in this case the int is
converted into an intmat of the right size with the integer on the
diagonal. The integer @code{1}, for example, is converted into the unit
matrix.

@menu
* intmat declarations::
* intmat expressions::
* intmat type cast::
* intmat operations::
* intmat related functions::
@end menu

@c ------------------------------
@node intmat declarations, intmat expressions, intmat, intmat
@subsection intmat declarations
@cindex intmat declarations

@table @strong
@item Syntax:
@code{intmat} name @code{=} intmat_expression @code{;}
@*@code{intmat} name @code{[} rows @code{] [} cols @code{] =} intmat_expression @code{;}
@*@code{intmat} name @code{[} rows @code{] [} cols @code{] =} list_of_int_and_intvec_and_intmat_expressions @code{;}
@*rows and cols must be positive int expressions.

@item Purpose:
defines an intmat variable.
@* Given a list of integers, the matrix is filled up with the first row
from the left to the right, then the second row and so on.
If the int_list contains less than rows*cols elements,
the matrix is filled up with zeros; if it contains more
elements, only the first rows*cols elements are used.

@item Default:
0 (1 x 1 matrix)

@item Example:
@smallexample
@c example
  intmat im[3][5]=1,3,5,7,8,9,10,11,12,13;
  im;
  im[3,2];
  intmat m[2][3] = im[1..2,3..5];  // defines a submatrix
  m;
@c example
@end smallexample
@end table

@c ------------------------------
@node intmat expressions, intmat type cast, intmat declarations, intmat
@subsection intmat expressions
@cindex intmat expressions

An intmat expression is:
@enumerate
@item
an identifier of type intmat
@item
a function returning intmat
@item
an intmat operation involving ints and int operations (@code{+}, @code{-}, @code{*}, @code{div}, @code{%})
@item
an expression involving intmats and the operations (@code{+}, @code{-}, @code{*})
@item
a type cast to intmat (@pxref{intmat type cast})
@end enumerate

@*@strong{Example:}
@smallexample
@c example
  intmat Idm[2][2];
  Idm +1;          // add the unit intmat
  intmat m1[3][2] = _,1,-2;  // take entries from the last result
  m1;
  intmat m2[2][3]=1,0,2,4,5,1;
  transpose(m2);
  intvec v1=1,2,4;
  intvec v2=5,7,8;
  m1=v1,v2;         // fill m1 with v1 and v2
  m1;
  trace(m1*m2);
@c example
@end smallexample
@c ref
See
@ref{number};
@ref{Type conversion and casting}.
@c ref

@c ------------------------------
@node intmat type cast,  intmat operations, intmat expressions, intmat
@subsection intmat type cast
@cindex intmat type cast
@table @code
@item @strong{Syntax:}
@code{intmat (} expression @code{)}
@*@code{intmat (} expression, int_n, int_m  @code{)}
@item @strong{Type:}
intmat
@item @strong{Purpose:}
Converts expression to an intmat, where expression must be of type
intvec, or intmat. If
int_n and int_m are supplied, then they specify the dimension of the
intmat. Otherwise, the size (resp.@: dimensions) of the intmat
are determined  by the size (resp.@: dimensions) of the
expression.
@item @strong{Example:}
@smallexample
@c example
  intmat(intvec(1));
  intmat(intvec(1), 1, 2);
  intmat(intvec(1,2,3,4), 2, 2);
  intmat(_, 2, 3);
  intmat(_, 2, 1);
@c example
@end smallexample
@end table
@c ref
See
@ref{intmat};
@ref{Type conversion and casting};
@ref{matrix type cast}.
@c ref
@c ------------------------------
@node intmat operations, intmat related functions, intmat type cast, intmat
@subsection intmat operations
@cindex intmat operations
@cindex +
@cindex -
@cindex *

@table @asis
@item @code{+}
addition with intmat or int; the int is converted into a diagonal intmat

@item @code{-}
negation or subtraction with intmat or int; the int is converted into a
diagonal intmat

@item @code{*}
multiplication with intmat, intvec, or int; the int is converted into a
diagonal intmat

@item @code{div,/}
division of entries in the integers (omitting the remainder)
@item @code{%, mod}
entries modulo int (remainder of the division)
@item @code{<>}, @code{==}
comparators

@item intmat_expression @code{[} intvec_expression@code{,} intvec_expression @code{]}
is an intmat entry, where the first index indicates the row and the
second the column
@end table

@*@strong{Example:}
@smallexample
@c example
  intmat m[2][4] = 1,0,2,4,0,1,-1,0,3,2,1,-2;
  m;
  m[2,3];          // entry at row 2, col 3
  size(m);         // number of entries
  intvec v = 1,0,-1,2;
  m * v;
  typeof(_);
  intmat m1[4][3] = 0,1,2,3,v,1;
  intmat m2 = m * m1;
  m2;             //  2 x 3 intmat
  m2*10;           // multiply each entry of m with 10;
  -m2;
  m2 % 2;
  m2 div 2;
  m2[2,1];          // entry at row 2, col 1
  m1[2..3,2..3];   // submatrix
  m2[nrows(m2),ncols(m2)];      // the last entry of intmat m2
@c example
@end smallexample

@c ------------------------------
@node intmat related functions,  , intmat operations, intmat
@subsection intmat related functions
@cindex intmat related functions

@table @code
@item betti
Betti numbers of a free resolution (see @ref{betti})
@item det
determinant (see @ref{det})
@item ncols
number of cols (see @ref{ncols})
@item nrows
number of rows (see @ref{nrows})
@item random
pseudo random intmat (see @ref{random})
@item size
total number of entries (see @ref{size})
@item transpose
transpose of an intmat (see @ref{transpose})
@item trace
trace of an intmat (see @ref{trace})
@end table

@c ---------------------------------------
@node intvec, link, intmat, Data types
@section intvec
@cindex intvec

Variables of type intvec are lists of integers.  For the range of
integers see @ref{Limitations}. They may be used for simulating
sets of integers (and other sets if the intvec is used as an index set
for other objects). Addition and subtraction of an
intvec with an int or an intvec is done element-wise.
@c @example
@c @c example
@c   intvec iv=1,2,5,7;
@c   iv;
@c   iv[3];
@c   iv[7]=1;
@c   iv;
@c @c example
@c @end example

@menu
* intvec declarations::
* intvec expressions::
* intvec operations::
* intvec related functions::
@end menu

@c ------------------------------
@node intvec declarations, intvec expressions, intvec, intvec
@subsection intvec declarations
@cindex intvec declarations

@table @strong
@item Syntax:
@code{intvec} name @code{=} intvec_expression @code{;}
@*@code{intvec} name @code{=} list_of_int_and_intvec_expressions @code{;}

@item Purpose:
defines an intvec variable.
@* An intvec consists of an ordered list of integers.

@item Default:
0

@item Example:
@smallexample
@c example
  intvec iv=1,3,5,7,8;
  iv;
  iv[4];
  iv[3..size (iv)];
@c example
@end smallexample
@end table

@c ------------------------------
@node intvec expressions, intvec operations, intvec declarations, intvec
@subsection intvec expressions
@cindex intvec expressions
@cindex :
@cindex +
@cindex -
@cindex *
@cindex /
@cindex %

An intvec expression is:
@enumerate
@item
a range: int expression @code{..} int expression
@item
a repeated entry: int expression @code{:} positive int expression
@*(@code{a:b} generates an @code{intvec} of length @code{b}>0 with identical entries @code{a})
@item
a function returning intvec
@item
an expression involving intvec operations with int (@code{+}, @code{-}, @code{*}, @code{/}, @code{%})
@item
an expression of intvecs involving intvec operations (@code{+}, @code{-})
@item
an expression involving an intvec operation with intmat (@code{*})
@item
a type cast to intvec
@end enumerate

@*@strong{Example:}
@smallexample
@c example
  intvec v=-1,2;
  intvec w=v,v;         // concatenation
  w;
  w=2:3;                // repetition
  w;
  int k = 3;
  v = 7:k;
  v;
  v=-1,2;
  w=-2..2,v,1;
  w;
  intmat m[3][2] = 0,1,2,-2,3,1;
  m*v;
  typeof(_);
  v = intvec(m);
  v;
  ring r;
  poly f = x2z + 2xy-z;
  f;
  v = leadexp(f);
  v;
@c example
@end smallexample

@c ------------------------------
@node intvec operations, intvec related functions, intvec expressions, intvec
@subsection intvec operations
@cindex intvec operations

@table @asis
@item @code{+}
addition with intvec or int (component-wise)

@item @code{-}
negation or subtraction with intvec or int (component-wise)

@item @code{*}
multiplication with int (component-wise)

@item @code{/}, @code{div}
division by int (component-wise)

@item  @code{%, mod}
modulo (component-wise)

@item  @code{<>}, @code{==}, @code{<=}, @code{>=}, @code{>}, @code{<}
comparison (done lexicographically)

@item intvec_expression @code{[} int_expression @code{]}
is an element of the intvec; the first element has index one.
@end table

@*@strong{Example:}
@smallexample
@c example
  intvec iv =  1,3,5,7,8;
  iv+1;               // add 1 to each entry
  iv*2;
  iv;
  iv-10;
  iv=iv,0;
  iv;
  iv div 2;
  iv+iv;              // component-wise addition
  iv[size(iv)-1];     // last-1 entry
  intvec iw=2,3,4,0;
  iv==iw;             // lexicographic comparison
  iv < iw;
  iv != iw;
  iv[2];
  iw = 4,1,2;
  iv[iw];
@c example
@end smallexample

@c ------------------------------
@node intvec related functions,  , intvec operations, intvec
@subsection intvec related functions
@cindex intvec related functions

@table @code
@item hilb
Hilbert series as intvec (see @ref{hilb})
@item indepSet
sets of independent variables of an ideal (see @ref{indepSet})
@item leadexp
the exponent vector of the leading monomial (see @ref{leadexp})
@item monomial
the power product corresponding to the exponent vector (see @ref{monomial})
@item nrows
number of rows (see @ref{nrows})
@item qhweight
quasihomogeneous weights (see @ref{qhweight})
@item size
length of the intvec (see @ref{size})
@item sortvec
permutation for sorting ideals/modules (see @ref{sortvec})
@item transpose
transpose of an intvec, returns an intmat (see @ref{transpose})
@item weight
weights for the weighted ecart method (see @ref{weight})
@end table

@c ---------------------------------------
@node link, list, intvec, Data types
@section link
@cindex link

@c {{{ section link }}}
Links are the communication channels of @sc{Singular}, i.e.,
something @sc{Singular} can write to and/or read from. Currently,
@sc{Singular} supports four different link types:
@itemize @bullet
@item ASCII links (see
@ref{ASCII links})

@item MPfile links (see
@ref{MPfile links})

@item MPtcp links (see
@ref{MPtcp links})

@item ssi links (see
@ref{Ssi links})

@item pipe links (see
@ref{Pipe links})

@item DBM links (see
@ref{DBM links})
@end itemize

@menu
* link declarations::
* link expressions::
* link related functions::
* ASCII links::
* MP links::
* Ssi links::
* Pipe links::
* DBM links::
@end menu

@c ------------------------------
@node link declarations, link expressions, link, link
@subsection link declarations
@cindex link declarations

@table @strong
@item Syntax:
@code{link} name @code{=} string_expression @code{;}

@item Purpose:
defines a new communication link.

@item Default:
none

@item Example:
@smallexample
@c Tim: Let's only do the read here once, doing it twice without closing
@c it first might be confusing
@c example
  link l=":w example.txt";
  int i=22;          // cf. ASCII links for explanation
  string s="An int follows:";
  write(l,s,i);
  l;
  close(l);          //
  read(l);
  close(l);
@c example
@end smallexample
@end table

@c ------------------------------
@node link expressions, link related functions, link declarations, link
@subsection link expressions
@cindex link expressions

A link expression is:
@enumerate
@item
an identifier of type link
@item
a string describing the link
@end enumerate

A link is described by a string which consists of two parts: a property
string followed by a name string. The property string describes the type
of the link (@code{ASCII}, @code{MPfile}, @code{MPtcp} or @code{DBM})
and the mode of the link (e.g., open for read, write or append). The name
string describes the filename of the link, resp.@: a network connection
for MPtcp links.

For a detailed format description of the link describing string see:
@iftex
@itemize @bullet
@item for ASCII links:
@ref{ASCII links}

@item for MPfile links:
@ref{MPfile links}

@item for MPtcp links:
@ref{MPtcp links}

@item ssi links (see
@ref{Ssi links})

@item pipe links (see
@ref{Pipe links})

@item for DBM links:
@ref{DBM links}
@end itemize
@end iftex

@menu
* ASCII links::
* MPfile links::
* MPtcp links::
* Ssi links::
* Pipe links::
* DBM links::
@end menu

@c ------------------------------
@node link related functions, ASCII links, link expressions, link
@subsection link related functions
@cindex link related functions

@table @code
@item close
closes a link (see @ref{close})
@item dump
generates a dump of all variables and their values (see @ref{dump})
@item getdump
reads a dump (see @ref{getdump})
@item open
opens a link (see @ref{open})
@item read
reads from a link (see @ref{read})
@item status
gets the status of a link (see @ref{status})
@item write
writes to a link (see @ref{write})
@item kill
closes and kills a link (see @ref{kill})
@end table

@c ------------------------------
@node ASCII links, MP links, link related functions, link
@subsection ASCII links
@cindex ASCII links

Via ASCII links data that can be converted to a string can be written
into files for storage or communication with other programs. The data is
written in plain ASCII format. The output format of polynomials is done
w.r.t@:. the value of the global variable @code{short} (see @ref{short}).
Reading from an ASCII link returns a string --- conversion into other data
is up to the user. This can be done, for example,
using the command @code{execute}
(see @ref{execute}).

The ASCII link describing string has to be one of the following:

@enumerate
@item @code{"ASCII: "} + filename
@*the mode (read or append) is set by the first @code{read} or
@code{write} command.
@item @code{"ASCII:r "} + filename
@*opens the file for reading.
@item @code{"ASCII:w "} + filename
@*opens the file for overwriting.
@item @code{"ASCII:a "} + filename
@*opens the file for appending.
@end enumerate

There are the following default values:
@itemize @bullet
@item the type @code{ASCII} may be omitted since ASCII links are the
default links.

@item if non of @code{r}, @code{w}, or @code{a} is specified, the mode of
the link is set by the first @code{read} or @code{write} command on the
link. If the first command is @code{write}, the mode is set to @code{a}
(append mode).

@item if the filename is omitted, @code{read} reads from stdin and
@code{write} writes to stdout.
@end itemize

Using these default rules, the string @code{":r temp"} describes a link
which is equivalent to the link @code{"ASCII:r temp"}: an ASCII link to
the file @code{temp} which is opened for reading. The string
@code{"temp"} describes an ASCII link to the file @code{temp}, where the
mode is set by the first @code{read} or @code{write} command. See also
the example below.

Note that the filename may contain a path. On Microsoft Windows
(resp.@: MS-DOS) platforms, names of a drive can precede the filename, but
must be started with a @code{//} (as in @code{//c/temp/ex}. An ASCII
link can be used either for reading or for writing, but not for both at
the same time. A @code{close} command must be used before a change of
I/O direction. Types without a conversion to @code{string} cannot be
written.

@*@strong{Example:}
@smallexample
@c example
  ring r=32003,(x,y,z),dp;
  link l=":w example.txt";     // type is ASCII, mode is overwrite
  l;
  status(l, "open", "yes");    // link is not yet opened
  ideal i=x2,y2,z2;
  write (l,1,";",2,";","ideal i=",i,";");
  status(l, "open", "yes");    // now link is open
  status(l, "mode");           // for writing
  close(l);                    // link is closed
  write("example.txt","int j=5;");// data is appended to file
  read("example.txt");         // data is returned as string
  execute(read(l));            // read string is executed
  close(l);                    // link is closed
@c example
@c  // dump vars overwriting previous file content:
@c  dump(":w example.txt");
@end smallexample

@c ------------------------------
@node MP links, Ssi links, ASCII links, link
@subsection MP links
@cindex MP links

MP (Multi Protocol) links give the possibility to store and communicate
data in the binary MP format: Read and write access is very fast
compared to ASCII links. MP links can be established using files (link
type is @code{MPfile}) or using TCP sockets (link type is
@code{MPtcp}). All data (including such data that cannot be converted
to a string) can be written to an MP link. For ring-dependent data, a
ring description is written together with the data. Reading from an MP
link returns an expression (not a string) which was evaluated after the
read operation. If the expression read from an MP link is not from the
same ring as the current ring, then a @code{read} changes the current
ring.

@strong{Note:} Currently, MP links are only available on Unix platforms and data is
written without attributes (which is likely to change in future
versions). For a general description of MP, see
@code{http://www.symbolicnet.org/areas/protocols/mp.html}.

@menu
* MPfile links::
* MPtcp links::
@end menu

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

MPfile links provide the possibility to store data in a file using the
binary MP format. Read and write operations are very fast compared to
ASCII links. Therefore, for storing large amounts of data, MPfile links
should be used instead of ASCII links. Unlike ASCII links, data read
from MPfile links is returned as expressions one at a time, and not as a
string containing the entire content of the file. Furthermore, ring-dependent
data is stored together with a ring description. Therefore,
reading ring-dependent data might change the current ring.

The MPfile link describing string has to be one of the following:

@enumerate
@item @code{"MPfile: "} + filename
@*the mode (read or append) is set by the first @code{read} or
@code{write} command.
@item @code{"MPfile:r "} + filename
@*opens the file for reading.
@item @code{"MPfile:w "} + filename
@*opens the file for overwriting.
@item @code{"MPfile:a "} + filename
@*opens the file for appending.
@end enumerate

There are the following default values:
@itemize @bullet
@item if none of @code{r}, @code{w}, or @code{a} is specified, the mode of
the link is set by the first @code{read} or @code{write} command on the
link. If the first command is @code{write}, the mode is set to @code{a}
(append mode).
@c Tim: You and I were right here: It is indeed append. Olaf
@end itemize

Note that the filename may contain a path. An MPfile link can be used
either for reading or for writing, but not for both at the same time. A
@code{close} command must be used before a change of I/O direction.

@*@strong{Example:}
@smallexample
@c example
  ring r;
  link l="MPfile:w example.mp"; // type=MPfile, mode=overwrite
  l;
  ideal i=x2,y2,z2;
  write (l,1, i, "hello world");// write three expressions
  write(l,4);                   // append one more expression
  close(l);                     // link is closed
  // open the file for reading now
  read(l);                      // only first expression is read
  kill r;                       // no basering active now
  def i = read(l);              // second expression
  // notice that current ring was set, the name was assigned
  // automatically
  listvar(ring);
  def s = read(l);              // third expression
  listvar();
  close(l);                     // link is closed
  dump("MPfile:w example.mp");  // dump everything to example.mp
  kill i, s;                    // kill i and s
  getdump("MPfile: example.mp");// get previous dump
  listvar();                    // got all variables and values back
@c example
@end smallexample

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

MPtcp links give the possibility to exchange data in the binary MP
format between two processes which may run on the same or on different
computers. MPtcp links can be opened in four different modes:

@table @code
@item listen
@sc{Singular} acts as a server.

@item connect
@sc{Singular} acts as a client.

@item launch
@sc{Singular} acts as a client, launching an application as server.

@item fork
@sc{Singular} acts as a client, forking another @sc{Singular} as
server.
@end table

The MPtcp link describing string has to be
@itemize @bullet
@item listen mode:
@enumerate
@item @code{"MPtcp:listen --MPport "} + portnumber
@end enumerate
@sc{Singular} becomes a server and waits at the port for a
connect call.
@item connect mode:
@enumerate 2
@item @code{"MPtcp:connect --MPport "} + portnumber
@item @code{"MPtcp:connect --MPhost "} + hostname + @code{" --MPport "} +
portnumber
@end enumerate
@sc{Singular} becomes a client and connects to a server waiting at
the host and port.
@item launch mode:
@enumerate 4
@item @code{"MPtcp:launch"}
@item @code{"MPtcp:launch --MPrsh "} + rsh
@item @code{"MPtcp:launch --MPrsh "} + rsh  + @code{" --MPhost "} +
hostname
@item @code{"MPtcp:launch --MPrsh "} + rsh  + @code{" --MPhost "} +
hostname + @code{" --MPapplication "} + application
@end enumerate
@sc{Singular} becomes a client and starts (launches) the application
using the specified remote shell command (default is
@code{ssh}) on a (possibly) different host (default is @code{localhost}
which then acts as a server.
@item fork mode:
@enumerate 8
@item @code{"MPtcp:fork"}
@end enumerate
@sc{Singular} becomes a client and forks another @sc{Singular} on the
same host which acts as a server.
@end itemize

There are the following default values:
@itemize @bullet
@item if none of @code{listen}, @code{connect}, @code{launch} or
@code{fork} is specified, the default mode is set to @code{fork}.

@item if no remote shell (rsh) command is specified, then the command
@code{ssh} is used.

@item if no application is specified in mode @code{launch} the default
application is the value of @code{system("Singular") + "-bq"}.
(This evaluates to the absolute path of the @sc{Singular} currently running
with the option @code{"-bq"} appended.)

@item if no hostname is specified the local host is used as default host.
@end itemize

To open an MPtcp link in launch mode, the application to launch must
either be given with an absolute pathname, or must be in a directory
contained in the search path. The launched application acts as a server,
whereas the @sc{Singular} that actually opened the link acts as a
client. @sc{Singular} automatically appends the command line arguments
"@code{--MPmode connect --MPhost} hostname @code{--MPport} portnumber"
to the command line of the server application. Both hostname and
portnumber are substituted by the values from the link
specification. The client "listens" at the given port until the server
application does a connect call. If @sc{Singular} is used as server
application it has to be started with the command line option @code{-b}.
Since launching is done using a remote shell command, the host on which
the application should run must have an entry in the @code{.rhosts}
file. Even the local machine must have an entry if applications are to
be launched locally.

If the MPtcp link is opened in fork mode a child of the current
@sc{Singular} is forked. All variables and their values are inherited by
the child. The child acts as a server whereas the @sc{Singular} that
actually opened the link acts as a client.

To arrange the evaluation of an expression by a server, the expression
must be quoted using the command @code{quote} (see @ref{quote}), so that
a local evaluation is prevented. Otherwise, the expression is evaluated
first, and the result of the evaluation is written, instead of the
expression which is to be evaluated.

If @sc{Singular} is in server mode, the value of the variable
@code{link_ll} is the MPtcp link connecting to the client and
@sc{Singular} is in an infinite read-eval-write loop until the
connection is closed from the client side (by closing its connecting
link). Reading and writing is done to the link @code{link_ll}: After an
expression is read, it is evaluated and the result of the evaluation is
written back.  That is, for each expression which was written to the
server, there is exactly one expression written back. This might be an
"empty" expression, if the evaluation on the server side does not return
a value.

MPtcp links should explicitly be opened before being used. MPtcp links
are bidirectional, i.e. can be used for both, writing and
reading. Reading from an MPtcp link blocks until data was written to
that link. The @code{status} command can be used to check whether there
is data to read.

@*@strong{Example:}
@smallexample
@c example unix_only
  LIB "general.lib"; // needed for "killall" command
  link l="MPtcp:launch";
  open(l); l;        // l is ready for writing but not for reading

  ring r; ideal i=x2+y,xyz+z,x2+y2;

  write (l,quote(std(eval(i))));   // std(i) is computed on server
  def j = read(l);j; // result of computation on server is read

  write(l, quote(getdump(link_ll))); // server reads dump
  dump(l);           //  dump is written to server (includes proc's)
  read(l);           // result of previous write-command is read
  killall("not", "link"); killall("proc"); // kills everything, but links

  write(l, quote(dump(link_ll)));    // server writes dump
  getdump(l);        // dump is read from server
  read(l);           // result of previous write-command is read

  close(l);          // server is shut down
  listvar(all);      // same state as we had before "killall()"

  l = "MPtcp:";      // fork link declaration
  open(l); l;        // Notice that name is "parent"

  write(l, quote(status(link_ll, "name")));
  read(l);           // and name of forked link is "child"
  write(l,quote(i)); // Child inherited vars and their values
  read(l);
  close(l);          // shut down forked child
@c example
@end smallexample

@c -------------------------------------------------------------------
@node Ssi links, Pipe links, MP links, link
@subsection Ssi links
@cindex Ssi links

Ssi (simple singular interface) links give the possibility to store
and communicate data betweenm Singular processes:
Read and write access is very fast
compared to ASCII links. Ssi links can be established using files
or using TCP sockets.
For ring-dependent data, a
ring description is written together with the data. Reading from an Ssi
link returns an expression (not a string) which was evaluated after the
read operation. If the expression read from an Ssi link is not from the
same ring as the current ring, then a @code{read} changes the current
ring.

Currently under development - not everything is implemtented.

@menu
* Ssi file links::
* Ssi tcp links::
@end menu

@c -------------------------------------------------------------
@node Ssi file links, Ssi tcp links, Ssi  links, Ssi  links
@subsubsection Ssi file links
@cindex Ssi file links

Ssi file links provide the possibility to store data in a file using the
ssi format.
For storing large amounts of data, ssi file links
should be used instead of ASCII links. Unlike ASCII links, data read
from ssi file links is returned as expressions one at a time.

The ssi file link describing string has to be one of the following:

@enumerate
@item @code{"ssi:r "} + filename
@*opens the file for reading.
@item @code{"ssi:w "} + filename
@*opens the file for overwriting.
@item @code{"ssi:a "} + filename
@*opens the file for appending.
@end enumerate

Note that the filename may contain a path. An ssi file link can be used
either for reading or for writing, but not for both at the same time. A
@code{close} command must be used before a change of I/O direction.

@*@strong{Example:}
@smallexample
@c example
  ring r;
  link l="ssi:w example.ssi"; // type=ssi, mode=overwrite
  l;
  ideal i=x2,y2,z2;
  write (l,1, i, "hello world");// write three expressions
  write(l,4);                   // append one more expression
  close(l);                     // link is closed
  // open the file for reading now
  read(l);                      // only first expression is read
  kill r;                       // no basering active now
  def i = read(l);              // second expression
  // notice that current ring was set, the name was assigned
  // automatically
  listvar(ring);
  def s = read(l);              // third expression
  listvar();
  close(l);                     // link is closed
@c example
@end smallexample

@c -------------------------------------------------------------
@node Ssi tcp links,  , Ssi file links, Ssi  links
@subsubsection Ssi tcp links
@cindex Ssi tcp links

Ssi tcp links give the possibility to exchange data
between two processes which may run on the same or on different
computers. Ssi tcp links can be opened in four different modes:

@table @code
@item tcp
@sc{Singular} acts as a server.

@item connect
@sc{Singular} acts as a client.

@item tcp <host>:<program>
@sc{Singular} acts as a client, launching an application as server.

@item fork
@sc{Singular} acts as a client, forking another @sc{Singular} as
server.
@end table

The Ssi tcp link describing string has to be
@itemize @bullet
@item tcp mode:
@enumerate
@item @code{"ssi:tcp"}
@end enumerate
@sc{Singular} becomes a server and waits at the first free port (>1024) for a
connect call.
@item connect mode:
@enumerate 2
@item @code{"ssi:connect "} + host@code{:}port
@end enumerate
@sc{Singular} becomes a client and connects to a server waiting at
the host and port.
@item launch mode:
@enumerate 4
@item @code{"ssi:tcp"} + host@code{:}application
@end enumerate
@sc{Singular} becomes a client and starts (launches) the application
using ssh on a (possibly) different host
which then acts as a server.
@item fork mode:
@enumerate 8
@item @code{"ssi:fork"}
@end enumerate
@sc{Singular} becomes a client and forks another @sc{Singular} on the
same host which acts as a server.
@end itemize

To open an ssi tcp link in launch mode, the application to launch must
either be given with an absolute pathname, or must be in a directory
contained in the search path. The launched application acts as a server,
whereas the @sc{Singular} that actually opened the link acts as a
client.
The client "listens" at the some free port until the server
application does a connect call.

If the ssi tcp link is opened in fork mode a child of the current
@sc{Singular} is forked. All variables and their values are inherited by
the child. The child acts as a server whereas the @sc{Singular} that
actually opened the link acts as a client.

To arrange the evaluation of an expression by a server, the expression
must be quoted using the command @code{quote} (see @ref{quote}), so that
a local evaluation is prevented. Otherwise, the expression is evaluated
first, and the result of the evaluation is written, instead of the
expression which is to be evaluated.

If @sc{Singular} is in server mode, the value of the variable
@code{link_ll} is the ssi link connecting to the client and
@sc{Singular} is in an infinite read-eval-write loop until the
connection is closed from the client side (by closing its connecting
link).
Reading and writing is done to the link @code{link_ll}:
After an
expression is read, it is evaluated and the result of the evaluation is
written back.  That is, for each expression which was written to the
server, there is exactly one expression written back. This might be an
"empty" expression, if the evaluation on the server side does not return
a value.

Ssi tcp links should explicitly be opened before being used. Ssi tcp links
are bidirectional, i.e. can be used for both, writing and
reading. Reading from an ssi tcp link blocks until data was written to
that link. The @code{status} command can be used to check whether there
is data to read.

@*@strong{Example:}
@smallexample
@c example unix_only
  int i=7;
  link l = "ssi:fork";      // fork link declaration
  open(l); l;

  write(l,quote(i)); // Child inherited vars and their values
  read(l);
  close(l);          // shut down forked child
@c example
@end smallexample

@c -------------------------------------------------------------------
@node Pipe links, DBM links, Ssi links, link
@subsection Pipe links
@cindex Pipe links
Pipe links provide acces to stdin and stdout of any program.
Pipe links are bidirectional.
@strong{Syntax:} @code{"|: "} + string_for_system

The string_for system will be passed to @code{system} after conneting
the input and output to the corresponding stdout and stdin.

@strong{Example:}
@smallexample
@c example
  link l="|: date";
  open(l); l;
  read(l);
  l;
  close(l);
@c example
@end smallexample

@c ------------------------------
@node DBM links,  , Pipe links, link
@subsection DBM links
@cindex DBM links

DBM links provide access to data stored in a data base.
Each entry in the data base consists of a (key_string,
value_string) pair. Such a pair can be inserted with the command
@code{write(}link@code{,} key_string@code{,} value_string@code{)}.  By
calling @code{write(}link@code{,} key_string@code{)}, the entry with key
key_string is deleted from the data base. The value of an entry is
returned by the command @code{read(}link@code{,}
key_string@code{)}. With only one argument, @code{read(}link@code{)}
returns the next key in the data base. Using this feature a
data base can be scanned in order to access all entries of the data base.

If a data base with name @code{name} is opened for writing for the first
time, two files (@code{name.pag} and @code{name.dir}), which contain the
data base, are automatically created.

The DBM link describing string has to be one of the following:

@enumerate
@item @code{"DBM: "} + name
@*opens the data base for reading (default mode).

@item @code{"DBM:r "} + name
@*opens the data base for reading.

@item @code{"DBM:rw "} + name
@*opens the data base for reading and writing.
@end enumerate

Note that @code{name} must be given without the suffix @code{.pag} or
@code{.dir}. The name may contain an (absolute) path.

@*@strong{Example:}
@smallexample
@c example unix_only
  link l="DBM:rw example";
  write(l,"1","abc");
  write(l,"3","XYZ");
  write(l,"2","ABC");
  l;
  close(l);
  // read all keys (till empty string):
  read(l);
  read(l);
  read(l);
  read(l);
  // read data corresponding to key "1"
  read(l,"1");
  // read all data:
  read(l,read(l));
  read(l,read(l));
  read(l,read(l));
  // close
  close(l);
@c example
@end smallexample

@c ---------------------------------------
@node list, map, link, Data types
@section list
@cindex list

Lists are arrays whose elements can be of different types (including ring and
qring). If one element belongs to a ring the whole list belongs to that
ring. This applies also to the special list @code{#}. The expression
@code{list()} is the empty list.

Note that a list stores the objects itself and not the names.  Hence, if
@code{L} is a list, @code{L[1]} for example has no name.  A name, say
@code{R}, can be created for @code{L[1]} by @code{def R=L[1];}. To store
also the name of an object, say @code{r}, it can be added to the list
with @code{nameof(r);}. Rings and qrings may be objects of a list.

@strong{Note}: Unlike other assignments a ring as an element of a list
is not a copy but another reference to the same ring.

@menu
* list declarations::
* list expressions::
* list operations::
* list related functions::
@end menu

@c ------------------------------
@node list declarations, list expressions, list, list
@subsection list declarations
@cindex list declarations

@table @strong
@item Syntax:
@code{list} name @code{=} expression_list@code{;}
@*@code{list} name @code{=} list_expression@code{;}

@item Purpose:
defines a list (of objects of possibly different types).

@item Default:
empty list

@item Example:
@smallexample
@c example
  list l=1,"str";
  l[1];
  l[2];
  ring r;
  listvar(r);
  ideal i = x^2, y^2 + z^3;
  l[3] = i;
  l;
  listvar(r);     // the list l belongs now to the ring r
@c example
@end smallexample
@end table

@c ------------------------------
@node list expressions, list operations, list declarations, list
@subsection list expressions
@cindex list expressions

A list expression is:
@enumerate
@item
the empty list @code{list()}
@item
an identifier of type list
@item
a function returning list
@item
list expressions combined by the arithmetic operation @code{+}
@item
a type cast to list
@end enumerate

@c ref
See @ref{Type conversion and casting}.
@c ref

@*@strong{Example:}
@smallexample
@c example
  list l = "hello",1;
  l;
  l = list();
  l;
  ring r =0,x,dp;
  factorize((x+1)^2);
  list(1,2,3);
@c example
@end smallexample

@c ------------------------------
@node list operations, list related functions, list expressions, list
@subsection list operations
@cindex list operations

@table @asis
@item @code{+}
concatenation
@item @code{delete}
deletes one element from list, returns new list
@item @code{insert}
inserts or appends a new element to list, returns a new list
@item list_expression @code{[} int_expression @code{]}
is a list entry; the index 1 gives the first element.
@end table

@*@strong{Example:}
@smallexample
@c example
  list l1 = 1,"hello",list(-1,1);
  list l2 = list(1,5,7);
  l1 + l2;             // a new list
  l2 = delete(l2, 2);  // delete 2nd entry
  l2;
@c example
@end smallexample

@c ------------------------------
@node list related functions,  , list operations, list
@subsection list related functions
@cindex list related functions

@table @code
@item bareiss
returns a list of a matrix (lower triangular) and
of an intvec (permutations of columns, see @ref{bareiss})
@item betti
Betti numbers of a resolution (see @ref{betti})
@item delete
deletion of an element from a list (see @ref{delete})
@item facstd
factorizing Groebner basis algorithm (see @ref{facstd})
@item factorize
list of factors of a polynomial (see @ref{factorize})
@item insert
insertion of a new element into a list (see @ref{insert})
@item lres
free resolution (see @ref{lres})
@item minres
minimization of a free resolution (see @ref{minres})
@item mres
minimal free resolution of an ideal, resp.@: module w.r.t.
a minimal set of generators of the first module (see @ref{mres})
@item names
list of all user-defined variable names (see @ref{names})
@item res
free resolution of an ideal, resp.@: module (see @ref{res})
@item size
number of entries (see @ref{size})
@item sres
free resolution of an ideal, resp.@: module, given by a standard base (see @ref{sres})
@end table


@c ---------------------------------------
@node map, matrix, list, Data types
@section map
@cindex map

Maps are ring maps from a preimage ring into the basering.

@strong{Note:}
@itemize @bullet
@item
The target of a map is @strong{ALWAYS} the actual basering
@item
The preimage ring has to be stored "by its name", that means, maps can only be
used in such contexts, where the name of the preimage ring can be
resolved (this has to be considered in subprocedures).
@c (i.e., there might be problems for rings/maps defined in subprocedures).
See also @ref{Identifier resolution}, @ref{Names in procedures}.
@end itemize

Maps between rings with different coefficient fields are
possible and listed below.

Canonically realized are
@itemize @bullet
@item
@tex
$Q \rightarrow  Q(a, \ldots)$
@end tex
@ifinfo
Q -> Q(a,..)
@end ifinfo
     (@math{Q}: the rational numbers)
@item
@tex
$Q \rightarrow R$
@end tex
@ifinfo
Q -> R
@end ifinfo
     (@math{R}: the real numbers)
@item
@tex
$Q \rightarrow  C$
@end tex
@ifinfo
Q -> C
@end ifinfo
     (@math{C}: the complex numbers)
@item
@tex
$Z/p \rightarrow  (Z/p)(a, \ldots)$
@end tex
@ifinfo
Z/p ->(Z/p)(a,...)
@end ifinfo
     (@math{Z}: the integers)
@item
@tex
$Z/p \rightarrow  GF(p^n)$
@end tex
@ifinfo
Z/p -> GF(p^n)
@end ifinfo
     (@math{GF}: the Galois field)
@item
@tex
$Z/p \rightarrow  R$
@end tex
@ifinfo
Z/p -> R
@end ifinfo

@item
@tex
$R \rightarrow C$
@end tex
@ifinfo
R -> C
@end ifinfo
@end itemize

Possible are furthermore
@itemize @bullet
@item
@tex
% This is quite a hack, but for now it works.
$Z/p \rightarrow Q,
\quad
[i]_p \mapsto i \in [-p/2, \, p/2]
\subseteq Z$
@end tex
@ifinfo
Z/p -> Q : [i]_p -> i in [-p/2, p/2] in Z
@end ifinfo
@item
@tex
$Z/p \rightarrow Z/p^\prime,
\quad
[i]_p \mapsto i \in [-p/2, \, p/2] \subseteq Z, \;
i \mapsto [i]_{p^\prime} \in Z/p^\prime$
@end tex
@ifinfo
Z/p -> Z/p' : [i]_p in Z/p -> i in [-p/2,p/2] in Z, i -> [i]_p' in Z/p'
@end ifinfo
@item
@tex
$C \rightarrow R, \quad$ by taking the real part
@end tex
@ifinfo
C -> R by taking the real part.
@end ifinfo
@end itemize

Finally, in @sc{Singular} we allow the mapping from rings
with coefficient field Q to rings whose ground fields
have finite characteristic:

@itemize @bullet
@item
@tex
$Q \rightarrow Z/p$
@end tex
@ifinfo
Q -> Z/p
@end ifinfo

@item
@tex
$Q \rightarrow (Z/p)(a, \ldots)$
@end tex
@ifinfo
Q -> (Z/p)(a,..)
@end ifinfo
@end itemize
In these cases the denominator and the numerator
of a number are mapped separately by the usual
map from Z to Z/p, and the image of the number
is built again afterwards by division. It is thus
not allowed to map numbers whose denominator is
divisible by the characteristic of the target
ground field, or objects containing such numbers.
We, therefore, strongly recommend using such
maps only to map objects with integer coefficients.


@menu
* map declarations::
* map expressions::
* map operations::
* map related functions::
@end menu
@c @iftex
@c See @ref{imap}; @ref{fetch}; @ref{subst}.
@c @end iftex

@c ------------------------------
@node map declarations, map expressions, map, map
@subsection map declarations
@cindex map declarations

@table @strong
@item Syntax:
@code{map} name @code{=} preimage_ring_name @code{,} ideal_expression @code{;}
@*@code{map} name @code{=} preimage_ring_name @code{,} list_of_poly_and_ideal_expressions @code{;}
@*@code{map} name @code{=} map_expression @code{;}

@item Purpose:
defines a ring map from preimage_ring to basering.
@* Maps the variables of the preimage ring to the generators of the ideal.
If the ideal contains less elements than variables in the
preimage_ring the remaining variables are mapped to 0, if the ideal contains
more elements these are ignored.
The image ring is always the current basering.
For the mapping of coefficients from different fields see @ref{map}.

@item Default:
none

@item Note:
There are standard mappings for maps which are close to the identity
map: @code{fetch} and @code{imap}.

The name of a map serves as the function which maps objects from the
preimage_ring into the basering.  These objects must be defined
by names (no evaluation in the preimage ring is possible).

@item Example:
@smallexample
@c example
  ring r1=32003,(x,y,z),dp;
  ideal i=x,y,z;
  ring r2=32003,(a,b),dp;
  map f=r1,a,b,a+b;
  // maps from r1 to r2,
  // x -> a
  // y -> b
  // z -> a+b
  f(i);
  // operations like f(i[1]) or f(i*i) are not allowed
  ideal i=f(i);
  // objects in different rings may have the same name
  map g   = r2,a2,b2;
  map phi = g(f);
  // composition of map f and g
  // maps from r1 to r2,
  // x -> a2
  // y -> b2
  // z -> a2+b2
  phi(i);
@c example
@end smallexample
@end table

@c ref
See @ref{map}; @ref{ideal expressions}; @ref{ring};
@ref{imap}; @ref{fetch}.
@c ref

@c ------------------------------
@node map expressions, map operations, map declarations, map
@subsection map expressions
@cindex map expressions

A map expression is:
@enumerate
@item
an identifier of type map
@item
a function returning map
@item
map expressions combined by composition using parentheses (@code{(}, @code{)})
@end enumerate

@c ------------------------------
@node map operations, map related functions, map expressions, map
@subsection map operations

@cindex map operations

@table @asis
@item @code{( )}
composition of maps. If, for example, @code{f} and @code{g} are maps,
then @code{f(g)} is a map expression giving the composition
@tex
$f \circ g$
@end tex
@ifinfo
@code{f} @bullet{} @code{g}
@end ifinfo
 of @code{f} and @code{g},
@* provided the target ring of @code{g} is the basering of @code{f}.

@item map_expression @code{[} int_expressions @code{]}
is a map entry (the image of the corresponding variable)
@end table

@*@strong{Example:}
@smallexample
@c example
  ring r=0,(x,y),dp;
  map f=r,y,x;    // the map f permutes the variables
  f;
  poly p=x+2y3;
  f(p);
  map g=f(f);    // the map g defined as  f^2 is the identity
  g;
  g(p) == p;
@c example
@end smallexample

@c ------------------------------
@node map related functions,  , map operations, map
@subsection map related functions

@cindex map related functions

@table @code
@item fetch
the identity map between rings and qrings (see @ref{fetch})
@item imap
a convenient map procedure for inclusions and projections of rings (see @ref{imap})
@item preimage
preimage under a ring map (see @ref{preimage})
@item subst
substitution of a ring variable (see @ref{subst})
@end table

See also the libraries @ref{algebra_lib} and @ref{ring_lib}, which contain more
functions, related to maps.

@c ---------------------------------------
@node matrix, module, map, Data types
@section matrix
@cindex matrix

Objects of type matrix are matrices with polynomial entries.
Like polynomials they can
only be defined or accessed with respect to a basering. In order to
compute with matrices having integer or rational entries, define a ring
with characteristic 0 and at least one variable.

A matrix can be multiplied by and added to a poly; in this case the
polynomial is converted into a matrix of the right size with the polynomial on the
diagonal.

If A is a matrix then the assignment @code{module M=A;} or @code{module
M=module(A);} creates a module generated by the columns of A.  Note that
the trailing zero columns of A may be deleted by module operations with
M.

@menu
* matrix declarations::
* matrix expressions::
* matrix type cast::
* matrix operations::
* matrix related functions::
@end menu

@c ------------------------------
@node matrix declarations, matrix expressions, matrix, matrix
@subsection matrix declarations
@cindex matrix declarations

@table @strong
@item Syntax:
@code{matrix} name@code{[}rows@code{][}cols@code{] =} list_of_poly_expressions @code{;}
@*@code{matrix} name = matrix_expression @code{;}

@item Purpose:
defines a matrix (of polynomials).

The given poly_list fills up the matrix beginning with the first row
from the left to the right, then the second row and so on.
If the poly_list contains less than rows*cols elements,
the matrix is filled up with zeros; if it contains more
elements, then only the first rows*cols elements are used.
If the right-hand side is a matrix expression
the matrix on the left-hand side gets the same size as the right-hand side,
otherwise the size is determined by the left-hand side.
If the size is omitted a 1x1 matrix is created.

@item Default:
0 (1 x 1 matrix)

@item Example:
@smallexample
@c example
  int ro = 3;
  ring r = 32003,(x,y,z),dp;
  poly f=xyz;
  poly g=z*f;
  ideal i=f,g,g^2;
  matrix m[ro][3] = x3y4, 0, i, f ; // a 3 x 3 matrix
  m;
  print(m);
  matrix A;   // the 1 x 1 zero matrix
  matrix B[2][2] = m[1..2, 2..3]; //defines a submatrix
  print(B);
  matrix C=m; // defines C as a 3 x 3 matrix equal to m
  print(C);
@c example
@end smallexample
@end table

@c ------------------------------
@node matrix expressions, matrix type cast, matrix declarations, matrix
@subsection matrix expressions
@cindex matrix expressions

A matrix expression is:
@enumerate
@item
an identifier of type matrix
@item
a function returning matrix
@item
matrix expressions combined by the arithmetic operations
@code{+}, @code{-} or @code{*}
@item
a type cast to matrix (@pxref{matrix type cast})
@end enumerate

@*@strong{Example:}
@smallexample
@c example
  ring r=0,(x,y),dp;
  poly f= x3y2 + 2x2y2 +2;
  matrix H = jacob(jacob(f));    // the Hessian of f
  matrix mc = coef(f,y);
  print(mc);
  module MD = [x+y,1,x],[x+y,0,y];
  matrix M = MD;
  print(M);
@c example
@end smallexample

@c ------------------------------
@node matrix type cast,  matrix operations, matrix expressions, matrix
@subsection matrix type cast
@cindex matrix type cast
@table @code
@item @strong{Syntax:}
@code{matrix (} expression @code{)}
@*@code{matrix (} expression, int_n, int_m  @code{)}
@item @strong{Type:}
matrix
@item @strong{Purpose:}
Converts expression to a matrix, where expression must be of type int,
intmat, intvec, number, poly, ideal, vector, module, or matrix. If
int_n and int_m are supplied, then they specify the dimension of the
matrix. Otherwise, the size (resp.@: dimensions) of the matrix
is determined by the size (resp.@: dimensions) of the
expression.
@item @strong{Example:}
@smallexample
@c example
  ring r=32003,(x,y,z),dp;
  matrix(x);
  matrix(x, 1, 2);
  matrix(intmat(intvec(1,2,3,4), 2, 2));
  matrix(_, 2, 3);
  matrix(_, 2, 1);
@c example
@end smallexample
@end table
@c ref
See
@ref{matrix};
@ref{Type conversion and casting};
@ref{intmat type cast}.
@c ref
@c ------------------------------
@node matrix operations, matrix related functions, matrix type cast, matrix
@subsection matrix operations
@cindex matrix operations

@table @asis
@item @code{+}
addition with matrix or poly; the polynomial is converted into a diagonal
matrix

@item @code{-}
negation or subtraction with matrix or poly
(the first operand is expected to be a matrix);
the polynomial is converted into a diagonal matrix

@item @code{*}
multiplication with matrix or poly; the polynomial is converted into a
diagonal matrix

@item @code{/}
division by poly

@item @code{==}, @code{<>}, @code{!=}
comparators

@item matrix_expression @code{[} int_expression@code{,} int_expression @code{]}
is a matrix entry, where the first index indicates the row and the
second the column
@end table

@*@strong{Example:}
@smallexample
@c example
  ring r=32003,x,dp;
  matrix A[3][3] = 1,3,2,5,0,3,2,4,5; // define a matrix
  print(A); // nice printing of small matrices
  A[2,3];   // matrix entry
  A[2,3] = A[2,3] + 1; // change entry
  A[2,1..3] = 1,2,3;   // change 2nd row
  print(A);
  matrix E[3][3]; E = E + 1;  // the unit matrix
  matrix B =x*E - A;
  print(B);
  // the same (but x-A does not work):
  B = -A+x;
  print(B);
  det(B);        // the characteristic polynomial of A
  A*A*A - 8 * A*A - 2*A == E;  // Cayley-Hamilton
  vector v =[x,-1,x2];
  A*v; // multiplication of matrix and vector
  matrix m[2][2]=1,2,3;
  print(m-transpose(m));
@c example
@end smallexample

@c ------------------------------
@node matrix related functions,  , matrix operations, matrix
@subsection matrix related functions
@cindex matrix related functions

@table @code
@item bareiss
Gauss-Bareiss algorithm (see @ref{bareiss})
@item coef
matrix of coefficients and monomials (see @ref{coef})
@item coeffs
matrix of coefficients (see @ref{coeffs})
@item det
determinant (see @ref{det})
@item diff
partial derivative (see @ref{diff})
@item jacob
Jacobi matrix (see @ref{jacob})
@item koszul
Koszul matrix (see @ref{koszul})
@item lift
lift-matrix (see @ref{lift})
@item liftstd
standard basis and transformation matrix computation (see @ref{liftstd})
@item minor
set of minors of a matrix (see @ref{minor})
@item ncols
number of columns (see @ref{ncols})
@item nrows
number of rows (see @ref{nrows})
@item print
nice print format (see @ref{print})
@item size
number of matrix entries (see @ref{size})
@item subst
substitute a ring variable (see @ref{subst})
@item trace
trace of a matrix (see @ref{trace})
@item transpose
transposed matrix (see @ref{transpose})
@item wedge
wedge product (see @ref{wedge})
@end table

See also the library @ref{matrix_lib}, which contains more
matrix-related functions.

@c @*@strong{Example:}
@c @example
@c @end example

@c ---------------------------------------
@node module, number, matrix, Data types
@section module
@cindex module

Modules are submodules of a free module over the basering with basis
@code{gen(1)}, @code{gen(2)}, @dots{} .
They are represented by lists of vectors which generate the submodule.
Like vectors they
can only be defined or accessed with respect to a basering.

@iftex
If @math{R} is the basering, and @math{M} is a submodule of @math{R^n}
generated by vectors @math{v_1, \ldots, v_k}, then @math{v_1, \ldots, v_k}
may be considered as the generators of relations of @math{R^n/M} between the
canonical generators @code{gen(1)},@dots{},@code{gen(n)}. Hence any finitely
generated @math{R}-module can be represented in @sc{Singular} by its module
of relations. The assignments @code{module M=v1,...,vk; matrix A=M;} create
the presentation matrix of size n@math{\times}k for @math{R^n/M}, i.e., the
columns of A are the vectors @math{v_1, \ldots, v_k} which generate M (cf.
@ref{Representation of mathematical objects}).
@end iftex

@ifinfo
If @math{M} is a submodule of R^n,
@math{R} the basering, generated by vectors
v_1, @dots{}, v_k, then v_1, @dots{}, v_k
may be considered as the generators of relations of R^n/M
between the canonical generators @code{gen(1)},@dots{},@code{gen(n)}.
Hence any finitely generated @math{R}-module can be represented in @sc{Singular}
by its module of relations. The assignments
@code{module M=v1,...,vk; matrix A=M;}
create the presentation matrix of size
n x k for R^n/M,
i.e., the columns of A are the vectors v_1, @dots{}, v_k
which generate M (cf. @ref{Representation of mathematical objects}).
@end ifinfo

@menu
* module declarations::
* module expressions::
* module operations::
* module related functions::
@end menu

@c ------------------------------
@node module declarations, module expressions, module, module
@subsection module declarations
@cindex module declarations

@table @strong
@item Syntax:
@code{module} name @code{=} list_of_vector_expressions @code{;}
@*@code{module} name @code{=} module_expression @code{;}

@item Purpose:
defines a module.

@item Default:
[0]

@item Example:
@smallexample
@c example
  ring r=0,(x,y,z),(c,dp);
  vector s1 = [x2,y3,z];
  vector s2 = [xy,1,0];
  vector s3 = [0,x2-y2,z];
  poly   f  = xyz;
  module m = s1, s2-s1,f*(s3-s1);
  m;
  // show m in matrix format (columns generate m)
  print(m);
@c example
@end smallexample
@end table

@c ------------------------------
@node module expressions, module operations, module declarations, module
@subsection module expressions
@cindex module expressions

A module expression is:
@enumerate
@item
an identifier of type module
@item
a function returning module
@item
module expressions combined by the arithmetic operation @code{+}
@item
multiplication of a module expression with an ideal or a poly expression: @code{*}
@item
a type cast to module
@end enumerate

@c ref
See
@ref{ideal};
@ref{poly};
@ref{Type conversion and casting};
@ref{vector}.
@c ref

@c @*@strong{Example:}
@c @example
@c @c example
@c @c example
@c @end example

@c ------------------------------
@node module operations, module related functions, module expressions, module
@subsection module operations
@cindex module operations

@table @asis
@item @code{+}
addition (concatenation of the generators and simplification)

@item @code{*}
multiplication with ideal or poly (but not `module` * `module`!)

@item module_expression @code{[} int_expression @code{,} int_expression @code{]}
is a module entry, where the first index indicates the row and
the second the column

@item module_expressions @code{[} int_expression @code{]}
is a vector, where the index indicates the column (generator)
@end table

@*@strong{Example:}
@smallexample
@c example
  ring r=0,(x,y,z),dp;
  module m=[x,y],[0,0,z];
  print(m*(x+y));
  // this is not distributive:
  print(m*x+m*y);
@c example
@end smallexample

@c ------------------------------
@node module related functions,  , module operations, module
@subsection module related functions
@cindex module related functions

@table @code
@item coeffs
matrix of coefficients (see @ref{coeffs})
@item degree
multiplicity, dimension and codimension of the module of leading terms (see @ref{degree})
@item diff
partial derivative (see @ref{diff})
@item dim
Krull dimension of free module over the basering modulo the module of leading terms (see @ref{dim})
@item eliminate
elimination of variables (see @ref{eliminate})
@item freemodule
the free module of given rank (see @ref{freemodule})
@item groebner
Groebner basis computation (a wrapper around @code{std,stdhilb,stdfglm},...)
(see @ref{groebner})
@item hilb
Hilbert function of a standard basis (see @ref{hilb})
@item homog
homogenization with respect to a variable (see @ref{homog})
@item interred
interreduction of a module (see @ref{interred})
@item intersect
module intersection (see @ref{intersect})
@item jet
Taylor series up to a given order (see @ref{jet})
@item kbase
vector space basis of free module over the basering modulo the module of
leading terms (see @ref{kbase})
@item lead
initial module (see @ref{lead})
@item lift
lift-matrix (see @ref{lift})
@item liftstd
standard basis and transformation matrix computation (see @ref{liftstd})
@item lres
free resolution (see @ref{lres})
@item minbase
minimal generating set of a homogeneous ideal, resp.@: module, or an ideal, resp.@: module,
over a local ring
@item modulo
represents
@tex
$(h1+h2)/h1=h2/(h1 \cap h2)$
@end tex
@ifinfo
(h1+h2)/h1=h2/(h1 intersect h2)
@end ifinfo
(see @ref{modulo})
@item mres
minimal free resolution of an ideal resp.@: module w.r.t. a minimal set of generators of the given module
(see @ref{mres})
@item mult
multiplicity, resp.@: degree, of the module of leading terms (see @ref{mult})
@item nres
computation of a free resolution of an ideal resp.@: module M which is
minimized from the second free module on (see @ref{nres})
@item ncols
number of columns (see @ref{ncols})
@item nrows
number of rows (see @ref{nrows})
@item print
nice print format (see @ref{print})
@item prune
minimization of the embedding into a free module (see @ref{prune})
@item qhweight
quasihomogeneous weights of an ideal, resp.@: module (see @ref{qhweight})
@item quotient
module quotient (see @ref{quotient})
@item reduce
normalform with respect to a standard basis (see @ref{reduce})
@item res
free resolution of an ideal, resp.@: module, but not changing the given ideal, resp.@: module
(see @ref{res})
@item simplify
simplification of a set of vectors (see @ref{simplify})
@item size
number of non-zero generators (see @ref{size})
@item sortvec
permutation for sorting ideals/modules (see @ref{sortvec})
@item sres
free resolution of a standard basis (see @ref{sres})
@item std
standard basis computation (see @ref{std}, @ref{liftstd})
@item subst
substitution of a ring variable (see @ref{subst})
@item syz
computation of the first syzygy module (see @ref{syz})
@item vdim
vector space dimension of free module over the basering modulo module
of leading terms (see @ref{vdim})
@item weight
"optimal" weights (see @ref{weight})
@end table

@c @*@strong{Example:}
@c @example
@c @end example

@c ---------------------------------------
@node number, package, module, Data types
@section number
@cindex number
@cindex coefficient field
@cindex ground field
@cindex field
@cindex galois field
@cindex finite field
@cindex parameter, as numbers

Numbers are elements from the coefficient field (or ground field).
They can only be defined or accessed with respect to a basering
which determines the coefficient field. See @ref{ring declarations} for
declarations of coefficient fields.

@strong{Warning:} Beware of the special meaning of the letter @code{e}
(immediately following a sequence of digits) if the field is real (or complex),
@ref{Miscellaneous oddities}.

@menu
* number declarations::
* number expressions::
* number operations::
* number related functions::
@end menu

@c ------------------------------
@node number declarations, number expressions, number, number
@subsection number declarations
@cindex number declarations

@table @strong
@item Syntax:
@code{number} name @code{=} number_expression @code{;}

@item Purpose:
defines a number.

@item Default:
0

@item Note:
Numbers may only be declared w.r.t. the coefficient field of the current
basering, i.e., a ring
has to be defined prior to any number declaration. See @ref{Rings and
orderings} for a list of the available coefficient fields.

@item Example:
@smallexample
@c example
  // finite field Z/p, p<= 32003
  ring r = 32003,(x,y,z),dp;
  number n = 4/6;
  n;
  // finite field GF(p^n), p^n <= 32767
  // z is a primitive root of the minimal polynomial
  ring rg= (7^2,z),x,dp;
  number n = 4/9+z;
  n;
  // the rational numbers
  ring r0 = 0,x,dp;
  number n = 4/6;
  n;
  // algebraic extensions of Z/p or Q
  ring ra=(0,a),x,dp;
  minpoly=a^2+1;
  number n=a3+a2+2a-1;
  n;
  a^2;
  // transcedental extensions of Z/p or Q
  ring rt=(0,a),x,dp;
  number n=a3+a2+2a-1;
  n;
  a^2;
  // machine floating point numbers, single precision
  ring R_0=real,x,dp;
  number n=4/6;
  n;
  n=0.25e+2;
  n;
  // floating point numbers, arbitrary prescribed precision
  ring R_1=(real,50),x,dp;
  number n=4.0/6;
  n;
  n=0.25e+2;
  n;
  // floating point complex numbers, arbitrary prescribed precision
  // the third parameter gives the name of the imaginary unit
  ring R_2=(complex,50,i),x,dp;
  number n=4.0/6;
  n;
  n=0.25e+2*i+n;
  n;
@c example
@end smallexample
@end table

@c ------------------------------
@node number expressions, number operations, number declarations, number
@subsection number expressions
@cindex number expressions

A number expression is:
@enumerate
@item
a rational number (there are NO spaces allowed inside a rational number,
see @ref{int expressions})
@item
a floating point number (if the coefficient field is @code{real}):
@*<digits>@code{.}<digits>@code{e}<sign><digits>
@item
an identifier of type number
@item
a function returning number
@item
an int expression (see @ref{Type conversion and casting})
@item
number expressions combined by the arithmetic operations
@code{+}, @code{-}, @code{*}, @code{/}, @code{^}, or @code{**}.
@item
a type cast to number
@end enumerate

@*@strong{Example:}
@smallexample
@c example
  // the following expressions are in any ring int expressions
  2 / 3;
  4/ 8;
  2 /2;   // the notation of / for div might change in the future
  ring r0=0,x,dp;
  2/3, 4/8, 2/2 ; // are numbers

  poly f = 2x2 +1;
  leadcoef(f);
  typeof(_);
  ring rr =real,x,dp;
  1.7e-2; 1.7e+2; // are valid (but  1.7e2 not), if the field is `real`
  ring rp = (31,t),x,dp;
  2/3, 4/8, 2/2 ; // are numbers
  poly g = (3t2 +1)*x2 +1;
  leadcoef(g);
  typeof(_);
  par(1);
  typeof(_);
@c example
@end smallexample
@c ref
See
@ref{ring};
@ref{Type conversion and casting}.
@c ref

@c ------------------------------
@node number operations, number related functions, number expressions, number
@subsection number operations
@cindex number operations
@cindex mod

@table @asis
@item @code{+}
addition
@item @code{-}
negation or subtraction
@item @code{*}
multiplication
@item @code{/}
division
@item @code{^}, @code{**}
power, exponentiation (by an integer)
@item @code{<=, >=, ==, <>}
comparison
@item @code{mod}
integer modulo (the remainder of the division @code{div}), always non-negative
@end table

@strong{Note:} Quotient and exponentiation is only recognized as a
number expression if it is already a number, see @ref{Miscellaneous
oddities}.
@* For the behavior of comparison operators in rings with
ground field different from real or the rational numbers, see @ref{boolean
expressions}.

@*@strong{Example:}
@smallexample
@c example error
  ring r=0,x,dp;
  number n = 1/2 +1/3;
  n;
  n/2;
  1/2/3;
  1/2 * 1/3;
  n = 2;
  n^-2;
  // the following oddities appear here
  2/(2+3);
  number(2)/(2+3);
  2^-2; // for int's exponent must be non-negative
  number(2)^-2;
  3/4>=2/5;
  2/6==1/3;
@c example
@end smallexample

@c ------------------------------
@node number related functions,  , number operations, number
@subsection number related functions
@cindex number related functions

@table @code
@item cleardenom
cancellation of denominators of numbers in polyomial and divide it by its content
(see @ref{cleardenom})
@item impart
imaginary part of a complex number, 0 otherwise
(see @ref{impart}, @ref{repart})
@item numerator, denominator
the numerator/denominator of a rational number
(see @ref{numerator}, @ref{denominator})
@item leadcoef
coefficient of the leading term (see @ref{leadcoef})
@item par
n-th parameter of the basering (see @ref{par})
@item pardeg
degree of a number in ring parameters (see @ref{pardeg})
@item parstr
string form of ring parameters (see @ref{parstr})
@item repart
real part of a complex number
(see @ref{impart}, @ref{repart})
@end table

@c ---------------------------------------
@node package, poly, number, Data types
@section package
@cindex package
@cindex ::

The data type package is used to group identifiers into collections.
It is mainly used as an internal means to avoid collisions of names
of identifiers in libraries with variable names defined by the user.
The most important package is the toplevel package, called @code{Top}.
It contains all user defined identifiers as well as all user accessible
library procedures. Identifiers which are local to a library are contained
in a package whose name is obtained from the name of the library, where the
first letter is converted to uppercase, the remaining ones to lowercase.
Another reserved package name is @code{Current} which denotes the current
package name in use.
See also @ref{Libraries}.

@c * package expressions::
@c * package operations::
@menu
* package declarations::
* package related functions::
@end menu
@c ------------------------------
@node package declarations, package related functions, package, package
@subsection package declarations
@cindex package declarations

@table @strong
@item Syntax:
@code{package} name @code{;}

@item Purpose:
defines a package (Only relevant in very special situations).

@item Example:
@smallexample
@c example error
  package Test;
  int Test::i;
  listvar();
  listvar(Test);
  package dummy = Test;
  kill Test;
  listvar(dummy);
@c example
@end smallexample
@end table

@c ------------------------------
@node package related functions,  , package declarations, package
@subsection package related functions
@cindex package related functions

@table @code
@item exportto
      transfer an identifier to the specified package
(see @ref{exportto})
@item importfrom
      generate a copy of an identifier from the specified package in the
      current package
(see @ref{importfrom})
@item listvar
      list variables currently defined in a given package
(see @ref{listvar})
@item load
      load a library or dynamic module
(see @ref{load})
@item LIB
      load a library or dynamic module
(see @ref{LIB})
@end table

@c ---------------------------------------
@node poly, proc, package, Data types
@section poly
@cindex poly

Polynomials are the basic data for all main algorithms in
@code{@sc{Singular}}. They consist of finitely many terms
(coefficient*monomial) which are combined by the usual polynomial
operations (see @ref{poly expressions}). Polynomials can only be defined
or accessed with respect to a basering which determines the coefficient
type, the names of the indeterminates and the monomial ordering.

@smallexample
@c example
  ring r=32003,(x,y,z),dp;
  poly f=x3+y5+z2;
@c example
@end smallexample

@menu
* poly declarations::
* poly expressions::
* poly operations::
* poly related functions::
@end menu

@c ------------------------------
@node poly declarations, poly expressions, poly, poly
@subsection poly declarations
@cindex poly declarations

@table @strong
@item Syntax:
@code{poly} name @code{=} poly_expression @code{;}

@item Purpose:
defines a polynomial.

@item Default:
0

@item Example:
@smallexample
@c example
  ring r = 32003,(x,y,z),dp;
  poly s1  = x3y2+151x5y+186xy6+169y9;
  poly s2  = 1*x^2*y^2*z^2+3z8;
  poly s3  = 5/4x4y2+4/5*x*y^5+2x2y2z3+y7+11x10;
  int a,b,c,t=37,5,4,1;
  poly f=3*x^a+x*y^(b+c)+t*x^a*y^b*z^c;
  f;
  short = 0;
  f;
@c example
@end smallexample
@end table
@c ref
@ref{short}
@c ref
@c ------------------------------
@node poly expressions, poly operations, poly declarations, poly
@subsection poly expressions
@cindex poly expressions

A polynomial expression is (optional parts in square brackets):
@enumerate
@item
a monomial (there are NO spaces allowed inside a monomial)
@smallexample
  [coefficient] ring_variable [ exponent] [ring_variable [exponent] @dots{}].
@end smallexample
Monomials which contain an indexed ring variable
must be built from @code{ring_variable} and @code{coefficient}
with the operations @code{*} and @code{^}
@item
an identifier of type poly
@item
a function returning poly
@item
polynomial expressions combined by the arithmetic operations
@code{+}, @code{-}, @code{*}, @code{/}, or @code{^}
@item
an int expression (see @ref{Type conversion and casting})
@item
a type cast to poly
@end enumerate

@*@strong{Example:}
@smallexample
ring S=0,(x,y,z,a(1)),dp;
2x, x3, 2x2y3, xyz, 2xy2; //  are monomials
2*x, x^3, 2*x^2*y^3, x*y*z, 2*x*y^2; // are poly expressions
2*a(1); // is a valid polynomial expression (a(1) is a name of a variable),
        // but not 2a(1) (is a syntax error)
2*x^3;  // is a valid polynomial expression equal to 2x3 (a valid monomial)
        // but not equal to 2x^3 which will be interpreted as (2x)^3
        // since 2x is a monomial
@c example
  ring r=0,(x,y),dp;
  poly f = 10x2y3 +2x2y2-2xy+y -x+2;
  lead(f);
  leadmonom(f);
  simplify(f,1);     // normalize leading coefficient
  poly g = 1/2x2 + 1/3y;
  cleardenom(g);
  int i = 102;
  poly(i);
  typeof(_);
@c example
@end smallexample

@c ref
See @ref{ring}; @ref{Type conversion and casting}.
@c ref

@c ------------------------------
@node poly operations, poly related functions, poly expressions, poly
@subsection poly operations
@cindex poly operations

@table @asis
@item @code{+}
addition

@item @code{-}
negation or subtraction

@item @code{*}
multiplication

@item @code{/}
division by a polynomial, non divisible terms yield 0

@item @code{^}, @code{**}
power by a positive integer

@item @code{<}, @code{<=}, @code{>}, @code{>=}, @code{==}, @code{<>}
comparators (considering leading monomials w.r.t. monomial ordering)

@item poly_expression @code{[} intvec_expression @code{]}
the sum of monomials at the indicated places w.r.t. the monomial ordering
@end table

@*@strong{Example:}
@smallexample
@c example
  ring R=0,(x,y),dp;
  poly f = x3y2 + 2x2y2 + xy - x + y + 1;
  f;
  f + x5 + 2;
  f * x2;
  (x+y)/x;
  f/3x2;
  x5 > f;
  x<=y;
  x>y;
  ring r=0,(x,y),ds;
  poly f = fetch(R,f);
  f;
  x5 > f;
  f[2..4];
  size(f);
  f[size(f)+1]; f[-1];    // monomials out of range are 0
  intvec v = 6,1,3;
  f[v];          // the polynom built from the 1st, 3rd and 6th monomial of f
@c example
@end smallexample

@c ------------------------------
@node poly related functions,  , poly operations, poly
@subsection poly related functions
@cindex poly related functions

@table @code
@item cleardenom
cancellation of denominators of numbers in polynomial and divide it by its content
(see @ref{cleardenom}; @ref{content})
@item coef
matrix of coefficients and monomials (see @ref{coef})
@item coeffs
matrix of coefficients (see @ref{coeffs})
@item deg
degree (see @ref{deg})
@c @item det
@c determinant (see @ref{det})
@item diff
partial derivative (see @ref{diff})
@item extgcd
Bezout representation of gcd (see @ref{extgcd})
@item factorize
factorization of polynomial (see @ref{factorize})
@item finduni
univariate polynomials in a zero-dimensional ideal (see @ref{finduni})
@item gcd
greatest common divisor (see @ref{gcd})
@item homog
homogenization (see @ref{homog})
@item jacob
ideal, resp.@: matrix, of all partial derivatives (see @ref{jacob})
@item lead
leading term (see @ref{lead})
@item leadcoef
coefficient of the leading term (see @ref{leadcoef})
@item leadexp
the exponent vector of the leading monomial (see @ref{leadexp})
@item leadmonom
leading monomial (see @ref{leadmonom})
@item jet
monomials of degree at most k (see @ref{jet})
@item ord
degree of the leading monomial (see @ref{ord})
@item qhweight
quasihomogeneous weights (see @ref{qhweight})
@item reduce
normal form with respect to a standard base (see @ref{reduce})
@item rvar
test for ring variable (see @ref{rvar})
@item simplify
normalization of a polynomial (see @ref{simplify})
@item size
number of monomials (see @ref{size})
@item subst
substitution of a ring variable (see @ref{subst})
@item trace
trace of a matrix (see @ref{trace})
@item var
the indicated variable of the ring (see @ref{var})
@item varstr
variable(s) in string form (see @ref{varstr})
@end table

@c @*@strong{Example:}
@c @example
@c @end example

@c ---------------------------------------
@node proc, qring, poly, Data types
@section proc
@cindex proc

Procedures are sequences of @sc{Singular} commands in a special
format. They are used to extend the set of @sc{Singular} commands with
user defined commands. Once a procedure is defined it can be used as
any other @sc{Singular} command. Procedures may be defined by either
typing them on the command line or by loading them from a file. For a
detailed description on the concept of procedures in @sc{Singular} see
@ref{Procedures}. A file containing procedure definitions which comply with
certain syntax rules is called a library. Such a file is loaded
using the command @code{LIB}. For more information on libraries see
@ref{Libraries}.

@menu
* proc declaration::
@end menu

@c ---------------------------------------
@node proc declaration,  , proc, proc
@subsection proc declaration
@cindex proc declaration

@c ------------------------------------------------------------
@c   This piece of text exists also in the file general.doc,
@c   chapter "Proc in a library".
@c   If you change something here, change it there, too!
@c ------------------------------------------------------------
@table @strong
@item Syntax:
[@code{static}] @code{proc} proc_name [(<parameter_list>)
@*[<help_string>]
@*@code{@{}
@*
@tex
\quad
@end tex
   <procedure_body>
@*@code{@}}
@*[@code{example}
@*@code{@{}
@*
@tex
\quad
@end tex
   <sequence_of_commands>
@*@code{@}}]
@item Purpose:
Defines a new function, the @code{proc} proc_name. Once loaded in a
@sc{Singular} session, the information provided in the help string will be
displayed upon entering @code{help proc_name;}, while the @code{example}
section will be executed  upon entering @code{example proc_name;}.
@xref{Parameter list}, @ref{Help string}, and the example in
@ref{Procedures in a library}.
@* The help string, the parameter list, and the example section are optional.
They are, however, mandatory for the procedures listed in the header of a library.
The help string is ignored and no example section is allowed if the procedure is defined
interactively, i.e., if it is not loaded from a file by the @code{LIB} or @code{load}
command (@pxref{LIB} and @pxref{load} ).
@* In the body of a library, each procedure not meant to be accessible by
users should be declared static. @xref{Procedures in a library}.

@item Example:
@smallexample
@c example
  proc milnor_number (poly p)
  {
    ideal i= std(jacob(p));
    int m_nr=vdim(i);
    if (m_nr<0)
    {
      "// not an isolated singularity";
    }
    return(m_nr);         // the value of m_nr is returned
  }
  ring r1=0,(x,y,z),ds;
  poly p=x^2+y^2+z^5;
  milnor_number(p);
@c example
@end smallexample
@end table

@c ref
See
@ref{LIB};
@ref{Libraries};
@ref{Procedures}
@c ref

@c ---------------------------------------
@node qring, resolution, proc, Data types
@section qring
@cindex qring

@sc{Singular} offers the opportunity to calculate in quotient rings
(factor rings), i.e., rings modulo an ideal.  The ideal has to be given
as a standard basis.  For a detailed description of the concept
of rings and quotient rings see @ref{Rings and orderings}.

@menu
* qring declaration::
@end menu

@c ---------------------------------------
@node qring declaration,  , qring, qring
@subsection qring declaration
@cindex qring declaration

@c ------------------------------------------------------------
@c   This piece of text exists also in the file general.doc,
@c   chapter "General syntax of a ring declaration".
@c   If you change something here, change it there, too!
@c ------------------------------------------------------------
@table @strong
@item Syntax:
@code{qring} name @code{=} ideal_expression @code{;}
@item Default:
none
@item Purpose:
declares a quotient ring as the basering modulo ideal_expression and sets
it as current basering.
@item Example:
@smallexample
@c example
ring r=0,(x,y,z),dp;
ideal i=xy;
qring q=std(i);
basering;
// simplification is not immediate:
(x+y)^2;
reduce(_,std(0));
@c example
@end smallexample
@end table

@c ---------------------------------------
@node resolution, ring, qring, Data types
@section resolution
@cindex resolution

The type resolution is intended as an intermediate representation which
internally retains additional information obtained during computation of
resolutions. It furthermore enables the use of partial results to
compute, for example, Betti numbers or minimal resolutions. Like ideals
and modules, a resolution can only be defined w.r.t.@: a basering
(see @ref{Syzygies and resolutions}).

@strong{Note:}
To access the elements of a resolution, it has to be assigned to a list.
This assignment also completes computations and may therefore take time,
(resp.@: an access directly with the brackets @code{[ , ]} causes
implicitly a cast to a list).

@menu
* resolution declarations::
* resolution expressions::
* resolution related functions::
@end menu

@c ---------------------------------------
@node resolution declarations, resolution expressions, resolution, resolution
@subsection resolution declarations
@cindex resolution declarations

@table @strong
@item Syntax:
@code{resolution} name @code{=} resolution_expression @code{;}

@item Purpose:
defines a resolution.

@item Default:
none

@item Example:
@smallexample
@c example
  ring R;
  ideal i=z2,x;
  resolution re=res(i,0);
  re;
  betti(re);
  list l = re;
  l;
@c example
@end smallexample
@end table

@c ------------------------------
@node resolution expressions, resolution related functions, resolution declarations, resolution
@subsection resolution expressions
@cindex resolution expressions

A resolution expression is:
@enumerate
@item
an identifier of type resolution
@item
a function returning a resolution
@item
a type cast to resolution from a list of ideals, resp.@: modules..
@end enumerate

@c ref
See @ref{Type conversion and casting}.
@c ref

@c ------------------------------
@node resolution related functions,  , resolution expressions, resolution
@subsection resolution related functions
@cindex resolution related functions

@table @code
@item betti
Betti numbers of a resolution (see @ref{betti})
@item lres
free resolution (see @ref{lres})
@item minres
minimize a free resolution (see @ref{minres})
@item mres
minimal free resolution of an ideal, resp.@: module and a minimal set of generators of
the given ideal, resp.@: module (see @ref{mres})
@item res
free resolution of an ideal, resp.@: module, but not changing the
given ideal, resp.@: module (see @ref{res})
@item sres
free resolution of a standard basis (see @ref{sres})
@end table

@c @*@strong{Example:}
@c @example
@c @end example

@c ---------------------------------------
@node ring, string, resolution, Data types
@section ring
@cindex ring

Rings are used to describe properties of polynomials, ideals etc.
Almost all computations in @sc{Singular} require a basering.
For a detailed description of the concept of rings see
@ref{Rings and orderings}.

@menu
* ring declarations::
* ring related functions::
* ring operations::
@end menu

@c ---------------------------------------
@node ring declarations, ring related functions, ring, ring
@subsection ring declarations
@cindex ring declarations

@table @strong
@item Syntax:
@code{ring} name @code{= (} coefficients @code{),}
  @code{(} names_of_ring_variables @code{),}
  @code{(} ordering @code{);}
@item Default:
@code{32003,(x,y,z),(dp,C);}
@item Purpose:
declares a ring and sets it as the actual basering.
@end table

The coefficients are given by one of the following:
@enumerate
@item
a non-negative int_expression less or equal 2147483629.
@item
an expression_list of an int_expression and one or more names.
@item
the name @code{real}
@item
an expression_list of the name @code{real} and an  int_expression.
@item
an expression_list of the name @code{complex}, an optional int_expression
and a name.
@item
an expression_list of the name @code{integer}.
@item
an expression_list of the name @code{integer} and following int_expressions.
@item
an expression_list of the name @code{integer} and two int_expressions.

@end enumerate

For the definition of the 'coefficients', see @ref{Rings and orderings}.

'names_of_ring_variables' must be a list of names or (multi-)indexed names.

'ordering' is a list of block orderings where each block ordering is either
@enumerate
@item
@code{lp}, @code{dp}, @code{Dp}, @code{rp}, @code{ls}, @code{ds}, or @code{Ds}
optionally followed by a size parameter in parentheses.

@item
@code{wp}, @code{Wp}, @code{ws}, @code{Ws}, or @code{a} followed by a
weight vector given as an intvec_expression in parentheses.

@item
@code{M} followed by an intmat_expression in parentheses.

@item
@code{c} or @code{C}.
@end enumerate

For the definition of the orderings, see @ref{Term orderings},
@ref{Monomial orderings}.

If one of coefficients, names_of_ring_variables, and ordering
consists of only one entry, the parentheses around this entry may be
omitted.

@c ref
See also
@ref{Examples of ring declarations};
@ref{ring};
@ref{ringlist}.
@c ref
@c ---------------------------------------
@node ring related functions, ring operations, ring declarations, ring
@subsection ring related functions
@cindex ring related functions

@table @code
@item charstr
description of the coefficient field of a ring (see @ref{charstr})
@item keepring
move ring to next upper level (see @ref{keepring})
@item npars
number of ring parameters (see @ref{npars})
@item nvars
number of ring variables (see @ref{nvars})
@item ordstr
monomial ordering of a ring (see @ref{ordstr})
@item parstr
names of all ring parameters or the
name of the n-th ring parameter (see @ref{parstr})
@item qring
quotient ring (see @ref{qring})
@item ringlist
decomposition of a ring into a list of its components (see @ref{ringlist})
@item setring
setting of a new basering (see @ref{setring})
@item varstr
names of all ring variables or the
name of the n-th ring variable (see @ref{varstr})
@end table

@c ---------------------------------------
@node ring operations, , ring related functions, ring
@subsection ring operations
@cindex ring operations
@table @asis
@item @code{+}
construct a new ring @math{k[X,Y]} from @math{k_1[X]}  and @math{k_2[Y]}.
(The sets of variables must be distinct).
@end table

@strong{Note:}
Concerning the ground fields @math{k_1} and @math{k_2} take the
following guide lines into consideration:
@itemize @bullet
@item Neither @math{k_1} nor @math{k_2} may be @math{R} or @math{C}.
@item If the characteristic of @math{k_1} and @math{k_2} differs, then one of them must be @math{Q}.
@item At most one of @math{k_1} and @math{k_2} may have parameters.
@item If one of @math{k_1} and @math{k_2} is an algebraic extension of @math{Z/p} it may not be defined by a @code{charstr} of type @code{(p^n,a)}.
@end itemize


@strong{Example:}
@smallexample
@c example
  ring R1=0,(x,y),dp;
  ring R2=32003,(a,b),dp;
  def R=R1+R2;
  R;
@c example
@end smallexample

@c ref
@ref{ring_lib}
@c ref

@c ---------------------------------------
@node string, vector, ring, Data types
@section string
@cindex string
@cindex newline

Variables of type @code{string} are used for output (almost every type
can be "converted" to @code{string}) and for creating new
commands at runtime see @ref{execute}.  They are also return values of
certain interpreter related functions (see @ref{Functions}).  String
constants consist of a sequence of ANY characters (including newline!)
between a starting @code{"} and a closing @code{"}.  There is also a
string constant @code{newline}, which is the newline character.  The
@code{+} sign "adds" strings, @code{""} is the empty string (hence
strings form a semigroup). Strings may be used to comment the output of
a computation or to give it a nice format. Strings may also be used for
intermediate conversion of one type into another.

@smallexample
@c example
  string s="Hi";
  string s1="a string with new line at the end"+newline;
  string s2="another string with new line at the end
  ";
  s;s1;s2;
  ring r; ideal i=std(ideal(x,y^3));
  "dimension of i =",dim(i),", multiplicity of i =",mult(i);
  "dimension of i = "+string(dim(i))+", multiplicity of i = "+string(mult(i));
  "a"+"b","c";
@c example
@end smallexample
A comma between two strings makes an expression list out of them
(such a list is printed with a separating blank in between),
while a @code{+} concatenates strings.

@menu
* string declarations::
* string expressions::
* string type cast::
* string operations::
* string related functions::
@end menu

@c ------------------------------
@node string declarations, string expressions, string, string
@subsection string declarations
@cindex string declarations

@table @strong
@item Syntax:
@code{string} name @code{=} string_expression @code{;}
@*@code{string} name @code{=} list_of_string_expressions @code{;}

@item Purpose:
defines a string variable.

@item Default:
"" (the empty string)

@item Example:
@smallexample
@c example
  string s1="Now I know";
  string s2="how to encode a \" in a string...";
  string s=s1+" "+s2; // concatenation of 3 strings
  s;
  s1,s2;   // 2 strings, separated by a blank in the output:
@c example
@end smallexample
@end table

@c ------------------------------
@node string expressions, string type cast, string declarations, string
@subsection string expressions
@cindex string expressions

A string expression is:
@enumerate
@item
a sequence of characters between two unescaped quotes (@code{"})
@item
an identifier of type string
@item
a function returning string
@item
a substring (using the bracket operator)
@item
a type cast to string (@pxref{string type cast})
@item
string expressions combined by the operation @code{+}.
@end enumerate

@*@strong{Example:}
@smallexample
@c  // a string constant
@c  "@dots{}";
@c  // a type cast from name
@c  string(name)
@c  // concatenation
@c  string_expression + string_expression
@c example
// string_expression[start, length] : a substring
// (possibly filled up with blanks)
// the substring of s starting at position 2
// with a length of 4
string s="123456";
s[2,4];
"abcd"[2,2];
// string_expression[position] : a character from a string
s[3];
// string_expression[position..position] :
// a substring starting at the first position up to the second
// given position
s[2..4];
// a function returning a string
typeof(s);
@c example
@end smallexample

@c ref
See @ref{Type conversion and casting}
@ref{string type cast}
@c ref

@c ------------------------------
@node string type cast,  string operations, string expressions, string
@subsection string type cast
@cindex string type cast
@table @code
@item @strong{Syntax:}
@code{string (} expression [, expression_2, ... expression_n]@code{)}
@item @strong{Type:}
string
@item @strong{Purpose:}
Converts each expression to a string, where expression can be of any
type. The concatenated string of all converted expressions is returned.

@*The elements of intvec, intmat, ideal, module, matrix, and list, are
separated by a comma. No newlines are inserted.
@*Not defined elements of a list are omitted.
@*For link, the name of the link is used.
@*For map, the ideal defining the mapping is converted.

@item @strong{Note:}
When applied to a list, elements of type intvec, intmat, ideal, module,
matrix, and list become indistinguishable.

@item @strong{Example:}
@smallexample
@c example
  string("1+1=", 2);
  string(intvec(1,2,3,4));
  string(intmat(intvec(1,2,3,4), 2, 2));
  ring r;
  string(r);
  string(ideal(x,y));
  qring R = std(ideal(x,y));
  string(R);
  map phi = r, ideal(x,z);
  string(phi);
  list l;
  string(l);
  l[3] = 1;
  string(l); // notice that l[1],l[2] are omitted
  l[2] = l;
  l;
  string(l); // notice that lists of list is flattened
  l[1] = intvec(1,2,3);
  l;
  string(l); // notice that intvec elements are not distinguishable
@c example
@end smallexample
@end table
@c ref
See
@ref{string};
@ref{Type conversion and casting};
@ref{print}.
@c ref

@c ------------------------------
@node string operations, string related functions, string type cast, string
@subsection string operations
@cindex string operations

@table @asis
@item @code{+}
concatenation

@item @code{<=}, @code{>=}, @code{==}, @code{<>}
comparison (lexicographical with respect to the ASCII encoding)

@item string_expression @code{[} int_expression @code{]}
is a character of the string; the index 1 gives the first character.

@item string_expression @code{[} int_expression@code{,} int_expression @code{]}
is a substring, where the first argument is the start index and the
second is the length of the substring, filled up with blanks if the
length exceeds the total size of the string

@item string_expression @code{[} intvec_expression @code{]}
is a expression list of characters from the string
@end table

@*@strong{Example:}
@smallexample
@c example
  string s="abcde";
  s[2];
  s[3,2];
  ">>"+s[1,10]+"<<";
  s[2]="BC"; s;
  intvec v=1,3,5;
  s=s[v]; s;
  s="654321"; s=s[3..5]; s;
@c example
@end smallexample

@c ------------------------------
@node string related functions,  , string operations, string
@subsection string related functions
@cindex string related functions

@table @code
@item charstr
description of the coefficient field of a ring (see @ref{charstr})
@item execute
executing string as command (see @ref{execute})
@item find
position of a substring in a string (see @ref{find})
@item names
list of strings of all user-defined variable names (see @ref{names})
@item nameof
name of an object (see @ref{nameof})
@item option
lists all defined options (see @ref{option})
@item ordstr
monomial ordering of a ring (see @ref{ordstr})
@item parstr
names of all ring parameters or the
name of the n-th ring parameter (see @ref{parstr})
@item read
read a file (see @ref{read})
@item size
length of a string (see @ref{size})
@item sprintf
string formatting (see @ref{sprintf})
@item typeof
type of an object (see @ref{typeof})
@item varstr
names of all ring variables or the
name of the n-th ring variable (see @ref{varstr})
@end table

@c @*@strong{Example:}
@c @example
@c @end example

@c ---------------------------------------
@node vector, User defined types , string, Data types
@section vector
@cindex vector

Vectors are elements of a free module over the basering with basis
@code{gen(1)}, @code{gen(2)}, @dots{} .
Like polynomials they
can only be defined or accessed with respect to the basering.
Each vector belongs to a free module of rank equal to the biggest index
of a generator with non-zero coefficient. Since generators with zero
coefficients need not be written any vector may be considered
also as an element of a free module of higher rank.
(E.g., if @code{f} and @code{g} are polynomials then
@code{f*gen(1)+g*gen(3)+gen(4)} may also be written as @code{[f,0,g,1]}
or as @code{[f,0,g,1,0]}.)
Note that the elements of a vector have to be
surrounded by square brackets (@code{[}  , @code{]})
(cf. @ref{Representation of mathematical objects}).

@menu
* vector declarations::
* vector expressions::
* vector operations::
* vector related functions::
@end menu

@c ------------------------------
@node vector declarations, vector expressions, vector, vector
@subsection vector declarations
@cindex vector declarations

@table @strong
@item Syntax:
@code{vector} name @code{=} vector_expression @code{;}

@item Purpose:
defines a vector of polynomials (an element of a free module).

@item Default:
[0]

@item Example:
@smallexample
@c example
  ring r=0,(x,y,z),(c,dp);
  poly s1 = x2;
  poly s2 = y3;
  poly s3 = z;
  vector v = [s1, s2-s1, s3-s1]+ s1*gen(5);
  // v is a vector in the free module of rank 5
  v;
@c example
@end smallexample
@end table

@c ------------------------------
@node vector expressions, vector operations, vector declarations, vector
@subsection vector expressions
@cindex vector expressions

A vector expression is:
@enumerate
@item
an identifier of type vector
@item
a function returning vector
@item
a polynomial expression (via the canonical embedding @code{p} @expansion{} @code{p*gen(1)})
@item
vector expressions combined by the arithmetic operations @code{+} or
@code{-}
@item
a polynomial expression and a vector expression combined by the arithmetic
operation @code{*}
@item
a type cast to vector using the brackets @code{[} , @code{]}
@end enumerate

@*@strong{Example:}
@smallexample
@c example
  // ordering gives priority to components:
  ring rr=0,(x,y,z),(c,dp);
  vector v=[x2+y3,2,0,x*y]+gen(6)*x6;
  v;
  vector w=[z3-x,3y];
  v-w;
  v*(z+x);
  // ordering gives priority to monomials:
  // this results in a different output
  ring r=0,(x,y,z),(dp,c);
  imap(rr,v);
@c example
@end smallexample

@c ref
See
@ref{ring};
@ref{Type conversion and casting}.
@c ref

@c ------------------------------
@node vector operations, vector related functions, vector expressions, vector
@subsection vector operations
@cindex vector operations

@table @asis
@item @code{+}
addition

@item @code{-}
negation or subtraction

@item @code{/}
division by a monomial, not divisible terms yield 0

@item @code{<}, @code{<=}, @code{>}, @code{>=}, @code{==}, @code{<>}
comparators (considering leading terms w.r.t. monomial ordering)

@item vector_expression @code{[} int_expressions @code{]}
is a vector entry; the index 1 gives the first entry.
@end table

@*@strong{Example:}
@smallexample
@c example
  ring R=0,(x,y),(c,dp);
  [x,y]-[1,x];
  [1,2,x,4][3];
@c example
@end smallexample


@c ------------------------------
@node vector related functions,  , vector operations, vector
@subsection vector related functions
@cindex vector related functions

@table @code
@item cleardenom
quotient of a vector by its content (see @ref{cleardenom})
@item coeffs
matrix of coefficients (see @ref{coeffs})
@item deg
degree (see @ref{deg})
@item diff
partial derivative (see @ref{diff})
@item gen
i-th generator (see @ref{gen})
@item homog
homogenization (see @ref{homog})
@item jet
k-jet: monomials of degree at most k (see @ref{jet})
@item lead
leading term (see @ref{lead})
@item leadcoef
leading coefficient (see @ref{leadcoef})
@item leadexp
the exponent vector of the leading monomial (see @ref{leadexp})
@item leadmonom
leading monomial (see @ref{leadmonom})
@item nrows
number of rows (see @ref{nrows})
@item ord
degree of the leading monomial (see @ref{ord})
@item reduce
normal form with respect to a standard base (see @ref{reduce})
@item simplify
normalize a vector (see @ref{simplify})
@item size
number of monomials (see @ref{size})
@item subst
substitute a ring variable (see @ref{subst})
@end table

@c @*@strong{Example:}
@c @example
@c @end example
@c ---------------------------------------
@node User defined types, pyobject, vector, Data types
@section User defined types
@cindex User defined types
@cindex newstruct

User defined types are (non-empty) lists with a fixed size
whose element can be accessed by names (and not indices).
These elements have a predefined type (which can also be a user defined type).
If these elemnts depend on a ring they can only be accessed if
their base ring ist the current base ring.
In contrast to usual lists the elements of a user defined type may
belong to different rings.

@menu
* Definition of a user defined type::
* Declaration of objects of a user defined type::
* Access to elements of a user defined type::
@end menu

@c ------------------------------
@node Definition of a user defined type, Declaration of objects of a user defined type, User defined types, User defined types
@subsection Definition of a user defined type
@cindex Definition of a user defined type

@table @strong
@item Syntax:
@code{newstruct(} name @code{,} string_expression @code{);}
@*@code{newstruct(} name @code{,} name @code{,} string_expression @code{);}


@item Purpose:
defines a new type with elemnts given by the last argmuent (string_expression).
The name of the new type is the first argument (of type string) and must
be longer than one character.
@*The second name (of type string) is an already defined type
which should be extended by the new type.
@*The last argument (of type string) must be an comma separated list of
a type followed by a name.
If there are duplicate member names, the last one wins.

@item Operations:
the only operations of user defined types are:
@table @asis
@item
assignment (between objects of the same or extended type)
@item
@code{typeof}
@item
@code{string} and printing
@item
operator @code{.} to access the elements
@end table

@item Example:
@smallexample
@c example
  newstruct("nt","int a,poly b,string c");
  nt A;
  nt B;
  A.a=3;
  A.c=string(A.a);
  B=A;
  newstruct("t2","nt","string c");
  t2 C; C.c="t2-c";
  A=C;
  typeof(A);
  A;
  // a motivating example ------------------------------------------
  newstruct("IDEAL","ideal I,proc prettyprint");
  newstruct("HOMOGENEOUS_IDEAL","IDEAL","intvec weights,proc prettyprint");
  proc IDEAL_pretty_print(IDEAL I)
  {
    "ideal generated by";
    I.I;
  }
  proc H_IDEAL_pretty_print(HOMOGENEOUS_IDEAL I)
  {
    "homogeneous ideal generated by";
    I.I;
    "with weights";
    I.weights;
  }
  proc p_print(IDEAL I) { I.prettyprint(I); }
  ring r;
  IDEAL I;
  I.I=ideal(x+y2,z);
  I.prettyprint=IDEAL_pretty_print;
  HOMOGENEOUS_IDEAL H;
  H.I=ideal(x,y,z);
  H.prettyprint=H_IDEAL_pretty_print;
  H.weights=intvec(1,1,1);
  p_print(I);
  p_print(H);
@c example
@end smallexample
@end table

@c ------------------------------
@node Declaration of objects of a user defined type, Access to elements of a user defined type, Definition of a user defined type, User defined types
@subsection Declaration of objects of a user defined type
@cindex Declaration of objects of a user defined type

@*@strong{Example:}
@smallexample
@c example
  newstruct("nt","int a,poly b,string c");
  nt A;
  // as long as there is no value assigned to A.b, no ring is needed
  nt B=A;
@c example
@end smallexample

@c @c ref
@c See
@c @ref{ring};
@c @ref{Type conversion and casting}.
@c @c ref

@c ------------------------------
@node Access to elements of a user defined type, , Declaration of objects of a user defined type, User defined types
@subsection Access to elements of a user defined type
@cindex Access to elements of a user defined type

@*@strong{Example:}
@smallexample
@c example
  newstruct("nt","int a,poly b,string c");
  nt A;
  3+A.a;
  A.c="example string";
  ring r;
  A.b=poly(1); // assignment: expression must be of the given type
  A;
@c example
@end smallexample

@c ------------------------------
@include pyobject.tex