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

FastMinors -- faster linear algebra, especially for computation of minors
*************************************************************************

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

FastMinors is a package for computing relevant minors (determinants of
submatrices) of matrices of polynomial functions quickly

This package provides functionality for doing certain linear algebra operations
over rings quickly.  There is also some multithreaded capability which is
disabled by default.  Note this package was previously called FastLinAlg.

Tutorials:
There are tutorials on how to use various strategies and options in
FastMinorsStrategyTutorial, and
RegularInCodimensionTutorial, which we recommend
the user explore if they are interested in the more advanced features of the
package.

Useful functions:
  * chooseGoodMinors, Tries to find interesting minors
    of a matrix.
  * isRankAtLeast, Tries to show that a matrix has rank at
    least a given number by looking at submatrices
  * regularInCodimension, checks whether a ring is
    regular in codimension n, but doesn't return false.
  * projDim, checks the projective dimension of a module and may
    give better answers than pdim (Macaulay2Doc), in the case that R
    is not homogeneous
  * recursiveMinors, provides a different strategy for
    computing minors of a matrix.  It is a cofactor strategy where the
    determinants of smaller minors are stored.
  * isCodimAtLeast, provides a way for finding lower
    bounds for the codimension of an ideal, without actually computing the
    codimension.
Many of these functions have extensive options for finetuning their behavior,
for instance by controlling how submatrices are chosen.  See the documentation
for StrategyDefault,

Acknowledgements:

The authors would like to thank the anonymous referee, David Eisenbud, Eloisa
Grifo, and Srikanth Iyengar for useful conversations and comments on the
development of this package.

Boyana Martinova received funding from the University of Utah Mathematics
Department REU program and from the ACCESS program at the University of Utah,
while developing this package.
Marcus Robinson received funding from the NSF RTG grant 1246989 while
developing this package.
Karl Schwede received funding from NSF grant 1801849 and a fellowship from the
Simons Foundation while developing this package.
Yuhui (Wei) Yao received funding from the University of Utah Mathematics
Department REU program, while developing this package

Authors
=======

  * Boyana Martinova (see https://sites.google.com/view/bmartinova )
    <martinova@wisc.edu>
  * Marcus Robinson (see https://people.reed.edu/~mrobinso/ )
    <mrobinso@reed.edu>
  * Karl Schwede (see http://www.math.utah.edu/~schwede )
    <schwede@math.utah.edu>
  * Yuhui (Wei) Yao <yuhuiyao4ever@gmail.com>

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

Version 1.2.6 of this package was accepted for publication in volume 13 (see
https://msp.org/jsag/2023/13-1/ ) of Journal of Software for Algebra and
Geometry (see https://msp.org/jsag/ ) on 2023-05-08, in the article FastMinors
package for Macaulay2 (see https://msp.org/jsag/2023/13-1/p02.xhtml ) (DOI:
10.2140/jsag.2023.13.13 (see https://doi.org/10.2140/jsag.2023.13.13 )). That
version can be obtained from the journal (see
https://msp.org/jsag/2023/13-1/jsag-v13-n1-x02-FastMinors.m2 ).

Version
=======

This documentation describes version 1.2.6 of FastMinors, released May 15th,
2023.

Citation
========

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

+-----------------------------------------------------------------------------+
|@misc{FastMinorsSource,                                                      |
|  title = {{FastMinors: faster linear algebra operations. Version~1.2.6}},   |
|  author = {Boyana Martinova and Marcus Robinson and Karl Schwede and Yuhui (|
|  howpublished = {A \emph{Macaulay2} package available at                    |
|    \url{https://github.com/Macaulay2/M2/tree/stable/M2/Macaulay2/packages}} |
|}                                                                            |
|                                                                             |
|@article{FastMinorsArticle,                                                  |
|  title = {{FastMinors package for \emph{Macaulay2}}},                       |
|  author = {Boyana Martinova and Marcus Robinson and Karl Schwede and Yuhui (|
|  journal = {Journal of Software for Algebra and Geometry},                  |
|  volume = {13},                                                             |
|  year = {2023},                                                             |
|}                                                                            |
|-----------------------------------------------------------------------------|
|Wei) Yao},                                                                   |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|Wei) Yao},                                                                   |
+-----------------------------------------------------------------------------+

Exports
=======

  * Functions and commands
      * chooseGoodMinors -- returns an ideal generated
        by interesting minors in a matrix
      * chooseRandomSubmatrix -- returns
        coordinates for a random submatrix
      * chooseSubmatrixLargestDegree, --
        returns coordinates for higher degree submatrix of a matrix
      * chooseSubmatrixSmallestDegree, --
        returns coordinates for low degree submatrix of a matrix
      * getSubmatrixOfRank -- tries to find a
        submatrix of the given rank
      * isCodimAtLeast -- returns true if we can quickly
        see whether the codim is at least a given number
      * isDimAtMost -- returns true if we can quickly see
        whether the dim is at most a given number
      * isRankAtLeast -- determines if the matrix has
        rank at least a number
      * projDim -- finds an upper bound for the projective
        dimension of a module
      * recursiveMinors -- uses a recursive cofactor
        algorithm to compute the ideal of minors of a matrix
      * regularInCodimension -- attempts to show
        that the ring is regular in codimension n
      * reorderPolynomialRing -- produces an
        isomorphic polynomial ring with a different, randomized, monomial order
  * Methods
      * "chooseGoodMinors(ZZ,ZZ,Matrix)" -- see chooseGoodMinors,
        -- returns an ideal generated by interesting minors
        in a matrix
      * "chooseGoodMinors(ZZ,ZZ,Matrix,Ideal)" -- see chooseGoodMinors,
        -- returns an ideal generated by interesting minors
        in a matrix
      * "chooseRandomSubmatrix(ZZ,Matrix)" -- see chooseRandomSubmatrix,
        -- returns coordinates for a random submatrix
      * "chooseSubmatrixLargestDegree(ZZ,Matrix)" -- see
        chooseSubmatrixLargestDegree, -- returns
        coordinates for higher degree submatrix of a matrix
      * "chooseSubmatrixSmallestDegree(ZZ,Matrix)" -- see
        chooseSubmatrixSmallestDegree, --
        returns coordinates for low degree submatrix of a matrix
      * "getSubmatrixOfRank(ZZ,Matrix)" -- see getSubmatrixOfRank,
        -- tries to find a submatrix of the given rank
      * "isCodimAtLeast(ZZ,Ideal)" -- see isCodimAtLeast,
        -- returns true if we can quickly see whether the codim is at least a
        given number
      * "isDimAtMost(ZZ,Ideal)" -- see isDimAtMost, --
        returns true if we can quickly see whether the dim is at most a given
        number
      * "isRankAtLeast(ZZ,Matrix)" -- see isRankAtLeast,
        -- determines if the matrix has rank at least a number
      * "projDim(Module)" -- see projDim, -- finds an upper
        bound for the projective dimension of a module
      * "recursiveMinors(ZZ,Matrix)" -- see recursiveMinors,
        -- uses a recursive cofactor algorithm to compute the
        ideal of minors of a matrix
      * "regularInCodimension(ZZ,Ring)" -- see regularInCodimension,
        -- attempts to show that the ring is regular in
        codimension n
      * "reorderPolynomialRing(Symbol,Ring)" -- see
        reorderPolynomialRing, -- produces an isomorphic
        polynomial ring with a different, randomized, monomial order
  * Symbols
      * "PeriodicCheckFunction" -- see chooseGoodMinors,
        -- returns an ideal generated by interesting minors
        in a matrix
      * DetStrategy -- DetStrategy is a strategy for
        allowing the user to choose how determinants (or rank), is computed
      * "Rank" -- see DetStrategy, -- DetStrategy is a
        strategy for allowing the user to choose how determinants (or rank), is
        computed
      * "Recursive" -- see DetStrategy, -- DetStrategy is a
        strategy for allowing the user to choose how determinants (or rank), is
        computed
      * FastMinorsStrategyTutorial -- How to
        use and construct strategies for selecting submatrices in various
        functions
      * "SPairsFunction" -- see isCodimAtLeast, --
        returns true if we can quickly see whether the codim is at least a
        given number
      * MaxMinors -- an option to control depth of search
      * MinDimension -- an option for projDim
      * Modulus -- an option for regularInCodimension
      * PointOptions -- options to pass to functions in
        the package RandomPoints
      * "MinorsCache" -- see recursiveMinors, -- uses a
        recursive cofactor algorithm to compute the ideal of minors of a matrix
      * "CodimCheckFunction" -- see regularInCodimension,
        -- attempts to show that the ring is regular in
        codimension n
      * "MinMinorsFunction" -- see regularInCodimension,
        -- attempts to show that the ring is regular in
        codimension n
      * "UseOnlyFastCodim" -- see regularInCodimension,
        -- attempts to show that the ring is regular in
        codimension n
      * RegularInCodimensionTutorial -- A
        tutorial for how to use the advanced options of the
        regularInCodimension function
      * "GRevLexLargest" -- see StrategyDefault, --
        strategies for choosing submatrices
      * "GRevLexSmallest" -- see StrategyDefault, --
        strategies for choosing submatrices
      * "GRevLexSmallestTerm" -- see StrategyDefault, --
        strategies for choosing submatrices
      * "LexLargest" -- see StrategyDefault, --
        strategies for choosing submatrices
      * "LexSmallest" -- see StrategyDefault, --
        strategies for choosing submatrices
      * "LexSmallestTerm" -- see StrategyDefault, --
        strategies for choosing submatrices
      * "Points" -- see StrategyDefault, -- strategies
        for choosing submatrices
      * "Random" -- see StrategyDefault, -- strategies
        for choosing submatrices
      * "RandomNonzero" -- see StrategyDefault, --
        strategies for choosing submatrices
  * Other things
      * StrategyCurrent -- strategies for choosing
        submatrices
      * StrategyDefault -- strategies for choosing
        submatrices
      * StrategyDefaultNonRandom -- strategies for
        choosing submatrices
      * StrategyDefaultWithPoints -- strategies for
        choosing submatrices
      * StrategyGRevLexSmallest -- strategies for
        choosing submatrices
      * StrategyLexSmallest -- strategies for choosing
        submatrices
      * StrategyPoints -- strategies for choosing
        submatrices
      * StrategyRandom -- strategies for choosing
        submatrices

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

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

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

The source of this document is in FastMinors.m2:1413:0.

chooseGoodMinors -- returns an ideal generated by interesting minors in a matrix
********************************************************************************

  * Usage:
        chooseGoodMinors(count, minorSize, M)
        chooseGoodMinors(count, minorSize, M, I)
  * Inputs:
      * count, an integer (Macaulay2Doc),
      * minorSize, an integer (Macaulay2Doc),
      * M, a matrix (Macaulay2Doc),
      * I, an ideal (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * PeriodicCheckFunction => a function (Macaulay2Doc),
        default value null, a function whose argument is the ideal of minors
        computed so far and which outputs whether the chooseGoodMinors should
        continue
      * PointOptions, => a list (Macaulay2Doc),
        default value {Strategy => Default, Homogeneous => false, Replacement
        => Binomial, ExtendField => true, PointCheckAttempts => 0,
        DecompositionStrategy => Decompose, NumThreadsToUse => 1,
        DimensionFunction => dim, Verbose => false}, options to be passed to
        the RandomPoints package
      * DetStrategy, => ..., default value Cofactor,
        DetStrategy is a strategy for allowing the user to choose how
        determinants (or rank), is computed
      * Strategy, => ..., default value new OptionTable
        from {Points => 0, Random => 16, GRevLexLargest => 0, LexSmallestTerm
        => 16, LexLargest => 0, LexSmallest => 16, GRevLexSmallestTerm => 16,
        RandomNonzero => 16, GRevLexSmallest => 16}, strategies for choosing
        submatrices
      * Verbose => ..., default value false
  * Outputs:
      * an ideal (Macaulay2Doc),

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

This returns an ideal generated by approximately count minors of size minorSize
of the matrix M.

+------------------------------------------------------------------+
|i1 : R = QQ[x, y, z];                                             |
+------------------------------------------------------------------+
|i2 : M = matrix{{x,y,0}, {y,z,0}, {0,0,0}}                        |
|                                                                  |
|o2 = | x y 0 |                                                    |
|     | y z 0 |                                                    |
|     | 0 0 0 |                                                    |
|                                                                  |
|             3      3                                             |
|o2 : Matrix R  <-- R                                              |
+------------------------------------------------------------------+
|i3 : chooseGoodMinors(1, 2, M, Strategy=>StrategyDefaultNonRandom)|
|                                                                  |
|              2                                                   |
|o3 = ideal(- y  + x*z)                                            |
|                                                                  |
|o3 : Ideal of R                                                   |
+------------------------------------------------------------------+

The ideal I is used in the Points portion of the Strategy.  Only points where
that ideal vanishes will be considered.

The option PeriodicCheckFunction can be set to a function which will
periodically evaluate the partially computed ideal of minors via the given
function (which should return a boolean value).  If that function returns true
then chooseGoodMinors will terminate.  For instance, one can set it to
periodically check whether the dimension of the ideal is at most zero via
PeriodicCheckFunction => (J -> dim J <= 0).

Ways to use chooseGoodMinors:
=============================

  * "chooseGoodMinors(ZZ,ZZ,Matrix)"
  * "chooseGoodMinors(ZZ,ZZ,Matrix,Ideal)"

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

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

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

The source of this document is in FastMinors.m2:1625:0.

chooseRandomSubmatrix -- returns coordinates for a random submatrix
*******************************************************************

  * Usage:
        chooseRandomSubmatrix(n1, M1)
  * Inputs:
      * n1, an integer (Macaulay2Doc),
      * M1, a matrix (Macaulay2Doc),
  * Outputs:
      * a list (Macaulay2Doc),

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

This returns a list with two entries, first a list of random rows, and then a
list of random columns.  These specify a random submatrix of the desired size,
n1.

+---------------------------------------------------------+
|i1 : R = QQ[x,y,z];                                      |
+---------------------------------------------------------+
|i2 : M=matrix{{x^2,x^3,x^4},{y^4,y^2,y^3},{z^3,z^4,z^2}};|
|                                                         |
|             3      3                                    |
|o2 : Matrix R  <-- R                                     |
+---------------------------------------------------------+
|i3 : chooseRandomSubmatrix(2, M)                         |
|                                                         |
|o3 = {{1, 2}, {2, 1}}                                    |
|                                                         |
|o3 : List                                                |
+---------------------------------------------------------+

Ways to use chooseRandomSubmatrix:
==================================

  * "chooseRandomSubmatrix(ZZ,Matrix)"

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

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

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

The source of this document is in FastMinors.m2:1696:0.

chooseSubmatrixLargestDegree -- returns coordinates for higher degree submatrix of a matrix
*******************************************************************************************

  * Usage:
        chooseSubmatrixLargestDegree(n1, M1)
  * Inputs:
      * n1, an integer (Macaulay2Doc),
      * M1, a matrix (Macaulay2Doc),
  * Outputs:
      * a list (Macaulay2Doc),

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

This returns a list containing two entries, the row and column coordinates in
the original matrix for a specified sized submatrix. In this case, the terms of
that submatrix are likely higher in degree than other terms of the matrix.

+--------------------------------------------------------+
|i1 : R = QQ[x,y,z];                                     |
+--------------------------------------------------------+
|i2 : M=matrix{{x^2,x^3,x^4},{y^4,y^2,y^3},{z^3,z^4,z^2}}|
|                                                        |
|o2 = | x2 x3 x4 |                                       |
|     | y4 y2 y3 |                                       |
|     | z3 z4 z2 |                                       |
|                                                        |
|             3      3                                   |
|o2 : Matrix R  <-- R                                    |
+--------------------------------------------------------+
|i3 : chooseSubmatrixLargestDegree(2, M)                 |
|                                                        |
|o3 = {{0, 1}, {2, 0}}                                   |
|                                                        |
|o3 : List                                               |
+--------------------------------------------------------+

It returns a list with two entries, first a list of row indices, and then a
list of column indices.  In this case, x^4 is the biggest element, and after
removing that row and column from consideration, y^4 is biggest.  Thus we want
rows 0 and 1 and columns 2 and 0.

Ways to use chooseSubmatrixLargestDegree:
=========================================

  * "chooseSubmatrixLargestDegree(ZZ,Matrix)"

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

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

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

The source of this document is in FastMinors.m2:1674:0.

chooseSubmatrixSmallestDegree -- returns coordinates for low degree submatrix of a matrix
*****************************************************************************************

  * Usage:
        chooseSubmatrixSmallestDegree(n1, M3)
  * Inputs:
      * n1, an integer (Macaulay2Doc),
      * M3, a matrix (Macaulay2Doc),
  * Outputs:
      * a list (Macaulay2Doc),

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

Returns a list containing the row and column coordinates in the original matrix
for a specified sized submatrix of terms lower in degree than other terms of
the matrix.

+--------------------------------------------------------+
|i1 : R = QQ[x,y,z];                                     |
+--------------------------------------------------------+
|i2 : M=matrix{{x^2,x^3,x^4},{y^4,y^2,y^3},{z^3,z^4,z^2}}|
|                                                        |
|o2 = | x2 x3 x4 |                                       |
|     | y4 y2 y3 |                                       |
|     | z3 z4 z2 |                                       |
|                                                        |
|             3      3                                   |
|o2 : Matrix R  <-- R                                    |
+--------------------------------------------------------+
|i3 : chooseSubmatrixSmallestDegree(2, M)                |
|                                                        |
|o3 = {{2, 1}, {2, 1}}                                   |
|                                                        |
|o3 : List                                               |
+--------------------------------------------------------+

This returns a list with two entries, first a list of row indices, and then a
list of column indices.  In this case, z^2 is the smallest element, and after
removing that row and column from consideration, y^2 is smallest.  Thus we want
rows 2 and 1 and columns 2 and 1.

Ways to use chooseSubmatrixSmallestDegree:
==========================================

  * "chooseSubmatrixSmallestDegree(ZZ,Matrix)"

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

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

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

The source of this document is in FastMinors.m2:1649:0.

DetStrategy -- DetStrategy is a strategy for allowing the user to choose how determinants (or rank), is computed
****************************************************************************************************************

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

Passing the option DetStrategy => Symbol controls how certain functions compute
determinants (or in some cases, rank). For all methods, Bareiss, Cofactor and
Recursive are valid options.  The first two come included with Macaulay2, the
third is just a call to recursiveMinors.

Additionally, for the methods getSubmatrixOfRank and isRankAtLeast, one can
also pass DetStrategy the option Rank (the default).  Not using Rank tells the
functions to check rank by computing the determinant, instead of using the
internal rank function.  This is not usually recommended, but sometimes it can
be effective.

See also
========

  * recursiveMinors -- uses a recursive cofactor
    algorithm to compute the ideal of minors of a matrix
  * Bareiss (Macaulay2Doc)
  * Cofactor (Macaulay2Doc)
  * rank (Macaulay2Doc) -- compute the rank

Functions with optional argument named DetStrategy:
===================================================

  * "chooseGoodMinors(...,DetStrategy=>...)"
  * "getSubmatrixOfRank(...,DetStrategy=>...)"
  * "isRankAtLeast(...,DetStrategy=>...)"
  * "projDim(...,DetStrategy=>...)"
  * "regularInCodimension(...,DetStrategy=>...)"

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

The object DetStrategy, is a symbol (Macaulay2Doc).

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

The source of this document is in FastMinors.m2:2197:0.

FastMinorsStrategyTutorial -- How to use and construct strategies for selecting submatrices in various functions
****************************************************************************************************************

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

We will work with the following example, the cone over a product of an elliptic
curve and a genus 3 planar curve, embedded with a Segre embedding, so the cone
over a surface, embedded in $P^8$ (defined by 31 equations).  The Jacobian is a
relatively sparse $9 \times 31$ matrix and to compute the full Jacobian ideal
we would need to compute the 61,847,604 minors of size $6 \times 6$.

+-----------------------------------------------------------------------------+
|i1 : S = ZZ/103[x_1..x_9];                                                   |
+-----------------------------------------------------------------------------+
|i2 : J = ideal(x_6*x_8-x_5*x_9,x_3*x_8-x_2*x_9,x_6*x_7-x_4*x_9,x_5*x_7-x_4*x_|
|                                                                             |
|                                                                             |
|o2 = ideal (x x  - x x , x x  - x x , x x  - x x , x x  - x x , x x  - x x , |
|             6 8    5 9   3 8    2 9   6 7    4 9   5 7    4 8   3 7    1 9  |
|     ------------------------------------------------------------------------|
|                                                          3    2        2    |
|     x x  - x x , x x  - x x , x x  - x x , x x  - x x , x  - x x  - x x ,   |
|      2 7    1 8   3 5    2 6   3 4    1 6   2 4    1 5   7    8 9    7 9    |
|     ------------------------------------------------------------------------|
|        2               2     2               2   2      2                   |
|     x x  - x x x  - x x , x x  - x x x  - x x , x x  - x x  - x x x , x x x |
|      4 7    5 8 9    4 9   1 7    2 8 9    1 9   4 7    5 9    4 6 9   1 4 7|
|     ------------------------------------------------------------------------|
|                         2      2              3    2        2     2         |
|     - x x x  - x x x , x x  - x x  - x x x , x  - x x  - x x , x x  - x x x |
|        2 5 9    1 6 9   1 7    2 9    1 3 9   4    5 6    4 6   1 4    2 5 6|
|     ------------------------------------------------------------------------|
|          2   2      2              3    2        2   4    4    4     3      |
|     - x x , x x  - x x  - x x x , x  - x x  - x x , x  + x  - x , x x  +    |
|        1 6   1 4    2 6    1 3 6   1    2 3    1 3   3    6    9   2 3      |
|     ------------------------------------------------------------------------|
|        3      3     3      3      3   2 2    2 2    2 2       2        2    |
|     x x  - x x , x x  + x x  - x x , x x  + x x  - x x , x x x  + x x x  -  |
|      5 6    8 9   1 3    4 6    7 9   2 3    5 6    8 9   1 2 3    4 5 6    |
|     ------------------------------------------------------------------------|
|          2   2 2    2 2    2 2   3      3      3       2        2           |
|     x x x , x x  + x x  - x x , x x  + x x  - x x , x x x  + x x x  -       |
|      7 8 9   1 3    4 6    7 9   2 3    5 6    8 9   1 2 3    4 5 6         |
|     ------------------------------------------------------------------------|
|        2     2        2        2       4    4    4     3      3      3   2 2|
|     x x x , x x x  + x x x  - x x x , x  + x  - x , x x  + x x  - x x , x x |
|      7 8 9   1 2 3    4 5 6    7 8 9   2    5    8   1 2    4 5    7 8   1 2|
|     ------------------------------------------------------------------------|
|        2 2    2 2                                                           |
|     + x x  - x x )                                                          |
|        4 5    7 8                                                           |
|                                                                             |
|o2 : Ideal of S                                                              |
|-----------------------------------------------------------------------------|
|8,x_3*x_7-x_1*x_9,x_2*x_7-x_1*x_8,x_3*x_5-x_2*x_6,x_3*x_4-x_1*x_6,x_2*x_4-x_1|
|-----------------------------------------------------------------------------|
|*x_5,x_7^3-x_8^2*x_9-x_7*x_9^2,x_4*x_7^2-x_5*x_8*x_9-x_4*x_9^2,              |
|-----------------------------------------------------------------------------|
|x_1*x_7^2-x_2*x_8*x_9-x_1*x_9^2,x_4^2*x_7-x_5^2*x_9-x_4*x_6*x_9,x_1*x_4*x_7-x|
|-----------------------------------------------------------------------------|
|_2*x_5*x_9-x_1*x_6*x_9,x_1^2*x_7-x_2^2*x_9-x_1*x_3*x_9,x_4^3-x_5^2*x_6-x_4*x_|
|-----------------------------------------------------------------------------|
|6^2,x_1*x_4^2-x_2*x_5*x_6-x_1*x_6^2,x_1^2*x_4-x_2^2*x_6-x_1*x_3*x_6,x_1^3-x_2|
|-----------------------------------------------------------------------------|
|^2*x_3-x_1*x_3^2,x_3^4+x_6^4-x_9^4,x_2*x_3^3+x_5*x_6^3-x_8*x_9^3,x_1*x_3^3+x_|
|-----------------------------------------------------------------------------|
|4*x_6^3-x_7*x_9^3,x_2^2*x_3^2+x_5^2*x_6^2-x_8^2*x_9^2,x_1*x_2*x_3^2+x_4*x_5*x|
|-----------------------------------------------------------------------------|
|_6^2-x_7*x_8*x_9^2,x_1^2*x_3^2+x_4^2*x_6^2-x_7^2*x_9^2,x_2^3*x_3+x_5^3*x_6-x_|
|-----------------------------------------------------------------------------|
|8^3*x_9,x_1*x_2^2*x_3+x_4*x_5^2*x_6-x_7*x_8^2*x_9,x_1^2*x_2*x_3+x_4^2*x_5*x_6|
|-----------------------------------------------------------------------------|
|-x_7^2*x_8*x_9,x_2^4+x_5^4-x_8^4,x_1*x_2^3+x_4*x_5^3-x_7*x_8^3,x_1^2*x_2^2+x_|
|-----------------------------------------------------------------------------|
|4^2*x_5^2-x_7^2*x_8^2)                                                       |
+-----------------------------------------------------------------------------+
|i3 : M = jacobian J                                                          |
|                                                                             |
|o3 = {1} | 0    0    0    0    -x_9 -x_8 0    -x_6 -x_5 0                    |
|     {1} | 0    -x_9 0    0    0    x_7  -x_6 0    x_4  0                    |
|     {1} | 0    x_8  0    0    x_7  0    x_5  x_4  0    0                    |
|     {1} | 0    0    -x_9 -x_8 0    0    0    x_3  x_2  0                    |
|     {1} | -x_9 0    0    x_7  0    0    x_3  0    -x_1 0                    |
|     {1} | x_8  0    x_7  0    0    0    -x_2 -x_1 0    0                    |
|     {1} | 0    0    x_6  x_5  x_3  x_2  0    0    0    3x_7^2-x_9^2         |
|     {1} | x_6  x_3  0    -x_4 0    -x_1 0    0    0    -2x_8x_9             |
|     {1} | -x_5 -x_2 -x_4 0    -x_1 0    0    0    0    -x_8^2-2x_7x_9       |
|     ------------------------------------------------------------------------|
|     0               x_7^2-x_9^2     0              x_4x_7-x_6x_9            |
|     0               -x_8x_9         0              -x_5x_9                  |
|     0               0               0              0                        |
|     x_7^2-x_9^2     0               2x_4x_7-x_6x_9 x_1x_7                   |
|     -x_8x_9         0               -2x_5x_9       -x_2x_9                  |
|     0               0               -x_4x_9        -x_1x_9                  |
|     2x_4x_7         2x_1x_7         x_4^2          x_1x_4                   |
|     -x_5x_9         -x_2x_9         0              0                        |
|     -x_5x_8-2x_4x_9 -x_2x_8-2x_1x_9 -x_5^2-x_4x_6  -x_2x_5-x_1x_6           |
|     ------------------------------------------------------------------------|
|     2x_1x_7-x_3x_9 0              x_4^2-x_6^2     2x_1x_4-x_3x_6            |
|     -2x_2x_9       0              -x_5x_6         -2x_2x_6                  |
|     -x_1x_9        0              0               -x_1x_6                   |
|     0              3x_4^2-x_6^2   2x_1x_4         x_1^2                     |
|     0              -2x_5x_6       -x_2x_6         0                         |
|     0              -x_5^2-2x_4x_6 -x_2x_5-2x_1x_6 -x_2^2-x_1x_3             |
|     x_1^2          0              0               0                         |
|     0              0              0               0                         |
|     -x_2^2-x_1x_3  0              0               0                         |
|     ------------------------------------------------------------------------|
|     3x_1^2-x_3^2   0       0          x_3^3      0          x_2x_3^2        |
|     -2x_2x_3       0       x_3^3      0          2x_2x_3^2  x_1x_3^2        |
|     -x_2^2-2x_1x_3 4x_3^3  3x_2x_3^2  3x_1x_3^2  2x_2^2x_3  2x_1x_2x_3      |
|     0              0       0          x_6^3      0          x_5x_6^2        |
|     0              0       x_6^3      0          2x_5x_6^2  x_4x_6^2        |
|     0              4x_6^3  3x_5x_6^2  3x_4x_6^2  2x_5^2x_6  2x_4x_5x_6      |
|     0              0       0          -x_9^3     0          -x_8x_9^2       |
|     0              0       -x_9^3     0          -2x_8x_9^2 -x_7x_9^2       |
|     0              -4x_9^3 -3x_8x_9^2 -3x_7x_9^2 -2x_8^2x_9 -2x_7x_8x_9     |
|     ------------------------------------------------------------------------|
|     2x_1x_3^2  0          x_2^2x_3    2x_1x_2x_3  0       x_2^3             |
|     0          3x_2^2x_3  2x_1x_2x_3  x_1^2x_3    4x_2^3  3x_1x_2^2         |
|     2x_1^2x_3  x_2^3      x_1x_2^2    x_1^2x_2    0       0                 |
|     2x_4x_6^2  0          x_5^2x_6    2x_4x_5x_6  0       x_5^3             |
|     0          3x_5^2x_6  2x_4x_5x_6  x_4^2x_6    4x_5^3  3x_4x_5^2         |
|     2x_4^2x_6  x_5^3      x_4x_5^2    x_4^2x_5    0       0                 |
|     -2x_7x_9^2 0          -x_8^2x_9   -2x_7x_8x_9 0       -x_8^3            |
|     0          -3x_8^2x_9 -2x_7x_8x_9 -x_7^2x_9   -4x_8^3 -3x_7x_8^2        |
|     -2x_7^2x_9 -x_8^3     -x_7x_8^2   -x_7^2x_8   0       0                 |
|     ------------------------------------------------------------------------|
|     2x_1x_2^2  |                                                            |
|     2x_1^2x_2  |                                                            |
|     0          |                                                            |
|     2x_4x_5^2  |                                                            |
|     2x_4^2x_5  |                                                            |
|     0          |                                                            |
|     -2x_7x_8^2 |                                                            |
|     -2x_7^2x_8 |                                                            |
|     0          |                                                            |
|                                                                             |
|             9      31                                                       |
|o3 : Matrix S  <-- S                                                         |
+-----------------------------------------------------------------------------+

getSubmatrixOfRank:  We begin by exploring submatrices of this matrix, chosen
using different strategies.  We try to select submatrices of rank 6 with the
command getSubmatrixOfRank.  The Random strategy for
instance selects a smallest matrix.  On the other hand, GRevLexSmallest
(respectively GRevLexLargest) tries to choose a matrix with minimal
(respectively maximal) values with respect to a random GRevLex order.
LexSmallest and LexLargest selects a smallest submatrix whose terms have
smallest and largest value with respect to a random Lex monomial order.  Points
first finds a point on $V(J)$ and then finds a submatrix where the matrix has
full rank after being evaluated at that point.  For more details on how these
strategies work, see getSubmatrixOfRank(...,Strategy=>...).

+-----------------------------------------------------------------------------+
|i4 : a = getSubmatrixOfRank(6, M**(S/J), Strategy=>Random)                   |
|                                                                             |
|o4 = {{0, 4, 5, 6, 7, 8}, {24, 8, 13, 5, 1, 25}}                             |
|                                                                             |
|o4 : List                                                                    |
+-----------------------------------------------------------------------------+
|i5 : M^(a#0)_(a#1)                                                           |
|                                                                             |
|o5 = {1} | 2x_1x_3^2  -x_5 x_4x_7-x_6x_9  -x_8 0    0          |             |
|     {1} | 0          -x_1 -x_2x_9        0    0    3x_5^2x_6  |             |
|     {1} | 2x_4^2x_6  0    -x_1x_9        0    0    x_5^3      |             |
|     {1} | -2x_7x_9^2 0    x_1x_4         x_2  0    0          |             |
|     {1} | 0          0    0              -x_1 x_3  -3x_8^2x_9 |             |
|     {1} | -2x_7^2x_9 0    -x_2x_5-x_1x_6 0    -x_2 -x_8^3     |             |
|                                                                             |
|             6      6                                                        |
|o5 : Matrix S  <-- S                                                         |
+-----------------------------------------------------------------------------+
|i6 : d = getSubmatrixOfRank(6, M**(S/J), MaxMinors=>100,                     |
|                                                                             |
|o6 = {{8, 7, 1, 2, 6, 4}, {2, 3, 8, 7, 12, 30}}                              |
|                                                                             |
|o6 : List                                                                    |
|-----------------------------------------------------------------------------|
|Strategy=>LexSmallest)                                                       |
+-----------------------------------------------------------------------------+
|i7 : M^(d#0)_(d#1)                                                           |
|                                                                             |
|o7 = {1} | -x_4 0    0    0   -x_5^2-x_4x_6 0          |                     |
|     {1} | 0    -x_4 0    0   0             -2x_7^2x_8 |                     |
|     {1} | 0    0    x_4  0   0             2x_1^2x_2  |                     |
|     {1} | 0    0    0    x_4 0             0          |                     |
|     {1} | x_6  x_5  0    0   x_4^2         -2x_7x_8^2 |                     |
|     {1} | 0    x_7  -x_1 0   -2x_5x_9      2x_4^2x_5  |                     |
|                                                                             |
|             6      6                                                        |
|o7 : Matrix S  <-- S                                                         |
+-----------------------------------------------------------------------------+
|i8 : e = getSubmatrixOfRank(6, M**(S/J), Strategy=>LexSmallestTerm)          |
|                                                                             |
|o8 = {{6, 3, 7, 4, 0, 2}, {4, 7, 1, 6, 18, 19}}                              |
|                                                                             |
|o8 : List                                                                    |
+-----------------------------------------------------------------------------+
|i9 : M^(e#0)_(e#1)                                                           |
|                                                                             |
|o9 = {1} | x_3  0    0   0   0              0      |                         |
|     {1} | 0    x_3  0   0   0              0      |                         |
|     {1} | 0    0    x_3 0   0              0      |                         |
|     {1} | 0    0    0   x_3 0              0      |                         |
|     {1} | -x_9 -x_6 0   0   3x_1^2-x_3^2   0      |                         |
|     {1} | x_7  x_4  x_8 x_5 -x_2^2-2x_1x_3 4x_3^3 |                         |
|                                                                             |
|             6      6                                                        |
|o9 : Matrix S  <-- S                                                         |
+-----------------------------------------------------------------------------+
|i10 : f = getSubmatrixOfRank(6, M**(S/J), MaxMinors=>100,                    |
|                                                                             |
|o10 = {{0, 2, 1, 5, 8, 4}, {29, 25, 28, 17, 14, 16}}                         |
|                                                                             |
|o10 : List                                                                   |
|-----------------------------------------------------------------------------|
|Strategy=>LexLargest)                                                        |
+-----------------------------------------------------------------------------+
|i11 : M^(f#0)_(f#1)                                                          |
|                                                                             |
|o11 = {1} | x_2^3     0         0      2x_1x_4-x_3x_6 2x_1x_7-x_3x_9         |
|      {1} | 0         x_2^3     0      -x_1x_6        -x_1x_9                |
|      {1} | 3x_1x_2^2 3x_2^2x_3 4x_2^3 -2x_2x_6       -2x_2x_9               |
|      {1} | 0         x_5^3     0      -x_2^2-x_1x_3  0                      |
|      {1} | 0         -x_8^3    0      0              -x_2^2-x_1x_3          |
|      {1} | 3x_4x_5^2 3x_5^2x_6 4x_5^3 0              0                      |
|      -----------------------------------------------------------------------|
|      x_4^2-x_6^2     |                                                      |
|      0               |                                                      |
|      -x_5x_6         |                                                      |
|      -x_2x_5-2x_1x_6 |                                                      |
|      0               |                                                      |
|      -x_2x_6         |                                                      |
|                                                                             |
|              6      6                                                       |
|o11 : Matrix S  <-- S                                                        |
+-----------------------------------------------------------------------------+
|i12 : g = getSubmatrixOfRank(6, M**(S/J), Strategy=>Points)                  |
|                                                                             |
|o12 = {{0, 1, 2, 3, 4, 6}, {0, 1, 2, 4, 9, 19}}                              |
|                                                                             |
|o12 : List                                                                   |
+-----------------------------------------------------------------------------+
|i13 : M^(g#0)_(g#1)                                                          |
|                                                                             |
|o13 = {1} | 0    0    0    -x_9 0            0      |                        |
|      {1} | 0    -x_9 0    0    0            0      |                        |
|      {1} | 0    x_8  0    x_7  0            4x_3^3 |                        |
|      {1} | 0    0    -x_9 0    0            0      |                        |
|      {1} | -x_9 0    0    0    0            0      |                        |
|      {1} | 0    0    x_6  x_3  3x_7^2-x_9^2 0      |                        |
|                                                                             |
|              6      6                                                       |
|o13 : Matrix S  <-- S                                                        |
+-----------------------------------------------------------------------------+

You can see that different strategies typically produce submatrices which can
appear quite different in their complexity. We left off the strategies
GRevLexLargest, GRevLexSmallest, GRevLexSmallestTerm as they behave very poorly
on this example (indeed, we had to increase MaxMinors, the number of
submatrices considered, for both LexSmallest and LexLargest as they did not
find a submatrix in the default number of attempts).  Of course, one can view
the matrix over $S$, instead of $S/J$, where it's easier to choose a submatrix.

+-----------------------------------------------------------------------------+
|i14 : b = getSubmatrixOfRank(6, M, Strategy=>GRevLexSmallest)                |
|                                                                             |
|o14 = {{3, 0, 2, 5, 8, 4}, {3, 5, 1, 0, 4, 8}}                               |
|                                                                             |
|o14 : List                                                                   |
+-----------------------------------------------------------------------------+
|i15 : M^(b#0)_(b#1)                                                          |
|                                                                             |
|o15 = {1} | -x_8 0    0    0    0    x_2  |                                  |
|      {1} | 0    -x_8 0    0    -x_9 -x_5 |                                  |
|      {1} | 0    0    x_8  0    x_7  0    |                                  |
|      {1} | 0    0    0    x_8  0    0    |                                  |
|      {1} | 0    0    -x_2 -x_5 -x_1 0    |                                  |
|      {1} | x_7  0    0    -x_9 0    -x_1 |                                  |
|                                                                             |
|              6      6                                                       |
|o15 : Matrix S  <-- S                                                        |
+-----------------------------------------------------------------------------+
|i16 : c = getSubmatrixOfRank(6, M, Strategy=>GRevLexSmallestTerm)            |
|                                                                             |
|o16 = {{1, 0, 6, 7, 2, 4}, {6, 7, 2, 0, 4, 3}}                               |
|                                                                             |
|o16 : List                                                                   |
+-----------------------------------------------------------------------------+
|i17 : M^(c#0)_(c#1)                                                          |
|                                                                             |
|o17 = {1} | -x_6 0    0   0    0    0    |                                   |
|      {1} | 0    -x_6 0   0    -x_9 0    |                                   |
|      {1} | 0    0    x_6 0    x_3  x_5  |                                   |
|      {1} | 0    0    0   x_6  0    -x_4 |                                   |
|      {1} | x_5  x_4  0   0    x_7  0    |                                   |
|      {1} | x_3  0    0   -x_9 0    x_7  |                                   |
|                                                                             |
|              6      6                                                       |
|o17 : Matrix S  <-- S                                                        |
+-----------------------------------------------------------------------------+
|i18 : h = getSubmatrixOfRank(6, M, Strategy=>LexLargest)                     |
|                                                                             |
|o18 = {{8, 7, 6, 3, 0, 2}, {19, 20, 21, 10, 11, 14}}                         |
|                                                                             |
|o18 : List                                                                   |
+-----------------------------------------------------------------------------+
|i19 : M^(h#0)_(h#1)                                                          |
|                                                                             |
|o19 = {1} | -4x_9^3 -3x_8x_9^2 -3x_7x_9^2 -x_5x_8-2x_4x_9 -x_2x_8-2x_1x_9    |
|      {1} | 0       -x_9^3     0          -x_5x_9         -x_2x_9            |
|      {1} | 0       0          -x_9^3     2x_4x_7         2x_1x_7            |
|      {1} | 0       0          x_6^3      x_7^2-x_9^2     0                  |
|      {1} | 0       0          x_3^3      0               x_7^2-x_9^2        |
|      {1} | 4x_3^3  3x_2x_3^2  3x_1x_3^2  0               0                  |
|      -----------------------------------------------------------------------|
|      -x_2^2-x_1x_3  |                                                       |
|      0              |                                                       |
|      x_1^2          |                                                       |
|      0              |                                                       |
|      2x_1x_7-x_3x_9 |                                                       |
|      -x_1x_9        |                                                       |
|                                                                             |
|              6      6                                                       |
|o19 : Matrix S  <-- S                                                        |
+-----------------------------------------------------------------------------+

chooseGoodMinors:  In many cases, we want to consider the determinant of the
submatrices we just found, perhaps to append the determinant to an ideal.  The
function chooseGoodMinors, helps us do that.  Note that
chooseGoodMinors does not check that the submatrix we are computing has full
rank (except by computing its determinant and adding it to our working ideal).

+-----------------------------------------------------------------------------+
|i20 : chooseGoodMinors(1, 6, M, J, Strategy=>Random)                         |
|                                                                             |
|                 3 2 3 2 4        5 3 2 4          2   4 6        3   2 2 6  |
|o20 = ideal(- 24x x x x x x  + 24x x x x x  + 48x x x x x x  - 48x x x x x x |
|                 1 2 3 4 6 8      1 3 5 6 8      1 2 3 4 6 8      1 3 4 5 6 8|
|      -----------------------------------------------------------------------|
|              2   3 6        2 2 3 7         2     2 7        2 2   2 7      |
|      - 7x x x x x x x  - 24x x x x x  + 7x x x x x x x  + 24x x x x x x  -  |
|          1 2 3 4 5 6 8      2 3 4 6 8     1 2 3 4 5 6 8      1 3 4 5 6 8    |
|      -----------------------------------------------------------------------|
|         3 5 2 3          3   4 2 2 2          2 5   3 2        2 6   3 2    |
|      16x x x x x x  + 48x x x x x x x  - 48x x x x x x x  - 48x x x x x x  +|
|         1 3 4 5 6 9      1 2 3 4 5 6 9      1 2 3 4 5 6 9      1 3 4 5 6 9  |
|      -----------------------------------------------------------------------|
|           3 4   2 3        2   5   2 3          3 4 3 3       3 3 2 2 4     |
|      48x x x x x x x  + 48x x x x x x x  + 39x x x x x x  - 8x x x x x x  - |
|         1 2 3 4 5 6 9      1 2 3 4 5 6 9      1 3 4 5 6 9     1 2 3 4 6 9   |
|      -----------------------------------------------------------------------|
|         5   2 2 4        4 3 3 4       3   2 3 5          3 4 6             |
|      24x x x x x x  + 32x x x x x  - 7x x x x x x  + 16x x x x x  -         |
|         1 2 3 5 6 9      3 4 5 6 9     1 3 4 5 6 9      1 2 4 6 9           |
|      -----------------------------------------------------------------------|
|         3   2 2 6       3   3 7        2       2 7                          |
|      48x x x x x x  - 8x x x x x  - 24x x x x x x x )                       |
|         1 2 4 5 6 9     2 3 4 6 9      1 2 3 4 5 6 9                        |
|                                                                             |
|o20 : Ideal of S                                                             |
+-----------------------------------------------------------------------------+
|i21 : chooseGoodMinors(1, 6, M, J, Strategy=>LexSmallest)                    |
|                                                                             |
|               2 4         3      2 2 2                                      |
|o21 = ideal(- x x  + 2x x x x  - x x x )                                     |
|               6 7     4 6 7 9    4 7 9                                      |
|                                                                             |
|o21 : Ideal of S                                                             |
+-----------------------------------------------------------------------------+
|i22 : chooseGoodMinors(1, 6, M, J, Strategy=>LexSmallestTerm)                |
|                                                                             |
|                9       7                                                    |
|o22 = ideal(- 4x  - 8x x x )                                                 |
|                5     4 5 6                                                  |
|                                                                             |
|o22 : Ideal of S                                                             |
+-----------------------------------------------------------------------------+
|i23 : chooseGoodMinors(1, 6, M, J, Strategy=>LexLargest)                     |
|                                                                             |
|              4 3   4       3     3 4        3     2   4       3   8         |
|o23 = ideal(6x x x x x  - 6x x x x x x  + 12x x x x x x x  - 6x x x x  -     |
|              1 2 3 7 8     1 3 4 5 7 8      1 2 4 5 6 7 8     1 2 7 8       |
|      -----------------------------------------------------------------------|
|        5 2   3 2     3   2 2 3 2     3   2     3 2        2   7 2           |
|      4x x x x x  + 4x x x x x x  - 8x x x x x x x  - 12x x x x x  -         |
|        1 2 3 7 8     1 3 4 5 7 8     1 2 4 5 6 7 8      1 2 3 7 8           |
|      -----------------------------------------------------------------------|
|           2   7 2     11 2     2     6 3     2     6 3     3   5 4          |
|      12x x x x x  + 6x  x  + 4x x x x x  + 8x x x x x  + 6x x x x  +        |
|         4 5 6 7 8     7  8     1 2 3 7 8     4 5 6 7 8     1 3 7 8          |
|      -----------------------------------------------------------------------|
|        5 2   4       3   2 2 4       3   2     4       2     7              |
|      4x x x x x  - 4x x x x x x  + 8x x x x x x x  - 4x x x x x x  -        |
|        1 2 3 7 9     1 3 4 5 7 9     1 2 4 5 6 7 9     1 2 3 7 8 9          |
|      -----------------------------------------------------------------------|
|        2     7         3 4   2 2         2   2 2 2 2       2       3 2 2    |
|      8x x x x x x  - 2x x x x x x  - 8x x x x x x x x  - 2x x x x x x x x  +|
|        4 5 6 7 8 9     1 2 3 7 8 9     1 2 3 4 5 7 8 9     1 2 3 4 5 7 8 9  |
|      -----------------------------------------------------------------------|
|          3 2     2 2       2 2 6 2       2     2 2   3       3     3   3    |
|      8x x x x x x x x  + 4x x x x x  + 4x x x x x x x x  + 4x x x x x x x  -|
|        1 2 4 5 6 7 8 9     4 5 7 8 9     1 2 3 4 5 7 8 9     1 3 4 5 7 8 9  |
|      -----------------------------------------------------------------------|
|        3     2     3         2   4 4       2     3 5       2     3 5        |
|      8x x x x x x x x  + 8x x x x x x  + 2x x x x x x  - 8x x x x x x  +    |
|        1 2 4 5 6 7 8 9     4 5 6 7 8 9     1 2 3 7 8 9     4 5 6 7 8 9      |
|      -----------------------------------------------------------------------|
|        3 4   3 2       2   2 2 3 2     2       3 3 2       3 2     3 2      |
|      4x x x x x  - 8x x x x x x x  + 4x x x x x x x  + 8x x x x x x x  +    |
|        1 2 3 7 9     1 2 3 4 5 7 9     1 2 3 4 5 7 9     1 2 4 5 6 7 9      |
|      -----------------------------------------------------------------------|
|        2 2 7 2      4 3   2   2     2     2 2 2   2      3     3 2   2      |
|      4x x x x  - 16x x x x x x  - 4x x x x x x x x  + 12x x x x x x x  -    |
|        4 5 7 9      1 2 3 7 8 9     1 2 3 4 5 7 8 9      1 3 4 5 7 8 9      |
|      -----------------------------------------------------------------------|
|         3     2   2   2      3   6   2     5 2     2 2     3   2 2   2 2    |
|      24x x x x x x x x  + 10x x x x x  + 4x x x x x x  - 4x x x x x x x  +  |
|         1 2 4 5 6 7 8 9      1 2 7 8 9     1 2 3 7 8 9     1 3 4 5 7 8 9    |
|      -----------------------------------------------------------------------|
|        3   2       2 2        2   5 2 2        2   5 2 2      9 2 2         |
|      8x x x x x x x x  + 32x x x x x x  + 24x x x x x x  - 10x x x  +       |
|        1 2 4 5 6 7 8 9      1 2 3 7 8 9      4 5 6 7 8 9      7 8 9         |
|      -----------------------------------------------------------------------|
|          2     3 3 2       3   2   3 2       3 4 3 2     2     4 3 2        |
|      4x x x x x x x  - 4x x x x x x x  + 6x x x x x  - 8x x x x x x  +      |
|        1 2 3 4 5 8 9     1 2 4 5 6 8 9     1 2 7 8 9     1 2 3 7 8 9        |
|      -----------------------------------------------------------------------|
|          3 4 3 2      2     4 3 2      3   3 4 2     2 2 3 4 2              |
|      4x x x x x  - 16x x x x x x  - 16x x x x x  - 4x x x x x  +            |
|        4 5 7 8 9      4 5 6 7 8 9      1 3 7 8 9     4 5 7 8 9              |
|      -----------------------------------------------------------------------|
|          2     6 2     5 6 2     5 2   2 3     3   2 2 2 3                  |
|      4x x x x x x  - 6x x x  - 8x x x x x  + 8x x x x x x  -                |
|        4 5 6 7 8 9     7 8 9     1 2 3 7 9     1 3 4 5 7 9                  |
|      -----------------------------------------------------------------------|
|         3   2     2 3       2     3     3       3   2       3        3 5   3|
|      16x x x x x x x  - 8x x x x x x x x  + 8x x x x x x x x  - 12x x x x x |
|         1 2 4 5 6 7 9     1 2 3 4 5 7 8 9     1 2 4 5 6 7 8 9      1 2 7 8 9|
|      -----------------------------------------------------------------------|
|          2     5   3       3 5   3      2     5   3     3 4   2 3           |
|      + 8x x x x x x  - 8x x x x x  + 16x x x x x x  + 2x x x x x  +         |
|          1 2 3 7 8 9     4 5 7 8 9      4 5 6 7 8 9     1 2 3 8 9           |
|      -----------------------------------------------------------------------|
|           2   2 2 2 3     2       3 2 3        3 2     2 3     2 2 4 2 3    |
|      16x x x x x x x  + 2x x x x x x x  - 16x x x x x x x  + 8x x x x x  +  |
|         1 2 3 4 5 8 9     1 2 3 4 5 8 9      1 2 4 5 6 8 9     4 5 7 8 9    |
|      -----------------------------------------------------------------------|
|         3   3 3 3       2   2 4 3     6 4 3     2       5 3       3   5 3   |
|      20x x x x x  - 8x x x x x x  - 8x x x  - 2x x x x x x  - 4x x x x x  + |
|         1 2 7 8 9     4 5 6 7 8 9     7 8 9     1 2 3 7 8 9     4 5 7 8 9   |
|      -----------------------------------------------------------------------|
|         2       5 3     3 4     4       2   2 2   4     2       3   4       |
|      16x x x x x x  - 4x x x x x  + 8x x x x x x x  - 4x x x x x x x  -     |
|         4 5 6 7 8 9     1 2 3 7 9     1 2 3 4 5 7 9     1 2 3 4 5 7 9       |
|      -----------------------------------------------------------------------|
|          3 2       4     2 2 5 4      4 3     4     2     2 2   4           |
|      8x x x x x x x  - 8x x x x  + 10x x x x x  + 4x x x x x x x  -         |
|        1 2 4 5 6 7 9     4 5 7 9      1 2 3 8 9     1 2 3 4 5 8 9           |
|      -----------------------------------------------------------------------|
|        3     3   4      3     2     4     3   4   4        2   3 2 4        |
|      6x x x x x x  + 12x x x x x x x  - 2x x x x x  - 20x x x x x x  -      |
|        1 3 4 5 8 9      1 2 4 5 6 8 9     1 2 7 8 9      1 2 3 7 8 9        |
|      -----------------------------------------------------------------------|
|           2   3 2 4     7 2 4       3 2 3 4     2     2 3 4       3 2 3 4   |
|      12x x x x x x  + 2x x x  - 6x x x x x  + 4x x x x x x  + 4x x x x x  + |
|         4 5 6 7 8 9     7 8 9     1 2 7 8 9     1 2 3 7 8 9     4 5 7 8 9   |
|      -----------------------------------------------------------------------|
|        2     2 3 4      3     4 4      2 2   4 4     3 6 4     5 2   5      |
|      8x x x x x x  + 10x x x x x  - 16x x x x x  + 6x x x  + 4x x x x  -    |
|        4 5 6 7 8 9      1 3 7 8 9      4 5 7 8 9     7 8 9     1 2 3 9      |
|      -----------------------------------------------------------------------|
|        3   2 2 5     3   2     5        3 3   5     2     3   5             |
|      4x x x x x  + 8x x x x x x  + 12x x x x x  - 4x x x x x x  +           |
|        1 3 4 5 9     1 2 4 5 6 9      1 2 7 8 9     1 2 3 7 8 9             |
|      -----------------------------------------------------------------------|
|          3 3   5     2     3   5      2 2 2 2 5      3     3 5     4 4 5    |
|      8x x x x x  - 8x x x x x x  - 12x x x x x  - 20x x x x x  + 8x x x  +  |
|        4 5 7 8 9     4 5 6 7 8 9      4 5 7 8 9      1 2 7 8 9     7 8 9    |
|      -----------------------------------------------------------------------|
|        2 2 3 6     3   2   6     5 2 6                                      |
|      4x x x x  - 2x x x x x  + 2x x x )                                     |
|        4 5 7 9     1 2 7 8 9     7 8 9                                      |
|                                                                             |
|o23 : Ideal of S                                                             |
+-----------------------------------------------------------------------------+
|i24 : chooseGoodMinors(1, 6, M, J, Strategy=>GRevLexSmallest)                |
|                                                                             |
|               2 2 2     3          4 2                                      |
|o24 = ideal(- x x x  + 2x x x x  - x x )                                     |
|               2 3 5     2 3 5 6    2 6                                      |
|                                                                             |
|o24 : Ideal of S                                                             |
+-----------------------------------------------------------------------------+
|i25 : chooseGoodMinors(1, 6, M, J, Strategy=>GRevLexSmallestTerm)            |
|                                                                             |
|               4 2       3        2 2 2                                      |
|o25 = ideal(- x x  + 2x x x x  - x x x )                                     |
|               6 8     5 6 8 9    5 6 9                                      |
|                                                                             |
|o25 : Ideal of S                                                             |
+-----------------------------------------------------------------------------+
|i26 : chooseGoodMinors(1, 6, M, J, Strategy=>GRevLexLargest)                 |
|                                                                             |
|                 3 3 3 6 2         2 3 2 7 2        2   3   8 2              |
|o26 = ideal(- 39x x x x x x  + 7x x x x x x x  + 32x x x x x x x  +          |
|                 2 3 4 5 7 8     1 2 3 4 5 7 8      1 2 3 4 5 7 8            |
|      -----------------------------------------------------------------------|
|           5 2 4 3 2       2 4   5 3 2        3 3 6 3 2        3 3 4 5   2   |
|      39x x x x x x x  - 7x x x x x x x  - 32x x x x x x  + 39x x x x x x  - |
|         1 2 4 5 6 7 8     1 2 4 5 6 7 8      1 2 5 6 7 8      2 3 4 5 7 8   |
|      -----------------------------------------------------------------------|
|          2 3 3 6   2      2   3 2 7   2      2 4 2 4 3   2     3 3   5 3   2|
|      7x x x x x x x  - 32x x x x x x x  - 39x x x x x x x  + 7x x x x x x x |
|        1 2 3 4 5 7 8      1 2 3 4 5 7 8      1 2 4 5 6 7 8     1 2 4 5 6 7 8|
|      -----------------------------------------------------------------------|
|           4 2 6 3   2        5 4 5 3      2 4 3 6 3      3 3 2 7 3          |
|      + 32x x x x x x  - 39x x x x x  + 46x x x x x  + 25x x x x x  -        |
|           1 2 5 6 7 8      1 2 4 5 9      1 2 4 5 9      1 2 4 5 9          |
|      -----------------------------------------------------------------------|
|         4 2   8 3                                                           |
|      32x x x x x )                                                          |
|         1 2 4 5 9                                                           |
|                                                                             |
|o26 : Ideal of S                                                             |
+-----------------------------------------------------------------------------+
|i27 : chooseGoodMinors(1, 6, M, J, Strategy=>Points)                         |
|                                                                             |
|               3 2 4     3 6                                                 |
|o27 = ideal(12x x x  - 4x x )                                                |
|               3 7 9     3 9                                                 |
|                                                                             |
|o27 : Ideal of S                                                             |
+-----------------------------------------------------------------------------+

Here the $1$ passed to the function says how many minors to compute.  For
instance, let's compute 8 minors for each of these strategies and see if that
was enough to verify that the ring is regular in codimension 1.  In other
words, if the dimension of $J$ plus the ideal of partial minors is $\leq 1$
(since $S/J$ has dimension 3).

+-----------------------------------------------------------------------------+
|i28 : time dim (J + chooseGoodMinors(8, 6, M, J, Strategy=>Random))          |
| -- used 0.188945s (cpu); 0.153826s (thread); 0s (gc)                        |
|                                                                             |
|o28 = 2                                                                      |
+-----------------------------------------------------------------------------+
|i29 : time dim (J + chooseGoodMinors(8, 6, M, J, Strategy=>LexSmallest))     |
| -- used 0.340051s (cpu); 0.270235s (thread); 0s (gc)                        |
|                                                                             |
|o29 = 3                                                                      |
+-----------------------------------------------------------------------------+
|i30 : time dim (J + chooseGoodMinors(8, 6, M, J, Strategy=>LexSmallestTerm)) |
| -- used 0.504431s (cpu); 0.39719s (thread); 0s (gc)                         |
|                                                                             |
|o30 = 1                                                                      |
+-----------------------------------------------------------------------------+
|i31 : time dim (J + chooseGoodMinors(8, 6, M, J, Strategy=>LexLargest))      |
| -- used 0.256987s (cpu); 0.222793s (thread); 0s (gc)                        |
|                                                                             |
|o31 = 2                                                                      |
+-----------------------------------------------------------------------------+
|i32 : time dim (J + chooseGoodMinors(8, 6, M, J, Strategy=>GRevLexSmallest)) |
| -- used 0.351069s (cpu); 0.251679s (thread); 0s (gc)                        |
|                                                                             |
|o32 = 3                                                                      |
+-----------------------------------------------------------------------------+
|i33 : time dim (J + chooseGoodMinors(8, 6, M, J,                             |
| -- used 0.349637s (cpu); 0.279499s (thread); 0s                             |
|                                                                             |
|o33 = 3                                                                      |
|-----------------------------------------------------------------------------|
|Strategy=>GRevLexSmallestTerm))                                              |
|(gc)                                                                         |
+-----------------------------------------------------------------------------+
|i34 : time dim (J + chooseGoodMinors(8, 6, M, J, Strategy=>GRevLexLargest))  |
| -- used 0.315007s (cpu); 0.243847s (thread); 0s (gc)                        |
|                                                                             |
|o34 = 3                                                                      |
+-----------------------------------------------------------------------------+
|i35 : time dim (J + chooseGoodMinors(8, 6, M, J, Strategy=>Points))          |
| -- used 15.7666s (cpu); 12.5615s (thread); 0s (gc)                          |
|                                                                             |
|o35 = 1                                                                      |
+-----------------------------------------------------------------------------+

Indeed, in this example, even computing determinants of 1,000 random
submatrices is not typically enough to verify that $V(J)$ is regular in
codimension 1.  On the other hand, Points is almost always quite effective at
finding valuable submatrices, but can be quite slow.  In this particular
example, we can see that LexSmallestTerm also performs very well (and does it
quickly). Since different strategies work better or worse on different
examples, the default strategy actually mixes and matches various strategies.
The default strategy, which we now elucidate,

+--------------------------------------------+
|i36 : peek StrategyDefault                  |
|                                            |
|o36 = OptionTable{GRevLexLargest => 0      }|
|                  GRevLexSmallest => 16     |
|                  GRevLexSmallestTerm => 16 |
|                  LexLargest => 0           |
|                  LexSmallest => 16         |
|                  LexSmallestTerm => 16     |
|                  Points => 0               |
|                  Random => 16              |
|                  RandomNonzero => 16       |
+--------------------------------------------+

says that we should use GRevLexSmallest, GRevLexSmallestTerm, LexSmallest,
LexSmallestTerm, Random, RandomNonzero all with equal probability (note
RandomNonzero, which we have not yet discussed chooses random submatrices where
no row or column is zero, which is good for working in sparse matrices).  For
instance, if we run:

+-----------------------------------------------------------------------------+
|i37 : time chooseGoodMinors(20, 6, M, J, Strategy=>StrategyDefault,          |
| -- used 0.480606s (cpu); 0.457882s (thread); 0s (gc)                        |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing Random                                         |
|chooseGoodMinors: found =20, attempted = 20                                  |
|                                                                             |
|o37 : Ideal of S                                                             |
|-----------------------------------------------------------------------------|
|Verbose=>true);                                                              |
+-----------------------------------------------------------------------------+

we can see different minors being chosen via different strategies.

Note, if one asks chooseGoodMinors for more than one minor, then any time a
Points strategy is selected, the point is found on $J$ plus the ideal of all
minors computed thus far.

Let us take a look at some other built-in strategies.

+--------------------------------------------+
|i38 : peek StrategyDefaultNonRandom         |
|                                            |
|o38 = OptionTable{GRevLexLargest => 0      }|
|                  GRevLexSmallest => 25     |
|                  GRevLexSmallestTerm => 25 |
|                  LexLargest => 0           |
|                  LexSmallest => 25         |
|                  LexSmallestTerm => 25     |
|                  Points => 0               |
|                  Random => 0               |
|                  RandomNonzero => 0        |
+--------------------------------------------+
|i39 : peek StrategyDefaultWithPoints        |
|                                            |
|o39 = OptionTable{GRevLexLargest => 0      }|
|                  GRevLexSmallest => 16     |
|                  GRevLexSmallestTerm => 16 |
|                  LexLargest => 0           |
|                  LexSmallest => 16         |
|                  LexSmallestTerm => 16     |
|                  Points => 32              |
|                  Random => 0               |
|                  RandomNonzero => 0        |
+--------------------------------------------+
|i40 : peek StrategyPoints                   |
|                                            |
|o40 = OptionTable{GRevLexLargest => 0     } |
|                  GRevLexSmallest => 0      |
|                  GRevLexSmallestTerm => 0  |
|                  LexLargest => 0           |
|                  LexSmallest => 0          |
|                  LexSmallestTerm => 0      |
|                  Points => 100             |
|                  Random => 0               |
|                  RandomNonzero => 0        |
+--------------------------------------------+

StrategyDefaultNonRandom is like StrategyDefault but removes random submatrices
(which can be surprisingly beneficial in some cases).
StrategyDefaultWithPoints removes randomness but adds in points instead.

A warning on chooseGoodMinors:  The strategies LexSmallest and LexSmallestTerm
will very frequently repeatedly choose the same submatrix of the given matrix.
Hence if one tries to run chooseGoodMinors and choose too many minors with such
a strategy, one can get into a long loop (the function give up eventually, but
only after doing way too much work).  The GRevLex strategies periodically
temporarily change the underlying matrix to avoid this sort of loop.

Points: Notice that Strategy => StrategyPoints and Strategy => Points do the
same thing. We briefly describe how chooseGoodMinors interacts with Points.
Indeed Points forms the ideal of minors computed so far (plus $J$), finds a
point where that ideal vanishes (which can be slow), evaluates the matrix $M$
at that point, and then finally computes the corresponding determinant of the
submatrix.  This submatrix will always produce a minor which shrinks our
vanishing locus.

By default, the Points strategy actually finds geometric points.  Which can be
sometimes slower (but which are almost certain to exist, and are less likely to
hang if the function has trouble finding a point).  For instance, we can
control that as follows.

+-----------------------------------------------------------------------------+
|i41 : ptsStratGeometric = new OptionTable from (options                      |
|-----------------------------------------------------------------------------|
|chooseGoodMinors)#PointOptions;                                              |
+-----------------------------------------------------------------------------+
|i42 : ptsStratGeometric#ExtendField --look at the default value              |
|                                                                             |
|o42 = true                                                                   |
+-----------------------------------------------------------------------------+
|i43 : time dim (J + chooseGoodMinors(1, 6, M, J, Strategy=>Points,           |
| -- used 0.606028s (cpu); 0.571138s (thread); 0s (gc)                        |
|                                                                             |
|o43 = 2                                                                      |
|-----------------------------------------------------------------------------|
|PointOptions=>ptsStratGeometric))                                            |
+-----------------------------------------------------------------------------+
|i44 : ptsStratRational = ptsStratGeometric++{ExtendField=>false} --change    |
|                                                                             |
|o44 = OptionTable{DecompositionStrategy => Decompose}                        |
|                  DimensionFunction => dim                                   |
|                  ExtendField => false                                       |
|                  Homogeneous => false                                       |
|                  NumThreadsToUse => 1                                       |
|                  PointCheckAttempts => 0                                    |
|                  Replacement => Binomial                                    |
|                  Strategy => Default                                        |
|                  Verbose => false                                           |
|                                                                             |
|o44 : OptionTable                                                            |
|-----------------------------------------------------------------------------|
|that value                                                                   |
+-----------------------------------------------------------------------------+
|i45 : ptsStratRational.ExtendField --look at our changed value               |
|                                                                             |
|o45 = false                                                                  |
+-----------------------------------------------------------------------------+
|i46 : time dim (J + chooseGoodMinors(1, 6, M, J, Strategy=>Points,           |
| -- used 0.573201s (cpu); 0.504508s (thread); 0s (gc)                        |
|                                                                             |
|o46 = 2                                                                      |
|-----------------------------------------------------------------------------|
|PointOptions=>ptsStratRational))                                             |
+-----------------------------------------------------------------------------+

Other options may also be passed to the RandomPoints,
package via the PointOptions, option.

regularInCodimension:  It is reasonable to think that you should find a few
minors (with one strategy or another), and see if perhaps the minors you have
computed so far are enough to verify our ring is regular in codimension 1.
This is exactly what regularInCodimension does.  One can control at a fine
level how frequently new minors are computed, and how frequently the dimension
of what we have computed so far is checked, by the option codimCheckFunction.
For more on that, see RegularInCodimensionTutorial,
and regularInCodimension.
Let us finish running regularInCodimension on our
example with several different strategies.

+-----------------------------------------------------------------------------+
|i47 : time regularInCodimension(1, S/J, MaxMinors => 100,                    |
| -- used 4.26102s (cpu); 4.07152s (thread); 0s (gc)                          |
|-----------------------------------------------------------------------------|
|Strategy=>StrategyDefault)                                                   |
+-----------------------------------------------------------------------------+
|i48 : time regularInCodimension(1, S/J, MaxMinors => 100,                    |
| -- used 0.949573s (cpu); 0.872099s (thread); 0s (gc)                        |
|                                                                             |
|o48 = true                                                                   |
|-----------------------------------------------------------------------------|
|Strategy=>StrategyDefaultNonRandom)                                          |
+-----------------------------------------------------------------------------+
|i49 : time regularInCodimension(1, S/J, MaxMinors => 100, Strategy=>Random)  |
| -- used 3.62641s (cpu); 3.4455s (thread); 0s (gc)                           |
+-----------------------------------------------------------------------------+
|i50 : time regularInCodimension(1, S/J, MaxMinors => 100,                    |
| -- used 2.80877s (cpu); 2.57575s (thread); 0s (gc)                          |
|-----------------------------------------------------------------------------|
|Strategy=>LexSmallest)                                                       |
+-----------------------------------------------------------------------------+
|i51 : time regularInCodimension(1, S/J, MaxMinors => 100,                    |
| -- used 0.992184s (cpu); 0.954373s (thread); 0s (gc)                        |
|                                                                             |
|o51 = true                                                                   |
|-----------------------------------------------------------------------------|
|Strategy=>LexSmallestTerm)                                                   |
+-----------------------------------------------------------------------------+
|i52 : time regularInCodimension(1, S/J, MaxMinors => 100,                    |
| -- used 3.28316s (cpu); 2.99802s (thread); 0s (gc)                          |
|-----------------------------------------------------------------------------|
|Strategy=>GRevLexSmallest)                                                   |
+-----------------------------------------------------------------------------+
|i53 : time regularInCodimension(1, S/J, MaxMinors => 100,                    |
| -- used 3.9272s (cpu); 3.62679s (thread); 0s (gc)                           |
|-----------------------------------------------------------------------------|
|Strategy=>GRevLexSmallestTerm)                                               |
+-----------------------------------------------------------------------------+
|i54 : time regularInCodimension(1, S/J, MaxMinors => 100, Strategy=>Points)  |
| -- used 11.0291s (cpu); 10.0334s (thread); 0s (gc)                          |
|                                                                             |
|o54 = true                                                                   |
+-----------------------------------------------------------------------------+
|i55 : time regularInCodimension(1, S/J, MaxMinors => 100,                    |
| -- used 8.52542s (cpu); 7.76759s (thread); 0s (gc)                          |
|                                                                             |
|o55 = true                                                                   |
|-----------------------------------------------------------------------------|
|Strategy=>StrategyDefaultWithPoints)                                         |
+-----------------------------------------------------------------------------+

If regularInCodimension outputs nothing, then it couldn't verify that the ring
was regular in that codimension.  We set MaxMinors => 100 to keep it from
running too long with an ineffective strategy.  Again, even though
GRevLexSmallest and GRevLexSmallestTerm are not effective in this particular
example, in others they perform better than other strategies.  Note similar
considerations also apply to projDim.

See also
========

  * chooseGoodMinors(...,Strategy=>...) -- strategies
    for choosing submatrices
  * RegularInCodimensionTutorial -- A
    tutorial for how to use the advanced options of the regularInCodimension
    function

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

The object FastMinorsStrategyTutorial, is a
symbol (Macaulay2Doc).

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

The source of this document is in FastMinors.m2:1525:0.

getSubmatrixOfRank -- tries to find a submatrix of the given rank
*****************************************************************

  * Usage:
        getSubmatrixOfRank(n1, M1)
  * Inputs:
      * n1, an integer (Macaulay2Doc),
      * M1, a matrix (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * DetStrategy, => ..., default value Rank, DetStrategy
        is a strategy for allowing the user to choose how determinants (or
        rank), is computed
      * MaxMinors, => ..., default value null, an option to
        control depth of search
      * PointOptions, => ..., default value {Strategy =>
        Default, Homogeneous => false, Replacement => Binomial, ExtendField =>
        true, PointCheckAttempts => 0, DecompositionStrategy => Decompose,
        NumThreadsToUse => 1, DimensionFunction => dim, Verbose => false},
        options to pass to functions in the package RandomPoints
      * Strategy, => ..., default value new OptionTable
        from {Points => 0, Random => 0, GRevLexLargest => 0, LexSmallestTerm =>
        25, LexLargest => 0, LexSmallest => 25, GRevLexSmallestTerm => 25,
        RandomNonzero => 0, GRevLexSmallest => 25}, strategies for choosing
        submatrices
      * Threads, =>
        ..., default value 1, an option for various functions
      * Verbose => ..., default value false
  * Outputs:
      * a list (Macaulay2Doc), the first entry is a list of row
        indices, the second is a list of column indices

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

This function looks at submatrices of the given matrix, and tries to find one
of the specified rank.  If it succeeds, it returns a list of two lists. The
first is the list of row indices, the second is the list of columns, of the
desired rank submatrix. If it fails to find such a matrix, the function returns
null.  The option MaxMinors is used to control how many minors to consider.  If
left null, the number considered is based on the size of the matrix.

+-----------------------------------------------------------+
|i1 : R = QQ[x,y];                                          |
+-----------------------------------------------------------+
|i2 : M = matrix{{x,y,2,0,2*x+y}, {0,0,1,0,x}, {x,y,0,0,y}};|
|                                                           |
|             3      5                                      |
|o2 : Matrix R  <-- R                                       |
+-----------------------------------------------------------+
|i3 : l = getSubmatrixOfRank(2, M)                          |
|                                                           |
|o3 = {{1, 2}, {2, 1}}                                      |
|                                                           |
|o3 : List                                                  |
+-----------------------------------------------------------+
|i4 : (M^(l#0))_(l#1)                                       |
|                                                           |
|o4 = | 1 0 |                                               |
|     | 0 y |                                               |
|                                                           |
|             2      2                                      |
|o4 : Matrix R  <-- R                                       |
+-----------------------------------------------------------+
|i5 : l = getSubmatrixOfRank(2, M)                          |
|                                                           |
|o5 = {{1, 0}, {2, 1}}                                      |
|                                                           |
|o5 : List                                                  |
+-----------------------------------------------------------+
|i6 : (M^(l#0))_(l#1)                                       |
|                                                           |
|o6 = | 1 0 |                                               |
|     | 2 y |                                               |
|                                                           |
|             2      2                                      |
|o6 : Matrix R  <-- R                                       |
+-----------------------------------------------------------+
|i7 : getSubmatrixOfRank(3, M)                              |
+-----------------------------------------------------------+

The option Strategy is used to used to control how the function computes the
rank of the submatrices considered.  See
getSubmatrixOfRank(...,Strategy=>...). In the future, we hope
to speed up the function to use multiple threads of execution, in which case
the threading would be controlled by the option Threads.

See also
========

  * isRankAtLeast -- determines if the matrix has rank at
    least a number
  * getSubmatrixOfRank(...,Strategy=>...) -- strategies
    for choosing submatrices

Ways to use getSubmatrixOfRank:
===============================

  * "getSubmatrixOfRank(ZZ,Matrix)"

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

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

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

The source of this document is in FastMinors.m2:1772:0.

isCodimAtLeast -- returns true if we can quickly see whether the codim is at least a given number
*************************************************************************************************

  * Usage:
        isCodimAtLeast(n, I)
  * Inputs:
      * n, an integer (Macaulay2Doc), an integer
      * I, an ideal (Macaulay2Doc), an ideal in a polynomial ring
        over a field, or a quotient ring
  * Optional inputs (Macaulay2Doc),:
      * SPairsFunction => a function (Macaulay2Doc), default
        value FunctionClosure[../FastMinors.m2:211:23-211:42], a function to
        control how when the codimension of minors is computed, default is
        i->ceiling(1.5^i)
      * PairLimit => a number (Macaulay2Doc), default value 100,
        the max value to be plugged into SPairsFunction
      * Verbose => ..., default value false
  * Outputs:
      * true if the codimension of I is at least n or null if the function
        cannot tell whether the codimension is at least n

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

This computes a partial Groebner basis, takes the initial terms, and checks
whether that (partial) initial ideal has codimension at least n. Consider the
following example.  We create an ideal of 15 minors of the matrix myDiff (a
matrix constructed in a way typical of applications).  We would like to verify
that the codimension of this ideal is at least 3.  The built-in codim function
typically does not terminate. However, isCodimAtLeast is normally very fast.

+-----------------------------------------------------------------------------+
|i1 : R = ZZ/127[x_1 .. x_(12)];                                              |
+-----------------------------------------------------------------------------+
|i2 : P = minors(3,genericMatrix(R,x_1,3,4));                                 |
|                                                                             |
|o2 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i3 : C = res (R^1/(P^3));                                                    |
+-----------------------------------------------------------------------------+
|i4 : myDiff = C.dd_3;                                                        |
|                                                                             |
|             30      12                                                      |
|o4 : Matrix R   <-- R                                                        |
+-----------------------------------------------------------------------------+
|i5 : r = rank myDiff;                                                        |
+-----------------------------------------------------------------------------+
|i6 : J = chooseGoodMinors(15, r, myDiff, Strategy=>StrategyDefaultNonRandom);|
|                                                                             |
|o6 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i7 : time isCodimAtLeast(3, J)                                               |
| -- used 0.00441545s (cpu); 0.0036677s (thread); 0s (gc)                     |
|                                                                             |
|o7 = true                                                                    |
+-----------------------------------------------------------------------------+

The function works by computing gb(I, PairLimit=>f(i)) for successive values of
i.  Here f(i) is a function that takes t, some approximation of the base degree
value of the polynomial ring (for example, in a standard graded polynomial
ring, this is probably expected to be \{1\}).  And i is a counting variable.
You can provide your own function by calling isCodimAtLeast(n, I,
SPairsFunction=>( (i) -> f(i) ), the default function is
SPairsFunction=>i->ceiling(1.5^i)   Perhaps more commonly however, the user may
want to instead tell the function to compute for larger values of i.  This is
done via the option PairLimit.  This is the max value of i to be plugged into
SPairsFunction before the function gives up.  In other words, PairLimit=>5 will
tell the function to check codimension 5 times.

+-----------------------------------------------------------------------------+
|i8 : I = ideal(x_2^8*x_10^3-3*x_1*x_2^7*x_10^2*x_11+3*x_1^2*x_2^6*x_10*x_11^2|
|                                                                             |
|               ZZ                                                            |
|o8 : Ideal of ---[x  , x , x , x , x  , x , x , x  , x , x , x , x ]         |
|              127  11   8   1   9   12   6   5   10   2   4   3   7          |
|-----------------------------------------------------------------------------|
|-x_1^3*x_2^5*x_11^3,x_5^5*x_6^3*x_11^3-3*x_5^6*x_6^2*x_11^2*x_12+3*x_5^7*x_6*|
|-----------------------------------------------------------------------------|
|x_11*x_12^2-x_5^8*x_12^3,x_1^5*x_2^3*x_4^3-3*x_1^6*x_2^2*x_4^2*x_5+3*x_1^7*x_|
|-----------------------------------------------------------------------------|
|2*x_4*x_5^2-x_1^8*x_5^3,x_6^8*x_11^3-3*x_5*x_6^7*x_11^2*x_12+3*x_5^2*x_6^6*x_|
|-----------------------------------------------------------------------------|
|11*x_12^2-x_5^3*x_6^5*x_12^3,x_8^3*x_10^8-3*x_7*x_8^2*x_10^7*x_11+3*x_7^2*x_8|
|-----------------------------------------------------------------------------|
|*x_10^6*x_11^2-x_7^3*x_10^5*x_11^3,x_2^8*x_4^3-3*x_1*x_2^7*x_4^2*x_5+3*x_1^2*|
|-----------------------------------------------------------------------------|
|x_2^6*x_4*x_5^2-x_1^3*x_2^5*x_5^3,-x_6^3*x_11^8+3*x_5*x_6^2*x_11^7*x_12-3*x_5|
|-----------------------------------------------------------------------------|
|^2*x_6*x_11^6*x_12^2+x_5^3*x_11^5*x_12^3,-x_6^3*x_7^3*x_9^5+3*x_4*x_6^2*x_7^2|
|-----------------------------------------------------------------------------|
|*x_9^6-3*x_4^2*x_6*x_7*x_9^7+x_4^3*x_9^8,x_8^8*x_10^3-3*x_7*x_8^7*x_10^2*x_11|
|-----------------------------------------------------------------------------|
|+3*x_7^2*x_8^6*x_10*x_11^2-x_7^3*x_8^5*x_11^3,x_2^5*x_3^3*x_11^3-3*x_2^6*x_3^|
|-----------------------------------------------------------------------------|
|2*x_11^2*x_12+3*x_2^7*x_3*x_11*x_12^2-x_2^8*x_12^3);                         |
+-----------------------------------------------------------------------------+
|i9 : time isCodimAtLeast(5, I, PairLimit => 5, Verbose=>true)                |
| -- used 0.0029602s (cpu); 0.0033587s (thread); 0s (gc)                      |
|isCodimAtLeast: Computing codim of monomials based on ideal generators.      |
|                                                                             |
|o9 = true                                                                    |
+-----------------------------------------------------------------------------+
|i10 : time isCodimAtLeast(5, I, PairLimit => 200, Verbose=>false)            |
| -- used 0.00270256s (cpu); 0.00343537s (thread); 0s (gc)                    |
|                                                                             |
|o10 = true                                                                   |
+-----------------------------------------------------------------------------+

Notice in the first case the function returned null, because the depth of
search was not high enough.  It only computed codim 5 times.  The second
returned true, but it did so as soon as the answer was found (and before we hit
the PairLimit limit).

Ways to use isCodimAtLeast:
===========================

  * "isCodimAtLeast(ZZ,Ideal)"

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

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

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

The source of this document is in FastMinors.m2:2246:0.

isDimAtMost -- returns true if we can quickly see whether the dim is at most a given number
*******************************************************************************************

  * Usage:
        isDimAtMost(n, I)
  * Inputs:
      * n, an integer (Macaulay2Doc), an integer
      * I, an ideal (Macaulay2Doc), an ideal in a polynomial ring
        over a field, or a quotient ring of such
  * Optional inputs (Macaulay2Doc),:
      * PairLimit => ..., default value 100
      * SPairsFunction => ..., default value
        FunctionClosure[../FastMinors.m2:211:23-211:42]
      * Verbose => ..., default value false
  * Outputs:
      * true if the dimension of I is at most n or null if the function cannot
        tell whether the dimension is at most n

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

This simply calls isCodimAtLeast, passing options as described there.

See also
========

  * isCodimAtLeast -- returns true if we can quickly see
    whether the codim is at least a given number

Ways to use isDimAtMost:
========================

  * "isDimAtMost(ZZ,Ideal)"

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

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

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

The source of this document is in FastMinors.m2:2272:0.

isRankAtLeast -- determines if the matrix has rank at least a number
********************************************************************

  * Usage:
        isRankAtLeast(n1, M1)
  * Inputs:
      * n1, an integer (Macaulay2Doc),
      * M1, a matrix (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * DetStrategy, => ..., default value Rank, DetStrategy
        is a strategy for allowing the user to choose how determinants (or
        rank), is computed
      * MaxMinors, => ..., default value null, an option to
        control depth of search
      * PointOptions, => ..., default value {Strategy =>
        Default, Homogeneous => false, Replacement => Binomial, ExtendField =>
        true, PointCheckAttempts => 0, DecompositionStrategy => Decompose,
        NumThreadsToUse => 1, DimensionFunction => dim, Verbose => false},
        options to pass to functions in the package RandomPoints
      * Strategy, => ..., default value new OptionTable
        from {Points => 0, Random => 0, GRevLexLargest => 0, LexSmallestTerm =>
        25, LexLargest => 0, LexSmallest => 25, GRevLexSmallestTerm => 25,
        RandomNonzero => 0, GRevLexSmallest => 25}, strategies for choosing
        submatrices
      * Threads, =>
        ..., default value 1, an option for various functions
      * Verbose => ..., default value false
  * Outputs:
      * a Boolean value (Macaulay2Doc),

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

This function tries to quickly determine whether the matrix has a given rank.
isRankAtLeast calls getSubmatrixOfRank.  If that
function finds a submatrix of a certain rank, this returns true.  If that
function fails to find a submatrix of a certain rank, this simply calls
rank (Macaulay2Doc).  To control the number of times getSubmatrixOfRank
considers submatrices, use the option MaxMinors.

+-----------------------------------------------------------+
|i1 : R = QQ[x,y];                                          |
+-----------------------------------------------------------+
|i2 : M = matrix{{x,y,2,0,2*x+y}, {0,0,1,0,x}, {x,y,0,0,y}};|
|                                                           |
|             3      5                                      |
|o2 : Matrix R  <-- R                                       |
+-----------------------------------------------------------+
|i3 : rank M                                                |
|                                                           |
|o3 = 2                                                     |
+-----------------------------------------------------------+
|i4 : isRankAtLeast(2, M)                                   |
|                                                           |
|o4 = true                                                  |
+-----------------------------------------------------------+
|i5 : isRankAtLeast(3, M)                                   |
|                                                           |
|o5 = false                                                 |
+-----------------------------------------------------------+

The option Threads can be used allow the function use multiple threads of
execution.  If allowableThreads is above 2 and Threads is set above 1, then
this function will try to simultaneously compute the rank of the matrix while
looking for a submatrix of a certain rank.

See also
========

  * getSubmatrixOfRank -- tries to find a submatrix
    of the given rank
  * isRankAtLeast(...,Strategy=>...) -- strategies for
    choosing submatrices

Ways to use isRankAtLeast:
==========================

  * "isRankAtLeast(ZZ,Matrix)"

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

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

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

The source of this document is in FastMinors.m2:1731:0.

isRankAtLeast(...,Threads=>...) -- an option for various functions
******************************************************************

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

Increasing this option may tell various functions to multithread their
operations.  You may also want to increase allowableThreads.

See also
========

  * isRankAtLeast -- determines if the matrix has rank at
    least a number
  * getSubmatrixOfRank -- tries to find a submatrix
    of the given rank
  * recursiveMinors -- uses a recursive cofactor
    algorithm to compute the ideal of minors of a matrix

Functions with optional argument named Threads:
===============================================

  * "getSubmatrixOfRank(...,Threads=>...)"
  * isRankAtLeast(...,Threads=>...)
    -- an option for various
    functions
  * "recursiveMinors(...,Threads=>...)"

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

  * Default value: 1
  * Function: isRankAtLeast, -- determines if the matrix
    has rank at least a number
  * Option key: Threads (Macaulay2Doc), -- an optional argument
-------------------------------------------------------------------------------

The source of this document is in FastMinors.m2:2120:0.

MaxMinors -- an option to control depth of search
*************************************************

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

This option controls how many minors various functions consider.  Increasing it
will make certain functions search longer, but may make them give more useful
outputs.  The functions projDim and regularInCodimension can also take in more
complicated inputs.  See their documentation for details.

See also
========

  * regularInCodimension -- attempts to show that
    the ring is regular in codimension n
  * projDim -- finds an upper bound for the projective
    dimension of a module
  * isRankAtLeast -- determines if the matrix has rank at
    least a number
  * getSubmatrixOfRank -- tries to find a submatrix
    of the given rank

Functions with optional argument named MaxMinors:
=================================================

  * "getSubmatrixOfRank(...,MaxMinors=>...)"
  * "isRankAtLeast(...,MaxMinors=>...)"
  * "projDim(...,MaxMinors=>...)"
  * "regularInCodimension(...,MaxMinors=>...)"

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

The object MaxMinors, is a symbol (Macaulay2Doc).

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

The source of this document is in FastMinors.m2:2139:0.

MinDimension -- an option for projDim
*************************************

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

This option is used to tell the function projDim not to look for projective
dimension below the option value.

See also
========

  * projDim -- finds an upper bound for the projective
    dimension of a module

Functions with optional argument named MinDimension:
====================================================

  * "projDim(...,MinDimension=>...)" -- see projDim, -- finds an
    upper bound for the projective dimension of a module

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

The object MinDimension, is a symbol (Macaulay2Doc).

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

The source of this document is in FastMinors.m2:2092:0.

Modulus -- an option for regularInCodimension
*********************************************

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

This option is used to tell the function to do the computation modulo a prime
p.

See also
========

  * regularInCodimension -- attempts to show that
    the ring is regular in codimension n

Functions with optional argument named Modulus:
===============================================

  * "regularInCodimension(...,Modulus=>...)" -- see regularInCodimension,
    -- attempts to show that the ring is regular in
    codimension n

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

The object Modulus, is a symbol (Macaulay2Doc).

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

The source of this document is in FastMinors.m2:2104:0.

PointOptions -- options to pass to functions in the package RandomPoints
************************************************************************

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

PointOptions is an option in various functions in this package, which can store
options to be passed to the function findANonZeroMinor and other functions in
RandomPoints.

+-----------------------------------------------------------------------------+
|i1 : (options regularInCodimension)#PointOptions                             |
|                                                                             |
|o1 = {Strategy => Default, Homogeneous => false, Replacement => Binomial,    |
|     ------------------------------------------------------------------------|
|     ExtendField => true, PointCheckAttempts => 0, DecompositionStrategy =>  |
|     ------------------------------------------------------------------------|
|     Decompose, NumThreadsToUse => 1, DimensionFunction => dim, Verbose =>   |
|     ------------------------------------------------------------------------|
|     false}                                                                  |
|                                                                             |
|o1 : List                                                                    |
+-----------------------------------------------------------------------------+
|i2 : options findANonZeroMinor                                               |
|                                                                             |
|o2 = OptionTable{DecompositionStrategy => null}                              |
|                 DimensionFunction => dim                                    |
|                 ExtendField => true                                         |
|                 Homogeneous => false                                        |
|                 MinorPointAttempts => 5                                     |
|                 NumThreadsToUse => 1                                        |
|                 PointCheckAttempts => 0                                     |
|                 Replacement => Binomial                                     |
|                 Strategy => Default                                         |
|                 Verbose => false                                            |
|                                                                             |
|o2 : OptionTable                                                             |
+-----------------------------------------------------------------------------+

The default setting ExtendField => true means that points whose residue field
are finite extensions of the prime field are valid, and are used to study the
matrix.  Furthermore, we have set Homogeneous=>false by default which means the
origin is treated as a valid point.  Setting ExtendField=>false will sometimes
speed up computation, but can also miss some important submatrices if that
determinant (plus what has already been computed) defines a scheme with no or
relatively few rational points.  In such a case, ExtendField => false will
typically substantially slow down computations.

See also
========

  * findANonZeroMinor (RandomPoints) -- finds a
    non-vanishing minor at some randomly chosen point

Functions with optional argument named PointOptions:
====================================================

  * "chooseGoodMinors(...,PointOptions=>...)"
  * "getSubmatrixOfRank(...,PointOptions=>...)"
  * "isRankAtLeast(...,PointOptions=>...)"
  * "projDim(...,PointOptions=>...)"
  * "regularInCodimension(...,PointOptions=>...)"

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

The object PointOptions, is a symbol (Macaulay2Doc).

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

The source of this document is in FastMinors.m2:1794:0.

projDim -- finds an upper bound for the projective dimension of a module
************************************************************************

  * Usage:
        n = projDim(N, MinDimension=>d)
  * Inputs:
      * N, a module (Macaulay2Doc), a module over a polynomial
        ring
      * d, an integer (Macaulay2Doc), the minimum projective
        dimension of the module
  * Optional inputs (Macaulay2Doc),:
      * MinDimension => a number (Macaulay2Doc), default value 0,
        stop after verifying the module has at most a certain projective
        dimension
      * PointOptions, => a list (Macaulay2Doc),
        default value {Strategy => Default, Homogeneous => false, Replacement
        => Binomial, ExtendField => true, PointCheckAttempts => 0,
        DecompositionStrategy => Decompose, NumThreadsToUse => 1,
        DimensionFunction => dim, Verbose => false}, options to be passed to
        the RandomPoints package
      * MaxMinors, => ..., default value
        FunctionClosure[../FastMinors.m2:186:18-186:45], used to control how
        many minors are computed of the matrices in a projective resolution
      * DetStrategy, => ..., default value Cofactor,
        DetStrategy is a strategy for allowing the user to choose how
        determinants (or rank), is computed
      * Strategy, => ..., default value new OptionTable
        from {Points => 0, Random => 16, GRevLexLargest => 0, LexSmallestTerm
        => 16, LexLargest => 0, LexSmallest => 16, GRevLexSmallestTerm => 16,
        RandomNonzero => 16, GRevLexSmallest => 16}, strategies for choosing
        submatrices
      * Verbose => ..., default value false
  * Outputs:
      * n, an integer (Macaulay2Doc), an upper bound for the
        projective dimension of N

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

The function pdim returns the length of a projective resolution. If the module
passed is not homogeneous, then the projective resolution may not be minimal
and so pdim can give the wrong answer.  This function projDim tries to improve
this bound by considering ideals of appropriately sized minors of the
resolution (starting from the end of the resolution and working backwards).
Using the option MinDimension (default value 0) gives a lower bound on the
projective dimension, increasing it can thus improve the speed of computation.

+------------------------------------------------------------------------+
|i1 : R = QQ[x,y];                                                       |
+------------------------------------------------------------------------+
|i2 : I = ideal((x^3+y)^2, (x^2+y^2)^2, (x+y^3)^2, (x*y)^2);             |
|                                                                        |
|o2 : Ideal of R                                                         |
+------------------------------------------------------------------------+
|i3 : pdim(module I)                                                     |
|                                                                        |
|o3 = 2                                                                  |
+------------------------------------------------------------------------+
|i4 : time projDim(module I, Strategy=>StrategyRandom)                   |
| -- used 0.273368s (cpu); 0.208748s (thread); 0s (gc)                   |
|                                                                        |
|o4 = 1                                                                  |
+------------------------------------------------------------------------+
|i5 : time projDim(module I, Strategy=>StrategyRandom, MinDimension => 1)|
| -- used 0.0174135s (cpu); 0.0180291s (thread); 0s (gc)                 |
|                                                                        |
|o5 = 1                                                                  |
+------------------------------------------------------------------------+

The option MaxMinors can be used to control how many minors are computed at
each step. If this is not specified, the number of minors is a function of the
dimension $d$ of the polynomial ring and the possible minors $c$. Specifically
it is 10 * d + 2 * log_1.3(c). Otherwise the user can set the option MaxMinors
=> ZZ to specify that a fixed integer is used for each step.  Alternatively,
the user can control the number of minors computed at each step by setting the
option MaxMinors => List.  In this case, the list specifies how many minors to
be computed at each step, (working backwards). Finally, you can also set
MaxMinors to be a custom function of the dimension $d$ of the polynomial ring
and the maximum number of minors.

See also
========

  * pdim (Macaulay2Doc) -- compute the projective dimension

Ways to use projDim:
====================

  * "projDim(Module)"

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

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

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

The source of this document is in FastMinors.m2:2079:0.

recursiveMinors -- uses a recursive cofactor algorithm to compute the ideal of minors of a matrix
*************************************************************************************************

  * Usage:
        I = recursiveMinors(n, M, Threads=>t, MinorsCache=>b)
  * Inputs:
      * n, an integer (Macaulay2Doc), the size of minors to compute
      * M, a matrix (Macaulay2Doc),
      * t, an integer (Macaulay2Doc), an optional input, which
        describes the number of threads to uses
      * b, a Boolean value (Macaulay2Doc), an optional input,
        which says whether to cache in input
  * Optional inputs (Macaulay2Doc),:
      * MinorsCache => ..., default value true
      * Threads, =>
        ..., default value 0, an option for various functions
      * Verbose => ..., default value false
  * Outputs:
      * I, an ideal (Macaulay2Doc), the ideal of minors of M

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

Given a matrix $M$, this computes the ideal of determinants of size $n \times
n$ submatrices. The recursiveMinors function uses a recursive strategy, keeping
track of the smaller minors computed so far, unlike the built-in Cofactor
strategy for minors

+-----------------------------------------------------+
|i1 : R = QQ[x,y];                                    |
+-----------------------------------------------------+
|i2 : M = random(R^{5,5,5,5,5,5}, R^7);               |
|                                                     |
|             6      7                                |
|o2 : Matrix R  <-- R                                 |
+-----------------------------------------------------+
|i3 : time I2 = recursiveMinors(4, M, Threads=>0);    |
| -- used 0.681867s (cpu); 0.616727s (thread); 0s (gc)|
|                                                     |
|o3 : Ideal of R                                      |
+-----------------------------------------------------+
|i4 : time I1 = minors(4, M, Strategy=>Cofactor);     |
| -- used 1.75346s (cpu); 1.66991s (thread); 0s (gc)  |
|                                                     |
|o4 : Ideal of R                                      |
+-----------------------------------------------------+
|i5 : I1 == I2                                        |
|                                                     |
|o5 = true                                            |
+-----------------------------------------------------+

See also
========

  * minors (Macaulay2Doc) -- ideal generated by
    minors

Ways to use recursiveMinors:
============================

  * "recursiveMinors(ZZ,Matrix)"

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

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

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

The source of this document is in FastMinors.m2:2030:0.

regularInCodimension -- attempts to show that the ring is regular in codimension n
**********************************************************************************

  * Usage:
        regularInCodimension(n, R)
  * Inputs:
      * n, an integer (Macaulay2Doc),
      * R, a ring (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * Modulus => a number (Macaulay2Doc), default value 0, work
        modulo the given prime modulus
      * PairLimit => a number (Macaulay2Doc), default value 100,
        passed to isCodimAtLeast
      * SPairsFunction => a function (Macaulay2Doc), default
        value FunctionClosure[../FastMinors.m2:169:23-169:42], passed to
        isCodimAtLeast
      * UseOnlyFastCodim => a Boolean value (Macaulay2Doc),
        default value false, tell the function not to use the built in dim
        command and only use isCodimAtLeast
      * MinMinorsFunction => a function (Macaulay2Doc), default
        value FunctionClosure[../FastMinors.m2:164:26-164:40], control how many
        minors are computed before computing codim
      * MaxMinors, => a function (Macaulay2Doc),
        default value
        FunctionClosure[../FastMinors.m2:159:18-159:50], how many minors to
        consider before giving up
      * CodimCheckFunction => a function (Macaulay2Doc),
        default value FunctionClosure[../FastMinors.m2:165:27-165:46], control
        how many minors to compute in between calls to codim
      * DetStrategy, => ..., default value Cofactor,
        DetStrategy is a strategy for allowing the user to choose how
        determinants (or rank), is computed
      * PointOptions, => ..., default value {Strategy =>
        Default, Homogeneous => false, Replacement => Binomial, ExtendField =>
        true, PointCheckAttempts => 0, DecompositionStrategy => Decompose,
        NumThreadsToUse => 1, DimensionFunction => dim, Verbose => false},
        options to pass to functions in the package RandomPoints
      * Strategy, => ..., default value new OptionTable
        from {Points => 0, Random => 16, GRevLexLargest => 0, LexSmallestTerm
        => 16, LexLargest => 0, LexSmallest => 16, GRevLexSmallestTerm => 16,
        RandomNonzero => 16, GRevLexSmallest => 16}, strategies for choosing
        submatrices
      * Verbose => ..., default value false
  * Outputs:
      * true, if the ring is regular in codimension n, false if it determines
        it is not, and null if no determination is made

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

This function returns true if R is regular in codimension n, false if it is
not, and null if it did not make a determination. It considers interesting
minors of the jacobian matrix to try to verify that the ring is regular in
codimension n. It is frequently much faster at giving an affirmative answer
than computing the dimension of the ideal of all minors of the Jacobian. We
begin with a simple example which is R1, but not R2.

+------------------------------------+
|i1 : R = QQ[x, y, z]/ideal(x*y-z^2);|
+------------------------------------+
|i2 : regularInCodimension(1, R)     |
|                                    |
|o2 = true                           |
+------------------------------------+
|i3 : regularInCodimension(2, R)     |
+------------------------------------+

Next we consider a more interesting example that is R1 but not R2, and
highlight the speed differences.  Note that regularInCodimension(2, R) returns
nothing, as the function did not determine whether the ring was regular in
codimension n.

+-----------------------------------------------------------------------------+
|i4 : T = ZZ/101[x1,x2,x3,x4,x5,x6,x7];                                       |
+-----------------------------------------------------------------------------+
|i5 : I =  ideal(x5*x6-x4*x7,x1*x6-x2*x7,x5^2-x1*x7,x4*x5-x2*x7,x4^2-x2*x6,x1*|
|                                                                             |
|o5 : Ideal of T                                                              |
|-----------------------------------------------------------------------------|
|x4-x2*x5,x2*x3^3*x5+3*x2*x3^2*x7+8*x2^2*x5+3*x3*x4*x7-8*x4*x7+x6*x7,x1*x3^3* |
|-----------------------------------------------------------------------------|
|x5+3*x1*x3^2*x7+8*x1*x2*x5+3*x3*x5*x7-8*x5*x7+x7^2,x2*x3^3*x4+3*x2*x3^2*x6+8*|
|-----------------------------------------------------------------------------|
|x2^2*x4+3*x3*x4*x6-8*x4*x6+x6^2,x2^2*x3^3+3*x2*x3^2*x4+8*x2^3+3*x2*x3*x6-8*x2|
|-----------------------------------------------------------------------------|
|*x6+x4*x6,x1*x2*x3^3+3*x2*x3^2*x5+8*x1*x2^2+3*x2*x3*x7-8*x2*x7+x4*x7,x1^2*x3^|
|-----------------------------------------------------------------------------|
|3+3*x1*x3^2*x5+8*x1^2*x2+3*x1*x3*x7-8*x1*x7+x5*x7);                          |
+-----------------------------------------------------------------------------+
|i6 : S = T/I;                                                                |
+-----------------------------------------------------------------------------+
|i7 : dim S                                                                   |
|                                                                             |
|o7 = 3                                                                       |
+-----------------------------------------------------------------------------+
|i8 : time regularInCodimension(1, S)                                         |
| -- used 0.757856s (cpu); 0.661082s (thread); 0s (gc)                        |
|                                                                             |
|o8 = true                                                                    |
+-----------------------------------------------------------------------------+
|i9 : time regularInCodimension(2, S)                                         |
| -- used 7.34201s (cpu); 6.37152s (thread); 0s (gc)                          |
+-----------------------------------------------------------------------------+

There are numerous examples where regularInCodimension is several orders of
magnitude faster that calls of dim singularLocus.

The following is a (pruned) affine chart on an Abelian surface obtained as a
product of two elliptic curves.  It is nonsingular, as our function verifies.
If one does not prune it, then the dim singularLocus call takes an enormous
amount of time, otherwise the running times of dim singularLocus and our
function are frequently about the same.

+-----------------------------------------------------------------------------+
|i10 : R = QQ[c, f, g, h]/ideal(g^3+h^3+1,f*g^3+f*h^3+f,c*g^3+c*h^3+c,f^2*g^3+|
|-----------------------------------------------------------------------------|
|f^2*h^3+f^2,c*f*g^3+c*f*h^3+c*f,c^2*g^3+c^2*h^3+c^2,f^3*g^3+f^3*h^3+f^3,c*f^2|
|-----------------------------------------------------------------------------|
|*g^3+c*f^2*h^3+c*f^2,c^2*f*g^3+c^2*f*h^3+c^2*f,c^3-f^2-c,c^3*h-f^2*h-c*h,c^3*|
|-----------------------------------------------------------------------------|
|g-f^2*g-c*g,c^3*h^2-f^2*h^2-c*h^2,c^3*g*h-f^2*g*h-c*g*h,c^3*g^2-f^2*g^2-c*g^2|
|-----------------------------------------------------------------------------|
|,c^3*h^3-f^2*h^3-c*h^3,c^3*g*h^2-f^2*g*h^2-c*g*h^2,c^3*g^2*h-f^2*g^2*h-c*g^2*|
|-----------------------------------------------------------------------------|
|h,c^3*g^3+f^2*h^3+c*h^3+f^2+c);                                              |
+-----------------------------------------------------------------------------+
|i11 : dim(R)                                                                 |
|                                                                             |
|o11 = 2                                                                      |
+-----------------------------------------------------------------------------+
|i12 : time (dim singularLocus (R))                                           |
| -- used 0.026922s (cpu); 0.0269324s (thread); 0s (gc)                       |
|                                                                             |
|o12 = -1                                                                     |
+-----------------------------------------------------------------------------+
|i13 : time regularInCodimension(2, R)                                        |
| -- used 0.202214s (cpu); 0.179637s (thread); 0s (gc)                        |
|                                                                             |
|o13 = true                                                                   |
+-----------------------------------------------------------------------------+
|i14 : time regularInCodimension(2, R)                                        |
| -- used 0.946137s (cpu); 0.806894s (thread); 0s (gc)                        |
|                                                                             |
|o14 = true                                                                   |
+-----------------------------------------------------------------------------+
|i15 : time regularInCodimension(2, R)                                        |
| -- used 1.39978s (cpu); 1.14748s (thread); 0s (gc)                          |
|                                                                             |
|o15 = true                                                                   |
+-----------------------------------------------------------------------------+

The function works by choosing interesting looking submatrices, computing their
determinants, and periodically (based on a logarithmic growth setting),
computing the dimension of a subideal of the Jacobian. The option Verbose can
be used to see this in action.

+-----------------------------------------------------------------------------+
|i16 : time regularInCodimension(2, S, Verbose=>true)                         |
|regularInCodimension: ring dimension =3, there are 17325 possible 4 by 4 mino|
|regularInCodimension: About to enter loop                                    |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing RandomNonZero                                  |
|regularInCodimension:  Loop step, about to compute dimension.  Submatrices co|
|regularInCodimension:  isCodimAtLeast failed, computing codim.               |
|regularInCodimension:  partial singular locus dimension computed, = 2        |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|regularInCodimension:  Loop step, about to compute dimension.  Submatrices co|
|regularInCodimension:  isCodimAtLeast failed, computing codim.               |
|regularInCodimension:  partial singular locus dimension computed, = 2        |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing RandomNonZero                                  |
|regularInCodimension:  Loop step, about to compute dimension.  Submatrices co|
|regularInCodimension:  isCodimAtLeast failed, computing codim.               |
|regularInCodimension:  partial singular locus dimension computed, = 2        |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing LexSmallest                                    |
|regularInCodimension:  Loop step, about to compute dimension.  Submatrices co|
|regularInCodimension:  isCodimAtLeast failed, computing codim.               |
|regularInCodimension:  partial singular locus dimension computed, = 1        |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|regularInCodimension:  Loop step, about to compute dimension.  Submatrices co|
|regularInCodimension:  isCodimAtLeast failed, computing codim.               |
|regularInCodimension:  partial singular locus dimension computed, = 1        |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|regularInCodimension:  Loop step, about to compute dimension.  Submatrices co|
|regularInCodimension:  isCodimAtLeast failed, computing codim.               |
|regularInCodimension:  partial singular locus dimension computed, = 1        |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing LexSmallest                                    |
|regularInCodimension:  Loop step, about to compute dimension.  Submatrices co|
|regularInCodimension:  isCodimAtLeast failed, computing codim.               |
|regularInCodimension:  partial singular locus dimension computed, = 1        |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|regularInCodimension:  Loop step, about to compute dimension.  Submatrices co|
|regularInCodimension:  isCodimAtLeast failed, computing codim.               |
|regularInCodimension:  partial singular locus dimension computed, = 1        |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|regularInCodimension:  Loop step, about to compute dimension.  Submatrices co|
|regularInCodimension:  isCodimAtLeast failed, computing codim.               |
|regularInCodimension:  partial singular locus dimension computed, = 1        |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|regularInCodimension:  Loop step, about to compute dimension.  Submatrices co|
|regularInCodimension:  isCodimAtLeast failed, computing codim.               |
|regularInCodimension:  partial singular locus dimension computed, = 1        |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing Random                                         |
|regularInCodimension:  Loop step, about to compute dimension.  Submatrices co|
|regularInCodimension:  isCodimAtLeast failed, computing codim.               |
|regularInCodimension:  partial singular locus dimension computed, = 1        |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|regularInCodimension:  Loop step, about to compute dimension.  Submatrices co|
|regularInCodimension:  isCodimAtLeast failed, computing codim.               |
|regularInCodimension:  partial singular locus dimension computed, = 1        |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|regularInCodimension:  Loop step, about to compute dimension.  Submatrices co|
|regularInCodimension:  isCodimAtLeast failed, computing codim.               |
|regularInCodimension:  partial singular locus dimension computed, = 1        |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Ch -- used 7.4039s (cpu); 6.44207s (thread); 0s (gc)    |
|oosing GRevLexSmallestTerm                                                   |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing RandomNonZero                                  |
|regularInCodimension:  Loop step, about to compute dimension.  Submatrices co|
|regularInCodimension:  isCodimAtLeast failed, computing codim.               |
|regularInCodimension:  partial singular locus dimension computed, = 1        |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing Random                                         |
|regularInCodimension:  Loop step, about to compute dimension.  Submatrices co|
|regularInCodimension:  isCodimAtLeast failed, computing codim.               |
|regularInCodimension:  partial singular locus dimension computed, = 1        |
|regularInCodimension:  Loop completed, submatrices considered = 328, and comp|
|-----------------------------------------------------------------------------|
|rs, we will compute up to 327.599 of them.                                   |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|nsidered: 9, and computed = 9                                                |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|nsidered: 11, and computed = 10                                              |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|nsidered: 15, and computed = 13                                              |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|nsidered: 21, and computed = 18                                              |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|nsidered: 28, and computed = 23                                              |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|nsidered: 37, and computed = 30                                              |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|nsidered: 49, and computed = 36                                              |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|nsidered: 64, and computed = 44                                              |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|nsidered: 84, and computed = 56                                              |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|nsidered: 110, and computed = 69                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|nsidered: 144, and computed = 83                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|nsidered: 188, and computed = 105                                            |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|nsidered: 245, and computed = 135                                            |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|nsidered: 319, and computed = 175                                            |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|nsidered: 328, and computed = 180                                            |
|                                                                             |
|                                                                             |
|uted = 180.  singular locus dimension appears to be = 1                      |
+-----------------------------------------------------------------------------+

The maximum number of minors considered can be controlled by the option
MaxMinors.  Alternatively, it can be controlled in a more precise way by
passing a function to the option MaxMinors.  This function should have two
inputs; the first is minimum number of minors needed to determine whether the
ring is regular in codimension n, and the second is the total number of minors
available in the Jacobian. The function regularInCodimension does not recompute
determinants, so MaxMinors or is only an upper bound on the number of minors
computed.

+-----------------------------------------------------------------------------+
|i17 : time regularInCodimension(2, S, Verbose=>true, MaxMinors=>30)          |
| -- used 1.46831s (cpu); 1.27015s (thread); 0s (gc)                          |
|regularInCodimension: ring dimension =3, there are 17325 possible 4 by 4 mino|
|regularInCodimension: About to enter loop                                    |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing RandomNonZero                                  |
|regularInCodimension:  Loop step, about to compute dimension.  Submatrices co|
|regularInCodimension:  isCodimAtLeast failed, computing codim.               |
|regularInCodimension:  partial singular locus dimension computed, = 2        |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|regularInCodimension:  Loop step, about to compute dimension.  Submatrices co|
|regularInCodimension:  isCodimAtLeast failed, computing codim.               |
|regularInCodimension:  partial singular locus dimension computed, = 2        |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing RandomNonZero                                  |
|regularInCodimension:  Loop step, about to compute dimension.  Submatrices co|
|regularInCodimension:  isCodimAtLeast failed, computing codim.               |
|regularInCodimension:  partial singular locus dimension computed, = 1        |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing RandomNonZero                                  |
|regularInCodimension:  Loop step, about to compute dimension.  Submatrices co|
|regularInCodimension:  isCodimAtLeast failed, computing codim.               |
|regularInCodimension:  partial singular locus dimension computed, = 1        |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|regularInCodimension:  Loop step, about to compute dimension.  Submatrices co|
|regularInCodimension:  isCodimAtLeast failed, computing codim.               |
|regularInCodimension:  partial singular locus dimension computed, = 1        |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|regularInCodimension:  Loop step, about to compute dimension.  Submatrices co|
|regularInCodimension:  isCodimAtLeast failed, computing codim.               |
|regularInCodimension:  partial singular locus dimension computed, = 1        |
|regularInCodimension:  Loop completed, submatrices considered = 30, and compu|
|-----------------------------------------------------------------------------|
|rs, we will compute up to 30 of them.                                        |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|nsidered: 9, and computed = 7                                                |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|nsidered: 11, and computed = 9                                               |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|nsidered: 15, and computed = 11                                              |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|nsidered: 21, and computed = 16                                              |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|nsidered: 28, and computed = 22                                              |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|nsidered: 30, and computed = 23                                              |
|                                                                             |
|                                                                             |
|ted = 23.  singular locus dimension appears to be = 1                        |
+-----------------------------------------------------------------------------+

This function has many options which allow you to fine tune the strategy used
to find interesting minors. You can pass it a HashTable specifying the strategy
via the option Strategy.  See LexSmallest, for how to
construct this HashTable. The default strategy is StrategyDefault, which seems
to work well on the examples we have explored.  However, caution must be
exercised, because, even in the examples above, certain strategies work well
while others do not.  In the Abelian surface example, LexSmallest works very
well, while LexSmallestTerm does not even typically correctly identify the ring
as nonsingular (this is because there are a small number of entries with
nonzero constant terms, which are selected repeatedly). However, in our first
example, the LexSmallestTerm is much faster, and Random does not perform well
at all.

+----------------------------------------------------------------+
|i18 : StrategyCurrent#Random = 0;                               |
+----------------------------------------------------------------+
|i19 : StrategyCurrent#LexSmallest = 100;                        |
+----------------------------------------------------------------+
|i20 : StrategyCurrent#LexSmallestTerm = 0;                      |
+----------------------------------------------------------------+
|i21 : time regularInCodimension(2, R, Strategy=>StrategyCurrent)|
| -- used 0.333234s (cpu); 0.269073s (thread); 0s (gc)           |
|                                                                |
|o21 = true                                                      |
+----------------------------------------------------------------+
|i22 : time regularInCodimension(2, R, Strategy=>StrategyCurrent)|
| -- used 0.126948s (cpu); 0.0970611s (thread); 0s (gc)          |
|                                                                |
|o22 = true                                                      |
+----------------------------------------------------------------+
|i23 : time regularInCodimension(1, S, Strategy=>StrategyCurrent)|
| -- used 0.429106s (cpu); 0.375393s (thread); 0s (gc)           |
|                                                                |
|o23 = true                                                      |
+----------------------------------------------------------------+
|i24 : time regularInCodimension(1, S, Strategy=>StrategyCurrent)|
| -- used 1.8237s (cpu); 1.56299s (thread); 0s (gc)              |
|                                                                |
|o24 = true                                                      |
+----------------------------------------------------------------+
|i25 : StrategyCurrent#LexSmallest = 0;                          |
+----------------------------------------------------------------+
|i26 : StrategyCurrent#LexSmallestTerm = 100;                    |
+----------------------------------------------------------------+
|i27 : time regularInCodimension(2, R, Strategy=>StrategyCurrent)|
| -- used 2.58348s (cpu); 2.1453s (thread); 0s (gc)              |
+----------------------------------------------------------------+
|i28 : time regularInCodimension(2, R, Strategy=>StrategyCurrent)|
| -- used 2.59533s (cpu); 2.15036s (thread); 0s (gc)             |
|                                                                |
|o28 = true                                                      |
+----------------------------------------------------------------+
|i29 : time regularInCodimension(1, S, Strategy=>StrategyCurrent)|
| -- used 0.467372s (cpu); 0.405336s (thread); 0s (gc)           |
|                                                                |
|o29 = true                                                      |
+----------------------------------------------------------------+
|i30 : time regularInCodimension(1, S, Strategy=>StrategyCurrent)|
| -- used 0.805322s (cpu); 0.727554s (thread); 0s (gc)           |
|                                                                |
|o30 = true                                                      |
+----------------------------------------------------------------+
|i31 : time regularInCodimension(1, S, Strategy=>StrategyRandom) |
| -- used 1.14956s (cpu); 1.0205s (thread); 0s (gc)              |
|                                                                |
|o31 = true                                                      |
+----------------------------------------------------------------+
|i32 : time regularInCodimension(1, S, Strategy=>StrategyRandom) |
| -- used 1.8597s (cpu); 1.63908s (thread); 0s (gc)              |
|                                                                |
|o32 = true                                                      |
+----------------------------------------------------------------+

The minimum number of minors computed before checking the codimension can also
be controlled by an option MinMinorsFunction.  This is should be a function of
a single variable, the number of minors computed.  Finally, via the option
CodimCheckFunction, you can pass the regularInCodimension a function which
controls how frequently the codimension of the partial Jacobian ideal is
computed.  By default this is the floor of 1.3^k. Finally, passing the option
Modulus => p will do the computation after changing the coefficient ring to
ZZ/p.

The options PairLimit and SPairsFunction are passed directly to isCodimAtLeast.
You can turn off internal calls to codim/dim, and only use isCodimAtLeast by
setting UseOnlyFastCodim => true.

See also
========

  * isCodimAtLeast -- returns true if we can quickly see
    whether the codim is at least a given number

Ways to use regularInCodimension:
=================================

  * "regularInCodimension(ZZ,Ring)"

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

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

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

The source of this document is in FastMinors.m2:1906:0.

RegularInCodimensionTutorial -- A tutorial for how to use the advanced options of the regularInCodimension function
*******************************************************************************************************************

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

In this tutorial we explore the different options of RegularInCodimension (and
related functions) on some cone singularities.  For the most part we will not
talk about the Strategy option, we have a separate tutorial for that
FastMinorsStrategyTutorial.

We begin with the following ideal.

+-----------------------------------------------------------------------------+
|i1 : S = ZZ/103[x_1..x_9];                                                   |
+-----------------------------------------------------------------------------+
|i2 : J = ideal(x_6*x_8-x_5*x_9,x_3*x_8-x_2*x_9,x_6*x_7-x_4*x_9,x_5*x_7-x_4*x_|
|                                                                             |
|o2 : Ideal of S                                                              |
|-----------------------------------------------------------------------------|
|8,x_3*x_7-x_1*x_9,x_2*x_7-x_1*x_8,x_3*x_5-x_2*x_6,x_3*x_4-x_1*x_6,x_2*x_4-x_1|
|-----------------------------------------------------------------------------|
|*x_5,x_3^3-x_6^3-x_9^3,x_2*x_3^2-x_5*x_6^2-x_8*x_9^2,x_1*x_3^2-x_4*x_6^2-x_7*|
|-----------------------------------------------------------------------------|
|x_9^2,x_2^2*x_3-x_5^2*x_6-x_8^2*x_9,x_1*x_2*x_3-x_4*x_5*x_6-x_7*x_8*x_9,x_1^2|
|-----------------------------------------------------------------------------|
|*x_3-x_4^2*x_6-x_7^2*x_9,x_2^3-x_5^3-x_8^3,x_1*x_2^2-x_4*x_5^2-x_7*x_8^2,x_1^|
|-----------------------------------------------------------------------------|
|2*x_2-x_4^2*x_5-x_7^2*x_8,x_1^3-x_4^3-x_7^3);                                |
+-----------------------------------------------------------------------------+
|i3 : dim (S/J)                                                               |
|                                                                             |
|o3 = 4                                                                       |
+-----------------------------------------------------------------------------+

It is the cone over $P^2 \times E$ where $E$ is an elliptic curve.  We have
embedded it with a Segre embedding inside $P^8$.  In particular, this example
is even regular in codimension 3.

+---------------------------------------------------+
|i4 : time regularInCodimension(1, S/J)             |
| -- used 1.0114s (cpu); 0.833364s (thread); 0s (gc)|
|                                                   |
|o4 = true                                          |
+---------------------------------------------------+
|i5 : time regularInCodimension(2, S/J)             |
| -- used 12.2014s (cpu); 10.3838s (thread); 0s (gc)|
+---------------------------------------------------+

We try to verify that $S/J$ is regular in codimension 1 or 2 by computing the
ideal made up of a small number of minors of the Jacobian matrix. In this
example, instead of computing all relevant 1465128 minors to compute the
singular locus, and then trying to compute the dimension of the ideal they
generate, we instead compute a few of them.  regularInCodimension returns true
if it verified that the ring is regular in codim 1 or 2 (respectively) and null
if not.  Because of the randomness that exists in terms of selecting minors,
the execution time can actually vary quite a bit.   Let's take a look at what
is occurring by using the Verbose option.  We go through the output and explain
what each line is telling us.

+-----------------------------------------------------------------------------+
|i6 : time regularInCodimension(1, S/J, Verbose=>true)                        |
|regularInCodimension: ring dimension =4, there are 1465128 possible 5 by 5 mi|
|regularInCodimension: About to enter loop                                    |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|regularInCodimension:  Loop step, about to compute dimension.  Submatrices co|
|regularInCodimension:  isCodimAtLeast failed, computing codim.               |
|regularInCodimension:  partial singular locus dimension computed, = 3        |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|regularInCodimension:  Loop step, about to compute dimension.  Submatrices co|
|regularInCodimension:  isCodimAtLeast failed, computing codim.               |
|regularInCodimension:  partial singular locus dimension computed, = 3        |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|regularInCodimension:  Loop step, about to compute dimension.  Submatrices co|
|regularInCodimension:  isCodimAtLeast failed, computing codim.               |
|regularInCodimension:  partial singular locus dimension computed, = 3        |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing Random                                         |
|regularInCodimension:  Loop step, about to compute dimension.  Submatrices co|
|regularInCodimension:  isCodimAtLeast failed, computing codim.               |
|regularInCodimension:  partial singular locus dimension computed, = 3        |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|regularInCodimension:  Loop step, about to compute dimension.  Submatrices co|
|regularInCodimension:  isCodimAtLeast failed, computing codim.               |
|regularInCodimension:  partial singular locus dimension computed, = 3        |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|regularInCodimension:  Loop step, about to compute dimension.  Submatrices co|
|regularInCodimension:  isCodimAtLeast failed, computing codim.               |
|regularInCodimension:  partial singular locus dimension computed, = 3        |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing Random                                         |
|regularInCodimension:  Loop step, about to compute dimension.  Submatrices co|
|regularInCodimension:  singularLocus dimension verified by isCodimAtLeast    |
|regularInCodimension:  partial singular locus dimension computed, = 2        |
|regularInCodimension:  Loop completed, submatrices considered = 49, and compu|
|d = 39.  singular locus dimension appears to be = 2                          |
|                                                                             |
|o6 = true                                                                    |
|-----------------------------------------------------------------------------|
|nors, we will compute up to 452.908 of them.                                 |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|nsidered: 7, and computed = 7                                                |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|nsidered: 11, and computed = 10                                              |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|nsidered: 15, and computed = 13                                              |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|nsidered: 21, and computed = 18                                              |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|nsidered: 28, and computed = 24                                              |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|nsidered: 37, and computed = 30                                              |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|nsidered: 49, and computed = 39                                              |
|                                                                             |
|                                                                             |
|te -- used 1.57255s (cpu); 1.29769s (thread); 0s (gc)                        |
+-----------------------------------------------------------------------------+

MaxMinors.  The first output says that we will compute up to 452.9 minors
before giving up.  We can control that by setting the option MaxMinors.

+-----------------------------------------------------------------------------+
|i7 : time regularInCodimension(1, S/J, MaxMinors=>10, Verbose=>true)         |
| -- used 0.203984s (cpu); 0.167819s (thread); 0s (gc)                        |
|regularInCodimension: ring dimension =4, there are 1465128 possible 5 by 5 mi|
|regularInCodimension: About to enter loop                                    |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|regularInCodimension:  Loop step, about to compute dimension.  Submatrices co|
|regularInCodimension:  isCodimAtLeast failed, computing codim.               |
|regularInCodimension:  partial singular locus dimension computed, = 3        |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing LexSmallest                                    |
|regularInCodimension:  Loop step, about to compute dimension.  Submatrices co|
|regularInCodimension:  isCodimAtLeast failed, computing codim.               |
|regularInCodimension:  partial singular locus dimension computed, = 3        |
|regularInCodimension:  Loop completed, submatrices considered = 10, and compu|
|-----------------------------------------------------------------------------|
|nors, we will compute up to 10 of them.                                      |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|nsidered: 7, and computed = 7                                                |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|nsidered: 10, and computed = 10                                              |
|                                                                             |
|                                                                             |
|ted = 10.  singular locus dimension appears to be = 3                        |
+-----------------------------------------------------------------------------+

There are other finer ways to control the MaxMinors option, but they will not
be discussed in this tutorial.  See regularInCodimension.

Selecting submatrices of the Jacobian.  We also see output like: ``Choosing
LexSmallest'' or ``Choosing Random''.  This is saying how we are selecting a
given submatrix.  For instance, we can run:

+-----------------------------------------------------------------------------+
|i8 : time regularInCodimension(1, S/J, MaxMinors=>10, Strategy=>StrategyRando|
| -- used 0.173228s (cpu); 0.136577s (thread); 0s (gc)                        |
|regularInCodimension: ring dimension =4, there are 1465128 possible 5 by 5 mi|
|regularInCodimension: About to enter loop                                    |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing Random                                         |
|regularInCodimension:  Loop step, about to compute dimension.  Submatrices co|
|regularInCodimension:  isCodimAtLeast failed, computing codim.               |
|regularInCodimension:  partial singular locus dimension computed, = 3        |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing Random                                         |
|regularInCodimension:  Loop step, about to compute dimension.  Submatrices co|
|regularInCodimension:  isCodimAtLeast failed, computing codim.               |
|regularInCodimension:  partial singular locus dimension computed, = 3        |
|regularInCodimension:  Loop completed, submatrices considered = 10, and compu|
|-----------------------------------------------------------------------------|
|m, Verbose=>true)                                                            |
|                                                                             |
|nors, we will compute up to 10 of them.                                      |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|nsidered: 7, and computed = 7                                                |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|nsidered: 10, and computed = 10                                              |
|                                                                             |
|                                                                             |
|ted = 10.  singular locus dimension appears to be = 3                        |
+-----------------------------------------------------------------------------+

and only random submatrices are chosen.  We discuss strategies for choosing
submatrices much more generally in the FastMinorsStrategyTutorial.
Regardless, after a certain number of minors have
been looked at, we see output lines like:  ``Loop step, about to compute
dimension.  Submatrices considered: 7, and computed = 7''.  We only compute
minors we haven't considered before.  So as we compute more minors, there can
be a distinction between considered and computed.

Computing minors vs considering the dimension of what has been computed.
Periodically we compute the codimension of the partial ideal of minors we have
computed so far.  There are two options to control this.  First, we can tell
the function when to first compute the dimension of the working partial ideal
of minors.

+-----------------------------------------------------------------------------+
|i9 : time regularInCodimension(1, S/J, MaxMinors=>10, MinMinorsFunction => t-|
| -- used 0.696107s (cpu); 0.592386s (thread); 0s (gc)                        |
|regularInCodimension: ring dimension =4, there are 1465128 possible 5 by 5 mi|
|regularInCodimension: About to enter loop                                    |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing Random                                         |
|internalChooseMinor: Choosing LexSmallest                                    |
|regularInCodimension:  Loop step, about to compute dimension.  Submatrices co|
|regularInCodimension:  isCodimAtLeast failed, computing codim.               |
|regularInCodimension:  partial singular locus dimension computed, = 3        |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|regularInCodimension:  Loop step, about to compute dimension.  Submatrices co|
|regularInCodimension:  isCodimAtLeast failed, computing codim.               |
|regularInCodimension:  partial singular locus dimension computed, = 3        |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|regularInCodimension:  Loop step, about to compute dimension.  Submatrices co|
|regularInCodimension:  isCodimAtLeast failed, computing codim.               |
|regularInCodimension:  partial singular locus dimension computed, = 3        |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|regularInCodimension:  Loop step, about to compute dimension.  Submatrices co|
|regularInCodimension:  isCodimAtLeast failed, computing codim.               |
|regularInCodimension:  partial singular locus dimension computed, = 3        |
|regularInCodimension:  Loop completed, submatrices considered = 10, and compu|
|-----------------------------------------------------------------------------|
|>3, Verbose=>true)                                                           |
|                                                                             |
|nors, we will compute up to 10 of them.                                      |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|nsidered: 3, and computed = 3                                                |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|nsidered: 6, and computed = 6                                                |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|nsidered: 8, and computed = 8                                                |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|nsidered: 10, and computed = 10                                              |
|                                                                             |
|                                                                             |
|ted = 10.  singular locus dimension appears to be = 3                        |
+-----------------------------------------------------------------------------+

MinMinorsFunction. We pass MinMinorsFunction a function which sends the minimum
number of minors needed to verify that something is regular in codimension $n$
(which is always $n+1$) to the number of minors to compute before computing the
dimension of the partial ideal of minors for the first time.   You can see that
three minors were computed in the above example before we attempt to compute
codimension.

CodimCheckFunction. The option CodimCheckFunction controls how frequently the
dimension of the partial ideal of minors is computed.  For instance, setting
CodimCheckFunction => t -> t/5 will say it should compute dimension after every
5 minors are examined.  In general, after the output of the CodimCheckFunction
increases by an integer we compute the codimension again.  The default function
has the space between computations grow exponentially.

+-----------------------------------------------------------------------------+
|i10 : time regularInCodimension(1, S/J, MaxMinors=>25, CodimCheckFunction => |
| -- used 0.787366s (cpu); 0.652169s (thread); 0s (gc)                        |
|regularInCodimension: ring dimension =4, there are 1465128 possible 5 by 5 mi|
|regularInCodimension: About to enter loop                                    |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|regularInCodimension:  Loop step, about to compute dimension.  Submatrices co|
|regularInCodimension:  isCodimAtLeast failed, computing codim.               |
|regularInCodimension:  partial singular locus dimension computed, = 4        |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing Random                                         |
|regularInCodimension:  Loop step, about to compute dimension.  Submatrices co|
|regularInCodimension:  isCodimAtLeast failed, computing codim.               |
|regularInCodimension:  partial singular locus dimension computed, = 4        |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|regularInCodimension:  Loop step, about to compute dimension.  Submatrices co|
|regularInCodimension:  isCodimAtLeast failed, computing codim.               |
|regularInCodimension:  partial singular locus dimension computed, = 4        |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing RandomNonZero                                  |
|regularInCodimension:  Loop step, about to compute dimension.  Submatrices co|
|regularInCodimension:  isCodimAtLeast failed, computing codim.               |
|regularInCodimension:  partial singular locus dimension computed, = 3        |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|regularInCodimension:  Loop step, about to compute dimension.  Submatrices co|
|regularInCodimension:  isCodimAtLeast failed, computing codim.               |
|regularInCodimension:  partial singular locus dimension computed, = 3        |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|regularInCodimension:  Loop step, about to compute dimension.  Submatrices co|
|regularInCodimension:  isCodimAtLeast failed, computing codim.               |
|regularInCodimension:  partial singular locus dimension computed, = 3        |
|regularInCodimension:  Loop completed, submatrices considered = 25, and compu|
|-----------------------------------------------------------------------------|
|t->t/5, MinMinorsFunction => t->2, Verbose=>true)                            |
|                                                                             |
|nors, we will compute up to 25 of them.                                      |
|                                                                             |
|                                                                             |
|                                                                             |
|nsidered: 2, and computed = 2                                                |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|nsidered: 5, and computed = 5                                                |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|nsidered: 10, and computed = 10                                              |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|nsidered: 15, and computed = 15                                              |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|nsidered: 20, and computed = 18                                              |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|nsidered: 25, and computed = 23                                              |
|                                                                             |
|                                                                             |
|ted = 23.  singular locus dimension appears to be = 3                        |
+-----------------------------------------------------------------------------+

isCodimAtLeast and dim.  We see the lines about the ``isCodimAtLeast failed''.
This means that isCodimAtLeast was not enough on its own to verify that our
ring is regular in codimension 1.  After this, ``partial singular locus
dimension computed'' indicates we did a complete dimension computation of the
partial ideal defining the singular locus.  How isCodimAtLeast is called can be
controlled via the options SPairsFunction and PairLimit, which are simply
passed to isCodimAtLeast.  You can force the function to
only use isCodimAtLeast and not call dimension by setting UseOnlyFastCodim =>
true.

+-----------------------------------------------------------------------------+
|i11 : time regularInCodimension(1, S/J, MaxMinors=>25, UseOnlyFastCodim => tr|
| -- used 0.507504s (cpu); 0.39997s (thread); 0s (gc)                         |
|regularInCodimension: ring dimension =4, there are 1465128 possible 5 by 5 mi|
|regularInCodimension: About to enter loop                                    |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing RandomNonZero                                  |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing Random                                         |
|regularInCodimension:  Loop step, about to compute dimension.  Submatrices co|
|regularInCodimension:  partial singular locus dimension computed, = 4        |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|internalChooseMinor: Choosing GRevLexSmallest                                |
|regularInCodimension:  Loop step, about to compute dimension.  Submatrices co|
|regularInCodimension:  partial singular locus dimension computed, = 4        |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|internalChooseMinor: Choosing LexSmallest                                    |
|internalChooseMinor: Choosing GRevLexSmallestTerm                            |
|internalChooseMinor: Choosing LexSmallestTerm                                |
|regularInCodimension:  Loop step, about to compute dimension.  Submatrices co|
|regularInCodimension:  singularLocus dimension verified by isCodimAtLeast    |
|regularInCodimension:  partial singular locus dimension computed, = 2        |
|regularInCodimension:  Loop completed, submatrices considered = 15, and compu|
|                                                                             |
|o11 = true                                                                   |
|-----------------------------------------------------------------------------|
|ue, Verbose=>true)                                                           |
|                                                                             |
|nors, we will compute up to 25 of them.                                      |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|nsidered: 7, and computed = 7                                                |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|nsidered: 11, and computed = 10                                              |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|nsidered: 15, and computed = 13                                              |
|                                                                             |
|                                                                             |
|ted = 13.  singular locus dimension appears to be = 2                        |
+-----------------------------------------------------------------------------+

This can be useful if the function is hanging when trying to compute the
dimension, but you may wish increase PairLimit.

Summary.  If you expect that finding a submatrix or computing a minor is
relatively costly from a time perspective, then it makes sense to compute the
codimension more frequently.  If computing the codimension is relatively costly
we recommend computing the codimension less frequently, or using the
UseOnlyFastCodim => true with a high PairLimit.  For example, if using
StrategyPoints, then choosing a submatrix can be quite slow, however each
submatrix is very ``valuable'', in that adding it to the ideal of minors so far
is quite likely to reduce the dimension of the singular locus.

One may also change how minors (determinants of the Jacobian submatrix) are
computed by using the DetStrategy, option.

See also
========

  * regularInCodimension -- attempts to show that
    the ring is regular in codimension n
  * FastMinorsStrategyTutorial -- How to use
    and construct strategies for selecting submatrices in various functions
  * DetStrategy -- DetStrategy is a strategy for allowing
    the user to choose how determinants (or rank), is computed

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

The object RegularInCodimensionTutorial, is
a symbol (Macaulay2Doc).

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

The source of this document is in FastMinors.m2:1588:0.

reorderPolynomialRing -- produces an isomorphic polynomial ring with a different, randomized, monomial order
************************************************************************************************************

  * Usage:
        R1 = reorderPolynomialRing(orderType, R)
  * Inputs:
      * R, a ring (Macaulay2Doc), a polynomial ring
      * orderType, a symbol (Macaulay2Doc), a valid monomial
        order, such as GRevLex
  * Outputs:
      * S, a ring (Macaulay2Doc), a polynomial ring with a new
        random monomial order

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

This function takes a polynomial ring and produces a new polynomial ring with
MonomialOrder of type orderType. The order of the variables is randomized.

+------------------------------------------+
|i1 : R = QQ[x,y,z,w];                     |
+------------------------------------------+
|i2 : x > y and y > z and z > w            |
|                                          |
|o2 = true                                 |
+------------------------------------------+
|i3 : use reorderPolynomialRing(GRevLex, R)|
|                                          |
|o3 = QQ[z, w..y]                          |
|                                          |
|o3 : PolynomialRing                       |
+------------------------------------------+
|i4 : x > y                                |
|                                          |
|o4 = true                                 |
+------------------------------------------+
|i5 : y > z                                |
|                                          |
|o5 = false                                |
+------------------------------------------+
|i6 : z > w                                |
|                                          |
|o6 = true                                 |
+------------------------------------------+

Ways to use reorderPolynomialRing:
==================================

  * "reorderPolynomialRing(Symbol,Ring)"

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

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

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

The source of this document is in FastMinors.m2:2168:0.

StrategyDefault -- strategies for choosing submatrices
******************************************************

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

Many of the core functions of this package allow the user to fine tune the
strategy used for selecting submatrices.  Different strategies yield markedly
different performance or results on various examples. These are controlled by
specifying a  Strategy =>  option, pointing to a  HashTablewhich specifies
several strategies should be used simultaneously, or to a symbol saying we
should use only a single strategy.  For a more detailed look at this in an
example please see FastMinorsStrategyTutorial,
Before describing the available strategies, we begin
by roughly outlining the different approaches.
  * Heuristic submatrix selection: In this case, a submatrix is chosen via a
    greedy algorithm, looking for a submatrix with smallest (or largest) degree
    with respect to a random monomial order.
  * Submatrix selection via rational and geometric points: Here a rational or
    geometric point is found where a given ideal vanishes.  That point is
    plugged into the matrix and a submatrix of full rank is identified.   This
    approach currently only works over a finite field and is accomplished with
    the help of the package RandomPoints.
  * Random submatrix selection: This either chooses a completely random
    submatrix, or a submatrix which has no zero columns or rows.
There we highlight five pre-programmed strategies provided to the user.
  * StrategyDefault: this uses a mix of heuristics and random submatrices.
  * StrategyRandom: this uses purely random submatrices.
  * StrategyDefaultNonRandom: this uses a mix of heuristics but no random
    submatrices.
  * StrategyPoints: this only uses rational / geometric points to find
    submatrices.
  * StrategyDefaultWithPoints: this uses a mix of heuristics and submatrices
    chosen with rational and geometric points.
Below the details of how these strategies are constructed will be detailed
below.  But first, we provide an example showing that these strategies can
perform quite differently.  The following is the cone over the product of two
elliptic curves.  We verify that this ring is regular in codimension 1 using
different strategies.  Essentially, minors are computed until it is verified
that the ring is regular in codimension 1.
+-----------------------------------------------------------------------------+
|i1 : T=ZZ/7[a..i]/ideal(f*h-e*i,c*h-b*i,f*g-d*i,e*g-d*h,c*g-a*i,b*g-a*h,c*e-b|
|-----------------------------------------------------------------------------|
|*f,c*d-a*f,b*d-a*e,g^3-h^2*i-g*i^2,d*g^2-e*h*i-d*i^2,a*g^2-b*h*i-a*i^2,d^2*g-|
|-----------------------------------------------------------------------------|
|e^2*i-d*f*i,a*d*g-b*e*i-a*f*i,a^2*g-b^2*i-a*c*i,d^3-e^2*f-d*f^2,a*d^2-b*e*f-a|
|-----------------------------------------------------------------------------|
|*f^2,a^2*d-b^2*f-a*c*f,c^3+f^3-i^3,b*c^2+e*f^2-h*i^2,a*c^2+d*f^2-g*i^2,b^2*c+|
|-----------------------------------------------------------------------------|
|e^2*f-h^2*i,a*b*c+d*e*f-g*h*i,a^2*c+d^2*f-g^2*i,b^3+e^3-h^3,a*b^2+d*e^2-g*h^2|
|-----------------------------------------------------------------------------|
|,a^2*b+d^2*e-g^2*h,a^3+e^2*f+d*f^2-h^2*i-g*i^2);                             |
+-----------------------------------------------------------------------------+
|i2 : elapsedTime regularInCodimension(1, T, Strategy=>StrategyDefault)       |
| -- 1.99243s elapsed                                                         |
|                                                                             |
|o2 = true                                                                    |
+-----------------------------------------------------------------------------+
In this particular example, on one machine, we list average time to completion
of each of the above strategies after 100 runs.
  * StrategyDefault: 1.65 seconds
  * StrategyRandom: 8.32 seconds
  * StrategyDefaultNonRandom: 0.99 seconds
  * StrategyPoints: 3.27 seconds
  * StrategyDefaultWithPoints: 3.37
Roughly speaking, heuristics tend to provide more information than random
submatrices and so they work much faster since they consider far fewer
submatrices.  Frequently also, computing random or rational points does have
advantages as typically fewer still minors are needed (hence if computing
minors is slow StrategyPoints is a good choice).  However, sometimes that
non-trivial point computation will become stuck (in the above example, the
median time for StrategyPoints and StrategyDefaultWithPoints was close to 1.5
seconds, but a couple runs in each case were orders of magnitude slower).

Custom Strategies
The user can create their own strategies as well, as we now explain.  In
particular, the user can even customize the heuristics used.  See below for how
to easily use only a single heuristic. To custom strategy is specified by a
HashTable which must have the following keys.
  * GRevLexLargest: try to find submatrices where each row and column has a
    large entry with respect to a random GRevLexorder.
  * GRevLexSmallest: try to find submatrices where each row and column has a
    small entry with respect to a random GRevLexorder.
  * GRevLexSmallestTerm: find submatrices where each row and column has an
    entry with a small term with respect to a random GRevLexorder.
  * LexLargest: try to find submatrices where each row and column has a large
    entry with respect to a random Lexorder.
  * LexSmallest: try to find submatrices where each row and column has a small
    entry with respect to a random Lexorder.
  * LexSmallestTerm: find submatrices where each row and column has an entry
    with a small term with respect to a random Lexorder.
  * Random: find random submatrices
  * RandomNonzero: find random submatrices that have nonzero rows and columns
  * Points: find submatrices that are not singular at the given ideal by
    finding a point where that ideal vanishes, and evaluating the matrix at
    that point (via the package RandomPoints).  If
    working over a characteristic zero field, this will select random
    submatrices.  To access options for that package, set the
    PointOptions, option.
For example:
+-------------------------------------------+
|i3 : peek StrategyDefault                  |
|                                           |
|o3 = OptionTable{GRevLexLargest => 0      }|
|                 GRevLexSmallest => 16     |
|                 GRevLexSmallestTerm => 16 |
|                 LexLargest => 0           |
|                 LexSmallest => 16         |
|                 LexSmallestTerm => 16     |
|                 Points => 0               |
|                 Random => 16              |
|                 RandomNonzero => 16       |
+-------------------------------------------+
Each such key should point to an integer.  The larger the integer, the more
likely that such a minor will be chosen.

Functions such as chooseGoodMinors, will select a
number of random submatrices based on the values of those keys.  For example,
if LexSmallest and LexLargest are set to 50 approximately the submatrics will
be smallest with respect to Lex and the other half will be largest with respect
to Lex.The values do not need to add up to 100.

The heuristic functions all work by finding the optimal entry with respect to
the given strategy, removing that row and column, and then choosing the next
optimal entry.  This is done until a submatrix of the desired size has been
found.

In some functions, the GRevLex versions of this strategy will modify the
working matrix in a loop, repeatedly lowering/raising the degree of elementsso
as to ensure that different choices are made.

We briefly summarize the Strategies provided to the user by default (some of
which we have seen in action above)
  * StrategyDefault: 16% of the matrices are LexSmallest, LexSmallestTerm,
    GRevLexSmallest, GRevLexLargest, Random, and RandomNonZero each
  * StrategyDefaultNonRandom: 25% of the matrices are LexSmallest,
    LexSmallestTerm, GRevLexSmallest and, GRevLexLargest each
  * StrategyLexSmallest: 50% of the matrices are LexSmallest and 50% are
    LexSmallestTerm
  * StrategyGRevLexSmallest: 50% of the matrices are GRevLexSmallest and 50%
    are GRevLexLargest
  * StrategyRandom: chooses 100% random submatrices.
  * StrategyPoints: choose all submatrices via Points.
  * StrategyDefaultWithPoints: like StrategyDefault but replaces the Random and
    RandomNonZero submatrices as with matrices chosen as in Points.
Additionally, a MutableHashTable named StrategyCurrent is also exported.  It
begins as the default strategy, but the user can modify it.

Using a single heuristic  Alternatively, if the user only wants to use say
LexSmallestTerm they can set, Strategy to point to that symbol, instead of a
creating a custom strategy HashTable.  For example:
+----------------------------------------------------------------------+
|i4 : elapsedTime regularInCodimension(1, T, Strategy=>LexSmallestTerm)|
| -- 1.16306s elapsed                                                  |
|                                                                      |
|o4 = true                                                             |
+----------------------------------------------------------------------+

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

The object StrategyDefault, is an option table (Macaulay2Doc).

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

The source of this document is in FastMinors.m2:1993:0.