This is WhitneyStratifications.info, produced by Macaulay2, version 1.25.05

WhitneyStratifications -- Computes Whitney Statifications of real and complex varieties and of algebraic maps between them.
***************************************************************************************************************************

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

This package computes Whitney stratifications of real and complex algebraic
varieties using the algorithms described in [1, 2]. For varieties considered
over the complex numbers the output is indexed by the strata dimension. When
wishing to treat the variety over the reals, the same output may be used, but
the dimensions of the strata may differ (and some strata may be empty), see [2]
for more details. This post processing in the real case is currently left to
the user.

A method is also provided to stratify polynomial maps $f:X\to Y$ between
algebraic varieties, the output is a Whitney stratification of both $X$ and
$Y$, such that for each (open, connected) strata $M$ of $X$ there is an (open,
connected) strata $N$ of $Y$ such that $f(M) \subset N$ and such that the
restriction of $f$ to $M$ is a submersion.

Computing the Conormal variety of a variety is an important step in these
algorithms, so a method for this is also provided.

References:

[1] Martin Helmer and Vidit Nanda. "Conormal Spaces and Whitney
Stratifications", Foundations of Computational Mathematics, DOI:
10.1007/s10208-022-09574-8.

[2] Martin Helmer and Vidit Nanda "Effective Whitney stratification of real
algebraic varieties", arXiv:2307.05427v2, 2023.

Author
======

  * Martin Helmer (see http://martin-helmer.com/ ) <mhelmer@ncsu.edu>

Version
=======

This documentation describes version 2.03 of WhitneyStratifications.

Citation
========

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

+-----------------------------------------------------------------------------+
|@misc{WhitneyStratificationsSource,                                          |
|  title = {{WhitneyStratifications: Compute Whitney Statifications           |
|  author = {Martin Helmer},                                                  |
|  howpublished = {A \emph{Macaulay2} package available at                    |
|    \url{https://github.com/Macaulay2/M2/tree/master/M2/Macaulay2/           |
|}                                                                            |
|-----------------------------------------------------------------------------|
| Algebraically & Stratifies Maps. Version~2.03}},                            |
|                                                                             |
|                                                                             |
|packages}}                                                                   |
+-----------------------------------------------------------------------------+

Exports
=======

  * Functions and commands
      * conormal -- Computes the conormal variety
      * conormalRing (missing documentation)
      * mapStratify -- Computes a Whitney stratification of
        a polynomial map $f:X\to Y$ between real or complex varieties.
      * nonProperSet (missing documentation)
      * whitneyStratify -- Computes a Whitney
        stratification of the real and complex varieties.
  * Methods
      * "conormal(Ideal)" -- see conormal, -- Computes the
        conormal variety
      * conormal(Ideal,Ring) (missing documentation)
      * conormalRing(Ideal) (missing documentation)
      * conormalRing(Ideal,List,List) (missing documentation)
      * "mapStratify(List,Ideal,Ideal)" -- see mapStratify,
        -- Computes a Whitney stratification of a polynomial map $f:X\to Y$
        between real or complex varieties.
      * nonProperSet(List,Ideal,Ideal) (missing documentation)
      * "whitneyStratify(Ideal)" -- see whitneyStratify,
        -- Computes a Whitney stratification of the real and complex varieties.
      * whitneyStratify(Ideal,ZZ) (missing documentation)
      * whitneyStratify(Ideal,ZZ,ZZ) (missing documentation)
  * Symbols
      * isProper (missing documentation)
      * StratsToFind (missing documentation)

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

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

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

The source of this document is in WhitneyStratifications.m2:676:0.

conormal -- Computes the conormal variety
*****************************************

  * Usage:
        conormal(I)
  * Inputs:
      * I, an ideal (Macaulay2Doc), in a polynomial ring
        $k[x_1,\dots, x_n]$ for a field $k$, defining a closed variety in $k^n$
        (or in $\PP^n$ if the ideal is homogeneous).
  * Outputs:
      * C, an ideal defining the conormal variety in $k^n \times \PP^{n-1}$.

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

For a complex projective variety $X=V(I)\subset \PP^n$ this command computes
the ideal of the conormal variety $Con(X)$ in $k^n \times \PP^{n-1}$.

+-----------------------------------------------------------------------------+
|i1 : S=QQ[x..z]                                                              |
|                                                                             |
|o1 = S                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : I=ideal(y^2*z-x^2)                                                      |
|                                                                             |
|            2     2                                                          |
|o2 = ideal(y z - x )                                                         |
|                                                                             |
|o2 : Ideal of S                                                              |
+-----------------------------------------------------------------------------+
|i3 : conormal I                                                              |
|                                                                             |
|                                           2    2     2                      |
|o3 = ideal (y*v  - 2z*v , x*v  + 2z*v , z*v  - v , y*v  - 2v v , y*z*v  +    |
|               1       2     0       2     0    1     0     1 2       0      |
|     ------------------------------------------------------------------------|
|            2             2     2                                            |
|     x*v , y v  + 2x*v , y z - x )                                           |
|        1     0       2                                                      |
|                                                                             |
|o3 : Ideal of QQ[x..z, v ..v ]                                               |
|                        0   2                                                |
+-----------------------------------------------------------------------------+

Ways to use conormal:
=====================

  * "conormal(Ideal)"
  * conormal(Ideal,Ring) (missing documentation)

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

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

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

The source of this document is in WhitneyStratifications.m2:676:0.

conormalRing
************

Ways to use conormalRing:
=========================

  * conormalRing(Ideal) (missing documentation)
  * conormalRing(Ideal,List,List) (missing documentation)

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

The object conormalRing (missing documentation) is a method function (Macaulay2Doc).

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

The source of this document is in
/home/runner/work/M2/M2/M2/BUILD/build/Macaulay2/packages/currentString:2:0.

isProper
********

Functions with optional argument named isProper:
================================================

  * mapStratify(...,isProper=>...) (missing documentation)

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

The object isProper (missing documentation) is a symbol (Macaulay2Doc).

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

The source of this document is in
/home/runner/work/M2/M2/M2/BUILD/build/Macaulay2/packages/currentString:2:0.

mapStratify -- Computes a Whitney stratification of a polynomial map $f:X\to Y$ between real or complex varieties.
******************************************************************************************************************

  * Usage:
        mapStratify(f,X,Y)
  * Inputs:
      * f, a list (Macaulay2Doc), a list of polynomials in the same
        ring as the ideal X
      * X, an ideal (Macaulay2Doc), defining an affine or
        projective variety.
      * Y, an ideal (Macaulay2Doc), defining an affine or
        projective variety.
  * Optional inputs (Macaulay2Doc),:
      * isProper (missing documentation) => ..., default value true,
      * Print (missing documentation) => ..., default value false,
      * Projective (missing documentation) => ..., default value false,
      * StratsToFind (missing documentation) => ..., default value "all",
  * Outputs:
      * MS, a list (Macaulay2Doc), a List containing two elements:
        a Whitney stratification of $X$ and of $Y$. Each stratification is
        stored in a hash table indexed by (complex) dimension, with the entry
        of (complex) dimension $i$ consisting of a list of prime ideals. The
        strata of $V(I)$ are the connected components of the successive
        difference between the varieties in the hash tables.

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

For a polynomial map $f:X\to Y$ this command computes a Whitney stratification
of $f$, that is a Whitney stratification of $X$ and of $Y$ (in the same output
format as the whitneyStatify command), such that for each (open, connected)
strata $M$ of $X$ there is an (open, connected) strata $N$ of $Y$ such that
$f(M) \subset N$ and such that the restriction of $f$ to $M$ is a submersion.
When $f$ is a proper map this stratification turns $f$ into a locally trivial
fiber bundle by Thom's isotopy lemma. More generally when $f$ is a dominant map
between varieties of the same dimension a stratification which further
stratifies by non-properness locus is also implemented (as described in Section
3.3 of [2], M. Helmer, V. Nanda, Effective Whitney Stratification of Real
Algebraic Varieties . Arxiv: 2307.05427). This can be used to, for example,
solve the real root classification problem (see Section 5 of [2]), that is to
stratify the parameter space of a parametric system of polynomials with
generically finitely many complex solutions into regions where the number of
real solutions is fixed.

We illustrate this on the quadratic equation $ax^2+bx+c$ by stratifying the
parameter space, $(a,b,c)\in \RR^3$, into regions where the number of real
roots is constant.

Here we stratify the projection map $X\to \RR^3$ where $X=V(ax^2+bx+c)$.

+-----------------------------------------------------------+
|i1 : R=QQ[a,b,c,x]                                         |
|                                                           |
|o1 = R                                                     |
|                                                           |
|o1 : PolynomialRing                                        |
+-----------------------------------------------------------+
|i2 : I=ideal(a*x^2+b*x+c)                                  |
|                                                           |
|              2                                            |
|o2 = ideal(a*x  + b*x + c)                                 |
|                                                           |
|o2 : Ideal of R                                            |
+-----------------------------------------------------------+
|i3 : S=QQ[(gens(R))_(toList(0..2))]                        |
|                                                           |
|o3 = S                                                     |
|                                                           |
|o3 : PolynomialRing                                        |
+-----------------------------------------------------------+
|i4 : gens S                                                |
|                                                           |
|o4 = {a, b, c}                                             |
|                                                           |
|o4 : List                                                  |
+-----------------------------------------------------------+
|i5 : F={R_0,R_1,R_2}                                       |
|                                                           |
|o5 = {a, b, c}                                             |
|                                                           |
|o5 : List                                                  |
+-----------------------------------------------------------+
|i6 : ms=mapStratify(F,I,ideal(0_S),isProper=>false)        |
|                                                           |
|o6 = {MutableHashTable{...4...}, MutableHashTable{...4...}}|
|                                                           |
|o6 : List                                                  |
+-----------------------------------------------------------+
|i7 : peek last ms                                          |
|                                                           |
|o7 = MutableHashTable{0 => {ideal (c, b, a)}          }    |
|                      1 => {ideal (b, a)}                  |
|                      3 => {ideal 0}                       |
|                                            2              |
|                      2 => {ideal a, ideal(b  - 4a*c)}     |
+-----------------------------------------------------------+

For this and other root classification examples the option isProper=>false
should be used, as the corresponding projection maps are in general not proper.
Note that the top dimensional strata in this case are the four connected
components of $\RR^3-V(a(b^2-4ac))$, and so on for the lower dimensional
strata.

Another root classification example, this time we find the regions of the
parameter space $\{(a,b)\in \RR^2\}$ where the number of real roots to the
system $x^2-y^2+b = -ax+x^2+by=0$ is constant; this is Example 1.2 in Reference
[2].

+-----------------------------------------------------------------------------+
|i8 : R=QQ[a,b,x,y];                                                          |
+-----------------------------------------------------------------------------+
|i9 : I=ideal(x^2-y^2+b, -a*x+x^2+b*y);                                       |
|                                                                             |
|o9 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i10 : S=QQ[(gens(R))_(toList(0..1))];                                        |
+-----------------------------------------------------------------------------+
|i11 : F={R_0,R_1};                                                           |
+-----------------------------------------------------------------------------+
|i12 : ms=mapStratify(F,I,ideal(0_S),isProper=>false)                         |
|                                                                             |
|o12 = {MutableHashTable{...3...}, MutableHashTable{...3...}}                 |
|                                                                             |
|o12 : List                                                                   |
+-----------------------------------------------------------------------------+
|i13 : peek last ms                                                           |
|                                                                             |
|o13 = MutableHashTable{2 => {ideal 0}                                        |
|                                                                             |
|                       0 => {ideal (b, a), ideal (b + 4, a), ideal (27b -    |
|                                             6     4 2     2 4    6    4     |
|                       1 => {ideal b, ideal(a  - 3a b  + 3a b  - b  + a b    |
|-----------------------------------------------------------------------------|
|                       }                                                     |
|       2                                                                     |
|4, 729a  + 128)}                                                             |
|     2 3     5      4                                                        |
|- 20a b  - 8b  - 16b )}                                                      |
+-----------------------------------------------------------------------------+

Another broad class of interesting examples is parameterized projective
varieties, as the projection map to the parameter space is induced by the
projection $\PP^n\times \CC^m\to \CC^m$ and is hence always proper. Again we
seek to understand how the topology of the variety changes with parameters. The
following example is a special case of an example from the study of Feynman
integrals in mathematical physics (in particular is arises from the "one loop
bubble" for the case of equal masses). Note that for any fixed value of
parameters M1, P, the resulting polynomial Gh is homogeneous.

+----------------------------------------------------------------+
|i14 : R=QQ[M1,P,X_0..X_2];                                      |
+----------------------------------------------------------------+
|i15 : U = (X_1+X_2);                                            |
+----------------------------------------------------------------+
|i16 : F =U*(M1*X_1+M1*X_2)-P*X_1*X_2;                           |
+----------------------------------------------------------------+
|i17 : Gh = U*X_0+F;                                             |
+----------------------------------------------------------------+
|i18 : Xh=ideal (X_0*X_1*X_2*Gh);                                |
|                                                                |
|o18 : Ideal of R                                                |
+----------------------------------------------------------------+
|i19 : F={M1,P};                                                 |
+----------------------------------------------------------------+
|i20 : S=QQ[(gens(R))_(toList(0..1))];                           |
+----------------------------------------------------------------+
|i21 : ms=mapStratify(F,Xh,ideal(0_S));                          |
+----------------------------------------------------------------+
|i22 : peek last ms                                              |
|                                                                |
|o22 = MutableHashTable{0 => {ideal (P, M1)}                    }|
|                       1 => {ideal P, ideal M1, ideal(4M1 - P)} |
|                       2 => {ideal 0}                           |
+----------------------------------------------------------------+

Finally we remark that the option: StratsToFind, may be used with this
function, but should only be used with care. The default setting is
StratsToFind=>"all", and this is the only value of the option which is
guaranteed to compute the complete stratification, the other options may fail
to find all strata but are provided to allow the user to obtain partial
information on larger examples which may take too long to run on the default
"all" setting. The other possible values are StratsToFind=>"singularOnly", and
StratsToFind=>"most". The option  StratsToFind=>"singularOnly" is the fastest,
but also the most likely to return incomplete answers, and hence the output of
this command should be treated as a partial answer only. The option
StratsToFind=>"most" will most often get the full answer, but can miss strata,
so again the output should be treated as a partial answer. In the example below
all options return the complete answer, but only the output with
StratsToFind=>"all" should be considered complete; StratsToFind=>"all" is run
when no option is given.

+-----------------------------------------------------------------------+
|i23 : time ms=mapStratify(F,Xh,ideal(0_S),StratsToFind=>"singularOnly")|
| -- used 2.13385s (cpu); 1.2666s (thread); 0s (gc)                     |
|                                                                       |
|o23 = {MutableHashTable{...5...}, MutableHashTable{...3...}}           |
|                                                                       |
|o23 : List                                                             |
+-----------------------------------------------------------------------+
|i24 : peek last ms                                                     |
|                                                                       |
|o24 = MutableHashTable{0 => {ideal (P, M1)}                    }       |
|                       1 => {ideal P, ideal M1, ideal(4M1 - P)}        |
|                       2 => {ideal 0}                                  |
+-----------------------------------------------------------------------+
|i25 : time ms=mapStratify(F,Xh,ideal(0_S),StratsToFind=>"most")        |
| -- used 13.7713s (cpu); 3.34458s (thread); 0s (gc)                    |
|                                                                       |
|o25 = {MutableHashTable{...5...}, MutableHashTable{...3...}}           |
|                                                                       |
|o25 : List                                                             |
+-----------------------------------------------------------------------+
|i26 : peek last ms                                                     |
|                                                                       |
|o26 = MutableHashTable{0 => {ideal (P, M1)}                    }       |
|                       1 => {ideal P, ideal M1, ideal(4M1 - P)}        |
|                       2 => {ideal 0}                                  |
+-----------------------------------------------------------------------+
|i27 : time ms=mapStratify(F,Xh,ideal(0_S),StratsToFind=>"all")         |
| -- used 16.535s (cpu); 3.87214s (thread); 0s (gc)                     |
|                                                                       |
|o27 = {MutableHashTable{...5...}, MutableHashTable{...3...}}           |
|                                                                       |
|o27 : List                                                             |
+-----------------------------------------------------------------------+
|i28 : peek last ms                                                     |
|                                                                       |
|o28 = MutableHashTable{0 => {ideal (P, M1)}                    }       |
|                       1 => {ideal P, ideal M1, ideal(4M1 - P)}        |
|                       2 => {ideal 0}                                  |
+-----------------------------------------------------------------------+

Ways to use mapStratify:
========================

  * "mapStratify(List,Ideal,Ideal)"

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

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

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

The source of this document is in WhitneyStratifications.m2:676:0.

nonProperSet
************

Ways to use nonProperSet:
=========================

  * nonProperSet(List,Ideal,Ideal) (missing documentation)

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

The object nonProperSet (missing documentation) is a method function (Macaulay2Doc).

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

The source of this document is in
/home/runner/work/M2/M2/M2/BUILD/build/Macaulay2/packages/currentString:2:0.

StratsToFind
************

Functions with optional argument named StratsToFind:
====================================================

  * mapStratify(...,StratsToFind=>...) (missing documentation)

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

The object StratsToFind (missing documentation) is a symbol (Macaulay2Doc).

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

The source of this document is in
/home/runner/work/M2/M2/M2/BUILD/build/Macaulay2/packages/currentString:2:0.

whitneyStratify -- Computes a Whitney stratification of the real and complex varieties.
***************************************************************************************

  * Usage:
        whitneyStratify(I)
  * Inputs:
      * I, an ideal (Macaulay2Doc), an ideal defining a closed
        subvariety of affine or projective space over a field.
  * Optional inputs (Macaulay2Doc),:
      * Print (missing documentation) => ..., default value false,
      * Projective (missing documentation) => ..., default value false,
  * Outputs:
      * WS, a mutable hash table (Macaulay2Doc), a hash
        table indexed by (complex) dimension, with the entry of (complex)
        dimension $i$ consisting of a list of prime ideals. The strata of
        $V(I)$ are the connected components of the difference between the
        variety defined by WS#i and that defined by WS#(i-1).

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

For a variety $X$ this command computes a Whitney stratification WS where WS#i
is a list of strata closures in (complex) dimension $i$; for a prime ideal $P$
in WS#i the associated open (connected) strata is given by the connected
components of $V(P)-Z$ where $Z$ is the union of the varieties defined by the
entries of WS#(i-1). We demonstrate the method for the Whitney umbrella below.

+---------------------------------------------+
|i1 : R=QQ[x..z]                              |
|                                             |
|o1 = R                                       |
|                                             |
|o1 : PolynomialRing                          |
+---------------------------------------------+
|i2 : I=ideal(y^2*z-x^2)                      |
|                                             |
|            2     2                          |
|o2 = ideal(y z - x )                         |
|                                             |
|o2 : Ideal of R                              |
+---------------------------------------------+
|i3 : WS=whitneyStratify I                    |
|                                             |
|o3 = MutableHashTable{...3...}               |
|                                             |
|o3 : MutableHashTable                        |
+---------------------------------------------+
|i4 : peek WS                                 |
|                                             |
|o4 = MutableHashTable{0 => {ideal (z, y, x)}}|
|                      1 => {ideal (y, x)}    |
|                                   2     2   |
|                      2 => {ideal(y z - x )} |
+---------------------------------------------+

Now the projective version; using the option Projective=>true will treat the
input as a projective vareity. If this option is omitted the input is treated
as an affine cone over the projective vareity.

+--------------------------------------------------------------+
|i5 : S=QQ[x..z,w]                                             |
|                                                              |
|o5 = S                                                        |
|                                                              |
|o5 : PolynomialRing                                           |
+--------------------------------------------------------------+
|i6 : I=ideal(y^2*z-x^2*w)                                     |
|                                                              |
|            2     2                                           |
|o6 = ideal(y z - x w)                                         |
|                                                              |
|o6 : Ideal of S                                               |
+--------------------------------------------------------------+
|i7 : WS=whitneyStratify(I,Projective=>true)                   |
|                                                              |
|o7 = MutableHashTable{...3...}                                |
|                                                              |
|o7 : MutableHashTable                                         |
+--------------------------------------------------------------+
|i8 : peek WS                                                  |
|                                                              |
|o8 = MutableHashTable{0 => {ideal (z, y, x), ideal (w, y, x)}}|
|                      1 => {ideal (y, x)}                     |
|                                   2     2                    |
|                      2 => {ideal(y z - x w)}                 |
+--------------------------------------------------------------+

Another projective example.

+-----------------------------------------------------------------------------+
|i9 : R=QQ[a_0..a_4]                                                          |
|                                                                             |
|o9 = R                                                                       |
|                                                                             |
|o9 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i10 : I=ideal(a_0^2*a_4-a_1*a_2^2+a_3^3-a_3*a_0^2-a_4^2*a_3)                 |
|                                                                             |
|                 2    2      3    2        2                                 |
|o10 = ideal(- a a  - a a  + a  + a a  - a a )                                |
|               1 2    0 3    3    0 4    3 4                                 |
|                                                                             |
|o10 : Ideal of R                                                             |
+-----------------------------------------------------------------------------+
|i11 : V=whitneyStratify(I,Projective=>true)                                  |
|                                                                             |
|o11 = MutableHashTable{...4...}                                              |
|                                                                             |
|o11 : MutableHashTable                                                       |
+-----------------------------------------------------------------------------+
|i12 : peek V                                                                 |
|                                                                             |
|o12 = MutableHashTable{2 => {}                                               |
|                                                      2     2                |
|                       0 => {ideal (a  - a , a , a , a  - 2a ), ideal (a ,   |
|                                     3    4   2   1   0     4           4    |
|                                                  2     2                    |
|                       1 => {ideal (a  - a , a , a  - 2a )}                  |
|                                     3    4   2   0     4                    |
|                                      2    2      3    2        2            |
|                       3 => {ideal(a a  + a a  - a  - a a  + a a )}          |
|                                    1 2    0 3    3    0 4    3 4            |
|-----------------------------------------------------------------------------|
|            }                                                                |
|                                                                             |
|a , a , a )}                                                                 |
| 3   2   0                                                                   |
+-----------------------------------------------------------------------------+

Note that as with the Whitney umbrella simply taking successive singular loci
will not yield the correct stratification, in particular one would miss the two
points defined by the second entry of V#0.

+------------------------------------------------+
|i13 : J=radical (I+minors(codim I, jacobian I)) |
|                                                |
|                           2     2              |
|o13 = ideal (a  - a , a , a  - 2a )             |
|              3    4   2   0     4              |
|                                                |
|o13 : Ideal of R                                |
+------------------------------------------------+
|i14 : J2=radical (J+minors(codim J, jacobian J))|
|                                                |
|o14 = ideal (a , a , a , a )                    |
|              4   3   2   0                     |
|                                                |
|o14 : Ideal of R                                |
+------------------------------------------------+

Ways to use whitneyStratify:
============================

  * "whitneyStratify(Ideal)"
  * whitneyStratify(Ideal,ZZ) (missing documentation)
  * whitneyStratify(Ideal,ZZ,ZZ) (missing documentation)

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

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

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

The source of this document is in WhitneyStratifications.m2:676:0.