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

EquivariantGB -- a package for computing equivariant Gröbner bases
******************************************************************

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

EquivariantGB is a package for computing in polynomial rings with an infinite
number of variables, but with an action of the infinite symmetric group.
Alternatively such a ring can be considered as the limit of a family of rings
with symmetric action.  A representation of such a ring can be created using
the method buildERing.

For example consider the ring R = $\mathbb{Q}[x_i,y_i \mid i,j\in
\mathbb{Z}_{\geq 0}]$, the coordinate ring of 2 by infinite matrices.  The
infinite symmetric group acts by permuting columns.

+---------------------------------------------------+
|i1 : R = buildERing({symbol x,symbol y},{1,1},QQ,4)|
|                                                   |
|o1 = R                                             |
|                                                   |
|o1 : PolynomialRing                                |
+---------------------------------------------------+
|i2 : vars R                                        |
|                                                   |
|o2 = | x_3 x_2 x_1 x_0 y_3 y_2 y_1 y_0 |           |
|                                                   |
|             1      8                              |
|o2 : Matrix R  <-- R                               |
+---------------------------------------------------+

Here the output ring stores only a truncation of the set of variables, with
indices from 0 to 3, but this bound will be adjusted as necessary in the
computations.

We now consider ideals of R that are closed under the symmetric group action.
For example, let I be the set of vanishing equations of the rank 1 matrices. I
is generated by all 2 by 2 minors $x_iy_j - x_jy_i$.

Authors
=======

  * Chris Hillar <chillar@msri.org>
  * Robert Krone <krone@math.gatech.edu>
  * Anton Leykin <leykin@math.gatech.edu>

Version
=======

This documentation describes version 0.2 of EquivariantGB, released 2014.

Citation
========

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

+-----------------------------------------------------------------------------+
|@misc{EquivariantGBSource,                                                   |
|  title = {{EquivariantGB: Equivariant Groebner bases and related algorithms.|
|  author = {Chris Hillar and Robert Krone and Anton Leykin},                 |
|  howpublished = {A \emph{Macaulay2} package available at                    |
|    ""}                                                                      |
|}                                                                            |
|-----------------------------------------------------------------------------|
|Version~0.2}},                                                               |
+-----------------------------------------------------------------------------+

Exports
=======

  * Types
      * PriorityQueue -- an efficient mutable priority
        queue implementation
      * Shift (missing documentation)
  * Functions and commands
      * buildEMonomialMap -- builds an equivariant
        ring map
      * buildERing -- creates a ring to be used with other
        functions in the EquivariantGB package
      * deleteMin -- deletes the minimum element of the queue
      * egb -- computes equivariant Gröbner bases
      * egbToric -- computes the kernel of an equivariant
        monomial map
      * exponentMatrix -- puts the exponent of a
        monomial into matrix form
      * incOrbit -- the increasing map orbit of an element
      * mergePQ -- merges two queues
      * pop -- returns the minimum element of the queue and deletes
        it
      * priorityQueue -- create a new PriorityQueue
      * reduce -- computes an equivariant normal form
      * shift (missing documentation)
  * Methods
      * "buildEMonomialMap(Ring,Ring,List)" -- see buildEMonomialMap,
        -- builds an equivariant ring map
      * "buildERing(List,List,Ring,ZZ)" -- see buildERing, --
        creates a ring to be used with other functions in the EquivariantGB
        package
      * buildERing(Ring,ZZ) -- creates a
        ERing from existing ERing
      * degree(Shift) (missing documentation)
      * "deleteMin(PriorityQueue)" -- see deleteMin, --
        deletes the minimum element of the queue
      * "egb(List)" -- see egb, -- computes equivariant Gröbner
        bases
      * "egbToric(RingMap)" -- see egbToric, -- computes the
        kernel of an equivariant monomial map
      * "exponentMatrix(RingElement)" -- see exponentMatrix,
        -- puts the exponent of a monomial into matrix form
      * "incOrbit(List,ZZ)" -- see incOrbit, -- the increasing
        map orbit of an element
      * "incOrbit(RingElement,ZZ)" -- see incOrbit, -- the
        increasing map orbit of an element
      * insert(PriorityQueue,Thing),
        -- insert a new element into the queue
      * length(PriorityQueue) -- returns the
        number of elements in the queue
      * max(Shift) (missing documentation)
      * "mergePQ(PriorityQueue,PriorityQueue)" -- see mergePQ,
        -- merges two queues
      * min(PriorityQueue) -- return the minimum
        element of the queue
      * net(Shift) (missing documentation)
      * "pop(PriorityQueue)" -- see pop, -- returns the minimum
        element of the queue and deletes it
      * "priorityQueue(List)" -- see priorityQueue, --
        create a new PriorityQueue
      * "reduce(RingElement,List)" -- see reduce, -- computes an
        equivariant normal form
      * Shift * Number (missing documentation)
      * Shift * RingElement (missing documentation)
      * Shift * Shift (missing documentation)
      * Shift == Shift (missing documentation)
      * Shift ? Shift (missing documentation)
      * shift(List) (missing documentation)
      * shift(MutableList) (missing documentation)
      * shift(Shift) (missing documentation)
      * width(Shift) (missing documentation)
  * Symbols
      * Completely (missing documentation)
      * "Buchberger" -- see egb(...,Algorithm=>...),
        -- algorithm choice for egb
      * "Incremental" -- see egb(...,Algorithm=>...),
        -- algorithm choice for egb
      * "Signature" -- see egb(...,Algorithm=>...),
        -- algorithm choice for egb
      * OutFile -- where to send messages
      * PrincipalSyzygies (missing documentation)
      * Symmetrize (missing documentation)

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

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

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

The source of this document is in EquivariantGB.m2:1048:0.

egb -- computes equivariant Gröbner bases
*****************************************

  * Usage:
        G = egb F
  * Inputs:
      * F, a list (Macaulay2Doc), a list of polynomials in a ring
        created by buildERing.
  * Optional inputs (Macaulay2Doc),:
      * Algorithm, => ...,
        default value Buchberger, algorithm choice for egb
      * OutFile, => ..., default value null, where to send
        messages
      * PrincipalSyzygies (missing documentation) => ..., default value false,
      * Symmetrize (missing documentation) => ..., default value false,
  * Outputs:
      * G, a list (Macaulay2Doc), an equivariant Gröbner basis for
        the equivariant ideal generated by F.

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

egb uses a variant of Buchberger's algorithm.

+--------------------------------------------+
|i1 : R = buildERing({symbol x}, {1}, QQ, 2);|
+--------------------------------------------+
|i2 : egb {x_0 + x_1}                        |
|                                            |
|o2 = {x }                                   |
|       0                                    |
|                                            |
|o2 : List                                   |
+--------------------------------------------+

Caveat
======

The output does not necessarily belong to the same ring as the input.

Ways to use egb:
================

  * "egb(List)"

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

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

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

The source of this document is in EquivariantGB.m2:1153:0.

buildERing -- creates a ring to be used with other functions in the EquivariantGB package
*****************************************************************************************

  * Usage:
        R = buildERing(X,I,F,n)
  * Inputs:
      * X, a list (Macaulay2Doc), a list of symbols, one for each
        block of variables
      * I, a list (Macaulay2Doc), a list of integers, the number of
        indices for each variable block
      * F, a ring (Macaulay2Doc), the coefficient ring
      * n, an integer (Macaulay2Doc), the width bound
  * Optional inputs (Macaulay2Doc),:
      * Degrees => ..., default value {}
      * MonomialOrder => ..., default value Lex
  * Outputs:
      * R, a ring (Macaulay2Doc), a polynomial ring with
        coefficient field F, and a block of variables for each entry of X. The
        corresponding integers in I determine how many indices each block of
        variables has. Variables with all index values from 0 to n-1 are
        included.

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

The object produced by buildERing is a Ring (Macaulay2Doc), with
additional stored information. It is used to represent a polynomial ring F[Y]
with an infinite set of variables Y, and an action of the infinite symmetric
group on Y such that it is composed of a finite number of orbits.  Macaulay2
cannot store a ring with an infinite number of variables, so the ring produced
contains only some of the variables.

We assume Y decomposes into a finite number of "blocks",  each block consisting
of variables of the form x_{(i_1,...,i_k)} for some k and each index i_j
ranging over all non-negative integers.  The symbol x to be used for each block
is listed in X.  The value of k for each block is listed in I.  The variables
in the ring output by buildERing are those with index values ranging from 0 to
n-1.  The same ring with a different index bound n can be produced by
buildERing(Ring,ZZ).

+-------------------------------------------+
|i1 : S = buildERing({symbol z}, {1}, QQ, 4)|
|                                           |
|o1 = S                                     |
|                                           |
|o1 : PolynomialRing                        |
+-------------------------------------------+
|i2 : vars S                                |
|                                           |
|o2 = | z_3 z_2 z_1 z_0 |                   |
|                                           |
|             1      4                      |
|o2 : Matrix S  <-- S                       |
+-------------------------------------------+
|i3 : coefficientRing S                     |
|                                           |
|o3 = QQ                                    |
|                                           |
|o3 : Ring                                  |
+-------------------------------------------+
+-----------------------------------------------------------------------------+
|i4 : R = buildERing({symbol y, symbol x}, {2,1}, QQ, 3)                      |
|                                                                             |
|o4 = R                                                                       |
|                                                                             |
|o4 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i5 : vars R                                                                  |
|                                                                             |
|o5 = | y_(2,2) y_(2,1) y_(2,0) y_(1,2) y_(1,1) y_(1,0) y_(0,2) y_(0,1)       |
|     ------------------------------------------------------------------------|
|     y_(0,0) x_2 x_1 x_0 |                                                   |
|                                                                             |
|             1      12                                                       |
|o5 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+

The monomial order can be chosen with optional argument MonomialOrder (Macaulay2Doc).
Currently valid choices are Lex (Macaulay2Doc),
see GLex (Macaulay2Doc), or GRevLex (Macaulay2Doc).
The variables are always ordered from the last block to
the first, with larger indices before smaller indices.  For blocks with
multiple indices the order of the variables is also lexicographic with first
index most significant, followed by the second, etc.

The grading of the ring can be chosen with optional argument Degrees (Macaulay2Doc).
The grading is specified by listing the degree of each
variable block. Because the degree function must be invariant under the
symmetric action, every variable in the same block must have the same degree.

Ways to use buildERing:
=======================

  * "buildERing(List,List,Ring,ZZ)"
  * buildERing(Ring,ZZ) -- creates a ERing
    from existing ERing

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

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

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

The source of this document is in EquivariantGB.m2:1107:0.

buildEMonomialMap -- builds an equivariant ring map
***************************************************

  * Usage:
        m = buildEMonomialMap
  * Inputs:
      * R, a ring (Macaulay2Doc), the target ring with symmetric
        action, produced by buildERing,
      * S, a ring (Macaulay2Doc), the source ring with symmetric
        action, produced by buildERing,
      * L, a list (Macaulay2Doc), a list of monomials in R, the
        images of each of the variable orbit generators of S
  * Outputs:
      * m, a ring map (Macaulay2Doc), an equivariant monomial
        map to R from S

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

R and S must be rings created by buildERing. Each orbit of
variables in S consists of variables of the form x_{(i_1,...,i_k)} for some
width k.  L is a list that for each such orbit gives the desired image of
x_{(0,...,k-1)}.  The rest of the map is extrapolated from these value.

+--------------------------------------------------------+
|i1 : R = buildERing({symbol x, symbol y}, {1,1}, QQ, 3);|
+--------------------------------------------------------+
|i2 : vars R                                             |
|                                                        |
|o2 = | x_2 x_1 x_0 y_2 y_1 y_0 |                        |
|                                                        |
|             1      6                                   |
|o2 : Matrix R  <-- R                                    |
+--------------------------------------------------------+
|i3 : n = buildEMonomialMap(R,R,{x_0,x_0^3})             |
|                                                        |
|                              3   3   3                 |
|o3 = map (R, R, {x , x , x , x , x , x })               |
|                  2   1   0   2   1   0                 |
|                                                        |
|o3 : RingMap R <-- R                                    |
+--------------------------------------------------------+
|i4 : n(x_1^3*y_0)                                       |
|                                                        |
|      3 3                                               |
|o4 = x x                                                |
|      1 0                                               |
|                                                        |
|o4 : R                                                  |
+--------------------------------------------------------+
+-----------------------------------------------------------------------------+
|i5 : S = buildERing({symbol z}, {2}, QQ, 3);                                 |
+-----------------------------------------------------------------------------+
|i6 : vars S                                                                  |
|                                                                             |
|o6 = | z_(2,2) z_(2,1) z_(2,0) z_(1,2) z_(1,1) z_(1,0) z_(0,2) z_(0,1)       |
|     ------------------------------------------------------------------------|
|     z_(0,0) |                                                               |
|                                                                             |
|             1      9                                                        |
|o6 : Matrix S  <-- S                                                         |
+-----------------------------------------------------------------------------+
|i7 : m = buildEMonomialMap(R,S,{x_0^2*y_1})                                  |
|                                                                             |
|                  2     2     2     2     2     2     2     2     2          |
|o7 = map (R, S, {x y , x y , x y , x y , x y , x y , x y , x y , x y })      |
|                  2 2   2 1   2 0   1 2   1 1   1 0   0 2   0 1   0 0        |
|                                                                             |
|o7 : RingMap R <-- S                                                         |
+-----------------------------------------------------------------------------+
|i8 : m(z_(1,2))                                                              |
|                                                                             |
|      2                                                                      |
|o8 = x y                                                                     |
|      1 2                                                                    |
|                                                                             |
|o8 : R                                                                       |
+-----------------------------------------------------------------------------+

Caveat
======

If a given variable orbit of S has k indices, then the target monomial list in
L should only use indices between 0 and k-1.

See also
========

  * egbToric -- computes the kernel of an equivariant monomial
    map
  * buildERing -- creates a ring to be used with other
    functions in the EquivariantGB package

Ways to use buildEMonomialMap:
==============================

  * "buildEMonomialMap(Ring,Ring,List)"

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

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

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

The source of this document is in EquivariantGB.m2:1236:0.

buildERing(Ring,ZZ) -- creates a ERing from existing ERing
**********************************************************

  * Function: buildERing,
  * Usage:
        R = buildERing(S,n)
  * Inputs:
      * S, a ring (Macaulay2Doc), a Ring built by buildERing,
      * n, an integer (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * Degrees, => ..., default value {}, creates a ring to
        be used with other functions in the EquivariantGB package
      * MonomialOrder, => ..., default value Lex, creates a
        ring to be used with other functions in the EquivariantGB package
  * Outputs:
      * R, a ring (Macaulay2Doc), a Ring with the same variable
        structure as S, but with different index ranges.

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

+-------------------------------------------+
|i1 : S = buildERing({symbol z}, {1}, QQ, 2)|
|                                           |
|o1 = S                                     |
|                                           |
|o1 : PolynomialRing                        |
+-------------------------------------------+
|i2 : vars S                                |
|                                           |
|o2 = | z_1 z_0 |                           |
|                                           |
|             1      2                      |
|o2 : Matrix S  <-- S                       |
+-------------------------------------------+
|i3 : R = buildERing(S,5)                   |
|                                           |
|o3 = R                                     |
|                                           |
|o3 : PolynomialRing                        |
+-------------------------------------------+
|i4 : vars R                                |
|                                           |
|o4 = | z_4 z_3 z_2 z_1 z_0 |               |
|                                           |
|             1      5                      |
|o4 : Matrix R  <-- R                       |
+-------------------------------------------+

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

  * buildERing(Ring,ZZ) -- creates a ERing
    from existing ERing
-------------------------------------------------------------------------------

The source of this document is in EquivariantGB.m2:1129:0.

Completely
**********

Functions with optional argument named Completely:
==================================================

  * "reduce(...,Completely=>...)" -- see reduce, -- computes an
    equivariant normal form

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

The object Completely (missing documentation) is a symbol (Macaulay2Doc).

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

The source of this document is in currentString:1:391.

egb(...,Algorithm=>...) -- algorithm choice for egb
***************************************************

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

Buchberger:  This is a top level implementation of the equivariant Buchberger
algorithm.

Incremental: This strategy uses Macaulay2's built in Gröbner basis algorithm
gb (Macaulay2Doc). A Gröbner basis is computed for each truncated
ideal.  If no new elements are discovered up to Inc-action are discovered
between the n truncation and the 2n-1 truncation for some n larger than the
width of the generators, then the result is returned.

Signature: This is an implementation of an equivariant variant of the
Gao-Volny-Wang signature based Gröbner basis algorithm.  Experimental!

+--------------------------------------------+
|i1 : R = buildERing({symbol x}, {1}, QQ, 2);|
+--------------------------------------------+
|i2 : egb({x_0+x_1}, Algorithm=>Buchberger)  |
|                                            |
|o2 = {x }                                   |
|       0                                    |
|                                            |
|o2 : List                                   |
+--------------------------------------------+
|i3 : use R;                                 |
+--------------------------------------------+
|i4 : egb({x_0+x_1}, Algorithm=>Incremental) |
|                                            |
|o4 = {x }                                   |
|       0                                    |
|                                            |
|o4 : List                                   |
+--------------------------------------------+
|i5 : use R;                                 |
+--------------------------------------------+
|i6 : egb({x_0+x_1}, Algorithm=>Signature)   |
|-- TOTAL covered pairs = -6                 |
|                                            |
|o6 = {x  + x , 2x }                         |
|       1    0    0                          |
|                                            |
|o6 : List                                   |
+--------------------------------------------+

Functions with optional argument named Algorithm:
=================================================

  * egb(...,Algorithm=>...),
    -- algorithm choice for egb
  * "gb(...,Algorithm=>...)" -- see Gröbner basis algorithms (Macaulay2Doc),
  * "syz(...,Algorithm=>...)" -- see syz(Matrix) (Macaulay2Doc),
    -- compute the syzygy matrix

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

  * Default value: Buchberger,
  * Function: egb, -- computes equivariant Gröbner bases
  * Option key: Algorithm (Macaulay2Doc), -- an optional
    argument
-------------------------------------------------------------------------------

The source of this document is in EquivariantGB.m2:1299:0.

egbToric -- computes the kernel of an equivariant monomial map
**************************************************************

  * Usage:
        G = egbToric m
  * Inputs:
      * m, a ring map (Macaulay2Doc), an equivariant monomial
        map between rings with symmetric action
  * Optional inputs (Macaulay2Doc),:
      * OutFile, => ..., default value null, where to send
        messages
  * Outputs:
      * G, a list (Macaulay2Doc), an equivariant Gröbner basis for
        the kernel of the map

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

m should be a monomial map between rings created by buildERing.
Such a map can be constructed with buildEMonomialMap,
but this is not required.

For a map to ring R from ring S, the algorithm infers the entire equivariant
map from where m sends the variable orbit generators of S.  In particular for
each orbit of variables of the form x_{(i_1,...,i_k)}, the image of
x_{(0,...,k-1)} is used.

egbToric uses an incremental strategy, computing Gröbner bases for truncations
using FourTiTwo.  Because of FourTiTwo's efficiency,
this strategy tends to be much faster than general equivariant Gröbner basis
algorithms such as egb.

In the following example we compute an equivariant Gröbner basis for the
vanishing equations of the second Veronese of P^n, i.e. the variety of n x n
rank 1 symmetric matrices.

+-----------------------------------------------------------------------------+
|i1 : R = buildERing({symbol x}, {1}, QQ, 2);                                 |
+-----------------------------------------------------------------------------+
|i2 : S = buildERing({symbol y}, {2}, QQ, 2);                                 |
+-----------------------------------------------------------------------------+
|i3 : m = buildEMonomialMap(R,S,{x_0*x_1})                                    |
|                                                                             |
|                  2               2                                          |
|o3 = map (R, S, {x , x x , x x , x })                                        |
|                  1   1 0   1 0   0                                          |
|                                                                             |
|o3 : RingMap R <-- S                                                         |
+-----------------------------------------------------------------------------+
|i4 : G = egbToric(m, OutFile=>stdio)                                         |
|3                                                                            |
|     -- used .00253646 seconds                                               |
|     -- used .000762913 seconds                                              |
|(9, 9)                                                                       |
|new stuff found                                                              |
|4                                                                            |
|     -- used .00481931 seconds                                               |
|     -- used .00609676 seconds                                               |
|(16, 26)                                                                     |
|new stuff found                                                              |
|5                                                                            |
|     -- used .0103771 seconds                                                |
|     -- used .0336396 seconds                                                |
|(25, 60)                                                                     |
|6                                                                            |
|     -- used .0241139 seconds                                                |
|     -- used .219973 seconds                                                 |
|(36, 120)                                                                    |
|7                                                                            |
|     -- used .0516121 seconds                                                |
|     -- used .953926 seconds                                                 |
|(49, 217)                                                                    |
|                                                                             |
|                                   2                                         |
|o4 = {- y    + y   , - y   y    + y   , - y   y    + y   y   , - y   y    +  |
|         1,0    0,1     1,1 0,0    1,0     2,1 0,0    2,0 1,0     2,1 1,0    |
|     ------------------------------------------------------------------------|
|     y   y   , - y   y    + y   y   , - y   y    + y   y   , - y   y    +    |
|      2,0 1,1     2,2 1,0    2,1 2,0     3,2 1,0    3,0 2,1     3,2 1,0      |
|     ------------------------------------------------------------------------|
|     y   y   }                                                               |
|      3,1 2,0                                                                |
|                                                                             |
|o4 : List                                                                    |
+-----------------------------------------------------------------------------+

Caveat
======

It is not checked if m is equivariant.  Only the images of the orbit generators
of the source ring are examined and the rest of the map ignored.

See also
========

  * egb -- computes equivariant Gröbner bases
  * buildEMonomialMap -- builds an equivariant ring
    map

Ways to use egbToric:
=====================

  * "egbToric(RingMap)"

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

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

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

The source of this document is in EquivariantGB.m2:1194:0.

exponentMatrix -- puts the exponent of a monomial into matrix form
******************************************************************

  * Usage:
        A = exponentMatrix m
  * Inputs:
      * m, a ring element (Macaulay2Doc), an element of a
        ring created by buildERing.
  * Outputs:
      * A, a matrix (Macaulay2Doc),

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

Let R be a ring such that all variables have a single index on which the
symmetric group acts. Then monomials in R can be represented by a k by infinite
exponent matrix where k is the number of variable orbits.

This representation can be helpful for visualizing the structure of a monomial.

+--------------------------------------------------------+
|i1 : R = buildERing({symbol x, symbol y}, {1,1}, QQ, 4);|
+--------------------------------------------------------+
|i2 : exponentMatrix(x_0^3*y_2)                          |
|                                                        |
|o2 = | 3 0 0 0 |                                        |
|     | 0 0 1 0 |                                        |
|                                                        |
|              2       4                                 |
|o2 : Matrix ZZ  <-- ZZ                                  |
+--------------------------------------------------------+
|i3 : exponentMatrix(x_0*x_1*y_0*y_3)                    |
|                                                        |
|o3 = | 1 1 0 0 |                                        |
|     | 1 0 0 1 |                                        |
|                                                        |
|              2       4                                 |
|o3 : Matrix ZZ  <-- ZZ                                  |
+--------------------------------------------------------+

Caveat
======

The ring in which the monomial resides must have all variable orbits with
exactly one index.

Ways to use exponentMatrix:
===========================

  * "exponentMatrix(RingElement)"

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

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

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

The source of this document is in EquivariantGB.m2:1345:0.

incOrbit -- the increasing map orbit of an element
**************************************************

  * Usage:
        O = incOrbit(f,n)
        O = incOrbit(F,n)
  * Inputs:
      * f, a ring element (Macaulay2Doc), an element of a
        ring created by buildERing,
      * F, a list (Macaulay2Doc), a list of ring elements
      * n, an integer (Macaulay2Doc), the index bound
  * Optional inputs (Macaulay2Doc),:
      * Symmetrize => ..., default value false
  * Outputs:
      * O, a list (Macaulay2Doc), a list of all elements in the
        orbit of f or F

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

If F is an equivariant Gröbner basis for invariant ideal I with respect to a
width order then this method produces a traditional Gröbner basis for the nth
truncation of I.

If the optional argument Symmetrize is set to true, then the full S_n orbit is
produced.

+-----------------------------------------------------------+
|i1 : R = buildERing({symbol x}, {1}, QQ, 2);               |
+-----------------------------------------------------------+
|i2 : O = incOrbit(x_0^2, 4)                                |
|                                                           |
|       2   2   2   2                                       |
|o2 = {x , x , x , x }                                      |
|       0   1   2   3                                       |
|                                                           |
|o2 : List                                                  |
+-----------------------------------------------------------+
|i3 : P = incOrbit(x_0 + x_1^2, 3, Symmetrize=>true)        |
|                                                           |
|       2             2   2             2   2             2 |
|o3 = {x  + x , x  + x , x  + x , x  + x , x  + x , x  + x }|
|       1    0   1    0   2    0   2    0   2    1   2    1 |
|                                                           |
|o3 : List                                                  |
+-----------------------------------------------------------+

Caveat
======

The output is not necessarily in the same ring as the input.  The width bound
of the ring of the output will always be n.

Ways to use incOrbit:
=====================

  * "incOrbit(List,ZZ)"
  * "incOrbit(RingElement,ZZ)"

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

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

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

The source of this document is in EquivariantGB.m2:1383:0.

OutFile -- where to send messages
*********************************

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

Both egb, and egbToric, have the option to print
text while running, describing what it is doing, giving timings of certain
steps, and printing intermediate outputs.

Specify where to write this information.  Passing null (Macaulay2Doc),
will discard the messages Passing stdio (Macaulay2Doc),
will print them in the Macaulay2 session.  You can also
pass a file to save this information.

Functions with optional argument named OutFile:
===============================================

  * "egb(...,OutFile=>...)"
  * "egbToric(...,OutFile=>...)"

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

The object OutFile, is a symbol (Macaulay2Doc).

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

The source of this document is in EquivariantGB.m2:1317:0.

PrincipalSyzygies
*****************

Functions with optional argument named PrincipalSyzygies:
=========================================================

  * egb(...,PrincipalSyzygies=>...) (missing documentation)

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

The object PrincipalSyzygies (missing documentation) is a symbol (Macaulay2Doc).

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

The source of this document is in currentString:1:391.

PriorityQueue -- an efficient mutable priority queue implementation
*******************************************************************

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

A priority queue is a data structure for storing a collection of totally
ordered objects and keeping track of the minimum. This binomial heap
implementation allows for efficiently adding a new element to the queue,
accessing or deleting the minimum element, or merging two queues.  Efficiently
means time logarithmic in the size of the queue, or better.

+--------------------------------+
|i1 : Q = priorityQueue {3,7,1,5}|
|                                |
|o1 = PriorityQueue{...4...}     |
|                                |
|o1 : PriorityQueue              |
+--------------------------------+
|i2 : min Q                      |
|                                |
|o2 = 1                          |
+--------------------------------+
|i3 : deleteMin Q;               |
+--------------------------------+
|i4 : insert(Q,2);               |
+--------------------------------+
|i5 : min Q                      |
|                                |
|o5 = 2                          |
+--------------------------------+
|i6 : R = priorityQueue {4,6,8}; |
+--------------------------------+
|i7 : QR = mergePQ(Q,R);         |
+--------------------------------+
|i8 : length QR                  |
|                                |
|o8 = 7                          |
+--------------------------------+

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

  * "deleteMin(PriorityQueue)" -- see deleteMin, -- deletes
    the minimum element of the queue
  * insert(PriorityQueue,Thing), --
    insert a new element into the queue
  * length(PriorityQueue) -- returns the
    number of elements in the queue
  * "mergePQ(PriorityQueue,PriorityQueue)" -- see mergePQ, --
    merges two queues
  * min(PriorityQueue) -- return the minimum
    element of the queue
  * "pop(PriorityQueue)" -- see pop, -- returns the minimum element
    of the queue and deletes it

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

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

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

The source of this document is in EquivariantGB.m2:1418:0.

priorityQueue -- create a new PriorityQueue
*******************************************

  * Usage:
        Q = priorityQueue()
        Q = priorityQueue L
  * Inputs:
      * L, a list (Macaulay2Doc), a list of comparable elements
  * Outputs:
      * Q, an instance of the type PriorityQueue, a
        priority queue storing the elements of L

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

+-----------------------------------+
|i1 : Q = priorityQueue {1,5,2,-3,0}|
|                                   |
|o1 = PriorityQueue{...4...}        |
|                                   |
|o1 : PriorityQueue                 |
+-----------------------------------+
|i2 : min Q                         |
|                                   |
|o2 = -3                            |
+-----------------------------------+

Ways to use priorityQueue:
==========================

  * "priorityQueue()"
  * "priorityQueue(List)"

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

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

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

The source of this document is in EquivariantGB.m2:1440:0.

insert(PriorityQueue,Thing) -- insert a new element into the queue
******************************************************************

  * Function: insert (Macaulay2Doc),
  * Usage:
        Q = insert(Q,x)
  * Inputs:
      * Q, an instance of the type PriorityQueue,
      * x, a thing (Macaulay2Doc),
  * Outputs:
      * Q, an instance of the type PriorityQueue, the
        same PriorityQueue as the input, now with a new element inserted

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

+------------------------------+
|i1 : Q = priorityQueue {1,2,3}|
|                              |
|o1 = PriorityQueue{...4...}   |
|                              |
|o1 : PriorityQueue            |
+------------------------------+
|i2 : insert(Q,0)              |
|                              |
|o2 = PriorityQueue{...4...}   |
|                              |
|o2 : PriorityQueue            |
+------------------------------+
|i3 : insert(Q,4)              |
|                              |
|o3 = PriorityQueue{...4...}   |
|                              |
|o3 : PriorityQueue            |
+------------------------------+
|i4 : min Q                    |
|                              |
|o4 = 0                        |
+------------------------------+

Caveat
======

The priority queue Q is mutable and is altered by insert. Q is also the output
of the function.

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

  * insert(PriorityQueue,Thing), --
    insert a new element into the queue
-------------------------------------------------------------------------------

The source of this document is in EquivariantGB.m2:1484:0.

min(PriorityQueue) -- return the minimum element of the queue
*************************************************************

  * Function: min (Macaulay2Doc),
  * Usage:
        m = min Q
  * Inputs:
      * Q, an instance of the type PriorityQueue,
  * Outputs:
      * m, a thing (Macaulay2Doc), the minimum of Q

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

+-----------------------------------+
|i1 : Q = priorityQueue {1,5,2,-3,0}|
|                                   |
|o1 = PriorityQueue{...4...}        |
|                                   |
|o1 : PriorityQueue                 |
+-----------------------------------+
|i2 : min Q                         |
|                                   |
|o2 = -3                            |
+-----------------------------------+

Caveat
======

If the queue is empty, null is returned.

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

  * min(PriorityQueue) -- return the minimum
    element of the queue
-------------------------------------------------------------------------------

The source of this document is in EquivariantGB.m2:1460:0.

deleteMin -- deletes the minimum element of the queue
*****************************************************

  * Usage:
        Q = deleteMin Q
  * Inputs:
      * Q, an instance of the type PriorityQueue,
  * Outputs:
      * Q, an instance of the type PriorityQueue, the
        same PriorityQueue as the input, now with the minimum deleted

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

+------------------------------+
|i1 : Q = priorityQueue {1,2,3}|
|                              |
|o1 = PriorityQueue{...4...}   |
|                              |
|o1 : PriorityQueue            |
+------------------------------+
|i2 : deleteMin Q              |
|                              |
|o2 = PriorityQueue{...4...}   |
|                              |
|o2 : PriorityQueue            |
+------------------------------+
|i3 : min Q                    |
|                              |
|o3 = 2                        |
+------------------------------+

Caveat
======

The priority queue Q is mutable and is altered by deleteMin. Q is also the
output of the function.

See also
========

  * pop -- returns the minimum element of the queue and deletes it

Ways to use deleteMin:
======================

  * "deleteMin(PriorityQueue)"

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

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

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

The source of this document is in EquivariantGB.m2:1509:0.

pop -- returns the minimum element of the queue and deletes it
**************************************************************

  * Usage:
        m = pop Q
  * Inputs:
      * Q, an instance of the type PriorityQueue,
  * Outputs:
      * m, a thing (Macaulay2Doc), the minimum element

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

pop both returns the minimum element and deletes it from the queue.

+------------------------------+
|i1 : Q = priorityQueue {1,2,3}|
|                              |
|o1 = PriorityQueue{...4...}   |
|                              |
|o1 : PriorityQueue            |
+------------------------------+
|i2 : pop Q                    |
|                              |
|o2 = 1                        |
+------------------------------+
|i3 : pop Q                    |
|                              |
|o3 = 2                        |
+------------------------------+
|i4 : pop Q                    |
|                              |
|o4 = 3                        |
+------------------------------+
|i5 : pop Q                    |
+------------------------------+

Caveat
======

Both pop Q and min Q return the same value, but Q is altered by pop.

See also
========

  * min(PriorityQueue) -- return the minimum
    element of the queue
  * deleteMin -- deletes the minimum element of the queue

Ways to use pop:
================

  * "pop(PriorityQueue)"

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

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

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

The source of this document is in EquivariantGB.m2:1538:0.

mergePQ -- merges two queues
****************************

  * Usage:
        Q = mergePQ(Q,R)
  * Inputs:
      * Q, an instance of the type PriorityQueue,
      * R, an instance of the type PriorityQueue,
  * Outputs:
      * Q, an instance of the type PriorityQueue, the
        same PriorityQueue as the first input, now with the second merged into
        it

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

The output of the function is the priority queue whose elements are the
disjoint union of the elements of Q and R.  Note that Q is altered in the
process to become the merged queue.

+------------------------------+
|i1 : Q = priorityQueue {2,4,6}|
|                              |
|o1 = PriorityQueue{...4...}   |
|                              |
|o1 : PriorityQueue            |
+------------------------------+
|i2 : R = priorityQueue {1,3,5}|
|                              |
|o2 = PriorityQueue{...4...}   |
|                              |
|o2 : PriorityQueue            |
+------------------------------+
|i3 : mergePQ(Q,R)             |
|                              |
|o3 = PriorityQueue{...4...}   |
|                              |
|o3 : PriorityQueue            |
+------------------------------+
|i4 : pop Q                    |
|                              |
|o4 = 1                        |
+------------------------------+
|i5 : pop Q                    |
|                              |
|o5 = 2                        |
+------------------------------+

Caveat
======

The priority queue Q is mutable and is altered by mergePQ. The elements of Q
and R must be comparable to each other.

Ways to use mergePQ:
====================

  * "mergePQ(PriorityQueue,PriorityQueue)"

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

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

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

The source of this document is in EquivariantGB.m2:1587:0.

length(PriorityQueue) -- returns the number of elements in the queue
********************************************************************

  * Function: length (Macaulay2Doc),
  * Usage:
        n = length Q
  * Inputs:
      * Q, an instance of the type PriorityQueue,
  * Outputs:
      * n, an integer (Macaulay2Doc),

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

+------------------------------+
|i1 : Q = priorityQueue {1,2,3}|
|                              |
|o1 = PriorityQueue{...4...}   |
|                              |
|o1 : PriorityQueue            |
+------------------------------+
|i2 : length Q                 |
|                              |
|o2 = 3                        |
+------------------------------+
|i3 : insert(Q,0)              |
|                              |
|o3 = PriorityQueue{...4...}   |
|                              |
|o3 : PriorityQueue            |
+------------------------------+
|i4 : length Q                 |
|                              |
|o4 = 4                        |
+------------------------------+

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

  * length(PriorityQueue) -- returns the
    number of elements in the queue
-------------------------------------------------------------------------------

The source of this document is in EquivariantGB.m2:1557:0.

reduce -- computes an equivariant normal form
*********************************************

  * Usage:
        r = reduce(f,F)
  * Inputs:
      * f, a ring element (Macaulay2Doc), an element of a
        ring created by buildERing.
      * F, a list (Macaulay2Doc), a list of polynomials from the
        same ring as f.
  * Optional inputs (Macaulay2Doc),:
      * Completely => ..., default value false
  * Outputs:
      * r, a ring element (Macaulay2Doc), an equivariant
        normal form of f with respect to F.

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

Reduces f by the Inc-orbits of the set F until f is in a normal form. That is
the lead monomial of f is a standard monomial, not divisible by any monomial in
the orbit of any lead monomial of an element of F.  If F is an equivariant
Gröbner basis then r is 0 if and only if f is in the ideal generated by the
orbits of F.

If the optional argument Completely is set to true then normal form r will
contain only standard monomials.  If F is an equivariant Gröbner basis, then
the completely reduced normal form r is uniquely determined, otherwise there is
no such guarantee.

+--------------------------------------------+
|i1 : R = buildERing({symbol x}, {1}, QQ, 3);|
+--------------------------------------------+
|i2 : reduce(x_0^2 + x_0*x_2, {x_1})         |
|                                            |
|      2                                     |
|o2 = x                                      |
|      0                                     |
|                                            |
|o2 : R                                      |
+--------------------------------------------+

Caveat
======

The output does not necessarily belong to the same ring as the input.

Ways to use reduce:
===================

  * "reduce(RingElement,List)"

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

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

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

The source of this document is in EquivariantGB.m2:1271:0.

Shift
*****

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

  * degree(Shift) (missing documentation)
  * max(Shift) (missing documentation)
  * net(Shift) (missing documentation)
  * Shift * Number (missing documentation)
  * Shift * RingElement (missing documentation)
  * Shift * Shift (missing documentation)
  * Shift == Shift (missing documentation)
  * Shift ? Shift (missing documentation)
  * shift(Shift) (missing documentation)
  * width(Shift) (missing documentation)

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

The object Shift (missing documentation) is a type (Macaulay2Doc),
with ancestor classes BasicList (Macaulay2Doc), < Thing (Macaulay2Doc).

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

The source of this document is in currentString:1:391.

shift
*****

Ways to use shift:
==================

  * shift(List) (missing documentation)
  * shift(MutableList) (missing documentation)
  * shift(Shift) (missing documentation)

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

The object shift (missing documentation) is a method function (Macaulay2Doc).

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

The source of this document is in currentString:1:391.

Symmetrize
**********

Functions with optional argument named Symmetrize:
==================================================

  * egb(...,Symmetrize=>...) (missing documentation)
  * "incOrbit(...,Symmetrize=>...)" -- see incOrbit, -- the
    increasing map orbit of an element

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

The object Symmetrize (missing documentation) is a symbol (Macaulay2Doc).

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

The source of this document is in currentString:1:391.