This is FrobeniusThresholds.info, produced by Macaulay2, version 1.20

FrobeniusThresholds -- a package for computing F-pure thresholds and related invariants
***************************************************************************************

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

FrobeniusThresholds is a package for computing $F$-pure thresholds, $F$-jumping
exponents, and related numerical measures of singularity in positive
characteristic.

The Frobenius endomorphism on a ring of prime characteristic $p > 0$, which
sends a ring element to its $p$-th power, is a fundamental tool in positive
characteristic commutative algebra.  Kunz showed that regularity is
characterized by the behavior of this map, and since then many other properties
of the Frobenius map have been used to measure the 'severity' of singularities
in commutative algebra. The $F$-pure threshold is a prominent object in this
realm.

This package relies heavily on the TestIdeals, package.
Many special cases (binomials, diagonal polynomials, etc.) are seamlessly
handled by using special algorithms found in Hernández (see
https://doi.org/10.1090/S0002-9939-2014-12260-X ), Hernández (see
https://doi.org/10.1090/S0002-9939-2014-11941-1 ), and Hernández-Teixeira (see
https://www.sciencedirect.com/science/article/pii/S0747717116300347 ).

Notable functions:
  * fpt, computes (or estimates) the $F$-pure threshold.
  * isFJumpingExponent, checks whether a given number
    is an $F$-jumping exponent.
  * compareFPT, determines whether the given number is
    greater than, less than, or equal to the $F$-pure threshold.
  * frobeniusNu, is a function whose normalized value
    provides a canonical estimate for the $F$-pure threshold, $F$-thresholds,
    and more.
The following example demonstrates some of the functionality of this package.

+---------------------------------+
|i1 : p = 131;                    |
+---------------------------------+
|i2 : R = ZZ/p[x,y];              |
+---------------------------------+
|i3 : f = x^13 - y^5;             |
+---------------------------------+
|i4 : c = fpt(f)                  |
|                                 |
|     18                          |
|o4 = --                          |
|     65                          |
|                                 |
|o4 : QQ                          |
+---------------------------------+
|i5 : compareFPT(c - 1/p^2, f)    |
|                                 |
|o5 = -1                          |
+---------------------------------+
|i6 : compareFPT(c, f)            |
|                                 |
|o6 = 0                           |
+---------------------------------+
|i7 : compareFPT(c + 1/p, f)      |
|                                 |
|o7 = 1                           |
+---------------------------------+
|i8 : isFJumpingExponent(36/65, f)|
|                                 |
|o8 = true                        |
+---------------------------------+

Acknowledgements:

The authors would like to thank David Eisenbud, Daniel Grayson, Anurag Singh,
Greg Smith, and Mike Stillman for useful conversations and comments on the
development of this package.

Contributors

We sincerely thank the following people, who contributed code to this package.
  * Erin Bela
  * Zhibek Kadyrsizova (see https://nu.edu.kz/faculty/zhibek-kadyrsizova )
  * Mordechai Katzman (see http://www.katzman.staff.shef.ac.uk/ )
  * Sara Malec (see https://www.hood.edu/academics/faculty/sara-malec )
  * Marcus Robinson (see http://www.math.utah.edu/~robinson/ )

Authors
=======

  * Juliette Bruce (see https://juliettebruce.github.io/ )
    <juliette.bruce@math.wisc.edu>
  * Daniel Hernández (see https://hernandez.faculty.ku.edu )
    <hernandez@ku.edu>
  * Karl Schwede (see http://math.utah.edu/~schwede/ ) <schwede@math.utah.edu>
  * Dan Smolkin (see http://dan.smolk.in ) <smolkin@math.utah.edu>
  * Pedro Teixeira (see https://www.knox.edu/academics/majors-and-minors/
    mathematics/faculty/teixeira-pedro ) <pteixeir@knox.edu>
  * Emily Witt (see https://witt.faculty.ku.edu ) <witt@ku.edu>

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

Version 2.1 of this package was accepted for publication in volume 11 (see
https://msp.org/jsag/2021/11-1/ ) of The Journal of Software for Algebra and
Geometry (see http://j-sag.org/ ) on 11 September 2020, in the article The
FrobeniusThresholds package for Macaulay2 (see
https://msp.org/jsag/2021/11-1/p04.xhtml ). That version can be obtained from
the journal (see https://msp.org/jsag/2021/11-1/jsag-v11-n1-x04-
FrobeniusThresholds.m2 ) or from the Macaulay2 source code repository (see
http://github.com/Macaulay2/M2/blob/eb4b9b426546bee5d4997afcc2b353421a30719d/M2
/Macaulay2/packages/....m2 ).

Version
=======

This documentation describes version 2.1 of FrobeniusThresholds.

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

The source code from which this documentation is derived is in the file
FrobeniusThresholds.m2 (see common/share/Macaulay2/FrobeniusThresholds.m2 ).
The auxiliary files accompanying it are in the directory FrobeniusThresholds/
(see common/share/Macaulay2/FrobeniusThresholds/ ).

Exports
=======

  * Functions and commands
      * compareFPT -- determine whether a number is less
        than, greater than, or equal to the F-pure threshold
      * fpt -- attempt to compute the F-pure threshold of a
        polynomial at the origin or globally
      * frobeniusNu -- computes the largest power of an
        ideal not contained in a specified Frobenius power
      * isFJumpingExponent -- whether a given number
        is an F-jumping exponent
      * isFPT -- checks whether a given rational number is the
        F-pure threshold
      * isSimpleNormalCrossing -- whether a
        polynomial is a product of factors that are in simple normal crossing
  * Methods
      * "compareFPT(Number,RingElement)" -- see compareFPT,
        -- determine whether a number is less than, greater than, or equal to
        the F-pure threshold
      * "fpt(List,List)" -- see fpt, -- attempt to compute the
        F-pure threshold of a polynomial at the origin or globally
      * "fpt(RingElement)" -- see fpt, -- attempt to compute the
        F-pure threshold of a polynomial at the origin or globally
      * "frobeniusNu(ZZ,Ideal)" -- see frobeniusNu, --
        computes the largest power of an ideal not contained in a specified
        Frobenius power
      * "frobeniusNu(ZZ,Ideal,Ideal)" -- see frobeniusNu, --
        computes the largest power of an ideal not contained in a specified
        Frobenius power
      * "frobeniusNu(ZZ,RingElement)" -- see frobeniusNu, --
        computes the largest power of an ideal not contained in a specified
        Frobenius power
      * "frobeniusNu(ZZ,RingElement,Ideal)" -- see frobeniusNu,
        -- computes the largest power of an ideal not contained in
        a specified Frobenius power
      * "isFJumpingExponent(Number,RingElement)" -- see
        isFJumpingExponent, -- whether a given number is an
        F-jumping exponent
      * "isFPT(Number,RingElement)" -- see isFPT, -- checks
        whether a given rational number is the F-pure threshold
      * "isSimpleNormalCrossing(Product)" -- see isSimpleNormalCrossing,
        -- whether a polynomial is a product of factors
        that are in simple normal crossing
      * "isSimpleNormalCrossing(RingElement)" -- see
        isSimpleNormalCrossing, -- whether a polynomial
        is a product of factors that are in simple normal crossing
  * Symbols
      * Bounds -- an option for the function fpt specifying
        lower and upper bounds for the F-pure threshold
      * ContainmentTest -- an option for the function
        frobeniusNu specifying the type of containment of powers of ideals to
        test
      * FinalAttempt -- an option for the function fpt to
        perform a final check attempting find an F-pure threshold
      * FrobeniusPower -- a valid value for the option
        ContainmentTest
      * FrobeniusRoot -- a valid value for the option
        ContainmentTest
      * GlobalFrobeniusRoot -- a valid value for
        the option ContainmentTest
      * GuessStrategy -- an option for the function fpt
        to specify the criterion used for selecting numbers to check
      * ReturnList -- an option for the function frobeniusNu
        to return a list of successive nu values
      * Search -- an option for the function frobeniusNu to
        specify the search method for testing containments of powers of ideals
      * StandardPower -- a valid value for the option
        ContainmentTest
      * UseSpecialAlgorithms -- an option for the
        functions fpt and frobeniusNu to use special algorithms to speed up
        computations

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

The object FrobeniusThresholds, is a package (Macaulay2Doc).

Bounds -- an option for the function fpt specifying lower and upper bounds for the F-pure threshold
***************************************************************************************************

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

An option for the function fpt, specifying bounds for the $F$-pure
threshold. Bounds accepts lists consisting of two numbers, namely a lower and
an upper bound for the $F$-pure threshold being computed. This useful feature
allows the user to refine bounds obtained in previous computations, as
illustrated below.

+------------------------------------------------------------+
|i1 : R = ZZ/5[x,y];                                         |
+------------------------------------------------------------+
|i2 : f = x^7*y^5*(x + y)^5*(x^2 + y^3)^4;                   |
+------------------------------------------------------------+
|i3 : fpt(f, DepthOfSearch => 3, Attempts => 5)              |
|                                                            |
|       19   1                                               |
|o3 = {---, --}                                              |
|      250  13                                               |
|                                                            |
|o3 : List                                                   |
+------------------------------------------------------------+
|i4 : fpt(f, DepthOfSearch => 3, Attempts => 5, Bounds => oo)|
|                                                            |
|       45   1                                               |
|o4 = {---, --}                                              |
|      589  13                                               |
|                                                            |
|o4 : List                                                   |
+------------------------------------------------------------+

Functions with optional argument named Bounds :
===============================================

  * "fpt(...,Bounds=>...)" -- see fpt, -- attempt to compute the
    F-pure threshold of a polynomial at the origin or globally

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

The object Bounds, is a symbol (Macaulay2Doc).

compareFPT -- determine whether a number is less than, greater than, or equal to the F-pure threshold
*****************************************************************************************************

Synopsis
========

  * Usage:
        compareFPT(t, f)
  * Inputs:
      * t, a number (Macaulay2Doc), a rational number to compare
        to the $F$-pure threshold
      * f, a ring element (Macaulay2Doc), in a
        $\mathbb{Q}$-Gorenstein ring of positive characteristic $p$, whose
        index is not divisible by $p$
  * Optional inputs (Macaulay2Doc),:
      * AssumeDomain => a Boolean value (Macaulay2Doc), default
        value true, indicates whether the ambient ring of f  is an integral
        domain
      * FrobeniusRootStrategy => a symbol (Macaulay2Doc), default
        value Substitution, passed to computations in the TestIdeals,
        package
      * AtOrigin => a Boolean value (Macaulay2Doc), default
        value false, tells the function whether to consider only the behavior
        at the origin
      * MaxCartierIndex => an integer (Macaulay2Doc), default value
        10, sets the maximum $\mathbb{Q}$-Gorenstein index to search for
      * QGorensteinIndex => an integer (Macaulay2Doc), default value
        0, specifies the $\mathbb{Q}$-Gorenstein index of the ring
      * Verbose => a Boolean value (Macaulay2Doc), default value
        false, whether the output is to be verbose
  * Outputs:
      * an integer (Macaulay2Doc), namely -1, 1, or 0, according as t
        is less than, greater than, or equal to the $F$-pure threshold of f

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

Let $f$ be an element of a $\mathbb{Q}$-Gorenstein ring of positive
characteristic $p$, whose index is not divisible by $p$. Given a rational
number $t$, the command compareFPT(t, f) returns -1 if $t$ is less than the
$F$-pure threshold of $f$, 1 if $t$ is greater than the $F$-pure threshold, or
0 if $t$ equals the $F$-pure threshold.

+-----------------------+
|i1 : R = ZZ/7[x,y];    |
+-----------------------+
|i2 : f =  x^3 - y^2;   |
+-----------------------+
|i3 : compareFPT(1/2, f)|
|                       |
|o3 = -1                |
+-----------------------+
|i4 : compareFPT(5/6, f)|
|                       |
|o4 = 0                 |
+-----------------------+
|i5 : compareFPT(6/7, f)|
|                       |
|o5 = 1                 |
+-----------------------+

As noted, this function can be used in a singular ring of characteristic $p>0$
that is strongly $F$-regular, as long as $p$ does not divide the
$\mathbb{Q}$-Gorenstein index. For instance, in the following example, $x$
defines a Cartier divisor that is twice one of the rulings of the cone.

+---------------------------------+
|i6 : R = ZZ/5[x,y,z]/(x*y - z^2);|
+---------------------------------+
|i7 : compareFPT(1/3, x)          |
|                                 |
|o7 = -1                          |
+---------------------------------+
|i8 : compareFPT(1/2, x)          |
|                                 |
|o8 = 0                           |
+---------------------------------+
|i9 : compareFPT(13/25, x)        |
|                                 |
|o9 = 1                           |
+---------------------------------+

Consider a Veronese subring (whose inclusion in the ambient polynomial ring is
étale in codimension 1), so the $F$-pure threshold of the given polynomial (in
this case 19/125) should be independent of which ring we are in.

+----------------------------------------------+
|i10 : T = ZZ/5[a,b];                          |
+----------------------------------------------+
|i11 : S = ZZ/5[x,y,z,w];                      |
+----------------------------------------------+
|i12 : f = map(T, S, {a^3, a^2*b, a*b^2, b^3});|
|                                              |
|o12 : RingMap T <--- S                        |
+----------------------------------------------+
|i13 : R = S/ker f;                            |
+----------------------------------------------+
|i14 : g = x^7 - w^3;                          |
+----------------------------------------------+
|i15 : h = f(sub(g, S))                        |
|                                              |
|       21    9                                |
|o15 = a   - b                                 |
|                                              |
|o15 : T                                       |
+----------------------------------------------+
|i16 : compareFPT(19/125, g)                   |
|                                              |
|o16 = 0                                       |
+----------------------------------------------+
|i17 : compareFPT(19/125, h)                   |
|                                              |
|o17 = 0                                       |
+----------------------------------------------+
|i18 : compareFPT(19/124, g)                   |
|                                              |
|o18 = 1                                       |
+----------------------------------------------+
|i19 : compareFPT(19/125 - 1/1000, g)          |
|                                              |
|o19 = -1                                      |
+----------------------------------------------+

Setting the AtOrigin option to true (its default value is false) will tell the
function to consider the $F$-pure threshold at the origin.

+------------------------------------------+
|i20 : R = ZZ/7[x,y];                      |
+------------------------------------------+
|i21 : f = (x + 1)^3 - (y + 3)^2;          |
+------------------------------------------+
|i22 : compareFPT(5/6, f)                  |
|                                          |
|o22 = 0                                   |
+------------------------------------------+
|i23 : compareFPT(5/6, f, AtOrigin => true)|
|                                          |
|o23 = -1                                  |
+------------------------------------------+

If the ambient ring $R$ is not a domain, the option AssumeDomain should be set
to false. We assume that the ring is a domain by default, in order to speed up
the computation.

If the Gorenstein index of $R$ is known, the user should set the option
QGorensteinIndex to this value. Otherwise, the function attempts to find the
Gorenstein index of $R$, assuming it is between 1 and the value passed to the
option MaxCartierIndex (default value 10).

The option FrobeniusRootStrategy is passed to internal calls of functions from
the TestIdeals, package. The two valid values for
FrobeniusRootStrategy are Substitution and MonomialBasis.

Setting the option Verbose (default value false) to true produces verbose
output.

See also
========

  * fpt -- attempt to compute the F-pure threshold of a polynomial
    at the origin or globally
  * isFPT -- checks whether a given rational number is the F-pure
    threshold
  * isFJumpingExponent -- whether a given number is
    an F-jumping exponent

Ways to use compareFPT :
========================

  * "compareFPT(Number,RingElement)"

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

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

ContainmentTest -- an option for the function frobeniusNu specifying the type of containment of powers of ideals to test
************************************************************************************************************************

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

An option for the function frobeniusNu, specifying which
type of containment test to apply. The valid values are StandardPower,
FrobeniusRoot, GlobalFrobeniusRoot, FrobeniusPower, and null. When the option
AtOrigin (TestIdeals), is set to true, the default value for
ContainmentTest, null, is replaced with FrobeniusRoot when the second argument
passed to frobeniusNu, is a ring element, and StandardPower
when that argument is an ideal. When AtOrigin (TestIdeals), is
set to false, the value GlobalFrobeniusRoot is used.

Functions with optional argument named ContainmentTest :
========================================================

  * "frobeniusNu(...,ContainmentTest=>...)" -- see frobeniusNu,
    -- computes the largest power of an ideal not contained in a
    specified Frobenius power

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

The object ContainmentTest, is a symbol (Macaulay2Doc).

FinalAttempt -- an option for the function fpt to perform a final check attempting find an F-pure threshold
***********************************************************************************************************

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

An option for the function fpt, specifying whether the convexity of
the $F$-signature function and a secant line argument are to be used as an
attempt to refine the interval containing the $F$-pure threshold, or to find
its exact value. Takes on Boolean values; default value is false.

Functions with optional argument named FinalAttempt :
=====================================================

  * "fpt(...,FinalAttempt=>...)" -- see fpt, -- attempt to compute
    the F-pure threshold of a polynomial at the origin or globally

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

The object FinalAttempt, is a symbol (Macaulay2Doc).

fpt -- attempt to compute the F-pure threshold of a polynomial at the origin or globally
****************************************************************************************

Synopsis
========

  * Usage:
        fpt(f)
        fpt(L, m)
  * Inputs:
      * f, a ring element (Macaulay2Doc), a polynomial with
        coefficients in a finite field
      * L, a list (Macaulay2Doc), containing linear forms in two
        variables
      * m, a list (Macaulay2Doc), containing positive integers
  * Optional inputs (Macaulay2Doc),:
      * Attempts => an integer (Macaulay2Doc), default value 3,
        specifies the number of "guess and check" attempts to make
      * Bounds => a list (Macaulay2Doc), default value {0, 1},
        consisting of two numbers, known to be lower and upper bounds,
        respectively, of the $F$-pure threshold of f
      * DepthOfSearch => an integer (Macaulay2Doc), default value 1,
        specifies the power of the characteristic to be used in a search for
        the $F$-pure threshold
      * FinalAttempt => a Boolean value (Macaulay2Doc), default
        value false, specifies whether to use the $F$-signature function and a
        secant line argument to attempt to improve the $F$-pure threshold
        estimate
      * GuessStrategy => a function (Macaulay2Doc), default
        value null, specifies a function to be used to rank numbers to be
        tested
      * GuessStrategy => a list (Macaulay2Doc), default value null,
        specifies weights to be used to rank numbers to be tested
      * AtOrigin => a Boolean value (Macaulay2Doc), default
        value true, specifies whether to compute the $F$-pure threshold at the
        origin or the global $F$-pure threshold
      * UseSpecialAlgorithms => a Boolean value (Macaulay2Doc),
        default value true, specifies whether to check if f is a diagonal
        polynomial, binomial, a standard-graded homogeneous polynomial in two
        variables, or a product of factors in simple normal crossing, and then
        apply appropriate algorithms or formulas
      * Verbose => a Boolean value (Macaulay2Doc), default value
        false, requests verbose feedback
  * Outputs:
      * a list (Macaulay2Doc), containing lower and upper bounds
        for the $F$-pure threshold of f
      * a rational number (Macaulay2Doc), the $F$-pure threshold of f
      * an infinite number (Macaulay2Doc), the $F$-pure
        threshold of f, if f does not vanish at the origin (or anywhere, if
        AtOrigin => false)

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

Given a polynomial $f$ with coefficients in a finite field, the function fpt
attempts to find the exact value for the $F$-pure threshold of $f$ at the
origin, and returns that value, if possible. Otherwise, it returns lower and
upper bounds for the $F$-pure threshold.

+-------------------------------------+
|i1 : ZZ/5[x,y,z];                    |
+-------------------------------------+
|i2 : fpt(x^3 + y^3 + z^3 + x*y*z)    |
|                                     |
|     4                               |
|o2 = -                               |
|     5                               |
|                                     |
|o2 : QQ                              |
+-------------------------------------+
|i3 : fpt(x^5 + y^6 + z^7 + (x*y*z)^3)|
|                                     |
|       7  2                          |
|o3 = {--, -}                         |
|      25  5                          |
|                                     |
|o3 : List                            |
+-------------------------------------+

When the option UseSpecialAlgorithms is set to true (the default value), fpt
first checks whether $f$ is a diagonal polynomial, a binomial, a form in two
variables, or a product of factors in simple normal crossing. If $f$ is either
a diagonal polynomial, a binomial, or a form in two variables, then algorithms
of Hernández, or Hernández and Teixeira, are executed to compute the $F$-pure
threshold of $f$. If $f$ is a product of factors in simple normal crossing, the
$F$-pure threshold is easily computed.

+-------------------------------------------------------------------+
|i4 : fpt(x^17 + y^20 + z^24) -- a diagonal polynomial              |
|                                                                   |
|      94                                                           |
|o4 = ---                                                           |
|     625                                                           |
|                                                                   |
|o4 : QQ                                                            |
+-------------------------------------------------------------------+
|i5 : fpt(x^2*y^6*z^10 + x^10*y^5*z^3) -- a binomial                |
|                                                                   |
|      997                                                          |
|o5 = ----                                                          |
|     6250                                                          |
|                                                                   |
|o5 : QQ                                                            |
+-------------------------------------------------------------------+
|i6 : fpt(x^5*(x + y)^7*(x + y + z)^10) -- SNC                      |
|                                                                   |
|      1                                                            |
|o6 = --                                                            |
|     10                                                            |
|                                                                   |
|o6 : QQ                                                            |
+-------------------------------------------------------------------+
|i7 : ZZ/5[x,y];                                                    |
+-------------------------------------------------------------------+
|i8 : fpt(x^2*y^6*(x + y)^9*(x + 3*y)^10) -- a form in two variables|
|                                                                   |
|      5787                                                         |
|o8 = -----                                                         |
|     78125                                                         |
|                                                                   |
|o8 : QQ                                                            |
+-------------------------------------------------------------------+

The computation of the $F$-pure threshold of a form $f$ in two variables
requires factoring $f$ into linear forms, and can sometimes hang when
attempting that factorization. For this reason, when a factorization is already
known, the user can pass to fpt a list containing all the pairwise prime linear
factors of $f$ and a list containing their respective multiplicities.

+-----------------------------------------------------+
|i9 : fpt({x, y, x + y, x + 3*y}, {2, 6, 9, 10}) == oo|
|                                                     |
|o9 = true                                            |
+-----------------------------------------------------+

When no special algorithm is available or UseSpecialAlgorithms is set to false,
fpt computes $\nu$ = See frobeniusNu,(e,f), where $e$ is the
value of the option DepthOfSearch, which conservatively defaults to 1. At this
point, we know that the $F$-pure threshold of $f$ lies in the closed interval
[$\nu/(p^e-1),(\nu+1)/p^e$], and the subroutine guessFPT is called to make some
"educated guesses" in an attempt to find the $F$-pure threshold, or at least
narrow down the above interval. The number of "guesses" is controlled by the
option Attempts, which conservatively defaults to 3. If Attempts is set to 0,
guessFPT is bypassed. If Attempts is set to at least 1, then a first check is
run to verify whether the right-hand endpoint $(\nu+1)/p^e$ of the above
interval is the $F$-pure threshold.

+-----------------------------------------------------------------------------+
|i10 : f = x^2*(x + y)^3*(x + 3*y^2)^5;                                       |
+-----------------------------------------------------------------------------+
|i11 : fpt(f, Attempts => 0) -- a bad estimate                                |
|                                                                             |
|          1                                                                  |
|o11 = {0, -}                                                                 |
|          5                                                                  |
|                                                                             |
|o11 : List                                                                   |
+-----------------------------------------------------------------------------+
|i12 : fpt(f, Attempts => 0, DepthOfSearch => 3) -- a better estimate         |
|                                                                             |
|        21   22                                                              |
|o12 = {---, ---}                                                             |
|       124  125                                                              |
|                                                                             |
|o12 : List                                                                   |
+-----------------------------------------------------------------------------+
|i13 : fpt(f, Attempts => 1, DepthOfSearch => 3) -- the right-hand endpoint   |
|                                                                             |
|       22                                                                    |
|o13 = ---                                                                    |
|      125                                                                    |
|                                                                             |
|o13 : QQ                                                                     |
|-----------------------------------------------------------------------------|
|(ν+1)/p^e is the fpt                                                        |
+-----------------------------------------------------------------------------+

If Attempts is set to at least 2 and the right-hand endpoint $(\nu+1)/p^e$ is
not the $F$-pure threshold, a second check is run to verify whether the
left-hand endpoint $\nu/(p^e-1)$ is the $F$-pure threshold.

+-----------------------------------------------------------------------------+
|i14 : f = x^6*y^4 + x^4*y^9 + (x^2 + y^3)^3;                                 |
+-----------------------------------------------------------------------------+
|i15 : fpt(f, Attempts => 1, DepthOfSearch => 3)                              |
|                                                                             |
|       17   7                                                                |
|o15 = {--, --}                                                               |
|       62  25                                                                |
|                                                                             |
|o15 : List                                                                   |
+-----------------------------------------------------------------------------+
|i16 : fpt(f, Attempts => 2, DepthOfSearch => 3) -- the left-hand endpoint    |
|                                                                             |
|      17                                                                     |
|o16 = --                                                                     |
|      62                                                                     |
|                                                                             |
|o16 : QQ                                                                     |
|-----------------------------------------------------------------------------|
|ν/(p^e-1) is the fpt                                                        |
+-----------------------------------------------------------------------------+

If neither endpoint is the $F$-pure threshold and Attempts is set to more than
2, then additional checks are performed at numbers in the interval. A number in
the interval is selected, according to criteria specified by the option
GuessStrategy, (see its documentation for details), and
compareFPT, is used to test that number. If that "guess" is
correct, its value is returned; otherwise, the information returned by
compareFPT, is used to narrow down the interval, and this process
is repeated as many times as specified by Attempts.

+-----------------------------------------------+
|i17 : f = x^3*y^11*(x + y)^8*(x^2 + y^3)^8;    |
+-----------------------------------------------+
|i18 : fpt(f, DepthOfSearch => 3, Attempts => 4)|
|                                               |
|        1   4                                  |
|o18 = {--, --}                                 |
|       20  75                                  |
|                                               |
|o18 : List                                     |
+-----------------------------------------------+
|i19 : fpt(f, DepthOfSearch => 3, Attempts => 6)|
|                                               |
|        13   4                                 |
|o19 = {---, --}                                |
|       250  75                                 |
|                                               |
|o19 : List                                     |
+-----------------------------------------------+
|i20 : fpt(f, DepthOfSearch => 3, Attempts => 8)|
|                                               |
|       1                                       |
|o20 = --                                       |
|      19                                       |
|                                               |
|o20 : QQ                                       |
+-----------------------------------------------+

The option Bounds allows the user to specify known lower and upper bounds for
the $F$-pure threshold of $f$, in order to speed up computations or to refine
previously obtained estimates.

+-------------------------------------------------------------+
|i21 : f = x^7*y^5*(x + y)^5*(x^2 + y^3)^4;                   |
+-------------------------------------------------------------+
|i22 : fpt(f, DepthOfSearch => 3, Attempts => 5)              |
|                                                             |
|        19   1                                               |
|o22 = {---, --}                                              |
|       250  13                                               |
|                                                             |
|o22 : List                                                   |
+-------------------------------------------------------------+
|i23 : fpt(f, DepthOfSearch => 3, Attempts => 5, Bounds => oo)|
|                                                             |
|        45   1                                               |
|o23 = {---, --}                                              |
|       589  13                                               |
|                                                             |
|o23 : List                                                   |
+-------------------------------------------------------------+

If guessFPT is unsuccessful and FinalAttempt is set to true, the function fpt
proceeds to use the convexity of the $F$-signature function and a secant line
argument to attempt to narrow down the interval bounding the $F$-pure
threshold. If successful, the new lower bound may coincide with the upper
bound, in which case we can conclude that it is the desired $F$-pure threshold.
If that is not the case, an $F$-regularity check is done at the new lower
bound, to verify if it is the $F$-pure threshold.

+-----------------------------------------------------------------------------+
|i24 : f = 2*x^10*y^8+x^4*y^7-2*x^3*y^8;                                      |
+-----------------------------------------------------------------------------+
|i25 : numeric fpt(f, DepthOfSearch => 3)                                     |
|                                                                             |
|o25 = {.14, .144}                                                            |
|                                                                             |
|o25 : List                                                                   |
+-----------------------------------------------------------------------------+
|i26 : numeric fpt(f, DepthOfSearch => 3, FinalAttempt => true) --            |
|                                                                             |
|o26 = {.142067, .144}                                                        |
|                                                                             |
|o26 : List                                                                   |
|-----------------------------------------------------------------------------|
|FinalAttempt improves the estimate slightly                                  |
+-----------------------------------------------------------------------------+

The computations performed when FinalAttempt is set to true are often slow, and
often fail to improve the estimate, and for this reason, this option should be
used sparingly. It is often more effective to increase the values of Attempts
or DepthOfSearch, instead.

+-------------------------------------------------------------------+
|i27 : time numeric fpt(f, DepthOfSearch => 3, FinalAttempt => true)|
|     -- used 2.20003 seconds                                       |
|                                                                   |
|o27 = {.142067, .144}                                              |
|                                                                   |
|o27 : List                                                         |
+-------------------------------------------------------------------+
|i28 : time fpt(f, DepthOfSearch => 3, Attempts => 7)               |
|     -- used 1.40572 seconds                                       |
|                                                                   |
|      1                                                            |
|o28 = -                                                            |
|      7                                                            |
|                                                                   |
|o28 : QQ                                                           |
+-------------------------------------------------------------------+
|i29 : time fpt(f, DepthOfSearch => 4)                              |
|     -- used 1.08745 seconds                                       |
|                                                                   |
|      1                                                            |
|o29 = -                                                            |
|      7                                                            |
|                                                                   |
|o29 : QQ                                                           |
+-------------------------------------------------------------------+

As seen in several examples above, when the exact answer is not found, a list
containing the endpoints of an interval containing the $F$-pure threshold of
$f$ is returned. Whether that interval is open, closed, or a mixed interval
depends on the options passed (it will be open whenever Attempts is set to at
least 3); if the option Verbose is set to true, the precise interval will be
printed.

+-----------------------------------------------------------------------------+
|i30 : fpt(f, DepthOfSearch => 3, FinalAttempt => true, Verbose =>            |
|Starting fpt ...                                                             |
|fpt is not 1 ...                                                             |
|Verifying whether special algorithms apply...                                |
|Special fpt algorithms were not used ...                                     |
|ν has been computed: ν = frobeniusNu(3,f) = 17 ...                         |
|fpt lies in the interval [ν/(p^e-1),(ν+1)/p^e] = [17/124,18/125            |
|Starting guessFPT ...                                                        |
|The right-hand endpoint is not the fpt ...                                   |
|The left-hand endpoint is not the fpt ...                                    |
|guessFPT narrowed the interval down to (7/50,18/125) ...                     |
|Beginning F-signature computation ...                                        |
|First F-signature computed: s(f,(ν-1)/p^e) = 793/15625 ...                  |
|Second F-signature computed: s(f,ν/p^e) = 342/15625 ...                     |
|Computed F-signature secant line intercept: 8009/56375 ...                   |
|F-signature intercept is an improved lower bound;                            |
|Using F-regularity to check if it is the fpt ...                             |
|The new lower bound is not the fpt ...                                       |
|fpt failed to find the exact answer; try increasing the value of             |
|fpt lies in the interval (8009/56375,18/125).                                |
|                                                                             |
|        8009   18                                                            |
|o30 = {-----, ---}                                                           |
|       56375  125                                                            |
|                                                                             |
|o30 : List                                                                   |
|-----------------------------------------------------------------------------|
| true)                                                                       |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|] ...                                                                        |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|DepthOfSearch or Attempts.                                                   |
+-----------------------------------------------------------------------------+

Setting the option AtOrigin (default value true) to false can be used to tell
the function to compute the $F$-pure threshold globally.  In other words, it
computes the minimum of the $F$-pure threshold at all maximal ideals.

+------------------------------------+
|i31 : R = ZZ/7[x,y];                |
+------------------------------------+
|i32 : f = x*(y - 1)^2 - y*(x - 1)^3;|
+------------------------------------+
|i33 : fpt(f)                        |
|                                    |
|o33 = 1                             |
+------------------------------------+
|i34 : fpt(f, AtOrigin => false)     |
|                                    |
|      5                             |
|o34 = -                             |
|      6                             |
|                                    |
|o34 : QQ                            |
+------------------------------------+

In this case, most features enabled by UseSpecialAlgorithms => true are
ignored, except for the check for simple normal crossings; FinalAttempt => true
is also ignored.

Consider a simple normal crossings case.

+------------------------------------+
|i35 : f = x*y^2*(x - 1)^3*(y - 1)^4;|
+------------------------------------+
|i36 : fpt(f)                        |
|                                    |
|      1                             |
|o36 = -                             |
|      2                             |
|                                    |
|o36 : QQ                            |
+------------------------------------+
|i37 : fpt(f, AtOrigin => false)     |
|                                    |
|      1                             |
|o37 = -                             |
|      4                             |
|                                    |
|o37 : QQ                            |
+------------------------------------+

See also
========

  * compareFPT -- determine whether a number is less than,
    greater than, or equal to the F-pure threshold
  * isFPT -- checks whether a given rational number is the F-pure
    threshold
  * frobeniusNu -- computes the largest power of an ideal
    not contained in a specified Frobenius power

Ways to use fpt :
=================

  * "fpt(List,List)"
  * "fpt(RingElement)"

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

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

frobeniusNu -- computes the largest power of an ideal not contained in a specified Frobenius power
**************************************************************************************************

Synopsis
========

  * Usage:
        frobeniusNu(e, I, J)
        frobeniusNu(e, I)
        frobeniusNu(e, f, J)
        frobeniusNu(e, f)
  * Inputs:
      * e, an integer (Macaulay2Doc), the order of the Frobenius
        power to consider
      * I, an ideal (Macaulay2Doc), in a polynomial ring $R$ over
        a finite field of characteristic $p$
      * f, a ring element (Macaulay2Doc), in the polynomial
        ring $R$
      * J, an ideal (Macaulay2Doc), in the polynomial ring $R$; if
        omitted, J is assumed to be the ideal generated by the variables of $R$
  * Optional inputs (Macaulay2Doc),:
      * ContainmentTest => a symbol (Macaulay2Doc), default value
        null, specifies the manner in which to verify the containment of powers
        of I or f in J^{[p^e]}
      * AtOrigin => a Boolean value (Macaulay2Doc), default
        value true, if false, tells the function to take the minimum value over
        all possible maximal ideals J
      * ReturnList => a Boolean value (Macaulay2Doc), default
        value false, specifies whether to return the list
        \{\nu(1),\ldots,\nu(p^e)\}, as opposed to just \nu(p^e)
      * Search => a symbol (Macaulay2Doc), default value Binary,
        specifies the strategy to be used in the search for the largest power
        of I or f not contained in J^{[p^e]}
      * UseSpecialAlgorithms => a Boolean value (Macaulay2Doc),
        default value true, specifies whether to use special algorithms to
        compute the $F$-pure threshold of f, for certain special types of
        polynomials
      * Verbose => a Boolean value (Macaulay2Doc), default value
        false, requests verbose feedback, where \nu(1), \nu(p), \nu(p^2), etc.,
        are printed as they are computed
  * Outputs:
      * an integer (Macaulay2Doc), the largest integer \nu\ =
        \nu(p^e) such that I^{\nu} (or f^{\nu}, or I^{[\nu]}, depending on the
        arguments and options passed) is not contained in J^{[p^e]}
      * an infinite number (Macaulay2Doc), if I or f is
        not contained in the radical of $J$, or when AtOrigin => false, if I or
        f is a unit ideal
      * a list (Macaulay2Doc), containing \nu(p^i), for i =
        0,\ldots,e

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

Consider an element $f$ of a polynomial ring $R$ over a finite field of
characteristic $p$, and an ideal $J$ of this ring. If $f$ is contained in the
radical of $J$, then the command frobeniusNu(e,f,J) outputs the maximal
exponent $n$ such that $f^{ n}$ is not contained in the $p^e$-th Frobenius
power of $J$. More generally, if $I$ is an ideal contained in the radical of
$J$, then frobeniusNu(e,I,J) outputs the maximal integer exponent $n$ such that
$I^n$ is not contained in the $p^e$-th Frobenius power of $J$.

These numbers are denoted $\nu_f^J(p^e)$ and $\nu_I^J(p^e)$, respectively, in
the literature, and were originally defined in the paper $F$-thresholds and
Bernstein-Sato Polynomials, by Mustaţă, Takagi, and Watanabe.

+-------------------------------+
|i1 : R = ZZ/11[x,y];           |
+-------------------------------+
|i2 : I = ideal(x^2 + y^3, x*y);|
|                               |
|o2 : Ideal of R                |
+-------------------------------+
|i3 : J = ideal(x^2, y^3);      |
|                               |
|o3 : Ideal of R                |
+-------------------------------+
|i4 : frobeniusNu(1, I, J)      |
|                               |
|o4 = 24                        |
+-------------------------------+
|i5 : f = x*y*(x^2 + y^2);      |
+-------------------------------+
|i6 : frobeniusNu(3, f, J)      |
|                               |
|o6 = 1330                      |
+-------------------------------+

If $f$ or $I$ is zero, then frobeniusNu returns 0; if $f$ or $I$ is not
contained in the radical of $J$, frobeniusNu returns infinity.

+---------------------------+
|i7 : frobeniusNu(1, 0_R, J)|
|                           |
|o7 = 0                     |
+---------------------------+
|i8 : frobeniusNu(1, 1_R, J)|
|                           |
|o8 = infinity              |
|                           |
|o8 : InfiniteNumber        |
+---------------------------+

When the third argument is omitted, the ideal $J$ is assumed to be the
homogeneous maximal ideal of $R$.

+---------------------------------------+
|i9 : R = ZZ/17[x,y,z];                 |
+---------------------------------------+
|i10 : f = x^3 + y^4 + z^5;             |
+---------------------------------------+
|i11 : frobeniusNu(2, f)                |
|                                       |
|o11 = 220                              |
+---------------------------------------+
|i12 : frobeniusNu(2, f, ideal(x, y, z))|
|                                       |
|o12 = 220                              |
+---------------------------------------+

It is well known that if $q=p^e$ for some nonnegative integer $e$, then
$\nu_I^J(qp) = \nu_I^J(q) p + L$, where the error term $L$ is nonnegative, and
can be explicitly bounded from above in terms of $p$ and the number of
generators of $I$ and $J$ (e.g., $L$ is at most $p-1$ when $I$ is principal).
This implies that when searching for frobeniusNu(e,I,J), it is always safe to
start at $p$ times frobeniusNu(e-1,I,J), and one need not search too far past
this number, and suggests that the most efficient way to compute
frobeniusNu(e,I,J) is to compute, successively, frobeniusNu(i,I,J), for i =
0,\ldots,e. This is indeed how the computation is done in most cases.

If $M$ is the homogeneous maximal ideal of $R$ and $f$ is an element of $R$,
the numbers $\nu_f^M(p^e)$ determine and are determined by the $F$-pure
threshold of $f$ at the origin. Indeed, $\nu_f^M(p^e)$ is $p^e$ times the
truncation of the non-terminating base $p$ expansion of fpt($f$) at its
$e$^{th} spot. This fact is used to speed up the computations for certain
polynomials whose $F$-pure thresholds can be quickly computed via special
algorithms, namely diagonal polynomials, binomials, forms in two variables, and
polynomials whose factors are in simple normal crossing. This feature can be
disabled by setting the option UseSpecialAlgorithms (default value true) to
false.

+-----------------------------------------------------------+
|i13 : R = ZZ/17[x,y,z];                                    |
+-----------------------------------------------------------+
|i14 : f = x^3 + y^4 + z^5; -- a diagonal polynomial        |
+-----------------------------------------------------------+
|i15 : time frobeniusNu(3, f)                               |
|     -- used 0.00991867 seconds                            |
|                                                           |
|o15 = 3756                                                 |
+-----------------------------------------------------------+
|i16 : time frobeniusNu(3, f, UseSpecialAlgorithms => false)|
|     -- used 0.524531 seconds                              |
|                                                           |
|o16 = 3756                                                 |
+-----------------------------------------------------------+

The valid values for the option ContainmentTest are FrobeniusPower,
FrobeniusRoot, and StandardPower. The default value of this option depends on
what is passed to frobeniusNu. Indeed, by default, ContainmentTest is set to
FrobeniusRoot if frobeniusNu is passed a ring element $f$, and is set to
StandardPower if frobeniusNu is passed an ideal $I$. We describe the
consequences of setting ContainmentTest to each of these values below.

First, if ContainmentTest is set to StandardPower, then the ideal containments
checked when computing frobeniusNu(e,I,J) are verified directly. That is, the
standard power $I^n$ is first computed, and a check is then run to see if it is
contained in the $p^e$-th Frobenius power of $J$.

Alternately, if ContainmentTest is set to FrobeniusRoot, then the ideal
containments are verified using Frobenius Roots. That is, the $p^e$-th
Frobenius root of $I^n$ is first computed, and a check is then run to see if it
is contained in $J$. The output is unaffected, but this option often speeds up
computations, specially when a polynomial or principal ideal is passed as the
second argument.

+-----------------------------------------------------------------------------+
|i17 : R = ZZ/5[x,y,z];                                                       |
+-----------------------------------------------------------------------------+
|i18 : f = x^3 + y^3 + z^3 + x*y*z;                                           |
+-----------------------------------------------------------------------------+
|i19 : time frobeniusNu(4, f) -- ContainmentTest is set to FrobeniusRoot, by  |
|     -- used 0.340346 seconds                                                |
|                                                                             |
|o19 = 499                                                                    |
|-----------------------------------------------------------------------------|
|default                                                                      |
+-----------------------------------------------------------------------------+
|i20 : time frobeniusNu(4, f, ContainmentTest => StandardPower)               |
|     -- used 4.87446 seconds                                                 |
|                                                                             |
|o20 = 499                                                                    |
+-----------------------------------------------------------------------------+

Finally, when ContainmentTest is set to FrobeniusPower, then instead of
producing the invariant $\nu_I^J(p^e)$ as defined above, frobeniusNu instead
outputs the maximal integer $n$ such that the $n$^{th} (generalized) Frobenius
power of $I$ is not contained in the $p^e$-th Frobenius power of $J$. Here, the
$n$^{th} Frobenius power of $I$, when $n$ is a nonnegative integer, is as
defined in the paper Frobenius Powers by Hernández, Teixeira, and Witt, which
can be computed with the function frobeniusPower (TestIdeals),
from the TestIdeals,
package. In particular, frobeniusNu(e,I,J) and
frobeniusNu(e,I,J,ContainmentTest=>FrobeniusPower) need not agree. However,
they will agree when $I$ is a principal ideal.

+------------------------------------------------------------+
|i21 : R = ZZ/3[x,y];                                        |
+------------------------------------------------------------+
|i22 : M = ideal(x, y);                                      |
|                                                            |
|o22 : Ideal of R                                            |
+------------------------------------------------------------+
|i23 : frobeniusNu(3, M^5)                                   |
|                                                            |
|o23 = 10                                                    |
+------------------------------------------------------------+
|i24 : frobeniusNu(3, M^5, ContainmentTest => FrobeniusPower)|
|                                                            |
|o24 = 8                                                     |
+------------------------------------------------------------+

The function frobeniusNu works by searching through the list of potential
integers $n$ and checking containments of $I^n$ in the specified Frobenius
power of $J$. The way this search is approached is specified by the option
Search, which can be set to Binary (the default value) or Linear.

+-----------------------------------------------------------------------------+
|i25 : R = ZZ/5[x,y,z];                                                       |
+-----------------------------------------------------------------------------+
|i26 : f = x^2*y^4 + y^2*z^7 + z^2*x^8;                                       |
+-----------------------------------------------------------------------------+
|i27 : time frobeniusNu(5, f) -- uses binary search (default)                 |
|     -- used 1.09815 seconds                                                 |
|                                                                             |
|o27 = 1124                                                                   |
+-----------------------------------------------------------------------------+
|i28 : time frobeniusNu(5, f, Search => Linear)                               |
|     -- used 1.48548 seconds                                                 |
|                                                                             |
|o28 = 1124                                                                   |
+-----------------------------------------------------------------------------+
|i29 : M = ideal(x, y, z);                                                    |
|                                                                             |
|o29 : Ideal of R                                                             |
+-----------------------------------------------------------------------------+
|i30 : time frobeniusNu(2, M, M^2) -- uses binary search (default)            |
|     -- used 4.69694 seconds                                                 |
|                                                                             |
|o30 = 97                                                                     |
+-----------------------------------------------------------------------------+
|i31 : time frobeniusNu(2, M, M^2, Search => Linear) -- but linear search gets|
|     -- used 1.64294 seconds                                                 |
|                                                                             |
|o31 = 97                                                                     |
|-----------------------------------------------------------------------------|
|luckier                                                                      |
+-----------------------------------------------------------------------------+

The option AtOrigin (default value true) can be turned off to tell frobeniusNu
to effectively do the computation over all possible maximal ideals $J$ and take
the minimum.

+------------------------------------------+
|i32 : R = ZZ/7[x,y];                      |
+------------------------------------------+
|i33 : f = (x - 1)^3 - (y - 2)^2;          |
+------------------------------------------+
|i34 : frobeniusNu(1, f)                   |
|                                          |
|o34 = infinity                            |
|                                          |
|o34 : InfiniteNumber                      |
+------------------------------------------+
|i35 : frobeniusNu(1, f, AtOrigin => false)|
|                                          |
|o35 = 5                                   |
+------------------------------------------+

The option ReturnList (default value false) can be used to request that the
output be not only $\nu_I^J(p^e)$, but a list containing $\nu_I^J(p^i)$, for
$i=0,\ldots,e$.

+-------------------------------------------+
|i36 : R = ZZ/5[x,y,z];                     |
+-------------------------------------------+
|i37 : f = x^2*y^4 + y^2*z^7 + z^2*x^8;     |
+-------------------------------------------+
|i38 : frobeniusNu(5, f, ReturnList => true)|
|                                           |
|o38 = {0, 1, 8, 44, 224, 1124}             |
|                                           |
|o38 : List                                 |
+-------------------------------------------+

Alternatively, the option Verbose (default value false) can be used to request
that the values $\nu_I^J(p^i)$ ($i=0,\ldots,e$) be printed as they are
computed, to monitor the progress of the computation.

+-----------------------------------------------+
|i39 : frobeniusNu(5, f, Verbose => true)       |
|nuInternal: using comparison test FrobeniusRoot|
|ν(1) = 0                                      |
|ν(p^1) = 1                                    |
|ν(p^2) = 8                                    |
|ν(p^3) = 44                                   |
|ν(p^4) = 224                                  |
|ν(p^5) = 1124                                 |
|                                               |
|o39 = 1124                                     |
+-----------------------------------------------+

See also
========

  * fpt -- attempt to compute the F-pure threshold of a polynomial
    at the origin or globally

Ways to use frobeniusNu :
=========================

  * "frobeniusNu(ZZ,Ideal)"
  * "frobeniusNu(ZZ,Ideal,Ideal)"
  * "frobeniusNu(ZZ,RingElement)"
  * "frobeniusNu(ZZ,RingElement,Ideal)"

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

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

FrobeniusPower -- a valid value for the option ContainmentTest
**************************************************************

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

A valid value for the option ContainmentTest, specifying
that Frobenius powers be used when verifying containments of powers of ideals.

See also
========

  * ContainmentTest -- an option for the function
    frobeniusNu specifying the type of containment of powers of ideals to test
  * frobeniusNu -- computes the largest power of an ideal
    not contained in a specified Frobenius power

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

The object FrobeniusPower, is a symbol (Macaulay2Doc).

FrobeniusRoot -- a valid value for the option ContainmentTest
*************************************************************

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

A valid value for the option ContainmentTest, specifying
that Frobenius roots be used when verifying containments of powers of ideals.

See also
========

  * ContainmentTest -- an option for the function
    frobeniusNu specifying the type of containment of powers of ideals to test
  * frobeniusNu -- computes the largest power of an ideal
    not contained in a specified Frobenius power

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

The object FrobeniusRoot, is a symbol (Macaulay2Doc).

GlobalFrobeniusRoot -- a valid value for the option ContainmentTest
*******************************************************************

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

A valid value for the option ContainmentTest, specifying
that Frobenius roots be used, and not localized, when verifying containments of
powers of ideals. This is turned on by default if AtOrigin is set to false in
frobeniusNu.

See also
========

  * ContainmentTest -- an option for the function
    frobeniusNu specifying the type of containment of powers of ideals to test
  * frobeniusNu -- computes the largest power of an ideal
    not contained in a specified Frobenius power

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

The object GlobalFrobeniusRoot, is a symbol (Macaulay2Doc).

GuessStrategy -- an option for the function fpt to specify the criterion used for selecting numbers to check
************************************************************************************************************

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

In the computation of the $F$-pure threshold of a polynomial $f$, in nontrivial
cases and when no special algorithm is used, the function fpt, uses
frobeniusNu, to find a closed interval [$A$, $B$] that
contains the $F$-pure threshold of $f$. The subroutine guessFPT is then called,
to first check whether one of the endpoints $B$ or $A$ is the $F$-pure
threshold, and then to select rational numbers in the interval, and check how
they are positioned in relation to the $F$-pure threshold, using the function
compareFPT. The option GuessStrategy controls how this
selection of numbers is done.

We start by describing what happens when GuessStrategy is set to null, its
default value. First, a list of several rational numbers in the interval ($A$,
$B$) is created and, using the function decomposeFraction (TestIdeals),
from the TestIdeals,
package, each number $t$ in that list is written in the form $t = a$ /($p^b$
($p^c$ - 1)), where $p$ is the characteristic of the ambient ring. That list of
candidates is then sorted based on

1. Increasing "computational cost" $w_aa + w_bb + w_cc$, for certain weights
$w_a$, $w_b$, and $w_c$,

and then refined by

2. Increasing distance from the midpoint of the interval ($A$, $B$).

Once this sorting is done, the first number in the list is selected, see
compareFPT, is called, and the result of that comparison is used to
trim the list of candidates and narrow down the interval ($A$, $B$). This
process is iterated as many times as requested by the user, via the option
Attempts. If the supply of candidates runs low, more are produced.

The default weights currently used in Criterion 1 are $w_a =$ 0, $w_b =$ 1, and
$w_c =$ 1.5. With these choices, we believe Criterion 1 is likely to prioritize
numbers for which the computation of compareFPT, is most
efficient. Criterion 2, on the other hand, aims at partitioning the interval as
evenly as possible.

The option GuessStrategy allows the user to choose his or her own weights for
Criterion 1. In that case, the list is sorted based on Criterion 1 with the
user's weights, and then Criterion 1 with default weights and Criterion 2,
respectively, are used as tie breakers. For instance, if the user suspects that
the (minimal) denominator of the $F$-pure threshold is prime to the
characteristic $p$, then weights $w_a =$ 0, $w_b =$ 1, and $w_c =$ 0 might be a
reasonable choice to try to find that $F$-pure threshold with fewer trials.

+-----------------------------------------------------------------------------+
|i1 : R = ZZ/11[x,y];                                                         |
+-----------------------------------------------------------------------------+
|i2 : f = 6*x^6*y^7 + 8*x^4*y^7 + 8*x^3*y^7 + 6*x^6*y^3 + 5*x^5*y^4 +         |
|                                                                             |
|         6 7     4 7     3 7     6 3     5 4     3 6     3 5                 |
|o2 = - 5x y  - 3x y  - 3x y  - 5x y  + 5x y  + 4x y  + 4x y                  |
|                                                                             |
|o2 : R                                                                       |
|-----------------------------------------------------------------------------|
|4*x^3*y^6 +4*x^3*y^5                                                         |
+-----------------------------------------------------------------------------+
|i3 : fpt(f, Attempts => 5, DepthOfSearch => 3)                               |
|                                                                             |
|       29   317                                                              |
|o3 = {---, ----}                                                             |
|      122  1331                                                              |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+
|i4 : fpt(f, Attempts => 5, DepthOfSearch => 3, GuessStrategy => {0, 1, 0})   |
|                                                                             |
|      5                                                                      |
|o4 = --                                                                      |
|     21                                                                      |
|                                                                             |
|o4 : QQ                                                                      |
+-----------------------------------------------------------------------------+

The user may also pass his or her own "cost" functions, that may take as input
any of the following: the candidate rational number $t$, the pair ($p$, $t$),
where $p$ is the characteristic of the ambient ring, or ($p$, $a$, $b$, $c$),
where the integers $a$, $b$, and $c$ are as described above. The list of
candidates is then sorted first by increasing values of that function, and
Criteria 1 and 2, respectively, are used as tie breakers. For instance, if the
user suspects the $F$-pure threshold has a small denominator, then passing the
function denominator (Macaulay2Doc), may help find the answer
in fewer trials.

+----------------------------------------------------------------------------+
|i5 : R = ZZ/5[x,y];                                                         |
+----------------------------------------------------------------------------+
|i6 : f = x^3*y^11*(x + y)^8*(x^2 + y^3)^8;                                  |
+----------------------------------------------------------------------------+
|i7 : fpt(f, DepthOfSearch => 3, Attempts => 7)                              |
|                                                                            |
|       5   4                                                                |
|o7 = {--, --}                                                               |
|      96  75                                                                |
|                                                                            |
|o7 : List                                                                   |
+----------------------------------------------------------------------------+
|i8 : fpt(f, DepthOfSearch => 3, Attempts => 4, GuessStrategy => denominator)|
|                                                                            |
|      1                                                                     |
|o8 = --                                                                     |
|     19                                                                     |
|                                                                            |
|o8 : QQ                                                                     |
+----------------------------------------------------------------------------+

Functions with optional argument named GuessStrategy :
======================================================

  * "fpt(...,GuessStrategy=>...)" -- see fpt, -- attempt to compute
    the F-pure threshold of a polynomial at the origin or globally

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

The object GuessStrategy, is a symbol (Macaulay2Doc).

isFJumpingExponent -- whether a given number is an F-jumping exponent
*********************************************************************

Synopsis
========

  * Usage:
        isFJumpingExponent(t, f)
  * Inputs:
      * t, a number (Macaulay2Doc), a rational number candidate
        for $F$-jumping exponent of f
      * f, a ring element (Macaulay2Doc), in a
        $\mathbb{Q}$-Gorenstein ring of positive characteristic $p$, whose
        index is not divisible by $p$
  * Optional inputs (Macaulay2Doc),:
      * AssumeDomain => a Boolean value (Macaulay2Doc), default
        value true, indicates whether the ambient ring of f  is an integral
        domain
      * FrobeniusRootStrategy => a symbol (Macaulay2Doc), default
        value Substitution, passed to computations in the TestIdeals,
        package
      * AtOrigin => a Boolean value (Macaulay2Doc), default
        value false, tells the function whether to consider only the behavior
        at the origin
      * MaxCartierIndex => an integer (Macaulay2Doc), default value
        10, sets the maximum $\mathbb{Q}$-Gorenstein index to search for
      * QGorensteinIndex => an integer (Macaulay2Doc), default value
        0, specifies the $\mathbb{Q}$-Gorenstein index of the ring
      * Verbose => a Boolean value (Macaulay2Doc), default value
        false, whether the output is to be verbose
  * Outputs:
      * a Boolean value (Macaulay2Doc), reporting whether t is
        an $F$-jumping exponent of f

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

Consider a $\mathbb{Q}$-Gorenstein ring $R$ of characteristic $p>0$, of index
not divisible by $p$. Given an element $f$ of $R$ and a rational number $t$,
isFJumpingExponent(t, f) returns true if $t$ is an $F$-jumping exponent of $f$,
and otherwise it returns false.

+---------------------------------+
|i1 : R = ZZ/5[x,y];              |
+---------------------------------+
|i2 : f =  x^4 + y^3 + x^2*y^2;   |
+---------------------------------+
|i3 : isFJumpingExponent(7/12, f) |
|                                 |
|o3 = true                        |
+---------------------------------+
|i4 : isFJumpingExponent(4/5, f)  |
|                                 |
|o4 = true                        |
+---------------------------------+
|i5 : isFJumpingExponent(5/6, f)  |
|                                 |
|o5 = false                       |
+---------------------------------+
|i6 : isFJumpingExponent(11/12, f)|
|                                 |
|o6 = true                        |
+---------------------------------+

The ring $R$ below is singular, and the jumping numbers of $f$ in the open unit
interval are 1/4, 1/2 and 3/4.

+----------------------------------+
|i7 : R = ZZ/11[x,y,z]/(x*y - z^2);|
+----------------------------------+
|i8 : f = x^2;                     |
+----------------------------------+
|i9 : isFJumpingExponent(1/4, f)   |
|                                  |
|o9 = true                         |
+----------------------------------+
|i10 : isFJumpingExponent(3/8, f)  |
|                                  |
|o10 = false                       |
+----------------------------------+
|i11 : isFJumpingExponent(1/2, f)  |
|                                  |
|o11 = true                        |
+----------------------------------+
|i12 : isFJumpingExponent(2/3, f)  |
|                                  |
|o12 = false                       |
+----------------------------------+
|i13 : isFJumpingExponent(3/4, f)  |
|                                  |
|o13 = true                        |
+----------------------------------+

Setting the option AtOrigin to true (its default value is false) tells the
function to consider only $F$-jumping exponents at the origin. The following
example considers a polynomial that looks locally analytically like two lines
at the origin, and four lines at (2,0).

+------------------------------------------------------+
|i14 : R = ZZ/13[x,y];                                 |
+------------------------------------------------------+
|i15 : f = y*((y + 1) - (x - 1)^2)*(x - 2)*(x + y - 2);|
+------------------------------------------------------+
|i16 : isFJumpingExponent(3/4, f)                      |
|                                                      |
|o16 = true                                            |
+------------------------------------------------------+
|i17 : isFJumpingExponent(3/4, f, AtOrigin => true)    |
|                                                      |
|o17 = false                                           |
+------------------------------------------------------+

If the ambient ring $R$ is not a domain, the option AssumeDomain should be set
to false. We assume that the ring is a domain by default, in order to speed up
the computation.

If the Gorenstein index of $R$ is known, the user should set the option
QGorensteinIndex to this value. Otherwise, the function attempts to find the
Gorenstein index of $R$, assuming it is between 1 and the value passed to the
option MaxCartierIndex (default value 10).

The option FrobeniusRootStrategy is passed to internal calls of functions from
the TestIdeals, package. The two valid values of
FrobeniusRootStrategy are Substitution and MonomialBasis.

Setting the option Verbose (default value false) to true produces verbose
output.

See also
========

  * compareFPT -- determine whether a number is less than,
    greater than, or equal to the F-pure threshold
  * isFPT -- checks whether a given rational number is the F-pure
    threshold
  * fpt -- attempt to compute the F-pure threshold of a polynomial
    at the origin or globally

Ways to use isFJumpingExponent :
================================

  * "isFJumpingExponent(Number,RingElement)"

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

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

isFPT -- checks whether a given rational number is the F-pure threshold
***********************************************************************

Synopsis
========

  * Usage:
        isFPT(t, f)
  * Inputs:
      * t, a number (Macaulay2Doc), a rational number candidate
        for the $F$-pure threshold of f
      * f, a ring element (Macaulay2Doc), in a
        $\mathbb{Q}$-Gorenstein ring of positive characteristic $p$, whose
        index is not divisible by $p$
  * Optional inputs (Macaulay2Doc),:
      * AssumeDomain => a Boolean value (Macaulay2Doc), default
        value true, indicates whether the ambient ring of f is an integral
        domain
      * FrobeniusRootStrategy => a symbol (Macaulay2Doc), default
        value Substitution, passed to computations in the TestIdeals,
        package
      * AtOrigin => a Boolean value (Macaulay2Doc), default
        value false, tells the function whether to consider only the behavior
        at the origin
      * MaxCartierIndex => an integer (Macaulay2Doc), default value
        10, sets the maximum $\mathbb{Q}$-Gorenstein index to search for
      * QGorensteinIndex => an integer (Macaulay2Doc), default value
        0, specifies the $\mathbb{Q}$-Gorenstein index of the ring
      * Verbose => a Boolean value (Macaulay2Doc), default value
        false, whether the output is to be verbose
  * Outputs:
      * a Boolean value (Macaulay2Doc), reporting whether t is
        the $F$-pure threshold of f

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

Consider an element $f$ of a $\mathbb{Q}$-Gorenstein ring of positive
characteristic $p$ (of $\mathbb{Q}$-Gorenstein index not divisible by $p$), and
a rational number $t$. If $t$ is the $F$-pure threshold of $f$, then the
command isFPT(t, f) outputs true, and otherwise, it outputs false.

+--------------------+
|i1 : R = ZZ/11[x,y];|
+--------------------+
|i2 : f = x^3 + y^2; |
+--------------------+
|i3 : isFPT(9/11, f) |
|                    |
|o3 = true           |
+--------------------+
|i4 : isFPT(9/12, f) |
|                    |
|o4 = false          |
+--------------------+

We also include an example in a singular ambient ring.

+---------------------------------------------+
|i5 : T = ZZ/7[a,b];                          |
+---------------------------------------------+
|i6 : S = ZZ/7[x,y,z,w];                      |
+---------------------------------------------+
|i7 : f = map(T, S, {a^3, a^2*b, a*b^2, b^3});|
|                                             |
|o7 : RingMap T <--- S                        |
+---------------------------------------------+
|i8 : R = S/ker f;                            |
+---------------------------------------------+
|i9 : isFPT(1/3, x)                           |
|                                             |
|o9 = true                                    |
+---------------------------------------------+
|i10 : isFPT(1/3 + 1/10000, x)                |
|                                             |
|o10 = false                                  |
+---------------------------------------------+
|i11 : isFPT(1/3 - 1/10000, x)                |
|                                             |
|o11 = false                                  |
+---------------------------------------------+

Setting the AtOrigin option to true (its default value is false) tells the
function to consider the $F$-pure threshold at the origin.

+-----------------------------------------+
|i12 : R = ZZ/11[x,y,z]/(x^2 - y*(z - 1));|
+-----------------------------------------+
|i13 : isFPT(1/2, z - 1)                  |
|                                         |
|o13 = true                               |
+-----------------------------------------+
|i14 : isFPT(1/2, z - 1, AtOrigin => true)|
|                                         |
|o14 = false                              |
+-----------------------------------------+

If the ambient ring $R$ is not a domain, the option AssumeDomain should be set
to false. We assume that the ring is a domain by default, in order to speed up
the computation.

If the Gorenstein index of $R$ is known, the user should set the option
QGorensteinIndex to this value. Otherwise, the function attempts to find the
Gorenstein index of $R$, assuming it is between 1 and the value passed to the
option MaxCartierIndex (default value 10).

The option FrobeniusRootStrategy is passed to internal calls of functions from
the TestIdeals, package. The two valid values of
FrobeniusRootStrategy are Substitution and MonomialBasis.

Setting the option Verbose (default value false) to true produces verbose
output.

See also
========

  * compareFPT -- determine whether a number is less than,
    greater than, or equal to the F-pure threshold
  * fpt -- attempt to compute the F-pure threshold of a polynomial
    at the origin or globally
  * isFJumpingExponent -- whether a given number is
    an F-jumping exponent

Ways to use isFPT :
===================

  * "isFPT(Number,RingElement)"

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

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

isSimpleNormalCrossing -- whether a polynomial is a product of factors that are in simple normal crossing
*********************************************************************************************************

Synopsis
========

  * Usage:
        isSimpleNormalCrossing(f)
        isSimpleNormalCrossing(P)
  * Inputs:
      * f, a ring element (Macaulay2Doc), a polynomial
      * P, a product expression (Macaulay2Doc), a product of
        polynomials
  * Optional inputs (Macaulay2Doc),:
      * AtOrigin => a Boolean value (Macaulay2Doc), default
        value true, tells the function whether to consider only the behavior at
        the origin
      * Verbose => a Boolean value (Macaulay2Doc), default value
        false, whether the output is to be verbose
  * Outputs:
      * a Boolean value (Macaulay2Doc), true if the factors of f
        are in simple normal crossing, false otherwise

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

Let $f$ be a polynomial or an object of class Product representing a
factorization of a  polynomial $f$. The function isSimpleNormalCrossing returns
true if the distinct factors of $f$ are in simple normal crossing, or in other
words, if at each point those factors, locally analytically, form part of a
regular system of parameters.

+----------------------------------------+
|i1 : R = ZZ/7[x,y,z];                   |
+----------------------------------------+
|i2 : isSimpleNormalCrossing(x^3*y^2)    |
|                                        |
|o2 = true                               |
+----------------------------------------+
|i3 : isSimpleNormalCrossing(x^2 - y^2)  |
|                                        |
|o3 = true                               |
+----------------------------------------+
|i4 : isSimpleNormalCrossing(x*y*(x - y))|
|                                        |
|o4 = false                              |
+----------------------------------------+
|i5 : isSimpleNormalCrossing(x^2 - y*z)  |
|                                        |
|o5 = false                              |
+----------------------------------------+

The option AtOrigin (default value true) is used to specify whether to work at
the origin (when true) or globally (when false).

+-----------------------------------------------------------------------+
|i6 : R = QQ[x,y,z];                                                    |
+-----------------------------------------------------------------------+
|i7 : f = (y - (x - 1)^2)*y^2; --SNC at the origin, but not globally    |
+-----------------------------------------------------------------------+
|i8 : isSimpleNormalCrossing(f)                                         |
|                                                                       |
|o8 = true                                                              |
+-----------------------------------------------------------------------+
|i9 : isSimpleNormalCrossing(f, AtOrigin => false)                      |
|                                                                       |
|o9 = false                                                             |
+-----------------------------------------------------------------------+
|i10 : g = (y - 1)^2 + (x - 7)^2; --doesn't even pass through the origin|
+-----------------------------------------------------------------------+
|i11 : isSimpleNormalCrossing(g)                                        |
|                                                                       |
|o11 = true                                                             |
+-----------------------------------------------------------------------+
|i12 : isSimpleNormalCrossing(g, AtOrigin => false)                     |
|                                                                       |
|o12 = false                                                            |
+-----------------------------------------------------------------------+
|i13 : h = x*y^2*(x + 1)^3*(y - 1)^4; --SNC everywhere                  |
+-----------------------------------------------------------------------+
|i14 : isSimpleNormalCrossing(h)                                        |
|                                                                       |
|o14 = true                                                             |
+-----------------------------------------------------------------------+
|i15 : isSimpleNormalCrossing(h, AtOrigin => false)                     |
|                                                                       |
|o15 = true                                                             |
+-----------------------------------------------------------------------+

Setting the option Verbose (default value false) to true produces verbose
output.

Ways to use isSimpleNormalCrossing :
====================================

  * "isSimpleNormalCrossing(Product)"
  * "isSimpleNormalCrossing(RingElement)"

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

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

ReturnList -- an option for the function frobeniusNu to return a list of successive nu values
*********************************************************************************************

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

An option for the function frobeniusNu, specifying whether
to return all nu values up to the given order. Takes on Boolean values; default
value is false.

Functions with optional argument named ReturnList :
===================================================

  * "frobeniusNu(...,ReturnList=>...)" -- see frobeniusNu,
    -- computes the largest power of an ideal not contained in a specified
    Frobenius power

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

The object ReturnList, is a symbol (Macaulay2Doc).

Search -- an option for the function frobeniusNu to specify the search method for testing containments of powers of ideals
**************************************************************************************************************************

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

An option for the function frobeniusNu, that specifies the
search algorithm to be used. Valid values are Binary and Linear; default value
is Binary.

Functions with optional argument named Search :
===============================================

  * "frobeniusNu(...,Search=>...)" -- see frobeniusNu, --
    computes the largest power of an ideal not contained in a specified
    Frobenius power

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

The object Search, is a symbol (Macaulay2Doc).

StandardPower -- a valid value for the option ContainmentTest
*************************************************************

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

A valid value for the option ContainmentTest,
specifying that when verifying containments of powers of ideals, to check
whether the standard power of an ideal is contained in the Frobenius power of
another ideal.

See also
========

  * ContainmentTest -- an option for the function
    frobeniusNu specifying the type of containment of powers of ideals to test
  * frobeniusNu -- computes the largest power of an ideal
    not contained in a specified Frobenius power

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

The object StandardPower, is a symbol (Macaulay2Doc).

UseSpecialAlgorithms -- an option for the functions fpt and frobeniusNu to use special algorithms to speed up computations
**************************************************************************************************************************

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

An option for the functions fpt, and frobeniusNu.
Takes on Boolean values; default value is true, in both
functions.

If this option is set to true in fpt, that function checks whether
the input is a diagonal polynomial, a binomial, a product of factors in simple
normal crossing, or a form in two variables, in which case specialized
algorithms or formulas are used.

If set to true in frobeniusNu, that function checks whether
the input is one of the above special types of polynomials, in which case it
computes the $F$-pure threshold of the polynomial, and uses the $F$-pure
threshold to compute the nu invariant.

Functions with optional argument named UseSpecialAlgorithms :
=============================================================

  * "fpt(...,UseSpecialAlgorithms=>...)" -- see fpt, -- attempt to
    compute the F-pure threshold of a polynomial at the origin or globally
  * "frobeniusNu(...,UseSpecialAlgorithms=>...)" -- see frobeniusNu,
    -- computes the largest power of an ideal not contained in a
    specified Frobenius power

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

The object UseSpecialAlgorithms, is a symbol (Macaulay2Doc).