4 Data types
************



This chapter explains all data types of 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 SINGULAR refers to any comma separated
list of expressions.

For the general syntax of a declaration see General command syntax.

* def::
* ideal::
* int::
* intmat::
* intvec::
* link::
* list::
* map::
* matrix::
* module::
* number::
* poly::
* proc::
* qring::
* resolution::
* ring::
* string::
* vector::

4.1 def
=======

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

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 s which is just another reference (or name)
for the basering r.

  ring r=32003,(x,y,z),dp;
  poly f = x;
  def s=basering;
  setring s;
  nameof(basering);
==> s
  listvar();
==> // s                    [0]  *ring
==> //      f                    [0]  poly
==> // r                    [0]  ring
==> // LIB                  [0]  string standard.lib
  poly g = y;
  kill f;
  listvar(r);
==> // r                    [0]  ring
==> // g                    [0]  poly
  ring t=32003,(u,w),dp;
  def rt=r+t;
  rt;
==> //   characteristic : 32003
==> //   number of vars : 5
==> //        block   1 : ordering dp
==> //                  : names    x y z 
==> //        block   2 : ordering dp
==> //                  : names    u w 
==> //        block   3 : ordering C

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 setring or map).
setring r; does not work in this case, because
r may not be local to the procedure.

* def declarations::

4.1.1 def declarations
----------------------

Syntax:
def name = expression ;

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

Default:
none

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.

Example:
  def i=2;
  typeof(i);
==> int


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

Note: size counts only the non-zero generators of an ideal
whereas ncols counts all generators.
* ideal declarations::
* ideal expressions::
* ideal operations::
* ideal related functions::

4.2.1 ideal declarations
------------------------

Syntax:
ideal name = list_of_poly_and_ideal_expressions ;

ideal name = ideal_expression ;

Purpose:
defines an ideal.

Default:
0

Example:
  ring r=0,(x,y,z),dp;
  poly s1 = x2;
  poly s2 = y3;
  poly s3 = z;
  ideal i =  s1, s2-s1, 0,s2*s3, s3^4;
  i;
==> i[1]=x2
==> i[2]=y3-x2
==> i[3]=0
==> i[4]=y3z
==> i[5]=z4
  size(i);
==> 4
  ncols(i);
==> 5

4.2.2 ideal expressions
-----------------------

An ideal expression is:
1. an identifier of type ideal
2. a function returning ideal
3. ideal expressions combined by the arithmetic operations
+ or *
4. a power of an ideal expression (operator ^ or **)

Note that the computation of the product i*i involves
all products of generators of i while i^2 involves
only the different ones, and is therefore faster.
5. a type cast to ideal


Example:
  ring r=0,(x,y,z),dp;
  ideal m = maxideal(1);
  m;
==> m[1]=x
==> m[2]=y
==> 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;
==> 0
  ncols(i);
==> 505
  timer =0;
  i = M^2;
  ncols(i);
==> 505
  timer;
==> 0
  i[ncols(i)];
==> x20
  vector v = [x,y-z,x2,y-x,x2yz2-y];
  ideal j = ideal(v);

4.2.3 ideal operations
----------------------

+
addition (concatenation of the generators and simplification)

*
multiplication (with ideal, poly, vector, module; simplification in case of
multiplication with ideal)

^
exponentiation (by a non-negative integer)

ideal_expression [ intvec_expression ]
are polynomial generators of the ideal, index 1 gives the first generator.

Note: For simplification of an ideal, see also simplify.


Example:
  ring r=0,(x,y,z),dp;
  ideal I = 0,x,0,1;
  I;
==> I[1]=0
==> I[2]=x
==> I[3]=0
==> I[4]=1
  I + 0;    // simplification
==> _[1]=1
  ideal J = I,0,x,x-z;;
  J;
==> J[1]=0
==> J[2]=x
==> J[3]=0
==> J[4]=1
==> J[5]=0
==> J[6]=x
==> J[7]=x-z
  I * J;   //  multiplication with simplification
==> _[1]=1
  I*x;
==> _[1]=0
==> _[2]=x2
==> _[3]=0
==> _[4]=x
  vector V = [x,y,z];
  print(V*I);
==> 0,x2,0,x,
==> 0,xy,0,y,
==> 0,xz,0,z 
  ideal m = maxideal(1);
  m^2;
==> _[1]=x2
==> _[2]=xy
==> _[3]=xz
==> _[4]=y2
==> _[5]=yz
==> _[6]=z2
  ideal II = I[2..4];
  II;
==> II[1]=x
==> II[2]=0
==> II[3]=1

4.2.4 ideal related functions
-----------------------------

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

4.3 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 for), and
to represent boolean values
(FALSE is represented by 0, every other value means TRUE, see
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
number if possible.

* int declarations::
* int expressions::
* int operations::
* boolean expressions::
* boolean operations::
* int related functions::

4.3.1 int declarations
----------------------

Syntax:
int name = int_expression ;

Purpose:
defines an integer variable.

Default:
0

Example:
  int i = 42;
  int j = i + 3; j;
==> 45
  i = i * 3 - j; i;
==> 81
  int k;   // assigning the default value 0 to k
  k;
==> 0

4.3.2 int expressions
---------------------

An int expression is:
1. 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)
2. an identifier of type int
3. a function returning int
4. int expressions combined by the arithmetic operations
+, -, *, div, /,
% (mod), or ^
5. a boolean expression
6. a type cast to int

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


Example:
12345678901; // too large
==>    ? `12345678901` greater than 2147483647(max. integer representation)
==>    ? error occurred in line 1: `12345678901; // too large`
typeof(_);
==> none
ring r=0,x,dp;
12345678901;
==> 12345678901
typeof(_);
==> number
// Note: 11*13*17*100*200*2000*503*1111*222222
// returns a machine integer:
11*13*17*100*200*2000*503*1111*222222;
==> // ** int overflow(*), result may be wrong
==> // ** int overflow(*), result may be wrong
==> // ** int overflow(*), result may be wrong
==> // ** int overflow(*), result may be wrong
==> -1875651584
// using the type cast number for a greater allowed range
number(11)*13*17*100*200*2000*503*1111*222222;
==> 12075748128684240000000
ring rp=32003,x,dp;
12345678901;
==> 9603
typeof(_);
==> number
intmat m[2][2] = 1,2,3,4;
m;
==> 1,2,
==> 3,4 
m[2,2];
==> 4
typeof(_);
==> int
det(m);
==> -2
m[1,1] + m[2,1] == trace(m);
==> 0
! 0;
==> 1
1 and 2;
==> 1
intvec v = 1,2,3;
def d =transpose(v)*v;    // scalarproduct gives an 1x1 intvec
typeof(d);
==> 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;
==> 6


4.3.3 int operations
--------------------

++
changes its operand to its successor, is itself no int expression
--
changes its operand to its predecessor, is itself no int expression
+
addition
-
negation or subtraction
*
multiplication
/
integer division (omitting the remainder), rounding toward 0
div
integer division (omitting the remainder >= 0)
%
integer modulo (the remainder of the division /)
mod
integer modulo (the remainder of the division div), always non-negative
^, **
exponentiation (exponent must be non-negative)
<, >, <=, >=, ==, <>
comparison

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



Example:
  int i=1;
  int j;
  i++; i;  i--; i;
==> 2
==> 1
  // ++ and -- do not return a value as in C, can not assign
  j = i++;
==> // ** right side is not a datum, assignment ignored
  // the value of j is unchanged
  j; i;
==> 0
==> 2
  i+2, 2-i, 5^2;
==> 4 0 25
  5 div 2, 8%3;
==> 2 2
  -5 div 2, -5 / 2, -5 mod 2, -5 % 2;
==> -3 -2 1 -1
  1<2, 2<=2;
==> 1 1

4.3.4 int related functions
---------------------------

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

4.3.5 boolean expressions
-------------------------

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


An int expression (<> 0 evaluates to TRUE (represented by 1),
0 represents FALSE).

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

Note: There are no comparisons for ideals and modules, resolution
and maps.

1. an integer comparison:
  i == j
  i != j    // or     i <> j
  i <= j
  i >= j
  i > j
  i < j
2. a number comparison:
  m == n
  m != n    // or     m <> n
  m < n
  m > n
  m <= n
  m >= n
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
(>=,<=) yield always TRUE (1) and
the < and > are equivalent to !=.
3. a polynomial or vector comparison:
  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
4. an intmat or matrix comparison:
  v == w
  v != w    // or     v <> w
5. an intvec or  string comparison:
  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
6. boolean expressions combined by boolean operations (and,
or, not)

Note:
All arguments of a logical expression are first evaluated and
then the value of the logical expression is determined. For example, the
logical expression (a || b) is evaluated by first evaluating
a and b, even though the value of b has no
influence on the value of (a || b), if 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 (1
|| b) is determined without ever evaluating b.

See Major differences to the C programming language.

4.3.6 boolean operations
------------------------

and
logical and, may also be written as &&

or
logical or, may also be written as ||

not
logical not, may also be written as !

The precedence of the boolean operations is:

1. parentheses
2. comparisons
3. not
4. and
5. or


Example:
  (1>2) and 3;
==> 0
  1 > 2 and 3;
==> 0
  ! 0 or 1;
==> 1
  !(0 or 1);
==> 0

4.4 intmat
==========

Integer matrices are matrices with integer entries. For the range of
integers see 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 1, for example, is converted into the unit
matrix.

* intmat declarations::
* intmat expressions::
* intmat type cast::
* intmat operations::
* intmat related functions::

4.4.1 intmat declarations
-------------------------

Syntax:
intmat name = intmat_expression ;

intmat name [ rows ] [ cols ] = intmat_expression ;

intmat name [ rows ] [ cols ] = list_of_int_and_intvec_and_intmat_expressions ;

rows and cols must be positive int expressions.

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.

Default:
0 (1 x 1 matrix)

Example:
  intmat im[3][5]=1,3,5,7,8,9,10,11,12,13;
  im;
==> 1,3,5,7,8,
==> 9,10,11,12,13,
==> 0,0,0,0,0 
  im[3,2];
==> 0
  intmat m[2][3] = im[1..2,3..5];  // defines a submatrix
  m;
==> 5,7,8,
==> 11,12,13 

4.4.2 intmat expressions
------------------------

An intmat expression is:
1. an identifier of type intmat
2. a function returning intmat
3. intmat operations with int (+, -, *, div, %)
4. intmat operations (+, -, *)
5. a type cast to intmat (see intmat type cast)


Example:
  intmat Idm[2][2];
  Idm +1;          // add the unit intmat
==> 1,0,
==> 0,1 
  intmat m1[3][2] = _,1,-2;  // take entries from the last result
  m1;
==> 1,0,
==> 0,1,
==> 1,-2 
  intmat m2[2][3]=1,0,2,4,5,1;
  transpose(m2);
==> 1,4,
==> 0,5,
==> 2,1 
  intvec v1=1,2,4;
  intvec v2=5,7,8;
  m1=v1,v2;         // fill m1 with v1 and v2
  m1;
==> 1,2,
==> 4,5,
==> 7,8 
  trace(m1*m2);
==> 56

4.4.3 intmat type cast
----------------------
Syntax:
intmat ( expression )

intmat ( expression, int_n, int_m  )
Type:
intmat
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.
Example:
  intmat(intvec(1));
==> 1 
  intmat(intvec(1), 1, 2);
==> 1,0 
  intmat(intvec(1,2,3,4), 2, 2);
==> 1,2,
==> 3,4 
  intmat(_, 2, 3);
==> 1,2,3,
==> 4,0,0 
  intmat(_, 2, 1);
==> 1,
==> 2 
4.4.4 intmat operations
-----------------------

+
addition with intmat or int; the int is converted into a diagonal intmat

-
negation or subtraction with intmat or int; the int is converted into a
diagonal intmat

*
multiplication with intmat, intvec, or int; the int is converted into a
diagonal intmat

div,/
division of entries in the integers (omitting the remainder)
%, mod
entries modulo int (remainder of the division)
<>, ==
comparison

intmat_expression [ intvec_expression, intvec_expression ]
is an intmat entry, where the first index indicates the row and the
second the column


Example:
  intmat m[2][4] = 1,0,2,4,0,1,-1,0,3,2,1,-2;
  m;
==> 1,0,2,4,
==> 0,1,-1,0 
  m[2,3];          // entry at row 2, col 3
==> -1
  size(m);         // number of entries
==> 8
  intvec v = 1,0,-1,2;
  m * v;
==> 7,1
  typeof(_);
==> intvec
  intmat m1[4][3] = 0,1,2,3,v,1;
  intmat m2 = m * m1;
  m2;             //  2 x 3 intmat
==> -2,5,4,
==> 4,-1,-1 
  m2*10;           // multiply each entry of m with 10;
==> -20,50,40,
==> 40,-10,-10 
  -m2;
==> 2,-5,-4,
==> -4,1,1 
  m2 % 2;
==> 0,1,0,
==> 0,1,1 
  m2 div 2;
==> -1,2,2,
==> 2,-1,-1 
  m2[2,1];          // entry at row 2, col 1
==> 4
  m1[2..3,2..3];   // submatrix
==> 1 0 2 1
  m2[nrows(m2),ncols(m2)];      // the last entry of intmat m2
==> -1

4.4.5 intmat related functions
------------------------------

betti
Betti numbers of a free resolution (see betti)
det
determinant (see det)
ncols
number of cols (see ncols)
nrows
number of rows (see nrows)
random
create a pseudo random intmat (see random)
size
total number of entries (see size)
transpose
transpose of an intmat (see transpose)
trace
trace of an intmat (see trace)

4.5 intvec
==========

Variables of type intvec are lists of integers.  For the range of
integers see 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.

* intvec declarations::
* intvec expressions::
* intvec operations::
* intvec related functions::

4.5.1 intvec declarations
-------------------------

Syntax:
intvec name = intvec_expression ;

intvec name = list_of_int_and_intvec_expressions ;

Purpose:
defines an intvec variable.

 An intvec consists of an ordered list of integers.

Default:
0

Example:
  intvec iv=1,3,5,7,8;
  iv;
==> 1,3,5,7,8
  iv[4];
==> 7
  iv[3..size (iv)];
==> 5 7 8

4.5.2 intvec expressions
------------------------

An intvec expression is:
1. a range: int expression .. int expression
2. a function returning intvec
3. intvec operations with int (+, -, *, /, %)
4. intvec operations (+, -)
5. intvec operation with intmat (*)
6. a type cast to intvec


Example:
  intvec v=-1,2;
  intvec w=v,v;         // concatenation
  w;
==> -1,2,-1,2
  w = -2..2,v,1;
  w;
==> -2,-1,0,1,2,-1,2,1
  intmat m[3][2] = 0,1,2,-2,3,1;
  m*v;
==> 2,-6,-1
  typeof(_);
==> intvec
  v = intvec(m);
  v;
==> 0,1,2,-2,3,1
  ring r;
  poly f = x2z + 2xy-z;
  f;
==> x2z+2xy-z
  v = leadexp(f);
  v;
==> 2,0,1

4.5.3 intvec operations
-----------------------

+
addition with intvec or int (component-wise)

-
negation or subtraction with intvec or int (component-wise)

*
multiplication with int (component-wise)

/, div
division by int (component-wise)

%, mod
modulo (component-wise)

<>, ==, <=, >=, >, <
comparison (done lexicographically)

intvec_expression [ int_expression ]
is an element of the intvec; the first element has index one.


Example:
  intvec iv =  1,3,5,7,8;
  iv+1;               // add 1 to each entry
==> 2,4,6,8,9
  iv*2;
==> 2,6,10,14,16
  iv;
==> 1,3,5,7,8
  iv-10;
==> -9,-7,-5,-3,-2
  iv=iv,0;
  iv;
==> 1,3,5,7,8,0
  iv div 2;
==> 0,1,2,3,4,0
  iv+iv;              // component-wise addition
==> 2,6,10,14,16,0
  iv[size(iv)-1];     // last-1 entry
==> 8
  intvec iw=2,3,4,0;
  iv==iw;             // lexicographic comparison
==> 0
  iv < iw;
==> 1
  iv != iw;
==> 1
  iv[2];
==> 3
  iw = 4,1,2;
  iv[iw];
==> 7 1 3

4.5.4 intvec related functions
------------------------------

hilb
returns Hilbert series as intvec (see hilb)
indepSet
sets of independent variables of an ideal (see indepSet)
leadexp
the exponent vector of the leading monomial (see leadexp)
nrows
number of rows (see nrows)
qhweight
returns quasihomogeneous weights (see qhweight)
size
length of the intvec (see size)
sortvec
permutation for sorting ideals/modules (see sortvec)
transpose
transpose of an intvec, returns an intmat (see transpose)
weight
returns weights for the weighted ecart method (see weight)

4.6 link
========

Links are the communication channels of SINGULAR, i.e.,
something SINGULAR can write to and/or read from. Currently,
SINGULAR supports four different link types:
* ASCII links (see
ASCII links)

* MPfile links (see
MPfile links)

* MPtcp links (see
MPtcp links)

* DBM links (see
DBM links)

* link declarations::
* link expressions::
* link related functions::
* ASCII links::
* MP links::
* DBM links::

4.6.1 link declarations
-----------------------

Syntax:
link name = string_expression ;

Purpose:
defines a new communication link.

Default:
none

Example:
  link l=":w example.txt";
  int i=22;          // cf. ASCII links for explanation
  string s="An int follows:";
  write(l,s,i);
  l;
==> // type : ASCII
==> // mode : w
==> // name : example.txt
==> // open : yes
==> // read : not ready
==> // write: ready
  close(l);          //
  read(l);
==> An int follows:
==> 22
==> 
  close(l);

4.6.2 link expressions
----------------------

A link expression is:
1. an identifier of type link
2. a string describing the link

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 (ASCII, MPfile, MPtcp or 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:

* ASCII links::
* MPfile links::
* MPtcp links::
* DBM links::

4.6.3 link related functions
----------------------------

close
closes a link (see close)
dump
generates a dump of all variables and their values (see dump)
getdump
reads a dump (see getdump)
open
opens a link (see open)
read
reads from a link (see read)
status
gets the status of a link (see status)
write
writes to a link (see write)
kill
closes and kills a link (see kill)

4.6.4 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 short (see 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 execute
(see execute).

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

1. "ASCII: " + filename

the mode (read or append) is set by the first read or
write command.
2. "ASCII:r " + filename

opens the file for reading.
3. "ASCII:w " + filename

opens the file for overwriting.
4. "ASCII:a " + filename

opens the file for appending.

There are the following default values:
* the type ASCII may be omitted since ASCII links are the
default links.

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

* if the filename is omitted, read reads from stdin and
write writes to stdout.

Using these default rules, the string ":r temp" describes a link
which is equivalent to the link "ASCII:r temp": an ASCII link to
the file temp which is opened for reading. The string
"temp" describes an ASCII link to the file temp, where the
mode is set by the first read or 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 // (as in //c/temp/ex. An ASCII
link can be used either for reading or for writing, but not for both at
the same time. A close command must be used before a change of
I/O direction. Types without a conversion to string cannot be
written.


Example:
  ring r=32003,(x,y,z),dp;
  link l=":w example.txt";     // type is ASCII, mode is overwrite
  l;
==> // type : ASCII
==> // mode : w
==> // name : example.txt
==> // open : no
==> // read : not ready
==> // write: not ready
  status(l, "open", "yes");    // link is not yet opened
==> 0
  ideal i=x2,y2,z2;
  write (l,1,";",2,";","ideal i=",i,";");
  status(l, "open", "yes");    // now link is open
==> 1
  status(l, "mode");           // for writing
==> 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
==> 1
==> ;
==> 2
==> ;
==> ideal i=
==> x2,y2,z2
==> ;
==> int j=5;
==> 
  execute(read(l));            // read string is executed
==> 1
==> 2
==> // ** redefining i **
  close(l);                    // link is closed

4.6.5 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 MPfile) or using TCP sockets (link type is
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 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
http://symbolicnet.mcs.kent.edu/areas/mp.html.

* MPfile links::
* MPtcp links::

4.6.5.1 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:

1. "MPfile: " + filename

the mode (read or append) is set by the first read or
write command.
2. "MPfile:r " + filename

opens the file for reading.
3. "MPfile:w " + filename

opens the file for overwriting.
4. "MPfile:a " + filename

opens the file for appending.

There are the following default values:
* if none of r, w, or a is specified, the mode of
the link is set by the first read or write command on the
link. If the first command is write, the mode is set to a
(append mode).

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
close command must be used before a change of I/O direction.


Example:
  ring r;
  link l="MPfile:w example.mp"; // type=MPfile, mode=overwrite
  l;
==> // type : MPfile
==> // mode : w
==> // name : example.mp
==> // open : no
==> // read : not ready
==> // 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
==> 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);
==> // mpsr_r0              [0]  *ring
  def s = read(l);              // third expression
  listvar();
==> // s                    [0]  string hello world
==> // mpsr_r0              [0]  *ring
==> //      i                    [0]  ideal, 3 generator(s)
==> // l                    [0]  link
==> // 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
==> // mpsr_r0              [0]  *ring
==> //      i                    [0]  ideal, 3 generator(s)
==> // s                    [0]  string hello world
==> // l                    [0]  link
==> // LIB                  [0]  string standard.lib

4.6.5.2 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:

listen
SINGULAR acts as a server.

connect
SINGULAR acts as a client.

launch
SINGULAR acts as a client, launching an application as server.

fork
SINGULAR acts as a client, forking another SINGULAR as
server.

The MPtcp link describing string has to be
* listen mode:
1. "MPtcp:listen --MPport " + portnumber
SINGULAR becomes a server and waits at the port for a
connect call.
* connect mode:
2. "MPtcp:connect --MPport " + portnumber
3. "MPtcp:connect --MPhost " + hostname + " --MPport " +
portnumber
SINGULAR becomes a client and connects to a server waiting at
the host and port.
* launch mode:
4. "MPtcp:launch"
5. "MPtcp:launch --MPrsh " + rsh
6. "MPtcp:launch --MPrsh " + rsh  + " --MPhost " +
hostname
7. "MPtcp:launch --MPrsh " + rsh  + " --MPhost " +
hostname + " --MPapplication " + application
SINGULAR becomes a client and starts (launches) the application
using the specified remote shell command (default is
ssh) on a (possibly) different host (default is localhost
which then acts as a server.
* fork mode:
8. "MPtcp:fork"
SINGULAR becomes a client and forks another SINGULAR on the
same host which acts as a server.

There are the following default values:
* if none of listen, connect, launch or
fork is specified, the default mode is set to fork.

* if no remote shell (rsh) command is specified, then the command
ssh is used.

* if no application is specified (in mode launch) the default
application is the value of system("Singular") + "-bq".
(This evaluates to the absolute path of the SINGULAR currently running
with the option "-bq" appended.)

* if no hostname is specified the local host is used as default host.

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 SINGULAR that actually opened the link acts as a
client. SINGULAR automatically appends the command line arguments
"--MPmode connect --MPhost hostname --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 SINGULAR is used as server
application it has to be started with the command line option -b.
Since launching is done using a remote shell command, the host on which
the application should run must have an entry in the .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
SINGULAR is forked. All variables and their values are inherited by
the child. The child acts as a server whereas the 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 quote (see 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 SINGULAR is in server mode, the value of the variable
mp_ll is the MPtcp link connecting to the client and
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 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 status command can be used to check whether there
is data to read.


Example:
  LIB "general.lib"; // needed for "killall" command
  link l="MPtcp:launch";
  open(l); l;        // l is ready for writing but not for reading
==> // type : MPtcp
==> // mode : launch
==> // name : 
==> // open : yes
==> // read : not ready
==> // 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
==> j[1]=z
==> j[2]=y2-y
==> 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
==> // ** 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()"
==> // mpsr_r0              [0]  ring
==> // r                    [0]  *ring
==> //      j                    [0]  ideal, 3 generator(s)
==> //      i                    [0]  ideal, 3 generator(s)
==> // l                    [0]  link

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

  write(l, quote(status(mp_ll, "name")));
  read(l);           // and name of forked link is "child"
==> child
  write(l,quote(i)); // Child inherited vars and their values
  read(l);
==> _[1]=x2+y
==> _[2]=xyz+z
==> _[3]=x2+y2
  close(l);          // shut down forked child

4.6.6 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
write(link, key_string, value_string).  By
calling write(link, key_string), the entry with key
key_string is deleted from the data base. The value of an entry is
returned by the command read(link,
key_string). With only one argument, read(link)
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 name is opened for writing for the first
time, two files (name.pag and name.dir), which contain the
data base, are automatically created.

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

1. "DBM: " + name

opens the data base for reading (default mode).

2. "DBM:r " + name

opens the data base for reading.

3. "DBM:rw " + name

opens the data base for reading and writing.

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


Example:
  link l="DBM:rw example";
  write(l,"1","abc");
  write(l,"3","XYZ");
  write(l,"2","ABC");
  l;
==> // type : DBM
==> // mode : rw
==> // name : example
==> // open : yes
==> // read : ready
==> // write: ready
  close(l);
  // read all keys (till empty string):
  read(l);
==> 1
  read(l);
==> 3
  read(l);
==> 2
  read(l);
==> 
  // read data corresponding to key "1"
  read(l,"1");
==> abc
  // read all data:
  read(l,read(l));
==> abc
  read(l,read(l));
==> XYZ
  read(l,read(l));
==> ABC
  // close
  close(l);

4.7 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 #. The expression
list() is the empty list.

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

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

* list declarations::
* list expressions::
* list operations::
* list related functions::

4.7.1 list declarations
-----------------------

Syntax:
list name = expression_list;

list name = list_expression;

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

Default:
empty list

Example:
  list l=1,"str";
  l[1];
==> 1
  l[2];
==> str
  ring r;
  listvar(r);
==> // r                    [0]  *ring
  ideal i = x^2, y^2 + z^3;
  l[3] = i;
  l;
==> [1]:
==>    1
==> [2]:
==>    str
==> [3]:
==>    _[1]=x2
==>    _[2]=z3+y2
  listvar(r);     // the list l belongs now to the ring r
==> // r                    [0]  *ring
==> // l                    [0]  list, size: 3
==> // i                    [0]  ideal, 2 generator(s)

4.7.2 list expressions
----------------------

A list expression is:
1. the empty list list()
2. an identifier of type list
3. a function returning list
4. list expressions combined by the arithmetic operation +
5. a type cast to list



Example:
  list l = "hello",1;
  l;
==> [1]:
==>    hello
==> [2]:
==>    1
  l = list();
  l;
==> empty list
  ring r =0,x,dp;
  factorize((x+1)^2);
==> [1]:
==>    _[1]=1
==>    _[2]=x+1
==> [2]:
==>    1,2
  list(1,2,3);
==> [1]:
==>    1
==> [2]:
==>    2
==> [3]:
==>    3

4.7.3 list operations
---------------------

+
concatenation
delete
deletes one element from list, returns new list
insert
inserts or appends a new element to list, returns a new list
list_expression [ int_expression ]
is a list entry; the index 1 gives the first element.


Example:
  list l1 = 1,"hello",list(-1,1);
  list l2 = list(1,2,3);
  l1 + l2;          // one new list
==> [1]:
==>    1
==> [2]:
==>    hello
==> [3]:
==>    [1]:
==>       -1
==>    [2]:
==>       1
==> [4]:
==>    1
==> [5]:
==>    2
==> [6]:
==>    3
  list l3 =_;
  l1,l2;            // two lists
==> [1]:
==>    1
==> [2]:
==>    hello
==> [3]:
==>    [1]:
==>       -1
==>    [2]:
==>       1
==> [1]:
==>    1
==> [2]:
==>    2
==> [3]:
==>    3
  l2[2];
==> 2

4.7.4 list related functions
----------------------------

bareiss
returns a list of a matrix (lower triangular) and
of an intvec (permutations of columns, see bareiss)
betti
Betti numbers of a resolution (see betti)
delete
deletes an element from a list (see delete)
facstd
factorizing Groebner basis algorithm (see facstd)
factorize
list of factors of a polynomial (see factorize)
insert
inserts or appends a new element to a list (see insert)
lres
free resolution (see lres)
minres
minimize a free resolution (see minres)
mres
minimal free resolution of an ideal, resp. module w.r.t.
a minimal set of generators of the first module (see mres)
names
list of all user-defined variable names (see names)
res
free resolution of an ideal, resp. module (see res)
size
number of entries (see size)
sres
free resolution of an ideal, resp. module, given by a standard base (see sres)


4.8 map
=======

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

Note:
* the target of a map is ALWAYS the actual basering
* 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 Identifier resolution, Names in procedures.

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

Canonically realized are
* 
* 
* 
* 
* 
* 
* 
Possible are furthermore
* * * 
Finally, in Singular we allow the mapping from rings
with coefficient field Q to rings whose ground fields
have finite characteristic:

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


* map declarations::
* map expressions::
* map operations::
* fetch::
* imap::
* subst::

4.8.1 map declarations
----------------------

Syntax:
map name = preimage_ring_name , ideal_expression ;

map name = preimage_ring_name , list_of_poly_and_ideal_expressions ;

map name = map_expression ;

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

Default:
none

Note:
There are standard mappings for maps which are close to the identity
map: fetch and 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).

Example:
  ring r1=32003,(x,y,z),dp;
  ideal i=x,y,z;
  ring r2=32003,(a,b),dp;
  map f=r1,a,b,a+b;
  // maps from r1 to r2,
  // x -> a
  // y -> b
  // z -> a+b
  f(i);
==> _[1]=a
==> _[2]=b
==> _[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);
==> _[1]=a2
==> _[2]=b2
==> _[3]=a2+b2


4.8.2 map expressions
---------------------

A map expression is:
1. an identifier of type map
2. a function returning map
3. map expressions combined by composition using parentheses ((, ))

4.8.3 map operations
--------------------


( )
composition of maps. If, for example, f and g are maps,
then f(g) is a map expression giving the composition of f
and g.

map_expression [ int_expressions ]
is a map entry (the image of the corresponding variable)


Example:
  ring r=0,(x,y),dp;
  map f=r,y,x;    // the map f permutes the variables
  f;
==> f[1]=y
==> f[2]=x
  poly p=x+2y3;
  f(p);
==> 2x3+y
  map g=f(f);    // the map g defined as  f^2 is the identity
  g;
==> g[1]=x
==> g[2]=y
  g(p) == p;
==> 1

4.9 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 module M=A; or 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.

* matrix declarations::
* matrix expressions::
* matrix type cast::
* matrix operations::
* matrix related functions::

4.9.1 matrix declarations
-------------------------

Syntax:
matrix name[rows][cols] = list_of_poly_expressions ;

matrix name = matrix_expression ;

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.

Default:
0 (1 x 1 matrix)

Example:
  int ro = 3;
  ring r = 32003,(x,y,z),dp;
  poly f=xyz;
  poly g=z*f;
  ideal i=f,g,g^2;
  matrix m[ro][3] = x3y4, 0, i, f ; // a 3 x 3 matrix
  m;
==> m[1,1]=x3y4
==> m[1,2]=0
==> m[1,3]=xyz
==> m[2,1]=xyz2
==> m[2,2]=x2y2z4
==> m[2,3]=xyz
==> m[3,1]=0
==> m[3,2]=0
==> m[3,3]=0
  print(m);
==> x3y4,0,     xyz,
==> xyz2,x2y2z4,xyz,
==> 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);
==> 0,     xyz,
==> x2y2z4,xyz 
  matrix C=m; // defines C as a 3 x 3 matrix equal to m
  print(C);
==> x3y4,0,     xyz,
==> xyz2,x2y2z4,xyz,
==> 0,   0,     0   

4.9.2 matrix expressions
------------------------

A matrix expression is:
1. an identifier of type matrix
2. a function returning matrix
3. matrix expressions combined by the arithmetic operations
+, - or *
4. a type cast to matrix (see matrix type cast)


Example:
  ring r=0,(x,y),dp;
  poly f= x3y2 + 2x2y2 +2;
  matrix H = jacob(jacob(f));    // the Hessian of f
  matrix mc = coef(f,y);
  print(mc);
==> y2,    1,
==> x3+2x2,2 
  module MD = [x+y,1,x],[x+y,0,y];
  matrix M = MD;
  print(M);
==> x+y,x+y,
==> 1,  0,  
==> x,  y   

4.9.3 matrix type cast
----------------------
Syntax:
matrix ( expression )

matrix ( expression, int_n, int_m  )
Type:
matrix
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.
Example:
  ring r=32003,(x,y,z),dp;
  matrix(x);
==> _[1,1]=x
  matrix(x, 1, 2);
==> _[1,1]=x
==> _[1,2]=0
  matrix(intmat(intvec(1,2,3,4), 2, 2));
==> _[1,1]=1
==> _[1,2]=2
==> _[2,1]=3
==> _[2,2]=4
  matrix(_, 2, 3);
==> _[1,1]=1
==> _[1,2]=2
==> _[1,3]=0
==> _[2,1]=3
==> _[2,2]=4
==> _[2,3]=0
  matrix(_, 2, 1);
==> _[1,1]=1
==> _[2,1]=3
4.9.4 matrix operations
-----------------------

+
addition with matrix or poly; the poly is converted into a diagonal
matrix

-
negation or subtraction with matrix or poly; the poly is converted into
a diagonal matrix

*
multiplication with matrix or poly; the poly is converted into a
diagonal matrix

/
division by poly

==, <>, !=
comparison

matrix_expression [ int_expression, int_expression ]
is a matrix entry, where the first index indicates the row and the
second the column


Example:
  ring r=32003,x,dp;
  matrix A[3][3] = 1,3,2,5,0,3,2,4,5; // define a matrix
  print(A); // nice printing of small matrices
==> 1,3,2,
==> 5,0,3,
==> 2,4,5 
  A[2,3];   // matrix entry
==> 3
  A[2,3] = A[2,3] + 1; // change entry
  A[2,1..3] = 1,2,3;   // change 2nd row
  print(A);
==> 1,3,2,
==> 1,2,3,
==> 2,4,5 
  matrix E[3][3]; E = E + 1;  // the unit matrix
  matrix B =x*E - A;
  print(B);
==> x-1,-3, -2,
==> -1, x-2,-3,
==> -2, -4, x-5
  det(B);        // the characteristic polynomial of A
==> x3-8x2-2x-1
  A*A*A - 8 * A*A - 2*A == E;  // Cayley-Hamilton
==> 1
  vector v =[x,-1,x2];
  A*v; // multiplication of matrix and vector
==> _[1,1]=2x2+x-3
==> _[2,1]=3x2+x-2
==> _[3,1]=5x2+2x-4
  matrix m[2][2]=1,2,3;
  print(m-transpose(m));
==> 0,-1,
==> 1,0  

4.9.5 matrix related functions
------------------------------

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

See also the library matrix_lib, which contains more
matrix-related functions.


4.10 module
===========

Modules are submodules of a free module over the basering with basis
gen(1), gen(2), ... .
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 
 is a submodule of

 the basering, generated by vectors
may be considered as the generators of relations of
between the canonical generators gen(1),...,gen(n).
Hence any finitely generated 
-module can be represented in SINGULAR
by its module of relations. The assignments
module M=v1,...,vk; matrix A=M;
create the presentation matrix of size
 for
i.e., the columns of A are the vectors
which generate M (cf. Representation of mathematical objects).

* module declarations::
* module expressions::
* module operations::
* module related functions::

4.10.1 module declarations
--------------------------

Syntax:
module name = list_of_vector_expressions ;

module name = module_expression ;

Purpose:
defines a module.

Default:
[0]

Example:
  ring r=0,(x,y,z),(c,dp);
  vector s1 = [x2,y3,z];
  vector s2 = [xy,1,0];
  vector s3 = [0,x2-y2,z];
  poly   f  = xyz;
  module m = s1, s2-s1,f*(s3-s1);
  m;
==> m[1]=[x2,y3,z]
==> m[2]=[-x2+xy,-y3+1,-z]
==> m[3]=[-x3yz,-xy4z+x3yz-xy3z]
  // show m in matrix format (columns generate m)
  print(m);
==> x2,-x2+xy,-x3yz,          
==> y3,-y3+1, -xy4z+x3yz-xy3z,
==> z, -z,    0               

4.10.2 module expressions
-------------------------

A module expression is:
1. an identifier of type module
2. a function returning module
3. module expressions combined by the arithmetic operation +
4. multiplication of a module expression with an ideal or a poly expression: *
5. a type cast to module



4.10.3 module operations
------------------------

+
addition (concatenation of the generators and simplification)

*
multiplication with ideal or poly, but not `module` * `module`

module_expression [ int_expression , int_expression ]
is a module entry, where the first index indicates the row and
the second the column

module_expressions [ int_expression ]
is a vector, where the index indicates the column


Example:
  ring r=0,(x,y,z),dp;
  module m=[x,y],[0,0,z];
  print(m*(x+y));
==> x2+xy,0,   
==> xy+y2,0,   
==> 0,    xz+yz

4.10.4 module related functions
-------------------------------

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


4.11 number
===========

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 ring declarations for
declarations of coefficient fields.

Warning: Beware of the special meaning of the letter e
(immediately following a sequence of digits) if the field is real (or complex).
See number operations, Miscellaneous oddities.

* number declarations::
* number expressions::
* number operations::
* number related functions::

4.11.1 number declarations
--------------------------

Syntax:
number name = number_expression ;

Purpose:
defines a number.

Default:
0

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 Rings and orderings for a list of the available coefficient fields.

Example:
  // finite field Z/p, p<= 32003
  ring r = 32003,(x,y,z),dp;
  number n = 4/6;
  n;
==> -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;
==> z11
  // the rational numbers
  ring r0 = 0,x,dp;
  number n = 4/6;
  n;
==> 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;
==> (a-2)
  a^2;
==> -1
  // transcedental extensions of Z/p or Q
  ring rt=(0,a),x,dp;
  number n=a3+a2+2a-1;
  n;
==> (a3+a2+2a-1)
  a^2;
==> (a2)
  // machine floating point numbers, single precision
  ring R_0=real,x,dp;
  number n=4/6;
  n;
==> 6.667e-01
  n=0.25e+2;
  n;
==> 2.500e+01
  // floating point numbers, arbitrary prescribed precision
  ring R_1=(real,50),x,dp;
  number n=4.0/6;
  n;
==> 0.66666666666666666666666666666666666666666666666667
  n=0.25e+2;
  n;
==> 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;
==> 0.66666666666666666666666666666666666666666666666667
  n=0.25e+2*i+n;
  n;
==> (0.66666666666666666666666666666666666666666666666667+i*25)

4.11.2 number expressions
-------------------------

A number expression is:
1. a rational number (there are NO spaces allowed inside a rational number,
see int expressions)
2. a floating point number (if the coefficient field is real):

<digits>.<digits>e<sign><digits>
3. an identifier of type number
4. a function returning number
5. an int expression (see Type conversion and casting)
6. number expressions combined by the arithmetic operations
+, -, *, /, ^, or **.
7. a type cast to number


Example:
  // the following expressions are in any ring int expressions
  2 / 3;
==> 0
  4/ 8;
==> 0
  2 /2;   // the notation of / for div might change in the future
==> 1
  ring r0=0,x,dp;
  2/3, 4/8, 2/2 ; // are numbers
==> 2/3 1/2 1

  poly f = 2x2 +1;
  leadcoef(f);
==> 2
  typeof(_);
==> number
  ring rr =real,x,dp;
  1.7e-2; 1.7e+2; // are valid (but  1.7e2 not), if the field is `real`
==> 1.700e-02
==> 1.700e+02
  ring rp = (31,t),x,dp;
  2/3, 4/8, 2/2 ; // are numbers
==> 11 -15 1
  poly g = (3t2 +1)*x2 +1;
  leadcoef(g);
==> (3t2+1)
  typeof(_);
==> number
  par(1);
==> (t)
  typeof(_);
==> number

4.11.3 number operations
------------------------

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

Note: quotient and exponentiation is only recognized as a
number expression if it is already a number, see Miscellaneous oddities.

 For the behavior of comparison operators in rings with
ground field different from real or the rational numbers, see boolean expressions.


Example:
  ring r=0,x,dp;
  number n = 1/2 +1/3;
  n;
==> 5/6
  n/2;
==> 5/12
  1/2/3;
==> 1/6
  1/2 * 1/3;
==> 1/6
  n = 2;
  n^-2;
==> 1/4
  // the following oddities appear here
  2/(2+3);
==> 0
  number(2)/(2+3);
==> 2/5
  2^-2; // for int's exponent must be non-negative
==>    ? exponent must be non-negative
==>    ? error occurred in line 12: `  2^-2; // for int's exponent must be no\
   n-negative`
  number(2)^-2;
==> 1/4
  3/4>=2/5;
==> 1
  2/6==1/3;
==> 1

4.11.4 number related functions
-------------------------------

cleardenom
cancel denominators of numbers in poly and divide it by its content
(see cleardenom)
impart
imaginary part of a complex number, 0 otherwise
(see impart, repart)
numerator, denominator
return the numerator/denominator of a rational number
(see numerator, denominator)
leadcoef
coefficient of the leading term (see leadcoef)
par
n-th parameter of the basering (see par)
pardeg
degree of a number in ring parameters (see pardeg)
parstr
string form of ring parameters (see parstr)
repart
real part of a complex number
(see impart, repart)


4.12 poly
=========

Polynomials are the basic data for all main algorithms in
SINGULAR. They consist of finitely many terms
(coefficient*power product) which are combined by the usual polynomial
operations (see 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.

  ring r=32003,(x,y,z),dp;
  poly f=x3+y5+z2;

* poly declarations::
* poly expressions::
* poly operations::
* poly related functions::

4.12.1 poly declarations
------------------------

Syntax:
poly name = poly_expression ;

Purpose:
defines a polynomial.

Default:
0

Example:
  ring r = 32003,(x,y,z),dp;
  poly s1  = x3y2+151x5y+186xy6+169y9;
  poly s2  = 1*x^2*y^2*z^2+3z8;
  poly s3  = 5/4x4y2+4/5*x*y^5+2x2y2z3+y7+11x10;
  int a,b,c,t=37,5,4,1;
  poly f=3*x^a+x*y^(b+c)+t*x^a*y^b*z^c;
  f;
==> x37y5z4+3x37+xy9
  short = 0;
  f;
==> x^37*y^5*z^4+3*x^37+x*y^9
4.12.2 poly expressions
-----------------------

A poly expression is (optional parts in square brackets):
1. a monomial (there are NO spaces allowed inside a monomial)
  [coefficient] ring_variable [ exponent] [ring_variable [exponent] ...]
monomials which contain an indexed ring variable
must be built from ring_variable and coefficient
with the operations * and ^
2. an identifier of type poly
3. a function returning poly
4. poly expressions combined by the arithmetic operations
+, -, *, /, or ^
5. an int expression (see Type conversion and casting)
6. a type cast to poly


Example:
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
  ring r=0,(x,y),dp;
  poly f = 10x2y3 +2x2y2-2xy+y -x+2;
  lead(f);
==> 10x2y3
  leadmonom(f);
==> x2y3
  simplify(f,1);     // normalize leading coefficient
==> x2y3+1/5x2y2-1/5xy-1/10x+1/10y+1/5
  poly g = 1/2x2 + 1/3y;
  cleardenom(g);
==> 3x2+2y
  int i = 102;
  poly(i);
==> 102
  typeof(_);
==> poly


4.12.3 poly operations
----------------------

+
addition

-
negation or subtraction

*
multiplication

/
division by a polynomial, ignoring the rest

^, **
power by an integer

<, <=, >, >=, ==, <>
comparison (w.r.t. monomial ordering)

poly_expression [ intvec_expression ]
the monomial at the indicated place w.r.t. the monomial ordering


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

4.12.4 poly related functions
-----------------------------

cleardenom
cancel denominators of numbers in poly and divide it by its content
(see cleardenom)
coef
matrix of coefficients and monomials (see coef)
coeffs
matrix of coefficients (see coeffs)
deg
degree (see deg)
det
determinant (see det)
diff
partial derivative (see diff)
extgcd
Bezout representation of gcd (see extgcd)
factorize
factorize polynomial (see factorize)
finduni
find univariate polynomials in a zero-dimensional ideal (see finduni)
gcd
greatest common divisor (see gcd)
homog
homogenization (see homog)
jacob
ideal, resp. matrix, of all partial derivatives (see jacob)
lead
leading term (see lead)
leadcoef
coefficient of the leading term (see leadcoef)
leadexp
the exponent vector of the leading monomial (see leadexp)
leadmonom
leading monomial (see leadmonom)
jet
monomials with degree smaller k+1 (see jet)
ord
degree of the leading monomial (see ord)
qhweight
quasihomogeneous weights (see qhweight)
reduce
normal form with respect to a standard base (see reduce)
rvar
test for ring variable (see rvar)
simplify
normalize a polynomial (see simplify)
size
number of monomials (see size)
subst
substitute a ring variable (see subst)
trace
trace of a matrix (see trace)
var
the indicated variable of the ring (see var)
varstr
variable in string form (see varstr)


4.13 proc
=========

Procedures are sequences of SINGULAR commands in a special
format. They are used to extend the set of SINGULAR commands with
user defined commands. Once a procedure is defined it can be used as
any other 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 SINGULAR see
Procedures. A file containing procedure definitions which comply with
certain syntax rules is called a library. Such a file is loaded
using the command LIB. For more information on libraries see
Libraries.

* proc declaration::

4.13.1 proc declaration
-----------------------

Syntax:
[static] proc proc_name [parameter_list]

["help_text"]

{


   procedure_body

}

[example

{


   sequence_of_commands;

}]

proc proc_name = proc_name ;

proc proc_name = string_expression ;
Purpose:
defines a new function, the proc proc_name, with the additional
information help_text, which is copied to the screen by
help proc_name; and the example section
which is executed by example proc_name;.

 The help_text, the parameter_list, and the example section are optional.
The default for a parameter_list is (list #), see 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 LIB command.

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

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



4.14 qring
==========

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 Rings and orderings.

* qring declaration::

4.14.1 qring declaration
------------------------

Syntax:
qring name = ideal_expression ;
Default:
none
Purpose:
declares a quotient ring as the basering modulo ideal_expression.  Sets
it as current basering.
Example:
ring r=0,(x,y,z),dp;
ideal i=xy;
qring q=std(i);
basering;
==> //   characteristic : 0
==> //   number of vars : 3
==> //        block   1 : ordering dp
==> //                  : names    x y z 
==> //        block   2 : ordering C
==> // quotient ring from ideal
==> _[1]=xy

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

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 [ , ] causes
implicitly a cast to a list).

* resolution declarations::
* resolution expressions::
* resolution related functions::

4.15.1 resolution declarations
------------------------------

Syntax:
resolution name = resolution_expression ;

Purpose:
defines a resolution.

Default:
none

Example:
  ring R;
  ideal i=z2,x;
  resolution re=res(i,0);
  re;
==>  1      2      1      
==> R <--  R <--  R
==> 
==> 0      1      2      
==> resolution not minimized yet
==> 
  betti(re);
==> 1,1,0,
==> 0,1,1 
  list l = re;
  l;
==> [1]:
==>    _[1]=x
==>    _[2]=z2
==> [2]:
==>    _[1]=-z2*gen(1)+x*gen(2)
==> [3]:
==>    _[1]=0

4.15.2 resolution expressions
-----------------------------

A resolution expression is:
1. an identifier of type resolution
2. a function returning a resolution
3. a type cast to resolution from a list of ideals, resp. modules..


4.15.3 resolution related functions
-----------------------------------

betti
Betti numbers of a resolution (see betti)
lres
free resolution (see lres)
minres
minimize a free resolution (see minres)
mres
minimal free resolution of an ideal, resp. module w.r.t. a minimal set of generators of
the given ideal, resp. module (see mres)
res
free resolution of an ideal, resp. module, but not changing the
given ideal, resp. module (see res)
sres
free resolution of a standard basis (see sres)


4.16 ring
=========

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

* ring declarations::
* ring related functions::
* ring operations::

4.16.1 ring declarations
------------------------

Syntax:
ring name = ( coefficient_field ),
  ( names_of_ring_variables ),
  ( ordering );
Default:
32003,(x,y,z),(dp,C);
Purpose:
declares a ring and sets it as the actual basering.

The coefficient_field is given by one of the following:
1. a non-negative int_expression less or equal 2147483629.
2. an expression_list of an int_expression and one or more names.
3. the name real
4. an expression_list of the name real and an  int_expression.
5. an expression_list of the name complex, an optional int_expression
and a name.

For the definition of the 'coefficient_field', see 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
1. lp, dp, Dp, ls, ds, or Ds
optionally followed by a size parameter in parentheses.

2. wp, Wp, ws, Ws, or a followed by a
weight vector given as an intvec_expression in parentheses.

3. M followed by an intmat_expression in parentheses.

4. c or C.

For the definition of the orderings, see Term orderings,
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.

4.16.2 ring related functions
-----------------------------

charstr
description of the coefficient field of a ring (see charstr)
keepring
move ring to next upper level (see keepring)
npars
number of ring parameters (see npars)
nvars
number of ring variables (see nvars)
ordstr
monomial ordering of a ring (see ordstr)
parstr
names of all ring parameters or the
name of the n-th ring parameter (see parstr)
qring
quotient ring (see qring)
setring
set a new basering (see setring)
varstr
names of all ring variables or the
name of the n-th ring variable (see varstr)

4.16.3 ring operations
----------------------
+
construct a new ring 
 from 
  and 
.

Concerning the ground fields 
 and 
 take the
following guide lines into consideration:
* Neither 
 nor 
 may be 
 or 
.
* If the characteristic of 
 and 
 differs, then one of them must be 
.
* At most one of 
 and 
 may be have parameters.
* If one of 
 and 
 is an algebraic extension of 
 it may not be defined by a charstr of type (p^n,a).


Example:
  ring R1=0,(x,y),dp;
  ring R2=32003,(a,b),dp;
  def R=R1+R2;
  R;
==> //   characteristic : 32003
==> //   number of vars : 4
==> //        block   1 : ordering dp
==> //                  : names    x y 
==> //        block   2 : ordering dp
==> //                  : names    a b 
==> //        block   3 : ordering C


4.17 string
===========

Variables of type string are used for output (almost every type
can be "converted" to string) and for creating new
commands at runtime see execute.  They are also return values of
certain interpreter related functions (see Functions).  String
constants consist of a sequence of ANY characters (including newline!)
between a starting " and a closing ".  There is also a
string constant newline, which is the newline character.  The
+ sign "adds" strings, "" 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.

  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;
==> Hi
==> a string with new line at the end
==> 
==> another string with new line at the end
==>   
  ring r; ideal i=std(ideal(x,y^3));
  "dimension of i =",dim(i),", multiplicity of i =",mult(i);
==> dimension of i = 1 , multiplicity of i = 3
  "dimension of i = "+string(dim(i))+", multiplicity of i = "+string(mult(i));
==> dimension of i = 1, multiplicity of i = 3
  "a"+"b","c";
==> ab c
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 + concatenates strings.

* string declarations::
* string expressions::
* string type cast::
* string operations::
* string related functions::

4.17.1 string declarations
--------------------------

Syntax:
string name = string_expression ;

string name = list_of_string_expressions ;

Purpose:
defines a string variable.

Default:
"" (the empty string)

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

4.17.2 string expressions
-------------------------

A string expression is:
1. a sequence of characters between two unescaped quotes (")
2. an identifier of type string
3. a function returning string
4. a substring (using the bracket operator)
5. a type cast to string (see string type cast)
6. string expressions combined by the operation +.


Example:
// string_expression[start, length] : a substring
// (possibly filled up with blanks)
// the substring of s starting at position 2
// with a length of 4
string s="123456";
s[2,4];
==> 2345
"abcd"[2,2];
==> bc
// string_expression[position] : a character from a string
s[3];
==> 3
// string_expression[position..position] :
// a substring starting at the first position up to the second
// given position
s[2..4];
==> 2 3 4
// a function returning a string
typeof(s);
==> string


4.17.3 string type cast
-----------------------
Syntax:
string ( expression [, expression_2, ... expression_n])
Type:
string
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.

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

Example:
  string("1+1=", 2);
==> 1+1=2
  string(intvec(1,2,3,4));
==> 1,2,3,4
  string(intmat(intvec(1,2,3,4), 2, 2));
==> 1,2,3,4 
  ring r;
  string(r);
==> (32003),(x,y,z),(dp(3),C)
  string(ideal(x,y));
==> x,y
  qring R = std(ideal(x,y));
  string(R);
==> (32003),(x,y,z),(dp(3),C)
  map phi = r, ideal(x,z);
  string(phi);
==> x,z
  list l;
  string(l);
==> 
  l[3] = 1;
  string(l); // notice that l[1],l[2] are omitted
==> 1
  l[2] = l;
  l;
==> [2]:
==>    [3]:
==>       1
==> [3]:
==>    1
  string(l); // notice that lists of list is flattened
==> 1,1
  l[1] = intvec(1,2,3);
  l;
==> [1]:
==>    1,2,3
==> [2]:
==>    [3]:
==>       1
==> [3]:
==>    1
  string(l); // notice that intvec elements are not distinguishable
==> 1,2,3,1,1

4.17.4 string operations
------------------------

+
concatenation

<=, >=, ==, <>
comparison (lexicographical with respect to the ASCII encoding)

string_expression [ int_expression ]
is a character of the string; the index 1 gives the first character.

string_expression [ int_expression, int_expression ]
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

string_expression [ intvec_expression ]
is a expression list of characters from the string


Example:
  string s="abcde";
  s[2];
==> b
  s[3,2];
==> cd
  ">>"+s[1,10]+"<<";
==> >>abcde     <<
  s[2]="BC"; s;
==> aBcde
  intvec v=1,3,5;
  s=s[v]; s;
==> ace
  s="123456"; s=s[3..5]; s;
==> 345

4.17.5 string related functions
-------------------------------

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


4.18 vector
===========

Vectors are elements of a free module over the basering with basis
gen(1), gen(2), ... .
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 f and g are polynomials then
f*gen(1)+g*gen(3)+gen(4) may also be written as [f,0,g,1]
or as [f,0,g,1,0].) Note that the elements of a vector have to be
surrounded by square brackets ([  , ])
(cf. Representation of mathematical objects).

* vector declarations::
* vector expressions::
* vector operations::
* vector related functions::

4.18.1 vector declarations
--------------------------

Syntax:
vector name = vector_expression ;

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

Default:
[0]

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

4.18.2 vector expressions
-------------------------

A vector expression is:
1. an identifier of type vector
2. a function returning vector
3. a poly expression (via the canonical embedding p ==> p*gen(1))
4. vector expressions combined by the arithmetic operations + or
-
5. a poly expression and a vector expression combined by the arithmetic
operation *
6. a type cast to vector using the brackets [ , ]


Example:
  // ordering gives priority to components:
  ring rr=0,(x,y,z),(c,dp);
  vector v=[x2+y3,2,0,x*y]+gen(6)*x6;
  v;
==> [y3+x2,2,0,xy,0,x6]
  vector w=[z3-x,3y];
  v-w;
==> [y3-z3+x2+x,-3y+2,0,xy,0,x6]
  v*(z+x);
==> [xy3+y3z+x3+x2z,2x+2z,0,x2y+xyz,0,x7+x6z]


4.18.3 vector operations
------------------------

+
addition

-
negation or subtraction

/
division by a monomial, not divisible terms yield 0

<, <=, >, >=, ==, <>
comparison of leading terms w.r.t. monomial ordering

vector_expression [ int_expressions ]
is a vector entry; the index 1 gives the first entry.


Example:
  ring R=0,(x,y),(c,dp);
  [x,y]-[1,x];
==> [x-1,-x+y]
  [1,2,x,4][3];
==> x


4.18.4 vector related functions
-------------------------------

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


