This is GeometricDecomposability.info, produced by Macaulay2, version 1.21

GeometricDecomposability -- a package to check whether ideals are geometrically vertex decomposable
***************************************************************************************************

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

This package includes routines to check whether an ideal is geometrically
vertex decomposable.

Geometrically vertex decomposable ideals can be viewed as a generalization of
the properties of the Stanley-Reisner ideal of a vertex decomposable simplicial
complex. This family of ideals is based upon the geometric vertex decomposition
property defined by Knutson, Miller, and Yong [KMY]. Klein and Rajchgot then
gave a recursive definition for geometrically vertex decomposable ideals in
[KR] using this notion.

An unmixed ideal $I$ in a polynomial ring $R$ is geometrically vertex
decomposable if it is the zero ideal, the unit ideal, an ideal generated by
indeterminates, or if there is a indeterminate $y$ of $R$ such that two ideals
$C_{y,I}$ and $N_{y,I}$ constructed from $I$ are both geometrically vertex
decomposable. For the complete definition, see isGVD.

Observe that a geometrically vertex decomposable ideal is recursively defined.
The complexity of verifying that an ideal is geometrically vertex decomposable
will increase as the number of indeterminates appearing in the ideal increases.

Acknowledgement
===============

We thank S. Da Silva, P. Klein, J. Rajchgot, and M. Harada for feedback.
Cummings was partially supported by an NSERC USRA. Van Tuyl's research is
partially supported by NSERC Discovery Grant 2019-05412.

References
==========

[CDSRVT] M. Cummings, S. Da Silva, J. Rajchgot, and A. Van Tuyl. Geometric
Vertex Decomposition and Liaison for Toric Ideals of Graphs. Preprint,
arXiv:2207.06391 (see https://arxiv.org/abs/2207.06391 ) (2022).

[DSH] S. Da Silva and M. Harada. Regular Nilpotent Hessenberg Varieties,
Gröbner Bases, and Toric Degenerations. Preprint, arXiv:2207.08573 (see
https://arxiv.org/abs/2207.08573 ) (2022).

[KMY] A. Knutson, E. Miller, and A. Yong. Gröbner Geometry of Vertex
Decompositions and of Flagged Tableaux. J. Reine Angew. Math. 630 (2009) 1–31.

[KR] P. Klein and J. Rajchgot. Geometric Vertex Decomposition and Liaison.
Forum of Math, Sigma, 9 (2021) e70:1-23.

[SM] H. Saremi and A. Mafi. Unmixedness and Arithmetic Properties of Matroidal
Ideals. Arch. Math. 114 (2020) 299–304.

Authors
=======

  * Mike Cummings (see https://math.mcmaster.ca/~cummim5/ )
    <cummim5@mcmaster.ca>
  * Adam Van Tuyl (see https://ms.mcmaster.ca/~vantuyl/ )
    <vantuyl@math.mcmaster.ca>

Version
=======

This documentation describes version 1.1 of GeometricDecomposability.

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

The source code from which this documentation is derived is in the file
GeometricDecomposability.m2 (see
common/share/Macaulay2/GeometricDecomposability.m2 ).

Exports
=======

  * Functions and commands
      * CyI -- computes the ideal $C_{y,I}$ for a given ideal and
        indeterminate
      * findLexCompatiblyGVDOrders -- finds
        all lexicographic monomial orders $<$ such that the ideal is
        $<$-compatibly geometrically vertex decomposable
      * findOneStepGVD -- for which indeterminates does
        there exist a geometric vertex decomposition
      * getGVDIdeal -- computes the $C_{y,I}$ or $N_{y,I}$
        ideal at any point in the GVD recursion tree
      * isGeneratedByIndeterminates, --
        checks whether the ideal is generated by indeterminates
      * isGVD -- checks whether an ideal is geometrically vertex
        decomposable
      * isLexCompatiblyGVD -- checks whether an
        ideal is <-compatibly geometrically vertex decomposable for a given
        order
      * isUnmixed -- checks whether an ideal is unmixed
      * isWeaklyGVD -- checks whether an ideal is weakly
        geometrically vertex decomposable
      * NyI -- computes the ideal $N_{y,I}$ for a given ideal and
        indeterminate
      * oneStepGVD -- computes a geometric vertex
        decomposition
      * yInit -- computes the ideal of initial y-forms
  * Methods
      * "CyI(Ideal,RingElement)" -- see CyI, -- computes the ideal
        $C_{y,I}$ for a given ideal and indeterminate
      * "findLexCompatiblyGVDOrders(Ideal)" -- see
        findLexCompatiblyGVDOrders, -- finds all
        lexicographic monomial orders $<$ such that the ideal is $<$-compatibly
        geometrically vertex decomposable
      * "findOneStepGVD(Ideal)" -- see findOneStepGVD, --
        for which indeterminates does there exist a geometric vertex
        decomposition
      * "getGVDIdeal(Ideal,List)" -- see getGVDIdeal, --
        computes the $C_{y,I}$ or $N_{y,I}$ ideal at any point in the GVD
        recursion tree
      * "isGeneratedByIndeterminates(Ideal)" -- see
        isGeneratedByIndeterminates, -- checks
        whether the ideal is generated by indeterminates
      * "isGVD(Ideal)" -- see isGVD, -- checks whether an ideal is
        geometrically vertex decomposable
      * "isLexCompatiblyGVD(Ideal,List)" -- see isLexCompatiblyGVD,
        -- checks whether an ideal is <-compatibly
        geometrically vertex decomposable for a given order
      * "isUnmixed(Ideal)" -- see isUnmixed, -- checks whether
        an ideal is unmixed
      * "isWeaklyGVD(Ideal)" -- see isWeaklyGVD, -- checks
        whether an ideal is weakly geometrically vertex decomposable
      * "NyI(Ideal,RingElement)" -- see NyI, -- computes the ideal
        $N_{y,I}$ for a given ideal and indeterminate
      * "oneStepGVD(Ideal,RingElement)" -- see oneStepGVD, --
        computes a geometric vertex decomposition
      * "yInit(Ideal,RingElement)" -- see yInit, -- computes the
        ideal of initial y-forms
  * Symbols
      * CheckCM -- when to perform a Cohen-Macaulay check on
        the ideal
      * CheckDegenerate -- check whether the geometric
        vertex decomposition is degenerate
      * CheckUnmixed -- check whether ideals encountered
        are unmixed
      * IsIdealHomogeneous -- specify whether an
        ideal is homogeneous
      * IsIdealUnmixed -- specify whether an ideal is
        unmixed
      * OnlyDegenerate -- restrict to degenerate
        geometric vertex decompositions
      * OnlyNondegenerate -- restrict to
        nondegenerate geometric vertex decompositions
      * Verbose -- print additional output

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

The object GeometricDecomposability, is a package (Macaulay2Doc).

CheckCM -- when to perform a Cohen-Macaulay check on the ideal
**************************************************************

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

Whether to check that the ideal is geometrically vertex decomposable using the
result of [KR, Corollary 4.5] which relates the geometrically vertex
decomposable and Cohen-Macaulay properties. Set CheckCM=>"once" to perform this
check once (default, only for the ideal given in the input), CheckCM=>"always"
check for the following $C_{y,I}$ and $N_{y,I}$ ideals as well, or
CheckCM=>"never".

References
==========

[KR] P. Klein and J. Rajchgot. Geometric Vertex Decomposition and Liaison.
Forum of Math, Sigma, 9 (2021) e70:1-23.

See also
========

  * isGVD -- checks whether an ideal is geometrically vertex
    decomposable
  * isLexCompatiblyGVD -- checks whether an ideal is
    <-compatibly geometrically vertex decomposable for a given order

Functions with optional argument named CheckCM :
================================================

  * "isGVD(...,CheckCM=>...)"
  * "isLexCompatiblyGVD(...,CheckCM=>...)"

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

The object CheckCM, is a symbol (Macaulay2Doc).

CheckDegenerate -- check whether the geometric vertex decomposition is degenerate
*********************************************************************************

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

A geometric vertex decomposition is degenerate if $\sqrt{C_{y,I}} =
\sqrt{N_{y,I}}$ or if $C_{y,I} = \langle 1 \rangle$, and nondegenerate
otherwise [KR, Section 2.2].

If CheckDegenerate=>true, then oneStepGVD returns a sequence of length four,
where the fourth entry is either "degenerate" or "nondegenerate". Otherwise,
oneStepGVD does not check whether the geometric vertex decomposition is
degenerate and the sequence in the output has length three.

Note that the degeneracy of a geometric vertex decomposition does not matter
with regards to whether an ideal is geometrically vertex decomposable. As a
result, see isGVD, does not check this. However, the definition of
weakly geometrically vertex decomposable depends the one-step geometric vertex
decomposition at each step is degenerate, so isWeaklyGVD,
asks for this check.

+-------------------------------------------------------+
|i1 : R = QQ[x,y,z]                                     |
|                                                       |
|o1 = R                                                 |
|                                                       |
|o1 : PolynomialRing                                    |
+-------------------------------------------------------+
|i2 : I = ideal(x-y, x-z)                               |
|                                                       |
|o2 = ideal (x - y, x - z)                              |
|                                                       |
|o2 : Ideal of R                                        |
+-------------------------------------------------------+
|i3 : oneStepGVD(I, x, CheckDegenerate=>true)           |
|                                                       |
|o3 = (true, ideal (y - z, 1), ideal(y - z), degenerate)|
|                                                       |
|o3 : Sequence                                          |
+-------------------------------------------------------+

References
==========

[KR] P. Klein and J. Rajchgot. Geometric Vertex Decomposition and Liaison.
Forum of Math, Sigma, 9 (2021) e70:1-23.

See also
========

  * isWeaklyGVD -- checks whether an ideal is weakly
    geometrically vertex decomposable
  * oneStepGVD -- computes a geometric vertex decomposition

Functions with optional argument named CheckDegenerate :
========================================================

  * "oneStepGVD(...,CheckDegenerate=>...)"

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

The object CheckDegenerate, is a symbol (Macaulay2Doc).

CheckUnmixed -- check whether ideals encountered are unmixed
************************************************************

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

If set to false, the program never checks whether the ideal $I$ or any
$C_{y,I}$ or $N_{y,I}$ ideals are unmixed. Setting CheckUnmixed=>false will
speed up computations since it is not performing a check of this condition but
comes at the cost that not all the necessary conditions are checked. Notice
that if isGVD(I, CheckUnmixed=>false) returns false, then $I$ is conclusively
not geometrically vertex decomposable as there is some other condition that is
not met. The default value is true.

If you know that $I$ is unmixed but want to check unmixedness for $C_{y,I}$,
$N_{y,I}$, and any later ideals, use IsIdealUnmixed,
instead.

The following is not unmixed [SM, Example 1.6] and hence not geometrically
vertex decomposable. However, if we disable the unmixedness check and skip the
Cohen-Macaulay check, isGVD returns true.

+--------------------------------------------------------------------+
|i1 : R = QQ[x_1..x_5]                                               |
|                                                                    |
|o1 = R                                                              |
|                                                                    |
|o1 : PolynomialRing                                                 |
+--------------------------------------------------------------------+
|i2 : I = ideal(x_1*x_3, x_1*x_4, x_1*x_5, x_2*x_3, x_2*x_4, x_2*x_5)|
|                                                                    |
|o2 = ideal (x x , x x , x x , x x , x x , x x )                     |
|             1 3   1 4   1 5   2 3   2 4   2 5                      |
|                                                                    |
|o2 : Ideal of R                                                     |
+--------------------------------------------------------------------+
|i3 : isUnmixed I                                                    |
|                                                                    |
|o3 = false                                                          |
+--------------------------------------------------------------------+
|i4 : isGVD(I, CheckCM=>"never", CheckUnmixed=>false)                |
|                                                                    |
|o4 = true                                                           |
+--------------------------------------------------------------------+

References
==========

[SM] H. Saremi and A. Mafi. Unmixedness and Arithmetic Properties of Matroidal
Ideals. Arch. Math. 114 (2020) 299–304.

Caveat
======

As in the above example, if you set CheckUnmixed=>false and you do not already
know that both $I$ is unmixed and all later $C_{y,I}$ and $N_{y,I}$ ideals are
unmixed, then the output of isGVD, or any other GVD method cannot
definitely conclude that $I$ is geometrically vertex decomposable, as not all
of conditions in the definition were checked.

See also
========

  * CyI -- computes the ideal $C_{y,I}$ for a given ideal and
    indeterminate
  * findLexCompatiblyGVDOrders -- finds all
    lexicographic monomial orders $<$ such that the ideal is $<$-compatibly
    geometrically vertex decomposable
  * findOneStepGVD -- for which indeterminates does
    there exist a geometric vertex decomposition
  * getGVDIdeal -- computes the $C_{y,I}$ or $N_{y,I}$
    ideal at any point in the GVD recursion tree
  * isGVD -- checks whether an ideal is geometrically vertex
    decomposable
  * IsIdealUnmixed -- specify whether an ideal is
    unmixed
  * isLexCompatiblyGVD -- checks whether an ideal is
    <-compatibly geometrically vertex decomposable for a given order
  * isUnmixed -- checks whether an ideal is unmixed
  * isWeaklyGVD -- checks whether an ideal is weakly
    geometrically vertex decomposable
  * NyI -- computes the ideal $N_{y,I}$ for a given ideal and
    indeterminate

Functions with optional argument named CheckUnmixed :
=====================================================

  * "CyI(...,CheckUnmixed=>...)"
  * "findLexCompatiblyGVDOrders(...,CheckUnmixed=>...)"
  * "findOneStepGVD(...,CheckUnmixed=>...)"
  * "getGVDIdeal(...,CheckUnmixed=>...)"
  * "isGVD(...,CheckUnmixed=>...)"
  * "isLexCompatiblyGVD(...,CheckUnmixed=>...)"
  * "isWeaklyGVD(...,CheckUnmixed=>...)"
  * "NyI(...,CheckUnmixed=>...)"
  * "oneStepGVD(...,CheckUnmixed=>...)"

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

The object CheckUnmixed, is a symbol (Macaulay2Doc).

CyI -- computes the ideal $C_{y,I}$ for a given ideal and indeterminate
***********************************************************************

Synopsis
========

  * Usage:
        CyI(I, y)
  * Inputs:
      * I, an ideal (Macaulay2Doc),
      * y, a ring element (Macaulay2Doc), an indeterminate
        in the ring
  * Optional inputs (Macaulay2Doc),:
      * CheckUnmixed, => ..., default value true, check
        whether ideals encountered are unmixed
  * Outputs:
      * an ideal (Macaulay2Doc),

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

Let $y$ be a variable of the polynomial ring $R = k[x_1,\ldots,x_n]$. A
monomial ordering $<$ on $R$ is said to be $y$-compatible if the initial term
of $f$ satisfies ${\rm in}_<(f) = {\rm in}_<({\rm in}_y(f))$ for all $f \in R$.
Here, ${\rm in}_y(f)$ is the initial $y$-form of $f$, that is, if $f = \sum_i
\alpha_iy^i$ and $\alpha_d \neq 0$ but $\alpha_t = 0$ for all $t >d$, then
${\rm in}_y(f) = \alpha_d y^d$.

Given an ideal $I$ and a $y$-compatible monomial ordering $<$, let $G(I) = \{
g_1,\ldots,g_m\}$ be a Gröbner basis of $I$ with respect to this ordering.  For
$i=1,\ldots,m$, write $g_i$ as $g_i = y^{d_i}q_i + r_i$, where $y$ does not
divide any term of $q_i$; that is, ${\rm in}_y(g_i) = y^{d_i}q_i$.   Given this
setup, the ideal $C_{y,I}$ is given by $$C_{y,I} = \langle
q_1,\ldots,q_m\rangle$$ This functions  takes an ideal $I$ and variable $y$,
and returns $C_{y,I}$.

The ideal $C_{y,I}$ does not depend upon the choice of the Gröbner basis or a
particular $y$-compatible order (see comment after [KR, Definition 2.3]). When
computing $C_{y,I}$ we use a lexicographical ordering on $R$ where $y > x_j$
for all $i \neq j$ if $y = x_i$ since this gives us a $y$-compatible order.

The ideal $I$ in the example below is the edge ideal of the complete graph
$K_4$. For more on edge ideals, see the EdgeIdeals package.

+-----------------------------------------------------------------------------+
|i1 : R = QQ[a,b,c,d];                                                        |
+-----------------------------------------------------------------------------+
|i2 : I = ideal(a*b, a*c, a*d, b*c, b*d, c*d); -- edge ideal of the complete  |
|                                                                             |
|o2 : Ideal of R                                                              |
|-----------------------------------------------------------------------------|
|graph K_4, a chordal graph                                                   |
+-----------------------------------------------------------------------------+
|i3 : CyI(I, b)                                                               |
|                                                                             |
|o3 = ideal (c*d, a*d, a*c, d, c, a)                                          |
|                                                                             |
|o3 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i4 : L = oneStepGVD(I, b);                                                   |
+-----------------------------------------------------------------------------+
|i5 : L_1 == CyI(I, b) -- CyI is the second element in the list given by      |
|                                                                             |
|o5 = true                                                                    |
|-----------------------------------------------------------------------------|
|oneStepGVD                                                                   |
+-----------------------------------------------------------------------------+

References
==========

[KR] P. Klein and J. Rajchgot. Geometric Vertex Decomposition and Liaison.
Forum of Math, Sigma, 9 (2021) e70:1-23.

Caveat
======

This method is a shortcut to extract the ideal $C_{y,I}$ as computed in
oneStepGVD. That is, to compute $C_{y,I}$, oneStepGVD is called in
the background. As a result, work is also done in the background to compute
$N_{y,I}$ at the same time, and as such, we encourage calling oneStepGVD
directly if we want both the $C_{y,I}$ and $N_{y,I}$ ideals to avoid performing
the same computation twice.

See also
========

  * CheckUnmixed -- check whether ideals encountered are
    unmixed
  * getGVDIdeal -- computes the $C_{y,I}$ or $N_{y,I}$
    ideal at any point in the GVD recursion tree
  * NyI -- computes the ideal $N_{y,I}$ for a given ideal and
    indeterminate
  * oneStepGVD -- computes a geometric vertex decomposition

Ways to use CyI :
=================

  * "CyI(Ideal,RingElement)"

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

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

findLexCompatiblyGVDOrders -- finds all lexicographic monomial orders $<$ such that the ideal is $<$-compatibly geometrically vertex decomposable
*************************************************************************************************************************************************

Synopsis
========

  * Usage:
        findLexCompatiblyGVDOrders I
  * Inputs:
      * I, an ideal (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * CheckUnmixed, => ..., default value true, check
        whether ideals encountered are unmixed
  * Outputs:
      * a list (Macaulay2Doc), if no order exists, returns {},
        otherwise returns L, a list containing all the lexicographical orders
        which work

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

An ideal $I$ is $<$-compatibly geometrically vertex decomposable if there
exists a (lexicographic) order $<$ such that $I$ is geometrically vertex
decomposable and for every (one-step) geometric vertex decomposition, we pick
$y$ to be the most expensive indeterminate remaining in the ideal according to
$<$ [KR, Definition 2.11]. For the definition of a (one-step) geometric vertex
decomposition, see oneStepGVD.

This method computes all possible lex orders $<$ for which the ideal $I$ is
$<$-compatibly geometrically vertex decomposable.

+-----------------------------------------------------------------------+
|i1 : R = QQ[x,y,z];                                                    |
+-----------------------------------------------------------------------+
|i2 : I = ideal(x-y, x-z);                                              |
|                                                                       |
|o2 : Ideal of R                                                        |
+-----------------------------------------------------------------------+
|i3 : findLexCompatiblyGVDOrders I                                      |
|                                                                       |
|o3 = {{x, y, z}, {x, z, y}, {y, x, z}, {y, z, x}, {z, x, y}, {z, y, x}}|
|                                                                       |
|o3 : List                                                              |
+-----------------------------------------------------------------------+

The ideal in the following example is not square-free with respect to any
indeterminate, so no one-step geometric vertex decomposition exists.

+---------------------------------+
|i4 : R = QQ[x,y];                |
+---------------------------------+
|i5 : I = ideal(x^2-y^2);         |
|                                 |
|o5 : Ideal of R                  |
+---------------------------------+
|i6 : findLexCompatiblyGVDOrders I|
|                                 |
|o6 = {}                          |
|                                 |
|o6 : List                        |
+---------------------------------+

References
==========

[KR] P. Klein and J. Rajchgot. Geometric Vertex Decomposition and Liaison.
Forum of Math, Sigma, 9 (2021) e70:1-23.

Caveat
======

In the ring $k[x_1, \ldots, x_n]$, there are $n!$ possible lexicographic
monomial orders, so this function can be computationally expensive.

See also
========

  * CheckUnmixed -- check whether ideals encountered are
    unmixed
  * isLexCompatiblyGVD -- checks whether an ideal is
    <-compatibly geometrically vertex decomposable for a given order

Ways to use findLexCompatiblyGVDOrders :
========================================

  * "findLexCompatiblyGVDOrders(Ideal)"

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

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

findOneStepGVD -- for which indeterminates does there exist a geometric vertex decomposition
********************************************************************************************

Synopsis
========

  * Usage:
        findOneStepGVD I
  * Inputs:
      * I, an ideal (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * CheckUnmixed, => ..., default value true, check
        whether ideals encountered are unmixed
      * OnlyDegenerate, => ..., default value false,
        restrict to degenerate geometric vertex decompositions
      * OnlyNondegenerate, => ..., default value
        false, restrict to nondegenerate geometric vertex decompositions
  * Outputs:
      * a list (Macaulay2Doc),

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

Returns a list containing the $y$ for which there exists a oneStepGVD.
In other words, a list of all the variables $y$ that satisfy
${\rm in}_y(I) = C_{y,I} \cap (N_{y,I} + \langle y \rangle)$. All
indeterminates $y$ which appear in the ideal are checked.

+-------------------------+
|i1 : R = QQ[x,y,z]       |
|                         |
|o1 = R                   |
|                         |
|o1 : PolynomialRing      |
+-------------------------+
|i2 : I = ideal(x-y, x-z) |
|                         |
|o2 = ideal (x - y, x - z)|
|                         |
|o2 : Ideal of R          |
+-------------------------+
|i3 : findOneStepGVD I    |
|                         |
|o3 = {x, y, z}           |
|                         |
|o3 : List                |
+-------------------------+

The following example is [KR, Example 2.16]. The variable $b$ is the only
indeterminate for which there exists a geometric vertex decomposition.

+------------------------------------------------------------------+
|i4 : R = QQ[a..f]                                                 |
|                                                                  |
|o4 = R                                                            |
|                                                                  |
|o4 : PolynomialRing                                               |
+------------------------------------------------------------------+
|i5 : I = ideal(b*(c*f - a^2), b*d*e, d*e*(c^2+a*c+d*e+f^2))       |
|                                                                  |
|               2                             2       2 2        2 |
|o5 = ideal (- a b + b*c*f, b*d*e, a*c*d*e + c d*e + d e  + d*e*f )|
|                                                                  |
|o5 : Ideal of R                                                   |
+------------------------------------------------------------------+
|i6 : findOneStepGVD I                                             |
|                                                                  |
|o6 = {b}                                                          |
|                                                                  |
|o6 : List                                                         |
+------------------------------------------------------------------+

References
==========

[KR] P. Klein and J. Rajchgot. Geometric Vertex Decomposition and Liaison.
Forum of Math, Sigma, 9 (2021) e70:1-23.

See also
========

  * CheckUnmixed -- check whether ideals encountered are
    unmixed
  * oneStepGVD -- computes a geometric vertex decomposition
  * OnlyDegenerate -- restrict to degenerate geometric
    vertex decompositions
  * OnlyNondegenerate -- restrict to nondegenerate
    geometric vertex decompositions

Ways to use findOneStepGVD :
============================

  * "findOneStepGVD(Ideal)"

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

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

getGVDIdeal -- computes the $C_{y,I}$ or $N_{y,I}$ ideal at any point in the GVD recursion tree
***********************************************************************************************

Synopsis
========

  * Usage:
        getGVDIdeal(I, L)
  * Inputs:
      * I, an ideal (Macaulay2Doc),
      * L, a list (Macaulay2Doc), a nested list where each list
        within L is of length two, the first entry is either "C" or "N" and the
        second entry is an indeterminate in the ring
  * Optional inputs (Macaulay2Doc),:
      * CheckUnmixed, => ..., default value true, check
        whether ideals encountered are unmixed
  * Outputs:
      * a list (Macaulay2Doc),

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

The purpose of getGVDIdeal is to return the ideal generated by a sequence of
choices of $C$ or $N$ ideals and corresponding choices of indeterminates $y$.

Given an ideal $I$ and variable $y_1$ in $R = k[x_1,\ldots,x_n]$, we can
compute the ideals $C_{y_1,I}$ and $N_{y_1,I}$ (see isGVD, for the
definition of these ideals).  But then for each of these ideals in the ring $R
= k[x_1,\ldots,\hat{y_1},\ldots,x_n]$, we can then pick a new variable $y_2$ to
form the ideals $C_{y_2,C_{y_1,I}}$, $C_{y_2,N_{y_1,I}}$, $N_{y_2,C_{y_1,I}}$
or $N_{y_2,N_{y_1,I}}$.  This process can be continued by now picking a new
variable $y_3$, and finding either the $C$ or $N$ ideals of these ideals.

The input syntax is best explained via example. The following is [KR, Example
2.16]. We are given the ideal $I$.  The input tells us to first find $C_{y,I}$
of $I$.  Then we find $N_{s,C_{y,I}}$.

+-------------------------------------------------------------------------+
|i1 : R = QQ[x,y,z,w,r,s]                                                 |
|                                                                         |
|o1 = R                                                                   |
|                                                                         |
|o1 : PolynomialRing                                                      |
+-------------------------------------------------------------------------+
|i2 : I = ideal(y*(z*s - x^2), y*w*r, w*r*(z^2+z*x+w*r+s^2))              |
|                                                                         |
|               2                             2       2 2        2        |
|o2 = ideal (- x y + y*z*s, y*w*r, x*z*w*r + z w*r + w r  + w*r*s )       |
|                                                                         |
|o2 : Ideal of R                                                          |
+-------------------------------------------------------------------------+
|i3 : getGVDIdeal(I, {{"C", y}, {"N", s}})                                |
|                                                                         |
|                        2       2 2        2        2                    |
|o3 = {ideal (x*z*w*r + z w*r + w r  + w*r*s , w*r, x  - z*s), ideal(w*r)}|
|                                                                         |
|o3 : List                                                                |
+-------------------------------------------------------------------------+

References
==========

[KR] P. Klein and J. Rajchgot. Geometric Vertex Decomposition and Liaison.
Forum of Math, Sigma, 9 (2021) e70:1-23.

See also
========

  * CheckUnmixed -- check whether ideals encountered are
    unmixed
  * CyI -- computes the ideal $C_{y,I}$ for a given ideal and
    indeterminate
  * NyI -- computes the ideal $N_{y,I}$ for a given ideal and
    indeterminate
  * oneStepGVD -- computes a geometric vertex decomposition

Ways to use getGVDIdeal :
=========================

  * "getGVDIdeal(Ideal,List)"

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

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

isGeneratedByIndeterminates -- checks whether the ideal is generated by indeterminates
**************************************************************************************

Synopsis
========

  * Usage:
        isGeneratedByIndeterminates I
  * Inputs:
      * I, an ideal (Macaulay2Doc),
  * Outputs:
      * a Boolean value (Macaulay2Doc),

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

An ideal is generated by indeterminates if the generators are a (possibly
empty) subset of the indeterminates in the ring.

+-------------------------------------------+
|i1 : R = QQ[x,y]                           |
|                                           |
|o1 = R                                     |
|                                           |
|o1 : PolynomialRing                        |
+-------------------------------------------+
|i2 : isGeneratedByIndeterminates ideal 0   |
|                                           |
|o2 = true                                  |
+-------------------------------------------+
|i3 : isGeneratedByIndeterminates ideal 1   |
|                                           |
|o3 = false                                 |
+-------------------------------------------+
|i4 : isGeneratedByIndeterminates ideal(x,y)|
|                                           |
|o4 = true                                  |
+-------------------------------------------+
|i5 : isGeneratedByIndeterminates ideal(x*y)|
|                                           |
|o5 = false                                 |
+-------------------------------------------+

See also
========

  * isGVD -- checks whether an ideal is geometrically vertex
    decomposable
  * isLexCompatiblyGVD -- checks whether an ideal is
    <-compatibly geometrically vertex decomposable for a given order
  * isWeaklyGVD -- checks whether an ideal is weakly
    geometrically vertex decomposable

Ways to use isGeneratedByIndeterminates :
=========================================

  * "isGeneratedByIndeterminates(Ideal)"

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

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

isGVD -- checks whether an ideal is geometrically vertex decomposable
*********************************************************************

Synopsis
========

  * Usage:
        isGVD I
  * Inputs:
      * I, an ideal (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * CheckCM, => ..., default value "once", when to perform a
        Cohen-Macaulay check on the ideal
      * CheckUnmixed, => ..., default value true, check
        whether ideals encountered are unmixed
      * IsIdealHomogeneous, => ..., default value
        false, specify whether an ideal is homogeneous
      * IsIdealUnmixed, => ..., default value false,
        specify whether an ideal is unmixed
      * Verbose, => ..., default value false, print additional
        output
  * Outputs:
      * a Boolean value (Macaulay2Doc),

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

This function tests whether a given ideal is geometrically vertex decomposable.
Geometrically vertex decomposable ideals are based upon the geometric vertex
decomposition defined by Knutson, Miller, and Yong [KMY].  Using geometric
vertex decomposition, Klein and Rajchgot gave a recursive definition for
geometrically vertex decomposable ideals in [KR, Definition 2.7].  This
definition generalizes the properties of a square-free monomial ideal whose
associated simplicial complex is vertex decomposable.

We include the definition here. Let $y$ be a variable of the polynomial ring $R
= k[x_1,\ldots,x_n]$. A monomial ordering $<$ on $R$ is said to be
$y$-compatible if the initial term of $f$ satisfies ${\rm in}_<(f) = {\rm
in}_<({\rm in}_y(f))$ for all $f \in R$.  Here, ${\rm in}_y(f)$ is the initial
$y$-form of $f$, that is, if $f = \sum_i \alpha_iy^i$ and $\alpha_d \neq 0$ but
$\alpha_t = 0$ for all $t >d$, then ${\rm in}_y(f) = \alpha_d y^d$. We set
${\rm in}_y(I) = \langle {\rm in}_y(f) ~|~ f \in I \rangle$ to be the ideal
generated by all the initial $y$-forms in $I$.

Given an ideal $I$ and a $y$-compatible monomial ordering $<$, let $G(I) = \{
g_1,\ldots,g_m\}$ be a Gröbner basis of $I$ with respect to this ordering.  For
$i=1,\ldots,m$, write $g_i$ as $g_i = y^{d_i}q_i + r_i$, where $y$ does not
divide any term of $q_i$; that is, ${\rm in}_y(g_i) = y^{d_i}q_i$.   Given this
setup, we define two ideals: $$C_{y,I} = \langle q_1,\ldots,q_m\rangle$$ and
$$N_{y,I} = \langle q_i ~|~ d_i = 0 \rangle.$$ Recall that an ideal $I$ is
unmixed if all of the associated primes of $I$ have the same height.

An ideal $I$ of $R =k[x_1,\ldots,x_n]$ is geometrically vertex decomposable if
$I$ is unmixed and

(1)  $I = \langle 1 \rangle$, or $I$ is generated by a (possibly empty) subset
of variables of $R$, or

(2) there is a variable $y = x_i$ in $R$ and a $y$-compatible monomial ordering
$<$ such that $${\rm in}_y(I) = C_{y,I} \cap (N_{y,I} + \langle y \rangle),$$
and the contractions of the ideals $C_{y,I}$ and $N_{y,I}$ to the ring
$k[x_1,\ldots,\hat{y},\ldots,x_n]$ are geometrically vertex decomposable.

NOTE:  The ideals $C_{y,I}$ and $N_{y,I}$ do not depend upon the choice of the
Gröbner basis or a particular $y$-compatible order (see comment after [KR,
Definition 2.3]). When computing $C_{y,I}$ and $N_{y,I}$ we use a
lexicographical ordering on $R$ where $y > x_j$ for all $i \neq j$ if $y = x_i$
since this gives us a $y$-compatible order.

+-------------------------------------+
|i1 : R = QQ[a,b,c,d]                 |
|                                     |
|o1 = R                               |
|                                     |
|o1 : PolynomialRing                  |
+-------------------------------------+
|i2 : f = 3*a*b + 4*b*c+ 16*a*c + 18*d|
|                                     |
|o2 = 3a*b + 16a*c + 4b*c + 18d       |
|                                     |
|o2 : R                               |
+-------------------------------------+
|i3 : i = ideal f                     |
|                                     |
|o3 = ideal(3a*b + 16a*c + 4b*c + 18d)|
|                                     |
|o3 : Ideal of R                      |
+-------------------------------------+
|i4 : isGVD i                         |
|                                     |
|o4 = true                            |
+-------------------------------------+

Square-free monomial ideals that are geometrically vertex decomposable are
precisely those square-free monomial ideals whose associated simplicial complex
are vertex decomposable [KR, Proposition 2.9]. The edge ideal of a chordal
graph corresponds to a simplicial complex that is vertex decomposable (for
more, see the EdgeIdeals package).  The option Verbose shows the intermediate
steps; in particular, Verbose displays what variable is being used to test a
decomposition, as well as the ideals $C_{y,I}$ and $N_{y,I}$.

+-----------------------------------------------------------------------------+
|i5 : R = QQ[a,b,c,d]                                                         |
|                                                                             |
|o5 = R                                                                       |
|                                                                             |
|o5 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i6 : i = ideal(a*b, a*c, a*d, b*c, b*d, c*d) -- edge ideal of a complete     |
|                                                                             |
|o6 = ideal (a*b, a*c, a*d, b*c, b*d, c*d)                                    |
|                                                                             |
|o6 : Ideal of R                                                              |
|-----------------------------------------------------------------------------|
|graph K_4, a chordal graph                                                   |
+-----------------------------------------------------------------------------+
|i7 : isGVD(i, Verbose=>true)                                                 |
|ideal(a*b,a*c,a*d,b*c,b*d,c*d)                                               |
|-- decomposing with respect to a                                             |
|-- C = ideal(c*d,b*d,b*c,d,c,b)                                              |
|-- N = ideal(c*d,b*d,b*c)                                                    |
|ideal(c*d,b*d,b*c,d,c,b)                                                     |
|-- decomposing with respect to b                                             |
|-- C = ideal(d,c,1)                                                          |
|-- N = ideal(d,c)                                                            |
|ideal(d,c,1)                                                                 |
|-- unit ideal                                                                |
|ideal(d,c)                                                                   |
|-- generated by indeterminates                                               |
|ideal(c*d,b*d,b*c)                                                           |
|-- decomposing with respect to b                                             |
|-- C = ideal(c*d,d,c)                                                        |
|-- N = ideal(c*d)                                                            |
|ideal(c*d,d,c)                                                               |
|-- decomposing with respect to c                                             |
|-- C = ideal(d,1)                                                            |
|-- N = ideal d                                                               |
|ideal(d,1)                                                                   |
|-- unit ideal                                                                |
|ideal d                                                                      |
|-- generated by indeterminates                                               |
|ideal(c*d)                                                                   |
|-- decomposing with respect to c                                             |
|-- C = ideal d                                                               |
|-- N = ideal()                                                               |
|ideal d                                                                      |
|-- generated by indeterminates                                               |
|ideal()                                                                      |
|-- zero ideal                                                                |
|                                                                             |
|o7 = true                                                                    |
+-----------------------------------------------------------------------------+

The following is an example of a toric ideal of graph that is geometrically
vertex decomposable, and another example of a toric ideal of a graph that is
not geometrically vertex decomposable. The second ideal is not Cohen-Macaulay,
so it cannot be geometrically vertex decomposable [KR, Corollary 4.5]. For
background on toric ideals of graphs, see [CDSRVT, Section 3].

+-----------------------------------------------------------------------------+
|i8 : R = QQ[e_1..e_7]                                                        |
|                                                                             |
|o8 = R                                                                       |
|                                                                             |
|o8 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i9 : i = ideal(e_2*e_7-e_5*e_6, e_1*e_4-e_2*e_3) -- the toric ideal of a     |
|                                                                             |
|o9 = ideal (- e e  + e e , - e e  + e e )                                    |
|               5 6    2 7     2 3    1 4                                     |
|                                                                             |
|o9 : Ideal of R                                                              |
|-----------------------------------------------------------------------------|
|graph                                                                        |
+-----------------------------------------------------------------------------+
|i10 : isGVD i                                                                |
|                                                                             |
|o10 = true                                                                   |
+-----------------------------------------------------------------------------+
|i11 : R = QQ[e_1..e_10]                                                      |
|                                                                             |
|o11 = R                                                                      |
|                                                                             |
|o11 : PolynomialRing                                                         |
+-----------------------------------------------------------------------------+
|i12 : i = ideal(e_1*e_4-e_2*e_3, e_2^2*e_7*e_8*e_9-e_4^2*e_5*e_6*e_10, e_1*e_|
|                                                                             |
|                             2          2                                    |
|o12 = ideal (- e e  + e e , e e e e  - e e e e  , e e e e e  - e e e e e  ,  |
|                2 3    1 4   2 7 8 9    4 5 6 10   1 2 7 8 9    3 4 5 6 10   |
|      -----------------------------------------------------------------------|
|       2          2                                                          |
|      e e e e  - e e e e  )                                                  |
|       1 7 8 9    3 5 6 10                                                   |
|                                                                             |
|o12 : Ideal of R                                                             |
|-----------------------------------------------------------------------------|
|2*e_7*e_8*e_9-e_3*e_4*e_5*e_6*e_10, e_1^2*e_7*e_8*e_9-e_3^2*e_5*e_6*e_10)    |
+-----------------------------------------------------------------------------+
|i13 : isGVD i                                                                |
|                                                                             |
|o13 = false                                                                  |
+-----------------------------------------------------------------------------+

References
==========

[CDSRVT] M. Cummings, S. Da Silva, J. Rajchgot, and A. Van Tuyl. Geometric
Vertex Decomposition and Liaison for Toric Ideals of Graphs. Preprint,
arXiv:2207.06391 (see https://arxiv.org/abs/2207.06391 ) (2022).

[KMY] A. Knutson, E. Miller, and A. Yong. Gröbner Geometry of Vertex
Decompositions and of Flagged Tableaux. J. Reine Angew. Math. 630 (2009) 1–31.

[KR] P. Klein and J. Rajchgot. Geometric Vertex Decomposition and Liaison.
Forum of Math, Sigma, 9 (2021) e70:1-23.

See also
========

  * CheckCM -- when to perform a Cohen-Macaulay check on the
    ideal
  * CheckUnmixed -- check whether ideals encountered are
    unmixed
  * isGeneratedByIndeterminates -- checks
    whether the ideal is generated by indeterminates
  * IsIdealHomogeneous -- specify whether an ideal
    is homogeneous
  * IsIdealUnmixed -- specify whether an ideal is
    unmixed
  * isLexCompatiblyGVD -- checks whether an ideal is
    <-compatibly geometrically vertex decomposable for a given order
  * isUnmixed -- checks whether an ideal is unmixed
  * isWeaklyGVD -- checks whether an ideal is weakly
    geometrically vertex decomposable
  * oneStepGVD -- computes a geometric vertex decomposition
  * Verbose -- print additional output

Ways to use isGVD :
===================

  * "isGVD(Ideal)"

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

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

IsIdealHomogeneous -- specify whether an ideal is homogeneous
*************************************************************

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

Whether the input ideal is homogeneous, if known. The value of this input is
only checked if CheckCM=>true.

See also
========

  * CheckCM -- when to perform a Cohen-Macaulay check on the
    ideal
  * isGVD -- checks whether an ideal is geometrically vertex
    decomposable
  * isLexCompatiblyGVD -- checks whether an ideal is
    <-compatibly geometrically vertex decomposable for a given order

Functions with optional argument named IsIdealHomogeneous :
===========================================================

  * "isGVD(...,IsIdealHomogeneous=>...)"
  * "isLexCompatiblyGVD(...,IsIdealHomogeneous=>...)"

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

The object IsIdealHomogeneous, is a symbol (Macaulay2Doc).

IsIdealUnmixed -- specify whether an ideal is unmixed
*****************************************************

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

Specify IsIdealUnmixed=>true if it is known a priori that an ideal is unmixed.
In this case, the program will not check whether the given ideal $I$ is unmixed
-- it will assume that it is unmixed -- but it will check whether $C_{y,I}$ and
$N_{y,I}$ are unmixed, as well as any ideals defined from further
degenerations. The default value is false and in this case, the unmixedness
property will be checked for $I$ and all later ideals.

To always skip the unmixedness check (perhaps you know that every ideal you
will encounter through repeated geometric vertex decompositions will always be
unmixed), use CheckUnmixed.

See also
========

  * CheckUnmixed -- check whether ideals encountered are
    unmixed
  * isGVD -- checks whether an ideal is geometrically vertex
    decomposable
  * isLexCompatiblyGVD -- checks whether an ideal is
    <-compatibly geometrically vertex decomposable for a given order
  * isUnmixed -- checks whether an ideal is unmixed
  * isWeaklyGVD -- checks whether an ideal is weakly
    geometrically vertex decomposable

Functions with optional argument named IsIdealUnmixed :
=======================================================

  * "isGVD(...,IsIdealUnmixed=>...)"
  * "isLexCompatiblyGVD(...,IsIdealUnmixed=>...)"
  * "isWeaklyGVD(...,IsIdealUnmixed=>...)"

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

The object IsIdealUnmixed, is a symbol (Macaulay2Doc).

isLexCompatiblyGVD -- checks whether an ideal is <-compatibly geometrically vertex decomposable for a given order
*****************************************************************************************************************

Synopsis
========

  * Usage:
        isLexCompatiblyGVD(I, L)
  * Inputs:
      * I, an ideal (Macaulay2Doc),
      * L, a list (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * CheckCM, => ..., default value "once", when to perform a
        Cohen-Macaulay check on the ideal
      * CheckUnmixed, => ..., default value true, check
        whether ideals encountered are unmixed
      * IsIdealHomogeneous, => ..., default value
        false, specify whether an ideal is homogeneous
      * IsIdealUnmixed, => ..., default value false,
        specify whether an ideal is unmixed
      * Verbose, => ..., default value false, print additional
        output
  * Outputs:
      * a Boolean value (Macaulay2Doc),

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

An ideal $I$ is $<$-compatibly geometrically vertex decomposable if there
exists a (lexicographic) order $<$ such that $I$ is geometrically vertex
decomposable and for every (one-step) geometric vertex decomposition, we pick
$y$ to be the most expensive indeterminate remaining in the ideal according to
$<$ [KR, Definition 2.11]. For the definition of a (one-step) geometric vertex
decomposition, see oneStepGVD.

This method returns a Boolean value depending upon whether or not the given
ideal is $<$-compatibly geometrically vertex decomposable with respect to a
given ordering lex ordering of the indeterminates. Compare this function to the
command findLexCompatiblyGVDOrders, which
checks all possible lex orders of the variables in order to find at least one
$<$-compatibly lex order.

Below is [KR, Example 2.16], which is an example of an ideal that is not
$<$-compatibly geometrically vertex decomposable. Any permutation of the
variables we give in this example will result in false.

+------------------------------------------------------------------+
|i1 : R = QQ[x,y,z,w,r,s];                                         |
+------------------------------------------------------------------+
|i2 : I = ideal(y*(z*s - x^2), y*w*r, w*r*(z^2 + z*x + w*r + s^2));|
|                                                                  |
|o2 : Ideal of R                                                   |
+------------------------------------------------------------------+
|i3 : isLexCompatiblyGVD(I, {x,y,z,w,r,s})                         |
|                                                                  |
|o3 = false                                                        |
+------------------------------------------------------------------+
|i4 : isLexCompatiblyGVD(I, {s,x,w,y,r,z}, Verbose=>true)          |
|ideal(-x^2*y+y*z*s,y*w*r,x*z*w*r+z^2*w*r+w^2*r^2+w*r*s^2)         |
|-- decomposing with respect to s                                  |
|Warning: Gröbner basis not square-free in s                       |
|                                                                  |
|o4 = false                                                        |
+------------------------------------------------------------------+

References
==========

[KR] P. Klein and J. Rajchgot. Geometric Vertex Decomposition and Liaison.
Forum of Math, Sigma, 9 (2021) e70:1-23.

See also
========

  * CheckCM -- when to perform a Cohen-Macaulay check on the
    ideal
  * CheckUnmixed -- check whether ideals encountered are
    unmixed
  * isGeneratedByIndeterminates -- checks
    whether the ideal is generated by indeterminates
  * isGVD -- checks whether an ideal is geometrically vertex
    decomposable
  * IsIdealHomogeneous -- specify whether an ideal
    is homogeneous
  * IsIdealUnmixed -- specify whether an ideal is
    unmixed
  * isUnmixed -- checks whether an ideal is unmixed
  * isWeaklyGVD -- checks whether an ideal is weakly
    geometrically vertex decomposable
  * oneStepGVD -- computes a geometric vertex decomposition
  * Verbose -- print additional output

Ways to use isLexCompatiblyGVD :
================================

  * "isLexCompatiblyGVD(Ideal,List)"

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

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

isUnmixed -- checks whether an ideal is unmixed
***********************************************

Synopsis
========

  * Usage:
        isUnmixed I
  * Inputs:
      * I, an ideal (Macaulay2Doc),
  * Outputs:
      * a Boolean value (Macaulay2Doc),

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

A function that checks whether an ideal $I \subseteq R$ is unmixed, i.e., the
ideal $I$ satisfies $\dim(R/I) = \dim(R/P)$ for all associated primes $P \in
{\rm Ass}_R(R/I)$.

The following example uses  [SM, Example 1.6].

+---------------------------------------------------------------------+
|i1 : R = QQ[x_1..x_5];                                               |
+---------------------------------------------------------------------+
|i2 : I = ideal(x_1*x_3, x_1*x_4, x_1*x_5, x_2*x_3, x_2*x_4, x_2*x_5);|
|                                                                     |
|o2 : Ideal of R                                                      |
+---------------------------------------------------------------------+
|i3 : isUnmixed I                                                     |
|                                                                     |
|o3 = false                                                           |
+---------------------------------------------------------------------+

References
==========

[SM] H. Saremi and A. Mafi. Unmixedness and Arithmetic Properties of Matroidal
Ideals. Arch. Math. 114 (2020) 299-304.

See also
========

  * CheckUnmixed -- check whether ideals encountered are
    unmixed
  * isGVD -- checks whether an ideal is geometrically vertex
    decomposable
  * IsIdealUnmixed -- specify whether an ideal is
    unmixed
  * isLexCompatiblyGVD -- checks whether an ideal is
    <-compatibly geometrically vertex decomposable for a given order
  * isWeaklyGVD -- checks whether an ideal is weakly
    geometrically vertex decomposable

Ways to use isUnmixed :
=======================

  * "isUnmixed(Ideal)"

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

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

isWeaklyGVD -- checks whether an ideal is weakly geometrically vertex decomposable
**********************************************************************************

Synopsis
========

  * Usage:
        isWeaklyGVD I
  * Inputs:
      * I, an ideal (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * CheckUnmixed, => ..., default value true, check
        whether ideals encountered are unmixed
      * IsIdealUnmixed, => ..., default value false,
        specify whether an ideal is unmixed
      * Verbose, => ..., default value false, print additional
        output
  * Outputs:
      * a Boolean value (Macaulay2Doc),

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

This function tests whether an ideal $I \subseteq k[x_1,\ldots,x_n]$ is weakly
geometrically vertex decomposable [KR, Definition 4.6].

See isGVD, for the definition of the ideals $C_{y,I}$ and
$N_{y,I}$ used below. Furthermore, we say that a geometric vertex decomposition
is degenerate if $C_{y,I} = \langle 1 \rangle$ or if $\sqrt{C_{y,I}} =
\sqrt{N_{y,I}}$. The geometric vertex decomposition is nondegenerate otherwise.

An ideal $I \subseteq R = k[x_1, \ldots, x_n]$ is weakly geometrically vertex
decomposable if $I$ is unmixed and

(1) $I = \langle 1 \rangle$, or $I$ is generated by a (possibly empty) subset
of variables of $R$, or

(2) (Degenerate Case) for some variable $y = x_j$ of $R$, ${\rm in}_y(I) =
C_{y,I} \cap (N_{y,I} + \langle y \rangle)$ is a degenerate geometric vertex
decomposition and the contraction of $N_{y,I}$ to the ring
$k[x_1,\ldots,\hat{y},\ldots,x_n]$ is weakly geometrically vertex decomposable,
or

(3) (Nondegenerate Case) for some variable $y = x_j$ of $R$,  ${\rm in}_y(I) =
C_{y,I} \cap (N_{y,I} + \langle y \rangle)$ is a nondegenerate geometric vertex
decomposition, the contraction of $C_{y,I}$ to the ring
$k[x_1,\ldots,\hat{y},\ldots,x_n]$ is weakly geometrically vertex decomposable,
and $N_{y,I}$ is radical and Cohen-Macaulay.

The following example is [KR, Example 4.10]. It is an example of an ideal that
is weakly geometrically vertex decomposable, but not geometrically vertex
decomposable.

+------------------------------------------------------------------+
|i1 : R = QQ[x,y,z,w,r,s];                                         |
+------------------------------------------------------------------+
|i2 : I = ideal(y*(z*s - x^2), y*w*r, w*r*(x^2 + s^2 + z^2 + w*r));|
|                                                                  |
|o2 : Ideal of R                                                   |
+------------------------------------------------------------------+
|i3 : isWeaklyGVD I                                                |
|                                                                  |
|o3 = true                                                         |
+------------------------------------------------------------------+
|i4 : isGVD I                                                      |
|                                                                  |
|o4 = false                                                        |
+------------------------------------------------------------------+

References
==========

[KR] P. Klein and J. Rajchgot. Geometric Vertex Decomposition and Liaison.
Forum of Math, Sigma, 9 (2021) e70:1-23.

See also
========

  * CheckUnmixed -- check whether ideals encountered are
    unmixed
  * isGeneratedByIndeterminates -- checks
    whether the ideal is generated by indeterminates
  * isGVD -- checks whether an ideal is geometrically vertex
    decomposable
  * IsIdealUnmixed -- specify whether an ideal is
    unmixed
  * isLexCompatiblyGVD -- checks whether an ideal is
    <-compatibly geometrically vertex decomposable for a given order
  * isUnmixed -- checks whether an ideal is unmixed
  * oneStepGVD -- computes a geometric vertex decomposition
  * Verbose -- print additional output

Ways to use isWeaklyGVD :
=========================

  * "isWeaklyGVD(Ideal)"

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

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

NyI -- computes the ideal $N_{y,I}$ for a given ideal and indeterminate
***********************************************************************

Synopsis
========

  * Usage:
        NyI(I, y)
  * Inputs:
      * I, an ideal (Macaulay2Doc),
      * y, a ring element (Macaulay2Doc), an indeterminate
        in the ring
  * Optional inputs (Macaulay2Doc),:
      * CheckUnmixed, => ..., default value true, check
        whether ideals encountered are unmixed
  * Outputs:
      * an ideal (Macaulay2Doc),

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

Let $y$ be a variable of the polynomial ring $R = k[x_1,\ldots,x_n]$. A
monomial ordering $<$ on $R$ is said to be $y$-compatible if the initial term
of $f$ satisfies ${\rm in}_<(f) = {\rm in}_<({\rm in}_y(f))$ for all $f \in R$.
Here, ${\rm in}_y(f)$ is the initial $y$-form of $f$, that is, if $f = \sum_i
\alpha_iy^i$ and $\alpha_d \neq 0$ but $\alpha_t = 0$ for all $t >d$, then
${\rm in}_y(f) = \alpha_d y^d$.

Given an ideal $I$ and a $y$-compatible monomial ordering $<$, let $G(I) = \{
g_1,\ldots,g_m\}$ be a Gröbner basis of $I$ with respect to this ordering.  For
$i=1,\ldots,m$, write $g_i$ as $g_i = y^{d_i}q_i + r_i$, where $y$ does not
divide any term of $q_i$; that is, ${\rm in}_y(g_i) = y^{d_i}q_i$.   Given this
setup, the ideal $N_{y,I}$ is given by $$N_{y,I} = \langle q_i ~|~ d_i =
0\rangle$$ This functions  takes an ideal $I$ and variable $y$, and returns
$N_{y,I}$

The ideal $N_{y,I}$ does not depend upon the choice of the Gröbner basis or a
particular $y$-compatible order (see comment after [KR, Definition 2.3]). When
computing $N_{y,I}$ we use a lexicographical ordering on $R$ where $y > x_j$
for all $i \neq j$ if $y = x_i$ since this gives us a $y$-compatible order.

The ideal $I$ in the example below is the edge ideal of the complete graph
$K_4$. For more on edge ideals, see the EdgeIdeals package.

+-----------------------------------------------------------------------------+
|i1 : R = QQ[a,b,c,d];                                                        |
+-----------------------------------------------------------------------------+
|i2 : I = ideal(a*b, a*c, a*d, b*c, b*d, c*d); -- edge ideal of a complete    |
|                                                                             |
|o2 : Ideal of R                                                              |
|-----------------------------------------------------------------------------|
|graph K_4, a chordal graph                                                   |
+-----------------------------------------------------------------------------+
|i3 : NyI(I, b)                                                               |
|                                                                             |
|o3 = ideal (c*d, a*d, a*c)                                                   |
|                                                                             |
|o3 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i4 : L = oneStepGVD(I, b);                                                   |
+-----------------------------------------------------------------------------+
|i5 : L_2 == NyI(I, b) -- NyI is the second element in the list given by      |
|                                                                             |
|o5 = true                                                                    |
|-----------------------------------------------------------------------------|
|oneStepGVD                                                                   |
+-----------------------------------------------------------------------------+

References
==========

[KR] P. Klein and J. Rajchgot. Geometric Vertex Decomposition and Liaison.
Forum of Math, Sigma, 9 (2021) e70:1-23.

Caveat
======

This method is a shortcut to extract the ideal $N_{y,I}$ as computed in
oneStepGVD. That is, to compute $N_{y,I}$, oneStepGVD is called in
the background. As a result, work is also done in the background to compute
$C_{y,I}$ at the same time, and as such, we encourage calling oneStepGVD
directly if we want both the $C_{y,I}$ and $N_{y,I}$ ideals to avoid performing
the same computation twice.

See also
========

  * CheckUnmixed -- check whether ideals encountered are
    unmixed
  * CyI -- computes the ideal $C_{y,I}$ for a given ideal and
    indeterminate
  * getGVDIdeal -- computes the $C_{y,I}$ or $N_{y,I}$
    ideal at any point in the GVD recursion tree
  * oneStepGVD -- computes a geometric vertex decomposition

Ways to use NyI :
=================

  * "NyI(Ideal,RingElement)"

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

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

oneStepGVD -- computes a geometric vertex decomposition
*******************************************************

Synopsis
========

  * Usage:
        oneStepGVD(I, y)
  * Inputs:
      * I, an ideal (Macaulay2Doc),
      * y, a ring element (Macaulay2Doc), an indeterminate
        in the ring
  * Optional inputs (Macaulay2Doc),:
      * CheckDegenerate, => ..., default value false,
        check whether the geometric vertex decomposition is degenerate
      * CheckUnmixed, => ..., default value true, check
        whether ideals encountered are unmixed
      * Verbose, => ..., default value false, print additional
        output
  * Outputs:
      * a sequence (Macaulay2Doc), containing whether the
        $C_{y,I}$ and $N_{y,I}$ ideals form a valid geometric vertex
        decomposition, these ideals $C_{y,I}$ and $N_{y,I}$, and if
        CheckDegenerate=>true, whether the one-step decomposition is degenerate
        or nondegenerate

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

This function computes a geometric vertex decomposition of an ideal based upon
work of Knutson, Miller, and Yong [KMY, Theorem 2.1].  Geometric vertex
decomposition is the key step in the recursive definition of geometrically
vertex decomposable ideals.  The function oneStepGVD is repeatedly used by
isGVD, to determine if an ideal is a geometrically vertex
decomposable ideal.

Let $y$ be a variable of the polynomial ring $R = k[x_1,\ldots,x_n]$. A
monomial ordering $<$ on $R$ is said to be $y$-compatible if the initial term
of $f$ satisfies ${\rm in}_<(f) = {\rm in}_<({\rm in}_y(f))$ for all $f \in R$.
Here, ${\rm in}_y(f)$ is the initial $y$-form of $f$, that is, if $f = \sum_i
\alpha_iy^i$ and $\alpha_d \neq 0$ but $\alpha_t = 0$ for all $t >d$, then
${\rm in}_y(f) = \alpha_d y^d$. We set ${\rm in}_y(I) = \langle {\rm in}_y(f)
~|~ f \in I \rangle$ to be the ideal generated by all the initial $y$-forms in
$I$.

Given an ideal $I$ and a $y$-compatible monomial ordering $<$, let $G(I) = \{
g_1,\ldots,g_m\}$ be a Gröbner basis of $I$ with respect to this ordering.  For
$i=1,\ldots,m$, write $g_i$ as $g_i = y^{d_i}q_i + r_i$, where $y$ does not
divide any term of $q_i$; that is, ${\rm in}_y(g_i) = y^{d_i}q_i$.   Given this
setup, we define two ideals: $$C_{y,I} = \langle q_1,\ldots,q_m\rangle$$ and
$$N_{y,I} = \langle q_i ~|~ d_i = 0 \rangle.$$

If ${\rm in}_y(I) = C_{y,I} \cap (N_{y,I} + \langle y \rangle),$ then we call
this decomposition a geometric vertex decomposition of $I$.

Furthermore, we say that a geometric vertex decomposition is degenerate if
$C_{y,I} = \langle 1 \rangle$ or if $\sqrt{C_{y,I}} = \sqrt{N_{y,I}}$. The
geometric vertex decomposition is nondegenerate otherwise.

For a given variable $y$, the function oneStepGVD returns a sequence, where the
first element in the sequence is true or false depending if the given variable
$y$ gives a geometric vertex decomposition of $I$, while the second element is
the ideal $C_{y,I}$ and the third element in the sequence is the ideal
$N_{y,I}$. If CheckDegenerate=>true, then there is a fourth element in the
output, either "degenerate" or "nondegenerate", corresponding to whether the
geometric vertex decomposition is degenerate.

Note:  The ideals $C_{y,I}$ and $N_{y,I}$ do not depend upon the choice of the
Gröbner basis or a particular $y$-compatible order (see comment after
Definition 2.3 of [KR]). When computing $C_{y,I}$ and $N_{y,I}$ we use a
lexicographical ordering on $R$ where $y > x_j$ for all $i \neq j$ if $y = x_i$
since this gives us a $y$-compatible order.

+--------------------------------------+
|i1 : R = QQ[a,b,c,d]                  |
|                                      |
|o1 = R                                |
|                                      |
|o1 : PolynomialRing                   |
+--------------------------------------+
|i2 : f = 3*a*b + 4*b*c+ 16*a*c+18*d   |
|                                      |
|o2 = 3a*b + 16a*c + 4b*c + 18d        |
|                                      |
|o2 : R                                |
+--------------------------------------+
|i3 : i = ideal f                      |
|                                      |
|o3 = ideal(3a*b + 16a*c + 4b*c + 18d) |
|                                      |
|o3 : Ideal of R                       |
+--------------------------------------+
|i4 : oneStepGVD(i, a)                 |
|                                      |
|o4 = (true, ideal(3b + 16c), ideal ())|
|                                      |
|o4 : Sequence                         |
+--------------------------------------+

In the example below, the ideal $I$ is the edge ideal of the complete graph
$K_4$.  We also check if the decomposition is degenerate (see
CheckDegenerate). For more on edge ideals, see the EdgeIdeals
package.

+-----------------------------------------------------------------------------+
|i5 : R = QQ[a,b,c,d];                                                        |
+-----------------------------------------------------------------------------+
|i6 : i = ideal(a*b, a*c, a*d, b*c, b*d, c*d); -- edge ideal of complete graph|
|                                                                             |
|o6 : Ideal of R                                                              |
|-----------------------------------------------------------------------------|
|K_4, a chordal graph                                                         |
+-----------------------------------------------------------------------------+
|i7 : oneStepGVD(i, c, CheckDegenerate=>true)                                 |
|                                                                             |
|o7 = (true, ideal (a*d, b*d, a*b, d, a, b), ideal (a*d, b*d, a*b),           |
|     ------------------------------------------------------------------------|
|     nondegenerate)                                                          |
|                                                                             |
|o7 : Sequence                                                                |
+-----------------------------------------------------------------------------+

The example below is the toric ideal of a graph such that the quotient ring is
not Cohen-Macaulay.  By [KR, Lemma 2.6], for an ideal $I$ to have a geometric
vertex decomposition with respect to the variable $y$, no term of the Gröbner
bases can be divided by $y^2$.  In this example, the Gröbner basis of $I$
contains an element with a term divisible by $e_1^2$. So $I$ does not have a
geometric vertex decomposition with respect to $y = e_1$. For background on
toric ideals of graphs, see [CDSRVT, Section 3].

+-----------------------------------------------------------------------------+
|i8 : R = QQ[e_1..e_10];                                                      |
+-----------------------------------------------------------------------------+
|i9 : i = ideal(e_1*e_4-e_2*e_3, e_2^2*e_7*e_8*e_9-e_4^2*e_5*e_6*e_10,        |
|                                                                             |
|o9 : Ideal of R                                                              |
|-----------------------------------------------------------------------------|
|e_1*e_2*e_7*e_8*e_9-e_3*e_4*e_5*e_6*e_10,                                    |
|-----------------------------------------------------------------------------|
|e_1^2*e_7*e_8*e_9-e_3^2*e_5*e_6*e_10);                                       |
+-----------------------------------------------------------------------------+
|i10 : mingens gb i                                                           |
|                                                                             |
|o10 = | e_2e_3-e_1e_4 e_2^2e_7e_8e_9-e_4^2e_5e_6e_10                         |
|      -----------------------------------------------------------------------|
|      e_1e_2e_7e_8e_9-e_3e_4e_5e_6e_10 e_1^2e_7e_8e_9-e_3^2e_5e_6e_10 |      |
|                                                                             |
|              1       4                                                      |
|o10 : Matrix R  <--- R                                                       |
+-----------------------------------------------------------------------------+
|i11 : oneStepGVD(i, e_1)                                                     |
|                                                                             |
|                      2          2                                           |
|o11 = (false, ideal (e e e e  - e e e e  , e , e e e e , e e e ),            |
|                      2 7 8 9    4 5 6 10   4   2 7 8 9   7 8 9              |
|      -----------------------------------------------------------------------|
|             2          2                                                    |
|      ideal(e e e e  - e e e e  ))                                           |
|             2 7 8 9    4 5 6 10                                             |
|                                                                             |
|o11 : Sequence                                                               |
+-----------------------------------------------------------------------------+

References
==========

[CDSRVT] M. Cummings, S. Da Silva, J. Rajchgot, and A. Van Tuyl. Geometric
Vertex Decomposition and Liaison for Toric Ideals of Graphs. Preprint,
arXiv:2207.06391 (see https://arxiv.org/abs/2207.06391 ) (2022).

[KMY] A. Knutson, E. Miller, and A. Yong. Gröbner Geometry of Vertex
Decompositions and of Flagged Tableaux. J. Reine Angew. Math. 630 (2009) 1–31.

[KR] P. Klein and J. Rajchgot. Geometric Vertex Decomposition and Liaison.
Forum of Math, Sigma, 9 (2021) e70:1-23.

See also
========

  * CheckDegenerate -- check whether the geometric
    vertex decomposition is degenerate
  * CheckUnmixed -- check whether ideals encountered are
    unmixed
  * CyI -- computes the ideal $C_{y,I}$ for a given ideal and
    indeterminate
  * getGVDIdeal -- computes the $C_{y,I}$ or $N_{y,I}$
    ideal at any point in the GVD recursion tree
  * isGVD -- checks whether an ideal is geometrically vertex
    decomposable
  * isLexCompatiblyGVD -- checks whether an ideal is
    <-compatibly geometrically vertex decomposable for a given order
  * isWeaklyGVD -- checks whether an ideal is weakly
    geometrically vertex decomposable
  * NyI -- computes the ideal $N_{y,I}$ for a given ideal and
    indeterminate
  * Verbose -- print additional output

Ways to use oneStepGVD :
========================

  * "oneStepGVD(Ideal,RingElement)"

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

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

OnlyDegenerate -- restrict to degenerate geometric vertex decompositions
************************************************************************

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

Set to true to restrict the output of findOneStepGVD, to
return only the indeterminates for which their geometric vertex decomposition
is degenerate. Default value false.

See also
========

  * findOneStepGVD -- for which indeterminates does
    there exist a geometric vertex decomposition
  * OnlyNondegenerate -- restrict to nondegenerate
    geometric vertex decompositions

Functions with optional argument named OnlyDegenerate :
=======================================================

  * "findOneStepGVD(...,OnlyDegenerate=>...)"

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

The object OnlyDegenerate, is a symbol (Macaulay2Doc).

OnlyNondegenerate -- restrict to nondegenerate geometric vertex decompositions
******************************************************************************

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

Set to true to restrict the output of findOneStepGVD, to
return only the indeterminates for which their geometric vertex decomposition
is nondegenerate. Default value false.

See also
========

  * findOneStepGVD -- for which indeterminates does
    there exist a geometric vertex decomposition
  * OnlyDegenerate -- restrict to degenerate geometric
    vertex decompositions

Functions with optional argument named OnlyNondegenerate :
==========================================================

  * "findOneStepGVD(...,OnlyNondegenerate=>...)"

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

The object OnlyNondegenerate, is a symbol (Macaulay2Doc).

Verbose -- print additional output
**********************************

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

If true, prints intermediate steps taken. Otherwise, prints nothing.

+--------------------------------+
|i1 : R = QQ[x,y,z]              |
|                                |
|o1 = R                          |
|                                |
|o1 : PolynomialRing             |
+--------------------------------+
|i2 : I = ideal(x-y, x-z)        |
|                                |
|o2 = ideal (x - y, x - z)       |
|                                |
|o2 : Ideal of R                 |
+--------------------------------+
|i3 : isGVD I                    |
|                                |
|o3 = true                       |
+--------------------------------+
|i4 : isGVD(I, Verbose=>true)    |
|ideal(x-y,x-z)                  |
|-- decomposing with respect to x|
|-- C = ideal(y-z,1)             |
|-- N = ideal(y-z)               |
|ideal(y-z,1)                    |
|-- unit ideal                   |
|ideal(y-z)                      |
|-- decomposing with respect to y|
|-- C = ideal 1                  |
|-- N = ideal()                  |
|ideal 1                         |
|-- unit ideal                   |
|ideal()                         |
|-- zero ideal                   |
|                                |
|o4 = true                       |
+--------------------------------+

See also
========

  * isGVD -- checks whether an ideal is geometrically vertex
    decomposable
  * isLexCompatiblyGVD -- checks whether an ideal is
    <-compatibly geometrically vertex decomposable for a given order
  * isWeaklyGVD -- checks whether an ideal is weakly
    geometrically vertex decomposable
  * oneStepGVD -- computes a geometric vertex decomposition

Functions with optional argument named Verbose :
================================================

  * "isGVD(...,Verbose=>...)"
  * "isLexCompatiblyGVD(...,Verbose=>...)"
  * "isWeaklyGVD(...,Verbose=>...)"
  * "oneStepGVD(...,Verbose=>...)"

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

The object Verbose, is a symbol (Macaulay2Doc).

yInit -- computes the ideal of initial y-forms
**********************************************

Synopsis
========

  * Usage:
        yInit(I, y)
  * Inputs:
      * I, an ideal (Macaulay2Doc),
      * y, a ring element (Macaulay2Doc), an indeterminate
        in the ring
  * Outputs:
      * an ideal (Macaulay2Doc),

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

Let $y$ be a variable of the polynomial ring $R = k[x_1,\ldots,x_n]$. A
monomial ordering $<$ on $R$ is said to be $y$-compatible if the initial term
of $f$ satisfies ${\rm in}_<(f) = {\rm in}_<({\rm in}_y(f))$ for all $f \in R$.
Here, ${\rm in}_y(f)$ is the initial $y$-form of $f$, that is, if $f = \sum_i
\alpha_iy^i$ and $\alpha_d \neq 0$ but $\alpha_t = 0$ for all $t >d$, then
${\rm in}_y(f) = \alpha_d y^d$. We set ${\rm in}_y(I) = \langle {\rm in}_y(f)
~|~ f \in I \rangle$ to be the ideal generated by all the initial $y$-forms in
$I$

This routine computes the ideal of initial $y$-forms ${\rm in}_y(I)$.

For more on the definition of initial $y$-forms or their corresponding ideals,
see [KMY, Section 2.1]. The following example is [KR, Example 2.16].

+------------------------------------------------------------------+
|i1 : R = QQ[x,y,z,w,r,s]                                          |
|                                                                  |
|o1 = R                                                            |
|                                                                  |
|o1 : PolynomialRing                                               |
+------------------------------------------------------------------+
|i2 : I = ideal(y*(z*s - x^2), y*w*r, w*r*(z^2 + z*x + w*r + s^2)) |
|                                                                  |
|               2                             2       2 2        2 |
|o2 = ideal (- x y + y*z*s, y*w*r, x*z*w*r + z w*r + w r  + w*r*s )|
|                                                                  |
|o2 : Ideal of R                                                   |
+------------------------------------------------------------------+
|i3 : yInit(I, y)                                                  |
|                                                                  |
|                       2       2 2        2          2            |
|o3 = ideal (x*z*w*r + z w*r + w r  + w*r*s , y*w*r, x y - y*z*s)  |
|                                                                  |
|o3 : Ideal of R                                                   |
+------------------------------------------------------------------+

References
==========

[KMY] A. Knutson, E. Miller, and A. Yong. Gröbner Geometry of Vertex
Decompositions and of Flagged Tableaux. J. Reine Angew. Math. 630 (2009) 1–31.

[KR] P. Klein and J. Rajchgot. Geometric Vertex Decomposition and Liaison.
Forum of Math, Sigma, 9 (2021) e70:1-23.

See also
========

  * oneStepGVD -- computes a geometric vertex decomposition

Ways to use yInit :
===================

  * "yInit(Ideal,RingElement)"

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

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