@comment -*-texinfo-*-
@comment This file was generated by doc2tex.pl from types.doc
@comment DO NOT EDIT DIRECTLY, BUT EDIT types.doc INSTEAD
@comment Id: types.tex,v 1.1 2003/08/08 14:27:06 pertusus Exp $
@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 types.hlp
@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
* def::
* ideal::
* int::
* intmat::
* intvec::
* link::
* list::
* map::
* matrix::
* module::
* number::
* poly::
* proc::
* qring::
* resolution::
* ring::
* string::
* vector::
@ifset namespaces
* package::
@end ifset
@end menu

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

Objects may be defined without a specific type: they get 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}.

@smallexample
@c reused example def types.doc:78 
  ring r=32003,(x,y,z),dp;
  poly f = x;
  def s=basering;
  setring s;
  nameof(basering);
@expansion{} s
  listvar();
@expansion{} // s                    [0]  *ring
@expansion{} //      f                    [0]  poly
@expansion{} // r                    [0]  ring
@expansion{} // LIB                  [0]  string standard.lib
  poly g = y;
  kill f;
  listvar(r);
@expansion{} // r                    [0]  ring
@expansion{} // g                    [0]  poly
  ring t=32003,(u,w),dp;
  def rt=r+t;
  rt;
@expansion{} //   characteristic : 32003
@expansion{} //   number of vars : 5
@expansion{} //        block   1 : ordering dp
@expansion{} //                  : names    x y z 
@expansion{} //        block   2 : ordering dp
@expansion{} //                  : names    u w 
@expansion{} //        block   3 : ordering C
@c end example def types.doc:78
@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 reused example def_declarations types.doc:127 
  def i=2;
  typeof(i);
@expansion{} int
@c end example def_declarations types.doc:127
@end smallexample
@end table

@c inserted refs from types.doc:134
@ifinfo
@menu
See
* typeof::
@end menu
@end ifinfo
@iftex
See
@ref{typeof}.
@end iftex
@c end inserted refs from types.doc:134

@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.
@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 reused example ideal_declarations types.doc:175 
  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;
@expansion{} i[1]=x2
@expansion{} i[2]=y3-x2
@expansion{} i[3]=0
@expansion{} i[4]=y3z
@expansion{} i[5]=z4
  size(i);
@expansion{} 4
  ncols(i);
@expansion{} 5
@c end example ideal_declarations types.doc:175
@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 ideal
@item
ideal expressions combined 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 reused example ideal_expressions types.doc:213 
  ring r=0,(x,y,z),dp;
  ideal m = maxideal(1);
  m;
@expansion{} m[1]=x
@expansion{} m[2]=y
@expansion{} m[3]=z
  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;
@expansion{} 0
  ncols(i);
@expansion{} 505
  timer =0;
  i = M^2;
  ncols(i);
@expansion{} 505
  timer;
@expansion{} 0
  i[ncols(i)];
@expansion{} x20
  vector v = [x,y-z,x2,y-x,x2yz2-y];
  ideal j = ideal(v);
@c end example ideal_expressions types.doc:213
@end smallexample

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

@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 reused example ideal_operations types.doc:259 
  ring r=0,(x,y,z),dp;
  ideal I = 0,x,0,1;
  I;
@expansion{} I[1]=0
@expansion{} I[2]=x
@expansion{} I[3]=0
@expansion{} I[4]=1
  I + 0;    // simplification
@expansion{} _[1]=1
  ideal J = I,0,x,x-z;;
  J;
@expansion{} J[1]=0
@expansion{} J[2]=x
@expansion{} J[3]=0
@expansion{} J[4]=1
@expansion{} J[5]=0
@expansion{} J[6]=x
@expansion{} J[7]=x-z
  I * J;   //  multiplication with simplification
@expansion{} _[1]=1
  I*x;
@expansion{} _[1]=0
@expansion{} _[2]=x2
@expansion{} _[3]=0
@expansion{} _[4]=x
  vector V = [x,y,z];
  print(V*I);
@expansion{} 0,x2,0,x,
@expansion{} 0,xy,0,y,
@expansion{} 0,xz,0,z 
  ideal m = maxideal(1);
  m^2;
@expansion{} _[1]=x2
@expansion{} _[2]=xy
@expansion{} _[3]=xz
@expansion{} _[4]=y2
@expansion{} _[5]=yz
@expansion{} _[6]=z2
  ideal II = I[2..4];
  II;
@expansion{} II[1]=x
@expansion{} II[2]=0
@expansion{} II[3]=1
@c end example ideal_operations types.doc:259
@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
computes 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
represents
@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 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
simplify a set of polynomials (see @ref{simplify})
@item size
number of non-zero generators (see @ref{size})
@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
substitute 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{number} if possible.

@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 reused example int_declarations types.doc:447 
  int i = 42;
  int j = i + 3; j;
@expansion{} 45
  i = i * 3 - j; i;
@expansion{} 81
  int k;   // assigning the default value 0 to k
  k;
@expansion{} 0
@c end example int_declarations types.doc:447
@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
int expressions combined by 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 reused example int_expressions types.doc:489 
12345678901; // too large
@expansion{}    ? `12345678901` greater than 2147483647(max. integer representation)
@expansion{}    ? error occurred in line 1: `12345678901; // too large`
typeof(_);
@expansion{} none
ring r=0,x,dp;
12345678901;
@expansion{} 12345678901
typeof(_);
@expansion{} number
// Note: 11*13*17*100*200*2000*503*1111*222222
// returns a machine integer:
11*13*17*100*200*2000*503*1111*222222;
@expansion{} // ** int overflow(*), result may be wrong
@expansion{} // ** int overflow(*), result may be wrong
@expansion{} // ** int overflow(*), result may be wrong
@expansion{} // ** int overflow(*), result may be wrong
@expansion{} -1875651584
// using the type cast number for a greater allowed range
number(11)*13*17*100*200*2000*503*1111*222222;
@expansion{} 12075748128684240000000
ring rp=32003,x,dp;
12345678901;
@expansion{} 9603
typeof(_);
@expansion{} number
intmat m[2][2] = 1,2,3,4;
m;
@expansion{} 1,2,
@expansion{} 3,4 
m[2,2];
@expansion{} 4
typeof(_);
@expansion{} int
det(m);
@expansion{} -2
m[1,1] + m[2,1] == trace(m);
@expansion{} 0
! 0;
@expansion{} 1
1 and 2;
@expansion{} 1
intvec v = 1,2,3;
def d =transpose(v)*v;    // scalarproduct gives an 1x1 intvec
typeof(d);
@expansion{} intvec
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;
@expansion{} 6
@c end example int_expressions types.doc:489
@end smallexample

@c inserted refs from types.doc:526
@ifinfo
@menu
See
* Type conversion and casting::
* number::
@end menu
@end ifinfo
@iftex
See
@ref{Type conversion and casting};
@ref{number}.
@end iftex
@c end inserted refs from types.doc:526

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

@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{<>}
comparison
@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 reused example int_operations types.doc:574 
  int i=1;
  int j;
  i++; i;  i--; i;
@expansion{} 2
@expansion{} 1
  // ++ and -- do not return a value as in C, can not assign
  j = i++;
@expansion{} // ** right side is not a datum, assignment ignored
  // the value of j is unchanged
  j; i;
@expansion{} 0
@expansion{} 2
  i+2, 2-i, 5^2;
@expansion{} 4 0 25
  5 div 2, 8%3;
@expansion{} 2 2
  -5 div 2, -5 / 2, -5 mod 2, -5 % 2;
@expansion{} -3 -2 1 -1
  1<2, 2<=2;
@expansion{} 1 1
@c end example int_operations types.doc:574
@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 poly 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 poly 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 really an int expression used in a logical context:

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

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

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

@enumerate
@item
an integer comparison:
@smallexample
  i == j
  i != j    // or     i <> j
  i <= j
  i >= j
  i > j
  i < j
@end smallexample
@item
a number comparison:
@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
a polynomial or vector comparison:
@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
an intmat or matrix comparison:
@smallexample
  v == w
  v != w    // or     v <> w
@end smallexample
@item
an intvec or  string comparison:
@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 reused example boolean_operations types.doc:784 
  (1>2) and 3;
@expansion{} 0
  1 > 2 and 3;
@expansion{} 0
  ! 0 or 1;
@expansion{} 1
  !(0 or 1);
@expansion{} 0
@c end example boolean_operations types.doc:784
@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 reused example intmat_declarations types.doc:838 
  intmat im[3][5]=1,3,5,7,8,9,10,11,12,13;
  im;
@expansion{} 1,3,5,7,8,
@expansion{} 9,10,11,12,13,
@expansion{} 0,0,0,0,0 
  im[3,2];
@expansion{} 0
  intmat m[2][3] = im[1..2,3..5];  // defines a submatrix
  m;
@expansion{} 5,7,8,
@expansion{} 11,12,13 
@c end example intmat_declarations types.doc:838
@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
intmat operations with int (@code{+}, @code{-}, @code{*}, @code{div}, @code{%})
@item
intmat operations (@code{+}, @code{-}, @code{*})
@item
a type cast to intmat (@pxref{intmat type cast})
@end enumerate

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

@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 reused example intmat_type_cast types.doc:908 
  intmat(intvec(1));
@expansion{} 1 
  intmat(intvec(1), 1, 2);
@expansion{} 1,0 
  intmat(intvec(1,2,3,4), 2, 2);
@expansion{} 1,2,
@expansion{} 3,4 
  intmat(_, 2, 3);
@expansion{} 1,2,3,
@expansion{} 4,0,0 
  intmat(_, 2, 1);
@expansion{} 1,
@expansion{} 2 
@c end example intmat_type_cast types.doc:908
@end smallexample
@end table
@c inserted refs from types.doc:917
@ifinfo
@menu
See
* Type conversion and casting::
* intmat::
* matrix type cast::
@end menu
@end ifinfo
@iftex
See
@ref{Type conversion and casting};
@ref{intmat};
@ref{matrix type cast}.
@end iftex
@c end inserted refs from types.doc:917
@c ------------------------------
@node intmat operations, intmat related functions, intmat type cast, intmat
@subsection intmat operations
@cindex intmat operations

@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{==}
comparison

@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 reused example intmat_operations types.doc:954 
  intmat m[2][4] = 1,0,2,4,0,1,-1,0,3,2,1,-2;
  m;
@expansion{} 1,0,2,4,
@expansion{} 0,1,-1,0 
  m[2,3];          // entry at row 2, col 3
@expansion{} -1
  size(m);         // number of entries
@expansion{} 8
  intvec v = 1,0,-1,2;
  m * v;
@expansion{} 7,1
  typeof(_);
@expansion{} intvec
  intmat m1[4][3] = 0,1,2,3,v,1;
  intmat m2 = m * m1;
  m2;             //  2 x 3 intmat
@expansion{} -2,5,4,
@expansion{} 4,-1,-1 
  m2*10;           // multiply each entry of m with 10;
@expansion{} -20,50,40,
@expansion{} 40,-10,-10 
  -m2;
@expansion{} 2,-5,-4,
@expansion{} -4,1,1 
  m2 % 2;
@expansion{} 0,1,0,
@expansion{} 0,1,1 
  m2 div 2;
@expansion{} -1,2,2,
@expansion{} 2,-1,-1 
  m2[2,1];          // entry at row 2, col 1
@expansion{} 4
  m1[2..3,2..3];   // submatrix
@expansion{} 1 0 2 1
  m2[nrows(m2),ncols(m2)];      // the last entry of intmat m2
@expansion{} -1
@c end example intmat_operations types.doc:954
@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
create a 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 reused example intvec_declarations types.doc:1045 
  intvec iv=1,3,5,7,8;
  iv;
@expansion{} 1,3,5,7,8
  iv[4];
@expansion{} 7
  iv[3..size (iv)];
@expansion{} 5 7 8
@c end example intvec_declarations types.doc:1045
@end smallexample
@end table

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

An intvec expression is:
@enumerate
@item
a range: int expression @code{..} int expression
@item
a function returning intvec
@item
intvec operations with int (@code{+}, @code{-}, @code{*}, @code{/}, @code{%})
@item
intvec operations (@code{+}, @code{-})
@item
intvec operation with intmat (@code{*})
@item
a type cast to intvec
@end enumerate

@*@strong{Example:}
@smallexample
@c reused example intvec_expressions types.doc:1077 
  intvec v=-1,2;
  intvec w=v,v;         // concatenation
  w;
@expansion{} -1,2,-1,2
  w = -2..2,v,1;
  w;
@expansion{} -2,-1,0,1,2,-1,2,1
  intmat m[3][2] = 0,1,2,-2,3,1;
  m*v;
@expansion{} 2,-6,-1
  typeof(_);
@expansion{} intvec
  v = intvec(m);
  v;
@expansion{} 0,1,2,-2,3,1
  ring r;
  poly f = x2z + 2xy-z;
  f;
@expansion{} x2z+2xy-z
  v = leadexp(f);
  v;
@expansion{} 2,0,1
@c end example intvec_expressions types.doc:1077
@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 reused example intvec_operations types.doc:1126 
  intvec iv =  1,3,5,7,8;
  iv+1;               // add 1 to each entry
@expansion{} 2,4,6,8,9
  iv*2;
@expansion{} 2,6,10,14,16
  iv;
@expansion{} 1,3,5,7,8
  iv-10;
@expansion{} -9,-7,-5,-3,-2
  iv=iv,0;
  iv;
@expansion{} 1,3,5,7,8,0
  iv div 2;
@expansion{} 0,1,2,3,4,0
  iv+iv;              // component-wise addition
@expansion{} 2,6,10,14,16,0
  iv[size(iv)-1];     // last-1 entry
@expansion{} 8
  intvec iw=2,3,4,0;
  iv==iw;             // lexicographic comparison
@expansion{} 0
  iv < iw;
@expansion{} 1
  iv != iw;
@expansion{} 1
  iv[2];
@expansion{} 3
  iw = 4,1,2;
  iv[iw];
@expansion{} 7 1 3
@c end example intvec_operations types.doc:1126
@end smallexample

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

@table @code
@item hilb
returns 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 nrows
number of rows (see @ref{nrows})
@item qhweight
returns 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
returns 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 DBM links (see
@ref{DBM links})
@end itemize

@menu
* link declarations::
* link expressions::
* link related functions::
* ASCII links::
* MP 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 reused example link_declarations types.doc:1224 
  link l=":w example.txt";
  int i=22;          // cf. ASCII links for explanation
  string s="An int follows:";
  write(l,s,i);
  l;
@expansion{} // type : ASCII
@expansion{} // mode : w
@expansion{} // name : example.txt
@expansion{} // open : yes
@expansion{} // read : not ready
@expansion{} // write: ready
  close(l);          //
  read(l);
@expansion{} An int follows:
@expansion{} 22
@expansion{} 
  close(l);
@c end example link_declarations types.doc:1224
@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 for DBM links:
@ref{DBM links}
@end itemize
@end iftex

@menu
* ASCII links::
* MPfile links::
* MPtcp 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 reused example ASCII_links types.doc:1364 
  ring r=32003,(x,y,z),dp;
  link l=":w example.txt";     // type is ASCII, mode is overwrite
  l;
@expansion{} // type : ASCII
@expansion{} // mode : w
@expansion{} // name : example.txt
@expansion{} // open : no
@expansion{} // read : not ready
@expansion{} // write: not ready
  status(l, "open", "yes");    // link is not yet opened
@expansion{} 0
  ideal i=x2,y2,z2;
  write (l,1,";",2,";","ideal i=",i,";");
  status(l, "open", "yes");    // now link is open
@expansion{} 1
  status(l, "mode");           // for writing
@expansion{} w
  close(l);                    // link is closed
  write("example.txt","int j=5;");// data is appended to file
  read("example.txt");         // data is returned as string
@expansion{} 1
@expansion{} ;
@expansion{} 2
@expansion{} ;
@expansion{} ideal i=
@expansion{} x2,y2,z2
@expansion{} ;
@expansion{} int j=5;
@expansion{} 
  execute(read(l));            // read string is executed
@expansion{} 1
@expansion{} 2
@expansion{} // ** redefining i **
  close(l);                    // link is closed
@c end example ASCII_links types.doc:1364
@c  // dump vars overwriting previous file content:
@c  dump(":w example.txt");
@end smallexample

@c ------------------------------
@node MP links, DBM 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.

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://symbolicnet.mcs.kent.edu/areas/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 reused example MPfile_links types.doc:1453 
  ring r;
  link l="MPfile:w example.mp"; // type=MPfile, mode=overwrite
  l;
@expansion{} // type : MPfile
@expansion{} // mode : w
@expansion{} // name : example.mp
@expansion{} // open : no
@expansion{} // read : not ready
@expansion{} // write: not ready
  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
@expansion{} 1
  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);
@expansion{} // mpsr_r0              [0]  *ring
  def s = read(l);              // third expression
  listvar();
@expansion{} // s                    [0]  string hello world
@expansion{} // mpsr_r0              [0]  *ring
@expansion{} //      i                    [0]  ideal, 3 generator(s)
@expansion{} // l                    [0]  link
@expansion{} // LIB                  [0]  string standard.lib
  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
@expansion{} // mpsr_r0              [0]  *ring
@expansion{} //      i                    [0]  ideal, 3 generator(s)
@expansion{} // s                    [0]  string hello world
@expansion{} // l                    [0]  link
@expansion{} // LIB                  [0]  string standard.lib
@c end example MPfile_links types.doc:1453
@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{mp_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{mp_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 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 reused example MPtcp_links types.doc:1601 
  LIB "general.lib"; // needed for "killall" command
  link l="MPtcp:launch";
  open(l); l;        // l is ready for writing but not for reading
@expansion{} // type : MPtcp
@expansion{} // mode : launch
@expansion{} // name : 
@expansion{} // open : yes
@expansion{} // read : not ready
@expansion{} // write: ready

  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
@expansion{} j[1]=z
@expansion{} j[2]=y2-y
@expansion{} j[3]=x2+y2

  write(l, quote(getdump(mp_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
@expansion{} // ** killing the basering for level 0

  write(l, quote(dump(mp_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()"
@expansion{} // mpsr_r0              [0]  ring
@expansion{} // r                    [0]  *ring
@expansion{} //      j                    [0]  ideal, 3 generator(s)
@expansion{} //      i                    [0]  ideal, 3 generator(s)
@expansion{} // l                    [0]  link

  l = "MPtcp:";      // fork link declaration
  open(l); l;        // Notice that name is "parent"
@expansion{} // type : MPtcp
@expansion{} // mode : fork
@expansion{} // name : parent
@expansion{} // open : yes
@expansion{} // read : not ready
@expansion{} // write: ready

  write(l, quote(status(mp_ll, "name")));
  read(l);           // and name of forked link is "child"
@expansion{} child
  write(l,quote(i)); // Child inherited vars and their values
  read(l);
@expansion{} _[1]=x2+y
@expansion{} _[2]=xyz+z
@expansion{} _[3]=x2+y2
  close(l);          // shut down forked child
@c end example MPtcp_links types.doc:1601
@end smallexample

@c ------------------------------
@node DBM links,  , MP 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 reused example DBM_links types.doc:1672 
  link l="DBM:rw example";
  write(l,"1","abc");
  write(l,"3","XYZ");
  write(l,"2","ABC");
  l;
@expansion{} // type : DBM
@expansion{} // mode : rw
@expansion{} // name : example
@expansion{} // open : yes
@expansion{} // read : ready
@expansion{} // write: ready
  close(l);
  // read all keys (till empty string):
  read(l);
@expansion{} 1
  read(l);
@expansion{} 3
  read(l);
@expansion{} 2
  read(l);
@expansion{} 
  // read data corresponding to key "1"
  read(l,"1");
@expansion{} abc
  // read all data:
  read(l,read(l));
@expansion{} abc
  read(l,read(l));
@expansion{} XYZ
  read(l,read(l));
@expansion{} ABC
  // close
  close(l);
@c end example DBM_links types.doc:1672
@end smallexample

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

Lists are arrays whose elements can be of any type (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 reused example list_declarations types.doc:1739 
  list l=1,"str";
  l[1];
@expansion{} 1
  l[2];
@expansion{} str
  ring r;
  listvar(r);
@expansion{} // r                    [0]  *ring
  ideal i = x^2, y^2 + z^3;
  l[3] = i;
  l;
@expansion{} [1]:
@expansion{}    1
@expansion{} [2]:
@expansion{}    str
@expansion{} [3]:
@expansion{}    _[1]=x2
@expansion{}    _[2]=z3+y2
  listvar(r);     // the list l belongs now to the ring r
@expansion{} // r                    [0]  *ring
@expansion{} // l                    [0]  list, size: 3
@expansion{} // i                    [0]  ideal, 2 generator(s)
@c end example list_declarations types.doc:1739
@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 inserted refs from types.doc:1772
@ifinfo
@menu
See 
* Type conversion and casting::
@end menu
@end ifinfo
@iftex
See 
@ref{Type conversion and casting}.
@end iftex
@c end inserted refs from types.doc:1772

@*@strong{Example:}
@smallexample
@c reused example list_expressions types.doc:1778 
  list l = "hello",1;
  l;
@expansion{} [1]:
@expansion{}    hello
@expansion{} [2]:
@expansion{}    1
  l = list();
  l;
@expansion{} empty list
  ring r =0,x,dp;
  factorize((x+1)^2);
@expansion{} [1]:
@expansion{}    _[1]=1
@expansion{}    _[2]=x+1
@expansion{} [2]:
@expansion{}    1,2
  list(1,2,3);
@expansion{} [1]:
@expansion{}    1
@expansion{} [2]:
@expansion{}    2
@expansion{} [3]:
@expansion{}    3
@c end example list_expressions types.doc:1778
@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 reused example list_operations types.doc:1807 
  list l1 = 1,"hello",list(-1,1);
  list l2 = list(1,2,3);
  l1 + l2;          // one new list
@expansion{} [1]:
@expansion{}    1
@expansion{} [2]:
@expansion{}    hello
@expansion{} [3]:
@expansion{}    [1]:
@expansion{}       -1
@expansion{}    [2]:
@expansion{}       1
@expansion{} [4]:
@expansion{}    1
@expansion{} [5]:
@expansion{}    2
@expansion{} [6]:
@expansion{}    3
  list l3 =_;
  l1,l2;            // two lists
@expansion{} [1]:
@expansion{}    1
@expansion{} [2]:
@expansion{}    hello
@expansion{} [3]:
@expansion{}    [1]:
@expansion{}       -1
@expansion{}    [2]:
@expansion{}       1
@expansion{} [1]:
@expansion{}    1
@expansion{} [2]:
@expansion{}    2
@expansion{} [3]:
@expansion{}    3
  l2[2];
@expansion{} 2
@c end example list_operations types.doc:1807
@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
deletes 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
inserts or appends a new element to a list (see @ref{insert})
@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 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 is stored "by name", that means, maps can only be
used in such contexts, where the name of the preimage ring can be
resolved (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

@item
@tex
$Q \rightarrow R$
@end tex
@ifinfo
Q -> R
@end ifinfo

@item
@tex
$Q \rightarrow  C$
@end tex
@ifinfo
Q -> C
@end ifinfo

@item
@tex
$Z/p \rightarrow  (Z/p)(a, \ldots)$
@end tex
@ifinfo
Z/p ->(Z/p)(a,...)
@end ifinfo

@item
@tex
$Z/p \rightarrow  GF(p^n)$
@end tex
@ifinfo
Z/p -> GF(p^n)
@end ifinfo

@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$ the real part
@end tex
@ifinfo
C -> R : the real part
@end ifinfo
@end itemize

Finally, in 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::
* fetch::
* imap::
* subst::
@end menu
@iftex
See @ref{imap}; @ref{fetch}; @ref{subst}.
@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 actual 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 reused example map_declarations types.doc:2044 
  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);
@expansion{} _[1]=a
@expansion{} _[2]=b
@expansion{} _[3]=a+b
  // 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);
@expansion{} _[1]=a2
@expansion{} _[2]=b2
@expansion{} _[3]=a2+b2
@c end example map_declarations types.doc:2044
@end smallexample
@end table

@c inserted refs from types.doc:2069
@ifinfo
@menu
See 
* fetch::
* ideal expressions::
* imap::
* map::
* ring::
@end menu
@end ifinfo
@iftex
See 
@ref{fetch};
@ref{ideal expressions};
@ref{imap};
@ref{map};
@ref{ring}.
@end iftex
@c end inserted refs from types.doc:2069

@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 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 of @code{f}
and @code{g}.

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

@*@strong{Example:}
@smallexample
@c reused example map_operations types.doc:2107 
  ring r=0,(x,y),dp;
  map f=r,y,x;    // the map f permutes the variables
  f;
@expansion{} f[1]=y
@expansion{} f[2]=x
  poly p=x+2y3;
  f(p);
@expansion{} 2x3+y
  map g=f(f);    // the map g defined as  f^2 is the identity
  g;
@expansion{} g[1]=x
@expansion{} g[2]=y
  g(p) == p;
@expansion{} 1
@c end example map_operations types.doc:2107
@end smallexample

@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
poly is converted into a matrix of the right size with the poly 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 reused example matrix_declarations types.doc:2175 
  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;
@expansion{} m[1,1]=x3y4
@expansion{} m[1,2]=0
@expansion{} m[1,3]=xyz
@expansion{} m[2,1]=xyz2
@expansion{} m[2,2]=x2y2z4
@expansion{} m[2,3]=xyz
@expansion{} m[3,1]=0
@expansion{} m[3,2]=0
@expansion{} m[3,3]=0
  print(m);
@expansion{} x3y4,0,     xyz,
@expansion{} xyz2,x2y2z4,xyz,
@expansion{} 0,   0,     0   
  matrix A;   // the 1 x 1 zero matrix
  matrix B[2][2] = m[1..2, 2..3]; //defines a submatrix
  print(B);
@expansion{} 0,     xyz,
@expansion{} x2y2z4,xyz 
  matrix C=m; // defines C as a 3 x 3 matrix equal to m
  print(C);
@expansion{} x3y4,0,     xyz,
@expansion{} xyz2,x2y2z4,xyz,
@expansion{} 0,   0,     0   
@c end example matrix_declarations types.doc:2175
@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 reused example matrix_expressions types.doc:2213 
  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);
@expansion{} y2,    1,
@expansion{} x3+2x2,2 
  module MD = [x+y,1,x],[x+y,0,y];
  matrix M = MD;
  print(M);
@expansion{} x+y,x+y,
@expansion{} 1,  0,  
@expansion{} x,  y   
@c end example matrix_expressions types.doc:2213
@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
are determined  by the size (resp.@: dimensions) of the
expression.
@item @strong{Example:}
@smallexample
@c reused example matrix_type_cast types.doc:2244 
  ring r=32003,(x,y,z),dp;
  matrix(x);
@expansion{} _[1,1]=x
  matrix(x, 1, 2);
@expansion{} _[1,1]=x
@expansion{} _[1,2]=0
  matrix(intmat(intvec(1,2,3,4), 2, 2));
@expansion{} _[1,1]=1
@expansion{} _[1,2]=2
@expansion{} _[2,1]=3
@expansion{} _[2,2]=4
  matrix(_, 2, 3);
@expansion{} _[1,1]=1
@expansion{} _[1,2]=2
@expansion{} _[1,3]=0
@expansion{} _[2,1]=3
@expansion{} _[2,2]=4
@expansion{} _[2,3]=0
  matrix(_, 2, 1);
@expansion{} _[1,1]=1
@expansion{} _[2,1]=3
@c end example matrix_type_cast types.doc:2244
@end smallexample
@end table
@c inserted refs from types.doc:2254
@ifinfo
@menu
See
* Type conversion and casting::
* intmat type cast::
* matrix::
@end menu
@end ifinfo
@iftex
See
@ref{Type conversion and casting};
@ref{intmat type cast};
@ref{matrix}.
@end iftex
@c end inserted refs from types.doc:2254
@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 poly is converted into a diagonal
matrix

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

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

@item @code{/}
division by poly

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

@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 reused example matrix_operations types.doc:2291 
  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
@expansion{} 1,3,2,
@expansion{} 5,0,3,
@expansion{} 2,4,5 
  A[2,3];   // matrix entry
@expansion{} 3
  A[2,3] = A[2,3] + 1; // change entry
  A[2,1..3] = 1,2,3;   // change 2nd row
  print(A);
@expansion{} 1,3,2,
@expansion{} 1,2,3,
@expansion{} 2,4,5 
  matrix E[3][3]; E = E + 1;  // the unit matrix
  matrix B =x*E - A;
  print(B);
@expansion{} x-1,-3, -2,
@expansion{} -1, x-2,-3,
@expansion{} -2, -4, x-5
  det(B);        // the characteristic polynomial of A
@expansion{} x3-8x2-2x-1
  A*A*A - 8 * A*A - 2*A == E;  // Cayley-Hamilton
@expansion{} 1
  vector v =[x,-1,x2];
  A*v; // multiplication of matrix and vector
@expansion{} _[1,1]=2x2+x-3
@expansion{} _[2,1]=3x2+x-2
@expansion{} _[3,1]=5x2+2x-4
  matrix m[2][2]=1,2,3;
  print(m-transpose(m));
@expansion{} 0,-1,
@expansion{} 1,0  
@c end example matrix_operations types.doc:2291
@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
transpose a 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.
If 
@ifinfo
@math{M}
@end ifinfo
@tex
$M$
@end tex
 is a submodule of
@ifinfo
R^n,
@end ifinfo
@tex
$R^n$,
@end tex

@ifinfo
@math{R}
@end ifinfo
@tex
$R$
@end tex
 the basering, generated by vectors
@ifinfo
v_1, @dots{}, v_k, then v_1, @dots{}, v_k
@end ifinfo
@tex
$v_1, \ldots, v_k$, then $v_1, \ldots, v_k$
@end tex
may be considered as the generators of relations of
@ifinfo
R^n/M
@end ifinfo
@tex
$R^n/M$
@end tex
between the canonical generators @code{gen(1)},@dots{},@code{gen(n)}.
Hence any finitely generated 
@ifinfo
@math{R}
@end ifinfo
@tex
$R$
@end tex
-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
@ifinfo
n x k
@end ifinfo
@tex
n$\times$k
@end tex
 for
@ifinfo
R^n/M,
@end ifinfo
@tex
R$^n$/M,
@end tex
i.e., the columns of A are the vectors
@ifinfo
v_1, @dots{}, v_k
@end ifinfo
@tex
$v_1, \ldots, v_k$
@end tex
which generate M (cf. @ref{Representation of mathematical objects}).

@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 reused example module_declarations types.doc:2445 
  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;
@expansion{} m[1]=[x2,y3,z]
@expansion{} m[2]=[-x2+xy,-y3+1,-z]
@expansion{} m[3]=[-x3yz,-xy4z+x3yz-xy3z]
  // show m in matrix format (columns generate m)
  print(m);
@expansion{} x2,-x2+xy,-x3yz,          
@expansion{} y3,-y3+1, -xy4z+x3yz-xy3z,
@expansion{} z, -z,    0               
@c end example module_declarations types.doc:2445
@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 inserted refs from types.doc:2478
@ifinfo
@menu
See
* Type conversion and casting::
* ideal::
* poly::
* vector::
@end menu
@end ifinfo
@iftex
See
@ref{Type conversion and casting};
@ref{ideal};
@ref{poly};
@ref{vector}.
@end iftex
@c end inserted refs from types.doc:2478

@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
@end table

@*@strong{Example:}
@smallexample
@c reused example module_operations types.doc:2514 
  ring r=0,(x,y,z),dp;
  module m=[x,y],[0,0,z];
  print(m*(x+y));
@expansion{} x2+xy,0,   
@expansion{} xy+y2,0,   
@expansion{} 0,    xz+yz
@c end example module_operations types.doc:2514
@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 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
minimize 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
simplify 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
substitute 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 ---------------------------------------
@ifset namespaces
@node number, package, module, Data types
@end ifset
@ifclear namespaces
@node number, poly, module, Data types
@end ifclear
@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).
See @ref{number operations}, @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 reused example number_declarations types.doc:2677 
  // finite field Z/p, p<= 32003
  ring r = 32003,(x,y,z),dp;
  number n = 4/6;
  n;
@expansion{} -10667
  // 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;
@expansion{} z11
  // the rational numbers
  ring r0 = 0,x,dp;
  number n = 4/6;
  n;
@expansion{} 2/3
  // algebraic extensions of Z/p or Q
  ring ra=(0,a),x,dp;
  minpoly=a^2+1;
  number n=a3+a2+2a-1;
  n;
@expansion{} (a-2)
  a^2;
@expansion{} -1
  // transcedental extensions of Z/p or Q
  ring rt=(0,a),x,dp;
  number n=a3+a2+2a-1;
  n;
@expansion{} (a3+a2+2a-1)
  a^2;
@expansion{} (a2)
  // machine floating point numbers, single precision
  ring R_0=real,x,dp;
  number n=4/6;
  n;
@expansion{} 6.667e-01
  n=0.25e+2;
  n;
@expansion{} 2.500e+01
  // floating point numbers, arbitrary prescribed precision
  ring R_1=(real,50),x,dp;
  number n=4.0/6;
  n;
@expansion{} 0.66666666666666666666666666666666666666666666666667
  n=0.25e+2;
  n;
@expansion{} 25
  // 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;
@expansion{} 0.66666666666666666666666666666666666666666666666667
  n=0.25e+2*i+n;
  n;
@expansion{} (0.66666666666666666666666666666666666666666666666667+i*25)
@c end example number_declarations types.doc:2677
@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 reused example number_expressions types.doc:2753 
  // the following expressions are in any ring int expressions
  2 / 3;
@expansion{} 0
  4/ 8;
@expansion{} 0
  2 /2;   // the notation of / for div might change in the future
@expansion{} 1
  ring r0=0,x,dp;
  2/3, 4/8, 2/2 ; // are numbers
@expansion{} 2/3 1/2 1

  poly f = 2x2 +1;
  leadcoef(f);
@expansion{} 2
  typeof(_);
@expansion{} number
  ring rr =real,x,dp;
  1.7e-2; 1.7e+2; // are valid (but  1.7e2 not), if the field is `real`
@expansion{} 1.700e-02
@expansion{} 1.700e+02
  ring rp = (31,t),x,dp;
  2/3, 4/8, 2/2 ; // are numbers
@expansion{} 11 -15 1
  poly g = (3t2 +1)*x2 +1;
  leadcoef(g);
@expansion{} (3t2+1)
  typeof(_);
@expansion{} number
  par(1);
@expansion{} (t)
  typeof(_);
@expansion{} number
@c end example number_expressions types.doc:2753
@end smallexample
@c inserted refs from types.doc:2775
@ifinfo
@menu
See
* Type conversion and casting::
* ring::
@end menu
@end ifinfo
@iftex
See
@ref{Type conversion and casting};
@ref{ring}.
@end iftex
@c end inserted refs from types.doc:2775

@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 reused example number_operations types.doc:2813 
  ring r=0,x,dp;
  number n = 1/2 +1/3;
  n;
@expansion{} 5/6
  n/2;
@expansion{} 5/12
  1/2/3;
@expansion{} 1/6
  1/2 * 1/3;
@expansion{} 1/6
  n = 2;
  n^-2;
@expansion{} 1/4
  // the following oddities appear here
  2/(2+3);
@expansion{} 0
  number(2)/(2+3);
@expansion{} 2/5
  2^-2; // for int's exponent must be non-negative
@expansion{}    ? exponent must be non-negative
@expansion{}    ? error occurred in line 12: `  2^-2; // for int's exponent must be no\
   n-negative`
  number(2)^-2;
@expansion{} 1/4
  3/4>=2/5;
@expansion{} 1
  2/6==1/3;
@expansion{} 1
@c end example number_operations types.doc:2813
@end smallexample

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

@table @code
@item cleardenom
cancel denominators of numbers in poly 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
return 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 ---------------------------------------
@ifset namespaces
@node package, poly, number, Data types
@section package
@cindex package
@cindex ::

Package are a collection of identifier.
The set of all identifier is called toplevel package: @code{Top}.
Other reserved package names are @code{Current} with denotes the current
package name in use, and @code{Up} which will be the current package
when leave the current one.
@ref{Libraries}, @ref{Namespaces}.

@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

@item Example:
@smallexample
@c reused example package_declarations types.doc:2894 
  package Test;
  int Test::i;
@expansion{}    ? package is not supported in this version
@expansion{}    ? object to declare is not a name
@expansion{}    ? error occurred in line 2: `  int Test::i;`
@expansion{}    ? wrong type declaration. type 'help int;'
  listvar();
@expansion{} // Test                 [0]  package (N)
@expansion{} // LIB                  [0]  string standard.lib
  listvar(Test);
@expansion{} // Test                 [0]  package (N)
  package dummy = Test;
  kill Test;
@expansion{} // ** unknown type to kill: package(452)
  listvar(dummy);
@expansion{} // dummy                [0]  package (N)
@c end example package_declarations types.doc:2894
@end smallexample
@end table

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

@table @code
@item exportto
(see @ref{exportto})
@item importfrom
(see @ref{importfrom})
@item listvar
(see @ref{listvar})
@item names
(see @ref{names})
@item load
(see @ref{load})
@item LIB
(see @ref{LIB})
@item system
@code{system("nsstack")}
@code{system("nspop")}
@code{system("nspush",}package @code{)}
(see @ref{system})
@end table
@end ifset

@c ---------------------------------------
@ifset namespaces
@node poly, proc, package, Data types
@end ifset
@ifclear namespaces
@node poly, proc, number, Data types
@end ifclear
@section poly
@cindex poly

Polynomials are the basic data for all main algorithms in
@code{@sc{Singular}}. They consist of finitely many terms
(coefficient*power product) 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 reused example poly types.doc:2950 
  ring r=32003,(x,y,z),dp;
  poly f=x3+y5+z2;
@c end example poly types.doc:2950
@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 reused example poly_declarations types.doc:2980 
  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;
@expansion{} x37y5z4+3x37+xy9
  short = 0;
  f;
@expansion{} x^37*y^5*z^4+3*x^37+x*y^9
@c end example poly_declarations types.doc:2980
@end smallexample
@end table
@c inserted refs from types.doc:2993
@ifinfo
@menu
See also:
* short::
@end menu
@end ifinfo
@iftex
@strong{See also:}
@ref{short}.
@end iftex
@c end inserted refs from types.doc:2993
@c ------------------------------
@node poly expressions, poly operations, poly declarations, poly
@subsection poly expressions
@cindex poly expressions

A poly 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
poly 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
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*x(1); // is a valid poly expression, but not 2x(1) (a syntax error)
2*x^3;  // is a valid poly 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 reused example poly_expressions types.doc:3032 
  ring r=0,(x,y),dp;
  poly f = 10x2y3 +2x2y2-2xy+y -x+2;
  lead(f);
@expansion{} 10x2y3
  leadmonom(f);
@expansion{} x2y3
  simplify(f,1);     // normalize leading coefficient
@expansion{} x2y3+1/5x2y2-1/5xy-1/10x+1/10y+1/5
  poly g = 1/2x2 + 1/3y;
  cleardenom(g);
@expansion{} 3x2+2y
  int i = 102;
  poly(i);
@expansion{} 102
  typeof(_);
@expansion{} poly
@c end example poly_expressions types.doc:3032
@end smallexample

@c inserted refs from types.doc:3046
@ifinfo
@menu
See 
* Type conversion and casting::
* ring::
@end menu
@end ifinfo
@iftex
See 
@ref{Type conversion and casting};
@ref{ring}.
@end iftex
@c end inserted refs from types.doc:3046

@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, ignoring the rest

@item @code{^}, @code{**}
power by an integer

@item @code{<}, @code{<=}, @code{>}, @code{>=}, @code{==}, @code{<>}
comparison (w.r.t. monomial ordering)

@item poly_expression @code{[} intvec_expression @code{]}
the monomial at the indicated place w.r.t.@: the monomial ordering
@end table

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

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

@table @code
@item cleardenom
cancel denominators of numbers in poly and divide it by its content
(see @ref{cleardenom})
@item coef
matrix of coefficients and monomials (see @ref{coef})
@item coeffs
matrix of coefficients (see @ref{coeffs})
@item deg
degree (see @ref{deg})
@item det
determinant (see @ref{det})
@item diff
partial derivative (see @ref{diff})
@item extgcd
Bezout representation of gcd (see @ref{extgcd})
@item factorize
factorize polynomial (see @ref{factorize})
@item finduni
find 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 with degree smaller k+1 (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
normalize a polynomial (see @ref{simplify})
@item size
number of monomials (see @ref{size})
@item subst
substitute 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 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_text"]
@*@code{@{}
@*
@tex
\quad
@end tex
   procedure_body
@*@code{@}}
@*[@code{example}
@*@code{@{}
@*
@tex
\quad
@end tex
   sequence_of_commands;
@*@code{@}}]
@*@code{proc} proc_name @code{=} proc_name @code{;}
@*@code{proc} proc_name @code{=} string_expression @code{;}
@item Purpose:
defines a new function, the @code{proc} proc_name, with the additional
information help_text, which is copied to the screen by
@code{help proc_name;} and the @code{example} section
which is executed by @code{example proc_name;}.
@* The help_text, the parameter_list, and the example section are optional.
The default for a parameter_list is @code{(list #)}, see @ref{Parameter list}.
The help and example sections are ignored if the procedure is defined
interactively, i.e., if it was not loaded from a file by a @ref{LIB} command.
@* Specifying @code{static} in front of the proc-definition is only possible
in a library file and makes this procedure local to the library,
i.e., accessible only for the other procedures in the same library,
but not for the users.

@item Example:
@smallexample
@c reused example proc_declaration types.doc:3237 
  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);
@expansion{} 4
@c end example proc_declaration types.doc:3237
@end smallexample
@end table
@c inserted refs from types.doc:3254
@ifinfo
@menu
See
* LIB::
* Libraries::
* Procedures::
@end menu
@end ifinfo
@iftex
See
@ref{LIB};
@ref{Libraries};
@ref{Procedures}.
@end iftex
@c end inserted refs from types.doc:3254



@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.  Sets
it as current basering.
@item Example:
@smallexample
@c reused example qring_declaration types.doc:3297 
ring r=0,(x,y,z),dp;
ideal i=xy;
qring q=std(i);
basering;
@expansion{} //   characteristic : 0
@expansion{} //   number of vars : 3
@expansion{} //        block   1 : ordering dp
@expansion{} //                  : names    x y z 
@expansion{} //        block   2 : ordering C
@expansion{} // quotient ring from ideal
@expansion{} _[1]=xy
@c end example qring_declaration types.doc:3297
@end smallexample
@end table

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

The resolution type 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.

@strong{Note:}
to access the elements of a resolution, it has to be assigned to a list,
which 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 reused example resolution_declarations types.doc:3346 
  ring R;
  ideal i=z2,x;
  resolution re=res(i,0);
  re;
@expansion{}  1      2      1      
@expansion{} R <--  R <--  R
@expansion{} 
@expansion{} 0      1      2      
@expansion{} resolution not minimized yet
@expansion{} 
  betti(re);
@expansion{} 1,1,0,
@expansion{} 0,1,1 
  list l = re;
  l;
@expansion{} [1]:
@expansion{}    _[1]=x
@expansion{}    _[2]=z2
@expansion{} [2]:
@expansion{}    _[1]=-z2*gen(1)+x*gen(2)
@expansion{} [3]:
@expansion{}    _[1]=0
@c end example resolution_declarations types.doc:3346
@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 inserted refs from types.doc:3373
@ifinfo
@menu
See 
* Type conversion and casting::
@end menu
@end ifinfo
@iftex
See 
@ref{Type conversion and casting}.
@end iftex
@c end inserted refs from types.doc:3373

@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 w.r.t. 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{= (} coefficient_field @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 coefficient_field is 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.
@end enumerate

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

'names_of_ring_variables' must be a list of names or indexed names.

'ordering' is a list of block orderings where each block ordering is either
@enumerate
@item
@code{lp}, @code{dp}, @code{Dp}, @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 coefficient_field, names_of_ring_variables, and ordering
consists of only one entry, the parentheses around this entry may be
omitted.

@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 setring
set 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 
@ifinfo
@math{k[X,Y]}
@end ifinfo
@tex
$k[X,Y]$
@end tex
 from 
@ifinfo
@math{k_1[X]}
@end ifinfo
@tex
$k_1[X]$
@end tex
  and 
@ifinfo
@math{k_2[Y]}
@end ifinfo
@tex
$k_2[Y]$
@end tex
.
@end table

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


@strong{Example:}
@smallexample
@c reused example ring_operations types.doc:3527 
  ring R1=0,(x,y),dp;
  ring R2=32003,(a,b),dp;
  def R=R1+R2;
  R;
@expansion{} //   characteristic : 32003
@expansion{} //   number of vars : 4
@expansion{} //        block   1 : ordering dp
@expansion{} //                  : names    x y 
@expansion{} //        block   2 : ordering dp
@expansion{} //                  : names    a b 
@expansion{} //        block   3 : ordering C
@c end example ring_operations types.doc:3527
@end smallexample

@c inserted refs from types.doc:3535
@ifinfo
@menu
See also:
* ring_lib::
@end menu
@end ifinfo
@iftex
@strong{See also:}
@ref{ring_lib}.
@end iftex
@c end inserted refs from types.doc:3535

@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 reused example string types.doc:3558 
  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;
@expansion{} Hi
@expansion{} a string with new line at the end
@expansion{} 
@expansion{} another string with new line at the end
@expansion{}   
  ring r; ideal i=std(ideal(x,y^3));
  "dimension of i =",dim(i),", multiplicity of i =",mult(i);
@expansion{} dimension of i = 1 , multiplicity of i = 3
  "dimension of i = "+string(dim(i))+", multiplicity of i = "+string(mult(i));
@expansion{} dimension of i = 1, multiplicity of i = 3
  "a"+"b","c";
@expansion{} ab c
@c end example string types.doc:3558
@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 reused example string_declarations types.doc:3600 
  string s1="Now I know";
  string s2="how to encode a \" in a string...";
  string s=s1+" "+s2; // concatenation of 3 strings
  s;
@expansion{} Now I know how to encode a " in a string...
  s1,s2;   // 2 strings, separated by a blank in the output:
@expansion{} Now I know how to encode a " in a string...
@c end example string_declarations types.doc:3600
@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 reused example string_expressions types.doc:3639 
// 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];
@expansion{} 2345
"abcd"[2,2];
@expansion{} bc
// string_expression[position] : a character from a string
s[3];
@expansion{} 3
// string_expression[position..position] :
// a substring starting at the first position up to the second
// given position
s[2..4];
@expansion{} 2 3 4
// a function returning a string
typeof(s);
@expansion{} string
@c end example string_expressions types.doc:3639
@end smallexample

@c inserted refs from types.doc:3658
@ifinfo
@menu
See 
* Type conversion and casting::
* string type cast::
@end menu
@end ifinfo
@iftex
See 
@ref{Type conversion and casting};
@ref{string type cast}.
@end iftex
@c end inserted refs from types.doc:3658

@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 concersions 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 reused example string_type_cast types.doc:3688 
  string("1+1=", 2);
@expansion{} 1+1=2
  string(intvec(1,2,3,4));
@expansion{} 1,2,3,4
  string(intmat(intvec(1,2,3,4), 2, 2));
@expansion{} 1,2,3,4 
  ring r;
  string(r);
@expansion{} (32003),(x,y,z),(dp(3),C)
  string(ideal(x,y));
@expansion{} x,y
  qring R = std(ideal(x,y));
  string(R);
@expansion{} (32003),(x,y,z),(dp(3),C)
  map phi = r, ideal(x,z);
  string(phi);
@expansion{} x,z
  list l;
  string(l);
@expansion{} 
  l[3] = 1;
  string(l); // notice that l[1],l[2] are omitted
@expansion{} 1
  l[2] = l;
  l;
@expansion{} [2]:
@expansion{}    [3]:
@expansion{}       1
@expansion{} [3]:
@expansion{}    1
  string(l); // notice that lists of list is flattened
@expansion{} 1,1
  l[1] = intvec(1,2,3);
  l;
@expansion{} [1]:
@expansion{}    1,2,3
@expansion{} [2]:
@expansion{}    [3]:
@expansion{}       1
@expansion{} [3]:
@expansion{}    1
  string(l); // notice that intvec elements are not distinguishable
@expansion{} 1,2,3,1,1
@c end example string_type_cast types.doc:3688
@end smallexample
@end table
@c inserted refs from types.doc:3712
@ifinfo
@menu
See
* Type conversion and casting::
* print::
* string::
@end menu
@end ifinfo
@iftex
See
@ref{Type conversion and casting};
@ref{print};
@ref{string}.
@end iftex
@c end inserted refs from types.doc:3712

@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 reused example string_operations types.doc:3745 
  string s="abcde";
  s[2];
@expansion{} b
  s[3,2];
@expansion{} cd
  ">>"+s[1,10]+"<<";
@expansion{} >>abcde     <<
  s[2]="BC"; s;
@expansion{} aBcde
  intvec v=1,3,5;
  s=s[v]; s;
@expansion{} ace
  s="123456"; s=s[3..5]; s;
@expansion{} 345
@c end example string_operations types.doc:3745
@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,  , 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{} .
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.
Like polynomials they
can only be defined or accessed with respect to the basering.
(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 reused example vector_declarations types.doc:3840 
  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;
@expansion{} [x2,y3-x2,-x2+z,0,x2]
@c end example vector_declarations types.doc:3840
@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 poly 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 poly 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 reused example vector_expressions types.doc:3877 
  // 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;
@expansion{} [y3+x2,2,0,xy,0,x6]
  vector w=[z3-x,3y];
  v-w;
@expansion{} [y3-z3+x2+x,-3y+2,0,xy,0,x6]
  v*(z+x);
@expansion{} [xy3+y3z+x3+x2z,2x+2z,0,x2y+xyz,0,x7+x6z]
@c end example vector_expressions types.doc:3877
@end smallexample

@c inserted refs from types.doc:3888
@ifinfo
@menu
See
* Type conversion and casting::
* ring::
@end menu
@end ifinfo
@iftex
See
@ref{Type conversion and casting};
@ref{ring}.
@end iftex
@c end inserted refs from types.doc:3888

@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{<>}
comparison of 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 reused example vector_operations types.doc:3918 
  ring R=0,(x,y),(c,dp);
  [x,y]-[1,x];
@expansion{} [x-1,-x+y]
  [1,2,x,4][3];
@expansion{} x
@c end example vector_operations types.doc:3918
@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 with degree smaller k+1 (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
