This is SymbolicPowers.info, produced by Macaulay2, version 1.21

SymbolicPowers -- symbolic powers of ideals
*******************************************

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

This package gives the ability to compute symbolic powers, and related
invariants, of ideals in a polynomial ring or a quotient of a polynomial ring.
For example, in the context of the default behavior, see symbolicPower,
assumes the following definition of the symbolic power of an
ideal  $I$,  $$I^{(n)} = \cap_{p \in Ass(R/I)}(I^nR_p \cap R ),$$ as defined by
M. Hochster and C. Huneke.

Alternatively, as defined in Villarreal, see symbolicPower,
has the option to restrict to minimal primes versus use all associated primes
with UseMinimalPrimes. In particular, the symbolic
power of an ideal $I$  is defined as $$I^{(n)} = \cap_{p \in Min(R/I)}(I^nR_p
\cap R ),$$ where  $Min(R/I)$ is the set of minimal primes in  $I$,

  * M. Hochster and C. Huneke. Comparison of symbolic and ordinary powers of
    ideals. Invent. Math. 147 (2002), no. 2, 349–369.
  * R. Villarreal. Monomial algebras. Second edition. Monographs and Research
    Notes in Mathematics. CRC Press, Boca Raton, FL, 2015. xviii+686 pp. ISBN:
    978-1-4822-3469-5.
  * Hailong Dao, Alessandro De Stefani, Eloísa Grifo, Craig Huneke, and Luis
    Núñez-Betancourt. Symbolic powers of ideals.in Singularities and
    foliations. Geometry, topology and applications, pp. 387-432, Springer
    Proc. Math. Stat., 222, Springer, Cham, 2018. See
    https://arxiv.org/abs/1708.03010 (see https://arxiv.org/abs/1708.03010 ).

Contributors
============

The following people have generously contributed code or worked on our code at
various Macaulay2 workshops.
  * Ben Drabkin
  * Andrew Conner
  * Alexandra Seceleanu
  * Branden Stone
  * Xuehua (Diana) Zhong

A Quick Introduction
====================

  * Computing symbolic powers of an ideal
  * Alternative algorithm to compute the symbolic powers of a prime ideal in positive characteristic

Other Related Examples
======================

  * The Containment Problem
  * Sullivant's algorithm for primes in a polynomial ring
  * The Packing Problem

Author
======

  * Eloisa Grifo (see http://www-personal.umich.edu/~grifo/ ) <grifo@umich.edu>

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

Version 2.0 of this package was accepted for publication in volume 9 (see
https://msp.org/jsag/2019/9-1/ ) of The Journal of Software for Algebra and
Geometry (see http://j-sag.org/ ) on 20 May 2019, in the article Calculations
involving symbolic powers (see https://msp.org/jsag/2019/9-1/p09.xhtml ). That
version can be obtained from the journal (see
https://msp.org/jsag/2019/9-1/jsag-v9-n1-x09-SymbolicPowers.m2 ) or from the
Macaulay2 source code repository (see
http://github.com/Macaulay2/M2/blob/fe3eea250b0c2c9a0ebbbd84cf44b7a52da63fc0/M2
/Macaulay2/packages/SymbolicPowers.m2 ).

Version
=======

This documentation describes version 2.0 of SymbolicPowers.

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

The source code from which this documentation is derived is in the file
SymbolicPowers.m2 (see common/share/Macaulay2/SymbolicPowers.m2 ).

Exports
=======

  * Functions and commands
      * assPrimesHeight -- The heights of all
        associated primes
      * asymptoticRegularity -- approximates the
        asymptotic regularity
      * bigHeight -- computes the big height of an ideal
      * containmentProblem -- computes the smallest
        symbolic power contained in a power of an ideal.
      * isKonig -- determines if a given square-free ideal is
        Konig.
      * isPacked -- determines if a given square-free ideal is
        packed.
      * isSymbolicEqualOrdinary -- tests if
        symbolic power is equal to ordinary power
      * isSymbPowerContainedinPower, --
        tests if the m-th symbolic power an ideal is contained the n-th power
      * joinIdeals -- Computes the join of the given ideals
      * lowerBoundResurgence -- computes a lower
        bound for the resurgence of a given ideal.
      * minDegreeSymbPower -- returns the minimal
        degree of a given symbolic power of an ideal.
      * minimalPart -- intersection of the minimal
        components
      * noPackedAllSubs -- finds all substitutions of
        variables by 1 and/or 0 for which ideal is not Konig.
      * noPackedSub -- finds a substitution of variables by
        1 and/or 0 for which an ideal is not Konig.
      * squarefreeGens -- returns all square-free
        monomials in a minimal generating set of the given ideal.
      * squarefreeInCodim -- finds square-fee
        monomials in ideal raised to the power of the codimension.
      * symbolicDefect -- computes the symbolic defect
        of an ideal
      * symbolicPolyhedron -- computes the symbolic
        polyhedron for a monomial ideal.
      * symbolicPower -- computes the symbolic power of
        an ideal.
      * symbolicPowerJoin -- computes the symbolic
        power of the prime ideal using join of ideals.
      * symbPowerPrimePosChar
      * waldschmidt -- computes the Waldschmidt constant
        for a homogeneous ideal.
  * Methods
      * "assPrimesHeight(Ideal)" -- see assPrimesHeight,
        -- The heights of all associated primes
      * "asymptoticRegularity(Ideal)" -- see asymptoticRegularity,
        -- approximates the asymptotic regularity
      * "bigHeight(Ideal)" -- see bigHeight, -- computes the
        big height of an ideal
      * "containmentProblem(Ideal,ZZ)" -- see containmentProblem,
        -- computes the smallest symbolic power contained
        in a power of an ideal.
      * "isKonig(Ideal)" -- see isKonig, -- determines if a
        given square-free ideal is Konig.
      * "isPacked(Ideal)" -- see isPacked, -- determines if a
        given square-free ideal is packed.
      * "isSymbolicEqualOrdinary(Ideal,ZZ)" -- see
        isSymbolicEqualOrdinary, -- tests if symbolic
        power is equal to ordinary power
      * "isSymbPowerContainedinPower(Ideal,ZZ,ZZ)" -- see
        isSymbPowerContainedinPower, -- tests if
        the m-th symbolic power an ideal is contained the n-th power
      * "joinIdeals(Ideal,Ideal)" -- see joinIdeals, --
        Computes the join of the given ideals
      * "lowerBoundResurgence(Ideal)" -- see lowerBoundResurgence,
        -- computes a lower bound for the resurgence of a
        given ideal.
      * "minDegreeSymbPower(Ideal,ZZ)" -- see minDegreeSymbPower,
        -- returns the minimal degree of a given symbolic
        power of an ideal.
      * "minimalPart(Ideal)" -- see minimalPart, --
        intersection of the minimal components
      * "noPackedAllSubs(Ideal)" -- see noPackedAllSubs,
        -- finds all substitutions of variables by 1 and/or 0 for which ideal
        is not Konig.
      * "noPackedSub(Ideal)" -- see noPackedSub, -- finds a
        substitution of variables by 1 and/or 0 for which an ideal is not
        Konig.
      * "squarefreeGens(Ideal)" -- see squarefreeGens, --
        returns all square-free monomials in a minimal generating set of the
        given ideal.
      * "squarefreeInCodim(Ideal)" -- see squarefreeInCodim,
        -- finds square-fee monomials in ideal raised to the
        power of the codimension.
      * "symbolicDefect(Ideal,ZZ)" -- see symbolicDefect,
        -- computes the symbolic defect of an ideal
      * "symbolicPolyhedron(Ideal)" -- see symbolicPolyhedron,
        -- computes the symbolic polyhedron for a monomial
        ideal.
      * "symbolicPolyhedron(MonomialIdeal)" -- see symbolicPolyhedron,
        -- computes the symbolic polyhedron for a monomial
        ideal.
      * "symbolicPower(Ideal,ZZ)" -- see symbolicPower, --
        computes the symbolic power of an ideal.
      * "symbolicPowerJoin(Ideal,ZZ)" -- see symbolicPowerJoin,
        -- computes the symbolic power of the prime ideal
        using join of ideals.
      * "symbPowerPrimePosChar(Ideal,ZZ)" -- see symbPowerPrimePosChar,
      * "waldschmidt(Ideal)" -- see waldschmidt, -- computes
        the Waldschmidt constant for a homogeneous ideal.
      * "waldschmidt(MonomialIdeal)" -- see waldschmidt, --
        computes the Waldschmidt constant for a homogeneous ideal.
  * Symbols
      * CIPrimes -- compute the symbolic power by taking the
        intersection of the powers of the primary components
      * InSymbolic -- an optional parameter used in
        containmentProblem.
      * SampleSize -- optional parameter used for
        approximating asymptotic invariants that are defined as limits.
      * UseMinimalPrimes -- an option to only use
        minimal primes to calculate symbolic powers
      * UseWaldschmidt -- optional input for computing a
        lower bound for the resurgence of a given ideal.

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

The object SymbolicPowers, is a package (Macaulay2Doc).

A quick introduction to this package -- How to use this package
***************************************************************

Here is a list of some examples which illustrate various parts of this package.

First examples which show how to use this package

$\bullet$ See Computing symbolic powers of an ideal,

$\bullet$ See Alternative algorithm to compute the symbolic powers of a prime ideal in positive characteristic,

Other examples which illustrate this package

$\bullet$ See The Containment Problem,

$\bullet$ See Sullivant's algorithm for primes in a polynomial ring,

The Packing Problem

$\bullet$ See The Packing Problem,

Alternative algorithm to compute the symbolic powers of a prime ideal in positive characteristic
************************************************************************************************

Given a prime ideal P in a regular ring of positive characteristic,
symbPowerPrimePosChar computes its symbolic powers. Unfortunately, this
algorithm is slower than others.

+-----------------------------------------------------------------------------+
|i1 : R = ZZ/7[x,y,z]                                                         |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : P = ker map(ZZ/7[t],R,{t^3,t^4,t^5})                                    |
|                                                                             |
|             2         2     2   3                                           |
|o2 = ideal (y  - x*z, x y - z , x  - y*z)                                    |
|                                                                             |
|o2 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i3 : J = symbPowerPrimePosChar(P,2)                                          |
|                                                                             |
|             4       2     2 2   2 3    3       2 2      3   3 2    4     3  |
|o3 = ideal (y  - 2x*y z + x z , x y  - x y*z - y z  + x*z , x y  - x z - y z |
|     ------------------------------------------------------------------------|
|            2   5      3     2       3                                       |
|     + x*y*z , x  + x*y  - 3x y*z + z )                                      |
|                                                                             |
|o3 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+

The symbolic powers of P do not coincide with its powers.

+-------------+
|i4 : J == P^2|
|             |
|o4 = false   |
+-------------+

We can also test it a bit faster, without computing the symbolic powers of $P$.

+---------------------------------+
|i5 : isSymbolicEqualOrdinary(P,2)|
|                                 |
|o5 = false                       |
+---------------------------------+

assPrimesHeight -- The heights of all associated primes
*******************************************************

Synopsis
========

  * Usage:
        assPrimesHeight(I)
  * Inputs:
      * I, an ideal (Macaulay2Doc),
  * Outputs:
      * a list (Macaulay2Doc), the heights of all associated primes
        of I

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

The algorithm is based on the following result by Eisenbud-Huneke-Vasconcelos,
in their 1993 Inventiones Mathematicae paper:

$\bullet$ codim $Ext^d(M,R) \geq d$ for all $d$

$\bullet$ If $P$ is an associated prime of $M$ of codimension $d :=$ codim $P >
$ codim $M$, then codim $Ext^d(M,R) = d$ and the annihilator of $Ext^d(M,R)$ is
contained in $P$

$\bullet$ If codim $Ext^d(M,R) = d$, then there really is an associated prime
of codimension $d$.

+-------------------------------------------+
|i1 : R = QQ[x,y,z,a,b]                     |
|                                           |
|o1 = R                                     |
|                                           |
|o1 : PolynomialRing                        |
+-------------------------------------------+
|i2 : J = intersect(ideal(x,y,z),ideal(a,b))|
|                                           |
|o2 = ideal (z*b, y*b, x*b, z*a, y*a, x*a)  |
|                                           |
|o2 : Ideal of R                            |
+-------------------------------------------+
|i3 : assPrimesHeight(J)                    |
|                                           |
|o3 = {2, 3}                                |
|                                           |
|o3 : List                                  |
+-------------------------------------------+

Caveat
======

bigHeight works faster than using assPrimesHeight and then taking the maximum

See also
========

  * bigHeight -- computes the big height of an ideal
  * codim (Macaulay2Doc) -- compute the codimension

Ways to use assPrimesHeight :
=============================

  * "assPrimesHeight(Ideal)"

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

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

asymptoticRegularity -- approximates the asymptotic regularity
**************************************************************

Synopsis
========

  * Usage:
        asymptoticRegularity(I,SampleSize=>ZZ)
  * Optional inputs (Macaulay2Doc),:
      * SampleSize,
        => ..., default value 10, optional parameter used for
        approximating asymptotic invariants that are defined as limits.

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

We give an approximation of the asymptotic regularity by taking the minimum
value of $\frac{reg(I^{(n)})}{n}$ over a finite number of exponents $n$, namely
for $n$ from 1 to the optional parameter SampleSize,; the
default value for SampleSize, is 10.

+-----------------------------------------------------+
|i1 : R = QQ[x,y,z];                                  |
+-----------------------------------------------------+
|i2 : J = ideal (x*(y^3-z^3),y*(z^3-x^3),z*(x^3-y^3));|
|                                                     |
|o2 : Ideal of R                                      |
+-----------------------------------------------------+
|i3 : asymptoticRegularity(J, SampleSize=>5)          |
|                                                     |
|o3 = 4                                               |
|                                                     |
|o3 : QQ                                              |
+-----------------------------------------------------+

Ways to use asymptoticRegularity :
==================================

  * "asymptoticRegularity(Ideal)"

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

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

asymptoticRegularity(...,SampleSize=>...) -- optional parameter used for approximating asymptotic invariants that are defined as limits.
****************************************************************************************************************************************

Synopsis
========

  * Usage:
        asymptoticRegularity(I,SampleSize=>ZZ)

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

We give an approximation of the asymptotic regularity by taking the minimum
value of $\frac{reg(I^{(n)})}{n}$ over a finite number of exponents $n$, namely
for $n$ from 1 to the optional parameter SampleSize,; the
default value for SampleSize, is 10.

+-----------------------------------------------------+
|i1 : R = QQ[x,y,z];                                  |
+-----------------------------------------------------+
|i2 : J = ideal (x*(y^3-z^3),y*(z^3-x^3),z*(x^3-y^3));|
|                                                     |
|o2 : Ideal of R                                      |
+-----------------------------------------------------+
|i3 : asymptoticRegularity(J, SampleSize=>5)          |
|                                                     |
|o3 = 4                                               |
|                                                     |
|o3 : QQ                                              |
+-----------------------------------------------------+

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

  * Default value: 10
  * Function: asymptoticRegularity, -- approximates
    the asymptotic regularity
  * Option key: SampleSize, -- optional parameter used for
    approximating asymptotic invariants that are defined as limits.

Functions with optional argument named SampleSize :
===================================================

  * asymptoticRegularity(...,SampleSize=>...)
    -- optional
    parameter used for approximating asymptotic invariants that are defined as
    limits.
  * lowerBoundResurgence(...,SampleSize=>...)
    -- optional
    parameter used for approximating asymptotic invariants that are defined as
    limits.
  * waldschmidt(...,SampleSize=>...)
    -- optional parameter
    used for approximating asymptotic invariants that are defined as limits.

bigHeight -- computes the big height of an ideal
************************************************

Synopsis
========

  * Usage:
        bigHeight(I)
  * Inputs:
      * I, an ideal (Macaulay2Doc),
  * Outputs:
      * an integer (Macaulay2Doc), the largest height of an
        associated prime of I

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

Big height of an ideal: the largest height of an associated prime. The
algorithm is based on the following result by Eisenbud-Huneke-Vasconcelos, in
their 1993 Inventiones Mathematicae paper:

$\bullet$ codim $Ext^d(M,R) \geq d$ for all $d$

$\bullet$ If $P$ is an associated prime of $M$ of codimension $d :=$ codim $P >
$ codim $M$, then codim $Ext^d(M,R) = d$ and the annihilator of $Ext^d(M,R)$ is
contained in $P$

$\bullet$ If codim $Ext^d(M,R) = d$, then there really is an associated prime
of codimension $d$.

+-------------------------------------------+
|i1 : R = QQ[x,y,z,a,b]                     |
|                                           |
|o1 = R                                     |
|                                           |
|o1 : PolynomialRing                        |
+-------------------------------------------+
|i2 : J = intersect(ideal(x,y,z),ideal(a,b))|
|                                           |
|o2 = ideal (z*b, y*b, x*b, z*a, y*a, x*a)  |
|                                           |
|o2 : Ideal of R                            |
+-------------------------------------------+
|i3 : bigHeight(J)                          |
|                                           |
|o3 = 3                                     |
+-------------------------------------------+

Caveat
======

bigHeight works faster than assPrimesHeight

See also
========

  * codim (Macaulay2Doc) -- compute the codimension
  * assPrimesHeight -- The heights of all associated
    primes

Ways to use bigHeight :
=======================

  * "bigHeight(Ideal)"

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

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

CIPrimes -- compute the symbolic power by taking the intersection of the powers of the primary components
*********************************************************************************************************

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

The default value is false.  When defined to be true, the symbolicPower,
function tests whether the primary components are complete
intersections having the same height.  If each component is, then the function
takes the intersection of the powers of the components: $$I^{(n)}=\cap_{p\in
Ass(R/I)} p^n.$$

See also
========

  * containmentProblem -- computes the smallest
    symbolic power contained in a power of an ideal.
  * isSymbPowerContainedinPower -- tests if
    the m-th symbolic power an ideal is contained the n-th power
  * symbolicDefect -- computes the symbolic defect of an
    ideal
  * symbolicPower -- computes the symbolic power of an
    ideal.

Functions with optional argument named CIPrimes :
=================================================

  * "containmentProblem(...,CIPrimes=>...)"
  * "isSymbPowerContainedinPower(...,CIPrimes=>...)"
  * "symbolicDefect(...,CIPrimes=>...)"
  * "symbolicPower(...,CIPrimes=>...)"

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

The object CIPrimes, is a symbol (Macaulay2Doc).

Computing symbolic powers of an ideal
*************************************

Given an ideal, symbolicPower computes a given symbolic power.

+-----------------------------------------------------------------------------+
|i1 : B = QQ[x,y,z];                                                          |
+-----------------------------------------------------------------------------+
|i2 : I = ideal(x*(y^3-z^3),y*(z^3-y^3),z*(x^3-y^3));                         |
|                                                                             |
|o2 : Ideal of B                                                              |
+-----------------------------------------------------------------------------+
|i3 : J = symbolicPower(I,3)                                                  |
|                                                                             |
|             3 6     9      3 3 4     6 4    3 7    3 7   6 3 2    9 2    6 5|
|o3 = ideal (x y z - y z - 2x y z  + 2y z  + x z  - y z , x y z  - y z  - x z |
|     ------------------------------------------------------------------------|
|         3 3 5     6 5     3 8     3 8   9 3    9 3     6 6     6 6     3 9  |
|     - 2x y z  + 3y z  + 2x z  - 2y z , x z  - y z  - 3x z  + 3y z  + 3x z  -|
|     ------------------------------------------------------------------------|
|       3 9   12     9 3     6 6    3 9     11       8 3       5 6      2 9   |
|     3y z , y   - 3y z  + 3y z  - y z , x*y   - 3x*y z  + 3x*y z  - x*y z ,  |
|     ------------------------------------------------------------------------|
|      2 10     2 7 3     2 4 6    2   9   3 9     9 3     3 3 6     6 6      |
|     x y   - 3x y z  + 3x y z  - x y*z , x y  - 3y z  - 3x y z  + 6y z  +    |
|     ------------------------------------------------------------------------|
|       3 9     3 9                                                           |
|     2x z  - 3y z )                                                          |
|                                                                             |
|o3 : Ideal of B                                                              |
+-----------------------------------------------------------------------------+

Various algorithms are used, in the following order:

1. If $I$ is squarefree monomial ideal, intersects the powers of the associated
primes of $I$;

2. If $I$ is monomial ideal, but not squarefree, takes an irredundant primary
decomposition of $I$ and intersects the powers of those ideals;

3. If $I$ is a saturated homogeneous ideal in a polynomial ring whose height is
one less than the dimension of the ring, returns the saturation of $I^n$;

4. If all the associated primes of $I$ have the same height, computes a primary
decomposition of $I^n$ and intersects the components with radical $I$;

5. If all else fails, compares the radicals of a primary decomposition of $I^n$
with the associated primes of $I$, and intersects the components corresponding
to minimal primes.

containmentProblem -- computes the smallest symbolic power contained in a power of an ideal.
********************************************************************************************

Synopsis
========

  * Usage:
        containmentProblem(I,n)
  * Inputs:
      * I, an ideal (Macaulay2Doc),
      * n, an integer (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * CIPrimes, => ..., default value false, compute the
        symbolic power by taking the intersection of the powers of the primary
        components
      * InSymbolic,
        => ..., default value false, an optional parameter used in
        containmentProblem.
      * UseMinimalPrimes, => ..., default value false,
        an option to only use minimal primes to calculate symbolic powers
  * Outputs:
      * an integer (Macaulay2Doc), the minimum value m such that the
        m-th symbolic power of I is contained in I^n

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

Given an ideal $I$ and an integer $n$, containementProblem returns the order of
the smallest symbolic power of $I$ contained in $I^n$.

+-----------------------------------+
|i1 : B = QQ[x,y,z];                |
+-----------------------------------+
|i2 : f = map(QQ[t],B,{t^3,t^4,t^5})|
|                                   |
|                      3   4   5    |
|o2 = map (QQ[t], B, {t , t , t })  |
|                                   |
|o2 : RingMap QQ[t] <--- B          |
+-----------------------------------+
|i3 : I = ker f;                    |
|                                   |
|o3 : Ideal of B                    |
+-----------------------------------+
|i4 : m = containmentProblem(I,2)   |
|                                   |
|o4 = 3                             |
+-----------------------------------+

See also
========

  * isSymbPowerContainedinPower -- tests if
    the m-th symbolic power an ideal is contained the n-th power

Ways to use containmentProblem :
================================

  * "containmentProblem(Ideal,ZZ)"

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

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

containmentProblem(...,InSymbolic=>...) -- an optional parameter used in containmentProblem.
********************************************************************************************

Synopsis
========

  * Usage:
        containmentProblem(I,n,InSymbolic => true)

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

Given an ideal I and an integer n, see InSymbolic, is used to ask
the following question: What is the largest power containing the symbolic power
$I^{(n)}$?

+-----------------------------------------------------+
|i1 : R = QQ[x,y,z];                                  |
+-----------------------------------------------------+
|i2 : J = ideal (x*(y^3-z^3),y*(z^3-x^3),z*(x^3-y^3));|
|                                                     |
|o2 : Ideal of R                                      |
+-----------------------------------------------------+
|i3 : containmentProblem(J,3,InSymbolic => true)      |
|                                                     |
|o3 = 1                                               |
+-----------------------------------------------------+

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

  * Default value: false (Macaulay2Doc),
  * Function: containmentProblem, -- computes the
    smallest symbolic power contained in a power of an ideal.
  * Option key: InSymbolic, -- an optional parameter used in
    containmentProblem.

Functions with optional argument named InSymbolic :
===================================================

  * containmentProblem(...,InSymbolic=>...)
    -- an optional
    parameter used in containmentProblem.

InSymbolic -- an optional parameter used in containmentProblem.
***************************************************************

See also
========

  * containmentProblem -- computes the smallest
    symbolic power contained in a power of an ideal.

Functions with optional argument named InSymbolic :
===================================================

  * containmentProblem(...,InSymbolic=>...)
    -- an optional
    parameter used in containmentProblem.

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

The object InSymbolic, is a symbol (Macaulay2Doc).

isKonig -- determines if a given square-free ideal is Konig.
************************************************************

Synopsis
========

  * Usage:
        isKonig(I)
  * Inputs:
      * I, an ideal (Macaulay2Doc),
  * Outputs:
      * a Boolean value (Macaulay2Doc),

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

Given a square-free monomial ideal $I$, determines if the ideal is Konig. A
square-free monomial ideal $I$ of codimension $c$ is Konig if it contains a
regular sequence of monomials of length $c$.

+----------------------------+
|i1 : R = QQ[x,y,z];         |
+----------------------------+
|i2 : I = ideal(x*y,y*z,x*z);|
|                            |
|o2 : Ideal of R             |
+----------------------------+
|i3 : isKonig(I)             |
|                            |
|o3 = false                  |
+----------------------------+

See also
========

  * squarefreeGens -- returns all square-free monomials
    in a minimal generating set of the given ideal.

Ways to use isKonig :
=====================

  * "isKonig(Ideal)"

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

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

isPacked -- determines if a given square-free ideal is packed.
**************************************************************

Synopsis
========

  * Usage:
        isPacked(I)
  * Inputs:
      * I, an ideal (Macaulay2Doc),
  * Outputs:
      * a Boolean value (Macaulay2Doc),

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

Given a square-free monomial ideal $I$, determines if the ideal is Konig. A
square-free monomial ideal $I$ of codimension $c$ is packed if every ideal
obtained from it by replacing any number of variables by 1 or 0 is Konig.

+----------------------------+
|i1 : R = QQ[x,y,z];         |
+----------------------------+
|i2 : I = ideal(x*y,y*z,x*z);|
|                            |
|o2 : Ideal of R             |
+----------------------------+
|i3 : isPacked(I)            |
|                            |
|o3 = false                  |
+----------------------------+

See also
========

  * squarefreeGens -- returns all square-free monomials
    in a minimal generating set of the given ideal.

Ways to use isPacked :
======================

  * "isPacked(Ideal)"

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

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

isSymbolicEqualOrdinary -- tests if symbolic power is equal to ordinary power
*****************************************************************************

Synopsis
========

  * Usage:
        isSymbolicEqualOrdinary(I,n)
  * Inputs:
      * I, an ideal (Macaulay2Doc),
      * n, an integer (Macaulay2Doc),
  * Outputs:
      * a Boolean value (Macaulay2Doc), the truth value of
        $I^n==I^{(n)}$

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

Given a radical ideal I and an integer $n$, this method returns true if and
only if $I^n=I^{(n)}$. This method circumvents computing the symbolic powers in
most cases, by first testing the bigHeight, of $I^n$

+-----------------------------------+
|i1 : B = QQ[x,y,z];                |
+-----------------------------------+
|i2 : f = map(QQ[t],B,{t^3,t^4,t^5})|
|                                   |
|                      3   4   5    |
|o2 = map (QQ[t], B, {t , t , t })  |
|                                   |
|o2 : RingMap QQ[t] <--- B          |
+-----------------------------------+
|i3 : I = ker f;                    |
|                                   |
|o3 : Ideal of B                    |
+-----------------------------------+
|i4 : isSymbolicEqualOrdinary(I,2)  |
|                                   |
|o4 = false                         |
+-----------------------------------+

See also
========

  * isSymbPowerContainedinPower -- tests if
    the m-th symbolic power an ideal is contained the n-th power

Ways to use isSymbolicEqualOrdinary :
=====================================

  * "isSymbolicEqualOrdinary(Ideal,ZZ)"

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

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

isSymbPowerContainedinPower -- tests if the m-th symbolic power an ideal is contained the n-th power
****************************************************************************************************

Synopsis
========

  * Usage:
        isSymbPowerContainedinPower(I,m,n)
  * Inputs:
      * I, an ideal (Macaulay2Doc),
      * m, an integer (Macaulay2Doc),
      * n, an integer (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * CIPrimes, => ..., default value false, compute the
        symbolic power by taking the intersection of the powers of the primary
        components
      * UseMinimalPrimes, => ..., default value false,
        an option to only use minimal primes to calculate symbolic powers
  * Outputs:
      * a Boolean value (Macaulay2Doc), whether the m-th
        symbolic power of $I$ is contained in the n-th power

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

+---------------------------------------+
|i1 : R = QQ[x,y,z]                     |
|                                       |
|o1 = R                                 |
|                                       |
|o1 : PolynomialRing                    |
+---------------------------------------+
|i2 : J = ideal(x,y)                    |
|                                       |
|o2 = ideal (x, y)                      |
|                                       |
|o2 : Ideal of R                        |
+---------------------------------------+
|i3 : isSymbPowerContainedinPower(J,3,2)|
|                                       |
|o3 = true                              |
+---------------------------------------+

See also
========

  * containmentProblem -- computes the smallest
    symbolic power contained in a power of an ideal.

Ways to use isSymbPowerContainedinPower :
=========================================

  * "isSymbPowerContainedinPower(Ideal,ZZ,ZZ)"

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

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

joinIdeals -- Computes the join of the given ideals
***************************************************

Synopsis
========

  * Usage:
        joinIdeals(Ideal,Ideal)
  * Inputs:
      * I, an ideal (Macaulay2Doc),
      * J, an ideal (Macaulay2Doc),
  * Outputs:
      * an ideal (Macaulay2Doc), the join of I and J

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

This method uses Seth Sullivant's results found in "Combinatorial symbolic
powers", J. Algebra 319 (2008), no. 1, 115-142.

+--------------------------------------------------+
|i1 : S = QQ[x,y,z];                               |
+--------------------------------------------------+
|i2 : I = ideal(x^3,x^2*y^2,x*z^3,y^4,y^2*z);      |
|                                                  |
|o2 : Ideal of S                                   |
+--------------------------------------------------+
|i3 : J = joinIdeals(I,I)                          |
|                                                  |
|             5   5    7   4 3   3 5   2 3 3   3 5 |
|o3 = ideal (x , y z, y , x y , x z , x y z , x y )|
|                                                  |
|o3 : Ideal of S                                   |
+--------------------------------------------------+

Ways to use joinIdeals :
========================

  * "joinIdeals(Ideal,Ideal)"

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

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

lowerBoundResurgence -- computes a lower bound for the resurgence of a given ideal.
***********************************************************************************

Synopsis
========

  * Usage:
        lowerBoundResurgence(Ideal)
  * Inputs:
      * I, an ideal (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * SampleSize,
        => ..., default value 5, optional parameter used for
        approximating asymptotic invariants that are defined as limits.
      * UseWaldschmidt,
        => ..., default value false, optional input for
        computing a lower bound for the resurgence of a given ideal.
  * Outputs:
      * a rational number (Macaulay2Doc),

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

The resurgence of an ideal $I$, defined by Harbourne and Bocci, is given by
$\rho(I) :=$ sup $\lbrace a/b : I^{(a)}$ &nsub; $I^b \rbrace.$

Given an ideal $I$, finds the maximum of the quotients $m/k$ that fail $I^{(m)}
\subseteq I^k$ with $k \leq$ the optional input SampleSize.

+-----------------------------------------------------+
|i1 : T = QQ[x,y,z];                                  |
+-----------------------------------------------------+
|i2 : I = intersect(ideal"x,y",ideal"x,z",ideal"y,z");|
|                                                     |
|o2 : Ideal of T                                      |
+-----------------------------------------------------+
|i3 : lowerBoundResurgence(I)                         |
|                                                     |
|     6                                               |
|o3 = -                                               |
|     5                                               |
|                                                     |
|o3 : QQ                                              |
+-----------------------------------------------------+

Ways to use lowerBoundResurgence :
==================================

  * "lowerBoundResurgence(Ideal)"

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

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

lowerBoundResurgence(...,SampleSize=>...) -- optional parameter used for approximating asymptotic invariants that are defined as limits.
****************************************************************************************************************************************

Synopsis
========

  * Usage:
        lowerBoundResurgence(I,SampleSize=>ZZ)

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

Given an ideal $I$ and an integer $n$, returns the larger of the two numbers
$\frac{\alpha(I)}{waldschmidt(I)}$ and the maximum of the quotients $m/k$ that
fail $I^{(m)} \subseteq I^k$ with $k \leq$ See SampleSize.

+-----------------------------------------------------+
|i1 : R = QQ[x,y,z];                                  |
+-----------------------------------------------------+
|i2 : J = ideal (x*(y^3-z^3),y*(z^3-x^3),z*(x^3-y^3));|
|                                                     |
|o2 : Ideal of R                                      |
+-----------------------------------------------------+
|i3 : lowerBoundResurgence(J, SampleSize=>5)          |
|                                                     |
|     3                                               |
|o3 = -                                               |
|     2                                               |
|                                                     |
|o3 : QQ                                              |
+-----------------------------------------------------+

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

  * Default value: 5
  * Function: lowerBoundResurgence, -- computes a
    lower bound for the resurgence of a given ideal.
  * Option key: SampleSize, -- optional parameter used for
    approximating asymptotic invariants that are defined as limits.

Functions with optional argument named SampleSize :
===================================================

  * asymptoticRegularity(...,SampleSize=>...)
    -- optional
    parameter used for approximating asymptotic invariants that are defined as
    limits.
  * lowerBoundResurgence(...,SampleSize=>...)
    -- optional
    parameter used for approximating asymptotic invariants that are defined as
    limits.
  * waldschmidt(...,SampleSize=>...)
    -- optional parameter
    used for approximating asymptotic invariants that are defined as limits.

lowerBoundResurgence(...,UseWaldschmidt=>...) -- optional input for computing a lower bound for the resurgence of a given ideal.
********************************************************************************************************************************

Synopsis
========

  * Usage:
        lowerBoundResurgence(Ideal,UseWaldschmidt=>true)
  * Inputs:
      * I, an ideal (Macaulay2Doc),
  * Outputs:
      * a rational number (Macaulay2Doc),

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

Given an ideal $I$ and an integer $n$, returns the larger value between the
maximum of the quotients $m/k$ that fail $I^{(m)} \subseteq I^k$ with $k \leq$
See SampleSize, and $\frac{\alpha(I)}{waldschmidt(I)}$.

+-----------------------------------------------------+
|i1 : T = QQ[x,y,z];                                  |
+-----------------------------------------------------+
|i2 : I = intersect(ideal"x,y",ideal"x,z",ideal"y,z");|
|                                                     |
|o2 : Ideal of T                                      |
+-----------------------------------------------------+
|i3 : lowerBoundResurgence(I,UseWaldschmidt=>true)    |
|                                                     |
|     4                                               |
|o3 = -                                               |
|     3                                               |
|                                                     |
|o3 : QQ                                              |
+-----------------------------------------------------+

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

  * Default value: false (Macaulay2Doc),
  * Function: lowerBoundResurgence, -- computes a
    lower bound for the resurgence of a given ideal.
  * Option key: UseWaldschmidt, -- optional input for
    computing a lower bound for the resurgence of a given ideal.

Functions with optional argument named UseWaldschmidt :
=======================================================

  * lowerBoundResurgence(...,UseWaldschmidt=>...),
    --
    optional input for computing a lower bound for the resurgence of a given
    ideal.

minDegreeSymbPower -- returns the minimal degree of a given symbolic power of an ideal.
***************************************************************************************

Synopsis
========

  * Usage:
        minDegreeSymbPower(Ideal,ZZ)
  * Inputs:
      * I, an ideal (Macaulay2Doc),
      * n, an integer (Macaulay2Doc),
  * Outputs:
      * an integer (Macaulay2Doc),

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

Given an ideal $I$ and an integer $n$, returns the minimal degree of an element
in $I^{(n)}$.

+----------------------------------------------------+
|i1 : T = QQ[x,y,z];                                 |
+----------------------------------------------------+
|i2 : I = intersect(ideal"x,y",ideal"x,z",ideal"y,z")|
|                                                    |
|o2 = ideal (y*z, x*z, x*y)                          |
|                                                    |
|o2 : Ideal of T                                     |
+----------------------------------------------------+
|i3 : minDegreeSymbPower(I,2)                        |
|                                                    |
|o3 = 3                                              |
+----------------------------------------------------+

Ways to use minDegreeSymbPower :
================================

  * "minDegreeSymbPower(Ideal,ZZ)"

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

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

minimalPart -- intersection of the minimal components
*****************************************************

Synopsis
========

  * Usage:
        minimalPart(I)
  * Inputs:
      * I, an ideal (Macaulay2Doc),
  * Outputs:
      * an ideal (Macaulay2Doc), the intersection of the
        components of I corresponding to minimal primes

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

Eliminates embedded components of a given ideal

+-----------------------------------------------+
|i1 : R = QQ[x,y,z]                             |
|                                               |
|o1 = R                                         |
|                                               |
|o1 : PolynomialRing                            |
+-----------------------------------------------+
|i2 : J = intersect(ideal(x^2,y,z^3),ideal(x,z))|
|                                               |
|                       2   3                   |
|o2 = ideal (y*z, x*y, x , z )                  |
|                                               |
|o2 : Ideal of R                                |
+-----------------------------------------------+
|i3 : minimalPart(J)                            |
|                                               |
|o3 = ideal (z, x)                              |
|                                               |
|o3 : Ideal of R                                |
+-----------------------------------------------+

See also
========

  * assPrimesHeight -- The heights of all associated
    primes
  * bigHeight -- computes the big height of an ideal
  * symbolicPower -- computes the symbolic power of an
    ideal.

Ways to use minimalPart :
=========================

  * "minimalPart(Ideal)"

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

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

noPackedAllSubs -- finds all substitutions of variables by 1 and/or 0 for which ideal is not Konig.
***************************************************************************************************

Synopsis
========

  * Usage:
        noPackedAllSubs(I)
  * Inputs:
      * I, an ideal (Macaulay2Doc),
  * Outputs:
      * a list (Macaulay2Doc),

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

Given an ideal that is not packed, returns a list with all substitution of
variables by 0 and/or 1 that produces an ideal that is not Konig.

+---------------------------------------------------------------+
|i1 : R = QQ[x,y,z];                                            |
+---------------------------------------------------------------+
|i2 : I = ideal(x*y,y*z,x*z);                                   |
|                                                               |
|o2 : Ideal of R                                                |
+---------------------------------------------------------------+
|i3 : noPackedAllSubs(I)                                        |
|                                                               |
|o3 = Only I is not Konig -- all proper substitutions are Konig.|
+---------------------------------------------------------------+

See also
========

  * noPackedSub -- finds a substitution of variables by 1
    and/or 0 for which an ideal is not Konig.
  * isPacked -- determines if a given square-free ideal is
    packed.

Ways to use noPackedAllSubs :
=============================

  * "noPackedAllSubs(Ideal)"

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

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

noPackedSub -- finds a substitution of variables by 1 and/or 0 for which an ideal is not Konig.
***********************************************************************************************

Synopsis
========

  * Usage:
        noPackedSub(I)
  * Inputs:
      * I, an ideal (Macaulay2Doc),
  * Outputs:
      * a list (Macaulay2Doc),

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

Given an ideal that is not packed, returns a substitution of variables by 0
and/or 1 that produces an ideal that is not Konig. Determines only one such
substitutions, even though others may exist.

+-----------------------------------+
|i1 : R = QQ[x,y,z];                |
+-----------------------------------+
|i2 : I = ideal(x*y,y*z,x*z);       |
|                                   |
|o2 : Ideal of R                    |
+-----------------------------------+
|i3 : noPackedSub(I)                |
|                                   |
|o3 = The ideal itself is not Konig!|
+-----------------------------------+

See also
========

  * isPacked -- determines if a given square-free ideal is
    packed.

Ways to use noPackedSub :
=========================

  * "noPackedSub(Ideal)"

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

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

SampleSize -- optional parameter used for approximating asymptotic invariants that are defined as limits.
*********************************************************************************************************

See also
========

  * waldschmidt -- computes the Waldschmidt constant for a
    homogeneous ideal.
  * lowerBoundResurgence -- computes a lower bound
    for the resurgence of a given ideal.
  * asymptoticRegularity -- approximates the
    asymptotic regularity

Functions with optional argument named SampleSize :
===================================================

  * asymptoticRegularity(...,SampleSize=>...)
    -- optional
    parameter used for approximating asymptotic invariants that are defined as
    limits.
  * lowerBoundResurgence(...,SampleSize=>...)
    -- optional
    parameter used for approximating asymptotic invariants that are defined as
    limits.
  * waldschmidt(...,SampleSize=>...)
    -- optional parameter
    used for approximating asymptotic invariants that are defined as limits.

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

The object SampleSize, is a symbol (Macaulay2Doc).

squarefreeGens -- returns all square-free monomials in a minimal generating set of the given ideal.
***************************************************************************************************

Synopsis
========

  * Usage:
        squarefreeGens(I)
  * Inputs:
      * I, an ideal (Macaulay2Doc),
  * Outputs:
      * a list (Macaulay2Doc),

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

Given a monomial ideal $I$, returns all square-free monomials in a minimal
generating set of $I$.

+----------------------------+
|i1 : R = QQ[x,y,z];         |
+----------------------------+
|i2 : I = ideal(x*y,y*z,x^2);|
|                            |
|o2 : Ideal of R             |
+----------------------------+
|i3 : squarefreeGens(I)      |
|                            |
|o3 = {y*z, x*y}             |
|                            |
|o3 : List                   |
+----------------------------+

See also
========

  * squarefreeInCodim -- finds square-fee monomials
    in ideal raised to the power of the codimension.

Ways to use squarefreeGens :
============================

  * "squarefreeGens(Ideal)"

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

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

squarefreeInCodim -- finds square-fee monomials in ideal raised to the power of the codimension.
************************************************************************************************

Synopsis
========

  * Usage:
        squarefreeInCodim(I)
  * Inputs:
      * I, an ideal (Macaulay2Doc),
  * Outputs:
      * a list (Macaulay2Doc),

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

Given a monomial ideal $I$, returns all square-free monomials in a minimal
generating set of $I^c$ where $c$ is the codimension of $I$.

+----------------------------+
|i1 : R = QQ[x,y,z];         |
+----------------------------+
|i2 : I = ideal(x*y,y*z,x*z);|
|                            |
|o2 : Ideal of R             |
+----------------------------+
|i3 : squarefreeInCodim(I)   |
|                            |
|o3 = {}                     |
|                            |
|o3 : List                   |
+----------------------------+

See also
========

  * squarefreeGens -- returns all square-free monomials
    in a minimal generating set of the given ideal.

Ways to use squarefreeInCodim :
===============================

  * "squarefreeInCodim(Ideal)"

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

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

Sullivant's algorithm for primes in a polynomial ring
*****************************************************

Given ideals I and J in a polynomial ring, we compute their join I*J:

+--------------------------------------------------+
|i1 : S = QQ[x,y,z];                               |
+--------------------------------------------------+
|i2 : I = ideal(x^3,x^2*y^2,x*z^3,y^4,y^2*z);      |
|                                                  |
|o2 : Ideal of S                                   |
+--------------------------------------------------+
|i3 : J = joinIdeals(I,I)                          |
|                                                  |
|             5   5    7   4 3   3 5   2 3 3   3 5 |
|o3 = ideal (x , y z, y , x y , x z , x y z , x y )|
|                                                  |
|o3 : Ideal of S                                   |
+--------------------------------------------------+

Following Seth Sullivant's "Combinatorial symbolic powers", J. Algebra 319
(2008), no. 1, 115–142, we can compute symbolic powers of prime ideals using
join:

+------------------------------------+
|i4 : A = QQ[x,y,z];                 |
+------------------------------------+
|i5 : symbolicPowerJoin(ideal(x,y),2)|
|                                    |
|             2        2             |
|o5 = ideal (y , x*y, x )            |
|                                    |
|o5 : Ideal of A                     |
+------------------------------------+
+-----------------------------------------------------------------------------+
|i6 : f = map(QQ[t],A,{t^3,t^4,t^5})                                          |
|                                                                             |
|                      3   4   5                                              |
|o6 = map (QQ[t], A, {t , t , t })                                            |
|                                                                             |
|o6 : RingMap QQ[t] <--- A                                                    |
+-----------------------------------------------------------------------------+
|i7 : P = ker f;                                                              |
|                                                                             |
|o7 : Ideal of A                                                              |
+-----------------------------------------------------------------------------+
|i8 : symbolicPowerJoin(P,2)                                                  |
|                                                                             |
|             4       2     2 2   2 3    3       2 2      3   3 2    4     3  |
|o8 = ideal (y  - 2x*y z + x z , x y  - x y*z - y z  + x*z , x y  - x z - y z |
|     ------------------------------------------------------------------------|
|            2   5      3     2       3                                       |
|     + x*y*z , x  + x*y  - 3x y*z + z )                                      |
|                                                                             |
|o8 : Ideal of A                                                              |
+-----------------------------------------------------------------------------+

symbolicDefect -- computes the symbolic defect of an ideal
**********************************************************

Synopsis
========

  * Usage:
        symbolicDefect(I,m)
  * Inputs:
      * I, an ideal (Macaulay2Doc),
      * m, an integer (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * CIPrimes, => ..., default value false, compute the
        symbolic power by taking the intersection of the powers of the primary
        components
      * UseMinimalPrimes, => ..., default value false,
        an option to only use minimal primes to calculate symbolic powers
  * Outputs:
      * an integer (Macaulay2Doc), the size of a minimal generating
        set of the m-th symbolic power of I modulo I^m.

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

Given an ideal $I$ and integer $m$, this method returns the size of a minimal
generating set for the $m$-th symbolic power of $I$ modulo $I^m$.

+----------------------------+
|i1 : R = QQ[x,y,z]          |
|                            |
|o1 = R                      |
|                            |
|o1 : PolynomialRing         |
+----------------------------+
|i2 : I = ideal(x*y,x*z,y*z);|
|                            |
|o2 : Ideal of R             |
+----------------------------+
|i3 : symbolicDefect(I,2)    |
|                            |
|o3 = 1                      |
+----------------------------+

Ways to use symbolicDefect :
============================

  * "symbolicDefect(Ideal,ZZ)"

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

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

symbolicPolyhedron -- computes the symbolic polyhedron for a monomial ideal.
****************************************************************************

Synopsis
========

  * Usage:
        symbolicPolyhedron(I)
  * Inputs:
      * I, an ideal (Macaulay2Doc),
  * Outputs:
      * a convex polyhedron (Polyhedra),

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

The symbolic polyhedron associated to a monomial ideal $I$ is defined in the
paper "Symbolic Powers of Monomial Ideals" by S. M. Cooper, R. J. D. Embree, H.
T. Ha, A. H. Hoefel. The symbolic polyhedron contains the exponent vector of
any monomial in $I^n$ scaled by $1/n$.

This function uses the Polyhedra package and returns an object of type
Polyhedron.

+----------------------------+
|i1 : R = QQ[x,y,z];         |
+----------------------------+
|i2 : I = ideal(x*y,y*z,x*z);|
|                            |
|o2 : Ideal of R             |
+----------------------------+
|i3 : symbolicPolyhedron(I)  |
|                            |
|o3 = Polyhedron{...1...}    |
|                            |
|o3 : Polyhedron             |
+----------------------------+

See also
========

  * Polyhedra -- for computations with convex polyhedra,
    cones, and fans

Ways to use symbolicPolyhedron :
================================

  * "symbolicPolyhedron(Ideal)"
  * "symbolicPolyhedron(MonomialIdeal)"

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

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

symbolicPower -- computes the symbolic power of an ideal.
*********************************************************

Synopsis
========

  * Usage:
        symbolicPower(I,n)
  * Inputs:
      * I, an ideal (Macaulay2Doc),
      * n, an integer (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * CIPrimes, => ..., default value false, compute the
        symbolic power by taking the intersection of the powers of the primary
        components
      * UseMinimalPrimes, => ..., default value false,
        an option to only use minimal primes to calculate symbolic powers
  * Outputs:
      * an ideal (Macaulay2Doc), the n-th symbolic power of I

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

Given an ideal $I$ and an integer $n$, this method returns the $n$-th symbolic
power of $I$. Various algorithms are used, in the following order:

1. If $I$ is squarefree monomial ideal, intersects the powers of the associated
primes of $I$;

2. If $I$ is monomial ideal, but not squarefree, takes an irredundant primary
decomposition of $I$ and intersects the powers of those ideals;

3. If $I$ is a saturated homogeneous ideal in a polynomial ring whose height is
one less than the dimension of the ring, returns the saturation of $I^n$;

4. If $I$ is an ideal with only degree one primary components, intersects the
powers of the primary components of I.

5. If all the associated primes of $I$ have the same height, computes a primary
decomposition of $I^n$ and intersects the components with radical $I$;

6. If all else fails, compares the radicals oyf a primary decomposition of
$I^n$ with the associated primes of $I$, and intersects the components
corresponding to minimal primes.

+-----------------------------------------------------------------------------+
|i1 : B = QQ[x,y,z];                                                          |
+-----------------------------------------------------------------------------+
|i2 : f = map(QQ[t],B,{t^3,t^4,t^5})                                          |
|                                                                             |
|                      3   4   5                                              |
|o2 = map (QQ[t], B, {t , t , t })                                            |
|                                                                             |
|o2 : RingMap QQ[t] <--- B                                                    |
+-----------------------------------------------------------------------------+
|i3 : I = ker f;                                                              |
|                                                                             |
|o3 : Ideal of B                                                              |
+-----------------------------------------------------------------------------+
|i4 : symbolicPower(I,2)                                                      |
|                                                                             |
|             4       2     2 2   2 3    3       2 2      3   3 2    4     3  |
|o4 = ideal (y  - 2x*y z + x z , x y  - x y*z - y z  + x*z , x y  - x z - y z |
|     ------------------------------------------------------------------------|
|            2   5      3     2       3                                       |
|     + x*y*z , x  + x*y  - 3x y*z + z )                                      |
|                                                                             |
|o4 : Ideal of B                                                              |
+-----------------------------------------------------------------------------+

When computing symbolic powers of a quasi-homogeneous ideal, the method runs
faster if the ideal is changed to be homogeneous.

+-------------------------------------------------------------------+
|i5 : P = ker map(QQ[t],QQ[x,y,z],{t^3,t^4,t^5})                    |
|                                                                   |
|             2         2     2   3                                 |
|o5 = ideal (y  - x*z, x y - z , x  - y*z)                          |
|                                                                   |
|o5 : Ideal of QQ[x..z]                                             |
+-------------------------------------------------------------------+
|i6 : isHomogeneous P                                               |
|                                                                   |
|o6 = false                                                         |
+-------------------------------------------------------------------+
|i7 : time symbolicPower(P,4);                                      |
|     -- used 0.423997 seconds                                      |
|                                                                   |
|o7 : Ideal of QQ[x..z]                                             |
+-------------------------------------------------------------------+
|i8 : Q = ker map(QQ[t],QQ[x,y,z, Degrees => {3,4,5}],{t^3,t^4,t^5})|
|                                                                   |
|             2         3         2     2                           |
|o8 = ideal (y  - x*z, x  - y*z, x y - z )                          |
|                                                                   |
|o8 : Ideal of QQ[x..z]                                             |
+-------------------------------------------------------------------+
|i9 : isHomogeneous Q                                               |
|                                                                   |
|o9 = true                                                          |
+-------------------------------------------------------------------+
|i10 : time symbolicPower(Q,4);                                     |
|     -- used 0.117301 seconds                                      |
|                                                                   |
|o10 : Ideal of QQ[x..z]                                            |
+-------------------------------------------------------------------+

See also
========

  * symbPowerPrimePosChar

Ways to use symbolicPower :
===========================

  * "symbolicPower(Ideal,ZZ)"

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

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

symbolicPowerJoin -- computes the symbolic power of the prime ideal using join of ideals.
*****************************************************************************************

Synopsis
========

  * Usage:
        symbolicPowerJoin(P,n)
  * Inputs:
      * P, an ideal (Macaulay2Doc),
      * n, an integer (Macaulay2Doc),
  * Outputs:
      * an ideal (Macaulay2Doc), the n-th symbolic power of P

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

Computes the $n$-th symbolic power of the prime ideal $P$, using join of
ideals.

This is the algorithm in Seth Sullivant's "Combinatorial symbolic powers", J.
Algebra 319 (2008), no. 1, 115-142.

+------------------------------------+
|i1 : A = QQ[x,y,z];                 |
+------------------------------------+
|i2 : symbolicPowerJoin(ideal(x,y),2)|
|                                    |
|             2        2             |
|o2 = ideal (y , x*y, x )            |
|                                    |
|o2 : Ideal of A                     |
+------------------------------------+

See also
========

  * joinIdeals -- Computes the join of the given ideals

Ways to use symbolicPowerJoin :
===============================

  * "symbolicPowerJoin(Ideal,ZZ)"

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

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

symbPowerPrimePosChar
*********************

Synopsis
========

  * Usage:
        symbPowerPrimePosChar(I,n)
  * Inputs:
      * I, an ideal (Macaulay2Doc),
      * n, an integer (Macaulay2Doc),
  * Outputs:
      * an ideal (Macaulay2Doc), the n-th symbolic power of I

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

Given a prime ideal $I$ in a polynomial ring over a field of positive
characteristic, and an integer $n$, this method returns the $n$-th symbolic
power of $I$.  To compute $I^{(a)}$, find the largest value $k$ with $q = p^k
\leq a$. Then $I^{(a)} = (I^{[q]} : I^{a-q+1})$.

+-----------------------------------------------------------------------------+
|i1 : B = ZZ/7[x,y,z];                                                        |
+-----------------------------------------------------------------------------+
|i2 : f = map(ZZ/7[t],B,{t^3,t^4,t^5})                                        |
|                                                                             |
|          ZZ          3   4   5                                              |
|o2 = map (--[t], B, {t , t , t })                                            |
|           7                                                                 |
|                                                                             |
|             ZZ                                                              |
|o2 : RingMap --[t] <--- B                                                    |
|              7                                                              |
+-----------------------------------------------------------------------------+
|i3 : I = ker f;                                                              |
|                                                                             |
|o3 : Ideal of B                                                              |
+-----------------------------------------------------------------------------+
|i4 : symbPowerPrimePosChar(I,2)                                              |
|                                                                             |
|             4       2     2 2   2 3    3       2 2      3   3 2    4     3  |
|o4 = ideal (y  - 2x*y z + x z , x y  - x y*z - y z  + x*z , x y  - x z - y z |
|     ------------------------------------------------------------------------|
|            2   5      3     2       3                                       |
|     + x*y*z , x  + x*y  - 3x y*z + z )                                      |
|                                                                             |
|o4 : Ideal of B                                                              |
+-----------------------------------------------------------------------------+

Caveat
======

The ideal must be prime.

See also
========

  * symbolicPower -- computes the symbolic power of an
    ideal.

Ways to use symbPowerPrimePosChar :
===================================

  * "symbPowerPrimePosChar(Ideal,ZZ)"

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

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

The Containment Problem
***********************

Given an ideal $I$, we can determine if $I^{(m)} \subseteq I^n$. For example,
here is an ideal that fails the containment $I^{(3)} \subseteq I^2$:

+----------------------------------------------------+
|i1 : B = ZZ/101[x,y,z];                             |
+----------------------------------------------------+
|i2 : I = ideal(x*(y^3-z^3),y*(z^3-x^3),z*(x^3-y^3));|
|                                                    |
|o2 : Ideal of B                                     |
+----------------------------------------------------+
|i3 : isSymbPowerContainedinPower(I,3,2)             |
|                                                    |
|o3 = false                                          |
+----------------------------------------------------+

We can also determine the smallest symbolic power contained in a given power.

In our example, $I^{(4)}$ is the smallest symbolic power contained in $I^2$:

+----------------------------+
|i4 : containmentProblem(I,2)|
|                            |
|o4 = 4                      |
+----------------------------+

We can ask the same question backwards: what is the largest power of I that
contains $I^{(4)}$?

+-----------------------------------------------+
|i5 : containmentProblem(I,4,InSymbolic => true)|
|                                               |
|o5 = 2                                         |
+-----------------------------------------------+

The Packing Problem
*******************

Given a square-free monomial ideal $I$ of codimension $c$, $I$ is Konig if it
contains a regular sequence of monomials of length $c$.

We can test if a given ideal is Konig:

+---------------------------+
|i1 : R = QQ[x,y,z]         |
|                           |
|o1 = R                     |
|                           |
|o1 : PolynomialRing        |
+---------------------------+
|i2 : I = ideal(x*y,z*y,x*z)|
|                           |
|o2 = ideal (x*y, y*z, x*z) |
|                           |
|o2 : Ideal of R            |
+---------------------------+
|i3 : isKonig(I)            |
|                           |
|o3 = false                 |
+---------------------------+

$I$ is said to have the packing property if any ideal obtained from $I$ by
setting any number of variables equal to 0 is Konig.

+----------------+
|i4 : isPacked(I)|
|                |
|o4 = false      |
+----------------+

Given an ideal that is not packed, we can determine which variable
substitutions lead to ideals that are not Konig.

+---------------------------------------------------------------+
|i5 : noPackedAllSubs(I)                                        |
|                                                               |
|o5 = Only I is not Konig -- all proper substitutions are Konig.|
+---------------------------------------------------------------+

We can obtained just one substitution leading to an ideal that is not Konig, or
all such substitutions:

+-----------------------------------------------------------------------------+
|i6 : R = QQ[a,b,c,d,A,B,C,D]                                                 |
|                                                                             |
|o6 = R                                                                       |
|                                                                             |
|o6 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i7 : J = ideal"ABCD,cdAB,abcD,bcABD,abcBD,abcdA,abcAD,abdAC,acdBC,acBCD,abcdC|
|                                                                             |
|o7 = ideal (A*B*C*D, c*d*A*B, a*b*c*D, b*c*A*B*D, a*b*c*B*D, a*b*c*d*A,      |
|     ------------------------------------------------------------------------|
|     a*b*c*A*D, a*b*d*A*C, a*c*d*B*C, a*c*B*C*D, a*b*c*d*C, b*c*d*A*C,       |
|     ------------------------------------------------------------------------|
|     b*c*A*C*D, b*c*d*A*D, a*c*d*B*D, a*d*B*C*D, a*c*A*B*D, b*d*A*B*C,       |
|     ------------------------------------------------------------------------|
|     a*d*A*B*C)                                                              |
|                                                                             |
|o7 : Ideal of R                                                              |
|-----------------------------------------------------------------------------|
|,bcdAC,bcACD,bcdAD,acdBD,adBCD,acABD,bdABC,adABC"                            |
+-----------------------------------------------------------------------------+
|i8 : isPacked(J)                                                             |
|                                                                             |
|o8 = false                                                                   |
+-----------------------------------------------------------------------------+
|i9 : noPackedSub(J)                                                          |
|                                                                             |
|o9 = The ideal itself is not Konig!                                          |
+-----------------------------------------------------------------------------+

These can easily be tested:

+-----------------------------------------------------------------------------+
|i10 : L = substitute(J,matrix{{1,0,c,d,A,1,C,D}})                            |
|                                                                             |
|o10 = ideal (A*C*D, c*d*A, 0, 0, 0, 0, 0, 0, c*d*C, c*C*D, 0, 0, 0, 0, c*d*D,|
|      -----------------------------------------------------------------------|
|      d*C*D, c*A*D, 0, d*A*C)                                                |
|                                                                             |
|o10 : Ideal of R                                                             |
+-----------------------------------------------------------------------------+
|i11 : isKonig(L)                                                             |
|                                                                             |
|o11 = false                                                                  |
+-----------------------------------------------------------------------------+

UseMinimalPrimes -- an option to only use minimal primes to calculate symbolic powers
*************************************************************************************

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

The default value is false. When defined to be true, the symbolic power is
calculated as defined in Villarreal. In particular, see symbolicPower,
has the option to restrict to minimal primes versus use all
associated primes with UseMinimalPrimes. With this
option the symbolic power of an ideal $I$ is defined as $$I^{(n)} = \cap_{p \in
Min(R/I)}(I^nR_p \cap R ),$$ where $Min(R/I)$, is the set of minimal primes in
$I$.

R. Villarreal. "Monomial algebras" Second edition. Monographs and Research
Notes in Mathematics. CRC Press, Boca Raton, FL, 2015. xviii+686 pp. ISBN:
978-1-4822-3469-5.

See also
========

  * containmentProblem -- computes the smallest
    symbolic power contained in a power of an ideal.
  * isSymbPowerContainedinPower -- tests if
    the m-th symbolic power an ideal is contained the n-th power
  * symbolicDefect -- computes the symbolic defect of an
    ideal
  * symbolicPower -- computes the symbolic power of an
    ideal.

Functions with optional argument named UseMinimalPrimes :
=========================================================

  * "containmentProblem(...,UseMinimalPrimes=>...)"
  * "isSymbPowerContainedinPower(...,UseMinimalPrimes=>...)"
  * "symbolicDefect(...,UseMinimalPrimes=>...)"
  * "symbolicPower(...,UseMinimalPrimes=>...)"

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

The object UseMinimalPrimes, is a symbol (Macaulay2Doc).

UseWaldschmidt -- optional input for computing a lower bound for the resurgence of a given ideal.
*************************************************************************************************

Synopsis
========

  * Usage:
        lowerBoundResurgence(Ideal,UseWaldschmidt=>true)
  * Inputs:
      * I, an ideal (Macaulay2Doc),
  * Outputs:
      * a rational number (Macaulay2Doc),

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

Given an ideal $I$ and an integer $n$, returns the larger value between the
maximum of the quotients $m/k$ that fail $I^{(m)} \subseteq I^k$ with $k \leq
n$ and $\frac{\alpha(I)}{waldschmidt(I)}$.

+-----------------------------------------------------+
|i1 : T = QQ[x,y,z];                                  |
+-----------------------------------------------------+
|i2 : I = intersect(ideal"x,y",ideal"x,z",ideal"y,z");|
|                                                     |
|o2 : Ideal of T                                      |
+-----------------------------------------------------+
|i3 : lowerBoundResurgence(I,UseWaldschmidt=>true)    |
|                                                     |
|     4                                               |
|o3 = -                                               |
|     3                                               |
|                                                     |
|o3 : QQ                                              |
+-----------------------------------------------------+

Functions with optional argument named UseWaldschmidt :
=======================================================

  * lowerBoundResurgence(...,UseWaldschmidt=>...),
    --
    optional input for computing a lower bound for the resurgence of a given
    ideal.

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

The object UseWaldschmidt, is a symbol (Macaulay2Doc).

waldschmidt -- computes the Waldschmidt constant for a homogeneous ideal.
*************************************************************************

Synopsis
========

  * Usage:
        waldschmidt(I)
  * Inputs:
      * I, an ideal (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * SampleSize,
        => ..., default value 5, optional parameter used for approximating
        asymptotic invariants that are defined as limits.
  * Outputs:
      * a rational number (Macaulay2Doc),

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

The Waldschmidt constant for a homogeneous ideal I is defined as
$waldschmidt(I)=lim_{n\to\infty} \frac{\alpha(I^{(n)})}{n}$, where $\alpha(J)$
denotes the smallest degree of a nonzero element in a given homogeneous ideal
$J$. The limit of the sequence $\frac{\alpha(I^{(n)})}{n}$ exists because of
the subadditivity of $\alpha$ and is equal to the infimum of the sequence
$\frac{\alpha(I^{(n)})}{n}$.

The Waldschmidt constant can be computed for monomial ideals as the smallest
value of the sum of the coordinates over all the points of the symbolic
polyhedron. The function uses this method to return an exact answer for the
Waldschmidt constant of a monomial ideal.

For ideals that are not monomial, we give an approximation of the Waldschmidt
constant by taking the minimum value of $\frac{\alpha(I^{(n)})}{n}$ over a
finite number of exponents $n$, namely for $n$ from 1 to the optional parameter
SampleSize.

+----------------------------+
|i1 : R = QQ[x,y,z];         |
+----------------------------+
|i2 : I = ideal(x*y,y*z,x*z);|
|                            |
|o2 : Ideal of R             |
+----------------------------+
|i3 : waldschmidt(I)         |
|                            |
|     3                      |
|o3 = -                      |
|     2                      |
|                            |
|o3 : QQ                     |
+----------------------------+
+-----------------------------------------------------+
|i4 : R = QQ[x,y,z];                                  |
+-----------------------------------------------------+
|i5 : J = ideal (x*(y^3-z^3),y*(z^3-x^3),z*(x^3-y^3));|
|                                                     |
|o5 : Ideal of R                                      |
+-----------------------------------------------------+
|i6 : waldschmidt(J, SampleSize=>5)                   |
|                                                     |
|o6 = 3                                               |
|                                                     |
|o6 : QQ                                              |
+-----------------------------------------------------+

See also
========

  * symbolicPolyhedron -- computes the symbolic
    polyhedron for a monomial ideal.

Ways to use waldschmidt :
=========================

  * "waldschmidt(Ideal)"
  * "waldschmidt(MonomialIdeal)"

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

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

waldschmidt(...,SampleSize=>...) -- optional parameter used for approximating asymptotic invariants that are defined as limits.
*******************************************************************************************************************************

Synopsis
========

  * Usage:
        waldschmidt(I,SampleSize=>ZZ)

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

For ideals that are not monomial, we give an approximation of the Waldschmidt
constant by taking the minimum value of $\frac{\alpha(I^{(n)})}{n}$ over a
finite number of exponents $n$, namely for $n$ from 1 to the optional parameter
SampleSize. Similarly the SampleSize, is
used to give an approximation for the asymptotic regularity by computing the
smallest value of $\frac{reg(I^{(n)})}{n}$ for $n$ from 1 to the
SampleSize.

+-----------------------------------------------------+
|i1 : R = QQ[x,y,z];                                  |
+-----------------------------------------------------+
|i2 : J = ideal (x*(y^3-z^3),y*(z^3-x^3),z*(x^3-y^3));|
|                                                     |
|o2 : Ideal of R                                      |
+-----------------------------------------------------+
|i3 : waldschmidt(J, SampleSize=>5)                   |
|                                                     |
|o3 = 3                                               |
|                                                     |
|o3 : QQ                                              |
+-----------------------------------------------------+

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

  * Default value: 5
  * Function: waldschmidt, -- computes the Waldschmidt
    constant for a homogeneous ideal.
  * Option key: SampleSize, -- optional parameter used for
    approximating asymptotic invariants that are defined as limits.

Functions with optional argument named SampleSize :
===================================================

  * asymptoticRegularity(...,SampleSize=>...)
    -- optional
    parameter used for approximating asymptotic invariants that are defined as
    limits.
  * lowerBoundResurgence(...,SampleSize=>...)
    -- optional
    parameter used for approximating asymptotic invariants that are defined as
    limits.
  * waldschmidt(...,SampleSize=>...)
    -- optional parameter
    used for approximating asymptotic invariants that are defined as limits.