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

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 Sergio Da Silva, Megumi Harada, Patricia Klein, and Jenna Rajchgot for
feedback and suggestions. Additionally, we thank the anonymous referees of the
paper [CVT] for their concrete suggestions that significantly improved that
manuscript and this package. Cummings was partially supported by an NSERC USRA
and CGS-M and a Milos Novotny Fellowship. Van Tuyl's research is partially
supported by NSERC Discovery Grant 2019-05412.

References
==========

[CDSRVT] Mike Cummings, Sergio Da Silva, Jenna Rajchgot, and Adam Van Tuyl.
Geometric vertex decomposition and liaison for toric ideals of graphs. Algebr.
Comb., 6 (2023), no. 4, 965–997.

[CVT] Mike Cummings and Adam Van Tuyl. The GeometricDecomposability package for
Macaulay2. J. Softw. Algebra Geom., 14 (2024), no. 1, 41–50.

[DSH] Sergio Da Silva and Megumi Harada. Geometric vertex decomposition,
Gröbner bases, and Frobenius splittings for regular nilpotent Hessenberg
Varieties. Transform. Groups, 2023.

[KMY] Allen Knutson, Ezra Miller, and Alexander Yong. Gröbner geometry of
vertex decompositions and of flagged tableaux. J. Reine Angew. Math. 630
(2009), 1–-31.

[KR] Patricia Klein and Jenna Rajchgot. Geometric vertex decomposition and
liaison. Forum Math. Sigma, 9 (2021) Paper No. e70, 23pp.

[SM] Hero Saremi and Amir Mafi. Unmixedness and arithmetic properties of
matroidal ideals. Arch. Math. 114 (2020), no. 3 299–-304.

Authors
=======

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

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

Version 1.2 of this package was accepted for publication in volume 14 (see
https://msp.org/jsag/2024/14-1/ ) of Journal of Software for Algebra and
Geometry (see https://msp.org/jsag/ ) on 2024-01-23, in the article The
GeometricDecomposability package for Macaulay2 (see
https://msp.org/jsag/2024/14-1/p06.xhtml ) (DOI: 10.2140/jsag.2024.14.41 (see
https://doi.org/10.2140/jsag.2024.14.41 )). That version can be obtained from
the journal (see https://msp.org/jsag/2024/14-1/jsag-v14-n1-x06-
GeometricDecomposability.m2 ).

Version
=======

This documentation describes version 1.4.3 of GeometricDecomposability,
released June 10, 2025.

Citation
========

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

+-----------------------------------------------------------------------------+
|@misc{GeometricDecomposabilitySource,                                        |
|  title = {{GeometricDecomposability: checking whether ideals are geometrical|
|  author = {Mike Cummings and Adam Van Tuyl},                                |
|  howpublished = {A \emph{Macaulay2} package available at                    |
|    \url{https://github.com/Macaulay2/M2/tree/stable/M2/Macaulay2/packages}} |
|}                                                                            |
|                                                                             |
|@article{GeometricDecomposabilityArticle,                                    |
|  title = {{The GeometricDecomposability package for \emph{Macaulay2}}},     |
|  author = {Mike Cummings and Adam Van Tuyl},                                |
|  journal = {Journal of Software for Algebra and Geometry},                  |
|  volume = {14},                                                             |
|  year = {2024},                                                             |
|}                                                                            |
|-----------------------------------------------------------------------------|
|ly vertex decomposable. Version~1.4.3}},                                     |
+-----------------------------------------------------------------------------+

Exports
=======

  * Functions and commands
      * 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
      * initialYForms -- computes the ideal of initial
        y-forms
      * 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
      * oneStepGVD -- computes a geometric vertex
        decomposition
      * oneStepGVDCyI -- computes the ideal $C_{y,I}$
      * oneStepGVDNyI -- computes the ideal $N_{y,I}$
  * Methods
      * "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
      * "initialYForms(Ideal,RingElement)" -- see initialYForms,
        -- computes the ideal of initial y-forms
      * "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
      * "oneStepGVD(Ideal,RingElement)" -- see oneStepGVD, --
        computes a geometric vertex decomposition
      * "oneStepGVDCyI(Ideal,RingElement)" -- see oneStepGVDCyI,
        -- computes the ideal $C_{y,I}$
      * "oneStepGVDNyI(Ideal,RingElement)" -- see oneStepGVDNyI,
        -- computes the ideal $N_{y,I}$
  * 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
      * SquarefreeOnly -- only return the squarefree
        variables from the generators
      * UniversalGB -- whether the generators for an ideal
        form a universal Gröbner basis

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

The object GeometricDecomposability, is a package (Macaulay2Doc),
defined in GeometricDecomposability.m2.

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

The source of this document is in GeometricDecomposability.m2:897:0.

oneStepGVDNyI -- computes the ideal $N_{y,I}$
*********************************************

  * Usage:
        oneStepGVDNyI(I, y)
        deletion(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
      * UniversalGB, => ..., default value false, whether
        the generators for an ideal form a universal Gröbner basis
  * 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 : oneStepGVDNyI(I, b)                                                     |
|                                                                             |
|o3 = ideal (c*d, a*d, a*c)                                                   |
|                                                                             |
|o3 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i4 : L = oneStepGVD(I, b);                                                   |
+-----------------------------------------------------------------------------+
|i5 : L_2 == oneStepGVDNyI(I, b) -- NyI is the second element in the list     |
|                                                                             |
|o5 = true                                                                    |
|-----------------------------------------------------------------------------|
|given by oneStepGVD                                                          |
+-----------------------------------------------------------------------------+

References
==========

[KR] Patricia Klein and Jenna Rajchgot. Geometric vertex decomposition and
liaison. Forum Math. Sigma, 9 (2021) Paper No. e70, 23pp.

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

  * oneStepGVDNyI -- computes the ideal $N_{y,I}$
  * 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
  * oneStepGVDCyI -- computes the ideal $C_{y,I}$
  * oneStepGVDCyI -- computes the ideal $C_{y,I}$
  * oneStepGVD -- computes a geometric vertex decomposition
  * UniversalGB -- whether the generators for an ideal form
    a universal Gröbner basis

Ways to use oneStepGVDNyI:
==========================

  * "oneStepGVDNyI(Ideal,RingElement)"

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

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

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

The source of this document is in GeometricDecomposability.m2:1667:0.

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

  * 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), list containing all the
        lexicographical orders $<$ with respect to which I is $<$-compatibly
        geometrically vertex decomposable

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] Patricia Klein and Jenna Rajchgot. Geometric vertex decomposition and
liaison. Forum Math. Sigma, 9 (2021) Paper No. e70, 23pp.

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

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

The source of this document is in GeometricDecomposability.m2:961:0.

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

  * 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
      * SquarefreeOnly, => ..., default value false, only
        return the squarefree variables from the generators
      * UniversalGB, => ..., default value false, whether
        the generators for an ideal form a universal Gröbner basis
      * Verbose => ..., default value false
  * 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.

The results [KR, Lemma 2.6] and [KR, Lemma 2.12] are used to check whether $I$
has a geometric vertex decomposition with respect to each indeterminate $y$.
First, for each indeterminate $y$ appearing in the ideal, we check whether the
given generators of the ideal are squarefree in $y$. Note that this is a
sufficient but not necessary condition. For the indeterminates $z$ that do not
satisfy this sufficient condition, we compute a Gröbner of $I$ with respect to
a $z$-compatible monomial order, and repeat the squarefree-check for the
entries of this Gröbner basis.

Warning: if SquarefreeOnly=>true, then the options CheckUnmixed,
see OnlyDegenerate, and
OnlyNondegenerate, are ignored.

+-------------------------+
|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] Patricia Klein and Jenna Rajchgot. Geometric vertex decomposition and
liaison. Forum Math. Sigma, 9 (2021) Paper No. e70, 23pp.

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
  * SquarefreeOnly -- only return the squarefree
    variables from the generators
  * UniversalGB -- whether the generators for an ideal form
    a universal Gröbner basis

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

  * "findOneStepGVD(Ideal)"

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

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

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

The source of this document is in GeometricDecomposability.m2:1022:0.

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

  * 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
      * UniversalGB, => ..., default value false, whether
        the generators for an ideal form a universal Gröbner basis
  * 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] Patricia Klein and Jenna Rajchgot. Geometric vertex decomposition and
liaison. Forum Math. Sigma, 9 (2021) Paper No. e70, 23pp.

See also
========

  * CheckUnmixed -- check whether ideals encountered are
    unmixed
  * oneStepGVD -- computes a geometric vertex decomposition
  * oneStepGVDCyI -- computes the ideal $C_{y,I}$
  * oneStepGVDNyI -- computes the ideal $N_{y,I}$
  * UniversalGB -- whether the generators for an ideal form
    a universal Gröbner basis

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

  * "getGVDIdeal(Ideal,List)"

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

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

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

The source of this document is in GeometricDecomposability.m2:1073:0.

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

  * Usage:
        initialYForms(I, y)
  * Inputs:
      * I, an ideal (Macaulay2Doc),
      * y, a ring element (Macaulay2Doc), an indeterminate
        in the ring
  * Optional inputs (Macaulay2Doc),:
      * UniversalGB, => ..., default value false, whether
        the generators for an ideal form a universal Gröbner basis
  * 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 : initialYForms(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] Allen Knutson, Ezra Miller, and Alexander Yong. Gröbner geometry of
vertex decompositions and of flagged tableaux. J. Reine Angew. Math. 630
(2009), 1–-31.

[KR] Patricia Klein and Jenna Rajchgot. Geometric vertex decomposition and
liaison. Forum Math. Sigma, 9 (2021) Paper No. e70, 23pp.

See also
========

  * oneStepGVD -- computes a geometric vertex decomposition
  * UniversalGB -- whether the generators for an ideal form
    a universal Gröbner basis

Ways to use initialYForms:
==========================

  * "initialYForms(Ideal,RingElement)"

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

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

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

The source of this document is in GeometricDecomposability.m2:1119:0.

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

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

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

The source of this document is in GeometricDecomposability.m2:1151:0.

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

  * Usage:
        isGVD I
  * Inputs:
      * I, an ideal (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * CheckCM, => ..., default value "always", 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
      * UniversalGB, => ..., default value false, whether
        the generators for an ideal form a universal Gröbner basis
      * Verbose => ..., default value false
  * 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)                                                 |
|I = 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)                                                    |
|I = ideal(c*d,b*d,b*c)                                                       |
|-- decomposing with respect to b                                             |
|-- C = ideal(c*d,d,c)                                                        |
|-- N = ideal(c*d)                                                            |
|I = ideal(c*d)                                                               |
|-- decomposing with respect to c                                             |
|-- C = ideal d                                                               |
|-- N = ideal()                                                               |
|I = ideal()                                                                  |
|-- zero ideal                                                                |
|I = ideal d                                                                  |
|-- generated by indeterminates                                               |
|I = ideal(c*d,d,c)                                                           |
|-- decomposing with respect to c                                             |
|-- C = ideal(d,1)                                                            |
|-- N = ideal d                                                               |
|I = ideal d                                                                  |
|-- generated by indeterminates                                               |
|I = ideal(d,1)                                                               |
|-- unit ideal                                                                |
|I = ideal(c*d,b*d,b*c,d,c,b)                                                 |
|-- decomposing with respect to b                                             |
|-- C = ideal(d,c,1)                                                          |
|-- N = ideal(d,c)                                                            |
|I = ideal(d,c)                                                               |
|-- generated by indeterminates                                               |
|I = ideal(d,c,1)                                                             |
|-- unit 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] Mike Cummings, Sergio Da Silva, Jenna Rajchgot, and Adam Van Tuyl.
Geometric vertex decomposition and liaison for toric ideals of graphs. Algebr.
Comb., 6 (2023), no. 4, 965–997.

[KMY] Allen Knutson, Ezra Miller, and Alexander Yong. Gröbner geometry of
vertex decompositions and of flagged tableaux. J. Reine Angew. Math. 630
(2009), 1–-31.

[KR] Patricia Klein and Jenna Rajchgot. Geometric vertex decomposition and
liaison. Forum Math. Sigma, 9 (2021) Paper No. e70, 23pp.

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
  * UniversalGB -- whether the generators for an ideal form
    a universal Gröbner basis
  * Verbose (Macaulay2Doc) -- an optional argument

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

  * "isGVD(Ideal)"

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

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

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

The source of this document is in GeometricDecomposability.m2:1264:0.

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

  * Usage:
        isLexCompatiblyGVD(I, L)
  * Inputs:
      * I, an ideal (Macaulay2Doc),
      * L, a list (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * CheckCM, => ..., default value "always", 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
      * UniversalGB, => ..., default value false, whether
        the generators for an ideal form a universal Gröbner basis
      * Verbose => ..., default value false
  * 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)          |
|I = 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)     |
|initial ideal = ideal(w*y*r,s*y*z,s^2*w*r)                        |
|I = ideal(w*y*r,s*y*z,s^2*w*r)                                    |
|-- decomposing with respect to s                                  |
|Warning: not a valid geometric vertex decomposition               |
|                                                                  |
|o4 = false                                                        |
+------------------------------------------------------------------+

In view of [KR, Proposition 2.14], we check whether the initial ideal ${\rm
in}_<(I)$ is $<$-compatibly geometrically vertex decomposable. Heuristically,
one should expect this check to be quicker than the definition [KR, Definition
2.11] since checking unmixedness (that is, computing a primary decomposition)
is in general faster for monomial ideals.

References
==========

[KR] Patricia Klein and Jenna Rajchgot. Geometric vertex decomposition and
liaison. Forum Math. Sigma, 9 (2021) Paper No. e70, 23pp.

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
  * UniversalGB -- whether the generators for an ideal form
    a universal Gröbner basis
  * Verbose (Macaulay2Doc) -- an optional argument

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

  * "isLexCompatiblyGVD(Ideal,List)"

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

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

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

The source of this document is in GeometricDecomposability.m2:1328:0.

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

  * 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, that is,
whether 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] Hero Saremi and Amir Mafi. Unmixedness and arithmetic properties of
matroidal ideals. Arch. Math. 114 (2020), no. 3 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).

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

The source of this document is in GeometricDecomposability.m2:1363:0.

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

  * 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
      * UniversalGB, => ..., default value false, whether
        the generators for an ideal form a universal Gröbner basis
      * Verbose => ..., default value false
  * 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. 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] Patricia Klein and Jenna Rajchgot. Geometric vertex decomposition and
liaison. Forum Math. Sigma, 9 (2021) Paper No. e70, 23pp.

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
  * UniversalGB -- whether the generators for an ideal form
    a universal Gröbner basis
  * Verbose (Macaulay2Doc) -- an optional argument

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

  * "isWeaklyGVD(Ideal)"

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

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

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

The source of this document is in GeometricDecomposability.m2:1422:0.

oneStepGVDCyI -- computes the ideal $C_{y,I}$
*********************************************

  * Usage:
        oneStepGVDCyI(I, y)
        link(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
      * UniversalGB, => ..., default value false, whether
        the generators for an ideal form a universal Gröbner basis
  * 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 : oneStepGVDCyI(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 == oneStepGVDCyI(I, b) -- CyI is the second element in the list     |
|                                                                             |
|o5 = true                                                                    |
|-----------------------------------------------------------------------------|
|given by oneStepGVD                                                          |
+-----------------------------------------------------------------------------+

References
==========

[KR] Patricia Klein and Jenna Rajchgot. Geometric vertex decomposition and
liaison. Forum Math. Sigma, 9 (2021) Paper No. e70, 23pp.

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

  * oneStepGVDNyI -- computes the ideal $N_{y,I}$
  * 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
  * oneStepGVDCyI -- computes the ideal $C_{y,I}$
  * oneStepGVD -- computes a geometric vertex decomposition
  * oneStepGVDNyI -- computes the ideal $N_{y,I}$
  * UniversalGB -- whether the generators for an ideal form
    a universal Gröbner basis

Ways to use oneStepGVDCyI:
==========================

  * "oneStepGVDCyI(Ideal,RingElement)"

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

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

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

The source of this document is in GeometricDecomposability.m2:1599:0.

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

  * 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
      * UniversalGB, => ..., default value false, whether
        the generators for an ideal form a universal Gröbner basis
      * Verbose => ..., default value false
  * Outputs:
      * a sequence (Macaulay2Doc), containing whether the
        $C_{y,I}$ and $N_{y,I}$ ideals form a valid geometric vertex
        decomposition, the 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] Mike Cummings, Sergio Da Silva, Jenna Rajchgot, and Adam Van Tuyl.
Geometric vertex decomposition and liaison for toric ideals of graphs. Algebr.
Comb., 6 (2023), no. 4, 965–997.

[KMY] Allen Knutson, Ezra Miller, and Alexander Yong. Gröbner geometry of
vertex decompositions and of flagged tableaux. J. Reine Angew. Math. 630
(2009), 1–-31.

[KR] Patricia Klein and Jenna Rajchgot. Geometric vertex decomposition and
liaison. Forum Math. Sigma, 9 (2021) Paper No. e70, 23pp.

See also
========

  * CheckDegenerate -- check whether the geometric
    vertex decomposition is degenerate
  * CheckUnmixed -- check whether ideals encountered are
    unmixed
  * 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
  * isLexCompatiblyGVD -- checks whether an ideal is
    <-compatibly geometrically vertex decomposable for a given order
  * isWeaklyGVD -- checks whether an ideal is weakly
    geometrically vertex decomposable
  * oneStepGVDCyI -- computes the ideal $C_{y,I}$
  * oneStepGVDNyI -- computes the ideal $N_{y,I}$
  * UniversalGB -- whether the generators for an ideal form
    a universal Gröbner basis
  * Verbose (Macaulay2Doc) -- an optional argument

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

  * "oneStepGVD(Ideal,RingElement)"

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

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

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

The source of this document is in GeometricDecomposability.m2:1532:0.

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, that is, only for the ideal given in the input; CheckCM=>"always"
(default) for all of the following $C_{y,I}$ and $N_{y,I}$ ideals as well; or
CheckCM=>"never".

In particular, [KR, Corollary 4.5] states that if a homogeneous ideal $I$ is
geometrically vertex decomposable then $I$ must be Cohen-Macaulay.
Equivalently, if a homogeneous ideal $I$ is not Cohen-Macaulay, then it is not
geometrically vertex decomposable. By the Auslander-Buchsbaum formula, if $I$
is homogeneous, then Cohen-Macualayness is equivalent to equality of projective
dimension and codimension, which is in general a quicker check than using isCM
from the Depth, package.

Since the result of [KR, Corollary 4.5] holds only for homogeneous ideals, the
Cohen-Macaulayness is checked only when the given ideal is homogeneous, no
matter the value of CheckCM.

We set the default value for CheckCM to "always" for, if the ideal is
homogeneous, it is quicker to check equality of projective dimension and
codimension than it is to check unmixedness, and Cohen-Macaulay impilies
unmixed. Hence if an ideal is homogeneous, we need only check unmixedness
directly when it is not Cohen-Macaulay.

References
==========

[KR] Patricia Klein and Jenna Rajchgot. Geometric vertex decomposition and
liaison. Forum Math. Sigma, 9 (2021) Paper No. e70, 23pp.

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

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

The source of this document is in GeometricDecomposability.m2:1719:0.

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] Patricia Klein and Jenna Rajchgot. Geometric vertex decomposition and
liaison. Forum Math. Sigma, 9 (2021) Paper No. e70, 23pp.

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

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

The source of this document is in GeometricDecomposability.m2:1760:0.

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] Hero Saremi and Amir Mafi. Unmixedness and arithmetic properties of
matroidal ideals. Arch. Math. 114 (2020), no. 3 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
========

  * oneStepGVDNyI -- computes the ideal $N_{y,I}$
  * 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
  * oneStepGVDCyI -- computes the ideal $C_{y,I}$
  * oneStepGVD -- computes a geometric vertex decomposition
  * oneStepGVDCyI -- computes the ideal $C_{y,I}$
  * oneStepGVDNyI -- computes the ideal $N_{y,I}$

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

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

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

The object CheckUnmixed, is a symbol (Macaulay2Doc).

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

The source of this document is in GeometricDecomposability.m2:1828:0.

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

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

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

If an ideal $I$ is homogeneous and has a geometric vertex decomposition with
respect to an indeterminate $y$, which is to say that ${\rm in}_y(I) = C_{y, I}
\cap (N_{y, I} + \langle y \rangle)$, then both $C_{y, I}$ and $N_{y, I}$ are
also homogeneous. Also, an ideal that is both homogeneous and geometrically
vertex decomposable is Cohen-Macaulay [KR, Corollary 4.5].

References
==========

[KR] Patricia Klein and Jenna Rajchgot. Geometric vertex decomposition and
liaison. Forum Math. Sigma, 9 (2021) Paper No. e70, 23pp.

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

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

The source of this document is in GeometricDecomposability.m2:1859:0.

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

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

The source of this document is in GeometricDecomposability.m2:1892:0.

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. Following the notation of oneStepGVD,
a geometric vertex decomposition is degenerate if either
$\sqrt{C_{y, I}} = \sqrt{N_{y, I}}$ or if $C_{y, I} = \langle 1 \rangle$, and
is nondegenerate otherwise.

See also
========

  * findOneStepGVD -- for which indeterminates does
    there exist a geometric vertex decomposition
  * oneStepGVD -- computes 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).

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

The source of this document is in GeometricDecomposability.m2:1915:0.

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. Following the notation of
oneStepGVD, a geometric vertex decomposition is degenerate if
either $\sqrt{C_{y, I}} = \sqrt{N_{y, I}}$ or if $C_{y, I} = \langle 1
\rangle$, and is nondegenerate otherwise.

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

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

The source of this document is in GeometricDecomposability.m2:1936:0.

SquarefreeOnly -- only return the squarefree variables from the generators
**************************************************************************

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

The algorithm for findOneStepGVD, comprises two steps.
First, it checks the given generators for the given ideal $I$ and creates a
list of all indeterminates which appear squarefree in all of the generators.
For each of the remaining variables $y$, it then computes a Gröbner basis for
$I$ with respect to a $y$-compatible monomial order. If $y$ appears in the
elements of the Gröbner basis with only degree zero or degree one, then we have
a geometric vertex decomposition, and $y$ is appended to the list of
indeterminates.

If SquarefreeOnly=>true, then only the first half of the algorithm runs. This
option is used by the isGVD, and isWeaklyGVD,
functions to avoid unnecessary duplicate computations of Gröbner bases.

See also
========

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

Functions with optional argument named SquarefreeOnly:
======================================================

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

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

The object SquarefreeOnly, is a symbol (Macaulay2Doc).

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

The source of this document is in GeometricDecomposability.m2:1962:0.

UniversalGB -- whether the generators for an ideal form a universal Gröbner basis
*********************************************************************************

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

Let $I \subseteq R = k[x_1, \ldots, x_n]$ be an ideal. A set of generators
$\mathcal G$ for $I$ is a universal Gröbner basis for $I$ if it is a Gröbner
basis for $I$ with respect to any monomial order on $R$. The default value is
always UniversalGB=>false.

Set UniversalGB to true if it is known that the given generators for your ideal
form a universal Gröbner basis. In this case, we can avoid computing Gröbner
bases as geometric vertex decompositions preserve universal Gröbner basis. That
is, if $\{ y^{d_i}q_i + r_i \mid i = 1, \ldots, s \}$ is a universal Gröbner
basis for an ideal $I$, then $\{ q_1, \ldots, q_s \}$ and $\{ q_i \mid d_i = 0
\}$ are universal Gröbner bases for $C_{y,I}$ and $N_{y,I}$ in $k[x_1, \ldots,
\hat y, \ldots, x_n]$, respectively.

Caveat
======

If a universal Gr\"obner basis is not given, the intersection condition ${\rm
in}_y(I) = C_{y,I} \cap (N_{y,I} + \langle y \rangle)$ via the results of [KR,
Lemmas 2.6 and 2.12], which looks at the degree of $y$ in the reduced Gr\"obner
basis of $I$. In general, a universal Gr\"obner basis is not reduced, so the
intersection condition must be checked explicitly. So, although providing a
universal Gr\"obner basis will speed up computing the ideals $C_{y, I}$ and
$N_{y, I}$, it may take longer to verify the intersection condition.

See also
========

  * oneStepGVDNyI -- computes the ideal $N_{y,I}$
  * 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
  * initialYForms -- computes the ideal of initial
    y-forms
  * 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
  * oneStepGVDCyI -- computes the ideal $C_{y,I}$
  * oneStepGVD -- computes a geometric vertex decomposition
  * oneStepGVDCyI -- computes the ideal $C_{y,I}$
  * oneStepGVDNyI -- computes the ideal $N_{y,I}$

Functions with optional argument named UniversalGB:
===================================================

  * "findOneStepGVD(...,UniversalGB=>...)"
  * "getGVDIdeal(...,UniversalGB=>...)"
  * "initialYForms(...,UniversalGB=>...)"
  * "isGVD(...,UniversalGB=>...)"
  * "isLexCompatiblyGVD(...,UniversalGB=>...)"
  * "isWeaklyGVD(...,UniversalGB=>...)"
  * "oneStepGVD(...,UniversalGB=>...)"
  * "oneStepGVDCyI(...,UniversalGB=>...)"
  * "oneStepGVDNyI(...,UniversalGB=>...)"

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

The object UniversalGB, is a symbol (Macaulay2Doc).

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

The source of this document is in GeometricDecomposability.m2:2020:0.