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

TestIdeals -- a package for calculations of singularities in positive characteristic
*************************************************************************************

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

TestIdeals is a package for basic computations of $F$-singularities. It is
focused on computing test ideals and related objects. It does this via
frobeniusRoot, which computes $I^{[1/p^e]}$, as introduced by
Blickle-Mustata-Smith (this is equivalent to the image of an ideal under the
Cartier operator in a polynomial ring).

Notable functions:
  * testIdeal, computes the test ideal of a normal
    \mathbb{Q}-Gorenstein ring or pair.
  * testModule, computes the parameter test module of a ring
    or pair.
  * parameterTestIdeal, computes the parameter test
    ideal of a Cohen-Macaulay ring.
  * FPureModule, computes the stable image of the trace of
    Frobenius on the canonical module.
  * isFRegular, checks if a normal \mathbb{Q}-Gorenstein ring
    or pair is $F$-regular.
  * isFPure, checks if a ring is $F$-pure.
  * isFRational, checks if a  ring is $F$-rational.
  * isFInjective, checks if a  ring is $F$-injective.
  * compatibleIdeals, finds the compatibly $F$-split
    ideals with a (near) $F$-splitting.

Consider, for instance, the test ideal of the cone over an elliptic curve.
+-------------------------------------------------+
|i1 : R = ZZ/5[x,y,z]/(z*y^2 - x*(x - z)*(x + z));|
+-------------------------------------------------+
|i2 : testIdeal(R)                                |
|                                                 |
|o2 = ideal (z, y, x)                             |
|                                                 |
|o2 : Ideal of R                                  |
+-------------------------------------------------+

The following example was studied by Anurag Singh when showing that
$F$-regularity does not deform.
+------------------------------------------------------+
|i3 : S = ZZ/3[A,B,C,D,T];                             |
+------------------------------------------------------+
|i4 : M = matrix{{A^2 + T^4, B, D}, {C, A^2, B^3 - D}};|
|                                                      |
|             2      3                                 |
|o4 : Matrix S  <-- S                                  |
+------------------------------------------------------+
|i5 : I = ideal(T) + minors(2, M);                     |
|                                                      |
|o5 : Ideal of S                                       |
+------------------------------------------------------+
|i6 : isFRegular(S/I)                                  |
|                                                      |
|o6 = 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.

Authors
=======

  * Erin Bela <ebela@nd.edu>
  * Alberto F. Boix <albertof.boix@gmail.com>
  * Juliette Bruce (see https://juliettebruce.github.io/ )
    <juliette.bruce@math.wisc.edu>
  * Drew Ellingson <drewtell@umich.edu>
  * Daniel Hernández (see https://hernandez.faculty.ku.edu ) <hernandez@ku.edu>
  * Zhibek Kadyrsizova <zhikadyr@umich.edu>
  * Mordechai Katzman (see http://www.katzman.staff.shef.ac.uk/ )
    <m.katzman@sheffield.ac.uk>
  * Sara Malec <malec@hood.edu>
  * Matthew Mastroeni (see https://mnmastro.github.io/ ) <mmastro@okstate.edu>
  * Maral Mostafazadehfard <maralmostafazadehfard@gmail.com>
  * Marcus Robinson <robinson@math.utah.edu>
  * Karl Schwede (see http://math.utah.edu/~schwede/ ) <schwede@math.utah.edu>
  * Dan Smolkin (see http://cohenmacaulay.life ) <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 1.01 of this package was accepted for publication in volume 9 (see
https://msp.org/jsag/2019/9-2/ ) of The Journal of Software for Algebra and
Geometry (see https://msp.org/jsag/ ) on 19 July 2019, in the article The
TestIdeals package for Macaulay2 (see https://msp.org/jsag/2019/9-2/p01.xhtml )
(DOI: 10.2140/jsag.2019.9.89 (see https://doi.org/10.2140/jsag.2019.9.89 )).
That version can be obtained from the journal (see
https://msp.org/jsag/2019/9-2/jsag-v9-n2-x01-TestIdeals.zip ).

Version
=======

This documentation describes version 1.01 of TestIdeals, released 3/22/2019,
2019.

Citation
========

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

+-----------------------------------------------------------------------------+
|@misc{TestIdealsSource,                                                      |
|  title = {{TestIdeals: singularities in positive characteristic.            |
|  author = {Erin Bela and Alberto F. Boix and Juliette Bruce and             |
|  howpublished = {A \emph{Macaulay2} package available at                    |
|    \url{https://github.com/Macaulay2/M2/tree/stable/M2/Macaulay2            |
|}                                                                            |
|                                                                             |
|@article{TestIdealsArticle,                                                  |
|  title = {{The TestIdeals package for \emph{Macaulay2}}},                   |
|  author = {Erin Bela and Alberto F. Boix and Juliette Bruce and             |
|  journal = {The Journal of Software for Algebra and Geometry},              |
|  volume = {9},                                                              |
|  year = {2019},                                                             |
|}                                                                            |
|-----------------------------------------------------------------------------|
| Version~1.01}},                                                             |
|Drew Ellingson and Daniel Hern{\'a}ndez and Zhibek Kadyrsizova and Mordechai |
|                                                                             |
|/packages}}                                                                  |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|Drew Ellingson and Daniel Hern{\'a}ndez and Zhibek Kadyrsizova and Mordechai |
|-----------------------------------------------------------------------------|
|Katzman and Sara Malec and Matthew Mastroeni and Maral Mostafazadehfard and  |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|Katzman and Sara Malec and Matthew Mastroeni and Maral Mostafazadehfard and  |
|-----------------------------------------------------------------------------|
|Marcus Robinson and Karl Schwede and Dan Smolkin and Pedro Teixeira and Emily|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|Marcus Robinson and Karl Schwede and Dan Smolkin and Pedro Teixeira and Emily|
|-----------------------------------------------------------------------------|
|Witt},                                                                       |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|Witt},                                                                       |
+-----------------------------------------------------------------------------+

Exports
=======

  * Functions and commands
      * adicDigit -- compute a digit of the non-terminating
        expansion of a number in the unit interval in a given base
      * adicExpansion -- compute adic expansion
      * adicTruncation -- truncation of a
        non-terminating adic expansion
      * ascendIdeal -- find the smallest ideal containing a
        given ideal which is compatible with a given Cartier linear map
      * ascendModule -- find the smallest submodule of
        free module containing a given submodule which is compatible with a
        given Cartier linear map
      * canonicalIdeal -- produce an ideal isomorphic to
        the canonical module of a ring
      * compatibleIdeals -- find all prime ideals
        compatible with a Frobenius near-splitting
      * decomposeFraction -- decompose a rational
        number
      * descendIdeal -- finds the maximal F-pure Cartier
        submodule of an ideal viewed as a Cartier module
      * floorLog -- floor of a logarithm
      * FPureModule -- compute the submodule of the
        canonical module stable under the image of the trace of Frobenius
      * frobenius -- compute a Frobenius power of an ideal or
        a matrix
      * frobeniusPower -- compute a (generalized)
        Frobenius power of an ideal
      * frobeniusPreimage -- finds the ideal of
        elements mapped into a given ideal, under all $p^{-e}$-linear maps
      * frobeniusRoot -- compute a Frobenius root
      * frobeniusTraceOnCanonicalModule,
        -- find an element of a polynomial ring that determines the Frobenius
        trace on the canonical module of a quotient of that ring
      * isCohenMacaulay -- whether a ring is
        Cohen-Macaulay
      * isFInjective -- whether a ring is F-injective
      * isFPure -- whether a ring is F-pure
      * isFRational -- whether a ring is F-rational
      * isFRegular -- whether a ring or pair is strongly
        F-regular
      * multiplicativeOrder -- multiplicative order
        of an integer modulo another
      * parameterTestIdeal -- compute the parameter
        test ideal of a Cohen-Macaulay ring
      * QGorensteinGenerator -- find an element
        representing the Frobenius trace map of a Q-Gorenstein ring
      * testElement -- find a test element of a ring
      * testIdeal -- compute a test ideal in a Q-Gorenstein
        ring
      * testModule -- find the parameter test module of a
        reduced ring
  * Methods
      * "adicDigit(ZZ,ZZ,List)" -- see adicDigit, -- compute a
        digit of the non-terminating expansion of a number in the unit interval
        in a given base
      * "adicDigit(ZZ,ZZ,QQ)" -- see adicDigit, -- compute a
        digit of the non-terminating expansion of a number in the unit interval
        in a given base
      * "adicDigit(ZZ,ZZ,ZZ)" -- see adicDigit, -- compute a
        digit of the non-terminating expansion of a number in the unit interval
        in a given base
      * "adicExpansion(ZZ,ZZ)" -- see adicExpansion, --
        compute adic expansion
      * "adicExpansion(ZZ,ZZ,QQ)" -- see adicExpansion, --
        compute adic expansion
      * "adicExpansion(ZZ,ZZ,ZZ)" -- see adicExpansion, --
        compute adic expansion
      * "adicTruncation(ZZ,ZZ,List)" -- see adicTruncation,
        -- truncation of a non-terminating adic expansion
      * "adicTruncation(ZZ,ZZ,QQ)" -- see adicTruncation,
        -- truncation of a non-terminating adic expansion
      * "adicTruncation(ZZ,ZZ,ZZ)" -- see adicTruncation,
        -- truncation of a non-terminating adic expansion
      * "ascendIdeal(ZZ,List,List,Ideal)" -- see ascendIdeal,
        -- find the smallest ideal containing a given ideal which
        is compatible with a given Cartier linear map
      * "ascendIdeal(ZZ,RingElement,Ideal)" -- see ascendIdeal,
        -- find the smallest ideal containing a given ideal which
        is compatible with a given Cartier linear map
      * "ascendIdeal(ZZ,ZZ,RingElement,Ideal)" -- see ascendIdeal,
        -- find the smallest ideal containing a given ideal which
        is compatible with a given Cartier linear map
      * "ascendModule(ZZ,Matrix,Matrix)" -- see ascendModule,
        -- find the smallest submodule of free module containing
        a given submodule which is compatible with a given Cartier linear map
      * "ascendModule(ZZ,Module,Matrix)" -- see ascendModule,
        -- find the smallest submodule of free module containing
        a given submodule which is compatible with a given Cartier linear map
      * "canonicalIdeal(Ring)" -- see canonicalIdeal, --
        produce an ideal isomorphic to the canonical module of a ring
      * "compatibleIdeals(RingElement)" -- see compatibleIdeals,
        -- find all prime ideals compatible with a Frobenius
        near-splitting
      * "decomposeFraction(ZZ,QQ)" -- see decomposeFraction,
        -- decompose a rational number
      * "decomposeFraction(ZZ,ZZ)" -- see decomposeFraction,
        -- decompose a rational number
      * "descendIdeal(ZZ,List,List,Ideal)" -- see descendIdeal,
        -- finds the maximal F-pure Cartier submodule of an ideal
        viewed as a Cartier module
      * "floorLog(Number,Number)" -- see floorLog, -- floor of
        a logarithm
      * "FPureModule(List,List)" -- see FPureModule, --
        compute the submodule of the canonical module stable under the image of
        the trace of Frobenius
      * "FPureModule(Number,RingElement)" -- see FPureModule,
        -- compute the submodule of the canonical module stable
        under the image of the trace of Frobenius
      * "FPureModule(Ring)" -- see FPureModule, -- compute
        the submodule of the canonical module stable under the image of the
        trace of Frobenius
      * "frobeniusPower(QQ,Ideal)" -- see frobeniusPower,
        -- compute a (generalized) Frobenius power of an ideal
      * "frobeniusPower(ZZ,Ideal)" -- see frobeniusPower,
        -- compute a (generalized) Frobenius power of an ideal
      * "frobeniusPreimage(ZZ,Ideal)" -- see frobeniusPreimage,
        -- finds the ideal of elements mapped into a given
        ideal, under all $p^{-e}$-linear maps
      * "frobeniusRoot(ZZ,Ideal)" -- see frobeniusRoot, --
        compute a Frobenius root
      * "frobeniusRoot(ZZ,List,List)" -- see frobeniusRoot,
        -- compute a Frobenius root
      * "frobeniusRoot(ZZ,List,List,Ideal)" -- see frobeniusRoot,
        -- compute a Frobenius root
      * "frobeniusRoot(ZZ,Matrix)" -- see frobeniusRoot,
        -- compute a Frobenius root
      * "frobeniusRoot(ZZ,Module)" -- see frobeniusRoot,
        -- compute a Frobenius root
      * "frobeniusRoot(ZZ,MonomialIdeal)" -- see frobeniusRoot,
        -- compute a Frobenius root
      * "frobeniusRoot(ZZ,ZZ,Ideal)" -- see frobeniusRoot,
        -- compute a Frobenius root
      * "frobeniusRoot(ZZ,ZZ,RingElement)" -- see frobeniusRoot,
        -- compute a Frobenius root
      * "frobeniusRoot(ZZ,ZZ,RingElement,Ideal)" -- see frobeniusRoot,
        -- compute a Frobenius root
      * "frobeniusTraceOnCanonicalModule(Ideal,Ideal)" -- see
        frobeniusTraceOnCanonicalModule, --
        find an element of a polynomial ring that determines the Frobenius
        trace on the canonical module of a quotient of that ring
      * "isCohenMacaulay(Ring)" -- see isCohenMacaulay,
        -- whether a ring is Cohen-Macaulay
      * "isFInjective(Ring)" -- see isFInjective, --
        whether a ring is F-injective
      * "isFPure(Ideal)" -- see isFPure, -- whether a ring is
        F-pure
      * "isFPure(Ring)" -- see isFPure, -- whether a ring is
        F-pure
      * "isFRational(Ring)" -- see isFRational, -- whether a
        ring is F-rational
      * "isFRegular(List,List)" -- see isFRegular, -- whether
        a ring or pair is strongly F-regular
      * "isFRegular(Number,RingElement)" -- see isFRegular,
        -- whether a ring or pair is strongly F-regular
      * "isFRegular(Ring)" -- see isFRegular, -- whether a
        ring or pair is strongly F-regular
      * "multiplicativeOrder(ZZ,ZZ)" -- see multiplicativeOrder,
        -- multiplicative order of an integer modulo
        another
      * "parameterTestIdeal(Ring)" -- see parameterTestIdeal,
        -- compute the parameter test ideal of a
        Cohen-Macaulay ring
      * "QGorensteinGenerator(Ring)" -- see QGorensteinGenerator,
        -- find an element representing the Frobenius
        trace map of a Q-Gorenstein ring
      * "QGorensteinGenerator(ZZ,Ring)" -- see QGorensteinGenerator,
        -- find an element representing the Frobenius
        trace map of a Q-Gorenstein ring
      * "testElement(Ring)" -- see testElement, -- find a
        test element of a ring
      * "testIdeal(List,List)" -- see testIdeal, -- compute a
        test ideal in a Q-Gorenstein ring
      * "testIdeal(Number,RingElement)" -- see testIdeal, --
        compute a test ideal in a Q-Gorenstein ring
      * "testIdeal(Ring)" -- see testIdeal, -- compute a test
        ideal in a Q-Gorenstein ring
      * "testModule(List,List)" -- see testModule, -- find
        the parameter test module of a reduced ring
      * "testModule(Number,RingElement)" -- see testModule,
        -- find the parameter test module of a reduced ring
      * "testModule(Ring)" -- see testModule, -- find the
        parameter test module of a reduced ring
  * Symbols
      * AscentCount -- an option for ascendIdeal
      * AssumeCM -- an option to assume a ring is
        Cohen-Macaulay
      * AssumeDomain -- an option to assume a ring is a
        domain
      * AssumeNormal -- an option to assume a ring is
        normal
      * AssumeReduced -- an option to assume a ring is
        reduced
      * AtOrigin -- an option used to specify whether to only
        work locally
      * CanonicalIdeal -- an option to specify that a
        certain ideal be used as the canonical ideal
      * CanonicalStrategy -- an option for
        isFInjective
      * CurrentRing -- an option to specify that a certain
        ring is used
      * DepthOfSearch -- an option to specify how hard to
        search for something
      * FrobeniusPowerStrategy -- an option for
        frobeniusPower
      * FrobeniusRootStrategy -- an option for
        various functions
      * GeneratorList -- an option to specify that a
        certain list of elements is used to describe a Cartier action
      * Katzman -- a valid value for the option
        CanonicalStrategy
      * MaxCartierIndex -- an option to specify the
        maximum number to consider when computing the Cartier index of a
        divisor
      * MonomialBasis -- a valid value for the option
        FrobeniusRootStrategy
      * Naive -- a valid value for the option
        FrobeniusPowerStrategy
      * NoZeroC -- an option for decomposeFraction
      * QGorensteinIndex -- an option to specify the
        index of the canonical divisor, if known
      * Safe -- a valid value for the option
        FrobeniusPowerStrategy
      * Substitution -- a valid value for the option
        FrobeniusRootStrategy

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

The object TestIdeals, is a package (Macaulay2Doc),
defined in TestIdeals.m2, with auxiliary files in TestIdeals/.

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

The source of this document is in TestIdeals/TestIdealDoc.m2:41:0.

adicDigit -- compute a digit of the non-terminating expansion of a number in the unit interval in a given base
**************************************************************************************************************

  * Usage:
        d = adicDigit(p, e, x)
        D = adicDigit(p, e, L)
  * Inputs:
      * p, an integer (Macaulay2Doc), greater than 1; the desired
        base
      * e, an integer (Macaulay2Doc), positive, which specifies which
        digit is desired
      * x, a rational number (Macaulay2Doc), in the interval [0,1];
        the number whose digit is to be computed
      * L, a list (Macaulay2Doc), consisting of rational numbers in
        the interval [0,1] whose digits are to be computed
  * Outputs:
      * d, an integer (Macaulay2Doc), the e^{th} digit of the base p
        expansion of x
      * D, a list (Macaulay2Doc), consisting of the e^{th} digits
        of the base p expansions of the elements of L

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

The command adicDigit(p, e, 0) returns 0. If $x$ is a rational number in the
interval (0,1], then adicDigit(p, e, x) returns the coefficient of $p^{-e}$ in
the non-terminating base $p$ expansion of $x$.

+-------------------------+
|i1 : adicDigit(5, 4, 1/3)|
|                         |
|o1 = 3                   |
+-------------------------+

If $L$ is a list of rational numbers in the unit interval, adicDigit(p, e, L)
returns a list containing the $e^{th}$ digits (base $p$) of the elements of
$L$.

+-------------------------------------+
|i2 : adicDigit(5, 4, {1/3, 1/7, 2/3})|
|                                     |
|o2 = {3, 4, 1}                       |
|                                     |
|o2 : List                            |
+-------------------------------------+

See also
========

  * adicExpansion -- compute adic expansion
  * adicTruncation -- truncation of a non-terminating
    adic expansion

Ways to use adicDigit:
======================

  * "adicDigit(ZZ,ZZ,List)"
  * "adicDigit(ZZ,ZZ,QQ)"
  * "adicDigit(ZZ,ZZ,ZZ)"

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

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

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

The source of this document is in TestIdeals/BasicFunctionsDoc.m2:47:0.

adicExpansion -- compute adic expansion
***************************************

  * Usage:
        L1 = adicExpansion(p, N)
        L2 = adicExpansion(p, e, x)
  * Inputs:
      * p, an integer (Macaulay2Doc), greater than 1; the desired
        base
      * N, an integer (Macaulay2Doc), positive; the number whose base
        $p$ expansion is to be computed
      * e, an integer (Macaulay2Doc), positive, which specifies how
        many digits are to be computed
      * x, a rational number (Macaulay2Doc), in the interval [0,1];
        the number whose base p expansion is to be computed
  * Outputs:
      * L1, a list (Macaulay2Doc), consisting of all digits of the
        terminating base p expansion of N
      * L2, a list (Macaulay2Doc), consisting of the first e digits
        of the non-terminating base p expansion of x

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

adicExpansion(p, 0) returns \{0\}. If $N$ is nonzero, then adicExpansion(p, N)
returns a list in which the $i^{th}$ element is the coefficient of $p^{i-1}$ in
the base $p$ expansion of $N$.

+--------------------------------+
|i1 : 38 == 3*5^0 + 2*5^1 + 1*5^2|
|                                |
|o1 = true                       |
+--------------------------------+
|i2 : adicExpansion(5, 38)       |
|                                |
|o2 = {3, 2, 1}                  |
|                                |
|o2 : List                       |
+--------------------------------+

adicExpansion(p, e, 0) returns a list with $e$ elements, all of which are zero.
If $x$ is nonzero, then adicExpansion(p, e, x) returns a list with $e$ elements
in which the $i^{th}$ element is the coefficient of $p^{-i}$ in the unique
nonterminating base $p$ expansion of $x$. For example, the non-terminating base
$3$ expansion of $1/5$ is $1/5 = 0/3 + 1/9 + 2/27 + 1/81 + 0/243 + 1/729 +
\cdots$, and so adicExpansion(3, 6, 1/5) returns the digits $0$, $1$, $2$, $1$,
$0$, and $1$.

+-----------------------------+
|i3 : adicExpansion(3, 6, 1/5)|
|                             |
|o3 = {0, 1, 2, 1, 0, 1}      |
|                             |
|o3 : List                    |
+-----------------------------+

See also
========

  * adicDigit -- compute a digit of the non-terminating
    expansion of a number in the unit interval in a given base
  * adicTruncation -- truncation of a non-terminating
    adic expansion

Ways to use adicExpansion:
==========================

  * "adicExpansion(ZZ,ZZ)"
  * "adicExpansion(ZZ,ZZ,QQ)"
  * "adicExpansion(ZZ,ZZ,ZZ)"

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

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

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

The source of this document is in TestIdeals/BasicFunctionsDoc.m2:90:0.

adicTruncation -- truncation of a non-terminating adic expansion
****************************************************************

  * Usage:
        t = adicTruncation(p, e, r)
        T = adicTruncation(p, e, L)
  * Inputs:
      * p, an integer (Macaulay2Doc), greater than 1; the desired
        base
      * e, an integer (Macaulay2Doc), nonnegative, which specifies
        where to truncate
      * r, a rational number (Macaulay2Doc), nonnegative; the number
        whose truncation is to be computed
      * L, a list (Macaulay2Doc), containing nonnegative rational
        numbers whose truncations are to be computed
  * Outputs:
      * t, a rational number (Macaulay2Doc), the e^{th} truncation of
        r (base p)
      * T, a list (Macaulay2Doc), containing the e^{th} truncations
        (base p) of the elements of L

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

This function computes the $e^{th}$ truncation of the unique non-terminating
$p$-adic expansion of a positive rational number $r$.

+---------------------------------+
|i1 : adicTruncation(5, 2, 1/100) |
|                                 |
|o1 = 0                           |
|                                 |
|o1 : QQ                          |
+---------------------------------+
|i2 : adicTruncation(5, 4, 1/100) |
|                                 |
|      6                          |
|o2 = ---                         |
|     625                         |
|                                 |
|o2 : QQ                          |
+---------------------------------+
|i3 : adicTruncation(5, 5, 1/1000)|
|                                 |
|       3                         |
|o3 = ----                        |
|     3125                        |
|                                 |
|o3 : QQ                          |
+---------------------------------+

If $r = 0$, adicTruncation returns zero.

+----------------------------+
|i4 : adicTruncation(4, 2, 0)|
|                            |
|o4 = 0                      |
+----------------------------+

If a list $L$ of nonnegative rational numbers is passed, adicTruncation(p, e,
L) returns a list containing the $e^{th}$ truncations (base $p$) of those
numbers.

+------------------------------------------+
|i5 : adicTruncation(5, 5, {1/100, 1/1000})|
|                                          |
|       31     3                           |
|o5 = {----, ----}                         |
|      3125  3125                          |
|                                          |
|o5 : List                                 |
+------------------------------------------+

See also
========

  * adicExpansion -- compute adic expansion
  * adicDigit -- compute a digit of the non-terminating
    expansion of a number in the unit interval in a given base

Ways to use adicTruncation:
===========================

  * "adicTruncation(ZZ,ZZ,List)"
  * "adicTruncation(ZZ,ZZ,QQ)"
  * "adicTruncation(ZZ,ZZ,ZZ)"

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

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

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

The source of this document is in TestIdeals/BasicFunctionsDoc.m2:135:0.

ascendIdeal -- find the smallest ideal containing a given ideal which is compatible with a given Cartier linear map
*******************************************************************************************************************

  * Usage:
        ascendIdeal(e, h, J)
        ascendIdeal(e, a, h, J)
        ascendIdeal(e, expList, hList, J)
  * Inputs:
      * J, an ideal (Macaulay2Doc), in a polynomial ring S of
        characteristic p > 0, or in a quotient of S; the ideal to ascend
      * e, an integer (Macaulay2Doc), the order of the Frobenius root
        to take at each step of the ascent
      * h, a ring element (Macaulay2Doc), the polynomial in
        S to multiply by at each step of the ascent
      * a, an integer (Macaulay2Doc), the power to raise h to at each
        step of the ascent
      * hList, a list (Macaulay2Doc), consisting elements
        h_1,\ldots,h_n of S to multiply by at each step of the ascent
      * expList, a list (Macaulay2Doc), consisting of the powers
        a_1,\ldots,a_n to raise the elements of hList to, at each step of the
        ascent
  * Optional inputs (Macaulay2Doc),:
      * AscentCount => a Boolean value (Macaulay2Doc), default
        value false, tells the function to return the number of steps it took
        before the ascent of the ideal stabilized
      * FrobeniusRootStrategy => a symbol (Macaulay2Doc), default
        value Substitution, selects the strategy for internal frobeniusRoot
        calls
  * Outputs:
      * an ideal (Macaulay2Doc), the stable ideal in the ascending
        chain J \subseteq\ J + \phi(J) \subseteq\ J + \phi(J) + \phi^2(J)
        \subseteq\ \ldots, where \phi is the p^{-e}-linear map obtained by
        premultiplying the e^{th} Frobenius trace on S by h, or h^a, or
        h_1^{a_1}\ldots h_n^{a_n}, depending on the arguments passed
      * a sequence (Macaulay2Doc), consisting of the stable
        (ascended) ideal and the number of steps it took before the ascent of
        the ideal stabilized (when the option AscentCount is set to true)

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

Let $J$ be an ideal in a polynomial ring $S$ of characteristic $p>0$. An
element $h$ of $S$ determines a $p^{-e}$-linear map $\phi: S \to\ S$, obtained
by premultiplying the $e^{th}$ Frobenius trace on $S$ by $h$. The function
ascendIdeal finds the smallest $\phi$-stable ideal of $S$ containing $J$, which
is the stable value of the ascending chain $J\subseteq J + \phi(J)\subseteq J +
\phi(J) + \phi^2(J)\subseteq \cdots$.

If $J$ is not an ideal of a polynomial ring, but of a quotient of a polynomial
ring, ascendIdeal will do the computation with the $e^{th}$ Frobenius trace in
the ambient polynomial ring, but will do the comparison, to see if
stabilization has occurred, inside the quotient ring.

+-------------------------------------------+
|i1 : S = ZZ/5[x,y,z];                      |
+-------------------------------------------+
|i2 : g = x^4 + y^4 + z^4;                  |
+-------------------------------------------+
|i3 : h = g^4;                              |
+-------------------------------------------+
|i4 : R = S/(g);                            |
+-------------------------------------------+
|i5 : ascendIdeal(1, h, ideal y^3)          |
|                                           |
|             2             2        2      |
|o5 = ideal (z , y*z, x*z, y , x*y, x )     |
|                                           |
|o5 : Ideal of R                            |
+-------------------------------------------+
|i6 : ascendIdeal(1, h, ideal (sub(y, S))^3)|
|                                           |
|             2             2        2      |
|o6 = ideal (z , y*z, x*z, y , x*y, x )     |
|                                           |
|o6 : Ideal of S                            |
+-------------------------------------------+

The alternate ways to call the function allow the function to behave more
efficiently. Indeed, frequently the polynomial passed is a power, $h^a$. If $a$
is large, it is more efficient not to compute $h^a$, but instead, to keep the
exponent small by only raising $h$ to the minimal power needed to do the
computation at that time.

+-----------------------------------------------+
|i7 : S = ZZ/5[x,y,z];                          |
+-----------------------------------------------+
|i8 : g = x^4 + y^4 + z^4;                      |
+-----------------------------------------------+
|i9 : R = S/(g);                                |
+-----------------------------------------------+
|i10 : ascendIdeal(1, 4, g, ideal y^3)          |
|                                               |
|              2             2        2         |
|o10 = ideal (z , y*z, x*z, y , x*y, x )        |
|                                               |
|o10 : Ideal of R                               |
+-----------------------------------------------+
|i11 : ascendIdeal(1, 4, g, ideal (sub(y, S))^3)|
|                                               |
|              2             2        2         |
|o11 = ideal (z , y*z, x*z, y , x*y, x )        |
|                                               |
|o11 : Ideal of S                               |
+-----------------------------------------------+

More generally, if $h$ is a product of powers, $h = h_1^{a_1}\ldots h_n^{a_n}$,
then it is more efficient to pass ascendIdeal the lists expList =
\{a_1,\ldots,a_n\} and hList = \{h_1,\ldots,h_n\} of exponents and bases.

By default (when AscentCount => false), ascendIdeal just returns the stable
(ascended) ideal. If, instead, AscentCount is set to true, then ascendIdeal
returns a sequence whose first entry is the stable ideal, and the second is the
number of steps it took for the ascending chain to stabilize and reach that
ideal.

+-------------------------------------------------+
|i12 : R = ZZ/5[x,y,z];                           |
+-------------------------------------------------+
|i13 : J = ideal(x^12, y^15, z^21);               |
|                                                 |
|o13 : Ideal of R                                 |
+-------------------------------------------------+
|i14 : f = y^2 + x^3 - z^5;                       |
+-------------------------------------------------+
|i15 : ascendIdeal(1, f^4, J)                     |
|                                                 |
|o15 = ideal (z, y, x)                            |
|                                                 |
|o15 : Ideal of R                                 |
+-------------------------------------------------+
|i16 : ascendIdeal(1, f^4, J, AscentCount => true)|
|                                                 |
|o16 = (ideal (z, y, x), 3)                       |
|                                                 |
|o16 : Sequence                                   |
+-------------------------------------------------+

The option FrobeniusRootStrategy is passed to internal frobeniusRoot,
calls.

This method is described in M. Katzman's Parameter-test-ideals of
Cohen–Macaulay rings (Compositio Mathematica 144 (4), 933-948), under the name
"star-closure". It is a key tool in computing test ideals and test modules.

See also
========

  * testIdeal -- compute a test ideal in a Q-Gorenstein ring
  * testModule -- find the parameter test module of a
    reduced ring

Ways to use ascendIdeal:
========================

  * "ascendIdeal(ZZ,List,List,Ideal)"
  * "ascendIdeal(ZZ,RingElement,Ideal)"
  * "ascendIdeal(ZZ,ZZ,RingElement,Ideal)"

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

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

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

The source of this document is in TestIdeals/EthRootsDoc.m2:87:0.

ascendModule -- find the smallest submodule of free module containing a given submodule which is compatible with a given Cartier linear map
*******************************************************************************************************************************************

  * Usage:
        V = ascendModule(e, M, U)
        B = ascendModule(e, A, U)
  * Inputs:
      * M, a module (Macaulay2Doc), a submodule of a free module
        R^n, where R is a polynomial ring over a finite field of characteristic
        p
      * A, a matrix (Macaulay2Doc), an {n\times m} matrix with
        entries in R
      * U, a matrix (Macaulay2Doc), an {n\times n} matrix with
        entries in R
      * e, an integer (Macaulay2Doc),
  * Outputs:
      * V, a module (Macaulay2Doc), the smallest submodule of R^n
        containing M such that U^{1+p+\ldots+p^{e-1}} V \subseteq V^{[p^e]}
      * B, a matrix (Macaulay2Doc), whose image is the smallest
        submodule V of R^n containing the image of A such that
        U^{1+p+\ldots+p^{e-1}} V \subseteq V^{[p^e]}

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

Given an $n\times n$ matrix $U$ and a submodule $M$ of a free module $R^n$,
ascendModule finds the smallest submodule $V$ of $R^n$ containing $M$ and which
satisfies $U^{1 + p + \cdots + p^{e-1}} V\subseteq V^{[p^e]}$.

+-----------------------------------------------------------------------------+
|i1 : R = ZZ/2[a,b,c,d];                                                      |
+-----------------------------------------------------------------------------+
|i2 : A = matrix {{b*c, a, 0}, {a^2* d, d^2 , c + d}};                        |
|                                                                             |
|             2      3                                                        |
|o2 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+
|i3 : M = image A;                                                            |
+-----------------------------------------------------------------------------+
|i4 : U = matrix {{a^4  + a*b*c^2  + a*b*c*d, a^2* b}, {a^2*c*d^3 , a^3* c*d +|
|                                                                             |
|             2      2                                                        |
|o4 : Matrix R  <-- R                                                         |
|-----------------------------------------------------------------------------|
|a^3 *d^2  + b*c*d^3}};                                                       |
+-----------------------------------------------------------------------------+
|i5 : ascendModule(1, M, U)                                                   |
|                                                                             |
|o5 = image | 0   a  bc  |                                                    |
|           | c+d d2 a2d |                                                    |
|                                                                             |
|                             2                                               |
|o5 : R-module, submodule of R                                                |
+-----------------------------------------------------------------------------+

For ease of use, instead of passing the module $M$, one can instead pass a
matrix $A$ whose image is $M$, and ascendModule will return a matrix whose
image is $V$.

+--------------------------+
|i6 : ascendModule(1, A, U)|
|                          |
|o6 = | 0   a  bc  |       |
|     | c+d d2 a2d |       |
|                          |
|             2      3     |
|o6 : Matrix R  <-- R      |
+--------------------------+

This method is described in M. Katzman and W. Zhang's "Annihilators of Artinian
modules compatible with a Frobenius map", under the name "star-closure".

Ways to use ascendModule:
=========================

  * "ascendModule(ZZ,Matrix,Matrix)"
  * "ascendModule(ZZ,Module,Matrix)"

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

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

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

The source of this document is in TestIdeals/EthRootsDoc.m2:128:0.

AscentCount -- an option for ascendIdeal
****************************************

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

AscentCount is an option for ascendIdeal, that tells the function to return the
number of steps it took before the ascent of the ideal stabilized.

Functions with optional argument named AscentCount:
===================================================

  * "ascendIdeal(...,AscentCount=>...)" -- see ascendIdeal,
    -- find the smallest ideal containing a given ideal which is compatible
    with a given Cartier linear map

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

The object AscentCount, is a symbol (Macaulay2Doc).

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

The source of this document is in TestIdeals/EthRootsDoc.m2:138:0.

AssumeCM -- an option to assume a ring is Cohen-Macaulay
********************************************************

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

AssumeCM is an option used in various functions, to assume that a ring is
Cohen-Macaulay.

Functions with optional argument named AssumeCM:
================================================

  * "isFInjective(...,AssumeCM=>...)" -- see isFInjective,
    -- whether a ring is F-injective
  * "isFRational(...,AssumeCM=>...)" -- see isFRational, --
    whether a ring is F-rational

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

The object AssumeCM, is a symbol (Macaulay2Doc).

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

The source of this document is in TestIdeals/FinjectiveDoc.m2:285:0.

AssumeDomain -- an option to assume a ring is a domain
******************************************************

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

AssumeDomain is an option used in various functions, to assume that a ring is
an integral domain.

Functions with optional argument named AssumeDomain:
====================================================

  * "isFRational(...,AssumeDomain=>...)" -- see isFRational,
    -- whether a ring is F-rational
  * "isFRegular(...,AssumeDomain=>...)" -- see isFRegular, --
    whether a ring or pair is strongly F-regular
  * "testElement(...,AssumeDomain=>...)" -- see testElement,
    -- find a test element of a ring
  * "testIdeal(...,AssumeDomain=>...)" -- see testIdeal, --
    compute a test ideal in a Q-Gorenstein ring
  * "testModule(...,AssumeDomain=>...)" -- see testModule, --
    find the parameter test module of a reduced ring

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

The object AssumeDomain, is a symbol (Macaulay2Doc).

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

The source of this document is in TestIdeals/testIdealsDoc.m2:83:0.

AssumeNormal -- an option to assume a ring is normal
****************************************************

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

AssumeNormal is an option used in various functions, to assume that a ring is
normal.

Functions with optional argument named AssumeNormal:
====================================================

  * "isFInjective(...,AssumeNormal=>...)" -- see isFInjective,
    -- whether a ring is F-injective

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

The object AssumeNormal, is a symbol (Macaulay2Doc).

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

The source of this document is in TestIdeals/FinjectiveDoc.m2:295:0.

AssumeReduced -- an option to assume a ring is reduced
******************************************************

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

AssumeReduced is an option used in various functions, to assume that a ring is
reduced.

Functions with optional argument named AssumeReduced:
=====================================================

  * "isFInjective(...,AssumeReduced=>...)" -- see isFInjective,
    -- whether a ring is F-injective

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

The object AssumeReduced, is a symbol (Macaulay2Doc).

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

The source of this document is in TestIdeals/FinjectiveDoc.m2:305:0.

AtOrigin -- an option used to specify whether to only work locally
******************************************************************

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

If true, then the function will only try to work at the origin (the ideal
generated by the variables).

Functions with optional argument named AtOrigin:
================================================

  * "isCohenMacaulay(...,AtOrigin=>...)" -- see isCohenMacaulay,
    -- whether a ring is Cohen-Macaulay
  * "isFInjective(...,AtOrigin=>...)" -- see isFInjective,
    -- whether a ring is F-injective
  * "isFPure(...,AtOrigin=>...)" -- see isFPure, -- whether a
    ring is F-pure
  * "isFRational(...,AtOrigin=>...)" -- see isFRational, --
    whether a ring is F-rational
  * "isFRegular(...,AtOrigin=>...)" -- see isFRegular, --
    whether a ring or pair is strongly F-regular

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

The object AtOrigin, is a symbol (Macaulay2Doc).

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

The source of this document is in TestIdeals/parameterTestIdealDoc.m2:262:0.

CanonicalIdeal -- an option to specify that a certain ideal be used as the canonical ideal
******************************************************************************************

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

CanonicalIdeal is an option used in various functions to specify an ideal to be
used as the canonical ideal. In this way, the canonical ideal does not have to
be recomputed, and one can use a single fixed choice across multiple calls of a
function.

Functions with optional argument named CanonicalIdeal:
======================================================

  * "FPureModule(...,CanonicalIdeal=>...)" -- see FPureModule,
    -- compute the submodule of the canonical module stable under
    the image of the trace of Frobenius
  * "testModule(...,CanonicalIdeal=>...)" -- see testModule,
    -- find the parameter test module of a reduced ring

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

The object CanonicalIdeal, is a symbol (Macaulay2Doc).

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

The source of this document is in TestIdeals/FinjectiveDoc.m2:264:0.

canonicalIdeal -- produce an ideal isomorphic to the canonical module of a ring
*******************************************************************************

  * Usage:
        canonicalIdeal(R)
  * Inputs:
      * R, a ring (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * Attempts => an integer (Macaulay2Doc), default value 10,
        specifies how many times the function should try to embed the canonical
        module as an ideal before giving up
  * Outputs:
      * an ideal (Macaulay2Doc), isomorphic to the canonical
        module of R

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

Given a ring $R$, typically a domain, canonicalIdeal(R) produces an ideal
isomorphic to the canonical module of $R$. It uses the function
embedAsIdeal (WeilDivisors), from WeilDivisors.

+---------------------------------------------+
|i1 : S = QQ[x,y,u,v];                        |
+---------------------------------------------+
|i2 : T = QQ[a,b];                            |
+---------------------------------------------+
|i3 : f = map(T, S, {a^3, a^2*b, a*b^2, b^3});|
|                                             |
|o3 : RingMap T <-- S                         |
+---------------------------------------------+
|i4 : R = S/(ker f);                          |
+---------------------------------------------+
|i5 : canonicalIdeal(R)                       |
|                                             |
|o5 = ideal (v, u)                            |
|                                             |
|o5 : Ideal of R                              |
+---------------------------------------------+

The function canonicalIdeal will not always produce the same ideal, especially
in a non-domain.

+------------------------------------------------------+
|i6 : R = ZZ/13[x,y,z]/(x*y, x*z, y*z);                |
+------------------------------------------------------+
|i7 : print \ unique apply(10, i -> canonicalIdeal(R));|
|ideal (y - 5z, x + 4z)                                |
|ideal (y - 4z, x + 2z)                                |
|ideal (y - 3z, x + z)                                 |
|ideal (y + 3z, x + 2z)                                |
|ideal (y - 4z, x - z)                                 |
|ideal (y - 4z, x - 4z)                                |
|ideal (y + 5z, x - 3z)                                |
|ideal (y - 6z, x + 6z)                                |
|ideal (y + 6z, x + 2z)                                |
|ideal (y + 6z, x + 4z)                                |
+------------------------------------------------------+

The option Attempts is passed to embedAsIdeal, and tells it how many times to
try to embed the canonical module as an ideal before giving up.

Ways to use canonicalIdeal:
===========================

  * "canonicalIdeal(Ring)"

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

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

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

The source of this document is in TestIdeals/parameterTestIdealDoc.m2:41:0.

CanonicalStrategy -- an option for isFInjective
***********************************************

Functions with optional argument named CanonicalStrategy:
=========================================================

  * "isFInjective(...,CanonicalStrategy=>...)" -- see isFInjective,
    -- whether a ring is F-injective

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

The object CanonicalStrategy, is a symbol (Macaulay2Doc).

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

The source of this document is in TestIdeals/FinjectiveDoc.m2:313:0.

compatibleIdeals -- find all prime ideals compatible with a Frobenius near-splitting
************************************************************************************

  * Usage:
        compatibleIdeals(u)
  * Inputs:
      * u, a ring element (Macaulay2Doc), in a polynomial
        ring over the prime field $\mathbb{Z}/p$; the element determining the
        Frobenius splitting
  * Optional inputs (Macaulay2Doc),:
      * FrobeniusRootStrategy => a symbol (Macaulay2Doc), default
        value Substitution, selects the strategy for internal frobeniusRoot
        calls
  * Outputs:
      * a list (Macaulay2Doc), containing all prime ideals P of the
        ring of u such that uP $\subseteq$ P^{[p]} and u is not in P^{[p]}

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

The given element $u$ in a polynomial ring $R$ over the prime field
$\mathbb{Z}/p$ defines a $p^{-1}$-linear map $\phi: R\to R$; this map consists
of multiplication by the polynomial $u$, followed by the Frobenius trace on the
polynomial ring $R$. An ideal $I$ of $R$ is $\phi$-compatible if
$\phi(I)\subseteq I$ or, equivalently, $u I \subseteq I^{[p]}$. The function
compatibleIdeals returns a list of all prime ideals $P$ of $R$ such that:

(a) $uP \subseteq P^{[p]}$, and

(b) $u$ is not in $P^{[p]}$.

Condition (b) is equivalent to the non-vanishing of the corresponding
near-splitting of $R/P$. When $\phi$ is surjective, the set of all
$\phi$-compatible ideals consists of all intersections of the above prime
ideals.

This function is an implementation of the algorithm described in Moty Katzman
and Karl Schwede's paper An algorithm for computing compatibly Frobenius split
subvarieties, J. Symbolic Comput. 47 (2012), no. 8, pp. 996-1008.

These prime ideals have a "Matlis-dual" interpretation, too. Let $E$ be the
injective hull of the residue field of the localization of $R$ at the
irrelevant ideal, and let $T: E \rightarrow E$ be the natural Frobenius map.
Then $uT$ is a Frobenius map on $E$, and the primes $P$ computed by this
function are precisely those for which $uT$ restricts to a nonzero Frobenius
map of the annihilator of $P$ on $E$.

The following is a simple example, which is split with the coordinate axes in
$\mathbb{A}^2$.

+-------------------------------------+
|i1 : R = ZZ/3[s,t];                  |
+-------------------------------------+
|i2 : u = s^2*t^2;                    |
+-------------------------------------+
|i3 : compatibleIdeals u              |
|                                     |
|o3 = {ideal s, ideal (t, s), ideal t}|
|                                     |
|o3 : List                            |
+-------------------------------------+

Here is a more substantial example.

+-----------------------------------------------------+
|i4 : R = ZZ/2[a,b,c,d,e,f];                          |
+-----------------------------------------------------+
|i5 : u = d*(b*e - d*c)*(d - a*e - b*f + a*c*f);      |
+-----------------------------------------------------+
|i6 : print \ compatibleIdeals u;                     |
|ideal d                                              |
|ideal (e, d)                                         |
|ideal (f, e, d)                                      |
|ideal (f, e, d, b)                                   |
|ideal (f, e, d, b, a)                                |
|ideal (f, e, d, c, b, a)                             |
|ideal (f, e, d, c, b)                                |
|ideal (f, e, d, a*c + b)                             |
|ideal (e, d, c, b)                                   |
|ideal (e, d, c, b, a)                                |
|ideal (e, d, b)                                      |
|ideal (e, d, b, a)                                   |
|ideal (e, d, a*c + b)                                |
|ideal (d, b, a)                                      |
|ideal (d, b, a, c*f + e)                             |
|ideal (d, b)                                         |
|ideal (d, b, c*f + e)                                |
|ideal (d, a*c*f + a*e + b*f)                         |
|ideal (a*e + d, c*d + b*e, a*c + b)                  |
|ideal (c*f + e, b*f + d, a*e + d, c*d + b*e, a*c + b)|
|ideal(c*d + b*e)                                     |
|ideal (c*f + e, b*f + d, c*d + b*e)                  |
|ideal(a*c*f + a*e + b*f + d)                         |
+-----------------------------------------------------+

The option FrobeniusRootStrategy is passed to internal frobeniusRoot,
calls.

Ways to use compatibleIdeals:
=============================

  * "compatibleIdeals(RingElement)"

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

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

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

The source of this document is in TestIdeals/compatiblySplitDoc.m2:58:0.

CurrentRing -- an option to specify that a certain ring is used
***************************************************************

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

CurrentRing is an option used in various functions to specify a ring to work
with.

Functions with optional argument named CurrentRing:
===================================================

  * "FPureModule(...,CurrentRing=>...)" -- see FPureModule,
    -- compute the submodule of the canonical module stable under the image of
    the trace of Frobenius
  * "testModule(...,CurrentRing=>...)" -- see testModule, --
    find the parameter test module of a reduced ring

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

The object CurrentRing, is a symbol (Macaulay2Doc).

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

The source of this document is in TestIdeals/FinjectiveDoc.m2:253:0.

decomposeFraction -- decompose a rational number
************************************************

  * Usage:
        (a, b, c) = decomposeFraction(p, t)
  * Inputs:
      * p, an integer (Macaulay2Doc), a prime
      * t, a rational number (Macaulay2Doc), the fraction to be
        decomposed
  * Optional inputs (Macaulay2Doc),:
      * NoZeroC => a Boolean value (Macaulay2Doc), default value
        false, forces the returned c to not be zero
  * Outputs:
      * a sequence (Macaulay2Doc), containing integers a, b,
        and c, with b and c nonnegative, such that t = a/(p^b(p^c-1))

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

Given a rational number $t$ and a prime $p$, decomposeFraction(p, t) returns a
sequence ($a$,$b$,$c$) of integers, with $b$ and $c$ nonnegative, such that $t
= a/(p^b(p^c-1))$.

+-------------------------------------------+
|i1 : (a, b, c) = decomposeFraction(3, 4/45)|
|                                           |
|o1 = (64, 2, 4)                            |
|                                           |
|o1 : Sequence                              |
+-------------------------------------------+
|i2 : 4/45 == a/(3^b * (3^c - 1))           |
|                                           |
|o2 = true                                  |
+-------------------------------------------+

If the number $t$ is of the form $a/p^b$, then the function returns
($a$,$b$,$0$). Setting the option NoZeroC => true forces the third entry of the
output sequence to be nonzero, even if that means increasing the first entry.

+------------------------------------------------------------+
|i3 : decomposeFraction(3, 4/27)                             |
|                                                            |
|o3 = (4, 3, 0)                                              |
|                                                            |
|o3 : Sequence                                               |
+------------------------------------------------------------+
|i4 : (a, b, c) = decomposeFraction(3, 4/27, NoZeroC => true)|
|                                                            |
|o4 = (8, 3, 1)                                              |
|                                                            |
|o4 : Sequence                                               |
+------------------------------------------------------------+
|i5 : 4/27 == a/(3^b * (3^c - 1))                            |
|                                                            |
|o5 = true                                                   |
+------------------------------------------------------------+

Ways to use decomposeFraction:
==============================

  * "decomposeFraction(ZZ,QQ)"
  * "decomposeFraction(ZZ,ZZ)"

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

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

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

The source of this document is in TestIdeals/BasicFunctionsDoc.m2:226:0.

DepthOfSearch -- an option to specify how hard to search for something
**********************************************************************

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

This option is used to tell certain functions how hard to look for an answer.
Increasing it too much can make functions take a lot of time and resources.
Making it too small may mean that an incorrect or incomplete answer is given.
See the documentation for each function.

Functions with optional argument named DepthOfSearch:
=====================================================

  * "isFRegular(...,DepthOfSearch=>...)" -- see isFRegular,
    -- whether a ring or pair is strongly F-regular

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

The object DepthOfSearch, is a symbol (Macaulay2Doc).

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

The source of this document is in TestIdeals/testIdealsDoc.m2:116:0.

descendIdeal -- finds the maximal F-pure Cartier submodule of an ideal viewed as a Cartier module
*************************************************************************************************

  * Usage:
        descendIdeal(e, tList, fList, J)
  * Inputs:
      * e, an integer (Macaulay2Doc), the order of the Frobenius root
        to take
      * fList, a list (Macaulay2Doc), consisting of ring elements
        f_1,\ldots,f_n, for a pair
      * tList, a list (Macaulay2Doc), consisting of formal
        exponents t_1,\ldots,t_n for the elements of fList
      * J, an ideal (Macaulay2Doc), the Cartier module to study
  * Optional inputs (Macaulay2Doc),:
      * FrobeniusRootStrategy => a symbol (Macaulay2Doc), default
        value Substitution, selects the strategy for internal frobeniusRoot
        calls
  * Outputs:
      * a sequence (Macaulay2Doc), whose first entry is the
        maximal $F$-pure Cartier submodule of J under the dual-e-iterated
        Frobenius induced by f_1^{t_1}\ldots f_n^{t_n}, and the second entry is
        the number of times frobeniusRoot was applied

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

This command computes the maximal $F$-pure Cartier submodule of an ideal $J$
under the dual-$e$-iterated Frobenius induced by $f_1^{t_1}\ldots f_n^{t_n}$.

The function returns a sequence, where the first entry is the descended ideal,
and the second entry is the number of times frobeniusRoot was applied (i.e.,
the HSL number).

+-----------------------------------------------------------------------------+
|i1 : R = ZZ/7[x,y,z];                                                        |
+-----------------------------------------------------------------------------+
|i2 : f = y^2 - x^3;                                                          |
+-----------------------------------------------------------------------------+
|i3 : descendIdeal(1, {5}, {f}, ideal 1_R) --this computes the non-F-pure     |
|                                                                             |
|o3 = (ideal 1, 0)                                                            |
|                                                                             |
|o3 : Sequence                                                                |
|-----------------------------------------------------------------------------|
|ideal of (R, f^{5/6})                                                        |
+-----------------------------------------------------------------------------+
|i4 : descendIdeal(2, {41}, {f}, ideal 1_R) --this computes the non-F-pure    |
|                                                                             |
|o4 = (ideal (y, x), 1)                                                       |
|                                                                             |
|o4 : Sequence                                                                |
|-----------------------------------------------------------------------------|
|ideal of (R, f^{41/48})                                                      |
+-----------------------------------------------------------------------------+

The same two examples could also be accomplished via calls of FPureModule, as
illustrated below; however, the descendIdeal construction gives the user more
direct control.

+-----------------------------------------------------------------------------+
|i5 : first FPureModule(5/6, f, CanonicalIdeal => ideal 1_R, GeneratorList => |
|                                                                             |
|o5 = ideal 1                                                                 |
|                                                                             |
|o5 : Ideal of R                                                              |
|-----------------------------------------------------------------------------|
|{1_R})                                                                       |
+-----------------------------------------------------------------------------+
|i6 : first FPureModule(41/48, f, CanonicalIdeal => ideal 1_R, GeneratorList  |
|                                                                             |
|o6 = ideal (y, x)                                                            |
|                                                                             |
|o6 : Ideal of R                                                              |
|-----------------------------------------------------------------------------|
|=> {1_R})                                                                    |
+-----------------------------------------------------------------------------+

The option FrobeniusRootStrategy is passed to internal frobeniusRoot,
calls.

See also
========

  * FPureModule -- compute the submodule of the canonical
    module stable under the image of the trace of Frobenius
  * ascendIdeal -- find the smallest ideal containing a
    given ideal which is compatible with a given Cartier linear map

Ways to use descendIdeal:
=========================

  * "descendIdeal(ZZ,List,List,Ideal)"

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

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

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

The source of this document is in TestIdeals/FinjectiveDoc.m2:144:0.

floorLog -- floor of a logarithm
********************************

  * Usage:
        floorLog(b, x)
  * Inputs:
      * b, a number (Macaulay2Doc), greater than 1; the base of
        the logarithm
      * x, a number (Macaulay2Doc), positive
  * Outputs:
      * an integer (Macaulay2Doc), the floor of log_b(x)

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

floorLog(b, x) computes floor(log_b x), correcting occasional errors due to
rounding.

+---------------------+
|i1 : floor(log_3 3^5)|
|                     |
|o1 = 4               |
+---------------------+
|i2 : floorLog(3, 3^5)|
|                     |
|o2 = 5               |
+---------------------+

Ways to use floorLog:
=====================

  * "floorLog(Number,Number)"

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

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

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

The source of this document is in TestIdeals/BasicFunctionsDoc.m2:161:0.

FPureModule -- compute the submodule of the canonical module stable under the image of the trace of Frobenius
*************************************************************************************************************

  * Usage:
        FPureModule()
        FPureModule(R)
        FPureModule(t, f)
        FPureModule(tList, fList)
  * Inputs:
      * R, a ring map (Macaulay2Doc),
      * f, a ring element (Macaulay2Doc), to make a pair
      * t, a number (Macaulay2Doc), the formal exponent to which
        f is raised
      * fList, a list (Macaulay2Doc), consisting of ring elements
        f_1,\ldots,f_n, for a pair
      * tList, a list (Macaulay2Doc), consisting of formal
        exponents t_1,\ldots,t_n for the elements of fList
  * Optional inputs (Macaulay2Doc),:
      * FrobeniusRootStrategy => a symbol (Macaulay2Doc), default
        value Substitution, selects the strategy for internal frobeniusRoot
        calls
      * CanonicalIdeal => an ideal (Macaulay2Doc), default value
        null, specifies the canonical ideal (so the function does not recompute
        it)
      * CurrentRing => a ring (Macaulay2Doc), default value null,
        specifies the ring to work with
      * GeneratorList => a list (Macaulay2Doc), default value null,
        specifies the element (or elements) of the ambient polynomial ring that
        determines the Frobenius trace on the canonical module
  * Outputs:
      * a sequence (Macaulay2Doc), consisting of four elements:
        the HSLG module of R, (R,f^t), or (R,f_1^{t_1}\ldots f_n^{t_n}),
        represented as a submodule of a canonical module; the canonical module
        of which it is a submodule (given as an ideal of R); the element (or
        elements) of the ambient polynomial ring that determines the Frobenius
        trace on the canonical module; the number of times the trace of
        Frobenius was computed before the image stabilized.

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

Given a ring $R$ with canonical module $\omega$, this function computes the
image of $F^e_* \omega \to \omega$ for $e >> 0$. This image is sometimes called
the HSLG module (named for Hartshorne-Speiser, Lyubeznik, and Gabber), and it
roughly tells us where a ring is non-$F$-injective. It can also be used to
compute the maximal $F$-pure sub-Cartier module of a given rank-1 Cartier
module (represented as an ideal). The name of the function is based on this
interpretation.

Specifically, this function returns a sequence (FPMod, canMod, frobTrace,
count), where canMod is a canonical module of the ring (expressed as an ideal),
FPMod is the HSLG module, given as a submodule of canMod, frobTrace is a list
of elements of the ambient polynomial ring representing the trace of Frobenius
on the canonical module, and count is the number of times the trace of
Frobenius was computed before the image stabilized, sometimes called the HSLG
number of the canonical module as a Cartier module.

+-----------------------------------------------------------------------------+
|i1 : R = ZZ/7[x,y,z]/(x^5 + y^5 + z^5);                                      |
+-----------------------------------------------------------------------------+
|i2 : (FPMod, canMod, frobTrace, count) = FPureModule(R);                     |
+-----------------------------------------------------------------------------+
|i3 : canMod --the ambient canonical module                                   |
|                                                                             |
|o3 = ideal 1                                                                 |
|                                                                             |
|o3 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i4 : FPMod --the F-pure submodule of the canonical module                    |
|                                                                             |
|             3     2     2   2           2    3     2   2    3               |
|o4 = ideal (z , y*z , x*z , y z, x*y*z, x z, y , x*y , x y, x )              |
|                                                                             |
|o4 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i5 : frobTrace --the element representing trace of Frobenius                 |
|                                                                             |
|       30    25 5    20 10    15 15    10 20    5 25    30    25 5     20 5 5|
|o5 = {x   - x  y  + x  y   - x  y   + x  y   - x y   + y   - x  z  + 2x  y z |
|     ------------------------------------------------------------------------|
|         15 10 5     10 15 5     5 20 5    25 5    20 10     15 5 10         |
|     - 3x  y  z  - 3x  y  z  + 2x y  z  - y  z  + x  z   - 3x  y z   -       |
|     ------------------------------------------------------------------------|
|      10 10 10     5 15 10    20 10    15 15     10 5 15     5 10 15    15 15|
|     x  y  z   - 3x y  z   + y  z   - x  z   - 3x  y z   - 3x y  z   - y  z  |
|     ------------------------------------------------------------------------|
|        10 20     5 5 20    10 20    5 25    5 25    30                      |
|     + x  z   + 2x y z   + y  z   - x z   - y z   + z  }                     |
|                                                                             |
|o5 : List                                                                    |
+-----------------------------------------------------------------------------+
|i6 : count --how many times it took until the image stabilized               |
|                                                                             |
|o6 = 2                                                                       |
+-----------------------------------------------------------------------------+

Sometimes it is convenient to specify the ambient canonical module across
multiple calls of FPureModule. This can be done by using the option
CanonicalIdeal. One can also pass it something other than the canonical module
as well (for example, a submodule of the canonical module).

Likewise, one can use the GeneratorList option to specify the dual Frobenius
action on the canonical module (or ideal playing the role of the canonical
module).

In the following example, the non-$F$-pure ideal of a $\mathbb{Q}$-Gorenstein
ring is computed by hijacking this functionality.

+-----------------------------------------------------------------------------+
|i7 : T = ZZ/7[a,b];                                                          |
+-----------------------------------------------------------------------------+
|i8 : S = ZZ/7[x,y,z,w];                                                      |
+-----------------------------------------------------------------------------+
|i9 : f = map(T, S, {a^3, a^2*b, a*b^2, b^3});                                |
|                                                                             |
|o9 : RingMap T <-- S                                                         |
+-----------------------------------------------------------------------------+
|i10 : R = S/(ker f);                                                         |
+-----------------------------------------------------------------------------+
|i11 : J = ideal 1_R;                                                         |
|                                                                             |
|o11 : Ideal of R                                                             |
+-----------------------------------------------------------------------------+
|i12 : u = QGorensteinGenerator(1, R);                                        |
+-----------------------------------------------------------------------------+
|i13 : FPureModule(CanonicalIdeal => J, GeneratorList => {u})                 |
|                                                                             |
|                           2 6 12    3 4 13    3 5 11     4 3 12     5   13  |
|o13 = (ideal 1, ideal 1, {x y z   + x y z   + x y z  w + x y z  w + x y*z  w |
|      -----------------------------------------------------------------------|
|         12 6 2    3 6 9 2    4 4 10 2    5 2 11 2    6 12 2    13 4 3       |
|      + y  z w  + x y z w  + x y z  w  + x y z  w  + x z  w  + y  z w  +     |
|      -----------------------------------------------------------------------|
|         11 5 3    2 9 6 3    4 5 8 3    5 3 9 3    6   10 3      12 3 4     |
|      x*y  z w  + x y z w  + x y z w  + x y z w  + x y*z  w  + x*y  z w  +   |
|      -----------------------------------------------------------------------|
|       2 10 4 4    3 8 5 4    4 6 6 4    5 4 7 4    6 2 8 4    7 9 4         |
|      x y  z w  + x y z w  + x y z w  + x y z w  + x y z w  + x z w  +       |
|      -----------------------------------------------------------------------|
|         13   5    2 11 2 5    3 9 3 5    4 7 4 5    5 5 5 5    6 3 6 5      |
|      x*y  z*w  + x y  z w  + x y z w  + x y z w  + x y z w  + x y z w  +    |
|      -----------------------------------------------------------------------|
|       7   7 5    2 12 6    3 10   6    4 8 2 6    5 6 3 6    6 4 4 6        |
|      x y*z w  + x y  w  + x y  z*w  + x y z w  + x y z w  + x y z w  +      |
|      -----------------------------------------------------------------------|
|       7 2 5 6    8 6 6    4 9 7    5 7   7    6 5 2 7    7 3 3 7    8   4 7 |
|      x y z w  + x z w  + x y w  + x y z*w  + x y z w  + x y z w  + x y*z w  |
|      -----------------------------------------------------------------------|
|         6 6 8    7 4   8    8 2 2 8    9 3 8    8 3 9    9     9    10 10   |
|      + x y w  + x y z*w  + x y z w  + x z w  + x y w  + x y*z*w  + x  w  }, |
|      -----------------------------------------------------------------------|
|      0)                                                                     |
|                                                                             |
|o13 : Sequence                                                               |
+-----------------------------------------------------------------------------+

Additionally, one can specify a pair ($R$, $f^{ t}$), as long as $t$ is a
rational number with a denominator prime to the characteristic of the ring.

+---------------------------------------+
|i14 : R = ZZ/7[x,y];                   |
+---------------------------------------+
|i15 : M = FPureModule(5/6, y^2 - x^3); |
+---------------------------------------+
|i16 : M#1 -- the canonical module      |
|                                       |
|o16 = ideal 1                          |
|                                       |
|o16 : Ideal of R                       |
+---------------------------------------+
|i17 : M#0 -- the F-pure submodule      |
|                                       |
|o17 = ideal 1                          |
|                                       |
|o17 : Ideal of R                       |
+---------------------------------------+
|i18 : N = FPureModule(9/10, y^2 - x^3);|
+---------------------------------------+
|i19 : N#0 -- the F-pure submodule      |
|                                       |
|o19 = ideal (y, x)                     |
|                                       |
|o19 : Ideal of R                       |
+---------------------------------------+

Finally, one can specify a pair ($R$, $f_1^{t_1}\cdots f_n^{t_n}$), even when
$R$ is not regular (although $R$ is required to be $\mathbb{Q}$-Gorenstein,
with index not divisible by the characteristic).

+--------------------------------------------------------+
|i20 : R = ZZ/3[x,y,z]/(x^2 - y*z);                      |
+--------------------------------------------------------+
|i21 : f = y;                                            |
+--------------------------------------------------------+
|i22 : g = z;                                            |
+--------------------------------------------------------+
|i23 : FPureModule({1/2, 1/2, 1/2}, {y, z, y + z})       |
|                                                        |
|                                   4    2       2 2     |
|o23 = (ideal (z, y, x), ideal 1, {x  + x y*z + y z }, 1)|
|                                                        |
|o23 : Sequence                                          |
+--------------------------------------------------------+

The option FrobeniusRootStrategy is passed to internal frobeniusRoot,
calls.

See also
========

  * testModule -- find the parameter test module of a
    reduced ring
  * isFInjective -- whether a ring is F-injective
  * descendIdeal -- finds the maximal F-pure Cartier
    submodule of an ideal viewed as a Cartier module

Ways to use FPureModule:
========================

  * "FPureModule(List,List)"
  * "FPureModule(Number,RingElement)"
  * "FPureModule(Ring)"
  * FPureModule() (missing documentation)

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

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

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

The source of this document is in TestIdeals/FinjectiveDoc.m2:99:0.

frobenius -- compute a Frobenius power of an ideal or a matrix
**************************************************************

  * Usage:
        frobenius(e, I)
        frobenius^e(I)
        frobenius(e, M)
        frobenius^e(M)
        frobenius(I)
        frobenius(M)
  * Inputs:
      * e, an integer (Macaulay2Doc), the power of Frobenius to take
      * I, an ideal (Macaulay2Doc), in a ring of characteristic $p
        > 0$
      * M, a matrix (Macaulay2Doc), with entries in a ring of
        characteristic $p > 0$
  * Optional inputs (Macaulay2Doc),:
      * FrobeniusRootStrategy => a symbol (Macaulay2Doc), default
        value Substitution, selects the strategy for internal frobeniusRoot
        calls
  * Outputs:
      * an ideal (Macaulay2Doc), the p^e-th Frobenius power of I
        (with e = 1, if e is not specified)
      * a matrix (Macaulay2Doc), the p^e-th Frobenius power of M
        (with e = 1, if e is not specified)

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

Given an ideal $I$ in a ring of characteristic $p > 0$ and a nonnegative
integer $e$, frobenius(e, I) or frobenius^e(I) returns the $p^e$-th Frobenius
power $I^{[p^e]}$, that is, the ideal generated by all powers $f^{ p^e}$, with
$f \in\ I$ (see frobeniusPower).

+------------------------------+
|i1 : R = ZZ/3[x,y];           |
+------------------------------+
|i2 : I = ideal(x^2, x*y, y^2);|
|                              |
|o2 : Ideal of R               |
+------------------------------+
|i3 : frobenius(2, I)          |
|                              |
|             18   9 9   18    |
|o3 = ideal (x  , x y , y  )   |
|                              |
|o3 : Ideal of R               |
+------------------------------+
|i4 : frobenius^2(I)           |
|                              |
|             18   9 9   18    |
|o4 = ideal (x  , x y , y  )   |
|                              |
|o4 : Ideal of R               |
+------------------------------+
|i5 : frobeniusPower(3^2, I)   |
|                              |
|             18   9 9   18    |
|o5 = ideal (x  , x y , y  )   |
|                              |
|o5 : Ideal of R               |
+------------------------------+

If $e$ is negative, then frobenius(e, I) or frobenius^e(I) computes a Frobenius
root, as defined by Blickle, Mustata, and Smith (see frobeniusRoot).

+-----------------------------------------------------------------------------+
|i6 : R = ZZ/5[x,y,z,w];                                                      |
+-----------------------------------------------------------------------------+
|i7 : I = ideal(x^27*y^10 + 3*z^28 - x^2*y^15*z^35, x^17*w^30 +               |
|                                                                             |
|o7 : Ideal of R                                                              |
|-----------------------------------------------------------------------------|
|2*x^10*y^10*z^35, x*z^50);                                                   |
+-----------------------------------------------------------------------------+
|i8 : frobenius(-1, I)                                                        |
|                                                                             |
|             5   5 2   3 6                                                   |
|o8 = ideal (z , x y , x w )                                                  |
|                                                                             |
|o8 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i9 : frobenius(-2, I)                                                        |
|                                                                             |
|o9 = ideal (w, z, x)                                                         |
|                                                                             |
|o9 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i10 : frobeniusRoot(2, I)                                                    |
|                                                                             |
|o10 = ideal (w, z, x)                                                        |
|                                                                             |
|o10 : Ideal of R                                                             |
+-----------------------------------------------------------------------------+

If $M$ is a matrix with entries in a ring of characteristic $p > 0$ and $e$ is
a nonnegative integer, then frobenius(e, M), or frobenius^e(M), outputs a
matrix whose entries are the $p^e$-th powers of the entries of $M$.

+---------------------------------------------+
|i11 : R = ZZ/3[x,y];                         |
+---------------------------------------------+
|i12 : M = matrix {{x, y},{x + y, x^2 + y^2}};|
|                                             |
|              2      2                       |
|o12 : Matrix R  <-- R                        |
+---------------------------------------------+
|i13 : frobenius(2, M)                        |
|                                             |
|o13 = | x9    y9      |                      |
|      | x9+y9 x18+y18 |                      |
|                                             |
|              2      2                       |
|o13 : Matrix R  <-- R                        |
+---------------------------------------------+

frobenius(I) and frobenius(M) are abbreviations for frobenius(1, I) and
frobenius(1, M).

See also
========

  * frobeniusPower -- compute a (generalized) Frobenius
    power of an ideal
  * frobeniusRoot -- compute a Frobenius root

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

The object frobenius, is an instance of the type
FrobeniusOperator.

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

The source of this document is in TestIdeals/frobeniusPowersDoc.m2:63:0.

frobeniusPower -- compute a (generalized) Frobenius power of an ideal
*********************************************************************

  * Usage:
        frobeniusPower(n, I)
        frobeniusPower(t, I)
  * Inputs:
      * n, an integer (Macaulay2Doc), nonnegative
      * t, a rational number (Macaulay2Doc), nonnegative
      * I, an ideal (Macaulay2Doc), in a ring of characteristic $p
        > 0$
  * Optional inputs (Macaulay2Doc),:
      * FrobeniusPowerStrategy => a symbol (Macaulay2Doc),
        default value Naive, selects the strategy for frobeniusPower
      * FrobeniusRootStrategy => a symbol (Macaulay2Doc), default
        value Substitution, selects the strategy for internal frobeniusRoot
        calls
  * Outputs:
      * an ideal (Macaulay2Doc), the n^{th} or t^{th} Frobenius
        power of I

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

If $I$ is an ideal in a ring of positive characteristic $p$, then
frobeniusPower(t, I) computes the generalized Frobenius power $I^{[t]}$, as
introduced by Hernandez, Teixeira, and Witt. If the exponent is a power of the
characteristic, this is just the usual Frobenius power.

+---------------------------+
|i1 : R = ZZ/5[x,y];        |
+---------------------------+
|i2 : I = ideal(x, y);      |
|                           |
|o2 : Ideal of R            |
+---------------------------+
|i3 : frobeniusPower(125, I)|
|                           |
|             125   125     |
|o3 = ideal (x   , y   )    |
|                           |
|o3 : Ideal of R            |
+---------------------------+

If $n$ is an arbitrary nonnegative integer, then write the base $p$ expansion
of $n$ as follows: $n = a_0 + a_1 p + a_2 p^2 + ... + a_r p^r$. Then the
$n^{th}$ Frobenius power of $I$ is defined as follows: $I^{[n]} =
(I^{a_0})(I^{a_1})^{[p]}(I^{a_2})^{[p^2]}\cdots(I^{a_r})^{[p^r]}$.

+------------------------------------------------+
|i4 : R = ZZ/3[x,y];                             |
+------------------------------------------------+
|i5 : I = ideal(x, y);                           |
|                                                |
|o5 : Ideal of R                                 |
+------------------------------------------------+
|i6 : adicExpansion(3, 17)                       |
|                                                |
|o6 = {2, 2, 1}                                  |
|                                                |
|o6 : List                                       |
+------------------------------------------------+
|i7 : J1 = I^2*frobenius(1, I^2)*frobenius(2, I);|
|                                                |
|o7 : Ideal of R                                 |
+------------------------------------------------+
|i8 : J2 = frobeniusPower(17, I);                |
|                                                |
|o8 : Ideal of R                                 |
+------------------------------------------------+
|i9 : J1 == J2                                   |
|                                                |
|o9 = true                                       |
+------------------------------------------------+

If $t$ is a rational number of the form $t = a/p^e$, then $I^{[t]} =
(I^{[a]})^{[1/p^e]}$.

+--------------------------------------------+
|i10 : R = ZZ/5[x,y,z];                      |
+--------------------------------------------+
|i11 : I = ideal(x^50*z^95, y^100 + z^27);   |
|                                            |
|o11 : Ideal of R                            |
+--------------------------------------------+
|i12 : frobeniusPower(4/5^2, I)              |
|                                            |
|              4   4 3   8 2   12    16      |
|o12 = ideal (z , y z , y z , y  z, y  )     |
|                                            |
|o12 : Ideal of R                            |
+--------------------------------------------+
|i13 : frobeniusRoot(2, frobeniusPower(4, I))|
|                                            |
|              4   4 3   8 2   12    16      |
|o13 = ideal (z , y z , y z , y  z, y  )     |
|                                            |
|o13 : Ideal of R                            |
+--------------------------------------------+

If $t$ is an arbitrary nonegative rational number, and \{$t_n$\} =
\{$a_n/p^{e_n}$\}\ is a sequence of rational numbers converging to $t$ from
above, then $I^{[t]}$ is the largest ideal in the increasing chain of ideals
\{$I^{[t_n]}$\}.

+-----------------------------------------------------------------------------+
|i14 : p = 7;                                                                 |
+-----------------------------------------------------------------------------+
|i15 : R = ZZ/p[x,y];                                                         |
+-----------------------------------------------------------------------------+
|i16 : I = ideal(x^50, y^30);                                                 |
|                                                                             |
|o16 : Ideal of R                                                             |
+-----------------------------------------------------------------------------+
|i17 : t = 6/19;                                                              |
+-----------------------------------------------------------------------------+
|i18 : expon = e -> ceiling(p^e*t)/p^e; -- a sequence converging to t from    |
|-----------------------------------------------------------------------------|
|above                                                                        |
+-----------------------------------------------------------------------------+
|i19 : print \ apply(6, i -> frobeniusPower(expon i, I));                     |
|        50   30                                                              |
|ideal (x  , y  )                                                             |
|        12   7 8   14 4   21                                                 |
|ideal (y  , x y , x  y , x  )                                                |
|        9   2 8   7 5   8 4   14    15                                       |
|ideal (y , x y , x y , x y , x  y, x  )                                      |
|        9     8   7 4   14                                                   |
|ideal (y , x*y , x y , x  )                                                  |
|        9     8   7 4   14                                                   |
|ideal (y , x*y , x y , x  )                                                  |
|        9     8   7 4   14                                                   |
|ideal (y , x*y , x y , x  )                                                  |
+-----------------------------------------------------------------------------+
|i20 : frobeniusPower(t, I)                                                   |
|                                                                             |
|              9     8   7 4   14                                             |
|o20 = ideal (y , x*y , x y , x  )                                            |
|                                                                             |
|o20 : Ideal of R                                                             |
+-----------------------------------------------------------------------------+

The option FrobeniusPowerStrategy controls the strategy for computing the
generalized Frobenius power $I^{[t]}$. The two valid options are Safe and
Naive, and the default strategy is Naive.

The option FrobeniusRootStrategy is passed to internal frobeniusRoot,
calls.

See also
========

  * frobenius -- compute a Frobenius power of an ideal or a
    matrix
  * frobeniusRoot -- compute a Frobenius root

Ways to use frobeniusPower:
===========================

  * "frobeniusPower(QQ,Ideal)"
  * "frobeniusPower(ZZ,Ideal)"

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

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

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

The source of this document is in TestIdeals/frobeniusPowersDoc.m2:139:0.

FrobeniusPowerStrategy -- an option for frobeniusPower
******************************************************

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

Valid values are Naive and Safe.

Functions with optional argument named FrobeniusPowerStrategy:
==============================================================

  * "frobeniusPower(...,FrobeniusPowerStrategy=>...)" -- see
    frobeniusPower, -- compute a (generalized) Frobenius power
    of an ideal

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

The object FrobeniusPowerStrategy, is a
symbol (Macaulay2Doc).

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

The source of this document is in TestIdeals/frobeniusPowersDoc.m2:167:0.

frobeniusPreimage -- finds the ideal of elements mapped into a given ideal, under all $p^{-e}$-linear maps
**********************************************************************************************************

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

Given an ideal $Q$ in a ring $R$, one frequently considers $I_e(Q)$.  This is
the ideal of elements $x \in R$ such that $\phi(x^{1/p^e}) \in Q$ for all $\phi
: R^{1/p^e} \to R$.  Sometimes this ideal is called the Frobenius pre-image. In
a regular ring, it agrees with the frobenius power $Q^{[p^e]}$.

+------------------------------------+
|i1 : R = ZZ/7[x,y,z]/ideal(x*y-z^2);|
+------------------------------------+
|i2 : Q = ideal(x, z);               |
|                                    |
|o2 : Ideal of R                     |
+------------------------------------+
|i3 : frobeniusPreimage(1, Q)        |
|                                    |
|                3    4              |
|o3 = ideal (0, x z, x )             |
|                                    |
|o3 : Ideal of R                     |
+------------------------------------+

In the previous example $I_1(Q)$ agrees with $Q^{(p)}$, the $p$th symbolic
power of $Q$.

Ways to use frobeniusPreimage:
==============================

  * "frobeniusPreimage(ZZ,Ideal)"

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

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

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

The source of this document is in TestIdeals/frobeniusPowersDoc.m2:185:0.

frobeniusRoot -- compute a Frobenius root
*****************************************

  * Usage:
        frobeniusRoot(e, I)
        frobeniusRoot(e, M)
        frobeniusRoot(e, A)
        frobeniusRoot(e, expList, idealList)
        frobeniusRoot(e, expList, idealList, I)
        frobeniusRoot(e, m, I)
        frobeniusRoot(e, a, f)
        frobeniusRoot(e, a, f, I)
  * Inputs:
      * e, an integer (Macaulay2Doc), the order of the Frobenius root
      * I, an ideal (Macaulay2Doc), in a polynomial ring over a
        finite field of characteristic p
      * M, a module (Macaulay2Doc), a submodule of a free module
        of a polynomial ring over a finite field of characteristic p
      * A, a matrix (Macaulay2Doc), with entries in a polynomial
        ring over a finite field of characteristic p
      * idealList, a list (Macaulay2Doc), containing ideals
        I_1,\ldots,I_n
      * expList, a list (Macaulay2Doc), containing exponents
        a_1,\ldots,a_n to which the ideals in idealList will be raised
      * m, an integer (Macaulay2Doc), the exponent to which I will be
        raised, before taking the Frobenius root
      * f, a ring element (Macaulay2Doc), a polynomial over
        a finite field of characteristic p
      * a, an integer (Macaulay2Doc), the exponent to which f will be
        raised, before taking the Frobenius root
  * Optional inputs (Macaulay2Doc),:
      * FrobeniusRootStrategy => a symbol (Macaulay2Doc), default
        value Substitution, controls the strategy used by this function
  * Outputs:
      * an ideal (Macaulay2Doc), the p^e-th Frobenius root of I
        (or I_1^{a_1}\ldots I_n^{a_n}, I_1^{a_1}\ldots I_n^{a_n}I, I^m, (f^a),
        f^aI, depending on the arguments passed)
      * a module (Macaulay2Doc), the p^e-th Frobenius root of the
        module M
      * a matrix (Macaulay2Doc), whose image is the p^e-th
        Frobenius root of the image of the matrix A

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

In a polynomial ring $R = k[x_1, \ldots, x_n]$ with coefficients in a field of
positive characteristic $p$, the $p^e$-th Frobenius root $I^{[1/p^e]}$ of an
ideal $I$ is the smallest ideal $J$ such that $I\subseteq J^{[p^e]}$ (=
frobeniusPower(p^e, J)). Similarly, if $M$ is a submodule of $R^k$, the
$p^e$-th Frobenius root of $M$, denoted $M^{[1/p^e]}$, is the smallest
submodule $V$ of $R^k$ such that $M\subseteq V^{[p^e]}$. The function
frobeniusRoot computes such ideals and submodules.

There are many ways to call frobeniusRoot. The simplest way is to call
frobeniusRoot(e, I), which computes $I^{[1/p^e]}$.

+----------------------------------------+
|i1 : R = ZZ/5[x,y,z];                   |
+----------------------------------------+
|i2 : I = ideal(x^50*z^95, y^100 + z^27);|
|                                        |
|o2 : Ideal of R                         |
+----------------------------------------+
|i3 : frobeniusRoot(2, I)                |
|                                        |
|                4                       |
|o3 = ideal (z, y )                      |
|                                        |
|o3 : Ideal of R                         |
+----------------------------------------+

The function frobeniusRoot works over arbitrary finite fields.

+----------------------------------------------+
|i4 : p = 3;                                   |
+----------------------------------------------+
|i5 : R = GF(p^2)[x,y,z];                      |
+----------------------------------------------+
|i6 : I = ideal(a^(2*p)*x^p + y*z^p + x^p*y^p);|
|                                              |
|o6 : Ideal of R                               |
+----------------------------------------------+
|i7 : frobeniusRoot(1, I)                      |
|                                              |
|o7 = ideal (z, x*y + (a + 1)x)                |
|                                              |
|o7 : Ideal of R                               |
+----------------------------------------------+

In the following example, for a submodule $M$ of $R^2$, frobeniusRoot(1, M)
computes the smallest submodule $V$ of $R^2$ such that $M \subseteq V^{[2]}$.

+-----------------------------------------------------------------------------+
|i8 : R = ZZ/2[a,b,c,d];                                                      |
+-----------------------------------------------------------------------------+
|i9 : A = matrix {{a^4  + a*b*c^2  + a*b*c*d, a^2* b}, {a^2*c*d^3 , a^3* c*d +|
|                                                                             |
|             2      2                                                        |
|o9 : Matrix R  <-- R                                                         |
|-----------------------------------------------------------------------------|
|a^3 *d^2  + b*c*d^3}};                                                       |
+-----------------------------------------------------------------------------+
|i10 : M = image A;                                                           |
+-----------------------------------------------------------------------------+
|i11 : frobeniusRoot(1, M)                                                    |
|                                                                             |
|o11 = image {-2} | 1 0 0 |                                                   |
|            {0}  | 0 d a |                                                   |
|                                                                             |
|                              2                                              |
|o11 : R-module, submodule of R                                               |
+-----------------------------------------------------------------------------+

For ease of use, one can also simply pass a matrix $A$ whose image is $M$, and
frobeniusRoot(1, A) returns a matrix whose image is $V$.

+-------------------------+
|i12 : frobeniusRoot(1, A)|
|                         |
|o12 = {-2} | 1 0 0 |     |
|      {0}  | 0 d a |     |
|                         |
|              2      3   |
|o12 : Matrix R  <-- R    |
+-------------------------+

Often, one wants to compute a Frobenius root of some product of powers of
ideals, $I_1^{a_1}\cdots I_n^{a_n}$. This is best accomplished by calling
frobeniusRoot(e, \{a_1,\ldots,a_n\}, \{I_1,\ldots,I_n\}).

+------------------------------------------------------------+
|i13 : R =  ZZ/5[x,y,z];                                     |
+------------------------------------------------------------+
|i14 : I1 = ideal(x^10, y^10, z^10);                         |
|                                                            |
|o14 : Ideal of R                                            |
+------------------------------------------------------------+
|i15 : I2 = ideal(x^20*y^100, x + z^100);                    |
|                                                            |
|o15 : Ideal of R                                            |
+------------------------------------------------------------+
|i16 : I3 = ideal(x^50*y^50*z^50);                           |
|                                                            |
|o16 : Ideal of R                                            |
+------------------------------------------------------------+
|i17 : time J1 = frobeniusRoot(1, {8, 10, 12}, {I1, I2, I3});|
| -- used 0.982679s (cpu); 0.869062s (thread); 0s (gc)       |
|                                                            |
|o17 : Ideal of R                                            |
+------------------------------------------------------------+
|i18 : time J2 = frobeniusRoot(1, I1^8*I2^10*I3^12);         |
| -- used 3.10163s (cpu); 2.83396s (thread); 0s (gc)         |
|                                                            |
|o18 : Ideal of R                                            |
+------------------------------------------------------------+
|i19 : J1 == J2                                              |
|                                                            |
|o19 = true                                                  |
+------------------------------------------------------------+

For legacy reasons, the last ideal in the list can be specified separately,
using frobeniusRoot(e, \{a_1,\ldots,a_n\}, \{I_1,\ldots,I_n\}, I). The last
ideal, I, is just raised to the first power.

The following are additional ways of calling frobeniusRoot:

$\bullet$ frobeniusRoot(e, m, I) computes the $p^e$-th Frobenius root of the
ideal $I^m$.

$\bullet$ frobeniusRoot(e, a, f) computes the $p^e$-th Frobenius root of the
principal ideal ($f^{ a}$).

$\bullet$ frobeniusRoot(e, a, f, I) computes the $p^e$-th Frobenius root of the
product $f^{ a}I$.

There are two valid inputs for the option FrobeniusRootStrategy, namely
Substitution and MonomialBasis.  In the computation of the $p^e$-th Frobenius
root of an ideal $I$, each generator $f$ of $I$ is written in the form $f =
\sum a_i^{p^e} m_i$, where each $m_i$ is a monomial whose exponents are less
than $p^e$; then the collection of all the $a_i$, obtained for all generators
of $I$, generates the Frobenius root $I^{[1/p^e]}$. Substitution and
MonomialBasis use different methods for gathering these $a_i$, and sometimes
one method is faster than the other.

See also
========

  * frobenius -- compute a Frobenius power of an ideal or a
    matrix
  * frobeniusPower -- compute a (generalized) Frobenius
    power of an ideal

Ways to use frobeniusRoot:
==========================

  * "frobeniusRoot(ZZ,Ideal)"
  * "frobeniusRoot(ZZ,List,List)"
  * "frobeniusRoot(ZZ,List,List,Ideal)"
  * "frobeniusRoot(ZZ,Matrix)"
  * "frobeniusRoot(ZZ,Module)"
  * "frobeniusRoot(ZZ,MonomialIdeal)"
  * "frobeniusRoot(ZZ,ZZ,Ideal)"
  * "frobeniusRoot(ZZ,ZZ,RingElement)"
  * "frobeniusRoot(ZZ,ZZ,RingElement,Ideal)"

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

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

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

The source of this document is in TestIdeals/EthRootsDoc.m2:246:0.

FrobeniusRootStrategy -- an option for various functions
********************************************************

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

An option for various functions, and in particular for frobeniusRoot.
The valid values are Substitution and MonomialBasis.

Functions with optional argument named FrobeniusRootStrategy:
=============================================================

  * "ascendIdeal(...,FrobeniusRootStrategy=>...)" -- see ascendIdeal,
    -- find the smallest ideal containing a given ideal which is
    compatible with a given Cartier linear map
  * "compatibleIdeals(...,FrobeniusRootStrategy=>...)" -- see
    compatibleIdeals, -- find all prime ideals compatible
    with a Frobenius near-splitting
  * "descendIdeal(...,FrobeniusRootStrategy=>...)" -- see descendIdeal,
    -- finds the maximal F-pure Cartier submodule of an ideal
    viewed as a Cartier module
  * "FPureModule(...,FrobeniusRootStrategy=>...)" -- see FPureModule,
    -- compute the submodule of the canonical module stable under
    the image of the trace of Frobenius
  * "frobenius(...,FrobeniusRootStrategy=>...)" -- see frobenius,
    -- compute a Frobenius power of an ideal or a matrix
  * "frobeniusPower(...,FrobeniusRootStrategy=>...)" -- see
    frobeniusPower, -- compute a (generalized) Frobenius power
    of an ideal
  * "frobeniusRoot(...,FrobeniusRootStrategy=>...)" -- see frobeniusRoot,
    -- compute a Frobenius root
  * "isFInjective(...,FrobeniusRootStrategy=>...)" -- see isFInjective,
    -- whether a ring is F-injective
  * "isFPure(...,FrobeniusRootStrategy=>...)" -- see isFPure, --
    whether a ring is F-pure
  * "isFRational(...,FrobeniusRootStrategy=>...)" -- see isFRational,
    -- whether a ring is F-rational
  * "isFRegular(...,FrobeniusRootStrategy=>...)" -- see isFRegular,
    -- whether a ring or pair is strongly F-regular
  * "parameterTestIdeal(...,FrobeniusRootStrategy=>...)" -- see
    parameterTestIdeal, -- compute the parameter test ideal
    of a Cohen-Macaulay ring
  * "testIdeal(...,FrobeniusRootStrategy=>...)" -- see testIdeal,
    -- compute a test ideal in a Q-Gorenstein ring
  * "testModule(...,FrobeniusRootStrategy=>...)" -- see testModule,
    -- find the parameter test module of a reduced ring

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

The object FrobeniusRootStrategy, is a
symbol (Macaulay2Doc).

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

The source of this document is in TestIdeals/EthRootsDoc.m2:257:0.

frobeniusTraceOnCanonicalModule -- find an element of a polynomial ring that determines the Frobenius trace on the canonical module of a quotient of that ring
**************************************************************************************************************************************************************

  * Usage:
        frobeniusTraceOnCanonicalModule(I, canIdeal)
  * Inputs:
      * I, an ideal (Macaulay2Doc), of a polynomial ring S; the
        defining ideal of a ring R
      * canIdeal, an ideal (Macaulay2Doc), an ideal of S whose
        image in R = S/I is a canonical module of R
  * Outputs:
      * a list (Macaulay2Doc), consisting of elements of the
        ambient polynomial ring S, a linear combination of which determines the
        Frobenius trace on the canonical module of the quotient ring R = S/I

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

Given $R = S/I$, where $S$ is a polynomial ring over a field of positive
characteristic $p$, there is a map $\omega_R^{1/p^e} \to \omega_R$ dual to the
Frobenius map on $R$. By embedding $\omega_R$ as an ideal of $R$, one can
interpret this map as a $p^{-e}$-linear map on $S$.  But every $p^{-e}$-linear
map on $S$ is a premultiple of the dual to Frobenius on $S$, by some element of
$S$. This function finds such an element.

However, because Macaulay2 does not always properly identify an ideal as
principal (even though it is), sometimes the function cannot find this single
element, but instead finds a list of elements of $S$, a linear combination of
which is the desired one.

The function frobeniusTraceOnCanonicalModule takes as inputs the defining ideal
$I$ of $R$, and an ideal $J$ of $S$ whose image in $R$ is a canonical module of
$R$.

+-----------------------------------------------------------------------------+
|i1 : S = ZZ/5[x,y,z,w];                                                      |
+-----------------------------------------------------------------------------+
|i2 : I = ker map( ZZ/5[a,b], S, {a^3, a^2*b, a*b^2, b^3} );                  |
|                                                                             |
|o2 : Ideal of S                                                              |
+-----------------------------------------------------------------------------+
|i3 : R = S/I;                                                                |
+-----------------------------------------------------------------------------+
|i4 : canIdeal = canonicalIdeal R;                                            |
|                                                                             |
|o4 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i5 : J = sub(canIdeal, S);                                                   |
|                                                                             |
|o5 : Ideal of S                                                              |
+-----------------------------------------------------------------------------+
|i6 : frobeniusTraceOnCanonicalModule(I, J)                                   |
|                                                                             |
|         4 9 2    2 3 8 3    3   9 3    8 4 4    2 4 6 4    3 2 7 4    4 8 4 |
|o6 = {x*y z w  + x y z w  + x y*z w  + y z w  + x y z w  + x y z w  + x z w  |
|     ------------------------------------------------------------------------|
|        9 2 5      7 3 5    2 5 4 5    3 3 5 5    4   6 5      8   6         |
|     + y z w  + x*y z w  + x y z w  + x y z w  + x y*z w  + x*y z*w  +       |
|     ------------------------------------------------------------------------|
|      2 6 2 6    3 4 3 6    4 2 4 6    5 5 6    2 7 7    3 5   7    4 3 2 7  |
|     x y z w  + x y z w  + x y z w  + x z w  + x y w  + x y z*w  + x y z w  +|
|     ------------------------------------------------------------------------|
|      5   3 7    4 4 8    5 2   8    6 2 8    6   9                          |
|     x y*z w  + x y w  + x y z*w  + x z w  + x y*w }                         |
|                                                                             |
|o6 : List                                                                    |
+-----------------------------------------------------------------------------+

Ways to use frobeniusTraceOnCanonicalModule:
============================================

  * "frobeniusTraceOnCanonicalModule(Ideal,Ideal)"

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

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

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

The source of this document is in TestIdeals/parameterTestIdealDoc.m2:74:0.

GeneratorList -- an option to specify that a certain list of elements is used to describe a Cartier action
**********************************************************************************************************

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

GeneratorList is an option used in various functions to specify a Cartier
action, particularly on the canonical module.  In particular, if it is not
specified, typically the Cartier action on the canonical module will need to be
recomputed.

Functions with optional argument named GeneratorList:
=====================================================

  * "FPureModule(...,GeneratorList=>...)" -- see FPureModule,
    -- compute the submodule of the canonical module stable under
    the image of the trace of Frobenius
  * "testModule(...,GeneratorList=>...)" -- see testModule,
    -- find the parameter test module of a reduced ring

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

The object GeneratorList, is a symbol (Macaulay2Doc).

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

The source of this document is in TestIdeals/FinjectiveDoc.m2:274:0.

isCohenMacaulay -- whether a ring is Cohen-Macaulay
***************************************************

  * Usage:
        isCohenMacaulay(R)
  * Inputs:
      * R, a ring (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * AtOrigin => a Boolean value (Macaulay2Doc), default
        value false, stipulates whether to check if the ring is Cohen-Macaulay
        only at the origin
  * Outputs:
      * a Boolean value (Macaulay2Doc),

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

The function isCohenMacaulay determines if a ring is Cohen-Macaulay. If the
option AtOrigin (default value false) is set to true, isCohenMacaulay will
simply call the isCM (Depth), function in the Depth package, which
checks whether the ring is Cohen-Macaulay at the origin; otherwise,
isCohenMacaulay checks the Cohen-Macaulay property globally, which sometimes is
much faster than the local computation.

+---------------------------------------------------------+
|i1 : T = ZZ/5[x,y];                                      |
+---------------------------------------------------------+
|i2 : S = ZZ/5[a,b,c,d];                                  |
+---------------------------------------------------------+
|i3 : g = map(T, S, {x^3, x^2*y, x*y^2, y^3});            |
|                                                         |
|o3 : RingMap T <-- S                                     |
+---------------------------------------------------------+
|i4 : R = S/(ker g);                                      |
+---------------------------------------------------------+
|i5 : time isCohenMacaulay(R)                             |
| -- used 0.00282211s (cpu); 0.00282168s (thread); 0s (gc)|
|                                                         |
|o5 = true                                                |
+---------------------------------------------------------+
|i6 : time isCohenMacaulay(R, AtOrigin => true)           |
| -- used 0.00597159s (cpu); 0.00597298s (thread); 0s (gc)|
|                                                         |
|o6 = true                                                |
+---------------------------------------------------------+
+------------------------------------------+
|i7 : R = QQ[x,y,u,v]/(x*u, x*v, y*u, y*v);|
+------------------------------------------+
|i8 : isCohenMacaulay(R)                   |
|                                          |
|o8 = false                                |
+------------------------------------------+

The function isCohenMacaulay considers $R$ as a quotient of a polynomial ring,
$R = S/I$, and takes a resolution of $I$. If the resolution has length equal to
dim $S$ - dim $R$, then $R$ is Cohen-Macaulay. If the resolution has a
different length, and $I$ is homogeneous, then $R$ is not Cohen-Macaulay.
Finally, if the resolution has a different length and $I$ is not homogeneous,
the function looks at the Ext modules which compute the depth.

Caveat
======

This function assumes that the spectrum of the ring is connected. If given a
non-equidimensional Cohen-Macaulay ring (e.g., a ring whose spectrum has two
connected components of different dimensions), isCohenMacaulay will return
false.

Ways to use isCohenMacaulay:
============================

  * "isCohenMacaulay(Ring)"

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

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

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

The source of this document is in TestIdeals/parameterTestIdealDoc.m2:252:0.

isFInjective -- whether a ring is F-injective
*********************************************

  * Usage:
        isFInjective(R)
  * Inputs:
      * R, a ring (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * FrobeniusRootStrategy => a symbol (Macaulay2Doc), default
        value Substitution, selects the strategy for internal frobeniusRoot
        calls
      * AtOrigin => a Boolean value (Macaulay2Doc), default
        value false, stipulates whether to check $F$-injectivity only at the
        origin
      * AssumeCM => a Boolean value (Macaulay2Doc), default
        value false, assumes the ring is Cohen-Macaulay
      * AssumeNormal => a Boolean value (Macaulay2Doc), default
        value false, assumes the ring is normal
      * AssumeReduced => a Boolean value (Macaulay2Doc), default
        value true, assumes the ring is reduced
      * CanonicalStrategy => a Boolean value (Macaulay2Doc),
        default value Katzman, specifies what strategy to use when computing
        the Frobenius action on top local cohomology
  * Outputs:
      * a Boolean value (Macaulay2Doc),

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

This function determines whether a ring of finite type over a finite prime
field is $F$-injective. Over a more general field, it checks the
$F$-injectivity of the relative Frobenius. We begin with an example of an
$F$-injective ring that is not $F$-pure (taken from the work of Anurag Singh on
deformation of $F$-regularity).

+----------------------------------------------------+
|i1 : S = ZZ/3[a,b,c,d,t];                           |
+----------------------------------------------------+
|i2 : M = matrix{{a^2 + t^4, b, d}, {c, a^2, b^3-d}};|
|                                                    |
|             2      3                               |
|o2 : Matrix S  <-- S                                |
+----------------------------------------------------+
|i3 : I = minors(2, M);                              |
|                                                    |
|o3 : Ideal of S                                     |
+----------------------------------------------------+
|i4 : R = S/I;                                       |
+----------------------------------------------------+
|i5 : isFInjective(R)                                |
|                                                    |
|o5 = true                                           |
+----------------------------------------------------+
|i6 : isFPure(R)                                     |
|                                                    |
|o6 = false                                          |
+----------------------------------------------------+

Next, let us form the cone over $\mathbb{P}^1 \times  E$, where $E$ is an
elliptic curve. We begin with a supersingular elliptic curve. This should be
$F$-injective if and only if it is $F$-pure.

+-----------------------------------------------------------------------------+
|i7 : S = ZZ/3[xs, ys, zs, xt, yt, zt];                                       |
+-----------------------------------------------------------------------------+
|i8 : EP1 = ZZ/3[x,y,z,s,t]/(x^3 + y^2*z - x*z^2); --supersingular elliptic   |
|-----------------------------------------------------------------------------|
|curve                                                                        |
+-----------------------------------------------------------------------------+
|i9 : f = map(EP1, S, {x*s, y*s, z*s, x*t, y*t, z*t});                        |
|                                                                             |
|o9 : RingMap EP1 <-- S                                                       |
+-----------------------------------------------------------------------------+
|i10 : R = S/(ker f);                                                         |
+-----------------------------------------------------------------------------+
|i11 : isFInjective(R)                                                        |
|                                                                             |
|o11 = false                                                                  |
+-----------------------------------------------------------------------------+
|i12 : isFPure(R)                                                             |
|                                                                             |
|o12 = false                                                                  |
+-----------------------------------------------------------------------------+

Now we do a similar computation, this time with an ordinary elliptic curve.

+----------------------------------------------------------------------------+
|i13 : S = ZZ/3[xs, ys, zs, xt, yt, zt];                                     |
+----------------------------------------------------------------------------+
|i14 : EP1 = ZZ/3[x,y,z,s,t]/(y^2*z - x^3 + x*y*z); --ordinary elliptic curve|
+----------------------------------------------------------------------------+
|i15 : f = map(EP1, S, {x*s, y*s, z*s, x*t, y*t, z*t});                      |
|                                                                            |
|o15 : RingMap EP1 <-- S                                                     |
+----------------------------------------------------------------------------+
|i16 : R = S/(ker f);                                                        |
+----------------------------------------------------------------------------+
|i17 : isFInjective(R)                                                       |
|                                                                            |
|o17 = true                                                                  |
+----------------------------------------------------------------------------+
|i18 : isFPure(R)                                                            |
|                                                                            |
|o18 = true                                                                  |
+----------------------------------------------------------------------------+

If CanonicalStrategy is set to Katzman (its default behavior), then the
Frobenius action on the top local cohomology (bottom Ext) is computed via the
method of Katzman. If it is set to anything else, it is simply brute forced in
Macaulay2 using the functoriality of Ext. The Katzman strategy is typically
much faster.

+-----------------------------------------------------+
|i19 : R = ZZ/5[x,y,z]/(y^2*z + x*y*z-x^3)            |
|                                                     |
|o19 = R                                              |
|                                                     |
|o19 : QuotientRing                                   |
+-----------------------------------------------------+
|i20 : time isFInjective(R)                           |
| -- used 0.035498s (cpu); 0.035498s (thread); 0s (gc)|
|                                                     |
|o20 = true                                           |
+-----------------------------------------------------+
|i21 : time isFInjective(R, CanonicalStrategy => null)|
| -- used 2.20842s (cpu); 1.61687s (thread); 0s (gc)  |
|                                                     |
|o21 = true                                           |
+-----------------------------------------------------+

If the option AtOrigin (default value false) is set to true, isFInjective will
only check $F$-injectivity at the origin. Otherwise, it will check
$F$-injectivity globally. Note that checking $F$-injectivity at the origin can
be slower than checking it globally. Consider the following example of a
non-$F$-injective ring.

+-----------------------------------------------------+
|i22 : R = ZZ/7[x,y,z]/((x-1)^5 + (y+1)^5 + z^5);     |
+-----------------------------------------------------+
|i23 : time isFInjective(R)                           |
| -- used 0.151424s (cpu); 0.120106s (thread); 0s (gc)|
|                                                     |
|o23 = false                                          |
+-----------------------------------------------------+
|i24 : time isFInjective(R, AtOrigin => true)         |
| -- used 0.159389s (cpu); 0.127372s (thread); 0s (gc)|
|                                                     |
|o24 = true                                           |
+-----------------------------------------------------+

If the option AssumeCM (default value false) is set to true, then isFInjective
only checks the Frobenius action on top cohomology (which is typically much
faster). Note that it can give an incorrect answer if the non-injective
Frobenius occurs in a lower degree.  Consider the example of the cone over a
supersingular elliptic curve times $\mathbb{P}^1$.

+------------------------------------------------------+
|i25 : S = ZZ/3[xs, ys, zs, xt, yt, zt];               |
+------------------------------------------------------+
|i26 : EP1 = ZZ/3[x,y,z,s,t]/(x^3 + y^2*z - x*z^2);    |
+------------------------------------------------------+
|i27 : f = map(EP1, S, {x*s, y*s, z*s, x*t, y*t, z*t});|
|                                                      |
|o27 : RingMap EP1 <-- S                               |
+------------------------------------------------------+
|i28 : R = S/(ker f);                                  |
+------------------------------------------------------+
|i29 : time isFInjective(R)                            |
| -- used 1.0509s (cpu); 0.934366s (thread); 0s (gc)   |
|                                                      |
|o29 = false                                           |
+------------------------------------------------------+
|i30 : time isFInjective(R, AssumeCM => true)          |
| -- used 0.373573s (cpu); 0.297987s (thread); 0s (gc) |
|                                                      |
|o30 = true                                            |
+------------------------------------------------------+

If the option AssumedReduced is set to true (its default behavior), then the
bottom local cohomology is avoided (this means the Frobenius action on the top
potentially nonzero Ext is not computed).

If the option AssumeNormal (default value false) is set to true, then the
bottom two local cohomology modules (or, rather, their duals) need not be
computed.

The value of the option FrobeniusRootStrategy is passed to internal
frobeniusRoot, calls.

See also
========

  * isFPure -- whether a ring is F-pure
  * testModule -- find the parameter test module of a
    reduced ring

Ways to use isFInjective:
=========================

  * "isFInjective(Ring)"

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

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

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

The source of this document is in TestIdeals/FinjectiveDoc.m2:243:0.

isFPure -- whether a ring is F-pure
***********************************

  * Usage:
        isFPure(R)
        isFPure(I)
  * Inputs:
      * R, a ring (Macaulay2Doc), whose $F$-purity is to be checked
      * I, an ideal (Macaulay2Doc), the defining ideal of the ring
        whose $F$-purity is to be checked
  * Optional inputs (Macaulay2Doc),:
      * AtOrigin => a Boolean value (Macaulay2Doc), default
        value false, specifies whether the $F$-purity is to be checked only at
        the origin
      * FrobeniusRootStrategy => a symbol (Macaulay2Doc), default
        value Substitution, selects the strategy for internal frobeniusRoot
        calls
  * Outputs:
      * a Boolean value (Macaulay2Doc),

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

Given a ring $R$, this function checks whether the ring is $F$-pure, using
Fedder's criterion (by applying frobeniusRoot, to $I^{[p]}
: I$, where $I$ is the defining ideal of $R$).

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

Alternatively, one may pass the defining ideal of a ring.

+-----------------------------------------------+
|i7 : S = ZZ/2[x,y,z];                          |
+-----------------------------------------------+
|i8 : isFPure ideal(y^2 - x^3)                  |
|                                               |
|o8 = false                                     |
+-----------------------------------------------+
|i9 : isFPure ideal(z^2 - x*y*z + x*y^2 + x^2*y)|
|                                               |
|o9 = true                                      |
+-----------------------------------------------+

The option AtOrigin controls whether $F$-purity is checked at the origin or
everywhere. If its value is set to true (the default is false), it will only
check $F$-purity at the origin.

+----------------------------------------------------+
|i10 : R = ZZ/5[x,y,z]/((x - 1)^3 + (y - 2)^3 + z^3);|
+----------------------------------------------------+
|i11 : isFPure(R)                                    |
|                                                    |
|o11 = false                                         |
+----------------------------------------------------+
|i12 : isFPure(R, AtOrigin => true)                  |
|                                                    |
|o12 = true                                          |
+----------------------------------------------------+
|i13 : S = ZZ/13[x,y,z]/(x^3 + y^3 + z^3);           |
+----------------------------------------------------+
|i14 : isFPure(S)                                    |
|                                                    |
|o14 = true                                          |
+----------------------------------------------------+
|i15 : isFPure(S, AtOrigin => true)                  |
|                                                    |
|o15 = true                                          |
+----------------------------------------------------+

Note that there is a difference in the strategy for the local or non-local
computations. In fact, checking $F$-purity globally can sometimes be faster
than checking it only at the origin. If AtOrigin is set to false, then isFPure
computes the frobeniusRoot, of $I^{[p]} : I$, whereas if
AtOrigin is set to true, it checks whether $I^{[p]} : I$ is contained in
$m^{[p]}$, where $m$ is the maximal ideal generated by the variables.

The option FrobeniusRootStrategy is passed to internal frobeniusRoot,
calls, and specifies the strategy to be used.

See also
========

  * isFRegular -- whether a ring or pair is strongly
    F-regular
  * isFInjective -- whether a ring is F-injective

Ways to use isFPure:
====================

  * "isFPure(Ideal)"
  * "isFPure(Ring)"

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

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

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

The source of this document is in TestIdeals/testIdealsDoc.m2:377:0.

isFRational -- whether a ring is F-rational
*******************************************

  * Usage:
        isFRational(R)
  * Inputs:
      * R, a ring (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * AtOrigin => a Boolean value (Macaulay2Doc), default
        value false, specifies that $F$-rationality be checked only at the
        origin, and that the Cohen-Macaulayness test be done with the isCM
        command, from the Depth package
      * AssumeCM => a Boolean value (Macaulay2Doc), default
        value false, assumes the ring is Cohen-Macaulay
      * AssumeDomain => a Boolean value (Macaulay2Doc), default
        value false, assumes the ring is an integral domain
      * FrobeniusRootStrategy => a symbol (Macaulay2Doc), default
        value Substitution, selects the strategy for internal frobeniusRoot
        calls
  * Outputs:
      * a Boolean value (Macaulay2Doc),

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

The function isFRational determines whether a ring is $F$-rational. If the
option AtOrigin (default value false) is set to true, it will only check if the
ring is $F$-rational at the origin (this can be slower). If the option AssumeCM
(default value false) is set to true, it will not verify that the ring is
Cohen-Macaulay.

+---------------------------------------------+
|i1 : T = ZZ/5[x,y];                          |
+---------------------------------------------+
|i2 : S = ZZ/5[a,b,c,d];                      |
+---------------------------------------------+
|i3 : g = map(T, S, {x^3, x^2*y, x*y^2, y^3});|
|                                             |
|o3 : RingMap T <-- S                         |
+---------------------------------------------+
|i4 : R = S/(ker g);                          |
+---------------------------------------------+
|i5 : isFRational(R)                          |
|                                             |
|o5 = true                                    |
+---------------------------------------------+
+---------------------------------------+
|i6 : R = ZZ/7[x,y,z]/(x^3 + y^3 + z^3);|
+---------------------------------------+
|i7 : isFRational(R)                    |
|                                       |
|o7 = false                             |
+---------------------------------------+

Below is a more interesting example, of a ring that is $F$-rational but not
$F$-regular. This example first appeared in A. K. Singh's work on deformation
of $F$-regularity.

+------------------------------------------------------+
|i8 : S = ZZ/3[a,b,c,d,t];                             |
+------------------------------------------------------+
|i9 : M = matrix{{a^2 + t^4, b, d}, {c, a^2, b^3 - d}};|
|                                                      |
|             2      3                                 |
|o9 : Matrix S  <-- S                                  |
+------------------------------------------------------+
|i10 : I = minors(2, M);                               |
|                                                      |
|o10 : Ideal of S                                      |
+------------------------------------------------------+
|i11 : R = S/I;                                        |
+------------------------------------------------------+
|i12 : isFRational(R)                                  |
|                                                      |
|o12 = true                                            |
+------------------------------------------------------+

The option AssumeDomain is used when computing a test element.  The option
FrobeniusRootStrategy is passed to internal frobeniusRoot,
calls.

Caveat
======

This function assumes that the spectrum of the ring is connected. Like
isCohenMacaulay, if given a non-equidimensional $F$-rational ring (e.g., a ring
whose spectrum has two connected components of different dimensions),
isFRational will return false.

Ways to use isFRational:
========================

  * "isFRational(Ring)"

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

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

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

The source of this document is in TestIdeals/parameterTestIdealDoc.m2:316:0.

isFRegular -- whether a ring or pair is strongly F-regular
**********************************************************

  * Usage:
        isFRegular(R)
        isFRegular(t, f)
        isFRegular(tList, fList)
  * Inputs:
      * R, a ring (Macaulay2Doc),
      * t, a rational number (Macaulay2Doc), a formal exponent for f
      * f, a ring element (Macaulay2Doc), the element for
        the pair, to test $F$-regularity
      * tList, a list (Macaulay2Doc), a list of formal exponents,
        for the elements of fList
      * fList, a list (Macaulay2Doc), a list of elements for a
        pair, to test $F$-regularity
  * Optional inputs (Macaulay2Doc),:
      * AssumeDomain => a Boolean value (Macaulay2Doc), default
        value false, assumes the ring is an integral domain
      * FrobeniusRootStrategy => a symbol (Macaulay2Doc), default
        value Substitution, selects the strategy for internal frobeniusRoot
        calls
      * MaxCartierIndex => an integer (Macaulay2Doc), default value
        10, sets the maximum Gorenstein index to search for when working with a
        $\mathbb{Q}$-Gorenstein ambient ring
      * QGorensteinIndex => an integer (Macaulay2Doc), default value
        0, specifies the $\mathbb{Q}$-Gorenstein index of the ring
      * AtOrigin => a Boolean value (Macaulay2Doc), default
        value false, specifies whether to check $F$-regularity just at the
        origin
      * DepthOfSearch => an integer (Macaulay2Doc), default value 2,
        specifies how hard to try to prove that a non-$\mathbb{Q}$-Gorenstein
        ring is $F$-regular
  * Outputs:
      * a Boolean value (Macaulay2Doc),

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

Given a normal $\mathbb{Q}$-Gorenstein ring $R$, the function isFRegular checks
whether the ring is strongly $F$-regular. It can also prove that a
non-$\mathbb{Q}$-Gorenstein ring is $F$-regular (but cannot show it is not);
see below for how to access this functionality.

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

The function isFRegular can also test strong $F$-regularity of pairs.

+-----------------------------------+
|i5 : R = ZZ/5[x,y];                |
+-----------------------------------+
|i6 : f = y^2 - x^3;                |
+-----------------------------------+
|i7 : isFRegular(1/2, f)            |
|                                   |
|o7 = true                          |
+-----------------------------------+
|i8 : isFRegular(5/6, f)            |
|                                   |
|o8 = false                         |
+-----------------------------------+
|i9 : isFRegular(4/5, f)            |
|                                   |
|o9 = false                         |
+-----------------------------------+
|i10 : isFRegular(4/5 - 1/100000, f)|
|                                   |
|o10 = true                         |
+-----------------------------------+

When checking whether a ring or pair is strongly $F$-regular, the option
AtOrigin determines if this is to be checked at the origin or everywhere. The
default value for AtOrigin is false, which corresponds to checking
$F$-regularity everywhere; setting AtOrigin => true, $F$-regularity is checked
only at the origin.

+----------------------------------------------------+
|i11 : R = ZZ/7[x,y,z]/((x - 1)^3 + (y + 1)^3 + z^3);|
+----------------------------------------------------+
|i12 : isFRegular(R)                                 |
|                                                    |
|o12 = false                                         |
+----------------------------------------------------+
|i13 : isFRegular(R, AtOrigin => true)               |
|                                                    |
|o13 = true                                          |
+----------------------------------------------------+
|i14 : S = ZZ/13[x,y,z]/(x^3 + y^3 + z^3);           |
+----------------------------------------------------+
|i15 : isFRegular(S)                                 |
|                                                    |
|o15 = false                                         |
+----------------------------------------------------+
|i16 : isFRegular(S, AtOrigin => true)               |
|                                                    |
|o16 = false                                         |
+----------------------------------------------------+

Here is an example of AtOrigin behavior with a pair.

+------------------------------------------+
|i17 : R = ZZ/13[x,y];                     |
+------------------------------------------+
|i18 : f = (y - 2)^2 - (x - 3)^3;          |
+------------------------------------------+
|i19 : isFRegular(5/6, f)                  |
|                                          |
|o19 = false                               |
+------------------------------------------+
|i20 : isFRegular(5/6, f, AtOrigin => true)|
|                                          |
|o20 = true                                |
+------------------------------------------+
|i21 : g = y^2 - x^3;                      |
+------------------------------------------+
|i22 : isFRegular(5/6, g)                  |
|                                          |
|o22 = false                               |
+------------------------------------------+
|i23 : isFRegular(5/6, g, AtOrigin => true)|
|                                          |
|o23 = false                               |
+------------------------------------------+

The option AssumeDomain (default value false) is used when finding a test
element. The option FrobeniusRootStrategy (default value Substitution) is
passed to internal frobeniusRoot, calls.

When working in a $\mathbb{Q}$-Gorenstein ring $R$, isFRegular looks for a
positive integer $N$ such that $N K_R$ is Cartier. The option MaxCartierIndex
(default value $10$) controls the maximum value of $N$ to consider in this
search. If the smallest such $N$ turns out to be greater than the value passed
to MaxCartierIndex, then testIdeal returns an error.

The $\mathbb{Q}$-Gorenstein index can be specified by the user through the
option QGorensteinIndex; when this option is used, the search for $N$ is
bypassed, and the option MaxCartierIndex ignored.

The function isFRegular can show that rings that are not
$\mathbb{Q}$-Gorenstein are $F$-regular (it cannot, however, show that such a
ring is not $F$-regular). To do this, set the option QGorensteinIndex =>
infinity. One may also use the option DepthOfSearch to increase the depth of
search.

+-----------------------------------------------------------------------------+
|i24 : S = ZZ/7[x,y,z,u,v,w];                                                 |
+-----------------------------------------------------------------------------+
|i25 : I = minors(2, matrix {{x, y, z}, {u, v, w}});                          |
|                                                                             |
|o25 : Ideal of S                                                             |
+-----------------------------------------------------------------------------+
|i26 : debugLevel = 1;                                                        |
+-----------------------------------------------------------------------------+
|i27 : time isFRegular(S/I, QGorensteinIndex => infinity,                     |
|isFRegular: This ring does not appear to be F-regular.                       |
| -- used 0.115489s (cpu); 0.0852082s (thread); 0s (gc)                       |
|                                                                             |
|o27 = false                                                                  |
|-----------------------------------------------------------------------------|
| DepthOfSearch => 1)                                                         |
|Increasing DepthOfSearch will let the function search more deeply.           |
+-----------------------------------------------------------------------------+
|i28 : time isFRegular(S/I, QGorensteinIndex => infinity, DepthOfSearch => 2) |
| -- used 0.197985s (cpu); 0.197988s (thread); 0s (gc)                        |
|                                                                             |
|o28 = true                                                                   |
+-----------------------------------------------------------------------------+
|i29 : debugLevel = 0;                                                        |
+-----------------------------------------------------------------------------+

See also
========

  * testIdeal -- compute a test ideal in a Q-Gorenstein ring
  * isFRational -- whether a ring is F-rational

Ways to use isFRegular:
=======================

  * "isFRegular(List,List)"
  * "isFRegular(Number,RingElement)"
  * "isFRegular(Ring)"

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

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

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

The source of this document is in TestIdeals/testIdealsDoc.m2:317:0.

Katzman -- a valid value for the option CanonicalStrategy
*********************************************************

See also
========

  * isFInjective -- whether a ring is F-injective
  * CanonicalStrategy -- an option for isFInjective

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

The object Katzman, is a symbol (Macaulay2Doc).

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

The source of this document is in TestIdeals/FinjectiveDoc.m2:323:0.

MaxCartierIndex -- an option to specify the maximum number to consider when computing the Cartier index of a divisor
********************************************************************************************************************

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

Some functions need to search for the smallest positive integer $N$ such that
$N$ times a divisor (usually the canonical divisor) is Cartier. The option
MaxCartierIndex is used to specify the largest integer to be considered in this
search.

Functions with optional argument named MaxCartierIndex:
=======================================================

  * "isFRegular(...,MaxCartierIndex=>...)" -- see isFRegular,
    -- whether a ring or pair is strongly F-regular
  * "testIdeal(...,MaxCartierIndex=>...)" -- see testIdeal, --
    compute a test ideal in a Q-Gorenstein ring

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

The object MaxCartierIndex, is a symbol (Macaulay2Doc).

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

The source of this document is in TestIdeals/testIdealsDoc.m2:94:0.

MonomialBasis -- a valid value for the option FrobeniusRootStrategy
*******************************************************************

See also
========

  * FrobeniusRootStrategy -- an option for
    various functions

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

The object MonomialBasis, is a symbol (Macaulay2Doc).

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

The source of this document is in TestIdeals/EthRootsDoc.m2:275:0.

multiplicativeOrder -- multiplicative order of an integer modulo another
************************************************************************

  * Usage:
        multiplicativeOrder(a, b)
  * Inputs:
      * a, an integer (Macaulay2Doc), whose multiplicative order is
        to be computed
      * b, an integer (Macaulay2Doc), prime to a; the modulus
  * Outputs:
      * an integer (Macaulay2Doc), the multiplicative order of a mod
        b

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

multiplicativeOrder(a,b) computes the multiplicative order of $a$ modulo $b$.

+---------------------------------+
|i1 : multiplicativeOrder(2, 11^2)|
|                                 |
|o1 = 110                         |
+---------------------------------+
|i2 : multiplicativeOrder(3, 11^2)|
|                                 |
|o2 = 5                           |
+---------------------------------+
|i3 : multiplicativeOrder(4, 11^2)|
|                                 |
|o3 = 55                          |
+---------------------------------+

If $a$ and $b$ are not relatively prime,  multiplicativeOrder(a, b) returns an
error.

Ways to use multiplicativeOrder:
================================

  * "multiplicativeOrder(ZZ,ZZ)"

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

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

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

The source of this document is in TestIdeals/BasicFunctionsDoc.m2:189:0.

Naive -- a valid value for the option FrobeniusPowerStrategy
************************************************************

See also
========

  * FrobeniusPowerStrategy -- an option for
    frobeniusPower

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

The object Naive, is a symbol (Macaulay2Doc).

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

The source of this document is in TestIdeals/frobeniusPowersDoc.m2:148:0.

NoZeroC -- an option for decomposeFraction
******************************************

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

Valid values are true or false. If true, the third entry in the output of
decomposeFraction is required to be nonzero.

Functions with optional argument named NoZeroC:
===============================================

  * "decomposeFraction(...,NoZeroC=>...)" -- see decomposeFraction,
    -- decompose a rational number

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

The object NoZeroC, is a symbol (Macaulay2Doc).

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

The source of this document is in TestIdeals/BasicFunctionsDoc.m2:238:0.

parameterTestIdeal -- compute the parameter test ideal of a Cohen-Macaulay ring
*******************************************************************************

  * Usage:
        parameterTestIdeal(R)
  * Inputs:
      * R, a ring (Macaulay2Doc), a Cohen-Macaulay ring
  * Optional inputs (Macaulay2Doc),:
      * FrobeniusRootStrategy => a symbol (Macaulay2Doc), default
        value Substitution, selects the strategy for internal frobeniusRoot
        calls
  * Outputs:
      * an ideal (Macaulay2Doc), the parameter test ideal of R

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

This function computes the parameter test ideal of a Cohen-Macaulay ring $R$.
Technically, it computes \tau($\omega$) : $\omega$ where $\omega$ is a
canonical module of $R$, and \tau($\omega$) is the (parameter) test module, as
computed by testModule. For example, the ring $R$ in the
following example is $F$-rational, and so its parameter test ideal is the unit
ideal.

+---------------------------------------------+
|i1 : T = ZZ/5[x,y];                          |
+---------------------------------------------+
|i2 : S = ZZ/5[a,b,c,d];                      |
+---------------------------------------------+
|i3 : g = map(T, S, {x^3, x^2*y, x*y^2, y^3});|
|                                             |
|o3 : RingMap T <-- S                         |
+---------------------------------------------+
|i4 : R = S/(ker g);                          |
+---------------------------------------------+
|i5 : parameterTestIdeal(R)                   |
|                                             |
|o5 = ideal 1                                 |
|                                             |
|o5 : Ideal of R                              |
+---------------------------------------------+

Consider now a non-$F$-rational Gorenstein ring, whose test ideal and parameter
test ideal coincide.

+---------------------------------------+
|i6 : R = ZZ/7[x,y,z]/(x^3 + y^3 + z^3);|
+---------------------------------------+
|i7 : parameterTestIdeal(R)             |
|                                       |
|o7 = ideal (z, y, x)                   |
|                                       |
|o7 : Ideal of R                        |
+---------------------------------------+
|i8 : testIdeal(R)                      |
|                                       |
|o8 = ideal (z, y, x)                   |
|                                       |
|o8 : Ideal of R                        |
+---------------------------------------+

See also
========

  * testModule -- find the parameter test module of a
    reduced ring
  * testIdeal -- compute a test ideal in a Q-Gorenstein ring

Ways to use parameterTestIdeal:
===============================

  * "parameterTestIdeal(Ring)"

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

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

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

The source of this document is in TestIdeals/parameterTestIdealDoc.m2:212:0.

QGorensteinGenerator -- find an element representing the Frobenius trace map of a Q-Gorenstein ring
***************************************************************************************************

  * Usage:
        QGorensteinGenerator(e, R)
        QGorensteinGenerator(R)
  * Inputs:
      * e, an integer (Macaulay2Doc), the degree in which to search
      * R, a ring (Macaulay2Doc), a $\mathbb{Q}$-Gorenstein ring
  * Outputs:
      * a ring element (Macaulay2Doc), representing the
        Frobenius trace map of R

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

Suppose that $R$ is a ring such that $(p^e-1)K_R$ is linearly equivalent to
zero (this is the case, for example, if $R$ is $\mathbb{Q}$-Gorenstein with
index not divisible by $p$). Then if we write $R = S/I$, where $S$ is a
polynomial ring, we have that $I^{[p^e]}:I = uS + I^{[p^e]}$ for some $u \in
S$. By Fedder's criterion, this element $u$ represents the generator of the
$R^{1/p^e}$-module Hom($R^{1/p^e}$,$R$). For example, if $I$ is principal,
generated by $f$, then we may take $u = f^{ p^e-1}$.

The function QGorensteinGenerator produces the element $u$ described above. If
the user does not specify a positive integer $e$, it assumes $e = 1$.

+-----------------------------------+
|i1 : S = ZZ/3[x,y,z];              |
+-----------------------------------+
|i2 : f = x^2*y - z^2;              |
+-----------------------------------+
|i3 : I = ideal f;                  |
|                                   |
|o3 : Ideal of S                    |
+-----------------------------------+
|i4 : R = S/I;                      |
+-----------------------------------+
|i5 : u = QGorensteinGenerator(1, R)|
|                                   |
|      4 2    2   2    4            |
|o5 = x y  + x y*z  + z             |
|                                   |
|o5 : S                             |
+-----------------------------------+
|i6 : u % I^3 == f^2 % I^3          |
|                                   |
|o6 = true                          |
+-----------------------------------+

If Macaulay2 does not recognize that $I^{[p^e]}:I / I^{[p^e]}$ is principal, an
error is thrown, which will also happen if $R$ is not $\mathbb{Q}$-Gorenstein
of the appropriate index. Note that in the nongraded case Macaulay2 is not
guaranteed to find minimal generators of principally generated modules.

Ways to use QGorensteinGenerator:
=================================

  * "QGorensteinGenerator(Ring)"
  * "QGorensteinGenerator(ZZ,Ring)"

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

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

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

The source of this document is in TestIdeals/testIdealsDoc.m2:45:0.

QGorensteinIndex -- an option to specify the index of the canonical divisor, if known
*************************************************************************************

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

When working in a $\mathbb{Q}$-Gorenstein ring $R$, frequently we must find a
positive integer $N$ such that $N K_R$ is Cartier. This option allows this
search to be bypassed if this integer is already known, by setting
QGorensteinIndex => N.

Functions with optional argument named QGorensteinIndex:
========================================================

  * "isFRegular(...,QGorensteinIndex=>...)" -- see isFRegular,
    -- whether a ring or pair is strongly F-regular
  * "testIdeal(...,QGorensteinIndex=>...)" -- see testIdeal,
    -- compute a test ideal in a Q-Gorenstein ring

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

The object QGorensteinIndex, is a symbol (Macaulay2Doc).

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

The source of this document is in TestIdeals/testIdealsDoc.m2:106:0.

Safe -- a valid value for the option FrobeniusPowerStrategy
***********************************************************

See also
========

  * FrobeniusPowerStrategy -- an option for
    frobeniusPower

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

The object Safe, is a symbol (Macaulay2Doc).

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

The source of this document is in TestIdeals/frobeniusPowersDoc.m2:157:0.

Substitution -- a valid value for the option FrobeniusRootStrategy
******************************************************************

See also
========

  * FrobeniusRootStrategy -- an option for
    various functions

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

The object Substitution, is a symbol (Macaulay2Doc).

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

The source of this document is in TestIdeals/EthRootsDoc.m2:266:0.

testElement -- find a test element of a ring
********************************************

  * Usage:
        testElement(R)
  * Inputs:
      * R, a ring (Macaulay2Doc), a quotient of a polynomial ring
  * Optional inputs (Macaulay2Doc),:
      * AssumeDomain => a Boolean value (Macaulay2Doc), default
        value false, assumes the ring is a domain
  * Outputs:
      * a ring element (Macaulay2Doc), a test element of R

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

Given $R = S/I$, where $S$ is a polynomial ring, the function testElement finds
an element of the ambient ring $S$ whose image in $R$ is a test element of $R$.
This is done by finding a minor of the jacobian of $I$ that does not lie in any
minimal prime of $I$. This function considers random minors until one is found,
instead of computing all minors. Thus, repeated calls will not always produce
the same answer.

+----------------------------------------+
|i1 : R = ZZ/11[x,y,z]/(x^3 + y^3 + z^3);|
+----------------------------------------+
|i2 : apply(1..5, i -> testElement(R))   |
|                                        |
|        2    2     2     2    2         |
|o2 = (2y , 2x , -3x , -4x , -y )        |
|                                        |
|o2 : Sequence                           |
+----------------------------------------+

If the option AssumeDomain (default value false) is set to true, then
testElement does not compute the minimal primes of $I$. This can result in a
substantial speedup in some cases.

Ways to use testElement:
========================

  * "testElement(Ring)"

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

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

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

The source of this document is in TestIdeals/testIdealsDoc.m2:73:0.

testIdeal -- compute a test ideal in a Q-Gorenstein ring
********************************************************

  * Usage:
        testIdeal(R)
        testIdeal(t, f)
        testIdeal(tList, fList)
  * Inputs:
      * R, a ring (Macaulay2Doc), a $\mathbb{Q}$-Gorenstein ring
      * f, a ring element (Macaulay2Doc), the element in a
        pair
      * t, a number (Macaulay2Doc), the formal exponent to which
        f is raised
      * fList, a list (Macaulay2Doc), consisting of ring elements
        f_1,\ldots,f_n, for a pair
      * tList, a list (Macaulay2Doc), consisting of formal
        exponents t_1,\ldots,t_n for the elements of fList
  * Optional inputs (Macaulay2Doc),:
      * AssumeDomain => a Boolean value (Macaulay2Doc), default
        value false, assumes the ring is an integral domain
      * FrobeniusRootStrategy => a symbol (Macaulay2Doc), default
        value Substitution, selects the strategy for internal frobeniusRoot
        calls
      * 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
  * Outputs:
      * an ideal (Macaulay2Doc), the test ideal \tau(R),
        \tau(R,f^{t}), or \tau(R,f_1^{t_1}\ldots f_n^{t_n}), depending on the
        arguments passed

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

Given a normal $\mathbb{Q}$-Gorenstein ring $R$, testIdeal(R) simply computes
the test ideal \tau($R$).

+---------------------------------------+
|i1 : R = ZZ/5[x,y,z]/(x^3 + y^3 + z^3);|
+---------------------------------------+
|i2 : testIdeal(R)                      |
|                                       |
|o2 = ideal (z, y, x)                   |
|                                       |
|o2 : Ideal of R                        |
+---------------------------------------+
+---------------------------------------------+
|i3 : S = ZZ/5[x,y,z,w];                      |
+---------------------------------------------+
|i4 : T = ZZ/5[a,b];                          |
+---------------------------------------------+
|i5 : f = map(T, S, {a^3, a^2*b, a*b^2, b^3});|
|                                             |
|o5 : RingMap T <-- S                         |
+---------------------------------------------+
|i6 : R = S/(ker f);                          |
+---------------------------------------------+
|i7 : testIdeal(R)                            |
|                                             |
|o7 = ideal 1                                 |
|                                             |
|o7 : Ideal of R                              |
+---------------------------------------------+

Given a nonnegative rational number $t$ and an element $f$ of a normal
$\mathbb{Q}$-Gorenstein ring $R$, testIdeal(t,f) computes the test ideal
\tau($R$, $f^{ t}$).

+-----------------------------------------------------------+
|i8 : R = ZZ/5[x,y,z];                                      |
+-----------------------------------------------------------+
|i9 : f = y^2 - x^3;                                        |
+-----------------------------------------------------------+
|i10 : apply({1/2, 4/5, 5/6, 1}, t -> testIdeal(t, f) )     |
|                                                           |
|                                                   3    2  |
|o10 = {ideal 1, ideal (y, x), ideal (y, x), ideal(x  - y )}|
|                                                           |
|o10 : List                                                 |
+-----------------------------------------------------------+
|i11 : R = ZZ/7[x,y,z];                                     |
+-----------------------------------------------------------+
|i12 : f = y^2 - x^3;                                       |
+-----------------------------------------------------------+
|i13 : apply({1/2, 4/5, 5/6, 1}, t -> testIdeal(t, f) )     |
|                                                           |
|                                              3    2       |
|o13 = {ideal 1, ideal 1, ideal (y, x), ideal(x  - y )}     |
|                                                           |
|o13 : List                                                 |
+-----------------------------------------------------------+

The ring $R$ need not be a polynomial ring, as the next example illustrates.

+-----------------------------------+
|i14 : R = ZZ/11[x,y,z]/(x^2 - y*z);|
+-----------------------------------+
|i15 : testIdeal(1/2, y)            |
|                                   |
|o15 = ideal (y, x)                 |
|                                   |
|o15 : Ideal of R                   |
+-----------------------------------+
|i16 : testIdeal(1/3, y)            |
|                                   |
|o16 = ideal 1                      |
|                                   |
|o16 : Ideal of R                   |
+-----------------------------------+

Given nonnegative rational numbers $t_1, t_2, \ldots$ and ring elements $f_1,
f_2, \ldots$, testIdeal(\{t_1,t_2,\ldots\},\{f_1,f_2,\ldots\}) computes the
test ideal \tau($R$, $f_1^{t_1} f_2^{t_2}\cdots$).

+-----------------------------------+
|i17 : R = ZZ/7[x,y];               |
+-----------------------------------+
|i18 : L = {x, y, x + y};           |
+-----------------------------------+
|i19 : f = x*y*(x + y);             |
+-----------------------------------+
|i20 : testIdeal({2/3, 2/3, 2/3}, L)|
|                                   |
|o20 = ideal (y, x)                 |
|                                   |
|o20 : Ideal of R                   |
+-----------------------------------+
|i21 : testIdeal(2/3, f)            |
|                                   |
|o21 = ideal (y, x)                 |
|                                   |
|o21 : Ideal of R                   |
+-----------------------------------+
|i22 : testIdeal({3/4, 2/3, 3/5}, L)|
|                                   |
|o22 = ideal (y, x)                 |
|                                   |
|o22 : Ideal of R                   |
+-----------------------------------+

It is often more efficient to pass a list, as opposed to finding a common
denominator and passing a single element, since testIdeal can do things in a
more intelligent way for such a list.

+-----------------------------------------------------+
|i23 : time testIdeal({3/4, 2/3, 3/5}, L)             |
| -- used 0.34214s (cpu); 0.234049s (thread); 0s (gc) |
|                                                     |
|o23 = ideal (y, x)                                   |
|                                                     |
|o23 : Ideal of R                                     |
+-----------------------------------------------------+
|i24 : time testIdeal(1/60, x^45*y^40*(x + y)^36)     |
| -- used 0.394644s (cpu); 0.326374s (thread); 0s (gc)|
|                                                     |
|o24 = ideal (y, x)                                   |
|                                                     |
|o24 : Ideal of R                                     |
+-----------------------------------------------------+

The option AssumeDomain (default value false) is used when finding a test
element. The option FrobeniusRootStrategy (default value Substitution) is
passed to internal frobeniusRoot, calls.

When working in a $\mathbb{Q}$-Gorenstein ring $R$, testIdeal looks for a
positive integer $N$ such that $N K_R$ is Cartier. The option MaxCartierIndex
(default value $10$) controls the maximum value of $N$ to consider in this
search. If the smallest such $N$ turns out to be greater than the value passed
to MaxCartierIndex, then testIdeal returns an error.

The $\mathbb{Q}$-Gorenstein index can be specified by the user through the
option QGorensteinIndex; when this option is used, the search for $N$ is
bypassed, and the option MaxCartierIndex ignored.

See also
========

  * testModule -- find the parameter test module of a
    reduced ring
  * isFRegular -- whether a ring or pair is strongly
    F-regular

Ways to use testIdeal:
======================

  * "testIdeal(List,List)"
  * "testIdeal(Number,RingElement)"
  * "testIdeal(Ring)"

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

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

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

The source of this document is in TestIdeals/testIdealsDoc.m2:209:0.

testModule -- find the parameter test module of a reduced ring
**************************************************************

  * Usage:
        testModule()
        testModule(R)
        testModule(t, f)
        testModule(tList, fList)
  * Inputs:
      * R, a ring (Macaulay2Doc),
      * f, a ring element (Macaulay2Doc), the element in a
        pair
      * t, a number (Macaulay2Doc), the formal exponent to which
        f is raised
      * fList, a list (Macaulay2Doc), consisting of ring elements
        f_1,\ldots,f_n, for a pair
      * tList, a list (Macaulay2Doc), consisting of formal
        exponents t_1,\ldots,t_n for the elements of fList
  * Optional inputs (Macaulay2Doc),:
      * AssumeDomain => a Boolean value (Macaulay2Doc), default
        value false, assumes the ring passed is an integral domain
      * FrobeniusRootStrategy => a symbol (Macaulay2Doc), default
        value Substitution, selects the strategy for internal frobeniusRoot
        calls
      * CanonicalIdeal => an ideal (Macaulay2Doc), default value
        null, specifies the canonical ideal (so the function does not recompute
        it)
      * CurrentRing => a ring (Macaulay2Doc), default value null,
        specifies the ring to work with
      * GeneratorList => a list (Macaulay2Doc), default value null,
        specifies the element (or elements) of the ambient polynomial ring that
        determines the Frobenius trace on the canonical module
  * Outputs:
      * a sequence (Macaulay2Doc), consisting of three
        elements: the parameter test module of R, (R,f^t), or
        (R,f_1^{t_1}\ldots f_n^{t_n}), represented as a submodule of a
        canonical module; the canonical module of which it is a submodule
        (given as an ideal of R); the element (or elements) of the ambient
        polynomial ring that determines the Frobenius trace on the canonical
        module

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

The function testModule computes the parameter test module of a ring $R$,
returning a sequence with three elements: the parameter test submodule (as a
submodule of the canonical module), the canonical module of which it is a
subset, and the element (or elements) of the ambient polynomial ring that
determines the Frobenius trace on the canonical module (see
frobeniusTraceOnCanonicalModule).

+-----------------------------------------------------------------------------+
|i1 : R = ZZ/7[x,y,z]/(x^3 + y^3 + z^3);                                      |
+-----------------------------------------------------------------------------+
|i2 : testModule(R)                                                           |
|                                                                             |
|                                 18    15 3    12 6    9 9    6 12    3 15   |
|o2 = (ideal (z, y, x), ideal 1, x   - x  y  + x  y  - x y  + x y   - x y   + |
|     ------------------------------------------------------------------------|
|      18    15 3     12 3 3     9 6 3     6 9 3     3 12 3    15 3    12 6   |
|     y   - x  z  + 2x  y z  - 3x y z  - 3x y z  + 2x y  z  - y  z  + x  z  - |
|     ------------------------------------------------------------------------|
|       9 3 6    6 6 6     3 9 6    12 6    9 9     6 3 9     3 6 9    9 9    |
|     3x y z  - x y z  - 3x y z  + y  z  - x z  - 3x y z  - 3x y z  - y z  +  |
|     ------------------------------------------------------------------------|
|      6 12     3 3 12    6 12    3 15    3 15    18                          |
|     x z   + 2x y z   + y z   - x z   - y z   + z  )                         |
|                                                                             |
|o2 : Sequence                                                                |
+-----------------------------------------------------------------------------+

The canonical module returned is always embedded as an ideal of $R$, and not of
the ambient polynomial ring. Likewise, the parameter test module is viewed as a
subideal of that ideal of $R$.

Because the ring in the example above is a Gorenstein ring, the ambient
canonical module is the unit ideal. In contrast, the ring in the next example
is not Gorenstein.

+-----------------------------------------------------------------------------+
|i3 : S = ZZ/3[x,y,u,v];                                                      |
+-----------------------------------------------------------------------------+
|i4 : T = ZZ/3[a,b];                                                          |
+-----------------------------------------------------------------------------+
|i5 : f = map(T, S, {a^3, a^2*b, a*b^2, b^3});                                |
|                                                                             |
|o5 : RingMap T <-- S                                                         |
+-----------------------------------------------------------------------------+
|i6 : R = S/(ker f);                                                          |
+-----------------------------------------------------------------------------+
|i7 : testModule(R)                                                           |
|                                                                             |
|                                       5     4 2 2      2 3 2    2 4 2    5 3|
|o7 = (ideal (v, u), ideal (v, u), x*y*u v + y u v  + x*y u v  + x u v  + y v |
|     ------------------------------------------------------------------------|
|          3   3    2   2 3    2 2 4    3   4                                 |
|     + x*y u*v  + x y*u v  + x y v  + x u*v )                                |
|                                                                             |
|o7 : Sequence                                                                |
+-----------------------------------------------------------------------------+

Note that the output in this case has the parameter test module equal to the
canonical module, as it should be, since the ring is $F$-rational. Let us now
consider a non-Gorenstein example that is not $F$-rational.

+---------------------------------------------------------------------------+
|i8 : R = ZZ/5[x,y,z]/(y*z, x*z, x*y);                                      |
+---------------------------------------------------------------------------+
|i9 : (testMod, canMod, u) = testModule(R)                                  |
|                                                                           |
|              2   2   2                            8 4 4    4 8 4    4 4 8 |
|o9 = (ideal (z , y , x ), ideal (y + 2z, x + 2z), x y z  + x y z  + x y z )|
|                                                                           |
|o9 : Sequence                                                              |
+---------------------------------------------------------------------------+
|i10 : testMod : canMod                                                     |
|                                                                           |
|o10 = ideal (z, y, x)                                                      |
|                                                                           |
|o10 : Ideal of R                                                           |
+---------------------------------------------------------------------------+

This function can be used to compute parameter test ideals in Cohen-Macaulay
rings, as an alternative to parameterTestIdeal.

+--------------------------------------------------------------+
|i11 : S = ZZ/2[X_1..X_5];                                     |
+--------------------------------------------------------------+
|i12 : E = matrix {{X_1, X_2, X_2, X_5}, {X_4, X_4, X_3, X_1}};|
|                                                              |
|              2      4                                        |
|o12 : Matrix S  <-- S                                         |
+--------------------------------------------------------------+
|i13 : R = S/minors(2, E);                                     |
+--------------------------------------------------------------+
|i14 : (testMod, canMod, u) = testModule(R);                   |
+--------------------------------------------------------------+
|i15 : testMod : canMod                                        |
|                                                              |
|o15 = ideal (X  + X , X , X )                                 |
|              3    4   2   1                                  |
|                                                              |
|o15 : Ideal of R                                              |
+--------------------------------------------------------------+
|i16 : parameterTestIdeal(R)                                   |
|                                                              |
|o16 = ideal (X  + X , X , X )                                 |
|              3    4   2   1                                  |
|                                                              |
|o16 : Ideal of R                                              |
+--------------------------------------------------------------+

The function testModule can also be used to compute the parameter test module
of a pair ($R, f^{ t}$), or ($R,f_1^{t_1}\cdots f_n^{t_n}$).

+------------------------------------+
|i17 : R = ZZ/7[x,y];                |
+------------------------------------+
|i18 : f = y^2 - x^3;                |
+------------------------------------+
|i19 : testModule(5/6, f)            |
|                                    |
|o19 = (ideal (y, x), ideal 1, 1)    |
|                                    |
|o19 : Sequence                      |
+------------------------------------+
|i20 : testModule(5/7, f)            |
|                                    |
|o20 = (ideal 1, ideal 1, 1)         |
|                                    |
|o20 : Sequence                      |
+------------------------------------+
|i21 : g = x^2 - y^3;                |
+------------------------------------+
|i22 : testModule({1/2, 1/2}, {f, g})|
|                                    |
|o22 = (ideal (y, x), ideal 1, 1)    |
|                                    |
|o22 : Sequence                      |
+------------------------------------+

Sometimes it is convenient to specify the ambient canonical module, or the
choice of element(s) that determines the Frobenius trace on the canonical
module, across multiple calls of testModule. This can be done by using the
options CanonicalIdeal and GeneratorList.

+--------------------------------------------------------------------------+
|i23 : R = ZZ/5[x,y,z]/(x*y, y*z, z*x);                                    |
+--------------------------------------------------------------------------+
|i24 : I = ideal(x - z, y - z);                                            |
|                                                                          |
|o24 : Ideal of R                                                          |
+--------------------------------------------------------------------------+
|i25 : testModule(CanonicalIdeal => I)                                     |
|                                                                          |
|               2   2   2                          8 4 4    4 8 4    4 4 8 |
|o25 = (ideal (z , y , x ), ideal (y - z, x - z), x y z  + x y z  + x y z )|
|                                                                          |
|o25 : Sequence                                                            |
+--------------------------------------------------------------------------+

Finally, the option FrobeniusRootStrategy is passed to any calls of
frobeniusRoot, and the option AssumeDomain is used when
computing a test element.

See also
========

  * testIdeal -- compute a test ideal in a Q-Gorenstein ring
  * parameterTestIdeal -- compute the parameter test
    ideal of a Cohen-Macaulay ring
  * FPureModule -- compute the submodule of the canonical
    module stable under the image of the trace of Frobenius

Ways to use testModule:
=======================

  * "testModule(List,List)"
  * "testModule(Number,RingElement)"
  * "testModule(Ring)"
  * testModule() (missing documentation)

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

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

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

The source of this document is in TestIdeals/parameterTestIdealDoc.m2:173:0.