This is InvariantRing.info, produced by Macaulay2, version 1.25.11

InvariantRing -- invariants of group actions
********************************************

Description
===========

InvariantRing is a package implementing algorithms to compute invariants of
linearly reductive groups.

Current algorithms include:

  * An elimination theory algorithm that computes the Hilbert ideal for any
    linearly reductive group: Derksen, H. & Kemper, G. (2015). Computational
    Invariant Theory (see https://link.springer.com/book/10.1007%2F978-3-662-
    48422-7 ). Heidelberg: Springer. Algorithm 4.1.9, pp 159-164
  * A simple and efficient algorithm for invariants of tori based on: Derksen,
    H. & Kemper, G. (2015). Computational Invariant Theory (see
    https://link.springer.com/book/10.1007%2F978-3-662-48422-7 ). Heidelberg:
    Springer. Algorithm 4.3.1 pp 174-177
  * An adaptation of the tori algorithm for invariants of finite abelian groups
    based on: Gandini, F. Ideals of Subspace Arrangements (see
    https://deepblue.lib.umich.edu/handle/2027.42/151589 ). Thesis
    (Ph.D.)-University of Michigan. 2019. ISBN: 978-1392-76291-2. pp 29-34.
  * King's algorithm and the linear algebra method for invariants of finite
    groups: Derksen, H. & Kemper, G. (2015). Computational Invariant Theory
    (see https://link.springer.com/book/10.1007%2F978-3-662-48422-7 ).
    Heidelberg: Springer. Algorithm 3.8.2, pp 107-109; pp 72-74
  * The algorithms for primary and secondary invariants, and Molien series of
    finite groups implemented in version 1.1.0 of this package by: Hawes, T.
    Computing the invariant ring of a finite group (see
    https://msp.org/jsag/2013/5-1/p03.xhtml ). JSAG, Vol. 5 (2013). pp 15-19.
    DOI: 10.2140/jsag.2013.5.15

Version history:

  * 1.1.0: the first version of this package was developed by Thomas Hawes. It
    focused on computing primary and secondary invariants of finite groups. For
    more information, see: Hawes, T. Computing the invariant ring of a finite
    group (see https://msp.org/jsag/2013/5-1/p03.xhtml ). JSAG, Vol. 5 (2013).
    pp 15-19. DOI: 10.2140/jsag.2013.5.15
  * 2.0: this version was developed by L. Ferraro, F. Galetto, F. Gandini, H.
    Huang, M. Mastroeni, and X. Ni. It introduces types for different group
    actions as well as rings of invariants. It also contains new functionality
    for invariants of finite groups, diagonal actions (tori/abelian groups),
    and linearly reductive groups. The code from version 1.1.0 is preserved in
    the auxiliary file Hawes.m2 (with documentation in the file HawesDoc.m2)
    and has been updated to work with the new types.

Authors
=======

  * Luigi Ferraro (see http://www.math.ttu.edu/~lferraro/ ) <lferraro@ttu.edu>
  * Federico Galetto (see https://math.galetto.org ) <f.galetto@csuohio.edu>
  * Francesca Gandini (see https://sites.google.com/a/umich.edu/gandini/home )
    <fra.gandi.phd@gmail.com>
  * Hang Huang (see https://math.tamu.edu/~hhuang ) <hhuang235@tamu.edu>
  * Thomas Hawes <thomas.hawes@maths.ox.ac.uk>
  * Matthew Mastroeni (see https://mnmastro.github.io/ ) <mmastro@okstate.edu>
  * Xianglong Ni (see https://math.berkeley.edu/~xlni/ ) <xlni@berkeley.edu>

Certification a gold star
=========================

Version 2.0 of this package was accepted for publication in volume 14 (see
https://msp.org/jsag/2024/14-1/ ) of Journal of Software for Algebra and
Geometry (see https://msp.org/jsag/ ) on 2023-09-14, in the article The
InvariantRing package for Macaulay2 (see
https://msp.org/jsag/2024/14-1/p02.xhtml ) (DOI: 10.2140/jsag.2024.14.5 (see
https://doi.org/10.2140/jsag.2024.14.5 )). That version can be obtained from
the journal (see https://msp.org/jsag/2024/14-1/jsag-v14-n1-x02-InvariantRing.
m2 ).

Version
=======

This documentation describes version 2.0 of InvariantRing, released November
11, 2020.

Citation
========

If you have used this package in your research, please cite it as follows:

+-----------------------------------------------------------------------------+
|@misc{InvariantRingSource,                                                   |
|  title = {{InvariantRing: invariants of group actions. Version~2.0}},       |
|  author = {Luigi Ferraro and Federico Galetto and Francesca Gandini and Hang|
|  howpublished = {A \emph{Macaulay2} package available at                    |
|    \url{https://github.com/Macaulay2/M2/tree/stable/M2/Macaulay2/packages}} |
|}                                                                            |
|                                                                             |
|@article{InvariantRingArticle,                                               |
|  title = {{The InvariantRing package for \emph{Macaulay2}}},                |
|  author = {Luigi Ferraro and Federico Galetto and Francesca Gandini and Hang|
|  journal = {Journal of Software for Algebra and Geometry},                  |
|  volume = {14},                                                             |
|  year = {2023},                                                             |
|}                                                                            |
|-----------------------------------------------------------------------------|
|Huang and Thomas Hawes and Matthew Mastroeni and Xianglong Ni},              |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|Huang and Thomas Hawes and Matthew Mastroeni and Xianglong Ni},              |
+-----------------------------------------------------------------------------+

Exports
=======

  * Types
      * DiagonalAction -- the class of all diagonal
        actions
      * FiniteGroupAction -- the class of all finite
        group actions
      * GroupAction -- the class of all group actions
      * LinearlyReductiveAction -- the class of
        all (non finite, non toric) linearly reductive group actions
      * RingOfInvariants -- the class of the rings of
        invariants under the action of a finite group, an Abelian group or a
        linearly reductive group
  * Functions and commands
      * action -- the group action that produced a ring of
        invariants
      * actionMatrix -- matrix of a linearly reductive
        action
      * cyclicFactors -- of a diagonal action
      * definingIdeal -- presentation of a ring of
        invariants as polynomial ring modulo the defining ideal
      * diagonalAction -- diagonal group action via
        weights
      * equivariantHilbertSeries, --
        equivariant Hilbert series for a diagonal action
      * finiteAction -- the group action generated by a
        list of matrices
      * group -- list all elements of the group of a finite group
        action
      * groupIdeal -- ideal defining a linearly reductive
        group
      * hilbertIdeal -- compute generators for the Hilbert
        ideal
      * hironakaDecomposition -- calculates a
        Hironaka decomposition for the invariant ring of a finite group
      * invariantRing -- the ring of invariants of a
        group action
      * invariants -- computes the generating invariants of
        a group action
      * isAbelian -- check whether a finite matrix group is
        Abelian
      * isInvariant -- check whether a polynomial is
        invariant under a group action
      * linearlyReductiveAction -- Linearly
        reductive group action
      * molienSeries -- computes the Molien (Hilbert)
        series of the invariant ring of a finite group
      * permutationMatrix -- convert a one-line
        notation or cyclic notation of a permutation to a matrix representation
      * primaryInvariants -- computes a list of
        primary invariants for the invariant ring of a finite group
      * reynoldsOperator -- the image of a polynomial
        under the Reynolds operator
      * schreierGraph -- Schreier graph of a finite group
      * secondaryInvariants -- computes secondary
        invariants for the invariant ring of a finite group
      * weights -- of a diagonal action
      * words -- associate a word in the generators of a group to
        each element
  * Methods
      * "action(RingOfInvariants)" -- see action, -- the group
        action that produced a ring of invariants
      * "actionMatrix(LinearlyReductiveAction)" -- see actionMatrix,
        -- matrix of a linearly reductive action
      * ambient(RingOfInvariants) -- the
        ambient polynomial ring where the group acted upon
      * "cyclicFactors(DiagonalAction)" -- see cyclicFactors,
        -- of a diagonal action
      * "definingIdeal(RingOfInvariants)" -- see definingIdeal,
        -- presentation of a ring of invariants as polynomial
        ring modulo the defining ideal
      * degreesRing(DiagonalAction), --
        of a diagonal action
      * "diagonalAction(Matrix,List,PolynomialRing)" -- see
        diagonalAction, -- diagonal group action via weights
      * "diagonalAction(Matrix,Matrix,List,PolynomialRing)" -- see
        diagonalAction, -- diagonal group action via weights
      * "diagonalAction(Matrix,PolynomialRing)" -- see diagonalAction,
        -- diagonal group action via weights
      * dim(GroupAction) -- dimension of the
        polynomial ring being acted upon
      * "equivariantHilbertSeries(DiagonalAction)" -- see
        equivariantHilbertSeries, -- equivariant
        Hilbert series for a diagonal action
      * "finiteAction(List,PolynomialRing)" -- see finiteAction,
        -- the group action generated by a list of matrices
      * "finiteAction(Matrix,PolynomialRing)" -- see finiteAction,
        -- the group action generated by a list of matrices
      * generators(FiniteGroupAction),
        -- generators of a finite group
      * generators(RingOfInvariants),
        -- the generators for a ring of invariants
      * "group(FiniteGroupAction)" -- see group, -- list all
        elements of the group of a finite group action
      * "groupIdeal(LinearlyReductiveAction)" -- see groupIdeal,
        -- ideal defining a linearly reductive group
      * "hilbertIdeal(LinearlyReductiveAction)" -- see hilbertIdeal,
        -- compute generators for the Hilbert ideal
      * hilbertSeries(RingOfInvariants)
        -- Hilbert series of the invariant
        ring
      * "hironakaDecomposition(FiniteGroupAction)" -- see
        hironakaDecomposition, -- calculates a Hironaka
        decomposition for the invariant ring of a finite group
      * "invariantRing(GroupAction)" -- see invariantRing,
        -- the ring of invariants of a group action
      * "PolynomialRing ^ GroupAction" -- see invariantRing,
        -- the ring of invariants of a group action
      * "QuotientRing ^ LinearlyReductiveAction" -- see invariantRing,
        -- the ring of invariants of a group action
      * invariants(DiagonalAction), --
        computes the generating invariants of a group action
      * invariants(FiniteGroupAction),
        -- computes the generating invariants of a group action
      * "invariants(FiniteGroupAction,List)" -- see
        invariants(FiniteGroupAction,ZZ),
        -- basis for graded component
        of invariant ring
      * invariants(FiniteGroupAction,ZZ)
        -- basis for graded component
        of invariant ring
      * invariants(LinearlyReductiveAction)
        -- invariant generators of
        Hilbert ideal
      * "invariants(LinearlyReductiveAction,List)" -- see
        invariants(LinearlyReductiveAction,ZZ),
        -- basis for graded
        component of invariant ring
      * invariants(LinearlyReductiveAction,ZZ)
        -- basis for graded
        component of invariant ring
      * "isAbelian(FiniteGroupAction)" -- see isAbelian, --
        check whether a finite matrix group is Abelian
      * "isInvariant(RingElement,DiagonalAction)" -- see isInvariant,
        -- check whether a polynomial is invariant under a group
        action
      * "isInvariant(RingElement,FiniteGroupAction)" -- see isInvariant,
        -- check whether a polynomial is invariant under a group
        action
      * "isInvariant(RingElement,LinearlyReductiveAction)" -- see
        isInvariant, -- check whether a polynomial is invariant
        under a group action
      * "linearlyReductiveAction(Ideal,Matrix,PolynomialRing)" -- see
        linearlyReductiveAction, -- Linearly reductive
        group action
      * "linearlyReductiveAction(Ideal,Matrix,QuotientRing)" -- see
        linearlyReductiveAction, -- Linearly reductive
        group action
      * "molienSeries(FiniteGroupAction)" -- see molienSeries,
        -- computes the Molien (Hilbert) series of the invariant
        ring of a finite group
      * "net(DiagonalAction)" -- see net(RingOfInvariants),
        -- format for printing, as a net
      * "net(FiniteGroupAction)" -- see net(RingOfInvariants),
        -- format for printing, as a net
      * "net(LinearlyReductiveAction)" -- see net(RingOfInvariants),
        -- format for printing, as a net
      * net(RingOfInvariants) -- format for
        printing, as a net
      * numgens(DiagonalAction) -- number
        of generators of the finite part of a diagonal group
      * numgens(FiniteGroupAction), --
        number of generators of a finite group
      * "permutationMatrix(Array)" -- see permutationMatrix,
        -- convert a one-line notation or cyclic notation of
        a permutation to a matrix representation
      * "permutationMatrix(List)" -- see permutationMatrix,
        -- convert a one-line notation or cyclic notation of
        a permutation to a matrix representation
      * "permutationMatrix(String)" -- see permutationMatrix,
        -- convert a one-line notation or cyclic notation of
        a permutation to a matrix representation
      * "permutationMatrix(ZZ,Array)" -- see permutationMatrix,
        -- convert a one-line notation or cyclic notation of
        a permutation to a matrix representation
      * "permutationMatrix(ZZ,List)" -- see permutationMatrix,
        -- convert a one-line notation or cyclic notation of
        a permutation to a matrix representation
      * "primaryInvariants(FiniteGroupAction)" -- see primaryInvariants,
        -- computes a list of primary invariants for the
        invariant ring of a finite group
      * rank(DiagonalAction) -- of a diagonal
        action
      * relations(FiniteGroupAction),
        -- relations of a finite group
      * "reynoldsOperator(RingElement,DiagonalAction)" -- see
        reynoldsOperator, -- the image of a polynomial under
        the Reynolds operator
      * "reynoldsOperator(RingElement,FiniteGroupAction)" -- see
        reynoldsOperator, -- the image of a polynomial under
        the Reynolds operator
      * ring(GroupAction) -- the polynomial ring
        being acted upon
      * "schreierGraph(FiniteGroupAction)" -- see schreierGraph,
        -- Schreier graph of a finite group
      * "secondaryInvariants(List,FiniteGroupAction)" -- see
        secondaryInvariants, -- computes secondary
        invariants for the invariant ring of a finite group
      * "weights(DiagonalAction)" -- see weights, -- of a
        diagonal action
      * "words(FiniteGroupAction)" -- see words, -- associate a
        word in the generators of a group to each element
  * Symbols
      * equivariantHilbert -- stores equivariant
        Hilbert series expansions
      * "DegreeBound" -- see invariants(...,DegreeBound=>...),
        -- degree bound for
        invariants of finite groups
      * "UseCoefficientRing" -- see
        invariants(...,UseCoefficientRing=>...),
        -- option to
        compute invariants over the given coefficient ring
      * "UseLinearAlgebra" -- see invariants(...,UseLinearAlgebra=>...),
        -- strategy
        for computing invariants of finite groups
      * "Dade" -- see primaryInvariants(...,Dade=>...),
        -- an optional
        argument for primaryInvariants determining whether to use the Dade
        algorithm
      * "DegreeVector" -- see primaryInvariants(...,DegreeVector=>...),
        -- an
        optional argument for primaryInvariants that finds invariants of
        certain degrees
      * "PrintDegreePolynomial" -- see
        secondaryInvariants(...,PrintDegreePolynomial=>...),
        -- an optional argument for secondaryInvariants that determines the
        printing of an informative polynomial
      * UseNormaliz -- option for diagonal invariants
      * "UsePolyhedra" -- see UseNormaliz, -- option for
        diagonal invariants

For the programmer
==================

The object InvariantRing, is a package (Macaulay2Doc),
defined in InvariantRing.m2, with auxiliary files in
InvariantRing/.

-------------------------------------------------------------------------------

The source of this document is in InvariantRing/InvariantRingDoc.m2:72:0.

action -- the group action that produced a ring of invariants
*************************************************************

  * Usage:
        action S
  * Inputs:
      * S, an instance of the type RingOfInvariants,
        of the group action being returned
  * Outputs:
      * an instance of the type GroupAction, the action
        that produced the ring of invariants in the input

Description
===========

This function is provided by the package InvariantRing.

This example shows how to recover the action of a torus that produced a certain
ring of invariants. Note other action types are possible and may produce a
different looking output.

+-----------------------------------------------------------+
|i1 : R = QQ[x_1..x_4]                                      |
|                                                           |
|o1 = R                                                     |
|                                                           |
|o1 : PolynomialRing                                        |
+-----------------------------------------------------------+
|i2 : T = diagonalAction(matrix {{0,1,-1,1},{1,0,-1,-1}}, R)|
|                                                           |
|             * 2                                           |
|o2 = R <- (QQ )  via                                       |
|                                                           |
|     | 0 1 -1 1  |                                         |
|     | 1 0 -1 -1 |                                         |
|                                                           |
|o2 : DiagonalAction                                        |
+-----------------------------------------------------------+
|i3 : S = R^T                                               |
|                                                           |
|o3 =             2                                         |
|     QQ[x x x , x x x ]                                    |
|         1 2 3   1 3 4                                     |
|                                                           |
|o3 : RingOfInvariants                                      |
+-----------------------------------------------------------+
|i4 : action S                                              |
|                                                           |
|             * 2                                           |
|o4 = R <- (QQ )  via                                       |
|                                                           |
|     | 0 1 -1 1  |                                         |
|     | 1 0 -1 -1 |                                         |
|                                                           |
|o4 : DiagonalAction                                        |
+-----------------------------------------------------------+

Ways to use action:
===================

  * "action(RingOfInvariants)"

For the programmer
==================

The object action, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in InvariantRing/InvariantsDoc.m2:41:0.

actionMatrix -- matrix of a linearly reductive action
*****************************************************

  * Usage:
        actionMatrix L
  * Inputs:
      * L, an instance of the type LinearlyReductiveAction,
  * Outputs:
      * a matrix (Macaulay2Doc), of a group action on a ring

Description
===========

This function is provided by the package InvariantRing.

Suppose the action L consists of the linearly reductive group with coordinate
ring S/I (where S is a polynomial ring) acting on a (quotient of) a polynomial
ring R via the action matrix M. This function returns the action matrix M.

+------------------------------------------------------+
|i1 : S = QQ[z]                                        |
|                                                      |
|o1 = S                                                |
|                                                      |
|o1 : PolynomialRing                                   |
+------------------------------------------------------+
|i2 : I = ideal(z^2 - 1)                               |
|                                                      |
|            2                                         |
|o2 = ideal(z  - 1)                                    |
|                                                      |
|o2 : Ideal of S                                       |
+------------------------------------------------------+
|i3 : M = matrix{{(z+1)/2, (1-z)/2},{(1-z)/2, (z+1)/2}}|
|                                                      |
|o3 = | 1/2z+1/2  -1/2z+1/2 |                          |
|     | -1/2z+1/2 1/2z+1/2  |                          |
|                                                      |
|             2      2                                 |
|o3 : Matrix S  <-- S                                  |
+------------------------------------------------------+
|i4 : R = QQ[x,y]                                      |
|                                                      |
|o4 = R                                                |
|                                                      |
|o4 : PolynomialRing                                   |
+------------------------------------------------------+
|i5 : L = linearlyReductiveAction(I, M, R)             |
|                                                      |
|                   2                                  |
|o5 = R <- S/ideal(z  - 1) via                         |
|                                                      |
|     | 1/2z+1/2  -1/2z+1/2 |                          |
|     | -1/2z+1/2 1/2z+1/2  |                          |
|                                                      |
|o5 : LinearlyReductiveAction                          |
+------------------------------------------------------+
|i6 : actionMatrix L                                   |
|                                                      |
|o6 = | 1/2z+1/2  -1/2z+1/2 |                          |
|     | -1/2z+1/2 1/2z+1/2  |                          |
|                                                      |
|             2      2                                 |
|o6 : Matrix S  <-- S                                  |
+------------------------------------------------------+

Ways to use actionMatrix:
=========================

  * "actionMatrix(LinearlyReductiveAction)"

For the programmer
==================

The object actionMatrix, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in
InvariantRing/LinearlyReductiveGroupsDoc.m2:46:0.

ambient(RingOfInvariants) -- the ambient polynomial ring where the group acted upon
***********************************************************************************

  * Function: ambient (Macaulay2Doc),
  * Usage:
        ambient S
  * Inputs:
      * S, an instance of the type RingOfInvariants,
        of the group action being returned
  * Outputs:
      * a polynomial ring (Macaulay2Doc), where the group
        acted upon

Description
===========

This function is provided by the package InvariantRing.

This example shows how to recover the polynomial ring when a torus acted upon.

+-----------------------------------------------------------+
|i1 : R = QQ[x_1..x_4]                                      |
|                                                           |
|o1 = R                                                     |
|                                                           |
|o1 : PolynomialRing                                        |
+-----------------------------------------------------------+
|i2 : T = diagonalAction(matrix {{0,1,-1,1},{1,0,-1,-1}}, R)|
|                                                           |
|             * 2                                           |
|o2 = R <- (QQ )  via                                       |
|                                                           |
|     | 0 1 -1 1  |                                         |
|     | 1 0 -1 -1 |                                         |
|                                                           |
|o2 : DiagonalAction                                        |
+-----------------------------------------------------------+
|i3 : S = R^T                                               |
|                                                           |
|o3 =             2                                         |
|     QQ[x x x , x x x ]                                    |
|         1 2 3   1 3 4                                     |
|                                                           |
|o3 : RingOfInvariants                                      |
+-----------------------------------------------------------+
|i4 : ambient S                                             |
|                                                           |
|o4 = R                                                     |
|                                                           |
|o4 : PolynomialRing                                        |
+-----------------------------------------------------------+

Ways to use this method:
========================

  * ambient(RingOfInvariants) -- the
    ambient polynomial ring where the group acted upon
-------------------------------------------------------------------------------

The source of this document is in InvariantRing/InvariantsDoc.m2:937:0.

cyclicFactors -- of a diagonal action
*************************************

  * Usage:
        cyclicFactors D
  * Inputs:
      * D, an instance of the type DiagonalAction,
  * Outputs:
      * a list (Macaulay2Doc), of orders of cyclic abelian factors
        in the decomposition of the diagonal group

Description
===========

This function is provided by the package InvariantRing.

Use this function to recover the cyclic abelian factors of a diagonal action on
a polynomial ring.

The following example defines an action of a product of two cyclic groups of
order 3 acting on a three-dimensional vector space.

+--------------------------------+
|i1 : R = QQ[x_1..x_3]           |
|                                |
|o1 = R                          |
|                                |
|o1 : PolynomialRing             |
+--------------------------------+
|i2 : d = {3,3}                  |
|                                |
|o2 = {3, 3}                     |
|                                |
|o2 : List                       |
+--------------------------------+
|i3 : W = matrix{{1,0,1},{0,1,1}}|
|                                |
|o3 = | 1 0 1 |                  |
|     | 0 1 1 |                  |
|                                |
|              2       3         |
|o3 : Matrix ZZ  <-- ZZ          |
+--------------------------------+
|i4 : A = diagonalAction(W, d, R)|
|                                |
|o4 = R <- ZZ/3 x ZZ/3 via       |
|                                |
|     | 1 0 1 |                  |
|     | 0 1 1 |                  |
|                                |
|o4 : DiagonalAction             |
+--------------------------------+
|i5 : cyclicFactors A            |
|                                |
|o5 = {3, 3}                     |
|                                |
|o5 : List                       |
+--------------------------------+

See also
========

  * DiagonalAction -- the class of all diagonal actions
  * diagonalAction -- diagonal group action via weights

Ways to use cyclicFactors:
==========================

  * "cyclicFactors(DiagonalAction)"

For the programmer
==================

The object cyclicFactors, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in InvariantRing/AbelianGroupsDoc.m2:315:0.

definingIdeal -- presentation of a ring of invariants as polynomial ring modulo the defining ideal
**************************************************************************************************

  * Usage:
        definingIdeal S
  * Inputs:
      * S, an instance of the type RingOfInvariants,
  * Optional inputs (Macaulay2Doc),:
      * Variable (missing documentation) => ..., default value "u", name of the
        variables in the polynomial ring.
  * Outputs:
      * an ideal (Macaulay2Doc), which defines the ring of
        invariants as a polynomial ring modulo the ideal.

Description
===========

This function is provided by the package InvariantRing.

This method presents the ring of invariants as a polynomial ring modulo the
defining ideal. The default variable name in the polynomial ring is u_i. You
can pass the variable name you want as optional input.

+---------------------------------------+
|i1 : R = QQ[x_1..x_4]                  |
|                                       |
|o1 = R                                 |
|                                       |
|o1 : PolynomialRing                    |
+---------------------------------------+
|i2 : W = matrix{{0,1,-1,1},{1,0,-1,-1}}|
|                                       |
|o2 = | 0 1 -1 1  |                     |
|     | 1 0 -1 -1 |                     |
|                                       |
|              2       4                |
|o2 : Matrix ZZ  <-- ZZ                 |
+---------------------------------------+
|i3 : T = diagonalAction(W, R)          |
|                                       |
|             * 2                       |
|o3 = R <- (QQ )  via                   |
|                                       |
|     | 0 1 -1 1  |                     |
|     | 1 0 -1 -1 |                     |
|                                       |
|o3 : DiagonalAction                    |
+---------------------------------------+
|i4 : S = R^T                           |
|                                       |
|o4 =             2                     |
|     QQ[x x x , x x x ]                |
|         1 2 3   1 3 4                 |
|                                       |
|o4 : RingOfInvariants                  |
+---------------------------------------+
|i5 : definingIdeal S                   |
|                                       |
|o5 = ideal ()                          |
|                                       |
|o5 : Ideal of QQ[u ..u ]               |
|                  1   2                |
+---------------------------------------+

Ways to use definingIdeal:
==========================

  * "definingIdeal(RingOfInvariants)"

For the programmer
==================

The object definingIdeal, is a method function with options (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in InvariantRing/InvariantsDoc.m2:895:0.

degreesRing(DiagonalAction) -- of a diagonal action
***************************************************

  * Function: degreesRing (Macaulay2Doc),
  * Usage:
        degreesRing D
  * Inputs:
      * D, an instance of the type DiagonalAction,
  * Outputs:
      * a ring (Macaulay2Doc), where the equivariant Hilbert series
        of the diagonal group action lives in

Description
===========

This function is provided by the package InvariantRing.

Use this function to get the ring where the equivariant Hilbert series of the
diagonal group action lives in.

The following example defines an action of the product of a two-dimensional
torus and two cyclic group of order 3 on a polynomial ring in four variables.

+---------------------------------------+
|i1 : R = QQ[x_1..x_4]                  |
|                                       |
|o1 = R                                 |
|                                       |
|o1 : PolynomialRing                    |
+---------------------------------------+
|i2 : W = matrix{{0,1,-1,1},{1,0,-1,-1}}|
|                                       |
|o2 = | 0 1 -1 1  |                     |
|     | 1 0 -1 -1 |                     |
|                                       |
|              2       4                |
|o2 : Matrix ZZ  <-- ZZ                 |
+---------------------------------------+
|i3 : W1 = matrix{{1,0,1,0},{0,1,1,0}}  |
|                                       |
|o3 = | 1 0 1 0 |                       |
|     | 0 1 1 0 |                       |
|                                       |
|              2       4                |
|o3 : Matrix ZZ  <-- ZZ                 |
+---------------------------------------+
|i4 : T = diagonalAction(W,W1,{3,3},R)  |
|                                       |
|             * 2                       |
|o4 = R <- (QQ )  x ZZ/3 x ZZ/3 via     |
|                                       |
|     (| 0 1 -1 1  |, | 1 0 1 0 |)      |
|      | 1 0 -1 -1 |  | 0 1 1 0 |       |
|                                       |
|o4 : DiagonalAction                    |
+---------------------------------------+
|i5 : degreesRing T                     |
|                                       |
|o5 = ZZ[z ..z ][T]                     |
|         0   3                         |
|                                       |
|o5 : PolynomialRing                    |
+---------------------------------------+

See also
========

  * DiagonalAction -- the class of all diagonal actions
  * diagonalAction -- diagonal group action via weights

Ways to use this method:
========================

  * degreesRing(DiagonalAction) -- of a
    diagonal action
-------------------------------------------------------------------------------

The source of this document is in InvariantRing/AbelianGroupsDoc.m2:389:0.

DiagonalAction -- the class of all diagonal actions
***************************************************

Description
===========

This class is provided by the package InvariantRing.

DiagonalAction is the class of all diagonal actions on polynomial rings by a
product of a torus (possibly trivial) with a finite abelian group  for the
purpose of computing invariants. It is created using diagonalAction.

Functions and methods returning an object of class DiagonalAction:
==================================================================

  * "diagonalAction(Matrix,List,PolynomialRing)" -- see diagonalAction,
    -- diagonal group action via weights
  * "diagonalAction(Matrix,Matrix,List,PolynomialRing)" -- see
    diagonalAction, -- diagonal group action via weights
  * "diagonalAction(Matrix,PolynomialRing)" -- see diagonalAction,
    -- diagonal group action via weights

Methods that use an object of class DiagonalAction:
===================================================

  * "cyclicFactors(DiagonalAction)" -- see cyclicFactors,
    -- of a diagonal action
  * degreesRing(DiagonalAction) -- of a
    diagonal action
  * "equivariantHilbertSeries(DiagonalAction)" -- see
    equivariantHilbertSeries, -- equivariant Hilbert
    series for a diagonal action
  * invariants(DiagonalAction), --
    computes the generating invariants of a group action
  * "isInvariant(RingElement,DiagonalAction)" -- see isInvariant,
    -- check whether a polynomial is invariant under a group
    action
  * "net(DiagonalAction)" -- see net(RingOfInvariants),
    -- format for printing, as a net
  * numgens(DiagonalAction) -- number of
    generators of the finite part of a diagonal group
  * rank(DiagonalAction) -- of a diagonal
    action
  * "reynoldsOperator(RingElement,DiagonalAction)" -- see
    reynoldsOperator, -- the image of a polynomial under the
    Reynolds operator
  * "weights(DiagonalAction)" -- see weights, -- of a diagonal
    action

For the programmer
==================

The object DiagonalAction, is a type (Macaulay2Doc),
with ancestor classes GroupAction, <
HashTable (Macaulay2Doc) < Thing (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in InvariantRing/AbelianGroupsDoc.m2:103:0.

diagonalAction -- diagonal group action via weights
***************************************************

  * Usage:
        diagonalAction(W, R), diagonalAction(W, d, R), diagonalAction(W1, W2, d, R)
  * Inputs:
      * W, a matrix (Macaulay2Doc), of weights of the diagonal
        group action
      * W1, a matrix (Macaulay2Doc), of weights for the torus
        action
      * W2, a matrix (Macaulay2Doc), of weights for the finite
        abelian action
      * d, a list (Macaulay2Doc), of orders of cyclic abelian
        factors in the decomposition of the diagonal group
      * R, a polynomial ring (Macaulay2Doc), on which the
        group acts
  * Outputs:
      * an instance of the type DiagonalAction, the
        diagonal action of the product of a torus with a finite abelian group
        corresponding to the given weight matrices

Description
===========

This function is provided by the package InvariantRing.

Use this function to set up a diagonal action of a group $(k^*)^r \times
\mathbb{Z}/d_1 \times \cdots \times \mathbb{Z}/d_g$  on a polynomial ring  $R =
k[x_1,\ldots,x_n]$ over a field. Saying the action is diagonal means that
$(t_1,\ldots,t_r) \in (k^*)^r$  acts by $$(t_1,\ldots,t_r) \cdot x_j =
t_1^{w_{1,j}}\cdots t_r^{w_{r,j}} x_j$$ for some integers  $w_{i,j}$  and the
generators  $u_1, \dots, u_g$  of the cyclic abelian factors act by $$u_i \cdot
x_j = \zeta_i^{w_{r+i,j}} x_j$$ for  $\zeta_i$  a primitive  $d_i$-th root of
unity. The integers $w_{i,j}$ comprise the weight matrix W. In other words, the
$j$ -th column of W is the weight vector of $x_j$.

The following example defines an action of a two-dimensional torus on a
four-dimensional vector space with a basis of weight vectors whose weights are
the columns of the input matrix.

+---------------------------------------+
|i1 : R = QQ[x_1..x_4]                  |
|                                       |
|o1 = R                                 |
|                                       |
|o1 : PolynomialRing                    |
+---------------------------------------+
|i2 : W = matrix{{0,1,-1,1},{1,0,-1,-1}}|
|                                       |
|o2 = | 0 1 -1 1  |                     |
|     | 1 0 -1 -1 |                     |
|                                       |
|              2       4                |
|o2 : Matrix ZZ  <-- ZZ                 |
+---------------------------------------+
|i3 : T = diagonalAction(W, R)          |
|                                       |
|             * 2                       |
|o3 = R <- (QQ )  via                   |
|                                       |
|     | 0 1 -1 1  |                     |
|     | 1 0 -1 -1 |                     |
|                                       |
|o3 : DiagonalAction                    |
+---------------------------------------+

Here is an example of a product of two cyclic groups of order 3 acting on a
three-dimensional vector space:

+--------------------------------+
|i4 : R = QQ[x_1..x_3]           |
|                                |
|o4 = R                          |
|                                |
|o4 : PolynomialRing             |
+--------------------------------+
|i5 : d = {3,3}                  |
|                                |
|o5 = {3, 3}                     |
|                                |
|o5 : List                       |
+--------------------------------+
|i6 : W = matrix{{1,0,1},{0,1,1}}|
|                                |
|o6 = | 1 0 1 |                  |
|     | 0 1 1 |                  |
|                                |
|              2       3         |
|o6 : Matrix ZZ  <-- ZZ          |
+--------------------------------+
|i7 : A = diagonalAction(W, d, R)|
|                                |
|o7 = R <- ZZ/3 x ZZ/3 via       |
|                                |
|     | 1 0 1 |                  |
|     | 0 1 1 |                  |
|                                |
|o7 : DiagonalAction             |
+--------------------------------+

Ways to use diagonalAction:
===========================

  * "diagonalAction(Matrix,List,PolynomialRing)"
  * "diagonalAction(Matrix,Matrix,List,PolynomialRing)"
  * "diagonalAction(Matrix,PolynomialRing)"

For the programmer
==================

The object diagonalAction, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in InvariantRing/AbelianGroupsDoc.m2:88:0.

dim(GroupAction) -- dimension of the polynomial ring being acted upon
*********************************************************************

  * Function: dim (Macaulay2Doc),
  * Usage:
        dim G
  * Inputs:
      * G, an instance of the type GroupAction, a group
        action on a polynomial ring
  * Outputs:
      * an integer (Macaulay2Doc), the dimension of the polynomial
        ring being acted upon

Description
===========

This function is provided by the package InvariantRing.

+-----------------------------------------------------------+
|i1 : R = QQ[x_1..x_4]                                      |
|                                                           |
|o1 = R                                                     |
|                                                           |
|o1 : PolynomialRing                                        |
+-----------------------------------------------------------+
|i2 : T = diagonalAction(matrix {{0,1,-1,1},{1,0,-1,-1}}, R)|
|                                                           |
|             * 2                                           |
|o2 = R <- (QQ )  via                                       |
|                                                           |
|     | 0 1 -1 1  |                                         |
|     | 1 0 -1 -1 |                                         |
|                                                           |
|o2 : DiagonalAction                                        |
+-----------------------------------------------------------+
|i3 : dim T == dim R                                        |
|                                                           |
|o3 = true                                                  |
+-----------------------------------------------------------+

Ways to use this method:
========================

  * dim(GroupAction) -- dimension of the
    polynomial ring being acted upon
-------------------------------------------------------------------------------

The source of this document is in InvariantRing/InvariantRingDoc.m2:97:0.

equivariantHilbert -- stores equivariant Hilbert series expansions
******************************************************************

Description
===========

This key is created in the cache table of a DiagonalAction,
upon calling equivariantHilbertSeries,
with the Order (Macaulay2Doc), option. It
stores partial expansions of the equivariant Hilbert series to avoid computing
them again.

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x_1..x_3]                                                        |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : W = matrix{{-1,0,1},{0,-1,1}}                                           |
|                                                                             |
|o2 = | -1 0  1 |                                                             |
|     | 0  -1 1 |                                                             |
|                                                                             |
|              2       3                                                      |
|o2 : Matrix ZZ  <-- ZZ                                                       |
+-----------------------------------------------------------------------------+
|i3 : T = diagonalAction(W, R)                                                |
|                                                                             |
|             * 2                                                             |
|o3 = R <- (QQ )  via                                                         |
|                                                                             |
|     | -1 0  1 |                                                             |
|     | 0  -1 1 |                                                             |
|                                                                             |
|o3 : DiagonalAction                                                          |
+-----------------------------------------------------------------------------+
|i4 : T.cache.?equivariantHilbert                                             |
|                                                                             |
|o4 = false                                                                   |
+-----------------------------------------------------------------------------+
|i5 : elapsedTime equivariantHilbertSeries(T, Order => 5)                     |
| -- .00337909s elapsed                                                       |
|                                                                             |
|                  -1    -1       2 2              -2    -1 -1    -2  2       |
|o5 = 1 + (z z  + z   + z  )T + (z z  + z  + z  + z   + z  z   + z  )T  +     |
|           0 1    1     0        0 1    0    1    1     0  1     0           |
|     ------------------------------------------------------------------------|
|       3 3    2        2      -1        -3    -1      -1 -2    -2 -1    -3  3|
|     (z z  + z z  + z z  + z z   + 1 + z   + z  z  + z  z   + z  z   + z  )T |
|       0 1    0 1    0 1    0 1         1     0  1    0  1     0  1     0    |
|     ------------------------------------------------------------------------|
|         4 4    3 2    2 3    2             -2    2    -1    -4    -1        |
|     + (z z  + z z  + z z  + z  + z z  + z z   + z  + z   + z   + z   +      |
|         0 1    0 1    0 1    0    0 1    0 1     1    1     1     0         |
|     ------------------------------------------------------------------------|
|      -1 -3    -2      -2 -2    -3 -1    -4  4                               |
|     z  z   + z  z  + z  z   + z  z   + z  )T                                |
|      0  1     0  1    0  1     0  1     0                                   |
|                                                                             |
|o5 : ZZ[z ..z ][T]                                                           |
|         0   1                                                               |
+-----------------------------------------------------------------------------+
|i6 : T.cache.?equivariantHilbert                                             |
|                                                                             |
|o6 = true                                                                    |
+-----------------------------------------------------------------------------+
|i7 : elapsedTime equivariantHilbertSeries(T, Order => 5);                    |
| -- .000640339s elapsed                                                      |
+-----------------------------------------------------------------------------+

For the programmer
==================

The object equivariantHilbert, is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in InvariantRing/AbelianGroupsDoc.m2:185:0.

equivariantHilbertSeries -- equivariant Hilbert series for a diagonal action
****************************************************************************

  * Usage:
        equivariantHilbertSeries D
  * Inputs:
      * D, an instance of the type DiagonalAction,
  * Optional inputs (Macaulay2Doc),:
      * Order (missing documentation) => an integer (Macaulay2Doc),
        default value infinity, stopping degree of the equivariant Hilbert
        series
  * Outputs:
      * a divide expression (Macaulay2Doc), the equivariant
        Hilbert series

Description
===========

This function is provided by the package InvariantRing.

For a torus acting on the vector space $V$ this function returns the
equivariant Hilbert series of the coordinate ring $K[V]$ as a rational function
of $z_0, \ldots, z_{r-1}, t$ where $r$ is the rank of the torus. The series in
$t$ which is the coefficient of $z_0^0\cdots z_{r-1}^0$ gives the ordinary
Hilbert series of $K[V]^T$ . The option Order => N can be used to compute the
series up to the  $t$ -degree N-1.

Here is an example of a rank 2 torus acting on a polynomial ring in 3
variables, whose invariant ring is generated by the single element $x_1 x_2
x_3$ .

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x_1..x_3]                                                        |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : W = matrix{{-1,0,1},{0,-1,1}}                                           |
|                                                                             |
|o2 = | -1 0  1 |                                                             |
|     | 0  -1 1 |                                                             |
|                                                                             |
|              2       3                                                      |
|o2 : Matrix ZZ  <-- ZZ                                                       |
+-----------------------------------------------------------------------------+
|i3 : T = diagonalAction(W, R)                                                |
|                                                                             |
|             * 2                                                             |
|o3 = R <- (QQ )  via                                                         |
|                                                                             |
|     | -1 0  1 |                                                             |
|     | 0  -1 1 |                                                             |
|                                                                             |
|o3 : DiagonalAction                                                          |
+-----------------------------------------------------------------------------+
|i4 : equivariantHilbertSeries T                                              |
|                                                                             |
|                    1                                                        |
|o4 = -------------------------------                                         |
|           -1        -1                                                      |
|     (1 - z  T)(1 - z  T)(1 - z z T)                                         |
|           0         1         0 1                                           |
|                                                                             |
|o4 : Expression of class Divide                                              |
+-----------------------------------------------------------------------------+
|i5 : S = equivariantHilbertSeries(T, Order => 7)                             |
|                                                                             |
|                  -1    -1       2 2              -2    -1 -1    -2  2       |
|o5 = 1 + (z z  + z   + z  )T + (z z  + z  + z  + z   + z  z   + z  )T  +     |
|           0 1    1     0        0 1    0    1    1     0  1     0           |
|     ------------------------------------------------------------------------|
|       3 3    2        2      -1        -3    -1      -1 -2    -2 -1    -3  3|
|     (z z  + z z  + z z  + z z   + 1 + z   + z  z  + z  z   + z  z   + z  )T |
|       0 1    0 1    0 1    0 1         1     0  1    0  1     0  1     0    |
|     ------------------------------------------------------------------------|
|         4 4    3 2    2 3    2             -2    2    -1    -4    -1        |
|     + (z z  + z z  + z z  + z  + z z  + z z   + z  + z   + z   + z   +      |
|         0 1    0 1    0 1    0    0 1    0 1     1    1     1     0         |
|     ------------------------------------------------------------------------|
|      -1 -3    -2      -2 -2    -3 -1    -4  4     5 5    4 3    3 4    3    |
|     z  z   + z  z  + z  z   + z  z   + z  )T  + (z z  + z z  + z z  + z z  +|
|      0  1     0  1    0  1     0  1     0         0 1    0 1    0 1    0 1  |
|     ------------------------------------------------------------------------|
|      2 2    2 -1      3           -3         -2    -5    -1 2    -1 -1      |
|     z z  + z z   + z z  + z  + z z   + z  + z   + z   + z  z  + z  z   +    |
|      0 1    0 1     0 1    0    0 1     1    1     1     0  1    0  1       |
|     ------------------------------------------------------------------------|
|      -1 -4    -2    -2 -3    -3      -3 -2    -4 -1    -5  5     6 6    5 4 |
|     z  z   + z   + z  z   + z  z  + z  z   + z  z   + z  )T  + (z z  + z z  |
|      0  1     0     0  1     0  1    0  1     0  1     0         0 1    0 1 |
|     ------------------------------------------------------------------------|
|        4 5    4 2    3 3    3    2 4    2      2 -2      2      -1      -4  |
|     + z z  + z z  + z z  + z  + z z  + z z  + z z   + z z  + z z   + z z   +|
|        0 1    0 1    0 1    0    0 1    0 1    0 1     0 1    0 1     0 1   |
|     ------------------------------------------------------------------------|
|      3        -3    -6    -1      -1 -2    -1 -5    -2 2    -2 -1    -2 -4  |
|     z  + 1 + z   + z   + z  z  + z  z   + z  z   + z  z  + z  z   + z  z   +|
|      1        1     1     0  1    0  1     0  1     0  1    0  1     0  1   |
|     ------------------------------------------------------------------------|
|      -3    -3 -3    -4      -4 -2    -5 -1    -6  6                         |
|     z   + z  z   + z  z  + z  z   + z  z   + z  )T                          |
|      0     0  1     0  1    0  1     0  1     0                             |
|                                                                             |
|o5 : ZZ[z ..z ][T]                                                           |
|         0   1                                                               |
+-----------------------------------------------------------------------------+
|i6 : sub(S, {z_0 => 0, z_1 => 0})                                            |
|                                                                             |
|          3    6                                                             |
|o6 = 1 + T  + T                                                              |
|                                                                             |
|o6 : ZZ[z ..z ][T]                                                           |
|         0   1                                                               |
+-----------------------------------------------------------------------------+

Ways to use equivariantHilbertSeries:
=====================================

  * "equivariantHilbertSeries(DiagonalAction)"

For the programmer
==================

The object equivariantHilbertSeries, is a
method function with options (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in InvariantRing/AbelianGroupsDoc.m2:160:0.

finiteAction -- the group action generated by a list of matrices
****************************************************************

  * Usage:
        finiteAction(L, R), finiteAction(M, R)
  * Inputs:
      * L, a list (Macaulay2Doc), of matrices representing the
        generators of a finite group
      * M, a matrix (Macaulay2Doc), generating a finite cyclic
        group of matrices
      * R, a polynomial ring (Macaulay2Doc), on which the
        group elements act by linear changes of coordinates
  * Outputs:
      * an instance of the type FiniteGroupAction,
        the action of the (finite) matrix group generated by the input matrices
        on the given polynomial ring

Description
===========

This function is provided by the package InvariantRing.

The following example defines the permutation action of a symmetric group on
three elements.

+--------------------------------------------------------------+
|i1 : R = QQ[x_1..x_3]                                         |
|                                                              |
|o1 = R                                                        |
|                                                              |
|o1 : PolynomialRing                                           |
+--------------------------------------------------------------+
|i2 : L = apply(2, i -> permutationMatrix(3, [i + 1, i + 2] ) )|
|                                                              |
|o2 = {| 0 1 0 |, | 1 0 0 |}                                   |
|      | 1 0 0 |  | 0 0 1 |                                    |
|      | 0 0 1 |  | 0 1 0 |                                    |
|                                                              |
|o2 : List                                                     |
+--------------------------------------------------------------+
|i3 : S3 = finiteAction(L, R)                                  |
|                                                              |
|o3 = R <- {| 0 1 0 |, | 1 0 0 |}                              |
|           | 1 0 0 |  | 0 0 1 |                               |
|           | 0 0 1 |  | 0 1 0 |                               |
|                                                              |
|o3 : FiniteGroupAction                                        |
+--------------------------------------------------------------+

On the other hand, the action below corresponds to a cyclic permutation of the
variables.

+---------------------------------------+
|i4 : P = permutationMatrix toString 231|
|                                       |
|o4 = | 0 0 1 |                         |
|     | 1 0 0 |                         |
|     | 0 1 0 |                         |
|                                       |
|              3       3                |
|o4 : Matrix ZZ  <-- ZZ                 |
+---------------------------------------+
|i5 : C3 = finiteAction(P, R)           |
|                                       |
|o5 = R <- {| 0 0 1 |}                  |
|           | 1 0 0 |                   |
|           | 0 1 0 |                   |
|                                       |
|o5 : FiniteGroupAction                 |
+---------------------------------------+

Ways to use finiteAction:
=========================

  * "finiteAction(List,PolynomialRing)"
  * "finiteAction(Matrix,PolynomialRing)"

For the programmer
==================

The object finiteAction, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in InvariantRing/FiniteGroupsDoc.m2:54:0.

FiniteGroupAction -- the class of all finite group actions
**********************************************************

Description
===========

This class is provided by the package InvariantRing.

FiniteGroupAction is the class of all finite matrix group actions on polynomial
rings for the purpose of computing invariants. It is created using
finiteAction. Note that diagonal actions of finite abelian
groups can be created with the class DiagonalAction,
which implements more efficient methods for computing invariants.

Functions and methods returning an object of class FiniteGroupAction:
=====================================================================

  * "finiteAction(List,PolynomialRing)" -- see finiteAction,
    -- the group action generated by a list of matrices
  * "finiteAction(Matrix,PolynomialRing)" -- see finiteAction,
    -- the group action generated by a list of matrices

Methods that use an object of class FiniteGroupAction:
======================================================

  * generators(FiniteGroupAction), --
    generators of a finite group
  * "group(FiniteGroupAction)" -- see group, -- list all elements
    of the group of a finite group action
  * "hironakaDecomposition(FiniteGroupAction)" -- see
    hironakaDecomposition, -- calculates a Hironaka
    decomposition for the invariant ring of a finite group
  * invariants(FiniteGroupAction), --
    computes the generating invariants of a group action
  * "invariants(FiniteGroupAction,List)" -- see
    invariants(FiniteGroupAction,ZZ),
    -- basis for graded component of invariant ring
  * invariants(FiniteGroupAction,ZZ)
    -- basis for graded component of
    invariant ring
  * "isAbelian(FiniteGroupAction)" -- see isAbelian, -- check
    whether a finite matrix group is Abelian
  * "isInvariant(RingElement,FiniteGroupAction)" -- see isInvariant,
    -- check whether a polynomial is invariant under a group
    action
  * "molienSeries(FiniteGroupAction)" -- see molienSeries,
    -- computes the Molien (Hilbert) series of the invariant ring of a finite
    group
  * "net(FiniteGroupAction)" -- see net(RingOfInvariants),
    -- format for printing, as a net
  * numgens(FiniteGroupAction) -- number
    of generators of a finite group
  * "primaryInvariants(FiniteGroupAction)" -- see primaryInvariants,
    -- computes a list of primary invariants for the
    invariant ring of a finite group
  * relations(FiniteGroupAction), --
    relations of a finite group
  * "reynoldsOperator(RingElement,FiniteGroupAction)" -- see
    reynoldsOperator, -- the image of a polynomial under the
    Reynolds operator
  * "schreierGraph(FiniteGroupAction)" -- see schreierGraph,
    -- Schreier graph of a finite group
  * "secondaryInvariants(List,FiniteGroupAction)" -- see
    secondaryInvariants, -- computes secondary invariants
    for the invariant ring of a finite group
  * "words(FiniteGroupAction)" -- see words, -- associate a word
    in the generators of a group to each element

For the programmer
==================

The object FiniteGroupAction, is a type (Macaulay2Doc),
with ancestor classes GroupAction, <
HashTable (Macaulay2Doc) < Thing (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in InvariantRing/FiniteGroupsDoc.m2:73:0.

generators(FiniteGroupAction) -- generators of a finite group
*************************************************************

  * Function: generators (Macaulay2Doc),
  * Usage:
        generators G
  * Inputs:
      * G, an instance of the type FiniteGroupAction,
        the action of a finite group
  * Optional inputs (Macaulay2Doc),:
      * CoefficientRing (Macaulay2Doc), => ...,
        default value null,
  * Outputs:
      * a list (Macaulay2Doc), a list of generators of the group

Description
===========

This function is provided by the package InvariantRing.

Use this function to get the user-defined generators of a group action.

The following example defines the permutation action of a symmetric group on
three elements using three transpositions.

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x_1..x_3]                                                        |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : L = {matrix {{0,1,0},{1,0,0},{0,0,1}}, matrix {{0,0,1},{0,1,0},{1,0,0}},|
|                                                                             |
|o2 = {| 0 1 0 |, | 0 0 1 |, | 1 0 0 |}                                       |
|      | 1 0 0 |  | 0 1 0 |  | 0 0 1 |                                        |
|      | 0 0 1 |  | 1 0 0 |  | 0 1 0 |                                        |
|                                                                             |
|o2 : List                                                                    |
|-----------------------------------------------------------------------------|
|matrix {{1,0,0},{0,0,1},{0,1,0}} }                                           |
+-----------------------------------------------------------------------------+
|i3 : G = finiteAction(L, R)                                                  |
|                                                                             |
|o3 = R <- {| 0 1 0 |, | 0 0 1 |, | 1 0 0 |}                                  |
|           | 1 0 0 |  | 0 1 0 |  | 0 0 1 |                                   |
|           | 0 0 1 |  | 1 0 0 |  | 0 1 0 |                                   |
|                                                                             |
|o3 : FiniteGroupAction                                                       |
+-----------------------------------------------------------------------------+
|i4 : generators G                                                            |
|                                                                             |
|o4 = {| 0 1 0 |, | 0 0 1 |, | 1 0 0 |}                                       |
|      | 1 0 0 |  | 0 1 0 |  | 0 0 1 |                                        |
|      | 0 0 1 |  | 1 0 0 |  | 0 1 0 |                                        |
|                                                                             |
|o4 : List                                                                    |
+-----------------------------------------------------------------------------+

Ways to use this method:
========================

  * generators(FiniteGroupAction), --
    generators of a finite group
-------------------------------------------------------------------------------

The source of this document is in InvariantRing/FiniteGroupsDoc.m2:104:0.

generators(RingOfInvariants) -- the generators for a ring of invariants
***********************************************************************

  * Function: generators (Macaulay2Doc),
  * Usage:
        generators S, gens S
  * Inputs:
      * S, an instance of the type RingOfInvariants,
  * Optional inputs (Macaulay2Doc),:
      * CoefficientRing (Macaulay2Doc), => ...,
        default value null,
  * Outputs:
      * a list (Macaulay2Doc), of algebra generators for the ring
        of invariants

Description
===========

This function is provided by the package InvariantRing.

This method gets the algebra generators for a ring of invariants.

+---------------------------------------+
|i1 : R = QQ[x_1..x_4]                  |
|                                       |
|o1 = R                                 |
|                                       |
|o1 : PolynomialRing                    |
+---------------------------------------+
|i2 : W = matrix{{0,1,-1,1},{1,0,-1,-1}}|
|                                       |
|o2 = | 0 1 -1 1  |                     |
|     | 1 0 -1 -1 |                     |
|                                       |
|              2       4                |
|o2 : Matrix ZZ  <-- ZZ                 |
+---------------------------------------+
|i3 : T = diagonalAction(W, R)          |
|                                       |
|             * 2                       |
|o3 = R <- (QQ )  via                   |
|                                       |
|     | 0 1 -1 1  |                     |
|     | 1 0 -1 -1 |                     |
|                                       |
|o3 : DiagonalAction                    |
+---------------------------------------+
|i4 : S = R^T                           |
|                                       |
|o4 =             2                     |
|     QQ[x x x , x x x ]                |
|         1 2 3   1 3 4                 |
|                                       |
|o4 : RingOfInvariants                  |
+---------------------------------------+
|i5 : gens S                            |
|                                       |
|               2                       |
|o5 = {x x x , x x x }                  |
|       1 2 3   1 3 4                   |
|                                       |
|o5 : List                              |
+---------------------------------------+

Ways to use this method:
========================

  * generators(RingOfInvariants), --
    the generators for a ring of invariants
-------------------------------------------------------------------------------

The source of this document is in InvariantRing/InvariantsDoc.m2:71:0.

group -- list all elements of the group of a finite group action
****************************************************************

  * Usage:
        group G
  * Inputs:
      * G, an instance of the type FiniteGroupAction,
  * Outputs:
      * a list (Macaulay2Doc), of all elements in the finite matrix
        group associated to the given group action

Description
===========

This function is provided by the package InvariantRing.

The following example defines the permutation action of a symmetric group on
three elements.

+-----------------------------------------------------------------------+
|i1 : R = QQ[x_1..x_3]                                                  |
|                                                                       |
|o1 = R                                                                 |
|                                                                       |
|o1 : PolynomialRing                                                    |
+-----------------------------------------------------------------------+
|i2 : L = apply(2, i -> permutationMatrix(3, [i + 1, i + 2] ) )         |
|                                                                       |
|o2 = {| 0 1 0 |, | 1 0 0 |}                                            |
|      | 1 0 0 |  | 0 0 1 |                                             |
|      | 0 0 1 |  | 0 1 0 |                                             |
|                                                                       |
|o2 : List                                                              |
+-----------------------------------------------------------------------+
|i3 : S3 = finiteAction(L, R)                                           |
|                                                                       |
|o3 = R <- {| 0 1 0 |, | 1 0 0 |}                                       |
|           | 1 0 0 |  | 0 0 1 |                                        |
|           | 0 0 1 |  | 0 1 0 |                                        |
|                                                                       |
|o3 : FiniteGroupAction                                                 |
+-----------------------------------------------------------------------+
|i4 : group S3                                                          |
|                                                                       |
|o4 = {| 1 0 0 |, | 0 1 0 |, | 1 0 0 |, | 0 0 1 |, | 0 1 0 |, | 0 0 1 |}|
|      | 0 0 1 |  | 1 0 0 |  | 0 1 0 |  | 0 1 0 |  | 0 0 1 |  | 1 0 0 | |
|      | 0 1 0 |  | 0 0 1 |  | 0 0 1 |  | 1 0 0 |  | 1 0 0 |  | 0 1 0 | |
|                                                                       |
|o4 : List                                                              |
+-----------------------------------------------------------------------+

The computation of all elements in the group is actually performed by the
method schreierGraph, since the process of computing the
Schreier graph of the group yields other useful information about the group
besides just its elements.

See also
========

  * schreierGraph -- Schreier graph of a finite group
  * words -- associate a word in the generators of a group to
    each element

Ways to use group:
==================

  * "group(FiniteGroupAction)"

For the programmer
==================

The object group, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in InvariantRing/FiniteGroupsDoc.m2:140:0.

GroupAction -- the class of all group actions
*********************************************

Description
===========

This class is provided by the package InvariantRing.

GroupAction is the class of all group actions on polynomial rings for the
purpose of computing invariants. This is not typically used directly,
delegating creation to the various constructor functions for different kinds of
group actions:

  * FiniteGroupAction, the class of a finite matrix
    group action, is created with finiteAction,
  * DiagonalAction, the class of the diagonal action of
    a product of a torus and a finite abelian group, is created with
    diagonalAction,
  * LinearlyReductiveAction, the class of a
    linearly reductive matrix group action, is created with
    linearlyReductiveAction,

Each class implements different algorithms to compute invariants. Although
mathematically speaking all the above group actions are linearly reductive (at
least in the non modular case), the class LinearlyReductiveAction,
should be used only when none of the other classes
apply because it has fewer and possibly less efficient methods.

The class GroupAction is implemented as a HashTable. When created it stores
information such as the action (in a format dependent upon the group) and the
polynomial ring being acted upon.

Types of GroupAction:
=====================

  * DiagonalAction -- the class of all diagonal actions
  * FiniteGroupAction -- the class of all finite
    group actions
  * LinearlyReductiveAction -- the class of all
    (non finite, non toric) linearly reductive group actions

Functions and methods returning an object of class GroupAction:
===============================================================

  * "action(RingOfInvariants)" -- see action, -- the group action
    that produced a ring of invariants

Methods that use an object of class GroupAction:
================================================

  * dim(GroupAction) -- dimension of the
    polynomial ring being acted upon
  * "invariantRing(GroupAction)" -- see invariantRing, --
    the ring of invariants of a group action
  * "PolynomialRing ^ GroupAction" -- see invariantRing,
    -- the ring of invariants of a group action
  * ring(GroupAction) -- the polynomial ring
    being acted upon

For the programmer
==================

The object GroupAction, is a type (Macaulay2Doc),
with ancestor classes HashTable (Macaulay2Doc),
< Thing (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in InvariantRing/InvariantRingDoc.m2:144:0.

groupIdeal -- ideal defining a linearly reductive group
*******************************************************

  * Usage:
        groupIdeal L
  * Inputs:
      * L, an instance of the type LinearlyReductiveAction,
        of a group with coordinate ring S/I
  * Outputs:
      * an ideal (Macaulay2Doc), I

Description
===========

This function is provided by the package InvariantRing.

Suppose the action L consists of the linearly reductive group with coordinate
ring S/I (where S is a polynomial ring) acting on a (quotient of) a polynomial
ring R via the action matrix M. This function returns the ideal I.

+------------------------------------------------------+
|i1 : S = QQ[z]                                        |
|                                                      |
|o1 = S                                                |
|                                                      |
|o1 : PolynomialRing                                   |
+------------------------------------------------------+
|i2 : I = ideal(z^2 - 1)                               |
|                                                      |
|            2                                         |
|o2 = ideal(z  - 1)                                    |
|                                                      |
|o2 : Ideal of S                                       |
+------------------------------------------------------+
|i3 : M = matrix{{(z+1)/2, (1-z)/2},{(1-z)/2, (z+1)/2}}|
|                                                      |
|o3 = | 1/2z+1/2  -1/2z+1/2 |                          |
|     | -1/2z+1/2 1/2z+1/2  |                          |
|                                                      |
|             2      2                                 |
|o3 : Matrix S  <-- S                                  |
+------------------------------------------------------+
|i4 : R = QQ[x,y]                                      |
|                                                      |
|o4 = R                                                |
|                                                      |
|o4 : PolynomialRing                                   |
+------------------------------------------------------+
|i5 : L = linearlyReductiveAction(I, M, R)             |
|                                                      |
|                   2                                  |
|o5 = R <- S/ideal(z  - 1) via                         |
|                                                      |
|     | 1/2z+1/2  -1/2z+1/2 |                          |
|     | -1/2z+1/2 1/2z+1/2  |                          |
|                                                      |
|o5 : LinearlyReductiveAction                          |
+------------------------------------------------------+
|i6 : groupIdeal L                                     |
|                                                      |
|            2                                         |
|o6 = ideal(z  - 1)                                    |
|                                                      |
|o6 : Ideal of S                                       |
+------------------------------------------------------+

Ways to use groupIdeal:
=======================

  * "groupIdeal(LinearlyReductiveAction)"

For the programmer
==================

The object groupIdeal, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in
InvariantRing/LinearlyReductiveGroupsDoc.m2:83:0.

hilbertIdeal -- compute generators for the Hilbert ideal
********************************************************

  * Usage:
        hilbertIdeal L
  * Inputs:
      * L, an instance of the type LinearlyReductiveAction,
  * Optional inputs (Macaulay2Doc),:
      * DegreeLimit,
        => ..., default value {}, GB option for invariants
      * SubringLimit,
        => ..., default value infinity, GB option for invariants
  * Outputs:
      * an ideal (Macaulay2Doc), the ideal generated by all ring
        elements invariant under the action

Description
===========

This function is provided by the package InvariantRing.

This function computes the Hilbert ideal for the action of a linearly reductive
group on a (quotient of a) polynomial ring, i.e., the ideal generated by all
ring elements of positive degree invariant under the action. The algorithm is
based on:

  * Derksen, H. & Kemper, G. (2015). Computational Invariant Theory.
    Heidelberg: Springer. pp 159-164

The next example constructs a cyclic group of order 2 as a set of two affine
points. Then it introduces an action of this group on a polynomial ring in two
variables and computes the Hilbert ideal. The action permutes the variables of
the polynomial ring. Note that the generators of the Hilbert ideal need not be
invariant.

+------------------------------------------------------+
|i1 : S = QQ[z]                                        |
|                                                      |
|o1 = S                                                |
|                                                      |
|o1 : PolynomialRing                                   |
+------------------------------------------------------+
|i2 : I = ideal(z^2 - 1)                               |
|                                                      |
|            2                                         |
|o2 = ideal(z  - 1)                                    |
|                                                      |
|o2 : Ideal of S                                       |
+------------------------------------------------------+
|i3 : M = matrix{{(z+1)/2, (1-z)/2},{(1-z)/2, (z+1)/2}}|
|                                                      |
|o3 = | 1/2z+1/2  -1/2z+1/2 |                          |
|     | -1/2z+1/2 1/2z+1/2  |                          |
|                                                      |
|             2      2                                 |
|o3 : Matrix S  <-- S                                  |
+------------------------------------------------------+
|i4 : sub(M,z=>1),sub(M,z=>-1)                         |
|                                                      |
|o4 = (| 1 0 |, | 0 1 |)                               |
|      | 0 1 |  | 1 0 |                                |
|                                                      |
|o4 : Sequence                                         |
+------------------------------------------------------+
|i5 : R = QQ[x,y]                                      |
|                                                      |
|o5 = R                                                |
|                                                      |
|o5 : PolynomialRing                                   |
+------------------------------------------------------+
|i6 : L = linearlyReductiveAction(I, M, R)             |
|                                                      |
|                   2                                  |
|o6 = R <- S/ideal(z  - 1) via                         |
|                                                      |
|     | 1/2z+1/2  -1/2z+1/2 |                          |
|     | -1/2z+1/2 1/2z+1/2  |                          |
|                                                      |
|o6 : LinearlyReductiveAction                          |
+------------------------------------------------------+
|i7 : H = hilbertIdeal L                               |
|                                                      |
|                    2                                 |
|o7 = ideal (x + y, y )                                |
|                                                      |
|o7 : Ideal of R                                       |
+------------------------------------------------------+
|i8 : apply(H_*, f -> isInvariant(f,L))                |
|                                                      |
|o8 = {true, false}                                    |
|                                                      |
|o8 : List                                             |
+------------------------------------------------------+

We offer a slight variation on the previous example to illustrate this method
at work on a quotient of a polynomial ring.

+--------------------------------------------------------+
|i9 : S = QQ[z];                                         |
+--------------------------------------------------------+
|i10 : I = ideal(z^2 - 1);                               |
|                                                        |
|o10 : Ideal of S                                        |
+--------------------------------------------------------+
|i11 : M = matrix{{(z+1)/2, (1-z)/2},{(1-z)/2, (z+1)/2}};|
|                                                        |
|              2      2                                  |
|o11 : Matrix S  <-- S                                   |
+--------------------------------------------------------+
|i12 : Q = QQ[x,y] / ideal(x*y)                          |
|                                                        |
|o12 = Q                                                 |
|                                                        |
|o12 : QuotientRing                                      |
+--------------------------------------------------------+
|i13 : L = linearlyReductiveAction(I, M, Q)              |
|                                                        |
|                    2                                   |
|o13 = Q <- S/ideal(z  - 1) via                          |
|                                                        |
|      | 1/2z+1/2  -1/2z+1/2 |                           |
|      | -1/2z+1/2 1/2z+1/2  |                           |
|                                                        |
|o13 : LinearlyReductiveAction                           |
+--------------------------------------------------------+
|i14 : H = hilbertIdeal L                                |
|                                                        |
|o14 = ideal(x + y)                                      |
|                                                        |
|o14 : Ideal of Q                                        |
+--------------------------------------------------------+

The algorithm performs an elimination using Groebner bases. The options
DegreeLimit (Macaulay2Doc), and SubringLimit (Macaulay2Doc),
are standard gb (Macaulay2Doc), options
that can be used to interrupt the computation before it is complete, yielding a
partial list of generators for the Hilbert ideal.

Caveat
======

The generators of the Hilbert ideal computed by this function need not be
invariant.

Ways to use hilbertIdeal:
=========================

  * "hilbertIdeal(LinearlyReductiveAction)"

For the programmer
==================

The object hilbertIdeal, is a method function with options (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in
InvariantRing/LinearlyReductiveGroupsDoc.m2:160:0.

hilbertSeries(RingOfInvariants) -- Hilbert series of the invariant ring
***********************************************************************

  * Function: hilbertSeries (Macaulay2Doc),
  * Usage:
        hilbertSeries S
  * Inputs:
      * S, an instance of the type RingOfInvariants,
  * Optional inputs (Macaulay2Doc),:
      * Order (Macaulay2Doc),
        => ..., default value infinity,
      * Reduce (Macaulay2Doc),
        => ..., default value false,
  * Outputs:
      * a divide expression (Macaulay2Doc), the Hilbert series of
        the invariant ring as a module over the ambient polynomial ring.

Description
===========

This function is provided by the package InvariantRing.

This method computes the Hilbert series of the ring of invariants.

+---------------------------------------+
|i1 : R = QQ[x_1..x_4]                  |
|                                       |
|o1 = R                                 |
|                                       |
|o1 : PolynomialRing                    |
+---------------------------------------+
|i2 : W = matrix{{0,1,-1,1},{1,0,-1,-1}}|
|                                       |
|o2 = | 0 1 -1 1  |                     |
|     | 1 0 -1 -1 |                     |
|                                       |
|              2       4                |
|o2 : Matrix ZZ  <-- ZZ                 |
+---------------------------------------+
|i3 : T = diagonalAction(W, R)          |
|                                       |
|             * 2                       |
|o3 = R <- (QQ )  via                   |
|                                       |
|     | 0 1 -1 1  |                     |
|     | 1 0 -1 -1 |                     |
|                                       |
|o3 : DiagonalAction                    |
+---------------------------------------+
|i4 : S = R^T                           |
|                                       |
|o4 =             2                     |
|     QQ[x x x , x x x ]                |
|         1 2 3   1 3 4                 |
|                                       |
|o4 : RingOfInvariants                  |
+---------------------------------------+
|i5 : hilbertSeries S                   |
|                                       |
|             1                         |
|o5 = ----------------                  |
|           4       3                   |
|     (1 - T )(1 - T )                  |
|                                       |
|o5 : Expression of class Divide        |
+---------------------------------------+

Ways to use this method:
========================

  * hilbertSeries(RingOfInvariants),
    -- Hilbert series of the invariant ring
-------------------------------------------------------------------------------

The source of this document is in InvariantRing/InvariantsDoc.m2:967:0.

hironakaDecomposition -- calculates a Hironaka decomposition for the invariant ring of a finite group
*****************************************************************************************************

  * Usage:
        hironakaDecomposition G
  * Inputs:
      * G, an instance of the type FiniteGroupAction,
  * Optional inputs (Macaulay2Doc),:
      * DegreeVector,
        => ..., default value 0, an optional argument for
        primaryInvariants that finds invariants of certain degrees
      * PrintDegreePolynomial,
        => ..., default value false, an optional argument for
        secondaryInvariants that determines the printing of an informative
        polynomial
  * Outputs:
      * a sequence (Macaulay2Doc), (P,S), where P is a
        List (Macaulay2Doc), of primary invariants (i.e. a homogeneous
        system of parameters for the invariant ring) and S is a List (Macaulay2Doc),
        of corresponding secondary invariants

Description
===========

This function is provided by the package InvariantRing.

See hironakaDecomposition,  makes use of the functions

See primaryInvariants, and secondaryInvariants,
in order to compute a Hironaka decomposition of the

invariant ring of a finite group G acting on a polynomial ring R. It outputs a

sequence ({f ,...,f }, {g ,...,g }) of primary and secondary invariants such
            1      n     1      r
      G
that R =Ag \oplus...\oplusAg , where A=K[f ,...,f ] and K is the field of
          1                 r             1      n
coefficients of R.

All of the optional arguments of hironakaDecomposition,
play the same role as for the functions
primaryInvariants, and secondaryInvariants.
By default, the function hironakaDecomposition,
calls upon primaryInvariants,
with the optional argument Dade,
set to false (Macaulay2Doc),
to compute a set of primary invariants, resulting in
Kemper's 'optimal' algorithm being used (see hsop algorithms,
for more information).

The example below computes a set of primary and secondary invariants for an
action of the cyclic group of order 4 on QQ[x,y].

+----------------------------------------------------+
|i1 : C4=finiteAction({matrix{{0,-1},{1,0}}},QQ[x,y])|
|                                                    |
|o1 = QQ[x..y] <- {| 0 -1 |}                         |
|                  | 1 0  |                          |
|                                                    |
|o1 : FiniteGroupAction                              |
+----------------------------------------------------+
|i2 : hironakaDecomposition C4                       |
|                                                    |
|        2    2   2 2        3       3               |
|o2 = ({x  + y , x y }, {1, x y - x*y })             |
|                                                    |
|o2 : Sequence                                       |
+----------------------------------------------------+

                                     C4                         4  4
From the output one sees that QQ[x,y]  =QQ[f f ]\oplusQQ[f f ](x +y ), where
                                            1 2           1 2
    2  2          3  3
f =x +y  and f =xy -x y.
 1            2

Caveat
======

Currently hironakaDecomposition works only with polynomial rings and matrices
over fields of characteristic 0.

See also
========

  * hsop algorithms -- an overview of the algorithms
    used in primaryInvariants

Ways to use hironakaDecomposition:
==================================

  * "hironakaDecomposition(FiniteGroupAction)"

For the programmer
==================

The object hironakaDecomposition, is a
method function with options (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in InvariantRing/HawesDoc.m2:78:0.

hsop algorithms -- an overview of the algorithms used in primaryInvariants
**************************************************************************

This page contains a discussion on the two algorithms that are used in the

function primaryInvariants, which computes a

                                                                              G
homogeneous system of parameters (hsop) for the invariant ring R:=K[x ,...,x ]
                                                                     1      n
of a finite group G. Which algorithm is used depends on the Boolean (Macaulay2Doc),
value the optional argument Dade,
takes. In the case where it
is set to false (Macaulay2Doc), it uses what shall be referred to
as the 'default' algorithm. If it is set to true (Macaulay2Doc),
then it uses what shall be called the 'Dade' algorithm.

The default algorithm is an implementation of the 'optimal' algorithm given in

[K]. It is optimal in the sense that it finds a hsop f ,...,f  such that the
                                                      1      n

number of secondary invariants required to make R into a free

K[f ,...,f ]-module is minimal. The first step in the default algorithm is to
   1      n

cycle through the List (Macaulay2Doc), s={d ,...,d } of possible
                                                      1      n

degrees for the hsop. It tests the degrees against two restrictions that are

known to hold for any hsop of R: firstly, the order of G must divide the

                                                          d1          dn
product d *...*d  and secondly, the polynomial H(R,T)*(1-T  )*...*(1-T  ) must
         1      n
lie in ZZ (Macaulay2Doc),[T], where H(R,T) is the Molien (Hilbert)
series of R [DK, p83]. Once a List (Macaulay2Doc), of suitable
degrees is found, the algorithm uses a Krull-dimension based test that holds
for algebras over infinite fields to determine the existence of a hsop with the
candidate degrees; see [K, Theorem 2]. It then finds such a hsop if one exists,
or tries a new List (Macaulay2Doc), of degrees if such a hsop does
not exist. Note: if one knows a priori that a hsop exists for some List (Macaulay2Doc),
of degrees, this can be assigned to the optional argument
DegreeVector,
and the default algorithm will compute a hsop with degrees corresponding to
this List (Macaulay2Doc). Finally, users should be aware that the
default algorithm currently only works in the case where R is defined over a
field of characteristic zero.

The Dade algorithm is simpler than the default algorithm. It first constructs a

                                         *
Dade basis v ,...,v  for the dual space V  spanned by x ,...,x . Then for each
            1      n                                   1      n

i, it computes the polynomial f  defined as the product over the G-orbit of v .
                               i                                             i

The resulting collection f ,...,f  is a hsop for R; see [DK, pp80,81]. In the
                          1      n

implemented Dade algorithm, a Dade basis is constructed iteratively by choosing

See random (Macaulay2Doc), linear forms such that v  is not contained
                                                            i

in any of the vector subspaces span {w ,...,w   }, where w  is in the G-orbit
                                   K  1      i-1          j

of v . The Dade algorithm can work with the case of finite fields, provided
    j
                                          n
that the field is large enough to ensure K  cannot be filled by the union of

the subspaces mentioned in the construction of the Dade basis. A sufficient,
                                                           n-1
though not necessarily optimal, requirement is that |K|>|G|   . Because of the
random generation involved in the construction of a Dade basis, the Dade
algorithm will generally output n primary invariants of degrees equalling the
order of G that have ugly coefficients.

The example below provides a good comparison of the two different algorithms
and their relative merits.

+------------------------------------------+
|i1 : A=matrix{{0,-1,0},{1,0,0},{0,0,-1}}  |
|                                          |
|o1 = | 0 -1 0  |                          |
|     | 1 0  0  |                          |
|     | 0 0  -1 |                          |
|                                          |
|              3       3                   |
|o1 : Matrix ZZ  <-- ZZ                    |
+------------------------------------------+
|i2 : B=matrix{{0,-1,0},{1,0,0},{0,0,1}}   |
|                                          |
|o2 = | 0 -1 0 |                           |
|     | 1 0  0 |                           |
|     | 0 0  1 |                           |
|                                          |
|              3       3                   |
|o2 : Matrix ZZ  <-- ZZ                    |
+------------------------------------------+
|i3 : C4xC2=finiteAction({A,B},QQ[x,y,z])  |
|                                          |
|o3 = QQ[x..z] <- {| 0 -1 0  |, | 0 -1 0 |}|
|                  | 1 0  0  |  | 1 0  0 | |
|                  | 0 0  -1 |  | 0 0  1 | |
|                                          |
|o3 : FiniteGroupAction                    |
+------------------------------------------+

The two algorithms used in primaryInvariants, are
timed. One sees that the Dade algorithm is faster, however the primary
invariants output are all of degree 8 and have ugly coefficients.

+-----------------------------------------------------------------------------+
|i4 : time P1=primaryInvariants C4xC2                                         |
| -- used 0.917706s (cpu); 0.705165s (thread); 0s (gc)                        |
|                                                                             |
|       2   2    2   4    4                                                   |
|o4 = {z , x  + y , x  + y }                                                  |
|                                                                             |
|o4 : List                                                                    |
+-----------------------------------------------------------------------------+
|i5 : time P2=primaryInvariants(C4xC2,Dade=>true)                             |
| -- used 0.63393s (cpu); 0.472367s (thread); 0s (gc)                         |
|                                                                             |
|                   8                 7                   6 2                 |
|o5 = {656100000000x  - 4738500000000x y + 10209037500000x y  -               |
|     ------------------------------------------------------------------------|
|                   5 3                  4 4                 3 5              |
|     1232156250000x y  - 14757374609375x y  + 1232156250000x y  +            |
|     ------------------------------------------------------------------------|
|                    2 6                   7                8                 |
|     10209037500000x y  + 4738500000000x*y  + 656100000000y  -               |
|     ------------------------------------------------------------------------|
|                   6 2                 5   2                 4 2 2           |
|     1272834000000x z  + 4596345000000x y*z  - 2876644125000x y z  -         |
|     ------------------------------------------------------------------------|
|                   2 4 2                   5 2                 6 2           |
|     2876644125000x y z  - 4596345000000x*y z  - 1272834000000y z  +         |
|     ------------------------------------------------------------------------|
|                  4 4                3   4                 2 2 4             |
|     787385610000x z  - 614109600000x y*z  + 1448931240000x y z  +           |
|     ------------------------------------------------------------------------|
|                    3 4                4 4                2 6                |
|     614109600000x*y z  + 787385610000y z  - 164959286400x z  -              |
|     ------------------------------------------------------------------------|
|                  2 6               8         8           7             6 2  |
|     164959286400y z  + 11019960576z , 810000x  + 9828000x y + 41477400x y  +|
|     ------------------------------------------------------------------------|
|              5 3            4 4            3 5            2 6             7 |
|     60944520x y  - 15999839x y  - 60944520x y  + 41477400x y  - 9828000x*y  |
|     ------------------------------------------------------------------------|
|              8             6 2              5   2              4 2 2        |
|     + 810000y  - 176580000x z  - 1071252000x y*z  - 1448152200x y z  -      |
|     ------------------------------------------------------------------------|
|                2 4 2                5 2             6 2               4 4   |
|     1448152200x y z  + 1071252000x*y z  - 176580000y z  + 11081610000x z  + |
|     ------------------------------------------------------------------------|
|                3   4               2 2 4                3 4                 |
|     8845200000x y*z  + 29746440000x y z  - 8845200000x*y z  +               |
|     ------------------------------------------------------------------------|
|                 4 4                2 6                2 6                8  |
|     11081610000y z  - 158922000000x z  - 158922000000y z  + 656100000000z , |
|     ------------------------------------------------------------------------|
|            8          7           6 2          5 3           4 4            |
|     104976x  - 629856x y + 997272x y  + 472392x y  - 1673055x y  -          |
|     ------------------------------------------------------------------------|
|            3 5          2 6            7          8         6 2             |
|     472392x y  + 997272x y  + 629856x*y  + 104976y  - 29160x z  +           |
|     ------------------------------------------------------------------------|
|           5   2         4 2 2         2 4 2           5 2         6 2       |
|     87480x y*z  - 36450x y z  - 36450x y z  - 87480x*y z  - 29160y z  +     |
|     ------------------------------------------------------------------------|
|          4 4        3   4        2 2 4          3 4        4 4      2 6     |
|     2673x z  - 1944x y*z  + 4212x y z  + 1944x*y z  + 2673y z  - 90x z  -   |
|     ------------------------------------------------------------------------|
|        2 6    8                                                             |
|     90y z  + z }                                                            |
|                                                                             |
|o5 : List                                                                    |
+-----------------------------------------------------------------------------+

The extra work done by the default algorithm to ensure an optimal hsop is
rewarded by needing to calculate a smaller collection of corresponding
secondary invariants.  In fact, it has proved quicker overall to calculate the
invariant ring based on the optimal algorithm rather than the Dade algorithm.

+-----------------------------------------------------------------------------+
|i6 : time secondaryInvariants(P1,C4xC2)                                      |
| -- used 0.0426685s (cpu); 0.0426692s (thread); 0s (gc)                      |
|                                                                             |
|          3       3                                                          |
|o6 = {1, x y - x*y }                                                         |
|                                                                             |
|o6 : List                                                                    |
+-----------------------------------------------------------------------------+
|i7 : time secondaryInvariants(P2,C4xC2)                                      |
| -- used 2.14899s (cpu); 1.68832s (thread); 0s (gc)                          |
|                                                                             |
|          2   2    2   4   2 2    2 2   2 2   3       3   4    4   6   2 4   |
|o7 = {1, z , x  + y , z , x z  + y z , x y , x y - x*y , x  + y , z , x z  + |
|     ------------------------------------------------------------------------|
|      2 4   2 2 2   3   2      3 2   4 2    4 2   4 2    2 4   5       5   6 |
|     y z , x y z , x y*z  - x*y z , x z  + y z , x y  + x y , x y - x*y , x  |
|     ------------------------------------------------------------------------|
|        6   3   4      3 4   4 4    4 4   4 2 2    2 4 2   5   2      5 2    |
|     + y , x y*z  - x*y z , x z  + y z , x y z  + x y z , x y*z  - x*y z ,   |
|     ------------------------------------------------------------------------|
|      6 2    6 2   4 4   5 3    3 5   6 2    2 6   7       7   8    8   5   4|
|     x z  + y z , x y , x y  - x y , x y  + x y , x y - x*y , x  + y , x y*z |
|     ------------------------------------------------------------------------|
|          5 4   6 4    6 4   4 4 2   5 3 2    3 5 2   6 2 2    2 6 2   7   2 |
|     - x*y z , x z  + y z , x y z , x y z  - x y z , x y z  + x y z , x y*z  |
|     ------------------------------------------------------------------------|
|          7 2   8 2    8 2   6 4    4 6   7 3    3 7   8 2    2 8   9        |
|     - x*y z , x z  + y z , x y  + x y , x y  - x y , x y  + x y , x y -     |
|     ------------------------------------------------------------------------|
|        9   10    10   8 4    8 4   8 2 2    2 8 2   9   2      9 2   10 2   |
|     x*y , x   + y  , x z  + y z , x y z  + x y z , x y*z  - x*y z , x  z  + |
|     ------------------------------------------------------------------------|
|      10 2   7 5    5 7   8 4    4 8   9 3    3 9   10 2    2 10   11        |
|     y  z , x y  - x y , x y  + x y , x y  - x y , x  y  + x y  , x  y -     |
|     ------------------------------------------------------------------------|
|        11   12    12   10 2 2    2 10 2   11   2      11 2   12 2    12 2   |
|     x*y  , x   + y  , x  y z  + x y  z , x  y*z  - x*y  z , x  z  + y  z ,  |
|     ------------------------------------------------------------------------|
|      10 4    4 10   11 3    3 11   12 2    2 12   13       13   14    14    |
|     x  y  + x y  , x  y  - x y  , x  y  + x y  , x  y - x*y  , x   + y  ,   |
|     ------------------------------------------------------------------------|
|      14 2    14 2   13 3    3 13   14 2    2 14   15       15   16    16    |
|     x  z  + y  z , x  y  - x y  , x  y  + x y  , x  y - x*y  , x   + y  ,   |
|     ------------------------------------------------------------------------|
|      17       17   18    18   20    20                                      |
|     x  y - x*y  , x   + y  , x   + y  }                                     |
|                                                                             |
|o7 : List                                                                    |
+-----------------------------------------------------------------------------+
|i8 : #oo                                                                     |
|                                                                             |
|o8 = 64                                                                      |
+-----------------------------------------------------------------------------+

Of course, currently one advantage of the Dade algorithm is that it can

calculate a hsop for the invariant ring when considering a finite field. Since
       2
|C4xC2| =64, it is safe to consider the finite field with 101 elements.

+-----------------------------------------------------------------------------+
|i9 : K=GF(101);                                                              |
+-----------------------------------------------------------------------------+
|i10 : C4xC2=finiteAction({A,B},K[x,y,z])                                     |
|                                                                             |
|o10 = K[x..z] <- {| 0 -1 0  |, | 0 -1 0 |}                                   |
|                  | 1 0  0  |  | 1 0  0 |                                    |
|                  | 0 0  -1 |  | 0 0  1 |                                    |
|                                                                             |
|o10 : FiniteGroupAction                                                      |
+-----------------------------------------------------------------------------+
|i11 : primaryInvariants(C4xC2,Dade=>true)                                    |
|                                                                             |
|        8      7      6 2     5 3      4 4     3 5     2 6        7    8     |
|o11 = {x  + 16x y - 9x y  + 6x y  - 31x y  - 6x y  - 9x y  - 16x*y  + y  +   |
|      -----------------------------------------------------------------------|
|         6 2      5   2      4 2 2      2 4 2        5 2      6 2    4 4     |
|      33x z  - 39x y*z  - 10x y z  - 10x y z  + 39x*y z  + 33y z  - x z  +   |
|      -----------------------------------------------------------------------|
|         3   4      2 2 4        3 4    4 4      2 6      2 6      8     8   |
|      36x y*z  - 49x y z  - 36x*y z  - y z  + 49x z  + 49y z  + 24z , 16x  + |
|      -----------------------------------------------------------------------|
|         7       6 2      5 3      4 4      3 5      2 6        7      8     |
|      38x y - 27x y  + 29x y  - 27x y  - 29x y  - 27x y  - 38x*y  + 16y  -   |
|      -----------------------------------------------------------------------|
|        6 2      5   2     4 2 2     2 4 2        5 2     6 2      4 4       |
|      3x z  + 28x y*z  + 5x y z  + 5x y z  - 28x*y z  - 3y z  + 28x z  +     |
|      -----------------------------------------------------------------------|
|        3   4     2 2 4       3 4      4 4      2 6      2 6      8    8     |
|      3x y*z  + 7x y z  - 3x*y z  + 28y z  + 29x z  + 29y z  + 25z , 5x  -   |
|      -----------------------------------------------------------------------|
|         7      6 2      5 3      4 4      3 5     2 6        7     8        |
|      44x y + 4x y  + 16x y  - 35x y  - 16x y  + 4x y  + 44x*y  + 5y  +      |
|      -----------------------------------------------------------------------|
|         6 2     5   2      4 2 2      2 4 2       5 2      6 2     4 4      |
|      31x z  + 5x y*z  + 14x y z  + 14x y z  - 5x*y z  + 31y z  + 2x z  +    |
|      -----------------------------------------------------------------------|
|         3   4      2 2 4        3 4     4 4      2 6      2 6      8        |
|      39x y*z  + 14x y z  - 39x*y z  + 2y z  - 16x z  - 16y z  - 22z }       |
|                                                                             |
|o11 : List                                                                   |
+-----------------------------------------------------------------------------+

References

[DK] Derksen, H., Kemper, G. Computational Invariant Theory. Berlin Heidelberg
New York: Springer-Verlag, 2002

[K] Kemper, G. An Algorithm to Calculate Optimal Homogeneous Systems of
Parameters. J. Symbolic Computation 27 (1999), 171-184

See also
========

  * primaryInvariants -- computes a list of primary
    invariants for the invariant ring of a finite group
  * Dade -- an
    optional argument for primaryInvariants determining whether to use the Dade
    algorithm
  * DegreeVector
    -- an optional argument for primaryInvariants that finds invariants of
    certain degrees
-------------------------------------------------------------------------------

The source of this document is in InvariantRing/HawesDoc.m2:426:0.

invariantRing -- the ring of invariants of a group action
*********************************************************

  * Usage:
        invariantRing G, R^G
  * Inputs:
      * G, an instance of the type GroupAction,
      * R, a polynomial ring (Macaulay2Doc), on which the
        group acts
  * Optional inputs (Macaulay2Doc),:
      * Strategy (missing documentation) => ..., default value UseNormaliz, the
        strategy used to compute the invariant ring
      * DegreeBound,
        => ..., default value infinity, degree bound for invariants of finite
        groups
      * UseCoefficientRing,
        => ...,
        default value false, option to compute invariants over the given
        coefficient ring
      * UseLinearAlgebra,
        => ...,
        default value false, strategy for computing invariants of finite groups
  * Outputs:
      * an instance of the type RingOfInvariants, the
        ring of invariants of the given group action

Description
===========

This function is provided by the package InvariantRing.

The following example defines an action of a two-dimensional torus on a
four-dimensional vector space with a basis of weight vectors whose weights are
the columns of the input matrix.

+---------------------------------------+
|i1 : R = QQ[x_1..x_4]                  |
|                                       |
|o1 = R                                 |
|                                       |
|o1 : PolynomialRing                    |
+---------------------------------------+
|i2 : W = matrix{{0,1,-1,1},{1,0,-1,-1}}|
|                                       |
|o2 = | 0 1 -1 1  |                     |
|     | 1 0 -1 -1 |                     |
|                                       |
|              2       4                |
|o2 : Matrix ZZ  <-- ZZ                 |
+---------------------------------------+
|i3 : T = diagonalAction(W, R)          |
|                                       |
|             * 2                       |
|o3 = R <- (QQ )  via                   |
|                                       |
|     | 0 1 -1 1  |                     |
|     | 1 0 -1 -1 |                     |
|                                       |
|o3 : DiagonalAction                    |
+---------------------------------------+
|i4 : S = invariantRing T               |
|                                       |
|o4 =             2                     |
|     QQ[x x x , x x x ]                |
|         1 2 3   1 3 4                 |
|                                       |
|o4 : RingOfInvariants                  |
+---------------------------------------+

The algebra generators for the ring of invariants are computed upon
initialization by the method invariants.

Alternatively, we can use the following shortcut to construct a ring of
invariants.

+-----------------------+
|i5 : S = R^T           |
|                       |
|o5 =             2     |
|     QQ[x x x , x x x ]|
|         1 2 3   1 3 4 |
|                       |
|o5 : RingOfInvariants  |
+-----------------------+

Caveat
======

By default, the invariants of a diagonal group action are computed over an
infinite extension of the ground field specified by the user over which the
action is defined. Provided the action is defined, it is possible to compute
invariants literally over the specified ground field in prime characteristic
using the option UseCoefficientRing.

Ways to use invariantRing:
==========================

  * "invariantRing(GroupAction)"

For the programmer
==================

The object invariantRing, is a method function with options (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in InvariantRing/InvariantsDoc.m2:128:0.

invariants -- computes the generating invariants of a group action
******************************************************************

  * Usage:
        invariants G
  * Inputs:
      * G, an instance of the type GroupAction, a specific
        type of group action on a polynomial ring
  * Optional inputs (Macaulay2Doc),:
      * Strategy (missing documentation) => ..., default value UseNormaliz, the
        strategy used to compute diagonal invariants, options are UsePolyhedra
        or UseNormaliz.
      * DegreeBound,
        => ..., default value infinity, degree bound for invariants of finite
        groups
      * DegreeLimit,
        => ..., default value {}, GB option for invariants
      * SubringLimit,
        => ..., default value infinity, GB option for invariants
      * UseCoefficientRing,
        => ...,
        default value false, option to compute invariants over the given
        coefficient ring
      * UseLinearAlgebra,
        => ...,
        default value false, strategy for computing invariants of finite groups
  * Outputs:
      * L, a list (Macaulay2Doc), a minimal set of generating
        invariants for the group action

Description
===========

This function is provided by the package InvariantRing. This
function can be used to compute the generating invariants of a diagonal group
action, finite group action or linearly reductive group action. It can also be
used to compute a basis of a graded component of the invariant ring. Below is a
list of the many ways to use this function:

  * invariants(FiniteGroupAction),:
    computes the generating invariants of a finite group action
  * invariants(DiagonalAction),: computes
    the generating invariants of a diagonal group action
  * invariants(LinearlyReductiveAction),:
    computes the generating
    invariants of a linearly reductive action
  * invariants(FiniteGroupAction,ZZ),
    or
    invariants(FiniteGroupAction,List),:
    computes a basis for graded
    component of the invariant ring of a finite group action
  * invariants(LinearlyReductiveAction,ZZ),
    or
    invariants(LinearlyReductiveAction,List),:
    computes a basis for graded
    component of the invariant ring of a linearly reductive group action

Caveat
======

Some optional inputs are only relevant to certain use cases of this method.
Please consult the documentation pages for the different cases to learn which
optional inputs are used.

See also
========

  * invariantRing -- the ring of invariants of a group
    action
  * isInvariant -- check whether a polynomial is invariant
    under a group action

Ways to use invariants:
=======================

  * invariants(DiagonalAction), --
    computes the generating invariants of a group action
  * invariants(FiniteGroupAction), --
    computes the generating invariants of a group action
  * "invariants(FiniteGroupAction,List)" -- see
    invariants(FiniteGroupAction,ZZ),
    -- basis for graded component of invariant ring
  * invariants(FiniteGroupAction,ZZ)
    -- basis for graded component of
    invariant ring
  * invariants(LinearlyReductiveAction)
    -- invariant generators of Hilbert
    ideal
  * "invariants(LinearlyReductiveAction,List)" -- see
    invariants(LinearlyReductiveAction,ZZ),
    -- basis for graded component
    of invariant ring
  * invariants(LinearlyReductiveAction,ZZ)
    -- basis for graded component
    of invariant ring

For the programmer
==================

The object invariants, is a method function with options (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in InvariantRing/InvariantsDoc.m2:171:0.

invariants(...,DegreeBound=>...) -- degree bound for invariants of finite groups
********************************************************************************

  * Usage:
        invariants G
  * Inputs:
      * G, an instance of the type FiniteGroupAction,
  * Outputs:
      * L, a list (Macaulay2Doc), a minimal set of generating
        invariants for the group action

Description
===========

This function is provided by the package InvariantRing.

This optional argument allows the user to provide an upper bound for the degree
of the generating invariants of a finite group action. If no upper bound is
provided, the order of the group is used as an upper bound. Providing a smaller
upper bound may speed up the computation of invariants. However, if the value
provided is too small the resulting list may not generate the ring of
invariants.

The following example computes the invariants of the symmetric group on 4
elements.

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x_1..x_4]                                                        |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : L = apply({"2134","2341"},permutationMatrix);                           |
+-----------------------------------------------------------------------------+
|i3 : S4 = finiteAction(L,R)                                                  |
|                                                                             |
|o3 = R <- {| 0 1 0 0 |, | 0 0 0 1 |}                                         |
|           | 1 0 0 0 |  | 1 0 0 0 |                                          |
|           | 0 0 1 0 |  | 0 1 0 0 |                                          |
|           | 0 0 0 1 |  | 0 0 1 0 |                                          |
|                                                                             |
|o3 : FiniteGroupAction                                                       |
+-----------------------------------------------------------------------------+
|i4 : elapsedTime invariants S4                                               |
| -- .80985s elapsed                                                          |
|                                                                             |
|                          2    2    2    2   3    3    3    3   4    4    4  |
|o4 = {x  + x  + x  + x , x  + x  + x  + x , x  + x  + x  + x , x  + x  + x  +|
|       1    2    3    4   1    2    3    4   1    2    3    4   1    2    3  |
|     ------------------------------------------------------------------------|
|      4                                                                      |
|     x }                                                                     |
|      4                                                                      |
|                                                                             |
|o4 : List                                                                    |
+-----------------------------------------------------------------------------+
|i5 : elapsedTime invariants(S4,DegreeBound=>4)                               |
|                                                                             |
|Warning: stopping condition not met!                                         |
|Output may not generate the entire ring of invariants.                       |
|Increase value of DegreeBound.                                               |
|                                                                             |
| -- .652206s elapsed                                                         |
|                                                                             |
|                          2    2    2    2   3    3    3    3   4    4    4  |
|o5 = {x  + x  + x  + x , x  + x  + x  + x , x  + x  + x  + x , x  + x  + x  +|
|       1    2    3    4   1    2    3    4   1    2    3    4   1    2    3  |
|     ------------------------------------------------------------------------|
|      4                                                                      |
|     x }                                                                     |
|      4                                                                      |
|                                                                             |
|o5 : List                                                                    |
+-----------------------------------------------------------------------------+

Caveat
======

If the value provided for this option is too small, then the output list does
not generate the entire ring of invariants. A warning message is produced to
notify the user of the issue.

See also
========

  * finiteAction -- the group action generated by a list
    of matrices
  * invariantRing -- the ring of invariants of a group
    action
  * isInvariant -- check whether a polynomial is invariant
    under a group action

Functions with optional argument named DegreeBound:
===================================================

  * "invariantRing(...,DegreeBound=>...)"
  * invariants(...,DegreeBound=>...)
    -- degree bound for
    invariants of finite groups

Further information
===================

  * Default value: infinity (Macaulay2Doc),
  * Function: invariants, -- computes the generating
    invariants of a group action
  * Option key: DegreeBound,
    -- degree bound for
    invariants of finite groups
-------------------------------------------------------------------------------

The source of this document is in InvariantRing/InvariantsDoc.m2:384:0.

invariants(...,DegreeLimit=>...) -- GB option for invariants
************************************************************

Description
===========

The computation of invariants of linearly reductive group actions requires the
use of Gröbner bases. These options allow partial control over the computation
performed by invariants(LinearlyReductiveAction),
and
hilbertIdeal(LinearlyReductiveAction), allowing to terminate the
computation after reaching a certain degree. For more information, see
gb (Macaulay2Doc).

See also
========

  * invariants(LinearlyReductiveAction)
    -- invariant generators of Hilbert
    ideal
  * hilbertIdeal(LinearlyReductiveAction) -- compute
    generators for the Hilbert ideal

Functions with optional argument named DegreeLimit:
===================================================

  * "compose(Module,Module,Module,DegreeLimit=>...)" -- see compose (Macaulay2Doc),
    -- composition as a pairing on Hom-modules
  * "End(...,DegreeLimit=>...)" -- see End (Macaulay2Doc), -- module
    of endomorphisms
  * "gb(...,DegreeLimit=>...)" -- see gb (Macaulay2Doc), -- compute a
    Gröbner basis
  * "Hom(...,DegreeLimit=>...)" -- see Hom (Macaulay2Doc), -- module
    of homomorphisms
  * "homomorphism'(...,DegreeLimit=>...)" -- see homomorphism' (Macaulay2Doc),
    -- get the element of Hom from a homomorphism
  * "hilbertIdeal(...,DegreeLimit=>...)"
  * invariants(...,DegreeLimit=>...)
    -- GB option for
    invariants
  * "minimalBetti(...,DegreeLimit=>...)" -- see minimalBetti (Macaulay2Doc),
    -- minimal betti numbers of (the minimal free
    resolution of) a homogeneous ideal or module
  * normalCone(Ideal,DegreeLimit=>...) (missing documentation)
  * normalCone(Ideal,RingElement,DegreeLimit=>...) (missing documentation)
  * "pushForward(...,DegreeLimit=>...)" -- see
    pushForward(RingMap,Module) (Macaulay2Doc),
    -- compute the pushforward
    of a module along a ring map
  * quotient(...,DegreeLimit=>...) (missing documentation)
  * saturate(...,DegreeLimit=>...) (missing documentation)
  * "syz(...,DegreeLimit=>...)" -- see syz(Matrix) (Macaulay2Doc),
    -- compute the syzygy matrix

Further information
===================

  * Default value: {}
  * Function: invariants, -- computes the generating
    invariants of a group action
  * Option key: DegreeLimit (Macaulay2Doc), -- an optional
    argument
-------------------------------------------------------------------------------

The source of this document is in InvariantRing/InvariantsDoc.m2:703:0.

invariants(...,SubringLimit=>...) -- GB option for invariants
*************************************************************

Description
===========

The computation of invariants of linearly reductive group actions requires the
use of Gröbner bases. These options allow partial control over the computation
performed by invariants(LinearlyReductiveAction),
and
hilbertIdeal(LinearlyReductiveAction), allowing to terminate the
computation after a certain number of invariants are obtained. For more
information, see gb (Macaulay2Doc).

See also
========

  * invariants(LinearlyReductiveAction)
    -- invariant generators of Hilbert
    ideal
  * hilbertIdeal(LinearlyReductiveAction) -- compute
    generators for the Hilbert ideal

Functions with optional argument named SubringLimit:
====================================================

  * "gb(...,SubringLimit=>...)" -- see gb (Macaulay2Doc), -- compute a
    Gröbner basis
  * "hilbertIdeal(...,SubringLimit=>...)"
  * invariants(...,SubringLimit=>...)
    -- GB option for
    invariants
  * kernel(...,SubringLimit=>...) (Macaulay2Doc)
    -- stop
    after finding enough elements of a subring

Further information
===================

  * Default value: infinity (Macaulay2Doc),
  * Function: invariants, -- computes the generating
    invariants of a group action
  * Option key: SubringLimit (Macaulay2Doc), -- an optional
    argument
-------------------------------------------------------------------------------

The source of this document is in InvariantRing/InvariantsDoc.m2:726:0.

invariants(...,UseCoefficientRing=>...) -- option to compute invariants over the given coefficient ring
*******************************************************************************************************

  * Usage:
        invariants G
  * Inputs:
      * D, an instance of the type DiagonalAction,
  * Outputs:
      * L, a list (Macaulay2Doc), a minimal set of generating
        invariants for the group action

Description
===========

This function is provided by the package InvariantRing.

By default, the invariants of a diagonal action are computed over an infinite
extension of the coefficient field specified by the user over which the action
is defined. Setting this optional argument to true (Macaulay2Doc),
will compute the invariants of the action literally over the finite field
specified by the user in prime characteristic, provided the action is defined.

The following example computes the invariants of a 1-dimensional torus action
literally over the specified finite field.

+------------------------------------------------+
|i1 : R = (GF 9)[x, y]                           |
|                                                |
|o1 = R                                          |
|                                                |
|o1 : PolynomialRing                             |
+------------------------------------------------+
|i2 : W = matrix {{7, -5}}                       |
|                                                |
|o2 = | 7 -5 |                                   |
|                                                |
|              1       2                         |
|o2 : Matrix ZZ  <-- ZZ                          |
+------------------------------------------------+
|i3 : T = diagonalAction(W, R)                   |
|                                                |
|                *                               |
|o3 = R <- (GF 9)  via                           |
|                                                |
|     | 7 -5 |                                   |
|                                                |
|o3 : DiagonalAction                             |
+------------------------------------------------+
|i4 : invariantRing(T,UseCoefficientRing => true)|
|                                                |
|o4 =         3   3    8   8                     |
|     GF 9[x*y , x y, y , x ]                    |
|                                                |
|o4 : RingOfInvariants                           |
+------------------------------------------------+

Over an infinite extension of the given ground field, there are fewer
invariants.

+---------------------+
|i5 : invariantRing T |
|                     |
|o5 =       5 7       |
|     GF 9[x y ]      |
|                     |
|o5 : RingOfInvariants|
+---------------------+

See also
========

  * diagonalAction -- diagonal group action via weights
  * invariants -- computes the generating invariants of a
    group action
  * invariantRing -- the ring of invariants of a group
    action

Functions with optional argument named UseCoefficientRing:
==========================================================

  * "invariantRing(...,UseCoefficientRing=>...)"
  * invariants(...,UseCoefficientRing=>...)
    -- option to
    compute invariants over the given coefficient ring

Further information
===================

  * Default value: false (Macaulay2Doc),
  * Function: invariants, -- computes the generating
    invariants of a group action
  * Option key: UseCoefficientRing,
    -- option to
    compute invariants over the given coefficient ring
-------------------------------------------------------------------------------

The source of this document is in InvariantRing/InvariantsDoc.m2:438:0.

invariants(...,UseLinearAlgebra=>...) -- strategy for computing invariants of finite groups
*******************************************************************************************

  * Usage:
        invariants G
  * Inputs:
      * G, an instance of the type FiniteGroupAction,
  * Outputs:
      * L, a list (Macaulay2Doc), a minimal set of generating
        invariants for the group action

Description
===========

This function is provided by the package InvariantRing.

This optional argument determines the strategy used to compute generating
invariants of a finite group action. The default strategy uses the Reynolds
operator, however this may be slow for large groups. Setting this argument to
true (Macaulay2Doc), uses the linear algebra method for computing
invariants of a given degree by calling invariants(FiniteGroupAction,ZZ).
This may provide a speedup at lower
degrees, especially if the user-provided generating set for the group is small.

The following example computes the invariants of the symmetric group on 4
elements. Note that using different strategies may lead to different sets of
generating invariants.

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x_1..x_4]                                                        |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : L = apply({"2134","2341"},permutationMatrix);                           |
+-----------------------------------------------------------------------------+
|i3 : S4 = finiteAction(L,R)                                                  |
|                                                                             |
|o3 = R <- {| 0 1 0 0 |, | 0 0 0 1 |}                                         |
|           | 1 0 0 0 |  | 1 0 0 0 |                                          |
|           | 0 0 1 0 |  | 0 1 0 0 |                                          |
|           | 0 0 0 1 |  | 0 0 1 0 |                                          |
|                                                                             |
|o3 : FiniteGroupAction                                                       |
+-----------------------------------------------------------------------------+
|i4 : elapsedTime invariants S4                                               |
| -- .756033s elapsed                                                         |
|                                                                             |
|                          2    2    2    2   3    3    3    3   4    4    4  |
|o4 = {x  + x  + x  + x , x  + x  + x  + x , x  + x  + x  + x , x  + x  + x  +|
|       1    2    3    4   1    2    3    4   1    2    3    4   1    2    3  |
|     ------------------------------------------------------------------------|
|      4                                                                      |
|     x }                                                                     |
|      4                                                                      |
|                                                                             |
|o4 : List                                                                    |
+-----------------------------------------------------------------------------+
|i5 : elapsedTime invariants(S4,UseLinearAlgebra=>true)                       |
| -- .131239s elapsed                                                         |
|                                                                             |
|o5 = {x  + x  + x  + x , x x  + x x  + x x  + x x  + x x  + x x , x x x  +   |
|       1    2    3    4   1 2    1 3    2 3    1 4    2 4    3 4   1 2 3     |
|     ------------------------------------------------------------------------|
|     x x x  + x x x  + x x x , x x x x }                                     |
|      1 2 4    1 3 4    2 3 4   1 2 3 4                                      |
|                                                                             |
|o5 : List                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * finiteAction -- the group action generated by a list
    of matrices
  * invariantRing -- the ring of invariants of a group
    action
  * isInvariant -- check whether a polynomial is invariant
    under a group action

Functions with optional argument named UseLinearAlgebra:
========================================================

  * "invariantRing(...,UseLinearAlgebra=>...)"
  * invariants(...,UseLinearAlgebra=>...)
    -- strategy for
    computing invariants of finite groups

Further information
===================

  * Default value: false (Macaulay2Doc),
  * Function: invariants, -- computes the generating
    invariants of a group action
  * Option key: UseLinearAlgebra,
    -- strategy for
    computing invariants of finite groups
-------------------------------------------------------------------------------

The source of this document is in InvariantRing/InvariantsDoc.m2:487:0.

invariants(DiagonalAction) -- computes the generating invariants of a group action
**********************************************************************************

  * Function: invariants,
  * Usage:
        invariants D
  * Inputs:
      * D, an instance of the type DiagonalAction, a
        diagonal action on a polynomial ring
  * Optional inputs (Macaulay2Doc),:
      * Strategy (missing documentation) => ..., default value UseNormaliz, the
        strategy used to compute diagonal invariants, options are UsePolyhedra
        or UseNormaliz.
      * DegreeBound,
        => ..., default value infinity, degree bound for invariants of finite
        groups
      * DegreeLimit,
        => ..., default value {}, GB option for invariants
      * SubringLimit,
        => ..., default value infinity, GB option for invariants
      * UseCoefficientRing,
        => ...,
        default value false, option to compute invariants over the given
        coefficient ring
      * UseLinearAlgebra,
        => ...,
        default value false, strategy for computing invariants of finite groups
  * Outputs:
      * L, a list (Macaulay2Doc), a minimal set of generating
        invariants for the group action

Description
===========

This function is provided by the package InvariantRing. It
implements an algorithm to compute a minimal set of generating monomial
invariants for a diagonal action of an abelian group $(k^*)^r \times
\mathbb{Z}/d_1 \times \cdots \times \mathbb{Z}/d_g$  on a polynomial ring  $R =
k[x_1, \dots, x_n]$. Saying the action is diagonal means that
$(t_1,\ldots,t_r) \in (k^*)^r$  acts by $$(t_1,\ldots,t_r) \cdot x_j =
t_1^{w_{1,j}}\cdots t_r^{w_{r,j}} x_j$$ for some integers  $w_{i,j}$  and the
generators  $u_1, \dots, u_g$  of the cyclic abelian factors act by $$u_i \cdot
x_j = \zeta_i^{w_{r+i,j}} x_j$$ for  $\zeta_i$  a primitive  $d_i$-th root of
unity. The integers $w_{i,j}$ comprise the weight matrix W. In other words, the
$j$ -th column of W is the weight vector of $x_j$.

The algorithm combines a modified version of an algorithm for tori due to
Derksen and Kemper which can be found in:

  * Derksen, H. & Kemper, G. (2015).Computational Invariant Theory. Heidelberg:
    Springer. pp 159-164

together with an algorithm for finite abelian groups due to Gandini which can
be found in:

  * Gandini, F. Ideals of Subspace Arrangements. Thesis (Ph.D.)-University of
    Michigan. 2019. ISBN: 978-1392-76291-2. pp 29-34.

Here is an example of a one-dimensional torus acting on a two-dimensional
vector space:

+-----------------------------+
|i1 : R = QQ[x_1,x_2]         |
|                             |
|o1 = R                       |
|                             |
|o1 : PolynomialRing          |
+-----------------------------+
|i2 : W = matrix{{1,-1}}      |
|                             |
|o2 = | 1 -1 |                |
|                             |
|              1       2      |
|o2 : Matrix ZZ  <-- ZZ       |
+-----------------------------+
|i3 : T = diagonalAction(W, R)|
|                             |
|            *                |
|o3 = R <- QQ  via            |
|                             |
|     | 1 -1 |                |
|                             |
|o3 : DiagonalAction          |
+-----------------------------+
|i4 : invariants T            |
|                             |
|o4 = {x x }                  |
|       1 2                   |
|                             |
|o4 : List                    |
+-----------------------------+

Here is an example of a product of two cyclic groups of order 3 acting on a
three-dimensional vector space:

+---------------------------------+
|i5 : R = QQ[x_1..x_3]            |
|                                 |
|o5 = R                           |
|                                 |
|o5 : PolynomialRing              |
+---------------------------------+
|i6 : d = {3,3}                   |
|                                 |
|o6 = {3, 3}                      |
|                                 |
|o6 : List                        |
+---------------------------------+
|i7 : W = matrix{{1,0,1},{0,1,1}} |
|                                 |
|o7 = | 1 0 1 |                   |
|     | 0 1 1 |                   |
|                                 |
|              2       3          |
|o7 : Matrix ZZ  <-- ZZ           |
+---------------------------------+
|i8 : A = diagonalAction(W, d, R) |
|                                 |
|o8 = R <- ZZ/3 x ZZ/3 via        |
|                                 |
|     | 1 0 1 |                   |
|     | 0 1 1 |                   |
|                                 |
|o8 : DiagonalAction              |
+---------------------------------+
|i9 : invariants A                |
|                                 |
|       3   3   3       2   2 2   |
|o9 = {x , x , x , x x x , x x x }|
|       3   2   1   1 2 3   1 2 3 |
|                                 |
|o9 : List                        |
+---------------------------------+

Here is an example of a diagonal action by the product of a two-dimensional
torus with a cyclic group of order 3 acting on a two-dimensional vector space:

+--------------------------------------+
|i10 : R = QQ[x_1, x_2]                |
|                                      |
|o10 = R                               |
|                                      |
|o10 : PolynomialRing                  |
+--------------------------------------+
|i11 : d = {3}                         |
|                                      |
|o11 = {3}                             |
|                                      |
|o11 : List                            |
+--------------------------------------+
|i12 : W1 = matrix{{1,-1}, {-1,1}}     |
|                                      |
|o12 = | 1  -1 |                       |
|      | -1 1  |                       |
|                                      |
|               2       2              |
|o12 : Matrix ZZ  <-- ZZ               |
+--------------------------------------+
|i13 : W2 = matrix {{1,0}}             |
|                                      |
|o13 = | 1 0 |                         |
|                                      |
|               1       2              |
|o13 : Matrix ZZ  <-- ZZ               |
+--------------------------------------+
|i14 : D = diagonalAction(W1, W2, d, R)|
|                                      |
|              * 2                     |
|o14 = R <- (QQ )  x ZZ/3 via          |
|                                      |
|      (| 1  -1 |, | 1 0 |)            |
|       | -1 1  |                      |
|                                      |
|o14 : DiagonalAction                  |
+--------------------------------------+
|i15 : invariants D                    |
|                                      |
|        3 3                           |
|o15 = {x x }                          |
|        1 2                           |
|                                      |
|o15 : List                            |
+--------------------------------------+

Caveat
======

By default, the invariants are computed over an infinite extension of the
ground field specified by the user over which the action is defined.  Provided
the action is defined, it is possible to compute invariants literally over the
specified ground field in prime characteristic using the option
UseCoefficientRing.

See also
========

  * diagonalAction -- diagonal group action via weights
  * invariantRing -- the ring of invariants of a group
    action
  * isInvariant -- check whether a polynomial is invariant
    under a group action

Ways to use this method:
========================

  * invariants(DiagonalAction), --
    computes the generating invariants of a group action
-------------------------------------------------------------------------------

The source of this document is in InvariantRing/InvariantsDoc.m2:292:0.

invariants(FiniteGroupAction) -- computes the generating invariants of a group action
*************************************************************************************

  * Function: invariants,
  * Usage:
        invariants G
  * Inputs:
      * G, an instance of the type FiniteGroupAction,
  * Optional inputs (Macaulay2Doc),:
      * Strategy (missing documentation) => ..., default value UseNormaliz, the
        strategy used to compute diagonal invariants, options are UsePolyhedra
        or UseNormaliz.
      * DegreeBound,
        => ..., default value infinity, degree bound for invariants of finite
        groups
      * DegreeLimit,
        => ..., default value {}, GB option for invariants
      * SubringLimit,
        => ..., default value infinity, GB option for invariants
      * UseCoefficientRing,
        => ...,
        default value false, option to compute invariants over the given
        coefficient ring
      * UseLinearAlgebra,
        => ...,
        default value false, strategy for computing invariants of finite groups
  * Outputs:
      * L, a list (Macaulay2Doc), a minimal set of generating
        invariants for the group action

Description
===========

This function is provided by the package InvariantRing.

It implements King's algorithm to compute a minimal set of generating
invariants for the action of a finite group on a polynomial ring following
Algorithm 3.8.2 in:

  * Derksen, H. & Kemper, G. (2015).Computational Invariant Theory. Heidelberg:
    Springer.

The following example computes the invariants of the alternating group on 4
elements.

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x_1..x_4]                                                        |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : L = apply({"2314","2143"},permutationMatrix);                           |
+-----------------------------------------------------------------------------+
|i3 : A4 = finiteAction(L,R)                                                  |
|                                                                             |
|o3 = R <- {| 0 0 1 0 |, | 0 1 0 0 |}                                         |
|           | 1 0 0 0 |  | 1 0 0 0 |                                          |
|           | 0 1 0 0 |  | 0 0 0 1 |                                          |
|           | 0 0 0 1 |  | 0 0 1 0 |                                          |
|                                                                             |
|o3 : FiniteGroupAction                                                       |
+-----------------------------------------------------------------------------+
|i4 : netList invariants A4                                                   |
|                                                                             |
|     +-----------------------------------------------------------------------|
|o4 = |x  + x  + x  + x                                                       |
|     | 1    2    3    4                                                      |
|     +-----------------------------------------------------------------------|
|     | 2    2    2    2                                                      |
|     |x  + x  + x  + x                                                       |
|     | 1    2    3    4                                                      |
|     +-----------------------------------------------------------------------|
|     | 3    3    3    3                                                      |
|     |x  + x  + x  + x                                                       |
|     | 1    2    3    4                                                      |
|     +-----------------------------------------------------------------------|
|     | 4    4    4    4                                                      |
|     |x  + x  + x  + x                                                       |
|     | 1    2    3    4                                                      |
|     +-----------------------------------------------------------------------|
|     | 3 2        3 2    2   3    2 3      3 2      2 3      3   2    3   2  |
|     |x x x  + x x x  + x x x  + x x x  + x x x  + x x x  + x x x  + x x x  +|
|     | 1 2 3    1 2 3    1 2 3    1 2 4    1 3 4    2 3 4    1 2 4    2 3 4  |
|     +-----------------------------------------------------------------------|
|-----------------------------------------------------------------------------|
|----------------------------------+                                          |
|                                  |                                          |
|                                  |                                          |
|----------------------------------+                                          |
|                                  |                                          |
|                                  |                                          |
|                                  |                                          |
|----------------------------------+                                          |
|                                  |                                          |
|                                  |                                          |
|                                  |                                          |
|----------------------------------+                                          |
|                                  |                                          |
|                                  |                                          |
|                                  |                                          |
|----------------------------------+                                          |
|    3 2      2 3    2   3      2 3|                                          |
| x x x  + x x x  + x x x  + x x x |                                          |
|  1 3 4    1 2 4    1 3 4    2 3 4|                                          |
|----------------------------------+                                          |
+-----------------------------------------------------------------------------+

See also
========

  * finiteAction -- the group action generated by a list
    of matrices
  * invariantRing -- the ring of invariants of a group
    action
  * isInvariant -- check whether a polynomial is invariant
    under a group action

Ways to use this method:
========================

  * invariants(FiniteGroupAction), --
    computes the generating invariants of a group action
-------------------------------------------------------------------------------

The source of this document is in InvariantRing/InvariantsDoc.m2:337:0.

invariants(FiniteGroupAction,ZZ) -- basis for graded component of invariant ring
********************************************************************************

  * Function: invariants,
  * Usage:
        invariants(G,d)
  * Inputs:
      * G, an instance of the type FiniteGroupAction,
      * d, an integer (Macaulay2Doc), a degree or multidegree
  * Optional inputs (Macaulay2Doc),:
      * Strategy (missing documentation) => ..., default value UseNormaliz, the
        strategy used to compute diagonal invariants, options are UsePolyhedra
        or UseNormaliz.
      * DegreeBound,
        => ..., default value infinity, degree bound for invariants of finite
        groups
      * DegreeLimit,
        => ..., default value {}, GB option for invariants
      * SubringLimit,
        => ..., default value infinity, GB option for invariants
      * UseCoefficientRing,
        => ...,
        default value false, option to compute invariants over the given
        coefficient ring
      * UseLinearAlgebra,
        => ...,
        default value false, strategy for computing invariants of finite groups
  * Outputs:
      * L, a list (Macaulay2Doc), an additive basis for a graded
        component of the ring of invariants

Description
===========

This function is provided by the package InvariantRing,

When called on a finite group action and a (multi)degree, it computes an
additive basis for the invariants of the action in the given degree.

This function uses an implementation of the Linear Algebra Method described in
§3.1.1 of

  * Derksen, H. & Kemper, G. (2015).Computational Invariant Theory. Heidelberg:
    Springer.

For example, consider the following action of a dihedral group.

+---------------------------------------------------------+
|i1 : K=toField(QQ[a]/(a^2+a+1));                         |
+---------------------------------------------------------+
|i2 : R = K[x,y]                                          |
|                                                         |
|o2 = R                                                   |
|                                                         |
|o2 : PolynomialRing                                      |
+---------------------------------------------------------+
|i3 : A=matrix{{a,0},{0,a^2}};                            |
|                                                         |
|             2      2                                    |
|o3 : Matrix K  <-- K                                     |
+---------------------------------------------------------+
|i4 : B=sub(matrix{{0,1},{1,0}},K);                       |
|                                                         |
|             2      2                                    |
|o4 : Matrix K  <-- K                                     |
+---------------------------------------------------------+
|i5 : D6=finiteAction({A,B},R)                            |
|                                                         |
|o5 = R <- {| a 0    |, | 0 1 |}                          |
|           | 0 -a-1 |  | 1 0 |                           |
|                                                         |
|o5 : FiniteGroupAction                                   |
+---------------------------------------------------------+
|i6 : invariants(D6,20)                                   |
|                                                         |
|       10 10   13 7    7 13   16 4    4 16   19       19 |
|o6 = {x  y  , x  y  + x y  , x  y  + x y  , x  y + x*y  }|
|                                                         |
|o6 : List                                                |
+---------------------------------------------------------+

It is important to note that this implementation uses the group generators
provided by the user, which can be recovered using
generators(FiniteGroupAction). To improve
efficiency the user should provide a generating set for the group that is as
small as possible.

See also
========

  * invariantRing -- the ring of invariants of a group
    action
  * isInvariant -- check whether a polynomial is invariant
    under a group action
  * finiteAction -- the group action generated by a list
    of matrices

Ways to use this method:
========================

  * "invariants(FiniteGroupAction,List)"
  * invariants(FiniteGroupAction,ZZ)
    -- basis for graded component of
    invariant ring
-------------------------------------------------------------------------------

The source of this document is in InvariantRing/InvariantsDoc.m2:549:0.

invariants(LinearlyReductiveAction) -- invariant generators of Hilbert ideal
****************************************************************************

  * Function: invariants,
  * Usage:
        invariants V
  * Inputs:
      * V, an instance of the type LinearlyReductiveAction,
  * Optional inputs (Macaulay2Doc),:
      * Strategy (missing documentation) => ..., default value UseNormaliz, the
        strategy used to compute diagonal invariants, options are UsePolyhedra
        or UseNormaliz.
      * DegreeBound,
        => ..., default value infinity, degree bound for invariants of finite
        groups
      * DegreeLimit,
        => ..., default value {}, GB option for invariants
      * SubringLimit,
        => ..., default value infinity, GB option for invariants
      * UseCoefficientRing,
        => ...,
        default value false, option to compute invariants over the given
        coefficient ring
      * UseLinearAlgebra,
        => ...,
        default value false, strategy for computing invariants of finite groups
  * Outputs:
      * L, a list (Macaulay2Doc), of invariants generating the
        Hilbert ideal

Description
===========

This function is provided by the package InvariantRing,

When called on a linearly reductive group action and a degree, this function
returns a list of generators for the Hilbert ideal that are also invariant
under the action. This function computes the Hilbert ideal first using
hilbertIdeal, then finds invariant generators degree by degree
using invariants(LinearlyReductiveAction,ZZ).

The next example constructs a cyclic group of order 2 as a set of two affine
points. Then it introduces an action of this group on a polynomial ring in two
variables and computes the Hilbert ideal. The action permutes the variables of
the polynomial ring.

+------------------------------------------------------+
|i1 : S = QQ[z]                                        |
|                                                      |
|o1 = S                                                |
|                                                      |
|o1 : PolynomialRing                                   |
+------------------------------------------------------+
|i2 : I = ideal(z^2 - 1)                               |
|                                                      |
|            2                                         |
|o2 = ideal(z  - 1)                                    |
|                                                      |
|o2 : Ideal of S                                       |
+------------------------------------------------------+
|i3 : M = matrix{{(z+1)/2, (1-z)/2},{(1-z)/2, (z+1)/2}}|
|                                                      |
|o3 = | 1/2z+1/2  -1/2z+1/2 |                          |
|     | -1/2z+1/2 1/2z+1/2  |                          |
|                                                      |
|             2      2                                 |
|o3 : Matrix S  <-- S                                  |
+------------------------------------------------------+
|i4 : sub(M,z=>1),sub(M,z=>-1)                         |
|                                                      |
|o4 = (| 1 0 |, | 0 1 |)                               |
|      | 0 1 |  | 1 0 |                                |
|                                                      |
|o4 : Sequence                                         |
+------------------------------------------------------+
|i5 : R = QQ[x,y]                                      |
|                                                      |
|o5 = R                                                |
|                                                      |
|o5 : PolynomialRing                                   |
+------------------------------------------------------+
|i6 : V = linearlyReductiveAction(I, M, R)             |
|                                                      |
|                   2                                  |
|o6 = R <- S/ideal(z  - 1) via                         |
|                                                      |
|     | 1/2z+1/2  -1/2z+1/2 |                          |
|     | -1/2z+1/2 1/2z+1/2  |                          |
|                                                      |
|o6 : LinearlyReductiveAction                          |
+------------------------------------------------------+
|i7 : H = hilbertIdeal V                               |
|                                                      |
|                    2                                 |
|o7 = ideal (x + y, y )                                |
|                                                      |
|o7 : Ideal of R                                       |
+------------------------------------------------------+
|i8 : invariants V                                     |
|                                                      |
|o8 = {x + y, x*y}                                     |
|                                                      |
|o8 : List                                             |
+------------------------------------------------------+

The algorithm for the Hilbert ideal performs an elimination using Groebner
bases. The options DegreeLimit (Macaulay2Doc), and
SubringLimit (Macaulay2Doc), are standard gb (Macaulay2Doc),
options that can be used to interrupt the computation before
it is complete, yielding a partial list of invariant generators for the Hilbert
ideal.

Caveat
======

Both hilbertIdeal, and
invariants(LinearlyReductiveAction,ZZ),
require Groebner bases
computations, which could lead to long running times. It might be helpful to
run these functions separately.

See also
========

  * hilbertIdeal -- compute generators for the Hilbert
    ideal
  * invariants -- computes the generating invariants of a
    group action

Ways to use this method:
========================

  * invariants(LinearlyReductiveAction)
    -- invariant generators of Hilbert
    ideal
-------------------------------------------------------------------------------

The source of this document is in InvariantRing/InvariantsDoc.m2:681:0.

invariants(LinearlyReductiveAction,ZZ) -- basis for graded component of invariant ring
**************************************************************************************

  * Function: invariants,
  * Usage:
        invariants(V,d)
  * Inputs:
      * V, an instance of the type LinearlyReductiveAction,
      * d, an integer (Macaulay2Doc), a degree or multidegree
  * Optional inputs (Macaulay2Doc),:
      * Strategy (missing documentation) => ..., default value UseNormaliz, the
        strategy used to compute diagonal invariants, options are UsePolyhedra
        or UseNormaliz.
      * DegreeBound,
        => ..., default value infinity, degree bound for invariants of finite
        groups
      * DegreeLimit,
        => ..., default value {}, GB option for invariants
      * SubringLimit,
        => ..., default value infinity, GB option for invariants
      * UseCoefficientRing,
        => ...,
        default value false, option to compute invariants over the given
        coefficient ring
      * UseLinearAlgebra,
        => ...,
        default value false, strategy for computing invariants of finite groups
  * Outputs:
      * L, a list (Macaulay2Doc), an additive basis for a graded
        component of the ring of invariants

Description
===========

This function is provided by the package InvariantRing,

When called on a linearly reductive group action and a (multi)degree, it
computes an additive basis for the invariants of the action in the given
degree.

This function uses an implementation of Algorithm 4.5.1 in:

  * Derksen, H. & Kemper, G. (2015).Computational Invariant Theory. Heidelberg:
    Springer.

The following example examines the action of the special linear group of degree
2 on the space of binary quadrics. There is a single invariant of degree 2 but
no invariant of degree 3.

+-----------------------------------------------------------------------------+
|i1 : S = QQ[a,b,c,d]                                                         |
|                                                                             |
|o1 = S                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : I = ideal(a*d - b*c - 1)                                                |
|                                                                             |
|o2 = ideal(- b*c + a*d - 1)                                                  |
|                                                                             |
|o2 : Ideal of S                                                              |
+-----------------------------------------------------------------------------+
|i3 : A = S[u,v]                                                              |
|                                                                             |
|o3 = A                                                                       |
|                                                                             |
|o3 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i4 : M = transpose (map(S,A)) last coefficients                              |
|                                                                             |
|o4 = | a2 2ab   b2 |                                                         |
|     | ac bc+ad bd |                                                         |
|     | c2 2cd   d2 |                                                         |
|                                                                             |
|             3      3                                                        |
|o4 : Matrix S  <-- S                                                         |
|-----------------------------------------------------------------------------|
|sub(basis(2,A),{u=>a*u+b*v,v=>c*u+d*v})                                      |
+-----------------------------------------------------------------------------+
|i5 : R = QQ[x_1..x_3]                                                        |
|                                                                             |
|o5 = R                                                                       |
|                                                                             |
|o5 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i6 : V = linearlyReductiveAction(I,M,R)                                      |
|                                                                             |
|o6 = R <- S/ideal(- b*c + a*d - 1) via                                       |
|                                                                             |
|     | a2 2ab   b2 |                                                         |
|     | ac bc+ad bd |                                                         |
|     | c2 2cd   d2 |                                                         |
|                                                                             |
|o6 : LinearlyReductiveAction                                                 |
+-----------------------------------------------------------------------------+
|i7 : invariants(V,2)                                                         |
|                                                                             |
|       2                                                                     |
|o7 = {x  - 4x x }                                                            |
|       2     1 3                                                             |
|                                                                             |
|o7 : List                                                                    |
+-----------------------------------------------------------------------------+
|i8 : invariants(V,3)                                                         |
|                                                                             |
|o8 = {}                                                                      |
|                                                                             |
|o8 : List                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * invariantRing -- the ring of invariants of a group
    action
  * isInvariant -- check whether a polynomial is invariant
    under a group action
  * linearlyReductiveAction -- Linearly
    reductive group action

Ways to use this method:
========================

  * "invariants(LinearlyReductiveAction,List)"
  * invariants(LinearlyReductiveAction,ZZ)
    -- basis for graded component
    of invariant ring
-------------------------------------------------------------------------------

The source of this document is in InvariantRing/InvariantsDoc.m2:608:0.

isAbelian -- check whether a finite matrix group is Abelian
***********************************************************

  * Usage:
        isAbelian G
  * Inputs:
      * G, an instance of the type FiniteGroupAction,
  * Outputs:
      * a Boolean value (Macaulay2Doc), whether the group
        associated to the action is Abelian

Description
===========

This function is provided by the package InvariantRing.

The following example defines the action of a symmetric group permuting the
three variables generating a polynomial ring.

+--------------------------------------------------------------+
|i1 : R = QQ[x_1..x_4]                                         |
|                                                              |
|o1 = R                                                        |
|                                                              |
|o1 : PolynomialRing                                           |
+--------------------------------------------------------------+
|i2 : P = apply(3, i -> permutationMatrix(4, [i + 1, i + 2] ) )|
|                                                              |
|o2 = {| 0 1 0 0 |, | 1 0 0 0 |, | 1 0 0 0 |}                  |
|      | 1 0 0 0 |  | 0 0 1 0 |  | 0 1 0 0 |                   |
|      | 0 0 1 0 |  | 0 1 0 0 |  | 0 0 0 1 |                   |
|      | 0 0 0 1 |  | 0 0 0 1 |  | 0 0 1 0 |                   |
|                                                              |
|o2 : List                                                     |
+--------------------------------------------------------------+
|i3 : S4 = finiteAction(P, R)                                  |
|                                                              |
|o3 = R <- {| 0 1 0 0 |, | 1 0 0 0 |, | 1 0 0 0 |}             |
|           | 1 0 0 0 |  | 0 0 1 0 |  | 0 1 0 0 |              |
|           | 0 0 1 0 |  | 0 1 0 0 |  | 0 0 0 1 |              |
|           | 0 0 0 1 |  | 0 0 0 1 |  | 0 0 1 0 |              |
|                                                              |
|o3 : FiniteGroupAction                                        |
+--------------------------------------------------------------+
|i4 : isAbelian S4                                             |
|                                                              |
|o4 = false                                                    |
+--------------------------------------------------------------+

The following example defines the action of the product of two cyclic groups.
One group has order 3 and cyclically permutes the three variables generating a
polynomial ring. The other group has order 2 and multiplies the variables by
-1.

+-----------------------------------------------------------------------------+
|i5 : R = QQ[x_1..x_3]                                                        |
|                                                                             |
|o5 = R                                                                       |
|                                                                             |
|o5 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i6 : L = {matrix {{0,0,1},{0,1,0},{1,0,0}}, matrix                           |
|                                                                             |
|o6 = {| 0 0 1 |, | -1 0  0  |}                                               |
|      | 0 1 0 |  | 0  -1 0  |                                                |
|      | 1 0 0 |  | 0  0  -1 |                                                |
|                                                                             |
|o6 : List                                                                    |
|-----------------------------------------------------------------------------|
|{{-1,0,0},{0,-1,0},{0,0,-1}} }                                               |
+-----------------------------------------------------------------------------+
|i7 : G = finiteAction(L, R)                                                  |
|                                                                             |
|o7 = R <- {| 0 0 1 |, | -1 0  0  |}                                          |
|           | 0 1 0 |  | 0  -1 0  |                                           |
|           | 1 0 0 |  | 0  0  -1 |                                           |
|                                                                             |
|o7 : FiniteGroupAction                                                       |
+-----------------------------------------------------------------------------+
|i8 : isAbelian G                                                             |
|                                                                             |
|o8 = true                                                                    |
+-----------------------------------------------------------------------------+

Ways to use isAbelian:
======================

  * "isAbelian(FiniteGroupAction)"

For the programmer
==================

The object isAbelian, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in InvariantRing/FiniteGroupsDoc.m2:186:0.

isInvariant -- check whether a polynomial is invariant under a group action
***************************************************************************

  * Usage:
        isInvariant(f, G), isInvariant(f, D), isInvariant(f, L)
  * Inputs:
      * f, a ring element (Macaulay2Doc), a polynomial in
        the polynomial ring on which the group acts
      * G, an instance of the type FiniteGroupAction,
      * D, an instance of the type DiagonalAction,
      * L, an instance of the type LinearlyReductiveAction,
  * Outputs:
      * a Boolean value (Macaulay2Doc), whether the given
        polynomial is invariant under the given group action

Description
===========

This function is provided by the package InvariantRing.

This function checks if a polynomial is invariant under a certain group action.

The following example defines the permutation action of a symmetric group on a
polynomial ring with three variables.

+--------------------------------------------------------------+
|i1 : R = QQ[x_1..x_3]                                         |
|                                                              |
|o1 = R                                                        |
|                                                              |
|o1 : PolynomialRing                                           |
+--------------------------------------------------------------+
|i2 : L = apply(2, i -> permutationMatrix(3, [i + 1, i + 2] ) )|
|                                                              |
|o2 = {| 0 1 0 |, | 1 0 0 |}                                   |
|      | 1 0 0 |  | 0 0 1 |                                    |
|      | 0 0 1 |  | 0 1 0 |                                    |
|                                                              |
|o2 : List                                                     |
+--------------------------------------------------------------+
|i3 : S3 = finiteAction(L, R)                                  |
|                                                              |
|o3 = R <- {| 0 1 0 |, | 1 0 0 |}                              |
|           | 1 0 0 |  | 0 0 1 |                               |
|           | 0 0 1 |  | 0 1 0 |                               |
|                                                              |
|o3 : FiniteGroupAction                                        |
+--------------------------------------------------------------+
|i4 : isInvariant(1 + x_1^2 + x_2^2 + x_3^2, S3)               |
|                                                              |
|o4 = true                                                     |
+--------------------------------------------------------------+
|i5 : isInvariant(x_1*x_2*x_3^2, S3)                           |
|                                                              |
|o5 = false                                                    |
+--------------------------------------------------------------+

Here is an example with a two-dimensional torus acting on polynomial ring in
four variables:

+----------------------------------------+
|i6 : R = QQ[x_1..x_4]                   |
|                                        |
|o6 = R                                  |
|                                        |
|o6 : PolynomialRing                     |
+----------------------------------------+
|i7 : W = matrix{{0,1,-1,1}, {1,0,-1,-1}}|
|                                        |
|o7 = | 0 1 -1 1  |                      |
|     | 1 0 -1 -1 |                      |
|                                        |
|              2       4                 |
|o7 : Matrix ZZ  <-- ZZ                  |
+----------------------------------------+
|i8 : T = diagonalAction(W, R)           |
|                                        |
|             * 2                        |
|o8 = R <- (QQ )  via                    |
|                                        |
|     | 0 1 -1 1  |                      |
|     | 1 0 -1 -1 |                      |
|                                        |
|o8 : DiagonalAction                     |
+----------------------------------------+
|i9 : isInvariant(x_1*x_2*x_3, T)        |
|                                        |
|o9 = true                               |
+----------------------------------------+
|i10 : isInvariant(x_1*x_2*x_4, T)       |
|                                        |
|o10 = false                             |
+----------------------------------------+

Here is another example of a product of two cyclic groups of order 3 acting on
a three-dimensional vector space:

+-------------------------------------+
|i11 : R = QQ[x_1..x_3]               |
|                                     |
|o11 = R                              |
|                                     |
|o11 : PolynomialRing                 |
+-------------------------------------+
|i12 : W = matrix{{1,0,1}, {0,1,1}}   |
|                                     |
|o12 = | 1 0 1 |                      |
|      | 0 1 1 |                      |
|                                     |
|               2       3             |
|o12 : Matrix ZZ  <-- ZZ              |
+-------------------------------------+
|i13 : A = diagonalAction(W, {3,3}, R)|
|                                     |
|o13 = R <- ZZ/3 x ZZ/3 via           |
|                                     |
|      | 1 0 1 |                      |
|      | 0 1 1 |                      |
|                                     |
|o13 : DiagonalAction                 |
+-------------------------------------+
|i14 : isInvariant(x_1*x_2*x_3, A)    |
|                                     |
|o14 = false                          |
+-------------------------------------+
|i15 : isInvariant((x_1*x_2*x_3)^3, A)|
|                                     |
|o15 = true                           |
+-------------------------------------+

Here is an example with a general linear group acting by conjugation on a space
of matrices (determinant and trace are invariants).

+--------------------------------------------------------------+
|i16 : S = QQ[a,b,c,d,t]                                       |
|                                                              |
|o16 = S                                                       |
|                                                              |
|o16 : PolynomialRing                                          |
+--------------------------------------------------------------+
|i17 : I = ideal((det genericMatrix(S,2,2))*t-1)               |
|                                                              |
|o17 = ideal(- b*c*t + a*d*t - 1)                              |
|                                                              |
|o17 : Ideal of S                                              |
+--------------------------------------------------------------+
|i18 : R = QQ[x_(1,1)..x_(2,2)]                                |
|                                                              |
|o18 = R                                                       |
|                                                              |
|o18 : PolynomialRing                                          |
+--------------------------------------------------------------+
|i19 : Q = (S/I)(monoid R);                                    |
+--------------------------------------------------------------+
|i20 : G = transpose genericMatrix(S/I,2,2)                    |
|                                                              |
|o20 = {-1} | a b |                                            |
|      {-1} | c d |                                            |
|                                                              |
|                       S          2               S          2|
|o20 : Matrix (-------------------)  <-- (-------------------) |
|              - b*c*t + a*d*t - 1        - b*c*t + a*d*t - 1  |
+--------------------------------------------------------------+
|i21 : X = transpose genericMatrix(Q,x_(1,1),2,2)              |
|                                                              |
|o21 = {-1, 0} | x_(1,1) x_(1,2) |                             |
|      {-1, 0} | x_(2,1) x_(2,2) |                             |
|                                                              |
|              2      2                                        |
|o21 : Matrix Q  <-- Q                                         |
+--------------------------------------------------------------+
|i22 : N = reshape(Q^1,Q^4,transpose(inverse(G)*X*G));         |
|                                                              |
|              1      4                                        |
|o22 : Matrix Q  <-- Q                                         |
+--------------------------------------------------------------+
|i23 : phi = map(S,Q);                                         |
|                                                              |
|o23 : RingMap S <-- Q                                         |
+--------------------------------------------------------------+
|i24 : M = phi last coefficients N;                            |
|                                                              |
|              4      4                                        |
|o24 : Matrix S  <-- S                                         |
+--------------------------------------------------------------+
|i25 : L = linearlyReductiveAction(I, M, R)                    |
|                                                              |
|o25 = R <- S/ideal(- b*c*t + a*d*t - 1) via                   |
|                                                              |
|      | adt    bdt  -act -adt+1 |                             |
|      | cdt    d2t  -c2t -cdt   |                             |
|      | -abt   -b2t a2t  abt    |                             |
|      | -adt+1 -bdt act  adt    |                             |
|                                                              |
|o25 : LinearlyReductiveAction                                 |
+--------------------------------------------------------------+
|i26 : isInvariant(det genericMatrix(R,2,2),L)                 |
|                                                              |
|o26 = true                                                    |
+--------------------------------------------------------------+
|i27 : isInvariant(trace genericMatrix(R,2,2),L)               |
|                                                              |
|o27 = true                                                    |
+--------------------------------------------------------------+

Ways to use isInvariant:
========================

  * "isInvariant(RingElement,DiagonalAction)"
  * "isInvariant(RingElement,FiniteGroupAction)"
  * "isInvariant(RingElement,LinearlyReductiveAction)"

For the programmer
==================

The object isInvariant, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in InvariantRing/InvariantsDoc.m2:817:0.

LinearlyReductiveAction -- the class of all (non finite, non toric) linearly reductive group actions
****************************************************************************************************

Description
===========

This class is provided by the package InvariantRing.

LinearlyReductiveAction is the class of all linearly reductive group actions on
(quotients of) polynomial rings for the        purpose of computing invariants.
It is created using linearlyReductiveAction.
This class should not be used for actions of tori or finite groups, as its
methods for computing invariants are in general less efficient than specialized
methods for the classes FiniteGroupAction, and
DiagonalAction.

Functions and methods returning an object of class LinearlyReductiveAction:
===========================================================================

  * "linearlyReductiveAction(Ideal,Matrix,PolynomialRing)" -- see
    linearlyReductiveAction, -- Linearly reductive
    group action
  * "linearlyReductiveAction(Ideal,Matrix,QuotientRing)" -- see
    linearlyReductiveAction, -- Linearly reductive
    group action

Methods that use an object of class LinearlyReductiveAction:
============================================================

  * "actionMatrix(LinearlyReductiveAction)" -- see actionMatrix,
    -- matrix of a linearly reductive action
  * "groupIdeal(LinearlyReductiveAction)" -- see groupIdeal,
    -- ideal defining a linearly reductive group
  * "hilbertIdeal(LinearlyReductiveAction)" -- see hilbertIdeal,
    -- compute generators for the Hilbert ideal
  * "QuotientRing ^ LinearlyReductiveAction" -- see invariantRing,
    -- the ring of invariants of a group action
  * invariants(LinearlyReductiveAction)
    -- invariant generators of Hilbert
    ideal
  * "invariants(LinearlyReductiveAction,List)" -- see
    invariants(LinearlyReductiveAction,ZZ),
    -- basis for graded component
    of invariant ring
  * invariants(LinearlyReductiveAction,ZZ)
    -- basis for graded component
    of invariant ring
  * "isInvariant(RingElement,LinearlyReductiveAction)" -- see
    isInvariant, -- check whether a polynomial is invariant under
    a group action
  * "net(LinearlyReductiveAction)" -- see net(RingOfInvariants),
    -- format for printing, as a net

For the programmer
==================

The object LinearlyReductiveAction, is a
type (Macaulay2Doc), with ancestor classes GroupAction,
< HashTable (Macaulay2Doc) < Thing (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in
InvariantRing/LinearlyReductiveGroupsDoc.m2:246:0.

linearlyReductiveAction -- Linearly reductive group action
**********************************************************

  * Usage:
        linearlyReductiveAction(I, M, R)
        linearlyReductiveAction(I, M, Q)
  * Inputs:
      * I, an ideal (Macaulay2Doc), of a polynomial ring S
        defining a group as an affine variety
      * M, a matrix (Macaulay2Doc), whose entries are in S, that
        encodes the group action on R
      * R, a polynomial ring (Macaulay2Doc), on which the
        group acts
      * Q, a quotient ring (Macaulay2Doc), on which the
        group acts
  * Outputs:
      * an instance of the type LinearlyReductiveAction,
        the linearly reductive action of S/I on R or
        Q via the matrix M

Description
===========

This function is provided by the package InvariantRing.

In order to encode a linearly reductive group action, we represent the group as
an affine variety. The polynomial ring S is the coordinate ring of the ambient
affine space containing the group, while I is the ideal of S defining the group
as a subvariety. In other words, the elements of the group are the points of
the affine variety with coordinate ring S/I. The group acts linearly on the
polynomial ring R via the matrix M with entries in S.

The next example constructs a cyclic group of order 2 as a set of two affine
points. Then it introduces an action of this group on a polynomial ring in two
variables.

+------------------------------------------------------+
|i1 : S = QQ[z]                                        |
|                                                      |
|o1 = S                                                |
|                                                      |
|o1 : PolynomialRing                                   |
+------------------------------------------------------+
|i2 : I = ideal(z^2 - 1)                               |
|                                                      |
|            2                                         |
|o2 = ideal(z  - 1)                                    |
|                                                      |
|o2 : Ideal of S                                       |
+------------------------------------------------------+
|i3 : M = matrix{{(z+1)/2, (1-z)/2},{(1-z)/2, (z+1)/2}}|
|                                                      |
|o3 = | 1/2z+1/2  -1/2z+1/2 |                          |
|     | -1/2z+1/2 1/2z+1/2  |                          |
|                                                      |
|             2      2                                 |
|o3 : Matrix S  <-- S                                  |
+------------------------------------------------------+
|i4 : sub(M,z=>1),sub(M,z=>-1)                         |
|                                                      |
|o4 = (| 1 0 |, | 0 1 |)                               |
|      | 0 1 |  | 1 0 |                                |
|                                                      |
|o4 : Sequence                                         |
+------------------------------------------------------+
|i5 : R = QQ[x,y]                                      |
|                                                      |
|o5 = R                                                |
|                                                      |
|o5 : PolynomialRing                                   |
+------------------------------------------------------+
|i6 : L = linearlyReductiveAction(I, M, R)             |
|                                                      |
|                   2                                  |
|o6 = R <- S/ideal(z  - 1) via                         |
|                                                      |
|     | 1/2z+1/2  -1/2z+1/2 |                          |
|     | -1/2z+1/2 1/2z+1/2  |                          |
|                                                      |
|o6 : LinearlyReductiveAction                          |
+------------------------------------------------------+

This function is also used to define linearly reductive group actions on
quotients of polynomial rings. We illustrate by a slight variation on the
previous example.

+-------------------------------------------------------+
|i7 : S = QQ[z];                                        |
+-------------------------------------------------------+
|i8 : I = ideal(z^2 - 1);                               |
|                                                       |
|o8 : Ideal of S                                        |
+-------------------------------------------------------+
|i9 : M = matrix{{(z+1)/2, (1-z)/2},{(1-z)/2, (z+1)/2}};|
|                                                       |
|             2      2                                  |
|o9 : Matrix S  <-- S                                   |
+-------------------------------------------------------+
|i10 : Q = QQ[x,y] / ideal(x*y)                         |
|                                                       |
|o10 = Q                                                |
|                                                       |
|o10 : QuotientRing                                     |
+-------------------------------------------------------+
|i11 : L = linearlyReductiveAction(I, M, Q)             |
|                                                       |
|                    2                                  |
|o11 = Q <- S/ideal(z  - 1) via                         |
|                                                       |
|      | 1/2z+1/2  -1/2z+1/2 |                          |
|      | -1/2z+1/2 1/2z+1/2  |                          |
|                                                       |
|o11 : LinearlyReductiveAction                          |
+-------------------------------------------------------+

Ways to use linearlyReductiveAction:
====================================

  * "linearlyReductiveAction(Ideal,Matrix,PolynomialRing)"
  * "linearlyReductiveAction(Ideal,Matrix,QuotientRing)"

For the programmer
==================

The object linearlyReductiveAction, is a
method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in
InvariantRing/LinearlyReductiveGroupsDoc.m2:224:0.

molienSeries -- computes the Molien (Hilbert) series of the invariant ring of a finite group
********************************************************************************************

  * Usage:
        molienSeries G
  * Inputs:
      * G, an instance of the type FiniteGroupAction,
  * Outputs:
      * a divide expression (Macaulay2Doc), the Molien series of
        the invariant ring of G as a rational function

Description
===========

This function is provided by the package InvariantRing.

The example below computes the Molien series for the dihedral group with 6
elements. K is the field obtained by adjoining a primitive third root of unity
to QQ (Macaulay2Doc).

+-------------------------------------+
|i1 : K=toField(QQ[a]/(a^2+a+1));     |
+-------------------------------------+
|i2 : A=matrix{{a,0},{0,a^2}};        |
|                                     |
|             2      2                |
|o2 : Matrix K  <-- K                 |
+-------------------------------------+
|i3 : B=sub(matrix{{0,1},{1,0}},K);   |
|                                     |
|             2      2                |
|o3 : Matrix K  <-- K                 |
+-------------------------------------+
|i4 : D6=finiteAction({A,B},K[x,y])   |
|                                     |
|o4 = K[x..y] <- {| a 0    |, | 0 1 |}|
|                 | 0 -a-1 |  | 1 0 | |
|                                     |
|o4 : FiniteGroupAction               |
+-------------------------------------+
|i5 : molienSeries D6                 |
|                                     |
|             1                       |
|o5 = ----------------                |
|           2       3                 |
|     (1 - T )(1 - T )                |
|                                     |
|o5 : Expression of class Divide      |
+-------------------------------------+

Ways to use molienSeries:
=========================

  * "molienSeries(FiniteGroupAction)"

For the programmer
==================

The object molienSeries, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in InvariantRing/HawesDoc.m2:111:0.

net(RingOfInvariants) -- format for printing, as a net
******************************************************

  * Function: net (Macaulay2Doc),

Description
===========

Format objects of the package InvariantRing, for printing. See
net (Macaulay2Doc), for more information.

Ways to use this method:
========================

  * "net(DiagonalAction)"
  * "net(FiniteGroupAction)"
  * "net(LinearlyReductiveAction)"
  * net(RingOfInvariants) -- format for
    printing, as a net
-------------------------------------------------------------------------------

The source of this document is in InvariantRing/InvariantRingDoc.m2:182:0.

numgens(DiagonalAction) -- number of generators of the finite part of a diagonal group
**************************************************************************************

  * Function: numgens (Macaulay2Doc),
  * Usage:
        numgens D
  * Inputs:
      * D, an instance of the type DiagonalAction, the
        action of a diagonal group
  * Outputs:
      * an integer (Macaulay2Doc), the number of generators of the
        group

Description
===========

This function is provided by the package InvariantRing.

Writing the diagonal group acting on the polynomial ring $k[x_1,\dots,x_n]$ as
$(k^*)^r \times \mathbb{Z}/d_1 \times \cdots \times \mathbb{Z}/d_g$, this
function returns g.

Here is an example of a product of two cyclic groups of order 3 acting on a
polynomial ring in 3 variables.

+--------------------------------+
|i1 : R = QQ[x_1..x_3]           |
|                                |
|o1 = R                          |
|                                |
|o1 : PolynomialRing             |
+--------------------------------+
|i2 : d = {3,3}                  |
|                                |
|o2 = {3, 3}                     |
|                                |
|o2 : List                       |
+--------------------------------+
|i3 : W = matrix{{1,0,1},{0,1,1}}|
|                                |
|o3 = | 1 0 1 |                  |
|     | 0 1 1 |                  |
|                                |
|              2       3         |
|o3 : Matrix ZZ  <-- ZZ          |
+--------------------------------+
|i4 : A = diagonalAction(W, d, R)|
|                                |
|o4 = R <- ZZ/3 x ZZ/3 via       |
|                                |
|     | 1 0 1 |                  |
|     | 0 1 1 |                  |
|                                |
|o4 : DiagonalAction             |
+--------------------------------+
|i5 : numgens A                  |
|                                |
|o5 = 2                          |
+--------------------------------+

Ways to use this method:
========================

  * numgens(DiagonalAction) -- number of
    generators of the finite part of a diagonal group
-------------------------------------------------------------------------------

The source of this document is in InvariantRing/AbelianGroupsDoc.m2:219:0.

numgens(FiniteGroupAction) -- number of generators of a finite group
********************************************************************

  * Function: numgens (Macaulay2Doc),
  * Usage:
        numgens G
  * Inputs:
      * G, an instance of the type FiniteGroupAction,
        the action of a finite group
  * Outputs:
      * an integer (Macaulay2Doc), the number of generators of the
        group

Description
===========

This function is provided by the package InvariantRing.

Use this function to get the number of user-defined generators of a group
action.

The following example defines the permutation action of a symmetric group on
three elements using three transpositions.

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x_1..x_3]                                                        |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : L = {matrix {{0,1,0},{1,0,0},{0,0,1}}, matrix {{0,0,1},{0,1,0},{1,0,0}},|
|                                                                             |
|o2 = {| 0 1 0 |, | 0 0 1 |, | 1 0 0 |}                                       |
|      | 1 0 0 |  | 0 1 0 |  | 0 0 1 |                                        |
|      | 0 0 1 |  | 1 0 0 |  | 0 1 0 |                                        |
|                                                                             |
|o2 : List                                                                    |
|-----------------------------------------------------------------------------|
|matrix {{1,0,0},{0,0,1},{0,1,0}} }                                           |
+-----------------------------------------------------------------------------+
|i3 : G = finiteAction(L, R)                                                  |
|                                                                             |
|o3 = R <- {| 0 1 0 |, | 0 0 1 |, | 1 0 0 |}                                  |
|           | 1 0 0 |  | 0 1 0 |  | 0 0 1 |                                   |
|           | 0 0 1 |  | 1 0 0 |  | 0 1 0 |                                   |
|                                                                             |
|o3 : FiniteGroupAction                                                       |
+-----------------------------------------------------------------------------+
|i4 : numgens G                                                               |
|                                                                             |
|o4 = 3                                                                       |
+-----------------------------------------------------------------------------+

Caveat
======

The integer returned by this function is not necessarily the minimal number of
generators of the group, rather it is the cardinality of the generating set
defined by the user.

Ways to use this method:
========================

  * numgens(FiniteGroupAction) -- number
    of generators of a finite group
-------------------------------------------------------------------------------

The source of this document is in InvariantRing/FiniteGroupsDoc.m2:222:0.

permutationMatrix -- convert a one-line notation or cyclic notation of a permutation to a matrix representation
***************************************************************************************************************

  * Usage:
        permutationMatrix s, permutationMatrix(n , c)
  * Inputs:
      * s, a string (Macaulay2Doc), an array or a list of arrays
        giving a one-line notation or cyclic notation of a permutation
      * n, an integer (Macaulay2Doc), giving the number of integers
        getting permuted
      * c, a list (Macaulay2Doc), of arrays giving a cyclic
        notation of a permutation
  * Outputs:
      * a matrix (Macaulay2Doc), the matrix representation of the
        permutation

Description
===========

This function is provided by the package InvariantRing.

The following example converts the one-line notation of a transposition into a
matrix representation.

+---------------------------------------+
|i1 : M = permutationMatrix toString 213|
|                                       |
|o1 = | 0 1 0 |                         |
|     | 1 0 0 |                         |
|     | 0 0 1 |                         |
|                                       |
|              3       3                |
|o1 : Matrix ZZ  <-- ZZ                 |
+---------------------------------------+

The following example converts the cyclic notation of the same transposition
into a matrix representation. Without n the function assumes n is the largest
integer that appears in your array or list of arrays.

+-----------------------------------+
|i2 : M = permutationMatrix(3,[1,2])|
|                                   |
|o2 = | 0 1 0 |                     |
|     | 1 0 0 |                     |
|     | 0 0 1 |                     |
|                                   |
|              3       3            |
|o2 : Matrix ZZ  <-- ZZ             |
+-----------------------------------+
|i3 : M = permutationMatrix [1,2]   |
|                                   |
|o3 = | 0 1 |                       |
|     | 1 0 |                       |
|                                   |
|              2       2            |
|o3 : Matrix ZZ  <-- ZZ             |
+-----------------------------------+

The following example converts the cyclic notation of a permutation of 4 into a
matrix representation.

+-------------------------------------------+
|i4 : M = permutationMatrix(4,{[1,2],[3,4]})|
|                                           |
|o4 = | 0 1 0 0 |                           |
|     | 1 0 0 0 |                           |
|     | 0 0 0 1 |                           |
|     | 0 0 1 0 |                           |
|                                           |
|              4       4                    |
|o4 : Matrix ZZ  <-- ZZ                     |
+-------------------------------------------+
|i5 : M = permutationMatrix {[1,2],[3,4]}   |
|                                           |
|o5 = | 0 1 0 0 |                           |
|     | 1 0 0 0 |                           |
|     | 0 0 0 1 |                           |
|     | 0 0 1 0 |                           |
|                                           |
|              4       4                    |
|o5 : Matrix ZZ  <-- ZZ                     |
+-------------------------------------------+

Ways to use permutationMatrix:
==============================

  * "permutationMatrix(Array)"
  * "permutationMatrix(List)"
  * "permutationMatrix(String)"
  * "permutationMatrix(ZZ,Array)"
  * "permutationMatrix(ZZ,List)"

For the programmer
==================

The object permutationMatrix, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in InvariantRing/FiniteGroupsDoc.m2:346:0.

primaryInvariants -- computes a list of primary invariants for the invariant ring of a finite group
***************************************************************************************************

  * Usage:
        primaryInvariants G
  * Inputs:
      * G, an instance of the type FiniteGroupAction,
  * Optional inputs (Macaulay2Doc),:
      * Dade, => ...,
        default value false, an optional argument for primaryInvariants
        determining whether to use the Dade algorithm
      * DegreeVector,
        => ..., default value 0, an optional argument for
        primaryInvariants that finds invariants of certain degrees
  * Outputs:
      * a list (Macaulay2Doc),  consisting of a homogeneous system
        of parameters (hsop) for the invariant ring of the group action

Description
===========

There are two algorithms implemented in primaryInvariants.
The default algorithm (corresponding to the optional
argument Dade, taking
the value false (Macaulay2Doc)) currently only works with
polynomial rings over fields of characteristic zero. The second is the Dade
algorithm, corresponding to the optional argument Dade,
taking the value
true (Macaulay2Doc). This algorithm can calculate an hsop over finite
fields, so long as the field is sufficiently large. See hsop algorithms,
for a discussion comparing the two algorithms.

+--------------------------------------------------------------------+
|i1 : A=matrix{{0,1,0},{0,0,1},{1,0,0}};                             |
|                                                                    |
|              3       3                                             |
|o1 : Matrix ZZ  <-- ZZ                                              |
+--------------------------------------------------------------------+
|i2 : B=matrix{{0,1,0},{1,0,0},{0,0,1}};                             |
|                                                                    |
|              3       3                                             |
|o2 : Matrix ZZ  <-- ZZ                                              |
+--------------------------------------------------------------------+
|i3 : S3=finiteAction({A,B},QQ[x,y,z])                               |
|                                                                    |
|o3 = QQ[x..z] <- {| 0 1 0 |, | 0 1 0 |}                             |
|                  | 0 0 1 |  | 1 0 0 |                              |
|                  | 1 0 0 |  | 0 0 1 |                              |
|                                                                    |
|o3 : FiniteGroupAction                                              |
+--------------------------------------------------------------------+
|i4 : primaryInvariants S3                                           |
|                                                                    |
|                  2    2    2   2       2    2     2       2      2 |
|o4 = {x + y + z, x  + y  + z , x y + x*y  + x z + y z + x*z  + y*z }|
|                                                                    |
|o4 : List                                                           |
+--------------------------------------------------------------------+

                                   S3
Below, the invariant ring QQ[x,y,z]   is calculated with K being the field with
101 elements.

+-----------------------------------------------------------------------------+
|i5 : K=GF(101)                                                               |
|                                                                             |
|o5 = K                                                                       |
|                                                                             |
|o5 : GaloisField                                                             |
+-----------------------------------------------------------------------------+
|i6 : S3=finiteAction({A,B},K[x,y,z])                                         |
|                                                                             |
|o6 = K[x..z] <- {| 0 1 0 |, | 0 1 0 |}                                       |
|                 | 0 0 1 |  | 1 0 0 |                                        |
|                 | 1 0 0 |  | 0 0 1 |                                        |
|                                                                             |
|o6 : FiniteGroupAction                                                       |
+-----------------------------------------------------------------------------+
|i7 : primaryInvariants(S3,Dade=>true)                                        |
|                                                                             |
|           6      5       4 2      3 3      2 4        5      6      5       |
|o7 = {- 45x  - 28x y - 45x y  - 42x y  - 45x y  - 28x*y  - 45y  - 28x z +    |
|     ------------------------------------------------------------------------|
|        4         3 2       2 3         4       5       4 2      3   2       |
|     11x y*z + 23x y z + 23x y z + 11x*y z - 28y z - 45x z  + 23x y*z  +     |
|     ------------------------------------------------------------------------|
|        2 2 2        3 2      4 2      3 3      2   3        2 3      3 3    |
|     18x y z  + 23x*y z  - 45y z  - 42x z  + 23x y*z  + 23x*y z  - 42y z  -  |
|     ------------------------------------------------------------------------|
|        2 4          4      2 4        5        5      6    6      5         |
|     45x z  + 11x*y*z  - 45y z  - 28x*z  - 28y*z  - 45z , 9x  + 32x y +      |
|     ------------------------------------------------------------------------|
|        4 2      3 3      2 4        5     6      5       4         3 2      |
|     13x y  - 21x y  + 13x y  + 32x*y  + 9y  + 32x z + 48x y*z + 14x y z +   |
|     ------------------------------------------------------------------------|
|        2 3         4       5       4 2      3   2      2 2 2        3 2     |
|     14x y z + 48x*y z + 32y z + 13x z  + 14x y*z  - 33x y z  + 14x*y z  +   |
|     ------------------------------------------------------------------------|
|        4 2      3 3      2   3        2 3      3 3      2 4          4      |
|     13y z  - 21x z  + 14x y*z  + 14x*y z  - 21y z  + 13x z  + 48x*y*z  +    |
|     ------------------------------------------------------------------------|
|        2 4        5        5     6     6      5       4 2      2 4        5 |
|     13y z  + 32x*z  + 32y*z  + 9z , 13x  - 43x y + 45x y  + 45x y  - 43x*y  |
|     ------------------------------------------------------------------------|
|          6      5       4         3 2       2 3         4       5       4 2 |
|     + 13y  - 43x z - 23x y*z - 39x y z - 39x y z - 23x*y z - 43y z + 45x z  |
|     ------------------------------------------------------------------------|
|          3   2      2 2 2        3 2      4 2      2   3        2 3      2 4|
|     - 39x y*z  + 29x y z  - 39x*y z  + 45y z  - 39x y*z  - 39x*y z  + 45x z |
|     ------------------------------------------------------------------------|
|              4      2 4        5        5      6                            |
|     - 23x*y*z  + 45y z  - 43x*z  - 43y*z  + 13z }                           |
|                                                                             |
|o7 : List                                                                    |
+-----------------------------------------------------------------------------+

This function is provided by the package InvariantRing.

Caveat
======

Currently users can only use primaryInvariants, to

calculate a hsop for the invariant ring over a finite field by using the Dade

algorithm. Users should enter the finite field as a GaloisField (Macaulay2Doc),
or a quotient field of the form ZZ (Macaulay2Doc),
/p and are advised to ensure that the ground field has
                            n-1
cardinality greater than |G|   , where n is the number of variables in the
polynomial ring . Using a ground field smaller than this runs the risk of the
algorithm getting stuck in an infinite loop; see primaryInvariants,
displays a warning message asking the user whether they wish
to continue with the computation in this case. See hsop algorithms,
for a discussion on the Dade algorithm.

Ways to use primaryInvariants:
==============================

  * "primaryInvariants(FiniteGroupAction)"

For the programmer
==================

The object primaryInvariants, is a method function with options (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in InvariantRing/HawesDoc.m2:175:0.

primaryInvariants(...,Dade=>...) -- an optional argument for primaryInvariants determining whether to use the Dade algorithm
****************************************************************************************************************************

  * Usage:
        primaryInvariants G
  * Inputs:
      * G, an instance of the type FiniteGroupAction,
  * Outputs:
      * a list (Macaulay2Doc),  consisting of a homogeneous system
        of parameters (hsop) for the invariant ring of the group action

Description
===========

See Dade, takes
Boolean (Macaulay2Doc), values and is set to false (Macaulay2Doc),
by default. If Dade,
is set to true (Macaulay2Doc),
then primaryInvariants, will use
the Dade algorithm to calculate a homogeneous system of parameters (hsop) for
the invariant ring of a finite group.

The example below computes the invariant ring of S3 acting on QQ[x,y,z] by
permutations on the variables. See Dade,
is set to true (Macaulay2Doc).

+-----------------------------------------------------------------------------+
|i1 : A=matrix{{0,1,0},{0,0,1},{1,0,0}};                                      |
|                                                                             |
|              3       3                                                      |
|o1 : Matrix ZZ  <-- ZZ                                                       |
+-----------------------------------------------------------------------------+
|i2 : B=matrix{{0,1,0},{1,0,0},{0,0,1}};                                      |
|                                                                             |
|              3       3                                                      |
|o2 : Matrix ZZ  <-- ZZ                                                       |
+-----------------------------------------------------------------------------+
|i3 : S3=finiteAction({A,B},QQ[x,y,z])                                        |
|                                                                             |
|o3 = QQ[x..z] <- {| 0 1 0 |, | 0 1 0 |}                                      |
|                  | 0 0 1 |  | 1 0 0 |                                       |
|                  | 1 0 0 |  | 0 0 1 |                                       |
|                                                                             |
|o3 : FiniteGroupAction                                                       |
+-----------------------------------------------------------------------------+
|i4 : primaryInvariants(S3,Dade=>true)                                        |
|                                                                             |
|                6              5               4 2              3 3          |
|o4 = {262440000x  + 1996002000x y + 5790722400x y  + 8116143300x y  +        |
|     ------------------------------------------------------------------------|
|                2 4                5             6              5            |
|     5790722400x y  + 1996002000x*y  + 262440000y  + 1996002000x z +         |
|     ------------------------------------------------------------------------|
|                 4                  3 2                2 3                   |
|     12566510100x y*z + 28505200770x y z + 28505200770x y z +                |
|     ------------------------------------------------------------------------|
|                   4               5               4 2               3   2   |
|     12566510100x*y z + 1996002000y z + 5790722400x z  + 28505200770x y*z  + |
|     ------------------------------------------------------------------------|
|                 2 2 2                 3 2              4 2              3 3 |
|     46353542149x y z  + 28505200770x*y z  + 5790722400y z  + 8116143300x z  |
|     ------------------------------------------------------------------------|
|                   2   3                 2 3              3 3                |
|     + 28505200770x y*z  + 28505200770x*y z  + 8116143300y z  +              |
|     ------------------------------------------------------------------------|
|                2 4                   4              2 4                5    |
|     5790722400x z  + 12566510100x*y*z  + 5790722400y z  + 1996002000x*z  +  |
|     ------------------------------------------------------------------------|
|                  5             6      6        5          4 2         3 3   |
|     1996002000y*z  + 262440000z , 324x  + 3888x y + 15327x y  + 24426x y  + |
|     ------------------------------------------------------------------------|
|           2 4          5       6        5          4            3 2         |
|     15327x y  + 3888x*y  + 324y  + 3888x z + 34506x y*z + 91134x y z +      |
|     ------------------------------------------------------------------------|
|           2 3            4         5          4 2         3   2             |
|     91134x y z + 34506x*y z + 3888y z + 15327x z  + 91134x y*z  +           |
|     ------------------------------------------------------------------------|
|            2 2 2           3 2         4 2         3 3         2   3        |
|     160138x y z  + 91134x*y z  + 15327y z  + 24426x z  + 91134x y*z  +      |
|     ------------------------------------------------------------------------|
|             2 3         3 3         2 4             4         2 4          5|
|     91134x*y z  + 24426y z  + 15327x z  + 34506x*y*z  + 15327y z  + 3888x*z |
|     ------------------------------------------------------------------------|
|              5       6         6            5             4 2               |
|     + 3888y*z  + 324z , 810000x  + 13824000x y + 69234300x y  +             |
|     ------------------------------------------------------------------------|
|               3 3            2 4              5          6            5     |
|     126729000x y  + 69234300x y  + 13824000x*y  + 810000y  + 13824000x z +  |
|     ------------------------------------------------------------------------|
|               4                3 2              2 3                4        |
|     180417600x y*z + 596611320x y z + 596611320x y z + 180417600x*y z +     |
|     ------------------------------------------------------------------------|
|              5             4 2             3   2              2 2 2         |
|     13824000y z + 69234300x z  + 596611320x y*z  + 1319475529x y z  +       |
|     ------------------------------------------------------------------------|
|                 3 2            4 2             3 3             2   3        |
|     596611320x*y z  + 69234300y z  + 126729000x z  + 596611320x y*z  +      |
|     ------------------------------------------------------------------------|
|                 2 3             3 3            2 4                 4        |
|     596611320x*y z  + 126729000y z  + 69234300x z  + 180417600x*y*z  +      |
|     ------------------------------------------------------------------------|
|              2 4              5              5          6                   |
|     69234300y z  + 13824000x*z  + 13824000y*z  + 810000z }                  |
|                                                                             |
|o4 : List                                                                    |
+-----------------------------------------------------------------------------+

Compare this result to the hsop output when Dade is left to its default value
false (Macaulay2Doc).

+-----------------------------------------------+
|i5 : primaryInvariants(S3)                     |
|                                               |
|                                   3    3    3 |
|o5 = {x + y + z, x*y + x*z + y*z, x  + y  + z }|
|                                               |
|o5 : List                                      |
+-----------------------------------------------+

                                   S3
Below, the invariant ring QQ[x,y,z]   is calculated with K being the field with
101 elements.

+-----------------------------------------------------------------------------+
|i6 : K=GF(101)                                                               |
|                                                                             |
|o6 = K                                                                       |
|                                                                             |
|o6 : GaloisField                                                             |
+-----------------------------------------------------------------------------+
|i7 : S3=finiteAction({A,B},K[x,y,z])                                         |
|                                                                             |
|o7 = K[x..z] <- {| 0 1 0 |, | 0 1 0 |}                                       |
|                 | 0 0 1 |  | 1 0 0 |                                        |
|                 | 1 0 0 |  | 0 0 1 |                                        |
|                                                                             |
|o7 : FiniteGroupAction                                                       |
+-----------------------------------------------------------------------------+
|i8 : primaryInvariants(S3,Dade=>true)                                        |
|                                                                             |
|         6      5       4 2      3 3      2 4        5      6      5         |
|o8 = {22x  - 20x y - 19x y  - 50x y  - 19x y  - 20x*y  + 22y  - 20x z +      |
|     ------------------------------------------------------------------------|
|        4         3 2       2 3         4       5       4 2      3   2       |
|     11x y*z - 29x y z - 29x y z + 11x*y z - 20y z - 19x z  - 29x y*z  +     |
|     ------------------------------------------------------------------------|
|        2 2 2        3 2      4 2      3 3      2   3        2 3      3 3    |
|     12x y z  - 29x*y z  - 19y z  - 50x z  - 29x y*z  - 29x*y z  - 50y z  -  |
|     ------------------------------------------------------------------------|
|        2 4          4      2 4        5        5      6    6      5      4 2|
|     19x z  + 11x*y*z  - 19y z  - 20x*z  - 20y*z  + 22z , 6x  + 37x y + 2x y |
|     ------------------------------------------------------------------------|
|          3 3     2 4        5     6      5       4         3 2       2 3    |
|     + 24x y  + 2x y  + 37x*y  + 6y  + 37x z + 13x y*z + 29x y z + 29x y z + |
|     ------------------------------------------------------------------------|
|          4       5      4 2      3   2      2 2 2        3 2     4 2        |
|     13x*y z + 37y z + 2x z  + 29x y*z  + 15x y z  + 29x*y z  + 2y z  +      |
|     ------------------------------------------------------------------------|
|        3 3      2   3        2 3      3 3     2 4          4     2 4        |
|     24x z  + 29x y*z  + 29x*y z  + 24y z  + 2x z  + 13x*y*z  + 2y z  +      |
|     ------------------------------------------------------------------------|
|          5        5     6     6      5       4 2      3 3      2 4        5 |
|     37x*z  + 37y*z  + 6z , 21x  - 42x y + 43x y  - 44x y  + 43x y  - 42x*y  |
|     ------------------------------------------------------------------------|
|          6      5       4        3 2      2 3         4       5       4 2   |
|     + 21y  - 42x z + 33x y*z + 9x y z + 9x y z + 33x*y z - 42y z + 43x z  + |
|     ------------------------------------------------------------------------|
|       3   2      2 2 2       3 2      4 2      3 3     2   3       2 3      |
|     9x y*z  + 20x y z  + 9x*y z  + 43y z  - 44x z  + 9x y*z  + 9x*y z  -    |
|     ------------------------------------------------------------------------|
|        3 3      2 4          4      2 4        5        5      6            |
|     44y z  + 43x z  + 33x*y*z  + 43y z  - 42x*z  - 42y*z  + 21z }           |
|                                                                             |
|o8 : List                                                                    |
+-----------------------------------------------------------------------------+

For more information about the algorithms used to calculate a hsop in
primaryInvariants, see hsop algorithms.

Caveat
======

Currently users can only use primaryInvariants, to

calculate a hsop for the invariant ring over a finite field by using the Dade

algorithm. Users should enter the finite field as a GaloisField (Macaulay2Doc),
or a quotient field of the form ZZ (Macaulay2Doc),
/p and are advised to ensure that the ground field has
                            n-1
cardinality greater than |G|   , where n is the number of variables in the
polynomial ring R. Using a ground field smaller than this runs the risk of the
algorithm getting stuck in an infinite loop; see primaryInvariants,
displays a warning message asking the user whether they wish
to continue with the computation in this case. See hsop algorithms,
for a discussion on the Dade algorithm.

See also
========

  * hsop algorithms -- an overview of the algorithms
    used in primaryInvariants
  * primaryInvariants -- computes a list of primary
    invariants for the invariant ring of a finite group

Functions with optional argument named Dade:
============================================

  * primaryInvariants(...,Dade=>...)
    -- an optional argument
    for primaryInvariants determining whether to use the Dade algorithm

Further information
===================

  * Default value: false (Macaulay2Doc),
  * Function: primaryInvariants, -- computes a list of
    primary invariants for the invariant ring of a finite group
  * Option key: Dade,
    -- an optional argument for primaryInvariants determining whether to use
    the Dade algorithm
-------------------------------------------------------------------------------

The source of this document is in InvariantRing/HawesDoc.m2:244:0.

primaryInvariants(...,DegreeVector=>...) -- an optional argument for primaryInvariants that finds invariants of certain degrees
*******************************************************************************************************************************

  * Usage:
        primaryInvariants G
  * Inputs:
      * G, an instance of the type FiniteGroupAction,
  * Outputs:
      * a list (Macaulay2Doc),  consisting of a homogeneous system
        of parameters (hsop) for the invariant ring of the group action

Description
===========

By default, see primaryInvariants, uses an optimising

algorithm which tests for the existence of a homogeneous system of parameters

(hsop) (f ,...,f ) with positive degrees corresponding to (d ,...,d ) in *note
         1      n                                           1      n
                     n
ZZ: (Macaulay2Doc)ZZ, . If it is known that a hsop exists for a certain
collection of degrees, this can be assigned, as a List (Macaulay2Doc),
to the optional argument DegreeVector.
See
primaryInvariants, will then output a hsop corresponding to
this list of degrees. If however no such hsop exists, see primaryInvariants,
outputs an error message.

Note that the List (Macaulay2Doc), assigned to DegreeVector,
is ignored if
Dade, is set to true (Macaulay2Doc).

+-----------------------------------------------------------------------------+
|i1 : A=matrix{{0,1,0},{0,0,1},{1,0,0}};                                      |
|                                                                             |
|              3       3                                                      |
|o1 : Matrix ZZ  <-- ZZ                                                       |
+-----------------------------------------------------------------------------+
|i2 : B=matrix{{0,1,0},{1,0,0},{0,0,1}};                                      |
|                                                                             |
|              3       3                                                      |
|o2 : Matrix ZZ  <-- ZZ                                                       |
+-----------------------------------------------------------------------------+
|i3 : S3=finiteAction({A,B},QQ[x,y,z])                                        |
|                                                                             |
|o3 = QQ[x..z] <- {| 0 1 0 |, | 0 1 0 |}                                      |
|                  | 0 0 1 |  | 1 0 0 |                                       |
|                  | 1 0 0 |  | 0 0 1 |                                       |
|                                                                             |
|o3 : FiniteGroupAction                                                       |
+-----------------------------------------------------------------------------+
|i4 : primaryInvariants(S3,DegreeVector=>{3,3,4})                             |
|                                                                             |
|       3    3    3   2       2    2     2       2      2   2 2    2 2    2 2 |
|o4 = {x  + y  + z , x y + x*y  + x z + y z + x*z  + y*z , x y  + x z  + y z }|
|                                                                             |
|o4 : List                                                                    |
+-----------------------------------------------------------------------------+

Caveat
======

Currently users can only use primaryInvariants, to

calculate a hsop for the invariant ring over a finite field by using the Dade

algorithm. Users should enter the finite field as a GaloisField (Macaulay2Doc),
or a quotient field of the form ZZ (Macaulay2Doc),
/p and are advised to ensure that the ground field has
                            n-1
cardinality greater than |G|   , where n is the number of variables in the
polynomial ring R. Using a ground field smaller than this runs the risk of the
algorithm getting stuck in an infinite loop; see primaryInvariants,
displays a warning message asking the user whether they wish
to continue with the computation in this case. See hsop algorithms,
for a discussion on the Dade algorithm.

See also
========

  * primaryInvariants -- computes a list of primary
    invariants for the invariant ring of a finite group

Functions with optional argument named DegreeVector:
====================================================

  * "hironakaDecomposition(...,DegreeVector=>...)"
  * primaryInvariants(...,DegreeVector=>...)
    -- an optional
    argument for primaryInvariants that finds invariants of certain degrees

Further information
===================

  * Default value: 0
  * Function: primaryInvariants, -- computes a list of
    primary invariants for the invariant ring of a finite group
  * Option key: DegreeVector,
    -- an optional
    argument for primaryInvariants that finds invariants of certain degrees
-------------------------------------------------------------------------------

The source of this document is in InvariantRing/HawesDoc.m2:298:0.

rank(DiagonalAction) -- of a diagonal action
********************************************

  * Function: rank (Macaulay2Doc),
  * Usage:
        rank D
  * Inputs:
      * D, an instance of the type DiagonalAction,
  * Outputs:
      * an integer (Macaulay2Doc), the rank of the torus factor of a
        diagonal action

Description
===========

This function is provided by the package InvariantRing.

Use this function to recover the rank of the torus factor of a diagonal action.

The following example defines an action of a two-dimensional torus on a
polynomial ring in four variables.

+---------------------------------------+
|i1 : R = QQ[x_1..x_4]                  |
|                                       |
|o1 = R                                 |
|                                       |
|o1 : PolynomialRing                    |
+---------------------------------------+
|i2 : W = matrix{{0,1,-1,1},{1,0,-1,-1}}|
|                                       |
|o2 = | 0 1 -1 1  |                     |
|     | 1 0 -1 -1 |                     |
|                                       |
|              2       4                |
|o2 : Matrix ZZ  <-- ZZ                 |
+---------------------------------------+
|i3 : T = diagonalAction(W, R)          |
|                                       |
|             * 2                       |
|o3 = R <- (QQ )  via                   |
|                                       |
|     | 0 1 -1 1  |                     |
|     | 1 0 -1 -1 |                     |
|                                       |
|o3 : DiagonalAction                    |
+---------------------------------------+
|i4 : rank T                            |
|                                       |
|o4 = 2                                 |
+---------------------------------------+

See also
========

  * DiagonalAction -- the class of all diagonal actions
  * diagonalAction -- diagonal group action via weights

Ways to use this method:
========================

  * rank(DiagonalAction) -- of a diagonal
    action
-------------------------------------------------------------------------------

The source of this document is in InvariantRing/AbelianGroupsDoc.m2:352:0.

relations(FiniteGroupAction) -- relations of a finite group
***********************************************************

  * Function: relations (Macaulay2Doc),
  * Usage:
        relations G
  * Inputs:
      * G, an instance of the type FiniteGroupAction,
        the action of a finite group
  * Outputs:
      * a list (Macaulay2Doc), a list of relations of the group

Description
===========

This function is provided by the package InvariantRing.

Use this function to get the relations among elements of a group. Each element
is represented by a word of minimal length in the Coxeter generators. And each
relation is represented by a list of two words that equates the group element
represented by those two words.

The following example defines the permutation action of a symmetric group on
three elements using three transpositions.

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x_1..x_3]                                                        |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : L = {matrix {{0,1,0},{1,0,0},{0,0,1}}, matrix {{0,0,1},{0,1,0},{1,0,0}},|
|                                                                             |
|o2 = {| 0 1 0 |, | 0 0 1 |, | 1 0 0 |}                                       |
|      | 1 0 0 |  | 0 1 0 |  | 0 0 1 |                                        |
|      | 0 0 1 |  | 1 0 0 |  | 0 1 0 |                                        |
|                                                                             |
|o2 : List                                                                    |
|-----------------------------------------------------------------------------|
|matrix {{1,0,0},{0,0,1},{0,1,0}} }                                           |
+-----------------------------------------------------------------------------+
|i3 : G = finiteAction(L, R)                                                  |
|                                                                             |
|o3 = R <- {| 0 1 0 |, | 0 0 1 |, | 1 0 0 |}                                  |
|           | 1 0 0 |  | 0 1 0 |  | 0 0 1 |                                   |
|           | 0 0 1 |  | 1 0 0 |  | 0 1 0 |                                   |
|                                                                             |
|o3 : FiniteGroupAction                                                       |
+-----------------------------------------------------------------------------+
|i4 : relations G                                                             |
|                                                                             |
|o4 = {{{}, {1, 1}}, {{}, {2, 2}}, {{1}, {0, 1, 2}}, {{1}, {0, 2, 0}}, {{},   |
|     ------------------------------------------------------------------------|
|     {0, 0}}, {{0, 2}, {1, 0}}, {{0, 2}, {2, 1}}, {{0, 1}, {1, 2}}, {{0, 1}, |
|     ------------------------------------------------------------------------|
|     {2, 0}}, {{2}, {0, 1, 0}}, {{2}, {0, 2, 1}}}                            |
|                                                                             |
|o4 : List                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * group -- list all elements of the group of a finite group
    action
  * schreierGraph -- Schreier graph of a finite group
  * words -- associate a word in the generators of a group to
    each element

Ways to use this method:
========================

  * relations(FiniteGroupAction), --
    relations of a finite group
-------------------------------------------------------------------------------

The source of this document is in InvariantRing/FiniteGroupsDoc.m2:377:0.

reynoldsOperator -- the image of a polynomial under the Reynolds operator
*************************************************************************

  * Usage:
        reynoldsOperator(f, G), reynoldsOperator(f, D)
  * Inputs:
      * f, a ring element (Macaulay2Doc), a polynomial in
        the polynomial ring of the given group action
      * G, an instance of the type FiniteGroupAction,
      * D, an instance of the type DiagonalAction,
  * Outputs:
      * a ring element (Macaulay2Doc), the invariant
        polynomial which is the image of the given polynomial under the
        Reynolds operator of the given finite group action or the given torus
        action

Description
===========

This function is provided by the package InvariantRing.

The following example computes the image of a polynomial under the Reynolds
operator for a cyclic permutation of the variables.

+-----------------------------------------------------------------+
|i1 : R = ZZ/3[x_0..x_6]                                          |
|                                                                 |
|o1 = R                                                           |
|                                                                 |
|o1 : PolynomialRing                                              |
+-----------------------------------------------------------------+
|i2 : P = permutationMatrix toString 2345671                      |
|                                                                 |
|o2 = | 0 0 0 0 0 0 1 |                                           |
|     | 1 0 0 0 0 0 0 |                                           |
|     | 0 1 0 0 0 0 0 |                                           |
|     | 0 0 1 0 0 0 0 |                                           |
|     | 0 0 0 1 0 0 0 |                                           |
|     | 0 0 0 0 1 0 0 |                                           |
|     | 0 0 0 0 0 1 0 |                                           |
|                                                                 |
|              7       7                                          |
|o2 : Matrix ZZ  <-- ZZ                                           |
+-----------------------------------------------------------------+
|i3 : C7 = finiteAction(P, R)                                     |
|                                                                 |
|o3 = R <- {| 0 0 0 0 0 0 1 |}                                    |
|           | 1 0 0 0 0 0 0 |                                     |
|           | 0 1 0 0 0 0 0 |                                     |
|           | 0 0 1 0 0 0 0 |                                     |
|           | 0 0 0 1 0 0 0 |                                     |
|           | 0 0 0 0 1 0 0 |                                     |
|           | 0 0 0 0 0 1 0 |                                     |
|                                                                 |
|o3 : FiniteGroupAction                                           |
+-----------------------------------------------------------------+
|i4 : reynoldsOperator(x_0*x_1*x_2^2, C7)                         |
|                                                                 |
|          2        2        2        2      2      2            2|
|o4 = x x x  + x x x  + x x x  + x x x  + x x x  + x x x  + x x x |
|      0 1 2    1 2 3    2 3 4    3 4 5    0 1 6    0 5 6    4 5 6|
|                                                                 |
|o4 : R                                                           |
+-----------------------------------------------------------------+

Here is an example computing the image of a polynomial under the Reynolds
operator for a two-dimensional torus acting on polynomial ring in four
variables:

+---------------------------------------------------+
|i5 : R = QQ[x_1..x_4]                              |
|                                                   |
|o5 = R                                             |
|                                                   |
|o5 : PolynomialRing                                |
+---------------------------------------------------+
|i6 : W = matrix{{0,1,-1,1}, {1,0,-1,-1}}           |
|                                                   |
|o6 = | 0 1 -1 1  |                                 |
|     | 1 0 -1 -1 |                                 |
|                                                   |
|              2       4                            |
|o6 : Matrix ZZ  <-- ZZ                             |
+---------------------------------------------------+
|i7 : T = diagonalAction(W, R)                      |
|                                                   |
|             * 2                                   |
|o7 = R <- (QQ )  via                               |
|                                                   |
|     | 0 1 -1 1  |                                 |
|     | 1 0 -1 -1 |                                 |
|                                                   |
|o7 : DiagonalAction                                |
+---------------------------------------------------+
|i8 : reynoldsOperator(x_1*x_2*x_3 + x_1*x_2*x_4, T)|
|                                                   |
|o8 = x x x                                         |
|      1 2 3                                        |
|                                                   |
|o8 : R                                             |
+---------------------------------------------------+

Ways to use reynoldsOperator:
=============================

  * "reynoldsOperator(RingElement,DiagonalAction)"
  * "reynoldsOperator(RingElement,FiniteGroupAction)"

For the programmer
==================

The object reynoldsOperator, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in InvariantRing/InvariantsDoc.m2:863:0.

ring(GroupAction) -- the polynomial ring being acted upon
*********************************************************

  * Function: ring (Macaulay2Doc),
  * Usage:
        ring G
  * Inputs:
      * G, an instance of the type GroupAction, a group
        action on a polynomial ring
  * Outputs:
      * a ring (Macaulay2Doc), the polynomial ring being acted upon

Description
===========

This function is provided by the package InvariantRing.

+-----------------------------------------------------------+
|i1 : R = QQ[x_1..x_4]                                      |
|                                                           |
|o1 = R                                                     |
|                                                           |
|o1 : PolynomialRing                                        |
+-----------------------------------------------------------+
|i2 : T = diagonalAction(matrix {{0,1,-1,1},{1,0,-1,-1}}, R)|
|                                                           |
|             * 2                                           |
|o2 = R <- (QQ )  via                                       |
|                                                           |
|     | 0 1 -1 1  |                                         |
|     | 1 0 -1 -1 |                                         |
|                                                           |
|o2 : DiagonalAction                                        |
+-----------------------------------------------------------+
|i3 : ring T === R                                          |
|                                                           |
|o3 = true                                                  |
+-----------------------------------------------------------+

Ways to use this method:
========================

  * ring(GroupAction) -- the polynomial ring
    being acted upon
-------------------------------------------------------------------------------

The source of this document is in InvariantRing/InvariantRingDoc.m2:169:0.

RingOfInvariants -- the class of the rings of invariants under the action of a finite group, an Abelian group or a linearly reductive group
*******************************************************************************************************************************************

Description
===========

This class is provided by the package InvariantRing.

RingOfInvariants is the class of rings of invariants when a finite group, an
Abelian group or a linearly reductive group acts on a polynomial ring.

Functions and methods returning an object of class RingOfInvariants:
====================================================================

  * "invariantRing(GroupAction)" -- see invariantRing, --
    the ring of invariants of a group action
  * "PolynomialRing ^ GroupAction" -- see invariantRing,
    -- the ring of invariants of a group action
  * "QuotientRing ^ LinearlyReductiveAction" -- see invariantRing,
    -- the ring of invariants of a group action

Methods that use an object of class RingOfInvariants:
=====================================================

  * "action(RingOfInvariants)" -- see action, -- the group action
    that produced a ring of invariants
  * ambient(RingOfInvariants) -- the
    ambient polynomial ring where the group acted upon
  * "definingIdeal(RingOfInvariants)" -- see definingIdeal,
    -- presentation of a ring of invariants as polynomial ring
    modulo the defining ideal
  * generators(RingOfInvariants), --
    the generators for a ring of invariants
  * hilbertSeries(RingOfInvariants),
    -- Hilbert series of the invariant ring
  * net(RingOfInvariants) -- format for
    printing, as a net

For the programmer
==================

The object RingOfInvariants, is a type (Macaulay2Doc),
with ancestor classes HashTable (Macaulay2Doc),
< Thing (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in InvariantRing/InvariantsDoc.m2:908:0.

schreierGraph -- Schreier graph of a finite group
*************************************************

  * Usage:
        schreierGraph G
  * Inputs:
      * G, an instance of the type FiniteGroupAction,
        a finite group action
  * Outputs:
      * a hash table (Macaulay2Doc), representing the Schreier
        graph of the group

Description
===========

This function is provided by the package InvariantRing.

For a finite group action, we form a HashTable (Macaulay2Doc),
whose keys are the generators provided by the user. The value corresponding to
a generator g is a HashTable (Macaulay2Doc), containing all
pairs a => b such that a*g == b. This represents the Schreier graph of the
group relative to the generating set provided by the user.

The following example defines the permutation action of a symmetric group on
three elements using only two generators, a transposition and a 3-cycle.

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x_1..x_3]                                                        |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : L = {matrix {{0,1,0},{1,0,0},{0,0,1}}, matrix {{0,0,1},{0,1,0},{1,0,0}} |
|                                                                             |
|o2 = {| 0 1 0 |, | 0 0 1 |}                                                  |
|      | 1 0 0 |  | 0 1 0 |                                                   |
|      | 0 0 1 |  | 1 0 0 |                                                   |
|                                                                             |
|o2 : List                                                                    |
|-----------------------------------------------------------------------------|
|}                                                                            |
+-----------------------------------------------------------------------------+
|i3 : G = finiteAction(L, R)                                                  |
|                                                                             |
|o3 = R <- {| 0 1 0 |, | 0 0 1 |}                                             |
|           | 1 0 0 |  | 0 1 0 |                                              |
|           | 0 0 1 |  | 1 0 0 |                                              |
|                                                                             |
|o3 : FiniteGroupAction                                                       |
+-----------------------------------------------------------------------------+
|i4 : schreierGraph G                                                         |
|                                                                             |
|o4 = HashTable{0 => HashTable{| 0 0 1 | => | 0 0 1 |}}                       |
|                              | 0 1 0 |    | 1 0 0 |                         |
|                              | 1 0 0 |    | 0 1 0 |                         |
|                              | 0 0 1 | => | 0 0 1 |                         |
|                              | 1 0 0 |    | 0 1 0 |                         |
|                              | 0 1 0 |    | 1 0 0 |                         |
|                              | 0 1 0 | => | 1 0 0 |                         |
|                              | 0 0 1 |    | 0 0 1 |                         |
|                              | 1 0 0 |    | 0 1 0 |                         |
|                              | 0 1 0 | => | 1 0 0 |                         |
|                              | 1 0 0 |    | 0 1 0 |                         |
|                              | 0 0 1 |    | 0 0 1 |                         |
|                              | 1 0 0 | => | 0 1 0 |                         |
|                              | 0 0 1 |    | 0 0 1 |                         |
|                              | 0 1 0 |    | 1 0 0 |                         |
|                              | 1 0 0 | => | 0 1 0 |                         |
|                              | 0 1 0 |    | 1 0 0 |                         |
|                              | 0 0 1 |    | 0 0 1 |                         |
|               1 => HashTable{| 0 0 1 | => | 1 0 0 |}                        |
|                              | 0 1 0 |    | 0 1 0 |                         |
|                              | 1 0 0 |    | 0 0 1 |                         |
|                              | 0 0 1 | => | 1 0 0 |                         |
|                              | 1 0 0 |    | 0 0 1 |                         |
|                              | 0 1 0 |    | 0 1 0 |                         |
|                              | 0 1 0 | => | 0 1 0 |                         |
|                              | 0 0 1 |    | 1 0 0 |                         |
|                              | 1 0 0 |    | 0 0 1 |                         |
|                              | 0 1 0 | => | 0 1 0 |                         |
|                              | 1 0 0 |    | 0 0 1 |                         |
|                              | 0 0 1 |    | 1 0 0 |                         |
|                              | 1 0 0 | => | 0 0 1 |                         |
|                              | 0 0 1 |    | 1 0 0 |                         |
|                              | 0 1 0 |    | 0 1 0 |                         |
|                              | 1 0 0 | => | 0 0 1 |                         |
|                              | 0 1 0 |    | 0 1 0 |                         |
|                              | 0 0 1 |    | 1 0 0 |                         |
|                                                                             |
|o4 : HashTable                                                               |
+-----------------------------------------------------------------------------+

Ways to use schreierGraph:
==========================

  * "schreierGraph(FiniteGroupAction)"

For the programmer
==================

The object schreierGraph, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in InvariantRing/FiniteGroupsDoc.m2:261:0.

secondaryInvariants -- computes secondary invariants for the invariant ring of a finite group
*********************************************************************************************

  * Usage:
        secondaryInvariants(P,G)
  * Inputs:
      * P, a list (Macaulay2Doc), a list of primary invariants in n

        variables f ,...,f  for the invariant ring of G defined over a field K
                   1      n
        of characteristic zero
      * G, an instance of the type FiniteGroupAction,
  * Optional inputs (Macaulay2Doc),:
      * PrintDegreePolynomial,
        => ..., default value false, an optional argument for
        secondaryInvariants that determines the printing of an informative
        polynomial
  * Outputs:

      * a list (Macaulay2Doc), a list S of secondary invariants for

                                         G
        the invariant ring R=K[x ,...,x ]  of G that makes R into a free
                                1      n
        K[f ,...,f ]-module with basis S
           1      n

Description
===========

The example below computes the secondary invariants for the dihedral group with
6 elements, given a set of primary invariantsP.

+----------------------------------+
|i1 : K=toField(QQ[a]/(a^2+a+1));  |
+----------------------------------+
|i2 : R=K[x,y];                    |
+----------------------------------+
|i3 : A=matrix{{a,0},{0,a^2}};     |
|                                  |
|             2      2             |
|o3 : Matrix K  <-- K              |
+----------------------------------+
|i4 : B=sub(matrix{{0,1},{1,0}},K);|
|                                  |
|             2      2             |
|o4 : Matrix K  <-- K              |
+----------------------------------+
|i5 : D6=finiteAction({A,B},R)     |
|                                  |
|o5 = R <- {| a 0    |, | 0 1 |}   |
|           | 0 -a-1 |  | 1 0 |    |
|                                  |
|o5 : FiniteGroupAction            |
+----------------------------------+
|i6 : P={x^3+y^3,-(x^3-y^3)^2};    |
+----------------------------------+
|i7 : secondaryInvariants(P,D6)    |
|                                  |
|               2 2                |
|o7 = {1, x*y, x y }               |
|                                  |
|o7 : List                         |
+----------------------------------+

This function is provided by the package InvariantRing.

Caveat
======

Currently, a user needs to ensure that the all primary invariants are defined
with coefficients in a ring that Macaulay2 recognises as a characteristic zero
field (see toField (Macaulay2Doc), for a way to do
this).

Note also that the function secondaryInvariants,
only works when R is defined over a field of characteristic zero.

Ways to use secondaryInvariants:
================================

  * "secondaryInvariants(List,FiniteGroupAction)"

For the programmer
==================

The object secondaryInvariants, is a method function with options (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in InvariantRing/HawesDoc.m2:487:0.

secondaryInvariants(...,PrintDegreePolynomial=>...) -- an optional argument for secondaryInvariants that determines the printing of an informative polynomial
*************************************************************************************************************************************************************

  * Usage:
        secondaryInvariants(P,G)
  * Inputs:
      * P, a list (Macaulay2Doc), a list of primary invariants in n

        variables f ,...,f  for the invariant ring of G defined over a field K
                   1      n
        of characteristic zero
      * G, an instance of the type FiniteGroupAction,
  * Outputs:

      * a list (Macaulay2Doc), a list S of secondary invariants for

                                         G
        the invariant ring R=K[x ,...,x ]  of G that makes R into a free
                                1      n
        K[f ,...,f ]-module with basis S
           1      n

Description
===========

See PrintDegreePolynomial,
takes a

See Boolean (Macaulay2Doc), value and is set to false (Macaulay2Doc),
by default. If it is set to true (Macaulay2Doc),
then secondaryInvariants, will

print a polynomial in the variable T. This polynomial encodes the degrees of

the secondary invariants (given by the exponents of T appearing in it) and the

number of secondary invariants of a given degree (the coefficient of the

corresponding term in the polynomial). Specifically, if
secondaryInvariants, takes as input a set of primary

                                                       G
invariants of degrees d ,...,d  for an invariant ring S  of a finite group G,
                       1      n
       G                                           G
and H(S ,T)denotes the Molien (Hilbert) series of S , then
secondaryInvariants, will compute the polynomial
   G        d           d
H(S ,T)*(1-T 1)*...*(1-T n).

The example below computes the secondary invariants for the dihedral group with
6 elements, given a set of primary invariants P. The optional argument
PrintDegreePolynomial,
is set to true (Macaulay2Doc), in order to see which
degrees the secondary invariants should have.

+----------------------------------------------------------+
|i1 : K=toField(QQ[a]/(a^2+a+1));                          |
+----------------------------------------------------------+
|i2 : R=K[x,y];                                            |
+----------------------------------------------------------+
|i3 : A=matrix{{a,0},{0,a^2}};                             |
|                                                          |
|             2      2                                     |
|o3 : Matrix K  <-- K                                      |
+----------------------------------------------------------+
|i4 : B=sub(matrix{{0,1},{1,0}},K);                        |
|                                                          |
|             2      2                                     |
|o4 : Matrix K  <-- K                                      |
+----------------------------------------------------------+
|i5 : D6=finiteAction({A,B},R)                             |
|                                                          |
|o5 = R <- {| a 0    |, | 0 1 |}                           |
|           | 0 -a-1 |  | 1 0 |                            |
|                                                          |
|o5 : FiniteGroupAction                                    |
+----------------------------------------------------------+
|i6 : P={x^3+y^3,-(x^3-y^3)^2};                            |
+----------------------------------------------------------+
|i7 : secondaryInvariants(P,D6,PrintDegreePolynomial=>true)|
| 4    2                                                   |
|t  + t  + 1                                               |
|                                                          |
|               2 2                                        |
|o7 = {1, x*y, x y }                                       |
|                                                          |
|o7 : List                                                 |
+----------------------------------------------------------+

Caveat
======

Currently, a user needs to ensure that the all primary invariants are defined
with coefficients in a ring that Macaulay2 recognises as a characteristic zero
field (see toField (Macaulay2Doc), for a way to do
this).

Functions with optional argument named PrintDegreePolynomial:
=============================================================

  * "hironakaDecomposition(...,PrintDegreePolynomial=>...)"
  * secondaryInvariants(...,PrintDegreePolynomial=>...),
    --
    an optional argument for secondaryInvariants that determines the printing
    of an informative polynomial

Further information
===================

  * Default value: false (Macaulay2Doc),
  * Function: secondaryInvariants, -- computes
    secondary invariants for the invariant ring of a finite group
  * Option key: PrintDegreePolynomial,
    --
    an optional argument for secondaryInvariants that determines the printing
    of an informative polynomial
-------------------------------------------------------------------------------

The source of this document is in InvariantRing/HawesDoc.m2:555:0.

UseNormaliz -- option for diagonal invariants
*********************************************

Description
===========

This option is provided by the package InvariantRing.

The computation of diagonal invariants relies on finding integral points in a
convex hull constructed from a weight matrix. This option selects the package
used for finding integral points. See invariants(DiagonalAction),
for usage.

For the programmer
==================

The object UseNormaliz, is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in InvariantRing/InvariantsDoc.m2:981:0.

weights -- of a diagonal action
*******************************

  * Usage:
        weights D
  * Inputs:
      * D, an instance of the type DiagonalAction,
  * Outputs:
      * a matrix (Macaulay2Doc), the weight matrix of the group
        action

Description
===========

This function is provided by the package InvariantRing.

Use this function to recover the weight matrix of a diagonal action on a
polynomial ring. For a diagonal action on a polynomial ring  $k[x_1, \dots,
x_n]$ , the  $j$ -th column of the weight matrix is the weight of the variable
$x_j$ .

The following example defines an action of a two-dimensional torus on a
polynomial ring in four variables.

+---------------------------------------+
|i1 : R = QQ[x_1..x_4]                  |
|                                       |
|o1 = R                                 |
|                                       |
|o1 : PolynomialRing                    |
+---------------------------------------+
|i2 : W = matrix{{0,1,-1,1},{1,0,-1,-1}}|
|                                       |
|o2 = | 0 1 -1 1  |                     |
|     | 1 0 -1 -1 |                     |
|                                       |
|              2       4                |
|o2 : Matrix ZZ  <-- ZZ                 |
+---------------------------------------+
|i3 : T = diagonalAction(W, R)          |
|                                       |
|             * 2                       |
|o3 = R <- (QQ )  via                   |
|                                       |
|     | 0 1 -1 1  |                     |
|     | 1 0 -1 -1 |                     |
|                                       |
|o3 : DiagonalAction                    |
+---------------------------------------+
|i4 : weights T                         |
|                                       |
|o4 = (| 0 1 -1 1  |, 0)                |
|      | 1 0 -1 -1 |                    |
|                                       |
|o4 : Sequence                          |
+---------------------------------------+

Here is an example of a product of two cyclic groups of order 3 acting on a
polynomial ring in 3 variables.

+--------------------------------+
|i5 : R = QQ[x_1..x_3]           |
|                                |
|o5 = R                          |
|                                |
|o5 : PolynomialRing             |
+--------------------------------+
|i6 : d = {3,3}                  |
|                                |
|o6 = {3, 3}                     |
|                                |
|o6 : List                       |
+--------------------------------+
|i7 : W = matrix{{1,0,1},{0,1,1}}|
|                                |
|o7 = | 1 0 1 |                  |
|     | 0 1 1 |                  |
|                                |
|              2       3         |
|o7 : Matrix ZZ  <-- ZZ          |
+--------------------------------+
|i8 : A = diagonalAction(W, d, R)|
|                                |
|o8 = R <- ZZ/3 x ZZ/3 via       |
|                                |
|     | 1 0 1 |                  |
|     | 0 1 1 |                  |
|                                |
|o8 : DiagonalAction             |
+--------------------------------+
|i9 : weights A                  |
|                                |
|o9 = (0, | 1 0 1 |)             |
|         | 0 1 1 |              |
|                                |
|o9 : Sequence                   |
+--------------------------------+

See also
========

  * DiagonalAction -- the class of all diagonal actions
  * diagonalAction -- diagonal group action via weights

Ways to use weights:
====================

  * "weights(DiagonalAction)"

For the programmer
==================

The object weights, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in InvariantRing/AbelianGroupsDoc.m2:278:0.

words -- associate a word in the generators of a group to each element
**********************************************************************

  * Usage:
        words G
  * Inputs:
      * G, an instance of the type FiniteGroupAction,
  * Outputs:
      * a hash table (Macaulay2Doc), associating to each
        element in the group of the action a word of minimal length in (the
        indices of) the generators of the group

Description
===========

This function is provided by the package InvariantRing.

The following example computes, for each permutation in the symmetric group on
three elements, a word of minimal length in the Coxeter generators.

+--------------------------------------------------------------+
|i1 : R = QQ[x_1..x_3]                                         |
|                                                              |
|o1 = R                                                        |
|                                                              |
|o1 : PolynomialRing                                           |
+--------------------------------------------------------------+
|i2 : L = apply(2, i -> permutationMatrix(3, [i + 1, i + 2] ) )|
|                                                              |
|o2 = {| 0 1 0 |, | 1 0 0 |}                                   |
|      | 1 0 0 |  | 0 0 1 |                                    |
|      | 0 0 1 |  | 0 1 0 |                                    |
|                                                              |
|o2 : List                                                     |
+--------------------------------------------------------------+
|i3 : S3 = finiteAction(L, R)                                  |
|                                                              |
|o3 = R <- {| 0 1 0 |, | 1 0 0 |}                              |
|           | 1 0 0 |  | 0 0 1 |                               |
|           | 0 0 1 |  | 0 1 0 |                               |
|                                                              |
|o3 : FiniteGroupAction                                        |
+--------------------------------------------------------------+
|i4 : words S3                                                 |
|                                                              |
|o4 = HashTable{| 0 0 1 | => {0, 1, 0}}                        |
|               | 0 1 0 |                                      |
|               | 1 0 0 |                                      |
|               | 0 0 1 | => {0, 1}                            |
|               | 1 0 0 |                                      |
|               | 0 1 0 |                                      |
|               | 0 1 0 | => {1, 0}                            |
|               | 0 0 1 |                                      |
|               | 1 0 0 |                                      |
|               | 0 1 0 | => {0}                               |
|               | 1 0 0 |                                      |
|               | 0 0 1 |                                      |
|               | 1 0 0 | => {1}                               |
|               | 0 0 1 |                                      |
|               | 0 1 0 |                                      |
|               | 1 0 0 | => {}                                |
|               | 0 1 0 |                                      |
|               | 0 0 1 |                                      |
|                                                              |
|o4 : HashTable                                                |
+--------------------------------------------------------------+

The computation of the words addressing each element in the group is actually
performed by the method schreierGraph, since the process
of computing the Schreier graph of the group yields other useful information
about the group.

See also
========

  * group -- list all elements of the group of a finite group
    action
  * schreierGraph -- Schreier graph of a finite group

Ways to use words:
==================

  * "words(FiniteGroupAction)"

For the programmer
==================

The object words, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in InvariantRing/FiniteGroupsDoc.m2:297:0.