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

Saturation -- ideal and submodule quotient, saturation, and annihilator routines
********************************************************************************

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

This package provides various basic commutative algebra routines for working
with ideals and modules.

Main functionalities

  * ideal quotients and saturation
  * module quotients, saturation, and annihilator

Authors
=======

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

Version
=======

This documentation describes version 0.3 of Saturation.

Citation
========

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

+-----------------------------------------------------------------------------+
|@misc{SaturationSource,                                                      |
|  title = {{Saturation: quotient, saturation, and annihilator routines for   |
|  author = {Justin Chen and Mahrud Sayrafi and Mike Stillman},               |
|  howpublished = {A \emph{Macaulay2} package available at                    |
|    \url{https://github.com/Macaulay2/M2/tree/master/M2/Macaulay2/packages   |
|}                                                                            |
|-----------------------------------------------------------------------------|
| ideals and modules. Version~0.3}},                                          |
|                                                                             |
|                                                                             |
|}}                                                                           |
+-----------------------------------------------------------------------------+

Exports
=======

  * Functions and commands
      * annihilator -- the annihilator ideal
      * isSupportedInZeroLocus -- whether
        support of a module is contained in the zero locus of the (irrelevant)
        ideal
      * saturate -- saturation of ideal or submodule
  * Methods
      * "annihilator(Ideal)" -- see annihilator, -- the
        annihilator ideal
      * "annihilator(Module)" -- see annihilator, -- the
        annihilator ideal
      * "annihilator(RingElement)" -- see annihilator, --
        the annihilator ideal
      * "isSupportedInZeroLocus(Ideal,GradedModule)" -- see
        isSupportedInZeroLocus, -- whether support of a
        module is contained in the zero locus of the (irrelevant) ideal
      * "isSupportedInZeroLocus(Ideal,Ideal)" -- see
        isSupportedInZeroLocus, -- whether support of a
        module is contained in the zero locus of the (irrelevant) ideal
      * "isSupportedInZeroLocus(Ideal,Module)" -- see
        isSupportedInZeroLocus, -- whether support of a
        module is contained in the zero locus of the (irrelevant) ideal
      * "Ideal : Ideal" -- see quotient(Module,Module),
        -- ideal or submodule quotient
      * "Ideal : RingElement" -- see quotient(Module,Module),
        -- ideal or submodule quotient
      * "Module : Ideal" -- see quotient(Module,Module),
        -- ideal or submodule quotient
      * "Module : Module" -- see quotient(Module,Module),
        -- ideal or submodule quotient
      * "Module : RingElement" -- see quotient(Module,Module),
        -- ideal or submodule quotient
      * "MonomialIdeal : RingElement" -- see quotient(Module,Module),
        -- ideal or submodule quotient
      * "quotient(Ideal,Ideal)" -- see quotient(Module,Module),
        -- ideal or submodule quotient
      * "quotient(Ideal,RingElement)" -- see quotient(Module,Module),
        -- ideal or submodule quotient
      * "quotient(Module,Ideal)" -- see quotient(Module,Module),
        -- ideal or submodule quotient
      * quotient(Module,Module) -- ideal
        or submodule quotient
      * "quotient(Module,RingElement)" -- see quotient(Module,Module),
        -- ideal or submodule quotient
      * "quotient(MonomialIdeal,RingElement)" -- see
        quotient(Module,Module), -- ideal or
        submodule quotient
      * "saturate(Ideal)" -- see saturate, -- saturation of
        ideal or submodule
      * "saturate(Ideal,Ideal)" -- see saturate, -- saturation
        of ideal or submodule
      * "saturate(Ideal,RingElement)" -- see saturate, --
        saturation of ideal or submodule
      * "saturate(Module)" -- see saturate, -- saturation of
        ideal or submodule
      * "saturate(Module,Ideal)" -- see saturate, -- saturation
        of ideal or submodule
      * "saturate(Module,RingElement)" -- see saturate, --
        saturation of ideal or submodule
      * "saturate(MonomialIdeal,RingElement)" -- see saturate,
        -- saturation of ideal or submodule
      * "saturate(Vector)" -- see saturate, -- saturation of
        ideal or submodule
      * "saturate(Vector,Ideal)" -- see saturate, -- saturation
        of ideal or submodule
      * "saturate(Vector,RingElement)" -- see saturate, --
        saturation of ideal or submodule

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

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

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

The source of this document is in Saturation/doc.m2:100:0.

quotient(Module,Module) -- ideal or submodule quotient
******************************************************

  * Function: quotient (Macaulay2Doc),
  * Usage:
        quotient(I, J)
        I:J
  * Inputs:
      * I, an ideal (Macaulay2Doc), a monomial ideal (Macaulay2Doc),
        or a module (Macaulay2Doc),
      * J, an ideal (Macaulay2Doc), a monomial ideal (Macaulay2Doc),
        a module (Macaulay2Doc), or
        a ring element (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * Strategy, => a
        thing (Macaulay2Doc), default value null, specifies the
        algorithm
      * MinimalGenerators => a Boolean value (Macaulay2Doc),
        default value true, indicates whether the output should be
        trimmed (Macaulay2Doc),
      * BasisElementLimit => an integer (Macaulay2Doc), default value
        infinity, passed onto gb(...,BasisElementLimit=>...) (Macaulay2Doc),;
      * DegreeLimit => a list (Macaulay2Doc), default value {},
        passed onto gb(...,DegreeLimit=>...) (Macaulay2Doc),;
      * PairLimit => an integer (Macaulay2Doc), default value
        infinity, passed onto gb(...,PairLimit=>...) (Macaulay2Doc),;
  * Outputs:
      * an ideal (Macaulay2Doc), or a module (Macaulay2Doc),
        the quotient $I:J = \{f | f J\subset I\}$

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

If I and J are both monomial ideals (Macaulay2Doc), then
the result will be as well. If I and J are both ideals or submodules of the
same module, then the result will be an ideal, otherwise if J is an ideal or
ring element, then the result is a submodule containing I.

The arguments should be ideals in the same ring, or submodules of the same
module. If the second input J is a ring element f, then the principal ideal
generated by f is used. The infix colon operator _colon_ (Macaulay2Doc),
may be used as an abbreviation, if no options need to be
supplied.

For ideals, the quotient is the set of ring elements $r$ such that $rJ$ is
contained in $I$. If $I$ is a submodule of a module $M$, and $J$ is an ideal,
the quotient is the set of elements $m \in M$ such that $Jm$ is contained in
$I$. Finally, if $I$ and $J$ are submodules of the same module $M$, then the
result is the set of ring elements $r$ such that $rJ$ is contained in $I$.

+--------------------------------------------------------------+
|i1 : R = ZZ/32003[a..d];                                      |
+--------------------------------------------------------------+
|i2 : J = monomialCurveIdeal(R,{1,4,7})                        |
|                                                              |
|             2         3     3    4    3                      |
|o2 = ideal (c  - b*d, b c - a d, b  - a c)                    |
|                                                              |
|o2 : Ideal of R                                               |
+--------------------------------------------------------------+
|i3 : I = ideal(J_1-a^2*J_0,J_2-d*c*J_0)                       |
|                                                              |
|             3     2 2    3     2      4    3     3         2 |
|o3 = ideal (b c - a c  - a d + a b*d, b  - a c - c d + b*c*d )|
|                                                              |
|o3 : Ideal of R                                               |
+--------------------------------------------------------------+
|i4 : I : J                                                    |
|                                                              |
|             3    2       2   3    2     2                    |
|o4 = ideal (b  - a c + c*d , a  - a b + c d)                  |
|                                                              |
|o4 : Ideal of R                                               |
+--------------------------------------------------------------+

When needed, Gröbner bases will be computed, and if the computation succeeds
the result is cached inside the first argument. Partial computations are not
yet cached, but this may change in a future version.

+----------------------------------------------------+
|i5 : R = ZZ[a,b,c];                                 |
+----------------------------------------------------+
|i6 : F = a^3-b^2*c-11*c^2                           |
|                                                    |
|      3    2       2                                |
|o6 = a  - b c - 11c                                 |
|                                                    |
|o6 : R                                              |
+----------------------------------------------------+
|i7 : I = ideal(F,diff(a,F),diff(b,F),diff(c,F))     |
|                                                    |
|             3    2       2    2            2       |
|o7 = ideal (a  - b c - 11c , 3a , -2b*c, - b  - 22c)|
|                                                    |
|o7 : Ideal of R                                     |
+----------------------------------------------------+
|i8 : I : (ideal(a,b,c))^3                           |
|                                                    |
|                                2        2          |
|o8 = ideal (11c, 3b, 33a, b*c, b , a*b, a )         |
|                                                    |
|o8 : Ideal of R                                     |
+----------------------------------------------------+

If the arguments are submodules of the same module, the annihilator of J/I (or
(J+I)/I) is returned.

+----------------------------------------+
|i9 : S = QQ[x,y,z];                     |
+----------------------------------------+
|i10 : J = image vars S                  |
|                                        |
|o10 = image | x y z |                   |
|                                        |
|                              1         |
|o10 : S-module, submodule of S          |
+----------------------------------------+
|i11 : I = image symmetricPower(2,vars S)|
|                                        |
|o11 = image | x2 xy xz y2 yz z2 |       |
|                                        |
|                              1         |
|o11 : S-module, submodule of S          |
+----------------------------------------+
|i12 : (I++I) : (J++J)                   |
|                                        |
|o12 = ideal (z, y, x)                   |
|                                        |
|o12 : Ideal of S                        |
+----------------------------------------+
|i13 : (I++I) : x+y+z                    |
|                                        |
|o13 = image | z y x 0 0 0 |             |
|            | 0 0 0 z y x |             |
|                                        |
|                              2         |
|o13 : S-module, submodule of S          |
+----------------------------------------+
|i14 : quotient(I,J)                     |
|                                        |
|o14 = ideal (z, y, x)                   |
|                                        |
|o14 : Ideal of S                        |
+----------------------------------------+
|i15 : quotient(gens I, gens J)          |
|                                        |
|o15 = {1} | x y z 0 0 0 |               |
|      {1} | 0 0 0 y z 0 |               |
|      {1} | 0 0 0 0 0 z |               |
|                                        |
|              3      6                  |
|o15 : Matrix S  <-- S                   |
+----------------------------------------+

Ideal quotients and saturations are useful for manipulating components of
ideals.

+-----------------------------------------------------------------------------+
|i16 : I = ideal(x^2-y^2, y^3)                                                |
|                                                                             |
|              2    2   3                                                     |
|o16 = ideal (x  - y , y )                                                    |
|                                                                             |
|o16 : Ideal of S                                                             |
+-----------------------------------------------------------------------------+
|i17 : J = ideal((x+y+z)^3, z^2)                                              |
|                                                                             |
|              3     2        2    3     2               2        2       2   |
|o17 = ideal (x  + 3x y + 3x*y  + y  + 3x z + 6x*y*z + 3y z + 3x*z  + 3y*z  + |
|      -----------------------------------------------------------------------|
|       3   2                                                                 |
|      z , z )                                                                |
|                                                                             |
|o17 : Ideal of S                                                             |
+-----------------------------------------------------------------------------+
|i18 : L = intersect(I,J)                                                     |
|                                                                             |
|              2 2    2 2    3      2 2       3     4     3      2          2 |
|o18 = ideal (x z  - y z , 2x y + 6x y  + 6x*y  + 2y  - 3x z - 3x y*z + 3x*y z|
|      -----------------------------------------------------------------------|
|          3    4     2 2       3     4     3      2          2      3    3 2 |
|      + 3y z, x  - 6x y  - 8x*y  - 3y  + 6x z + 6x y*z - 6x*y z - 6y z, y z )|
|                                                                             |
|o18 : Ideal of S                                                             |
+-----------------------------------------------------------------------------+
|i19 : L : z^2                                                                |
|                                                                             |
|              2    2   3                                                     |
|o19 = ideal (x  - y , y )                                                    |
|                                                                             |
|o19 : Ideal of S                                                             |
+-----------------------------------------------------------------------------+
|i20 : L : I == J                                                             |
|                                                                             |
|o20 = true                                                                   |
+-----------------------------------------------------------------------------+

See also
========

  * annihilator -- the annihilator ideal
  * saturate -- saturation of ideal or submodule
  * _colon_ (Macaulay2Doc) -- a binary operator, uses include
    repetition; ideal quotients

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

  * "quotient(Ideal,Ideal)"
  * "quotient(Ideal,RingElement)"
  * "quotient(Module,Ideal)"
  * quotient(Module,Module) -- ideal or
    submodule quotient
  * "quotient(Module,RingElement)"
  * "quotient(MonomialIdeal,RingElement)"
-------------------------------------------------------------------------------

The source of this document is in Saturation/quotient-doc.m2:147:0.

annihilator -- the annihilator ideal
************************************

  * Usage:
        ann M
        annihilator M
  * Inputs:
      * M, an ideal (Macaulay2Doc), a module (Macaulay2Doc),
        or a ring element (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * Strategy => a symbol (Macaulay2Doc), default value null,
        either Quotient or Intersection
  * Outputs:
      * an ideal (Macaulay2Doc), the annihilator ideal
        $\mathrm{ann}(M) = \{ f \in R | fM = 0 \}$ where $R$ is the ring of $M$

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

You may use ann as a synonym for annihilator.

As an example, we compute the annihilator of the canonical module of the
rational quartic curve.

+-------------------------------------------------------+
|i1 : R = QQ[a..d];                                     |
+-------------------------------------------------------+
|i2 : J = 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 : M = Ext^2(R^1/J, R)                               |
|                                                       |
|o3 = cokernel {-3} | c  a  0 b 0 |                     |
|              {-3} | -d -b c 0 a |                     |
|              {-3} | 0  0  d c b |                     |
|                                                       |
|                            3                          |
|o3 : R-module, quotient of R                           |
+-------------------------------------------------------+
|i4 : annihilator M                                     |
|                                                       |
|                        3      2     2    2    3    2  |
|o4 = ideal (b*c - a*d, c  - b*d , a*c  - b d, b  - a c)|
|                                                       |
|o4 : Ideal of R                                        |
+-------------------------------------------------------+

For another example, we compute the annihilator of an element in a quotient
ring.

+--------------------------+
|i5 : A = R/(a*b, a*c, a*d)|
|                          |
|o5 = A                    |
|                          |
|o5 : QuotientRing         |
+--------------------------+
|i6 : ann a                |
|                          |
|o6 = ideal (d, c, b)      |
|                          |
|o6 : Ideal of A           |
+--------------------------+

Currently two algorithms to compute annihilators are implemented. The default
is to compute the annihilator of each generator of the module M and to
intersect these two by two. Each annihilator is done using a submodule
quotient. The other algorithm computes the annihilator in one large computation
and is used if Strategy => Quotient is specified.

+-------------------------------------------------------+
|i7 : annihilator(M, Strategy => Quotient)              |
|                                                       |
|                        3      2     2    2    3    2  |
|o7 = ideal (b*c - a*d, c  - b*d , a*c  - b d, b  - a c)|
|                                                       |
|o7 : Ideal of R                                        |
+-------------------------------------------------------+

See also
========

  * quotient(Module,Module) (missing documentation)
  * monomialCurveIdeal (Macaulay2Doc) -- make the
    ideal of a monomial curve
  * Ext (Macaulay2Doc) -- compute an Ext module

Ways to use annihilator:
========================

  * "annihilator(Ideal)"
  * "annihilator(Module)"
  * "annihilator(RingElement)"

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

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

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

The source of this document is in Saturation/annihilator-doc.m2:50:0.

saturate -- saturation of ideal or submodule
********************************************

  * Usage:
        saturate(I, J)
        saturate I
  * Inputs:
      * I, an ideal (Macaulay2Doc), a monomial ideal (Macaulay2Doc),
        or a module (Macaulay2Doc),
      * J, an ideal (Macaulay2Doc), a monomial ideal (Macaulay2Doc),
        a module (Macaulay2Doc), or
        a ring element (Macaulay2Doc), if not present, then
        the ideal generated by the variables of the ring is used
  * Optional inputs (Macaulay2Doc),:
      * Strategy, => a
        thing (Macaulay2Doc), default value null, specifies the
        algorithm
      * MinimalGenerators => a Boolean value (Macaulay2Doc),
        default value true, indicates whether the output should be
        trimmed (Macaulay2Doc),
      * BasisElementLimit => an integer (Macaulay2Doc), default value
        infinity, passed onto gb(...,BasisElementLimit=>...) (Macaulay2Doc),;
      * DegreeLimit => a list (Macaulay2Doc), default value {},
        passed onto gb(...,DegreeLimit=>...) (Macaulay2Doc),;
      * PairLimit => an integer (Macaulay2Doc), default value
        infinity, passed onto gb(...,PairLimit=>...) (Macaulay2Doc),;
  * Outputs:
      * an ideal (Macaulay2Doc), or a module (Macaulay2Doc),
        the saturation $I:J^\infty = \{f | f J^N\subset
        I \text{ for some } N>0\}$

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

If $I$ is either an ideal or a submodule of a module $M$, the saturation $I :
J^\infty$ is defined to be the set of elements $f$ in the ring or $M$ such that
$f J^N$ is contained in $I$, for some $N$ large enough.

For example, one way to homogenize an ideal is to homogenize the generators and
then saturate with respect to the homogenizing variable.

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

We can use this command to remove graded submodules of finite length.

+----------------------------------------------------------+
|i5 : m = ideal vars R                                     |
|                                                          |
|o5 = ideal (a, b, c, d)                                   |
|                                                          |
|o5 : Ideal of R                                           |
+----------------------------------------------------------+
|i6 : M = R^1 / (a * m^2)                                  |
|                                                          |
|o6 = cokernel | a3 a2b a2c a2d ab2 abc abd ac2 acd ad2 |  |
|                                                          |
|                            1                             |
|o6 : R-module, quotient of R                              |
+----------------------------------------------------------+
|i7 : M / saturate 0_M                                     |
|                                                          |
|o7 = cokernel | a a3 a2b a2c a2d ab2 abc abd ac2 acd ad2 ||
|                                                          |
|                            1                             |
|o7 : R-module, quotient of R                              |
+----------------------------------------------------------+

If $I$ and $J$ are both monomial ideals, then a faster algorithm is used.
Otherwise, when needed, Gröbner bases will be computed, and if the computation
succeeds the result is cached inside the first argument. Partial computations
are not yet cached, but this may change in a future version.

See also
========

  * quotient(Ideal,Ideal) (missing documentation)
  * annihilator -- the annihilator ideal
  * MinimalPrimes -- minimal primes and radical
    routines for ideals
  * PrimaryDecomposition -- primary
    decomposition and associated primes routines for ideals and modules

Ways to use saturate:
=====================

  * "saturate(Ideal)"
  * "saturate(Ideal,Ideal)"
  * "saturate(Ideal,RingElement)"
  * "saturate(Module)"
  * "saturate(Module,Ideal)"
  * "saturate(Module,RingElement)"
  * "saturate(MonomialIdeal,RingElement)"
  * "saturate(Vector)"
  * "saturate(Vector,Ideal)"
  * "saturate(Vector,RingElement)"

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

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

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

The source of this document is in Saturation/saturate-doc.m2:139:0.

isSupportedInZeroLocus -- whether support of a module is contained in the zero locus of the (irrelevant) ideal
**************************************************************************************************************

  * Usage:
        isSupportedInZeroLocus_B M
  * Inputs:
      * B, an ideal (Macaulay2Doc),
      * M, an ideal (Macaulay2Doc), a module (Macaulay2Doc),
        or a graded module (OldChainComplexes),
  * Outputs:
      * a Boolean value (Macaulay2Doc), true if $M$ (or $R^1/I$,
        if an ideal of $R$ is given) is supported only on the zero locus of
        $B$; that is, whether $\mathrm{supp}(M) \subset \mathrm{V}(B)$

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

Given an module $M$ and an ideal $B$, isSupportedInZeroLocus checks whether
$\mathrm{ann}(M):B^\infty=R$. If it is, isSupportedInZeroLocus returns true
otherwise it returns false. If the second argument is an ideal, $M = R^1/I$ is
taken as the module.

+---------------------------------------------------------+
|i1 : S = ZZ/32003[x_0..x_4, Degrees=>{2:{1,0}, 3:{0,1}}];|
+---------------------------------------------------------+
|i2 : irr = intersect(ideal(x_0,x_1), ideal(x_2,x_3,x_4));|
|                                                         |
|o2 : Ideal of S                                          |
+---------------------------------------------------------+
|i3 : M = S^1/(irr^2);                                    |
+---------------------------------------------------------+
|i4 : isSupportedInZeroLocus_irr M                        |
|                                                         |
|o4 = true                                                |
+---------------------------------------------------------+

This is done without computing saturation of $M$. Instead, we check whether for
each generator of $B$ some power of it annihilates the module $M$.

Ways to use isSupportedInZeroLocus:
===================================

  * "isSupportedInZeroLocus(Ideal,GradedModule)"
  * "isSupportedInZeroLocus(Ideal,Ideal)"
  * "isSupportedInZeroLocus(Ideal,Module)"

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

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

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

The source of this document is in Saturation/saturate-doc.m2:139:0.

ideal quotients and saturation
******************************

Ideal Quotients
===============

The quotient, of two ideals $I, J\subset
R$ is ideal $I:J$ of elements $f\in R$ such that $f J \subset I$.

+--------------------------------------------+
|i1 : R = QQ[a..d];                          |
+--------------------------------------------+
|i2 : I = ideal(a^2*b-c^2, a*b^2-d^3, c^5-d);|
|                                            |
|o2 : Ideal of R                             |
+--------------------------------------------+
|i3 : J = ideal(a^2,b^2,c^2,d^2);            |
|                                            |
|o3 : Ideal of R                             |
+--------------------------------------------+
|i4 : I:J                                    |
|                                            |
|               2    3   2     2   5         |
|o4 = ideal (a*b  - d , a b - c , c  - d)    |
|                                            |
|o4 : Ideal of R                             |
+--------------------------------------------+
|i5 : P = quotient(I,J)                      |
|                                            |
|               2    3   2     2   5         |
|o5 = ideal (a*b  - d , a b - c , c  - d)    |
|                                            |
|o5 : Ideal of R                             |
+--------------------------------------------+

The functions _colon_ (Macaulay2Doc), and quotient (Macaulay2Doc),
perform the same basic operation, however quotient
takes options.

Saturation of Ideals
====================

The saturation, of an ideal $I\subset R$ with respect to
another ideal $J\subset R$ is the ideal $I:J^\infty$ of elements $f\in R$ such
that $f J^N\subset I$ for some $N$ large enough. If the ideal $J$ is not given,
the ideal generated by the variables of the ring $R$ is used.

For example, one way to homogenize an ideal is to homogenize the generators and
then saturate with respect to the homogenizing variable.

+-------------------------------------------------------+
|i6 : R = ZZ/32003[a..d];                               |
+-------------------------------------------------------+
|i7 : I = ideal(a^3-b, a^4-c)                           |
|                                                       |
|             3       4                                 |
|o7 = ideal (a  - b, a  - c)                            |
|                                                       |
|o7 : Ideal of R                                        |
+-------------------------------------------------------+
|i8 : Ih = homogenize(I, d)                             |
|                                                       |
|                        2     2    3      2   3      2 |
|o8 = ideal (a*b - c*d, a c - b d, b  - a*c , a  - b*d )|
|                                                       |
|o8 : Ideal of R                                        |
+-------------------------------------------------------+
|i9 : saturate(Ih, d)                                   |
|                                                       |
|                        2     2    3      2   3      2 |
|o9 = ideal (a*b - c*d, a c - b d, b  - a*c , a  - b*d )|
|                                                       |
|o9 : Ideal of R                                        |
+-------------------------------------------------------+
-------------------------------------------------------------------------------

The source of this document is in Saturation/doc.m2:100:0.

module quotients, saturation, and annihilator
*********************************************

Module Quotients
================

There are two notions associated to the colon construction for modules.

Similar to the case of ideals, the quotient,
of two $R$-modules $M, N$ contained in the same
ambient (Macaulay2Doc), module is an ideal $M:N$ of elements
$f\in R$ such that $f N \subset M$. This is equivalent to the
annihilator, of the quotient module $(M+N)/M$.

The quotient, of an $R$-module $M\subset
F$ with respect to an ideal $J\subset R$ is the module $M:_F J$ of elements
$f\in F$ such that $J f\subset M$.

Saturation of Modules
=====================

The saturation, of an $R$-module $M\subset F$ with respect to
an ideal $J\subset R$ is an $R$-module $M:_F J^\infty$ of elements $f\in F$
such that $J^N f\subset M$ for some $N$ large enough. If the ideal $J$ is not
given, the ideal generated by the variables of the ring $R$ is used.

If $M=M:_F J^\infty$ (or, equivalently, $M=M:_F J$), we say that $M$ is
saturated with respect to $J$. We can use this command to remove graded
submodules of finite length.

+----------------------------------------------------------+
|i1 : R = ZZ/32003[a..d];                                  |
+----------------------------------------------------------+
|i2 : m = ideal vars R                                     |
|                                                          |
|o2 = ideal (a, b, c, d)                                   |
|                                                          |
|o2 : Ideal of R                                           |
+----------------------------------------------------------+
|i3 : M = R^1 / (a * m^2)                                  |
|                                                          |
|o3 = cokernel | a3 a2b a2c a2d ab2 abc abd ac2 acd ad2 |  |
|                                                          |
|                            1                             |
|o3 : R-module, quotient of R                              |
+----------------------------------------------------------+
|i4 : M / saturate 0_M                                     |
|                                                          |
|o4 = cokernel | a a3 a2b a2c a2d ab2 abc abd ac2 acd ad2 ||
|                                                          |
|                            1                             |
|o4 : R-module, quotient of R                              |
+----------------------------------------------------------+

Module Annihilators
===================

The annihilator, of an $R$-module $M$ is the ideal
$\mathrm{ann}(M) = \{ f \in R | f M = 0 \}$.

+---------------------------------------------------------+
|i5 : R = QQ[a..i];                                       |
+---------------------------------------------------------+
|i6 : M = cokernel genericMatrix(R,a,3,3)                 |
|                                                         |
|o6 = cokernel | a d g |                                  |
|              | b e h |                                  |
|              | c f i |                                  |
|                                                         |
|                            3                            |
|o6 : R-module, quotient of R                             |
+---------------------------------------------------------+
|i7 : annihilator M                                       |
|                                                         |
|o7 = ideal(c*e*g - b*f*g - c*d*h + a*f*h + b*d*i - a*e*i)|
|                                                         |
|o7 : Ideal of R                                          |
+---------------------------------------------------------+

You may also use the abbreviation ann:

+---------------------------------------------+
|i8 : ann (M/(a*M))                           |
|                                             |
|o8 = ideal (a, c*e*g - b*f*g - c*d*h + b*d*i)|
|                                             |
|o8 : Ideal of R                              |
+---------------------------------------------+
-------------------------------------------------------------------------------

The source of this document is in Saturation/doc.m2:100:0.

quotient(...,Strategy=>...)
***************************

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

Suppose that I is the image of a free module FI in a quotient module G, and J
is the image of the free module FJ in G.

Available strategies for the computation can be listed using the function
hooks (Macaulay2Doc),:

+----------------------------------------------------------+
|i1 : hooks methods(quotient, Ideal, Ideal)                |
|                                                          |
|o1 = {0 => (quotient, Ideal, Ideal, Strategy => Quotient)}|
|     {1 => (quotient, Ideal, Ideal, Strategy => Iterate) }|
|     {2 => (quotient, Ideal, Ideal, Strategy => Monomial)}|
|                                                          |
|o1 : NumberedVerticalList                                 |
+----------------------------------------------------------+

The strategy Quotient computes the first components of the syzygies of the map
$R\oplus(FJ^\vee\otimes FI) \to FJ^\vee \otimes G$. The Macaulay2 code for each
strategy can be viewed using the function code (Macaulay2Doc),:

+----------------------------------------------------------------------+
|i2 : code(quotient, Ideal, Ideal, Strategy => Quotient)               |
|                                                                      |
|o2 = -- code for strategy: quotient(Ideal,Ideal,Strategy => Quotient) |
|     ${prefix}/share/Macaulay2/Saturation.m2:226:16-238:              |
|     25: --source code:                                               |
|         Quotient => (opts, I, J) -> (                                |
|             R := ring I;                                             |
|             -- FIXME: this line computes a gb for I!!!               |
|             mR := transpose generators J ** (R / I);                 |
|             -- if J is a single element, this is the same as         |
|             -- computing syz gb(matrix{{f}} | generators I, ...)     |
|             g := syz gb(mR, opts,                                    |
|                 Strategy   => LongPolynomial,                        |
|                 Syzygies   => true,                                  |
|                 SyzygyRows => 1);                                    |
|             -- The degrees of g are not correct, so we fix that here:|
|             -- g = map(R^1, null, g);                                |
|             lift(ideal g, R)),                                       |
+----------------------------------------------------------------------+

If Strategy => Iterate then quotient first computes the quotient I1 by the
first generator of J. It then checks whether this quotient already annihilates
the second generator of J mod I. If so, it goes on to the third generator; else
it intersects I1 with the quotient of I by the second generator to produce a
new I1. It then iterates this process, working through the generators one at a
time.

To use Strategy=>Linear the argument J must be a principal ideal, generated by
a linear form. A change of variables is made so that this linear form becomes
the last variable. Then a reverse lex Gröbner basis is used, and the quotient
of the initial ideal by the last variable is computed combinatorially. This set
of monomial is then lifted back to a set of generators for the quotient.

The following examples show timings for the different strategies. Strategy =>
Iterate is sometimes faster for ideals with a small number of generators:

+-----------------------------------------------------+
|i3 : n = 6                                           |
|                                                     |
|o3 = 6                                               |
+-----------------------------------------------------+
|i4 : S = ZZ/101[vars(0..n-1)];                       |
+-----------------------------------------------------+
|i5 : I = monomialCurveIdeal(S, 1..n-1);              |
|                                                     |
|o5 : Ideal of S                                      |
+-----------------------------------------------------+
|i6 : J = ideal(map(S^1, S^n, (p, q) -> S_q^5));      |
|                                                     |
|o6 : Ideal of S                                      |
+-----------------------------------------------------+
|i7 : time quotient(I^3, J^2, Strategy => Iterate);   |
| -- used 0.474091s (cpu); 0.431317s (thread); 0s (gc)|
|                                                     |
|o7 : Ideal of S                                      |
+-----------------------------------------------------+
|i8 : time quotient(I^3, J^2, Strategy => Quotient);  |
| -- used 0.714791s (cpu); 0.678402s (thread); 0s (gc)|
|                                                     |
|o8 : Ideal of S                                      |
+-----------------------------------------------------+

Strategy => Quotient is faster in other cases:

+-------------------------------------------------------+
|i9 : S = ZZ/101[vars(0..4)];                           |
+-------------------------------------------------------+
|i10 : I = ideal vars S;                                |
|                                                       |
|o10 : Ideal of S                                       |
+-------------------------------------------------------+
|i11 : time quotient(I^5, I^3, Strategy => Iterate);    |
| -- used 0.0309738s (cpu); 0.0313169s (thread); 0s (gc)|
|                                                       |
|o11 : Ideal of S                                       |
+-------------------------------------------------------+
|i12 : time quotient(I^5, I^3, Strategy => Quotient);   |
| -- used 0.0100955s (cpu); 0.0102886s (thread); 0s (gc)|
|                                                       |
|o12 : Ideal of S                                       |
+-------------------------------------------------------+

References
==========

For further information see for example Exercise 15.41 in Eisenbud's
Commutative Algebra with a View Towards Algebraic Geometry.

Functions with optional argument named Strategy:
================================================

  * "addHook(...,Strategy=>...)" -- see addHook (Macaulay2Doc),
    -- add a hook function to an object for later processing
  * "annihilator(...,Strategy=>...)" -- see annihilator, --
    the annihilator ideal
  * "basis(...,Strategy=>...)" -- see basis (Macaulay2Doc), --
    basis or generating set of all or part of a ring, ideal or module
  * "mingens(...,Strategy=>...)" -- see Complement (Macaulay2Doc),
    -- a Strategy option value
  * "trim(...,Strategy=>...)" -- see Complement (Macaulay2Doc),
    -- a Strategy option value
  * "compose(Module,Module,Module,Strategy=>...)" -- see compose (Macaulay2Doc),
    -- composition as a pairing on Hom-modules
  * determinant(...,Strategy=>...) (Macaulay2Doc)
    -- choose
    between Bareiss, Cofactor and Dynamic algorithms
  * "dual(MonomialIdeal,List,Strategy=>...)" -- see
    dual(MonomialIdeal,Strategy=>...) (Macaulay2Doc),
  * "dual(MonomialIdeal,RingElement,Strategy=>...)" -- see
    dual(MonomialIdeal,Strategy=>...) (Macaulay2Doc),
  * dual(MonomialIdeal,Strategy=>...) (Macaulay2Doc)
  * "End(...,Strategy=>...)" -- see End (Macaulay2Doc), -- module of
    endomorphisms
  * exteriorPower(...,Strategy=>...) (Macaulay2Doc)
    -- choose
    between Bareiss, Cofactor and Dynamic algorithms
  * "gb(...,Strategy=>...)" -- see gb (Macaulay2Doc), -- compute a
    Gröbner basis
  * "GF(...,Strategy=>...)" -- see GF (Macaulay2Doc), -- make a finite
    field
  * "groebnerBasis(...,Strategy=>...)" -- see groebnerBasis (Macaulay2Doc),
    -- Gröbner basis, as a matrix
  * "Hom(...,Strategy=>...)" -- see Hom (Macaulay2Doc), -- module of
    homomorphisms
  * "homomorphism'(...,Strategy=>...)" -- see homomorphism' (Macaulay2Doc),
    -- get the element of Hom from a homomorphism
  * "hooks(...,Strategy=>...)" -- see hooks (Macaulay2Doc), -- list
    hooks attached to a key
  * "intersect(Ideal,Ideal,Strategy=>...)" -- see intersect(Ideal,Ideal) (Macaulay2Doc),
    -- compute an intersection of a
    sequence of ideals or modules
  * "intersect(Module,Module,Strategy=>...)" -- see
    intersect(Ideal,Ideal) (Macaulay2Doc), --
    compute an intersection of a sequence of ideals or modules
  * "match(...,Strategy=>...)" -- see match (Macaulay2Doc), --
    regular expression matching
  * minors(...,Strategy=>...) (Macaulay2Doc)
    -- choose
    between Bareiss, Cofactor and Dynamic algorithms
  * "parallelApply(...,Strategy=>...)" -- see parallelApply (Macaulay2Doc),
    -- apply a function to each element in
    parallel
  * "pushForward(...,Strategy=>...)" -- see pushForward(RingMap,Module) (Macaulay2Doc),
    -- compute the pushforward
    of a module along a ring map
  * quotient'(...,Strategy=>...) (missing documentation)
  * quotient(...,Strategy=>...)
  * resolution(...,Strategy=>...) (OldChainComplexes)
  * saturate(...,Strategy=>...)
  * "syz(...,Strategy=>...)" -- see syz(Matrix) (Macaulay2Doc),
    -- compute the syzygy matrix

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

  * Default value: null
  * Function: quotient (Macaulay2Doc), -- quotient or division
  * Option key: Strategy (Macaulay2Doc), -- an optional argument
-------------------------------------------------------------------------------

The source of this document is in Saturation/quotient-doc.m2:147:0.

saturate(...,Strategy=>...)
***************************

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

There are four strategy values:

Iterate
=======

saturate(I,J,Strategy => Iterate) -- indicates that successive ideal or module
quotients should be used.

This value is the default.

Linear
======

saturate(I,J,Strategy => Linear)Strategy => Linear -- indicates that the
reverse lex order should be used to compute the saturation.

This presumes that J is a single, linear polynomial, and that I is homogeneous.

Bayer
=====

saturate(I,f,Strategy => Bayer) -- indicates that the method of Bayer's thesis
should be used.

The method is to compute (I:f) for I and f homogeneous, add a new variable z,
compute a Gröbner basis of (I,f-z) in reverse lex order, divide by z, and
finally replace z by f.

Eliminate
=========

saturate(I,f,Strategy => Eliminate) -- indicates that the saturation (I:f)
should be computed by eliminating fz from (I,f*z-1), where z is a new variable.

Functions with optional argument named Strategy:
================================================

  * "addHook(...,Strategy=>...)" -- see addHook (Macaulay2Doc),
    -- add a hook function to an object for later processing
  * "annihilator(...,Strategy=>...)" -- see annihilator, --
    the annihilator ideal
  * "basis(...,Strategy=>...)" -- see basis (Macaulay2Doc), --
    basis or generating set of all or part of a ring, ideal or module
  * "mingens(...,Strategy=>...)" -- see Complement (Macaulay2Doc),
    -- a Strategy option value
  * "trim(...,Strategy=>...)" -- see Complement (Macaulay2Doc),
    -- a Strategy option value
  * "compose(Module,Module,Module,Strategy=>...)" -- see compose (Macaulay2Doc),
    -- composition as a pairing on Hom-modules
  * determinant(...,Strategy=>...) (Macaulay2Doc)
    -- choose
    between Bareiss, Cofactor and Dynamic algorithms
  * "dual(MonomialIdeal,List,Strategy=>...)" -- see
    dual(MonomialIdeal,Strategy=>...) (Macaulay2Doc),
  * "dual(MonomialIdeal,RingElement,Strategy=>...)" -- see
    dual(MonomialIdeal,Strategy=>...) (Macaulay2Doc),
  * dual(MonomialIdeal,Strategy=>...) (Macaulay2Doc)
  * "End(...,Strategy=>...)" -- see End (Macaulay2Doc), -- module of
    endomorphisms
  * exteriorPower(...,Strategy=>...) (Macaulay2Doc)
    -- choose
    between Bareiss, Cofactor and Dynamic algorithms
  * "gb(...,Strategy=>...)" -- see gb (Macaulay2Doc), -- compute a
    Gröbner basis
  * "GF(...,Strategy=>...)" -- see GF (Macaulay2Doc), -- make a finite
    field
  * "groebnerBasis(...,Strategy=>...)" -- see groebnerBasis (Macaulay2Doc),
    -- Gröbner basis, as a matrix
  * "Hom(...,Strategy=>...)" -- see Hom (Macaulay2Doc), -- module of
    homomorphisms
  * "homomorphism'(...,Strategy=>...)" -- see homomorphism' (Macaulay2Doc),
    -- get the element of Hom from a homomorphism
  * "hooks(...,Strategy=>...)" -- see hooks (Macaulay2Doc), -- list
    hooks attached to a key
  * "intersect(Ideal,Ideal,Strategy=>...)" -- see intersect(Ideal,Ideal) (Macaulay2Doc),
    -- compute an intersection of a
    sequence of ideals or modules
  * "intersect(Module,Module,Strategy=>...)" -- see
    intersect(Ideal,Ideal) (Macaulay2Doc), --
    compute an intersection of a sequence of ideals or modules
  * "match(...,Strategy=>...)" -- see match (Macaulay2Doc), --
    regular expression matching
  * minors(...,Strategy=>...) (Macaulay2Doc)
    -- choose
    between Bareiss, Cofactor and Dynamic algorithms
  * "parallelApply(...,Strategy=>...)" -- see parallelApply (Macaulay2Doc),
    -- apply a function to each element in
    parallel
  * "pushForward(...,Strategy=>...)" -- see pushForward(RingMap,Module) (Macaulay2Doc),
    -- compute the pushforward
    of a module along a ring map
  * quotient'(...,Strategy=>...) (missing documentation)
  * quotient(...,Strategy=>...)
  * resolution(...,Strategy=>...) (OldChainComplexes)
  * saturate(...,Strategy=>...)
  * "syz(...,Strategy=>...)" -- see syz(Matrix) (Macaulay2Doc),
    -- compute the syzygy matrix

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

  * Default value: null
  * Function: saturate, -- saturation of ideal or submodule
  * Option key: Strategy (Macaulay2Doc), -- an optional argument
-------------------------------------------------------------------------------

The source of this document is in Saturation/saturate-doc.m2:139:0.