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

ReesAlgebra -- Compute Rees algebras and their invariants
*********************************************************

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

The Rees Algebra of an ideal is the commutative algebra analogue of the blow up
in algebraic geometry. (In fact, the  ``Rees Algebra'' is sometimes called the
``blowup algebra''.) A great deal of modern commutative algebra is devoted to
studying them.

Classically the Rees algebra appeared as the bihomogeneous coordinate ring of
the blowup of a projective variety along a subvariety or subscheme, used for
resolution of singularities. Though this is computationally slow on interesting
examples, we illustrate with some elementary cases of resolution of plane curve
singularities in PlaneCurveSingularities.

The Rees algebra was studied in the commutative algebra context (in the case
where M is an ideal of a ring R), by David Rees in a famous paper,

On a problem of Zariski, Illinois J. Math. (1958) 145-149).

In fact, Rees mainly studied the ring $R[It,t^{-1}]$, now also called the
`extended Rees Algebra' of I.

The original goal of this package, first written around 2002, was to compute
the Rees algebra of a module as it is defined in the paper What is the Rees
algebra of a module?, by Craig Huneke, David Eisenbud and Bernd Ulrich, Proc.
Am. Math. Soc. 131, 701-708, 2002. It has since expanded to include routines
for computing many of the invariants of an ideal or module defined in terms of
Rees algebras.

The Rees algebra, or more precisely the associated graded ring, which we
compute as a biproduct, plays a central role in modern intersection theory: it
is the basis of the Fulton-MacPherson definition of the intersection product in
the Chow ring. We illustrate this in distinguished, and
intersectInP.

The Rees algebra of a module M is defined by a certain ideal in the symmetric
algebra $Sym(M)$ of $M$, or, as in this package, by an ideal in the symmetric
algebra of any free module $F$ that maps onto $M$. When $\phi: M \to G$ is the
versal embedding of $M$, then, by the definition of Huneke-Eisenbud-Ulrich, the
Rees ideal of M is the kernel of $Sym(\phi)$. Thus the Rees Algebra of M is the
image of $Sym(\phi)$.

In most cases the kernel of the $Sym(\phi)$ is the same for any embedding
$\phi$ of $M$ into a free module:

Theorem (Eisenbud-Huneke-Ulrich, Thms 0.2 and 1.4): Let R be a Noetherian ring
and let $M$ be a finitely generated R-module. Let $\phi: M \to G$ be a versal
map of $M$ to a free module. Assume that $\phi$ is an inclusion, and let $\psi:
M \to G'$ be any inclusion. If $R$ is torsion-free over $\ZZ$ or $R$ is unmixed
and generically Gorenstein, or $M$ is free locally at each associated prime of
$R$, or $G=R$, then the kernel of $Sym(\phi)$ and the kernel of $Sym(\psi)$ are
equal.

It follows that in the good cases above the Rees ideal is equal to the
saturation of the defining ideal of symmetric algebra of $M$ with respect to
any element f of the ground ring such that $M[f^{-1}]$ is free, or is simply of
linear type, meaning that $Sym(\phi)$ is a monomorphism. This is the case, for
example, when M is an ideal and $M[f^{-1}]$ is generated by a regular sequence.
This fact often leads to a faster computation than computing the kernel of
$Sym(\phi)$ directly.

Here is an example of the pathological case of inclusions $\phi: M \to G$ and
$\psi: M \to G'$ where $ker(\phi) \neq ker(\psi)$. In the following, any finite
characteristic would work as well.

+-----------------------------------------------------------+
|i1 : p = 5;                                                |
+-----------------------------------------------------------+
|i2 : R = ZZ/p[x,y,z]/(ideal(x^p,y^p)+(ideal(x,y,z))^(p+1));|
+-----------------------------------------------------------+
|i3 : M = module ideal(z);                                  |
+-----------------------------------------------------------+

It is easy to check that M \cong R^1/(x,y,z)^p. We write iota: M\to R^1 for the
embedding as an ideal and psi for the embedding M \to R^2 sending z to (x,y).

+--------------------------------------+
|i4 : iota = map(R^1,M,matrix{{z}});   |
|                                      |
|             1                        |
|o4 : Matrix R  <-- M                  |
+--------------------------------------+
|i5 : psi = map(R^2,M,matrix{{x},{y}});|
|                                      |
|             2                        |
|o5 : Matrix R  <-- M                  |
+--------------------------------------+

Finally, a versal embedding is M \to R^3, sending z to (x,y,z):

+------------------------------+
|i6 : phi = versalEmbedding(M);|
|                              |
|             3                |
|o6 : Matrix R  <-- M          |
+------------------------------+

We now compute the kernels of the three maps on symmetric algebras:

+-----------------------------------------------------------------------------+
|i7 : Iiota = symmetricKernel iota;                                           |
|                                                                             |
|                                                                             |
|                                                                             |
|o7 : Ideal of ---------------------------------------------------------------|
|                5       4       4     2 3         3     2 3     3 2       2 2|
|              (z w , y*z w , x*z w , y z w , x*y*z w , x z w , y z w , x*y z |
|                  0       0       0       0         0       0       0        |
|-----------------------------------------------------------------------------|
|                R[w ]                                                        |
|                   0                                                         |
|-----------------------------------------------------------------------------|
|     2   2     3 2     4         3       2 2       3         4         4     |
|w , x y*z w , x z w , y z*w , x*y z*w , x y z*w , x y*z*w , x z*w , x*y w , x|
| 0         0       0       0         0         0         0       0       0   |
|-----------------------------------------------------------------------------|
|----------------------                                                       |
|2 3     3 2     4                                                            |
| y w , x y w , x y*w )                                                       |
|    0       0       0                                                        |
+-----------------------------------------------------------------------------+
|i8 : Ipsi = symmetricKernel psi;                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|o8 : Ideal of ---------------------------------------------------------------|
|                5       4       4     2 3         3     2 3     3 2       2 2|
|              (z w , y*z w , x*z w , y z w , x*y*z w , x z w , y z w , x*y z |
|                  0       0       0       0         0       0       0        |
|-----------------------------------------------------------------------------|
|                R[w ]                                                        |
|                   0                                                         |
|-----------------------------------------------------------------------------|
|     2   2     3 2     4         3       2 2       3         4         4     |
|w , x y*z w , x z w , y z*w , x*y z*w , x y z*w , x y*z*w , x z*w , x*y w , x|
| 0         0       0       0         0         0         0       0       0   |
|-----------------------------------------------------------------------------|
|----------------------                                                       |
|2 3     3 2     4                                                            |
| y w , x y w , x y*w )                                                       |
|    0       0       0                                                        |
+-----------------------------------------------------------------------------+
|i9 : Iphi = symmetricKernel phi;                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|o9 : Ideal of ---------------------------------------------------------------|
|                5       4       4     2 3         3     2 3     3 2       2 2|
|              (z w , y*z w , x*z w , y z w , x*y*z w , x z w , y z w , x*y z |
|                  0       0       0       0         0       0       0        |
|-----------------------------------------------------------------------------|
|                R[w ]                                                        |
|                   0                                                         |
|-----------------------------------------------------------------------------|
|     2   2     3 2     4         3       2 2       3         4         4     |
|w , x y*z w , x z w , y z*w , x*y z*w , x y z*w , x y*z*w , x z*w , x*y w , x|
| 0         0       0       0         0         0         0       0       0   |
|-----------------------------------------------------------------------------|
|----------------------                                                       |
|2 3     3 2     4                                                            |
| y w , x y w , x y*w )                                                       |
|    0       0       0                                                        |
+-----------------------------------------------------------------------------+

and check that the ones corresponding to phi and iota are equal, whereas the
ones corresponding to psi and phi are not:

+-------------------+
|i10 : Iiota == Iphi|
|                   |
|o10 = true         |
+-------------------+
|i11 : Ipsi == Iphi |
|                   |
|o11 = false        |
+-------------------+

In fact, they differ in degree p:

+---------------------------+
|i12 : numcols basis(p,Iphi)|
|                           |
|o12 = 3                    |
+---------------------------+
|i13 : numcols basis(p,Ipsi)|
|                           |
|o13 = 1                    |
+---------------------------+

See also
========

  * PlaneCurveSingularities -- Using the Rees
    Algebra to resolve plane curve singularities
  * distinguished -- Compute the distinguished
    subvarieties of a pullback, intersection or cone
  * intersectInP -- Compute distinguished varieties for an
    intersection in A^n or P^n

Authors
=======

  * David Eisenbud <de@msri.org>
  * Amelia Taylor <originalbrickhouse@gmail.com>
  * Sorin Popescu <sorin@math.sunysb.edu>
  * Michael E. Stillman <mike@math.cornell.edu>

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

Version 2.2 of this package was accepted for publication in volume 8 (see
https://msp.org/jsag/2018/8-1/ ) of The Journal of Software for Algebra and
Geometry (see https://msp.org/jsag/ ) on 21 May 2018, in the article The
ReesAlgebra package in Macaulay2 (see https://msp.org/jsag/2018/8-1/p05.xhtml )
(DOI: 10.2140/jsag.2018.8.49 (see https://doi.org/10.2140/jsag.2018.8.49 )).
That version can be obtained from the journal (see
https://msp.org/jsag/2018/8-1/jsag-v8-n1-x05-ReesAlgebra.m2 ).

Version
=======

This documentation describes version 2.3 of ReesAlgebra, released November
2019.

Citation
========

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

+-----------------------------------------------------------------------------+
|@misc{ReesAlgebraSource,                                                     |
|  title = {{ReesAlgebra: A \emph{Macaulay2} package. Version~2.3}},          |
|  author = {David Eisenbud and Amelia Taylor and Sorin Popescu and Michael E.|
|  howpublished = {A \emph{Macaulay2} package available at                    |
|    \url{https://github.com/Macaulay2/M2/tree/stable/M2/Macaulay2/packages}} |
|}                                                                            |
|                                                                             |
|@article{ReesAlgebraArticle,                                                 |
|  title = {{The ReesAlgebra package in \emph{Macaulay2}}},                   |
|  author = {David Eisenbud and Amelia Taylor and Sorin Popescu and Michael E.|
|  journal = {The Journal of Software for Algebra and Geometry},              |
|  volume = {8},                                                              |
|  year = {2018},                                                             |
|}                                                                            |
|-----------------------------------------------------------------------------|
|Stillman},                                                                   |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|Stillman},                                                                   |
+-----------------------------------------------------------------------------+

Exports
=======

  * Functions and commands
      * analyticSpread -- Compute the analytic spread of
        a module or ideal
      * associatedGradedRing -- The normal cone of
        a subscheme
      * distinguished -- Compute the distinguished
        subvarieties of a pullback, intersection or cone
      * expectedReesIdeal -- symmetric algebra ideal
        plus jacobian dual
      * intersectInP -- Compute distinguished varieties
        for an intersection in A^n or P^n
      * isLinearType -- Determine whether module has
        linear type
      * isReduction -- Determine whether an ideal is a
        reduction
      * jacobianDual -- Computes the 'jacobian dual', part
        of a method of finding generators for Rees Algebra ideals
      * minimalReduction -- Find a minimal reduction
        of an ideal
      * multiplicity -- Compute the Hilbert-Samuel
        multiplicity of an ideal
      * reductionNumber -- Reduction number of one
        ideal with respect to another
      * reesAlgebra -- Compute the defining ideal of the
        Rees Algebra
      * reesIdeal -- Compute the defining ideal of the Rees
        Algebra
      * specialFiber -- Special fiber of a blowup
      * specialFiberIdeal -- Special fiber of a
        blowup
      * symmetricAlgebraIdeal -- Ideal of the
        symmetric algebra of an ideal or module
      * symmetricKernel -- Compute the Rees ring of the
        image of a matrix
      * versalEmbedding -- Compute a versal embedding
      * whichGm -- Largest Gm satisfied by an ideal
  * Methods
      * "analyticSpread(Ideal)" -- see analyticSpread, --
        Compute the analytic spread of a module or ideal
      * "analyticSpread(Ideal,RingElement)" -- see analyticSpread,
        -- Compute the analytic spread of a module or ideal
      * "analyticSpread(Module)" -- see analyticSpread,
        -- Compute the analytic spread of a module or ideal
      * "analyticSpread(Module,RingElement)" -- see analyticSpread,
        -- Compute the analytic spread of a module or ideal
      * "associatedGradedRing(Ideal)" -- see associatedGradedRing,
        -- The normal cone of a subscheme
      * "associatedGradedRing(Ideal,RingElement)" -- see
        associatedGradedRing, -- The normal cone of a
        subscheme
      * "normalCone(Ideal)" -- see associatedGradedRing,
        -- The normal cone of a subscheme
      * "normalCone(Ideal,RingElement)" -- see associatedGradedRing,
        -- The normal cone of a subscheme
      * "distinguished(Ideal)" -- see distinguished, --
        Compute the distinguished subvarieties of a pullback, intersection or
        cone
      * "distinguished(Ideal,Ideal)" -- see distinguished,
        -- Compute the distinguished subvarieties of a pullback, intersection
        or cone
      * "distinguished(RingMap,Ideal)" -- see distinguished,
        -- Compute the distinguished subvarieties of a pullback,
        intersection or cone
      * "expectedReesIdeal(Ideal)" -- see expectedReesIdeal,
        -- symmetric algebra ideal plus jacobian dual
      * "expectedReesIdeal(Module)" -- see expectedReesIdeal,
        -- symmetric algebra ideal plus jacobian dual
      * "intersectInP(Ideal,Ideal)" -- see intersectInP, --
        Compute distinguished varieties for an intersection in A^n or P^n
      * "isLinearType(Ideal)" -- see isLinearType, --
        Determine whether module has linear type
      * "isLinearType(Ideal,RingElement)" -- see isLinearType,
        -- Determine whether module has linear type
      * "isLinearType(Module)" -- see isLinearType, --
        Determine whether module has linear type
      * "isLinearType(Module,RingElement)" -- see isLinearType,
        -- Determine whether module has linear type
      * "isReduction(Ideal,Ideal)" -- see isReduction, --
        Determine whether an ideal is a reduction
      * "isReduction(Ideal,Ideal,RingElement)" -- see isReduction,
        -- Determine whether an ideal is a reduction
      * "isReduction(Module,Module)" -- see isReduction, --
        Determine whether an ideal is a reduction
      * "isReduction(Module,Module,RingElement)" -- see isReduction,
        -- Determine whether an ideal is a reduction
      * "jacobianDual(Matrix)" -- see jacobianDual, --
        Computes the 'jacobian dual', part of a method of finding generators
        for Rees Algebra ideals
      * "jacobianDual(Matrix,Matrix,Matrix)" -- see jacobianDual,
        -- Computes the 'jacobian dual', part of a method of
        finding generators for Rees Algebra ideals
      * "minimalReduction(Ideal)" -- see minimalReduction,
        -- Find a minimal reduction of an ideal
      * "multiplicity(Ideal)" -- see multiplicity, --
        Compute the Hilbert-Samuel multiplicity of an ideal
      * "multiplicity(Ideal,RingElement)" -- see multiplicity,
        -- Compute the Hilbert-Samuel multiplicity of an ideal
      * "reductionNumber(Ideal,Ideal)" -- see reductionNumber,
        -- Reduction number of one ideal with respect to
        another
      * "reesAlgebra(Ideal)" -- see reesAlgebra, -- Compute
        the defining ideal of the Rees Algebra
      * "reesAlgebra(Ideal,RingElement)" -- see reesAlgebra,
        -- Compute the defining ideal of the Rees Algebra
      * "reesAlgebra(Module)" -- see reesAlgebra, -- Compute
        the defining ideal of the Rees Algebra
      * "reesAlgebra(Module,RingElement)" -- see reesAlgebra,
        -- Compute the defining ideal of the Rees Algebra
      * "reesIdeal(Ideal)" -- see reesIdeal, -- Compute the
        defining ideal of the Rees Algebra
      * "reesIdeal(Ideal,RingElement)" -- see reesIdeal, --
        Compute the defining ideal of the Rees Algebra
      * "reesIdeal(Module)" -- see reesIdeal, -- Compute the
        defining ideal of the Rees Algebra
      * "reesIdeal(Module,RingElement)" -- see reesIdeal, --
        Compute the defining ideal of the Rees Algebra
      * "specialFiber(Ideal)" -- see specialFiber, --
        Special fiber of a blowup
      * "specialFiber(Ideal,RingElement)" -- see specialFiber,
        -- Special fiber of a blowup
      * "specialFiber(Module)" -- see specialFiber, --
        Special fiber of a blowup
      * "specialFiber(Module,RingElement)" -- see specialFiber,
        -- Special fiber of a blowup
      * "specialFiberIdeal(Ideal)" -- see specialFiberIdeal,
        -- Special fiber of a blowup
      * "specialFiberIdeal(Ideal,RingElement)" -- see specialFiberIdeal,
        -- Special fiber of a blowup
      * "specialFiberIdeal(Module)" -- see specialFiberIdeal,
        -- Special fiber of a blowup
      * "specialFiberIdeal(Module,RingElement)" -- see specialFiberIdeal,
        -- Special fiber of a blowup
      * "symmetricAlgebraIdeal(Ideal)" -- see symmetricAlgebraIdeal,
        -- Ideal of the symmetric algebra of an ideal or
        module
      * "symmetricAlgebraIdeal(Module)" -- see symmetricAlgebraIdeal,
        -- Ideal of the symmetric algebra of an ideal or
        module
      * "symmetricKernel(Matrix)" -- see symmetricKernel,
        -- Compute the Rees ring of the image of a matrix
      * "versalEmbedding(Ideal)" -- see versalEmbedding,
        -- Compute a versal embedding
      * "versalEmbedding(Module)" -- see versalEmbedding,
        -- Compute a versal embedding
      * "whichGm(Ideal)" -- see whichGm, -- Largest Gm satisfied
        by an ideal
  * Symbols
      * PlaneCurveSingularities -- Using the
        Rees Algebra to resolve plane curve singularities
      * Trim -- Choose whether to trim (or find minimal
        generators) for the ideal or module.

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

The object ReesAlgebra, is a package (Macaulay2Doc),
defined in ReesAlgebra.m2.

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

The source of this document is in ReesAlgebra.m2:748:0.

analyticSpread -- Compute the analytic spread of a module or ideal
******************************************************************

  * Usage:
        analyticSpread M
        analyticSpread(M,f)
  * Inputs:
      * M, a module (Macaulay2Doc), or an ideal (Macaulay2Doc),
      * f, a ring element (Macaulay2Doc), an optional
        element, which is a non-zerodivisor such that $M[f^{-1}]$ is a free
        module when $M$ is a module, an element in $M$ when $M$ is an ideal
  * Optional inputs (Macaulay2Doc),:
      * BasisElementLimit,
        => ...,
        default value infinity, Bound the number of Groebner basis elements to
        compute in the saturation step
      * DegreeLimit,
        => ..., default value {}, Bound the degrees considered in the
        saturation step. Defaults to infinity
      * MinimalGenerators,
        => ...,
        default value true, Whether the saturation step returns minimal
        generators
      * PairLimit, =>
        ..., default value infinity, Bound the number of s-pairs considered in
        the saturation step
      * Strategy, => ...,
        default value null, Choose a strategy for the saturation step
  * Outputs:
      * an integer (Macaulay2Doc), the analytic spread of a module or
        an ideal $M$

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

The analytic spread of a module is the dimension of its special fiber ring.
When $I$ is an ideal (and more generally, with the right definitions) the
analytic spread of $I$ is the smallest number of generators of an ideal $J$
such that $I$ is integral over $J$. See for example the book Integral closure
of ideals, rings, and modules. London Mathematical Society Lecture Note Series,
336. Cambridge University Press, Cambridge, 2006, by Craig Huneke and Irena
Swanson.

+--------------------------------------------------------------------+
|i1 : R=QQ[a..h]                                                     |
|                                                                    |
|o1 = R                                                              |
|                                                                    |
|o1 : PolynomialRing                                                 |
+--------------------------------------------------------------------+
|i2 : M=matrix{{a,b,c,d},{e,f,g,h}}                                  |
|                                                                    |
|o2 = | a b c d |                                                    |
|     | e f g h |                                                    |
|                                                                    |
|             2      4                                               |
|o2 : Matrix R  <-- R                                                |
+--------------------------------------------------------------------+
|i3 : analyticSpread minors(2,M)                                     |
|                                                                    |
|o3 = 5                                                              |
+--------------------------------------------------------------------+
|i4 : specialFiberIdeal minors(2,M)                                  |
|                                                                    |
|o4 = ideal(Z Z  - Z Z  + Z Z )                                      |
|            2 3    1 4    0 5                                       |
|                                                                    |
|o4 : Ideal of QQ[Z ..Z ]                                            |
|                  0   5                                             |
+--------------------------------------------------------------------+
|i5 : R=QQ[a,b,c,d]                                                  |
|                                                                    |
|o5 = R                                                              |
|                                                                    |
|o5 : PolynomialRing                                                 |
+--------------------------------------------------------------------+
|i6 : M=matrix{{a,b,c,d},{b,c,d,a}}                                  |
|                                                                    |
|o6 = | a b c d |                                                    |
|     | b c d a |                                                    |
|                                                                    |
|             2      4                                               |
|o6 : Matrix R  <-- R                                                |
+--------------------------------------------------------------------+
|i7 : analyticSpread minors(2,M)                                     |
|                                                                    |
|o7 = 4                                                              |
+--------------------------------------------------------------------+
|i8 : specialFiberIdeal minors(2,M)                                  |
|                                                                    |
|                                 2                  2               |
|o8 = ideal (Z Z  - Z Z  + Z Z , Z  - Z Z  - Z Z  - Z  + Z Z  + Z Z )|
|             2 3    1 4    0 5   1    0 2    0 3    4    2 5    3 5 |
|                                                                    |
|o8 : Ideal of QQ[Z ..Z ]                                            |
|                  0   5                                             |
+--------------------------------------------------------------------+

See also
========

  * specialFiberIdeal -- Special fiber of a blowup
  * reesIdeal -- Compute the defining ideal of the Rees
    Algebra

Ways to use analyticSpread:
===========================

  * "analyticSpread(Ideal)"
  * "analyticSpread(Ideal,RingElement)"
  * "analyticSpread(Module)"
  * "analyticSpread(Module,RingElement)"

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

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

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

The source of this document is in ReesAlgebra.m2:1471:0.

associatedGradedRing -- The normal cone of a subscheme
******************************************************

  * Usage:
        normalCone I
        normalCone(I,f)
        associatedGradedRing I
        associatedGradedRing(I,f)
  * Inputs:
      * I, an ideal (Macaulay2Doc),
      * f, a ring element (Macaulay2Doc), optional argument,
        if given it should be a non-zero divisor in the ideal I
  * Optional inputs (Macaulay2Doc),:
      * BasisElementLimit,
        => ...,
        default value infinity, Bound the number of Groebner basis elements to
        compute in the saturation step
      * DegreeLimit,
        => ..., default value {}, Bound the degrees considered in the
        saturation step. Defaults to infinity
      * MinimalGenerators,
        => ...,
        default value true, Whether the saturation step returns minimal
        generators
      * PairLimit, =>
        ..., default value infinity, Bound the number of s-pairs considered in
        the saturation step
      * Strategy, => ...,
        default value null, Choose a strategy for the saturation step
      * Variable,
        => ..., default value "w", Choose name for variables in the created
        ring
  * Outputs:
      * a ring (Macaulay2Doc), the ring $R[It] \otimes{} R/I$ of
        the normal cone of $I$

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

The normal cone of an ideal $I\subset{} R$ is the ring $R/I \oplus{} I/I^2
\oplus \ldots$, also called the associated graded ring of $R$ with respect to
$I$.  If $S$ is the Rees algebra of $I$, then this ring is isomorphic to
$S/IS$, which is how it is computed here.

See also
========

  * reesAlgebra -- Compute the defining ideal of the Rees
    Algebra
  * grGr (MultiplicitySequence) -- the bigraded ring Gr_m(Gr_I(R))

Ways to use associatedGradedRing:
=================================

  * "associatedGradedRing(Ideal)"
  * "associatedGradedRing(Ideal,RingElement)"

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

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

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

The source of this document is in ReesAlgebra.m2:1278:0.

distinguished -- Compute the distinguished subvarieties of a pullback, intersection or cone
*******************************************************************************************

  * Usage:
        L = distinguished(f,I)
        L = distinguished(I,J)
        L = distinguished(I)
  * Inputs:
      * f, a ring map (Macaulay2Doc),
      * I, an ideal (Macaulay2Doc),
      * J, an ideal (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * BasisElementLimit,
        => ...,
        default value infinity, Bound the number of Groebner basis elements to
        compute in the saturation step
      * DegreeLimit,
        => ..., default value {}, Bound the degrees considered in the
        saturation step. Defaults to infinity
      * MinimalGenerators,
        => ...,
        default value true, Whether the saturation step returns minimal
        generators
      * PairLimit, =>
        ..., default value infinity, Bound the number of s-pairs considered in
        the saturation step
      * Strategy, => ...,
        default value null, Choose a strategy for the saturation step
      * Variable,
        => ..., default value "w", Choose name for variables in the created
        ring
  * Outputs:
      * L, a list (Macaulay2Doc),

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

Suppose that f:S\to R is a map of rings, and I is an ideal of S. Let K be the
kernel of the map of associated graded rings gr_I(S) \to gr_(fI)R.

The distinguished primes p_i in S/I are the intersections of the minimal primes
P_i over K with S/I \subset{} gr_IS, that is, the minimal primes of the support
in R/I of the normal cone of f(I). The multiplicity associated with p_i is by
definition the multiplicity of P_i in the primary decomposition of K.

Distinguished subvarieties and their multiplicity (defined by the distinguished
primes, usually in the global case of a quasi-projective variety and its sheaf
of rings) play a central role in the Fulton-MacPherson construction of refined
intersection products. See William Fulton, Intersection Theory, Section 6.1 for
the geometric context and the general case, and the explanation in the article
Rees Algebras in JSAG (submitted).

This application is illustrated in the code for intersectInP.

We allow the special cases

distinguished(I,J) := distinguished(f,I), with f:S\to S/J the projection

and

distinguished(I) := distinguished(f,I), with f:S\to S the identity.

which computes the distinguished primes in the support of the normal cone gr_IS
itself. An interesting application is given in the paper

``A geometric effective Nullstellensatz,'' Invent. Math. 137 (1999), no. 2,
427–448 by Ein and Lazarsfeld.

Here is an example showing that associated primes need not be distinguished
primes:

+----------------------------+
|i1 : R = ZZ/101[a,b]        |
|                            |
|o1 = R                      |
|                            |
|o1 : PolynomialRing         |
+----------------------------+
|i2 : I = ideal(a^2, a*b)    |
|                            |
|             2              |
|o2 = ideal (a , a*b)        |
|                            |
|o2 : Ideal of R             |
+----------------------------+
|i3 : ass I                  |
|                            |
|o3 = {ideal a, ideal (b, a)}|
|                            |
|o3 : List                   |
+----------------------------+

There is one minimal associated prime (a thick line in $P^3$) and one embedded
prime.

+--------------------------------------+
|i4 : distinguished I                  |
|                                      |
|o4 = {{2, ideal (b, a)}, {1, ideal a}}|
|                                      |
|o4 : List                             |
+--------------------------------------+
|i5 : intersectInP(I,I)                |
|                                      |
|o5 = {{1, ideal a}}                   |
|                                      |
|o5 : List                             |
+--------------------------------------+

See also
========

  * intersectInP -- Compute distinguished varieties for an
    intersection in A^n or P^n
  * saturate (missing documentation)

Ways to use distinguished:
==========================

  * "distinguished(Ideal)"
  * "distinguished(Ideal,Ideal)"
  * "distinguished(RingMap,Ideal)"

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

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

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

The source of this document is in ReesAlgebra.m2:1544:0.

expectedReesIdeal -- symmetric algebra ideal plus jacobian dual
***************************************************************

  * Usage:
        J = expectedReesIdeal M
  * Inputs:
      * M, an ideal (Macaulay2Doc),
      * M, a module (Macaulay2Doc),
  * Outputs:
      * J, an ideal (Macaulay2Doc),

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

Let M be an R-module with g generators and free presentation phi: R^h \to R^g.
The symmetric algebra of M can be written as R[T_1,\dots,T_g]/J, where J is the
ideal generated by the entries of the 1 x h matrix T*m, where T = (T_1..T_g).
If the entries of m are all contained in an ideal (X_1..X_n) (for example, when
m is a minimal presentation and the X_i generate the maximal ideal, there is a
matrix psi: R[Z]^h \to R[Z]^n such that T*phi = X*psi. Under reasonable
hypotheses (eg when R is a domain) the relation X*psi = 0 in the Rees algebra
implies that the n x n minors of psi are 0. Thus these minors lie in the ideal
defining the Rees algebra. The expectedReesIdeal is the sum of the ideals
(T*phi) and the ideal of nxn minors of psi. Under particularly good
circumstances this sum is known to be equal to the ideal of the Rees algebra.
More generally, it may speed computations of reesIdeal, to
start with this sum rather than with the ideal T*phi, as in the following
example. (This can be turned off with the Jacobian=>false option.)

The term 'Expected Rees Ideal' for the sum of of the ideal of the symmetric
algebra of I with the ideal of maximal minors of the Jacobian dual matrix of a
presentation of I is derived from the paper "Rees Algebras of Ideals of Low
Codimension", Proc. Am. Math. Soc. 1996 of Colley and Ulrich. Building on the
paper "Ideals with Expected Reduction Number", Am. J. Math 1996, they prove
that this ideal is in fact equal to the ideal of the Rees algebra of I when I
is a codimension 2 perfect ideal whose Hilbert-Burch matrix has a special form.
See jacobianDual, for an example.

+-----------------------------------------------------------------------------+
|i1 : setRandomSeed 0                                                         |
| -- setting random seed to 0                                                 |
|                                                                             |
|o1 = 0                                                                       |
+-----------------------------------------------------------------------------+
|i2 : n = 5                                                                   |
|                                                                             |
|o2 = 5                                                                       |
+-----------------------------------------------------------------------------+
|i3 : S = ZZ/101[x_0..x_(n-2)];                                               |
+-----------------------------------------------------------------------------+
|i4 : M1 = random(S^(n-1),S^{n-1:-2});                                        |
|                                                                             |
|             4      4                                                        |
|o4 : Matrix S  <-- S                                                         |
+-----------------------------------------------------------------------------+
|i5 : M = M1||vars S                                                          |
|                                                                             |
|o5 = | 24x_0^2-36x_0x_1+19x_1^2-30x_0x_2+19x_1x_2-29x_2^2-29x_0x_3-10x_1x_3  |
|     | -29x_0^2-24x_0x_1+39x_1^2-38x_0x_2+21x_1x_2+19x_2^2-16x_0x_3+34x_1x_  |
|     | -18x_0^2-13x_0x_1-28x_1^2-43x_0x_2-47x_1x_2+2x_2^2-15x_0x_3+38x_1x_3  |
|     | 45x_0^2-34x_0x_1+47x_1^2-48x_0x_2+19x_1x_2+7x_2^2-47x_0x_3-16x_1x_3+  |
|     | x_0                                                                   |
|     ------------------------------------------------------------------------|
|     -8x_2x_3-22x_3^2   39x_0^2+43x_0x_1+48x_1^2-17x_0x_2+36x_1x_2+11x_2     |
|     3-47x_2x_3-39x_3^2 40x_0^2+11x_0x_1+x_1^2+46x_0x_2-3x_1x_2-47x_2^2-     |
|     +16x_2x_3+22x_3^2  2x_0^2+29x_0x_1-37x_1^2-47x_0x_2-13x_1x_2+30x_2^     |
|     15x_2x_3-23x_3^2   27x_0^2-22x_0x_1-32x_1^2+32x_0x_2-20x_1x_2-30x_2     |
|                        x_1                                                  |
|     ------------------------------------------------------------------------|
|     ^2-11x_0x_3+35x_1x_3-38x_2x_3+33x_3^2                                   |
|     28x_0x_3+22x_1x_3-23x_2x_3-7x_3^2                                       |
|     2+15x_0x_3-10x_1x_3-18x_2x_3+39x_3^2                                    |
|     ^2-9x_0x_3+24x_1x_3-48x_2x_3-15x_3^2                                    |
|                                                                             |
|     ------------------------------------------------------------------------|
|     39x_0^2-33x_1^2+33x_0x_2-19x_1x_2-20x_2^2-49x_0x_3+17x_1x_3+44x_2x      |
|     36x_0^2+9x_0x_1+13x_1^2-39x_0x_2-26x_1x_2-49x_2^2+4x_0x_3+22x_1x_3      |
|     43x_0^2-8x_0x_1-22x_1^2+36x_0x_2-30x_1x_2+16x_2^2-3x_0x_3+41x_1x_3      |
|     35x_0^2-9x_0x_1+40x_1^2-35x_0x_2+3x_1x_2+25x_2^2+6x_0x_3-31x_1x_3-      |
|     x_2                                                                     |
|     ------------------------------------------------------------------------|
|     _3-39x_3^2       -49x_0^2-13x_0x_1-47x_1^2+4x_0x_2+27x_1x_2+37x_2^2     |
|     -11x_2x_3-8x_3^2 -39x_0^2-31x_0x_1-48x_1^2-48x_0x_2+30x_1x_2+47x_2^     |
|     -28x_2x_3-6x_3^2 -18x_0^2+46x_0x_1-22x_1^2+x_0x_2+10x_1x_2+30x_2^2+     |
|     2x_2x_3-41x_3^2  -13x_0^2+3x_0x_1+8x_1^2-41x_0x_2-29x_1x_2-46x_2^2+     |
|                      x_3                                                    |
|     ------------------------------------------------------------------------|
|     +30x_0x_3-40x_1x_3-35x_2x_3-31x_3^2  |                                  |
|     2-29x_0x_3-37x_1x_3-49x_2x_3+28x_3^2 |                                  |
|     40x_0x_3+7x_1x_3+13x_2x_3-17x_3^2    |                                  |
|     8x_0x_3+30x_1x_3+49x_2x_3-18x_3^2    |                                  |
|                                          |                                  |
|                                                                             |
|             5      4                                                        |
|o5 : Matrix S  <-- S                                                         |
+-----------------------------------------------------------------------------+
|i6 : I = minors(n-1, M);                                                     |
|                                                                             |
|o6 : Ideal of S                                                              |
+-----------------------------------------------------------------------------+
|i7 : time rI = expectedReesIdeal I; -- n= 5 case takes < 1 sec.              |
| -- used 1.36835s (cpu); 0.986148s (thread); 0s (gc)                         |
|                                                                             |
|o7 : Ideal of S[w ..w ]                                                      |
|                 0   4                                                       |
+-----------------------------------------------------------------------------+
|i8 : kk = ZZ/101;                                                            |
+-----------------------------------------------------------------------------+
|i9 : S = kk[x,y,z];                                                          |
+-----------------------------------------------------------------------------+
|i10 : m = random(S^3, S^{4:-2});                                             |
|                                                                             |
|              3      4                                                       |
|o10 : Matrix S  <-- S                                                        |
+-----------------------------------------------------------------------------+
|i11 : I = minors(3,m);                                                       |
|                                                                             |
|o11 : Ideal of S                                                             |
+-----------------------------------------------------------------------------+
|i12 : time reesIdeal (I, I_0);                                               |
| -- used 2.12105s (cpu); 1.72332s (thread); 0s (gc)                          |
|                                                                             |
|o12 : Ideal of S[w ..w ]                                                     |
|                  0   3                                                      |
+-----------------------------------------------------------------------------+
|i13 : time reesIdeal (I, I_0, Jacobian =>false);                             |
| -- used 2.12039s (cpu); 1.71008s (thread); 0s (gc)                          |
|                                                                             |
|o13 : Ideal of S[w ..w ]                                                     |
|                  0   3                                                      |
+-----------------------------------------------------------------------------+

See also
========

  * symmetricAlgebraIdeal -- Ideal of the
    symmetric algebra of an ideal or module
  * jacobianDual -- Computes the 'jacobian dual', part of
    a method of finding generators for Rees Algebra ideals

Ways to use expectedReesIdeal:
==============================

  * "expectedReesIdeal(Ideal)"
  * "expectedReesIdeal(Module)"

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

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

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

The source of this document is in ReesAlgebra.m2:2234:0.

intersectInP -- Compute distinguished varieties for an intersection in A^n or P^n
*********************************************************************************

  * Usage:
        L = intersectInP(I,J)
  * Inputs:
      * I, an ideal (Macaulay2Doc), of a polynomial ring P over a
        field
      * J, an ideal (Macaulay2Doc), of the same ring
  * Optional inputs (Macaulay2Doc),:
      * BasisElementLimit,
        => ...,
        default value infinity, Option for intersectInP
      * DegreeLimit,
        => ..., default value {}, Option for intersectInP
      * MinimalGenerators,
        => ...,
        default value true, Option for intersectInP
      * PairLimit,
        => ..., default value infinity, Option for intersectInP
      * Strategy,
        => ..., default value null, Option for intersectInP
      * Variable,
        => ..., default value "w", Option for intersectInP
  * Outputs:
      * L, a list (Macaulay2Doc),

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

This function applies the technology of distinguished, to
compute the distinguished subvarieties, with their multiplicities, for an
intersection in affine or projective space. The function distinguished,
is actually applied to the diagonal ideal in P**P and the ideal
I**P + P**I, and the answer is pulled back to P.

+-------------------------------------------------------+
|i1 : kk = ZZ/101                                       |
|                                                       |
|o1 = kk                                                |
|                                                       |
|o1 : QuotientRing                                      |
+-------------------------------------------------------+
|i2 : P = kk[x,y]                                       |
|                                                       |
|o2 = P                                                 |
|                                                       |
|o2 : PolynomialRing                                    |
+-------------------------------------------------------+
|i3 : I = ideal"x2-y";J=ideal y                         |
|                                                       |
|o3 : Ideal of P                                        |
|                                                       |
|o4 = ideal y                                           |
|                                                       |
|o4 : Ideal of P                                        |
+-------------------------------------------------------+
|i5 : intersectInP(I,J)                                 |
|                                                       |
|o5 = {{2, ideal (y, x)}}                               |
|                                                       |
|o5 : List                                              |
+-------------------------------------------------------+
|i6 : I = ideal"x4+y3+1"                                |
|                                                       |
|            4    3                                     |
|o6 = ideal(x  + y  + 1)                                |
|                                                       |
|o6 : Ideal of P                                        |
+-------------------------------------------------------+
|i7 : intersectInP(I,J)                                 |
|                                                       |
|                     2                        2        |
|o7 = {{1, ideal (y, x  - 10)}, {1, ideal (y, x  + 10)}}|
|                                                       |
|o7 : List                                              |
+-------------------------------------------------------+
|i8 : I = ideal"x2y";J=ideal"xy2"                       |
|                                                       |
|o8 : Ideal of P                                        |
|                                                       |
|              2                                        |
|o9 = ideal(x*y )                                       |
|                                                       |
|o9 : Ideal of P                                        |
+-------------------------------------------------------+
|i10 : intersectInP(I,J)                                |
|                                                       |
|o10 = {{5, ideal (y, x)}, {2, ideal y}, {2, ideal x}}  |
|                                                       |
|o10 : List                                             |
+-------------------------------------------------------+
|i11 : intersectInP(I,I)                                |
|                                                       |
|o11 = {{4, ideal (y, x)}, {1, ideal y}, {4, ideal x}}  |
|                                                       |
|o11 : List                                             |
+-------------------------------------------------------+

Note that in the last two cases, which are improper intersections of two
cubics, the total multiplicity is 9 = 3*3. But this is not always the case (in
the actual definition of the intersection product, the multiplicity is
multiplied by the class of a certain cycle supported on the distinguished
subvariety).

+--------------------------+
|i12 : I = ideal"y-x2"     |
|                          |
|               2          |
|o12 = ideal(- x  + y)     |
|                          |
|o12 : Ideal of P          |
+--------------------------+
|i13 : intersectInP(I,I)   |
|                          |
|                  2       |
|o13 = {{1, ideal(x  - y)}}|
|                          |
|o13 : List                |
+--------------------------+

Caveat
======

See also
========

  * distinguished -- Compute the distinguished
    subvarieties of a pullback, intersection or cone

Ways to use intersectInP:
=========================

  * "intersectInP(Ideal,Ideal)"

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

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

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

The source of this document is in ReesAlgebra.m2:1589:0.

intersectInP(...,BasisElementLimit=>...) -- Option for intersectInP
*******************************************************************

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

see the options for saturate (Saturation).

See also
========

  * intersectInP -- Compute distinguished varieties for an
    intersection in A^n or P^n
  * distinguished -- Compute the distinguished
    subvarieties of a pullback, intersection or cone
  * saturate (missing documentation)

Functions with optional argument named BasisElementLimit:
=========================================================

  * "gb(...,BasisElementLimit=>...)" -- see gb (Macaulay2Doc), --
    compute a Gröbner basis
  * intersectInP(...,BasisElementLimit=>...)
    -- Option for
    intersectInP
  * "analyticSpread(...,BasisElementLimit=>...)" -- see
    minimalReduction(...,BasisElementLimit=>...),
    -- Bound
    the number of Groebner basis elements to compute in the saturation step
  * "associatedGradedRing(...,BasisElementLimit=>...)" -- see
    minimalReduction(...,BasisElementLimit=>...),
    -- Bound
    the number of Groebner basis elements to compute in the saturation step
  * "distinguished(...,BasisElementLimit=>...)" -- see
    minimalReduction(...,BasisElementLimit=>...),
    -- Bound
    the number of Groebner basis elements to compute in the saturation step
  * "isLinearType(...,BasisElementLimit=>...)" -- see
    minimalReduction(...,BasisElementLimit=>...),
    -- Bound
    the number of Groebner basis elements to compute in the saturation step
  * "isReduction(...,BasisElementLimit=>...)" -- see
    minimalReduction(...,BasisElementLimit=>...),
    -- Bound
    the number of Groebner basis elements to compute in the saturation step
  * minimalReduction(...,BasisElementLimit=>...)
    -- Bound
    the number of Groebner basis elements to compute in the saturation step
  * "multiplicity(...,BasisElementLimit=>...)" -- see
    minimalReduction(...,BasisElementLimit=>...),
    -- Bound
    the number of Groebner basis elements to compute in the saturation step
  * "normalCone(Ideal,BasisElementLimit=>...)" -- see
    minimalReduction(...,BasisElementLimit=>...),
    -- Bound
    the number of Groebner basis elements to compute in the saturation step
  * "normalCone(Ideal,RingElement,BasisElementLimit=>...)" -- see
    minimalReduction(...,BasisElementLimit=>...),
    -- Bound
    the number of Groebner basis elements to compute in the saturation step
  * "reesAlgebra(...,BasisElementLimit=>...)" -- see
    minimalReduction(...,BasisElementLimit=>...),
    -- Bound
    the number of Groebner basis elements to compute in the saturation step
  * "reesIdeal(...,BasisElementLimit=>...)" -- see
    minimalReduction(...,BasisElementLimit=>...),
    -- Bound
    the number of Groebner basis elements to compute in the saturation step
  * "specialFiber(...,BasisElementLimit=>...)" -- see
    minimalReduction(...,BasisElementLimit=>...),
    -- Bound
    the number of Groebner basis elements to compute in the saturation step
  * "specialFiberIdeal(...,BasisElementLimit=>...)" -- see
    minimalReduction(...,BasisElementLimit=>...),
    -- Bound
    the number of Groebner basis elements to compute in the saturation step
  * quotient(...,BasisElementLimit=>...) (missing documentation)
  * saturate(...,BasisElementLimit=>...) (missing documentation)
  * "syz(...,BasisElementLimit=>...)" -- see syz(Matrix) (Macaulay2Doc),
    -- compute the syzygy matrix

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

  * Default value: infinity (Macaulay2Doc),
  * Function: intersectInP, -- Compute distinguished
    varieties for an intersection in A^n or P^n
  * Option key: BasisElementLimit (Macaulay2Doc), -- an
    optional argument
-------------------------------------------------------------------------------

The source of this document is in ReesAlgebra.m2:1609:0.

isLinearType -- Determine whether module has linear type
********************************************************

  * Usage:
        isLinearType M
        isLinearType(M,f)
  * Inputs:
      * M, a module (Macaulay2Doc), or an ideal (Macaulay2Doc),
      * f, a ring element (Macaulay2Doc), any non-zero
        divisor modulo the ideal or module.  Optional
  * Optional inputs (Macaulay2Doc),:
      * BasisElementLimit,
        => ...,
        default value infinity, Bound the number of Groebner basis elements to
        compute in the saturation step
      * DegreeLimit,
        => ..., default value {}, Bound the degrees considered in the
        saturation step. Defaults to infinity
      * MinimalGenerators,
        => ...,
        default value true, Whether the saturation step returns minimal
        generators
      * PairLimit, =>
        ..., default value infinity, Bound the number of s-pairs considered in
        the saturation step
      * Strategy, => ...,
        default value null, Choose a strategy for the saturation step
  * Outputs:
      * a Boolean value (Macaulay2Doc), true if M is of linear
        type, false otherwise

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

A module or ideal $M$ is said to be ``of linear type'' if the natural map from
the symmetric algebra of $M$ to the Rees algebra of $M$ is an isomorphism. It
is known, for example, that any complete intersection ideal is of linear type.

This routine computes the reesIdeal, of M.  Giving the element
f computes the reesIdeal, in a different manner, which is
sometimes faster, sometimes slower.

+-----------------------------------------------------------------------------+
|i1 : S = QQ[x_0..x_4]                                                        |
|                                                                             |
|o1 = S                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : i = monomialCurveIdeal(S,{2,3,5,6})                                     |
|                                                                             |
|                          2                       3      2     2      2     2|
|o2 = ideal (x x  - x x , x  - x x , x x  - x x , x  - x x , x x  - x x , x x |
|             2 3    1 4   2    0 4   1 2    0 3   3    2 4   1 3    0 4   0 3|
|     ------------------------------------------------------------------------|
|        2     2              3    2                                          |
|     - x x , x x  - x x x , x  - x x )                                       |
|        1 4   1 3    0 2 4   1    0 4                                        |
|                                                                             |
|o2 : Ideal of S                                                              |
+-----------------------------------------------------------------------------+
|i3 : isLinearType i                                                          |
|                                                                             |
|o3 = false                                                                   |
+-----------------------------------------------------------------------------+
|i4 : isLinearType(i, i_0)                                                    |
|                                                                             |
|o4 = false                                                                   |
+-----------------------------------------------------------------------------+
|i5 : I = reesIdeal i                                                         |
|                                                                             |
|                                                     2                       |
|o5 = ideal (x w  - x w  + x w , x w  - x w  + x w , x w  + x w  - x w ,      |
|             2 0    3 1    4 2   0 0    1 1    2 2   4 2    1 3    3 4       |
|     ------------------------------------------------------------------------|
|                            2                   2                            |
|     x x w  + x w  - x w , x w  + x w  - x w , x w  + x w  - x w , x x w  -  |
|      0 4 2    1 5    3 6   3 2    0 3    2 4   1 2    0 5    2 6   1 4 1    |
|     ------------------------------------------------------------------------|
|                                                           2      2          |
|     x x w  - x w  + x w , x x w  - x x w  - x w  + x w , x w  - x w  - x w  |
|      2 4 2    1 4    3 5   0 4 1    1 3 2    0 4    2 5   3 0    4 1    2 3 |
|     ------------------------------------------------------------------------|
|                                    2                                2    2  |
|     + x w , x x w  - x w  + x w , x w  - x x w  - x w  + x w , x x w  - w  -|
|        4 4   1 3 0    2 4    4 5   1 0    1 3 2    0 4    4 6   1 4 2    5  |
|     ------------------------------------------------------------------------|
|                                         2                         2         |
|     x w w  + w w , x x w w  - x w w  + w  - w w , x x w w  - x x w  + w w  -|
|      4 1 6    4 6   3 4 0 2    4 1 4    4    3 5   1 4 0 2    3 4 2    4 5  |
|     ------------------------------------------------------------------------|
|     w w )                                                                   |
|      3 6                                                                    |
|                                                                             |
|o5 : Ideal of S[w ..w ]                                                      |
|                 0   6                                                       |
+-----------------------------------------------------------------------------+
|i6 : select(I_*, f -> first degree f > 1)                                    |
|                                                                             |
|           2    2                                       2                    |
|o6 = {x x w  - w  - x w w  + w w , x x w w  - x w w  + w  - w w , x x w w  - |
|       1 4 2    5    4 1 6    4 6   3 4 0 2    4 1 4    4    3 5   1 4 0 2   |
|     ------------------------------------------------------------------------|
|          2                                                                  |
|     x x w  + w w  - w w }                                                   |
|      3 4 2    4 5    3 6                                                    |
|                                                                             |
|o6 : List                                                                    |
+-----------------------------------------------------------------------------+
+-------------------------------------------------------------+
|i7 : S = ZZ/101[x,y,z]                                       |
|                                                             |
|o7 = S                                                       |
|                                                             |
|o7 : PolynomialRing                                          |
+-------------------------------------------------------------+
|i8 : for p from 1 to 5 do print isLinearType (ideal vars S)^p|
|true                                                         |
|false                                                        |
|false                                                        |
|false                                                        |
|false                                                        |
+-------------------------------------------------------------+

See also
========

  * reesIdeal -- Compute the defining ideal of the Rees
    Algebra
  * monomialCurveIdeal (Macaulay2Doc) -- make the
    ideal of a monomial curve

Ways to use isLinearType:
=========================

  * "isLinearType(Ideal)"
  * "isLinearType(Ideal,RingElement)"
  * "isLinearType(Module)"
  * "isLinearType(Module,RingElement)"

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

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

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

The source of this document is in ReesAlgebra.m2:1199:0.

isReduction -- Determine whether an ideal is a reduction
********************************************************

  * Usage:
        t=isReduction(I,J)
        t=isReduction(I,J,f)
  * Inputs:
      * I, an ideal (Macaulay2Doc),
      * J, an ideal (Macaulay2Doc),
      * f, a ring element (Macaulay2Doc), an optional
        element, which is a non-zerodivisor modulo M and the ring of M
  * Optional inputs (Macaulay2Doc),:
      * BasisElementLimit,
        => ...,
        default value infinity, Bound the number of Groebner basis elements to
        compute in the saturation step
      * DegreeLimit,
        => ..., default value {}, Bound the degrees considered in the
        saturation step. Defaults to infinity
      * MinimalGenerators,
        => ...,
        default value true, Whether the saturation step returns minimal
        generators
      * PairLimit, =>
        ..., default value infinity, Bound the number of s-pairs considered in
        the saturation step
      * Strategy, => ...,
        default value null, Choose a strategy for the saturation step
      * Variable,
        => ..., default value "w", Choose name for variables in the created
        ring
  * Outputs:
      * t, a Boolean value (Macaulay2Doc), true if J is a
        reduction of I, false otherwise

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

For an ideal $I$, a subideal $J$ of $I$ is said to be a reduction of $I$ if
there exists a nonnegative integer n such that $JI^{n}=I^{n+1}$.

This function returns true if $J$ is a reduction of $I$ and returns false if
$J$ is not a subideal of $I$ or $J$ is a subideal but not a reduction of $I$.

+----------------------------+
|i1 : S = ZZ/5[x,y]          |
|                            |
|o1 = S                      |
|                            |
|o1 : PolynomialRing         |
+----------------------------+
|i2 : I = ideal(x^3,x*y,y^4) |
|                            |
|             3        4     |
|o2 = ideal (x , x*y, y )    |
|                            |
|o2 : Ideal of S             |
+----------------------------+
|i3 : J = ideal(x*y, x^3+y^4)|
|                            |
|                  4    3    |
|o3 = ideal (x*y, y  + x )   |
|                            |
|o3 : Ideal of S             |
+----------------------------+
|i4 : isReduction(I,J)       |
|                            |
|o4 = true                   |
+----------------------------+
|i5 : isReduction(J,I)       |
|                            |
|o5 = false                  |
+----------------------------+
|i6 : isReduction(I,I)       |
|                            |
|o6 = true                   |
+----------------------------+
|i7 : g = I_0                |
|                            |
|      3                     |
|o7 = x                      |
|                            |
|o7 : S                      |
+----------------------------+
|i8 : isReduction(I,J,g)     |
|                            |
|o8 = true                   |
+----------------------------+
|i9 : isReduction(J,I,g)     |
|                            |
|o9 = false                  |
+----------------------------+
|i10 : isReduction(I,I,g)    |
|                            |
|o10 = true                  |
+----------------------------+

See also
========

  * minimalReduction -- Find a minimal reduction of an
    ideal
  * reductionNumber -- Reduction number of one ideal
    with respect to another

Ways to use isReduction:
========================

  * "isReduction(Ideal,Ideal)"
  * "isReduction(Ideal,Ideal,RingElement)"
  * "isReduction(Module,Module)"
  * "isReduction(Module,Module,RingElement)"

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

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

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

The source of this document is in ReesAlgebra.m2:1245:0.

jacobianDual -- Computes the 'jacobian dual', part of a method of finding generators for Rees Algebra ideals
************************************************************************************************************

  * Usage:
        psi = jacobianDual phi
        psi = jacobianDual(phi, X, T)
  * Inputs:
      * phi, a matrix (Macaulay2Doc), presentation matrix of an
        ideal
      * X, a matrix (Macaulay2Doc), row matrix generating an
        ideal that contains the entries of phi
      * T, a matrix (Macaulay2Doc), row matrix of variables that
        will be generators of the Rees algebra of I
  * Optional inputs (Macaulay2Doc),:
      * Variable,
        => ..., default value "w", Choose name for variables in the created
        ring
  * Outputs:
      * psi, a matrix (Macaulay2Doc), the `Jacobian Dual', which
        satisfies $T*phi = X*psi$

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

Let I be an ideal of R and let phi be the presentation matrix of I as a module.
The symmetric algebra of I has the form

$Sym_R(I) = R[T_0..T_m]/ideal(T*phi)$

where the T_i correspond to the generators of I. If $X =
matrix\{\{x_1..x_n\}\}$, with x_i \in{} R, and ideal X contains the entries of
the matrix phi, then there is a matrix psi defined over R[T_0..T_m], called the
Jacobian Dual of phi with respect to X, such that $T*phi = X*psi$. (the matrix
psi is generally not unique; Macaulay2 computes it using Groebner division with
remainder.)

In the form psi = jacobianDual phi, a new ring ST := S[T_0..T_m] is created,
and the vector X is set to the variables of R. The result is returned as a
matrix over ST. To do the computation in a ring previously defined computed,
use the form psi = jacobianDual(phi, X,T); in this case, the matrices phi, X, T
should all be defined over the same ring ST, the matrix T should be a row of
variables of ST, and the matrix phi should have entries in a subring not
involving the entries of T.

If I is an ideal of grade >=1 and ideal X contains a nonzerodivisor of R (which
will be automatic if I has finite projective dimension) then ideal X has grade
>= 1 on the Rees algebra. Since ideal(T*phi) is contained in the defining ideal
of the Rees algebra, the vector X is annihilated by the matrix psi when
regarded over the Rees algebra. If also the number of relations of I is >= the
number of generators of I, this implies that the maximal minors of psi
annihilate  the x_i as elements of the Rees algebra, and thus that the maximal
minors of psi are inside the ideal of the Rees algebra. In very favorable
circumstances, one may even have the equality reesIdeal I = ideal(T*phi)+ideal
minors(psi): For example:

Theorem (S. Morey and B. Ulrich, Rees Algebras of Ideals with Low Codimension,
Proc. Am. Math. Soc. 124 (1996) 3653–3661): Let R be a local Gorenstein ring
with infinite residue field, let I be a perfect ideal of grade 2 with n
generators, and let phi be the presentation matrix of I. Let ell = ell(I) be
the analytic spread. Suppose that I satisfies the condition G_{ell} or,
equivalently, that the n-p sized minors of phi have codimension >p for 1<= p <
ell. The following conditions are equivalent:

1) reesAlgebra I is Cohen-Macaulay and I_(n-ell)(phi) = I_1(phi)^{n-ell} 2)
reductionNumber I < ell and I_(n+1-ell)(phi) = I_1(phi)^{n+1-ell} 3) reesIdeal
I = symmetricAlgebraIdeal I + minors(n, jacobianDual phi)

We start with the presentation matrix phi of an (n+1)-generator perfect ideal
Such that the first row consists of the n variables of the ring, and the rest
of whose rows are reasonably general (in this case random quadrics):

+-----------------------------------------------------------------------------+
|i1 : setRandomSeed 0                                                         |
| -- setting random seed to 0                                                 |
|                                                                             |
|o1 = 0                                                                       |
+-----------------------------------------------------------------------------+
|i2 : n=3;                                                                    |
+-----------------------------------------------------------------------------+
|i3 : kk = ZZ/101;                                                            |
+-----------------------------------------------------------------------------+
|i4 : S = kk[a_0..a_(n-2)];                                                   |
+-----------------------------------------------------------------------------+
|i5 : phi' = map(S^(n),S^(n-1), (i,j) -> if i == 0 then a_j else random(2,S));|
|                                                                             |
|             3      2                                                        |
|o5 : Matrix S  <-- S                                                         |
+-----------------------------------------------------------------------------+
|i6 : I = minors(n-1,phi');                                                   |
|                                                                             |
|o6 : Ideal of S                                                              |
+-----------------------------------------------------------------------------+
|i7 : betti (F = res I)                                                       |
|                                                                             |
|            0 1 2                                                            |
|o7 = total: 1 3 2                                                            |
|         0: 1 . .                                                            |
|         1: . . .                                                            |
|         2: . 2 .                                                            |
|         3: . 1 2                                                            |
|                                                                             |
|o7 : BettiTally                                                              |
+-----------------------------------------------------------------------------+
|i8 : phi = F.dd_2;                                                           |
|                                                                             |
|             3      2                                                        |
|o8 : Matrix S  <-- S                                                         |
+-----------------------------------------------------------------------------+
|i9 : jphi = jacobianDual phi                                                 |
|                                                                             |
|o9 = {0, 1} | (11a_0-37a_1)w_1                                               |
|     {0, 1} | (-11a_0-34a_1)w_0-46a_1w_1+14w_2                               |
|     ------------------------------------------------------------------------|
|     w_2                              |                                      |
|     11a_1w_0+(-11a_0-30a_1)w_1+18w_2 |                                      |
|                                                                             |
|                       2                2                                    |
|o9 : Matrix (S[w ..w ])  <-- (S[w ..w ])                                     |
|                0   2            0   2                                       |
+-----------------------------------------------------------------------------+

We first compute the analytic spread ell and the reduction number r

+------------------------------------------------+
|i10 : ell = analyticSpread I                    |
|                                                |
|o10 = 2                                         |
+------------------------------------------------+
|i11 : r = reductionNumber(I, minimalReduction I)|
|                                                |
|o11 = 1                                         |
+------------------------------------------------+

Now we can check the condition G_{ell}, first probabilistically

+----------------------+
|i12 : whichGm I >= ell|
|                      |
|o12 = true            |
+----------------------+

and now deterministically

+----------------------------------------------------------------+
|i13 : apply(toList(1..ell-1), p-> {p+1, codim minors(n-p, phi)})|
|                                                                |
|o13 = {{2, 2}}                                                  |
|                                                                |
|o13 : List                                                      |
+----------------------------------------------------------------+

We now check the three equivalent conditions of the Morey-Ulrich Theorem. Note
that since ell = n-1 in this case, the second part of conditions 1,2 is
vacuously satisfied, and since r<ell, the conditions must all be satisfied. We
first check that reesAlgebra I is Cohen-Macaulay:

+--------------------------+
|i14 : reesI = reesIdeal I;|
|                          |
|o14 : Ideal of S[w ..w ]  |
|                  0   2   |
+--------------------------+
|i15 : codim reesI         |
|                          |
|o15 = 2                   |
+--------------------------+
|i16 : betti res reesI     |
|                          |
|             0 1 2        |
|o16 = total: 1 3 2        |
|          0: 1 . .        |
|          1: . . .        |
|          2: . 2 .        |
|          3: . 1 2        |
|                          |
|o16 : BettiTally          |
+--------------------------+

Finally, we wish to see that reesIdeal I is generated by the ideal of the
symmetric algebra together with the jacobian dual:

+-----------------------------------------------------------------------------+
|i17 : psi = jacobianDual phi                                                 |
|                                                                             |
|o17 = {0, 1} | (11a_0-37a_1)w_1                                              |
|      {0, 1} | (-11a_0-34a_1)w_0-46a_1w_1+14w_2                              |
|      -----------------------------------------------------------------------|
|      w_2                              |                                     |
|      11a_1w_0+(-11a_0-30a_1)w_1+18w_2 |                                     |
|                                                                             |
|                        2                2                                   |
|o17 : Matrix (S[w ..w ])  <-- (S[w ..w ])                                    |
|                 0   2            0   2                                      |
+-----------------------------------------------------------------------------+

We now compute the ideal J of the symmetric algebra; the call symmetricAlgebra
I would return the ideal over a different ring, so we do it by hand:

+-----------------------------------------------------------------------------+
|i18 : ST = ring psi                                                          |
|                                                                             |
|o18 = ST                                                                     |
|                                                                             |
|o18 : PolynomialRing                                                         |
+-----------------------------------------------------------------------------+
|i19 : T = vars ST                                                            |
|                                                                             |
|o19 = | w_0 w_1 w_2 |                                                        |
|                                                                             |
|               1       3                                                     |
|o19 : Matrix ST  <-- ST                                                      |
+-----------------------------------------------------------------------------+
|i20 : J = ideal(T*promote(phi, ST))                                          |
|                                                                             |
|                            2          2               2                 2   |
|o20 = ideal ((- 11a a  - 34a )w  + (11a  - 37a a  - 46a )w  + 14a w , 11a w  |
|                   0 1      1  0       0      0 1      1  1      1 2     1 0 |
|      -----------------------------------------------------------------------|
|                       2                                                     |
|      + (- 11a a  - 30a )w  + (a  + 18a )w )                                 |
|              0 1      1  1     0      1  2                                  |
|                                                                             |
|o20 : Ideal of ST                                                            |
+-----------------------------------------------------------------------------+
|i21 : betti res J                                                            |
|                                                                             |
|             0 1 2                                                           |
|o21 = total: 1 2 1                                                           |
|          0: 1 . .                                                           |
|          1: . . .                                                           |
|          2: . 2 .                                                           |
|          3: . . .                                                           |
|          4: . . 1                                                           |
|                                                                             |
|o21 : BettiTally                                                             |
+-----------------------------------------------------------------------------+
|i22 : J1 = minors(ell, psi)                                                  |
|                                                                             |
|                        2              2             2  2                    |
|o22 = ideal((20a a  - 3a )w w  + (- 20a  - 24a a  - a )w  + (11a  + 34a )w w |
|                0 1     1  0 1         0      0 1    1  1       0      1  0 2|
|      -----------------------------------------------------------------------|
|                                2                                            |
|      + (- 4a  - 14a )w w  - 14w )                                           |
|             0      1  1 2      2                                            |
|                                                                             |
|o22 : Ideal of ST                                                            |
+-----------------------------------------------------------------------------+
|i23 : betti (G = res trim (J+J1))                                            |
|                                                                             |
|             0 1 2                                                           |
|o23 = total: 1 3 2                                                           |
|          0: 1 . .                                                           |
|          1: . . .                                                           |
|          2: . 2 .                                                           |
|          3: . 1 2                                                           |
|                                                                             |
|o23 : BettiTally                                                             |
+-----------------------------------------------------------------------------+
|i24 : betti res reesIdeal I                                                  |
|                                                                             |
|             0 1 2                                                           |
|o24 = total: 1 3 2                                                           |
|          0: 1 . .                                                           |
|          1: . . .                                                           |
|          2: . 2 .                                                           |
|          3: . 1 2                                                           |
|                                                                             |
|o24 : BettiTally                                                             |
+-----------------------------------------------------------------------------+

The name Jacobian Dual comes from the case where phi is a matrix of linear
forms the x_i are the variables of R, and the generators of I are forms, all of
the same degree D; in this case Euler's formula sum(df_i/dx_j*xj) = Df can be
used to express the entries of psi in terms of the derivatives of the entries
of phi, at least when the degrees of the columns of phi are nonzero in the
coefficient field.

Explicitly, let x_1,...,x_n be the variables of R, and let phi be a
presentation matrix for I. Since all the f_i have the same degree, if follows
that, for each j, the entries phi_(i,j) will all have the same degree, say D_j
= deg phi_(i,j). Let ST be the polynomial ring R[T_0..T_m], where the T_i
correspond to f_i, and let X=matrix{{x_1,...,x_n}}, and T=matrix{{T_0,...,T_m}}
be row matrices over ST. In this case, by Euler's formula, we may take

psi_{k,j}=(1/D_j)*sum_i(d phi_{i,j}/d x_k*T_i),

Caveat
======

The division with remainder step is usually fast, but if this ever becomes a
bottleneck it would be possible to test for the degree condition and use
Euler's formula in the case where it applies.

See also
========

  * whichGm -- Largest Gm satisfied by an ideal
  * expectedReesIdeal -- symmetric algebra ideal plus
    jacobian dual
  * reesAlgebra -- Compute the defining ideal of the Rees
    Algebra
  * reesIdeal -- Compute the defining ideal of the Rees
    Algebra
  * reesIdeal -- Compute the defining ideal of the Rees
    Algebra
  * specialFiberIdeal -- Special fiber of a blowup

Ways to use jacobianDual:
=========================

  * "jacobianDual(Matrix)"
  * "jacobianDual(Matrix,Matrix,Matrix)"

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

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

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

The source of this document is in ReesAlgebra.m2:1913:0.

minimalReduction -- Find a minimal reduction of an ideal
********************************************************

  * Usage:
        J = minimalReduction I
  * Inputs:
      * I, an ideal (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * BasisElementLimit,
        => ...,
        default value infinity, Bound the number of Groebner basis elements to
        compute in the saturation step
      * DegreeLimit,
        => ..., default value {}, Bound the degrees considered in the
        saturation step. Defaults to infinity
      * MinimalGenerators,
        => ...,
        default value true, Whether the saturation step returns minimal
        generators
      * PairLimit, =>
        ..., default value infinity, Bound the number of s-pairs considered in
        the saturation step
      * Strategy, => ...,
        default value null, Choose a strategy for the saturation step
      * Tries, =>
        ..., default value 20, Set the number of random tries to compute a
        minimal reduction
  * Outputs:
      * an ideal (Macaulay2Doc), A minimal reduction of I (defined
        below)

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

minimalReduction takes an ideal I that is homogeneous or inhomogeneous (in the
latter case the ideal is to be regarded as an ideal in the localization of the
polynomial ring at the origin.). It returns an ideal $J$ contained in $I$, with
a minimal number of generators such that $I$ is integrally dependent on $J$.
This minimal number is called the analyticSpread of $I$.

This routine is probabilistic: $J$ is computed as the ideal generated by the
right number of random linear combinations of the generators of $I$. However,
the routine checks rigorously that the output ideal is a reduction, and tries
probabilistically again if it is not. If it cannot find a minimal reduction
after a certain number of tries, it returns an error. The number of tries
defaults to 20, but can be set with the optional argument
minimalReduction(...,Tries=>...).

To say that $I$ is integrally dependent on $J$ means that $JI^k = I^{k+1}$ for
some non-negative integer $k$.  The smallest $k$ with this property is called
the reduction number of $I$, and can be computed with reductionNumber,
i.

See the book Huneke, Craig; Swanson, Irena: Integral closure of ideals, rings,
and modules. London Mathematical Society Lecture Note Series, 336. Cambridge
University Press, Cambridge, 2006. for further information.

+-----------------------------------------------------------------------------+
|i1 : kk = ZZ/101;                                                            |
+-----------------------------------------------------------------------------+
|i2 : S = kk[a..c];                                                           |
+-----------------------------------------------------------------------------+
|i3 : m = ideal vars S;                                                       |
|                                                                             |
|o3 : Ideal of S                                                              |
+-----------------------------------------------------------------------------+
|i4 : i = (ideal"a,b")*m+ideal"c3"                                            |
|                                                                             |
|             2                  2        3                                   |
|o4 = ideal (a , a*b, a*c, a*b, b , b*c, c )                                  |
|                                                                             |
|o4 : Ideal of S                                                              |
+-----------------------------------------------------------------------------+
|i5 : analyticSpread i                                                        |
|                                                                             |
|o5 = 3                                                                       |
+-----------------------------------------------------------------------------+
|i6 : minimalReduction i                                                      |
|                                                                             |
|                 3      2              2                       3      2      |
|o6 = ideal (- 10c  + 24a  + 36a*b + 19b  - 30a*c + 19b*c, - 16c  - 29a  -    |
|     ------------------------------------------------------------------------|
|                2                       3      2              2              |
|     37a*b - 24b  - 22a*c - 38b*c, - 18c  + 39a  + 40a*b - 47b  + 34a*c -    |
|     ------------------------------------------------------------------------|
|     39b*c)                                                                  |
|                                                                             |
|o6 : Ideal of S                                                              |
+-----------------------------------------------------------------------------+

Note that this is inhomogeneous-- it is generated by 3 random linear
combinations of the generators of i. There is no homogeneous ideal with just 3
generators on which i is integrally dependent.

+-----------------------------------------------------------------------------+
|i7 : f = gens i                                                              |
|                                                                             |
|o7 = | a2 ab ac ab b2 bc c3 |                                                |
|                                                                             |
|             1      7                                                        |
|o7 : Matrix S  <-- S                                                         |
+-----------------------------------------------------------------------------+
|i8 : for a from 0 to 3 do(jhom:=ideal (f*random(source f, S^{3-a:-2,a:-3})); |
|false                                                                        |
|false                                                                        |
|false                                                                        |
|false                                                                        |
|-----------------------------------------------------------------------------|
|print(i^6 == (i^5)*jhom))                                                    |
+-----------------------------------------------------------------------------+

Caveat
======

It is possible that the ideal returned is not a minimal reduction, due to the
probabilistic nature of the routine.  This will be addressed in a future
version of the package.  The larger the size of the base field, the less likely
this is to happen.

See also
========

  * analyticSpread -- Compute the analytic spread of a
    module or ideal
  * reductionNumber -- Reduction number of one ideal
    with respect to another
  * whichGm -- Largest Gm satisfied by an ideal

Ways to use minimalReduction:
=============================

  * "minimalReduction(Ideal)"

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

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

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

The source of this document is in ReesAlgebra.m2:1676:0.

minimalReduction(...,BasisElementLimit=>...) -- Bound the number of Groebner basis elements to compute in the saturation step
*****************************************************************************************************************************

  * Usage:
        reesIdeal(...,BasisElementLimit => X)

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

Here X is a positive integer. Each of these functions computes the Rees Algebra
using a saturation step, and the optional argument causes the saturation
process to stop after that number of s-pairs is found. This is described in the
documentation node for saturate (Saturation).

See also
========

  * reesIdeal -- Compute the defining ideal of the Rees
    Algebra
  * reesAlgebra -- Compute the defining ideal of the Rees
    Algebra
  * isLinearType -- Determine whether module has linear
    type
  * isReduction -- Determine whether an ideal is a
    reduction
  * associatedGradedRing -- The normal cone of a
    subscheme
  * multiplicity -- Compute the Hilbert-Samuel
    multiplicity of an ideal
  * specialFiberIdeal -- Special fiber of a blowup
  * specialFiber -- Special fiber of a blowup
  * analyticSpread -- Compute the analytic spread of a
    module or ideal
  * distinguished -- Compute the distinguished
    subvarieties of a pullback, intersection or cone
  * minimalReduction -- Find a minimal reduction of an
    ideal
  * saturate (missing documentation)

Functions with optional argument named BasisElementLimit:
=========================================================

  * "gb(...,BasisElementLimit=>...)" -- see gb (Macaulay2Doc), --
    compute a Gröbner basis
  * intersectInP(...,BasisElementLimit=>...)
    -- Option for
    intersectInP
  * "analyticSpread(...,BasisElementLimit=>...)"
  * "associatedGradedRing(...,BasisElementLimit=>...)"
  * "distinguished(...,BasisElementLimit=>...)"
  * "isLinearType(...,BasisElementLimit=>...)"
  * "isReduction(...,BasisElementLimit=>...)"
  * minimalReduction(...,BasisElementLimit=>...)
    -- Bound
    the number of Groebner basis elements to compute in the saturation step
  * "multiplicity(...,BasisElementLimit=>...)"
  * "normalCone(Ideal,BasisElementLimit=>...)"
  * "normalCone(Ideal,RingElement,BasisElementLimit=>...)"
  * "reesAlgebra(...,BasisElementLimit=>...)"
  * "reesIdeal(...,BasisElementLimit=>...)"
  * "specialFiber(...,BasisElementLimit=>...)"
  * "specialFiberIdeal(...,BasisElementLimit=>...)"
  * quotient(...,BasisElementLimit=>...) (missing documentation)
  * saturate(...,BasisElementLimit=>...) (missing documentation)
  * "syz(...,BasisElementLimit=>...)" -- see syz(Matrix) (Macaulay2Doc),
    -- compute the syzygy matrix

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

  * Default value: infinity (Macaulay2Doc),
  * Function: minimalReduction, -- Find a minimal
    reduction of an ideal
  * Option key: BasisElementLimit (Macaulay2Doc), -- an
    optional argument
-------------------------------------------------------------------------------

The source of this document is in ReesAlgebra.m2:2133:0.

minimalReduction(...,Tries=>...) -- Set the number of random tries to compute a minimal reduction
*************************************************************************************************

  * Usage:
        minimalReduction(..., Tries => 20)

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

When searching for a minimal reduction of an ideal over a field with a small
number of elements, random choices of generators are often not good enough.
This option controls how many times the routine will try new random choices
before giving up and reporting an error.

+----------------------------------------+
|i1 : setRandomSeed(314159268)           |
| -- setting random seed to 314159268    |
|                                        |
|o1 = 314159268                          |
+----------------------------------------+
|i2 : kk=ZZ/2                            |
|                                        |
|o2 = kk                                 |
|                                        |
|o2 : QuotientRing                       |
+----------------------------------------+
|i3 : S = kk[a,b,c,d];                   |
+----------------------------------------+
|i4 : I = monomialCurveIdeal(S, {1,3,4});|
|                                        |
|o4 : Ideal of S                         |
+----------------------------------------+
|i5 : minimalReduction(I, Tries=>30);    |
|                                        |
|o5 : Ideal of S                         |
+----------------------------------------+

Functions with optional argument named Tries:
=============================================

  * minimalReduction(...,Tries=>...)
    -- Set the number of
    random tries to compute a minimal reduction

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

  * Default value: 20
  * Function: minimalReduction, -- Find a minimal
    reduction of an ideal
  * Option key: Tries (Macaulay2Doc), -- an optional argument
-------------------------------------------------------------------------------

The source of this document is in ReesAlgebra.m2:882:0.

multiplicity -- Compute the Hilbert-Samuel multiplicity of an ideal
*******************************************************************

  * Usage:
        multiplicity I
        multiplicity(I,f)
  * Inputs:
      * I, an ideal (Macaulay2Doc),
      * f, a ring element (Macaulay2Doc), optional argument,
        if given it should be a non-zero divisor in the ideal I
  * Optional inputs (Macaulay2Doc),:
      * BasisElementLimit,
        => ...,
        default value infinity, Bound the number of Groebner basis elements to
        compute in the saturation step
      * DegreeLimit,
        => ..., default value {}, Bound the degrees considered in the
        saturation step. Defaults to infinity
      * MinimalGenerators,
        => ...,
        default value true, Whether the saturation step returns minimal
        generators
      * PairLimit, =>
        ..., default value infinity, Bound the number of s-pairs considered in
        the saturation step
      * Strategy, => ...,
        default value null, Choose a strategy for the saturation step
      * Variable,
        => ..., default value "w", Option for intersectInP
  * Outputs:
      * an integer (Macaulay2Doc), the normalized leading coefficient
        of the Hilbert-Samuel polynomial of $I$

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

Given an ideal $I\subset{} R$, ``multiplicity I'' returns the degree of the
normal cone of $I$.  When $R/I$ has finite length this is the sum of the Samuel
multiplicities of $I$ at the various localizations of $R$. When $I$ is
generated by a complete intersection, this is the length of the ring $R/I$ but
in general it is greater. For example,

+-------------------------------+
|i1 : R=ZZ/101[x,y]             |
|                               |
|o1 = R                         |
|                               |
|o1 : PolynomialRing            |
+-------------------------------+
|i2 : I = ideal(x^3, x^2*y, y^3)|
|                               |
|             3   2    3        |
|o2 = ideal (x , x y, y )       |
|                               |
|o2 : Ideal of R                |
+-------------------------------+
|i3 : multiplicity I            |
|                               |
|o3 = 9                         |
+-------------------------------+
|i4 : degree I                  |
|                               |
|o4 = 7                         |
+-------------------------------+

Caveat
======

The normal cone is computed using the Rees algebra, thus may be slow.

Ways to use multiplicity:
=========================

  * "multiplicity(Ideal)"
  * "multiplicity(Ideal,RingElement)"

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

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

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

The source of this document is in ReesAlgebra.m2:1316:0.

PlaneCurveSingularities -- Using the Rees Algebra to resolve plane curve singularities
**************************************************************************************

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

The Rees Algebra of an ideal I appeared classically as the bihomogeneous
coordinate ring of the blow up of the ideal I, used in resolution of
singularities. Though the general case is still out of reach, we illustrate
with some simple examples of plane curve singularities.

First the cusp in the affine plane

+------------------------------------------+
|i1 : R = ZZ/32003[x,y]                    |
|                                          |
|o1 = R                                    |
|                                          |
|o1 : PolynomialRing                       |
+------------------------------------------+
|i2 : cusp = ideal(x^2-y^3)                |
|                                          |
|              3    2                      |
|o2 = ideal(- y  + x )                     |
|                                          |
|o2 : Ideal of R                           |
+------------------------------------------+
|i3 : mm = radical ideal singularLocus cusp|
|                                          |
|o3 = ideal (y, x)                         |
|                                          |
|o3 : Ideal of R                           |
+------------------------------------------+

The cusp is singular at the maximal ideal (x,y), so we blow that up, and
examine the ``total transform'', that is, the ideal generated by the x^2-y^3 in
the Rees algebra.

+------------------------------------------+
|i4 : B = first flattenRing reesAlgebra(mm)|
|                                          |
|o4 = B                                    |
|                                          |
|o4 : QuotientRing                         |
+------------------------------------------+

Application of first flattenRing serves to make B a quotient of the polynomial
ring T in 4 variables; otherwise it would be a quotient of R[w_0,w_1], which
Macaulay2 treats as a polynomial ring in 2 variables, and the calculation of
the singular locus later on would be wrong.

+----------------------------------------------------------+
|i5 : vars B                                               |
|                                                          |
|o5 = | w_0 w_1 x y |                                      |
|                                                          |
|             1      4                                     |
|o5 : Matrix B  <-- B                                      |
+----------------------------------------------------------+
|i6 : proj = map(B,R,{x,y})                                |
|                                                          |
|o6 = map (B, R, {x, y})                                   |
|                                                          |
|o6 : RingMap B <-- R                                      |
+----------------------------------------------------------+
|i7 : totalTransform = proj cusp                           |
|                                                          |
|              3    2                                      |
|o7 = ideal(- y  + x )                                     |
|                                                          |
|o7 : Ideal of B                                           |
+----------------------------------------------------------+
|i8 : D = decompose totalTransform                         |
|                                                          |
|                            3    2     2         2     2  |
|o8 = {ideal (y, x), ideal (y  - x , w y  - w x, w y - w )}|
|                                     0      1    0     1  |
|                                                          |
|o8 : List                                                 |
+----------------------------------------------------------+
|i9 : D/codim                                              |
|                                                          |
|o9 = {1, 1}                                               |
|                                                          |
|o9 : List                                                 |
+----------------------------------------------------------+

We see that the reduced preimage consists of two codimension 1 components, the
`exceptional divisor', which is the pullback of the point we blew up, (x,y),
and the `strict transform'. The two components meet in a double point in the 2
dimensional variety B \subset{} A^2\times P^1. We have to saturate with respect
to the irrelevant ideal to understand what's going on.

+---------------------------------------------+
|i10 : irrelB = ideal(B_0,B_1)                |
|                                             |
|o10 = ideal (w , w )                         |
|              0   1                          |
|                                             |
|o10 : Ideal of B                             |
+---------------------------------------------+
|i11 : doublePoint = saturate(D_0+D_1, irrelB)|
|                                             |
|                    2                        |
|o11 = ideal (y, x, w )                       |
|                    1                        |
|                                             |
|o11 : Ideal of B                             |
+---------------------------------------------+
|i12 : codim doublePoint                      |
|                                             |
|o12 = 2                                      |
+---------------------------------------------+
|i13 : degree doublePoint                     |
|                                             |
|o13 = 2                                      |
+---------------------------------------------+

We can see the multiplicities of these components by comparing their degrees to
the degrees of the reduced components

+------------------------------------------------------------------+
|i14 : divisors = primaryDecomposition totalTransform              |
|                                                                  |
|               2        2           3    2     2         2     2  |
|o14 = {ideal (y , x*y, x ), ideal (y  - x , w y  - w x, w y - w )}|
|                                             0      1    0     1  |
|                                                                  |
|o14 : List                                                        |
+------------------------------------------------------------------+
|i15 : strictTransform = divisors_0                                |
|                                                                  |
|              2        2                                          |
|o15 = ideal (y , x*y, x )                                         |
|                                                                  |
|o15 : Ideal of B                                                  |
+------------------------------------------------------------------+
|i16 : exceptional = divisors_1                                    |
|                                                                  |
|              3    2     2         2     2                        |
|o16 = ideal (y  - x , w y  - w x, w y - w )                       |
|                       0      1    0     1                        |
|                                                                  |
|o16 : Ideal of B                                                  |
+------------------------------------------------------------------+
|i17 : divisors/(i-> degree i/degree radical i)                    |
|                                                                  |
|o17 = {2, 1}                                                      |
|                                                                  |
|o17 : List                                                        |
+------------------------------------------------------------------+

That is, the exceptional component occurs with multiplicity 2 (in general we'd
get the exceptional component with multiplicity equal to the multiplicity of
the singular point we blew up.)

We next investigate the singularity of the strict transform. We want to see it
as a curve in P^1 x A^2, that is, as an ideal of  T = kk[w_0,w_1,x,y]

+------------------------------------------------------------------+
|i18 : T = ring ideal B                                            |
|                                                                  |
|o18 = T                                                           |
|                                                                  |
|o18 : PolynomialRing                                              |
+------------------------------------------------------------------+
|i19 : irrelT  = ideal(w_0,w_1)                                    |
|                                                                  |
|o19 = ideal (w , w )                                              |
|              0   1                                               |
|                                                                  |
|o19 : Ideal of T                                                  |
+------------------------------------------------------------------+
|i20 : sing = saturate(ideal singularLocus strictTransform, irrelT)|
|                                                                  |
|o20 = ideal (y, x)                                                |
|                                                                  |
|o20 : Ideal of T                                                  |
+------------------------------------------------------------------+

We see that the singular locus of the strict transform is empty; that is, the
curve is smooth.

We could have made the computation in B as well:

+-------------------------------------------------------------------+
|i21 : jacobianMatrix = diff(vars B, transpose gens strictTransform)|
|                                                                   |
|o21 = {0, -2} | 0 0 0  2y |                                        |
|      {0, -2} | 0 0 y  x  |                                        |
|      {0, -2} | 0 0 2x 0  |                                        |
|                                                                   |
|              3      4                                             |
|o21 : Matrix B  <-- B                                              |
+-------------------------------------------------------------------+
|i22 : codim strictTransform                                        |
|                                                                   |
|o22 = 1                                                            |
+-------------------------------------------------------------------+
|i23 : jacobianIdeal  = strictTransform+ minors(1,jacobianMatrix)   |
|                                                                   |
|              2        2                                           |
|o23 = ideal (y , x*y, x , y, 2x, 2y, x)                            |
|                                                                   |
|o23 : Ideal of B                                                   |
+-------------------------------------------------------------------+
|i24 : sing1 = saturate(jacobianIdeal, irrelB)                      |
|                                                                   |
|o24 = ideal (y, x)                                                 |
|                                                                   |
|o24 : Ideal of B                                                   |
+-------------------------------------------------------------------+

Next we look at the desingularization of a tacnode; it will take two blowups.

+------------------------------------------------------------+
|i25 : R = ZZ/32003[x,y]                                     |
|                                                            |
|o25 = R                                                     |
|                                                            |
|o25 : PolynomialRing                                        |
+------------------------------------------------------------+
|i26 : tacnode = ideal(x^2-y^4)                              |
|                                                            |
|               4    2                                       |
|o26 = ideal(- y  + x )                                      |
|                                                            |
|o26 : Ideal of R                                            |
+------------------------------------------------------------+
|i27 : sing = ideal singularLocus tacnode                    |
|                                                            |
|                4    2         3                            |
|o27 = ideal (- y  + x , 2x, -4y )                           |
|                                                            |
|o27 : Ideal of R                                            |
+------------------------------------------------------------+
|i28 : mm = radical sing                                     |
|                                                            |
|o28 = ideal (y, x)                                          |
|                                                            |
|o28 : Ideal of R                                            |
+------------------------------------------------------------+
|i29 : B1 = first flattenRing reesAlgebra mm                 |
|                                                            |
|o29 = B1                                                    |
|                                                            |
|o29 : QuotientRing                                          |
+------------------------------------------------------------+
|i30 : proj1 = map(B1,R,{x,y})                               |
|                                                            |
|o30 = map (B1, R, {x, y})                                   |
|                                                            |
|o30 : RingMap B1 <-- R                                      |
+------------------------------------------------------------+
|i31 : irrelB1 = ideal(w_0,w_1)                              |
|                                                            |
|o31 = ideal (w , w )                                        |
|              0   1                                         |
|                                                            |
|o31 : Ideal of B1                                           |
+------------------------------------------------------------+
|i32 : totalTransform1 = proj1 tacnode                       |
|                                                            |
|               4    2                                       |
|o32 = ideal(- y  + x )                                      |
|                                                            |
|o32 : Ideal of B1                                           |
+------------------------------------------------------------+
|i33 : netList (D1 = decompose totalTransform1)              |
|                                                            |
|      +------------------------+                            |
|o33 = |ideal (y, x)            |                            |
|      +------------------------+                            |
|      |        2               |                            |
|      |ideal (y  - x, w y - w )|                            |
|      |                0     1 |                            |
|      +------------------------+                            |
|      |        2               |                            |
|      |ideal (y  + x, w y + w )|                            |
|      |                0     1 |                            |
|      +------------------------+                            |
+------------------------------------------------------------+
|i34 : strictTransform1 = saturate(totalTransform1,proj1 mm )|
|                                                            |
|              4    2     3         2 2    2                 |
|o34 = ideal (y  - x , w y  - w x, w y  - w )                |
|                       0      1    0      1                 |
|                                                            |
|o34 : Ideal of B1                                           |
+------------------------------------------------------------+

Here proj1 mm is the ideal of the exceptional divisor. The strict transform is,
by definition, obtained by saturating it away, The strict transform of the
tacnode is not yet smooth: it consists of two smooth branches, meeting
transversely at a point:

+----------------------------------------------+
|i35 : strictTransform1 == intersect(D1_1,D1_2)|
|                                              |
|o35 = true                                    |
+----------------------------------------------+
|i36 : degree (D1_1+D1_2)                      |
|                                              |
|o36 = 1                                       |
+----------------------------------------------+

We compute the singular point of the strict transform:

+-----------------------------------------------------------------+
|i37 : mm1 = sub(radical ideal singularLocus strictTransform1, B1)|
|                                                                 |
|o37 = ideal (y, x, w )                                           |
|                    1                                            |
|                                                                 |
|o37 : Ideal of B1                                                |
+-----------------------------------------------------------------+

...and blow up B1, getting a variety in P^2 x P^1 x A^2

+-----------------------------------------------------------------------------+
|i38 : B2 = first flattenRing reesAlgebra(mm1, Variable => p)                 |
|                                                                             |
|o38 = B2                                                                     |
|                                                                             |
|o38 : QuotientRing                                                           |
+-----------------------------------------------------------------------------+
|i39 : vars B2                                                                |
|                                                                             |
|o39 = | p_0 p_1 p_2 w_0 w_1 x y |                                            |
|                                                                             |
|               1       7                                                     |
|o39 : Matrix B2  <-- B2                                                      |
+-----------------------------------------------------------------------------+
|i40 : proj2 = map(B2,B1,{w_0,w_1,x,y})                                       |
|                                                                             |
|o40 = map (B2, B1, {w , w , x, y})                                           |
|                     0   1                                                   |
|                                                                             |
|o40 : RingMap B2 <-- B1                                                      |
+-----------------------------------------------------------------------------+
|i41 : irrelB2 = ideal(p_0,p_1,p_2)                                           |
|                                                                             |
|o41 = ideal (p , p , p )                                                     |
|              0   1   2                                                      |
|                                                                             |
|o41 : Ideal of B2                                                            |
+-----------------------------------------------------------------------------+
|i42 : irrelTot = (proj2 irrelB1) *irrelB2                                    |
|                                                                             |
|o42 = ideal (p w , p y, p w , p y, p x, p w )                                |
|              0 0   2    2 0   2    2    2 1                                 |
|                                                                             |
|o42 : Ideal of B2                                                            |
+-----------------------------------------------------------------------------+
|i43 : totalTransform2 = saturate(proj2 proj1 tacnode, irrelTot)              |
|                                                                             |
|              4    2       3    2    2 2 2    4                              |
|o43 = ideal (y  - x , p p y  - p x, p p y  - p )                             |
|                       0 1      1    0 1      1                              |
|                                                                             |
|o43 : Ideal of B2                                                            |
+-----------------------------------------------------------------------------+
|i44 : exceptional2 = saturate(proj2 proj1 mm, irrelTot)                      |
|                                                                             |
|o44 = ideal (y, x, p )                                                       |
|                    1                                                        |
|                                                                             |
|o44 : Ideal of B2                                                            |
+-----------------------------------------------------------------------------+
|i45 : netList(D2 = decompose totalTransform2)                                |
|                                                                             |
|      +---------------------------------------------+                        |
|o45 = |ideal (y, x, w , p )                         |                        |
|      |              1   1                          |                        |
|      +---------------------------------------------+                        |
|      |ideal (y, x, p , p )                         |                        |
|      |              1   0                          |                        |
|      +---------------------------------------------+                        |
|      |        2                                    |                        |
|      |ideal (y  - x, w y - w , p y - p , p w  - p )|                        |
|      |                0     1   0     1   0 0    2 |                        |
|      +---------------------------------------------+                        |
|      |        2                                    |                        |
|      |ideal (y  + x, w y + w , p y + p , p w  + p )|                        |
|      |                0     1   0     1   0 0    2 |                        |
|      +---------------------------------------------+                        |
+-----------------------------------------------------------------------------+
|i46 : netList(E2 = decompose exceptional2)                                   |
|                                                                             |
|      +--------------------+                                                 |
|o46 = |ideal (y, x, w , p )|                                                 |
|      |              1   1 |                                                 |
|      +--------------------+                                                 |
|      |ideal (y, x, p , p )|                                                 |
|      |              1   0 |                                                 |
|      +--------------------+                                                 |
+-----------------------------------------------------------------------------+
|i47 : strictTransform2 = saturate(totalTransform2, exceptional2)             |
|                                                                             |
|              4    2     3         2 2    2     3             2           2  |
|o47 = ideal (y  - x , w y  - w x, w y  - w , p y  - p x, p w y  - p x, p w y |
|                       0      1    0      1   0      1    0 0      2    0 0  |
|      -----------------------------------------------------------------------|
|               2 2    2   2             2 2    2                             |
|      - p w , p y  - p , p w y - p p , p w  - p )                            |
|         2 1   0      1   0 0     1 2   0 0    2                             |
|                                                                             |
|o47 : Ideal of B2                                                            |
+-----------------------------------------------------------------------------+

We compute the singular locus once again:

+--------------------------------------------------------+
|i48 : time sing2 = ideal singularLocus strictTransform2;|
| -- used 1.12994s (cpu); 0.948275s (thread); 0s (gc)    |
|                                                        |
|                 ZZ                                     |
|o48 : Ideal of -----[p ..p , w ..w , x..y]              |
|               32003  0   2   0   1                     |
+--------------------------------------------------------+
|i49 : saturate(sing2, sub(irrelTot, ring sing2))        |
|                                                        |
|o49 = ideal 1                                           |
|                                                        |
|                 ZZ                                     |
|o49 : Ideal of -----[p ..p , w ..w , x..y]              |
|               32003  0   2   0   1                     |
+--------------------------------------------------------+

The answer, ideal 1 shows that the second blowup desingularizes the tacnode.

It is not necessary to repeatedly blow up closed points: there is always a
single ideal that can be blown up to desingularize (Hartshorne, Algebraic
Geometry,Thm II.7.17). In this case, blowing-up (x,y^2) desingularizes the
tacnode x^2-y^4 in a single step.

+--------------------------------------------------------------+
|i50 : R = ZZ/32003[x,y];                                      |
+--------------------------------------------------------------+
|i51 : tacnode = ideal(x^2-y^4);                               |
|                                                              |
|o51 : Ideal of R                                              |
+--------------------------------------------------------------+
|i52 : mm = ideal(x,y^2);                                      |
|                                                              |
|o52 : Ideal of R                                              |
+--------------------------------------------------------------+
|i53 : B = first flattenRing reesAlgebra mm;                   |
+--------------------------------------------------------------+
|i54 : irrelB = ideal(w_0,w_1);                                |
|                                                              |
|o54 : Ideal of B                                              |
+--------------------------------------------------------------+
|i55 : proj = map(B,R,{x,y});                                  |
|                                                              |
|o55 : RingMap B <-- R                                         |
+--------------------------------------------------------------+
|i56 : totalTransform = proj tacnode                           |
|                                                              |
|               4    2                                         |
|o56 = ideal(- y  + x )                                        |
|                                                              |
|o56 : Ideal of B                                              |
+--------------------------------------------------------------+
|i57 : netList (D = decompose totalTransform)                  |
|                                                              |
|      +-----------------------+                               |
|o57 = |ideal (y, x)           |                               |
|      +-----------------------+                               |
|      |        2              |                               |
|      |ideal (y  - x, w  - w )|                               |
|      |                0    1 |                               |
|      +-----------------------+                               |
|      |        2              |                               |
|      |ideal (y  + x, w  + w )|                               |
|      |                0    1 |                               |
|      +-----------------------+                               |
+--------------------------------------------------------------+
|i58 : exceptional = proj mm                                   |
|                                                              |
|                 2                                            |
|o58 = ideal (x, y )                                           |
|                                                              |
|o58 : Ideal of B                                              |
+--------------------------------------------------------------+
|i59 : strictTransform = saturate(totalTransform, exceptional);|
|                                                              |
|o59 : Ideal of B                                              |
+--------------------------------------------------------------+
|i60 : netList decompose strictTransform                       |
|                                                              |
|      +-----------------------+                               |
|      |        2              |                               |
|o60 = |ideal (y  - x, w  - w )|                               |
|      |                0    1 |                               |
|      +-----------------------+                               |
|      |        2              |                               |
|      |ideal (y  + x, w  + w )|                               |
|      |                0    1 |                               |
|      +-----------------------+                               |
+--------------------------------------------------------------+
|i61 : sing0 = sub(ideal singularLocus strictTransform, B);    |
|                                                              |
|o61 : Ideal of B                                              |
+--------------------------------------------------------------+
|i62 : sing = saturate(sing0,irrelB)                           |
|                                                              |
|o62 = ideal 1                                                 |
|                                                              |
|o62 : Ideal of B                                              |
+--------------------------------------------------------------+

So this single blowup is already nonsingular.

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

The object PlaneCurveSingularities, is a
symbol (Macaulay2Doc).

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

The source of this document is in ReesAlgebra.m2:2394:0.

reductionNumber -- Reduction number of one ideal with respect to another
************************************************************************

  * Usage:
        k = reductionNumber(I,J)
  * Inputs:
      * I, an ideal (Macaulay2Doc),
      * J, an ideal (Macaulay2Doc),
  * Outputs:
      * an integer (Macaulay2Doc), the reduction number of $I$
        (defined below)

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

The function reductionNumber takes a pair of ideals $I,J$, homogeneous or
inhomogeneous (in the latter case $I$ and $J$ are to be regarded as ideals in
the localization of the polynomial ring at the origin.). The ideal $J$ must be
a reduction of $I$ (that is, $J\subset{} I$ and $I$ is integrally dependent on
$J$. This condition is checked by the function isReduction.
It returns the smallest integer $k$ such that $JI^k = I^{k+1}$.

For further information, see the book: Huneke, Craig; Swanson, Irena: Integral
closure of ideals, rings, and modules, London Mathematical Society Lecture Note
Series, 336. Cambridge University Press, Cambridge, 2006.

+-----------------------------------------------------------------------------+
|i1 : setRandomSeed()                                                         |
| -- initializing random seed                                                 |
+-----------------------------------------------------------------------------+
|i2 : kk = ZZ/32003;                                                          |
+-----------------------------------------------------------------------------+
|i3 : S = kk[a..c];                                                           |
+-----------------------------------------------------------------------------+
|i4 : m = ideal vars S;                                                       |
|                                                                             |
|o4 : Ideal of S                                                              |
+-----------------------------------------------------------------------------+
|i5 : i = (ideal"a,b")*m+ideal"c3"                                            |
|                                                                             |
|             2                  2        3                                   |
|o5 = ideal (a , a*b, a*c, a*b, b , b*c, c )                                  |
|                                                                             |
|o5 : Ideal of S                                                              |
+-----------------------------------------------------------------------------+
|i6 : analyticSpread i                                                        |
|                                                                             |
|o6 = 3                                                                       |
+-----------------------------------------------------------------------------+
|i7 : j=minimalReduction i                                                    |
|                                                                             |
|                 3         2                   2                             |
|o7 = ideal (1851c  + 10356a  - 4344a*b + 15816b  + 11567a*c - 15394b*c,      |
|     ------------------------------------------------------------------------|
|           3         2                  2                            3       |
|     11958c  - 11142a  + 6959a*b - 2765b  - 15224a*c - 2094b*c, 8725c  +     |
|     ------------------------------------------------------------------------|
|          2                   2                                              |
|     1278a  + 4039a*b - 10543b  - 7124a*c - 12085b*c)                        |
|                                                                             |
|o7 : Ideal of S                                                              |
+-----------------------------------------------------------------------------+
|i8 : reductionNumber (i,j)                                                   |
|                                                                             |
|o8 = 1                                                                       |
+-----------------------------------------------------------------------------+

Caveat
======

It is possible for the routine to not finish in reasonable time, due to the
probabilistic nature of the routine.  What happens is that the routine
minimalReduction, occasionally, but rarely, returns an ideal
which is not a minimal reduction.  In this case, the routine goes into an
infinite loop. This will be addressed in a future version of the package.  In
the meantime, simply interrupt the routine, and restart the computation.

See also
========

  * analyticSpread -- Compute the analytic spread of a
    module or ideal
  * minimalReduction -- Find a minimal reduction of an
    ideal
  * whichGm -- Largest Gm satisfied by an ideal

Ways to use reductionNumber:
============================

  * "reductionNumber(Ideal,Ideal)"

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

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

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

The source of this document is in ReesAlgebra.m2:1727:0.

reesAlgebra -- Compute the defining ideal of the Rees Algebra
*************************************************************

  * Usage:
        A = reesAlgebra M
        A = reesAlgebra(M,f)
  * Inputs:
      * M, a module (Macaulay2Doc), or an ideal (Macaulay2Doc),
        of a quotient polynomial ring $R$
      * f, a ring element (Macaulay2Doc), any
        non-zerodivisor in ideal or the first Fitting ideal of the module.
        Optional
  * Optional inputs (Macaulay2Doc),:
      * BasisElementLimit,
        => ...,
        default value infinity, Bound the number of Groebner basis elements to
        compute in the saturation step
      * DegreeLimit,
        => ..., default value {}, Bound the degrees considered in the
        saturation step. Defaults to infinity
      * Jacobian (missing documentation) => ..., default value false,
      * MinimalGenerators,
        => ...,
        default value true, Whether the saturation step returns minimal
        generators
      * PairLimit, =>
        ..., default value infinity, Bound the number of s-pairs considered in
        the saturation step
      * Strategy, => ...,
        default value null, Choose a strategy for the saturation step
      * Variable,
        => ..., default value "w", Choose name for variables in the created
        ring
  * Outputs:
      * A, a ring (Macaulay2Doc), defining the Rees algebra of M

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

If $M$ is an ideal or module over a ring $R$, and $F\to M$ is a surjection from
a free module, then reesAlgebra(M) returns the ring $Sym(F)/J$, where $J =
reesIdeal(M)$.

In the following example, we find the Rees Algebra of a monomial curve
singularity.  We also demonstrate the use of reesIdeal,
symmetricKernel, isLinearType,
normalCone(Ideal,RingElement),
associatedGradedRing, specialFiberIdeal.

+-----------------------------------------------------------------------------+
|i1 : S = QQ[x_0..x_3]                                                        |
|                                                                             |
|o1 = S                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : i = monomialCurveIdeal(S,{3,7,8})                                       |
|                                                                             |
|               2    2       3      3   3      2 2   5      4   5    3        |
|o2 = ideal (x x  - x x , x x  - x x , x x  - x x , x  - x x , x  - x x x )   |
|             0 2    1 3   1 2    0 3   1 2    0 3   2    1 3   1    0 2 3    |
|                                                                             |
|o2 : Ideal of S                                                              |
+-----------------------------------------------------------------------------+
|i3 : I = reesIdeal i;                                                        |
|                                                                             |
|o3 : Ideal of S[w ..w ]                                                      |
|                 0   4                                                       |
+-----------------------------------------------------------------------------+
|i4 : reesIdeal(i, Variable=>v)                                               |
|                                                                             |
|                                   3      2              2      2      2     |
|o4 = ideal (x x v  - x v  + x v , x v  + x v  - x v , x x v  - x v  + x v ,  |
|             1 2 0    0 1    3 2   3 0    2 1    1 3   0 3 0    1 1    2 2   |
|     ------------------------------------------------------------------------|
|      2        2            3                     3                       2 2|
|     x x v  - x v  + x v , x v  + x x v  - x v , x v  - x x v  + x v , x x v |
|      0 3 0    1 2    2 4   2 0    1 3 1    0 3   1 0    0 2 2    3 4   2 3 0|
|     ------------------------------------------------------------------------|
|          2                2      2             2      2 2  2                |
|     - x v  + v v , x x x v  - x v  + v v , (x x x  + x x )v  - x x v v  +   |
|        1 1    2 3   0 1 3 0    2 2    1 4    0 2 3    1 3  0    1 2 1 2     |
|     ------------------------------------------------------------------------|
|     v v )                                                                   |
|      3 4                                                                    |
|                                                                             |
|o4 : Ideal of S[v ..v ]                                                      |
|                 0   4                                                       |
+-----------------------------------------------------------------------------+
|i5 : I=reesIdeal(i,i_0);                                                     |
|                                                                             |
|o5 : Ideal of S[w ..w ]                                                      |
|                 0   4                                                       |
+-----------------------------------------------------------------------------+
|i6 : (J=symmetricKernel gens i);                                             |
|                                                                             |
|o6 : Ideal of S[w ..w ]                                                      |
|                 0   4                                                       |
+-----------------------------------------------------------------------------+
|i7 : isLinearType(i,i_0)                                                     |
|                                                                             |
|o7 = false                                                                   |
+-----------------------------------------------------------------------------+
|i8 : isLinearType i                                                          |
|                                                                             |
|o8 = false                                                                   |
+-----------------------------------------------------------------------------+
|i9 : reesAlgebra (i,i_0)                                                     |
|                                                                             |
|                                                                             |
|                                                                             |
|o9 = ------------------------------------------------------------------------|
|                             3      2              2      2      2     2     |
|     (x x w  - x w  + x w , x w  + x w  - x w , x x w  - x w  + x w , x x w  |
|       1 2 0    0 1    3 2   3 0    2 1    1 3   0 3 0    1 1    2 2   0 3 0 |
|                                                                             |
|o9 : QuotientRing                                                            |
|-----------------------------------------------------------------------------|
|                              S[w ..w ]                                      |
|                                 0   4                                       |
|-----------------------------------------------------------------------------|
|   2            3                     3                       2 2      2     |
|- x w  + x w , x w  + x x w  - x w , x w  - x x w  + x w , x x w  - x w  + w |
|   1 2    2 4   2 0    1 3 1    0 3   1 0    0 2 2    3 4   2 3 0    1 1    2|
|-----------------------------------------------------------------------------|
|----------------------------------------------------------------             |
|           2      2             2      2 2  2                                |
|w , x x x w  - x w  + w w , (x x x  + x x )w  - x x w w  + w w )             |
| 3   0 1 3 0    2 2    1 4    0 2 3    1 3  0    1 2 1 2    3 4              |
+-----------------------------------------------------------------------------+
|i10 : trim ideal normalCone (i, i_0)                                         |
|                                                                             |
|                2    2       3      3   3      2 2   5      4   5    3       |
|o10 = ideal (x x  - x x , x x  - x x , x x  - x x , x  - x x , x  - x x x )  |
|              0 2    1 3   1 2    0 3   1 2    0 3   2    1 3   1    0 2 3   |
|                                                                             |
|                                                                             |
|                                                                             |
|o10 : Ideal of --------------------------------------------------------------|
|                                       3      2              2      2      2 |
|               (x x w  - x w  + x w , x w  + x w  - x w , x x w  - x w  + x w|
|                 1 2 0    0 1    3 2   3 0    2 1    1 3   0 3 0    1 1    2 |
|-----------------------------------------------------------------------------|
|                                        S[w ..w ]                            |
|                                           0   4                             |
|-----------------------------------------------------------------------------|
|    2        2            3                     3                       2 2  |
| , x x w  - x w  + x w , x w  + x x w  - x w , x w  - x x w  + x w , x x w  -|
|2   0 3 0    1 2    2 4   2 0    1 3 1    0 3   1 0    0 2 2    3 4   2 3 0  |
|-----------------------------------------------------------------------------|
|--------------------------------------------------------------------------   |
|    2                2      2             2      2 2  2                      |
| x w  + w w , x x x w  - x w  + w w , (x x x  + x x )w  - x x w w  + w w )   |
|  1 1    2 3   0 1 3 0    2 2    1 4    0 2 3    1 3  0    1 2 1 2    3 4    |
+-----------------------------------------------------------------------------+
|i11 : trim ideal associatedGradedRing (i,i_0)                                |
|                                                                             |
|                2    2       3      3   3      2 2   5      4   5    3       |
|o11 = ideal (x x  - x x , x x  - x x , x x  - x x , x  - x x , x  - x x x )  |
|              0 2    1 3   1 2    0 3   1 2    0 3   2    1 3   1    0 2 3   |
|                                                                             |
|                                                                             |
|                                                                             |
|o11 : Ideal of --------------------------------------------------------------|
|                                       3      2              2      2      2 |
|               (x x w  - x w  + x w , x w  + x w  - x w , x x w  - x w  + x w|
|                 1 2 0    0 1    3 2   3 0    2 1    1 3   0 3 0    1 1    2 |
|-----------------------------------------------------------------------------|
|                                        S[w ..w ]                            |
|                                           0   4                             |
|-----------------------------------------------------------------------------|
|    2        2            3                     3                       2 2  |
| , x x w  - x w  + x w , x w  + x x w  - x w , x w  - x x w  + x w , x x w  -|
|2   0 3 0    1 2    2 4   2 0    1 3 1    0 3   1 0    0 2 2    3 4   2 3 0  |
|-----------------------------------------------------------------------------|
|--------------------------------------------------------------------------   |
|    2                2      2             2      2 2  2                      |
| x w  + w w , x x x w  - x w  + w w , (x x x  + x x )w  - x x w w  + w w )   |
|  1 1    2 3   0 1 3 0    2 2    1 4    0 2 3    1 3  0    1 2 1 2    3 4    |
+-----------------------------------------------------------------------------+
|i12 : trim specialFiberIdeal (i,i_0)                                         |
|                                                                             |
|o12 = ideal (w w , w w , w w )                                               |
|              3 4   1 4   2 3                                                |
|                                                                             |
|o12 : Ideal of QQ[w ..w ]                                                    |
|                   0   4                                                     |
+-----------------------------------------------------------------------------+

See also
========

  * reesIdeal -- Compute the defining ideal of the Rees
    Algebra
  * symmetricKernel -- Compute the Rees ring of the
    image of a matrix

Ways to use reesAlgebra:
========================

  * "reesAlgebra(Ideal)"
  * "reesAlgebra(Ideal,RingElement)"
  * "reesAlgebra(Module)"
  * "reesAlgebra(Module,RingElement)"

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

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

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

The source of this document is in ReesAlgebra.m2:1152:0.

reesIdeal -- Compute the defining ideal of the Rees Algebra
***********************************************************

  * Usage:
        reesIdeal M
        reesIdeal(M,f)
  * Inputs:
      * M, a module (Macaulay2Doc), or an ideal (Macaulay2Doc),
        of a quotient polynomial ring $R$
      * f, a ring element (Macaulay2Doc), any
        non-zerodivisor in ideal or the first Fitting ideal of the module.
        Optional
  * Optional inputs (Macaulay2Doc),:
      * BasisElementLimit,
        => ...,
        default value infinity, Bound the number of Groebner basis elements to
        compute in the saturation step
      * DegreeLimit,
        => ..., default value {}, Bound the degrees considered in the
        saturation step. Defaults to infinity
      * Jacobian => ..., default value false
      * MinimalGenerators,
        => ...,
        default value true, Whether the saturation step returns minimal
        generators
      * PairLimit, =>
        ..., default value infinity, Bound the number of s-pairs considered in
        the saturation step
      * Strategy, => ...,
        default value null, Choose a strategy for the saturation step
      * Trim => ..., default value true
      * Variable,
        => ..., default value "w", Choose name for variables in the created
        ring
  * Outputs:
      * an ideal (Macaulay2Doc), defining the Rees algebra of M

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

This routine gives the user a choice between two methods for finding the
defining ideal of the Rees algebra of an ideal or module $M$ over a ring $R$:
The command reesIdeal(M) computes a versal embedding $g: M\to G$ and a
surjection $f: F\to M$ and returns the result of symmetricKernel(gf).

When M is an ideal (the usual case) or in characteristic 0, the same ideal can
be computed by an alternate method that is often faster. If the user knows a
non-zerodivisor $a\in{} R$ such that $M[a^{-1}$ is a free module (for example,
when M is an ideal, any non-zerodivisor $a \in{} M$ then it is often much
faster to compute reesIdeal(M,a) which computes the saturation of the defining
ideal of the symmetric algebra of M with respect to a. This gives the correct
answer even under the slightly weaker hypothesis that $M[a^{-1}]$ is of linear
type. (See also isLinearType.)

+-----------------------------------------------------------------------------+
|i1 : kk = ZZ/101;                                                            |
+-----------------------------------------------------------------------------+
|i2 : S=kk[x_0..x_4];                                                         |
+-----------------------------------------------------------------------------+
|i3 : i= trim monomialCurveIdeal(S,{2,3,5,6})                                 |
|                                                                             |
|                          2                       3      2     2      2   2  |
|o3 = ideal (x x  - x x , x  - x x , x x  - x x , x  - x x , x x  - x x , x x |
|             2 3    1 4   2    0 4   1 2    0 3   3    2 4   1 3    0 4   1 3|
|     ------------------------------------------------------------------------|
|                3    2                                                       |
|     - x x x , x  - x x )                                                    |
|        0 2 4   1    0 4                                                     |
|                                                                             |
|o3 : Ideal of S                                                              |
+-----------------------------------------------------------------------------+
|i4 : time V1 = reesIdeal i;                                                  |
| -- used 0.0347757s (cpu); 0.0324961s (thread); 0s (gc)                      |
|                                                                             |
|o4 : Ideal of S[w ..w ]                                                      |
|                 0   6                                                       |
+-----------------------------------------------------------------------------+
|i5 : time V2 = reesIdeal(i,i_0);                                             |
| -- used 0.179634s (cpu); 0.178828s (thread); 0s (gc)                        |
|                                                                             |
|o5 : Ideal of S[w ..w ]                                                      |
|                 0   6                                                       |
+-----------------------------------------------------------------------------+

The following example shows how we handle degrees

+-------------------------------------------------------+
|i6 : S=kk[a,b,c]                                       |
|                                                       |
|o6 = S                                                 |
|                                                       |
|o6 : PolynomialRing                                    |
+-------------------------------------------------------+
|i7 : m=matrix{{a,0},{b,a},{0,b}}                       |
|                                                       |
|o7 = | a 0 |                                           |
|     | b a |                                           |
|     | 0 b |                                           |
|                                                       |
|             3      2                                  |
|o7 : Matrix S  <-- S                                   |
+-------------------------------------------------------+
|i8 : i=minors(2,m)                                     |
|                                                       |
|             2        2                                |
|o8 = ideal (a , a*b, b )                               |
|                                                       |
|o8 : Ideal of S                                        |
+-------------------------------------------------------+
|i9 : time I1 = reesIdeal i;                            |
| -- used 0.0253258s (cpu); 0.0241168s (thread); 0s (gc)|
|                                                       |
|o9 : Ideal of S[w ..w ]                                |
|                 0   2                                 |
+-------------------------------------------------------+
|i10 : time I2 = reesIdeal(i,i_0);                      |
| -- used 0.0104108s (cpu); 0.010121s (thread); 0s (gc) |
|                                                       |
|o10 : Ideal of S[w ..w ]                               |
|                  0   2                                |
+-------------------------------------------------------+
|i11 : transpose gens I1                                |
|                                                       |
|o11 = {-1, -3} | aw_1-bw_2    |                        |
|      {-1, -3} | aw_0-bw_1    |                        |
|      {-2, -4} | w_1^2-w_0w_2 |                        |
|                                                       |
|                        3                1             |
|o11 : Matrix (S[w ..w ])  <-- (S[w ..w ])              |
|                 0   2            0   2                |
+-------------------------------------------------------+
|i12 : transpose gens I2                                |
|                                                       |
|o12 = {-1, -3} | aw_1-bw_2    |                        |
|      {-1, -3} | aw_0-bw_1    |                        |
|      {-2, -4} | w_1^2-w_0w_2 |                        |
|                                                       |
|                        3                1             |
|o12 : Matrix (S[w ..w ])  <-- (S[w ..w ])              |
|                 0   2            0   2                |
+-------------------------------------------------------+

Investigating plane curve singularities:

Proj of the Rees algebra of I \subset{} R is the blowup of I in spec R. Thus
the Rees algebra is a basic construction in resolution of singularities. Here
we work out a simple case:

+-----------------------------------------------------------------------------+
|i13 : R = ZZ/32003[x,y]                                                      |
|                                                                             |
|o13 = R                                                                      |
|                                                                             |
|o13 : PolynomialRing                                                         |
+-----------------------------------------------------------------------------+
|i14 : I = ideal(x,y)                                                         |
|                                                                             |
|o14 = ideal (x, y)                                                           |
|                                                                             |
|o14 : Ideal of R                                                             |
+-----------------------------------------------------------------------------+
|i15 : cusp = ideal(x^2-y^3)                                                  |
|                                                                             |
|               3    2                                                        |
|o15 = ideal(- y  + x )                                                       |
|                                                                             |
|o15 : Ideal of R                                                             |
+-----------------------------------------------------------------------------+
|i16 : RI = reesIdeal(I)                                                      |
|                                                                             |
|o16 = ideal(x*w  - y*w )                                                     |
|               0      1                                                      |
|                                                                             |
|o16 : Ideal of R[w ..w ]                                                     |
|                  0   1                                                      |
+-----------------------------------------------------------------------------+
|i17 : S = ring RI                                                            |
|                                                                             |
|o17 = S                                                                      |
|                                                                             |
|o17 : PolynomialRing                                                         |
+-----------------------------------------------------------------------------+
|i18 : totalTransform = substitute(cusp, S) + RI                              |
|                                                                             |
|                3    2                                                       |
|o18 = ideal (- y  + x , x*w  - y*w )                                         |
|                           0      1                                          |
|                                                                             |
|o18 : Ideal of S                                                             |
+-----------------------------------------------------------------------------+
|i19 : D = decompose totalTransform -- the components are the strict transform|
|                                                                             |
|                                          3    2   2              2    2     |
|o19 = {ideal (y, x), ideal (x*w  - y*w , y  - x , y w  - x*w , y*w  - w )}   |
|                               0      1              0      1     0    1     |
|                                                                             |
|o19 : List                                                                   |
|-----------------------------------------------------------------------------|
|of the cuspidal curve and the exceptional curve                              |
+-----------------------------------------------------------------------------+
|i20 : totalTransform = first flattenRing totalTransform                      |
|                                                                             |
|                3    2                                                       |
|o20 = ideal (- y  + x , w x - w y)                                           |
|                         0     1                                             |
|                                                                             |
|                 ZZ                                                          |
|o20 : Ideal of -----[w ..w , x..y]                                           |
|               32003  0   1                                                  |
+-----------------------------------------------------------------------------+
|i21 : L = primaryDecomposition totalTransform                                |
|                                                                             |
|               2        2                                 3    2     2       |
|o21 = {ideal (y , x*y, x , w x - w y), ideal (w x - w y, y  - x , w y  - w x,|
|                            0     1            0     1             0      1  |
|      -----------------------------------------------------------------------|
|       2     2                                                               |
|      w y - w )}                                                             |
|       0     1                                                               |
|                                                                             |
|o21 : List                                                                   |
+-----------------------------------------------------------------------------+
|i22 : apply(L, i -> (degree i)/(degree radical i))                           |
|                                                                             |
|o22 = {2, 1}                                                                 |
|                                                                             |
|o22 : List                                                                   |
+-----------------------------------------------------------------------------+

The total transform of the cusp contains the exceptional divisor with
multiplicity two.  The strict transform of the cusp is a smooth curve but is
tangent to the exceptional divisor

+-------------------------------------------+
|i23 : use ring L_0                         |
|                                           |
|        ZZ                                 |
|o23 = -----[w ..w , x..y]                  |
|      32003  0   1                         |
|                                           |
|o23 : PolynomialRing                       |
+-------------------------------------------+
|i24 : singular = ideal(singularLocus(L_0));|
|                                           |
|                 ZZ                        |
|o24 : Ideal of -----[w ..w , x..y]         |
|               32003  0   1                |
+-------------------------------------------+
|i25 : SL = saturate(singular, ideal(x,y)); |
|                                           |
|                 ZZ                        |
|o25 : Ideal of -----[w ..w , x..y]         |
|               32003  0   1                |
+-------------------------------------------+
|i26 : saturate(SL, ideal(w_0,w_1))         |
|                                           |
|o26 = ideal 1                              |
|                                           |
|                 ZZ                        |
|o26 : Ideal of -----[w ..w , x..y]         |
|               32003  0   1                |
+-------------------------------------------+

This shows that the strict transform is smooth.

See also
========

  * symmetricKernel -- Compute the Rees ring of the
    image of a matrix
  * reesAlgebra -- Compute the defining ideal of the Rees
    Algebra

Ways to use reesIdeal:
======================

  * "reesIdeal(Ideal)"
  * "reesIdeal(Ideal,RingElement)"
  * "reesIdeal(Module)"
  * "reesIdeal(Module,RingElement)"

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

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

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

The source of this document is in ReesAlgebra.m2:1105:0.

reesIdeal(...,DegreeLimit=>...) -- Bound the degrees considered in the saturation step. Defaults to infinity
************************************************************************************************************

  * Usage:
        reesIdeal(...,DegreeLimit => X)

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

where X is a non-negative integer. Stop computation at degree X. This is
described in the documentation node for saturate (Saturation).
Here X is a positive integer. Each of these functions computes the Rees Algebra
using a saturation step, and the optional argument causes the saturation
process to stop after that number of s-pairs is found. This is described in the
documentation node for saturate (Saturation).

See also
========

  * reesIdeal -- Compute the defining ideal of the Rees
    Algebra
  * reesAlgebra -- Compute the defining ideal of the Rees
    Algebra
  * isLinearType -- Determine whether module has linear
    type
  * isReduction -- Determine whether an ideal is a
    reduction
  * associatedGradedRing -- The normal cone of a
    subscheme
  * multiplicity -- Compute the Hilbert-Samuel
    multiplicity of an ideal
  * specialFiberIdeal -- Special fiber of a blowup
  * specialFiber -- Special fiber of a blowup
  * analyticSpread -- Compute the analytic spread of a
    module or ideal
  * distinguished -- Compute the distinguished
    subvarieties of a pullback, intersection or cone
  * minimalReduction -- Find a minimal reduction of an
    ideal
  * saturate (missing documentation)

Functions with optional argument named DegreeLimit:
===================================================

  * "compose(Module,Module,Module,DegreeLimit=>...)" -- see compose (Macaulay2Doc),
    -- composition as a pairing on Hom-modules
  * "End(...,DegreeLimit=>...)" -- see End (Macaulay2Doc), -- module
    of endomorphisms
  * "gb(...,DegreeLimit=>...)" -- see gb (Macaulay2Doc), -- compute a
    Gröbner basis
  * "Hom(...,DegreeLimit=>...)" -- see Hom (Macaulay2Doc), -- module
    of homomorphisms
  * "homomorphism'(...,DegreeLimit=>...)" -- see homomorphism' (Macaulay2Doc),
    -- get the element of Hom from a homomorphism
  * "intersectInP(...,DegreeLimit=>...)" -- see
    intersectInP(...,BasisElementLimit=>...),
    -- Option for
    intersectInP
  * kernel(...,DegreeLimit=>...) (Macaulay2Doc)
    -- stop after
    finding enough elements of a subring
  * "minimalBetti(...,DegreeLimit=>...)" -- see minimalBetti (Macaulay2Doc),
    -- minimal betti numbers of (the minimal free
    resolution of) a homogeneous ideal or module
  * "pushForward(...,DegreeLimit=>...)" -- see
    pushForward(RingMap,Module) (Macaulay2Doc),
    -- compute the pushforward
    of a module along a ring map
  * quotient(...,DegreeLimit=>...) (missing documentation)
  * "analyticSpread(...,DegreeLimit=>...)"
  * "associatedGradedRing(...,DegreeLimit=>...)"
  * "distinguished(...,DegreeLimit=>...)"
  * "isLinearType(...,DegreeLimit=>...)"
  * "isReduction(...,DegreeLimit=>...)"
  * "minimalReduction(...,DegreeLimit=>...)"
  * "multiplicity(...,DegreeLimit=>...)"
  * "normalCone(Ideal,DegreeLimit=>...)"
  * "normalCone(Ideal,RingElement,DegreeLimit=>...)"
  * "reesAlgebra(...,DegreeLimit=>...)"
  * reesIdeal(...,DegreeLimit=>...)
    -- Bound the degrees
    considered in the saturation step. Defaults to infinity
  * "specialFiber(...,DegreeLimit=>...)"
  * "specialFiberIdeal(...,DegreeLimit=>...)"
  * saturate(...,DegreeLimit=>...) (missing documentation)
  * "syz(...,DegreeLimit=>...)" -- see syz(Matrix) (Macaulay2Doc),
    -- compute the syzygy matrix

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

  * Default value: {}
  * Function: reesIdeal, -- Compute the defining ideal of the
    Rees Algebra
  * Option key: DegreeLimit (Macaulay2Doc), -- an optional
    argument
-------------------------------------------------------------------------------

The source of this document is in ReesAlgebra.m2:2174:0.

reesIdeal(...,MinimalGenerators=>...) -- Whether the saturation step returns minimal generators
***********************************************************************************************

  * Usage:
        reesIdeal(...,MinimalGenerators => X)

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

Here X is of type boolean. Each of these functions involves the computation of
a Rees algebra, which may involve a saturation step. This optional argument
determines whether or not the output of the saturation step will be forced to
have a minimal generating set. This is described in the documentation node for
saturate (Saturation).

See also
========

  * reesIdeal -- Compute the defining ideal of the Rees
    Algebra
  * reesAlgebra -- Compute the defining ideal of the Rees
    Algebra
  * isLinearType -- Determine whether module has linear
    type
  * isReduction -- Determine whether an ideal is a
    reduction
  * associatedGradedRing -- The normal cone of a
    subscheme
  * multiplicity -- Compute the Hilbert-Samuel
    multiplicity of an ideal
  * specialFiberIdeal -- Special fiber of a blowup
  * specialFiber -- Special fiber of a blowup
  * analyticSpread -- Compute the analytic spread of a
    module or ideal
  * distinguished -- Compute the distinguished
    subvarieties of a pullback, intersection or cone
  * minimalReduction -- Find a minimal reduction of an
    ideal
  * saturate (missing documentation)

Functions with optional argument named MinimalGenerators:
=========================================================

  * "compose(Module,Module,Module,MinimalGenerators=>...)" -- see
    compose (Macaulay2Doc), -- composition as a pairing on Hom-modules
  * decompose(Ideal,MinimalGenerators=>...) (missing documentation)
  * "End(...,MinimalGenerators=>...)" -- see End (Macaulay2Doc), --
    module of endomorphisms
  * "Hom(...,MinimalGenerators=>...)" -- see Hom (Macaulay2Doc), --
    module of homomorphisms
  * "homomorphism'(...,MinimalGenerators=>...)" -- see homomorphism' (Macaulay2Doc),
    -- get the element of Hom from a homomorphism
  * "intersect(Ideal,Ideal,MinimalGenerators=>...)" -- see
    intersect(Ideal,Ideal) (Macaulay2Doc), --
    compute an intersection of a sequence of ideals or modules
  * "intersect(Module,Module,MinimalGenerators=>...)" -- see
    intersect(Ideal,Ideal) (Macaulay2Doc), --
    compute an intersection of a sequence of ideals or modules
  * "intersectInP(...,MinimalGenerators=>...)" -- see
    intersectInP(...,BasisElementLimit=>...),
    -- Option for
    intersectInP
  * quotient'(...,MinimalGenerators=>...) (missing documentation)
  * quotient(...,MinimalGenerators=>...) (missing documentation)
  * "analyticSpread(...,MinimalGenerators=>...)"
  * "associatedGradedRing(...,MinimalGenerators=>...)"
  * "distinguished(...,MinimalGenerators=>...)"
  * "isLinearType(...,MinimalGenerators=>...)"
  * "isReduction(...,MinimalGenerators=>...)"
  * "minimalReduction(...,MinimalGenerators=>...)"
  * "multiplicity(...,MinimalGenerators=>...)"
  * "normalCone(Ideal,MinimalGenerators=>...)"
  * "normalCone(Ideal,RingElement,MinimalGenerators=>...)"
  * "reesAlgebra(...,MinimalGenerators=>...)"
  * reesIdeal(...,MinimalGenerators=>...)
    -- Whether the
    saturation step returns minimal generators
  * "specialFiber(...,MinimalGenerators=>...)"
  * "specialFiberIdeal(...,MinimalGenerators=>...)"
  * saturate(...,MinimalGenerators=>...) (missing documentation)
  * truncate(InfiniteNumber,InfiniteNumber,Matrix,MinimalGenerators=>...)
    (missing documentation)
  * truncate(InfiniteNumber,Thing,MinimalGenerators=>...) (missing
    documentation)
  * truncate(List,Ideal,MinimalGenerators=>...) (missing documentation)
  * truncate(List,List,Matrix,MinimalGenerators=>...) (missing documentation)
  * truncate(List,Matrix,MinimalGenerators=>...) (missing documentation)
  * truncate(List,Module,MinimalGenerators=>...) (missing documentation)
  * truncate(List,Ring,MinimalGenerators=>...) (missing documentation)
  * truncate(Nothing,InfiniteNumber,Matrix,MinimalGenerators=>...) (missing
    documentation)
  * truncate(Nothing,List,Matrix,MinimalGenerators=>...) (missing
    documentation)
  * truncate(Nothing,ZZ,Matrix,MinimalGenerators=>...) (missing documentation)
  * truncate(ZZ,Ideal,MinimalGenerators=>...) (missing documentation)
  * truncate(ZZ,Matrix,MinimalGenerators=>...) (missing documentation)
  * truncate(ZZ,Module,MinimalGenerators=>...) (missing documentation)
  * truncate(ZZ,Ring,MinimalGenerators=>...) (missing documentation)
  * truncate(ZZ,ZZ,Matrix,MinimalGenerators=>...) (missing documentation)

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

  * Default value: true (Macaulay2Doc),
  * Function: reesIdeal, -- Compute the defining ideal of the
    Rees Algebra
  * Option key: MinimalGenerators (Macaulay2Doc), --
    whether to compute minimal generators and return a trimmed set of
    generators
-------------------------------------------------------------------------------

The source of this document is in ReesAlgebra.m2:2094:0.

reesIdeal(...,PairLimit=>...) -- Bound the number of s-pairs considered in the saturation step
**********************************************************************************************

  * Usage:
        reesIdeal(...,PairLimit => X)

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

Here X is a positive integer. Each of these functions computes the Rees Algebra
using a saturation step, and the optional argument causes the saturation
process to stop after that number of s-pairs is found. This is described in the
documentation node for saturate (Saturation).

See also
========

  * reesIdeal -- Compute the defining ideal of the Rees
    Algebra
  * reesAlgebra -- Compute the defining ideal of the Rees
    Algebra
  * isLinearType -- Determine whether module has linear
    type
  * isReduction -- Determine whether an ideal is a
    reduction
  * associatedGradedRing -- The normal cone of a
    subscheme
  * multiplicity -- Compute the Hilbert-Samuel
    multiplicity of an ideal
  * specialFiberIdeal -- Special fiber of a blowup
  * specialFiber -- Special fiber of a blowup
  * analyticSpread -- Compute the analytic spread of a
    module or ideal
  * distinguished -- Compute the distinguished
    subvarieties of a pullback, intersection or cone
  * minimalReduction -- Find a minimal reduction of an
    ideal
  * saturate (missing documentation)

Functions with optional argument named PairLimit:
=================================================

  * "gb(...,PairLimit=>...)" -- see gb (Macaulay2Doc), -- compute a
    Gröbner basis
  * "intersectInP(...,PairLimit=>...)" -- see
    intersectInP(...,BasisElementLimit=>...),
    -- Option for
    intersectInP
  * "pushForward(...,PairLimit=>...)" -- see pushForward(RingMap,Module) (Macaulay2Doc),
    -- compute the pushforward
    of a module along a ring map
  * quotient(...,PairLimit=>...) (missing documentation)
  * "analyticSpread(...,PairLimit=>...)"
  * "associatedGradedRing(...,PairLimit=>...)"
  * "distinguished(...,PairLimit=>...)"
  * "isLinearType(...,PairLimit=>...)"
  * "isReduction(...,PairLimit=>...)"
  * "minimalReduction(...,PairLimit=>...)"
  * "multiplicity(...,PairLimit=>...)"
  * "normalCone(Ideal,PairLimit=>...)"
  * "normalCone(Ideal,RingElement,PairLimit=>...)"
  * "reesAlgebra(...,PairLimit=>...)"
  * reesIdeal(...,PairLimit=>...)
    -- Bound the number of
    s-pairs considered in the saturation step
  * "specialFiber(...,PairLimit=>...)"
  * "specialFiberIdeal(...,PairLimit=>...)"
  * saturate(...,PairLimit=>...) (missing documentation)
  * "syz(...,PairLimit=>...)" -- see syz(Matrix) (Macaulay2Doc),
    -- compute the syzygy matrix

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

  * Default value: infinity (Macaulay2Doc),
  * Function: reesIdeal, -- Compute the defining ideal of the
    Rees Algebra
  * Option key: PairLimit (Macaulay2Doc), -- an optional
    argument
-------------------------------------------------------------------------------

The source of this document is in ReesAlgebra.m2:2054:0.

reesIdeal(...,Strategy=>...) -- Choose a strategy for the saturation step
*************************************************************************

  * Usage:
        reesIdeal(...,Strategy => X)

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

where X is is one of Iterate (Macaulay2Doc), Linear (Macaulay2Doc),
see Bayer (Macaulay2Doc), Eliminate (Macaulay2Doc).
These are described in the documentation node for
saturate (Saturation).

The Rees algebra S(M) of a submodule M of a free module (most importantly, an
ideal in the ring), is equal to the symmetric algebra Sym_k(M) mod torsion.
computing this torsion is the slow link in most of the programs in this
package. The fastest way to compute it is usually by saturating the ideal
defining the symmetric algebra with respect to an element in that ideal.

See also
========

  * reesIdeal -- Compute the defining ideal of the Rees
    Algebra
  * reesAlgebra -- Compute the defining ideal of the Rees
    Algebra
  * isLinearType -- Determine whether module has linear
    type
  * isReduction -- Determine whether an ideal is a
    reduction
  * associatedGradedRing -- The normal cone of a
    subscheme
  * multiplicity -- Compute the Hilbert-Samuel
    multiplicity of an ideal
  * specialFiberIdeal -- Special fiber of a blowup
  * specialFiber -- Special fiber of a blowup
  * analyticSpread -- Compute the analytic spread of a
    module or ideal
  * distinguished -- Compute the distinguished
    subvarieties of a pullback, intersection or cone
  * minimalReduction -- Find a minimal reduction of an
    ideal
  * saturate (missing documentation)

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 (Saturation),
    -- 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
  * decompose(Ideal,Strategy=>...) (missing documentation)
  * 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
  * hilbertFunction(...,Strategy=>...) (missing documentation)
  * "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
  * "intersectInP(...,Strategy=>...)" -- see
    intersectInP(...,BasisElementLimit=>...),
    -- Option for
    intersectInP
  * isPrime(Ideal,Strategy=>...) (missing documentation)
  * kernel(...,Strategy=>...) (Macaulay2Doc)
    -- strategy for
    Groebner Basis computations used in kernel computations
  * "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=>...) (missing documentation)
  * "analyticSpread(...,Strategy=>...)"
  * "associatedGradedRing(...,Strategy=>...)"
  * "distinguished(...,Strategy=>...)"
  * "isLinearType(...,Strategy=>...)"
  * "isReduction(...,Strategy=>...)"
  * "minimalReduction(...,Strategy=>...)"
  * "multiplicity(...,Strategy=>...)"
  * "normalCone(Ideal,RingElement,Strategy=>...)"
  * "normalCone(Ideal,Strategy=>...)"
  * "reesAlgebra(...,Strategy=>...)"
  * reesIdeal(...,Strategy=>...)
    -- Choose a strategy for
    the saturation step
  * "specialFiber(...,Strategy=>...)"
  * "specialFiberIdeal(...,Strategy=>...)"
  * saturate(...,Strategy=>...) (missing documentation)
  * "syz(...,Strategy=>...)" -- see syz(Matrix) (Macaulay2Doc),
    -- compute the syzygy matrix

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

  * Default value: null
  * Function: reesIdeal, -- Compute the defining ideal of the
    Rees Algebra
  * Option key: Strategy (Macaulay2Doc), -- an optional argument
-------------------------------------------------------------------------------

The source of this document is in ReesAlgebra.m2:2015:0.

specialFiber -- Special fiber of a blowup
*****************************************

  * Usage:
        specialFiber M
        specialFiber(M,f)
  * Inputs:
      * M, a module (Macaulay2Doc), or an ideal (Macaulay2Doc),
      * f, a ring element (Macaulay2Doc), an optional
        element, which is a non-zerodivisor such that $M[f^{-1}]$ is a free
        module when $M$ is a module, an element in $M$ when $M$ is an ideal
  * Optional inputs (Macaulay2Doc),:
      * BasisElementLimit,
        => ...,
        default value infinity, Bound the number of Groebner basis elements to
        compute in the saturation step
      * DegreeLimit,
        => ..., default value {}, Bound the degrees considered in the
        saturation step. Defaults to infinity
      * Jacobian => ..., default value false
      * MinimalGenerators,
        => ...,
        default value true, Whether the saturation step returns minimal
        generators
      * PairLimit, =>
        ..., default value infinity, Bound the number of s-pairs considered in
        the saturation step
      * Strategy, => ...,
        default value null, Choose a strategy for the saturation step
      * Trim => ..., default value true
      * Variable,
        => ..., default value "w", Choose name for variables in the created
        ring
  * Outputs:
      * a ring (Macaulay2Doc),

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

Let $M$ be an $R = k[x_1,\ldots,x_n]/J$-module (for example an ideal), and let
$mm=ideal vars R = (x_1,\ldots,x_n)$, and suppose that $M$ is a homomorphic
image of the free module $F$ with $m+1$ generators. Let $T$ be the Rees algebra
of $M$. The call specialFiber(M) returns the ideal $J\subset{}
k[w_0,\dots,w_m]$ such that $k[w_0,\dots,w_m]/J \cong{} T/mm*T$; that is,
$specialFiber(M) = reesIdeal(M)+mm*Sym(F)$. This routine differs from
specialFiberIdeal, in that the ambient ring of the output
ideal is $k[w_0,\dots,w_m]$ rather than $R[w_0,\dots,w_m]$. The coefficient
ring $k$ used is always the ultimate (Macaulay2Doc),
coefficient ring (Macaulay2Doc), of $R$.

The name derives from the fact that $Proj(T/mm*T)$ is the special fiber of the
blowup of $Spec R$ along the subscheme defined by $I$.

With the default Trim => true, the computation begins by computing minimal
generators, which may result in a change of generators of M

+----------------------------------+
|i1 : R=QQ[a..h]                   |
|                                  |
|o1 = R                            |
|                                  |
|o1 : PolynomialRing               |
+----------------------------------+
|i2 : M=matrix{{a,b,c,d},{e,f,g,h}}|
|                                  |
|o2 = | a b c d |                  |
|     | e f g h |                  |
|                                  |
|             2      4             |
|o2 : Matrix R  <-- R              |
+----------------------------------+
|i3 : analyticSpread minors(2,M)   |
|                                  |
|o3 = 5                            |
+----------------------------------+
|i4 : specialFiber minors(2,M)     |
|                                  |
|         QQ[Z ..Z ]               |
|             0   5                |
|o4 = ------------------           |
|     Z Z  - Z Z  + Z Z            |
|      2 3    1 4    0 5           |
|                                  |
|o4 : QuotientRing                 |
+----------------------------------+

See also
========

  * reesIdeal -- Compute the defining ideal of the Rees
    Algebra
  * specialFiberIdeal -- Special fiber of a blowup

Ways to use specialFiber:
=========================

  * "specialFiber(Ideal)"
  * "specialFiber(Ideal,RingElement)"
  * "specialFiber(Module)"
  * "specialFiber(Module,RingElement)"

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

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

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

The source of this document is in ReesAlgebra.m2:1428:0.

specialFiberIdeal -- Special fiber of a blowup
**********************************************

  * Usage:
        specialFiberIdeal M
        specialFiberIdeal(M,f)
  * Inputs:
      * M, a module (Macaulay2Doc), or an ideal (Macaulay2Doc),
      * f, a ring element (Macaulay2Doc), a non-zerodivisor
        such that $M[f^{-1}]$ is a free module when $M$ is a module, an element
        in $M$ when $M$ is an ideal
  * Optional inputs (Macaulay2Doc),:
      * BasisElementLimit,
        => ...,
        default value infinity, Bound the number of Groebner basis elements to
        compute in the saturation step
      * DegreeLimit,
        => ..., default value {}, Bound the degrees considered in the
        saturation step. Defaults to infinity
      * Jacobian => ..., default value false
      * MinimalGenerators,
        => ...,
        default value true, Whether the saturation step returns minimal
        generators
      * PairLimit, =>
        ..., default value infinity, Bound the number of s-pairs considered in
        the saturation step
      * Strategy, => ...,
        default value null, Choose a strategy for the saturation step
      * Trim => ..., default value true
      * Variable,
        => ..., default value "w", Choose name for variables in the created
        ring
  * Outputs:
      * an ideal (Macaulay2Doc),

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

Let $M$ be an $R = k[x_1,\ldots,x_n]/J$-module (for example an ideal), and let
$mm=ideal vars R = (x_1,\ldots,x_n)$, and suppose that $M$ is a homomorphic
image of the free module $F$. Let $T$ be the Rees algebra of $M$. The call
specialFiberIdeal(M) returns the ideal $J\subset{} Sym(F)$ such that $Sym(F)/J
\cong{} T/mm*T$; that is, $specialFiberIdeal(M) = reesIdeal(M)+mm*Sym(F).$

The name derives from the fact that $Proj(T/mm*T)$ is the special fiber of the
blowup of $Spec R$ along the subscheme defined by $I$.

With the default Trim => true, the computation begins by computing minimal
generators, which may result in a change of generators of M

+----------------------------------+
|i1 : R=QQ[a..h]                   |
|                                  |
|o1 = R                            |
|                                  |
|o1 : PolynomialRing               |
+----------------------------------+
|i2 : M=matrix{{a,b,c,d},{e,f,g,h}}|
|                                  |
|o2 = | a b c d |                  |
|     | e f g h |                  |
|                                  |
|             2      4             |
|o2 : Matrix R  <-- R              |
+----------------------------------+
|i3 : analyticSpread minors(2,M)   |
|                                  |
|o3 = 5                            |
+----------------------------------+
|i4 : specialFiberIdeal minors(2,M)|
|                                  |
|o4 = ideal(Z Z  - Z Z  + Z Z )    |
|            2 3    1 4    0 5     |
|                                  |
|o4 : Ideal of QQ[Z ..Z ]          |
|                  0   5           |
+----------------------------------+

If M is an n x n+1 matrix in n variables, and all generators have the same
degree d, with ell = n as expected, then the special fiber is a rational
hypersurface of degree $D := d^n$, and the reduction number is D-1.

+----------------------------------------+
|i5 : n = 2                              |
|                                        |
|o5 = 2                                  |
+----------------------------------------+
|i6 : x = symbol x                       |
|                                        |
|o6 = x                                  |
|                                        |
|o6 : Symbol                             |
+----------------------------------------+
|i7 : S = ZZ/32003[x_1..x_n]             |
|                                        |
|o7 = S                                  |
|                                        |
|o7 : PolynomialRing                     |
+----------------------------------------+
|i8 : M = matrix{{x_1,x_2,0},{0,x_1,x_2}}|
|                                        |
|o8 = | x_1 x_2 0   |                    |
|     | 0   x_1 x_2 |                    |
|                                        |
|             2      3                   |
|o8 : Matrix S  <-- S                    |
+----------------------------------------+
|i9 : I = minors(n,M)                    |
|                                        |
|             2         2                |
|o9 = ideal (x , x x , x )               |
|             1   1 2   2                |
|                                        |
|o9 : Ideal of S                         |
+----------------------------------------+
|i10 : specialFiber(I,I_0)               |
|                                        |
|        ZZ                              |
|      -----[w ..w ]                     |
|      32003  0   2                      |
|o10 = -------------                     |
|         2                              |
|        w  - w w                        |
|         1    0 2                       |
|                                        |
|o10 : QuotientRing                      |
+----------------------------------------+

Caveat
======

Special fiber is here defined to be the fiber of the blowup over the subvariety
defined by the vars of the original ring. Note that if the original ring is a
tower ring, this might not be the fiber over the closed point! To get the
closed fiber, flatten the base ring first.

See also
========

  * reesIdeal -- Compute the defining ideal of the Rees
    Algebra

Ways to use specialFiberIdeal:
==============================

  * "specialFiberIdeal(Ideal)"
  * "specialFiberIdeal(Ideal,RingElement)"
  * "specialFiberIdeal(Module)"
  * "specialFiberIdeal(Module,RingElement)"

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

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

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

The source of this document is in ReesAlgebra.m2:1379:0.

symmetricAlgebraIdeal -- Ideal of the symmetric algebra of an ideal or module
*****************************************************************************

  * Usage:
        I = symmetricAlgebraIdeal J
  * Inputs:
      * I, an ideal (Macaulay2Doc),
      * I, a module (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * VariableBaseName => ..., default value "w"
  * Outputs:
      * J, an ideal (Macaulay2Doc),

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

Uses the built-in  function symmetricAlgebra (Macaulay2Doc).
The function returns J an ideal in a new ring,
with generators corresponding to those of th eideal or module I. The name of
the new generators may be set, for example to T, with the form

symmetricAlgebraIdeal(J, VariableBaseName =>"T")

See also
========

  * reesIdeal -- Compute the defining ideal of the Rees
    Algebra

Ways to use symmetricAlgebraIdeal:
==================================

  * "symmetricAlgebraIdeal(Ideal)"
  * "symmetricAlgebraIdeal(Module)"

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

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

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

The source of this document is in ReesAlgebra.m2:774:0.

symmetricKernel -- Compute the Rees ring of the image of a matrix
*****************************************************************

  * Usage:
        I = symmetricKernel f
  * Inputs:
      * f, a matrix (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * Variable,
        => ..., default value "w", Choose name for variables in the created
        ring
  * Outputs:
      * an ideal (Macaulay2Doc), the defining ideal of the image
        of $Sym(f)$

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

Given a map between free modules $f: F \to G$ this function computes the kernel
of the induced map of symmetric algebras, $Sym(f): Sym(F) \to Sym(G)$ as an
ideal in $Sym(F)$.  When $f$ defines a versal embedding of $Im f$ then by the
definition of Huneke-Eisenbud-Ulrich) this is equal to the defining ideal of
the Rees algebra of the module Im f, the Rees ideal of M.

When $M$ is an ideal (and in general in characteristic 0) then, by a theorem of
Eisenbud-Huneke-Ulrich, any embedding of M into a free module may be used, and
it follows that the Rees ideal is equal to the saturation of the defining ideal
of symmetric algebra of M with respect to any element f of the ground ring such
that M[f^{-1}] is free. And this often gives a faster computation.

Most users will prefer to use one of the front end commands reesAlgebra,
see reesIdeal, to compute the ideal.

+---------------------------------------------------+
|i1 : R = QQ[a..e]                                  |
|                                                   |
|o1 = R                                             |
|                                                   |
|o1 : PolynomialRing                                |
+---------------------------------------------------+
|i2 : J = monomialCurveIdeal(R, {1,2,3})            |
|                                                   |
|             2                    2                |
|o2 = ideal (c  - b*d, b*c - a*d, b  - a*c)         |
|                                                   |
|o2 : Ideal of R                                    |
+---------------------------------------------------+
|i3 : symmetricKernel (gens J)                      |
|                                                   |
|o3 = ideal (b*w  - c*w  + d*w , a*w  - b*w  + c*w )|
|               0      1      2     0      1      2 |
|                                                   |
|o3 : Ideal of R[w ..w ]                            |
|                 0   2                             |
+---------------------------------------------------+

Let I be the ideal returned and let S be the ring it lives in (also printed).
The ring S/I is isomorphic to the Rees algebra R[Jt].  We can get the same
information above using reesIdeal(J), see reesIdeal. Note
that the degree length of S is one more than the degree length of R; the old
variables now have first degree 0, while the new variables have first degree 1.

+-------------------------------+
|i4 : S = ring oo;              |
+-------------------------------+
|i5 : (monoid S).Options.Degrees|
|                               |
|o5 = {{1, 2}, {1, 2}, {1, 2}}  |
|                               |
|o5 : List                      |
+-------------------------------+

The function symmetricKernel can also be computed over a quotient ring.

+-----------------------------------------------------------------------------+
|i6 : R = QQ[x,y,z]/ideal(x*y^2-z^9)                                          |
|                                                                             |
|o6 = R                                                                       |
|                                                                             |
|o6 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i7 : J = ideal(x,y,z)                                                        |
|                                                                             |
|o7 = ideal (x, y, z)                                                         |
|                                                                             |
|o7 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i8 : symmetricKernel(gens J)                                                 |
|                                                                             |
|                                                             8       2       |
|o8 = ideal (z*w  - y*w , z*w  - x*w , y*w  - x*w , x*y*w  - z w , x*w  -     |
|               1      2     0      2     0      1       1      2     1       |
|     ------------------------------------------------------------------------|
|      7 2     2    6 3                                                       |
|     z w , w w  - z w )                                                      |
|        2   0 1      2                                                       |
|                                                                             |
|o8 : Ideal of R[w ..w ]                                                      |
|                 0   2                                                       |
+-----------------------------------------------------------------------------+

The many ways of working with this function allows the system to compute both
the classic Rees algebra of an ideal over a ring (polynomial or quotient) and
to compute the Rees algebra of a module or ideal using a versal embedding as
described in the paper of Eisenbud, Huneke and Ulrich.  It also allows
different ways of setting up the quotient ring.

See also
========

  * reesIdeal -- Compute the defining ideal of the Rees
    Algebra
  * reesAlgebra -- Compute the defining ideal of the Rees
    Algebra
  * versalEmbedding -- Compute a versal embedding

Ways to use symmetricKernel:
============================

  * "symmetricKernel(Matrix)"

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

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

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

The source of this document is in ReesAlgebra.m2:841:0.

symmetricKernel(...,Variable=>...) -- Choose name for variables in the created ring
***********************************************************************************

  * Usage:
        symmetricKernel(...,Variable=>w)
        reesIdeal(...,Variable=>w)
        reesAlgebra(...,Variable=>w)
        specialFiberIdeal(...,Variable=>w)
        specialFiber(...,Variable=>w)
        distinguished(...,Variable=>w)
        isReduction(...,Variable=>w)
        jacobianDual(...,Variable=>w)

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

Each of these functions creates a new ring of the form R[w_0,\ldots, w_r] or
R[w_0,\ldots, w_r]/J, where R is the ring of the input ideal or module (except
for specialFiber, which creates a ring $K[w_0,\ldots,
w_r]$, where $K$ is the ultimate coefficient ring of the input ideal or
module.) This option allows the user to change the names of the new variables
in this ring. The default variable is w.

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x,y,z]/ideal(x*y^2-z^9)                                          |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : QuotientRing                                                            |
+-----------------------------------------------------------------------------+
|i2 : J = ideal(x,y,z)                                                        |
|                                                                             |
|o2 = ideal (x, y, z)                                                         |
|                                                                             |
|o2 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i3 : I = reesIdeal(J, Variable => p)                                         |
|                                                                             |
|                                                    8      2     7 2         |
|o3 = ideal (x*p  - y*p , y*p  - z*p , x*p  - z*p , z p  - y p , z p  -       |
|               1      2     0      1     0      2     0      2     0         |
|     ------------------------------------------------------------------------|
|              6 3    2                                                       |
|     y*p p , z p  - p p )                                                    |
|        1 2     0    1 2                                                     |
|                                                                             |
|o3 : Ideal of R[p ..p ]                                                      |
|                 0   2                                                       |
+-----------------------------------------------------------------------------+

To lift the result to an ideal in a flattened ring, use flattenRing (Macaulay2Doc),:

+-----------------------------------------------------------------------------+
|i4 : describe ring I                                                         |
|                                                                             |
|o4 = R[p ..p , Degrees => {3:{1}}, Heft => {1, 0}, Join => false]            |
|        0   2                {1}                                             |
+-----------------------------------------------------------------------------+
|i5 : I1 = first flattenRing I                                                |
|                                                                             |
|               9      2                                      8      2   2 7  |
|o5 = ideal (- z  + x*y , p x - p y, p y - p z, p x - p z, p z  - p y , p z  -|
|                          1     2    0     1    0     2    0      2     0    |
|     ------------------------------------------------------------------------|
|             3 6    2                                                        |
|     p p y, p z  - p p )                                                     |
|      1 2    0      1 2                                                      |
|                                                                             |
|o5 : Ideal of QQ[p ..p , x..z]                                               |
|                  0   2                                                      |
+-----------------------------------------------------------------------------+
|i6 : describe ring oo                                                        |
|                                                                             |
|o6 = QQ[p ..p , x..z, Degrees => {3:{1}, 3:{0}}, Heft => {0..1}, Join =>     |
|         0   2                      {1}    {1}                               |
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|false, MonomialOrder => {MonomialSize => 32}]                                |
|                        {GRevLex => {3:1}  }                                 |
|                        {Position => Up    }                                 |
|                        {GRevLex => {3:1}  }                                 |
+-----------------------------------------------------------------------------+

Note that the rings of I and I1 both have bigradings. Use newRing (Macaulay2Doc),
to make a new ring with different degrees.

+-----------------------------------------------------------------------------+
|i7 : S = newRing(ring I1, Degrees=>{numgens ring I1:1})                      |
|                                                                             |
|o7 = S                                                                       |
|                                                                             |
|o7 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i8 : describe S                                                              |
|                                                                             |
|o8 = QQ[p ..p , x..z, Degrees => {6:1}, Heft => {1}, Join => false,          |
|         0   2                                                               |
|                                                                             |
|                                                                             |
|-----------------------------------------------------------------------------|
|MonomialOrder => {MonomialSize => 32}]                                       |
|                 {GRevLex => {3:1}  }                                        |
|                 {Position => Up    }                                        |
|                 {GRevLex => {3:1}  }                                        |
+-----------------------------------------------------------------------------+
|i9 : I2 = sub(I1,vars S)                                                     |
|                                                                             |
|               9      2                                      8      2   2 7  |
|o9 = ideal (- z  + x*y , p x - p y, p y - p z, p x - p z, p z  - p y , p z  -|
|                          1     2    0     1    0     2    0      2     0    |
|     ------------------------------------------------------------------------|
|             3 6    2                                                        |
|     p p y, p z  - p p )                                                     |
|      1 2    0      1 2                                                      |
|                                                                             |
|o9 : Ideal of S                                                              |
+-----------------------------------------------------------------------------+
|i10 : res I2                                                                 |
|                                                                             |
|       1      7      11      6      1                                        |
|o10 = S  <-- S  <-- S   <-- S  <-- S                                         |
|                                                                             |
|      0      1      2       3      4                                         |
|                                                                             |
|o10 : Complex                                                                |
+-----------------------------------------------------------------------------+

See also
========

  * flattenRing (Macaulay2Doc) -- write a ring as a
    (quotient of a) polynomial ring
  * newRing (Macaulay2Doc) -- make a copy of a ring, with some
    features changed
  * substitute (Macaulay2Doc) -- substituting values for
    variables

Functions with optional argument named Variable:
================================================

  * "GF(...,Variable=>...)" -- see GF (Macaulay2Doc), -- make a finite
    field
  * "Grassmannian(...,Variable=>...)" -- see Grassmannian (Macaulay2Doc),
    -- compute the ideal of the Grassmannian of
    linear subspaces of a vector space
  * "intersectInP(...,Variable=>...)" -- see
    intersectInP(...,BasisElementLimit=>...),
    -- Option for
    intersectInP
  * "multiplicity(...,Variable=>...)" -- see
    intersectInP(...,BasisElementLimit=>...),
    -- Option for
    intersectInP
  * "Schubert(...,Variable=>...)" -- see Schubert (Macaulay2Doc),
    -- compute the Plücker ideal of a Schubert variety
  * "associatedGradedRing(...,Variable=>...)"
  * "distinguished(...,Variable=>...)"
  * "isReduction(...,Variable=>...)"
  * "jacobianDual(...,Variable=>...)"
  * "normalCone(Ideal,RingElement,Variable=>...)"
  * "normalCone(Ideal,Variable=>...)"
  * "reesAlgebra(...,Variable=>...)"
  * "reesIdeal(...,Variable=>...)"
  * "specialFiber(...,Variable=>...)"
  * "specialFiberIdeal(...,Variable=>...)"
  * symmetricKernel(...,Variable=>...)
    -- Choose name for
    variables in the created ring

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

  * Default value: w
  * Function: symmetricKernel, -- Compute the Rees ring
    of the image of a matrix
  * Option key: Variable (Macaulay2Doc), -- an optional argument
-------------------------------------------------------------------------------

The source of this document is in ReesAlgebra.m2:1970:0.

Trim -- Choose whether to trim (or find minimal generators) for the ideal or module.
************************************************************************************

  * Usage:
        reesIdeal(..., Trim => true)

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

Note that when Trim=>true, the generators used will be the ones (and in the
order) M2 likes, possibly not the original ones.

See also
========

  * reesIdeal -- Compute the defining ideal of the Rees
    Algebra
  * reesAlgebra -- Compute the defining ideal of the Rees
    Algebra
  * specialFiberIdeal -- Special fiber of a blowup
  * specialFiber -- Special fiber of a blowup
  * expectedReesIdeal -- symmetric algebra ideal plus
    jacobian dual

Functions with optional argument named Trim:
============================================

  * "reesIdeal(...,Trim=>...)" -- see reesIdeal, -- Compute
    the defining ideal of the Rees Algebra
  * "specialFiber(...,Trim=>...)" -- see specialFiber, --
    Special fiber of a blowup
  * "specialFiberIdeal(...,Trim=>...)" -- see specialFiberIdeal,
    -- Special fiber of a blowup

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

The object Trim, is a symbol (Macaulay2Doc).

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

The source of this document is in ReesAlgebra.m2:861:0.

versalEmbedding -- Compute a versal embedding
*********************************************

  * Usage:
        u = versalEmbedding M
  * Inputs:
      * M, a module (Macaulay2Doc), or an ideal (Macaulay2Doc),
  * Outputs:
      * u, a matrix (Macaulay2Doc), a matrix that induces a
        versal embedding of the R-module M into a free R-module.

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

For any module M over a Noetherian ring R there is a map $u: M \to H$ that is
versal for maps from M to free modules; that is, such that any map from M to a
free module factors through u. Such a map may be constructed by choosing a set
of s generators for Hom(M,R), and using them as the components of a map $u: M
\to H := R^s$.

(NOTE: In the paper of  Eisenbud, Huneke and Ulrich cited below, the versal map
is described with the term ``universal'', which is misleading, since the
induced map from H is generally not unique.)

Suppose that $M$ has a free presentation $F \to G$, and let $u1$ be the map
$u1: G\to H$ induced by composing $u$ with the surjection $p: G \to M$.  By
definition, the Rees algebra of $M$ is the image of the induced map $Sym(u1):
Sym(G)\to Sym(H)$, and thus can be computed with symmetricKernel(u1).  The map
u is computed from the dual of the first syzygy map of the dual of the
presentation of $M$.

We first give a simple example looking at the syzygy matrix of the cube of the
maximal ideal of a polynomial ring.

+------------------------------------------------------------------+
|i1 : S = ZZ/101[x,y,z];                                           |
+------------------------------------------------------------------+
|i2 : FF=res ((ideal vars S)^3);                                   |
+------------------------------------------------------------------+
|i3 : M=coker (FF.dd_2)                                            |
|                                                                  |
|o3 = cokernel {3} | -y 0  0  -z 0  0  0  0  0  0  0  0  0  0  0  ||
|              {3} | x  -y 0  0  -z 0  0  0  0  0  0  0  0  0  0  ||
|              {3} | 0  x  -y 0  0  0  -z 0  0  0  0  0  0  0  0  ||
|              {3} | 0  0  x  0  0  0  0  0  -z 0  0  0  0  0  0  ||
|              {3} | 0  0  0  x  y  -y 0  0  0  -z 0  0  0  0  0  ||
|              {3} | 0  0  0  0  0  x  y  -y 0  0  -z 0  0  0  0  ||
|              {3} | 0  0  0  0  0  0  0  x  y  0  0  0  -z 0  0  ||
|              {3} | 0  0  0  0  0  0  0  0  0  x  y  -y 0  -z 0  ||
|              {3} | 0  0  0  0  0  0  0  0  0  0  0  x  y  0  -z ||
|              {3} | 0  0  0  0  0  0  0  0  0  0  0  0  0  x  y  ||
|                                                                  |
|                            10                                    |
|o3 : S-module, quotient of S                                      |
+------------------------------------------------------------------+
|i4 : versalEmbedding M                                            |
|                                                                  |
|o4 = | x3 x2y xy2 y3 x2z xyz y2z xz2 yz2 z3 |                     |
|                                                                  |
|             1                                                    |
|o4 : Matrix S  <-- M                                              |
+------------------------------------------------------------------+

A more complicated example.

+-----------------------------------------------------------------------------+
|i5 : x = symbol x;                                                           |
+-----------------------------------------------------------------------------+
|i6 : R=QQ[x_1..x_8];                                                         |
+-----------------------------------------------------------------------------+
|i7 : m1=genericMatrix(R,x_1,2,2); m2=genericMatrix(R,x_5,2,2);               |
|                                                                             |
|             2      2                                                        |
|o7 : Matrix R  <-- R                                                         |
|                                                                             |
|             2      2                                                        |
|o8 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+
|i9 : m=m1*m2                                                                 |
|                                                                             |
|o9 = | x_1x_5+x_3x_6 x_1x_7+x_3x_8 |                                         |
|     | x_2x_5+x_4x_6 x_2x_7+x_4x_8 |                                         |
|                                                                             |
|             2      2                                                        |
|o9 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+
|i10 : d1=minors(2,m1); d2=minors(2,m2);                                      |
|                                                                             |
|o10 : Ideal of R                                                             |
|                                                                             |
|o11 : Ideal of R                                                             |
+-----------------------------------------------------------------------------+
|i12 : M=matrix{{0,d1_0,m_(0,0),m_(0,1)},           {0,0,m_(1,0),m_(1,1)},    |
|                                                                             |
|o12 = | 0 -x_2x_3+x_1x_4 x_1x_5+x_3x_6 x_1x_7+x_3x_8  |                      |
|      | 0 0              x_2x_5+x_4x_6 x_2x_7+x_4x_8  |                      |
|      | 0 0              0             -x_6x_7+x_5x_8 |                      |
|      | 0 0              0             0              |                      |
|                                                                             |
|              4      4                                                       |
|o12 : Matrix R  <-- R                                                        |
|-----------------------------------------------------------------------------|
|{0,0,0,d2_0},           {0,0,0,0}}                                           |
+-----------------------------------------------------------------------------+
|i13 : M=M-(transpose M);                                                     |
|                                                                             |
|              4      4                                                       |
|o13 : Matrix R  <-- R                                                        |
+-----------------------------------------------------------------------------+
|i14 : N= coker(res coker transpose M).dd_2                                   |
|                                                                             |
|o14 = cokernel {0} | -x_2x_5-x_4x_6 -x_2x_7-x_4x_8 x_6x_7-x_5x_8             |
|               {2} | x_2x_3-x_1x_4  0              x_1x_7+x_3x_8             |
|               {2} | -x_1x_5-x_3x_6 -x_1x_7-x_3x_8 0                         |
|               {2} | 0              x_2x_3-x_1x_4  -x_1x_5-x_3x_6            |
|                                                                             |
|                             4                                               |
|o14 : R-module, quotient of R                                                |
|-----------------------------------------------------------------------------|
|0              |                                                             |
|x_2x_7+x_4x_8  |                                                             |
|-x_6x_7+x_5x_8 |                                                             |
|-x_2x_5-x_4x_6 |                                                             |
+-----------------------------------------------------------------------------+
|i15 : versalEmbedding(N)                                                     |
|                                                                             |
|o15 = {-1} | x_1 -x_6 -x_2 -x_8 |                                            |
|      {-1} | x_3 x_5  -x_4 x_7  |                                            |
|                                                                             |
|              2                                                              |
|o15 : Matrix R  <-- N                                                        |
+-----------------------------------------------------------------------------+

Here is an example from the paper "What is the Rees Algebra of a Module" by
David Eisenbud, Craig Huneke and Bernd Ulrich, Proc. Am. Math. Soc. 131,
701-708, 2002.  The example shows that one cannot, in general, define the Rees
algebra of a module by using *any* embedding of that module, even when the
module is isomorphic to an ideal; this is the reason for using the map provided
by the routine versalEmbedding. Note that the same paper shows that such
problems do not arise when the ring is torsion-free as a ZZ-module, or when one
takes the natural embedding of the ideal into the ring.

+---------------------------------------------------+
|i16 : p = 3;                                       |
+---------------------------------------------------+
|i17 : S = ZZ/p[x,y,z];                             |
+---------------------------------------------------+
|i18 : R = S/((ideal(x^p,y^p))+(ideal(x,y,z))^(p+1))|
|                                                   |
|o18 = R                                            |
|                                                   |
|o18 : QuotientRing                                 |
+---------------------------------------------------+
|i19 : I = module ideal(z)                          |
|                                                   |
|o19 = image | z |                                  |
|                                                   |
|                              1                    |
|o19 : R-module, submodule of R                     |
+---------------------------------------------------+

As a module (or ideal), $Hom(I,R^1)$ is minimally generated by 3 elements, and
thus a versal embedding of $I$ into a free module is into $R^3$.

+----------------------------+
|i20 : betti Hom(I,R^1)      |
|                            |
|             0  1           |
|o20 = total: 3 14           |
|          0: 3  3           |
|          1: .  2           |
|          2: .  9           |
|                            |
|o20 : BettiTally            |
+----------------------------+
|i21 : ui = versalEmbedding I|
|                            |
|o21 = | z |                 |
|      | y |                 |
|      | x |                 |
|                            |
|              3             |
|o21 : Matrix R  <-- I       |
+----------------------------+

it is injective:

+-------------------------------+
|i22 : kernel ui                |
|                               |
|o22 = image 0                  |
|                               |
|                              1|
|o22 : R-module, submodule of R |
+-------------------------------+

It is easy to make two other embeddings of $I$ into free modules. One is the
natural inclusion of $I$ into $R$ as an ideal:

+-----------------------------------+
|i23 : inci = map(R^1,I,matrix{{z}})|
|                                   |
|o23 = | z |                        |
|                                   |
|              1                    |
|o23 : Matrix R  <-- I              |
+-----------------------------------+
|i24 : kernel inci                  |
|                                   |
|o24 = image 0                      |
|                                   |
|                              1    |
|o24 : R-module, submodule of R     |
+-----------------------------------+

Another is the map defined by multiplication by x and y.

+---------------------------------------+
|i25 : gi = map(R^2, I, matrix{{x},{y}})|
|                                       |
|o25 = | x |                            |
|      | y |                            |
|                                       |
|              2                        |
|o25 : Matrix R  <-- I                  |
+---------------------------------------+
|i26 : kernel gi                        |
|                                       |
|o26 = image 0                          |
|                                       |
|                              1        |
|o26 : R-module, submodule of R         |
+---------------------------------------+

We can compose $ui, inci$ and $gi$ with a surjection $R\to i$ to get maps
$u:R^1 \to R^3, inc: R^1 \to R^1$ and $g:R^1 \to R^2$ having image $i$.

+-----------------------------------------+
|i27 : u= map(R^3,R^{-1},ui)              |
|                                         |
|o27 = | z |                              |
|      | y |                              |
|      | x |                              |
|                                         |
|              3      1                   |
|o27 : Matrix R  <-- R                    |
+-----------------------------------------+
|i28 : inc=map(R^1, R^{-1}, matrix{{z}})  |
|                                         |
|o28 = | z |                              |
|                                         |
|              1      1                   |
|o28 : Matrix R  <-- R                    |
+-----------------------------------------+
|i29 : g=map(R^2, R^{-1}, matrix{{x},{y}})|
|                                         |
|o29 = | x |                              |
|      | y |                              |
|                                         |
|              2      1                   |
|o29 : Matrix R  <-- R                    |
+-----------------------------------------+

We now form the symmetric kernels of these maps and compare them.  Note that
since symmetricKernel defines a new ring, we must bring them to the same ring
to make the comparison.  First the map u, which would be used by reesIdeal:

+-----------------------------------------------------------------------------+
|i30 : A=symmetricKernel u                                                    |
|                                                                             |
|              3       2       2     2                 2         2     2      |
|o30 = ideal (z w , y*z w , x*z w , y z*w , x*y*z*w , x z*w , x*y w , x y*w , |
|                0       0       0       0         0       0       0       0  |
|      -----------------------------------------------------------------------|
|       2 2       2       2   2 2       2   2 2     3     3     3   4         |
|      z w , y*z*w , x*z*w , y w , x*y*w , x w , z*w , y*w , x*w , w )        |
|         0       0       0     0       0     0     0     0     0   0         |
|                                                                             |
|o30 : Ideal of R[w ]                                                         |
|                  0                                                          |
+-----------------------------------------------------------------------------+

Next the inclusion:

+-----------------------------------------------------------------------------+
|i31 : B1=symmetricKernel inc                                                 |
|                                                                             |
|              3       2       2     2                 2         2     2      |
|o31 = ideal (z w , y*z w , x*z w , y z*w , x*y*z*w , x z*w , x*y w , x y*w , |
|                0       0       0       0         0       0       0       0  |
|      -----------------------------------------------------------------------|
|       2 2       2       2   2 2       2   2 2     3     3     3   4         |
|      z w , y*z*w , x*z*w , y w , x*y*w , x w , z*w , y*w , x*w , w )        |
|         0       0       0     0       0     0     0     0     0   0         |
|                                                                             |
|o31 : Ideal of R[w ]                                                         |
|                  0                                                          |
+-----------------------------------------------------------------------------+
|i32 : B=(map(ring A, ring B1)) B1                                            |
|                                                                             |
|              3       2       2     2                 2         2     2      |
|o32 = ideal (z w , y*z w , x*z w , y z*w , x*y*z*w , x z*w , x*y w , x y*w , |
|                0       0       0       0         0       0       0       0  |
|      -----------------------------------------------------------------------|
|       2 2       2       2   2 2       2   2 2     3     3     3   4         |
|      z w , y*z*w , x*z*w , y w , x*y*w , x w , z*w , y*w , x*w , w )        |
|         0       0       0     0       0     0     0     0     0   0         |
|                                                                             |
|o32 : Ideal of R[w ]                                                         |
|                  0                                                          |
+-----------------------------------------------------------------------------+

Finally, the map g1:

+-----------------------------------------------------------------------------+
|i33 : C1 = symmetricKernel g                                                 |
|                                                                             |
|              3   3       2       2     2                 2         2        |
|o33 = ideal (w , z w , y*z w , x*z w , y z*w , x*y*z*w , x z*w , x*y w ,     |
|              0     0       0       0       0         0       0       0      |
|      -----------------------------------------------------------------------|
|       2       2 2       2       2   2 2       2   2 2                       |
|      x y*w , z w , y*z*w , x*z*w , y w , x*y*w , x w )                      |
|           0     0       0       0     0       0     0                       |
|                                                                             |
|o33 : Ideal of R[w ]                                                         |
|                  0                                                          |
+-----------------------------------------------------------------------------+
|i34 : C=(map(ring A, ring C1)) C1                                            |
|                                                                             |
|              3   3       2       2     2                 2         2        |
|o34 = ideal (w , z w , y*z w , x*z w , y z*w , x*y*z*w , x z*w , x*y w ,     |
|              0     0       0       0       0         0       0       0      |
|      -----------------------------------------------------------------------|
|       2       2 2       2       2   2 2       2   2 2                       |
|      x y*w , z w , y*z*w , x*z*w , y w , x*y*w , x w )                      |
|           0     0       0       0     0       0     0                       |
|                                                                             |
|o34 : Ideal of R[w ]                                                         |
|                  0                                                          |
+-----------------------------------------------------------------------------+

The following test yields ``true'', as implied by the theorem of Eisenbud,
Huneke and Ulrich.

+----------+
|i35 : A==B|
|          |
|o35 = true|
+----------+

But the following yields ``false'', showing that one must take care in general,
which inclusion one uses.

+-----------+
|i36 : A==C |
|           |
|o36 = false|
+-----------+

See also
========

  * reesIdeal -- Compute the defining ideal of the Rees
    Algebra
  * reesAlgebra -- Compute the defining ideal of the Rees
    Algebra
  * symmetricKernel -- Compute the Rees ring of the
    image of a matrix

Ways to use versalEmbedding:
============================

  * "versalEmbedding(Ideal)"
  * "versalEmbedding(Module)"

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

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

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

The source of this document is in ReesAlgebra.m2:1013:0.

whichGm -- Largest Gm satisfied by an ideal
*******************************************

  * Usage:
        whichGm I
  * Inputs:
      * I, an ideal (Macaulay2Doc),
  * Outputs:
      * an integer (Macaulay2Doc), the largest $m$ such that $I$
        satisfies the condition $G_m$, or infinity (Macaulay2Doc),

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

An ideal $I$ in a ring $S$ is said to satisfy the condition $G_m$ if, for every
prime ideal $P$ of codimension $0<k<m$, the ideal $I_P$ in $S_P$ can be
generated by at most $k$ elements.

The command whichGm I returns the largest $m$ such that $I$ satisfies $G_m$, or
infinity if $I$ satisfies $G_m$ for every $m$.

This condition arises frequently in work of Vasconcelos and Ulrich and their
schools on Rees algebras and powers of ideals. See for example Morey, Susan;
Ulrich, Bernd: Rees algebras of ideals with low codimension. Proc. Amer. Math.
Soc.  124  (1996),  no. 12, 3653–3661.

+-------------------------------------------+
|i1 : kk=ZZ/101;                            |
+-------------------------------------------+
|i2 : S=kk[a..c];                           |
+-------------------------------------------+
|i3 : m=ideal vars S                        |
|                                           |
|o3 = ideal (a, b, c)                       |
|                                           |
|o3 : Ideal of S                            |
+-------------------------------------------+
|i4 : i=(ideal"a,b")*m+ideal"c3"            |
|                                           |
|             2                  2        3 |
|o4 = ideal (a , a*b, a*c, a*b, b , b*c, c )|
|                                           |
|o4 : Ideal of S                            |
+-------------------------------------------+
|i5 : whichGm i                             |
|                                           |
|o5 = 3                                     |
+-------------------------------------------+

See also
========

  * analyticSpread -- Compute the analytic spread of a
    module or ideal
  * minimalReduction -- Find a minimal reduction of an
    ideal
  * reductionNumber -- Reduction number of one ideal
    with respect to another

Ways to use whichGm:
====================

  * "whichGm(Ideal)"

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

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

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

The source of this document is in ReesAlgebra.m2:1766:0.