@c ---content LibInfo---
@comment This file was generated by doc2tex.pl from d2t_singular/ainvar_lib.doc
@comment DO NOT EDIT DIRECTLY, BUT EDIT d2t_singular/ainvar_lib.doc INSTEAD
@c library version: (1.6.2.2,2002/04/12)
@c library file: ../Singular/LIB/ainvar.lib
@cindex ainvar.lib
@cindex ainvar_lib
@table @asis
@item @strong{Library:}
ainvar.lib
@item @strong{Purpose:}
    Invariant Rings of the Additive Group
@item @strong{Authors:}
Gerhard Pfister (email: pfister@@mathematik.uni-kl.de),
Gert-Martin Greuel (email: greuel@@mathematik.uni-kl.de)

@end table

@strong{Procedures:}
@menu
* invariantRing:: compute ring of invariants of (K,+)-action given by m
* derivate:: derivation of f with respect to the vector field m
* actionIsProper:: tests whether action defined by m is proper
* reduction:: SAGBI reduction of p in the subring generated by I
* completeReduction:: complete SAGBI reduction
* localInvar:: invariant polynomial under m computed from p,...
* furtherInvar:: compute further invariants of m from the given ones
* sortier:: sorts generators of id by increasing leading terms
@end menu
@c ---end content LibInfo---

@c ------------------- invariantRing -------------
@node invariantRing, derivate,, ainvar_lib
@subsubsection invariantRing
@cindex invariantRing
@c ---content invariantRing---
Procedure from library @code{ainvar.lib} (@pxref{ainvar_lib}).

@table @asis
@item @strong{Usage:}
invariantRing(m,p,q,b[,r,pa]); m matrix, p,q poly, b,r int, pa string

@item @strong{Assume:}
p,q variables with m(p)=q and q invariant under m
@*i.e. if p=x(i) and q=x(j) then m[j,1]=0 and m[i,1]=x(j)

@item @strong{Return:}
ideal, containing generators of the ring of invariants of the
additive group (K,+) given by the vector field
@format
         m = m[1,1]*d/dx(1) +...+ m[n,1]*d/dx(n).
@end format
If b>0 the computation stops after all invariants of degree <= b
(and at least one of higher degree) are found or when all invariants
are computed.
@*If b<=0, the computation continues until all generators
of the ring of invariants are computed (should be used only if the
ring of invariants is known to be finitely generated otherwise the
algorithm might not stop).
@*If r=1 a different reduction is used which is sometimes faster
(default r=0).

@item @strong{Display:}
if pa is given (any string as 5th or 6th argument), the computation
pauses whenever new invariants are found and displays them

@item @strong{Theory:}
The algorithm to compute the ring of invariants works in char 0
or big enough characteristic. (K,+) acts as the exponential of the
vector field defined by the matrix m. For background see G.-M. Greuel,
G. Pfister, Geometric quotients of unipotent group actions, Proc.
London Math. Soc. (3) 67, 75-105 (1993).

@end table
@strong{Example:}
@smallexample
@c computed example invariantRing d2t_singular/ainvar_lib.doc:75 
LIB "ainvar.lib";
//Winkelmann: free action but Spec(k[x(1),...,x(5)]) --> Spec(invariant ring)
//is not surjective
ring rw=0,(x(1..5)),dp;
matrix m[5][1];
m[3,1]=x(1);
m[4,1]=x(2);
m[5,1]=1+x(1)*x(4)+x(2)*x(3);
ideal in=invariantRing(m,x(3),x(1),0);      //compute full invarint ring
in;
@expansion{} in[1]=x(1)
@expansion{} in[2]=x(2)
@expansion{} in[3]=x(2)*x(3)*x(4)-x(2)*x(5)+x(4)
@expansion{} in[4]=x(1)*x(3)*x(4)-x(1)*x(5)+x(3)
//Deveney/Finston: The ring of invariants is not finitely generated
ring rf=0,(x(1..7)),dp;
matrix m[7][1];
m[4,1]=x(1)^3;
m[5,1]=x(2)^3;
m[6,1]=x(3)^3;
m[7,1]=(x(1)*x(2)*x(3))^2;
ideal in=invariantRing(m,x(4),x(1),6);      //all invariants up to degree 6
in;
@expansion{} in[1]=x(1)
@expansion{} in[2]=x(3)
@expansion{} in[3]=x(2)
@expansion{} in[4]=x(3)^3*x(4)-x(1)^3*x(6)
@expansion{} in[5]=x(2)^3*x(4)-x(1)^3*x(5)
@expansion{} in[6]=x(2)^2*x(3)^2*x(4)-x(1)*x(7)
@expansion{} in[7]=x(1)^2*x(2)^2*x(6)-x(3)*x(7)
@expansion{} in[8]=x(1)^2*x(3)^2*x(5)-x(2)*x(7)
@expansion{} in[9]=x(1)^2*x(2)*x(3)^4*x(4)*x(5)+x(1)^2*x(2)^4*x(3)*x(4)*x(6)-x(1)^5*x(\
   2)*x(3)*x(5)*x(6)-2*x(2)^2*x(3)^2*x(4)*x(7)+x(1)*x(7)^2
@c end example invariantRing d2t_singular/ainvar_lib.doc:75
@end smallexample
@c ---end content invariantRing---

@c ------------------- derivate -------------
@node derivate, actionIsProper, invariantRing, ainvar_lib
@subsubsection derivate
@cindex derivate
@c ---content derivate---
Procedure from library @code{ainvar.lib} (@pxref{ainvar_lib}).

@table @asis
@item @strong{Usage:}
derivate(m,id); m matrix, id poly/vector/ideal

@item @strong{Assume:}
m is a nx1 matrix, where n = number of variables of the basering

@item @strong{Return:}
poly/vector/ideal (same type as input), result of applying the
vector field by the matrix m componentwise to id;

@item @strong{Note:}
the vector field is m[1,1]*d/dx(1) +...+ m[1,n]*d/dx(n)

@end table
@strong{Example:}
@smallexample
@c computed example derivate d2t_singular/ainvar_lib.doc:123 
LIB "ainvar.lib";
ring q=0,(x,y,z,u,v,w),dp;
poly f=2xz-y2;
matrix m[6][1] =x,y,0,u,v;
derivate(m,f);
@expansion{} -2y2+2xz
vector v = [2xz-y2,u6-3];
derivate(m,v);
@expansion{} 6u6*gen(2)-2y2*gen(1)+2xz*gen(1)
derivate(m,ideal(2xz-y2,u6-3));
@expansion{} _[1]=-2y2+2xz
@expansion{} _[2]=6u6
@c end example derivate d2t_singular/ainvar_lib.doc:123
@end smallexample
@c ---end content derivate---

@c ------------------- actionIsProper -------------
@node actionIsProper, reduction, derivate, ainvar_lib
@subsubsection actionIsProper
@cindex actionIsProper
@c ---content actionIsProper---
Procedure from library @code{ainvar.lib} (@pxref{ainvar_lib}).

@table @asis
@item @strong{Usage:}
actionIsProper(m); m matrix

@item @strong{Assume:}
m is a nx1 matrix, where n = number of variables of the basering

@item @strong{Return:}
int = 1, if the action defined by m is proper, 0 if not

@item @strong{Note:}
m defines a group action which is the exponential of the vector
field m[1,1]*d/dx(1) +...+ m[1,n]*d/dx(n)

@end table
@strong{Example:}
@smallexample
@c computed example actionIsProper d2t_singular/ainvar_lib.doc:160 
LIB "ainvar.lib";
ring rf=0,x(1..7),dp;
matrix m[7][1];
m[4,1]=x(1)^3;
m[5,1]=x(2)^3;
m[6,1]=x(3)^3;
m[7,1]=(x(1)*x(2)*x(3))^2;
actionIsProper(m);
@expansion{} 0
ring rd=0,x(1..5),dp;
matrix m[5][1];
m[3,1]=x(1);
m[4,1]=x(2);
m[5,1]=1+x(1)*x(4)^2;
actionIsProper(m);
@expansion{} 1
@c end example actionIsProper d2t_singular/ainvar_lib.doc:160
@end smallexample
@c ---end content actionIsProper---

@c ------------------- reduction -------------
@node reduction, completeReduction, actionIsProper, ainvar_lib
@subsubsection reduction
@cindex reduction
@c ---content reduction---
Procedure from library @code{ainvar.lib} (@pxref{ainvar_lib}).

@table @asis
@item @strong{Usage:}
reduction(p,I[,q,n]); p poly, I ideal, [q monomial, n int (optional)]

@item @strong{Return:}
a polynomial equal to p-H(f1,...,fr), in case the leading
term LT(p) of p is of the form H(LT(f1),...,LT(fr)) for some
polynomial H in r variables over the base field, I=f1,...,fr;
if q is given, a maximal power a is computed such that q^a divides
p-H(f1,...,fr), and then (p-H(f1,...,fr))/q^a is returned;
return p if no H is found
@*if n=1, a different algorithm is chosen which is sometimes faster
(default: n=0; q and n can be given (or not) in any order)

@item @strong{Note:}
this is a kind of SAGBI reduction in the subalgebra K[f1,...,fr] of
the basering

@end table
@strong{Example:}
@smallexample
@c computed example reduction d2t_singular/ainvar_lib.doc:207 
LIB "ainvar.lib";
ring q=0,(x,y,z,u,v,w),dp;
poly p=x2yz-x2v;
ideal dom =x-w,u2w+1,yz-v;
reduction(p,dom);
@expansion{} 2xyzw-yzw2-2xvw+vw2
reduction(p,dom,w);
@expansion{} 2xyz-yzw-2xv+vw
@c end example reduction d2t_singular/ainvar_lib.doc:207
@end smallexample
@c ---end content reduction---

@c ------------------- completeReduction -------------
@node completeReduction, localInvar, reduction, ainvar_lib
@subsubsection completeReduction
@cindex completeReduction
@c ---content completeReduction---
Procedure from library @code{ainvar.lib} (@pxref{ainvar_lib}).

@table @asis
@item @strong{Usage:}
completeReduction(p,I[,q,n]); p poly, I ideal, [q monomial, n int]

@item @strong{Return:}
a polynomial, the SAGBI reduction of the polynomial p with I
via the procedure 'reduction' as long as possible
@*if n=1, a different algorithm is chosen which is sometimes faster
(default: n=0; q and n can be given (or not) in any order)

@item @strong{Note:}
help reduction; shows an explanation of SAGBI reduction

@end table
@strong{Example:}
@smallexample
@c computed example completeReduction d2t_singular/ainvar_lib.doc:241 
LIB "ainvar.lib";
ring q=0,(x,y,z,u,v,w),dp;
poly p=x2yz-x2v;
ideal dom =x-w,u2w+1,yz-v;
completeReduction(p,dom);
@expansion{} 2xyzw-yzw2-2xvw+vw2
completeReduction(p,dom,w);
@expansion{} 0
@c end example completeReduction d2t_singular/ainvar_lib.doc:241
@end smallexample
@c ---end content completeReduction---

@c ------------------- localInvar -------------
@node localInvar, furtherInvar, completeReduction, ainvar_lib
@subsubsection localInvar
@cindex localInvar
@c ---content localInvar---
Procedure from library @code{ainvar.lib} (@pxref{ainvar_lib}).

@table @asis
@item @strong{Usage:}
localInvar(m,p,q,h); m matrix, p,q,h polynomials

@item @strong{Assume:}
m(q) and h are invariant under the vector field m, i.e. m(m(q))=m(h)=0
h must be a ring variable

@item @strong{Return:}
a polynomial, the invariant polynomial of the vector field
@format
         m = m[1,1]*d/dx(1) +...+ m[n,1]*d/dx(n)
@end format
with respect to p,q,h. It is defined as follows: set inv = p if p is
invariant, and else as
@*inv = m(q)^N * sum_i=1..N-1@{ (-1)^i*(1/i!)*m^i(p)*(q/m(q))^i @}
where m^N(p) = 0, m^(N-1)(p) != 0;
@*the result is inv divided by h as much as possible

@end table
@strong{Example:}
@smallexample
@c computed example localInvar d2t_singular/ainvar_lib.doc:281 
LIB "ainvar.lib";
ring q=0,(x,y,z),dp;
matrix m[3][1];
m[2,1]=x;
m[3,1]=y;
poly in=localInvar(m,z,y,x);
in;
@expansion{} -1/2y2+xz
@c end example localInvar d2t_singular/ainvar_lib.doc:281
@end smallexample
@c ---end content localInvar---

@c ------------------- furtherInvar -------------
@node furtherInvar, sortier, localInvar, ainvar_lib
@subsubsection furtherInvar
@cindex furtherInvar
@c ---content furtherInvar---
Procedure from library @code{ainvar.lib} (@pxref{ainvar_lib}).

@table @asis
@item @strong{Usage:}
furtherInvar(m,id,karl,q); m matrix, id,karl ideals, q poly, n int

@item @strong{Assume:}
karl,id,q are invariant under the vector field m,
@*moreover, q must be a variable

@item @strong{Return:}
list of two ideals, the first ideal contains further invariants of
the vector field
@format
         m = sum m[i,1]*d/dx(i) with respect to id,p,q,
@end format
i.e. we compute elements in the (invariant) subring generated by id
which are divisible by q and divide them by q as much as possible
the second ideal contains all invariants given before
if n=1, a different algorithm is chosen which is sometimes faster
(default: n=0)

@end table
@strong{Example:}
@smallexample
@c computed example furtherInvar d2t_singular/ainvar_lib.doc:323 
LIB "ainvar.lib";
ring r=0,(x,y,z,u),dp;
matrix m[4][1];
m[2,1]=x;
m[3,1]=y;
m[4,1]=z;
ideal id=localInvar(m,z,y,x),localInvar(m,u,y,x);
ideal karl=id,x;
list in=furtherInvar(m,id,karl,x);
in;
@expansion{} [1]:
@expansion{}    _[1]=y2z2-8/3xz3-2y3u+6xyzu-3x2u2
@expansion{} [2]:
@expansion{}    _[1]=-1/2y2+xz
@expansion{}    _[2]=1/3y3-xyz+x2u
@expansion{}    _[3]=x
@c end example furtherInvar d2t_singular/ainvar_lib.doc:323
@end smallexample
@c ---end content furtherInvar---

@c ------------------- sortier -------------
@node sortier,, furtherInvar, ainvar_lib
@subsubsection sortier
@cindex sortier
@c ---content sortier---
Procedure from library @code{ainvar.lib} (@pxref{ainvar_lib}).

@table @asis
@item @strong{Usage:}
sortier(id); id ideal/module

@item @strong{Return:}
the same ideal/module but with generators ordered by there
leading term, starting with the smallest

@end table
@strong{Example:}
@smallexample
@c computed example sortier d2t_singular/ainvar_lib.doc:356 
LIB "ainvar.lib";
ring q=0,(x,y,z,u,v,w),dp;
ideal i=w,x,z,y,v;
sortier(i);
@expansion{} _[1]=w
@expansion{} _[2]=v
@expansion{} _[3]=z
@expansion{} _[4]=y
@expansion{} _[5]=x
@c end example sortier d2t_singular/ainvar_lib.doc:356
@end smallexample
@c ---end content sortier---
