@comment -*-texinfo-*-
@comment $Id: reference.doc,v 1.330 2009-03-11 11:22:03 seelisch Exp $
@comment this file contains the reference part of the manual

@c The following directives are necessary for proper compilation
@c with emacs (C-c C-e C-r)end tex.  Please keep it as it is.  Since it
@c is wrapped in `@ifset' and `@end' it does not harm `tex' or
@c `makeinfo' but is a great help in editing this file (emacs
@c ignores the conditionals).
@ignore
%**start
\input texinfo.tex
@setfilename reference.info
@node Top, Functions and system variables
@menu
* Functions and system variables::
@end menu
@node Functions and system variables, Tricks and pitfalls, Data types, Top
@chapter Functions and system variables
%**end
@end ignore

@c ---------------------------------------
@menu
* Functions::
* Control structures::
* System variables::
@end menu

@c ---------------------------------------
@node Functions, Control structures, Functions and system variables, Functions and system variables
@section Functions
@cindex Functions

This section gives a complete reference of all functions, commands and
special variables of the @sc{Singular} kernel (i.e., all built-in
commands). @xref{standard_lib}, for those
functions from the @code{standard.lib} (this library is automatically
loaded at start-up time) which extend the functionality of the kernel
and are written
in the  @sc{Singular} programming language.

The general syntax of a function is
@format
                   [target =] function_name (<arguments>);
@end format
If no target is specified, the result is printed.
In some cases (e.g., @code{export}, @code{keepring},
@code{setring}, @code{type}) the brackets are optional. For the commands
@code{kill}, @code{help}, @code{break}, @code{quit}, @code{exit}
and @code{LIB} no brackets are allowed.

@ifinfo
@*List of all supported kernel functions.
@end ifinfo
@menu
* attrib::
* bareiss::
* betti::
* char::
* char_series::
* charstr::
* chinrem::
* cleardenom::
* close::
* coef::
* coeffs::
* contract::
* dbprint::
* defined::
* deg::
* degree::
* delete::
* det::
* diff::
* dim::
* division::
* dump::
* eliminate::
* eval::
* ERROR::
* example::
* execute::
* exit::
* extgcd::
* facstd::
* factorize::
* fetch::
* fglm::
* fglmquot::
* filecmd::
* find::
* finduni::
* fprintf::
* freemodule::
* frwalk::
* gcd::
* gen::
* getdump::
* groebner::
* help::
* highcorner::
* hilb::
* homog::
* hres::
* imap::
* impart::
* indepSet::
* insert::
* interpolation::
* interred::
* intersect::
* jacob::
* janet::
* jet::
* kbase::
* kernel::
* kill::
* killattrib::
* koszul::
* laguerre::
* lead::
* leadcoef::
* leadexp::
* leadmonom::
* LIB::
* lift::
* liftstd::
* listvar::
* lres::
* maxideal::
* memory::
* minbase::
* minor::
* minres::
* modulo::
* monitor::
* mpresmat::
* mres::
* mstd::
* mult::
* nameof::
* names::
* ncols::
* npars::
* nres::
* nrows::
* nvars::
* open::
* option::
* ord::
* ordstr::
* par::
* pardeg::
* parstr::
* preimage::
* prime::
* print::
* printf::
* prune::
* qhweight::
* quote::
* quotient::
* random::
* read::
* reduce::
* regularity::
* repart::
* res::
* reservedName::
* resultant::
* ringlist::
* rvar::
* setring::
* simplex::
* simplify::
* size::
* slimgb::
* sortvec::
* sqrfree::
* sprintf::
* sres::
* status::
* std::
* stdfglm::
* stdhilb::
* subst::
* system::
* syz::
* trace::
* transpose::
* type::
* typeof::
* univariate::
* uressolve::
* vandermonde::
* var::
* variables::
* varstr::
* vdim::
* wedge::
* weight::
* weightKB::
* write::
@end menu
@c ---------------------------------------
@node attrib, bareiss, Functions, Functions
@subsection attrib
@cindex attrib
@table @code
@item @strong{Syntax:}
@code{attrib (} name @code{)}
@item @strong{Type:}
none
@item @strong{Purpose:}
displays the attribute list of the object called name.
@item @strong{Example:}
@smallexample
@c example
  ring r=0,(x,y,z),dp;
  ideal I=std(maxideal(2));
  attrib(I);
@c example
@end smallexample
@item @strong{Syntax:}
@code{attrib (} name @code{,} string_expression @code{)}
@item @strong{Type:}
any
@item @strong{Purpose:}
returns the value of the attribute string_expression of the
variable name. If the attribute is not defined for this variable,
@code{attrib} returns the empty string.
@item @strong{Example:}
@smallexample
@c example
  ring r=0,(x,y,z),dp;
  ideal I=std(maxideal(2));
  attrib(I,"isSB");
  // although maxideal(2) is a standard basis,
  // SINGULAR does not know it:
  attrib(maxideal(2), "isSB");
@c example
@end smallexample
@item @strong{Syntax:}
@code{attrib (} name@code{,} string_expression@code{,} expression @code{)}
@item @strong{Type:}
none
@item @strong{Purpose:}
sets the attribute string_expression of the variable name
to the value expression.
@item @strong{Example:}
@smallexample
@c example
  ring r=0,(x,y,z),dp;
  ideal I=maxideal(2); // the attribute "isSB" is not set
  vdim(I);
  attrib(I,"isSB",1);  // the standard basis attribute is set here
  vdim(I);
@c example
@end smallexample
@item @strong{Remark:}
An attribute may be described by any string_expression. Some of these are
used by the kernel of @sc{Singular} and referred to as reserved attributes.
Non-reserved attributes may be used, however, in procedures and can
considerably speed up computations.
@sp 1
@item @strong{Reserved attributes:}
(isSB, isHomog are used by the kernel, the other are used by libraries)
@table @code
@item isSB
the standard basis property is set by all commands computing a standard
basis like
@code{groebner}, @code{std}, @code{stdhilb} etc.; used by @code{lift}, @code{dim},
@code{degree}, @code{mult}, @code{hilb}, @code{vdim}, @code{kbase}
@item isHomog
the weight vector for homogeneous or quasihomogeneous ideals/modules
@item isCI
complete intersection property
@item isCM
Cohen-Macaulay property
@item rank
set the rank of a module (see @ref{nrows})
@item withSB
value of type ideal, resp.@: module, is std
@item withHilb
value of type intvec is hilb(_,1) (see @ref{hilb})
@item withRes
value of type list is a free resolution
@item withDim
value of type int is the dimension (see @ref{dim})
@item withMult
value of type int is the multiplicity (see @ref{mult})
@end table
@end table
@c @c ref
@c See
@c @ref{Expressions};
@c @ref{killattrib}.
@c @c ref
@c ---------------------------------------
@node bareiss, betti, attrib, Functions
@subsection bareiss
@cindex bareiss

@table @code
@item @strong{Syntax:}
@code{bareiss (} module_expression @code{)}
@*@code{bareiss (} matrix_expression @code{)}
@*@code{bareiss (} module_expression@code{,} int_expression@code{,} int_expression @code{)}
@*@code{bareiss (} matrix_expression@code{,} int_expression@code{,} int_expression @code{)}
@item @strong{Type:}
list of module and intvec
@item @strong{Purpose:}
applies the sparse Gauss-Bareiss algorithm (see @ref{References}, Lee and
Saunders) to a module (or with type conversion to a matrix) with an 'optimal'
pivot strategy. The vectors of the module are the columns of the matrix,
hence elimination takes place w.r.t.@: rows.
@* With only one parameter a complete elimination is done.
Result is a list: the first entry is a module with a minimal independent set
of vectors (as a matrix lower triangular),
the second entry an intvec with the permutation of the rows
w.r.t.@: the original matrix, that is, a k at position l indicates that
row k was carried over to the row l.
@* The further parameters control the algorithm. @code{bareiss(M,i,j)}
does not attempt to diagonalize the last i rows in the elimination procedure
and stops computing when the remaining number of vectors (columns) to reduce
is at most j.
@item @strong{Example:}
@smallexample
@c example
  ring r=0,(x,y,z),(c,dp);
  module mm;
  // ** generation of the module mm **
  int d=7;
  int b=2;
  int db=d-b;
  int i;
  for(i=d;i>0;i--){ mm[i]=3*x*gen(i); }
  for(i=db;i;i--){ mm[i]=mm[i]+7*y*gen(i+b); }
  for(i=d;i>db;i--){ mm[i]=mm[i]+7*y*gen(i-db); }
  for(i=d;i>b;i--){ mm[i]=mm[i]+11*z*gen(i-b); }
  for(i=b;i;i--){ mm[i]=mm[i]+11*z*gen(i+db); }
  // ** the generating matrix of mm **
  print(mm);
  // complete elimination
  list ss=bareiss(mm);
  print(ss[1]);
  ss[2];
  // elimination up to 3 vectors
  ss=bareiss(mm,0,3);
  print(ss[1]);
  ss[2];
  // elimination without the last 3 rows
  ss=bareiss(mm,3,0);
  print(ss[1]);
  ss[2];
@c example
@end smallexample
@end table
@c ref
See
@ref{det};
@ref{matrix}.
@c ref
@c ---------------------------------------
@node betti, char, bareiss, Functions
@subsection betti
@cindex betti
@table @code
@item @strong{Syntax:}
@code{betti (} list_expression @code{)}
@*@code{betti (} resolution_expression @code{)}
@*@code{betti (} list_expression @code{,} int_expression @code{)}
@*@code{betti (} resolution_expression @code{,} int_expression @code{)}
@item @strong{Type:}
intmat
@item @strong{Purpose:}
with 1 argument: computes the graded Betti numbers of a minimal resolution of
@tex
$R^n/M$, if $R$ denotes the basering and
$M$ a homogeneous submodule of $R^n$ and the argument represents a
resolution of
$R^n/M$.
@end tex
@iftex
@*
@end iftex
@tex
The entry d of the intmat at place (i,j) is the minimal number of
generators in degree i+j of the j-th syzygy module (= module of
relations) of $R^n/M$ (the 0th (resp.\ 1st) syzygy module of $R^n/M$ is
$R^n$ (resp.\ $M$)).
@end tex
@ifinfo
R^n/M, if R denotes the basering and
M a homogeneous submodule of R^n and the argument represents a resolution of
R^n/M:
@*The entry d of the intmat at place (i,j) is the minimal number of
generators in degree i+j of the j-th syzygy module (= module of
relations) of R^n/M (the 0th (resp.@: 1st) syzygy module of R^n/M is R^n
(resp.@: M)).
@end ifinfo
The argument is considered to be the result of a res/sres/mres/nres/lres
command. This implies that a zero is only allowed (and counted) as a
generator in the first module.
@*For the computation betti uses only the initial monomials. This could lead
to confusing results for a non-homogeneous input.

If the optional second argument is non-zero, the Betti numbers will be minimized.
@c If it is 0 then the Betti numbers correspond exactly to the input -
@c otherwise the command is identical to the one-argument form.
@item @strong{Example:}
@smallexample
@c example
  ring r=32003,(a,b,c,d),dp;
  ideal j=bc-ad,b3-a2c,c3-bd2,ac2-b2d;
  list T=mres(j,0); // 0 forces a full resolution
  // a minimal set of generators for j:
  print(T[1]);
  // second syzygy module of r/j which is the first
  // syzygy module of j (minimal generating set):
  print(T[2]);
  // the second syzygy module (minimal generating set):
  print(T[3]);
  print(T[4]);
  betti(T);
  // most useful for reading off the graded Betti numbers:
  print(betti(T),"betti");
@c example
@end smallexample
@end table

Hence
@itemize @bullet
@item the 0th syzygy module of r/j (which is r) has 1 generator in
degree 0 (which is 1),
@item the 1st syzygy module @code{T[1]} (which is j) has 4
generators (one in degree 2 and three in degree 3),
@item the 2nd syzygy
module @code{T[2]} has 4 generators (all in degree 4),
@item the 3rd syzygy module @code{T[3]} has
1 generator in degree 5,
@end itemize
where the generators are the columns of the
displayed matrix and degrees are assigned such that the corresponding maps
have degree 0:
@tex
$$
0 \longleftarrow r/j \longleftarrow r(1)
\buildrel{T[1]}\over{\longleftarrow} r(2) \oplus r^3(3)
\buildrel{T[2]}\over{\longleftarrow} r^4(4)
\buildrel{T[3]}\over{\longleftarrow} r(5)
\longleftarrow 0 \quad .
$$
@end tex
@ifinfo
@*                     T[1]                T[2]           T[3]
@*0 <-- r/j <-- r(1) <------ r(2)+r^3(3) <------ r^4(4) <------ r(5) <-- 0 .
@end ifinfo

@c ref
See
@ref{hres};
@ref{lres};
@ref{mres};
@ref{print};
@ref{res};
@ref{sres};
@ref{Syzygies and resolutions};
@ref{resolution}.
@c ref
@c ---------------------------------------
@node char, char_series, betti, Functions
@subsection char
@cindex char

@table @code
@item @strong{Syntax:}
@code{char (} ring_name @code{)}
@item @strong{Type:}
int
@item @strong{Purpose:}
returns the characteristic of the coefficient field of a ring.
@item @strong{Example:}
@smallexample
@c example
  ring r=32003,(x,y),dp;
  char(r);
  ring s=0,(x,y),dp;
  char(s);
  ring ra=(7,a),(x,y),dp;
  minpoly=a^3+a+1;
  char(ra);
  ring rp=(49,a),(x,y),dp;
  char(rp);
  ring rr=real,x,dp;
  char(rr);
@c example
@end smallexample
@end table
@c ref
See
@ref{ring};
@ref{charstr}.
@c ref
@c ---------------------------------------
@node char_series, charstr, char, Functions
@subsection char_series
@cindex char_series

@table @code
@item @strong{Syntax:}
@code{char_series (} ideal_expression @code{)}
@item @strong{Type:}
matrix
@item @strong{Purpose:}
the rows of the matrix represent the irreducible characteristic series of the
ideal with respect to the current ordering of variables.
@*One application is the decomposition of the zero-set.
@item @strong{Example:}
@smallexample
@c example
  ring r=32003,(x,y,z),dp;
  print(char_series(ideal(xyz,xz,y)));
@c example
@end smallexample
@c @item @strong{Background:}
@c @tex
@c Let $>$ be the lexicographical ordering $x_1 < ... < x_n$ on $R=K[x_1,...,x_n]$.
@c For $f \in R$ let lvar(f) (the leading variable of f) be the largest
@c variable in lead(f) (the leading term of f with respect to $>$),
@c i.e., if $f=a_k(x_1,...,x_{k-1})x_k^s+...+a_0(x_1,...,x_{k-1})$ for some
@c $k \leq n$ then $lvar(f)=x_k$, moreover let $ini(f):=a_k(x_1,...,x_{k-1})$.
@c
@c A set $T=\{f_1,...,f_r\} \subset R$ is called triangular if $lvar(f_1)<...<lvar(f_r)$.
@c The pseudoremainder $r=prem(g,f)$ of $g$ with respect to $f$ is defined by
@c $ini(f)^a*g=q*f+r$ with the property $deg_{lvar(f)}(r)<deg_{lvar(f)}(f)$,
@c a minimal.
@c
@c (T,U) is called a triangular system, if T is a triangular set such that ini(T)
@c does not vanish on $Zero(T) \setminus Zero(U)
@c ( =:Zero(T\setminus U))$.
@c
@c T is called irreducible if for every i there are no $d_i$,$f_i'$,$f_i''$ with
@c the property:
@c $$   lvar(d_i)<lvar(f_i) $$
@c $$   lvar(f_i')=lvar(f_i'')=lvar(f_i)$$
@c $$   0 \not\in prem(\{ d_i, ini(f_i'), ini(f_i'')\},\{ f_1,...,f_(i-1)\})$$
@c such that $prem(d_i*f_i-f_i'*f_i'',\{f_1,...,f_(i-1)\})=0$.
@c
@c (T,U) is irreducible if T is irreducible.
@c
@c Let $G=\{g_1,...,g_s\}$ then there are irreducible triangular sets $T_1,...,T_l$
@c such that $Zero(G)=\bigcup(i=1..l: Zero(T_i\setminus I_i))$
@c where $I_i=\{ini(f), f \in T_i \}$.
@c @end tex
@c @ifinfo
@c Let > be the lexicographical ordering x_1 < ... < x_n on R=K[x_1,...,x_n].
@c For f in R let lvar(f) (the leading variable of f) be the largest
@c variable in lead(f) (the leading term of f with respect to >),
@c i.e., if f=a_k(x_1,...,x_(k-1))x_k^s+...+a_0(x_1,...,x_(k-1)) for some
@c k<=n then lvar(f)=x_k, moreover let ini(f):=a_k(x_1,...,x_(k-1)).
@c
@c A set T=@{f_1,...,f_r@} in R is called triangular if lvar(f_1)<...<lvar(f_r).
@c The pseudoremainder r=prem(g,f) of g with respect to f is defined by
@c ini(f)^a*g=q*f+r with the property deg_(lvar(f))(r)<deg_(lvar(f))(f),s
@c a minimal.
@c
@c (T,U) is called a triangular system, if T is a triangular set such that ini(T)
@c does not vanish on the zero-set of T \ zero-set of U
@c ( =:Zero(T\U)).
@c
@c T is called irreducible if for every i there are no d_i,f_i',f_i'' with
@c the property:
@c @*   lvar(d_i)<lvar(f_i)
@c @*   lvar(f_i')=lvar(f_i'')=lvar(f_i)
@c @*   0 not in prem(@{ d_i, ini(f_i'), ini(f_i'')@},@{ f_1,...,f_(i-1)@})
@c @*such that prem(d_i*f_i-f_i'*f_i'',@{f_1,...,f_(i-1)@})=0.
@c
@c (T,U) is irreducible if T is irreducible.
@c
@c Let G=@{g_1,...,g_s@} then there are irreducible triangular sets T_1,...,T_l
@c such that Zero(G)=Union(i=1..l: Zero(T_i\I_i))
@c where I_i=@{ini(f), f in T_i @}.
@c @end ifinfo
@c @item @strong{Example:}
@c @example
@c @c example
@c   ring R=0,(x,y,z,u),dp;
@c   ideal i=-3zu+y2-2x+2,
@c           -3x2u-4yz-6xz+2y2+3xy,
@c           -3z2u-xu+y2z+y;
@c   print(char_series(i));
@c @c example
@c @end example
@end table

@c ref
See
@ref{Characteristic sets}.
@c ref
@c ---------------------------------------
@node charstr, chinrem, char_series, Functions
@subsection charstr
@cindex charstr

@table @code
@item @strong{Syntax:}
@code{charstr (} ring_name @code{)}
@item @strong{Type:}
string
@item @strong{Purpose:}
returns the description of the coefficient field of a ring.
@item @strong{Example:}
@smallexample
@c example
  ring r=32003,(x,y),dp;
  charstr(r);
  ring s=0,(x,y),dp;
  charstr(s);
  ring ra=(7,a),(x,y),dp;
  minpoly=a^3+a+1;
  charstr(ra);
  ring rp=(49,a),(x,y),dp;
  charstr(rp);
  ring rr=real,x,dp;
  charstr(rr);
@c example
@end smallexample
@end table
@c ref
See
@ref{char};
@ref{ring};
@ref{ordstr};
@ref{varstr}.
@c ref
@c ---------------------------------------
@node chinrem, cleardenom, charstr, Functions
@subsection chinrem
@cindex chinrem

@table @code
@item @strong{Syntax:}
@code{chinrem (} list, intvec @code{)}
@*@code{chinrem (} intvec, intvec @code{)}
@item @strong{Type:}
ideal resp. bigint
@item @strong{Purpose:}
applies chines remainder theorem to the fisrt argument wrt. the moduli given in the second.
@item @strong{Example:}
@smallexample
@c example
  ring r=0,(x,y),dp;
  ideal i1=5x+2y,x2+3y2+xy;
  ideal i2=2x-3y,2x2+4y2+5xy;
  chinrem(list(i1,i2),intvec(7,11));
  chinrem(intvec(2,-3),intvec(7,11));
@c example
@end smallexample
@end table
@c ref
See
@ref{modstd_lib}.
@c ref
@c ---------------------------------------
@node cleardenom, close, chinrem, Functions
@subsection cleardenom
@cindex cleardenom

@table @code
@item @strong{Syntax:}
@code{cleardenom (} poly_expression @code{)}
@*@code{cleardenom (} vector_expression @code{)}
@item @strong{Type:}
same as the input type
@item @strong{Purpose:}
multiplies a polynomial, resp.@: vector, by a suitable constant to cancel
all denominators from its coefficients and then divide it by its content.
@item @strong{Example:}
@smallexample
@c example
  ring r=0,(x,y,z),dp;
  poly f=(3x+6y)^5;
  f/5;
  cleardenom(f/5);
  vector w= [4x2+20,6x+2,0,8];   // application to a vector
  print(cleardenom(w));
@c example
@end smallexample
@end table
@c ref
See
@ref{content}.
@c ref
@c ---------------------------------------
@node close, coef, cleardenom, Functions
@subsection close
@cindex close
@table @code
@item @strong{Syntax:}
@code{close (} link_expression @code{)}
@item @strong{Type:}
none
@item @strong{Purpose:}
closes a link.
@item @strong{Example:}
@smallexample
link l="MPtcp:launch";
open(l); // start SINGULAR "server" on localhost in batchmode
close(l); // shut down SINGULAR server
@end smallexample
@end table
@c ref
See
@ref{link};
@ref{open}.
@c ref
@c ---------------------------------------
@node coef, coeffs, close, Functions
@subsection coef
@cindex coef

@table @code
@item @strong{Syntax:}
@code{coef (} poly_expression@code{,} product_of_ringvars @code{)}
@item @strong{Type:}
matrix
@item @strong{Syntax:}
@code{coef (} vector_expression@code{,} product_of_ringvars@code{,} matrix_name@code{,} matrix_name @code{)}
@item @strong{Type:}
none
@item @strong{Purpose:}
determines the monomials in f divisible by one of the ring variables of m
(where f is the first argument and m the second argument) and the coefficients
of these monomials as polynomials in the remaining variables.

First case:  returns a 2 x n matrix M, n being the number
of the determined monomials.
The first row consists of these monomials, the second row
of the corresponding coefficients of the monomials in f.
Thus, f = M[1,1]*M[2,1]+...+M[1,n]*M[2,n].

Second case: the second matrix (i.e., the 4th argument) contains the
monomials, the first matrix (i.e., the 3rd argument) the corresponding
coefficients of the monomials in the vector.

@item @strong{Note:}
coef considers only monomials which really occur in f (i.e., which are not 0),
while coeffs (see @ref{coeffs}) returns the coefficient 0 at the
appropriate place if a monomial is not present.

@item @strong{Example:}
@smallexample
@c example
  ring r=32003,(x,y,z),dp;
  poly f=x5+5x4y+10x2y3+y5;
  matrix m=coef(f,y);
  print(m);
  f=x20+xyz+xy+x2y+z3;
  print(coef(f,xy));
  vector v=[f,zy+77+xy];
  print(v);
  matrix mc; matrix mm;
  coef(v,y,mc,mm);
  print(mc);
  print(mm);
@c example
@end smallexample
@end table
@c ref
See
@ref{coeffs}.
@c ref
@c ---------------------------------------
@node coeffs, contract, coef, Functions
@subsection coeffs
@cindex coeffs

@table @code
@item @strong{Syntax:}
@code{coeffs (} poly_expression @code{,} ring_variable @code{)}
@*@code{coeffs (} ideal_expression@code{,} ring_variable @code{)}
@*@code{coeffs (} vector_expression@code{,} ring_variable @code{)}
@*@code{coeffs (} module_expression@code{,} ring_variable @code{)}
@*@code{coeffs (} poly_expression@code{,} ring_variable@code{,} matrix_name @code{)}
@*@code{coeffs (} ideal_expression@code{,} ring_variable@code{,} matrix_name @code{)}
@*@code{coeffs (} vector_expression@code{,} ring_variable@code{,} matrix_name @code{)}
@*@code{coeffs (} module_expression@code{,} ring_variable@code{,} matrix_name @code{)}
@item @strong{Type:}
matrix
@item @strong{Purpose:}
develops each polynomial of the first argument J
as a univariate polynomial in the given ring_variable
z, and returns the coefficients as a matrix M.

With e denoting the maximal z-degree occuring in the polynomials of J, and d:=e+1, M =
@tex
  $(m_{ij})$
@end tex
@ifinfo
  (m(i,j))
@end ifinfo
satisfies the following conditions:
@itemize
@item
(i) If J is a single polynomial f, then M is a (d x 1)-matrix and
@tex
  $m_{i+1,j}, 0\leq i\leq e$,
@end tex
@ifinfo
  m(i+1,j), 0 <= i <= e,
@end ifinfo
is the coefficient of
@tex
  $z^i$
@end tex
@ifinfo
  z^i
@end ifinfo
in f.
@item
(ii) If J is an ideal with generators
@tex
  $f_1, f_2,\ldots,f_k$
@end tex
@ifinfo
  f_1, f_2, ..., f_k
@end ifinfo
then M is a (d x k)-matrix and
@tex
  $m_{i+1,j}, 0\leq i\leq e, 1\leq j\leq k$,
@end tex
@ifinfo
  m(i+1,j), 0 <= i <= e, 1 <= j <= k,
@end ifinfo
is the coefficient of
@tex
  $z^i$
@end tex
@ifinfo
  z^i
@end ifinfo
in
@tex
  $f_j$.
@end tex
@ifinfo
  f_j.
@end ifinfo
@item
(iii) If J is a k-dimensional vector with entries
@tex
  $f_1, f_2,\ldots,f_k$
@end tex
@ifinfo
  f_1, f_2, ..., f_k
@end ifinfo
then M is a (dk x 1)-matrix and
@tex
  $m_{(j-1)d+i+1,1}, 0\leq i\leq e, 1\leq j\leq k$,
@end tex
@ifinfo
  m((j-1)d+i+1, 1), 0 <= i <= e, 1 <= j <= k,
@end ifinfo
is the coefficient of
@tex
  $z^i$
@end tex
@ifinfo
  z^i
@end ifinfo
in
@tex
  $f_j$.
@end tex
@ifinfo
  f_j.
@end ifinfo
@item
(iV) If J is a module generated by s vectors
@tex
  $v_1, v_2,\ldots,v_s$
@end tex
@ifinfo
  v_1, v_2, ..., v_s
@end ifinfo
of dimension k then M is a (dk x s)-matrix and
@tex
  $m_{(j-1)d+i+1,r}, 0\leq i\leq e, 1\leq j\leq k, 1\leq r\leq s$,
@end tex
@ifinfo
  m((j-1)d+i+1, r), 0 <= i <= e, 1 <= j <= k, 1 <= r <= s,
@end ifinfo
is the coefficient of
@tex
  $z^i$
@end tex
@ifinfo
  z^i
@end ifinfo
in the j-th entry of
@tex
  $v_r$.
@end tex
@ifinfo
  v_r.
@end ifinfo
@end itemize
The optional third argument T can be used to return the matrix of powers of z
such that matrix(J) = T*M holds in each of the previous four cases.

@item @strong{Note:}
@code{coeffs} returns the coefficient 0 at the appropriate matrix entry if a monomial
is not present, while @code{coef} considers only monomials which actually occur
in the given expression.

@item @strong{Example:}
@smallexample
@c example
  ring r;
  poly f = (x+y)^3;
  poly g = xyz+z10y4;
  ideal i = f, g;
  matrix M = coeffs(i, y);
  print(M);
  vector v = [f, g];
  M = coeffs(v, y);
  print(M);
@c example
@end smallexample

@item @strong{Syntax:}
@code{coeffs (} ideal_expression@code{,} ideal_expression @code{)}
@*@code{coeffs (} module_expression@code{,} module_expression @code{)}
@*@code{coeffs (} ideal_expression@code{,} ideal_expression@code{,} product_of_ringvars @code{)}
@*@code{coeffs (} module_expression@code{,} module_expression@code{,} product_of_ringvars @code{)}

@item @strong{Type:}
matrix

@item @strong{Purpose:}
expresses each polynomial of the first argument M as a sum
@tex
  $sum_{i=1}^k m_i\cdot a_i\cdot x^{e_i}$,
@end tex
@ifinfo
  m_1 * a_1 * x^e1 + m_2 * a_2 * x^e2 + ... + m_k * a_k * x^ek,
@end ifinfo
where the
@tex
  $m_i$
@end tex
@ifinfo
  m_i
@end ifinfo
come from a specified set of monomials, the
@tex
  $a_i$
@end tex
@ifinfo
  a_i
@end ifinfo
are from the underlying
coefficient ring (or field), and the
@tex
  $x^{e_i}$
@end tex
@ifinfo
  x^ei
@end ifinfo
are powers of a specified ring variable x.

The second parameter K provides the set of monomials which should be sufficient to generate all entries of M.@*
Both M and K can be thought of as the matrices obtained by matrix(M) and matrix(K), respectively. (If M and K
are given by ideals, then this matrix has just one row.)

The optional parameter product_of_ringvars determines the variable x: It is expected to be either the product of
all ring variables (then x is 1, and each polynomial will be expressed as
@tex
  $sum_{i=1}^k m_i\cdot a_i$,
@end tex
@ifinfo
  m_1 * a_1 + m_2 * a_2 + ... + m_k * a_k,
@end ifinfo
or product_of_ringvars is the product of all ring variables except one variable (which then determines x).
If product_of_ringvars is omitted then x = 1 as default.

If K contains all monomials that are necessary to express the entries of
M, then the returned matrix A satisfies K*A=M. Otherwise only a subset of entries of K*A and M will coincide.
In this case, the valid entries start at M[1,1] and run from left to right, top to bottom.

@item @strong{Note:}
Note that in general not all entries of K*A and M will coincide, depending on the set of monomials
provided by K.

@item @strong{Example:}
@smallexample
@c example
  ring r=32003,(x,y,z),dp;
  module M = [y3+x2z, xy], [-xy, y2+x2z];
  print(M);
  module K = [x2, xy], [y3, xy], [xy, x];
  print(K);
  matrix A = coeffs(M, K, xy);   // leaving z as variable of interest
  print(A);   // attention: only the first row of M is reproduced by K*A
@c example
@end smallexample
@end table
@c ref
See
@ref{coef};
@ref{kbase}.
@c ref
@c ---------------------------------------
@node contract, dbprint, coeffs, Functions
@subsection contract
@cindex contract

@table @code
@item @strong{Syntax:}
@code{contract (} ideal_expression@code{,} ideal_expression @code{)}
@item @strong{Type:}
matrix
@item @strong{Purpose:}
contracts each of the n elements of the second ideal J
by each of the m elements of the first ideal I,
producing a m x n matrix.
@*Contraction is defined on monomials by:
@*
@ifinfo
@format
  contract(x^A,x^B) := x^(B-A) (if B>=A componentwise),
                    :=   0     (otherwise),
@end format
@end ifinfo
@tex
$${\rm contract}(x^A ,  x^B) := \cases{ x^{(B-A)}, &if $B\ge A$
componentwise\cr 0,&otherwise.\cr}$$
@end tex
where A and B are the multiexponents of the ring variables represented by
@tex
$x$.
@end tex
@ifinfo
x.
@end ifinfo
@code{contract} is extended bilinearly to all polynomials.
@item @strong{Example:}
@smallexample
@c example
  ring r=0,(a,b,c,d),dp;
  ideal I=a2,a2+bc,abc;
  ideal J=a2-bc,abcd;
  print(contract(I,J));
@c example
@end smallexample
@end table
@c ref
See
@ref{diff}.
@c ref
@c ---------------------------------------
@node dbprint, defined, contract, Functions
@subsection dbprint
@cindex dbprint
@table @code
@item @strong{Syntax:}
@code{dbprint (} int_expression@code{,} expression_list @code{)}
@item @strong{Type:}
none
@item @strong{Purpose:}
applies the print command to each expression in the expression_list if
int_expression is positive.
@code{dbprint} may also be used in procedures
in order to print results subject to certain
conditions.
@item @strong{Syntax:}
@code{dbprint (} expression @code{)}
@item @strong{Type:}
none
@item @strong{Purpose:}
The print command is applied to the expression
if @code{printlevel>=voice}.
@item @strong{Note:}
@xref{Guidelines for writing a library}, for an example how this is used
for displaying comments while procedures are executed.
@item @strong{Example:}
@smallexample
@c example
  int debug=0;
  intvec i=1,2,3;
  dbprint(debug,i);
  debug=1;
  dbprint(debug,i);
  voice;
  printlevel;
  dbprint(i);
@c example
@end smallexample
@end table
@c ref
See
@ref{print};
@ref{voice};
@ref{printlevel};
@ref{Debugging tools}.
@c ref
@c ---------------------------------------
@node defined, deg, dbprint, Functions
@subsection defined
@cindex defined

@table @code
@item @strong{Syntax:}
@code{defined (} name @code{)}
@item @strong{Type:}
int
@item @strong{Purpose:}
returns a value <>0 (TRUE) if there is a user-defined object with this name,
and 0 (FALSE) otherwise.
@*A non-zero return value is the level where the object is defined (level
1 denotes the top level, level 2 the level of a first procedure, level 3
the level of a procedure called by a first procedure, etc.). For ring
variables and other constants, -1 is returned.
@item @strong{Note:}
A local object @code{m} may be identified by @code{if
(defined(m)==voice)}.
@item @strong{Example:}
@smallexample
@c example
  ring r=(0,t),(x,y),dp;
  matrix m[5][6]=x,y,1,2,0,x+y;
  defined(mm);
  defined(r) and defined(m);
  defined(m)==voice;   // m is defined in the current level
  defined(x);
  defined(z);
  defined("z");
  defined(t);
  defined(42);
@c example
@end smallexample
@end table
@c ref
See
@ref{rvar};
@ref{voice}.
@c ref
@c ---------------------------------------
@node deg, degree, defined, Functions
@subsection deg
@cindex deg

@table @code
@item @strong{Syntax:}
@code{deg (} poly_expression @code{)}
@*@code{deg (} vector_expression @code{)}
@*@code{deg (} poly_expression @code{,} intvec_expression @code{)}
@*@code{deg (} vector_expression @code{,} intvec_expression @code{)}
@item @strong{Type:}
int
@item @strong{Purpose:}
returns the maximal (weighted) degree of
the terms of a polynomial or a vector;
@*deg(0) is -1.
@*The optional second argument gives the weight vector,
otherwise weight 1 is used for lex orderings and block ordering,
the default weights of the base ring are used for orderings consisting of one
block.

@item @strong{Example:}
@smallexample
@c example
  ring r=0,(x,y,z),lp;
  deg(0);
  deg(x3+y4+xyz3);
  ring rr=7,(x,y),wp(2,3);
  poly f=x2+y3;
  deg(f);
  ring R=7,(x,y),ws(2,3);
  poly f=x2+y3;
  deg(f);
  vector v=[x2,y];
  deg(v);
@c example
@end smallexample
@end table
@c ref
See
@ref{jet};
@ref{ord};
@ref{poly};
@ref{vector}.
@c ref
@c ---------------------------------------
@node degree, delete, deg, Functions
@subsection degree
@cindex degree
@table @code
@item @strong{Syntax:}
@code{degree (} ideal_expression @code{)}
@*@code{degree (} module_expression @code{)}
@item @strong{Type:}
none
@item @strong{Purpose:}
computes the (Krull) dimension and the multiplicity of the
ideal, resp.@: module, generated by the leading monomials of the input
and prints it.  This is equal to the dimension and
multiplicity of the ideal, resp.@: module, if the input is a standard
basis with respect to a degree ordering.
@item @strong{Example:}
@smallexample
@c example
ring r3=32003,(x,y,z),ds;
int a,b,c,t=11,10,3,1;
poly f=x^a+y^b+z^(3*c)+x^(c+2)*y^(c-1)+x^(c-1)*y^(c-1)*z3
  +x^(c-2)*y^c*(y2+t*x)^2;
ideal i=jacob(f);
ideal i0=std(i);
degree(i0);
@c example
@end smallexample
@end table
@c ref
See
@ref{ideal};
@ref{std};
@ref{dim};
@ref{vdim};
@ref{mult}.
@c ref
@c ---------------------------------------
@node delete, det, degree, Functions
@subsection delete
@cindex delete

@table @code
@item @strong{Syntax:}
@code{delete (} list_expression@code{,} int_expression @code{)}
@item @strong{Type:}
list
@item @strong{Purpose:}
deletes the element with the given index from a list (the input is not changed).
@item @strong{Example:}
@smallexample
@c example
  list l="a","b","c";
  list l1=delete(l,2);l1;
  l;
@c example
@end smallexample
@end table
@c ref
See
@ref{list};
@ref{insert}.
@c ref
@c ---------------------------------------
@node det, diff, delete, Functions
@subsection det
@cindex det

@table @code
@item @strong{Syntax:}
@code{det (} intmat_expression @code{)}
@*@code{det (} matrix_expression @code{)}
@*@code{det (} module_expression @code{)}
@item @strong{Type:}
int, resp.@: poly
@item @strong{Purpose:}
returns the determinant of a square matrix. A module is considered
as a matrix. The applied algorithms depend on type of input.
If the input is a module or matrix with symbolic entries the
Bareiss algorithm is used. In the other cases the chinese remainder
algorithm is used. For large sparse problems the input as a module
has advantages.
@item @strong{Example:}
@smallexample
@c example
  ring r=7,(x,y),wp(2,3);
  matrix m[3][3]=1,2,3,4,5,6,7,8,x;
  det(m);
@c example
@end smallexample
@end table
@c ref
See
@ref{intmat};
@ref{matrix};
@ref{minor}.
@c ref
@c ---------------------------------------
@node diff, dim, det, Functions
@subsection diff
@cindex diff

@table @code
@item @strong{Syntax:}
@code{diff (} poly_expression@code{,} ring_variable @code{)}
@*@code{diff (} vector_expression@code{,} ring_variable @code{)}
@*@code{diff (} ideal_expression@code{,} ring_variable @code{)}
@*@code{diff (} module_expression@code{,} ring_variable @code{)}
@*@code{diff (} matrix_expression@code{,} ring_variable @code{)}
@item @strong{Type:}
the same as the type of the first argument
@item @strong{Syntax:}
@code{diff (} ideal_expression@code{,} ideal_expression @code{)}
@item @strong{Type:}
matrix
@item @strong{Purpose:}
computes the partial derivative of a polynomial object by a ring variable
(first forms)
@*respectively differentiates each polynomial (1..n) of the second ideal
by the differential operator corresponding to each polynomial (1..m) in the first
ideal, producing an m x n matrix.
@item @strong{Example:}
@smallexample
@c example
  ring r=0,(x,y,z),dp;
  poly f=2x3y+3z5;
  diff(f,x);
  vector v=[f,y2+z];
  diff(v,z);
  ideal j=x2-yz,xyz;
  ideal i=x2,x2+yz,xyz;
  // corresponds to differential operators
  // d2/dx2, d2/dx2+d2/dydz, d3/dxdydz:
  print(diff(i,j));
@c example
@end smallexample
@end table
@c ref
See
@ref{poly};
@ref{vector};
@ref{ideal};
@ref{module};
@ref{matrix};
@ref{contract};
@ref{jacob};
@ref{var};
@c ref
@c ---------------------------------------
@node dim, division, diff, Functions
@subsection dim
@cindex dim

@table @code
@item @strong{Syntax:}
@code{dim (} ideal_expression @code{)}
@*@code{dim (} module_expression @code{)}
@item @strong{Type:}
int
@item @strong{Purpose:}
computes the dimension of the ideal, resp.@: module, generated by
the leading monomials of the given generators of the ideal, resp.@: module.
This is also the dimension of the ideal if it is represented by
a standard basis.
@item @strong{Note:}
The dimension of an ideal I means
the Krull dimension of the basering modulo I.
@*The dimension of a
module is the dimension of its annihilator ideal.
@item @strong{Example:}
@smallexample
@c example
  ring r=32003,(x,y,z),dp;
  ideal I=x2-y,x3;
  dim(std(I));
@c example
@end smallexample
@end table
@c ref
See
@ref{ideal};
@ref{std};
@ref{degree};
@ref{vdim};
@ref{mult}.
@c ref
@c -------------------------------------------------
@node division, dump, dim, Functions
@subsection division
@cindex division
@table @code
@item @strong{Syntax:}
@code{division (} ideal_expression@code{,} ideal_expression @code{)}
@*@code{division (} module_expression@code{,} module_expression @code{)}
@*@code{division (} ideal_expression@code{,} ideal_expression@code{,} int_expression @code{)}
@*@code{division (} module_expression@code{,} module_expression@code{,} int_expression @code{)}
@*@code{division (} ideal_expression@code{,} ideal_expression@code{,} int_expression@code{,} intvec_expression @code{)}
@*@code{division (} module_expression@code{,} module_expression@code{,} int_expression@code{,} intvec_expression @code{)}
@item @strong{Type:}
list
@item @strong{Purpose:}
@code{division} computes a division with remainder.
For two ideals resp.@: modules @code{M} (first argument) and @code{N}
(second argument), it returns a list @code{T,R,U} where @code{T} is a matrix,
@code{R} is an ideal resp. a module, and @code{U} is a diagonal matrix of units
such that @code{matrix(M)*U=matrix(N)*T+matrix(R)} is a standard representation
for the normal form @code{R} of @code{M} with respect to a standard basis of @code{N}.
@code{division} uses different algorithms depending on whether @code{N} is
represented by a standard basis.
For a polynomial basering, the matrix @code{U} is the identity matrix.
A matrix @code{T} as above is also computed by @code{lift}.
@*For additional arguments @code{n} (third argument) and @code{w} (fourth argument),
@code{division} returns a list @code{T,R} as above such that
@code{matrix(M)=matrix(N)*T+matrix(R)} is a standard representation for the
normal form @code{R} of @code{M} with respect to @code{N} up to weighted degree
@code{n} with respect to the weight vector @code{w}.
The weighted degree of @code{T} and @code{R} respect to @code{w} is at most @code{n}.
If the weight vector @code{w} is not given,
@code{division} uses the standard weight vector @code{w=1,...,1}.
@item @strong{Example:}
@smallexample
@c example
ring R=0,(x,y),ds;
poly f=x5+x2y2+y5;
division(f,jacob(f)); // automatic conversion: poly -> ideal
division(f^2,jacob(f));
division(ideal(f^2),jacob(f),10);
@c example
@end smallexample
@end table
@c ref
See
@ref{ideal};
@ref{lift};
@ref{module}.
@c ref
@c ---------------------------------------
@node dump, eliminate, division, Functions
@subsection dump
@cindex dump
@table @code
@item @strong{Syntax:}
@code{dump (} link_expression @code{)}
@item @strong{Type:}
none
@item @strong{Purpose:}
dumps (i.e., writes in one "message" or "block") the state of the @sc{Singular}
session (i.e., all defined variables and their values) to the specified
link (which must be either an ASCII or MP link) such that a
@code{getdump} can retrieve it later on.
@item @strong{Example:}
@smallexample
@c example
  ring r;
  // write the whole session to the file dump.ascii
  // in ASCII format
  dump(":w dump.ascii");
  kill r;                  // kill the basering
  // reread the session from the file
  // redefining everything which was not explicitly killed before
  getdump("dump.ascii");
  r;
@c example
@end smallexample
@item @strong{Restrictions:}
For ASCII links, integer matrices contained in lists are  dumped as
integer list elements (and not as integer matrices), and lists of lists
are dumped as one flatted list. Furthermore, links
themselves are not dumped.
@end table
@c ref
See
@ref{getdump};
@ref{link};
@ref{write}.
@c ref
@c ---------------------------------------
@node eliminate, eval, dump, Functions
@subsection eliminate
@cindex eliminate

@table @code
@item @strong{Syntax:}
@code{eliminate (} ideal_expression@code{,} product_of_ring_variables @code{)}
@*@code{eliminate (} module_expression@code{,} product_of_ring_variables @code{)}
@*@code{eliminate (} ideal_expression@code{,} intvec_expression @code{)}
@*@code{eliminate (} module_expression@code{,} intvec_expression @code{)}
@*@code{eliminate (} ideal_expression@code{,} product_of_ring_variables@code{,} intvec_hilb @code{)}
@*@code{eliminate (} module_expression@code{,} product_of_ring_variables@code{,} intvec_hilb @code{)}
@item @strong{Type:}
the same as the type of the first argument
@item @strong{Purpose:}
eliminates variables occurring as factors/entries of the second argument from an
ideal (resp.@: a submodule of a free module), by intersecting it
(resp. each component of the submodule) with the subring not containing these variables.
@c comment: GMG insisted on changing the definition
@c eliminates variables occurring as factors of the second argument from an
@c ideal, resp.@: module, by intersecting it with the subring not containing
@c these variables.
@*@code{eliminate} does not need a special ordering nor a standard basis as input.
@item @strong{Note:}
Since elimination is expensive, for homogeneous input it might be useful
first to compute the Hilbert function of the ideal (first
argument) with a fast ordering (e.g., @code{dp}). Then make use of it to speed
up the computation: a Hilbert-driven elimination uses the intvec
provided as the third argument.
@*If the ideal (resp. module) is not homogeneous with weights 1,
this intvec will be silently ignored.
@item @strong{Example:}
@smallexample
@c example
  ring r=32003,(x,y,z),dp;
  ideal i=x2,xy,y5;
  eliminate(i,x);
  ring R=0,(x,y,t,s,z),dp;
  ideal i=x-t,y-t2,z-t3,s-x+y3;
  eliminate(i,ts);
  ideal j=x2,xy,y2;
  intvec v=hilb(std(j),1);
  eliminate(j,y,v);
@c example
@end smallexample
@end table
@c ref
See
@ref{hilb};
@ref{ideal};
@ref{module};
@ref{std}.
@c ref
@c ---------------------------------------
@node eval, ERROR, eliminate, Functions
@subsection eval
@cindex eval
@table @code
@item @strong{Syntax:}
@code{eval (} expression @code{)}
@item @strong{Type:}
none
@item @strong{Purpose:}
evaluates (quoted) expressions. Within a quoted expression, the
quote can be "undone" by an @code{eval} (i.e., each eval "undoes" the
effect of exactly one quote). Used only when receiving a quoted expression
from an MPfile link,
with @code{quote} and @code{write} to
prevent local evaluations  when writing to an MPtcp link.
@item @strong{Example:}
@smallexample
@c example unix_only
  link l="MPfile:w example.mp";
  ring r=0,(x,y,z),ds;
  ideal i=maxideal(3);
  ideal j=x7,x2,z;
  // compute i+j before writing, but not std
  // this writes 'std(ideal(x3,...,z))'
  write (l, quote(std(eval(i+j))));
  option(prot);
  close(l);
  // now read it in again and evaluate
  // read(l) forces to compute 'std(ideal(x3,...,z))'
  read(l);
  close(l);
@c example
@end smallexample
@end table
@c ref
See
@ref{MPfile links};
@ref{quote};
@ref{write}.
@c ref
@c ---------------------------------------
@node ERROR, example, eval, Functions
@subsection ERROR
@cindex ERROR
@table @code
@item @strong{Syntax:}
@code{ERROR (} string_expression @code{)}
@item @strong{Type:}
none
@item @strong{Purpose:}
Immediately interrupts the current computation, returns to the
top-level, and displays the argument @code{string_expression} as error
message.

@item @strong{Note:}
This should be used as an emergency, resp.@: failure, exit within procedures.

@item @strong{Example:}
@smallexample
@c example error
int i=1;
proc myError() {ERROR("Need to leave now");i=2;}
myError();
i;
@c example
@end smallexample
@end table
@c ---------------------------------------
@node example, execute, ERROR, Functions
@subsection example
@cindex example
@table @code
@item @strong{Syntax:}
@code{example} topic @code{;}
@item @strong{Purpose:}
computes an example for @code{topic}. Examples are available for all
@sc{Singular} kernel and library functions. Where available (e.g.,
within Emacs), use @code{<TAB>} completion for a list of all available
example @code{topic}s.
@item @strong{Example:}
@smallexample
example prime;
example intvec_declarations;
@end smallexample
@end table
@c ref
@ref{help}
@c ref
@c ---------------------------------------
@node execute, extgcd, example, Functions
@subsection execute
@cindex execute
@table @code
@item @strong{Syntax:}
@code{execute (} string_expression @code{)}
@item @strong{Type:}
none
@item @strong{Purpose:}
executes a string containing a sequence of @sc{Singular} commands.
@item @strong{Note:}
The command @code{return} cannot appear in the string.
@* @code{execute} should be avoided in procedures
whenever possible, since it may give rise to name conflicts.  Moreover,
such procedures cannot be precompiled (a feature which @sc{Singular} will
provide in the future).
@item @strong{Example:}
@smallexample
@c example
  ring r=32003,(x,y,z),dp;
  ideal i=x+y,z3+22y;
  write(":w save_i",i);
  ring r0=0,(x,y,z),Dp;
  string s="ideal k="+read("save_i")+";";
  s;
  execute(s); // define the ideal k
  k;
@c example
@end smallexample
@end table
@c ---------------------------------------
@node extgcd, facstd, execute, Functions
@subsection extgcd
@cindex extgcd

@table @code
@item @strong{Syntax:}
@code{extgcd (} int_expression@code{,} int_expression @code{)}
@*@code{extgcd (} poly_expression@code{,} poly_expression @code{)}
@item @strong{Type:}
list of 3 objects of the same type as the type of the arguments
@item @strong{Purpose:}
computes extended gcd: the first element is the greatest common divisor
of the two arguments,
the second and third are factors such that if @code{list L=extgcd(a,b);}
then L[1]=a*L[2]+b*L[3].
@item @strong{Note:}
Polynomials must be univariate (in the same variable) to apply @code{extgcd}.
@item @strong{Example:}
@smallexample
@c example
  extgcd(24,10);
  ring r=0,(x,y),lp;
  extgcd(x4-x6,(x2+x5)*(x2+x3));
@c example
@end smallexample
@end table
@c ref
See
@ref{gcd};
@ref{int};
@ref{poly}
@c ref
@c ---------------------------------------
@node facstd, factorize, extgcd, Functions
@subsection facstd
@cindex facstd

@table @code
@item @strong{Syntax:}
@code{facstd (} ideal_expression @code{)}
@*@code{facstd (} ideal_expression@code{,} ideal_expression @code{)}
@item @strong{Type:}
list of ideals
@item @strong{Purpose:}
returns a list of ideals computed by the factorizing Groebner basis algorithm.
@*The intersection of these ideals has the same zero-set as the input,
i.e., the radical of the intersection coincides with the radical of the input
ideal.
In many (but not all!) cases this is already a decomposition of the radical
of the ideal. (Note however, that, in general, no inclusion between the
input and output ideals holds.)
@*The second, optional argument gives a list of polynomials which define
non-zero constraints:
those ideals which contain one of the constraint polynomials are omitted
from the output list. Thus the zero set of the intersection of the output
ideals is contained in the zero set V of the first input ideal
and contains the complement in V of the zero set of the second input ideal.
@item @strong{Note:}
Not implemented for baserings over real ground fields and galois fields
(that is, only
implemented for ground fields for which @ref{factorize} is implemented).
@item @strong{Example:}
@smallexample
@c example
  ring r=32003,(x,y,z),(c,dp);
  ideal I=xyz,x2z;
  facstd(I);
  facstd(I,x);
@c example
@end smallexample
@end table
@c ref
See
@ref{std};
@ref{ring};
@ref{ideal}.
@c ref
@c ---------------------------------------
@node factorize, fetch, facstd, Functions
@subsection factorize
@cindex factorize

@table @code
@item @strong{Syntax:}
@code{factorize (} poly_expression @code{)}
@*@code{factorize (} poly_expression@code{, 0 )}
@*@code{factorize (} poly_expression@code{, 2 )}
@item @strong{Type:}
list of ideal and intvec
@*
@item @strong{Syntax:}
@code{factorize (} poly_expression@code{, 1 )}
@item @strong{Type:}
ideal
@item @strong{Purpose:}
computes the irreducible factors (as an ideal) of the polynomial
together with or without
the multiplicities (as an intvec) depending on the second argument:
@format
    0: returns factors and multiplicities, first factor is a constant.
       May also be written with only one argument.
    1: returns non-constant factors (no multiplicities).
    2: returns non-constant factors and multiplicities.
@end format
@item @strong{Note:}
Not implemented for the coefficient fields real and finite fields of
type @code{(p^n,a)}.
@item @strong{Example:}
@smallexample
@c example
  ring r=32003,(x,y,z),dp;
  factorize(9*(x-1)^2*(y+z));
  factorize(9*(x-1)^2*(y+z),1);
  factorize(9*(x-1)^2*(y+z),2);
  ring rQ=0,x,dp;
  poly f = x2+1;            // irreducible in Q[x]
  factorize(f);
  ring rQi = (0,i),x,dp;
  minpoly = i2+1;
  poly f = x2+1;            // splits into linear factors in Q(i)[x]
  factorize(f);
@c example
@end smallexample
@end table
@c ref
See
@ref{poly};
@ref{absFactorize}.
@c ref
@c ---------------------------------------
@node fetch, fglm, factorize, Functions
@subsection fetch
@cindex fetch

@table @code
@item @strong{Syntax:}
@code{fetch (} ring_name@code{,} name @code{)}
@item @strong{Type:}
number, poly, vector, ideal, module, matrix or list
(the same type as the second argument)
@item @strong{Purpose:}
maps objects between rings.
@code{fetch} is the identity map between rings and qrings,
the i-th variable of the source ring is mapped to the i-th
variable of the basering.  The coefficient fields must be compatible.
(See @ref{map} for a description of possible mappings between
different ground fields).
@*@code{fetch} offers a convenient way to change
variable names or orderings, or to map objects from a ring to a quotient
ring of that ring or vice versa.
@item @strong{Note:}
Compared with @code{imap}, @code{fetch} uses the position of the ring
variables, not their names.
@item @strong{Example:}
@smallexample
@c example
  ring r=0,(x,y,z),dp;
  ideal i=maxideal(2);
  ideal j=std(i);
  poly f=x+y2+z3;
  vector v=[f,1];
  qring q=j;
  poly f=fetch(r,f);
  f;
  vector v=fetch(r,v);
  v;
  ideal i=fetch(r,i);
  i;
  ring rr=0,(a,b,c),lp;
  poly f=fetch(q,f);
  f;
  vector v=fetch(r,v);
  v;
  ideal k=fetch(q,i);
  k;
@c example
@end smallexample
@end table
@c ref
See
@ref{imap};
@ref{map};
@ref{ring};
@ref{qring}.
@c ref
@c ---------------------------------------
@node fglm, fglmquot, fetch, Functions
@subsection fglm
@cindex fglm

@table @code
@item @strong{Syntax:}
@code{fglm (} ring_name@code{,} ideal_name @code{)}
@item @strong{Type:}
ideal
@item @strong{Purpose:}
computes for the given ideal in the given ring
a reduced Groebner basis in the current ring, by applying the so-called FGLM
(Faugere, Gianni, Lazard, Mora)  algorithm.
@*The main application is to compute a lexicographical Groebner basis
from a reduced Groebner basis with respect to a degree ordering. This
can be much faster than computing a lexicographical Groebner basis
directly.
@item @strong{Assume:}
The ideal must be zero-dimensional and given as a reduced Groebner
basis in the given ring. The monomial ordering must be global.
@item @strong{Note:}
The only permissible differences between the given ring and the current ring
are the monomial ordering and a permutation of the variables,
resp.@: parameters.
@item @strong{Example:}
@smallexample
@c example
  ring r=0,(x,y,z),dp;
  ideal i=y3+x2, x2y+x2, x3-x2, z4-x2-y;
  option(redSB);   // force the computation of a reduced SB
  i=std(i);
  vdim(i);
  ring s=0,(z,x,y),lp;
  ideal j=fglm(r,i);
  j;
@c example
@end smallexample
@end table
@c ref
See
@ref{stdfglm};
@ref{fglmquot};
@ref{ring};
@ref{qring};
@ref{std};
@ref{option};
@ref{vdim}.
@c ref
@c ---------------------------------------
@node fglmquot, filecmd, fglm, Functions
@subsection fglmquot
@cindex fglmquot

@table @code
@item @strong{Syntax:}
@code{fglmquot (} ideal_expression@code{,} poly_expression @code{)}
@item @strong{Type:}
ideal
@item @strong{Purpose:}
computes a reduced Groebner basis of the ideal quotient @code{I:p} of
a zero-dimensional ideal @code{I} and a polynomial @code{p} using
FGLM-techniques.
@item @strong{Assume:}
The ideal must be zero-dimensional and given as a reduced Groebner
basis in the given ring. The poly must be reduced with respect to the
ideal.
@item @strong{Example:}
@smallexample
@c example
  ring r=0,(x,y,z),lp;
  ideal i=y3+x2,x2y+x2,x3-x2,z4-x2-y;
  option(redSB);   // force the computation of a reduced SB
  i=std(i);
  poly p=reduce(x+yz2+z10,i);
  ideal j=fglmquot(i,p);
  j;
@c example
@end smallexample
@end table
@c ref
See
@ref{fglm};
@ref{ring};
@ref{std};
@ref{option};
@ref{quotient};
@ref{vdim}.
@c ref
@c ---------------------------------------
@node filecmd, find, fglmquot, Functions
@subsection files, input from
@cindex filecmd
@cindex <
@table @code
@item @strong{Syntax:}
@code{< "}filename@code{"}
@item @strong{Type:}
none
@item @strong{Purpose:}
input comes from the file filename. Shorthand for
@code{execute(read(filename))}.
@item @strong{Example:}
@smallexample
< "example"; //read in the file example and execute it
@end smallexample
@end table
@c ref
See
@ref{execute};
@ref{read}.
@c ref
@c ---------------------------------------
@node find, finduni, filecmd, Functions
@subsection find
@cindex find
@table @code
@item @strong{Syntax:}
@code{find (} string_expression@code{,} substring_expression @code{)}
@*@code{find (} string_expression@code{,} substring_expression@code{,} int_expression @code{)}
@item @strong{Type:}
int
@item @strong{Purpose:}
returns the first position of the substring
in the string or 0 (if not found),
@*starts the search at the position given in the 3rd argument.
@item @strong{Example:}
@smallexample
@c example
  find("Aac","a");
  find("abab","a"+"b");
  find("abab","a"+"b",2);
  find("abab","ab",3);
  find("0123","abcd");
@c example
@end smallexample
@end table
@c ref
See
@ref{string}.
@c ref
@c ---------------------------------------
@node finduni, fprintf, find, Functions
@subsection finduni
@cindex finduni
@table @code
@item @strong{Syntax:}
@code{finduni (} ideal_expression @code{)}
@item @strong{Type:}
ideal
@item @strong{Purpose:}
returns an ideal which is contained in the ideal_expression such that the i-th
generator is a univariate polynomial in the i-th ring variable.
@* The polynomials have minimal degree w.r.t.@: this property.
@item @strong{Assume:}
The ideal must be zero-dimensional and given as a reduced Groebner basis in
the current ring.
@item @strong{Example:}
@smallexample
@c example
  ring  r=0,(x,y,z), dp;
  ideal i=y3+x2,x2y+x2,z4-x2-y;
  option(redSB);  // force computation of reduced basis
  i=std(i);
  ideal k=finduni(i);
  print(k);
@c example
@end smallexample
@end table
@c ref
See
@ref{ring};
@ref{std};
@ref{option};
@ref{vdim}.
@c ref

@c ---------------------------------------
@node fprintf, freemodule, finduni, Functions
@subsection fprintf
@cindex fprintf
@c lib standard.lib:fprintf lib_fun lib_ex subsection

@c ---------------------------------------
@node freemodule, frwalk, fprintf, Functions
@subsection freemodule
@cindex freemodule

@table @code
@item @strong{Syntax:}
@code{freemodule (} int_expression @code{)}
@item @strong{Type:}
module
@item @strong{Purpose:}
creates the free module of rank n generated by
@code{gen(1)}, @dots{}, @code{gen(n)}.
@item @strong{Example:}
@smallexample
@c example
  ring r=32003,(x,y),(c,dp);
  freemodule(3);
  matrix m=freemodule(3); // generates the 3x3 unit matrix
  print(m);
@c example
@end smallexample
@end table
@c ref
See
@ref{gen};
@ref{module}.
@c ref
@c ---------------------------------------
@node frwalk, gcd, freemodule, Functions
@subsection frwalk
@cindex frwalk

@table @code
@item @strong{Syntax:}
@code{frwalk (} ring_name@code{,} ideal_name @code{)}
@*@code{frwalk (} ring_name@code{,} ideal_name @code{,} int_expression @code{)}
@item @strong{Type:}
ideal
@item @strong{Purpose:}
computes for the ideal @code{ideal_name} in the ring @code{ring_name}
a Groebner basis in the current ring, by applying the fractal walk
algorithm.
@*The main application is to compute a lexicographical Groebner basis
from a reduced Groebner basis with respect to a degree ordering. This
can be much faster than computing a lexicographical Groebner basis
directly.
@item @strong{Note:}
The only permissible difference between the ring @code{ring_name}
and the base ring active when calling @code{frwalk} is the monomial ordering.
@item @strong{Example:}
@smallexample
@c example
  ring r=0,(x,y,z),dp;
  ideal i=y3+x2, x2y+x2, x3-x2, z4-x2-y;
  i=std(i);
  ring s=0,(x,y,z),lp;
  ideal j=frwalk(r,i);
  j;
@c example
@end smallexample
@end table
@c ref
See
@ref{fglm};
@ref{groebner};
@ref{ring};
@ref{qring};
@ref{std}.
@c ref
@c ---------------------------------------
@node gcd, gen, frwalk, Functions
@subsection gcd
@cindex gcd

@table @code
@item @strong{Syntax:}
@code{gcd (} int_expression@code{,} int_expression @code{)}
@*@code{gcd (} bigint_expression@code{,} bigint_expression @code{)}
@*@code{gcd (} number_expression@code{,} number_expression @code{)}
@*@code{gcd (} poly_expression@code{,} poly_expression @code{)}
@item @strong{Type:}
the same as the type of the arguments
@item @strong{Purpose:}
computes the greatest common divisor.
@item @strong{Note:}
Not implemented for the coefficient fields real and finite fields of
type @code{(p^n,a)}.
@*The gcd of two numbers is their gcd as integer numbers or polynomials,
otherwise it is not defined.
@item @strong{Example:}
@smallexample
@c example
  gcd(2,3);
  gcd(bigint(2)^20,bigint(3)^23);     // also applicable for bigints
  typeof(_);
  ring r=0,(x,y,z),lp;
  gcd(3x2*(x+y),9x*(y2-x2));
  gcd(number(6472674604870),number(878646537247372));
@c example
@end smallexample
@end table
@c ref
See
@ref{extgcd};
@ref{int};
@ref{bigint};
@ref{number};
@ref{poly}
@c ref
@c ----------------------------------------
@node gen, getdump, gcd, Functions
@subsection gen
@cindex gen

@table @code
@item @strong{Syntax:}
@code{gen (} int_expression @code{)}
@item @strong{Type:}
vector
@item @strong{Purpose:}
returns the i-th free generator of a free module.
@item @strong{Example:}
@smallexample
@c example
  ring r=32003,(x,y,z),(c,dp);
  gen(3);
  vector v=gen(5);
  poly f=xyz;
  v=v+f*gen(4); v;
  ring rr=32003,(x,y,z),dp;
  fetch(r,v);
@c example
@end smallexample
@end table
@c ref
See
@ref{freemodule};
@ref{int};
@ref{vector}.
@c ref
@c ---------------------------------------
@node getdump, groebner, gen, Functions
@subsection getdump
@cindex getdump
@table @code
@item @strong{Syntax:}
@code{getdump (} link_expression @code{)}
@item @strong{Type:}
none
@item @strong{Purpose:}
reads the content of the entire file, resp.@: link, and restores all variables
from it. For ASCII links, @code{getdump} is equivalent to an
@code{execute(read(} link @code{))} command. For MP links,
@code{getdump} should only be used on data which were previously
@code{dump}'ed.
@item @strong{Example:}
@smallexample
@c example
  int i=3;
  dump(":w example.txt");
  kill i;
  option(noredefine);
  getdump("example.txt");
  i;
@c example
@end smallexample
@item @strong{Restrictions:}
@code{getdump} is not supported for DBM links, or for a link connecting
to @code{stdin} (standard input).
@end table
@c ref
See
@ref{link};
@ref{dump};
@ref{read}.
@c ref
@c ---------------------------------------
@node groebner, help, getdump, Functions
@subsection groebner
@cindex groebner
@c lib standard.lib:groebner lib_fun lib_ex subsection

@c @table @code
@c @item @strong{Syntax:}
@c @code{groebner (} ideal_expression @code{)}
@c @*@code{groebner (} module_expression @code{)}
@c @item @strong{Type:}
@c ideal or module
@c @item @strong{Purpose:}
@c returns a standard basis of an ideal or module with respect to the
@c monomial ordering of the basering using a heuristically chosen method.
@c @item @strong{Example:}
@c @example
@c @c example
@c   ring r=0,(a,b,c,d),lp;
@c   ideal i=a+b+c+d,ab+ad+bc+cd,abc+abd+acd+bcd,abcd-1;
@c   groebner(i);
@c @c example
@c @end example
@c @end table
@c @c ref
@c See
@c @ref{std};
@c @ref{stdfglm};
@c @ref{stdhilb}.
@c @c ref
@c ---------------------------------------
@node help, highcorner, groebner, Functions
@subsection help
@cindex help
@table @code
@item @strong{Syntax:}
@code{help;}
@*@code{help} topic @code{;}
@item @strong{Type:}
none
@item @strong{Purpose:}
displays online help information for @code{topic} using the currently
set help browser. If no @code{topic} is given, the title page of the
manual is displayed.

@item @strong{Note:}
@itemize @bullet
@cindex ?
@item
@code{?} may be used instead of @code{help}.

@item
@code{topic} can be an index entry of the @sc{Singular} manual or the
name of a (loaded) procedure which has a help section.
@item
@code{topic} may contain wildcard characters (i.e.,
@code{*} characters).
@item
If a (possibly "wildcarded") @code{topic} cannot be found (or
uniquely matched) a warning is displayed and no help information is
provided.
@item
If @code{topic} is the name of a (loaded) procedure whose help
section has changed w.r.t.@: the help available in the manual then,
instead of displaying the respective help section of the manual in the
help browser, the "newer" help section of the procedure is simply
printed to the terminal.

@item
The browser in which the help information is displayed can be either set
with the command-line option @code{--browser=<browser>} (@pxref{Command
line options}), or with the command @code{system("--browser",
"<browser>")}. Use the command @code{system("browsers");} for a list of
all available browsers. @xref{The online help system}, for more details
about help browsers.

@end itemize

@item @strong{Example:}
@smallexample
help;      // display title page of manual
help ring; // display help for 'ring'
?ringe;    // equivalent to 'help ringe;'
@expansion{} // ** No help for topic 'ringe' (not even for '*ringe*')
@expansion{} // ** Try '?;'       for general help
@expansion{} // ** or  '?Index;'  for all available help topics
?ring*;
@expansion{} //  ** No unique help for 'ring*'
@expansion{} //  ** Try one of
@expansion{} ?Rings and orderings; ?Rings and standard bases; ?ring;
@expansion{} ?ring declarations; ?ring operations; ?ring related functions;
@expansion{} ?ring.lib; ?ring_lib; ?ringtensor; ?ringweights;
help Rings and orderings;
help standard.lib;  // displays help for library 'standard.lib'
@end smallexample
@end table

@c ref
See
@ref{Format of a library};
@ref{Procedure definition};
@ref{Command line options};
@ref{system};
@ref{The online help system}.
@c ref
@c ---------------------------------------
@node highcorner, hilb, help, Functions
@subsection highcorner
@cindex highcorner
@table @code
@item @strong{Syntax:}
@code{highcorner (} ideal_expression @code{)}
@*@code{highcorner (} module_expression @code{)}
@item @strong{Type:}
poly, resp.@: vector
@item @strong{Purpose:}
returns the smallest monomial not contained in
the ideal, resp.@: module, generated by the initial terms of the given
generators. If the generators are a standard basis,
this is also the smallest monomial not contained in the ideal, resp.@: module.
@*If the ideal, resp.@: module, is not zero-dimensional, 0 is returned.
@*The command works also in global orderings, but is not very useful there.
@item @strong{Note:}
Let the ideal I be given by a standard basis. Then
@code{highcorner(I)} returns 0 iff @code{dim(I)>0} or @code{dim(I)=-1}.
Otherwise it returns the smallest monomial m not in I which has the following
properties (with
@ifinfo
x(i)
@end ifinfo
@tex
$x_i$
@end tex
the variables of the basering):
@itemize @bullet
@item
if
@ifinfo
x(i)>1 then x(i)
@end ifinfo
@tex
$x_i>1$ then $x_i$
@end tex
does not divide m (hence, m=1 if the ordering is global)
@item
given any set of generators
@ifinfo
f_1,...f_k of I, let f_i' be obtained from
f_i by deleting the terms divisible by x(i)*m for all i with x(i)<1.
Then f_1',...,f_k' generate I.
@end ifinfo
@tex
$f_1,\dots,f_k$ of I, let $f'_i$ be obtained from
$f_i$ by deleting the terms divisible by $x_i\cdot m$ for all i with $x_i<1$.
Then $f'_1,\dots,f'_k$ generate I.
@end tex
@end itemize
@item @strong{Example:}
@smallexample
@c example
ring r=0,(x,y),ds;
ideal i=x3,x2y,y3;
highcorner(std(i));
highcorner(std(ideal(1)));
@c example
@end smallexample
@end table
@c ref
See
@ref{dim};
@ref{std};
@ref{vdim}.
@c ref
@c ---------------------------------------
@node hilb, homog, highcorner, Functions
@subsection hilb
@cindex hilb
@table @code
@item @strong{Syntax:}
@code{hilb (} ideal_expression @code{)}
@*@code{hilb (} module_expression @code{)}
@*@code{hilb (} ideal_expression@code{,} int_expression @code{)}
@*@code{hilb (} module_expression@code{,} int_expression @code{)}
@*@code{hilb (} ideal_expression@code{,} int_expression @code{,} intvec_expression @code{)}
@*@code{hilb (} module_expression@code{,} int_expression @code{,} intvec_expression @code{)}
@item @strong{Type:}
none (if called with one argument)
@*intvec (if called with two or three arguments)
@item @strong{Purpose:}
computes the (weighted) Hilbert series of the ideal, resp.@: module,
defined by the leading terms of the generators of the given ideal, resp.@: module.@*
If @code{hilb} is called with one argument, then the 1st and 2nd Hilbert series
together with some additional information are displayed.@*
If @code{hilb} is called with two arguments, then the n-th Hilbert series is returned
as an intvec, where n=1,2 is the second argument.@*
If a weight vector w is a given as 3rd argument, then the Hilbert series is computed
w.r.t.@: these weights w (by default all weights are set to 1).
@item @strong{Caution:}
The last entry of the returned intvec is not part of the actual Hilbert series,
but is used in the Hilbert driven standard basis computation (see @ref{stdhilb}).
@item @strong{Note:}
If the input is homogeneous w.r.t.@: the weights and a standard basis, the result is
the (weighted) Hilbert series of the original ideal, resp.@: module.@*
@item @strong{Example:}
@smallexample
@c example
  ring R=32003,(x,y,z),dp;
  ideal i=x2,y2,z2;
  ideal s=std(i);
  hilb(s);
  hilb(s,1);
  hilb(s,2);
  intvec w=2,2,2;
  hilb(s,1,w);
@c example
@end smallexample
@end table
@c ref
See
@ref{Hilbert function};
@ref{ideal};
@ref{intvec};
@ref{module};
@ref{stdhilb};
@ref{std}.
@c ref
@c ---------------------------------------
@node homog, hres, hilb, Functions
@subsection homog
@cindex homog

@table @code
@item @strong{Syntax:}
@code{homog (} ideal_expression @code{)}
@*@code{homog (} module_expression @code{)}
@item @strong{Type:}
int
@item @strong{Purpose:}
tests for homogeneity: returns 1 for homogeneous input, 0 otherwise.
@item @strong{Note:}
If the current ring has a weighted monomial ordering,
@code{homog} tests for weighted homogeneity w.r.t. the given weights.
@item @strong{Syntax:}
@*@code{homog (} polynomial_expression@code{,} ring_variable @code{)}
@*@code{homog (} vector_expression@code{,} ring_variable @code{)}
@*@code{homog (} ideal_expression@code{,} ring_variable @code{)}
@*@code{homog (} module_expression@code{,} ring_variable @code{)}
@item @strong{Type:}
same as first argument
@item @strong{Purpose:}
homogenizes polynomials, vectors, ideals, or modules by multiplying
each monomial with a suitable power of the given ring variable.
@item @strong{Note:}
If the current ring has a weighted monomial ordering,
@code{homog} computes the weighted homogenization w.r.t. the given weights.
@*The homogenizing variable must have weight 1.
@item @strong{Example:}
@smallexample
@c example
  ring r=32003,(x,y,z),ds;
  poly s1=x3y2+x5y+3y9;
  poly s2=x2y2z2+3z8;
  poly s3=5x4y2+4xy5+2x2y2z3+y7+11x10;
  ideal i=s1,s2,s3;
  homog(s2,z);
  homog(i,z);
  homog(i);
  homog(homog(i,z));
@c example
@end smallexample
@end table
@c ref
See
@ref{poly};
@ref{vector};
@ref{ideal};
@ref{module}.
@c ref
@c ---------------------------------------
@node hres, imap, homog, Functions
@subsection hres
@cindex hres
@cindex resolution, hilbert-driven
@table @code
@item @strong{Syntax:}
@code{hres (} ideal_expression@code{,} int_expression @code{)}
@item @strong{Type:}
resolution
@item @strong{Purpose:}
computes a free resolution of an ideal using the Hilbert-driven
algorithm.

More precisely, let R be the basering and I be the given ideal.
Then @code{hres} computes a minimal free resolution of R/I
@ifinfo
@format
                    A2       A1
      ... ----> F2 ----> F1 ----> R --> R/I --> 0.
@end format
@end ifinfo
@tex
$$...\longrightarrow F_2 \buildrel{A_2}\over{\longrightarrow} F_1
\buildrel{A_1}\over{\longrightarrow} R\longrightarrow R/I
\longrightarrow 0.$$
@end tex
If the int_expression k is not zero then the computation stops after
k steps and returns a list of modules
@tex
$M_i={\tt module} (A_i)$, i=1..k.
@end tex
@ifinfo
Mi=module(Ai), i=1...k.
@end ifinfo

@code{list L=hres(I,0);} returns a list L of n modules (where n is the
number of variables of the basering) such that
@tex
${\tt L[i]}=M_i$
@end tex
@ifinfo
L[i]=M_i
@end ifinfo
in the above notation.
@item @strong{Note:}
The ideal_expression has to be homogeneous.
@* Accessing single elements of a resolution may require that some partial
computations have to be finished and may therefore take some time.
@item @strong{Example:}
@smallexample
@c example
  ring r=0,(x,y,z),dp;
  ideal I=xz,yz,x3-y3;
  def L=hres(I,0);
  print(betti(L),"betti");
  L[2];     // the first syzygy module of r/I
@c example
@end smallexample
@end table
@c ref
See
@ref{betti};
@ref{ideal};
@ref{int};
@ref{minres};
@ref{module};
@ref{mres};
@ref{res};
@ref{lres};
@ref{sres}.
@c ref
@c ---------------------------------------
@node imap, impart, hres, Functions
@subsection imap
@cindex imap

@table @code
@item @strong{Syntax:}
@code{imap (} ring_name@code{,} name @code{)}
@item @strong{Type:}
number, poly, vector, ideal, module, matrix or list
(the same type as the second argument)
@item @strong{Purpose:}
identity map on common subrings.  @code{imap} is the map between rings
and qrings with compatible ground fields which is the identity on
variables and parameters of the same name and 0 otherwise.
(See @ref{map} for a description of possible mappings between
different ground fields).
Useful for mapping from a homogenized ring to the original ring or
for mappings from/to rings with/without parameters. Compared with
@code{fetch}, @code{imap} uses the names of variables and parameters.
Unlike @code{map} and @code{fetch} @code{imap} can map parameters to variables.
@item @strong{Example:}
@smallexample
@c example
  ring r=0,(x,y,z,a,b,c),dp;
  ideal i=xy2z3a4b5+1,homog(xy2z3a4b5+1,c); i;
  ring r1=0,(a,b,x,y,z),lp;
  ideal j=imap(r,i); j;
  ring r2=(0,a,b),(x,y,z),ls;
  ideal j=imap(r,i); j;
@c example
@end smallexample
@end table
@c ref
See
@ref{fetch};
@ref{homog};
@ref{map};
@ref{qring};
@ref{ring}.
@c ref
@c ---------------------------------------
@node impart, indepSet, imap, Functions
@subsection impart
@cindex impart

@table @code
@item @strong{Syntax:}
@code{impart (} number_expression @code{)}
@item @strong{Type:}
number
@item @strong{Purpose:}
returns the imaginary part of a number in a complex ground field,
@*returns 0 otherwise.
@item @strong{Example:}
@smallexample
@c example
  ring r=(complex,i),x,dp;
  impart(1+2*i);
@c example
@end smallexample
@end table
@c ref
See
@ref{repart}.
@c ref
@c ---------------------------------------
@node indepSet, insert, impart, Functions
@subsection indepSet
@cindex indepSet

@table @code
@item @strong{Syntax:}
@code{indepSet (} ideal_expression @code{)}
@item @strong{Type:}
intvec
@item @strong{Purpose:}
computes a maximal set U of independent variables (in the sense defined in
the note below) of the ideal given by
a standard basis.  If @code{v} is the result then @code{v[i]} is 1 if and
only if the i-th variable of the ring, @code{x(i)}, is an independent
variable.  Hence, the set U consisting of all variables @code{x(i)} with
@code{v[i]=1} is a maximal independent set.

@c Indeed we compute a maximal strongly independent set U,
@c where no power of a variable from U occurs as a leading term ofs
@c a standard basis of the ideal.

@item @strong{Note:}
U is a set of independent variables for I if and only if
@tex
$I \cap K[U]=(0)$,
@end tex
@ifinfo
I intersect K[U]=(0),
@end ifinfo
i.e., eliminating the remaining variables gives (0).
U is maximal if dim(I)=#U.
@item @strong{Syntax:}
@code{indepSet (} ideal_expression, int_expression @code{)}
@item @strong{Type:}
list
@item @strong{Purpose:}
computes a list of all maximal independent sets of the leading ideal
(if the flag is 0), resp.@: of all those sets of independent variables
of the leading ideal which cannot be enlarged.
@item @strong{Example:}
@smallexample
@c example
  ring r=32003,(x,y,u,v,w),dp;
  ideal I=xyw,yvw,uyw,xv;
  attrib(I,"isSB",1);
  indepSet(I);
  eliminate(I,vw);
  indepSet(I,0);
  indepSet(I,1);
  eliminate(I,xuv);
@c example
@end smallexample
@end table
@c ref
See
@ref{std};
@ref{ideal}.
@c ref
@c ---------------------------------------
@node insert, interpolation, indepSet, Functions
@subsection insert
@cindex insert

@table @code
@item @strong{Syntax:}
@code{insert (} list_expression@code{,} expression @code{)}
@*@code{insert (} list_expression@code{,} expression@code{,} int_expression @code{)}
@item @strong{Type:}
list
@item @strong{Purpose:}
inserts a new element (expression) into a list at the beginning, or (if
called with 3 arguments) after the given position (the input is not changed).
@item @strong{Example:}
@smallexample
@c example
  list L=1,2;
  insert(L,4,2);
  insert(L,4);
@c example
@end smallexample
@end table
@c ref
See
@ref{list};
@ref{delete}.
@c ref
@c ---------------------------------------
@node interpolation, interred, insert, Functions
@subsection interpolation
@cindex interpolation

@table @code
@item @strong{Syntax:}
@code{interpolation (} list@code{,} intvec @code{)}
@item @strong{Type:}
ideal
@item @strong{Purpose:}
@code{interpolation(l,v)} computes the reduced Groebner basis of the intersection
of ideals l[1]^v[1],...,l[N]^v[N] by applying linear algebra methods.
@item @strong{Assume:}
Every ideal from the list l must be a maximal ideal of a point and should have
the following form: variable_1-coordinate_1,...,variable_n-coordinate_n, where n
is the number of variables in the ring.
@*The ring should be a polynomial ring over Zp or Q with global ordering.
@item @strong{Example:}
@smallexample
@c example
  ring r=0,(x,y),dp;
  ideal p_1=x,y;
  ideal p_2=x+1,y+1;
  ideal p_3=x+2,y-1;
  ideal p_4=x-1,y+2;
  ideal p_5=x-1,y-3;
  ideal p_6=x,y+3;
  ideal p_7=x+2,y;
  list l=p_1,p_2,p_3,p_4,p_5,p_6,p_7;
  intvec v=2,1,1,1,1,1,1;
  ideal j=interpolation(l,v);
  // generator of degree 3 gives the equation of the unique
  // singular cubic passing
  // through p_1,...,p_7 with singularity at p_1
  j;
  // computes values of generators of j at p_4, results should be 0
  subst(j,x,1,y,-2);
  // computes values of derivatives d/dx of generators at (0,0)
  subst(diff(j,x),x,0,y,0);
@c example
@end smallexample
@end table
@c ref
See
@ref{fglm};
@ref{intersect};
@ref{std};
@ref{diff};
@ref{subst}.
@c ref
@c ---------------------------------------
@node interred, intersect, interpolation, Functions
@subsection interred
@cindex interred
@table @code
@item @strong{Syntax:}
@code{interred (} ideal_expression @code{)}
@*@code{interred (} module_expression @code{)}
@item @strong{Type:}
the same as the input type
@item @strong{Purpose:}
interreduces a set of polynomials/vectors.
@*
@ifinfo
input: f_1,@dots{},f_n
@end ifinfo
@tex
input: $f_1,\dots,f_n$
@end tex
@*
@ifinfo
output: g_1,@dots{},g_s with s<=n and the properties

@*
@end ifinfo
@tex
output: $g_1,\dots,g_s$ with $s \leq n$ and the properties
@end tex
@itemize @bullet
@item
@ifinfo
(f_1,@dots{},f_n) = (g_1,@dots{},g_s)
@end ifinfo
@tex
$(f_1,\dots,f_n) = (g_1,\dots,g_s)$
@end tex
@item
@ifinfo
L(g_i)<>L(g_j) for all i<>j
@end ifinfo
@tex
$L(g_i)\neq L(g_j)$ for all $i\neq j$
@end tex
@item
in the case of a global ordering (polynomial ring) and @code{option(redSB);}:
@*
@ifinfo
L(g_i)
@end ifinfo
@tex
$L(g_i)$
@end tex
 does not divide m for all monomials m of
@ifinfo
@{g_1,@dots{},g_(i-1),g_(i+1),@dots{},g_s@}
@end ifinfo
@tex
$\{g_1,\dots,g_{i-1},g_{i+1},\dots,g_s\}$
@end tex
@item
in the case of a local or mixed ordering (localization of polynomial ring) and @code{option(redSB);}:
@* if
@ifinfo
L(g_i) | L(g_j) for any i<>j,
@end ifinfo
@tex
$L(g_i) | L(g_j)$ for any $i \neq j$,
@end tex
then
@ifinfo
ecart(g_i) > ecart(g_j)
@end ifinfo
@tex
$ecart(g_i) > ecart(g_j)$
@end tex
@end itemize
@tex
Here, $L(g)$ denotes the leading term of $g$ and
$ecart(g):=deg(g)-deg(L(g))$.
@end tex
@ifinfo

@*
Here, L(g) denotes the leading term of g and ecart(g) := deg(g)-deg(L(g)).
@end ifinfo
@item @strong{Example:}
@smallexample
@c example
  ring r=0,(x,y,z),dp;
  ideal i=zx+y3,z+y3,z+xy;
  interred(i);
  ring R=0,(x,y,z),ds;
  ideal i=zx+y3,z+y3,z+xy;
  interred(i);
@c example
@end smallexample
@end table
@c ref
See
@ref{ideal};
@ref{module};
@ref{std}.
@c ref
@c ---------------------------------------
@node intersect, jacob, interred, Functions
@subsection intersect
@cindex intersect
@table @code
@item @strong{Syntax:}
@code{intersect (} expression_list of ideal_expression @code{)}
@*@code{intersect (} expression_list of module_expression @code{)}
@item @strong{Type:}
ideal, resp.@: module
@item @strong{Purpose:}
computes the intersection of ideals, resp.@: modules.
@item @strong{Note:}
If the option @code{returnSB} is enabled then the result is a standard basis.
@item @strong{Example:}
@smallexample
@c example
  ring R=0,(x,y),dp;
  ideal i=x;
  ideal j=y;
  intersect(i,j);
  ring r=181,(x,y,z),(c,ls);
  ideal id1=maxideal(3);
  ideal id2=x2+xyz,y2-z3y,z3+y5xz;
  ideal id3=intersect(id1,id2,ideal(x,y));
  id3;
@c example
@end smallexample
@end table
@c ref
See
@ref{ideal};
@ref{module};
@ref{option}.
@c ref
@c ---------------------------------------
@node jacob, janet, intersect, Functions
@subsection jacob
@cindex jacob
@table @code
@item @strong{Syntax:}
@code{jacob (} poly_expression @code{)}
@*@code{jacob (} ideal_expression @code{)}
@*@code{jacob (} module_expression @code{)}
@item @strong{Type:}
ideal, if the input is a polynomial
@* matrix, if the input is an ideal
@* module, if the input is a module
@item @strong{Purpose:}
computes the Jacobi ideal, resp.@: Jacobi matrix, generated by all
partial derivatives of the input.
@item @strong{Note:}
In a ring with n variables, jacob of a module or
an ideal (considered as matrix with a single a row) or
a polynomial (considered as a matrix with a single entry)
is the matrix consisting of horizontally concatinated blocks (in this order):
diff(MT,var(1)), ... , diff(MT,var(n)),
where MT is the transposed input argument considered as a matrix.
@item @strong{Example:}
@smallexample
@c example
  ring R;
  poly f = x2yz + xy3z + xyz5;
  ideal i = jacob(f); i;
  matrix m = jacob(i);
  print(m);
  print(jacob(m));
@c example
@end smallexample
@end table
@c ref
See
@ref{ideal};
@ref{module};
@ref{diff};
@ref{nvars}.
@c ref
@c ---------------------------------------
@node janet, jet, jacob, Functions
@subsection janet
@cindex janet
@table @code
@item @strong{Syntax:}
@code{janet (} ideal_expression @code{)}
@*@code{janet (} ideal_expression @code{,} int_expression @code{)}
@item @strong{Type:}
ideal
@item @strong{Purpose:}
computes the Janet basis of the given ideal, resp.@:  the standard basis
if 1 is given as the second argument.
@item @strong{Remark:}
it works only with global orderings.
@item @strong{Example:}
@smallexample
@c example
  ring r=0,(x,y,z),dp;
  ideal i=x*y*z-1,x+y+z,x*y+x*z+y*z; // cyclic 3
  janet(i);
@c example
@end smallexample
@end table
@c ref
See
@ref{ideal};
@ref{groebner};
@ref{std}.
@c ref
@c ---------------------------------------
@node jet, kbase, janet, Functions
@subsection jet
@cindex jet
@table @code
@item @strong{Syntax:}
@code{jet (} poly_expression@code{,} int_expression @code{)}
@*@code{jet (} vector_expression@code{,} int_expression @code{)}
@*@code{jet (} ideal_expression@code{,} int_expression @code{)}
@*@code{jet (} module_expression@code{,} int_expression @code{)}
@*@code{jet (} poly_expression@code{,} int_expression@code{,} intvec_expression @code{)}
@*@code{jet (} vector_expression@code{,} int_expression@code{,} intvec_expression @code{)}
@*@code{jet (} ideal_expression@code{,} int_expression@code{,} intvec_expression @code{)}
@*@code{jet (} module_expression@code{,} int_expression@code{,} intvec_expression @code{)}
@*@code{jet (} poly_expression@code{,} poly_expression@code{,} int_expression @code{)}
@*@code{jet (} vector_expression@code{,} poly_expression@code{,} int_expression @code{)}
@*@code{jet (} ideal_expression@code{,} matrix_expression@code{,} int_expression @code{)}
@*@code{jet (} module_expression@code{,} matrix_expression@code{,} int_expression @code{)}
@item @strong{Type:}
the same as the type of the first argument
@item @strong{Purpose:}
deletes from the first argument all terms of degree bigger than the second argument.
@*If a third argument @code{w} of type intvec is given, the degree is replaced by the weighted degree defined by @code{w}.
@*If a second argument @code{u} of type poly or matrix is given, the first argument @code{p} is replaced by @code{p/u}.
@item @strong{Example:}
@smallexample
@c example
  ring r=32003,(x,y,z),(c,dp);
  jet(1+x+x2+x3+x4,3);
  poly f=1+x+x2+xz+y2+x3+y3+x2y2+z4;
  jet(f,3);
  intvec iv=2,1,1;
  jet(f,3,iv);
  // the part of f with (total) degree >3:
  f-jet(f,3);
  // the homogeneous part of f of degree 2:
  jet(f,2)-jet(f,1);
  // the part of maximal degree:
  jet(f,deg(f))-jet(f,deg(f)-1);
  // the absolute term of f:
  jet(f,0);
  // now for other types:
  ideal i=f,x,f*f;
  jet(i,2);
  vector v=[f,1,x];
  jet(v,1);
  jet(v,0);
  v=[f,1,0];
  module m=v,v,[1,x2,z3,0,1];
  jet(m,2);
  ring rs=0,x,ds;
  // 1/(1+x) till degree 5
  jet(1,1+x,5);
@c example
@end smallexample
@end table
@c ref
See
@ref{deg};
@ref{int};
@ref{intvec};
@ref{ideal};
@ref{module};
@ref{poly};
@ref{vector}.
@c ref
@c ---------------------------------------
@node kbase, kernel, jet, Functions
@subsection kbase
@cindex kbase
@table @code
@item @strong{Syntax:}
@code{kbase (} ideal_expression @code{)}
@*@code{kbase (} module_expression @code{)}
@*@code{kbase (} ideal_expression@code{,} int_expression@code{)}
@*@code{kbase (} module_expression@code{,} int_expression@code{)}
@item @strong{Type:}
the same as the input type of the first argument
@item @strong{Purpose:}
with one argument:
computes a vector space basis (consisting of monomials)
of the quotient ring by the ideal,
resp.@: of a free module by the module, in case it is finite dimensional
and if the input is a standard basis with respect to the ring ordering.
If the input is not a standard basis, the leading terms of the input are
used and the result may have no meaning.
@*With two arguments: computes the part of a vector space basis of the
respective quotient with degree of the monomials equal to the
second argument. Here, the quotient does not need to be finite dimensional.
If an attribute@code{isHomog} (of type @code{intvec} is present,
it is used as module weight.
@item @strong{Example:}
@smallexample
@c example
  ring r=32003,(x,y,z),ds;
  ideal i=x2,y2,z;
  kbase(std(i));
  i=x2,y3,xyz;  // quotient not finite dimensional
  kbase(std(i),2);
@c example
@end smallexample
@end table
@c ref
See
@ref{ideal};
@ref{module};
@ref{vdim}.
@c ref
@c ---------------------------------------
@node kernel, kill, kbase, Functions
@subsection kernel
@cindex kernel

@table @code
@item @strong{Syntax:}
@code{kernel (} ring_name@code{,} map_name @code{)}
@*@code{preimage (} ring_name@code{,} ideal_expression @code{)}
@item @strong{Type:}
ideal
@item @strong{Purpose:}
returns the kernel of a given map.
@*
The second argument has to be a map from the basering to the given ring
(or an ideal defining such a map).
@item @strong{Example:}
@smallexample
@c example
  ring r1=32003,(x,y,z,w),lp;
  ring r=32003,(x,y,z),dp;
  ideal i=x,y,z;
  map f=r1,i;
  setring r1;
  // the kernel of f
  kernel(r,f);
@c example
@end smallexample
@end table
@c ref
See
@ref{preimage};
@ref{map};
@ref{ideal};
@ref{ring};
@ref{alg_kernel};
@ref{hom_kernel};
@ref{modulo}.
@c ref
@c ---------------------------------------
@node kill, killattrib, kernel, Functions
@subsection kill
@cindex kill
@table @code
@item @strong{Syntax:}
@code{kill } name @code{}
@*@code{kill } list_of_names @code{}
@item @strong{Type:}
none
@item @strong{Purpose:}
deletes objects.
@item @strong{Example:}
@smallexample
@c example error
  int i=3;
  ring r=0,x,dp;
  poly p;
  listvar();
  kill i,r;
  // the variable `i` does not exist any more
  i;
  listvar();
@c example
@end smallexample
@end table
@c ref
See
@ref{defined};
@ref{general_lib};
@ref{names}
@c ref
@c ---------------------------------------
@node killattrib, koszul, kill, Functions
@subsection killattrib
@cindex killattrib
@table @code
@item @strong{Syntax:}
@code{killattrib (} name@code{,} string_expression @code{)}
@item @strong{Type:}
none
@item @strong{Purpose:}
deletes the attribute given as the second argument.
@item @strong{Example:}
@smallexample
@c example
  ring r=32003,(x,y),lp;
  ideal i=maxideal(1);
  attrib(i,"isSB",1);
  attrib(i);
  killattrib(i,"isSB");
  attrib(i);
@c example
@end smallexample
@end table
@c ref
See
@ref{attrib};
@ref{option}.
@c ref
@c ---------------------------------------
@node koszul, laguerre, killattrib, Functions
@subsection koszul
@cindex koszul
@table @code
@item @strong{Syntax:}
@code{koszul (} int_expression@code{,} int_expression @code{)}
@*@code{koszul (} int_expression@code{,} ideal_expression @code{)}
@*@code{koszul (} int_expression@code{,} int_expression@code{,} ideal_expression @code{)}
@item @strong{Type:}
matrix
@item @strong{Purpose:}
@code{koszul(d,n)} computes a matrix of the Koszul relations of degree d of
the first n ring variables.

@code{koszul(d,id)} computes a matrix of the Koszul relations of degree d of
the generators of the ideal @code{id}.

@code{koszul(d,n,id)} computes a matrix of the Koszul relations of degree d of
the first n generators of the ideal @code{id}.

@item @strong{Note:}
@code{koszul(1,id),koszul(2,id),...} form a complex, that is, the product
of the matrices @code{koszul(i,id)} and @code{koszul(i+1,id)} equals zero.
@item @strong{Example:}
@smallexample
@c example
  ring r=32003,(x,y,z),dp;
  print(koszul(2,3));
  ideal I=xz2+yz2+z3,xyz+y2z+yz2,xy2+y3+y2z;
  print(koszul(1,I));
  print(koszul(2,I));
  print(koszul(2,I)*koszul(3,I));
@c example
@end smallexample
@end table
@c ref
See
@ref{int};
@ref{matrix}.
@c ref
@c ---------------------------------------
@node laguerre, lead, koszul, Functions
@subsection laguerre
@cindex laguerre
@table @code
@item @strong{Syntax:}
@code{laguerre (} poly_expression@code{,} int_expression@code{,} int_expression @code{)}
@item @strong{Type:}
list
@item @strong{Purpose:}
computes all complex roots of a univariate polynomial using Laguerre's
algorithm. The second argument defines the precision of the fractional part
if the ground field is the field of rational numbers, otherwise it will be
ignored. The third argument (can be 0, 1 or 2) gives the number of extra runs
for Laguerre's algorithm (with corrupted roots), leading to better results.
@item @strong{Note:}
If the ground field is the field of complex numbers, the elements of the
list are of type number, otherwise of type string.
@item @strong{Example:}
@smallexample
@c example
ring rs1=0,(x,y),lp;
poly f=15x5+x3+x2-10;
laguerre(f,10,2);
@c example
@end smallexample
@end table
@c @c ref
@c @c ref
@c -------------------------------------------------
@node lead, leadcoef, laguerre, Functions
@subsection lead
@cindex lead
@table @code
@item @strong{Syntax:}
@code{lead (} poly_expression @code{)}
@*@code{lead (} vector_expression @code{)}
@*@code{lead (} ideal_expression @code{)}
@*@code{lead (} module_expression @code{)}
@item @strong{Type:}
the same as the input type
@item @strong{Purpose:}
returns the leading (or initial) term(s) of a polynomial, a vector,
resp.@: of the generators of an ideal or module with respect
to the monomial ordering.
@cindex IN
@item @strong{Note:}
@code{IN} may be used instead of @code{lead}.
@item @strong{Example:}
@smallexample
@c example
  ring r=32003,(x,y,z),(c,ds);
  poly f=2x2+3y+4z3;
  vector v=[2x10,f];
  ideal i=f,z;
  module m=v,[0,0,2+x];
  lead(f);
  lead(v);
  lead(i);
  lead(m);
  lead(0);
@c example
@end smallexample
@end table
@c ref
See
@ref{leadcoef};
@ref{leadexp};
@ref{leadmonom};
@ref{poly};
@ref{vector};
@ref{ideal};
@ref{module}.
@c ref
@c -------------------------------------------------
@node leadcoef, leadexp, lead, Functions
@subsection leadcoef
@cindex leadcoef
@table @code
@item @strong{Syntax:}
@code{leadcoef (} poly_expression @code{)}
@*@code{leadcoef (} vector_expression @code{)}
@item @strong{Type:}
number
@item @strong{Purpose:}
returns the leading (or initial) coefficient of a polynomial or a vector
with respect to the monomial ordering.
@item @strong{Example:}
@smallexample
@c example
  ring r=32003,(x,y,z),(c,ds);
  poly f=x2+y+z3;
  vector v=[2*x^10,f];
  leadcoef(f);
  leadcoef(v);
  leadcoef(0);
@c example
@end smallexample
@end table
@c ref
See
@ref{lead};
@ref{leadexp};
@ref{leadmonom};
@ref{number}
@ref{poly};
@ref{vector}.
@c ref
@c -------------------------------------------------
@node leadexp, leadmonom, leadcoef, Functions
@subsection leadexp
@cindex leadexp
@table @code
@item @strong{Syntax:}
@code{leadexp (} poly_expression @code{)}
@*@code{leadexp (} vector_expression @code{)}
@item @strong{Type:}
intvec
@item @strong{Purpose:}
returns the exponent vector of the leading monomial of a polynomial or a vector.
In the case of a vector the last component is the index in the vector.
@item @strong{Example:}
@smallexample
@c example
  ring r=32003,(x,y,z),(c,ds);
  poly f=x2+y+z3;
  vector v=[2*x^10,f];
  leadexp(f);
  leadexp(v);
  leadexp(0);
@c example
@end smallexample
@end table
@c ref
See
@ref{lead};
@ref{leadcoef};
@ref{leadmonom};
@ref{intvec};
@ref{poly};
@ref{vector}.
@c ref
@c -------------------------------------------------
@node leadmonom, LIB, leadexp, Functions
@subsection leadmonom
@cindex leadmonom
@table @code
@item @strong{Syntax:}
@code{leadmonom (} poly_expression @code{)}
@*@code{leadmonom (} vector_expression @code{)}
@item @strong{Type:}
the same as the input type
@item @strong{Purpose:}
returns the leading monomial of a polynomial or a vector as a polynomial
or vector whose coefficient is one.
@item @strong{Example:}
@smallexample
@c example
  ring r=32003,(x,y,z),(c,ds);
  poly f=2x2+3y+4z3;
  vector v=[0,2x10,f];
  leadmonom(f);
  leadmonom(v);
  leadmonom(0);
@c example
@end smallexample
@end table

@c ref
See
@ref{lead};
@ref{leadcoef};
@ref{leadexp};
@ref{intvec};
@ref{poly};
@ref{vector}.
@c ref
@c ---------------------------------------
@node LIB, lift, leadmonom, Functions
@subsection LIB
@cindex LIB
@table @code
@item @strong{Syntax:}
@code{LIB} string_expression@code{;}
@item @strong{Type:}
none
@item @strong{Purpose:}
reads a library of procedures from a file. In contrast to the command
@code{load}, the procedures from the library are added to the package
@code{Top} as well as the package corresponding to the library.
If the given filename does
not start with @kbd{.} or @kbd{/} and cannot be located in the current
directory, each directory contained in the library
@code{SearchPath} is searched for file of this name.
@xref{Loading of a library}, for more info on @code{SearchPath}.

@item @strong{Note on standard.lib:}
Unless  @sc{Singular} is started with the @code{--no-stdlib} option, the
library @code{standard.lib} is automatically loaded at start-up time.

@item @strong{Example:}
@smallexample
@c example
  option(loadLib); // show loading of libraries

                   // the names of the procedures of inout.lib
  LIB "inout.lib"; // are now known to Singular
@c example
@end smallexample
@end table
@c ref
See
@ref{Command line options};
@ref{Procedures and libraries};
@ref{SINGULAR libraries};
@ref{proc};
@ref{standard_lib};
@ref{string};
@ref{load};
@ref{package};
@ref{system}.
@c ref
@c -------------------------------------------------
@node lift, liftstd, LIB, Functions
@subsection lift
@cindex lift
@table @code
@item @strong{Syntax:}
@code{lift (} ideal_expression@code{,} subideal_expression @code{)}
@*@code{lift (} module_expression@code{,} submodule_expression @code{)}
@*@code{lift (} ideal_expression@code{,} subideal_expression@code{,} matrix_name @code{)}
@*@code{lift (} module_expression@code{,} submodule_expression@code{,} matrix_name @code{)}
@item @strong{Type:}
matrix
@item @strong{Purpose:}
computes the transformation matrix which expresses the generators of a
submodule in terms of the generators of a module.  Uses different
algorithms for modules which are, resp.@: are not, represented by a
standard basis.
@* More precisely, if  @code{m} is the
module (or ideal), @code{sm} the submodule (or ideal),
and @code{T} the transformation matrix returned by
lift, then @code{matrix(sm)*U = matrix(m)*T}
and @code{module(sm*U) = module(matrix(m)*T)}
(resp.@: @code{ideal(sm) = ideal(matrix(m)*T)}),
where @code{U} is a diagonal matrix of units.
@*@code{U} is always the unity matrix if the basering is a polynomial ring
(not power series ring). @code{U} is stored in the optional third argument.
@item @strong{Note:}
Gives a warning if @code{sm} is not a submodule.
@item @strong{Example:}
@smallexample
@c example
  ring r=32003,(x,y,z),(dp,C);
  ideal m=3x2+yz,7y6+2x2y+5xz;
  poly f=y7+x3+xyz+z2;
  ideal i=jacob(f);
  matrix T=lift(i,m);
  matrix(m)-matrix(i)*T;
@c example
@end smallexample
@end table
@c ref
See
@ref{division};
@ref{ideal};
@ref{module}.
@c ref
@c -----------------------------------------
@node liftstd, listvar, lift, Functions
@subsection liftstd
@cindex liftstd
@table @code
@item @strong{Syntax:}
@code{liftstd (} ideal_expression@code{,} matrix_name @code{)}
@*@code{liftstd (} module_expression@code{,} matrix_name @code{)}
@item @strong{Type:}
ideal or module
@item @strong{Purpose:}
returns a standard basis of an ideal or module and the transformation
matrix from the given ideal, resp.@: module, to the standard basis.
@*That is, if @code{m} is the ideal or module, @code{sm} the standard
basis returned by @code{liftstd}, and @code{T} the transformation matrix
then @code{matrix(sm)=matrix(m)*T} and @code{sm=ideal(matrix(m)*T)},
resp.@: @code{sm=module(matrix(m)*T)}.
@item @strong{Example:}
@smallexample
@c example
  ring R=0,(x,y,z),dp;
  poly f=x3+y7+z2+xyz;
  ideal i=jacob(f);
  matrix T;
  ideal sm=liftstd(i,T);
  sm;
  print(T);
  matrix(sm)-matrix(i)*T;
@c example
@end smallexample
@end table
@c ref
See
@ref{ideal};
@ref{ring};
@ref{option};
@ref{std};
@ref{matrix}.
@c ref
@c ---------------------------------------
@node listvar, lres, liftstd, Functions
@subsection listvar
@cindex listvar
@table @code
@item @strong{Syntax:}
@code{listvar (} [package] @code{)}
@*@code{listvar (} [package@code{,}] type @code{)}
@*@code{listvar (} [package@code{,}] ring_name @code{)}
@*@code{listvar (} [package@code{,}] name @code{)}
@*@code{listvar (} [package@code{,}] @code{all )}
@item @strong{Type:}
none
@item @strong{Purpose:}
lists all (user-)defined names in the current namespace:
@itemize @bullet
@item @code{listvar()}: all currently visible names except procedures,
@item @code{listvar(}type@code{)}: all currently visible names of the given
type,
@item @code{listvar(}ring_name@code{)}: all names which belong to the given
ring,
@item @code{listvar(}name@code{)}: the object with the given name,
@item @code{listvar(all)}: all names except procedures.
@end itemize
The current basering is marked with a @code{*}.  The nesting level of
variables in procedures is shown in square brackets.

package can be @code{Current}, @code{Top} or any other
identifier of type package.
@item @strong{Example:}
@smallexample
@c example error
  proc t1 { }
  proc t2 { }
  ring s;
  poly ss;
  ring r;
  poly f=x+y+z;
  int i=7;
  ideal I=f,x,y;
  listvar();
  listvar(r);
  listvar(t1);
  listvar(proc);
  LIB "poly.lib";
  listvar(Poly);
@c example
@end smallexample
@end table
@c ref
See
@ref{Names in procedures};
@ref{Names};
@ref{defined};
@ref{names};
@ref{package};
@ref{type}.
@c ref
@c ---------------------------------------
@node lres, maxideal, listvar, Functions
@subsection lres
@cindex lres
@cindex resolution, La Scala's method

@table @code
@item @strong{Syntax:}
@code{lres (} ideal_expression@code{,} int_expression @code{)}
@item @strong{Type:}
resolution
@item @strong{Purpose:}
computes a free resolution of an ideal using LaScala's algorithm.

More precisely, let R be the basering and I be the given ideal.
Then @code{lres} computes a minimal free resolution of R/I
@ifinfo
@format
                    A2       A1
      ... ----> F2 ----> F1 ----> R --> R/I --> 0.
@end format
@end ifinfo
@tex
$$...\longrightarrow F_2 \buildrel{A_2}\over{\longrightarrow} F_1
\buildrel{A_1}\over{\longrightarrow} R\longrightarrow R/I
\longrightarrow 0.$$
@end tex
If the int_expression k is not zero then the computation stops after
k steps and returns a list of modules
@tex
$M_i={\tt module}(A_i)$, i=1..k.
@end tex
@ifinfo
Mi=module(Ai), i=1..k.
@end ifinfo

@code{list L=lres(I,0);} returns a list L of n modules (where n is the
number of variables of the basering) such that
@tex
${\tt L[i]}=M_i$
@end tex
@ifinfo
L[i]=M_i
@end ifinfo
in the above notation.
@item @strong{Note:}
The ideal_expression has to be homogeneous.
@*Accessing single elements of a resolution may require that some partial
computations have to be finished and may therefore take some time.
@item @strong{Example:}
@smallexample
@c example
  ring r=0,(x,y,z),dp;
  ideal I=xz,yz,x3-y3;
  def L=lres(I,0);
  print(betti(L),"betti");
  L[2];     // the first syzygy module of r/I
@c example
@end smallexample
@end table
@c ref
See
@ref{betti};
@ref{ideal};
@ref{int};
@ref{minres};
@ref{module};
@ref{mres};
@ref{res};
@ref{hres};
@ref{sres}.
@c ref
@c ---------------------------------------
@node maxideal, memory, lres, Functions
@subsection maxideal
@cindex maxideal
@table @code
@item @strong{Syntax:}
@code{maxideal (} int_expression @code{)}
@item @strong{Type:}
ideal
@item @strong{Purpose:}
returns the power given by int_expression of the maximal ideal
generated by all ring variables (@code{maxideal(i)=1} for @code{i<=0}).
@item @strong{Example:}
@smallexample
@c example
  ring r=32003,(x,y,z),dp;
  maxideal(2);
@c example
@end smallexample
@end table
@c ref
See
@ref{ideal};
@ref{ring}.
@c ref
@c ---------------------------------------
@node  memory, minbase, maxideal, Functions
@subsection memory
@cindex memory
@cindex memory managment
@table @code
@item @strong{Syntax:}
@code{memory (} int_expression @code{)}
@item @strong{Type:}
bigint
@item @strong{Purpose:}
returns statistics concerning the memory management:
@itemize @bullet
@item @code{memory(0)} is the number of active (used) bytes,
@item @code{memory(1)} is the number of bytes allocated from the
operating system,
@item @code{memory(2)} is the maximal number of bytes ever allocated from the
operating system during the current @sc{Singular} session.
@end itemize
@item @strong{Note:}
To monitor the memory usage during ongoing computations the option
@code{mem} should be set (using the command @code{option(mem);}, see
also @ref{option}).
@item @strong{Example:}
@smallexample
@c example
  ring r=0,(x(1..500)),dp;
  poly p=(x(1)+x(500))^50;
  proc ReportMemoryUsage()
  {  "Memory currently used by SINGULAR     :",memory(0),"Byte (",
     int(memory(0)/1023), "KByte)" +newline+
     "Memory currently allocated from system:",memory(1), "Byte (",
     int(memory(1)/1023), "KByte)";
     "Maximal memory allocated from system  :",memory(2), "Byte (",
     int(memory(2)/1023), "KByte)";
  }
  ReportMemoryUsage();
  kill p;
  ReportMemoryUsage(); // less memory used: p killed
  kill r;
  ReportMemoryUsage(); // even less memory: r killed
@c example
@end smallexample
@end table
@c ref
See
@ref{option};
@ref{system}.
@c ref
@c ---------------------------------------
@node minbase, minor, memory, Functions
@subsection minbase
@cindex minbase
@table @code
@item @strong{Syntax:}
@code{minbase (} ideal_expression @code{)}
@*@code{minbase (} module_expression @code{)}
@item @strong{Type:}
the same as the type of the argument
@item @strong{Purpose:}
returns a minimal set of generators of an ideal, resp.@: module, if the
input is
either homogeneous or if the ordering is local.
@item @strong{Example:}
@smallexample
@c example
  ring r=181,(x,y,z),(c,ls);
  ideal id2=x2+xyz,y2-z3y,z3+y5xz;
  ideal id4=maxideal(3)+id2;
  size(id4);
  minbase(id4);
@c example
@end smallexample
@end table
@c ref
See
@ref{mstd}.
@c ref
@c ---------------------------------------
@node minor, minres, minbase, Functions
@subsection minor
@cindex minor
@table @code
@item @strong{Syntax:}
@code{minor (} matrix_expression@code{,} int_expression @code{)}
@*@code{minor (} matrix_expression@code{,} int_expression@code{,} ideal_expression @code{)}
@item @strong{Type:}
ideal
@item @strong{Purpose:}
returns the set of all minors (=subdeterminants) of the given size of a matrix.
The optional third argument must be a standard basis.
If a third argument is given, the computations will be performed modulo that
ideal.
@item @strong{Example:}
@smallexample
@c example
  ring r=0,(x(1..5)),ds;
  matrix m[2][4]=x(1..4),x(2..5);
  print(m);
  ideal j=minor(m,2);
  j;
  minor(m,2,std(ideal(x(1))));
@c example
@end smallexample
@end table
@c ref
See
@ref{det}.
@c ref
@c ---------------------------------------
@node  minres, modulo, minor, Functions
@subsection minres
@cindex minres
@table @code
@item @strong{Syntax:}
@code{minres (} list_expression @code{)}
@item @strong{Type:}
list
@item @strong{Syntax:}
@code{minres (} resolution_expression @code{)}
@item @strong{Type:}
resolution
@item @strong{Purpose:}
minimizes a free resolution of an ideal or module
given by the list_expression, resp.@: resolution_expression.
@item @strong{Example:}
@smallexample
@c example
  ring r1=32003,(x,y),dp;
  ideal i=x5+xy4,x3+x2y+xy2+y3;
  resolution rs=lres(i,0);
  rs;
  list(rs);
  minres(rs);
  list(rs);
@c example
@end smallexample
@end table
@c ref
See
@ref{res};
@ref{mres};
@ref{sres}.
@c ref
@c --------------------------------------
@node modulo, monitor, minres, Functions
@subsection modulo
@cindex modulo
@table @code
@item @strong{Syntax:}
@code{modulo (} ideal_expression@code{,} ideal_expression @code{)}
@*@code{modulo (} module_expression@code{,} module_expression @code{)}
@item @strong{Type:}
module
@item @strong{Purpose:}
@code{modulo(h1,h2)}
@ifinfo
represents h1/(h1 intersect h2) (isomorphic to (h1+h2)/h2)
@end ifinfo
@tex
represents $h_1/(h_1 \cap h_2) \cong (h_1+h_2)/h_2$
@end tex
where
@tex
$h_1$ and $h_2$
@end tex
@ifinfo
h1 and h2
@end ifinfo
are considered as submodules of the same free module
@tex
$R^l$
@end tex
@ifinfo
R^l
@end ifinfo
(l=1 for ideals). Let
@tex
$H_1$, resp.\ $H_2$,
@end tex
@ifinfo
H1 and H2
be the matrices of size l x k, resp.@: l x m, having the columns of
@end ifinfo
@tex
be the matrices of size $l \times k$, resp.\ $l \times m$, having the
generators of $h_1$, resp.\ $h_2$,
@end tex
@ifinfo
h1, resp.@: h2,
@end ifinfo
as columns.
@c @*
@c @tex
@c $R^k \buildrel{H_1}\over{\rightarrow} R^l
@c \buildrel{H_2}\over{\leftarrow} R^m$
@c @end tex
@c @ifinfo
@c @smallexample
@c      H1         H2
@c R^k ----> R^l <---- R^m
@c @end smallexample
@c @end ifinfo
Then
@tex
$h_1/(h_1 \cap h_2) \cong R^k / ker(\overline{H_1})$
@end tex
@ifinfo
@format
                                                    __
      h1/(h1 intersect h2) is isomorphic to R^k/ker(H1)

@*
@end format
@end ifinfo
where
@tex
$\overline{H_1}: R^k \rightarrow R^l/Im(H_2)=R^l/h_2$
is the induced map.
@end tex
@ifinfo
@format
         __
         H1: R^k ----> R^l/Im(H2)=R^l/h2 is the induced map.

@*
@end format
@end ifinfo
@*@code{modulo(h1,h2)} returns generators of
the kernel of this induced map.
@item @strong{Note:}
If for at least one of @code{h1} or @code{h2} the attribute @code{"isHomog"} is
set, @code{modulo(h1,h2)} also sets the attribute @code{"isHomog"}
(if possible, that is, if the weights are compatible).
@item @strong{Example:}
@smallexample
@c example
  ring r;
  ideal h1=x,y,z;
  ideal h2=x;
  module m=modulo(h1,h2);
  print(m);
@c example
@end smallexample
@end table
@c ref
See
@ref{syz};
@ref{hom_kernel}.
@c ref
@c ---------------------------------------
@node monitor, mpresmat, modulo, Functions
@subsection monitor
@cindex monitor
@table @code
@item @strong{Syntax:}
@code{monitor (} link_expression @code{)}
@*@code{monitor (} link_expression@code{,} string_expression @code{)}
@item @strong{Type:}
none
@item @strong{Purpose:}
controls the recording of all user input and/or program output into a file.
The second argument describes what to log: @code{"i"} means input,
@code{"o"} means output, @code{"io"} for both.
@*The default for the second argument is @code{"i"}.
@*Each @code{monitor} command closes a previous monitor file
and opens the file given by the first string expression.
@*@code{monitor ("")} turns off recording.
@item @strong{Example:}
@smallexample
@c example no_comp
  monitor("doe.tmp","io"); // log input and output to doe.tmp
  ring r;
  poly f=x+y+z;
  int i=7;
  ideal I=f,x,y;
  monitor("");             // stop logging:
  // doe.tmp contains now all input and output from the example above
@c example
@end smallexample
@end table
@c ref
See
@ref{link expressions}.
@c ref
@c ---------------------------------------
@node mpresmat, mres, monitor, Functions
@subsection mpresmat
@cindex mpresmat
@table @code
@item @strong{Syntax:}
@code{mpresmat (} ideal_expression@code{,} int_expression @code{)}
@item @strong{Type:}
module
@item @strong{Purpose:}
computes the multipolynomial resultant matrix of the input system.
Uses the sparse resultant matrix method of Gelfand, Kapranov and Zelevinsky
(second parameter = 0) or the resultant matrix method of Macaulay
(second parameter = 1).
@item @strong{Note:}
When using the resultant matrix method of Macaulay the input system must be
homogeneous. The number of elements in the input system must be the number of
variables in the basering plus one.
@item @strong{Example:}
@smallexample
@c example
  ring rsq=(0,s,t,u),(x,y),lp;
  ideal i=s+tx+uy,x2+y2-10,x2+xy+2y2-16;
  module m=mpresmat(i,0);
  print(m);
@c example
@end smallexample
@end table
@c ref
See
@ref{uressolve}.
@c ref
@c ---------------------------------------
@node  mres, mstd, mpresmat, Functions
@subsection mres
@cindex mres
@table @code
@item @strong{Syntax:}
@code{mres (} ideal_expression@code{,} int_expression @code{)}
@*@code{mres (} module_expression@code{,} int_expression @code{)}
@item @strong{Type:}
resolution
@item @strong{Purpose:}
computes a minimal free resolution of an ideal or module M with the
standard basis method. More precisely, let A=@code{matrix}(M), then @code{mres}
computes a free resolution of
@ifinfo
coker(A)=F0/M
@format
                    A2       A1
      ... ----> F2 ----> F1 ----> F0 --> F0/M --> 0.
@end format
@end ifinfo
@tex
$coker(A)=F_0/M$
$$...\longrightarrow F_2 \buildrel{A_2}\over{\longrightarrow} F_1
\buildrel{A_1}\over{\longrightarrow} F_0\longrightarrow F_0/M
\longrightarrow 0,$$
@end tex
where the columns of the matrix
@tex
$A_1$
@end tex
@ifinfo
A1
@end ifinfo
are a minimal set of generators
of M if the basering is local or if M is homogeneous.
If the int expression k is not zero, then the computation stops after k steps
and returns a list of modules
@tex
$M_i={\tt module}(A_i)$, i=1...k.
@end tex
@ifinfo
Mi=module(Ai), i=1...k.
@end ifinfo
@*@code{mres(M,0)} returns a resolution consisting of at most n+2 modules,
where n is the number of variables of the basering.
Let @code{list L=mres(M,0);}
 then @code{L[1]} consists of a minimal set of generators of the input, @code{L[2]}
consists of a minimal set of generators for the first syzygy module of
@code{L[1]}, etc., until @code{L[p+1]}, such that
@ifinfo
L[i]<>0 for i<=p,
@end ifinfo
@tex
${\tt L[i]}\neq 0$ for $i \le p$,
@end tex
 but @code{L[p+1]}, the first syzygy module of @code{L[p]},
is 0 (if the basering is not a qring).
@item @strong{Note:}
Accessing single elements of a resolution may require that some partial
computations have to be finished and may therefore take some time.
@item @strong{Example:}
@smallexample
@c example
  ring r=31991,(t,x,y,z,w),ls;
  ideal M=t2x2+tx2y+x2yz,t2y2+ty2z+y2zw,
          t2z2+tz2w+xz2w,t2w2+txw2+xyw2;
  resolution L=mres(M,0);
  L;
  // projective dimension of M is 5
@c example
@end smallexample
@end table
@c ref
See
@ref{ideal};
@ref{hres};
@ref{lres};
@ref{module};
@ref{res};
@ref{sres}.
@c ref
@c ---------------------------------------
@node  mstd, mult, mres, Functions
@subsection mstd
@cindex mstd
@table @code
@item @strong{Syntax:}
@code{mstd (} ideal_expression @code{)}
@*@code{mstd (} module_expression @code{)}
@item @strong{Type:}
list
@item @strong{Purpose:}
returns a list whose first entry is a standard basis for the ideal, resp.@:
module, and whose second entry is a generating set for the
ideal, resp.@: module.
If the ideal/module is homogeneous or the ordering is local,
this second entry is a minimal generating set.
@item @strong{Example:}
@smallexample
@c example
  ring r=0,(x,y,z,t),dp;
  poly f=x3+y4+z6+xyz;
  ideal j=jacob(f),f;
  j=homog(j,t);j;
  mstd(j);
@c example
@end smallexample
@end table
@c ref
See
@ref{ideal};
@ref{module};
@ref{std};
@ref{minbase}.
@c ref
@c ---------------------------------------
@node mult, nameof, mstd, Functions
@subsection mult
@cindex mult
@table @code
@item @strong{Syntax:}
@code{mult (} ideal_expression @code{)}
@*@code{mult (} module_expression @code{)}
@item @strong{Type:}
int
@item @strong{Purpose:}
computes the degree of the monomial ideal, resp.@: module, generated by
the leading monomials of the input.
@*If the input is a standard basis of a homogeneous ideal
then it returns the degree of this ideal.
@*If the input is a standard basis of an ideal in a (local)
ring with respect to a local degree ordering
then it returns the multiplicity of the ideal (in the sense of Samuel,
with respect to the maximal ideal).
@item @strong{Example:}
@smallexample
@c example
  ring r=32003,(x,y),ds;
  poly f=(x3+y5)^2+x2y7;
  ideal i=std(jacob(f));
  mult(i);
  mult(std(f));
@c example
@end smallexample
@end table
@c ref
See
@ref{ideal};
@ref{std};
@ref{degree};
@ref{vdim};
@ref{dim}.
@c ref
@c ---------------------------------------
@node nameof, names, mult, Functions
@subsection nameof
@cindex nameof
@table @code
@item @strong{Syntax:}
@code{nameof (} expression @code{)}
@item @strong{Type:}
string
@item @strong{Purpose:}
returns the name of an expression as string.
@item @strong{Example:}
@smallexample
@c example error
  int i=9;
  string s=nameof(i);
  s;
  nameof(s);
  nameof(i+1); //returns the empty string:
  nameof(basering);
  basering;
  ring r;
  nameof(basering);
@c example
@end smallexample
@end table
@c ref
See
@ref{typeof};
@ref{names};
@ref{reservedName}.
@c ref
@c ---------------------------------------
@node names, ncols, nameof, Functions
@subsection names
@cindex names
@table @code
@item @strong{Syntax:}
@code{names ( )}
@*@code{names (} ring_name @code{)}
@*@code{names (} package_name @code{)}
@item @strong{Type:}
list of strings
@item @strong{Purpose:}
returns the names of all user-defined variables which are ring independent
(this includes the names of  procedures) or, in the second case, which
belong to the given ring.

package_name can be @code{Current}, @code{Top} or any other
identifier of type package.
@item @strong{Example:}
@smallexample
@c example
  int i=9;
  ring r;
  poly f;
  package p;
  int p::j;
  poly g;
  setring r;
  list l=names();
  l[1..3];
  names(r);
  names(p);
@c example
@end smallexample
@end table
@c ref
See
@ref{nameof};
@ref{reservedName}.
@c ref
@c ---------------------------------------
@node ncols, npars, names, Functions
@subsection ncols
@cindex ncols
@table @code
@item @strong{Syntax:}
@code{ncols (} matrix_expression @code{)}
@*@code{ncols (} intmat_expression @code{)}
@*@code{ncols (} ideal_expression @code{)}
@item @strong{Type:}
int
@item @strong{Purpose:}
returns the number of columns of a matrix or an intmat or the number of
given generators of the ideal, including zeros.
@item @strong{Note:}
@code{size(}ideal@code{)} counts the number of generators
which are different from zero. (Use @code{nrows} to get the number of rows
of a given matrix or intmat.)
@item @strong{Example:}
@smallexample
@c example
  ring r;
  matrix m[5][6];
  ncols(m);
  ideal i=x,0,y;
  ncols(i);
  size(i);
@c example
@end smallexample
@end table
@c ref
See
@ref{matrix};
@ref{nrows};
@ref{size}.
@c ref
@c ---------------------------------------
@node npars, nres, ncols, Functions
@subsection npars
@cindex npars
@table @code
@item @strong{Syntax:}
@code{npars (} ring_name @code{)}
@item @strong{Type:}
int
@item @strong{Purpose:}
returns the number of parameters of a ring.
@item @strong{Example:}
@smallexample
@c example
  ring r=(23,t,v),(x,a(1..7)),lp;
  // the parameters are t,v
  npars(r);
@c example
@end smallexample
@end table
@c ref
See
@ref{par};
@ref{parstr};
@ref{ring}.
@c ref
@c ---------------------------------------
@node  nres, nrows, npars, Functions
@subsection nres
@cindex nres
@table @code
@item @strong{Syntax:}
@code{nres (} ideal_expression@code{,} int_expression @code{)}
@*@code{nres (} module_expression@code{,} int_expression @code{)}
@item @strong{Type:}
resolution
@item @strong{Purpose:}
computes a free resolution of an ideal or module M which is minimized from
the second module on (by the standard basis method).

More precisely, let
@tex
$A_1$=matrix(M),
@end tex
@ifinfo
A1=matrix(M),
@end ifinfo
then @code{nres} computes a free resolution of
@ifinfo
coker(A1)=F0/M
@format
                    A2       A1
      ... ----> F2 ----> F1 ----> F0 --> F0/M --> 0.
@end format
@end ifinfo
@tex
$coker(A_1)=F_0/M$
$$...\longrightarrow F_2 \buildrel{A_2}\over{\longrightarrow} F_1 \buildrel{A_1}\over{\longrightarrow} F_0\longrightarrow F_0/M\longrightarrow 0,$$
@end tex
@*where the columns of the matrix
@tex
$A_1$
@end tex
@ifinfo
A1
@end ifinfo
are the given set of generators of M.
If the int expression k is not zero then the computation stops after k steps
and returns a list of modules
@tex
$M_i={\tt module}(A_i)$, i=1..k.
@end tex
@ifinfo
Mi=module(Ai), i=1..k.
@end ifinfo
@*@code{nres(M,0)} returns a list of n modules where n is the number of
variables of the basering.
Let @code{list L=nres(M,0);} then @code{L[1]=M} is identical to the input,
@code{L[2]} is a minimal set of generators for the first syzygy
module of  @code{L[1]}, etc.
@ifinfo
(L[i]=M_i
@end ifinfo
@tex
(${\tt L[i]}=M_i$
@end tex
in the notations from above).
@item @strong{Example:}
@smallexample
@c example
  ring r=31991,(t,x,y,z,w),ls;
  ideal M=t2x2+tx2y+x2yz,t2y2+ty2z+y2zw,
          t2z2+tz2w+xz2w,t2w2+txw2+xyw2;
  resolution L=nres(M,0);
  L;
@c example
@end smallexample
@end table
@c ref
See
@ref{ideal};
@ref{lres};
@ref{hres};
@ref{module};
@ref{mres};
@ref{res};
@ref{resolution};
@ref{sres}.
@c ref
@c ---------------------------------------
@node nrows, nvars, nres, Functions
@subsection nrows
@cindex nrows
@table @code
@item @strong{Syntax:}
@code{nrows (} matrix_expression @code{)}
@*@code{nrows (} intmat_expression @code{)}
@*@code{nrows (} intvec_expression @code{)}
@*@code{nrows (} module_expression @code{)}
@*@code{nrows (} vector_expression @code{)}
@item @strong{Type:}
int
@item @strong{Purpose:}
returns the number of rows of a matrix, an intmat or an intvec, resp.@:
the minimal rank of a free module in which the given module or
vector lives (the index of the last non-zero component).
@item @strong{Note:}
Use @code{ncols} to get the number of columns of a given matrix or intmat.
@item @strong{Example:}
@smallexample
@c example
  ring R;
  matrix M[2][3];
  nrows(M);
  nrows(freemodule(4));
  module m=[0,0,1];
  nrows(m);
  nrows([0,x,0]);
@c example
@end smallexample
@end table
@c ref
See
@ref{gen};
@ref{matrix};
@ref{module};
@ref{vector};
@ref{ncols}.
@c ref
@c ---------------------------------------
@node nvars, open, nrows, Functions
@subsection nvars
@cindex nvars
@table @code
@item @strong{Syntax:}
@code{nvars (} ring_name @code{)}
@item @strong{Type:}
int
@item @strong{Purpose:}
returns the number of variables of a ring.
@item @strong{Example:}
@smallexample
@c example
  ring r=(23,t,v),(x,a(1..7)),ls;
  // the variables are x,a(1),...,a(7)
  nvars(r);
@c example
@end smallexample
@end table
@c ref
See
@ref{npars};
@ref{ring};
@ref{var};
@ref{varstr}.
@c ref
@c ---------------------------------------
@node open, option, nvars, Functions
@subsection open
@cindex open
@table @code
@item @strong{Syntax:}
@code{open (} link_expression @code{)}
@item @strong{Type:}
none
@item @strong{Purpose:}
opens a link.
@item @strong{Example:}
@smallexample
link l="MPtcp:launch";
open(l);  // start SINGULAR "server" on localhost in batchmode
close(l); // shut down SINGULAR server
@end smallexample
@end table
@c ref
See
@ref{link};
@ref{close}.
@c ref
@c ---------------------------------------
@node option, ord, open, Functions
@subsection option
@cindex option
@table @code
@item @strong{Syntax:}
@code{option ()}
@item @strong{Type:}
string
@item @strong{Purpose:}
lists all defined options.
@*
@item @strong{Syntax:}
@code{option (} option_name @code{)}
@item @strong{Type:}
none
@item @strong{Purpose:}
sets an option.
@item @strong{Note:}
To disable an option, use the prefix @code{no}.
@*
@item @strong{Syntax:}
@code{option ( get )}
@item @strong{Type:}
intvec
@item @strong{Purpose:}
dumps the state of all options to an intvec.
@*
@item @strong{Syntax:}
@code{option ( set,} intvec_expression @code{)}
@item @strong{Type:}
none
@item @strong{Purpose:}
restores the state of all options from an intvec (produced by
@code{option(get)}).
@sp 1
@item @strong{Values:}
The following options are used to manipulate the behavior of
computations and act like boolean switches. Use the prefix @code{no} to
disable an option. Notice that some options are ring dependent and reset
to their default values on a change of the current basering.
@table @asis
@c ---------
@item @code{none}
@c ---------
@cindex none, option
turns off all options (including the @code{prompt} option).
@c ---------
@item @code{returnSB}
@cindex returnSB, option
the functions @code{syz}, @code{intersect}, @code{quotient},
@code{modulo} return a standard base instead of a generating set if
@code{returnSB} is set. This option should not be used for @code{lift}.
@c ---------
@item @code{fastHC}
@cindex fastHC, option
tries to the find the highest corner of the staircase (HC) as fast as
possible during a standard basis computation (only used for local
orderings).
@c ---------
@c @item @code{interrupt}
@c allows fast interruption of standard basis computation
@c ---------
@item @code{intStrategy}
@cindex intStrategy, option
avoids division of coefficients during standard basis
computations. This option is ring dependent. By default, it is set for
rings with characteristic 0 and not set for all other rings.
@c ---------
@item @code{lazy}
@cindex lazy, option
uses a more lazy approach in std computations,
which was used in Singular version before 2-0
(and which may lead to faster or slower computations, depending on the example)
@item @code{length}
@cindex length, option
select shorter reduceers in std computations,
@c ---------
@c @item @code{minRes}
@c @cindex minRes, option
@c special (additional) minimizing during computations (@code{res}, @code{mres}),
@c @*assumes homogeneous case and degree-compatible ordering.
@c ---------
@item @code{notRegularity}
@cindex notRegularity, option
disables the regularity bound for @code{res} and @code{mres} (see
@ref{regularity}).
@c ---------
@item @code{notSugar}
@cindex notSugar, option
disables the sugar strategy during standard basis computation.
@anchor{option(prot)}
@c ---------
@item @code{notBuckets}
@cindex notBuckets, option
disables the bucket representation of polynomials during standard basis
computations. This option usually decreases the memory usage but
increases the computation time. It should only be set for
memory-critical standard basis computations.
@c ---------
@item @code{oldStd}
@cindex oldStd, option
uses a more lazy approach in std computations,
which was used in Singular version before 2-0
(and which may lead to faster or slower computations, depending on the example)
@c ---------
@item @code{prot}
@cindex prot, option
@cindex protocol of computations
@cindex progress watch
shows protocol information indicating the
progress during the following computations:
@code{facstd},
@code{fglm},
@code{groebner},
@code{lres},
@code{mres},
@code{minres},
@code{mstd},
@code{res},
@code{slimgb},
@code{sres},
@code{std},
@code{stdfglm},
@code{stdhilb},
@code{syz}.
@anchor{option(redSB)}
See below for more details.
@c ---------
@item @code{redSB}
@cindex redSB, option
@cindex reduced standard basis
computes a reduced standard basis in any standard basis computation.
@c ---------
@item @code{redTail}
@cindex redTail, option
reduction of the tails of polynomials during standard basis
computations. This option is ring dependent. By default, it is set for
rings with global degree orderings and not set for all other rings.
@c ---------
@item @code{redThrough}
@cindex redThrough, option
for inhomogenous input, polynomial reductions during standard basis
computations are never postponed, but always finished through. This option
is ring   dependent. By default, it is set for rings with global degree
orderings and not set for all other rings.
@c ---------
@item @code{sugarCrit}
@cindex sugarCrit, option
uses criteria similar to the homogeneous case to keep more useless pairs.
@c ---------
@item @code{weightM}
@cindex weightM, option
automatically computes suitable weights for the weighted ecart and the
weighted sugar method.
@c ---------
@end table
@*
The following options, which also control computations, are special,
since they are not manipulated by the @code{option} command but by a
direct assignment of a value. Reset the option by assigning the value 0;
the command @code{option(none)} will not reset them! If there is a
non-zero value assigned, the command @code{option()} prints the option.
@table @asis
@item @code{multBound}
a multiplicity bound is set (see @ref{multBound}).
@item @code{degBound}
a degree bound is set (see @ref{degBound}).
@end table
@*
The last set of options controls the output of @sc{Singular}:
@table @asis
@item @code{Imap}
@cindex Imap, option
shows the mapping of variables with the fetch and imap commands.
@item @code{loadLib}
@cindex loadLib, option
shows loading of libraries (set by default).
@item @code{debugLib}
@cindex debugLib, option
warns about syntax errors during loading of libraries.
@item @code{loadProc}
@cindex loadProc, option
shows loading of procedures from libraries.
@item @code{mem}
@cindex mem, option
shows memory usage in square brackets (see @ref{memory}).
@item @code{prompt}
@cindex prompt, option
shows prompt (@code{>}, resp.@: @code{.}) if ready for input (default).
@item @code{reading}
@cindex reading, option
shows the number of characters read from a file.
@item @code{redefine}
@cindex redefine, option
warns about variable redefinitions (set by default).
@item @code{usage}
@cindex usage, option
shows correct usage in error messages (set by default).
@end table
@item @strong{Example:}
@smallexample
@c example
  option(prot);
  option();
  option(notSugar);
  option();
  option(noprot);
  option();
  option(none);
  option();
  ring r=0,x,dp;
  degBound=22;
  option();
  intvec i=option(get);
  option(none);
  option(set,i);
  option();
@c example
@end smallexample
@end table

@*The output reported on @code{option(prot)} has the following meaning:
@multitable @columnfractions .01 .14 .11 .65

@item @tab (command)
@tab (character) @tab (meaning)
@item @tab @code{facstd}
@tab @code{F} @tab found a new factor
@item @tab @tab @tab all other characters: like the output of @code{std} and @code{reduce}
@item @tab @tab @tab
@item @tab @code{fglm}
@tab @code{.} @tab basis monomial found
@item @tab @tab @code{+} @tab edge monomial found
@item @tab @tab @code{-} @tab border monomial found
@item @tab @tab @tab
@item @tab @code{groebner} @tab @tab all characters: like the output of @code{std}/@code{slimgb}
@item @tab @tab @tab
@item @tab @code{lres}
@tab @code{.} @tab minimal syzygy found
@item @tab @tab n @tab slanted degree, i.e., row of Betti matrix
@item @tab @tab @code{(mn)} @tab calculate in module n
@item @tab @tab @code{g} @tab pair found giving reductum and syzygy
@item @tab @tab @tab
@item @tab @code{mres}
@tab @code{[d]}
@tab computations of the d-th syzygy module
@item @tab @tab @tab all other characters: like the output of @code{std}
@item @tab @tab @tab
@item @tab @code{minres}
@tab @code{[d]}
@tab minimizing of the d-th syzygy module
@item @tab @tab @tab
@item @tab @code{mstd} @tab @tab all characters: like the output of @code{std}
@item @tab @tab @tab
@item @tab @code{reduce}
@tab @code{r} @tab reduced a leading term
@item @tab @tab @code{t} @tab reduced a non-leading term
@item @tab @code{res}
@tab @code{[d]}
@tab computations of the d-th syzygy module
@item @tab @tab @tab all other characters: like the output of @code{std}
@item @tab @tab @tab
@item @tab @code{slimgb}
@tab @code{M[n,m]} @tab parallel reduction of n elements with m non-zero output elements
@item @tab @tab @code{.} @tab postponed a reduction of a pair/S-polynomial
@item @tab @tab @code{b} @tab exchange of a reductor by a 'better' one
@item @tab @tab @code{e} @tab a new reductor with non-minimal leading term
@item @tab @tab @code{(n)} @tab n critical pairs are still to be reduced
@item @tab @tab d @tab the maximal degree of the leading terms is currently d
@item @tab @tab @tab
@item @tab @code{sres}
@tab @code{.} @tab syzygy found
@item @tab @tab @code{(n)} @tab n elements remaining
@item @tab @tab @code{[n]} @tab finished module n
@item @tab @tab @tab
@item @tab @code{std}
@tab @code{[m:n]}
@tab internal ring change to poly representation with exponent bound
m and n words in exponent vector
@item @tab @tab @code{s} @tab found a new element of the standard basis
@item @tab @tab @code{-} @tab reduced a pair/S-polynomial to 0
@item @tab @tab @code{.} @tab postponed a reduction of a pair/S-polynomial
@item @tab @tab @code{h} @tab used Hilbert series criterion
@item @tab @tab @code{H(d)} @tab found a 'highest corner' of degree d, no need to consider higher degrees
@item @tab @tab @code{(n)} @tab n critical pairs are still to be reduced
@item @tab @tab @code{(S:n)} @tab doing complete reduction of n elements
@item @tab @tab d @tab the degree of the leading terms is currently d
@item @tab @tab @tab
@item @tab @code{stdfglm} @tab @tab all characters in first part: like the output of @code{std}
@item @tab @tab @tab all characters in second part: like the output of @code{fglm}
@item @tab @tab @tab
@item @tab @code{stdhilb} @tab @tab all characters: like the output of @code{std}
@item @tab @tab @tab
@item @tab @code{syz} @tab @tab all characters: like the output of @code{std}
@end multitable


@c ref
See
@ref{degBound};
@ref{multBound};
@ref{std}.
@c ref
@c ---------------------------------------
@node ord, ordstr, option, Functions
@subsection ord
@cindex ord
@table @code
@item @strong{Syntax:}
@code{ord (} poly_expression @code{)}
@*@code{ord (} vector_expression @code{)}
@item @strong{Type:}
int
@item @strong{Purpose:}
returns the (weighted) degree of
the initial term of a polynomial or a vector;
the weights are the weights used for the first block of the ring ordering.
@item @strong{Note:}
@code{ord(0)} is @code{-1}.
@*In a global degree ordering @code{ord} is the same as @code{deg}.
@item @strong{Example:}
@smallexample
@c example
  ring r=7,(x,y),wp(2,3);
  ord(0);
  poly f=x2+y3;  // weight on y is 3
  ord(f),deg(f);
  ring R=7,(x,y),ws(2,3);
  poly f=x2+y3;
  ord(f),deg(f);
  vector v=[x2,y];
  ord(v),deg(v);
@c example
@end smallexample
@end table
@c ref
See
@ref{deg};
@ref{poly};
@ref{vector}.
@c ref
@c ---------------------------------------
@node ordstr, par, ord, Functions
@subsection ordstr
@cindex ordstr
@table @code
@item @strong{Syntax:}
@code{ordstr (} ring_name @code{)}
@item @strong{Type:}
string
@item @strong{Purpose:}
returns the description of the monomial ordering of the ring.
@item @strong{Example:}
@smallexample
@c example
  ring r=7,(x,y),wp(2,3);
  ordstr(r);
@c example
@end smallexample
@end table
@c ref
See
@ref{ring};
@ref{varstr};
@ref{parstr};
@ref{charstr}.
@c ref
@c ---------------------------------------
@node par, pardeg, ordstr, Functions
@subsection par
@cindex par
@table @code
@item @strong{Syntax:}
@code{par (} int_expression @code{)}
@item @strong{Type:}
number
@item @strong{Purpose:}
@code{par(n);} returns the n-th parameter of the basering.
@item @strong{Example:}
@smallexample
@c example
  ring r=(0,a,b,c),(x,y,z),dp;
  char(r);  // char to get the characteristic
  par(2);   // par to get the n-th parameter
@c example
@end smallexample
@end table
@c ref
See
@ref{char};
@ref{npars};
@ref{parstr};
@ref{ring};
@ref{var}.
@c ref
@c ---------------------------------------
@node pardeg, parstr, par, Functions
@subsection pardeg
@cindex pardeg
@table @code
@item @strong{Syntax:}
@code{pardeg (} number_expression @code{)}
@item @strong{Type:}
int
@item @strong{Purpose:}
returns the degree of a number considered as a polynomial in the ring parameters.
@item @strong{Example:}
@smallexample
@c example
  ring r=(0,a,b,c),(x,y,z),dp;
  pardeg(a^2*b);
@c example
@end smallexample
@end table
@c ref
See
@ref{deg};
@ref{number};
@ref{ring};
@ref{var}.
@c ref
@c ---------------------------------------
@node parstr, preimage, pardeg, Functions
@subsection parstr
@cindex parstr
@table @code
@item @strong{Syntax:}
@code{parstr (} ring_name @code{)}
@*@code{parstr (} int_expression @code{)}
@*@code{parstr (} ring_name@code{,} int_expression @code{)}
@item @strong{Type:}
string
@item @strong{Purpose:}
returns the list of parameters of the ring as a string
or the name of the n-th parameter where n is given by the int_expression.
@*If the ring_name is omitted, the basering is used, thus
@code{parstr(n)} is equivalent to @code{parstr(basering,n)}.
@item @strong{Example:}
@smallexample
@c example
  ring r=(7,a,b,c),(x,y),wp(2,3);
  parstr(r);
  parstr(2);
  parstr(r,3);
@c example
@end smallexample
@end table
@c ref
See
@ref{charstr};
@ref{npars};
@ref{ordstr};
@ref{par}
@ref{ring};
@ref{varstr}.
@c ref
@c ---------------------------------------
@node preimage, prime, parstr, Functions
@subsection preimage
@cindex preimage

@table @code
@item @strong{Syntax:}
@code{preimage (} map @code{)}
@*@code{preimage (} ring_name@code{,} map_name@code{,} ideal_name @code{)}
@*@code{preimage (} ring_name@code{,} ideal_expression@code{,} ideal_name @code{)}
@item @strong{Type:}
ring
@*ideal
@item @strong{Purpose:}
returns the source ring of a map (in the first case) or
@*returns the preimage of an ideal under a given map.
@*
The second argument has to be a map from the basering to the given ring
(or an ideal defining such a map),
and the ideal has to be an ideal in the given ring.
@item @strong{Note:}
As @code{preimage} is handling ideals (not polynomials), the result of a preimage
calculation of a principal ideal, whose generator is not in the image of the map,
is the zero ideal.
@item @strong{Example:}
@smallexample
@c example
  ring r1=32003,(x,y,z,w),lp;
  ring r=32003,(x,y,z),dp;
  ideal i=x,y,z;
  ideal i1=x,y;
  ideal i0=0;
  map f=r1,i;
  nameof (preimage (f));
  setring r1;
  ideal i1=preimage(r,f,i1);
  i1;
  // the kernel of f
  preimage(r,f,i0);
  // or, use:
  kernel(r,f);
@c example
@end smallexample
@end table
@c ref
See
@ref{kernel};
@ref{map};
@ref{ideal};
@ref{ring}.
@c ref
@c ---------------------------------------
@node prime, print, preimage, Functions
@subsection prime
@cindex prime
@table @code
@item @strong{Syntax:}
@code{prime (} int_expression @code{)}
@item @strong{Type:}
int
@item @strong{Purpose:}
returns the largest prime less than or equal to the argument;
@*returns 2 for all arguments smaller than 3.
@item @strong{Example:}
@smallexample
@c example
  prime(320000);
  prime(32004);
  prime(0);
  prime(-1);
@c example
@end smallexample
@end table
@c ref
See
@ref{int};
@ref{general_lib}.
@c ref
@c ---------------------------------------
@node print, printf, prime, Functions
@subsection print
@cindex print
@table @code
@item @strong{Syntax:}
@code{print (} expression @code{)}
@*@code{print (} expression@code{, "betti" )}
@*@code{print (} expression@code{,} format_string @code{)}
@item @strong{Type:}
none (for the first two calling sequences), resp.@:
@*string (for the last calling sequence)
@item @strong{Purpose:}
The first form prints the expression to the terminal and has no return
value. Use the format string @code{%p} to print into a string (see
below).
@*The second form prints the graded Betti numbers from a matrix
and has no return value.
The Betti numbers are printed in a matrix-like format where the entry
@tex
$d$ in row $i$ and column $j$
@end tex
@ifinfo
d in row i and column j
@end ifinfo
is the minimal number of generators in
degree
@tex
$i+j$ of the $j$-th
@end tex
@ifinfo
i+j of the j-th
@end ifinfo
 syzygy module of
@tex
$R^n/M$ (the 0th and 1st syzygy module of $R^n/M$ is $R^n$ and $M$, resp.).
@end tex
@ifinfo
R^n/M (the 0th and 1st syzygy module of R^n/M are R^n and M, resp.).
@end ifinfo
@*The last form returns the printed output as a string. The format
string determines which format to use to generate the string.

The following format strings are supported:
@table @code
@item "%s"
returns @code{string(} expression @code{)}
@item "%2s"
similar to @code{"%s"}, except that newlines are inserted after every
comma and at the end
@item "%l"
similar to @code{"%s"}, except that each object is embraced by its type
such that it can be directly used for "cutting and pasting"
@item "%2l"
similar to @code{"%l"}, except that newlines are inserted after every
comma and at the end
@item "%;"
returns the string equivalent to typing @code{expression;}
@item "%t"
returns the string equivalent to typing @code{type expression;}
@item "%p"
returns the string equivalent to typing @code{print(expression);}
@item "%b"
returns the string equivalent to typing @code{print(expression, "betti");}
@item "betti"
is not a format string
@end table
@item @strong{Example:}
@smallexample
@c example
  ring r=0,(x,y,z),dp;
  module m=[1,y],[0,x+z];
  m;
  print(m);  // the columns generate m
  string s=print(m,"%s"); s;
  s=print(m,"%2s"); s;
  s=print(m,"%l"); s;
  s=print(m,"%;"); s;
  s=print(m,"%t"); s;
  s=print(m,"%p"); s;
  intmat M=betti(mres(m,0));
  print(M,"betti");
  list l=r,M;
  s=print(l,"%s"); s;
  s=print(l,"%2s"); s;
  s=print(l,"%l"); s;
@c example
@end smallexample
@end table
@c ref
See
@ref{dbprint};
@ref{short};
@ref{type};
@ref{betti};
@ref{string type cast};
@ref{sprintf};
@ref{printf};
@ref{fprintf};
@ref{Type conversion and casting}.
@c ref

@c ---------------------------------------
@node printf, prune, print, Functions
@subsection printf
@cindex printf
@c lib standard.lib:printf lib_fun lib_ex subsection

@c ---------------------------------------
@node prune, qhweight, printf, Functions
@subsection prune
@cindex prune
@table @code
@item @strong{Syntax:}
@code{prune (} module_expression @code{)}
@item @strong{Type:}
module
@item @strong{Purpose:}
returns the module minimally embedded in a free module such that the
corresponding factor modules are isomorphic.
@item @strong{Note:}
If for the input module the attribute @code{"isHomog"} is
set, @code{prune} also sets the attribute @code{"isHomog"}.
@item @strong{Example:}
@smallexample
@c example
  ring r=0,(x,y,z),dp;
  module m=gen(1),gen(3),[x,y,0,z],[x+y,0,0,0,1];
  print(m);
  print(prune(m));
@c example
@end smallexample
@end table
@c ref
See
@ref{module}.
@c ref
@c ---------------------------------------
@c @node qhweight, quot, prune, Functions
@node qhweight, quote, prune, Functions
@subsection qhweight
@cindex qhweight
@table @code
@item @strong{Syntax:}
@code{qhweight (} ideal_expression @code{)}
@item @strong{Type:}
intvec
@item @strong{Purpose:}
computes the weight vector of the variables for a quasihomogeneous ideal.
If the input is not weighted homogeneous, an intvec of zeros is returned.
@item @strong{Example:}
@smallexample
@c example
  ring h1=32003,(t,x,y,z),dp;
  ideal i=x4+y3+z2;
  qhweight(i);
@c example
@end smallexample
@end table
@c ref
See
@ref{ideal};
@ref{intvec};
@ref{weight}.
@c ref

@c ---------------------------------------
@c @node quot, quote, qhweight, Functions
@c @subsection quot
@c @cindex quot
@c @c lib standard.lib:quot lib_fun lib_ex subsection

@c ---------------------------------------
@c @node quote, quotient, quot, Functions
@node quote, quotient, qhweight, Functions
@subsection quote
@cindex quote
@table @code
@item @strong{Syntax:}
@code{quote (} expression @code{)}
@item @strong{Type:}
none
@item @strong{Purpose:}
prevents expressions from evaluation. Used only in connections with write to
MPfile links, prevents evaluation of an expression before sending it to an other
@sc{Singular} process.
Within a quoted expression, the
quote can be "undone" by an @code{eval} (i.e., each eval "undoes" the
effect of exactly one quote).
@item @strong{Example:}
@smallexample
@c example unix_only
  link l="MPfile:w example.mp";
  ring r=0,(x,y,z),ds;
  ideal i=maxideal(3);
  ideal j=x7,x2,z;
  option(prot);
  // compute i+j before writing, but not std
  write (l, quote(std(eval(i+j))));
  close(l);
  // now read it in again and evaluate:
  read(l);
  close(l);
@c example
@end smallexample
@end table
@c ref
See
@ref{eval};
@ref{write};
@ref{MPfile links}.
@c ref
@c ---------------------------------------
@node quotient, random, quote, Functions
@subsection quotient
@cindex quotient
@table @code
@item @strong{Syntax:}
@code{quotient (} ideal_expression@code{,} ideal_expression @code{)}
@*@code{quotient (} module_expression@code{,} module_expression @code{)}
@item @strong{Type:}
ideal
@item @strong{Syntax:}
@code{quotient (} module_expression@code{,} ideal_expression @code{)}
@item @strong{Type:}
module
@item @strong{Purpose:}
computes the ideal quotient, resp.@: module quotient. Let @code{R} be the
basering, @code{I,J} ideals and @code{M} a module in
@ifinfo
R^n.
@end ifinfo
@tex
${\tt R}^n$.
@end tex
Then
@itemize
@item
@code{quotient(I,J)}=
@ifinfo
@{a in R | aJ in I @}
@end ifinfo
@tex
$\{a \in R \mid aJ \subset I\}$,
@end tex
@item
@code{quotient(M,J)}=
@ifinfo
@{b in R | bJ in M @}.
@end ifinfo
@tex
$\{b \in R^n \mid bJ \subset M\}$.
@end tex
@end itemize
@item @strong{Example:}
@smallexample
@c example
ring r=181,(x,y,z),(c,ls);
ideal id1=maxideal(3);
ideal id2=x2+xyz,y2-z3y,z3+y5xz;
ideal id6=quotient(id1,id2);
id6;
quotient(id2,id1);
module m=x*freemodule(3),y*freemodule(2);
ideal id3=x,y;
quotient(m,id3);
@c example
@end smallexample
@end table
@c ref
See
@ref{fglmquot};
@ref{ideal};
@ref{module}.
@c ref
@c ---------------------------------------
@node random, read, quotient, Functions
@subsection random
@cindex random
@table @code
@item @strong{Syntax:}
@code{random (} int_expression@code{,} int_expression @code{)}
@item @strong{Type:}
int
@item @strong{Purpose:}
returns a random integer between the integer given by the first
int_expression and the one given by the second int_expression.
@*
@item @strong{Syntax:}
@code{random (} int_expression@code{,} int_expression@code{,} int_expression @code{)}
@item @strong{Type:}
intmat
@item @strong{Purpose:}
returns a random intmat where the size is given by the second (number of
rows) and third argument (number of columns). The absolute value of the
entries of the matrix is smaller than or equal to the integer given as
the first argument.
@item @strong{Note:}
The random generator can be set to a startvalue with
the function @code{system}, resp.@: by a command line option.
@item @strong{Example:}
@smallexample
@c example
  random(1,1000);
  random(1,2,3);
  system("random",210);  // start random generator with 210
  random(-1000,1000);
  random(-1000,1000);
  system("random",210);
  random(-1000,1000);    // the same random values again
@c example
@end smallexample
@end table
@c ref
See
@ref{Command line options};
@ref{int};
@ref{intmat};
@ref{system}.
@c ref
@c ---------------------------------------
@node read, reduce, random, Functions
@subsection read
@cindex read
@table @code
@item @strong{Syntax:}
@code{read (} link_expression @code{)}
@*for DBM links:
@*@code{read (} link_expression @code{)}
@*@code{read (} link_expression@code{,} string_expression @code{)}
@item @strong{Type:}
any
@item @strong{Purpose:}
reads data from a link.
@*For ASCII links, the content of the entire
file is returned as one string. If the ASCII link is the empty string,
@code{read} reads from standard input.
@*For MP links, one expression is read
from the link and returned after evaluation. See @ref{MP links}.
@*For MPtcp links the @code{read} command blocks as long as there is no
data to be read from the link. The @code{status} command can be used to
check whether or not there is data to be read.
@*For DBM links, a @code{read} with one argument returns the value of
the next entry in the data base, and a @code{read} with two arguments
returns the value to the key given as the second argument from the data
base. See @ref{DBM links}.
@item @strong{Example:}
@smallexample
@c example
  ring r=32003,(x,y,z),dp;
  ideal i=x+y,z3+22y;
  // write the ideal i to the file save_i
  write(":w save_i",i);
  ring r0=0,(x,y,z),Dp;
  // create an ideal k equal to the content
  // of the file save_i
  string s="ideal k="+read("save_i")+";";
  execute(s);
  k;
@c example
@end smallexample
@end table
@c ref
See
@ref{execute};
@ref{getdump};
@ref{link};
@ref{status};
@ref{write}.
@c ref
@c ---------------------------------------
@node reduce, regularity, read, Functions
@subsection reduce
@cindex reduce
@cindex NF
@table @code
@item @strong{Syntax:}
@code{reduce (} poly_expression@code{,} ideal_expression @code{)}
@*@code{reduce (} poly_expression@code{,} ideal_expression@code{,} int_expression @code{)}
@*@code{reduce (} poly_expression@code{,} poly_expression@code{,} ideal_expression @code{)}
@*@code{reduce (} vector_expression@code{,} ideal_expression @code{)}
@*@code{reduce (} vector_expression@code{,} ideal_expression@code{,} int_expression @code{)}
@*@code{reduce (} vector_expression@code{,} module_expression @code{)}
@*@code{reduce (} vector_expression@code{,} module_expression@code{,} int_expression @code{)}
@*@code{reduce (} vector_expression@code{,} poly_expression@code{,} module_expression @code{)}
@*@code{reduce (} ideal_expression@code{,} ideal_expression @code{)}
@*@code{reduce (} ideal_expression@code{,} ideal_expression@code{,} int_expression @code{)}
@*@code{reduce (} ideal_expression@code{,} matrix_expression@code{,} ideal_expression @code{)}
@*@code{reduce (} module_expression@code{,} ideal_expression @code{)}
@*@code{reduce (} module_expression@code{,} ideal_expression@code{,} int_expression @code{)}
@*@code{reduce (} module_expression@code{,} module_expression @code{)}
@*@code{reduce (} module_expression@code{,} module_expression@code{,} int_expression @code{)}
@*@code{reduce (} module_expression@code{,} matrix_expression@code{,} module_expression @code{)}
@*@code{reduce (} poly/vector/ideal/module@code{,} ideal/module@code{,} int@code{,} intvec @code{)}
@*@code{reduce (} ideal@code{,} matrix@code{,} ideal@code{,} int @code{)}
@*@code{reduce (} poly@code{,} poly@code{,} ideal@code{,} int @code{)}
@*@code{reduce (} poly@code{,} poly@code{,} ideal@code{,} int@code{,} intvec @code{)}
@item @strong{Type:}
the type of the first argument
@item @strong{Purpose:}
reduces a polynomial, vector, ideal  or module to its normal form with respect to an ideal or module represented by a standard basis.
Returns 0 if and only if the polynomial (resp.@: vector, ideal, module)
is an element (resp.@: subideal, submodule) of the ideal (resp.@: module).
The result may have no meaning if the second argument is not a standard basis.
@*The third (optional) argument of type int modifies the behaviour:
@itemize
@item 0
default
@item 1
consider only the leading term and do no tail reduction.
@item 2
reduce also with bad ecart (in the local case)
@item 4
reduce without division, return possibly a non-zero constant multiple of the remainder
@end itemize
@*If a second argument @code{u} of type poly or matrix is given, the first argument @code{p} is replaced by @code{p/u}.
This works only for zero dimensional ideals (resp.@: modules) in the third argument and gives, even in a local ring, a reduced normal form which is the projection to the quotient by the ideal (resp.@: module).
One may give a degree bound in the fourth argument with respect to a weight vector in the fifth argument in order have a finite computation.
If some of the weights are zero, the procedure may not terminate!
@item @strong{Note:}
The commands @code{reduce} and @code{NF} are synonymous.
@item @strong{Example:}
@smallexample
@c example
  ring r1 = 0,(z,y,x),ds;
  poly s1=2x5y+7x2y4+3x2yz3;
  poly s2=1x2y2z2+3z8;
  poly s3=4xy5+2x2y2z3+11x10;
  ideal i=s1,s2,s3;
  ideal j=std(i);
  reduce(3z3yx2+7y4x2+yx5+z12y2x2,j);
  reduce(3z3yx2+7y4x2+yx5+z12y2x2,j,1);
  // 4 arguments:
  ring rs=0,x,ds;
  // normalform of 1/(1+x) w.r.t. (x3) up to degree 5
  reduce(poly(1),1+x,ideal(x3),5);
@c example
@end smallexample
@end table
@c ref
See
@ref{ideal};
@ref{module};
@ref{vector};
@ref{std}.
@c ref
@c ---------------------------------------
@node regularity, repart, reduce, Functions
@subsection regularity
@cindex regularity
@table @code
@item @strong{Syntax:}
@code{regularity (} list_expression @code{)}
@*@code{regularity (} resolution_expression @code{)}
@item @strong{Type:}
int
@item @strong{Purpose:}
computes the regularity of a homogeneous ideal, resp.@: module, from a
minimal resolution given by the argument.
@*
@ifinfo
Let
@format
       K[X]e(a,n) ---> ... ---> (+) K[X]e(a,0) ---> I ---> 0
@end format
be a minimal resolution with homogeneous maps of degree 0.
The regularity is the smallest number s with the property @*
deg(e(a,i)) <= s+i for all i.
@end ifinfo
@tex
\noindent
Let $0 \rightarrow\ \bigoplus_a K[x]e_{a,n}\ \rightarrow\ \dots
  \rightarrow\ \bigoplus_a K[x]e_{a,0}\ \rightarrow\
  I\ \rightarrow\ 0$
be a minimal resolution of I considered with homogeneous maps of degree 0.
The regularity is the smallest number $s$ with the property deg($e_{a,i})
 \leq s+i$ for all $i$.
@end tex
@item @strong{Note:}
If applied to a non minimal resolution only an upper bound is returned.
@*If the input to the commands @code{res} and @code{mres} is homogeneous
the regularity is computed and used as a degree bound during
the computation unless @code{option(notRegularity);} is given.
@item @strong{Example:}
@smallexample
@c example
  ring rh3=32003,(w,x,y,z),(dp,C);
  poly f=x11+y10+z9+x5y2+x2y2z3+xy3*(y2+x)^2;
  ideal j=homog(jacob(f),w);
  def jr=res(j,0);
  regularity(jr);
  // example for upper bound behaviour:
  list jj=jr;
  regularity(jj);
  jj=nres(j,0);
  regularity(jj);
  jj=minres(jj);
  regularity(jj);
@c example
@end smallexample
@end table
@c ref
See
@ref{res};
@ref{resolution};
@ref{mres};
@ref{sres};
@ref{list};
@ref{minres};
@ref{option}.
@c ref
@c ---------------------------------------
@node repart, res, regularity, Functions
@subsection repart
@cindex repart

@table @code
@item @strong{Syntax:}
@code{repart (} number_expression @code{)}
@item @strong{Type:}
number
@item @strong{Purpose:}
returns the real part of a number from a complex ground field,
@*returns its argument otherwise.
@item @strong{Example:}
@smallexample
@c example
  ring r=(complex,i),x,dp;
  repart(1+2*i);
@c example
@end smallexample
@end table
@c ref
See
@ref{impart}.
@c ref
@c ---------------------------------------
@node  res, reservedName, repart, Functions
@subsection res
@cindex res
@c lib standard.lib:res lib_fun lib_ex subsection

@c ---------------------------------------
@node reservedName, resultant, res, Functions
@subsection reservedName
@cindex reservedName
@table @code
@item @strong{Syntax:}
@code{reservedName ()}
@item @strong{Type:}
none
@item @strong{Syntax:}
@code{reservedName (} string_expression @code{)}
@item @strong{Type:}
int
@item @strong{Purpose:}
prints a list of all reserved identifiers (first form) or tests
whether the string is a reserved identifier (second form).
@item @strong{Example:}
@smallexample
reservedName();
@expansion{} ... // output skipped
@c example
  reservedName("ring");
  reservedName("xyz");
@c example
@end smallexample
@end table
@c ref
See
@ref{names};
@ref{string}.
@c ref
@c ---------------------------------------
@node  resultant, ringlist, reservedName, Functions
@subsection resultant
@cindex resultant
@table @code
@item @strong{Syntax:}
@code{resultant (} poly_expression@code{,} poly_expression@code{,} ring_variable @code{)}
@item @strong{Type:}
poly
@item @strong{Purpose:}
computes the resultant of the first and second argument with respect
to the variable given as the third argument.
@item @strong{Example:}
@smallexample
@c example
  ring r=32003,(x,y,z),dp;
  poly f=3*(x+2)^3+y;
  poly g=x+y+z;
  resultant(f,g,x);
@c example
@end smallexample
@end table
@c ref
See
@ref{poly};
@ref{ring}.
@c ref
@c ---------------------------------------
@node  ringlist, rvar, resultant, Functions
@subsection ringlist
@cindex ringlist
@table @code
@item @strong{Syntax:}
@code{ringlist (} ring_expression @code{)}
@*@code{ringlist (} qring_expression @code{)}
@item @strong{Type:}
list
@item @strong{Purpose:}
decomposes a ring/qring into a list of 4 (or 6 in the noncommutative case,
see @ref{ringlist (plural)}) components:
@enumerate
@item
the field description in the following format:
  @itemize
  @item for Q, Z/p:
  the characteristic, type int (0 or prime number)
  @item for real, complex:
  a list of:@*
  the characteristic, type int (always 0)@*
  the precision, type list (2 integers: external, internal precision)@*
  the name of the imaginary unit, type string
  @item for transcendental or algebraic extensions:
  described as a ringlist (that is, as list L with 4 entries:
  L[1] the characteristic, L[2] the names of the parameters, L[3] the monomial
  ordering for the ring of parameters (default: lp), L[4] the minimal
  polynomial (as ideal))
  @item for Z, Z/n, Z/n^m a list ["integer", [n, m]] with:@*
  the base n is of type int or bigint (if not given n = 0, Z/0 = Z)@*
  the exponent m is of type int (if not given m = 1)@*
  @end itemize
@item
the names of the variables (a list L of strings: L[i] is the name of the i-th
variable)
@item
the monomial ordering (a list L of lists): each block L[i] consists of
@itemize
@item
the name of the ordering ( string )
@item
parameters specifying the ordering and the size of the block ( intvec : typically the weights for the variables [default: 1] )
@end itemize
@item
the quotient ideal.
@end enumerate
From a list of such structure, a new ring may be defined by the command @code{ring}
( see the following example ).
@item @strong{Example:}
@smallexample
@c example
 ring r = 0,(x(1..3)),dp;
 list l = ringlist(r);
 l;
 //  Now change l and create a new ring, by
 //- changing the base field to the function field with parameter a,
 //- introducing one extra variable y,
 //- defining the block ordering (dp(2),wp(3,4)).
 //- define the minpoly after creating the function field
 l[1]=list(0,list("a"),list(list("lp",1)),ideal(0));
 l[2][size(l[2])+1]="y";
 l[3][3]=l[3][2]; // save the module ordering
 l[3][1]=list("dp",intvec(1,1));
 l[3][2]=list("wp",intvec(3,4));
 def ra = ring(l);     //creates the newring
 ra; setring ra;
 list lra = ringlist(ra);
 lra[1][4]=ideal(a2+1);
 def Ra = ring(lra);
 setring Ra; Ra;
@c example
@end smallexample
@end table
@c ref
See
@ref{ring};
@ref{qring}.
@c ref
@c ---------------------------------------
@node rvar, setring, ringlist, Functions
@subsection rvar
@cindex rvar
@table @code
@item @strong{Syntax:}
@code{rvar (} name @code{)}
@*@code{rvar (} poly_expression @code{)}
@*@code{rvar (} string_expression @code{)}
@item @strong{Type:}
int
@item @strong{Purpose:}
returns the number of the variable if the name/poly is a ring variable of the
basering or if the string is the name of a ring variable of the
basering; returns 0 if not. Hence the return value of @code{rvar} can
also be used in a boolean context to check whether the variable exists.
@item @strong{Example:}
@smallexample
@c example
  ring r=29,(x,y,z),lp;
  rvar(x);
  rvar(r);
  rvar(y);
  rvar(var(3));
  rvar("x");
@c example
@end smallexample
@end table
@c ref
See
@ref{defined};
@ref{ring};
@ref{var};
@ref{varstr}.
@c ref
@c ---------------------------------------
@node setring, simplex, rvar, Functions
@subsection setring
@cindex setring
@table @code
@item @strong{Syntax:}
@code{setring} ring_name
@item @strong{Type:}
none
@item @strong{Purpose:}
changes the basering to another (already defined) ring.
@item @strong{Example:}
@smallexample
@c example
  ring r1=0,(x,y),lp;
  // the basering is r1
  ring r2=32003,(a(1..8)),ds;
  // the basering is r2
  setring r1;
  // the basering is again r1
  nameof(basering);
  listvar();
@c example
@end smallexample
@item @strong{Use in procedures:}
All changes of the basering by a definition of a new ring or a
@code{setring} command in a procedure are local to this procedure.  Use
@code{keepring} to move a ring, which is local to a procedure, up by one
nesting level.

@end table
@c ref
See
@ref{qring};
@ref{ring};
@ref{keepring}.
@c ref
@c ---------------------------------------
@node simplex, simplify, setring, Functions
@subsection simplex
@cindex simplex
@table @code
@item @strong{Syntax:}
@code{simplex (} matrix_expression@code{,} int_expression@code{,}
int_expression@code{,} int_expression@code{,} int_expression@code{,}
int_expression@code{)}
@item @strong{Type:}
list
@item @strong{Purpose:}
perform the simplex algorithm for the tableau given by the input, e.g.
@code{simplex (}M, m, n, m1, m2, m3 @code{)}:

@table @asis
@item  M matrix of numbers :
     first row describing the objective function (maximize problem),
     the remaining rows describing constraints;
@item  m,n,m1,m2,m3 int :
     n = number of variables;
     m = total number of constraints;
     m1 = number of <=constraints (rows 2 ... m1+1 of M);
     m2 = number of >=constraints (rows m1+2 ... m1+m2+1 of M);
     m3 = number of == constraints.
@end table

The following assumptions are made:
@table @asis
@item   * ground field is of type @code{(real,N)}, N>=4;
@item   * the matrix M is of size m x n;
@item   * m=m1+m2+m3;
@item   * the entries M[2,1] ,..., M[m+1,1] are non-negative;
@item   * the variables x(i) are non-negative;
@item   * a row  b, a(1) ,..., a(n)  corresponds to  b+a(1)x(1)+...+a(n)x(n);
@item   * for a <=, >=, or == constraint: add "in mind" >=0, <=0, or ==0.
@end table

The output is a list L with
@table @asis
@item * L[1] = matrix
@item * L[2] = int:
    0 = finite solution found;  1 = unbounded;  -1 = no solution;
   -2 = error occured;
@item * L[3] = intvec :
   L[3][k] = number of variable which corresponds to row k+1 of L[1];
@item * L[4] = intvec :
   L[4][j] = number of variable which is represented by column j+1 of L[1]
   ("non-basis variable");
@item * L[5] = int :
   number of constraints (= m);
@item * L[6] = int :
   number of variables (= n).
@end table

The solution can be read from the first column of L[1] as is done by the
procedure @ref{simplexOut} in @code{solve.lib}.

@item @strong{Example:}
@smallexample
@c example
    ring r = (real,10),(x),lp;

    // consider the max. problem:
    //
    //    maximize  x(1) + x(2) + 3*x(3) - 0.5*x(4)
    //
    //  with constraints:   x(1) +          2*x(3)          <= 740
    //                             2*x(2)          - 7*x(4) <=   0
    //                               x(2) -   x(3) + 2*x(4) >=   0.5
    //                      x(1) +   x(2) +   x(3) +   x(4)  =   9
    //
    matrix sm[5][5]=(  0, 1, 1, 3,-0.5,
                     740,-1, 0,-2, 0,
                       0, 0,-2, 0, 7,
                     0.5, 0,-1, 1,-2,
                       9,-1,-1,-1,-1);

    int n = 4;  // number of constraints
    int m = 4;  // number of variables
    int m1= 2;  // number of <= constraints
    int m2= 1;  // number of >= constraints
    int m3= 1;  // number of == constraints
    simplex(sm, n, m, m1, m2, m3);
@c example
@end smallexample
@end table
@c ref
See
@ref{simplexOut}.
@c ref
@c ---------------------------------------
@node simplify, size, simplex, Functions
@subsection simplify
@cindex simplify
@table @code
@item @strong{Syntax:}
@code{simplify (} poly_expression@code{,} int_expression @code{)}
@*@code{simplify (} vector_expression@code{,} int_expression @code{)}
@*@code{simplify (} ideal_expression@code{,} int_expression @code{)}
@*@code{simplify (} module_expression@code{,} int_expression @code{)}
@item @strong{Type:}
the type of the first argument
@item @strong{Purpose:}
returns the "simplified" first argument depending on the simplification rule
given as the second argument.
The simplification rules are the sum of the following
functions:
@table @code
@item 1
normalize (make leading coefficients 1).
@item 2
erase zero generators/columns.
@item 4
keep only the first one of identical generators/columns.
@item 8
keep only the first one of generators/columns which differ only by a factor
in the ground field.
@item 16
keep only those generators/columns whose leading monomials
differ.
@item 32
keep only those generators/columns whose leading monomials are
not divisible by other ones.
@end table
@item @strong{Example:}
@smallexample
@c example
ring r=0,(x,y,z),(c,dp);
ideal i=0,2x,2x,4x,3x+y,5x2;
simplify(i,1);
simplify(i,2);
simplify(i,4);
simplify(i,8);
simplify(i,16);
simplify(i,32);
simplify(i,32+2+1);
matrix A[2][3]=x,0,2x,y,0,2y;
simplify(A,2+8); // by automatic conversion to module
@c example
@end smallexample
@end table
@c ref
See
@ref{poly};
@ref{vector};
@ref{ideal};
@ref{module}.
@c ref
@c ---------------------------------------
@node size, slimgb, simplify, Functions
@subsection size
@cindex size
@table @code
@item @strong{Syntax:}
@code{size (} string_expression @code{)}
@*@code{size (} intvec_expression @code{)}
@*@code{size (} intmat_expression @code{)}
@*@code{size (} poly_expression @code{)}
@*@code{size (} vector_expression @code{)}
@*@code{size (} ideal_expression @code{)}
@*@code{size (} module_expression @code{)}
@*@code{size (} matrix_expression @code{)}
@*@code{size (} list_expression @code{)}
@*@code{size (} resolution_expression @code{)}
@*@code{size (} ring_expression @code{)}
@item @strong{Type:}
int
@item @strong{Purpose:}
depends on the type of argument:
@table @asis
@item ideal or module
returns the number of (non-zero) generators.
@item string, intvec, list or resolution
returns the length, i.e., the number of characters, entries or elements.
@item poly or vector
returns the number of monomials.
@item matrix or intmat
returns the number of entries (rows*columns).
@item ring
returns the number of elements in the ground field
(for Z/p and algebraic extensions) or -1
@end table
@item @strong{Example:}
@smallexample
@c example
  string s="hello";
  size(s);
  intvec iv=1,2;
  size(iv);
  ring r=0,(x,y,z),lp;
  poly f=x+y+z;
  size(f);
  vector v=[x+y,0,0,1];
  size(v);
  ideal i=f,y;
  size(i);
  module m=v,[0,1],[0,0,1],2*v;
  size(m);
  matrix mm[2][2];
  size(mm);
  ring r1=(2,a),x,dp;
  minpoly=a4+a+1;
  size(r1);
@c example
@end smallexample
@end table
@c ref
See
@ref{string};
@ref{intvec};
@ref{intmat};
@ref{poly};
@ref{vector};
@ref{ideal};
@ref{module};
@ref{ncols};
@ref{nrows}.
@c ref
@c ---------------------------------------
@node slimgb, sortvec, size, Functions
@subsection slimgb
@cindex slimgb
@table @code
@item @strong{Syntax:}
@* @code{slimgb (} ideal_expression@code{)}
@* @code{slimgb (} module_expression@code{)}
@item @strong{Type:}
ideal or module
@item @strong{Purpose:}

@ref{slim Groebner bases}


Returns a Groebner basis of an ideal or module with respect to the monomial
ordering of the basering (which has to be global).
@item @strong{Note:}
The algorithm is designed to keep polynomials slim (short with small coefficients). For details see @code{http://www.mathematik.uni-kl.de/~zca/Reports_on_ca/35/paper_35_full.ps.gz}.
A reduced Groebner basis is returned if option(redSB) is set
(see @ref{option(redSB)}).
To view the progress of long running computations, use option(prot)
(see @ref{option(prot)}).



@item @strong{Example:}
@smallexample
@c example
  ring r=2,(x,y,z),lp;
  poly s1=z*(x*y+1);
  poly s2=x2+x;
  poly s3=y2+y;
  ideal i=s1,s2,s3;
  slimgb(i);
@c example
@end smallexample

@end table

@c ref
See
@ref{groebner};
@ref{ideal};
@ref{ring};
@ref{option};
@ref{std}.
@c ref

@c ---------------------------------------
@node sortvec, sqrfree, slimgb, Functions
@subsection sortvec
@cindex sortvec
@table @code
@item @strong{Syntax:}
@code{sortvec (} ideal_expression @code{)}
@*@code{sortvec (} module_expression @code{)}
@item @strong{Type:}
intvec
@item @strong{Purpose:}
@tex
computes the permutation {\tt v}
which orders the ideal, resp.\ module, {\tt I} by its initial terms,
starting with the smallest, that is, {\tt I(v[i]) < I(v[i+1])} for all
{\tt i}.
@end tex
@ifinfo
computes the permutation v
which orders the ideal, resp.@: module, I by its initial terms,
starting with the smallest, that is,
@*I(v[i]) < I(v[i+1]) for all i.
@end ifinfo
@item @strong{Example:}
@smallexample
@c example
  ring r=0,(x,y,z),dp;
  ideal I=y,z,x,x3,xz;
  sortvec(I);
@c example
@end smallexample
@end table
@c ref
See
@ref{general_lib}.
@c ref
@c ---------------------------------------
@node sqrfree, sprintf, sortvec, Functions
@subsection sqrfree
@cindex sqrfree
@table @code
@item @strong{Syntax:}
@code{sqrfree (} poly_expression @code{)}
@item @strong{Type:}
ideal
@item @strong{Purpose:}
computes a squarefree decomposition of the given polynomial.
@item @strong{Example:}
@smallexample
@c example
  ring r=3,(x,y,z),dp;
  poly f=(x-y)^3*(x+z)*(y-z);
  sqrfree(f);
@c example
@end smallexample
@end table
@c ref
See
@ref{factorize}.
@c ref
@c ---------------------------------------
@node sprintf, sres, sqrfree, Functions
@subsection sprintf
@cindex sprintf
@c lib standard.lib:sprintf lib_fun lib_ex subsection

@c ---------------------------------------
@node sres, status, sprintf, Functions
@subsection sres
@cindex sres
@table @code
@item @strong{Syntax:}
@code{sres (} ideal_expression@code{,} int_expression @code{)}
@*@code{sres (} module_expression@code{,} int_expression @code{)}
@item @strong{Type:}
resolution
@item @strong{Purpose:}
computes a free resolution of an ideal or module with Schreyer's
method. The ideal, resp.@: module, has to be a standard basis.
More precisely, let M be given by a standard basis and
@tex
$A_1={\tt matrix}(M)$.
@end tex
@ifinfo
A1=matrix(M).
@end ifinfo
Then @code{sres}
computes a free resolution of
@ifinfo
coker(A1)=F0/M
@format
                    A2       A1
      ... ----> F2 ----> F1 ----> F0 --> F0/M --> 0.
@end format
@end ifinfo
@tex
$coker(A_1)=F_0/M$
$$...\longrightarrow F_2 \buildrel{A_2}\over{\longrightarrow} F_1 \buildrel{A_1}\over{\longrightarrow} F_0\longrightarrow F_0/M\longrightarrow 0.$$
@end tex
If the int expression k is not zero then the computation stops after k steps
and returns a list of modules (given by standard bases)
@tex
$M_i={\tt module}(A_i)$, i=1..k.
@end tex
@ifinfo
Mi=module(Ai), i=1..k.
@end ifinfo
@*@code{sres(M,0)}
returns a list of n modules where n is the number of variables of the basering.

Even if @code{sres} does not compute a minimal resolution, the @code{betti}
command gives the true betti numbers! In many cases of interest
@code{sres} is much faster than any other known method.
Let @code{list L=sres(M,0);} then @code{L[1]=M} is identical to the input,
@code{L[2]} is a standard basis with respect to the Schreyer ordering of
the first syzygy
module of @code{L[1]}, etc.
@ifinfo
(L[i]=M_i
@end ifinfo
@tex
(${\tt L[i]}=M_i$
@end tex
 in the notations from above.)
@item @strong{Note:}
Accessing single elements of a resolution may require that some partial
computations have to be finished and may therefore take some time.
@item @strong{Example:}
@smallexample
@c example
  ring r=31991,(t,x,y,z,w),ls;
  ideal M=t2x2+tx2y+x2yz,t2y2+ty2z+y2zw,
          t2z2+tz2w+xz2w,t2w2+txw2+xyw2;
  M=std(M);
  resolution L=sres(M,0);
  L;
  print(betti(L),"betti");
@c example
@end smallexample
@end table
@c ref
See
@ref{betti};
@ref{ideal};
@ref{int};
@ref{lres};
@ref{hres};
@ref{minres};
@ref{module};
@ref{mres};
@ref{res};
@ref{syz}.
@c ref
@c ---------------------------------------
@node status, std, sres, Functions
@subsection status
@cindex status
@cindex sleep
@cindex suspend
@table @code
@item @strong{Syntax:}
@code{status (} link_expression@code{,} string_expression @code{)}
@item @strong{Type:}
string
@item @strong{Syntax:}
@code{status (} link_expression@code{,} string_expression@code{,} string_expression @code{)}
@*@code{status (} link_expression@code{,} string_expression@code{,} string_expression@code{,} int_expression @code{)}
@item @strong{Type:}
int
@item @strong{Purpose:}
returns the status of the link as asked for by the second argument.  If
a third argument is given, the result of the comparison to the status
string is returned: @code{(status(l,s1)==s2)} is equivalent to
@code{status(l,s1,s2)}.  If a fourth integer argument (say, @code{i}) is
given and if @code{status(l,s1,s2)} yields @code{0}, then the execution
of the current process is suspended (the process is put to ``sleep'')
for approximately@: @code{i} microseconds, and afterwards the result of another
call to @code{status(l,s1,s2)} is returned. The latter is useful for
``polling'' the @code{read} status of MPtcp links such that busy
loops are avoided (see @ref{Parallelization with MPtcp links} for an
example).  Note that on some systems, the minimum time for a process to
be put to sleep is one second.
@*The following string expressions are allowed:
@table @code
@item @code{"name"}
the name string given by the definition of the link (usually the filename)
@item @code{"type"}
returns @code{"ASCII"}, @code{"MPfile"}, @code{"MPtcp"} or @code{"DBM"}
@item @code{"open"}
returns @code{"yes"} or @code{"no"}
@item @code{"openread"}
returns @code{"yes"} or @code{"no"}
@item @code{"openwrite"}
returns @code{"yes"} or @code{"no"}
@item @code{"read"}
returns @code{"ready"} or @code{"not ready"}
@item @code{"write"}
returns @code{"ready"} or @code{"not ready"}
@item @code{"mode"}
returns (depending on the type of the link and its status)
@code{"","w","a","r"} or @code{"rw"}
@item @code{"exists"}
returns @code{"yes"} or @code{"no"}: existence of the filename for ASCII/MPfile links
@end table
@item @strong{Example:}
@smallexample
@c example
  link l=":w example.txt";
  status(l,"write");
  open(l);
  status(l,"write","ready");
  close(l);
@c example
@end smallexample
@end table
@c ref
See
@ref{link};
@ref{open};
@ref{read};
@ref{write}.
@c ref
@c ---------------------------------------
@node std, stdfglm, status, Functions
@subsection std
@cindex std
@table @code
@item @strong{Syntax:}
@code{std (} ideal_expression@code{)}
@*@code{std (} module_expression@code{)}
@*@code{std (} ideal_expression@code{,} intvec_expression @code{)}
@*@code{std (} module_expression@code{,} intvec_expression @code{)}
@*@code{std (} ideal_expression@code{,} intvec_expression@code{,} intvec_expression @code{)}
@*@code{std (} module_expression@code{,} intvec_expression@code{,} intvec_expression @code{)}
@*@code{std (} ideal_expression@code{,} poly_expression @code{)}
@*@code{std (} module_expression@code{,} vector_expression @code{)}
@*@code{std (} ideal_expression@code{,} ideal_expression @code{)}
@*@code{std (} module_expression@code{,} module_expression @code{)}
@*@code{std (} ideal_expression@code{,} poly_expression@code{,} intvec_expression@code{,} intvec_expression @code{)}
@*@code{std (} module_expression@code{,} poly_expression@code{,} intvec_expression@code{,} intvec_expression @code{)}
@item @strong{Type:}
ideal or module
@item @strong{Purpose:}
returns a standard basis of an ideal or module with respect to the
monomial ordering of the basering.
A standard basis is a set of generators such that
the leading terms generate the leading ideal, resp.@: module.
@*Use an optional
second argument of type intvec as Hilbert series
(result of @code{hilb(i,1)}, see @ref{hilb}),
if the ideal, resp.@: module, is homogeneous
(Hilbert driven standard basis computation, @ref{stdhilb}).
If the ideal is quasihomogeneous with some weights w and if the Hilbert series
is computed w.r.t.@: to these weights, then use w as third argument.
@*Use an optional second argument of type poly/vector/ideal, resp.@: module,
to construct the standard basis from an already computed one (given as the
first argument) and additional generator(s) (the second argument).
@*4 arguments @code{G,p,hv,w} are the combination of the above:
standard basis @code{G}, additional generator @code{p}, hilbert function @code{hv} w.r.t. weights @code{w}.

@item @strong{Note:}
The
standard basis is computed with a (more or less) straight-forward
implementation of the classical
Buchberger (resp.@: Mora) algorithm. For global orderings, use the
@code{groebner} command instead (@pxref{groebner}), which heuristically
chooses the "best" algorithm to compute a Groebner basis.
@*To view the progress of long running computations, use
@code{option(prot)} (see @ref{option(prot)}).

@item @strong{Example:}
@smallexample
@c example
  // local computation
  ring r=32003,(x,y,z),ds;
  poly s1=1x2y+151xyz10+169y21;
  poly s2=1xz14+6x2y4+3z24;
  poly s3=5y10z10x+2y20z10+y10z20+11x3;
  ideal i=s1,s2,s3;
  ideal j=std(i);
  degree(j);
  // Hilbert driven elimination (standard)
  ring rhom=32003,(x,y,z,h),dp;
  ideal i=homog(imap(r,i),h);
  ideal j=std(i);
  intvec iv=hilb(j,1);
  ring rlex=32003,(x,y,z,h),lp;
  ideal i=fetch(rhom,i);
  ideal j=std(i,iv);
  j=subst(j,h,1);
  j[1];
  // Hilbert driven elimination (ideal is quasihomogeneous)
  intvec w=10,1,1;
  ring whom=32003,(x,y,z),wp(w);
  ideal i=fetch(r,i);
  ideal j=std(i);
  intvec iw=hilb(j,1,w);
  ring wlex=32003,(x,y,z),lp;
  ideal i=fetch(whom,i);
  ideal j=std(i,iw,w);
  j[1];
@c example
@end smallexample
@end table
@c ref
See
@ref{ideal};
@ref{ring};
@ref{option};
@ref{facstd};
@ref{fglm};
@ref{groebner};
@ref{mstd};
@ref{stdfglm};
@ref{stdhilb}.
@c ref

@c ---------------------------------------
@node stdfglm, stdhilb, std, Functions
@subsection stdfglm
@cindex stdfglm
@c lib standard.lib:stdfglm lib_fun lib_ex subsection

@c ---------------------------------------
@node stdhilb, subst, stdfglm, Functions
@subsection stdhilb
@cindex stdhilb
@c lib standard.lib:stdhilb lib_fun lib_ex subsection

@c ---------------------------------------
@node subst, system, stdhilb, Functions
@subsection subst
@cindex subst
@table @code
@item @strong{Syntax:}
@code{subst (} poly_expression@code{,} variable@code{,} poly_expression @code{)}
@*@code{subst (} vector_expression@code{,} variable@code{,} poly_expression @code{)}
@*@code{subst (} ideal_expression@code{,} variable@code{,} poly_expression @code{)}
@*@code{subst (} module_expression@code{,} variable@code{,} poly_expression @code{)}
@item @strong{Type:}
poly, vector, ideal or module (corresponding to the first argument)
@item @strong{Purpose:}
substitutes a ring variable/parameter variable by a polynomial.
@item @strong{Note:}
use @code{map} for substitutions by polynomials.
@item @strong{Example:}
@smallexample
@c example
  ring r=0,(x,y,z),dp;
  poly f=x2+y2+z2+x+y+z;
  subst(f,x,3/2);
  int a=1;
  subst(f,y,a);
  subst(f,y,z);
@c example
@end smallexample
@end table
@c ref
See
@ref{map};
@ref{poly};
@ref{vector};
@ref{ideal};
@ref{module};
@ref{substitute}.
@c ref
@c ---------------------------------------
@node  system, syz, subst, Functions
@subsection system
@cindex system
@table @code
@item @strong{Syntax:}
@code{system (} string_expression @code{)}
@*@code{system (} string_expression@code{,} expression @code{)}
@item @strong{Type:}
depends on the desired function, may be none
@item @strong{Purpose:}
interface to internal data and the operating system. The
string_expression determines the command to execute. Some commands
require an additional argument (second form) where the type of the
argument depends on the command. See below for a list of all possible
commands.
@item @strong{Note:}
Not all functions work on every platform.
@item @strong{Functions:}
@table @asis
@item @code{system("sh"}, string_expression @code{)}
@cindex sh
@cindex system, sh
shell escape, returns the return code of the shell as int. The string is
sent literally to the shell.
@item @code{system("pid")}
@cindex pid
@cindex system, pid
returns the process number as int (for creating unique names).
@item @code{system("uname")}
@cindex uname
@cindex system, uname
@cindex hardware platform
returns a string identifying the architecture for which @sc{Singular}
was compiled.
@item @code{system("getenv",} string_expression@code{)}
@cindex getenv
@cindex system, getenv
returns the value of the shell environment variable given as the second
argument. The return type is string.
@item @code{system("setenv",}string_expression, string_expression@code{)}
@cindex setenv
@cindex system, setenv
sets the shell environment variable given as the second argument to the
value given as the third argument. Returns the third argument. Might not
be available on all platforms.
@item @code{system("tty")}
@cindex tty
@cindex system, tty
resets the terminal.
@item @code{system("version")}
@cindex version
@cindex system, version
returns the version number of  @sc{Singular} as int.
@item @code{system("contributors")}
@cindex contributors
@cindex system, contributors
returns names of people who contributed to the @sc{Singular} kernel as string.
@item @code{system("gen")}
@c gen is reserved id: @cindex gen
@cindex system, gen
returns the generating element of the multiplicative
group of (Z/p)\@{0@} (as int) where p is the characteristic of the
basering.
@item @code{system("nblocks")}
@item @code{system("nblocks",} ring_name @code{)}
@cindex nblocks
@cindex system, nblocks
returns the number of blocks of the given ring, or the number of parameters
of the current basering, if no second argument is given. The return type
is int.
@item @code{system("Singular")}
@cindex Singular
@cindex system, Singular
returns the absolute (path) name of the running @sc{Singular} as string.
@item @code{system("SingularLib")}
@cindex SingularLib
@cindex system, SingularLib
returns the colon seperated library search path name as string.
@item @code{system("}--@code{")}
@cindex system, --
@cindex command-line options, print all values of
prints the values of all options.
@item @code{system("}--long_option_name@code{")}
@cindex command-line option, value of
@cindex system, --long_option_name
returns the value of the (command-line) option long_option_name. The
type of the returned value is either string or int.
@xref{Command line options}, for more info.
@item @code{system("}--long_option_name@code{",} expression@code{)}
@cindex command-line option, setting value of
@cindex system, --long_option_name=value
@cindex random number generator, seed
@cindex browsers, setting the
@cindex browser, setting the
@cindex help browsers, setting the
@cindex timer resolution, setting the
@cindex minimal display time, setting the
sets the value of the (command-line) option long_option_name to the
value given by the expression. Type of the expression must be string, or
int.  @xref{Command line options}, for more info. Among others,
this can be used for setting the seed of the random number generator,
the used help browser, the minimal display time, or the timer
resolution.
@item @code{system("browsers");}
@cindex system, browsers
returns a string about available help browsers.
@xref{The online help system}.
@end table
@item @strong{Example:}
@smallexample
// a listing of the current directory:
system("sh","ls");
// execute a shell, return to SINGULAR with exit:
system("sh","sh");
string unique_name="/tmp/xx"+string(system("pid"));
unique_name;
@expansion{} /tmp/xx4711
system("uname")
@expansion{} ix86-Linux
system("getenv","PATH");
@expansion{} /bin:/usr/bin:/usr/local/bin
system("Singular");
@expansion{} /usr/local/bin/Singular
@c example
// report value of all options
system("--");
// set minimal display time to 0.02 seconds
system("--min-time", "0.02");
// set timer resolution to 0.01 seconds
system("--ticks-per-sec", 100);
// re-seed random number generator
system("--random", 12345678);
// allow netscape to access HTML pages from the net
system("--allow-net", 1);
// and set help browser to netscape
system("--browser", "netscape");
@c example
@end smallexample
@end table
@c -------------------------------------------------
@node syz, trace, system, Functions
@subsection syz
@cindex syz
@table @code
@item @strong{Syntax:}
@code{syz (} ideal_expression @code{)}
@*@code{syz (} module_expression @code{)}
@item @strong{Type:}
module
@item @strong{Purpose:}
computes the first syzygy (i.e., the module of relations of the given
generators) of the ideal, resp.@: module.
@item @strong{Example:}
@smallexample
@c example
  ring R=0,(x,y),(c,dp);
  ideal i=x,y;
  syz(i);
@c example
@end smallexample
@end table
@c ref
See
@ref{ideal};
@ref{lres};
@ref{hres};
@ref{module};
@ref{mres};
@ref{nres};
@ref{res};
@ref{sres}.
@c ref
@c ---------------------------------------
@node trace, transpose, syz, Functions
@subsection trace
@cindex trace
@table @code
@item @strong{Syntax:}
@code{trace (} intmat_expression @code{)}
@*@code{trace (} matrix_expression @code{)}
@item @strong{Type:}
int, if the argument is an intmat, resp.@: @*
poly, if the argument is a matrix
@item @strong{Purpose:}
returns the trace of an intmat, resp.@: matrix.
@item @strong{Example:}
@smallexample
@c example
  intmat m[2][2]=1,2,3,4;
  print(m);
  trace(m);
@c example
@end smallexample
@end table
@c ref
See
@ref{intmat};
@ref{matrix}.
@c ref
@c ---------------------------------------
@node transpose, type, trace, Functions
@subsection transpose
@cindex transpose
@table @code
@item @strong{Syntax:}
@code{transpose (} intmat_expression @code{)}
@*@code{transpose (} matrix_expression @code{)}
@*@code{transpose (} module_expression @code{)}
@item @strong{Type:}
intmat, matrix, or module, corresponding to the argument
@item @strong{Purpose:}
transposes a matrix.
@item @strong{Example:}
@smallexample
@c example
  ring R=0,x,dp;
  matrix m[2][3]=1,2,3,4,5,6;
  print(m);
  print(transpose(m));
@c example
@end smallexample
@end table
@c ref
See
@ref{intmat};
@ref{matrix};
@ref{module}.
@c ref
@c ---------------------------------------
@node type, typeof, transpose, Functions
@subsection type
@cindex type
@table @code
@item @strong{Syntax:}
@code{type } name @code{;} @*
@code{type (} name @code{);}
@item @strong{Type:}
none
@item @strong{Purpose:}
prints the name, level, type and value of a variable. To display the
value of an expression, it is sufficient to type the expression followed
by @code{;}.
@item @strong{Example:}
@smallexample
@c example
  int i=3;
  i;
  type(i);
@c example
@end smallexample
@end table
@c ref
See
@ref{listvar};
@ref{print};
@ref{Data types}.
@c ref
@c ---------------------------------------
@node typeof, univariate, type, Functions
@subsection typeof
@cindex typeof
@table @code
@item @strong{Syntax:}
@code{typeof (} expression @code{)}
@item @strong{Type:}
string
@item @strong{Purpose:}
returns the type of an expression as string.

Returns the type of the first list element if the expression is an
expression list.

Possible types are:
@code{"ideal"},
@code{"int"},
@code{"intmat"},
@code{"intvec"},
@code{"list"},
@code{"map"},
@code{"matrix"},
@code{"module"},
@code{"number"},
@code{"none"},
@code{"poly"},
@code{"proc"},
@code{"qring"},
@code{"resolution"},
@code{"ring"},
@code{"string"},
@code{"vector"}.

For internal use only is the type
@c @code{"package"},
@code{"?unknown type?"}.
@item @strong{Example:}
@smallexample
@c example
  int i=9; i;
  typeof(_);
  print(i);
  typeof(_);
  type i;
  typeof(_);
  string s=typeof(i);
  s;
  typeof(s);
  proc p() {  "hello"; return();}
  p();
  typeof(_);
@c example
@end smallexample
@end table
@c ref
See
@ref{type};
@ref{Data types}.
@c ref
@c ---------------------------------------
@node univariate, uressolve, typeof, Functions
@subsection univariate
@cindex univariate
@table @code
@item @strong{Syntax:}
@code{univariate (} poly_expression @code{)}
@item @strong{Type:}
int
@item @strong{Purpose:}
returns 0 for not univariate, -1 for a constant or the number of the variable
of the univariate polynomial.

@item @strong{Example:}
@smallexample
@c example
  ring r=0,(x,y,z),dp;
  univariate(x2+1);
  univariate(x2+y+1);
  univariate(1);
  univariate(var(2));
  var(univariate(z));
@c example
@end smallexample
@end table
@c ref
See
@ref{var};
@ref{leadexp}.
@c ref
@c ---------------------------------------
@node uressolve, vandermonde, univariate, Functions
@subsection uressolve
@cindex uressolve
@table @code
@item @strong{Syntax:}
@code{uressolve (} ideal_expression@code{,} int_expression@code{,} int_expression@code{,} int_expression @code{)}
@item @strong{Type:}
list
@item @strong{Purpose:}
computes all complex roots of a zerodimensional ideal. @*
Makes either use of the multipolynomial resultant of Macaulay (second argument
= 1), which works only for homogeneous ideals, or uses the sparse resultant
of Gelfand, Kapranov and Zelevinsky (second argument = 0). @*
The sparse resultant algorithm uses a mixed polyhedral subdivision of the
Minkowsky sum of the Newton polytopes in order to construct the sparse
resultant matrix. Its determinant is a nonzero multiple of the sparse
resultant. The u-resultant of B.L.@: van der Waerden and Laguerre's algorithm
are used to determine the complex roots. @*
The third argument defines the precision of the fractional part if the ground
field is the field of rational numbers, otherwise it will be ignored. @*
The fourth argument (can be 0, 1 or 2) gives the number of extra runs of
Laguerre's algorithm (with corrupted roots), leading to better results.
@item @strong{Note:}
If the ground field is the field of complex numbers, the elements of the list
are of type number, otherwise of type string.
@c @item @strong{Example:}
@c @smallexample
@c @c example
@c ring rsc=(real,20,I),(x,y),lp;
@c ideal i=(2+3*I)*x2+(0.35+I*45.0e-2)*y2-8,x2+xy+(42.7)*y2;
@c list l=uressolve(i,0,0,2);
@c l[1];
@c subst(subst(i[1],x,l[1][1]),y,l[1][2]);
@c @c example
@c @end smallexample
@end table
@c ref
See
@ref{laguerre};
@ref{mpresmat}.
@c ref
@c ---------------------------------------
@node vandermonde, var, uressolve, Functions
@subsection vandermonde
@cindex vandermonde
@table @code
@item @strong{Syntax:}
@code{vandermonde (} ideal_expression@code{,} ideal_expression@code{,}
int_expression @code{)}
@item @strong{Type:}
poly
@item @strong{Purpose:}
@ifinfo
@code{vandermonde(p,v,d)} computes the (unique) polynomial of degree
d with prescribed values v[1],...,v[N] at the points
p^0,...,p^(N-1), N=(d+1)^n, n the number of ring
variables.
@*The returned polynomial is sum_a c[a]*x1^a1*@dots{}*xn^an,
where the coefficients c[a] are the solution of the (transposed)
Vandermonde system of linear equations
@format
   sum_(|a|<=d) c_[a] * p[1]^(k*a1) *..* p[n]^(k*an) = v[k+1],
k=1,@dots{},N.
@end format
@end ifinfo
@tex
{\tt vandermonde(p,v,d)} computes the (unique) polynomial of degree
{\tt d} with prescribed values {\tt v[1],...,v[N]} at the points
{\tt p}$^0,\dots,$ {\tt p}$^{N-1}$, {\tt N=(d+1)}$^n$, $n$ the
number of ring variables.

The returned polynomial is $\sum
c_{\alpha_1\ldots\alpha_n}\cdot x_1^{\alpha_1} \cdot \dots \cdot
x_n^{\alpha_n}$, where the coefficients
$c_{\alpha_1\ldots\alpha_n}$ are the solution of the (transposed)
Vandermonde system of linear equations
$$ \sum_{\alpha_1+\ldots+\alpha_n\leq d} c_{\alpha_1\ldots\alpha_n} \cdot
{\tt p}_1^{(k-1)\alpha_1}\cdot\dots\cdot {\tt p}_n^{(k-1)\alpha_n} =
{\tt v}[k], \quad  k=1,\dots,{\tt N}.$$
@end tex
@item @strong{Note:}
@ifinfo
the ground field has to be the field of rational
numbers. Moreover, ncols(p)==n, the number of variables in the
basering, and all the given generators have to be numbers different from
0,1 or -1. Finally, ncols(v)==(d+1)^n, and all given generators have
to be numbers.
@end ifinfo
@tex
the ground field has to be the field of rational
numbers. Moreover, {\tt ncols(p)==}$n$, the number of variables in the
basering, and all the given generators have to be numbers different from
0,1 or -1. Finally, {\tt ncols(v)==(d+1)$^n$}, and all given generators have
to be numbers.
@end tex
@item @strong{Example:}
@smallexample
@c example
ring r=0,(x,y),dp;
// determine f with deg(f)=2 and with given values v of f
// at 9 points: (2,3)^0=(1,1),...,(2,3)^8=(2^8,3^8)
// valuation point: (2,3)
ideal p=2,3;
ideal v=1,2,3,4,5,6,7,8,9;
poly ip=vandermonde(p,v,2);
ip[1..5];  //  the 5 first terms of ip:
// compute value of ip at the point 2^8,3^8, result must be 9
subst(subst(ip,x,2^8),y,3^8);
@c example
@end smallexample
@end table
@c ref
@c ref
@c ---------------------------------------
@node var, variables, vandermonde, Functions
@subsection var
@cindex var
@table @code
@item @strong{Syntax:}
@code{var (} int_expression @code{)}
@item @strong{Type:}
poly
@item @strong{Purpose:}
@code{var(n)} returns the n-th ring variable.
@item @strong{Example:}
@smallexample
@c example
  ring r=0,(x,y,z),dp;
  var(2);
@c example
@end smallexample
@end table
@c ref
See
@ref{ring};
@ref{int};
@ref{univariate};
@ref{nvars};
@ref{varstr}.
@c ref
@c ---------------------------------------
@node variables, varstr, var, Functions
@subsection variables
@cindex variables
@table @code
@item @strong{Syntax:}
@code{variables (} poly_expression @code{)}
@*@code{variables (} ideal_expression @code{)}
@*@code{variables (} matrix_expression @code{)}
@item @strong{Type:}
ideal
@item @strong{Purpose:}
@code{var(p)} returns the list of all ring variables the argument depends on.
@item @strong{Example:}
@smallexample
@c example
  ring r=0,(x,y,z),dp;
  variables(2);
  variables(x+y2);
  variables(ideal(x+y2,x3y,z));
  string(variables(ideal(x+y2,x3y,z)));
@c example
@end smallexample
@end table
@c ref
See
@ref{var};
@ref{univariate};
@ref{leadexp};
@ref{nvars};
@ref{varstr}.
@c ref
@c ---------------------------------------
@node varstr, vdim, variables, Functions
@subsection varstr
@cindex varstr
@table @code
@item @strong{Syntax:}
@code{varstr (} ring_name @code{)}
@*@code{varstr (} int_expression @code{)}
@*@code{varstr (} ring_name@code{,} int_expression @code{)}
@item @strong{Type:}
string
@item @strong{Purpose:}
returns the list of the names of the ring variables as a string
or the name of the n-th ring variable, where n is given by the
int_expression.
@*If the ring name is omitted, the basering is used, thus
@code{varstr(n)} is equivalent to @code{varstr(basering,n)}.
@item @strong{Example:}
@smallexample
@c example
  ring r=0,(x,y,z),dp;
  varstr(r);
  varstr(r,1);
  varstr(2);
@c example
@end smallexample
@end table
@c ref
See
@ref{ring};
@ref{int};
@ref{nvars};
@ref{var};
@ref{ordstr};
@ref{charstr};
@ref{parstr}.
@c ref
@c ---------------------------------------
@node vdim, wedge, varstr, Functions
@subsection vdim
@cindex vdim
@table @code
@item @strong{Syntax:}
@code{vdim (} ideal_expression @code{)}
@*@code{vdim (} module_expression @code{)}
@item @strong{Type:}
int
@item @strong{Purpose:}
computes the vector space dimension of the ring, resp.@: free module,
modulo the ideal, resp.@: module,
generated by the initial terms of the given generators.
If the generators form a standard basis,
this is the same as the vector space dimension of the ring, resp.@:
free module, modulo the ideal, resp.@: module.
@*If the ideal, resp.@: module, is not zero-dimensional, -1 is returned.
@item @strong{Example:}
@smallexample
@c example
  ring r=0,(x,y),ds;
  ideal i=x2+y2,x2-y2;
  ideal j=std(i);
  vdim(j);
@c example
@end smallexample
@end table
@c ref
See
@ref{ideal};
@ref{std};
@ref{dim};
@ref{degree};
@ref{mult};
@ref{kbase};
@ref{codim}.
@c ref
@c ---------------------------------------
@node wedge, weight, vdim, Functions
@subsection wedge
@cindex wedge
@table @code
@item @strong{Syntax:}
@code{wedge (} matrix_expression@code{,} int_expression @code{)}
@item @strong{Type:}
matrix
@item @strong{Purpose:}
@code{wedge(M,n)} computes the @code{n}-th exterior power of the matrix
@code{M}.
@item @strong{Example:}
@smallexample
@c example
  ring r;
  matrix m[2][3]=x,y,y,z,z,x;
  print(m);
  print(wedge(m,2));
@c example
@end smallexample
@end table
@c ref
See
@ref{matrix};
@ref{minor};
@ref{int}.
@c ref
@c ---------------------------------------
@node weight, weightKB, wedge, Functions
@subsection weight
@cindex weight
@table @code
@item @strong{Syntax:}
@code{weight (} ideal_expression @code{)}
@*@code{weight (} module_expression @code{)}
@item @strong{Type:}
intvec
@item @strong{Purpose:}
computes an "optimal" weight vector for an ideal, resp.@: module,
which may be used as weight vector for the variables in order to speed
up the standard basis algorithm. If the input is weighted homogeneous,
a weight vector for which the input is weighted homogeneous is found.
@item @strong{Example:}
@smallexample
@c example
  ring h1=32003,(t,x,y,z),dp;
  ideal i=
  9x8+y7t3z4+5x4y2t2+2xy2z3t2,
  9y8+7xy6t+2x5y4t2+2x2yz3t2,
  9z8+3x2y3z2t4;
  intvec e=weight(i);
  e;
  ring r=32003,(a,b,c,d),wp(e);
  map f=h1,a,b,c,d;
  ideal i0=std(f(i));
@c example
@end smallexample
@end table
@c ref
See
@ref{ideal};
@ref{intvec};
@ref{qhweight}.
@c ref
@c ---------------------------------------
@node weightKB, write, weight, Functions
@subsection weightKB
@cindex weightKB
@c lib standard.lib:weightKB lib_fun lib_ex subsection

@c ---------------------------------------
@node  write,  , weightKB, Functions
@subsection write
@cindex write
@table @code
@item @strong{Syntax:}
@code{write (} link_expression@code{,} expression_list @code{)}
@*for DBM links:
@*@code{write (} link@code{,} string_expression@code{,} string_expression @code{)}
@*@code{write (} link@code{,} string_expression @code{)}
@item @strong{Type:}
none
@item @strong{Purpose:}
writes data to a link.
@*If the link is of type @code{ASCII}, all expressions are converted to
strings  (and separated by a newline character) before they are
written. As a consequence, only such values which can be converted to a
string can be written to an  @code{ASCII} link.
@*For MP links,
ring-dependent expressions are written together with a ring
description. To prevent an evaluation of the expression before it is
written, the @code{quote} command (possibly together with @code{eval})
can be used. A @code{write} blocks (i.e., does not return to the prompt),
as long as a MPtcp link is not ready for writing.
@*For DBM links, @code{write} with three arguments inserts the first
string as key and the second string as value into the dbm data
base.
@*Called with two arguments, it deletes the entry with the key
specified by the string from the data base.
@item @strong{Example:}
@smallexample
// write the values of the variables f and i as strings into
// the file "outfile" (overwrite it, if it exists)
write(":w outfile",f,i);

// now append the string "that was f,i" (without the quotes)
// at the end of the file "outfile"
write(":a outfile","that was f,i");
// alternatively, links could be used:
link l=":a outfile"; l;
// type : ASCII
// mode : a
// name : outfile
// open : no
// read : not ready
// write: not ready
write(l," that was f,i");
// saving and retrieving data (ASCII format):
ring r=32003,(x,y,z),dp;
ideal i=x+y,z3+22y;
write(":w save_i",i);// this writes x+y,z3+22y to the file save_i
ring r=32003,(x,y,z),dp;
string s=read("save_i");   //creates the string x+y,z3+22y
execute("ideal k="+s+";"); // this defines an ideal k which
                           // is equal to i.
// for large objects, the MP format and MPfile links are better:
write("MPfile:w save_i.mp",i);
def j=read("MPfile:r save_i.mp");
@end smallexample
@end table
@c ref
See
@ref{read};
@ref{link};
@ref{Data types};
@ref{quote};
@ref{eval};
@ref{dump};
@ref{print};
@ref{printf};
@ref{short}.
@c ref


@c ---------------------------------------
@node Control structures, System variables, Functions, Functions and system variables
@section Control structures
@cindex Control structures
@cindex block
@ifinfo
@*List of all supported control structures.
@end ifinfo
@menu
* break::
* breakpoint::
* continue::
* else::
* export::
* exportto::
* for::
* if::
* importfrom::
* keepring::
* load::
* quit::
* return::
* while::
* ~::
@end menu

A sequence of commands surrounded by curly brackets (@code{@{} and
@code{@}}) is a so called block. Blocks are used in @sc{Singular} in
order to define procedures and to collect commands belonging to
@code{if}, @code{else}, @code{for} and @code{while} statements and to the
@code{example} part in libraries. Even if
the sequence of statements consists of only a single command it has to be
surrounded by curly brackets!
Variables which are defined inside a block
are not local to that block. Note that there is no ending semicolon at
the end of the block.
@table @code
@item @strong{Example:}
@smallexample
if ( i>j )
@{
  // This is the block
  int temp;
  temp=i;
  i=j;
  j=temp;
  kill temp;
@}
@end smallexample
@end table

@c ---------------------------------------
@node break, breakpoint, Control structures, Control structures
@subsection break
@cindex break
@table @code
@item @strong{Syntax:}
@code{break;}
@item @strong{Purpose:}
leaves the innermost @code{for} or @code{while} block.
@item @strong{Example:}
@smallexample
while (1)
@{
  @dots{}
  if ( @dots{} )
  @{
    break; // leave the while block
  @}
@}
@end smallexample
@end table
@c ref
See
@ref{Control structures};
@ref{for};
@ref{while}.
@c ref
@c ---------------------------------------
@node breakpoint, continue, break, Control structures
@subsection breakpoint
@cindex breakpoint
@table @code
@item @strong{Syntax:}
@code{breakpoint(} proc_name @code{);}
@*@code{breakpoint(} proc_name@code{,} line_no @code{);}
@item @strong{Purpose:}
sets a breakpoint at the beginning of the specified procedure or
at the given line.
@strong{Note:} Line number 1 is the first line of a library (for
procedures from libraries), resp.@: the line with the @code{@{}.
@*A line number of -1 removes all breakpoint from that procedure.
@item @strong{Example:}
@smallexample
@c example
breakpoint(groebner);
breakpoint(groebner, 176);
breakpoint(groebner, -1);
@c example
@end smallexample
@end table
@c ref
See
@ref{~};
@ref{Source code debugger}.
@c ref
@c ---------------------------------------
@node continue, else, breakpoint, Control structures
@subsection continue
@cindex continue
@table @code
@item @strong{Syntax:}
@code{continue;}
@item @strong{Purpose:}
skips the rest of the innermost @code{for} or @code{while} loop und jumps
to the beginning of the block. This command is only valid inside a
@code{for} or a @code{while} construction.
@item @strong{Note:}
Unlike the C-construct it @strong{does not execute the increment statement}.
The command @code{continue} is mainly for internal use.
@item @strong{Example:}
@smallexample
for (int i = 1 ; i<=10; i=i+1)
@{
   @dots{}
   if (i==3) @{ i=8;continue; @}
     // skip the rest if i is 3 and
     // continue with the next i: 8
   i;
@}
@expansion{} 1
@expansion{} 2
@expansion{} 8
@expansion{} 9
@expansion{} 10
@end smallexample
@end table
@c ref
See
@ref{Control structures};
@ref{for};
@ref{while}.
@c ref
@c ---------------------------------------
@node else, export, continue, Control structures
@subsection else
@table @code
@item @strong{Syntax:}
@code{if (} boolean_expression @code{)} true_block @code{else} false_block
@item @strong{Purpose:}
executes false_block if the boolean_expression of the @code{if} statement
is false. This command is only valid in combination with an @code{if}
command.
@item @strong{Example:}
@smallexample
int i=3;
if (i > 5)
@{
  "i is bigger than 5";
@}
else
@{
  "i is smaller than 6";
@}
@expansion{} i is smaller than 6
@end smallexample
@end table
@c ref
See
@ref{if};
@ref{boolean expressions};
@ref{Control structures}.
@c ref
@c ---------------------------------------
@node export, exportto, else, Control structures
@subsection export
@cindex export
@table @code
@item @strong{Syntax:}
@code{export} name @code{;}
@*@code{export} list_of_names @code{;}
@item @strong{Purpose:}
converts a local variable of a procedure to a global one, that is the
identifier is not removed at the end of the procedure.
However, the package the variable belongs to, is not changed.
@item @strong{Note:}
Objects defined in a ring are not automatically exported
when exporting the ring.
@item @strong{Example:}
@smallexample
proc p1
@{
  int i,j;
  export(i);
  intmat m;
  listvar();
  export(m);
@}
p1();
@expansion{} // m                    [1]  intmat 1 x 1
@expansion{} // j                    [1]  int 0
@expansion{} // i                    [0]  int 0
listvar();
@expansion{} // m                    [0]  intmat 1 x 1
@expansion{} // i                    [0]  int 0
@end smallexample
@end table

@c ref
See
@ref{exportto};
@ref{importfrom};
@ref{keepring}.
@c ref
@c ---------------------------------------
@node exportto, for, export, Control structures
@subsection exportto
@cindex exportto
@table @code
@item @strong{Syntax:}
@code{exportto(} package_name @code{, }name @code{);}
@*@code{exportto(} package_name @code{,} list_of_names @code{);}
@item @strong{Purpose:}
transfers an identifier in the current package into the one specified by
package_name. package_name can be @code{Current}, @code{Top}
or any other identifier of type package.

@item @strong{Note:}
Objects defined in a ring are not automatically exported
when exporting the ring.

@item @strong{Warning:}
The identifier is transfered to the other package. It does no longer
exist in the current package. If the identifier should only be copied,
@ref{importfrom} should be used instead.

@item @strong{Example:}

@smallexample
@c example
proc p1
{
  int i,j;
  exportto(Current,i);
  intmat m;
  listvar(Current);
  exportto(Top,m);
}
p1();
package Test1;
exportto(Test1,p1);
listvar(Top);
listvar(Test1);
Test1::p1();
listvar(Top);
listvar(Test1);
@c example
@end smallexample
@end table
@c ref
See
@ref{export};
@ref{importfrom};
@ref{keepring}.
@c ref
@c ---------------------------------------
@node for, if, exportto, Control structures
@subsection for
@cindex for
@table @code
@item @strong{Syntax:}
@code{for (} init_command@code{;}
boolean_expression@code{;}
iterate_commands@code{)} block
@item @strong{Purpose:}
repetitive, conditional execution of a command block.
@*The command init_command is executed first. Then boolean_expression is
evaluated. If its value is TRUE the block is executed, otherwise the
@code{for} statement is complete. After each execution of the block, the
command iterate_command is executed and boolean_expression is
evaluated. This is repeated until boolean_expression evaluates to FALSE.
@*The command @code{break;} leaves the innermost @code{for} construct.
@item @strong{Example:}
@smallexample
// sum of 1 to 10:
int s=0;
for (int i=1; i<=10; i=i+1)
@{
   s=s+i;
@}
s;
@expansion{} 55
@end smallexample
@end table
@c ref
See
@ref{Control structures};
@ref{boolean expressions};
@ref{while};
@ref{if};
@ref{break};
@ref{continue}.
@c ref
@c ---------------------------------------
@node if, importfrom, for, Control structures
@subsection if
@cindex if
@cindex else
@table @code
@item @strong{Syntax:}
@code{if (} boolean_expression @code{)} true_block
@*@code{if (} boolean_expression @code{)} true_block @code{else} false_block
@item @strong{Purpose:}
executes true_block if the boolean condition is true. If the @code{if}
statement is followed by an @code{else} statement and the boolean
condition is false, then false_block is executed.
@item @strong{Example:}
@smallexample
int i = 9;
matrix m[i][i];
if (i > 5 and typeof(m) == "matrix")
@{
  m[i][i] = i;
@}
@end smallexample
@end table
@c ref
See
@ref{else};
@ref{break};
@ref{Control structures};
@ref{boolean expressions}.
@c ref
@c ---------------------------------------
@node importfrom, keepring, if, Control structures
@subsection importfrom
@cindex importfrom
@table @code
@item @strong{Syntax:}
@code{importfrom(} package_name @code{, }name @code{);}
@*@code{importfrom(} package_name @code{,} list_of_names @code{);}
@item @strong{Purpose:}
creates a new identifier in the current package which is a copy of the
one specified by name in the package package_name. package_name can be
@code{Top} or any other identifier of type package.

@item @strong{Note:}
Objects defined in a ring are not automatically imported
when importing the ring.

@item @strong{Warning:}
The identifier is copied to the current package. It does still exist
(independently) in the package package_name. If the identifier should
be erased in the package from which it originates, @ref{exportto} should
be used instead.

@item @strong{Example:}
@smallexample
@c example
listvar(Top);
load("inout.lib");
listvar(Top);
importfrom(Inout,pause);
listvar(Top);
@c example
@end smallexample
@end table

@c ref
See
@ref{export};
@ref{exportto};
@ref{keepring}.
@c ref
@c ---------------------------------------
@node keepring, load, importfrom, Control structures
@subsection keepring
@cindex keepring
@table @code
@item @strong{Syntax:}
@code{keepring} name @code{;}
@item @strong{Warning:}
This command is obsolete. Instead the respective identifiers in the ring
should be exported and the ring itself should subsequently be returned.
The command is only included for backward compatibility and may be
removed in future releases.

@item @strong{Purpose:}
moves the specified ring to the next (upper) level. This command can only
be used inside of procedures and it should be the last command before the
@code{return} statement. There it provides the possibility to keep
a ring which is local to the procedure (and its objects) accessible after
the procedure ended without making the ring global.

@item @strong{Example:}
@smallexample
proc P1
@{
  ring r=0,x,dp;
  keepring r;
@}
proc P2
@{
  "inside P2: " + nameof(basering);
  P1();
  "inside P2, after call of P1: " + nameof(basering);
@}
ring r1= 0,y,dp;
P2();
@expansion{} inside P2: r1
@expansion{} inside P2, after call of P1: r
"at top level: " + nameof(basering);
@expansion{} at top level: r1
@end smallexample
@end table
@c ref
See
@ref{ring}.
@c ref
@c ---------------------------------------
@node load, quit, keepring, Control structures
@subsection load
@cindex load
@table @code
@item @strong{Syntax:}
@code{load(} string_expression @code{);}
@item @strong{Type:}
none
@item @strong{Purpose:}
@c reads a library of procedures or functions from a file. If the given
@c filename does not start with  @kbd{~}, @kbd{.} or @kbd{/}, the following
@c directories are searched for (in that order): the current directory, the
@c directories given in the environment variable @code{SINGULARPATH}, some
@c default directories relative to the location of the @sc{Singular}
@c executable program, and finally some default absolute directories. You
@c can view the search path which @sc{Singular} uses to locate its
@c libraries, by starting up @sc{Singular} with the option @code{-v}, or by
@c issuing the command @code{system("with");"}.
reads a library of procedures from a file. In contrast to the command
@code{LIB}, the command @code{load} does not add the procedures of the
library to the package @code{Top}, but only to the package corresponding
to the library. If the given filename does
not start with @kbd{.} or @kbd{/}, the following directories are
searched for it (in the given order): the current directory, the
directories given in the environment variable @code{SINGULARPATH}, some
default directories relative to the location of the @sc{Singular}
executable program, and finally some default absolute directories.
You can view the search path which @sc{Singular} uses to locate its
libraries, by starting up @sc{Singular} with the option @code{-v},
or by issuing the command @code{system("with");}.

@end table

All loaded libraries are displayed by the @code{listvar(package);}
command:
@smallexample
@c example
  option(loadLib);   // show loading of libraries;
                     // standard.lib is loaded
  listvar(package);
                     // the names of the procedures of inout.lib
  load("inout.lib"); // are now known to Singular
  listvar(package);
@c example
@end smallexample

Each time a library (@ref{Libraries}) / dynamic module (@ref{Dynamic
loading}) is loaded, the corresponding package is created, if it does
not already exist.

The name of a package corresponding to a Singular library is
derived from the name of the library file. The first letter is
capitalized and everything to right of the left-most dot is
dropped.
For a dynamic module the packagename is hard-coded in the binary file.

Only the names of the procedures in the library are loaded, the body of
the procedures is read during the first call of this procedure. This minimizes
memory consumption by unused procedures.  When @sc{Singular} is started
with the @code{-q} or @code{--quiet} option, no message about the
loading of a library is displayed.

@smallexample
@c example
  option(loadLib); // show loading of libraries; standard.lib is loaded
                   // the names of the procedures of inout.lib
  load("inout.lib"); // are now known to Singular
  listvar();
@c example
@end smallexample
@c ref
See
@ref{Command line options};
@ref{Procedures and libraries};
@ref{SINGULAR libraries};
@ref{proc};
@ref{standard_lib};
@ref{package};
@ref{string};
@ref{system};
@ref{LIB};
@ref{exportto};
@ref{importfrom};
@ref{Dynamic modules}.
@c ref
@c ---------------------------------------
@node quit, return, load, Control structures
@subsection quit
@cindex quit
@cindex exit
@anchor{exit}
@table @code
@item @strong{Syntax:}
@code{quit;}
@item @strong{Purpose:}
quits @sc{Singular};
works also from inside a procedure or from an interrupt. Instead of @code{quit}, the synonymous command
@code{exit} may be used.
@item @strong{Example:}
@smallexample
  quit;
@end smallexample
@end table
@c ref
See
@ref{exit}.
@c ref
@c ---------------------------------------
@node return, while, quit, Control structures
@subsection return
@cindex return
@table @code
@item @strong{Syntax:}
@code{return (} expression_list @code{);}
@*@code{return ();}
@item @strong{Type:}
any
@item @strong{Purpose:}
returns the result(s) of a procedure and can only be used inside a
procedure. Note that the brackets are required even if no return value
is given.
@item @strong{Example:}
@smallexample
proc p2
@{
  int i,j;
  for(i=1;i<=10;i++)
  @{
    j=j+i;
  @}
  return(j);
@}
// can also return an expression list, i.e., more than one value
proc tworeturn ()
@{ return (1,2); @}
int i,j = tworeturn();
// return type may even depend on the input
proc type_return (int i)
@{
  if (i > 0) @{return (i);@}
  else @{return (list(i));@}
@}
// then we need def type (or list) to collect value
def t1 = type_return(1);
def t2 = type_return(-1);
@end smallexample
@end table
@c ref
See
@ref{Data types};
@ref{proc}.
@c ref
@c ---------------------------------------
@node while, ~ , return, Control structures
@subsection while
@cindex while
@table @code
@item @strong{Syntax:}
@code{while (}boolean_expression@code{)} block
@item @strong{Purpose:}
repetitive, conditional execution of block.
@*The boolean_expression is evaluated and if its value is TRUE, the
block gets executed. This is repeated until boolean_expression evaluates
to FALSE.  The command @code{break} leaves the innermost @code{while}
construction.
@item @strong{Example:}
@smallexample
int i = 9;
while (i>0)
@{
   // @dots{} // do something for i=9, 8, ..., 1
   i = i - 1;
@}
while (1)
@{
   // @dots{}   // do something forever
   if (i == -5) // but leave the loop if i is -5
   @{
     break;
   @}
@}
@end smallexample
@end table
@c ref
See
@ref{Control structures};
@ref{boolean expressions};
@ref{break}.
@c ref

@c ---------------------------------------
@node ~, , while, Control structures
@subsection ~ (break point)
@cindex ~
@cindex break point
@table @code
@item @strong{Syntax:}
@code{~;}
@item @strong{Purpose:}
sets a break point. Whenever @sc{Singular} reaches the command @code{~;}
in a sequence of commands it prompts for input. The user may now input
lines of @sc{Singular} commands. The line length cannot exceed 80
characters.
@sc{Singular} proceeds with the execution of the command following @code{~;}
as soon as it receives an empty line.
@item @strong{Example:}
@smallexample
proc t
@{
  int i=2;
  ~;
  return(i+1);
@}
t();
@expansion{} -- break point in t --
@expansion{} -- 0: called    from STDIN --
// here local variables of the procedure can be accessed
i;
@expansion{} 2
@expansion{} -- break point in t --

@expansion{} 3
@end smallexample
@end table
@c ref
See
@ref{Break points}.
@c ref

@c ---------------------------------------
@node System variables,  , Control structures, Functions and system variables
@section System variables
@cindex System variables
@ifinfo
@*List of all system variables.
@end ifinfo
@menu
* degBound::
* echo::
* minpoly::
* multBound::
* noether::
* printlevel::
* short::
* timer::
* TRACE var::
* rtimer::
* voice::
@end menu
@c ---------------------------------------
@node degBound, echo, System variables, System variables
@subsection degBound
@cindex degBound
@table @code
@item @strong{Type:}
int
@item @strong{Purpose:}
The standard basis computation is stopped if the total
(weighted) degree
exceeds @code{degBound}.
@* @code{degBound} should not be used for a global ordering with inhomogeneous
input.
@*Reset this bound by setting @code{degBound} to 0.
@*The exact meaning of "degree" depends on the ring odering and the command:
@code{slimgb} uses always the total degree with weights 1,
@code{std} does so only for block orderings.
@item @strong{Example:}
@smallexample
degBound = 7;
option();
@expansion{} //options for 'std'-command: degBound
ideal j=std(i);
degBound;
@expansion{} 7
degBound = 0; //resets degree bound to infinity
@end smallexample
@end table
@c ref
See
@ref{deg};
@ref{int};
@ref{option};
@ref{std}.
@c ref
@c -----------------------------------------------------
@node echo, minpoly, degBound, System variables
@subsection echo
@cindex echo
@table @code
@item @strong{Type:}
int
@item @strong{Purpose:}
input is echoed if @code{echo} >= @code{voice}.
@*@code{echo} is a local setting for a procedure and defaulted to 0.
@*@code{echo} does not affect the output of commands.
@item @strong{Example:}
@c this example cannot be a computed one - echo interferes with -e
@smallexample
echo = 1;
int i = echo;
@expansion{} int i = echo;
@end smallexample
@end table
@c ref
See
@ref{int};
@ref{voice}.
@c ref
@c -----------------------------------------------------
@node minpoly, multBound, echo, System variables
@subsection minpoly
@cindex minpoly
@table @code
@item @strong{Type:}
number
@item @strong{Purpose:}
describes the coefficient field of the current basering as
an algebraic extension with the minimal polynomial equal to @code{minpoly}.
Setting the @code{minpoly} should be the first command after
defining the ring.
@item @strong{Note:}
The minimal polynomial has to be specified in the syntax of a polynomial.
Its variable is not one of the ring variables, but the algebraic element
which is being adjoined to the field.
Algebraic extensions in @sc{singular} are only possible over the rational
numbers or over Z/p, p a prime number.
@c @*@strong{Warning:}
@*@sc{Singular} does not check whether the given
polynomial is irreducible! It can be checked in advance with the
function @code{factorize} (@pxref{factorize}).
@item @strong{Example:}
@smallexample
@c example
  //(Q[i]/(i^2+1))[x,y,z]:
  ring Cxyz=(0,i),(x,y,z),dp;
  minpoly=i^2+1;
  i2;  //this is a number, not a poly
@c example
@end smallexample
@end table
@c ref
See
@ref{factorize};
@ref{ring}.
@c ref
@c -----------------------------------------------------
@node multBound, noether, minpoly, System variables
@subsection multBound
@cindex multBound
@table @code
@item @strong{Type:}
int
@item @strong{Purpose:}
The standard basis computation is stopped if the ideal is
zero-dimensional in a ring with local ordering
and its multiplicity (@code{mult}) is lower than @code{multBound}.
@*Reset this bound by setting @code{multBound} to 0.
@item @strong{Example:}
@smallexample
ring r=0,(x,y,z),ds;
ideal i,j;
i=x7+y7+z6,x6+y8+z7,x7+y5+z8,
x2y3+y2z3+x3z2,x3y2+y3z2+x2z3;
multBound=100;
j=std(i);
degree(j);
multBound=0;  //disables multBound
j=std(i);
degree(j);
@end smallexample
@end table
@c ref
See
@ref{int};
@ref{mult};
@ref{option};
@ref{std}.
@c ref
@c -----------------------------------------------------
@node noether, printlevel, multBound, System variables
@subsection noether
@cindex noether
@table @code
@item @strong{Type:}
poly
@item @strong{Purpose:}
The standard basis computation in local rings
cuts off  all monomials above
(in the sense of the monomial ordering)
the monomial @code{noether} during the computation.
@*Reset @code{noether} by setting @code{noether} to 0.
@item @strong{Example:}
@smallexample
@c example
  ring R=32003,(x,y,z),ds;
  ideal i=x2+y12,y13;
  std(i);
  noether=x11;
  std(i);
  noether=0; //disables noether
@c example
@end smallexample
@end table
@c ref
See
@ref{poly};
@ref{std}.
@c ref
@c -----------------------------------------------------
@node printlevel, short, noether, System variables
@subsection printlevel
@cindex printlevel
@table @code
@item @strong{Type:}
int
@item @strong{Purpose:}
sets the debug level for @code{dbprint}.
If @code{printlevel} >= @code{voice} then @code{dbprint} is equivalent to
@code{print}, otherwise nothing is printed.
@item @strong{Note:}
@xref{Procedures in a library}, for a small example about how this
is used for the display of comments while procedures are executed.
@item @strong{Example:}
@smallexample
@c example
  voice;
  printlevel=0;
  dbprint(1);
  printlevel=voice;
  dbprint(1);
@c example
@end smallexample
@end table
@c ref
See
@ref{int};
@ref{dbprint};
@ref{voice}.
@c ref
@c -----------------------------------------------------
@node short, timer, printlevel, System variables
@subsection short
@cindex short
@table @code
@item @strong{Type:}
int
@item @strong{Purpose:}
the output of monomials is done in the short manner,
if @code{short} is non-zero. A C-like notion is used, if short is zero.
Both notations may be used as input.
@*The default depends on the names of the ring variables
(0 if there are names of variables longer than 1 character, 1 otherwise). Every
change of the basering sets @code{short} to the previous value for
that ring. In other words, the value of the variable @code{short} is
"ring-local".
@item @strong{Example:}
@smallexample
@c example
  ring r=23,x,dp;
  int save=short;
  short=1;
  2x2,x2;
  short=0;
  2x2,x2;
  short=save;  //resets short to the previous value
@c example
@end smallexample
@end table
@c ref
See
@ref{int}.
@c ref
@c -----------------------------------------------------
@node timer, TRACE var, short, System variables
@subsection timer
@cindex timer
@table @code
@item @strong{Type:}
int
@item @strong{Purpose:}
@enumerate
@item
the CPU time (i.e, user and system time) used for each command is
printed if timer >0 , if this
time is bigger than a (customizable) minimal time and
if @code{printlevel+1 >= voice} (which is by default true on the
@sc{Singular} top level, but not true while procedures are executed).

@item
yields the used CPU time since the start-up of @sc{Singular} in a
(customizable) resolution.
@end enumerate

The default setting of @code{timer} is 0, the default minimal time is
0.5 seconds, and the default timer resolution is 1 (i.e., the default unit
of time is one second). The minimal time and timer resolution
can be set using the command line options @code{--min-time} and
@code{--ticks-per-sec} and can be checked using
@code{system("--min-time")} and @code{system("--ticks-per-sec")}.

How to use @code{timer} in order to measure the time for a sequence of
commands, see example below.

@item @strong{Note for Windows95/98:}
The value of the @code{timer} cannot be used (resp.@: trusted) when
@sc{Singular} is run under Windows95/98 (this is due to the shortcomings
of the Windows95/98 operating system). Use @ref{rtimer}, instead.

@item @strong{Example:}
@smallexample
@c example
  timer=1; // The time of each command is printed
  int t=timer; // initialize t by timer
  ring r=0,(x,y,z),dp;
  poly p=(x+2y+3z+4xy+5xz+6yz)^20;
  // timer as int_expression:
  t=timer-t;
  t;  // yields the time in ticks-per-sec (default 1)
      // since t was initialized by timer
  int tps=system("--ticks-per-sec");
  t/tps; // yields the time in seconds truncated to int
@c example
@end smallexample
@end table
@c ref
See
@ref{Command line options};
@ref{printlevel};
@ref{rtimer};
@ref{system};
@ref{voice}.
@c ref
@c ---------------------------------------
@node TRACE var, rtimer, timer, System variables
@subsection TRACE
@cindex TRACE

@table @code
@item @strong{Type:}
int
@item @strong{Purpose:}
sets level of debugging.
@table @asis
@item @code{TRACE=0}
no debugging messages are printed.
@item @code{TRACE=1}
messages about entering and leaving of procedures are displayed.
@item @code{TRACE=3}
messages about entering and leaving of procedures together with
line numbers are displayed.
@item @code{TRACE=4}
each line is echoed and the interpretation of commands
in this line is suspended until the user presses @code{RETURN}.
@end table
@*@code{TRACE} is defaulted to 0.
@*@code{TRACE} does not affect the output of commands.
@item @strong{Example:}
@smallexample
@c example
  TRACE=1;
  LIB "general.lib";
  sum(1..100);
@c example
@end smallexample
@end table
@c ref
See
@ref{int}.
@c ref
@c ---------------------------------------
@node rtimer, voice, TRACE var, System variables
@subsection rtimer
@cindex timer
@table @code
@item @strong{Type:}
int
@item @strong{Purpose:}
identical to @code{timer} (@pxref{timer}), except that real times (i.e.,
wall-clock) times are reported, instead of CPU times. This can be
trusted on all operating systems (including Windows95/98).

@end table
@c ---------------------------------------
@node voice,, rtimer, System variables
@subsection voice
@cindex voice

@table @code
@item @strong{Type:}
int
@item @strong{Purpose:}
shows the nesting level of procedures.
@item @strong{Note:}
@xref{Guidelines for writing a library}, for a small example how this is used
for the display of comments while procedures are executed.
@item @strong{Example:}
@smallexample
@c example
  voice;
@c example
proc p
@{
  voice;
@};
p();
@expansion{} 2
@end smallexample
@end table
@c ref
See
@ref{dbprint};
@ref{listvar};
@ref{printlevel}.
@c ref
@c ---------------------------------------