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

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 ring
$k[x_1,\ldots,x_n]$ 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) \mid f \in R],$ is
generated by the elements $in(f_1), \ldots , in(f_k).$ The main functions
provided by this package are for computing these subalgebra bases: sagbi,
see subalgebraBasis, and isSAGBI.

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 )

References
==========

  * Kapur, D., Madlener, K. (1989). A completion procedure for computing a
    canonical basis of a $k$-subalgebra. Proceedings of Computers and
    Mathematics 89 (eds. Kaltofen and Watt), MIT, Cambridge, June 1989
  * Robbiano, L., Sweedler, M. (1990). Subalgebra bases, in W.~Bruns, A.~Simis
    (eds.): Commutative Algebra, Springer Lecture Notes in Mathematics 1430,
    pp.~61--87
  * F. Ollivier, Canonical Bases: Relations with Standard bases, finiteness
    conditions and applications to tame automorphisms, in Effective Methods in
    Algebraic Geometry, Castiglioncello 1990, pp. 379-400, Progress in Math. 94
    Birkhauser, Boston (1991)
  * Stillman, Michael, and Harrison Tsai. Using SAGBI bases to compute
    invariants. J. Pure and Appl. Alg., 1999, pp.~285--302.
  * B. Sturmfels, Groebner bases and Convex Polytopes, Univ. Lecture Series 8,
    Amer Math Soc, Providence, 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://sites.google.com/view/oclarke-homepage/ )
    <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>
  * Legacy author: Mike Stillman (see http://www.math.cornell.edu/~mike/ )
    <mike@math.cornell.edu>
  * Legacy author: Harrison Tsai

Version
=======

This documentation describes version 1.3 of SubalgebraBases.

Source code
===========

The source code from which this documentation is derived is in the file
SubalgebraBases.m2 (see common/share/Macaulay2/SubalgebraBases.m2 ). The
auxiliary files accompanying it are in the directory SubalgebraBases/ (see
common/share/Macaulay2/SubalgebraBases/ ).

Exports
=======

  * Types
      * SAGBIBasis -- The type of all sagbi bases
      * Subring -- The type of all subrings
  * Functions and commands
      * forceSB -- declare the generators of a subring or
        SAGBIBasis to be a complete sagbi basis
      * groebnerMembershipTest -- Extrinsic
        method for subring membership
      * groebnerSubductionQuotient, --
        Extrinsic method for subduction quotients
      * isSAGBI -- Check if the generators are a sagbi basis
      * sagbi -- Compute a subalgebra basis (sagbi basis)
      * sagbiBasis -- Constructs a computation object from a
        subring.
      * sagbiDegree -- The current degree of the sagbi
        computation
      * sagbiLimit -- The current limit of the sagbi
        computation
      * sagbiStatus -- returns if the sagbi computation is
        done
      * subalgebraBasis -- Compute subalgebra basis
        (sagbi basis) generators
      * subduction -- Subduction of polynomials
      * subductionQuotientRing -- returns the
        subduction quotient ring of a subring
      * subring -- Constructs a subring of a polynomial ring.
      * subringIntersection -- Intersection of
        subrings
  * Methods
      * ambient(SAGBIBasis) -- The ambient ring
        of a SAGBIBasis computation object
      * ambient(Subring) -- The ambient ring of a
        subring
      * "forceSB(SAGBIBasis)" -- see forceSB, -- declare the
        generators of a subring or SAGBIBasis to be a complete sagbi basis
      * "forceSB(Subring)" -- see forceSB, -- declare the
        generators of a subring or SAGBIBasis to be a complete sagbi basis
      * generators(SAGBIBasis) -- Returns a
        partial sagbi generating set
      * 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
      * "isSAGBI(List)" -- see isSAGBI, -- Check if the
        generators are a sagbi basis
      * "isSAGBI(Matrix)" -- see isSAGBI, -- Check if the
        generators are a sagbi basis
      * "isSAGBI(SAGBIBasis)" -- see isSAGBI, -- Check if the
        generators are a sagbi basis
      * "isSAGBI(Subring)" -- see isSAGBI, -- Check if the
        generators are a sagbi basis
      * Matrix % SAGBIBasis -- Remainder modulo a
        subring
      * Matrix % Subring -- Remainder modulo a subring
      * net(SAGBIBasis) -- Short summary of a sagbi
        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
      * ring(SAGBIBasis) -- The lifted ring of a
        SAGBIBasis computation object
      * RingElement % SAGBIBasis -- Remainder
        modulo a subring
      * RingElement % Subring -- Remainder modulo
        a subring
      * RingElement // Subring, --
        subductionQuotient 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(HashTable)" -- see sagbiBasis, --
        Constructs a computation object from a subring.
      * "sagbiBasis(Subring)" -- see sagbiBasis, --
        Constructs a computation object from a subring.
      * "sagbiDegree(SAGBIBasis)" -- see sagbiDegree, -- The
        current degree of the sagbi computation
      * "sagbiLimit(SAGBIBasis)" -- see sagbiLimit, -- The
        current limit of the sagbi computation
      * "sagbiStatus(SAGBIBasis)" -- see sagbiStatus, --
        returns if the sagbi computation is done
      * status(SAGBIBasis) -- status of the
        sagbi computation
      * "subalgebraBasis(List)" -- see subalgebraBasis,
        -- Compute subalgebra basis (sagbi basis) generators
      * "subalgebraBasis(Matrix)" -- see subalgebraBasis,
        -- Compute subalgebra basis (sagbi basis) generators
      * "subalgebraBasis(Subring)" -- see subalgebraBasis,
        -- Compute subalgebra basis (sagbi basis) generators
      * "subduction(List,List)" -- see subduction, --
        Subduction of polynomials
      * "subduction(List,RingElement)" -- see subduction, --
        Subduction of polynomials
      * "subduction(Matrix,Matrix)" -- see subduction, --
        Subduction of polynomials
      * "subduction(Matrix,RingElement)" -- see subduction,
        -- Subduction of polynomials
      * "subduction(SAGBIBasis,Matrix)" -- see subduction, --
        Subduction of polynomials
      * "subduction(SAGBIBasis,RingElement)" -- see subduction,
        -- Subduction of polynomials
      * "subduction(Subring,Matrix)" -- see subduction, --
        Subduction of polynomials
      * "subduction(Subring,RingElement)" -- see subduction,
        -- Subduction of polynomials
      * "subductionQuotientRing(Subring)" -- see subductionQuotientRing,
        -- returns the subduction quotient ring of a
        subring
      * "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.
      * "subringIntersection(Subring,Subring)" -- see
        subringIntersection, -- Intersection of subrings
  * Symbols
      * AutoSubduce -- Flag for autosubduction before the
        Sagbi algorithm
      * AutoSubduceOnPartialCompletion,
        -- Subduct sagbi generators at the end of the Sagbi algorithm
      * Compute -- Flag for performing computations while
        checking a sagbi basis
      * GeneratorSymbol -- variables for the
        subductionQuotientRing
      * PrintLevel -- Levels of information displayed during
        Sagbi algorithm
      * Recompute -- Flag for restarting a sagbi computation
      * ReduceNewGenerators -- Flag for reducing
        new generators in Sagbi algorithm
      * RenewOptions -- Flag for reselecting the options
        for a sagbi computation
      * 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 sagbi basis

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

The object SubalgebraBases, is a package (Macaulay2Doc).

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

Synopsis
========

  * Function: ambient (Macaulay2Doc),
  * Usage:
        result = ambient S
  * Inputs:
      * S, an instance of the type SAGBIBasis,
  * Outputs:
      * result, a ring (Macaulay2Doc),

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

Returns the ambient ring of S. This may be a PolynomialRing or QuotientRing.

+------------------------------------------------------------------+
|i1 : R = QQ[x,y,z];                                               |
+------------------------------------------------------------------+
|i2 : S = sagbi {x^2, y^2, z^2}                                    |
|                                                                  |
|o2 = SAGBIBasis Computation Object with 3 generators, Limit = 100.|
|                                                                  |
|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 = 100.|
|                                                                  |
|o5 : SAGBIBasis                                                   |
+------------------------------------------------------------------+
|i6 : ambient S'                                                   |
|                                                                  |
|o6 = Q                                                            |
|                                                                  |
|o6 : QuotientRing                                                 |
+------------------------------------------------------------------+

See also
========

  * SAGBIBasis -- The type of all sagbi bases
  * generators(SAGBIBasis) -- Returns a
    partial sagbi generating set
  * 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 sagbi
    basis computation object
  * status(SAGBIBasis) -- status of the sagbi
    computation
  * sagbiDegree -- The current degree of the sagbi
    computation
  * sagbiLimit -- The current limit of the sagbi computation
  * sagbi -- Compute a subalgebra basis (sagbi basis)

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

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

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

Synopsis
========

  * Function: ambient (Macaulay2Doc),
  * Usage:
        result = ambient S
  * Inputs:
      * S, an instance of the type Subring,
  * Outputs:
      * result, a ring (Macaulay2Doc),

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

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

+----------------------------------+
|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(Subring) -- The ambient ring of a
    subring
  * numgens(Subring) -- The number of generators
    of a subring
  * net(Subring) -- Short summary of a subring

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

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

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

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

By default, the function sagbi, performs autosubduction on the
generators of the given subring before starting the main algorithm. This step
is required to guarantee correctness of the result. However, the output of the
sagbi, algorithm is often correct even when this step is skipped.
Setting this flag to false may result in a performance improvement, albeit with
a risk of errors.

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
  * Strategy (Macaulay2Doc) -- an optional argument
  * SubductionMethod -- Subduction method for the
    Sagbi algorithm
  * Limit (Macaulay2Doc) -- an optional argument
  * AutoSubduceOnPartialCompletion, --
    Subduct sagbi generators at the end of the Sagbi algorithm
  * PrintLevel -- Levels of information displayed during
    Sagbi algorithm
  * Recompute -- Flag for restarting a sagbi computation
  * RenewOptions -- Flag for reselecting the options for a
    sagbi computation

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

  * "forceSB(...,AutoSubduce=>...)" -- see forceSB, -- declare
    the generators of a subring or SAGBIBasis to be a complete sagbi basis
  * "sagbi(...,AutoSubduce=>...)" -- see sagbi, -- Compute a
    subalgebra basis (sagbi basis)
  * "sagbiBasis(...,AutoSubduce=>...)" -- see sagbiBasis, --
    Constructs a computation object from a subring.
  * "subalgebraBasis(...,AutoSubduce=>...)" -- see subalgebraBasis,
    -- Compute subalgebra basis (sagbi basis) generators
  * "subduction(...,AutoSubduce=>...)" -- see subduction, --
    Subduction of polynomials

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

The object AutoSubduce, is a symbol (Macaulay2Doc).

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

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

During the main loop in sagbi, if no new sagbi generators are
added and the AutoSubduceOnPartialCompletion,
flag is true then all sagbi generators are
subducted against each other. This a significant time investment, however if no
new sagbi generators are to be added then the subduction of the sagbi
generators will speed up the computation of the groebner basis of the reduction
ideal and S-pairs.

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
  * Strategy (Macaulay2Doc) -- an optional argument
  * SubductionMethod -- Subduction method for the
    Sagbi algorithm
  * Limit (Macaulay2Doc) -- an optional argument
  * AutoSubduceOnPartialCompletion, --
    Subduct sagbi generators at the end of the Sagbi algorithm
  * PrintLevel -- Levels of information displayed during
    Sagbi algorithm
  * Recompute -- Flag for restarting a sagbi computation
  * RenewOptions -- Flag for reselecting the options for a
    sagbi computation

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

  * "sagbi(...,AutoSubduceOnPartialCompletion=>...)" -- see sagbi,
    -- Compute a subalgebra basis (sagbi basis)
  * "sagbiBasis(...,AutoSubduceOnPartialCompletion=>...)" -- see
    sagbiBasis, -- Constructs a computation object from a subring.
  * "subalgebraBasis(...,AutoSubduceOnPartialCompletion=>...)" -- see
    subalgebraBasis, -- Compute subalgebra basis (sagbi basis)
    generators
  * "subduction(...,AutoSubduceOnPartialCompletion=>...)" -- see
    subduction, -- Subduction of polynomials

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

The object AutoSubduceOnPartialCompletion,
is a symbol (Macaulay2Doc).

Compute -- Flag for performing computations while checking a sagbi basis
************************************************************************

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

A flag that determines whether computations should be performed for verifying
the correctness of a sagbi basis. When the flag is set to false then the
function being called will only use the results of previous computations, if
they exist. When previous computations have not been performed and the flag is
set to false, then the function will usually return null.

See also
========

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

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

  * "isSAGBI(...,Compute=>...)" -- see isSAGBI, -- Check if the
    generators are a sagbi basis

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

The object Compute, is a symbol (Macaulay2Doc).

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 considered
in the preprint Polynomial invariants and SAGBI bases for multi-screws. (see
https://arxiv.org/abs/2001.05417 )

+-----------------------------------------------------------------------------+
|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},      |
|                                                                             |
|                6          1                                                 |
|o2 : Matrix gndR  <--- gndR                                                  |
|-----------------------------------------------------------------------------|
|{-t_1*w_1+t_3*w_3+v_2}, {-t_2*w_1-t_3*w_2+v_3}};                             |
+-----------------------------------------------------------------------------+
|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 above is precisely the 5 invariants Crook and Donelan give in equation (9),
plus the additional 6th invariant.

The generators computed below verify 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_4^2+x_5^2+x_6^2-1,                                           |
|              x_7^2+x_8^2+x_9^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*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_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                                          |                             |
|-----------------------------------------------+                             |
+-----------------------------------------------------------------------------+

forceSB -- declare the generators of a subring or SAGBIBasis to be a complete sagbi basis
*****************************************************************************************

Synopsis
========

  * Usage:
        forceSB S
        forceSB SB
  * Inputs:
      * S, an instance of the type Subring,
      * SB, an instance of the type SAGBIBasis,
  * Optional inputs (Macaulay2Doc),:
      * AutoSubduce => a Boolean value (Macaulay2Doc), default
        value true, subduct the generators against themselves
      * Limit => ..., default value 100
      * PrintLevel => ..., default value 0
      * RenewOptions => ..., default value false
      * Strategy => ..., default value "Master"
      * SubductionMethod => ..., default value "Engine"

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

If forceSB is given a SAGBIBasis, $SB$, then the function
performs autosubduction on the sagbiGenerators of $SB$. The sagbiDone flag is
then set to true without checking whether the generators form a sagbi basis.

If forceSB is given a Subring, $S$, then the function checks
whether a SAGBIBasis, $SB$ has been created for $S$. If $SB$
exists, then forceSB is applied to $SB$ as described above. Otherwise, $SB$ is
created from $S$ and has its sagbiDone flag set to true.

Note, if the generators supplied to forceSB do not form a sagbi basis, then it
may cause unexpected behaviour.

See also
========

  * Subring -- The type of all subrings
  * SAGBIBasis -- The type of all sagbi bases

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

  * "forceSB(SAGBIBasis)"
  * "forceSB(Subring)"

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

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

generators(SAGBIBasis) -- Returns a partial sagbi generating set
****************************************************************

Synopsis
========

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

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

Returns the current list of sagbiGenerators of the underlying Subring.
If the SAGBIBasis, is not a complete sagbi basis
(for example it is 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                       |
| -- 0.000093183 seconds elapsed      |
| -- 0.000117587 seconds elapsed      |
| -- 0.000106671 seconds elapsed      |
| -- 0.000048856 seconds elapsed      |
| -- 0.000114965 seconds elapsed      |
| -- 0.00009772 seconds elapsed       |
| -- 0.000047974 seconds elapsed      |
| -- 0.000104052 seconds elapsed      |
| -- 0.000097119 seconds elapsed      |
| -- 0.000092775 seconds elapsed      |
| -- 0.000112542 seconds elapsed      |
| -- 0.000094903 seconds elapsed      |
| -- 0.000049476 seconds elapsed      |
| -- 0.000112969 seconds elapsed      |
| -- 0.000096343 seconds elapsed      |
| -- 0.000050754 seconds elapsed      |
| -- 0.000113458 seconds elapsed      |
| -- 0.000101306 seconds elapsed      |
| -- 0.000051107 seconds elapsed      |
| -- 0.000134027 seconds elapsed      |
| -- 0.00013686 seconds elapsed       |
| -- 0.000050874 seconds elapsed      |
| -- 0.000134576 seconds elapsed      |
| -- 0.000143996 seconds elapsed      |
|timing raw subduction                |
|timing raw subduction                |
|timing raw subduction                |
|timing raw subduction                |
|timing raw subduction                |
|timing raw subduction                |
|timing raw subduction                |
|timing raw subduction                |
|                                     |
|o6 = true                            |
+-------------------------------------+
|i7 : isSAGBI SB                      |
|                                     |
|o7 = false                           |
+-------------------------------------+

See also
========

  * SAGBIBasis -- The type of all sagbi bases
  * generators(SAGBIBasis) -- Returns a
    partial sagbi generating set
  * 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 sagbi
    basis computation object
  * status(SAGBIBasis) -- status of the sagbi
    computation
  * sagbiDegree -- The current degree of the sagbi
    computation
  * sagbiLimit -- The current limit of the sagbi computation
  * sagbi -- Compute a subalgebra basis (sagbi basis)

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

  * generators(SAGBIBasis) -- Returns a
    partial sagbi generating set

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

Synopsis
========

  * Function: generators (Macaulay2Doc),
  * Usage:
        result = gens S
  * Inputs:
      * S, an instance of the type Subring,
  * Optional inputs (Macaulay2Doc),:
      * CoefficientRing (Macaulay2Doc), => ...,
        default value null, null
  * 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(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

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

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

GeneratorSymbol -- variables for the subductionQuotientRing
***********************************************************

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

A symbol to be used for variables of the subductionQuotientRing

+-------------------------------------------------------+
|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                                           |
+-------------------------------------------------------+

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(Subring) -- Short summary 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).

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

Synopsis
========

  * Usage:
        result = groebnerMembershipTest(f, S)
  * Inputs:
      * f, a ring element (Macaulay2Doc),
      * S, an instance of the type Subring,
  * Outputs:
      * result, a Boolean value (Macaulay2Doc), f belongs to S.

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

Uses the extrinsic method to test membership of a polynomial in a subring. Note
that S must be a subring of a polynomial ring.

+----------------------------------+
|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 sagbi basis is known for S then it is recommended to use RingElement % Subring.

See also
========

  * Subring -- The type of all subrings
  * RingElement % Subring -- Remainder modulo a
    subring
  * groebnerSubductionQuotient -- Extrinsic
    method for subduction quotients
  * RingElement // Subring -- subductionQuotient
    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).

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

Synopsis
========

  * Usage:
        result = groebnerSubductionQuotient(f, S)
  * Inputs:
      * f, a ring element (Macaulay2Doc),
      * S, an instance of the type Subring,
  * Outputs:
      * result, a ring element (Macaulay2Doc),

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
subductionQuotientRing. 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$.

+-----------------------------------------+
|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 : h = groebnerSubductionQuotient(f, S)|
|                                         |
|      3                                  |
|o5 = p  - 2p p  + p                      |
|      0     0 1    2                     |
|                                         |
|o5 : QQ[p ..p ]                          |
|         0   2                           |
+-----------------------------------------+

See also
========

  * Subring -- The type of all subrings
  * RingElement % Subring -- Remainder modulo a
    subring
  * RingElement // Subring -- subductionQuotient
    with respect to a subring
  * sagbi -- Compute a subalgebra basis (sagbi basis)

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

  * "groebnerSubductionQuotient(RingElement,Subring)"

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

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

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

Synopsis
========

  * Usage:
        result = isSAGBI S
        result = isSAGBI SB
        result = isSAGBI M
        result = isSAGBI L
  * Inputs:
      * S, an instance of the type Subring,
      * SB, an instance of the type SAGBIBasis,
      * M, a matrix (Macaulay2Doc),
      * L, a list (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * Compute => ..., default value true
      * Limit => ..., default value 0
      * PrintLevel => ..., default value 0
      * Recompute => ..., default value false
      * RenewOptions => ..., default value false
      * Strategy => ..., default value "Master"
      * SubductionMethod => ..., default value "Top"
      * UseSubringGens => ..., default value false
  * Outputs:
      * result, a Boolean value (Macaulay2Doc),

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

This checks whether the generators of a subring or the sagbi generators of a
computation object form a sagbi basis. After running sagbi on a subring, note
that the result of the computation is stored in that subring. If new sagbi
generators need to be added to S to make it a sagbi basis then isSAGBI will
return false. If isSAGBI is run on a ring for which no sagbi computation has
been performed, then isSAGBI will perform a test to see if the generators form
a sagbi basis. This test can be skipped by setting Compute, to
false, and, in that case, isSAGBI will return null.

+------------------------------------------------------------------------+
|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 : sagbi(S, Limit => 5)                                               |
|                                                                        |
|o4 = Partial SAGBIBasis Computation Object with 6 generators, Limit = 5.|
|                                                                        |
|o4 : SAGBIBasis                                                         |
+------------------------------------------------------------------------+
|i5 : isSAGBI S                                                          |
| -- 0.000094081 seconds elapsed                                         |
| -- 0.000124904 seconds elapsed                                         |
| -- 0.000114313 seconds elapsed                                         |
| -- 0.000052377 seconds elapsed                                         |
| -- 0.000117722 seconds elapsed                                         |
| -- 0.000107853 seconds elapsed                                         |
| -- 0.000050307 seconds elapsed                                         |
| -- 0.000115539 seconds elapsed                                         |
| -- 0.000105831 seconds elapsed                                         |
| -- 0.00005082 seconds elapsed                                          |
| -- 0.000110718 seconds elapsed                                         |
| -- 0.000115673 seconds elapsed                                         |
| -- 0.000093212 seconds elapsed                                         |
| -- 0.000252348 seconds elapsed                                         |
| -- 0.000120125 seconds elapsed                                         |
| -- 0.000050666 seconds elapsed                                         |
| -- 0.00026758 seconds elapsed                                          |
| -- 0.000121486 seconds elapsed                                         |
| -- 0.000050136 seconds elapsed                                         |
| -- 0.000231321 seconds elapsed                                         |
| -- 0.000120993 seconds elapsed                                         |
| -- 0.000051195 seconds elapsed                                         |
| -- 0.000333113 seconds elapsed                                         |
| -- 0.000127337 seconds elapsed                                         |
| -- 0.000048115 seconds elapsed                                         |
| -- 0.00018967 seconds elapsed                                          |
| -- 0.000119057 seconds elapsed                                         |
| -- 0.000047982 seconds elapsed                                         |
| -- 0.000215413 seconds elapsed                                         |
| -- 0.000120307 seconds elapsed                                         |
| -- 0.000049675 seconds elapsed                                         |
| -- 0.000293064 seconds elapsed                                         |
| -- 0.000172552 seconds elapsed                                         |
| -- 0.000049817 seconds elapsed                                         |
| -- 0.000105189 seconds elapsed                                         |
| -- 0.000157736 seconds elapsed                                         |
|timing raw subduction                                                   |
|timing raw subduction                                                   |
|timing raw subduction                                                   |
|timing raw subduction                                                   |
|timing raw subduction                                                   |
|timing raw subduction                                                   |
|timing raw subduction                                                   |
|timing raw subduction                                                   |
|timing raw subduction                                                   |
|timing raw subduction                                                   |
|timing raw subduction                                                   |
|timing raw subduction                                                   |
|                                                                        |
|o5 = false                                                              |
+------------------------------------------------------------------------+
|i6 : S' = subring {x+y+z,x*y+x*z+y*z, x*y*z};                           |
+------------------------------------------------------------------------+
|i7 : isSAGBI S'                                                         |
|                                                                        |
|o7 = true                                                               |
+------------------------------------------------------------------------+
|i8 : sagbi(S', Limit => 5)                                              |
|                                                                        |
|o8 = SAGBIBasis Computation Object with 3 generators, Limit = 5.        |
|                                                                        |
|o8 : SAGBIBasis                                                         |
+------------------------------------------------------------------------+
|i9 : isSAGBI S'                                                         |
| -- 0.000091293 seconds elapsed                                         |
| -- 0.00010138 seconds elapsed                                          |
| -- 0.000099073 seconds elapsed                                         |
| -- 0.000048959 seconds elapsed                                         |
| -- 0.000100928 seconds elapsed                                         |
| -- 0.000174954 seconds elapsed                                         |
| -- 0.000051615 seconds elapsed                                         |
| -- 0.000105341 seconds elapsed                                         |
| -- 0.00010077 seconds elapsed                                          |
| -- 0.000092408 seconds elapsed                                         |
| -- 0.000100495 seconds elapsed                                         |
| -- 0.000099153 seconds elapsed                                         |
| -- 0.000048981 seconds elapsed                                         |
| -- 0.000099816 seconds elapsed                                         |
| -- 0.000102604 seconds elapsed                                         |
| -- 0.000053163 seconds elapsed                                         |
| -- 0.000117554 seconds elapsed                                         |
| -- 0.000099387 seconds elapsed                                         |
| -- 0.000050658 seconds elapsed                                         |
| -- 0.000108704 seconds elapsed                                         |
| -- 0.000141587 seconds elapsed                                         |
| -- 0.000051386 seconds elapsed                                         |
| -- 0.000111036 seconds elapsed                                         |
| -- 0.000145262 seconds elapsed                                         |
|timing raw subduction                                                   |
|timing raw subduction                                                   |
|timing raw subduction                                                   |
|timing raw subduction                                                   |
|timing raw subduction                                                   |
|timing raw subduction                                                   |
|timing raw subduction                                                   |
|timing raw subduction                                                   |
|                                                                        |
|o9 = true                                                               |
+------------------------------------------------------------------------+

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

A note of caution. Excessive use of isSAGBI may impact performance. The inputs
and outputs of isSAGBI are stored and never deleted. Since the inputs and
outputs include pointers objects such as SAGBIBasis,
computation objects, these objects will not be garbage collected.

See also
========

  * SAGBIBasis -- The type of all sagbi bases
  * generators(SAGBIBasis) -- Returns a
    partial sagbi generating set
  * 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 sagbi
    basis computation object
  * sagbi -- Compute a subalgebra basis (sagbi basis)

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

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

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

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

Limit -- Degree limit for the Sagbi algorithm
*********************************************

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

The stopping criteria for the main loop in sagbi, are: a finite
sagbi basis is computed, or the smallest degree of an S-pair exceeds the
Limit (Macaulay2Doc). In general, the initial terms of generators of a
partial computation do not generate the initial algebra up to the degree limit.
It is possible that, with a higher degree limit, sagbi generators of lower
degree will be added. One can guarantee that all sagbi generators up to a
certain degree are found by using a graded term-order such as GRevLex and
working with a subring or a polynomial ring (and not a quotient ring).

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
  * Strategy (Macaulay2Doc) -- an optional argument
  * SubductionMethod -- Subduction method for the
    Sagbi algorithm
  * Limit (Macaulay2Doc) -- an optional argument
  * AutoSubduceOnPartialCompletion, --
    Subduct sagbi generators at the end of the Sagbi algorithm
  * PrintLevel -- Levels of information displayed during
    Sagbi algorithm
  * Recompute -- Flag for restarting a sagbi computation
  * RenewOptions -- Flag for reselecting the options for a
    sagbi computation

Functions with optional argument named Limit :
==============================================

  * "basis(...,Limit=>...)" -- see basis (Macaulay2Doc), -- basis
    or generating set of all or part of a ring, ideal or module
  * "forceSB(...,Limit=>...)" -- see forceSB, -- declare the
    generators of a subring or SAGBIBasis to be a complete sagbi basis
  * hermite(...,Limit=>...) (missing documentation)
  * icFracP(...,Limit=>...) (IntegralClosure)
    -- Limits the
    number of computed intermediate modules.
  * "independentSets(...,Limit=>...)" -- see independentSets (Macaulay2Doc),
    -- some size-maximal independent subsets of
    variables modulo an ideal
  * integralClosure(...,Limit=>...) (IntegralClosure)
    -- do a
    partial integral closure
  * "isSAGBI(...,Limit=>...)" -- see isSAGBI, -- Check if the
    generators are a sagbi basis
  * kernelLLL(...,Limit=>...) (missing documentation)
  * LLL(...,Limit=>...) (missing documentation)
  * "minors(...,Limit=>...)" -- see minors(ZZ,Matrix) (Macaulay2Doc),
    -- ideal generated by minors
  * "oeis(...,Limit=>...)" -- see oeis (OnlineLookup), -- OEIS
    lookup
  * "sagbi(...,Limit=>...)" -- see sagbi, -- Compute a subalgebra
    basis (sagbi basis)
  * "sagbiBasis(...,Limit=>...)" -- see sagbiBasis, --
    Constructs a computation object from a subring.
  * "simpleDocFrob(...,Limit=>...)" -- see simpleDocFrob (SimpleDoc),
    -- a sample documentation node
  * "subalgebraBasis(...,Limit=>...)" -- see subalgebraBasis,
    -- Compute subalgebra basis (sagbi basis) generators
  * "subduction(...,Limit=>...)" -- see subduction, --
    Subduction of polynomials
  * "subringIntersection(...,Limit=>...)" -- see subringIntersection,
    -- Intersection of subrings

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

The object Limit (Macaulay2Doc), is a symbol (Macaulay2Doc).

Matrix % SAGBIBasis -- Remainder modulo a subring
*************************************************

Synopsis
========

  * Operator: % (Macaulay2Doc),
  * Usage:
        R = M % SB
  * Inputs:
      * M, a matrix (Macaulay2Doc),
      * SB, an instance of the type SAGBIBasis,
  * Outputs:
      * R, a matrix (Macaulay2Doc), the normal form of entries of
        M modulo the subring

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

Subducts M entry-wise against the sagbi generators of SB.

See also
========

  * 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 sagbi bases
  * groebnerMembershipTest -- Extrinsic method
    for subring membership

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

  * Matrix % SAGBIBasis -- Remainder modulo a
    subring

Matrix % Subring -- Remainder modulo a subring
**********************************************

Synopsis
========

  * Operator: % (Macaulay2Doc),
  * Usage:
        R = M % S
  * Inputs:
      * M, a matrix (Macaulay2Doc),
      * S, an instance of the type Subring,
  * Outputs:
      * R, a matrix (Macaulay2Doc), the normal form of entries of
        M modulo the subring

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

Applies RingElement % Subring, entry-wise to M.

See also
========

  * 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 sagbi bases
  * groebnerMembershipTest -- Extrinsic method
    for subring membership

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

  * Matrix % Subring -- Remainder modulo a subring

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

Synopsis
========

  * Function: net (Macaulay2Doc),
  * Usage:
        net S
  * Inputs:
      * S, an instance of the type SAGBIBasis,
  * Outputs:
      * a net (Macaulay2Doc),

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

Displays the number of sagbi generators of a S along with the degree limit.

See also
========

  * SAGBIBasis -- The type of all sagbi bases
  * generators(SAGBIBasis) -- Returns a
    partial sagbi generating set
  * 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 sagbi
    basis computation object
  * status(SAGBIBasis) -- status of the sagbi
    computation
  * sagbiDegree -- The current degree of the sagbi
    computation
  * sagbiLimit -- The current limit of the sagbi computation
  * sagbi -- Compute a subalgebra basis (sagbi basis)

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

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

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

Synopsis
========

  * Function: net (Macaulay2Doc),
  * Usage:
        net S
  * Inputs:
      * S, an instance of the type Subring,
  * Outputs:
      * a net (Macaulay2Doc),

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

Displays the ambient ring and number of generators of a 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(Subring) -- Short summary of a subring

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

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

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

Synopsis
========

  * Function: numgens (Macaulay2Doc),
  * Usage:
        result = numgens SB
  * Inputs:
      * SB, an instance of the type SAGBIBasis,
  * Outputs:
      * result, an integer (Macaulay2Doc),

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

Returns the number of sagbi 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 sagbi bases
  * sagbiBasis -- Constructs a computation object from a
    subring.
  * 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

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

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

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

Synopsis
========

  * Function: numgens (Macaulay2Doc),
  * Usage:
        result = numgens S
  * Inputs:
      * S, an instance of the type Subring,
  * Outputs:
      * result, an integer (Macaulay2Doc),

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(Subring) -- The number of generators
    of a subring
  * numgens(SAGBIBasis) -- The number of
    generators of a SAGBIBasis
  * net(Subring) -- Short summary of a subring

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

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

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

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

PrintLevel 0: no output

PrintLevel 1+: some basic information each loop (no polynomials): computation
degree, number of S-pairs, number of new generators, termination conditions.

PrintLevel 2+: basic polynomials: S-pairs and new sagbi generators

PrintLevel 3+: extra polynomials: reduction ideal generators, zeroGens, current
sagbi generators

PrintLevel 4+: show the input and output of each subduction

Higher levels exist but may be overly verbose. PrintLevel 5 shows the
processPending data and PrintLevel 6 shows 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
  * Strategy (Macaulay2Doc) -- an optional argument
  * SubductionMethod -- Subduction method for the
    Sagbi algorithm
  * Limit (Macaulay2Doc) -- an optional argument
  * AutoSubduceOnPartialCompletion, --
    Subduct sagbi generators at the end of the Sagbi algorithm
  * PrintLevel -- Levels of information displayed during
    Sagbi algorithm
  * Recompute -- Flag for restarting a sagbi computation
  * RenewOptions -- Flag for reselecting the options for a
    sagbi computation

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

  * "forceSB(...,PrintLevel=>...)" -- see forceSB, -- declare
    the generators of a subring or SAGBIBasis to be a complete sagbi basis
  * "isSAGBI(...,PrintLevel=>...)" -- see isSAGBI, -- Check if
    the generators are a sagbi basis
  * "sagbi(...,PrintLevel=>...)" -- see sagbi, -- Compute a
    subalgebra basis (sagbi basis)
  * "sagbiBasis(...,PrintLevel=>...)" -- see sagbiBasis, --
    Constructs a computation object from a subring.
  * "subalgebraBasis(...,PrintLevel=>...)" -- see subalgebraBasis,
    -- Compute subalgebra basis (sagbi basis) generators
  * "subduction(...,PrintLevel=>...)" -- see subduction, --
    Subduction of polynomials
  * "subringIntersection(...,PrintLevel=>...)" -- see
    subringIntersection, -- Intersection of subrings

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

The object PrintLevel, is a symbol (Macaulay2Doc).

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

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

If the flag is set to true, then the sagbi computation will start from scratch.
This process constructs a new computation object and uses the computation
options from the previous computation.

See also
========

  * sagbi -- Compute a subalgebra basis (sagbi basis)
  * subalgebraBasis -- Compute subalgebra basis (sagbi
    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
  * Strategy (Macaulay2Doc) -- an optional argument
  * SubductionMethod -- Subduction method for the
    Sagbi algorithm
  * Limit (Macaulay2Doc) -- an optional argument
  * AutoSubduceOnPartialCompletion, --
    Subduct sagbi generators at the end of the Sagbi algorithm
  * PrintLevel -- Levels of information displayed during
    Sagbi algorithm
  * RenewOptions -- Flag for reselecting the options for a
    sagbi computation

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

  * "isSAGBI(...,Recompute=>...)" -- see isSAGBI, -- Check if
    the generators are a sagbi basis
  * "sagbi(...,Recompute=>...)" -- see sagbi, -- Compute a
    subalgebra basis (sagbi basis)
  * "sagbiBasis(...,Recompute=>...)" -- see sagbiBasis, --
    Constructs a computation object from a subring.
  * "subalgebraBasis(...,Recompute=>...)" -- see subalgebraBasis,
    -- Compute subalgebra basis (sagbi basis) generators
  * "subduction(...,Recompute=>...)" -- see subduction, --
    Subduction of polynomials

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

The object Recompute, is a symbol (Macaulay2Doc).

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

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

The function sagbi, computes a sagbi basis by subducting S-pairs.
Any resulting non-zero polynomials are added to the list of sagbi generators.
However if ReduceNewGenerators is set to true (by default) then the new
generators are reduced using gaussian elimination against the other new
generators. This process is quick (as fast as computing a groebner basis for a
linear ideal) and ensures that duplicate generators are not added to the list
of sagbi generators.

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
  * Strategy (Macaulay2Doc) -- an optional argument
  * SubductionMethod -- Subduction method for the
    Sagbi algorithm
  * Limit (Macaulay2Doc) -- an optional argument
  * AutoSubduceOnPartialCompletion, --
    Subduct sagbi generators at the end of the Sagbi algorithm
  * PrintLevel -- Levels of information displayed during
    Sagbi algorithm
  * Recompute -- Flag for restarting a sagbi computation
  * RenewOptions -- Flag for reselecting the options for a
    sagbi computation

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

  * "sagbi(...,ReduceNewGenerators=>...)" -- see sagbi, -- Compute
    a subalgebra basis (sagbi basis)
  * "sagbiBasis(...,ReduceNewGenerators=>...)" -- see sagbiBasis,
    -- Constructs a computation object from a subring.
  * "subalgebraBasis(...,ReduceNewGenerators=>...)" -- see
    subalgebraBasis, -- Compute subalgebra basis (sagbi basis)
    generators
  * "subduction(...,ReduceNewGenerators=>...)" -- see subduction,
    -- Subduction of polynomials

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

The object ReduceNewGenerators, is a symbol (Macaulay2Doc).

RenewOptions -- Flag for reselecting the options for a sagbi computation
************************************************************************

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

When a sagbi 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 (Macaulay2Doc),
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)
  * 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
  * Strategy (Macaulay2Doc) -- an optional argument
  * SubductionMethod -- Subduction method for the
    Sagbi algorithm
  * Limit (Macaulay2Doc) -- an optional argument
  * AutoSubduceOnPartialCompletion, --
    Subduct sagbi generators at the end of the Sagbi algorithm
  * PrintLevel -- Levels of information displayed during
    Sagbi algorithm
  * Recompute -- Flag for restarting a sagbi computation

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

  * "forceSB(...,RenewOptions=>...)" -- see forceSB, -- declare
    the generators of a subring or SAGBIBasis to be a complete sagbi basis
  * "isSAGBI(...,RenewOptions=>...)" -- see isSAGBI, -- Check if
    the generators are a sagbi basis
  * "sagbi(...,RenewOptions=>...)" -- see sagbi, -- Compute a
    subalgebra basis (sagbi basis)
  * "sagbiBasis(...,RenewOptions=>...)" -- see sagbiBasis, --
    Constructs a computation object from a subring.
  * "subalgebraBasis(...,RenewOptions=>...)" -- see subalgebraBasis,
    -- Compute subalgebra basis (sagbi basis) generators
  * "subduction(...,RenewOptions=>...)" -- see subduction, --
    Subduction of polynomials

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

The object RenewOptions, is a symbol (Macaulay2Doc).

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

Synopsis
========

  * Function: ring (Macaulay2Doc),
  * Usage:
        result = ring S
  * Inputs:
      * S, an instance of the type SAGBIBasis,
  * Outputs:
      * result, a ring (Macaulay2Doc),

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

Returns the lifted ring of S. This is always a PolynomialRing.

+------------------------------------------------------------------+
|i1 : R = QQ[x,y,z];                                               |
+------------------------------------------------------------------+
|i2 : S = sagbi {x^2, y^2, z^2}                                    |
|                                                                  |
|o2 = SAGBIBasis Computation Object with 3 generators, Limit = 100.|
|                                                                  |
|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 = 100.|
|                                                                  |
|o5 : SAGBIBasis                                                   |
+------------------------------------------------------------------+
|i6 : ring S'                                                      |
|                                                                  |
|o6 = R                                                            |
|                                                                  |
|o6 : PolynomialRing                                               |
+------------------------------------------------------------------+

See also
========

  * SAGBIBasis -- The type of all sagbi bases
  * generators(SAGBIBasis) -- Returns a
    partial sagbi generating set
  * 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 sagbi
    basis computation object
  * status(SAGBIBasis) -- status of the sagbi
    computation
  * sagbiDegree -- The current degree of the sagbi
    computation
  * sagbiLimit -- The current limit of the sagbi computation
  * sagbi -- Compute a subalgebra basis (sagbi basis)

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

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

RingElement % SAGBIBasis -- Remainder modulo a subring
******************************************************

Synopsis
========

  * Operator: % (Macaulay2Doc),
  * Usage:
        r = f % SB
  * Inputs:
      * f, a ring element (Macaulay2Doc),
      * SB, an instance of the type SAGBIBasis,
  * Outputs:
      * r, a ring element (Macaulay2Doc), the normal form of
        f modulo the subring

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

Subducts f against the sagbi generators of SB.

See also
========

  * 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 sagbi bases
  * groebnerMembershipTest -- Extrinsic method
    for subring membership

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

  * RingElement % SAGBIBasis -- Remainder
    modulo a subring

RingElement % Subring -- Remainder modulo a subring
***************************************************

Synopsis
========

  * Operator: % (Macaulay2Doc),
  * Usage:
        r = f % S
  * Inputs:
      * f, a ring element (Macaulay2Doc),
      * S, an instance of the type Subring,
  * Outputs:
      * r, a ring element (Macaulay2Doc), the normal form of
        f modulo the subring

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

The result is zero if and only if the input belongs to the subring. If a sagbi
basis is known for the subring then subduction is used to compute the normal
forms. If no sagbi 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)} --usual invariants of A_3                           |
+-----------------------------------------------------------------------------+
|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
========

  * 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 sagbi bases
  * groebnerMembershipTest -- Extrinsic method
    for subring membership

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

  * RingElement % Subring -- Remainder modulo a
    subring

RingElement // Subring -- subductionQuotient with respect to a subring
**********************************************************************

Synopsis
========

  * Operator: // (Macaulay2Doc),
  * Usage:
        r = f // S
  * Inputs:
      * f, a ring element (Macaulay2Doc),
      * S, an instance of the type Subring,
  * Outputs:
      * r, a ring element (Macaulay2Doc), a
        subductionQuotient of f with respect to the subring

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

The result is a ring element that lies in the subductionQuotientRing that has
one variable for generator of the subring $S$. A subduction quotient can be
thought of as an expression of $f - (f\%S) \in S$ in terms of the generators of
$S$. This function is equivalent to 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 sagbi bases
  * groebnerMembershipTest -- Extrinsic method
    for subring membership

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

  * RingElement // Subring -- subductionQuotient
    with respect to a subring

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

Synopsis
========

  * Usage:
        N = sagbi M
        N = sagbi A
        N = sagbi L
        N = sagbi B
  * Inputs:
      * A, an instance of the type 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, an instance of the type SAGBIBasis, containing a
        partial computation of a sagbi 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 Sagbi basis computation (See:
        AutoSubduce)
      * ReduceNewGenerators => a Boolean value (Macaulay2Doc),
        default value true, a flag indicating whether to apply gaussian
        elimination to new sagbi generators before adding them to the current
        sagbi basis (See: ReduceNewGenerators)
      * StorePending => a Boolean value (Macaulay2Doc), default
        value true, a flag that indicates whether the pending list should be
        stored in the result. (See: StorePending)
      * 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 that combines the other two; starting with
        \"DegreeByDegree\" for low degrees and switching to \"Incremental\".
        (See: Strategy (Macaulay2Doc))
      * SubductionMethod => a string (Macaulay2Doc), default
        value "Top", the method used for subduction either: \"Top\" or
        \"Engine\". (See: SubductionMethod)
      * Limit => an integer (Macaulay2Doc), default value 100, a
        degree limit for the binomial S-pairs that are computed internally.
      * AutoSubduceOnPartialCompletion => a Boolean value (Macaulay2Doc),
        default value false, apply autosubduction to
        the sagbi generators the first time no new generators are added. Use
        this only if very few new sagbi generators are expected. (See:
        AutoSubduceOnPartialCompletion)
      * PrintLevel => an integer (Macaulay2Doc), default value 0,
        When this is greater than zero, information is printed about the
        progress of the computation (See: PrintLevel)
      * 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 will use the options
        specified otherwise it will use the previously selected options (except
        for the following, which may always be specified: PrintLevel,
        see Limit (Macaulay2Doc), Recompute,
        and RenewOptions)
  * Outputs:
      * N, an instance of the type SAGBIBasis, a computation
        object holding the state of the sagbi 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 (sagbi
    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
  * Strategy (Macaulay2Doc) -- an optional argument
  * SubductionMethod -- Subduction method for the
    Sagbi algorithm
  * Limit (Macaulay2Doc) -- an optional argument
  * AutoSubduceOnPartialCompletion, --
    Subduct sagbi generators at the end of the Sagbi algorithm
  * PrintLevel -- Levels of information displayed during
    Sagbi algorithm
  * Recompute -- Flag for restarting a sagbi computation
  * RenewOptions -- Flag for reselecting the options for a
    sagbi 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).

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

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

This is a computation object for sagbi bases. It stores a partial sagbi
computation for picking up a computation where it left off. An instance of a
SAGBIBasis is constructed with the function sagbiBasis, and
as the output of sagbi.

Every instance of SAGBIBasis contains the following hashtables:

  * SAGBIdata: contains parameters for the sagbi computation
  *   degree: current degree of the S-pairs in the sagbi algorithm.
  *   limit: degree limit of the computation.
  *   sagbiGenerators: generators in the sagbi basis (default none)
  *   subalgebraGenerators: original generating set of the subring.
  * SAGBIideals
  *   I: the ideal defining the ambient ring = liftedRing / I
  *   leadTermsI: initial ideal of I
  *   reductionIdeal: SIdeal+I lifted to the tensorRing
  *   SIdeal: ideal generated by (SagbiGenerators - TagVariables)
  * SAGBIrings
  *   liftedRing: the polynomial ring of the quotient ring
  *   quotientRing: ambient ring of the underlying subring
  *   tensorRing: tensor product of the liftedRing with a polynomial ring that
    has one variable for each sagbi generator
  * SAGBImaps: a collection of useful maps between the 'rings'
  * SAGBIoptions: supplied options for the sagbi computation
  * SAGBIpending: newly computed sagbi generators before they are added to the
    sagbiGenerators in 'data'

See also
========

  * sagbiBasis -- Constructs a computation object from a
    subring.
  * Subring -- The type of all subrings
  * sagbi -- Compute a subalgebra basis (sagbi basis)

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

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

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

  * ambient(SAGBIBasis) -- The ambient ring of
    a SAGBIBasis computation object
  * "forceSB(SAGBIBasis)" -- see forceSB, -- declare the
    generators of a subring or SAGBIBasis to be a complete sagbi basis
  * generators(SAGBIBasis) -- Returns a
    partial sagbi generating set
  * "isSAGBI(SAGBIBasis)" -- see isSAGBI, -- Check if the
    generators are a sagbi basis
  * Matrix % SAGBIBasis -- Remainder modulo a
    subring
  * net(SAGBIBasis) -- Short summary of a sagbi
    basis computation object
  * numgens(SAGBIBasis) -- The number of
    generators of a SAGBIBasis
  * ring(SAGBIBasis) -- The lifted ring of a
    SAGBIBasis computation object
  * RingElement % SAGBIBasis -- Remainder
    modulo a subring
  * "sagbi(SAGBIBasis)" -- see sagbi, -- Compute a subalgebra
    basis (sagbi basis)
  * "sagbiDegree(SAGBIBasis)" -- see sagbiDegree, -- The
    current degree of the sagbi computation
  * "sagbiLimit(SAGBIBasis)" -- see sagbiLimit, -- The
    current limit of the sagbi computation
  * "sagbiStatus(SAGBIBasis)" -- see sagbiStatus, -- returns
    if the sagbi computation is done
  * status(SAGBIBasis) -- status of the sagbi
    computation
  * "subduction(SAGBIBasis,Matrix)" -- see subduction, --
    Subduction of polynomials
  * "subduction(SAGBIBasis,RingElement)" -- see subduction,
    -- Subduction of polynomials
  * "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).

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

Synopsis
========

  * Usage:
        B = sagbiBasis S
  * Inputs:
      * S, an instance of the type Subring,
  * Optional inputs (Macaulay2Doc),:
      * AutoSubduce => ..., default value true
      * AutoSubduceOnPartialCompletion => ..., default value false
      * Limit => ..., default value 100
      * PrintLevel => ..., default value 0
      * Recompute => ..., default value false
      * ReduceNewGenerators => ..., default value true
      * RenewOptions => ..., default value false
      * StorePending => ..., default value true
      * Strategy => ..., default value "Master"
      * SubductionMethod => ..., default value "Top"
  * Outputs:
      * B, an instance of the type SAGBIBasis,

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

This function serves as the canonical constructor for the SAGBIBasis,
type. It is also the output of the sagbi, function. A
SAGBIBasis, may be cast to a Subring, using
subring.

See also
========

  * SAGBIBasis -- The type of all sagbi bases
  * generators(SAGBIBasis) -- Returns a
    partial sagbi generating set
  * 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 sagbi
    basis computation object
  * status(SAGBIBasis) -- status of the sagbi
    computation
  * sagbiDegree -- The current degree of the sagbi
    computation
  * sagbiLimit -- The current limit of the sagbi computation
  * sagbi -- Compute a subalgebra basis (sagbi basis)

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

  * "sagbiBasis(HashTable)"
  * "sagbiBasis(Subring)"

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

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

sagbiDegree -- The current degree of the sagbi computation
**********************************************************

Synopsis
========

  * Usage:
        result = sagbiDegree SB
  * Inputs:
      * SB, an instance of the type SAGBIBasis,
  * Outputs:
      * result, an integer (Macaulay2Doc),

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

Returns the current degree of the sagbi computation. When the computation is
resumed (without restarting) then the algorithm will pick up at this degree.
Note that the degree may drop during the computation.

See also
========

  * SAGBIBasis -- The type of all sagbi bases
  * generators(SAGBIBasis) -- Returns a
    partial sagbi generating set
  * 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 sagbi
    basis computation object
  * status(SAGBIBasis) -- status of the sagbi
    computation
  * sagbiLimit -- The current limit of the sagbi 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).

sagbiLimit -- The current limit of the sagbi computation
********************************************************

Synopsis
========

  * Usage:
        result = sagbiLimit SB
  * Inputs:
      * SB, an instance of the type SAGBIBasis,
  * Outputs:
      * result, an integer (Macaulay2Doc),

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

Returns the current limit of the sagbi computation. When the computation is
resumed then this limit will be set to the new specified limit.

See also
========

  * SAGBIBasis -- The type of all sagbi bases
  * generators(SAGBIBasis) -- Returns a
    partial sagbi generating set
  * 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 sagbi
    basis computation object
  * status(SAGBIBasis) -- status of the sagbi
    computation
  * sagbiDegree -- The current degree of the sagbi
    computation
  * sagbi -- Compute a subalgebra basis (sagbi basis)
  * Limit (Macaulay2Doc) -- an optional argument

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

  * "sagbiLimit(SAGBIBasis)"

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

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

sagbiStatus -- returns if the sagbi computation is done
*******************************************************

Synopsis
========

  * Usage:
        result = sagbiStatus SB
  * Inputs:
      * SB, an instance of the type SAGBIBasis,
  * Outputs:
      * result, a Boolean value (Macaulay2Doc),

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

Returns true if the sagbi computation is completed otherwise returns false.

See also
========

  * SAGBIBasis -- The type of all sagbi bases
  * generators(SAGBIBasis) -- Returns a
    partial sagbi generating set
  * 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 sagbi
    basis computation object
  * status(SAGBIBasis) -- status of the sagbi
    computation
  * sagbiDegree -- The current degree of the sagbi
    computation
  * sagbiLimit -- The current limit of the sagbi 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).

status(SAGBIBasis) -- status of the sagbi computation
*****************************************************

Synopsis
========

  * Function: status (Macaulay2Doc),
  * Usage:
        result = status SB
  * Inputs:
      * SB, an instance of the type SAGBIBasis,
  * Optional inputs (Macaulay2Doc),:
      * Monomials (Macaulay2Doc), => ..., default value false,
        null
      * PairsRemaining (Macaulay2Doc), => ..., default value
        false, null
      * TotalPairs (Macaulay2Doc), => ..., default value true,
        null
  * Outputs:
      * result, a string (Macaulay2Doc),

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

Returns a string with the status of sagbi computation.

See also
========

  * SAGBIBasis -- The type of all sagbi bases
  * generators(SAGBIBasis) -- Returns a
    partial sagbi generating set
  * 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 sagbi
    basis computation object
  * sagbiDegree -- The current degree of the sagbi
    computation
  * sagbiLimit -- The current limit of the sagbi computation
  * sagbi -- Compute a subalgebra basis (sagbi basis)

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

  * status(SAGBIBasis) -- status of the sagbi
    computation

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

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

The function sagbi, produces a SAGBIBasis,
computation object. If the StorePending flag is true then the output will
contain a copy of the pending list. The pending list contains all S-pairs
grouped by their degrees. If the Sagbi algorithm terminates without producing a
complete sagbi basis, for example due to Limit (Macaulay2Doc),
then the computation may be resumed by calling sagbi, on the
resulting computation object with new options. The resumed computation will use
the pending list stored in the SAGBIBasis, computation
object. If there is no pending list in the computation object then one will be
created. 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
  * StorePending -- Flag for storing the pending list to
    the result of the Sagbi algorithm
  * Strategy (Macaulay2Doc) -- an optional argument
  * SubductionMethod -- Subduction method for the
    Sagbi algorithm
  * Limit (Macaulay2Doc) -- an optional argument
  * AutoSubduceOnPartialCompletion, --
    Subduct sagbi generators at the end of the Sagbi algorithm
  * PrintLevel -- Levels of information displayed during
    Sagbi algorithm
  * Recompute -- Flag for restarting a sagbi computation
  * RenewOptions -- Flag for reselecting the options for a
    sagbi computation

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

  * "sagbi(...,StorePending=>...)" -- see sagbi, -- Compute a
    subalgebra basis (sagbi basis)
  * "sagbiBasis(...,StorePending=>...)" -- see sagbiBasis, --
    Constructs a computation object from a subring.
  * "subalgebraBasis(...,StorePending=>...)" -- see subalgebraBasis,
    -- Compute subalgebra basis (sagbi basis) generators
  * "subduction(...,StorePending=>...)" -- see subduction, --
    Subduction of polynomials

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

The object StorePending, is a symbol (Macaulay2Doc).

Strategy -- Update procedure for the Sagbi algorithm
****************************************************

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

At the beginning of each loop inside of sagbi, the main
SAGBIBasis, computation object is updated. There are two types of
update procedure; they are selected by setting Strategy to either
\"DegreeByDegree\" or \"Incremental\". The \"DegreeByDegree\" strategy computes
a partial groebner basis of the reduction ideal from scratch. 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
sagbi generators. The \"DegreeByDegree\" strategy is better when many new
generators are added during each loop of the Sagbi algorithm. The
\"Incremental\" strategy is better when there is little change to the number of
sagbi generators. For many examples, it is observed that many new generators
are added at the beginning of sagbi basis computations. Then towards the end of
the computation, there are very few new generators that are added. 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
  * Strategy (Macaulay2Doc) -- an optional argument
  * SubductionMethod -- Subduction method for the
    Sagbi algorithm
  * Limit (Macaulay2Doc) -- an optional argument
  * AutoSubduceOnPartialCompletion, --
    Subduct sagbi generators at the end of the Sagbi algorithm
  * PrintLevel -- Levels of information displayed during
    Sagbi algorithm
  * Recompute -- Flag for restarting a sagbi computation
  * RenewOptions -- Flag for reselecting the options for a
    sagbi computation

Functions with optional argument named Strategy :
=================================================

  * "addHook(...,Strategy=>...)" -- see addHook (Macaulay2Doc),
    -- add a hook function to an object for later processing
  * "annihilator(...,Strategy=>...)" -- see annihilator (Saturation),
    -- the annihilator ideal
  * "associatedPrimes(...,Strategy=>...)" -- see associatedPrimes (PrimaryDecomposition),
    -- find associated primes
  * "basis(...,Strategy=>...)" -- see basis (Macaulay2Doc), --
    basis or generating set of all or part of a ring, ideal or module
  * "mingens(...,Strategy=>...)" -- see Complement (Macaulay2Doc),
    -- a Strategy option value
  * "trim(...,Strategy=>...)" -- see Complement (Macaulay2Doc),
    -- a Strategy option value
  * determinant(...,Strategy=>...) (Macaulay2Doc)
    -- choose
    between Bareiss, Cofactor and Dynamic algorithms
  * "dual(MonomialIdeal,List,Strategy=>...)" -- see
    dual(MonomialIdeal,Strategy=>...) (Macaulay2Doc),
  * "dual(MonomialIdeal,RingElement,Strategy=>...)" -- see
    dual(MonomialIdeal,Strategy=>...) (Macaulay2Doc),
  * dual(MonomialIdeal,Strategy=>...) (Macaulay2Doc)
  * exteriorPower(...,Strategy=>...) (Macaulay2Doc)
    -- choose
    between Bareiss, Cofactor and Dynamic algorithms
  * "forceSB(...,Strategy=>...)" -- see forceSB, -- declare the
    generators of a subring or SAGBIBasis to be a complete sagbi basis
  * "gb(...,Strategy=>...)" -- see gb (Macaulay2Doc), -- compute a
    Gröbner basis
  * gcdLLL(...,Strategy=>...) (missing documentation)
  * "GF(...,Strategy=>...)" -- see GF (Macaulay2Doc), -- make a finite
    field
  * "groebnerBasis(...,Strategy=>...)" -- see groebnerBasis (Macaulay2Doc),
    -- Gröbner basis, as a matrix
  * hermite(...,Strategy=>...) (missing documentation)
  * "hooks(...,Strategy=>...)" -- see hooks (Macaulay2Doc), -- list
    hooks attached to a key
  * "idealizer(...,Strategy=>...)" -- see idealizer (IntegralClosure),
    -- compute Hom(I,I) as a quotient ring
  * integralClosure(...,Strategy=>...) (IntegralClosure),
    --
    control the algorithm used
  * "intersect(Ideal,Ideal,Strategy=>...)" -- see intersect(Ideal,Ideal) (Macaulay2Doc),
    -- compute an intersection of a
    sequence of ideals or modules
  * "intersect(Module,Module,Strategy=>...)" -- see
    intersect(Ideal,Ideal) (Macaulay2Doc), --
    compute an intersection of a sequence of ideals or modules
  * "intersectInP(...,Strategy=>...)" -- see
    intersectInP(...,BasisElementLimit=>...) (ReesAlgebra),
    --
    Option for intersectInP
  * "isPrimary(...,Strategy=>...)" -- see isPrimary (PrimaryDecomposition),
    -- determine whether a submodule is
    primary
  * "isPrime(Ideal,Strategy=>...)" -- see isPrime(Ideal) (MinimalPrimes),
    -- whether an ideal is prime
  * "isSAGBI(...,Strategy=>...)" -- see isSAGBI, -- Check if the
    generators are a sagbi basis
  * LLL(...,Strategy=>...) (LLLBases)
    -- choose among
    different algorithms
  * "localize(...,Strategy=>...)" -- see localize (PrimaryDecomposition),
    -- localize an ideal at a prime ideal
  * "match(...,Strategy=>...)" -- see match (Macaulay2Doc), --
    regular expression matching
  * "decompose(Ideal,Strategy=>...)" -- see minimalPrimes (MinimalPrimes),
    -- minimal primes of an ideal
  * "minimalPrimes(...,Strategy=>...)" -- see minimalPrimes (MinimalPrimes),
    -- minimal primes of an ideal
  * minors(...,Strategy=>...) (Macaulay2Doc)
    -- choose
    between Bareiss, Cofactor and Dynamic algorithms
  * "primaryComponent(...,Strategy=>...)" -- see primaryComponent (PrimaryDecomposition),
    -- find a primary component
    corresponding to an associated prime
  * pushForward(...,Strategy=>...) (missing documentation)
  * quotient(...,Strategy=>...) (Saturation)
  * "radical(...,Strategy=>...)" -- see radical (MinimalPrimes),
    -- the radical of an ideal
  * "radicalContainment(...,Strategy=>...)" -- see radicalContainment (MinimalPrimes),
    -- whether an element is contained in
    the radical of an ideal
  * "analyticSpread(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "distinguished(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "isLinearType(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "isReduction(...,Strategy=>...)" -- see reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "minimalReduction(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "multiplicity(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "normalCone(...,Strategy=>...)" -- see reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "reesAlgebra(...,Strategy=>...)" -- see reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * reesIdeal(...,Strategy=>...) (ReesAlgebra)
    -- Choose a
    strategy for the saturation step
  * "specialFiber(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "specialFiberIdeal(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "regSeqInIdeal(...,Strategy=>...)" -- see regSeqInIdeal (PrimaryDecomposition),
    -- a regular sequence contained in an
    ideal
  * resolution(...,Strategy=>...) (Macaulay2Doc)
  * "sagbi(...,Strategy=>...)" -- see sagbi, -- Compute a
    subalgebra basis (sagbi basis)
  * "sagbiBasis(...,Strategy=>...)" -- see sagbiBasis, --
    Constructs a computation object from a subring.
  * saturate(...,Strategy=>...) (Saturation)
  * "primaryDecomposition(...,Strategy=>...)" -- see strategies for computing primary decomposition (PrimaryDecomposition),
  * "subalgebraBasis(...,Strategy=>...)" -- see subalgebraBasis,
    -- Compute subalgebra basis (sagbi basis) generators
  * "subduction(...,Strategy=>...)" -- see subduction, --
    Subduction of polynomials
  * "subringIntersection(...,Strategy=>...)" -- see subringIntersection,
    -- Intersection of subrings
  * "syz(...,Strategy=>...)" -- see syz(Matrix) (Macaulay2Doc),
    -- compute the syzygy matrix
  * "tangentCone(...,Strategy=>...)" -- see tangentCone(Ideal) (TangentCone),

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

The object Strategy (Macaulay2Doc), is a symbol (Macaulay2Doc).

subalgebraBasis -- Compute subalgebra basis (sagbi basis) generators
********************************************************************

Synopsis
========

  * Usage:
        N = subalgebraBasis M
        N = subalgebraBasis A
        N = subalgebraBasis L
        N = subalgebraBasis B
  * Inputs:
      * A, an instance of the type 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, an instance of the type SAGBIBasis, containing a
        partial computation of a sagbi 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 Sagbi basis computation (See:
        AutoSubduce)
      * ReduceNewGenerators => a Boolean value (Macaulay2Doc),
        default value true, a flag indicating whether to apply gaussian
        elimination to new sagbi generators before adding them to the current
        sagbi basis (See: ReduceNewGenerators)
      * StorePending => a Boolean value (Macaulay2Doc), default
        value true, a flag that indicates whether the pending list should be
        stored in the result. (See: StorePending)
      * 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 that combines the other two; starting with
        \"DegreeByDegree\" for low degrees and switching to \"Incremental\".
        (See: Strategy (Macaulay2Doc))
      * SubductionMethod => a string (Macaulay2Doc), default
        value "Top", the method used for subduction either: \"Top\" or
        \"Engine\". (See: SubductionMethod)
      * Limit => an integer (Macaulay2Doc), default value 100, a
        degree limit for the binomial S-pairs that are computed internally.
      * AutoSubduceOnPartialCompletion => a Boolean value (Macaulay2Doc),
        default value false, apply autosubduction to
        the sagbi generators the first time no new generators are added. Use
        this only if very few new sagbi generators are expected. (See:
        AutoSubduceOnPartialCompletion)
      * PrintLevel => an integer (Macaulay2Doc), default value 0,
        When this is greater than zero, information is printed about the
        progress of the computation (See: PrintLevel)
      * 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 will use the options
        specified otherwise it will use the previously selected options (except
        for the following, which may always be specified: PrintLevel,
        see Limit (Macaulay2Doc), Recompute,
        and RenewOptions)
  * Outputs:
      * N, a matrix (Macaulay2Doc), whose entries form a partial
        subalgebra basis

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

The command subalgebraBasis, A is equivalent to the
command generators (Macaulay2Doc), 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
  * Strategy (Macaulay2Doc) -- an optional argument
  * SubductionMethod -- Subduction method for the
    Sagbi algorithm
  * Limit (Macaulay2Doc) -- an optional argument
  * AutoSubduceOnPartialCompletion, --
    Subduct sagbi generators at the end of the Sagbi algorithm
  * PrintLevel -- Levels of information displayed during
    Sagbi algorithm
  * Recompute -- Flag for restarting a sagbi computation
  * RenewOptions -- Flag for reselecting the options for a
    sagbi computation

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

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

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

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

subduction -- Subduction of polynomials
***************************************

Synopsis
========

  * 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, an instance of the type SAGBIBasis, subduct with
        respect to the sagbi generators of $SB$
      * S, an instance of the type Subring, subduct with
        respect to the generators of $S$
      * F, a matrix (Macaulay2Doc), subduct with respect to the
        entries of $F$
      * FList, a list (Macaulay2Doc), subduct with respect to the
        entries of $FList$
      * 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 Sagbi basis computation (See:
        AutoSubduce)
      * ReduceNewGenerators => a Boolean value (Macaulay2Doc),
        default value true, a flag indicating whether to apply gaussian
        elimination to new sagbi generators before adding them to the current
        sagbi basis (See: ReduceNewGenerators)
      * StorePending => a Boolean value (Macaulay2Doc), default
        value true, a flag that indicates whether the pending list should be
        stored in the result. (See: StorePending)
      * 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 that combines the other two; starting with
        \"DegreeByDegree\" for low degrees and switching to \"Incremental\".
        (See: Strategy (Macaulay2Doc))
      * SubductionMethod => a string (Macaulay2Doc), default
        value "Top", the method used for subduction either: \"Top\" or
        \"Engine\". (See: SubductionMethod)
      * Limit => an integer (Macaulay2Doc), default value 100, a
        degree limit for the binomial S-pairs that are computed internally.
      * AutoSubduceOnPartialCompletion => a Boolean value (Macaulay2Doc),
        default value false, apply autosubduction to
        the sagbi generators the first time no new generators are added. Use
        this only if very few new sagbi generators are expected. (See:
        AutoSubduceOnPartialCompletion)
      * PrintLevel => an integer (Macaulay2Doc), default value 0,
        When this is greater than zero, information is printed about the
        progress of the computation (See: PrintLevel)
      * 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 will use the options
        specified otherwise it will use the previously selected options (except
        for the following, which may always be specified: PrintLevel,
        see Limit (Macaulay2Doc), 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 subduction uses the specified SubductionMethod,
and PrintLevel.

+-----------------------------------+
|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                             |
+-----------------------------------+

See also
========

  * sagbi -- Compute a subalgebra basis (sagbi basis)
  * 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
  * Strategy (Macaulay2Doc) -- an optional argument
  * SubductionMethod -- Subduction method for the
    Sagbi algorithm
  * Limit (Macaulay2Doc) -- an optional argument
  * AutoSubduceOnPartialCompletion, --
    Subduct sagbi generators at the end of the Sagbi algorithm
  * PrintLevel -- Levels of information displayed during
    Sagbi algorithm
  * Recompute -- Flag for restarting a sagbi computation
  * RenewOptions -- Flag for reselecting the options for a
    sagbi computation

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).

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

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

To subduct the S-pairs in sagbi, one can either use \"Top\" or
\"Engine\". Engine level subduction is generally faster. To view each
subduction taking place inside the Sagbi algorithm, use a high value for
PrintLevel, together with 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
  * Strategy (Macaulay2Doc) -- an optional argument
  * SubductionMethod -- Subduction method for the
    Sagbi algorithm
  * Limit (Macaulay2Doc) -- an optional argument
  * AutoSubduceOnPartialCompletion, --
    Subduct sagbi generators at the end of the Sagbi algorithm
  * PrintLevel -- Levels of information displayed during
    Sagbi algorithm
  * Recompute -- Flag for restarting a sagbi computation
  * RenewOptions -- Flag for reselecting the options for a
    sagbi computation

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

  * "forceSB(...,SubductionMethod=>...)" -- see forceSB, --
    declare the generators of a subring or SAGBIBasis to be a complete sagbi
    basis
  * "isSAGBI(...,SubductionMethod=>...)" -- see isSAGBI, --
    Check if the generators are a sagbi basis
  * "sagbi(...,SubductionMethod=>...)" -- see sagbi, -- Compute a
    subalgebra basis (sagbi basis)
  * "sagbiBasis(...,SubductionMethod=>...)" -- see sagbiBasis,
    -- Constructs a computation object from a subring.
  * "subalgebraBasis(...,SubductionMethod=>...)" -- see subalgebraBasis,
    -- Compute subalgebra basis (sagbi basis) generators
  * "subduction(...,SubductionMethod=>...)" -- see subduction,
    -- Subduction of polynomials
  * "subringIntersection(...,SubductionMethod=>...)" -- see
    subringIntersection, -- Intersection of subrings

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

The object SubductionMethod, is a symbol (Macaulay2Doc).

subductionQuotientRing -- returns the subduction quotient ring of a subring
***************************************************************************

Synopsis
========

  * Usage:
        subQuotRing = subductionQuotientRing S
  * Inputs:
      * S, an instance of the type Subring,
  * Outputs:
      * subQuotRing, a polynomial ring (Macaulay2Doc),

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

Given a subring S of a quotient ring Q is a polynomial ring with same
coefficient ring as Q and has one variable for each generator of S. There is a
natural map from the subduction quotient ring to S that sends each variable to
its corresponding generator of S. Elements of the subduction quotient ring
represent polynomial combinations of generators. Evaluating a combination of
generators is equal to applying the aforementioned map.

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

+--------------------------------------------------+
|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 : M = map(Q, subductionQuotientRing S, gens S);|
|                                                  |
|                    ZZ                            |
|o7 : RingMap Q <--- --[p ..p ]                    |
|                     2  0   2                     |
+--------------------------------------------------+
|i8 : M g == f                                     |
|                                                  |
|o8 = true                                         |
+--------------------------------------------------+

See also
========

  * Subring -- The type of all subrings
  * RingElement // Subring -- subductionQuotient
    with respect to a subring

Ways to use subductionQuotientRing :
====================================

  * "subductionQuotientRing(Subring)"

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

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

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

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

Subring is a type that stores information associated to a subring of a
polynomial ring, such as a set of subring generators and a reference to the
polynomial ring it is contained in. An instance of a Subring is constructed
with the function subring.

Every instance of Subring is guaranteed to have the following keys:

  * 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 unspecified information. The contents of the cache may
    effect performance, but should never effect the result of a computation.
  * subductionQuotientRing: the polynomial ring with one variable for each
    generator 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
  * subductionQuotientRing(Subring) -- returns
    the subduction quotient ring of a subring
  * sagbi -- Compute a subalgebra basis (sagbi basis)
  * SAGBIBasis -- The type of all sagbi bases

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

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

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

  * ambient(Subring) -- The ambient ring of a
    subring
  * "forceSB(Subring)" -- see forceSB, -- declare the generators
    of a subring or SAGBIBasis to be a complete sagbi 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
  * "isSAGBI(Subring)" -- see isSAGBI, -- Check if the
    generators are a sagbi basis
  * Matrix % Subring -- Remainder modulo a subring
  * net(Subring) -- Short summary of a subring
  * numgens(Subring) -- The number of generators
    of a subring
  * RingElement % Subring -- Remainder modulo a
    subring
  * RingElement // Subring -- subductionQuotient
    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 (sagbi basis) generators
  * "subduction(Subring,Matrix)" -- see subduction, --
    Subduction of polynomials
  * "subduction(Subring,RingElement)" -- see subduction, --
    Subduction of polynomials
  * "subductionQuotientRing(Subring)" -- see subductionQuotientRing,
    -- returns the subduction quotient ring of a
    subring
  * "subringIntersection(Subring,Subring)" -- see subringIntersection,
    -- Intersection of subrings

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

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

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

Synopsis
========

  * Usage:
        A = subring M
        A = subring L
        A = subring S
  * Inputs:
      * M, a matrix (Macaulay2Doc), a one-row matrix whose
        entries are the generators for the constructed Subring.
      * L, a list (Macaulay2Doc), a list of generators for the
        constructed Subring.
      * S, an instance of the type SAGBIBasis,
  * Optional inputs (Macaulay2Doc),:
      * GeneratorSymbol => a symbol (Macaulay2Doc), default value
        null, a symbol to be used for the variables of the
        subductionQuotientRing.
  * Outputs:
      * A, an instance of the type Subring,

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

This function serves as the canonical constructor for the Subring,
type.

+---------------------------------+
|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 sagbi bases

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

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

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

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

subringIntersection -- Intersection of subrings
***********************************************

Synopsis
========

  * Usage:
        result = subringIntersection(S1, S2)
  * Inputs:
      * S1, an instance of the type Subring,
      * S2, an instance of the type Subring,
      * SAGBILimitType, a string (Macaulay2Doc), Either \"Fixed\"
        or \"Function\". Determined the stopping criterion for the sagbi
        computation. If \"Fixed\" then the Limit (Macaulay2Doc), is
        used, otherwise if \"Function\" is selected then the maximum degree of
        the input generators is used as the degree limit.
  * 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 that combines the other two; starting with
        \"DegreeByDegree\" for low degrees and switching to \"Incremental\".
        (See: Strategy (Macaulay2Doc))
      * SubductionMethod => a string (Macaulay2Doc), default
        value "Top", the method used for subduction either: \"Top\" or
        \"Engine\". (See: SubductionMethod)
      * 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,
        When this is greater than zero, information is printed about the
        progress of the computation (See: PrintLevel).
      * SAGBILimitType
  * Outputs:
      * result, an instance of the type Subring,

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

Computes the intersection of subrings "S_1" and "S_2". These subrings must be
subrings of the same ambient ring. The ambient ring is allowed to be a
polynomial ring or the quotient of a polynomial 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 : S = subringIntersection(S1, S2);|
| -- 0.000050158 seconds elapsed      |
| -- 0.000520434 seconds elapsed      |
| -- 0.000140285 seconds elapsed      |
| -- 0.000048565 seconds elapsed      |
| -- 0.000476475 seconds elapsed      |
| -- 0.000132088 seconds elapsed      |
| -- 0.00004427 seconds elapsed       |
| -- 0.000042746 seconds elapsed      |
| -- 0.00011409 seconds elapsed       |
| -- 0.000050539 seconds elapsed      |
| -- 0.000450514 seconds elapsed      |
| -- 0.000150614 seconds elapsed      |
| -- 0.00004993 seconds elapsed       |
| -- 0.000423712 seconds elapsed      |
| -- 0.000123707 seconds elapsed      |
| -- 0.000049025 seconds elapsed      |
| -- 0.00041902 seconds elapsed       |
| -- 0.000129219 seconds elapsed      |
| -- 0.0000497 seconds elapsed        |
| -- 0.000448862 seconds elapsed      |
| -- 0.000131912 seconds elapsed      |
|timing raw subduction                |
|timing raw subduction                |
|timing raw subduction                |
|timing raw subduction                |
|timing raw subduction                |
|timing raw subduction                |
|timing raw subduction                |
+-------------------------------------+
|i7 : gens S                          |
|                                     |
|o7 = | x2 x2y2+xy3 y4 xy3 y6 xy5 |   |
|                                     |
|             1       6               |
|o7 : Matrix Q  <--- Q                |
+-------------------------------------+
|i8 : isSAGBI S                       |
| -- 0.000051651 seconds elapsed      |
| -- 0.000514066 seconds elapsed      |
| -- 0.00012785 seconds elapsed       |
| -- 0.000049267 seconds elapsed      |
| -- 0.000465148 seconds elapsed      |
| -- 0.000126291 seconds elapsed      |
| -- 0.000063059 seconds elapsed      |
| -- 0.000448029 seconds elapsed      |
| -- 0.00012613 seconds elapsed       |
| -- 0.000049514 seconds elapsed      |
| -- 0.000424909 seconds elapsed      |
| -- 0.000124438 seconds elapsed      |
| -- 0.000048609 seconds elapsed      |
| -- 0.0004156 seconds elapsed        |
| -- 0.000124073 seconds elapsed      |
| -- 0.000049152 seconds elapsed      |
| -- 0.000449122 seconds elapsed      |
| -- 0.000125903 seconds elapsed      |
| -- 0.000051944 seconds elapsed      |
| -- 0.000519873 seconds elapsed      |
| -- 0.000128375 seconds elapsed      |
| -- 0.000049172 seconds elapsed      |
| -- 0.000478729 seconds elapsed      |
| -- 0.000126172 seconds elapsed      |
| -- 0.000048566 seconds elapsed      |
| -- 0.000430572 seconds elapsed      |
| -- 0.000123873 seconds elapsed      |
| -- 0.000049378 seconds elapsed      |
| -- 0.000428503 seconds elapsed      |
| -- 0.000126002 seconds elapsed      |
| -- 0.000048695 seconds elapsed      |
| -- 0.000413364 seconds elapsed      |
| -- 0.000124156 seconds elapsed      |
| -- 0.000048804 seconds elapsed      |
| -- 0.000453232 seconds elapsed      |
| -- 0.000129171 seconds elapsed      |
| -- 0.000050383 seconds elapsed      |
| -- 0.000640141 seconds elapsed      |
| -- 0.000208883 seconds elapsed      |
| -- 0.000051326 seconds elapsed      |
| -- 0.000654725 seconds elapsed      |
| -- 0.000214789 seconds elapsed      |
|timing raw subduction                |
|timing raw subduction                |
|timing raw subduction                |
|timing raw subduction                |
|timing raw subduction                |
|timing raw subduction                |
|timing raw subduction                |
|timing raw subduction                |
|timing raw subduction                |
|timing raw subduction                |
|timing raw subduction                |
|timing raw subduction                |
|timing raw subduction                |
|timing raw subduction                |
|                                     |
|o8 = true                            |
+-------------------------------------+

If the generators of $S$ form a sagbi basis and the degree limit is high
enough, then they are a generating set for the intersection.

See also
========

  * Subring -- The type of all subrings
  * sagbi -- Compute a subalgebra basis (sagbi basis)

Ways to use subringIntersection :
=================================

  * "subringIntersection(Subring,Subring)"

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

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

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

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

When isSAGBI, is supplied a SAGBIBasis, $SB$,
then this flag determines whether the sagbi generators or the subring
generators are checked for being a subalgebra basis. Explicitly, if the flag is
set to false then the sagbi generators of $SB$ are checked for being a
subalgebra basis. Otherwise, if the flag is set to true then the generators of
the underlying subring associated to $SB$ are checked for being a subalgebra
basis.

See also
========

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

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

  * "isSAGBI(...,UseSubringGens=>...)" -- see isSAGBI, -- Check
    if the generators are a sagbi basis

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

The object UseSubringGens, is a symbol (Macaulay2Doc).