This is MultiGradedRationalMap.info, produced by Macaulay2, version 1.22

MultiGradedRationalMap
**********************

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

MultiGradedRationalMap provides functions for computing the degree of a
multi-graded rational map.

In the paper  Degree and birationality of multi-graded rational maps (see
https://arxiv.org/abs/1805.05180 ), a new algebra called the saturated special
fiber ring was introduced. This algebra is related to several features in the
study of rational maps.

Some functions of this package are capable of working in the multi-graded
setting. Let $R$ be the multi-homogeneous polynomial ring
$R=k[x_{1,0},x_{1,1},...,x_{1,r_1}, x_{2,0},x_{2,1},...,x_{2,r_2}, ......,
x_{m,0},x_{m,1},...,x_{m,r_m}]$ where the multidegree of a variable $x_{i,j}$
is $\{0,...,1,...,0\}$. Let $\mathbf{m}$ be the multi-homogeneous irrelevant
ideal  $\mathbf{m}=(x_{1,0},x_{1,1},...,x_{1,r_1})\cap
(x_{2,0},x_{2,1},...,x_{2,r_2}) \cap ... \cap (x_{m,0},x_{m,1},...,x_{m,r_m})$
of $R$. Let $I$ be a multi-homogeneous ideal in $R$, which is generated by
multi-homogeneous polynomials of the same multi-degree. The saturated special
fiber ring of $I$ is defined by the algebra $$ \oplus_{n=0}^\infty
[(I^n)^{sat}]_{n*d}. $$

The main idea of this package is to exploit this algebra to compute the degree
and test the birationality of rational maps.

We also implement the Jacobian dual criterion in the multi-graded setting.

Overlap with other packages: -  The package Cremona (see
https://faculty.math.illinois.edu/Macaulay2/doc/Macaulay2-1.12/share/doc/
Macaulay2/Cremona/html/ ) performs several computations related to rational and
birational maps between irreducible projective varieties. Among other things,
it can compute the degree of a rational map, test birationality and find the
inverse of a birational map. There is a deterministic implementation and a fast
probabilistic implementation.

- The package RationalMaps (see
https://faculty.math.illinois.edu/Macaulay2/doc/Macaulay2-1.11/share/doc/
Macaulay2/RationalMaps/html/index.html ) computes several things related to
rational maps between projective varieties. Among other things, it can detect
birationality and compute the inverse of a rational map. It contains an
implementation of the remarkable Jacobian dual criterion.

- The package Parametrization (see
https://faculty.math.illinois.edu/Macaulay2/doc/Macaulay2-1.11/share/doc/
Macaulay2/Parametrization/html/index.html ) mostly deals with rational
parametrizations of rational curves defined over ℚ. It includes a function to
compute the inverse of a rational map.

- The present implementation of this package can only handle rational maps
where the source is a multiprojective space. On the other hand, the packages
Cremona (see https://faculty.math.illinois.edu/Macaulay2/doc/Macaulay2-1.12/
share/doc/Macaulay2/Cremona/html/ ), RationalMaps (see
https://faculty.math.illinois.edu/Macaulay2/doc/Macaulay2-1.11/share/doc/
Macaulay2/RationalMaps/html/index.html ) and Parametrization (see
https://faculty.math.illinois.edu/Macaulay2/doc/Macaulay2-1.11/share/doc/
Macaulay2/Parametrization/html/index.html )  can handle more general varieties.

Acknowledgements: The author is grateful to the organizers of the Macaulay2
workshop in Leipzig. The author is grateful to Laurent Busé for his support on
the preparation of this package.

Author
======

  * Yairon Cid Ruiz (see http://www.ub.edu/arcades/ycid.html ) <ycid@ub.edu>

Version
=======

This documentation describes version 0.1 of MultiGradedRationalMap.

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

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

Exports
=======

  * Functions and commands
      * degreeOfMap -- computes the degree of a rational
        map
      * degreeOfMapIter -- computes the degree of a
        rational map
      * gensSatSpecialFib -- computes generators of
        the saturated special fiber ring
      * Hm1Rees0 -- computes the module [Hm^1(Rees(I))]_0
      * isBiratMap -- tests the birationality of a rational
        with the Jacobian dual criterion
      * jacobianDualRank -- computes the full Jacobian
        dual rank
      * partialJDRs -- computes the partial Jacobian dual
        ranks
      * satSpecialFiber (missing documentation)
      * satSpecialFiberIdeal -- computes the
        defining equations of the saturated special fiber ring
      * upperBoundDegreeSingleGraded, --
        computes an upper bound for the degree of a rational map
  * Methods
      * "degreeOfMap(Ideal)" -- see degreeOfMap, -- computes
        the degree of a rational map
      * "degreeOfMapIter(Ideal,ZZ)" -- see degreeOfMapIter,
        -- computes the degree of a rational map
      * "gensSatSpecialFib(Ideal)" -- see gensSatSpecialFib,
        -- computes generators of the saturated special
        fiber ring
      * "gensSatSpecialFib(Ideal,ZZ)" -- see gensSatSpecialFib,
        -- computes generators of the saturated special
        fiber ring
      * "Hm1Rees0(Ideal)" -- see Hm1Rees0, -- computes the
        module [Hm^1(Rees(I))]_0
      * "isBiratMap(Ideal)" -- see isBiratMap, -- tests the
        birationality of a rational with the Jacobian dual criterion
      * "jacobianDualRank(Ideal)" -- see jacobianDualRank,
        -- computes the full Jacobian dual rank
      * "partialJDRs(Ideal)" -- see partialJDRs, -- computes
        the partial Jacobian dual ranks
      * "satSpecialFiber(Ideal)" -- see satSpecialFiberIdeal,
        -- computes the defining equations of the
        saturated special fiber ring
      * "satSpecialFiberIdeal(Ideal,ZZ)" -- see satSpecialFiberIdeal,
        -- computes the defining equations of the
        saturated special fiber ring
      * "upperBoundDegreeSingleGraded(Ideal)" -- see
        upperBoundDegreeSingleGraded, -- computes
        an upper bound for the degree of a rational map
  * Symbols
      * Hm1Rees0Strategy -- A strategy for degreeOfMap
      * SatSpecialFibStrategy -- A strategy for
        degreeOfMap

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

The object MultiGradedRationalMap, is a package (Macaulay2Doc).

degreeOfMap -- computes the degree of a rational map
****************************************************

Synopsis
========

  * Usage:
        degreeOfMap(I)
  * Inputs:
      * I, an ideal (Macaulay2Doc), an ideal defining the map
  * Optional inputs (Macaulay2Doc),:
      * Strategy, =>
        ..., default value Hm1Rees0Strategy, Choose a strategy for computing
        the degree of map
  * Outputs:
      * an integer (Macaulay2Doc), the degree of the corresponding
        rational map

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

Let $R$ be the polynomial ring $R=k[x_0,...,x_r]$ and $I$ be the homogeneous
ideal $I=(f_0,f_1,...,f_s)$ where $deg(f_i)=d$. We compute the degree of the
rational map $\mathbb{F}: \mathbb{P}^r \to \mathbb{P}^s$ defined by $$ (x_0:
... :x_r) \to (f_0(x_0,...,x_r), f_1(x_0,...,x_r), ..... , f_s(x_0,...,x_r)).
$$ The degree can be computed by two different strategies and the default one
is "Hm1Rees0Strategy".

The following example is a rational map without base points:

+---------------------------------------------------------+
|i1 : R = QQ[x,y,z]                                       |
|                                                         |
|o1 = R                                                   |
|                                                         |
|o1 : PolynomialRing                                      |
+---------------------------------------------------------+
|i2 : I = ideal(random(4, R), random(4, R), random(4, R));|
|                                                         |
|o2 : Ideal of R                                          |
+---------------------------------------------------------+
|i3 : betti res I                                         |
|                                                         |
|            0 1 2 3                                      |
|o3 = total: 1 3 3 1                                      |
|         0: 1 . . .                                      |
|         1: . . . .                                      |
|         2: . . . .                                      |
|         3: . 3 . .                                      |
|         4: . . . .                                      |
|         5: . . . .                                      |
|         6: . . 3 .                                      |
|         7: . . . .                                      |
|         8: . . . .                                      |
|         9: . . . 1                                      |
|                                                         |
|o3 : BettiTally                                          |
+---------------------------------------------------------+
|i4 : degreeOfMap I                                       |
|                                                         |
|o4 = 16                                                  |
+---------------------------------------------------------+

In the following examples we play with the relations of the Hilbert-Burch
presentation and the degree of $\mathbb{F}$ (see Proposition 5.2 and Theorem
5.12):

+---------------------------------------------------+
|i5 : A = matrix{ {x, x^2 + y^2},                   |
|                 {-y, y^2 + z*x},                  |
|                 {0, x^2}                          |
|               };                                  |
|                                                   |
|             3       2                             |
|o5 : Matrix R  <--- R                              |
+---------------------------------------------------+
|i6 : I = minors(2, A) -- a birational map          |
|                                                   |
|             2       2    3    2    3    2         |
|o6 = ideal (x y + x*y  + y  + x z, x , -x y)       |
|                                                   |
|o6 : Ideal of R                                    |
+---------------------------------------------------+
|i7 : degreeOfMap I                                 |
|                                                   |
|o7 = 1                                             |
+---------------------------------------------------+
|i8 : A = matrix{ {x^2, x^2 + y^2},                 |
|                 {-y^2, y^2 + z*x},                |
|                 {0, x^2}                          |
|               };                                  |
|                                                   |
|             3       2                             |
|o8 : Matrix R  <--- R                              |
+---------------------------------------------------+
|i9 : I = minors(2, A) -- a non birational map      |
|                                                   |
|              2 2    4    3    4    2 2            |
|o9 = ideal (2x y  + y  + x z, x , -x y )           |
|                                                   |
|o9 : Ideal of R                                    |
+---------------------------------------------------+
|i10 : degreeOfMap I                                |
|                                                   |
|o10 = 2                                            |
+---------------------------------------------------+
|i11 : A = matrix{ {x^3, x^2 + y^2},                |
|                  {-y^3, y^2 + z*x},               |
|                  {0, x^2}                         |
|                };                                 |
|                                                   |
|              3       2                            |
|o11 : Matrix R  <--- R                             |
+---------------------------------------------------+
|i12 : I = minors(2, A) -- a non birational map     |
|                                                   |
|              3 2    2 3    5    4    5    2 3     |
|o12 = ideal (x y  + x y  + y  + x z, x , -x y )    |
|                                                   |
|o12 : Ideal of R                                   |
+---------------------------------------------------+
|i13 : degreeOfMap I                                |
|                                                   |
|o13 = 3                                            |
+---------------------------------------------------+
|i14 : A = matrix{ {x^3, x^4},                      |
|                  {-y^3, y^4},                     |
|                  {z^3, x^4}                       |
|                };                                 |
|                                                   |
|              3       2                            |
|o14 : Matrix R  <--- R                             |
+---------------------------------------------------+
|i15 : I = minors(2, A) -- a non birational map     |
|                                                   |
|              4 3    3 4   7    4 3     4 3    4 3 |
|o15 = ideal (x y  + x y , x  - x z , - x y  - y z )|
|                                                   |
|o15 : Ideal of R                                   |
+---------------------------------------------------+
|i16 : degreeOfMap I                                |
|                                                   |
|o16 = 12                                           |
+---------------------------------------------------+

The following examples are computed with the strategy "SatSpecialFibStrategy".

+-----------------------------------------------------------------------------+
|i17 : R = QQ[x,y,z,v,w]                                                      |
|                                                                             |
|o17 = R                                                                      |
|                                                                             |
|o17 : PolynomialRing                                                         |
+-----------------------------------------------------------------------------+
|i18 : I = ideal(random(1, R), random(1, R), random(1, R), random(1, R),      |
|                                                                             |
|o18 : Ideal of R                                                             |
|-----------------------------------------------------------------------------|
|random(1, R));                                                               |
+-----------------------------------------------------------------------------+
|i19 : degreeOfMap(I, Strategy=>SatSpecialFibStrategy)                        |
|                                                                             |
|o19 = 1                                                                      |
+-----------------------------------------------------------------------------+
|i20 : I = ideal(29*x^3 + 55*x*y*z, 7*y^3, 14*z^3, 17*v^3, 12*w^3)            |
|                                                                             |
|                3              3     3     3     3                           |
|o20 = ideal (29x  + 55x*y*z, 7y , 14z , 17v , 12w )                          |
|                                                                             |
|o20 : Ideal of R                                                             |
+-----------------------------------------------------------------------------+
|i21 : degreeOfMap(I, Strategy=>SatSpecialFibStrategy)                        |
|                                                                             |
|o21 = 81                                                                     |
+-----------------------------------------------------------------------------+

Caveat
======

To call the method "degreeOfMap(I)", the ideal $I$ should be in a single graded
polynomial ring.

Ways to use degreeOfMap :
=========================

  * "degreeOfMap(Ideal)"

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

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

degreeOfMap(...,Strategy=>...) -- Choose a strategy for computing the degree of map
***********************************************************************************

Synopsis
========

  * Usage:
        degreeOfMap(...,Strategy => ...)

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

Depending on this strategy the function "degreeOfMap" computes the degree of a
map by two different approaches. The two strategies are "Hm1Rees0Strategy" and
"SatSpecialFibStrategy".

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

  * Default value: Hm1Rees0Strategy,
  * Function: degreeOfMap, -- computes the degree of a
    rational map
  * Option key: Strategy (Macaulay2Doc), -- an optional argument

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
  * "associatedPrimes(...,Strategy=>...)" -- see associatedPrimes (PrimaryDecomposition),
    -- find associated primes
  * "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
  * degreeOfMap(...,Strategy=>...)
    -- Choose a strategy for
    computing the degree of map
  * 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)
  * exteriorPower(...,Strategy=>...) (Macaulay2Doc)
    -- choose
    between Bareiss, Cofactor and Dynamic algorithms
  * "gb(...,Strategy=>...)" -- see gb (Macaulay2Doc), -- compute a
    Gröbner basis
  * gcdLLL(...,Strategy=>...) (missing documentation)
  * "GF(...,Strategy=>...)" -- see GF (Macaulay2Doc), -- make a finite
    field
  * "groebnerBasis(...,Strategy=>...)" -- see groebnerBasis (Macaulay2Doc),
    -- Gröbner basis, as a matrix
  * hermite(...,Strategy=>...) (missing documentation)
  * "hooks(...,Strategy=>...)" -- see hooks (Macaulay2Doc), -- list
    hooks attached to a key
  * "idealizer(...,Strategy=>...)" -- see idealizer (IntegralClosure),
    -- compute Hom(I,I) as a quotient ring
  * integralClosure(...,Strategy=>...) (IntegralClosure),
    --
    control the algorithm used
  * "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=>...) (ReesAlgebra),
    --
    Option for intersectInP
  * "isPrimary(...,Strategy=>...)" -- see isPrimary (PrimaryDecomposition),
    -- determine whether a submodule is
    primary
  * "isPrime(Ideal,Strategy=>...)" -- see isPrime(Ideal) (MinimalPrimes),
    -- whether an ideal is prime
  * LLL(...,Strategy=>...) (LLLBases)
    -- choose among
    different algorithms
  * "localize(...,Strategy=>...)" -- see localize (PrimaryDecomposition),
    -- localize an ideal at a prime ideal
  * "match(...,Strategy=>...)" -- see match (Macaulay2Doc), --
    regular expression matching
  * "decompose(Ideal,Strategy=>...)" -- see minimalPrimes (MinimalPrimes),
    -- minimal primes of an ideal
  * "minimalPrimes(...,Strategy=>...)" -- see minimalPrimes (MinimalPrimes),
    -- minimal primes of an ideal
  * minors(...,Strategy=>...) (Macaulay2Doc)
    -- choose
    between Bareiss, Cofactor and Dynamic algorithms
  * "primaryComponent(...,Strategy=>...)" -- see primaryComponent (PrimaryDecomposition),
    -- find a primary component
    corresponding to an associated prime
  * pushForward(...,Strategy=>...) (missing documentation)
  * quotient(...,Strategy=>...) (Saturation)
  * "radical(...,Strategy=>...)" -- see radical (MinimalPrimes),
    -- the radical of an ideal
  * "radicalContainment(...,Strategy=>...)" -- see radicalContainment (MinimalPrimes),
    -- whether an element is contained in
    the radical of an ideal
  * "analyticSpread(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "distinguished(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "isLinearType(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "isReduction(...,Strategy=>...)" -- see reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "minimalReduction(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "multiplicity(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "normalCone(...,Strategy=>...)" -- see reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "reesAlgebra(...,Strategy=>...)" -- see reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * reesIdeal(...,Strategy=>...) (ReesAlgebra)
    -- Choose a
    strategy for the saturation step
  * "specialFiber(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "specialFiberIdeal(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "regSeqInIdeal(...,Strategy=>...)" -- see regSeqInIdeal (PrimaryDecomposition),
    -- a regular sequence contained in an
    ideal
  * resolution(...,Strategy=>...) (Macaulay2Doc)
  * saturate(...,Strategy=>...) (Saturation)
  * "primaryDecomposition(...,Strategy=>...)" -- see strategies for computing primary decomposition (PrimaryDecomposition),
  * "syz(...,Strategy=>...)" -- see syz(Matrix) (Macaulay2Doc),
    -- compute the syzygy matrix
  * "tangentCone(...,Strategy=>...)" -- see tangentCone(Ideal) (TangentCone),

degreeOfMapIter -- computes the degree of a rational map
********************************************************

Synopsis
========

  * Usage:
        degreeOfMapIter(I, nsteps)
  * Inputs:
      * I, an ideal (Macaulay2Doc), an ideal defining the map
      * nsteps, an integer (Macaulay2Doc), the number of steps used
        for computing the saturated special fiber ring
  * Outputs:
      * an integer (Macaulay2Doc), the degree of the corresponding
        rational map

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

Let $R$ be the multi-homogeneous polynomial ring
$R=k[x_{1,0},x_{1,1},...,x_{1,r_1}, x_{2,0},x_{2,1},...,x_{2,r_2}, ......,
x_{m,0},x_{m,1},...,x_{m,r_m}]$ and $I$ be the multi-homogeneous ideal
$I=(f_0,f_1,...,f_s)$ where the polynomials $f_i$'s have the same multi-degree.
We compute the degree of the rational map $\mathbb{F}: \mathbb{P}^{r_1} \times
\mathbb{P}^{r_2} \times ... \times \mathbb{P}^{r_m}  \to \mathbb{P}^s$ defined
by $$ (x_{1,0} : ... : x_{1,r_1}; ...... ;x_{m,0} : ... : x_{m,r_m}) \to
(f_0(x_{1,0},...,x_{1,r_1}, ...... ,x_{m,0},...,x_{m,r_m}), ..... ,
f_0(x_{1,0},...,x_{1,r_1}, ...... ,x_{m,0},...,x_{m,r_m})). $$ This method
calls "satSpecialFiber(I, nsteps)" in order to obtain the saturated special
fiber ring and then computes the degree of $\mathbb{F}$ from the multiplicity
of the saturated special fiber ring.

+-------------------------------------------------------------+
|i1 : R = QQ[x,y,u,v, Degrees => {{1,0}, {1,0}, {0,1}, {0,1}}]|
|                                                             |
|o1 = R                                                       |
|                                                             |
|o1 : PolynomialRing                                          |
+-------------------------------------------------------------+
|i2 : I = ideal(x*u, y*u, y*v) -- a birational map            |
|                                                             |
|o2 = ideal (x*u, y*u, y*v)                                   |
|                                                             |
|o2 : Ideal of R                                              |
+-------------------------------------------------------------+
|i3 : degreeOfMapIter(I, 5)                                   |
|                                                             |
|o3 = 1                                                       |
+-------------------------------------------------------------+
|i4 : I = ideal(x*u, y*v, x*v + y*u) -- a non birational map  |
|                                                             |
|o4 = ideal (x*u, y*v, y*u + x*v)                             |
|                                                             |
|o4 : Ideal of R                                              |
+-------------------------------------------------------------+
|i5 : degreeOfMapIter(I, 5)                                   |
|                                                             |
|o5 = 2                                                       |
+-------------------------------------------------------------+
|i6 : A = matrix{ {x^5*u,  x^2*v^2},                          |
|                 {y^5*v, x^2*u^2},                           |
|                 {0,     y^2*v^2}                            |
|               };                                            |
|                                                             |
|             3       2                                       |
|o6 : Matrix R  <--- R                                        |
+-------------------------------------------------------------+
|i7 : I = minors(2, A)  -- a non birational                   |
|                                                             |
|             7 3    2 5 3   5 2   2   7 3                    |
|o7 = ideal (x u  - x y v , x y u*v , y v )                   |
|                                                             |
|o7 : Ideal of R                                              |
+-------------------------------------------------------------+
|i8 : degreeOfMapIter(I, 5)                                   |
|                                                             |
|o8 = 10                                                      |
+-------------------------------------------------------------+

Caveat
======

It only gives the correct answer if nteps is big enough to attain all the
generators of the saturated special fiber ring.

Ways to use degreeOfMapIter :
=============================

  * "degreeOfMapIter(Ideal,ZZ)"

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

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

gensSatSpecialFib -- computes generators of the saturated special fiber ring
****************************************************************************

Synopsis
========

  * Usage:
        gensSatSpecialFib(I, nsteps)
        gensSatSpecialFib(I)
  * Inputs:
      * I, an ideal (Macaulay2Doc), a homogeneous ideal generated
        by elements of the same degree
      * nteps, an integer (Macaulay2Doc), the number steps in the
        saturation of the powers of I. Optional.
  * Outputs:
      * a list (Macaulay2Doc), a list of generators of the
        saturated special fiber ring. In the case where we use the function as
        "gensSatSpecialFib(I, nsteps)", the answer is correct only if nsteps is
        big enough to attain all the generators.

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

This function computes generators of the saturated special fiber ring.

When we call "gensSatSpecialFib(I, nsteps)", the method iteratively computes
the graded pieces $$ [(I^1)^{sat}]_d, [(I^2)^{sat}]_{2d},  ......... ,
[(I^{nsteps})^{sat}]_{nsteps*d}, $$ where $(I^k)^{sat}$ denotes the saturation
of $I$ with respect to the irrelevant ideal.

When we call "gensSatSpecialFib(I)", the method first computes the module
$[H_m^1(Rees(I))]_0$ from which an upper bound nsteps. After that, it simply
calls "gensSatSpecialFib(I, nsteps)".

First, we compute some examples in the case of plane rational maps.

+--------------------------------------------------------------------+
|i1 : R = QQ[x,y,z]                                                  |
|                                                                    |
|o1 = R                                                              |
|                                                                    |
|o1 : PolynomialRing                                                 |
+--------------------------------------------------------------------+
|i2 : A = matrix{ {x, x^2 + y^2},                                    |
|                 {-y, y^2 + z*x},                                   |
|                 {0, x^2}                                           |
|               };                                                   |
|                                                                    |
|             3       2                                              |
|o2 : Matrix R  <--- R                                               |
+--------------------------------------------------------------------+
|i3 : I = minors(2, A) -- a birational map                           |
|                                                                    |
|             2       2    3    2    3    2                          |
|o3 = ideal (x y + x*y  + y  + x z, x , -x y)                        |
|                                                                    |
|o3 : Ideal of R                                                     |
+--------------------------------------------------------------------+
|i4 : gensSatSpecialFib I                                            |
|                                                                    |
|         2    3    2    2    3                                      |
|o4 = {x*y  + y  + x z, x y, x }                                     |
|                                                                    |
|o4 : List                                                           |
+--------------------------------------------------------------------+
|i5 : gensSatSpecialFib(I, 5)                                        |
|                                                                    |
|         2    3    2    2    3                                      |
|o5 = {x*y  + y  + x z, x y, x }                                     |
|                                                                    |
|o5 : List                                                           |
+--------------------------------------------------------------------+
|i6 : A = matrix{ {x^3, x^2 + y^2},                                  |
|                 {-y^3, y^2 + z*x},                                 |
|                 {0, x^2}                                           |
|               };                                                   |
|                                                                    |
|             3       2                                              |
|o6 : Matrix R  <--- R                                               |
+--------------------------------------------------------------------+
|i7 : I = minors(2, A) -- a non birational map                       |
|                                                                    |
|             3 2    2 3    5    4    5    2 3                       |
|o7 = ideal (x y  + x y  + y  + x z, x , -x y )                      |
|                                                                    |
|o7 : Ideal of R                                                     |
+--------------------------------------------------------------------+
|i8 : gensSatSpecialFib I                                            |
|                                                                    |
|       2 3   3 2    5    4    5   9    4 11    11 3     8 6    13 2 |
|o8 = {x y , x y  + y  + x z, x , x y, x y   - x  y z + x y z, x  y }|
|                                                                    |
|o8 : List                                                           |
+--------------------------------------------------------------------+
|i9 : gensSatSpecialFib(I, 5)                                        |
|                                                                    |
|       2 3   3 2    5    4    5   9    4 11    11 3     8 6    13 2 |
|o9 = {x y , x y  + y  + x z, x , x y, x y   - x  y z + x y z, x  y }|
|                                                                    |
|o9 : List                                                           |
+--------------------------------------------------------------------+

Next, we compute an example in the bigraded case.

+--------------------------------------------------------------+
|i10 : R = QQ[x,y,u,v, Degrees => {{1,0}, {1,0}, {0,1}, {0,1}}]|
|                                                              |
|o10 = R                                                       |
|                                                              |
|o10 : PolynomialRing                                          |
+--------------------------------------------------------------+
|i11 : I = ideal(x*u, y*v, x*v + y*u) -- a non birational map  |
|                                                              |
|o11 = ideal (x*u, y*v, y*u + x*v)                             |
|                                                              |
|o11 : Ideal of R                                              |
+--------------------------------------------------------------+
|i12 : gensSatSpecialFib(I, 5)                                 |
|                                                              |
|o12 = {x*u, x*v, y*u, y*v}                                    |
|                                                              |
|o12 : List                                                    |
+--------------------------------------------------------------+

Caveat
======

To call the method "gensSatSpecialFib(I)", the ideal $I$ should be in a single
graded polynomial ring.

Ways to use gensSatSpecialFib :
===============================

  * "gensSatSpecialFib(Ideal)"
  * "gensSatSpecialFib(Ideal,ZZ)"

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

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

Hm1Rees0 -- computes the module [Hm^1(Rees(I))]_0
*************************************************

Synopsis
========

  * Usage:
        Hm1Rees0(I)
  * Inputs:
      * I, an ideal (Macaulay2Doc), an ideal in a single graded
        polynomial ring
  * Outputs:
      * a module (Macaulay2Doc), the module $[H_m^1(Rees(I))]_0$

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

Let $R$ be the polynomial ring $R=k[x_0,...,x_n]$ and $\mathbf{m}$ be the
maximal irrelevant ideal  $\mathbf{m}=(x_0,...,x_n)$. Let $I \subset R$ be the
ideal $I=(f_0,...,f_m)$ where $deg(f_i)=d$. The Rees algebra $\mathcal{R}(I)$
is a bigraded algebra which can be given as a quotient of the polynomial ring
$\mathcal{A}=R[y_0,...,y_m]$. We denote by $S$ the polynomial ring
$S=k[y_0,...,y_m]$.

The local cohomology module $H_{m}^1(\mathcal{R}(I))$ with respect to the
maximal irrelevant ideal $\mathbf{m}$ is actually a bigraded
$\mathcal{A}$-module. We denote by $[H_m^1(Rees(I))]_0$ the restriction to
degree zero part in the $R$-grading, that is
$[H_m^1(Rees(I))]_0=[H_m^1(Rees(I))]_{(0,*)}$. So we have that
$[H_m^1(Rees(I))]_0$ is naturally a graded $S$-module.

+-----------------------------------------------------------------------+
|i1 : R = QQ[x,y,z]                                                     |
|                                                                       |
|o1 = R                                                                 |
|                                                                       |
|o1 : PolynomialRing                                                    |
+-----------------------------------------------------------------------+
|i2 : A = matrix{ {x, x^6 + y^6 + z*x^5},                               |
|                 {-y, y^6 + z*x^3*y^2},                                |
|                 {0, x^6 + x*y^4*z}                                    |
|               };                                                      |
|                                                                       |
|             3       2                                                 |
|o2 : Matrix R  <--- R                                                  |
+-----------------------------------------------------------------------+
|i3 : I = minors(2, A) -- a birational map                              |
|                                                                       |
|             6       6    7    5       4 2    7    2 4      6       5  |
|o3 = ideal (x y + x*y  + y  + x y*z + x y z, x  + x y z, - x y - x*y z)|
|                                                                       |
|o3 : Ideal of R                                                        |
+-----------------------------------------------------------------------+
|i4 : prune Hm1Rees0 I                                                  |
|                                                                       |
|o4 = 0                                                                 |
|                                                                       |
|o4 : QQ[Z ..Z ]-module                                                 |
|         1   3                                                         |
+-----------------------------------------------------------------------+
|i5 : A = matrix{ {x^2, x^2 + y^2},                                     |
|                 {-y^2, y^2 + z*x},                                    |
|                 {0, x^2}                                              |
|               };                                                      |
|                                                                       |
|             3       2                                                 |
|o5 : Matrix R  <--- R                                                  |
+-----------------------------------------------------------------------+
|i6 : I = minors(2, A) -- a non birational map                          |
|                                                                       |
|              2 2    4    3    4    2 2                                |
|o6 = ideal (2x y  + y  + x z, x , -x y )                               |
|                                                                       |
|o6 : Ideal of R                                                        |
+-----------------------------------------------------------------------+
|i7 : Hm1Rees0 I                                                        |
|                                                                       |
|                 1                                                     |
|o7 = (QQ[Z ..Z ])                                                      |
|          1   3                                                        |
|                                                                       |
|o7 : QQ[Z ..Z ]-module, free, degrees {2}                              |
|         1   3                                                         |
+-----------------------------------------------------------------------+

Caveat
======

To call the method "Hm1Rees0(I)", the ideal $I$ should be in a single graded
polynomial ring.

Ways to use Hm1Rees0 :
======================

  * "Hm1Rees0(Ideal)"

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

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

Hm1Rees0Strategy -- A strategy for degreeOfMap
**********************************************

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

When this strategy is used then the degree of the map is computed directly from
the multiplicity of $[H_m^1(Rees(I))]_0$. It contains an implementation of
Corollary 2.12 in Degree and birationality of multi-graded rational maps (see
https://arxiv.org/abs/1805.05180 ).

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

The object Hm1Rees0Strategy, is a symbol (Macaulay2Doc).

isBiratMap -- tests the birationality of a rational with the Jacobian dual criterion
************************************************************************************

Synopsis
========

  * Usage:
        isBiratMap(I)
  * Inputs:
      * I, an ideal (Macaulay2Doc), an ideal defining the map
  * Outputs:
      * a Boolean value (Macaulay2Doc), true/false if the
        rational map is birational/non birational

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

Let $R$ be the multi-homogeneous polynomial ring
$R=k[x_{1,0},x_{1,1},...,x_{1,r_1}, x_{2,0},x_{2,1},...,x_{2,r_2}, ......,
x_{m,0},x_{m,1},...,x_{m,r_m}]$ and $I$ be the multi-homogeneous ideal
$I=(f_0,f_1,...,f_s)$ where the polynomials $f_i$'s have the same multi-degree.
We compute the degree of the rational map $\mathbb{F}: \mathbb{P}^{r_1} \times
\mathbb{P}^{r_2} \times ... \times \mathbb{P}^{r_m}  \to \mathbb{P}^s$ defined
by $$ (x_{1,0} : ... : x_{1,r_1}; ...... ;x_{m,0} : ... : x_{m,r_m}) \to
(f_0(x_{1,0},...,x_{1,r_1}, ...... ,x_{m,0},...,x_{m,r_m}), ..... ,
f_0(x_{1,0},...,x_{1,r_1}, ...... ,x_{m,0},...,x_{m,r_m})). $$ This method
calls "jacobianDualRank" in order to obtain the full Jacobian dual rank  and
then it tests the birationality of $\mathbb{F}$ (see Theorem 4.4 in Degree and
birationality of multi-graded rational maps (see
https://arxiv.org/abs/1805.05180 )).

First, we compute some examples in the bigraded setting.

+-------------------------------------------------------------+
|i1 : R = QQ[x,y,u,v, Degrees => {{1,0}, {1,0}, {0,1}, {0,1}}]|
|                                                             |
|o1 = R                                                       |
|                                                             |
|o1 : PolynomialRing                                          |
+-------------------------------------------------------------+
|i2 : I = ideal(x*u, y*u, y*v) -- a birational map            |
|                                                             |
|o2 = ideal (x*u, y*u, y*v)                                   |
|                                                             |
|o2 : Ideal of R                                              |
+-------------------------------------------------------------+
|i3 : isBiratMap I                                            |
|                                                             |
|o3 = true                                                    |
+-------------------------------------------------------------+
|i4 : I = ideal(x*u, y*v, x*v + y*u) -- a non birational map  |
|                                                             |
|o4 = ideal (x*u, y*v, y*u + x*v)                             |
|                                                             |
|o4 : Ideal of R                                              |
+-------------------------------------------------------------+
|i5 : isBiratMap I                                            |
|                                                             |
|o5 = false                                                   |
+-------------------------------------------------------------+
|i6 : A = matrix{ {x^5*u,  x^2*v^2},                          |
|                 {y^5*v, x^2*u^2},                           |
|                 {0,     y^2*v^2}                            |
|               };                                            |
|                                                             |
|             3       2                                       |
|o6 : Matrix R  <--- R                                        |
+-------------------------------------------------------------+
|i7 : I = minors(2, A)  -- a non birational                   |
|                                                             |
|             7 3    2 5 3   5 2   2   7 3                    |
|o7 = ideal (x u  - x y v , x y u*v , y v )                   |
|                                                             |
|o7 : Ideal of R                                              |
+-------------------------------------------------------------+
|i8 : isBiratMap I                                            |
|                                                             |
|o8 = false                                                   |
+-------------------------------------------------------------+
|i9 : I = ideal(x*u^2, y*u^2, x*v^2) -- a non birational map  |
|                                                             |
|               2     2     2                                 |
|o9 = ideal (x*u , y*u , x*v )                                |
|                                                             |
|o9 : Ideal of R                                              |
+-------------------------------------------------------------+
|i10 : isBiratMap I                                           |
|                                                             |
|o10 = false                                                  |
+-------------------------------------------------------------+

Next, we test some rational maps over three projective spaces.

+-----------------------------------------------------------------------------+
|i11 : R = QQ[x,y,z,w]                                                        |
|                                                                             |
|o11 = R                                                                      |
|                                                                             |
|o11 : PolynomialRing                                                         |
+-----------------------------------------------------------------------------+
|i12 : A = matrix{ {x + y,  x, x},                                            |
|                  {3*z - 4*w, y, z},                                         |
|                  {w,  z, z + w},                                            |
|                  {y - z,  w, x + y}                                         |
|                };                                                           |
|                                                                             |
|              4       3                                                      |
|o12 : Matrix R  <--- R                                                       |
+-----------------------------------------------------------------------------+
|i13 : I = minors(3, A) -- a birational map                                   |
|                                                                             |
|                      2       2      2    2                 2   2       2    |
|o13 = ideal (x*y*z + y z - x*z  - y*z  + y w - 2x*z*w + 4x*w , x y + x*y  +  |
|      -----------------------------------------------------------------------|
|       3     2               2     2                                  2   2  |
|      y  - 3x z - x*y*z - x*z  + 4x w + 4x*y*w + 2x*z*w - y*z*w - 4x*w , x z |
|      -----------------------------------------------------------------------|
|                  2     2                        2   2        2      2    3  |
|      + 2x*y*z + y z - x w - 2x*z*w - y*z*w - y*w , y z + 3x*z  + y*z  + z  -|
|      -----------------------------------------------------------------------|
|                                  2        2     3                           |
|      x*y*w - 4x*z*w - 5y*z*w - 3z w + 2z*w  + 4w )                          |
|                                                                             |
|o13 : Ideal of R                                                             |
+-----------------------------------------------------------------------------+
|i14 : isBiratMap I                                                           |
|                                                                             |
|o14 = true                                                                   |
+-----------------------------------------------------------------------------+
|i15 : I = ideal(random(2, R), random(2, R), random(2, R), random(2, R)); -- a|
|                                                                             |
|o15 : Ideal of R                                                             |
|-----------------------------------------------------------------------------|
|non birational                                                               |
+-----------------------------------------------------------------------------+
|i16 : isBiratMap I                                                           |
|                                                                             |
|o16 = false                                                                  |
+-----------------------------------------------------------------------------+

Ways to use isBiratMap :
========================

  * "isBiratMap(Ideal)"

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

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

jacobianDualRank -- computes the full Jacobian dual rank
********************************************************

Synopsis
========

  * Usage:
        jacobianDualRank(I)
  * Inputs:
      * I, an ideal (Macaulay2Doc), an ideal defining the map
  * Outputs:
      * an integer (Macaulay2Doc), the total Jacobian dual rank

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

Let $R$ be the multi-homogeneous polynomial ring
$R=k[x_{1,0},x_{1,1},...,x_{1,r_1}, x_{2,0},x_{2,1},...,x_{2,r_2}, ......,
x_{m,0},x_{m,1},...,x_{m,r_m}]$ and $I$ be the multi-homogeneous ideal
$I=(f_0,f_1,...,f_s)$ where the polynomials $f_i$'s have the same multi-degree.
We compute the degree of the rational map $\mathbb{F}: \mathbb{P}^{r_1} \times
\mathbb{P}^{r_2} \times ... \times \mathbb{P}^{r_m}  \to \mathbb{P}^s$ defined
by $$ (x_{1,0} : ... : x_{1,r_1}; ...... ;x_{m,0} : ... : x_{m,r_m}) \to
(f_0(x_{1,0},...,x_{1,r_1}, ...... ,x_{m,0},...,x_{m,r_m}), ..... ,
f_0(x_{1,0},...,x_{1,r_1}, ...... ,x_{m,0},...,x_{m,r_m})). $$ This function
computes the full Jacobian dual rank of $\mathbb{F}$ (see Notation 4.2 in
Degree and birationality of multi-graded rational maps (see
https://arxiv.org/abs/1805.05180 )).

First, we compute some examples in the bigraded setting.

+-------------------------------------------------------------+
|i1 : R = QQ[x,y,u,v, Degrees => {{1,0}, {1,0}, {0,1}, {0,1}}]|
|                                                             |
|o1 = R                                                       |
|                                                             |
|o1 : PolynomialRing                                          |
+-------------------------------------------------------------+
|i2 : I = ideal(x*u, y*u, y*v) -- a birational map            |
|                                                             |
|o2 = ideal (x*u, y*u, y*v)                                   |
|                                                             |
|o2 : Ideal of R                                              |
+-------------------------------------------------------------+
|i3 : jacobianDualRank I                                      |
|                                                             |
|o3 = 2                                                       |
+-------------------------------------------------------------+
|i4 : I = ideal(x*u, y*v, x*v + y*u) -- a non birational map  |
|                                                             |
|o4 = ideal (x*u, y*v, y*u + x*v)                             |
|                                                             |
|o4 : Ideal of R                                              |
+-------------------------------------------------------------+
|i5 : jacobianDualRank I                                      |
|                                                             |
|o5 = 0                                                       |
+-------------------------------------------------------------+
|i6 : A = matrix{ {x^5*u,  x^2*v^2},                          |
|                 {y^5*v, x^2*u^2},                           |
|                 {0,     y^2*v^2}                            |
|               };                                            |
|                                                             |
|             3       2                                       |
|o6 : Matrix R  <--- R                                        |
+-------------------------------------------------------------+
|i7 : I = minors(2, A)  -- a non birational                   |
|                                                             |
|             7 3    2 5 3   5 2   2   7 3                    |
|o7 = ideal (x u  - x y v , x y u*v , y v )                   |
|                                                             |
|o7 : Ideal of R                                              |
+-------------------------------------------------------------+
|i8 : jacobianDualRank I                                      |
|                                                             |
|o8 = 0                                                       |
+-------------------------------------------------------------+
|i9 : I = ideal(x*u^2, y*u^2, x*v^2) -- non birational map    |
|                                                             |
|               2     2     2                                 |
|o9 = ideal (x*u , y*u , x*v )                                |
|                                                             |
|o9 : Ideal of R                                              |
+-------------------------------------------------------------+
|i10 : jacobianDualRank I                                     |
|                                                             |
|o10 = 1                                                      |
+-------------------------------------------------------------+

Next, we test some rational maps over three projective spaces.

+-----------------------------------------------------------------------------+
|i11 : R = QQ[x,y,z,w]                                                        |
|                                                                             |
|o11 = R                                                                      |
|                                                                             |
|o11 : PolynomialRing                                                         |
+-----------------------------------------------------------------------------+
|i12 : A = matrix{ {x + y,  x, x},                                            |
|                  {3*z - 4*w, y, z},                                         |
|                  {w,  z, z + w},                                            |
|                  {y - z,  w, x + y}                                         |
|                };                                                           |
|                                                                             |
|              4       3                                                      |
|o12 : Matrix R  <--- R                                                       |
+-----------------------------------------------------------------------------+
|i13 : I = minors(3, A) -- a birational map                                   |
|                                                                             |
|                      2       2      2    2                 2   2       2    |
|o13 = ideal (x*y*z + y z - x*z  - y*z  + y w - 2x*z*w + 4x*w , x y + x*y  +  |
|      -----------------------------------------------------------------------|
|       3     2               2     2                                  2   2  |
|      y  - 3x z - x*y*z - x*z  + 4x w + 4x*y*w + 2x*z*w - y*z*w - 4x*w , x z |
|      -----------------------------------------------------------------------|
|                  2     2                        2   2        2      2    3  |
|      + 2x*y*z + y z - x w - 2x*z*w - y*z*w - y*w , y z + 3x*z  + y*z  + z  -|
|      -----------------------------------------------------------------------|
|                                  2        2     3                           |
|      x*y*w - 4x*z*w - 5y*z*w - 3z w + 2z*w  + 4w )                          |
|                                                                             |
|o13 : Ideal of R                                                             |
+-----------------------------------------------------------------------------+
|i14 : jacobianDualRank I                                                     |
|                                                                             |
|o14 = 3                                                                      |
+-----------------------------------------------------------------------------+
|i15 : I = ideal(random(2, R), random(2, R), random(2, R), random(2, R)); -- a|
|                                                                             |
|o15 : Ideal of R                                                             |
|-----------------------------------------------------------------------------|
|non birational                                                               |
+-----------------------------------------------------------------------------+
|i16 : jacobianDualRank I                                                     |
|                                                                             |
|o16 = 0                                                                      |
+-----------------------------------------------------------------------------+

Ways to use jacobianDualRank :
==============================

  * "jacobianDualRank(Ideal)"

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

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

partialJDRs -- computes the partial Jacobian dual ranks
*******************************************************

Synopsis
========

  * Usage:
        partialJDRs(I)
  * Inputs:
      * I, an ideal (Macaulay2Doc), an ideal defining the map
  * Outputs:
      * a list (Macaulay2Doc), the partial Jacobian dual ranks

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

Let $R$ be the multi-homogeneous polynomial ring
$R=k[x_{1,0},x_{1,1},...,x_{1,r_1}, x_{2,0},x_{2,1},...,x_{2,r_2}, ......,
x_{m,0},x_{m,1},...,x_{m,r_m}]$ and $I$ be the multi-homogeneous ideal
$I=(f_0,f_1,...,f_s)$ where the polynomials $f_i$'s have the same multi-degree.
We compute the degree of the rational map $\mathbb{F}: \mathbb{P}^{r_1} \times
\mathbb{P}^{r_2} \times ... \times \mathbb{P}^{r_m}  \to \mathbb{P}^s$ defined
by $$ (x_{1,0} : ... : x_{1,r_1}; ...... ;x_{m,0} : ... : x_{m,r_m}) \to
(f_0(x_{1,0},...,x_{1,r_1}, ...... ,x_{m,0},...,x_{m,r_m}), ..... ,
f_0(x_{1,0},...,x_{1,r_1}, ...... ,x_{m,0},...,x_{m,r_m})). $$ This function
computes the partial Jacobian dual ranks of $\mathbb{F}$ (see Notation 4.2 in
Degree and birationality of multi-graded rational maps (see
https://arxiv.org/abs/1805.05180 )).

First, we compute some examples in the bigraded setting.

+-------------------------------------------------------------+
|i1 : R = QQ[x,y,u,v, Degrees => {{1,0}, {1,0}, {0,1}, {0,1}}]|
|                                                             |
|o1 = R                                                       |
|                                                             |
|o1 : PolynomialRing                                          |
+-------------------------------------------------------------+
|i2 : I = ideal(x*u, y*u, y*v) -- a birational map            |
|                                                             |
|o2 = ideal (x*u, y*u, y*v)                                   |
|                                                             |
|o2 : Ideal of R                                              |
+-------------------------------------------------------------+
|i3 : partialJDRs I                                           |
|                                                             |
|o3 = {1, 1}                                                  |
|                                                             |
|o3 : List                                                    |
+-------------------------------------------------------------+
|i4 : I = ideal(x*u, y*v, x*v + y*u) -- a non birational map  |
|                                                             |
|o4 = ideal (x*u, y*v, y*u + x*v)                             |
|                                                             |
|o4 : Ideal of R                                              |
+-------------------------------------------------------------+
|i5 : partialJDRs I                                           |
|                                                             |
|o5 = {0, 0}                                                  |
|                                                             |
|o5 : List                                                    |
+-------------------------------------------------------------+
|i6 : A = matrix{ {x^5*u,  x^2*v^2},                          |
|                 {y^5*v, x^2*u^2},                           |
|                 {0,     y^2*v^2}                            |
|               };                                            |
|                                                             |
|             3       2                                       |
|o6 : Matrix R  <--- R                                        |
+-------------------------------------------------------------+
|i7 : I = minors(2, A)  -- a non birational                   |
|                                                             |
|             7 3    2 5 3   5 2   2   7 3                    |
|o7 = ideal (x u  - x y v , x y u*v , y v )                   |
|                                                             |
|o7 : Ideal of R                                              |
+-------------------------------------------------------------+
|i8 : partialJDRs I                                           |
|                                                             |
|o8 = {0, 0}                                                  |
|                                                             |
|o8 : List                                                    |
+-------------------------------------------------------------+
|i9 : I = ideal(x*u^2, y*u^2, x*v^2) -- non birational map    |
|                                                             |
|               2     2     2                                 |
|o9 = ideal (x*u , y*u , x*v )                                |
|                                                             |
|o9 : Ideal of R                                              |
+-------------------------------------------------------------+
|i10 : partialJDRs I                                          |
|                                                             |
|o10 = {1, 0}                                                 |
|                                                             |
|o10 : List                                                   |
+-------------------------------------------------------------+

Next, we test some rational maps over three projective spaces.

+-----------------------------------------------------------------------------+
|i11 : R = QQ[x,y,z,w]                                                        |
|                                                                             |
|o11 = R                                                                      |
|                                                                             |
|o11 : PolynomialRing                                                         |
+-----------------------------------------------------------------------------+
|i12 : A = matrix{ {x + y,  x, x},                                            |
|                  {3*z - 4*w, y, z},                                         |
|                  {w,  z, z + w},                                            |
|                  {y - z,  w, x + y}                                         |
|                };                                                           |
|                                                                             |
|              4       3                                                      |
|o12 : Matrix R  <--- R                                                       |
+-----------------------------------------------------------------------------+
|i13 : I = minors(3, A) -- a birational map                                   |
|                                                                             |
|                      2       2      2    2                 2   2       2    |
|o13 = ideal (x*y*z + y z - x*z  - y*z  + y w - 2x*z*w + 4x*w , x y + x*y  +  |
|      -----------------------------------------------------------------------|
|       3     2               2     2                                  2   2  |
|      y  - 3x z - x*y*z - x*z  + 4x w + 4x*y*w + 2x*z*w - y*z*w - 4x*w , x z |
|      -----------------------------------------------------------------------|
|                  2     2                        2   2        2      2    3  |
|      + 2x*y*z + y z - x w - 2x*z*w - y*z*w - y*w , y z + 3x*z  + y*z  + z  -|
|      -----------------------------------------------------------------------|
|                                  2        2     3                           |
|      x*y*w - 4x*z*w - 5y*z*w - 3z w + 2z*w  + 4w )                          |
|                                                                             |
|o13 : Ideal of R                                                             |
+-----------------------------------------------------------------------------+
|i14 : partialJDRs I                                                          |
|                                                                             |
|o14 = {3}                                                                    |
|                                                                             |
|o14 : List                                                                   |
+-----------------------------------------------------------------------------+
|i15 : I = ideal(random(2, R), random(2, R), random(2, R), random(2, R)); -- a|
|                                                                             |
|o15 : Ideal of R                                                             |
|-----------------------------------------------------------------------------|
|non birational                                                               |
+-----------------------------------------------------------------------------+
|i16 : partialJDRs I                                                          |
|                                                                             |
|o16 = {0}                                                                    |
|                                                                             |
|o16 : List                                                                   |
+-----------------------------------------------------------------------------+

Ways to use partialJDRs :
=========================

  * "partialJDRs(Ideal)"

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

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

satSpecialFiber
***************

Ways to use satSpecialFiber :
=============================

  * satSpecialFiber(Ideal,ZZ) (missing documentation)
  * "satSpecialFiber(Ideal)" -- see satSpecialFiberIdeal,
    -- computes the defining equations of the saturated
    special fiber ring

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

The object satSpecialFiber (missing documentation) is a method function (Macaulay2Doc).

satSpecialFiberIdeal -- computes the defining equations of the saturated special fiber ring
*******************************************************************************************

Synopsis
========

  * Usage:
        satSpecialFiberIdeal(I, nsteps)
        satSpecialFiberIdeal(I)
  * Inputs:
      * I, an ideal (Macaulay2Doc), a homogeneous ideal generated
        by elements of the same degree
      * nteps, an integer (Macaulay2Doc), the number steps in the
        saturation of the powers of I. Optional.
  * Outputs:
      * an ideal (Macaulay2Doc), the defining equations of the
        saturated special fiber ring

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

The purpose of this function is to compute the defining equations of the
special fiber ring.

Suppose that $\{g_1,...,g_m\}$ is the set of generators of the saturated
special fiber ring (which can be obtained from  "gensSatSpecialFib"). This
function returns the kernel of the map $k[z_1, ... ,z_m] \to k[g_1, ... ,g_m]$
which is given by $$ z_i \to g_i. $$

First, we compute some examples of plane rational maps.

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x,y,z]                                                           |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : A = matrix{ {x, x^5 + y^5},                                             |
|                 {-y, y^5 + z*x^2*y^2},                                      |
|                 {0, x^5}                                                    |
|               };                                                            |
|                                                                             |
|             3       2                                                       |
|o2 : Matrix R  <--- R                                                        |
+-----------------------------------------------------------------------------+
|i3 : I = minors(2, A) -- a birational map                                    |
|                                                                             |
|             5       5    6    3 2    6    5                                 |
|o3 = ideal (x y + x*y  + y  + x y z, x , -x y)                               |
|                                                                             |
|o3 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i4 : satSpecialFiberIdeal I                                                  |
|                                                                             |
|o4 = ideal ()                                                                |
|                                                                             |
|o4 : Ideal of QQ[Z ..Z ]                                                     |
|                  1   3                                                      |
+-----------------------------------------------------------------------------+
|i5 : A = matrix{ {x^3, x^2 + y^2},                                           |
|                 {-y^3, y^2 + z*x},                                          |
|                 {0, x^2}                                                    |
|               };                                                            |
|                                                                             |
|             3       2                                                       |
|o5 : Matrix R  <--- R                                                        |
+-----------------------------------------------------------------------------+
|i6 : I = minors(2, A) -- a non birational map                                |
|                                                                             |
|             3 2    2 3    5    4    5    2 3                                |
|o6 = ideal (x y  + x y  + y  + x z, x , -x y )                               |
|                                                                             |
|o6 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i7 : satSpecialFiberIdeal I                                                  |
|                                                                             |
|             2          2            2                   4          2 3      |
|o7 = ideal (Z  - Z Z , Z Z Z  - Z Z Z  - Z Z  + Z Z , Z Z  - Z Z , Z Z  +    |
|             4    3 6   1 2 3    1 2 3    3 5    1 6   1 3    4 6   1 3      |
|     ------------------------------------------------------------------------|
|      2                           3      2   2 2      2                      |
|     Z Z Z  - Z Z Z Z  - Z Z , Z Z Z  - Z , Z Z Z  + Z Z Z  - Z Z Z Z  -     |
|      1 2 4    1 2 3 4    4 5   1 3 4    6   1 3 4    1 2 6    1 2 3 6       |
|     ------------------------------------------------------------------------|
|            2 2        2        3                 2              4 2      2 3|
|     Z Z , Z Z Z  - Z Z Z Z  + Z Z  - Z Z Z  - Z Z Z  + Z Z Z , Z Z  - Z Z Z |
|      5 6   1 2 4    1 2 3 4    3 5    2 4 5    1 3 6    2 4 6   1 2    1 2 3|
|     ------------------------------------------------------------------------|
|        3         2          2      2     2                  2        2 2    |
|     - Z Z Z  - 2Z Z Z  - Z Z Z  + Z  + 2Z Z Z  + Z Z Z Z , Z Z Z  + Z Z Z  -|
|        1 3 4     1 2 5    2 3 5    5     1 2 6    1 2 3 6   3 4 5    1 2 6  |
|     ------------------------------------------------------------------------|
|        2                              2   4        3                        |
|     Z Z Z Z  - Z Z Z Z  - Z Z Z  + Z Z , Z Z  - Z Z Z  - Z Z Z Z  +         |
|      1 2 3 6    1 3 4 6    2 5 6    2 6   3 5    1 3 6    1 2 4 6           |
|     ------------------------------------------------------------------------|
|     Z Z Z Z )                                                               |
|      2 3 4 6                                                                |
|                                                                             |
|o7 : Ideal of QQ[Z ..Z ]                                                     |
|                  1   6                                                      |
+-----------------------------------------------------------------------------+

Next, we test some bigraded rational maps.

+-------------------------------------------------------------+
|i8 : R = QQ[x,y,u,v, Degrees => {{1,0}, {1,0}, {0,1}, {0,1}}]|
|                                                             |
|o8 = R                                                       |
|                                                             |
|o8 : PolynomialRing                                          |
+-------------------------------------------------------------+
|i9 : I = ideal(x*u, y*u, y*v) -- a birational map            |
|                                                             |
|o9 = ideal (x*u, y*u, y*v)                                   |
|                                                             |
|o9 : Ideal of R                                              |
+-------------------------------------------------------------+
|i10 : satSpecialFiberIdeal(I, 5)                             |
|                                                             |
|o10 = ideal ()                                               |
|                                                             |
|o10 : Ideal of QQ[Z ..Z ]                                    |
|                   1   3                                     |
+-------------------------------------------------------------+
|i11 : I = ideal(x*u, y*v, x*v + y*u) -- a non birational map |
|                                                             |
|o11 = ideal (x*u, y*v, y*u + x*v)                            |
|                                                             |
|o11 : Ideal of R                                             |
+-------------------------------------------------------------+
|i12 : satSpecialFiberIdeal(I, 5)                             |
|                                                             |
|o12 = ideal(Z Z  - Z Z )                                     |
|             2 3    1 4                                      |
|                                                             |
|o12 : Ideal of QQ[Z ..Z ]                                    |
|                   1   4                                     |
+-------------------------------------------------------------+

Caveat
======

To call the method "satSpecialFiberIdeal(I)", the ideal $I$ should be in a
single graded polynomial ring.

The answer of "satSpecialFiberIdeal(I, nsteps)" is correct only if nsteps is
big enough to attain all the generators of the saturated special fiber ring.

Ways to use satSpecialFiberIdeal :
==================================

  * "satSpecialFiberIdeal(Ideal,ZZ)"
  * satSpecialFiberIdeal(Ideal) (missing documentation)

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

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

SatSpecialFibStrategy -- A strategy for degreeOfMap
***************************************************

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

When this strategy is used then the degree of the map is computed directly from
the multiplicity of the saturated special fiber ring of $I$. The degree of the
rational map then can be obtained from Theorem 2.4 in Degree and birationality
of multi-graded rational maps (see https://arxiv.org/abs/1805.05180 ).

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

The object SatSpecialFibStrategy, is a
symbol (Macaulay2Doc).

upperBoundDegreeSingleGraded -- computes an upper bound for the degree of a rational map
****************************************************************************************

Synopsis
========

  * Usage:
        upperBoundDegreeSingleGraded(I)
  * Inputs:
      * I, an ideal (Macaulay2Doc), an ideal defining the map
  * Outputs:
      * an integer (Macaulay2Doc), an upper bound for the degree of
        the corresponding rational map

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

Let $R$ be the polynomial ring $R=k[x_0,...,x_r]$ and $I$ be the homogeneous
ideal $I=(f_0,f_1,...,f_s)$ where $deg(f_i)=d$. We compute the degree of the
rational map $\mathbb{F}: \mathbb{P}^r \to \mathbb{P}^s$ defined by $$ (x_0:
... :x_r) \to (f_0(x_0,...,x_r), f_1(x_0,...,x_r), ..... , f_s(x_0,...,x_r)).
$$ Using certain Hilbert functions the degree of the map is bounded (see
Theorem 3.22 in Degree and birationality of multi-graded rational maps (see
https://arxiv.org/abs/1805.05180 )).

The following example is a rational map without base points:

+---------------------------------------------------------+
|i1 : R = QQ[x,y,z]                                       |
|                                                         |
|o1 = R                                                   |
|                                                         |
|o1 : PolynomialRing                                      |
+---------------------------------------------------------+
|i2 : I = ideal(random(4, R), random(4, R), random(4, R));|
|                                                         |
|o2 : Ideal of R                                          |
+---------------------------------------------------------+
|i3 : betti res I                                         |
|                                                         |
|            0 1 2 3                                      |
|o3 = total: 1 3 3 1                                      |
|         0: 1 . . .                                      |
|         1: . . . .                                      |
|         2: . . . .                                      |
|         3: . 3 . .                                      |
|         4: . . . .                                      |
|         5: . . . .                                      |
|         6: . . 3 .                                      |
|         7: . . . .                                      |
|         8: . . . .                                      |
|         9: . . . 1                                      |
|                                                         |
|o3 : BettiTally                                          |
+---------------------------------------------------------+
|i4 : degreeOfMap I                                       |
|                                                         |
|o4 = 16                                                  |
+---------------------------------------------------------+
|i5 : upperBoundDegreeSingleGraded I                      |
|                                                         |
|o5 = 16                                                  |
+---------------------------------------------------------+

In the following examples we play with the relations of the Hilbert-Burch
presentation and the degree of $\mathbb{F}$ (see Proposition 5.2 and Theorem
5.12):

+-----------------------------------------------+
|i6 : A = matrix{ {x, x^2 + y^2},               |
|                 {-y, y^2 + z*x},              |
|                 {0, x^2}                      |
|               };                              |
|                                               |
|             3       2                         |
|o6 : Matrix R  <--- R                          |
+-----------------------------------------------+
|i7 : I = minors(2, A) -- a birational map      |
|                                               |
|             2       2    3    2    3    2     |
|o7 = ideal (x y + x*y  + y  + x z, x , -x y)   |
|                                               |
|o7 : Ideal of R                                |
+-----------------------------------------------+
|i8 : degreeOfMap I                             |
|                                               |
|o8 = 1                                         |
+-----------------------------------------------+
|i9 : upperBoundDegreeSingleGraded I            |
|                                               |
|o9 = 2                                         |
+-----------------------------------------------+
|i10 : A = matrix{ {x^2, x^2 + y^2},            |
|                  {-y^2, y^2 + z*x},           |
|                  {0, x^2}                     |
|                };                             |
|                                               |
|              3       2                        |
|o10 : Matrix R  <--- R                         |
+-----------------------------------------------+
|i11 : I = minors(2, A) -- a non birational map |
|                                               |
|               2 2    4    3    4    2 2       |
|o11 = ideal (2x y  + y  + x z, x , -x y )      |
|                                               |
|o11 : Ideal of R                               |
+-----------------------------------------------+
|i12 : degreeOfMap I                            |
|                                               |
|o12 = 2                                        |
+-----------------------------------------------+
|i13 : upperBoundDegreeSingleGraded I           |
|                                               |
|o13 = 4                                        |
+-----------------------------------------------+
|i14 : A = matrix{ {x^3, x^2 + y^2},            |
|                  {-y^3, y^2 + z*x},           |
|                  {0, x^2}                     |
|                };                             |
|                                               |
|              3       2                        |
|o14 : Matrix R  <--- R                         |
+-----------------------------------------------+
|i15 : I = minors(2, A) -- a non birational map |
|                                               |
|              3 2    2 3    5    4    5    2 3 |
|o15 = ideal (x y  + x y  + y  + x z, x , -x y )|
|                                               |
|o15 : Ideal of R                               |
+-----------------------------------------------+
|i16 : degreeOfMap I                            |
|                                               |
|o16 = 3                                        |
+-----------------------------------------------+
|i17 : upperBoundDegreeSingleGraded I           |
|                                               |
|o17 = 7                                        |
+-----------------------------------------------+

Caveat
======

To call the method "degreeOfMap(I)", the ideal $I$ should be in a single graded
polynomial ring and dim(R/I) <= 1.

Ways to use upperBoundDegreeSingleGraded :
==========================================

  * "upperBoundDegreeSingleGraded(Ideal)"

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

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