# 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_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); o2 : Ideal of S 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.081 seconds o4 = true i5 : time regularInCodimension(2, S/J) -- used 11.9281 seconds

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 the the ring with 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 minors, we will compute up to 452.908 of them. regularInCodimension: About to enter loop internalChooseMinor: Choosing GRevLexSmallestTerm internalChooseMinor: Choosing LexSmallestTerm internalChooseMinor: Choosing LexSmallestTerm internalChooseMinor: Choosing GRevLexSmallestTerm internalChooseMinor: Choosing LexSmallestTerm internalChooseMinor: Choosing RandomNonZero internalChooseMinor: Choosing Random regularInCodimension: Loop step, about to compute dimension. Submatrices considered: 7, and computed = 6 regularInCodimension: isCodimAtLeast failed, computing codim. regularInCodimension: partial singular locus dimension computed, = 3 internalChooseMinor: Choosing Random internalChooseMinor: Choosing LexSmallest internalChooseMinor: Choosing LexSmallestTerm internalChooseMinor: Choosing LexSmallest regularInCodimension: Loop step, about to compute dimension. Submatrices considered: 11, and computed = 9 regularInCodimension: isCodimAtLeast failed, computing codim. regularInCodimension: partial singular locus dimension computed, = 3 internalChooseMinor: Choosing LexSmallestTerm internalChooseMinor: Choosing RandomNonZero internalChooseMinor: Choosing Random internalChooseMinor: Choosing GRevLexSmallest regularInCodimension: Loop step, about to compute dimension. Submatrices considered: 15, and computed = 12 regularInCodimension: isCodimAtLeast failed, computing codim. regularInCodimension: partial singular locus dimension computed, = 3 internalChooseMinor: Choosing Random internalChooseMinor: Choosing Random internalChooseMinor: Choosing LexSmallestTerm internalChooseMinor: Choosing LexSmallest internalChooseMinor: Choosing RandomNonZero internalChooseMinor: Choosing GRevLexSmallest regularInCodimension: Loop step, about to compute dimension. Submatrices considered: 21, and computed = 17 regularInCodimension: isCodimAtLeast failed, computing codim. regularInCodimension: partial singular locus dimension computed, = 3 internalChooseMinor: Choosing RandomNonZero internalChooseMinor: Choosing GRevLexSmallestTerm internalChooseMinor: Choosing Random internalChooseMinor: Choosing RandomNonZero internalChooseMinor: Choosing LexSmallestTerm internalChooseMinor: Choosing Random internalChooseMinor: Choosing LexSmallestTerm regularInCodimension: Loop step, about to compute dimension. Submatrices considered: 28, and computed = 23 regularInCodimension: isCodimAtLeast failed, computing codim. regularInCodimension: partial singular locus dimension computed, = 3 internalChooseMinor: Choosing LexSmallestTerm internalChooseMinor: Choosing GRevLexSmallestTerm internalChooseMinor: Choosing LexSmallest internalChooseMinor: Choosing RandomNonZero internalChooseMinor: Choosing LexSmallest internalChooseMinor: Choosing RandomNonZero internalChooseMinor: Choosing GRevLexSmallestTerm internalChooseMinor: Choosing LexSmallestTerm internalChooseMinor: Choosing Random regularInCodimension: Loop step, about to compute dimension. Submatrices considered: 37, and computed = 29 regularInCodimension: isCodimAtLeast failed, computing codim. regularInCodimension: partial singular locus dimension computed, = 3 internalChooseMinor: Choosing RandomNonZero internalChooseMinor: Choosing LexSmallestTerm internalChooseMinor: Choosing GRevLexSmallestTerm internalChooseMinor: Choosing GRevLexSmallestTerm internalChooseMinor: Choosing RandomNonZero internalChooseMinor: Choosing RandomNonZero internalChooseMinor: Choosing RandomNonZero internalChooseMinor: Choosing RandomNonZero internalChooseMinor: Choosing LexSmallestTerm internalChooseMinor: Choosing RandomNonZero internalChooseMinor: Choosing Random internalChooseMinor: Choosing LexSmallestTerm regularInCodimension: Loop step, about to compute dimension. Submatrices considered: 49, and computed = 39 regularInCodimension: isCodimAtLeast failed, computing codim. regularInCodimension: partial singular locus dimension computed, = 3 internalChooseMinor: Choosing Random internalChooseMinor: Choosing Random internalChooseMinor: Choosing GRevLexSmallest internalChooseMinor: Choosing GRevLexSmallest internalChooseMinor: Choosing LexSmallestTerm internalChooseMinor: Choosing LexSmallestTerm internalChooseMinor: Choosing LexSmallestTerm internalChooseMinor: Choosing RandomNonZero internalChooseMinor: Choosing GRevLexSmallest internalChooseMinor: Choosing RandomNonZero internalChooseMinor: Choosing RandomNonZero internalChooseMinor: Choosing GRevLexSmallest internalChooseMinor: Choosing GRevLexSmallest internalChooseMinor: Choosing GRevLexSmallestTerm internalChooseMinor: Choosing LexSmallestTerm regularInCodimension: Loop step, about to compute dimension. Submatrices considered: 64, and computed = 50 regularInCodimension: singularLocus dimension verified by isCodimAtLeast regularInCodimension: partial singular locus dimension computed, = 2 regularInCodimension: Loop completed, submatrices considered = 64, and computed = 50. singular locus dimension appears to be = 2 -- used 2.01323 seconds o6 = true

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) regularInCodimension: ring dimension =4, there are 1465128 possible 5 by 5 minors, we will compute up to 10 of them. regularInCodimension: About to enter loop internalChooseMinor: Choosing LexSmallestTerm internalChooseMinor: Choosing Random internalChooseMinor: Choosing LexSmallest internalChooseMinor: Choosing LexSmallest internalChooseMinor: Choosing Random internalChooseMinor: Choosing RandomNonZero internalChooseMinor: Choosing RandomNonZero regularInCodimension: Loop step, about to compute dimension. Submatrices considered: 7, and computed = 7 regularInCodimension: isCodimAtLeast failed, computing codim. regularInCodimension: partial singular locus dimension computed, = 3 internalChooseMinor: Choosing Random internalChooseMinor: Choosing LexSmallest internalChooseMinor: Choosing RandomNonZero regularInCodimension: Loop step, about to compute dimension. Submatrices considered: 10, and computed = 10 regularInCodimension: isCodimAtLeast failed, computing codim. regularInCodimension: partial singular locus dimension computed, = 3 regularInCodimension: Loop completed, submatrices considered = 10, and computed = 10. singular locus dimension appears to be = 3 -- used 0.417555 seconds

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=>StrategyRandom, Verbose=>true) regularInCodimension: ring dimension =4, there are 1465128 possible 5 by 5 minors, we will compute up to 10 of them. 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 considered: 7, and computed = 7 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 considered: 10, and computed = 10 regularInCodimension: isCodimAtLeast failed, computing codim. regularInCodimension: partial singular locus dimension computed, = 3 regularInCodimension: Loop completed, submatrices considered = 10, and computed = 10. singular locus dimension appears to be = 3 -- used 0.161845 seconds

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->3, Verbose=>true) regularInCodimension: ring dimension =4, there are 1465128 possible 5 by 5 minors, we will compute up to 10 of them. regularInCodimension: About to enter loop internalChooseMinor: Choosing LexSmallestTerm internalChooseMinor: Choosing Random internalChooseMinor: Choosing LexSmallest regularInCodimension: Loop step, about to compute dimension. Submatrices considered: 3, and computed = 3 regularInCodimension: isCodimAtLeast failed, computing codim. regularInCodimension: partial singular locus dimension computed, = 3 internalChooseMinor: Choosing LexSmallestTerm internalChooseMinor: Choosing RandomNonZero internalChooseMinor: Choosing GRevLexSmallestTerm regularInCodimension: Loop step, about to compute dimension. Submatrices considered: 6, and computed = 6 regularInCodimension: isCodimAtLeast failed, computing codim. regularInCodimension: partial singular locus dimension computed, = 3 internalChooseMinor: Choosing GRevLexSmallest internalChooseMinor: Choosing LexSmallestTerm regularInCodimension: Loop step, about to compute dimension. Submatrices considered: 8, and computed = 8 regularInCodimension: isCodimAtLeast failed, computing codim. regularInCodimension: partial singular locus dimension computed, = 3 internalChooseMinor: Choosing GRevLexSmallest internalChooseMinor: Choosing LexSmallestTerm regularInCodimension: Loop step, about to compute dimension. Submatrices considered: 10, and computed = 10 regularInCodimension: isCodimAtLeast failed, computing codim. regularInCodimension: partial singular locus dimension computed, = 3 regularInCodimension: Loop completed, submatrices considered = 10, and computed = 10. singular locus dimension appears to be = 3 -- used 0.334279 seconds

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 => t->t/5, MinMinorsFunction => t->2, Verbose=>true) regularInCodimension: ring dimension =4, there are 1465128 possible 5 by 5 minors, we will compute up to 25 of them. regularInCodimension: About to enter loop internalChooseMinor: Choosing LexSmallestTerm internalChooseMinor: Choosing Random regularInCodimension: Loop step, about to compute dimension. Submatrices considered: 2, and computed = 2 regularInCodimension: isCodimAtLeast failed, computing codim. regularInCodimension: partial singular locus dimension computed, = 3 internalChooseMinor: Choosing Random internalChooseMinor: Choosing GRevLexSmallestTerm internalChooseMinor: Choosing Random regularInCodimension: Loop step, about to compute dimension. Submatrices considered: 5, and computed = 5 regularInCodimension: isCodimAtLeast failed, computing codim. regularInCodimension: partial singular locus dimension computed, = 3 internalChooseMinor: Choosing GRevLexSmallest internalChooseMinor: Choosing GRevLexSmallest internalChooseMinor: Choosing LexSmallestTerm internalChooseMinor: Choosing GRevLexSmallest internalChooseMinor: Choosing GRevLexSmallest regularInCodimension: Loop step, about to compute dimension. Submatrices considered: 10, and computed = 10 regularInCodimension: isCodimAtLeast failed, computing codim. regularInCodimension: partial singular locus dimension computed, = 3 internalChooseMinor: Choosing LexSmallest internalChooseMinor: Choosing RandomNonZero internalChooseMinor: Choosing LexSmallestTerm internalChooseMinor: Choosing Random internalChooseMinor: Choosing Random regularInCodimension: Loop step, about to compute dimension. Submatrices considered: 15, and computed = 14 regularInCodimension: isCodimAtLeast failed, computing codim. regularInCodimension: partial singular locus dimension computed, = 3 internalChooseMinor: Choosing RandomNonZero internalChooseMinor: Choosing GRevLexSmallestTerm internalChooseMinor: Choosing LexSmallestTerm internalChooseMinor: Choosing GRevLexSmallestTerm internalChooseMinor: Choosing GRevLexSmallestTerm regularInCodimension: Loop step, about to compute dimension. Submatrices considered: 20, and computed = 19 regularInCodimension: isCodimAtLeast failed, computing codim. regularInCodimension: partial singular locus dimension computed, = 3 internalChooseMinor: Choosing LexSmallest internalChooseMinor: Choosing LexSmallest internalChooseMinor: Choosing GRevLexSmallestTerm internalChooseMinor: Choosing Random internalChooseMinor: Choosing RandomNonZero regularInCodimension: Loop step, about to compute dimension. Submatrices considered: 25, and computed = 23 regularInCodimension: isCodimAtLeast failed, computing codim. regularInCodimension: partial singular locus dimension computed, = 3 regularInCodimension: Loop completed, submatrices considered = 25, and computed = 23. singular locus dimension appears to be = 3 -- used 0.798307 seconds

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 => true, Verbose=>true) regularInCodimension: ring dimension =4, there are 1465128 possible 5 by 5 minors, we will compute up to 25 of them. regularInCodimension: About to enter loop internalChooseMinor: Choosing Random internalChooseMinor: Choosing LexSmallestTerm internalChooseMinor: Choosing Random internalChooseMinor: Choosing RandomNonZero internalChooseMinor: Choosing GRevLexSmallest internalChooseMinor: Choosing GRevLexSmallestTerm internalChooseMinor: Choosing GRevLexSmallest regularInCodimension: Loop step, about to compute dimension. Submatrices considered: 7, and computed = 7 regularInCodimension: partial singular locus dimension computed, = 4 internalChooseMinor: Choosing GRevLexSmallest internalChooseMinor: Choosing GRevLexSmallestTerm internalChooseMinor: Choosing Random internalChooseMinor: Choosing RandomNonZero regularInCodimension: Loop step, about to compute dimension. Submatrices considered: 11, and computed = 11 regularInCodimension: partial singular locus dimension computed, = 4 internalChooseMinor: Choosing GRevLexSmallestTerm internalChooseMinor: Choosing Random internalChooseMinor: Choosing LexSmallestTerm internalChooseMinor: Choosing LexSmallest regularInCodimension: Loop step, about to compute dimension. Submatrices considered: 15, and computed = 15 regularInCodimension: partial singular locus dimension computed, = 4 internalChooseMinor: Choosing GRevLexSmallestTerm internalChooseMinor: Choosing LexSmallest internalChooseMinor: Choosing RandomNonZero internalChooseMinor: Choosing Random internalChooseMinor: Choosing LexSmallestTerm internalChooseMinor: Choosing Random regularInCodimension: Loop step, about to compute dimension. Submatrices considered: 21, and computed = 21 regularInCodimension: partial singular locus dimension computed, = 4 internalChooseMinor: Choosing LexSmallestTerm internalChooseMinor: Choosing LexSmallestTerm internalChooseMinor: Choosing Random internalChooseMinor: Choosing LexSmallestTerm regularInCodimension: Loop step, about to compute dimension. Submatrices considered: 25, and computed = 24 regularInCodimension: partial singular locus dimension computed, = 4 regularInCodimension: Loop completed, submatrices considered = 25, and computed = 24. singular locus dimension appears to be = 4 -- used 0.54534 seconds

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.