@c ---content LibInfo---
@comment This file was generated by doc2tex.pl from d2t_singular/primitiv_lib.doc
@comment DO NOT EDIT DIRECTLY, BUT EDIT d2t_singular/primitiv_lib.doc INSTEAD
@c library version: (1.15,2001/02/05)
@c library file: ../Singular/LIB/primitiv.lib
@cindex primitiv.lib
@cindex primitiv_lib
@table @asis
@item @strong{Library:}
primitiv.lib
@item @strong{Purpose:}
    Computing a Primitive Element
@item @strong{Author:}
Martin Lamm, email: lamm@@mathematik.uni-kl.de

@end table

@strong{Procedures:}
@menu
* primitive:: find minimal polynomial for a primitive element
* primitive_extra:: find primitive element for two generators
* splitring:: define ring extension with name R and switch to it
@end menu
@c ---end content LibInfo---

@c ------------------- primitive -------------
@node primitive, primitive_extra,, primitiv_lib
@subsubsection primitive
@cindex primitive
@c ---content primitive---
Procedure from library @code{primitiv.lib} (@pxref{primitiv_lib}).

@table @asis
@item @strong{Usage:}
primitive(i); i ideal

@item @strong{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).

@item @strong{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.

@item @strong{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.

@cindex primitive element
@end table
@strong{Example:}
@smallexample
@c computed example primitive d2t_singular/primitiv_lib.doc:62 
LIB "primitiv.lib";
ring exring=0,(x,y),dp;
ideal i=x2+1,y2-x;                  // compute Q(i,i^(1/2))=:L
ideal j=primitive(i);
j[1];                               // L=Q(a) with a=(-1)^(1/4)
@expansion{} y4+1
j[2];                               // i=a^2
@expansion{} y2
j[3];                               // i^(1/2)=a
@expansion{} y
// the 2nd element was already primitive!
j=primitive(ideal(x2-2,y2-3));      // compute Q(sqrt(2),sqrt(3))
j[1];
@expansion{} y4-10y2+1
j[2];
@expansion{} 1/2y3-9/2y
j[3];
@expansion{} -1/2y3+11/2y
// no element was primitive -- the calculation of primitive elements 
// is based on a random choice.
@c end example primitive d2t_singular/primitiv_lib.doc:62
@end smallexample
@c inserted refs from d2t_singular/primitiv_lib.doc:79
@ifinfo
@menu
See also:
* primitive_extra::
@end menu
@end ifinfo
@iftex
@strong{See also:}
@ref{primitive_extra}.
@end iftex
@c end inserted refs from d2t_singular/primitiv_lib.doc:79

@c ---end content primitive---

@c ------------------- primitive_extra -------------
@node primitive_extra, splitring, primitive, primitiv_lib
@subsubsection primitive_extra
@cindex primitive_extra
@c ---content primitive_extra---
Procedure from library @code{primitiv.lib} (@pxref{primitiv_lib}).

@table @asis
@item @strong{Usage:}
primitive_extra(i); i ideal

@item @strong{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.

@item @strong{Return:}
ideal j in k[y] such that
@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

@item @strong{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].

@end table
@strong{Example:}
@smallexample
@c computed example primitive_extra d2t_singular/primitiv_lib.doc:125 
LIB "primitiv.lib";
ring exring=3,(x,y),dp;
ideal i=x2+1,y3+y2-1;
primitive_extra(i);
@expansion{} _[1]=y6-y5+y4-y3-y-1
@expansion{} _[2]=y5+y4+y2+y+1
ring extension=(3,y),x,dp;
minpoly=y6-y5+y4-y3-y-1;
number a=y5+y4+y2+y+1;
a^2;
@expansion{} -1
factorize(x2+1);
@expansion{} [1]:
@expansion{}    _[1]=1
@expansion{}    _[2]=x+(-y5-y4-y2-y-1)
@expansion{}    _[3]=x+(y5+y4+y2+y+1)
@expansion{} [2]:
@expansion{}    1,1,1
factorize(x3+x2-1);
@expansion{} [1]:
@expansion{}    _[1]=1
@expansion{}    _[2]=x+(-y5-y4-y3-y2-y-1)
@expansion{}    _[3]=x+(y5+y4+y2+1)
@expansion{}    _[4]=x+(y3+y+1)
@expansion{} [2]:
@expansion{}    1,1,1,1
@c end example primitive_extra d2t_singular/primitiv_lib.doc:125
@end smallexample
@c ---end content primitive_extra---

@c ------------------- splitring -------------
@node splitring,, primitive_extra, primitiv_lib
@subsubsection splitring
@cindex splitring
@c ---content splitring---
Procedure from library @code{primitiv.lib} (@pxref{primitiv_lib}).

@table @asis
@item @strong{Usage:}
splitring(f,R[,L]); f poly, R string, L list of polys and/or ideals
(optional)

@item @strong{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).

@item @strong{Create:}
a ring with name R, in which f is reducible, and CHANGE to it.

@item @strong{Return:}
list L mapped into the new ring R, if L is given; else nothing

@item @strong{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).

@cindex algebraic field extension
@cindex extension of rings
@end table
@strong{Example:}
@smallexample
@c computed example splitring d2t_singular/primitiv_lib.doc:180 
LIB "primitiv.lib";
ring r=0,(x,y),dp;
splitring(x2-2,"r1");   // change to Q(sqrt(2))
// change to Q(sqrt(2),sqrt(sqrt(2)))=Q(a) and return the transformed 
// old parameter:
splitring(x2-a,"r2",a); 
@expansion{} // new minimal polynomial: a4-2
@expansion{} [1]:
@expansion{}    (a2)
// the result is (a)^2 = (sqrt(sqrt(2)))^2
nameof(basering);
@expansion{} r2
r2;
@expansion{} //   characteristic : 0
@expansion{} //   1 parameter    : a 
@expansion{} //   minpoly        : (a4-2)
@expansion{} //   number of vars : 2
@expansion{} //        block   1 : ordering dp
@expansion{} //                  : names    x y 
@expansion{} //        block   2 : ordering C
kill r1; kill r2;
@c end example splitring d2t_singular/primitiv_lib.doc:180
@end smallexample
@c ---end content splitring---
