This is PrimaryDecomposition.info, produced by Macaulay2, version 1.26.06

PrimaryDecomposition -- primary decomposition and associated primes routines for ideals and modules
***************************************************************************************************

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

This package provides routines for computation involving components of ideals
and modules, including associated primes and primary decompositions.

The following simple example illustrates the use of
removeLowestDimension, topComponents,
see radical (MinimalPrimes), minimalPrimes (MinimalPrimes),
see associatedPrimes, and
primaryDecomposition.

+-----------------------------------------------------------------------------+
|i1 : R = ZZ/32003[a..d];                                                     |
+-----------------------------------------------------------------------------+
|i2 : I = monomialCurveIdeal(R,{1,3,4})                                       |
|                                                                             |
|                        3      2     2    2    3    2                        |
|o2 = ideal (b*c - a*d, c  - b*d , a*c  - b d, b  - a c)                      |
|                                                                             |
|o2 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i3 : J = ideal(a^3,b^3,c^3-d^3)                                              |
|                                                                             |
|             3   3   3    3                                                  |
|o3 = ideal (a , b , c  - d )                                                 |
|                                                                             |
|o3 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i4 : I = intersect(I,J)                                                      |
|                                                                             |
|             4    3      3    3      4      3         3      4   6      3 2  |
|o4 = ideal (b  - a d, a*b  - a c, b*c  - a*c d - b*c*d  + a*d , c  - b*c d  -|
|     ------------------------------------------------------------------------|
|      3 3      5     5    2 3       2 3    2 4   2 4    3 3    3 3    2   3  |
|     c d  + b*d , a*c  - b c d - a*c d  + b d , a c  - a d  + b d  - a c*d , |
|     ------------------------------------------------------------------------|
|      3 3    3 3     2 3    3   2    3   2      2 3   2   3    3 2     3 2   |
|     b c  - a d , a*b c  - a c*d  + b c*d  - a*b d , a b*c  - a c d + b c d -|
|     ------------------------------------------------------------------------|
|      2   3   3 3    3   2   4 2    3 2                                      |
|     a b*d , a c  - a b*d , a c  - a b d)                                    |
|                                                                             |
|o4 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i5 : removeLowestDimension I                                                 |
|                                                                             |
|                        3      2     2    2    3    2                        |
|o5 = ideal (b*c - a*d, c  - b*d , a*c  - b d, b  - a c)                      |
|                                                                             |
|o5 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i6 : topComponents I                                                         |
|                                                                             |
|                        3      2     2    2    3    2                        |
|o6 = ideal (b*c - a*d, c  - b*d , a*c  - b d, b  - a c)                      |
|                                                                             |
|o6 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i7 : radical I                                                               |
|                                                                             |
|                          2    2    3    2    6    3 3    2 4      5         |
|o7 = ideal (b*c - a*d, a*c  - b d, b  - a c, c  - c d  - b d  + b*d )        |
|                                                                             |
|o7 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i8 : minimalPrimes I                                                         |
|                                                                             |
|                         3      2     2    2    3    2                       |
|o8 = {ideal (b*c - a*d, c  - b*d , a*c  - b d, b  - a c), ideal (c - d, b,   |
|     ------------------------------------------------------------------------|
|                       2          2                                          |
|     a), ideal (b, a, c  + c*d + d )}                                        |
|                                                                             |
|o8 : List                                                                    |
+-----------------------------------------------------------------------------+
|i9 : associatedPrimes I                                                      |
|                                                                             |
|                         3      2     2    2    3    2                       |
|o9 = {ideal (b*c - a*d, c  - b*d , a*c  - b d, b  - a c), ideal (c - d, b,   |
|     ------------------------------------------------------------------------|
|                       2          2                                          |
|     a), ideal (b, a, c  + c*d + d )}                                        |
|                                                                             |
|o9 : List                                                                    |
+-----------------------------------------------------------------------------+
|i10 : primaryDecomposition I                                                 |
|                                                                             |
|                          3      2     2    2    3    2                   3  |
|o10 = {ideal (b*c - a*d, c  - b*d , a*c  - b d, b  - a c), ideal (c - d, b , |
|      -----------------------------------------------------------------------|
|       3           2          2   3   3                                      |
|      a ), ideal (c  + c*d + d , b , a )}                                    |
|                                                                             |
|o10 : List                                                                   |
+-----------------------------------------------------------------------------+

References
==========

  * Eisenbud-Huneke-Vasconcelos, Inventiones mathematicae, 110 207–235 (1992)
  * Shimoyama-Yokoyama, Journal of Symbolic Computation, 22(3) 247–277 (1996)

See also
========

  * MinimalPrimes -- minimal primes and radical
    routines for ideals
  * Saturation -- quotient, saturation, and annihilator
    routines for ideals and modules

Authors
=======

  * Mike Stillman (see http://www.math.cornell.edu/~mike )
    <mike@math.cornell.edu>
  * Carolyn Yackel <cyackel@math.indiana.edu>
  * Justin Chen <justin.chen@math.gatech.edu>
  * Mahrud Sayrafi (see https://math.umn.edu/~mahrud ) <mahrud@umn.edu>

Version
=======

This documentation describes version 2.0 of PrimaryDecomposition, released July
4, 2020.

Citation
========

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

+-----------------------------------------------------------------------------+
|@misc{PrimaryDecompositionSource,                                            |
|  title = {{PrimaryDecomposition: primary decomposition                      |
|  author = {Mike Stillman and Carolyn Yackel and Justin                      |
|  howpublished = {A \emph{Macaulay2} package available                       |
|    \url{https://github.com/Macaulay2/M2/tree/stable/M2                      |
|}                                                                            |
|-----------------------------------------------------------------------------|
| and associated primes routines. Version~2.0}},                              |
| Chen and Mahrud Sayrafi},                                                   |
|at                                                                           |
|/Macaulay2/packages}}                                                        |
+-----------------------------------------------------------------------------+

Exports
=======

  * Functions and commands
      * associatedPrimes -- find associated primes
      * irreducibleDecomposition -- express a
        monomial ideal as an intersection of irreducible monomial ideals
      * isPrimary -- determine whether a submodule is primary
      * kernelOfLocalization -- the kernel of the
        localization map
      * localize -- localize an ideal at a prime ideal
      * primaryComponent -- find a primary component
        corresponding to an associated prime
      * primaryDecomposition -- irredundant
        primary decomposition of an ideal
      * regSeqInIdeal -- a regular sequence contained in
        an ideal
      * removeLowestDimension -- remove
        components of lowest dimension
      * topComponents -- compute top dimensional
        component of an ideal or module
  * Methods
      * "associatedPrimes(Ideal)" -- see associatedPrimes,
        -- find associated primes
      * "associatedPrimes(Module)" -- see associatedPrimes,
        -- find associated primes
      * "associatedPrimes(Ring)" -- see associatedPrimes,
        -- find associated primes
      * "irreducibleDecomposition(MonomialIdeal)" -- see
        irreducibleDecomposition, -- express a
        monomial ideal as an intersection of irreducible monomial ideals
      * "isPrimary(Ideal)" -- see isPrimary, -- determine
        whether a submodule is primary
      * "isPrimary(Ideal,Ideal)" -- see isPrimary, --
        determine whether a submodule is primary
      * "isPrimary(Module,Module)" -- see isPrimary, --
        determine whether a submodule is primary
      * "kernelOfLocalization(Module,Ideal)" -- see kernelOfLocalization,
        -- the kernel of the localization map
      * "localize(Ideal,Ideal)" -- see localize, -- localize an
        ideal at a prime ideal
      * "primaryComponent(Ideal,Ideal)" -- see primaryComponent,
        -- find a primary component corresponding to an
        associated prime
      * "primaryDecomposition(Ideal)" -- see primaryDecomposition,
        -- irredundant primary decomposition of an ideal
      * primaryDecomposition(Module),
        -- irredundant primary decomposition of a module
      * "primaryDecomposition(Ring)" -- see primaryDecomposition(Module),
        -- irredundant primary decomposition
        of a module
      * "regSeqInIdeal(Ideal)" -- see regSeqInIdeal, -- a
        regular sequence contained in an ideal
      * "regSeqInIdeal(Ideal,ZZ)" -- see regSeqInIdeal, --
        a regular sequence contained in an ideal
      * "regSeqInIdeal(Ideal,ZZ,ZZ,ZZ)" -- see regSeqInIdeal,
        -- a regular sequence contained in an ideal
      * "removeLowestDimension(Ideal)" -- see removeLowestDimension,
        -- remove components of lowest dimension
      * "removeLowestDimension(Module)" -- see removeLowestDimension,
        -- remove components of lowest dimension
      * "topComponents(Ideal)" -- see topComponents, --
        compute top dimensional component of an ideal or module
      * "topComponents(Module)" -- see topComponents, --
        compute top dimensional component of an ideal or module
      * "topComponents(Module,ZZ)" -- see topComponents,
        -- compute top dimensional component of an ideal or module
  * Symbols
      * "Increment" -- see primaryComponent, -- find a
        primary component corresponding to an associated prime
      * "EisenbudHunekeVasconcelos" -- see strategies for computing primary decomposition,
      * "GTZ" -- see strategies for computing primary decomposition,
      * "ShimoyamaYokoyama" -- see strategies for computing primary decomposition,

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

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

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

The source of this document is in PrimaryDecomposition/doc.m2:771:0.

associatedPrimes -- find associated primes
******************************************

  * Usage:
        associatedPrimes I
        ass I
  * Inputs:
      * I, a ring (Macaulay2Doc), an ideal (Macaulay2Doc),
        or a module (Macaulay2Doc), a
        quotient ring, ideal, or module over a (quotient of a) polynomial ring
        R
  * Optional inputs (Macaulay2Doc),:
      * CodimensionLimit => an integer (Macaulay2Doc), default value
        infinity, stop after finding primes of codimension less than or equal
        to this value
      * MinimalGenerators => a Boolean value (Macaulay2Doc),
        default value true, if false, the associated primes will not be
        minimalized
      * Strategy => ..., default value null
  * Outputs:
      * a list (Macaulay2Doc), a list of the prime ideals in R that
        are associated to I

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

ass is an abbreviation for associatedPrimes.

This function computes the list of associated primes for a module M using Ext
modules: the codimension i associated primes of M and $\mathrm{Ext}^i(M,R)$ are
identical, as shown in Eisenbud-Huneke-Vasconcelos, Invent. Math. 110 (1992)
207-235.

In some cases, see primaryDecomposition, also computes
the associated primes, in which case calling associatedPrimes,
requires no new computation and the list of associated primes
is in the same order as the list of primary components returned by
primaryDecomposition. Conversely, calling
associatedPrimes, beforehand will speed up the process of
primaryDecomposition(Module).

+-----------------------------------------------------------------------------+
|i1 : R = QQ[a..d]                                                            |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : M = coker(transpose matrix{{1_R,1,1,1}} | diagonalMatrix vars R)        |
|                                                                             |
|o2 = cokernel | 1 a 0 0 0 |                                                  |
|              | 1 0 b 0 0 |                                                  |
|              | 1 0 0 c 0 |                                                  |
|              | 1 0 0 0 d |                                                  |
|                                                                             |
|                            4                                                |
|o2 : R-module, quotient of R                                                 |
+-----------------------------------------------------------------------------+
|i3 : associatedPrimes M                                                      |
|                                                                             |
|o3 = {ideal (b, a), ideal (c, a), ideal (c, b), ideal (d, a), ideal (d, b),  |
|     ------------------------------------------------------------------------|
|     ideal (d, c)}                                                           |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+

For an ideal I, associatedPrimes I is mathematically equivalent to
associatedPrimes comodule I.

+----------------------------------------------------------------+
|i4 : I = intersect(ideal(a^2,b), ideal(a,b,c^5), ideal(b^4,c^4))|
|                                                                |
|             4     4   2 4                                      |
|o4 = ideal (b , b*c , a c )                                     |
|                                                                |
|o4 : Ideal of R                                                 |
+----------------------------------------------------------------+
|i5 : associatedPrimes I                                         |
|                                                                |
|o5 = {ideal (b, a), ideal (c, b)}                               |
|                                                                |
|o5 : List                                                       |
+----------------------------------------------------------------+
|i6 : associatedPrimes comodule I                                |
|                                                                |
|o6 = {ideal (b, a), ideal (c, b)}                               |
|                                                                |
|o6 : List                                                       |
+----------------------------------------------------------------+

For a quotient ring R, associatedPrimes R is equivalent to associatedPrimes
ideal R, the associated primes of the defining ideal of R.

+----------------------------+
|i7 : R = QQ[x,y,z]/(x^2,x*y)|
|                            |
|o7 = R                      |
|                            |
|o7 : QuotientRing           |
+----------------------------+
|i8 : associatedPrimes R     |
|                            |
|o8 = {ideal x, ideal (y, x)}|
|                            |
|o8 : List                   |
+----------------------------+

If the ideal is a monomial ideal (Macaulay2Doc), then a
more efficient strategy written by Greg Smith and Serkan Hosten is used. The
above comments about primary decomposition hold in this case too.

+-----------------------------------------------------------------------------+
|i9 : R = QQ[a..f];                                                           |
+-----------------------------------------------------------------------------+
|i10 : I = monomialIdeal ideal"abc,bcd,af3,a2cd,bd3d,adf,f5"                  |
|                                                                             |
|                             2               4            3   5              |
|o10 = monomialIdeal (a*b*c, a c*d, b*c*d, b*d , a*d*f, a*f , f )             |
|                                                                             |
|o10 : MonomialIdeal of R                                                     |
+-----------------------------------------------------------------------------+
|i11 : ass I                                                                  |
|                                                                             |
|o11 = {monomialIdeal (a, b, f), monomialIdeal (a, d, f), monomialIdeal (b, c,|
|      -----------------------------------------------------------------------|
|      f), monomialIdeal (b, d, f), monomialIdeal (c, d, f), monomialIdeal (a,|
|      -----------------------------------------------------------------------|
|      c, d, f)}                                                              |
|                                                                             |
|o11 : List                                                                   |
+-----------------------------------------------------------------------------+
|i12 : primaryDecomposition I                                                 |
|                                                                             |
|                       2           5                         5               |
|o12 = {monomialIdeal (a , b, a*f, f ), monomialIdeal (a, d, f ),             |
|      -----------------------------------------------------------------------|
|                                                     3                       |
|      monomialIdeal (b, c, f), monomialIdeal (b, d, f ), monomialIdeal (c,   |
|      -----------------------------------------------------------------------|
|       4        3                         4   5                              |
|      d , d*f, f ), monomialIdeal (a, c, d , f )}                            |
|                                                                             |
|o12 : List                                                                   |
+-----------------------------------------------------------------------------+

The list of associated primes corresponds to the list of primary components of
I: the i-th associated prime is the radical of the i-th primary component.

If a value to the option CodimensionLimit is provided, then only associated
primes of codimension at most this value are returned. This can save time if
the big height (that is, the maximal codimension of an associated prime) is
less than the projective dimension. This method stores the primes already found
in a cache, and calling it with a different value of CodimensionLimit will only
perform further computation if it is necessary.

There are three methods for computing associated primes in Macaulay2: If the
ideal is a monomial ideal, use code that Greg Smith and Serkan Hosten wrote. If
a primary decomposition has already been found, use the stashed associated
primes found. If neither of these is the case, then use Ext modules to find the
associated primes (this is Strategy => 1).

+-----------------------------------------------------------------------------+
|i13 : S = QQ[a,b,c,d,e];                                                     |
+-----------------------------------------------------------------------------+
|i14 : I1 = ideal(a,b,c);                                                     |
|                                                                             |
|o14 : Ideal of S                                                             |
+-----------------------------------------------------------------------------+
|i15 : I2 = ideal(a,b,d);                                                     |
|                                                                             |
|o15 : Ideal of S                                                             |
+-----------------------------------------------------------------------------+
|i16 : I3 = ideal(a,e);                                                       |
|                                                                             |
|o16 : Ideal of S                                                             |
+-----------------------------------------------------------------------------+
|i17 : P = I1*I2*I3                                                           |
|                                                                             |
|              3   2    2           2           2             2   2           |
|o17 = ideal (a , a e, a b, a*b*e, a d, a*d*e, a b, a*b*e, a*b , b e, a*b*d,  |
|      -----------------------------------------------------------------------|
|              2                                                              |
|      b*d*e, a c, a*c*e, a*b*c, b*c*e, a*c*d, c*d*e)                         |
|                                                                             |
|o17 : Ideal of S                                                             |
+-----------------------------------------------------------------------------+
|i18 : L1 = associatedPrimes P                                                |
|                                                                             |
|o18 = {ideal (e, a), ideal (c, b, a), ideal (d, b, a), ideal (d, c, b, a),   |
|      -----------------------------------------------------------------------|
|      ideal (e, c, b, a), ideal (e, d, b, a), ideal (e, d, c, b, a)}         |
|                                                                             |
|o18 : List                                                                   |
+-----------------------------------------------------------------------------+
|i19 : L2 = apply(associatedPrimes monomialIdeal P, J -> ideal J)             |
|                                                                             |
|o19 = {ideal (a, e), ideal (a, b, c), ideal (a, b, d), ideal (a, b, c, d),   |
|      -----------------------------------------------------------------------|
|      ideal (a, b, c, e), ideal (a, b, d, e), ideal (a, b, c, d, e)}         |
|                                                                             |
|o19 : List                                                                   |
+-----------------------------------------------------------------------------+
|i20 : M1 = set apply(L1, I -> sort flatten entries gens I)                   |
|                                                                             |
|o20 = set {{e, d, b, a}, {e, c, b, a}, {e, a}, {d, b, a}, {e, d, c, b, a},   |
|      -----------------------------------------------------------------------|
|      {d, c, b, a}, {c, b, a}}                                               |
|                                                                             |
|o20 : Set                                                                    |
+-----------------------------------------------------------------------------+
|i21 : M2 = set apply(L2, I -> sort flatten entries gens I)                   |
|                                                                             |
|o21 = set {{e, d, b, a}, {e, c, b, a}, {e, a}, {d, b, a}, {e, d, c, b, a},   |
|      -----------------------------------------------------------------------|
|      {d, c, b, a}, {c, b, a}}                                               |
|                                                                             |
|o21 : Set                                                                    |
+-----------------------------------------------------------------------------+
|i22 : assert(M1 === M2)                                                      |
+-----------------------------------------------------------------------------+

The method using Ext modules comes from Eisenbud-Huneke-Vasconcelos, Invent.
Math 110 (1992) 207-235.

Original author (for ideals): C. Yackel (see
http://faculty.mercer.edu/yackel_ca/ ). Updated for modules by J. Chen.

See also
========

  * primaryDecomposition(Ideal) -- irredundant
    primary decomposition of an ideal
  * primaryDecomposition(Module), --
    irredundant primary decomposition of a module
  * radical (MinimalPrimes) -- the radical of an ideal
  * minimalPrimes (MinimalPrimes) -- minimal primes of an
    ideal
  * topComponents -- compute top dimensional component of
    an ideal or module
  * removeLowestDimension -- remove components of
    lowest dimension

Ways to use associatedPrimes:
=============================

  * "associatedPrimes(Ideal)"
  * "associatedPrimes(Module)"
  * "associatedPrimes(Ring)"

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

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

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

The source of this document is in PrimaryDecomposition/doc.m2:771:0.

associated primes
*****************

The function associatedPrimes, returns a list of the
associated prime ideals for a given ideal I. The associated prime ideals
correspond to the irreducible components of the variety associated to I. They
are useful in many applications in commutative algebra, algebraic geometry and
combinatorics.

+-----------------------------------------------------------------------------+
|i1 : R = ZZ/101[a..d];                                                       |
+-----------------------------------------------------------------------------+
|i2 : I = ideal(a*b-c*d, (a*c-b*d)^2);                                        |
|                                                                             |
|o2 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i3 : associatedPrimes I                                                      |
|                                                                             |
|o3 = {ideal (d, a), ideal (c, b), ideal (b - c, a - d), ideal (b + c, a + d)}|
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+

See primary decomposition, for more information
about finding primary decompositions. To find just the minimal prime ideals see
minimal primes of an ideal (MinimalPrimes).

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

The source of this document is in PrimaryDecomposition/doc.m2:771:0.

primaryDecomposition -- irredundant primary decomposition of an ideal
*********************************************************************

  * Usage:
        primaryDecomposition I
  * Inputs:
      * I, an ideal (Macaulay2Doc), in a (quotient of a)
        polynomial ring R
  * Optional inputs (Macaulay2Doc),:
      * MinimalGenerators => a Boolean value (Macaulay2Doc),
        default value true, if false, the components will not be minimalized
      * Strategy, => ...,
        default value null,
  * Outputs:
      * a list (Macaulay2Doc), containing a minimal list of primary
        ideals whose intersection is I

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

This routine returns an irredundant primary decomposition for the ideal I. The
specific algorithm used varies depending on the characteristics of the ideal,
and can also be specified using the Strategy option. In all cases, the radical
of each entry of the output is equal to the corresponding entry of the output
of associatedPrimes.

Primary decomposition algorithms are very sensitive to the input. Some
algorithms work very well on certain classes of ideals, but poorly on other
classes. If this function seems to be taking too long, try another algorithm
using primaryDecomposition(...,Strategy=>...).

+-----------------------------------------------------------------------------+
|i1 : R = QQ[a..i];                                                           |
+-----------------------------------------------------------------------------+
|i2 : I = permanents(2,genericMatrix(R,a,3,3))                                |
|                                                                             |
|o2 = ideal (b*d + a*e, c*d + a*f, c*e + b*f, b*g + a*h, c*g + a*i, c*h + b*i,|
|     ------------------------------------------------------------------------|
|     e*g + d*h, f*g + d*i, f*h + e*i)                                        |
|                                                                             |
|o2 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i3 : C = primaryDecomposition I;                                             |
+-----------------------------------------------------------------------------+
|i4 : I == intersect C                                                        |
|                                                                             |
|o4 = true                                                                    |
+-----------------------------------------------------------------------------+
|i5 : #C                                                                      |
|                                                                             |
|o5 = 16                                                                      |
+-----------------------------------------------------------------------------+

This function has one optional input Strategy, which accepts three possible
values used to determine the algorithm for finding embedded components.

The available values are Res, which is closest to the original
Eisenbud-Huneke-Vasconcelos method, together with Hom and Sat.

If you want to specify the Strategy to be used by localize, as
well, this can be specified by passing a Hybrid Strategy in the form:
Hybrid{primaryDecomposition.Strategy, localize.Strategy}.

+--------------------------------------------------------+
|i6 : kk = ZZ/3                                          |
|                                                        |
|o6 = kk                                                 |
|                                                        |
|o6 : QuotientRing                                       |
+--------------------------------------------------------+
|i7 : R = kk[a,b]                                        |
|                                                        |
|o7 = R                                                  |
|                                                        |
|o7 : PolynomialRing                                     |
+--------------------------------------------------------+
|i8 : I = ideal {a^2, a*b}                               |
|                                                        |
|             2                                          |
|o8 = ideal (a , a*b)                                    |
|                                                        |
|o8 : Ideal of R                                         |
+--------------------------------------------------------+
|i9 : primaryDecomposition(I, Strategy => Hybrid{Res, 1})|
|                                                        |
|o9 = {ideal a, ideal (b, a)}                            |
|                                                        |
|o9 : List                                               |
+--------------------------------------------------------+

While the default (and typically fastest) strategy is Sat, it is recommended to
try different Strategy values if the computation of a particular embedded
component is taking too long. One can start the computation with one strategy,
and interrupt and resume with a different strategy (even multiple times) if
desired.

Recall that List / Function (Macaulay2Doc),
applies a function to each element of a list, returning the results as a list.
This is often useful with lists of ideals, such as the list C of primary
components.

+-----------------------------------------------------------------------------+
|i10 : C / toString / print;                                                  |
|ideal(i,h,g,f,e,d)                                                           |
|ideal(i,h,g,f,c,b*d+a*e)                                                     |
|ideal(i,h,g,e,b,c*d+a*f)                                                     |
|ideal(i,h,g,d,a,c*e+b*f)                                                     |
|ideal(i,h,g,c,b,a)                                                           |
|ideal(i,h,f,e,c,b)                                                           |
|ideal(i,g,f,d,c,a)                                                           |
|ideal(i,f,e,d,c,b*g+a*h)                                                     |
|ideal(i,f,c,b,a,e*g+d*h)                                                     |
|ideal(h,g,e,d,b,a)                                                           |
|ideal(h,f,e,d,b,c*g+a*i)                                                     |
|ideal(h,e,c,b,a,f*g+d*i)                                                     |
|ideal(g,f,e,d,a,c*h+b*i)                                                     |
|ideal(g,d,c,b,a,f*h+e*i)                                                     |
|ideal(f,e,d,c,b,a)                                                           |
|ideal(i^2,f*h+e*i,c*h+b*i,f*g+d*i,e*g+d*h,c*g+a*i,b*g+a*h,c*e+b*f,c*d+a*f,b*d|
|-----------------------------------------------------------------------------|
|+a*e,a^2,g*h*i,c*f*i,h^3,g*h^2,e*h^2,d*h^2,b*h^2,a*h^2,b*e*h,g^3,d*g^2,a*g^2,|
|-----------------------------------------------------------------------------|
|a*d*g,f^3,e*f^2,d*f^2,c*f^2,b*f^2,a*f^2,d*e*f,e^3,d*e^2,b*e^2,a*e^2,d^3,a*d^2|
|-----------------------------------------------------------------------------|
|,c^3,b*c^2,a*c^2,a*b*c,b^3,a*b^2)                                            |
+-----------------------------------------------------------------------------+
|i11 : C / codim                                                              |
|                                                                             |
|o11 = {6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 9}                       |
|                                                                             |
|o11 : List                                                                   |
+-----------------------------------------------------------------------------+
|i12 : C / degree                                                             |
|                                                                             |
|o12 = {1, 2, 2, 2, 1, 1, 1, 2, 2, 1, 2, 2, 2, 2, 1, 82}                      |
|                                                                             |
|o12 : List                                                                   |
+-----------------------------------------------------------------------------+

The corresponding list of associated prime ideals is cached and can be obtained
by using associatedPrimes(Ideal).

+---------------------------------+
|i13 : associatedPrimes I / print;|
|ideal a                          |
|ideal (b, a)                     |
+---------------------------------+

Some strategies require the ground ring to be a prime field but results can be
obtained in some cases even for more general ground rings.

+------------------------------+
|i14 : kk = GF(9)              |
|                              |
|o14 = kk                      |
|                              |
|o14 : GaloisField             |
+------------------------------+
|i15 : R = kk[a,b]             |
|                              |
|o15 = R                       |
|                              |
|o15 : PolynomialRing          |
+------------------------------+
|i16 : I = ideal {a^2, a*b}    |
|                              |
|              2               |
|o16 = ideal (a , a*b)         |
|                              |
|o16 : Ideal of R              |
+------------------------------+
|i17 : primaryDecomposition(I) |
|                              |
|                           2  |
|o17 = {ideal a, ideal (b, a )}|
|                              |
|o17 : List                    |
+------------------------------+

See also
========

  * primaryDecomposition(Module), --
    irredundant primary decomposition of a module
  * associatedPrimes(Ideal) -- find associated primes
  * radical (MinimalPrimes) -- the radical of an ideal
  * minimalPrimes (MinimalPrimes) -- minimal primes of an
    ideal
  * topComponents -- compute top dimensional component of
    an ideal or module
  * removeLowestDimension -- remove components of
    lowest dimension

Ways to use primaryDecomposition:
=================================

  * "primaryDecomposition(Ideal)"
  * primaryDecomposition(Module), --
    irredundant primary decomposition of a module
  * "primaryDecomposition(Ring)" -- see primaryDecomposition(Module),
    -- irredundant primary decomposition of a
    module

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

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

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

The source of this document is in PrimaryDecomposition/doc.m2:771:0.

primary decomposition
*********************

Introduction
============

The function primaryDecomposition, applied to an
ideal I returns a list of ideals. These ideals have two key features, first,
their intersection is equal to the ideal I and second the ideals are primary.
Therefore these ideals form a primary decomposition of the ideal. Since the
ideals are primary their corresponding varieties are irreducible. The
decomposition returned is irredundant, which means that the radicals of the
ideals returned are distinct prime ideals which are the associated prime ideals
for I (see associated primes).

An example
==========

+-----------------------------------------------------------------------------+
|i1 : R = ZZ/101[a..d];                                                       |
+-----------------------------------------------------------------------------+
|i2 : I = ideal(a*b-c*d, (a*c-b*d)^2);                                        |
|                                                                             |
|o2 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i3 : primaryDecomposition I                                                  |
|                                                                             |
|              2                   2           2        2                     |
|o3 = {ideal (d , a*d, a*b - c*d, a ), ideal (c , b*c, b , a*b - c*d), ideal  |
|     ------------------------------------------------------------------------|
|                         2           2              2           2            |
|     (a*c + b*d - 2c*d, b  - 2b*c + c , a*b - c*d, a  - 2a*d + d ), ideal    |
|     ------------------------------------------------------------------------|
|                         2           2              2           2            |
|     (a*c + b*d + 2c*d, b  + 2b*c + c , a*b - c*d, a  + 2a*d + d )}          |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+

To obtain the associated prime ideals corresponding to the primary components
returned by primaryDecomposition use the function associatedPrimes.
Each entry in the list given by associatedPrimes is the
radical of the respective entry in the list given by primary decomposition.

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

The source of this document is in PrimaryDecomposition/doc.m2:771:0.

primaryComponent -- find a primary component corresponding to an associated prime
*********************************************************************************

  * Usage:
        Q = primaryComponent(I, P)
  * Inputs:
      * I, an ideal (Macaulay2Doc), an ideal in a (quotient of a)
        polynomial ring R
      * P, an ideal (Macaulay2Doc), an associated prime of I
  * Optional inputs (Macaulay2Doc),:
      * Increment => ..., default value 1
      * Strategy => ..., default value 2
  * Outputs:
      * Q, an ideal (Macaulay2Doc), a P-primary ideal of I

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

The output Q is topComponents(I + P^m) for sufficiently large m. The criterion
that Q is primary is given in Eisenbud-Huneke-Vasconcelos, Invent. Math. 110
(1992) 207-235. However, we use localize(Ideal,Ideal).

The Strategy option value sets the strategy option for localize,
and should be one of the following:

  * Strategy => 0 -- Uses localize, Strategy 0
  * Strategy => 1 -- Uses localize, Strategy 1
  * Strategy => 2 -- Uses localize, Strategy 2 - default

The Increment option value should be an integer. The algorithm given in
Eisenbud-Huneke-Vasconcelos, Invent. Math. 110 (1992) 207-235, relies on
topComponents(I + P^m) for $m$ sufficiently large. The algorithm begins with $m
= 1$, and increases $m$ by the value of the Increment option until m is
sufficiently large. The default value is 1.

Authored by C. Yackel (see http://faculty.mercer.edu/yackel_ca ). Last modified
June, 2000.

See also
========

  * associatedPrimes(Ideal) -- find associated primes
  * primaryDecomposition(Ideal) -- irredundant
    primary decomposition of an ideal
  * radical (MinimalPrimes) -- the radical of an ideal
  * minimalPrimes (MinimalPrimes) -- minimal primes of an
    ideal
  * topComponents -- compute top dimensional component of
    an ideal or module
  * removeLowestDimension -- remove components of
    lowest dimension

Ways to use primaryComponent:
=============================

  * "primaryComponent(Ideal,Ideal)"

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

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

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

The source of this document is in PrimaryDecomposition/doc.m2:771:0.

localize -- localize an ideal at a prime ideal
**********************************************

  * Usage:
        localize(I, P)
  * Inputs:
      * I, an ideal (Macaulay2Doc), an ideal in a (quotient of a)
        polynomial ring R
      * P, an ideal (Macaulay2Doc), a prime ideal in the same ring
  * Optional inputs (Macaulay2Doc),:
      * Strategy => ..., default value 1
  * Outputs:
      * an ideal (Macaulay2Doc), the extension contraction ideal
        $I R_P \cap R$.

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

The result is the ideal obtained by first extending to the localized ring and
then contracting back to the original ring.

+-------------------------+
|i1 : R = ZZ/(101)[x,y];  |
+-------------------------+
|i2 : I = ideal (x^2,x*y);|
|                         |
|o2 : Ideal of R          |
+-------------------------+
|i3 : P1 = ideal (x);     |
|                         |
|o3 : Ideal of R          |
+-------------------------+
|i4 : localize(I,P1)      |
|                         |
|o4 = ideal x             |
|                         |
|o4 : Ideal of R          |
+-------------------------+
|i5 : P2 = ideal (x,y);   |
|                         |
|o5 : Ideal of R          |
+-------------------------+
|i6 : localize(I,P2)      |
|                         |
|             2           |
|o6 = ideal (x , x*y)     |
|                         |
|o6 : Ideal of R          |
+-------------------------+
+----------------------------+
|i7 : R = ZZ/31991[x,y,z];   |
+----------------------------+
|i8 : I = ideal(x^2,x*z,y*z);|
|                            |
|o8 : Ideal of R             |
+----------------------------+
|i9 : P1 = ideal(x,y);       |
|                            |
|o9 : Ideal of R             |
+----------------------------+
|i10 : localize(I,P1)        |
|                            |
|o10 = ideal (y, x)          |
|                            |
|o10 : Ideal of R            |
+----------------------------+
|i11 : P2 = ideal(x,z);      |
|                            |
|o11 : Ideal of R            |
+----------------------------+
|i12 : localize(I,P2)        |
|                            |
|                 2          |
|o12 = ideal (z, x )         |
|                            |
|o12 : Ideal of R            |
+----------------------------+

The strategy option value should be one of the following, with default value 1.

  * Strategy => 0 -- Uses the algorithm of Eisenbud-Huneke-Vasconcelos

    This strategy does not require the calculation of the assassinator, but can
    require the computation of high powers of ideals. The method appears in
    Eisenbud-Huneke-Vasconcelos, Invent. Math. 110 (1992) 207-235.
  * Strategy => 1 -- Uses a separator to find the localization

    This strategy uses a separator polynomial - a polynomial in all of the
    associated primes of {   t I} but {      t P} and those contained in {   t
    P}. In this strategy, the assassinator of the ideal will be recalled, or
    recomputed using Strategy => 1, if unknown. The
    separator polynomial method is described in Shimoyama-Yokoyama, J. Symbolic
    computation, 22(3) 247-277 (1996). This is the same as Strategy => 1 except
    that, if unknown, the assassinator is computed using Strategy => 2.
  * Strategy => 2 -- Uses a separator to find the localization

Authored by C. Yackel (see http://faculty.mercer.edu/yackel_ca ). Last modified
June, 2000.

Caveat
======

The ideal P is not checked to be prime.

See also
========

  * primaryDecomposition(Ideal) -- irredundant
    primary decomposition of an ideal
  * radical (MinimalPrimes) -- the radical of an ideal
  * minimalPrimes (MinimalPrimes) -- minimal primes of an
    ideal
  * topComponents -- compute top dimensional component of
    an ideal or module
  * removeLowestDimension -- remove components of
    lowest dimension

Ways to use localize:
=====================

  * "localize(Ideal,Ideal)"

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

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

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

The source of this document is in PrimaryDecomposition/doc.m2:771:0.

irreducibleDecomposition -- express a monomial ideal as an intersection of irreducible monomial ideals
******************************************************************************************************

  * Usage:
        irreducibleDecomposition I
  * Inputs:
      * I, an ideal (Macaulay2Doc),
  * Outputs:
      * a list (Macaulay2Doc), containing the irreducible monomial
        ideals whose intersection is I

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

+---------------------------------------------------------------+
|i1 : R = QQ[x..z];                                             |
+---------------------------------------------------------------+
|i2 : I = monomialIdeal (x*y^3, x*y^2*z)                        |
|                                                               |
|                       3     2                                 |
|o2 = monomialIdeal (x*y , x*y z)                               |
|                                                               |
|o2 : MonomialIdeal of R                                        |
+---------------------------------------------------------------+
|i3 : w = irreducibleDecomposition I                            |
|                                                               |
|                                      2                  3     |
|o3 = {monomialIdeal x, monomialIdeal y , monomialIdeal (y , z)}|
|                                                               |
|o3 : List                                                      |
+---------------------------------------------------------------+
|i4 : assert( I == intersect w )                                |
+---------------------------------------------------------------+

Ways to use irreducibleDecomposition:
=====================================

  * "irreducibleDecomposition(MonomialIdeal)"

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

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

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

The source of this document is in PrimaryDecomposition/doc.m2:771:0.

isPrimary -- determine whether a submodule is primary
*****************************************************

  * Usage:
        isPrimary Q
        isPrimary(Q, P)
        isPrimary(M, Q)
  * Inputs:
      * Q, an ideal (Macaulay2Doc), or a module (Macaulay2Doc),
        the submodule or ideal to be checked for being
        primary
      * P, an ideal (Macaulay2Doc), the radical (MinimalPrimes),
        of Q
      * M, a module (Macaulay2Doc), the ambient module
  * Optional inputs (Macaulay2Doc),:
      * Strategy => a thing (Macaulay2Doc), default value null,
        See associatedPrimes(...,Strategy=>...), and
        isPrime(Ideal, Strategy => ...) (missing documentation)
  * Outputs:
      * a Boolean value (Macaulay2Doc), true if Q is primary,
        false otherwise

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

Checks to see if a given submodule Q of a module M is primary, i.e. whether or
not M/Q has exactly one associated prime (which is equivalent for finitely
generated modules over Noetherian rings). If the input is a single ideal, then
the ambient module is taken to be the ring (i.e. the free module of rank 1),
and does not need to be specified.

+------------------------------------+
|i1 : Q = ZZ/101[x,y,z]              |
|                                    |
|o1 = Q                              |
|                                    |
|o1 : PolynomialRing                 |
+------------------------------------+
|i2 : isPrimary ideal(y^6)           |
|                                    |
|o2 = true                           |
+------------------------------------+
|i3 : isPrimary(ideal(y^6), ideal(y))|
|                                    |
|o3 = true                           |
+------------------------------------+
|i4 : isPrimary ideal(x^4, y^7)      |
|                                    |
|o4 = true                           |
+------------------------------------+
|i5 : isPrimary ideal(x*y, y^2)      |
|                                    |
|o5 = false                          |
+------------------------------------+

See also
========

  * primaryDecomposition(Ideal) -- irredundant
    primary decomposition of an ideal
  * primaryDecomposition(Module), --
    irredundant primary decomposition of a module
  * associatedPrimes -- find associated primes

Ways to use isPrimary:
======================

  * "isPrimary(Ideal)"
  * "isPrimary(Ideal,Ideal)"
  * "isPrimary(Module,Module)"

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

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

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

The source of this document is in PrimaryDecomposition/doc.m2:771:0.

kernelOfLocalization -- the kernel of the localization map
**********************************************************

  * Usage:
        kernelOfLocalization(M, P)
  * Inputs:
      * M, a module (Macaulay2Doc),
      * P, an ideal (Macaulay2Doc), the prime ideal to localize at
  * Outputs:
      * a module (Macaulay2Doc), the kernel of the localization
        map M -> M_P

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

This method computes the kernel of the natural map from a module to its
localization at a given prime ideal. The efficiency of this method is
intimately tied to the efficiency of computation of associated primes for the
module - if the associated primes of M have previously been computed, then this
method should finish quickly.

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x_0..x_3]                                                        |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : (I1,I2,I3) = monomialCurveIdeal_R \ ({1,2,3},{2,3},{4,5})               |
|                                                                             |
|              2                       2                 3      2          5  |
|o2 = (ideal (x  - x x , x x  - x x , x  - x x ), ideal(x  - x x ), ideal(x  -|
|              2    1 3   1 2    0 3   1    0 2          1    0 2          1  |
|     ------------------------------------------------------------------------|
|        4                                                                    |
|     x x ))                                                                  |
|      0 2                                                                    |
|                                                                             |
|o2 : Sequence                                                                |
+-----------------------------------------------------------------------------+
|i3 : M = comodule I1 ++ comodule I2 ++ comodule I3                           |
|                                                                             |
|o3 = cokernel | x_2^2-x_1x_3 x_1x_2-x_0x_3 x_1^2-x_0x_2 0                    |
|              | 0            0             0            x_1^3-x_0x_2^2       |
|              | 0            0             0            0                    |
|                                                                             |
|                            3                                                |
|o3 : R-module, quotient of R                                                 |
|-----------------------------------------------------------------------------|
|0              |                                                             |
|0              |                                                             |
|x_1^5-x_0x_2^4 |                                                             |
+-----------------------------------------------------------------------------+
|i4 : elapsedTime kernelOfLocalization(M, I1)                                 |
| -- .191264s elapsed                                                         |
|                                                                             |
|o4 = subquotient (| 0 0 |, | x_2^2-x_1x_3 x_1x_2-x_0x_3 x_1^2-x_0x_2         |
|                  | 1 0 |  | 0            0             0                    |
|                  | 0 1 |  | 0            0             0                    |
|                                                                             |
|                               3                                             |
|o4 : R-module, subquotient of R                                              |
|-----------------------------------------------------------------------------|
|0              0              |)                                             |
|x_1^3-x_0x_2^2 0              |                                              |
|0              x_1^5-x_0x_2^4 |                                              |
+-----------------------------------------------------------------------------+
|i5 : elapsedTime kernelOfLocalization(M, I2)                                 |
| -- .0216856s elapsed                                                        |
|                                                                             |
|o5 = subquotient (| 1 0 |, | x_2^2-x_1x_3 x_1x_2-x_0x_3 x_1^2-x_0x_2         |
|                  | 0 0 |  | 0            0             0                    |
|                  | 0 1 |  | 0            0             0                    |
|                                                                             |
|                               3                                             |
|o5 : R-module, subquotient of R                                              |
|-----------------------------------------------------------------------------|
|0              0              |)                                             |
|x_1^3-x_0x_2^2 0              |                                              |
|0              x_1^5-x_0x_2^4 |                                              |
+-----------------------------------------------------------------------------+
|i6 : elapsedTime kernelOfLocalization(M, I3)                                 |
| -- .02146s elapsed                                                          |
|                                                                             |
|o6 = subquotient (| 1 0 |, | x_2^2-x_1x_3 x_1x_2-x_0x_3 x_1^2-x_0x_2         |
|                  | 0 1 |  | 0            0             0                    |
|                  | 0 0 |  | 0            0             0                    |
|                                                                             |
|                               3                                             |
|o6 : R-module, subquotient of R                                              |
|-----------------------------------------------------------------------------|
|0              0              |)                                             |
|x_1^3-x_0x_2^2 0              |                                              |
|0              x_1^5-x_0x_2^4 |                                              |
+-----------------------------------------------------------------------------+

See also
========

  * associatedPrimes(Module) -- find associated primes
  * primaryDecomposition(Module), --
    irredundant primary decomposition of a module

Ways to use kernelOfLocalization:
=================================

  * "kernelOfLocalization(Module,Ideal)"

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

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

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

The source of this document is in PrimaryDecomposition/doc.m2:771:0.

primaryDecomposition(Module) -- irredundant primary decomposition of a module
*****************************************************************************

  * Function: primaryDecomposition,
  * Usage:
        primaryDecomposition M
  * Inputs:
      * M, a module (Macaulay2Doc), in a (quotient of a)
        polynomial ring R
  * Optional inputs (Macaulay2Doc),:
      * MinimalGenerators, => a Boolean value (Macaulay2Doc),
        default value true, if false, the
        components will not be minimalized
      * Strategy, => ...,
        default value null,
  * Outputs:
      * a list (Macaulay2Doc), containing a minimal list of primary
        submodules of M whose intersection is 0

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

This routine returns a minimal primary decomposition for the zero submodule of
M, i.e. a minimal list of submodules Q_i of M such that the intersection of all
the Q_i is 0 and Ass(M/Q_i) = {p_i} for some associated prime p_i of M.

Here minimality means that the associated primes of the submodules are pairwise
distinct, and that the decomposition is irredundant, i.e. no submodule contains
the intersection of the others. The i-th element of this output is primary to
the i-th element of associatedPrimes M. The algorithm used is inspired by the
Eisenbud-Huneke-Vasconcelos algorithm, modified to work for modules.

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x_0..x_3]                                                        |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : (I1,I2,I3) = ({1,2,3},{2,3},{4,5}) / monomialCurveIdeal_R               |
|                                                                             |
|              2                       2                 3      2          5  |
|o2 = (ideal (x  - x x , x x  - x x , x  - x x ), ideal(x  - x x ), ideal(x  -|
|              2    1 3   1 2    0 3   1    0 2          1    0 2          1  |
|     ------------------------------------------------------------------------|
|        4                                                                    |
|     x x ))                                                                  |
|      0 2                                                                    |
|                                                                             |
|o2 : Sequence                                                                |
+-----------------------------------------------------------------------------+
|i3 : M = comodule I1 ++ comodule I2 ++ comodule I3                           |
|                                                                             |
|o3 = cokernel | x_2^2-x_1x_3 x_1x_2-x_0x_3 x_1^2-x_0x_2 0                    |
|              | 0            0             0            x_1^3-x_0x_2^2       |
|              | 0            0             0            0                    |
|                                                                             |
|                            3                                                |
|o3 : R-module, quotient of R                                                 |
|-----------------------------------------------------------------------------|
|0              |                                                             |
|0              |                                                             |
|x_1^5-x_0x_2^4 |                                                             |
+-----------------------------------------------------------------------------+
|i4 : associatedPrimes M                                                      |
|                                                                             |
|             3      2          5      4           2                       2  |
|o4 = {ideal(x  - x x ), ideal(x  - x x ), ideal (x  - x x , x x  - x x , x  -|
|             1    0 2          1    0 2           2    1 3   1 2    0 3   1  |
|     ------------------------------------------------------------------------|
|     x x )}                                                                  |
|      0 2                                                                    |
|                                                                             |
|o4 : List                                                                    |
+-----------------------------------------------------------------------------+
|i5 : C = primaryDecomposition M;                                             |
+-----------------------------------------------------------------------------+
|i6 : netList C                                                               |
|                                                                             |
|     +-----------------------------------------------------------------------|
|o6 = |subquotient (| 1 0 |, | x_2^2-x_1x_3 x_1x_2-x_0x_3 x_1^2-x_0x_2 0      |
|     |             | 0 0 |  | 0            0             0            x_1^3-x|
|     |             | 0 1 |  | 0            0             0            0      |
|     +-----------------------------------------------------------------------|
|     |subquotient (| 1 0 |, | x_2^2-x_1x_3 x_1x_2-x_0x_3 x_1^2-x_0x_2 0      |
|     |             | 0 1 |  | 0            0             0            x_1^3-x|
|     |             | 0 0 |  | 0            0             0            0      |
|     +-----------------------------------------------------------------------|
|     |subquotient (| 0 0 |, | x_2^2-x_1x_3 x_1x_2-x_0x_3 x_1^2-x_0x_2 0      |
|     |             | 1 0 |  | 0            0             0            x_1^3-x|
|     |             | 0 1 |  | 0            0             0            0      |
|     +-----------------------------------------------------------------------|
|-----------------------------------------------------------------------------|
|-------------------------+                                                   |
|        0              |)|                                                   |
|_0x_2^2 0              | |                                                   |
|        x_1^5-x_0x_2^4 | |                                                   |
|-------------------------+                                                   |
|        0              |)|                                                   |
|_0x_2^2 0              | |                                                   |
|        x_1^5-x_0x_2^4 | |                                                   |
|-------------------------+                                                   |
|        0              |)|                                                   |
|_0x_2^2 0              | |                                                   |
|        x_1^5-x_0x_2^4 | |                                                   |
|-------------------------+                                                   |
+-----------------------------------------------------------------------------+
|i7 : intersect C == 0 and all(C, isPrimary_M)                                |
|                                                                             |
|o7 = true                                                                    |
+-----------------------------------------------------------------------------+
|i8 : C / degree                                                              |
|                                                                             |
|o8 = {5, 3, 8}                                                               |
|                                                                             |
|o8 : List                                                                    |
+-----------------------------------------------------------------------------+

Recall that in Macaulay2, a module is commonly represented as a
subquotient (Macaulay2Doc), which is an ordered pair consisting of
generators (Macaulay2Doc), and relations (Macaulay2Doc),
represented as column matrices. As submodules of M,
each module in the output list has the same relations as M, and has generators
which are R-linear combinations of generators of M, where R = ring M.

To obtain a primary decomposition of a submodule N, run this function on the
quotient M/N. Note that the / command does not check whether N is actually a
submodule of M, and a non-sensible result may be returned if this is not the
case.

This function generalizes primary decomposition of ideals (more precisely,
cyclic modules), as can be seen by calling primaryDecomposition comodule I for
an ideal I. For convenience, one can also call primaryDecomposition R for a
ring R (which is most useful when R is a QuotientRing (Macaulay2Doc)).
When computing primary decompositions of ideals
with this function, remember to add back the original ideal to obtain the
desired primary ideals, as in the following example.

+-----------------------------------------------------------------------------+
|i9 : I = intersect((ideal(x_0..x_3))^5, (ideal(x_0..x_2))^4, (ideal(x_0..x_1)|
|                                                                             |
|             3         2       2         3       4       3     2 2     3     |
|o9 = ideal (x x x , x x x x , x x x x , x x x , x x , x x x , x x x , x x x ,|
|             1 2 3   0 1 2 3   0 1 2 3   0 2 3   1 3   0 1 3   0 1 3   0 1 3 |
|     ------------------------------------------------------------------------|
|      4     3 2     2 2   2   2   3 2   4       3     2 2     3       4      |
|     x x , x x , x x x , x x x , x x , x x , x x x , x x x , x x x , x x ,   |
|      0 3   1 2   0 1 2   0 1 2   0 2   1 2   0 1 2   0 1 2   0 1 2   0 2    |
|     ------------------------------------------------------------------------|
|      5     4   2 3   3 2   4     5                                          |
|     x , x x , x x , x x , x x , x )                                         |
|      1   0 1   0 1   0 1   0 1   0                                          |
|                                                                             |
|o9 : Ideal of R                                                              |
|-----------------------------------------------------------------------------|
|)^3)                                                                         |
+-----------------------------------------------------------------------------+
|i10 : S = R/I                                                                |
|                                                                             |
|o10 = S                                                                      |
|                                                                             |
|o10 : QuotientRing                                                           |
+-----------------------------------------------------------------------------+
|i11 : associatedPrimes S                                                     |
|                                                                             |
|o11 = {ideal (x , x ), ideal (x , x , x ), ideal (x , x , x , x )}           |
|               1   0           2   1   0           3   2   1   0             |
|                                                                             |
|o11 : List                                                                   |
+-----------------------------------------------------------------------------+
|i12 : comps = primaryDecomposition S                                         |
|                                                                             |
|o12 = {subquotient (| x_1^3 x_0x_1^2 x_0^2x_1 x_0^3 |, | x_1^3x_2x_3         |
|      -----------------------------------------------------------------------|
|      x_0x_1^2x_2x_3 x_0^2x_1x_2x_3 x_0^3x_2x_3 x_1^4x_3 x_0x_1^3x_3         |
|      -----------------------------------------------------------------------|
|      x_0^2x_1^2x_3 x_0^3x_1x_3 x_0^4x_3 x_1^3x_2^2 x_0x_1^2x_2^2            |
|      -----------------------------------------------------------------------|
|      x_0^2x_1x_2^2 x_0^3x_2^2 x_1^4x_2 x_0x_1^3x_2 x_0^2x_1^2x_2 x_0^3x_1x_2|
|      -----------------------------------------------------------------------|
|      x_0^4x_2 x_1^5 x_0x_1^4 x_0^2x_1^3 x_0^3x_1^2 x_0^4x_1 x_0^5 |),       |
|      -----------------------------------------------------------------------|
|      subquotient (| x_1^3x_2 x_0x_1^2x_2 x_0^2x_1x_2 x_0^3x_2 x_1^4 x_0x_1^3|
|      -----------------------------------------------------------------------|
|      x_0^2x_1^2 x_0^3x_1 x_0^4 x_2^5 |, | x_1^3x_2x_3 x_0x_1^2x_2x_3        |
|      -----------------------------------------------------------------------|
|      x_0^2x_1x_2x_3 x_0^3x_2x_3 x_1^4x_3 x_0x_1^3x_3 x_0^2x_1^2x_3          |
|      -----------------------------------------------------------------------|
|      x_0^3x_1x_3 x_0^4x_3 x_1^3x_2^2 x_0x_1^2x_2^2 x_0^2x_1x_2^2 x_0^3x_2^2 |
|      -----------------------------------------------------------------------|
|      x_1^4x_2 x_0x_1^3x_2 x_0^2x_1^2x_2 x_0^3x_1x_2 x_0^4x_2 x_1^5 x_0x_1^4 |
|      -----------------------------------------------------------------------|
|      x_0^2x_1^3 x_0^3x_1^2 x_0^4x_1 x_0^5 |), subquotient (| x_3^5 x_2^5 |, |
|      -----------------------------------------------------------------------|
|      | x_1^3x_2x_3 x_0x_1^2x_2x_3 x_0^2x_1x_2x_3 x_0^3x_2x_3 x_1^4x_3       |
|      -----------------------------------------------------------------------|
|      x_0x_1^3x_3 x_0^2x_1^2x_3 x_0^3x_1x_3 x_0^4x_3 x_1^3x_2^2 x_0x_1^2x_2^2|
|      -----------------------------------------------------------------------|
|      x_0^2x_1x_2^2 x_0^3x_2^2 x_1^4x_2 x_0x_1^3x_2 x_0^2x_1^2x_2 x_0^3x_1x_2|
|      -----------------------------------------------------------------------|
|      x_0^4x_2 x_1^5 x_0x_1^4 x_0^2x_1^3 x_0^3x_1^2 x_0^4x_1 x_0^5 |)}       |
|                                                                             |
|o12 : List                                                                   |
+-----------------------------------------------------------------------------+
|i13 : apply(comps, Q -> ideal mingens(I + ideal gens Q))                     |
|                                                                             |
|               3     2   2     3           3       2     2       3     4     |
|o13 = {ideal (x , x x , x x , x ), ideal (x x , x x x , x x x , x x , x ,    |
|               1   0 1   0 1   0           1 2   0 1 2   0 1 2   0 2   1     |
|      -----------------------------------------------------------------------|
|         3   2 2   3     4   5           5   3         2       2             |
|      x x , x x , x x , x , x ), ideal (x , x x x , x x x x , x x x x ,      |
|       0 1   0 1   0 1   0   2           3   1 2 3   0 1 2 3   0 1 2 3       |
|      -----------------------------------------------------------------------|
|       3       4       3     2 2     3       4     5   3 2     2 2   2   2   |
|      x x x , x x , x x x , x x x , x x x , x x , x , x x , x x x , x x x ,  |
|       0 2 3   1 3   0 1 3   0 1 3   0 1 3   0 3   2   1 2   0 1 2   0 1 2   |
|      -----------------------------------------------------------------------|
|       3 2   4       3     2 2     3       4     5     4   2 3   3 2   4     |
|      x x , x x , x x x , x x x , x x x , x x , x , x x , x x , x x , x x ,  |
|       0 2   1 2   0 1 2   0 1 2   0 1 2   0 2   1   0 1   0 1   0 1   0 1   |
|      -----------------------------------------------------------------------|
|       5                                                                     |
|      x )}                                                                   |
|       0                                                                     |
|                                                                             |
|o13 : List                                                                   |
+-----------------------------------------------------------------------------+
|i14 : I == intersect oo                                                      |
|                                                                             |
|o14 = true                                                                   |
+-----------------------------------------------------------------------------+

The results of the computation are stored inside M.cache, as a
MutableHashTable (Macaulay2Doc), whose keys are associated
primes and values are the corresponding primary components. The list of all
associated prime ideals is also cached, and can be obtained with
associatedPrimes M. The computation may be interrupted at any point, and can be
resumed later without recomputing already known primary components. To display
detailed information throughout the computation, set the global variable
debugLevel (Macaulay2Doc), to a value greater than 0, e.g.
debugLevel=1 (or debugLevel=2 for even more detail).

This function has one optional input Strategy, which accepts three possible
values that determine the algorithm for finding embedded components.

The available values are Hybrid{Res}, which is closest to the original
Eisenbud-Huneke-Vasconcelos method, together with Hybrid{Hom} and Hybrid{Sat}.

While the default (and typically fastest) strategy is Sat, it is recommended to
try different Strategy values if the computation of a particular embedded
component is taking too long. One can start the computation with one strategy,
and interrupt and resume with a different strategy (even multiple times) if
desired.

Caveat
======

Note that although isolated components (i.e. those corresponding to minimal
primes) are unique, embedded components are never unique, and thus specifying
generators of an embedded component requires non-canonical choices. For speed
purposes, this algorithm searches for embedded components obtained by adding a
bracket power of the embedded prime, with exponent determined by the degrees of
generators of the embedded prime and ann M. In particular, the generators of an
embedded component may not be of minimal possible degree.

See also
========

  * primaryDecomposition(Ideal) -- irredundant
    primary decomposition of an ideal
  * associatedPrimes(Module) -- find associated primes
  * isPrimary -- determine whether a submodule is primary
  * topComponents -- compute top dimensional component of
    an ideal or module
  * primaryDecomposition(...,Strategy=>...)

Ways to use this method:
========================

  * primaryDecomposition(Module), --
    irredundant primary decomposition of a module
  * "primaryDecomposition(Ring)"
-------------------------------------------------------------------------------

The source of this document is in PrimaryDecomposition/doc.m2:771:0.

regSeqInIdeal -- a regular sequence contained in an ideal
*********************************************************

  * Usage:
        regSeqInIdeal I
        regSeqInIdeal(I, n)
        regSeqInIdeal(I, n, c, t)
  * Inputs:
      * I, an ideal (Macaulay2Doc),
      * n, an integer (Macaulay2Doc), the length of the regular
        sequence returned
      * c, an integer (Macaulay2Doc), the codimension of I if known
      * t, an integer (Macaulay2Doc), a limit on the time spent (in
        seconds) for each trial
  * Optional inputs (Macaulay2Doc),:
      * Strategy => ..., default value "Quick"
  * Outputs:
      * an ideal (Macaulay2Doc), generated by a regular sequence
        of length n contained in I

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

This method computes a regular sequence of length n contained in a given ideal
I. It attempts to do so by first trying "sparse" combinations of the
generators, i.e. elements which are either generators or sums of two
generators. If a sparse regular sequence is not found, then dense combinations
of generators will be tried.

If the length n is either unspecified or greater than the codimension of I then
it is silently replaced with the codimension of I. The ideal I should be in a
polynomial (or at least Cohen-Macaulay) ring, so that codim I = grade I.

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x_0..x_7]                                                        |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : I = intersect(ideal(x_0,x_1,x_2,x_3), ideal(x_4,x_5,x_6,x_7), ideal(x_0,|
|                                                                             |
|o2 = ideal (x x , x x , x x , x x , x x , x x , x x , x x , x x , x x , x x ,|
|             2 7   0 7   3 6   2 6   1 6   0 6   2 5   0 5   3 4   2 4   1 4 |
|     ------------------------------------------------------------------------|
|     x x )                                                                   |
|      0 4                                                                    |
|                                                                             |
|o2 : Ideal of R                                                              |
|-----------------------------------------------------------------------------|
|x_2,x_4,x_6), ideal(x_1,x_3,x_5,7))                                          |
+-----------------------------------------------------------------------------+
|i3 : elapsedTime regSeqInIdeal I                                             |
| -- .0385038s elapsed                                                        |
|                                                                             |
|o3 = ideal (x x , x x  + x x , x x  + x x , x x  + x x )                     |
|             2 7   3 6    0 7   2 5    0 7   1 4    0 7                      |
|                                                                             |
|o3 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+

If I is the unit ideal, then an ideal of variables of the ring is returned.

If the codimension of I is already known, then one can specify this, along with
a time limit for each trial (normally this is taken from the length of time for
computing codim I). This can result in a significant speedup: in the following
example, codim I takes more than a minute to complete.

+-----------------------------------------------------------------------------+
|i4 : R = QQ[h,l,s,x,y,z]                                                     |
|                                                                             |
|o4 = R                                                                       |
|                                                                             |
|o4 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i5 : I = ideal(h*l-l^2-4*l*s+h*y,h^2*s-6*l*s^3+h^2*z,x*h^2-l^2*s-h^3,h^8,l^8,|
|                                                                             |
|                   2                     3    2     2      3    2     2    8 |
|o5 = ideal (h*l - l  - 4l*s + h*y, - 6l*s  + h s + h z, - h  - l s + h x, h ,|
|     ------------------------------------------------------------------------|
|      8   8                                                                  |
|     l , s )                                                                 |
|                                                                             |
|o5 : Ideal of R                                                              |
|-----------------------------------------------------------------------------|
|s^8)                                                                         |
+-----------------------------------------------------------------------------+
|i6 : isSubset(I, ideal(s,l,h)) -- implies codim I == 3                       |
|                                                                             |
|o6 = true                                                                    |
+-----------------------------------------------------------------------------+
|i7 : elapsedTime regSeqInIdeal(I, 3, 3, 1)                                   |
| -- .00969523s elapsed                                                       |
|                                                                             |
|                   2                3    2     2    8    3    2     2        |
|o7 = ideal (h*l - l  - 4l*s + h*y, h  + l s - h x, s  + h  + l s - h x)      |
|                                                                             |
|o7 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+

See also
========

  * radical (MinimalPrimes) -- the radical of an ideal

Ways to use regSeqInIdeal:
==========================

  * "regSeqInIdeal(Ideal)"
  * "regSeqInIdeal(Ideal,ZZ)"
  * "regSeqInIdeal(Ideal,ZZ,ZZ,ZZ)"

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

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

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

The source of this document is in PrimaryDecomposition/doc.m2:771:0.

removeLowestDimension -- remove components of lowest dimension
**************************************************************

  * Usage:
        removeLowestDimension M
  * Inputs:
      * M, an ideal (Macaulay2Doc), or a module (Macaulay2Doc),
  * Outputs:
      * an ideal (Macaulay2Doc), or a module (Macaulay2Doc),

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

This function yields the intersection of the primary components of M except
those of lowest dimension, and thus returns the ambient free module of M (or
unit ideal) if M is pure dimensional. For a very brief description of the
method used, see topComponents.

As an example we remove the lowest dimensional component of an ideal I:

+-----------------------------------------------------------------------------+
|i1 : R = ZZ/32003[a..d];                                                     |
+-----------------------------------------------------------------------------+
|i2 : I = intersect(ideal(a*b+a^2,b^2), ideal(a^2,b^2,c^2), ideal(b^3,c^3,d^3 |
|                                                                             |
|             3   2 3   2 3   2 3        3   2   3   3 3   2 2 3        2 3   |
|o2 = ideal (b , b d , b c , a c  + a*b*c , a b*d , a d , a c d  + a*b*c d )  |
|                                                                             |
|o2 : Ideal of R                                                              |
|-----------------------------------------------------------------------------|
|))                                                                           |
+-----------------------------------------------------------------------------+
|i3 : removeLowestDimension I                                                 |
|                                                                             |
|             2   2                                                           |
|o3 = ideal (b , a  + a*b)                                                    |
|                                                                             |
|o3 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+

See also
========

  * topComponents -- compute top dimensional component of
    an ideal or module
  * saturate (Saturation) -- saturation of ideal or submodule
  * Ideal _colon_ Ideal (Saturation), --
    ideal or submodule quotient
  * radical (MinimalPrimes) -- the radical of an ideal
  * minimalPrimes (MinimalPrimes) -- minimal primes of an
    ideal

Ways to use removeLowestDimension:
==================================

  * "removeLowestDimension(Ideal)"
  * "removeLowestDimension(Module)"

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

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

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

The source of this document is in PrimaryDecomposition/doc.m2:771:0.

strategies for computing primary decomposition
**********************************************

Primary Decomposition of Modules
================================

In this case, the only available strategy is similar to the
Eisenbud-Huneke-Vasconcelos strategy and is implemented by Justin Chen.
Optionally, it is possible to specify the strategy for finding the embedded
components by passing

Strategy => Hybrid{strategy for getEmbeddedComponents}

where the strategy is one of "Hom", "Sat", or "Res". See
primaryDecomposition(Module), for more
information.

Primary Decomposition of Ideals
===============================

In this case, the strategy option value should be one of the following:

  * Monomial -- uses Alexander duality of a monomial ideal
  * Binomial -- finds a cellular resolution of a binomial ideal (see
    binomialPrimaryDecomposition (Binomials))
  * Hybrid -- uses parts of the above two algorithms
  * ShimoyamaYokoyama -- uses the algorithm of Shimoyama-Yokoyama
  * EisenbudHunekeVasconcelos -- uses the algorithm of
    Eisenbud-Huneke-Vasconcelos
  * GTZ -- uses the algorithm of Gianni-Trager-Zacharias (NOT YET IMPLEMENTED)

The strategies are implemented as hooks (Macaulay2Doc),
meaning that each strategy is attempted in the reverse order in which it was
added until one is successful.

+-----------------------------------------------------------------------------+
|i1 : hooks(primaryDecomposition, Ideal)                                      |
|                                                                             |
|o1 = {0 => (primaryDecomposition, Ideal, Strategy =>                         |
|     {1 => (primaryDecomposition, Ideal, Strategy =>                         |
|     {2 => (primaryDecomposition, Ideal, Strategy =>                         |
|     {3 => (primaryDecomposition, Ideal, Strategy =>                         |
|     {4 => (primaryDecomposition, Ideal, Strategy =>                         |
|                                                                             |
|o1 : NumberedVerticalList                                                    |
|-----------------------------------------------------------------------------|
|Comodule)                 }                                                  |
|EisenbudHunekeVasconcelos)}                                                  |
|ShimoyamaYokoyama)        }                                                  |
|Hybrid)                   }                                                  |
|Monomial)                 }                                                  |
+-----------------------------------------------------------------------------+

Strategy => Monomial
====================

This strategy only works for monomial ideals, and is automatically used for
such ideals. See the chapter on "Monomial Ideals" in the Macaulay2 book.

+-----------------------------------------------------------------------------+
|i2 : Q = QQ[a..d]                                                            |
|                                                                             |
|o2 = Q                                                                       |
|                                                                             |
|o2 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i3 : I = ideal(a^2*b,a*c^2,b*d,c*d^2);                                       |
|                                                                             |
|o3 : Ideal of Q                                                              |
+-----------------------------------------------------------------------------+
|i4 : primaryDecomposition(I, Strategy => Monomial)                           |
|                                                                             |
|                                                2              2   2         |
|o4 = {ideal (d, a), ideal (c, b), ideal (b, a, d ), ideal (d, c , a ), ideal |
|     ------------------------------------------------------------------------|
|          2   2                                                              |
|     (b, d , c )}                                                            |
|                                                                             |
|o4 : List                                                                    |
+-----------------------------------------------------------------------------+

Strategy => EisenbudHunekeVasconcelos
=====================================

See Direct methods for primary decomposition by Eisenbud, Huneke, and
Vasconcelos, Invent. Math. 110, 207-235 (1992).

+-----------------------------------------------------------------------------+
|i5 : primaryDecomposition(I, Strategy => EisenbudHunekeVasconcelos)          |
|                                                                             |
|                                                2              2   2         |
|o5 = {ideal (d, a), ideal (c, b), ideal (b, a, d ), ideal (d, c , a ), ideal |
|     ------------------------------------------------------------------------|
|          2   2                                                              |
|     (b, d , c )}                                                            |
|                                                                             |
|o5 : List                                                                    |
+-----------------------------------------------------------------------------+

Strategy => ShimoyamaYokoyama
=============================

This strategy is the default for non-monomial ideals. See Localization and
Primary Decomposition of Polynomial ideals by Shimoyama and Yokoyama, J. Symb.
Comp. 22, 247-277 (1996).

+-----------------------------------------------------------------------------+
|i6 : primaryDecomposition(I, Strategy => ShimoyamaYokoyama)                  |
|                                                                             |
|                                                2              2   2         |
|o6 = {ideal (d, a), ideal (c, b), ideal (b, a, d ), ideal (d, c , a ), ideal |
|     ------------------------------------------------------------------------|
|          2   2                                                              |
|     (b, d , c )}                                                            |
|                                                                             |
|o6 : List                                                                    |
+-----------------------------------------------------------------------------+

Strategy => Hybrid{associated primes strategy, localize strategy}
=================================================================

Uses a hybrid of the Eisenbud-Huneke-Vasconcelos and Shimoyama-Yokoyama
strategies. To use this strategy, the field Strategy should be a list of two
integers, indicating the strategy to use for finding associated primes and
localizing, respectively.

Warning: Setting the second parameter to 1 works only if the ideal is
homogeneous and equidimensional.

+------------------------------------------------------+
|i7 : Q = QQ[x,y];                                     |
+------------------------------------------------------+
|i8 : I = intersect(ideal(x^2), ideal(y^2))            |
|                                                      |
|            2 2                                       |
|o8 = ideal(x y )                                      |
|                                                      |
|o8 : Ideal of Q                                       |
+------------------------------------------------------+
|i9 : primaryDecomposition(I, Strategy => Hybrid{1,1}) |
|                                                      |
|             2         2                              |
|o9 = {ideal x , ideal y }                             |
|                                                      |
|o9 : List                                             |
+------------------------------------------------------+
|i10 : primaryDecomposition(I, Strategy => Hybrid{1,2})|
|                                                      |
|              2         2                             |
|o10 = {ideal x , ideal y }                            |
|                                                      |
|o10 : List                                            |
+------------------------------------------------------+
|i11 : primaryDecomposition(I, Strategy => Hybrid{2,1})|
|                                                      |
|              2         2                             |
|o11 = {ideal x , ideal y }                            |
|                                                      |
|o11 : List                                            |
+------------------------------------------------------+
|i12 : primaryDecomposition(I, Strategy => Hybrid{2,2})|
|                                                      |
|              2         2                             |
|o12 = {ideal x , ideal y }                            |
|                                                      |
|o12 : List                                            |
+------------------------------------------------------+
-------------------------------------------------------------------------------

The source of this document is in PrimaryDecomposition/doc.m2:771:0.

topComponents -- compute top dimensional component of an ideal or module
************************************************************************

  * Usage:
        topComponents M
  * Inputs:
      * M, an ideal (Macaulay2Doc), or a module (Macaulay2Doc),
  * Outputs:
      * an ideal (Macaulay2Doc), or a module (Macaulay2Doc),
        the intersection of the primary components of
        the input with the greatest Krull dimension

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

The method used is that of Eisenbud-Huneke-Vasconcelos, in their 1993
Inventiones Mathematicae paper.

+---------------------------------------------------------------------------+
|i1 : R = ZZ/32003[a..c];                                                   |
+---------------------------------------------------------------------------+
|i2 : I = intersect(ideal(a,b), ideal(b,c), ideal(c,a), ideal(a^2,b^3,c^4));|
|                                                                           |
|o2 : Ideal of R                                                            |
+---------------------------------------------------------------------------+
|i3 : topComponents I                                                       |
|                                                                           |
|o3 = ideal (b*c, a*c, a*b)                                                 |
|                                                                           |
|o3 : Ideal of R                                                            |
+---------------------------------------------------------------------------+

If $M$ is a module in a polynomial ring $R$, then the implementations of
topComponents and removeLowestDimension, are based
on the following observations:

  * $codim Ext^d(M,R) \ge d$ for all $d$
  * 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$
  * If $codim Ext^d(M,R) = d$, then there really is an associated prime of
    codimension $d$.
  * If $M$ is $R/I$, then $topComponents(I) = ann Ext^c(R/I,R)$, where $c =
    codim I$

See also
========

  * removeLowestDimension -- remove components of
    lowest dimension
  * saturate (Saturation) -- saturation of ideal or submodule
  * Ideal _colon_ Ideal (Saturation), --
    ideal or submodule quotient
  * radical (MinimalPrimes) -- the radical of an ideal

Ways to use topComponents:
==========================

  * "topComponents(Ideal)"
  * "topComponents(Module)"
  * "topComponents(Module,ZZ)"

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

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

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

The source of this document is in PrimaryDecomposition/doc.m2:771:0.