This is SubalgebraBases.info, produced by Macaulay2, version 1.25.05

SubalgebraBases -- A package for finding canonical subalgebra bases (SAGBI bases)
*********************************************************************************

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

Let $R=k[f_1,\ldots,f_k]$ denote the subalgebra of the polynomial quotient ring
$k[x_1,\ldots,x_n] / I$ generated by $f_1, \ldots, f_k$. We say $f_1, \ldots,
f_k$ form a subalgebra basis with respect to a monomial order $<$ if the
initial algebra associated to $<$, defined as $$in(R) := k[in(f\%I) \mid f \in
R] \subseteq k[x_1, \ldots, x_n] / in(I),$$ is generated by the elements
$in(f_1\%I), \ldots , in(f_k\%I)$. The main functions provided by this package
are for computing these subalgebra bases: sagbi, isSAGBI,
and subduction.

Contributors
============

In addition to the authors below, we thank the following attendees of the 2020
Macaulay2 workshops at Cleveland State University and University of Warwick for
their contributions to the package.

  * Aaron Dall (see https://aarondall.com/mathematics/ )
  * Alessio D'Alì (see https://www.dima.unige.it/~dali/ )
  * Alicia Tocino (see https://aliciatocino.com )
  * Ayah Almousa (see https://sites.google.com/view/ayah-almousa )
  * Dharm Veer
  * Dipak Kumar Pradhan
  * Emil Sköldberg (see https://maths.nuigalway.ie/~emil/ )
  * Eriola Hoxhaj
  * Kriti Goel (see https://sites.google.com/view/kritigoel/home )
  * Liđan Edin
  * Peter Phelan (see https://maths.nuigalway.ie/~peterphelan/ )
  * Ritika Nair (see https://mathematics.ku.edu/people/ritika-nair )
  * Ilir Dema (see https://www.utm.utoronto.ca/math-cs-stats/people/ilir-dema )

Michael Stillman and  Harrison Tsai authored an earlier version of this
package.

References
==========

  * D. Kapur and K. Madlener.    A completion procedure for computing a
    canonical basis of a $k$-subalgebra. In E. Kaltofen and S. Watt, editors,
    Computers and Mathematics, pages 1-11, New York, NY, 1989, Springer US.
  * L. Robbiano and M. Sweedler.    Subalgebra bases. In W. Bruns and A. Simis,
    editors, Commutative Algebra, pages 61-87, Berlin, Heidelberg, 1990.
    Springer Berlin Heidelberg.
  * F. Ollivier.    Canonical Bases: Relations with Standard Bases, Finiteness
    conditions and application to tame automorphisms. In T. Mora, editor,
    Effective Methods in Algebraic Geometry, pages 379-4000, Birkhaeuser
    Boston, Boston, MA, 1991.
  * M. Stillman and H. Tsai. Using SAGBI bases to compute invariants.Journal of
    Pure and Applied Algebra, 139(1), pages 285-302, 1999.
  * B. Sturmfels.    Groebner bases and Convex Polytopes. Volume 8 of
    University Lecture Series. American Mathematical Society, Providence, RI,
    1996.

See also
========

  * Example_colon_ Translation and rotation sub-actions of the adjoint action of SE(3)

Authors
=======

  * Michael Burr (see https://cecas.clemson.edu/~burr2/ ) <burr2@clemson.edu>
  * Oliver Clarke (see https://www.oliverclarkemath.com/ )
    <oliver.clarke.crgs@gmail.com>
  * Timothy Duff (see https://timduff35.github.io/timduff35/ ) <timduff@uw.edu>
  * Jackson Leaman <jacksonleaman@gmail.com>
  * Nathan Nichols <nathannichols454@gmail.com>
  * Elise Walker (see https://sites.google.com/view/elise-walker/home )
    <elise.walker@tamu.edu>

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

Version 1.3 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 2024-03-18, in the article
SubalgebraBases in Macaulay2 (see https://msp.org/jsag/2024/14-1/p11.xhtml )
(DOI: 10.2140/jsag.2024.14.97 (see https://doi.org/10.2140/jsag.2024.14.97 )).
That version can be obtained from the journal (see
https://msp.org/jsag/2024/14-1/jsag-v14-n1-x11-SAGBIBases.zip ).

Version
=======

This documentation describes version 1.4 of SubalgebraBases.

Citation
========

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

+-----------------------------------------------------------------------------+
|@misc{SubalgebraBasesSource,                                                 |
|  title = {{SubalgebraBases: Canonical subalgebra bases (aka SAGBI/Khovanskii|
|  author = {Michael Burr and Oliver Clarke and Timothy Duff and Jackson Leama|
|  howpublished = {A \emph{Macaulay2} package available at                    |
|    \url{https://github.com/Macaulay2/M2/tree/master/M2/Macaulay2/packages}} |
|}                                                                            |
|                                                                             |
|@article{SubalgebraBasesArticle,                                             |
|  title = {{SubalgebraBases in \emph{Macaulay2}}},                           |
|  author = {Michael Burr and Oliver Clarke and Timothy Duff and Jackson Leama|
|  journal = {Journal of Software for Algebra and Geometry},                  |
|  volume = {14},                                                             |
|  year = {2024},                                                             |
|}                                                                            |
|-----------------------------------------------------------------------------|
| bases). Version~1.4}},                                                      |
|n and Nathan Nichols and Elise Walker},                                      |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|n and Nathan Nichols and Elise Walker},                                      |
+-----------------------------------------------------------------------------+

Exports
=======

  * Types
      * IntersectedSubring -- The type of all
        subrings arising from intersection
      * SAGBIBasis -- The type of all subalgebra bases
      * Subring -- The type of all subrings
  * Functions and commands
      * flattenedRing -- The flattened ring of a subring
        or sagbiBasis
      * forceSB -- declare the generators to be a complete
        subalgebra basis
      * groebnerMembershipTest -- Extrinsic
        method for subring membership
      * groebnerSubductionQuotient, --
        Extrinsic method for subduction quotients
      * isFullIntersection -- check correctness of
        intersection computation
      * isSAGBI -- Check if the generators are a subalgebra
        basis
      * originalSubringGens -- generators of the
        original subrings
      * presentationRing -- returns the presentation
        ring of a subring
      * sagbi -- Compute a subalgebra basis (sagbi basis)
      * sagbiBasis -- Constructs a computation object from a
        subring.
      * sagbiDegree -- The current degree of the subalgebra
        bases computation
      * sagbiLimit -- The current limit of the subalgebra
        bases computation
      * sagbiStatus -- checks if the subalgebra bases
        computation is done
      * subalgebraBasis -- Compute subalgebra basis
        generators
      * subduction -- Subduction against a set elements
      * subring -- Constructs a subring of a polynomial ring.
  * Methods
      * ambient(SAGBIBasis) -- The ambient ring
        of a SAGBIBasis computation object
      * ambient(Subring) -- The ambient ring of a
        subring
      * "flattenedRing(SAGBIBasis)" -- see flattenedRing,
        -- The flattened ring of a subring or sagbiBasis
      * "flattenedRing(Subring)" -- see flattenedRing, --
        The flattened ring of a subring or sagbiBasis
      * forceSB(SAGBIBasis) -- declare the
        generators to be a complete subalgebra basis
      * forceSB(Subring) -- declare the generators
        to be a complete subalgebra basis
      * generators(SAGBIBasis) -- Returns
        generators of a SAGBIBasis computation object
      * generators(Subring) -- A generating set
        of a subring
      * "groebnerMembershipTest(RingElement,Subring)" -- see
        groebnerMembershipTest, -- Extrinsic method for
        subring membership
      * "groebnerSubductionQuotient(RingElement,Subring)" -- see
        groebnerSubductionQuotient, -- Extrinsic
        method for subduction quotients
      * intersect(Subring,Subring), --
        Intersection of subrings
      * "isFullIntersection(IntersectedSubring)" -- see
        isFullIntersection, -- check correctness of
        intersection computation
      * "isSAGBI(List)" -- see isSAGBI, -- Check if the
        generators are a subalgebra basis
      * "isSAGBI(Matrix)" -- see isSAGBI, -- Check if the
        generators are a subalgebra basis
      * isSAGBI(SAGBIBasis) -- Check if the
        generators are a subalgebra basis
      * isSAGBI(Subring) -- Check if the
        generators are a subalgebra basis
      * net(SAGBIBasis) -- Short summary of a
        subalgebra basis computation object
      * net(Subring) -- Short summary of a subring
      * numgens(SAGBIBasis) -- The number of
        generators of a SAGBIBasis
      * numgens(Subring) -- The number of
        generators of a subring
      * "originalSubringGens(IntersectedSubring)" -- see
        originalSubringGens, -- generators of the original
        subrings
      * "presentationRing(Subring)" -- see presentationRing,
        -- returns the presentation ring of a subring
      * "Matrix % SAGBIBasis" -- see Reduction in subrings,
        -- Remainder modulo a subring
      * "Matrix % Subring" -- see Reduction in subrings,
        -- Remainder modulo a subring
      * "RingElement % SAGBIBasis" -- see Reduction in subrings,
        -- Remainder modulo a subring
      * "RingElement % Subring" -- see Reduction in subrings,
        -- Remainder modulo a subring
      * ring(SAGBIBasis) -- The lifted ring of a
        SAGBIBasis computation object
      * RingElement // Subring -- Subduction
        quotient with respect to a subring
      * "sagbi(List)" -- see sagbi, -- Compute a subalgebra basis
        (sagbi basis)
      * "sagbi(Matrix)" -- see sagbi, -- Compute a subalgebra
        basis (sagbi basis)
      * "sagbi(SAGBIBasis)" -- see sagbi, -- Compute a subalgebra
        basis (sagbi basis)
      * "sagbi(Subring)" -- see sagbi, -- Compute a subalgebra
        basis (sagbi basis)
      * "sagbiBasis(Subring)" -- see sagbiBasis, --
        Constructs a computation object from a subring.
      * "sagbiDegree(SAGBIBasis)" -- see sagbiDegree, -- The
        current degree of the subalgebra bases computation
      * "sagbiLimit(SAGBIBasis)" -- see sagbiLimit, -- The
        current limit of the subalgebra bases computation
      * "sagbiStatus(SAGBIBasis)" -- see sagbiStatus, --
        checks if the subalgebra bases computation is done
      * status(SAGBIBasis) -- status of the
        subalgebra bases computation
      * "subalgebraBasis(List)" -- see subalgebraBasis,
        -- Compute subalgebra basis generators
      * "subalgebraBasis(Matrix)" -- see subalgebraBasis,
        -- Compute subalgebra basis generators
      * "subalgebraBasis(Subring)" -- see subalgebraBasis,
        -- Compute subalgebra basis generators
      * "subduction(List,List)" -- see subduction, --
        Subduction against a set elements
      * "subduction(List,RingElement)" -- see subduction, --
        Subduction against a set elements
      * "subduction(Matrix,Matrix)" -- see subduction, --
        Subduction against a set elements
      * "subduction(Matrix,RingElement)" -- see subduction,
        -- Subduction against a set elements
      * "subduction(SAGBIBasis,Matrix)" -- see subduction, --
        Subduction against a set elements
      * "subduction(SAGBIBasis,RingElement)" -- see subduction,
        -- Subduction against a set elements
      * "subduction(Subring,Matrix)" -- see subduction, --
        Subduction against a set elements
      * "subduction(Subring,RingElement)" -- see subduction,
        -- Subduction against a set elements
      * "subring(List)" -- see subring, -- Constructs a subring
        of a polynomial ring.
      * "subring(Matrix)" -- see subring, -- Constructs a
        subring of a polynomial ring.
      * "subring(SAGBIBasis)" -- see subring, -- Constructs a
        subring of a polynomial ring.
  * Symbols
      * AutoSubduce -- Flag for autosubduction before the
        sagbi algorithm
      * AutoSubduceOnPartialCompletion,
        -- Subduct subalgebra generators at the end of the sagbi algorithm
      * CheckFullIntersection -- Flag for
        deciding if isFullIntersection is called
      * Compute -- Flag for performing computations while
        checking the completeness of a subalgebra basis
      * GeneratorSymbol -- variables for the
        presentationRing
      * ModifySAGBIBasis -- Flag for allowing the
        cached computation object to be modified
      * PrintLevel -- Levels of information displayed during
        Sagbi algorithm
      * Recompute -- Flag for restarting a sagbi or isSAGBI
        computation
      * ReduceNewGenerators -- Flag for reducing
        new generators in Sagbi algorithm
      * RenewOptions -- Flag for reselecting the options
        for a subalgebra bases computation
      * SAGBILimitType -- Flag for calculating degree
        limit in intersections
      * StorePending -- Flag for storing the pending list
        to the result of the Sagbi algorithm
      * SubductionMethod -- Subduction method for the
        Sagbi algorithm
      * UseSubringGens -- Flag for using the subring
        generators when checking a subalgebra basis

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

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

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

The source of this document is in SubalgebraBases/documentation.m2:79:0.

ambient(SAGBIBasis) -- The ambient ring of a SAGBIBasis computation object
**************************************************************************

  * Function: ambient (Macaulay2Doc),
  * Usage:
        result = ambient S
  * Inputs:
      * S, a SAGBIBasis,
  * Outputs:
      * result, a ring (Macaulay2Doc),

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

Returns the ambient ring of a SAGBIBasis. This is the
ambient ring of the generating Subring, This may be a
PolynomialRing (Macaulay2Doc), or QuotientRing (Macaulay2Doc).

+-----------------------------------------------------------------+
|i1 : R = QQ[x,y,z];                                              |
+-----------------------------------------------------------------+
|i2 : S = sagbi {x^2, y^2, z^2}                                   |
|                                                                 |
|o2 = SAGBIBasis Computation Object with 3 generators, Limit = 20.|
|                                                                 |
|o2 : SAGBIBasis                                                  |
+-----------------------------------------------------------------+
|i3 : ambient S                                                   |
|                                                                 |
|o3 = R                                                           |
|                                                                 |
|o3 : PolynomialRing                                              |
+-----------------------------------------------------------------+
|i4 : Q = R / ideal(x^3 - y);                                     |
+-----------------------------------------------------------------+
|i5 : S' = sagbi {x^3, y^2}                                       |
|                                                                 |
|o5 = SAGBIBasis Computation Object with 1 generators, Limit = 20.|
|                                                                 |
|o5 : SAGBIBasis                                                  |
+-----------------------------------------------------------------+
|i6 : ambient S'                                                  |
|                                                                 |
|o6 = Q                                                           |
|                                                                 |
|o6 : QuotientRing                                                |
+-----------------------------------------------------------------+

See also
========

  * Subring -- The type of all subrings
  * subring -- Constructs a subring of a polynomial ring.
  * SAGBIBasis -- The type of all subalgebra bases
  * sagbiBasis -- Constructs a computation object from a
    subring.
  * generators(SAGBIBasis) -- Returns
    generators of a SAGBIBasis computation object
  * ambient(Subring) -- The ambient ring of a
    subring

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

  * ambient(SAGBIBasis) -- The ambient ring of
    a SAGBIBasis computation object
-------------------------------------------------------------------------------

The source of this document is in SubalgebraBases/documentation.m2:2035:0.

ambient(Subring) -- The ambient ring of a subring
*************************************************

  * Function: ambient (Macaulay2Doc),
  * Usage:
        result = ambient S
  * Inputs:
      * S, a subring,
  * Outputs:
      * result, a ring (Macaulay2Doc),

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

Returns the ambient ring of the generating set of the Subring.
This may be a PolynomialRing (Macaulay2Doc), or
QuotientRing (Macaulay2Doc).

+----------------------------------+
|i1 : R = QQ[x,y,z];               |
+----------------------------------+
|i2 : S = subring({x^2, y^2, z^2});|
+----------------------------------+
|i3 : ambient S                    |
|                                  |
|o3 = R                            |
|                                  |
|o3 : PolynomialRing               |
+----------------------------------+
|i4 : Q = R / ideal(x^3 - y);      |
+----------------------------------+
|i5 : S' = subring({x^3, y^2});    |
+----------------------------------+
|i6 : ambient S'                   |
|                                  |
|o6 = Q                            |
|                                  |
|o6 : QuotientRing                 |
+----------------------------------+

See also
========

  * Subring -- The type of all subrings
  * subring -- Constructs a subring of a polynomial ring.
  * generators(Subring) -- A generating set of
    a subring
  * ambient(SAGBIBasis) -- The ambient ring of
    a SAGBIBasis computation object

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

  * ambient(Subring) -- The ambient ring of a
    subring
-------------------------------------------------------------------------------

The source of this document is in SubalgebraBases/documentation.m2:1719:0.

AutoSubduce -- Flag for autosubduction before the sagbi algorithm
*****************************************************************

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

Autosubduction is a procedure which performs subduction on a collection of ring
elements against each other, one at a time. This is typically performed on a
set of generators of a Subring, or SAGBIBasis.
The result of each subduction replaces the original element in the
collection and zeros are removed from the collection. If the elements form a
subalgebra basis, then the result of autosubduction is unique.

By default, the function sagbi, performs autosubduction on the
generators of the given Subring, before starting the main
algorithm. Setting this flag to false sometimes results in a performance
improvement, but with a risk of including nonreduced or redundant generators.

See also
========

  * sagbi -- Compute a subalgebra basis (sagbi basis)
  * subalgebraBasis -- Compute subalgebra basis
    generators
  * ReduceNewGenerators -- Flag for reducing new
    generators in Sagbi algorithm
  * subduction -- Subduction against a set elements
  * SubductionMethod -- Subduction method for the
    Sagbi algorithm
  * AutoSubduceOnPartialCompletion, --
    Subduct subalgebra generators at the end of the sagbi algorithm
  * PrintLevel -- Levels of information displayed during
    Sagbi algorithm
  * Recompute -- Flag for restarting a sagbi or isSAGBI
    computation
  * ReduceNewGenerators -- Flag for reducing new
    generators in Sagbi algorithm
  * RenewOptions -- Flag for reselecting the options for a
    subalgebra bases computation

Functions with optional argument named AutoSubduce:
===================================================

  * "forceSB(SAGBIBasis,AutoSubduce=>...)"
  * "forceSB(Subring,AutoSubduce=>...)"
  * "sagbi(...,AutoSubduce=>...)"
  * "sagbiBasis(...,AutoSubduce=>...)"
  * "subalgebraBasis(...,AutoSubduce=>...)"
  * "subduction(...,AutoSubduce=>...)"

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

The object AutoSubduce, is a symbol (Macaulay2Doc).

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

The source of this document is in SubalgebraBases/documentation.m2:309:0.

AutoSubduceOnPartialCompletion -- Subduct subalgebra generators at the end of the sagbi algorithm
*************************************************************************************************

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

During the main loop in sagbi, if no new subalgebra generators
are added and the AutoSubduceOnPartialCompletion,
flag is true then all current subalgebra
generators are subducted against each other. The autosubduction can be a
significant time investment, but it can speed up subsequent computations by
removing redundant generators.

See also
========

  * sagbi -- Compute a subalgebra basis (sagbi basis)
  * subalgebraBasis -- Compute subalgebra basis
    generators
  * AutoSubduce -- Flag for autosubduction before the sagbi
    algorithm
  * ReduceNewGenerators -- Flag for reducing new
    generators in Sagbi algorithm
  * subduction -- Subduction against a set elements
  * SubductionMethod -- Subduction method for the
    Sagbi algorithm
  * PrintLevel -- Levels of information displayed during
    Sagbi algorithm
  * Recompute -- Flag for restarting a sagbi or isSAGBI
    computation
  * ReduceNewGenerators -- Flag for reducing new
    generators in Sagbi algorithm
  * RenewOptions -- Flag for reselecting the options for a
    subalgebra bases computation

Functions with optional argument named AutoSubduceOnPartialCompletion:
======================================================================

  * "sagbi(...,AutoSubduceOnPartialCompletion=>...)"
  * "sagbiBasis(...,AutoSubduceOnPartialCompletion=>...)"
  * "subalgebraBasis(...,AutoSubduceOnPartialCompletion=>...)"
  * "subduction(...,AutoSubduceOnPartialCompletion=>...)"

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

The object AutoSubduceOnPartialCompletion,
is a symbol (Macaulay2Doc).

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

The source of this document is in SubalgebraBases/documentation.m2:460:0.

CheckFullIntersection -- Flag for deciding if isFullIntersection is called
**************************************************************************

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

If the option is set to true, then the function
intersect(Subring,Subring), performs two
tests. If either of these tests fail, then a relevant warning message is
displayed. Other than the warning messages, the output of the function
intersect(Subring,Subring), is not affected
by the value of this option. If the option CheckFullIntersection is set to
false then no warnings are produced.

The first test is performed at the beginning of the function call. It checks
whether any of the inputs is an intersected subring,
and applies isFullIntersection, to each instance. For
more details see isFullIntersection. If the function
isFullIntersection, returns false, i.e., the
generators of the input are not guaranteed to generate the full intersection,
then a warning is printed.

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x,y];                                                            |
+-----------------------------------------------------------------------------+
|i2 : S1 = subring {x^2, y^2};                                                |
+-----------------------------------------------------------------------------+
|i3 : S2 = subring {x*y};                                                     |
+-----------------------------------------------------------------------------+
|i4 : gens (S3 = intersect(S1, S2, Limit => 6, CheckFullIntersection =>       |
|                                                                             |
|o4 = | x2y2 |                                                                |
|                                                                             |
|             1      1                                                        |
|o4 : Matrix R  <-- R                                                         |
|-----------------------------------------------------------------------------|
|false))                                                                      |
+-----------------------------------------------------------------------------+
|i5 : isFullIntersection S3                                                   |
|                                                                             |
|o5 = false                                                                   |
+-----------------------------------------------------------------------------+
|i6 : gens (S4 = intersect(S3, S2, Limit => 6))                               |
|-- Warning! The input contains an IntersectedSubring whose generators may not|
|                                                                             |
|o6 = | x2y2 |                                                                |
|                                                                             |
|             1      1                                                        |
|o6 : Matrix R  <-- R                                                         |
|-----------------------------------------------------------------------------|
|generate the entire subring                                                  |
+-----------------------------------------------------------------------------+
|i7 : isFullIntersection S4                                                   |
|                                                                             |
|o7 = true                                                                    |
+-----------------------------------------------------------------------------+

In the example above, a warning is produced when computing $S4$ because the
input algebra $S3$ is not guaranteed to be the full intersection. However, the
final line shows that the generators of $S4$ are guaranteed to generate the
full intersection of $S2$ and $S3$.

The second test is performed at the end of the function call. It checks if the
result is guaranteed to generate the full intersection by calling
isFullIntersection, on the result. If the function
isFullIntersection, returns false, then a warning printed.
For instance, in the example above, the computation of $S3$ would print a
warning.

+---------------------------------------------------------------------+
|i8 : intersect(S1, S2, Limit => 6)                                   |
|-- Warning! Result is not a full intersection.  Try increasing Limit.|
|                                                                     |
|o8 = QQ[p_0], subring of R                                           |
|                                                                     |
|o8 : IntersectedSubring                                              |
+---------------------------------------------------------------------+

If this warning message appears, then it is recommended to set the option
SAGBILimitType, to its default value of Fixed or to use a
higher value for the option Limit.

See also
========

  * intersect(Subring,Subring), --
    Intersection of subrings
  * isFullIntersection -- check correctness of
    intersection computation
  * SAGBILimitType -- Flag for calculating degree limit
    in intersections
  * IntersectedSubring -- The type of all subrings
    arising from intersection
  * Subduction computation limit -- Bound
    for subalgebra basis computation

Functions with optional argument named CheckFullIntersection:
=============================================================

  * "intersect(Subring,Subring,CheckFullIntersection=>...)"

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

The object CheckFullIntersection, is a
symbol (Macaulay2Doc).

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

The source of this document is in SubalgebraBases/documentation.m2:1321:0.

Compute -- Flag for performing computations while checking the completeness of a subalgebra basis
*************************************************************************************************

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

A flag that determines whether additional computations may be performed.
When the flag is set to false, the function being called only uses the results
of prior computations, if they have been stored.    When previous computations
have not been performed, the function usually returns null.

When the flag is set to true, additional computations will be performed if the
prior computations are insufficient.

+------------------------------+
|i1 : R = QQ[x,y];             |
+------------------------------+
|i2 : S = subring{x+y,x*y};    |
+------------------------------+
|i3 : isSAGBI(S,Compute=>false)|
+------------------------------+
|i4 : isSAGBI(S,Compute=>true) |
|                              |
|o4 = true                     |
+------------------------------+
|i5 : sagbi S;                 |
+------------------------------+
|i6 : isSAGBI(S,Compute=>false)|
|                              |
|o6 = true                     |
+------------------------------+

See also
========

  * Recompute -- Flag for restarting a sagbi or isSAGBI
    computation
  * RenewOptions -- Flag for reselecting the options for a
    subalgebra bases computation

Functions with optional argument named Compute:
===============================================

  * "intersect(Subring,Subring,Compute=>...)"
  * "isSAGBI(List,Compute=>...)"
  * "isSAGBI(Matrix,Compute=>...)"
  * "isSAGBI(SAGBIBasis,Compute=>...)"
  * "isSAGBI(Subring,Compute=>...)"

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

The object Compute, is a symbol (Macaulay2Doc).

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

The source of this document is in SubalgebraBases/documentation.m2:989:0.

Example: Translation and rotation sub-actions of the adjoint action of SE(3)
****************************************************************************

The following example shows how to use this package to calculate the invariants
of the translation sub-action of the adjoint action of $SE(3)$, as studied by
Crook and Donelan.

+-----------------------------------------------------------------------+
|i1 : gndR = QQ[(t_1..t_3)|(w_1..w_3)|(v_1..v_3), MonomialOrder => Lex];|
+-----------------------------------------------------------------------+
|i2 : translation := matrix {{w_1}, {w_2}, {w_3}, {t_1*w_2+t_2*w_3+v_1},|
|         {-t_1*w_1+t_3*w_3+v_2}, {-t_2*w_1-t_3*w_2+v_3}};              |
|                                                                       |
|                6         1                                            |
|o2 : Matrix gndR  <-- gndR                                             |
+-----------------------------------------------------------------------+
|i3 : sag := sagbi transpose translation;                               |
+-----------------------------------------------------------------------+
|i4 : netList first entries gens sag                                    |
|                                                                       |
|     +------------------+                                              |
|o4 = |w                 |                                              |
|     | 3                |                                              |
|     +------------------+                                              |
|     |w                 |                                              |
|     | 2                |                                              |
|     +------------------+                                              |
|     |w                 |                                              |
|     | 1                |                                              |
|     +------------------+                                              |
|     |t w  + t w  - v   |                                              |
|     | 2 1    3 2    3  |                                              |
|     +------------------+                                              |
|     |t w  + t w  + v   |                                              |
|     | 1 2    2 3    1  |                                              |
|     +------------------+                                              |
|     |t w  - t w  - v   |                                              |
|     | 1 1    3 3    2  |                                              |
|     +------------------+                                              |
|     |w v  + w v  + w v |                                              |
|     | 1 1    2 2    3 3|                                              |
|     +------------------+                                              |
+-----------------------------------------------------------------------+

The generators above are the 5 invariants Crook and Donelan give in their
Equation (9), plus the additional 6th invariant. The computation below verifies
Theorem 2 of Crook and Donelan, describing rotational invariants in the case
where $m=3$.

+-----------------------------------------------------------------------------+
|i5 : R = QQ[x_1..x_9, MonomialOrder => Lex];                                 |
+-----------------------------------------------------------------------------+
|i6 : eqns := {x_1^2+x_2^2+x_3^2-1, x_1*x_4+x_2*x_5+x_3*x_6,                  |
|         x_1*x_7+x_2*x_8+x_3*x_9, x_1*x_4+x_2*x_5+x_3*x_6,                   |
|         x_4^2+x_5^2+x_6^2-1, x_4*x_7+x_5*x_8+x_6*x_9,                       |
|         x_1*x_7+x_2*x_8+x_3*x_9, x_4*x_7+x_5*x_8+x_6*x_9,                   |
|         x_7^2+x_8^2+x_9^2-1,                                                |
|         x_1*x_5*x_9-x_1*x_6*x_8-x_2*x_4*x_9+x_2*x_6*x_7+x_3*x_4*x_8-x_3*x_5*|
|-----------------------------------------------------------------------------|
|x_7-1};                                                                      |
+-----------------------------------------------------------------------------+
|i7 : sag1 = subring sagbi eqns;                                              |
+-----------------------------------------------------------------------------+
|i8 : SB = sagbi(sag1, Limit => 100);                                         |
+-----------------------------------------------------------------------------+
|i9 : isSAGBI SB                                                              |
|                                                                             |
|o9 = true                                                                    |
+-----------------------------------------------------------------------------+
|i10 : netList first entries gens SB                                          |
|                                                                             |
|      +----------------------------------------------------------------------|
|      | 2    2    2                                                          |
|o10 = |x  + x  + x                                                           |
|      | 7    8    9                                                          |
|      +----------------------------------------------------------------------|
|      |x x  + x x  + x x                                                     |
|      | 4 7    5 8    6 9                                                    |
|      +----------------------------------------------------------------------|
|      | 2    2    2                                                          |
|      |x  + x  + x                                                           |
|      | 4    5    6                                                          |
|      +----------------------------------------------------------------------|
|      |x x  + x x  + x x                                                     |
|      | 1 7    2 8    3 9                                                    |
|      +----------------------------------------------------------------------|
|      |x x  + x x  + x x                                                     |
|      | 1 4    2 5    3 6                                                    |
|      +----------------------------------------------------------------------|
|      | 2    2    2                                                          |
|      |x  + x  + x                                                           |
|      | 1    2    3                                                          |
|      +----------------------------------------------------------------------|
|      |x x x  - x x x  - x x x  + x x x  + x x x  - x x x                    |
|      | 1 5 9    1 6 8    2 4 9    2 6 7    3 4 8    3 5 7                   |
|      +----------------------------------------------------------------------|
|      | 2 2    2 2                            2 2    2 2                2 2  |
|      |x x  + x x  - 2x x x x  - 2x x x x  + x x  + x x  - 2x x x x  + x x  +|
|      | 4 8    4 9     4 5 7 8     4 6 7 9    5 7    5 9     5 6 8 9    6 7  |
|      +----------------------------------------------------------------------|
|      |     2        2                                         2        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  - x|
|      | 1 4 8    1 4 9    1 5 7 8    1 6 7 9    2 4 7 8    2 5 7    2 5 9    |
|      +----------------------------------------------------------------------|
|      |                         2        2        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 x  -|
|      | 1 4 5 8    1 4 6 9    1 5 7    1 6 7    2 4 8    2 4 5 7    2 5 6 9  |
|      +----------------------------------------------------------------------|
|      | 2 2    2 2                            2 2    2 2                2 2  |
|      |x x  + x x  - 2x x x x  - 2x x x x  + x x  + x x  - 2x x x x  + x x  +|
|      | 1 8    1 9     1 2 7 8     1 3 7 9    2 7    2 9     2 3 8 9    3 7  |
|      +----------------------------------------------------------------------|
|      | 2        2                                                    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 x  +|
|      | 1 5 8    1 6 9    1 2 4 8    1 2 5 7    1 3 4 9    1 3 6 7    2 4 7  |
|      +----------------------------------------------------------------------|
|      | 2 2    2 2                            2 2    2 2                2 2  |
|      |x x  + x x  - 2x x x x  - 2x x x x  + x x  + x x  - 2x x x x  + x x  +|
|      | 1 5    1 6     1 2 4 5     1 3 4 6    2 4    2 6     2 3 5 6    3 4  |
|      +----------------------------------------------------------------------|
|-----------------------------------------------------------------------------|
|-----------------------------------------------+                             |
|                                               |                             |
|                                               |                             |
|                                               |                             |
|-----------------------------------------------+                             |
|                                               |                             |
|                                               |                             |
|-----------------------------------------------+                             |
|                                               |                             |
|                                               |                             |
|                                               |                             |
|-----------------------------------------------+                             |
|                                               |                             |
|                                               |                             |
|-----------------------------------------------+                             |
|                                               |                             |
|                                               |                             |
|-----------------------------------------------+                             |
|                                               |                             |
|                                               |                             |
|                                               |                             |
|-----------------------------------------------+                             |
|                                               |                             |
|                                               |                             |
|-----------------------------------------------+                             |
|  2 2                                          |                             |
| x x                                           |                             |
|  6 8                                          |                             |
|-----------------------------------------------+                             |
|                                     2        2|                             |
| x x x  - x x x x  - x x x x  + x x x  + x x x |                             |
|2 6 8 9    3 4 7 9    3 5 8 9    3 6 7    3 6 8|                             |
|-----------------------------------------------+                             |
|    2        2                   2             |                             |
| x x x  - x x x  + x x x x  - x x x  + x x x x |                             |
|  2 6 8    3 4 9    3 4 6 7    3 5 9    3 5 6 8|                             |
|-----------------------------------------------+                             |
|  2 2                                          |                             |
| x x                                           |                             |
|  3 8                                          |                             |
|-----------------------------------------------+                             |
|  2                              2        2    |                             |
| x x x  - x x x x  - x x x x  + x x x  + x x x |                             |
|  2 6 9    2 3 5 9    2 3 6 8    3 4 7    3 5 8|                             |
|-----------------------------------------------+                             |
|  2 2                                          |                             |
| x x                                           |                             |
|  3 5                                          |                             |
|-----------------------------------------------+                             |
+-----------------------------------------------------------------------------+

References
==========

D. Crook and P. Donelan.    Polynomial invariants and SAGBI bases for
multi-screws. arXiv:2001.05417, 2020. (see https://arxiv.org/abs/2001.05417 )

See also
========

  * sagbi -- Compute a subalgebra basis (sagbi basis)
  * generators(SAGBIBasis) -- Returns
    generators of a SAGBIBasis computation object
  * isSAGBI -- Check if the generators are a subalgebra basis
-------------------------------------------------------------------------------

The source of this document is in SubalgebraBases/documentation.m2:2517:0.

flattenedRing -- The flattened ring of a subring or sagbiBasis
**************************************************************

  * Usage:
        result = flattened S
        result = flattened SB
  * Inputs:
      * S, a subring,
      * SB, a SAGBIBasis,
  * Outputs:
      * result, a ring (Macaulay2Doc), the flattened ring of the
        ambient ring

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

Returns the flattened ring of the ambient ring. This may be a
PolynomialRing (Macaulay2Doc), or QuotientRing (Macaulay2Doc).

+-----------------------------------+
|i1 : R = (QQ[x])[y]/ideal(x^2-y^3);|
+-----------------------------------+
|i2 : S = subring {x+y,x*y};        |
+-----------------------------------+
|i3 : ambient S                     |
|                                   |
|o3 = R                             |
|                                   |
|o3 : QuotientRing                  |
+-----------------------------------+
|i4 : flattenedRing S               |
|                                   |
|      QQ[y, x]                     |
|o4 = ---------                     |
|        3    2                     |
|     - y  + x                      |
|                                   |
|o4 : QuotientRing                  |
+-----------------------------------+

See also
========

  * Subring -- The type of all subrings
  * subring -- Constructs a subring of a polynomial ring.
  * SAGBIBasis -- The type of all subalgebra bases
  * sagbiBasis -- Constructs a computation object from a
    subring.
  * ambient(SAGBIBasis) -- The ambient ring of
    a SAGBIBasis computation object

Ways to use flattenedRing:
==========================

  * "flattenedRing(SAGBIBasis)"
  * "flattenedRing(Subring)"

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

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

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

The source of this document is in SubalgebraBases/documentation.m2:2670:0.

forceSB -- declare the generators to be a complete subalgebra basis
*******************************************************************

  * Usage:
        forceSB S
        forceSB SB
  * Inputs:
      * S, a subring,
      * SB, a SAGBIBasis,

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

If forceSB is called on a SAGBIBasis, $SB$, then the function
performs autosubduction on the subalgebra generators of $SB$. The completion
flag is then set to complete without checking whether the generators form a
subalgebra basis.

If forceSB is called on a subring, $S$, then the function
performs autosubduction on the generators of $S$.    The completion flag is
then set to complete without checking whether the generators form a subalgebra
basis.

In each case above, the option UseSubringGens can be toggled between true and
false to operate on the subring generators in the case where the input is a
SAGBIBasis, and operate on any partial subalgebra basis
created for $S$ when the the input is a subring.

If the generators supplied to forceSB do not form a subalgebra basis, then the
resulting behavior may be unexpected.

+--------------------------------------------------------------------------+
|i1 : R = QQ[x,y];                                                         |
+--------------------------------------------------------------------------+
|i2 : S = subring{x+y,x*y,x*y^2}                                           |
|                                                                          |
|o2 = QQ[p_0..p_2], subring of R                                           |
|                                                                          |
|o2 : Subring                                                              |
+--------------------------------------------------------------------------+
|i3 : forceSB S;                                                           |
+--------------------------------------------------------------------------+
|i4 : isSAGBI S                                                            |
|                                                                          |
|o4 = true                                                                 |
+--------------------------------------------------------------------------+
|i5 : sagbi(S,Recompute=>true)                                             |
|                                                                          |
|o5 = Partial SAGBIBasis Computation Object with 20 generators, Limit = 20.|
|                                                                          |
|o5 : SAGBIBasis                                                           |
+--------------------------------------------------------------------------+
|i6 : isSAGBI S                                                            |
|                                                                          |
|o6 = true                                                                 |
+--------------------------------------------------------------------------+

In this example, forceSB causes isSAGBI, to return true even
though the generators of $S$ do not form a subalgebra basis. Recomputing the
subalgebra basis exposes that the generators do not form a subalgebra basis.

Optional inputs for specific uses (see forceSB(SAGBIBasis),
and forceSB(Subring))
include the following: AutoSubduce, Limit,
see PrintLevel, RenewOptions,
see Subduction strategies,
UseSubringGens, and SubductionMethod.

See also
========

  * Subring -- The type of all subrings
  * SAGBIBasis -- The type of all subalgebra bases
  * isSAGBI -- Check if the generators are a subalgebra basis
  * forceSB(SAGBIBasis) -- declare the
    generators to be a complete subalgebra basis
  * forceSB(Subring) -- declare the generators to
    be a complete subalgebra basis
  * AutoSubduce -- Flag for autosubduction before the sagbi
    algorithm
  * Subduction computation limit -- Bound
    for subalgebra basis computation
  * PrintLevel -- Levels of information displayed during
    Sagbi algorithm
  * RenewOptions -- Flag for reselecting the options for a
    subalgebra bases computation
  * Subduction strategies -- Update procedure for
    the Sagbi algorithm
  * UseSubringGens -- Flag for using the subring
    generators when checking a subalgebra basis
  * SubductionMethod -- Subduction method for the
    Sagbi algorithm

Ways to use forceSB:
====================

  * forceSB(SAGBIBasis) -- declare the
    generators to be a complete subalgebra basis
  * forceSB(Subring) -- declare the generators to
    be a complete subalgebra basis

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

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

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

The source of this document is in SubalgebraBases/documentation.m2:2275:0.

forceSB(SAGBIBasis) -- declare the generators to be a complete subalgebra basis
*******************************************************************************

  * Function: forceSB,
  * Usage:
        forceSB SB
  * Inputs:
      * SB, a SAGBIBasis,
  * Optional inputs (Macaulay2Doc),:
      * AutoSubduce, => a Boolean value (Macaulay2Doc),
        default value true, a flag indicating whether
        to autosubduce the generators of $SB$.
      * Limit, => an integer (Macaulay2Doc),
        default value 20, a degree limit for the binomial
        S-pairs that are computed internally.
      * PrintLevel, => an integer (Macaulay2Doc),
        default value 0, indicating how much additional information should be
        printed. When this is greater than zero, information is printed about
        the progress of the computation.
      * RenewOptions, => a Boolean value (Macaulay2Doc),
        default value false, if true then the
        computation will use the options specified, otherwise it will use the
        previously selected options (except for the following, which may always
        be specified: PrintLevel, Limit,
        see Recompute, and
        RenewOptions)
      * Strategy, => a string (Macaulay2Doc),
        default value "Master", the update strategy used
        for updating the SAGBIBasis: "DegreeByDegree", "Incremental", and
        "Master". The strategy "Master" is a hybrid method that combines the
        other two; starting with "DegreeByDegree" for low degrees and switching
        to "Incremental".
      * UseSubringGens, => a Boolean value (Macaulay2Doc),
        default value false, a flag indicating whether
        to use the generators of the subring. If false, then the method uses
        the subalgebra generators of the partial subalgebra basis.
      * SubductionMethod, => a string (Macaulay2Doc),
        default value "Engine", the name of the method
        used for subduction either: "Top" or "Engine".

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

When forceSB is called on a SAGBIBasis, $SB$, the function
performs autosubduction on the subalgebra generators of $SB$. The completion
flag is then set to complete without checking whether the generators form a
subalgebra basis.

The option UseSubringGens can be toggled between true and false to operate on
the subring generators.

If the generators supplied to forceSB do not form a subalgebra basis, then the
resulting behavior may be unexpected.

+--------------------------------------------------------------------------+
|i1 : R = QQ[x,y];                                                         |
+--------------------------------------------------------------------------+
|i2 : S = sagbi({x+y,x*y,x*y^2},Limit=>10)                                 |
|                                                                          |
|o2 = Partial SAGBIBasis Computation Object with 10 generators, Limit = 10.|
|                                                                          |
|o2 : SAGBIBasis                                                           |
+--------------------------------------------------------------------------+
|i3 : forceSB S;                                                           |
+--------------------------------------------------------------------------+
|i4 : isSAGBI S                                                            |
|                                                                          |
|o4 = false                                                                |
+--------------------------------------------------------------------------+
|i5 : sagbi(S,Recompute=>true)                                             |
|                                                                          |
|o5 = Partial SAGBIBasis Computation Object with 20 generators, Limit = 20.|
|                                                                          |
|o5 : SAGBIBasis                                                           |
+--------------------------------------------------------------------------+
|i6 : isSAGBI S                                                            |
|                                                                          |
|o6 = false                                                                |
+--------------------------------------------------------------------------+

In this example, forceSB causes isSAGBI to return true even though the
generators of $S$ do not form a subalgebra basis. Recomputing the subalgebra
basis exposes that the generators do not form a subalgebra basis.

See also
========

  * Subring -- The type of all subrings
  * SAGBIBasis -- The type of all subalgebra bases
  * isSAGBI -- Check if the generators are a subalgebra basis
  * forceSB -- declare the generators to be a complete
    subalgebra basis
  * forceSB(Subring) -- declare the generators to
    be a complete subalgebra basis
  * AutoSubduce -- Flag for autosubduction before the sagbi
    algorithm
  * Subduction computation limit -- Bound
    for subalgebra basis computation
  * PrintLevel -- Levels of information displayed during
    Sagbi algorithm
  * RenewOptions -- Flag for reselecting the options for a
    subalgebra bases computation
  * Subduction strategies -- Update procedure for
    the Sagbi algorithm
  * UseSubringGens -- Flag for using the subring
    generators when checking a subalgebra basis
  * SubductionMethod -- Subduction method for the
    Sagbi algorithm

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

  * forceSB(SAGBIBasis) -- declare the
    generators to be a complete subalgebra basis
-------------------------------------------------------------------------------

The source of this document is in SubalgebraBases/documentation.m2:2348:0.

forceSB(Subring) -- declare the generators to be a complete subalgebra basis
****************************************************************************

  * Function: forceSB,
  * Usage:
        forceSB S
  * Inputs:
      * S, a subring,
  * Optional inputs (Macaulay2Doc),:
      * AutoSubduce, => a Boolean value (Macaulay2Doc),
        default value true, a flag indicating whether
        to autosubduce the generators of $S$.
      * Limit, => an integer (Macaulay2Doc),
        default value 20, a degree limit for the binomial
        S-pairs that are computed internally.
      * PrintLevel, => an integer (Macaulay2Doc),
        default value 0, indicating how much additional information should be
        printed. When this is greater than zero, information is printed about
        the progress of the computation.
      * RenewOptions, => a Boolean value (Macaulay2Doc),
        default value false, if true then the
        computation will use the options specified, otherwise it will use the
        previously selected options (except for the following, which may always
        be specified: PrintLevel, Limit,
        see Recompute, and
        RenewOptions)
      * Strategy, => a string (Macaulay2Doc),
        default value "Master", the update strategy used
        for updating the SAGBIBasis: "DegreeByDegree", "Incremental", and
        "Master". The strategy "Master" is a hybrid method that combines the
        other two; starting with "DegreeByDegree" for low degrees and switching
        to "Incremental".
      * UseSubringGens, => a Boolean value (Macaulay2Doc),
        default value true, a flag indicating whether
        to use the generators of the subring. If false then the method uses the
        subalgebra generators of the partial subalgebra basis.
      * SubductionMethod, => a string (Macaulay2Doc),
        default value "Engine", the name of the method
        used for subduction either: "Top" or "Engine".

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

When forceSB is called on a subring, $S$, the function performs
autosubduction on the generators of $S$.    The completion flag is then set to
complete without checking whether the generators form a subalgebra basis.

The option UseSubringGens can be toggled between true and false to operate on
any partial subalgebra basis created for $S$.

If the generators supplied to forceSB do not form a subalgebra basis, then the
resulting behavior may be unexpected.

+--------------------------------------------------------------------------+
|i1 : R = QQ[x,y];                                                         |
+--------------------------------------------------------------------------+
|i2 : S = subring{x+y,x*y,x*y^2}                                           |
|                                                                          |
|o2 = QQ[p_0..p_2], subring of R                                           |
|                                                                          |
|o2 : Subring                                                              |
+--------------------------------------------------------------------------+
|i3 : forceSB S;                                                           |
+--------------------------------------------------------------------------+
|i4 : isSAGBI S                                                            |
|                                                                          |
|o4 = true                                                                 |
+--------------------------------------------------------------------------+
|i5 : sagbi(S,Recompute=>true)                                             |
|                                                                          |
|o5 = Partial SAGBIBasis Computation Object with 20 generators, Limit = 20.|
|                                                                          |
|o5 : SAGBIBasis                                                           |
+--------------------------------------------------------------------------+
|i6 : isSAGBI S                                                            |
|                                                                          |
|o6 = true                                                                 |
+--------------------------------------------------------------------------+

In this example, forceSB causes isSAGBI, to return true even
though the generators of $S$ do not form a subalgebra basis. Recomputing the
subalgebra basis exposes that the generators do not form a subalgebra basis.

See also
========

  * Subring -- The type of all subrings
  * SAGBIBasis -- The type of all subalgebra bases
  * isSAGBI -- Check if the generators are a subalgebra basis
  * forceSB -- declare the generators to be a complete
    subalgebra basis
  * forceSB(SAGBIBasis) -- declare the
    generators to be a complete subalgebra basis
  * AutoSubduce -- Flag for autosubduction before the sagbi
    algorithm
  * Subduction computation limit -- Bound
    for subalgebra basis computation
  * PrintLevel -- Levels of information displayed during
    Sagbi algorithm
  * RenewOptions -- Flag for reselecting the options for a
    subalgebra bases computation
  * Subduction strategies -- Update procedure for
    the Sagbi algorithm
  * UseSubringGens -- Flag for using the subring
    generators when checking a subalgebra basis
  * SubductionMethod -- Subduction method for the
    Sagbi algorithm

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

  * forceSB(Subring) -- declare the generators to
    be a complete subalgebra basis
-------------------------------------------------------------------------------

The source of this document is in SubalgebraBases/documentation.m2:2423:0.

generators(SAGBIBasis) -- Returns generators of a SAGBIBasis computation object
*******************************************************************************

  * Function: generators (Macaulay2Doc),
  * Usage:
        result = gens S
  * Inputs:
      * S, a SAGBIBasis,
  * Optional inputs (Macaulay2Doc),:
      * CoefficientRing (Macaulay2Doc), => a
        Boolean value (Macaulay2Doc), default value null, unused
        option
  * Outputs:
      * result, a matrix (Macaulay2Doc),

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

Returns a list of subalgebra generators of the Subring,
underlying the SAGBIBasis. If the subalgebra generators do
not form a complete subalgebra basis (for example if they were obtained from a
partial computation), then the generators obtained from this command may not be
a generating set for the original subring.

+-------------------------------------+
|i1 : R = QQ[x,y];                    |
+-------------------------------------+
|i2 : S = subring {x*y, x^2*y, x^3*y};|
+-------------------------------------+
|i3 : gens S                          |
|                                     |
|o3 = | xy x2y x3y |                  |
|                                     |
|             1      3                |
|o3 : Matrix R  <-- R                 |
+-------------------------------------+
|i4 : SB = sagbi(S, Limit => 3);      |
+-------------------------------------+
|i5 : gens SB                         |
|                                     |
|o5 = | xy x2y |                      |
|                                     |
|             1      2                |
|o5 : Matrix R  <-- R                 |
+-------------------------------------+
|i6 : isSAGBI S                       |
|                                     |
|o6 = true                            |
+-------------------------------------+
|i7 : isSAGBI SB                      |
|                                     |
|o7 = false                           |
+-------------------------------------+

See also
========

  * SAGBIBasis -- The type of all subalgebra bases
  * generators(Subring) -- A generating set of
    a subring
  * sagbi -- Compute a subalgebra basis (sagbi basis)

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

  * generators(SAGBIBasis) -- Returns
    generators of a SAGBIBasis computation object
-------------------------------------------------------------------------------

The source of this document is in SubalgebraBases/documentation.m2:1972:0.

generators(Subring) -- A generating set of a subring
****************************************************

  * Function: generators (Macaulay2Doc),
  * Usage:
        result = gens S
  * Inputs:
      * S, a subring,
  * Optional inputs (Macaulay2Doc),:
      * CoefficientRing (Macaulay2Doc), => a
        Boolean value (Macaulay2Doc), default value null, unused
        option
  * Outputs:
      * result, a matrix (Macaulay2Doc),

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

Returns a generating set for the Subring, as a one-row matrix.

+----------------------------------+
|i1 : R = QQ[x,y,z];               |
+----------------------------------+
|i2 : S = subring({x^2, y^2, z^2});|
+----------------------------------+
|i3 : gens S                       |
|                                  |
|o3 = | x2 y2 z2 |                 |
|                                  |
|             1      3             |
|o3 : Matrix R  <-- R              |
+----------------------------------+

See also
========

  * Subring -- The type of all subrings
  * subring -- Constructs a subring of a polynomial ring.
  * generators(SAGBIBasis) -- Returns
    generators of a SAGBIBasis computation object

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

  * generators(Subring) -- A generating set of
    a subring
-------------------------------------------------------------------------------

The source of this document is in SubalgebraBases/documentation.m2:1690:0.

GeneratorSymbol -- variables for the presentationRing
*****************************************************

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

A symbol to be used for variables of the presentationRing.

+-------------------------------------------------------+
|i1 : R = QQ[x,y];                                      |
+-------------------------------------------------------+
|i2 : S = subring({x^2, y^2, x*y}, GeneratorSymbol => f)|
|                                                       |
|o2 = QQ[f_1..f_3], subring of R                        |
|                                                       |
|o2 : Subring                                           |
+-------------------------------------------------------+
|i3 : (x+y)^4 // S                                      |
|                                                       |
|      2    2                     2                     |
|o3 = f  + f  + 4f f  + 4f f  + 6f                      |
|      1    2     1 3     2 3     3                     |
|                                                       |
|o3 : QQ[f ..f ]                                        |
|         1   3                                         |
+-------------------------------------------------------+

If a symbol is not specified, then the variables of the presentationRing,
are indexed from 0 and use the default symbol. If a symbol is
specified, then the indices start from 1.

See also
========

  * Subring -- The type of all subrings
  * subring -- Constructs a subring of a polynomial ring.
  * presentationRing -- returns the presentation ring
    of a subring

Functions with optional argument named GeneratorSymbol:
=======================================================

  * "subring(...,GeneratorSymbol=>...)" -- see subring, --
    Constructs a subring of a polynomial ring.

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

The object GeneratorSymbol, is a symbol (Macaulay2Doc).

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

The source of this document is in SubalgebraBases/documentation.m2:1830:0.

groebnerMembershipTest -- Extrinsic method for subring membership
*****************************************************************

  * Usage:
        result = groebnerMembershipTest(f, S)
  * Inputs:
      * f, a ring element (Macaulay2Doc),
      * S, a subring,
  * Outputs:
      * result, a Boolean value (Macaulay2Doc), which indicates
        if $f$ belongs to $S$.

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

Uses the extrinsic method (based on Groebner bases) to test membership of a
polynomial in a subring.

+----------------------------------+
|i1 : R = QQ[x,y];                 |
+----------------------------------+
|i2 : S = subring {x^2 - x*y, x^4};|
+----------------------------------+
|i3 : f1 = x^2*y^2 - 2*x^3*y;      |
+----------------------------------+
|i4 : groebnerMembershipTest(f1, S)|
|                                  |
|o4 = true                         |
+----------------------------------+
|i5 : f2 = x^10;                   |
+----------------------------------+
|i6 : groebnerMembershipTest(f2, S)|
|                                  |
|o6 = false                        |
+----------------------------------+

If a subalgebra basis is known for $S$, then it is recommended to use
RingElement % Subring, instead.

See also
========

  * Subring -- The type of all subrings
  * RingElement % Subring -- Remainder modulo a
    subring
  * groebnerSubductionQuotient -- Extrinsic
    method for subduction quotients
  * RingElement // Subring -- Subduction
    quotient with respect to a subring
  * sagbi -- Compute a subalgebra basis (sagbi basis)

Ways to use groebnerMembershipTest:
===================================

  * "groebnerMembershipTest(RingElement,Subring)"

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

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

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

The source of this document is in SubalgebraBases/documentation.m2:1082:0.

groebnerSubductionQuotient -- Extrinsic method for subduction quotients
***********************************************************************

  * Usage:
        result = groebnerSubductionQuotient(f, S)
  * Inputs:
      * f, a ring element (Macaulay2Doc),
      * S, a subring,
  * Outputs:
      * result, a ring element (Macaulay2Doc), the normal
        form of $f$ in the presentationRing,

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

Uses the extrinsic method to compute a subduction quotient of $f$ by the
generators of $S$. A subduction quotient is an element of the
presentationRing. The variables of this ring correspond to
the generators of $S$. A subduction quotient is a polynomial representation of
$f - f\%S$ in terms of the generators of $S$. The value of this element in the
ambient(Subring), ring can be recovered using the
field presentationMap of the subring.

+------------------------------------------+
|i1 : R = QQ[x,y];                         |
+------------------------------------------+
|i2 : S = subring {x+y, x*y, x*y^2};       |
+------------------------------------------+
|i3 : f = x^3;                             |
+------------------------------------------+
|i4 : f - (f%S)                            |
|                                          |
|      3    2        2    3                |
|o4 = x  + x y + 2x*y  + y                 |
|                                          |
|o4 : R                                    |
+------------------------------------------+
|i5 : gs = groebnerSubductionQuotient(f, S)|
|                                          |
|      3                                   |
|o5 = p  - 2p p  + p                       |
|      0     0 1    2                      |
|                                          |
|o5 : QQ[p ..p ]                           |
|         0   2                            |
+------------------------------------------+
|i6 : S#"presentationMap" gs               |
|                                          |
|      3    2        2    3                |
|o6 = x  + x y + 2x*y  + y                 |
|                                          |
|o6 : R                                    |
+------------------------------------------+

See also
========

  * Subring -- The type of all subrings
  * subring -- Constructs a subring of a polynomial ring.
  * RingElement % Subring -- Remainder modulo a
    subring
  * RingElement // Subring -- Subduction
    quotient with respect to a subring
  * sagbi -- Compute a subalgebra basis (sagbi basis)
  * groebnerMembershipTest -- Extrinsic method
    for subring membership

Ways to use groebnerSubductionQuotient:
=======================================

  * "groebnerSubductionQuotient(RingElement,Subring)"

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

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

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

The source of this document is in SubalgebraBases/documentation.m2:1122:0.

intersect(Subring,Subring) -- Intersection of subrings
******************************************************

  * Function: intersect (Macaulay2Doc),
  * Usage:
        result = intersect(S1, S2)
  * Inputs:
      * S1, a subring,
      * S2, a subring,
  * Optional inputs (Macaulay2Doc),:
      * Strategy, => a string (Macaulay2Doc),
        default value "Master", the update strategy at
        the beginning of each loop: "DegreeByDegree", "Incremental", and
        "Master". The strategy "Master" is a hybrid method that combines the
        other two; starting with "DegreeByDegree" for low degrees and switching
        to "Incremental".
      * SubductionMethod, => a string (Macaulay2Doc),
        default value "Top", the method used for
        subduction. See SubductionMethod, can be either
        "Top" or "Engine".
      * SAGBILimitType, => a string (Macaulay2Doc),
        default value "Fixed", Either "Fixed" or
        "Function". Determines the stopping criterion for the subalgebra bases
        computation. If "Fixed" then the Limit,
        is used, otherwise, if "Function" is selected, then the maximum
        degree of the input generators is used as the degree limit.
      * Limit, => an integer (Macaulay2Doc),
        default value 20, a degree limit for the binomial
        S-pairs that are computed internally.
      * PrintLevel, => an integer (Macaulay2Doc),
        default value 0, which determines how much information is printed about
        the progress of the computation. Larger positive values of
        PrintLevel, result in more output.
      * CheckFullIntersection, => a Boolean value (Macaulay2Doc),
        default value true, which determines if
        isFullIntersection, is run on the output
        IntersectedSubring.
      * Compute, => a Boolean value (Macaulay2Doc),
        default value true, which determines if the
        check to see if the computed generators form a subalgebra basis of the
        ring they generate is performed.
  * Outputs:
      * result, an intersected subring,

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

Computes the intersection of input subrings of the same ambient ring.

+---------------------------------------------------------------------+
|i1 : R = QQ[x,y];                                                    |
+---------------------------------------------------------------------+
|i2 : I = ideal(x^3 + x*y^2 + y^3);                                   |
|                                                                     |
|o2 : Ideal of R                                                      |
+---------------------------------------------------------------------+
|i3 : Q = R/I;                                                        |
+---------------------------------------------------------------------+
|i4 : S1 = subring {x^2, x*y};                                        |
+---------------------------------------------------------------------+
|i5 : S2 = subring {x, y^2};                                          |
+---------------------------------------------------------------------+
|i6 : gens intersect(S1, S2, Limit=>5)                                |
|-- Warning! Result is not a full intersection.  Try increasing Limit.|
|                                                                     |
|o6 = | x2 x2y2+xy3 |                                                 |
|                                                                     |
|             1      2                                                |
|o6 : Matrix Q  <-- Q                                                 |
+---------------------------------------------------------------------+
|i7 : S = intersect(S1, S2);                                          |
+---------------------------------------------------------------------+
|i8 : gens S                                                          |
|                                                                     |
|o8 = | x2 x2y2+xy3 y4 xy3 y6 xy5 |                                   |
|                                                                     |
|             1      6                                                |
|o8 : Matrix Q  <-- Q                                                 |
+---------------------------------------------------------------------+
|i9 : isFullIntersection S                                            |
|                                                                     |
|o9 = true                                                            |
+---------------------------------------------------------------------+
|i10 : isSAGBI S                                                      |
|                                                                     |
|o10 = true                                                           |
+---------------------------------------------------------------------+

The generators of the resulting IntersectedSubring,
form a partial subalgebra basis for the computed intersection. When
CheckFullIntersection, is true, the function
automatically checks if the generators of the resulting
IntersectedSubring, generate the intersection of the given
subrings. The generators of an instance of IntersectedSubring,
lie in both input algebras. However, if the function cannot
guarantee that the generators of the resulting IntersectedSubring,
generate the full intersection then a warning is given.

The function works by creating a composite subring $S$ from the input algebras
and attempts to compute a subalgebra basis for $S$. If a subalgebra basis $G$
for $S$ is found, then a subset of $G$ forms a subalgebra basis of the
intersection of the input algebras. Whenever this happens, the output is
guaranteed to be the full intersection of the input algebras and, furthermore,
form a subalgebra basis for the intersection. The function
isFullIntersection, checks whether this is the case, i.e.,
whether a finite subalgebra basis for $S$ was found. If the function
isFullIntersection, returns false then there are a few
different possibilities: First, the composite subring $S$ may have a finite
subalgebra basis that could be found by either setting the option
SAGBILimitType, to its default value of Fixed or by using a
higher Limit, option. Second, $S$ may not
have a finite subalgebra basis but the intersection does have a finite
subalgebra basis. In this case, the output may be a generating set for the full
intersection, but cannot be verified by the algorithm. Third, the intersection
of the input algebras may not have a finite subalgebra basis, and so the
composite subring does not have a finite subalgebra basis. In this case case,
the computed generators may be a generating set (but not a subalgebra basis)
for the intersection but the algorithm cannot guarantee it.

This function can also be run on a sequence containing both Subring,
and IntersectedSubring, types. When
CheckFullIntersection, is true, all intermediate
intersections are checked for completeness.

+------------------------------+
|i11 : R = QQ[x,y];            |
+------------------------------+
|i12 : S1 = subring{x^2,y^3};  |
+------------------------------+
|i13 : S2 = subring{x,y^2};    |
+------------------------------+
|i14 : S3 = subring{x^4,y};    |
+------------------------------+
|i15 : gens intersect(S1,S2,S3)|
|                              |
|o15 = | x4 y6 |               |
|                              |
|              1      2        |
|o15 : Matrix R  <-- R         |
+------------------------------+

See also
========

  * Subring -- The type of all subrings
  * IntersectedSubring -- The type of all subrings
    arising from intersection
  * isFullIntersection -- check correctness of
    intersection computation
  * originalSubringGens -- generators of the
    original subrings
  * isSAGBI -- Check if the generators are a subalgebra basis
  * Subduction computation limit -- Bound
    for subalgebra basis computation

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

  * intersect(Subring,Subring), --
    Intersection of subrings
-------------------------------------------------------------------------------

The source of this document is in SubalgebraBases/documentation.m2:1436:0.

IntersectedSubring -- The type of all subrings arising from intersection
************************************************************************

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

IntersectedSubring is a type of Subring, produced by
intersecting two subrings using the function intersect (Macaulay2Doc).
The function intersect (Macaulay2Doc),
is the constructor for IntersectedSubring. Applying
the function isFullIntersection, to an instance $S$
of IntersectedSubring checks whether the generators of $S$ are guaranteed to
generate the intersection of the original subrings.

+-------------------------------------------------------------+
|i1 : R = QQ[x,y];                                            |
+-------------------------------------------------------------+
|i2 : S1 = subring{x^3,y};                                    |
+-------------------------------------------------------------+
|i3 : S2 = subring{x^2,y^2};                                  |
+-------------------------------------------------------------+
|i4 : S = intersect(S1,S2)                                    |
|                                                             |
|o4 = QQ[p_0..p_1], subring of R                              |
|                                                             |
|o4 : IntersectedSubring                                      |
+-------------------------------------------------------------+
|i5 : S#"originalSubrings"                                    |
|                                                             |
|o5 = {QQ[p_0..p_1], subring of R, QQ[p_0..p_1], subring of R}|
|                                                             |
|o5 : List                                                    |
+-------------------------------------------------------------+

The originalSubrings field lists the two subrings which were used to generate
the intersection.

See also
========

  * Subring -- The type of all subrings
  * intersect(Subring,Subring), --
    Intersection of subrings
  * isFullIntersection -- check correctness of
    intersection computation
  * originalSubringGens -- generators of the
    original subrings

Functions and methods returning an intersected subring:
=======================================================

  * intersect(Subring,Subring), --
    Intersection of subrings

Methods that use an intersected subring:
========================================

  * "isFullIntersection(IntersectedSubring)" -- see isFullIntersection,
    -- check correctness of intersection computation
  * "originalSubringGens(IntersectedSubring)" -- see originalSubringGens,
    -- generators of the original subrings

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

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

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

The source of this document is in SubalgebraBases/documentation.m2:1468:0.

isFullIntersection -- check correctness of intersection computation
*******************************************************************

  * Usage:
        result = isFullIntersection(S)
  * Inputs:
      * S, an intersected subring,
  * Outputs:
      * result, a Boolean value (Macaulay2Doc), is true to
        indicate that the generators of $S$ generate the intersection of the
        original subrings

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

Checks if the algorithm for computing the intersection of two subrings in the
function intersect (Macaulay2Doc), produced a subalgebra basis
for the intersection.

+----------------------------------+
|i1 : R = QQ[x,y];                 |
+----------------------------------+
|i2 : I = ideal(x^3 + x*y^2 + y^3);|
|                                  |
|o2 : Ideal of R                   |
+----------------------------------+
|i3 : Q = R/I;                     |
+----------------------------------+
|i4 : S1 = subring {x^2, x*y};     |
+----------------------------------+
|i5 : S2 = subring {x, y^2};       |
+----------------------------------+
|i6 : S = intersect(S1, S2);       |
+----------------------------------+
|i7 : isFullIntersection S         |
|                                  |
|o7 = true                         |
+----------------------------------+

This test is one-sided: if the function isFullIntersection,
returns false, then the generators of the given subring may
still generate the intersection as a subalgebra basis.

+-------------------------------------------------------------------------+
|i8 : R = QQ[x,y];                                                        |
+-------------------------------------------------------------------------+
|i9 : S1 = subring {x^3, x^2*y};                                          |
+-------------------------------------------------------------------------+
|i10 : S2 = subring {x^4, y};                                             |
+-------------------------------------------------------------------------+
|i11 : S = intersect(S1, S2, Limit => 15, CheckFullIntersection => false);|
+-------------------------------------------------------------------------+
|i12 : gens S                                                             |
|                                                                         |
|o12 = | x4y2 x8y x12 |                                                   |
|                                                                         |
|              1      3                                                   |
|o12 : Matrix R  <-- R                                                    |
+-------------------------------------------------------------------------+
|i13 : isFullIntersection S                                               |
|                                                                         |
|o13 = false                                                              |
+-------------------------------------------------------------------------+
|i14 : isSAGBI S                                                          |
|                                                                         |
|o14 = true                                                               |
+-------------------------------------------------------------------------+

If the function isFullIntersection returns false then, there are a few
different possibilities: First, the composite subring $S$ may have a finite
subalgebra basis that could be found by setting the option
SAGBILimitType, to its default value of Fixed or by using a
higher Limit, option in intersect (Macaulay2Doc).
Second, $S$ may not have a finite subalgebra basis
but the intersection does have a finite subalgebra basis. In this case, the
output may be a generating set for the full intersection, but cannot be
verified by the algorithm. Third, the intersection of the input algebras may
not have a finite subalgebra basis, and so the composite subring does not have
a finite subalgebra basis. In this case, the computed generators may be a
generating set (but not a subalgebra basis) for the intersection but the
algorithm cannot guarantee it.

See also
========

  * intersect(Subring,Subring), --
    Intersection of subrings
  * Subring -- The type of all subrings
  * IntersectedSubring -- The type of all subrings
    arising from intersection
  * Subduction computation limit -- Bound
    for subalgebra basis computation
  * SAGBILimitType -- Flag for calculating degree limit
    in intersections

Ways to use isFullIntersection:
===============================

  * "isFullIntersection(IntersectedSubring)"

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

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

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

The source of this document is in SubalgebraBases/documentation.m2:1535:0.

isSAGBI -- Check if the generators are a subalgebra basis
*********************************************************

  * Usage:
        result = isSAGBI S
        result = isSAGBI SB
        result = isSAGBI M
        result = isSAGBI L
  * Inputs:
      * S, a subring,
      * SB, a SAGBIBasis,
      * M, a matrix (Macaulay2Doc),
      * L, a list (Macaulay2Doc),
  * Outputs:
      * result, a Boolean value (Macaulay2Doc), if true, then
        the generators or subalgebra generators form a subalgebra basis.

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

Checks whether the generators of a subring, or the subalgebra
generators of a SAGBIBasis, form a subalgebra basis. If
isSAGBI is supplied a matrix (Macaulay2Doc), or a list (Macaulay2Doc),
A, then the command isSAGBI A is equivalent to isSAGBI
subring, A. For further details of their respective uses see
isSAGBI(Subring), and isSAGBI(SAGBIBasis).

The result of isSagbi is stored in the cache of a subring, or
the sagbiStatus of a SAGBIBasis. If isSagbi is called again,
then the result is looked up, unless the option Recompute, is
set to true.

+---------------------------------------------------------------+
|i1 : R = QQ[x,y,z];                                            |
+---------------------------------------------------------------+
|i2 : S = subring {x+y+z,x*y+x*z+y*z, x*y*z, (x-y)*(x-z)*(y-z)};|
+---------------------------------------------------------------+
|i3 : isSAGBI S                                                 |
|                                                               |
|o3 = false                                                     |
+---------------------------------------------------------------+
|i4 : isSAGBI sagbi(S, Limit => 5)                              |
|                                                               |
|o4 = false                                                     |
+---------------------------------------------------------------+
|i5 : S' = subring {x+y,x*y,x*y^2,x*y^4-y};                     |
+---------------------------------------------------------------+
|i6 : isSAGBI S'                                                |
|                                                               |
|o6 = false                                                     |
+---------------------------------------------------------------+
|i7 : isSAGBI sagbi(S', Limit => 10)                            |
|                                                               |
|o7 = true                                                      |
+---------------------------------------------------------------+

If isSAGBI is supplied a SAGBIBasis, then the generators of
its subring can be checked for being a subalgebra basis by setting
UseSubringGens, to true. If isSAGBI is supplied a
subring, then the generators of a partial subalgebra basis can be
checked for being a subalgebra basis by setting UseSubringGens,
to false.

Optional inputs for specific uses (see isSAGBI(Subring),
and isSAGBI(SAGBIBasis))
include the following: Compute, Recompute,
Subduction strategies, SubductionMethod,
see PrintLevel, RenewOptions,
see UseSubringGens, and
ModifySAGBIBasis.

See also
========

  * isSAGBI(Subring) -- Check if the generators
    are a subalgebra basis
  * isSAGBI(SAGBIBasis) -- Check if the
    generators are a subalgebra basis
  * SAGBIBasis -- The type of all subalgebra bases
  * generators(SAGBIBasis) -- Returns
    generators of a SAGBIBasis computation object
  * ambient(SAGBIBasis) -- The ambient ring of
    a SAGBIBasis computation object
  * sagbi -- Compute a subalgebra basis (sagbi basis)

Ways to use isSAGBI:
====================

  * "isSAGBI(List)"
  * "isSAGBI(Matrix)"
  * isSAGBI(SAGBIBasis) -- Check if the
    generators are a subalgebra basis
  * isSAGBI(Subring) -- Check if the generators
    are a subalgebra basis

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

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

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

The source of this document is in SubalgebraBases/documentation.m2:779:0.

isSAGBI(SAGBIBasis) -- Check if the generators are a subalgebra basis
*********************************************************************

  * Function: isSAGBI,
  * Usage:
        result = isSAGBI SB
  * Inputs:
      * SB, a SAGBIBasis,
  * Optional inputs (Macaulay2Doc),:
      * Compute, => a Boolean value (Macaulay2Doc),
        default value true, a flag indicating whether
        to perform computation.
      * Recompute, => a Boolean value (Macaulay2Doc),
        default value false, if true then sagbiStatus
        is ignored and a computation is performed to verify if the subalgebra
        generators are a subalgebra basis.
      * Strategy, => a string (Macaulay2Doc),
        default value "Master", the update strategy used
        for updating the SAGBIBasis: "DegreeByDegree", "Incremental", and
        "Master". The strategy "Master" is a hybrid method that combines the
        other two; starting with "DegreeByDegree" for low degrees and switching
        to "Incremental".
      * SubductionMethod, => a string (Macaulay2Doc),
        default value "Top", the method used for
        subduction either: "Top" or "Engine".
      * PrintLevel, => an integer (Macaulay2Doc),
        default value 0, When this is greater than zero, information is printed
        about the progress of the computation.
      * RenewOptions, => a Boolean value (Macaulay2Doc),
        default value false, if true then the
        computation uses the options specified, otherwise it will use the
        previously selected options (except for the following, which may always
        be specified: PrintLevel, Limit,
        see Recompute, and
        RenewOptions).
      * UseSubringGens, => a Boolean value (Macaulay2Doc),
        default value false, a flag indicating whether
        to use the generators of the subring of the partial subalgebra basis.
        If false then the method uses the subalgebra generators of the partial
        subalgebra basis.
      * ModifySAGBIBasis, => a Boolean value (Macaulay2Doc),
        default value true, a flag indicating whether
        to replace the partial subalgebra basis cached in the subring.
  * Outputs:
      * result, a Boolean value (Macaulay2Doc),

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

Checks whether the subalgebra generators of a SAGBIBasis,
$SB$ form a subalgebra basis. The result of the computation is stored in the
sagbiStatus of $SB$. Subsequent calls of isSAGBI on $SB$ will look up the
result of the sagbiStatus unless the option Recompute, is set
to true. If the option Compute, is set to false, then isSAGBI
attempts to find a previously cached result. If isSAGBI cannot determine a
result without computation and the option Compute, is set to
false, then isSAGBI returns null.

If the subalgebra generators of $SB$ form a subalgebra basis, then the partial
subalgebra basis is updated, unless ModifySAGBIBasis,
is set to false. If the option UseSubringGens, is set to
true, then the generators of the subring of $SB$ are used instead of the
subalgebra generators of the subring.

+---------------------------------------------------------------+
|i1 : R = QQ[x,y,z];                                            |
+---------------------------------------------------------------+
|i2 : S = subring {x+y+z,x*y+x*z+y*z, x*y*z, (x-y)*(x-z)*(y-z)};|
+---------------------------------------------------------------+
|i3 : isSAGBI S                                                 |
|                                                               |
|o3 = false                                                     |
+---------------------------------------------------------------+
|i4 : isSAGBI sagbi(S, Limit => 5)                              |
|                                                               |
|o4 = false                                                     |
+---------------------------------------------------------------+
|i5 : S' = subring {x+y,x*y,x*y^2,x*y^7-y};                     |
+---------------------------------------------------------------+
|i6 : isSAGBI S'                                                |
|                                                               |
|o6 = false                                                     |
+---------------------------------------------------------------+
|i7 : isSAGBI sagbi(S', Limit => 5)                             |
|                                                               |
|o7 = false                                                     |
+---------------------------------------------------------------+
|i8 : isSAGBI sagbi(S', Limit => 10)                            |
|                                                               |
|o8 = true                                                      |
+---------------------------------------------------------------+

The options Subduction strategies,
SubductionMethod, PrintLevel, and
RenewOptions, are only used when performing a subalgebra bases
computation.

See also
========

  * isSAGBI -- Check if the generators are a subalgebra basis
  * isSAGBI(Subring) -- Check if the generators
    are a subalgebra basis
  * SAGBIBasis -- The type of all subalgebra bases
  * generators(SAGBIBasis) -- Returns
    generators of a SAGBIBasis computation object
  * ambient(SAGBIBasis) -- The ambient ring of
    a SAGBIBasis computation object
  * sagbiStatus(SAGBIBasis) -- checks if the subalgebra
    bases computation is done
  * sagbi -- Compute a subalgebra basis (sagbi basis)
  * Compute -- Flag for performing computations while checking
    the completeness of a subalgebra basis
  * Recompute -- Flag for restarting a sagbi or isSAGBI
    computation
  * Subduction strategies -- Update procedure for
    the Sagbi algorithm
  * SubductionMethod -- Subduction method for the
    Sagbi algorithm
  * PrintLevel -- Levels of information displayed during
    Sagbi algorithm
  * RenewOptions -- Flag for reselecting the options for a
    subalgebra bases computation
  * UseSubringGens -- Flag for using the subring
    generators when checking a subalgebra basis
  * ModifySAGBIBasis -- Flag for allowing the cached
    computation object to be modified

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

  * isSAGBI(SAGBIBasis) -- Check if the
    generators are a subalgebra basis
-------------------------------------------------------------------------------

The source of this document is in SubalgebraBases/documentation.m2:956:0.

isSAGBI(Subring) -- Check if the generators are a subalgebra basis
******************************************************************

  * Function: isSAGBI,
  * Usage:
        result = isSAGBI S
  * Inputs:
      * S, a subring,
  * Optional inputs (Macaulay2Doc),:
      * Compute, => a Boolean value (Macaulay2Doc),
        default value true, a flag indicating whether
        to perform computation.
      * Recompute, => a Boolean value (Macaulay2Doc),
        default value false, if true then cached
        results are ignored and a computation is performed to verify if the
        generators are a subalgebra basis.
      * Strategy, => a string (Macaulay2Doc),
        default value "Master", the update strategy used
        for updating the SAGBIBasis: "DegreeByDegree", "Incremental", and
        "Master". The strategy "Master" is a hybrid method that combines the
        other two; starting with "DegreeByDegree" for low degrees and switching
        to "Incremental".
      * SubductionMethod, => a string (Macaulay2Doc),
        default value "Top", the method used for
        subduction either: "Top" or "Engine".
      * PrintLevel, => an integer (Macaulay2Doc),
        default value 0, When this is greater than zero, information is printed
        about the progress of the computation.
      * RenewOptions, => a Boolean value (Macaulay2Doc),
        default value false, if true then the
        computation will use the options specified, otherwise it will use the
        previously selected options (except for the following, which may always
        be specified: PrintLevel, Limit,
        see Recompute, and
        RenewOptions)
      * UseSubringGens, => a Boolean value (Macaulay2Doc),
        default value true, a flag indicating whether
        to use the generators of the subring. If false, then the method uses
        the subalgebra generators of the partial subalgebra basis.
      * ModifySAGBIBasis, => a Boolean value (Macaulay2Doc),
        default value true, a flag indicating whether
        to replace the partial subalgebra basis cached in the subring.
  * Outputs:
      * result, a Boolean value (Macaulay2Doc), if true, then
        the generators or subalgebra generators form a subalgebra basis.

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

Checks whether the generators of a subring, $S$ form a
subalgebra basis. The result of the computation is stored in the cache of the
ring. Subsequent calls to isSAGBI on $S$ with the same options will look up the
cached result unless the option Recompute, is set to true. If
the option Compute, is set to false then isSAGBI attempts to
find a previously cached result. If isSAGBI cannot determine a result without
computation and the option Compute, is set to false, then
isSAGBI returns null.

If the generators of $S$ form a subalgebra basis, then the subalgebra
generators of the cached partial subalgebra basis are updated to match the ring
generators, unless the option ModifySAGBIBasis, is set
to false. If the option UseSubringGens, is set to false,
then the generators of a partial subalgebra basis are used instead of the
generators of the subring.

+---------------------------------------------------------------+
|i1 : R = QQ[x,y,z];                                            |
+---------------------------------------------------------------+
|i2 : S = subring {x+y+z,x*y+x*z+y*z, x*y*z, (x-y)*(x-z)*(y-z)};|
+---------------------------------------------------------------+
|i3 : isSAGBI S                                                 |
|                                                               |
|o3 = false                                                     |
+---------------------------------------------------------------+
|i4 : S' = subring {x+y+z,x*y+x*z+y*z, x*y*z};                  |
+---------------------------------------------------------------+
|i5 : isSAGBI S'                                                |
|                                                               |
|o5 = true                                                      |
+---------------------------------------------------------------+

The options Subduction strategies,
SubductionMethod, PrintLevel, and
RenewOptions, are only used when performing a subalgebra bases
computation.

See also
========

  * isSAGBI -- Check if the generators are a subalgebra basis
  * isSAGBI(SAGBIBasis) -- Check if the
    generators are a subalgebra basis
  * Subring -- The type of all subrings
  * sagbi -- Compute a subalgebra basis (sagbi basis)
  * Compute -- Flag for performing computations while checking
    the completeness of a subalgebra basis
  * Recompute -- Flag for restarting a sagbi or isSAGBI
    computation
  * Subduction strategies -- Update procedure for
    the Sagbi algorithm
  * SubductionMethod -- Subduction method for the
    Sagbi algorithm
  * PrintLevel -- Levels of information displayed during
    Sagbi algorithm
  * RenewOptions -- Flag for reselecting the options for a
    subalgebra bases computation
  * UseSubringGens -- Flag for using the subring
    generators when checking a subalgebra basis
  * ModifySAGBIBasis -- Flag for allowing the cached
    computation object to be modified

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

  * isSAGBI(Subring) -- Check if the generators
    are a subalgebra basis
-------------------------------------------------------------------------------

The source of this document is in SubalgebraBases/documentation.m2:864:0.

ModifySAGBIBasis -- Flag for allowing the cached computation object to be modified
**********************************************************************************

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

When isSAGBI, is supplied a subring, $S$, then
this option determines whether the cached instance of a SAGBIBasis,
may be replaced.

+------------------------------------------+
|i1 : R = QQ[x,y];                         |
+------------------------------------------+
|i2 : S = subring {x^2, y^3};              |
+------------------------------------------+
|i3 : SB = sagbi(S, Limit => 2);           |
+------------------------------------------+
|i4 : S.cache#SAGBIBasis === SB            |
|                                          |
|o4 = true                                 |
+------------------------------------------+
|i5 : isSAGBI(S, ModifySAGBIBasis => false)|
|                                          |
|o5 = true                                 |
+------------------------------------------+
|i6 : S.cache#SAGBIBasis === SB            |
|                                          |
|o6 = true                                 |
+------------------------------------------+
|i7 : isSAGBI(S, ModifySAGBIBasis => true) |
|                                          |
|o7 = true                                 |
+------------------------------------------+
|i8 : S.cache#SAGBIBasis === SB            |
|                                          |
|o8 = false                                |
+------------------------------------------+

See also
========

  * isSAGBI -- Check if the generators are a subalgebra basis

Functions with optional argument named ModifySAGBIBasis:
========================================================

  * "isSAGBI(List,ModifySAGBIBasis=>...)"
  * "isSAGBI(Matrix,ModifySAGBIBasis=>...)"
  * "isSAGBI(SAGBIBasis,ModifySAGBIBasis=>...)"
  * "isSAGBI(Subring,ModifySAGBIBasis=>...)"

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

The object ModifySAGBIBasis, is a symbol (Macaulay2Doc).

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

The source of this document is in SubalgebraBases/documentation.m2:1046:0.

net(SAGBIBasis) -- Short summary of a subalgebra basis computation object
*************************************************************************

  * Function: net (Macaulay2Doc),
  * Usage:
        net S
  * Inputs:
      * S, a SAGBIBasis,
  * Outputs:
      * a net (Macaulay2Doc), obtained by formatting S for printing.

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

Displays the number of subalgebra generators of a SAGBIBasis,
along with the degree limit.

+-----------------------------------------------------------------+
|i1 : R = QQ[x,y];                                                |
+-----------------------------------------------------------------+
|i2 : S = subring{x^2,x*y^2,y^4};                                 |
+-----------------------------------------------------------------+
|i3 : sagbi S                                                     |
|                                                                 |
|o3 = SAGBIBasis Computation Object with 3 generators, Limit = 20.|
|                                                                 |
|o3 : SAGBIBasis                                                  |
+-----------------------------------------------------------------+

See also
========

  * SAGBIBasis -- The type of all subalgebra bases
  * generators(SAGBIBasis) -- Returns
    generators of a SAGBIBasis computation object
  * ambient(SAGBIBasis) -- The ambient ring of
    a SAGBIBasis computation object
  * ring(SAGBIBasis) -- The lifted ring of a
    SAGBIBasis computation object
  * net(Subring) -- Short summary of a subring
  * status(SAGBIBasis) -- status of the
    subalgebra bases computation
  * sagbiLimit -- The current limit of the subalgebra bases
    computation
  * sagbi -- Compute a subalgebra basis (sagbi basis)

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

  * net(SAGBIBasis) -- Short summary of a
    subalgebra basis computation object
-------------------------------------------------------------------------------

The source of this document is in SubalgebraBases/documentation.m2:2003:0.

net(Subring) -- Short summary of a subring
******************************************

  * Function: net (Macaulay2Doc),
  * Usage:
        net S
  * Inputs:
      * S, a subring,
  * Outputs:
      * a net (Macaulay2Doc), obtained by formatting S for printing.

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

Displays the presentation and ambient rings of a Subring.

+-------------------------------+
|i1 : R = QQ[x,y];              |
+-------------------------------+
|i2 : S = subring{x^2,x*y^2,y^4}|
|                               |
|o2 = QQ[p_0..p_2], subring of R|
|                               |
|o2 : Subring                   |
+-------------------------------+

See also
========

  * Subring -- The type of all subrings
  * subring -- Constructs a subring of a polynomial ring.
  * generators(Subring) -- A generating set of
    a subring
  * ambient(Subring) -- The ambient ring of a
    subring
  * numgens(Subring) -- The number of generators
    of a subring
  * net(SAGBIBasis) -- Short summary of a
    subalgebra basis computation object
  * flattenedRing(Subring) -- The flattened ring of a
    subring or sagbiBasis

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

  * net(Subring) -- Short summary of a subring
-------------------------------------------------------------------------------

The source of this document is in SubalgebraBases/documentation.m2:1808:0.

numgens(SAGBIBasis) -- The number of generators of a SAGBIBasis
***************************************************************

  * Function: numgens (Macaulay2Doc),
  * Usage:
        result = numgens SB
  * Inputs:
      * SB, a SAGBIBasis,
  * Outputs:
      * result, an integer (Macaulay2Doc), the number of subalgebra
        generators of SB

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

Returns the number of subalgebra generators of a SAGBIBasis.

+-------------------------------------------+
|i1 : R = QQ[x,y,z];                        |
+-------------------------------------------+
|i2 : S = subring({x^2, y^2, z^2, x^2+y^2});|
+-------------------------------------------+
|i3 : SB = sagbi S;                         |
+-------------------------------------------+
|i4 : numgens SB                            |
|                                           |
|o4 = 3                                     |
+-------------------------------------------+

See also
========

  * Subring -- The type of all subrings
  * subring -- Constructs a subring of a polynomial ring.
  * SAGBIBasis -- The type of all subalgebra bases
  * sagbiBasis -- Constructs a computation object from a
    subring.
  * generators(SAGBIBasis) -- Returns
    generators of a SAGBIBasis computation object
  * ambient(SAGBIBasis) -- The ambient ring of
    a SAGBIBasis computation object
  * numgens(SAGBIBasis) -- The number of
    generators of a SAGBIBasis
  * net(Subring) -- Short summary of a subring
  * flattenedRing(SAGBIBasis) -- The flattened ring of a
    subring or sagbiBasis

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

  * numgens(SAGBIBasis) -- The number of
    generators of a SAGBIBasis
-------------------------------------------------------------------------------

The source of this document is in SubalgebraBases/documentation.m2:1780:0.

numgens(Subring) -- The number of generators of a subring
*********************************************************

  * Function: numgens (Macaulay2Doc),
  * Usage:
        result = numgens S
  * Inputs:
      * S, a subring,
  * Outputs:
      * result, an integer (Macaulay2Doc), the number of generators
        of S

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

Returns the number of generators of a Subring.

+-------------------------------------------+
|i1 : R = QQ[x,y,z];                        |
+-------------------------------------------+
|i2 : S = subring({x^2, y^2, z^2, x^2+y^2});|
+-------------------------------------------+
|i3 : numgens S                             |
|                                           |
|o3 = 4                                     |
+-------------------------------------------+

See also
========

  * Subring -- The type of all subrings
  * subring -- Constructs a subring of a polynomial ring.
  * generators(Subring) -- A generating set of
    a subring
  * ambient(Subring) -- The ambient ring of a
    subring
  * numgens(SAGBIBasis) -- The number of
    generators of a SAGBIBasis
  * net(Subring) -- Short summary of a subring
  * flattenedRing(Subring) -- The flattened ring of a
    subring or sagbiBasis

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

  * numgens(Subring) -- The number of generators
    of a subring
-------------------------------------------------------------------------------

The source of this document is in SubalgebraBases/documentation.m2:1748:0.

originalSubringGens -- generators of the original subrings
**********************************************************

  * Usage:
        result = originalSubringGens(S)
  * Inputs:
      * S, an intersected subring,
  * Outputs:
      * result, a list (Macaulay2Doc), of the generators of the
        original subrings used in the creation of $S$

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

Returns a list of two one-row matrices of the generators of the original
subrings whose intersection (via the function intersect (Macaulay2Doc))
is $S$.

+----------------------------------+
|i1 : R = QQ[x,y];                 |
+----------------------------------+
|i2 : I = ideal(x^3 + x*y^2 + y^3);|
|                                  |
|o2 : Ideal of R                   |
+----------------------------------+
|i3 : Q = R/I;                     |
+----------------------------------+
|i4 : S1 = subring {x^2, x*y};     |
+----------------------------------+
|i5 : S2 = subring {x, y^2};       |
+----------------------------------+
|i6 : S = intersect(S1, S2);       |
+----------------------------------+
|i7 : originalSubringGens S        |
|                                  |
|o7 = {| x2 xy |, | x y2 |}        |
|                                  |
|o7 : List                         |
+----------------------------------+

See also
========

  * intersect(Subring,Subring), --
    Intersection of subrings
  * Subring -- The type of all subrings
  * IntersectedSubring -- The type of all subrings
    arising from intersection

Ways to use originalSubringGens:
================================

  * "originalSubringGens(IntersectedSubring)"

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

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

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

The source of this document is in SubalgebraBases/documentation.m2:1567:0.

presentationRing -- returns the presentation ring of a subring
**************************************************************

  * Usage:
        presRing = presentationRing S
  * Inputs:
      * S, a subring,
  * Outputs:
      * presRing, a polynomial ring (Macaulay2Doc), the
        presentation ring of S

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

Given a subring, $S$ of a quotient ring (Macaulay2Doc),
$Q$, the presentationRing $P$ is a polynomial ring
with the same coefficient ring as Q and with one variable for each generator of
S. There is a natural map from $P$ to $S$ that sends each variable to its
corresponding generator. Elements of the presentationRing represent polynomial
combinations of generators. Evaluating a polynomial combination of generators
is equal to applying this map. Therefore, $S$ is naturally isomorphic to the
quotient of $P$ by the kernel of the this map.

The presentationRing naturally arises when using RingElement // Subring,
which takes an element of a subring,
and expresses it as a polynomial combination of its generators.

Subrings include the field presentationMap, which provides a map from the
presentationRing to the ambient(Subring), ring.

+-----------------------------------+
|i1 : R = ZZ/2[x,y];                |
+-----------------------------------+
|i2 : Q = R / ideal(x + y^5);       |
+-----------------------------------+
|i3 : S = subring {x+y, x*y, x*y^2};|
+-----------------------------------+
|i4 : f = x^2*y^3 + x^4 + y^4;      |
+-----------------------------------+
|i5 : f % S                         |
|                                   |
|o5 = 0                             |
|                                   |
|o5 : Q                             |
+-----------------------------------+
|i6 : g = f // S                    |
|                                   |
|      4                            |
|o6 = p  + p p                      |
|      0    1 2                     |
|                                   |
|     ZZ                            |
|o6 : --[p ..p ]                    |
|      2  0   2                     |
+-----------------------------------+
|i7 : S#"presentationMap" g == f    |
|                                   |
|o7 = true                          |
+-----------------------------------+

See also
========

  * Subring -- The type of all subrings
  * RingElement // Subring -- Subduction
    quotient with respect to a subring
  * groebnerSubductionQuotient -- Extrinsic
    method for subduction quotients
  * ambient(Subring) -- The ambient ring of a
    subring
  * flattenedRing(Subring) -- The flattened ring of a
    subring or sagbiBasis

Ways to use presentationRing:
=============================

  * "presentationRing(Subring)"

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

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

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

The source of this document is in SubalgebraBases/documentation.m2:2474:0.

PrintLevel -- Levels of information displayed during Sagbi algorithm
********************************************************************

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

PrintLevel is an optional input to sagbi, and the methods that
call it to control the amount of internal computational data to be displayed
for debugging and informational purposes. Higher values for PrintLevel result
in more verbose output (especially Levels 5 and 6).

  * Level 0: No additional output
  * Level 1+: some basic information each computation loop (but no
    polynomials): computation degree, number of S-pairs, number of new
    generators, termination conditions.
  * Level 2+: basic polynomials: S-pairs and new subalgebra generators.
  * Level 3+: extra polynomials: reduction ideal generators, zeroGens, current
    subalgebra generators
  * Level 4+: the input and output of each subduction
  * Level 5+: the processPending data
  * Level 6+: the intermediate steps for top-level subduction

See also
========

  * sagbi -- Compute a subalgebra basis (sagbi basis)
  * AutoSubduce -- Flag for autosubduction before the sagbi
    algorithm
  * ReduceNewGenerators -- Flag for reducing new
    generators in Sagbi algorithm
  * StorePending -- Flag for storing the pending list to
    the result of the Sagbi algorithm
  * SubductionMethod -- Subduction method for the
    Sagbi algorithm
  * AutoSubduceOnPartialCompletion, --
    Subduct subalgebra generators at the end of the sagbi algorithm
  * PrintLevel -- Levels of information displayed during
    Sagbi algorithm
  * RenewOptions -- Flag for reselecting the options for a
    subalgebra bases computation
  * forceSB -- declare the generators to be a complete
    subalgebra basis
  * isSAGBI -- Check if the generators are a subalgebra basis
  * intersect(Subring,Subring), --
    Intersection of subrings
  * sagbi -- Compute a subalgebra basis (sagbi basis)
  * sagbiBasis -- Constructs a computation object from a
    subring.
  * subalgebraBasis -- Compute subalgebra basis
    generators
  * subduction -- Subduction against a set elements
  * Subduction strategies -- Update procedure for
    the Sagbi algorithm

Functions with optional argument named PrintLevel:
==================================================

  * "forceSB(SAGBIBasis,PrintLevel=>...)"
  * "forceSB(Subring,PrintLevel=>...)"
  * "intersect(Subring,Subring,PrintLevel=>...)"
  * "isSAGBI(List,PrintLevel=>...)"
  * "isSAGBI(Matrix,PrintLevel=>...)"
  * "isSAGBI(SAGBIBasis,PrintLevel=>...)"
  * "isSAGBI(Subring,PrintLevel=>...)"
  * "sagbi(...,PrintLevel=>...)"
  * "sagbiBasis(...,PrintLevel=>...)"
  * "subalgebraBasis(...,PrintLevel=>...)"
  * "subduction(...,PrintLevel=>...)"

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

The object PrintLevel, is a symbol (Macaulay2Doc).

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

The source of this document is in SubalgebraBases/documentation.m2:516:0.

Recompute -- Flag for restarting a sagbi or isSAGBI computation
***************************************************************

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

If the flag is set to true, then the subalgebra bases computation starts from
scratch. This process constructs a SAGBIBasis, and uses the
computation options from the previous computation.

If the flag is set to false (the typical case), then previous computations are
used to speed up subsequent calculations.

See also
========

  * sagbi -- Compute a subalgebra basis (sagbi basis)
  * isSAGBI -- Check if the generators are a subalgebra basis
  * sagbiBasis -- Constructs a computation object from a
    subring.
  * subduction -- Subduction against a set elements
  * subalgebraBasis -- Compute subalgebra basis
    generators
  * Compute -- Flag for performing computations while checking
    the completeness of a subalgebra basis
  * ModifySAGBIBasis -- Flag for allowing the cached
    computation object to be modified
  * PrintLevel -- Levels of information displayed during
    Sagbi algorithm
  * RenewOptions -- Flag for reselecting the options for a
    subalgebra bases computation
  * ReduceNewGenerators -- Flag for reducing new
    generators in Sagbi algorithm
  * ModifySAGBIBasis -- Flag for allowing the cached
    computation object to be modified

Functions with optional argument named Recompute:
=================================================

  * "isSAGBI(List,Recompute=>...)"
  * "isSAGBI(Matrix,Recompute=>...)"
  * "isSAGBI(SAGBIBasis,Recompute=>...)"
  * "isSAGBI(Subring,Recompute=>...)"
  * "sagbi(...,Recompute=>...)"
  * "sagbiBasis(...,Recompute=>...)"
  * "subalgebraBasis(...,Recompute=>...)"
  * "subduction(...,Recompute=>...)"

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

The object Recompute, is a symbol (Macaulay2Doc).

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

The source of this document is in SubalgebraBases/documentation.m2:552:0.

ReduceNewGenerators -- Flag for reducing new generators in Sagbi algorithm
**************************************************************************

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

The function sagbi, computes a subalgebra basis by subducting
S-pairs. Any resulting non-zero polynomials are added to the list of subalgebra
generators. If ReduceNewGenerators is set to true, then the new generators are
reduced (using Gaussian elimination) against the other new generators. This
process is quick and ensures that duplicate generators are not added to the
list of subalgebra generators.

See also
========

  * sagbi -- Compute a subalgebra basis (sagbi basis)
  * sagbiBasis -- Constructs a computation object from a
    subring.
  * subalgebraBasis -- Compute subalgebra basis
    generators
  * subduction -- Subduction against a set elements
  * AutoSubduce -- Flag for autosubduction before the sagbi
    algorithm
  * ReduceNewGenerators -- Flag for reducing new
    generators in Sagbi algorithm
  * StorePending -- Flag for storing the pending list to
    the result of the Sagbi algorithm
  * SubductionMethod -- Subduction method for the
    Sagbi algorithm
  * AutoSubduceOnPartialCompletion, --
    Subduct subalgebra generators at the end of the sagbi algorithm
  * PrintLevel -- Levels of information displayed during
    Sagbi algorithm
  * Recompute -- Flag for restarting a sagbi or isSAGBI
    computation
  * RenewOptions -- Flag for reselecting the options for a
    subalgebra bases computation

Functions with optional argument named ReduceNewGenerators:
===========================================================

  * "sagbi(...,ReduceNewGenerators=>...)"
  * "sagbiBasis(...,ReduceNewGenerators=>...)"
  * "subalgebraBasis(...,ReduceNewGenerators=>...)"
  * "subduction(...,ReduceNewGenerators=>...)"

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

The object ReduceNewGenerators, is a symbol (Macaulay2Doc).

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

The source of this document is in SubalgebraBases/documentation.m2:342:0.

Reduction in subrings -- Remainder modulo a subring
***************************************************

  * Usage:
        r = f % S
        R = M % S
        r = f % SB
        R = M % SB
  * Inputs:
      * f, a ring element (Macaulay2Doc),
      * M, a matrix (Macaulay2Doc),
      * S, a subring,
      * SB, a SAGBIBasis,
  * Outputs:
      * r, a ring element (Macaulay2Doc), the normal form of
        f modulo the Subring or SAGBIBasis
      * R, a matrix (Macaulay2Doc), the normal form of entries of
        M modulo the subring or the SAGBIBasis

The result is zero if and only if the input belongs to the subring. If a
subalgebra basis is known for the subring, then subduction is used to compute
the normal forms. If no subalgebra basis is known, then an extrinsic method is
used, similar to groebnerMembershipTest.

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x1, x2, x3];                                                     |
+-----------------------------------------------------------------------------+
|i2 : S = subring {x1+x2+x3, x1*x2+x1*x3+x2*x3, x1*x2*x3,                     |
|                                                                             |
|o2 = QQ[p_0..p_3], subring of R                                              |
|                                                                             |
|o2 : Subring                                                                 |
|-----------------------------------------------------------------------------|
|(x1-x2)*(x1-x3)*(x2-x3)}                                                     |
+-----------------------------------------------------------------------------+
|i3 : f = x1 + x2 + 2*x3                                                      |
|                                                                             |
|o3 = x1 + x2 + 2x3                                                           |
|                                                                             |
|o3 : R                                                                       |
+-----------------------------------------------------------------------------+
|i4 : f % S                                                                   |
|                                                                             |
|o4 = x3                                                                      |
|                                                                             |
|o4 : R                                                                       |
+-----------------------------------------------------------------------------+
|i5 : g = x1^2*x2 + x2^2*x3 + x3^2*x1                                         |
|                                                                             |
|       2       2          2                                                  |
|o5 = x1 x2 + x2 x3 + x1*x3                                                   |
|                                                                             |
|o5 : R                                                                       |
+-----------------------------------------------------------------------------+
|i6 : g % S                                                                   |
|                                                                             |
|o6 = 0                                                                       |
|                                                                             |
|o6 : R                                                                       |
+-----------------------------------------------------------------------------+

See also
========

  * Subring -- The type of all subrings
  * SAGBIBasis -- The type of all subalgebra bases
  * groebnerMembershipTest -- Extrinsic method
    for subring membership
-------------------------------------------------------------------------------

The source of this document is in SubalgebraBases/documentation.m2:1209:0.

RenewOptions -- Flag for reselecting the options for a subalgebra bases computation
***********************************************************************************

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

When a subalgebra bases computation is initialized (for the first time), the
options of that computation are stored in the computation object. Whenever the
computation is resumed, the same options will apply to the computation, with
the exception of PrintLevel, Limit,
see Recompute, and RenewOptions.
To change the other options in the computation, set this flag to
true. The new options will be used and stored in the computation object.

See also
========

  * sagbi -- Compute a subalgebra basis (sagbi basis)
  * forceSB -- declare the generators to be a complete
    subalgebra basis
  * isSAGBI -- Check if the generators are a subalgebra basis
  * sagbiBasis -- Constructs a computation object from a
    subring.
  * subalgebraBasis -- Compute subalgebra basis
    generators
  * subduction -- Subduction against a set elements
  * AutoSubduce -- Flag for autosubduction before the sagbi
    algorithm
  * ReduceNewGenerators -- Flag for reducing new
    generators in Sagbi algorithm
  * StorePending -- Flag for storing the pending list to
    the result of the Sagbi algorithm
  * SubductionMethod -- Subduction method for the
    Sagbi algorithm
  * AutoSubduceOnPartialCompletion, --
    Subduct subalgebra generators at the end of the sagbi algorithm
  * Subduction computation limit -- Bound
    for subalgebra basis computation
  * Subduction strategies -- Update procedure for
    the Sagbi algorithm
  * PrintLevel -- Levels of information displayed during
    Sagbi algorithm
  * Recompute -- Flag for restarting a sagbi or isSAGBI
    computation

Functions with optional argument named RenewOptions:
====================================================

  * "forceSB(SAGBIBasis,RenewOptions=>...)"
  * "forceSB(Subring,RenewOptions=>...)"
  * "isSAGBI(List,RenewOptions=>...)"
  * "isSAGBI(Matrix,RenewOptions=>...)"
  * "isSAGBI(SAGBIBasis,RenewOptions=>...)"
  * "isSAGBI(Subring,RenewOptions=>...)"
  * "sagbi(...,RenewOptions=>...)"
  * "sagbiBasis(...,RenewOptions=>...)"
  * "subalgebraBasis(...,RenewOptions=>...)"
  * "subduction(...,RenewOptions=>...)"

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

The object RenewOptions, is a symbol (Macaulay2Doc).

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

The source of this document is in SubalgebraBases/documentation.m2:595:0.

ring(SAGBIBasis) -- The lifted ring of a SAGBIBasis computation object
**********************************************************************

  * Function: ring (Macaulay2Doc),
  * Usage:
        result = ring S
  * Inputs:
      * S, a SAGBIBasis,
  * Outputs:
      * result, a ring (Macaulay2Doc),

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

Returns the lifted ring of a SAGBIBasis. This is always a
polynomial ring (Macaulay2Doc), and the flattened ring,
is a quotient of this ring.

+-----------------------------------------------------------------+
|i1 : R = QQ[x,y,z];                                              |
+-----------------------------------------------------------------+
|i2 : S = sagbi {x^2, y^2, z^2}                                   |
|                                                                 |
|o2 = SAGBIBasis Computation Object with 3 generators, Limit = 20.|
|                                                                 |
|o2 : SAGBIBasis                                                  |
+-----------------------------------------------------------------+
|i3 : ring S                                                      |
|                                                                 |
|o3 = R                                                           |
|                                                                 |
|o3 : PolynomialRing                                              |
+-----------------------------------------------------------------+
|i4 : Q = R / ideal(x^3 - y);                                     |
+-----------------------------------------------------------------+
|i5 : S' = sagbi {x^3, y^2}                                       |
|                                                                 |
|o5 = SAGBIBasis Computation Object with 1 generators, Limit = 20.|
|                                                                 |
|o5 : SAGBIBasis                                                  |
+-----------------------------------------------------------------+
|i6 : ring S'                                                     |
|                                                                 |
|o6 = R                                                           |
|                                                                 |
|o6 : PolynomialRing                                              |
+-----------------------------------------------------------------+

See also
========

  * SAGBIBasis -- The type of all subalgebra bases
  * ambient(SAGBIBasis) -- The ambient ring of
    a SAGBIBasis computation object
  * ring(SAGBIBasis) -- The lifted ring of a
    SAGBIBasis computation object
  * net(SAGBIBasis) -- Short summary of a
    subalgebra basis computation object
  * sagbi -- Compute a subalgebra basis (sagbi basis)
  * flattenedRing(SAGBIBasis) -- The flattened ring of a
    subring or sagbiBasis

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

  * ring(SAGBIBasis) -- The lifted ring of a
    SAGBIBasis computation object
-------------------------------------------------------------------------------

The source of this document is in SubalgebraBases/documentation.m2:2067:0.

RingElement // Subring -- Subduction quotient with respect to a subring
***********************************************************************

  * Operator: // (Macaulay2Doc),
  * Usage:
        r = f // S
  * Inputs:
      * f, a ring element (Macaulay2Doc),
      * S, a subring,
  * Outputs:
      * r, a ring element (Macaulay2Doc), a subduction
        quotient of f with respect to the subring

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

The result is a ring element that lies in the presentationRing,
that has one variable for each generator of the subring $S$.
A subduction quotient is an expression of $f - (f\%S) \in S$ in terms of the
generators of $S$. The value of this element in the ambient(Subring),
ring can be recovered using the field presentationMap of
the subring.

+---------------------------------+
|i1 : R = QQ[x,y];                |
+---------------------------------+
|i2 : S = subring {x+y,x*y,x*y^2};|
+---------------------------------+
|i3 : f = x^3;                    |
+---------------------------------+
|i4 : f - (f%S)                   |
|                                 |
|      3    2        2    3       |
|o4 = x  + x y + 2x*y  + y        |
|                                 |
|o4 : R                           |
+---------------------------------+
|i5 : gs = f // S                 |
|                                 |
|      3                          |
|o5 = p  - 2p p  + p              |
|      0     0 1    2             |
|                                 |
|o5 : QQ[p ..p ]                  |
|         0   2                   |
+---------------------------------+
|i6 : S#"presentationMap" gs      |
|                                 |
|      3    2        2    3       |
|o6 = x  + x y + 2x*y  + y        |
|                                 |
|o6 : R                           |
+---------------------------------+

This function calls groebnerSubductionQuotient.

See also
========

  * groebnerSubductionQuotient -- Extrinsic
    method for subduction quotients
  * RingElement % Subring -- Remainder modulo a
    subring
  * Matrix % Subring -- Remainder modulo a
    subring
  * RingElement % SAGBIBasis -- Remainder modulo
    a subring
  * Matrix % SAGBIBasis -- Remainder modulo a
    subring
  * Subring -- The type of all subrings
  * SAGBIBasis -- The type of all subalgebra bases
  * groebnerMembershipTest -- Extrinsic method
    for subring membership

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

  * RingElement // Subring -- Subduction
    quotient with respect to a subring
-------------------------------------------------------------------------------

The source of this document is in SubalgebraBases/documentation.m2:1164:0.

sagbi -- Compute a subalgebra basis (sagbi basis)
*************************************************

  * Usage:
        N = sagbi M
        N = sagbi A
        N = sagbi L
        N = sagbi B
  * Inputs:
      * A, a subring,
      * M, a matrix (Macaulay2Doc), of generators for a
        subring, of a polynomial ring (Macaulay2Doc),
      * L, a list (Macaulay2Doc), containing generators for a
        subring, of a polynomial ring (Macaulay2Doc),
      * B, a SAGBIBasis, containing a partial computation of
        a subalgebra basis
  * Optional inputs (Macaulay2Doc),:
      * AutoSubduce, => a Boolean value (Macaulay2Doc),
        default value true, a flag indicating when to
        perform autosubduction on the generators before performing the
        subalgebra basis computation
      * ReduceNewGenerators, => a Boolean value (Macaulay2Doc),
        default value true, a flag indicating
        whether to reduce (via Gaussian elimination) to new subalgebra
        generators before adding them to the current subalgebra basis
      * StorePending, => a Boolean value (Macaulay2Doc),
        default value true, a flag that indicates
        whether the pending list should be stored in the result.
      * Strategy, => a string (Macaulay2Doc),
        default value "Master", the name of the update
        strategy at the beginning of each loop: "DegreeByDegree",
        "Incremental", and "Master". The strategy "Master" is a hybrid method
        that combines the other two; starting with "DegreeByDegree" for low
        degrees and switching to "Incremental".
      * SubductionMethod, => a string (Macaulay2Doc),
        default value "Top", the name of the method used
        for subduction either: "Top" or "Engine".
      * Limit, => an integer (Macaulay2Doc),
        default value 20, a degree limit for the binomial
        S-pairs that are computed internally.
      * AutoSubduceOnPartialCompletion,
        => a Boolean value (Macaulay2Doc), default value false,
        a flag that indicates whether autosubduction is applied to the
        subalgebra generators the first time no new generators are added. Use
        this only if very few new subalgebra generators are expected.
      * PrintLevel, => an integer (Macaulay2Doc),
        default value 0, an option to produce additional output. When this is
        greater than zero, information is printed about the progress of the
        computation
      * Recompute, => a Boolean value (Macaulay2Doc),
        default value false, a flag that indicates if
        the computation will resume in subsequent runs, otherwise it starts at
        the beginning
      * RenewOptions, => a Boolean value (Macaulay2Doc),
        default value false, a flag that indicates if
        the computation will use the options specified, otherwise it will use
        the previously selected options (except for the following, which may
        always be specified: PrintLevel, Limit,
        see Recompute, and
        RenewOptions)
  * Outputs:
      * N, a SAGBIBasis, a computation object holding the
        state of the subalgebra basis computation

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

The output of this function is a partial subalgebra basis stored in a
computation object.

+-----------------------------------------------------------------------------+
|i1 : R = QQ[t_(1,1)..t_(3,3),MonomialOrder=>Lex];                            |
+-----------------------------------------------------------------------------+
|i2 : M = genericMatrix(R,3,3);                                               |
|                                                                             |
|             3      3                                                        |
|o2 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+
|i3 : A = subring gens minors(2, M);                                          |
+-----------------------------------------------------------------------------+
|i4 : isSAGBI A                                                               |
|                                                                             |
|o4 = false                                                                   |
+-----------------------------------------------------------------------------+
|i5 : S = sagbi A;                                                            |
+-----------------------------------------------------------------------------+
|i6 : gS = gens S                                                             |
|                                                                             |
|o6 = | t_(2,2)t_(3,3)-t_(2,3)t_(3,2) t_(2,1)t_(3,3)-t_(2,3)t_(3,1)           |
|     ------------------------------------------------------------------------|
|     t_(2,1)t_(3,2)-t_(2,2)t_(3,1) t_(1,2)t_(3,3)-t_(1,3)t_(3,2)             |
|     ------------------------------------------------------------------------|
|     t_(1,2)t_(2,3)-t_(1,3)t_(2,2) t_(1,1)t_(3,3)-t_(1,3)t_(3,1)             |
|     ------------------------------------------------------------------------|
|     t_(1,1)t_(3,2)-t_(1,2)t_(3,1) t_(1,1)t_(2,3)-t_(1,3)t_(2,1)             |
|     ------------------------------------------------------------------------|
|     t_(1,1)t_(2,2)-t_(1,2)t_(2,1)                                           |
|     ------------------------------------------------------------------------|
|     t_(1,1)t_(2,2)t_(3,1)t_(3,3)-t_(1,1)t_(2,3)t_(3,1)t_(3,2)-t_(1,2)t_(2,1)|
|     ------------------------------------------------------------------------|
|     t_(3,1)t_(3,3)+t_(1,2)t_(2,3)t_(3,1)^2+t_(1,3)t_(2,1)t_(3,1)t_(3,2)-t_(1|
|     ------------------------------------------------------------------------|
|     ,3)t_(2,2)t_(3,1)^2 t_(1,1)t_(1,3)t_(2,2)t_(3,3)-t_(1,1)t_(1,3)t_(2,3)t |
|     ------------------------------------------------------------------------|
|     _(3,2)-t_(1,2)t_(1,3)t_(2,1)t_(3,3)+t_(1,2)t_(1,3)t_(2,3)t_(3,1)+t_(1,3 |
|     ------------------------------------------------------------------------|
|     )^2t_(2,1)t_(3,2)-t_(1,3)^2t_(2,2)t_(3,1) |                             |
|                                                                             |
|             1      11                                                       |
|o6 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+
|i7 : isSAGBI gS                                                              |
|                                                                             |
|o7 = true                                                                    |
+-----------------------------------------------------------------------------+

Partial subalgebra bases are unavoidable since a subalgebra of a polynomial
ring, endowed with some polynomial order, need not have a finite subalgebra
basis. Here is a quintessential example of this phenomenon:

+------------------------------------------------+
|i8 : R=QQ[x,y];                                 |
+------------------------------------------------+
|i9 : A = subring matrix{{x+y,x*y,x*y^2}};       |
+------------------------------------------------+
|i10 : gens sagbi(A,Limit=>3)                    |
|                                                |
|o10 = | x+y xy xy2 |                            |
|                                                |
|              1      3                          |
|o10 : Matrix R  <-- R                           |
+------------------------------------------------+
|i11 : gens sagbi(A,Limit=>10)                   |
|                                                |
|o11 = | x+y xy xy2 xy3 xy4 xy5 xy6 xy7 xy8 xy9 ||
|                                                |
|              1      10                         |
|o11 : Matrix R  <-- R                           |
+------------------------------------------------+

Nevertheless, a finite subalgebra basis can be computed in many cases.

See also
========

  * subalgebraBasis -- Compute subalgebra basis
    generators
  * AutoSubduce -- Flag for autosubduction before the sagbi
    algorithm
  * ReduceNewGenerators -- Flag for reducing new
    generators in Sagbi algorithm
  * StorePending -- Flag for storing the pending list to
    the result of the Sagbi algorithm
  * SubductionMethod -- Subduction method for the
    Sagbi algorithm
  * AutoSubduceOnPartialCompletion, --
    Subduct subalgebra generators at the end of the sagbi algorithm
  * PrintLevel -- Levels of information displayed during
    Sagbi algorithm
  * Recompute -- Flag for restarting a sagbi or isSAGBI
    computation
  * RenewOptions -- Flag for reselecting the options for a
    subalgebra bases computation
  * Subring -- The type of all subrings
  * SAGBIBasis -- The type of all subalgebra bases
  * Subduction strategies -- Update procedure for
    the Sagbi algorithm
  * Subduction computation limit -- Bound
    for subalgebra basis computation

Ways to use sagbi:
==================

  * "sagbi(List)"
  * "sagbi(Matrix)"
  * "sagbi(SAGBIBasis)"
  * "sagbi(Subring)"

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

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

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

The source of this document is in SubalgebraBases/documentation.m2:267:0.

SAGBIBasis -- The type of all subalgebra bases
**********************************************

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

A computation object for subalgebra bases. It stores a partial subalgebra bases
computation for picking up a computation where it left off. For many uses, it
is superior to use a subring, as the computation SAGBIBases are
handled behind the scenes, and the user experience is more streamlined. To
create a SAGBIBasis, use the function sagbiBasis.
The SAGBIBasis type is the main output type of the function
sagbi. Applying subring, to a SAGBIBasis returns the
original subring that generated the SAGBIBasis.

See also
========

  * sagbiBasis -- Constructs a computation object from a
    subring.
  * Subring -- The type of all subrings
  * subring -- Constructs a subring of a polynomial ring.
  * sagbi -- Compute a subalgebra basis (sagbi basis)
  * generators(SAGBIBasis) -- Returns
    generators of a SAGBIBasis computation object
  * status(SAGBIBasis) -- status of the
    subalgebra bases computation
  * numgens(SAGBIBasis) -- The number of
    generators of a SAGBIBasis

Functions and methods returning a SAGBIBasis:
=============================================

  * sagbi -- Compute a subalgebra basis (sagbi basis)
  * sagbiBasis -- Constructs a computation object from a
    subring.

Methods that use a SAGBIBasis:
==============================

  * ambient(SAGBIBasis) -- The ambient ring of
    a SAGBIBasis computation object
  * "flattenedRing(SAGBIBasis)" -- see flattenedRing, --
    The flattened ring of a subring or sagbiBasis
  * forceSB(SAGBIBasis) -- declare the
    generators to be a complete subalgebra basis
  * generators(SAGBIBasis) -- Returns
    generators of a SAGBIBasis computation object
  * isSAGBI(SAGBIBasis) -- Check if the
    generators are a subalgebra basis
  * net(SAGBIBasis) -- Short summary of a
    subalgebra basis computation object
  * numgens(SAGBIBasis) -- The number of
    generators of a SAGBIBasis
  * "Matrix % SAGBIBasis" -- see Reduction in subrings,
    -- Remainder modulo a subring
  * "RingElement % SAGBIBasis" -- see Reduction in subrings,
    -- Remainder modulo a subring
  * ring(SAGBIBasis) -- The lifted ring of a
    SAGBIBasis computation object
  * "sagbi(SAGBIBasis)" -- see sagbi, -- Compute a subalgebra
    basis (sagbi basis)
  * "sagbiDegree(SAGBIBasis)" -- see sagbiDegree, -- The
    current degree of the subalgebra bases computation
  * "sagbiLimit(SAGBIBasis)" -- see sagbiLimit, -- The
    current limit of the subalgebra bases computation
  * "sagbiStatus(SAGBIBasis)" -- see sagbiStatus, -- checks
    if the subalgebra bases computation is done
  * status(SAGBIBasis) -- status of the
    subalgebra bases computation
  * "subduction(SAGBIBasis,Matrix)" -- see subduction, --
    Subduction against a set elements
  * "subduction(SAGBIBasis,RingElement)" -- see subduction,
    -- Subduction against a set elements
  * "subring(SAGBIBasis)" -- see subring, -- Constructs a
    subring of a polynomial ring.

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

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

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

The source of this document is in SubalgebraBases/documentation.m2:1859:0.

sagbiBasis -- Constructs a computation object from a subring.
*************************************************************

  * Usage:
        B = sagbiBasis S
  * Inputs:
      * S, a subring,
  * Optional inputs (Macaulay2Doc),:
      * AutoSubduce, => a Boolean value (Macaulay2Doc),
        default value true, a flag indicating when to
        perform autosubduction on the generators before performing the
        subalgebra basis computation
      * ReduceNewGenerators, => a Boolean value (Macaulay2Doc),
        default value true, a flag indicating
        whether to reduce (via Gaussian elimination) to new subalgebra
        generators before adding them to the current subalgebra basis
      * StorePending, => a Boolean value (Macaulay2Doc),
        default value true, a flag that indicates
        whether the pending list should be stored in the result.
      * Strategy, => a string (Macaulay2Doc),
        default value "Master", the name of the update
        strategy at the beginning of each loop: "DegreeByDegree",
        "Incremental", and "Master". The strategy "Master" is a hybrid method
        that combines the other two; starting with "DegreeByDegree" for low
        degrees and switching to "Incremental".
      * SubductionMethod, => a string (Macaulay2Doc),
        default value "Top", the name of the method used
        for subduction either: "Top" or "Engine".
      * Limit, => an integer (Macaulay2Doc),
        default value 20, a degree limit for the binomial
        S-pairs that are computed internally.
      * AutoSubduceOnPartialCompletion,
        => a Boolean value (Macaulay2Doc), default value false,
        a flag that indicates whether autosubduction is applied to the
        subalgebra generators the first time no new generators are added. Use
        this only if very few new subalgebra generators are expected.
      * PrintLevel, => an integer (Macaulay2Doc),
        default value 0, an option to produce additional output. When this is
        greater than zero, information is printed about the progress of the
        computation
      * Recompute, => a Boolean value (Macaulay2Doc),
        default value false, a flag that indicates if
        the computation will resume in subsequent runs, otherwise it starts at
        the beginning
      * RenewOptions, => a Boolean value (Macaulay2Doc),
        default value false, a flag that indicates if
        the computation will use the options specified, otherwise it will use
        the previously selected options (except for the following, which may
        always be specified: PrintLevel, Limit,
        see Recompute, and
        RenewOptions)
  * Outputs:
      * B, a SAGBIBasis, a computation object associated to
        S

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

This function serves as the canonical constructor for the SAGBIBasis,
type. The SAGBIBasis type is also the output of the function
sagbi. The Subring, used to construct a SAGBIBasis may
be recovered using subring,

+--------------------------------------------------------------------------+
|i1 : R = QQ[x,y];                                                         |
+--------------------------------------------------------------------------+
|i2 : S = subring{x+y,x*y,x*y^2};                                          |
+--------------------------------------------------------------------------+
|i3 : T = sagbiBasis S                                                     |
|                                                                          |
|o3 = Partial SAGBIBasis Computation Object with 0 generators, Limit = -1. |
|                                                                          |
|o3 : SAGBIBasis                                                           |
+--------------------------------------------------------------------------+
|i4 : sagbi(T,Limit=>20)                                                   |
|                                                                          |
|o4 = Partial SAGBIBasis Computation Object with 20 generators, Limit = 20.|
|                                                                          |
|o4 : SAGBIBasis                                                           |
+--------------------------------------------------------------------------+
|i5 : subring T                                                            |
|                                                                          |
|o5 = QQ[p_0..p_2], subring of R                                           |
|                                                                          |
|o5 : Subring                                                              |
+--------------------------------------------------------------------------+

See also
========

  * sagbi -- Compute a subalgebra basis (sagbi basis)
  * subalgebraBasis -- Compute subalgebra basis
    generators
  * AutoSubduce -- Flag for autosubduction before the sagbi
    algorithm
  * ReduceNewGenerators -- Flag for reducing new
    generators in Sagbi algorithm
  * StorePending -- Flag for storing the pending list to
    the result of the Sagbi algorithm
  * SubductionMethod -- Subduction method for the
    Sagbi algorithm
  * AutoSubduceOnPartialCompletion, --
    Subduct subalgebra generators at the end of the sagbi algorithm
  * PrintLevel -- Levels of information displayed during
    Sagbi algorithm
  * Recompute -- Flag for restarting a sagbi or isSAGBI
    computation
  * RenewOptions -- Flag for reselecting the options for a
    subalgebra bases computation
  * Subring -- The type of all subrings
  * SAGBIBasis -- The type of all subalgebra bases
  * Subduction strategies -- Update procedure for
    the Sagbi algorithm
  * Subduction computation limit -- Bound
    for subalgebra basis computation
  * forceSB -- declare the generators to be a complete
    subalgebra basis

Ways to use sagbiBasis:
=======================

  * "sagbiBasis(Subring)"

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

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

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

The source of this document is in SubalgebraBases/documentation.m2:1937:0.

sagbiDegree -- The current degree of the subalgebra bases computation
*********************************************************************

  * Usage:
        result = sagbiDegree SB
  * Inputs:
      * SB, a SAGBIBasis,
  * Outputs:
      * result, an integer (Macaulay2Doc), the current degree of
        computation in SB.

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

Returns the current degree of the computation stored in a SAGBIBasis.
When the computation is resumed (without restarting) then the
algorithm will pick up at this degree. The degree may drop during the
computation.

+----------------------------------------+
|i1 : R = QQ[x,y];                       |
+----------------------------------------+
|i2 : S = subring{x+y,x*y,x*y^2,x*y^5+y};|
+----------------------------------------+
|i3 : T = sagbiBasis S;                  |
+----------------------------------------+
|i4 : sagbiDegree T                      |
|                                        |
|o4 = -1                                 |
+----------------------------------------+
|i5 : sagbiDegree sagbi(S,Limit=>5)      |
|                                        |
|o5 = 6                                  |
+----------------------------------------+
|i6 : sagbiDegree sagbi(S,Limit=>20)     |
|                                        |
|o6 = 7                                  |
+----------------------------------------+
|i7 : isSAGBI(S,UseSubringGens=>false)   |
|                                        |
|o7 = true                               |
+----------------------------------------+

See also
========

  * SAGBIBasis -- The type of all subalgebra bases
  * sagbiBasis -- Constructs a computation object from a
    subring.
  * generators(SAGBIBasis) -- Returns
    generators of a SAGBIBasis computation object
  * status(SAGBIBasis) -- status of the
    subalgebra bases computation
  * sagbiLimit -- The current limit of the subalgebra bases
    computation
  * sagbi -- Compute a subalgebra basis (sagbi basis)

Ways to use sagbiDegree:
========================

  * "sagbiDegree(SAGBIBasis)"

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

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

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

The source of this document is in SubalgebraBases/documentation.m2:2103:0.

sagbiLimit -- The current limit of the subalgebra bases computation
*******************************************************************

  * Usage:
        result = sagbiLimit SB
  * Inputs:
      * SB, a SAGBIBasis,
  * Outputs:
      * result, an integer (Macaulay2Doc), the current upper bound on
        degree of a subalgebra bases computation

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

Returns the current limit of the subalgebra bases computation. When the
computation is resumed then this limit may be set to a new specified limit.

+----------------------------------------+
|i1 : R = QQ[x,y];                       |
+----------------------------------------+
|i2 : S = subring{x+y,x*y,x*y^2,x*y^5+y};|
+----------------------------------------+
|i3 : T = sagbiBasis S;                  |
+----------------------------------------+
|i4 : sagbiLimit T                       |
|                                        |
|o4 = -1                                 |
+----------------------------------------+
|i5 : sagbiLimit sagbi(S,Limit=>5)       |
|                                        |
|o5 = 5                                  |
+----------------------------------------+
|i6 : sagbiLimit sagbi(S,Limit=>30)      |
|                                        |
|o6 = 30                                 |
+----------------------------------------+

See also
========

  * SAGBIBasis -- The type of all subalgebra bases
  * sagbiBasis -- Constructs a computation object from a
    subring.
  * generators(SAGBIBasis) -- Returns
    generators of a SAGBIBasis computation object
  * status(SAGBIBasis) -- status of the
    subalgebra bases computation
  * sagbiDegree -- The current degree of the subalgebra
    bases computation
  * sagbi -- Compute a subalgebra basis (sagbi basis)

Ways to use sagbiLimit:
=======================

  * "sagbiLimit(SAGBIBasis)"

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

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

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

The source of this document is in SubalgebraBases/documentation.m2:2137:0.

SAGBILimitType -- Flag for calculating degree limit in intersections
********************************************************************

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

There are two possible values for SAGBILimitType: Fixed or Function. Determines
the stopping criterion for the subalgebra basis computation performed by the
function intersect(Subring,Subring).
This function creates a subring, $S$, called the composite
subring, from the input algebras and attempts to compute a subalgebra basis for
$S$. The Limit, of this subalgebra basis
computation is controlled by the two options SAGBILimitType and Limit.

If SAGBILimitType is set to Fixed, then the Limit,
of the subalgebra basis computation is set to the value of the option
Limit. Otherwise, if SAGBILimitType is set
to Function, then the Limit, of the
subalgebra basis computation is set to the product of the degrees of the
maximum degree generators of the input algebras.

+--------------------------------------------------------------------------+
|i1 : R = QQ[x,y];                                                         |
+--------------------------------------------------------------------------+
|i2 : I = ideal(x^3 + x*y^2 + y^3);                                        |
|                                                                          |
|o2 : Ideal of R                                                           |
+--------------------------------------------------------------------------+
|i3 : Q = R/I;                                                             |
+--------------------------------------------------------------------------+
|i4 : S1 = subring {x^2, x*y};                                             |
+--------------------------------------------------------------------------+
|i5 : S2 = subring {x, y^2};                                               |
+--------------------------------------------------------------------------+
|i6 : gens (S3 = intersect(S1, S2, SAGBILimitType => "Fixed", Limit => 5)) |
|-- Warning! Result is not a full intersection.  Try increasing Limit.     |
|                                                                          |
|o6 = | x2 x2y2+xy3 |                                                      |
|                                                                          |
|             1      2                                                     |
|o6 : Matrix Q  <-- Q                                                      |
+--------------------------------------------------------------------------+
|i7 : gens (S4 = intersect(S1, S2, SAGBILimitType => "Fixed", Limit => 10))|
|                                                                          |
|o7 = | x2 x2y2+xy3 y4 xy3 y6 xy5 |                                        |
|                                                                          |
|             1      6                                                     |
|o7 : Matrix Q  <-- Q                                                      |
+--------------------------------------------------------------------------+
|i8 : gens (S5 = intersect(S1, S2, SAGBILimitType => "Function"))          |
|-- Warning! Result is not a full intersection.  Try increasing Limit.     |
|                                                                          |
|o8 = | x2 x2y2+xy3 |                                                      |
|                                                                          |
|             1      2                                                     |
|o8 : Matrix Q  <-- Q                                                      |
+--------------------------------------------------------------------------+

By default, the option SAGBILimitType is set to Fixed, and the default
Limit, is $20$. For more information see
intersect(Subring,Subring).

See also
========

  * intersect(Subring,Subring), --
    Intersection of subrings
  * IntersectedSubring -- The type of all subrings
    arising from intersection
  * sagbi -- Compute a subalgebra basis (sagbi basis)
  * SAGBILimitType -- Flag for calculating degree limit
    in intersections
  * CheckFullIntersection -- Flag for deciding if
    isFullIntersection is called
  * Subduction computation limit -- Bound
    for subalgebra basis computation

Functions with optional argument named SAGBILimitType:
======================================================

  * "intersect(Subring,Subring,SAGBILimitType=>...)"

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

The object SAGBILimitType, is a symbol (Macaulay2Doc).

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

The source of this document is in SubalgebraBases/documentation.m2:1259:0.

sagbiStatus -- checks if the subalgebra bases computation is done
*****************************************************************

  * Usage:
        result = sagbiStatus SB
  * Inputs:
      * SB, a SAGBIBasis,
  * Outputs:
      * result, a Boolean value (Macaulay2Doc), is true if the
        subalgebra basis computation is complete

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

Returns true if the subalgebra bases computation is completed otherwise returns
false. It is possible that the computed subalgebra basis generators form a
subalgebra basis while sagbiStatus returns false. In this case, additional
computation is needed to confirm that the computed generators form a subalgebra
basis. For more descriptive output, see status(SAGBIBasis).

+------------------------------------------+
|i1 : R = QQ[x,y];                         |
+------------------------------------------+
|i2 : S = subring {x+y,x*y,x*y^2,x*y^10+y};|
+------------------------------------------+
|i3 : sagbiStatus sagbi(S,Limit=>10)       |
|                                          |
|o3 = false                                |
+------------------------------------------+
|i4 : sagbiStatus sagbi(S,Limit=>20)       |
|                                          |
|o4 = true                                 |
+------------------------------------------+

See also
========

  * SAGBIBasis -- The type of all subalgebra bases
  * sagbiBasis -- Constructs a computation object from a
    subring.
  * status(SAGBIBasis) -- status of the
    subalgebra bases computation
  * sagbi -- Compute a subalgebra basis (sagbi basis)

Ways to use sagbiStatus:
========================

  * "sagbiStatus(SAGBIBasis)"

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

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

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

The source of this document is in SubalgebraBases/documentation.m2:2173:0.

status(SAGBIBasis) -- status of the subalgebra bases computation
****************************************************************

  * Function: status (Macaulay2Doc),
  * Usage:
        result = status SB
  * Inputs:
      * SB, a SAGBIBasis,
  * Optional inputs (Macaulay2Doc),:
      * Monomials (missing documentation) => a Boolean value (Macaulay2Doc),
        default value false, unused option
      * PairsRemaining (missing documentation) => a Boolean value (Macaulay2Doc),
        default value false, unused option
      * TotalPairs (missing documentation) => a Boolean value (Macaulay2Doc),
        default value true, unused option
  * Outputs:
      * result, a string (Macaulay2Doc), a description of the
        status of a subalgebra basis computation

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

Returns a string with a human readable description of the status of subalgebra
bases computation.

+--------------------------------------------------------------+
|i1 : R = QQ[x,y];                                             |
+--------------------------------------------------------------+
|i2 : S = subring {x+y,x*y,x*y^2,x*y^10+y};                    |
+--------------------------------------------------------------+
|i3 : status sagbi(S,Limit=>10)                                |
|                                                              |
|o3 = status: DegreeLimit; current degree 11                   |
+--------------------------------------------------------------+
|i4 : status sagbi(S,Limit=>20)                                |
|                                                              |
|o4 = status: done; sagbiGenerators encountered up to degree 10|
+--------------------------------------------------------------+

See also
========

  * SAGBIBasis -- The type of all subalgebra bases
  * sagbiBasis -- Constructs a computation object from a
    subring.
  * sagbiStatus -- checks if the subalgebra bases
    computation is done
  * sagbi -- Compute a subalgebra basis (sagbi basis)

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

  * status(SAGBIBasis) -- status of the
    subalgebra bases computation
-------------------------------------------------------------------------------

The source of this document is in SubalgebraBases/documentation.m2:2207:0.

StorePending -- Flag for storing the pending list to the result of the Sagbi algorithm
**************************************************************************************

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

If the StorePending flag is true, then the SAGBIBasis,
produced by the function sagbi, contains a copy of the pending
list. The pending list contains all unprocessed S-pairs grouped by their
degrees. The pending list may be nonempty if the sagbi, algorithm
terminates without producing a complete subalgebra basis. The pending list is
stored to speed up the computation if it is resumed later.

If the StorePending flag is false, then the pending list is not stored.
Depending on the computation, the pending list may be very large, and it may
not be convenient to save all the data.

See also
========

  * sagbi -- Compute a subalgebra basis (sagbi basis)
  * AutoSubduce -- Flag for autosubduction before the sagbi
    algorithm
  * ReduceNewGenerators -- Flag for reducing new
    generators in Sagbi algorithm
  * SubductionMethod -- Subduction method for the
    Sagbi algorithm
  * AutoSubduceOnPartialCompletion, --
    Subduct subalgebra generators at the end of the sagbi algorithm
  * PrintLevel -- Levels of information displayed during
    Sagbi algorithm
  * Recompute -- Flag for restarting a sagbi or isSAGBI
    computation
  * RenewOptions -- Flag for reselecting the options for a
    subalgebra bases computation
  * sagbiBasis -- Constructs a computation object from a
    subring.
  * subduction -- Subduction against a set elements
  * subalgebraBasis -- Compute subalgebra basis
    generators

Functions with optional argument named StorePending:
====================================================

  * "sagbi(...,StorePending=>...)"
  * "sagbiBasis(...,StorePending=>...)"
  * "subalgebraBasis(...,StorePending=>...)"
  * "subduction(...,StorePending=>...)"

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

The object StorePending, is a symbol (Macaulay2Doc).

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

The source of this document is in SubalgebraBases/documentation.m2:378:0.

subalgebraBasis -- Compute subalgebra basis generators
******************************************************

  * Usage:
        N = subalgebraBasis M
        N = subalgebraBasis A
        N = subalgebraBasis L
        N = subalgebraBasis B
  * Inputs:
      * A, a subring,
      * M, a matrix (Macaulay2Doc), of generators for a
        subring, of a polynomial ring (Macaulay2Doc),
      * L, a list (Macaulay2Doc), containing generators for a
        subring, of a polynomial ring (Macaulay2Doc),
      * B, a SAGBIBasis, containing a partial computation of
        a subalgebra basis
  * Optional inputs (Macaulay2Doc),:
      * AutoSubduce, => a Boolean value (Macaulay2Doc),
        default value true, a flag indicating when to
        perform autosubduction on the generators before performing the
        subalgebra basis computation
      * ReduceNewGenerators, => a Boolean value (Macaulay2Doc),
        default value true, a flag indicating
        whether to reduce (via Gaussian elimination) to new subalgebra basis
        generators before adding them to the current subalgebra basis
      * StorePending, => a Boolean value (Macaulay2Doc),
        default value true, a flag that indicates
        whether the pending list should be stored in the result.
      * Strategy, => a string (Macaulay2Doc),
        default value "Master", the name of the update
        strategy at the beginning of each loop: "DegreeByDegree",
        "Incremental", and "Master". The strategy "Master" is a hybrid method
        that combines the other two; starting with "DegreeByDegree" for low
        degrees and switching to "Incremental".
      * SubductionMethod, => a string (Macaulay2Doc),
        default value "Top", the name of the method used
        for subduction either: "Top" or "Engine".
      * Limit, => an integer (Macaulay2Doc),
        default value 20, a degree limit for the binomial
        S-pairs that are computed internally.
      * AutoSubduceOnPartialCompletion,
        => a Boolean value (Macaulay2Doc), default value false,
        a flag that indicates whether autosubduction is applied to the
        subalgebra basis generators the first time no new generators are added.
        Use this only if very few new subalgebra basis generators are expected.
      * PrintLevel, => an integer (Macaulay2Doc),
        default value 0, an option to produce additional output. When this is
        greater than zero, information is printed about the progress of the
        computation
      * Recompute, => a Boolean value (Macaulay2Doc),
        default value false, a flag that indicates if
        the computation will resume on subsequent runs, otherwise it starts at
        the beginning
      * RenewOptions, => a Boolean value (Macaulay2Doc),
        default value false, a flag that indicates if
        the computation will use the options specified, otherwise it will use
        the previously selected options (except for the following, which may
        always be specified: PrintLevel, Limit,
        see Recompute, and
        RenewOptions)
  * Outputs:
      * N, a matrix (Macaulay2Doc), whose entries form a partial
        subalgebra basis

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

Computes a partial subalgebra basis for its input. This command returns the
computed generators and not a computation object. If the input is a
subring, then the computation object is stored in the cache of the
input.

+-----------------------------------------------------------------------------+
|i1 : R = QQ[t_(1,1)..t_(3,3),MonomialOrder=>Lex];                            |
+-----------------------------------------------------------------------------+
|i2 : M = genericMatrix(R,3,3);                                               |
|                                                                             |
|             3      3                                                        |
|o2 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+
|i3 : A = subring gens minors(2, M);                                          |
+-----------------------------------------------------------------------------+
|i4 : subalgebraBasis A                                                       |
|                                                                             |
|o4 = | t_(2,2)t_(3,3)-t_(2,3)t_(3,2) t_(2,1)t_(3,3)-t_(2,3)t_(3,1)           |
|     ------------------------------------------------------------------------|
|     t_(2,1)t_(3,2)-t_(2,2)t_(3,1) t_(1,2)t_(3,3)-t_(1,3)t_(3,2)             |
|     ------------------------------------------------------------------------|
|     t_(1,2)t_(2,3)-t_(1,3)t_(2,2) t_(1,1)t_(3,3)-t_(1,3)t_(3,1)             |
|     ------------------------------------------------------------------------|
|     t_(1,1)t_(3,2)-t_(1,2)t_(3,1) t_(1,1)t_(2,3)-t_(1,3)t_(2,1)             |
|     ------------------------------------------------------------------------|
|     t_(1,1)t_(2,2)-t_(1,2)t_(2,1)                                           |
|     ------------------------------------------------------------------------|
|     t_(1,1)t_(2,2)t_(3,1)t_(3,3)-t_(1,1)t_(2,3)t_(3,1)t_(3,2)-t_(1,2)t_(2,1)|
|     ------------------------------------------------------------------------|
|     t_(3,1)t_(3,3)+t_(1,2)t_(2,3)t_(3,1)^2+t_(1,3)t_(2,1)t_(3,1)t_(3,2)-t_(1|
|     ------------------------------------------------------------------------|
|     ,3)t_(2,2)t_(3,1)^2 t_(1,1)t_(1,3)t_(2,2)t_(3,3)-t_(1,1)t_(1,3)t_(2,3)t |
|     ------------------------------------------------------------------------|
|     _(3,2)-t_(1,2)t_(1,3)t_(2,1)t_(3,3)+t_(1,2)t_(1,3)t_(2,3)t_(3,1)+t_(1,3 |
|     ------------------------------------------------------------------------|
|     )^2t_(2,1)t_(3,2)-t_(1,3)^2t_(2,2)t_(3,1) |                             |
|                                                                             |
|             1      11                                                       |
|o4 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+

The command subalgebraBasis, A is equivalent to the
command gens, sagbi, A.

See also
========

  * sagbi -- Compute a subalgebra basis (sagbi basis)
  * AutoSubduce -- Flag for autosubduction before the sagbi
    algorithm
  * ReduceNewGenerators -- Flag for reducing new
    generators in Sagbi algorithm
  * StorePending -- Flag for storing the pending list to
    the result of the Sagbi algorithm
  * SubductionMethod -- Subduction method for the
    Sagbi algorithm
  * AutoSubduceOnPartialCompletion, --
    Subduct subalgebra generators at the end of the sagbi algorithm
  * Subduction computation limit -- Bound
    for subalgebra basis computation
  * PrintLevel -- Levels of information displayed during
    Sagbi algorithm
  * Recompute -- Flag for restarting a sagbi or isSAGBI
    computation
  * RenewOptions -- Flag for reselecting the options for a
    subalgebra bases computation
  * generators(SAGBIBasis) -- Returns
    generators of a SAGBIBasis computation object

Ways to use subalgebraBasis:
============================

  * "subalgebraBasis(List)"
  * "subalgebraBasis(Matrix)"
  * "subalgebraBasis(Subring)"

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

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

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

The source of this document is in SubalgebraBases/documentation.m2:167:0.

subduction -- Subduction against a set elements
***********************************************

  * Usage:
        N = subduction(SB, M)
        n = subduction(SB, m)
        N = subduction(S, M)
        n = subduction(S, m)
        N = subduction(F, M)
        n = subduction(F, m)
        nList = subduction(FList, mList)
        n = subduction(FList, m)
  * Inputs:
      * SB, a SAGBIBasis, whose subalgebra generators are
        subducted against
      * S, a subring, whose generators are subducted against
      * F, a matrix (Macaulay2Doc), whose entries are subducted
        against
      * FList, a list (Macaulay2Doc), whose entries are subducted
        against
      * M, a matrix (Macaulay2Doc), a 1-row matrix whose entries
        are to be subducted
      * m, a ring element (Macaulay2Doc), the element to be
        subducted
      * mList, a list (Macaulay2Doc), a list of elements to be
        subducted
  * Optional inputs (Macaulay2Doc),:
      * AutoSubduce, => a Boolean value (Macaulay2Doc),
        default value true, a flag indicating when to
        perform autosubduction on the generators before performing the
        Subalgebra basis computation
      * ReduceNewGenerators, => a Boolean value (Macaulay2Doc),
        default value true, a flag indicating
        whether to reduce (via Gaussian elimination) to new subalgebra
        generators before adding them to the current subalgebra basis
      * StorePending, => a Boolean value (Macaulay2Doc),
        default value true, a flag that indicates
        whether the pending list should be stored in the result.
      * Strategy, => a string (Macaulay2Doc),
        default value "Master", the update strategy at
        the beginning of each loop: "DegreeByDegree", "Incremental", and
        "Master". The strategy "Master" is a hybrid method that combines the
        other two; starting with "DegreeByDegree" for low degrees and switching
        to "Incremental".
      * SubductionMethod, => a string (Macaulay2Doc),
        default value "Top", the method used for
        subduction either: "Top" or "Engine".
      * Limit, => an integer (Macaulay2Doc),
        default value 20, a degree limit for the binomial
        S-pairs that are computed internally.
      * AutoSubduceOnPartialCompletion,
        => a Boolean value (Macaulay2Doc), default value false,
        apply autosubduction to the subalgebra generators the first time no new
        generators are added. Use this only if very few new subalgebra
        generators are expected.
      * PrintLevel, => an integer (Macaulay2Doc),
        default value 0, When this is greater than zero, information is printed
        about the progress of the computation
      * Recompute, => a Boolean value (Macaulay2Doc),
        default value false, if true then the
        computation will resume, otherwise it starts at the beginning
      * RenewOptions, => a Boolean value (Macaulay2Doc),
        default value false, if true then the
        computation uses the options specified, otherwise it uses the
        previously selected options (except for the following, which may always
        be specified: PrintLevel, Limit,
        see Recompute, and
        RenewOptions)
  * Outputs:
      * N, a matrix (Macaulay2Doc), entries of $M$ after
        subduction
      * n, a ring element (Macaulay2Doc), the element $m$
        after subduction
      * nList, a list (Macaulay2Doc), the elements of $mList$ after
        subduction

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

Performs subduction on the input with respect to the generating set of the
supplied object. The result of subduction of $f$ by $S$ is an element $g$ such
that $f-g$ is in $S$. If the generating set is not a subalgebra basis, then the
result of subduction may not be a normal form for the input.

+-----------------------------------+
|i1 : R = QQ[x,y];                  |
+-----------------------------------+
|i2 : S = subring {x+y, x*y, x*y^2};|
+-----------------------------------+
|i3 : f = x^4;                      |
+-----------------------------------+
|i4 : subduction(S, f)              |
|                                   |
|           3    4                  |
|o4 = - 2x*y  - y                   |
|                                   |
|o4 : R                             |
+-----------------------------------+
|i5 : sagbi S;                      |
+-----------------------------------+
|i6 : subduction(gens sagbi S, f)   |
|                                   |
|       4                           |
|o6 = -y                            |
|                                   |
|o6 : R                             |
+-----------------------------------+

See also
========

  * sagbi -- Compute a subalgebra basis (sagbi basis)
  * Subring -- The type of all subrings
  * SAGBIBasis -- The type of all subalgebra bases
  * RingElement % Subring -- Remainder modulo a
    subring
  * AutoSubduce -- Flag for autosubduction before the sagbi
    algorithm
  * ReduceNewGenerators -- Flag for reducing new
    generators in Sagbi algorithm
  * StorePending -- Flag for storing the pending list to
    the result of the Sagbi algorithm
  * SubductionMethod -- Subduction method for the
    Sagbi algorithm
  * AutoSubduceOnPartialCompletion, --
    Subduct subalgebra generators at the end of the sagbi algorithm
  * PrintLevel -- Levels of information displayed during
    Sagbi algorithm
  * Recompute -- Flag for restarting a sagbi or isSAGBI
    computation
  * RenewOptions -- Flag for reselecting the options for a
    subalgebra bases computation
  * Subduction computation limit -- Bound
    for subalgebra basis computation
  * Subduction strategies -- Update procedure for
    the Sagbi algorithm
  * groebnerSubductionQuotient -- Extrinsic
    method for subduction quotients
  * RingElement // Subring -- Subduction
    quotient with respect to a subring

Ways to use subduction:
=======================

  * "subduction(List,List)"
  * "subduction(List,RingElement)"
  * "subduction(Matrix,Matrix)"
  * "subduction(Matrix,RingElement)"
  * "subduction(SAGBIBasis,Matrix)"
  * "subduction(SAGBIBasis,RingElement)"
  * "subduction(Subring,Matrix)"
  * "subduction(Subring,RingElement)"

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

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

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

The source of this document is in SubalgebraBases/documentation.m2:708:0.

Subduction computation limit -- Bound for subalgebra basis computation
**********************************************************************

The value of Limit is used internally within the sagbi, function
to stop the computation before a subalgebra basis has been found. Since
subalgebra bases may be infinite, such a barrier is needed to prevent endless
loops.

The Limit is an upper bound on the degrees of the $S$-pairs considered by the
algorithm in the presentationRing. In this ring, the
degrees are assigned according to the degrees of the leading terms of the
polynomials that the variables represent.

Since the sagbiDegree, does not monotonically increase
during the computation, there is no guarantee that a computed partial
subalgebra basis is complete up to Limit, even when the computation terminates
at this bound.

+------------------------------------------------------------------------+
|i1 : R = QQ[x,y];                                                       |
+------------------------------------------------------------------------+
|i2 : S = subring{x+y,x*y,x*y^2,x*y^5+y};                                |
+------------------------------------------------------------------------+
|i3 : T = sagbiBasis S;                                                  |
+------------------------------------------------------------------------+
|i4 : sagbiDegree T                                                      |
|                                                                        |
|o4 = -1                                                                 |
+------------------------------------------------------------------------+
|i5 : T5 = sagbi(S,Limit=>5)                                             |
|                                                                        |
|o5 = Partial SAGBIBasis Computation Object with 5 generators, Limit = 5.|
|                                                                        |
|o5 : SAGBIBasis                                                         |
+------------------------------------------------------------------------+
|i6 : sagbiDegree T5                                                     |
|                                                                        |
|o6 = 6                                                                  |
+------------------------------------------------------------------------+
|i7 : gens T5                                                            |
|                                                                        |
|o7 = | x+y xy xy2 xy3 xy4 |                                             |
|                                                                        |
|             1      5                                                   |
|o7 : Matrix R  <-- R                                                    |
+------------------------------------------------------------------------+
|i8 : T20 = sagbi(S,Limit=>20)                                           |
|                                                                        |
|o8 = SAGBIBasis Computation Object with 6 generators, Limit = 20.       |
|                                                                        |
|o8 : SAGBIBasis                                                         |
+------------------------------------------------------------------------+
|i9 : sagbiDegree T20                                                    |
|                                                                        |
|o9 = 7                                                                  |
+------------------------------------------------------------------------+
|i10 : gens T20                                                          |
|                                                                        |
|o10 = | x+y xy xy2 xy3 xy4 y |                                          |
|                                                                        |
|              1      6                                                  |
|o10 : Matrix R  <-- R                                                   |
+------------------------------------------------------------------------+

See also
========

  * sagbi -- Compute a subalgebra basis (sagbi basis)
  * AutoSubduce -- Flag for autosubduction before the sagbi
    algorithm
  * ReduceNewGenerators -- Flag for reducing new
    generators in Sagbi algorithm
  * StorePending -- Flag for storing the pending list to
    the result of the Sagbi algorithm
  * Subduction strategies -- Update procedure for
    the Sagbi algorithm
  * SubductionMethod -- Subduction method for the
    Sagbi algorithm
  * AutoSubduceOnPartialCompletion, --
    Subduct subalgebra generators at the end of the sagbi algorithm
  * PrintLevel -- Levels of information displayed during
    Sagbi algorithm
  * Recompute -- Flag for restarting a sagbi or isSAGBI
    computation
  * RenewOptions -- Flag for reselecting the options for a
    subalgebra bases computation
  * intersect(Subring,Subring), --
    Intersection of subrings
  * forceSB -- declare the generators to be a complete
    subalgebra basis
  * isSAGBI -- Check if the generators are a subalgebra basis
  * sagbiBasis -- Constructs a computation object from a
    subring.
  * subalgebraBasis -- Compute subalgebra basis
    generators
  * subduction -- Subduction against a set elements
-------------------------------------------------------------------------------

The source of this document is in SubalgebraBases/documentation.m2:2637:0.

Subduction strategies -- Update procedure for the Sagbi algorithm
*****************************************************************

There are three possible values for Strategy: DegreeByDegree, Incremental, or
Master.

At the beginning of each loop inside of sagbi, the main
SAGBIBasis, computation object is updated. There are two types of
update procedures, and the update procedure that is used is determined by the
value of Strategy.

The DegreeByDegree strategy computes a partial groebner basis of the reduction
ideal from scratch. The DegreeByDegree strategy is better when many new
generators are added during each loop of the sagbi, algorithm. The
Incremental strategy computes a full groebner basis of the reduction ideal by
using the previous full groebner basis together with the data of the new
subalgebra generators. The Incremental strategy is better when there is little
change to the number of subalgebra generators.

For many examples, it is observed that many new generators are added at the
beginning of subalgebra basis computations, but, towards the end of the
computation, there are very few new generators that are added at each step. By
setting Strategy to Master (default), the DegreeByDegree strategy is used at
the beginning, and the strategy switches to Incremental part-of-the-way through
the algorithm.

See also
========

  * sagbi -- Compute a subalgebra basis (sagbi basis)
  * AutoSubduce -- Flag for autosubduction before the sagbi
    algorithm
  * ReduceNewGenerators -- Flag for reducing new
    generators in Sagbi algorithm
  * StorePending -- Flag for storing the pending list to
    the result of the Sagbi algorithm
  * SubductionMethod -- Subduction method for the
    Sagbi algorithm
  * AutoSubduceOnPartialCompletion, --
    Subduct subalgebra generators at the end of the sagbi algorithm
  * PrintLevel -- Levels of information displayed during
    Sagbi algorithm
  * Recompute -- Flag for restarting a sagbi or isSAGBI
    computation
  * RenewOptions -- Flag for reselecting the options for a
    subalgebra bases computation
  * intersect(Subring,Subring), --
    Intersection of subrings
  * forceSB -- declare the generators to be a complete
    subalgebra basis
  * isSAGBI -- Check if the generators are a subalgebra basis
  * sagbiBasis -- Constructs a computation object from a
    subring.
  * subalgebraBasis -- Compute subalgebra basis
    generators
  * subduction -- Subduction against a set elements
-------------------------------------------------------------------------------

The source of this document is in SubalgebraBases/documentation.m2:2579:0.

SubductionMethod -- Subduction method for the Sagbi algorithm
*************************************************************

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

There are two possible values for Strategy: Top and Engine.

There are two implementations to subduct the $S$-pairs in the function
sagbi. Both implementations follow the same procedure, but are coded in
different parts of Macaulay2. Subduction using the Strategy Top (default) is
generally faster for smaller inputs. Subduction using the Engine implementation
can be faster for larger subalgebra bases.

When using the Top Strategy, the status of the computation using sagbi,
can be displayed using the PrintLevel, option.

See also
========

  * sagbi -- Compute a subalgebra basis (sagbi basis)
  * AutoSubduce -- Flag for autosubduction before the sagbi
    algorithm
  * ReduceNewGenerators -- Flag for reducing new
    generators in Sagbi algorithm
  * StorePending -- Flag for storing the pending list to
    the result of the Sagbi algorithm
  * Subduction strategies -- Update procedure for
    the Sagbi algorithm
  * AutoSubduceOnPartialCompletion, --
    Subduct subalgebra generators at the end of the sagbi algorithm
  * PrintLevel -- Levels of information displayed during
    Sagbi algorithm
  * Recompute -- Flag for restarting a sagbi or isSAGBI
    computation
  * RenewOptions -- Flag for reselecting the options for a
    subalgebra bases computation
  * intersect(Subring,Subring), --
    Intersection of subrings
  * forceSB -- declare the generators to be a complete
    subalgebra basis
  * isSAGBI -- Check if the generators are a subalgebra basis
  * sagbiBasis -- Constructs a computation object from a
    subring.
  * subalgebraBasis -- Compute subalgebra basis
    generators
  * subduction -- Subduction against a set elements

Functions with optional argument named SubductionMethod:
========================================================

  * "forceSB(SAGBIBasis,SubductionMethod=>...)"
  * "forceSB(Subring,SubductionMethod=>...)"
  * "intersect(Subring,Subring,SubductionMethod=>...)"
  * "isSAGBI(List,SubductionMethod=>...)"
  * "isSAGBI(Matrix,SubductionMethod=>...)"
  * "isSAGBI(SAGBIBasis,SubductionMethod=>...)"
  * "isSAGBI(Subring,SubductionMethod=>...)"
  * "sagbi(...,SubductionMethod=>...)"
  * "sagbiBasis(...,SubductionMethod=>...)"
  * "subalgebraBasis(...,SubductionMethod=>...)"
  * "subduction(...,SubductionMethod=>...)"

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

The object SubductionMethod, is a symbol (Macaulay2Doc).

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

The source of this document is in SubalgebraBases/documentation.m2:429:0.

Subring -- The type of all subrings
***********************************

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

Subring is a type that stores information associated to a subring of a
polynomial ring or quotient ring, such as a set of subring generators and a
reference to the ring containing these generators. An instance of a Subring is
constructed with the function subring. For many uses, it is
suggested to use a Subring, as the computation objects (see SAGBIBasis)
are handled behind the scenes, and the user experience is more
streamlined.

Every instance of Subring has the following keys (some of which are strings):

  * ambientRing: The polynomial or quotient ring that contains the subring
    instance's generators.
  * generators: A one-row matrix, the generators of the subring.
  * cache: Contains data from previous computations to allow for more efficient
    computations.
  * presentationRing: the polynomial ring with one variable for each generator
    of the subring.
  * presentationMap: a map from the presentation ring to the ambient ring of
    the subring.

See also
========

  * subring -- Constructs a subring of a polynomial ring.
  * generators(Subring) -- A generating set of
    a subring
  * ambient(Subring) -- The ambient ring of a
    subring
  * numgens(Subring) -- The number of generators
    of a subring
  * net(Subring) -- Short summary of a subring
  * presentationRing(Subring) -- returns the
    presentation ring of a subring
  * sagbi -- Compute a subalgebra basis (sagbi basis)
  * SAGBIBasis -- The type of all subalgebra bases
  * subalgebraBasis -- Compute subalgebra basis
    generators
  * flattenedRing(Subring) -- The flattened ring of a
    subring or sagbiBasis

Types of subring:
=================

  * IntersectedSubring -- The type of all subrings
    arising from intersection

Methods that use a subring:
===========================

  * ambient(Subring) -- The ambient ring of a
    subring
  * "flattenedRing(Subring)" -- see flattenedRing, -- The
    flattened ring of a subring or sagbiBasis
  * forceSB(Subring) -- declare the generators to
    be a complete subalgebra basis
  * generators(Subring) -- A generating set of
    a subring
  * "groebnerMembershipTest(RingElement,Subring)" -- see
    groebnerMembershipTest, -- Extrinsic method for
    subring membership
  * "groebnerSubductionQuotient(RingElement,Subring)" -- see
    groebnerSubductionQuotient, -- Extrinsic method
    for subduction quotients
  * intersect(Subring,Subring), --
    Intersection of subrings
  * isSAGBI(Subring) -- Check if the generators
    are a subalgebra basis
  * net(Subring) -- Short summary of a subring
  * numgens(Subring) -- The number of generators
    of a subring
  * "presentationRing(Subring)" -- see presentationRing,
    -- returns the presentation ring of a subring
  * "Matrix % Subring" -- see Reduction in subrings,
    -- Remainder modulo a subring
  * "RingElement % Subring" -- see Reduction in subrings,
    -- Remainder modulo a subring
  * RingElement // Subring -- Subduction
    quotient with respect to a subring
  * "sagbi(Subring)" -- see sagbi, -- Compute a subalgebra basis
    (sagbi basis)
  * "sagbiBasis(Subring)" -- see sagbiBasis, -- Constructs a
    computation object from a subring.
  * "subalgebraBasis(Subring)" -- see subalgebraBasis,
    -- Compute subalgebra basis generators
  * "subduction(Subring,Matrix)" -- see subduction, --
    Subduction against a set elements
  * "subduction(Subring,RingElement)" -- see subduction, --
    Subduction against a set elements

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

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

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

The source of this document is in SubalgebraBases/documentation.m2:1616:0.

subring -- Constructs a subring of a polynomial ring.
*****************************************************

  * Usage:
        A = subring M
        A = subring L
        A = subring S
  * Inputs:
      * M, a matrix (Macaulay2Doc), whose entries are the
        generators for the constructed Subring.
      * L, a list (Macaulay2Doc), containing generators for the
        constructed Subring.
      * S, a SAGBIBasis,
  * Optional inputs (Macaulay2Doc),:
      * GeneratorSymbol => a symbol (Macaulay2Doc), default value
        null, a symbol to be used for the variables of the presentationRing.
  * Outputs:
      * A, a subring, generated by the input generators.

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

This function serves as the canonical constructor for the Subring,
type. For many uses, it is suggested to use a subring,
as the computation objects (see SAGBIBasis) are handled behind
the scenes, and the user experience is more streamlined.

+---------------------------------+
|i1 : R = QQ[x];                  |
+---------------------------------+
|i2 : S = subring {x^4+x^3, x^2+x}|
|                                 |
|o2 = QQ[p_0..p_1], subring of R  |
|                                 |
|o2 : Subring                     |
+---------------------------------+
|i3 : SB = sagbi S;               |
+---------------------------------+
|i4 : gens SB                     |
|                                 |
|o4 = | x2+x x3-x |               |
|                                 |
|             1      2            |
|o4 : Matrix R  <-- R             |
+---------------------------------+
|i5 : (x^3+x^2)%S                 |
|                                 |
|o5 = 0                           |
|                                 |
|o5 : R                           |
+---------------------------------+

See also
========

  * Subring -- The type of all subrings
  * generators(Subring) -- A generating set of
    a subring
  * ambient(Subring) -- The ambient ring of a
    subring
  * numgens(Subring) -- The number of generators
    of a subring
  * net(Subring) -- Short summary of a subring
  * sagbi -- Compute a subalgebra basis (sagbi basis)
  * SAGBIBasis -- The type of all subalgebra bases

Ways to use subring:
====================

  * "subring(List)"
  * "subring(Matrix)"
  * "subring(SAGBIBasis)"

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

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

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

The source of this document is in SubalgebraBases/documentation.m2:1664:0.

UseSubringGens -- Flag for using the subring generators when checking a subalgebra basis
****************************************************************************************

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

When isSAGBI, is supplied a SAGBIBasis, or a
subring, there are two generating sets which can be used:
either the generators of a subring, or the subalgebra generators
of a SAGBIBasis, (which may be stored in the cache of a
subring).

If the flag is set to false, then the check is applied to the subalgebra
generators of $SB$. If the flag is set to true, then the check is applied to
the generators of the subring of $SB$.

See also
========

  * isSAGBI -- Check if the generators are a subalgebra basis
  * isSAGBI(Subring) -- Check if the generators
    are a subalgebra basis
  * isSAGBI(SAGBIBasis) -- Check if the
    generators are a subalgebra basis

Functions with optional argument named UseSubringGens:
======================================================

  * "forceSB(SAGBIBasis,UseSubringGens=>...)"
  * "forceSB(Subring,UseSubringGens=>...)"
  * "isSAGBI(List,UseSubringGens=>...)"
  * "isSAGBI(Matrix,UseSubringGens=>...)"
  * "isSAGBI(SAGBIBasis,UseSubringGens=>...)"
  * "isSAGBI(Subring,UseSubringGens=>...)"

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

The object UseSubringGens, is a symbol (Macaulay2Doc).

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

The source of this document is in SubalgebraBases/documentation.m2:1019:0.