<?xml version="1.0" encoding="ascii"?>
<!-- XML document for the CoCoA online help system -->
<!-- last modified 28 March 2014 -->
<!-- STRUCTURE:  -->
<!--  help         -->
<!--    version    -->
<!--    command    -->
<!--    command    -->
<!--     ...   (a separate entry for each CoCoA command -->
<!--    command    -->
                        <!--    part       -->
<!--    part       -->
<!--     ...   (a separate entry for each manual part -->
<!--    part       -->

<!-- TODO LIST -->
<!-- 1. Make TODO list. -->

<help>

<!--The 'version' appears in a few places in the manual. -->
<!--It would be nice to have to change only the version stuff here, -->
<!--i.e., just once, when revising the manual -->
  <version>
    <man_version>3.0</man_version>
    <cocoa_version>5.0.9</cocoa_version>
    <date>28 March 2014</date>
  </version>

<!--A description of the structure of the help system-->
  <description>

-- This package provides online help for CoCoA.  The online help
-- consists of two parts: a manual and a list of commands.
-- Each section of the manual and each command is uniquely identified
-- by a set of keywords.  The online help command <tt>H.Man</tt> takes a string from
-- the user and searches for a match among the keywords.  If a match
-- is found, the corresponding description is sourced from the
-- appropriate file, kept in the directory <tt>man</tt> inside the CoCoA
-- directory.  The set of keywords always includes the title of the
-- section or the title of the command.
-- Each command is associated with a list of topics.  (This applies
-- only to commands, not to sections of the manual.)
-- The online help function <tt>H.Commands</tt> takes a string from
-- the user and searches for all matches among these topics.  For each
-- match, the title of the command and a brief description is
-- displayed.  For instance, the user may give the string <em>poly</em> to
-- find all commands having to do with polynomials.  Information about
-- a specific command can then be retrieved with <tt>H.Man</tt>.
--
-- Information about the other online help functions and more details
-- concerning <tt>H.Man</tt> and <tt>H.Commands</tt> can be found through the online
-- help system itself.  To get started, set up the help package as
-- described below,  start CoCoA, and enter <tt>H.Man()</tt>, with no arguments.
--
-- Note: in a CoCoA session, the command <tt>Man</tt> is synonymous with
-- <tt>H.Man</tt>.  When one of these commands is first issued, CoCoA
-- automatically loads the help package.
--
-- TABLE OF CONTENTS FOR THE PACKAGE
-- * Create the manual
--     initializes the global variable, MEMORY.Doc
-- * CoCoA Commands
--     Comms() defined; it creates the commands part of online help
-- * Chapters of the Manual
--     functions ChapM_N() defined; they create the online manual
-- * The Online Help Functions
--     Functions for searching and displaying the manual
--
-- STRUCTURE OF THE VARIABLE, MEMORY.Doc
-- MEMORY.Doc is a record.
--   &quot;.Parts: a list of the parts of the manual.
--     &quot;[K].Name: a string naming part K.
--     &quot;[K].Chapters: a list of chapters in part K.
--       &quot;[L]: a record of the sections of Chapter L.
--       &quot;[L].Name: name for Chapter L.
--       &quot;[L].Sections: a list of sections in chapter L.
--         &quot;[M].SectionType: integer used for nesting sections.
--         &quot;[M].Title: the Title of section M.
--         &quot;[M].Keys: keywords for search, *must be lower-case*!
--         &quot;[M].Descr: main contents of section M.
--         &quot;[M].See: list of strings for related topics in the manual.
--   &quot;.ChapterTitles: a list of decapped chapter titles (speeds up searching)
--   &quot;.Commands: a list of CoCoA commands and functions.
--     &quot;[K].Title: name of the command.
--     &quot;[K].ShortDescr: short description for the command.
--     &quot;[K].Syntax: syntax for the command.
--     &quot;[K].Descr: description of the command.
--     &quot;[K].See: list of strings for related topics in the manual.
--     &quot;[K].Types: a list of strings giving the types for the arguments,
--               for use with the functions Commands();
--     &quot;[K].Keys: keywords with which to find this command.
--                The keys must uniquely define this entry among
--                the commands *and* among the Sections above.
--   &quot;.Pointer: a list used by the Browse function to determine which
--              section of the manual or which command to
--              print.  The format is: [<em>manual</em>, [P,C,S]]
--              or [<em>commands</em>, Com]
--              where P, C, S are the part, chapter, and section numbers,
--              respectively, and Com is the command number.
--
--
  </description>
<!--The following section records changes to the manual with each version.-->
  <changes>
-- VERSION 0.2
-- 1. <tt>Man</tt> now also checks chapter titles for matches.  If an exact
-- match is made, the first section of the chapter is displayed.
-- 2. A new field has been added to MEMORY.Doc called
-- MEMORY.Doc.ChapterTitles consisting of the decapped chapter
-- titles.  It is used to speed up the search for matches among chapter
-- titles.  Otherwise, the decap function slows the search down too
-- much.
--
-- IMPORTANT NOTE: If a chapter is added, then its title must be added
-- to this field.
--
-- 3. Various typos have been fixed and clarifications have been
-- made.  Some new commands have been documented.
-- 4. <tt>H.Toc</tt> has been changed so that <tt>H.Toc()</tt>; displays only
-- chapter titles.  To see the full table of contents, one must now
-- type <tt>H.Toc(<quotes>all</quotes>)</tt>.
-- 5. <tt>H.Chapters</tt> is hidden from view, and its entry is removed from
-- the manual.
-- 6. <tt>Decap</tt> checks for type.
--
-- VERSION 0.3
-- 1. Corrected miscellaneous typos.
-- 2. Added documentation for the new functions dealing with ideals of
--    points.  Added documentation for <tt>EvalHilbertFn</tt>.
--
-- TODO: write section on finite point sets and Buchberger-Moeller
--
-- VERSION 0.4
-- 1. corrected typos, added documentation for miscellaneous new
--    functions.
--
-- VERSION 0.5
-- 1. corrected typos, added documentation for miscellaneous new
--    functions.
--
-- VERSION 0.6
-- 1. usual stuff
-- 2. fixed bug in search function (adding <tt>PotentialFlag</tt> variable).
--
-- VERSION 1.0, 1.1
-- 1. updated entries
--
-- VERSION 1.2
-- 1. updated entries
-- 2. Replace GetEnv(<quotes>COCOA_LIBRARY</quotes>) with CocoaLibrary() (and changed
--    <tt>lib</tt> to <tt>/lib/</tt>).
--
-- VERSION 1.3
-- 1. updated entries
-- 2. <tt>Man</tt> is now called with ?
--
-- VERSION 1.4
-- 1. updated entries
  </changes>

<!-- **************************************** -->
<!-- A big list of CoCoA commands appear next -->
<!-- **************************************** -->
<cocoa_commands>

 <!-- ===  CHAPTER  =============================================== -->
 <chapter_letter>
   <title>Special Characters</title>

<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>operators, shortcuts</title>
    <short_description>Special characters equivalent to commands</short_description>

    <syntax>
A := B   A:variable, B:OBJECT
A = B    A,B:OBJECT
A &lt;&gt; B   A,B:OBJECT
[...]    LIST
[..|..]  LIST
L[N]     N:INT, L:LIST
A..B     A,B:INT  or  A,B:indeterminates
R.F      R:RECORD and F field name
R ::= ... R:variable
A &gt;&lt; B   A,B: LIST
M : N    M, N: MODULE or IDEAL
S[N]     N:INT, S:STRING
***E***  E:expression
?S       S:STRING
&lt;&lt; S     S:STRING
</syntax>

    <description>
<tt>A := B;</tt> compute <tt>B</tt> then assign the result to <tt>A</tt>
<tt>A = B</tt>   test whether <tt>A</tt> and <tt>B</tt> are equal
<tt>A &lt;&gt; B</tt>  test whether <tt>A</tt> and <tt>B</tt> are not equal
<tt>[...]</tt>   build a new list (see <ttref>list constructors</ttref>)
<tt>[..|..]</tt>   build a new list (see <ttref>list constructors</ttref>)
<tt>L[N]</tt>    access <tt>N</tt>-th entry of list <tt>L</tt> (indexes start from 1)
<tt>A..B</tt>    is the <ref>Range Operator</ref>
<tt>R.F</tt>    access field named <tt>F</tt> of <ref>record</ref> <tt>R</tt>
<tt>R ::= </tt>  for the special ring syntax (<ref>NewPolyRing</ref>)
<par/>
<tt>A &gt;&lt; B</tt>  equivalent to <tt>CartesianProduct(A, B)</tt>, <tt>CartesianProductList([A,B])</tt>
<tt>M : N</tt>   equivalent to <tt>colon(M, N)</tt>
<tt>R/I</tt>     equivalent to <tt>NewQuotientRing(R,I)</tt>

<tt>S[N]</tt>    access <tt>N</tt>-th char of string <tt>L</tt> (indexes start from 1)
<tt>***E***</tt>   interpret <tt>E</tt> in <ttref>CoCoA-4 mode</ttref>

<tt><formula>&lt;&lt; S</formula></tt>  OBSOLESCENT equivalent to <ttref>source(S)</ttref>
<par/>
<tt>? string</tt> prints the manual page for <tt>string</tt>, or a list of matching manual pages
    </description>

    <seealso>
      <see>colon</see>
      <see>list constructors</see>
      <see>CartesianProduct, CartesianProductList</see>
      <see>NewPolyRing</see>
      <see>NewQuotientRing</see>
      <see>Range Operator</see>
      <see>source</see>
      <see>Manual</see>
      <see>Character Set and Special Symbols</see>
    </seealso>

    <keys>
    <key>operator</key>
    <key>:</key>
    <key>:=</key>
    <key>::=</key>
    <key>/</key>
    <key>[]</key>
    <key>&lt;&gt;</key>
    <key>&lt;&lt;</key>
    <key>&gt;&lt;</key>
    <key>..</key>
    <key>***</key>
    </keys>
  </command>

<!--     <title>..</title> -->
<!--     <title>:</title> -->
<!--     <title><formula>&lt;&lt;</formula></title> -->
<!--     <title><formula>&gt;&lt;</formula></title> -->
<!--     <title>?</title> -->
<!--     <title>@</title> -->

 </chapter_letter>
 <!-- ===  CHAPTER  =============================================== -->
 <chapter_letter>
   <title>A</title>

<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>abs</title>
    <short_description>absolute value of a number</short_description>

    <description>
This function returns the absolute value of N.
If N is a <tt>RINGELEM</tt> then it must belong to an ordered ring.

<example>
/**/  abs(-3);
3

/**/  abs(-2/3);
2/3
</example>
    </description>

    <syntax>
abs(N:INT):INT
abs(N:RAT):RAT
abs(N:RINGELEM):RINGELEM
</syntax>

    <types>
      <type>integer</type>
      <type>rat</type>
      <type>ringelem</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>adjoint</title>
    <short_description>adjoint matrix</short_description>

    <description>
This function returns the adjoint matrix of M.

<example>
/**/  Use R ::= QQ[t,x,y,z];
/**/  adjoint(mat([[x,y,z],[t,y,x],[x,x^2,x*y]]));
matrix([
 [-x^3 +x*y^2, -x*y^2 +x^2*z, x*y -y*z],
 [-t*x*y +x^2, x^2*y -x*z, -x^2 +t*z],
 [t*x^2 -x*y, -x^3 +x*y, -t*y +x*y]
]

/**/   Z5 := NewRingFp(5);
/**/   adjoint(matrix(Z5, [[1,2],[3,1]])); 
matrix( /*FFp(5)*/
 [[1, -2],
  [2, 1]]
 )
</example>
    </description>

    <syntax>
adjoint(M:MAT):MAT

where M is a square matrix.
</syntax>

    <types>
      <type>matrix</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>AffHilbert</title>
    <short_description>the affine Hilbert function</short_description>

    <description>
The first form of this function computes the affine Hilbert function for R.
The second form computes the N-th value of the affine Hilbert function.  The
weights of the indeterminates of R must all be 1.  For repeated
evaluations of the Hilbert function, use <ttref>EvalHilbertFn</ttref>
instead of <tt>hilbert(R, N)</tt> in order to speed up execution.
<par/>
This function is the same as <ttref>AffHilbertFn</ttref>.
<par/>
The coefficient ring must be a field.

<example>
/**/  Use R ::= QQ[x,y,z];
/**/  AffHilbert(R/ideal(z^4-1, x*z^4-y-3));
H(0) = 1
H(1) = 3
H(t) = 4t - 2   for t >= 2
</example>
    </description>

    <syntax>
AffHilbert(R:RING or TAGGED("Quotient")):TAGGED("$hp.Hilbert")
AffHilbert(R:RING or TAGGED("Quotient"), N:INT):INT
</syntax>

    <seealso>
      <see>AffHilbertSeries</see>
      <see>EvalHilbertFn</see>
    </seealso>

    <types>
      <type>groebner</type>
      <type>groebner-basic</type>
      <type>hilbert</type>
      <type>quotient</type>
      <type>ideal</type>
      <type>ring</type>
    </types>

    <keys>
    <key>bigatti</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>AffHilbertFn</title>
    <short_description>the affine Hilbert function</short_description>

    <description>
Same as <ttref>AffHilbert</ttref>.
    </description>

    <syntax>
AffHilbertFn(R:RING or TAGGED("Quotient")): TAGGED("$hp.Hilbert")
AffHilbertFn(R:RING or TAGGED("Quotient"), N:INT): INT
</syntax>

    <seealso>
      <see>EvalHilbertFn</see>
      <see>HilbertPoly</see>
      <see>HVector</see>
      <see>HilbertSeries</see>
    </seealso>

    <types>
      <type>groebner</type>
      <type>groebner-basic</type>
      <type>hilbert</type>
      <type>ideal</type>
      <type>quotient</type>
      <type>ring</type>
    </types>

    <keys>
    <key>bigatti</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>AffHilbertSeries</title>
    <short_description>the affine Hilbert-Poincare series</short_description>

    <description>
This function computes the affine Hilbert-Poincare series of M.
The grading must be a positive <formula>Z^1</formula>-grading (i.e. <ttref>WeightsMatrix</ttref>
must have a single row with positive entries), and the ordering must
be degree compatible.
In the standard case, i.e. the weights of all
indeterminates are 1, the result is simplified so that the power
appearing in the denominator is the dimension of M + 1.
<par/>
It is exactly the same as <ttref>AffPoincare</ttref>.
<par/>
NOTES:
<par/>
(i) the coefficient ring must be a field.
<par/>
(ii) these functions produce tagged objects: they cannot safely be
     (non-)equality to other values.
<par/>
For further details on affine Hilbert functions see the book:
Kreuzer, Robbiano <quotes>Computer Commutative Algebra II</quotes>, Section 5.6.

<example>
/**/  Use R ::= QQ[x,y,z];
/**/  AffHilbertSeries(R/ideal(z^4-1, x*z^4-y-3));
(1 +x +x^2 +x^3) / (1-x)^2
</example>
    </description>

    <syntax>
AffHilbertSeries(TAGGED("Quotient")):TAGGED("$hp.PSeries")
</syntax>

    <seealso>
      <see>AffHilbert</see>
      <see>HilbertSeries</see>
    </seealso>

    <types>
      <type>groebner</type>
      <type>groebner-basic</type>
      <type>hilbert</type>
      <type>quotient</type>
      <type>ideal</type>
      <type>ring</type>
    </types>

    <keys>
    <key>bigatti</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>AffPoincare</title>
    <short_description>the affine Hilbert-Poincare series</short_description>

    <description>
Same as <ttref>AffHilbertSeries</ttref>.

    </description>

    <syntax>
AffPoincare(TAGGED("Quotient")):TAGGED("$hp.PSeries")
</syntax>

    <seealso>
      <see>AffHilbert</see>
      <see>AffHilbertSeries</see>
      <see>hilbert</see>
      <see>HilbertSeries</see>
    </seealso>

    <types>
      <type>groebner</type>
      <type>groebner-basic</type>
      <type>hilbert</type>
      <type>quotient</type>
      <type>ideal</type>
      <type>ring</type>
    </types>

    <keys>
    <key>bigatti</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>alias</title>
    <short_description>define aliases for package names</short_description>

    <description>
This function is for declaring both global and local aliases for
package names.  Recall that package names are meant to be long in
order to avoid conflicts between the names of functions that are read
into a CoCoA session.  However, it is inconvenient to have to type out
the long package name when referencing a function.  So the user
chooses an alias to take the place of the package name; the alias is
just a means to avoid typing.  Aliases for packages that are routinely
loaded, may be added to <tt>userinit.coc</tt> (see <ref>User Initialization</ref>).
<par/>
1.  Global aliases.  To avoid typing the full package name as a prefix
to package functions, one may declare a short global alias during a
CoCoA session.  A list of the global aliases is produced by the
function <ttref>aliases</ttref>.  For examples, see the chapter on packages in the
manual, in particular the section, <ref>Global Aliases</ref>.  Online, enter
<tt>?global aliases</tt>.
<par/>
2.  Local aliases.  A local alias has the same syntax as a global
alias, however it appears inside a package definition.  The local
aliases work only inside the package and do not conflict with any
global aliases already defined.  In fact, in order to avoid conflicts,
global aliases are not recognized within a package.  For examples,
again look in the chapter for packages.

<example>
/**/  alias LL := $abcd;
/**/  aliases();

Coclib       = $coclib
Approx       = $approx
(...) 
TP           = $contrib/thmproving
TV           = $contrib/typevectors
LL           = $abcd
</example>
    </description>

    <syntax>
alias B_1,...,B_r

where each B_i is a <em>binding</em> of the form: Identifier := $PackageName
</syntax>

    <seealso>
      <see>Alias In</see>
      <see>aliases</see>
      <see>Global Aliases</see>
      <see>Introduction to Packages</see>
      <see>Local Aliases</see>
    </seealso>

    <types>
      <type>packages</type>
    </types>

  </command>
<!-- ===  COMMAND-rm Alias In  =============================================== -->
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>aliases</title>
    <short_description>list of global aliases</short_description>

    <description>
This function prints a list of global aliases for packages. Aliases
are formed with the function <ttref>alias</ttref>.

<example>
/**/  alias LL := $abcd;
/**/  aliases();

Coclib       = $coclib
Approx       = $approx
(...)
TP           = $contrib/thmproving
TV           = $contrib/typevectors
LL           = $abcd
</example>
    </description>

    <syntax>
aliases():TAGGED("aliases")
</syntax>

    <seealso>
      <see>alias</see>
      <see>Introduction to Packages</see>
    </seealso>

    <types>
      <type>packages</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>All CoCoA commands</title>

<description>
This is a (work in progress) complete list of all CoCoA commands:
<commands_and_functions_for type="command"></commands_and_functions_for>
</description>

<keys>
  <key>allcommands</key>
  <key>allcocoacommands</key>
</keys>

</command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>AlmostQR</title>
    <short_description>QR decomposition of a matrix</short_description>

    <description>
This function computes the decomposition of the matrix into an
orthogonal and an upper triangular matrix with 1 on the diagonal.
[<em>orthogonal</em> meaning that <formula>Q<sup>T</sup> * Q</formula> is a diagonal matrix]

<par/>
The auxiliary (possibly slow!) function <tt>Mat.SimplifySquareFactorsInAQR</tt>
modifies Q and R in the decomposition so that the entries of the diagonal
matrix <formula>Q<sup>T</sup> * Q</formula> are squarefree rationals.

<example>
/**/  M := matrix(QQ, [ [4, -2, 3],  [3, 2, -2],  [0, 0, 3] ]);
/**/  Dec := AlmostQR(M);
/**/  Dec;
Record[Q := matrix( /*QQ*/
 [[4, -42/25, 0],
  [3, 56/25, 0],
  [0, 0, 3]]
 )
, R := matrix( /*QQ*/
 [[1, -2/25, 6/25],
  [0, 1, -17/14],
  [0, 0, 1]]
 )
]

/**/  $mat.SimplifySquareFactorsInAQR(ref Dec);
/**/  Dec;
Record[Q := matrix( /*QQ*/
 [[4/5, -3/5, 0],
  [3/5, 4/5, 0],
  [0, 0, 1]]
 )
, R := matrix( /*QQ*/
 [[5, -2/5, 6/5],
  [0, 14/5, -17/5],
  [0, 0, 3]]
 )
, SqDiag := [1, 1, 1]]
</example>
    </description>

    <syntax>
AlmostQR(M:MAT):RECORD
</syntax>

    <seealso>
      <see>Matrix Normal Form</see>
    </seealso>

    <types>
      <type>matrix</type>
    </types>

    <keys>
    <key>qr decomposition</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>append</title>
  <short_description>append an object to a list</short_description>

<syntax>
append(ref L:LIST, E:OBJECT):NULL

where <tt>L</tt> is a list.
</syntax>

<description>
Append the object <tt>E</tt> to the list <tt>L</tt>; this call returns nothing!
<par/>
NOTE: the old CoCoA-4 syntax <tt>Append(L, E)</tt> is still allowed, but
produces a warning; replace the call by <tt>append(ref L, E)</tt>.

  <example>
  /**/  Use R ::= QQ[t,x,y,z];
  /**/  L := [1,2,3];
  /**/  append(ref L, 4);
  /**/  L;
  [1, 2, 3, 4]
  </example>
</description>

  <types>
    <type>list</type>
  </types>

  <seealso>
    <see>ref</see>
    <see>concat</see>
    <see>ConcatLists</see>
    <see>insert</see>
    <see>remove</see>
  </seealso>

</command>

<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>apply</title>
    <short_description>apply homomorphism</short_description>

    <description>
Apply homomorphism <tt>phi</tt> to all elements in second argument <tt>X</tt>
(<tt>RINGELEM</tt>, <tt>LIST</tt>, or <tt>MAT</tt>)
<par/>
When <tt>X</tt> is of type <tt>RINGELEM</tt> this is equivalent to the
natural syntax <tt>phi(X)</tt>.
<example>
/**/ Use R ::= QQ[x,y,z];
/**/ S ::= QQ[x[1..3]];
/**/ phi := PolyAlgebraHom(R, S, indets(S));
/**/ apply(phi, [x^2-y, z-2]);
[x[1]^2 -x[2], x[3] -2]

/**/ apply(phi, x^2-y);  -- same as phi(x^2-y)
x[1]^2 -x[2]
/**/ phi(x^2-y)
x[1]^2 -x[2]
</example>
    </description>

    <syntax>
apply(phi: RINGHOM, X: RINGELEM): RINGELEM
apply(phi: RINGHOM, X: LIST): LIST
apply(phi: RINGHOM, X: MAT): MAT
</syntax>

    <seealso>
      <see>PolyAlgebraHom</see>
      <see>CanonicalHom</see>
    </seealso>

    <types>
      <type>LIST</type>
      <type>MAT</type>
      <type>RINGELEM</type>
      <type>RINGHOM</type>
    </types>

    <keys>
    <key>map</key>
    </keys>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>ascii</title>
    <short_description>convert between characters and ascii code</short_description>

    <syntax>
ascii(N:INT):STRING
ascii(L:LIST of INT):STRING
ascii(S:STRING):LIST of INT
</syntax>

    <description>
In the first form, <tt>ascii</tt> returns the character whose ASCII code is <tt>N</tt>.
<par/>
In the second form, <tt>ascii</tt> returns the string whose characters, in
order, have the ASCII codes listed in <tt>L</tt>.
<par/>
The third form is the inverse of the second: it returns the ASCII codes
of the characters in <tt>S</tt>.

<example>
/**/  ascii(97);
a

/**/  C := ascii("hello world");
/**/  C;
[104, 101, 108, 108, 111, 32, 119, 111, 114, 108, 100]

/**/  ascii(C);
hello world
</example>
    </description>

    <types>
      <type>string</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>AsINT</title>
    <short_description>convert into an INT</short_description>

    <description>
If the argument is an integer value this function returns this value as
an INT, otherwise it throws an error.

<example>
/**/  Use P ::= QQ[x,y];
/**/  type(LC(3*x-y));
RINGELEM
/**/ type(AsINT(LC(3*x-y)));
INT
/**/ type(AsINT(LC((3/2)*x-y)));  -- !!! ERROR !!!
</example>
    </description>

    <syntax>
AsInt(N:INT,RAT,RINGELEM):INT
</syntax>

    <seealso>
      <see>AsRAT</see>
    </seealso>

    <types>
      <type>int</type>
    </types>

    <keys>
      <key>cast</key>
      <key>convert</key>
    </keys>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>AsRAT</title>
    <short_description>convert into a RAT</short_description>

    <description>
If the argument is a rational value this function returns this value as
a RAT, otherwise it throws an error.  Note that if the argument is
actually an integer the result is nevertheless a RAT (with denominator 1).

<example>
/**/  Use P ::= QQ[x,y];
/**/  type(LC(3*x-y));
RINGELEM
/**/ type(AsRAT(LC(3*x-y)));
RAT
</example>
    </description>

    <syntax>
AsRAT(N:INT,RAT,RINGELEM):RAT
</syntax>

    <seealso>
      <see>AsINT</see>
    </seealso>

    <types>
      <type>int</type>
    </types>

    <keys>
      <key>cast</key>
      <key>convert</key>
    </keys>

  </command>

 </chapter_letter>
 <!-- ===  CHAPTER  =============================================== -->
 <chapter_letter>
   <title>B</title>

<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>BaseRing</title>
    <short_description>the base ring of an object</short_description>

    <description>
Might be replaced completely by <ttref>RingOf</ttref>
<par/>

<example>
...work in progress...
</example>
    </description>

    <syntax>
BaseRing(M: MAT):RING
BaseRing(M: MODULE):RING
BaseRing(RmodI: (Quotient)RING):RING
BaseRing(K: (Fraction Field)RING):RING
</syntax>

    <seealso>
      <see>matrix</see>
      <see>NewFractionField</see>
      <see>NewQuotientRing</see>
      <see>NewFreeModule</see>
    </seealso>

    <types>
      <type>ring</type>
      <type>matrix</type>
      <type>module</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>BBasis5</title>
    <short_description>Border Basis of zero dimensional ideal</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This function is implemented in ApCoCoALib by Stefan Kaspar (requires an active <ref>CoCoAServer</ref>).
<par/>
The function <tt>BBasis5</tt> calls the CoCoAServer to compute
a Border Basis of zero dimensional ideal I.

<example>
  Use QQ[x, y], DegLex;
  I := ideal([x^2, xy + y2]);
  BBasis := BBasis5(I);
</example>
    </description>

    <syntax>
BBasis5(I:IDEAL):LIST
</syntax>

    <seealso>
    </seealso>

    <types>
      <type>ideal</type>
      <type>list</type>
    </types>

    <keys>
    <key>apcocoalib</key>
    <key>border basis</key>
    <key>kaspar</key>
    </keys>
  </command>

<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>BettiDiagram</title>
    <short_description>the diagram of the graded Betti numbers</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This function returns the (<quotes>Macaulay-style</quotes>) Betti
diagram for M.

<example>
  Use R ::= QQ[t,x,y,z];
  I := ideal(x^2-yt, xy-zt, xy);
  Res(I);
0 --&gt; R^2(-5) --&gt; R^4(-4) --&gt; R^3(-2)
-------------------------------
  BettiDiagram(I);
        0    1    2
--------------------
 2:     3    -    -
 3:     -    4    2
--------------------
Tot:    3    4    2
-------------------------------
  Untagged(BettiDiagram(I));
Record[Diagram := mat([
  [3, 0, 0],
  [0, 4, 2]
]), FirstShift := 2]
</example>
    </description>

    <syntax>
BettiDiagram(M:IDEAL or MODULE):TAGGED("$gb.BettiDiagram")
</syntax>

    <seealso>
      <see>res</see>
      <see>GB.GetBettiMatrix</see>
      <see>BettiMatrix</see>
    </seealso>

    <types>
      <type>groebner</type>
      <type>ideal</type>
      <type>module</type>
    </types>

  </command>

<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>BettiMatrix</title>
    <short_description>the matrix of the graded Betti numbers</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This function returns the Betti matrix for M.

<example>
  Use R ::= QQ[t,x,y,z];
  I := ideal(x^2-yt, xy-zt, xy);
  Res(I);
0 --&gt; R^2(-5) --&gt; R^4(-4) --&gt; R^3(-2)
-------------------------------
  BettiMatrix(I);
--------------

--------------
   0    0    0
   0    0    3
   0    0    0
   0    4    0
   2    0    0
--------------

-------------------------------
  Untagged(BettiMatrix(I));
mat([
  [0, 0, 0],
  [0, 0, 3],
  [0, 0, 0],
  [0, 4, 0],
  [2, 0, 0]
])
-------------------------------
</example>
    </description>

    <syntax>
BettiMatrix(M:IDEAL or MODULE):TAGGED("$io.Matrix")
</syntax>

    <seealso>
      <see>res</see>
      <see>GB.GetBettiMatrix</see>
      <see>BettiDiagram</see>
    </seealso>

    <types>
      <type>groebner</type>
      <type>ideal</type>
      <type>module</type>
    </types>

  </command>

<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>binomial</title>
    <short_description>binomial coefficient</short_description>

    <description>
This function computes the binomial coefficient, <em>N choose K</em>
according to the formula <formula>(N)(N-1)(N-2)...(N-K+1) / K!</formula>
<par/>
The same formula is used if N is a polynomial.  The integer K cannot
be negative.

<example>
/**/  binomial(4,2);
6

/**/  binomial(-4,3);
-20

/**/  binomial(x^2+2*y,3);
(1/6)*x^6 +x^4*y +(-1/2)*x^4 +2*x^2*y^2 -2*x^2*y +(4/3)*y^3 +(1/3)*x^2 -2*y^2 +(2/3)*y

/**/  It = ***(x^2+2y)*(x^2+2y-1)*(x^2+2y-2)/6***;
true
</example>
    </description>

    <syntax>
binomial(N:INT or POLY, K:INT):INT
</syntax>

    <seealso>
      <see>BinomialRepr, BinomialReprShift</see>
    </seealso>

    <types>
      <type>integer</type>
      <type>polynomial</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>BinomialRepr, BinomialReprShift</title>
  <short_description>binomial representation of integers</short_description>
  
<syntax>
BinomialRepr(N:INT, K:INT): LIST of INT
BinomialReprShift(N:INT, K:INT, Up:INT, Down:INT): INT

where N and K are positive.
</syntax>
<description>
The function <tt>BinomialRepr</tt> computes the <tt>K</tt>-binomial
representation of <tt>N</tt>, also called <i>Macaulay representation</i>,
<i>i.e.</i> the unique expression
<verbatim>
  N = binomial(N(K),K) + binomial(N(K-1),K-1) + ... + binomial(N(L),L)
</verbatim>
where <formula>N(K) &gt; ... &gt; N(L) &gt;= 1</formula>, for some L.
The value returned is the list <tt>[N(t) | t in 1..K]</tt>
where N(t)=0 for all <formula>t &lt; L</formula>.

<par/>
The function call <tt>BinomialReprShift(N,K,up,down)</tt> computes the integer
<verbatim>
  binomial(N(K)  +up,    K+down) +
  binomial(N(K-1)+up,(K-1)+down) +
  ... +
  binomial(N(L)  +up,    L+down)
</verbatim>
It is useful in generalizations of Macaulay&apos;s theorem characterizing
Hilbert functions.

<example>
/**/  BinRep := BinomialRepr(13,4);
/**/  BinRep;
[1, 3, 4, 5]

/**/  BinomialReprShift(13,4,1,1);
16
</example>
</description>

<seealso>
  <see>binomial</see>
</seealso>

<types>
  <type>integer</type>
  <type>list</type>
</types>

<keys>
  <key>binexp</key>
  <key>binomial expansion</key>
  <key>macaulay expansion</key>
  <key>macaulay representation</key>
</keys>
</command>

<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>block</title>
    <short_description>group several commands into a single command</short_description>

    <description>
The <tt>block</tt> command executes the commands as if they where one
command.  What this means in practice is that CoCoA will not print a
string of dashes after executing each <tt>C_i</tt>.  Thus, <tt>Block</tt> is used
on-the-fly and not inside user-defined functions.  (It has nothing to
do with declaration of local variables, for instance, as one might
infer from some other computer languages.)  The following example
should make the use of <tt>Block</tt> clear:

<example>
/**/  Print "hello "; Print "world";
hello world
-------------------------------
  Block
    Print "hello ";
    Print "world";
  EndBlock;
hello world
-------------------------------
  Block
    PrintLn GCD([12, 24, 96]);
    PrintLn LCM([12, 24, 96]);
    PrintLn GCD([x+y, x^2-y^2]);
    Print LCM([x+y, x^2-y^2]);
  EndBlock;

12
96
x + y
x^2 - y^2
-------------------------------
</example>
    </description>

    <syntax>
block C_1; ... ; C_n EndBlock;

where each C_i is a command.
</syntax>

    <types>
      <type>io</type>
      <type>miscellaneous</type>
      <type>printing</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>BlockMat</title>
  <short_description>create a block matrix</short_description>
  
<syntax>
BlockMat(LIST of LIST of MAT):MAT
</syntax>

<description>
This function creates a block matrix from a LIST of rows of matrices.

The following restrictions on the sizes of the matrices apply:
  in each row of matrices <tt>NumRows(M)</tt> must be constant,
and
  for all rows of matrices the total number of columns must be the same.
<par/>
The function <ttref>BlockMat2x2</ttref> has a simpler syntax for a
2x2 block matrix.
<example>
/**/  A := RowMat([1,2,3,4]);   B := RowMat([0,0]);
/**/  BlockMat2x2(A,B, B,A);   -- !!! ERROR !!! as expected
/**/  BlockMat([[A,B], [B,A]]);
matrix( /*QQ*/
 [[1, 2, 3, 4, 0, 0],
  [0, 0, 1, 2, 3, 4]]
 )
</example>
</description>

<keys>
  <key>MultiBlockMatrix</key>
</keys>

<seealso>
  <see>ConcatHor</see>
  <see>ConcatVer</see>
  <see>ConcatHorList</see>
  <see>ConcatVerList</see>
  <see>ConcatDiag</see>
  <see>ConcatAntiDiag</see>
  <see>BlockMat2x2</see>
</seealso>

<types>
  <type>list</type>
  <type>matrix</type>
</types>

</command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>BlockMat2x2</title>
    <short_description>create a block matrix with 4 matrices</short_description>

<syntax>
BlockMat2x2(A:MAT,B:MAT,C:MAT,D:MAT):MAT
</syntax>

<description>
This function creates a block matrix.  Each entry is a matrix.
Given A, B, C, D matrices, then <tt>BlockMat(A,B,C,D)</tt> returns the matrix
<verbatim>
                | A B |
                | C D |
</verbatim>
The obvious restrictions on the sizes of the matrices apply:
<tt>NumRows(A) = NumRows(B)</tt>  and  <tt>NumRows(C) = NumRows(D)</tt>,
and
<tt>NumCols(A) = NumCols(C)</tt>  and  <tt>NumCols(B) = NumCols(D)</tt>.
<par/>
The function <ttref>BlockMat</ttref> offers more flexibility, but
with a heavier syntax.

<example>
/**/    A := matrix([[1,2,3], [4,5,6]]);
/**/    B := matrix([[1,2], [3,4]]);
/**/    C := matrix([[1,1,1], [2,2,2], [3,3,3]]);
/**/    D := matrix([[4,4], [5,5], [6,6]]);
/**/    BlockMat2x2(A,B, C,D);
matrix( /*QQ*/
 [[1, 2, 3, 1, 2],
  [4, 5, 6, 3, 4],
  [1, 1, 1, 4, 4],
  [2, 2, 2, 5, 5],
  [3, 3, 3, 6, 6]]
 )
</example>
</description>

<keys>
  <key>BlockMatrix</key>
</keys>

<seealso>
  <see>ConcatHor</see>
  <see>ConcatVer</see>
  <see>ConcatDiag</see>
  <see>ConcatAntiDiag</see>
  <see>BlockMat</see>
</seealso>

<types>
  <type>list</type>
  <type>matrix</type>
</types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>Bool01</title>
    <short_description>Convert a boolean to an integer</short_description>

    <description>
This function converts a boolean to an integer using the convention:
<tt>false</tt> becomes 0, and <tt>true</tt> becomes 1.

<example>
/**/  Id4 := matrix([[Bool01(i=j) | i in 1..4] | j in 1..4]);
/**/  Id4;
matrix( /*QQ*/
 [[1, 0, 0, 0],
  [0, 1, 0, 0],
  [0, 0, 1, 0],
  [0, 0, 0, 1]]
 )
</example>
    </description>

    <syntax>
Bool01(B:BOOL):INT
</syntax>

    <types>
      <type>boolean</type>
      <type>int</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>break</title>
    <short_description>break out of a loop</short_description>

    <description>
This command must be used inside a loop statement (<tt>for</tt>, <tt>foreach</tt>,
<tt>repeat</tt>, or <tt>while</tt>).
When executed, the current loop statement is terminated and control
passes to the command following the loop statement.
Thus, in the case of nested loops <tt>break</tt> does <em>not</em> break
out of all loops back to the <em>top level</em> (see <tt>Return</tt>).

<example>
  For I := 5 To 1 Step -1 Do
    For J := 1 To 100 Do
      Print J, " ";
      If J = I Then PrintLn; Break; EndIf;
    EndFor;
  EndFor;
1 2 3 4 5
1 2 3 4
1 2 3
1 2
1
</example>
    </description>

    <syntax>
break
</syntax>

    <seealso>
      <see>return</see>
    </seealso>

    <types>
      <type>command</type>
      <type>loops</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>BringIn</title>
    <short_description>bring in objects from another ring</short_description>

    <description>
This function maps a polynomial or rational function (or a list,
matrix of these) into the current ring, preserving the
names of the indeterminates.  When mapping from a ring of finite
characteristic to one of zero characteristic then consistent choices
of image for the coefficients are made (i.e. if two coefficients are
equal mod p then their images will be equal).
<par/>
If the two polynomial rings differ only in characteristic then it
is faster to use the functions <ttref>QZP</ttref>, <ttref>ZPQ</ttref>.
<par/>
This function does not work on ideals because <tt>BringIn(ideal(x-y, x+y))</tt>
into <tt>R[x]</tt> is ambiguous: one might expect <tt>ideal(2x)</tt>,
whereas just mapping the generators would return an error.
So, if you want to map the generators of the ideal type
<tt>ideal(BringIn(gens(I)))</tt>.

<example>
  RR ::= QQ[x[1..4],z,y];
  SS ::= ZZ/(101)[z,y,x[1..2]];
  Use RR;
  F := (x[1]-y-z)^2;
  F;
x[1]^2 - 2x[1]z + z^2 - 2x[1]y + 2zy + y^2
-------------------------------
  Use SS;
  B := BringIn(F);
  B;
z^2 + 2zy + y^2 - 2zx[1] - 2yx[1] + x[1]^2
-------------------------------
  Use R ::= QQ[x,y,z];
  F := (1/2)*x^3 + (34/567)*x*y*z - 890;   -- a poly with rational coefficients
  Use S ::= ZZ/(101)[x,y,z];
  QZP(F) = BringIn(F);
True
-------------------------------
</example>
    </description>

    <syntax>
BringIn(E:OBJECT):OBJECT

where E
 is a polynomial, a rational function, a matrix, or a list.
</syntax>

    <seealso>
      <see>image</see>
      <see>QZP</see>
      <see>ZPQ</see>
    </seealso>

    <types>
      <type>list</type>
      <type>matrix</type>
      <type>polynomial</type>
      <type>ratfun</type>
      <type>moduleelem</type>
    </types>

  </command>

 </chapter_letter>
 <!-- ===  CHAPTER  =============================================== -->
 <chapter_letter>
   <title>C</title>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>Call</title>
    <short_description>apply a function to given arguments</short_description>

    <description>
***** NOT AVAILABLE IN CoCoA-5: functions can be used directly  *****
This function applies the function F to the arguments <tt>X_1,...X_n</tt>.

<example>
  -- The following function MyMax takes a function LessThan as parameter,
  -- and returns the maximum of X and Y w.r.t. the ordering defined by the
  -- function LessThan.

  Define MyMax(LessThan, X, Y)
    If Call(LessThan, X, Y) Then Return Y Else Return X EndIf;
  EndDefine;

  -- Let&apos;s use MyMax by giving two different orderings.

  Define LT_Standard(X, Y)
    Return X &lt; Y;
  EndDefine;
  Define LT_First(X, Y)
    Return True;
  EndDefine;

  MyMax(Function(<quotes>LT_Standard</quotes>),3,5);
5
-------------------------------
  MyMax(Function(<quotes>LT_First</quotes>),5,3);
3
-------------------------------
  MyMax(Function(<quotes>LT_First</quotes>),3,5);
5
-------------------------------
  MyMax(Function(<quotes>LT_First</quotes>),5,3);
3
-------------------------------
</example>
    </description>

    <syntax>
Call(F:FUNCTION, X_1,...,X_n):OBJECT

where X_1,...,X_n are the arguments for the function F.
</syntax>

    <seealso>
      <see>Function</see>
    </seealso>

    <types>
      <type>function</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>CanonicalHom</title>
    <short_description>canonical homomorphism</short_description>

    <description>
CanonicalHom(R, S) -- where R and S are rings, gives the
canonical homomorphism from R to S.
Currently it works only on the most natural constructions:
<verbatim>
ZZ -> S    QQ -> S
R -> R/I   R -> FractionFiels(R)
R -> R[x[1..N]]
</verbatim>

<example>
/**/ Use R ::= QQ[x,y];
/**/ RmodI := NewQuotientRing(R, ideal(x^2-1));

/**/ phi := CanonicalHom(R, RmodI);
/**/ phi(x^3*y);
(x*y)
/**/ RingOf(It) = RmodI;
true

/**/ RingElem(RmodI, x^3*y); -- same as phi(x^3*y)
			     -- internally computes CanonicalHom
</example>
    </description>

    <syntax>
CanonicalHom(R:RING, S:RING): RINGHOM
</syntax>

    <seealso>
      <see>NewFractionField</see>
      <see>NewQuotientRing</see>
      <see>NewPolyRing</see>
      <see>CanonicalHom</see>
      <see>PolyAlgebraHom</see>
      <see>PolyRingHom</see>
    </seealso>

    <types>
      <type>ring</type>
      <type>RINGHOM</type>
    </types>

    <keys>
      <key>canonical homomorphism</key>
    </keys>

  </command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>CartesianProduct, CartesianProductList</title>
  <short_description>Cartesian product of lists</short_description>
  
<syntax>
CartesianProduct(L1:LIST, L2:LIST, L3:LIST, ..): LIST
CartesianProductList(L: LIST of LIST): LIST
L1 &gt;&lt; L2
L1 &gt;&lt; L2 &gt;&lt; ... &gt;&lt; Ln

where each Li is a LIST
</syntax>

<description>
This command returns the list whose elements form the Cartesian product
of <formula>L_1,...,L_n</formula>.
<par/>
For the N-fold product of a list with itself, one may use <ttref>tuples</ttref>.

<example>
/**/  L1 := [1,2,3];
/**/  L2 := ["a","b"];
/**/  L1 &gt;&lt; L2 &gt;&lt; [5];  -- same as
/**/  CartesianProduct(L1, L2, [5]);  -- same as
/**/  CartesianProductList([L1, L2, [5]]);  -- this takes a lists of lists
[[1, "a", 5], [1, "b", 5], [2, "a", 5], [2, "b", 5], [3, "a", 5], [3, "b", 5]]
-------------------------------
/**/  ChessBoard := (1..8)&gt;&lt;(1..8); -- Need brackets around 1..8 otherwise
                                    -- we get a parse error.
</example>
Note that only <tt>&lt;&gt;</tt> is used for <em>not equal</em> in CoCoA.
</description>

<seealso>
  <see>CoCoA Operators</see>
  <see>tuples</see>
  <see>operators, shortcuts</see>
</seealso>

<types>
  <type>list</type>
</types>

<keys>
  <key>&gt;&lt;</key>
  <key>cartesian product</key>
</keys>
</command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>Cast</title>
    <short_description>type conversion</short_description>

    <description>
For casting an INT, RAT, string to a polynomial (and more in general
to a RINGELEM) use <ttref>RingElem</ttref>.


***** NOT YET IMPLEMENTED *****
<par/>
This function returns the value of the expression E after converting
it to type T.  If S and T are types with S &lt; T, then casting from S to
T is usually possible.

<example>
  L := [[1,2],[3,4]];
  type(L);
LIST
-------------------------------
  Cast(L, MAT);
mat([
  [1, 2],
  [3, 4]
])
-------------------------------
  L;  -- L is unchanged; it is still a list.
[[1, 2], [3, 4]]
-------------------------------
  Use ZZ/(5)[t];
  A := 8;
  A;  -- A has type INT
8
-------------------------------
  Cast(A, POLY);  -- cast as a polynomial, A = -2 since the coefficient
                  -- ring is ZZ/5ZZ
-2
-------------------------------
</example>
    </description>

    <syntax>
Cast(E:OBJECT, T:TYPE):TYPE
</syntax>

    <seealso>
      <see>Data Types</see>
      <see>RingElem</see>
      <see>shape</see>
      <see>type</see>
      <see>CurrentTypes</see>
    </seealso>

    <types>
      <type>type</type>
    </types>

    <keys>
      <key>convert</key>
    </keys>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>CFApprox</title>
    <short_description>continued fraction approximation</short_description>

    <description>
CFApprox       finds the <em>simplest</em> continued fraction approximant which is within a
               maximum specified relative error.

<example>
/**/  CFApprox(1.414213, 10^(-2));
17/12
</example>
    </description>

    <syntax>
CFApprox(X:RAT, MaxRelErr:RAT): RAT
</syntax>

    <seealso>
      <see>CFApproximants</see>
      <see>ContFrac</see>
    </seealso>

    <types>
      <type>rat</type>
    </types>

    <keys>
    <key>continued fraction</key>
    <key>convergent</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>CFApproximants</title>
    <short_description>continued fractions</short_description>

    <description>
CFApproximants returns a list of all continued fraction approximants
               to a specified rational

<example>
/**/  CFApproximants(1.414213);
[1, 3/2, 7/5, 17/12, 41/29, 99/70, 239/169, 577/408, 816/577, 1393/985,
 6388/4517, 7781/5502, 14169/10019, 21950/15521, 36119/25540, 58069/41061,
 152257/107662, 210326/148723, 1414213/1000000]
</example>
    </description>

    <syntax>
CFApproximants(X:RAT): LIST of INT and RAT
</syntax>

    <seealso>
      <see>CFApprox</see>
      <see>ContFrac</see>
    </seealso>

    <types>
      <type>rat</type>
    </types>

    <keys>
    <key>continued fraction</key>
    <key>convergent</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>characteristic</title>
    <short_description>the characteristic of a ring</short_description>

    <description>
This function returns the characteristic of the current ring, in the
first case, or of the ring R, in the second.

<example>
/**/   Use R ::= ZZ(3)[t];
/**/   S ::= QQ[x,y];
/**/   characteristic(CurrentRing);
3

/**/  characteristic(S);
0
</example>
    </description>

    <syntax>
characteristic(R:RING):INT
</syntax>

    <seealso>
      <see>IsFiniteField</see>
      <see>LogCardinality</see>
    </seealso>

    <types>
      <type>integer</type>
      <type>ring</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>CharPoly</title>
    <short_description>characteristic polynomial of a matrix</short_description>

    <syntax>
CharPoly(M:MAT, X:INDET): POLY
</syntax>

    <description>
X is an indeterminate, and M is a square matrix whose entries are in the coefficient ring of X.
<par/>
This function returns the characteristic polynomial of M in the indeterminate X.
See also <ttref>MinPoly</ttref>.

<example>
/**/  Use R ::= QQ[x];
/**/  CharPoly(matrix([[1,2,3],[4,5,6],[7,8,9]]), x);
x^3 -15*x^2 -18*x
</example>
    </description>

    <seealso>
      <see>MinPoly</see>
    </seealso>

    <types>
      <type>matrix</type>
    </types>

    <keys>
    <key>characteristic polynomial</key>
    <key>abbott</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>CheckArgTypes</title>
    <short_description>Check types in a list</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This function provides a basic type checking for user defined functions:
it checks whether the types of the elements in the third 
argument, a list, correspond to the types in the second list.
If so, it returns nothing, otherwise returns an error.

<example>
  -- the following returns nothing
  CheckArgTypes("MyFunc", [INT, POLY, IDEAL], [10, 20, ideal(x)]);
  -- the following returns an error for the 3rd argument
  CheckArgTypes("MyFunc", [INT, POLY, IDEAL], [10, 20, 30]);
ERROR: MyFunc: arg 3 is INT but must be IDEAL
CONTEXT: Return(S)
-------------------------------

  -- an example of use for type checking
  Define Power(F, N)
    CheckArgTypes("Power", [POLY, INT], [F, N]);
    Return F^N;
  EndDefine; -- Power
  Power(x, 3);
x^3
-------------------------------
  Power(2, 3);
8
-------------------------------
  Power(2, x);
ERROR: Power: arg 2 is POLY but must be INT
CONTEXT: Return(S)
-------------------------------
</example>
    </description>

    <syntax>
CheckArgTypes(S:STRING, Ltype:LIST of TYPE, Larg:LIST):NULL
</syntax>

    <types>
      <type>list</type>
      <type>string</type>
      <type>type</type>
    </types>

    <keys>
    <key>argument</key>
    <key>checking</key>
    <key>CurrentTypes</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>ciao</title>
    <short_description>quit CoCoA</short_description>

    <description>
This command is used to quit CoCoA.  It may be used only at top level.
    </description>

    <syntax>
ciao
</syntax>

    <seealso>
      <see>quit</see>
    </seealso>

    <types>
      <type>system</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>ClearDenom</title>
    <short_description>clear common denominator of a polynomial with rational coeffs</short_description>

    <description>
This function clears the denominators of the coefficients in a
polynomial over QQ.  It simply multiplies by the least common multiple of
the denominators.

<example>
/**/  Use QQ[x,y];
/**/  F := (2/3)*x + (4/5)*y;
/**/  ClearDenom(F);
10*x +12*y
</example>
    </description>

    <syntax>
ClearDenom(F:POLY):POLY
</syntax>

    <types>
      <type>poly</type>
    </types>

    <keys>
    <key>clearing denominator</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>close</title>
    <short_description>close a device</short_description>

    <description>
This function closes the device D.

<example>
  D := OpenOFile("my-test"); -- open file for output from CoCoA
  Print "test" On D;  -- write to my-file
  Close(D);  -- close the file
  Close(DEV.STDIN);  -- close the standard input device
-- Bye

(Close(DEV.OUT) suppresses all output to the CoCoA window.)
</example>
    </description>

    <syntax>
close(D:DEVICE)
</syntax>

    <seealso>
      <see>Introduction to IO</see>
    </seealso>

    <types>
      <type>io</type>
      <type>printing</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>CloseLog</title>
    <short_description>close a log of a CoCoA session</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This function <ttref>OpenLog</ttref> opens the output device D and
starts to record the output from a CoCoA session on D.
<par/>
This function closes the device D and stops recording the CoCoA session on D.
    </description>

    <syntax>
CloseLog(D:DEVICE):NULL
</syntax>

    <seealso>
      <see>OpenLog</see>
    </seealso>

    <types>
      <type>io</type>
      <type>printing</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>CoCoA-4 mode</title>
    <short_description>Backward compatibility mode for CoCoA-4</short_description>

    <syntax>
  *** E ***

where <tt>E</tt> is a CoCoA-4 expression.
</syntax>

    <description>
CoCoA-5 is not fully backward compatible with CoCoA-4, <i>i.e.</i> some CoCoA-4
programs will be rejected by CoCoA-5.  CoCoA-4 mode helps ease the transition to
CoCoA-5.
<par/>
In CoCoA-4 it was not necessary to write explicitly the product between two
indeterminates; in CoCoA-5 this is obligatory.
<par/>
The expression <tt>E</tt> may also contain function calls, but only if the function
names begin with a capital letter.

<example>
/**/ Use QQ[x,y,z];
/**/ f := 2*x^2*y - 3*x*y*z - 4*y^2*z + 5*y*z^2 + 6*z^3;
/**/ g := ***2x^2y - 3xyz - 4y^2z + 5yz^2 + 6z^3***; --> C4 mode, more compact!
/**/ f = g;
true
</example>
    </description>

    <seealso>
      <see>updating CoCoA-4 code</see>
      <see>operators, shortcuts</see>
      <see>not, and, or</see>
    </seealso>

    <types>
      <type>polynomial</type>
      <type>rational function</type>
    </types>

    <keys>
      <key>*</key>
      <key>***</key>
      <key>multiplication by juxtaposition</key>
    </keys>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>CocoaLimits</title>
    <short_description>limits on exponents and ring characteristics</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This function returns the maximum allowable characteristic of a CoCoA
ring and the maximum allowable exponent in a CoCoA expression.  These
numbers may vary depending on the platform on which CoCoA is run.

<example>
  CocoaLimits();
Record[MaxChar := 32767, MaxExp := 2147483647]
-------------------------------
</example>
    </description>

    <syntax>
CocoaLimits():RECORD
</syntax>

    <types>
      <type>system</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>CocoaPackagePath</title>
    <short_description>returns the path to the CoCoA packages</short_description>

    <description>
This function returns the path name of the directory containing the CoCoA
libraries. It is platform dependent.

<example>
/**/  CocoaPackagePath();
/Applications/CoCoA-5/packages
</example>
    </description>

    <syntax>
CocoaPackagePath():STRING
</syntax>

    <types>
      <type>system</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>CoeffEmbeddingHom</title>
    <short_description>returns the coefficient embedding homomorphism of a polynomial ring</short_description>

    <syntax>
CoeffEmbeddingHom(P:RING):RINGHOM
</syntax>

    <description>
This function returns the coefficient embedding homomorphism of the
polynomial ring <tt>P</tt>.

<example>
/**/ Use P ::= QQ[x,y];
/**/ phi := CoeffEmbeddingHom(P);
/**/ f := 2*x+3*y;
/**/ f/phi(LC(f));
x + (3/2)*y
</example>
    </description>

    <keys>
       <key>homomorphism</key>
    </keys>

    <types>
      <type>ring</type>
      <type>ringhom</type>
    </types>

    <seealso>
      <see>CanonicalHom</see>
    </seealso>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>coefficients</title>
    <short_description>list of coefficients of a polynomial</short_description>

    <description>
This function returns a list of coefficients of F in <tt>CoeffRing(RingOf(F))</tt>.
<par/>
Called with one argument F it returns the list of all non-zero
coefficients; the order being decreasing on the terms in F as
determined by the term-ordering of <tt>RingOf(F)</tt>.
<par/>
Called with two arguments F it returns the coefficients of the
list of specified terms S; their order is determined by the list S.
<par/>
The old form (CoCoA-4) <tt>Coefficients(F,x)</tt> for the coefficients
of F w.r.t an indeterminate x is now implemented
as <ttref>CoefficientsWRT</ttref> and <ttref>CoeffListWRT</ttref>.

<example>
/**/  Use R ::= QQ[x,y,z];
/**/  F := 3*x^2*y + 5*y^2 - x*y;
/**/  Coeffs := coefficients(F);  Coeffs;  -- with one argument
[3, -1, 5]
/**/  phi := CoeffEmbeddingHom(RingOf(F));
/**/  F = ScalarProduct(apply(phi,Coeffs), support(F));
true

/**/  Skeleton := [1, x, y, z, x^2, x*y, y^2, y*z, z^2];
/**/  Coeffs := coefficients(F, Skeleton);  Coeffs;  -- with two arguments
[0, 0, 0, 0, 0, -1, 5, 0, 0]
/**/  ScalarProduct(apply(phi,Coeffs), Skeleton);
-x*y +5*y^2

/**/  L := CoefficientsWRT(F,[x,y,z]);  indent(L);  -- similar function
[
  Record[PP := y^3, coeff := 5],
  Record[PP := x^2*y, coeff := 3],
  Record[PP := x*y^5, coeff := -1]
]
/**/  F = sum([X.coeff * X.PP | X In L]);
true

/**/  L := CoeffListWRT(F, y);  L;  -- similar function
[0, 3*x^2 -x, 5]
/**/  F = sum([L[d+1]*y^d | d in 0..(len(L)-1)]);
true

/**/  R3 := NewFreeModule(R,3);
/**/  V := ModuleElem(R3, ***[3x^2+y, x-5z^3, x+2y]***);
/**/  ConcatLists([coefficients(V[i]) | i In 1..NumCompts(V)]);
[3, 1, -5, 1, 1, 2]
</example>
    </description>

    <syntax>
coefficients(F:POLY):LIST
coefficients(F:POLY, S:LIST):LIST
</syntax>

    <seealso>
      <see>Coefficient Rings</see>
      <see>CoefficientsWRT</see>
      <see>CoeffListWRT</see>
      <see>LC</see>
      <see>monomials</see>
      <see>support</see>
    </seealso>

    <types>
      <type>polynomial</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>CoefficientsWRT</title>
    <short_description>list of coefficients and PPs of a polynomial wrt and indet or a list of indets</short_description>

    <syntax>
CoefficientsWRT(F:RINGELEM, F:RINGELEM): LIST
CoefficientsWRT(F:RINGELEM, S:LIST of RINGELEM): LIST
</syntax>

    <description>
This function returns the list of the coefficients and PPs of F seen
as a polynomial in X, and indeterminate or a list of indeterminates.
All entries in the returned list are RingElem in RingOf(F). 

<example>
/**/ Use R ::= QQ[x,y,z]; 
/**/ f := x^3*z+x*y+x*z+y+2*z;
/**/ Cx :=  CoefficientsWRT(f, x);  -- same as...
/**/ Cx :=  CoefficientsWRT(f, [x]);
/**/ indent(Cx);
[
  Record[PP := 1, coeff := y +2*z],
  Record[PP := x, coeff := y +z],
  Record[PP := x^3, coeff := z]
]
/**/ f = sum([M.coeff * M.PP | M In Cx]);
true
/**/ Foreach M In Cx Do Print "  +(", M.coeff, ")*", M.PP; EndForeach;
  +(y +2*z)*1  +(y +z)*x  +(z)*x^3

/**/ Cxz :=  CoefficientsWRT(f, [x,z]);
/**/ indent(Cxz);
[
  Record[PP := 1, coeff := y],
  Record[PP := z, coeff := 2],
  Record[PP := x, coeff := y],
  Record[PP := x*z, coeff := 1],
  Record[PP := x^3*z, coeff := 1]
]
</example>
    </description>

    <seealso>
      <see>Coefficient Rings</see>
      <see>CoeffOfTerm</see>
      <see>ContentWRT</see>
      <see>LC</see>
      <see>monomials</see>
      <see>support</see>
    </seealso>

    <types>
      <type>polynomial</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>CoeffListWRT</title>
    <short_description>list of coefficients of a polynomial wrt and indet</short_description>

    <description>
This function returns the list of the coefficients of F seen as a
univariate polynomial in X, and indeterminate or a list of
indeterminates. 
All entries in the returned list are RingElem in RingOf(F). 
<par/>
Note that the returned list is <em>reversed</em> from the CoCoA-4 analogue
<tt>Coefficients(F,X)</tt> thus to re-use old code you should call
<tt>reversed(CoeffListWRT(F,X))</tt>.

<example>
/**/  Use R ::= QQ[x,y,z]; 
/**/  L := CoeffListWRT(F, y);  L;  -- similar function
[0, 3*x^2 -x, 5]
/**/  F = sum([L[d+1]*y^d | d in 0..(len(L)-1)]);
true
</example>
    </description>

    <syntax>
CoeffListWRT(F:RINGELEM, F:RINGELEM): LIST
</syntax>

    <seealso>
      <see>coefficients</see>
      <see>CoefficientsWRT</see>
    </seealso>

    <types>
      <type>polynomial</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>CoeffOfTerm</title>
    <short_description>coefficient of a term of a polynomial</short_description>

    <description>
This function returns the coefficient of the term T occurring in F.
NB: In CoCoA 4 the order of the arguments was different.

<example>
/**/  Use R ::= QQ[x,y,z];
/**/  F := 5*x*y^2 - 3*z^3;
/**/  CoeffOfTerm(F, x*y^2);
5

/**/  CoeffOfTerm(F, x^3);
0

/**/  CoeffOfTerm(F, z^3);
-3

/**/  CoeffOfTerm(Vector(0,x^3,0), Vector(x+3, 6xy-5x^3, x-z^2));--***OBSOLETE MANUAL: WORK IN PROGRESS***
-5
</example>
    </description>

    <syntax>
CoeffOfTerm(F:POLY, T:POLY):C
CoeffOfTerm(F:MODULEELEM, T:MODULEELEM):C --***OBSOLETE MANUAL: WORK IN PROGRESS***

where T is a term (no coefficient) and C is one of INT, RAT, or ZMOD.
</syntax>

    <seealso>
      <see>coefficients</see>
      <see>LC</see>
      <see>log</see>
      <see>LogToTerm</see>
      <see>monomials</see>
      <see>support</see>
    </seealso>

    <types>
      <type>polynomial</type>
      <type>moduleelem</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>CoeffRing</title>
    <short_description>the ring of coefficients of a polynomial ring</short_description>

    <description>
This function returns the ring of coefficients of a polynomial ring.

<example>
/**/  Use R ::= QQ[x,y,z];
/**/  S ::= ZZ/(2)[a,b,c];
/**/  CoeffRing(R);
QQ

/**/  CoeffRing(S);
FFp(2)
</example>
    </description>

    <syntax>
CoeffRing(R:RING):RING
</syntax>

    <seealso>
      <see>characteristic</see>
      <see>coefficients</see>
      <see>CurrentRing</see>
      <see>indets</see>
    </seealso>

    <types>
      <type>ring</type>
      <type>type</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>ColMat</title>
    <short_description>single column matrix</short_description>

    <description>
This function returns the matrix whose only column consists of the
elements of the list L.

<example>
/**/  ColMat([3,4,5]);
matrix( /*QQ*/
 [[3],
  [4],
  [5]]
 )

/**/  RingOf(It);  -- default ring is QQ
QQ

/**/  ColMat(ZZ, [3,4,5]);
matrix( /*ZZ*/
 [[3],
  [4],
  [5]]
 )
/**/  RingOf(It);
ZZ
</example>
    </description>

    <syntax>
ColMat(L:LIST):MAT
ColMat(R:RING, L:LIST):MAT
</syntax>

    <seealso>
      <see>matrix</see>
      <see>BlockMat</see>
      <see>DiagMat</see>
      <see>RowMat</see>
      <see>GensAsCols, GensAsRows</see>
    </seealso>

    <types>
      <type>matrix</type>
    </types>

    <keys>
    <key>column matrix</key>
    <key>columnmatrix</key>
    <key>colmatrix</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>colon</title>
    <short_description>ideal or module quotient</short_description>

    <description>
This function returns the quotient of M by N: the ideal of all
polynomials F such that F*G is in M for all G in N. The command
<tt>M : N</tt> is a shortcut for <tt>colon(M, N)</tt>.
<par/>
See also  <ttref>HColon</ttref> for non-homogeneous input.

<example>
/**/  Use R ::= QQ[x,y];
/**/  ideal(x*y, x^2) : ideal(x);
ideal(y, x)

/**/  colon(ideal(x^2, x*y), ideal(x, x-y^2));
ideal(x)
</example>
    </description>

    <syntax>
colon(M:IDEAL, N:IDEAL):IDEAL
colon(M:MODULE, N:MODULE):IDEAL
</syntax>

    <seealso>
      <see>saturate</see>
      <see>HSaturation</see>
      <see>HColon</see>
      <see>operators, shortcuts</see>
    </seealso>

    <types>
      <type>groebner</type>
      <type>groebner-basic</type>
      <type>ideal</type>
      <type>module</type>
      <type>polynomial</type>
      <type>moduleelem</type>
    </types>

    <keys>
      <key>quotient</key>
    </keys>

  </command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>ColumnVectors</title>
  <short_description>list of module elements</short_description>

<description>
OBSOLETE: essentially replaced by
<ttref>GensAsCols, GensAsRows</ttref>
and
<ttref>SubmoduleCols, SubmoduleRows</ttref>
</description>

<types>
  <type>matrix</type>
  <type>moduleelem</type>
</types>

<seealso>
  <see>GensAsCols, GensAsRows</see>
  <see>SubmoduleCols, SubmoduleRows</see>
</seealso>

</command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>comp</title>
    <short_description>the N-th component of a list</short_description>

    <description>
This function returns <tt>E[X_1,...,X_k]</tt> except in the case where there
are no additional arguments <tt>X_1,...,X_k</tt>, in which case E, itself, is
returned (in other words <tt>Comp(E)</tt> returns E).  Since the square
bracket notation works only for variables and indeterminates, this
function must be used in all other situations (e.g. directly indexing
into, or selecting from, the result of a function call).

<example>
/**/  Use R ::= QQ[x,y,z];
/**/  L := [4,5,[6,7],8];
/**/  comp(L,1);
4

/**/  comp(L,3);
[6, 7]

/**/  comp(L,3,2);
7

/**/  Define F(X)  Return [X, X^2];  EndDefine;  
  -- the following usage of "comp" is useful for programming
/**/  F(2);
[2, 4]

/**/  comp(F(2),2);
4

/**/  Struct := record[L := [x,y,z], S := "string"];
/**/  Struct["L",3]; -- "Comp" works for records also
z

/**/  comp(Struct,"L",3);
z

/**/  comp("this is a string",3);  -- use of "comp" with strings
i
</example>
    </description>

    <syntax>
comp(E:LIST, RECORD, STRING, or MODULEELEM, X_1:INT,...,X_k:INT):OBJECT
</syntax>

    <types>
      <type>list</type>
      <type>record</type>
      <type>string</type>
      <type>moduleelem</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>CompleteToOrd</title>
    <short_description>completes a matrix to an ordering matrix</short_description>

    <description>
This function returns an ordering matrix (i.e. with non-zero
determinant) completing the first matrix.

Given two matrices M1 and M2, it just concatenates of M1 and M2 and
makes it square removing the redundant rows.

Given only one matrix M it completes M to an ordering matrix; if
M is suitable the resulting matrix defines a term-ordering.

<example>
/**/  M := matrix([[1,2,3,4]]);
/**/  CompleteToOrd(M);
 [[1, 2, 3, 4],
  [0, 0, 0, -1],
  [0, 0, -1, 0],
  [0, -1, 0, 0]]
 )

/**/  CompleteToOrd(M, LexMat(4));
matrix( /*QQ*/
 [[1, 2, 3, 4],
  [1, 0, 0, 0],
  [0, 1, 0, 0],
  [0, 0, 1, 0]]
 )

/**/  CompleteToOrd(matrix([[1,2,0,0]]));
 [[1, 2, 0, 0],
  [0, 0, 1, 1],
  [0, 0, 0, -1],
  [0, -1, 0, 0]]
 )

/**/  CompleteToOrd(matrix([[1,2,0,0],[0,0,3,0]]));
matrix( /*QQ*/
 [[1, 2, 0, 0],
  [0, 0, 3, 0],
  [0, 0, 0, 1],
  [0, -1, 0, 0]]
 )

/**/  CompleteToOrd(matrix([[1,2,0,0],[0,0,3,0]]), RevLexMat(4));
matrix( /*QQ*/
 [[1, 2, 0, 0],
  [0, 0, 3, 0],
  [0, 0, 0, -1],
  [0, -1, 0, 0]]
 )
--> not a term-ordering
</example>
    </description>

    <syntax>
CompleteToOrd(M: MAT):MAT
CompleteToOrd(M1, M2: MAT):MAT
</syntax>

    <types>
      <type>matrix</type>
    </types>

    <keys>
      <key>term-ordering</key>
      <key>termordering</key>
      <key>NewMatCompleteOrd</key>
    </keys>

    <seealso>
      <see>LexMat</see>
      <see>RevLexMat</see>
      <see>StdDegLexMat</see>
      <see>StdDegRevLexMat</see>
    </seealso>

  </command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>compts</title>
  <short_description>list of components of a ModuleElem</short_description>
  
<syntax>
compts(V:MODULEELEM):LIST
Comps(V:MODULEELEM):LIST
</syntax>

    <description>
<par/>
This function returns the list of components of a ModuleElem V.
It is like converting a ModuleElem into a generic list.
Note that a ModuleElem is a more structured object than a generic
list.
<example>
/**/  R3 := NewFreeModule(R,3);
/**/  V := ModuleElem(R3, ***[3x^2+4y, 2x-5z^3, 2x+2y]***);  V;
[3*x^2 +4*y, -5*z^3 +2*x, 2*x +2*y]
/**/  type(V);
MODULEELEM

/**/  compts(V);
[3*x^2 +4*y, -5*z^3 +2*x, 2*x +2*y]
/**/ type(compts(V));
LIST
</example>
</description>
    
    <seealso>
      <see>comp</see>
      <see>NumCompts</see>
    </seealso>
    <keys>
      <key>components</key>
      <key>comps</key>
    </keys>
    <types>
      <type>moduleelem</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>concat</title>
    <short_description>concatenate lists</short_description>

    <description>
This function returns the list obtained by concatenating lists
<tt>L_1,...,L_n</tt>.
<par/>
To concatenate strings use <tt>+</tt>.
<example>
/**/  concat([1,2,3],[4,5],[],[6]);
[1, 2, 3, 4, 5, 6]
</example>
    </description>

    <syntax>
concat(L_1:LIST,...,L_n:LIST):LIST
</syntax>

    <seealso>
      <see>Concatenation</see>
      <see>ConcatLists</see>
    </seealso>

    <types>
      <type>list</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>ConcatAntiDiag</title>
    <short_description>create a simple block matrix</short_description>

    <description>
This function creates a simple block matrix.  The two entries are
matrices.
ConcatAntiDiag(A, B) will return a matrix of the form
<verbatim>
                | 0 A |
                | B 0 |
</verbatim>

<example>
/**/  A := mat([[1,2,3],   [4,5,6]]);
/**/  B := mat([[101,102], [103,104]]);
/**/  ConcatAntiDiag(A, B);
matrix([
  [0, 0, 1, 2, 3],
  [0, 0, 4, 5, 6],
  [101, 102, 0, 0, 0],
  [103, 104, 0, 0, 0]
])
</example>
    </description>

    <syntax>
ConcatAntiDiag(A:MAT, B:MAT):MAT
</syntax>

    <seealso>
      <see>BlockMat</see>
      <see>ConcatDiag</see>
      <see>ConcatHor</see>
      <see>ConcatVer</see>
    </seealso>

    <types>
      <type>list</type>
      <type>matrix</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>ConcatDiag</title>
    <short_description>create a simple block matrix</short_description>

    <description>
This function creates a simple block matrix.  The two entries are
matrices.
ConcatDiag(A, B) will return a matrix of the form
<verbatim>
                | A 0 |
                | 0 B |
</verbatim>

<example>
/**/  A := mat([[1,2,3],   [4,5,6]]);
/**/  B := mat([[101,102], [103,104]]);
/**/  ConcatDiag(A, B);
matrix([
  [1, 2, 3, 0, 0],
  [4, 5, 6, 0, 0],
  [0, 0, 0, 101, 102],
  [0, 0, 0, 103, 104]
])
</example>
    </description>

    <syntax>
ConcatDiag(A:MAT, B:MAT):MAT
</syntax>

    <seealso>
      <see>BlockMat</see>
      <see>ConcatAntiDiag</see>
      <see>ConcatHor</see>
      <see>ConcatVer</see>
      <see>DiagMat</see>
    </seealso>

    <types>
      <type>list</type>
      <type>matrix</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>ConcatHor</title>
    <short_description>create a simple block matrix</short_description>

    <description>
This function creates a simple block matrix.  The two entries are
matrices with the same number of rows. 
ConcatHor(A, B) will return a matrix of the form
<verbatim>
                | A B |
</verbatim>

<example>
/**/  A := mat([[1,2,3],   [4,5,6]]);
/**/  B := mat([[101,102], [103,104]]);
/**/  ConcatHor(A, B);
matrix([
  [1, 2, 3, 101, 102],
  [4, 5, 6, 103, 104]
])
</example>
    </description>

    <syntax>
ConcatHor(A:MAT, B:MAT):MAT

where A and B have the same number of rows
</syntax>

    <seealso>
      <see>BlockMat</see>
      <see>MakeMatByRows, MakeMatByCols</see>
      <see>ConcatAntiDiag</see>
      <see>ConcatDiag</see>
      <see>ConcatHorList</see>
      <see>ConcatVer</see>
      <see>RowMat</see>
    </seealso>

    <types>
      <type>list</type>
      <type>matrix</type>
    </types>

    <keys>
    <key>extend rows</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>ConcatHorList</title>
    <short_description>create a simple block matrix</short_description>

    <description>
This function creates a simple block matrix.  The entries in the list are
matrices with the same number of rows.
ConcatHorList(L) will return a matrix of the form
<verbatim>
                | L[1] L[2] .. L[N] |
</verbatim>

<example>
/**/  L := [ mat([[1,2,3], [4,5,6]]), mat([[101,102], [103,104]]) ];
/**/  ConcatHorList(L);
matrix([
  [1, 2, 3, 101, 102],
  [4, 5, 6, 103, 104]
])
</example>
    </description>

    <syntax>
ConcatHorList(L:LIST of MAT):MAT

where the matrices in L have the same number of rows
</syntax>

    <seealso>
      <see>BlockMat</see>
      <see>MakeMatByRows, MakeMatByCols</see>
      <see>ConcatAntiDiag</see>
      <see>ConcatDiag</see>
      <see>ConcatHor</see>
      <see>ConcatVerList</see>
      <see>RowMat</see>
    </seealso>

    <types>
      <type>list</type>
      <type>matrix</type>
    </types>

    <keys>
    <key>extend rows</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>ConcatLists</title>
    <short_description>concatenate a list of lists</short_description>

    <description>
This function takes a list whose components are lists and
returns the concatenation of these components.

<example>
/**/  L := [[1,2],["abc","def"],[3,4]];
/**/  ConcatLists(L);
[1, 2, "abc", "def", 3, 4]
</example>
    </description>

    <syntax>
ConcatLists([L_1:LIST,...,L_n:LIST]):LIST
</syntax>

    <seealso>
      <see>concat</see>
    </seealso>

    <types>
      <type>list</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>ConcatVer</title>
    <short_description>create a simple block matrix</short_description>

    <description>
This function creates a simple block matrix.  The two entries are
matrices with the same number of columns. 
ConcatVer(A, B) will return a matrix of the form
<verbatim>
                | A |
                | B |
</verbatim>

<example>
/**/  A := mat([[1,2,3], [4,5,6]]);
/**/  B := mat([[101,102,103]]);
/**/  ConcatVer(A, B);
matrix([
  [1, 2, 3],
  [4, 5, 6],
  [101, 102, 103]
])
</example>
    </description>

    <syntax>
ConcatVer(A:MAT, B:MAT):MAT

where A and B have the same number of columns
</syntax>

    <seealso>
      <see>BlockMat</see>
      <see>ColMat</see>
      <see>MakeMatByRows, MakeMatByCols</see>
      <see>ConcatAntiDiag</see>
      <see>ConcatDiag</see>
      <see>ConcatHor</see>
      <see>ConcatVerList</see>
    </seealso>

    <types>
      <type>list</type>
      <type>matrix</type>
    </types>

    <keys>
    <key>extend columns</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>ConcatVerList</title>
    <short_description>create a simple block matrix</short_description>

    <description>
This function creates a simple block matrix.  The entries in the list are
matrices with the same number of columns. 
ConcatVer(L) will return a matrix of the form
<verbatim>
                | L[1] |
                | L[2] |
                |  ..  |
</verbatim>

<example>
/**/  L := [ mat([[1,2,3], [4,5,6]]), mat([[101,102,103]]) ];
/**/  ConcatVerList(L);
matrix([
  [1, 2, 3],
  [4, 5, 6],
  [101, 102, 103]
])
</example>
    </description>

    <syntax>
ConcatVerList(L:LIST of MAT):MAT

where the matrices in L have the same number of columns
</syntax>

    <seealso>
      <see>BlockMat</see>
      <see>ColMat</see>
      <see>MakeMatByRows, MakeMatByCols</see>
      <see>ConcatAntiDiag</see>
      <see>ConcatDiag</see>
      <see>ConcatVer</see>
      <see>ConcatHorList</see>
    </seealso>

    <types>
      <type>list</type>
      <type>matrix</type>
    </types>

    <keys>
    <key>extend columns</key>
    </keys>
  </command>
<!-- ===  COMMAND-rm cond  =============================================== -->
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>content</title>
    <short_description>content of a polynomial</short_description>

    <description>
This function returns the content of F (i.e. a gcd of its coefficients).
<par/>
The returned value is a RingElem in RingOf(F). 

<example>
/**/ Use R ::= QQ[x,y,z]; 
/**/ F := *** 1234x^3z + 3456xyz^3 + 5678y^2z ***;
/**/ content(F);
2
/**/ RingOf(It);
QQ
</example>
    </description>

    <syntax>
content(F:RINGELEM): RINGELEM
</syntax>

    <seealso>
      <see>ContentWRT</see>
      <see>coefficients</see>
    </seealso>

    <types>
      <type>polynomial</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>ContentFreeFactor</title>
    <short_description>factorization of multivariate polynomial into content-free factors</short_description>

    <syntax>
ContentFreeFactor(F:RINGELEM):RECORD
    </syntax>

    <description>
This function returns a factorization of the multivariate polynomial F into
content-free factors; it works by calling <code>ContentWRT</code> repeatedly.
The multiplicities will always be 1.

<example>
/**/ Use R ::= QQ[x,y,z]; 
/**/ F := 2*(x+1)*(y+2)*(x+y);
/**/ indent(ContentFreeFactor(F));
Record[
  RemainingFactor := 2,
  factors := [y +2, x +1, x +y],
  multiplicities := [1, 1, 1]
]
</example>
    </description>

    <seealso>
      <see>ContentWRT</see>
      <see>factor</see>
      <see>SqfreeFactor</see>
    </seealso>

    <types>
      <type>polynomial</type>
    </types>

    <keys>
    <key>factorization</key>
    <key>content</key>
    <key>primitive</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>ContentWRT</title>
    <short_description>content of a polynomial wrt and indet or a list of indets</short_description>

    <description>
This function returns the content of F (i.e. a gcd of its
coefficients) seen as a polynomial in X, indet or list of
indeterminates. 
The returned value is a RingElem in RingOf(F). 

<example>
/**/ Use R ::= QQ[x,y,z]; 
/**/ F := x^3*z + x*y*z^3 + 2*z;
/**/ Cx :=  CoefficientsWRT(F, x);
/**/ indent(Cx);
[
  Record[PP := 1, coeff := 2*z],
  Record[PP := x, coeff := y*z^3],
  Record[PP := x^3, coeff := z]
]
/**/ ContentWRT(F, x);
z
/**/ ContentWRT(F, [x]);
z
</example>
    </description>

    <syntax>
ContentWRT(F:RINGELEM, X:RINGELEM): RINGELEM
ContentWRT(F:RINGELEM, L:LIST of RINGELEM): RINGELEM
</syntax>

    <seealso>
      <see>CoefficientsWRT</see>
      <see>content</see>
      <see>monomials</see>
    </seealso>

    <types>
      <type>polynomial</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>ContFrac</title>
    <short_description>continued fraction quotients</short_description>

    <description>
ContFrac returns a list of the continued fraction <em>quotients</em>
for a given rational number.

<example>
/**/  ContFrac(1.414213);
[1, 2, 2, 2, 2, 2, 2, 2, 1, 1, 4, 1, 1, 1, 1, 1, 2, 1, 6]
</example>
    </description>

    <syntax>
ContFrac(X:RAT):LIST of INT
</syntax>

    <seealso>
      <see>CFApprox</see>
      <see>CFApproximants</see>
      <see>ContFracToRat</see>
    </seealso>

    <types>
      <type>rat</type>
    </types>

    <keys>
    <key>continued fraction</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>ContFracToRat</title>
    <short_description>convert continued fraction to rational</short_description>

    <description>
ContFracToRat returns the rational number equal to the continued
fraction whose quotients are given as input.  The quotients must
all be integers, only the very first may be non-positive.

<example>
/**/  ContFracToRat([1, 2, 2, 2, 2, 2, 2, 2]);
577/408
</example>
    </description>

    <syntax>
ContFracToRat(L:LIST of INT):RAT
</syntax>

    <seealso>
      <see>ContFrac</see>
      <see>CFApprox</see>
      <see>CFApproximants</see>
    </seealso>

    <types>
      <type>rat</type>
    </types>

    <keys>
    <key>continued fraction</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
<!--   <command> -->
<!--     <title>Contrib</title> -->
<!--     <short_description>list of contributors to CoCoA</short_description> -->

<!--     <description> -->
<!-- This function returns a list of contributors to the main CoCoA -->
<!-- system.  In addition to these contributions, there are many other -->
<!-- contributions which are not part of the standard distribution.  For -->
<!-- pointers to these, see the CoCoA homepage at -->
<!-- <tt>http://cocoa.dima.unige.it</tt> or one of its mirrors. -->
<!--     </description> -->

<!--     <syntax> -->
<!-- Contrib():NULL -->
<!-- </syntax> -->

<!--     <type>misc</type> -->
<!--     <type>system</type> -->

    <keys>
<!--     <key>contrib</key> -->
    </keys>
<!--   </command> -->
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>count</title>
    <short_description>count the objects in a list</short_description>

    <description>
This function counts the number of occurrences of the object E in the
list L.

<example>
/**/  L := [1,2,3,2,[2,3]];
/**/  count(L,2);
2

/**/  count(L,[2,3]);
1

/**/  count(L,"a");
0
</example>
    </description>

    <syntax>
count(L:LIST, E:OBJECT):INT
</syntax>

    <seealso>
      <see>distrib</see>
      <see>len</see>
    </seealso>

    <types>
      <type>list</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>CpuTime</title>
    <short_description>Counts cpu time</short_description>

    <syntax>
CpuTime():RAT
</syntax>

    <description>
This function returns a <tt>RAT</tt> whose value is the user CPU usage in
seconds since the start of the program (i.e. the amount of time the
processor has dedicated to your computation -- this may be rather less
than the real elapsed time if the computer is also busy with other 
tasks).  Use <ttref>DecimalStr</ttref> to have the time in a more easily
comprehensible form.

<example>
StartTime := CpuTime(); -- time in seconds since the start (a RAT)

-- .... long computation ....

EndTime := CpuTime();
PrintLn "Computation time: ",DecimalStr(EndTime - StartTime);
</example>
    </description>

    <seealso>
      <see>DecimalStr</see>
    </seealso>

    <types>
      <type>rat</type>
    </types>

    <keys>
      <key>cpu time</key>
      <key>timing</key>
      <key>set timer</key>
    </keys>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>CRT</title>
    <short_description>Chinese Remainder Theorem</short_description>

    <syntax>
CRT(R1:INT, M1:INT, R2:INT, M2:INT): RECORD[modulus:INT, residue:INT]
</syntax>

    <description>
This function combines two residue-modulus pairs <tt>(R1,M1)</tt> and <tt>(R2,M2)</tt>
using the Chinese Remainder Theorem to produce a single
residue-modulus pair <tt>(R,M)</tt> such that <tt>R = R1 mod M1</tt> and <tt>R = R2 mod M2</tt>,
and <tt>|R| &lt; M</tt>.  The moduli <tt>M1</tt> and <tt>M2</tt> must be coprime (hence <tt>M = M1*M2</tt>).

<example>
  CRT(2,3,4,5);
Record[modulus := 15, residue := -1]
</example>
    </description>

    <seealso>
      RatReconstructByContFrac
      RatReconstructByLattice
    </seealso>

    <types>
      <type>INT</type>
    </types>

    <keys>
      <key>chinese</key>
      <key>remaindering</key>
    </keys>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>CurrentRing</title>
    <short_description>the current ring</short_description>

    <description>
This is a top-level SYSTEM VARIABLE containing the current ring.
<par/>
NB in CoCoA-4 it used to be a function (namely <tt>CurrentRing()</tt>),
now it is a top-level <em>variable</em> which needs to be imported in
functions... but beware: this is to be considered BAD STYLE ;-)

<example>
/**/  Use R ::= QQ[x,y];
/**/  Use S ::= ZZ/(3)[t];
/**/  CurrentRing;
RingDistrMPolyClean(FFp(3), 1)

/**/  Use R;
/**/  CurrentRing;
RingDistrMPolyClean(QQ, 2)

  Define MyIndets1()
    TopLevel CurrentRing; -- importing a top-level (global) variable
    Return indets(CurrentRing);
  EndDefine;

  Define MyIndets2(val)
    Return indets(RingOf(val));  -- cleaner: depends only on the argument
  EndDefine;

/**/ MyIndets1();
[x, y]

/**/ MyIndets2(ideal(x));
[x, y]
</example>
    </description>

    <syntax>
CurrentRing
</syntax>

    <seealso>
      <see>RingOf</see>
      <see>TopLevel</see>
    </seealso>

    <types>
      <type>ring</type>
    </types>

      <keys>
        <key>system variable</key>
      </keys>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>CurrentTypes</title>
    <short_description>lists all data types</short_description>

    <description>
This function lists all CoCoA data types.

<example>
/**/  CurrentTypes();
[BOOL, ERROR, FUNCTION, IDEAL, INT, INTMAP, LIST, MAT, MATRIXROW, MODULE, OSTREAM, RAT, RATFUN, RECORD, RING, RINGELEM, RINGHOM, STRING, TYPE, MODULEELEM, VOID, ZMOD, TAGGED("$TopLevel.MyTag")]
</example>
    </description>

    <syntax>
CurrentTypes()
</syntax>

    <seealso>
      <see>Data Types</see>
      <see>type</see>
    </seealso>

    <types>
      <type>type</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>cyclotomic</title>
    <short_description>n-th cyclotomic polynomial</short_description>

    <syntax>
cyclotomic(n:INT, x:INDET):RINGELEM
</syntax>

    <description>
This function computes the n-th cyclotomic polynomial (in the indeterminate x).

<example>
/**/  Use QQ[z];
/**/  cyclotomic(4,z);
z^2 + 1
</example>
    </description>


    <seealso>
      <see>Data Types</see>
      <see>type</see>
    </seealso>

    <types>
      <type>ringelem</type>
      <type>int</type>
    </types>

  </command>

 </chapter_letter>
 <!-- ===  CHAPTER  =============================================== -->
 <chapter_letter>
   <title>D</title>

<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>dashes</title>
    <short_description>returns string of dashes</short_description>

    <description>
This function returns a string of dashes:

<example>
/**/  dashes(); 1+1;
-------------------------------
2
</example>
    </description>

    <syntax>
dashes()
</syntax>

    <seealso>
      <see>equals</see>
    </seealso>

    <types>
      <type>miscellaneous</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>date</title>
    <short_description>the date</short_description>

<syntax>
date() :INT
</syntax>
<description>
This function returns the date.
<par/>
Note that from version 5.0.4 the result is an INT and the date is in
the form YYYYMMDD.
See also <ttref>TimeOfDay</ttref>.

<example>
/**/  date();
20130530
</example>
</description>

<seealso>
  <see>TimeOfDay</see>
</seealso>

<types>
  <type>miscellaneous</type>
</types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>DecimalStr</title>
    <short_description>convert rational number to decimal string</short_description>

    <syntax>
DecimalStr(X:RAT):STRING
DecimalStr(X:RAT, NumDigits:INT):STRING
</syntax>

    <description>
This function computes a decimal approximation with NumDigits
decimal digits of a rational number (default value is 3) and converts
it into a string for printing.  If the returned string presents less
than NumDigits decimal digits, then the string represents the exact
value of the input.

<example>
/**/  DecimalStr(1/3);
0.333

/**/  DecimalStr(1/3, 60);
0.333333333333333333333333333333333333333333333333333333333333

/**/  DecimalStr(121/10);
12.1
</example>
    </description>

    <seealso>
      <see>FloatStr</see>
      <see>MantissaAndExponent</see>
    </seealso>

    <types>
      <type>rat</type>
      <type>string</type>
    </types>

    <keys>
    <key>printing rational numbers</key>
    </keys>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>define</title>
    <short_description>define a function</short_description>

    <description>
1. INTRODUCTION. This command adds the user-defined function F to the
library. The function F can be called in the following way:
<verbatim>
    F(E_1,...,E_n)
</verbatim>
where the <tt>E_i</tt>&apos;s are expressions.  The result of the evaluation of each
expression <tt>E_i</tt> is assigned to the respective formal parameter <tt>X_i</tt>, and
the command sequence C is executed.  If, during the execution of C, a
statement <tt>Return E</tt> is executed, then the result of the evaluation of
E is the return-value of the function F. If no <tt>Return</tt> command is
executed, or <tt>Return</tt> is executed without argument, then the
return-value is <tt>Null</tt>.

<example>
  Define square(X)
    Return X^2;
  EndDefine;

  square(5);
25
-------------------------------
</example>

2. SCOPE.  Every variable defined or modified by the command sequence
C is considered local to the function unless the variable is global or
relative to a <tt>ref</tt> parameter.  For the use of global variables, see
<ref>Global Memory</ref> or the example below.  See <tt>ref</tt> to learn about
calling a function <em>by reference</em>, i.e. so that the function can
change the value of an existing variable.

<example>
  Define Example_1(L)
    L := L + 5;
    Return L;
  EndDefine;
  L := 0;
  Example_1(L);
5
-------------------------------
  L;  -- L is unchanged despite the function call.
0
-------------------------------
  Define Example_2(L)  -- Example using a global variable.
    MEMORY.X := L + 3;
  EndDefine;
  Example_2(10);
  MEMORY.X;
13
-------------------------------
</example>

3. VARIABLE NUMBER OF PARAMETERS.  It is also possible to have a
variable number of parameters using the syntax
<verbatim>
    Define F(...) C EndDefine;
</verbatim>
In this case the special variable ARGV will contain the list of
the arguments passed to the function.
(The old statement, <tt>Help S;</tt> is obsolescent!)

<example>
  Define Sum(...)
    If len(ARGV) = 0 Then Return Null;  -- empty sum
    Else
      ans := 0;
      Foreach N In ARGV Do ans := ans+N EndForeach;
    EndIf;
    Return ans;
  EndDefine;
  Sum(1,2,3,4,5);
15
-------------------------------
  Sum();
Null
-------------------------------
</example>

4. SHORTCUT.  The form <tt>F(X_1,...,X_n) := E</tt> is discouraged and may be
discontinued in later versions of CoCoA. If is shorthand for
<tt>Define F(X_1,...X_n) Return E EndDefine;</tt>.

<example>
  F(X) := X^2;
  F(5);
25
-------------------------------
</example>

5. HELP.  Obsolescent: Inside a user-defined function, one may add the command:
<verbatim>
  Help S;
</verbatim>
where S is a string.  This is obsolescent!!
Then, when a user enters <tt>Help(<quotes>F</quotes>)</tt> where F is
the identifier for the function, the string, S, is printed.

<example>
  Define Test(N)
    Help "Usage: Test(N:INT):INT";
    Return N;
  EndDefine;
  Help("Test");
Usage: Test(N:INT):INT
-------------------------------
</example>

6. DEFINING RINGS INSIDE FUNCTIONS.  For information on this topic,
please see the section of the tutorial entitled, <ref>Rings Inside
User-Defined Functions</ref>
    </description>

    <syntax>
Define F(X_1,...,X_n) Help S:STRING; C EndDefine
F(X_1,...,X_n) := E   -- obsolescent!
Define F(...) Help S:STRING; C EndDefine

where F is an identifier, C is a sequence of commands, the X_i&apos;s are
formal parameters and E is an expression.  The third form, which
literally includes the string <tt>...</tt> is used for a variable number of
parameters.  The optional <tt>Help S</tt>, where S is a string, may be added
to provide help for the user.
</syntax>

    <seealso>
      <see>An Overview of CoCoA Programming</see>
      <see>Introduction to User-Defined Functions</see>
      <see>Memory Management</see>
      <see>return</see>
      <see>Rings Inside User-Defined Functions</see>
      <see>ref</see>
    </seealso>

    <types>
      <type>function</type>
      <type>programming</type>
    </types>

    <keys>
    <key>argv</key>
    <key>...</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>deg</title>
    <short_description>the standard degree of a polynomial or moduleelem</short_description>

    <description>
The first form of this function returns the standard degree of F
(see <ttref>wdeg</ttref> for the weighted degree).
The second form returns the exponent of the indeterminate X in F.
In either case, if F is a ModuleElem, the maximum of the degrees
of its components is returned.
<par/>
For the degree of a ring or quotient object, see <ttref>multiplicity</ttref>.

<example>
/**/  Use R ::= QQ[x,y,z];
/**/  deg(x*y^2+y);
3

/**/  deg(x*y^2+y, x);
1

/**/  Ws := RowMat([2,3,1]);
/**/  P := NewPolyRing(QQ, ["x","y","z"], CompleteToOrd(Ws), 1);
/**/  Use P;
/**/  deg(x*y^2+y);
3
/**/  wdeg(x*y^2+y);
[8]
/**/  deg(x*y^2+y, x);
1
/**/  wdeg(x*y^2+y, x);
2

/**/  P3 := NewFreeModule(P, 3);
/**/  deg(ModuleElem(P3, [x^2, x*y^3+y, x^2-y^5])); --***OBSOLETE MANUAL: WORK IN PROGRESS***
5
/**/  deg(ModuleElem(P3, [x^2, x*y^3+y, x^2-y^5]), x); --***OBSOLETE MANUAL: WORK IN PROGRESS***
2
</example>
    </description>

    <syntax>
deg(F:POLY):INT
deg(F:POLY, X:INDET):INT
deg(F:MODULEELEM):INT --***OBSOLETE MANUAL: WORK IN PROGRESS***
deg(F:MODULEELEM, X:INDET):INT --***OBSOLETE MANUAL: WORK IN PROGRESS***
</syntax>

    <seealso>
      <see>wdeg</see>
      <see>Weights Modifier</see>
    </seealso>

    <types>
      <type>polynomial</type>
      <type>ring</type>
      <type>moduleelem</type>
    </types>

    <keys>
    <key>degree</key>
    </keys>
  </command>
<!-- ===  COMMAND-rm delete =============================================== -->
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>den</title>
    <short_description>denominator</short_description>

    <description>
These function returns the denominator of the argument X.
If X is a RingElem in FractionField(R), then den(X) is a RingElem in R.
<par/>
NB In CoCoA 4 the numerator and denominator could also be found
using <tt>.Num</tt> and <tt>.Den</tt>, but this fragile syntax is no
longer supported.

<example>
/**/  den(3);
1

/**/  P ::= QQ[x,y];
/**/  F := NewFractionField(P);
/**/  Use F;
/**/  den(x/(x+y));
x +y
/**/ RingOf(It);
RingDistrMPolyClean(QQ, 2)
</example>
    </description>

    <syntax>
den(N:INT or RAT):INT
den(N:POLY or RATFUN):POLY
</syntax>

    <seealso>
      <see>Numerators and Denominators for Rational Functions</see>
      <see>Numerators and Denominators for Rational Numbers</see>
      <see>num</see>
    </seealso>

    <types>
      <type>integer</type>
      <type>polynomial</type>
      <type>rat</type>
      <type>ratfun</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>DensePoly</title>
    <short_description>the sum of all power-products of a given degree</short_description>

    <description>
This function returns the sum of all power-products of (standard) degree N.

<example>
/**/  Use R ::= QQ[x,y];
/**/  DensePoly(R,3);
x^3 + x^2*y + x*y^2 + y^3

/**/  Ws := RowMat([2,3]);
/**/  P := NewPolyRing(QQ, ["x","y"], CompleteToOrd(Ws), 1);
/**/  Use P;
/**/  DensePoly(P,1);  // NB standard degree!!
y +x
</example>
    </description>

    <syntax>
DensePoly(R:RING, N:INT):POLY
</syntax>

    <seealso>
      <see>randomize</see>
      <see>randomized</see>
    </seealso>

    <types>
      <type>polynomial</type>
    </types>

  </command>
<!--  ===  COMMAND  =============================================== -->
<command>
  <title>Depth</title>
  <short_description>Depth of a module</short_description>
<description>
***** NOT YET IMPLEMENTED *****
<par/>
This function calculates the depth of M in the ideal I, i.e. the
length of a maximal I-regular sequence in M. In the second form,
where I is not specified, it assumes that I is the maximal ideal
generated by the indeterminates, i.e. <tt>ideal(Indets())</tt>.
<par />
Note that if M is homogeneous and I is the maximal ideal, then it uses
the Auslander-Buchsbaum formula <tt>depth_I(M) = N - pd(M)</tt>
where N is the number of indeterminates and pd is the projective
dimension, otherwise it returns <tt>min{N | Ext^N(R/I, M)&lt;>0}</tt>
using the function <ttref>Ext</ttref>.
<example>
  Use R ::= QQ[x,y,z];
  Depth(R/ideal(0)); -- the (x,y,z)-depth of the entire ring is 3
3
-------------------------------
  I := ideal(x^5,y^3,z^2);
  -- one can check that it is zerodimensional and CM this way
  dim(R/I);
0
-------------------------------
  Depth(R/I);
0
-------------------------------

  N := Module([x^2,y], [x+z,0]);
  Depth(I, R^2/N);  --- a max reg sequence would be (z^2,y^3)
2
-------------------------------
  Use R ::= QQ[x,y,z,t,u,v];
  -- Cauchy-Riemann system in three complex vars!
  N := Module([x,y], [-y,x], [z,t], [-t,z], [u,v], [-v,u]);
  --- is it CM?
  Depth(R^2/N);
3
-------------------------------
  dim(R^2/N);
3
-------------------------------
  --- yes!

  M := Module([x,y,z],[t,v,u]);
  Res(R^3/M);
0 --> R^2(-1) --> R^3
-------------------------------
  Depth(R^3/M); -- using Auslander Buchsbaum 6-1=5
5
-------------------------------
  dim(R^3/M);  -- not CM
6
-------------------------------
  Depth(ideal(x,y,z,t), R^2/N);
2
-------------------------------
</example>
  </description>
  <syntax>
Depth(I: IDEAL, M: Tagged("Quotient")): INT
Depth(M: Tagged("Quotient"): INT
</syntax>

  <seealso>
    <see>res</see>
    <see>Ext</see>
  </seealso>

  <types>
    <type>ideal</type>
    <type>module</type>
  </types>

</command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>deriv</title>
    <short_description>the derivative of a polynomial or rational function</short_description>

<syntax>
deriv(F:POLY, X:INDET):POLY
deriv(F:RATFUN, X:INDET):RATFUN
</syntax>

<description>
This function returns the derivative of F with respect to the
indeterminate X.

<example>
/**/  Use R ::= QQ[x,y];
/**/  deriv(x*y^2, x);
y^2

  Define Jac(F)  --&gt; The Jacobian matrix for a polynomial.
    Return matrix([[deriv(F, X) | X In Indets(RingOf(F))]]);
  EndDefine;

/**/  Jac(x*y^2);
matrix( /*RingDistrMPolyClean(QQ, 2)*/
 [[y^2, 2*x*y]])

/**/  FrF := NewFractionField(R);
/**/  Use FrF;
/**/  deriv((x*y^2)/(x-1), x);
(-y^2)/(x^2 -2*x +1)
</example>
</description>

<seealso>
  <see>jacobian</see>
</seealso>

<types>
  <type>ratfun</type>
  <type>polynomial</type>
</types>

<keys>
  <key>der</key>
  <key>derivative</key>
  <key>differentiate</key>
</keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>DerivationAction</title>
    <short_description>Action of a derivation</short_description>

    <syntax>
DerivationAction(D:POLY, P:POLY)
</syntax>

    <description>
Given the polynomial <tt>P</tt> and the derivation <tt>D</tt>, this function
computes the action of <tt>D</tt> on <tt>P</tt>.
<par/>
For the sake of simplicity Forms/Polynomials and Derivations live in
the same ring, the distinction between them is purely formal.

<example>
/**/  Use R ::= QQ[x,y,z];
/**/  DerivationAction(x*y*z, x^3+x*y*z);
1
</example>
    </description>

    <seealso>
      <see>InverseSystem</see>
      <see>PerpIdealOfForm</see>
    </seealso>

    <types>
      <type>poly</type>
    </types>

    <keys>
    <key>carlini</key>
    </keys>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>Describe</title>
    <short_description>information about an object</short_description>

    <syntax>
describe X:OBJECT
</syntax>

    <description>
This command gives some information about the object <tt>X</tt>.  For
instance, if <tt>X</tt> is a CoCoA-5 function, it prints out the
definition, and if <tt>X</tt> is a package name (prefixed with a dollar
sign), it prints out the exported names.

<example>
/**/  Define succ(N) Return N+1 EndDefine;
/**/  describe succ;
Define succ(N) Return N+1 EndDefine

/**/  describe $chebyshev;
The package $chebyshev exports the following names:
* ChebyshevPoly
* ChebyshevPoly2
</example>
    </description>

    <seealso>
      <see>Other Help</see>
    </seealso>

    <types>
      <type>print</type>
      <type>type</type>
      <type>miscellaneous</type>
    </types>

  </command>
<!-- ===  COMMAND-rm Destroy  =============================================== -->
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>det</title>
    <short_description>the determinant of a matrix</short_description>

    <description>
This function returns the determinant of the matrix M.  The resulting
type depends on the types of the entries of the matrix.

<example>
/**/  Use R ::= QQ[x];
/**/  M := mat(R,[[x,x^2], [x,x^3]]);
/**/  det(M);
x^4 -x^3

/**/ det(mat(QQ,[[1,2], [0,5]]));
5
</example>
    </description>

    <syntax>
det(M:MAT)

the resulting type depends on the entries of the matrix.
</syntax>

    <seealso>
      <see>minors</see>
    </seealso>

    <types>
      <type>matrix</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>DF</title>
    <short_description>the degree form of a polynomial</short_description>

    <description>
Same as <ttref>LF</ttref>, but does not throw an error if the argument
is zero or if the <ttref>GradingDim</ttref> of the polynomial ring is 0.
As defined in Kreuzer-Robbiano book II (Definition 4.2.8).

<example>
/**/  Use R ::= QQ[x,y];
/**/  DF(x^2 -x*y +2*x -1);
x^2 -x*y

/**/  Use R ::= QQ[x,y], Lex;  -- GradingDim is 0: everything is homogeneous
/**/  DF(x^2 -x*y +2*x -1);
x^2 -x*y +2*x -1

/**/ P := NewPolyRing(QQ, IndetSymbols(R), mat([[1,4],[1,0]]), 1);
/**/ Use P;
/**/ DF(x^2 -x*y);
-x*y
/**/ DF(x^4 +x^2 -y);
 x^4 -y
</example>
    </description>

    <syntax>
DF(F:RINGELEM): RINGELEM
</syntax>

    <keys>
      <key>degree-form</key>
      <key>degreeform</key>
      <key>degree form</key>
    </keys>

    <seealso>
      <see>LF</see>
    </seealso>

    <types>
      <type>polynomial</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>DiagMat</title>
    <short_description>matrix with given diagonal</short_description>

    <description>
This function returns the diagonal matrix whose diagonal are the
elements of the list L.

<example>
/**/  DiagMat([3,4,5]);
matrix(
[
  [3, 0, 0],
  [0, 4, 0],
  [0, 0, 5]
])

/**/ DiagMat(QQ,[5,6,7]);
matrix(
[
  [5, 0, 0],
  [0, 6, 0],
  [0, 0, 7]
])

-- fast implementation for high powers of a diagonal matrix
  Define PowerDiag(M, Exp)
    If not(IsDiagonal(M)) Then
      error("PowerDiag: matrix must be diagonal");
    EndIf;
    Return DiagMat([ M[I, I]^Exp | I In 1..NumRows(M) ]);
  EndDefine;

/**/ PowerDiag(IdentityMat(QQ,3), 200000000);
matrix( /*QQ*/
 [[1, 0, 0],
  [0, 1, 0],
  [0, 0, 1]]
 )
</example>
    </description>

    <syntax>
DiagMat(L:LIST):MAT
DiagMat(R:RING, L:LIST):MAT
</syntax>

    <keys>
      <key>PowerDiag</key>
    </keys>

    <seealso>
      <see>BlockMat</see>
      <see>IsDiagonal</see>
      <see>ColMat</see>
      <see>RowMat</see>
    </seealso>

    <types>
      <type>matrix</type>
    </types>

    <keys>
    <key>diagmat</key>
    <key>power</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>diff</title>
    <short_description>returns the difference between two lists</short_description>

    <description>
This function returns the list obtained by removing all the elements
of M from L.

<example>
/**/  L := [1,2,3,2,[2,3]];
/**/  M := [1,2];
/**/  diff(L, M);
[3, [2, 3]]
</example>
    </description>

    <syntax>
diff(L:LIST, M:LIST):LIST
</syntax>

    <seealso>
      <see>insert</see>
      <see>remove</see>
    </seealso>

    <types>
      <type>list</type>
    </types>

    <keys>
    <key>difference</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>dim</title>
    <short_description>the dimension of a ring or quotient object</short_description>

    <description>
This function computes the dimension of R.
<par/>
The coefficient ring must be a field.

<example>
/**/ Use R ::= QQ[x,y,z];
/**/ dim(R/ideal(x));
2

/**/ dim(R/ideal(y^2-x, x*z-y^3));
1
</example>
    </description>

    <syntax>
dim(R:RING or TAGGED("Quotient")):INT
</syntax>

    <types>
      <type>groebner</type>
      <type>groebner-basic</type>
      <type>hilbert</type>
      <type>quotient</type>
      <type>ring</type>
    </types>

    <keys>
    <key>dimension</key>
    <key>bigatti</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>discriminant</title>
    <short_description>the discriminant of a polynomial</short_description>

    <description>
This function computes the discriminant of a polynomial F (with
respect to a given indeterminate X, if the polynomial is multivariate).
If the polynomial is univariate then there is no need to specify
which indeterminate to use.
<par/>
The discriminant is defined as
<verbatim>
(-1)^(N*(N-1)/2)*det(M)/M[1,1]
</verbatim>
where <code>M := Sylvester(F, der(F,X), X)</code>
and  <code>N := deg(F, X)</code>.

<example>
/**/ Use R ::= QQ[x,y];
/**/ discriminant(x^2+3*y^2, x);
-12*y^2

/**/ discriminant(x^2+3*y^2, y);
-12*x^2

/**/ discriminant((x+1)^20+2);
54975581388800000000000000000000
</example>
    </description>

    <syntax>
discriminant(F:POLY):POLY
discriminant(F:POLY, X:INDET):POLY
</syntax>

    <seealso>
      <see>resultant</see>
    </seealso>

    <types>
      <type>polynomial</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>distrib</title>
    <short_description>the distribution of objects in a list</short_description>

    <description>
For each object E of a list L, let N(E) be the number of times E
occurs as a component of L.  Then Distrib(L) returns the list whose
components are [E, N(E)].

<example>
/**/  distrib(["b","a","b",4,4,[1,2]]);
[["b", 2], ["a", 1], [4, 2], [[1, 2], 1]]
</example>
    </description>

    <syntax>
distrib(L:LIST):LIST
</syntax>

    <seealso>
      <see>count</see>
    </seealso>

    <types>
      <type>list</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>div</title>
    <short_description>quotient for integers</short_description>

    <syntax>
div(N:INT, D:INT):INT
</syntax>

    <description>
We define the quotient <tt>Q</tt> and remainder <tt>R</tt> to be integers which
satisfy <formula>N = Q*D + R</formula> with <formula>0 <less_eq/> R &lt; |D|</formula>.
Then <tt>div(N, D)</tt> returns <tt>Q</tt> while <tt>mod(N, D)</tt> returns <tt>R</tt>.
<par/>
NOTE: To perform the division algorithm on a polynomial or vector, use
<ttref>NR</ttref> (normal remainder) to find the remainder, or <ttref>DivAlg</ttref> to get both
the quotients and the remainder.  To determine if a polynomial is in a
given ideal or a vector is in a given module, use <ttref>NF</ttref> or <ttref>IsIn</ttref>, and
to find a representation in terms of the generators use <ttref>GenRepr</ttref>.

<example>
/**/ div(10,3);
3

/**/ mod(10,3);
1
</example>
    </description>

    <seealso>
      <see>DivAlg</see>
      <see>GenRepr</see>
      <see>NF</see>
      <see>NR</see>
      <see>mod</see>
    </seealso>

    <types>
      <type>integer</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>DivAlg</title>
  <short_description>division algorithm</short_description>
  
<syntax>
DivAlg(X:POLY, L:LIST of POLY): RECORD
DivAlg(X:MODULEELEM, L:LIST of MODULEELEM): RECORD
</syntax>
<description>
This function performs the division algorithm on X with respect to L.
It returns a record with two fields: <tt>Quotients</tt> holding a list of
polynomials, and <tt>Remainder</tt> holding the remainder of X upon division
by L.
<example>
/**/  Use R ::= QQ[x,y,z];
/**/  F := x^2*y +x*y^2 +y^2;
/**/  L := [x*y-1, y^2-1];
/**/  DivAlg(F, L);
Record[quotients := [x +y, 1], remainder := x +y +1]

/**/  D := It;
/**/  D.quotients;
[x +y, 1]
/**/  D.remainder;
x +y + 1
/**/  ScalarProduct(D.quotients, L) + D.remainder = F;
true

/**/  R2 := NewFreeModule(R,2);
/**/  V := ModuleElem(R2, [x^2+y^2+z^2, x*y*z]);
/**/  L := gens(SubmoduleRows(R2, mat([[x,y], [y,z], [z,x]])));
/**/  D := DivAlg(V, L);
/**/  indent(D);
Record[
  quotients := [x, -z^2 +y +z, y*z -y],
  remainder := [z^2, z^3 -y*z -z^2]
]
/**/ sum([D.quotients[i]*L[i] | i in 1..len(L)]) + D.remainder;
[x^2 +y^2 +z^2, x*y*z]
</example>
</description>

<seealso>
  <see>div</see>
  <see>mod</see>
  <see>GenRepr</see>
  <see>NF</see>
  <see>NR</see>
</seealso>

<types>
  <type>polynomial</type>
  <type>record</type>
  <type>moduleelem</type>
</types>

<keys>
  <key>division algorithm</key>
</keys>
</command>

</chapter_letter>
<!-- ===  CHAPTER  =============================================== -->
<chapter_letter>
  <title>E</title>
  
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>E_</title>
  <short_description>vector of the canonical basis</short_description>

<description>
OBSOLETE: essentially replaced by <ttref>gens</ttref> of a FreeModule.
<example>
/**/  Use R ::= QQ[x,y,z];
/**/  R5 := NewFreeModule(R,5);
/**/  e := gens(R5);
/**/  e[2];
[0, 1, 0, 0, 0]
</example>
</description>

<seealso>
  <see>gens</see>
  <see>GensAsRows</see>
  <see>GensAsCols</see>
</seealso>

<types>
  <type>moduleelem</type>
  <type>module</type>
</types>

<keys>
  <key>canonical basis</key>
  <key>canonicalbasis</key>
</keys>
</command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>eigenvectors</title>
    <short_description>eigenvalues and eigenvectors of a matrix</short_description>

    <description>
<par/>
<tt>M</tt> must be a matrix of numbers, and <tt>X</tt> an indeterminate.
<par/>
This function determines the eigenvalues of <tt>M</tt>, and for each eigenvalue
gives a basis of the corresponding eigenspace -- note that the basis is
probably not orthogonal.  For irrational eigenvalues, the minimal
polynomial of the eigenvalue is given (as a polynomial in <tt>X</tt>), along with
the eigenvectors expressed in terms of a root of the minimal polynomial
(represented as <tt>X</tt>).

<example>
/**/  Use R ::= QQ[x];
/**/  M := mat([[1,2,3],[4,5,6],[7,8,9]]);
/**/  eigenvectors(M, x);
[Record[MinPoly := x, eigenspace := matrix(QQ,
 [[-1],
  [2],
  [-1]])], 
Record[MinPoly := x^2 -15*x -18,
eigenspace := [[1, (1/8)*x +1/4, (1/4)*x -1/2]]]
]

/**/  M := mat([[0,2,0,0],[1,0,0,0],[0,0,0,2],[0,0,1,0]]);
  eigenvectors(M, x); -- two irrational eigenvalues, each with eigenspace of dimension 2
[Record[MinPoly := x^2 -2, eigenspace := [[1, (1/2)*x, 0, 0], [0, 0, 1, (1/2)*x]]]]
</example>
    </description>

    <syntax>
eigenvectors(M:MAT, X:INDET):LIST of RECORD
</syntax>

    <types>
      <type>matrix</type>
    </types>

    <keys>
    <key>eigenvalues</key>
    <key>eigenspace</key>
    <key>abbott</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>elim</title>
  <short_description>eliminate variables</short_description>

<syntax>
elim(X: RINGELEM, M:IDEAL):IDEAL
elim(L:LIST, M:IDEAL):IDEAL
elim(X: RINGELEM, M:MODULE):MODULE
elim(L:LIST, M:MODULE):MODULE

where X is an indeterminate, L a list of indeterminates.
</syntax>

<description>
This function returns the ideal or module obtained by eliminating the
indeterminates X from M.  The coefficient ring needs to be a field.
<par/>
As opposed to this function, there is also the <em>modifier</em>, <tt>elim</tt>,
used when constructing a ring (see <ttref>Orderings</ttref> and
<ref>Predefined Term-Orderings</ref>).

<example>
/**/  Use R ::= QQ[t,x,y,z];
/**/  E := elim(t, ideal(t^15+t^6+t-x, t^5-y, t^3-z));
/**/ indent(E);
ideal(
  -z^5 +y^3,
  -y^4 -y*z^2 +x*y -z^2,
  -x*y^3*z -y^2*z^3 -x*z^3 +x^2*z -y^2 -y,
  -y^2*z^4 -x^2*y^3 -x*y^2*z^2 -y*z^4 -x^2*z^2 +x^3 -y^2*z -2*y*z -z,
  y^3*z^3 -x*z^3 +y^3 +y^2
)

/**/  Use R ::= QQ[t,s,x,y,z,w];
/**/  t..x;
[t, s, x]

/**/  elim(t..x, ideal(t-x^2*z*w, x^2-t, y^2*t-w)); -- Note the use of t..x.
ideal(-z*w^2 + w)

/**/  Use R ::= QQ[t[1..2], x[1..4]];
/**/  I := ideal(x[1]-t[1]^4, x[2]-t[1]^2*t[2], x[3]-t[1]*t[2]^3, x[4]-t[2]^4);
/**/  elim(indets(R,"t"), I);
ideal(x[2]^4 -x[1]^2*x[4], -x[3]^4 +x[1]*x[4]^3)
</example>
</description>

<seealso>
  <see>Orderings</see>
  <see>Predefined Term-Orderings</see>
</seealso>

<types>
  <type>groebner</type>
  <type>groebner-basic</type>
  <type>ideal</type>
  <type>module</type>
</types>

<keys>
  <key>eliminate</key>
  <key>elimination</key>
</keys>
</command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>ElimMat</title>
  <short_description>matrix for elimination ordering</short_description>

<syntax>
ElimMat(N:INT, ElimInd:LIST): MAT
ElimMat(W:MAT, ElimInd:LIST): MAT
</syntax>
<description>
This function returns an <tt>NxN</tt> matrix for a term ordering
eliminating the indeterminates with indices in <tt>ElimInd</tt>.
If a weight matrix is given, then these weights are included after
the first elimination row.

<example>
/**/  ElimMat(3, [2,3]);
matrix( /*QQ*/
 [[0, 1, 1],
  [1, 1, 1],
  [0, 0, -1]]
 )

/**/  ElimMat(mat([[1,5,0]]), [2,3]);
matrix( /*QQ*/
 [[0, 1, 1],
  [1, 5, 0],
  [0, 0, -1]]
 )
</example>
</description>

<seealso>
  <see>elim</see>
  <see>HomogElimMat</see>
</seealso>

<types>
  <type>matrix</type>
</types>

<keys>
  <key>elimination ordering</key>
  <key>blockordering</key>
  <key>block ordering</key>
</keys>
</command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>EqSet</title>
    <short_description>checks if the set of elements in two lists are equal</short_description>

    <description>
This function returns True if L equals M as sets, otherwise it
returns False.

<example>
/**/  L := [1,2,2];
/**/  M := [2,1];
/**/  EqSet(L, M);
true
</example>
    </description>

    <syntax>
EqSet(L:LIST, M:LIST):BOOL
</syntax>

    <seealso>
      <see>intersect</see>
      <see>IntersectionList</see>
      <see>IsSubset</see>
    </seealso>

    <types>
      <type>boolean</type>
      <type>list</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>equals</title>
    <short_description>returns a string of equal signs</short_description>

    <description>
This function returns a string of equal signs:

<example>
/**/  equals();
===============================
</example>
    </description>

    <syntax>
equals()
</syntax>

    <seealso>
      <see>dashes</see>
    </seealso>

    <types>
      <type>miscellaneous</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>EquiIsoDec</title>
    <short_description>equidimensional isoradical decomposition</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This function computes an equidimensional isoradical decomposition of
I, i.e. a list of unmixed ideals <formula>I_1,...,I_k</formula> such that the radical of I
is the intersection of the radicals of <formula>I_1,...,I_k</formula>. Redundancies are
possible.
<par/>
NOTE: at the moment, this implementation works only if the coefficient
ring is the rationals or has large enough characteristic.

<example>
  Use R ::= QQ[x,y,z];
  I := intersect(ideal(x-1,y-1,z-1), ideal(x-2,y-2)^2, ideal(x)^3);
  H := EquiIsoDec(I);
  H;
[ideal(x), ideal(z - 1, y - 1, x - 1), ideal(xy - y^2 - 2x + 2y, x^2 -
y^2 - 4x + 4y, y^2z - y^2 - 4yz + 4y + 4z - 4, y^3 - 5y^2 + 8y - 4, x
- 2)]
-------------------------------
  T := [radical(J)|J In H];
  S := IntersectionList(T);
  radical(I) = S;
True
-------------------------------
</example>
    </description>

    <syntax>
EquiIsoDec(I:IDEAL):LIST of IDEAL
</syntax>

    <seealso>
      <see>PrimaryDecomposition</see>
      <see>radical</see>
      <see>RadicalOfUnmixed</see>
    </seealso>

    <types>
      <type>groebner</type>
      <type>ideal</type>
    </types>

    <keys>
    <key>equidimensional</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>error</title>
    <short_description>throw an error message</short_description>

    <description>
This function throws an error containing the given message.
For backward compatibility the function may also be called using
the name <tt>Error</tt>

<example>
/**/ Define T(N)
/**/   If type(N) &lt;&gt; INT Then error("Argument must be an integer.") EndIf;
/**/   Return mod(N,5);
/**/ EndDefine;
/**/ T(1/3);

ERROR: Argument must be an integer.
    If type(N) &lt;&gt; INT Then error("Argument must be an integer.") EndIf;
                           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
CONTEXT: function T (previously defined at the prompt)
 called at top-level

/**/  T(7);
2
</example>
    </description>

    <syntax>
error(S:STRING):ERROR
</syntax>

    <seealso>
      <see>try</see>
      <see>GetErrMesg</see>
    </seealso>

    <types>
      <type>error</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>eval</title>
    <short_description>substitute numbers or polynomials for indeterminates</short_description>

    <description>
This function substitutes <tt>L[I]</tt> for <tt>indet(I)</tt> in the
expression E which must be of type POLY, RATFUN, MODULEELEM, LIST, or MAT,
and defined in the current ring.
For more general substitutions use <ttref>subst</ttref>.
<par/>
If <tt>len(L)</tt> is different from <tt>NumIndets()</tt> then only
the first N substitutions are performed, where N is the minumum of the
two values.

<example>
/**/  Use QQ[x,y];
/**/  eval(x^2+y, [2, 3]);
7

/**/  eval(x^2+y, [2]);
y +4

/**/  F := x*(x-1)*(x-2)*y*(y-1)*(y-2)/36;
/**/  P := [1/2, -2/3];
/**/  eval(F, P);
-5/162

/**/  eval([x+y,x-y], [2,1]);
[3, 1]

/**/  eval([x+y,x-y], [x^2,y^2]);
[x^2 + y^2, x^2 - y^2]

/**/  eval([x+y,x-y], [y]);
[2*y, 0]
</example>
    </description>

    <syntax>
eval(E:POLY/RATFUN/MODULEELEM/LIST/MAT, L:LIST):OBJECT
</syntax>

    <seealso>
      <see>Evaluation of Polynomials</see>
      <see>image</see>
      <see>subst</see>
      <see>Substitutions</see>
    </seealso>

    <types>
      <type>polynomial</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>EvalHilbertFn</title>
    <short_description>evaluate the Hilbert function</short_description>

    <description>
This function evaluates the Hilbert function H at N.  If H is the
Hilbert function of a quotient R/I, then the value returned is the
same as that returned by <tt>hilbert(R/I, N)</tt> but time is saved since the
Hilbert function does not need to be recalculated at each call.

<example>
/**/  Use R ::= QQ[w,x,y,z];
/**/  I := ideal(z^2-x*y, x*z^2+w^3);
/**/  H := Hilbert(R/I);
/**/  H;
H(0) = 1
H(1) = 4
H(t) = 6t - 3   for t &gt;= 2

/**/  EvalHilbertFn(H,1);
4
/**/  EvalHilbertFn(H,2);
9
</example>
    </description>

    <syntax>
EvalHilbertFn(H:TAGGED("$hp.Hilbert"), N:INT):INT
</syntax>

    <seealso>
      <see>hilbert</see>
      <see>HilbertFn</see>
      <see>HilbertPoly</see>
    </seealso>

    <types>
      <type>hilbert</type>
      <type>integer</type>
    </types>

    <keys>
    <key>bigatti</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
 <title>Ext</title>
  <short_description>presentation Ext modules as quotients of free modules</short_description>
 <description>
***** NOT YET IMPLEMENTED *****
<par/>
  In the first form the function computes the I-th Ext module of M and N.
It returns a presentation of <formula>Ext^I_R(M, N)</formula> as a quotient of a free module.
  <par />
IMPORTANT: the only exception to the type of M or N (or even of the
output) is when they are either a zero module or a free module.
In these cases their type is indeed MOD. 
  <par />
It computes Ext via a presentation of the quotient of the two modules
  <formula>Ker(Phi*_I)</formula>
  and
  <formula>Im(Phi*_{I-1})</formula>, where
  <par />
  -   <formula>Phi_I</formula>   is the I-th map in the free resolution of M
  <par />
  -   <formula>Phi*_I</formula>   is the map <formula>Hom(Phi_I, N)</formula>
  in the dual of the free resolution.
  <par />
Main differences with the previous version include:
  <par />
- SHIFTS have been removed, consequently  only standard homogeneous
  modules and quotients are supported
  <par />
- as a consequence of 1), the type <tt>Tagged(<quotes>Shifted</quotes>)</tt> has been
  removed. Ext will just be a <tt>Tagged(<quotes>Quotient</quotes>)</tt>
  <par />
- The former functions Presentation(), HomPresentation() and
  KerPresentation() have been removed
  <par />
- The algorithm uses Res() to compute the maps needed, and not
  SyzOfGens anylonger, believed to cause troubles
  <par />
- The function <tt>Ext</tt> always has THREE variables, see syntax...
  <par />

In the second form the variable I is a LIST of nonnegative
integers. In this case the function Ext prints all the Ext modules
corresponding to the integers in I.
The output is of special type <tt>Tagged(<quotes>$ext.ExtList</quotes>)</tt> which is basically
just the list of pairs  <formula>{(J, Ext^J(M, N)) | J in I}</formula> in
which the first element is an integer of I and the second element is
the correpsonding Ext module.
  <par />
VERY IMPORTANT: CoCoA cannot accept  the ring R as one of the inputs,
 so if you want to calculate the module <formula>Ext^I_R(M, R)</formula>
 you need to type something like
  <par />
<tt>Ext(I, M, ideal(1));</tt>
  <par />
or
  <par />
<tt>Ext(I, M, R^1);</tt>
  <par />
or
  <par />
<tt>Ext(I, M, R/ideal(0));</tt>
  <par />
NOTE: The input is pretty flexible in terms of what you can use for M
 and N. For example they can be zero modules or free modules. See some
 examples below.

<example>
  Use R ::= QQ[x,y,z];
  I := ideal(x^5, y^3, z^2);
  ideal(0) : (I);
ideal(0)
-------------------------------
  $hom.Hom(R^1/Module(I), R^1);   -- from Hom package
Module([[0]])
-------------------------------
  Ext(0, R/I, R^1);   --- all those things should be isomorphic
Module([[0]])
-------------------------------
  Ext(0..4, R/I, R/ideal(0)); -- another way to define the ring R as a quotient
Ext^0 = Module([[0]])

Ext^1 = Module([[0]])

Ext^2 = Module([[0]])

Ext^3 = R^1/Module([[x^5], [y^3], [z^2]])

Ext^4 = Module([[0]])

-------------------------------
  N := Module([x^2,y], [x+z,0]);
  Ext(0..4, R/I, R^2/N);
Ext^0 = Module([[0]])

Ext^1 = Module([[0]])

Ext^2 = R^2/Module([[0, x + z], [y, 0], [0, z^2], [z^2, 0], [0, y^3], [x^5, 0]])

Ext^3 = R^2/Module([[x + z, 0], [0, z^2], [z^2, 0], [y^3, 0], [0, x^5], [0, y]])

Ext^4 = Module([[0]])

-------------------------------
</example>

Since version 4.7.3 the output modules are presented minimally.
  </description>
  <syntax>
Ext(I:INT, M:TAGGED("Quotient"), Q:TAGGED("Quotient")): TAGGED("Quotient")
Ext(I:LIST, M:TAGGED("Quotient"), Q:TAGGED("Quotient")): TAGGED("$ext.ExtList")
</syntax>
  <seealso>
    <see>res</see>
    <see>Depth</see>
    <see>MinimalPresentation</see>
  </seealso>

  <types>
    <type>ideal</type>
    <type>module</type>
    <type>quotient</type>
  </types>

    <keys>
  <key>damiano</key>
    </keys>
  </command>

 </chapter_letter>
 <!-- ===  CHAPTER  =============================================== -->
 <chapter_letter>
   <title>F</title>

<!-- ===  COMMAND  =============================================== -->
<command>
  <title>factor</title>
  <short_description>factor a polynomial</short_description>
  
<syntax>
factor(F:POLY):RECORD[factors, multiplicities, RemainingFactor]
</syntax>

<description>
This function factorizes a polynomial in its ring of definition.
Multivariate factorization is not yet supported over finite fields.
(For information about the algorithm, consult <ref>Pointers to the
Literature</ref>.)  To factorize an integer use <ttref>SmoothFactor</ttref>.
<par/>
The function returns a list of the form <tt>[[F_1, N_1],...,[F_r, N_r]]</tt>
where <tt>F_1^N_1 ... F_r^N_r = F</tt> and the <tt>F_i</tt> are
irreducible in the polynomial ring of <tt>F</tt>.
<par/>
Note: in older versions of CoCoA-5 the field names were <tt>Factors</tt>
and <tt>Exponents</tt>.

<example>
/**/  Use R ::= QQ[x,y];
/**/  F := *** x^12 - 37x^11 + 608x^10 - 5852x^9 + 36642x^8 - 156786x^7
               + 468752x^6 - 984128x^5 + 1437157x^4 - 1422337x^3
	       + 905880x^2 - 333900x + 54000***;
/**/  F := factor(F);
/**/  indent(Fs);
Record[
  factors := [x -2, x -4, x -6, x -3, x -5, x -1],
  multiplicities := [1, 1, 1, 2, 3, 4],
  RemainingFactor := 1
]
/**/  G := product([Fs.factors[i]^Fs.multiplicities[i]
                    | i In 1..len(Fs.factors)]);
/**/  F = G * Fs.RemainingFactor;
true

/**/  factor((8*x^2 +16*x +8)/27);
  -- the "content" appears as RemainingFactor;
  -- it is not factorized into prime factors.
Record[factors := [x +1], multiplicities := [2], RemainingFactor := 8/27]

/**/  F := (x+y)^2*(x^2*y+y^2*x+3);    -- multivariate factorization
/**/  F;
x^4*y + 3*x^3*y^2 + 3*x^2*y^3 + x*y^4 + 3*x^2 + 6*x*y + 3*y^2
/**/  indent(factor(F));
Record[
  factors := [x^2*y +x*y^2 +3, x +y],
  multiplicities := [1, 2],
  RemainingFactor := 1
]

/**/  Use ZZ/(37)[x];
/**/  indent(factor(x^6-1));
Record[
  factors := [x +1, x +11, x -11, x +10, x -1, x -10],
  multiplicities := [1, 1, 1, 1, 1, 1],
  RemainingFactor := 1
]

/**/  factor(2*x^2-4); -- over a finite field the factors are made monic;
                       -- leading coeff appears as "content" if it is not 1.
Record[factors := [x^2 -2], multiplicities := [1], RemainingFactor := 2]
---------------------------------
</example>
</description>

<seealso>
  <see>SmoothFactor</see>
  <see>SqfreeFactor</see>
  <see>ContentFreeFactor</see>
</seealso>

<types>
  <type>polynomial</type>
</types>

<keys>
  <key>factors</key>
  <key>factorise</key>
  <key>factorisation</key>
  <key>factorize</key>
  <key>factorization</key>
  <key>abbott</key>
</keys>
</command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>factorial</title>
    <short_description>factorial function</short_description>

    <description>
This function returns N factorial.

<example>
/**/  factorial(5);
120

/**/  factorial(100);
9332621544394415268169923885626670049071596826438162146859
2963895217599993229915608941463976156518286253697920827223
758251185210916864000000000000000000000000
</example>
    </description>

    <syntax>
factorial(N:INT):INT

where N is a non-negative integer.
</syntax>

    <seealso>
      <see>binomial</see>
    </seealso>

    <types>
      <type>integer</type>
    </types>

    <keys>
  <key>factorial</key>
    </keys>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>FactorMultiplicity</title>
    <short_description>multiplicity of a factor of an integer</short_description>

    <description>
This function counts how many times a given factor divides a given
integer. Obviously Fac must not be -1, 0, or 1, and N must not be zero.

<example>
/**/  FactorMultiplicity(20, 2);
2

/**/  FactorMultiplicity(20, 10);
1

/**/  FactorMultiplicity(20, 7);
0
</example>
    </description>

    <syntax>
FactorMultiplicity(N:INT, Fac:INT):INT
</syntax>

    <types>
      <type>int</type>
    </types>

    <keys>
    <key>integer factor order</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>FGLM5</title>
    <short_description>perform a FGLM Groebner Basis conversion</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This function is implemented in ApCoCoALib by Stefan Kaspar.
<par/>
The function <tt>FGLM5</tt> calls the CoCoAServer to perform a
FGLM Groebner Basis conversion. Please note that the ideal generated
by the given Groebner Basis must be zero-dimensional. The Groebner
Basis contained in list GBOld will be converted into a Groebner Basis
with respect to term ordering <tt>Ord(M)</tt>, i.e. M must be a matrix
specifying a term ordering.

<example>
  Use QQ[x, y, z], DegRevLex;
  GBOld := [z^4 -3z^3 - 4yz + 2z^2 - y + 2z - 2, yz^2 + 2yz - 2z^2 + 1, y^2 - 2yz + z^2 - z, x + y - z];
  M := LexMat(3);
  GBNew := FGLM5(GBOld, M);
  Use QQ[x, y, z], Ord(M);
  -- New basis (Lex)
  BringIn(GBNew);
</example>
    </description>

    <syntax>
FGLM5(GBOld:LIST, M:MAT):LIST
</syntax>

    <seealso>     
    </seealso>

    <types>
      <type>groebner</type>
      <type>ideal</type>
      <type>list</type>
    </types>

    <keys>
    <key>apcocoalib</key>
    <key>kaspar</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>fields</title>
    <short_description>list the fields of a record</short_description>

    <syntax>
fields(R:RECORD):LIST
</syntax>

    <description>
This function returns a list of all of the fields of the record <tt>R</tt>.
It is particularly useful when you want to know if a record field
has been defined
<example>
/**/  rec := Record[name := "David", number := 3728852, data := ["X","Y"] ];
/**/  fields(rec);
["data", "name", "number"]

/**/  rec.data;
["X", "Y"]

/**/  "surname" IsIn fields(rec);
false
</example>
    </description>

    <seealso>
      <see>Introduction to Records</see>
      <see>record</see>
    </seealso>

    <types>
      <type>record</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>first</title>
    <short_description>the first N elements of a list</short_description>

    <description>
In the first form the function returns the first element of the list
L, same as <tt>L[1]</tt>.
In the second form, it returns the list of the first N elements of L,
same as <tt>[ L[i] | i in 1..N ]</tt>
<example>
/**/  L := [1,2,3,4,5];
/**/  first(L);
1

/**/  first(L,3);
[1, 2, 3]
</example>
    </description>

    <syntax>
first(L:LIST):OBJECT
first(L:LIST, N:INT):OBJECT
</syntax>

    <seealso>
      <see>last</see>
    </seealso>

    <types>
      <type>list</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>FirstNonZero</title>
    <short_description>the first non-zero entry in a MODULEELEM</short_description>

    <description>
This function returns the first non-zero entry of V.  If it
is handed a zero MODULEELEM then an error is signalled.

<example>
/**/  Use R ::= QQ[x,y,z];
/**/  R5 := NewFreeModule(R,5);
/**/  V := ModuleElem(R5, [0, 0, x^2+y*z, 0, z^2]);

/**/  FirstNonZero(V);
x^2 +y*z

/**/  FirstNonZeroPos(V);
2
</example>
    </description>

    <syntax>
FirstNonZero(V:MODULEELEM):POLY
</syntax>

    <seealso>
      <see>FirstNonZeroPos</see>
      <see>IsZero</see>
      <see>NonZero</see>
    </seealso>

    <types>
      <type>moduleelem</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>FirstNonZeroPos</title>
    <short_description>the first non-zero entry in a MODULEELEM</short_description>

    <description>
This function returns the index of the first non-zero entry of V.  If it
is handed a zero MODULEELEM then an error is signalled.

<example>
/**/  Use R ::= QQ[x,y,z];
/**/  R5 := NewFreeModule(R,5);
/**/  V := ModuleElem(R5, [0, 0, x^2+y*z, 0, z^2]);

/**/  FirstNonZero(V);
x^2 +y*z

/**/  FirstNonZeroPos(V);
2
</example>
    </description>

    <syntax>
FirstNonZero(V:MODULEELEM):POLY
</syntax>

    <seealso>
      <see>FirstNonZero</see>
      <see>IsZero</see>
      <see>NonZero</see>
    </seealso>

    <types>
      <type>moduleelem</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>flatten</title>
  <short_description>flatten a list</short_description>

<syntax>
flatten(L:LIST):LIST
flatten(L:LIST, N:INT):LIST
</syntax>
<description>
Components of lists may be lists themselves, i.e., lists may be
nested.  With one argument this function returns the list obtained
from the list <tt>L</tt> by removing all nesting, bringing all elements <em>to
the top level</em>.  With the optional second argument, <tt>N</tt>, nesting is
removed down <tt>N</tt> levels.  Thus, the elements of <tt>M := flatten(L,1)</tt> are
formed as follows: go through the elements of <tt>L</tt> one at a time; if an
elements is not a list, add it to <tt>M</tt>; if an element is a list, add all
of its elements to <tt>M</tt>.  Recursively, <tt>Flatten(L, N) =
Flatten(Flatten(L, N-1),1)</tt>.  For <tt>N</tt> large, depending on <tt>L</tt>,
<tt>Flatten(L, N)</tt> gives the same result as <tt>Flatten(L)</tt>.

<example>
/**/  flatten([1,["a","b",[2,3,4],"c","d"],5,6]);
[1, "a", "b", 2, 3, 4, "c", "d", 5, 6]

/**/  L := [1,2, [3,4], [5, [6,7,[8,9]]]];
/**/  flatten(L,1);
[1, 2, 3, 4, 5, [6, 7, [8, 9]]]

/**/  flatten(It,1);
[1, 2, 3, 4, 5, 6, 7, [8, 9]]

/**/  flatten(L,2);  -- same as flatten(flatten(L,1),1)
[1, 2, 3, 4, 5, 6, 7, [8, 9]]

/**/  flatten(L,3);  -- same as flatten(L)
[1, 2, 3, 4, 5, 6, 7, 8, 9]
</example>
</description>

<types>
  <type>list</type>
</types>

</command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>FloatApprox</title>
    <short_description>approx. of rational number of the form <formula>M*10^E</formula></short_description>

    <description>
This function computes an approximation of the form <formula>M*10^E</formula> to
a rational number X and to within a maximum specified relative error.
MaxRelErr says indirectly how many decimal digits to include in the
mantissa.  Compare with <ttref>MantissaAndExponent</ttref>.

<example>
/**/  FloatApprox(1/3, 10^(-2));
333/1000

/**/  FloatApprox(1000000/3, 10^(-2));
333000

/**/  FloatApprox(1/3, 10^(-9));
3333333333/10000000000
</example>
    </description>

    <syntax>
FloatApprox(X:RAT, MaxRelErr:RAT):RAT
</syntax>

    <seealso>
      <see>DecimalStr</see>
      <see>FloatStr</see>
      <see>MantissaAndExponent</see>
    </seealso>

    <types>
      <type>rat</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>FloatStr</title>
    <short_description>convert integer/rational to a floating-point string</short_description>

    <syntax>
FloatStr(X:INT or RAT):STRING
FloatStr(X:INT or RAT, Prec:INT):STRING
</syntax>

    <description>
These two functions convert a rational number X into a (decimal)
floating point string.  The optional second argument Prec says how many
decimal digits to include in the mantissa; the default value is 10.
Note that an exponent is always included.

<example>
/**/  FloatStr(2/3);         -- last printed digit is rounded
6.666666667*10^(-1)

/**/  FloatStr(7^510);       -- no arbitrary limit on exponent range
1.000000938*10^431

/**/  FloatStr(1/81, 50);    -- precision of mantissa specified by user
1.2345679012345679012345679012345679012345679012346*10^(-2)

/**/  FloatStr(1/2);         -- trailing zeroes are not suppressed
5.000000000*10^(-1)
</example>
    </description>

    <seealso>
      <see>DecimalStr</see>
      <see>FloatApprox</see>
      <see>MantissaAndExponent</see>
    </seealso>

    <types>
      <type>int</type>
      <type>rat</type>
      <type>string</type>
    </types>

    <keys>
      <key>floating point</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>floor, ceil</title>
    <short_description>convert rational to nearby integer</short_description>

    <syntax>
floor(X:RAT):INT
ceil(X:RAT):INT
</syntax>

    <description>
These two functions convert a rational number <tt>X</tt> into an integer.
<tt>floor</tt> converts to the greatest integer less than or equal to <tt>X</tt>;
<tt>ceil</tt> converts to the least integer greater than or equal to <tt>X</tt>.

<example>
/**/  floor(0.99);
0

/**/ ceil(0.99);
1

/**/  floor(-0.99);
-1

/**/  ceil(-0.99);
0
</example>
    </description>

    <seealso>
      <see>round</see>
      <see>num</see>
      <see>den</see>
    </seealso>

    <types>
      <type>int</type>
      <type>rat</type>
    </types>

    <keys>
      <key>floor</key>
      <key>ceil</key>
      <key>ceiling</key>
      <key>rounding</key>
      <key>integer part</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>for</title>
    <short_description>loop command</short_description>

    <description>
In the first form, the variable I is assigned the values
<tt>N_1, N_1+1, ...,N_2</tt>
in succession.  After each assignment, the command sequence C
is executed.  The second form is the same, except that I is assigned
the values <tt>N_1, N_1+D, N_1+2D</tt>, etc. until the greatest value less than
or equal to <tt>N_2</tt> is reached.  If <tt>N_2 &lt; N_1</tt>, then C is not executed.
<par/>
NOTE: Large values for <tt>N_1, N_2</tt>, or D are not permitted; typically
      they should lie in the range about <formula>-10^9</formula> to <formula>+10^9</formula>.
<par/>
NOTE: Don&apos;t forget the capitalization in the word <tt>To</tt>.

<example>
/**/  For N := 1 To 5 Do Print 2^N, " "; EndFor;
2 4 8 16 32

/**/  for n := 1 to 20 step 3 do print n, " "; endfor;
1 4 7 10 13 16 19

/**/  for N := 10 To 1 Step -2 Do Print N, " "; EndFor;
10 8 6 4 2

/**/  For N := 5 To 3 Do Print N, " "; endfor;  -- no output
</example>

Loops can be nested.

<example>
   Define MySort(ref L)
     For I := 1 To len(L)-1 Do
       M := I;
       For J := I+1 To len(L) Do
         If L[J] &lt; L[M] Then M := J EndIf;
       EndFor;
       If M &lt;&gt; I Then
         C := L[M];
         L[M] := L[I];
         L[I] := C;
       EndIf;
     EndFor;
   EndDefine;

/**/  M := [5,3,1,4,2];
/**/  MySort(ref M);
/**/  M;
[1, 2, 3, 4, 5]
</example>

(Note that <tt>ref L</tt> is used so that the function can change the value
of the variable referenced by L.  See <tt>ref</tt>.)
    </description>

    <syntax>
For I := N_1 To N_2 Do C EndFor
For I := N_1 To N_2 Step D Do C EndFor

where I is a dummy variable, N_1, N_2, and D are integer expressions,
and C is a sequence of commands.
</syntax>

    <seealso>
      <see>foreach</see>
      <see>repeat</see>
      <see>while</see>
    </seealso>

    <types>
      <type>command</type>
      <type>programming</type>
      <type>loops</type>
    </types>

    <keys>
    <key>step</key>
    <key>downto</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>foreach</title>
    <short_description>loop command</short_description>

    <syntax>
foreach  X  in  L  do  CMDS  endforeach

where <tt>X</tt> is a dummy variable, <tt>L</tt> is a list, and <tt>CMDS</tt> is a sequence of commands.
</syntax>

    <description>
The dummy variable <tt>X</tt> is assigned the value of each component of <tt>L</tt> in
turn.  After each assignment the command sequence <tt>CMDS</tt> is executed.

<example>
/**/  foreach N In 1..10 Do  -- Note: 1..10 gives the list [1,...,10].
        print N^2, " ";
      endforeach;
1 4 9 16 25 36 49 64 81 100

/**/  Use R ::= QQ[x,y,z];
/**/  F := x^2*y + 3*y^2*z - z^3;
/**/  J := [der(F, X) | X In indets(R)];
/**/  J;
[2*x*y, x^2 +6*y*z, 3*y^2 -3*z^2]

/**/  Foreach X In J Do
        PrintLn X^2;
      EndForeach;
4*x^2*y^2
x^4 +12*x^2*y*z +36*y^2*z^2
9*y^4 -18*y^2*z^2 +9*z^4
</example>
    </description>

    <seealso>
      <see>operators</see>
      <see>for</see>
      <see>repeat</see>
      <see>while</see>
    </seealso>

    <types>
      <type>command</type>
      <type>programming</type>
      <type>loops</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>format</title>
    <short_description>convert object to formatted string</short_description>
    <syntax>
format(E:OBJECT, N:INT):STRING
</syntax>

    <description>
Like Sprint, this function converts the value of E into a string.  If
the string has fewer than N characters, then spaces are added to the
front to make the length N.

<example>
/**/  L := [5^n | n In 0..7];
/**/  Foreach F In L Do print Format(F,8); EndForeach;
       1       5      25     125     625    3125   15625   78125

/**/  M := Format(L,20);
/**/  M;  -- "Format" does not truncate
[1, 5, 25, 125, 625, 3125, 15625, 78125]
/**/  type(L);
LIST
/**/  type(M);
STRING
</example>
    </description>

    <seealso>
      <see>IO.SprintTrunc</see>
      <see>Latex</see>
      <see>sprint</see>
    </seealso>

    <types>
      <type>io</type>
      <type>printing</type>
      <type>string</type>
    </types>

    <keys>
    <key>formatted printing</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>Fraction</title>
    <short_description>returns the quotient of its arguments</short_description>

    <description>
This function returns E/F provided the quotient is defined (see
<ref>Algebraic Operators</ref>).

<example>
  Use R ::= QQ[x,y];
  Fraction(2,3);
2/3
-------------------------------
  Fraction(2,4);
1/2
-------------------------------
  Fraction(x,x+y);
x/(x + y)
-------------------------------
  Fraction(5%11,6%11);
10 % 11
-------------------------------
</example>
    </description>

    <syntax>
Fraction(E:OBJECT, F:OBJECT)
</syntax>

    <seealso>
      <see>Algebraic Operators</see>
    </seealso>

    <types>
      <type>integer</type>
      <type>polynomial</type>
      <type>rat</type>
      <type>ratfun</type>
      <type>zmod</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>FrbAlexanderDual</title>
  <short_description>Alexander Dual of monomial ideals</short_description>

<syntax>
FrbAlexanderDual(I:MONOMIAL IDEAL):LIST
FrbAlexanderDual(I:MONOMIAL IDEAL, T:Power-product):LIST
</syntax>
<description>
Using the <ttref>Frobby</ttref> library linked with CoCoALib.
<example>
/**/  I := ideal(x^2, x*y, y^2, z^2);
/**/  FrbAlexanderDual(I);
ideal(x^2*y*z, x*y^2*z)

/**/  FrbAlexanderDual(I, x^2*y^2*z^5);
ideal(x^2*y*z^4, x*y^2*z^4)
</example>
</description>

<types>
  <type>monomialideal</type>
  <type>cocoaserver</type>
</types>

<keys>
  <key>frobby</key>
  <key>roune</key>
</keys>

<seealso>
  <see>Frobby</see>
  <see>FrbPrimaryDecomposition</see>
  <see>PrimaryDecomposition</see>
</seealso>

</command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>FrbAssociatedPrimes</title>
  <short_description>Associated primes of monomial ideals</short_description>

<syntax>
FrbAssociatedPrimes(I:MONOMIAL IDEAL):LIST
</syntax>
<description>
Using the <ttref>Frobby</ttref> C++ library by Bjarke Roune.
<example>
/**/  Use R ::= QQ[x,y,z];
/**/  I := ideal(x^2, x*y, y^2, z^2);
/**/  FrbAssociatedPrimes(I);
[ideal(x, y, z)]
</example>
</description>

<types>
  <type>monomialideal</type>
</types>

<keys>
  <key>frobby</key>
  <key>roune</key>
</keys>

<seealso>
  <see>Frobby</see>
  <see>FrbIrreducibleDecom</see>
  <see>FrbPrimaryDecomposition</see>
</seealso>
</command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>FrbIrreducibleDecom</title>
  <short_description>Irreducible decomposition of monomial ideals</short_description>

<syntax>
FrbIrreducibleDecom(I:MONOMIAL IDEAL):LIST
</syntax>
<description>
Using the <ttref>Frobby</ttref> C++ library by Bjarke Roune.

<example>
/**/  Use R ::= QQ[x,y,z];
/**/  I := ideal(x^2, x*y, y^2, z^2);
/**/  FrbIrreducibleDecom(I);
[ideal(x, y^2, z^2), ideal(x^2, y, z^2)];

-- *** missing manual for these function: volunteers? ;-) ***
FrbDimension
FrbMultigradedHilbertPoincareNumerator
FrbTotalDegreeHilbertPoincareNumerator
</example>
</description>

<types>
  <type>monomialideal</type>
</types>

<keys>
  <key>frobby</key>
  <key>roune</key>
</keys>

<seealso>
  <see>Frobby</see>
  <see>FrbAssociatedPrimes</see>
  <see>FrbIrreducibleDecom</see>
</seealso>
</command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>FrbMaximalStandardMonomials</title>
  <short_description>Maximal standard monomials of monomial ideals</short_description>

<syntax>
FrbMaximalStandardMonomials(I:MONOMIAL IDEAL):LIST
</syntax>
<description>
Using the <ttref>Frobby</ttref> library linked with CoCoALib.
<example>
/**/  I := ideal(x^2, x*y, y^2, z^2);
/**/  FrbMaximalStandardMonomials(I);
ideal(y*z, x*z)
</example>
</description>

<types>
  <type>monomialideal</type>
</types>

<keys>
  <key>frobby</key>
  <key>roune</key>
</keys>

<seealso>
  <see>Frobby</see>
</seealso>

</command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>FrbPrimaryDecomposition</title>
  <short_description>Primary decomposition of monomial ideals</short_description>

<syntax>
FrbPrimaryDecomposition(I:MONOMIAL IDEAL):LIST
</syntax>
<description>
Using the <ttref>Frobby</ttref> C++ library by Bjarke Roune.

<example>
/**/  Use R ::= QQ[x,y,z];
/**/  I := ideal(x^2, x*y^2, z^2);
/**/  FrbPrimaryDecomposition(I);
[ideal(x^2, y^2, z^2), ideal(x, z^2)]
</example>
</description>

<types>
  <type>monomialideal</type>
</types>

<keys>
  <key>frobby</key>
  <key>roune</key>
</keys>

<seealso>
  <see>Frobby</see>
  <see>FrbAssociatedPrimes</see>
  <see>FrbIrreducibleDecom</see>
  <see>PrimaryDecomposition</see>
</seealso>
</command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>func</title>
    <short_description>Anonymous function</short_description>

    <syntax>
Func ... EndFunc
</syntax>

    <description>
This command returns a function without giving it a name; an anonymous
functions can be passed as a parameter and assigned to a variable.
Note that <tt>Func...EndFunc</tt> can be used inside function definitions.

<example>
/**/  square := Func(x) Return x^2; EndFunc;
/**/  square(3);
9

/**/  SortedBy(["zzz", "x", "yy"], Func(x,y) Return len(x)>len(y); EndFunc);
["zzz", "yy", "x"]
</example>
    </description>

    <seealso>
      <see>define</see>
      <see>TopLevel</see>
      <see>ImportByRef, ImportByValue</see>
    </seealso>

    <types>
      <type>function</type>
    </types>

    <keys>
    <key>anonymous functions</key>
    <key>lambda function</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>Function</title>
    <short_description>[*OBSOLETE*]</short_description>

    <description>
In CoCoA-4 it was possible to have a variable and a function with the
same name; the operator <tt>Function</tt> was used to instruct CoCoA-4
to search for the function of the given name, <i>e.g.</i> to pass it as
an argument to another function.

In CoCoA-5 functions are "first class objects", and so may be passed
like any other value -- the operator <tt>Function</tt> serves no purpose.

In CoCoA-5 if you want to use the name of a function as an ordinary
variable then you must make it "visible" by using the <tt>TopLevel</tt>
command.
<example>
  Define IncreasingDeg(f,g)
    Return deg(f) &lt; deg(g);
  EndDefine;
  Use QQ[x];
  L := [x^2,x];
  SortBy(ref L, IncreasingDeg);
  -- In C4 it was   SortBy(L, Function("IncreasingDeg"));
</example>
    </description>

    <syntax>
Function -- OBSOLETE!!
</syntax>

    <seealso>
      <see>functions</see>
      <see>TopLevel</see>
    </seealso>

    <types>
      <type>function</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>functions</title>
    <short_description>[*OBSOLETE*] replaced by describe</short_description>

    <syntax>
[*OBSOLETE*] Functions(PKG:STRING):LIST of FUNCTION
</syntax>

    <description>
This function is OBSOLETE; please use the command <ttref>describe</ttref>.
    </description>

  </command>

 </chapter_letter>
 <!-- ===  CHAPTER  =============================================== -->
 <chapter_letter>
   <title>G</title>

<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>GB.Complete</title>
    <short_description>Complete an interactive Groebner-type calculation</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This function completes a calculation started in the Interactive
Groebner Framework.  For explanations and examples, see
<ref>The Interactive Groebner Framework</ref>.
    </description>

    <syntax>
$gb.Complete(M:IDEAL or MODULE):NULL
</syntax>

    <seealso>
      <see>The Interactive Groebner Framework</see>
    </seealso>

    <types>
      <type>groebner</type>
      <type>groebner-interactive</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>GB.GetBettiMatrix</title>
    <short_description>returns the Betti matrix computed so far</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This function, if used after executing <tt>Res(M)</tt>, prints the Betti
matrix for M.  Within the Interactive Groebner Framework, in which
resolutions may be computed one step at a time, the function returns
the Betti matrix for the part of the resolution computed so far.  See
<ttref>GB.GetRes</ttref> for an example.

<example>
  Use R ::= QQ[t,x,y,z];
  I := ideal(x^2-yt, xy-zt, xy);
  Res(I);
0 --&gt; R^2(-5) --&gt; R^4(-4) --&gt; R^3(-2)
-------------------------------
  $gb.GetBettiMatrix(I);
--------------

--------------
   0    0    0
   0    0    3
   0    0    0
   0    4    0
   2    0    0
--------------

-------------------------------
</example>
    </description>

    <syntax>
$gb.GetBettiMatrix(M:IDEAL or MODULE):TAGGED("$io.Matrix")
</syntax>

    <seealso>
      <see>GB.GetRes</see>
      <see>GB.GetResLen</see>
      <see>res</see>
      <see>The Interactive Groebner Framework</see>
      <see>BettiDiagram</see>
      <see>BettiMatrix</see>
    </seealso>

    <types>
      <type>groebner</type>
      <type>groebner-interactive</type>
      <type>ideal</type>
      <type>module</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>GB.GetNthSyz</title>
    <short_description>returns the part of the Nth syzygy module computed so far</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This function, if used after executing <tt>Res(M)</tt>, returns the Nth
syzygy module for M.  Within the Interactive Groebner Framework, in
which resolutions may be computed one step at a time, the function
returns the part of the Nth syzygy module computed so far.  In
contrast, the function <ttref>syz</ttref> always determines the complete syzygy
module even from within the Interactive Groebner Framework.

<example>
  Use R ::= QQ[t,x,y,z];
  I := ideal(x^2-yt, xy-zt, xy);
  $gb.Start_Res(I);
  $gb.Steps(I,1);
  $gb.GetNthSyz(I,1);  $gb.GetNthSyz(I,2);
Module([[0]])
-------------------------------
Module([[0]])
-------------------------------
  $gb.Steps(I,1);
  $gb.GetNthSyz(I,1);  $gb.GetNthSyz(I,2);
Module([0, 0])
-------------------------------
Module([[0]])
-------------------------------
  $gb.Steps(I,5);
  $gb.GetNthSyz(I,1);  $gb.GetNthSyz(I,2);
Module([-xz, -y^2, yz])
-------------------------------
Module([[0]])
-------------------------------
  $gb.Complete(I);
  $gb.GetNthSyz(I,1);  $gb.GetNthSyz(I,2);
Module([-xz, -y^2, yz], [tz, xy, 0], [0, -x^2 + ty, -tz], [-x^2 + ty, 0, xy])
-------------------------------
Module([-x, -y, 0, z], [-t, -x, -y, 0])
-------------------------------
</example>
    </description>

    <syntax>
$gb.GetNthSyz(M:IDEAL or MODULE, N:INT):MODULE
</syntax>

    <seealso>
      <see>GB.GetNthSyzShifts</see>
      <see>GB.GetRes</see>
      <see>res</see>
      <see>syz</see>
      <see>The Interactive Groebner Framework</see>
    </seealso>

    <types>
      <type>groebner</type>
      <type>groebner-interactive</type>
      <type>ideal</type>
      <type>module</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>GB.GetNthSyzShifts</title>
    <short_description>shifts of the Nth syzygy module computed so far</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This function, if used after executing <tt>Res(M)</tt>, returns the shifts
for the Nth syzygy module for M.  Within the Interactive Groebner
Framework, in which resolutions may be computed one step at a time,
the function returns shifts of the part of the Nth syzygy module
computed so far.

<example>
  Use R ::= QQ[t,x,y,z];
  I := ideal(x^2-yt, xy-zt, xy);
  $gb.Start_Res(I);
  $gb.Steps(I,6);
  $gb.GetNthSyzShifts(I,2);
Shifts([x^2yz])
-------------------------------
  $gb.Complete(I);
  $gb.GetNthSyzShifts(I,2);
Shifts([x^2yz, txyz, tx^2z, x^3y])
-------------------------------
  J := ideal(t,x)^3;
  Res(J);
0 --&gt; R^3(-4) --&gt; R^4(-3)
-------------------------------
  $gb.GetNthSyzShifts(J,1);
Shifts([x^3, tx^2, t^2x, t^3])
-------------------------------
  $gb.GetNthSyzShifts(J,2);
Shifts([tx^3, t^2x^2, t^3x])
-------------------------------
  SS := It;
  SS[1];
tx^3
-------------------------------
</example>
    </description>

    <syntax>
$gb.GetNthSyzShifts(M:IDEAL or MODULE, N:INT):TAGGED("shifts")
</syntax>

    <seealso>
      <see>GB.GetNthSyz</see>
      <see>GB.GetRes</see>
      <see>res</see>
      <see>Shifts</see>
      <see>The Interactive Groebner Framework</see>
    </seealso>

    <types>
      <type>groebner</type>
      <type>groebner-interactive</type>
      <type>ideal</type>
      <type>module</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>GB.GetRes</title>
    <short_description>returns the resolution computed so far</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This function returns the part of the resolution of M computed so
far.  It does not compute the resolution of M as does <ttref>res</ttref>, rather,
<tt>GB.GetRes</tt> is intended primarily to be used within the Interactive
Groebner Framework.  Thus, for example, <tt>GB.GetRes</tt> may be used to
examine the resolution as it is computed, one step at a time.

<example>
  Use R ::= QQ[t,x,y,z];
  I := ideal(x^2-yt, xy-zt, xy);
  $gb.Start_Res(I); -- start Interactive Groebner Framework
  $gb.Steps(I,1); -- take one step in calculation of resolution
  $gb.GetRes(I);  -- the resolution so far
0 --&gt; R(-2)
-------------------------------
  $gb.Steps(I,1);  -- one more step
  $gb.GetResLen(I);  -- the computed resolution still has length 1
1
-------------------------------
  $gb.GetBettiMatrix(I);  -- the Betti Matrix so far
----

----
   0
   2
----

-------------------------------
  $gb.GetRes(I);
0 --&gt; R^2(-2)
-------------------------------
  $gb.Steps(I,5); -- five more steps
  $gb.GetRes(I);
0 --&gt; R(-4) --&gt; R^3(-2)
-------------------------------
  $gb.Complete(I); -- complete the calculation
  $gb.GetResLen(I);
3
-------------------------------
  $gb.GetBettiMatrix(I);
--------------

--------------
   0    0    0
   0    0    3
   0    0    0
   0    4    0
   2    0    0
--------------

-------------------------------
  $gb.GetRes(I);
0 --&gt; R^2(-5) --&gt; R^4(-4) --&gt; R^3(-2)
-------------------------------
</example>
    </description>

    <syntax>
$gb.GetRes(M:IDEAL or MODULE):TAGGED("$gb.Res")
</syntax>

    <seealso>
      <see>GB.GetBettiMatrix</see>
      <see>GB.GetResLen</see>
      <see>res</see>
      <see>The Interactive Groebner Framework</see>
    </seealso>

    <types>
      <type>groebner</type>
      <type>groebner-interactive</type>
      <type>ideal</type>
      <type>module</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>GB.GetResLen</title>
    <short_description>returns the length of the resolution computed so far</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This function, if used after executing <tt>Res(M)</tt>, prints the length of
the resolution for M.  Within the Interactive Groebner Framework, in
which resolutions may be computed one step at a time, the function
returns the length of the part of the resolution computed so far.  See
<ttref>GB.GetRes</ttref> for an example.

<example>
  Use R ::= QQ[t,x,y,z];
  I := ideal(x^2-yt, xy-zt, xy);
  Res(I);
0 --&gt; R^2(-5) --&gt; R^4(-4) --&gt; R^3(-2)
-------------------------------
  $gb.GetResLen(I);
3
-------------------------------
</example>
    </description>

    <syntax>
$gb.GetResLen(M:IDEAL or MODULE):INT
</syntax>

    <seealso>
      <see>GB.GetBettiMatrix</see>
      <see>GB.GetRes</see>
      <see>res</see>
      <see>The Interactive Groebner Framework</see>
    </seealso>

    <types>
      <type>groebner</type>
      <type>groebner-interactive</type>
      <type>ideal</type>
      <type>module</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>GB.ResReport</title>
    <short_description>status of an interactive resolution calculation</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This function reports statistics about the current status of a
resolution computation begun in the Interactive Groebner Framework.
For explanations and examples, see <ref>The Interactive Groebner
Framework</ref>.
    </description>

    <syntax>
$gb.ResReport(M:IDEAL or MODULE):NULL
</syntax>

    <seealso>
      <see>GB.Stats</see>
      <see>The Interactive Groebner Framework</see>
    </seealso>

    <types>
      <type>groebner</type>
      <type>groebner-interactive</type>
      <type>ideal</type>
      <type>module</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>GB.Start_GBasis</title>
    <short_description>start interactive Groebner basis computation</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This command starts the Interactive Groebner Framework for
calculating a Groebner basis for M.  For explanations and examples,
see <ref>The Interactive Groebner Framework</ref>.
    </description>

    <syntax>
$gb.Start_GBasis(M:IDEAL or MODULE):NULL
</syntax>

    <seealso>
      <see>The Interactive Groebner Framework</see>
    </seealso>

    <types>
      <type>groebner</type>
      <type>groebner-start</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>GB.Start_MinGens</title>
    <short_description>start interactive minimal generator calculation </short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This command starts the Interactive Groebner Framework for
calculating minimal generators for M.  For explanations and examples,
see <ref>The Interactive Groebner Framework</ref>.
    </description>

    <syntax>
$gb.Start_MinGens(M:IDEAL or MODULE):NULL
</syntax>

    <seealso>
      <see>The Interactive Groebner Framework</see>
    </seealso>

    <types>
      <type>groebner</type>
      <type>groebner-start</type>
    </types>

  </command>
<!-- ===  COMMAND-rm GB.Start_MinSyzMinGens ================================= -->
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>GB.Start_Res</title>
    <short_description>start interactive resolution computation</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This command starts the Interactive Groebner Framework for
calculating a resolution for M.  For explanations and examples, see
<ref>The Interactive Groebner Framework</ref>.
    </description>

    <syntax>
$gb.Start_Res(M:IDEAL or MODULE):NULL
</syntax>

    <seealso>
      <see>The Interactive Groebner Framework</see>
    </seealso>

    <types>
      <type>groebner</type>
      <type>groebner-start</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>GB.Start_Syz</title>
    <short_description>start interactive syzygy computation</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This command starts the Interactive Groebner Framework for
calculating syzygies for M.  For explanations and examples, see
<ref>The Interactive Groebner Framework</ref>.
    </description>

    <syntax>
$gb.Start_Syz(M:IDEAL or MODULE):NULL
</syntax>

    <seealso>
      <see>The Interactive Groebner Framework</see>
    </seealso>

    <types>
      <type>groebner</type>
      <type>groebner-start</type>
    </types>

  </command>
<!-- ===  COMMAND-rm GB.Start_SyzMinGens ================================== -->
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>GB.Stats</title>
    <short_description>status of an interactive Groebner-type calculation</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This function displays information about the current status of a
calculation started in the Interactive Groebner Framework.  For
explanations and examples, see <ref>The Interactive Groebner Framework</ref>.
    </description>

    <syntax>
$gb.Stats(M:IDEAL or MODULE):NULL
</syntax>

    <seealso>
      <see>GB.ResReport</see>
      <see>The Interactive Groebner Framework</see>
    </seealso>

    <types>
      <type>groebner</type>
      <type>groebner-interactive</type>
    </types>

  </command>
<!-- ===  COMMAND-rm GB.Step =============================================== -->
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>GB.Steps</title>
    <short_description>take steps in an interactive Groebner-type calculation</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This function performs N steps in a calculation started in the
Interactive Groebner Framework.
For explanations and examples, see <ref>The Interactive Groebner Framework</ref>.
    </description>

    <syntax>
$gb.Steps(M:IDEAL or MODULE, N:INT):NULL
</syntax>

    <seealso>
      <see>The Interactive Groebner Framework</see>
      <see>GB.Steps</see>
    </seealso>

    <types>
      <type>groebner</type>
      <type>groebner-interactive</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>GBasis</title>
    <short_description>calculate a Groebner basis</short_description>

    <description>
If M is an ideal or module, this function returns a list whose
components form a Groebner basis for M with respect to the
term-ordering of the polynomial ring of M.  If M is a quotient ring by
an ideal I or of a free module by a submodule N, then the
Groebner basis for M is defined to be that of I or N, respectively.
<par/>
If M is a variable, then the result is stored in M for later use.
<par/>
For a reduced Groebner basis, use the command <ref>ReducedGBasis</ref>.
<par/>
The coefficient ring must be a field.

<example>
/**/  Use R ::= QQ[t,x,y];
/**/  I := ideal(t^3-x, t^4-y);
/**/  GBasis(I);
[t^3 - x, -tx + y, t^2y - x^2, x^3 - ty^2]
</example>

For fine control and monitoring of Groebner basis calculations, see
<ref>The Interactive Groebner Framework</ref> and <ref>Introduction to Panels</ref>.
    </description>

    <syntax>
GBasis(M:IDEAL or MODULE):LIST
</syntax>

    <seealso>
      <see>Introduction to Groebner Bases in CoCoA</see>
      <see>GBasisTimeout</see>
    </seealso>

    <types>
      <type>groebner</type>
      <type>groebner-basic</type>
      <type>ideal</type>
      <type>module</type>
      <type>quotient</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>GBasisTimeout</title>
    <short_description>compute a Groebner basis with a timeout</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
Same as <ttref>GBasis</ttref>, but it will stop and return an error if
the computation is not completed.
<par/>
For dealing with errors see <ttref>try</ttref>.
<par/>
For a limit on the degree see <ref>Example: Truncations</ref>.

<example>
  Use R ::= QQ[t,x,y,z];
  I := ideal(t^3-x, t^4-y, t^5-z);
  J := I^5; Time G := GBasisTimeout(J, 1);
ERROR: Time expired: use $gb.Complete to complete the computation
CONTEXT: Error(GBasisTimeout_Err)
-------------------------------
  J := I^5; Time G := GBasisTimeout(J, 10);
Cpu time = 1.96, User time = 2
-------------------------------
</example>

    </description>

    <syntax>
GBasisTimeout(M:IDEAL, MODULE, or TAGGED("Quotient"), SECONDS:INT):LIST
</syntax>

    <seealso>
      <see>Introduction to Groebner Bases in CoCoA</see>
      <see>Example: Truncations</see>
      <see>GBasis</see>
      <see>try</see>
    </seealso>

    <types>
      <type>groebner</type>
      <type>groebner-basic</type>
      <type>ideal</type>
      <type>module</type>
      <type>quotient</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>GBM</title>
    <short_description>intersection of ideals for zero-dimensional schemes</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This function computes the intersection of ideals corresponding to
zero-dimensional schemes: GBM is for affine schemes, and <ttref>HGBM</ttref> for
projective schemes.  The list L must be a list of ideals.  The function
<ttref>IntersectionList</ttref> should be used for computing the intersection of a
collection of general ideals.
<par/>
The name GBM comes from the name of the algorithm used: Generalized
Buchberger-Moeller.

<example>
/**/  Use P ::= QQ[x,y,z];
/**/  I1 := IdealOfPoints(P, mat([[1,2,1], [0,1,0]])); -- a simple affine scheme
/**/  I2 := IdealOfPoints(P, mat([[1,1,1], [2,0,1]]))^2;-- another affine scheme

***** NOT YET IMPLEMENTED *****
  GBM([I1, I2]);                                  -- intersect the ideals
ideal(xz + yz - z^2 - x - y + 1,
 z^3 - 2z^2 + z,
 yz^2 - 2yz - z^2 + y + 2z - 1,
 y^2z - y^2 - yz + y,
 xy^2 + y^3 - 2x^2 - 5xy - 5y^2 + 2z^2 + 8x + 10y - 4z - 6,
 x^2y - y^3 + 2x^2 + 2xy + 4y^2 - 3z^2 - 8x - 8y + 6z + 5,
 x^3 + y^3 - 7x^2 - 5xy - 4y^2 + 5z^2 + 16x + 10y - 10z - 7,
 y^4 - 2y^3 - 4x^2 - 8xy - 3y^2 + 4z^2 + 16x + 16y - 8z - 12)
-------------------------------
</example>
    </description>

    <syntax>
GBM(L:LIST):IDEAL
</syntax>

    <seealso>
      <see>Finite Point Sets: Buchberger-Moeller</see>
      <see>IdealAndSeparatorsOfPoints</see>
      <see>IdealAndSeparatorsOfProjectivePoints</see>
      <see>IdealOfPoints</see>
      <see>IdealOfProjectivePoints</see>
      <see>HGBM</see>
    </seealso>

    <types>
      <type>groebner</type>
      <type>ideal</type>
      <type>list</type>
      <type>points</type>
    </types>

    <keys>
    <key>fat</key>
    <key>point</key>
    <key>abbott</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>gcd</title>
    <short_description>greatest common divisor</short_description>

    <description>
This function returns the greatest common divisor of <tt>F_1,...,F_n</tt>
or of the elements in the list L.
For the calculation of the GCDs and LCMs of polynomials, the
coefficient ring must be a field.

<example>
/**/  Use R ::= QQ[x,y];
/**/  F := x^2-y^2;
/**/  G := (x+y)^3;
/**/  gcd(F, G);
-x -y

/**/  gcd([3*4,3*8,6*16]);
12
</example>
    </description>

    <syntax>
gcd(F:INT,G:INT):INT
gcd(L:LIST of INT):INT

gcd(F:RINGELEM, G:RINGELEM):RINGELEM
gcd(L:LIST of RINGELEM):RINGELEM
</syntax>

    <seealso>
      <see>div</see>
      <see>mod</see>
      <see>lcm</see>
    </seealso>

    <types>
      <type>groebner</type>
      <type>groebner-basic</type>
      <type>integer</type>
      <type>polynomial</type>
    </types>

    <keys>
    <key>greatest common divisor</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>GCDFreeBasis</title>
    <short_description>determine (minimal) GCD free basis of a set of integers</short_description>

    <description>
This function returns a GCD free basis of a set of integers; you can
think of this as the set of all numbers (except 1) obtainable by performing GCD
and exact division operations.
<par/>
Given a set <formula>N = [ N_1,...N_k ]</formula> we seek a basis <formula>G = [ G_1,...,G_s ]</formula> such that
each <formula>N_i</formula> is a product of powers of the <formula>G_j</formula>, and the <formula>G_j</formula> are pairwise
coprime; the set <formula>G</formula> is called a GCD free basis for <formula>N</formula>.  In general the set
<formula>G</formula> is not uniquely defined.

<example>
/**/  GCDFreeBasis([factorial(20), factorial(10)]);
[46189, 4, 14175]
</example>
    </description>

    <syntax>
GCDFreeBasis(L:LIST of INT):LIST of INT

</syntax>

    <seealso>
      <see>gcd</see>
    </seealso>

    <types>
      <type>integer</type>
    </types>

    <keys>
    <key>gcd free basis</key>
    <key>greatest common divisor</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>GenericPoints</title>
    <short_description>random projective points</short_description>

    <description>
<tt>GenericPoints</tt> returns a list of NumPoints generic projective points
with integer coordinates; it is not guaranteed that these points are
distinct.  RandomRange specifies the largest value any coordinate may
take.  If the second argument is omitted, the largest value possible
is 100 (or P-1 where P is the characteristic of the coefficient ring).

<example>
/**/  Use R ::= QQ[x,y];  GenericPoints(R,7);
[[1, 0], [0, 1], [1, 1], [12, 59], [6, 63], [12, 80], [17, 63]]

/**/  GenericPoints(R,7,500);
[[1, 0], [0, 1], [1, 1], [220, 162], [206, 452], [98, 106], [403, 449]]

/**/  Use R ::= ZZ/(5)[x,y,z];
/**/  GenericPoints(R,7);
[[1, 0, 0], [0, 1, 0], [0, 0, 1], [1, 1, 1], [2, 1, 1], [2, 2, 4], [3, 1, 3]]

/**/  GenericPoints(R,7,500);
[[1, 0, 0], [0, 1, 0], [0, 0, 1], [1, 1, 1], [1, 4, 2], [1, 3, 2], [2, 3, 3]]
</example>
    </description>

    <syntax>
GenericPoints(R:RING, NumPoints:INT):LIST
GenericPoints(R:RING, NumPoints:INT, RandomRange:INT):LIST
</syntax>

    <types>
      <type>integer</type>
      <type>list</type>
      <type>points</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>GenRepr</title>
    <short_description>representation in terms of generators</short_description>

    <description>
<par/>
This function returns a list giving a representation of X in terms of
generators for I. Let the generators for I be <tt>[G_1,...,G_t]</tt>.  If X is
in I, then <tt>GenRepr</tt> will return a list <tt>[F_1,...,F_t]</tt> such that
<verbatim>
             X = F_1*G_1 + ... + F_t*G_t.
</verbatim>
If X is not in I, then <tt>GenRepr</tt> returns the empty list, [].

<example>
/**/  Use R ::= QQ[x,y];
/**/  I := ideal(x+y^2, x^2-x*y);
/**/  GenRepr(x^3-x^2*y-y^3-x*y, I);
[-y, x]
/**/  -y*gens(I)[1] + x*gens(I)[2];
x^3 -x^2*y -y^3 -x*y
/**/  GenRepr(x+y, I);  -- x+y is not in I
[ ]

/**/  K := NewFractionField(NewPolyRing(QQ, ["a"]));
/**/  Use R ::= K[x,y];
/**/  L := [x+y^2, x^2-x*y];
/**/  GenRepr((a-2)*L[1] - (x-a)*L[2], ideal(L));
[a -2, -x +a]

/**/  R3 := NewFreeModule(R,3);
/**/  V1 := ModuleElem(R3, [x, y, y^2]);
/**/  V2 := ModuleElem(R3, [x-y, 0, x^2]);
/**/  X := x^2*V1 - y^2*V2;
/**/  M := submodule(R3, [V1, V2]);
/**/  GenRepr(X, M);
[x^2, -y^2]
-------------------------------
</example>
    </description>

    <syntax>
GenRepr(X:RINGELEM, I:IDEAL):LIST of RINGELEM
GenRepr(X:MODULEELEM, I:MODULE):LIST of RINGELEM
</syntax>

    <seealso>
      <see>DivAlg</see>
      <see>IsIn</see>
      <see>NF</see>
      <see>syz</see>
    </seealso>

    <types>
      <type>ideal</type>
      <type>module</type>
      <type>polynomial</type>
      <type>moduleelem</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>gens</title>
    <short_description>list of generators of an ideal</short_description>

    <description>
This function returns a list of polynomials which generate the ideal
I or the module M.  The list is not necessarily minimal.

<example>
/**/  Use R ::= QQ[x,y];
/**/  I := ideal(y^2-x^3, x*y);
/**/  gens(I);
[-x^3 +y^2, x*y]

/**/  gens(I^2);
[x^6 -2x^3*y^2 +y^4, -x^4*y +x*y^3, x^2*y^2]

/**/  R3 := NewFreeModule(R, 3);
/**/  e := gens(R3);  // canonical basis
/**/  e[2];
[0, 1, 0]

/**/  M := SubmoduleRows(R3, mat([[x,y,z], [x-1,0,z]]));
/**/  gens(M);
[[x, y, z], [x -1, 0, z]]
/**/  shape(It);
[MODULEELEM, MODULEELEM]
/**/  GensAsRows(M);
matrix( /*RingDistrMPolyClean(QQ, 3)*/
 [[x, y, z],
  [x -1, 0, z]])
</example>
    </description>

    <syntax>
gens(I:IDEAL):LIST
gens(M:MODULE):LIST
</syntax>

    <seealso>
      <see>GensAsCols, GensAsRows</see>
      <see>minimalize</see>
      <see>minimalized</see>
    </seealso>

    <types>
      <type>ideal</type>
      <type>module</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>GensAsCols, GensAsRows</title>
    <short_description>matrix of generators of a module</short_description>

    <description>
These functions returns a matrix which generate the module M
with the components as row (or colums) of a matrix.

The generators are not necessarily minimal.

<example>
/**/  Use R ::= QQ[x,y,z];
/**/  R3 := NewFreeModule(R, 3);
/**/  L := [[x,y,z], [x-1,0,z]];
/**/  M := SubmoduleRows(R3, mat(L));
/**/  gens(M);
[[x, y, z], [x -1, 0, z]]
/**/ shape(It);
[MODULEELEM, MODULEELEM]

/**/ GensAsRows(M);
matrix( /*RingDistrMPolyClean(QQ, 3)*/
 [[x, y, z],
  [x -1, 0, z]]
 )

/**/ GensAsCols(M);
matrix( /*RingDistrMPolyClean(QQ, 3)*/
 [[x, x -1],
  [y, 0],
  [z, z]]
 )
</example>
    </description>

    <syntax>
GensAsRows(M:MODULE):MAT
GensAsCols(M:MODULE):MAT
</syntax>

    <seealso>
      <see>gens</see>
      <see>SubmoduleCols, SubmoduleRows</see>
    </seealso>

    <types>
      <type>ideal</type>
      <type>module</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>Get</title>
    <short_description>read characters from a device</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This function reads N characters from D and returns the list of
their ASCII codes.

<example>
  D := OpenIFile("io.cpkg");  -- open the file "io.cpkg"
  Get(D,10);  -- get the first 10 characters
[45, 45, 32, 105, 111, 100, 101, 118, 46, 112]
-------------------------------
  ascii(It); convert the ASCII code to characters
-- iodev.p
-------------------------------
  ascii(Get(D,10));  -- get the next 10 characters and convert
kg : 0.1 :
-------------------------------
  Close(D);
</example>

The instruction <tt>Get(DEV.STDIN,3)</tt>, for instance, will read
3 characters typed in by the user.
Clever use of this function can be used to prompt a
user for input to a function, although it is usually easier for
functions to take input directly as arguments.
NOTE: this function does not work properly under the GUI Interface.
    </description>

    <syntax>
Get(D:DEVICE, N:INT):LIST of INT
</syntax>

    <seealso>
      <see>Introduction to IO</see>
      <see>OpenIFile</see>
      <see>OpenOFile</see>
      <see>OpenIString</see>
      <see>OpenOString</see>
    </seealso>

    <types>
      <type>io</type>
      <type>printing</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>GetEnv</title>
    <short_description>access shell variables</short_description>

    <description>
This function returns the value of system shell variables

<example>
/**/  GetEnv("HOME");
/Users/bigatti

/**/  GetEnv("COCOARC");
/Users/bigatti/.cocoarc

/**/  GetEnv("COCOA_PACKAGES");
/Applications/CoCoA-4.7/packages
</example>
    </description>

    <syntax>
GetEnv(S:STRING):STRING
</syntax>

    <types>
      <type>string</type>
    </types>

    <keys>
    <key>home</key>
    <key>path</key>
    <key>shell</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>GetErrMesg</title>
    <short_description>returns the message associated with an error</short_description>

    <description>
This function returns the string containing the error message
associated with an error.

<example>
/**/  ErrMsg := ""; 

  Try
    F := 1/0;
  UponError E Do
    ErrMsg := GetErrMesg(E);
  EndTry;  -- no error is thrown with Try .. UponError .. EndTry

/**/ ErrMsg;
Division by zero or by a zero-divisor
</example>
    </description>

    <syntax>
GetErrMesg(E:ERROR):STRING
</syntax>

    <seealso>
      <see>try</see>
      <see>error</see>
    </seealso>

    <types>
      <type>error</type>
    </types>

    <keys>
    <key>message</key>
    <key>msg</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>Gin, Gin5</title>
    <short_description>generic initial ideal</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
These functions return the [probabilistic] gin (generic initial ideal)
of the ideal I.  It is obtained by computing the leading term ideal of
g(I), where g is a random change of coordinates.
<par/>
While <tt>Gin</tt> uses integer coefficients in [-Range, Range], with
default value [-100, 100] (repeated until 4 consecutive random changes
of coordinates give the same result), the function <tt>Gin5</tt> uses
the special TwinFloat implementation to allow a much
wider range of coefficients (and then performs the computation only twice).
The latter is faster, but needs you to start the server!

<example>
  Use R ::= QQ[x,y,z], DegRevLex;
  Gin(ideal(y^2-xz, x^2z-yz^2));
ideal(x^2, xy^2, y^4)
-------------------------------
  Use R ::= QQ[x,y,z], Lex;
  Gin(ideal(y^2-xz, x^2z-yz^2), 10);  -- coeffs in range [-10, 10]
ideal(x^2, xy^2, xyz^2, xz^4, y^6)
-------------------------------
  Use R ::= QQ[x,y,z], DegRevLex;
  Gin5(ideal(y^2-xz, x^2z-yz^2));     -- default coeff range [-10000, 10000]
ideal(x^2, xy^2, y^4)
-------------------------------
  Use R ::= QQ[x,y,z], Lex;
  Gin5(ideal(y^2-xz, x^2z-yz^2), 2); -- choose dangerously small range [-2,2]:
                                     -- ==> answer might be wrong
</example>
    </description>

    <syntax>
Gin(I: IDEAL): IDEAL
Gin(I: IDEAL, Range: INT): IDEAL
Gin5(I: IDEAL): IDEAL
Gin5(I: IDEAL, Range: INT): IDEAL
</syntax>

    <types>
      <type>ideal</type>
      <type>cocoaserver</type>
    </types>

    <keys>
    <key>cocoalib</key>
    <key>generic initial ideal</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>GlobalMemory</title>
    <short_description>contents of global memory</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This function prints the contents of the global memory which are not
bound to rings: variables prefixed by <tt>MEMORY</tt> but not by
<tt>MEMORY.ENV</tt>.  Untagging the value returned by <tt>GlobalMemory</tt> gives a
list of strings which are identifiers for the global variables.  The
command <tt>fields(MEMORY)</tt> gives the same set of strings.
<par/>
For more information about memory in CoCoA, see the chapter entitled
<ref>Memory Management</ref>.

<example>
  Use R ::= QQ[x,y,z];
  A := 3;
  ENV.R.B := 7;
  MEMORY.C := 6;
  GlobalMemory();
["C", "DEV", "ENV", "ERR", "PKG"]
-------------------------------
  MEMORY.ENV;  -- the record holding the rings defined during the
               -- CoCoA session
Record[QQ := QQ, QQt = QQ[t], R := QQ[x,y,z], ZZ := ZZ]
-------------------------------
  Memory();  -- the working memory
["A", "It"]
-------------------------------
  Memory(R);  -- the global variables bound to the ring R
["B"]
-------------------------------
</example>
    </description>

    <syntax>
GlobalMemory():TAGGED("Memory")
</syntax>

    <seealso>
      <see>Memory</see>
      <see>Memory Management</see>
    </seealso>

    <types>
      <type>memory</type>
      <type>system</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>GradingDim</title>
    <short_description>Number of components in weighted degree</short_description>

    <description>
<par/>
This function returns the grading dimension of a polynomial ring, i.e.
how many of the rows of OrderMatrix are to be taken as specifying the grading.

<example>
/**/  OrdM := CompleteToOrd(RowMat([2,3]));
/**/  P := NewPolyRing(QQ, ["x","y"], OrdM, 1);
/**/  GradingDim(P);
1
</example>
    </description>

    <syntax>
GradingDim(P):INT
</syntax>

    <seealso>
      <see>NewPolyRing</see>
      <see>WeightsMatrix</see>
    </seealso>

    <types>
      <type>ring</type>
    </types>

  </command>

 </chapter_letter>
 <!-- ===  CHAPTER  =============================================== -->
 <chapter_letter>
   <title>H</title>

<!-- ===  COMMAND-rm Head =============================================== -->
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>HColon</title>
    <short_description>ideal or module quotient</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
The function <ttref>colon</ttref> returns the quotient of M by N:
the ideal of all polynomials F such that F*G is in M for all G in N.
<par/>
This function computes the same ideal using a Hilbert-driven
algorithm. It differs from <ttref>colon</ttref> only when the input
is non-homogeneous, in which case, <tt>HColon</tt> may be faster.

<example>
  Use R ::= QQ[x,y];
  ideal(xy, x^2) : ideal(x);
ideal(y, x)
-------------------------------
  colon(ideal(x^2, xy), ideal(x, x-y^2));
ideal(x)
-------------------------------
  HColon(ideal(x^2, xy), ideal(x, x-y^2));
ideal(x)
-------------------------------
</example>
    </description>

    <syntax>
HColon(M:IDEAL, N:IDEAL):IDEAL
</syntax>

    <seealso>
      <see>HSaturation</see>
      <see>saturate</see>
      <see>HColon</see>
      <see>colon</see>
    </seealso>

    <types>
      <type>groebner</type>
      <type>groebner-basic</type>
      <type>ideal</type>
      <type>module</type>
      <type>polynomial</type>
      <type>moduleelem</type>
    </types>

  </command>
<!-- ===  COMMAND-rm Help =============================================== -->
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>HGBM</title>
    <short_description>intersection of ideals for zero-dimensional schemes</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This function computes the intersection of ideals corresponding to
zero-dimensional schemes: <ttref>GBM</ttref> is for affine schemes, and HGBM for
projective schemes.  The list L must be a list of ideals.  The function
<ttref>IntersectionList</ttref> should be used for computing the intersection of a
collection of general ideals.
<par/>
The name GBM comes from the name of the algorithm used: Generalized
Buchberger-Moeller.  The prefix H comes from Homogeneous since ideals
of projective schemes are necessarily homogeneous.

<example>
  Use QQ[x[0..2]];
  I1 := IdealOfProjectivePoints([[1,2,1], [0,1,0]]);   -- simple projective scheme
  I2 := IdealOfProjectivePoints([[1,1,1], [2,0,1]])^2; -- another projective scheme
  HGBM([I1, I2]);                                      -- intersect the ideals
ideal(x[0]^3 - x[0]x[1]^2 - 5x[0]^2x[2] + x[1]^2x[2] + 8x[0]x[2]^2 - 4x[2]^3,
 x[0]^2x[1] + x[0]x[1]^2 - 3x[0]x[1]x[2] - x[1]^2x[2] + 2x[1]x[2]^2,
 x[0]x[1]^3 - 2x[0]^2x[2]^2 - 5x[0]x[1]x[2]^2 - 4x[1]^2x[2]^2 +
8x[0]x[2]^3 + 10x[1]x[2]^3 - 8x[2]^4,
 x[0]x[1]^2x[2] + x[1]^3x[2] - 2x[0]^2x[2]^2 - 5x[0]x[1]x[2]^2
- 5x[1]^2x[2]^2 + 8x[0]x[2]^3 + 10x[1]x[2]^3 - 8x[2]^4,
 x[1]^4x[2] - 2x[1]^3x[2]^2 - 4x[0]^2x[2]^3 - 8x[0]x[1]x[2]^3
- 3x[1]^2x[2]^3 + 16x[0]x[2]^4 + 16x[1]x[2]^4 - 16x[2]^5)
-------------------------------
</example>
    </description>

    <syntax>
HGBM(L:LIST):IDEAL
</syntax>

    <seealso>
      <see>Finite Point Sets: Buchberger-Moeller</see>
      <see>IdealAndSeparatorsOfPoints</see>
      <see>IdealAndSeparatorsOfProjectivePoints</see>
      <see>IdealOfPoints</see>
      <see>IdealOfProjectivePoints</see>
      <see>GBM</see>
    </seealso>

    <types>
      <type>groebner</type>
      <type>ideal</type>
      <type>list</type>
      <type>points</type>
    </types>

    <keys>
    <key>fat</key>
    <key>point</key>
    <key>abbott</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>hilbert</title>
  <short_description>the Hilbert-Poincare' function</short_description>
  
<syntax>
Hilbert(R:RING or TAGGED("Quotient")):TAGGED("$hp.Hilbert")
Hilbert(R:RING or TAGGED("Quotient"), N:INT):INT
</syntax>
<description>
(sorry Hilbert for the lower-case: here we follow the naming
convention <em>single name goes lower-case</em>)
<par/>
This function is the same as <ttref>HilbertFn</ttref>.
</description>

<seealso>
  <see>HilbertFn</see>
</seealso>

<types>
  <type>groebner</type>
  <type>groebner-basic</type>
  <type>hilbert</type>
  <type>quotient</type>
  <type>ring</type>
</types>

<keys>
  <key>bigatti</key>
</keys>
</command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>HilbertBasisKer</title>
    <short_description>Hilbert basis for a monoid</short_description>

    <description>
This function returns a list whose components are lists (of
non-negative integers) representing the Hilbert basis for the monoid
of elements with non-negative coordinates in the kernel of M.

<example>
/**/  M := mat([[1,-2,3,4], [1, 0, 0, -1]]);
/**/  HilbertBasisKer(M);
[[0, 3, 2, 0], [1, 4, 1, 1], [2, 5, 0, 2]]

/**/  M * transposed(mat(It));
matrix([
  [0, 0, 0],
  [0, 0, 0]
])
</example>
    </description>

    <syntax>
HilbertBasisKer(M:MAT): LIST

where M is a matrix over ZZ.
</syntax>

    <seealso>
      <see>LinKerBasis</see>
    </seealso>

    <types>
      <type>matrix</type>
    </types>

    <keys>
      <key>hilbert basis positive kernel</key>
      <key>positive kernel hilbert basis</key>
      <key>positivekerhilbertbasis</key>
      <key>hilbertbasispositiveker</key>
    </keys>

  </command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>HilbertFn</title>
  <short_description>the Hilbert function</short_description>
  
<syntax>
HilbertFn(R:RING or IDEAL): TAGGED("$hp.Hilbert")
HilbertFn(R:RING or IDEAL, N:INT): INT
</syntax>
<description>
The first form of this function computes the Hilbert function for R.
The second form computes the N-th value of the Hilbert function.  The
weights of the indeterminates of R must all be 1.  If the input is not
homogeneous, the Hilbert function of the corresponding leading term
(initial) ideal or module is calculated.  For repeated evaluations of
the Hilbert function, use <ttref>EvalHilbertFn</ttref> instead
of <tt>Hilbert(R, N)</tt> in order to speed up execution.
<par/>
The coefficient ring must be a field.

<example>
/**/  Use R ::= QQ[t,x,y,z];
/**/  HilbertFn(R/ideal(z^2-x*y, x*z^2+t^3));
H(0) = 1
H(1) = 4
H(t) = 6*t -3   for t &gt;= 2

/**/  R2 := NewFreeModule(R, 2);
/**/  MGens := matrix(R, [[x^3,y^3], [x*y^2,0], [0,z^3]]);
/**/  M := SubmoduleRows(R2, MGens);
/**/  HilbertFn(M);
H(0) = 0
H(1) = 0
H(2) = 0
H(3) = 3
H(4) = 12
H(t) = (1/3)*t^3 +(3/2)*t^2 +(-101/6)*t +35   for t >= 5

/**/  HilbertFn(M,3)
3
/**/  HilbertFn(M,5);
30
</example>
</description>

<seealso>
  <see>EvalHilbertFn</see>
  <see>HilbertPoly</see>
  <see>HVector</see>
  <see>HilbertSeries</see>
</seealso>

<types>
  <type>groebner</type>
  <type>groebner-basic</type>
  <type>hilbert</type>
  <type>quotient</type>
  <type>ring</type>
</types>

</command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>HilbertPoly</title>
    <short_description>the Hilbert polynomial</short_description>

    <description>
This function returns the Hilbert polynomial for R as a polynomial in
the standard CoCoA ring QQt (= QQ[t]).
<par/>
The weights of the indeterminates of R must all be 1, and the
coefficient ring must be a field.
<par/>
If the input is not homogeneous, the Hilbert polynomial of the
corresponding leading term (initial) ideal or module is calculated.
For the Hilbert *function*, see <ttref>hilbert</ttref>.

<example>
/**/  Use R ::= QQ[w,x,y,z];
/**/  I := ideal(z^2-x*y, x*z^2+w^3);
/**/  Hilbert(R/I);
H(0) = 1
H(1) = 4
H(t) = 6*t-3   for t &gt;= 2

/**/  F := HilbertPoly(R/I);
/**/  F;  -- a polynomial in the ring Qt
6*t-3

/**/ T := indet(RingOf(F), 1);
/**/ subst(F, T, 3);
15
</example>
    </description>

    <syntax>
HilbertPoly(R:RING or TAGGED("Quotient")):POLY in the ring Qt.
</syntax>

    <seealso>
      <see>EvalHilbertFn</see>
      <see>hilbert</see>
      <see>HVector</see>
      <see>HilbertSeries</see>
    </seealso>

    <types>
      <type>groebner</type>
      <type>groebner-basic</type>
      <type>hilbert</type>
      <type>quotient</type>
      <type>ring</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>HilbertSeries</title>
  <short_description>the Hilbert-Poincare series</short_description>

<syntax>
HilbertSeries(M:MODULE or IDEAL or QuotientRing):TAGGED("$hp.PSeries")
</syntax>
<description>
This function computes the Hilbert-Poincare series of M.
The input, M, must be homogeneous (with respect to the first row of
the weights matrix).  In the standard case, i.e. the weights of all
indeterminates are 1, the result is simplified so that the power
appearing in the denominator is the dimension of M.
<par/>
The function <ttref>poincare</ttref> is exacly the same as <ttref>HilbertSeries</ttref>.
<par/>
NOTES:
<par/>
(i) the coefficient ring must be a field.
<par/>
(ii) these functions produce tagged objects: they cannot safely be
     (non-)equality to other values.
<par/>
Starting from release 4.7.5 the input may also be an ideal.
<par/>
For more information, see the article: A.M. Bigatti, <quotes>Computations of
Hilbert-Poincare Series</quotes> J. Pure Appl. Algebra, 119/3 (1997),
237--253.

<example>
/**/  Use R ::= QQ[t,x,y,z]; -- standard weights
/**/  HilbertSeries(R/ideal(R,[]));
(1) / (1-t)^4

/**/  HilbertSeries(R/ideal(t^2, x, y^3));
(1 + 2*t + 2*t^2 + t^3) / (1-t)

/**/  R2 := NewFreeModule(R, 2); -- MODULE
/**/  M := SubmoduleRows(R2, matrix(R, [[x^2,0], [0,z^3]]));
/**/  HilbertSeries(M);
(t^2 + t^3) / (1-t)^4

/**/  HilbertSeries(R2/M);  --***WORK IN PROGRESS***

/**/  Ws := RowMat([1,2,3,4]); -- weights and multigradings
/**/  P := NewPolyRing(QQ,["t","x","y","z"],CompleteToOrd(Ws),1);
/**/  Use P;
/**/  HilbertSeries(P/ideal(t^2, x, y^3));
---  Non-simplified HilbertPoincare' Series  ---
(1 - 2*t^2 + t^4 - t^9 + 2*t^11 - t^13) / ( (1-t)*(1-t^2)*(1-t^3)*(1-t^4) )

/**/  HilbertSeries(ideal(t^2, x, y^3));
---  Non-simplified HilbertPoincare' Series  ---
(2*t^2 - t^4 + t^9 - 2*t^11 + t^13) / ( (1-t)*(1-t^2)*(1-t^3)*(1-t^4) )

/**/  Ws := mat([[1,2,3,4],[0,0,5,8]]);
/**/  P := NewPolyRing(QQ,["t","x","y","z"],CompleteToOrd(Ws),2);
/**/  Use P;
/**/  HilbertSeries(P/ideal(t^2, x, y^3));
---  Non Simplified Pseries  ---
(1 - 2*t[1]^2 + t[1]^4 - t[1]^9*t[2]^15 + 2*t[1]^11*t[2]^15 - t[1]^13*t[2]^15) / ( (1-t[1])^1*(1-t[1]^2)*(1-t[1]^3*t[2]^5)*(1-t[1]^4*t[2]^8) )

/**/  Ws := mat([[1,2,3,4],[0,0,5,8]]);
/**/  P := NewPolyRing(QQ, ["t","x","y","z"], CompleteToOrd(Ws), 2);
/**/  Use P;
/**/  Poincare(P/ideal(t^2, y^3));
---  Non-simplified HilbertPoincare' Series  ---
(1 - t[1]^2 - t[1]^9*t[2]^15 + t[1]^11*t[2]^15) / 
    ((1-t[1])^1*(1-t[1]^2)*(1-t[1]^3*t[2]^5)*(1-t[1]^4*t[2]^8) )
</example>
</description>

<seealso>
  <see>dim</see>
  <see>multiplicity</see>
  <see>HilbertFn</see>
  <see>HVector</see>
  <see>HilbertSeriesShifts</see>
  <see>HilbertSeriesMultiDeg</see>
  <see>Weights Modifier</see>
  <see>WeightsMatrix</see>
</seealso>

<types>
  <type>groebner</type>
  <type>groebner-basic</type>
  <type>hilbert</type>
  <type>quotient</type>
  <type>ring</type>
</types>

<keys>
  <key>bigatti</key>
</keys>
</command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>HilbertSeriesMultiDeg</title>
    <short_description>the Hilbert-Poincare series wrt a multigrading</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This function computes the Hilbert-Poincare series of M.
The input, M, must be homogeneous with respect to the grading defined
by the second argument.
<par/>
The function <ttref>PoincareMultiDeg</ttref> is exacly the same as <ttref>HilbertSeriesMultiDeg</ttref>.
<par/>
NOTES:
CoCoA-4 has an intrinsic limitation on multigradings (<ttref>Weights Modifier</ttref>)
which does not allow zero-entries in the first row of the defining
matrix.
This function performs all the appropriate conversions for computing the
HilbertSeries wrt any positive grading (<ttref>IsPositiveGrading</ttref>).
<example>
  Use R ::= QQ[x,y,z];
  WM := mat([[1,0,0],[1,-1,0]]);
  HilbertSeriesMultiDeg(R/ideal(Indets())^2, WM);
</example>
    </description>

    <syntax>
HilbertSeriesMultiDeg(TAGGED("Quotient"), WM:MAT):TAGGED("$hp.PSeries")
</syntax>

    <seealso>
      <see>HilbertSeries</see>
      <see>Weights Modifier</see>
      <see>IsPositiveGrading</see>
      <see>PoincareMultiDeg</see>
    </seealso>

    <types>
      <type>groebner</type>
      <type>groebner-basic</type>
      <type>hilbert</type>
      <type>quotient</type>
      <type>ring</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>HilbertSeriesShifts</title>
    <short_description>the Hilbert-Poincare series</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This function computes the Hilbert-Poincare series of a
(single-graded) module M with shifts.
The input, M, must be homogeneous (with respect the weights list).
In the standard case, i.e. the weights of all indeterminates are 1,
the result is simplified so that the power appearing in the
denominator is the dimension of M.
<par/>
The function <ttref>PoincareShifts</ttref> is exacly the same as
<ttref>HilbertSeriesShifts</ttref>.
<par/>
NOTES:
<par/>
(i) the coefficient ring must be a field.
<par/>
(ii) these functions produce tagged objects: they cannot safely be
     (non-)equality to other values.
<par/>
For more information, see the article: A.M. Bigatti, <quotes>Computations of
Hilbert-Poincare Series</quotes> J. Pure Appl. Algebra, 119/3 (1997),
237--253.

<example>
  Use P ::= QQ[x,y,z];
  M := Module([x,y^3], [x-z,0]);
  HilbertSeriesShifts(M, [2,0]);  -- HilbertPoincare series of a shifted module
(2x^3) / (1-x)^3
-------------------------------
  PoincareShifts(P^2/M, [3,1]);   -- HP series of a shifted quotient module
(x + x^2 + 2x^3) / (1-x)^2
-------------------------------
</example>
    </description>

    <syntax>
HilbertSeriesShifts(M: Module, ShiftsList: LIST):TAGGED("$hp.PSeries")
HilbertSeriesShifts(M: TAGGED("Quotient"), ShiftsList: LIST)
                                           :TAGGED("$hp.PSeries")
</syntax>

    <seealso>
      <see>dim</see>
      <see>hilbert</see>
      <see>HVector</see>
      <see>multiplicity</see>
      <see>Weights Modifier</see>
      <see>WeightsMatrix</see>
    </seealso>

    <types>
      <type>groebner</type>
      <type>groebner-basic</type>
      <type>hilbert</type>
      <type>quotient</type>
      <type>ring</type>
    </types>

    <keys>
    <key>bigatti</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>HIntersection</title>
    <short_description>intersection of ideals</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
The function <tt>HIntersection</tt> returns the intersection of <tt>I_1,...,I_n</tt>
using a Hilbert-driven algorithm.  It differs from <ttref>intersect</ttref> only
when the input is non-homogeneous, in which case, <tt>HIntersection</tt>
may be faster.
<par/>
The coefficient ring must be a field.

<example>
  Use R ::= QQ[x,y,z];
  HIntersection(ideal(x-z,y-2z), ideal(x-2z,y-z));
ideal(x + y - 3z, y^2 - 3yz + 2z^2)
-------------------------------
</example>
    </description>

    <syntax>
HIntersection(I_1:IDEAL,...,I_n:IDEAL):IDEAL
HIntersectionList(L:LIST of IDEAL):IDEAL
</syntax>

    <seealso>
      <see>intersect</see>
      <see>IntersectionList</see>
      <see>HIntersectionList</see>
    </seealso>

    <types>
      <type>groebner</type>
      <type>groebner-basic</type>
      <type>ideal</type>
      <type>list</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>HIntersectionList</title>
    <short_description>intersection of ideals</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
The function <tt>HIntersectionList</tt> applies the function <tt>HIntersection</tt>
to the elements of a list, i.e., <tt>HIntersectionList([I_1,...,I_n])</tt> is
the same as <tt>HIntersection(I_1,...,I_n)</tt>.
<par/>
The coefficient ring must be a field.

<example>
  L := [ideal(x-z,y-2z), ideal(x-2z,y-z)];
  HIntersectionList(L);
ideal(x + y - 3z, y^2 - 3yz + 2z^2)
-------------------------------
</example>
    </description>

    <syntax>
HIntersectionList(L:LIST of IDEAL):IDEAL
</syntax>

    <seealso>
      <see>intersect</see>
      <see>IntersectionList</see>
      <see>HIntersection</see>
    </seealso>

    <types>
      <type>groebner</type>
      <type>groebner-basic</type>
      <type>ideal</type>
      <type>list</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>homog</title>
    <short_description>homogenize with respect to an indeterminate</short_description>

    <description>
This function returns the homogenization of E with respect to the
indeterminate X, which must have weight 1.  Note that in the case
where E is an ideal, <tt>Homogenized</tt> returns the ideal generated by the
homogenizations of all the elements of E, not just the homogenization
of the generators of E (see the example, below).  The coefficient ring
must be a field for this function to work reliably.

<example>
/**/  Use R ::= QQ[x,y,z,w];
/**/  homog(x^3-y, w);
x^3 -y*w^2

/**/  homog([x^3-y, x^4-z], w);
[x^3 -y*w^2, x^4 -z*w^3]

/**/  I := ideal(x^3-y, x^4-z);
/**/  homog(I, w);    -- don&apos;t just get the homogenizations of 
                      -- the generators of I
ideal(x*y -z*w, x^2*z -y^2*w, x^3 -y*w^2, y^3 -x*z^2)
</example>
    </description>

    <syntax>
homog(E:T, X:INDET):T

where T is of type RINGELEM or MODULEELEM, or a LIST of them, or
IDEAL, or MODULE
</syntax>

    <seealso>
    </seealso>

    <types>
      <type>groebner</type>
      <type>groebner-basic</type>
      <type>ideal</type>
      <type>polynomial</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>HomogElimMat</title>
    <short_description>matrix for elimination ordering</short_description>

    <description>
This function returns a matrix for a term ordering eliminating the
indeterminates with indices in <tt>ElimInd</tt> for homogeneous input
wrt the weights in the matrix <tt>W</tt>.
If you don't understand what this means use <ttref>ElimMat</ttref>
instead ;-)

<example>
/**/  HomogElimMat(mat([[1,5,0]]), [2,3]);
matrix( /*QQ*/
 [[1, 5, 0],
  [0, 1, 1],
  [0, 0, -1]]
 )
</example>
    </description>

    <syntax>
HomogElimMat(W:MAT, ElimInd:LIST): MAT
</syntax>

    <seealso>
      <see>elim</see>
      <see>ElimMat</see>
    </seealso>

    <types>
      <type>matrix</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>HSaturation</title>
    <short_description>saturation of ideals</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This functions returns the saturation of I with respect to J: the
ideal of polynomials F such that F*G is in I for all G in <formula>J^d</formula>
for some positive integer <formula>d</formula>.
<par/>
It calculates the saturation using a Hilbert-driven algorithm.
It differs from <ttref>saturate</ttref> only when the
input is inhomogeneous, in which case, <tt>HSaturation</tt> may be faster.
<par/>
The coefficient ring must be a field.

<example>
/**/  Use R ::= QQ[x,y];
/**/  I := ideal(x^4-x, y*x-2*x);
/**/  saturate(I, ideal(x));
ideal(y -2, x^3 -1)

  HSaturation(I, ideal(x)); -- ***** NOT YET IMPLEMENTED *****
</example>
    </description>

    <syntax>
HSaturation(I:IDEAL, J:IDEAL):IDEAL
</syntax>

    <seealso>
      <see>colon</see>
      <see>HColon</see>
      <see>saturate</see>
    </seealso>

    <types>
      <type>groebner</type>
      <type>groebner-basic</type>
      <type>ideal</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>HVector</title>
    <short_description>the h-vector of a module or quotient object</short_description>

    <description>
This function returns the h-vector of M, i.e., the
coefficients of the numerator of the simplified Poincare series for M.
M can be a module or a quotient.
<par/>
The weights of the indeterminates of the polynomial ring of M must all be 1,
and the coefficient ring must be a field.
<par/>
If the input is not homogeneous, the Hilbert function of the
corresponding leading term (initial) ideal or module is calculated.

<example>
/**/  Use R ::= QQ[t,x,y,z];
/**/  HVector(R/ideal(x,y,z)^5);
[1, 3, 6, 10, 15]

/**/  Poincare(R/ideal(x,y,z)^5);
(1 + 3t + 6t^2 + 10t^3 + 15t^4) / (1-t)
</example>
    </description>

    <syntax>
HVector(R:RING or TAGGED("Quotient")):LIST
</syntax>

    <seealso>
      <see>hilbert</see>
      <see>HilbertSeries</see>
    </seealso>

    <types>
      <type>groebner</type>
      <type>groebner-basic</type>
      <type>hilbert</type>
      <type>quotient</type>
      <type>ring</type>
    </types>

    <keys>
    <key>hnumerator</key>
    <key>hilbert numerator</key>
    <key>hilbert poincare numerator</key>
    </keys>
  </command>

 </chapter_letter>
 <!-- ===  CHAPTER  =============================================== -->
 <chapter_letter>
   <title>I</title>

<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>ideal</title>
    <short_description>convert an expression into an ideal</short_description>

    <description>
The first form returns the ideal generated by <tt>P_1,...P_n</tt>.  The second
form returns the ideal generated by the polynomials in L.  The third
form returns the ideal generated by the polynomials in M; it is the
same as <tt>Cast(M, IDEAL)</tt>, and requires that the module be a submodule of
the free module of rank 1.

<example>
/**/  Use R ::= QQ[x,y,z];
/**/  I := ideal(x-y^2, x*y-z);
/**/  I;
ideal(-y^2 +x, x*y -z)

/**/  L := [x*y-z, x-y^2];
/**/  J := ideal(L);
/**/  I = J;
true

/**/  M := Module([y^3-z],[x-y^2]);  --***OBSOLETE MANUAL: WORK IN PROGRESS***
/**/  ideal(M) = I;
true
</example>
    </description>

    <syntax>
ideal(P_1:POLY,...,P_n:POLY):IDEAL
ideal(L:LIST):IDEAL
ideal(M:MODULE):IDEAL

where L is a list of polynomials and M is contained in a free module
of rank 1.
</syntax>

    <types>
      <type>cast</type>
      <type>ideal</type>
    </types>

    <keys>
      <key>cast</key>
      <key>generated</key>
      <key>generators</key>
    </keys>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>IdealAndSeparatorsOfPoints</title>
    <short_description>ideal and separators for affine points</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This function computes the results of <ttref>IdealOfPoints</ttref> and
<ttref>SeparatorsOfPoints</ttref> together at a cost lower than making the two
separate calls.  The result is a record with three fields:
<verbatim>
    points     -- the points given as argument
    ideal      -- the result of IdealOfPoints
    separators -- the result of SeparatorsOfPoints
</verbatim>
Thus, if the result is stored in a variable with identifier X, then:
X.points will be the input list of points;
X.ideal will be the ideal of the set of points, with generators
forming the reduced Groebner basis for the ideal;
X.separators will be a list of polynomials whose i-th element will
take the value 1 on the i-th point and 0 on the others.
<par/>
NOTE:
<par/>
 * the current ring must have at least as many indeterminates as the
   dimension of the space in which the points lie;
<par/>
 * the base field for the space in which the points lie is taken to be
   the coefficient ring, which should be a field;
<par/>
 * in the polynomials returned, the first coordinate in the space is
   taken to correspond to the first indeterminate, the second to the
   second, and so on;
<par/>
 * if the number of points is large, say 100 or more, the returned
   value can be very large.  To avoid possible problems when printing
   such values as a single item we recommend printing out the elements
   one at a time as in this example:
<verbatim>
     X := IdealAndSeparatorsOfPoints(Pts);
     Foreach Element In gens(X.ideal) Do
       PrintLn Element;
     EndForeach;
</verbatim>

For ideals and separators of points in projective space, see
<ttref>IdealAndSeparatorsOfProjectivePoints</ttref>.

<example>
  Use R ::= QQ[x,y];
  Points := [[1, 2], [3, 4], [5, 6]];
  X := IdealAndSeparatorsOfPoints(Points);
  X.points;
[[1, 2], [3, 4], [5, 6]]
-------------------------------
  X.ideal;
ideal(x - y + 1, y^3 - 12y^2 + 44y - 48)
-------------------------------
  X.separators;
[1/8y^2 - 5/4y + 3, -1/4y^2 + 2y - 3, 1/8y^2 - 3/4y + 1]
-------------------------------
</example>
    </description>

    <syntax>
IdealAndSeparatorsOfPoints(Points:LIST):RECORD

where Points is a list of lists of coefficients representing a set of
<em>distinct</em> points in affine space.
</syntax>

    <seealso>
      <see>GBM</see>
      <see>HGBM</see>
      <see>GenericPoints</see>
      <see>IdealAndSeparatorsOfProjectivePoints</see>
      <see>IdealOfPoints</see>
      <see>IdealOfProjectivePoints</see>
      <see>Interpolate</see>
      <see>QuotientBasis</see>
      <see>SeparatorsOfPoints</see>
      <see>SeparatorsOfProjectivePoints</see>
    </seealso>

    <types>
      <type>groebner</type>
      <type>ideal</type>
      <type>list</type>
      <type>points</type>
      <type>record</type>
    </types>

    <keys>
    <key>zero</key>
    <key>buchbergermoeller</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>IdealAndSeparatorsOfProjectivePoints</title>
    <short_description>ideal and separators for points</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This function computes the results of <ttref>IdealOfProjectivePoints</ttref> and
<ttref>SeparatorsOfProjectivePoints</ttref> together at a cost lower than making
the two separate calls.  The result is a record with three fields:
<verbatim>
    points     -- the points given as argument
    ideal      -- the result of IdealOfProjectivePoints
    separators -- the result of SeparatorsOfProjectivePoints
</verbatim>
Thus, if the result is stored in a variable with identifier X, then:
X.ideal will be the ideal of the set of points, with generators
forming a reduced Groebner basis for the ideal;
X.separators will be a list of homogeneous polynomials whose i-th
element will be non-zero (actually 1, using the given representatives
for the coordinates of the points) on the i-th point and 0 on the others.
<par/>
NOTE:
<par/>
 * the current ring must have at least one more indeterminate than the
   dimension of the projective space in which the points lie, i.e, at
   least as many indeterminates as the length of an element of
   the input, Points;
<par/>
 * the base field for the space in which the points lie is taken to be
   the coefficient ring, which should be a field;
<par/>
 * in the polynomials returned, the first coordinate in the space is
   taken to correspond to the first indeterminate, the second to the
   second, and so on;
<par/>
 * if the number of points is large, say 100 or more, the returned
   value can be very large.  To avoid possible problems when printing
   such values as a single item we recommend printing out the elements
   one at a time as in this example:
<verbatim>
     X := IdealAndSeparatorsOfProjectivePoints(Pts);
     Foreach Element In gens(X.ideal) Do
       PrintLn Element;
     EndForeach;
</verbatim>

For ideals and separators of points in affine space, see
<ttref>IdealAndSeparatorsOfPoints</ttref>.

<example>
  Use R ::= QQ[x,y,z];
  Points := [[0,0,1],[1/2,1,1],[0,1,0]];
  X := IdealAndSeparatorsOfProjectivePoints(Points);
  X.points;
[[0, 0, 1], [1, 1, 1], [0, 1, 0]]
-------------------------------
  X.ideal;
ideal(xz - 1/2yz, xy - 1/2yz, x^2 - 1/4yz, y^2z - yz^2)
-------------------------------
  X.separators;
[-2x + z, x, -2x + y]
-------------------------------
</example>
    </description>

    <syntax>
IdealAndSeparatorsOfProjectivePoints(Points:LIST):RECORD

where Points is a list of lists of coefficients representing a set of
<em>distinct</em> points in projective space.
</syntax>

    <seealso>
      <see>HGBM</see>
      <see>GBM</see>
      <see>GenericPoints</see>
      <see>IdealAndSeparatorsOfPoints</see>
      <see>IdealOfPoints</see>
      <see>IdealOfProjectivePoints</see>
      <see>Interpolate</see>
      <see>QuotientBasis</see>
      <see>SeparatorsOfPoints</see>
      <see>SeparatorsOfProjectivePoints</see>
    </seealso>

    <types>
      <type>groebner</type>
      <type>ideal</type>
      <type>list</type>
      <type>points</type>
      <type>record</type>
    </types>

    <keys>
    <key>buchbergermoeller</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>IdealOfPoints</title>
    <short_description>ideal of a set of affine points</short_description>

<syntax>
IdealOfPoints(P:RING, Points:MAT):IDEAL

where Points is a list of lists of coefficients representing a set of
<em>distinct</em> points in affine space.
</syntax>

    <description>
<par/>
This function computes the reduced Groebner basis for the ideal of all
polynomials which vanish at the given set of points.  It returns the
ideal generated by that Groebner basis.
<par/>
NOTE:
<par/>
 * the current ring must have at least as many indeterminates as the
   dimension of the space in which the points lie;
<par/>
 * the base field for the space in which the points lie is taken to be
   the coefficient ring, which should be a field;
<par/>
 * in the polynomials returned, the first coordinate in the space is
   taken to correspond to the first indeterminate, the second to the
   second, and so on;
<!-- <par/> -->
<!--  * if the number of points is large, say 100 or more, the returned -->
<!--    value can be very large.  To avoid possible problems when printing -->
<!--    such values as a single item we recommend printing out the elements -->
<!--    one at a time as in this example: -->
<!-- <verbatim> -->
<!--      I := IdealOfPoints(P, Pts); -->
<!--      Foreach Element In gens(I) Do -->
<!--        PrintLn Element; -->
<!--      EndForeach; -->
<!-- </verbatim> -->
For ideals of points in projective space, see
<ttref>IdealOfProjectivePoints</ttref>.

<example>
/**/  Use P ::= QQ[x,y];
/**/  Points := mat([[1, 2], [3, 4], [5, 6]]);
/**/  I := IdealOfPoints(P, Points);
/**/  I;
ideal(x -y +1, y^3 -12*y^2 +44*y -48)

/**/  K := NewFractionField(NewPolyRing(QQ, ["a"]));
/**/  Use K;
/**/  Points := mat([[1,2,0], [3,4,a], [5,1,6]]);
/**/  Use P ::= K[x,y,z], Lex;
/**/  I := IdealOfPoints(P, Points);
/**/  indent(I);
ideal(
  z^3 +(-a -6)*z^2 +(6*a)*z,
  y +((-a -12)/(6*a^2 -36*a))*z^2 +((a^2 +72)/(6*a^2 -36*a))*z -2,
  x +((2*a -6)/(3*a^2 -18*a))*z^2 +((-2*a^2 +36)/(3*a^2 -18*a))*z -1
)
</example>
    </description>

    <seealso>
      <see>GBM</see>
      <see>HGBM</see>
      <see>GenericPoints</see>
      <see>IdealAndSeparatorsOfPoints</see>
      <see>IdealAndSeparatorsOfProjectivePoints</see>
      <see>IdealOfProjectivePoints</see>
      <see>Interpolate</see>
      <see>QuotientBasis</see>
      <see>SeparatorsOfPoints</see>
      <see>SeparatorsOfProjectivePoints</see>
    </seealso>

    <types>
      <type>groebner</type>
      <type>ideal</type>
      <type>list</type>
      <type>points</type>
    </types>

    <keys>
    <key>buchbergermoeller</key>
    <key>buchberger-moeller</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>IdealOfProjectivePoints</title>
    <short_description>ideal of a set of projective points</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This function computes the reduced Groebner basis for the ideal of
all homogeneous polynomials which vanish at the given set of points.
It returns the ideal generated by that Groebner basis.
<par/>
NOTE:
<par/>
 * the current ring must have at least one more indeterminate than the
   dimension of the projective space in which the points lie, i.e, at
   least as many indeterminates as the length of an element of
   the input, Points;
<par/>
 * the base field for the space in which the points lie is taken to be
   the coefficient ring, which should be a field;
<par/>
 * in the polynomials returned, the first coordinate in the space is
   taken to correspond to the first indeterminate, the second to the
   second, and so on;
<par/>
 * if the number of points is large, say 100 or more, the returned
   value can be very large.  To avoid possible problems when printing
   such values as a single item we recommend printing out the elements
   one at a time as in this example:
<verbatim>
     I := IdealOfProjectivePoints(Pts);
     Foreach Element In gens(I) Do
       PrintLn Element;
     EndForeach;
</verbatim>
For ideals of points in affine space, see <ttref>IdealOfPoints</ttref>.

<example>
  Use R ::= QQ[x,y,z];
  I := IdealOfProjectivePoints([[0,0,1],[1/2,1,1],[0,1,0]]);
  I;
ideal(xz - 1/2yz, xy - 1/2yz, x^2 - 1/4yz, y^2z - yz^2)
-------------------------------
  I.Gens;  -- the reduced Groebner basis
[xz - 1/2yz, xy - 1/2yz, x^2 - 1/4yz, y^2z - yz^2]
-------------------------------
</example>
    </description>

    <syntax>
IdealOfProjectivePoints(Points:LIST):IDEAL

where Points is a list of lists of coefficients representing a set of
<em>distinct</em> points in projective space.
</syntax>

    <seealso>
      <see>GBM</see>
      <see>HGBM</see>
      <see>GenericPoints</see>
      <see>IdealAndSeparatorsOfPoints</see>
      <see>IdealAndSeparatorsOfProjectivePoints</see>
      <see>IdealOfPoints</see>
      <see>Interpolate</see>
      <see>QuotientBasis</see>
      <see>SeparatorsOfPoints</see>
      <see>SeparatorsOfProjectivePoints</see>
    </seealso>

    <types>
      <type>groebner</type>
      <type>ideal</type>
      <type>list</type>
      <type>points</type>
    </types>

    <keys>
    <key>buchbergermoeller</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>IdentityMat</title>
    <short_description>the identity matrix</short_description>

    <description>
This function returns the NxN identity matrix.

<example>
 /**/ IdentityMat(QQ,3);
matrix([
  [1, 0, 0],
  [0, 1, 0],
  [0, 0, 1]
])
</example>
    </description>

    <syntax>
IdentityMat(R:RING, N:INT):MAT
</syntax>

    <types>
      <type>matrix</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>if</title>
  <short_description>conditional statement</short_description>
  

<syntax>
If B_1 Then C_1 EndIf
If B_1 Then C_1 Else D EndIf
If B_1 Then C_1 Elif B_2 Then C_2 Elif ... EndIf
If B_1 Then C_1 Elif B_2 Then C_2 Elif ... Else D EndIf

where the B_j are boolean expressions,
and the C_j and D are command sequences.
</syntax>
<description>
If <tt>B_n</tt> is the first in the sequence of the <tt>B_j</tt> to evaluate to True,
then <tt>C_n</tt> is executed.
If none of the <tt>B_j</tt> evaluates to True, then <tt>D</tt> is executed if present otherwise
nothing is done.
The construct, <tt>Elif B_j Then C_j</tt> can be repeated any number of times.
<par/>
NB: <tt>Elsif</tt> is no longer allowed.

<example>
  Define Sign(A)
    If A &gt; 0 Then Return 1;
    Elif A = 0 Then Return 0;
    Else Return -1;
    EndIf;
  EndDefine;
/**/  Sign(3);
1
</example>
</description>

<keys>
  <key>else</key>
</keys>

<seealso>
</seealso>

<types>
  <type>command</type>
  <type>programming</type>
  <type>branching</type>
</types>

</command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>ILogBase</title>
    <short_description>integer part of the logarithm</short_description>

    <description>
This function computes the integer part (floor) of the logarithm of a
rational number in a given base.  The signs of X and Base are ignored.

<example>
/**/  ILogBase(128,2);
7

/**/  ILogBase(81.5,3);
4
</example>
    </description>

    <syntax>
ILogBase(X:RAT, Base:INT):INT
</syntax>

    <types>
      <type>integer</type>
      <type>rat</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>image</title>
    <short_description>apply ring homomorphism</short_description>

    <description>
This function maps the object E from one ring into the current ring as
determined by F.  Suppose the current ring is S, and E is an object
dependent on a ring R; then
<verbatim>
               Image(R::E, F)
</verbatim>
returns the object in S obtained by substituting <tt>F_i</tt> for the i-th
indeterminate of R in E.  Effectively, we get the image of E under
the ring homomorphism,
<verbatim>
               F: R   ---&gt;  S
                  x_i |--&gt; F_i,
</verbatim>
where <tt>x_i</tt> denotes the i-th indeterminate of R.
<par/>
Notes:
<par/>
1. The coefficient rings for the domain and codomain must be the same.
<par/>
2. If R = S, one may use <tt>Image(E, F)</tt> but in this case it may be
   easier to use <ttref>eval</ttref> or <ttref>subst</ttref>.
<par/>
3. The exact domain is never specified by the mapping F.  It is only
   necessary that the domain have the same number of indeterminates as F
   has components. Thus, we are abusing terminology somewhat in
   calling F a map.
<par/>
4. The second form of the function does not require the prefix <tt>R::</tt>
   since the prefix is associated automatically.
<par/>
5. If the object E in R is a polynomial or rational function (or list,
   matrix, or vector of these) which involves only indeterminates that are
   already in S, the object E can be mapped over to S without change
   using the command <ref>BringIn</ref>.

<example>
  Use C ::= QQ[u,v];   -- domain
  Use B ::= QQ[x,y];   -- another possible domain
  I := ideal(x^2-y);   -- an ideal in B
  Use A ::= QQ[a,b,c]; -- codomain
  F := RMap(a,c^2-ab);
  Image(B::xy, F);     -- the image of xy under F:B --&gt; A
-a^2b + ac^2
-------------------------------
  Image(C::uv, F);     -- the image of uv under F:C --&gt; A
-a^2b + ac^2
-------------------------------
  Image(I, F);         -- the image of the ideal I under F: B --&gt; A
ideal(a^2 + ab - c^2)
-------------------------------
  I; -- the prefix "B::" was not needed in the previous example since
     -- I is already labeled by B
B :: ideal(x^2 - y)
-------------------------------
  Image(B::Module([x+y,xy^2], [x,y]), F); -- the image of a module
Module([-ab + c^2 + a, a^3b^2 - 2a^2bc^2 + ac^4], [a, -ab + c^2])
-------------------------------
  X := C:: u+v;  -- X is a variable in the current ring (the codomain), A,
  X;             -- whose value is an expression in the ring C.
C :: u + v
-------------------------------
  Image(X, F);   -- map X to get a value in C
-ab + c^2 + a
-------------------------------
</example>
    </description>

    <syntax>
Image(R::E:OBJECT, F:TAGGED("RMap")):OBJECT
Image(V:OBJECT, F:TAGGED("RMap")):OBJECT

where R is the identifier for a ring and F has the form
RMap(F_1:POLY,...,F_n:POLY) or the form RMap([F_1:POLY,...,F_n:POLY]).
The number n is the number of indeterminates of the ring R. In the
second form, V is a variable containing a CoCoA object dependent on R
or not dependent on any ring.
</syntax>

    <seealso>
      <see>Accessing Other Rings</see>
      <see>BringIn</see>
      <see>QZP</see>
      <see>ZPQ</see>
      <see>Ring Mappings: the Image Function</see>
      <see>subst</see>
    </seealso>

    <types>
      <type>ring</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>ImplicitPlot</title>
    <short_description>outputs the zero locus of a bivariate polynomial to a file</short_description>

    <description>
This function evaluates the first argument, a bivariate polynomial, at
a grid of points in the range given by the second and third arguments.
The coordinates of the approximate zeroes are output to a file
called <quotes>CoCoAPlot</quotes>.
See <ttref>ImplicitPlotOn</ttref> for outputting to another file.
<par/>
This result can be plotted using your preferred plotting program.
For example, start <quotes>gnuplot</quotes> and then give it the command
<verbatim>  plot <quotes>CoCoAPlot</quotes></verbatim>
to see the plot.

<example>
/**/  Use R ::= QQ[x,y];
/**/  ImplicitPlot(x^2 + y^2 - 200^2, [-256,256], [-256,256]);
Plotting points...10%...20%...30%...40%...50%...60%...70%...80%...90%...100%
800 plotted points have been placed in the file CoCoAPlot
</example>

    </description>

    <syntax>
ImplicitPlot(F: POLY, Xrange: LIST, Yrange: LIST)
</syntax>

    <types>
      <type>list</type>
      <type>poly</type>
    </types>

    <seealso>
      <see>ImplicitPlotOn</see>
      <see>PlotPoints</see>
    </seealso>

    <keys>
    <key>gnuplot</key>
    <key>plot curve</key>
    </keys>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>ImplicitPlotOn</title>
    <short_description>outputs the zero locus of a bivariate polynomial to a file</short_description>

    <description>
This function is the same as <ttref>ImplicitPlot</ttref> with a fourth
argument giving the name of the file to print on.
<par/>
Note that the last argument is a STRING, the name of the file, and not
a DEVICE, as for <ttref>Print On</ttref>.

<example>
/**/  Use R::= QQ[x,y];
/**/  F := x^2 + y^2 - 100;
/**/  G := (x^2-1)*(x^2-36)*(x^2-64)*(x^2-100);
/**/  H := ((64*y^2-36*x^2)*(36*y^2-64*x^2)*(100*x^2-y^2)-1) * F - 1000^2 * G;

/**/  ImplicitPlotOn(F, [-16,16], [-16,16], "circle");
Plotting points...10%...20%...30%...40%...50%...60%...70%...80%...90%...100%
640 plotted points have been placed in the file circle

/**/  ImplicitPlotOn(G, [-16,16], [-16,16], "lines");

/**/  ImplicitPlotOn(H, [-16,16], [-16,16], "curve");
Plotting points...10%...20%...30%...40%...50%...60%...70%...80%...90%...100%
1962 plotted points have been placed in the file curve
</example>
After having produced the plot files using CoCoA-4,
start <quotes>gnuplot</quotes> and then give it the following commands:
<verbatim>  plot <quotes>circle</quotes>
  replot <quotes>lines</quotes>
  replot <quotes>curve</quotes>
</verbatim>
    </description>

    <syntax>
ImplicitPlotOn(F: POLY, Xrange: LIST, Yrange: LIST, PlotFileName: STRING)
</syntax>

    <types>
      <type>list</type>
      <type>poly</type>
    </types>

    <seealso>
      <see>ImplicitPlot</see>
      <see>PlotPointsOn</see>
    </seealso>

    <keys>
    <key>gnuplot</key>
    <key>plot curve</key>
    </keys>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>ImportByRef, ImportByValue</title>
    <short_description>import an external variable by reference or value</short_description>

    <syntax>
  ImportByRef X;
  ImportByValue X;

where <tt>X</tt> is the name of a variable in the containing scope.
</syntax>

    <description>
<em>***YOU PROBABLY SHOULDN'T USE THESE COMMANDS YET!***</em>
It seems that they can be used only inside anonymous functions (see <ttref>Func</ttref>).
<par/>
These commands "import" an external variable by reference or value.
<tt>ImportByValue</tt> creates a local variable with the given name, and its
initial value is taken from the variable of the same name in the context the
anonymous function is defined.  <tt>ImportByRef</tt> creates a reference to
the named variable in the context where the anonymous function is defined.

<example>
/**/  Define add(X)
/**/    AnonFn := Func(Y) ImportByValue X; Return X+Y; EndFunc;
/**/    Return AnonFn;
/**/  EndDefine;
/**/  add3 := add(3);
/**/  add3(2);
5
</example>
    </description>

    <seealso>
      <see>TopLevel</see>
      <see>Func</see>
    </seealso>

    <types>
      <type>function</type>
    </types>

    <keys>
      <key>closure</key>
      <key>variable capture</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>in</title>
    <short_description>list element selector in list constructor</short_description>

    <syntax>
[X in L:LIST | B:BOOL]:LIST
[E:expression | X in L]:LIST
[E:expression | X in L:LIST and B:BOOL]:LIST
</syntax>
    <description>
See <ttref>list constructors</ttref> for a full description.

<example>
/**/  [N in 1..10 | IsPrime(N)];
[2, 3, 5, 7]

/**/  [N^2 | N in 1..10 and IsPrime(N)];
[4, 9, 25, 49]
</example>
    </description>

    <seealso>
      <see>list costructors</see>
      <see>IsIn</see>
    </seealso>

    <types>
      <type>list</type>
    </types>

  </command>
<!--===  COMMAND  =============================================== -->
  <command>
    <title>incr, decr</title>
    <short_description>increment/decrement a counter</short_description>

    <syntax>
incr(ref X)
decr(ref X)

where <tt>X</tt> has an integer value.
</syntax>

    <description>
<tt>incr(ref X)</tt> adds 1 to the value of <tt>X</tt>.
<tt>decr(ref X)</tt> subtracts 1 from the value of <tt>X</tt>.

<par/>
These functions are useful when counting objects or adjusting pointers.
<example>
/**/ L := [(10^k-1)/9 | k in 1..99];
/**/ NPrimes := 0;
/**/ Foreach N in L Do
/**/   If IsPrime(N) Then incr(ref NPrimes); EndIf;
/**/ EndForeach;
/**/ PrintLn "The list L contains ", NPrimes, " primes.";
The list L contains 3 primes.
</example>
    </description>

    
    <types>
       <type>int</type>
    </types>

    <keys>
    <key>increment</key>
    <key>decrement</key>
    <key>counter</key>
    <key>++</key>
    </keys>

  </command>
<!--===  COMMAND  =============================================== -->
  <command>
    <title>indent</title>
    <short_description>prints in a more readable way</short_description>

    <syntax>
indent(X)
indent(X, N)
</syntax>

    <description>
This function prints the argument <tt>X</tt> splitting it into several
lines: a <tt>LIST</tt> or <tt>IDEAL</tt> is printed one element per
line, a <tt>RECORD</tt> one field per line.
<par/>
The second optional argument is for setting the level of recursive
indentation, useful for example when printing a list of records.

<example>
/**/ L := [1,2] >&lt; [3,4];
/**/ L;
[[1, 3], [1, 4], [2, 3], [2, 4]]

/**/ indent(L);
[
  [1, 3],
  [1, 4],
  [2, 3],
  [2, 4]
]

/**/ indent(L,2);
[
  [
    1,
    3
  ],
            --( Output suppressed )--
  [
    2,
    4
  ]
]

/**/ indent(Record[B:=1,A:=2]);
Record[
  A := 2,
  B := 1
]
</example>
    </description>

    <seealso>
      <see>format</see>
    </seealso>

    <types>
    </types>

    <keys>
    <key>indentation</key>
    <key>print</key>
    <key>string</key>
    </keys>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>indet</title>
    <short_description>individual indeterminates</short_description>

    <description>
This function returns the N-th indeterminate of the current ring.

<example>
/**/  Use R ::= QQ[x,y,z];
/**/  indet(R, 2);
y
</example>
    </description>

    <syntax>
indet(R:RING, N:INT):POLY
</syntax>

    <seealso>
      <see>IndetSubscripts</see>
      <see>IndetIndex</see>
      <see>IndetName</see>
      <see>indets</see>
      <see>NumIndets</see>
    </seealso>

    <types>
      <type>ring</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>IndetIndex</title>
    <short_description>index of an indeterminate</short_description>

    <description>
This function returns the position in which the indeterminate is
listed when the corresponding ring was created.

<example>
/**/  Use R ::= QQ[x,y,z]
/**/  IndetIndex(y);
2

/**/  Use R ::= QQ[x[1..2,1..2],y[1..2]];
/**/  Indets(R);
[x[1,1], x[1,2], x[2,1], x[2,2], y[1], y[2]]

/**/  IndetIndex(x[2,1]);
3

/**/  S ::= QQ[a,b,c];
/**/  IndetIndex(RingElem(S, "b"));
2
</example>
    </description>

    <syntax>
IndetIndex(X:INDET):INT
</syntax>

    <seealso>
      <see>indet</see>
      <see>IndetSubscripts</see>
      <see>IndetName</see>
      <see>indets</see>
      <see>NumIndets</see>
      <see>UnivariateIndetIndex</see>
    </seealso>

    <types>
      <type>ring</type>
    </types>

    <keys>
    <key>position</key>
    <key>variable</key>
    <key>indexed</key>
    <key>indices</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>IndetName</title>
    <short_description>the name of an indeterminate</short_description>

    <description>
This function returns the name of the indeterminate X as a string
(i.e. the letter without the indices).

<example>
/**/  Use R ::= QQ[x,y,z];
/**/  IndetName(indet(R, 2));
y

/**/  type(It);
STRING

/**/  Use R ::= QQ[a, x[1..3]];
/**/  IndetName(Indet(R, 2));
x

/**/  indent(IndetSymbols(R));
[
  Record[head := "a", indices := []],
  Record[head := "x", indices := [1]],
  Record[head := "x", indices := [2]],
  Record[head := "x", indices := [3]]
]
</example>
    </description>

    <syntax>
IndetName(X:INDET):STRING
</syntax>

    <seealso>
      <see>indet</see>
      <see>IndetSubscripts</see>
      <see>IndetIndex</see>
      <see>IndetSymbols</see>
      <see>NumIndets</see>
    </seealso>

    <types>
      <type>ring</type>
    </types>

    <keys>
    <key>variable</key>
    <key>indexed</key>
    <key>indices</key>
    </keys>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>indets</title>
    <short_description>list of indetermiantes in a PolyRing</short_description>

    <description>
With one argument (a polynomial ring), this function returns the
list of indeterminates of that polynomial ring.
With two arguments (the second a STRING), it returns the
list of all indeterminates whose name is the given string.
The indeterminates in the list appear in order of increasing
index (see the function <tt>IndetIndex</tt>).
<par/>
This function used to be called <tt>IndetsCalled</tt> up to version 5.0.3,
and <tt>AllIndetsCalled</tt> in CoCoA-4.
<par/>
Additionally, up to version 4.7.3 you could get this list just by giving
the name, <i>e.g.</i> <tt>Use QQ[x[0..4]];  x;</tt> but this syntax is no longer
allowed because it is ambiguous: 
<tt>x[2];</tt> is different from <tt>X := x;  X[2];</tt>

<example>
/**/  S ::= QQ[x,y,z];
/**/  Use R ::= QQ[a,b];
/**/  indets(CurrentRing);
[a, b]
/**/  indets(S);
[x, y, z]
/**/  indets(S,"x");
[x]
/**/  RingElem(S,"x"); -- work also if R is not a polynomial ring
x

/**/  Use R ::= QQ[x[1..4],a[1..2,1..3]];
/**/  indets(R,"x");
[x[1], x[2], x[3], x[4]]
/**/  indets(R,"a");
[a[1,1], a[1,2], a[1,3], a[2,1], a[2,2], a[2,3]]
/**/  indets(R,"b");
[]
</example>
    </description>

    <syntax>
indets(R:RING):LIST
indets(R:RING, X:STRING):LIST
</syntax>

    <seealso>
      <see>indet</see>
      <see>IndetSubscripts</see>
      <see>IndetIndex</see>
      <see>IndetName</see>
      <see>NumIndets</see>
    </seealso>

    <types>
      <type>ring</type>
    </types>

    <keys>
    <key>allindetscalled</key>
    <key>variables</key>
    <key>indexed</key>
    <key>indices</key>
    <key>indeterminates</key>
    <key>indeterminate named</key>
    <key>indeterminate names</key>
    <key>indet range</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>IndetSubscripts</title>
    <short_description>the index of an indeterminate</short_description>

    <description>
This function returns the subscripts of the name of the argument,
an indeterminate (used to be called <tt>IndetInd</tt>).
<par/>
Please note the difference with <ttref>IndetIndex</ttref>.

<example>
/**/  Use R ::= QQ[x[1..3,1..2],y,z];
/**/  IndetSubscripts(x[3,2]);
[3, 2]
/**/  IndetSubscripts(y);
[]
/**/  IndetIndex(RingElem(R, ["x",3,2]));
6
/**/  IndetSubscripts(RingElem(R, ["x",3,2]));
[3, 2]
</example>
    </description>

    <syntax>
IndetSubscripts(X:INDET):LIST
</syntax>

    <seealso>
      <see>indet</see>
      <see>IndetIndex</see>
      <see>IndetName</see>
      <see>IndetSymbols</see>
      <see>indets</see>
      <see>NumIndets</see>
    </seealso>

    <types>
      <type>ring</type>
    </types>

    <keys>
    <key>variable</key>
    <key>indexed</key>
    <key>indices</key>
    <key>indetind</key>
    </keys>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>IndetSymbols</title>
    <short_description>the names of the indeterminates in a PolyRing</short_description>

    <description>
This function returns the list of the symbols in a polynomial ring.
A symbol is a record with head (as <ttref>IndetName</ttref>) and subscripts
(as <ttref>IndetSubscripts</ttref>)

<example>
/**/  Use R ::= QQ[x,y,z];
/**/  indent(IndetSymbols(R));
[
  Record[head := "x", indices := []],
  Record[head := "y", indices := []],
  Record[head := "z", indices := []]
]

/**/  Use R ::= QQ[a, x[1..3]];
/**/  indent(IndetSymbols(R));
[
  Record[head := "a", indices := []],
  Record[head := "x", indices := [1]],
  Record[head := "x", indices := [2]],
  Record[head := "x", indices := [3]]
]
/**/  IndetName(Indet(R, 2));
x
</example>
    </description>

    <syntax>
IndetSymbols(P:RING):RECORD
</syntax>

    <seealso>
      <see>indet</see>
      <see>IndetSubscripts</see>
      <see>IndetIndex</see>
      <see>IndetName</see>
      <see>NumIndets</see>
      <see>SymbolRange</see>
    </seealso>

    <types>
      <type>ring</type>
    </types>

    <keys>
    <key>variable</key>
    <key>indexed</key>
    <key>indices</key>
    </keys>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>InducedHom</title>
    <short_description>homomorphism induced by a homomorphism</short_description>

    <description>
InducedHom(R, phi) -- where R is a QuotientRing, gives the
homomorphism R/I into S induced by phi: R into S (which must have
the base ring of RmodI as its domain, and whose kernel must
contain the defining ideal of RmodI)

InducedHom(FrF, phi) -- may be partial where FrF is a
FractionField, gives the homomorphism induced by phi (which must
have the base ring of FrF as its domain). Note that the resulting
homomorphism may be only partial (e.g. if ker(phi) is non-trivial,
or if the codomain is not a field). 

<example>
/**/ Use R ::= QQ[x,y];
/**/ RmodI := NewQuotientRing(R, ideal(x^2-1));

/**/ Use S ::= QQ[a,b,c];
/**/ SmodJ := NewQuotientRing(S, ideal(a^2-1));

/**/ phi := PolyAlgebraHom(R,S,[a,b]);
/**/ Use R;
/**/ phi(x);
a
/**/ psi := InducedHom(RmodI, CanonicalHom(S,SmodJ)(phi));
/**/ Use RmodI;
/**/ psi(x);
(a)
</example>
    </description>

    <syntax>
InducedHom(RmodI:RING, phi:RINGHOM): RINGHOM
</syntax>

    <seealso>
      <see>NewQuotientRing</see>
      <see>CanonicalHom</see>
      <see>PolyAlgebraHom</see>
      <see>PolyRingHom</see>
    </seealso>

    <types>
      <type>ring</type>
      <type>RINGHOM</type>
    </types>

    <keys>
    <key>quotienting homomorphism</key>
    </keys>

  </command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>InitialIdeal</title>
  <short_description>Initial ideal</short_description>

<syntax>
InitialIdeal(I:IDEAL, Inds:LIST): IDEAL
</syntax>
<description>

The <em>initial form</em> of a polynomial F is the homogeneous
component of F of the lowest degree (in contrast with the <em>leading
form</em>, see <ttref>LF</ttref>, <ttref>DF</ttref>).
The <em>initial ideal</em> of the ideal <tt>I</tt> is the ideal
generated by the initial forms of all polynomials in <tt>I</tt>.
It is also called <em>tangent cone</em> (which strictly is the variety
defined by the initial ideal).
<par/>
The implementation is based on Lazard's method (see Kreuzer-Robbiano,
Commutative Computer Algebra II, pg.463).
<example>
/**/  Use R ::= QQ[x,y,z];
/**/  InitialIdeal(ideal(x^3-y), [x,y,z]);
ideal(-y)
/**/  TgCone(ideal(x^3+x^2-y^2));
ideal(x^2 -y^2)

/**/  I := ideal(x^3-y*z, y^2-x*z, z^2-x^2*y);
/**/  TgCone(I); -- same as InitialIdeal(I, [x,y,z]);
ideal(y^2 -x*z, z^2, -y*z)
</example>
</description>

<types>
  <type>ideal</type>
</types>

<keys>
  <key>tangentcone</key>
  <key>tangent cone</key>
</keys>

<seealso>
  <see>InitialIdeal</see>
  <see>PrimaryPoincare</see>
</seealso>

</command>
<!--===  COMMAND  =============================================== -->
<!--   <command> -->
<!--     <title>InputForm</title> -->
<!--     <short_description>prints a version suitable for input</short_description> -->

<!--     <description> -->
<!-- This function returns the argument in a form which is suitable as -->
<!-- input.  ** not yet implemented ** -->

<!-- <example> -->
<!-- /**/  A := "hello world"; -->
<!-- /**/  Print A; -->
<!-- hello world -->
<!-- /**/  Print InputForm(A); -->
<!-- "hello world"; -->
<!-- </example> -->
<!--     </description> -->

<!--     <syntax> -->
<!-- InputForm(???):??? -->
<!-- </syntax> -->

<!--     <seealso> -->
<!--       <see>indent</see> -->
<!--     </seealso> -->

<!--     <types> -->
<!--     </types> -->

<!--     <keys> -->
<!--     <key>print</key> -->
<!--     <key>InputForm</key> -->
<!--     <key>string</key> -->
<!--     </keys> -->

<!--   </command> -->
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>insert</title>
    <short_description>insert an object in a list</short_description>

    <description>
This function inserts E into the list L as the N-th component.

<example>
/**/  L := ["a","b","d","e"];
/**/  insert(ref L,3,"c");
/**/  L;
["a", "b", "c", "d", "e"]
</example>
    </description>

    <syntax>
insert(ref V:LIST, N:INT, E:OBJECT):NULL

where V is a variable containing a list.
</syntax>

    <seealso>
      <see>append</see>
      <see>remove</see>
    </seealso>

    <types>
      <type>list</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>Interpolate</title>
    <short_description>interpolating polynomial</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This function returns a multivariate polynomial which takes given
values at a given set of points.
<par/>
NOTE:
<par/>
 * the current ring must have at least as many indeterminates as the
   dimension of the space in which the points lie;
<par/>
 * the base field for the space in which the points lie is taken to be
   the coefficient ring, which should be a field;
<par/>
 * in the polynomials returned, the first coordinate in the space is
   taken to correspond to the first indeterminate, the second to the
   second, and so on;
<par/>
 * if the number of points is large, say 100 or more, the returned
   value can be very large.  To avoid possible problems when printing
   such values as a single item we recommend printing out the elements
   one at a time as in this example:

<example>
  X := Interpolate(Pts, Vals);
  Foreach Element In X Do
    PrintLn Element;
  EndForeach;

  Use QQ[x,y];
  Points := [[1/2, 2], [3/4, 4], [5, 6/11], [-1/2, -2]];
  Values := [1/2,1/3,1/5,-1/2];
  F := Interpolate(Points, Values);
  F;
-46849/834000y^2 - 1547/52125x + 13418/52125y + 46849/208500
-------------------------------
  [Eval(F, P) | P In Points] = Values;  -- check
True
-------------------------------
</example>
    </description>

    <syntax>
Interpolate(Points:LIST, Values:LIST):POLY

where Points is a list of lists of coefficients representing a set of
<em>distinct</em> points and Values is a list of the same size containing
numbers from the coefficient ring.
</syntax>

    <types>
      <type>list</type>
      <type>points</type>
      <type>polynomial</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>interreduce, interreduced</title>
    <short_description>interreduce a list of polynomials or vectors</short_description>

    <description>
These functions reduce each polynomial (resp., vector) using the other
polynomials (resp., vectors) as reduction rules. The process
terminates when each is in normal form with respect to the
others.  The function <tt>interreduce</tt> takes a variable containing a list
and overwrites that variable with the interreduced list.  The second
returns an interreduced list without affecting its arguments.
<par/>
Note <em>OBSOLETE</em> that the definition of normal form depends on the current
value of the option FullRed of the panel GROEBNER.  If FullRed is False
it means that a polynomial (resp., vector) is in normal form when its
leading term with respect to the current term ordering cannot be
reduced. If FullRed is True it means that a polynomial (resp., vector)
is in normal form if and only if each monomial cannot be reduced.

<example>
/**/  interreduced([x^3-x*y^2+y*z, x*y, z]);
[x*y, z, x^3]

/**/  L := [x^3-x*y^2+y*z, x*y, z];
/**/  interreduce(ref L);
/**/  L;
[x*y, z, x^3]
</example>
<!-- /**/  Unset FullRed;  // FullRed = False -->
<!-- /**/  Use R ::= QQ[x,y,z]; -->
<!-- /**/  interreduced([x^3-x*y^2+y*z, x*y, z]); -->
<!-- [x^3 - x*y^2 + y*z, x*y, z] -->

<!-- /**/  Set FullRed;  // FullRed = True (the default value) -->

    </description>

    <syntax>
interreduce(ref V:LIST of POLY):NULL
interreduce(ref V:LIST of MODULEELEM):NULL

interreduced(L:LIST of POLY):LIST of POLY
interreduced(L:LIST of MODULEELEM):LIST of MODULEELEM
</syntax>

    <types>
      <type>ideal</type>
      <type>module</type>
      <type>list</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>intersect</title>
    <short_description>intersect lists, ideals, or modules</short_description>

    <description>
The function <tt>intersect</tt> returns the intersection of <tt>E_1,...,E_n</tt>.
In the case where the <tt>E_i</tt>&apos;s are lists, it returns the elements common
to all of the lists.
<par/>
The coefficient ring must be a field.
<par/>
NOTE: In order to compute the intersection of inhomogeneous ideals, it
may be faster to use the function <tt>HIntersection</tt>.  To compute the
intersection of ideals corresponding to zero-dimensional schemes, see
the commands <ttref>GBM</ttref> and <ttref>HGBM</ttref>.

<example>
/**/ Use R ::= QQ[x,y,z];
/**/ Points := [[0,0], [1,0], [0,1], [1,1]]; -- a list of points in the plane
/**/  I := ideal(x, y); -- the ideal for the first point
/**/  Foreach P In Points Do
        I := intersect(I, ideal(x-P[1]*z,y-P[2]*z));
      EndForeach;
/**/  I;  -- the ideal for (the projective closure of) Points
ideal(y^2 -y*z, x^2 -x*z)

  Intersection(["a","b","c"], ["b","c","d"]);
["b", "c"]
-------------------------------
</example>
    </description>

    <syntax>
Intersection(E_1:LIST,....,E_n:LIST):LIST
Intersection(E_1:IDEAL,...,E_n:IDEAL):IDEAL
Intersection(E_1:MODULE,....,E_n:MODULE):MODULE
</syntax>

    <seealso>
      <see>GBM</see>
      <see>HGBM</see>
      <see>IntersectionList</see>
      <see>HIntersection</see>
      <see>HIntersectionList</see>
    </seealso>

    <types>
      <type>groebner</type>
      <type>groebner-basic</type>
      <type>ideal</type>
      <type>list</type>
      <type>module</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>IntersectList</title>
    <short_description>intersect lists, ideals, or modules</short_description>

    <description>
The function <tt>IntersectionList</tt> applies the function <tt>Intersection</tt> to
the elements of a list, i.e., <tt>IntersectionList([X_1,...,X_n])</tt> is the
same as <tt>Intersection(X_1,...,X_n)</tt>.
<par/>
The coefficient ring must be a field.
<par/>
NOTE: In order to compute the intersection of inhomogeneous ideals, it
may be faster to use the function <tt>HIntersectionList</tt>.
<par/>
To compute the intersection of ideals corresponding to
zero-dimensional schemes, see the commands <ttref>GBM</ttref> and <ttref>HGBM</ttref>.

<example>
/**/  Use R ::= QQ[x,y,z];
/**/  Points := [[0,0],[1,0],[0,1],[1,1]]; -- a list of points in the plane
/**/  IntersectionList([ ideal(x-P[1]*z, y-P[2]*z)  |  P In Points]);
ideal(y^2 - y*z, x^2 - x*z)

/**/  Intersection(["a","b","c"],["b","c","d"]);
["b", "c"]

/**/  IntersectionList([ideal(x,y), ideal(y^2,z)]);
ideal(y*z, x*z, y^2)

/**/  It = intersect(ideal(x,y), ideal(y^2,z));
true
</example>
    </description>

    <syntax>
IntersectionList(L:LIST of LIST):LIST
IntersectionList(L:LIST of IDEAL):IDEAL
IntersectionList(L:LIST of MODULE):MODULE
</syntax>

    <seealso>
      <see>IdealOfProjectivePoints</see>
      <see>IdealOfPoints</see>
      <see>HGBM</see>
      <see>HIntersection</see>
      <see>HIntersectionList</see>
      <see>intersect</see>
    </seealso>

    <types>
      <type>groebner</type>
      <type>groebner-basic</type>
      <type>ideal</type>
      <type>list</type>
      <type>module</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>inverse</title>
    <short_description>multiplicative inverse</short_description>

    <description>
This function computes the multiplicative inverse of its argument.
It is included for use when writing inverse(X) comes more naturally
than writing <tt>X^(-1)</tt>, though both notations are functionally equivalent.

<example>
/**/  inverse(mat(QQ, [[1,2], [3,4]]));
matrix([
  [-2, 1],
  [3/2, -1/2]
])
</example>
    </description>

    <syntax>
inverse(X:OBJECT):OBJECT
</syntax>

    <types>
      <type>integer</type>
      <type>matrix</type>
      <type>polynomial</type>
      <type>rat</type>
      <type>ratfun</type>
      <type>zmod</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>InverseSystem</title>
    <short_description>Inverse system of an ideal of derivations</short_description>

    <syntax>
InverseSystem(I:IDEAL, D:INT)
</syntax>

    <description>
Given an ideal of derivations <tt>I</tt>, and an integer <tt>D</tt>, this function
computes the degree <tt>D</tt> part of the inverse system of <tt>I</tt>.
<par/>
For the sake of simplicity Forms/Polynomials and Derivations live in
the same ring, the distinction between them is purely formal.

<example>
/**/  Use QQ[x,y,z];
/**/  InverseSystem(ideal(x^3+x*y*z), 3);
[z^3, y*z^2, x*z^2, y^2*z, x^2*z, y^3, x*y^2, x^2*y, x^3 - 6*x*y*z]
</example>
    </description>

    <seealso>
      <see>DerivationAction</see>
      <see>PerpIdealOfForm</see>
    </seealso>

    <types>
      <type>ideal</type>
      <type>int</type>
    </types>

    <keys>
    <key>carlini</key>
    </keys>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>IO.SprintTrunc</title>
    <short_description>convert to a string and truncate</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This function works like <ttref>sprint</ttref>, turning the value of the
expression E into a string, but if the string has length greater than
N-1, it is truncated and the string <tt>...</tt> is concatenated.  This
function is useful in formatting reports of results.

<example>
  Use R ::= QQ[x,y];
  I := ideal(x,y);
  $io.SprintTrunc(I,4);
Idea...
-------------------------------
</example>
    </description>

    <syntax>
$io.SprintTrunc(E:OBJECT, N:INT):STRING
</syntax>

    <seealso>
      <see>format</see>
      <see>sprint</see>
    </seealso>

    <types>
      <type>io</type>
      <type>printing</type>
      <type>string</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>iroot</title>
    <short_description>integer part of r-th root of an integer</short_description>

    <description>
This function computes the R-th root of an integer.  If the argument is
not a perfect R-th power it returns the integer part of the root.

<example>
/**/  iroot(25, 2);
5
/**/  iroot(99, 3);
4
/**/  iroot(-1, 3);
-1
</example>
    </description>

    <syntax>
iroot(N:INT, R: INT):INT
</syntax>

    <seealso>
      <see>ILogBase</see>
    </seealso>

    <types>
      <type>integer</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>IsAntiSymmetric</title>
    <short_description>checks if a matrix is anti-symmetric</short_description>

    <description>
This function tests whether the square matrix M is anti-symmetric.

<example>
/**/  M := mat([[0, 1, 2], [-1, 0, 3], [-2, -3, 0]]);
/**/  IsAntiSymmetric(M);
true
</example>
    </description>

    <syntax>
IsAntiSymmetric(M: MAT): BOOL
</syntax>

    <types>
      <type>matrix</type>
      <type>boolean</type>
    </types>

    <seealso>
      <see>IsSymmetric</see>
    </seealso>

  </command>

<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>IsConstant</title>
    <short_description>checks if a ringelem is in the coefficient ring</short_description>

    <description>
This function tests whether the value of a RINGELEM of a polynomial ring
actually lies in the image of the coefficient ring.  It is equivalent to
checking that the degree in each indeterminate is 0.

<example>
/**/  QQx ::= QQ[x];
/**/  Use QQx[y,z];
/**/  IsConstant(y+1);
false
/**/  IsConstant(x+1);
true
</example>
    </description>

    <syntax>
IsConstant(X:RINGELEM):BOOL
</syntax>

    <types>
      <type>ringelem</type>
      <type>boolean</type>
    </types>

    <seealso>
      <see>indets</see>
    </seealso>

  </command>

<!-- ===  COMMAND  =============================================== -->
<command>
  <title>IsContained</title>
  <short_description>checks if A is Contained in B</short_description>
  
<syntax>
IsContained(A:IDEAL, B:IDEAL): BOOL
IsContained(A:MODULE, B:MODULE): BOOL
</syntax>

<description>
This function tests whether A is contained in B.
Was <tt>&lt;=</tt> in CoCoA-4: this syntax is no longer supported.

<example>
/**/  Use QQ[x,y,z];
/**/  IsContained(ideal(x), ideal(x+y, x-y));
true
</example>
</description>

<types>
  <type>ideal</type>
  <type>module</type>
  <type>boolean</type>
</types>

<seealso>
  <see>IsIn</see>
  <see>IsSubset</see>
</seealso>

</command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>IsDefined</title>
    <short_description>check if an expression has been defined</short_description>

    <description>
This function returns true if E is defined, otherwise it returns false.
Typically, it is used to check if a name has already been assigned.
<par/>
To know if a field in a record has been assigned use <ttref>fields</ttref>.

<example>
/**/  IsDefined(MyVariable);
false

/**/  MyVariable := 3;
/**/  IsDefined(MyVariable);
true
</example>
    </description>

    <syntax>
IsDefined(E)

where E is a CoCoA expression.
</syntax>

    <types>
      <type>memory</type>
      <type>boolean</type>
    </types>

    <seealso>
      <see>fields</see>
    </seealso>

  </command>

<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>IsDiagonal</title>
    <short_description>checks if a matrix is diagonal</short_description>

    <description>
This function tests whether the square matrix M is diagonal.

<example>
/**/  M := mat([[0, 1, 2],[-1, 0, 3],[-2, -3, 0]]);
/**/  IsDiagonal(M);
false
</example>
    </description>

    <syntax>
IsDiagonal(M: MAT): BOOL
</syntax>

    <types>
      <type>matrix</type>
      <type>boolean</type>
    </types>

    <seealso>
      <see>IsSymmetric</see>
      <see>DiagMat</see>
    </seealso>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>IsDivisible</title>
    <short_description>checks if A is divisible by B</short_description>
<description>
This function says whether <tt>A</tt> is divisible by <tt>B</tt>; it
returns <tt>true</tt> if so, otherwise <tt>false</tt>.

<example>
/**/  Use QQ[x,y,z];
/**/   IsDivisible(x, x^2*(y-1));
false
/**/   IsDivisible(x^2*(y-1), x);
true
</example>
    </description>

    <syntax>
IsDivisible(A:RINGELEM, B:RINGELEM): BOOL
</syntax>

    <types>
      <type>boolean</type>
      <type>RingElem</type>
    </types>

    <keys>
    <key>divides</key>
    <key>divisibility</key>
    <key>factor</key>
    <key>isfactor</key>
    </keys>

    <seealso>
      <see>valuation</see>
    </seealso>
  </command>

<!-- ===  COMMAND  =============================================== -->
<command>
  <title>IsElem</title>
  <short_description>checks if A is an element of B</short_description>
  
<syntax>
IsElem(A:RINGELEM, B:IDEAL): BOOL
IsElem(A:MODULEELEM, B:MODULE): BOOL
</syntax>

<description>
This function tests whether A is an element of B.
Same as the command <ttref>IsIn</ttref>, but works on fewer types: it
is in CoCoA-5 for compatibility with the C++ function in CoCoALib.

<example>
/**/  Use QQ[x,y,z];
/**/  IsElem(x, ideal(x+y, x-y));
true

/**/  x IsIn ideal(x+y, x-y);
true
</example>
</description>

<types>
  <type>ideal</type>
  <type>module</type>
  <type>boolean</type>
</types>

<seealso>
  <see>IsIn</see>
</seealso>

</command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>IsEven, IsOdd</title>
    <short_description>test whether an integer is even or odd</short_description>

    <description>
These functions test whether an integer is even or odd.

<example>
/**/  IsEven(3);
false
/**/  IsOdd(3);
true
</example>
    </description>

    <syntax>
IsEven(N:INT):BOOL
IsOdd(N:INT):BOOL
</syntax>

    <seealso>
      <see>IsZero</see>
    </seealso>

    <types>
      <type>boolean</type>
      <type>integer</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>IsFactorClosed</title>
  <short_description>test whether a list of PPs is factor closed</short_description>

<syntax>
IsFactorClosed(L: LIST of power products): BOOL
</syntax>

<description>
A set of power products is factor closed iff it contains every factor of
every one of its elements.  This function checks whether the given set
is factor closed (also known as "order-ideal").  It is an error if L is empty.

<example>
/**/  use P ::= QQ[x,y,z];
/**/  IsFactorClosed([1, x, x^2]);
true
/**/  IsFactorClosed([one(P), y^2]);
false
</example>
</description>

<seealso>
  <see>QuotientBasis</see>
  <see>LT</see>
  <see>TmpNBM</see>
  <see>IsStronglyStable</see>
</seealso>

<types>
  <type>boolean</type>
  <type>list</type>
  <type>monomial</type>
</types>

<keys>
  <key>factor-closed</key>
  <key>factor closed</key>
  <key>order-ideal</key>
  <key>order ideal</key>
</keys>
</command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>IsField</title>
    <short_description>test whether a ring is a field</short_description>

    <description>
This function tests whether a ring is a field.

<example>
/**/  IsField(ZZ);
false
/**/  IsField(QQ);
true
</example>
    </description>

    <syntax>
IsField(R:RING):BOOL
</syntax>

    <seealso>
      <see>IsFiniteField</see>
    </seealso>

    <types>
      <type>boolean</type>
      <type>ring</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>IsFiniteField</title>
    <short_description>test whether a ring is a finite field</short_description>

    <description>
This function tests whether a ring is a finite field.

<example>
/**/  IsFiniteField(ZZ);
false
/**/  IsFiniteField(QQ);
false
/**/  Fp::=ZZ/(7); IsFiniteField(Fp);
true
</example>
    </description>

    <syntax>
IsFiniteField(R:RING):BOOL
</syntax>

    <seealso>
      <see>IsField</see>
      <see>IsPthPower</see>
      <see>LogCardinality</see>
      <see>PthRoot</see>
    </seealso>

    <types>
      <type>boolean</type>
      <type>ring</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>IsHomog</title>
    <short_description>test whether given polynomials are homogeneous</short_description>

    <description>
The first form of this function returns True if F is homogeneous.
The second form returns True if every element of L is homogeneous.
Otherwise, they return False.  The third form returns True if the
ideal/module can be generated by homogeneous elements, and False
if not.  Homogeneity is with respect to the first row of the weights
matrix.
<par/>
NOTE: when the grading dimension is 0 everything is trivially true.
For safety reasons (from version 5.0.3) <tt>IsHomog</tt> throws an error
in this case, e.g. <tt>IsHomog(x-1)</tt> gives error instead of a
possibly misleading <tt>true</tt>.
<example>
/**/  Use R ::= QQ[x,y];
/**/  IsHomog(x^2-x*y);
true

/**/  IsHomog(x-y^2);
false

/**/  IsHomog([x^2-x*y, x-y^2]);
false

/**/  R := NewPolyRing(QQ, ["x","y"], mat([[2,3],[1,2]]), 1);
/**/  Use R;
/**/  IsHomog(x^3*y^2+y^4);
true

/**/  R := NewPolyRing(QQ, ["x","y"], mat([[2,3],[1,2]]), 2);
/**/  Use R;
/**/  IsHomog(x^3*y^2+y^4);
false

/**/  Use R ::= QQ[x,y];
/**/  IsHomog(ideal(x^2+y,y));
true

/**/  Use R ::= QQ[x,y], Lex;  -- note: GradingDim = 0
/**/  IsHomog(x-1); -- !!! ERROR !!! instead of "true"
</example>
    </description>

    <syntax>
IsHomog(F:POLY or MODULEELEM):BOOL
IsHomog(L:LIST):BOOL
IsHomog(I:IDEAL or MODULE):BOOL
</syntax>

    <seealso>
      <see>deg</see>
      <see>wdeg</see>
      <see>Weights Modifier</see>
    </seealso>

    <types>
      <type>boolean</type>
      <type>polynomial</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>IsIn</title>
    <short_description>check if one object is contained in another</short_description>

    <description>
The semantics of IsIn is explained in the following table:
<verbatim>
    ----------------------------------------------------------------
   | POLY   IsIn  IDEAL   checks for ideal membership.              |
   | MODULEELEM IsIn  MODULE  checks for module membership.         |
   | OBJECT IsIn  LIST    checks if the list contains the object.   |
   | STRING IsIn  STRING  checks if the first string is a substring |
   |                      of the second one.                        |
    ----------------------------------------------------------------
                       IsIn operator
</verbatim>
    </description>

    <syntax>
E IsIn F

where E and F are CoCoA objects.  For a precise description of
allowable objects, see the full online help entry.
</syntax>

    <types>
      <type>boolean</type>
      <type>ideal</type>
      <type>list</type>
      <type>module</type>
      <type>polynomial</type>
      <type>string</type>
      <type>moduleelem</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>IsIndet</title>
    <short_description>checks argument is an indetermiante</short_description>

    <description>
This function tests whether <tt>X</tt> is an indeterminate.  If so, it
returns <tt>true</tt>; otherwise it returns <tt>false</tt>.  An error
is signalled if <tt>X</tt> is not a <tt>RINGELEM</tt> or
if <tt>RingOf(X)</tt> is not a polynomial ring.

<example>
/**/  Use QQ[x,y,z];
/**/  IsIndet(x);
true
/**/  IsIndet(x-1);
false
</example>
    </description>

    <syntax>
IsIndet(X:RINGELEM): BOOL
</syntax>

    <types>
      <type>boolean</type>
      <type>polynomial</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>IsInRadical</title>
    <short_description>check if a polynomial (or ideal) is in a radical</short_description>

    <description>
This function tests whether the first argument, a polynomial or an
ideal, is contained in the radical of the second argument, an ideal.

<par/>
This function is much faster than asking <tt>F IsIn Radical(I);</tt>.

<example>
/**/  Use QQ[x,y,z];
/**/  I := ideal(x^6*y^4, z);
/**/  IsInRadical(x*y, I);
true

/**/  IsInRadical(ideal(x,y), I);
false

/**/  MinPowerInIdeal(x*y, I);
6
</example>
    </description>

    <syntax>
IsInRadical(F:POLY, I:IDEAL):BOOL
IsInRadical(J:IDEAL, I:IDEAL):BOOL
</syntax>

    <seealso>
      <see>MinPowerInIdeal</see>
      <see>radical</see>
    </seealso>

    <types>
      <type>ideal</type>
      <type>poly</type>
      <type>boolean</type>
    </types>

    <keys>
    <key>radical membership</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>IsInSubalgebra</title>
    <short_description>check if one polynomial is in a subalgebra</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This function tests whether a polynomial is in a subalgebra, i.e. can
be written as a polynomial expression of the elements of a list.

<example>
  Use QQ[s,t];
  L := [s^3, s^2t, st^2, t^3];
  IsInSubalgebra(s^6t^6, L);
True
-------------------------------
  SAM := SubalgebraMap(L);
  IsInSubalgebra(s^6t^6, SAM);  -- more efficient for repeated checks
True
-------------------------------
</example>
    </description>

    <syntax>
SubalgebraRepr(F:POLY, L:LIST):POLY
SubalgebraRepr(F:POLY, M:TAGGED("$alghom.Map")):POLY
</syntax>

    <seealso>
      <see>SubalgebraMap</see>
      <see>SubalgebraRepr</see>
      <see>ker</see>
    </seealso>

    <types>
      <type>list</type>
      <type>poly</type>
    </types>

    <keys>
    <key>homomorphism</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>IsLexSegment</title>
    <short_description>checks if an ideal is lex-segment</short_description>

    <description>
This function tests whether the monomial ideal I is a lex-segment ideal.

<example>
/**/  Use R ::= QQ[x,y,z];
/**/  I := ideal(x*y^3, y^4, x^3, x^2*y, x^2*z);
/**/  IsLexSegment(I);
false
</example>
    </description>

    <syntax>
IsLexSegment(I: MONOMIAL IDEAL): BOOL
</syntax>

    <seealso>
      <see>IsStable</see>
      <see>IsStronglyStable</see>
      <see>LexSegmentIdeal</see>
    </seealso>

    <types>
      <type>monomialideal</type>
      <type>boolean</type>
    </types>

    <keys>
    <key>lex segment</key>
    <key>lex-segment</key>
    </keys>
  </command>

<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>IsNumber</title>
    <short_description>checks if the argument is a number</short_description>

    <description>
This function returns True if E has type INT, RAT, or ZMOD.
Otherwise, it returns False.
***Suppressed***
<example>
  Use R ::= QQ[x,y];
  IsNumber(x+y);
False
-------------------------------
  IsNumber(3);
True
-------------------------------
  IsNumber(3%5);
True
-------------------------------
</example>
    </description>

    <syntax>
IsNumber(E:OBJECT):BOOL
</syntax>

    <types>
      <type>boolean</type>
      <type>integer</type>
      <type>rat</type>
      <type>zmod</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>IsPositiveGrading</title>
    <short_description>check if a matrix defines a positive grading</short_description>

    <description>
This function determines whether a matrix defines a positive grading,
i.e. foreach column the first nonnegative entry is positive.

<example>
/**/  IsPositiveGrading(LexMat(5));
true

/**/  IsPositiveGrading(LexMat(5),3); --considering only the first three rows
false

/**/  IsPositiveGrading(mat([[0,2,3], [1, -1, 0]]));
true

/**/  IsPositiveGrading(mat([[1,1], [0,-1], [-1, 0]]));
true
</example>
    </description>

    <syntax>
IsPositiveGrading(M:MAT):BOOL
IsPositiveGrading(M:MAT,N:INT):BOOL
</syntax>

    <seealso>
      <see>HilbertSeriesMultiDeg</see>
    </seealso>

    <types>
      <type>matrix</type>
      <type>boolean</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>IsPrime</title>
    <short_description>prime integer test</short_description>

    <description>
This function determines whether a positive integer is prime; if <code>N</code>
is not positive, and error is signalled.  This function may be extremely slow
when <code>N</code> is a large prime; in practice it is usually better to call
<code>IsProbPrime</code>.

For the curious: currently, the function first performs a probabilistic check
(Miller-Rabin), if that passes, it then verifies primality (via Lucas test).

<example>
/**/  IsPrime(32003);
true

/**/  IsPrime(10^100);
false
</example>
    </description>

    <syntax>
IsPrime(N:INT):BOOL
</syntax>

    <seealso>
      <see>IsProbPrime</see>
      <see>NextPrime</see>
    </seealso>

    <types>
      <type>integer</type>
      <type>boolean</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>IsProbPrime</title>
    <short_description>checks if an integer is a probable prime</short_description>

    <description>
This function returns True if its integer argument passes a fairly
stringent primality test; otherwise it returns False.  There is a very
small chance of the function returning True even though the argument is
composite; if it returns False, we are certain that the argument is composite.
Some people call it a compositeness test.

<example>
/**/  IsProbPrime(2);
true

/**/  IsProbPrime(1111111111111111111);
true

/**/  [N in 1..1111 | IsProbPrime((10^N-1)/9)]; -- only five values are known
[2, 19, 23, 317, 1031]                          -- next might be 49081
</example>
    </description>

    <syntax>
IsProbPrime(N:INT):BOOL
</syntax>

    <seealso>
      <see>IsPrime</see>
      <see>NextProbPrime</see>
    </seealso>

    <types>
      <type>boolean</type>
      <type>integer</type>
    </types>

    <keys>
    <key>primality test</key>
    <key>compositeness test</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>IsPthPower</title>
    <short_description>p-th power test</short_description>

    <description>
This function determines whether a polynomial over a finite
field (of char p) is a p-th power.
If the coefficient ring is not a finite field then an error is signalled.

<example>
/**/  Use ZZ/(7)[x];
/**/  IsPthPower(x^7+3);
true
/**/  IsPthPower(x^6+3);
false
</example>
    </description>

    <syntax>
IsPthPower(X:RINGELEM):BOOL
</syntax>

    <seealso>
      <see>IsFiniteField</see>
      <see>PthRoot</see>
    </seealso>

    <types>
      <type>ringelem</type>
      <type>boolean</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>isqrt</title>
    <short_description>(truncated) square root of an integer</short_description>

    <description>
This function computes the square root of an integer.  If the argument is
not a perfect square it returns the integer part of the square root.

<example>
/**/  isqrt(16);
4

/**/  isqrt(99);
9

/**/  isqrt(-1);
ERROR: Value must be non-negative
 isqrt(-1);
 ^^^^^^^^^
</example>
    </description>

    <syntax>
isqrt(N:INT):INT
</syntax>

    <types>
      <type>integer</type>
      <type>boolean</type>
    </types>

    <keys>
    <key>square root</key>
    <key>squareroot</key>
    </keys>
  </command>

<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>IsServerReady</title>
    <short_description>checks if CoCoAServer is running</short_description>

    <description>
***** OBSOLETE: CoCoAServer no longer needed *****
<par/>
This function tests whether the CoCoAServer is running.
Warning: this may cause a harmless error message in the CoCoAServer window.

<example>
  IsServerReady();
True
</example>
    </description>

    <syntax>
IsServerReady(): BOOL
</syntax>

    <types>
      <type>cocoaserver</type>
      <type>boolean</type>
    </types>

  </command>

<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>IsStable</title>
    <short_description>checks if an ideal is stable</short_description>

    <description>
This function tests whether the monomial ideal I is stable.

<example>
/**/  Use R ::= QQ[x,y,z];
/**/  I := ideal(x*y^3, y^4, x^3, x^2*y, x^2*z);
/**/  IsStable(I);
true
</example>
    </description>

    <syntax>
IsStable(I: MONOMIAL IDEAL): BOOL
</syntax>

    <seealso>
      <see>IsLexSegment</see>
      <see>IsStronglyStable</see>
      <see>LexSegmentIdeal</see>
    </seealso>

    <types>
      <type>monomialideal</type>
      <type>boolean</type>
    </types>

  </command>

<!-- ===  COMMAND  =============================================== -->
<command>
  <title>IsStdGraded</title>
  <short_description>checks if the grading is standard</short_description>
  
<syntax>
IsStdGraded(P: PolyRing): BOOL
</syntax>
<description>
This function tests whether <tt>P</tt> is standard graded,
<em>i.e.</em> <tt>GradingDim</tt> is 1 and all indeterminates
in <tt>P</tt> have degree 1.

<example>
/**/  P ::= QQ[x,y,z];
/**/  IsStdGraded(P);
true
/**/  P ::= QQ[x,y,z], lex;
/**/  IsStdGraded(P);
false
/**/  P := NewPolyRing(QQ, ["x","y"], mat([[2,3],[1,2]]), 1);
/**/  IsStdGraded(P);
false
</example>
</description>

<seealso>
  <see>NewPolyRing</see>
  <see>wdeg</see>
</seealso>

<types>
  <type>ring</type>
  <type>boolean</type>
</types>

</command>

<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>IsStronglyStable</title>
    <short_description>checks if an ideal is strongly stable</short_description>

    <description>
This function tests whether the monomial ideal I is strongly stable
(Borel-fixed in characteristic 0).

<example>
/**/  Use R ::= QQ[x,y,z];
/**/  I := ideal(x*y^3, y^4, x^3, x^2*y, x^2*z);
/**/  IsStronglyStable(I);
true
</example>
    </description>

    <syntax>
IsStronglyStable(I: MONOMIAL IDEAL): BOOL
</syntax>

    <seealso>
      <see>IsLexSegment</see>
      <see>IsStable</see>
    </seealso>

    <types>
      <type>monomialideal</type>
      <type>boolean</type>
    </types>

    <keys>
    <key>borel</key>
    </keys>
  </command>

<!-- ===  COMMAND  =============================================== -->
<command>
  <title>IsSubset</title>
  <short_description>checks if the elements of one list are a subset of another</short_description>

<syntax>
IsSubset(L:LIST, M:LIST):BOOL
</syntax>

<description>
This function returns True if MakeSet(L) is contained in MakeSet(M);
otherwise it returns False.
<par/>
NOTE: The obsolete function SubSet used to have the same behaviour.

<example>
/**/  IsSubset([1,1,2],[1,2,3,"a"]);
true

/**/  IsSubset([1,2],["a","b"]);
false

/**/  IsSubset([],[1,2]);
true
</example>
</description>

<seealso>
  <see>IsContained</see>
  <see>IsIn</see>
  <see>EqSet</see>
  <see>MakeSet</see>
  <see>subsets</see>
</seealso>

<types>
  <type>boolean</type>
  <type>list</type>
</types>

<keys>
  <key>subset</key>
</keys>
</command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>IsSymmetric</title>
    <short_description>checks if a matrix is symmetric</short_description>

    <description>
This function tests whether the square matrix M is symmetric.

<example>
 /**/ M := mat([
               [1, 2, 3],
               [2, 4, 5],
               [3, 5, 6]
               ]);
/**/ IsSymmetric(M);
true
</example>
    </description>

    <syntax>
IsSymmetric(M: MAT): BOOL
</syntax>

    <types>
      <type>matrix</type>
      <type>boolean</type>
    </types>

    <seealso>
      <see>IsAntiSymmetric</see>
    </seealso>

  </command>

<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>IsTerm</title>
    <short_description>checks if the argument is a term</short_description>

    <description>
The function determines whether X is a term.  For a polynomial, a
<em>term</em> is a power-product, i.e., a product of indeterminates.  Thus,
<formula>xy^2z</formula> is a term, while <formula>4xy^2z</formula> and <formula>xy+2z^3</formula> are not.  For a vector, a
term is a power-product times a standard basis vector, e.g.,
<formula>(0, xy^2z, 0)</formula>.

<example>
/**/  Use R ::= QQ[x,y,z];
/**/  IsTerm(x+y^2);
false

/**/  IsTerm(x^3*y*z^2);
true

/**/  IsTerm(5*x^3*y*z^2);
false

/**/  IsTerm(Vector(0,0,x*y*z)); --***OBSOLETE MANUAL: WORK IN PROGRESS***
true

/**/  IsTerm(Vector(x^2,y^2)); --***OBSOLETE MANUAL: WORK IN PROGRESS***
false

/**/  IsTerm(5*x^2);
false
</example>
    </description>

    <syntax>
IsTerm(X:POLY or MODULEELEM):BOOL
</syntax>

    <types>
      <type>polynomial</type>
      <type>moduleelem</type>
      <type>boolean</type>
    </types>

  </command>

<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>IsTermOrdering</title>
    <short_description>check if a matrix defines a term-ordering</short_description>

    <description>
This function determines whether a square matrix defines a term-ordering,
i.e. if its determinant is non-zero and if foreach column the first
nonnegative entry is positive.

<example>
/**/  IsTermOrdering(LexMat(5));
true

/**/  IsTermOrdering(StdDegRevLexMat(5));
true

/**/  IsTermOrdering(RevLexMat(5));
false
</example>
    </description>

    <syntax>
IsTermOrdering(M:MAT):BOOL
</syntax>

    <seealso>
      <see>Custom Term-Orderings</see>
    </seealso>

    <types>
      <type>matrix</type>
      <type>boolean</type>
    </types>

  </command>

<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>IsTree5</title>
    <short_description>checks if a facet complex is a tree</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This function is implemented in CoCoALib.
<par/>
This function tests whether the facet complex described by the
list L of square free power products is a tree, plus a list which:
<par/>
- is empty if L is a tree
<par/>
- contains three elements of a cycle of L if L is not a tree.
<par/>
Four options <tt>NOOPT</tt>,<tt>OPT</tt>,<tt>CS_NOOPT</tt>,<tt>CS_OPT</tt> are available as second
argument, specifying different algorithms; the default is <tt>CS_OPT</tt>.
<par/>
For a full description of the algorithms we refer to the paper by
M. Caboara, S. Faridi, and P. Selinger, <quotes>Simplicial cycles and
the computation of simplicial trees</quotes>, Journal of Symbolic Computation,
vol.42/1-2, pp.77-88 (2006).

<example>
  Use R ::= QQ[x,y,z,t];
  D := [xy, yz, zt, tx];
  IsTree5(D);
[False, [xy, xt, yt]]
-------------------------------
  IsTree5([xy, yz, zt]);
[True, [ ]]
-------------------------------
</example>
</description>

    <syntax>
IsTree5(L: LIST): [BOOL, LIST ]
IsTree5(L: LIST, "NOOPT"): [BOOL, LIST]
IsTree5(L: LIST, "OPT"): [BOOL, LIST]
IsTree5(L: LIST, "CS_NOOPT"): [BOOL, LIST]
IsTree5(L: LIST, "CS_OPT"): [BOOL, LIST]
</syntax>

    <types>
      <type>cocoaserver</type>
    </types>

    <seealso>
      <see>Introduction to CoCoAServer</see>
    </seealso>

    <keys>
    <key>caboara</key>
    <key>cocoalib</key>
    </keys>
</command>

<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>IsTrueGCDDomain</title>
    <short_description>test whether a ring is a true GCD domain</short_description>

    <description>
This function tests whether a ring is a (true) GCD domain but not a field.
CoCoA can compute GCDs of elements of a true GCD domain.

<example>
/**/  IsTrueGCDDomain(ZZ);
true
/**/  IsTrueGCDDomain(QQ);
false
</example>
    </description>

    <syntax>
IsTrueGCDDomain(R:RING):BOOL
</syntax>

    <seealso>
      <see>IsField</see>
    </seealso>

    <types>
      <type>boolean</type>
      <type>ring</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>IsZero</title>
    <short_description>test whether an object is zero</short_description>

    <description>
This function tests whether its argument is zero; the argument can be
of almost any type for which <em>zero</em> makes sense.

<example>
/**/  IsZero(23);
false

/**/  IsZero(3-3);
true

/**/  Use R ::= QQ[x,y];
/**/  IsZero(x^2+3*y-1);
false

/**/  IsZero(ideal(x^2,x*y^3));
false

/**/  F := NewFreeModule(R, 3);
/**/  zero(F);
[0, 0, 0]
/**/  IsZero(zero(F));
true
</example>
    </description>

    <syntax>
IsZero(X:OBJECT):BOOL
</syntax>

    <seealso>
      <see>IsEven, IsOdd</see>
      <see>zero</see>
    </seealso>

    <types>
      <type>boolean</type>
      <type>ideal</type>
      <type>integer</type>
      <type>matrix</type>
      <type>module</type>
      <type>polynomial</type>
      <type>rat</type>
      <type>ratfun</type>
      <type>moduleelem</type>
      <type>zmod</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>IsZeroDim</title>
    <short_description>test whether an ideal is zero-dimensional</short_description>

    <syntax>
IsZeroDim(I:IDEAL):BOOL
</syntax>

    <description>
This function tests whether its argument is zero-dimensional.

<example>
/**/  Use QQ[x,y,z];
/**/  IsZero(ideal(x));
false

/**/  IsZeroDim(ideal(x^3, y^4-x ,z-3));
true

/**/  IsZeroDim(ideal(x^2, x*y^3));
false
</example>
    </description>

    <seealso>
      <see>dim</see>
    </seealso>

    <types>
      <type>boolean</type>
      <type>ideal</type>
    </types>

  </command>

<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>IsZeroDivisor</title>
    <short_description>test whether a RINGELEM is a zero-divisor</short_description>

<syntax>
IsZeroDivisor(X:RINGELEM): BOOL
</syntax>
<description>
This function tests whether its argument is a zero-divisor.

<example>
/**/  Use P ::= QQ[x,y,z];
/**/  R := NewQuotientRing(P, ideal(x*y));
/**/  IsZeroDivisor(RingElem(R,x));
true
/**/  colon(ideal(zero(R)), ideal(RingElem(R,x)));
ideal((y))
</example>
</description>

<seealso>
  <see>colon</see>
</seealso>

<types>
  <type>boolean</type>
  <type>ideal</type>
</types>

  </command>

<!-- ===  COMMAND  =============================================== -->
<command>
  <title>It</title>
  <short_description>variable contatining the last result</short_description>

<syntax>
It
</syntax>
<description>
<tt>It</tt> is a top-level SYSTEM VARIABLE containing the "last"
result printed. (The CoCoA equivalent to GAP <tt>last</tt>)
<par/>
When CoCoA evaluates a standalone expression, the result is assigned to
the system variable named <tt>It</tt> (and then printed as if in a
<ref>PrintLn</ref> command).  You may use <tt>It</tt> in expressions
just like any other variable.

<example>
/**/  1+1; -- standalone expression ==> result is saved in "It".
2
/**/  It;
2

/**/  It+1;
3
/**/  It;
3

/**/  X := 17;  -- assignment is not a standalone expression, "It" is unchanged
/**/  It;
3
/**/  X+It;
20
</example>
</description>

<seealso>
  <see>print</see>
  <see>PrintLn</see>
  <see>Evaluation and Assignment</see>
</seealso>

<keys>
  <key>system variable</key>
  <key>The variable It</key>
</keys>
</command>

 </chapter_letter>
 <!-- ===  CHAPTER  =============================================== -->
 <chapter_letter>
   <title>J</title>

<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>jacobian</title>
    <short_description>the Jacobian of a list of polynomials</short_description>

    <description>
This function returns the Jacobian matrix of the polynomials in L
with respect to all the indeterminates of the current ring.

<example>
/**/  Use R ::= QQ[x,y];
/**/  L := [x-y, x^2-y, x^3-y^2];
/**/  jacobian(L);
matrix([
  [1, -1],
  [2*x, -1],
  [3*x^2, -2*y]
])
</example>
    </description>

    <syntax>
jacobian(L:LIST):MAT

where L is a list of polynomials.
</syntax>

    <types>
      <type>polynomial</type>
      <type>matrix</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>JanetBasis</title>
  <short_description>the Janet basis of an ideal</short_description>
  
<syntax>
JanetBasis(I:IDEAL):LIST
</syntax>
<description>
Thanks to Mario Albert.
<par/>
This function returns the Janet basis of an ideal.
<example>
/**/  Use R ::= QQ[x,y,z];
/**/  L := [x-y, x^2-z+1, x^3-y^2];
/**/  JanetBasis(ideal(L));
[x -y, z^2 -3*z +2, y*z -y -z +1, y^2 -z +1]
</example>
</description>

<types>
  <type>ideal</type>
  <type>list</type>
</types>

<keys>
  <key>janet basis</key>
</keys>

<seealso>
  <see>GBasis</see>
</seealso>
</command>

 </chapter_letter>
 <!-- ===  CHAPTER  =============================================== -->
 <chapter_letter>
   <title>K</title>

<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>ker</title>
    <short_description>Kernel of a K-algebra homomorphism</short_description>

    <description>
This function returns the kernel of a K-algebra homomorphism.

<example>
  Use QQ[s,t];
  L := [s^3, s^2t, st^2, t^3];
  SAM := SubalgebraMap(L);  --***OBSOLETE MANUAL: WORK IN PROGRESS***
  SAM;
Record[
  DomainIndets := SubalgebraRing::[x[1], x[2], x[3], x[4]],
  Images := CurrentRingEnv::[s^3, s^2t, st^2, t^3],
  ElimIdeal := AlgHomRing :: ideal(
  -y[1]^3 + x[1],
  -y[1]^2y[2] + x[2],
  -y[1]y[2]^2 + x[3],
  -y[2]^3 + x[4])
]
-------------------------------
  Ker(SAM);
SubalgebraRing :: ideal(x[3]^2 - x[2]x[4], x[2]x[3] - x[1]x[4], x[2]^2 - x[1]x[3])
-------------------------------
</example>
    </description>

    <syntax>
Ker(M:TAGGED("$alghom.Map")):IDEAL
</syntax>

    <seealso>
      <see>SubalgebraMap</see>
      <see>SubalgebraRepr</see>
      <see>IsInSubalgebra</see>
    </seealso>

    <types>
      <type>list</type>
      <type>poly</type>
    </types>

    <keys>
    <key>algebra</key>
    <key>homomorphism</key>
    </keys>
  </command>
 </chapter_letter>
 <!-- ===  CHAPTER  =============================================== -->
 <chapter_letter>
   <title>L</title>

<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>last</title>
    <short_description>the last N elements of a list</short_description>

    <description>
In the first form, the function returns the last element of L.  In
the second form, it returns the list of the last N elements of L.
<par/>
The CoCoA equivalent to GAP <tt>last</tt> is the variable <ttref>It</ttref>.

<example>
/**/  L := [1,2,3,4,5];
/**/  last(L);
5

/**/  last(L,3);
[3, 4, 5]
</example>
    </description>

    <syntax>
last(L:LIST):OBJECT
last(L:LIST, N:INT):OBJECT
</syntax>

    <seealso>
      <see>first</see>
      <see>tail</see>
      <see>It</see>
    </seealso>

    <types>
      <type>list</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>Latex</title>
    <short_description>LaTeX formatting</short_description>

    <description>
This function returns a string containing the argument formatted in LaTeX.
From version 4.7.5 it returns a string, so it can be printed on a file.
Can also be called as <tt>LaTeX</tt>.

<example>
/**/  Use R ::= QQ[x,y,z];
/**/  F := x^3+2*y^2*z;
/**/  Latex(F);
x^{3} + 2y^{2}z

/**/  M := mat([[1,2],[3,4]]);
/**/  Latex(M);
<backslash/>left( <backslash/>begin{array}{cc} 
  1 &amp; 2 <backslash/><backslash/>
  3 &amp; 4 <backslash/>end{array}<backslash/>right)

/**/  R ::= Q[x,y,z];
/**/  P := NewFractionField(R);
/**/  Use P;
/**/  F := (x+y)/(1-z)^3;
/**/  Latex(F);
<backslash/>frac{ - x - y} {z^{3}-3z^{2} + 3z-1}

/**/  Latex(ideal(x^2,y+z));
(x^{2},
 y +z)

  R := Res(ideal(x^2,y+z));  --***OBSOLETE MANUAL: WORK IN PROGRESS***
  D := OpenOFile("my-test");
  Print Latex(R) On D;
</example>
    </description>

    <syntax>
Latex(X:OBJECT):STRING
</syntax>

    <seealso>
      <see>format</see>
      <see>sprint</see>
    </seealso>

    <types>
      <type>io</type>
      <type>printing</type>
      <type>string</type>
    </types>

    <keys>
    <key>latex printing</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>LC</title>
    <short_description>the leading coefficient of a polynomial or vector</short_description>

    <description>
This function returns the leading coefficient of F, as determined by
the term-ordering of the ring to which F belongs.

<example>
/**/  Use R ::= QQ[x,y];
/**/  LC(x +3*x^2 -5*y^2);
3

/**/  F := NewFreeModule(R,3);
/**/  LC(ModuleElem(F, [0, 5*y+6*x^2, y^2]));
6
</example>
    </description>

    <syntax>
LC(F:POLY or MODULEELEM):RINGELEM
</syntax>

    <seealso>
      <see>coefficients</see>
      <see>CoeffOfTerm</see>
      <see>LT</see>
    </seealso>

    <types>
      <type>polynomial</type>
      <type>moduleelem</type>
    </types>

    <keys>
    <key>leading coefficient</key>
    </keys>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>lcm</title>
    <short_description>least common multiple</short_description>

    <description>
This function returns the least common multiple of <tt>F_1,...,F_n</tt>
or of the elements in the list L.
For the calculation of the GCDs and LCMs of polynomials, the
coefficient ring must be a field.

<example>
/**/  Use R ::= QQ[x,y];
/**/  F := x^2-y^2;
/**/  G := (x+y)^3;
/**/  lcm(F, G);
-x^4 -2*x^3*y +2*x*y^3 +y^4

/**/  IsDivisible(F*G, It);
true

/**/  lcm(F, G) * gcd(F,G) = F*G;
true

/**/  lcm([3*4,3*8,6*16]);
96
</example>
    </description>

    <syntax>
lcm(N:INT, M:INT):INT
lcm(L:LIST of INT):INT

lcm(F:RINGELEM, G:RINGELEM):RINGELEM
lcm(L:LIST of RINGELEM):RINGELEM
</syntax>

    <seealso>
      <see>div</see>
      <see>mod</see>
      <see>gcd</see>
    </seealso>

    <types>
      <type>groebner</type>
      <type>groebner-basic</type>
      <type>integer</type>
      <type>polynomial</type>
    </types>

    <keys>
    <key>least common multiple</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>len</title>
    <short_description>the length of an object</short_description>

    <description>
This function returns the <em>length</em> of an object, as summarized in
the table below:
<verbatim>
      ----------------------------------------------
     | type   | length                              |
     -----------------------------------------------|
     | INT    | 1                                   |
     | LIST   | number of items in the list         |
     | MODULE | length of gens(E)                   |
     | POLY   | number of monomials                 |
     | MODULEELEM | number of components            |
      ----------------------------------------------
               The operator <tt>len</tt>
</verbatim>

<example>
/**/  Use R ::= QQ[x,y];
/**/  L := ["a",2,3,[4,5]];
/**/  len(L);
4

/**/  len(L[1]);
1

/**/  len(L[4]);
2

/**/  F := x^2 + x*y + y^2 + x*y^4;
/**/  len(F);
4

/**/  NumTerms(F); --> is the same of len(F)!
4

/**/  len((x+y) - (x*y/x));
1

/**/  A := mat([[1,2],[3,4],[5,6]]);
/**/  len(A);
ERROR: len(matrix) not allowed, use NumRows(matrix) instead

/**/  NumRows(A); 
3
</example>
The function <ttref>size</ttref> returns the amount of memory used by the object.
    </description>

    <syntax>
len(E:STRING or LIST or RINGELEM):INT
</syntax>

    <seealso>
      <see>count</see>
      <see>size</see>
    </seealso>

    <types>
      <type>ideal</type>
      <type>integer</type>
      <type>list</type>
      <type>matrix</type>
      <type>module</type>
      <type>polynomial</type>
      <type>ratfun</type>
      <type>moduleelem</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>LexMat</title>
    <short_description>matrices for std. term-orderings</short_description>

    <description>
This function return the matrix defining a standard term-ordering.
These functions return matrices defining standard term-orderings.

<example>
  LexMat(3);
matrix([
  [1, 0, 0],
  [0, 1, 0],
  [0, 0, 1]
])
</example>
    </description>

    <syntax>
LexMat(N:INTEGER):MAT
</syntax>

    <seealso>
      <see>Orderings</see>
      <see>StdDegLexMat</see>
      <see>StdDegRevLexMat</see>
      <see>RevLexMat</see>
      <see>XelMat</see>
    </seealso>

    <types>
      <type>matrix</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>LexSegmentIdeal</title>
    <short_description>lex-segment ideal containing L, or with the same Hilbert fn as I</short_description>

    <description>
If the argument is a list of power-products L, this function returns the
smallest lex-segment ideal containing the power-products in L.
<par/>
If it is an ideal I, it returns the lex-segment ideal having the same
Hilbert function as I.

<example>
/**/  Use R ::= QQ[x,y,z];
/**/  LexSegmentIdeal([y^3]);
ideal(y^3, x*z^2, x*y*z, x*y^2, x^2*z, x^2*y, x^3)
/**/  LexSegmentIdeal(ideal(y^3));
ideal(x^3)
</example>
    </description>

    <syntax>
LexSegmentIdeal(L: LIST of power-products): IDEAL
LexSegmentIdeal(I: IDEAL): IDEAL
</syntax>

    <seealso>
      <see>IsLexSegment</see>
      <see>StableIdeal</see>
      <see>StronglyStableIdeal</see>
    </seealso>

    <types>
      <type>ideal</type>
      <type>list</type>
    </types>

    <keys>
    <key>lex segment</key>
    <key>lex-segment</key>
    </keys>
  </command>

<!-- ===  COMMAND  =============================================== -->
<command>
  <title>LF</title>
  <short_description>the leading form of a polynomial or an ideal</short_description>

<syntax>
LF(E):same type as E
where E has type IDEAL, RINGELEM.
</syntax>

<description>
If E is a polynomial this function returns the leading form of a
polynomial, <i>i.e.</i> the sum of all summands having highest degree.
Throws an error if the argument is zero or if the <ttref>GradingDim</ttref> 
of the polynomial ring is 0 (use <ttref>DF</ttref> to allow 0 these cases).

If E is an ideal this function return the ideal of all the LF(f) for f in E.
Throws an error if the <ttref>GradingDim</ttref> of the polynomial ring is 0.

<example>
/**/  Use R ::= QQ[x,y];
/**/  LF(x^2 -x*y +2*x -1);
x^2 -x*y

/**/  Use R ::= QQ[x,y], Lex;  -- GradingDim is 0: everything is homogeneous
/**/  LF(x-1); -- !!! ERROR !!! instead of x-1

/**/ P := NewPolyRing(QQ, IndetSymbols(R), mat([[1,4],[1,0]]), 1);
/**/ Use P;
/**/ LF(x^2 - x*y);
-x*y
/**/  LF(x^4 + x^2 - y);
 x^4 -y
</example>
    </description>

    <keys>
      <key>leading-form</key>
      <key>leadingform</key>
      <key>leading form</key>
    </keys>

    <seealso>
      <see>DF</see>
      <see>IsHomog</see>
      <see>LC</see>
      <see>LM</see>
      <see>LPP</see>
      <see>LT</see>
    </seealso>

    <types>
      <type>polynomial</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>LinearSimplify</title>
  <short_description>find simplifying linear substitution for a univariate polynomial over QQ</short_description>
  
<syntax>
LinearSimplify(F:POLY):RECORD[LinearChange:POLY, SimplePoly:POLY]
</syntax>
<description>
This function returns a RECORD[LinearChange, SimplePoly] where LinearChange is a
linear change of variable and SimplePoly is simple (in a heuristic sense).  The
composition SimplePoly(LinearChange) is equal the univariate polynomial given to
LinearSimplify.
<example>
/**/  Use QQ[x];
/**/  LinearSimplify((123*x-456)^9-1);
Record[LinearChange := 123*x - 456, SimplePoly := x^9 - 1]

/**/  LinearSimplify(x^9-1); -- the heuristic finds no useful simplification
Record[LinearChange := x, SimplePoly := x^9 - 1]
</example>
</description>

<types>
  <type>poly</type>
</types>

<keys>
  <key>linear simplify</key>
  <key>simplification</key>
  <key>simplifying substitution</key>
</keys>
</command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>LinKer</title>
  <short_description>find the kernel of a matrix</short_description>

<syntax>
LinKer(M:MAT):MAT
</syntax>

<description>
This function returns a matrix whose columns representing a basis for
the kernel of M.  Calling the function twice on the same input will
not necessarily produce the same output, though in each case, a basis
for the kernel is produced.
<par/>
This function works only (CoCoA-5.0.3) on matrices whose entries are
in a field.
The CoCoA-4 function returning a ZZ-basis for the kernel of M is not
yet implemented.
<par/>
The output as it was given by CoCoA-4 (the basis of the ker) is
now given by <ttref>LinKerBasis</ttref>.
See also <ttref>HilbertBasisKer</ttref>.

<example>
/**/   M := mat([[1,2,3,4],[5,6,7,8],[9,10,11,12]]);
/**/   LinKer(M);
matrix( /*QQ*/
 [[-1, -2],
  [2, 3],
  [-1, 0],
  [0, -1]]
 )

/**/ M*It;
matrix( /*QQ*/
 [[0, 0],
  [0, 0],
  [0, 0]]
 )
</example>
</description>

<seealso>
  <see>LinKerModP</see>
  <see>LinSol</see>
  <see>HilbertBasisKer</see>
</seealso>

<types>
  <type>matrix</type>
</types>

<keys>
  <key>linear kernel</key>
  <key>nullspace</key>
  <key>abbott</key>
</keys>
</command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>LinKerBasis</title>
    <short_description>find the kernel of a matrix</short_description>

    <description>
<par/>
This function returns a list whose components are lists
representing a basis for the kernel of M.  Calling the function
twice on the same input will not necessarily produce the same output,
though in each case, a basis for the kernel is produced.

This function works only (CoCoA-5.0.3) on matrices whose entries are
in a field.

The CoCoA-4 function returning a Z-basis for the kernel of M is not
yet implemented.

<example>
/**/   M := mat([[1,2,3,4],[5,6,7,8],[9,10,11,12]]);
/**/   LinKerBasis(M);
[[-1, 2, -1, 0], [-2, 3, 0, -1]]

/**/  K := NewFractionField(NewPolyRing(QQ, ["a","b"]));
/**/  Use K;
/**/  M := mat([[1,2,3,a],[5,6,7,a*b]]);
/**/  LinKerBasis(M);
[[-1, 2, -1, 0], [(a*b -3*a)/2, (-a*b +5*a)/4, 0, -1]]
</example>
    </description>

    <syntax>
LinKerBasis(M:MAT):LIST
</syntax>

    <seealso>
      <see>LinKerModP</see>
      <see>LinSol</see>
    </seealso>

    <types>
      <type>matrix</type>
    </types>

    <keys>
    <key>linear kernel</key>
    <key>nullspace</key>
    <key>abbott</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>LinKerModP</title>
    <short_description>find the kernel of a matrix</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This function returns a list whose components are lists representing a
basis for the kernel of M over the current field of coefficients.

<example>
  M := mat([[1,2,3,4],[5,6,7,8],[9,10,11,12]]);
  Use ZZ/(3)[x];
  LinKerModP(M);
[[1, 1, 1, 0], [0, 2, 2, 2]]
-------------------------------
  Use ZZ/(7)[x];
  LinKerModP(M);
[[2, 3, 2, 0], [1, 3, 5, 5]]
-------------------------------
  N := M*Transposed(mat(It));
  [ [ mod(X,Characteristic()) | X In Row ]  | Row In N ];
[[0, 0], [0, 0], [0, 0]]
-------------------------------
</example>
    </description>

    <syntax>
LinKerModP(M:MAT):LIST

where M is a matrix over QQ or ZZ.
</syntax>

    <seealso>
      <see>LinKer</see>
      <see>LinSol</see>
    </seealso>

    <types>
      <type>matrix</type>
    </types>

    <keys>
    <key>linear kernel</key>
    <key>nullspace</key>
    <key>abbott</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>LinSol</title>
    <short_description>find a solution to a linear system</short_description>

    <description>
***** REPLACED BY NEW FUNCTION <ttref>LinSolve</ttref> *****

The code from CoCoA-4 has not been implemented yet.
There is an experimental low-level interface: <tt>$builtin.LinSol</tt> which expects
as second argument a list of lists <formula>[L_1,...,L_k]</formula> where each <formula>L_i</formula> is a list of
length m with entries in ZZ or QQ (to be considered as a list of column
vectors).  The result is a list of lists <formula>[X_1,...,X_k]</formula> where each <formula>X_i</formula> is either
a solution to the linear system <formula>M X_i = L_i</formula> or it is the empty list (meaning
that no solution exists to the equation <formula>M X_i = L_i</formula>).

    </description>

    <syntax>
LinSol(M:MAT, RHS:MAT):MAT or STRING

where M is an m x n matrix over ZZ or QQ, and RHS is an m x k matrix
with entries in ZZ or QQ.
</syntax>

    <seealso>
      <see>LinKer</see>
    </seealso>

    <types>
      <type>matrix</type>
    </types>

    <keys>
    <key>linear solve</key>
    <key>solve</key>
    <key>abbott</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>LinSolve</title>
    <short_description>find a solution to a linear system</short_description>

    <syntax>
LinSolve(M:MAT, RHS:MAT):MAT

with entries in ZZ or QQ.
</syntax>

    <description>
<par/>
This function finds a solution X to the matrix equation <tt>M*X = RHS</tt>.
If more than one solution exists, it returns just one of them.
If no solution exists then it produces a 0-by-0 matrix.
To find all solutions compute the kernel of <tt>M</tt> using
the function <ttref>LinKer</ttref>.
<par/>
NOTE: an easy way of converting a list into a column matrix (for the second
argument) is to use the function <ttref>ColMat</ttref>.

<example>
/**/  M := mat([[3,1,4],[1,5,9],[2,6,5]]);
/**/  L := [123,456,789];
/**/  LinSolve(M, ColMat(L));
mat([
  [199/5],
  [742/5],
  [-181/5]
])

/**/  M*It;
mat([
  [123],
  [456],
  [789]
])
-------------------------------
</example>

    </description>

    <seealso>
      <see>LinKer</see>
    </seealso>

    <types>
      <type>matrix</type>
    </types>

    <keys>
    <key>solve matrix equation</key>
    <key>solve linear system</key>
    <key>linear system solving</key>
    <!-- <key>abbott</key> -->
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>list</title>
    <short_description>convert an expression into a list</short_description>

    <description>
This function converts the expression E into a list.  It
is the same as Cast(E, LIST).

<example>
/**/  M := mat([[1,2], [3,4]]);
/**/  M;
matrix([
  [1, 2],
  [3, 4]
])

/**/  first(M);  -- the WRONG WAY to compute the first row of M
ERROR: Expecting type LIST, but found type MAT
 first(M);
       ^

/**/  GetRow(M, 1);  -- the RIGHT WAY to compute the first row of M
[1, 2]

/**/  first(list(M));
[1, 2]
</example>

    </description>

    <syntax>
list(E:OBJECT):LIST

where E has type LIST, MAT, or MODULEELEM.
</syntax>

    <seealso>
      <see>NewList</see>
    </seealso>

    <types>
      <type>list</type>
      <type>matrix</type>
      <type>moduleelem</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>list constructors</title>
    <short_description>build a new list</short_description>

    <syntax>
A..B
[A,B,C,...]
[X in L:LIST | B:BOOL]:LIST
[E:expression | X in L]:LIST
[E:expression | X in L:LIST and B:BOOL]:LIST

where <tt>X</tt> is a variable which may occur in <tt>B</tt> or <tt>E</tt>.
</syntax>

    <description>
These operators create new lists.
<par/>
<tt>A..B</tt> creates the list of integers from <tt>A</tt> to <tt>B</tt>, both ends are included.
<par/>
The expression <tt>[A,B,C,...]</tt> makes a list whose first element is <tt>A</tt>, second
element is <tt>B</tt>, and so on.
<par/>
The expression <tt>[X in L | B]</tt> makes a list of those elements in the list <tt>L</tt>
for which the condition <tt>B</tt> is true.
<par/>
The expression <tt>[E | X in L]</tt> evaluates the expression <tt>E</tt> for each <tt>X</tt>
in <tt>L</tt>, and collects the results in a new list.
<par/>
The expression <tt>[E | X in L and B]</tt> evaluates the expression <tt>E</tt> for
each <tt>X</tt> in <tt>L</tt> which satisfies the condition <tt>B</tt>, and collects the
results in a new list.

<example>
/**/  []; --> empty list
[]

/**/  1..4;
[1, 2, 3, 4]

/**/  [3,1,4,2];
[3, 1, 4, 2]

/**/  [N in 1..10 | IsPrime(N)];
[2, 3, 5, 7]

/**/  [N^2 | N in 1..4];
[1, 4, 9, 16]

/**/  [N^2 | N in 1..10 and IsPrime(N)];
[4, 9, 25, 49]
</example>

    </description>

    <seealso>
      <see>NewList</see>
      <see>append</see>
      <see>concat</see>
      <see>CartesianProduct</see>
    </seealso>

    <types>
      <type>list</type>
      <type>boolean</type>
    </types>

    <keys>
      <key>[]</key>
      <key>building lists</key>
      <key>making lists</key>
      <key>empty list</key>
    </keys>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>LM</title>
    <short_description>the leading monomial of a polynomial or vector</short_description>

    <description>
This function returns the leading monomial of P.  The monomial
includes the coefficient.  To get the leading term of P, (which does
not included the coefficient), use <ttref>LT</ttref>.

<example>
/**/  Use R ::= QQ[x,y];
/**/  LM(3*x^2*y + y);
3*x^2*y

/**/  LM(Vector(2*x,y));  --***OBSOLETE MANUAL: WORK IN PROGRESS***
Vector(2*x, 0)

/**/  LT(Vector(2*x,y));  --***OBSOLETE MANUAL: WORK IN PROGRESS***
Vector(x, 0)
</example>
    </description>

    <syntax>
LM(P:POLY or MODULEELEM):same type as P
</syntax>

    <seealso>
      <see>LC</see>
      <see>LF</see>
      <see>LPP</see>
      <see>LT</see>
    </seealso>

    <types>
      <type>polynomial</type>
      <type>moduleelem</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>log</title>
    <short_description>the list of exponents of the leading term of a polynomial</short_description>

    <description>
This function returns the list of exponents of the leading term of F.

<example>
/**/  Use R ::= QQ[x,y,z];
/**/  F := x^3*y^2*z^5 + x^2*y + x*z^4;
/**/  log(F);
[3, 2, 5]
</example>
    </description>

    <syntax>
log(F:POLY):LIST
</syntax>

    <seealso>
      <see>ILogBase</see>
      <see>LT</see>
      <see>LogToTerm</see>
    </seealso>

    <types>
      <type>polynomial</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>LogCardinality</title>
    <short_description>extension degree of a finite field</short_description>

    <description>
This function returns the extension degree of a finite field over its prime field, or equivalently the log (base p) of its cardinality.

<example>
/**/  Fp ::= ZZ/(7);
/**/  Use Fpx ::= Fp[x];
/**/  Fq := Fpx/ideal(x^2+1);
/**/  LogCardinality(Fq);
2
</example>
    </description>

    <syntax>
LogCardinality(Fp:RING):INT
</syntax>

    <seealso>
      <see>IsFiniteField</see>
      <see>characteristic</see>
    </seealso>

    <types>
      <type>ring</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>LogToTerm</title>
    <short_description>returns a monomial (power-product) with given exponents</short_description>

    <description>
This function returns the power-product whose list of exponents is L.

<example>
/**/  Use R ::= QQ[x,y,z];
/**/  LogToTerm(R, [2,3,5]);
x^2*y^3*z^5

/**/  log(It);
[2, 3, 5]
</example>
    </description>

    <syntax>
LogToTerm(R:RING, L:LIST):POLY

where L is a list of integers.
</syntax>

    <seealso>
      <see>log</see>
    </seealso>

    <types>
      <type>polynomial</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>LPosn</title>
  <short_description>the position of the leading power-product in a vector</short_description>
  
<syntax>
LPosn(V:MODULEELEM): INT
</syntax>
<description>
This function returns the position of the leading power-product of V.
<par/>
This function used to be called <tt>LPosn</tt> up to version 5.0.3.
<example>
/**/  Use R ::= QQ[x,y,z];  -- the default term-ordering is DegRevLex
/**/  R4 := NewFreeModule(R,4); -- the default module ordering is TOPos
/**/  LPosn(ModuleElem(R4, [0, x, y^2, x^2]));
4
/**/  LPP(ModuleElem(R4, [0, x, y^2, x^2]));
x^2
/**/  LT(ModuleElem(R4, [0, x, y^2, x^2]));
[0, 0, 0, x^2]


  Use R ::= QQ[x,y], PosTo;
  LT(Vector(x,y^2));
Vector(x, 0)
-------------------------------
  LPP(Vector(x,y^2));
x
-------------------------------
  LPosn(Vector(x,y^2));
1
-------------------------------
</example>
</description>

<seealso>
  <see>LF</see>
  <see>LM</see>
  <see>LPP</see>
  <see>LT</see>
</seealso>

<types>
  <type>moduleelem</type>
</types>

</command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>LPP</title>
    <short_description>the leading power-product of a polynomial or vector</short_description>

    <description>
This function returns the leading power-product of P.

<example>
/**/  Use R ::= QQ[x,y];
/**/  LPP(3*x^2*y+y);  -- LPP is the same as LT for polynomials
x^2*y

-- Note the difference between LPP and LT for MODULEELEM.
/**/  R4 := NewFreeModule(R,4); -- the default module ordering is TOPos
/**/  LPP(ModuleElem(R4, [0, x, y^2, x^2]));
x^2
/**/  LT(ModuleElem(R4, [0, x, y^2, x^2]));
[0, 0, 0, x^2]
/**/  LPosn(ModuleElem(R4, [0, x, y^2, x^2]));
4
</example>
    </description>

    <syntax>
LPP(P:POLY or MODULEELEM):POLY
</syntax>

    <seealso>
      <see>LC</see>
      <see>LF</see>
      <see>LM</see>
      <see>LT</see>
    </seealso>

    <types>
      <type>polynomial</type>
      <type>moduleelem</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>LT</title>
  <short_description>the leading term of an object</short_description>

<syntax>
LT(E):same type as E
where E has type IDEAL, MODULE, RINGELEM, or MODULEELEM.
</syntax>

<description>
If E is a polynomial this function returns the leading term of the
polynomial E with respect to the term-ordering of the polynomial ring
of E.
For the leading monomial, which includes the coefficient, use <ttref>LM</ttref>.

<example>
/**/  Use R ::= QQ[x,y,z];  -- the default term-ordering is DegRevLex
/**/  LT(y^2-x*z);
y^2

/**/  Use R ::= QQ[x,y,z], Lex;
/**/  LT(y^2-x*z);
x*z
</example>

If E is a MODULEELEM, LT(E) gives the leading term of E with respect to
the module term-ordering of E.  For the leading monomial, which
includes the coefficient, use <ttref>LM</ttref>.

<example>
/**/  R3 := NewFreeModule(R,3);
/**/  LT(ModuleElem(R3, [0, x, y^2]));
[0, 0, y^2]

  Use R ::= QQ[x,y], PosTo;
  V := Vector(0, x, y^2);
  LT(V); -- the leading term of V w.r.t. PosTo
Vector(0, x, 0)
-------------------------------
</example>

If E is an ideal or module, LT(E) returns the ideal or module
generated by the leading terms of all elements of E, sometimes called
the <em>initial</em> ideal or module.

<example>
/**/  Use R ::= QQ[x,y,z];
/**/  I := ideal(x-y, x-z^2);
/**/  LT(I);
ideal(x, z^2)
</example>
    </description>

    <seealso>
      <see>LC</see>
      <see>LF</see>
      <see>LM</see>
      <see>LPP</see>
      <see>Module Orderings</see>
      <see>Orderings</see>
    </seealso>

    <types>
      <type>ideal</type>
      <type>module</type>
      <type>polynomial</type>
      <type>moduleelem</type>
    </types>

    <keys>
    <key>leading term</key>
    <key>initial term</key>
    </keys>
  </command>

 </chapter_letter>
 <!-- ===  CHAPTER  =============================================== -->
 <chapter_letter>
   <title>M</title>

<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>MakeCheck</title>
    <short_description>run a series of tests</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This function run a series of tests on the whole system.  To get a
reliable result you should run this on a <em>just opened</em> CoCoA
because some printouts may mysteriously add some empty spaces which
will result in an, apparent, failure of some tests.
<example>
  MakeCheck();
</example>

    </description>

    <syntax>
MakeCheck()
</syntax>

    <types>
      <type>cocoaserver</type>
    </types>

    <keys>
    <key>tests</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>MakeMatByRows, MakeMatByCols</title>
    <short_description>convert a list into a matrix</short_description>

    <description>
These functions convert the list L into a matrix.
The first argument is the number of rows and the second the number of columns.

<example>
/**/  MakeMatByRows(2, 10, 1..20);
matrix([
  [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
  [11, 12, 13, 14, 15, 16, 17, 18, 19, 20]
])

/**/  MakeMatByCols(2, 10, 1..20);
matrix([
  [1, 3, 5, 7, 9, 11, 13, 15, 17, 19],
  [2, 4, 6, 8, 10, 12, 14, 16, 18, 20]
])
</example>
    </description>

    <syntax>
MakeMatByRows(R:INT, C:INT, L:LIST):MAT
MakeMatByCols(R:INT, C:INT, L:LIST):MAT
</syntax>

    <seealso>
      <see>BlockMat</see>
      <see>matrix</see>
      <see>NewMat</see>
      <see>ColMat</see>
      <see>RowMat</see>
      <see>DiagMat</see>
      <see>ConcatHor</see>
      <see>ConcatVer</see>
    </seealso>

    <types>
      <type>list</type>
      <type>matrix</type>
    </types>

    <keys>
      <key>rows</key>
      <key>cols</key>
    </keys>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>MakeSet</title>
    <short_description>remove duplicates from a list</short_description>

    <description>
This function returns a list obtained by removing duplicates from L.

<example>
/**/  MakeSet([2,2,2,1,2,1,1,3,3]);
[2, 1, 3]
</example>

WARNING: to test two sets for equality use the function <ttref>EqSet</ttref>
instead of a normal equality test (because the latter yields false if the
elements are in a different order).

    </description>

    <syntax>
MakeSet(L:LIST):LIST
</syntax>

    <seealso>
      <see>EqSet</see>
      <see>intersect</see>
      <see>IntersectionList</see>
      <see>insert</see>
      <see>remove</see>
    </seealso>

    <types>
      <type>list</type>
    </types>

    <keys>
      <key>duplicates</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>MantissaAndExponent</title>
    <short_description>convert rational number to a float</short_description>

    <description>
This function converts a rational number into a Record with
components named Mantissa and Exponent.  The value of the Exponent
field is the unique integer E such that
<formula>1 <less_eq/> X*10^E <less_eq/> 10</formula>, and the
value of Mantissa is the nearest integer to <formula>(X*10^E)*10^(Prec-1)</formula>.
As an exception the case of X=0 always produces zero values for
both components of the record.

<example>
/**/  FloatStr(1/2);         -- trailing zeroes are not suppressed
5.000000000*10^(-1)

/**/  MantissaAndExponent(1/2,3);       --  1/2 = 5.00*10^(-1)
Record[exponent := -1, mantissa := 500]

/**/  MantissaAndExponent(0.9999, 3);   --  0.9999 rounds up to give 1.00
Record[exponent := 0, mantissa := 100]
</example>
    </description>

    <syntax>
MantissaAndExponent(X:RAT, Prec:INT):RECORD
</syntax>

    <seealso>
      <see>DecimalStr</see>
      <see>FloatApprox</see>
      <see>FloatStr</see>
    </seealso>

    <types>
      <type>rat</type>
      <type>string</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>Manual</title>
    <short_description>search online help system</short_description>

    <syntax>
? key
?? key
where <em>key</em> is a literal string (without quotes)
</syntax>

    <description>
The <tt>?</tt> operator is used to search the online help system for
information matching a keyword.
<par/>
The command has the form <tt>?key</tt> where <em>key</em> is a string without quotes.
The <tt>?</tt> operator is case insensitive and ignores blank space before or
after <em>key</em>.  Also, the semicolon usually required at the end of a line of
CoCoA input is optional.  The <tt>?</tt> operator was introduced in CoCoA 4.2.
<par/>
The online help comprises a descriptive page for each CoCoA command/function.
Each page summarises the syntax, gives a short verbal description, and some
examples of use.  Often there are also references to other closely related
command/functions.
<par/>
The search system is fairly simple.  The searching algorithm looks through
the title and keywords of each manual page.  If the given <em>key</em> appears
as a (case-insensitive) substring of the title/keywords of just one manual
page, or if it matches exactly then that page is displayed.  In any case the
titles of all other pages where a match was found are printed in "menu" style.

<example>
/**/ ?pol

All matches for "pol":
 ? CharPoly
 ? DensePoly

     --( Further output suppressed )--

/**/ ?hvec
==============[ HVector ]===============
--====  syntax  ====--
-- HVector(R:RING or TAGGED("Quotient")):LIST
--====  description  ====--
This function returns the h-vector of M, i.e., the...

            --( Output suppressed )--
</example>

    </description>

    <seealso>
      <see>operators, shortcuts</see>
    </seealso>

    <keys>
    <key>?</key>
    <key>??</key>
    <key>help</key>
    <key>online help</key>
    </keys>

  </command>

<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>MapDown</title>
    <short_description>convert a constant polynomial to a number</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This function converts a constant polynomial to the equivalent
coefficient.  If the argument is not a constant polynomial, an error
is signalled.

<example>
  Use QQ[x,y,z];
  type((x+1)^2 - x*(x+2));    -- value is seen as a polynomial
POLY
-------------------------------
  MapDown((x+1)^2 - x*(x+2)); -- attempt to map down to the coeff ring
1
-------------------------------
  type(It);                   -- value is now simply a coefficient
RAT
-------------------------------
  MapDown((x+1)^2 - x^2);     -- 2*x + 1 is not a coefficient
ERROR: Cannot MapDown non-const poly
CONTEXT: Error("Cannot MapDown non-const poly")
-------------------------------
</example>
    </description>

    <syntax>
MapDown(F:POLY):RAT or ZMOD
</syntax>

    <types>
      <type>polynomial</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>matrix</title>
    <short_description>convert an expression into a matrix</short_description>

    <description>
This function converts the expression E into a matrix.
<par/>
When E is a LIST of LIST of RINGELEM all the elements must be in the
same RING and the resulting matrix is in that RING.
When E is a LIST of LIST of INT or RAT the resulting matrix is in QQ.
When a RING is specified the resulting matrix will be in that RING
(if possible).
<par/>
When the arguments are a ring R and a matrix M the resulting matrix is
the image of M in R (if possible)

<example>
/**/  Use R ::= QQ[x,y];
/**/  L := [[1,2],[3,4]];
/**/  mat(L);
matrix( /*QQ*/
 [[1, 2],
  [3, 4]]
 )
/**/  mat(R,L);
matrix( /*RingDistrMPolyClean(QQ, 2)*/
 [[1, 2],
  [3, 4]]
 )
/**/  mat(ZZ,L);
matrix( /*ZZ*/
 [[1, 2],
  [3, 4]]
 )

/**/  RingOf(mat(R, [[1,2],[3,4]]));
RingDistrMPolyClean(QQ, 2)

/**/ M := IdentityMat(ZZ,2);   matrix(QQ, M);
matrix( /*QQ*/
 [[1, 0],
  [0, 1]]
 )


  M := Module([x,x^2,y], [x^2,y,0]); --***OBSOLETE MANUAL: WORK IN PROGRESS***
  mat(M);
mat([
  [x, x^2, y],
  [x^2, y, 0]
])
</example>
    </description>

    <syntax>
mat(R:RING, L:LIST):MAT
mat(L:LIST):MAT
where L is either: a <em>rectangular</em> lists of lists, or a module
</syntax>

    <seealso>
      <see>NewMat</see>
      <see>ColMat</see>
      <see>RowMat</see>
      <see>DiagMat</see>
      <see>MakeMatByRows, MakeMatByCols</see>
      <see>ConcatHor</see>
      <see>ConcatVer</see>
      <see>BlockMat</see>
    </seealso>

    <types>
      <type>list</type>
      <type>matrix</type>
      <type>moduleelem</type>
    </types>

    <keys>
    <key>matrix</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>Max</title>
    <short_description>a maximum element of a sequence or list</short_description>

    <description>
In the first form, this function returns a maximum of <formula>E_1,...,E_n</formula>.
In the second form, it returns a maximum of the objects in the list L.

<example>
/**/  Max([1,2,3]);
3

/**/  Max(1,2,3);
3

/**/  Min(1,2,3);
1

/**/  Use R ::= QQ[x,y,z];
/**/  Max(x^3*z, x^2*y^2); -- x^2y^2 &gt; x^3z in the default ordering, DegRevLex
x^2*y^2

/**/  Min(x^3*z, x^2*y^2);
x^3*z

/**/  Use R ::= QQ[x,y,z], DegLex;
/**/  Max(x^3*z, x^2*y^2); -- x^3z &gt; x^2y^2 in DegLex
x^3*z
</example>
    </description>

    <syntax>
Max(E_1:OBJECT,...,E_n:OBJECT):OBJECT
Min(E_1:OBJECT,...,E_n:OBJECT):OBJECT

Max(L:LIST):OBJECT
Min(L:LIST):OBJECT
</syntax>

    <seealso>
      <see>Min</see>
      <see>Relational Operators</see>
    </seealso>

    <types>
      <type>integer</type>
      <type>ideal</type>
      <type>list</type>
      <type>module</type>
      <type>rat</type>
      <type>string</type>
      <type>type</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>MayerVietorisTreeN1</title>
    <short_description>N-1st Betti multidegrees of monomial ideals using Mayer-Vietoris trees</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This function returns the list of multidegrees M such that the N-1st
Betti number of a monomial ideal I at multidegree M is not zero.
It is computed via a version of its Mayer-Vietoris tree.

The length of this list is the number of irreducible components of I,
the number of maximal standard monomials, and the number of generators
of its Alexander Dual.

<example>
  Use QQ[x,y,z];
  I := ideal(x, y, z)^2;
  MayerVietorisTreeN1(I);
-------------------------------
[x^2yz, xy^2z, xyz^2]
-------------------------------
</example>
    </description>

    <syntax>
MayerVietorisTreeN1(I:(MONOMIAL)IDEAL):INT
</syntax>

    <seealso>
      <see>Frobby</see>
    </seealso>

    <types>
      <type>monomialideal</type>
      <type>cocoaserver</type>
    </types>

    <keys>
    <key>mvt</key>
    <key>saenz-de-cabezon</key>
    <key>cocoalib</key>
    </keys>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>Memory</title>
    <short_description>contents of local memory or ring-bound memory</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
The first form of this function prints the contents of the working
memory, i.e, all non-global variables. The second form lists all
global variables bound to the ring R.
<par/>
For more information about memory in CoCoA, see the chapter entitled
<ref>Memory Management</ref>.

<example>
  Use R ::= QQ[x,y,z];
  I := ideal(x-y^2, xy-z^3);
  X := 14;
  ENV.R.Y := 5;  --  a global variable bound to R
                 -- "ENV.R" is equivalent to "MEMORY.ENV.R"
  Use S ::= QQ[a,b];
  J := ideal(a,b);
  ENV.S.Z := 7;
  Memory();
["I", "J", "X"]
-------------------------------
  Memory(R);
["Y"]
-------------------------------
</example>
    </description>

    <syntax>
Memory():TAGGED("Memory")
Memory(R:RING):TAGGED("Memory")
</syntax>

    <seealso>
      <see>GlobalMemory</see>
      <see>Memory Management</see>
    </seealso>

    <types>
      <type>memory</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>Min</title>
    <short_description>a minimum element of a sequence or list</short_description>

    <description>
In the first form, this function returns a minimum of <formula>E_1,...,E_n</formula>.
In the second form, it returns a minimum of the objects in the list L.

<example>
/**/  Min([1,2,3]);
1

/**/  Min(1,2,3);
1
</example>
    </description>

    <syntax>
Min(E_1:OBJECT,...,E_n:OBJECT):OBJECT

Min(L:LIST):OBJECT
</syntax>

    <seealso>
      <see>Max</see>
      <see>Relational Operators</see>
    </seealso>

    <types>
      <type>integer</type>
      <type>ideal</type>
      <type>list</type>
      <type>module</type>
      <type>rat</type>
      <type>string</type>
      <type>type</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>MinGens</title>
  <short_description>list of minimal generators</short_description>
  
<syntax>
MinGens(M:IDEAL or MODULE):LIST
</syntax>
<description>
If M is a homogeneous ideal or module, this function returns a list of
minimal generators for M.
<par/>
The coefficient ring must be a field.
<par/>
For non-homogeneous input use <ttref>MinGensGeneral</ttref>.
<example>
/**/  Use R ::= QQ[x,y,z];
/**/  I := ideal(x-y, (x-y)^4, z+y, (z+y)^2);
/**/  MinGens(I);
[y + z, x + z]

/**/  R3 := NewFreeModule(R, 3);
/**/  MGens := matrix(R, [[x,y,z], [x^2,0,z^2], [2*x^2,x*y,z^2+x*z]]);
/**/  M := SubmoduleRows(R3, MGens);
/**/  gens(M);
[[x, y, z], [x^2, 0, z^2], [2*x^2, x*y, x*z +z^2]]
/**/  MinGens(M);
[[x, y, z], [0, x*y, x*z -z^2]]
</example>
</description>

<seealso>
  <see>minimalize</see>
  <see>minimalized</see>
</seealso>

<types>
  <type>groebner</type>
  <type>groebner-basic</type>
  <type>ideal</type>
  <type>module</type>
  <type>quotient</type>
</types>

</command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>minimalize</title>
    <short_description>remove redundant generators</short_description>

<syntax>
minimalize(ref X:IDEAL):NULL
minimalize(ref X:MODULE):NULL
</syntax>
<description>
Similar to <ttref>minimalized</ttref>, but modifies the
argument <tt>X</tt> and returns NULL.
*** NOT YET IMPLEMENTED for submodule *** use MinGens instead.
<example>
/**/  Use R ::= QQ[x,y,z];
/**/  I := ideal(x^2-y^2, z^4-y^4, x^2-z^2);
/**/  I;
ideal(x^2 -y^2, -y^4 +z^4, x^2 -z^2)
/**/  minimalize(ref I); -- returns NULL and modifies I
/**/  I;
ideal(x^2 -z^2, y^2 -z^2)
</example>
</description>

<seealso>
  <see>MinGens</see>
  <see>minimalized</see>
</seealso>

<types>
  <type>ideal</type>
  <type>module</type>
</types>

</command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>minimalized</title>
  <short_description>ideal with minimal generators</short_description>
  
<syntax>
minimalized(E:IDEAL):IDEAL
minimalized(E:MODULE):MODULE
</syntax>
<description>
It works only in the homogeneous case: it returns the ideal or module
generated by a set of minimal generators of E (with minimal cardinality).
The minimal set of generators is not necessarily a subset of the given
generators.
<par/>
*** NOT YET IMPLEMENTED for submodules *** use <ttref>MinGens</ttref> instead.
<par/>
In the inhomogeneous case use <ttref>MinGensGeneral</ttref>.
<par/>
The coefficient ring is assumed to be a field.
<par/>
The similar function <ttref>minimalize</ttref> performs the same
operation, but modifies the argument (<ttref>ref</ttref>) and returns NULL.
<example>
/**/  Use R ::= QQ[x,y,z];
/**/  I := ideal(x^2-y^2, z^4-y^4, x^2-z^2);
/**/  I;
ideal(x^2 -y^2, -y^4 +z^4, x^2 -z^2)
/**/  minimalized(I);
ideal(x^2 -z^2, y^2 -z^2)
/**/  I; -- not modified
ideal(x^2 -y^2, -y^4 +z^4, x^2 -z^2)
</example>
</description>

<seealso>
  <see>MinGens</see>
  <see>minimalize</see>
</seealso>

<types>
  <type>ideal</type>
  <type>module</type>
</types>

</command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>MinimalPresentation</title>
    <short_description>minimal presentation for a quotient</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
Given a quotient module of the type <formula>R<sup>s</sup>/M</formula>,
or a zero module, this function computes an isomorphic quotient,
<formula>R<sup>t</sup>/N</formula>, minimally presented
[using the algortihm in Kreuzer-Robbiano II].

<example>
  Use R ::= QQ[x,y,z];
  MinimalPresentation(R^3/Module([[x,1,1], [x,2,2]]));
R^2/Module([[x, 0]])
-------------------------------
</example>
    </description>

    <syntax>
MinimalPresentation(Q:TAGGED):TAGGED

where Q is a quotient module of the type R^s/M
</syntax>

    <types>
      <type>module</type>
    </types>

    <keys>
    <key>minimal presentation</key>
    <key>damiano</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>minors</title>
    <short_description>list of minor determinants of a matrix</short_description>

    <description>
This function returns the list of all determinants of N x N
submatrices of M.

<example>
/**/  M := mat([[1,2,3],[-1,2,4]]);
/**/  minors(M, 2);
[4, 7, 2]
</example>
    </description>

    <syntax>
minors(M:MAT, N:INT):LIST
</syntax>

    <seealso>
      <see>det</see>
    </seealso>

    <types>
      <type>matrix</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>MinPoly</title>
    <short_description>minimal polynomial of a matrix</short_description>

    <syntax>
MinPoly(M:MAT, X:INDET): POLY
</syntax>

    <description>
This function returns the minimal polynomial of the matrix M in the
indeterminate X (with M a square matrix whose entries lies in the
coefficient ring of X).
See also <ttref>CharPoly</ttref>.

<example>
/**/  Use R ::= QQ[x];
/**/  MinPoly(matrix([[0,0,1],[0,0,0],[0,0,0]]), x);
x^2
/**/  CharPoly(matrix([[0,0,1],[0,0,0],[0,0,0]]), x);
x^3
</example>
    </description>

    <seealso>
      <see>CharPoly</see>
    </seealso>

    <types>
      <type>matrix</type>
    </types>

    <keys>
    <key>minimal polynomial</key>
    <key>torrente</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>MinPowerInIdeal</title>
    <short_description>the mininum power of a polynomial is an ideal</short_description>

    <description>
This function returns the minimum power of F, the first argument, in
the ideal I, the second argument.
If F is not in the radical I then -1 is returned.

<example>
/**/  Use QQ[x,y,z];
/**/  I := ideal(x^6*y^4, z);
/**/  IsInRadical(x*y, I);
true

/**/  MinPowerInIdeal(x*y, I);
6
</example>
    </description>

    <syntax>
MinPowerInIdeal(F:POLY, I:IDEAL):INT
</syntax>

    <seealso>
      <see>IsInRadical</see>
      <see>radical</see>
    </seealso>

    <types>
      <type>ideal</type>
      <type>poly</type>
    </types>

    <keys>
    <key>radical membership</key>
    </keys>
  </command>
<!-- ===  COMMAND-rm MinSyzMinGens ========================================== -->
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>mod</title>
    <short_description>remainder for integers</short_description>

    <description>
We define the quotient <tt>Q</tt> and remainder <tt>R</tt> to be integers which
satisfy <formula>N = Q*D + R</formula> with <formula>0 <less_eq/> R &lt; |D|</formula>.
Then <tt>div(N, D)</tt> returns <tt>Q</tt> while <tt>mod(N, D)</tt> returns <tt>R</tt>.
<par/>
NOTE: To perform the division algorithm on a polynomial or vector, use
<ttref>NR</ttref> (normal remainder) to find the remainder, or
<ttref>DivAlg</ttref> to get both the quotients and the remainder.

<example>
/**/  div(10,3);
3

/**/  mod(10,3);
1
</example>
    </description>

    <syntax>
mod(N:INT, D:INT):INT
</syntax>

    <seealso>
      <see>div</see>
      <see>DivAlg</see>
      <see>GenRepr</see>
      <see>NF</see>
      <see>NR</see>
    </seealso>

    <types>
      <type>integer</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>Mod2Rat</title>
    <short_description>reconstructing rationals from modular integers</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This function determines a rational number equivalent to the given
residue modulo the given modulus; the denominator will not exceed
DenomBound, and the absolute value of the numerator will be at most
Modulus/(2*DenomBound) -- this guarantees uniqueness of the answer.
If no such rational exists, or if DenomBound exceeds Modulus/2 then
zero is returned.  DenomBound must be positive; if not, zero is
returned.

<example>
  Mod2Rat(239094665,314159265,10000);
355/113
-------------------------------
  Residue := 1234567;                         -- To compute inverse of
  Modulus := 2^100;                           -- Residue modulo Modulus,
  Mod2Rat(Residue, Modulus, Div(Modulus-1,2));-- result is the denominator.
1/284507170216309247716413542199
-------------------------------
</example>
    </description>

    <syntax>
Mod2Rat(Residue:INT, Modulus:INT, DenomBound:INT):RAT
</syntax>

    <seealso>
      <see>div</see>
      <see>mod</see>
    </seealso>

    <types>
      <type>integer</type>
      <type>rational</type>
      <type>zmod</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>ModuleElem</title>
    <short_description>create a module elem</short_description>

    <description>
<par/>
This function returns the ModuleElem (vector) in M whose components
are the components of the list L.

<example>
/**/  Use R ::= QQ[x];
/**/  R3 := NewFreeModule(R,3);
/**/  V := ModuleElem(R3, [1, x, x^2]);  V;
[1, x, x^2]
/**/  type(V);
MODULEELEM
/**/  zero(R3);
[0, 0, 0]
</example>
    </description>

    <syntax>
ModuleElem(M:MODULE, L:LIST):MODULEELEM

where L is a list of RINGELEM.
</syntax>

    <seealso>
      <see>SubmoduleCols, SubmoduleRows</see>
    </seealso>

    <types>
      <type>moduleelem</type>
    </types>

    <keys>
      <key>vector</key>
      <key>module element</key>
    </keys>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>ModuleOf</title>
    <short_description>the module environment of the object</short_description>

    <description>
<par/>
This function returns the module on which the object E is defined.
<par/>
NB A module contains many information and two separate rings, even when
defined with the same commands, are not <quotes>equal</quotes>.
When a module is printed only a few informations are shown, so different
modules might look the same.

<example>
/**/  Use R ::= QQ[x];
/**/  R3 := NewFreeModule(R,3);
/**/  V := ModuleElem(R3, [1, x, x^2]);  V;
[1, x, x^2]
/**/  type(V);
MODULEELEM
/**/  ModuleOf(V) = R3;
true
/**/  ModuleOf(V);
FreeModule(RingDistrMPolyClean(QQ, 1), 3)
</example>
    </description>

    <syntax>
ModuleElem(M:MODULE, L:LIST):MODULEELEM

where L is a list of RINGELEM.
</syntax>

    <types>
      <type>moduleelem</type>
    </types>

    <keys>
      <key>vector</key>
      <key>module element</key>
    </keys>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>monic</title>
    <short_description>divide polynomials by their leading coefficients</short_description>

    <syntax>
monic(F:POLY):POLY
</syntax>

    <description>
This function returns <tt>F</tt> divided by its leading coefficient (see <ttref>LC</ttref>) or,
if <tt>F</tt> is zero, it returns just zero.

<example>
/**/  Use R ::= QQ[x,y];
/**/  F := 4*x^5-y^2;
/**/  monic(F);
x^5 +(-1/4)*y^2

/**/  Use R ::= ZZ[x,y];
/**/  F := 4*x^5-y^2;
/**/  monic(F);  -- can&apos;t invert coefficients over ZZ
ERROR: Inexact division
monic(L);  -- can't invert coefficient ...
^^^^^^^^

/**/  Use P ::= ZZ/(5)[x,y];
/**/  F := 2*x^2+4*y^3;
/**/  monic(F);
y^3 -2*x^2
</example>
    </description>

    <seealso>
      <see>LC</see>
    </seealso>

    <types>
      <type>polynomial</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>monomials</title>
    <short_description>the list of monomials of a polynomial or vector</short_description>

    <description>
This function returns the list of monomials of F.  The function
<ttref>support</ttref> returns the list of terms (monomials without coefficients).

<example>
/**/  Use R ::= QQ[x,y];
/**/  F := 3*x^2*y +5*y^3 -x*y^5;
/**/  monomials(F);
[-x*y^5, 3*x^2*y, 5*y^3]

/**/  support(F);
[x*y^5, x^2*y, y^3]

  Monomials(Vector(3x^2y+y,5xy+4)); --***OBSOLETE MANUAL: WORK IN PROGRESS***
[Vector(3x^2y, 0), Vector(0, 5xy), Vector(y, 0), Vector(0, 4)]
</example>
    </description>

    <syntax>
monomials(F:POLY or MODULEELEM):LIST
</syntax>

    <seealso>
      <see>coefficients</see>
      <see>support</see>
    </seealso>

    <types>
      <type>polynomial</type>
      <type>moduleelem</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>MonsInIdeal</title>
    <short_description>ideal generated by the monomials in an ideal</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This function returns the ideal generated by all monomials in the
original ideal I.

<example>
  Use R ::= QQ[x,y,z];
  I := ideal(xy^3+z^2, y^5-z^3, xz-y^2-x^3, x^4-xz^2+y^3);
  MonsInIdeal(I);
ideal(z^3, yz^2, x^2z^2, x^5z, x^4yz, x^5y, x^2y^2z, x^7, x^4y^2,
      xy^3z, y^4z, xy^4, x^3y^3, y^5)
-------------------------------
</example>
    </description>

    <syntax>
MonsInIdeal(I:IDEAL):IDEAL
</syntax>

    <types>
      <type>ideal</type>
    </types>

  </command>
<!-- ===  COMMAND-rm More =============================================== -->
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>multiplicity</title>
    <short_description>the multiplicity (degree) of a ring or quotient object</short_description>

    <description>
This function computes the multiplicity (or degree) of M,
i.e., the leading coefficient of the Hilbert polynomial multiplied by
the factorial of the degree of the Hilbert polynomial.
M can be a module or a quotient.

<example>
/**/  Use R ::= QQ[t,x,y,z];
/**/  multiplicity(R/ideal(x,y,z)^5);
35
</example>
    </description>

    <syntax>
multiplicity(R:RING or TAGGED("Quotient")):INT
</syntax>

    <seealso>
      <see>hilbert</see>
      <see>HilbertSeries</see>
      <see>HVector</see>
      <see>poincare</see>
    </seealso>

    <types>
      <type>groebner</type>
      <type>groebner-basic</type>
      <type>hilbert</type>
      <type>quotient</type>
      <type>ring</type>
    </types>

    <keys>
    <key>bigatti</key>
    </keys>
  </command>

 </chapter_letter>
 <!-- ===  CHAPTER  =============================================== -->
 <chapter_letter>
   <title>N</title>

<!-- ===  COMMAND  =============================================== -->
<command>
  <title>NewFractionField</title>
  <short_description>create a new fraction field</short_description>

<syntax>
NewFractionField(R:RING):RING
</syntax>

<description>
<par/>
NOTE: calling twice <tt>NewFractionField</tt> will produce
two different rings, even with identical input: equality test is
performed on the pointers.
<par/>

<example>
/**/  K := NewFractionField(NewPolyRing(QQ, ["a","b"]));
/**/  Use K;
/**/  M := mat([[1,2,3,a],[5,6,7,a*b]]);
/**/  LinKerBasis(M);
[[-1, 2, -1, 0], [(a*b -3*a)/2, (-a*b +5*a)/4, 0, -1]]
</example>
</description>

<seealso>
  <see>NewQuotientRing</see>
  <see>den</see>
  <see>num</see>
</seealso>

<types>
  <type>ring</type>
</types>

</command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>NewFreeModule</title>
  <short_description>create a new FreeModule</short_description>

<syntax>
NewFreeModule(R:RING, N:INT): MODULE
NewFreeModule(R:RING, Shifts:MATRIX): MODULE
</syntax>
<description>
This function returns a free module which can be used as any
programming variable.
<par/>
NOTE: as for rings, calling twice <tt>NewFreeModule</tt> will produce
two different modules, even with identical input: equality test is
performed on the pointers.
<par/>
This function does accept shifts from version CoCoA-5.0.4.
<example>
/**/  F := NewFreeModule(R, 3);
/**/  zero(F);
[0, 0, 0]
/**/ type(zero(F));  -- is NOT a LIST
MODULEELEM
/**/ gens(F);
[[1, 0, 0], [0, 1, 0], [0, 0, 1]]

/**/ F := NewFreeModule(R, matrix([[1],[2],[3]])); -- shifts
/**/ [wdeg(e) | e in gens(F)];
[[1], [2], [3]]
</example>
</description>

<seealso>
  <see>BaseRing</see>
  <see>RingOf</see>
</seealso>

<types>
  <type>io</type>
  <type>printing</type>
</types>
</command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>NewId</title>
    <short_description>create a new identifier</short_description>

    <description>
<em>This command is ***OBSOLETE***!!!  CoCoA-5 easily allows to have
temporary rings.</em>
<par/>
This function returns a string of the form <tt>V#N</tt> where N is an
integer.  Each time it is called, the integer N changes, producing a
new string.  The purpose is to produce identifiers for variables or
rings.  (CoCoA does not check for the unlikely event that variables of
the same form have been defined without the use of <tt>NewId</tt>.)  The
function <tt>NewId</tt> is often used with <tt>Var</tt>.
<par/>
The most important use for this function is for creating temporary
rings within user-defined functions.  For an example, see the section
of the tutorial entitled <ref>Rings Inside User-Defined Functions</ref>.

<example>
  NewId();
V#0
-------------------------------
  NewId();
V#1
-------------------------------
  X := NewId();
  X;
V#2
-------------------------------
  Var(X) := 3;
  Var(NewId()) := 4;
  Describe Memory();
------------[Memory]-----------
It = V#2
V#2 = 3
V#3 = 4
X = V#2
-------------------------------
  Y := NewId();
  Var(Y) ::= QQ[a,b];
  Use Var(Y);
  RingEnvs();
["QQ", "QQt", "R", "V#6", "ZZ"]
-------------------------------
  Y;
V#6
-------------------------------
  Var(Y);
QQ[a,b]
-------------------------------
</example>
    </description>

    <syntax>
NewId():STRING
</syntax>

    <seealso>
      <see>Rings Inside User-Defined Functions</see>
    </seealso>

    <types>
      <type>function</type>
      <type>string</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>NewLine</title>
    <short_description>[OBSOLESCENT] string containing a newline</short_description>

    <syntax>
NewLine():STRING 
OBSOLESCENT (retained only for backward compatibility)
</syntax>

    <description>
This function exists only for backward compatibility with old CoCoA code.  It
returns a string containing just a newline; in CoCoA-5 it is simpler to write
<quotes><backslash/>n</quotes>.
<example>
/**/  str1 := "Line 1" + NewLine() + "Line 2"; --> old CoCoA-4 way
/**/  str2 := "Line 1\nLine 2";                --> more compact in CoCoA-5
/**/  str1 = str2;
True
/**/ Print str2;
Line 1
Line2
</example>
    </description>

    <seealso>
      <see>string</see>
      <see>PrintLn</see>
      <see>ascii</see>
    </seealso>

    <types>
      <type>string</type>
      <type>io</type>
      <type>printing</type>
    </types>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>NewList</title>
    <short_description>create a new list</short_description>

    <description>
The second function returns a list of length N, filled by E.  The
first function, in which E is not indicated, returns a list of length
N filled with 0 (<tt>INT</tt>).

<example>
/**/  NewList(4,"a");
["a", "a", "a", "a"]

/**/  NewList(4);
[0, 0, 0, 0]
</example>
    </description>

    <syntax>
NewList(N:INT):LIST
NewList(N:INT, E:OBJECT)
</syntax>

    <seealso>
      <see>list</see>
    </seealso>

    <types>
      <type>list</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>NewMat</title>
    <short_description>create a new matrix</short_description>

    <description>
The second function returns an MxN matrix, filled by Val.  The first
function, in which Val is not indicated, returns an MxN matrix filled
with <quotes>zero(R)</quotes> values.

<example>
/**/  Use S ::= QQ[x,y,z];
/**/  NewMat(S,2,3);
matrix([
  [0, 0, 0],
  [0, 0, 0]
])

/**/  NewMat(2,3, RingElem(QQ,4));
matrix([
  [4, 4, 4],
  [4, 4, 4]
])
</example>
    </description>

    <syntax>
NewMat(R:RING, M:INT, N:INT):MAT
NewMat(M:INT, N:INT, Val:RINGELEM):MAT
</syntax>

    <seealso>
      <see>matrix</see>
    </seealso>

    <types>
      <type>matrix</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>NewPolyRing</title>
  <short_description>create a new PolyRing</short_description>

<syntax>
NewPolyRing(CoeffRing:RING, IndetNames:LIST):RING
NewPolyRing(CoeffRing:RING, IndetNames:LIST, OrdMat:MAT, GradingDim:INT):RING
</syntax>
<description>
This function returns a polynomial ring which can be used as any
programming variable (assigned with <tt>:=</tt>).
<par/>
The <tt>::=</tt> syntax starts the input method for a new polynomial ring,
with the special interpretation of brackets and symbols
(i.e. R ::= QQ[x] is not read as X := LL[i])
<par/>
NB: calling <tt>NewPolyRing</tt> twice with the same arguments gives
two <em>different rings</em>, therefore incompatible.
<example>
/**/  R ::= QQ[x,y,alpha]; -- is equivalent to
/**/  R := NewPolyRing(RingQQ(), ["x","y","alpha"]);

/**/  R ::= QQ[x,y], DegRevLex; -- is equivalent to
/**/  R := NewPolyRing(RingQQ(), ["x","y"], StdDegRevLexMat(2), 1);

/**/  OrdM := matrix([[2,3],[1,0]]);
/**/  P := NewPolyRing(QQ, ["x","y"], OrdM, 1);
/**/  GradingDim(P);
1
/**/  P2 := NewPolyRing(RingZZ(), IndetSymbols(P));
/**/  Indets(P2);
[x, y]
/**/  P3 := NewPolyRing(P2, SymbolRange("alpha", 0,2));
/**/  indets(P3);
[alpha[0], alpha[1], alpha[2]]
</example>
</description>


    <seealso>
      <see>IndetSymbols</see>
      <see>SymbolRange</see>
      <see>GradingDim</see>
    </seealso>

    <types>
      <type>ring</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>NewQuotientRing</title>
  <short_description>create a new quotient ring</short_description>
  
<syntax>
NewQuotientRing(R:RING, I:IDEAL):RING
R/I
</syntax>
<description>
<example>
/**/  Use Qi ::= QQ[i];
/**/  CC := Qi/ideal(i^2+1);  -- sort of  ;-)
/**/  Use CC[x];
/**/  (x+i)^2;
(2*i*x +x^2 -1)

/**/  R ::= QQ[x,y,z];
/**/  S := NewQuotientRing(R, ideal(indet(R,1)-3));
/**/  Use S;
/**/  (x+y)^2;
(y^2 +6*y +9)
</example>
</description>

<seealso>
  <see>QuotientBasis</see>
  <see>NewFractionField</see>
</seealso>

<types>
  <type>ring</type>
</types>

</command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>NewRingFp</title>
    <short_description>create a new finite field</short_description>

    <description>
<par/>

<example>
...work in progress...
</example>
    </description>

    <syntax>
NewRingFp(INT, P):RING
</syntax>

    <seealso>
      <see>NewQuotientRing</see>
    </seealso>

    <types>
      <type>ring</type>
    </types>

    <keys>
      <key>NewZZMod</key>
      <key>NewFp</key>
      <key>NewFFp</key>
    </keys>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>NextPrime</title>
    <short_description>find the next largest prime number</short_description>

    <description>
This function computes the smallest prime number greater than <code>N</code>.  If
<code>N</code> is negative or too large then an error is signalled.  The upper
limit depends on the computer you are using; it is probably <formula>2^31</formula>
or <formula>2^63</formula>.

<example>
/**/  NextPrime(1000);
1009
</example>
    </description>

    <syntax>
NextPrime(N:INT):INT
</syntax>

    <seealso>
      <see>IsPrime</see>
      <see>NextProbPrime</see>
    </seealso>

    <types>
      <type>integer</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>NextProbPrime</title>
    <short_description>find the next largest probable prime number</short_description>

    <description>
This function computes the smallest probable prime number greater than <code>N</code>.  If
<code>N</code> is negative, an error is generated.  To be absolutely certain the number
produced is prime, you must call <code>IsPrime</code> on it, but this may be very costly.

<example>
/**/  NextProbPrime(1000);
1009

/**/  NextProbPrime(10^50);
100000000000000000000000000000000000000000000000151
</example>
    </description>

    <syntax>
NextProbPrime(N:INT):INT

</syntax>

    <seealso>
      <see>IsPrime</see>
      <see>IsProbPrime</see>
      <see>NextPrime</see>
    </seealso>

    <types>
      <type>integer</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>NF</title>
    <short_description>normal form</short_description>

    <description>
The first function returns the normal form of F with respect to I.
It also computes a Groebner basis of I if that basis has not been
computed previously.
<par/>
The second function returns the normal form of V with respect to M. It
also computes a Groebner basis of M if that basis has not been
computed previously.
<par/>
Currently (v 5.0.3) only full reduction is computed: each monomial in
the result cannot be reduced.  CoCoA-4 allowed setting the flag
FullRed (of the panel GROEBNER) to False so that only the leading term
is reduced.
<par/>
Currently (v 5.0.3) polynomial ideals are implemented only with coeffs
in a field.

<example>
/**/  Use R ::= QQ[x,y,z];
/**/  I := ideal(z);
/**/  NF(x^2+x*y+x*z+y^2+y*z+z^2, I);
x^2 +x*y +y^2

/**/  I := ideal(z-1);
/**/  NF(x^2+x*y+x*z+y^2+y*z+z^2, I);
x^2 +x*y +y^2 +x +y +1
</example>
    </description>

    <syntax>
NF(F:POLY, I:IDEAL):POLY
NF(V:MODULEELEM, M:MODULE):MODULEELEM
</syntax>

    <seealso>
      <see>DivAlg</see>
      <see>GenRepr</see>
      <see>IsIn</see>
      <see>NFsAreZero</see>
      <see>NR</see>
    </seealso>

    <types>
      <type>groebner</type>
      <type>groebner-basic</type>
      <type>ideal</type>
      <type>module</type>
      <type>polynomial</type>
      <type>moduleelem</type>
    </types>

    <keys>
    <key>normal form</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>NFsAreZero</title>
    <short_description>test if normal forms are zero</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This function returns True if each component of L
has normal form 0 with respect to M, i.e., if each component is an
element of M.  Otherwise, it returns False.  The coefficient ring is
assumed to be a field.

<example>
  Use S ::= QQ[t,x,y,z];
  I := ideal(t^31-t^6-x, t^8-y, t^10-z);
  F := y^5-z^4;
  G := (t^8-y)(3F+t^10-z);
  NFsAreZero([F, G], I);   -- F and G are in I
True
-------------------------------
  NFsAreZero([F,x, G], I); -- x is not in I
False
-------------------------------
</example>
    </description>

    <syntax>
NFsAreZero(L:LIST of POLY, M:IDEAL):BOOL
NFsAreZero(L:LIST of MODULEELEM, M:MODULE):BOOL
</syntax>

    <seealso>
      <see>IsIn</see>
      <see>NF</see>
    </seealso>

    <types>
      <type>groebner</type>
      <type>groebner-basic</type>
      <type>ideal</type>
      <type>polynomial</type>
      <type>module</type>
      <type>moduleelem</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>NmzComputation</title>
  <short_description>...</short_description>
  
<syntax>
NmzComputation(Cone:RECORD): RECORD;
</syntax>
<description>
(while waiting for a proper description, have a guess from this example ;-)
<example>
/**/ Cone := Record[ integral_closure := mat([[1,2],[2,1]]) ];
/**/ NC := NmzComputation(Cone,
                          ["HilbertBasis","SupportHyperplanes"]
                          );
/**/ indent(NC);
Record[
  HilbertBasis := [[2, 1], [1, 2], [1, 1]],
  SupportHyperplanes := [[-1, 2], [2, -1]]
]
</example>
</description>

<seealso>
</seealso>

<types>
  <type>record</type>
</types>

<keys>
  <key>normaliz</key>
  <key>normalizcomputation</key>
</keys>
</command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>NmzHilbertBasis</title>
  <short_description>Hilbert Basis of a monoid</short_description>
  
<syntax>
NmzHilbertBasis(M:MATRIX):MATRIX
</syntax>
<description>
Given a matrix M, this function returns a matrix whose rows represent
 the Hilbert Basis for the monoid generated by the rows of M.
<example>
/**/     M:= matrix([[0,1],[3,1]]);
/**/     NmzHilbertBasis(M);
--the Hilbert basis of the monoid generated by the vectors [0,1] and [3,1] is...
matrix( /*QQ*/
 [[3, 1],
  [0, 1]]
 )
-- ... ([3,1], [0,1])

-- Different result for...
/**/     HilbertBasisKer(M); 
-- the Hilbert basis of M is the Hilbert basis of the monoid of
-- elements in the kernel of M, namely...
[]
-- ...no elements! (except the zero-element) 
</example>
</description>

<seealso>
  <see>HilbertBasisKer</see>
  <see>NmzComputation</see>
  <see>NmzNormalToricRing</see>
  <see>NmzIntClosureMonIdeal</see>
</seealso>

<types>
</types>

<keys>
  <key>normaliz</key>
  <key>hilbert basis</key>
</keys>
</command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>NmzIntClosureMonIdeal</title>
    <short_description>integral closure of a monomial ideal</short_description>

    <description>
Given a list L of power-products in a ring R, the function returns the 
generators the integral closure of the ideal generated by the elements in L.

<example>
/**/     Use R::=QQ[x,y,z,t];
/**/     NmzIntClosureMonIdeal([x^2,y^2,z^3]);
-- the integral closure of the ideal generated by x^2,y^2 and z^3 is...
[y^2, x^2, x*y, z^3, y*z^2, x*z^2]
-- ...the ideal generated by y^2, x^2, x*y, z^3, y*z^2 and x*z^2
</example>
    </description>

    <syntax>
NmzIntClosureMonRing(L:LIST of RINGELEM ):LIST of RINGELEM

where L is a list of power-products in a ring R.
</syntax>

    <seealso>
      <see>NmzComputation</see>
      <see>NmzHilbertBasis</see>
      <see>NmzNormalToricRing</see>
      <see>NmzIntClosureMonIdeal</see>
    </seealso>

    <types>
    </types>

    <keys>
      <key>normaliz</key>
      <key>integral closure</key>
      <key>integralclosure</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>NmzIntClosureToricRing</title>
    <short_description>integral closure of a toric ring</short_description>

    <description>
Given a list L of power-products in a ring R, the function returns the 
generators of the integral closure of the algebra generated by the list. 
 
<example>
/**/     Use R::=QQ[x,y,t];
/**/     NmzIntClosureToricRing([x^3,x^2*y,y^3]);
-- the integral closure of QQ[x^3, x^2*y, y^3] is...
[y,x]
-- ... QQ[y, x]
</example>
    </description>

    <syntax>
NmzIntClosureToricRing(L:LIST of RINGELEM):LIST of RINGELEM

where L is a list of power-products in a ring R.
</syntax>

    <seealso>
      <see>NmzComputation</see>
      <see>NmzHilbertBasis</see>
      <see>NmzNormalToricRing</see>
      <see>NmzIntClosureMonIdeal</see>
    </seealso>

    <types>
    </types>

    <keys>
      <key>normaliz</key>
      <key>integral closure</key>
      <key>integralclosure</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>NmzNormalToricRing</title>
    <short_description>normalization of a toric ring</short_description>

    <description>
Given a list L of power-products in a ring R, the function returns the 
generators of the normalization of the algebra generated by the list. 

<example>
/**/     Use R::=QQ[x,y,t];
/**/     NmzNormalToricRing([x^3,x^2*y,y^3]);
-- the normalization of QQ[x^3,x^2*y,y^3] is...
[y^3, x^2*y, x^3, x*y^2]
-- QQ[y^3, x^2*y, x^3, x*y^2]
</example>
    </description>

    <syntax>
NmzNormalToricRing(LIST of RINGELEM ):LIST of RINGELEM

</syntax>

    <seealso>
      <see>NmzComputation</see>
      <see>NmzHilbertBasis</see>
      <see>NmzIntClosureToricRing</see>
      <see>NmzIntClosureMonIdeal</see>
    </seealso>

    <types>
    </types>

    <keys>
      <key>normaliz</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>NonZero</title>
  <short_description>remove zeroes from a list</short_description>
  
<syntax>
NonZero(L:LIST or MODULEELEM):LIST
</syntax>

<description>
This function returns the list obtained by removing the zeroes from L.

<example>
/**/  Use R ::= QQ[x,y,z];
/**/  NonZero([0,0,3, ideal(y),0]);
[3, ideal(y)]
</example>
</description>

<seealso>
  <see>FirstNonZero</see>
  <see>FirstNonZeroPos</see>
  <see>IsZero</see>
</seealso>

<types>
  <type>list</type>
  <type>moduleelem</type>
</types>

<keys>
  <key>non-zero</key>
  <key>non zero</key>
</keys>
</command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>not, and, or</title>
    <short_description>boolean operators</short_description>

    <syntax>
not(A)
A and B
A or B

where A and B are of type BOOL.
</syntax>

    <description>
These operators have their usual meanings.  Note that when two or more
boolean expressions are combined with AND, they are evaluated from left to
right, stopping as soon as a False expression is found (any further
expressions are not evaluated).  For example, given the expression <tt>A and B</tt>,
CoCoA does not attempt to evaluate B unless A evaluates to True.  Similarly,
evaluation of a sequence of boolean expressions connected by OR stops
as soon as a True expression is found.

Note that from CoCoA-5.1 <tt>not</tt> is a function, so its argument must be
between brackets!
    </description>

    <types>
      <type>boolean</type>
    </types>

    <keys>
    <key>logical</key>
    <key>operator</key>
    <key>logical operator</key>
    <key>logical and</key>
    <key>logical or</key>
    <key>logical not</key>
    </keys>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>NR</title>
    <short_description>normal reduction</short_description>

    <description>
This function returns the normal remainder of X with respect to L,
i.e., it returns the remainder from the division algorithm.  To get
both the quotients and the remainder, use <ttref>DivAlg</ttref>.
<par/>
Note that if the list does not form a Groebner basis, the remainder
may not be zero even if X is in the ideal or module generated by L
(use <ttref>GenRepr</ttref> or <ttref>NF</ttref> instead).
<par/>
Currently (v 5.0.3) the internal code for computing 
<code>NF(F, I)</code> and <code>NR(F, GBasis(I))</code> is identical,
but the second is slower just for the overhead in interpreting a
possibly long list of polynomials.

<example>
/**/  Use R ::= QQ[x,y,z];
/**/  F := x^2*y +x*y^2 +y^2;
/**/  NR(F, [x*y-1, y^2-1]);
x +y +1

/**/  V := Vector(x^2 +y^2 +z^2, x*y*z);  --***OBSOLETE MANUAL: WORK IN PROGRESS***
/**/  NR(V,[Vector(x,y), Vector(y,z), Vector(z,x)]);
Vector(z^2, z^3 - y*z - z^2)
</example>
    </description>

    <syntax>
NR(X:POLY, L:LIST of POLY):POLY
NR(X:MODULEELEM, L:LIST of MODULEELEM):MODULEELEM
</syntax>

    <seealso>
      <see>DivAlg</see>
      <see>GenRepr</see>
      <see>NF</see>
    </seealso>

    <types>
      <type>polynomial</type>
      <type>moduleelem</type>
    </types>

    <keys>
    <key>normal reduction</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>num</title>
    <short_description>numerator</short_description>

    <description>
These functions return the numerator and denominator of N.
<par/>
The fragile syntax in CoCoA 4 <tt>N.Num</tt> and <tt>N.Den</tt> is no
longer supported.

<example>
/**/  num(3);
3

/**/  P ::= QQ[x,y];
/**/  F := NewFractionField(P);
/**/  Use F;
/**/  Den(x/(x+y));
x
</example>
    </description>

    <syntax>
num(N:INT or RAT):INT
num(N:POLY or RATFUN):POLY
</syntax>

    <seealso>
      <see>Numerators and Denominators for Rational Functions</see>
      <see>Numerators and Denominators for Rational Numbers</see>
      <see>den</see>
    </seealso>

    <types>
      <type>integer</type>
      <type>polynomial</type>
      <type>rat</type>
      <type>ratfun</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>NumCols</title>
    <short_description>number of columns in a matrix</short_description>

    <description>
This function returns the number of columns in a matrix.

<example>
/**/  M := mat([[1,2,3], [4,5,6]]);
/**/  NumCols(M);
3
</example>
    </description>

    <syntax>
NumCols(M):INT
</syntax>

    <seealso>
      <see>matrix</see>
      <see>NumRows</see>
    </seealso>

    <types>
      <type>matrix</type>
    </types>

    <keys>
    <key>number of columns</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>NumCompts</title>
  <short_description>the number of components of a vector</short_description>

<syntax>
NumCompts(X:MODULEELEM or MODULE):INT
</syntax>
<description>
If X is a MODULEELEM, it returns the number of components of X.
If X is a MODULE, it returns the rank of the free module in which X is
defined.
<par/>
This function used to be called <tt>NumComps</tt> in CoCoA-4.
<example>
/**/  Use R ::= QQ[x,y];
/**/  R2 := NewFreeModule(R, 3);
/**/  M := SubmoduleRows(R2, matrix(R, mat([[x,0,y], [x^2+y^2,x^2,3]])));
/**/  NumCompts(M);
3
/**/  NumCompts(gens(M)[1]);
3
</example>
</description>

<seealso>
  <see>len</see>
</seealso>

<keys>
  <key>NumCompts</key>
  <key>free module rank</key>
  <key>FreeModuleRank</key>
</keys>

<types>
  <type>moduleelem</type>
  <type>module</type>
</types>

</command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>NumIndets</title>
    <short_description>number of indeterminates</short_description>

    <syntax>
NumIndets(R:RING):INT
</syntax>

    <description>
This function returns the number of indeterminates of the current ring or
of R.

<example>
/**/  S ::= QQ[x,y];
/**/  R ::= QQ[x,y,z];
/**/  NumIndets(R);
3

/**/  NumIndets(S);
2
</example>
    </description>

    <seealso>
      <see>indet</see>
      <see>IndetSubscripts</see>
      <see>IndetIndex</see>
      <see>IndetName</see>
      <see>indets</see>
    </seealso>

    <types>
      <type>ring</type>
    </types>

  </command>

<!-- ===  COMMAND  =============================================== -->
<command>
  <title>NumPartitions</title>
  <short_description>number of partitions of an integer</short_description>

<syntax>
NumPartitions(N):INT
</syntax>
<description>
This function returns the number of partitions of a non-negative integer,
i.e. the number of distinct ways of writing <code>N</code> as a sum of positive integers.
<example>
/**/  NumPartitions(2); -- 2 and 1+1
2
/**/  NumPartitions(5);
7
</example>
    </description>

    <types>
      <type>INT</type>
    </types>

    <keys>
    <key>number of partitions</key>
    <key>combinatorics</key>
    </keys>
  </command>

<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>NumRows</title>
    <short_description>number of rows in a matrix</short_description>

    <syntax>
NumRows(M):INT
</syntax>

    <description>
This function returns the number of rows in a matrix.

<example>
/**/  M := mat([[1,2,3], [4,5,6]]);
/**/  NumRows(M);
2
</example>
    </description>

    <seealso>
      <see>matrix</see>
      <see>NumCols</see>
    </seealso>

    <types>
      <type>matrix</type>
    </types>

    <keys>
    <key>number of rows</key>
    </keys>
  </command>

 </chapter_letter>
 <!-- ===  CHAPTER  =============================================== -->
 <chapter_letter>
   <title>O</title>

<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>one</title>
    <short_description>one of a ring</short_description>

    <description>
This function return the multiplicative identity of a ring.
For when you want to force the integer <tt>1</tt> to be a
<tt>RINGELEM</tt>.

<example>
/**/ P ::= ZZ/(101)[x,y,z];
/**/ N := 1;  Print N, " of type ",  type(N);
1 of type INT
/**/ N := one(P);  Print N, " of type ",  type(N);
1 of type RINGELEM
/**/ N := 300*1;  Print N, " of type ",  type(N);
300 of type INT
/**/ N := 300*one(P);  Print N, " of type ",  type(N);
-3 of type RINGELEM
</example>
    </description>

    <syntax>
one(R:RING):RINGELEM
</syntax>

    <seealso>
      <see>zero</see>
    </seealso>

    <types>
      <type>ring</type>
      <type>ringelem</type>
    </types>

    <keys>
      <key>cast</key>
      <key>convert</key>
    </keys>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>OpenIFile</title>
    <short_description>open input file</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This function opens the file with name S for input.
Input from that file can then be read with <ttref>Get</ttref>.
<par/>
(Note: one would normally use <ttref>source</ttref> to read CoCoA commands from a file.)

<example>
  D := OpenOFile("my-test");  -- open "my-test" for output from CoCoA
  Print "hello world" On D;   -- print string into "mytest"
  Close(D);
  D := OpenIFile("my-test");  -- open "my-test" for input to CoCoA
  Get(D,3);  -- get the first three characters (in Ascii code)
[104, 101, 108]
-------------------------------
  ascii(It);  -- convert the ASCII code into characters
hel
-------------------------------
  Close(D);
</example>
    </description>

    <syntax>
OpenIFile(S:STRING):DEVICE
</syntax>

    <seealso>
      <see>close</see>
      <see>Introduction to IO</see>
      <see>OpenOFile</see>
      <see>OpenIString</see>
      <see>OpenOString</see>
      <see>OpenSocket</see>
      <see>source</see>
    </seealso>

    <types>
      <type>io</type>
      <type>printing</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>OpenIString</title>
    <short_description>open input string</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This function open strings for input.  The string S
serves as the name of the device opened for input or output; one may
use the empty string.  <tt>OpenIString</tt> is used to read input from the
string T with the help of <ttref>Get</ttref>.

<example>
  S := "hello world";
  D := OpenIString("", S);  -- open the string S for input to CoCoA
  L := Get(D,7);  -- read 7 characters from the string
  L;  -- ASCII code
[104, 101, 108, 108, 111, 32, 119]
-------------------------------
  ascii(L); -- convert ASCII code to characters
hello w
-------------------------------
  Close(D);  -- close device D
</example>
    </description>

    <syntax>
OpenIString(S:STRING, T:STRING):DEVICE
OpenOString(S:STRING):DEVICE
</syntax>

    <seealso>
      <see>close</see>
      <see>Introduction to IO</see>
      <see>OpenOString</see>
      <see>OpenIFile</see>
      <see>OpenOFile</see>
      <see>source</see>
      <see>sprint</see>
    </seealso>

    <types>
      <type>io</type>
      <type>printing</type>
      <type>string</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>OpenLog</title>
    <short_description>open a log of a CoCoA session</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This function opens the output device D and starts to record the
output from a CoCoA session on D.  The <ttref>CloseLog</ttref> closes the
device D and stops recording the CoCoA session on D.
<par/>
At present the choices for the device D are an output file (see
<ttref>OpenOFile</ttref>) or an output string (see <ttref>OpenOString</ttref>).  Several output
devices may be open at a time.  If the panel option <tt>Echo</tt> is set to
True, both the input and output of the CoCoA session are logged;
otherwise, just the output is logged.

<example>
  D := OpenOFile("MySession");
  OpenLog(D);
  1+1;
2
-------------------------------
  G := 1;
  Set Echo;
  2+2;
2 + 2
4
-------------------------------
  F := 2;
F := 2
  CloseLog(D);
CloseLog(D)
  UnSet Echo;
SET(Echo, False)

-- The contents of "MySession":
2
-------------------------------
2 + 2
4
-------------------------------
F := 2
CloseLog(D)
</example>
    </description>

    <syntax>
OpenLog(D:DEVICE):NULL
</syntax>

    <seealso>
      <see>Introduction to IO</see>
      <see>OpenIFile</see>
      <see>OpenOFile</see>
      <see>OpenIString</see>
      <see>OpenOString</see>
      <see>Unset</see>
    </seealso>

    <types>
      <type>io</type>
      <type>printing</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>OpenOFile</title>
    <short_description>open output file</short_description>

    <description>
This function opens the file with name S---creating it if it
does not already exist---for output.  If used with second argument
<tt>w</tt> or <tt>W</tt> then it immediately erases the file S.
The function <ttref>Print On</ttref> is then used for appending output to S.

<example>
  D := OpenOFile("my-test");  -- open "my-test" for output from CoCoA
  Print "hello world" On D;   -- print string into "mytest"
  Print " test" On D;  -- append to the file "mytest"
  Close(D);  -- close the file
  D := OpenOFile("my-test","w"); -- clear "my-test"
  Print "goodbye" On D; -- "mytest" now consists only of the string "goodbye"
  Close(D);
</example>
    </description>

    <syntax>
OpenOFile(S:STRING):DEVICE
OpenOFile(S:STRING,"w" or "W"):DEVICE
</syntax>

    <seealso>
      <see>close</see>
      <see>Introduction to IO</see>
      <see>OpenIFile</see>
      <see>OpenIString</see>
      <see>OpenOString</see>
      <see>source</see>
    </seealso>

    <types>
      <type>io</type>
      <type>printing</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>OpenOString</title>
    <short_description>open output string</short_description>

    <description>
This function opens strings for output.  The string S
serves as the name of the device opened for input or output; one may
use the empty string.  <tt>OpenOString</tt> is used to write to a
string with the help of <tt>Print On</tt>.

<example>
  D := OpenOString("");  -- open a string for output from CoCoA
  L := [1,2,3]; -- a list
  Print L On D;  -- print to D
  D;
Record[Name := "", Type := "OString", Protocol := "CoCoALanguage"]
-------------------------------
  S := Cast(D, STRING);  -- S is the string output to D
  S; -- a string
[1, 2, 3]
-------------------------------
  Print " more characters" On D;  -- append to the existing output string
  Cast(D, STRING);
[1, 2, 3] more characters
-------------------------------
</example>
    </description>

    <syntax>
OpenOString(S:STRING):DEVICE
</syntax>

    <seealso>
      <see>close</see>
      <see>Introduction to IO</see>
      <see>OpenIFile</see>
      <see>OpenOFile</see>
      <see>OpenIString</see>
      <see>source</see>
      <see>sprint</see>
    </seealso>

    <types>
      <type>io</type>
      <type>printing</type>
      <type>string</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>OpenSocket</title>
    <short_description>open a socket connection</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This function opens a client socket (I/O) connection.
It requires the name of the machine with the server socket and the
port number (expressed as a STRING).
<par/>
CoCoA-4  communicates with the CoCoAServer via socket which, by
default, runs on <tt>localhost</tt> on
port <tt><quotes>0xc0c0</quotes></tt>.
To change these settings redefine in your <tt>userinit.coc</tt> or
<tt>.cocoarc</tt> the variables
<verbatim>
  MEMORY.CoCoAServerMachine := <quotes>localhost</quotes>;
  MEMORY.CoCoAServerPort := <quotes>0xc0c0</quotes>;
</verbatim>

<example>
  D := OpenSocket("localhost", "10000");
  Print 100^6 On D;
  Source D;
  Close(D);
</example>
    </description>

    <syntax>
OpenSocket(Machine: STRING, Port: STRING): DEVICE
</syntax>

    <seealso>
      <see>Introduction to IO</see>
      <see>OpenIFile</see>
      <see>OpenOFile</see>
      <see>OpenIString</see>
      <see>OpenOString</see>
      <see>Unset</see>
    </seealso>

    <types>
      <type>io</type>
      <type>printing</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>Option</title>
    <short_description>status of a panel option</short_description>

    <description>
*** OBSOLETE ***
This function returns the status of a panel option (True/False).  For
a list of panels, use <ttref>panels</ttref> and for the current status of each
option for a panel with name P, use <tt>panel(P)</tt>.
The function <tt>Option</tt> is particularly
useful inside a user-defined function in order to temporarily change
the value of an option (restoring the option&apos;s original value when the
function is complete). See <ref>Setting Options</ref> for an example of this
use of <tt>Option</tt>.
--***OBSOLETE MANUAL: WORK IN PROGRESS***

<example>
  Option(Indentation);
False
-------------------------------
</example>
    </description>

    <syntax>
Option(O):BOOL

where O is a panel option.
</syntax>

    <seealso>
      <see>Introduction to Panels</see>
      <see>panel</see>
      <see>panels</see>
      <see>Setting Options</see>
      <see>Unset</see>
    </seealso>

    <types>
      <type>panels</type>
      <type>system</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>OrdMat</title>
    <short_description>matrix defining a term-ordering</short_description>

    <description>
This function returns a matrix which describes the term-ordering
of the ring <tt>R</tt>.

<example>
/**/  Use S ::= QQ[x,y,z];
/**/  M := mat([ [1,2,3], [3,4,5], [0,0,1]]);
/**/  P := NewPolyRing(CoeffRing(S), IndetSymbols(S), M, 2);
/**/  GradingDim(P);
2
/**/  OrdMat(P);
matrix( /*QQ*/
 [[1, 2, 3],
  [3, 4, 5],
  [0, 0, 1]]
 )

/**/  GradingDim(S);
1
/**/  OrdMat(S);
matrix( /*QQ*/
 [[1, 1, 1],
  [0, 0, -1],
  [0, -1, 0]]
 )
</example>
    </description>

    <syntax>
OrdMat(R:RING):MAT
</syntax>

    <seealso>
      <see>StdDegLexMat</see>
      <see>StdDegRevLexMat</see>
      <see>LexMat</see>
      <see>RevLexMat</see>
      <see>XelMat</see>
      <see>elim</see>
      <see>GradingDim</see>
      <see>Orderings</see>
      <see>Predefined Term-Orderings</see>
    </seealso>

    <types>
      <type>ring</type>
      <type>mat</type>
    </types>

  </command>

 </chapter_letter>
 <!-- ===  CHAPTER  =============================================== -->
 <chapter_letter>
   <title>P</title>

<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>Packages</title>
    <short_description>list of loaded packages</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This function returns the names of the loaded packages as a list of
strings.  The string <tt>$user</tt> refers to the user-defined
functions defined in the current CoCoA session.

<example>
  Packages();
["$builtin", "$coclib", "$user", "$help", "$io", "$misc"]
-------------------------------
</example>
    </description>

    <syntax>
Packages():LIST
</syntax>

    <seealso>
      <see>CoCoA Packages</see>
      <see>Supported Packages</see>
    </seealso>

    <types>
      <type>packages</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>panel</title>
    <short_description>print status of a panel&apos;s options</short_description>

    <description>
This command prints the status of the options in one of the three
panels.  It returns no value.

<example>
  Panel(GENERAL);

Echo............... : False
Timer.............. : False
Trace.............. : False
Indentation........ : False
TraceSources....... : False
SuppressWarnings... : False
ComputationStack... : False
-------------------------------
</example>
    </description>

    <syntax>
Panel(E)

where E is one of "GENERAL" or "GROEBNER".
</syntax>

    <seealso>
      <see>Introduction to Panels</see>
      <see>Option</see>
      <see>panels</see>
      <see>Unset</see>
    </seealso>

    <types>
      <type>panels</type>
      <type>system</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>panels</title>
    <short_description>list of CoCoA panels</short_description>

    <description>
This function returns a list of CoCoA&apos;s panels.

<example>
  Panels();
["GENERAL", "GROEBNER"]
-------------------------------
  Panel(It[1]);

Echo............... : False
Timer.............. : False
Trace.............. : False
Indentation........ : False
TraceSources....... : False
SuppressWarnings... : False
ComputationStack... : False
-------------------------------
</example>
    </description>

    <syntax>
Panels()
</syntax>

    <seealso>
      <see>Introduction to Panels</see>
      <see>Option</see>
      <see>panel</see>
      <see>Unset</see>
    </seealso>

    <types>
      <type>panels</type>
      <type>system</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>partitions</title>
    <short_description>partitions of an integer</short_description>

    <description>
These function returns all integer partitions of N, positive integer

<example>
/**/  partitions(3);
[[3], [1, 2], [1, 1, 1]]
</example>
    </description>

    <syntax>
partitions(N: INT): LIST
</syntax>

    <seealso>
      <see>subsets</see>
      <see>tuples</see>
    </seealso>

    <types>
      <type>integer</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>permutations</title>
    <short_description>returns all permutations of the entries of a list</short_description>

    <description>
This function computes all permutations of the entries of a list (set).
If L has repeated elements it will return repeated elements.

<example>
/**/  permutations(3..5);
[[3, 4, 5], [3, 5, 4], [4, 3, 5], [4, 5, 3], [5, 3, 4], [5, 4, 3]]

/**/  permutations([2, 2, x]);
[[2, 2, x], [2, x, 2], [2, 2, x], [2, x, 2], [x, 2, 2], [x, 2, 2]]

/**/  MakeSet(permutations([2, 2, x]));
[[2, 2, x], [2, x, 2], [x, 2, 2]]
</example>
    </description>

    <syntax>
permutations(L: LIST): LIST
</syntax>

    <seealso>
      <see>subsets</see>
      <see>tuples</see>
    </seealso>

    <types>
      <type>list</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>PerpIdealOfForm</title>
    <short_description>Ideal of derivations annihilating a form</short_description>

    <syntax>
PerpIdealOfForm(F:POLY)

where <tt>F</tt> is homogeneous.
</syntax>

    <description>
Given a form <tt>F</tt> computes the ideal of derivations killing it.
<par/>
For the sake of simplicity Forms/Polynomials and Derivations live in
the same ring, the distinction between them is purely formal.

<example>
/**/  Use R ::= QQ[x,y,z];
/**/  PerpIdealOfForm(x^3+x*y*z);
ideal(z^2, y^2, x^2 -6*y*z)

/**/  Hilbert(R/It);
H(0) = 1
H(1) = 3
H(2) = 3
H(3) = 1
H(t) = 0   for t >= 4
</example>
    </description>

    <seealso>
      <see>InverseSystem</see>
      <see>DerivationAction</see>
    </seealso>

    <types>
      <type>poly</type>
    </types>

    <keys>
    <key>carlini</key>
    </keys>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>pfaffian</title>
    <short_description>the Pfaffian of a skew-symmetric matrix</short_description>

    <description>
This function returns the Pfaffian of M.

<example>
/**/  Use R ::= QQ[x,y];
/**/  pfaffian(mat([[0,y],[-y,0]]));
y
</example>
    </description>

    <syntax>
pfaffian(M:MAT)

where M is skew-symmetric.  The resulting type depends on the entries
of the matrix.
</syntax>

    <seealso>
      <see>det</see>
    </seealso>

    <types>
      <type>matrix</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>PkgName</title>
    <short_description>returns the name of a package</short_description>

    <description>
This function returns the (long) name of a package.  The first form
returns <tt>$coclib</tt> and the second returns the name of the package
whose name or alias is S.  This function is useful as a shorthand,
when S is an alias, for the full name a package.

<example>
  GB.PkgName();
$gb
-------------------------------
  $gb.PkgName();
$gb
-------------------------------
  PkgName();
$coclib
-------------------------------
</example>
    </description>

    <syntax>
PkgName():STRING
S.PkgName():STRING

where S is the identifier or alias for a package.
</syntax>

    <types>
      <type>packages</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>PlotPoints</title>
    <short_description>outputs the coordinates of the points to a file</short_description>

    <description>
This function outputs the coordinates of the points (with two
components) to a file called <quotes>CoCoAPlot</quotes>.
See <ttref>PlotPointsOn</ttref> for outputting to another file.
<par/>
This result can be plotted using your preferred plotting program.
For example, start <quotes>gnuplot</quotes> and then give it the command
<verbatim>  plot <quotes>CoCoAPlot</quotes></verbatim>
to see the plot.

<example>
/**/  PlotPoints([ [X, X^2-X+14] | X In -10..10]);
Plotting points...100%
21 plotted points have been placed in the file CoCoAPlot
</example>

    </description>

    <syntax>
PlotPoints(L: LIST of points)
</syntax>

    <types>
      <type>list</type>
    </types>

    <seealso>
      <see>ImplicitPlot</see>
      <see>PlotPointsOn</see>
    </seealso>

    <keys>
    <key>gnuplot</key>
    <key>plot points</key>
    </keys>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>PlotPointsOn</title>
    <short_description>outputs the coordinates of the points to a file</short_description>

    <description>
This function is the same as <ttref>PlotPoints</ttref> with a second
argument giving the name of the file to print on.
<par/>
Note that the last argument is a STRING, the name of the file, and not
a DEVICE, as for <ttref>Print On</ttref>.

<example>
/**/  PlotPointsOn([ [1/(X+1/2), X^2-X+14] | X In -10..10], "points");
Plotting points...100%
21 plotted points have been placed in the file points

/**/  ImplicitPlotOn(x^2*y - 59/4*x^2 + 2*x - 1,  [-3,3], [0,250], "curve");
Plotting points...10%...20%...30%...40%...50%...60%...70%...80%...90%...100%
735 plotted points have been placed in the file curve
</example>
After having produced the plot files using CoCoA-4,
start <quotes>gnuplot</quotes> and then give it the following commands:
<verbatim>  plot <quotes>curve</quotes>
  replot <quotes>points</quotes>
</verbatim>

    </description>

    <syntax>
PlotPointsOn(L: LIST of points, S: STRING)
</syntax>

    <types>
      <type>list</type>
    </types>

    <seealso>
      <see>ImplicitPlot</see>
      <see>PlotPoints</see>
    </seealso>

    <keys>
    <key>gnuplot</key>
    <key>plot points</key>
    </keys>

  </command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>poincare</title>
  <short_description>the Hilbert-Poincare series</short_description>

<syntax>
Poincare(M:RING or IDEAL):TAGGED("$hp.PSeries")
</syntax>
<description>
(sorry Poincare' for the lower-case: here we follow the naming
convention <em>single name goes lower-case</em>)
<par/>
Same as <ttref>HilbertSeries</ttref>.
</description>

<seealso>
  <see>HilbertSeries</see>
</seealso>

<types>
  <type>groebner</type>
  <type>groebner-basic</type>
  <type>hilbert</type>
  <type>quotient</type>
  <type>ideal</type>
  <type>ring</type>
</types>

<keys>
  <key>bigatti</key>
</keys>
</command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>PoincareMultiDeg</title>
  <short_description>the Hilbert-Poincare series wrt a multigrading</short_description>

<syntax>
PoincareMultiDeg(TAGGED("Quotient"), WM:MAT):TAGGED("$hp.PSeries")
</syntax>
<description>
***** NOT YET IMPLEMENTED *****
<par/>
Same as <ttref>HilbertSeriesMultiDeg</ttref>.

<example>
  Use R ::= QQ[x,y,z];

  WM := mat([[1,0,0],[1,-1,0]]);
  PoincareMultiDeg(R/ideal(Indets())^2, WM);
</example>
</description>

<seealso>
  <see>HilbertSeries</see>
  <see>HilbertSeriesMultiDeg</see>
  <see>Weights Modifier</see>
  <see>WeightsMatrix</see>
</seealso>

<types>
  <type>groebner</type>
  <type>groebner-basic</type>
  <type>hilbert</type>
  <type>quotient</type>
  <type>ideal</type>
  <type>ring</type>
</types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>PoincareShifts</title>
    <short_description>the Hilbert-Poincare series</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
Same as <ttref>HilbertSeriesShifts</ttref>.
    </description>

    <syntax>
PoincareShifts(M: Module, ShiftsList: LIST):TAGGED("$hp.PSeries")
PoincareShifts(M: TAGGED("Quotient"), ShiftsList: LIST)
                                           :TAGGED("$hp.PSeries")
</syntax>

    <seealso>
      <see>dim</see>
      <see>hilbert</see>
      <see>HilbertSeries</see>
      <see>HilbertSeriesShifts</see>
      <see>HVector</see>
      <see>multiplicity</see>
      <see>poincare</see>
      <see>PoincareMultiDeg</see>
      <see>Weights Modifier</see>
      <see>WeightsMatrix</see>
    </seealso>

    <types>
      <type>groebner</type>
      <type>groebner-basic</type>
      <type>hilbert</type>
      <type>quotient</type>
      <type>ideal</type>
      <type>ring</type>
    </types>

  </command>
<!-- ===  COMMAND-rm Poly =============================================== -->
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>PolyAlgebraHom</title>
    <short_description>homomorphism of polynomial algebras</short_description>

    <description>
This function create the homomorphism of (polynomial) algebras between
R and S with the same ring of ceofficients.  This is uniquely defined by
the images of the indeterminated of R.
<par/>
This is a cleaner mathematical implementation of the function
<ttref>image</ttref> in CoCoA-4.
<example>
/**/ Use R ::= QQ[x,y,z];
/**/ S ::= QQ[x[1..3]];
/**/ phi := PolyAlgebraHom(R, S, indets(S));
/**/ phi(x^2-y);
x[1]^2 -x[2]

/**/ S ::= QQ[a];
/**/ phi := PolyAlgebraHom(R, S, [RingElem(S,"a"),1,0]);
/**/ phi(x^2-y);
a^2 -1

/**/ phi := PolyAlgebraHom(R, QQ, [2,1,0]);
/**/ phi(x^2-y);
3
</example>
    </description>

    <syntax>
PolyAlgebraHom(R: RING, S: RING, images:LIST): RINGHOM
</syntax>

    <seealso>
      <see>apply</see>
      <see>CanonicalHom</see>
    </seealso>

    <types>
      <type>LIST</type>
      <type>MAT</type>
      <type>RINGELEM</type>
      <type>RINGHOM</type>
    </types>

    <keys>
    <key>map</key>
    </keys>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>PolyRingHom</title>
    <short_description>homomorphism of polynomial rings</short_description>

    <description>
This function create the homomorphism of (polynomial) algebras between
R and S.
This is uniquely defined by the images of the indeterminated of R and
the homomorphism CoeffRing(R) into S.

<par/>
<example>
/**/ R ::= QQ[x,y];
/**/ S ::= QQ[a,b,c];
/**/ SmodJ := NewQuotientRing(S, ideal(RingElem(S,"a")^2-1));

/**/ Use SmodJ;
/**/ phi := PolyRingHom(R, SmodJ, CanonicalHom(QQ,SmodJ), [a,b]);
/**/ Use R;
/**/ phi(x);
(a)
</example>
    </description>

    <syntax>
PolyRingHom(R: RING, S: RING, CoeffHom: RINGHOM, images:LIST): RINGHOM
</syntax>

    <seealso>
      <see>apply</see>
      <see>CanonicalHom</see>
    </seealso>

    <types>
      <type>LIST</type>
      <type>MAT</type>
      <type>RINGELEM</type>
      <type>RINGHOM</type>
    </types>

    <keys>
    <key>map</key>
    </keys>

  </command>
<!-- ===  COMMAND-rm PositiveGrading4 ==================================== -->
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>PowerMod</title>
    <short_description>compute a modular power efficiently</short_description>

    <description>
This function calculates efficiently an integer power modulo a given
modulus.  Thus <tt>PowerMod(A, B, M)</tt> is equal to <tt>mod(A^B, M)</tt>, but the former
is computed faster.  B must be non-negative.

<example>
/**/  PowerMod(12345,41041,41041); -- 41041 is a Carmichael number
12345

/**/  PowerMod(123456789,987654321,32003); -- cannot compute 123456789^987654321 directly
2332
</example>
    </description>

    <syntax>
PowerMod(A:INT, B:INT, M:INT):INT

</syntax>

    <types>
      <type>int</type>
    </types>

    <keys>
    <key>modular power</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>PreprocessPts</title>
  <short_description>Reduce redundancy in a set of approximate points</short_description>

<syntax>
PreprocessPts(Pts: LIST, Toler: LIST): RECORD[Points: MAT, Weights: LIST]
PreprocessPtsGrid(Pts: LIST, Toler: LIST): RECORD[Points: MAT, Weights: LIST]
PreprocessPtsAggr(Pts: LIST, Toler: LIST): RECORD[Points: MAT, Weights: LIST]
PreprocessPtsSubDiv(Pts: LIST, Toler: LIST): RECORD[Points: MAT, Weights: LIST]
</syntax>
<description>
These functions return a record containing two fields <tt>Points</tt> which is a
list of <em>well-separated</em> points, and <tt>Weights</tt> which contains the
number of input points associated to each output point.
The first argument is a matrix representing a list of points in k-dimensional space, and the
second argument is list of k tolerances (one for each dimension).
These functions detect groupings of close points, and choose a single
representative for them (which lies within the given tolerance of each
original point); the result is the list of these representatives, and the
number of original points associated to each representative.
<par/>
There are three underlying algorithms: <tt>Grid</tt> is fast but
crude, <tt>Subdiv</tt> works best when the original points are densely
packed (so the result will be a small list), and <tt>Aggr</tt> which
is better suited to situations where the original points are less
densely packed.  The function <tt>PreprocessPts</tt> automatically
chooses between <tt>Subdiv</tt> and <tt>Aggr</tt> with the aim of
minimising computation time.  Note that the <tt>Aggr</tt>
and <tt>Subdiv</tt> methods regard the tolerances as being slightly
flexible.
<par/>
For a full description of the algorithms we refer to the paper
J.Abbott, C.Fassino, L.Torrente
<em>Thinning Out Redundant Empirical Data</em> (arXiv:0702327).

<example>
/**/  Pts := mat([[-1,0],[0,0],[1,0],[99,1],[99,0],[99,-1]]);
/**/  Toler := RowMat([3,3]);
/**/  PreprocessPts(Pts, Toler);
Record[NewPoints := matrix( /*QQ*/
 [[99, 0],
  [0, 0]]), weights := [3, 3]]

/**/  PreprocessPts(Pts, RowMat([0.8,0.8]));
Record[Points := matrix( /*QQ*/
 [[-1/2, 0],
  [1, 0],
  [99, 1/2],
  [99, -1]], Weights := [2, 1, 2, 1]]

/**/  PreprocessPtsAggr(Pts, RowMat([0.9,0.9])); -- exhibits tolerance flex
Record[Points := matrix( /*QQ*/
 [[0, 0],
  [99, 0]], Weights := [3, 3]]
</example>
</description>

<types>
  <type>matrix</type>
  <type>list</type>
</types>

<seealso>
  <see>Introduction to CoCoAServer</see>
</seealso>

<keys>
  <key>abbott fassino torrente</key>
  <key>cocoalib</key>
  <key>preprocessing points</key>
</keys>
</command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>PrimaryDecomposition</title>
  <short_description>primary decomposition of an ideal</short_description>

<syntax>
PrimaryDecomposition(I: SQUAREFREE MONOMIAL IDEAL): LIST of IDEAL
</syntax>
<description>
This function returns the primary decomposition of the ideal I.
Currently it is implemented ONLY for squarefree monomial ideals
using the Alexander dual technique.
See <ttref>FrbPrimaryDecomposition</ttref> for monomial ideals.

<example>
/**/  Use R ::= QQ[x,y,z];
/**/  PrimaryDecomposition(***Ideal(xy, yz, zx)***);
[ideal(y, z), ideal(x, z), ideal(x, y)]
</example>
</description>

<seealso>
  <see>FrbPrimaryDecomposition</see>
  <see>EquiIsoDec</see>
</seealso>

<types>
  <type>monomialideal</type>
  <type>ideal</type>
</types>

</command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>PrimaryPoincare</title>
  <short_description>primary</short_description>

<syntax>
PrimaryPoincare(I: Ideal, Q: Primary Ideal): TAGGED("PSeries")
</syntax>
<description>
Let P be a polynomial ring, M the maximal ideal generated by the
indeterminates.  This function computes the Hilbert-Poincare' series
of (P/I)/((Q+I)/I), where (Q+I)/I is a primary ideal for M/I.

<example>
/**/  Use S ::= QQ[x,y,z];
/**/  I := ideal(x^3-y*z, y^2-x*z, z^2-x^2*y);
/**/  Q := ideal(y, z);
/**/  PS := PrimaryPoincare(I, Q); PS;

/**/  Use S ::= ZZ/(32003)[x,y,z,w];
/**/  I := ***Ideal(x^5 - yz, y^4 - xz^2, xy^3 - zw, x^2z - yw,
      y^2z^2 - w^3, y^3z - x^2w^2, x^3w - z^2, xyw^2 - z^3,
      x^3y^2 - w^2, xz^4 - y^2w^3, yz^5 - xw^5, y^3w^5 - z^7,
      x^2w^7 - z^8, z^9 - yw^8)***;
/**/  Q  := ideal(x, y, z);
/**/  PS := PrimaryPoincare(I, Q); PS;
/**/  $hp.PSerToHilbert(PS);

/**/  Use S ::= ZZ/(32003)[x,y,z];
/**/  I  := ideal(0);
/**/  Q  := ideal(x, y, z^2);
/**/  PS := PrimaryPoincare(I, Q); PS;
/**/  $hp.PSerToHilbert(PS);
/**/  HV := $hp.PSerHVector(PS); -- the H-vector associated to PS

/**/  Use S ::= ZZ/(32003)[x,y,z,w];
/**/  I  := ***Ideal(-yz + xw, z^3 - yw^2, -xz^2 + y^2w, -y^3 + x^2z)***;
/**/  Q  := ideal(x, y, z^2, w^3);
/**/  PS := PrimaryPoincare(I, Q); PS;
/**/  $hp.PSerToHilbert(PS);
/**/  HV := $hp.PSerHVector(PS);
/**/  P.E(0, HV);
/**/  [ P.E(J,HV) | J In 0..($hp.PSerDim(PS)-2) ];
/**/  [ P.E(J,HV) | J In 0..(len(HV)-1) ];

/**/  Use S ::= ZZ/(32003)[x,y,z,w];
/**/  I  := ***Ideal(x^3-y^7, x^2y - xw^3-z^6)***;
/**/  Q  := ideal(x, y, z, w);
/**/  PS := PrimaryPoincare(I, Q); PS;
/**/  $hp.PSerToHilbert(PS);
/**/  HV := $hp.PSerHVector(PS);
/**/  [ P.E(J,HV) | J In 0..($hp.PSerDim(PS)-2) ];
/**/  [ P.E(J,HV) | J In 0..(len(HV)-1) ];

/**/  Use S ::= ZZ/(32003)[x,y,z];
/**/  I  := ideal(z^3);
/**/  Q  := ideal(x^2, y^2, x*z, y*z);
/**/  PS := PrimaryPoincare(I, Q); PS;
/**/  $hp.PSerToHilbert(PS);
/**/  HV := $hp.PSerHVector(PS);
/**/  [ P.E(J,HV) | J In 0..($hp.PSerDim(PS)-2) ];
/**/  [ P.E(J,HV) | J In 0..(len(HV)-1) ];
</example>
</description>

<seealso>
  <see>InitialIdeal</see>
  <see>TgCone</see>
</seealso>

<types>
  <type>ideal</type>
</types>

</command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>print</title>
    <short_description>print the value of an expression</short_description>

    <description>
This command displays the value of each of the expressions, <tt>E_i</tt>.
To insert a newline write <tt><backslash/>n</tt> in the string or call
the function <ttref>NewLine</ttref> (returning a string containing a newline)
<par/>
The similar command <ttref>PrintLn</ttref> is equivalent to <tt>print</tt>
with a final newline.

<example>
/**/  for I := 1 To 10 Do  print I^2, " ";  endfor;
1 4 9 16 25 36 49 64 81 100

/**/  print "a<backslash/>nb", NewLine(), "c";
a
b
c
</example>
    </description>

    <syntax>
print E_1,...,E_n :NULL

where the E_i are CoCoA expressions.
</syntax>

    <seealso>
      <see>Print On</see>
      <see>PrintLn</see>
      <see>format</see>
      <see>Latex</see>
      <see>StarPrint, StarSprint</see>
    </seealso>

    <types>
      <type>io</type>
      <type>printing</type>
    </types>

    <keys>
    <key>printing</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>Print On</title>
    <short_description>print to an output device</short_description>

    <description>
This command prints the value of expression E to the device D.
Currently, the command can be used to print to files, strings, or the
CoCoA window.  In the first two cases, the appropriate device must be
opened with <ttref>OpenOFile</ttref> or <ttref>OpenOString</ttref>.

<example>
/**/  D := OpenOFile("my-test");  -- open "my-test" for output from CoCoA
/**/  Print "hello world" On D;   -- print string into "mytest"
/**/  close(D);  -- close the file
</example>

See <ttref>OpenOFile</ttref> for an example using output strings.
For printing to the CoCoA window, just use <tt>Print E</tt> which is short for
<tt>Print E On DEV.OUT</tt>.
    </description>

    <syntax>
Print E:OBJECT On D:DEVICE
</syntax>

    <seealso>
      <see>Introduction to IO</see>
      <see>OpenIFile</see>
      <see>OpenOFile</see>
      <see>OpenIString</see>
      <see>OpenOString</see>
      <see>print</see>
      <see>PrintLn</see>
    </seealso>

    <types>
      <type>io</type>
      <type>printing</type>
    </types>

    <keys>
    <key>printing</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>PrintLn</title>
    <short_description>print the value of an expression</short_description>

    <description>
This command is equivalent to <ttref>print</ttref> with a final newline;
in other words, it prints the values of its arguments, then moves the
cursor to the next line.

<example>
/**/  for I := 1 to 10 do
        print I^2, " ";
      EndFor;
1 4 9 16 25 36 49 64 81 100

/**/  for I := 1 to 3 do
        PrintLn I;
      EndFor;
1
2
3
</example>
    </description>

    <syntax>
PrintLn E_1,...,E_n :NULL

where the E_i are CoCoA expressions.
</syntax>

    <seealso>
      <see>print</see>
      <see>Print On</see>
    </seealso>

    <types>
      <type>io</type>
      <type>printing</type>
    </types>

    <keys>
    <key>printing</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>product</title>
    <short_description>the product of the elements of a list</short_description>

    <description>
This function returns the product of the objects in the list L and the
optional last argument.

<example>
/**/  Use R ::= QQ[x,y];
/**/  product([3, x, y^2]);
3*x*y^2

/**/  product(1..40) = factorial(40);
true

/**/  product([]);  -- gives 1 of type INT
1
/**/  product([], y);
y
/**/  product([3, x], y);
3*x*y
</example>
    </description>

    <syntax>
product(L:LIST):OBJECT
product(L:LIST, O:OBJECT):OBJECT
</syntax>

    <seealso>
      <see>Algebraic Operators</see>
      <see>sum</see>
    </seealso>

    <types>
      <type>ideal</type>
      <type>integer</type>
      <type>list</type>
      <type>matrix</type>
      <type>polynomial</type>
      <type>rat</type>
      <type>ratfun</type>
      <type>moduleelem</type>
      <type>zmod</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>PthRoot</title>
    <short_description>Compute p-th root</short_description>

    <description>
This function returns the p-th root of a polynomial over a finite
field.  If no p-th root exists then an error is signalled.  p is
the characteristic of the field.

<example>
/**/  Use R ::= ZZ/(7)[x,y];
/**/  F := x^7-y^14+3;
/**/  PthRoot(F);
-y^2+x+3
</example>
    </description>

    <syntax>
PthRoot(X:RINGELEM):RINGELEM
</syntax>

    <seealso>
      <see>IsFiniteField</see>
      <see>IsPthPower</see>
    </seealso>

    <types>
      <type>ringelem</type>
    </types>

  </command>

 </chapter_letter>
 <!-- ===  CHAPTER  =============================================== -->
 <chapter_letter>
   <title>Q</title>

<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>QQ</title>
    <short_description>the ring of rationals</short_description>

    <description>
This variable returns the ring of rationals.
Its name is protected so that it cannot be re-assigned to any other value.

<example>
/**/ Use QQ;

/**/ type(5);
INT
/**/ type(RingElem(QQ, 5));
RINGELEM
</example>
    </description>

    <syntax>
QQ
</syntax>

    <seealso>
      <see>ZZ</see>
      <see>NewQuotientRing</see>
    </seealso>

    <types>
      <type>ring</type>
    </types>

    <keys>
    </keys>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>quit</title>
    <short_description>quit CoCoA</short_description>

    <description>
This command is used to quit CoCoA.  It may be used only at top level.
    </description>

    <syntax>
quit
</syntax>

    <seealso>
      <see>ciao</see>
    </seealso>

    <types>
      <type>system</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>QuotientBasis</title>
    <short_description>vector space basis for zero-dimensional quotient rings</short_description>

<syntax>
QuotientBasis(I:IDEAL):LIST
</syntax>

    <description>
This function determines a vector space basis (of power products)
for the quotient space associated to a zero-dimensional ideal.
That is, if R is a polynomial ring with field of coefficients k, and
I is a zero-dimensional ideal in R then QuotientBasis(I) is a set of
power products forming a k-vector space basis of R/I.
<par/>
The actual set of power products chosen depends on the term ordering
in the ring R: the power products chosen are those not divisible by
the leading term of any member of the reduced Groebner basis of I
(and consequently they form a factor-closed set).

<example>
/**/  Points := [[Rand(-9,9) | N In 1..3] | S In 1..25];
/**/  Use P ::= QQ[x,y,z];
/**/  I := IdealOfPoints(P, mat(QQ, Points));
/**/  QuotientBasis(I);
[1, z, z^2, z^3, z^4, y, y*z, y*z^2, y*z^3, y^2, y^2*z, y^2*z^2, y^3, x,
x*z, x*z^2, x*z^3, x*y, x*y*z, x*y*z^2, x*y^2, x^2, x^2*z, x^2*y, x^3]

/**/  Use P ::= QQ[x,y,z], Lex;
/**/  I := IdealOfPoints(P, mat(QQ,Points));
/**/  QuotientBasis(I);     -- power products underneath the Lex reduced GBasis
[1, z, z^2, z^3, z^4, z^5, z^6, z^7, z^8, z^9, z^10, z^11, z^12, y, y*z,
y*z^2, y*z^3, y*z^4, y*z^5, y*z^6, y^2, y^2*z, y^2*z^2, y^2*z^3, y^3]
</example>
    </description>

    <seealso>
      <see>IdealOfPoints</see>
      <see>IsFactorClosed</see>
    </seealso>

    <types>
      <type>ideal</type>
    </types>

    <keys>
    <key>points</key>
    <key>quotient basis</key>
    <key>abbott</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>QZP</title>
    <short_description>change field for polynomials and ideals</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
The functions <tt>QZP</tt> and <ttref>ZPQ</ttref> map polynomials and
ideals of other rings into ones of the current ring.
When mapping from one ring to another, one of the rings must have
coefficients in the rational numbers and the other must have
coefficients in a finite field.  The indeterminates in both
rings must be identical.
<par/>
The function <tt>QZP</tt> maps polynomials with rational coefficients to
polynomials with coefficients in a finite field; the function <ttref>ZPQ</ttref>
does the reverse, mapping a polynomial with finite field coefficients
into one with rational (actually, integer) coefficients.  The function
<ttref>ZPQ</ttref> is not uniquely defined mathematically, and currently for each
coefficient the least non-negative equivalent integer is chosen.
Users should not rely on this choice, though any change will be
documented.

<example>
  Use R ::= QQ[x,y,z];
  F := 1/2*x^3 + 34/567*x*y*z - 890; -- a poly with rational coefficients
  Use S ::= ZZ/(101)[x,y,z];
  QZP(F);                            -- compute its image with coeffs in ZZ/(101)
-50x^3 - 19xyz + 19
-------------------------------
  G := It;
  Use R;
  ZPQ(G);                      -- now map that result back to QQ[x,y,z]
                               -- it is NOT the same as F...
51x^3 + 82xyz + 19
-------------------------------
  H := It;
  F - H;                       -- ... but the difference is divisible by 101
-101/2x^3 - 46460/567xyz - 909
-------------------------------
  Use S;
  QZP(H) - G;                  -- F and H have the same image in ZZ/(101)[x,y,z]
0
-------------------------------
</example>
    </description>

    <syntax>
QZP(F:POLY):POLY
QZP(F:LIST of POLY):LIST of POLY
QZP(I:IDEAL):IDEAL
</syntax>

    <seealso>
      <see>Accessing Other Rings</see>
      <see>BringIn</see>
      <see>image</see>
      <see>Ring Mappings: the Image Function</see>
    </seealso>

    <types>
      <type>ideal</type>
      <type>polynomial</type>
      <type>ring</type>
    </types>

    <keys>
    <key>change ring</key>
    <key>abbott</key>
    </keys>
  </command>

 </chapter_letter>
 <!-- ===  CHAPTER  =============================================== -->
 <chapter_letter>
   <title>R</title>

<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>radical</title>
    <short_description>radical of an ideal</short_description>

    <description>
This function computes the radical of I using the algorithm described
in the paper
<par/>
  M. Caboara, P.Conti and C. Traverso: <em>Yet Another Ideal
  Decomposition Algorithm.</em> Proc. AAECC-12, pp 39-54, 1997, Lecture
  Notes in Computer Science, n.1255 Springer-Verlag.
<par/>
NOTE: at the moment, this implementation works only if the coefficient
ring is the rationals or has large enough characteristic.

<example>
/**/  Use R ::= QQ[x,y];
/**/  I := ideal(x,y)^3;
/**/  radical(I);
ideal(y, x)
</example>
    </description>

    <syntax>
radical(I:IDEAL):IDEAL
</syntax>

    <seealso>
      <see>IsInRadical</see>
      <see>EquiIsoDec</see>
      <see>RadicalOfUnmixed</see>
    </seealso>

    <types>
      <type>groebner</type>
      <type>ideal</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>RadicalOfUnmixed</title>
    <short_description>radical of an unmixed ideal</short_description>

    <description>
This function computes the radical of an unmixed ideal.
<par/>
NOTE: at the moment, this implementation works only if the coefficient
ring is the rationals or has large enough characteristic.

<example>
/**/  Use R ::= QQ[x,y];
/**/  I := ideal(x^2 - y^2 - 4*x + 4*y, x - 2);
/**/  RadicalOfUnmixed(I);
ideal(x^2 -y^2 -4*x +4*y, x -2, y -2)
/**/ interreduced(gens(It)); -- the result may not be in its simplest form
[y -2, x -2]
</example>
    </description>

    <syntax>
RadicalOfUnmixed(I:IDEAL):IDEAL
</syntax>

    <seealso>
      <see>EquiIsoDec</see>
      <see>radical</see>
    </seealso>

    <types>
      <type>groebner</type>
      <type>ideal</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>random</title>
    <short_description>random integer</short_description>

    <description>
The function returns a random integer between X and Y, inclusive. (Note:
|X-Y| should be less than <formula>2^33</formula> to assure a more random distribution.)
<par/>
NB: every time you restart CoCoA the sequence of random numbers will
be the same (as happens in many programming languages).  If you want better
randomness, see <ttref>seed</ttref>.

<example>
/**/  random(1,100);
6

/**/  random(-10^4,0);
-3263
</example>
    </description>

    <syntax>
random(X:INT, Y:INT):INT
</syntax>

    <seealso>
      <see>randomize</see>
      <see>randomized</see>
      <see>seed</see>
    </seealso>

    <types>
      <type>integer</type>
      <type>miscellaneous</type>
    </types>

    <keys>
    <key>random</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>randomize</title>
    <short_description>randomize the coefficients of a given polynomial</short_description>

    <description>
***** NOT YET IMPLEMENTED: use random *****
<par/>
This function replaces the coefficients of terms of the polynomial
contained in V with randomly generated coefficients.  The result is
stored in V, overwriting the original polynomial.
<par/>
Note: It is possible that some coefficients will be replaced by
zeroes, i.e., some terms from the original polynomial may disappear in
the result.
<par/>
The similar function <ttref>randomized</ttref> performs the same operation,
but returns the randomized polynomial without modifying the argument.
<par/>
NB: every time you restart CoCoA the sequence of random numbers will
be the same (as in other programming languages).  If you want total
randomness read <ttref>seed</ttref>.

<example>
  Use R ::= QQ[x];
  F := 1+x+x^2;
  Randomized(F);
-2917104644x^2 + 3623608766x - 2302822308
-------------------------------
  F;
x^2 + x + 1
-------------------------------
  Randomize(F);
  F;
-1010266662x^2 + 1923761602x - 4065654277
-------------------------------
</example>
    </description>

    <syntax>
Randomize(V:POLY):POLY

where V is a variable containing a polynomial.
</syntax>

    <seealso>
      <see>random</see>
      <see>randomized</see>
      <see>seed</see>
    </seealso>

    <types>
      <type>polynomial</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>randomized</title>
    <short_description>randomize the coefficients of a given polynomial</short_description>

    <description>
***** NOT YET IMPLEMENTED: use random *****
<par/>
This function with a polynomial argument returns a polynomial
obtained by replacing the coefficients of F with randomly generated
coefficients.  The original polynomial, F, is unaffected.  With an
integer argument, it returns a random integer.
<par/>
Note: It is possible that some coefficients will be replaced by
zeroes, i.e., some terms from the original polynomial may disappear in
the result.
<par/>
The similar function <ttref>randomize</ttref> performs the same operation,
but returns NULL and modifies the argument.
<par/>
NB: every time you restart CoCoA the sequence of random numbers will
be the same (as in other programming languages).  If you want total
randomness read <ttref>seed</ttref>.

<example>
  Use R ::= QQ[x];
  F := 1 + x + x^2;
  Randomized(F);
-2917104644x^2 + 3623608766x - 2302822308
-------------------------------
  F;
x^2 + x + 1
-------------------------------
  Randomized(23);
-3997312402
-------------------------------
  Use R ::= ZZ/(7)[x,y];
  Randomized(x^2 + 3x - 5);
3x^2 + 2x - 2
-------------------------------
</example>
    </description>

    <syntax>
Randomized(F:POLY or INT):POLY or INT

where V is a variable containing a polynomial.
</syntax>

    <seealso>
      <see>random</see>
      <see>randomize</see>
      <see>seed</see>
    </seealso>

    <types>
      <type>polynomial</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>rank</title>
    <short_description>rank of a module</short_description>

    <description>
This function computes the rank of M.  For a module M this is defined
as the vector space dimension of the subspace generated by the generators
of M over the quotient field of the base ring -- contrast this with the
function <ttref>NumCompts</ttref> which simply counts the number of
components the module has.

<example>
  Use R ::= QQ[x,y,z];
  Rank(Module([x,y,z,0])); --***OBSOLETE MANUAL: WORK IN PROGRESS***
1
-------------------------------
  Rank(Module([[1,2,3],[2,4,6]]));   --***OBSOLETE MANUAL: WORK IN PROGRESS***
1
-------------------------------
  Rank(Module([[1,2,3],[2,5,6]]));   --***OBSOLETE MANUAL: WORK IN PROGRESS***
2
-------------------------------
</example>
    </description>

    <syntax>
rank(M:MODULE):INT
rank(M:MAT):INT
</syntax>

    <types>
      <type>module</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>RatReconstructByContFrac, RatReconstructByLattice</title>
    <short_description>rational reconstruction from modular image</short_description>

    <description>
These functions attempt to reconstruct rational numbers from a modular image
X mod M.  The algorithms are fault-tolerant: they will succeed provided that
X is correct modulo a sufficiently large factor of M.

The result is a record: if the algorithm finds a "convincing" result then
the field IsConvincing will be true, and the field ReconstructedRat contains
the value found; otherwise the record contains only the field IsConvincing whose
value will be false.

The two functions use different heuristic algorithms.  Both functions accept
an optional third argument which determines what "convincing" means: a higher
value gives a more reliable answer, but may need a larger modulus before
the answer is found.

<example>
  X := 3333333333;
  M := 10^10;
  RatReconstructByContFrac(X,M);
Record[IsConvincing := true, ReconstructedRat := -1/3]
-------------------------------
  X := 3141592654;
  M := 10^10;
  RatReconstructByContFrac(X,M);
Record[IsConvincing := false]
-------------------------------
</example>
    </description>

    <syntax>
RatReconstructByContFrac(X:INT,M:INT): RECORD[IsConvincing:BOOL, ReconstructedRat:RAT]
RatReconstructByContFrac(X:INT,M:INT,Threshold:INT): RECORD[IsConvincing:BOOL, ReconstructedRat:RAT]
RatReconstructByLattice(X:INT,M:INT): RECORD[IsConvincing:BOOL, ReconstructedRat:RAT]
RatReconstructByLattice(X:INT,M:INT,Threshold:INT): RECORD[IsConvincing:BOOL, ReconstructedRat:RAT]
</syntax>

    <seealso>
      <see>CRT</see>
    </seealso>

    <types>
      <type>INT</type>
      <type>RAT</type>
    </types>

    <keys>
    <key>rational reconstruction</key>
    <key>fault-tolerant</key>
    </keys>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>RatReconstructWithBounds</title>
    <short_description>deterministic rational reconstruction from modular image</short_description>

    <description>
This function attempts to reconstruct a rational number from a collection
of residue-modulus pairs (res[i],mod[i]).  The function also requires the
input of three bounds: "e" is an upper bound on the number of bad moduli,
and P and Q are upper bounds for the numerator and denominator respectively
of the rational to be reconstructed.

If a suitable rational exists, it will be found and returned.  If none
exists then the function returns the string "FAILURE".

<example>
  mod := [11,13,15,17,19];
  res := [-2, -5, 0, 7, 4];
  RatReconstructWithBounds(1,10,10,res,mod);
1/5
-------------------------------
  RatReconstructWithBounds(0,10,10,res,mod);
FAILURE
-------------------------------
</example>
    </description>

    <syntax>
RatReconstructWithBounds(e:INT, P:INT, Q:INT, res:LIST of INT, mod:LIST of INT): RAT or STRING
</syntax>

    <seealso>
      <see>CRT</see>
      <see>RatReconstructByContFrac</see>
    </seealso>

    <types>
      <type>INT</type>
      <type>RAT</type>
    </types>

    <keys>
    <key>rational reconstruction</key>
    <key>fault-tolerant</key>
    </keys>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>RealRootRefine</title>
    <short_description>refine a real root of a univariate polynomial</short_description>

    <description>
This function computes a refinement of a real root of a univariate
polynomial over QQ to the desired precision (width of isolating
interval).  The starting root must be a record produced by <ttref>RealRoots</ttref>.

<example>
/**/  RR := RealRoots(x^2-2);
/**/  RealRootRefine(RR[1], 1/2);
Record[CoeffList := [-1, 0, 2], inf := -3/2, sup := -5/4]

/**/  RR := [RealRootRefine(Root, 10^(-20)) | Root In RR];
/**/  FloatStr(RR[1].inf);
-1.414213562*10^0
</example>
    </description>

    <syntax>
RealRootRefine(Root:RECORD, Precision:RAT):RECORD
</syntax>

    <seealso>
      <see>RealRoots</see>
      <see>RealRootsApprox</see>
      <see>RootBound</see>
    </seealso>

    <types>
      <type>polynomial</type>
    </types>

    <keys>
    <key>scientific notation</key>
    <key>printing rational numbers</key>
    </keys>

  </command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>RealRoots</title>
  <short_description>computes the real roots of a univariate polynomial</short_description>

<syntax>
RealRoots(F:POLY):LIST
RealRoots(F:POLY, Precision:RAT):LIST
RealRoots(F:POLY, Precision:RAT, Interval:[RAT, RAT]):LIST
</syntax>
<description>
This function computes isolating intervals for the real roots of a
univariate polyomial over QQ.
It returns the list of the real roots, where a root is represented as
a record containing either the exact root (if the fields <tt>inf</tt>
and <tt>sup</tt> are equal), or an open interval (inf, sup) containing
the root.
A third field (called CoeffList) has an obscure meaning.
<par/>
An optional second argument specifies the maximum width an isolating
interval may have.  An optional third argument specifies a closed
interval in which to search for roots.
<par/>
The interval represented by a root record may be refined by using the
function <ttref>RealRootRefine</ttref>.
The function <ttref>RealRootsApprox</ttref> may be more useful to you:
it produces rational approximations to the real roots (but these
cannot later be refined).
<example>
/**/  indent(RealRoots(x^2-2));
[
  Record[CoeffList := [-1, 0, 2], inf := -4, sup := 0],
  Record[CoeffList := [1, 0, -2], inf := 0, sup := 4]
]

/**/  RR := RealRoots((x^2-2)*(x-1), 10^(-5));
/**/  FloatStr(RR[1].inf);  -- left end of interval
-1.414213562*10^0

/**/  FloatStr(RR[1].sup);  -- right end of interval
-1.414213561*10^0

/**/  RR := RealRoots(x^2-2, 10^(-20), [0, 2]);

/**/  RR[1].inf;                -- incomprehensible
60153992292001127886258443119406264231/42535295865117307932921825928971026432
/**/  FloatStr(RR[1].inf, 20);  -- comprehensible
1.4142135623730950488*10^0
</example>
</description>

<seealso>
  <see>RealRootRefine</see>
  <see>RealRootsApprox</see>
  <see>RootBound</see>
</seealso>

<types>
  <type>polynomial</type>
</types>

<keys>
  <key>abbott</key>
  <key>solve</key>
  <key>solutions</key>
</keys>
</command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>RealRootsApprox</title>
    <short_description>computes approximations to the real roots of a univariate polynomial</short_description>

    <description>
This function computes rational approximations to the real roots of a
univariate polyomial (with rational coefficients).
<par/>
An optional second argument specifies the maximum separation between
the approximations produced and the corresponding exact root.  An
optional third argument specifies a closed interval in which to search
for roots.

<example>
/**/  RealRootsApprox(x^2-2);
[-3037000499/2147483648, 3037000499/2147483648]

/**/  RR := RealRootsApprox(x^2-2, 10^(-15), [0, 2]);
/**/  RR;
[6521908912666391107/4611686018427387904]

/**/  FloatStr(RR[1], 15);
1.41421356237310*10^0
</example>
    </description>

    <syntax>
RealRootsApprox(F:POLY):LIST
RealRootsApprox(F:POLY, Precision:RAT):LIST
RealRootsApprox(F:POLY, Precision:RAT, Interval:[RAT, RAT]):LIST
</syntax>

    <seealso>
      <see>RealRoots</see>
      <see>RootBound</see>
    </seealso>

    <types>
      <type>polynomial</type>
    </types>

    <keys>
    <key>abbott</key>
    <key>solve</key>
    <key>solutions</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>record</title>
    <short_description>create a record</short_description>

    <syntax>
record[F_1 := OBJECT,...,F_n := OBJECT]

where each F_i is a field name.
</syntax>

    <description>
This constructor creates a record with fields called <tt>F_1</tt>,...,<tt>F_n</tt>.  The
empty record is given by <tt>record[]</tt>.  Records in CoCoA are <em>open</em> in the
sense that new fields may be added after the record is first defined.  The names allowed
for the fields are the same as those allowed for variables.
<par/>
The dot operator is used to access the fields in a record.
<par/>

<example>
/**/  P := Record[height := 10, width := 5];
/**/  P.height * P.width;
50

/**/  P.area := It;  --> creates a new field called "area"
/**/  P;
Record[area := 50, height := 10, width := 5]
</example>
    </description>

    <seealso>
      <see>fields</see>
      <see>operators</see>
    </seealso>

    <types>
      <type>record</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>ReducedGBasis</title>
    <short_description>compute reduced Groebner basis</short_description>

    <description>
If M is an ideal or module, this function returns a list whose
components form a reduced Groebner basis for M with respect to the
term-ordering of the polynomial ring of M.  If M is a quotient of a
ring by an ideal I or of a free module by a submodule N, then the
Groebner basis for M is defined to be that of I or N, respectively.

<example>
/**/  Use R ::= QQ[t,x,y,z];
/**/  I := ideal(t^3-x, t^4-y, t^5-z);
                             --***OBSOLETE MANUAL: WORK IN PROGRESS***
  $gb.Start_GBasis(I);  -- start the Interactive Groebner Framework
  $gb.Steps(I,1);  -- take one step towards computing the Groebner basis
  I.GBasis;  -- the Groebner basis so far
[t^3 - x]

  $gb.Complete(I);-- finish the computation
  I.GBasis;
[t^3 - x, -tx + y, -ty + z, -y^2 + xz, -x^2 + tz, t^2z - xy]

/**/  ReducedGBasis(I);
[y^2 -x*z, t*y -z, x^2 -t*z, t*x -y, t^2*z -x*y, t^3 -x]
</example>
    </description>

    <syntax>
ReducedGBasis(M:IDEAL, MODULE, or TAGGED("Quotient")):LIST
</syntax>

    <seealso>
      <see>Introduction to Groebner Bases in CoCoA</see>
      <see>The Interactive Groebner Framework</see>
    </seealso>

    <types>
      <type>groebner</type>
      <type>groebner-interactive</type>
      <type>ideal</type>
      <type>module</type>
      <type>quotient</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>ref</title>
    <short_description>passing function parameters by reference</short_description>

    <syntax>
ref X

where X is the identifier of a CoCoA variable.
</syntax>

    <description>
The keyword <tt>ref</tt> is used to pass a parameter "by reference" to a
function which may modify its value (<i>e.g.</i> <ttref>append</ttref>).
The keyword <tt>ref</tt> alerts the programmer to the possibility that the
value may be changed during the call.
<par/>
To write a new function which can modify some parameters use the same
keyword <tt>ref</tt> to identify which formal parameters are to be passed
by reference.  The following example illustrates the difference between
passing by reference and passing by value.

<example>
/**/ Define CallByRef(ref L)  -- "call by reference": The variable referred
/**/   L := "new value";       -- to by L is changed.
/**/ EndDefine;
/**/ M := "old value";
/**/ CallByRef(ref M);  -- here "ref" recalls that M might change
/**/ PrintLn M;
new value

/**/ Define CallByVal(L)  -- "call by value": The value of L is passed to
/**/   L := "new value";  -- the function.
/**/   Return L;
/**/ EndDefine;
/**/ L := "old value";
/**/ CallByVal(L);
new value

/**/  PrintLn L;
old value
</example>
    </description>

    <seealso>
      <see>define</see>
    </seealso>

    <types>
      <type>function</type>
      <type>string</type>
    </types>

    <keys>
      <key>var</key>
      <key>reference</key>
      <key>pointer</key>
    </keys>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>RefineGCDFreeBasis</title>
    <short_description>refine an integer GCD free basis</short_description>

    <description>
This function computes a refined GCD free basis by adjoining a given
integer to it.  The value returned is [NewB, N2] where NewB is the
refined basis and N2 is the part of N coprime to every element of B.

<example>
/**/  B := GCDFreeBasis([Fact(10), binomial(20,10)]);  B;
[14175, 4, 46189]

/**/  RefineGCDFreeBasis(B, 15);
[[7, 3, 5, 4, 46189], 1]
</example>
    </description>

    <syntax>
RefineGCDFreeBasis(B:LIST of INT, N:INT):LIST of INT

</syntax>

    <seealso>
      <see>GCDFreeBasis</see>
    </seealso>

    <types>
      <type>int</type>
    </types>

    <keys>
    <key>greatest common divisor</key>
    </keys>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>Reg, Reg5</title>
    <short_description>Castelnuovo-Mumford regularity of a module</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
These functions computes the Castelnuovo-Mumford regularity of a module.
The implementation of <tt>Reg</tt> is just implementation of the
definition (i.e. computes the resolution).
The implementation of <tt>Reg5</tt> implements Bermejo-Gimenez
Algorithm and uses functions from the CoCoAServer (linked with the
Frobby library).  This algorithm has a chance when the computation of the
resolution is unfeasable.

<par/>
Note: this is different from <ttref>RegularityIndex</ttref>, the regularity
of a Hilbert Function.

<example>
  Use R ::= QQ[x,y,z];
  I := ideal(x^3, y^2);
  Res(I);
0 --&gt; R(-5) --&gt; R(-2)(+)R(-3)
-------------------------------
  BettiDiagram(I);
        0    1
---------------
 2:     1    -
 3:     1    -
 4:     -    1
---------------
Tot:    2    1
-------------------------------
  Reg(I);
4
-------------------------------
  Reg(R/I);
3
-------------------------------
  Reg5(I);
4
-------------------------------
</example>
    </description>

    <syntax>
Reg(M:Ideal or TAGGED("Quotient")):INT
</syntax>

    <seealso>
      <see>res</see>
      <see>BettiDiagram</see>
      <see>BettiMatrix</see>
      <see>RegularityIndex</see>
    </seealso>

    <types>
      <type>module</type>
      <type>ideal</type>
    </types>

    <keys>
    <key>castelnuovo-mumford regularity</key>
    <key>castelnuovomumford regularity</key>
    </keys>

  </command>

<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>RegularityIndex</title>
    <short_description>regularity index of a Hilbert function or series</short_description>

    <description>
This function computes the regularity index of a Hilbert function.
The input might be expressed as a Hilbert function or as the
corresponding Hilbert series (computed with standard weights).

<example>
/**/  Use R ::= QQ[x,y,z];
/**/  Quot := R/ideal(x^3, y^2);
/**/  HilbertFn(Quot);
H(0) = 1
H(1) = 3
H(2) = 5
H(t) = 6   for t >= 3
/**/  RegularityIndex(HilbertFn(Quot));
3
/**/  RegularityIndex(HilbertSeries(Quot));
3
</example>
    </description>

    <syntax>
RegularityIndex(R:RING or TAGGED("Quotient")):INT
</syntax>

    <seealso>
      <see>hilbert</see>
      <see>HilbertFn</see>
      <see>HilbertSeries</see>
      <see>poincare</see>
    </seealso>

    <types>
      <type>hilbert</type>
    </types>

  </command>

<!-- ===  COMMAND  =============================================== -->
<command>
  <title>RelNotes</title>
  <short_description>print the release notes</short_description>

<syntax>
RelNotes()
</syntax>
<description>
This function prints the release notes of the version you are running.
<example>
  RelNotes();
</example>
</description>

<keys>
  <key>release notes</key>
  <key>rel notes</key>
</keys>
</command>

<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>ReloadMan</title>
    <short_description>Reload CoCoAManual/CoCoAHelp.xml</short_description>

    <description>
This function reloads the xml source of the manual <tt>CoCoAHelp.xml</tt>
(in directory <tt>CoCoAManual</tt>) and recreates the internal manual
index in a running CoCoA-5.
<par/>
It is necessary when a substantial change has been made
to <tt>CoCoAHelp.xml</tt> (such as a new entry been added) and the
index needs updating.
If the change is in the description of an existing entry (so the
internal index is still valid) there is no need to reload the manual:
the description is always searched in the current file.

<example>
  ReloadMan();
</example>
    </description>

    <syntax>
ReloadMan()
</syntax>

    <keys>
      <key>reload manual</key>
    </keys>
  </command>

<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>remove</title>
    <short_description>remove an object in a list</short_description>

    <syntax>
remove(ref L:LIST, N:INT):NULL

where L is a variable containing a list.
</syntax>

    <description>
This function removes the <tt>N</tt>-th component from <tt>L</tt>; it changes the value of <tt>L</tt>.
Use the function <ttref>WithoutNth</ttref> to create a new list containing the
elements of <tt>L</tt> except the <tt>N</tt>-th (without changing <tt>L</tt>).

<example>
/**/  Use R ::= QQ[x,y,z];
/**/  L := indets(R);
/**/  L;
[x, y, z]

/**/  remove(ref L,2);
/**/  L;
[x, z]
</example>
    </description>

    <seealso>
      <see>insert</see>
      <see>WithoutNth</see>
    </seealso>

    <types>
      <type>list</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>repeat</title>
    <short_description>loop command</short_description>

    <description>
In the first form, the command sequence C is repeated until B
evaluates to False.  Unlike the <tt>While</tt> command, C is executed at
least once.  Note that there is no <tt>EndRepeat</tt> following B.  In the
second form, ending with <tt>EndRepeat</tt> is obsolescent from version 4.7.5,
and can be trivially substituted with <tt>While True Do ...... EndWhile</tt>

<example>
      Define GCD_Euclid(A, B)
        Repeat
          R := mod(A, B);
          A := B;
          B := R;
         Until B = 0;
        Return A;
      EndDefine;
/**/  GCD_Euclid(6,15);
3

/**/  N := 0;
/**/  While true do 
        N := N+1;
        PrintLn N;
        If N = 5 Then Break; EndIf;
      EndWhile;
1
2
3
4
5
</example>
    </description>

    <syntax>
Repeat C Until B

where C is a sequence of commands and B is a boolean expression.
</syntax>

    <seealso>
      <see>for</see>
      <see>foreach</see>
      <see>while</see>
    </seealso>

    <types>
      <type>command</type>
      <type>programming</type>
      <type>loops</type>
    </types>

    <keys>
    <key>until</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>res</title>
    <short_description>free resolution</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This function returns the minimal free resolution of M.  If M is a
quotient of a ring by an ideal I or a quotient of a free
module by a submodule N, then the resolution of M is defined
to be that of I or N, respectively.
<par/>
<tt>res</tt> only works in the homogeneous context, and the coefficient ring
must be a field.

<example>
  Use R ::= QQ[x,y,z];
  I := ideal(x, y, z^2);
  Res(R/I);
0 --&gt; R(-4) --&gt; R(-2)(+)R(-3)^2 --&gt; R(-1)^2(+)R(-2) --&gt; R
-------------------------------
  Describe It;

mat([
  [y, x, z^2]
])
mat([
  [x, z^2, 0],
  [-y, 0, z^2],
  [0, -y, -x]
])
mat([
  [z^2],
  [-x],
  [y]
])
-------------------------------
</example>

For fine control and monitoring of Groebner basis calculations,
including various types of truncations, see <ref>The Interactive Groebner
Framework</ref> and <ref>Introduction to Panels</ref>.
    </description>

    <syntax>
Res(M):TAGGED("$gb.Res")

where M is of type IDEAL or MODULE or TAGGED("Quotient").
</syntax>

    <seealso>
      <see>BettiDiagram</see>
      <see>BettiMatrix</see>
      <see>Example: Interactive Resolution Computation</see>
      <see>Example: Truncations</see>
      <see>Introduction to Groebner Bases in CoCoA</see>
    </seealso>

    <types>
      <type>groebner</type>
      <type>groebner-basic</type>
      <type>ideal</type>
      <type>module</type>
      <type>quotient</type>
    </types>

    <keys>
    <key>resolutions</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>Reset</title>
    <short_description>reset panels and random number seed to defaults</short_description>

    <description>
<em>***OBSOLETE***</em>
This function resets the options in the CoCoA panels to their default
values and executes <tt>Seed(0)</tt>.

<example>
  Set Indentation;
  Panel(GENERAL);

Echo............... : False
Timer.............. : False
Trace.............. : False
Indentation........ : True
TraceSources....... : False
SuppressWarnings... : False
ComputationStack... : False
-------------------------------
  Reset();
  Panel(GENERAL);

Echo............... : False
Timer.............. : False
Trace.............. : False
Indentation........ : False
TraceSources....... : False
SuppressWarnings... : False
ComputationStack... : False
-------------------------------
</example>
    </description>

    <syntax>
Reset():NULL
</syntax>

    <seealso>
      <see>Introduction to Panels</see>
      <see>ResetPanels</see>
      <see>seed</see>
    </seealso>

    <types>
      <type>panels</type>
      <type>system</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>ResetPanels</title>
    <short_description>reset panels to their default values</short_description>

    <description>
<em>***OBSOLETE***</em>
This function resets the options in the CoCoA panels to their default
values.

<example>
  Set Indentation;
  Panel(GENERAL);

Echo............... : False
Timer.............. : False
Trace.............. : False
Indentation........ : True
TraceSources....... : False
SuppressWarnings... : False
ComputationStack... : False
-------------------------------
  ResetPanels();
  Panel(GENERAL);

Echo............... : False
Timer.............. : False
Trace.............. : False
Indentation........ : False
TraceSources....... : False
SuppressWarnings... : False
ComputationStack... : False
-------------------------------
</example>
    </description>

    <syntax>
ResetPanels():NULL
</syntax>

    <seealso>
      <see>Introduction to Panels</see>
      <see>Reset</see>
    </seealso>

    <types>
      <type>panels</type>
      <type>system</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>resultant</title>
    <short_description>the resultant of two polynomials</short_description>

    <description>
This function returns the resultant of the polynomials F and G with
respect to the indeterminate X.

<example>
/**/  Use R ::= QQ[p,q,x];
/**/  F := x^3+p*x-q;   G := Der(F, x);
/**/  resultant(F, G, x);
4*p^3 +27*q^2
</example>
    </description>

    <syntax>
resultant(F:POLY, G:POLY, X:INDET):POLY
</syntax>

    <seealso>
      <see>discriminant</see>
      <see>sylvester</see>
    </seealso>

    <types>
      <type>polynomial</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>return</title>
  <short_description>exit from a function</short_description>
  
<syntax>
return
return E
</syntax>
<description>
This command is used to exit from a procedure/function.
The latter form returns the value of the expression E to the user.
As a safety measure all <tt>return</tt>s in a function/procedure must
be of the same kind: either they all return a value (function) or none
returns a value (procedure).
To exit from a loop see <ttref>break</ttref>.

<example>
  Define Rev(L) -- reverse a list
    If len(L) &lt; 2 Then Return L; EndIf;
    M := Rev(Tail(L)); -- recursive function call
    append(ref M, L[1]);
    Return M;
  EndDefine;

/**/  Rev([1,2,3,4]);
[4, 3, 2, 1]

  -- mixing function/procedure returns is not allowed
  Define AFailingExample(X)
    If X=1 Then Return 123456;
    Else Return; -- .....
 ERROR: Inside a function definition all Return statements must be
  either with or without an expression
    Else Return;
         ^^^^^^^
</example>
</description>

<seealso>
  <see>break</see>
  <see>define</see>
</seealso>

<types>
  <type>command</type>
  <type>function</type>
  <type>loops</type>
</types>

</command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>reverse, reversed</title>
    <short_description>reverse a list</short_description>

    <description>
The the function <tt>reverse</tt> reverses the order of the elements of the
list in V, returning Null.  It does <em>not</em> return the reversed list,
but instead changes L itself.  The function <tt>reversed</tt> returns the
reversed list without changing L.

<example>
/**/  L := [1,2,3,4];
/**/  reverse(ref L);
/**/  L;  -- L has been modified
[4, 3, 2, 1]

/**/  M := [1,2,3,4];
/**/  reversed(M);  -- the reversed list is returned
[4, 3, 2, 1]

/**/  M;  -- M has not been modified
[1, 2, 3, 4]
</example>
    </description>

    <syntax>
reverse(ref V:LIST):NULL
reversed(L:LIST):NULL

where V is a variable containing a list in the first case.
</syntax>

    <seealso>
      <see>sort</see>
      <see>sorted</see>
    </seealso>

    <types>
      <type>list</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>RevLexMat</title>
    <short_description>matrices for std. term-orderings</short_description>

    <description>
This function return the matrix defining a standard ordering (which is
not a term-ordering!).

<example>
/**/  RevLexMat(3);
matrix([
  [0, 0, -1],
  [0, -1, 0],
  [-1, 0, 0]
])
</example>
    </description>

    <syntax>
RevLexMat(N:INTEGER):MAT
</syntax>

    <seealso>
      <see>OrdMat</see>
      <see>Orderings</see>
      <see>StdDegRevLexMat</see>
      <see>StdDegLexMat</see>
      <see>LexMat</see>
      <see>XelMat</see>
    </seealso>

    <types>
      <type>matrix</type>
    </types>

  </command>
<!-- ===  COMMAND-rm Ring =============================================== -->
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>RingElem</title>
    <short_description>convert an expression into a RINGELEM</short_description>

    <syntax>
RingElem(R:RING, E:RINGELEM): RINGELEM
RingElem(R:RING, E:INT): RINGELEM
RingElem(R:RING, E:RAT): RINGELEM
RingElem(R:RING, E:STRING): RINGELEM
RingElem(R:RING, E:[STRING, INT, .., INT]): RINGELEM
</syntax>
    <description>
This function converts the expression E into a RINGELEM in R, if possible.
<par/>
Can be used for mapping ring element between rings when
a <ttref>CanonicalHom</ttref> exists.  For other homomorphisms
search see <ttref>RINGHOM</ttref>.

<example>
/**/  Use P ::= QQ[x,y,z];
/**/  -- RINGELEM (via CanonicalHom)
/**/  F := 2*x-3;
/**/  F/LC(F); -- !!! ERROR !!!  LC(F) in CoeffRing(P)
/**/  F/RingElem(P,LC(F));
x +1
/**/  1/x; -- !!! ERROR !!!  x in P is not invertible
/**/  K := NewFractionField(P);
/**/  1/RingElem(K, x); -- x in K is invertible
1/x

/**/  Use P ::= ZZ/(5)[x,y,z];
/**/  -- INT and RAT
/**/  RingElem(P, 7);
2
/**/  RingElem(P, 3/2);
-1

/**/  -- STRING (indet name, symbol)
/**/  S ::= QQ[x,y,z[1..4,3..7]];
/**/  7*RingElem(P, "x");  --> x as an element of P
2*x
/**/  7*RingElem(S, "x");  --> x as an element of S
7*x
/**/  7*RingElem(S, ["z",2,5]);
7*z[2,5]
</example>
    </description>

    <seealso>
      <see>RingOf</see>
      <see>AsINT</see>
      <see>AsRAT</see>
      <see>IndetName</see>
      <see>IndetSubscripts</see>
      <see>CanonicalHom</see>
    </seealso>

    <types>
      <type>ring</type>
      <type>RINGELEM</type>
    </types>

    <keys>
      <key>cast</key>
      <key>convert</key>
    </keys>

  </command>
<!-- ===  COMMAND-rm RingEnvs =============================================== -->
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>RingOf</title>
    <short_description>the ring of the object</short_description>

    <description>
This function returns the ring on which the object E is defined.
<par/>
NB A ring contains many information and two separate rings, even when
defined with the same commands, are not <quotes>equal</quotes>.
When a ring is printed only a few informations are shown, so different
rings might look the same.

<example>
/**/  Use R ::= QQ[x,y,z];
/**/  I := ideal(x,y);  
/**/  RingOf(I);
RingDistrMPolyClean(QQ, 3)

/**/  RingOf(mat([[1,2],[3,4]]));
ZZ

/**/  Use Qabc ::= QQ[a,b,c];
/**/  F := a^2+b;
/**/  G := a*b+b^2;
/**/  Use S ::=ZZ/(3)[x,y];
/**/  RingOf(F+G);  -- F+G is computed in the ring of definition
RingDistrMPolyClean(QQ, 3)
/**/  indets(RingOf(F));
[a, b, c]
</example>
    </description>

    <syntax>
RingOf(E:RINGELEM, IDEAL, MATRIX, MODULE):RING
</syntax>

    <seealso>
      <see>CurrentRing</see>
      <see>RingSet</see>
      <see>BaseRing</see>
    </seealso>

    <types>
      <type>ring</type>
      <type>ringelem</type>
      <type>matrix</type>
      <type>ideal</type>
      <type>module</type>
      <type>moduleelem</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>RingQQ</title>
  <short_description>the ring of rationals</short_description>
 
<syntax>
RingQQ():RING
</syntax>
<description>
This function returns the ring of rationals.
It is particularly useful when you want to use <tt>QQ</tt>
(which is a pre-defined top-level variable) inside a function.
<par/>
NB calling <tt>RingQQ</tt> twice gives the same identical ring,
whereas calling <ttref>NewPolyRing</ttref> or
<ttref>NewFractionField</ttref> return each time a new ring.
<example>
/**/  Two := RingElem(RingQQ(), 2);   Two;
2
/**/  type(Two);
RINGELEM;
/**/  RingOf(Two) = RingQQ();
true
</example>
</description>

<types>
  <type>ring</type>
</types>
<keys>
  <key>ring of rationals</key>
</keys>
<seealso>
  <see>TopLevel</see>
  <see>RingQQt</see>
  <see>RingZZ</see>
</seealso>
</command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>RingQQt</title>
  <short_description>pre-defined polynomial rings</short_description>
 
<syntax>
RingQQt(N: INT): RING
</syntax>

<description>
This function returns a polynomial ring over <tt>QQ</tt> with indeterminates <formula>t[1]...t[N]</formula>.
In particular <tt>RingQQt(1)</tt> is the polynomial ring in which Hilbert polynomials
are defined.
<par/>
NB calling <tt>RingQQt(5)</tt> twice gives the same identical ring,
whereas calling <ttref>NewPolyRing(RingQQ(), SymbolRange("t", 5))</ttref>
returns each time a new ring (therefore incompatible).
<example>
/**/  QQt := RingQQt(3);  Use QQt;
/**/  (t[1]+1)^3;
t[1]^3 +3*t[1]^2 +3*t[1] +1
/**/  indets(RingQQt(1));
[t]
/**/  indets(RingQQt(5));
[t[1], t[2], t[3], t[4], t[5]]
</example>
</description>

<types>
  <type>ring</type>
  <type>polyring</type>
</types>
<keys>
  <key>ring of polynomials</key>
</keys>
<seealso>
  <see>TopLevel</see>
  <see>RingQQ</see>
  <see>RingZZ</see>
</seealso>
</command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>RingSet</title>
    <short_description>list of the rings of an object</short_description>

    <description>
This function returns the list of the RINGs (or types, if not
dependent from a RING) on which the object E is dependent.
Similar to <ttref>RingOf</ttref>, this function also works on lists
and returns the set of ring environments of all entries.
...needless to say that it may be quite slow on big inputs!

<example>
/**/  Use R ::= QQ[x,y,z];
/**/  L1 := [x, y];
/**/  L2 := [x, y, 0, 5/4];
/**/  Z3 := NewRingFp(3);
/**/  Use S ::= Z3[a,b];
/**/  RingSet(L1);
[RingDistrMPolyClean(QQ, 3)]

/**/  RingSet(L2);
[RingDistrMPolyClean(QQ, 3), INT, RAT]

/**/  RingSet([L2, a+b]);
[RingDistrMPolyClean(QQ, 3), INT, RAT, RingDistrMPolyClean(FFp(3), 2)]
</example>
    </description>

    <syntax>
RingSet(E:LIST, RINGELEM, IDEAL, MATRIX, MODULE, MODULEELEM):LIST of RING and TYPE
</syntax>

    <seealso>
      <see>CurrentRing</see>
      <see>RingOf</see>
    </seealso>

    <types>
      <type>ring</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>RingZZ</title>
  <short_description>the ring of integers</short_description>
 
<syntax>
RingZZ(): RING
</syntax>
<description>
This function returns the ring of integers.
It is particularly useful when you want to use <tt>ZZ</tt>
(which is a pre-defined top-level variable) inside a function.
<par/>
NB calling <tt>RingZZ</tt> twice gives the same identical ring,
whereas calling <ttref>NewPolyRing</ttref> or
<ttref>NewFractionField</ttref> return each time a new ring.
<example>
/**/  Two := RingElem(RingZZ(), 2);   Two;
2
/**/  type(Two);
RINGELEM;
/**/  RingOf(Two) = RingZZ();
true
/**/  RingOf(Two) = RingQQ();
false
</example>
</description>

<types>
  <type>ring</type>
</types>
<keys>
  <key>ring of integers</key>
</keys>
<seealso>
  <see>TopLevel</see>
  <see>RingQQt</see>
  <see>RingQQ</see>
</seealso>
</command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>RMap</title>
    <short_description>define ring homomorphism</short_description>

    <description>
See <ttref>image</ttref>.
    </description>

    <syntax>
RMap(L:LIST)):TAGGED("RMap")
</syntax>

    <seealso>
      <see>Accessing Other Rings</see>
      <see>BringIn</see>
      <see>image</see>
      <see>QZP</see>
      <see>ZPQ</see>
      <see>Ring Mappings: the Image Function</see>
      <see>subst</see>
    </seealso>

    <types>
      <type>ring</type>
    </types>

    <keys>
    <key>ring homomorphism</key>
    <key>ringmap</key>
    <key>ring map</key>
    <key>change ring</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>RootBound</title>
  <short_description>bound on roots of a polynomial over QQ</short_description>

<syntax>
RootBound(F:POLY):INT
</syntax>
<description>
This function computes a bound on the absolute values of the complex
roots of a univariate polynomial over QQ.
<example>
/**/  Use R ::= QQ[x,y,z];
/**/  RootBound(x^2-2);
4
</example>
</description>

<seealso>
  <see>RealRootRefine</see>
  <see>RealRoots</see>
</seealso>

<types>
  <type>polynomial</type>
</types>

</command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>round</title>
  <short_description>round to integer</short_description>

<syntax>
round(X:RAT):INT
</syntax>

<description>
This function rounds a rational to the nearest integer; halves are rounded towards zero.
<example>
/**/  round(4.56);
5

/**/  round(-1/2);
0
</example>
</description>

<seealso>
  <see>num</see>
  <see>den</see>
  <see>floor</see>
  <see>ceil</see>
</seealso>

<types>
  <type>RAT</type>
  <type>INT</type>
</types>

<keys>
  <key>rounding</key>
</keys>
</command>

<!-- ===  COMMAND  =============================================== -->
<command>
  <title>RowMat</title>
  <short_description>single row matrix</short_description>

<syntax>
RowMat(L:LIST):MAT
RowMat(R:RING, L:LIST):MAT
</syntax>
<description>
This function return the matrix whose only row consists of the
elements of the list L.
<example>
/**/  RowMat([3,4,5]);
matrix([
  [3, 4, 5]
])

/**/  RowMat(QQ,[5,6,7]);
matrix([
  [5, 6, 7]
])
</example>
</description>

<seealso>
  <see>BlockMat</see>
  <see>DiagMat</see>
  <see>ColMat</see>
</seealso>

<types>
  <type>matrix</type>
</types>

<keys>
  <key>row matrix</key>
</keys>
</command>

</chapter_letter>
<!-- ===  CHAPTER  =============================================== -->
<chapter_letter>
  <title>S</title>

<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>saturate</title>
    <short_description>saturation of ideals</short_description>

    <description>
This function returns the saturation of I with respect to J: the
ideal of polynomials F such that F*G is in I for all G in <formula>J^d</formula>
for some positive integer d.
<par/>
The coefficient ring must be a field.

<example>
/**/  Use R ::= QQ[x,y,z];
/**/  I := ideal(x-z, y-2*z);
/**/  J := ideal(x-2*z, y-z);
/**/  K := intersection(I, J); -- ideal of two points in the
                               -- projective plane
/**/  L := intersection(K, ideal(x,y,z)^3); -- add an irrelevant component
/**/  Hilbert(R/L);
H(0) = 1
H(1) = 3
H(2) = 6
H(t) = 2   for t &gt;= 3

/**/  saturate(L, ideal(x,y,z)) = K; -- saturating gets rid of the
                                     -- irrelevant component
true
</example>
    </description>

    <syntax>
saturate(I:IDEAL, J:IDEAL):IDEAL
</syntax>

    <seealso>
      <see>colon</see>
      <see>HColon</see>
      <see>HSaturation</see>
    </seealso>

    <types>
      <type>groebner</type>
      <type>groebner-basic</type>
      <type>ideal</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>ScalarProduct</title>
    <short_description>scalar product</short_description>

    <description>
This function returns the sum of the product of the components of L
and M; precisely (len(L)=len(M)):
<par/>
  ScalarProduct(L, M) = sum([ L[I]*M[I] | I In 1..len(L) ]).
<par/>
The function works whenever the product of the components of L and M
are defined (see <ref>Algebraic Operators</ref>).

<example>
/**/  ScalarProduct([1,2,3], [5,0,-1]);
2

  Use R ::= QQ[x,y];
  ScalarProduct([ideal(x,y), ideal(x^2-xy)],[x^2,y]);
ideal(x^3, x^2y, x^2y - xy^2)
-------------------------------
</example>
    </description>

    <syntax>
ScalarProduct(L, M):OBJECT

where each of L and M is of type MODULEELEM or LIST
</syntax>

    <seealso>
      <see>Algebraic Operators</see>
    </seealso>

    <types>
      <type>list</type>
      <type>moduleelem</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>seed</title>
    <short_description>seed for <tt>random</tt></short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This function seeds the random number generator, <ttref>random</ttref>.
<par/>
NB: every time you restart CoCoA the sequence of random numbers will
be the same (as happens in many programming languages).  If you want better
randomness, see the example below.
<example>
  Seed(5);
  Rand();
1991603592
-------------------------------
  Rand();
-1650270230
-------------------------------
  Seed(5);  -- with the same seed, "Rand" generates the same sequence
  Rand();
1991603592
-------------------------------
  Rand();
-1650270230
-------------------------------
  -- Better randomness:
  -- the following shows how to make a random seed based on the date.
  D := Date();
  D;
Mon Mar 02 14:43:44 1998
-------------------------------
  Seed(Sum(Ascii(D)));
</example>
    </description>

    <syntax>
Seed(N:INT):INT
</syntax>

    <seealso>
      <see>random</see>
    </seealso>

    <types>
      <type>integer</type>
      <type>miscellaneous</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>SeparatorsOfPoints</title>
    <short_description>separators for affine points</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This function computes separators for the points: that is, for each
point a polynomial is determined whose value is 1 at that point and 0
at all the others.  The separators yielded are reduced with respect to
the reduced Groebner basis which would be found by <ttref>IdealOfPoints</ttref>.
<par/>
NOTE:
<par/>
 * the current ring must have at least as many indeterminates as the
   dimension of the space in which the points lie;
<par/>
 * the base field for the space in which the points lie is taken to be
   the coefficient ring, which should be a field;
<par/>
 * in the polynomials returned the first coordinate in the space is
   taken to correspond to the first indeterminate, the second to the
   second, and so on;
<par/>
 * the separators are in the same order as the points (i.e. the first
   separator is the one corresponding the first point, and so on);
<par/>
 * if the number of points is large, say 100 or more, the returned
   value can be very large.  To avoid possible problems when printing
   such values as a single item we recommend printing out the elements
   one at a time as in this example:
<verbatim>
     S := SeparatorsOfPoints(Pts);
     Foreach Element In S Do
       PrintLn Element;
     EndForeach;
</verbatim>
For separators of points in projective space, see
<ttref>SeparatorsOfProjectivePoints</ttref>.

<example>
  Use R ::= QQ[x,y];
  Points := [[1, 2], [3, 4], [5, 6]];
  S := SeparatorsOfPoints(Points);  -- compute the separators
  S;
[1/8y^2 - 5/4y + 3, -1/4y^2 + 2y - 3, 1/8y^2 - 3/4y + 1]
-------------------------------
  [[Eval(F, P) | P In Points] | F In S];  -- verify separators
[[1, 0, 0], [0, 1, 0], [0, 0, 1]]
-------------------------------
</example>
    </description>

    <syntax>
SeparatorsOfPoints(Points:LIST):LIST

where Points is a list of lists of coefficients representing a set of
<em>distinct</em> points in affine space.
</syntax>

    <seealso>
      <see>GenericPoints</see>
      <see>IdealAndSeparatorsOfPoints</see>
      <see>IdealAndSeparatorsOfProjectivePoints</see>
      <see>IdealOfPoints</see>
      <see>IdealOfProjectivePoints</see>
      <see>Interpolate</see>
      <see>SeparatorsOfProjectivePoints</see>
    </seealso>

    <types>
      <type>list</type>
      <type>points</type>
    </types>

    <keys>
    <key>abbott</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>SeparatorsOfProjectivePoints</title>
    <short_description>separators for projective points</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This function computes separators for the points: that is, for each
point a homogeneous polynomial is determined whose value is non-zero at
that point and zero at all the others.  (Actually, choosing the values
listed in Points as representatives for the homogeneous coordinates of
the corresponding points in projective space, the non-zero value will
be 1.)  The separators yielded are reduced with respect to the reduced
Groebner basis which would be found by <ttref>IdealOfProjectivePoints</ttref>.
<par/>
NOTE:
<par/>
 * the current ring must have at least one more indeterminate than the
   dimension of the projective space in which the points lie, i.e, at
   least as many indeterminates as the length of an element of
   the input, Points;
<par/>
 * the base field for the space in which the points lie is taken to be
   the coefficient ring, which should be a field;
<par/>
 * in the polynomials returned the first coordinate in the space is
   taken to correspond to the first indeterminate, the second to the
   second, and so on;
<par/>
 * the separators are in the same order as the points (i.e. the first
   separator is the one corresponding the first point, and so on);
<par/>
 * if the number of points is large, say 100 or more, the returned
   value can be very large.  To avoid possible problems when printing
   such values as a single item we recommend printing out the elements
   one at a time as in this example:
<verbatim>
     S := SeparatorsOfProjectivePoints(Pts);
     Foreach Element In S Do
       PrintLn Element;
     EndForeach;
</verbatim>
For separators of points in affine space, see
<ttref>SeparatorsOfPoints</ttref>.

<example>
  Use R ::= QQ[x,y,z];
  Points := [[0,0,1],[1/2,1,1],[0,1,0]];
  S := SeparatorsOfProjectivePoints(Points);
  S;
[-2x + z, 2x, -2x + y]
-------------------------------
  [[Eval(F, P) | P In Points] | F In S];   -- verify separators
[[1, 0, 0], [0, 1, 0], [0, 0, 1]]
-------------------------------
</example>
    </description>

    <syntax>
SeparatorsOfProjectivePoints(Points:LIST):LIST

where Points is a list of lists of coefficients representing a set of
<em>distinct</em> points in projective space.
</syntax>

    <seealso>
      <see>GenericPoints</see>
      <see>IdealAndSeparatorsOfPoints</see>
      <see>IdealAndSeparatorsOfProjectivePoints</see>
      <see>IdealOfPoints</see>
      <see>IdealOfProjectivePoints</see>
      <see>Interpolate</see>
      <see>SeparatorsOfPoints</see>
    </seealso>

    <types>
      <type>list</type>
      <type>points</type>
    </types>

    <keys>
    <key>abbott</key>
    </keys>
  </command>
<!-- ===  COMMAND-rm Set,Unset ============================================ -->
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>shape</title>
    <short_description>extended list of types involved in an expression</short_description>

    <description>
This function returns the extended list of types involved in the
expression E as outlined below:
<verbatim>
type(E) = LIST
  In this case, Shape(E) is the list whose i-th component is the type
  of  the i-th component of E.

type(E) = MAT
  In this case, Shape(E) is a matrix with (i,j)-th entry equal to the
  type of the (i,j)-th entry of E.

type(E) = RECORD
  In this case, Shape(E) is a record whose fields are the types of the
  fields of E.
</verbatim>
Otherwise, <tt>Shape(E)</tt> is the type of E.

<example>
/**/  Use R ::= QQ[x];
/**/  L := [1,[1,"a"], x^2-x];
/**/  shape(L);
[INT, [INT, STRING], POLY]

/**/  R := Record[name := "test", contents := L];
/**/  shape(R);
Record[contents := [INT, [INT, STRING], POLY], name := STRING]

/**/  It.name;
STRING
</example>

There are undocumented functions, <tt>IsSubShape</tt> and <tt>IsSubShapeOfSome</tt>,
for determining if the <tt>shape</tt> of a CoCoA expression is a <tt>subshape</tt>
of another.  To see the code for these functions, enter
<verbatim>
  Describe Function(<quotes>$misc.IsSubShape</quotes>);
  Describe Function(<quotes>$misc.IsSubShapeOfSome</quotes>);
</verbatim>
    </description>

    <syntax>
shape(E:LIST):LIST (of TYPE)
shape(E:RECORD):RECORD (of TYPE)
shape(E:OTHER):TYPE

where OTHER stands for a type which is not LIST, MAT, or RECORD.
</syntax>

    <seealso>
      <see>Data Types</see>
    </seealso>

    <types>
      <type>type</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>sign</title>
    <short_description>the sign of a number</short_description>

    <description>
This function returns -1 if X &lt; 0, 0 if X = 0, and 1 if X &gt; 0.
X must be INT or RAT.

<example>
/**/  sign(123);
1

/**/  sign(-5/2);
-1
</example>
    </description>

    <syntax>
sign(X:INT of RAT):INT
</syntax>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>SimplestRATBetween</title>
    <short_description>find simplest rational in a closed interval</short_description>

    <description>
This function finds the simplest rational in the closed interval with end points A and B.

<example>
/**/  SimplestRATBetween(0.123, 0.456);
1/3

/**/  SimplestRATBetween(-3.14159, -2.71828);
-3
</example>
    </description>

    <syntax>
SimplestRATBetween(A:RAT, B:RAT):RAT
</syntax>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>size</title>
    <short_description>the amount of memory used by an object</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This function returns the amount of memory used by the object E,
expressed in words (1 word = 4 bytes = 32 bits).

<example>
  Use R ::= QQ[x,y];
  Size(1);
1
-------------------------------
  Size(2^32-1);
1
-------------------------------
  Size(2^32);
2
-------------------------------
  Size(2^64);
3
-------------------------------
  Size(x);
32
-------------------------------
  Size([x,y]);
64
-------------------------------
</example>
    </description>

    <syntax>
Size(E:OBJECT):INT
</syntax>

    <seealso>
      <see>count</see>
      <see>len</see>
    </seealso>

    <types>
      <type>ideal</type>
      <type>integer</type>
      <type>list</type>
      <type>matrix</type>
      <type>memory</type>
      <type>module</type>
      <type>polynomial</type>
      <type>ratfun</type>
      <type>moduleelem</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>skip</title>
    <short_description>does nothing</short_description>

    <description>
This command does nothing.  I suppose it might be used to make the
structure of a user-defined function more clear.  It is probably at
least as useful as the function <tt>Tao</tt>.

<example>
/**/  skip;
</example>
    </description>

    <syntax>
skip
</syntax>

    <types>
      <type>miscellaneous</type>
      <type>programming</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>SmoothFactor</title>
  <short_description>find small prime factors of an integer</short_description>
  
<syntax>
SmoothFactor(N:INT, MaxP:INT): RECORD
</syntax>

<description>
This function finds the small prime factors of an integer.  It simply
tries dividing by all primes up to the given bound <tt>MaxP</tt>.
The result is a list of the prime factors found together with the
unfactored part of <code>N</code>.
Be careful about supplying large values for <tt>MaxP</tt>
(e.g. greater than a million): the function could take a very long
time.
<tt>MaxP</tt> must be positive. 
<par/>
From version 5.0.4 the field are called <tt>factors</tt>
and <tt>multiplicities</tt> instead of  <tt>Factors</tt>
and <tt>Exponents</tt> to comply with the naming conventions.

<example>
/**/  SmoothFactor(100,3);
Record[factors := [2], multiplicities := [2], RemainingFactor := 25]

/**/  SmoothFactor(123456789,3700);
Record[factors := [3, 3607], multiplicities := [2, 1], RemainingFactor := 3803]
</example>
</description>

<seealso>
  <see>IsPrime</see>
  <see>IsProbPrime</see>
</seealso>

<types>
  <type>int</type>
  <type>list</type>
</types>

<keys>
  <key>factor</key>
  <key>factors</key>
  <key>factorise</key>
  <key>factorisation</key>
  <key>factorize</key>
  <key>factorization</key>
  <key>small prime</key>
  <key>partial factorization</key>
</keys>

</command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>sort</title>
    <short_description>sort a list</short_description>

    <description>
This function sorts the elements of the list in V with respect
to the default comparisons related to their types; it overwrites V and
returns NULL.
<par/>
For more on the default comparisons, see <ref>Relational Operators</ref>
in the chapter on operators.
For more complicated sorting, see <ttref>SortBy</ttref>, <ttref>SortedBy</ttref>.

<example>
/**/  L := [3,2,1];
/**/  sort(ref L);  -- this returns nothing and modifies L
/**/  L;
[1, 2, 3]

/**/  Use R ::= QQ[x,y,z];
/**/  L := [x,y,z];
/**/  sort(ref L);  -- this returns nothing and modifies L
/**/  L[1];
z

/**/  sorted([y, x, x^2]);   -- this returns the sorted list
[y, x, x^2]
</example>
    </description>

    <syntax>
sort(V:LIST):NULL

where V is a variable containing a list.
</syntax>

    <seealso>
      <see>Relational Operators</see>
      <see>sorted</see>
      <see>SortBy</see>
      <see>SortedBy</see>
    </seealso>

    <types>
      <type>list</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>SortBy</title>
    <short_description>sort a list</short_description>

    <syntax>
SortBy(L:LIST, CmpFn:FUNCTION):NULL

where <code>L</code> is a variable containing a list and <code>CmpFn</code> is a boolean-valued
comparison function of two arguments (representing <em>less than</em>).
</syntax>

    <description>
This function sorts the elements of the list in <code>L</code> with respect
to the comparisons made by <code>CmpFn</code>; it overwrites <code>L</code> and returns <code>NULL</code>.
<par/>
The comparison function <code>CmpFn</code> takes two arguments and returns <code>True</code> if the
first argument is less than the second, otherwise it returns <code>False</code>.
The sorted list is in increasing order.
<par/>
Note that to call <code>SortBy(L,CmpFn)</code> inside a function you
will need to make the name <code>CmpFn</code> accessible using <code>TopLevel CmpFn;</code>
<par/>
Note that if both <code>CmpFn(A, B)</code> and <code>CmpFn(B, A)</code> return
<code>True</code>, then <code>A</code> and <code>B</code> are viewed as being equal.

<example>
/**/  Define ByLength(S, T)    -- define the sorting function
        Return len(S) &gt; len(T);
      EndDefine;
/**/  M := ["bird","mouse","cat"];
/**/  SortBy(ref M, ByLength);
/**/  M;
["mouse", "bird", "cat"]
</example>
    </description>

    <seealso>
      <see>func</see>
      <see>sort</see>
      <see>sorted</see>
      <see>SortedBy</see>
      <see>TopLevel</see>
    </seealso>

    <types>
      <type>list</type>
      <type>function</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>sorted</title>
    <short_description>sort a list</short_description>

    <description>
This function returns the list of the sorted elements of L without
affecting L, itself.
<par/>
For more on the default comparisons, see <ref>Relational Operators</ref>
in the chapter on operators.
For more complicated sorting, see <ttref>SortBy</ttref>, <ttref>SortedBy</ttref>.

<example>
/**/  L := [3,2,1];
/**/  sorted(L);
[1, 2, 3]

/**/  Use R ::= QQ[x,y,z];
/**/  L := [x,y,z];
/**/  sorted(L);
[z, y, x]

/**/  sorted([y, x, z, x^2]);
[z, y, x, x^2]

/**/  sorted([3, 1, 1, 2]);
[1, 1, 2, 3]

/**/  sorted(["b","c","a"]);
["a", "b", "c"]
</example>
    </description>

    <syntax>
sorted(L:LIST):LIST

where V is a variable containing a list.
</syntax>

    <seealso>
      <see>Relational Operators</see>
      <see>SortBy</see>
      <see>SortedBy</see>
      <see>sort</see>
    </seealso>

    <types>
      <type>list</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>SortedBy</title>
    <short_description>sort a list</short_description>

    <description>
This function returns the list of the sorted elements of L without
affecting L, itself.  As for <ttref>SortBy</ttref>, the comparison
function F takes two arguments and returns True if the first argument
is less than the second, otherwise it returns False.  The sorted list
is in increasing order.
<par/>
Note that if both F(A, B) and F(B, A) return True, then A and B are
viewed as being equal.

<example>
/**/  Define ByLength(S, T)    -- define the sorting function
        Return len(S) &gt; len(T);
      EndDefine;
/**/  M := ["bird","mouse","cat"];
/**/  SortedBy(M, ByLength);
["mouse", "bird", "cat"]

/**/  M;  -- M is not changed
["bird", "mouse", "cat"]

/**/  sorted(M);  -- the function "Sort" sorts using the default ordering:
                  -- in this case, alphabetical order.
["cat", "bird", "mouse"]

/**/  SortBy(ref M, ByLength);  -- sort M in place, changing M
/**/  M;
["mouse", "bird", "cat"]
</example>
    </description>

    <syntax>
SortedBy(L:LIST, F:FUNCTION):LIST

where V is a variable containing a list and F is a boolean-valued
comparison function of two arguments (e.g. representing <em>less than</em>).
</syntax>

    <seealso>
      <see>func</see>
      <see>sort</see>
      <see>sorted</see>
      <see>SortBy</see>
    </seealso>

    <types>
      <type>list</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>source</title>
    <short_description>read commands from a file or device</short_description>

    <description>
This command executes all CoCoA commands in the file or device named
S.  A typical use of <tt>source</tt> is to collect user-defined functions and
variables in a text file, say, <tt>MyFile.coc</tt> and then execute:
<verbatim>
    source <quotes>MyFile.cocoa5</quotes>;
</verbatim>
or, equivalently, the obsolescent
<verbatim>
    &lt;&lt; <quotes>MyFile.cocoa5</quotes>;
</verbatim>
Functions and variables read in from a file in this way will erase
functions and variables with identical names that may already exist.
This can be avoided by using packages.  Repeatedly used functions can be
read into CoCoA at start-up by using <tt>source</tt> in the
<tt>userinit.coc</tt> file.
    </description>

    <syntax>
source S:STRING
</syntax>

    <seealso>
      <see>Introduction to IO</see>
      <see>Introduction to Packages</see>
      <see>User Initialization</see>
      <see>operators, shortcuts</see>
    </seealso>

    <types>
      <type>io</type>
      <type>printing</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>SourceRegion</title>
    <short_description>read commands from a region in a file</short_description>

    <description>
This command executes all CoCoA commands in the specified region of the given file.
It is not intended for manual use, but is used by the CoCoA UI.
<verbatim>
    SourceRegion FromLine,FromChar To ToLine,ToChar In <quotes>MyFile.cocoa5</quotes>;
</verbatim>
It is almost equivalent to copying the region into a temporary file, and then reading
that file with the <tt>source</tt> command.

Line and char indexes start from 1; the region identified starts at the "from"
line/character position and stops immediately before the "to" line/character position.
    </description>

    <syntax>
SourceRegion FromLine:INT,FromChar:INT To ToLine:INT,ToChar:INT In S:STRING
</syntax>

    <seealso>
      <see>source</see>
    </seealso>

    <types>
      <type>io</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>spaces</title>
    <short_description>return a string of spaces</short_description>

    <description>
This function returns a string consisting of N spaces.

<example>
/**/  L := "a" + Spaces(5) + "b";
/**/  L;
a     b
</example>
    </description>

    <syntax>
spaces(N:INT):STRING
</syntax>

    <seealso>
      <see>dashes</see>
      <see>equals</see>
    </seealso>

    <types>
      <type>string</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>sprint</title>
    <short_description>convert to a string</short_description>

    <description>
This function takes any CoCoA expression and converts its value to a
string.  One use is to check for extremely long output before printing
in a CoCoA window.

<example>
/**/  Use R ::= QQ[x,y];
/**/  I := ideal(x,y);
/**/  J := sprint(I);
/**/  I;
ideal(x, y)

/**/  J;        -- The output for I and J looks the same, but ...
ideal(x, y)

/**/  type(I);  -- I is an ideal, and
IDEAL

/**/  type(J);  -- J is just the string "ideal(x, y)".
STRING

/**/  J[1];  -- the 1st character of J
i

/**/  J[2];  -- the 2nd character of J
d

/**/  len(J);  -- J has 11 characters
11
</example>
    </description>

    <syntax>
sprint(E:OBJECT):STRING
</syntax>

    <seealso>
      <see>Introduction to IO</see>
      <see>IO.SprintTrunc</see>
      <see>print</see>
      <see>PrintLn</see>
    </seealso>

    <types>
      <type>io</type>
      <type>printing</type>
      <type>string</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>SqfreeFactor</title>
    <short_description>compute a squarefree factorization</short_description>

    <syntax>
SqfreeFactor(F:RINGELEM):RECORD
</syntax>

    <description>
Compute a factorization (of a polynomial) into coprime squarefree factors.
The factorization may sometimes be finer than necessary, i.e. two factors
could have the same multiplicity.

<example>
/**/  Use R ::= QQ[x,y];
/**/  f := (x^2-1)^2*(y+2)^3;
/**/  indent(SqfreeFactor(f));
Record[
  RemainingFactor := 1,
  factors := [x^2 -1, y +2],
  multiplicities := [2, 3]
]
</example>
    </description>

    <seealso>
      <see>factor</see>
      <see>ContentFreeFactor</see>
    </seealso>

    <types>
      <type>RingElem</type>
      <type>Record</type>
    </types>

<keys>
  <key>squarefree</key>
  <key>square-free</key>
  <key>factors</key>
  <key>factorise</key>
  <key>factorisation</key>
  <key>factorize</key>
  <key>factorization</key>
</keys>

  </command>
<!-- === COMMAND =============================================== -->
   <command>
     <title>StableBBasis5</title>
     <short_description>Stable Border Basis of ideal of points</short_description>
 
     <description>
***** NOT YET IMPLEMENTED ***** 

This function returns a record containing a <em>stable order ideal</em> of
the ideal of points, and a list of <em>almost vanishing</em> polynomials.
If the cardinality of the order ideal is equal to the number of points, it
is in fact a <em>quotient basis</em>, and in this case a <em>stable border
basis</em> founded on it is also returned.  The boolean field <tt>StableBBasisFound</tt>
is set to true if a stable border basis was found, otherwise false.
<par/>
The first argument is a list of points in k-dimensional space, and the
second argument is list of k positive tolerances (one for each dimension).
The function builds the stable order ideal stepwise by testing, from a
numerical point of view, the linear dependence of a set of vectors.
So that the answer can be represented, the current ring must have at
least k indeterminates; the term ordering is ignored as it plays no role
in determining the border basis.
 <par/>
 There is a third, optional argument: it is a real non negative number
 <tt>Gamma</tt> which is used for scaling the threshold on the
 admissible perturbation of the points.
 A value of <tt>Gamma</tt> &lt;&lt; 1 should be used.  
 If no value is specified then by default <tt>Gamma</tt> = 0.1
 <par/>
 For a full description of the algorithms we refer to the paper
 J.Abbott, C.Fassino, L.Torrente
 <em>Stable Border Bases for Ideals of Points</em> (to appear in JSC
 or arXiv:07062316).
 <par/>

<example>
  Pts := [[0.1,-1],[1,1],[2,3]];
  Toler := [0.1,0.1];
  StableBBasis5(Pts, Toler);
Record[
  AlmostVanishing := [ (...) ],
  BBasis := [
    -3602879701896397/288230376151711744y^2 + x -
  32425917317067571/72057594037927936y -
  154923827181545063/288230376151711744,
    xy - 140512308373959475/288230376151711744y^2 -
  39631676720860365/72057594037927936y +
  10808639105689191/288230376151711744,
    y^3 - 3y^2 - y + 3,
    xy^2 - 580063632005319885/288230376151711744y^2 -
  32425917317067571/72057594037927936y +
  421536925121878425/288230376151711744],
  SOI := [1, y, y^2],
  StableBBasisFound := True]
-------------------------------
  Toler := [0.6, 0.6]:
  StableBBasis5(Pts, Toler);
Record[AlmostVanishing := [.....], SOI := [1, y], StableBBasisFound := False]
-------------------------------
</example>
</description>
 

     <syntax>
 StableBBasis5(Pts: LIST, Toler: LIST): RECORD[SOI: LIST, BBasis: LIST, AlmostVanishing: LIST, StableBBasisFound: BOOL]
 StableBBasis5(Pts: LIST, Toler: LIST, Gamma: RAT): RECORD[SOI: LIST, BBasis: LIST, AlmostVanishing: LIST, StableBBasisFound: BOOL]
  </syntax>
 
     <types>
       <type>list</type>
       <type>cocoaserver</type>
     </types>
 
     <seealso>
       <see>IdealOfPoints</see>
       <see>TmpNBM</see>
       <see>Border Basis</see>
       <see>Border Bases</see>
       <see>Finite Point Sets: Buchberger-Moeller</see>
       <see>Introduction to CoCoAServer</see>
     </seealso>
 
    <keys>
     <key>abbott fassino torrente</key>
     <key>cocoalib</key>
     <key>soi</key>
     <key>stable border basis</key>
     <key>stable order ideal</key>
     <key>approx</key>
     <key>numerical buchbergermoeller</key>
     <key>approx</key>
    </keys>
 </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>StableIdeal</title>
    <short_description>stable ideal containing L</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This function returns the smallest stable ideal containing the
power-products in L.

<example>
  Use R ::= QQ[x,y,z];
  L := [xz^4, y^3];
  StableIdeal(L);
ideal(x^2z^3, xyz^3, xz^4, x^3, x^2y, xy^2, y^3)
-------------------------------
</example>
    </description>

    <syntax>
StableIdeal(L: LIST of power-products): IDEAL
</syntax>

    <seealso>
      <see>IsStable</see>
      <see>LexSegmentIdeal</see>
      <see>StronglyStableIdeal</see>
    </seealso>

    <types>
      <type>ideal</type>
      <type>list</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>StarPrint, StarSprint</title>
    <short_description>print polynomial with *&apos;s for multiplications</short_description>

    <description>
These functions print the polynomial F with asterisks added to denote
multiplications.  They may be useful when transfering polynomials or
rational functions from CoCoA to other mathematical software (e.g. Gap,
Maple, Macaulay, Singular,..).  <tt>StarPrint</tt> inserts newline
characters (only between terms) with the aim of avoiding lines longer
than 70 characters; the second argument to <tt>StarPrintFold</tt> is for
specifying a different width limit; a non positive value is treated as
meaning no limit.  The <tt>StarSprint</tt> functions print the value into
a string.


<example>
  Use R ::= QQ[x,y];
  F := x^3+2xy-y^2;
  StarPrint(F);
1*x^3 +2*x*y -1*y^2
-------------------------------
  StarPrintFold(F,1); -- this will print one term per line
1*x^3
 +2*x*y
 -1*y^2
-------------------------------
  D := OpenOFile("example");
  Print StarSprint(F) On D; -- this will print F into the file "example"
  Close(D);
-------------------------------
</example>
    </description>

    <syntax>
StarPrint(F:POLY):NULL
StarPrintFold(F:POLY, LineWidth:INT):NULL
StarSprint(F:POLY):STRING
StarSprintFold(F:POLY, LineWidth:INT):STRING
</syntax>

    <types>
      <type>polynomial</type>
    </types>

    <seealso>
      <see>Latex</see>
    </seealso>

    <keys>
    <key>multiplication asterisk</key>
    <key>gap, maple, macaulay, singular</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>starting</title>
    <short_description>list functions starting with a given string</short_description>

    <syntax>
starting(S:STRING):LIST of RECORD[IsExported, name]
</syntax>

    <description>
This function returns a list of all CoCoA functions starting with the
string <tt>S</tt>.  In general, this list will include undocumented
commands.  For these, one may find some information using
<tt>Describe Function(<quotes>Fn_Name</quotes>)</tt> or
<tt>Describe Function(<quotes>$PackageName.Fn_Name</quotes>)</tt>.

<example>
/**/  indent(starting("Su"));
[
  Record[IsExported := true, name := "$BackwardCompatible.Subsets"],
  Record[IsExported := true, name := "$BackwardCompatible.Subst"],
  Record[IsExported := true, name := "$BackwardCompatible.Sum"],
  Record[IsExported := true, name := "$BackwardCompatible.Support"]
]
</example>
    </description>

    <seealso>
      <see>Other Help</see>
    </seealso>

    <types>
      <type>help</type>
      <type>miscellaneous</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>StdDegLexMat</title>
    <short_description>matrices for std. term-orderings</short_description>

    <description>
This function return the matrix defining a standard term-ordering.

<example>
/**/  StdDegLexMat(3);
matrix( /*QQ*/
 [[1, 1, 1],
  [1, 0, 0],
  [0, 1, 0]]
 )
</example>
    </description>

    <syntax>
StdDegLexMat(N:INTEGER):MAT
</syntax>

    <seealso>
      <see>OrdMat</see>
      <see>Orderings</see>
      <see>StdDegRevLexMat</see>
      <see>LexMat</see>
      <see>RevLexMat</see>
      <see>XelMat</see>
    </seealso>

    <types>
      <type>matrix</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>StdDegRevLexMat</title>
    <short_description>matrices for std. term-orderings</short_description>

    <description>
This function return the matrix defining a standard term-ordering.

<example>
/**/  StdDegRevLexMat(3);
matrix([
  [1, 1, 1],
  [0, 0, -1],
  [0, -1, 0]
])
</example>
    </description>

    <syntax>
StdDegRevLexMat(N:INTEGER):MAT
</syntax>

    <seealso>
      <see>OrdMat</see>
      <see>Orderings</see>
      <see>StdDegLexMat</see>
      <see>LexMat</see>
      <see>RevLexMat</see>
      <see>XelMat</see>
    </seealso>

    <types>
      <type>matrix</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>StronglyStableIdeal</title>
    <short_description>strongly stable ideal containing L</short_description>

    <description>
This function returns the smallest strongly stable ideal containing the
power-products in L.

<example>
/**/  Use R ::= QQ[x,y,z];
/**/  L := [x*y^2*z];
/**/  StableIdeal(L);
ideal(x^4, x^3*y, x^2*y^2, x*y^3, x*y^2*z)

/**/  StronglyStableIdeal(L);
ideal(x^4, x^3*y, x^2*y^2, x*y^3, x^3*z, x^2*y*z, x*y^2*z)
</example>
    </description>

    <syntax>
StronglyStableIdeal(L: LIST of power-products): IDEAL
</syntax>

    <seealso>
      <see>IsStronglyStable</see>
      <see>LexSegmentIdeal</see>
      <see>StableIdeal</see>
    </seealso>

    <types>
      <type>ideal</type>
      <type>list</type>
    </types>

    <keys>
    <key>borel</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>SubalgebraMap</title>
    <short_description>algebra homomorphism representing a subalgebra</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This function returns the homomorphism representing a subalgebra.

<example>
  Use QQ[s,t];
  SAM := SubalgebraMap([s^3, s^2t, st^2, t^3]);
  Ker(SAM);
SubalgebraRing :: ideal(x[3]^2 - x[2]x[4], x[2]x[3] - x[1]x[4], x[2]^2 - x[1]x[3])
-------------------------------
  IsInSubalgebra(s^3, SAM);
True
-------------------------------
  SubalgebraRepr(s^3, SAM);
SubalgebraRing :: x[1]
-------------------------------
  IsInSubalgebra(s^5, [s^3, s^2t, st^2, t^3]);
False
-------------------------------
  SubalgebraRepr(s^5, SAM);
NULL
-------------------------------
</example>
    </description>

    <syntax>
IsInSubalgebra(F:POLY, L:LIST)
IsInSubalgebra(F:POLY, TAGGED("$alghom.Map"))
</syntax>

    <seealso>
      <see>SubalgebraRepr</see>
      <see>IsInSubalgebra</see>
      <see>ker</see>
    </seealso>

    <types>
      <type>list</type>
      <type>poly</type>
    </types>

    <keys>
    <key>homomorphism</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>SubalgebraRepr</title>
    <short_description>representation of a polynomial as a subalgebra element</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
This function returns the representation of a polynomial as a
subalgebra element in terms of the subalgebra generators.

<example>
  Use QQ[s,t];
  L := [s^3, s^2t, st^2, t^3];
  SAM := SubalgebraMap(L);
  IsInSubalgebra(s^6t^6, SAM);
True
-------------------------------
  SubalgebraRepr(s^6t^6, L);
SubalgebraRing :: x[1]^2x[4]^2
-------------------------------
  SubalgebraRepr(s^6t^6, SAM);  -- more efficient for repeated computations
SubalgebraRing :: x[1]^2x[4]^2
-------------------------------
  Image(It, RMap(L));
s^6t^6
-------------------------------
</example>
    </description>

    <syntax>
SubalgebraRepr(F:POLY, L:LIST):POLY
SubalgebraRepr(F:POLY, M:TAGGED("$alghom.Map")):POLY
</syntax>

    <seealso>
      <see>SubalgebraMap</see>
      <see>IsInSubalgebra</see>
      <see>ker</see>
    </seealso>

    <types>
      <type>list</type>
      <type>poly</type>
    </types>

    <keys>
    <key>homomorphism</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>submat</title>
    <short_description>submatrix</short_description>

    <description>
This function returns the submatrix of M formed by the rows listed
in R and the columns listed in C.  If M is a list, it is interpreted
as a matrix in the natural way.

<example>
/**/  M := mat([[1,2,3,4,5],[6,7,8,9,10],[11,12,13,14,15]]);
/**/  submat(M,[1,3],3..5);
matrix([
  [3, 4, 5],
  [13, 14, 15]
])

/**/  M := mat([[1,2,3],[4,5,6]]);
/**/  submat(M,[2],[1,3]);
matrix([
  [4, 6]
])
</example>
    </description>

    <syntax>
submat(M:MAT, R:LIST of INT, C:LIST of INT):MAT
</syntax>

    <seealso>
      <see>Introduction to Matrices</see>
      <see>minors</see>
    </seealso>

    <types>
      <type>list</type>
      <type>matrix</type>
    </types>

    <keys>
    <key>submatrix</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>submodule</title>
  <short_description>convert an expression into a module</short_description>
  
<syntax>
submodule(F: MODULE, L:LIST):MODULE
where L is a LIST of MODULEELEM.
</syntax>

<description>
This function returns the module generated by the module elements
in the given list (which might be empty).
This function is not friendly if you write the input by hand:
we suggest <ttref>SubmoduleCols, SubmoduleRows</ttref> for creating
a module from the rows or columns of a MATRIX.
<par/>
NOTE: the second argument is a list of MODULEELEM, not a list of lists
of RINGELEM.

<example>
/**/  Use R ::= QQ[x,y,z];
/**/  R3 := NewFreeModule(R, 3);
/**/  L := [ModuleElem(R3, [x,y,z]), ModuleElem(R3, [x-1,0,z])];
/**/  M := submodule(R3, L);
/**/  gens(M);
[[x, y, z], [x -1, 0, z]]
</example>
</description>

<seealso>
  <see>SubmoduleCols, SubmoduleRows</see>
  <see>GensAsCols, GensAsRows</see>
  <see>gens</see>
</seealso>

<types>
  <type>module</type>
</types>

</command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>SubmoduleCols, SubmoduleRows</title>
    <short_description>convert a matrix into a module</short_description>

    <description>
<par/>
The first (second) function returns the submodule of F generated by
the module elements described by the columns (rows) in the matrix M
(which might be empty).
<par/>
Dimensions must be compatible.

<example>
/**/  R3 := NewFreeModule(R, 3);
/**/  MGens := matrix(R,[[x,y,z],[x-1,0,z]]);

/**/  M := SubmoduleRows(R3, MGens);
/**/  gens(M);
[[x, y, z], [x -1, 0, z]]

/**/  M := SubmoduleCols(R3, MGens); -- !!! ERROR !!!

/**/  M := SubmoduleCols(NewFreeModule(R,2), MGens);
/**/  gens(M);
[[x, x -1], [y, 0], [z, z]]
</example>
    </description>

    <syntax>
SubmoduleCols(F:MODULE, M:Matrix):MODULE
SubmoduleRows(F:MODULE, M:Matrix):MODULE
</syntax>

    <seealso>
      <see>GensAsCols, GensAsRows</see>
      <see>submodule</see>
      <see>ModuleElem</see>
    </seealso>

    <types>
      <type>module</type>
    </types>

    <keys>
      <key>Cast</key>
      <key>generated</key>
      <key>generators</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>subsets</title>
    <short_description>returns all sublists of a list</short_description>

    <description>
This function computes all sublists (subsets) of a list (set).
If N is specified, it computes all sublists of cardinality N.

<example>
/**/  subsets([1, 4, 7]);
[[ ], [7], [4], [4, 7], [1], [1, 7], [1, 4], [1, 4, 7]]

/**/  subsets([1, 4, 7], 2);
[[1, 4], [1, 7], [4, 7]]

/**/  subsets([2,3,3]);                 -- list with repeated entries
[[ ], [3], [3], [3, 3], [2], [2, 3], [2, 3], [2, 3, 3]]

/**/  subsets(MakeSet([2,3,3]));
[[ ], [3], [2], [2, 3]]
</example>
    </description>

    <syntax>
subsets(S:LIST):LIST
subsets(S:LIST, N:INT):LIST
</syntax>

    <seealso>
      <see>IsSubset</see>
      <see>partitions</see>
      <see>permutations</see>
      <see>MakeSet</see>
      <see>tuples</see>
    </seealso>

    <types>
      <type>list</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>subst</title>
    <short_description>substitute values for indeterminates</short_description>

    <description>
The first form of this function substitutes <tt>F_i</tt> for <tt>X_i</tt> in the
expression E.  The second form is a shorthand for the first in the
case of a single indeterminate.  When substituting for the
indeterminates in order, it is easier to use <ttref>eval</ttref>.

<example>
/**/  Use R ::= QQ[x,y,z,t];
/**/  F := x +y +z +t^2;
/**/  subst(F, x, -2);
t^2 +y +z -2

/**/  subst(F, [[x,x^2], [y,y^3], [z,t^5]]);
t^5 +y^3 +x^2 +t^2

/**/  eval(F, [x^2,y^3,t^5]); -- the same thing as above
t^5 +y^3 +x^2 +t^2

/**/  MySubst := [[y,1], [t,3z-x]];
/**/  subst(x*y*z*t, MySubst);  -- substitute into the function x*y*z*t
-x^2*z +3*x*z^2
</example>
    </description>

    <syntax>
subst(E:OBJECT, X, F):OBJECT
subst(E:OBJECT,[[X_1, F_1],...,[X_r, F_r]]):OBJECT

where each X or X_i is an indeterminate and each F or F_i is a number,
polynomial, or rational function.
</syntax>

    <seealso>
      <see>eval</see>
      <see>Evaluation of Polynomials</see>
      <see>image</see>
      <see>PolyAlgebraHom</see>
      <see>QZP</see>
      <see>RingElem</see>
      <see>ZPQ</see>
      <see>Substitutions</see>
    </seealso>

    <types>
      <type>polynomial</type>
      <type>ratfun</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>sum</title>
    <short_description>the sum of the elements of a list</short_description>

    <description>
This function returns the sum of the objects in the list L.

<example>
/**/  Use R ::= QQ[x,y];
/**/  sum([3, x, y^2]);
y^2 +x +3

/**/  sum(1..40) = binomial(41,2);
true

/**/  sum(["c","oc","oa"]);
cocoa

/**/ sum([]);  -- gives 0 of type INT
0
/**/ sum([], "");  -- gives empty STRING

/**/ sum([], x);  -- gives type RINGELEM
x
</example>
    </description>

    <syntax>
sum(L:LIST):OBJECT
sum(L:LIST, O:OBJECT):OBJECT
</syntax>

    <seealso>
      <see>Algebraic Operators</see>
      <see>product</see>
    </seealso>

    <types>
      <type>ideal</type>
      <type>integer</type>
      <type>list</type>
      <type>matrix</type>
      <type>polynomial</type>
      <type>rat</type>
      <type>ratfun</type>
      <type>moduleelem</type>
      <type>zmod</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>support</title>
    <short_description>the list of terms of a polynomial or vector</short_description>

    <description>
This function returns the list of terms of F.  To get a list of
monomials, which includes coefficients, use <ttref>monomials</ttref>.

<example>
/**/  Use R ::= QQ[x,y];
/**/  F := 3*x^2-4*x*y+y^3+3;
/**/  support(F);
[y^3, x^2, x*y, 1]

/**/  monomials(F);
[y^3, 3*x^2, -4*x*y, 3]

/**/  Support(Vector(x^2y, x^3-3y^2, 34)); --***OBSOLETE MANUAL: WORK IN PROGRESS***
[Vector(0, x^3, 0), Vector(x^2y, 0, 0), Vector(0, y^2, 0), Vector(0, 0, 1)]
</example>
    </description>

    <syntax>
support(F:POLY or MODULEELEM):LIST
</syntax>

    <seealso>
      <see>coefficients</see>
      <see>monomials</see>
    </seealso>

    <types>
      <type>polynomial</type>
      <type>moduleelem</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>swap</title>
    <short_description>swap two values</short_description>

    <syntax>
swap(ref A:OBJECT, ref B:OBJECT):NULL
</syntax>

    <description>
This procedure swaps two values; it returns nothing!

<example>
/**/  A := 1;
/**/  B := 2;
/**/  swap(ref A, ref B);
/**/  PrintLn [A,B];
[2, 1]
</example>
    </description>

    <seealso>
      <see>ref</see>
    </seealso>

    <types>
      <type>any</type>
    </types>

  </command>

<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>sylvester</title>
    <short_description>the Sylvester matrix of two polynomials</short_description>

    <description>
(sorry Sylvester for the lower-case: here we follow the naming
convention <em>single name goes lower-case</em>)
<par/>
This function returns the Sylvester matrix of the polynomials F and G
with respect to the indeterminate X.  This is the matrix used to
calculate the resultant.

<example>
/**/  Use R ::= QQ[p,q,x];
/**/  F := x^3+p*x-q; G := der(F, x);
/**/  sylvester(F, G, x);
matrix([
  [1, 0, p, -q, 0],
  [0, 1, 0, p, -q],
  [3, 0, p, 0, 0],
  [0, 3, 0, p, 0],
  [0, 0, 3, 0, p]
])

/**/  det(sylvester(F, G, x)) = resultant(F, G, x);
true
</example>
    </description>

    <syntax>
sylvester(F:POLY, G:POLY, X:INDET)
</syntax>

    <seealso>
      <see>resultant</see>
    </seealso>

    <types>
      <type>polynomial</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>SymbolRange</title>
    <short_description>range of symbols for the indeterminates of a PolyRing</short_description>

    <description>
This function returns the list of the symbols with a given head and a
range of indices.
A symbol is a record with head (as <ttref>IndetName</ttref>) and indices
(as <ttref>IndetSubscripts</ttref>)

<example>
/**/  indent(SymbolRange("x", 3, 5));
[
  Record[head := "x", indices := [3]],
  Record[head := "x", indices := [4]],
  Record[head := "x", indices := [5]]
]
/**/  P := NewPolyRing(QQ, SymbolRange("x", 0,2));
/**/  indets(P);
[x[0], x[1], x[2]]
</example>
    </description>

    <syntax>
SymbolRange(H:STRING, LO:INT, HI:INT):RECORD
</syntax>

    <seealso>
      <see>indet</see>
      <see>IndetSubscripts</see>
      <see>IndetIndex</see>
      <see>IndetName</see>
      <see>NumIndets</see>
      <see>SymbolRange</see>
    </seealso>

    <types>
      <type>ring</type>
    </types>

    <keys>
      <key>variable</key>
      <key>indexed</key>
      <key>indices</key>
    </keys>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>syz</title>
    <short_description>syzygy modules</short_description>

    <description>
<par/>
In the first two forms this function computes the syzygy module of a list
of polynomials or vectors.
<tt>SyzOfGens(I)</tt> is the same as <tt>Syz(gens(I))</tt>.
<par/>
In the last form this function returns the specified syzygy module of
the minimal free resolution of M which must be homogeneous.  As a side
effect, it computes the Groebner basis of M.   (***** NOT YET IMPLEMENTED *****)
<par/>
The coefficient ring must be a field.
<par/>
For fine control and monitoring of Groebner basis calculations, see
<ref>The Interactive Groebner Framework</ref> and <ref>Introduction to Panels</ref>.

<example>
/**/  Use R ::= QQ[x,y,z];
/**/  indent(Syz([x^2-y-1, y^3-z, x^2-y, y^3-z]));
SubmoduleRows(F, matrix(
  [y^3 -z, 0, 0, -x^2 +y +1],
  [0, 1, 0, -1],
  [x^2 -y, 0, -x^2 +y +1, 0],
  [0, 0, y^3 -z, -x^2 +y]
))
-------------------------------
/**/  I := ideal(x, x, y);
/**/  syz(gens(I));
submodule(FreeModule(..), [[1, -1, 0], [0, y, -x]])
/**/  SyzOfGens(I);
submodule(FreeModule(..), [[1, -1, 0], [0, y, -x]])


  Syz(I, 1);      -- NOT YET IMPLEMENTED
Module([[x, -y]])
-------------------------------
  I := ideal(x^2-yz, xy-z^2, xyz);    -- NOT YET IMPLEMENTED
  Syz(I,0);
Module([x^2 - yz], [xy - z^2], [xyz])
-------------------------------
  Syz(I,1);    -- NOT YET IMPLEMENTED
  Module([-x^2 + yz, xy - z^2, 0], [xz^2, -yz^2, -y^2 + xz], [z^3, 0,
-xy + z^2], [0, z^3, -x^2 + yz])
-------------------------------
  Syz(I,2);
Module([0, z, -x, y], [-z^2, -x, y, -z])
-------------------------------
  Syz(I,3);
Module([[0]])
-------------------------------
  Res(I);
0 --&gt; R(-6)^2 --&gt; R(-4)(+)R(-5)^3 --&gt; R(-2)^2(+)R(-3)
-------------------------------
</example>
    </description>

    <syntax>
Syz(L:LIST of RINGELEM):MODULE
Syz(M:IDEAL or MODULE, Index:INT):MODULE
</syntax>

    <seealso>
      <see>Introduction to Groebner Bases in CoCoA</see>
      <see>res</see>
      <see>SyzOfGens</see>
    </seealso>

    <types>
      <type>groebner</type>
      <type>groebner-basic</type>
      <type>ideal</type>
      <type>list</type>
      <type>module</type>
    </types>

    <keys>
    <key>syzygies</key>
    <key>syzygy</key>
    </keys>
  </command>
<!-- ===  COMMAND-rm SyzMinGens ========================================== -->
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>SyzOfGens</title>
  <short_description>syzygy module for a given set of generators</short_description>

<syntax>
SyzOfGens(M:IDEAL, MODULE, or Quotient):MODULE
</syntax>
<description>
If M is an ideal or submodule, this function calculates the syzygy
module for the given set of generators of M. 
<par/>
If M is a quotient of a ring by an ideal I or a quotient of a free
module by a submodule N, then this function calculates the syzygy
module for the given set of generators of I or N, respectively.
<par/>
<tt>SyzOfGens(I)</tt> is the same as <tt>Syz(gens(I))</tt>.
<par/>
The coefficient ring must be a field.

<example>
/**/  Use R ::= QQ[x,y];
/**/  I := ideal(x, y, x+y);
/**/  indent(SyzOfGens(I));
SubmoduleRows(F, matrix([
  [1, 1, -1],
  [0, x +y, -y]
]))

/**/  R3 := NewFreeModule(R, 3);
/**/  MGens := matrix(R,[[x,y,z], [x-y,0,z], [y,y,0]]);
/**/  indent(SyzOfGens(SubmoduleRows(R3, MGens)));
SubmoduleRows(F, matrix([
  [1, -1, -1]
]))
</example>
</description>

<seealso>
  <see>syz</see>
</seealso>

<types>
  <type>groebner</type>
  <type>groebner-basic</type>
  <type>ideal</type>
  <type>module</type>
  <type>quotient</type>
</types>

</command>

 </chapter_letter>
 <!-- ===  CHAPTER  =============================================== -->
 <chapter_letter>
   <title>T</title>

<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>tag</title>
    <short_description>returns the tag string of an object</short_description>

    <description>
If E is a tagged object, this function returns the tag of E;
otherwise, it returns the empty string.

<example>
/**/  L := tagged(3,"MyTag");
/**/  type(L);
TAGGED("$TopLevel.MyTag")

/**/  tag(L);
MyTag
</example>
    </description>

    <syntax>
tag(E:OBJECT):STRING
</syntax>

    <seealso>
      <see>Tagged Printing</see>
      <see>tagged</see>
      <see>untagged</see>
    </seealso>

    <types>
      <type>io</type>
      <type>printing</type>
      <type>tags</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>tagged</title>
    <short_description>tag an object for pretty printing</short_description>

    <description>
This first function returns the object E, tagged with the string S.
Tagging is used for pretty printing of objects.  See the reference
listed below.

<example>
/**/  L := [1,2,3];
/**/  M := tagged(L,"MyTag");
/**/  type(L);
LIST

/**/  type(M);
TAGGED("$TopLevel.MyTag")

/**/  type(untagged(M));
LIST
</example>
    </description>

    <syntax>
tagged(E:OBJECT, S:STRING):TAGGED(S)
</syntax>

    <seealso>
      <see>Tagged Printing</see>
      <see>tag</see>
      <see>untagged</see>
    </seealso>

    <types>
      <type>io</type>
      <type>printing</type>
      <type>tags</type>
    </types>

    <keys>
    <key>tag an object</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>tail</title>
    <short_description>remove the first element of a list</short_description>

    <description>
This function returns the list obtained from L by removing its first
element.  It cannot be applied to the empty list.

<example>
/**/  tail([1,2,3]);
[2, 3]
</example>
    </description>

    <syntax>
tail(L:LIST):LIST
</syntax>

    <seealso>
      <see>first</see>
      <see>last</see>
    </seealso>

    <types>
      <type>list</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>TensorMat</title>
    <short_description>returns the tensor product of two matrices</short_description>

    <description>
This function returns the tensor product of two matrices.

<example>
/**/  Use R ::= QQ[x,y,z,w];
/**/  TensorMat(mat(R, [[1,-1],[2,-2],[3,-3]]), mat(R, [[x,y],[z,w]]));
matrix([
  [x, y, -x, -y],
  [z, w, -z, -w],
  [2*x, 2*y, -2*x, -2*y],
  [2*z, 2*w, -2*z, -2*w],
  [3*x, 3*y, -3*x, -3*y],
  [3*z, 3*w, -3*z, -3*w]
])
</example>
    </description>

    <syntax>
TensorMat(M:Mat, N:Mat):MAT
</syntax>

    <types>
      <type>matrix</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>TgCone</title>
  <short_description>tangent cone</short_description>

<syntax>
TgCone(I:IDEAL): IDEAL
</syntax>

<description>
The <em>initial form</em> of a polynomial F is the homogeneous
component of F of the lowest degree (in contrast with the <em>leading
form</em>, see <ttref>LF</ttref>, <ttref>DF</ttref>).
The <em>initial ideal</em> of the ideal <tt>I</tt> is the ideal
generated by the initial forms of all polynomials in <tt>I</tt>.
It is also called <em>tengent cone</em> (which strictly is the variety
defined by the initial ideal).
<par/>
The implementation is based on Lazard's method (see Kreuzer-Robbiano,
Commutative Computer Algebra II, pg.463).
<example>
/**/  Use R ::= QQ[x,y,z];
/**/  TgCone(ideal(x^3-y));
ideal(-y)
/**/  TgCone(ideal(x^3+x^2-y^2));
ideal(x^2 -y^2)

/**/  I := ideal(x^3-y*z, y^2-x*z, z^2-x^2*y);
/**/  TgCone(I); -- same as InitialIdeal(I, [x,y,z]);
ideal(y^2 -x*z, z^2, -y*z)
</example>
</description>

<types>
  <type>ideal</type>
</types>

<keys>
  <key>tangentcone</key>
  <key>tangent cone</key>
</keys>

<seealso>
  <see>InitialIdeal</see>
  <see>PrimaryPoincare</see>
</seealso>
</command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>TimeOfDay</title>
    <short_description>the current time</short_description>

<syntax>
TimeOfDay()
</syntax>
<description>
This function returns the current time as an INT in the form HHMMSS.
<par/>
Note that from version 5.0.4 this information is no longer given by
the function <ttref>date</ttref>.

<example>
/**/  date();       -- 2013-05-30
20130530
/**/  TimeOfDay();  -- 09:08:13
90813
</example>
</description>

<seealso>
  <see>date</see>
</seealso>

<types>
  <type>miscellaneous</type>
</types>

  </command>
<!-- === COMMAND =============================================== -->
   <command>
     <title>TmpNBM</title>
     <short_description>Numerical Border Basis of ideal of points</short_description>
 
     <description>
<par/>
This function checks that the current ring is suitable: see below for details.
<par/>	
This function returns a record containing a factor-closed set of power-products
<tt>QuotientBasis</tt> and a list of <em>almost vanishing</em> polynomials.
If the cardinality of the <tt>QuotientBasis</tt> is equal to the
number of points, it is in fact a <em>quotient basis</em> of the ideal
of points, and in this case a <em>border basis</em> founded on it is also returned.
<par/>
The first argument is a list of points in k-dimensional space, and the
second argument is list of k positive tolerances (one for each dimension).
So that the answer can be represented, the current ring must have at
least k indeterminates; the term ordering is ignored as it plays no role
in determining the border basis.
 <par/>
 For a full description of the algorithms we refer to the paper
 C.Fassino
 <em>Almost Vanishing Polynomials for Sets of Limited Precision Points</em>
 (arXiv:0807.3412).
 <par/>

<example>
/**/ P ::= QQ[x,y];
/**/ Eps := [0.1, 0.1];
/**/ Points := [[10, 0], [-10, 0], [0, 10], [0, -10], [7, 7], [-7, -7]];
/**/ indent(TmpNBM(P, mat(Points), RowMat(Eps)));
Record[
  AlmostVanishing := [x^2 +(2/49)*x*y +y^2 -100,
                      x*y^2 +(49/51)*y^3 +(-4900/51)*y, y^4 +51*x*y -100*y^2],
  BBasis := [x^2 +(2/49)*x*y +y^2 -100, x*y^2 +(49/51)*y^3 +(-4900/51)*y,
             x^2*y +(49/51)*y^3 +(-4900/51)*y, y^4 +51*x*y -100*y^2, x*y^3 -49*x*y],
  QuotientBasis := [1, y, x, y^2, x*y, y^3],
  StableBBasisFound := true
]
</example>
</description>
 

     <syntax>
 TmpNBM(P: RING, Pts: MAT, Toler: MAT): RECORD[QuotientBasis: LIST, BBasis: LIST, AlmostVanishing: LIST, StableBBasisFound: BOOL]
  </syntax>
 
     <types>
       <type>list</type>
       <type>matrix</type>
     </types>
 
     <seealso>
       <see>IdealOfPoints</see>
       <see>StableBBasis5</see>
       <see>Finite Point Sets: Buchberger-Moeller</see>
     </seealso>
 
    <keys>
     <key>abbott fassino torrente</key>
     <key>cocoalib</key>
     <key>stable border basis</key>
     <key>bbasis</key>
     <key>stable order ideal</key>
     <key>approx</key>
     <key>numerical buchbergermoeller</key>
     <key>approx</key>
     <key>stablebbasisnbm5</key>
    </keys>
 </command>

<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>TopLevel</title>
    <short_description>make a top level variable accessible</short_description>

    <syntax>
TopLevel X;

where <tt>X</tt> is the name of a top level variable or function.
</syntax>

    <description>
This command makes a top-level variable accessible from inside a function.
It is useful for making <tt>QQ</tt> and <tt>ZZ</tt> visible, and also if
a top-level function is to be passed as a parameter (<i>e.g.</i> to the
function <ttref>SortBy</ttref>).
<par/>
The command may be used with any top-level variable, but it is poor style
to use it for purposes other than those mentioned above.

<example>
/**/  Define CompareLen(X,Y) Return len(X) &lt; len(Y); EndDefine;
/**/  Define LongestName(ListOfNameAndValue)
/**/    TopLevel CompareLen;  --> to pass it as paremeter to SortBy
/**/    names := [entry[1] | entry in ListOfNameAndValue];
/**/    SortBy(ref names, CompareLen);
/**/    Return last(names);
/**/  EndDefine;
/**/  L := [["ABC",1],["XYZT",2]];
/**/  LongestName(L);
XYZT
</example>
    </description>

  <seealso>
    <see>Func</see>
    <see>ImportByRef, ImportByValue</see>
  </seealso>

    <types>
      <type>function</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>TopLevelFunctions</title>
    <short_description>returns the functions available at top-level</short_description>

    <description>
This function returns the list of all functions available at top-level

<example>
/**/  indent(TopLevelFunctions());
[
  Record[IsExported := true, Name := "$BackwardCompatible.Abs"],
  Record[IsExported := true, Name := "$BackwardCompatible.Append"],
  Record[IsExported := true, Name := "$BackwardCompatible.Ascii"],
  ...
</example>
    </description>

    <syntax>
TopLevelFunctions(): LIST
</syntax>

    <types>
      <type>list</type>
      <type>function</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>toric</title>
    <short_description>saturate toric ideals</short_description>

    <description>
These functions return the saturation of an ideal, I, generated by
binomials.  In the first two cases, I is the ideal generated by the
binomials in L.  To describe the ideal in the last case, let K be the
integral elements in the kernel of M.  For each k in K, we can write k
= k(+) - k(-) where the i-th component of k(+) is the i-th component
of k, if positive, otherwise zero.  Then I is the ideal generated by
the binomials <tt>x^k(+) - x^k(-)</tt> as k ranges over K.
<par/>
NOTE: successive calls to this last form of the function may produce
different generators for the saturation.
<par/>
The first and third functions return the saturation of I.  For the
second function, if the saturation of I with respect to the variables
in X happens to equal the saturation of I, then the saturation of I is
returned.  Otherwise, an ideal <em>containing</em> the saturation with
respect to the given variables is returned.  The point is that if one
knows, a priori, that the saturation of I can be obtained by
saturating with respect to a subset of the variables, the second
function may be used to save time.
<par/>
For more details, see the article: A.M. Bigatti, R. La Scala,
L. Robbiano, <em>Computing Toric Ideals,</em> Preprint (1998).  The article
describes three different algorithms; the one implemented in CoCoA is
<em>EATI</em>. The first two examples below are motivated by B. Sturmfels,
<em>Groebner Bases and Convex Polytopes,</em> Chapter 6, p. 51.  They count
the number of homogeneous primitive partition identities of degrees 8
and 9.

<example>
/**/  Use QQ[x[1..8],y[1..8]];
/**/  HPPI8 := [x[1]^I*x[I+2]*y[2]^(I+1) -y[1]^I*y[I+2]*x[2]^(I+1) | I In 1..6];
/**/  BL := toric(ideal(HPPI8), [x[1],y[2]]);
/**/  len(gens(BL));
340

/**/  Use QQ[x[1..9],y[1..9]];
/**/  HPPI9 := [x[1]^I*x[I+2]*y[2]^(I+1) -y[1]^I*y[I+2]*x[2]^(I+1) | I In 1..7];
/**/  BL := toric(ideal(HPPI9), [x[1],y[2]]);
/**/  len(gens(BL));
798

/**/  Use R ::= QQ[x,y,z,w];
/**/  toric(ideal(xz-y^2, xw-yz));
ideal(-y^2 +x*z, -y*z +x*w, z^2 -y*w)

/**/  toric(ideal(x*z-y^2, x*w-y*z), [y]);
ideal(-y^2 +x*z, -y*z +x*w, z^2 -y*w)

/**/  Use R ::= QQ[x,y,z];
/**/  toric([[1,3,2],[3,4,8]]);
ideal(-x^16 +y^2*z^5)

/**/  toric(mat([[1,3,2],[3,4,8]]));
ideal(-x^16 +y^2*z^5)
</example>
    </description>

    <syntax>
toric(I:IDEAL):IDEAL
toric(I:IDEAL, L:LIST of INDETS):IDEAL
toric(M:MAT or LIST of LIST):IDEAL

where M is a matrix of integers with no zero column.
</syntax>

    <seealso>
    </seealso>

    <types>
      <type>ideal</type>
      <type>matrix</type>
      <type>list</type>
      <type>toric</type>
    </types>


    <keys>
    <key>bigatti lascala robbiano</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
<!--   <command> -->
<!--     <title>Toric.CheckInput</title> -->
<!--     <short_description>check input to <tt>Toric</tt></short_description> -->

<!--     <description> -->
<!-- This function checks if E or (E, X) is suitable input for <ttref>Toric</ttref>. -->
<!-- Thus, E should be either a list of homogeneous binomials (without -->
<!-- coefficients) or a matrix of non-negative integers.  In the former -->
<!-- case, X must be a list of indeterminates (in the latter, X would be -->
<!-- ignored by <ttref>Toric</ttref> anyway). -->

<!-- <example> -->
<!--   Use R ::= QQ[x,y,z]; -->
<!--   Toric.CheckInput([[1,2,3,4],[4,5,6,7]]); -->
<!-- True -->
<!--   Toric.CheckInput([[-1,2],[3,4]]); -->
<!-- ERROR: entries must be non-negative integers -->
<!-- CONTEXT: Return(Error(Toric_IntMatrix)) -->
<!--   Toric.CheckInput([xy-z^2,x^3-y^2z]); -->
<!-- True -->
<!--   Toric.CheckInput([3xy-z^2,x^3-y^2z]); // the binomials should not -->
<!--                                         // have coefficients -->
<!-- ERROR: generators must be of type: power-product - power-product -->
<!-- CONTEXT: Return(Error(Toric_PP)) -->
<!--   Toric.CheckInput([xy-z^2,x^3-y^2z],[x]); -->
<!-- True -->
<!-- </example> -->
<!--     </description> -->

<!--     <syntax> -->
<!-- Toric.CheckInput(E:OBJECT):BOOL -->
<!-- Toric.CheckInput(E:OBJECT, X:LIST):BOOL -->
<!-- </syntax> -->

<!--     <seealso> -->
<!--       <see>Toric</see> -->
<!--     </seealso> -->

<!--     <types> -->
<!--       <type>ideal</type> -->
<!--       <type>matrix</type> -->
<!--       <type>list</type> -->
<!--       <type>toric</type> -->
<!--     </types> -->

    <keys>
<!--     <key>bigatti</key> -->
    </keys>
<!--   </command> -->
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>transposed</title>
    <short_description>the transposition of a matrix</short_description>

    <description>
This function returns the transpose of the matrix M.

<example>
/**/  M := mat([[1,2,3],[4,5,6]]);
/**/  M;
matrix([
  [1, 2, 3],
  [4, 5, 6]
])

/**/  transposed(M);
matrix([
  [1, 4],
  [2, 5],
  [3, 6]
])
</example>
    </description>

    <syntax>
transposed(M:MAT):MAT
</syntax>

    <types>
      <type>matrix</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>try</title>
    <short_description>try and catch an error</short_description>

    <description>
Usually, when an error occurs during the execution of a command, the
error is automatically propagated out of the nesting of the
evaluation.  This can be prevented with the use of <tt>Try..UponError</tt>.
<par/>
If an error occurs during the execution of the commands C1, then it is
captured by the command <tt>UponError</tt> and assigned to the
variable E, and the commands C2 are executed; the string inside E may be
retrieved using <ttref>GetErrMesg</ttref>.  If no error occurs then
the variable E and the commands C2 are ignored.

<example>
/**/  deg(zero(R));
ERROR: Non-zero RingElem required
 deg(zero(R));
 ^^^^^^^^^^^^

  Define MyDeg(F)
    Try
      D := Deg(F);
      Return D;
    UponError E Do
      MyDegError := GetErrMesg(E);
      If "Non-zero RingElem required" IsIn MyDegError Then
        Return -123456;
      Else
        error(MyDegError);
      EndIf; 
    EndTry;
  EndDefine;

/**/  MyDeg(x);
1
/**/  MyDeg(zero(R));
-123456
/**/  MyDeg("a");
ERROR: Expecting type RINGELEM, but found type STRING
        error(MyDegError);
        ^^^^^^^^^^^^^^^^^
</example>


    </description>

    <syntax>
Try C1 UponError E Do C2 EndTry

where C1, C2 are sequences of commands and E is a variable identifier.
</syntax>

    <keys>
    <key>catch</key>
    <key>uponerror</key>
    </keys>

    <seealso>
      <see>error</see>
      <see>GetErrMesg</see>
    </seealso>

    <types>
      <type>error</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>tuples</title>
    <short_description>N-tuples</short_description>

    <description>
This function computes all N-tuples with entries in S.
It is equivalent to <tt>S &gt;&lt; S &gt;&lt; ... &gt;&lt; S</tt>  [N times].

<example>
/**/  tuples([1, 4, 7], 2);
[[1, 1], [1, 4], [1, 7], [4, 1], [4, 4], [4, 7], [7, 1], [7, 4], [7, 7]]
</example>
    </description>

    <syntax>
tuples(S:LIST, N:INT):LIST
</syntax>

    <seealso>
      <see>CartesianProduct, CartesianProductList</see>
      <see>permutations</see>
      <see>subsets</see>
    </seealso>

    <types>
      <type>list</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>type</title>
    <short_description>the data type of an expression</short_description>

    <description>
This function returns the data type of E.

<example>
/**/ L := [1,"a",2,"b",3,"c"];
/**/ [ X In L | type(X)=INT ];
[1, 2, 3]

/**/  type(type(INT));  -- Type returns a value of type TYPE
TYPE

/**/  CurrentTypes();
[BOOL, ERROR, FUNCTION, IDEAL, INT, INTMAP, LIST, MAT, MATRIXROW, MODULE, OSTREAM, RAT, RATFUN, RECORD, RING, RINGELEM, RINGHOM, STRING, TYPE, MODULEELEM, VOID, ZMOD, TAGGED("$TopLevel.MyTag")]
</example>
    </description>

    <syntax>
type(E:OBJECT):TYPE
</syntax>

    <seealso>
      <see>Data Types</see>
      <see>CurrentTypes</see>
    </seealso>

    <types>
      <type>type</type>
    </types>

  </command>
 </chapter_letter>
 <!-- ===  CHAPTER  =============================================== -->
 <chapter_letter>
   <title>U</title>

<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>UnivariateIndetIndex</title>
    <short_description>the index of the indeterminate of a univariate polynomial</short_description>

    <description>
This function returns 0 if the polynomial F is not univariate
otherwise it returns the indeterminate index of F.
<par/>
NB: If F is a constant, it returns 1.
<example>
/**/  Use R ::= QQ[x,y,z];
/**/  UnivariateIndetIndex(3*x^4-2*x-1);
1

/**/  UnivariateIndetIndex(x-y-1);
0

/**/  UnivariateIndetIndex(one(R));
1
</example>

    </description>

    <syntax>
UnivariateIndetIndex(F: POLY): INT
</syntax>

    <seealso>
      <see>indet</see>
      <see>IndetSubscripts</see>
      <see>IndetIndex</see>
      <see>IndetName</see>
      <see>indets</see>
      <see>NumIndets</see>
    </seealso>

    <types>
      <type>ring</type>
      <type>polynomial</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>Unset</title>
    <short_description>set and unset panel options</short_description>

    <description>
***** OBSOLETE *****
The command <tt>Set</tt> in its first form sets a panel option to True.
The command <tt>UnSet</tt> sets a panel option to False.  The command <tt>Set</tt>
in the second-listed form can be used to set an option to True or
False.  A list of panels is returned by <tt>panels()</tt>, and a list of
panel options for a panel with name P is printed by <tt>panel(P)</tt>.  The
current status of an option is returned by <ttref>Option</ttref>.

<example>
  Panel(GROEBNER);

Sugar........... : True
FullRed......... : True
SingleStepRed... : False
Verbose......... : False
-------------------------------
  Set Verbose;
  UnSet Sugar;
  Set FullRed := False;
  Panel(GROEBNER);

Sugar........... : False
FullRed......... : False
SingleStepRed... : False
Verbose......... : True
-------------------------------
</example>

NOTE: there is also a function called <tt>MakeSet</tt> which takes a list
obtained by removing duplicate elements.  The search key for that
function in online help is <ttref>MakeSet</ttref> and the search key for the present
command is <tt>Unset</tt>.
    </description>

    <syntax>
Set O
Set O := B:BOOL
UnSet O

where O is a panel option.
</syntax>

    <seealso>
      <see>Introduction to Panels</see>
      <see>panel</see>
      <see>Option</see>
      <see>panels</see>
    </seealso>

    <types>
      <type>panels</type>
      <type>system</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>untagged</title>
    <short_description>untag an object</short_description>

    <description>
This function strips an object E of its tag, if any.
<tt>@E</tt> is equivalent to <tt>untagged(E)</tt>.
<par/>
Tags are used for pretty printing of objects.  See the reference
listed below.

<example>
/**/  L := [1,2,3];
/**/  M := tagged(L,"MyTag");
/**/  type(L);
LIST

/**/  type(M);
TAGGED("MyTag")

/**/  type(untagged(M));
LIST
</example>
    </description>

    <syntax>
untagged(E:TAGGED_OBJECT):UNTAGGED_OBJECT
</syntax>

    <seealso>
      <see>Tagged Printing</see>
      <see>tag</see>
      <see>tagged</see>
      <see>operators, shortcuts</see>
    </seealso>

    <types>
      <type>io</type>
      <type>printing</type>
      <type>tags</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>updating CoCoA-4 code</title>
  <short_description>Guidance for updating CoCoA-4 code</short_description>

<syntax>
Not E
Var X
Using R Do...EndUsing
</syntax>
<description>
CoCoA-5 is largely, but not completely, backward-compatible with CoCoA-4.
Some commands/functions have changed name; others have been removed or
replaced.  Here we give a little guidance to help update your CoCoA-4
programs to CoCoA-5/
<par/>
The operator <tt>Not</tt> has been replaced by the function <tt>not(...)</tt>.
<par/>
Several functions modify one of their arguments (<i>e.g.</i> <ttref>append</ttref>,
<ttref>sort</ttref>); CoCoA-5 wants these arguments to be identified with the new
keyword <ttref>ref</ttref>, and will issue a warning if you don't do this.
<par/>
Implicit multiplication has gone: either write <tt>x*y</tt> instead of <tt>xy</tt>
for every product, or use <ttref>CoCoA-4 mode</ttref>.
<par/>
Many CoCoA-4 functions would employ the <tt>CurrentRing</tt> implicitly (<i>e.g.</i>
<tt>NumIndets()</tt>, <tt>CoeffRing()</tt>).  They now require an explicit argument;
you can pass <tt>CurrentRing</tt> as the argument, but inside a function you must
make that system variable visible via the command <ttref>TopLevel</ttref>.  However,
we encourage you to consider modifying your function so that it does not depend
on <tt>CurrentRing</tt>; <i>e.g.</i> you can find out to which ring a value belongs
by calling the function <ttref>RingOf</ttref>.
<par/>
The function <ttref>LinKer</ttref> has been replaced by <ttref>LinKerBasis</ttref>,
and there is a new function called <ttref>LinKer</ttref> which produces a matrix.
More generally, see also the CoCoA-4 "translation table" (where is it???)

<example>
/*C4*/ If Not X IsIn L Then ... EndIf;
/*C5*/ If not(X IsIn L) Then ... EndIf;

/*C4*/ F := 3xyzt;
/*C5*/ F := 3*x*y*z*t;  OR  F := ***3xyzt***;

/*C4*/ Define LastIndet() Return Last(Indets()); EndDefine;
/*C5*/ Define LastIndet() TopLevel CurrentRing; Return last(indets(CurrentRing)); EndDefine;
</example>
    </description>

    <seealso>
      <see>CoCoA-4 mode</see>
      <see>TopLevel</see>
      <see>CurrentRing</see>
      <see>RingOf</see>
    </seealso>

    <types>
      <type>ring</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>use</title>
  <short_description>command for making a ring active</short_description>

<syntax>
Use R
Use RingDefn
Use R ::= RingDefn

where R is a RING, and RingDefn is a ring definition.
</syntax>
<description>
This command works only at top-level; it makes a ring active,
<i>i.e.</i> it makes that ring the <em>current ring</em>.
The command will also let you create a new ring, and make it active
immediately <tt>Use NewR ::= RingDefn;</tt> where <tt>RingDefn</tt> is
a ring definition; this is a shorthand for
<tt>NewR ::= RingDefn;  Use NewR;</tt>
<par/>
This command cannot be called inside a function, and it is never
necessary (if you write clean programs ;-)
In CoCoA-5 you can define new rings, return rings, assign rings and
pass rigns as arguments (this was not possible in CoCoA-4).
<par/>

<example>
/**/  Use S ::= QQ[x,y,z];
/**/  Print CurrentRing;
RingDistrMPolyClean(QQ, 3)
/**/  indets(CurrentRing);
[x, y, z]

/**/  Use QQ[u];  -- can be used w/out a ring identifier
/**/  indets(CurrentRing);
[u]

  Define SumInAnotherRing(N)
    K := NewRingTwinFloat(128); -- 128 bits of precision
    P ::= K[x[1..N]], Lex;
    Return sum(indets(P));
  EndDefine;
/**/  SumInAnotherRing(4);
x[1] +x[2] +x[3] +x[4]
/**/  CoeffRing(RingOf(It));
RingTwinFloat(AccuracyBits=128, BufferBits=128, NoiseBits=32)
</example>
    </description>

    <seealso>
      <see>Accessing Other Rings</see>
      <see>CurrentRing</see>
      <see>RingOf</see>
    </seealso>

    <types>
      <type>ring</type>
    </types>

  </command>
<!-- ===  COMMAND-rm Using ============================================= -->

 </chapter_letter>
 <!-- ===  CHAPTER  =============================================== -->
 <chapter_letter>
   <title>V</title>

<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>valuation</title>
    <short_description>p-adic valuation</short_description>

<syntax>
valuation(p:INT, N:INT):INT
</syntax>

    <description>
This function determines the p-adic valuation of a non-zero integer:
the largest integer <code>k</code> such that <code>power(p,k)</code> divides <code>N</code>.
The first argument is the prime <code>p</code>.

<example>
/**/ valuation(5,10);
1
</example>
    </description>

    <seealso>
      <see>IsDivisible</see>
    </seealso>

    <types>
      <type>INT</type>
    </types>

    <keys>
      <key>p-adic</key>
      <key>divisible</key>
    </keys>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>VersionInfo</title>
    <short_description>version and info about CoCoA</short_description>
    <description>
This function returns a record with various information about CoCoA 
and CoCoALib (the mathematical core of CoCoA)

<example>
/**/ indent(VersionInfo());
Record[
  CoCoALibVersion := "0.9951",
  CoCoAVersion := "5.0.3", ...
</example>
    </description>

    <syntax>
VersionInfo(): RECORD
</syntax>

    <seealso>
      <see>CoCoAManVersion</see>
    </seealso>

    <types>
      <type>RECORD</type>
      <type>STRING</type>
    </types>

    <keys>
      <key>versioninfos</key>
      <key>cocoainfos</key>
    </keys>

  </command>

 </chapter_letter>
 <!-- ===  CHAPTER  =============================================== -->
 <chapter_letter>
   <title>W</title>

<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>wdeg</title>
    <short_description>multi-degree of an polynomial</short_description>

    <description>
This function returns the multi-weighted degree of F, as determined by the
matrix weights of the polynomial ring of F.  The function <ttref>deg</ttref>
returns the standard degree.
<par/>
NB: In CoCoA-4 <ttref>deg</ttref> gave the weight
given by only the first row of the weights matrix.

<example>
/**/  M := matrix([[2,3,4], [1,0,2], [1,0,0]]);
/**/  P := NewPolyRing(QQ, ["x","y","z"], M, 1);  -- GradingDim=1
/**/  Use P;
/**/  wdeg(x*y^2+y);
[8]
/**/  P := NewPolyRing(QQ, ["x","y","z"], M, 2);  -- GradingDim=2
/**/  Use P;
/**/  wdeg(x*y^2+y);
[8, 1]
/**/  deg(x*y^2+y);
3

/**/  P4 := NewFreeModule(P,4); -- the default module ordering is TOPos
/**/  wdeg(ModuleElem(P4, [0, x, y^2, x^2]));
[6, 0]

/**/  LT(ModuleElem(P4, [0, x, y^2, x^2]));
[0, 0, y^2, 0]
</example>
    </description>

    <syntax>
WDeg(F:RINGELEM):LIST
</syntax>

    <seealso>
      <see>deg</see>
      <see>LF</see>
      <see>Weights Modifier</see>
    </seealso>

    <types>
      <type>RINGELEM</type>
      <type>ring</type>
    </types>

  </command>
<!-- ===  COMMAND-rm WeightsList  ===================================== -->
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>WeightsMatrix</title>
    <short_description>matrix of generalized weights for indeterminates</short_description>

    <description>
This function returns the weights matrix for the current ring.

<example>
/**/  OrdM := CompleteToOrd(RowMat([2,3]));
/**/  P := NewPolyRing(QQ, ["x","y"], OrdM, 1);
/**/  Use P;
/**/  WeightsMatrix(P);
matrix([
  [2, 3]
])

/**/ deg(x*y);
2
/**/ wdeg(x*y);
[5]
</example>
    </description>
    <syntax>
WeightsMatrix(R:RING):MAT
</syntax>

    <seealso>
      <see>deg</see>
      <see>wdeg</see>
    </seealso>

    <types>
      <type>RING</type>
      <type>MAT</type>
    </types>

    <keys> 
      <key>WeightsList</key>
    </keys>

  </command>
<!-- ===  COMMAND  =============================================== -->
<command>
  <title>while</title>
  <short_description>loop command</short_description>
    
<syntax>
While B Do C EndWhile

where B is a boolean expression and C is a sequence of commands.
</syntax>

<description>
The command sequence C is repeated until B evaluates to False.

<example>
/**/  N := 0;
/**/  while N &lt;= 5 do
        PrintLn 2, "^", N, " = ", 2^N;
        N := N+1;
      EndWhile;
2^0 = 1
2^1 = 2
2^2 = 4
2^3 = 8
2^4 = 16
2^5 = 32
</example>
</description>

<seealso>
  <see>for</see>
  <see>foreach</see>
  <see>repeat</see>
</seealso>

<types>
  <type>command</type>
  <type>programming</type>
  <type>loops</type>
</types>

</command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>WithoutNth</title>
    <short_description>removes the N-th component from a list</short_description>

    <syntax>
WithoutNth(L:LIST, N:INT):LIST
</syntax>

    <description>
This function returns the list obtained by removing the <tt>N</tt>-th component
of the list <tt>L</tt>.  The list <tt>L</tt> itself is not changed; compare with
<ttref>remove</ttref>.

<example>
/**/  L := [1,2,3,4,5];
/**/  WithoutNth(L,3);
[1, 2, 4, 5]
</example>
    </description>

    <seealso>
      <see>insert</see>
      <see>remove</see>
    </seealso>

    <types>
      <type>list</type>
    </types>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>WLog</title>
    <short_description>weighted list of exponents</short_description>

    <description>
This function returns the weighted list of exponents of the leading
term of F, as determined by the first row of the weights matrix.
Thus, if all the weights are 1, this function returns the same thing
as <tt>Log(F)</tt>.
--***OBSOLETE MANUAL: WORK IN PROGRESS***

<example>
  Use R ::= QQ[x,y];
  F := x^2-y;
  WLog(F);
[2, 0]
-------------------------------
  Use R ::= QQ[x,y], Weights(2,3);
  F := x^2-y;
  WLog(F);
[4, 0]
-------------------------------
</example>
    </description>

    <syntax>
WLog(F:POLY):LIST of INT
</syntax>

    <seealso>
      <see>log</see>
    </seealso>

    <types>
      <type>polynomial</type>
    </types>

  </command>

 </chapter_letter>
 <!-- ===  CHAPTER  =============================================== -->
 <chapter_letter>
   <title>X</title>

<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>XelMat</title>
    <short_description>matrices for std. term-orderings</short_description>

    <description>
This function return the matrix defining a standard term-ordering.

<example>
/**/  XelMat(3);
matrix([
  [0, 0, 1],
  [0, 1, 0],
  [1, 0, 0]
])
</example>
    </description>

    <syntax>
XelMat(N:INTEGER):MAT
</syntax>

    <seealso>
      <see>OrdMat</see>
      <see>Orderings</see>
      <see>StdDegRevLexMat</see>
      <see>StdDegLexMat</see>
      <see>LexMat</see>
      <see>RevLexMat</see>
    </seealso>

    <types>
      <type>matrix</type>
    </types>

  </command>

 </chapter_letter>
 <!-- ===  CHAPTER  =============================================== -->
 <chapter_letter>
   <title>Z</title>

<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>zero</title>
    <short_description>zero of a ring</short_description>

    <description>
This function return the additive identity of a ring.
For when you want to force the integer <tt>0</tt> to be a
<tt>RINGELEM</tt>.
<example>
/**/ P ::= ZZ/(101)[x,y,z];

/**/ N := 0;  Print N, " of type ",  type(N);
0 of type INT
/**/ N := zero(P);  Print N, " of type ",  type(N);
0 of type RINGELEM
/**/ N := 300*0;  Print N, " of type ",  type(N);
0 of type INT
/**/ N := 300*zero(P);  Print N, " of type ",  type(N);
0 of type RINGELEM

/**/  F := NewFreeModule(P, 3);
/**/  zero(F);
[0, 0, 0]
</example>
    </description>

    <syntax>
zero(R:RING):RINGELEM
</syntax>

    <seealso>
      <see>one</see>
      <see>IsZero</see>
    </seealso>

    <types>
      <type>ring</type>
      <type>ringelem</type>
    </types>

    <keys>
      <key>cast</key>
      <key>convert</key>
      <key>NewVector</key>
    </keys>

  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>ZPQ</title>
    <short_description>change field for polynomials and ideals</short_description>

    <description>
***** NOT YET IMPLEMENTED *****
<par/>
The function <tt>ZPQ</tt> maps a polynomial with finite field coefficients
into one with rational (actually, integer) coefficients.  It is not
uniquely defined mathematically, and currently for each coefficient
the least non-negative equivalent integer is chosen.
Users should not rely on this choice, though any change will be
documented.
<par/>
See <ttref>QZP</ttref> for more details.

<example>
  Use R ::= QQ[x,y,z];
  F := 1/2*x^3 + 34/567*x*y*z - 890; -- a poly with rational coefficients
  Use S ::= ZZ/(101)[x,y,z];
  QZP(F);                            -- compute its image with coeffs in ZZ/(101)
-50x^3 - 19xyz + 19
-------------------------------
  G := It;
  Use R;
  ZPQ(G);     -- now map that result back to QQ[x,y,z] it is NOT the same as F...
51x^3 + 82xyz + 19
-------------------------------
</example>
    </description>

    <syntax>
ZPQ(F:POLY):POLY
ZPQ(F:LIST of POLY):LIST of POLY
ZPQ(I:IDEAL):IDEAL
</syntax>

    <seealso>
      <see>Accessing Other Rings</see>
      <see>BringIn</see>
      <see>image</see>
      <see>Ring Mappings: the Image Function</see>
    </seealso>

    <types>
      <type>ideal</type>
      <type>polynomial</type>
      <type>ring</type>
    </types>

    <keys>
    <key>change ring</key>
    <key>abbott</key>
    </keys>
  </command>
<!-- ===  COMMAND  =============================================== -->
  <command>
    <title>ZZ</title>
    <short_description>the ring of integers</short_description>

    <description>
This variable returns the ring of integers.
Its name is protected so that it cannot be re-assigned to any other value.

<example>
/**/ P ::= ZZ/(101)[x,y,z];

/**/ Use ZZ;

/**/ type(5);
INT
/**/ type(RingElem(ZZ, 5));
RINGELEM
</example>
    </description>

    <syntax>
ZZ
</syntax>

    <seealso>
      <see>QQ</see>
    </seealso>

    <types>
      <type>ring</type>
    </types>

    <keys>
    </keys>

  </command>



 </chapter_letter>

</cocoa_commands>



<!-- *************************** -->
<!-- LIST OF PARTS OF THE MANUAL -->
<!-- *************************** -->
<manual_parts>
  <part>
    <title></title>
<!-- ===  CHAPTER  =============================================== -->
    <chapter>
      <title>Preamble</title>
<!-- ===  SECTION  =============================================== -->
      <section>
        <title>CoCoAManVersion</title>
        <type>1</type>

        <description>
        <verbatim>
-------------------------------------------------------
--   Online Help : CoCoA <cocoa_version/>                       --
--          date : <cocoa_date/>                       --
-------------------------------------------------------
        </verbatim>
    </description>

    <seealso>
      <see>VersionInfo</see>
    </seealso>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Preface</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
CoCoA is a system for doing <em>Computations in Commutative Algebra.</em>
It is one of the projects of an active research team in Computer
Algebra at the University of Genova, Italy, and whose current members are:
Lorenzo Robbiano (team manager), John Abbott, Anna Bigatti, Massimo Caboara,
Martin Kreuzer, David Perkinson, Michael Abshoff, Karsten Hiddeman,
and occasionally other researchers and students.
Notable contributions from outside the team have been received
from Volker Augustin, Arndt Wills, Stefan Kaspar.
Much of the original code for CoCoA was written by Gianfranco Niesi
and Antonio Capani.
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>System Distribution</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
CoCoA is public domain software, available at
  <tt>http://cocoa.dima.unige.it</tt>
where there is also a great deal of information about the system.
From there you can access to the CoCoAForum and the CoCoAWiki,
or directly at
<verbatim>
  http://www.apcocoa.org/forum/index.php
  http://www.apcocoa.org/wiki/Main_Page
</verbatim>

Besides the main site in Genoa, Italy, there is a mirror of the
official distribution: USA, West Coast
 <tt>http://www.reed.edu/cocoa</tt>
<par/>
CoCoA is distributed freely under the following condition: any
research activity which uses CoCoA should cite the system in the
following form:
<verbatim>
  CoCoATeam
  CoCoA, a system for doing Computations in Commutative Algebra,
  Available at http://cocoa.dima.unige.it
</verbatim>
  (see also <tt>http://cocoa.dima.unige.it/citing.html</tt>)
<par/>
The system can be freely redistributed to other users. New users
should notify the CoCoA team at the email address below so they can be
included in a users list. All members of this list will be kept up to
date about the progress of the system.
<par/>
The system is distributed <em>as is</em>.  The authors make no guarantee
about the fitness of the system for any particular application. They
will not be liable for any direct, indirect, special, incidental or
consequential damages in connection with the use of the system or of
the manual.
<par/>
Bug reports, questions, and suggestions should be sent to the
following email address:
<par/>
              cocoa (at) dima.unige.it
<par/>
Comments on the online help system would be greatly appreciated.  They
may be sent to the above address or to davidp (at) reed.edu.
    </description>

      <keys>
        <key>contact</key>
        <key>email</key>
        <key>forum</key>
        <key>http</key>
        <key>website</key>
        <key>wikipedia</key>
        <key>www</key>
      </keys>
      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>System Requirements</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
CoCoA runs on most common platforms.  Please visit the CoCoA
web site to see whether it is available for the platform you wish
to use.  If the version you seek is absent let us know, and we will
try to rectify the situation.
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Copyright and Trademarks</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
The product names mentioned in this manual are trademarks or
registered trademarks of their manufacturers.
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Acknowledgments</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
The CoCoA project is partly supported by:
<par/>
  * Department of Mathematics, University of Genova
<par/>
  * Department of Computer Science, University of Genova
<par/>
  * Consiglio Nazionale delle Ricerche
<par/>
  * Ministero dell&apos;Universita` e della Ricerca Scientifica e Tecnologica
<par/>
The author of the online help package would like to thank Tony
Geramita, Lorenzo Robbiano and the CoCoA team.  Thanks to Antonio
Capani and Gianfranco Niesi for patiently answering my questions and
for allowing me to use their <em>CoCoA User&apos;s Manual, version 3.0b
Draft,</em> from which the online help package borrows, sometimes
verbatim.
    </description>

      </section>

    </chapter>

  </part>
  <part>
    <title>Introduction to CoCoA</title>
<!-- ===  CHAPTER  =============================================== -->
    <chapter>
      <title>The CoCoA System</title>
<!-- ===  SECTION  =============================================== -->
      <section>
        <title>An Overview of the System</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
CoCoA is a computer algebra system for doing <em>Computations in
Commutative Algebra</em>.  Since its first version CoCoA has been designed
to offer maximum ease of use and flexibility to the mathematician with
little or no knowledge of computers.  It is able to perform simple and
sophisticated operations on multivariate polynomial rings and on
various data connected with them (ideals, modules, matrices, rational
functions).
<par/>
The system is capable of performing basic operations such as
<verbatim>
    * sums, products, powers, derivatives, gcd, lcm of polynomials;
    * sums, products, powers, derivatives  of rational functions;
    * sums, products, powers of ideals;
    * sums  of modules;
    * sums, products, powers, determinants, adjoints of matrices;
    * operations between heterogeneous values, like the product
      between an ideal and a polynomial, etc.
</verbatim>
Besides these, more advanced operations are available. For example:
<verbatim>
    * Groebner bases of ideals and modules;
    * syzygies of ideals and modules;
    * minimal free resolutions of ideals and modules;
    * intersection and division of ideals and modules;
    * inclusion and equality test for ideals and modules;
    * elimination of indeterminates;
    * homogenization of ideals;
    * Poincare series and Hilbert functions;
    * factorization of polynomials;
    * saturation of toric ideals.
</verbatim>
Every computation is performed within a <em>current</em> or <em>active</em>
ring, but the user can easily define and switch between many rings in
a single CoCoA session.
<par/>
CoCoA includes an extensive Pascal-like programming language, CoCoALanguage,
that allows the user to customize the system and extend the embedded
library.
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>System Structure</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
CoCoA is written in C language and is available on several platforms.
The core of the system is an implementation of Buchberger&apos;s algorithm
for computing Groebner bases of ideals and modules over a polynomial
ring whose coefficient ring is a field, and a variation of it for
computing syzygies. The algorithm has been optimized in several
directions and is used as a building block for many operations. Most
users can, however, completely ignore the theory of Groebner bases and
even their existence: CoCoA will do all the necessary <em>Groebner
stuff</em> in the background. However, for optimum use of the system some
knowledge of the theory is helpful.
<par/>
The system interacts with the external world using a Low Level
Protocol (LLP) that is independent of any machine architecture.  High
level inputs from the user are translated into LLP-requests to the
CoCoA kernel.  The LLP-answers are then translated back into high
level, user-readable outputs.
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Contributions</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
Important parts of the system have been developed by:
<verbatim>
         John Abbott : factorization, linear algebra, points, mainteiner
        Anna Bigatti : Hilbert-Poincare series, toric ideals, help system
     David Perkinson : help system
    Karsten Hiddeman : help system
     Volker Augustin : GUI (QT graphical user interface)
Alessandro Polverini : GUI
        Fabian Theis : GUI
     Michael Abshoff : GUI
     Massimo Caboara : operations on ideals
</verbatim>
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>CoCoA and Macaulay</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
Most of the standard scripts from the computer algebra system
Macaulay (Classic) have been translated into CoCoALanguage.  For
information, see

  <tt>http://www.matha.mathematik.uni-dortmund.de/~kreuzer/projects.html</tt>
    </description>

	<seealso>
	  <see>StarPrint, StarSprint</see>
    </seealso>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Pointers to the Literature</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
The following are articles which may be of interest to CoCoA users.
Many of the algorithms discussed in these articles have been
implemented in CoCoA.
<par/>
J. Abbott, <em>Univariate factorization over the integers,</em>  Preprint (1998).
<par/>
A.M. Bigatti, <em>Computations of Hilbert-Poincare Series,</em> J. Pure
Appl. Algebra, 119/3, 237--253 (1997).
<par/>
A.M. Bigatti, A. Capani, G. Niesi, L. Robbiano, <em>Hilbert-Poincare
Series and Elimination Problems,</em> Preprint (1998).
<par/>
A.M. Bigatti, R. La Scala, L. Robbiano, <em>Computing Toric Ideals,</em>
Preprint (1998).
<par/>
A.M. Bigatti, L. Robbiano, <em>Borel Sets and Sectional Matrices,</em>
Annals of Combinatorics, 1, 197--213, (1997)
<par/>
M. Caboara, P. Conti, and C. Traverso, <em>Yet Another Ideal
Decomposition Algorithm,</em> AAECC-12, Springer LNCS 1255, 39--54,
(1997).
<par/>
M. Caboara, G. De Dominicis, L. Robbiano, <em>Multigraded Hilbert
Functions and Buchberger Algorithm,</em> In Proc. ISSAC`96, 72--78 (1996),
Y.N. Lakshman, editor, New York. ACM Press.
<par/>
A. Capani, G. De Dominicis, <em>Web Algebra,</em> In Proc. of WebNet
96. Association for the Advancement of Computing in Education (AACE)
Charlottesville, USA, (1996).
<par/>
A. Capani, G. De Dominicis, G. Niesi, L. Robbiano, <em>Computing Minimal
Finite Free Resolutions,</em> J. Pure Appl. Algebra, 117/118, 105--117,
(1997).
<par/>
A. Capani, G. Niesi, <em>The CoCoA 3 Framework for a Family of
Buchberger-like Algorithms,</em> In Groebner Bases and Applications
(Proc. of the Conf. 33 Years of Groebner Bases) , London
Math. Soc. Lecture Notes Series, Vol. 251, B. Buchberger and
F. Winkler eds., Cambridge University Press, p. 338--350, (1998).
<par/>
A. Capani, G. Niesi, <em>CoCoA 3.0 User&apos;s Manual,</em> (1995).
<par/>
A. Capani, G. Niesi, L. Robbiano, <em>Some Features of CoCoA 3,</em>
Comput. Sci. J. of Moldova 4, 296--314, (1996).
<par/>
A. Giovini, T. Mora, G. Niesi, L. Robbiano, C. Traverso, <em>`One sugar
cube, please' or selection strategies in the Buchberger algorithm,</em> In
Proc. ISSAC`91, 49--54, Stephen M. Watt, editor, New York, ACM
Press, (1991).
<par/>
A. Giovini and G. Niesi, <em>CoCoA: a user-friendly system for commutative
algebra,</em>  In Design and Implementation of Symbolic Computation
Systems -- International Symposium DISCO`90, Lecture Notes in
Comput. Sci., 429, 20--29, Berlin, Springer Verlag, (1990).
<par/>
B. Sturmfels, <em>Groebner Bases and Convex Polytopes</em>, AMS University
Lecture Series, Vol. 8 (1995).
<par/>
SOME BOOKS AND ARTICLES MENTIONING CoCoA:
W. W. Adams, P. Loustaunau, <em>An Introduction to Groebner Bases,</em>
Graduate Studies in Mathematics, AMS, Providence, R.I. (1994).
<par/>
D. Cox, J. Little, D. O&apos;shea, <em>Ideals, Varieties, and Algorithms,</em>
Springer-Verlag, New York (1992).
<par/>
M. Kreuzer, L. Robbiano, <em>Computational Commutative Algebra 1</em>
Springer-Verlag, (2000).
<par/>
L. Robbiano, <em>Groebner Bases and Statistics,</em> in <em>Groebner Bases
and Applications,</em> (Proceedings of the Conference: 33 Years of
Groebner Bases), LMS Lecture Note Series, Vol. 251, B. Buchberger and
F. Winkler eds., Cambridge University Press, p. 79--204 (1998).
    </description>

      </section>

    </chapter>

<!-- ===  CHAPTER  =============================================== -->
    <chapter>
      <title>Tutorial</title>
<!-- ===  SECTION  =============================================== -->
      <section>
        <title>A Tutorial Introduction to CoCoA</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
This is an introduction to CoCoA, mainly through examples.  It is
just a small part of the online CoCoA manual.
<par/>
If you are using an HTML version of the manual just click on <em>next</em>!
The following few sections are for those who call the manual from
a CoCoA shell.
<par/>
To learn more about finding information in the manual, enter <tt>?</tt>
(without the quotes).  For now, the only essential command to know is
<tt>H.Browse()</tt>.  Entering <tt>H.Browse();</tt> or <tt>H.Browse(1);</tt> will display
the next section of the manual.  <tt>H.Browse(0);</tt> will redisplay the
current section, and <tt>H.Browse(-1);</tt> will display the previous
section.  Start browsing the tutorial now by entering <tt>H.Browse();</tt>.
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Setting Up CoCoA for the Tutorial</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
If you are using an HTML version of the manual skip this section.
<par/>
Some of the information from the online manual (and results of CoCoA
calculations, in general) may scroll off of the screen.  It is best to
run CoCoA from a system that has scrollable windows with enough
room to hold the output from each CoCoA command.
<par/>
Under X-windows, you might try running CoCoA from an xterm started
with the command <tt>xterm -sb -sl 512</tt> (scroll bar enabled,
saving 512 lines).  In addition, you may want to increase the vertical
size of your window, e.g., <tt>xterm -sb -sl 512 -geometry 80x40</tt>
under X-windows.  Better yet: run CoCoA from a shell
within Emacs.
<par/>
IF YOU DO NOT HAVE SCROLLABLE WINDOWS: enter the command
<tt>H.SetMore();</tt> to receive output 20 lines at a time.  As long as there
is output waiting to be printed, you will be prompted to enter
<tt>More();</tt> to get the next 20 lines.  You may type <tt>H.SetMore(N)</tt> in
order to get N lines at a time instead of 20.
<par/>
Enter <tt>H.Browse();</tt> to continue.  (The <tt>Browse</tt> command will be assumed
from now on.)
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Entering Commands</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
While reading the tutorial it is highly recommended that you have
a copy of CoCoA running in a separate window in order to play with the
examples presented.
<par/>
If you are using the CoCoA GUI (Graphical User Interface) then you
should follow the dedicated link <em>Graphical User Interface</em> for
entering commands.
<par/>
To execute a CoCoA command, type it into the window, ending it with a
semicolon, then press the <em>return</em> key or <em>enter</em> key (depending on
your system).  A command can run over several lines; CoCoA will wait
for a semicolon before processing the command.  Also, several commands
may be written on a single line (each ending with a semicolon).
<par/>
See the next section for examples.
<par/>
IMPORTANT NOTES for Macintosh OS 9 (up to version 4.0):
<par/>
1.  Only the <em>enter</em> key (on the far right of the keyboard is the one
to use) will function to enter CoCoA commands.  Experiment.
<par/>
2. To enter multiple lines, one needs to highlight the lines using the
mouse before hitting the <em>enter</em> key.  Otherwise, the enter key just
feeds the line containing the cursor to CoCoA.
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Examples of Entering Commands</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
Here are some examples of entering simple commands in CoCoA.
(Macintosh OS9 and GUI users please remember the special instructions
made in the previous section.)

<example>
  1+1;  -- a simple command
2
-------------------------------
  1  +   -- the same command spread over several lines

  1;
2
-------------------------------
  1+1; 2+2; 3+3;  -- several commands on a single line
2
-------------------------------
4
-------------------------------
6
-------------------------------
</example>

NOTE: The output above appears just as it does in my CoCoA window.
The examples in the online manual will often be annotated.  When CoCoA
encounters *double dashes*, as above, it regards the rest of the line
as a comment.
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>More on Entering Commands</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
One may save a sequence of commands in a file and read them into a
CoCoA session with the <ttref>source</ttref> command.
For instance, if a sequence of CoCoA commands is saved in the file
<tt>MySession</tt>, one may enter
<verbatim>
  Source <quotes>MySession</quotes>;
</verbatim>
to run the commands (give the full pathname, or store your file in the
cocoa directory).  User-defined functions are often stored in files
and sourced in this way.
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>After the Tutorial</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
Browsing through the examples in this tutorial may enable you to
solve your particular problems.  If not, or to learn more about CoCoA
in general, enter <tt>?</tt> to learn more about CoCoA&apos;s online help.  For
example, you will see that <tt>H.Command(<quotes></quotes>)</tt> gives a long annotated
list of CoCoA commands, and <tt>?keyword</tt> will look for information about
<em>keyword</em> in the manual.
<par/>
The GUI Help System (html) and the printable/browsable version (pdf)
contain exactly the same information as the online help.
You may choose your preferred format or exploit the different
searching methods suiting best your need.
<par/>
With the following section, the tutorial proper begins.  To see a
table of contents for the tutorial, enter <tt>H.Toc(1,2)</tt>.  The command
<tt>H.Browse()</tt> will then continue with the tutorial, or you may give the
title of a tutorial section to <tt>?</tt> to skip to that section.
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Arithmetic</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
Here are some first examples; they illustrate CoCoA evaluating
arithmetic expressions.

<example>
  (2+3)(1+1);  -- multiplication, as usual
10
-------------------------------
  2^10;
1024
-------------------------------
  2+2/3;
8/3
-------------------------------
  1.5+2.3;  -- decimals are converted to fractions
19/5
-------------------------------
  mod(27,5);
2
-------------------------------
  2*3;
6
-------------------------------
  Fact(4);
24
-------------------------------
</example>
For multiplication, one may use <tt>*</tt>, parentheses, or just a space.
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Variables</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
Results from CoCoA calculations can be stored in variables.
Variables, like CoCoA functions, must begin with a capital letter or an
error will result.

<example>
  A := 3;
  2 * A;
6
-------------------------------
  b := 7;
ERROR: parse error in line 12 of device stdin
-------------------------------
7
-------------------------------
  B := 7;
  A^2 + B;
16
-------------------------------
</example>
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Making Lists</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
The following example illustrates the use of lists in CoCoA.

<example>
  L := [2, 3, "a string", [5,7], 3, 3]; -- L is now a list
  L[3];  -- here is the 3rd component of L
a string
-------------------------------
  L[4];  -- the 4th component of L is a list, itself
[5, 7]
-------------------------------
  L[4][2];  -- the 2nd component of the 4th component of L
7
-------------------------------
  L[4,2];  -- same as above
7
-------------------------------
  append(ref L,"new");
  L;
[2, 3, "a string", [5, 7], 3, 3, "new"]
-------------------------------
  -- insert 8 as the 4th component of L, shifting the other
  -- entries to the right:
  Insert(L,4,8);
  L;
[2, 3, "a string", 8, [5, 7], 3, 3, "new"]
-------------------------------
  Remove(L,4);  -- remove it again
  L;
[2, 3, "a string", [5, 7], 3, 3, "new"]
-------------------------------
  len(L);  -- the number of components of L
7
-------------------------------
  MakeSet(L);  -- same as L but with repeats removed
[2, 3, "a string", [5, 7], "new"]
-------------------------------
  1..5;  -- a range of values
[1, 2, 3, 4, 5]
-------------------------------
  [ X^2 | X In 1..5];  -- a useful way to make lists
[1, 4, 9, 16, 25]
-------------------------------
  [1,2] &gt;&lt; [3,4] &gt;&lt; [5];  -- Cartesian product: use a greater-than
                    -- sign "&gt;" and a less-than sign "&lt;" to make
                    -- the operator "&gt;&lt;"
[[1, 3, 5], [1, 4, 5], [2, 3, 5], [2, 4, 5]]
-------------------------------
</example>
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Setting Up a Ring</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
A CoCoA session automatically starts with the default ring, R =
QQ[x,y,z].  The command <ttref>Use</ttref> is used to change rings.  The following
example shows how to create the ring ZZ/(5)[a,b,c] (the coefficient
ring is the integers mod 5).  Once the ring has been declared, one may
start to play with polynomials, ideals, modules, and other
constructions in that ring.  In the ring declaration, the
indeterminates are optionally separated by commas, and note the use of
two colons.
<par/>
Some details on handling several rings is provided below in the
section of the Tutorial entitled <ref>Using More Than One Ring</ref>
and <ref>Ring Mapping Example</ref>.

<example>
  Use S ::= ZZ/(5)[a,b,c];
  F := a-b;
  I := ideal(F^2,c);
  I;
ideal(a^2 - 2ab + b^2, c)
-------------------------------
  J := ideal(a-b);
  I + J;
ideal(a^2 - 2ab + b^2, c, a - b)
-------------------------------
  Minimalized(It);  -- find a minimal set of generators for I+J
ideal(a - b, c)
-------------------------------
</example>
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>A Groebner Basis Example</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
A Groebner basis of an ideal I is calculated with the command
<tt>GBasis(I)</tt>, as illustrated in the following example.
<par/>
Let <formula>r</formula> be a root of the equation <formula>x^7-x-1</formula> over the rationals.  The
minimal polynomial of <formula>(4r-1)/r^3</formula> can be found by computing the reduced
Groebner basis of the ideal <formula>(x^7-x-1, x^3y-4x+1)</formula> with respect to the
lexicographic term-ordering with <formula>x&gt;y</formula>.

<example>
  Use R ::= QQ[x,y], Lex;
  Set Indentation;  -- to improve the appearance of the output
  G := GBasis(ideal(x^7-x-1, x^3y-4x+1));
  G;

[ 1602818757152090759440/34524608236181199361x - 4457540/5875764481y^7
  - 47746460716124220/34524608236181199361y^6 +
  890175715271333840/34524608236181199361y^5 -
  3541992534667352220/34524608236181199361y^4 -
  55943894513139464160/34524608236181199361y^3 -
  56473654361333280980/34524608236181199361y^2 -
  27971979712025453040/34524608236181199361y -
  400704689288022689860/34524608236181199361, 1/16384y^7 - 5/16384y^6
  + 147/16384y^4 + 5/128y^3 - 31/16384y^2 + 17/128y - 20479/16384]
-------------------------------
  len(G);
2
-------------------------------
  F := 16384*G[2];  -- clear denominators
  F;
y^7 - 5y^6 + 147y^4 + 640y^3 - 31y^2 + 2176y - 20479
-------------------------------
</example>

The Groebner basis is reported as a list with two elements.  The
second gives a univariate polynomial which is the minimal polynomial
for <formula>r</formula>.
<par/>
Note that the statement declaring the ring includes the modifier,
<tt>Lex</tt>.  Without this modifier, the default term-ordering, DegRevLex,
is used.  The command <tt>Set Indentation</tt> forces each polynomial of the
Groebner basis to be printed on a new line.
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Eliminating Variables</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
The Cartesian equations of the space curve parametrized by
  <formula>t --&gt; 
(t<sup>31</sup>+t<sup>6</sup>, t<sup>8</sup>, t<sup>10</sup>)</formula>
<par/>
can be found by eliminating the indeterminate t in the ideal
<formula>
(t<sup>31</sup>+t<sup>6</sup>-x, t<sup>8</sup>-y, t<sup>10</sup>-z)
</formula>

<example>
  Use R ::= QQ[t,x,y,z];
  Set Indentation;
  Elim(t, ideal(t^31+t^6-x, t^8-y, t^10-z));
ideal(
  y^5 - z^4,
  -y^4z^5 + y^4 - 2xy^2z + x^2z^2,
  -z^8 - 2xy^3 + x^2yz + z^3,
  2xy^4z^4 + yz^7 + 3x^2y^2 - 2x^3z - yz^2,
  -y^2z^6 - 1/2xz^7 + 1/2x^3y + y^2z - 3/2xz^2,
  -1/3x^2y^4z^3 - y^3z^5 - 2/3xyz^6 + 1/3x^4 + y^3 - 4/3xyz)
-------------------------------
</example>

With the command <ttref>elim</ttref>, CoCoA automatically switches to a
term-ordering suitable for eliminating the variable <formula>t</formula>, then changes
back to the declared term-ordering (in this case the default
term-ordering, DegRevLex).
<par/>
One may see the entire Groebner basis for our ideal with respect to
the elimination term-ordering for <formula>t</formula> as follows:

<example>
  Use R ::= QQ[t,x,y,z], Elim(t);
  Set Indentation;
  GBasis(ideal(t^31+t^6-x, t^8-y, t^10-z));
[
  -t^2y + z,
  y^5 - z^4,
  -t^6 - tz^3 + x,
  -tz^4 - y^2 + xz,
  -ty^2 + txz - y^4z,
  -y^4z^5 + y^4 - 2xy^2z + x^2z^2,
  -z^8 - 2xy^3 + x^2yz + z^3,
  2xy^4z^4 + yz^7 + 3x^2y^2 - 2x^3z - yz^2,
  tx^2y - tz^2 - y^2z^3 - xz^4,
  2txyz^3 - z^7 - x^2y + z^2,
  -y^2z^6 - 1/2xz^7 + 1/2x^3y + y^2z - 3/2xz^2,
  t^2x - tx^2z^2 + xy^4z^2 + yz^5 - y,
  t^2z + 2txz^3 - y^4z^3 - x^2,
  -3tx^2z^3 + 2xy^4z^3 + yz^6 + x^3 - yz,
  -1/3x^2y^4z^3 - y^3z^5 - 2/3xyz^6 + 1/3x^4 + y^3 - 4/3xyz,
  1/3tx^3 - 1/3tyz - 1/3x^2y^4 - 1/3y^3z^2 - 1/3xyz^3]
-------------------------------
</example>
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Using More Than One Ring</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
In CoCoA, every calculation takes place in a <em>current</em> or
<em>active</em> ring.  Ring-dependent objects defined by the user such as
polynomials, ideals, and modules are automatically labeled by the
current ring.  Objects that do not depend essentially on the ring,
e.g., lists or matrices of integers, do not get labeled.
<par/>
CoCoA automatically starts with the ring R = QQ[x,y,z].  The
following example illustrates setting up a ring with the construction
<tt>::=</tt> and changing rings with the command <ttref>Use</ttref>.  One may temporarily
change rings with the command <ttref>Using</ttref>.  The example assumes that you
do not already have a ring with identifier <tt>S</tt>.

<example>
  Use R ::= QQ[x,y];  -- declare and use a ring R
  F := (x+y)^3;
  F;
x^3 + 3x^2y + 3xy^2 + y^3
-------------------------------
  M := [1,"test",2];
  S ::= QQ[x,y,z,a,b];   -- declare a ring S with indeterminates x,y,z,a,b
  Use S;            -- switch to the ring S
  F;  -- F is labeled by ring R
R :: x^3 + 3x^2y + 3xy^2 + y^3
-------------------------------
  M;  -- this list is not labeled R since its elements are not
      -- ring dependent (e.g., "1" is considered a separate integer, not
      -- part of the ring R)
[1, "test", 2]
-------------------------------
  F := ideal(a^2+b^2);  -- change the definition of F
  Use R;  -- switch back to R
  F;   -- the old F no longer exists
S :: ideal(a^2 + b^2)
-------------------------------
  GBasis(F);  -- built in functions automatically recognize the ring
[S :: a^2 + b^2]
-------------------------------
</example>
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Substitutions</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
To substitute a list of numbers or polynomials for the indeterminates
(in the order specified by the definition of the ring), one may use
the function <ttref>eval</ttref>.  To substitute out of order, use the function
<ttref>subst</ttref>.

<example>
  Use R ::= QQ[x,y,z];
  F := x^2+y^2+z^2;
  Eval(F,[1]);  -- substitute x=1
y^2 + z^2 + 1
-------------------------------
  Eval(F, [1,2,3]);  -- substitute x=1, y=2, z=3
14
-------------------------------
  type(It); -- [1,2,3] has NumIndets() rational components
RAT
-------------------------------
  Subst(F, y, 2);  -- substitute y=2
x^2 + z^2 + 4
-------------------------------
  Eval(F, [x,2,z]); -- same as above
x^2 + z^2 + 4
-------------------------------
  Subst(F, [[y,y^2],[z,z^2]]);  -- substitute y^2 for y, z^2 for z
y^4 + z^4 + x^2
-------------------------------
  Eval(ideal(F), [x^2,z]); -- substitute x^2 for x, z for y
ideal(x^4 + 2z^2)
-------------------------------
</example>
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>First Functions</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
CoCoA&apos;s gamut of functions can be easily extended with user-defined
functions.  Longer functions are usually cut-and-pasted from a text
editor into a CoCoA session.  If the functions are to be used
repeatedly, they can be saved in a separate text file and read into a
CoCoA session with the <ttref>source</ttref> command. The usual way to
define a function is with the syntax:
<verbatim>
   Define &lt; FunctionName &gt;(&lt; argument list &gt;) &lt; Commands &gt; EndDefine;
</verbatim>
NOTE: Variables defined within a function are usually local to that
function and disappear after the function returns.  Normally, the only
variables accessible within a function are the function&apos;s arguments
and local variables.  (For the exceptions, see the section of the
manual entitled <ref>Global Memory</ref>.)

<example>
  Define square(X)   -- a simple function
    Return X^2;
  EndDefine;
  square(3);
9
-------------------------------
  Define IsPrime(X)  -- a more complicated function
    If type(X) &lt;&gt; INT Then Return Error("Expected INT") EndIf;
    I := 2;
    While I^2 &lt;= X Do
      If mod(X, I) = 0 Then Return False EndIf;
      I := I+1;
    EndWhile;
    Return True;
  EndDefine; -- end of function definition
  IsPrime(4);
False
-------------------------------
  Define Test(A, B)  -- a function with two arguments
    Sum := A+B;
    Prod := A*B;
    PrintLn "The sum of ", A," and ", B," is ", Sum,".";
    Print "The product of ", A," and ", B," is ", Prod,".";
  EndDefine;
  Test(3,5);
The sum of 3 and 5 is 8.
The product of 3 and 5 is 15.
-------------------------------
</example>
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>More First Functions</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
A user-defined function can have any number of parameters of any
type, even a variable number of parameters.  Note that even a function
with no parameters must be called with parentheses.

<example>
  Define Test1()
    PrintLn "This is a function with no parameters.";
    For I := 1 To 10 Do
      Print I^2, " ";
    EndFor;
  EndDefine;
  Test1();
This is a function with no parameters.
1 4 9 16 25 36 49 64 81 100
-------------------------------
  Define Test2(...)  -- a variable number of parameters
    If len(ARGV) = 0 Then -- parameters are stored in the list ARGV
      Return "Wrong number of parameters";
    Elif len(ARGV) = 1 Then
      Print "There is 1 parameter: ", ARGV[1];
    Else
      Print "There are ", len(ARGV), " parameters: ";
      Foreach P In ARGV Do
        Print P, " ";
      EndForeach;
    EndIf;
  EndDefine;
  Test2(1, 2, "string",3);
There are 4 parameters: 1 2 string 3
-------------------------------
</example>
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Rings Inside User-Defined Functions</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
As mentioned earlier, user-defined functions cannot reference
(non-global) variables except those defined within the function or
passed as arguments.  However, functions can refer to rings via their
identifiers and use them as one would outside of a function.
<par/>
When a function is called, it assumes the current ring and performs
operations in that ring.  One may define new rings which will exist
after the function returns, but one may not change the current ring
with the command <ttref>Use</ttref>.
However, one may <em>temporarily</em> use a ring with the command <ttref>Using</ttref>.
<par/>
To make functions more portable, it may be useful to refer to the
current ring not by its name but by using the command <ttref>CurrentRing</ttref>.
<par/>
Example I.
<par/>
Test uses the existing rings, R, S, and creates a new ring T.
While a (non-global) <em>variable</em> defined in a function will
automatically disappear, a ring (and its name) will not.

<example>
  Use R ::= QQ[x,y,z];
  S ::= QQ[a,b];
  Define Test()
    PrintLn (x+y)^2;
    PrintLn S :: (a+b)^3;
    T ::= ZZ/(5)[t];
    I := T :: ideal(t^2);
    Print I;
  EndDefine;
  Test();
x^2 + 2xy + y^2
S :: a^3 + 3a^2b + 3ab^2 + b^3
T :: ideal(t^2)
-------------------------------
  I;  -- the variable I was local to the function
ERROR: Undefined variable I
CONTEXT: I
-------------------------------
  T;  -- The function created the ring T.  (Note: T is not a variable.)
ZZ/(5)[t]
-------------------------------
</example>

Example II
<par/>
The use of <ttref>CurrentRing</ttref> within a function.

<example>
  Define Poincare2(I)
    Return Poincare(CurrentRing()/I);
  EndDefine;
  Use R ::= QQ[x,y];
  Poincare2(ideal(x^2,y^2));
(1 + 2x + x^2)
-------------------------------
</example>

Example III
<par/>
Creating a ring with a user-supplied name.

<example>
  Define Create(Var(R));
    Var(R) ::= QQ[a,b];
  EndDefine;
  Create("K");
  K;
QQ[a,b]
-------------------------------
  Create("myring");
  Var("myring");
QQ[a,b]
-------------------------------
  Use Var("myring");  -- make myring current
</example>

Example IV
<par/>
A more complicated example, creating rings whose names are
automatically generated.  See <ttref>NewId</ttref> and <tt>Var</tt>
for more information.

<example>
  Define CreateRing(I)
    NewRingName := NewId();
    Var(NewRingName) ::= QQ[x[1..I]], Lex;
    Return NewRingName;
  EndDefine;

  Use R ::= QQ[x,y], DegRevLex;
  Use S ::= QQ[x,y,z], Lex;
  N := 5;
  For I := 1 To N Do
    RingName := CreateRing(I); -- RingName is a string
    Using Var(RingName) Do
      PrintLn Indets();
    EndUsing;
    -- Destroy Var(RingName); -- uncomment if you want to destroy the tmp ring
  EndFor;

[x[1]]
[x[1], x[2]]
[x[1], x[2], x[3]]
[x[1], x[2], x[3], x[4]]
[x[1], x[2], x[3], x[4], x[5]]

-------------------------------
</example>
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Rational Normal Curve</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
In this example, we compute the ideal of the rational normal curve of
degree <formula>N</formula> in <formula>P^N</formula> then compute its Poincare series for a range of values
of <formula>N</formula>.

<example>
  Define Minor2(M, I, J)
    Return M[1,I] M[2,J] - M[2,I] M[1,J];
  EndDefine;

  Define Rational_Normal_Curve_ideal(N)
    -- first define the 2xN matrix whose 2x2 minors generate the ideal
    M := NewMat(2, N);
    For C := 0 To N-1 Do
      M[1,C+1] := x[C];
      M[2,C+1] := x[C+1];
    EndFor;
    -- then construct the generators of the ideal
    L := [];
    For C1 := 1 To N-1 Do
      For C2 := C1+1 To N Do
        P := M[1,C1] M[2,C2] - M[2,C1] M[1,C2];
        -- determinant for columns C1,C2
        append(ref L, P)
      EndFor;
    EndFor;
    Return ideal(L);
  EndDefine;

  For N := 3 To 5 Do
    S ::= QQ[x[0..N]], Lex;
    PrintLn;
    PrintLn "degree ", N;
    Using S Do  -- switch, temporarily, to ring S
      I := Rational_Normal_Curve_ideal(N);
      Print "Poincare series: ", Poincare(S/I);
    EndUsing;
    PrintLn;
  EndFor; -- for statement

degree 3
Poincare series: (1 + 2x[0]) / (1-x[0])^2

degree 4
Poincare series: (1 + 3x[0]) / (1-x[0])^2

degree 5
Poincare series: (1 + 4x[0]) / (1-x[0])^2

-------------------------------
</example>
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Generic Minors</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
The following example computes the relations among the 2x2 minors of
a generic 2xN matrix for a range of values of N.  Note the use of
indeterminates with multiple indices.

<example>
  Define Minor2(M, I, J)
    Return M[1,I] M[2,J] - M[2,I] M[1,J];
  EndDefine;

  Define Det_Subalgebra(N)
    M := mat([[x[I,J] | J In 1..N] | I In 1..2]);
    Cols := (1..N) &gt;&lt; (1..N);
    L := [ y[C[1],C[2]] - Minor2(M, C[1], C[2]) | C In Cols And C[1] &lt; C[2] ];
    Return ideal(L);
  EndDefine;

  Define Det_Subalgebra_Print(N)  -- calculate and print relations
    J := Det_Subalgebra(N);
    PrintLn;
    PrintLn "N = ", N;
    PrintLn "Subalgebra equations:";
    PrintLn gens(Elim(x, J))
  EndDefine;
  
  Set Indentation;
  For N := 3 To 5 Do
    S ::= ZZ/(32003)[y[1..(N-1),2..N], x[1..2,1..N]];
    Using S Do
      Det_Subalgebra_Print(N);
    EndUsing;
  EndFor;

N = 3
Sub-algebra equations:
[
  0]

N = 4
Sub-algebra equations:
[
  2y[1,4]y[2,3] - 2y[1,3]y[2,4] + 2y[1,2]y[3,4]]

N = 5
Sub-algebra equations:
[
  2y[2,5]y[3,4] - 2y[2,4]y[3,5] + 2y[2,3]y[4,5],
  2y[1,5]y[3,4] - 2y[1,4]y[3,5] + 2y[1,3]y[4,5],
  2y[1,5]y[2,4] - 2y[1,4]y[2,5] + 2y[1,2]y[4,5],
  2y[1,5]y[2,3] - 2y[1,3]y[2,5] + 2y[1,2]y[3,5],
  2y[1,4]y[2,3] - 2y[1,3]y[2,4] + 2y[1,2]y[3,4]]

-------------------------------
</example>
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Leading Term (Initial) Ideals, Generic Polynomials</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
The following example produces the leading term (initial) ideal of
the ideal generated by three <em>generic</em> polynomials of degree 2 with
respect to the lexicographic term-ordering.

<example>
  Use R ::= ZZ/(32003)[x[1..4]], Lex;
  F := DensePoly(2);  -- sum of all power-products of degree 2
  L := [ Randomized(F) | I In 1..3 ]; -- randomize coefficients
  LT(ideal(L));
ideal(x[1]^2, x[1]x[2], x[1]x[3], x[2]^3, x[1]x[4]^2, x[2]^2x[3],
x[2]^2x[4]^2, x[2]x[3]^3, x[2]x[3]^2x[4]^2, x[2]x[3]x[4]^4,
x[2]x[4]^6, x[3]^8)
-------------------------------
</example>
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Ring Mapping Example</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
If R is the current ring and E is an object in another ring, then the
function <ttref>image</ttref> may be used to map E into R by substituting
polynomials from R for the indeterminates in E.  (Also: see the
command <ttref>BringIn</ttref> for a shortcut in certain cases.)

<example>
  Use S ::= QQ[a,b,c];
  I := ideal(a^2+b^2,ab-c^2);
  Use R ::= QQ[x,y];  -- the current ring is R
  F := RMap(x+y, x-y, y^2); -- define a map F:S --&gt; R sending a to x+y,
                            -- b to x-y, and c to y^2
  Image(I, F); -- the image of I under F
ideal(2x^2 + 2y^2, -y^4 + x^2 - y^2)
-------------------------------
</example>
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Output to a File</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
The following example illustrates one way of saving CoCoA output to a
file.

<example>
  Use R ::= QQ[t,x,y,z];
  I := ideal(t^2-x, t^5-y, t^7-z);
  G := GBasis(I);
  G;
[t^2 - x, -tx^2 + y, -x^3 + ty, -xy + z, -ty^2 + x^2z, txz - y^2, y^3 - tz^2]
-------------------------------
  D := OpenOFile("MyFile"); -- open "MyFile" for output from CoCoA
  Print G On D;  -- G is appended to the file "MyFile"
  Close(D);
</example>

Text can be read from files using <ttref>OpenIFile</ttref> and <ttref>Get</ttref>, and commands
can be executed from files using <ttref>source</ttref>.  One may also
keep a log of a CoCoA session (see <ttref>OpenLog</ttref>)
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Finite Point Sets: Buchberger-Moeller</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
CoCoA includes an implementation of the Buchberger-Moeller algorithm
for efficient computations dealing with finite sets of points.  These
functions include:
<par/>
  * GBM, HGBM -- intersection of ideals for zero-dimensional schemes
<par/>
  * IdealAndSeparatorsOfPoints -- ideal and separators for affine points
<par/>
  * IdealAndSeparatorsOfProjectivePoints -- ideal and separators for points
<par/>
  * IdealOfPoints -- ideal of a set of affine points
<par/>
  * IdealOfProjectivePoints -- ideal of a set of projective points
<par/>
  * Interpolate -- interpolating polynomial
<par/>
  * SeparatorsOfPoints -- separators for affine points
<par/>
  * SeparatorsOfProjectivePoints -- separators for projective points
<par/>
Details about these functions may be found individually in the online
manual.  Briefly, the functions above may be used to find the ideal of
a set of points in affine or projective space along with a reduced
Groebner basis and separators.  Separators are polynomials that take
the value 1 on one of the points and 0 on the remainder.  The
Buchberger-Moeller algorithm works <em>much</em> faster than the
straightforward technique involving intersecting ideals for the
individual points.

<example>
  Use R ::= QQ[t,x,y,z];
  Pts := GenericPoints(20);  -- 20 random points in projective 3-space
  X := IdealAndSeparatorsOfProjectivePoints(Pts);
  len(gens(X.ideal));  -- number of generators in the ideal
17
-------------------------------
  Hilbert(R/X.ideal);
H(0) = 1
H(1) = 4
H(2) = 10
H(t) = 20   for t &gt;= 3
-------------------------------
  F := X.separators[3];
  [Eval(F, P)| P In Pts];
[0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
-------------------------------
  Res(R/X.ideal);  -- the resolution of the ideal
0 --&gt; R^10(-6) --&gt; R^24(-5) --&gt; R^15(-4) --&gt; R
-------------------------------
</example>
    </description>

      <keys>
        <key>buchbergermoeller</key>
        <key>buchbergermoller</key>
      </keys>
      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Syzygies and Resolution Example</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
The following example, among other things, computes the resolution of
ideals of sets of points.

<example>
  Use R ::= QQ[x,y,z];
  X1 := [[0,0,1],[1,0,1],[2,0,1],[2,1,1]]; -- 4 points in the projective
                                           -- plane
  X2 := [[0,0,1],[1,0,1],[0,1,1],[1,1,1]]; -- 4 more points
  I1 := IdealOfProjectivePoints(X1);
  I2 := IdealOfProjectivePoints(X2);
  Hilbert(R/I1);  -- the Hilbert function of X1
H(0) = 1
H(1) = 3
H(x) = 4   for t &gt;= 2
-------------------------------
  Hilbert(R/I2) = Hilbert(R/I1);  -- The Hilbert functions for X1 and X2
                                  -- are the same
True
-------------------------------
  Res(R/I1);                      -- but the resolutions ...
0 --&gt; R(-3)(+)R(-4) --&gt; R(-2)^2(+)R(-3) --&gt; R
-------------------------------
  Res(R/I2);                      -- are different.
0 --&gt; R(-4) --&gt; R(-2)^2 --&gt; R
-------------------------------
  Describe Res(R/I1);  -- more information about the resolution for X1
mat([
  [xy - 2yz, y^2 - yz, x^3 - 3x^2z + 2xz^2]
])
mat([
  [y - z, x^2 - xz],
  [-x + 2z, 0],
  [0, -y]
])
-------------------------------
  Syz(I1,1);  -- the first syzygy module for X1
Module([y - z, -x + 2z, 0], [x^2 - xz, 0, -y])
-------------------------------
</example>
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Factoring Polynomials</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
CoCoA can factor a polynomial over its coefficient ring.

<example>
  Use R ::= QQ[x,y];
  F := x^12 - 37x^11 + 608x^10 - 5852x^9 + 36642x^8 - 156786x^7 + 468752x^6
      - 984128x^5 + 1437157x^4 - 1422337x^3 + 905880x^2 - 333900x + 54000;
  Factor(F);
[[x - 2, 1], [x - 4, 1], [x - 6, 1], [x - 3, 2], [x - 5, 3], [x - 1, 4]]
-------------------------------
  F := (x+y)^2*(x^2y+y^2x+3);
  F;
x^4y + 3x^3y^2 + 3x^2y^3 + xy^4 + 3x^2 + 6xy + 3y^2
-------------------------------
  Factor(F);  -- multivariate factorization
[[x^2y + xy^2 + 3, 1], [x + y, 2]]
-------------------------------
  Use ZZ/(37)[x];
  Factor(x^6-1);
[[x - 1, 1], [x + 1, 1], [x + 10, 1], [x + 11, 1], [x - 11, 1], [x - 10, 1]]
-------------------------------
</example>
    </description>

      </section>

    </chapter>

  </part>
  <part>
    <title>The CoCoA Programming Language</title>
<!-- ===  CHAPTER  =============================================== -->
    <chapter>
      <title>Introduction to CoCoA Programming</title>
<!-- ===  SECTION  =============================================== -->
      <section>
        <title>An Overview of CoCoA Programming</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
The CoCoA system includes a full-fledged high level programming
language, CoCoALanguage, complete with loops, branching, scoping of
variables, and input/output control.  The language is used whenever
one issues commands during a CoCoA session.  A sequence of commands
may be stored in a text file and then read into a CoCoA session using
the <ttref>source</ttref> command.
<par/>
The most important construct in CoCoA programming is the user-defined
function, created with <ttref>Define</ttref>.  A user-defined function can take any
number of arguments, of any types, perform CoCoA commands, and return
values.  Collections of these functions can be stored in text files,
as mentioned in the preceding paragraph, or formed into CoCoA
<em>packages</em>, to be made available for general use.
    </description>

      </section>

    </chapter>

<!-- ===  CHAPTER  =============================================== -->
    <chapter>
      <title>Language Elements</title>
<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Character Set and Special Symbols</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
The CoCoA character set consists of the 26 lower case letters, the 26
upper case letters, the 10 digits and the special characters listed in
the table below.  Note that the special character <tt>|</tt> looks a bit
different on some keyboards (its ASCII code is 124).

<verbatim>
    ------------------------------------------------------
   |    blank     _  underscore     (  left parenthesis   |
   | +  plus      =  equal          )  right parenthesis  |
   | -  minus     &lt;  less than      [  left bracket       |
   | *  asterisk  &lt;  greater than   [  right bracket      |
   | /  slash     |  vertical bar   &apos;  single quote       |
   | :  colon     .  period         <quotes>  </quotes>  double quote    |
   | ^  caret     ;  semicolon                            |
   | ,  comma     %  percent                              |
    ------------------------------------------------------
                  Special Characters
</verbatim>

The character-groups listed in the table below are special symbols in CoCoA

<verbatim>
    ----------------------------------------------------------
   | :=   assign                      ..   range              |
   | &lt;&lt;   input from                  //   start line comment |
   | &lt;&gt;   not equal                   --   start line comment |
   | &lt;=   less than or equal to       /*   start embedded comment|
   | &gt;=   greater than or equal to    */   end embedded comment  |
   | &gt;&lt;   Cartesian product           ::   ring casting       |
   | ::=  ring definition             ...  dots               |
    ----------------------------------------------------------
                     Special Character-groups
</verbatim>

    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Identifiers</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
There are two types of identifiers or names.
<par/>
  * Identifiers of ring indeterminates. They must begin with lower case
    letters.
<par/>
  * Predefined or user-defined names (functions and CoCoALanguage variables).
    They must begin with upper case letters.
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Names of Indeterminates</title>
        <type>2</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
Each indeterminate of a polynomial ring may have one of the following
forms:
<par/>
   * a single lower case letter;
   * a single lower case letter, indexed by one or more integer
     expressions, separated by commas, and enclosed by square
     brackets, e.g. x[1,3+5,2].
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Reserved Names</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
The names in the following tables are reserved and cannot be used
otherwise.  The names in the first table are case insensitive
(e.g. CLEAR, Clear and ClEaR are all reserved).  The names in the
second table are case sensitive.

<par/>...work in progress...

<verbatim>
     ----------------------------------------------------
    | Alias      And      Block       Ciao      Define   |
    | Describe   Do       Elif        Else      End      |
    | EndBlock   EndTry               EndDefine EndFor   |
    | EndForeach EndIf    EndPackage  EndRepeat EndUsing |
    | EndWhile   Eof      False       For       Foreach  |
    | Global     Help     If          In        IsIn     |
    | NewLine    Not      On          Or        Package  |
    | Print      PrintLn  Quit        Repeat    Record   |
    | Return     Set      Skip        Source    Step     |
    | Then       Time     To          True      Unset    |
    | Until      Use      Using       Var       While    |
    | QQ         ZZ                                      |
     ----------------------------------------------------
           Case insensitive reserved names

     -------------------------------------------------
    | BOOL      DegLex  DegRevLex  DEVICE  ERROR      |
    | FUNCTION  IDEAL   INT        LIST    Lex        |
    | MAT       MODULE  NULL       Null    PANEL      |
    | POLY      PosTo   RAT        RATFUN  RING       |
    | STRING    TAGGED  ToPos      TYPE    MODULEELEM |
    | Xel       ZMOD                                  |
     -------------------------------------------------
            Case sensitive reserved names
</verbatim>

    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Comments</title>
        <type>1</type>

        <description>
<par/>
End-of-line comments in CoCoA start with either <tt>--</tt> or
<tt>//</tt>; all text up to the end of the line is considered comment.
CoCoA also allows embedded comments; these begin with the symbol
<tt>/*</tt> and end with the symbol <tt>*/</tt>.  CoCoA ignores the
contents of a comment, and treats it as if it were just a space.
<par/>

<example>
/**/  // This is an end-of-line comment
/**/  Print 1+1; -- a command followed by an end-of-comment
2
/**/  A := [1 /*x-coord*/, 2 /*y-coord*/ ]; --> embedded comments
</example>
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Data Types</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
Each CoCoA object has a type.  The possible types are:
<verbatim>
  BOOL     : A boolean.  The boolean constants are True and False.
  DEVICE   : For input/output.
  ERROR    : Objects of this type are used in error-handling.
  FUNCTION : A CoCoA-defined function.
  IDEAL    : An ideal.
  INT      : An arbitrary precision integer.
  LIST     : A list.
  MAT      : A matrix.
  MODULE   : A submodule of a free module.
  NULL     : The null constant is Null.
  RAT      : An arbitrary precision rational number.
  RATFUN   : A rational function.
  RECORD   : A record is a set of bindings, name --&gt; object.
  RING     : A base ring, a polynomial ring, or a quotient ring.
  RINGELEM : A ring element (e.g. a polynomial)
  STRING   : A string.
  TAGGED   : Used to help in printing complicated objects.
  TYPE     : Returned by the function <tt>type</tt>, for example.
  MODULEELEM : A module element.
  ZMOD     : An integer modulo another integer, e.g. 3 % 5.
</verbatim>
The types are partially ordered by inclusion of the sets that they
represent, as follows:
<verbatim>
  MAT &lt; LIST
  MODULEELEM &lt; LIST
  INT &lt; RAT &lt; POLY &lt; RATFUN
  ZMOD &lt; POLY &lt; RATFUN  (if compatible).
</verbatim>
In the manual, OBJECT is used to refer to an arbitrary CoCoA type.  It
is not a type itself.
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
<section>
  <title>Commands and Functions for Data Types</title>
  <type>2</type>
  
  <description>
The following are commands and functions for data types:
<commands_and_functions_for type="type"></commands_and_functions_for>
  </description>
  
</section>

</chapter>

<!-- ===  CHAPTER  =============================================== -->
    <chapter>
      <title>Operators</title>
<!-- ===  SECTION  =============================================== -->
      <section>
        <title>CoCoA Operators</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
In CoCoA there are 5 main types of operators: algebraic
operators, relational operators, boolean operators, selection
operators, and the range operator.  There is also an n-ary operator <tt>&gt;&lt;</tt>
for forming Cartesian products of lists and an operator <tt>::</tt> used in
defining rings.
<par/>
The meaning of an operator depends on the types of its operands; the <tt>+</tt>
in the expression <tt>A + B</tt> represents the sum of polynomials, or of
ideals, or of matrices, etc. according to the type of A and B.
<par/>
The multiplication symbol <tt>*</tt> can always be omitted.  The expression
<tt>F(E)</tt> is intrinsically ambiguous; it can be the variable F multiplied
by the parenthesized expression E, or the application of the function
F to the argument E. CoCoA always interprets this expression in the
latter way. In the former case the user must separate F from the left
parenthesis with a blank or an <tt>*</tt>.
<par/>
The CoCoA operators are, from the highest to the lowest priority:

<verbatim>
    []  .   (selection operators)
    ^  %
    +  -    (as unary operators)
    *  :  /
    +  -    (as binary operators)
    ..
    =  &lt;&gt;  &lt;  &lt;=  &gt;  &gt;=
    IsIn
    And
    Or
</verbatim>

Operations with equal priority are performed from left to right.
When in doubt, parentheses may be used to enforce a particular order of
evaluation.
<par/>
Furthermore there is the n-ary operator <tt>&gt;&lt;</tt> (made by using a greater
than sign <tt>&gt;</tt> and a less than sign <tt>&lt;</tt>) for making Cartesian
products of lists (see <ttref>CartesianProduct, CartesianProductList</ttref>)
and the operator <tt>::</tt> for defining rings (see <ref>New Rings</ref>
and <ttref>Use</ttref>).
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Algebraic Operators</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
The algebraic operators are:

<verbatim>
      +  -  *  /  :  ^
</verbatim>

The following table shows which operations the system can perform
between two objects of the same or of different types; the first
column lists the type of the first operand and the first row lists the
type of the second operand. So, for example, the symbol <tt>:</tt> in the box
on the seventh row and fourth column means that it is possible to
divide an ideal by a polynomial.

<verbatim>
       INT    RAT    ZMOD RINGELEM RATFUN MODULEELEM IDEAL MODULE MAT LIST
INT    +-*/^  +-*/   *      +-*/   +-*/     *         *     *      *   *
RAT    +-*/^  +-*/          +-*/   +-*/     *         *     *      *   *
ZMOD   *^            +-*/   +-*/   +-*/     *         *     *      *   *
POLY   +-*/^  +-*/   +-*/   +-*/   +-*/     *         *     *      *   *
RATFUN +-*/^  +-*/   +-*/   +-*/   +-*/                            *   *
MODULEELEM *  *      *      *               +-
IDEAL  *^     *      *      *                         +*:   *
MODULE *      *      *      *                         *     +:
MAT    *^     *      *      *      *                               +-*
LIST   *      *      *      *      *                                   +-

                           Algebraic operators
</verbatim>

Remarks:
<par/>
  * Let F and G be two polynomials. If F is a multiple of G, then
    F/G is the polynomial obtained from the division of F by G,
    otherwise F/G is a rational function (common factors are
    simplified). The functions <ttref>div</ttref> and <ttref>mod</ttref> can be used to get the
    quotient and the remainder of a polynomial division.
<par/>
  * Let <formula>L_1</formula> and <formula>L_2</formula> be two lists of the same length. Then <formula>L_1 + L_2</formula> is
    the list obtained by adding <formula>L_1</formula> to <formula>L_2</formula> componentwise.
<par/>
  * If I and J are both ideals or both modules, then <formula>I : J</formula> is the
    ideal consisting of all polynomials f such that fg is in I for all
    g in J.
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Relational Operators</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
The relational operators are:

<verbatim>
      =    &lt;&gt;    &lt;    &gt;    &lt;=    &gt;=   IsIn
</verbatim>

The operator <ttref>IsIn</ttref> is quite flexible: see its manual for an explanation.
The other relational operators can be applied to two objects of the same type.
The admissible types for <tt>=</tt> and <tt>&lt;&gt;</tt> are:

<verbatim>
     NULL, BOOL, STRING, TYPE, INT, RAT, ZMOD, POLY, RATFUN,
     MODULEELEM, IDEAL, MODULE, MAT, LIST.
</verbatim>

The admissible types for the other relational operators are:

<verbatim>
     STRING, TYPE, INT, RAT, IDEAL, MODULE.
</verbatim>

The meaning of <tt>&lt;</tt> for string is the lexicographic comparison.  For
ideals and modules <tt>A &lt; B</tt> and <tt>A &lt;= B</tt> both mean that A is (not
necessarily strictly) contained in B.
<par/>
NOTE: It is sometimes hard to judge the type of an expression from the
appearance of CoCoA output, leading to confusing results from the
relational operators.  Here is an simple example:

<example>
  L := "3";
  L;
3
-------------------------------
  L=3;
False
-------------------------------
  type(L);
STRING
-------------------------------
  type(3);
INT
-------------------------------
</example>

Tagged expressions are especially prone to causing confusion of this sort.
    </description>

      <keys>
        <key>=</key>
        <key>equality</key>
      </keys>
      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Boolean Operators</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
The boolean operators are:
<verbatim>
      And  Or   not(...)
</verbatim>
see <ref>Introduction to Booleans</ref>.
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Selection Operators</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
The selection operators are
<verbatim>
      []  .
</verbatim>
Let N be of type INT and let L be of type STRING, MODULEELEM, LIST, or
MAT.  Then the meaning of L[N] depends on the type of L as explained
in the following table:

<verbatim>
    ------------------------------------------------------------
   |  Type of L    Meaning of L[N]                              |
    ------------------------------------------------------------
   | STRING       string consisting of the N-th character of L. |
   | MODULEELEM   N-th component of L                           |
   | LIST         N-th element of L                             |
   | MAT          N-th element of L                             |
    ------------------------------------------------------------
                   Selection Operator
</verbatim>

If N is an identifier and L is of type RECORD, then <tt>L.N</tt> indicates the
object contained in the field N of the record L (see <ref>Introduction to
Records</ref> and <ref>Records</ref>).
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Range Operator</title>
        <type>1</type>

        <description>
<par/>
If M and N are of type INT, then the expression:  <tt>M .. N</tt> returns
<par/>
      * the list <tt>[M, M+1, ... , N]</tt> if <formula>M <less_eq/> N;</formula>
<par/>
      * the empty list, <tt>[]</tt>, otherwise.
<par/>
NOTE: Large values for M and N are not permitted; typically
      they should lie in the range about <formula>-10^9</formula> to <formula>+10^9</formula>.
<par/>
NOTE: see example for how to select a sub-range of a list
<par/>
If x and y are indeterminates in a ring, then <tt>x .. y</tt>
gives the indeterminates between x and y in the order they appear
in the definition of the ring.

<example>
/**/  1..10;
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

/**/  Use R ::= QQ[x,y,z,a,b,c,d];
/**/  z..c;
[z, a, b, c]

/**/ L := [11, 22, 33, 44, 55];
/**/ PartOfL := L[2]..L[4];  --> probably NOT what you want!
/**/ PartOfL := [ L[k] | k in 2..4 ]; -- OK, this is RIGHT!
</example>
    </description>

	<seealso>
	  <see>CoCoA Operators</see>
	  <see>operators, shortcuts</see>
    </seealso>

    <type>list</type>

      <keys>
        <key>list constructor</key>
        <key>dot dot</key>
        <key>dotdot</key>
      </keys>
      </section>

    </chapter>

<!-- ===  CHAPTER  =============================================== -->
    <chapter>
      <title>Evaluation and Assignment</title>
<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Evaluation</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
An expression is by itself a valid command. The effect of this
command is that the expression is evaluated in the current ring and
its value is displayed.
<par/>
The evaluation of an expression in CoCoA is normally performed in a
full recursive evaluation mode. Usually the result is the fully
evaluated expression.
<par/>
The result of the evaluation is automatically stored in the variable
<ttref>It</ttref>.

<example>
  2 + 2;
4
-------------------------------
  It + 3;
7
-------------------------------
  It;
7
-------------------------------
  X := 5;
  It;
7
-------------------------------
</example>
The command <tt>X := 5</tt> is an assignment, not an evaluation; so it does
not change the value of the variable <ttref>It</ttref>.
<par/>
If an error occurs during the evaluation of an expression, then the
evaluation is interrupted and the user is notified about the error.
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Assignment</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
An assignment command has the form
<verbatim>
  L := E
</verbatim>
where L is a variable and E is an expression.  The assignment command
binds the result of the evaluation of the expression E to L in the
working memory (see the chapter entitled <ref>Memory Management</ref>).  If E
is dependent upon a ring, then L is labeled with that ring.  The label
is listed when L is evaluated in another ring.  Then command
<tt>RingEnv(L)</tt> will return the label for L.

<example>
  Use R ::= QQ[t,x,y,z];
  I := ideal(x,y);
  M := 5;
  N := 8;
  T := M+N;
  T;
13
-------------------------------
  T := T+1;  -- note that T occurs on the right, also
  T;
14
-------------------------------
  L := [1,2,3];
  L[2] := L[3];
  L;
[1, 3, 3]
-------------------------------
  P := Record[F := xz];
  P.Degree := Deg(P.F);
  P;
Record[Degree := 2, F := xz]
-------------------------------
  Use S ::= QQ[a,b];
  I;  -- I is labeled by R since it depends on R
R :: ideal(x, y)
-------------------------------
  T;  -- T is not labeled by R
14
-------------------------------
  J := R:: ideal(x^2-y);  -- J contains an object dependent on R
  J; -- since the ring S is active, J is labeled by R
R :: ideal(x^2 - y)
-------------------------------
  Use R;
  J;
ideal(x^2 - y)
-------------------------------
</example>

For information about interacting with rings outside of the current
ring, see <ref>Accessing Other Rings</ref> in the chapter entitled <ref>Rings</ref>.
<par/>
To assign values to global variables, see <ref>Introduction to Memory</ref> or
<ref>Global Memory</ref>.
    </description>

      </section>

    </chapter>

<!-- ===  CHAPTER  =============================================== -->
    <chapter>
      <title>User-Defined Functions</title>
<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Introduction to User-Defined Functions</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
The most important construct in CoCoA programming is the user-defined
function.  These functions take parameters, perform CoCoA commands,
and return values.  Collections of functions can be stored in text
files and read into CoCoA sessions using <ttref>source</ttref>.  To
prevent name conflicts of the type that are likely to arise if
functions are to be made available for use by others, the functions
can be collected in <em>packages</em>, as described in a later chapter.
<par/>
To learn about user functions, look up <ttref>Define</ttref> (online, enter
<tt>?define</tt>) for the complete syntax and for examples.  The <ref>Tutorial</ref>
also contains several examples of functions.
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
<section>
  <title>Commands and Functions for Functions</title>
  <type>1</type>
  
  <description>
User-defined functions can contain just about any CoCoA command and
may refer to other user-defined functions.  The following are some
commands that pertain particularly to functions:
<commands_and_functions_for type="function"></commands_and_functions_for>
  </description>
  
</section>

    </chapter>

<!-- ===  CHAPTER  =============================================== -->
    <chapter>
      <title>Flow Control: Conditional Statements and Loops</title>
<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Commands and Functions for Branching</title>
        <type>1</type>

        <description>
The following are the CoCoA commands for constructing conditional
statements:
<commands_and_functions_for type="branching"></commands_and_functions_for>
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Commands and Functions for Loops</title>
        <type>1</type>

        <description>
<par/>
The following are the commands and functions for loops:
<commands_and_functions_for type="loops"></commands_and_functions_for>
    </description>

      </section>

    </chapter>

<!-- ===  CHAPTER  =============================================== -->
    <chapter>
      <title>Input/Output</title>
<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Introduction to IO</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
Input and output is implemented in CoCoA through the use of
<em>devices</em>.  At present, the official devices are: (1) standard IO (the
CoCoA window), (2) text files, and (3) strings.  What this means is that
it is possible to read from or write to any of these places.  The
cases are discussed separately, below.  Text files may be read
verbatim or---with the <ttref>source</ttref> command---be executed as CoCoA
commands.
    </description>

      <keys>
        <key>devices</key>
      </keys>
      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Standard IO</title>
        <type>2</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
Standard IO is what takes places normally when one interacts with
CoCoA via the CoCoA window.  CoCoA accepts and interprets strings
typed in by the user and prints out expressions.  If E is a CoCoA
object, then the command
<verbatim>
    E;
</verbatim>
causes the value of E to be printed to the CoCoA window.  One may also
use the functions <ttref>print</ttref> and <ttref>PrintLn</ttref> for more control over the
format of the output.
<par/>
The official devices that are being used here are <tt>DEV.STDIN</tt> and
<tt>DEV.OUT</tt>. So for instance, the commands <ttref>Get</ttref> and <ttref>Print On</ttref> can be
used with the standard devices although they are really meant to be
used with the other devices.  <tt>Print E On DEV.OUT</tt> is synonymous with
<tt>Print E</tt>.  Also, one may use <tt>Get(DEV.STDIN,10)</tt>, for example, to get
the next 10 characters typed in the CoCoA window.  Thus, clever use of
<ttref>Get</ttref> will allow your user-defined functions to prompt the user for
input, but normal practice is to pass variables to a function as
arguments to that function.
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>File IO</title>
        <type>2</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
To print CoCoA output to a file, one first opens the file
with <ttref>OpenOFile</ttref> then prints to the file using <ttref>Print On</ttref>.
<par/>
To receive verbatim input from a file, one first opens the file with
<ttref>OpenIFile</ttref>, then gets characters from the file with <ttref>Get</ttref>.  Actually,
<ttref>Get</ttref> gets a list of ASCII codes for the characters in the file.
These can be converted to real characters using the function <ttref>ascii</ttref>.

<example>
  D := OpenOFile("my-file"); -- open text file with name "my-file",
                             -- creating it if necessary
  Print "hello world" On D; -- append "hello world" to my-file
  Close(D); -- close the file
  D := OpenIFile("my-file"); -- open "my-file"
  Get(D,10);  -- get the first ten characters, in ASCII code
[104, 101, 108, 108, 111, 32, 119, 111, 114, 108]
-------------------------------
  ascii(It); -- convert the ASCII code
hello worl
-------------------------------
  Close(D);
</example>

To read and execute a sequence of CoCoA commands from a text file, one
uses the <ttref>source</ttref> command.  For instance, if the
file <tt>MyFile.coc</tt> contains a list of CoCoA commands, then
<verbatim>
  Source <quotes>MyFile.cocoa</quotes>;
</verbatim>
reads and executes the commands.
    </description>

	<seealso>
          <see>ascii</see>
          <see>close</see>
          <see>Get</see>
	  <see>OpenIFile</see>
	  <see>OpenOFile</see>
          <see>OpenLog</see>
          <see>CloseLog</see>
          <see>Print On</see>
          <see>source</see>
	</seealso>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>String IO</title>
        <type>2</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
To print CoCoA output to a string, on may use <ttref>OpenOString</ttref> to
<em>open</em> the string, then <ttref>Print On</ttref> to write to it.  To read from a
string, one may open the string for input with <ttref>OpenIString</ttref> then get
characters from it with <ttref>Get</ttref>.

<example>
  S := "hello world";
  D := OpenIString("", S);  -- open the string S for input to CoCoA
                -- the first argument is just a name for the device
  L := Get(D,7);  -- read 7 characters from the string
  L;  -- ASCII code
[104, 101, 108, 108, 111, 32, 119]
-------------------------------
  ascii(L); -- convert ASCII code to characters
hello w
-------------------------------
  Close(D);  -- close device D
  D := OpenOString("");  -- open a string for output from CoCoA
  L := [1,2,3]; -- a list
  Print L On D;  -- print to D
  D;
Record[Name := "", Type := "OString", Protocol := "CoCoALanguage"]
-------------------------------
  S := Cast(D, STRING);  -- S is the string output printed on D
  S; -- a string
  [1, 2, 3]
  Print " more characters" On D;  -- append to the existing output string
  Cast(D, STRING);
[1, 2, 3] more characters
-------------------------------
</example>
There are usually more direct ways to collect results in strings.  For
instance, if the output of a CoCoA command is not already of type
STRING, one may convert it to a string using <ttref>sprint</ttref>.
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
<section>
  <title>Commands and Functions for IO</title>
  <type>1</type>
  
  <description>
The following are commands and functions for input/output:
<commands_and_functions_for type="io"></commands_and_functions_for>
  </description>
  
</section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Tagged Printing</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
Some CoCoA objects are intrinsically complicated, so printing them
verbatim might be confusing.  For this reason a mechanism has been
implemented which enables automatic pretty printing through the use of
<em>tags</em>.  A user may <em>tag</em> any object with a string and then define
how objects tagged with that string should be printed or described.
Commands that do not have to do with printing ignore the tag.
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Tagging an Object</title>
        <type>2</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
If E is any CoCoA object and S a string, then the function
<tt>Tagged(E, S)</tt> returns the object E tagged with the string S.  The type
of the returned object is <tt>TAGGED(S)</tt> (but the type of E is
unchanged).  The function <ttref>Tag</ttref> returns the tag string of an object,
and the function <ttref>untagged</ttref> (or <tt>@</tt>) returns the object, stripped of
its tag.

<example>
  L := ["Dave","March 14, 1959",372];
  M := Tagged(L, "MiscData");  -- L has been tagged with the string "MiscData"
  type(L);  -- L is a list
LIST
-------------------------------
  type(M);  -- M is a tagged object
TAGGED("MiscData")
-------------------------------
  Tag(M); -- the tag string of M (it would be the empty string if M
          -- were not a tagged object).
MiscData
-------------------------------
  M;  -- Until a special print function is defined, the printing of L
      -- and M is identical.
["Dave", "March 14, 1959", 372]
-------------------------------
  Untagged(M) = L; -- "untagged" removes the tag from M, recovering L.
True
-------------------------------
</example>
The next section explains how to define functions for pretty printing
of tagged objects.
    </description>

      <keys>
        <key>dave</key>
      </keys>
      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Printing a Tagged Object</title>
        <type>2</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
Suppose the object E is tagged with the string S.  When one tries to
print E---say with <tt>Print E</tt> or just <tt>E;</tt>--- CoCoA looks for a
user-defined function with name <tt>Print_S</tt>.  If no such function is
available, CoCoA prints E as if it were not tagged, otherwise, it
executes <tt>Print_S</tt>.

<example>
  L := ["Dave","March 14, 1959",372];  -- continuing with the previous example
  M := Tagged(L,"MiscData");
  M; -- M is printed as normal in the absence of a function "Print_MiscData"
["Dave", "March 14, 1959", 372]
-------------------------------
  Define Print_MiscData(X) -- Exactly one parameter is required.
    M := Untagged(X);
    Print M[1];
  EndDefine;
  Print M; -- Now, any object tagged with the string "MiscData" will be
     -- printed using Print_MiscData
Dave
-------------------------------
  M;  -- Whenever printing of M is called for, "Print_MiscData" is executed.
Dave
-------------------------------
</example>
The line <tt>M := Untagged(X)</tt> is actually not necessary here, but in
general one may get into an infinite loop trying to print X, a tagged
object, from within the function that is being defined in order to
print X, if that makes sense.  Untagging X prevents this problem.
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Describing a Tagged Object</title>
        <type>2</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
If the object E is tagged with the string S, then when the user
enters the command <tt>Describe E</tt>, CoCoA first looks for a user-defined
function with name <tt>Describe_S</tt> and executes it; if not found, the
output depends on the type of Untagged(E).

<example>
  Use R ::= QQ[x,y,z];
  I := ideal(x-y^2, x-z^3);
  I := Tagged(I,"MyIdeals");  -- I is now tagged with "MyIdeals"
  Describe I;  -- the default description of an ideal
Record[Type := IDEAL, Value := Record[Gens := [-y^2 + x, -z^3 + x]]]
-------------------------------
  Define Describe_MyIdeals(X)
    Y := Untagged(X);
    PrintLn "The generators are:";
    Foreach G In Y.Gens Do
      PrintLn"  ", G;
    EndForeach;
  EndDefine;
  Describe I;  -- Any object tagged with "MyIdeals" is now described
               -- using "Describe_MyIdeals".
The generators are:
  -y^2 + x
  -z^3 + x

-------------------------------
</example>
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Another Example Using Tags</title>
        <type>2</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
Here is one more example using tags.  Note that CoCoA commands that
do not have to do with printing ignore tags.

<example>
  N := Tagged(4,"Dots");
  N;
4
-------------------------------
  Define Print_Dots(X)
    For I := 1 To X Do
      Print ".";
    EndFor;
  EndDefine;
N;
....
-------------------------------
  N+N;  -- As long as printing is not involved, N is treated as if
        -- it has no tag.  In this case, the sum of two tagged objects
        -- returns an integer, not another tagged object.
8
-------------------------------
  M := Tagged(12,"Dots");
  M;
............
-------------------------------
</example>
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
<section>
  <title>Commands and Functions for Tags</title>
  <type>2</type>
  
  <description>
The following are commands and functions involving tags:
<commands_and_functions_for type="tags"></commands_and_functions_for>
  </description>

</section>

</chapter>

<!-- ===  CHAPTER  =============================================== -->
    <chapter>
      <title>Memory Management</title>
<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Introduction to Memory</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
CoCoA has three types of memory: <em>working</em>, <em>global</em>, and
<em>ring-bound</em> memory.  Unlike previous versions of CoCoA, starting
with CoCoA 3.5, variables defined during a session are by default
assigned to a <em>working memory</em>, accessible from all rings (but not
from user-defined functions).  There are no longer variables that are
local to a particular ring.  However, as in previous versions of
CoCoA, one may define variables in the <em>global memory</em> by using the
prefix <tt>MEMORY</tt>.
<par/>
The word <em>global</em> now refers to the fact that these
variables are accessible not only to all rings but also to
user-defined functions.  A special class of global variables can be
stored in what is called the <em>ring-bound memory</em>. 
Most users will never need the ring-bound memory!
These variables are formed with the prefix <tt>MEMORY.ENV.R</tt>
where <tt>R</tt> is a ring identifier; they are <em>bound</em> to the
ring, which means that they are automatically destroyed when their
corresponding rings cease to exist.  Otherwise, variables in the
ring-bound memory behave exactly as all other global variables.
<par/>
These three types of memory are discussed separately, below.
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Working Memory</title>
        <type>1</type>

        <description>
***** OBSOLETE *****
<par/>
The <em>working memory</em> consists of all variables except those defined
with the prefix <tt>MEMORY</tt>, e.g. <tt>MEMORY.X</tt>.  All variables in the
working memory are accessible from all rings, but they are not
accessible from within a user-define function (see examples in the
next section).  The function <tt>Memory</tt> displays the contents of the
working memory. More information is provided by <tt>Describe Memory()</tt>.
<par/>
Ring-dependent variables such as those containing polynomials, ideals,
or modules, are labeled by their corresponding rings.  If the ring of
a ring-dependent variable in the working memory is destroyed, the
variable will continue to exist, but labeled by a ring automatically
generated by CoCoA.  Once all variables dependent on this new ring
cease to exist, so does the ring.

<example>
  Use R ::= QQ[x,y,z];
  Memory();  -- the working memory is empty
[ ]
-------------------------------
  I := ideal(xy-z^3, x^2-yz);
  X := 3;
  M := mat([[1,2],[3,4]]);
  Memory();
["I", "It", "M", "X"]
-------------------------------
  Describe Memory();
------------[Memory]-----------
I = ideal(-z^3 + xy, x^2 - yz)
It = ["I", "It", "M", "X"]
M = mat([
  [1, 2],
  [3, 4]
])
X = 3
-------------------------------
  Use S ::= ZZ/(3)[t];  -- switch to a different ring
  X := t^2+t+1;  -- the identifier X is used again
  Y := 7;
Describe Memory();  -- note that I is labeled by its ring
------------[Memory]-----------
I = R :: ideal(-z^3 + xy, x^2 - yz)
It = ["I", "It", "M", "X"]
M = mat([
  [1, 2],
  [3, 4]
])
X = t^2 + t + 1
Y = 7
-------------------------------
  GBasis(I);  -- The Groebner basis for the ideal in R can be calculated
              -- even though the current ring is S.
[R :: x^2 - yz, R :: -z^3 + xy]
-------------------------------
  M^2;
mat([
  [7, 10],
  [15, 22]
])
-------------------------------
  Use R ::= QQ[s,t];  -- redefine the ring R
  I;  -- Note that I is labeled by a new ring, automatically produced by
      -- CoCoA.  This ring will automatically cease to exist when there
      -- are no longer variables dependent upon it, as shown below.
R#17 :: ideal(-z^3 + xy, x^2 - yz)
-------------------------------
  RingEnvs();
["QQ", "QQt", "R", "R#17", "S", "ZZ"]
-------------------------------
  I := 3; -- I is overwritten with an integer, and since it is the only
          -- variable dependent on R#17, the ring R#17 ceases to exist.
  RingEnvs();  -- Since the only variable that was dependent upon the
               -- temporary ring "R#17" was overwritten, that ring is
               -- destroyed.
["QQ", "QQt", "R", "S", "ZZ"]
-------------------------------
</example>
    </description>

	<seealso>
          <see>Commands and Functions for Memory</see>
	</seealso>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Global Memory</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
Starting with CoCoA 3.5, a <em>global</em> variable is one that is
accessible from within a user-defined function.  A global variable is
formed by using the prefix <tt>MEMORY</tt>.  The special prefixes <tt>DEV</tt>,
<tt>ENV</tt>, <tt>ERR</tt>, and <tt>PKG</tt> are shorthand for <tt>MEMORY.DEV</tt>, <tt>MEMORY.ENV</tt>,
etc.  Any global variable prefixed by <tt>MEMORY.ENV.R</tt> where <tt>R</tt> is the
identifier of a ring, becomes part of the ring-bound memory discussed
in the next section.  A list of the global variables which are not
ring-bound is provided by the function <ttref>GlobalMemory</ttref>.

<example>
  Use R ::= QQ[x,y,z];
  X := 5;  -- a variable called "X" in the working memory
  MEMORY.X := 7; -- a global variable
  X;
5
-------------------------------
  MEMORY.X;
7
-------------------------------
  Memory();  -- the working memory
["It", "X"]
-------------------------------
  GlobalMemory(); -- the global memory
["DEV", "ENV", "ERR", "PKG", "X"]
-------------------------------
  Define Test()
    PrintLn MEMORY.X;
    MEMORY.X := "a new value";
    PrintLn X;
  EndDefine;
  -- MEMORY.X is accessible from within a function
  -- X is not accessible within a function (thus we get an error)
  Test();
7

-------------------------------
ERROR: Undefined variable X
CONTEXT: PrintLn(X)
-------------------------------
  MEMORY.X;  -- the contents of the global memory can be changed from
             -- within a function
a new value
-------------------------------
  Fields(MEMORY.ENV);  -- a list of all defined rings
["QQ", "QQt", "R", "ZZ"]
-------------------------------
</example>
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Ring-Bound Memory</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
A variable prefixed by <tt>MEMORY.ENV.R</tt> where <tt>R</tt> is the identifier of
a ring, becomes bound to the ring R.  This means that when R ceases to
exist, so does the variable (unlike variables that are part of the
working memory, labeled by R: see <ref>Working Memory</ref>, above).  The
collection of these variables comprises the <em>ring-bound memory</em>.
The variables bound to a ring R can be listed with the command
<tt>Memory(R)</tt>. Note that since ring-bound variables are, in particular,
prefixed by <tt>MEMORY</tt>, they are also part of the global memory
discussed in the previous section.
<par/>
Most users will never need ring-bound variables.  Their main use is
within functions which need to define and use rings temporarily,
destroying them (along with their variables) before returning.
<par/>
The prefix <tt>ENV</tt> is shorthand for <tt>MEMORY.ENV</tt>.

<example>
  Use R ::= QQ[x,y,z];
  X := ideal(x,y);  -- a variable in the current memory
  ENV.R.Y := "bound to R";  -- a variable in the memory bound to R
  Use S ::= QQ[a,b];
  Z := 6;
  Memory();  -- the working memory
["X", "Z"]
-------------------------------
  Memory(R);  -- the memory bound to R
["Y"]
-------------------------------
  Destroy R;
  Memory();
["It", "X", "Z"]
-------------------------------
  X;  -- Since X is not in the ring-bound memory of R,
      -- it is not destroyed.  It was <em>dependent</em> on the ring R,
      -- so the base ring of R has been given the new name R#5.
R#5 :: ideal(x, y)
-------------------------------
  ENV.R.Y;  -- this variable was destroyed along with R
ERROR: Unknown record field R
CONTEXT: ENV.R.Y
-------------------------------
  RingEnvs();
["QQ", "QQt", "R#5", "S", "ZZ"]
-------------------------------
</example>
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Commands and Functions for Memory</title>
        <type>1</type>

        <description>
<par/>
The following are commands and functions for memory:
<commands_and_functions_for type="memory"></commands_and_functions_for>
    </description>

      </section>

    </chapter>

<!-- ===  CHAPTER  =============================================== -->
    <chapter>
      <title>CoCoA Packages</title>
<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Introduction to Packages</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
User-defined functions may be saved in separate files and read into a
CoCoA session using the <ttref>source</ttref> command.  If one sources several such
files or, especially, if a file is to be made available for general
use, a possible problem arises from conflicting function names.  If
two functions with the same name are read into a CoCoA session, only
the one last read survives.  To avoid this, functions may be collected
in <em>packages</em>.
<par/>
A CoCoA package is essentially a list of functions (made using the
<ttref>Define</ttref> command), labeled with a long prefix.  A function from a
package is referred to by the package prefix plus the function name.
The user may type the full prefix, but the usual method is to create a
short alias for the prefix.  Details are provided below, starting with
a short example.
    </description>

	<seealso>
          <see>Define</see>
          <see>source</see>
	</seealso>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>First Example of a Package</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
The following is an example of a package.  It could be typed into a
window as-is during a CoCoA session, but we will assume that it is
stored in a file in the CoCoA directory under the name <tt>one.cpkg</tt>.

<example>
  Package $contrib/toypackage

  Define IsOne(N)
    If N = 1 Then Return True Else Return False EndIf;
  EndDefine;
  
  Define Test(N)
    If $.IsOne(N) Then
      Print "The number 1."
    Else
      Print "Not the number 1."
    EndIf;
  EndDefine;
  
  EndPackage; -- of toypackage
</example>

Below is output from a CoCoA session in which this package was used:

<example>
  -- read in the package:
  Source "one.cpkg";
  Test(1);  -- error here because the function "Test" is not defined

-------------------------------
ERROR: Unknown operator Test
CONTEXT: Test(1)
-------------------------------
  $contrib/toypackage.Test(1); -- this is the name of the function
                               -- we are looking for
The number 1.
-------------------------------
  Alias Toy := $contrib/toypackage;  -- use an alias to save typing
  Toy.Test(3);
Not the number 1.
-------------------------------
  Toy.IsOne(3);
False
-------------------------------
</example>

Once the package is read, the user can choose a <em>substitute prefix</em>
using the <ttref>Alias</ttref> command and in that way avoid conflicts between
functions in various packages and save on typing.
<par/>
Note one other thing: the function <tt>IsOne</tt> is used in the definition
of <tt>Test</tt>.  In that case, it is referred to as <tt>$.IsOne</tt>.  Otherwise,
CoCoA would look for a global function, outside of the package, called
<tt>IsOne</tt>.  Forgetting this kind of reference is a common source of
errors when constructing a package.
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Package Essentials</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
A package begins with
<verbatim>
    Package $PackageName
</verbatim>
and ends with
<verbatim>
    EndPackage;
</verbatim>
PackageName is a string that will be used to identify the package.
The dollar sign is required.  There are no restrictions on the string
PackageName, but keep in mind that it serves to distinguish functions
in the package from those in all other CoCoA packages.  A name of the
form <tt>contrib/subject</tt> is typical.
<par/>
In between the <tt>Package</tt> declaration and its <tt>EndPackage</tt> one may: (1)
declare aliases (see below), (2) define functions, and (3) make
comments (please).
<par/>
If a function F in the package appears in the definition of another
function within the package, it must be referred to as <tt>$.F</tt> (or
<tt>$PackageName.F</tt>, or using a local alias, see below).
<par/>
Typically, the user will read in the package using the <ttref>source</ttref>
command.  After that, to save on typing, the user will
choose a global alias with which to refer to the package using the
syntax:

<verbatim>
    Alias ShortName := $PackageName;
</verbatim>

where ShortName is any convenient string, hopefully not conflicting
with other global aliases.  (A list of the global aliases is returned
by the function <ttref>aliases</ttref>.)
<par/>
A package function, F, is then called using the name <tt>ShortName.F</tt>.
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Package Sourcing and Autoloading</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
As mentioned above, packages are usually saved in files and then read
into a CoCoA session using the command <ttref>source</ttref>.
<par/>
(I) Full path name, ordinary file sourcing.
<verbatim>
package name: $mypackage
   file name: this/is/my/stuff.cpkg
</verbatim>
Suppose the name of your package is <tt>$mypackage</tt> and is kept in the
file with full pathname <tt>this/is/my/stuff.cpkg</tt>.  Then the package can
be loaded into the session as usual with the command:
<verbatim>
  Source <quotes>this/is/my/stuff.cpkg</quotes>;
</verbatim>
Functions can then be called from the package using the package name,
<tt>$mypackage</tt>, as a prefix (or using aliases).
<par/>
(II) The standard package path, <tt>$</tt>-shortcut.
<verbatim>
package name: $mypackage
   file name: packages/anna/stuff.cpkg (relative to cocoa directory)
</verbatim>
<verbatim>
  Source CocoaPackagePath() + <quotes>/anna/stuff.cpkg</quotes>;
</verbatim>
<em>The following syntax is obsolescent!</em>
<verbatim>
  Source <quotes>$anna/stuff</quotes>;
</verbatim>
<par/>
(III) Autoloading.
<verbatim>
package name: $anna/stuff
   file name: packages/anna/stuff.cpkg (relative to cocoa directory)
</verbatim>
Now suppose that the package is in the standard package path, as
above, in the file with pathname (relative to the cocoa directory)
<tt>packages/anna/stuff.cpkg</tt>.  However, now assume that the name of the
package is <tt>$anna/stuff</tt>, i.e., that it matches the name of its
file (without <tt>packages/</tt> and <tt>.cpkg</tt>).  Then, if any function from the
package is called, say <tt>$anna/stuff.MyFunction</tt>, the package
will automatically be loaded.  Of course, one may also source the
package using either method I or II, from above.
<par/>
* Initialize *
NOTE: As explained in the section entitled <ref>Package Initialization</ref>,
below, no matter which method is used to source a package, any
function in the package named <tt>Initialize</tt> will automatically be
executed when the package is loaded.
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Global Aliases</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
A global alias for a package is formed by using the command <ttref>Alias</ttref>
during a CoCoA session.  (Local aliases are formed with the same
command, but are declared inside a package.  They are for use only
within the package.)  The syntax for <ttref>Alias</ttref> is

  Alias binding, ...,binding;

where a <em>binding</em> has the form
<verbatim>
  identifier := $PackageName
</verbatim>
The function <ttref>aliases</ttref> prints a list of the global aliases.

<example>
  aliases();

H      = $help
IO     = $io
GB     = $gb
HP     = $hp
HL     = $hilop
List   = $list
Mat    = $mat
Latex  = $latex
LaTeX  = $latex
Toric  = $toric
Coclib = $coclib
TT     = $abc
-------------------------------
  Alias  My := $my_package,
        Old := $my_package/old_version;
  aliases();

HP      = $hp
BinRepr = $binrepr
SpPoly  = $sppoly
HL      = $hilop
H       = $help
My      = $my_package
Old     = $my_package/old_version
-------------------------------
</example>
Note: global aliases cannot be used in function definitions.  This is
to force independence of context.  Inside a function, one must use the
complete package name.  For example, <tt>$gb.Steps(M,1)</tt> is a
valid statement inside a function, but not <tt>GB.Steps(M,1)</tt>.
    </description>

	<seealso>
          <see>Alias</see>
          <see>aliases</see>
	</seealso>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Local Aliases</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
A local alias is an alias declared inside a package, for use only
within the package.  A local alias can have the same identifier as a
global alias.  Only local aliases are recognized within packages.
<par/>
There are two uses for local aliases.  First, recall that if the
definition of function in a package uses another function, F, also
defined in the package, then F must be referred to using the package
name as a prefix or, for short, <tt>$.F</tt>.  In this way, <tt>$</tt>, is an
automatically a local alias for the package itself.  One may choose
another alias, say <tt>DD</tt>, and write <tt>DD.F</tt>, instead.  A second use for
a local alias is to refer to a separate package.  In that way, one may
refer to functions from that package inside the current package
without typing out the full package name.
<par/>
Keep in mind that these aliases are used only to save typing.
Examples appear below.
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>More Examples of Packages</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
Here is a simple package for printing lists.

<example>
  Package $contrib/list

  Define About()
    Return "
      Author: Antonio
      Version: 1.0
      Date: 18 July 1997
    "
  EndDefine;
  
  Define PrintList(L)
    Foreach X In L Do
      PrintLn X;
    EndForeach;
  EndDefine;
  
  EndPackage;
</example>
Here is another package that takes a pair of objects and turns the
pair into a list.  Note the local alias used to reference the previous
package.

<example>
  Package $contrib/pair
  
  Alias L := $contrib/list; -- Local alias for another package.
                            -- This alias does not affect global
                            -- aliases.
  Define Make(A, B)
    Return [A, B];
  EndDefine;
  
  Define First(P)
    Return P[1];
  EndDefine;
  
  Define Second(P)
    Return P[2];
  EndDefine;
  
  Define PrintPairOfLists(P)
    PrintLn "First list:";
    L.PrintList($.First(P));  -- The local alias, L, is used here,
    PrintLn "Second list:";
    L.PrintList($.Second(P)); -- and here.  <tt>$</tt> refers to a function
  EndDefine;                  -- defined in the current package.
  
  EndPackage;
</example>
USING THE PACKAGES.  After reading in the packages using <ttref>source</ttref> one may proceed as follows to use them:

<example>
  Alias P := $contrib/pair;
  X := P.Make([x^2,x], [x,y,z]);
  P.PrintPairOfLists(X);
First list:
x^2
x
Second list:
x
y
z
-------------------------------
</example>
Note: suppose a package with identifier <tt>$contrib/newlist</tt> prints lists
in another format.  To switch to this format in <tt>$contrib/pair</tt>, one
need only change the alias for L from <tt>$contrib/list</tt> to
<tt>$contrib/newlist</tt>.
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Package Initialization</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
Packages are often stored in files and read into a CoCoA session
using the <ttref>source</ttref> command.  When a package is loaded, any function
whose name is <tt>Initialize</tt> will automatically be executed.  For
example, this feature may be used to print a message or initialized
global variables when the package is read into a session.
<par/>
(Note: following this rule, if the first time you access package
PKG is to make an explicit call to the function PKG.Initialize() then
the function will be called twice!)

<example>
  Package $example
    Define Initialize()
      Print "CALLED INITIALIZE";
      MEMORY.MyVar := 17;
    EndDefine;
  EndPackage;
CALLED INITIALIZE
-------------------------------
  MEMORY.MyVar;
17
-------------------------------
</example>
    </description>

	<seealso>
          <see>User Initialization</see>
	</seealso>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Sharing Your Package</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
If you create a package that others might find useful, please contact
the CoCoA team by email at <tt>cocoa at dima.unige.it</tt>.
<par/>
Include comments in the package that:
<par/>
  * explain the use of the package
<par/>
  * list functions that are meant to be seen by the user
<par/>
  * give the syntax for these functions.  (What are the arguments?
    What values are returned?)
<par/>
  * describe what each function does
<par/>
  * provide examples of the use of each function.
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Commands and Functions for Packages</title>
        <type>1</type>

        <description>
<par/>
The following are commands and functions for packages:
<commands_and_functions_for type="packages"></commands_and_functions_for>
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Supported Packages</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
Several packages are supported by the CoCoA team.  These packages
contain functions that are not built into CoCoA because they are of a
more specialized or experimental nature.
<par/>
The supported packages are:
<verbatim>
    CantStop         -- the first game in CoCoA  ;-)
    conductor.cpkg   -- conductor sequence of points
    control.cpkg     -- tools for geometric Control Theory
    galois.cpkg      -- computing in a cyclic extension
    intprog.cpkg     -- integer programming
    invariants.cpkg  -- generators of an algebra of invariants
    matrixnormalform.cpkg  -- Smith normal form of a matrix
    primary.cpkg     -- primary ideals
    specvar.cpkg     -- special varieties
    stat.cpkg        -- statistics, design of experiment
    thmproving.cpkg  -- geometrical theorem proving
    typevectors.cpkg -- typevectors for ideals of points
</verbatim>
All of these packages are included in /packages/contrib of the distribution
of CoCoA.  The packages are likely to be updated more often than
CoCoA, itself, and new packages may appear; so it may be worth
checking at the CoCoA distribution sites, e.g.,
<tt>http://cocoa.dima.unige.it/</tt>.
<par/>
HOW TO USE A SUPPORTED PACKAGE
(1) save the package in /packages/contrib/, if necessary;
(2) to get the syntax, description, and examples of the main functions
   and a suggested alias for the package, type
       <tt>$contrib/<quotes>package_name</quotes>.Man();</tt>
(3) to know the author and version number, type
       <tt>$contrib/<quotes>package_name</quotes>.About();</tt>
<par/>
or just XX.Man(); XX.About()
where XX is a defined alias (type <tt>aliases();</tt> to get the list)
<par/>
NOTE: The packages will load automatically when one of their functions
is called (see <ref>Package Sourcing and Autoloading</ref>) for more
information.
<par/>
See below for more details about specific supported packages.
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Galois Package</title>
        <type>2</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
Supported CoCoA Package
<verbatim>
TITLE       : galois.cpkg
DESCRIPTION : CoCoA package for computing in a cyclic algebraic
              extension
AUTHOR      : A. Bigatti, D.La Macchia, F.Rossi

LOADING INSTRUCTIONS
-- Enter
       $contrib/galois.Man();
   to get a complete description of the package including a suggested alias.
-- Enter
       $contrib/galois.About();
   to find the version number.  You may want to check the CoCoA
   homepage for the latest version.
</verbatim>
    </description>

      <keys>
        <key>algebraic extension</key>
        <key>cyclic extension</key>
        <key>galois group</key>
	<key>bigatti la macchia rossi</key>
      </keys>
      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Integer Programming</title>
        <type>2</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
Supported CoCoA Package
<verbatim>
TITLE       : intprog.cpkg
DESCRIPTION : CoCoA package for applying toric ideals to integer
              programming
AUTHOR      : A. Bigatti

LOADING INSTRUCTIONS
-- Enter
       $contrib/intprog.Man();
   to get a complete description of the package including a suggested alias.
-- Enter
       $contrib/intprog.About();
   to find the version number.  You may want to check the CoCoA
   homepage for the latest version.
</verbatim>
    </description>

      <keys>
        <key>intprog</key>
        <key>test set</key>
        <key>testset</key>
	<key>bigatti</key>
      </keys>
      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Algebra of Invariants</title>
        <type>2</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
Supported CoCoA Package
<verbatim>
TITLE       : invariants.cpkg
DESCRIPTION : CoCoA package for computing homogeneous generators of an
              algebra of invariants, and for testing invariance of a polynomial
AUTHOR      : A. Del Padrone

LOADING INSTRUCTIONS
-- Enter
       $contrib/invariants.Man();
   to get a complete description of the package including a suggested alias.
-- Enter
       $contrib/invariants.About();
   to find the version number.  You may want to check the CoCoA
   homepage for the latest version.
</verbatim>
    </description>

      <keys>
        <key>invariance</key>
	<key>del padrone</key>
      </keys>
      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Primary Ideals</title>
        <type>2</type>

        <description>
<!-- ***** NOT YET UPDATED TO CoCoA-5: follow with care ***** -->
<!-- <par/> -->
<!-- Supported CoCoA Package -->
<!-- <verbatim> -->
<!-- TITLE       : primary.cpkg -->
<!-- DESCRIPTION : CoCoA package for applying toric ideals to integer -->
<!--               programming -->
<!-- AUTHORS     : A. Bigatti, L. Robbiano -->

<!-- LOADING INSTRUCTIONS -->
<!--  Enter -->
<!--        $contrib/primary.Man(); -->
<!--    to get a complete description of the package including a suggested alias. -->
<!--  Enter -->
<!--        $contrib/primary.About(); -->
<!--    to find the version number.  You may want to check the CoCoA -->
<!--    homepage for the latest version. -->
<!-- </verbatim> -->
    </description>

      <seealso>
        <see>InitialIdeal</see>
        <see>TgCone</see>
	<see>PrimaryPoincare</see>
      </seealso>

      <keys>
        <key>initial ideal</key>
        <key>tangent cone</key>
	<key>bigatti robbiano</key>
      </keys>
      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Special Varieties</title>
        <type>2</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
Supported CoCoA Package
<verbatim>
TITLE       : specvar.cpkg
DESCRIPTION : CoCoA package for computing the Hilbert-Poincare
              series of special varieties (Segre, Veronese, Rees).
AUTHORS     : A. Bigatti, L. Robbiano

LOADING INSTRUCTIONS
-- Enter
       $contrib/specvar.Man();
   to get a complete description of the package including a suggested alias.
-- Enter
       $contrib/specvar.About();
   to find the version number.  You may want to check the CoCoA
   homepage for the latest version.
</verbatim>
    </description>

      <keys>
        <key>rees</key>
        <key>segre</key>
        <key>veronese</key>
	<key>bigatti robbiano</key>
      </keys>
      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Statistics</title>
        <type>2</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
Supported CoCoA Package
<verbatim>
TITLE       : stat.cpkg
DESCRIPTION : package for design of experiments in statistics
AUTHOR      : M. Caboara

LOADING INSTRUCTIONS
-- Enter
       $contrib/stat.Man();
   to get a complete description of the package including a suggested alias.
-- Enter
       $contrib/stat.About();
   to find the version number.  You may want to check the CoCoA
   homepage for the latest version.
</verbatim>
    </description>

      <keys>
        <key>design of experiments</key>
	<key>caboara</key>
      </keys>
      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Geometrical Theorem-Proving</title>
        <type>2</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
Supported CoCoA Package
<verbatim>
TITLE       : thmproving.cpkg
DESCRIPTION : CoCoA package for geometrical theorem-proving in euclidean space
AUTHOR      : L. Bazzotti, G. Dalzotto

LOADING INSTRUCTIONS
-- Enter
       $contrib/thmproving.Man();
   to get a complete description of the package including a suggested alias.
-- Enter
       $contrib/thmproving.About();
   to find the version number.  You may want to check the CoCoA
   homepage for the latest version.
</verbatim>
    </description>

      <keys>
        <key>thmproving</key>
        <key>hypothesis</key>
        <key>thesis</key>
	<key>bazzotti dalzotto</key>
      </keys>
      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Typevectors</title>
        <type>2</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
Supported CoCoA Package
<verbatim>
TITLE       : typevectors.cpkg
DESCRIPTION : CoCoA package for computing type-vectors associated to
              Hilbert functions of ideals of points
AUTHOR      : E.Carlini, M.Stewart

LOADING INSTRUCTIONS
-- Enter
       $contrib/typevectors.Man();
   to get a complete description of the package including a suggested alias.
-- Enter
       $contrib/typevectors.About();
   to find the version number.  You may want to check the CoCoA
   homepage for the latest version.
</verbatim>
    </description>

      <keys>
        <key>type-vectors</key>
        <key>type vectors</key>
        <key>hilbert functions of points</key>
	<key>carlini stewart</key>
      </keys>
      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Conductor</title>
        <type>2</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
Supported CoCoA Package
<verbatim>
TITLE       : conductor.cpkg
DESCRIPTION : CoCoA package for computing conductor sequence of points
AUTHOR      : L.Bazzotti

LOADING INSTRUCTIONS
-- Enter
       $contrib/conductor.Man();
   to get a complete description of the package including a suggested alias.
-- Enter
       $contrib/conductor.About();
   to find the version number.  You may want to check the CoCoA
   homepage for the latest version.
</verbatim>
    </description>

      <keys>
        <key>bazzotti</key>
      </keys>
      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Matrix Normal Form</title>
        <type>2</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
Supported CoCoA Package
<verbatim>
TITLE       : matrixnormalform.cpkg
DESCRIPTION : CoCoA package for computing normal forms of a matrix,
              Smith Normal Form (PID)
AUTHOR      : A.Bigatti, S.DeFrancisci

LOADING INSTRUCTIONS
-- Enter
       $contrib/matrixnormalform.Man();
   to get a complete description of the package including a suggested alias.
-- Enter
       $contrib/matrixnormalform.About();
   to find the version number.  You may want to check the CoCoA
   homepage for the latest version.
</verbatim>
    </description>

      <keys>
        <key>matrixnormalform</key>
        <key>smith normal form</key>
        <key>principal ideal domain, PID</key>
        <key>bigatti de francisci</key>
      </keys>
      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>CantStop</title>
        <type>2</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
Supported CoCoA Package
<verbatim>
TITLE       : CantStop.cpkg
DESCRIPTION : CoCoA package for playing  Can't Stop  and studying strategies
AUTHOR      : A.Bigatti

LOADING INSTRUCTIONS
-- Enter
       $contrib/CantStop.Man();
   to get a complete description of the package including a suggested alias.
-- Enter
       $contrib/CantStop.About();
   to find the version number.  You may want to check the CoCoA
   homepage for the latest version.
</verbatim>
    </description>

      <keys>
        <key>game</key>
        <key>play</key>
        <key>bigatti</key>
      </keys>
      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Control</title>
        <type>2</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
Supported CoCoA Package
<verbatim>
TITLE       : control.cpkg
DESCRIPTION : CoCoA package for Geometric Control Theory
AUTHOR      : M. Anderlucci and M. Caboara

LOADING INSTRUCTIONS
-- Enter
       $contrib/control.Man();
   to get a complete description of the package including a suggested alias.
-- Enter
       $contrib/control.About();
   to find the version number.  You may want to check the CoCoA
   homepage for the latest version.
</verbatim>
    </description>

      <keys>
        <key>control theory</key>
	<key>geometric theory of control</key>
        <key>anderlucci caboara</key>
      </keys>
      </section>

    </chapter>

  </part>

  <part>
    <title>Doing Mathematics with CoCoA</title>
<!-- ===  CHAPTER  =============================================== -->
    <chapter>
      <title>Booleans</title>
<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Introduction to Booleans</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
The two boolean constants are <tt>True</tt> and <tt>False</tt>.  They are mainly used
with the commands <ttref>If</ttref> and <ttref>While</ttref>, etc., inside CoCoA programs.  The
relational operators
<verbatim>
    =  &lt;&gt;  &lt;  &lt;=  &gt;  &gt;=
</verbatim>
return boolean constants (see <ref>Relational Operators</ref>).  The boolean
operators are
<verbatim>
    And  Or  IsIn  not(...)
</verbatim>
and return boolean constants and are described below.

    </description>

      <keys>
        <key>true</key>
        <key>false</key>
      </keys>
	<seealso>
          <see>Relational Operators</see>
          <see>Boolean Operators</see>
	</seealso>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Commands and Functions for Booleans</title>
        <type>1</type>

        <description>
<par/>
The following are commands and functions for booleans:
<commands_and_functions_for type="boolean"></commands_and_functions_for>
    </description>

      </section>

    </chapter>

<!-- ===  CHAPTER  =============================================== -->
    <chapter>
      <title>Numbers</title>
<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Introduction to Numbers</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
There are three types of numbers recognized by CoCoA: integers (type
<tt>INT</tt>), rationals (type <tt>RAT</tt>), and modular integers (type <tt>ZMOD</tt>).  Numbers
in CoCoA are handled with arbitrary precision.  This means that the
sizes of numbers are only limited by the amount of available memory.
The basic numeric operations---addition (<tt>+</tt>), subtraction (<tt>-</tt>),
multiplication (<tt>*</tt>), division (<tt>/</tt>), exponentiation (<tt>^</tt>), and negation
(<tt>-</tt>)---behave as one would expect.  Be careful, two adjacent minus
signs, <tt>--</tt>, start a comment in CoCoA.

<example>
  N := 3;
  -N;
-3
-------------------------------
--N;
</example>
The last line in the above example does not return 3; it is
interpreted as a comment.
    </description>

      <keys>
        <key>integers</key>
      </keys>
      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Rationals</title>
        <type>2</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
Rational numbers can be entered as fractions or as terminating
decimals.  CoCoA always converts a rational number into a fraction in
lowest terms.

<example>
  3/5;
3/5
-------------------------------
  3.8;
19/5
-------------------------------
  N := 4/8;
  N;
1/2
-------------------------------
</example>
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Numerators and Denominators for Rational Numbers</title>
        <type>3</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
If F is a variable holding a fraction, then <tt>F.Num</tt> and <tt>F.Den</tt> are the
numerator and denominator, respectively.  The functions <tt>Num</tt> and
<tt>Den</tt>, respectively, return the same.

<example>
  F := 3/5;
  F.Num;
3
-------------------------------
  F.Den;
5
-------------------------------
  Den(F);
5
-------------------------------
  1.75;
7/4
-------------------------------
  It.Num;
7
-------------------------------
</example>
    </description>

	<seealso>
          <see>Den</see>
          <see>Num</see>
	</seealso>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Modular Integers</title>
        <type>2</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
Let A and B be integers.  The expression <tt>A%B</tt> has type <tt>ZMOD</tt> and
represents the class of A modulo B.  The integer B should be greater
than 0 and less then <formula>32767 = 2<sup>15</sup> - 1</formula>.
<par/>
When a modular integer is evaluated by CoCoA, it is reduced to a
canonical form <tt>A%B</tt> with <formula>-B/2 &lt; A <less_eq/> B/2</formula>.
<par/>
Two modular integers of the form <tt>A%C</tt> and <tt>B%C</tt> are said to be
<em>compatible</em>, and the usual arithmetical operations are applicable.

<example>
  3%7;
3 % 7
-------------------------------
  4%7;
-3 % 7
-------------------------------
  2%5 + 4%5;
1 % 5
-------------------------------
  type(3%11);
ZMOD
-------------------------------
  3%11 = 14%11;
True
-------------------------------
  3%11 * 3;
-2 % 11
-------------------------------
  3%11 = 3;  -- better and error than an unexpected answer!
ERROR: Cannot cast INT to ZMOD
CONTEXT:  ZPMK(3, 11) = 3
-------------------------------
</example>
Use the functions <ttref>div</ttref> and <ttref>mod</ttref> for quotients and remainders.
    </description>

      <keys>
        <key>zmod</key>
      </keys>
	<seealso>
          <see>div</see>
          <see>mod</see>
	</seealso>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Commands and Functions for Numbers</title>
        <type>1</type>

        <description>
<par/>
The following are commands and functions for numbers:
<par/>
INTEGERS
<commands_and_functions_for type="integer"></commands_and_functions_for>
RATIONALS
<commands_and_functions_for type="rat"></commands_and_functions_for>
MODULAR INTEGERS
<commands_and_functions_for type="zmod"></commands_and_functions_for>
    </description>

      </section>

    </chapter>

<!-- ===  CHAPTER  =============================================== -->
    <chapter>
      <title>Strings</title>
<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Introduction to Strings</title>
        <type>1</type>

        <description>

A string constant consists of a sequence of characters between double
quotes (<quotes> </quotes>).
An old, obsolescent syntax is still accepted for the time being.
<par/>
CoCoA offers on a few operations on strings: length, concatenation, and
indexing.
<example>
/**/ Print "String containing \" character";
String containing " character
/**/ mesg1 := "Hello";
/**/ mesg2 := "World!";
/**/ mesg1+mesg2; -- concatenation
HelloWorld!
/**/ len(mesg1);
5
/**/ mesg1[1]; -- character indexing
H
</example>

    </description>

	<seealso>
          <see>ascii</see>
          <see>len</see>
          <see>operators</see>
          <see>Concatenation</see>
          <see>concat</see>
          <see>ConcatLists</see>
          <see>Substrings</see>
          <see>Quotes Within Strings</see>
	</seealso>

<keys>
  <key>concatenation</key>
  <key>characters</key>
  <key>literal</key>
</keys>
      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Concatenation</title>
        <type>2</type>

        <description>
<par/>
Strings may be concatenated using <tt>+</tt>.

<example>
/**/  L := "hello ";
/**/  M := "world";
/**/  L + M;
hello world
</example>
    </description>

	<seealso>
          <see>concat</see>
          <see>ConcatLists</see>
	</seealso>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Substrings</title>
        <type>2</type>

        <description>
If L is a string and N is an integer, then L[N] is the N-th character
of L.

<example>
/**/  L := "hello world";
/**/  L[2];
e
</example>

The operator <ttref>IsIn</ttref> can be used to test if one string is
a substring of another.

<example>
/**/  L := "hello world";
/**/  "hello" IsIn L;
true
</example>
    </description>

	<seealso>
          <see>IsIn</see>
	</seealso>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Quotes Within Strings</title>
        <type>2</type>

        <description>
OBSOLETE!!!
Strings are delimited using double quotes (or single quotes, obsolescent).
<par/>
To get double quotes inside a string, quotes must be <em>escaped</em>
by preceding them with a backslash.
<par/>
Note: from 4.7.5 escaping quotes by doubling them is obsolescent.

<example>
  Print "This string <backslash/>"contains<backslash/>" double quotes.";
This string "contains" double quotes.
-------------------------------
  Print "This string <backslash/>"contains<backslash/>" quotes of &apos;various&apos; styles.";
This string "contains" quotes of &apos;various&apos; styles.
-------------------------------
</example>
<!-- Imagine the difficulties in writing this section of the online manual -->
<!-- within a CoCoA package. <formula>;&gt;</formula> -->
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Commands and Functions for Strings</title>
        <type>1</type>

        <description>
<par/>
The following are commands and functions for strings:
<commands_and_functions_for type="string"></commands_and_functions_for>
    </description>

      </section>

    </chapter>

<!-- ===  CHAPTER  =============================================== -->
    <chapter>
      <title>Lists</title>
<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Introduction to Lists</title>
        <type>1</type>

        <description>
<par/>
A CoCoA list is a sequence of CoCoA objects between brackets.  In
particular, a list may contain other lists.  The empty list is <tt>[]</tt>.  If
L is a list and N is an integer, then L[N] is the N-th component of
L.  If L contains sublists, then        <tt>L[N_1, N_2,...,N_s]</tt>
is shorthand for <tt>L[N_1][N_2]...[N_s]</tt> (see the example below).  Lists
are often used to build structured objects of type <tt>MAT</tt>, <tt>MODULEELEM</tt>, <tt>IDEAL</tt>,
and <tt>MODULE</tt>.

<example>
/**/  Use R ::= QQ[t,x,y,z];
/**/  L := [34*x+y^2, "a string", [], [True, False]]; -- a list
/**/  L[1];  -- the 1st component
y^2 +34*x
/**/  L[2];
a string
/**/  L[3];
[ ]
/**/  L[4];  -- The 4th component is a list, itself;
[true, false]
/**/  L[4][1]; -- its 1st component;
true
/**/  L[4,1];  -- the same.
true

/**/  [1,"a"]+[2,"b"];  -- Note: one may add lists if their components are
[3, "ab"]               -- compatible (see "Algebraic Operators").

/**/  L := [x^2-y, t*y^2-z^3];
/**/  I := ideal(L);
/**/  I;
ideal(x^2 -y, t*y^2 -z^3)
</example>
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
<section>
  <title>Commands and Functions for Lists</title>
  <type>1</type>
  
  <description>
CoCoA provides a variety of commands for manipulating lists.  Note in
particular the command <ttref>In</ttref> which is useful for building lists.
<par/>
The following are commands and functions for lists:
<commands_and_functions_for type="list"></commands_and_functions_for>
  </description>
  
</section>

    </chapter>

<!-- ===  CHAPTER  =============================================== -->
    <chapter>
      <title>Records</title>
<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Introduction to Records</title>
        <type>1</type>

        <description>
A record is a data type in CoCoA representing a list of bindings of
the form <em>name to object</em>.

<example>
/**/  Use R ::= QQ[x,y,z];
/**/  P := Record[ I := ideal(x,y^2-z), F := x^2 + y, Misc := [1,3,4]];
/**/  P.I;
ideal(x, y^2 -z)
/**/ P["I"];
ideal(x, y^2 -z)

/**/  P.Misc;
[1, 3, 4]
/**/  P.Misc[2];
3

/**/  P.Date := "1/1/98";
/**/ indent(P);
Record[
  Date := "1/1/98",
  F := x^2 +y,
  I := ideal(x, y^2 -z),
  Misc := [1, 3, 4]
]

/**/  P["Misc",3];  -- equivalent to P.Misc[3]
4
</example>

Each entry in a record is called a <em>field</em>.  Note that records are
<em>open</em> in the sense that their fields can be extended, as shown in
the previous example.  At present, there is no function for deleting
fields from a record, one must rewrite the record, selecting the
fields to retain:

<example>
/**/   P := Record[A := 2, B := 3, C := 5, D := 7];
/**/   Q := Record[];

  Foreach F In Fields(P) Do
    If F &lt;&gt; "C" Then Q[F] := P[F]; EndIf;
  EndForeach;

/**/  P := Q;
/**/  P;
Record[A := 2, B := 3, D := 7]
</example>
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
<section>
  <title>Commands and Functions for Records</title>
  <type>1</type>
  
  <description>
The following are commands and functions for records:
<commands_and_functions_for type="record"></commands_and_functions_for>
  </description>
  
</section>

    </chapter>

<!-- ===  CHAPTER  =============================================== -->
    <chapter>
      <title>Vectors</title>
<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Introduction to Vectors</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
An object of type MODULEELEM in CoCoA represents a vector of
polynomials.  If V is a vector and F is a polynomial, then the
following are also vectors:
<verbatim>
   +V, -V, F*V, V*F.
</verbatim>
If V and W are vectors with the same number of components, then one
may add and subtract V and W componentwise:
<verbatim>
    V+W, V-W.
</verbatim>

<example>
  Use R ::= QQ[x,y];
  V := Vector(x+1,y, xy^2);
  V;
Vector(x + 1, y, xy^2)
-------------------------------
  -V;
Vector(-x - 1, -y, -xy^2)
-------------------------------
  x*V;
Vector(x^2 + x, xy, x^2y^2)
-------------------------------
  W := Vector(x, y, x^2y^2-y);
  x*V-W;
Vector(x^2, xy - y, y)
-------------------------------
</example>
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
<section>
  <title>Commands and Functions for ModuleElem</title>
  <type>1</type>

  <description>
The following are commands and functions for vectors:
<commands_and_functions_for type="moduleelem"></commands_and_functions_for>
  </description>
  
</section>

    </chapter>

<!-- ===  CHAPTER  =============================================== -->
    <chapter>
      <title>Matrices</title>
<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Introduction to Matrices</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
An m x n matrix is represented in CoCoA by the list of its rows
<verbatim>
  matrix([R_1,...,R_m])
</verbatim>
where each <tt>R_i</tt> is of type <tt>LIST</tt> and has length n.  A matrix has type
<tt>MAT</tt>.  The (A,B)-th entry of a matrix M is given by <tt>M[A][B]</tt> or <tt>M[A,B]</tt>.

<example>
  Use R ::= QQ[x,y,z];
  M := mat([[x, y, xy^2], [y, z^2, 2+x]]);
  M;
mat([
  [x, y, xy^2],
  [y, z^2, x + 2]
])
-------------------------------
  M[1][3];
xy^2
-------------------------------
  M[1,3];
xy^2
-------------------------------
</example>

The following operations are defined as one would expect for matrices
<verbatim>
  M^A, +M, -N, M+N, M-N, M*N, F*M, M*F
</verbatim>
where M, N are matrices, A is a non-negative integer, and F is a
polynomial or rational function, with the obvious restrictions on the
dimensions of the matrices involved.

<example>
  Use R ::= QQ[x,y];
  N := mat([[1,2],[3,4]]);
  N^2;
mat([
  [7, 10],
  [15, 22]
])
-------------------------------
  x/y * N;
mat([
  [x/y, 2x/y],
  [3x/y, 4x/y]
])
-------------------------------
  N + mat([[x,x], [y,y]]);
mat([
  [x + 1, x + 2],
  [y + 3, y + 4]
])
-------------------------------
</example>
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
<section>
  <title>Commands and Functions for Matrices</title>
  <type>1</type>
  
  <description>
The following are commands and functions for matrices:
<commands_and_functions_for type="matrix"></commands_and_functions_for>
  </description>
</section>

    </chapter>
    
<!-- ===  CHAPTER  =============================================== -->
    <chapter>
      <title>Rings</title>
<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Introduction to Rings</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
Polynomial rings play a central role in CoCoA. Indeed, every object
in CoCoA is defined over a base ring which is a polynomial ring. The
user can define many rings, but at any time a <em>current ring</em> is
active within the system.  Most commands use the current ring as the
base ring.
<par/>
Once a ring has been defined, the system can handle the following
mathematical objects defined over that ring:
<verbatim>
 * numbers (integers, rationals, modular integers);
 * polynomials;
 * vectors of polynomials;
 * rational functions;
 * ideals;
 * modules (submodules of a free module);
 * lists of objects;
 * matrices of objects.
</verbatim>
Variables containing ring-dependent objects such as polynomials,
ideals, and modules are <em>labeled</em> by their ring.  Variables
containing objects such as integers which are not dependent on a
particular ring are not labeled.
<par/>
IMPORTANT NOTE: Starting with CoCoA 3.5, variables are no longer local
to specific rings, i.e., all variables are accessible from all rings.
<par/>
The next sections explains how to create a ring.
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>New Rings</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
CoCoA starts with the default ring R = QQ[t,x,y,z].  The command for
building a new ring is:
<verbatim>
          I ::= C[X:INDETS]
</verbatim>
or
<verbatim>
          I ::= C[X:INDETS], M_1, ... , M_n
</verbatim>

where I is the identifier of a CoCoALanguage variable, C: RING is an
expression defining a coefficient ring (ZZ, QQ or ZZ/(N)), X is an
expression that defines the indeterminates, and the <tt>M_i</tt> are
<em>modifiers</em>.  Each of these components is discussed in separate
sections, below.
<par/>
The modifiers are used to modify the default settings of the base
ring. The modifiers are of three classes: term-orderings, weights,
term orderings for modules.  These classes are discussed in separate
sections below.  It is possible to have no modifiers.  The default
values are: DegRevLex for the term-ordering, 1 for the weight of each
indeterminate, and ToPos for the module term-ordering.
<par/>
After the ring is defined using the above syntax, it can be made to be
the current ring with the command <ttref>Use</ttref> or it can be accessed
temporarily from within the current ring with the command
<ttref>Using</ttref>.  See these two commands for more information.  There are also
several examples of ring-building in the tutorial.

<example>
  Use R ::= QQ[x,y,z];  -- define and use the ring R
  S ::= ZZ/(103)[x,y], Lex; -- define the ring S with Lex term-ordering
  CurrentRing();  -- the current ring is still R
QQ[x,y,z]
-------------------------------
  Use S; -- now the ring S is the current ring
ZZ/(103)[x,y]
-------------------------------
  Using R Do X := z^2-3 EndUsing;  -- define a variable in R (not the current
                                   -- ring)
  Y := R::x^2+y^2+z^2;  -- another way of defining a variable in R while
                        -- S is the current ring
  T ::= QQ[x[1..4],y[1..5,1..5]], Elim(y[1..5,1]), ToPos; -- a more
                                                          -- complicated ring
</example>
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Coefficient Rings</title>
        <type>2</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
As mentioned above, the coefficient ring for a CoCoA polynomial ring
may be:
<verbatim>
 1. ZZ: (arbitrarily large) integer numbers;
 2. QQ: (arbitrarily large) rational numbers;
 3. ZZ/(N): (see <ttref>CocoaLimits</ttref>) integers modulo N,
</verbatim>
You may also use <tt>Q</tt> and <tt>Z</tt>, but from version
4.7.4 <tt>QQ</tt> and <tt>ZZ</tt> are strongly recommended for
compatibility with the forthcoming version 5.

While waiting for CoCoA-5, you may also perform some Groebner-related
operations, such as GBasis5x, LT5x, Intersersection5x, with
coefficients in K(a,b,c), where K is one of the above fields:
see <ref>GBasis5, and more</ref>.

The first two types of coefficients are based on the GNU-gmp library.
When integers modulo N are used, the system checks whether N is a
prime number and, if it is not, a warning message is given.  However
non-prime integers are accepted.  Hence it is possible to do some work
with polynomials whose coefficients are not in a field, but it is up
to the user to ensure that no illegal operation will be attempted.  To
find the upper limit for the characteristic in the third case, see the
field <tt>MaxChar</tt> returned by the function <ttref>CocoaLimits</ttref>; <formula>N <less_eq/> 32767</formula> is
typical.  (Note: 32003 is prime)
<par/>
IMPORTANT NOTE: Presently the implementation of the Buchberger
algorithm for computing Groebner bases operates correctly only if
polynomials have coefficients in a field. So the high level operations
on ideals and modules (and the polynomial GCD) involving Groebner
bases computations work only if polynomials have coefficients in a
field.  Otherwise it is very likely that the user will run into
trouble.
<par/>
<tt>CoeffRing</tt>: When creating a new ring, the word <tt>CoeffRing</tt> may be
used to refer to the current coefficient ring.  Examples below
illustrate its use.

<example>
  Use R ::= QQ[x,y];  -- coefficient ring is Q
  S ::= ZZ/(5)[t]; -- coefficient ring is the field with 5 elements
  T ::= ZZ[u,v]; -- A warning is issued if the coefficient ring
                 -- is not a field.
-- WARNING: Coeffs are not in a field
-- GBasis-related computations could fail to terminate or be wrong
-------------------------------
  Use R ::= ZZ/(2)[x,y,z]; CurrentRing();  -- these examples show the usage
                                           -- of "CoeffRing"
ZZ/(2)[x,y,z]
-------------------------------
  Use S ::= CoeffRing[a,b]; CurrentRing();
ZZ/(2)[a,b]
-------------------------------
</example>
    </description>

    <seealso>
    </seealso>

      <keys>
        <key>coeffring</key>
        <key>parameters</key>
      </keys>
      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Indeterminates</title>
        <type>2</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
An <em>indeterminate</em> is represented by a name consisting of either a
single lower case letter or a lower case letter followed by one or
more indices. For example, <tt>x</tt>, <tt>x[1]</tt>, <tt>x[1,2,3]</tt> are legal (and different)
indeterminates, as is <tt>x[2I,2I+1]</tt> if I is an integer variable.
<par/>
When creating a ring the indeterminates are listed, optionally
separated by commas: lack of separating commas is now obsolescent and
might be unacceptable in future versions.
Indeterminates with indices are formed with the syntax: <tt>x[R_1,...,R_n]</tt>,
where <tt>x</tt> stands for any lower case letter and each <tt>R_i</tt>
has the form <tt>A..B</tt> for integers <tt>A &lt;= B</tt>.

<example>
--    Use R ::= QQ[xyz];  -- this old CoCoA-4 syntax is OBSOLETE
/**/  Use R ::= QQ[x,y,z];
/**/  Use R ::= QQ[x[1..2,4..8],y[1..3],u,v];
/**/  Indets();
[x[1,4], x[1,5], x[1,6], x[1,7], x[1,8], x[2,4], x[2,5], x[2,6],
x[2,7], x[2,8], y[1], y[2], y[3], u, v]
-------------------------------
</example>
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Weights Modifier</title>
        <type>2</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
In forming a ring, one of the possible modifiers that may be added
has one of the forms:
<par/>
(i) <tt>Weights(W_1,...,W_n)</tt> where <tt>W_i</tt> is a
positive integer specifying the weight of the i-th indeterminate (the
number of weights listed must be equal to the number of
indeterminates)
<par/>
(ii) <tt>Weights(M)</tt> where M is a matrix with as many
columns as there are indeterminates.  In the latter case, the i-th
indeterminate has the multi-degree given by the i-th column of M.
<par/>
NB: Because of a choice in the early design (oriented to single
gradings), the first row of the matrix M <em>must</em> have all positive
entries.  CoCoA-5, with a cleaner mathematical foundation, will not
have this limitation.
<par/>
If the weights are not specified the default value is 1 for all indeterminates.

<example>
  Use S ::= QQ[a,b,c], Weights(1,2,3);
  Deg(b);
2
-------------------------------
  L := [1,2,3];
  Use S ::= QQ[a,b,c], Weights(L);
  Deg(b);
2
-------------------------------
  W := mat([[1,2,3],[4,5,6]]);
  Use S ::= QQ[a,b,c], Weights(W);
  Deg(b);
2
-------------------------------
  MDeg(b);  -- the multi-degree of b
[2, 5]
-------------------------------
  Deg(b^3+a^2c);
6
-------------------------------
  MDeg(b^3+a^2c);
[6, 15]
-------------------------------
  WeightsMatrix();
mat([
  [1, 2, 3],
  [4, 5, 6]
])
-------------------------------
  WeightsList(); -- returns the first row of the Weights Matrix
[1, 2, 3]
-------------------------------
</example>
    </description>

	<seealso>
          <see>deg</see>
          <see>wdeg</see>
          <see>WeightsList</see>
          <see>WeightsMatrix</see>
	</seealso>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Orderings</title>
        <type>2</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
Polynomials are always sorted with respect to the ordering of their
base ring.  All the operations involving polynomials utilize and
preserve this ordering. The user can define custom orderings or choose
a predefined term-ordering.  Some commands temporarily change the
term-ordering in order to make a computation.  The various
possibilities are discussed more fully, below.
<par/>
The command <ttref>ord</ttref> can be used both as a modifier to set the ordering
of the ring and as a way to view the matrix defining the current
term-ordering.

<example>
  Use R ::= QQ[x,y,z], Lex;  -- lexicographic term-ordering (predefined)
  Use S ::= QQ[u,v], Ord([[1,1],[2,-3]]);  -- custom term-ordering
  OrdMat(R);  -- the matrix defining the term-ordering for R
mat([
  [1, 0, 0],
  [0, 1, 0],
  [0, 0, 1]
])
-------------------------------
  OrdMat(S);  -- the matrix defining the term-ordering for S
mat([
  [1, 1],
  [2, -3]
])
-------------------------------
</example>
    </description>

	<seealso>
          <see>OrdMat</see>
	</seealso>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Predefined Term-Orderings</title>
        <type>3</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
The predefined term-orderings are:
<par/>
 * degree reverse lexicographic: <tt>DegRevLex</tt>  (the default ordering)
<par/>
 * degree lexicographic: <tt>DegLex</tt>
<par/>
 * pure lexicographic: <tt>Lex</tt>
<par/>
 * pure xel: <tt>Xel</tt>
<par/>
 * elimination term-ordering: <tt>Elim(X:INDETS)</tt>
<par/>
The first two term-orderings use the weights of the indeterminates for
computing the degree of a monomial. If the indeterminates are given in
the order <tt>x_1, ...,x_n</tt>, then <tt>x_1 &gt; ... &gt; x_n</tt> with respect to Lex, but
<tt>x_1 &lt; ... &lt; x_n</tt> with respect to Xel.
<par/>
In the last ordering, X specifies the variables that are to be
eliminated.  It may be a single indeterminate or a range of
indeterminates.  However, X may not be an arbitrary list of
indeterminates; for that, see the command <ttref>elim</ttref> (as opposed to the
modifier <ttref>elim</ttref> being discussed here).  A range of indeterminates can
be specified using the syntax <tt>&lt; first-indet &gt;..&lt; last-indet &gt;</tt>.
Another shortcut: if there are indexed variables of the form, say,  <tt>x[i,j]</tt>,
then <tt>Elim(x)</tt> specifies a term-ordering for eliminating all of the
<tt>x[i,j]</tt>.

<example>
  Use R ::= QQ[x,y,z], Lex;
  x+y+z;
x + y + z
-------------------------------
  Use R ::= QQ[x,y,z], Xel;
  x+y+z;
z + y + x
-------------------------------
  Use R ::= QQ[t,x,y,z], Elim(t);
  I := ideal(t-x, t-y^2, t^2-xz^3);
  GBasis(I);
[t - x, -y^2 + x, xz^3 - x^2]
-------------------------------
  Use R ::= QQ[x[1..5],y,z], Elim(x[5]..y); -- eliminating x[5] and y
  Use R ::= QQ[x[1..5],y,z], Elim(x); -- term-ordering for eliminating all
                                      -- of the x[i]&apos;s
  Ord(); -- OBSOLETE!!!!
mat([
  [1, 1, 1, 1, 1, 0, 0],
  [0, 0, 0, 0, 0, 1, 1],
  [0, 0, 0, 0, 0, 0, -1],
  [0, 0, 0, 0, -1, 0, 0],
  [0, 0, 0, -1, 0, 0, 0],
  [0, 0, -1, 0, 0, 0, 0],
  [0, -1, 0, 0, 0, 0, 0]
])
-------------------------------
</example>
    </description>

      <keys>
        <key>degrevlex</key>
        <key>deglex</key>
        <key>lex</key>
        <key>xel</key>
      </keys>
	<seealso>
          <see>elim</see>
	</seealso>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Temporary Term-Orderings</title>
        <type>3</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
For computations which temporarily require a different term-ordering
(for example, to eliminate variables or to homogenize ideals), the
system automatically changes the term-ordering to a more suitable one,
performs the computation, and then restores the initial term-ordering
and gives its output with respect to this one. In this way the user
never has to deal with temporary changes.

<example>
  Use R ::= QQ[t,x,y,z];
  I := ideal(t-x, y-z, t-z);
  Elim(y, I);
ideal(t - z, -x + z)
-------------------------------
</example>
    </description>

	<seealso>
          <see>elim</see>
          <see>Homogenized</see>
	</seealso>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Custom Term-Orderings</title>
        <type>3</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
For special purposes, the user can enter a custom ordering.  We recall
that each ordering <tt>&gt;</tt> on the set of the terms of a polynomial ring
in n variables corresponds to a (not uniquely determined)
array <tt>(u_1,...,u_s)</tt> of vectors of the real vector
space <formula>R^n</formula>.
More precisely if <formula>a = (a_1,... ,a_n)</formula> and <formula>b = (b_1, ... ,b_n)</formula>
are the n-tuples of the exponents of two terms t and t&apos;, then
<par/>
<formula>t &gt; t&apos; &lt;=&gt; (a*u_1, ..., a*u_s) &gt;_{lex} (b*u_1, ..., b*u_s)</formula>
<par/>
where <formula>&gt;_{lex}</formula> is the ordering on <formula>R^s</formula> given by:
<formula>(c_1,...,c_s)&gt;_{lex} (d_1,...,d_s)</formula> if and only if the first (leftmost)
non-zero coordinate of <formula>(c_1-d_1,...,c_s-d_s)</formula> is positive.
<par/>
CoCoA accepts orderings defined by means of n x n matrices of integers.
This is not a real restriction if one is interested, for instance, in
finding all possible Groebner bases of a given ideal.
<par/>
Moreover <formula>&gt;</formula> is a term-ordering if and only if the matrix whose rows are
the vectors <formula>(u_1,...,u_s)</formula> has maximal rank and is such that the first
non-zero element in each column is positive.
<par/>
To compute a Groebner basis a term-ordering is needed.

<example>
  -- The following CoCoA command defines S to be a polynomial ring and
  -- orders the terms of S using the term-ordering corresponding to the
  -- vectors (1,1,0,0),(0,-1,0,0),(0,0,1,1),(0,0,0,-1):
  Use S ::= QQ[x,y,z,t], Ord( mat([[1, 1, 0, 0],
                                   [0,-1, 0, 0],
                                   [0, 0, 1, 1],
                                   [0, 0, 0,-1]]) );
</example>
    </description>

      <keys>
        <key>custom termorderings</key>
      </keys>
	<seealso>
          <see>OrdMat</see>
	</seealso>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Module Orderings</title>
        <type>2</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
First we recall the definition of a module term-ordering. We assume
that all our free modules have finite rank and are of the type <formula>M = R^r</formula>
where R is a polynomial ring with n indeterminates.  Let
<formula>[e_i|i=1,...,r]</formula> be the canonical basis of M. A <em>term</em> of M is an
element of the form <formula>Te_i</formula> where T belongs to the set T(R) of the terms
of R.  Hence the set T(M), of the terms of M, is in one-to-one
correspondence with the Cartesian product, <formula>T(R)<times/>[1,...,r]</formula>.
<par/>
A <em>module term-ordering</em> is defined as a total ordering <formula>&gt;</formula> on T(M)
such that for all <tt>T, T_1, T_2</tt> in T(R), with T not equal to 1, and for
all i, j in {1,...,r},
<verbatim>
   (1)  T * T_1 * e_i &gt; T_1 * e_i
   (2)  T_1 * e_i &gt; T_2 * e_j  =&gt;  T * T_1 * e_i &gt; T * T_2 * e_j
</verbatim>
Each term-ordering on the current ring induces several term-orderings
on a free module.  CoCoA allows the user to choose between the
following:
<par/>
   * the ordering called <tt>ToPos</tt> (which is the default one) defined by:
<verbatim>
      T_1 * e_i &gt; T_2 * e_j &lt;=&gt;  T_1 &gt; T_2 in R
                                 or, if  T_1 = T_2 , i &lt; j
</verbatim>
   * the ordering called <tt>PosTo</tt> defined by:
<verbatim>
       T_1 * e_i &gt; T_2 * e_j &lt;=&gt; i &lt; j
                                 or, if i = j, T_1 &gt; T_2 in R .
</verbatim>

The leading term of the vector <formula>(x,y^2)</formula> with respect
to two different module term-orderings:

<example>
  Use R ::= QQ[x,y], ToPos;
  LT(Vector(x,y^2));
Vector(0, y^2)
-------------------------------
  Use R ::= QQ[x,y], PosTo;
  LT(Vector(x,y^2));
Vector(x, 0)
-------------------------------
</example>
    </description>

      <keys>
        <key>posto</key>
        <key>topos</key>
      </keys>
      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Accessing Other Rings</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
There are a variety of ways of interacting with a ring outside of the
current ring.  First of all, unlike CoCoA 3.4, starting with CoCoA
3.5, variables are usually assigned to a <em>working memory</em> accessible
from all rings. (The only exceptions are variables prefixed by
<tt>MEMORY</tt>.  See the chapter entitled <ref>Memory Management</ref> for further
information.)  If a variable contains an object which does not depend
on a user-defined ring---for example an integer---that object can be
immediately accessed and used within any ring.  If a variable contains
a ring-dependent object such as a polynomial, an ideal, or a module,
the variable becomes labeled by the ring in which it was defined.
Built-in CoCoA functions should be smart enough to take into account
the rings on which their arguments depend (if you find an exception,
please send a message to <tt>cocoa at dima.unige.it</tt>).
<par/>
To access rings outside of the current ring, one may of course use the
command <ttref>Use</ttref> to change the current ring.  Some other ways of
interacting with outside rings:
<par/>
(1) The <tt>::</tt> construction.  This construction can be used to define
variables or perform operations in rings outside of the current ring.

<example>
  Use R ::= QQ[x,y,z];
  I := ideal(x,y,z)^3;
  I;
ideal(x^3, x^2y, x^2z, xy^2, xyz, xz^2, y^3, y^2z, yz^2, z^3)
-------------------------------
  Use S ::= ZZ/(5)[a,b];
  I;  -- I is labeled by its ring, R
R :: ideal(x^3, x^2y, x^2z, xy^2, xyz, xz^2, y^3, y^2z, yz^2, z^3)
-------------------------------
  RingEnv(I);  -- the name of the ring on which I is dependent
R
-------------------------------
  R:: Poincare(R/I);  -- To be sure, one may prefix any operation
                      -- on I by "R::"  although this should not
                      -- be necessary
(1 + 3a + 6a^2)
-------------------------------
  R:: (x+y)^2;  -- S is still the active ring, but we can perform
                -- operations in R
R :: x^2 + 2xy + y^2
-------------------------------
  J := R :: ideal(x^2-y);  -- while S is active, one may define an
                           -- object dependent on R.  This variable
                           -- becomes part of the working memory.
  J;
R :: ideal(x^2 - y)
-------------------------------
  Use R;
  J;  -- the label is not used if R is active
ideal(x^2 - y)
-------------------------------
</example>

(2) <ttref>Using</ttref>.  From within the current ring one may temporarily perform
commands in an another ring using the command <ttref>Using</ttref>.  A brief
example appears below.  For more information, see the online help
entry for <ttref>Using</ttref>.

<example>
  Use R ::= QQ[x,y];
  S ::= ZZ/(5)[a,b]; -- the current ring is still R
  Using S Do
    X := (a+b)^5;  -- assign a value to a variable in another ring
  EndUsing;
  X;
S :: a^5 + b^5
-------------------------------
  Use S;
  X;
a^5 + b^5
-------------------------------
</example>

(3) <ttref>image</ttref>.  To map objects from one ring to another, one may use the
command <ttref>image</ttref>.  An introduction to this command appears in the
following section and more details can be found in the online help
entry, <ttref>image</ttref>.
<par/>
(4) <tt>QZP</tt>, <tt>ZPQ</tt>.  The commands <tt>QZP</tt> and <tt>ZPQ</tt> can sometimes be used to
quickly map a polynomial or ideal from an outside ring into the
current ring.  See the online help entry, <ttref>QZP</ttref>, <ttref>ZPQ</ttref>, for details.
<par/>
(5) <ttref>BringIn</ttref>. This is the easiest function, but may be
	slow, to map objects from one ring to another.
    </description>

	<seealso>
          <see>image</see>
          <see>QZP</see>
          <see>ZPQ</see>
          <see>Use</see>
	</seealso>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Ring Mappings: the Image Function</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
The function <ttref>image</ttref> implements a ring homomorphism.  Suppose S is
the current ring and R is another ring.  If X is an object in R, the
function <ttref>image</ttref> may be used to substitute polynomials in S for the
indeterminates in X.  An example is given below and complete details
are given in the online help entry for <ttref>image</ttref>.
<par/>
To make substitutions within a single ring, one would usually use
<ttref>eval</ttref> or <ttref>subst</ttref> rather than <ttref>image</ttref>.  To map a polynomial or ideal
from an outside ring into the current ring, the functions <tt>QZP</tt> and
<tt>ZPQ</tt> are sometimes useful.  To map a polynomial or rational function
(or a list, matrix, or vector of these) from R to S without changing
indeterminates, use the function <ttref>BringIn</ttref>.  (<tt>BringIn</tt> is only
applicable if the indeterminates of the object to be mapped are a
subset of those in S.)

<example>
  Use R ::= QQ[a,b,c];
  X := a+b-3c;
  Use S ::= QQ[x,y];
  F := RMap(x^2,2,y^2);  -- syntax for defining a map: the n-th
             -- indeterminate in the domain will be mapped to
             -- the n-th element listed in RMap.
  X; -- X lives in the ring R
R :: a + b - 3c
-------------------------------
  Image(X, F); -- the image of E under the map F
x^2 - 3y^2 + 2
-------------------------------
  Image(R:: (a+b)^2, F);
x^4 + 4x^2 + 4
-------------------------------
</example>
    </description>

	<seealso>
          <see>BringIn</see>
          <see>image</see>
          <see>eval</see>
          <see>QZP</see>
          <see>ZPQ</see>
          <see>subst</see>
	</seealso>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Quotient Rings</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
If <tt>R</tt> is a ring identifier and I is an ideal defined
in <tt>R</tt>,
then <tt>R/I</tt> represents the corresponding quotient ring.
It has type <tt>TAGGED(<quotes>Quotient</quotes>)</tt>.

<example>
  Use R ::= QQ[x,y];
  I := ideal(y-x^2);
  Q := R/I;
  Hilbert(Q);  -- the Hilbert function for Q
H(0) = 1
H(x) = 2   for x &gt;= 1
-------------------------------
</example>
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Commands and Functions for Rings</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
The following are commands and functions controlling rings:
<commands_and_functions_for type="ring"></commands_and_functions_for>
For details look up each item by name.  Online, try
<tt>?ItemName</tt> or <tt>H.Syntax(<quotes>ItemName</quotes>)</tt>.
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Commands and Functions for Ring homomorphisms</title>
        <type>1</type>

        <description>
<par/>
The following are commands and functions controlling rings:
<commands_and_functions_for type="ringhom"></commands_and_functions_for>
For details look up each item by name.  Online, try
<tt>?ItemName</tt> or <tt>H.Syntax(<quotes>ItemName</quotes>)</tt>.
    </description>

      </section>

    </chapter>

<!-- ===  CHAPTER  =============================================== -->
    <chapter>
      <title>Polynomials</title>
<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Introduction to Polynomials</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
An object of type POLY in CoCoA represents a polynomial.  To fix
terminology: a polynomial is a sum of terms; each term is the product
of a coefficient and power-product, a power-product being a product of
powers of indeterminates. (In English it is standard to use <em>monomial</em>
to mean a power-product, however, in other languages, such as Italian,
monomial connotes a power product multiplied by a scalar.  In the
interest of world peace, we will use the term power-product in those
cases where confusion may arise.)

<example>
  The following are CoCoA polynomials:

  Use R ::= QQ[x,y,z];
  F := 3xyz + xy^2;
  F;
xy^2 + 3xyz
-------------------------------
  Use R ::= QQ[x[1..5]];
  Sum([x[N]^2 | N In 1..5]);
x[1]^2 + x[2]^2 + x[3]^2 + x[4]^2 + x[5]^2
-------------------------------
</example>

CoCoA always keeps polynomials ordered with respect to the
term-orderings of their corresponding rings.
<par/>
The following algebraic operations on polynomials are supported:
<verbatim>
  F^N, +F, -F, F*G, F/G if G divides F, F+G, F-G,
</verbatim>
where F, G are polynomials and N is an integer.  The result may be a
rational function.

<example>
  Use R ::= QQ[x,y,z];
  F := x^2+xy;
  G := x;
  F/G;
x + y
-------------------------------
  F/(x+z);
(x^2 + xy)/(x + z)
-------------------------------
  F^2;
x^4 + 2x^3y + x^2y^2
-------------------------------
  F^(-1);
1/(x^2 + xy)
-------------------------------
</example>
    </description>

      <keys>
        <key>power-product</key>
        <key>world peace</key>
      </keys>
      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Evaluation of Polynomials</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
Polynomials may be evaluated using the function <ttref>subst</ttref>.  More
generally, <ttref>subst</ttref> allows one to substitute polynomials from the
current ring for the indeterminates of a given polynomial.  If
substitutions are to be made for each indeterminate, in order, it is
easier to use <ttref>eval</ttref>.  For more general substitutions, see <ttref>image</ttref>.

<example>
  Use R ::= QQ[x,y,z];
  F := x+y+z;
  Eval(F,[2,1]); -- let x=2 and y=1 in F
z + 3
-------------------------------
  Subst(F,[[x,2],[y,1]]);  -- the same thing using Subst
z + 3
-------------------------------
  Subst(F,y,1); -- the syntax is easier when substituting for a single
                -- indeterminate
x + z + 1
-------------------------------
  Subst(F, [[y,x-y], [z,2]]);  -- substitute x-y for y and 2 for z
2x - y + 2
-------------------------------
</example>
    </description>

	<seealso>
          <see>eval</see>
          <see>image</see>
          <see>subst</see>
	</seealso>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Commands and Functions for Polynomials</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
The following are commands and functions for polynomials:
<commands_and_functions_for type="polynomial"></commands_and_functions_for>
For details look up each item by name.  Online, try
<tt>?ItemName</tt> or <tt>H.Syntax(<quotes>ItemName</quotes>)</tt>.
    </description>

      </section>

    </chapter>

<!-- ===  CHAPTER  =============================================== -->
    <chapter>
      <title>Rational Functions</title>
<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Introduction to Rational Functions</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
An object of type RATFUN in CoCoA represents a rational function,
i.e., a quotient of polynomials.  Each rational function is
represented as P/Q where P and Q are polynomials (of type POLY) and
<formula>deg(Q) &gt; 0</formula>.  Common factors of the numerator and denominator are
automatically simplified.  At present, rational functions in CoCoA are
only available over a field.

<example>
  Use R ::= QQ[x,y];
  F := x/(x+y);  -- a rational function
  F*(x+y);
x
-------------------------------
  (x^2-y^2)/(x+y);  -- the result here is a polynomial
x - y
-------------------------------
</example>

The following algebraic operations on rational functions are supported:
<verbatim>
  F^N, +F, -F, F*G, F/G, F+G, F-G,
</verbatim>
where F, G are rational functions and N is an integer.
<par/>
For details look up each item by name.  Online, try
<tt>?ItemName</tt> or <tt>H.Syntax(<quotes>ItemName</quotes>)</tt>.
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Numerators and Denominators for Rational Functions</title>
        <type>2</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
If F is a variable holding a rational function, then F.Num and F.Den
are the numerator and denominator, respectively.  The functions <ttref>Num</ttref>
and <ttref>Den</ttref>, respectively, return the same.

<example>
  F := x/(x+y);
  F.Num;
x
-------------------------------
  F.Den;
x+y
-------------------------------
  Den(F);
x + y
-------------------------------
</example>
    </description>

	<seealso>
          <see>Den</see>
          <see>Num</see>
	</seealso>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Commands and Functions for Rational Functions</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
The following are commands and functions for rational functions:
<commands_and_functions_for type="ratfun"></commands_and_functions_for>
For details look up each item by name.  Online, try
<tt>?ItemName</tt> or <tt>H.Syntax(<quotes>ItemName</quotes>)</tt>.
    </description>

      </section>

    </chapter>

<!-- ===  CHAPTER  =============================================== -->
    <chapter>
      <title>Ideals</title>
<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Introduction to Ideals</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
An object of type IDEAL in CoCoA represents an ideal. An ideal is
formed using the command <tt>ideal(P_1,...,P_n)</tt> where the <tt>P_i</tt> are
generators for the ideal.

<example>
  Use R ::= QQ[x,y];
  I := ideal(x,y^2,2+xy^2);
</example>

The following algebraic operations yield ideals:
<verbatim>
  I^N, I+J, E*F, P:Q
</verbatim>
where: I and J are ideals; N is a non-negative integer; E, F are either
both ideals or one is an ideal and the other is a polynomial; and the
pair (P, Q) has the form (IDEAL, POLY), (IDEAL, IDEAL),
(MODULE, MODULEELEM), (MODULE, MODULE).

<example>
  Use R ::= QQ[x,y];
  I := ideal(x,y^2,2+xy^2);
  I^2;
ideal(x^2, xy^2, x^2y^2 + 2x, y^4, xy^4 + 2y^2, x^2y^4 + 4xy^2 + 4)
-------------------------------
  J := ideal(y);
  I+J;
ideal(x, y^2, xy^2 + 2, y)
-------------------------------
  I*J;
ideal(xy, y^3, xy^3 + 2y)
-------------------------------
</example>
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Commands and Functions for Ideals</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
The following are commands and functions for ideals:
<commands_and_functions_for type="ideal"></commands_and_functions_for>
For details look up each item by name.  Online, try
<tt>?ItemName</tt> or <tt>H.Syntax(<quotes>ItemName</quotes>)</tt>.
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Commands and Functions for Monomial Ideals</title>
        <type>2</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
The following are commands and functions for monomial ideals:
<commands_and_functions_for type="monomialideal"></commands_and_functions_for>
For details look up each item by name.  Online, try
<tt>?ItemName</tt> or <tt>H.Syntax(<quotes>ItemName</quotes>)</tt>.
    </description>

      </section>

    </chapter>

<!-- ===  CHAPTER  =============================================== -->
    <chapter>
      <title>Modules</title>
<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Introduction to Modules</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
An object of type MODULE in CoCoA represents a submodule of a free
module.  A module is represented by its generators as:
<verbatim>
  Module(V_1,...,V_n)
</verbatim>
Each <tt>V_i</tt> has the form <tt>[P_1,...P_r]</tt> or
<tt>Vector(P_1,...P_r)</tt>, where r is the rank of the free
module containing the given module and each <tt>P_j</tt> is of type POLY.
<par/>
As with ideals, information about a module can be accessed using the
same syntax as for records.
<par/>
CoCoA supports quotient modules and modules, as described in the next
section.  Shifts have been disabled in CoCoA 4.

<example>
  Use S ::= QQ[x,y];
  M := Module([x,y^2,2+x^2y],[x,0,y]);  -- define the submodule of S^3
                          -- generated by (x,y^2,2+x^2y) and (x,0,y)
  GBasis(M);
[Vector(x, 0, y), Vector(x, y^2, x^2y + 2)]
-------------------------------
  Describe M;
Record[Type := MODULE, Value := Record[Gens := [[x, y^2, x^2y + 2], [x,
0, y]], MRC := 1, GBasis := [[x, 0, y], [x, y^2, x^2y + 2]]]]
-------------------------------
  M.GBasis;
[Vector(x, 0, y), Vector(x, y^2, x^2y + 2)]
-------------------------------
  M.Gens[1];
Vector(x, y^2, x^2y + 2)
-------------------------------
  M.NumCompts;  -- M is a submodule of a free module of rank 3
3
-------------------------------
</example>
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Quotient Modules</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
If M is a CoCoA module which is a submodule of the free module <formula>R^k</formula>
for some ring <formula>R</formula>, then <formula>R^k/M</formula> represents a quotient module.  It has type
TAGGED(<quotes>Quotient</quotes>).

<example>
  Use R ::= QQ[x,y];
  M := Module([x-y, x^2-y^2, x^3+xy^2], [y, x^2, x^2y]);
  Q := R^3/M;
</example>
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Shifts</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>

<verbatim>
           ===========================================
              THIS FACILITY IS DISABLED IN COCOA 4

           (See the new function <tt>GB.GetNthSyzShifts</tt>;
            read below for an explanation of shifts.)
           ===========================================
</verbatim>

One creates a shifted module in CoCoA using the <ttref>Shifts</ttref> modifier:
<verbatim>
    Module(Shifts([P_1,...,P_r]), V_1,...,V_n)
</verbatim>
where the <tt>P_i</tt>&apos;s are integers or monomials in the current ring and, as
usual, the <tt>V_i</tt>&apos;s are lists of polynomials, each with length r.  This
object represents the submodule, generated by <tt>V_1,...,V_n</tt>, of the free
module of rank r which is the direct sum of <tt>R(P_1),...,R(P_r)</tt>.  Here,
<tt>R(P_i)</tt> is the ring R with shifted degrees.  To explain these shifts,
recall that in a CoCoA ring, the weights of the indeterminates are
given by a weights matrix, say W.  The (multi)weight of the i-th
indeterminate is given by the i-th column of W.  By default, the
weights matrix is a single row of 1s.  If <tt>P_i</tt> is an integer, then the
homogeneous part of <tt>R(P_i)</tt> of degree d is the homogeneous part of R of
degree <tt>d+P_i</tt>.  If <tt>P_i</tt> is a monomial, then the homogeneous part of
<tt>R(P_i)</tt> in multidegree d is the homogeneous part of R in multidegree
<tt>d+deg_W(P_i)</tt>.

<example>
  Use R ::= QQ[x,y,z];
  M := Module([x,y,z],[x^2,y,0]);
  LT(M.Gens[1]);
Vector(x, 0, 0)
-------------------------------
  Deg(M.Gens[1]);
1
-------------------------------
  Ss := Shifts([-3,-5,-2]);
  M := Module(Ss,[x,y,z],[x^2,y,0]);
  M;
Module(Shifts([-3, -5, -2]), [x, y, z], [x^2, y, 0])
-------------------------------
  LT(M.Gens[1]);  -- the leading term changes in the shifted module
Vector(0, y, 0)
-------------------------------
  Deg(M.Gens[1]);
6
-------------------------------
  Use S ::= QQ[x,y,z], Weights(mat([[1,2,3],[4,5,6]]));
  M := Module(Shifts([xy, xz]), [x, y], [x,z]);
  LT(M.Gens[1]);
Vector(0, y)
-------------------------------
  MDeg(M.Gens[1]);  -- multidegree of y in R(xz), i.e. of (xz)y in R
[6, 15]
-------------------------------
</example>
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Commands and Functions for Modules</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
The following are commands and functions for modules:
<commands_and_functions_for type="module"></commands_and_functions_for>
For details look up each item by name.  Online, try
<tt>?ItemName</tt> or <tt>H.Syntax(<quotes>ItemName</quotes>)</tt>.
    </description>

      </section>

    </chapter>

<!-- ===  CHAPTER  =============================================== -->
    <chapter>
      <title>Groebner Bases and Related Computations</title>
<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Introduction to Groebner Bases in CoCoA</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
The heart of the CoCoA system is a implementation of Buchberger&apos;s
algorithm for computing Groebner bases for ideals and modules over
polynomial rings with coefficients in a field.  CoCoA&apos;s Groebner basis
engine can be used to compute Groebner bases, syzygies, free
resolutions, Hilbert functions and Poincare series, and to eliminate
variables and find minimal sets of generators.  Considerable control
over the computations is provided through CoCoA&apos;s <ref>The Interactive
Groebner Framework</ref>.
<par/>
Groebner bases can be calculated over QQ, but large calculations
depending on Groebner bases will take much less time over finite
fields.  A common tactic is to work mod large primes to get an idea
of behavior expected over QQ.
<par/>
It would eventually be nice to have descriptions within this online
help system of the specific algorithms used by CoCoA.  For now, see
<ref>Pointers to the Literature</ref> for references.
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Commands and Functions for Groebner-Type Computations</title>
        <type>2</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
The following are the commands and functions for computations based
on Groebner bases.  In addition to these, there are many commands that
provide finer control over the computations (see the next section:
<ref>The Interactive Groebner Framework</ref>).
<commands_and_functions_for type="groebner"></commands_and_functions_for>
For details look up each item by name.  Online, try
<tt>?ItemName</tt> or <tt>H.Syntax(<quotes>ItemName</quotes>)</tt>.
    </description>

	<seealso>
          <see>The Interactive Groebner Framework</see>
	</seealso>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>The Interactive Groebner Framework</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
For the following computations:
<verbatim>
  * Groebner bases
  * minimal generators
  * syzygies
  * free resolutions
  * elimination of variables
</verbatim>
CoCoA provides the following features:
<verbatim>
  * step-by-step computation
  * monitoring of the execution (verbose mode)
  * various types of truncation (degree, resolution length, or regularity)
  * customization of algorithms (through the GROEBNER panel and P-Series).
</verbatim>
It works like this: instead of using one of the normal Groebner
basis-type commands (listed in the previous section), start the
computation with one of the commands,
<verbatim>
  * GB.Start_GBasis -- start interactive Groebner basis computation
  * GB.Start_MinGens -- start interactive minimal generator calculation
  * GB.Start_Res -- start interactive resolution computation
  * GB.Start_Syz -- start interactive syzygy computation
</verbatim>
After starting the computation, the following commands are available:
<verbatim>
  * GB.Complete -- Complete an interactive Groebner-type calculation
  * GB.GetBettiMatrix -- returns the Betti matrix computed so far
  * GB.GetNthSyz -- returns the part of the Nth syzygy module computed so far
  * GB.GetNthSyzShifts -- shifts of the Nth syzygy module computed so far
  * GB.GetRes -- returns the resolution computed so far
  * GB.GetResLen -- returns the length of the resolution computed so far
  * GB.ResReport -- status of an interactive resolution calculation
  * GB.Stats -- status of an interactive Groebner-type calculation
  * GB.Step, GB.Steps -- take steps in an interactive Groebner-type calculation
  * ReducedGBasis -- compute a reduced Groebner basis
</verbatim>
Almost all of these functions report more information if you set the
Verbose flag in the GROEBNER panel by typing
<verbatim>
  Set Verbose;
</verbatim>
(to unset, enter <tt>Unset Verbose</tt>).  For more possibilities, see
<ref>Options in the GROEBNER Panel</ref>.
<par/>
Use of the Interactive Groebner Framework is illustrated in the
examples below.
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Example: Interactive Groebner Basis Computation</title>
        <type>2</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>

<example>
  Use R ::= QQ[t,x,y,z];
  I := ideal(t^3-x, t^4-y, t^5-z);
  $gb.Start_GBasis(I);  -- start the interactive framework
  I.GBasis;  -- the Groebner basis is initially empty
Null
-------------------------------
  $gb.Steps(I,1); -- a single step of the computation
  I.GBasis;
[t^3 - x]
-------------------------------
  $gb.Steps(I,4); -- 4 more steps
  I.GBasis;
[t^3 - x, -tx + y, t^2y - x^2]
-------------------------------
  $gb.Complete(I); -- complete the computation
  I.GBasis;
[t^3 - x, -tx + y, -ty + z, -y^2 + xz, -x^2 + tz, t^2z - xy]
-------------------------------
  ReducedGBasis(I);
[t^3 - x, tx - y, ty - z, y^2 - xz, x^2 - tz, t^2z - xy]
-------------------------------
</example>

Note that Groebner bases calculated in the interactive framework may
not be reduced, as illustrated in the final step of the example.
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Example: Verbose Mode</title>
        <type>2</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
The following example illustrates the use of <tt>Verbose</tt> mode.  For
more information, see <ref>Verbose</ref>.

<example>
  Set Verbose;
  Use R ::= QQ[t,x,y,z];
  I := ideal(t^3-x, t^4-y, t^5-z);
  G := GBasis(I);
..................18
------------------------------------
 IPs  IVs Gens GBases MinGens MinDeg
------------------------------------
   0    0    3      6       0     -1
------------------------------------
Betti numbers:
18 steps of computation

-------------------------------
  Describe I;  -- more information, (it would help to <tt>Set Indentation</tt>)
Record[Type := IDEAL, Value = Record[Gens := [t^3 - x, t^4 - y, t^5 -
z], GBasis := [t^3 - x, -tx + y, -ty + z, -y^2 + xz, -x^2 + tz, t^2z -
xy], IVs := [ ], Rules := [t^3 - x, t^4 - y, t^5 - z, -tx + y, t^2y -
x^2, x^3 - ty^2, -ty + z, -y^2 + xz, -x^2 + tz, t^2z - xy],
Discrepancy := -1, KFL = [1, 7, 14, 4, 16, 9, 10, 20, 22, 23, 28, 18,
0, 39, 42]]]
-------------------------------
</example>
    </description>

	<seealso>
          <see>Describe</see>
          <see>Verbose</see>
	</seealso>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Example: Interactive Resolution Computation</title>
        <type>2</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
In this example we compute the minimal free resolution of the ideal I
generated by the 2 by 2 minors of a catalecticant matrix, A, using the
interactive environment of the system. We define the ideal I, and
start the computation of its minimal free resolution using the
Hilbert-driven algorithm described in
<par/>
     A. Capani, G. De Dominicis, G. Niesi, L. Robbiano,
     <em>Computing Minimal Finite Free Resolutions</em>,
     J. Pure Appl. Algebra, Vol. 117--118, Pages 105--117, 1997.

<example>
  Use R ::= ZZ/(32003)[z[0..3,0..3,0..3]]; -- set up the ring
  A := mat([                               -- define the ideal
    [z[3,0,0], z[2,1,0], z[2,0,1]],
    [z[2,1,0], z[1,2,0], z[1,1,1]],
    [z[2,0,1], z[1,1,1], z[1,0,2]],
    [z[1,2,0], z[0,3,0], z[0,2,1]],
    [z[1,1,1], z[0,2,1], z[0,1,2]],
    [z[1,0,2], z[0,1,2], z[0,0,3]]
  ]);
  I := ideal(Minors(2, A));
  $gb.Start_Res(I);                        -- start interactive framework
  
  $gb.Steps(I,1000);                       -- first 1000 steps
  $gb.GetRes(I);
0 --&gt; R^176(-5) --&gt; R^189(-4) --&gt; R^105(-3) --&gt; R^27(-2)
-------------------------------
  $gb.ResReport(I);
--------------------------------------------------------------
Minimal Pairs,             :   650
  Groebner Pairs           :    14
  Minimal (Type S)         :   636
      H-Killed (Type S0)   :     9
--------------------------------------------------------------
-------------------------------
  $gb.Complete(I);                        -- complete the calculation
  $gb.GetRes(I);
0 --&gt; R(-9) --&gt; R^27(-7) --&gt; R^105(-6) --&gt; R^189(-5) --&gt;
   R^189(-4) --&gt; R^105(-3) --&gt; R^27(-2)
-------------------------------
  $gb.ResReport(I);
--------------------------------------------------------------
Minimal Pairs,             :   730
  Groebner Pairs           :    25
  Minimal (Type S)         :   705
    Minimal (Type Smin)    :   616
    Minimal (Type S0)      :    89
      H-Killed (Type S0)   :    78
      Hard (Type S0)       :    11
--------------------------------------------------------------
-------------------------------
</example>
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Example: Truncations</title>
        <type>2</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
The user may assign one or more of three different truncation
conditions to a module: DegTrunc, ResTrunc and RegTrunc; in this case
the execution will stop when a bound is reached (see the examples,
below).
<par/>
For a time limit see <ttref>GBasisTimeout</ttref>.
<par/>
DEGREE TRUNCATION:

<example>
  Use R ::= ZZ/(32003)[a,b,c,d,e];
  I := ideal(a+b+c+d, ab+bc+cd+da, abc+bcd+cda, abcd-e^4);
  I.DegTrunc := 3;
  $gb.Start_GBasis(I);
  $gb.Complete(I);
  [LT(F) | F In I.GBasis];
[a, b^2, bc^2]
-------------------------------
  I.DegTrunc := 6;
  $gb.Complete(I);
  [LT(F) | F In I.GBasis];
[a, b^2, bc^2, bcd^2, c^2d^2, cd^4, be^4, d^2e^4]
-------------------------------
</example>

RESOLUTION TRUNCATION:

<example>
  Use R ::= ZZ/(32003)[x[1..10]];
  I := ideal(Indets());
  I.ResTrunc := 4;
  $gb.Start_Res(I);
  $gb.Complete(I);
  $gb.GetRes(I);
0 --&gt; R^252(-5) --&gt; R^210(-4) --&gt; R^120(-3) --&gt; R^45(-2) --&gt; R^10(-1)
-------------------------------
</example>

REGULARITY TRUNCATION:
We know that the Castelnuovo regularity of I in the following example is 6.

<example>
  Set Verbose;
  Use R_Gen ::= ZZ/(5)[x,y,z,t];
  M := 3; N := 4;
  D := DensePoly(2);
  P := mat([ [ Randomized(D) | J In 1..N ] | I In 1.. M]);
  I := ideal(Minors(2, P));
  $gb.Start_Res(I);
  $gb.Complete(I);
-- text suppressed --
Betti numbers: 17 48 48 18
318 steps of computation

  I := ideal(Minors(2, P));
  $gb.Start_Res(I);
  I.RegTrunc := 6; -- here we store the Castelnuovo Regularity
  $gb.Complete(I);
...
Betti numbers: 17 48 48 18
281 steps of computation

  $gb.GetBettiMatrix(I);
-------------------
   0    0    0    0
   0    0    0    0
   0    0    0    0
   0    0    0   18
   0    0   16    0
   0    0   32    0
   0   48    0    0
  17    0    0    0
-------------------
</example>
    </description>

	<seealso>
	  <see>The Interactive Groebner Framework</see>
	  <see>GBasisTimeout</see>
	</seealso>

      <keys>
        <key>groebner basis</key>
        <key>bound</key>
        <key>limit</key>
        <key>stop</key>
        <key>truncations</key>
        <key>degtrunc</key>
        <key>regtrunc</key>
        <key>restrunc</key>
        <key>degree</key>
        <key>regularity</key>
      </keys>
      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Hilbert-Driven Computations</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
CoCoA Groebner basis algorithms will use knowledge of a Poincare
series to improve efficiency.

<example>
  Use R ::= QQ[w,x,y,z];
  PS := HP.PSeries(1 + 2w + 3w^2 + 4w^3 + 5w^4 + 6w^5 + 5w^6 +
        4w^7 + 3w^8 + 2w^9 + w^10,2);
  PS;
(1 + 2w + 3w^2 + 4w^3 + 5w^4 + 6w^5 + 5w^6 + 4w^7 + 3w^8 + 2w^9 + w^10) / (1-w)^2
-------------------------------
  I := ideal((xy-zw)^3,(xz-yw)^3);
  I.PSeries := PS; -- this is how to let CoCoA know about the Poincare series
  G := GBasis(I);
</example>
    </description>

      </section>

    </chapter>

<!-- ===  CHAPTER  =============================================== -->
    <chapter>
      <title>CoCoAServer</title>
<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Introduction to CoCoAServer</title>
        <type>1</type>
        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
Waiting for the completely new CoCoA-5, based on the C++ library
CoCoALib (open source, GPL), you may get a good feel of the new
capabilities using the CoCoAServer: here the word <em>server</em>
stands for <em>serving process</em> doing the computations for CoCoA
on the same computer (as opposed to <em>computer server</em> which runs,
say, the mail services).
<par/>
You need to start the CoCoAServer before calling these functions
(otherwise an error message will remind you).
You don't need to worry about what this really means: what you
have to do is just pressing a button ;-).  Instructions for starting
the server vary depending on the User Interface you use:
<par/>
[text] From a shell call <tt>COCOADIR/CoCoAServer</tt>.
<par/>
[emacs] From the CoCoA menu select <tt>(re)start CoCoAServer</tt>.
<par/>
It will respond to any other request from you and from other CoCoA-4
processes connected to the same machine on the same port (using <ttref>OpenSocket</ttref>).
You may leave the CoCoAServer running on your computer even if you
don't use it: it takes no cpu time while waiting for requests.

        </description>
      </section>
<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Frobby</title>
        <type>2</type>
        <description>
<par/>
External libraries can be linked with CoCoALib and their functions be
made accessible.
Thanks to Bjarke Hammersholt Roune for linking his library <tt>frobby</tt>
for computations with monomial ideals <tt>http://www.broune.com/frobby/</tt>.

  <commands_and_functions_for type="frobby"></commands_and_functions_for>
        </description>
      </section>
<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Functions using CoCoAServer</title>
        <type>1</type>
        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
The following are the functions using CoCoAServer :
          <commands_and_functions_for type="cocoaserver"></commands_and_functions_for>
        </description>
      </section>
    </chapter>

  </part>
  <part>
    <title>Working the System</title>
<!-- ===  CHAPTER  =============================================== -->
    <chapter>
      <title>CoCoA Panels</title>
<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Introduction to Panels</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
The user can customize some features of CoCoA by setting (or
unsetting) some boolean options (ON/OFF) which are grouped in three
panels.  The function <ttref>panels</ttref> returns the list of panel names, and
the settings in a particular panel can be seen using the function
<ttref>panel</ttref> as illustrated in the example below.

<example>
  Panels();
["GENERAL", "GROEBNER"]
-------------------------------
  Panel(GENERAL);

Echo............... : False
Timer.............. : False
Trace.............. : False
Indentation........ : False
TraceSources....... : False
SuppressWarnings... : False
ComputationStack... : False
-------------------------------
</example>
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Setting Options</title>
        <type>2</type>

        <description>
***** OBSOLETE: NOT PORTED TO CoCoA-5 *****
<par/>
Each option name is unique, not just among the options in a
particular panel, but among the options from all panels.  The command
<tt>Set</tt> followed by an option name (without parentheses or quotes) sets
the corresponding option to True.  Similarly, <tt>Unset</tt> sets the option
to False.  In addition, one may use the <tt>Set</tt> command to set an option
either true or false using the syntax: <tt>Set option-name := True</tt> or
<tt>Set option-name := True</tt>.

<example>
  Use R ::= QQ[x,y,z];
  L := [(x+y)^N | N In 1..3];
  Set Indentation;  -- print each component on a separate line
  L;
[
  x + y,
  x^2 + 2xy + y^2,
  x^3 + 3x^2y + 3xy^2 + y^3]
-------------------------------
  Unset Indentation;
</example>

The function <ttref>Option</ttref> takes as parameter an option name and
returns the (boolean) value of the option.  It is particularly useful
within user-defined functions as illustrated in the example below:

<example>
  Define Print_UnIndented(X)
    Opt := Option(Indentation);
    Unset Indentation;
    Print X;
    Set Indentation := Opt;
  EndDefine;

  R := Record[X:="test", L:=[1,2,3]];
  Set Indentation;
  Print_UnIndented(R);
Record[L := [1, 2, 3], X := "test"]
-------------------------------
  UnSet Indentation;
  Print_UnIndented(R);
Record[L := [1, 2, 3], X := "test"]
-------------------------------
</example>
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Options in the GENERAL Panel</title>
        <type>2</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
The options in the GENERAL panel and their default settings are as
follows:

<example>
  Panel(GENERAL);

Echo............... : False
Timer.............. : False
Trace.............. : False
Indentation........ : False
TraceSources....... : False
SuppressWarnings... : False
ComputationStack... : False
-------------------------------

They are discussed separately, below.
</example>
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Echo</title>
        <type>3</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
If the Echo option is on, then the system echoes every command at the
top level.  When logging a CoCoA session, one would set Echo to True
in order to log both the input as well as the output in a CoCoA
session (see <ttref>OpenLog</ttref>).

<example>
  1+1;
2
-------------------------------
  Set Echo;
  1+1;
1 + 1
2
-------------------------------
  L := [1,2,3];
L := [1, 2, 3]
  Unset Echo;
SET(Echo, False)
  L := [4,5,6];
-------------------------------
</example>
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Timer</title>
        <type>3</type>

        <description>
The CoCoA-4 commands <tt>Set Timer</tt> and <tt>Time</tt> are not
implemented (as such) in CoCoA-5.
See <ttref>CpuTime</ttref> for getting timings in CoCoA-5.
	</description>

	<seealso>
	  <see>CpuTime</see>
	</seealso>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Trace</title>
        <type>3</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
If the Trace option is on, then the system echoes every command at
every level.  This is useful for debugging programs.  The following
(toy) user-defined function returns the same error message for N = 3
and N = 6.  Turning the Trace option on makes the sources of the
trouble clear.

<example>
  Define T(N)
    M := 1/(N-3);
    If N = 6 Then N := 3 EndIf;
    M := 1/(N-3);
    Return M;
  EndDefine;
  T(3);
ERROR: Division by zero
CONTEXT: 1 / (N - 3)
-------------------------------
  T(6);
ERROR: Division by zero
CONTEXT: 1 / (N - 3)
-------------------------------
  Set Trace;
  T(3);
T(3)
M := 1 / (N - 3); If N = 6 Then N := 3 EndIf; M := 1 / (N - 3); Return(M);
M := 1 / (N - 3)
ERROR: Division by zero
CONTEXT: 1 / (N - 3)
-------------------------------
  T(6);
T(6)
M := 1 / (N - 3); If N = 6 Then N := 3 EndIf; M := 1 / (N - 3); Return(M);
M := 1 / (N - 3)
If N = 6 Then N := 3 EndIf
N := 3
M := 1 / (N - 3)
ERROR: Division by zero
CONTEXT: 1 / (N - 3)
-------------------------------
</example>
    </description>

	<seealso>
          <see>ComputationStack</see>
	</seealso>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Indentation</title>
        <type>3</type>

        <description>
The CoCoA-4 command <tt>Set Indentation</tt> is not implemented (as
such) in CoCoA-5.
See <ttref>indent</ttref> for indenting in CoCoA-5.
	</description>

	<seealso>
	  <see>indent</see>
	</seealso>

    </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>TraceSources</title>
        <type>3</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
If the TraceSources option is on, then the name of every file read
with the <ttref>source</ttref> command will be echoed.
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>SuppressWarnings</title>
        <type>3</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
If the SuppressWarnings option is on, then the system suppress warning
statements.

<example>
  Use ZZ/(4);
-- WARNING: Coeffs are not in a field
-- GBasis-related computations could fail to terminate or be wrong
-------------------------------

-------------------------------
  Set SuppressWarnings;
Use ZZ/(4);
</example>
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>ComputationStack</title>
        <type>3</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
If the ComputationStack option is on, a special variable named
<tt>ComputationStack</tt> contains a list tracing errors that occur during
the execution of CoCoA commands.  This option is useful for debugging
programs.

<example>
  Define Test(X)
    If X&gt;=0 Then PrintLn 1/X; EndIf;
  EndDefine;

  Set ComputationStack;
  Test(0);

-------------------------------
ERROR: Division by zero
CONTEXT: 1 / X
-------------------------------
  S := ComputationStack;  -- to save typing later
  S[1];  -- the command that produced the error
PrintLn(1 / X)
-------------------------------
  S[2];  -- S[1] was part of an If-statement
If X &gt;= 0 Then PrintLn(1 / X) EndIf
-------------------------------
  S[3];  -- the command issued by the user
If X &gt;= 0 Then PrintLn(1 / X) EndIf;
-------------------------------
</example>
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Options in the GROEBNER Panel</title>
        <type>2</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
The options in the GROEBNER panel and their default settings are as
follows:

<example>
  Panel(GROEBNER);

Sugar........... : True
FullRed......... : True
SingleStepRed... : False
Verbose......... : False
-------------------------------
</example>
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Sugar</title>
        <type>3</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
If the Sugar option is on, as it is by default, then the critical
pairs are processed by using the <em>sugar</em> strategy: the pairs are
processed in an order which is as close as possible to the order which
would have been chosen if the polynomials had been homogeneous.  For
details, see the article:
<par/>
A. Giovini, T. Mora, G. Niesi, L. Robbiano, C. Traverso,
 <em>`One sugar cube, please&apos;
   or selection strategies in the Buchberger algorithm,</em>
In Proc. ISSAC`91, 49--54 (1991), Stephen M. Watt, editor, New York,
ACM Press.
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>FullRed</title>
        <type>3</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
If FullRed is set to True, then when a normal form is required in any
Groebner-type computation, CoCoA will reduce all monomials in a
polynomial; if FullRed is False, only the leading terms will be
reduced.  The default is to have FullRed set to True.

<example>
  UnSet FullRed;
  Use R ::= QQ[x,y];
  Interreduced([xy^3+y^2+x, x]);
[x, y^2 + x]
-------------------------------
  Set FullRed;
  Interreduced([xy^3+y^2+x, x]);
[x, y^2]
-------------------------------
</example>
    </description>

	<seealso>
          <see>Interreduced</see>
	</seealso>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>SingleStepRed</title>
        <type>3</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
Sorry: documentation not yet available.
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Verbose</title>
        <type>3</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
During a Groebner basis (or Groebner-like) computation prints some
progress information.
Usually one dot represents a reduction.
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Commands and Functions for Panels</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
The following are commands and functions for panels:
<commands_and_functions_for type="panels"></commands_and_functions_for>
For details look up each item by name.  Online, try
<tt>?ItemName</tt> or <tt>H.Syntax(<quotes>ItemName</quotes>)</tt>.
    </description>

      </section>

    </chapter>

<!-- ===  CHAPTER  =============================================== -->
    <chapter>
      <title>CoCoA&apos;s Help System</title>
<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Online Help</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
CoCoA&apos;s online help is roughly divided into two parts: a manual and a
list of commands.  The manual includes a tutorial which can be started
by entering
<par/>
  ?tutorial
<par/>
If you are a new user of CoCoA, the tutorial is a good place to start.
To see the titles of the sections of the online manual, enter
<tt>H.Toc()</tt>; to see a list of commands, enter <tt>H.Commands(<quotes></quotes>)</tt>.
<par/>
Each section of the manual and each command is uniquely identified by
a set of keywords.  The set of keywords always includes the title of
the section or the title of the command.  The online help command <tt>?</tt>
takes a string from the user and searches for a match among the
keywords.  For instance, <tt>?gbasis</tt> will display information
about the function <ttref>GBasis</ttref>.  Note that when using <tt>?</tt>, the keyword
does not appear in quotes.  Also, a semicolon is not required.
<par/>
The command <tt>??</tt> will return a list of entries in the manual that
contain a given keyword.  For instance, <tt>??gbasis</tt> returns
<verbatim>
    See:
      GB.Start_GBasis
      GBasis
      ReducedGBasis
    -------------------------------
</verbatim>
Each command is associated with a list of topics.  (This applies only
to commands, not to sections of the manual.)  The online help function
<tt>H.Commands</tt> takes a string from the user and searches for all matches
among these topics.  For each match, the title of the command and a
brief description is displayed.  For instance, <tt>H.Commands(<quotes>poly</quotes>)</tt>
will find all commands having to do with polynomials.  Information
about a specific command can then be retrieved with <tt>?</tt>.  A list of
topics is provided by <tt>H.Commands()</tt>, with no argument.
<par/>
IMPORTANT NOTE: Searches are case insensitive and your keyword need
only be a substring to make a match.
<par/>
For a thorough description of the search function <tt>?</tt>, type <tt>? ?</tt> with
a space between the two questions marks.
<par/>
Tips on using online help and summary of the online help functions
appear below.  Enter <tt>H.Browse();</tt> to see the next section.
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Quick Tips for Using Online Help</title>
        <type>2</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
Here are some tips for using the online help system:
<par/>
1. Searches are case insensitive and your search string need only be a
substring of a keyword to make a match.  Thus, for instance, to find
the section of the manual entitled <ref>Commands and Functions for Polynomials</ref>, it is enough to type: <tt>?for poly</tt>.
<par/>
2. In general, it is best to start with short keywords in order to
maximize the number of matches.
<par/>
3. If you cannot find a match using <tt>?</tt>, try using <tt>H.Command</tt> to
search by type.  For example, suppose you are looking for a command
that will give the remainder of the division of one polynomial into
another.  Trying <tt>?remainder</tt> produces no matches.  You know
that the command you are looking for operates on polynomials, so try
<tt>H.Command(<quotes>poly</quotes>)</tt>.  It produces a list of a little over 30 commands,
among which will be listed:
<par/>
  * DivAlg -- division algorithm.
<par/>
4.  The command <tt>??keyword</tt>, with two question marks, will list all
matches even if <em>keyword</em> exactly matches a keyword for the online
help system.
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Commands and Functions for Online Help</title>
        <type>2</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
The following are commands and functions for CoCoA online help:
<commands_and_functions_for type="help"></commands_and_functions_for>
For details look up each item by name.  Online, try
<tt>?ItemName</tt> or <tt>H.Syntax(<quotes>ItemName</quotes>)</tt>.  A good place to start is
with the command, <tt>?</tt>, itself. To see more information about <tt>?</tt>,
enter <tt>? ?</tt> (with a space between the two question marks)
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>Other Help</title>
        <type>1</type>

        <description>
<!-- ***** NOT YET UPDATED TO CoCoA-5: follow with care ***** -->
<!-- <par/> -->
<!-- 1. A user may provide help and sometimes (rarely) get help for a -->
<!-- user-defined function using the <tt>Help</tt> feature of the <ttref>Define</ttref> -->
<!-- command. -->

1. The command, <ttref>Describe</ttref>, can be used to find more information about
functions.

<!-- <example> -->
<!--   Describe Function("Insert"); -->
<!-- Define Insert(L, I, O) -->
<!--   $list.Insert(L, I, O) -->
<!-- EndDefine; -->

<!--   Describe Function("$list.Insert"); -->
<!-- Define Insert(L, I, O) -->
<!--   If not(type(L) = LIST) Then -->
<!--     Return(Error(ERR.BAD_PARAMS, ": expected LIST")) -->
<!--   Elif I = len(L) + 1 Then -->
<!--     append(ref L, O) -->
<!--   Elif I &gt; len(L) Then -->
<!--     Return(Error(ERR.INDEX_TOO_BIG, I)) -->
<!--   Elif I &lt;= 0 Then -->
<!--     Return(Error(ERR.INDEX_NEG, I)) -->
<!--   Else -->
<!--     L := Concat([L[J]|J In 1..(I - 1)],[O],[L[J]|J In I..len(L)]); -->
<!--   EndIf; -->
<!-- EndDefine; -->
<!-- </example> -->

<!-- 3. The function, <ttref>functions</ttref>, may be used to list all functions -->
<!-- defined in a package. -->
<!-- Note: <tt>Functions(<quotes>$user</quotes>)</tt> -->
<!-- lists all current user-defined functions. -->

<!-- <example> -->
<!--   Functions("$mat"); -->
<!-- [About(), Man(), Identity(N), Transposed(M), Submat(M, Rows, Cols), -->
<!-- Jacobian(S), Resultant(F, G, X), DirectSum(M1, M2), BlockMat(LL), -->
<!-- ColumnVectors(M), Complement(M, I, J), Bip(M, J), Pfaffian(M), -->
<!-- Sylvester(F, G, X), ExtendRows(M, N), PushRows(M, N), ConcatRows(L), -->
<!-- PkgName()] -->
<!-- </example> -->

<!-- The list of packages is given by <tt>Packages()</tt>. -->
<!-- <par/> -->
2. The function <tt>starting(S)</tt> returns a list of all
functions starting with the substring <tt>S</tt>.

<!-- <example> -->
<!--   Starting("Su"); -->
<!-- ["SubstPoly", "SubSet", "Submat", "Sum", "Subst", "Support"] -->
<!-- </example> -->
    </description>

      </section>

    </chapter>

<!-- ===  CHAPTER  =============================================== -->
    <chapter>
      <title>Fine Tuning At Start-up</title>
<!-- ===  SECTION  =============================================== -->
      <section>
        <title>User Initialization</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
At the beginning of a CoCoA session, CoCoA reads in a file called
<tt>init.coc</tt>.  This file performs certain initialization routines, reads
in standard packages, and sets up global aliases for the packages.  It
also reads in a file called <tt>userinit.coc</tt>.  It is in this latter file
that users should put their own commands to be run when CoCoA starts.
<par/>
For example, suppose a user wants a file called <tt>MyFile.coc</tt>---
containing function definitions, variable assignments, etc.---to
automatically be read into the CoCoA system on start-up.  It suffices
to add the following line to <tt>userinit.coc</tt>:
<verbatim>
  Source <quotes>MyFile.cocoa</quotes>;
</verbatim>
To load the package with identifier <tt>$contrib/mypackage</tt>, contained in a
file <tt>MyPackage.cpkg</tt> and use MP as an alias, it suffices to add the
following lines to <tt>userinit.coc</tt> (you may want to look at the section
of the manual entitled <ref>Package Sourcing and Autoloading</ref> for more details):
<verbatim>
  Source <quotes>MyPackage.cpkg</quotes>;
  alias MP := $contrib/mypackage;
</verbatim>
    </description>

      </section>

    </chapter>

<!-- ===  CHAPTER  =============================================== -->
    <chapter>
      <title>CoCoA Interfaces</title>
<!-- ===  SECTION  =============================================== -->
      <section>
        <title>CoCoA on a Macintosh</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
For the GUI (Graphical User Interface) follow the specific pages
in the graphical manual, for the textual interface follow the
instruction for Unix.

The following lines refer to the old CoCoA-4.0 for Macintosh OS 9.

The CoCoA user interface on the Macintosh OS 9 is based on Mel Park&apos;s
PlainText (v.1.6) which handles very large text files (larger than
32K).  It uses standard Macintosh editing techniques, so Macintosh
users should be familiar with its basic operations.
<par/>
Double-clicking on the CoCoA icon or on the icon of a CoCoA document
will start up the system. The system draws the menu bar, opens a text
editing window and loads the CoCoA packages and then possibly user&apos;s
packages (via the <tt>userinit.coc</tt> file).
<par/>
After the system is started, it is ready to receive and execute
commands.  To execute a CoCoA command, type it into the window, ending
it with a semicolon, then press the <em>enter</em> key. If the command
occupies more than one line then highlight the whole command using the
mouse and then press the <em>enter</em> key.
<par/>
At this point the following part of the text of the active window is
taken as being the <em>current command</em>:
<par/>
 * if there is no selection (the cursor is blinking somewhere), then
   the row containing the cursor is taken as current command;
<par/>
 * if there is a non-null selection range, then the whole selection is
   taken as current command (in this way the system can process multiline
   commands).
<par/>
The editor uses all the standard Macintosh editing techniques as well as
some special ones:
<par/>
 * Double-clicking on a word select the entire word.
 * Triple-clicking anywhere in a line selects the whole line.
 * Double-clicking on or just before a parenthesis, a bracket, or a
   brace, i.e. one of following symbols <tt>(</tt> , <tt>)</tt> , <tt>[</tt> , <tt>]</tt> , <tt>{</tt> ,
   <tt>}</tt> causes all the text between that symbol and its matching symbol
   to become selected.
<par/>
IMPORTANT NOTE. Devices of type FILE are not yet available with the
Macintosh interface.
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
        <title>CoCoA under Unix</title>
        <type>1</type>

        <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
Probably the best way to run CoCoA under Unix is through the editor
emacs.  In that way, one may easily edit or repeat commands.
From within emacs, issue the command <tt>META-x shell</tt>.  You
will be presented with a Unix prompt within emacs.  Change to the
CoCoA directory, and start CoCoA.  For more information about
shell-mode, issue the emacs command <tt>Control-h m</tt> after the shell is
started.  (You may want to use the emacs command:
<tt>META-x set-variable comint-scroll-show-maximum-output</tt>
to set the variable comint-scroll-show-maximum-output to the value 1.)
<par/>
If running CoCoA in an xterm, it may be best to first start the xterm
with the command <tt>xterm -sb -sl 512</tt> (scroll bar enabled, saving 512
lines).  In addition, you may want to increase the vertical size of
your window, e.g., <tt>xterm -sb -sl 512 -geometry 80x40</tt>.  In that way,
output that scrolls off of the screen is captured and easily reviewed.
<par/>
At any rate, complicated CoCoA command sequences or any sequences that
you may want to repeat should be saved in a text editor.  The commands
can then be executed by copying and pasting into a CoCoA window or
using the <ttref>source</ttref> command.  In addition, you may want to keep a log
of your CoCoA session using the command <ttref>OpenLog</ttref>.
    </description>

      </section>

<!-- ===  SECTION  =============================================== -->
      <section>
          <title>CoCoA under Windows</title>
          <type>1</type>

          <description>
***** NOT YET UPDATED TO CoCoA-5: follow with care *****
<par/>
Sorry this section is still under construction.  Probably the best
advice I could give is to repartition your disk and install Linux. ;&gt;
          </description>

        </section>

    </chapter>

  </part>
</manual_parts>

</help>

<!--
 $Header: /Volumes/Home_1/cocoa/cvs-repository/CoCoALib-0.99/src/CoCoA-5/CoCoAManual/CoCoAHelp.xml,v 1.186 2014/03/28 18:23:32 bigatti Exp $
 $Log: CoCoAHelp.xml,v $
 Revision 1.186  2014/03/28 18:23:32  bigatti
 ++ minor correctio for Normaliz

 Revision 1.185  2014/03/28 15:51:53  bigatti
 ++ cleaned some "commands and functions for .."

 Revision 1.184  2014/03/28 15:35:41  bigatti
 removed "H." entries

 Revision 1.183  2014/03/28 15:28:07  abbott
 Summary: Added new page "list constructors"; reduce page "in" to a reference to "list ctors"; updated "operators, shortcuts"
 Author: JAA

 Revision 1.182  2014/03/28 13:21:39  bigatti
 ++ some fixes for xsl
 ++ updated Frb functions

 Revision 1.181  2014/03/28 07:14:12  bigatti
 ++ cleaned eigenvectors and LinearSimplify
 ++ cleaned and fixed Frobby

 Revision 1.180  2014/03/27 17:36:42  bigatti
 ++ minimalize, minimalized

 Revision 1.179  2014/03/27 15:11:09  bigatti
 ++ fixed return
 ++ improved RingElem

 Revision 1.178  2014/03/27 15:09:56  abbott
 Summary: Lowercased several fn calls in examples
 Author: JAA

 Revision 1.177  2014/03/26 18:00:56  bigatti
 ++ MinGens for submodule

 Revision 1.176  2014/03/26 16:33:11  abbott
 Summary: Corrected entry for binomial
 Author: JAA

 Revision 1.175  2014/03/26 15:45:22  bigatti
 ++ example for NewQuotientRing

 Revision 1.174  2014/03/26 15:28:28  bigatti
 ++ removed "/DOS"

 Revision 1.173  2014/03/26 13:18:26  abbott
 Summary: Corrected/cleaned entries for DerivationAction, InverseSystem, PerpIdealOfForm
 Author: JAA

 Revision 1.172  2014/03/26 12:19:33  abbott
 Summary: Removed several GRATUITOUS CoCoA-4 mode expressions from examples
 Author: JAA

 Revision 1.171  2014/03/26 12:11:58  abbott
 Summary: Corrected entry for CoefficientsWRT; added entries for incr/decr, CoCoA-4 mode, updating CoCoA-4 code
 Author: JAA

 Revision 1.170  2014/03/25 15:23:40  abbott
 Summary: Corrected XML syntax of enty for TgCone
 Author: JAA

 Revision 1.169  2014/03/25 15:21:25  abbott
 Summary: Added entries for ImportByRef/ImportByValue and TopLevel
 Author: JAA

 Revision 1.168  2014/03/25 14:56:30  bigatti
 ++ some changes to BinRepr
 ++ some changes to NumPartitions

 Revision 1.167  2014/03/25 14:34:09  abbott
 Summary: Improved entry for  ref
 Author: JAA

 Revision 1.166  2014/03/25 14:18:30  abbott
 Summary: Cleaned entries for append, func, swap
 Author: JAA

 Revision 1.165  2014/03/25 12:08:14  abbott
 Summary: Improved entry for remove; changed name of IntersectionList; minor cleaning
 Author: JAA

 Revision 1.164  2014/03/21 15:48:34  bigatti
 ++ improved example in DF

 Revision 1.163  2014/03/21 12:03:00  abbott
 Summary: Improved entry for strings (e.g. added ops on strings)
 Author: JAA

 Revision 1.162  2014/03/21 11:54:06  bigatti
 ++ improved doc for SyzOfGens (module)

 Revision 1.161  2014/03/21 10:49:53  bigatti
 ++ improved MinGens, minimalize, minimalized
 ++ in IsFactorClosed used "1"
 ++ resurrected RelNotes

 Revision 1.160  2014/03/20 17:29:00  abbott
 Summary: Added CoeffEmbeddingHom
 Author: JAA

 Revision 1.159  2014/03/20 16:23:51  bigatti
 ++ comment on LinKer

 Revision 1.158  2014/03/19 16:56:03  abbott
 Summary: Revised entry for NewLine
 Author: JAA

 Revision 1.157  2014/03/19 16:22:51  abbott
 Summary: Added entries for floor/ceil/round; revised entries for describe/Function/Functions/Other help
 Author: JAA

 Revision 1.156  2014/03/14 11:49:37  abbott
 Summary: Added L[N] to page about operators
 Author: JAA

 Revision 1.155  2014/03/14 11:45:45  abbott
 Summary: Many changes: operators, CpuTime, CRT, fields, foreach, div & mod, monic, record, comments, strings
 Author: JAA

 Revision 1.154  2014/03/12 21:53:44  bigatti
 ++ added "All CoCoA commands"

 Revision 1.153  2014/03/06 15:56:42  abbott
 Summary: Corrected entry for LinSolve
 Author: JAA

 Revision 1.152  2014/03/05 17:35:14  abbott
 Summary: Added missing end-of-description marker
 Author: JAA

 Revision 1.151  2014/03/05 17:28:59  abbott
 Summary: Completed syntax for operators; greatly simplified page for "manual"
 Author: JAA

 Revision 1.150  2014/03/05 16:18:13  abbott
 Summary: Improved man page for logical operators (and, or, not)
 Author: JAA

 Revision 1.149  2014/03/05 14:49:31  bigatti
 ++ improved NewPolyRing, use, operators/shortcuts

 Revision 1.148  2014/03/05 13:48:02  abbott
 Summary: Added entry for cyclotomic; added note to entry for IsFactorClosed.
 Author: JAA

 Revision 1.147  2014/03/05 13:10:24  abbott
 Summary: Clean up page for operators (removed @, ??)
 Author: JAA

 Revision 1.146  2014/03/05 12:55:45  bigatti
 ++ removed minus-es in the log (for XSL)

 Revision 1.145  2014/03/05 12:53:56  bigatti
 ++ improved doc for E_

 Revision 1.144  2014/03/05 10:01:58  bigatti
 ++ some improvements

 Revision 1.143  2014/03/03 18:16:46  bigatti
 ++ added PrimaryPoincare

 Revision 1.142  2014/02/28 21:55:36  bigatti
 ++ added InitialIdeal
 ++ improved TgCone

 Revision 1.141  2014/02/26 15:37:34  abbott
 Summary: Added to QuotientBasis see-also IsFactorClosed
 Author: JAA

 Revision 1.140  2014/02/25 11:16:13  abbott
 Summary: Moved entry for "swap" to correct place
 Author: JAA

 Revision 1.139  2014/02/25 11:03:02  abbott
 Summary: Replaced  Lambda...EndLambda by Func...EndFunc; renamed Not to not(...)
 Author: JAA

 Revision 1.138  2014/02/21 11:27:43  abbott
 Summary: Improved entry for "div"; added entry for "IsIndet"; updated entry for "eigenvectors"
 Author: JAA

 Revision 1.137  2014/01/28 17:12:50  bigatti
 ++ added doc for NmzComputation

 Revision 1.136  2014/01/28 12:27:53  bigatti
 ++ improved doc for LF and DF

 Revision 1.135  2014/01/23 13:03:23  abbott
 Completed doc for IsDivisible.

 Revision 1.134  2014/01/16 16:20:05  abbott
 Added doc for NumPartitions.
 Corrected entries for  IsPrime, NextPrime, NextProbPrime.
 Sundry other cleaning.

 Revision 1.133  2013/11/21 08:35:16  abbott
 Improved entry for SortBy.  A couple of other minor changes.

 Revision 1.132  2013/10/30 08:52:32  bigatti
 ++ some label/reference fixes
 ++ the variable it  moved in "commands" and titled "It" (as for CurrentRing)
 ++ added a couple of missing closed command tags
 ++ NmzComputation had empty syntax breaking tex compilation

 Revision 1.131  2013/10/28 13:01:52  bigatti
 ++ added Elim(RingElem, ideal)

 Revision 1.130  2013/10/22 14:15:07  abbott
 Added SqfreeFactor.

 Revision 1.129  2013/10/15 16:22:57  abbott
 Added doc for valuation (also IsConstant, and ContentFreeFactor?).

 Revision 1.128  2013/10/11 10:32:50  bigatti
 ++ added R/I to Shortcuts

 Revision 1.127  2013/10/02 13:54:47  abbott
 Improved entry for dot-dot operator.

 Revision 1.126  2013/08/02 16:37:26  bigatti
 ++ added shifts to NewFreeModule

 Revision 1.125  2013/08/02 15:06:08  bigatti
 ++ fixed naming conventions for record field names
  MantissaAndExponent, RealRoots, IdealAndSeparatorsOfPoints

 Revision 1.124  2013/08/02 14:46:11  bigatti
 ++ updated DivAlg for moduleelem
 ++ updated LC for moduleelem
 ++ changed LPos into LPosn

 Revision 1.123  2013/07/31 14:44:00  bigatti
 added NumCompts

 Revision 1.122  2013/07/31 14:21:00  bigatti
 ++ added HilbertSeries and HilbertFn for MODULE

 Revision 1.121  2013/07/31 09:44:45  bigatti
 added some comments about naming conventions

 Revision 1.120  2013/07/31 09:42:01  bigatti
 updated "hilbert" entries

 Revision 1.119  2013/07/30 16:47:33  bigatti
 ++ improved entries HilbertSeries and factor/SmoothFactor

 Revision 1.118  2013/07/30 14:54:49  bigatti
 ++ updated factor, SmoothFactor (Exponents into multiplicities)
 ++ updated Frobby functions (Frb)
 ++ added IsStdGraded

 Revision 1.117  2013/06/26 17:58:31  bigatti
 ++ improved entry for append

 Revision 1.116  2013/06/26 10:02:58  bigatti
 ++ added RingQQ, RingQQt, RingZZ
 ++ added JanetBasis
 ++ updated Frobby functions and PrimaryDecomposition

 Revision 1.115  2013/06/17 10:20:02  bigatti
 merged entries for IsFactorClosed

 Revision 1.114  2013/06/17 10:10:27  bigatti
 added IsFactorClosed

 Revision 1.113  2013/06/17 09:39:02  abbott
 Added entry for IsFactorClosed.

 Revision 1.112  2013/06/17 08:58:28  abbott
 Updated entry for LinearSimplify.

 Revision 1.111  2013/06/13 07:39:29  bigatti
 updated ColumnVectors

 Revision 1.110  2013/06/13 07:32:46  bigatti
 added TgCone

 Revision 1.109  2013/06/13 07:22:25  bigatti
 *** empty log message ***

 Revision 1.108  2013/06/12 08:58:57  bigatti
 improved doc for CartesianProduct
 added new MinGens

 Revision 1.107  2013/06/06 06:01:05  bigatti
 Improved NewFreeModule, NewFractionField
 added IsElem, IsContained

 Revision 1.106  2013/06/03 11:47:26  abbott
 Moved BinomialRepr to correct place; corrected signature of fn LC.

 Revision 1.105  2013/05/31 14:54:17  bigatti
 cleaned entry for submodule

 Revision 1.104  2013/05/31 12:42:35  bigatti
 changed BlockMat into BlockMat2x2
 changed MultiBlockMat into BlockMat

 Revision 1.103  2013/05/31 07:50:32  bigatti
 improved deriv

 Revision 1.102  2013/05/31 07:28:02  bigatti
 added MultiBlockMat

 Revision 1.101  2013/05/30 07:21:20  bigatti
 *** empty log message ***

 Revision 1.100  2013/05/30 07:20:16  bigatti
 ++ added TimeOfDay
 ++ fixed date
 ++ added IsZeroDivisor

 Revision 1.99  2013/05/28 15:26:28  abbott
 Synchronized the entries for CharPoly and MinPoly.

 Revision 1.98  2013/05/28 15:14:26  bigatti
 ++ added MinPoly
 ++ improved submodule manual

 Revision 1.97  2013/05/21 15:38:47  abbott
 Improved/completed entry for "indent".

 Revision 1.96  2013/05/21 14:31:45  abbott
 Added BinomialRepr and BinomialReprShift to CoCoALib and CoCoA-5.

 Revision 1.95  2013/05/21 11:33:37  abbott
 Added rows and cols as keywords for entry about MakeMatByRows/Cols.

 Revision 1.94  2013/05/06 12:11:48  abbott
 Changed entry for "deriv" (previously "Der").

 Revision 1.93  2013/05/03 15:20:10  bigatti
 ++ added IsZeroDim
 ++ changed HilbertBasis into HilbertBasisKer

 Revision 1.92  2013/04/29 09:12:00  abbott
 Added keyword "quotient" to colon operator.

 Revision 1.91  2013/04/24 09:15:56  abbott
 Moved an entry into the right alphabetical place.

 Revision 1.90  2013/04/17 16:41:02  abbott
 Removed ref to FullRed from interreduce.
 Added new keys to IsDivisible.

 Revision 1.89  2013/04/16 15:44:23  bigatti
 ++ updated entry IdealOfPoints
 ++ updated entry QuotientBasis
 ++ removed NormalizHilbertBasis (is NmzHilbertBasis)

 Revision 1.88  2013/04/16 14:46:16  abbott
 Further improvement to page for interreduce.

 Revision 1.87  2013/04/15 12:35:07  abbott
 Improved entry for interreduce/interreduced.

 Revision 1.86  2013/04/05 15:03:16  bigatti
 ++ added indent

 Revision 1.85  2013/04/04 16:11:44  abbott
 Added some search keys to the entry for logical operators and/or/not.

 Revision 1.84  2013/03/28 15:16:55  abbott
 Changed preprocessing fns so that they produce a matrix containing the
 new points (consistent with the input being a matrix containing the
 points).

 Revision 1.83  2013/03/27 18:25:04  abbott
 Added doc for approx point preprocessing fns.

 Revision 1.82  2013/03/27 17:00:02  bigatti
 ++ updated syntax for format

 Revision 1.81  2013/03/26 15:38:46  abbott
 Improved entry for "ref".

 Revision 1.80  2013/03/21 15:44:17  bigatti
 ++ improved example for format

 Revision 1.79  2013/03/21 15:10:12  bigatti
 ++ added doc for functions and commands for ring homomorphisms
 ++ added doc for RingElem(RING, RINGELEM)

 Revision 1.78  2013/03/15 17:48:37  abbott
 Improved (alphabetical) order of entries.

 Revision 1.77  2013/03/14 15:40:01  bigatti
 minor fix in log tail comments

 Revision 1.76  2013/03/14 15:38:57  bigatti
 ++ fixed NmzIntClosureToricRing
 ++ added NmzNormalToricRing

 Revision 1.75  2013/03/12 14:43:54  abbott
 Improved the order of entries in the manual.

 Revision 1.74  2013/03/11 17:57:47  abbott
 Improved entry for SourceRegion.

 Revision 1.73  2013/03/08 10:07:21  abbott
 Added doc for SourceRegion.

 Revision 1.72  2013/03/07 17:49:59  abbott
 Added key "chinese" to entry for CRT.

 Revision 1.71  2013/02/27 10:43:37  bigatti
 ++ changed title (without <em>) in  The variable It

 Revision 1.70  2013/02/26 14:10:55  abbott
 Changed name of fn "ord" into "OrdMat".

 Revision 1.69  2013/02/26 11:49:34  abbott
 Added RatReconstructWithBounds.
 Updated entries for CurrentRing, the variable It, the Use command.

 Revision 1.68  2013/02/25 11:48:11  bigatti
 ++ swapped some unsorted entries

 Revision 1.67  2013/02/22 22:44:59  abbott
 Added doc for new fn CRT.

 Revision 1.66  2013/02/22 18:58:04  abbott
 Added new fns RatReconstructByContFrac and RatReconstructByLattice.

 Revision 1.65  2013/02/22 12:43:06  bigatti
 ++ changed GenRepr

 Revision 1.64  2013/02/22 11:06:44  bigatti
 ++ added CanonicalHom
 ++ added content
 ++ updated some "NOT YET IMPLEMENTED" entries
 ++ fixed some broken references (thanks TeX)

 Revision 1.63  2013/02/21 17:21:04  bigatti
 *** empty log message ***

 Revision 1.62  2013/02/21 17:20:26  bigatti
 ++ added GensAsCols, GensAsRows

 Revision 1.61  2013/02/21 12:53:24  bigatti
 ++ added DF and improved LF
 ++ updated SyzOfGens and syz

 Revision 1.60  2013/02/19 18:53:54  abbott
 Improved doc for "indets".

 Revision 1.59  2013/02/15 16:05:08  bigatti
 ++ added ElimMat, HomogElimMat
 ++ added ex for matrix(R,M)

 Revision 1.58  2013/02/14 09:49:47  bigatti
 ++ added ConcatHorList, ConcatVerList
 ++ updated PerpIdealOfForm

 Revision 1.57  2013/02/12 16:20:20  bigatti
 ++ fixed some entries for modules
 ++ updated IsHomog for GradingDim=0

 Revision 1.56  2013/02/11 11:06:36  bigatti
 ++ minor improvement to CpuTime
 ++ updated section Timer and Indentation

 Revision 1.55  2013/02/06 11:41:15  bigatti
 ++ added LinKerBasis

 Revision 1.54  2013/02/04 16:19:02  bigatti
 ++ added Normaliz (Nmz) functions

 Revision 1.53  2013/01/30 15:53:51  bigatti
 ++ added some search keys

 Revision 1.52  2013/01/30 15:49:27  bigatti
 ++ added SubmoduleCols/Rows, ModuleOf
 ++ some improvements to modules
 ++ removed unnecessary &gt;

 Revision 1.51  2013/01/24 17:39:37  bigatti
 ++ moved in the correct alphabetical position: wdeg
 ++ fixed deg

 Revision 1.50  2013/01/24 17:29:33  bigatti
 ++ moved in the correct alphabetical position: PoincareShifts,
    subalgebra.., factorial

 Revision 1.49  2013/01/24 17:26:04  bigatti
 ++ moved in the correct alphabetical position: QQ, StdDeg.., HilbertBasis

 Revision 1.48  2013/01/24 17:19:56  bigatti
  ++ moved in the correct alphabetical position: CoeffRing, submat

 Revision 1.47  2013/01/24 14:53:41  bigatti
  ++ moved in the correct alphabetical position: Concat..,
     NextProbPrime, IndetSubscripts

 Revision 1.46  2013/01/24 14:45:02  bigatti
  ++ moved in the correct alphabetical position: IsDivisible,
     IsProbPrime, Lambda

 Revision 1.45  2013/01/24 14:41:28  bigatti
 ++ moved in the correct alphabetical position: IndetName, SortBy, Sylvester

 Revision 1.44  2013/01/24 14:36:01  bigatti
 ++ moved in the correct alphabetical position: moduleelem and ref

 Revision 1.43  2013/01/24 14:27:50  bigatti
 ++ changed VECTOR to MODULEELEM

 Revision 1.42  2013/01/23 14:37:53  bigatti
 ++ added first function for modules
 ++ added NewFractionField
 ++ added CpuTime

 Revision 1.41  2013/01/21 13:24:51  bigatti
 ++ replaced <quotes> in syntax and example into "

 Revision 1.40  2013/01/21 11:30:29  bigatti
 ++ merged "IndetsCalled" documentation into "indets" (after renaming)

 Revision 1.39  2013/01/14 17:19:32  bigatti
 ++ improved NF, NR
 ++ added ZZ, QQ

 Revision 1.38  2013/01/07 17:06:41  bigatti
 ++ added example for InducedHom and PolyRingHom
 ++ added ZZ, QQ in Reserved Names
 ++ minor fixes

 Revision 1.37  2012/12/17 15:05:04  bigatti
 ++ added InducedHom, IsDivisible, PolyRingHom

 Revision 1.36  2012/12/11 17:31:36  abbott
 Changed name from SimplestRationalInInterval to SimplestRATBetween.

 Revision 1.35  2012/12/05 15:33:48  abbott
 Corrected an example for SimplestRationalInInterval.

 Revision 1.34  2012/12/05 15:33:02  abbott
 Added new fn SimplestRationalInInterval.

 Revision 1.33  2012/12/05 15:11:00  abbott
 Corrected entry for CFApprox.
 Replaced "denominator" by "quotient" in all doc about continued fractions.
 Some minor cleaning.

 Revision 1.32  2012/11/28 10:51:43  bigatti
 ++ added one, zero
 ++ added cast/convert key to some functions
 ++ added CoeffListWRT and fixed coefficients and CoefficientsWRT

 Revision 1.31  2012/11/23 17:51:48  bigatti
 ++ added manual for CompleteToOrd

 Revision 1.30  2012/10/05 10:24:20  bigatti
 ++ added LF (leading form)

 Revision 1.29  2012/10/02 16:48:55  bigatti
 ++ added homog for ideal

 Revision 1.28  2012/07/31 13:27:30  bigatti
 ++ updated entry: NBM

 Revision 1.27  2012/07/11 15:15:00  bigatti
 ++ some alphabethical sorting
 ++ added "empty" normaliz functions
 ++ added TopLevelFunctions

 Revision 1.26  2012/07/10 12:02:02  bigatti
 ++ added LinKer
 ++ removed body for LinSol

 Revision 1.25  2012/06/19 15:39:20  bigatti
 ++ minor update for VersionInfo
 ++ replaced some <quotes> in <tt> and <example> with "

 Revision 1.24  2012/06/18 10:08:10  bigatti
 ++ added version
 ++ removed some quotes

 Revision 1.23  2012/06/08 15:34:56  bigatti
 ++ added some entires (see redmine)
 ++ fixed casing for broken links
 ++ changed some  quotes  into  "

 Revision 1.22  2012/05/30 14:24:24  abbott
 Minor improvements to doc for AsINT and AsRAT.

 Revision 1.21  2012/05/30 12:46:34  abbott
 Improved example for SortBy and SortedBy.
 Made sure the keyword Define has a capital D,
 and that the keyword ref is all lower case.

 Revision 1.20  2012/05/28 10:33:34  abbott
 Added IsTrueGCDDomain.

 Revision 1.19  2012/05/25 13:07:23  abbott
 Added entry for Bool01.
 Added signature abs(RINGELEM):RINGELEM
 Cleaned entry for "Try".

 Revision 1.18  2012/05/24 14:54:20  bigatti
 ++ changed symbol "index" into "subscripts"
 ++ added manual entry for "lambda"

 Revision 1.17  2012/05/16 13:04:14  bigatti
 ++ added AsINT, AsRAT

 Revision 1.16  2012/05/15 13:56:43  bigatti
 ++ fixed manual for gcd and lcm

 Revision 1.15  2012/04/27 14:56:35  bigatti
 ++ added some "*"

 Revision 1.14  2012/04/27 14:50:03  abbott
 Added LinSolve

 Revision 1.13  2012/04/24 14:26:28  abbott
 Added IsFiniteField, IsPthPower, LogCardinality, PthRoot.
 Corrected CheckArgTypes.

 Revision 1.12  2012/04/04 15:57:48  bigatti
 *** empty log message ***

 Revision 1.11  2012/04/04 11:10:43  bigatti
 ++ added ***** NOT YET UPDATED TO CoCoA-5: follow with care ***** in sections

 Revision 1.10  2012/04/04 08:16:05  bigatti
 ++ minor changes (new syntax for IdealOfPoints)
 ++ highlighted "NOT YET IMPLEMENTED" and "OBSOLETE MANUAL"

 Revision 1.9  2012/04/03 10:46:32  bigatti
 ++ added IndetSymbols, SymbolRange
 ++ more cleaning and perfectioning

 Revision 1.8  2012/03/30 09:31:15  bigatti
 ++ minor change

 Revision 1.7  2012/03/29 08:42:14  bigatti
 ++ changed Mat/matrix and updated doc on matrices
 ++ changed syntax for ContentWRT/CoefficientsWRT

 Revision 1.6  2012/03/21 09:41:14  abbott
 Cleaned entry for command "if".

 Revision 1.5  2012/03/20 15:09:39  bigatti
 ++ updated manual for mat and ScalarProduct

 Revision 1.4  2012/03/16 14:44:24  bigatti
 ++ removed spurious </example>

 Revision 1.3  2012/03/16 10:01:23  bigatti
 ++ merged more updates by Elisa Fascio (finished?)
 ++ more improvements and updates

 Revision 1.2  2012/03/14 10:58:45  bigatti
 ++ merged more changes by Elisa Fascio
 ++ changed man for return, 0 values, ..

 Revision 1.1  2012/03/13 16:00:31  bigatti
 ++ used to be in /packages/man/
 ++ updated IndetSubscripts

 Revision 1.15  2012/03/12 16:01:11  bigatti
 ++ fixed version and date

 Revision 1.14  2012/03/09 17:00:29  bigatti
 ++ merged more changes by Elisa Fascio
 ++ fixed manual for  try

 Revision 1.13  2012/03/07 18:05:54  bigatti
 ++ more changes by elisa Fascio and updates

 Revision 1.12  2012/02/24 13:27:12  bigatti
 ++ merged in some updates by Elisa Fascio
 ++ added CoefficientsWRT, ContentWRT

 Revision 1.11  2011/11/02 16:28:03  bigatti
 ++ updates by Elisa Fascio

 Revision 1.10  2011/05/26 11:25:00  bigatti
 ++ minor fixes

 Revision 1.9  2011/03/23 17:27:36  bigatti
 ++ minor fixes

 Revision 1.8  2011/02/16 17:24:18  bigatti
 *** empty log message ***

 Revision 1.7  2011/02/16 17:23:22  bigatti
 ++ removed line breakes in short_description

 Revision 1.6  2011/02/15 09:41:19  bigatti
 ++ added a "*"

 Revision 1.5  2011/01/25 09:52:07  bigatti
  Updated entry for LinSol: left the old interface as public but
  "experimental". (abbott)

 Revision 1.4  2011/01/25 09:47:26  bigatti
 fixed a typo

 Revision 1.3  2011/01/19 16:03:23  bigatti
 ++ minor fix

 Revision 1.2  2010/12/16 17:48:23  bigatti
 changed  coc-quotes  into  quotes

 Revision 1.1  2010/08/31 15:11:58  bigatti
 ++ same as cocoa-4 manual

 Revision 1.51  2010/08/31 14:34:44  bigatti
 ++ added tag <keys>..<keys>  around keys list
 ++ minor fixes and key/type additions

 Revision 1.50  2010/07/12 12:28:56  bigatti
 ++ fixed some quotes
 ++ added obsolescent for help in functions

 Revision 1.49  2010/03/12 00:04:03  abbott
 Improved entries for Factor and SmoothFactor; extra keywords too.

 Revision 1.48  2009/11/26 17:35:04  bigatti
 ++ fixed some "quotes"
 ++ added "downto" key to for loop entry

 Revision 1.47  2009/10/27 16:38:41  abbott
 Added StarSprint & StarSprintFold.
 Extended StarPrint to rational functions.
 Created new version (4.7.6).

 Revision 1.46  2009/10/09 13:20:09  bigatti
 ++ added IsInRadical and MinPowerInIdeal

 Revision 1.45  2009/10/07 14:35:15  abbott
 Improved the man page for the command "Using".

 Revision 1.44  2009/10/01 15:51:05  bigatti
 ++ improved doc for Reg5

 Revision 1.43  2009/09/30 15:17:16  bigatti
 ++ added Reg5
 ++ fixed some Hilbert/Poincare names

 Revision 1.42  2009/09/24 08:23:50  bigatti
 *** empty log message ***

 Revision 1.41  2009/09/22 15:59:04  bigatti
 ++ ElsIf changed into Elif

 Revision 1.40  2009/09/03 15:36:24  abbott
 Minor update to entries for StableBBasis5 and StableBBasisNBM5.

 Revision 1.39  2009/07/01 15:14:05  bigatti
 ++ separated Max/Min
 ++ minor

 Revision 1.38  2009/06/22 15:15:08  abbott
 Minor changes to some examples.

 Revision 1.37  2009/06/09 15:23:11  abbott
 Replaced some Qs by QQs;  corrected a package name in a comment.

 Revision 1.36  2009/06/09 10:01:38  bigatti
 ++ added Reg
 ++ changed resolutions exponents

 Revision 1.35  2009/06/08 16:41:31  bigatti
 ++ fixed some quotes
 ++ fixed RegularityIndex

 Revision 1.34  2009/06/04 15:14:09  bigatti
 ++ added some functions for the school (subalgebra, apolarity)

 Revision 1.33  2009/05/26 14:44:02  bigatti
 ++ obsolescent: NewId, NewLine, Source $pkgname
 ++ new: function NewLine()

 Revision 1.32  2009/05/22 12:40:36  bigatti
 ++ changed obsolescent: GB.Step, Print(..), Repeat .. EndRepeat

 Revision 1.31  2009/05/15 16:28:42  bigatti
 ++ new tag <backslash/>

 Revision 1.30  2009/05/15 16:14:15  bigatti
 ++ updated entry for Latex

 Revision 1.29  2009/05/14 09:04:37  bigatti
 ++ Delete, Clear, Destroy obsolescent

 Revision 1.28  2009/05/06 16:03:18  bigatti
 new way to escape quotes in strings

 Revision 1.27  2009/05/05 12:14:10  bigatti
 updated for obsolescent syntax for Record

 Revision 1.26  2009/04/21 14:05:11  bigatti
 ++ added CheckArgTypes
 ++ added Frobby functions
 ++ split LinKer and LinKerModP
 ++ Q to QQ, Z to ZZ
 ++ updates for Record[..:=..] and Mat(..)
 ++ added some spaces and semicolons
 ++ added some search keys

 Revision 1.25  2009/02/05 15:41:23  bigatti
 ++ added key "factorial" for Fact
 ++ minor tidying

 Revision 1.24  2008/12/11 10:27:33  bigatti
 ++ minor changes to ImplicitPlotOn, PlotPointsOn

 Revision 1.23  2008/11/24 09:46:51  bigatti
 ++ added RelNotes

 Revision 1.22  2008/11/24 09:18:37  bigatti
 ++ ApproxBBasis5 and NBM5 renamed into StableBBasis5 and StableBBasisNBM5

 Revision 1.21  2008/11/23 17:22:06  abbott
 Changed name of NBM5 to StableBBasisNBM5; the new name is clumsy but
 more meaningful.

 Revision 1.20  2008/11/23 17:09:16  abbott
 Removed "warning" about approx output from the preprocessing algms, as the
 code now does the right thing.

 Revision 1.19  2008/11/21 21:07:27  abbott
 Changed name of ApproxBBasis5 to StableBBasis5.
 A few other minor changes.

 Revision 1.18  2008/11/20 12:43:40  bigatti
 ++ minor changes

 Revision 1.17  2008/11/19 17:37:17  bigatti
 ++ minor cleanup

 Revision 1.16  2008/11/19 16:29:42  abbott
 Updated entry for PreprocessPts5.

 Revision 1.15  2008/11/14 13:04:25  bigatti
 ++ added PlotPoints and keys for the plot functions
 ++ fixed LexSegmentIdeal (for an ideal)

 Revision 1.14  2008/11/07 15:05:20  bigatti
 ++ minor improvement for ImplicitPlot/ImplicitPlotOn

 Revision 1.13  2008/11/07 14:19:21  bigatti
 ++ added AllIndetsCalled, ImplicitPlot, ImplicitPlotOn
 ++ a few minor fixes and new keys

 Revision 1.12  2008/10/22 15:15:03  bigatti
 ++ minor changes

 Revision 1.11  2008/10/17 16:25:46  bigatti
 ++ changed all Z into ZZ and Q into QQ
 ++ added some spaces after commas

 Revision 1.10  2008/10/14 16:09:16  bigatti
 ++ using new (preferred) syntax "ZZ/(P)"

 Revision 1.9  2008/09/12 14:56:19  bigatti
 ++ added NBM5

 Revision 1.8  2008/07/17 15:10:24  bigatti
 ++ added LexSegmentIdeal(I:IDEAL)

 Revision 1.7  2008/06/30 15:34:35  bigatti
 ++ fixed manual for old help: "Help S;" into "Help(S);"

 Revision 1.6  2008/06/12 15:41:15  cocoa
  ++ removed obsolete title-keys (finished)

 Revision 1.5  2008/06/11 16:32:10  cocoa
 ++ removed obsolete title-keys (up to letter S)

-->

<!--  LocalWords:  CoCoA adjoints indeterminates equidimensional towards
 -->
