@c ---content LibInfo---
@comment This file was generated by doc2tex.pl from d2t_singular/finvar_lib.doc
@comment DO NOT EDIT DIRECTLY, BUT EDIT d2t_singular/finvar_lib.doc INSTEAD
@c library version: (1.32.2.2,2002/08/13)
@c library file: ../Singular/LIB/finvar.lib
@cindex finvar.lib
@cindex finvar_lib
@table @asis
@item @strong{Library:}
finvar.lib
@item @strong{Purpose:}
    Invariant Rings of Finite Groups
@item @strong{Author:}
Agnes E. Heydtmann, email: agnes@@math.uni-sb.de

@item @strong{Overview:}
A library for computing polynomial invariants of finite matrix groups and
generators of related varieties. The algorithms are based on B. Sturmfels,
G. Kemper and W. Decker et al..

@end table

@strong{Main procedures:}
@menu
* invariant_ring:: generators of the invariant ring (i.r.)
* invariant_ring_random:: generators of the i.r., randomized alg.
* primary_invariants:: primary invariants (p.i.)
* primary_invariants_random:: primary invariants, randomized alg.
@end menu
@strong{Auxiliary procedures:}
@menu
* cyclotomic:: cyclotomic polynomial
* group_reynolds:: finite group and Reynolds operator (R.o.)
* molien:: Molien series (M.s.)
* reynolds_molien:: Reynolds operator and Molien series
* partial_molien:: partial expansion of Molien series
* evaluate_reynolds:: image under the Reynolds operator
* invariant_basis:: basis of homogeneous invariants of a degree
* invariant_basis_reynolds:: as invariant_basis(), with R.o.
* primary_char0:: primary invariants in char 0
* primary_charp:: primary invariant in char p
* primary_char0_no_molien:: p.i., char 0, without Molien series
* primary_charp_no_molien:: p.i., char p, without Molien series
* primary_charp_without:: p.i., char p, without R.o. or Molien series
* primary_char0_random:: primary invariants in char 0, randomized
* primary_charp_random:: primary invariants in char p, randomized
* primary_char0_no_molien_random:: p.i., char 0, without M.s., randomized
* primary_charp_no_molien_random:: p.i., char p, without M.s., randomized
* primary_charp_without_random:: p.i., char p, without R.o. or M.s., random.
* power_products:: exponents for power products
* secondary_char0:: secondary (s.i.) invariants in char 0
* secondary_charp:: secondary invariants in char p
* secondary_no_molien:: secondary invariants, without Molien series
* secondary_and_irreducibles_no_molien:: s.i. & irreducible s.i., without M.s.
* secondary_not_cohen_macaulay:: s.i. when invariant ring not Cohen-Macaulay
* orbit_variety:: ideal of the orbit variety
* relative_orbit_variety:: ideal of a relative orbit variety
* image_of_variety:: ideal of the image of a variety
@end menu
@c ---end content LibInfo---

@c ------------------- invariant_ring -------------
@node invariant_ring, invariant_ring_random,, finvar_lib
@subsubsection invariant_ring
@cindex invariant_ring
@c ---content invariant_ring---
Procedure from library @code{finvar.lib} (@pxref{finvar_lib}).

@table @asis
@item @strong{Usage:}
invariant_ring(G1,G2,...[,flags]);
@*G1,G2,...: <matrices> generating a finite matrix group, flags: an
optional <intvec> with three entries: if the first one equals 0, the
program attempts to compute the Molien series and Reynolds operator,
if it equals 1, the program is told that the Molien series should not
be computed, if it equals -1 characteristic 0 is simulated, i.e. the
Molien series is computed as if the base field were characteristic 0
(the user must choose a field of large prime characteristic, e.g.
32003) and if the first one is anything else, it means that the
characteristic of the base field divides the group order (i.e. it will
not even be attempted to compute the Reynolds operator or Molien
series), the second component should give the size of intervals
between canceling common factors in the expansion of Molien series, 0
(the default) means only once after generating all terms, in prime
characteristic also a negative number can be given to indicate that
common factors should always be canceled when the expansion is simple
(the root of the extension field occurs not among the coefficients)

@item @strong{Return:}
primary and secondary invariants (both of type <matrix>) generating
the invariant ring with respect to the matrix group generated by the
matrices in the input and irreducible secondary invariants (type
<matrix>) if the Molien series was available

@item @strong{Display:}
information about the various stages of the program if the third flag
does not equal 0

@item @strong{Theory:}
Bases of homogeneous invariants are generated successively and those
are chosen as primary invariants that lower the dimension of the ideal
generated by the previously found invariants (see "Generating a
Noetherian Normalization of the Invariant Ring of a Finite Group" by
Decker, Heydtmann, Schreyer (1998)). In the
@*non-modular case secondary invariants are calculated by finding a
basis (in terms of monomials) of the basering modulo the primary
invariants, mapping to invariants with the Reynolds operator and using
those or their power products such that they are linearly independent
modulo the primary invariants (see "Some Algorithms in Invariant
Theory of Finite Groups" by Kemper and Steel (1997)). In the modular
case they are generated according to "Generating Invariant Rings of
Finite Groups over Arbitrary Fields" by Kemper (1996).

@end table
@strong{Example:}
@smallexample
@c computed example invariant_ring d2t_singular/finvar_lib.doc:115 
LIB "finvar.lib";
ring R=0,(x,y,z),dp;
matrix A[3][3]=0,1,0,-1,0,0,0,0,-1;
matrix P,S,IS=invariant_ring(A);
print(P);
@expansion{} z2,x2+y2,x2y2
print(S);
@expansion{} 1,xyz,x2z-y2z,x3y-xy3
print(IS);
@expansion{} xyz,x2z-y2z,x3y-xy3
@c end example invariant_ring d2t_singular/finvar_lib.doc:115
@end smallexample
@c ---end content invariant_ring---

@c ------------------- invariant_ring_random -------------
@node invariant_ring_random, primary_invariants, invariant_ring, finvar_lib
@subsubsection invariant_ring_random
@cindex invariant_ring_random
@c ---content invariant_ring_random---
Procedure from library @code{finvar.lib} (@pxref{finvar_lib}).

@table @asis
@item @strong{Usage:}
invariant_ring_random(G1,G2,...,r[,flags]);
@*G1,G2,...: <matrices> generating a finite matrix group, r: an <int>
where -|r| to |r| is the range of coefficients of random
combinations of bases elements that serve as primary invariants,
flags: an optional <intvec> with three entries: if the first equals 0,
the program attempts to compute the Molien series and Reynolds
operator, if it equals 1, the program is told that the Molien series
should not be computed, if it equals -1 characteristic 0 is simulated,
i.e. the Molien series is computed as if the base field were
characteristic 0 (the user must choose a field of large prime
characteristic, e.g. 32003) and if the first one is anything else,
then the characteristic of the base field divides the group order
(i.e. we will not even attempt to compute the Reynolds operator or
Molien series), the second component should give the size of intervals
between canceling common factors in the expansion of the Molien
series, 0 (the default) means only once after generating all terms,
in prime characteristic also a negative number can be given to
indicate that common factors should always be canceled when the
expansion is simple (the root of the extension field does not occur
among the coefficients)

@item @strong{Return:}
primary and secondary invariants (both of type <matrix>) generating
invariant ring with respect to the matrix group generated by the
matrices in the input and irreducible secondary invariants (type
<matrix>) if the Molien series was available

@item @strong{Display:}
information about the various stages of the program if the third flag
does not equal 0

@item @strong{Theory:}
is the same as for invariant_ring except that random combinations of
basis elements are chosen as candidates for primary invariants and
hopefully they lower the dimension of the previously found primary
invariants by the right amount.

@end table
@strong{Example:}
@smallexample
@c computed example invariant_ring_random d2t_singular/finvar_lib.doc:176 
LIB "finvar.lib";
ring R=0,(x,y,z),dp;
matrix A[3][3]=0,1,0,-1,0,0,0,0,-1;
matrix P,S,IS=invariant_ring_random(A,1);
print(P);
@expansion{} z2,x2+y2,x4+y4-z4
print(S);
@expansion{} 1,xyz,x2z-y2z,x3y-xy3
print(IS);
@expansion{} xyz,x2z-y2z,x3y-xy3
@c end example invariant_ring_random d2t_singular/finvar_lib.doc:176
@end smallexample
@c ---end content invariant_ring_random---

@c ------------------- primary_invariants -------------
@node primary_invariants, primary_invariants_random, invariant_ring_random, finvar_lib
@subsubsection primary_invariants
@cindex primary_invariants
@c ---content primary_invariants---
Procedure from library @code{finvar.lib} (@pxref{finvar_lib}).

@table @asis
@item @strong{Usage:}
primary_invariants(G1,G2,...[,flags]);
@*G1,G2,...: <matrices> generating a finite matrix group, flags: an
optional <intvec> with three entries, if the first one equals 0 (also
the default), the program attempts to compute the Molien series and
Reynolds operator, if it equals 1, the program is told that the
Molien series should not be computed, if it equals -1 characteristic 0
is simulated, i.e. the Molien series is computed as if the base field
were characteristic 0 (the user must choose a field of large prime
characteristic, e.g. 32003) and if the first one is anything else, it
means that the characteristic of the base field divides the group
order, the second component should give the size of intervals between
canceling common factors in the expansion of the Molien series, 0 (the
default) means only once after generating all terms, in prime
characteristic also a negative number can be given to indicate that
common factors should always be canceled when the expansion is simple
(the root of the extension field occurs not among the coefficients)

@item @strong{Display:}
information about the various stages of the program if the third
flag does not equal 0

@item @strong{Return:}
primary invariants (type <matrix>) of the invariant ring and if
computable Reynolds operator (type <matrix>) and Molien series (type
<matrix>) or ring name (type string) where the Molien series
can be found in the char p case; if the first flag is 1 and we are in
the non-modular case then an <intvec> is returned giving some of the
degrees where no non-trivial homogeneous invariants can be found

@item @strong{Theory:}
Bases of homogeneous invariants are generated successively and those
are chosen as primary invariants that lower the dimension of the ideal
generated by the previously found invariants (see paper "Generating a
Noetherian Normalization of the Invariant Ring of a Finite Group" by
Decker, Heydtmann, Schreyer (1998)).

@end table
@strong{Example:}
@smallexample
@c computed example primary_invariants d2t_singular/finvar_lib.doc:236 
LIB "finvar.lib";
ring R=0,(x,y,z),dp;
matrix A[3][3]=0,1,0,-1,0,0,0,0,-1;
list L=primary_invariants(A);
print(L[1]);
@expansion{} z2,x2+y2,x2y2
@c end example primary_invariants d2t_singular/finvar_lib.doc:236
@end smallexample
@c ---end content primary_invariants---

@c ------------------- primary_invariants_random -------------
@node primary_invariants_random, cyclotomic, primary_invariants, finvar_lib
@subsubsection primary_invariants_random
@cindex primary_invariants_random
@c ---content primary_invariants_random---
Procedure from library @code{finvar.lib} (@pxref{finvar_lib}).

@table @asis
@item @strong{Usage:}
primary_invariants_random(G1,G2,...,r[,flags]);
@*G1,G2,...: <matrices> generating a finite matrix group, r: an <int>
where -|r| to |r| is the range of coefficients of the random
combinations of bases elements, flags: an optional <intvec> with three
entries, if the first one equals 0 (also the default), the program
attempts to compute the Molien series and Reynolds operator, if it
equals 1, the program is told that the Molien series should not be
computed, if it equals -1 characteristic 0 is simulated, i.e. the
Molien series is computed as if the base field were characteristic 0
(the user must choose a field of large prime characteristic, e.g.
32003) and if the first one is anything else, it means that the
characteristic of the base field divides the group order, the second
component should give the size of intervals between canceling common
factors in the expansion of the Molien series, 0 (the default) means
only once after generating all terms, in prime characteristic also a
negative number can be given to indicate that common factors should
always be canceled when the expansion is simple (the root of the
extension field does not occur among the coefficients)

@item @strong{Display:}
information about the various stages of the program if the third
flag does not equal 0

@item @strong{Return:}
primary invariants (type <matrix>) of the invariant ring and if
computable Reynolds operator (type <matrix>) and Molien series (type
<matrix>), if the first flag is 1 and we are in the non-modular case
then an <intvec> is returned giving some of the degrees where no
non-trivial homogeneous invariants can be found

@item @strong{Theory:}
Bases of homogeneous invariants are generated successively and random
linear combinations are chosen as primary invariants that lower the
dimension of the ideal generated by the previously found invariants
(see "Generating a Noetherian Normalization of the Invariant Ring of
a Finite Group" by Decker, Heydtmann, Schreyer (1998)).

@end table
@strong{Example:}
@smallexample
@c computed example primary_invariants_random d2t_singular/finvar_lib.doc:295 
LIB "finvar.lib";
ring R=0,(x,y,z),dp;
matrix A[3][3]=0,1,0,-1,0,0,0,0,-1;
list L=primary_invariants_random(A,1);
print(L[1]);
@expansion{} z2,x2+y2,x4+y4-z4
@c end example primary_invariants_random d2t_singular/finvar_lib.doc:295
@end smallexample
@c ---end content primary_invariants_random---

@c ------------------- cyclotomic -------------
@node cyclotomic, group_reynolds, primary_invariants_random, finvar_lib
@subsubsection cyclotomic
@cindex cyclotomic
@c ---content cyclotomic---
Procedure from library @code{finvar.lib} (@pxref{finvar_lib}).

@table @asis
@item @strong{Usage:}
cyclotomic(i); i integer > 0

@item @strong{Returns:}
the i-th cyclotomic polynomial (type <poly>) as one in the first ring
variable

@item @strong{Theory:}
x^i-1 is divided by the j-th cyclotomic polynomial where j takes on
the value of proper divisors of i

@end table
@strong{Example:}
@smallexample
@c computed example cyclotomic d2t_singular/finvar_lib.doc:327 
LIB "finvar.lib";
ring R=0,(x,y,z),dp;
print(cyclotomic(25));
@expansion{} x20+x15+x10+x5+1
@c end example cyclotomic d2t_singular/finvar_lib.doc:327
@end smallexample
@c ---end content cyclotomic---

@c ------------------- group_reynolds -------------
@node group_reynolds, molien, cyclotomic, finvar_lib
@subsubsection group_reynolds
@cindex group_reynolds
@c ---content group_reynolds---
Procedure from library @code{finvar.lib} (@pxref{finvar_lib}).

@table @asis
@item @strong{Usage:}
group_reynolds(G1,G2,...[,v]);
@*G1,G2,...: nxn <matrices> generating a finite matrix group, v: an
optional <int>

@item @strong{Assume:}
n is the number of variables of the basering, g the number of group
elements

@item @strong{Return:}
a <list>, the first list element will be a gxn <matrix> representing
the Reynolds operator if we are in the non-modular case; if the
characteristic is >0, minpoly==0 and the finite group non-cyclic the
second list element is an <int> giving the lowest common multiple of
the matrix group elements' order (used in molien); in general all
other list elements are nxn <matrices> listing all elements of the
finite group

@item @strong{Display:}
information if v does not equal 0

@item @strong{Theory:}
The entire matrix group is generated by getting all left products of
generators with the new elements from the last run through the loop
(or the generators themselves during the first run). All the ones that
have been generated before are thrown out and the program terminates
when no new elements found in one run. Additionally each time a new
group element is found the corresponding ring mapping of which the
Reynolds operator is made up is generated. They are stored in the rows
of the first return value.

@end table
@strong{Example:}
@smallexample
@c computed example group_reynolds d2t_singular/finvar_lib.doc:377 
LIB "finvar.lib";
ring R=0,(x,y,z),dp;
matrix A[3][3]=0,1,0,-1,0,0,0,0,-1;
list L=group_reynolds(A);
print(L[1]);
@expansion{} y, -x,-z,
@expansion{} -x,-y,z, 
@expansion{} -y,x, -z,
@expansion{} x, y, z  
print(L[2..size(L)]);
@expansion{} 0, 1,0,
@expansion{} -1,0,0,
@expansion{} 0, 0,-1
@expansion{} -1,0, 0,
@expansion{} 0, -1,0,
@expansion{} 0, 0, 1 
@expansion{} 0,-1,0,
@expansion{} 1,0, 0,
@expansion{} 0,0, -1
@expansion{} 1,0,0,
@expansion{} 0,1,0,
@expansion{} 0,0,1 
@c end example group_reynolds d2t_singular/finvar_lib.doc:377
@end smallexample
@c ---end content group_reynolds---

@c ------------------- molien -------------
@node molien, reynolds_molien, group_reynolds, finvar_lib
@subsubsection molien
@cindex molien
@c ---content molien---
Procedure from library @code{finvar.lib} (@pxref{finvar_lib}).

@table @asis
@item @strong{Usage:}
molien(G1,G2,...[,ringname,lcm,flags]);
@*G1,G2,...: nxn <matrices>, all elements of a finite matrix group,
ringname: a <string> giving a name for a new ring of characteristic 0
for the Molien series in case of prime characteristic, lcm: an <int>
giving the lowest common multiple of the elements' orders in case of
prime characteristic, minpoly==0 and a non-cyclic group, flags: an
optional <intvec> with three components: if the first element is not
equal to 0 characteristic 0 is simulated, i.e. the Molien series is
computed as if the base field were characteristic 0 (the user must
choose a field of large prime characteristic, e.g. 32003), the second
component should give the size of intervals between canceling common
factors in the expansion of the Molien series, 0 (the default) means
only once after generating all terms, in prime characteristic also a
negative number can be given to indicate that common factors should
always be canceled when the expansion is simple (the root of the
extension field does not occur among the coefficients)

@item @strong{Assume:}
n is the number of variables of the basering, G1,G2... are the group
elements generated by group_reynolds(), lcm is the second return value
of group_reynolds()

@item @strong{Return:}
in case of characteristic 0 a 1x2 <matrix> giving enumerator and
denominator of Molien series; in case of prime characteristic a ring
with the name `ringname` of characteristic 0 is created where the same
Molien series (named M) is stored

@item @strong{Display:}
information if the third component of flags does not equal 0

@item @strong{Theory:}
In characteristic 0 the terms 1/det(1-xE) for all group elements of
the Molien series are computed in a straight forward way. In prime
characteristic a Brauer lift is involved. The returned matrix gives
enumerator and denominator of the expanded version where common
factors have been canceled.

@end table
@strong{Example:}
@smallexample
@c computed example molien d2t_singular/finvar_lib.doc:438 
LIB "finvar.lib";
"         note the case of prime characteristic"; 
@expansion{}          note the case of prime characteristic
ring R=0,(x,y,z),dp;
matrix A[3][3]=0,1,0,-1,0,0,0,0,-1;
list L=group_reynolds(A);
matrix M=molien(L[2..size(L)]);
print(M);
@expansion{} x3+x2-x+1,-x7+x6+x5-x4+x3-x2-x+1
ring S=3,(x,y,z),dp;
string newring="alksdfjlaskdjf";
matrix A[3][3]=0,1,0,-1,0,0,0,0,-1;
list L=group_reynolds(A);
molien(L[2..size(L)],newring);
setring alksdfjlaskdjf;
print(M);
@expansion{} x3+x2-x+1,-x7+x6+x5-x4+x3-x2-x+1
setring S;
kill alksdfjlaskdjf;
@c end example molien d2t_singular/finvar_lib.doc:438
@end smallexample
@c ---end content molien---

@c ------------------- reynolds_molien -------------
@node reynolds_molien, partial_molien, molien, finvar_lib
@subsubsection reynolds_molien
@cindex reynolds_molien
@c ---content reynolds_molien---
Procedure from library @code{finvar.lib} (@pxref{finvar_lib}).

@table @asis
@item @strong{Usage:}
reynolds_molien(G1,G2,...[,ringname,flags]);
@*G1,G2,...: nxn <matrices> generating a finite matrix group, ringname:
a <string> giving a name for a new ring of characteristic 0 for the
Molien series in case of prime characteristic, flags: an optional
<intvec> with three components: if the first element is not equal to 0
characteristic 0 is simulated, i.e. the Molien series is computed as
if the base field were characteristic 0 (the user must choose a field
of large prime characteristic, e.g. 32003) the second component should
give the size of intervals between canceling common factors in the
expansion of the Molien series, 0 (the default) means only once after
generating all terms, in prime characteristic also a negative number
can be given to indicate that common factors should always be canceled
when the expansion is simple (the root of the extension field does not
occur among the coefficients)

@item @strong{Assume:}
n is the number of variables of the basering, G1,G2... are the group
elements generated by group_reynolds(), g is the size of the group

@item @strong{Return:}
a gxn <matrix> representing the Reynolds operator is the first return
value and in case of characteristic 0 a 1x2 <matrix> giving enumerator
and denominator of Molien series is the second one; in case of prime
characteristic a ring with the name `ringname` of characteristic 0 is
created where the same Molien series (named M) is stored

@item @strong{Display:}
information if the third component of flags does not equal 0

@item @strong{Theory:}
The entire matrix group is generated by getting all left products of
the generators with new elements from the last run through the loop
(or the generators themselves during the first run). All the ones that
have been generated before are thrown out and the program terminates
when are no new elements found in one run. Additionally each time a
new group element is found the corresponding ring mapping of which the
Reynolds operator is made up is generated. They are stored in the rows
of the first return value. In characteristic 0 the terms 1/det(1-xE)
is computed whenever a new element E is found. In prime characteristic
a Brauer lift is involved and the terms are only computed after the
entire matrix group is generated (to avoid the modular case). The
returned matrix gives enumerator and denominator of the expanded
version where common factors have been canceled.

@end table
@strong{Example:}
@smallexample
@c computed example reynolds_molien d2t_singular/finvar_lib.doc:515 
LIB "finvar.lib";
"         note the case of prime characteristic"; 
@expansion{}          note the case of prime characteristic
ring R=0,(x,y,z),dp;
matrix A[3][3]=0,1,0,-1,0,0,0,0,-1;
matrix REY,M=reynolds_molien(A);
print(REY);
@expansion{} y, -x,-z,
@expansion{} -x,-y,z, 
@expansion{} -y,x, -z,
@expansion{} x, y, z  
print(M);
@expansion{} x3+x2-x+1,-x7+x6+x5-x4+x3-x2-x+1
ring S=3,(x,y,z),dp;
string newring="Qadjoint";
matrix A[3][3]=0,1,0,-1,0,0,0,0,-1;
matrix REY=reynolds_molien(A,newring);
print(REY);
@expansion{} y, -x,-z,
@expansion{} -x,-y,z, 
@expansion{} -y,x, -z,
@expansion{} x, y, z  
setring Qadjoint;
print(M);
@expansion{} x3+x2-x+1,-x7+x6+x5-x4+x3-x2-x+1
setring S;
kill Qadjoint;
@c end example reynolds_molien d2t_singular/finvar_lib.doc:515
@end smallexample
@c ---end content reynolds_molien---

@c ------------------- partial_molien -------------
@node partial_molien, evaluate_reynolds, reynolds_molien, finvar_lib
@subsubsection partial_molien
@cindex partial_molien
@c ---content partial_molien---
Procedure from library @code{finvar.lib} (@pxref{finvar_lib}).

@table @asis
@item @strong{Usage:}
partial_molien(M,n[,p]);
@*M: a 1x2 <matrix>, n: an <int> indicating number of terms in the
expansion, p: an optional <poly>

@item @strong{Assume:}
M is the return value of molien or the second return value of
reynolds_molien, p ought to be the second return value of a previous
run of partial_molien and avoids recalculating known terms

@item @strong{Return:}
n terms (type <poly>) of the partial expansion of the Molien series
(first n if there is no third parameter given, otherwise the next n
terms depending on a previous calculation) and an intermediate result
(type <poly>) of the calculation to be used as third parameter in a
next run of partial_molien

@item @strong{Theory:}
The following calculation is implemented:
@format
(1+a1x+a2x^2+...+anx^n)/(1+b1x+b2x^2+...+bmx^m)=(1+(a1-b1)x+...
(1+b1x+b2x^2+...+bmx^m)
-----------------------
   (a1-b1)x+(a2-b2)x^2+...
   (a1-b1)x+b1(a1-b1)x^2+...
@end format

@end table
@strong{Example:}
@smallexample
@c computed example partial_molien d2t_singular/finvar_lib.doc:574 
LIB "finvar.lib";
ring R=0,(x,y,z),dp;
matrix A[3][3]=0,1,0,-1,0,0,0,0,-1;
matrix REY,M=reynolds_molien(A);
poly p(1..2);
p(1..2)=partial_molien(M,5);
p(1);
@expansion{} 4x5+5x4+2x3+2x2+1
p(1..2)=partial_molien(M,5,p(2));
p(1);
@expansion{} 18x10+12x9+13x8+8x7+8x6
@c end example partial_molien d2t_singular/finvar_lib.doc:574
@end smallexample
@c ---end content partial_molien---

@c ------------------- evaluate_reynolds -------------
@node evaluate_reynolds, invariant_basis, partial_molien, finvar_lib
@subsubsection evaluate_reynolds
@cindex evaluate_reynolds
@c ---content evaluate_reynolds---
Procedure from library @code{finvar.lib} (@pxref{finvar_lib}).

@table @asis
@item @strong{Usage:}
evaluate_reynolds(REY,I);
@*REY: a <matrix> representing the Reynolds operator, I: an arbitrary
<ideal>

@item @strong{Assume:}
REY is the first return value of group_reynolds() or reynolds_molien()

@item @strong{Returns:}
image of the polynomials defining I under the Reynolds operator
(type <ideal>)

@item @strong{Note:}
the characteristic of the coefficient field of the polynomial ring
should not divide the order of the finite matrix group

@item @strong{Theory:}
REY has been constructed in such a way that each row serves as a ring
mapping of which the Reynolds operator is made up.

@end table
@strong{Example:}
@smallexample
@c computed example evaluate_reynolds d2t_singular/finvar_lib.doc:619 
LIB "finvar.lib";
ring R=0,(x,y,z),dp;
matrix A[3][3]=0,1,0,-1,0,0,0,0,-1;
list L=group_reynolds(A);
ideal I=x2,y2,z2;
print(evaluate_reynolds(L[1],I));
@expansion{} 1/2x2+1/2y2,
@expansion{} 1/2x2+1/2y2,
@expansion{} z2
@c end example evaluate_reynolds d2t_singular/finvar_lib.doc:619
@end smallexample
@c ---end content evaluate_reynolds---

@c ------------------- invariant_basis -------------
@node invariant_basis, invariant_basis_reynolds, evaluate_reynolds, finvar_lib
@subsubsection invariant_basis
@cindex invariant_basis
@c ---content invariant_basis---
Procedure from library @code{finvar.lib} (@pxref{finvar_lib}).

@table @asis
@item @strong{Usage:}
invariant_basis(g,G1,G2,...);
@*g: an <int> indicating of which degree (>0) the homogeneous basis
should be, G1,G2,...: <matrices> generating a finite matrix group

@item @strong{Returns:}
the basis (type <ideal>) of the space of invariants of degree g

@item @strong{Theory:}
A general polynomial of degree g is generated and the generators of
the matrix group applied. The difference ought to be 0 and this way a
system of linear equations is created. It is solved by computing
syzygies.

@end table
@strong{Example:}
@smallexample
@c computed example invariant_basis d2t_singular/finvar_lib.doc:655 
LIB "finvar.lib";
ring R=0,(x,y,z),dp;
matrix A[3][3]=0,1,0,-1,0,0,0,0,-1;
print(invariant_basis(2,A));
@expansion{} x2+y2,
@expansion{} z2
@c end example invariant_basis d2t_singular/finvar_lib.doc:655
@end smallexample
@c ---end content invariant_basis---

@c ------------------- invariant_basis_reynolds -------------
@node invariant_basis_reynolds, primary_char0, invariant_basis, finvar_lib
@subsubsection invariant_basis_reynolds
@cindex invariant_basis_reynolds
@c ---content invariant_basis_reynolds---
Procedure from library @code{finvar.lib} (@pxref{finvar_lib}).

@table @asis
@item @strong{Usage:}
invariant_basis_reynolds(REY,d[,flags]);
@*REY: a <matrix> representing the Reynolds operator, d: an <int>
indicating of which degree (>0) the homogeneous basis should be, flags:
an optional <intvec> with two entries: its first component gives the
dimension of the space (default <0 meaning unknown) and its second
component is used as the number of polynomials that should be mapped
to invariants during one call of evaluate_reynolds if the dimension of
the space is unknown or the number such that number x dimension
polynomials are mapped to invariants during one call of
evaluate_reynolds

@item @strong{Assume:}
REY is the first return value of group_reynolds() or reynolds_molien()
and flags[1] given by partial_molien

@item @strong{Return:}
the basis (type <ideal>) of the space of invariants of degree d

@item @strong{Theory:}
Monomials of degree d are mapped to invariants with the Reynolds
operator. A linearly independent set is generated with the help of
minbase.

@end table
@strong{Example:}
@smallexample
@c computed example invariant_basis_reynolds d2t_singular/finvar_lib.doc:699 
LIB "finvar.lib";
ring R=0,(x,y,z),dp;
matrix A[3][3]=0,1,0,-1,0,0,0,0,-1;
intvec flags=0,1,0;
matrix REY,M=reynolds_molien(A,flags);
flags=8,6;
print(invariant_basis_reynolds(REY,6,flags));
@expansion{} z6,
@expansion{} x2z4+y2z4,
@expansion{} x2y2z2,
@expansion{} x3yz2-xy3z2,
@expansion{} x4z2+y4z2,
@expansion{} x4y2+x2y4,
@expansion{} x5y-xy5,
@expansion{} x6+y6
@c end example invariant_basis_reynolds d2t_singular/finvar_lib.doc:699
@end smallexample
@c ---end content invariant_basis_reynolds---

@c ------------------- primary_char0 -------------
@node primary_char0, primary_charp, invariant_basis_reynolds, finvar_lib
@subsubsection primary_char0
@cindex primary_char0
@c ---content primary_char0---
Procedure from library @code{finvar.lib} (@pxref{finvar_lib}).

@table @asis
@item @strong{Usage:}
primary_char0(REY,M[,v]);
@*REY: a <matrix> representing the Reynolds operator, M: a 1x2 <matrix>
representing the Molien series, v: an optional <int>

@item @strong{Assume:}
REY is the first return value of group_reynolds or reynolds_molien and
M the one of molien or the second one of reynolds_molien

@item @strong{Display:}
information about the various stages of the program if v does not
equal 0

@item @strong{Return:}
primary invariants (type <matrix>) of the invariant ring

@item @strong{Theory:}
Bases of homogeneous invariants are generated successively and those
are chosen as primary invariants that lower the dimension of the ideal
generated by the previously found invariants (see paper "Generating a
Noetherian Normalization of the Invariant Ring of a Finite Group" by
Decker, Heydtmann, Schreyer (1998)).

@end table
@strong{Example:}
@smallexample
@c computed example primary_char0 d2t_singular/finvar_lib.doc:745 
LIB "finvar.lib";
ring R=0,(x,y,z),dp;
matrix A[3][3]=0,1,0,-1,0,0,0,0,-1;
matrix REY,M=reynolds_molien(A);
matrix P=primary_char0(REY,M);
print(P);
@expansion{} z2,x2+y2,x2y2
@c end example primary_char0 d2t_singular/finvar_lib.doc:745
@end smallexample
@c ---end content primary_char0---

@c ------------------- primary_charp -------------
@node primary_charp, primary_char0_no_molien, primary_char0, finvar_lib
@subsubsection primary_charp
@cindex primary_charp
@c ---content primary_charp---
Procedure from library @code{finvar.lib} (@pxref{finvar_lib}).

@table @asis
@item @strong{Usage:}
primary_charp(REY,ringname[,v]);
@*REY: a <matrix> representing the Reynolds operator, ringname: a
<string> giving the name of a ring where the Molien series is stored,
v: an optional <int>

@item @strong{Assume:}
REY is the first return value of group_reynolds or reynolds_molien and
ringname gives the name of a ring of characteristic 0 that has been
created by molien or reynolds_molien

@item @strong{Display:}
information about the various stages of the program if v does not
equal 0

@item @strong{Return:}
primary invariants (type <matrix>) of the invariant ring

@item @strong{Theory:}
Bases of homogeneous invariants are generated successively and those
are chosen as primary invariants that lower the dimension of the ideal
generated by the previously found invariants (see paper "Generating a
Noetherian Normalization of the Invariant Ring of a Finite Group" by
Decker, Heydtmann, Schreyer (1998)).

@end table
@strong{Example:}
@smallexample
@c computed example primary_charp d2t_singular/finvar_lib.doc:792 
LIB "finvar.lib";
ring R=3,(x,y,z),dp;
matrix A[3][3]=0,1,0,-1,0,0,0,0,-1;
list L=group_reynolds(A);
string newring="alskdfj";
molien(L[2..size(L)],newring);
matrix P=primary_charp(L[1],newring);
if(system("with","Namespaces")) @{ kill Top::`newring`; @}
kill `newring`;
print(P);
@expansion{} z2,x2+y2,x2y2
@c end example primary_charp d2t_singular/finvar_lib.doc:792
@end smallexample
@c ---end content primary_charp---

@c ------------------- primary_char0_no_molien -------------
@node primary_char0_no_molien, primary_charp_no_molien, primary_charp, finvar_lib
@subsubsection primary_char0_no_molien
@cindex primary_char0_no_molien
@c ---content primary_char0_no_molien---
Procedure from library @code{finvar.lib} (@pxref{finvar_lib}).

@table @asis
@item @strong{Usage:}
primary_char0_no_molien(REY[,v]);
@*REY: a <matrix> representing the Reynolds operator, v: an optional
<int>

@item @strong{Assume:}
REY is the first return value of group_reynolds or reynolds_molien

@item @strong{Display:}
information about the various stages of the program if v does not
equal 0

@item @strong{Return:}
primary invariants (type <matrix>) of the invariant ring and an
<intvec> listing some of the degrees where no non-trivial homogeneous
invariants are to be found

@item @strong{Theory:}
Bases of homogeneous invariants are generated successively and those
are chosen as primary invariants that lower the dimension of the ideal
generated by the previously found invariants (see paper "Generating a
Noetherian Normalization of the Invariant Ring of a Finite Group" by
Decker, Heydtmann, Schreyer (1998)).

@end table
@strong{Example:}
@smallexample
@c computed example primary_char0_no_molien d2t_singular/finvar_lib.doc:842 
LIB "finvar.lib";
ring R=0,(x,y,z),dp;
matrix A[3][3]=0,1,0,-1,0,0,0,0,-1;
list L=group_reynolds(A);
list l=primary_char0_no_molien(L[1]);
print(l[1]);
@expansion{} z2,x2+y2,x2y2
@c end example primary_char0_no_molien d2t_singular/finvar_lib.doc:842
@end smallexample
@c ---end content primary_char0_no_molien---

@c ------------------- primary_charp_no_molien -------------
@node primary_charp_no_molien, primary_charp_without, primary_char0_no_molien, finvar_lib
@subsubsection primary_charp_no_molien
@cindex primary_charp_no_molien
@c ---content primary_charp_no_molien---
Procedure from library @code{finvar.lib} (@pxref{finvar_lib}).

@table @asis
@item @strong{Usage:}
primary_charp_no_molien(REY[,v]);
@*REY: a <matrix> representing the Reynolds operator, v: an optional
<int>

@item @strong{Assume:}
REY is the first return value of group_reynolds or reynolds_molien

@item @strong{Display:}
information about the various stages of the program if v does not
equal 0

@item @strong{Return:}
primary invariants (type <matrix>) of the invariant ring and an
<intvec> listing some of the degrees where no non-trivial homogeneous
invariants are to be found

@item @strong{Theory:}
Bases of homogeneous invariants are generated successively and those
are chosen as primary invariants that lower the dimension of the ideal
generated by the previously found invariants (see paper "Generating a
Noetherian Normalization of the Invariant Ring of a Finite Group" by
Decker, Heydtmann, Schreyer (1998)).

@end table
@strong{Example:}
@smallexample
@c computed example primary_charp_no_molien d2t_singular/finvar_lib.doc:888 
LIB "finvar.lib";
ring R=3,(x,y,z),dp;
matrix A[3][3]=0,1,0,-1,0,0,0,0,-1;
list L=group_reynolds(A);
list l=primary_charp_no_molien(L[1]);
print(l[1]);
@expansion{} z2,x2+y2,x2y2
@c end example primary_charp_no_molien d2t_singular/finvar_lib.doc:888
@end smallexample
@c ---end content primary_charp_no_molien---

@c ------------------- primary_charp_without -------------
@node primary_charp_without, primary_char0_random, primary_charp_no_molien, finvar_lib
@subsubsection primary_charp_without
@cindex primary_charp_without
@c ---content primary_charp_without---
Procedure from library @code{finvar.lib} (@pxref{finvar_lib}).

@table @asis
@item @strong{Usage:}
primary_charp_without(G1,G2,...[,v]);
@*G1,G2,...: <matrices> generating a finite matrix group, v: an optional
<int>

@item @strong{Display:}
information about the various stages of the program if v does not
equal 0

@item @strong{Return:}
primary invariants (type <matrix>) of the invariant ring

@item @strong{Theory:}
Bases of homogeneous invariants are generated successively and those
are chosen as primary invariants that lower the dimension of the ideal
generated by the previously found invariants (see paper "Generating a
Noetherian Normalization of the Invariant Ring of a Finite Group" by
Decker, Heydtmann, Schreyer (1998)). No Reynolds
@*operator or Molien series is used.

@end table
@strong{Example:}
@smallexample
@c computed example primary_charp_without d2t_singular/finvar_lib.doc:930 
LIB "finvar.lib";
ring R=2,(x,y,z),dp;
matrix A[3][3]=0,1,0,-1,0,0,0,0,-1;
matrix P=primary_charp_without(A);
print(P);
@expansion{} x+y,z,xy
@c end example primary_charp_without d2t_singular/finvar_lib.doc:930
@end smallexample
@c ---end content primary_charp_without---

@c ------------------- primary_char0_random -------------
@node primary_char0_random, primary_charp_random, primary_charp_without, finvar_lib
@subsubsection primary_char0_random
@cindex primary_char0_random
@c ---content primary_char0_random---
Procedure from library @code{finvar.lib} (@pxref{finvar_lib}).

@table @asis
@item @strong{Usage:}
primary_char0_random(REY,M,r[,v]);
@*REY: a <matrix> representing the Reynolds operator, M: a 1x2 <matrix>
representing the Molien series, r: an <int> where -|r| to |r| is the
range of coefficients of the random combinations of bases elements,
v: an optional <int>

@item @strong{Assume:}
REY is the first return value of group_reynolds or reynolds_molien and
M the one of molien or the second one of reynolds_molien

@item @strong{Display:}
information about the various stages of the program if v does not
equal 0

@item @strong{Return:}
primary invariants (type <matrix>) of the invariant ring

@item @strong{Theory:}
Bases of homogeneous invariants are generated successively and random
linear combinations are chosen as primary invariants that lower the
dimension of the ideal generated by the previously found invariants
(see "Generating a Noetherian Normalization of the Invariant Ring of
a Finite Group" by Decker, Heydtmann, Schreyer (1998)).

@end table
@strong{Example:}
@smallexample
@c computed example primary_char0_random d2t_singular/finvar_lib.doc:976 
LIB "finvar.lib";
ring R=0,(x,y,z),dp;
matrix A[3][3]=0,1,0,-1,0,0,0,0,-1;
matrix REY,M=reynolds_molien(A);
matrix P=primary_char0_random(REY,M,1);
print(P);
@expansion{} z2,x2+y2,x4+y4-z4
@c end example primary_char0_random d2t_singular/finvar_lib.doc:976
@end smallexample
@c ---end content primary_char0_random---

@c ------------------- primary_charp_random -------------
@node primary_charp_random, primary_char0_no_molien_random, primary_char0_random, finvar_lib
@subsubsection primary_charp_random
@cindex primary_charp_random
@c ---content primary_charp_random---
Procedure from library @code{finvar.lib} (@pxref{finvar_lib}).

@table @asis
@item @strong{Usage:}
primary_charp_random(REY,ringname,r[,v]);
@*REY: a <matrix> representing the Reynolds operator, ringname: a
<string> giving the name of a ring where the Molien series is stored,
r: an <int> where -|r| to |r| is the range of coefficients of the
random combinations of bases elements, v: an optional <int>

@item @strong{Assume:}
REY is the first return value of group_reynolds or reynolds_molien and
ringname gives the name of a ring of characteristic 0 that has been
created by molien or reynolds_molien

@item @strong{Display:}
information about the various stages of the program if v does not
equal 0

@item @strong{Return:}
primary invariants (type <matrix>) of the invariant ring

@item @strong{Theory:}
Bases of homogeneous invariants are generated successively and random
linear combinations are chosen as primary invariants that lower the
dimension of the ideal generated by the previously found invariants
(see "Generating a Noetherian Normalization of the Invariant Ring of
a Finite Group" by Decker, Heydtmann, Schreyer (1998)).

@end table
@strong{Example:}
@smallexample
@c computed example primary_charp_random d2t_singular/finvar_lib.doc:1024 
LIB "finvar.lib";
ring R=3,(x,y,z),dp;
matrix A[3][3]=0,1,0,-1,0,0,0,0,-1;
list L=group_reynolds(A);
string newring="alskdfj";
molien(L[2..size(L)],newring);
matrix P=primary_charp_random(L[1],newring,1);
if(system("with","Namespaces")) @{ kill Top::`newring`; @}
kill `newring`;
print(P);
@expansion{} z2,x2+y2,x4+y4-z4
@c end example primary_charp_random d2t_singular/finvar_lib.doc:1024
@end smallexample
@c ---end content primary_charp_random---

@c ------------------- primary_char0_no_molien_random -------------
@node primary_char0_no_molien_random, primary_charp_no_molien_random, primary_charp_random, finvar_lib
@subsubsection primary_char0_no_molien_random
@cindex primary_char0_no_molien_random
@c ---content primary_char0_no_molien_random---
Procedure from library @code{finvar.lib} (@pxref{finvar_lib}).

@table @asis
@item @strong{Usage:}
primary_char0_no_molien_random(REY,r[,v]);
@*REY: a <matrix> representing the Reynolds operator, r: an <int> where
-|r| to |r| is the range of coefficients of the random combinations of
bases elements, v: an optional <int>

@item @strong{Assume:}
REY is the first return value of group_reynolds or reynolds_molien

@item @strong{Display:}
information about the various stages of the program if v does not
equal 0

@item @strong{Return:}
primary invariants (type <matrix>) of the invariant ring and an
<intvec> listing some of the degrees where no non-trivial homogeneous
invariants are to be found

@item @strong{Theory:}
Bases of homogeneous invariants are generated successively and random
linear combinations are chosen as primary invariants that lower the
dimension of the ideal generated by the previously found invariants
(see "Generating a Noetherian Normalization of the Invariant Ring of
a Finite Group" by Decker, Heydtmann, Schreyer (1998)).

@end table
@strong{Example:}
@smallexample
@c computed example primary_char0_no_molien_random d2t_singular/finvar_lib.doc:1075 
LIB "finvar.lib";
ring R=0,(x,y,z),dp;
matrix A[3][3]=0,1,0,-1,0,0,0,0,-1;
list L=group_reynolds(A);
list l=primary_char0_no_molien_random(L[1],1);
print(l[1]);
@expansion{} z2,x2+y2,x4+y4-z4
@c end example primary_char0_no_molien_random d2t_singular/finvar_lib.doc:1075
@end smallexample
@c ---end content primary_char0_no_molien_random---

@c ------------------- primary_charp_no_molien_random -------------
@node primary_charp_no_molien_random, primary_charp_without_random, primary_char0_no_molien_random, finvar_lib
@subsubsection primary_charp_no_molien_random
@cindex primary_charp_no_molien_random
@c ---content primary_charp_no_molien_random---
Procedure from library @code{finvar.lib} (@pxref{finvar_lib}).

@table @asis
@item @strong{Usage:}
primary_charp_no_molien_random(REY,r[,v]);
@*REY: a <matrix> representing the Reynolds operator, r: an <int> where
-|r| to |r| is the range of coefficients of the random combinations of
bases elements, v: an optional <int>

@item @strong{Assume:}
REY is the first return value of group_reynolds or reynolds_molien

@item @strong{Display:}
information about the various stages of the program if v does not
equal 0

@item @strong{Return:}
primary invariants (type <matrix>) of the invariant ring and an
<intvec> listing some of the degrees where no non-trivial homogeneous
invariants are to be found

@item @strong{Theory:}
Bases of homogeneous invariants are generated successively and random
linear combinations are chosen as primary invariants that lower the
dimension of the ideal generated by the previously found invariants
(see "Generating a Noetherian Normalization of the Invariant Ring of
a Finite Group" by Decker, Heydtmann, Schreyer (1998)).

@end table
@strong{Example:}
@smallexample
@c computed example primary_charp_no_molien_random d2t_singular/finvar_lib.doc:1122 
LIB "finvar.lib";
ring R=3,(x,y,z),dp;
matrix A[3][3]=0,1,0,-1,0,0,0,0,-1;
list L=group_reynolds(A);
list l=primary_charp_no_molien_random(L[1],1);
print(l[1]);
@expansion{} z2,x2+y2,x4+y4-z4
@c end example primary_charp_no_molien_random d2t_singular/finvar_lib.doc:1122
@end smallexample
@c ---end content primary_charp_no_molien_random---

@c ------------------- primary_charp_without_random -------------
@node primary_charp_without_random, power_products, primary_charp_no_molien_random, finvar_lib
@subsubsection primary_charp_without_random
@cindex primary_charp_without_random
@c ---content primary_charp_without_random---
Procedure from library @code{finvar.lib} (@pxref{finvar_lib}).

@table @asis
@item @strong{Usage:}
primary_charp_without_random(G1,G2,...,r[,v]);
@*G1,G2,...: <matrices> generating a finite matrix group, r: an <int>
where -|r| to |r| is the range of coefficients of the random
combinations of bases elements, v: an optional <int>

@item @strong{Display:}
information about the various stages of the program if v does not
equal 0

@item @strong{Return:}
primary invariants (type <matrix>) of the invariant ring

@item @strong{Theory:}
Bases of homogeneous invariants are generated successively and random
linear combinations are chosen as primary invariants that lower the
dimension of the ideal generated by the previously found invariants
(see "Generating a Noetherian Normalization of the Invariant Ring of
a Finite Group" by Decker, Heydtmann, Schreyer (1998)). No Reynolds
operator or Molien series is used.

@end table
@strong{Example:}
@smallexample
@c computed example primary_charp_without_random d2t_singular/finvar_lib.doc:1165 
LIB "finvar.lib";
ring R=2,(x,y,z),dp;
matrix A[3][3]=0,1,0,-1,0,0,0,0,-1;
matrix P=primary_charp_without_random(A,1);
print(P);
@expansion{} x+y,z,xy
@c end example primary_charp_without_random d2t_singular/finvar_lib.doc:1165
@end smallexample
@c ---end content primary_charp_without_random---

@c ------------------- power_products -------------
@node power_products, secondary_char0, primary_charp_without_random, finvar_lib
@subsubsection power_products
@cindex power_products
@c ---content power_products---
Procedure from library @code{finvar.lib} (@pxref{finvar_lib}).

@table @asis
@item @strong{Usage:}
power_products(dv,d);
@*dv: an <intvec> giving the degrees of homogeneous polynomials, d: the
degree of the desired power products

@item @strong{Return:}
a size(dv)*m <intmat> where each column ought to be interpreted as
containing the exponents of the corresponding polynomials. The product
of the powers is then homogeneous of degree d.

@end table
@strong{Example:}
@smallexample
@c computed example power_products d2t_singular/finvar_lib.doc:1196 
LIB "finvar.lib";
intvec dv=5,5,5,10,10;
print(power_products(dv,10));
@expansion{}      2     1     1     0     0     0     0     0
@expansion{}      0     1     0     2     1     0     0     0
@expansion{}      0     0     1     0     1     2     0     0
@expansion{}      0     0     0     0     0     0     1     0
@expansion{}      0     0     0     0     0     0     0     1
print(power_products(dv,7));
@expansion{}      0
@expansion{}      0
@expansion{}      0
@expansion{}      0
@expansion{}      0
@c end example power_products d2t_singular/finvar_lib.doc:1196
@end smallexample
@c ---end content power_products---

@c ------------------- secondary_char0 -------------
@node secondary_char0, secondary_charp, power_products, finvar_lib
@subsubsection secondary_char0
@cindex secondary_char0
@c ---content secondary_char0---
Procedure from library @code{finvar.lib} (@pxref{finvar_lib}).

@table @asis
@item @strong{Usage:}
secondary_char0(P,REY,M[,v]);
@*P: a 1xn <matrix> with primary invariants, REY: a gxn <matrix>
representing the Reynolds operator, M: a 1x2 <matrix> giving numerator
and denominator of the Molien series, v: an optional <int>

@item @strong{Assume:}
n is the number of variables of the basering, g the size of the group,
REY is the 1st return value of group_reynolds(), reynolds_molien() or
the second one of primary_invariants(), M the return value of molien()
or the second one of reynolds_molien() or the third one of
primary_invariants()

@item @strong{Return:}
secondary invariants of the invariant ring (type <matrix>) and
irreducible secondary invariants (type <matrix>)

@item @strong{Display:}
information if v does not equal 0

@item @strong{Theory:}
The secondary invariants are calculated by finding a basis (in terms
of monomials) of the basering modulo the primary invariants, mapping
those to invariants with the Reynolds operator and using these images
or their power products such that they are linearly independent modulo
the primary invariants (see paper "Some Algorithms in Invariant
Theory of Finite Groups" by Kemper and Steel (1997)).

@end table
@strong{Example:}
@smallexample
@c computed example secondary_char0 d2t_singular/finvar_lib.doc:1244 
LIB "finvar.lib";
ring R=0,(x,y,z),dp;
matrix A[3][3]=0,1,0,-1,0,0,0,0,-1;
list L=primary_invariants(A);
matrix S,IS=secondary_char0(L[1..3]);
print(S);
@expansion{} 1,xyz,x2z-y2z,x3y-xy3
print(IS);
@expansion{} xyz,x2z-y2z,x3y-xy3
@c end example secondary_char0 d2t_singular/finvar_lib.doc:1244
@end smallexample
@c ---end content secondary_char0---

@c ------------------- secondary_charp -------------
@node secondary_charp, secondary_no_molien, secondary_char0, finvar_lib
@subsubsection secondary_charp
@cindex secondary_charp
@c ---content secondary_charp---
Procedure from library @code{finvar.lib} (@pxref{finvar_lib}).

@table @asis
@item @strong{Usage:}
secondary_charp(P,REY,ringname[,v]);
@*P: a 1xn <matrix> with primary invariants, REY: a gxn <matrix>
representing the Reynolds operator, ringname: a <string> giving the
name of a ring of characteristic 0 where the Molien series is stored,
v: an optional <int>

@item @strong{Assume:}
n is the number of variables of the basering, g the size of the group,
REY is the 1st return value of group_reynolds(), reynolds_molien() or
the second one of primary_invariants(), `ringname` is a ring of
char 0 that has been created by molien() or reynolds_molien() or
primary_invariants()

@item @strong{Return:}
secondary invariants of the invariant ring (type <matrix>) and
irreducible secondary invariants (type <matrix>)

@item @strong{Display:}
information if v does not equal 0

@item @strong{Theory:}
Secondary invariants are calculated by finding a basis (in terms of
monomials) of the basering modulo primary invariants, mapping those
to invariants with the Reynolds operator and using these images or
their power products such that they are linearly independent modulo
the primary invariants (see paper "Some Algorithms in Invariant
Theory of Finite Groups" by Kemper and Steel (1997)).

@end table
@strong{Example:}
@smallexample
@c computed example secondary_charp d2t_singular/finvar_lib.doc:1296 
LIB "finvar.lib";
ring R=3,(x,y,z),dp;
matrix A[3][3]=0,1,0,-1,0,0,0,0,-1;
list L=primary_invariants(A);
matrix S,IS=secondary_charp(L[1..size(L)]);
print(S);
@expansion{} 1,xyz,x2z-y2z,x3y-xy3
print(IS);
@expansion{} xyz,x2z-y2z,x3y-xy3
@c end example secondary_charp d2t_singular/finvar_lib.doc:1296
@end smallexample
@c ---end content secondary_charp---

@c ------------------- secondary_no_molien -------------
@node secondary_no_molien, secondary_and_irreducibles_no_molien, secondary_charp, finvar_lib
@subsubsection secondary_no_molien
@cindex secondary_no_molien
@c ---content secondary_no_molien---
Procedure from library @code{finvar.lib} (@pxref{finvar_lib}).

@table @asis
@item @strong{Usage:}
secondary_no_molien(P,REY[,deg_vec,v]);
@*P: a 1xn <matrix> with primary invariants, REY: a gxn <matrix>
representing the Reynolds operator, deg_vec: an optional <intvec>
listing some degrees where no non-trivial homogeneous invariants can
be found, v: an optional <int>

@item @strong{Assume:}
n is the number of variables of the basering, g the size of the group,
REY is the 1st return value of group_reynolds(), reynolds_molien() or
the second one of primary_invariants(), deg_vec is the second return
value of primary_char0_no_molien(), primary_charp_no_molien(),
primary_char0_no_molien_random() or primary_charp_no_molien_random()

@item @strong{Return:}
secondary invariants of the invariant ring (type <matrix>)

@item @strong{Display:}
information if v does not equal 0

@item @strong{Theory:}
Secondary invariants are calculated by finding a basis (in terms of
monomials) of the basering modulo primary invariants, mapping those to
invariants with the Reynolds operator and using these images as
candidates for secondary invariants.

@end table
@strong{Example:}
@smallexample
@c computed example secondary_no_molien d2t_singular/finvar_lib.doc:1345 
LIB "finvar.lib";
ring R=0,(x,y,z),dp;
matrix A[3][3]=0,1,0,-1,0,0,0,0,-1;
list L=primary_invariants(A,intvec(1,1,0));
matrix S=secondary_no_molien(L[1..3]);
print(S);
@expansion{} 1,xyz,x2z-y2z,x3y-xy3
@c end example secondary_no_molien d2t_singular/finvar_lib.doc:1345
@end smallexample
@c ---end content secondary_no_molien---

@c ------------------- secondary_and_irreducibles_no_molien -------------
@node secondary_and_irreducibles_no_molien, secondary_not_cohen_macaulay, secondary_no_molien, finvar_lib
@subsubsection secondary_and_irreducibles_no_molien
@cindex secondary_and_irreducibles_no_molien
@c ---content secondary_and_irreducibles_no_molien---
Procedure from library @code{finvar.lib} (@pxref{finvar_lib}).

@table @asis
@item @strong{Usage:}
secondary_and_irreducibles_no_molien(P,REY[,v]);
@*P: a 1xn <matrix> with primary invariants, REY: a gxn <matrix>
representing the Reynolds operator, v: an optional <int>

@item @strong{Assume:}
n is the number of variables of the basering, g the size of the group,
REY is the 1st return value of group_reynolds(), reynolds_molien() or
the second one of primary_invariants()

@item @strong{Return:}
secondary invariants of the invariant ring (type <matrix>) and
irreducible secondary invariants (type <matrix>)

@item @strong{Display:}
information if v does not equal 0

@item @strong{Theory:}
Secondary invariants are calculated by finding a basis (in terms of
monomials) of the basering modulo primary invariants, mapping those to
invariants with the Reynolds operator and using these images or their
power products such that they are linearly independent modulo the
primary invariants (see paper "Some Algorithms in Invariant Theory of
Finite Groups" by Kemper and Steel (1997)).

@end table
@strong{Example:}
@smallexample
@c computed example secondary_and_irreducibles_no_molien d2t_singular/finvar_lib.doc:1392 
LIB "finvar.lib";
ring R=0,(x,y,z),dp;
matrix A[3][3]=0,1,0,-1,0,0,0,0,-1;
list L=primary_invariants(A,intvec(1,1,0));
matrix S,IS=secondary_and_irreducibles_no_molien(L[1..2]);
print(S);
@expansion{} 1,xyz,x2z-y2z,x3y-xy3
print(IS);
@expansion{} xyz,x2z-y2z,x3y-xy3
@c end example secondary_and_irreducibles_no_molien d2t_singular/finvar_lib.doc:1392
@end smallexample
@c ---end content secondary_and_irreducibles_no_molien---

@c ------------------- secondary_not_cohen_macaulay -------------
@node secondary_not_cohen_macaulay, orbit_variety, secondary_and_irreducibles_no_molien, finvar_lib
@subsubsection secondary_not_cohen_macaulay
@cindex secondary_not_cohen_macaulay
@c ---content secondary_not_cohen_macaulay---
Procedure from library @code{finvar.lib} (@pxref{finvar_lib}).

@table @asis
@item @strong{Usage:}
secondary_not_cohen_macaulay(P,G1,G2,...[,v]);
@*P: a 1xn <matrix> with primary invariants, G1,G2,...: nxn <matrices>
generating a finite matrix group, v: an optional <int>

@item @strong{Assume:}
n is the number of variables of the basering

@item @strong{Return:}
secondary invariants of the invariant ring (type <matrix>)

@item @strong{Display:}
information if v does not equal 0

@item @strong{Theory:}
Secondary invariants are generated following "Generating Invariant
Rings of Finite Groups over Arbitrary Fields" by Kemper (1996).

@end table
@strong{Example:}
@smallexample
@c computed example secondary_not_cohen_macaulay d2t_singular/finvar_lib.doc:1433 
LIB "finvar.lib";
ring R=2,(x,y,z),dp;
matrix A[3][3]=0,1,0,-1,0,0,0,0,-1;
list L=primary_invariants(A);
matrix S=secondary_not_cohen_macaulay(L[1],A);
print(S);
@expansion{} 1
@c end example secondary_not_cohen_macaulay d2t_singular/finvar_lib.doc:1433
@end smallexample
@c ---end content secondary_not_cohen_macaulay---

@c ------------------- orbit_variety -------------
@node orbit_variety, relative_orbit_variety, secondary_not_cohen_macaulay, finvar_lib
@subsubsection orbit_variety
@cindex orbit_variety
@c ---content orbit_variety---
Procedure from library @code{finvar.lib} (@pxref{finvar_lib}).

@table @asis
@item @strong{Usage:}
orbit_variety(F,s);
@*F: a 1xm <matrix> defining an invariant ring, s: a <string> giving the
name for a new ring

@item @strong{Return:}
a Groebner basis (type <ideal>, named G) for the ideal defining the
orbit variety (i.e. the syzygy ideal) in the new ring (named `s`)

@item @strong{Theory:}
The ideal of algebraic relations of the invariant ring generators is
calculated, then the variables of the original ring are eliminated and
the polynomials that are left over define the orbit variety

@end table
@strong{Example:}
@smallexample
@c computed example orbit_variety d2t_singular/finvar_lib.doc:1469 
LIB "finvar.lib";
ring R=0,(x,y,z),dp;
matrix F[1][7]=x2+y2,z2,x4+y4,1,x2z-1y2z,xyz,x3y-1xy3;
string newring="E";
orbit_variety(F,newring);
print(G);
@expansion{} y(4)-1,
@expansion{} y(5)*y(6)-y(2)*y(7),
@expansion{} y(2)*y(3)-y(5)^2-2*y(6)^2,
@expansion{} y(1)^2*y(6)-2*y(3)*y(6)+y(5)*y(7),
@expansion{} y(1)^2*y(5)-y(3)*y(5)-2*y(6)*y(7),
@expansion{} y(1)^2*y(2)-y(2)*y(3)-2*y(6)^2,
@expansion{} y(1)^4-3*y(1)^2*y(3)+2*y(3)^2+2*y(7)^2
basering;
@expansion{} //   characteristic : 0
@expansion{} //   number of vars : 7
@expansion{} //        block   1 : ordering dp
@expansion{} //                  : names    y(1) y(2) y(3) y(4) y(5) y(6) y(7) 
@expansion{} //        block   2 : ordering C
@c end example orbit_variety d2t_singular/finvar_lib.doc:1469
@end smallexample
@c ---end content orbit_variety---

@c ------------------- relative_orbit_variety -------------
@node relative_orbit_variety, image_of_variety, orbit_variety, finvar_lib
@subsubsection relative_orbit_variety
@cindex relative_orbit_variety
@c ---content relative_orbit_variety---
Procedure from library @code{finvar.lib} (@pxref{finvar_lib}).

@table @asis
@item @strong{Usage:}
relative_orbit_variety(I,F,s);
@*I: an <ideal> invariant under the action of a group, F: a 1xm
<matrix> defining the invariant ring of this group, s: a <string>
giving a name for a new ring

@item @strong{Return:}
a Groebner basis (type <ideal>, named G) for the ideal defining the
relative orbit variety with respect to I in the new ring (named s)

@item @strong{Theory:}
A Groebner basis of the ideal of algebraic relations of the invariant
ring generators is calculated, then one of the basis elements plus the
ideal generators. The variables of the original ring are eliminated
and the polynomials that are left define the relative orbit variety
with respect to I.

@end table
@strong{Example:}
@smallexample
@c computed example relative_orbit_variety d2t_singular/finvar_lib.doc:1509 
LIB "finvar.lib";
ring R=0,(x,y,z),dp;
matrix F[1][3]=x+y+z,xy+xz+yz,xyz;
ideal I=x2+y2+z2-1,x2y+y2z+z2x-2x-2y-2z,xy2+yz2+zx2-2x-2y-2z;
string newring="E";
relative_orbit_variety(I,F,newring);
print(G);
@expansion{} 27*y(3)^6-513*y(3)^4+33849*y(3)^2-784,
@expansion{} 1475*y(2)+9*y(3)^4-264*y(3)^2+736,
@expansion{} 8260*y(1)+9*y(3)^5-87*y(3)^3+5515*y(3)
basering;
@expansion{} //   characteristic : 0
@expansion{} //   number of vars : 3
@expansion{} //        block   1 : ordering lp
@expansion{} //                  : names    y(1) y(2) y(3) 
@expansion{} //        block   2 : ordering C
@c end example relative_orbit_variety d2t_singular/finvar_lib.doc:1509
@end smallexample
@c ---end content relative_orbit_variety---

@c ------------------- image_of_variety -------------
@node image_of_variety,, relative_orbit_variety, finvar_lib
@subsubsection image_of_variety
@cindex image_of_variety
@c ---content image_of_variety---
Procedure from library @code{finvar.lib} (@pxref{finvar_lib}).

@table @asis
@item @strong{Usage:}
image_of_variety(I,F);
@*I: an arbitrary <ideal>, F: a 1xm <matrix> defining an invariant ring
of a some matrix group

@item @strong{Return:}
the <ideal> defining the image under that group of the variety defined
by I

@item @strong{Theory:}
relative_orbit_variety(I,F,s) is called and the newly introduced
variables in the output are replaced by the generators of the
invariant ring. This ideal in the original variables defines the image
of the variety defined by I

@end table
@strong{Example:}
@smallexample
@c computed example image_of_variety d2t_singular/finvar_lib.doc:1548 
LIB "finvar.lib";
ring R=0,(x,y,z),dp;
matrix F[1][3]=x+y+z,xy+xz+yz,xyz;
ideal I=xy;
print(image_of_variety(I,F));
@expansion{} xyz
@c end example image_of_variety d2t_singular/finvar_lib.doc:1548
@end smallexample
@c ---end content image_of_variety---
