code:
@comment -*-texinfo-*-
@comment This file was generated by doc2tex.pl from reference.doc
@comment DO NOT EDIT DIRECTLY, BUT EDIT reference.doc INSTEAD
@comment Id: reference.tex,v 1.1 2003/08/08 14:27:06 pertusus 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).  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.hlp
@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{kill},
@code{setring}, @code{type}) the brackets are optional. For the commands
@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::
* 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::
* gcd::
* gen::
* getdump::
* groebner::
* help::
* highcorner::
* hilb::
* homog::
* hres::
* imap::
* impart::
* indepSet::
* insert::
* interred::
* intersect::
* jacob::
* jet::
* kbase::
* 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::
* quot::
* quote::
* quotient::
* random::
* read::
* reduce::
* regularity::
* repart::
* res::
* reservedName::
* resultant::
* rvar::
* setring::
* simplex::
* simplify::
* size::
* sortvec::
* sprintf::
* sres::
* status::
* std::
* stdfglm::
* stdhilb::
* subst::
* system::
* syz::
* trace::
* transpose::
* type::
* typeof::
* uressolve::
* vandermonde::
* var::
* varstr::
* vdim::
* wedge::
* weight::
* 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 reused example attrib reference.doc:209
  ring r=0,(x,y,z),dp;
  ideal I=std(maxideal(2));
  attrib(I);
@expansion{} attr:isSB, type int
@c end example attrib reference.doc:209
@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 reused example attrib_1 reference.doc:225
  ring r=0,(x,y,z),dp;
  ideal I=std(maxideal(2));
  attrib(I,"isSB");
@expansion{} 1
  // although maxideal(2) is a standard basis,
  // SINGULAR does not know it:
  attrib(maxideal(2), "isSB");
@expansion{} 0
@c end example attrib_1 reference.doc:225
@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 reused example attrib_2 reference.doc:243
  ring r=0,(x,y,z),dp;
  ideal I=maxideal(2); // the attribute "isSB" is not set
  vdim(I);
@expansion{} // ** I is no standardbasis
@expansion{} 4
  attrib(I,"isSB",1);  // the standard basis attribute is set here
  vdim(I);
@expansion{} 4
@c end example attrib_2 reference.doc:243
@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:}
(not all are in use at the moment)
@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})
@c @item @code{D}
@c object is an differential operator, if set to 1;
@c @*object is in a module, if set to 0
@c @*only valid in a dring (see @ref{dring}).
@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 l became row k.
@* The further parameters control the algorithm. @code{bareiss(M,i,j)}
does not consider 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 reused example bareiss reference.doc:324
  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);
@expansion{} 3x, 0,  11z,0,  0,  7y, 0,
@expansion{} 0,  3x, 0,  11z,0,  0,  7y,
@expansion{} 7y, 0,  3x, 0,  11z,0,  0,
@expansion{} 0,  7y, 0,  3x, 0,  11z,0,
@expansion{} 0,  0,  7y, 0,  3x, 0,  11z,
@expansion{} 11z,0,  0,  7y, 0,  3x, 0,
@expansion{} 0,  11z,0,  0,  7y, 0,  3x
  // complete elimination
  list ss=bareiss(mm);
  print(ss[1]);
@expansion{} 7y, 0,     0,     0,      0,        0,     0,
@expansion{} 3x, -33xz, 0,     0,      0,        0,     0,
@expansion{} 11z,-121z2,1331z3,0,      0,        0,     0,
@expansion{} 0,  0,     0,     9317yz3,0,        0,     0,
@expansion{} 0,  21xy,  _[5,3],14641z4,-43923xz4,0,     0,
@expansion{} 0,  0,     0,     0,      65219y2z3,_[6,6],0,
@expansion{} 0,  49y2,  _[7,3],3993xz3,_[7,5],   _[7,6],_[7,7]
  ss[2];
@expansion{} 2,7,5,1,4,3,6
  // elimination up to 3 vectors
  ss=bareiss(mm,0,3);
  print(ss[1]);
@expansion{} 7y, 0,     0,     0,      0,        0,        0,
@expansion{} 3x, -33xz, 0,     0,      0,        0,        0,
@expansion{} 11z,-121z2,1331z3,0,      0,        0,        0,
@expansion{} 0,  0,     0,     9317yz3,0,        0,        0,
@expansion{} 0,  0,     0,     0,      27951xyz3,102487yz4,65219y2z3,
@expansion{} 0,  21xy,  _[6,3],14641z4,_[6,5],   _[6,6],   -43923xz4,
@expansion{} 0,  49y2,  _[7,3],3993xz3,_[7,5],   _[7,6],   _[7,7]
  ss[2];
@expansion{} 2,7,5,1,3,4,6
  // elimination without the last 3 rows
  ss=bareiss(mm,3,0);
  print(ss[1]);
@expansion{} 7y, 0,   0,      0,       0,     0,     0,
@expansion{} 0,  77yz,0,      0,       0,     0,     0,
@expansion{} 0,  0,   231xyz, 0,       0,     0,     0,
@expansion{} 0,  0,   0,      1617xy2z,0,     0,     0,
@expansion{} 11z,21xy,-1331z3,14641z4, _[5,5],_[5,6],_[5,7],
@expansion{} 0,  0,   539y2z, _[6,4],  _[6,5],_[6,6],-3773y3z,
@expansion{} 3x, 49y2,-363xz2,3993xz3, _[7,5],_[7,6],_[7,7]
  ss[2];
@expansion{} 2,3,4,1
@c end example bareiss reference.doc:324
@end smallexample
@end table
@c inserted refs from reference.doc:354
@ifinfo
@menu
See
* det::
* matrix::
@end menu
@end ifinfo
@iftex
See
@ref{det};
@ref{matrix}.
@end iftex
@c end inserted refs from reference.doc:354
@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.

The optional second argument is a switch for the minimization of the Betti
numbers. If it is 0 then the Betti numbers correspond exactly to the input -
otherwise the command is identical to the one-argument form.
@item @strong{Example:}
@smallexample
@c reused example betti reference.doc:408
  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]);
@expansion{} bc-ad,
@expansion{} c3-bd2,
@expansion{} ac2-b2d,
@expansion{} b3-a2c
  // second syzygy module of r/j which is the first
  // syzygy module of j (minimal generating set):
  print(T[2]);
@expansion{} bd,c2,ac,b2,
@expansion{} -a,-b,0, 0,
@expansion{} c, d, -b,-a,
@expansion{} 0, 0, -d,-c
  // the second syzygy module (minimal generating set):
  print(T[3]);
@expansion{} -b,
@expansion{} a,
@expansion{} -c,
@expansion{} d
  print(T[4]);
@expansion{} 0
  betti(T);
@expansion{} 1,0,0,0,
@expansion{} 0,1,0,0,
@expansion{} 0,3,4,1
  // most useful for reading off the graded Betti numbers:
  print(betti(T),"betti");
@expansion{}            0     1     2     3
@expansion{} ------------------------------
@expansion{}     0:     1     -     -     -
@expansion{}     1:     -     1     -     -
@expansion{}     2:     -     3     4     1
@expansion{} ------------------------------
@expansion{} total:     1     4     4     1
@c end example betti reference.doc:408
@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 inserted refs from reference.doc:455
@ifinfo
@menu
See
* Syzygies and resolutions::
* hres::
* lres::
* mres::
* print::
* res::
* resolution::
* sres::
@end menu
@end ifinfo
@iftex
See
@ref{Syzygies and resolutions};
@ref{hres};
@ref{lres};
@ref{mres};
@ref{print};
@ref{res};
@ref{resolution};
@ref{sres}.
@end iftex
@c end inserted refs from reference.doc:455
@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 reused example char reference.doc:480
  ring r=32003,(x,y),dp;
  char(r);
@expansion{} 32003
  ring s=0,(x,y),dp;
  char(s);
@expansion{} 0
  ring ra=(7,a),(x,y),dp;
  minpoly=a^3+a+1;
  char(ra);
@expansion{} 7
  ring rp=(49,a),(x,y),dp;
  char(rp);
@expansion{} 7
  ring rr=real,x,dp;
  char(rr);
@expansion{} 0
@c end example char reference.doc:480
@end smallexample
@end table
@c inserted refs from reference.doc:495
@ifinfo
@menu
See
* charstr::
* ring::
@end menu
@end ifinfo
@iftex
See
@ref{charstr};
@ref{ring}.
@end iftex
@c end inserted refs from reference.doc:495
@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 reused example char_series reference.doc:516
  ring r=32003,(x,y,z),dp;
  print(char_series(ideal(xyz,xz,y)));
@expansion{} y,z,
@expansion{} x,y
@c end example char_series reference.doc:516
@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 pseudo remainder $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 pseudo remainder 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 inserted refs from reference.doc:592
@ifinfo
@menu
See
* Characteristic sets::
@end menu
@end ifinfo
@iftex
See
@ref{Characteristic sets}.
@end iftex
@c end inserted refs from reference.doc:592
@c ---------------------------------------
@node charstr, cleardenom, 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 reused example charstr reference.doc:610
  ring r=32003,(x,y),dp;
  charstr(r);
@expansion{} 32003
  ring s=0,(x,y),dp;
  charstr(s);
@expansion{} 0
  ring ra=(7,a),(x,y),dp;
  minpoly=a^3+a+1;
  charstr(ra);
@expansion{} 7,a
  ring rp=(49,a),(x,y),dp;
  charstr(rp);
@expansion{} 49,a
  ring rr=real,x,dp;
  charstr(rr);
@expansion{} real
@c end example charstr reference.doc:610
@end smallexample
@end table
@c inserted refs from reference.doc:625
@ifinfo
@menu
See
* char::
* ordstr::
* ring::
* varstr::
@end menu
@end ifinfo
@iftex
See
@ref{char};
@ref{ordstr};
@ref{ring};
@ref{varstr}.
@end iftex
@c end inserted refs from reference.doc:625
@c ---------------------------------------
@node cleardenom, close, charstr, 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 reused example cleardenom reference.doc:648
  ring r=0,(x,y,z),dp;
  poly f=(3x+6y)^5;
  f/5;
@expansion{} 243/5x5+486x4y+1944x3y2+3888x2y3+3888xy4+7776/5y5
  cleardenom(f/5);
@expansion{} x5+10x4y+40x3y2+80x2y3+80xy4+32y5
@c end example cleardenom reference.doc:648
@end smallexample
@end table
@c @c ref
@c See @ref{poly}.
@c @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 inserted refs from reference.doc:677
@ifinfo
@menu
See
* link::
* open::
@end menu
@end ifinfo
@iftex
See
@ref{link};
@ref{open}.
@end iftex
@c end inserted refs from reference.doc:677
@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 reused example coef reference.doc:718
  ring r=32003,(x,y,z),dp;
  poly f=x5+5x4y+10x2y3+y5;
  matrix m=coef(f,y);
  print(m);
@expansion{} y5,y3,  y,  1,
@expansion{} 1, 10x2,5x4,x5
  f=x20+xyz+xy+x2y+z3;
  print(coef(f,xy));
@expansion{} x20,x2y,xy, 1,
@expansion{} 1,  1,  z+1,z3
  vector v=[f,zy+77+xy];
  print(v);
@expansion{} [x20+x2y+xyz+z3+xy,xy+yz+77]
  matrix mc; matrix mm;
  coef(v,y,mc,mm);
  print(mc);
@expansion{} x2+xz+x,x20+z3,
@expansion{} x+z,    77
  print(mm);
@expansion{} y,1,
@expansion{} y,1
@c end example coef reference.doc:718
@end smallexample
@end table
@c inserted refs from reference.doc:734
@ifinfo
@menu
See
* coeffs::
@end menu
@end ifinfo
@iftex
See
@ref{coeffs}.
@end iftex
@c end inserted refs from reference.doc:734
@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, say J,
as a univariate polynomial in the given ring_variable,
say z, and returns the coefficients as a k x d
matrix M,
where:
@format
    d-1 = maximum z-degree of all occurring polynomials
      k = 1 if J is a polynomial,
      k = number of generators  if J is an ideal.
@end format
If J is a vector or a module this procedure is repeated for each
component and the resulting matrices are appended.@*
@ifinfo
The third argument is used to return the matrix T of coefficients
such that matrix(J) = T*M.
@end ifinfo
@tex
The third argument is used to return the matrix T of coefficients
such that {\tt matrix}(J) = T*M.
@end tex
@item @strong{Note:}
@code{coeffs} returns the coefficient 0 at the appropriate place if a monomial
is not present, while @code{coef} considers only monomials which really occur
in the given expression. @*
If
@tex
$M=(m_{ij})$
@end tex
@ifinfo
M=(M[i,j])
@end ifinfo
then the j-th generator of an ideal J is equal to
@tex
$$J_j = z^0 \cdot m_{1j} + z^1 \cdot m_{2j} + ... + z^{d-1} \cdot m_{dj},$$
while for a module J the i-th component of the j-th generator is
equal to the entry [i,j] of {\tt matrix}(J), and we get
@end tex
@ifinfo

@*
@format
   J[j] = z^0*M[1,j] + z^1*M[2,j] + ... + z^(d-1)*M[d,j],
@end format
@*while for a module J the i-th component of the j-th generator is
equal to the entry [i,j] of matrix(J), and we get
@end ifinfo
@tex
$$ J_{i,j} = z^0 \cdot m_{(i-1)d+1,j} + z^1 \cdot m_{(i-1)d+2,j} + ... +
z^{d-1} \cdot m_{id,j}.$$
@end tex
@ifinfo

@*
@format
 J[i,j] = z^0*M[(i-1)*d+1,j] + z^1*M[(i-1)*d+2,j] + ...
                             + z^(d-1)*M[i*d,j].
@end format
@end ifinfo

@item @strong{Example:}
@smallexample
@c reused example coeffs reference.doc:817
  ring r;
  poly f=(x+y)^3;
  matrix M=coeffs(f,y);
  print(M);
@expansion{} x3,
@expansion{} 3x2,
@expansion{} 3x,
@expansion{} 1
  ideal i=f,xyz+z10y4;
  print(coeffs(i,y));
@expansion{} x3, 0,
@expansion{} 3x2,xz,
@expansion{} 3x, 0,
@expansion{} 1,  0,
@expansion{} 0,  z10
@c end example coeffs reference.doc:817
@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:}
let the first argument be M,
the second argument  be K (a set of monomials, resp.@: vectors with monomial
entries, in the variables appearing in P),
the third argument be the product P of variables to consider (if this
argument is not given, then the product of all ring variables is taken
as default argument).
@*M is supposed to consist of elements of (resp.@: have entries in)
a finitely generated module
over a ring in the variables not appearing in P. K should contain the
generators of M over this smaller ring.
Then @code{coeffs(M,K,P)} returns a matrix A of coefficients with K*A=M
such that the entries of A do not contain any variable from P.
@*If K does not contain all generators that are necessary to express
M, then K*A=M' where M' is the part of M that can be expressed.

@item @strong{Example:}
@smallexample
@c reused example coeffs_1 reference.doc:851
  ring r=32003,(x,y,z),dp;
  ideal M=x2z+y3,xy;
  print(coeffs(M,ideal(x2,xy,y2),xy));
@expansion{} z,0,
@expansion{} 0,1,
@expansion{} 0,0
  print(coeffs(M,ideal(x2,xy,y2)));
@expansion{} 0,0,
@expansion{} 0,1,
@expansion{} 0,0
@c end example coeffs_1 reference.doc:851
@end smallexample
@end table
@c inserted refs from reference.doc:859
@ifinfo
@menu
See
* coef::
* kbase::
@end menu
@end ifinfo
@iftex
See
@ref{coef};
@ref{kbase}.
@end iftex
@c end inserted refs from reference.doc:859
@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 reused example contract reference.doc:900
  ring r=0,(a,b,c,d),dp;
  ideal I=a2,a2+bc,abc;
  ideal J=a2-bc,abcd;
  print(contract(I,J));
@expansion{} 1,0,
@expansion{} 0,ad,
@expansion{} 0,d
@c end example contract reference.doc:900
@end smallexample
@end table
@c inserted refs from reference.doc:908
@ifinfo
@menu
See
* diff::
@end menu
@end ifinfo
@iftex
See
@ref{diff}.
@end iftex
@c end inserted refs from reference.doc:908
@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 reused example dbprint reference.doc:939
  int debug=0;
  intvec i=1,2,3;
  dbprint(debug,i);
  debug=1;
  dbprint(debug,i);
@expansion{} 1,2,3
  voice;
@expansion{} 1
  printlevel;
@expansion{} 0
  dbprint(i);
@c end example dbprint reference.doc:939
@end smallexample
@end table
@c inserted refs from reference.doc:951
@ifinfo
@menu
See
* Debugging tools::
* print::
* printlevel::
* voice::
@end menu
@end ifinfo
@iftex
See
@ref{Debugging tools};
@ref{print};
@ref{printlevel};
@ref{voice}.
@end iftex
@c end inserted refs from reference.doc:951
@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, -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 reused example defined reference.doc:980
  ring r=(0,t),(x,y),dp;
  matrix m[5][6]=x,y,1,2,0,x+y;
  defined(mm);
@expansion{} 0
  defined(r) and defined(m);
@expansion{} 1
  defined(m)==voice;   // m is defined in the current level
@expansion{} 1
  defined(x);
@expansion{} -1
  defined(z);
@expansion{} 0
  defined(t);
@expansion{} -1
  defined(42);
@expansion{} -1
@c end example defined reference.doc:980
@end smallexample
@end table
@c inserted refs from reference.doc:993
@ifinfo
@menu
See
* rvar::
* voice::
@end menu
@end ifinfo
@iftex
See
@ref{rvar};
@ref{voice}.
@end iftex
@c end inserted refs from reference.doc:993
@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,
the default weights of the base ring will be used otherwise.
@item @strong{Example:}
@smallexample
@c reused example deg reference.doc:1019
  ring r=0,(x,y,z),lp;
  deg(0);
@expansion{} -1
  deg(x3+y4+xyz3);
@expansion{} 5
  ring rr=7,(x,y),wp(2,3);
  poly f=x2+y3;
  deg(f);
@expansion{} 9
  ring R=7,(x,y),ws(2,3);
  poly f=x2+y3;
  deg(f);
@expansion{} 9
  vector v=[x2,y];
  deg(v);
@expansion{} 4
@c end example deg reference.doc:1019
@end smallexample
@end table
@c inserted refs from reference.doc:1034
@ifinfo
@menu
See
* jet::
* ord::
* poly::
* vector::
@end menu
@end ifinfo
@iftex
See
@ref{jet};
@ref{ord};
@ref{poly};
@ref{vector}.
@end iftex
@c end inserted refs from reference.doc:1034
@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:}
int
@item @strong{Purpose:}
computes the (weighted) degree of the projective
variety, respectively sheaf over the projective variety, defined by the ideal,
respectively module, generated by the leading monomials of the input.
This is equal to the
(weighted) degree of the projective variety, respectively
sheaf over the projective variety, defined by the ideal,
respectively module, if the
input is a standard basis with respect to a (weighted) degree ordering.
@item @strong{Example:}
@smallexample
ring r3=32003,(x,y,z,h),dp;
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);
i=homog(i,h);
ideal i0=std(i);
degree(i0);
@expansion{} 720
@end smallexample
@end table
@c inserted refs from reference.doc:1073
@ifinfo
@menu
See
* dim::
* ideal::
* mult::
* std::
* vdim::
@end menu
@end ifinfo
@iftex
See
@ref{dim};
@ref{ideal};
@ref{mult};
@ref{std};
@ref{vdim}.
@end iftex
@c end inserted refs from reference.doc:1073
@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 reused example delete reference.doc:1095
  list l="a","b","c";
  list l1=delete(l,2);l1;
@expansion{} [1]:
@expansion{}    a
@expansion{} [2]:
@expansion{}    c
  l;
@expansion{} [1]:
@expansion{}    a
@expansion{} [2]:
@expansion{}    b
@expansion{} [3]:
@expansion{}    c
@c end example delete reference.doc:1095
@end smallexample
@end table
@c inserted refs from reference.doc:1102
@ifinfo
@menu
See
* insert::
* list::
@end menu
@end ifinfo
@iftex
See
@ref{insert};
@ref{list}.
@end iftex
@c end inserted refs from reference.doc:1102
@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 reused example det reference.doc:1128
  ring r=7,(x,y),wp(2,3);
  matrix m[3][3]=1,2,3,4,5,6,7,8,x;
  det(m);
@expansion{} -3x-1
@c end example det reference.doc:1128
@end smallexample
@end table
@c inserted refs from reference.doc:1135
@ifinfo
@menu
See
* intmat::
* matrix::
* minor::
@end menu
@end ifinfo
@iftex
See
@ref{intmat};
@ref{matrix};
@ref{minor}.
@end iftex
@c end inserted refs from reference.doc:1135
@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 reused example diff reference.doc:1167
  ring r=0,(x,y,z),dp;
  poly f=2x3y+3z5;
  diff(f,x);
@expansion{} 6x2y
  vector v=[f,y2+z];
  diff(v,z);
@expansion{} 15z4*gen(1)+gen(2)
  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));
@expansion{} 2,0,
@expansion{} 1,x,
@expansion{} 0,1
@c end example diff reference.doc:1167
@end smallexample
@end table
@c inserted refs from reference.doc:1181
@ifinfo
@menu
See
* contract::
* ideal::
* jacob::
* matrix::
* module::
* poly::
* var::
* vector::
@end menu
@end ifinfo
@iftex
See
@ref{contract};
@ref{ideal};
@ref{jacob};
@ref{matrix};
@ref{module};
@ref{poly};
@ref{var};
@ref{vector}.
@end iftex
@c end inserted refs from reference.doc:1181
@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 reused example dim reference.doc:1215
  ring r=32003,(x,y,z),dp;
  ideal I=x2-y,x3;
  dim(std(I));
@expansion{} 1
@c end example dim reference.doc:1215
@end smallexample
@end table
@c inserted refs from reference.doc:1222
@ifinfo
@menu
See
* degree::
* ideal::
* mult::
* std::
* vdim::
@end menu
@end ifinfo
@iftex
See
@ref{degree};
@ref{ideal};
@ref{mult};
@ref{std};
@ref{vdim}.
@end iftex
@c end inserted refs from reference.doc:1222
@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 reused example division reference.doc:1255
ring R=0,(x,y),ds;
poly f=x5+x2y2+y5;
division(f,jacob(f));
@expansion{} [1]:
@expansion{}    _[1,1]=1/5x
@expansion{}    _[2,1]=3/10y
@expansion{} [2]:
@expansion{}    _[1]=-1/2y5
@expansion{} [3]:
@expansion{}    _[1,1]=1
division(f^2,jacob(f));
@expansion{} [1]:
@expansion{}    _[1,1]=1/20x6-9/80xy5-5/16x7y+5/8x2y6
@expansion{}    _[2,1]=1/8x2y3+1/5x5y+1/20y6-3/4x3y4-5/4x6y2-5/16xy7
@expansion{} [2]:
@expansion{}    _[1]=0
@expansion{} [3]:
@expansion{}    _[1,1]=1/4-25/16xy
division(ideal(f^2),jacob(f),10);
@expansion{} // ** _ is no standardbasis
@expansion{} [1]:
@expansion{}    _[1,1]=-75/8y9
@expansion{}    _[2,1]=1/2x2y3+x5y-1/4y6-3/2x3y4+15/4xy7+375/16x2y8
@expansion{} [2]:
@expansion{}    _[1]=x10+9/4y10
@c end example division reference.doc:1255
@end smallexample
@end table
@c inserted refs from reference.doc:1264
@ifinfo
@menu
See
* ideal::
* lift::
* module::
@end menu
@end ifinfo
@iftex
See
@ref{ideal};
@ref{lift};
@ref{module}.
@end iftex
@c end inserted refs from reference.doc:1264
@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 reused example dump reference.doc:1286
  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");
@expansion{} // ** redefining stdfglm **
@expansion{} // ** redefining stdhilb **
@expansion{} // ** redefining groebner **
@expansion{} // ** redefining res **
@expansion{} // ** redefining quot **
@expansion{} // ** redefining quot1 **
@expansion{} // ** redefining quotient0 **
@expansion{} // ** redefining quotient1 **
@expansion{} // ** redefining quotient2 **
@expansion{} // ** redefining quotient3 **
@expansion{} // ** redefining quotient5 **
@expansion{} // ** redefining quotient4 **
@expansion{} // ** redefining intersect1 **
@expansion{} // ** redefining sprintf **
@expansion{} // ** redefining printf **
@expansion{} // ** redefining fprintf **
  r;
@expansion{} //   characteristic : 32003
@expansion{} //   number of vars : 3
@expansion{} //        block   1 : ordering dp
@expansion{} //                  : names    x y z
@expansion{} //        block   2 : ordering C
@c end example dump reference.doc:1286
@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 inserted refs from reference.doc:1304
@ifinfo
@menu
See
* getdump::
* link::
* write::
@end menu
@end ifinfo
@iftex
See
@ref{getdump};
@ref{link};
@ref{write}.
@end iftex
@c end inserted refs from reference.doc:1304
@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{,} 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 of the second argument from an
ideal, resp.@: module, by intersecting it with the subring not containing
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.
@item @strong{Example:}
@smallexample
@c reused example eliminate reference.doc:1336
  ring r=32003,(x,y,z),dp;
  ideal i=x2,xy,y5;
  eliminate(i,x);
@expansion{} _[1]=y5
  ring R=0,(x,y,t,s,z),dp;
  ideal i=x-t,y-t2,z-t3,s-x+y3;
  eliminate(i,ts);
@expansion{} _[1]=y2-xz
@expansion{} _[2]=xy-z
@expansion{} _[3]=x2-y
  intvec v=hilb(std(i),1);
  eliminate(i,ts,v);
@expansion{} _[1]=y2-xz
@expansion{} _[2]=xy-z
@expansion{} _[3]=x2-y
@c end example eliminate reference.doc:1336
@end smallexample
@end table
@c inserted refs from reference.doc:1348
@ifinfo
@menu
See
* hilb::
* ideal::
* module::
* std::
@end menu
@end ifinfo
@iftex
See
@ref{hilb};
@ref{ideal};
@ref{module};
@ref{std}.
@end iftex
@c end inserted refs from reference.doc:1348
@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 @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 @c example
@end smallexample
@end table
@c inserted refs from reference.doc:1390
@ifinfo
@menu
See
* MPfile links::
* quote::
* write::
@end menu
@end ifinfo
@iftex
See
@ref{MPfile links};
@ref{quote};
@ref{write}.
@end iftex
@c end inserted refs from reference.doc:1390
@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 reused example ERROR reference.doc:1415
int i=1;
proc myError() @{ERROR("Need to leave now");i=2;@}
myError();
@expansion{}    ? Need to leave now
@expansion{}    ? error occurred in line 2: `ERROR("Need to leave now");i=2;`
@expansion{}    ? leaving ::myError
@expansion{}    skipping text from `;` error at token `)`
i;
@expansion{} 1
@c end example ERROR reference.doc:1415
@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 inserted refs from reference.doc:1441
@ifinfo
@menu
See also:
* help::
@end menu
@end ifinfo
@iftex
@strong{See also:}
@ref{help}.
@end iftex
@c end inserted refs from reference.doc:1441
@c ---------------------------------------
@node execute, exit, 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 reused example execute reference.doc:1463
  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;
@expansion{} ideal k=x+y,z3+22y
@expansion{} ;
  execute(s); // define the ideal k
  k;
@expansion{} k[1]=x+y
@expansion{} k[2]=z3+22y
@c end example execute reference.doc:1463
@end smallexample
@end table
@c ---------------------------------------
@node exit, extgcd, execute, Functions
@subsection exit
@cindex exit
@table @code
@item @strong{Syntax:}
@code{exit;}
@item @strong{Purpose:}
exits (quits) @sc{Singular},
works also from inside a procedure or from an interrupt.
@end table
@c ---------------------------------------
@node extgcd, facstd, exit, 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 to apply @code{extgcd}.
@item @strong{Example:}
@smallexample
@c reused example extgcd reference.doc:1506
  extgcd(24,10);
@expansion{} [1]:
@expansion{}    2
@expansion{} [2]:
@expansion{}    -2
@expansion{} [3]:
@expansion{}    5
  ring r=0,(x,y),lp;
  extgcd(x4-x6,(x2+x5)*(x2+x3));
@expansion{} [1]:
@expansion{}    2x5+2x4
@expansion{} [2]:
@expansion{}    x2+x+1
@expansion{} [3]:
@expansion{}    1
@c end example extgcd reference.doc:1506
@end smallexample
@end table
@c inserted refs from reference.doc:1513
@ifinfo
@menu
See
* gcd::
* int::
* poly::
@end menu
@end ifinfo
@iftex
See
@ref{gcd};
@ref{int};
@ref{poly}.
@end iftex
@c end inserted refs from reference.doc:1513
@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. Hence, the intersection of the output ideals
has a zero-set which is the (closure of the) complement of the zero-set
of the second argument in the zero-set of the first argument.
@item @strong{Note:}
Not implemented for baserings over real ground fields, galois fields and
over algebraic extensions over the rational numbers (that is, only
implemented for ground fields for which @ref{factorize} is implemented).
@item @strong{Example:}
@smallexample
@c reused example facstd reference.doc:1548
  ring r=32003,(x,y,z),(c,dp);
  ideal I=xyz,x2z;
  facstd(I);
@expansion{} [1]:
@expansion{}    _[1]=z
@expansion{} [2]:
@expansion{}    _[1]=x
  facstd(I,x);
@expansion{} [1]:
@expansion{}    _[1]=z
@c end example facstd reference.doc:1548
@end smallexample
@end table
@c inserted refs from reference.doc:1556
@ifinfo
@menu
See
* ideal::
* ring::
* std::
@end menu
@end ifinfo
@iftex
See
@ref{ideal};
@ref{ring};
@ref{std}.
@end iftex
@c end inserted refs from reference.doc:1556
@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 reused example factorize reference.doc:1594
  ring r=32003,(x,y,z),dp;
  factorize(9*(x-1)^2*(y+z));
@expansion{} [1]:
@expansion{}    _[1]=9
@expansion{}    _[2]=y+z
@expansion{}    _[3]=x-1
@expansion{} [2]:
@expansion{}    1,1,2
  factorize(9*(x-1)^2*(y+z),1);
@expansion{} _[1]=y+z
@expansion{} _[2]=x-1
  factorize(9*(x-1)^2*(y+z),2);
@expansion{} [1]:
@expansion{}    _[1]=y+z
@expansion{}    _[2]=x-1
@expansion{} [2]:
@expansion{}    1,2
@c end example factorize reference.doc:1594
@end smallexample
@end table
@c inserted refs from reference.doc:1602
@ifinfo
@menu
See
* poly::
@end menu
@end ifinfo
@iftex
See
@ref{poly}.
@end iftex
@c end inserted refs from reference.doc:1602
@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 mapping 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 reused example fetch reference.doc:1632
  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;
@expansion{} z3+y2+x
  vector v=fetch(r,v);
  v;
@expansion{} z3*gen(1)+y2*gen(1)+x*gen(1)+gen(2)
  ideal i=fetch(r,i);
  i;
@expansion{} i[1]=z2
@expansion{} i[2]=yz
@expansion{} i[3]=y2
@expansion{} i[4]=xz
@expansion{} i[5]=xy
@expansion{} i[6]=x2
  ring rr=0,(a,b,c),lp;
  poly f=fetch(q,f);
  f;
@expansion{} a+b2+c3
  vector v=fetch(r,v);
  v;
@expansion{} a*gen(1)+b2*gen(1)+c3*gen(1)+gen(2)
  ideal k=fetch(q,i);
  k;
@expansion{} k[1]=c2
@expansion{} k[2]=bc
@expansion{} k[3]=b2
@expansion{} k[4]=ac
@expansion{} k[5]=ab
@expansion{} k[6]=a2
@c end example fetch reference.doc:1632
@end smallexample
@end table
@c inserted refs from reference.doc:1655
@ifinfo
@menu
See
* imap::
* map::
* qring::
* ring::
@end menu
@end ifinfo
@iftex
See
@ref{imap};
@ref{map};
@ref{qring};
@ref{ring}.
@end iftex
@c end inserted refs from reference.doc:1655
@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{Note:}
The ideal must be zero-dimensional and given as a reduced Groebner
basis in the given ring.
@*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 reused example fglm reference.doc:1688
  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);
@expansion{} 28
  ring s=0,(z,x,y),lp;
  ideal j=fglm(r,i);
  j;
@expansion{} j[1]=y4+y3
@expansion{} j[2]=xy3-y3
@expansion{} j[3]=x2+y3
@expansion{} j[4]=z4+y3-y
@c end example fglm reference.doc:1688
@end smallexample
@end table
@c inserted refs from reference.doc:1700
@ifinfo
@menu
See
* fglmquot::
* option::
* qring::
* ring::
* std::
* stdfglm::
* vdim::
@end menu
@end ifinfo
@iftex
See
@ref{fglmquot};
@ref{option};
@ref{qring};
@ref{ring};
@ref{std};
@ref{stdfglm};
@ref{vdim}.
@end iftex
@c end inserted refs from reference.doc:1700
@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{Note:}
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 reused example fglmquot reference.doc:1730
  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;
@expansion{} j[1]=z12
@expansion{} j[2]=yz4-z8
@expansion{} j[3]=y2+y-z8-z4
@expansion{} j[4]=x+y-z10-z6-z4
@c end example fglmquot reference.doc:1730
@end smallexample
@end table
@c inserted refs from reference.doc:1741
@ifinfo
@menu
See
* fglm::
* option::
* quotient::
* ring::
* std::
* vdim::
@end menu
@end ifinfo
@iftex
See
@ref{fglm};
@ref{option};
@ref{quotient};
@ref{ring};
@ref{std};
@ref{vdim}.
@end iftex
@c end inserted refs from reference.doc:1741
@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 inserted refs from reference.doc:1768
@ifinfo
@menu
See
* execute::
* read::
@end menu
@end ifinfo
@iftex
See
@ref{execute};
@ref{read}.
@end iftex
@c end inserted refs from reference.doc:1768
@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 reused example find reference.doc:1789
  find("Aac","a");
@expansion{} 2
  find("abab","a"+"b");
@expansion{} 1
  find("abab","a"+"b",2);
@expansion{} 3
  find("abab","ab",3);
@expansion{} 3
  find("0123","abcd");
@expansion{} 0
@c end example find reference.doc:1789
@end smallexample
@end table
@c inserted refs from reference.doc:1798
@ifinfo
@menu
See
* string::
@end menu
@end ifinfo
@iftex
See
@ref{string}.
@end iftex
@c end inserted refs from reference.doc:1798
@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{Note:}
The ideal must be zero-dimensional and given as a reduced Groebner basis in
the current ring.
@item @strong{Example:}
@smallexample
@c reused example finduni reference.doc:1820
  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);
@expansion{} x4-x2,
@expansion{} y4+y3,
@expansion{} z12
@c end example finduni reference.doc:1820
@end smallexample
@end table
@c inserted refs from reference.doc:1830
@ifinfo
@menu
See
* option::
* ring::
* std::
* vdim::
@end menu
@end ifinfo
@iftex
See
@ref{option};
@ref{ring};
@ref{std};
@ref{vdim}.
@end iftex
@c end inserted refs from reference.doc:1830

@c ---------------------------------------
@node fprintf, freemodule, finduni, Functions
@subsection fprintf
@cindex fprintf
@c start include of docu for standard.lib:fprintf
@c replaced @subsubsection by @sub
@c ---content fprintf---
Procedure from library @code{standard.lib} (@pxref{standard_lib}).

@table @asis
@item @strong{Syntax:}
@code{fprintf (} link_expression@code{,} string_expression @code{[,}
any_expressions@code{] )}

@item @strong{Return:}
none

@item @strong{Purpose:}
@code{fprintf(l,fmt,...);} performs output formatting.
The second argument is a format control string. Additional
arguments may be required, depending on the content of the
control string. A series of output characters is generated as
directed by the control string; these characters are
written to the link l.
The control string @code{fmt} is simply text to be copied, except
that the string may contain conversion specifications.@*
Do @code{help print;} for a listing of valid conversion
specifications. As an addition to the conversions of @code{print},
the @code{%n} and @code{%2} conversion specification does not
consume an additional argument, but simply generates a newline
character.

@item @strong{Note:}
If one of the additional arguments is a list, then it should be
enclosed once more into a @code{list()} command, since passing
a list as an argument flattens the list by one level.

@end table
@strong{Example:}
@smallexample
@c reused example fprintf d2t_singular/standard_lib.doc:393
  ring r=0,(x,y,z),dp;
module m=[1,y],[0,x+z];
intmat M=betti(mres(m,0));
list l=r,m,M;
link li="";   // link to stdout
fprintf(li,"s:%s,l:%l",1,2);
@expansion{} s:1,l:int(2)
fprintf(li,"s:%s",l);
@expansion{} s:(0),(x,y,z),(dp(3),C)
fprintf(li,"s:%s",list(l));
@expansion{} s:(0),(x,y,z),(dp(3),C),y*gen(2)+gen(1),x*gen(2)+z*gen(2),1,1
fprintf(li,"2l:%2l",list(l));
@expansion{} 2l:list("(0),(x,y,z),(dp(3),C)",
@expansion{} module(y*gen(2)+gen(1),
@expansion{} x*gen(2)+z*gen(2)),
@expansion{} intmat(intvec(1,1 ),1,2))
@expansion{}
fprintf(li,"%p",list(l));
@expansion{} [1]:
@expansion{}    //   characteristic : 0
@expansion{} //   number of vars : 3
@expansion{} //        block   1 : ordering dp
@expansion{} //                  : names    x y z
@expansion{} //        block   2 : ordering C
@expansion{} [2]:
@expansion{}    _[1]=y*gen(2)+gen(1)
@expansion{}    _[2]=x*gen(2)+z*gen(2)
@expansion{} [3]:
@expansion{}    1,1
@expansion{}
fprintf(li,"%;",list(l));
@expansion{} [1]:
@expansion{}    //   characteristic : 0
@expansion{} //   number of vars : 3
@expansion{} //        block   1 : ordering dp
@expansion{} //                  : names    x y z
@expansion{} //        block   2 : ordering C
@expansion{} [2]:
@expansion{}    _[1]=y*gen(2)+gen(1)
@expansion{}    _[2]=x*gen(2)+z*gen(2)
@expansion{} [3]:
@expansion{}    1,1
@expansion{}
fprintf(li,"%b",M);
@expansion{}            0     1
@expansion{} ------------------
@expansion{}     0:     1     1
@expansion{} ------------------
@expansion{} total:     1     1
@expansion{}
@c end example fprintf d2t_singular/standard_lib.doc:393
@end smallexample
@c inserted refs from d2t_singular/standard_lib.doc:408
@ifinfo
@menu
See also:
* print::
* printf::
* sprintf::
* string::
@end menu
@end ifinfo
@iftex
@strong{See also:}
@ref{print};
@ref{printf};
@ref{sprintf};
@ref{string}.
@end iftex
@c end inserted refs from d2t_singular/standard_lib.doc:408

@c ---end content fprintf---
@c generated lib proc docu for standard.lib:fprintf reference.doc:1842
@c end include of docu for standard.lib:fprintf

@c ---------------------------------------
@node freemodule, gcd, 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 reused example freemodule reference.doc:1859
  ring r=32003,(x,y),(c,dp);
  freemodule(3);
@expansion{} _[1]=[1]
@expansion{} _[2]=[0,1]
@expansion{} _[3]=[0,0,1]
  matrix m=freemodule(3); // generates the 3x3 unit matrix
  print(m);
@expansion{} 1,0,0,
@expansion{} 0,1,0,
@expansion{} 0,0,1
@c end example freemodule reference.doc:1859
@end smallexample
@end table
@c inserted refs from reference.doc:1867
@ifinfo
@menu
See
* gen::
* module::
@end menu
@end ifinfo
@iftex
See
@ref{gen};
@ref{module}.
@end iftex
@c end inserted refs from reference.doc:1867
@c ---------------------------------------
@node gcd, gen, freemodule, Functions
@subsection gcd
@cindex gcd

@table @code
@item @strong{Syntax:}
@code{gcd (} int_expression@code{,} int_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 reused example gcd reference.doc:1893
  gcd(2,3);
@expansion{} 1
  ring r=0,(x,y,z),lp;
  gcd(3x2*(x+y),9x*(y2-x2));
@expansion{} x2+xy
  gcd(number(6472674604870),number(878646537247372));
@expansion{} 2
@c end example gcd reference.doc:1893
@end smallexample
@end table
@c inserted refs from reference.doc:1901
@ifinfo
@menu
See
* extgcd::
* int::
* number::
* poly::
@end menu
@end ifinfo
@iftex
See
@ref{extgcd};
@ref{int};
@ref{number};
@ref{poly}.
@end iftex
@c end inserted refs from reference.doc:1901
@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 reused example gen reference.doc:1922
  ring r=32003,(x,y,z),(c,dp);
  gen(3);
@expansion{} [0,0,1]
  vector v=gen(5);
  poly f=xyz;
  v=v+f*gen(4); v;
@expansion{} [0,0,0,xyz,1]
  ring rr=32003,(x,y,z),dp;
  fetch(r,v);
@expansion{} xyz*gen(4)+gen(5)
@c end example gen reference.doc:1922
@end smallexample
@end table
@c inserted refs from reference.doc:1933
@ifinfo
@menu
See
* freemodule::
* int::
* vector::
@end menu
@end ifinfo
@iftex
See
@ref{freemodule};
@ref{int};
@ref{vector}.
@end iftex
@c end inserted refs from reference.doc:1933
@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 reused example getdump reference.doc:1956
  int i=3;
  dump(":w example.txt");
  kill i;
  option(noredefine);
  getdump("example.txt");
  i;
@expansion{} 3
@c end example getdump reference.doc:1956
@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 inserted refs from reference.doc:1969
@ifinfo
@menu
See
* dump::
* link::
* read::
@end menu
@end ifinfo
@iftex
See
@ref{dump};
@ref{link};
@ref{read}.
@end iftex
@c end inserted refs from reference.doc:1969
@c ---------------------------------------
@node groebner, help, getdump, Functions
@subsection groebner
@cindex groebner
@c start include of docu for standard.lib:groebner
@c replaced @subsubsection by @sub
@c ---content groebner---
Procedure from library @code{standard.lib} (@pxref{standard_lib}).

@table @asis
@item @strong{Syntax:}
@code{groebner (} ideal_expression @code{)} @*
@code{groebner (} module_expression @code{)} @*
@code{groebner (} ideal_expression@code{,} int_expression @code{)} @*
@code{groebner (} module_expression@code{,} int_expression @code{)}

@item @strong{Type:}
type of the first argument

@item @strong{Purpose:}
computes the standard basis of the first argument @code{I}
(ideal or module), by a heuristically chosen method: if the
ordering of the current ring is a local ordering, or if it is a
non-block ordering and the current ring has no parameters, then
@code{std(I)} is returned. Otherwise, @code{I} is mapped into a
ring with no parameters and ordering dp, where its Hilbert series
is computed. This is followed by a Hilbert-series based std
computation in the original ring.

@item @strong{Note:}
If a 2nd argument @code{wait} is given, then the computation proceeds
at most @code{wait} seconds. That is, if no result could be computed in
@code{wait} seconds, then the computation is interrupted, 0 is returned,
a warning message is displayed, and the global variable
@code{groebner_error} is defined.

@cindex time limit on computations
@cindex MP, groebner basis computations
@end table
@strong{Example:}
@smallexample
@c reused example groebner d2t_singular/standard_lib.doc:149
  ring r=0,(a,b,c,d),lp;
option(prot);
ideal i=a+b+c+d,ab+ad+bc+cd,abc+abd+acd+bcd,abcd-1; // cyclic 4
groebner(i);
@expansion{} std in (0),(a,b,c,d,@@t),(dp,C)
@expansion{} [63:1]1(3)s2(2)s3s4-s5ss6-s7--
@expansion{} product criterion:8 chain criterion:5
@expansion{} std with hilb in  (0),(a,b,c,d,@@t),(lp(4),C)
@expansion{} [63:1]1(3)s2(2)s3s4-s5ss6shhhh8shh
@expansion{} product criterion:9 chain criterion:8
@expansion{} hilbert series criterion:6
@expansion{} dehomogenization
@expansion{} imap to original ring
@expansion{} simplification
@expansion{} _[1]=c2d6-c2d2-d4+1
@expansion{} _[2]=c3d2+c2d3-c-d
@expansion{} _[3]=bd4-b+d5-d
@expansion{} _[4]=bc-bd5+c2d4+cd-d6-d2
@expansion{} _[5]=b2+2bd+d2
@expansion{} _[6]=a+b+c+d
ring rp=(0,a,b),(c,d), lp;
ideal i=imap(r,i);
ideal j=groebner(i);
@expansion{} std in 0,(c,d,a,b,@@t),(dp,C)
@expansion{} [63:1]1(3)s2(2)s3s4-s5ss6-s7--
@expansion{} product criterion:8 chain criterion:5
@expansion{} std with hilb in  (0),(c,d,a,b,@@t),(lp(2),C, dp(3))
@expansion{} [63:3]1(3)s2(2)s3s4-s5ss6shhhh8shh
@expansion{} product criterion:9 chain criterion:8
@expansion{} hilbert series criterion:6
@expansion{} dehomogenization
@expansion{} imap to original ring
@expansion{} simplification
option(noprot);
j; simplify(j,1); std(i);
@expansion{} j[1]=(a3b2+a2b3-a-b)
@expansion{} _[1]=1
@expansion{} _[1]=1
if (system("with","MP")) @{groebner(i,0);@}
@expansion{} // ** groebner did not finish
@expansion{} _[1]=0
defined(groebner_error);
@expansion{} 1
@c end example groebner d2t_singular/standard_lib.doc:149
@end smallexample
@c inserted refs from d2t_singular/standard_lib.doc:163
@ifinfo
@menu
See also:
* std::
* stdfglm::
* stdhilb::
@end menu
@end ifinfo
@iftex
@strong{See also:}
@ref{std};
@ref{stdfglm};
@ref{stdhilb}.
@end iftex
@c end inserted refs from d2t_singular/standard_lib.doc:163

@c ---end content groebner---
@c generated lib proc docu for standard.lib:groebner reference.doc:1979
@c end include of docu for standard.lib:groebner

@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 inserted refs from reference.doc:2072
@ifinfo
@menu
See
* Command line options::
* Format of a library::
* Procedure definition::
* The online help system::
* system::
@end menu
@end ifinfo
@iftex
See
@ref{Command line options};
@ref{Format of a library};
@ref{Procedure definition};
@ref{The online help system};
@ref{system}.
@end iftex
@c end inserted refs from reference.doc:2072
@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.
@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 (e.g., 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 reused example highcorner reference.doc:2133
ring r=0,(x,y),ds;
ideal i=x3,x2y,y3;
highcorner(std(i));
@expansion{} xy2
highcorner(std(ideal(1)));
@expansion{} 0
@c end example highcorner reference.doc:2133
@end smallexample
@end table
@c inserted refs from reference.doc:2141
@ifinfo
@menu
See
* dim::
* std::
* vdim::
@end menu
@end ifinfo
@iftex
See
@ref{dim};
@ref{std};
@ref{vdim}.
@end iftex
@c end inserted refs from reference.doc:2141
@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 reused example hilb reference.doc:2179
  ring R=32003,(x,y,z),dp;
  ideal i=x2,y2,z2;
  ideal s=std(i);
  hilb(s);
@expansion{} //         1 t^0
@expansion{} //        -3 t^2
@expansion{} //         3 t^4
@expansion{} //        -1 t^6
@expansion{}
@expansion{} //         1 t^0
@expansion{} //         3 t^1
@expansion{} //         3 t^2
@expansion{} //         1 t^3
@expansion{} // dimension (affine)  = 0
@expansion{} // degree      = 8
  hilb(s,1);
@expansion{} 1,0,-3,0,3,0,-1,0
  hilb(s,2);
@expansion{} 1,3,3,1,0
  intvec w=2,2,2;
  hilb(s,1,w);
@expansion{} 1,0,0,0,-3,0,0,0,3,0,0,0,-1,0
@c end example hilb reference.doc:2179
@end smallexample
@end table
@c inserted refs from reference.doc:2191
@ifinfo
@menu
See
* Hilbert function::
* ideal::
* intvec::
* module::
* std::
* stdhilb::
@end menu
@end ifinfo
@iftex
See
@ref{Hilbert function};
@ref{ideal};
@ref{intvec};
@ref{module};
@ref{std};
@ref{stdhilb}.
@end iftex
@c end inserted refs from reference.doc:2191
@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{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 (which must have
weight 1).
@item @strong{Example:}
@smallexample
@c reused example homog reference.doc:2226
  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);
@expansion{} x2y2z4+3z8
  homog(i,z);
@expansion{} _[1]=3y9+x5yz3+x3y2z4
@expansion{} _[2]=x2y2z4+3z8
@expansion{} _[3]=11x10+y7z3+5x4y2z4+4xy5z4+2x2y2z6
  homog(i);
@expansion{} 0
  homog(homog(i,z));
@expansion{} 1
@c end example homog reference.doc:2226
@end smallexample
@end table
@c inserted refs from reference.doc:2239
@ifinfo
@menu
See
* ideal::
* module::
* poly::
* vector::
@end menu
@end ifinfo
@iftex
See
@ref{ideal};
@ref{module};
@ref{poly};
@ref{vector}.
@end iftex
@c end inserted refs from reference.doc:2239
@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 reused example hres reference.doc:2297
  ring r=0,(x,y,z),dp;
  ideal I=xz,yz,x3-y3;
  def L=hres(I,0);
  print(betti(L),"betti");
@expansion{}            0     1     2
@expansion{} ------------------------
@expansion{}     0:     1     -     -
@expansion{}     1:     -     2     1
@expansion{}     2:     -     1     1
@expansion{} ------------------------
@expansion{} total:     1     3     2
  L[2];     // the first syzygy module of r/I
@expansion{} _[1]=-x*gen(1)+y*gen(2)
@expansion{} _[2]=-x2*gen(2)+y2*gen(1)+z*gen(3)
@c end example hres reference.doc:2297
@end smallexample
@end table
@c inserted refs from reference.doc:2306
@ifinfo
@menu
See
* betti::
* ideal::
* int::
* lres::
* minres::
* module::
* mres::
* res::
* sres::
@end menu
@end ifinfo
@iftex
See
@ref{betti};
@ref{ideal};
@ref{int};
@ref{lres};
@ref{minres};
@ref{module};
@ref{mres};
@ref{res};
@ref{sres}.
@end iftex
@c end inserted refs from reference.doc:2306
@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 mapping 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 reused example imap reference.doc:2341
  ring r=0,(x,y,z,a,b,c),dp;
  ideal i=xy2z3a4b5+1,homog(xy2z3a4b5+1,c); i;
@expansion{} i[1]=xy2z3a4b5+1
@expansion{} i[2]=xy2z3a4b5+c15
  ring r1=0,(a,b,x,y,z),lp;
  ideal j=imap(r,i); j;
@expansion{} j[1]=a4b5xy2z3+1
@expansion{} j[2]=a4b5xy2z3
  ring r2=(0,a,b),(x,y,z),ls;
  ideal j=imap(r,i); j;
@expansion{} j[1]=1+(a4b5)*xy2z3
@expansion{} j[2]=(a4b5)*xy2z3
@c end example imap reference.doc:2341
@end smallexample
@end table
@c inserted refs from reference.doc:2351
@ifinfo
@menu
See
* fetch::
* homog::
* map::
* qring::
* ring::
@end menu
@end ifinfo
@iftex
See
@ref{fetch};
@ref{homog};
@ref{map};
@ref{qring};
@ref{ring}.
@end iftex
@c end inserted refs from reference.doc:2351
@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 reused example impart reference.doc:2374
  ring r=(complex,i),x,dp;
  impart(1+2*i);
@expansion{} 2
@c end example impart reference.doc:2374
@end smallexample
@end table
@c inserted refs from reference.doc:2380
@ifinfo
@menu
See
* repart::
@end menu
@end ifinfo
@iftex
See
@ref{repart}.
@end iftex
@c end inserted refs from reference.doc:2380
@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 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 reused example indepSet reference.doc:2425
  ring r=32003,(x,y,u,v,w),dp;
  ideal I=xyw,yvw,uyw,xv;
  attrib(I,"isSB",1);
  indepSet(I);
@expansion{} 1,1,1,0,0
  eliminate(I,vw);
@expansion{} _[1]=0
  indepSet(I,0);
@expansion{} [1]:
@expansion{}    1,1,1,0,0
@expansion{} [2]:
@expansion{}    0,1,1,1,0
@expansion{} [3]:
@expansion{}    1,0,1,0,1
@expansion{} [4]:
@expansion{}    0,0,1,1,1
  indepSet(I,1);
@expansion{} [1]:
@expansion{}    1,1,1,0,0
@expansion{} [2]:
@expansion{}    0,1,1,1,0
@expansion{} [3]:
@expansion{}    1,0,1,0,1
@expansion{} [4]:
@expansion{}    0,0,1,1,1
@expansion{} [5]:
@expansion{}    0,1,0,0,1
  eliminate(I,xuv);
@expansion{} _[1]=0
@c end example indepSet reference.doc:2425
@end smallexample
@end table
@c inserted refs from reference.doc:2437
@ifinfo
@menu
See
* ideal::
* std::
@end menu
@end ifinfo
@iftex
See
@ref{ideal};
@ref{std}.
@end iftex
@c end inserted refs from reference.doc:2437
@c ---------------------------------------
@node insert, interred, 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 reused example insert reference.doc:2458
  list L=1,2;
  insert(L,4,2);
@expansion{} [1]:
@expansion{}    1
@expansion{} [2]:
@expansion{}    2
@expansion{} [3]:
@expansion{}    4
  insert(L,4);
@expansion{} [1]:
@expansion{}    4
@expansion{} [2]:
@expansion{}    1
@expansion{} [3]:
@expansion{}    2
@c end example insert reference.doc:2458
@end smallexample
@end table
@c inserted refs from reference.doc:2465
@ifinfo
@menu
See
* delete::
* list::
@end menu
@end ifinfo
@iftex
See
@ref{delete};
@ref{list}.
@end iftex
@c end inserted refs from reference.doc:2465
@c ---------------------------------------
@node interred, intersect, insert, 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):
@*
@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):
@* 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 reused example interred reference.doc:2557
  ring r=0,(x,y,z),dp;
  ideal i=x2+z,z,2z;
  interred(i);
@expansion{} _[1]=z
@expansion{} _[2]=x2
  ring R=0,(x,y,z),ds;
  ideal i=zx+y3,z+y3,z+xy;
  interred(i);
@expansion{} _[1]=z+xy
@expansion{} _[2]=xy-y3
@expansion{} _[3]=x2y-y3
@c end example interred reference.doc:2557
@end smallexample
@end table
@c inserted refs from reference.doc:2567
@ifinfo
@menu
See
* ideal::
* module::
* std::
@end menu
@end ifinfo
@iftex
See
@ref{ideal};
@ref{module};
@ref{std}.
@end iftex
@c end inserted refs from reference.doc:2567
@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 reused example intersect reference.doc:2589
  ring R=0,(x,y),dp;
  ideal i=x;
  ideal j=y;
  intersect(i,j);
@expansion{} _[1]=xy
  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;
@expansion{} id3[1]=yz3+xy6z
@expansion{} id3[2]=yz4-y2z
@expansion{} id3[3]=y2z3-y3
@expansion{} id3[4]=xz3+x2y5z
@expansion{} id3[5]=xyz2+x2z
@expansion{} id3[6]=xyz3-xy2
@expansion{} id3[7]=xy2z+x2y
@expansion{} id3[8]=x2yz+x3
@c end example intersect reference.doc:2589
@end smallexample
@end table
@c inserted refs from reference.doc:2602
@ifinfo
@menu
See
* ideal::
* module::
* option::
@end menu
@end ifinfo
@iftex
See
@ref{ideal};
@ref{module};
@ref{option}.
@end iftex
@c end inserted refs from reference.doc:2602
@c ---------------------------------------
@node jacob, jet, intersect, Functions
@subsection jacob
@cindex jacob
@table @code
@item @strong{Syntax:}
@code{jacob (} poly_expression @code{)}
@*@code{jacob (} ideal_expression @code{)}
@item @strong{Type:}
ideal, if the input is a polynomial
@* matrix, if the input is an ideal
@item @strong{Purpose:}
computes the Jacobi ideal, resp.@: Jacobi matrix, generated by all
partial derivatives of the input.
@item @strong{Example:}
@smallexample
@c reused example jacob reference.doc:2624
  ring R;
  poly f=x2+y3+z5;
  jacob(f);
@expansion{} _[1]=2x
@expansion{} _[2]=3y2
@expansion{} _[3]=5z4
  ideal i=jacob(f);
  print(jacob(i));
@expansion{} 2,0, 0,
@expansion{} 0,6y,0,
@expansion{} 0,0, 20z3
@c end example jacob reference.doc:2624
@end smallexample
@end table
@c inserted refs from reference.doc:2633
@ifinfo
@menu
See
* diff::
* ideal::
* module::
* nvars::
@end menu
@end ifinfo
@iftex
See
@ref{diff};
@ref{ideal};
@ref{module};
@ref{nvars}.
@end iftex
@c end inserted refs from reference.doc:2633
@c ---------------------------------------
@node jet, kbase, jacob, 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{,} int_expression@code{,} poly_expression @code{)}
@*@code{jet (} vector_expression@code{,} int_expression@code{,} poly_expression @code{)}
@*@code{jet (} ideal_expression@code{,} int_expression@code{,} matrix_expression @code{)}
@*@code{jet (} module_expression@code{,} int_expression@code{,} matrix_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 third 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 reused example jet reference.doc:2666
  ring r=32003,(x,y,z),(c,dp);
  jet(1+x+x2+x3+x4,3);
@expansion{} x3+x2+x+1
  poly f=1+x+x2+xz+y2+x3+y3+x2y2+z4;
  jet(f,3);
@expansion{} x3+y3+x2+y2+xz+x+1
  intvec iv=2,1,1;
  jet(f,3,iv);
@expansion{} y3+y2+xz+x+1
  // the part of f with (total) degree >3:
  f-jet(f,3);
@expansion{} x2y2+z4
  // the homogeneous part of f of degree 2:
  jet(f,2)-jet(f,1);
@expansion{} x2+y2+xz
  // the part of maximal degree:
  jet(f,deg(f))-jet(f,deg(f)-1);
@expansion{} x2y2+z4
  // the absolute term of f:
  jet(f,0);
@expansion{} 1
  // now for other types:
  ideal i=f,x,f*f;
  jet(i,2);
@expansion{} _[1]=x2+y2+xz+x+1
@expansion{} _[2]=x
@expansion{} _[3]=3x2+2y2+2xz+2x+1
  vector v=[f,1,x];
  jet(v,1);
@expansion{} [x+1,1,x]
  jet(v,0);
@expansion{} [1,1]
  v=[f,1,0];
  module m=v,v,[1,x2,z3,0,1];
  jet(m,2);
@expansion{} _[1]=[x2+y2+xz+x+1,1]
@expansion{} _[2]=[x2+y2+xz+x+1,1]
@expansion{} _[3]=[1,x2,0,0,1]
@c end example jet reference.doc:2666
@end smallexample
@end table
@c inserted refs from reference.doc:2693
@ifinfo
@menu
See
* deg::
* ideal::
* int::
* intvec::
* module::
* poly::
* vector::
@end menu
@end ifinfo
@iftex
See
@ref{deg};
@ref{ideal};
@ref{int};
@ref{intvec};
@ref{module};
@ref{poly};
@ref{vector}.
@end iftex
@c end inserted refs from reference.doc:2693
@c ---------------------------------------
@node kbase, kill, 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.
@item @strong{Example:}
@smallexample
@c reused example kbase reference.doc:2728
  ring r=32003,(x,y,z),ds;
  ideal i=x2,y2,z;
  kbase(std(i));
@expansion{} _[1]=xy
@expansion{} _[2]=y
@expansion{} _[3]=x
@expansion{} _[4]=1
  i=x2,y3,xyz;  // quotient not finite dimensional
  kbase(std(i),2);
@expansion{} _[1]=z2
@expansion{} _[2]=yz
@expansion{} _[3]=xz
@expansion{} _[4]=y2
@expansion{} _[5]=xy
@c end example kbase reference.doc:2728
@end smallexample
@end table
@c inserted refs from reference.doc:2737
@ifinfo
@menu
See
* ideal::
* module::
* vdim::
@end menu
@end ifinfo
@iftex
See
@ref{ideal};
@ref{module};
@ref{vdim}.
@end iftex
@c end inserted refs from reference.doc:2737
@c ---------------------------------------
@node kill, killattrib, kbase, 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 reused example kill reference.doc:2757
  int i=3;
  ring r=0,x,dp;
  poly p;
  listvar();
@expansion{} // r                    [0]  *ring
@expansion{} //      p                    [0]  poly
@expansion{} // i                    [0]  int 3
@expansion{} // LIB                  [0]  string standard.lib
  kill(i,r);
  // the variable `i` does not exist any more
  i;
@expansion{}    ? `i` is undefined
@expansion{}    ? error occurred in line 7: `  i;`
  listvar();
@expansion{} // LIB                  [0]  string standard.lib
@c end example kill reference.doc:2757
@end smallexample
@end table
@c inserted refs from reference.doc:2769
@ifinfo
@menu
See
* defined::
* general_lib::
* names::
@end menu
@end ifinfo
@iftex
See
@ref{defined};
@ref{general_lib};
@ref{names}.
@end iftex
@c end inserted refs from reference.doc:2769
@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 reused example killattrib reference.doc:2788
  ring r=32003,(x,y),lp;
  ideal i=maxideal(1);
  attrib(i,"isSB",1);
  attrib(i);
@expansion{} attr:isSB, type int
  killattrib(i,"isSB");
  attrib(i);
@expansion{} no attributes
@c end example killattrib reference.doc:2788
@end smallexample
@end table
@c inserted refs from reference.doc:2798
@ifinfo
@menu
See
* attrib::
* option::
@end menu
@end ifinfo
@iftex
See
@ref{attrib};
@ref{option}.
@end iftex
@c end inserted refs from reference.doc:2798
@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 reused example koszul reference.doc:2829
  ring r=32003,(x,y,z),dp;
  print(koszul(2,3));
@expansion{} -y,-z,0,
@expansion{} x, 0, -z,
@expansion{} 0, x, y
  ideal I=xz2+yz2+z3,xyz+y2z+yz2,xy2+y3+y2z;
  print(koszul(1,I));
@expansion{} xz2+yz2+z3,xyz+y2z+yz2,xy2+y3+y2z
  print(koszul(2,I));
@expansion{} -xyz-y2z-yz2,-xy2-y3-y2z,0,
@expansion{} xz2+yz2+z3,  0,          -xy2-y3-y2z,
@expansion{} 0,           xz2+yz2+z3, xyz+y2z+yz2
  print(koszul(2,I)*koszul(3,I));
@expansion{} 0,
@expansion{} 0,
@expansion{} 0
@c end example koszul reference.doc:2829
@end smallexample
@end table
@c inserted refs from reference.doc:2839
@ifinfo
@menu
See
* int::
* matrix::
@end menu
@end ifinfo
@iftex
See
@ref{int};
@ref{matrix}.
@end iftex
@c end inserted refs from reference.doc:2839
@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 reused example laguerre reference.doc:2864
ring rs1=0,(x,y),lp;
poly f=15x5+x3+x2-10;
laguerre(f,10,2);
@expansion{} [1]:
@expansion{}    (0.2930464644-I*0.9003002396)
@expansion{} [2]:
@expansion{}    (0.2930464644+I*0.9003002396)
@expansion{} [3]:
@expansion{}    (-0.7392783383-I*0.5355190078)
@expansion{} [4]:
@expansion{}    (-0.7392783383+I*0.5355190078)
@expansion{} [5]:
@expansion{}    0.8924637479
@c end example laguerre reference.doc:2864
@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 reused example lead reference.doc:2894
  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);
@expansion{} 3y
  lead(v);
@expansion{} [2x10]
  lead(i);
@expansion{} _[1]=3y
@expansion{} _[2]=z
  lead(m);
@expansion{} _[1]=[2x10]
@expansion{} _[2]=[0,0,2]
  lead(0);
@expansion{} 0
@c end example lead reference.doc:2894
@end smallexample
@end table
@c inserted refs from reference.doc:2908
@ifinfo
@menu
See
* ideal::
* leadcoef::
* leadexp::
* leadmonom::
* module::
* poly::
* vector::
@end menu
@end ifinfo
@iftex
See
@ref{ideal};
@ref{leadcoef};
@ref{leadexp};
@ref{leadmonom};
@ref{module};
@ref{poly};
@ref{vector}.
@end iftex
@c end inserted refs from reference.doc:2908
@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 reused example leadcoef reference.doc:2933
  ring r=32003,(x,y,z),(c,ds);
  poly f=x2+y+z3;
  vector v=[2*x^10,f];
  leadcoef(f);
@expansion{} 1
  leadcoef(v);
@expansion{} 2
  leadcoef(0);
@expansion{} 0
@c end example leadcoef reference.doc:2933
@end smallexample
@end table
@c inserted refs from reference.doc:2943
@ifinfo
@menu
See
* lead::
* leadexp::
* leadmonom::
* number::
* poly::
* vector::
@end menu
@end ifinfo
@iftex
See
@ref{lead};
@ref{leadexp};
@ref{leadmonom};
@ref{number};
@ref{poly};
@ref{vector}.
@end iftex
@c end inserted refs from reference.doc:2943
@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 reused example leadexp reference.doc:2967
  ring r=32003,(x,y,z),(c,ds);
  poly f=x2+y+z3;
  vector v=[2*x^10,f];
  leadexp(f);
@expansion{} 0,1,0
  leadexp(v);
@expansion{} 10,0,0,1
  leadexp(0);
@expansion{} 0,0,0
@c end example leadexp reference.doc:2967
@end smallexample
@end table
@c inserted refs from reference.doc:2977
@ifinfo
@menu
See
* intvec::
* lead::
* leadcoef::
* leadmonom::
* poly::
* vector::
@end menu
@end ifinfo
@iftex
See
@ref{intvec};
@ref{lead};
@ref{leadcoef};
@ref{leadmonom};
@ref{poly};
@ref{vector}.
@end iftex
@c end inserted refs from reference.doc:2977
@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 reused example leadmonom reference.doc:3001
  ring r=32003,(x,y,z),(c,ds);
  poly f=2x2+3y+4z3;
  vector v=[2x10,f];
  leadmonom(f);
@expansion{} y
  leadmonom(v);
@expansion{} [x10]
  leadmonom(0);
@expansion{} 0
@c end example leadmonom reference.doc:3001
@end smallexample
@end table

@c inserted refs from reference.doc:3012
@ifinfo
@menu
See
* intvec::
* lead::
* leadcoef::
* leadexp::
* poly::
* vector::
@end menu
@end ifinfo
@iftex
See
@ref{intvec};
@ref{lead};
@ref{leadcoef};
@ref{leadexp};
@ref{poly};
@ref{vector}.
@end iftex
@c end inserted refs from reference.doc:3012
@c ---------------------------------------
@node LIB, lift, leadmonom, Functions
@subsection LIB
@cindex LIB
@table @code
@item @strong{Syntax:}
@code{LIB} string_expression@code{;}
@item @strong{Type:}
none
@ifset namespaces
@item @strong{Note:}
This command is obsoleted by
@code{load(}string_expression@code{,"with");}
@end ifset
@ifclear namespaces
@item @strong{Purpose:}
reads a library of procedures from a file. 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}.
@end ifclear

@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{Syntax:}
@code{LIB;}
@item @strong{Type:}
string
@item @strong{Purpose:}
shows all loaded libraries written in Singular.

@item @strong{Example:}
@smallexample
@c reused example LIB reference.doc:3058
  option(loadLib); // show loading of libraries
  LIB;             // standard.lib is loaded
@expansion{} standard.lib

                   // the names of the procedures of inout.lib
  LIB "inout.lib"; // are now known to Singular
@expansion{} // ** loaded inout.lib (1.21.2.5,2002/06/12)
  LIB;
@expansion{} standard.lib,inout.lib
@c end example LIB reference.doc:3058
@end smallexample
@end table
@ifset namespaces
@c inserted refs from reference.doc:3069
@ifinfo
@menu
See
* Command line options::
* Namespaces::
* Procedures and libraries::
* SINGULAR libraries::
* load::
* package::
* proc::
* standard_lib::
* string::
* system::
@end menu
@end ifinfo
@iftex
See
@ref{Command line options};
@ref{Namespaces};
@ref{Procedures and libraries};
@ref{SINGULAR libraries};
@ref{load};
@ref{package};
@ref{proc};
@ref{standard_lib};
@ref{string};
@ref{system}.
@end iftex
@c end inserted refs from reference.doc:3069
@end ifset
@ifclear namespaces
@c inserted refs from reference.doc:3084
@ifinfo
@menu
See
* Command line options::
* Loading of a library::
* Procedures and libraries::
* SINGULAR libraries::
* proc::
* standard_lib::
* string::
* system::
@end menu
@end ifinfo
@iftex
See
@ref{Command line options};
@ref{Loading of a library};
@ref{Procedures and libraries};
@ref{SINGULAR libraries};
@ref{proc};
@ref{standard_lib};
@ref{string};
@ref{system}.
@end iftex
@c end inserted refs from reference.doc:3084
@end ifclear
@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*U) = 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 reused example lift reference.doc:3126
  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;
@expansion{} _[1,1]=0
@expansion{} _[1,2]=0
@c end example lift reference.doc:3126
@end smallexample
@end table
@c inserted refs from reference.doc:3136
@ifinfo
@menu
See
* division::
* ideal::
* module::
@end menu
@end ifinfo
@iftex
See
@ref{division};
@ref{ideal};
@ref{module}.
@end iftex
@c end inserted refs from reference.doc:3136
@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 reused example liftstd reference.doc:3161
  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;
@expansion{} sm[1]=xy+2z
@expansion{} sm[2]=3x2+yz
@expansion{} sm[3]=yz2+3048192z3
@expansion{} sm[4]=3024xz2-yz2
@expansion{} sm[5]=y2z-6xz
@expansion{} sm[6]=3097158156288z4+2016z3
@expansion{} sm[7]=7y6+xz
  print(T);
@expansion{} 0,1,T[1,3],   T[1,4],y,  T[1,6],0,
@expansion{} 0,0,-3x+3024z,3x,    0,  T[2,6],1,
@expansion{} 1,0,T[3,3],   T[3,4],-3x,T[3,6],0
  matrix(sm)-matrix(i)*T;
@expansion{} _[1,1]=0
@expansion{} _[1,2]=0
@expansion{} _[1,3]=0
@expansion{} _[1,4]=0
@expansion{} _[1,5]=0
@expansion{} _[1,6]=0
@expansion{} _[1,7]=0
@c end example liftstd reference.doc:3161
@end smallexample
@end table
@c inserted refs from reference.doc:3173
@ifinfo
@menu
See
* ideal::
* matrix::
* option::
* ring::
* std::
@end menu
@end ifinfo
@iftex
See
@ref{ideal};
@ref{matrix};
@ref{option};
@ref{ring};
@ref{std}.
@end iftex
@c end inserted refs from reference.doc:3173
@c ---------------------------------------
@node listvar, lres, liftstd, Functions
@subsection listvar
@cindex listvar
@table @code
@item @strong{Syntax:}
@ifset namespaces
@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 )}
@end ifset
@ifclear namespaces
@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 )}
@end ifclear
@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.

@ifset namespaces
package can be @code{Current}, @code{Up}, @code{Top} or any other
identifier of type package.
@item @strong{Example:}
@smallexample
@c reused example listvar reference.doc:3222
  proc t1 @{ @}
  proc t2 @{ @}
  ring s;
  poly ss;
  ring r;
  poly f=x+y+z;
  int i=7;
  ideal I=f,x,y;
  listvar(all);
@expansion{} // i                    [0]  int 7
@expansion{} // r                    [0]  *ring
@expansion{} //      I                    [0]  ideal, 3 generator(s)
@expansion{} //      f                    [0]  poly
@expansion{} // s                    [0]  ring
@expansion{} //      ss                   [0]  poly
@expansion{} // LIB                  [0]  string standard.lib
  listvar();
@expansion{} // i                    [0]  int 7
@expansion{} // r                    [0]  *ring
@expansion{} //      I                    [0]  ideal, 3 generator(s)
@expansion{} //      f                    [0]  poly
@expansion{} // s                    [0]  ring
@expansion{} // LIB                  [0]  string standard.lib
  listvar(r);
@expansion{} // r                    [0]  *ring
@expansion{} // I                    [0]  ideal, 3 generator(s)
@expansion{} // f                    [0]  poly
  listvar(t1);
@expansion{} // t1                   [0]  proc
  listvar(proc);
@expansion{} // t2                   [0]  proc
@expansion{} // t1                   [0]  proc
@expansion{} // fprintf              [0]  proc from standard.lib
@expansion{} // printf               [0]  proc from standard.lib
@expansion{} // sprintf              [0]  proc from standard.lib
@expansion{} // intersect1           [0]  proc from standard.lib (static)
@expansion{} // quotient4            [0]  proc from standard.lib
@expansion{} // quotient5            [0]  proc from standard.lib
@expansion{} // quotient3            [0]  proc from standard.lib
@expansion{} // quotient2            [0]  proc from standard.lib
@expansion{} // quotient1            [0]  proc from standard.lib
@expansion{} // quotient0            [0]  proc from standard.lib (static)
@expansion{} // quot1                [0]  proc from standard.lib (static)
@expansion{} // quot                 [0]  proc from standard.lib
@expansion{} // res                  [0]  proc from standard.lib
@expansion{} // groebner             [0]  proc from standard.lib
@expansion{} // stdhilb              [0]  proc from standard.lib
@expansion{} // stdfglm              [0]  proc from standard.lib
  listvar(Standard, proc);
@c end example listvar reference.doc:3222
@end smallexample
@end ifset
@ifclear namespaces
@item @strong{Example:}
@smallexample
@c reused example listvar_1 reference.doc:3243
  proc t1 @{ @}
  proc t2 @{ @}
  ring s;
  poly ss;
  ring r;
  poly f=x+y+z;
  int i=7;
  ideal I=f,x,y;
  listvar(all);
@expansion{} // i                    [0]  int 7
@expansion{} // r                    [0]  *ring
@expansion{} //      I                    [0]  ideal, 3 generator(s)
@expansion{} //      f                    [0]  poly
@expansion{} // s                    [0]  ring
@expansion{} //      ss                   [0]  poly
@expansion{} // LIB                  [0]  string standard.lib
  listvar();
@expansion{} // i                    [0]  int 7
@expansion{} // r                    [0]  *ring
@expansion{} //      I                    [0]  ideal, 3 generator(s)
@expansion{} //      f                    [0]  poly
@expansion{} // s                    [0]  ring
@expansion{} // LIB                  [0]  string standard.lib
  listvar(r);
@expansion{} // r                    [0]  *ring
@expansion{} // I                    [0]  ideal, 3 generator(s)
@expansion{} // f                    [0]  poly
  listvar(t1);
@expansion{} // t1                   [0]  proc
  listvar(proc);
@expansion{} // t2                   [0]  proc
@expansion{} // t1                   [0]  proc
@expansion{} // fprintf              [0]  proc from standard.lib
@expansion{} // printf               [0]  proc from standard.lib
@expansion{} // sprintf              [0]  proc from standard.lib
@expansion{} // intersect1           [0]  proc from standard.lib (static)
@expansion{} // quotient4            [0]  proc from standard.lib
@expansion{} // quotient5            [0]  proc from standard.lib
@expansion{} // quotient3            [0]  proc from standard.lib
@expansion{} // quotient2            [0]  proc from standard.lib
@expansion{} // quotient1            [0]  proc from standard.lib
@expansion{} // quotient0            [0]  proc from standard.lib (static)
@expansion{} // quot1                [0]  proc from standard.lib (static)
@expansion{} // quot                 [0]  proc from standard.lib
@expansion{} // res                  [0]  proc from standard.lib
@expansion{} // groebner             [0]  proc from standard.lib
@expansion{} // stdhilb              [0]  proc from standard.lib
@expansion{} // stdfglm              [0]  proc from standard.lib
@c end example listvar_1 reference.doc:3243
@end smallexample
@end ifclear
@end table
@ifset namespaces
@c inserted refs from reference.doc:3262
@ifinfo
@menu
See
* Names::
* Names in procedures::
* Namespaces::
* defined::
* names::
* package::
* type::
@end menu
@end ifinfo
@iftex
See
@ref{Names};
@ref{Names in procedures};
@ref{Namespaces};
@ref{defined};
@ref{names};
@ref{package};
@ref{type}.
@end iftex
@c end inserted refs from reference.doc:3262
@end ifset
@ifclear namespaces
@c inserted refs from reference.doc:3274
@ifinfo
@menu
See
* Names::
* Names in procedures::
* defined::
* names::
* type::
@end menu
@end ifinfo
@iftex
See
@ref{Names};
@ref{Names in procedures};
@ref{defined};
@ref{names};
@ref{type}.
@end iftex
@c end inserted refs from reference.doc:3274
@end ifclear
@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 La Scala'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 reused example lres reference.doc:3334
  ring r=0,(x,y,z),dp;
  ideal I=xz,yz,x3-y3;
  def L=lres(I,0);
  print(betti(L),"betti");
@expansion{}            0     1     2
@expansion{} ------------------------
@expansion{}     0:     1     -     -
@expansion{}     1:     -     2     1
@expansion{}     2:     -     1     1
@expansion{} ------------------------
@expansion{} total:     1     3     2
  L[2];     // the first syzygy module of r/I
@expansion{} _[1]=-x*gen(1)+y*gen(2)
@expansion{} _[2]=-x2*gen(2)+y2*gen(1)+z*gen(3)
@c end example lres reference.doc:3334
@end smallexample
@end table
@c inserted refs from reference.doc:3343
@ifinfo
@menu
See
* betti::
* hres::
* ideal::
* int::
* minres::
* module::
* mres::
* res::
* sres::
@end menu
@end ifinfo
@iftex
See
@ref{betti};
@ref{hres};
@ref{ideal};
@ref{int};
@ref{minres};
@ref{module};
@ref{mres};
@ref{res};
@ref{sres}.
@end iftex
@c end inserted refs from reference.doc:3343
@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 reused example maxideal reference.doc:3369
  ring r=32003,(x,y,z),dp;
  maxideal(2);
@expansion{} _[1]=z2
@expansion{} _[2]=yz
@expansion{} _[3]=y2
@expansion{} _[4]=xz
@expansion{} _[5]=xy
@expansion{} _[6]=x2
@c end example maxideal reference.doc:3369
@end smallexample
@end table
@c inserted refs from reference.doc:3375
@ifinfo
@menu
See
* ideal::
* ring::
@end menu
@end ifinfo
@iftex
See
@ref{ideal};
@ref{ring}.
@end iftex
@c end inserted refs from reference.doc:3375
@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:}
int
@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 reused example memory reference.doc:3405
  ring r=0,(x(1..500)),dp;
  poly p=(x(1)+x(500))^50;
  proc ReportMemoryUsage()
  @{  "Memory currently used by SINGULAR     :",memory(0),"Byte (",
     memory(0)/1023, "KByte)" +newline+
     "Memory currently allocated from system:",memory(1), "Byte (",
     memory(1)/1023, "KByte)";
     "Maximal memory allocated from system  :",memory(2), "Byte (",
     memory(2)/1023, "KByte)";
  @}
  ReportMemoryUsage();
@expansion{} Memory currently used by SINGULAR     : 206940 Byte ( 202 KByte)
@expansion{} Memory currently allocated from system: 669128 Byte ( 654 KByte)
@expansion{} Maximal memory allocated from system  : 669128 Byte ( 654 KByte)
  kill p;
  ReportMemoryUsage(); // less memory used: p killed
@expansion{} Memory currently used by SINGULAR     : 153704 Byte ( 150 KByte)
@expansion{} Memory currently allocated from system: 669128 Byte ( 654 KByte)
@expansion{} Maximal memory allocated from system  : 669128 Byte ( 654 KByte)
  kill r;
  ReportMemoryUsage(); // even less memory: r killed
@expansion{} Memory currently used by SINGULAR     : 143124 Byte ( 139 KByte)
@expansion{} Memory currently allocated from system: 669128 Byte ( 654 KByte)
@expansion{} Maximal memory allocated from system  : 669128 Byte ( 654 KByte)
@c end example memory reference.doc:3405
@end smallexample
@end table
@c inserted refs from reference.doc:3424
@ifinfo
@menu
See
* option::
* system::
@end menu
@end ifinfo
@iftex
See
@ref{option};
@ref{system}.
@end iftex
@c end inserted refs from reference.doc:3424
@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 reused example minbase reference.doc:3445
  ring r=181,(x,y,z),(c,ls);
  ideal id2=x2+xyz,y2-z3y,z3+y5xz;
  ideal id4=maxideal(3)+id2;
  size(id4);
@expansion{} 13
  minbase(id4);
@expansion{} _[1]=x2
@expansion{} _[2]=xyz+x2
@expansion{} _[3]=xz2
@expansion{} _[4]=y2
@expansion{} _[5]=yz2
@expansion{} _[6]=z3
@c end example minbase reference.doc:3445
@end smallexample
@end table
@c inserted refs from reference.doc:3454
@ifinfo
@menu
See
* mstd::
@end menu
@end ifinfo
@iftex
See
@ref{mstd}.
@end iftex
@c end inserted refs from reference.doc:3454
@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 reused example minor reference.doc:3475
  ring r=0,(x(1..5)),ds;
  matrix m[2][4]=x(1..4),x(2..5);
  print(m);
@expansion{} x(1),x(2),x(3),x(4),
@expansion{} x(2),x(3),x(4),x(5)
  ideal j=minor(m,2);
  j;
@expansion{} j[1]=-x(4)^2+x(3)*x(5)
@expansion{} j[2]=-x(3)*x(4)+x(2)*x(5)
@expansion{} j[3]=-x(2)*x(4)+x(1)*x(5)
@expansion{} j[4]=x(3)^2-x(2)*x(4)
@expansion{} j[5]=x(2)*x(3)-x(1)*x(4)
@expansion{} j[6]=-x(2)^2+x(1)*x(3)
  minor(m,2,std(ideal(x(1))));
@expansion{} _[1]=-x(4)^2+x(3)*x(5)
@expansion{} _[2]=-x(3)*x(4)+x(2)*x(5)
@expansion{} _[3]=-x(2)*x(4)
@expansion{} _[4]=x(3)^2-x(2)*x(4)
@expansion{} _[5]=x(2)*x(3)
@expansion{} _[6]=-x(2)^2
@c end example minor reference.doc:3475
@end smallexample
@end table
@c inserted refs from reference.doc:3485
@ifinfo
@menu
See
* det::
@end menu
@end ifinfo
@iftex
See
@ref{det}.
@end iftex
@c end inserted refs from reference.doc:3485
@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 reused example minres reference.doc:3507
  ring r1=32003,(x,y),dp;
  ideal i=x5+xy4,x3+x2y+xy2+y3;
  resolution rs=lres(i,0);
  rs;
@expansion{}   1       2       1
@expansion{} r1 <--  r1 <--  r1
@expansion{}
@expansion{} 0       1       2
@expansion{} resolution not minimized yet
@expansion{}
  list(rs);
@expansion{} [1]:
@expansion{}    _[1]=x3+x2y+xy2+y3
@expansion{}    _[2]=xy4
@expansion{}    _[3]=y7
@expansion{} [2]:
@expansion{}    _[1]=-y4*gen(1)+x2*gen(2)+xy*gen(2)+y2*gen(2)+gen(3)
@expansion{}    _[2]=-y3*gen(2)+x*gen(3)
  minres(rs);
@expansion{}   1       2       1
@expansion{} r1 <--  r1 <--  r1
@expansion{}
@expansion{} 0       1       2
@expansion{}
  list(rs);
@expansion{} [1]:
@expansion{}    _[1]=x3+x2y+xy2+y3
@expansion{}    _[2]=xy4
@expansion{} [2]:
@expansion{}    _[1]=xy4*gen(1)-x3*gen(2)-x2y*gen(2)-xy2*gen(2)-y3*gen(2)
@c end example minres reference.doc:3507
@end smallexample
@end table
@c inserted refs from reference.doc:3518
@ifinfo
@menu
See
* mres::
* res::
* sres::
@end menu
@end ifinfo
@iftex
See
@ref{mres};
@ref{res};
@ref{sres}.
@end iftex
@c end inserted refs from reference.doc:3518
@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{Example:}
@smallexample
@c reused example modulo reference.doc:3612
  ring r;
  ideal h1=x,y,z;
  ideal h2=x;
  module m=modulo(h1,h2);
  print(m);
@expansion{} 1,0, 0,0,
@expansion{} 0,-z,x,0,
@expansion{} 0,y, 0,x
@c end example modulo reference.doc:3612
@end smallexample
@end table
@c inserted refs from reference.doc:3621
@ifinfo
@menu
See
* syz::
@end menu
@end ifinfo
@iftex
See
@ref{syz}.
@end iftex
@c end inserted refs from reference.doc:3621
@c ---------------------------------------
@node monitor, mpresmat, modulo, Functions
@subsection monitor
@cindex monitor
@table @code
@item @strong{Syntax:}
@code{monitor (} string_expression @code{)}
@*@code{monitor (} string_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
  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
@end smallexample
@end table
@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 reused example mpresmat reference.doc:3675
  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);
@expansion{} -16,0,  -10,0,  (s),0,  0,  0,  0,  0,
@expansion{} 0,  -16,0,  -10,(u),(s),0,  0,  0,  0,
@expansion{} 2,  0,  1,  0,  0,  (u),0,  0,  0,  0,
@expansion{} 0,  2,  0,  1,  0,  0,  0,  0,  0,  0,
@expansion{} 0,  0,  0,  0,  (t),0,  -10,(s),0,  -16,
@expansion{} 1,  0,  0,  0,  0,  (t),0,  (u),(s),0,
@expansion{} 0,  1,  0,  0,  0,  0,  1,  0,  (u),2,
@expansion{} 1,  0,  1,  0,  0,  0,  0,  (t),0,  0,
@expansion{} 0,  1,  0,  1,  0,  0,  0,  0,  (t),1,
@expansion{} 0,  0,  0,  0,  0,  0,  1,  0,  0,  1
@c end example mpresmat reference.doc:3675
@end smallexample
@end table
@c inserted refs from reference.doc:3683
@ifinfo
@menu
See
* uressolve::
@end menu
@end ifinfo
@iftex
See
@ref{uressolve}.
@end iftex
@c end inserted refs from reference.doc:3683
@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 reused example mres reference.doc:3750
  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;
@expansion{}  1      4      15      18      7      1
@expansion{} r <--  r <--  r <--   r <--   r <--  r
@expansion{}
@expansion{} 0      1      2       3       4      5
@expansion{}
  // projective dimension of M is 5
@c end example mres reference.doc:3750
@end smallexample
@end table
@c inserted refs from reference.doc:3760
@ifinfo
@menu
See
* hres::
* ideal::
* lres::
* module::
* res::
* sres::
@end menu
@end ifinfo
@iftex
See
@ref{hres};
@ref{ideal};
@ref{lres};
@ref{module};
@ref{res};
@ref{sres}.
@end iftex
@c end inserted refs from reference.doc:3760
@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. If the monomial ordering is global, then the second entry is both
a generating set for the
ideal, resp.@: module, and a subset of the standard basis.
If, additionally, the input is homogeneous then the second entry is a
minimal generating set for the ideal, resp.@: module.
@item @strong{Example:}
@smallexample
@c reused example mstd reference.doc:3788
  ring r=0,(x,y,z,t),dp;
  poly f=x3+y4+z6+xyz;
  ideal j=jacob(f),f;
  j=homog(j,t);j;
@expansion{} j[1]=3x2+yz
@expansion{} j[2]=4y3+xzt
@expansion{} j[3]=6z5+xyt3
@expansion{} j[4]=0
@expansion{} j[5]=z6+y4t2+x3t3+xyzt3
  mstd(j);
@expansion{} [1]:
@expansion{}    _[1]=3x2+yz
@expansion{}    _[2]=4y3+xzt
@expansion{}    _[3]=6z5+xyt3
@expansion{}    _[4]=xyzt3
@expansion{}    _[5]=y2z2t3
@expansion{}    _[6]=yz3t4
@expansion{}    _[7]=xz3t4
@expansion{}    _[8]=yz2t7
@expansion{}    _[9]=xz2t7
@expansion{}    _[10]=y2zt7
@expansion{}    _[11]=xy2t7
@expansion{} [2]:
@expansion{}    _[1]=3x2+yz
@expansion{}    _[2]=4y3+xzt
@expansion{}    _[3]=6z5+xyt3
@expansion{}    _[4]=xyzt3
@c end example mstd reference.doc:3788
@end smallexample
@end table
@c inserted refs from reference.doc:3797
@ifinfo
@menu
See
* ideal::
* minbase::
* module::
* std::
@end menu
@end ifinfo
@iftex
See
@ref{ideal};
@ref{minbase};
@ref{module};
@ref{std}.
@end iftex
@c end inserted refs from reference.doc:3797
@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 reused example mult reference.doc:3825
  ring r=32003,(x,y),ds;
  poly f=(x3+y5)^2+x2y7;
  ideal i=std(jacob(f));
  mult(i);
@expansion{} 46
  mult(std(f));
@expansion{} 6
@c end example mult reference.doc:3825
@end smallexample
@end table
@c inserted refs from reference.doc:3834
@ifinfo
@menu
See
* degree::
* dim::
* ideal::
* std::
* vdim::
@end menu
@end ifinfo
@iftex
See
@ref{degree};
@ref{dim};
@ref{ideal};
@ref{std};
@ref{vdim}.
@end iftex
@c end inserted refs from reference.doc:3834
@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 reused example nameof reference.doc:3855
  int i=9;
  string s=nameof(i);
  s;
@expansion{} i
  nameof(s);
@expansion{} s
  nameof(i+1); //returns the empty string:
@expansion{}
  nameof(basering);
@expansion{} basering
  basering;
@expansion{}    ? `basering` is undefined
@expansion{}    ? error occurred in line 7: `  basering;`
  ring r;
  nameof(basering);
@expansion{} r
@c end example nameof reference.doc:3855
@end smallexample
@end table
@c inserted refs from reference.doc:3868
@ifinfo
@menu
See
* names::
* reservedName::
* typeof::
@end menu
@end ifinfo
@iftex
See
@ref{names};
@ref{reservedName};
@ref{typeof}.
@end iftex
@c end inserted refs from reference.doc:3868
@c ---------------------------------------
@node names, ncols, nameof, Functions
@subsection names
@cindex names
@table @code
@item @strong{Syntax:}
@code{names ( )}
@*@code{names (} ring_name @code{)}
@ifset namespaces
@*@code{names (} package_name @code{)}
@end ifset
@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.

@ifset namespaces
package_name can be @code{Current}, @code{Up}, @code{Top} or any other
identifier of type package.
@item @strong{Example:}
@smallexample
@c reused example names reference.doc:3897
  int i=9;
  ring r;
  poly f;
  package p;
  int p::j;
@expansion{}    ? package is not supported in this version
@expansion{}    ? object to declare is not a name
@expansion{}    ? error occurred in line 5: `  int p::j;`
@expansion{}    ? wrong type declaration. type 'help int;'
  ring p::q;
@expansion{}    ? package is not supported in this version
@expansion{}    ? error occurred in line 6: `  ring p::q;`
@expansion{}    ? wrong type declaration. type 'help ring;'
  poly g;
  setring r;
  names();
@expansion{} [1]:
@expansion{}    p
@expansion{} [2]:
@expansion{}    r
@expansion{} [3]:
@expansion{}    i
@expansion{} [4]:
@expansion{}    fprintf
@expansion{} [5]:
@expansion{}    printf
@expansion{} [6]:
@expansion{}    sprintf
@expansion{} [7]:
@expansion{}    intersect1
@expansion{} [8]:
@expansion{}    quotient4
@expansion{} [9]:
@expansion{}    quotient5
@expansion{} [10]:
@expansion{}    quotient3
@expansion{} [11]:
@expansion{}    quotient2
@expansion{} [12]:
@expansion{}    quotient1
@expansion{} [13]:
@expansion{}    quotient0
@expansion{} [14]:
@expansion{}    quot1
@expansion{} [15]:
@expansion{}    quot
@expansion{} [16]:
@expansion{}    res
@expansion{} [17]:
@expansion{}    groebner
@expansion{} [18]:
@expansion{}    stdhilb
@expansion{} [19]:
@expansion{}    stdfglm
@expansion{} [20]:
@expansion{}    LIB
  names(r);
@expansion{} [1]:
@expansion{}    g
@expansion{} [2]:
@expansion{}    f
  names(p);
@expansion{} empty list
  names(p::q);
@expansion{}    ? package is not supported in this version
@expansion{}    ? error occurred in line 12: `  names(p::q);`
@c end example names reference.doc:3897
@end smallexample
@end ifset
@ifclear namespaces
@item @strong{Example:}
@smallexample
@c reused example names_1 reference.doc:3916
  int i=9;
  ring r;
  poly f;
  poly g;
  setring r;
  names();
@expansion{} [1]:
@expansion{}    r
@expansion{} [2]:
@expansion{}    i
@expansion{} [3]:
@expansion{}    fprintf
@expansion{} [4]:
@expansion{}    printf
@expansion{} [5]:
@expansion{}    sprintf
@expansion{} [6]:
@expansion{}    intersect1
@expansion{} [7]:
@expansion{}    quotient4
@expansion{} [8]:
@expansion{}    quotient5
@expansion{} [9]:
@expansion{}    quotient3
@expansion{} [10]:
@expansion{}    quotient2
@expansion{} [11]:
@expansion{}    quotient1
@expansion{} [12]:
@expansion{}    quotient0
@expansion{} [13]:
@expansion{}    quot1
@expansion{} [14]:
@expansion{}    quot
@expansion{} [15]:
@expansion{}    res
@expansion{} [16]:
@expansion{}    groebner
@expansion{} [17]:
@expansion{}    stdhilb
@expansion{} [18]:
@expansion{}    stdfglm
@expansion{} [19]:
@expansion{}    LIB
  names(r);
@expansion{} [1]:
@expansion{}    g
@expansion{} [2]:
@expansion{}    f
@c end example names_1 reference.doc:3916
@end smallexample
@end ifclear
@end table
@c inserted refs from reference.doc:3928
@ifinfo
@menu
See
* nameof::
* reservedName::
@end menu
@end ifinfo
@iftex
See
@ref{nameof};
@ref{reservedName}.
@end iftex
@c end inserted refs from reference.doc:3928
@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 reused example ncols reference.doc:3953
  ring r;
  matrix m[5][6];
  ncols(m);
@expansion{} 6
  ideal i=x,0,y;
  ncols(i);
@expansion{} 3
  size(i);
@expansion{} 2
@c end example ncols reference.doc:3953
@end smallexample
@end table
@c inserted refs from reference.doc:3963
@ifinfo
@menu
See
* matrix::
* nrows::
* size::
@end menu
@end ifinfo
@iftex
See
@ref{matrix};
@ref{nrows};
@ref{size}.
@end iftex
@c end inserted refs from reference.doc:3963
@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 reused example npars reference.doc:3982
  ring r=(23,t,v),(x,a(1..7)),lp;
  // the parameters are t,v
  npars(r);
@expansion{} 2
@c end example npars reference.doc:3982
@end smallexample
@end table
@c inserted refs from reference.doc:3989
@ifinfo
@menu
See
* par::
* parstr::
* ring::
@end menu
@end ifinfo
@iftex
See
@ref{par};
@ref{parstr};
@ref{ring}.
@end iftex
@c end inserted refs from reference.doc:3989
@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 reused example nres reference.doc:4058
  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;
@expansion{}  1      4      15      18      7      1
@expansion{} r <--  r <--  r <--   r <--   r <--  r
@expansion{}
@expansion{} 0      1      2       3       4      5
@expansion{} resolution not minimized yet
@expansion{}
@c end example nres reference.doc:4058
@end smallexample
@end table
@c inserted refs from reference.doc:4067
@ifinfo
@menu
See
* hres::
* ideal::
* lres::
* module::
* mres::
* res::
* resolution::
* sres::
@end menu
@end ifinfo
@iftex
See
@ref{hres};
@ref{ideal};
@ref{lres};
@ref{module};
@ref{mres};
@ref{res};
@ref{resolution};
@ref{sres}.
@end iftex
@c end inserted refs from reference.doc:4067
@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 reused example nrows reference.doc:4099
  ring R;
  matrix M[2][3];
  nrows(M);
@expansion{} 2
  nrows(freemodule(4));
@expansion{} 4
  module m=[0,0,1];
  nrows(m);
@expansion{} 3
  nrows([0,x,0]);
@expansion{} 2
@c end example nrows reference.doc:4099
@end smallexample
@end table
@c inserted refs from reference.doc:4110
@ifinfo
@menu
See
* gen::
* matrix::
* module::
* ncols::
* vector::
@end menu
@end ifinfo
@iftex
See
@ref{gen};
@ref{matrix};
@ref{module};
@ref{ncols};
@ref{vector}.
@end iftex
@c end inserted refs from reference.doc:4110
@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 reused example nvars reference.doc:4131
  ring r=(23,t,v),(x,a(1..7)),ls;
  // the variables are x,a(1),...,a(7)
  nvars(r);
@expansion{} 8
@c end example nvars reference.doc:4131
@end smallexample
@end table
@c inserted refs from reference.doc:4138
@ifinfo
@menu
See
* npars::
* ring::
* var::
* varstr::
@end menu
@end ifinfo
@iftex
See
@ref{npars};
@ref{ring};
@ref{var};
@ref{varstr}.
@end iftex
@c end inserted refs from reference.doc:4138
@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 inserted refs from reference.doc:4163
@ifinfo
@menu
See
* close::
* link::
@end menu
@end ifinfo
@iftex
See
@ref{close};
@ref{link}.
@end iftex
@c end inserted refs from reference.doc:4163
@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
@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{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)
@item @code{minRes}
@cindex minRes, option
special (additional) minimizing during computations (@code{res}, @code{mres}),
@*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{prot}
@cindex prot, option
@cindex protocoll 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{sres},
@code{std},
@code{stdfglm},
@code{stdhilb},
@code{syz}.
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 inhomogeneous 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.
@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 reused example option reference.doc:4356
  option(prot);
  option();
@expansion{} //options: prot redefine usage prompt
  option(notSugar);
  option();
@expansion{} //options: prot notSugar redefine usage prompt
  option(noprot);
  option();
@expansion{} //options: notSugar redefine usage prompt
  option(none);
  option();
@expansion{} //options: none
  ring r=0,x,dp;
  degBound=22;
  option();
@expansion{} //options: degBound redTail redThrough intStrategy
  intvec i=option(get);
  option(none);
  option(set,i);
  option();
@expansion{} //options: degBound redTail redThrough intStrategy
@c end example option reference.doc:4356
@end smallexample
@end table

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

@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}
@item @tab @tab @tab
@item @tab @code{lres}
@tab @code{.} @tab minimal syzygy found
@item @tab @tab @code{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{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 @code{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 inserted refs from reference.doc:4442
@ifinfo
@menu
See
* degBound::
* multBound::
* std::
@end menu
@end ifinfo
@iftex
See
@ref{degBound};
@ref{multBound};
@ref{std}.
@end iftex
@c end inserted refs from reference.doc:4442
@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}.
@item @strong{Example:}
@smallexample
@c reused example ord reference.doc:4466
  ring r=7,(x,y),wp(2,3);
  ord(0);
@expansion{} -1
  poly f=x2+y3;  // weight on y is 3
  ord(f);
@expansion{} 9
  ring R=7,(x,y),ws(2,3);
  poly f=x2+y3;
  ord(f);
@expansion{} 4
  vector v=[x2,y];
  ord(v);
@expansion{} 3
@c end example ord reference.doc:4466
@end smallexample
@end table
@c inserted refs from reference.doc:4479
@ifinfo
@menu
See
* deg::
* poly::
* vector::
@end menu
@end ifinfo
@iftex
See
@ref{deg};
@ref{poly};
@ref{vector}.
@end iftex
@c end inserted refs from reference.doc:4479
@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 reused example ordstr reference.doc:4498
  ring r=7,(x,y),wp(2,3);
  ordstr(r);
@expansion{} wp(2,3),C
@c end example ordstr reference.doc:4498
@end smallexample
@end table
@c inserted refs from reference.doc:4504
@ifinfo
@menu
See
* charstr::
* parstr::
* ring::
* varstr::
@end menu
@end ifinfo
@iftex
See
@ref{charstr};
@ref{parstr};
@ref{ring};
@ref{varstr}.
@end iftex
@c end inserted refs from reference.doc:4504
@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{Note:}
This command should only be used if the basering has at least one parameter.
@item @strong{Example:}
@smallexample
@c reused example par reference.doc:4526
  ring r=(0,a,b,c),(x,y,z),dp;
  char(r);  // char to get the characteristic
@expansion{} 0
  par(2);   // par to get the n-th parameter
@expansion{} (b)
@c end example par reference.doc:4526
@end smallexample
@end table
@c inserted refs from reference.doc:4533
@ifinfo
@menu
See
* char::
* npars::
* parstr::
* ring::
* var::
@end menu
@end ifinfo
@iftex
See
@ref{char};
@ref{npars};
@ref{parstr};
@ref{ring};
@ref{var}.
@end iftex
@c end inserted refs from reference.doc:4533
@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 reused example pardeg reference.doc:4554
  ring r=(0,a,b,c),(x,y,z),dp;
  pardeg(a^2*b);
@expansion{} 3
@c end example pardeg reference.doc:4554
@end smallexample
@end table
@c inserted refs from reference.doc:4560
@ifinfo
@menu
See
* deg::
* number::
* ring::
* var::
@end menu
@end ifinfo
@iftex
See
@ref{deg};
@ref{number};
@ref{ring};
@ref{var}.
@end iftex
@c end inserted refs from reference.doc:4560
@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 reused example parstr reference.doc:4585
  ring r=(7,a,b,c),(x,y),wp(2,3);
  parstr(r);
@expansion{} a,b,c
  parstr(2);
@expansion{} b
  parstr(r,3);
@expansion{} c
@c end example parstr reference.doc:4585
@end smallexample
@end table
@c inserted refs from reference.doc:4593
@ifinfo
@menu
See
* charstr::
* npars::
* ordstr::
* par::
* ring::
* varstr::
@end menu
@end ifinfo
@iftex
See
@ref{charstr};
@ref{npars};
@ref{ordstr};
@ref{par};
@ref{ring};
@ref{varstr}.
@end iftex
@c end inserted refs from reference.doc:4593
@c ---------------------------------------
@node preimage, prime, parstr, Functions
@subsection preimage
@cindex preimage
@cindex kernel

@table @code
@item @strong{Syntax:}
@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:}
ideal
@item @strong{Purpose:}
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:}
To compute the kernel of a map, the preimage of zero has to be determined.
Hence there is no special command for computing the kernel of a map in
@sc{Singular}.
@item @strong{Example:}
@smallexample
@c reused example preimage reference.doc:4626
  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;
  setring r1;
  ideal i1=preimage(r,f,i1);
  i1;
@expansion{} i1[1]=w
@expansion{} i1[2]=y
@expansion{} i1[3]=x
  // the kernel of f
  preimage(r,f,i0);
@expansion{} _[1]=w
@c end example preimage reference.doc:4626
@end smallexample
@end table
@c inserted refs from reference.doc:4641
@ifinfo
@menu
See
* ideal::
* map::
* ring::
@end menu
@end ifinfo
@iftex
See
@ref{ideal};
@ref{map};
@ref{ring}.
@end iftex
@c end inserted refs from reference.doc:4641
@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 then 32004 smaller or equal to the argument;
@*returns 2 for all arguments smaller than 3.
@item @strong{Example:}
@smallexample
@c reused example prime reference.doc:4661
  prime(32004);
@expansion{} 32003
  prime(0);
@expansion{} 2
  prime(-1);
@expansion{} 2
@c end example prime reference.doc:4661
@end smallexample
@end table
@c inserted refs from reference.doc:4668
@ifinfo
@menu
See
* general_lib::
* int::
@end menu
@end ifinfo
@iftex
See
@ref{general_lib};
@ref{int}.
@end iftex
@c end inserted refs from reference.doc:4668
@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. See
the description of the format string @code{"betti"} below for more
details.
@*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 "betti"
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
@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");}
@end table
@item @strong{Example:}
@smallexample
@c reused example print reference.doc:4742
  ring r=0,(x,y,z),dp;
  module m=[1,y],[0,x+z];
  m;
@expansion{} m[1]=y*gen(2)+gen(1)
@expansion{} m[2]=x*gen(2)+z*gen(2)
  print(m);  // the columns generate m
@expansion{} 1,0,
@expansion{} y,x+z
  string s=print(m,"%s"); s;
@expansion{} y*gen(2)+gen(1),x*gen(2)+z*gen(2)
  s=print(m,"%2s"); s;
@expansion{} y*gen(2)+gen(1),
@expansion{} x*gen(2)+z*gen(2)
@expansion{}
  s=print(m,"%l"); s;
@expansion{} module(y*gen(2)+gen(1),x*gen(2)+z*gen(2))
  s=print(m,"%;"); s;
@expansion{} m[1]=y*gen(2)+gen(1)
@expansion{} m[2]=x*gen(2)+z*gen(2)
@expansion{}
  s=print(m,"%t"); s;
@expansion{} // m                    [0]  module, rk 2, 2 generator(s)
@expansion{} m[1]=y*gen(2)+gen(1)
@expansion{} m[2]=x*gen(2)+z*gen(2)
  s=print(m,"%p"); s;
@expansion{} 1,0,
@expansion{} y,x+z
@expansion{}
  intmat M=betti(mres(m,0));
  print(M,"betti");
@expansion{}            0     1
@expansion{} ------------------
@expansion{}     0:     1     1
@expansion{} ------------------
@expansion{} total:     1     1
  list l=r,M;
  s=print(l,"%s"); s;
@expansion{} (0),(x,y,z),(dp(3),C),1,1
  s=print(l,"%2s"); s;
@expansion{} (0),(x,y,z),(dp(3),C),
@expansion{} 1,1
@expansion{}
  s=print(l,"%l"); s;
@expansion{} list("(0),(x,y,z),(dp(3),C)",intmat(intvec(1,1 ),1,2))
@c end example print reference.doc:4742
@end smallexample
@end table
@c inserted refs from reference.doc:4762
@ifinfo
@menu
See
* Type conversion and casting::
* betti::
* dbprint::
* fprintf::
* printf::
* short::
* sprintf::
* string type cast::
* type::
@end menu
@end ifinfo
@iftex
See
@ref{Type conversion and casting};
@ref{betti};
@ref{dbprint};
@ref{fprintf};
@ref{printf};
@ref{short};
@ref{sprintf};
@ref{string type cast};
@ref{type}.
@end iftex
@c end inserted refs from reference.doc:4762

@c ---------------------------------------
@node printf, prune, print, Functions
@subsection printf
@cindex printf
@c start include of docu for standard.lib:printf
@c replaced @subsubsection by @sub
@c ---content printf---
Procedure from library @code{standard.lib} (@pxref{standard_lib}).

@table @asis
@item @strong{Syntax:}
@code{printf (} string_expression @code{[,} any_expressions@code{] )}

@item @strong{Return:}
none

@item @strong{Purpose:}
@code{printf(fmt,...);} performs output formatting. The first
argument is a format control string. Additional arguments may be
required, depending on the content of the control string. A series
of output characters is generated as directed by the control string;
these characters are displayed (i.e., printed to standard out). @*
The control string @code{fmt} is simply text to be copied, except
that the string may contain conversion specifications. @*
Do @code{help print;} for a listing of valid conversion
specifications. As an addition to the conversions of @code{print},
the @code{%n} and @code{%2} conversion specification does not
consume an additional argument, but simply generates a newline
character.

@item @strong{Note:}
If one of the additional arguments is a list, then it should be
enclosed once more into a @code{list()} command, since passing a
list as an argument flattens the list by one level.

@end table
@strong{Example:}
@smallexample
@c reused example printf d2t_singular/standard_lib.doc:450
  ring r=0,(x,y,z),dp;
module m=[1,y],[0,x+z];
intmat M=betti(mres(m,0));
list l=r,m,M;
printf("s:%s,l:%l",1,2);
@expansion{} s:1,l:int(2)
printf("s:%s",l);
@expansion{} s:(0),(x,y,z),(dp(3),C)
printf("s:%s",list(l));
@expansion{} s:(0),(x,y,z),(dp(3),C),y*gen(2)+gen(1),x*gen(2)+z*gen(2),1,1
printf("2l:%2l",list(l));
@expansion{} 2l:list("(0),(x,y,z),(dp(3),C)",
@expansion{} module(y*gen(2)+gen(1),
@expansion{} x*gen(2)+z*gen(2)),
@expansion{} intmat(intvec(1,1 ),1,2))
@expansion{}
printf("%p",list(l));
@expansion{} [1]:
@expansion{}    //   characteristic : 0
@expansion{} //   number of vars : 3
@expansion{} //        block   1 : ordering dp
@expansion{} //                  : names    x y z
@expansion{} //        block   2 : ordering C
@expansion{} [2]:
@expansion{}    _[1]=y*gen(2)+gen(1)
@expansion{}    _[2]=x*gen(2)+z*gen(2)
@expansion{} [3]:
@expansion{}    1,1
@expansion{}
printf("%;",list(l));
@expansion{} [1]:
@expansion{}    //   characteristic : 0
@expansion{} //   number of vars : 3
@expansion{} //        block   1 : ordering dp
@expansion{} //                  : names    x y z
@expansion{} //        block   2 : ordering C
@expansion{} [2]:
@expansion{}    _[1]=y*gen(2)+gen(1)
@expansion{}    _[2]=x*gen(2)+z*gen(2)
@expansion{} [3]:
@expansion{}    1,1
@expansion{}
printf("%b",M);
@expansion{}            0     1
@expansion{} ------------------
@expansion{}     0:     1     1
@expansion{} ------------------
@expansion{} total:     1     1
@expansion{}
@c end example printf d2t_singular/standard_lib.doc:450
@end smallexample
@c inserted refs from d2t_singular/standard_lib.doc:464
@ifinfo
@menu
See also:
* fprintf::
* print::
* sprintf::
* string::
@end menu
@end ifinfo
@iftex
@strong{See also:}
@ref{fprintf};
@ref{print};
@ref{sprintf};
@ref{string}.
@end iftex
@c end inserted refs from d2t_singular/standard_lib.doc:464

@c ---end content printf---
@c generated lib proc docu for standard.lib:printf reference.doc:4779
@c end include of docu for standard.lib:printf

@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{Example:}
@smallexample
@c reused example prune reference.doc:4795
  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);
@expansion{} 1,0,x,x+y,
@expansion{} 0,0,y,0,
@expansion{} 0,1,0,0,
@expansion{} 0,0,z,0,
@expansion{} 0,0,0,1
  print(prune(m));
@expansion{} y,
@expansion{} z
@c end example prune reference.doc:4795
@end smallexample
@end table
@c inserted refs from reference.doc:4803
@ifinfo
@menu
See
* module::
@end menu
@end ifinfo
@iftex
See
@ref{module}.
@end iftex
@c end inserted refs from reference.doc:4803
@c ---------------------------------------
@node qhweight, quot, 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 reused example qhweight reference.doc:4821
  ring h1=32003,(t,x,y,z),dp;
  ideal i=x4+y3+z2;
  qhweight(i);
@expansion{} 0,3,4,6
@c end example qhweight reference.doc:4821
@end smallexample
@end table
@c inserted refs from reference.doc:4828
@ifinfo
@menu
See
* ideal::
* intvec::
* weight::
@end menu
@end ifinfo
@iftex
See
@ref{ideal};
@ref{intvec};
@ref{weight}.
@end iftex
@c end inserted refs from reference.doc:4828

@c ---------------------------------------
@node quot, quote, qhweight, Functions
@subsection quot
@cindex quot
@c start include of docu for standard.lib:quot
@c replaced @subsubsection by @sub
@c ---content quot---
Procedure from library @code{standard.lib} (@pxref{standard_lib}).

@table @asis
@item @strong{Syntax:}
@code{quot (} module_expression@code{,} module_expression @code{)}
@*@code{quot (} module_expression@code{,} module_expression@code{,}
int_expression @code{)}
@*@code{quot (} ideal_expression@code{,} ideal_expression @code{)}
@*@code{quot (} ideal_expression@code{,} ideal_expression@code{,}
int_expression @code{)}

@item @strong{Type:}
ideal

@item @strong{Syntax:}
@code{quot (} module_expression@code{,} ideal_expression @code{)}

@item @strong{Type:}
module

@item @strong{Purpose:}
computes the quotient of the 1st and the 2nd argument.
If a 3rd argument 'n' is given the n-th method is used
(n=1...5).

@end table
@strong{Example:}
@smallexample
@c reused example quot d2t_singular/standard_lib.doc:202
  ring r=181,(x,y,z),(c,ls);
ideal id1=maxideal(4);
ideal id2=x2+xyz,y2-z3y,z3+y5xz;
option(prot);
ideal id3=quotient(id1,id2);
@expansion{} [1023:1]4(14)s(13)s(12)s(11)s(10)s(9)s(8)s(7)s(6)s(5)s(4)s(3)s(2)sss
@expansion{} product criterion:12 chain criterion:0
@expansion{} @{3@}[1023:3]8(2)s(4)s(5)s9s.s.s.s.s.s
@expansion{} product criterion:0 chain criterion:39
id3;
@expansion{} id3[1]=z2
@expansion{} id3[2]=yz
@expansion{} id3[3]=y2
@expansion{} id3[4]=xz
@expansion{} id3[5]=xy
@expansion{} id3[6]=x2
ideal id4=quot(id1,id2,1);
@expansion{} [1023:2]4(14)s(13)s(12)s(11)s(10)s(9)s(8)s(7)s(6)s(5)s(4)s(3)s(2)sss
@expansion{} product criterion:0 chain criterion:0
@expansion{} (S:3)rtrtrt
@expansion{} @{1@}[1023:3]4(2)s(4)s(5)s5s.s(3)s(2)sss
@expansion{} product criterion:0 chain criterion:39
@expansion{} @{1@}[1023:3]4(5)s(4)s(3)s(2)sss
@expansion{} product criterion:0 chain criterion:9
@expansion{} [255:3]3(11)s(10)sss(9)s(10)s(8)ss(7)s(8)s(6)s(7)s4(5)-----
@expansion{} product criterion:12 chain criterion:9
@expansion{} @{1@}[1023:3]4(2)sss
@expansion{} product criterion:0 chain criterion:12
@expansion{} [255:3]2(8)s(7)s(6)s3(5)ssssss4-----
@expansion{} product criterion:15 chain criterion:3
id4;
@expansion{} id4[1]=z2
@expansion{} id4[2]=yz
@expansion{} id4[3]=xz
@expansion{} id4[4]=y2
@expansion{} id4[5]=xy
@expansion{} id4[6]=x2
ideal id5=quot(id1,id2,2);
@expansion{} [1023:2]4(14)s(13)s(12)s(11)s(10)s(9)s(8)s(7)s(6)s(5)s(4)s(3)s(2)sss
@expansion{} product criterion:0 chain criterion:0
@expansion{} (S:3)rtrtrt
@expansion{} @{1@}[1023:3]4(2)sss
@expansion{} product criterion:0 chain criterion:12
@expansion{} @{1@}[1023:3]4(5)s(4)s(3)s(2)sss
@expansion{} product criterion:0 chain criterion:9
@expansion{} [255:3]2(8)s(7)s(6)s3(5)s(4)s(3)s(2)sss
@expansion{} product criterion:15 chain criterion:0
id5;
@expansion{} id5[1]=z2
@expansion{} id5[2]=yz
@expansion{} id5[3]=xz
@expansion{} id5[4]=y2
@expansion{} id5[5]=xy
@expansion{} id5[6]=x2
@c end example quot d2t_singular/standard_lib.doc:202
@end smallexample
@c inserted refs from d2t_singular/standard_lib.doc:215
@ifinfo
@menu
See also:
* quotient::
@end menu
@end ifinfo
@iftex
@strong{See also:}
@ref{quotient}.
@end iftex
@c end inserted refs from d2t_singular/standard_lib.doc:215

@c ---end content quot---
@c generated lib proc docu for standard.lib:quot reference.doc:4839
@c end include of docu for standard.lib:quot

@c ---------------------------------------
@node quote, quotient, quot, 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 reused example quote reference.doc:4860
  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);
@expansion{} [1023:1]1(12)s2(11)s3(10)--s(7)s(6)-----7-
@expansion{} product criterion:4 chain criterion:0
@expansion{} _[1]=z
@expansion{} _[2]=x2
@expansion{} _[3]=xy2
@expansion{} _[4]=y3
  close(l);
@c end example quote reference.doc:4860
@end smallexample
@end table
@c inserted refs from reference.doc:4875
@ifinfo
@menu
See
* MPfile links::
* eval::
* write::
@end menu
@end ifinfo
@iftex
See
@ref{MPfile links};
@ref{eval};
@ref{write}.
@end iftex
@c end inserted refs from reference.doc:4875
@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 reused example quotient reference.doc:4925
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;
@expansion{} id6[1]=z
@expansion{} id6[2]=y
@expansion{} id6[3]=x
quotient(id2,id1);
@expansion{} _[1]=z2
@expansion{} _[2]=yz
@expansion{} _[3]=y2
@expansion{} _[4]=xz
@expansion{} _[5]=xy
@expansion{} _[6]=x2
module m=x*freemodule(3),y*freemodule(2);
ideal id3=x,y;
quotient(m,id3);
@expansion{} _[1]=[1]
@expansion{} _[2]=[0,1]
@expansion{} _[3]=[0,0,x]
@c end example quotient reference.doc:4925
@end smallexample
@end table
@c inserted refs from reference.doc:4938
@ifinfo
@menu
See
* fglmquot::
* ideal::
* module::
@end menu
@end ifinfo
@iftex
See
@ref{fglmquot};
@ref{ideal};
@ref{module}.
@end iftex
@c end inserted refs from reference.doc:4938
@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 start value with
the function @code{system}, resp.@: by a command line option.
@item @strong{Example:}
@smallexample
@c reused example random reference.doc:4971
  random(1,1000);
@expansion{} 35
  random(1,2,3);
@expansion{} 0,0,0,
@expansion{} 1,1,-1
  system("random",210);  // start random generator with 210
  random(-1000,1000);
@expansion{} 707
  random(-1000,1000);
@expansion{} 284
  system("random",210);
  random(-1000,1000);    // the same random values again
@expansion{} 707
@c end example random reference.doc:4971
@end smallexample
@end table
@c inserted refs from reference.doc:4982
@ifinfo
@menu
See
* Command line options::
* int::
* intmat::
* system::
@end menu
@end ifinfo
@iftex
See
@ref{Command line options};
@ref{int};
@ref{intmat};
@ref{system}.
@end iftex
@c end inserted refs from reference.doc:4982
@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.
@*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.
@item @strong{Example:}
@smallexample
@c reused example read reference.doc:5017
  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;
@expansion{} k[1]=x+y
@expansion{} k[2]=z3+22y
@c end example read reference.doc:5017
@end smallexample
@end table
@c inserted refs from reference.doc:5031
@ifinfo
@menu
See
* execute::
* getdump::
* link::
* status::
* write::
@end menu
@end ifinfo
@iftex
See
@ref{execute};
@ref{getdump};
@ref{link};
@ref{status};
@ref{write}.
@end iftex
@c end inserted refs from reference.doc:5031
@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{,} ideal_expression@code{,} poly_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{,} module_expression@code{,} poly_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{,} ideal_expression@code{,} matrix_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{,} module_expression@code{,} matrix_expression @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 1 of type int forces a reduction which considers only the leading term and does no tail reduction.
@*If a third 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 second argument and gives, even in a local ring, a reduced normal form which is the projection to the quotient by the ideal (resp.@: module).
@item @strong{Note:}
The commands @code{reduce} and @code{NF} are synonymous.
@item @strong{Example:}
@smallexample
@c reused example reduce reference.doc:5076
  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);
@expansion{} -yx5+2401/81y14x2+2744/81y11x5+392/27y8x8+224/81y5x11+16/81y2x14
  reduce(3z3yx2+7y4x2+yx5+z12y2x2,j,1);
@expansion{} -yx5+z12y2x2
@c end example reduce reference.doc:5076
@end smallexample
@end table
@c inserted refs from reference.doc:5088
@ifinfo
@menu
See
* ideal::
* module::
* std::
* vector::
@end menu
@end ifinfo
@iftex
See
@ref{ideal};
@ref{module};
@ref{std};
@ref{vector}.
@end iftex
@c end inserted refs from reference.doc:5088
@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 list expression.
@*
@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 reused example regularity reference.doc:5134
  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);
@expansion{} 25
  // example for upper bound behavior:
  list jj=jr;
  regularity(jj);
@expansion{} 25
  jj=nres(j,0);
  regularity(jj);
@expansion{} 27
  jj=minres(jj);
  regularity(jj);
@expansion{} 25
@c end example regularity reference.doc:5134
@end smallexample
@end table
@c inserted refs from reference.doc:5150
@ifinfo
@menu
See
* list::
* minres::
* mres::
* option::
* res::
* resolution::
* sres::
@end menu
@end ifinfo
@iftex
See
@ref{list};
@ref{minres};
@ref{mres};
@ref{option};
@ref{res};
@ref{resolution};
@ref{sres}.
@end iftex
@c end inserted refs from reference.doc:5150
@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 reused example repart reference.doc:5175
  ring r=(complex,i),x,dp;
  repart(1+2*i);
@expansion{} 1
@c end example repart reference.doc:5175
@end smallexample
@end table
@c inserted refs from reference.doc:5181
@ifinfo
@menu
See
* impart::
@end menu
@end ifinfo
@iftex
See
@ref{impart}.
@end iftex
@c end inserted refs from reference.doc:5181
@c ---------------------------------------
@node  res, reservedName, repart, Functions
@subsection res
@cindex res
@c start include of docu for standard.lib:res
@c replaced @subsubsection by @sub
@c ---content res---
Procedure from library @code{standard.lib} (@pxref{standard_lib}).

@c we do texinfo here:
@cindex resolution, computation of
@table @code
@item @strong{Syntax:}
@code{res (} ideal_expression@code{,} int_expression @code{[,} any_expression @code{])}
@*@code{res (} module_expression@code{,} int_expression @code{[,} any_expression @code{])}
@item @strong{Type:}
resolution
@item @strong{Purpose:}
computes a (possibly minimal) free resolution of an ideal or module using
a heuristically chosen method.
@* The second (int) argument (say, @code{k}) specifies the length of
the resolution. If it is not positive then @code{k} is assumed to be the
number of variables of the basering.
@* If a third argument is given, the returned resolution is minimized.

Depending on the input, the returned resolution is computed using the
following methods:
@table @asis
@item @strong{quotient rings:}
@code{nres} (classical method using syzygies) , see @ref{nres}.

@item @strong{homogeneous ideals and k=0:}
@code{lres} (La'Scala's method), see @ref{lres}.

@item @strong{not minimized resolution and (homogeneous input with k not 0, or local rings):}
@code{sres} (Schreyer's method), see @ref{sres}.

@item @strong{all other inputs:}
@code{mres} (classical method), see @ref{mres}.
@end table
@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.
@end table
@c inserted refs from d2t_singular/standard_lib.doc:263
@ifinfo
@menu
See also
* betti::
* hres::
* ideal::
* lres::
* minres::
* module::
* mres::
* nres::
* resolution::
* sres::
@end menu
@end ifinfo
@iftex
See also
@ref{betti};
@ref{hres};
@ref{ideal};
@ref{lres};
@ref{minres};
@ref{module};
@ref{mres};
@ref{nres};
@ref{resolution};
@ref{sres}.
@end iftex
@c end inserted refs from d2t_singular/standard_lib.doc:263

@strong{Example:}
@smallexample
@c reused example res d2t_singular/standard_lib.doc:279
  ring r=0,(x,y,z),dp;
ideal i=xz,yz,x3-y3;
def l=res(i,0); // homogeneous ideal: uses lres
l;
@expansion{}  1      3      2
@expansion{} r <--  r <--  r
@expansion{}
@expansion{} 0      1      2
@expansion{} resolution not minimized yet
@expansion{}
print(betti(l), "betti"); // input to betti may be of type resolution
@expansion{}            0     1     2
@expansion{} ------------------------
@expansion{}     0:     1     -     -
@expansion{}     1:     -     2     1
@expansion{}     2:     -     1     1
@expansion{} ------------------------
@expansion{} total:     1     3     2
l[2];         // element access may take some time
@expansion{} _[1]=-x*gen(1)+y*gen(2)
@expansion{} _[2]=-x2*gen(2)+y2*gen(1)+z*gen(3)
i=i,x+1;
l=res(i,0);   // inhomogeneous ideal: uses mres
l;
@expansion{}  1      3      3      1
@expansion{} r <--  r <--  r <--  r
@expansion{}
@expansion{} 0      1      2      3
@expansion{} resolution not minimized yet
@expansion{}
ring rs=0,(x,y,z),ds;
ideal i=imap(r,i);
def l=res(i,0); // local ring not minimized: uses sres
l;
@expansion{}   1       1
@expansion{} rs <--  rs
@expansion{}
@expansion{} 0       1
@expansion{} resolution not minimized yet
@expansion{}
res(i,0,0);     // local ring and minimized: uses mres
@expansion{}   1       1
@expansion{} rs <--  rs
@expansion{}
@expansion{} 0       1
@expansion{}
@c end example res d2t_singular/standard_lib.doc:279
@end smallexample
@c ---end content res---
@c generated lib proc docu for standard.lib:res reference.doc:5189
@c end include of docu for standard.lib:res

@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 reused example reservedName reference.doc:5211
  reservedName("ring");
@expansion{} 1
  reservedName("xyz");
@expansion{} 0
@c end example reservedName reference.doc:5211
@end smallexample
@end table
@c inserted refs from reference.doc:5217
@ifinfo
@menu
See
* names::
* string::
@end menu
@end ifinfo
@iftex
See
@ref{names};
@ref{string}.
@end iftex
@c end inserted refs from reference.doc:5217
@c ---------------------------------------
@node  resultant, rvar, 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 reused example resultant reference.doc:5236
  ring r=32003,(x,y,z),dp;
  poly f=3*(x+2)^3+y;
  poly g=x+y+z;
  resultant(f,g,x);
@expansion{} 3y3+9y2z+9yz2+3z3-18y2-36yz-18z2+35y+36z-24
@c end example resultant reference.doc:5236
@end smallexample
@end table
@c inserted refs from reference.doc:5244
@ifinfo
@menu
See
* poly::
* ring::
@end menu
@end ifinfo
@iftex
See
@ref{poly};
@ref{ring}.
@end iftex
@c end inserted refs from reference.doc:5244
@c ---------------------------------------
@node rvar, setring, resultant, 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 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 reused example rvar reference.doc:5267
  ring r=29,(x,y,z),lp;
  rvar(x);
@expansion{} 1
  rvar(r);
@expansion{} 0
  rvar(y);
@expansion{} 2
  rvar(var(3));
@expansion{} 3
  rvar("x");
@expansion{} 1
@c end example rvar reference.doc:5267
@end smallexample
@end table
@c inserted refs from reference.doc:5277
@ifinfo
@menu
See
* defined::
* ring::
* var::
* varstr::
@end menu
@end ifinfo
@iftex
See
@ref{defined};
@ref{ring};
@ref{var};
@ref{varstr}.
@end iftex
@c end inserted refs from reference.doc:5277
@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 reused example setring reference.doc:5297
  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);
@expansion{} r1
  listvar();
@expansion{} // r2                   [0]  ring
@expansion{} // r1                   [0]  *ring
@expansion{} // LIB                  [0]  string standard.lib
@c end example setring reference.doc:5297
@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 inserted refs from reference.doc:5315
@ifinfo
@menu
See
* keepring::
* qring::
* ring::
@end menu
@end ifinfo
@iftex
See
@ref{keepring};
@ref{qring};
@ref{ring}.
@end iftex
@c end inserted refs from reference.doc:5315
@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.
M,m,n,m1,m2,m3:

@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 reused example simplex reference.doc:5381
    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);
@expansion{} [1]:
@expansion{}    _[1,1]=17.025
@expansion{}    _[1,2]=-0.95
@expansion{}    _[1,3]=-0.05
@expansion{}    _[1,4]=1.95
@expansion{}    _[1,5]=-1.05
@expansion{}    _[2,1]=730.55
@expansion{}    _[2,2]=0.1
@expansion{}    _[2,3]=-0.1
@expansion{}    _[2,4]=-1.1
@expansion{}    _[2,5]=0.9
@expansion{}    _[3,1]=3.325
@expansion{}    _[3,2]=-0.35
@expansion{}    _[3,3]=-0.15
@expansion{}    _[3,4]=0.35
@expansion{}    _[3,5]=0.35
@expansion{}    _[4,1]=0.95
@expansion{}    _[4,2]=-0.1
@expansion{}    _[4,3]=0.1
@expansion{}    _[4,4]=0.1
@expansion{}    _[4,5]=0.1
@expansion{}    _[5,1]=4.725
@expansion{}    _[5,2]=-0.55
@expansion{}    _[5,3]=0.05
@expansion{}    _[5,4]=0.55
@expansion{}    _[5,5]=-0.45
@expansion{} [2]:
@expansion{}    0
@expansion{} [3]:
@expansion{}    5,2,4,3
@expansion{} [4]:
@expansion{}    1,6,8,7
@expansion{} [5]:
@expansion{}    4
@expansion{} [6]:
@expansion{}    4
@c end example simplex reference.doc:5381
@end smallexample
@end table
@c inserted refs from reference.doc:5408
@ifinfo
@menu
See
* simplexOut::
@end menu
@end ifinfo
@iftex
See
@ref{simplexOut}.
@end iftex
@c end inserted refs from reference.doc:5408
@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 reused example simplify reference.doc:5448
ring r=0,(x,y,z),(c,dp);
ideal i=0,2x,2x,4x,3x+y,5x2;
simplify(i,1);
@expansion{} _[1]=0
@expansion{} _[2]=x
@expansion{} _[3]=x
@expansion{} _[4]=x
@expansion{} _[5]=x+1/3y
@expansion{} _[6]=x2
simplify(i,2);
@expansion{} _[1]=2x
@expansion{} _[2]=2x
@expansion{} _[3]=4x
@expansion{} _[4]=3x+y
@expansion{} _[5]=5x2
simplify(i,4);
@expansion{} _[1]=0
@expansion{} _[2]=2x
@expansion{} _[3]=4x
@expansion{} _[4]=3x+y
@expansion{} _[5]=5x2
simplify(i,8);
@expansion{} _[1]=0
@expansion{} _[2]=2x
@expansion{} _[3]=3x+y
@expansion{} _[4]=5x2
simplify(i,16);
@expansion{} _[1]=0
@expansion{} _[2]=2x
@expansion{} _[3]=5x2
simplify(i,32);
@expansion{} _[1]=0
@expansion{} _[2]=2x
simplify(i,32+2+1);
@expansion{} _[1]=x
matrix A[2][3]=x,0,2x,y,0,2y;
simplify(A,2+8); // by automatic conversion to module
@expansion{} _[1]=[x,y]
@c end example simplify reference.doc:5448
@end smallexample
@end table
@c inserted refs from reference.doc:5463
@ifinfo
@menu
See
* ideal::
* module::
* poly::
* vector::
@end menu
@end ifinfo
@iftex
See
@ref{ideal};
@ref{module};
@ref{poly};
@ref{vector}.
@end iftex
@c end inserted refs from reference.doc:5463
@c ---------------------------------------
@node size, sortvec, 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 reused example size reference.doc:5506
  string s="hello";
  size(s);
@expansion{} 5
  intvec iv=1,2;
  size(iv);
@expansion{} 2
  ring r=0,(x,y,z),lp;
  poly f=x+y+z;
  size(f);
@expansion{} 3
  vector v=[x+y,0,0,1];
  size(v);
@expansion{} 3
  ideal i=f,y;
  size(i);
@expansion{} 2
  module m=v,[0,1],[0,0,1],2*v;
  size(m);
@expansion{} 4
  matrix mm[2][2];
  size(mm);
@expansion{} 4
  ring r1=(2,a),x,dp;
  minpoly=a4+a+1;
  size(r1);
@expansion{} 8
@c end example size reference.doc:5506
@end smallexample
@end table
@c inserted refs from reference.doc:5528
@ifinfo
@menu
See
* ideal::
* intmat::
* intvec::
* module::
* ncols::
* nrows::
* poly::
* string::
* vector::
@end menu
@end ifinfo
@iftex
See
@ref{ideal};
@ref{intmat};
@ref{intvec};
@ref{module};
@ref{ncols};
@ref{nrows};
@ref{poly};
@ref{string};
@ref{vector}.
@end iftex
@c end inserted refs from reference.doc:5528
@c ---------------------------------------
@node sortvec, sprintf, size, 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 reused example sortvec reference.doc:5565
  ring r=0,(x,y,z),dp;
  ideal I=y,z,x,x3,xz;
  sortvec(I);
@expansion{} 2,1,3,5,4
@c end example sortvec reference.doc:5565
@end smallexample
@end table
@c inserted refs from reference.doc:5572
@ifinfo
@menu
See
* general_lib::
@end menu
@end ifinfo
@iftex
See
@ref{general_lib}.
@end iftex
@c end inserted refs from reference.doc:5572
@c ---------------------------------------
@node sprintf, sres, sortvec, Functions
@subsection sprintf
@cindex sprintf
@c start include of docu for standard.lib:sprintf
@c replaced @subsubsection by @sub
@c ---content sprintf---
Procedure from library @code{standard.lib} (@pxref{standard_lib}).

@table @asis
@item @strong{Syntax:}
@code{sprintf (} string_expression @code{[,} any_expressions
@code{] )}

@item @strong{Return:}
string

@item @strong{Purpose:}
@code{sprintf(fmt,...);} performs output formatting. The first
argument is a format control string. Additional arguments may be
required, depending on the content of the control string. A series
of output characters is generated as directed by the control string;
these characters are returned as a string. @*
The control string @code{fmt} is simply text to be copied,
except that the string may contain conversion specifications.@*
Do @code{help print;} for a listing of valid conversion
specifications. As an addition to the conversions of @code{print},
the @code{%n} and @code{%2} conversion specification does not
consume an additional argument, but simply generates a newline
character.

@item @strong{Note:}
If one of the additional arguments is a list, then it should be
enclosed once more into a @code{list()} command, since passing a list
as an argument flattens the list by one level.

@end table
@strong{Example:}
@smallexample
@c reused example sprintf d2t_singular/standard_lib.doc:335
  ring r=0,(x,y,z),dp;
module m=[1,y],[0,x+z];
intmat M=betti(mres(m,0));
list l = r, m, M;
string s = sprintf("s:%s,%n l:%l", 1, 2); s;
@expansion{} s:1,
@expansion{}  l:int(2)
s = sprintf("s:%n%s", l); s;
@expansion{} s:
@expansion{} (0),(x,y,z),(dp(3),C)
s = sprintf("s:%2%s", list(l)); s;
@expansion{} s:
@expansion{} (0),(x,y,z),(dp(3),C),y*gen(2)+gen(1),x*gen(2)+z*gen(2),1,1
s = sprintf("2l:%n%2l", list(l)); s;
@expansion{} 2l:
@expansion{} list("(0),(x,y,z),(dp(3),C)",
@expansion{} module(y*gen(2)+gen(1),
@expansion{} x*gen(2)+z*gen(2)),
@expansion{} intmat(intvec(1,1 ),1,2))
@expansion{}
s = sprintf("%p", list(l)); s;
@expansion{} [1]:
@expansion{}    //   characteristic : 0
@expansion{} //   number of vars : 3
@expansion{} //        block   1 : ordering dp
@expansion{} //                  : names    x y z
@expansion{} //        block   2 : ordering C
@expansion{} [2]:
@expansion{}    _[1]=y*gen(2)+gen(1)
@expansion{}    _[2]=x*gen(2)+z*gen(2)
@expansion{} [3]:
@expansion{}    1,1
@expansion{}
s = sprintf("%;", list(l)); s;
@expansion{} [1]:
@expansion{}    //   characteristic : 0
@expansion{} //   number of vars : 3
@expansion{} //        block   1 : ordering dp
@expansion{} //                  : names    x y z
@expansion{} //        block   2 : ordering C
@expansion{} [2]:
@expansion{}    _[1]=y*gen(2)+gen(1)
@expansion{}    _[2]=x*gen(2)+z*gen(2)
@expansion{} [3]:
@expansion{}    1,1
@expansion{}
s = sprintf("%b", M); s;
@expansion{}            0     1
@expansion{} ------------------
@expansion{}     0:     1     1
@expansion{} ------------------
@expansion{} total:     1     1
@expansion{}
@c end example sprintf d2t_singular/standard_lib.doc:335
@end smallexample
@c inserted refs from d2t_singular/standard_lib.doc:349
@ifinfo
@menu
See also:
* fprintf::
* print::
* printf::
* string::
@end menu
@end ifinfo
@iftex
@strong{See also:}
@ref{fprintf};
@ref{print};
@ref{printf};
@ref{string}.
@end iftex
@c end inserted refs from d2t_singular/standard_lib.doc:349

@c ---end content sprintf---
@c generated lib proc docu for standard.lib:sprintf reference.doc:5580
@c end include of docu for standard.lib:sprintf

@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 reused example sres reference.doc:5645
  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;
@expansion{}  1      35      141      209      141      43      4
@expansion{} r <--  r <--   r <--    r <--    r <--    r <--   r
@expansion{}
@expansion{} 0      1       2        3        4        5       6
@expansion{} resolution not minimized yet
@expansion{}
  print(betti(L),"betti");
@expansion{}            0     1     2     3     4     5
@expansion{} ------------------------------------------
@expansion{}     0:     1     -     -     -     -     -
@expansion{}     1:     -     -     -     -     -     -
@expansion{}     2:     -     -     -     -     -     -
@expansion{}     3:     -     4     -     -     -     -
@expansion{}     4:     -     -     -     -     -     -
@expansion{}     5:     -     -     -     -     -     -
@expansion{}     6:     -     -     6     -     -     -
@expansion{}     7:     -     -     9    16     2     -
@expansion{}     8:     -     -     -     2     5     1
@expansion{} ------------------------------------------
@expansion{} total:     1     4    15    18     7     1
@c end example sres reference.doc:5645
@end smallexample
@end table
@c inserted refs from reference.doc:5656
@ifinfo
@menu
See
* betti::
* hres::
* ideal::
* int::
* lres::
* minres::
* module::
* mres::
* res::
* syz::
@end menu
@end ifinfo
@iftex
See
@ref{betti};
@ref{hres};
@ref{ideal};
@ref{int};
@ref{lres};
@ref{minres};
@ref{module};
@ref{mres};
@ref{res};
@ref{syz}.
@end iftex
@c end inserted refs from reference.doc:5656
@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"}
@end table
@item @strong{Example:}
@smallexample
@c reused example status reference.doc:5720
  link l=":w example.txt";
  status(l,"write");
@expansion{} not ready
  open(l);
  status(l,"write","ready");
@expansion{} 1
  close(l);
@c end example status reference.doc:5720
@end smallexample
@end table
@c inserted refs from reference.doc:5729
@ifinfo
@menu
See
* link::
* open::
* read::
* write::
@end menu
@end ifinfo
@iftex
See
@ref{link};
@ref{open};
@ref{read};
@ref{write}.
@end iftex
@c end inserted refs from reference.doc:5729
@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{)}
@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, resp.@: vector,
to construct the standard basis from an already computed one (given as the
first argument) and one additional generator (the second argument).
@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 reused example std reference.doc:5779
  // 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);
@expansion{} 0
  // 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];
@expansion{} z64
  // 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];
@expansion{} z64
@c end example std reference.doc:5779
@end smallexample
@end table
@c inserted refs from reference.doc:5811
@ifinfo
@menu
See
* facstd::
* fglm::
* groebner::
* ideal::
* mstd::
* option::
* ring::
* stdfglm::
* stdhilb::
@end menu
@end ifinfo
@iftex
See
@ref{facstd};
@ref{fglm};
@ref{groebner};
@ref{ideal};
@ref{mstd};
@ref{option};
@ref{ring};
@ref{stdfglm};
@ref{stdhilb}.
@end iftex
@c end inserted refs from reference.doc:5811

@c ---------------------------------------
@node stdfglm, stdhilb, std, Functions
@subsection stdfglm
@cindex stdfglm
@c start include of docu for standard.lib:stdfglm
@c replaced @subsubsection by @sub
@c ---content stdfglm---
Procedure from library @code{standard.lib} (@pxref{standard_lib}).

@table @asis
@item @strong{Syntax:}
@code{stdfglm (} ideal_expression @code{)} @*
@code{stdfglm (} ideal_expression@code{,} string_expression @code{)}

@item @strong{Type:}
ideal

@item @strong{Purpose:}
computes the standard basis of the ideal in the basering
via @code{fglm} (from the ordering given as the second argument
to the ordering of the basering).@*
If no second argument is given, "dp" is used.

@cindex fglm
@end table
@strong{Example:}
@smallexample
@c reused example stdfglm d2t_singular/standard_lib.doc:52
   ring r=0,(x,y,z),lp;
ideal i=y3+x2,x2y+x2,x3-x2,z4-x2-y;
ideal i1=stdfglm(i);         //uses fglm from "dp" to "lp"
i1;
@expansion{} i1[1]=z12
@expansion{} i1[2]=yz4-z8
@expansion{} i1[3]=y2+y-z8-z4
@expansion{} i1[4]=xy-xz4-y+z4
@expansion{} i1[5]=x2+y-z4
ideal i2=stdfglm(i,"Dp");    //uses fglm from "Dp" to "lp"
i2;
@expansion{} i2[1]=z12
@expansion{} i2[2]=yz4-z8
@expansion{} i2[3]=y2+y-z8-z4
@expansion{} i2[4]=xy-xz4-y+z4
@expansion{} i2[5]=x2+y-z4
@c end example stdfglm d2t_singular/standard_lib.doc:52
@end smallexample
@c inserted refs from d2t_singular/standard_lib.doc:61
@ifinfo
@menu
See also:
* fglm::
* groebner::
* std::
* stdhilb::
@end menu
@end ifinfo
@iftex
@strong{See also:}
@ref{fglm};
@ref{groebner};
@ref{std};
@ref{stdhilb}.
@end iftex
@c end inserted refs from d2t_singular/standard_lib.doc:61

@c ---end content stdfglm---
@c generated lib proc docu for standard.lib:stdfglm reference.doc:5828
@c end include of docu for standard.lib:stdfglm

@c ---------------------------------------
@node stdhilb, subst, stdfglm, Functions
@subsection stdhilb
@cindex stdhilb
@c start include of docu for standard.lib:stdhilb
@c replaced @subsubsection by @sub
@c ---content stdhilb---
Procedure from library @code{standard.lib} (@pxref{standard_lib}).

@table @asis
@item @strong{Syntax:}
@code{stdhilb (} ideal_expression @code{)} @*
@code{stdhilb (} ideal_expression@code{,} intvec_expression @code{)}

@item @strong{Type:}
ideal

@item @strong{Purpose:}
computes the standard basis of the homogeneous ideal in the basering,
via a Hilbert driven standard basis computation.@*
An optional second argument will be used as 1st Hilbert function.

@item @strong{Assume:}
The optional second argument is the first Hilbert series as computed
by @code{hilb}.

@cindex Hilbert function
@end table
@strong{Example:}
@smallexample
@c reused example stdhilb d2t_singular/standard_lib.doc:95
   ring  r=0,(x,y,z),dp;
ideal i=y3+x2,x2y+x2,x3-x2,z4-x2-y;
ideal i1=stdhilb(i); i1;
@expansion{} i1[1]=y3+x2
@expansion{} i1[2]=x2y+x2
@expansion{} i1[3]=x3-x2
@expansion{} i1[4]=z4-x2-y
// the latter computation is equivalent to:
intvec v=hilb(i,1);
@expansion{} // ** i is no standardbasis
ideal i2=stdhilb(i,v); i2;
@expansion{} i2[1]=y3+x2
@expansion{} i2[2]=x2y+x2
@expansion{} i2[3]=x3-x2
@expansion{} i2[4]=z4-x2-y
@c end example stdhilb d2t_singular/standard_lib.doc:95
@end smallexample
@c inserted refs from d2t_singular/standard_lib.doc:104
@ifinfo
@menu
See also:
* groebner::
* std::
* stdfglm::
@end menu
@end ifinfo
@iftex
@strong{See also:}
@ref{groebner};
@ref{std};
@ref{stdfglm}.
@end iftex
@c end inserted refs from d2t_singular/standard_lib.doc:104

@c ---end content stdhilb---
@c generated lib proc docu for standard.lib:stdhilb reference.doc:5834
@c end include of docu for standard.lib:stdhilb

@c ---------------------------------------
@node subst, system, stdhilb, Functions
@subsection subst
@cindex subst
@table @code
@item @strong{Syntax:}
@code{subst (} poly_expression@code{,} ring_variable@code{,} poly_expression @code{)}
@*@code{subst (} vector_expression@code{,} ring_variable@code{,} poly_expression @code{)}
@*@code{subst (} ideal_expression@code{,} ring_variable@code{,} poly_expression @code{)}
@*@code{subst (} module_expression@code{,} ring_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 by a polynomial.
@item @strong{Example:}
@smallexample
@c reused example subst reference.doc:5852
  ring r=0,(x,y,z),dp;
  poly f=x2+y2+z2+x+y+z;
  subst(f,x,3/2);
@expansion{} y2+z2+y+z+15/4
  int a=1;
  subst(f,y,a);
@expansion{} x2+z2+x+z+2
  subst(f,y,z);
@expansion{} x2+2z2+x+2z
  subst(f,y,z+1);
@expansion{} x2+2z2+x+4z+2
@c end example subst reference.doc:5852
@end smallexample
@end table
@c inserted refs from reference.doc:5863
@ifinfo
@menu
See
* ideal::
* map::
* module::
* poly::
* vector::
@end menu
@end ifinfo
@iftex
See
@ref{ideal};
@ref{map};
@ref{module};
@ref{poly};
@ref{vector}.
@end iftex
@c end inserted refs from reference.doc:5863
@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("}--@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
// report value of all options
system("--");
@expansion{} // --batch           0
@expansion{} // --execute
@expansion{} // --sdb             0
@expansion{} // --echo            0
@expansion{} // --help            0
@expansion{} // --quiet           0
@expansion{} // --random          937848971
@expansion{} // --no-tty          0
@expansion{} // --user-option
@expansion{} // --version         0
@expansion{} // --allow-net       0
@expansion{} // --browser
@expansion{} // --emacs           0
@expansion{} // --no-stdlib       0
@expansion{} // --no-rc           0
@expansion{} // --no-warn         0
@expansion{} // --no-out          0
@expansion{} // --min-time        "0.5"
@expansion{} // --mp-port
@expansion{} // --mp-host
@expansion{} // --ticks-per-sec   1
@expansion{} // --mp-transp
@expansion{} // --mp-mode
// 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");
@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 reused example syz reference.doc:6043
  ring R=0,(x,y),(c,dp);
  ideal i=x,y;
  syz(i);
@expansion{} _[1]=[y,-x]
@c end example syz reference.doc:6043
@end smallexample
@end table
@c inserted refs from reference.doc:6050
@ifinfo
@menu
See
* hres::
* ideal::
* lres::
* module::
* mres::
* nres::
* res::
* sres::
@end menu
@end ifinfo
@iftex
See
@ref{hres};
@ref{ideal};
@ref{lres};
@ref{module};
@ref{mres};
@ref{nres};
@ref{res};
@ref{sres}.
@end iftex
@c end inserted refs from reference.doc:6050
@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 reused example trace reference.doc:6076
  intmat m[2][2]=1,2,3,4;
  print(m);
@expansion{}      1     2
@expansion{}      3     4
  trace(m);
@expansion{} 5
@c end example trace reference.doc:6076
@end smallexample
@end table
@c inserted refs from reference.doc:6083
@ifinfo
@menu
See
* intmat::
* matrix::
@end menu
@end ifinfo
@iftex
See
@ref{intmat};
@ref{matrix}.
@end iftex
@c end inserted refs from reference.doc:6083
@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 reused example transpose reference.doc:6103
  ring R=0,x,dp;
  matrix m[2][3]=1,2,3,4,5,6;
  print(m);
@expansion{} 1,2,3,
@expansion{} 4,5,6
  print(transpose(m));
@expansion{} 1,4,
@expansion{} 2,5,
@expansion{} 3,6
@c end example transpose reference.doc:6103
@end smallexample
@end table
@c inserted refs from reference.doc:6111
@ifinfo
@menu
See
* intmat::
* matrix::
* module::
@end menu
@end ifinfo
@iftex
See
@ref{intmat};
@ref{matrix};
@ref{module}.
@end iftex
@c end inserted refs from reference.doc:6111
@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 reused example type reference.doc:6133
  int i=3;
  i;
@expansion{} 3
  type(i);
@expansion{} // i                    [0]  int 3
@c end example type reference.doc:6133
@end smallexample
@end table
@c inserted refs from reference.doc:6140
@ifinfo
@menu
See
* Data types::
* listvar::
* print::
@end menu
@end ifinfo
@iftex
See
@ref{Data types};
@ref{listvar};
@ref{print}.
@end iftex
@c end inserted refs from reference.doc:6140
@c ---------------------------------------
@node typeof, uressolve, 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 reused example typeof reference.doc:6185
  int i=9; i;
@expansion{} 9
  typeof(_);
@expansion{} int
  print(i);
@expansion{} 9
  typeof(_);
@expansion{} none
  type i;
@expansion{} // i                    [0]  int 9
  typeof(_);
@expansion{} string
  string s=typeof(i);
  s;
@expansion{} int
  typeof(s);
@expansion{} string
  proc p() @{  "hello"; return();@}
  p();
@expansion{} hello
  typeof(_);
@expansion{} none
@c end example typeof reference.doc:6185
@end smallexample
@end table
@c inserted refs from reference.doc:6201
@ifinfo
@menu
See
* Data types::
* type::
@end menu
@end ifinfo
@iftex
See
@ref{Data types};
@ref{type}.
@end iftex
@c end inserted refs from reference.doc:6201
@c ---------------------------------------
@node uressolve, vandermonde, typeof, 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.
@item @strong{Example:}
@smallexample
@c reused example uressolve reference.doc:6234
ring rsc=(real,20,I),(x,y),lp;
ideal i=(2+3*I)*x2+(0.35+I*45.0e-2)*y2-8,x2+xy+(42.7)*y2;
list l=uressolve(i,0,0,2);
l[1];
@expansion{} [1]:
@expansion{}    (-1.315392899374542198+I*0.70468233142752928117)
@expansion{} [2]:
@expansion{}    (0.12292646536251281054+I*0.19245727404407015049)
subst(subst(i[1],x,l[1][1]),y,l[1][2]);
@expansion{} 0
@c end example uressolve reference.doc:6234
@end smallexample
@end table
@c inserted refs from reference.doc:6243
@ifinfo
@menu
See
* laguerre::
* mpresmat::
@end menu
@end ifinfo
@iftex
See
@ref{laguerre};
@ref{mpresmat}.
@end iftex
@c end inserted refs from reference.doc:6243
@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
@code{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 reused example vandermonde reference.doc:6304
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:
@expansion{} -1/9797760x2y2-595/85536x2y+55/396576xy2+935/384x2-1309/3240xy
// compute value of ip at the point 2^8,3^8, result must be 9
subst(subst(ip,x,2^8),y,3^8);
@expansion{} 9
@c end example vandermonde reference.doc:6304
@end smallexample
@end table
@c inserted refs from reference.doc:6318
@ifinfo
@menu
See also:
@end menu
@end ifinfo
@iftex

@end iftex
@c end inserted refs from reference.doc:6318
@c ---------------------------------------
@node var, varstr, 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 reused example var reference.doc:6333
  ring r=0,(x,y,z),dp;
  var(2);
@expansion{} y
@c end example var reference.doc:6333
@end smallexample
@end table
@c inserted refs from reference.doc:6339
@ifinfo
@menu
See
* int::
* nvars::
* ring::
* varstr::
@end menu
@end ifinfo
@iftex
See
@ref{int};
@ref{nvars};
@ref{ring};
@ref{varstr}.
@end iftex
@c end inserted refs from reference.doc:6339
@c ---------------------------------------
@node varstr, vdim, var, 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 reused example varstr reference.doc:6365
  ring r=0,(x,y,z),dp;
  varstr(r);
@expansion{} x,y,z
  varstr(r,1);
@expansion{} x
  varstr(2);
@expansion{} y
@c end example varstr reference.doc:6365
@end smallexample
@end table
@c inserted refs from reference.doc:6373
@ifinfo
@menu
See
* charstr::
* int::
* nvars::
* ordstr::
* parstr::
* ring::
* var::
@end menu
@end ifinfo
@iftex
See
@ref{charstr};
@ref{int};
@ref{nvars};
@ref{ordstr};
@ref{parstr};
@ref{ring};
@ref{var}.
@end iftex
@c end inserted refs from reference.doc:6373
@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 reused example vdim reference.doc:6403
  ring r=0,(x,y),ds;
  ideal i=x2+y2,x2-y2;
  ideal j=std(i);
  vdim(j);
@expansion{} 4
@c end example vdim reference.doc:6403
@end smallexample
@end table
@c inserted refs from reference.doc:6411
@ifinfo
@menu
See
* degree::
* dim::
* ideal::
* kbase::
* mult::
* std::
@end menu
@end ifinfo
@iftex
See
@ref{degree};
@ref{dim};
@ref{ideal};
@ref{kbase};
@ref{mult};
@ref{std}.
@end iftex
@c end inserted refs from reference.doc:6411
@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 reused example wedge reference.doc:6434
  ring r;
  matrix m[2][3]=x,y,y,z,z,x;
  print(m);
@expansion{} x,y,y,
@expansion{} z,z,x
  print(wedge(m,2));
@expansion{} xz-yz,-x2+yz,xy-yz
@c end example wedge reference.doc:6434
@end smallexample
@end table
@c inserted refs from reference.doc:6442
@ifinfo
@menu
See
* int::
* matrix::
* minor::
@end menu
@end ifinfo
@iftex
See
@ref{int};
@ref{matrix};
@ref{minor}.
@end iftex
@c end inserted refs from reference.doc:6442
@c ---------------------------------------
@node weight, write, 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 reused example weight reference.doc:6465
  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;
@expansion{} 5,7,5,7
  ring r=32003,(a,b,c,d),wp(e);
  map f=h1,a,b,c,d;
  ideal i0=std(f(i));
@c end example weight reference.doc:6465
@end smallexample
@end table
@c inserted refs from reference.doc:6479
@ifinfo
@menu
See
* ideal::
* intvec::
* qhweight::
@end menu
@end ifinfo
@iftex
See
@ref{ideal};
@ref{intvec};
@ref{qhweight}.
@end iftex
@c end inserted refs from reference.doc:6479
@c ---------------------------------------
@node  write,  , weight, 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 inserted refs from reference.doc:6545
@ifinfo
@menu
See
* Data types::
* dump::
* eval::
* link::
* print::
* printf::
* quote::
* read::
* short::
@end menu
@end ifinfo
@iftex
See
@ref{Data types};
@ref{dump};
@ref{eval};
@ref{link};
@ref{print};
@ref{printf};
@ref{quote};
@ref{read};
@ref{short}.
@end iftex
@c end inserted refs from reference.doc:6545

@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::
* for::
* if::
* keepring::
* quit::
* return::
* while::
* ~::
@ifset namespaces
* exportto::
* importfrom::
* load::
* unload::
@end ifset
@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 inserted refs from reference.doc:6634
@ifinfo
@menu
See
* Control structures::
* for::
* while::
@end menu
@end ifinfo
@iftex
See
@ref{Control structures};
@ref{for};
@ref{while}.
@end iftex
@c end inserted refs from reference.doc:6634
@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 reused example breakpoint reference.doc:6656
breakpoint(groebner);
@expansion{} breakpoint 1, at line 163 in groebner
breakpoint(groebner, 176);
@expansion{} breakpoint 2, at line 176 in groebner
breakpoint(groebner, -1);
@expansion{} breakpoints in groebner deleted(0x6)
@c end example breakpoint reference.doc:6656
@end smallexample
@end table
@c inserted refs from reference.doc:6663
@ifinfo
@menu
See
* Source code debugger::
* ~::
@end menu
@end ifinfo
@iftex
See
@ref{Source code debugger};
@ref{~}.
@end iftex
@c end inserted refs from reference.doc:6663
@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 inserted refs from reference.doc:6699
@ifinfo
@menu
See
* Control structures::
* for::
* while::
@end menu
@end ifinfo
@iftex
See
@ref{Control structures};
@ref{for};
@ref{while}.
@end iftex
@c end inserted refs from reference.doc:6699
@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 inserted refs from reference.doc:6729
@ifinfo
@menu
See
* Control structures::
* boolean expressions::
* if::
@end menu
@end ifinfo
@iftex
See
@ref{Control structures};
@ref{boolean expressions};
@ref{if}.
@end iftex
@c end inserted refs from reference.doc:6729
@c ---------------------------------------
@ifset namespaces
@node export, exportto, else, Control structures
@end ifset
@ifclear namespaces
@node export, for, else, Control structures
@end ifclear
@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.
@item @strong{Note:}
Objects defined in a ring are not automatically exported
when exporting the ring (use @code{keepring} instead).
@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

@ifset namespaces
@c inserted refs from reference.doc:6774
@ifinfo
@menu
See
* exportto::
* keepring::
@end menu
@end ifinfo
@iftex
See
@ref{exportto};
@ref{keepring}.
@end iftex
@c end inserted refs from reference.doc:6774
@end ifset
@ifclear namespaces
@c inserted refs from reference.doc:6780
@ifinfo
@menu
See
* keepring::
@end menu
@end ifinfo
@iftex
See
@ref{keepring}.
@end iftex
@c end inserted refs from reference.doc:6780
@end ifclear
@c ---------------------------------------
@ifset namespaces
@c ---------------------------------------
@node exportto, importfrom, 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:}
converts a local variable of a procedure to a global one.
package_name can be @code{Current}, @code{Up}, @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 (use @code{keepring} instead).
@item @strong{Example:}
@smallexample
proc p1
@{
  int i,j;
  exportto(Current,i);
  intmat m;
  listvar();
  exportto(Top,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 inserted refs from reference.doc:6822
@ifinfo
@menu
See
* keepring::
@end menu
@end ifinfo
@iftex
See
@ref{keepring}.
@end iftex
@c end inserted refs from reference.doc:6822
@c ---------------------------------------
@node importfrom, load, exportto, Control structures
@subsection importfrom
@cindex importfrom
@table @code
@item @strong{Syntax:}
@code{importfrom(}@code{);}
@end table

@c inserted refs from reference.doc:6834
@ifinfo
@menu
See
* exportto::
@end menu
@end ifinfo
@iftex
See
@ref{exportto}.
@end iftex
@c end inserted refs from reference.doc:6834
@c ---------------------------------------
@node load, unload, importfrom, Control structures
@subsection load
@cindex load
@table @code
@item @strong{Syntax:}
@code{load(} string_expression @code{);}
@*@code{load(}string_expression@code{,"with");}
@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. If the given filename does
not start with @kbd{.} or @kbd{/}, the following directories are
searched for (in that 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");"}.

Unless  @sc{Singular} is started with the @code{--no-stdlib} option, the
library @code{standard.lib} is automatically loaded at start-up time.
@end table

All loaded libraries are displayed by the @code{listvar(package);}
command:
@smallexample
@c reused example load reference.doc:6874
  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
@expansion{} // ** loaded inout.lib (1.21.2.5,2002/06/12)
  listvar(package);
@c end example load reference.doc:6874
@end smallexample

Each time a library @ref{Singular library} / dynamic module @ref{dynamic
module} is loaded, the corresponding namespace is created, if it does
not already exist.

The name of this namespace 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.

@sc{Singular} also supports autoloading of packages.
To use this features, just specify the identifier by its full name:

@smallexample
@c reused example load_1 reference.doc:6898
  listvar(package);
  Inout::version;     // full name of a variable in the package Inout
@expansion{}    ? package is not supported in this version
@expansion{}    ? error occurred in line 2: `  Inout::version;     // full name of a v\
   ariable in the package Inout`
  listvar(package);   // the package Inout has been autoloaded
@c end example load_1 reference.doc:6898
@end smallexample

For autoloading the base of the filename is generated by converting the
packagename to lowercase letters. The search is done in the standard
@sc{Singular} search path, first looking for a file of this name, and then
appending to the base @code{.lib}, @code{.so}, @code{.sl} (in this order).

An identifier of type @code{package} is created and all procedures are
stored in that package.
Before loading the type of the file is checking. For an Singular
library, the package is set as filename until the first '.' in the name
with an uppercase first letter. If the library to load is an binary file
with procedures written in an higher language (e.g. C, C++, ...) the
package name s hard-code in the library.

The second argument @code{"with"} will automatically export all none
static procedures to the toplevel.

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.  More exactly, option @code{-q} (and
likewise @code{--quiet}) unsets option @code{loadLib} to inhibit
monitoring of library loading (@pxref{option}).

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

@smallexample
@c reused example load_2 reference.doc:6936
  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
@expansion{} // ** loaded inout.lib (1.21.2.5,2002/06/12)
  listvar();
@expansion{} // LIB                  [0]  string standard.lib,inout.l..., 22 char(s)
@c end example load_2 reference.doc:6936
@end smallexample
@c inserted refs from reference.doc:6943
@ifinfo
@menu
See
* Command line options::
* LIB::
* Namespaces::
* Procedures and libraries::
* SINGULAR libraries::
* dynamic module::
* exportto::
* importfrom::
* package::
* proc::
* standard_lib::
* string::
* system::
@end menu
@end ifinfo
@iftex
See
@ref{Command line options};
@ref{LIB};
@ref{Namespaces};
@ref{Procedures and libraries};
@ref{SINGULAR libraries};
@ref{dynamic module};
@ref{exportto};
@ref{importfrom};
@ref{package};
@ref{proc};
@ref{standard_lib};
@ref{string};
@ref{system}.
@end iftex
@c end inserted refs from reference.doc:6943

@c ---------------------------------------
@node unload, for, load, Control structures
@subsection unload
@cindex unload
@table @code
@item @strong{Syntax:}
@code{unload(}@code{);}
@end table
@c ---------------------------------------
@end ifset
@c ---------------------------------------
@ifset namespaces
@node for, if, unload, Control structures
@end ifset
@ifclear namespaces
@node for, if, export, Control structures
@end ifclear
@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 inserted refs from reference.doc:7004
@ifinfo
@menu
See
* Control structures::
* boolean expressions::
* break::
* continue::
* if::
* while::
@end menu
@end ifinfo
@iftex
See
@ref{Control structures};
@ref{boolean expressions};
@ref{break};
@ref{continue};
@ref{if};
@ref{while}.
@end iftex
@c end inserted refs from reference.doc:7004
@c ---------------------------------------
@node if, keepring, 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 inserted refs from reference.doc:7036
@ifinfo
@menu
See
* Control structures::
* boolean expressions::
* break::
* else::
@end menu
@end ifinfo
@iftex
See
@ref{Control structures};
@ref{boolean expressions};
@ref{break};
@ref{else}.
@end iftex
@c end inserted refs from reference.doc:7036
@c ---------------------------------------
@node keepring, quit, if, Control structures
@subsection keepring
@cindex keepring
@table @code
@item @strong{Syntax:}
@code{keepring} name @code{;}
@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 inserted refs from reference.doc:7077
@ifinfo
@menu
See
* ring::
@end menu
@end ifinfo
@iftex
See
@ref{ring}.
@end iftex
@c end inserted refs from reference.doc:7077
@c ---------------------------------------
@node quit, return, keepring, Control structures
@subsection quit
@cindex quit
@cindex exit
@table @code
@item @strong{Syntax:}
@code{quit;}
@item @strong{Purpose:}
quits @sc{Singular};
works also from inside a procedure. The commands @code{quit} and
@code{exit} are synonymous.
@item @strong{Example:}
@smallexample
  quit;
@end smallexample
@end table
@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 inserted refs from reference.doc:7138
@ifinfo
@menu
See
* Data types::
* proc::
@end menu
@end ifinfo
@iftex
See
@ref{Data types};
@ref{proc}.
@end iftex
@c end inserted refs from reference.doc:7138
@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 inserted refs from reference.doc:7174
@ifinfo
@menu
See
* Control structures::
* boolean expressions::
* break::
@end menu
@end ifinfo
@iftex
See
@ref{Control structures};
@ref{boolean expressions};
@ref{break}.
@end iftex
@c end inserted refs from reference.doc:7174

@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 inserted refs from reference.doc:7215
@ifinfo
@menu
See
* Break points::
@end menu
@end ifinfo
@iftex
See
@ref{Break points}.
@end iftex
@c end inserted refs from reference.doc:7215

@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 ---------------------------------------
@c @node alternating, degBound, System variables, System variables
@c @subsection alternating
@c @cindex alternating
@c @table @code
@c @item @strong{Syntax:}
@c @code{alternating =} int_expression@code{;}
@c @*int_variable @code{= alternating;}
@c @item @strong{Purpose:}
@c describes the position of the first alternating variable in the current
@c basering, thus creating the tensor
@c product of a polynomial ring with an exterior algebra.
@c @*Remark: Setting @code{alternating=1;} defines the exterior algebra.
@c @item @strong{Note:}
@c These algebras are only available in those versions of
@c @sc{Singular} which are compiled with the SRING option.
@c The SRING version is
@c significantly slower for usual (commutative) ring operations.
@c @item @strong{Example:}
@c @example
@c   // define the exterior algebra in 3 variables x, y, z
@c   ring r=0,(x,y,z),dp;
@c   alternating=1;
@c   y*x;
@c   @expansion{} -1*xy
@c @end example
@c @end table
@c @c ref
@c See
@c @ref{ring};
@c @ref{int expressions}.
@c @c ref
@c @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.
@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 inserted refs from reference.doc:7297
@ifinfo
@menu
See
* deg::
* int::
* option::
* std::
@end menu
@end ifinfo
@iftex
See
@ref{deg};
@ref{int};
@ref{option};
@ref{std}.
@end iftex
@c end inserted refs from reference.doc:7297
@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 inserted refs from reference.doc:7323
@ifinfo
@menu
See
* int::
* voice::
@end menu
@end ifinfo
@iftex
See
@ref{int};
@ref{voice}.
@end iftex
@c end inserted refs from reference.doc:7323
@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 reused example minpoly reference.doc:7352
  //(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
@expansion{} -1
@c end example minpoly reference.doc:7352
@end smallexample
@end table
@c inserted refs from reference.doc:7360
@ifinfo
@menu
See
* factorize::
* ring::
@end menu
@end ifinfo
@iftex
See
@ref{factorize};
@ref{ring}.
@end iftex
@c end inserted refs from reference.doc:7360
@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
multBound = 20;
option();
@expansion{}    //options for 'std'-command: multBound
ideal j=std(i);
multBound;
@expansion{} 20
multBound = 0;  //disables multBound
@end smallexample
@end table
@c inserted refs from reference.doc:7388
@ifinfo
@menu
See
* int::
* mult::
* option::
* std::
@end menu
@end ifinfo
@iftex
See
@ref{int};
@ref{mult};
@ref{option};
@ref{std}.
@end iftex
@c end inserted refs from reference.doc:7388
@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 reused example noether reference.doc:7410
  ring R=32003,(x,y,z),ds;
  ideal i=x2+y12,y13;
  std(i);
@expansion{} _[1]=x2+y12
@expansion{} _[2]=y13
  noether=x11;
  std(i);
@expansion{} _[1]=x2
  noether=0; //disables noether
@c end example noether reference.doc:7410
@end smallexample
@end table
@c inserted refs from reference.doc:7420
@ifinfo
@menu
See
* poly::
* std::
@end menu
@end ifinfo
@iftex
See
@ref{poly};
@ref{std}.
@end iftex
@c end inserted refs from reference.doc:7420
@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 reused example printlevel reference.doc:7441
  voice;
@expansion{} 1
  printlevel=0;
  dbprint(1);
  printlevel=voice;
  dbprint(1);
@expansion{} 1
@c end example printlevel reference.doc:7441
@end smallexample
@end table
@c inserted refs from reference.doc:7450
@ifinfo
@menu
See
* dbprint::
* int::
* voice::
@end menu
@end ifinfo
@iftex
See
@ref{dbprint};
@ref{int};
@ref{voice}.
@end iftex
@c end inserted refs from reference.doc:7450
@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 reused example short reference.doc:7474
  ring r=23,x,dp;
  int save=short;
  short=1;
  2x2,x2;
@expansion{} 2x2 x2
  short=0;
  2x2,x2;
@expansion{} 2*x^2 x^2
  short=save;  //resets short to the previous value
@c end example short reference.doc:7474
@end smallexample
@end table
@c inserted refs from reference.doc:7485
@ifinfo
@menu
See
* int::
@end menu
@end ifinfo
@iftex
See
@ref{int}.
@end iftex
@c end inserted refs from reference.doc:7485
@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 reused example timer reference.doc:7527
  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)
@expansion{} 0
      // since t was initialized by timer
  int tps=system("--ticks-per-sec");
  t/tps; // yields the time in seconds truncated to int
@expansion{} 0
@c end example timer reference.doc:7527
@end smallexample
@end table
@c inserted refs from reference.doc:7541
@ifinfo
@menu
See
* Command line options::
* printlevel::
* rtimer::
* system::
* voice::
@end menu
@end ifinfo
@iftex
See
@ref{Command line options};
@ref{printlevel};
@ref{rtimer};
@ref{system};
@ref{voice}.
@end iftex
@c end inserted refs from reference.doc:7541
@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 reused example TRACE reference.doc:7575
  TRACE=1;
  LIB "general.lib";
  sum(1..100);
@expansion{} entering sum (level 0)
@expansion{} leaving  sum (level 0)
@expansion{} 5050
@c end example TRACE reference.doc:7575
@end smallexample
@end table
@c inserted refs from reference.doc:7582
@ifinfo
@menu
See
* int::
@end menu
@end ifinfo
@iftex
See
@ref{int}.
@end iftex
@c end inserted refs from reference.doc:7582
@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 an small example how this is used
for the display of comments while procedures are executed.
@item @strong{Example:}
@smallexample
@c reused example voice reference.doc:7614
  voice;
@expansion{} 1
@c end example voice reference.doc:7614
proc p
@{
  voice;
@};
p();
@expansion{} 2
@end smallexample
@end table
@c inserted refs from reference.doc:7625
@ifinfo
@menu
See
* dbprint::
* listvar::
* printlevel::
@end menu
@end ifinfo
@iftex
See
@ref{dbprint};
@ref{listvar};
@ref{printlevel}.
@end iftex
@c end inserted refs from reference.doc:7625
@c ---------------------------------------