Changeset 7b3971 in git

Timestamp:

Feb 5, 2001, 1:01:39 PM (23 years ago)

Author:

Christoph Lossen <lossen@…>

Branches:

(u'spielwiese', 'fe61d9c35bf7c61f2b6cbf1b56e25e2f08d536cc')

Children:

7658571fa599a7581bd2feaa67021a15b67187a4

Parents:

d2087041ae4c66e9858042b1fd1cdc41851a03d4

Message:

* lossen:  help strings edited


git-svn-id: file:///usr/local/Singular/svn/trunk@5184 2c84dea3-7e68-4137-9b89-c4e89433aadc

Location:

Singular/LIB

Files:

• equising.lib (modified) (6 diffs)
• hnoether.lib (modified) (36 diffs)
• primdec.lib (modified) (14 diffs)
• primitiv.lib (modified) (5 diffs)

Singular/LIB/equising.lib

@@ -1 @@
-version="$Id: equising.lib,v 1.6 2001-01-31 15:36:02 lossen Exp $";
+version="$Id: equising.lib,v 1.7 2001-02-05 12:01:37 lossen Exp $";
 category="Singularities";
 info="
@@ -7 +7 @@
 PROCEDURES:
  esStratum(F[,m]);   computes the equisingularity stratum of a deformation
- isEquising(F[,m]);  tests, whether a given deformation is equisingular
+ isEquising(F[,m]);  tests if a given deformation is equisingular
 ";
 
@@ -752 +752 @@
 
 proc esStratum (poly p_F, list #)
-"USAGE:   esStratum(F[,m]); F a polynomial, m an integer
+"USAGE:   esStratum(F[,m]); F poly, m int
 ASSUME:  F defines a deformation of an irreducible bivariate polynomial f
-         and that char(basering) does not divide mult(f).
+         and the characteristic of the basering does not divide mult(f). @*
          If nv is the number of variables of the basering, then the first nv-2
-         ringvariables are the deformation parameters.
+         variables are the deformation parameters. @*
          If the basering is a qring, ideal(basering) must only depend
          on the deformation parameters.
-RETURN:  A list l of an ideal and an integer, where
-         l[1] is the ideal in the deformation parameters, defining the
-         equisingularity stratum of F,
-         l[2] = 1 if some error has occured, l[2] = 0 otherwise.
-         If m is given, the computation stops after m steps of the iteration.
-NOTE:    printlevel > 0 displays comments and pauses after intermediate
-         computations (default: printlevel=0)
-         This proc uses 'execute' or calls a procedure using 'execute'.
+RETURN:  list l of an ideal and an integer, where
+@format
+  l[1] is the ideal in the deformation parameters, defining the ES-stratum of F,
+  l[2]=1 if some error has occured,  l[2]=0 otherwise.
+@end format
+NOTE:    If m is given, the computation stops after m steps of the iteration. @*
+         printlevel > 0 displays comments and pauses after intermediate
+         computations (default: printlevel=0) @*
+         This procedure uses @code{execute} or calls a procedure using 
+         @code{execute}.
 EXAMPLE: example esStratum; shows an example
 "
@@ -847 +849 @@
    "EXAMPLE:"; echo=2;
    ring r = 11,(a,b,c,d,e,f,g,x,y),ds;
-   poly F =
-   xa+yb+x2+2xy+y2c+y^2+y3d+y4e+y5f+y6g+x^7;
+   poly F = (x2+2xy+y2+x5)+ax+by+cx2+dxy+ey2+fx3+gx4;
    esStratum(F);
    esStratum(F,2);
-   ideal I  = f-fa,e+b;
+   ideal I = f-fa,e+b;
    qring q = std(I);
    poly F = imap(r,F);
@@ -1159 +1160 @@
 
 proc isEquising (poly p_F, list #)
-"USAGE:   isEquising(F[,m]); F a polynomial, m an integer
-ASSUME:  F defines a deformation of an irreducible bivariate polynomial f
-         and that char(basering) does not divide mult(f).
+"USAGE:   isEquising(F[,m]); F poly, m int
+ASSUME:   F defines a deformation of an irreducible bivariate polynomial f
+         and the characteristic of the basering does not divide mult(f). @*
          If nv is the number of variables of the basering, then the first nv-2
-         ringvariables are the deformation parameters.
+         variables are the deformation parameters. @*
          If the basering is a qring, ideal(basering) must only depend
          on the deformation parameters.
-RETURN:  A list l of two integers, where
-         l[1] = 1 if F is an equisingular deformation,l[1] = 0 otherwise.
-         l[2] = 1 if some error has occured, l[2] = 0 otherwise.
-         If m is given, the computation stops after m steps of the iteration.
-NOTE:    This proc uses 'execute' or calls a procedure using 'execute'.
+RETURN:  list l of two integers, where
+@format        
+   l[1]=1 if F is an equisingular deformation,  l[1]=0 otherwise.
+   l[2]=1 if some error has occured,  l[2]=0 otherwise.
+@end format
+NOTE:    If m is given, the computation stops after m steps of the iteration. @*
+         This procedure uses @code{execute} or calls a procedure using 
+         @code{execute}.
 EXAMPLE: example isEquising; shows an example
 "
@@ -1242 +1246 @@
 {
    "EXAMPLE:"; echo=2;
-   ring r = 11,(T,x,y),ds;
-   poly F = (x+y)^2+y^3*T+x^7;
+   ring r = 11,(a,b,x,y),ds;
+   poly F = (x2+2xy+y2+x5)+ay3+bx5;
    isEquising(F);
    isEquising(F,1);
-   isEquising(F,2);
-   ideal I  = ideal(T);
+   ideal I = ideal(a);
    qring q = std(I);
    poly F = imap(r,F);
-   isEquising(F,2);
+   isEquising(F);
 }
 ///////////////////////////////////////////////////////////////////////////////

Singular/LIB/hnoether.lib

@@ -3 +3 @@
 // This library is for Singular 1-3-7 or newer
 
-version="$Id: hnoether.lib,v 1.27 2001-01-16 13:48:30 Singular Exp $";
-category="Singularities";
+version="$Id: hnoether.lib,v 1.28 2001-02-05 12:01:39 lossen Exp $";
+//category="Singularities";
 info="
 LIBRARY:  hnoether.lib   Hamburger-Noether (Puiseux) Development
@@ -10 +10 @@
 
 OVERVIEW:
- A library for computing the Hamburger-Noether resp. Puiseux development
- of a plane curve singularity following A. Campillo: Algebroid curves
- in positive characteristic, Lecture Notes in Math. 813, Springer (1980).
+ A library for computing the Hamburger-Noether, resp. Puiseux, development
+ of a plane curve singularity following [Campillo, A.: Algebroid curves
+ in positive characteristic, Springer LNM 813 (1980)]. @*
  The library contains also procedures for computing the (topological)
  numerical invariants of plane curve singularities.
@@ -50 +50 @@
 proc further_hn_proc()
 "USAGE: further_hn_proc();
-   The library `hnoether.lib' contains some more procedures which are not
-   shown when typing @code{help hnoether.lib}. They may be useful for
-   interactive use (e.g. if you want to do the calculation of a HNE
-   \"by hand\" to see the intermediate results), and they can be enumerated by
-   calling further_hn_proc. Use @code{help <procedure>;} for detailed
-   information about each of them.
+NOTE:  The library @code{hnoether.lib} contains some more procedures which 
+       are not shown when typing @code{help hnoether.lib;}. They may be useful 
+       for interactive use (e.g. if you want to do the calculation of an HN
+       development \"by hand\" to see the intermediate results), and they 
+       can be enumerated by calling @code{further_hn_proc()}. @*
+       Use @code{help <procedure>;} for detailed information about each of 
+       them.
 "
 {
  "
- The following procedures are also part of the library `hnoether.lib':
+ The following procedures are also part of `hnoether.lib':
 
  newtonpoly(f);      Newton polygon of polynom f
- getnm(f);           intersection pts. of Newton polygon with the axes
+ getnm(f);           intersection pts. of Newton polygon with axes
  T_Transform(f,Q,N); returns f(y,xy^Q)/y^NQ (f: poly, Q,N: int)
  T1_Transform(f,d,M); returns f(x,y+d*x^M)  (f: poly,d:number,M:int)
@@ -73 +74 @@
  find_in_list(L,p);  find int p in list L
  get_last_divisor(M,N); last divisor in Euclid's algorithm
- factorfirst(f,M,N); try to factor f in a trivial way without `factorize'
+ factorfirst(f,M,N); try to factor f without `factorize'
  factorlist(L);      factorize a list L of polynomials
  referencepoly(D);   a polynomial f s.t. D is the Newton diagram of f";
@@ -257 +258 @@
 
 proc squarefree (poly f)
-"USAGE:  squarefree(f);  f a bivariate polynomial
-RETURN: a squarefree divisor of f.
-        Normally the return value is a greatest squarefree divisor, but there
-        is an exception: factors with a p-th root, p the ring characteristic,
-        are lost.
+"USAGE:  squarefree(f);  f poly
+ASSUME:  f is a bivariate polynomial (in the first 2 ring variables).
+RETURN:  poly, a squarefree divisor of f.
+NOTE:    Usually, the return value is the greatest squarefree divisor, but 
+         there is one exception: factors with a p-th root, p the 
+         characteristic of the basering, are lost.
 SEE ALSO: allsquarefree
 EXAMPLE: example squarefree; shows some examples.
@@ -342 +344 @@
 { "EXAMPLE:"; echo = 2;
  ring exring=3,(x,y),dp;
- squarefree(x3+y);
- squarefree(x3);
- squarefree(x2);
- squarefree(xy+x);
- squarefree((x+y)^3*(x-y)^2); // (x+y)^3 is lost
+ squarefree((x3+y)^2);
+ squarefree((x+y)^3*(x-y)^2); // Warning: (x+y)^3 is lost
  squarefree((x+y)^4*(x-y)^2); // result is (x+y)*(x-y)
 }
@@ -352 +351 @@
 
 proc allsquarefree (poly f, poly l)
-"USAGE : allsquarefree(f,l);  poly f,l
-        l is the squarefree divisor of f you get by @code{l=squarefree(f);}
-RETURN: the squarefree divisor of f consisting of all irreducible factors of f
-NOTE  : This proc uses factorize to get the missing factors of f not in l and
-        therefore may be slow.
+"USAGE : allsquarefree(f,g);  f,g poly
+ASSUME: g is the output of @code{squarefree(f)}.
+RETURN: the greatest squarefree divisor of f.
+NOTE  : This proc uses factorize to get the missing factors of f not in g and,
+        therefore, may be slow.
 SEE ALSO: squarefree
 EXAMPLE: example allsquarefree;  shows an example
@@ -405 +404 @@
   ring exring=7,(x,y),dp;
   poly f=(x+y)^7*(x-y)^8;
-  poly l=squarefree(f);
-  l; // x-y found because 7 does not divide 8
-  allsquarefree(f,l); // all factors (x+y)*(x-y) found
+  poly g=squarefree(f);
+  g;                      // factor x+y lost, since characteristic=7
+  allsquarefree(f,g);     // all factors (x+y)*(x-y) found
 }
 ///////////////////////////////////////////////////////////////////////////////
 
 proc is_irred (poly f)
-"USAGE:   is_irred(f); f a squarefree bivariate polynomial
-RETURN:  an integer:
- @*      is_irred(f) @math{= 1} if f is irreducible as a formal power series
-         over the algebraic closure of its coefficient field (f defines an
-         analytically irreducible curve at zero),
- @*      is_irred(f) @math{= 0} else.
-NOTE:    @math{f = 0} and units in the ring of formal power series are not
-         considered irreducible.
+"USAGE:   is_irred(f); f poly
+ASSUME:  f is a squarefree bivariate polynomial (in the first 2 ring 
+         variables).
+RETURN:  int (0 or 1): @* 
+         - @code{is_irred(f)=1} if f is irreducible as a formal power 
+         series over the algebraic closure of its coefficient field (f 
+         defines an analytically irreducible curve at zero), @*
+         - @code{is_irred(f)=0} otherwise.
+NOTE:    0 and units in the ring of formal power series are considered to be 
+         not irreducible.
 KEYWORDS: irreducible power series
 EXAMPLE: example is_irred;  shows an example
@@ -465 +466 @@
 
 proc develop
-"USAGE:   develop(f [,n]); f polynomial in two variables, n integer
-RETURN:  Hamburger-Noether development of f, in form of a list:
-  @*     [1]: Hamburger-Noether matrix:
-            Each row contains the coefficients of the corresponding line of the
-            Hamburger-Noether expansion (HNE). The end of the line is marked in
-            the matrix as the first ring variable (usually x).
-  @*     [2]: intvec indicating the length of lines of the HNE
-  @*     [3]: int:
-           0  if the 1st ring variable was transversal (with respect to f),
-  @*       1  if the variables were changed at the beginning of the
-              computation,
-           -1 if an error has occurred.
-  @*     [4]: the transformed polynomial of f to make it possible to extend the
-              Hamburger-Noether development a posteriori without having to do
-              all the previous calculation once again (0 if not needed)
-  @*     [5]: int:
-           1  if the curve has exactly one branch (i.e. is irreducible),
-  @*       0  else (i.e. the curve has more than one HNE or f is not valid).
-
-ASSUME:  f irreducible as a power series (for reducible f use
-         @code{reddevelop})
+"USAGE:   develop(f [,n]); f poly, n int
+ASSUME:  f is a bivariate polynomial (in the first 2 ring variables) and 
+         irreducible as power series (for reducible f use @code{reddevelop}).
+RETURN:  list @code{L} with:
+@texinfo
+@table @asis
+@item @code{L[1]}; matrix:
+         Each row contains the coefficients of the corresponding line of the
+         Hamburger-Noether expansion (HNE). The end of the line is marked in
+         the matrix by the first ring variable (usually x).
+@item @code{L[2]}; intvec: 
+         indicating the length of lines of the HNE
+@item @code{L[3]}; int:
+         0  if the 1st ring variable was transversal (with respect to f), @*
+         1  if the variables were changed at the beginning of the 
+            computation, @*
+        -1  if an error has occurred. 
+@item @code{L[4]}; poly: 
+         the transformed polynomial of f to make it possible to extend the 
+         Hamburger-Noether development a posteriori without having to do
+         all the previous calculation once again (0 if not needed)
+@item @code{L[5]}; int:
+         1  if the curve has exactly one branch (i.e., is irreducible), @*
+         0  else (i.e., the curve has more than one HNE, or f is not valid). 
+@end table
+@end texinfo
 DISPLAY: The (non zero) elements of the HNE (if not called by another proc).
-
-NOTE: If the optional parameter @math{n} is given, the HN-matrix will have
-      at least @math{n} columns. Otherwise the number of columns will be chosen
-      minimal s.t. the matrix contains all necessary information (i.e. all
-      lines of the HNE but the last (which is in general infinite) have place).
-      If @math{n} is negative, the algorithm is stopped as soon as possible,
-      i.e. the information computed is enough for `@code{invariants}', but the
-      HN-matrix may contain undetermined elements, which are marked with the
-      2nd variable (of the basering).
-      In any case, the optional parameter only affects the calculation of
-      the LAST line of the HNE; @code{develop}(f) gives already all necessary
-      information for the procedure `@code{invariants}'. A negative value of
-      @math{n} will result in a very poor parametrization, but it can make
-      `@code{develop}' faster; a positive value will improve the exactness of
-      the parametrization.
-
-      For time critical computations it is recommended to use
-      \"@code{ring ...,(x,y),ls}\" as basering - it increases the algorithm's
-      speed.
-
+NOTE:    The optional parameter @code{n} affects only the computation of
+         the LAST line of the HNE. If it is given, the HN-matrix @code{L[1]}
+         will have at least @code{n} columns. @*
+         Otherwise, the number of columns will be chosen minimal such that the 
+         matrix contains all necessary information (i.e., all lines of the HNE 
+         but the last (which is in general infinite) have place). @*
+         If @code{n} is negative, the algorithm is stopped as soon as the 
+         computed information is sufficient for @code{invariants(L)}, but the 
+         HN-matrix @code{L[1]} may still contain undetermined elements, which 
+         are marked with the 2nd variable (of the basering). @*
+         For time critical computations it is recommended to use
+         @code{ring ...,(x,y),ls} as basering - it increases the algorithm's
+         speed. @*
+         If @code{printlevel>=0} comments are displayed (default is 
+         @code{printlevel=0}). 
 SEE ALSO: reddevelop, extdevelop, displayHNE
 EXAMPLES: example develop; shows an example
@@ -889 +890 @@
   // therefore the HNE is:
   // z(-1)= 3*z(0)^7 + z(0)^7*z(1),
-  // z(0) = z(1)*z(2),
-  //        (note that there is 1 zero in the 2nd row before x)
-  // z(1) = z(2)^3*z(3),    (there are 3 zeroes in the 3rd row)
+  // z(0) = z(1)*z(2),       (there is 1 zero in the 2nd row before x)
+  // z(1) = z(2)^3*z(3),     (there are 3 zeroes in the 3rd row)
   // z(2) = z(3)*z(4),
   // z(3) = -z(4)^2 + 0*z(4)^3 +...+ 0*z(4)^8 + ?*z(4)^9 + ...
-  //   (the missing x in the matrix indicates that this line
-  //    is not complete. It can only occur in the last line of the
-  //    HNE, and normally does.)
+  // (the missing x in the last line indicates that it is not complete.)
   hne[2];
   param(hne);
-  // returns the parametrization
-  // x(t)= -t^14+O(t^21),  y(t)= -3t^98+O(t^105)
+  // parametrization:   x(t)= -t^14+O(t^21),  y(t)= -3t^98+O(t^105)
   // (the term -t^109 in y may have a wrong coefficient)
   displayHNE(hne);
@@ -910 +907 @@
 
 proc param
-"USAGE:  param(l [,x]) takes the output of develop(f)
-        (list l (matrix m, intvec v, int s[,poly g,...]))
-        and gives a parametrization for f; the first variable of the active
-        ring is chosen as indefinite. If the ring contains more than
-        two variables, the 3rd variable is chosen (remember that develop takes
-        the first two variables and therefore the other vars should be unused).
- @*     x is an optional parameter of any type.
-RETURN: If only the list l is given:
-        ideal of two polynomials: if the HNE was finite, f(param[1],param[2])
-        will be  zero. If not, the real parametrization will be
-        two power series; then param will return a truncation of these series.
-
-        If the optional parameter x is given:
-        list L with L[1]=param(l) (the ideal containing the parametrization)
-        and L[2]=intvec with two entries indicating the highest degree unto
-        which the coefficients of the monomials in L[1] are exact (a value of
-        -1 is for infinity, i.e. the corresponding polynomial is exact).
+"USAGE:  param(L [,x]); L list, x any type (optional)
+ASSUME:  L is the output of @code{develop(f)}, or of 
+        @code{extdevelop(develop(f),n)}, or one entry of the output of 
+        @code{reddevelop(f)}.
+RETURN: a parametrization for f in the following format: @*
+        - if only the list L is given, the result is an ideal of two 
+        polynomials p[1],p[2]: if the HNE was finite then f(p[1],p[2])=0};
+        if not, the \"real\" parametrization will be two power series and 
+        p[1],p[2] are truncations of these series.@* 
+        - if the optional parameter x is given, the result is a list l:
+        l[1]=param(L) (ideal) and l[2]=intvec with two entries indicating 
+        the highest degree up to which the coefficients of the monomials in 
+        l[1] are exact (entry -1 means that the corresponding parametrization
+        is exact).
+NOTE:   If the basering has only 2 variables, the first variable is chosen 
+        as indefinite. Otherwise, the 3rd variable is chosen. 
 SEE ALSO: develop, extdevelop
 KEYWORDS: parametrization
@@ -1040 +1036 @@
  poly f=x3+2xy2+y2;
  list hne=develop(f);
- list hne_extended1=develop(f,6);
- list hne_extended2=develop(f,10);
-            //   compare the different matrices ...
+ list hne_extended=extdevelop(hne,10);
+            //   compare the matrices ...
  print(hne[1]);
- print(hne_extended1[1]);
- print(hne_extended2[1]);
+ print(hne_extended[1]);
             // ... and the resulting parametrizations:
  param(hne);
- param(hne_extended1);
- param(hne_extended2);
- param(hne_extended2,0);
+ param(hne_extended);
+ param(hne_extended,0);
 }
 ///////////////////////////////////////////////////////////////////////////////
 
 proc invariants
-"USAGE:   invariants(l) takes the output of develop(f)
-         (list l (matrix m, intvec v, int s[,poly g,...]))
-         and computes the following irreducible curve invariants:
-RETURN:  a list, if l contains a valid HNE:
-      @format
-    - invariants(l)[1]: intvec         (characteristic exponents)
-    - invariants(l)[2]: intvec         (generators of the semigroup)
-    - invariants(l)[3],[4]: 2 x intvec (Puiseux pairs, 1st and 2nd components)
-    - invariants(l)[5]: int            (degree of the conductor)
-    - invariants(l)[6]: intvec         (sequence of multiplicities)
-      @end format
-         an empty list, if an error occurred in the procedure develop.
+"USAGE:   invariants(L); L list
+ASSUME:  L is the output of @code{develop(f)}, or of 
+         @code{extdevelop(develop(f),n)}, or one entry of the output of 
+         @code{reddevelop(f)}.
+RETURN:  list, if L contains a valid HNE:
+@format
+    invariants(L)[1]:  intvec    (characteristic exponents)
+    invariants(L)[2]:  intvec    (generators of the semigroup)
+    invariants(L)[3]:  intvec    (Puiseux pairs, 1st components)
+    invariants(L)[4]:  intvec    (Puiseux pairs, 2nd components)
+    invariants(L)[5]:  int          (degree of the conductor)
+    invariants(L)[6]:  intvec    (sequence of multiplicities)
+@end format
+         an empty list, if L contains no valid HNE.
 SEE ALSO: develop, displayInvariants, multsequence, intersection
 KEYWORDS: characteristic exponents; semigroup of values; Puiseux pairs;
@@ -1157 +1152 @@
 
 proc displayInvariants
-"USAGE:   displayInvariants(l); takes the output both of
-         develop(f) and reddevelop(f)
-          ( list l (matrix m, intvec v, int s[,poly g,...])
-            or list of lists in the form l )
-RETURN:  nothing
+"USAGE:  displayInvariants(L); L list
+ASSUME:  L is the output of @code{develop(f)}, or of 
+         @code{extdevelop(develop(f),n)}, or (one entry of) the output of 
+         @code{reddevelop(f)}.
+RETURN:  none
 DISPLAY: invariants of the corresponding branch, resp. of all branches,
          in a better readable form.
@@ -1244 +1239 @@
 
 proc multiplicities
-"USAGE:   multiplicities(l) takes the output of develop(f)
-         (list l (matrix m, intvec v, int s[,poly g,...]))
-RETURN:  intvec of the different multiplicities that occur during the
-         successive blowing up of the curve corresponding to f
+"USAGE:   multiplicities(L); L list
+ASSUME:  L is the output of @code{develop(f)}, or of 
+         @code{extdevelop(develop(f),n)}, or one entry of the output of 
+         @code{reddevelop(f)}. 
+RETURN:  intvec of the different multiplicities that occur when successively
+         blowing-up the curve singularity corresponding to f.
 SEE ALSO: develop
 EXAMPLE: example multiplicities;  shows an example
@@ -1287 +1284 @@
 
 proc puiseux2generators (intvec m, intvec n)
-"USAGE:   puiseux2generators(m,n);
-         m,n intvecs with 1st resp. 2nd components of Puiseux pairs
-RETURN:  intvec of the generators of the semigroup of values
+"USAGE:   puiseux2generators(m,n); m,n intvec 
+ASSUME:  m, resp. n, represent the 1st, resp. 2nd, components of Puiseux pairs
+         (e.g., @code{m=invariants(L)[3]}, @code{n=invariants(L)[4]}). 
+RETURN:  intvec of the generators of the semigroup of values.
 SEE ALSO: invariants
 EXAMPLE: example puiseux2generators;  shows an example
@@ -1316 +1314 @@
 
 proc intersection (list hn1, list hn2)
-"USAGE:   intersection(hne1,hne2);
-         hne1,hne2: two lists representing a HNE (normally two entries out of
-         the output of reddevelop), i.e. list(matrix,intvec,int[,poly]).
-RETURN:  The intersection multiplicity of the branches corresponding to
-         hne1 & hne2 (of type int).
+"USAGE:   intersection(hne1,hne2); hne1, hne2 lists
+ASSUME:  hne1, hne2 represent a HNE (i.e., are the output of 
+        @code{develop(f)}, or of @code{extdevelop(develop(f),n)}, or 
+        one entry of the output of @code{reddevelop(f)}).
+RETURN:  int, the intersection multiplicity of the branches corresponding to
+         hne1 and hne2.
 SEE ALSO: reddevelop, displayInvariants
 KEYWORDS: intersection multiplicity
@@ -1421 +1420 @@
   // ------ the example starts here -------
   "EXAMPLE:"; echo = 2;
+  int plevel=printlevel; printlevel=-1;
   ring r=0,(x,y),dp;
   list hne=reddevelop((x2-y3)*(x2+y3));
   intersection(hne[1],hne[2]);
-  kill HNEring,r;
-  echo = 0;
+  kill HNEring,r; 
+  printlevel=plevel; echo = 0;
   // --- restore HNEring if previously defined ---
   if (defined(rettering)) {
@@ -1436 +1436 @@
 
 proc multsequence
-"USAGE:   multsequence(l);
-         l is the output of either develop(f) or reddevelop(f)
-RETURN:  - if l=@code{develop}(f) or l=@code{reddevelop}(f)[i]:
-           intvec of the sequence of multiplicities of the curve
-           resp. of the i-th branch (the same as @code{invariants}(l)[6]; )
-
-         - if l=@code{reddevelop}(f) : list of two integer matrices:
-  @* @code{multsequence}(l)[1][i,*] contains the multiplicities of the branches
-           at their infinitely near point of 0 in its (i-1) order
-           neighbourhood (i.e. i=1: multiplicity of the branches themselves,
-                 i=2: multiplicity of their 1st quadratic transformed etc.,
-       @*  or to say it in another way: @code{multsequence}(l)[1][*,j] is the
-                 sequence of multiplicities of the j-th branch).
-  @* @code{multsequence}(l)[2][i,*] contains the information which of these
-           infinitely near points coincide.
-NOTE:  The order of elements of the list obtained from @code{reddevelop} must
-       not be changed (because then the coincident infinitely near points
+"USAGE:   multsequence(L); L list
+ASSUME:  L is the output of @code{develop(f)}, or of 
+         @code{extdevelop(develop(f),n)}, or one entry of the output of 
+         @code{reddevelop(f)}.
+RETURN:  intvec corresponding to the multiplicity sequence of (a branch) 
+         of the curve (the same as @code{invariants(L)[6]}).
+ASSUME:  L is the output of @code{reddevelop(f)}.
+RETURN:  list of two integer matrices:
+@texinfo
+@table @asis
+@item  @code{multsequence(L)[1][i,*]}
+   contains the multiplicities of the branches at their infinitely near point 
+   of 0 in its (i-1) order neighbourhood (i.e., i=1: multiplicity of the 
+   branches themselves, i=2: multiplicity of their 1st quadratic transformed, 
+   etc., @*
+   Hence, @code{multsequence(L)[1][*,j]} is the multiplicity sequence 
+   of branch j.
+@item  @code{multsequence(L)[2][i,*]}: 
+   contains the information which of these infinitely near points coincide.
+@end table
+@end texinfo
+NOTE:  The order of elements of the list obtained from @code{reddevelop(f)} 
+       must not be changed (because then the coincident infinitely near points
        couldn't be grouped together, cf. meaning of 2nd intmat in example).
-       Hence it is not wise to compute the HNE of several polynomials
-       separately, put them into a list l and call @code{multsequence}(l).
-
+       Hence, it is not wise to compute the HNE of several polynomials
+       separately, put them into a list L and call @code{multsequence(L)}. @*
        Use @code{displayMultsequence} to produce a better readable output for
        reducible curves on the screen.
@@ -1537 +1542 @@
   }
   // ------ the example starts here -------
-  "EXAMPLE:"; echo = 2;
+  "EXAMPLE:"; echo = 2;   
+  int plevel=printlevel; printlevel=-1;
   ring r=0,(x,y),dp;
-  list hne=reddevelop((x6-y10)*(x+y2-y3)*(x+y2+y3));
-
+  list hne=reddevelop((x6-y10)*(x+y2-y3)*(x+y2+y3));   // 4 branches
   multsequence(hne[1]),"  |  ",multsequence(hne[2]),"  |  ",
   multsequence(hne[3]),"  |  ",multsequence(hne[4]);
@@ -1547 +1552 @@
   displayMultsequence(hne);
   kill HNEring,r;
+  printlevel=plevel;
   echo = 0;
   // --- restore HNEring if previously defined ---
@@ -1558 +1564 @@
 
 proc displayMultsequence
-"USAGE:   displayMultsequence(l);
-         l is the output of either develop(f) or reddevelop(f)
+"USAGE:   displayMultsequence(L);
+ASSUME:  L is the output of @code{develop(f)}, or of 
+         @code{extdevelop(develop(f),n)}, or (one entry of) the output of 
+         @code{reddevelop(f)}.
 RETURN:  nothing
 DISPLAY: the sequence of multiplicities:
-       if l=develop(f) or l=reddevelop(f)[i] : just the sequence a,b,c,...,1
- @*    if l=reddevelop(f) : a sequence of the following form:
-
- @*    @math{[(a_1,....,b_1,....,c_1)]},
- @*    @math{[(a_2,...),...,(...,c_2)]},
- @*    @math{   ...................}
- @*    @math{[(a_n),(b_n),.....,(c_n)]}
-
- @*    with @math{a_1,...,a_n} the sequence of multiplicities of the 1st branch
- @*    [...] the multiplicities of the j-th transformed of all branches
- @*    (...) the multiplicities of those branches meeting in the same
-             infinitely near point.
-NOTE:    The same restrictions for l as in `@code{multsequence}' apply.
+@format
+ -  if @code{L=develop(f)} or @code{L=reddevelop(f)[i]}: 
+                      @code{a , b , c , ....... , 1}  
+ - if @code{L=reddevelop(f)}: 
+                      @code{[(a_1, .... , b_1 , .... , c_1)],}
+                      @code{[(a_2, ... ), ... , (... , c_2)],}
+                      @code{ ........................................ ,}
+                      @code{[(a_n),(b_n), ....., (c_n)]}
+     with: 
+       @code{a_1 , ... , a_n} the sequence of multiplicities of the 1st branch,
+       @code{[...]} the multiplicities of the j-th transformed of all branches,
+       @code{(...)} indicating branches meeting in an infinitely near point.
+@end format
+NOTE:    The same restrictions for L as in @code{multsequence} apply.
 SEE ALSO: multsequence, develop, reddevelop, separateHNE
 EXAMPLE: example displayMultsequence;  shows an example
@@ -1622 +1631 @@
   // ------ the example starts here -------
   "EXAMPLE:"; echo = 2;
+  int plevel=printlevel; printlevel=-1;
   ring r=0,(x,y),dp;
   list hne=reddevelop((x6-y10)*(x+y2-y3)*(x+y2+y3));
-
   displayMultsequence(hne[1]);
   displayMultsequence(hne);
   kill HNEring,r;
+  printlevel=plevel; 
   echo = 0;
   // --- restore HNEring if previously defined ---
@@ -1639 +1649 @@
 
 proc separateHNE (list hn1,list hn2)
-"USAGE:    separateHNE(hne1,hne2);  list hne1,hne2: output of develop
-RETURN:   number of quadratic transformations needed to separate both curves
+"USAGE:    separateHNE(hne1,hne2);  hne1, hne2 lists
+ASSUME:   hne1, hne2 are HNEs (=output of 
+          @code{develop(f)}, @code{extdevelop(develop(f),n)}, or 
+          one entry of the output of @code{reddevelop(f)}).
+RETURN:   number of quadratic transformations needed to separate both curves 
+          (branches).
 SEE ALSO: develop, reddevelop, multsequence, displayMultsequence
 EXAMPLE:  example separateHNE;  shows an example
@@ -1736 +1750 @@
 
 proc displayHNE(list ldev,list #)
-"USAGE:   displayHNE(ldev,[,n]); ldev=list (the output of develop(f) or
-          reddevelop(f)), n=int
+"USAGE:   displayHNE(L[,n]); L list, n int
+ASSUME:  L has the format of the output of @code{develop(f)}, resp. of 
+         @code{reddevelop(f)}.
 RETURN:  - if only one argument is given, no return value, but
          display an ideal HNE of the following form:
@@ -1747 +1762 @@
      HNE[r+1]=           []*z(r)^2+[]*z(r)^3+......
      @end example
-     where x,y are the indeterminates of the basering. The values of @code{[]}
-     are the coefficients of the Hamburger-Noether matrix, the values of
-     @code{<>} are represented in the HN-matrix as `x'.
-     @*  The 1st line (@code{HNE[1]}) means that
-     @math{y=}@code{[]}@math{*z(0)^1+...},
-       the 2nd line (@code{HNE[2]}) means that
-     @math{x=}@code{[]}@math{*z(1)^2+...},
-     so you can see which indeterminate corresponds to which line
-     (it's also possible that x corresponds to the 1st line and y to the 2nd).
-     @*  - if a second argument is given, create and export a new ring with
-         name `displayring' containing an ideal `HNE' as described above.
-
-     If ldev contains the output of @code{reddevelop}(f), @code{displayHNE}
-     shows the HNE's of all branches of f in the form described above.
-     The optional parameter is then ignored.
-
+     where @code{x},@code{y} are the first 2 variables of the basering. 
+     The values of @code{[]} are the coefficients of the Hamburger-Noether 
+     matrix, the values of @code{<>} are represented by @code{x} in the 
+     HN-matrix.@*  
+     - if a second argument is given, create and export a new ring with
+     name @code{displayring} containing an ideal @code{HNE} as described 
+     above.@*
+     - if L corresponds to the output of @code{reddevelop(f)}, 
+     @code{displayHNE(L[,n])} shows the HNE's of all branches of f in the form 
+     described above. The optional parameter is then ignored.
+NOTE:  The 1st line of the above ideal (i.e., @code{HNE[1]}) means that
+     @code{y=[]*z(0)^1+...}, the 2nd line (@code{HNE[2]}) means that
+     @code{x=[]*z(1)^2+...}, so you can see which indeterminate 
+     corresponds to which line (it's also possible that @code{x} corresponds 
+     to the 1st line and @code{y} to the 2nd).
+ 
 SEE ALSO: develop, reddevelop
 EXAMPLE: example displayHNE; shows an example
@@ -1999 +2014 @@
 
 proc extdevelop (list l, int Exaktheit)
-"USAGE:   extdevelop(l,n);
-         list l (matrix m, intvec v, int s, poly g[,int b]), int n
- @*      takes the output l of develop(f) ( or extdevelop(L,N),
-         or one entry of the output of reddevelop(f))  and
-RETURN:  an extension of the Hamburger-Noether development of f in the same
-         form as l (i.e. list(matrix, intvec, int, poly) ).
-         The new HN-matrix will have at least n columns
-         (if the HNE isn't finite).
-         Thus if f is irreducible, @code{extdevelop}(@code{develop}(f),n);
-         (in most cases) will produce the same result as @code{develop}(f,n).
-         Type `help develop;'  for more details.
-NOTE:    If the matrix m of l has N columns, the exactness of
-         @code{param}(@code{extdevelop}(l,n))  will be increased by at least
-         (n-N) more significant monomials compared with @code{param}(l).
+"USAGE:   extdevelop(L,N); list L, int N 
+ASSUME:  L is the output of @code{develop(f)}, or of @code{extdevelop(l,n)},
+         or one entry of the output of @code{reddevelop(f)}.
+RETURN:  an extension of the Hamburger-Noether development of f as a list 
+         in the same format as L has (up to the last entry in the output
+         of @code{develop(f)}).@*
+         Type @code{help develop;}, resp. @code{help reddevelop;} for more 
+         details.
+NOTE:    The new HN-matrix will have at least N columns (if the HNE is not
+         finite). In particular, if f is irreducible then (in most cases)
+         @code{extdevelop(develop(f),N)} will produce the same result as 
+         @code{develop(f,N)}.@*
+         If the matrix M of L has n columns then, compared with 
+         @code{param(L)}, @code{param(extdevelop(L,N))} will increase the
+         exactness by at least (N-n) more significant monomials.
 SEE ALSO: develop, reddevelop, param
 EXAMPLE: example extdevelop;  shows an example
@@ -2145 +2161 @@
   }
   // ------ the example starts here -------
-  "EXAMPLE:"; echo = 2;
+  "EXAMPLE:"; echo = 2; 
   ring exring=0,(x,y),dp;
   list hne=reddevelop(x14-3y2x11-y3x10-y2x9+3y4x8+y5x7+3y4x6+x5*(-y6+y5)
                       -3y6x3-y7x2+y8);
-  print(hne[1][1]); // finite HNE
+  print(hne[1][1]);    // HNE of 1st branch is finite  
   print(extdevelop(hne[1],5)[1]);
-  // ------------------------------------------
-  print(hne[2][1]); // HNE that can be extended
+  print(hne[2][1]);    // HNE of 2nd branch can be extended
   list ehne=extdevelop(hne[2],5);
-  print(ehne[1]); // new HN-matrix has 5 columns
+  print(ehne[1]);      // new HN-matrix has 5 columns
   param(hne[2]);
   param(ehne);
@@ -2169 +2184 @@
 
 proc stripHNE (list l)
-"USAGE:   stripHNE(l);    takes the output both of develop(f) and reddevelop(f)
- @*        ( list l (matrix m, intvec v, int s[,poly g,...])
-             or list of lists in the form l )
-RETURN:  a list in the same format as l, but all polynomials g are set to zero
+"USAGE:   stripHNE(L);  L list
+ASSUME:  L is the output of @code{develop(f)}, or of 
+         @code{extdevelop(develop(f),n)}, or (one entry of) the output of 
+         @code{reddevelop(f)}.
+RETURN:  list in the same format as L, but all polynomials L[4], resp.
+         L[i][4], are set to zero.
 NOTE:    The purpose of this procedure is to remove huge amounts of data
          no longer needed. It is useful, if one or more of the polynomials
-         in l consumes much memory. It is still possible to compute invariants,
+         in L consume much memory. It is still possible to compute invariants,
          parametrizations etc. with the stripped HNE(s), but it is not possible
-         to use extdevelop with them.
+         to use @code{extdevelop} with them.
 SEE ALSO: develop, reddevelop, extdevelop
 EXAMPLE: example stripHNE;  shows an example
@@ -2194 +2211 @@
 }
 example
-{ "EXAMPLE:"; echo = 2;
+{  
+  "EXAMPLE:"; echo = 2;
+  int plevel=printlevel; printlevel=-1;
   ring r=0,(x,y),dp;
   list hne=develop(x2+y3+y4);
   hne;
   stripHNE(hne);
+  printlevel=plevel; echo = 0;
 }
 ///////////////////////////////////////////////////////////////////////////////
@@ -2288 +2308 @@
 proc HNdevelop (poly f)
 "USAGE:   HNdevelop(f); f poly
-RETURN:  Hamburger-Noether development of f:
-         A list of lists in the form of develop(f)
-         (matrix,intvec,int,poly -- the last int indicating irreducibility is
-         omitted); each entry contains the data for one of the branches of f.
-         For more details type `help develop;'
-CREATE:  a ring with name `HNEring', variables `x,y' and ordering `ls' over
-         a field extension of the current basering's ground field.
-         As the Hamburger-Noether development normally does not exist
+ASSUME:  f is a bivariate polynomial (in the first 2 ring variables)
+CREATE:  ring with name @code{HNEring}, variables @code{x,y} and ordering 
+         @code{ls} over a field extension of the current basering's ground 
+         field. @*
+         Since the Hamburger-Noether development usually does not exist
          in the originally given basering, @code{HNdevelop} always defines
-         HNEring and changes to it. The field extension is chosen minimal.
+         @code{HNEring} and CHANGES to it. The field extension is chosen 
+         minimally.
+RETURN:  list @code{L} of lists @code{L[i]} (corresponding to the output of
+         @code{develop(f[i])}, f[i] a branch of f, but the last entry being 
+         omitted).
+@texinfo
+@table @asis
+@item @code{L[i][1]}; matrix:
+         Each row contains the coefficients of the corresponding line of the
+         Hamburger-Noether expansion (HNE) for f[i]. The end of the line is 
+         marked in the matrix by the first ring variable (usually x).
+@item @code{L[i][2]}; intvec: 
+         indicating the length of lines of the HNE
+@item @code{L[i][3]}; int:
+         0  if the 1st ring variable was transversal (with respect to f[i]), @*
+         1  if the variables were changed at the beginning of the 
+            computation, @*
+        -1  if an error has occurred. 
+@item @code{L[i][4]}; poly: 
+         the transformed polynomial of f[i] to make it possible to extend the 
+         Hamburger-Noether development a posteriori without having to do
+         all the previous calculation once again (0 if not needed)
+@end table
+@end texinfo
 NOTE:    @code{HNdevelop} decides which procedure (@code{develop} or
-         @code{reddevelop}) applies best to the given problem and calls it.
-SEE ALSO: develop, reddevelop, extdevelop
+         @code{reddevelop}) applies best to the given problem and calls it. @*
+         If f is known to be irreducible as a power series, @code{develop(f)}
+         should be chosen instead to avoid the change of basering. @*
+         If @code{printlevel>=0} comments are displayed (default is 
+         @code{printlevel=0}).  
+SEE ALSO: develop, reddevelop, extdevelop, essdevelop, param, displayHNE
 EXAMPLE: example HNdevelop;  shows an example
 "
@@ -2367 +2411 @@
   list hne=HNdevelop(x4-y6);
   nameof(basering);
-  size(hne);           // i.e. x4-y6 has two branches
+  size(hne);           // number of branches
   print(hne[1][1]);    // HN-matrix of 1st branch
-  param(hne[1]);
-  param(hne[2]);
-  displayInvariants(hne);
+  param(hne[1]);       // parametrization of 1st branch
+  param(hne[2]);       // parametrization of 2nd branch
   kill HNEring,r;
   echo = 0;
@@ -2385 +2428 @@
 proc reddevelop (poly f)
 "USAGE:   reddevelop(f); f poly
-RETURN:  Hamburger-Noether development of f:
-         A list of lists in the form of develop(f)
-         (matrix,intvec,int,poly -- the last int indicating irreducibility is
-         omitted); each entry contains the data for one of the branches of f.
-         For more details type `help develop;'
-CREATE:  a ring with name `HNEring', variables `x,y' and ordering `ls' over
-         a field extension of the current basering's ground field.
-         As the Hamburger-Noether development of a reducible curve normally
-         does not exist in the given basering, @code{reddevelop} always defines
-         HNEring and changes to it. The field extension is chosen minimal.
-SEE ALSO: develop, extdevelop, displayHNE
+ASSUME:  f is a bivariate polynomial (in the first 2 ring variables)
+CREATE:  ring with name @code{HNEring}, variables @code{x,y} and ordering 
+         @code{ls} over a field extension of the current basering's ground 
+         field. @*
+         Since the Hamburger-Noether development of a reducible curve
+         singularity usually does not exist in the originally given basering,
+         @code{reddevelop} always defines @code{HNEring} and CHANGES to it. 
+         The field extension is chosen minimally.
+RETURN:  list @code{L} of lists @code{L[i]} (corresponding to the output of
+         @code{develop(f[i])}, f[i] a branch of f, but the last entry being 
+         omitted).
+@texinfo
+@table @asis
+@item @code{L[i][1]}; matrix:
+         Each row contains the coefficients of the corresponding line of the
+         Hamburger-Noether expansion (HNE) for f[i]. The end of the line is 
+         marked in the matrix by the first ring variable (usually x).
+@item @code{L[i][2]}; intvec: 
+         indicating the length of lines of the HNE
+@item @code{L[i][3]}; int:
+         0  if the 1st ring variable was transversal (with respect to f[i]), @*
+         1  if the variables were changed at the beginning of the 
+            computation, @*
+        -1  if an error has occurred. 
+@item @code{L[i][4]}; poly: 
+         the transformed polynomial of f[i] to make it possible to extend the 
+         Hamburger-Noether development a posteriori without having to do
+         all the previous calculation once again (0 if not needed)
+@end table
+@end texinfo
+NOTE:    If @code{printlevel>=0} comments are displayed (default is 
+         @code{printlevel=0}). 
+SEE ALSO: develop, extdevelop, essdevelop, param, displayHNE
 EXAMPLE: example reddevelop;  shows an example
 "
@@ -2418 +2483 @@
   // ------ the example starts here -------
   "EXAMPLE:"; echo = 2;
-  ring r=0,(x,y),dp;
-  list hne=reddevelop(x4-y6);
-  size(hne);           // i.e. x4-y6 has two branches
-  print(hne[1][1]);    // HN-matrix of 1st branch
-  param(hne[1]);
-  param(hne[2]);
-  displayInvariants(hne);
-  kill HNEring,r;
-  // ----------------- a more interesting example: --------------------
   ring r = 32003,(x,y),dp;
   poly f = x25+x24-4x23-1x22y+4x22+8x21y-2x21-12x20y-4x19y2+4x20+10x19y
@@ -2433 +2489 @@
           +126x10y4+4x8y6-126x8y5+84x6y6-36x4y7+9x2y8-1y9;
   list hne=reddevelop(f);
-  size(hne);
-  print(hne[1][1]);
-  print(hne[4][1]);
+  size(hne);            // number of branches 
+  print(hne[1][1]);     // HN-matrix of 1st branch
+  print(hne[4][1]);     // HN-matrix of 4th branch
   // a ring change was necessary, a is a parameter
   HNEring;
@@ -2769 +2825 @@
 proc essdevelop (poly f)
 "USAGE:   essdevelop(f); f poly
-RETURN:  Hamburger-Noether development of essential branches of f:
-         A list of lists in the form of develop(f)
-         (matrix,intvec,int,poly -- the last int indicating irreducibility is
-         omitted); each entry contains the data for one of the branches of f.
-         For more details type `help develop;'
-CREATE:  a ring with name `HNEring', variables `x,y' and ordering `ls' over
-         a field extension of the current basering's ground field.
-         As the Hamburger-Noether development of a reducible curve normally
-         does not exist in the given basering, @code{essdevelop} always defines
-         HNEring and changes to it. The field extension is chosen minimal.
+ASSUME:  f is a bivariate polynomial (in the first 2 ring variables)
+CREATE:  ring with name @code{HNEring}, variables @code{x,y} and ordering 
+         @code{ls} over a field extension of the current basering's ground 
+         field. @*
+         Since the Hamburger-Noether development of a reducible curve
+         singularity usually does not exist in the originally given basering,
+         @code{essdevelop} always defines @code{HNEring} and CHANGES to it. 
+         The field extension is chosen minimally.
+RETURN:  list @code{L} of lists @code{L[i]} (corresponding to the output of
+         @code{develop(f[i])}, f[i] an \"essential\" branch of f, but the last 
+         entry being omitted).@*
+         For more details type @code{help reddevelop;}.
 NOTE:    If the HNE needs a field extension, some of the branches will be
          conjugate. In this case @code{essdevelop} reduces the computation to
-         one representative for each group of conjugate branches.
+         one representative for each group of conjugate branches.@*
          Note that the degree of each branch is in general less than the degree
-         of the field extension in which all HNEs can be put.
-
+         of the field extension in which all HNEs can be put.@*
          Use @code{reddevelop} or @code{HNdevelop} to compute a complete HNE,
-         i.e. a HNE for all branches.
+         i.e., a HNE for all branches.@*
+         If @code{printlevel>=0} comments are displayed (default is 
+         @code{printlevel=0}). 
 SEE ALSO: develop, reddevelop, HNdevelop, extdevelop
 EXAMPLE: example essdevelop;  shows an example
@@ -2817 +2876 @@
   // --------- compute all branches: ---------
   list hne=reddevelop(f);
-  displayHNE(hne);
+  displayHNE(hne[1]);   // HN-matrix of 1st branch
+  displayHNE(hne[4]);   // HN-matrix of 4th branch
   setring r;
+  kill HNEring;
   // --- compute only one of conjugate branches: ---
   list hne=essdevelop(f);
   displayHNE(hne);
-  // nr. 1 of essdevelop represents nr. 1 - 3 of reddevelop and
-  // nr. 2 of essdevelop represents nr. 4 + 5 of reddevelop
+  // no. 1 of essdevelop represents no. 1 - 3 of reddevelop and
+  // no. 2 of essdevelop represents no. 4 + 5 of reddevelop
+  kill HNEring,r;
   echo = 0;
   // --- restore HNEring if previously defined ---

Singular/LIB/primdec.lib

@@ -1 +1 @@
 ///////////////////////////////////////////////////////////////////////////////
-version="$Id: primdec.lib,v 1.94 2001-01-16 13:48:38 Singular Exp $";
+version="$Id: primdec.lib,v 1.95 2001-02-05 12:01:38 lossen Exp $";
 category="Commutative Algebra";
 info="
@@ -10 +10 @@
 OVERVIEW:
     Algorithms for primary decomposition based on the ideas of
-    Gianni,Trager,Zacharias was written by Gerhard Pfister.
-    Algorithms for primary decomposition based on the ideas of
-    Shimoyama/Yokoyama was written by Wolfram Decker and Hans Schoenemann.
- @* These procedures are implemented to be used in characteristic 0
-    They also work in positive characteristic >> 0.
+    Gianni, Trager and Zacharias (implementation by Gerhard Pfister), 
+    respectively based on the ideas of Shimoyama and Yokoyama (implementation 
+    by Wolfram Decker and Hans Schoenemann).
+ @* The procedures are implemented to be used in characteristic 0.
+ @* They also work in positive characteristic >> 0.
  @* In small characteristic and for algebraic extensions, primdecGTZ and
-    minAssGTZ may not terminate and primdecSY and minAssChar may not give
+    minAssGTZ may not terminate, while primdecSY and minAssChar may not give
     a complete decomposition.
     Algorithms for the computation of the radical based on the ideas of
-    Krick/Logar and Kemper was written by Gerhard Pfister.
+    Krick, Logar and Kemper (implementation by Gerhard Pfister).
 
 PROCEDURES:
@@ -815 +815 @@
          If ser!=(0) and ser is contained in j or if j is not zero-dimen-
          sional then ideal(1),ideal(1) is returned
-NOTE:    Algorithm of Gianni, Traeger, Zacharias
+NOTE:    Algorithm of Gianni/Trager/Zacharias
 EXAMPLE: example zero_decomp; shows an example
 "
@@ -1752 +1752 @@
 proc equidim(ideal i,list #)
 "USAGE:  equidim(i) or equidim(i,1) ; i ideal
-         equidim(i,1) uses the algorithm of Eisenbud, Hunecke and Vasconcelos
-RETURN: list of equidimensional ideals a_1,...,a_s such that the following
-         holds:
-@*       a_s is the equidimensional locus of i, a1,...a_s-1 are the lower
-         dimensional equidimensional loci  with (perhaps) modified embedded
-         components. I.e. an embedded component q (primary ideal) of i can be
-         replaced in the decomposition by a primary ideal q1 with the same
-         radical as q.
+RETURN: list of equidimensional ideals a[1],...,a[s] with:
+        - a[s] the equidimensional locus of i, 
+        - a[1],...,a[s-1] the lower dimensional equidimensional loci.  
+NOTE:    An embedded component q (primary ideal) of i can be replaced in the 
+         decomposition by a primary ideal q1 with the same radical as q. @*
+         @code{equidim(i,1)} uses the algorithm of Eisenbud/Huneke/Vasconcelos.
+
 EXAMPLE:example equidim; shows an example
 "
@@ -1858 +1857 @@
 { "EXAMPLE:"; echo = 2;
    ring  r = 32003,(x,y,z),dp;
-   ideal i=intersect(ideal(z),ideal(x,y),ideal(x2,z2),ideal(x5,y5,z5));
+   ideal i = intersect(ideal(z),ideal(x,y),ideal(x2,z2),ideal(x5,y5,z5));
    equidim(i);
 }
@@ -1975 +1974 @@
 { "EXAMPLE:"; echo = 2;
    ring  r = 32003,(x,y,z),dp;
-   ideal i=intersect(ideal(z),ideal(x,y),ideal(x2,z2),ideal(x5,y5,z5));
+   ideal i = intersect(ideal(z),ideal(x,y),ideal(x2,z2),ideal(x5,y5,z5));
    equidimMax(i);
 }
@@ -1986 +1985 @@
          (at even positions in the list)
          (resp. a list of the minimal associated primes)
-NOTE:    Algorithm of Gianni, Traeger, Zacharias
+NOTE:    Algorithm of Gianni/Trager/Zacharias
 EXAMPLE: example decomp; shows an example
 "
@@ -3150 +3149 @@
 "USAGE:   radicalEHV(i); i ideal.
 RETURN:  ideal, the radical of i.
-NOTE:    The algorithm of Eisenbud,Huneke,Vasconcelos is used.
+NOTE:    The algorithm of Eisenbud/Huneke/Vasconcelos is used.
          Works only in characteristic 0 or p large.
 EXAMPLE: example radicalEHV; shows an example
@@ -4381 +4380 @@
 "USAGE:   primdecGTZ(i); i ideal
 RETURN:  a list pr of primary ideals and their associated primes:
-@*       -  pr[i][1] the i-th primary component,
-@*       -  pr[i][2] the i-th prime component.
-NOTE:    Algorithm of Gianni, Traeger, Zacharias.
+@format   
+   pr[i][1]   the i-th primary component,
+   pr[i][2]   the i-th prime component.
+@end format
+NOTE:    Algorithm of Gianni/Trager/Zacharias.
          Designed for characteristic 0, works also in char k > 0, if it
          terminates (may result in an infinite loop in small characteristic!)
@@ -4408 +4409 @@
 ///////////////////////////////////////////////////////////////////////////////
 
-proc primdecSY(ideal i, list #))
+proc primdecSY(ideal i, list #)
 "USAGE:   primdecSY(i); i ideal, c int
-@*         if c=0, the given ordering of the variables is used.
-@*         if c=1, minAssChar tries to use an optimal ordering,
-@*         if c=2, minAssGTZ is used
-@*         if c=3, minAssGTZ and facstd is used
 RETURN:  a list pr of primary ideals and their associated primes:
-@*         -  pr[i][1] the i-th primary component,
-@*         -  pr[i][2] the i-th prime component.
-NOTE:    Algorithm of Shimoyama-Yokoyama.
+@format   
+   pr[i][1]   the i-th primary component,
+   pr[i][2]   the i-th prime component.
+@end format
+NOTE:    Algorithm of Shimoyama/Yokoyama.
+@format
+   if c=0,  the given ordering of the variables is used,
+   if c=1,  minAssChar tries to use an optimal ordering,
+   if c=2,  minAssGTZ is used,
+   if c=3,  minAssGTZ and facstd are used.
+@end format
          Due to a bug in the factorization, the result may be not completely
          decomposed in small characteristic.
@@ -4472 +4477 @@
 ///////////////////////////////////////////////////////////////////////////////
 proc minAssChar(ideal i, list #)
-"USAGE:   minAssChar(i[,c]); i ideal.
-         If c=0, the given ordering of the variables is used.
+"USAGE:   minAssChar(i[,c]); i ideal, c int.
+RETURN:  list, the minimal associated prime ideals of i.
+NOTE:    If c=0, the given ordering of the variables is used. @*
          Otherwise, the system tries to find an optimal ordering,
-         which in some cases may considerably speed up the algorithm.
-RETURN:  a list, the minimal associated prime ideals of i.
-NOTE:    Due to a bug in the factorization, the result may be not completely
+         which in some cases may considerably speed up the algorithm. @*
+         Due to a bug in the factorization, the result may be not completely
          decomposed in small characteristic.
 EXAMPLE: example minAssChar; shows an example
@@ -4590 +4595 @@
 proc prepareAss(ideal i)
 "USAGE:   prepareAss(i); i ideal
-RETURN:  a list, the radicals of the maximal dimensional components of i.
-NOTE:    Uses algorithm of Eisenbud, Huneke and Vasconcelos.
+RETURN:  list, the radicals of the maximal dimensional components of i.
+NOTE:    Uses algorithm of Eisenbud/Huneke/Vasconcelos.
 EXAMPLE: example prepareAss; shows an example
 "
@@ -4673 +4678 @@
 
 proc testPrimary(list pr, ideal k)
-"USAGE:   testPrimary(pr,k); pr a list, result of primdecGTZ(k) or primdecSY(k)
-RETURN:  int, 1 if intersection of the primary ideals in pr is k, 0 if not
+"USAGE:   testPrimary(pr,k); pr a list, k an ideal.
+ASSUME:  pr is the result of primdecGTZ(k) or primdecSY(k).
+RETURN:  int, 1 if the intersection of the ideals in pr is k, 0 if not
 EXAMPLE: example testPrimary; shows an example
 "
@@ -4700 +4706 @@
 proc zerodec(ideal I)
 "USAGE:   zerodec(I); I ideal
-RETURN:  A list of primary ideals, the zero-dimensional decomposition of I
-ASSUME:  I is zero-dimensional, the characterisitic of the ground field is 0
-NOTE:    The algorithm (of C. Monico), works well only for small total number
-         of solutions (vdim(std(I)) should be < 100) and without parameters.
-         In practice, it works also in big characteristic p>0 but may fail
-         for small p.
-@*         If printlevel > 0 (default = 0) additional information is displayed
+ASSUME:  I is zero-dimensional, the characteristic of the ground field is 0
+RETURN:  list of primary ideals, the zero-dimensional decomposition of I
+NOTE:    The algorithm (of Monico), works well only for a small total number
+         of solutions (@code{vdim(std(I))} should be < 100) and without 
+         parameters. In practice, it works also in large characteristic p>0 
+         but may fail for small p.
+@*       If printlevel > 0 (default = 0) additional information is displayed.
 EXAMPLE: example zerodec; shows an example
 "

Singular/LIB/primitiv.lib

@@ -3 +3 @@
 // This library is for Singular 1.2 or newer
 
-version="$Id: primitiv.lib,v 1.14 2001-01-16 13:48:40 Singular Exp $";
+version="$Id: primitiv.lib,v 1.15 2001-02-05 12:01:39 lossen Exp $";
 category="Commutative Algebra";
 info="
@@ -19 +19 @@
 
 proc primitive(ideal i)
-"USAGE:   primitive(i); i ideal of the following form:
-          Let k be the ground field of your basering, a_1,...,a_n algebraic
-          over k, m_1(x_1), m_2(x_1,x_2),...,m_n(x_1,...,x_n) polynomials over
-          k such that  m_j(a_1,...,a_(j-1),x_j) is minimal polynomial for
-          a_j over k(a_1,...,a_(j-1)) for all j=1,...,n.
-          Then i has to be generated by m_1,...,m_n.
-RETURN:   ideal j in k[x_n] such that
-          j[1] is minimal polynomial for a primitive element b of
-          k(a_1,...,a_n)=k(b) over k
-          j[2],...,j[n+1] polynomials in k[x_n] : j[i+1](b)=a_i for i=1,...,n
-NOTE:     the number of variables in the basering has to be exactly the number
-          n of given algebraic elements (and minimal polynomials).
-          If k has few elements it may happen that no linear combination
-          of a_1,...,a_n is a primitive element. In this case `primitive'
-          returns the zero ideal. If this occurs use primitive_extra instead.
+"USAGE:   primitive(i); i ideal
+ASSUME:   i is given by generators m[1],...,m[n] such that for j=1,...,n @*
+          -  m[j] is a polynomial in k[x(1),...,x(j)] @* 
+          -  m[j](a[1],...,a[j-1],x(j)) is the minimal polynomial for a[j] over 
+             k(a[1],...,a[j-1]) @*
+          (k the ground field of the current basering and x(1),...,x(n)
+          the ring variables). 
+RETURN:   ideal j in k[x(n)] with
+          - j[1] a minimal polynomial for a primitive element b of     
+                 k(a[1],...,a[n]) over k,
+          - j[2],...,j[n+1] polynomials in k[x(n)] such that j[i+1](b)=a[i] 
+                 for i=1,...,n.
+NOTE:     the number of variables in the basering has to be exactly n, 
+          the number of given generators (i.e., minimal polynomials).@*
+          If the ground field k has only a few elements it may happen that no 
+          linear combination of a[1],...,a[n] is a primitive element. In this 
+          case @code{primitive(i)} returns the zero ideal, and one should use
+          @code{primitive_extra(i)} instead.
 SEE ALSO: primitive_extra
 KEYWORDS: primitive element
@@ -122 +125 @@
  ring exring=0,(x,y),dp;
  ideal i=x2+1,y2-x;                  // compute Q(i,i^(1/2))=:L
- ideal j=primitive(i);               // -> we have L=Q(a):
- "minimal polynomial of a:",j[1];    // => a=(-1)^(1/4)
- "polynomial for i:       ",j[2];    // => i=a^2
- "polynomial for i^(1/2): ",j[3];    // => i^(1/2)=a
- // ==> the 2nd element was already primitive!
+ ideal j=primitive(i);
+ j[1];                               // L=Q(a) with a=(-1)^(1/4)
+ j[2];                               // i=a^2
+ j[3];                               // i^(1/2)=a
+ // the 2nd element was already primitive!
  j=primitive(ideal(x2-2,y2-3));      // compute Q(sqrt(2),sqrt(3))
- "minimal polynomial:",j[1];
- "polynomial p s.t. p(a)=sqrt(2):",j[2];
- "polynomial r s.t. r(a)=sqrt(3):",j[3];
- // ==> no element was primitive -- the calculation of a is based
- //     on a random choice.
+ j[1];
+ j[2];
+ j[3];
+ // no element was primitive -- the calculation of primitive elements 
+ // is based on a random choice.
 }
 ///////////////////////////////////////////////////////////////////////////////
 
 proc primitive_extra(ideal i)
-"USAGE:   primitive_extra(i);  ideal i=f,g;  with the following properties: @*
-          Let k=Q or k=Z/pZ be the ground field of the basering, a,b algebraic
-          over k, x the name of the first ring variable, y the name of the
-          second, then:
-          f is the minimal polynomial of a in k[x], g is a polynomial in
-          k[x,y] s.t. g(a,y) is the minimal polynomial of b in k(a)[y]
+"USAGE:   primitive_extra(i); i ideal
+ASSUME:  The ground field of the basering is k=Q or k=Z/pZ and the ideal
+         i is given by 2 generators f,g with the following properties: 
+@format
+   f is the minimal polynomial of a in k[x], 
+   g is a polynomial in k[x,y] s.th. g(a,y) is the minpoly of b in k(a)[y].
+@end format
+          Here, x is the name of the first ring variable, y the name of the
+          second.
 RETURN:  ideal j in k[y] such that
-         j[1] is minimal polynomial over k for a primitive element c of
-         k(a,b)=k(c)
-         j[2] is a polynomial s.t. j[2](c)=a
-NOTE:    While `primitive' may fail for finite fields, this proc tries all
-         elements of k(a,b) and hence finds by assurance a primitive element.
-         In order to do this (try all elements) field extensions like Z/pZ(a)
-         are not allowed for the ground field k.
-         primitive_extra assumes that g is monic as polynomial in (k[x])[y]
+@format
+   j[1] is the minimal polynomial for a primitive element c of k(a,b) over k,
+   j[2] is a polynomial s.th. j[2](c)=a.
+@end format
+NOTE:    While @code{primitive(i)} may fail for finite fields, 
+         @code{primitive_extra(i)} tries all elements of k(a,b) and, hence, 
+         always finds a primitive element. @*
+         In order to do this (try all elements), field extensions like Z/pZ(a)
+         are not allowed for the ground field k. @*
+         @code{primitive_extra(i)} assumes that the second generator, g, is 
+         monic as polynomial in (k[x])[y].
 EXAMPLE: example primitive_extra;  shows an example
 "
@@ -245 +254 @@
 
 proc splitring
-"USAGE:   splitring(f,R[,L]);  f poly, univariate and irreducible(!) over the
-         active basering; R string, L list of polys and/or ideals (optional)
-CREATE:  a ring with name R, in which f is reducible, and change to it.
-         If the old ring has no parameter, the name 'a' is chosen for the
-         parameter of R (if a is no variable; if it is, the proc takes 'b',
-         etc.; if a,b,c,o are variables of the ring, produce an error message),
-         otherwise the name of the parameter is kept and only the
-         minimal polynomial is changed.
-         The names of variables and orderings are not affected.
-         It is also allowed to call splitring with R==\"\".
-         Then the old basering will be REPLACED by the new ring
-         (with the same name as the old ring).
+"USAGE:   splitring(f,R[,L]); f poly, R string, L list of polys and/or ideals 
+         (optional)
+ASSUME:  f is univariate and irreducible over the active basering. @*
+         The active ring must allow an algebraic extension (e.g., it cannot 
+         be a transcendent ring extension of Q or Z/p).
+CREATE:  a ring with name R, in which f is reducible, and CHANGE to it.
 RETURN:  list L mapped into the new ring R, if L is given; else nothing
-ASSUME:  The active ring must allow an algebraic extension
-         (e.g. it cannot be a transcendent ring extension of Q or Z/p).
+NOTE:    If the old ring has no parameter, the name @code{a} is chosen for the
+         parameter of R (if @code{a} is no ring variable; if it is, @code{b} is 
+         chosen, etc.; if @code{a,b,c,o} are ring variables, 
+         @code{splitring(f,R[,L])} produces an error message), otherwise the 
+         name of the parameter is kept and only the minimal polynomial is 
+         changed. @*
+         The names of the ring variables and the orderings are not affected. @*
+         It is also allowed to call @code{splitring} with R=\"\".
+         Then the old basering will be REPLACED by the new ring (with the 
+         same name as the old ring).
 KEYWORDS: algebraic field extension; extension of rings
 EXAMPLE: example splitring;  shows an example
@@ -389 +400 @@
  ring r=0,(x,y),dp;
  splitring(x2-2,"r1");   // change to Q(sqrt(2))
- splitring(x2-a,"r2",a); // change to Q(sqrt(2),sqrt(sqrt(2)))=Q(a)
-                         // and return the transformed old parameter
- // the result is (a2) == (sqrt(sqrt(2)))^2
+ // change to Q(sqrt(2),sqrt(sqrt(2)))=Q(a) and return the transformed 
+ // old parameter:
+ splitring(x2-a,"r2",a); 
+ // the result is (a)^2 = (sqrt(sqrt(2)))^2
  nameof(basering);
  r2;